@gjsify/cli 0.52.0 → 0.53.0

package/lib/utils/run-gjs.js

@@ -21,12 +21,20 @@ import { captureNativeBacktrace, createHangWatchdog, formatHangReport, hangGrace
  * variable is set is host-dependent (`LD_LIBRARY_PATH` / `DYLD_LIBRARY_PATH` / `PATH`) — see
  * `buildNativeEnv`.
  */
-export function computeNativeEnvForBundle(bundlePath, cwd = process.cwd(), inherited = process.env) {
+export function computeNativeEnvForBundle(bundlePath, cwd = process.cwd(), inherited = process.env, extraRoots = []) {
     const resolvedBundle = resolve(bundlePath);
-    const cwdPackages = detectNativePackages(cwd);
-    const bundlePackages = detectNativePackages(dirname(resolvedBundle));
-    const seen = new Set(cwdPackages.map((p) => p.name));
-    const nativePackages = [...cwdPackages, ...bundlePackages.filter((p) => !seen.has(p.name))];
+    // First root wins per package name: the project, then the bundle's own tree, then
+    // whatever the caller adds (see `RunGjsBundleOptions.nativeRoots`).
+    const nativePackages = [];
+    const seen = new Set();
+    for (const root of [cwd, dirname(resolvedBundle), ...extraRoots]) {
+        for (const pkg of detectNativePackages(root)) {
+            if (seen.has(pkg.name))
+                continue;
+            seen.add(pkg.name);
+            nativePackages.push(pkg);
+        }
+    }
     // `inherited` feeds BOTH halves — composition and comparison. Split them and the win32
     // branch disagrees with itself: `buildNativeEnv` writes the library variable back under
     // the host's own spelling (`Path` in a stock env block), so a comparison keyed on the
@@ -58,7 +66,7 @@ function safeMkdtemp() {
     }
 }
 export async function runGjsBundle(bundlePath, extraArgs = [], options) {
-    const { env: nativeEnv, envPrefix } = computeNativeEnvForBundle(bundlePath);
+    const { env: nativeEnv, envPrefix } = computeNativeEnvForBundle(bundlePath, process.cwd(), process.env, options.nativeRoots);
     // The breadcrumb `@gjsify/unit` writes what it is running into, and this process polls —
     // the only way a bundle that has stopped turning its main loop can still say which test it
     // died in. Anything that is not a unit run never writes the file, so the watchdog stays
@@ -149,7 +157,8 @@ export async function runGjsBundle(bundlePath, extraArgs = [], options) {
     if (hung)
         return failed(result.code ?? 1);
     if (result.code !== 0) {
-        console.error(`gjs exited with ${describeExit(result)}`);
+        if (!options.quietExit)
+            console.error(`gjs exited with ${describeExit(result)}`);
         return failed(result.code ?? 1);
     }
     // See RunGjsBundleOptions.exitOnSuccess — terminal callers opt in,

package/lib/utils/run-node.d.ts

@@ -26,6 +26,8 @@ export interface RunNodeBundleOptions {
     exitOnSuccess?: boolean;
     /** Suppress the `$ <env> node …` echo — see `RunGjsBundleOptions.quiet`. */
     quiet?: boolean;
+    /** Leave a failing child's output alone — see `RunGjsBundleOptions.quietExit`. */
+    quietExit?: boolean;
 }
 /**
  * Run a `--app node` bundle on Node.js with the native typelib env set (same detection as

package/lib/utils/run-node.js

@@ -148,7 +148,8 @@ export async function runRuntimeBundle(runtime, bundlePath, extraArgs = [], opti
         return failed(1);
     }
     if (result.code !== 0) {
-        console.error(`${runtime} exited with ${describeExit(result)}`);
+        if (!options.quietExit)
+            console.error(`${runtime} exited with ${describeExit(result)}`);
         return failed(result.code ?? 1);
     }
     if (options.exitOnSuccess)

package/lib/utils/runtimes.js

@@ -6,13 +6,14 @@
 // runtime→build-target mapping and `availableRuntimes()` live in ONE place instead
 // of a per-example copy.
 //
-// Intentionally PURE (only `node:child_process` and the side-effect-free
-// `@gjsify/rolldown-plugin-gjsify/runtime` host detector, no `gi://` or native
-// imports) so an external example can deep-import it from the installed CLI
-// (`@gjsify/cli/lib/utils/runtimes.js`) without pulling in the whole bundler — the
-// same deep-import precedent as `@gjsify/cli/lib/utils/run-gjs.js`.
-import { execFileSync } from 'node:child_process';
+// Intentionally PURE (only `node:child_process`, `./spawn.js`'s Windows command
+// rewrite and the side-effect-free `@gjsify/rolldown-plugin-gjsify/runtime` host
+// detector, no `gi://` or native imports) so an external example can deep-import
+// it from the installed CLI (`@gjsify/cli/lib/utils/runtimes.js`) without pulling
+// in the whole bundler — the same deep-import precedent as `@gjsify/cli/lib/utils/run-gjs.js`.
+import { spawnSync } from 'node:child_process';
 import { hostRuntime } from '@gjsify/rolldown-plugin-gjsify/runtime';
+import { toSpawnable } from './spawn.js';
 /** All runtimes, in canonical order (gjs first — it is the reference). */
 export const EXAMPLE_RUNTIMES = ['gjs', 'node', 'bun', 'deno'];
 /**
@@ -57,13 +58,13 @@ export function requiresGjsSystemDeps(runtime) {
 }
 /** Whether `<probe> --version` succeeds (i.e. the runtime binary is on PATH). */
 export function isRuntimeOnPath(probe) {
-    try {
-        execFileSync(probe, ['--version'], { stdio: 'ignore', timeout: 15000 });
-        return true;
-    }
-    catch {
-        return false;
-    }
+    const inv = toSpawnable(probe, ['--version']);
+    const r = spawnSync(inv.cmd, inv.args, {
+        stdio: 'ignore',
+        timeout: 15000,
+        windowsVerbatimArguments: inv.windowsVerbatimArguments,
+    });
+    return !r.error && r.status === 0;
 }
 /**
  * Whether a specific runtime is runnable here. The HOST runtime needs no PATH probe

package/lib/utils/ship/gzip.js

@@ -26,7 +26,7 @@
 //     asked for only where a reader demands it (see below) and not blanket-applied
 //     to the payload tarballs.
 //
-// Ledgered in `status/open-todos.md`; closing it means pinning ONE deflate
+// Ledgered in `status/open-todos/README.md`; closing it means pinning ONE deflate
 // implementation, which is a larger decision than this file.
 import { gzip } from '@gjsify/tar';
 /**

package/lib/utils/ship/icons.d.ts

@@ -157,6 +157,12 @@ export interface RasterizeInput {
      * alone passes just as well when nobody wires it in.
      */
     spawn?: typeof spawnToCompletion;
+    /**
+     * The command a refusal names (default `gjsify ship`). `gjsify webext` renders
+     * its toolbar icons through the same child, and a message blaming `ship`
+     * would send its reader to the wrong command's documentation.
+     */
+    command?: string;
 }
 /**
  * Render an SVG at every size through librsvg, in a child GJS.

package/lib/utils/ship/icons.js

@@ -267,6 +267,7 @@ export function rasterizerEnv(opts = {}) {
 export async function rasterizeSvg(input) {
     if (input.sizes.length === 0)
         return new Map();
+    const command = input.command ?? 'gjsify ship';
     // THE CLI'S OWN SPAWN WRAPPER, not `promisify(execFile)`. Measured under the
     // GJS-built CLI (`dist/cli.gjs.mjs`, gjs 1.88): `node:util`'s `promisify` over
     // `@gjsify/child_process`'s `execFile` resolves with the bare stdout string —
@@ -285,7 +286,7 @@ export async function rasterizeSvg(input) {
         // A 1024 px PNG of a detailed icon is a few hundred kilobytes; base64 adds
         // a third. Node's default 1 MiB is within reach of one large element.
         maxBuffer: 64 * 1024 * 1024,
-        notFound: () => new Error(`gjsify ship: \`${RASTERIZER}\` is not on PATH, and it is what renders ${input.svg} into the ` +
+        notFound: () => new Error(`${command}: \`${RASTERIZER}\` is not on PATH, and it is what renders ${input.svg} into the ` +
             `sizes an icon needs on this OS. ${RASTERIZER_HINT}.`),
     });
     const stdout = result.stdout ?? '';
@@ -296,7 +297,7 @@ export async function rasterizeSvg(input) {
         const hint = /Rsvg|Typelib|cairo/i.test(stderr)
             ? ` The Rsvg typelib or GJS's cairo binding is missing. ${RASTERIZER_HINT}.`
             : '';
-        throw new Error(`gjsify ship: rendering ${input.svg} through ${RASTERIZER} failed (exit ${result.code ?? result.signal}).` +
+        throw new Error(`${command}: rendering ${input.svg} through ${RASTERIZER} failed (exit ${result.code ?? result.signal}).` +
             `${hint}${stderr === '' ? '' : `\n    ${stderr.split('\n').join('\n    ')}`}`);
     }
     let parsed;
@@ -304,19 +305,19 @@ export async function rasterizeSvg(input) {
         parsed = JSON.parse(stdout);
     }
     catch {
-        throw new Error(`gjsify ship: ${RASTERIZER} printed something other than the rendered icon while rendering ` +
+        throw new Error(`${command}: ${RASTERIZER} printed something other than the rendered icon while rendering ` +
             `${input.svg}: ${stdout.slice(0, 200)}`);
     }
     const out = new Map();
     for (const size of input.sizes) {
         const encoded = parsed[String(size)];
         if (encoded === undefined) {
-            throw new Error(`gjsify ship: ${RASTERIZER} rendered no ${size} px image of ${input.svg}.`);
+            throw new Error(`${command}: ${RASTERIZER} rendered no ${size} px image of ${input.svg}.`);
         }
         const png = new Uint8Array(Buffer.from(encoded, 'base64'));
         const { width, height } = readPngSize(png, `the ${size} px render of ${input.svg}`);
         if (width !== size || height !== size) {
-            throw new Error(`gjsify ship: asked ${RASTERIZER} for a ${size} px render of ${input.svg} and got ${width}×${height}.`);
+            throw new Error(`${command}: asked ${RASTERIZER} for a ${size} px render of ${input.svg} and got ${width}×${height}.`);
         }
         out.set(size, png);
     }

package/lib/utils/spawn.d.ts

@@ -1,4 +1,5 @@
 import type { ChildProcess } from 'node:child_process';
+import { type Win32Invocation } from './win32-command.js';
 /**
  * What the calling command does once this spawn settles.
  *
@@ -82,6 +83,18 @@ export interface SpawnCompletion {
     /** The child's stderr — only under `stdio: 'capture'`, `''` when it wrote none. */
     stderr?: string;
 }
+/**
+ * Rewrite a bare command for Windows (see `utils/win32-command.ts`). A no-op on
+ * every other platform, and on win32 for anything already carrying a path or
+ * extension. `env` is the CHILD's, because its `PATH` is what must be searched.
+ *
+ * Exported for the synchronous PROBES that cannot go through
+ * {@link spawnToCompletion} (`<tool> --version` in `check-system-deps.ts`, the
+ * runtime probe in `runtimes.ts`): a raw `execFileSync('deno', …)` is ENOENT on
+ * Windows when deno came from `npm i -g deno`, which installs a `.cmd` shim, so
+ * `--runtime deno` was refused as "not installed" on a host where `deno` runs.
+ */
+export declare function toSpawnable(cmd: string, args: readonly string[], env?: NodeJS.ProcessEnv): Win32Invocation;
 /**
  * Run `cmd args…` to completion and resolve with its exit code and signal.
  *

package/lib/utils/spawn.js

@@ -60,7 +60,7 @@
 //
 // ## What is spawned still matters — the Windows rewrite
 //
-// This helper also carries the Windows command rewrite (`forWin32`), which is a
+// This helper also carries the Windows command rewrite (`toSpawnable`), which is a
 // second reason to come through it, and the one that applies OUTSIDE the CLI too:
 //
 //   • a real executable (`git`, `gh`, `node`, `gjs`, `flatpak`, `process.execPath`)
@@ -93,10 +93,15 @@ function resolveEnv(opts) {
 /**
  * Rewrite a bare command for Windows (see `utils/win32-command.ts`). A no-op on
  * every other platform, and on win32 for anything already carrying a path or
- * extension. Applied to BOTH paths below so the blocking and streaming branches
- * agree; `env` is the CHILD's, because its `PATH` is what must be searched.
+ * extension. `env` is the CHILD's, because its `PATH` is what must be searched.
+ *
+ * Exported for the synchronous PROBES that cannot go through
+ * {@link spawnToCompletion} (`<tool> --version` in `check-system-deps.ts`, the
+ * runtime probe in `runtimes.ts`): a raw `execFileSync('deno', …)` is ENOENT on
+ * Windows when deno came from `npm i -g deno`, which installs a `.cmd` shim, so
+ * `--runtime deno` was refused as "not installed" on a host where `deno` runs.
  */
-function forWin32(cmd, args, env) {
+export function toSpawnable(cmd, args, env) {
     const rewritten = resolveWin32Command(cmd, args, {
         platform: process.platform,
         env: env ?? process.env,
@@ -132,7 +137,7 @@ export function spawnToCompletion(cmd, args, opts) {
     // must not touch it — see `SpawnToCompletionOptions.shell`.
     const invocation = opts.shell
         ? { cmd, args: [...args], windowsVerbatimArguments: false }
-        : forWin32(cmd, args, env);
+        : toSpawnable(cmd, args, env);
     if (mustBlock(opts)) {
         // `'inherit'` is NOT forwarded through `@gjsify/child_process`'s GJS
         // spawnSync path (it drives a private main context via

package/lib/utils/watch-loop.d.ts

@@ -23,9 +23,23 @@ export declare function spawnSupervised(cmd: string, cmdArgs: string[], env?: No
  * "this project").
  */
 export declare function spawnBundleSupervised(runtime: ExampleRuntime, bundlePath: string, cwd: string, subject: string): Promise<ChildProcess>;
+/** One path the loop watches — a directory recursively, or the directory's own entries only. */
+export interface WatchTarget {
+    path: string;
+    recursive: boolean;
+}
 export interface WatchLoopOptions {
-    /** Directory watched recursively. */
+    /** Directory watched recursively — the label and the default when `watch` is not given. */
     dir: string;
+    /**
+     * Several paths instead of `dir` alone. `gjsify webext dev` needs it: its
+     * sources sit in sibling top-level directories next to `node_modules`, and a
+     * recursive watch on the project root costs one `Gio.FileMonitor` per
+     * directory under GJS, `node_modules` included.
+     */
+    watch?: readonly WatchTarget[];
+    /** An absolute changed path the loop must not rebuild for (build output, caches). */
+    ignore?: (changed: string) => boolean;
     /** How `dir` is spelled in the loop's own log lines. Defaults to `dir`. */
     dirLabel?: string;
     /** Prefix for the loop's log lines: `[<label>] …`. */

package/lib/utils/watch-loop.js

@@ -125,7 +125,7 @@ export function isSelfWrite(dir, output, filename) {
  * fix, and a dev loop that dies on a syntax error is a dev loop nobody uses.
  */
 export async function runWatchLoop(opts) {
-    const { dir, label, prepare, build, spawnChild, output, debounceMs = 200 } = opts;
+    const { dir, label, prepare, build, spawnChild, output, ignore, debounceMs = 200 } = opts;
     // Say so BEFORE the first build: `gjsify run`'s in-process dispatch acts on
     // this the moment the handler resolves, and a first build that throws still
     // leaves the loop watching.
@@ -164,13 +164,16 @@ export async function runWatchLoop(opts) {
     };
     await rebuild();
     let debounce = null;
-    const watcher = watch(dir, { recursive: true }, (_event, filename) => {
-        if (isSelfWrite(dir, output, typeof filename === 'string' ? filename : null))
+    const watchers = (opts.watch ?? [{ path: dir, recursive: true }]).map((target) => watch(target.path, { recursive: target.recursive }, (_event, filename) => {
+        const name = typeof filename === 'string' ? filename : null;
+        if (isSelfWrite(target.path, output, name))
+            return;
+        if (ignore && name !== null && ignore(resolve(target.path, name)))
             return;
         if (debounce)
             clearTimeout(debounce);
         debounce = setTimeout(() => void rebuild(), debounceMs);
-    });
+    }));
     // Under GJS nothing else keeps us here. An `fs.watch` handle is a Gio file
     // monitor, not a Node handle count, and the supervised spawn's own
     // `ensureMainLoop()` declines to arm anything: it is reached from a
@@ -198,7 +201,8 @@ export async function runWatchLoop(opts) {
         if (debounce)
             clearTimeout(debounce);
         child?.kill();
-        watcher.close();
+        for (const watcher of watchers)
+            watcher.close();
         process.exit(0);
     };
     process.on('SIGINT', shutdown);

package/lib/utils/webext/build.d.ts

@@ -0,0 +1,42 @@
+import { type ZipEntry } from '../ship/zip.js';
+import type { RasterizeInput } from '../ship/icons.js';
+import type { ResolvedWebext } from './config.js';
+import type { WebextTarget } from './targets.js';
+export interface BundleRequest {
+    entry: string;
+    outfile: string;
+    format: 'esm' | 'iife';
+    define: Record<string, string>;
+    minify: boolean;
+}
+export interface WebextBuildOptions {
+    config: ResolvedWebext;
+    targets: readonly WebextTarget[];
+    /** Absolute; the target folders are `<outDir>/<target>`. */
+    outDir: string;
+    mode: 'production' | 'development';
+    /** Effective defines: the config's, then the command line's. */
+    define: Record<string, string>;
+    /**
+     * Overwrite files instead of starting from an empty folder. `dev` needs it:
+     * deleting the folder `web-ext run` watches makes Firefox unload the
+     * extension mid-rebuild (measured in beifahrer).
+     */
+    inPlace: boolean;
+    zip: boolean;
+    /** Bundle one entry. Injectable so the assembly is testable without a bundler. */
+    bundle: (request: BundleRequest) => Promise<void>;
+    rasterize?: (input: RasterizeInput) => Promise<Map<number, Uint8Array>>;
+    log?: (line: string) => void;
+}
+export interface WebextBuildResult {
+    /** target id → absolute folder. */
+    folders: Map<string, string>;
+    /** target id → absolute zip path (only with `zip`). */
+    zips: Map<string, string>;
+}
+/** One `SOURCE_DATE_EPOCH`-aware timestamp for every entry, so a rebuild zips to the same bytes. */
+export declare function zipTimestamp(env?: NodeJS.ProcessEnv): number;
+/** Every file under `dir`, as archive entries relative to it. */
+export declare function zipEntriesOf(dir: string): ZipEntry[];
+export declare function buildWebext(opts: WebextBuildOptions): Promise<WebextBuildResult>;

package/lib/utils/webext/build.js

@@ -0,0 +1,120 @@
+// `gjsify webext build|zip|dev` — assemble one folder per target (ADR 0077 § 4).
+//
+// Every bundle is built ONCE into a staging directory and copied into each
+// target; only the manifest and the icon files differ between targets. That is
+// beifahrer's measured arrangement, and it is also what makes a target cheap:
+// adding `edge-mv3` to a project costs a copy, not a rebuild.
+import { cpSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { buildZip } from '../ship/zip.js';
+import { renderWebextIcons, webextIconPaths, writeWebextIcons } from './icons.js';
+import { checkManifest, composeManifest, loadManifestTemplate } from './manifest.js';
+import { planPage } from './pages.js';
+/** The fixed ZIP timestamp when SOURCE_DATE_EPOCH is unset: 1980-01-01, the format's floor. */
+const ZIP_EPOCH_FLOOR = 315532800;
+/** One `SOURCE_DATE_EPOCH`-aware timestamp for every entry, so a rebuild zips to the same bytes. */
+export function zipTimestamp(env = process.env) {
+    const epoch = Number(env.SOURCE_DATE_EPOCH);
+    return Number.isFinite(epoch) && epoch >= ZIP_EPOCH_FLOOR ? epoch : ZIP_EPOCH_FLOOR;
+}
+/** Every file under `dir`, as archive entries relative to it. */
+export function zipEntriesOf(dir) {
+    const out = [];
+    const walk = (current) => {
+        for (const entry of readdirSync(current, { withFileTypes: true })) {
+            const full = join(current, entry.name);
+            if (entry.isDirectory())
+                walk(full);
+            else
+                out.push({ path: relative(dir, full).split(/[\\/]/).join('/'), mode: 0o644, data: readFileSync(full) });
+        }
+    };
+    walk(dir);
+    return out;
+}
+export async function buildWebext(opts) {
+    const { config, targets, outDir, define } = opts;
+    const log = opts.log ?? ((line) => console.log(line));
+    const minify = opts.mode === 'production' && config.minify;
+    const stage = join(outDir, '.stage');
+    rmSync(stage, { recursive: true, force: true });
+    mkdirSync(stage, { recursive: true });
+    try {
+        for (const [name, entry] of config.scripts) {
+            await opts.bundle({ entry, outfile: join(stage, `${name}.js`), format: 'iife', define, minify });
+        }
+        const written = new Map();
+        for (const [name, htmlPath] of config.pages) {
+            const plan = planPage(name, htmlPath, readFileSync(htmlPath, 'utf8'));
+            for (const script of plan.scripts) {
+                await opts.bundle({
+                    entry: script.entry,
+                    outfile: join(stage, script.output),
+                    format: script.format,
+                    define,
+                    minify,
+                });
+            }
+            for (const sheet of plan.stylesheets) {
+                const previous = written.get(sheet.output);
+                if (previous !== undefined && previous !== sheet.source) {
+                    throw new Error(`gjsify webext: pages link ${previous} and ${sheet.source}, which would both be written as ` +
+                        `${sheet.output}. Rename one.`);
+                }
+                written.set(sheet.output, sheet.source);
+                cpSync(sheet.source, join(stage, sheet.output));
+            }
+            writeFileSync(join(stage, `${name}.html`), plan.html);
+        }
+        const icons = config.icons;
+        const rendered = icons ? await renderWebextIcons(icons, targets, opts.rasterize) : null;
+        const template = await loadManifestTemplate(config.manifest);
+        const result = { folders: new Map(), zips: new Map() };
+        for (const target of targets) {
+            const dir = join(outDir, target.id);
+            if (!opts.inPlace)
+                rmSync(dir, { recursive: true, force: true });
+            mkdirSync(dir, { recursive: true });
+            // Public files first, so a built file of the same name wins.
+            if (config.publicDir)
+                cpSync(config.publicDir, dir, { recursive: true });
+            if (config.localesDir)
+                cpSync(config.localesDir, join(dir, '_locales'), { recursive: true });
+            cpSync(stage, dir, { recursive: true });
+            if (icons && rendered)
+                writeWebextIcons(rendered, icons, target, dir);
+            const ctx = {
+                target: target.id,
+                browser: target.browser,
+                manifestVersion: target.manifestVersion,
+                mode: opts.mode,
+                version: config.version,
+                define,
+                icons: (name) => {
+                    if (!icons) {
+                        throw new Error(`gjsify webext: the manifest asks for icon "${name}" and \`gjsify.webext.icons\` is not declared.`);
+                    }
+                    return webextIconPaths(icons, name, target);
+                },
+            };
+            const manifest = await composeManifest(template, ctx);
+            writeFileSync(join(dir, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`);
+            const problems = checkManifest(manifest, target, dir);
+            if (problems.length > 0) {
+                throw new Error(`gjsify webext: ${target.id} would not load:\n  - ${problems.join('\n  - ')}`);
+            }
+            result.folders.set(target.id, dir);
+            log(`built ${relative(process.cwd(), dir) || dir}`);
+            if (opts.zip) {
+                const file = join(outDir, `${config.name}-${config.version}-${target.id}.zip`);
+                writeFileSync(file, buildZip(zipEntriesOf(dir), zipTimestamp()));
+                result.zips.set(target.id, file);
+                log(`zipped ${relative(process.cwd(), file) || file} (${Math.round(statSync(file).size / 1024)} KiB)`);
+            }
+        }
+        return result;
+    }
+    finally {
+        rmSync(stage, { recursive: true, force: true });
+    }
+}

package/lib/utils/webext/config.d.ts

@@ -0,0 +1,72 @@
+import { type WebextTarget } from './targets.js';
+/** A source SVG per icon name: one file, or one per size ceiling (`{ "default": …, "32": … }`). */
+export type WebextIconSource = string | Record<string, string>;
+export interface WebextIconsConfig {
+    sizes?: number[];
+    sources: Record<string, WebextIconSource>;
+    /** Targets that receive the SVG files themselves instead of rendered PNGs. */
+    svg?: string[];
+}
+/** The block as a project writes it. */
+export interface WebextConfig {
+    name?: string;
+    targets?: string[];
+    manifest?: string;
+    scripts?: Record<string, string>;
+    pages?: Record<string, string>;
+    icons?: WebextIconsConfig;
+    public?: string;
+    locales?: string;
+    outDir?: string;
+    define?: Record<string, string>;
+    watch?: string[];
+    minify?: boolean;
+}
+export interface ResolvedWebextIcons {
+    sizes: number[];
+    /** name → absolute SVG path per size. */
+    sources: Map<string, Map<number, string>>;
+    svgTargets: Set<string>;
+}
+/** The block after validation, with every path absolute. */
+export interface ResolvedWebext {
+    root: string;
+    name: string;
+    version: string;
+    targets: WebextTarget[];
+    manifest: string;
+    scripts: Map<string, string>;
+    pages: Map<string, string>;
+    icons: ResolvedWebextIcons | null;
+    publicDir: string | null;
+    localesDir: string | null;
+    outDir: string;
+    define: Record<string, string>;
+    watch: string[];
+    minify: boolean;
+}
+export declare const DEFAULT_ICON_SIZES: number[];
+interface PackageShape {
+    name?: string;
+    version?: string;
+    gjsify?: {
+        webext?: unknown;
+    };
+}
+/** The zip base name a package gets when it declares none: its npm name without the scope. */
+export declare function defaultArtifactName(packageName: string | undefined): string;
+/**
+ * Pick the SVG an icon uses at `size`: the smallest numeric ceiling that is
+ * `>= size`, else `default`. Returns undefined when neither covers the size.
+ */
+export declare function iconSourceForSize(source: WebextIconSource, size: number): string | undefined;
+/**
+ * Validate `gjsify.webext` and resolve it against the package root.
+ *
+ * `exists` is injectable so the specs can describe a project without writing
+ * one to disk.
+ */
+export declare function resolveWebextConfig(pkg: PackageShape, root: string, exists?: (path: string, kind: 'file' | 'dir') => boolean): ResolvedWebext;
+/** Narrow the configured targets to the ones a command was asked for. */
+export declare function selectTargets(config: ResolvedWebext, requested: readonly string[] | undefined): WebextTarget[];
+export {};