@stacksjs/browser-extension 0.70.113 → 0.70.114

package/README.md

@@ -1,9 +1,11 @@
 # @stacksjs/browser-extension
 
-Build MV3 browser extensions (Chrome + Firefox) the Stacks way — the manifest,
-content/background scripts, stx pages, `declarativeNetRequest` rulesets, and
-store-ready packaging are all derived from a single `config/extension.ts`. No
-hand-written `manifest.json`, no per-project build script.
+Build MV3 browser extensions (Chrome + Firefox + Safari) the Stacks way — the
+manifest, content/background scripts, stx pages, `declarativeNetRequest`
+rulesets, and store-ready packaging are all derived from a single
+`config/extension.ts`. No hand-written `manifest.json`, no per-project build
+script. Safari additionally gets the macOS container app: a checked-in Xcode
+scaffold, appex resource sync, and an xcodebuild pipeline.
 
 ## Quick start
 
@@ -11,9 +13,36 @@ hand-written `manifest.json`, no per-project build script.
 buddy extension:init          # scaffold config/extension.ts + starter files
 buddy extension:build         # build all targets → dist/ (+ dist-firefox/)
 buddy extension:build --target chrome
+buddy extension:build --target safari   # → dist-safari/ (browser.* namespace, safari manifest)
 buddy extension:package       # build + zip store-ready archives
 ```
 
+## Safari
+
+Safari Web Extensions ship inside a macOS app, so the safari target has two
+halves: the web bundle (`extension:build --target safari`) and the container
+app. The build rewrites promise-style `chrome.*` to `browser.*` (Safari's
+`chrome.*` is callback-flavoured) and pins
+`browser_specific_settings.safari.strict_min_version` (default 18.4, the first
+Safari with MAIN-world content scripts + `match_about_blank`).
+
+```sh
+buddy extension:safari:init   # scaffold the Xcode container app into safari/
+buddy extension:safari:app    # build + sync into the appex + xcodebuild
+buddy extension:safari:publish # signed archive + App Store Connect upload
+```
+
+Set `safariBundleId` in the config (the appex gets `<safariBundleId>.Extension`)
+and `safariTeamId` to the Apple Developer team used for signing. Publishing
+reads `APP_STORE_CONNECT_API_KEY_ID`, `APP_STORE_CONNECT_API_ISSUER_ID`, and
+`APP_STORE_CONNECT_API_KEY_PATH` from the environment. Run with
+`--validate-only` to exercise Apple's validation without uploading a build.
+and list any build output that is not part of the extension (marketing pages,
+etc.) in `safariExclude` so it stays out of the appex. The scaffold mirrors
+what `xcrun safari-web-extension-converter` generates, so day-to-day work
+never needs the converter; `--signed` builds need an Apple Development
+identity selected in Xcode.
+
 ## Configure
 
 ```ts
@@ -24,6 +53,7 @@ export default defineExtension({
   name: 'My Extension',
   description: 'Does something useful.',
   geckoId: 'my-ext@example.com',      // required to ship on Firefox
+  safariBundleId: 'com.example.MyExtension', // Safari container app bundle id
   targets: ['chrome', 'firefox'],
 
   background: 'src/background/index.ts',
@@ -49,6 +79,7 @@ export default defineExtension({
     hostPermissions: ['http://*/*', 'https://*/*'],
     minimumChromeVersion: '111',
     firefoxMinVersion: '140.0',
+    safariMinVersion: '18.4',
     webAccessibleResources: [{ resources: ['stubs/*.js'], matches: ['<all_urls>'] }],
   },
 
@@ -73,5 +104,14 @@ vs Firefox event-page + `browser_specific_settings.gecko`), and runs your
 ## Programmatic API
 
 ```ts
-import { buildExtension, buildAllTargets, packageExtension, generateManifest } from '@stacksjs/browser-extension'
+import {
+  buildExtension,
+  buildAllTargets,
+  packageExtension,
+  generateManifest,
+  rewriteBrowserNamespace,
+  scaffoldSafariApp,
+  syncSafariResources,
+  buildSafariApp,
+} from '@stacksjs/browser-extension'
 ```

package/dist/build.d.ts

@@ -1,6 +1,8 @@
 import type { BuildOptions, ExtensionConfig, ExtensionTarget } from './types';
 /** Resolve the output directory for a target. */
 export declare function resolveOutdir(config: ExtensionConfig, target: ExtensionTarget, override?: string): string;
+/** Rewrite promise-style `chrome.*` API access in `code` to `browser.*`. */
+export declare function rewriteBrowserNamespace(code: string): { code: string, replacements: number };
 /**`) + extra `assets` copied in
  * - stx pages → `<name>.html` (+ companion `<name>.js`), sanitized for the
  *   extension CSP, with stx dev chunks removed

package/dist/build.js

@@ -11,7 +11,14 @@ export function resolveOutdir(config, target, override) {
     return config.outdir;
   if (config.outdir?.[target])
     return config.outdir[target];
-  return target === "firefox" ? "dist-firefox" : "dist";
+  return target === "chrome" ? "dist" : `dist-${target}`;
+}
+const browserApiNamespaces = ["runtime", "tabs", "declarativeNetRequest", "storage", "action", "alarms", "scripting", "webNavigation", "cookies", "contextMenus", "notifications", "i18n", "downloads", "permissions", "windows", "bookmarks", "history", "search", "sidePanel", "omnibox", "idle", "management", "commands", "sessions", "topSites", "extension", "types", "devtools", "offscreen", "clipboard"], browserNamespacePattern = new RegExp(`\\bchrome\\.(?=(?:${browserApiNamespaces.join("|")})[?.])`, "g");
+export function rewriteBrowserNamespace(code) {
+  const replacements = (code.match(browserNamespacePattern) ?? []).length;
+  if (!replacements)
+    return { code, replacements: 0 };
+  return { code: code.replace(browserNamespacePattern, "browser."), replacements };
 }
 function normalizePage(page) {
   return typeof page === "string" ? { template: page } : page;
@@ -88,6 +95,12 @@ export async function buildExtension(config, options) {
   for (const cs of config.content ?? [])
     scripts.push({ entry: cs.entry, out: contentScriptOut(cs.entry, cs.out) });
   await Promise.all(scripts.map((s) => buildScript(s.entry, s.out, outdir, cwd, minify)));
+  if (target === "safari")
+    for await (const file of new Glob("*.js").scan(outdir)) {
+      const path = join(outdir, file), { code, replacements } = rewriteBrowserNamespace(await Bun.file(path).text());
+      if (replacements)
+        await Bun.write(path, code);
+    }
   for (const rule of config.rules ?? []) {
     if (!rule.source)
       continue;

package/dist/index.d.ts

@@ -1,14 +1,16 @@
 /**
  * @stacksjs/browser-extension
  *
- * Build MV3 browser extensions (Chrome + Firefox) from a single
+ * Build MV3 browser extensions (Chrome, Firefox, Safari) from a single
  * `ExtensionConfig` — manifest generation, content/background script bundling,
  * stx pages, declarativeNetRequest rulesets, and store-ready packaging — with
- * none of the per-project boilerplate.
+ * none of the per-project boilerplate. Safari additionally gets the container
+ * app scaffold, appex resource sync, and xcodebuild pipeline.
  */
 export * from './build';
 export * from './config';
 export * from './manifest';
 export * from './package';
+export * from './safari';
 export * from './sanitize';
 export * from './types';

package/dist/index.js

@@ -2,5 +2,6 @@ export * from "./build";
 export * from "./config";
 export * from "./manifest";
 export * from "./package";
+export * from "./safari";
 export * from "./sanitize";
 export * from "./types";

package/dist/manifest.d.ts

@@ -4,7 +4,10 @@ export declare function contentScriptOut(entry: string, out?: string): string;
 /**
  * Generate an MV3 manifest for a target from the extension config. Chrome uses
  * a `service_worker` background + `minimum_chrome_version`; Firefox uses a
- * `scripts` event page + `browser_specific_settings.gecko` (required by AMO).
+ * `scripts` event page + `browser_specific_settings.gecko` (required by AMO);
+ * Safari uses a classic (non-module) `service_worker` +
+ * `browser_specific_settings.safari` (15.4+ runs MV3 service workers, and the
+ * bundles are classic IIFEs, so the module hint is dropped).
  */
 export declare function generateManifest(config: ExtensionConfig, opts: { version: string, target?: ExtensionTarget }): GeneratedManifest;
 /** MV3 manifest shape (loose — the two targets diverge on `background`). */
@@ -23,6 +26,10 @@ export declare interface GeneratedManifest {
       strict_min_version: string
       data_collection_permissions: { required: ['none'] }
     }
+  } | {
+    safari: {
+      strict_min_version: string
+    }
   }
   permissions?: string[]
   optional_permissions?: string[]

package/dist/manifest.js

@@ -3,20 +3,20 @@ export function contentScriptOut(entry, out) {
   return out ?? basename(entry).replace(/\.[cm]?tsx?$/, ".js");
 }
 export function generateManifest(config, opts) {
-  const isFirefox = (opts.target ?? "chrome") === "firefox", m = config.manifest ?? {}, manifest = {
+  const target = opts.target ?? "chrome", isFirefox = target === "firefox", isSafari = target === "safari", m = config.manifest ?? {}, manifest = {
     manifest_version: 3,
     name: config.name,
     description: config.description,
     version: opts.version
   };
-  if (!isFirefox && m.minimumChromeVersion)
+  if (!isFirefox && !isSafari && m.minimumChromeVersion)
     manifest.minimum_chrome_version = m.minimumChromeVersion;
   if (config.pages?.popup)
     manifest.action = { default_title: config.name, default_popup: "popup.html" };
   if (config.pages?.options)
     manifest.options_page = "options.html";
   if (config.background)
-    manifest.background = isFirefox ? { scripts: ["background.js"], type: "module" } : { service_worker: "background.js", type: "module" };
+    manifest.background = isFirefox ? { scripts: ["background.js"], type: "module" } : isSafari ? { service_worker: "background.js" } : { service_worker: "background.js", type: "module" };
   if (isFirefox && config.geckoId)
     manifest.browser_specific_settings = {
       gecko: {
@@ -25,6 +25,12 @@ export function generateManifest(config, opts) {
         data_collection_permissions: { required: ["none"] }
       }
     };
+  if (isSafari)
+    manifest.browser_specific_settings = {
+      safari: {
+        strict_min_version: m.safariMinVersion ?? "18.4"
+      }
+    };
   if (m.permissions?.length)
     manifest.permissions = m.permissions;
   if (m.optionalPermissions?.length)

package/dist/package.js

@@ -12,7 +12,7 @@ export async function packageExtension(config, options) {
   const outdir = resolve(cwd, resolveOutdir(config, target));
   if (!existsSync(outdir))
     throw Error(`[browser-extension] nothing to package: ${outdir} does not exist`);
-  const suffix = target === "firefox" ? "-firefox" : "", outfile = resolve(cwd, options.outfile ?? `${slug(config.name)}-${options.version}${suffix}.zip`);
+  const suffix = target === "chrome" ? "" : `-${target}`, outfile = resolve(cwd, options.outfile ?? `${slug(config.name)}-${options.version}${suffix}.zip`);
   await mkdir(dirname(outfile), { recursive: !0 });
   const proc = Bun.spawn(["zip", "-r", "-q", outfile, "."], { cwd: outdir, stdout: "pipe", stderr: "pipe" }), code = await proc.exited;
   if (code !== 0)

package/dist/safari.d.ts

@@ -0,0 +1,79 @@
+import type { ExtensionConfig } from './types';
+/**
+ * Safari container-app tooling: scaffold the Xcode project, sync the built
+ * safari bundle into the appex Resources, and xcodebuild the app.
+ *
+ * Safari Web Extensions ship inside a macOS app, so the safari target has two
+ * halves: the web bundle (`extension:build --target safari`, `dist-safari/`)
+ * and the container app scaffolded here (a checked-in, converter-free Xcode
+ * project: SwiftUI app + Safari Web Extension appex).
+ *
+ * The template tree lives in `safari-template/` at the package root and is
+ * tokenized (`__APP_NAME__`, `__BUNDLE_ID__`, …); scaffolding copies it and
+ * substitutes per project. It mirrors what `xcrun
+ * safari-web-extension-converter` generates, so day-to-day work never needs
+ * the converter.
+ */
+/** App target name from the extension display name (`Very Good AdBlock` → `VeryGoodAdBlock`). */
+export declare function safariAppName(config: ExtensionConfig): string;
+/** Directory the container app is scaffolded into. */
+export declare function safariProjectDir(cwd?: unknown, dir?: string): string;
+/**
+ * Scaffold the macOS container app (Xcode project + SwiftUI app + appex) from
+ * the tokenized template. Idempotent: existing files are kept unless `force`.
+ * Also renders the AppIcon/ExtensionIcon PNGs from the project's own icons
+ * via `sips` (macOS-only step; skipped with a warning elsewhere).
+ */
+export declare function scaffoldSafariApp(config: ExtensionConfig, options?: SafariScaffoldOptions): Promise<{ dir: string, written: string[], skipped: string[] }>;
+/**
+ * Mirror the built safari bundle into the appex `Resources/` folder. The
+ * project references Resources as a folder, so everything synced here ships
+ * in the appex verbatim. Files listed in `config.safariExclude` (e.g.
+ * marketing-site pages built into dist) are kept out.
+ */
+export declare function syncSafariResources(config: ExtensionConfig, options?: SafariSyncOptions): Promise<{ resources: string, files: number }>;
+/**
+ * Full pipeline: build the safari bundle, sync it into the appex Resources,
+ * then xcodebuild the container app when full Xcode is available. Returns the
+ * built `.app` path (undefined when xcodebuild was skipped/unavailable).
+ */
+export declare function buildSafariApp(config: ExtensionConfig, options?: SafariAppBuildOptions): Promise<{ appPath?: string, resources: string }>;
+/**
+ * Create a signed Release archive and either validate it or upload it to App
+ * Store Connect. Xcode owns certificate/profile creation and the upload so the
+ * same command works locally and in macOS CI with an API key.
+ */
+export declare function publishSafariApp(config: ExtensionConfig, options: SafariPublishOptions): Promise<{ archivePath: string, exportPath: string, buildNumber: string }>;
+export declare interface SafariScaffoldOptions {
+  bundleId?: string
+  dir?: string
+  force?: boolean
+  version?: string
+  iconsDir?: string
+  teamId?: string
+  cwd?: string
+}
+export declare interface SafariSyncOptions {
+  outdir?: string
+  dir?: string
+  cwd?: string
+}
+export declare interface SafariAppBuildOptions extends SafariSyncOptions {
+  release?: boolean
+  signed?: boolean
+  skipXcodebuild?: boolean
+  version?: string
+  build?: boolean
+}
+export declare interface AppStoreConnectAuth {
+  keyId?: string
+  issuerId?: string
+  keyPath?: string
+}
+export declare interface SafariPublishOptions extends SafariSyncOptions, AppStoreConnectAuth {
+  version: string
+  buildNumber?: string
+  teamId?: string
+  validateOnly?: boolean
+  build?: boolean
+}

package/dist/safari.js

@@ -0,0 +1,199 @@
+import { cpSync, existsSync, readdirSync, statSync } from "node:fs";
+import { mkdir, rm } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { buildExtension, resolveOutdir } from "./build";
+export function safariAppName(config) {
+  const name = config.name.replace(/[^a-z0-9]+/gi, "");
+  if (!name)
+    throw Error("[browser-extension] cannot derive an app name from the extension name; set one without spaces");
+  return name;
+}
+export function safariProjectDir(cwd = process.cwd(), dir = "safari") {
+  return resolve(cwd, dir);
+}
+function templateRoot() {
+  return resolve(import.meta.dir, "..", "safari-template");
+}
+function fillTemplate(text, vars) {
+  return text.replaceAll("__EXT_BUNDLE_ID__", vars.extBundleId).replaceAll("__BUNDLE_ID__", vars.bundleId).replaceAll("__APP_DISPLAY_NAME__", vars.displayName).replaceAll("__APP_NAME__", vars.appName).replaceAll("__MARKETING_VERSION__", vars.version).replaceAll("__DEVELOPMENT_TEAM__", vars.teamId).replaceAll("__YEAR__", String(new Date().getFullYear()));
+}
+function* walk(dir, prefix = "") {
+  for (const entry of readdirSync(dir)) {
+    const rel = prefix ? `${prefix}/${entry}` : entry;
+    if (statSync(join(dir, entry)).isDirectory())
+      yield* walk(join(dir, entry), rel);
+    else
+      yield rel;
+  }
+}
+export async function scaffoldSafariApp(config, options = {}) {
+  const cwd = options.cwd ?? process.cwd(), appName = safariAppName(config), bundleId = options.bundleId ?? config.safariBundleId ?? `com.example.${appName.toLowerCase()}`, dir = safariProjectDir(cwd, options.dir), vars = {
+    appName,
+    displayName: config.name,
+    bundleId,
+    extBundleId: `${bundleId}.Extension`,
+    version: options.version ?? "0.1.0",
+    teamId: options.teamId ?? config.safariTeamId ?? ""
+  };
+  if (!options.bundleId && !config.safariBundleId)
+    console.warn(`[browser-extension] no safari bundle id configured; using placeholder ${bundleId}. Set safariBundleId in config/extension.ts.`);
+  const written = [], skipped = [];
+  for (const rel of walk(templateRoot())) {
+    const outRel = fillTemplate(rel, vars), out = join(dir, outRel);
+    if (existsSync(out) && !options.force) {
+      skipped.push(outRel);
+      continue;
+    }
+    await mkdir(dirname(out), { recursive: !0 });
+    await Bun.write(out, fillTemplate(await Bun.file(join(templateRoot(), rel)).text(), vars));
+    written.push(outRel);
+  }
+  await generateAppIcons(config, dir, vars, options.iconsDir, cwd);
+  return { dir, written, skipped };
+}
+const appIconSizes = [16, 32, 64, 128, 256, 512, 1024];
+async function generateAppIcons(config, dir, vars, iconsDir, cwd) {
+  const source = [
+    iconsDir,
+    join(resolve(cwd, resolveOutdir(config, "chrome")), "icons"),
+    config.public ? join(resolve(cwd, config.public), "icons") : void 0
+  ].filter(Boolean).find((d) => existsSync(d));
+  if (!source) {
+    console.warn("[browser-extension] no icons directory found; add PNGs to the asset catalog manually.");
+    return;
+  }
+  let largest, largestSize = 0;
+  for (const file of readdirSync(source)) {
+    const match = /(\d+)\.png$/.exec(file);
+    if (match && Number(match[1]) > largestSize) {
+      largestSize = Number(match[1]);
+      largest = join(source, file);
+    }
+  }
+  if (!largest) {
+    console.warn(`[browser-extension] no icon PNGs in ${source}; add them to the asset catalog manually.`);
+    return;
+  }
+  const appIconDir = join(dir, vars.appName, "Assets.xcassets", "AppIcon.appiconset"), imageSetDir = join(dir, vars.appName, "Assets.xcassets", "ExtensionIcon.imageset");
+  await mkdir(appIconDir, { recursive: !0 });
+  await mkdir(imageSetDir, { recursive: !0 });
+  const targets = [
+    ...appIconSizes.map((size) => ({ dir: appIconDir, name: `icon-${size}.png`, size })),
+    { dir: imageSetDir, name: "extension-icon-128.png", size: 128 },
+    { dir: imageSetDir, name: "extension-icon-256.png", size: 256 }
+  ];
+  for (const t of targets)
+    if (await Bun.spawn(["sips", "-z", String(t.size), String(t.size), largest, "--out", join(t.dir, t.name)], { stdout: "ignore", stderr: "pipe" }).exited !== 0) {
+      console.warn(`[browser-extension] sips failed for ${t.name} (macOS only). Generate the icon PNGs on a Mac.`);
+      return;
+    }
+}
+export async function syncSafariResources(config, options = {}) {
+  const cwd = options.cwd ?? process.cwd(), outdir = resolve(cwd, options.outdir ?? resolveOutdir(config, "safari"));
+  if (!existsSync(join(outdir, "manifest.json")))
+    throw Error(`[browser-extension] ${outdir}/manifest.json is missing. Run extension:build --target safari first.`);
+  const appName = safariAppName(config), resources = join(safariProjectDir(cwd, options.dir), `${appName} Extension`, "Resources"), exclude = new Set(config.safariExclude ?? []);
+  if (existsSync(resources)) {
+    for (const entry of readdirSync(resources))
+      if (entry !== ".gitkeep")
+        await rm(join(resources, entry), { recursive: !0, force: !0 });
+  }
+  await mkdir(resources, { recursive: !0 });
+  let files = 0;
+  for (const rel of walk(outdir)) {
+    if (exclude.has(rel))
+      continue;
+    const dest = join(resources, rel);
+    await mkdir(dirname(dest), { recursive: !0 });
+    cpSync(join(outdir, rel), dest);
+    files += 1;
+  }
+  return { resources, files };
+}
+export async function buildSafariApp(config, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  if (options.build !== !1) {
+    if (!options.version)
+      throw Error("[browser-extension] buildSafariApp needs a version to build the extension");
+    await buildExtension(config, { target: "safari", version: options.version, cwd });
+  }
+  const { resources } = await syncSafariResources(config, options);
+  if (options.skipXcodebuild)
+    return { resources };
+  const appName = safariAppName(config), dir = safariProjectDir(cwd, options.dir), configuration = options.release ? "Release" : "Debug", derivedData = join(dir, "build"), developerDir = (process.env.DEVELOPER_DIR ?? (await Bun.$`xcode-select -p`.text()).trim()).replace(/\/$/, "");
+  if (!developerDir.includes(".app/Contents/Developer")) {
+    console.error(`[browser-extension] full Xcode is required to build the app (active developer directory: ${developerDir}).`);
+    console.error("Install Xcode, then: sudo xcode-select -s /Applications/Xcode.app/Contents/Developer");
+    console.error("or point DEVELOPER_DIR at any Xcode toolchain (betas included) for this shell.");
+    console.error(`The extension payload is built and synced at ${resources}`);
+    return { resources };
+  }
+  const signing = options.signed ? ["-allowProvisioningUpdates"] : ["CODE_SIGNING_ALLOWED=NO"];
+  await Bun.$`xcodebuild -project ${join(dir, `${appName}.xcodeproj`)} -scheme ${appName} -configuration ${configuration} -derivedDataPath ${derivedData} ${signing} build`;
+  return { appPath: join(derivedData, "Build", "Products", configuration, `${appName}.app`), resources };
+}
+function appStoreConnectAuth(options) {
+  const keyId = options.keyId ?? process.env.APP_STORE_CONNECT_API_KEY_ID, issuerId = options.issuerId ?? process.env.APP_STORE_CONNECT_API_ISSUER_ID, keyPath = options.keyPath ?? process.env.APP_STORE_CONNECT_API_KEY_PATH, missing = [
+    !keyId && "APP_STORE_CONNECT_API_KEY_ID",
+    !issuerId && "APP_STORE_CONNECT_API_ISSUER_ID",
+    !keyPath && "APP_STORE_CONNECT_API_KEY_PATH"
+  ].filter(Boolean);
+  if (missing.length)
+    throw Error(`[browser-extension] missing App Store Connect credentials: ${missing.join(", ")}`);
+  if (!existsSync(resolve(keyPath)))
+    throw Error(`[browser-extension] App Store Connect API key not found: ${resolve(keyPath)}`);
+  return { keyId, issuerId, keyPath: resolve(keyPath) };
+}
+function xcodeAuthArgs(auth) {
+  return [
+    "-allowProvisioningUpdates",
+    "-authenticationKeyPath",
+    auth.keyPath,
+    "-authenticationKeyID",
+    auth.keyId,
+    "-authenticationKeyIssuerID",
+    auth.issuerId
+  ];
+}
+function exportOptionsPlist(method, teamId) {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>destination</key>
+  <string>upload</string>
+  <key>manageAppVersionAndBuildNumber</key>
+  <false/>
+  <key>method</key>
+  <string>${method}</string>
+  <key>signingStyle</key>
+  <string>automatic</string>
+  <key>teamID</key>
+  <string>${teamId}</string>
+  <key>uploadSymbols</key>
+  <true/>
+</dict>
+</plist>
+`;
+}
+export async function publishSafariApp(config, options) {
+  const cwd = options.cwd ?? process.cwd(), teamId = options.teamId ?? config.safariTeamId;
+  if (!teamId)
+    throw Error("[browser-extension] Safari publishing needs safariTeamId in config/extension.ts or --team-id");
+  const auth = appStoreConnectAuth(options), buildNumber = options.buildNumber ?? process.env.GITHUB_RUN_NUMBER ?? String(Math.floor(Date.now() / 1000));
+  if (!/^\d+(?:\.\d+){0,2}$/.test(buildNumber))
+    throw Error(`[browser-extension] invalid Safari build number ${buildNumber}; use one to three dot-separated integers`);
+  if (options.build !== !1)
+    await buildExtension(config, { target: "safari", version: options.version, cwd });
+  await syncSafariResources(config, options);
+  const appName = safariAppName(config), dir = safariProjectDir(cwd, options.dir), buildDir = join(dir, "build"), archivePath = join(buildDir, `${appName}.xcarchive`), exportPath = join(buildDir, options.validateOnly ? "validation" : "upload"), plistPath = join(buildDir, options.validateOnly ? "ExportOptions.validation.plist" : "ExportOptions.app-store.plist"), authArgs = xcodeAuthArgs(auth);
+  await mkdir(buildDir, { recursive: !0 });
+  await rm(archivePath, { recursive: !0, force: !0 });
+  await rm(exportPath, { recursive: !0, force: !0 });
+  const project = join(dir, `${appName}.xcodeproj`);
+  await Bun.$`xcodebuild -project ${project} -scheme ${appName} -configuration Release -destination generic/platform=macOS -archivePath ${archivePath} MARKETING_VERSION=${options.version} CURRENT_PROJECT_VERSION=${buildNumber} DEVELOPMENT_TEAM=${teamId} ${authArgs} archive`;
+  const method = options.validateOnly ? "validation" : "app-store-connect";
+  await Bun.write(plistPath, exportOptionsPlist(method, teamId));
+  await Bun.$`xcodebuild -exportArchive -archivePath ${archivePath} -exportPath ${exportPath} -exportOptionsPlist ${plistPath} ${authArgs}`;
+  return { archivePath, exportPath, buildNumber };
+}

package/dist/types.d.ts

@@ -39,6 +39,7 @@ export declare interface ManifestOverrides {
   optionalPermissions?: string[]
   minimumChromeVersion?: string
   firefoxMinVersion?: string
+  safariMinVersion?: string
   contentSecurityPolicy?: string
   webAccessibleResources?: Array<{ resources: string[], matches: string[] }>
   extra?: Record<string, unknown>
@@ -55,6 +56,9 @@ export declare interface ExtensionConfig {
   name: string
   description: string
   geckoId?: string
+  safariBundleId?: string
+  safariTeamId?: string
+  safariExclude?: string[]
   targets?: ExtensionTarget[]
   background?: string
   content?: ContentScript[]
@@ -84,4 +88,4 @@ export declare interface BuildOptions {
  * manifest, build graph, and packaging from it — no hand-written manifest.json
  * or per-project build script.
  */
-export type ExtensionTarget = 'chrome' | 'firefox';
+export type ExtensionTarget = 'chrome' | 'firefox' | 'safari';

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@stacksjs/browser-extension",
   "type": "module",
-  "version": "0.70.113",
-  "description": "Build MV3 browser extensions (Chrome + Firefox) the Stacks way — manifest, content/background scripts, DNR rules, packaging, all config-driven.",
+  "version": "0.70.114",
+  "description": "Build MV3 browser extensions (Chrome, Firefox, Safari) the Stacks way — manifest, content/background scripts, DNR rules, packaging, Safari container app, all config-driven.",
   "author": "Chris Breuer",
   "contributors": [
     "Chris Breuer <chris@stacksjs.com>"
@@ -22,6 +22,7 @@
     "browser-extension",
     "chrome-extension",
     "firefox-extension",
+    "safari-extension",
     "manifest-v3",
     "mv3",
     "declarativeNetRequest",
@@ -48,7 +49,8 @@
   "types": "dist/index.d.ts",
   "files": [
     "README.md",
-    "dist"
+    "dist",
+    "safari-template"
   ],
   "scripts": {
     "build": "bun build.ts",
@@ -56,6 +58,6 @@
     "prepublishOnly": "bun run build"
   },
   "devDependencies": {
-    "better-dx": "^0.2.16"
+    "better-dx": "catalog:"
   }
 }

package/safari-template/README.md

@@ -0,0 +1,63 @@
+# __APP_DISPLAY_NAME__ for Safari
+
+The macOS container app that ships the Safari Web Extension build of
+__APP_DISPLAY_NAME__. Generated by `buddy extension:safari:init`; safe to
+regenerate with `--force` (your signing settings are the only thing to redo).
+
+- `__APP_NAME__/` — the SwiftUI container app (shows extension state, opens
+  Safari's extension settings).
+- `__APP_NAME__ Extension/` — the Safari Web Extension target. Its
+  `Resources/` folder is a mirror of the safari build output, produced by
+  `buddy extension:safari:app` (or `syncSafariResources`).
+- `__APP_NAME__.xcodeproj` — checked in on purpose: building the app never
+  requires re-running Apple's `safari-web-extension-converter`.
+
+## Prerequisites
+
+- macOS with Safari 18.4+ (the manifest pins
+  `browser_specific_settings.safari.strict_min_version`).
+- Full Xcode (Command Line Tools alone are not enough):
+
+  ```bash
+  sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
+  xcodebuild -license accept   # first launch only
+  ```
+
+## Build
+
+```bash
+buddy extension:safari:app
+```
+
+This builds the extension (safari target), syncs the bundle into the appex
+Resources, and runs xcodebuild. Then launch __APP_NAME__.app once (it
+registers the extension with Safari) and enable it under
+Safari > Settings > Extensions, granting it website access.
+
+## Signing
+
+The project uses `safariTeamId` when configured and otherwise leaves
+`DEVELOPMENT_TEAM` empty so anyone can build.
+
+Local, unsigned (no Apple account): the default build uses
+`CODE_SIGNING_ALLOWED=NO`. Unsigned extensions require
+Safari > Develop > Allow Unsigned Extensions (resets on Safari updates).
+
+Signed (Apple Developer Program): select your team under Signing &
+Capabilities for both targets, then:
+
+```bash
+buddy extension:safari:app --signed            # Debug, Apple Development identity
+buddy extension:safari:app --signed --release  # Release
+```
+
+## Distribution
+
+- Mac App Store: `xcodebuild archive` (or Xcode > Product > Archive), then
+  Xcode Organizer > Distribute App > App Store Connect.
+- Developer ID + notarization: archive, export with a Developer ID profile,
+  then `xcrun notarytool submit ... --wait && xcrun stapler staple
+  __APP_NAME__.app`. The project already enables the hardened runtime.
+
+Either way, bump `MARKETING_VERSION` in the project when the extension
+releases.