Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

browser-extension: add a safari build target; point Safari packaging at it

Claude192375d48edb
diff --git a/browser-extension/README.md b/browser-extension/README.md
index 368d2cf0..67e492d8 100644
--- a/browser-extension/README.md
+++ b/browser-extension/README.md
@@ -80,6 +80,7 @@ npx playwright install chromium # one-time, for the e2e harness
npm run build # bundle src/ → dist/ (esbuild, Chrome target)
npm run build:watch # rebuild on change
npm run build:firefox # bundle src/ → dist-firefox/ with the Gecko manifest
+npm run build:safari # bundle src/ → dist-safari/ (input to packaging/macos/safari; not loadable alone)
npm run lint:firefox # build:firefox, then Mozilla's web-ext lint (warnings fail)
npm run check # tsc --noEmit
npm run test:unit # pure adapter + normalization tests (vitest, no browser)
@@ -227,7 +228,7 @@ staging one. Prefer a throwaway account where practical.
| `src/options/` | OTLP endpoint and per-site toggles. |
| `e2e/` | Playwright fixtures + helpers (`mock-collector`, `sse-replay-server`, `otlp-assertions`) + specs. |
| `test/unit/` | vitest unit tests. |
-| `tools/targets.mjs` | Per-browser build targets (`chrome` → `dist/`, `firefox` → `dist-firefox/`) and the manifest each one ships. |
+| `tools/targets.mjs` | Per-browser build targets (`chrome` → `dist/`, `firefox` → `dist-firefox/`, `safari` → `dist-safari/`) and the manifest each one ships. |
| `fixtures/<site>/*.sse` | Recorded, sanitized chat streams — real captures for `claude/` and `chatgpt/`. |
## Testing model (layered by fidelity/cost)
@@ -251,7 +252,11 @@ staging one. Prefer a throwaway account where practical.
## Safari (experimental, not shipped)
-Safari support is in progress (#392). Its packaging lives in
+Safari support is in progress (#392). `npm run build:safari` writes
+`dist-safari/`: the same bundles and the unchanged `src/manifest.json`, compiled
+for Safari 18, the first release documented to run MAIN-world content scripts.
+Safari cannot load that folder for real use; it has to ship inside a macOS app.
+The packaging lives in
[`packaging/macos/safari/`](../packaging/macos/safari/README.md): the Xcode app
wrapper script, the signing plan, the MDM example, and a
[compatibility review](../packaging/macos/safari/compatibility.md) with its gap
diff --git a/browser-extension/package.json b/browser-extension/package.json
index 71ef9608..564caa8a 100644
--- a/browser-extension/package.json
+++ b/browser-extension/package.json
@@ -8,6 +8,7 @@
"build": "node esbuild.config.mjs",
"build:watch": "node esbuild.config.mjs --watch",
"build:firefox": "node esbuild.config.mjs --target firefox",
+ "build:safari": "node esbuild.config.mjs --target safari",
"lint:firefox": "npm run build:firefox && web-ext lint --source-dir dist-firefox --warnings-as-errors",
"check": "tsc --noEmit",
"test:unit": "vitest run",
diff --git a/browser-extension/test/unit/build.test.ts b/browser-extension/test/unit/build.test.ts
index 09493ead..e5091c39 100644
--- a/browser-extension/test/unit/build.test.ts
+++ b/browser-extension/test/unit/build.test.ts
@@ -1,5 +1,5 @@
// Runs the real build (esbuild.config.mjs) for each target into a temp dir. The
-// Chrome output must be what it always was; the Firefox output must be complete.
+// Chrome output must be what it always was; the Firefox and Safari outputs must be complete.
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
import { execFileSync } from 'node:child_process';
import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync } from 'node:fs';
@@ -16,7 +16,7 @@ const out = (t: string) => path.join(work, t);
beforeAll(() => {
work = mkdtempSync(path.join(tmpdir(), 'beacon-ext-build-'));
- for (const t of ['chrome', 'firefox']) {
+ for (const t of ['chrome', 'firefox', 'safari']) {
execFileSync(process.execPath, ['esbuild.config.mjs', '--target', t, '--outdir', out(t)], {
cwd: root,
stdio: 'pipe',
@@ -28,7 +28,7 @@ afterAll(() => {
rmSync(work, { recursive: true, force: true });
});
-describe.each(['chrome', 'firefox'])('%s build', (t) => {
+describe.each(['chrome', 'firefox', 'safari'])('%s build', (t) => {
it.each(FILES)('emits a non-empty %s', (f) => {
const p = path.join(out(t), f);
expect(existsSync(p)).toBe(true);
@@ -49,6 +49,16 @@ describe('chrome build', () => {
});
});
+describe('safari build', () => {
+ it('ships src/manifest.json byte for byte, with the same file set as Chrome', () => {
+ expect(readFileSync(path.join(out('safari'), 'manifest.json'))).toEqual(
+ readFileSync(path.join(root, 'src', 'manifest.json')),
+ );
+ const got = readdirSync(out('safari')).filter((f) => !f.endsWith('.map')).sort();
+ expect(got).toEqual([...FILES].sort());
+ });
+});
+
describe('firefox build', () => {
it('writes the derived Gecko manifest', () => {
const m = JSON.parse(readFileSync(path.join(out('firefox'), 'manifest.json'), 'utf8'));
diff --git a/browser-extension/test/unit/targets.test.ts b/browser-extension/test/unit/targets.test.ts
index eba67be1..3b477b64 100644
--- a/browser-extension/test/unit/targets.test.ts
+++ b/browser-extension/test/unit/targets.test.ts
@@ -11,6 +11,7 @@ import {
FIREFOX_MIN_VERSION,
GECKO_ID,
MIN_FIREFOX_FOR_MAIN_WORLD,
+ SAFARI_MIN_VERSION,
TARGETS,
firefoxManifest,
getTarget,
@@ -36,7 +37,7 @@ describe('build targets', () => {
});
it('rejects an unknown target by name', () => {
- expect(() => getTarget('safari')).toThrow(/unknown build target "safari".*chrome, firefox/);
+ expect(() => getTarget('opera')).toThrow(/unknown build target "opera".*chrome, firefox, safari/);
expect(() => getTarget('toString')).toThrow(/unknown build target/);
});
@@ -47,6 +48,27 @@ describe('build targets', () => {
});
});
+describe('safari target', () => {
+ it('builds to dist-safari and ships src/manifest.json verbatim', () => {
+ const safari = getTarget('safari');
+ expect(safari.outdir).toBe('dist-safari');
+ expect(safari.manifest).toBeNull();
+ });
+
+ it('targets a Safari that runs world: "MAIN" content scripts (Safari 18)', () => {
+ expect(SAFARI_MIN_VERSION).toBeGreaterThanOrEqual(18);
+ expect(getTarget('safari').esbuildTarget).toEqual([`safari${SAFARI_MIN_VERSION}`]);
+ const usesMain = base().content_scripts.some((c: { world?: string }) => c.world === 'MAIN');
+ expect(usesMain).toBe(true);
+ });
+
+ it('keeps the Chrome background shape, which Safari documents as supported', () => {
+ // Verbatim means the service worker ships as is. If Safari needs
+ // background.scripts instead, the target must gain a derived manifest.
+ expect(base().background).toEqual({ service_worker: 'sw.js' });
+ });
+});
+
describe('firefoxManifest', () => {
it('replaces the service worker with a background script (Firefox runs event pages)', () => {
const m = firefoxManifest(base());
diff --git a/browser-extension/tools/targets.d.mts b/browser-extension/tools/targets.d.mts
index 54484838..a127ec4b 100644
--- a/browser-extension/tools/targets.d.mts
+++ b/browser-extension/tools/targets.d.mts
@@ -5,6 +5,7 @@ export declare const GECKO_ID: string;
export declare const FIREFOX_MIN_VERSION: string;
export declare const FIREFOX_ANDROID_MIN_VERSION: string;
export declare const MIN_FIREFOX_FOR_MAIN_WORLD: number;
+export declare const SAFARI_MIN_VERSION: number;
export declare const FIREFOX_DATA_COLLECTION: Readonly<{ required: string[] }>;
export declare function firefoxManifest(base: Record<string, any>): Record<string, any>;
diff --git a/browser-extension/tools/targets.mjs b/browser-extension/tools/targets.mjs
index fe017927..a7950685 100644
--- a/browser-extension/tools/targets.mjs
+++ b/browser-extension/tools/targets.mjs
@@ -90,6 +90,10 @@ export function firefoxManifest(base) {
return m;
}
+/** Oldest Safari the Safari build supports: the first release documented to run
+ * `content_scripts[].world: "MAIN"`, which the fetch interceptor depends on. */
+export const SAFARI_MIN_VERSION = 18;
+
/**
* @typedef {object} BuildTarget
* @property {string} name target id, as passed to `--target`
@@ -116,6 +120,19 @@ export const TARGETS = Object.freeze({
esbuildTarget: [`firefox${parseInt(FIREFOX_MIN_VERSION, 10)}`],
manifest: firefoxManifest,
},
+ // Safari documents every key src/manifest.json uses, including the
+ // `background.service_worker` and the MAIN-world content script (Safari 18),
+ // so the manifest ships verbatim and only the esbuild target differs. The
+ // output is not loadable on its own: packaging/macos/safari wraps it in the
+ // macOS app Safari requires. If the service worker turns out to be unable to
+ // reach the collector (see packaging/macos/safari/compatibility.md), this is
+ // where a derived manifest with `background.scripts` would go.
+ safari: {
+ name: 'safari',
+ outdir: 'dist-safari',
+ esbuildTarget: [`safari${SAFARI_MIN_VERSION}`],
+ manifest: null,
+ },
});
export const DEFAULT_TARGET = 'chrome';
diff --git a/packaging/macos/safari/README.md b/packaging/macos/safari/README.md
index b3127257..fa42207f 100644
--- a/packaging/macos/safari/README.md
+++ b/packaging/macos/safari/README.md
@@ -35,7 +35,7 @@ On a Mac with full Xcode (the Command Line Tools alone do not include the
packager):
```bash
-cd browser-extension && npm ci && npm run build && cd ..
+cd browser-extension && npm ci && npm run build:safari && cd ..
sh packaging/macos/safari/create-safari-project.sh
```
@@ -44,7 +44,7 @@ target (`ai.asymptote.beacon.browser-collector`) and the extension target
(`ai.asymptote.beacon.browser-collector.Extension`). The extension files are
**copied** into the project, so it is a snapshot of that build. Regenerate it
(`--force`) after rebuilding the extension. For a local edit-and-build loop, use
-`--reference-resources`; the project then points at `browser-extension/dist`,
+`--reference-resources`; the project then points at `browser-extension/dist-safari`,
and Product > Build picks up each rebuild.
`--dry-run` validates the inputs and prints the exact packager command on any
@@ -57,17 +57,22 @@ extension in step, and avoids a hand-edited Xcode project in the repository. If
the wrapper later needs native code (it does not today), commit the project
then.
-### Dependency on the Firefox work (#393)
+### The Safari build target
-This directory wraps whatever build it is pointed at. It does not add a
-`browser.*` shim or per-target manifests: #393 owns both.
+The script wraps `browser-extension/dist-safari/`, which `npm run build:safari`
+produces from the `safari` entry in `browser-extension/tools/targets.mjs`. That
+entry came with the per-target build and `browser.*` shim merged in #628 (the
+Firefox work, #393):
-- Safari does not need the shim. It supports `chrome.*`.
-- Safari may need a manifest variant. If S5 in the checklist shows the service
- worker's POST failing CORS even after `127.0.0.1` access is granted, the Safari
- target needs `background.scripts` plus `preferred_environment`. That comes from
- #393's per-target manifest build. Point the script at that target's output
- with `--extension-dir` (or `SAFARI_EXTENSION_DIR`).
+- The Safari target ships `src/manifest.json` unchanged and compiles for Safari
+ 18, the first release documented to run MAIN-world content scripts.
+- The shim is harmless in Safari but not required, because Safari supports
+ `chrome.*` as well.
+- If S5 in the checklist shows the service worker's POST failing CORS even
+ after `127.0.0.1` access is granted, give the Safari target a derived manifest
+ with `background.scripts` plus `preferred_environment`. `firefoxManifest` in
+ the same file is the model to follow. Point the script at any other build with
+ `--extension-dir` (or `SAFARI_EXTENSION_DIR`).
## Distribution and signing plan
@@ -93,7 +98,7 @@ Proposed release steps, for a macOS runner in the existing `release` environment
which already holds `DEVELOPER_ID_APP_CERT_P12`, `DEVELOPER_ID_INSTALLER_CERT_P12`,
their passwords, and the `NOTARY_API_KEY_*` secrets:
-1. Build the extension and strip sourcemaps, as the Chrome zip job does.
+1. Build the extension (`npm run build:safari`) and strip sourcemaps, as the Chrome zip job does.
2. `sh packaging/macos/safari/create-safari-project.sh --force`
3. Archive the app with the Developer ID Application identity, the team from the
`APPLE_TEAM_ID` variable, and the hardened runtime. macOS requires app
diff --git a/packaging/macos/safari/compatibility.md b/packaging/macos/safari/compatibility.md
index 6bb130d9..57362ab2 100644
--- a/packaging/macos/safari/compatibility.md
+++ b/packaging/macos/safari/compatibility.md
@@ -63,8 +63,10 @@ and a third gate, not in the issue, is the real risk.
`AllowedDomains` (see [`mdm/`](mdm/)). This is the first thing to try in S5.
- If the service worker still fails once access is granted, ship a Safari
manifest variant with `background.scripts` (plus
- `preferred_environment: ["document", "service_worker"]`). That needs the
- per-target manifest build owned by #393.
+ `preferred_environment: ["document", "service_worker"]`). The per-target
+ build merged in #628 makes that a derived-manifest function on the `safari`
+ entry in `browser-extension/tools/targets.mjs`, which today ships the
+ manifest unchanged.
- Last resort: add a `cors.allowed_origins` entry for
`safari-web-extension://*` to the collector's OTLP HTTP receiver.
Safari changes the extension's origin UUID on every launch
@@ -82,8 +84,12 @@ Blocking. Must be confirmed on a Mac before Safari counts as supported:
observed teeing `window.fetch` on claude.ai and chatgpt.com in Safari.
- **G3: site-access grants.** Content scripts do not run on claude.ai or
chatgpt.com until the user grants access. Unmanaged users need an onboarding
- step. Managed fleets can pre-grant with MDM `AllowedDomains`, but only on
- supervised macOS 15+ (see [`README.md`](README.md#mdm)).
+ step. The host-permission banner merged in #628 (`src/shared/permissions.ts`,
+ shown in the popup and options page) may cover that, since it asks through
+ `permissions.request`. How Safari answers that call from an extension page has
+ not been tested, so S4 must check it. Managed fleets can pre-grant with MDM
+ `AllowedDomains`, but only on supervised macOS 15+ (see
+ [`README.md`](README.md#mdm)).
Non-blocking differences:
@@ -107,8 +113,9 @@ Non-blocking differences:
Not needed for Safari:
-- **A `browser.*` shim.** Safari supports `chrome.*` natively. The shim #393 adds
- is harmless here but not required.
+- **A `browser.*` shim.** Safari supports `chrome.*` natively. The shim merged
+ in #628 (`src/shared/browser.ts`) prefers `browser.*` where it exists, which is
+ harmless in Safari but not required.
- **The Local Network usage string (`NSLocalNetworkUsageDescription`).** See
"Reaching the collector" above.
diff --git a/packaging/macos/safari/create-safari-project.sh b/packaging/macos/safari/create-safari-project.sh
index ee260892..eee59c4e 100755
--- a/packaging/macos/safari/create-safari-project.sh
+++ b/packaging/macos/safari/create-safari-project.sh
@@ -14,7 +14,7 @@ set -eu
ROOT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")/../../.." && pwd)"
-EXTENSION_DIR="${SAFARI_EXTENSION_DIR:-$ROOT_DIR/browser-extension/dist}"
+EXTENSION_DIR="${SAFARI_EXTENSION_DIR:-$ROOT_DIR/browser-extension/dist-safari}"
PROJECT_DIR="${SAFARI_PROJECT_DIR:-$ROOT_DIR/dist/safari}"
APP_NAME="${SAFARI_APP_NAME:-Beacon Browser Collector}"
BUNDLE_IDENTIFIER="${SAFARI_BUNDLE_IDENTIFIER:-ai.asymptote.beacon.browser-collector}"
@@ -32,11 +32,11 @@ usage() {
Usage:
sh packaging/macos/safari/create-safari-project.sh [options]
-Build the extension first (cd browser-extension && npm ci && npm run build),
+Build the extension first (cd browser-extension && npm ci && npm run build:safari),
then run this on a Mac with Xcode installed.
Options:
- --extension-dir DIR Built extension to wrap (default: browser-extension/dist).
+ --extension-dir DIR Built extension to wrap (default: browser-extension/dist-safari).
--project-dir DIR Directory the Xcode project is written under
(default: dist/safari). The packager creates
DIR/<app name>/.
@@ -139,7 +139,7 @@ if ! printf '%s\n' "$BUNDLE_IDENTIFIER" | grep -Eq '^[A-Za-z0-9-]+(\.[A-Za-z0-9-
die "--bundle-id must be a reverse-DNS identifier of letters, digits, hyphens, and periods (got '$BUNDLE_IDENTIFIER')"
fi
-[ -d "$EXTENSION_DIR" ] || die "extension directory not found: $EXTENSION_DIR (run 'npm ci && npm run build' in browser-extension first)"
+[ -d "$EXTENSION_DIR" ] || die "extension directory not found: $EXTENSION_DIR (run 'npm ci && npm run build:safari' in browser-extension first)"
EXTENSION_DIR="$(CDPATH= cd -- "$EXTENSION_DIR" && pwd)"
for f in $REQUIRED_FILES; do
diff --git a/packaging/macos/safari/smoke-checklist.md b/packaging/macos/safari/smoke-checklist.md
index 8f72db65..92cf9867 100644
--- a/packaging/macos/safari/smoke-checklist.md
+++ b/packaging/macos/safari/smoke-checklist.md
@@ -24,7 +24,7 @@ The IDs (S1 to S10) are referenced from [`compatibility.md`](compatibility.md).
- A fresh extension build:
```bash
- cd browser-extension && npm ci && npm run build && cd ..
+ cd browser-extension && npm ci && npm run build:safari && cd ..
```
- Safari > Settings > Advanced: turn on "Show features for web developers".
@@ -33,7 +33,7 @@ Choose one of two ways to load the build:
- **Quick (no Xcode, unsigned):** Safari > Settings > Developer > turn on
"Allow unsigned extensions", then "Add Temporary Extension…" and select
- `browser-extension/dist`. Safari removes temporary extensions after 24 hours or
+ `browser-extension/dist-safari`. Safari removes temporary extensions after 24 hours or
when you quit Safari, and "Allow unsigned extensions" also resets on quit.
- **App wrapper (what users get):**
@@ -60,7 +60,7 @@ sudo tail -f /var/log/beacon-agent/runtime.jsonl # system/package install
| S1 | **Loads.** The extension appears in Safari > Settings > Extensions with name "Agent Beacon — Browser Collector" and the manifest's version, and can be enabled. If you used the app wrapper, note any packager warnings about unsupported manifest keys. | Enabled, no load error. Any packager warnings are copied into the results. |
| S2 | **Service worker starts.** Develop > Web Extension Background Content (or the extension's service worker entry in the Develop menu) opens an inspector for `sw.js`. | The console shows no uncaught errors at startup. |
| S3 | **MAIN-world interceptor runs.** Grant the extension access to claude.ai (toolbar button > Always Allow on This Website), reload claude.ai, open the page's Web Inspector, and check that `window.fetch` has been wrapped. For example, `window.fetch.toString()` does not print `[native code]`. | The interceptor is installed before the page's first chat request. |
-| S4 | **Site-access flow.** On a site you have not granted yet, the toolbar badge asks for access and capture does not happen. After you grant access, capture works. | The behaviour matches Safari's documented ask-first model. Write down the exact prompts shown; users will see the same ones. |
+| S4 | **Site-access flow.** On a site you have not granted yet, the toolbar badge asks for access and capture does not happen. Open the popup: the host-permission banner should list the missing sites, and its grant button should trigger Safari's permission request. After you grant access, capture works. | The behaviour matches Safari's documented ask-first model. Write down the exact prompts shown; users will see the same ones. |
| S5 | **Reaches the collector.** Grant access to `127.0.0.1` too, if Safari lists it: Safari > Settings > Websites > the extension, or "Always Allow on Every Website" for a test profile only. Send a claude.ai message and watch the service worker inspector's Network and Console tabs. | The `POST http://127.0.0.1:4318/v1/logs` returns 200. There is no "access control checks" (CORS) error, no ATS error, and no Local Network prompt from macOS. If it fails, record the exact console error and see "Reaching the collector" in `compatibility.md`. |
| S6 | **claude.ai end to end.** Send one message on claude.ai. | `runtime.jsonl` gains a `prompt.submitted` and an `agent.response.completed` event with harness `claude_web`, the right model, and the prompt and response text (with retention `full`). |
| S7 | **chatgpt.com end to end.** Send one message on chatgpt.com. | The same pair of events, with harness `chatgpt_web`. |
diff --git a/packaging/macos/safari/test-safari-packaging.sh b/packaging/macos/safari/test-safari-packaging.sh
index 6e64960c..5aeccf55 100755
--- a/packaging/macos/safari/test-safari-packaging.sh
+++ b/packaging/macos/safari/test-safari-packaging.sh
@@ -108,6 +108,13 @@ sh -n "$0"
run_linux --help >"$TMP_DIR/out" || fail "--help should exit 0"
grep -q '^Usage:' "$TMP_DIR/out" || fail "--help should print usage"
+# The default input is the `safari` build target's output directory.
+grep -q 'default: browser-extension/dist-safari' "$TMP_DIR/out" || fail "--help should name dist-safari as the default"
+grep -q 'EXTENSION_DIR="${SAFARI_EXTENSION_DIR:-$ROOT_DIR/browser-extension/dist-safari}"' "$SCRIPT" ||
+ fail "the script should default to browser-extension/dist-safari"
+grep -q "outdir: 'dist-safari'" "$ROOT_DIR/browser-extension/tools/targets.mjs" ||
+ fail "browser-extension/tools/targets.mjs should build the safari target to dist-safari"
+
# --- argument handling ---
expect_fail "unknown argument" "unknown argument: --bogus" -- run_linux --bogus