anton.galiglobal.com
Firefox WebExtension (Desktop and Mobile) that lets you share the current tab to Margit.at, frontpage.fyi, etc. with minimal effort.
chore: update docs and repo metadata
- rewrite README and add CONTRIBUTING guide for the new workflow
- delete devcontainer setup and AGENTS notes no longer needed
- point the Margin generator ID at the new GitHub repository
-24
.devcontainer/Dockerfile
-24
.devcontainer/Dockerfile
···
1
-
FROM fedora:40
2
-
3
-
# Install system packages required for Rust builds and Node-based Codex CLI
4
-
RUN dnf install -y \
5
-
curl \
6
-
ca-certificates \
7
-
make \
8
-
gcc \
9
-
pkg-config \
10
-
openssl-devel \
11
-
git \
12
-
nodejs \
13
-
npm \
14
-
&& dnf clean all
15
-
16
-
# Install OpenAI Codex CLI from npm registry
17
-
RUN npm install -g @openai/codex
18
-
19
-
# Create a non-root user to run the CLI by default
20
-
RUN useradd --create-home --shell /bin/bash app
21
-
USER app
22
-
WORKDIR /home/app
23
-
24
-
CMD ["codex", "--help"]
-16
.devcontainer/devcontainer.json
-16
.devcontainer/devcontainer.json
···
1
-
{
2
-
"name": "Frontpage Firefox Plugin",
3
-
"build": {
4
-
"dockerfile": "Dockerfile",
5
-
"context": ".."
6
-
},
7
-
"remoteUser": "app",
8
-
"customizations": {
9
-
"vscode": {
10
-
"extensions": [
11
-
"ms-vsliveshare.vsliveshare",
12
-
"dbaeumer.vscode-eslint"
13
-
]
14
-
}
15
-
}
16
-
}
-6
AGENTS.md
-6
AGENTS.md
···
1
-
# Agent Notes
2
-
3
-
- Relocated the project Dockerfile into `.devcontainer/Dockerfile` so GitHub Codespaces can pick it up automatically.
4
-
- Added `.devcontainer/devcontainer.json` pointing to the Dockerfile, sets remote user `app`, and recommends necessary VS Code extensions.
5
-
- Dropped the Rust Analyzer recommendation per project requirements; keep the list lean to essentials.
6
-
- Remember to mirror any environment dependency updates in both the Dockerfile and devcontainer definition.
+65
CONTRIBUTING.md
+65
CONTRIBUTING.md
···
1
+
## Contributing to ATProto Social
2
+
3
+
### Development install (temporary)
4
+
5
+
1. Open `about:debugging#/runtime/this-firefox`.
6
+
2. Click **Load Temporary Add-on…** and choose `manifest.json` inside the
7
+
`extension/` directory.
8
+
3. Pin the "ATProto Social" toolbar button if you want quick access.
9
+
10
+
> This method is ideal while iterating; Firefox forgets the add-on on restart.
11
+
12
+
### Development tips
13
+
14
+
- Inspect background/service-worker logs from `about:debugging` → **Inspect**.
15
+
- The UI scripts (`popup.js` and `options.js`) log to the DevTools console
16
+
attached to their respective documents.
17
+
- When packaging for distribution, zip the contents of the `extension/`
18
+
directory (see workflow below).
19
+
- Licensed under the [Apache License 2.0](./LICENSE).
20
+
21
+
### Implementation notes
22
+
23
+
- The background worker discovers the user's PDS by resolving the handle
24
+
(`com.atproto.identity.resolveHandle` + PLC lookup).
25
+
- Sessions are refreshed automatically via `com.atproto.server.refreshSession`
26
+
when the access JWT expires.
27
+
- All data stays in `browser.storage.local`; nothing is transmitted to
28
+
third-party services beyond the ATProto endpoints.
29
+
- Margin records use the `at.margin.annotation` and `at.margin.highlight`
30
+
lexicons with a `TextQuoteSelector` for text targeting.
31
+
- Maximum lengths follow the current Frontpage limits (120 characters for the
32
+
title, 2048 for URLs).
33
+
34
+
### Self-distribution pipeline
35
+
36
+
This repository includes `.github/workflows/package-extension.yml` which builds
37
+
(and optionally signs) the add-on using
38
+
[`web-ext`](https://extensionworkshop.com/documentation/develop/web-ext-command-reference/).
39
+
40
+
1. Configure `AMO_JWT_ISSUER` and `AMO_JWT_SECRET` repository secrets with your
41
+
AMO API credentials if you want automatic signing. Without the secrets, the
42
+
workflow still produces an unsigned ZIP you can download.
43
+
2. Trigger the workflow manually (`Actions` → **package-extension** →
44
+
**Run workflow**).
45
+
3. Download the artifacts:
46
+
- `frontpage-extension-unsigned` contains the ZIP that `web-ext build`
47
+
generates.
48
+
- `frontpage-extension-signed` (only when secrets are present) contains the
49
+
signed `.xpi` from AMO for self-hosting.
50
+
4. Each run also publishes a GitHub Release (tagged `v<version>-<run-id>`) that
51
+
ships the same ZIP/XPI assets, so you can share a permanent download link.
52
+
- Mozilla requires every signed upload to have a unique version number. Bump
53
+
`version` in `extension/manifest.json` before rerunning the workflow if you
54
+
need a new signed package.
55
+
56
+
These artifacts can be hosted directly for self-distribution as described in the
57
+
[Mozilla documentation](https://extensionworkshop.com/documentation/publish/self-distribution/).
58
+
59
+
### Tangled mirror
60
+
61
+
The `mirror-to-tangled.yml` workflow pushes every commit on `main` to Tangled, a
62
+
federated Git hosting platform built on ATProto. Browse the mirror at
63
+
<https://tangled.org/anton.galiglobal.com/frontpage_firefox_plugin>. Add a
64
+
deploy key with write access as the `TANGLED_DEPLOY_KEY` repository secret so
65
+
the mirror stays up to date.
+62
-62
README.md
+62
-62
README.md
···
1
1
## ATProto Social — Firefox extension
2
2
3
-
A Firefox WebExtension for publishing to ATProto-based social platforms directly from your browser.
3
+
A Firefox WebExtension for publishing to ATProto-based social platforms directly
4
+
from your browser.
4
5
5
-
> ℹ️ This repository is hosted on [tangled](https://tangled.org/anton.galiglobal.com/frontpage_firefox_plugin) (PRs, issues) and [GitHub](https://github.com/antonmry/frontpage_firefox_plugin) (CI/CD, releases).
6
+
> ℹ️ This repository is hosted on
7
+
> [tangled](https://tangled.org/anton.galiglobal.com/frontpage_firefox_plugin)
8
+
> (PRs, issues) and [GitHub](https://github.com/antonmry/atproto_firefox_plugin)
9
+
> (CI/CD, releases).
6
10
7
11
### Features
8
12
9
-
- **Margin tab** — select text on any page and publish it as a highlight or annotation to [margin.at](https://margin.at):
13
+
- **Margin tab** — select text on any page and publish it as a highlight or
14
+
annotation to [margin.at](https://margin.at):
10
15
- No comment → creates an `at.margin.highlight` record.
11
-
- With comment → creates an `at.margin.annotation` record (`motivation: commenting`).
12
-
- Uses the W3C `TextQuoteSelector` (exact text + surrounding context) for precise targeting.
13
-
- **Frontpage tab** — share the current tab to [frontpage.fyi](https://frontpage.fyi) by creating a `fyi.frontpage.feed.post` record on your ATProto account.
16
+
- With comment → creates an `at.margin.annotation` record
17
+
(`motivation: commenting`).
18
+
- Uses the W3C `TextQuoteSelector` (exact text + surrounding context) for
19
+
precise targeting.
20
+
- **Frontpage tab** — share the current tab to
21
+
[frontpage.fyi](https://frontpage.fyi) by creating a `fyi.frontpage.feed.post`
22
+
record on your ATProto account.
14
23
- Auto-fills the active tab's title and URL.
15
24
- Title length indicator (120 character limit).
16
-
- Background service worker handles ATProto login, token refresh, and record creation for both services.
25
+
- Background service worker handles ATProto login, token refresh, and record
26
+
creation for both services.
17
27
- Options page for storing your handle, app password, and optional PDS override.
18
28
19
29
### Prerequisites
20
30
21
31
- An ATProto account (Bluesky or self-hosted PDS).
22
-
- An app password for that account (create one at <https://bsky.app/settings/app-passwords> or via your own PDS).
32
+
- An app password for that account (create one at
33
+
<https://bsky.app/settings/app-passwords> or via your own PDS).
23
34
24
-
### Install a packaged build
35
+
### Install on Firefox (desktop)
25
36
26
-
1. Visit the [Releases](https://github.com/antonmry/frontpage_firefox_plugin/releases) page and download the latest `frontpage-submitter-<version>.xpi` (signed) or `.zip` (unsigned) asset.
27
-
2. In Firefox, open `about:addons`, click the gear icon, and choose **Install Add-on From File…**.
28
-
3. Select the downloaded `.xpi` (preferred) or `.zip` to complete the installation and approve the permissions prompt.
37
+
1. Visit the
38
+
[Releases](https://github.com/antonmry/atproto_firefox_plugin/releases) page
39
+
and download the latest `frontpage-submitter-<version>.xpi` (signed) or
40
+
`.zip` (unsigned) asset.
41
+
2. In Firefox, open `about:addons`, click the gear icon, and choose
42
+
**Install Add-on From File…**.
43
+
3. Select the downloaded `.xpi` (preferred) or `.zip` to complete the
44
+
installation and approve the permissions prompt.
45
+
46
+
### Install on Firefox for Android
47
+
48
+
Firefox for Android requires enabling the **"Install from file"** option first:
49
+
50
+
1. Open Firefox for Android → tap the three-dot menu → **Settings** →
51
+
**About Firefox**.
52
+
2. Tap the Firefox logo **5 times** to unlock debug options.
53
+
3. Go back to **Settings** — a new **Install extension from file** option now
54
+
appears at the bottom.
55
+
4. Download the signed `.xpi` from the
56
+
[Releases](https://github.com/antonmry/atproto_firefox_plugin/releases) page
57
+
to your device.
58
+
5. Tap **Install extension from file**, select the downloaded `.xpi`, and
59
+
approve the permissions prompt.
60
+
61
+
> The extension must be signed by Mozilla. Unsigned `.xpi` files are rejected on
62
+
> Android. Use the signed asset from the releases page.
29
63
30
64
### Configure credentials
31
65
32
-
1. Open the add-on pop-up and press the gear icon (or use `about:addons` → **Preferences**).
33
-
2. Enter your handle and app password. Supply a PDS URL only if you run a custom server.
34
-
3. Click **Save credentials**. A success message confirms that the session tokens are stored locally.
35
-
4. Use **Log out** at any time to remove stored tokens (you can also revoke the app password server-side).
66
+
1. Open the add-on pop-up and press the gear icon (or use `about:addons` →
67
+
**Preferences**).
68
+
2. Enter your handle and app password. Supply a PDS URL only if you run a custom
69
+
server.
70
+
3. Click **Save credentials**. A success message confirms that the session
71
+
tokens are stored locally.
72
+
4. Use **Log out** at any time to remove stored tokens (you can also revoke the
73
+
app password server-side).
36
74
37
75
### Publish a highlight or annotation (Margin)
38
76
39
77
1. Select text on any webpage.
40
-
2. Open the ATProto Social pop-up — the **Margin** tab opens by default with the selected text pre-filled.
78
+
2. Open the ATProto Social pop-up — the **Margin** tab opens by default with the
79
+
selected text pre-filled.
41
80
3. Optionally add a comment (turns a highlight into an annotation).
42
81
4. Click **Highlight on Margin** or **Annotate on Margin**.
43
82
44
83
### Submit a link (Frontpage)
45
84
46
85
1. Browse to the page you want to share.
47
-
2. Open the ATProto Social pop-up and switch to the **Frontpage** tab; the title and URL are pre-filled.
86
+
2. Open the ATProto Social pop-up and switch to the **Frontpage** tab; the title
87
+
and URL are pre-filled.
48
88
3. Adjust the text if necessary and click **Post to Frontpage**.
49
-
4. On success, the pop-up reports the record URI returned by `com.atproto.repo.createRecord`.
50
-
51
-
### Implementation notes
52
-
53
-
- The background worker discovers the user's PDS by resolving the handle (`com.atproto.identity.resolveHandle` + PLC lookup).
54
-
- Sessions are refreshed automatically via `com.atproto.server.refreshSession` when the access JWT expires.
55
-
- All data stays in `browser.storage.local`; nothing is transmitted to third-party services beyond the ATProto endpoints.
56
-
- Margin records use the `at.margin.annotation` and `at.margin.highlight` lexicons with a `TextQuoteSelector` for text targeting.
57
-
- Maximum lengths follow the current Frontpage limits (120 characters for the title, 2048 for URLs).
58
-
59
-
### Development tips
60
-
61
-
- Inspect background/service-worker logs from `about:debugging` → **Inspect**.
62
-
- The UI scripts (`popup.js` and `options.js`) log to the DevTools console attached to their respective documents.
63
-
- When packaging for distribution, zip the contents of the `extension/` directory (see workflow below).
64
-
- Licensed under the [Apache License 2.0](./LICENSE).
65
-
66
-
### Development install (temporary)
67
-
68
-
1. Open `about:debugging#/runtime/this-firefox`.
69
-
2. Click **Load Temporary Add-on…** and choose `manifest.json` inside the `extension/` directory.
70
-
3. Pin the "ATProto Social" toolbar button if you want quick access.
71
-
72
-
> This method is ideal while iterating; Firefox forgets the add-on on restart.
73
-
74
-
### Self-distribution pipeline
75
-
76
-
This repository includes `.github/workflows/package-extension.yml` which builds (and optionally signs) the add-on using [`web-ext`](https://extensionworkshop.com/documentation/develop/web-ext-command-reference/).
89
+
4. On success, the pop-up reports the record URI returned by
90
+
`com.atproto.repo.createRecord`.
77
91
78
-
1. Configure `AMO_JWT_ISSUER` and `AMO_JWT_SECRET` repository secrets with your AMO API credentials if you want automatic signing.
79
-
Without the secrets, the workflow still produces an unsigned ZIP you can download.
80
-
2. Trigger the workflow manually (`Actions` → **package-extension** → **Run workflow**).
81
-
3. Download the artifacts:
82
-
- `frontpage-extension-unsigned` contains the ZIP that `web-ext build` generates.
83
-
- `frontpage-extension-signed` (only when secrets are present) contains the signed `.xpi` from AMO for self-hosting.
84
-
4. Each run also publishes a GitHub Release (tagged `v<version>-<run-id>`) that ships the same ZIP/XPI assets, so you can share a permanent download link.
85
-
- Mozilla requires every signed upload to have a unique version number. Bump `version` in `extension/manifest.json` before rerunning the workflow if you need a new signed package.
86
-
87
-
These artifacts can be hosted directly for self-distribution as described in the [Mozilla documentation](https://extensionworkshop.com/documentation/publish/self-distribution/).
88
-
89
-
### Tangled mirror
90
-
91
-
The `mirror-to-tangled.yml` workflow pushes every commit on `main` to Tangled, a federated Git hosting platform built on ATProto.
92
-
Browse the mirror at <https://tangled.org/anton.galiglobal.com/frontpage_firefox_plugin>.
93
-
Add a deploy key with write access as the `TANGLED_DEPLOY_KEY` repository secret so the mirror stays up to date.
92
+
See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup, build pipeline,
93
+
and implementation notes.