@stacksjs/browser-extension 0.70.88 → 0.70.91

package/dist/build.d.ts

@@ -0,0 +1,16 @@
+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;
+/**`) + 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
+ *
+ * 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. */
+export declare function buildAllTargets(config: ExtensionConfig, options: Omit<BuildOptions, 'target'>): Promise<void>;

package/dist/build.js

@@ -0,0 +1,106 @@
+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;
+  if (typeof config.outdir === "string")
+    return config.outdir;
+  if (config.outdir?.[target])
+    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(`
+`)}`);
+  const output = result.outputs[0];
+  if (!output)
+    throw Error(`[browser-extension] build produced no output for ${entry}`);
+  await Bun.write(join(outdir, out), await output.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(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 });
+  }
+  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,
+      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((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 };
+}
+export async function buildAllTargets(config, options) {
+  for (const target of config.targets ?? ["chrome", "firefox"])
+    await buildExtension(config, { ...options, target });
+}

package/dist/config.d.ts

@@ -0,0 +1,17 @@
+import type { ExtensionConfig } from './types';
+/**
+ * Identity helper for authoring `config/extension.ts` with full type-checking
+ * and editor completion:
+ *
+ * ```ts
+ * // config/extension.ts
+ * import { defineExtension } from '@stacksjs/browser-extension'
+ * export default defineExtension({ name: 'My Extension', description: '…', … })
+ * ```
+ */
+export declare function defineExtension(config: ExtensionConfig): ExtensionConfig;
+/**
+ * Load the project's extension config from `config/extension.ts` (default
+ * export). Returns null when the project has no extension config.
+ */
+export declare function loadExtensionConfig(cwd?: string): Promise<ExtensionConfig | null>;

package/dist/config.js

@@ -0,0 +1,16 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+export function defineExtension(config) {
+  return config;
+}
+export async function loadExtensionConfig(cwd = process.cwd()) {
+  for (const rel of ["config/extension.ts", "extension.config.ts"]) {
+    const path = resolve(cwd, rel);
+    if (!existsSync(path))
+      continue;
+    const mod = await import(path), config = mod.default ?? mod.extension ?? mod.config;
+    if (config)
+      return config;
+  }
+  return null;
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @stacksjs/browser-extension
+ *
+ * Build MV3 browser extensions (Chrome + Firefox) 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.
+ */
+export * from './build';
+export * from './config';
+export * from './manifest';
+export * from './package';
+export * from './sanitize';
+export * from './types';

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from "./build";
+export * from "./config";
+export * from "./manifest";
+export * from "./package";
+export * from "./sanitize";
+export * from "./types";

package/dist/manifest.d.ts

@@ -0,0 +1,45 @@
+import type { ExtensionConfig, ExtensionTarget } from './types';
+/** Output filename for a content script (explicit `out`, else entry basename). */
+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).
+ */
+export declare function generateManifest(config: ExtensionConfig, opts: { version: string, target?: ExtensionTarget }): GeneratedManifest;
+/** MV3 manifest shape (loose — the two targets diverge on `background`). */
+export declare interface GeneratedManifest {
+  manifest_version: 3
+  name: string
+  description: string
+  version: string
+  minimum_chrome_version?: string
+  action?: { default_title?: string, default_popup?: string }
+  options_page?: string
+  background?: { service_worker: string, type?: 'module' } | { scripts: string[], type?: 'module' }
+  browser_specific_settings?: {
+    gecko: {
+      id: string
+      strict_min_version: string
+      data_collection_permissions: { required: ['none'] }
+    }
+  }
+  permissions?: string[]
+  optional_permissions?: string[]
+  host_permissions?: string[]
+  icons?: Record<string, string>
+  content_scripts?: Array<{
+    matches: string[]
+    js: string[]
+    css?: string[]
+    run_at?: string
+    world?: string
+    all_frames?: boolean
+    match_about_blank?: boolean
+    exclude_matches?: string[]
+  }>
+  declarative_net_request?: { rule_resources: Array<{ id: string, enabled: boolean, path: string }> }
+  content_security_policy?: { extension_pages: string }
+  web_accessible_resources?: Array<{ resources: string[], matches: string[] }>
+  [key: string]: unknown
+}

package/dist/manifest.js

@@ -0,0 +1,60 @@
+import { basename } from "node:path";
+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 = {
+    manifest_version: 3,
+    name: config.name,
+    description: config.description,
+    version: opts.version
+  };
+  if (!isFirefox && 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" };
+  if (isFirefox && config.geckoId)
+    manifest.browser_specific_settings = {
+      gecko: {
+        id: config.geckoId,
+        strict_min_version: m.firefoxMinVersion ?? "128.0",
+        data_collection_permissions: { required: ["none"] }
+      }
+    };
+  if (m.permissions?.length)
+    manifest.permissions = m.permissions;
+  if (m.optionalPermissions?.length)
+    manifest.optional_permissions = m.optionalPermissions;
+  if (m.hostPermissions?.length)
+    manifest.host_permissions = m.hostPermissions;
+  if (config.icons)
+    manifest.icons = Object.fromEntries(Object.entries(config.icons).map(([size, path]) => [String(size), path]));
+  if (config.content?.length)
+    manifest.content_scripts = config.content.map((cs) => ({
+      matches: cs.matches,
+      js: [contentScriptOut(cs.entry, cs.out)],
+      ...cs.runAt ? { run_at: cs.runAt } : {},
+      ...cs.world ? { world: cs.world } : {},
+      ...cs.allFrames ? { all_frames: !0 } : {},
+      ...cs.matchAboutBlank ? { match_about_blank: !0 } : {},
+      ...cs.excludeMatches ? { exclude_matches: cs.excludeMatches } : {}
+    }));
+  if (config.rules?.length)
+    manifest.declarative_net_request = {
+      rule_resources: config.rules.map((r) => ({
+        id: r.id,
+        enabled: r.enabled ?? !0,
+        path: r.path ?? `rules/${r.id}.json`
+      }))
+    };
+  manifest.content_security_policy = {
+    extension_pages: m.contentSecurityPolicy ?? "script-src 'self'; object-src 'self'"
+  };
+  if (m.webAccessibleResources?.length)
+    manifest.web_accessible_resources = m.webAccessibleResources;
+  return { ...manifest, ...m.extra ?? {} };
+}

package/dist/package.d.ts

@@ -0,0 +1,15 @@
+import type { ExtensionConfig, ExtensionTarget } from './types';
+/**
+ * Package a built extension into a store-ready `.zip` (one per target). Builds
+ * first unless `build: false`. Uses the system `zip` (available on CI runners
+ * and dev machines) so the archive matches what the Chrome/Firefox stores
+ * expect (files at the archive root, no wrapping directory).
+ */
+export declare function packageExtension(config: ExtensionConfig, options: PackageOptions): Promise<string>;
+export declare interface PackageOptions {
+  target?: ExtensionTarget
+  version: string
+  cwd?: string
+  outfile?: string
+  build?: boolean
+}

package/dist/package.js

@@ -0,0 +1,21 @@
+import { existsSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { buildExtension, resolveOutdir } from "./build";
+function slug(name) {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
+}
+export async function packageExtension(config, options) {
+  const target = options.target ?? "chrome", cwd = options.cwd ?? process.cwd();
+  if (options.build !== !1)
+    await buildExtension(config, { target, version: options.version, cwd });
+  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`);
+  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)
+    throw Error(`[browser-extension] zip failed (${code}): ${await new Response(proc.stderr).text()}`);
+  return outfile;
+}

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

@@ -0,0 +1,87 @@
+/** A content script mapped into the manifest's `content_scripts`. */
+export declare interface ContentScript {
+  entry: string
+  out?: string
+  matches: string[]
+  runAt?: 'document_start' | 'document_end' | 'document_idle'
+  world?: 'ISOLATED' | 'MAIN'
+  allFrames?: boolean
+  matchAboutBlank?: boolean
+  excludeMatches?: string[]
+}
+/**
+ * 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
+}
+/** stx pages bundled to HTML (popup, options, …). A bare string = template only. */
+export declare interface ExtensionPages {
+  popup?: string | ExtensionPage
+  options?: string | ExtensionPage
+  extra?: Record<string, string | ExtensionPage>
+}
+/** Overrides merged verbatim into the generated manifest, per target. */
+export declare interface ManifestOverrides {
+  permissions?: string[]
+  hostPermissions?: string[]
+  optionalPermissions?: string[]
+  minimumChromeVersion?: string
+  firefoxMinVersion?: string
+  contentSecurityPolicy?: string
+  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
+  geckoId?: string
+  targets?: ExtensionTarget[]
+  background?: string
+  content?: ContentScript[]
+  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
+  version: string
+  outdir?: string
+  minify?: boolean
+  cwd?: string
+}
+/**
+ * Config-driven MV3 browser-extension types.
+ *
+ * A consuming app declares one `ExtensionConfig` (typically in
+ * `config/extension.ts` via `defineExtension`) and the framework derives the
+ * manifest, build graph, and packaging from it — no hand-written manifest.json
+ * or per-project build script.
+ */
+export type ExtensionTarget = 'chrome' | 'firefox';

package/package.json

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