@stacksjs/browser-extension 0.70.67 → 0.70.69

package/README.md

@@ -1,3 +1,77 @@
 # @stacksjs/browser-extension
 
-Build MV3 browser extensions (Chrome + Firefox) the Stacks way — manifest, content/background scripts, DNR rules, and packaging, all driven by a single `config/extension.ts`.
+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.
+
+## Quick start
+
+```sh
+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:package       # build + zip store-ready archives
+```
+
+## Configure
+
+```ts
+// config/extension.ts
+import { defineExtension } from '@stacksjs/browser-extension'
+
+export default defineExtension({
+  name: 'My Extension',
+  description: 'Does something useful.',
+  geckoId: 'my-ext@example.com',      // required to ship on Firefox
+  targets: ['chrome', 'firefox'],
+
+  background: 'src/background/index.ts',
+  content: [
+    { entry: 'src/content/index.ts', matches: ['<all_urls>'], runAt: 'document_start' },
+    // world: 'MAIN' runs in the page's own JS context (patch page globals)
+    { entry: 'src/content/inpage.ts', matches: ['*://example.com/*'], world: 'MAIN' },
+  ],
+  pages: {
+    popup: { template: 'pages/popup.stx', script: 'src/ui/popup.ts' },
+    options: { template: 'pages/options.stx', script: 'src/ui/options.ts' },
+  },
+  icons: { 16: 'icons/icon-16.png', 48: 'icons/icon-48.png', 128: 'icons/icon-128.png' },
+  public: 'public',                    // copied verbatim into the build
+  assets: { 'styles.css': 'src/ui/styles.css' }, // extra file copies
+
+  // declarativeNetRequest — compiled from a module whose default export
+  // returns the rules array, written to rules/<id>.json:
+  rules: [{ id: 'static_rules', source: 'src/rules/static.ts' }],
+
+  manifest: {
+    permissions: ['declarativeNetRequest', 'storage', 'tabs'],
+    hostPermissions: ['http://*/*', 'https://*/*'],
+    minimumChromeVersion: '111',
+    firefoxMinVersion: '140.0',
+    webAccessibleResources: [{ resources: ['stubs/*.js'], matches: ['<all_urls>'] }],
+  },
+
+  // App-specific post-processing the generic build can't express:
+  hooks: {
+    async postBuild({ outdir, target }) { /* … */ },
+  },
+})
+```
+
+## What the build does
+
+Per target it: copies `public/**` + `assets`, bundles page scripts, builds the
+stx pages to HTML (**sanitized for the extension CSP** — inline scripts/styles
+stripped, asset paths made relative, stx dev-chunks removed), bundles
+content/background scripts as classic **IIFE** bundles (esm would leak
+top-level vars as page globals), compiles each ruleset's `source` to
+`rules/<id>.json`, writes `manifest.json` (per-target: Chrome `service_worker`
+vs Firefox event-page + `browser_specific_settings.gecko`), and runs your
+`hooks.postBuild`.
+
+## Programmatic API
+
+```ts
+import { buildExtension, buildAllTargets, packageExtension, generateManifest } from '@stacksjs/browser-extension'
+```

package/dist/build.d.ts

@@ -1,15 +1,15 @@
 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;
-/**
- * Build a browser extension for one target: bundle stx pages → HTML, content +
- * background scripts → classic IIFE bundles, copy static assets, and write the
- * generated manifest.json. Mirrors the hand-rolled build-extension.ts every
- * extension used to carry, now driven purely by `ExtensionConfig`.
+/**`) + extra `assets` copied in
+ * - stx pages → `<name>.html` (+ companion `<name>.js`), sanitized for the
+ *   extension CSP, with stx dev chunks removed
+ * - content + background scripts → classic IIFE bundles
+ * - declarativeNetRequest rulesets compiled from their `source` modules
+ * - `manifest.json` generated per target
+ * - the app's `hooks.postBuild` run last
  *
- * The stx page bundling is delegated to `bun-plugin-stx` (loaded lazily so the
- * package doesn't hard-depend on it when only the manifest/packaging APIs are
- * used).
+ * Replaces the hand-rolled `build-extension.ts` every extension used to carry.
  */
 export declare function buildExtension(config: ExtensionConfig, options: BuildOptions): Promise<{ outdir: string, target: ExtensionTarget }>;
 /** Build every configured target. */

package/dist/build.js

@@ -1,7 +1,9 @@
+import { Glob } from "bun";
 import { cp, mkdir, rm } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { contentScriptOut, generateManifest } from "./manifest";
+import { sanitizeExtensionHtml } from "./sanitize";
 export function resolveOutdir(config, target, override) {
   if (override)
     return override;
@@ -11,53 +13,90 @@ export function resolveOutdir(config, target, override) {
     return config.outdir[target];
   return target === "firefox" ? "dist-firefox" : "dist";
 }
+function normalizePage(page) {
+  return typeof page === "string" ? { template: page } : page;
+}
+function pageEntries(pages) {
+  if (!pages)
+    return [];
+  const out = [];
+  if (pages.popup)
+    out.push({ name: "popup", page: normalizePage(pages.popup) });
+  if (pages.options)
+    out.push({ name: "options", page: normalizePage(pages.options) });
+  for (const [name, page] of Object.entries(pages.extra ?? {}))
+    out.push({ name, page: normalizePage(page) });
+  return out;
+}
+async function buildScript(entry, out, outdir, cwd, minify) {
+  const result = await Bun.build({
+    entrypoints: [resolve(cwd, entry)],
+    target: "browser",
+    format: "iife",
+    splitting: !1,
+    minify
+  });
+  if (!result.success)
+    throw Error(`[browser-extension] failed to build ${entry}: ${result.logs.join(`
+`)}`);
+  await Bun.write(join(outdir, out), await result.outputs[0].text());
+}
 export async function buildExtension(config, options) {
   const target = options.target ?? "chrome", cwd = options.cwd ?? process.cwd(), outdir = resolve(cwd, resolveOutdir(config, target, options.outdir)), minify = options.minify ?? !0;
   await rm(outdir, { recursive: !0, force: !0 });
-  await mkdir(outdir, { recursive: !0 });
+  await mkdir(join(outdir, "rules"), { recursive: !0 });
+  await mkdir(join(outdir, "icons"), { recursive: !0 });
   if (config.public) {
     const pub = resolve(cwd, config.public);
     if (existsSync(pub))
       await cp(pub, outdir, { recursive: !0 });
   }
-  const pageEntries = collectPages(config, cwd);
-  if (pageEntries.length) {
-    const { default: stxPlugin } = await import("bun-plugin-stx");
-    await Bun.build({
-      entrypoints: pageEntries,
+  for (const [dest, src] of Object.entries(config.assets ?? {})) {
+    const s = resolve(cwd, src);
+    if (existsSync(s))
+      await Bun.write(join(outdir, dest), Bun.file(s));
+  }
+  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({
+      entrypoints: pages.map((p) => resolve(cwd, p.page.template)),
       outdir,
-      target: "browser",
       minify,
+      naming: { entry: "[name].html" },
       plugins: [stxPlugin()]
     });
+    if (!result.success)
+      throw Error(`[browser-extension] failed to build pages: ${result.logs.join(`
+`)}`);
+    for (const { name, page } of pages) {
+      const file = join(outdir, `${name}.html`);
+      if (!existsSync(file))
+        continue;
+      const own = page.script ? [`${name}.js`] : [];
+      await Bun.write(file, sanitizeExtensionHtml(await Bun.file(file).text(), own));
+    }
+    for await (const chunk of new Glob("chunk-*.js").scan(outdir))
+      await rm(join(outdir, chunk), { force: !0 });
   }
   const scripts = [];
   if (config.background)
     scripts.push({ entry: config.background, out: "background.js" });
   for (const cs of config.content ?? [])
     scripts.push({ entry: cs.entry, out: contentScriptOut(cs.entry, cs.out) });
-  await Promise.all(scripts.map(async ({ entry, out }) => {
-    const result = await Bun.build({
-      entrypoints: [resolve(cwd, entry)],
-      target: "browser",
-      format: "iife",
-      minify
-    });
-    if (!result.success)
-      throw Error(`[browser-extension] failed to build ${entry}: ${result.logs.join(`
-`)}`);
-    await Bun.write(join(outdir, out), await result.outputs[0].text());
-  }));
+  await Promise.all(scripts.map((s) => buildScript(s.entry, s.out, outdir, cwd, minify)));
+  for (const rule of config.rules ?? []) {
+    if (!rule.source)
+      continue;
+    const mod = await import(resolve(cwd, rule.source)), build = mod.default ?? mod.buildRules ?? mod.rules ?? Object.values(mod).find((v) => typeof v === "function") ?? Object.values(mod).find((v) => Array.isArray(v)), data = typeof build === "function" ? await build() : build;
+    await Bun.write(join(outdir, rule.path ?? `rules/${rule.id}.json`), `${JSON.stringify(data, null, 2)}
+`);
+  }
   await Bun.write(join(outdir, "manifest.json"), `${JSON.stringify(generateManifest(config, { version: options.version, target }), null, 2)}
 `);
+  await config.hooks?.postBuild?.({ config, target, outdir, version: options.version, cwd });
   return { outdir, target };
 }
-function collectPages(config, cwd) {
-  const p = config.pages;
-  if (!p)
-    return [];
-  return [p.popup, p.options, ...Object.values(p.extra ?? {})].filter(Boolean).map((e) => resolve(cwd, e));
-}
 export async function buildAllTargets(config, options) {
   for (const target of config.targets ?? ["chrome", "firefox"])
     await buildExtension(config, { ...options, target });

package/dist/index.d.ts

@@ -10,4 +10,5 @@ export * from './build';
 export * from './config';
 export * from './manifest';
 export * from './package';
+export * from './sanitize';
 export * from './types';

package/dist/index.js

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

package/dist/sanitize.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Sanitize an stx-built page for use as an extension page.
+ *
+ * MV3 extension pages run under a strict CSP (`script-src 'self'`) — no inline
+ * `<script>` or `<style>`, and asset URLs must be relative (the page loads from
+ * `chrome-extension://…/<name>.html`, not a web root). stx emits dev niceties
+ * (SEO meta, an inline style block, an inline hydration script) and absolute
+ * `/asset` paths, so strip/rewrite them, keeping only the page's own compiled
+ * script(s).
+ */
+export declare function sanitizeExtensionHtml(html: string, ownScripts: string[]): string;

package/dist/sanitize.js

@@ -0,0 +1,7 @@
+export function sanitizeExtensionHtml(html, ownScripts) {
+  const keep = ownScripts.map((s) => `(?![^>]*src="/?${s.replace(".", "\\.")}")`).join("");
+  let out = html.replace(/\n?<!-- stx SEO Tags -->[\s\S]*?(?=\n\s*<meta charset=)/, "").replace(/\n?\s*<style\b[\s\S]*?<\/style>/g, "").replace(new RegExp(`\\n?\\s*<script\\b${keep}[\\s\\S]*?<\\/script>`, "g"), "").replaceAll('href="/styles.css"', 'href="styles.css"').replaceAll('href="/icons/', 'href="icons/');
+  for (const s of ownScripts)
+    out = out.replaceAll(`src="/${s}"`, `src="${s}"`);
+  return out;
+}

package/dist/types.d.ts

@@ -9,17 +9,28 @@ export declare interface ContentScript {
   matchAboutBlank?: boolean
   excludeMatches?: string[]
 }
-/** A declarativeNetRequest static ruleset. */
+/**
+ * A declarativeNetRequest static ruleset. Either point `path` at a pre-built
+ * JSON file, or give `source` — a module whose default export is a function (or
+ * value) producing the rules array, which the build compiles to
+ * `rules/<id>.json`.
+ */
 export declare interface RuleResource {
   id: string
   path?: string
   enabled?: boolean
+  source?: string
+}
+/** An extension page: an stx template + an optional companion script. */
+export declare interface ExtensionPage {
+  template: string
+  script?: string
 }
-/** An stx page bundled to HTML (popup, options, …). */
+/** stx pages bundled to HTML (popup, options, …). A bare string = template only. */
 export declare interface ExtensionPages {
-  popup?: string
-  options?: string
-  extra?: Record<string, string>
+  popup?: string | ExtensionPage
+  options?: string | ExtensionPage
+  extra?: Record<string, string | ExtensionPage>
 }
 /** Overrides merged verbatim into the generated manifest, per target. */
 export declare interface ManifestOverrides {
@@ -32,6 +43,14 @@ export declare interface ManifestOverrides {
   webAccessibleResources?: Array<{ resources: string[], matches: string[] }>
   extra?: Record<string, unknown>
 }
+/** Context passed to build hooks. */
+export declare interface BuildContext {
+  config: ExtensionConfig
+  target: ExtensionTarget
+  outdir: string
+  version: string
+  cwd: string
+}
 export declare interface ExtensionConfig {
   name: string
   description: string
@@ -42,9 +61,13 @@ export declare interface ExtensionConfig {
   pages?: ExtensionPages
   icons?: Record<number, string>
   public?: string
+  assets?: Record<string, string>
   rules?: RuleResource[]
   manifest?: ManifestOverrides
   outdir?: Partial<Record<ExtensionTarget, string>> | string
+  hooks?: {
+    postBuild?: (ctx: BuildContext) => void | Promise<void>
+  }
 }
 export declare interface BuildOptions {
   target?: ExtensionTarget

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/browser-extension",
   "type": "module",
-  "version": "0.70.67",
+  "version": "0.70.69",
   "description": "Build MV3 browser extensions (Chrome + Firefox) the Stacks way — manifest, content/background scripts, DNR rules, packaging, all config-driven.",
   "author": "Chris Breuer",
   "contributors": [