@stacksjs/browser-extension 0.70.148 → 0.70.150

package/README.md

@@ -11,13 +11,24 @@ packaging owned by the framework.
 ## Quick start
 
 ```sh
-buddy extension:init          # scaffold config/extension.ts + starter files
+buddy extension:init          # scaffold Chrome + Firefox + Safari, including the Xcode app
+buddy extension:init --target safari --name "My Extension" --bundle-id com.example.MyExtension
 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
 ```
 
+Use `icons` for full-color store/app branding and `actionIcons` for separate,
+usually neutral artwork in the browser toolbar:
+
+```ts
+defineExtension({
+  icons: { 16: 'icons/icon-16.png', 128: 'icons/icon-128.png' },
+  actionIcons: { 16: 'icons/toolbar-16.png', 32: 'icons/toolbar-32.png' },
+})
+```
+
 ## Store publishing
 
 Stacks owns the store-specific upload clients as well as the builds. Chrome

package/dist/build.js

@@ -69,12 +69,12 @@ export async function buildExtension(config, options) {
   const pages = pageEntries(config.pages);
   await Promise.all(pages.filter((p) => p.page.script).map((p) => buildScript(p.page.script, `${p.name}.js`, outdir, cwd, minify)));
   if (pages.length) {
-    const { default: stxPlugin } = await import("bun-plugin-stx"), result = await Bun.build({
+    const { default: stxPlugin } = await import("bun-plugin-stx"), resourcesPartials = resolve(cwd, "resources/partials"), legacyPartials = resolve(cwd, "partials"), partialsDir = existsSync(resourcesPartials) ? resourcesPartials : legacyPartials, result = await Bun.build({
       entrypoints: pages.map((p) => resolve(cwd, p.page.template)),
       outdir,
       minify,
       naming: { entry: "[name].html" },
-      plugins: [stxPlugin()]
+      plugins: [stxPlugin({ partialsDir })]
     });
     if (!result.success)
       throw Error(`[browser-extension] failed to build pages: ${result.logs.join(`

package/dist/index.d.ts

@@ -16,5 +16,6 @@ export * from './firefox-addons';
 export * from './manifest';
 export * from './package';
 export * from './safari';
+export * from './scaffold';
 export * from './sanitize';
 export * from './types';

package/dist/index.js

@@ -7,5 +7,6 @@ export * from "./firefox-addons";
 export * from "./manifest";
 export * from "./package";
 export * from "./safari";
+export * from "./scaffold";
 export * from "./sanitize";
 export * from "./types";

package/dist/manifest.d.ts

@@ -17,7 +17,7 @@ export declare interface GeneratedManifest {
   description: string
   version: string
   minimum_chrome_version?: string
-  action?: { default_title?: string, default_popup?: string }
+  action?: { default_title?: string, default_popup?: string, default_icon?: Record<string, string> }
   options_page?: string
   background?: { service_worker: string, type?: 'module' } | { scripts: string[], type?: 'module' }
   browser_specific_settings?: {

package/dist/manifest.js

@@ -11,8 +11,12 @@ export function generateManifest(config, opts) {
   };
   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?.popup || config.actionIcons)
+    manifest.action = {
+      default_title: config.name,
+      ...config.pages?.popup ? { default_popup: "popup.html" } : {},
+      ...config.actionIcons ? { default_icon: Object.fromEntries(Object.entries(config.actionIcons).map(([size, path]) => [String(size), path])) } : {}
+    };
   if (config.pages?.options)
     manifest.options_page = "options.html";
   if (config.background)

package/dist/scaffold.d.ts

@@ -0,0 +1,22 @@
+import { scaffoldSafariApp } from './safari';
+import type { ExtensionConfig, ExtensionTarget, SafariPlatform } from './types';
+export declare function resolveExtensionScaffoldTargets(target?: ExtensionScaffoldTarget): ExtensionTarget[];
+/** Scaffold a complete cross-browser extension, including Safari's container app. */
+export declare function scaffoldExtensionProject(options?: ExtensionProjectScaffoldOptions): Promise<ExtensionProjectScaffoldResult>;
+export declare interface ExtensionProjectScaffoldOptions {
+  cwd?: string
+  name?: string
+  target?: ExtensionScaffoldTarget
+  bundleId?: string
+  teamId?: string
+  platforms?: SafariPlatform[]
+  version?: string
+  force?: boolean
+}
+export declare interface ExtensionProjectScaffoldResult {
+  config: ExtensionConfig
+  written: string[]
+  skipped: string[]
+  safari?: Awaited<ReturnType<typeof scaffoldSafariApp>>
+}
+export type ExtensionScaffoldTarget = ExtensionTarget | 'all';

package/dist/scaffold.js

@@ -0,0 +1,92 @@
+import { existsSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import process from "node:process";
+import { scaffoldSafariApp } from "./safari";
+export function resolveExtensionScaffoldTargets(target = "all") {
+  return target === "all" ? ["chrome", "firefox", "safari"] : [target];
+}
+function safariAppName(name) {
+  return name.replace(/[^A-Za-z0-9]/g, "") || "MyExtension";
+}
+function quotedList(values) {
+  return `[${values.map((value) => `'${value}'`).join(", ")}]`;
+}
+function extensionConfigSource(config) {
+  const safari = config.targets?.includes("safari") ? `
+  safariBundleId: '${config.safariBundleId}',
+  safariPlatforms: ${quotedList(config.safariPlatforms ?? ["macos", "ios"])},
+  safariAppCategory: 'public.app-category.utilities',${config.safariTeamId ? `
+  safariTeamId: '${config.safariTeamId}',` : ""}` : "", firefox = config.targets?.includes("firefox") ? `
+  // Replace this before publishing to Mozilla Add-ons.
+  geckoId: 'extension@example.com',` : "";
+  return `import { defineExtension } from '@stacksjs/browser-extension'
+
+export default defineExtension({
+  name: ${JSON.stringify(config.name)},
+  description: 'A browser extension built with Stacks.',
+  targets: ${quotedList(config.targets ?? [])},${firefox}${safari}
+  background: 'src/background/index.ts',
+  content: [
+    { entry: 'src/content/index.ts', matches: ['<all_urls>'], runAt: 'document_start' },
+  ],
+  pages: {
+    popup: { template: 'resources/views/popup.stx', script: 'resources/scripts/popup.ts' },
+  },
+  public: 'public',
+  manifest: {
+    permissions: ['storage', 'tabs'],
+  },
+})
+`;
+}
+export async function scaffoldExtensionProject(options = {}) {
+  const cwd = options.cwd ?? process.cwd(), name = options.name ?? "My Extension", targets = resolveExtensionScaffoldTargets(options.target), appName = safariAppName(name), config = {
+    name,
+    description: "A browser extension built with Stacks.",
+    targets,
+    background: "src/background/index.ts",
+    content: [{ entry: "src/content/index.ts", matches: ["<all_urls>"], runAt: "document_start" }],
+    pages: { popup: { template: "resources/views/popup.stx", script: "resources/scripts/popup.ts" } },
+    public: "public",
+    manifest: { permissions: ["storage", "tabs"] },
+    ...targets.includes("firefox") && { geckoId: "extension@example.com" },
+    ...targets.includes("safari") && {
+      safariBundleId: options.bundleId ?? `com.example.${appName}`,
+      safariTeamId: options.teamId,
+      safariPlatforms: options.platforms ?? ["macos", "ios"],
+      safariAppCategory: "public.app-category.utilities"
+    }
+  }, written = [], skipped = [], write = async (relative, content) => {
+    const absolute = join(cwd, relative);
+    if (existsSync(absolute) && !options.force) {
+      skipped.push(relative);
+      return;
+    }
+    await mkdir(dirname(absolute), { recursive: !0 });
+    await Bun.write(absolute, content);
+    written.push(relative);
+  };
+  await write("config/extension.ts", extensionConfigSource(config));
+  await write("src/background/index.ts", `console.log(${JSON.stringify(`[${name}] background ready`)})
+`);
+  await write("src/content/index.ts", `console.log(${JSON.stringify(`[${name}] content script loaded`)})
+`);
+  await write("resources/scripts/popup.ts", `console.log(${JSON.stringify(`[${name}] popup ready`)})
+`);
+  await write("resources/views/popup.stx", `<main class="popup">
+  <h1>${name}</h1>
+  <p>Edit resources/views/popup.stx to build your popup.</p>
+  <script src="/popup.js"></script>
+</main>
+`);
+  await mkdir(join(cwd, "public"), { recursive: !0 });
+  const safari = targets.includes("safari") ? await scaffoldSafariApp(config, {
+    cwd,
+    bundleId: config.safariBundleId,
+    teamId: config.safariTeamId,
+    version: options.version,
+    force: options.force
+  }) : void 0;
+  return { config, written, skipped, safari };
+}

package/dist/types.d.ts

@@ -144,6 +144,7 @@ export declare interface ExtensionConfig {
   content?: ContentScript[]
   pages?: ExtensionPages
   icons?: Record<number, string>
+  actionIcons?: Record<number, string>
   public?: string
   assets?: Record<string, string>
   rules?: RuleResource[]

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/browser-extension",
   "type": "module",
-  "version": "0.70.148",
+  "version": "0.70.150",
   "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": [