xbintsc 0.5.45 → 0.5.52

package/src/driver/usage.ts

@@ -0,0 +1,376 @@
+/**
+ * Static usage analysis for optional link features.
+ *
+ * The bundled AST is the last place where the compiler can see *all* of a
+ * program: imported modules and `.html` assets are already merged into one
+ * `SourceFile`, and asset loaders have inlined external stylesheets. This module
+ * extracts the facts a {@link LinkFeature} needs to decide whether it may be
+ * used, without pretending to be a full data-flow analysis:
+ *
+ *   - every string literal / template chunk (HTML tags, CSS property values),
+ *   - identifiers and property names (`Audio`, `decodeAudioData`, …),
+ *   - every `getContext(...)` kind that can be resolved statically,
+ *   - whether HTML/CSS can be built from data the compiler cannot see.
+ *
+ * Constants are resolved through a small, name-based table (`const` only,
+ * invalidated by shadowing or reassignment). Anything that cannot be resolved is
+ * treated as dynamic, which makes features conservative: a false positive costs
+ * size, a false negative could disable a capability at run time.
+ */
+
+import {
+  SyntaxKind,
+  type BinaryExpression,
+  type CallExpression,
+  type Expression,
+  type Identifier,
+  type NoSubstitutionTemplateLiteral,
+  type Parameter,
+  type PrefixUnaryExpression,
+  type PrivateIdentifier,
+  type PropertyAccessExpression,
+  type SourceFileNode,
+  type StringLiteral,
+  type TemplateLiteral,
+  type VariableStatement,
+  type ElementAccessExpression,
+  type AssignmentExpression,
+  type PostfixUnaryExpression,
+  type NumericLiteral,
+  type BigIntLiteral,
+  type BooleanLiteral,
+  type Node,
+} from "../ast/nodes.js";
+import { walk } from "../ast/visitor.js";
+import type { ProgramUsage } from "../extensions/link-feature.js";
+
+/** Operators that make a `BinaryExpression`-shaped node an assignment. */
+const ASSIGNMENT_OPERATORS = new Set<string>([
+  "=",
+  "+=",
+  "-=",
+  "*=",
+  "/=",
+  "%=",
+  "**=",
+  "<<=",
+  ">>=",
+  ">>>=",
+  "&=",
+  "|=",
+  "^=",
+  "&&=",
+  "||=",
+  "??=",
+]);
+
+/** Property names whose assigned value is parsed as markup or CSS. */
+const MARKUP_PROPERTIES = new Set(["innerHTML", "outerHTML", "cssText"]);
+
+/** A call site with a statically known method/function name. */
+interface CallSite {
+  readonly name: string;
+  readonly arguments: readonly Expression[];
+}
+
+/** An assignment whose left side is a statically known property name. */
+interface PropertyAssignmentSite {
+  readonly name: string;
+  readonly right: Expression;
+}
+
+/** A wrapper expression (`as`, `satisfies`, `!`, parentheses) around a value. */
+interface WrappedExpression {
+  readonly expression: Expression;
+}
+
+/**
+ * The property/method name of `a.b` or `a["b"]`, or the identifier of a bare
+ * call (`loadHTML(...)`). Returns undefined for a computed access.
+ */
+function memberName(expression: Expression): string | undefined {
+  if (expression.kind === SyntaxKind.PropertyAccessExpression) {
+    return (expression as PropertyAccessExpression).name.text;
+  }
+  if (expression.kind === SyntaxKind.ElementAccessExpression) {
+    const argument = (expression as ElementAccessExpression).argumentExpression;
+    if (argument.kind === SyntaxKind.StringLiteral) return (argument as StringLiteral).value;
+    return undefined;
+  }
+  if (expression.kind === SyntaxKind.Identifier) return (expression as Identifier).text;
+  return undefined;
+}
+
+/** The assignment-shaped view of a `BinaryExpression`, when it is one. */
+function asAssignment(node: Node): AssignmentExpression | undefined {
+  if (node.kind !== SyntaxKind.BinaryExpression) return undefined;
+  const operator = (node as BinaryExpression).operator;
+  return ASSIGNMENT_OPERATORS.has(String(operator)) ? (node as unknown as AssignmentExpression) : undefined;
+}
+
+/** True for literals that stringify to text which can never contain markup. */
+function isPrimitiveLiteral(expression: Expression): boolean {
+  switch (expression.kind) {
+    case SyntaxKind.NumericLiteral:
+    case SyntaxKind.BigIntLiteral:
+    case SyntaxKind.TrueKeyword:
+    case SyntaxKind.FalseKeyword:
+    case SyntaxKind.NullKeyword:
+    case SyntaxKind.UndefinedKeyword:
+      return true;
+    default:
+      return false;
+  }
+}
+
+/** Convert a primitive literal to the text it contributes to a template. */
+function primitiveText(expression: Expression): string | undefined {
+  switch (expression.kind) {
+    case SyntaxKind.NumericLiteral:
+      return String((expression as NumericLiteral).value);
+    case SyntaxKind.BigIntLiteral:
+      return (expression as BigIntLiteral).value.toString();
+    case SyntaxKind.TrueKeyword:
+    case SyntaxKind.FalseKeyword:
+      return (expression as BooleanLiteral).value ? "true" : "false";
+    case SyntaxKind.NullKeyword:
+      return "null";
+    case SyntaxKind.UndefinedKeyword:
+      return "undefined";
+    default:
+      return undefined;
+  }
+}
+
+/** Collect the usage facts of one bundled program. */
+export function collectUsage(sourceFile: SourceFileNode): ProgramUsage {
+  const strings = new Set<string>();
+  const identifiers = new Set<string>();
+  const constants = new Map<string, Expression>();
+  const ambiguous = new Set<string>();
+  const assigned = new Set<string>();
+  const calls: CallSite[] = [];
+  const assignments: PropertyAssignmentSite[] = [];
+  let createsStyleElement = false;
+  let unresolvedTextContent = false;
+
+  const forget = (name: string): void => {
+    if (constants.delete(name)) ambiguous.add(name);
+  };
+
+  walk(sourceFile, (node) => {
+    switch (node.kind) {
+      case SyntaxKind.StringLiteral:
+        strings.add((node as StringLiteral).value);
+        break;
+      case SyntaxKind.NoSubstitutionTemplateLiteral:
+        strings.add((node as NoSubstitutionTemplateLiteral).value);
+        break;
+      case SyntaxKind.TemplateLiteral: {
+        const template = node as TemplateLiteral;
+        strings.add(template.head);
+        for (const span of template.spans) strings.add(span.literal);
+        break;
+      }
+      case SyntaxKind.Identifier:
+        identifiers.add((node as Identifier).text);
+        break;
+      case SyntaxKind.PrivateIdentifier:
+        identifiers.add((node as PrivateIdentifier).text);
+        break;
+      case SyntaxKind.VariableStatement: {
+        const statement = node as VariableStatement;
+        if (statement.declarationList.declarationKind !== "const") break;
+        for (const declaration of statement.declarationList.declarations) {
+          if (declaration.name.kind !== SyntaxKind.Identifier || declaration.initializer === undefined) continue;
+          const name = declaration.name.text;
+          /* A second declaration of the same name makes the initializer
+           * ambiguous: shadowing is not tracked, so refuse to resolve it. */
+          if (constants.has(name) || ambiguous.has(name)) {
+            forget(name);
+            continue;
+          }
+          constants.set(name, declaration.initializer);
+        }
+        break;
+      }
+      case SyntaxKind.Parameter: {
+        /* A parameter shadows any const of the same name; resolution only looks
+         * at the name, so mark it ambiguous. */
+        const parameter = node as Parameter;
+        if (parameter.name.kind === SyntaxKind.Identifier) ambiguous.add(parameter.name.text);
+        break;
+      }
+      case SyntaxKind.PrefixUnaryExpression: {
+        const unary = node as PrefixUnaryExpression;
+        if (unary.operator === "++" || unary.operator === "--") {
+          if (unary.operand.kind === SyntaxKind.Identifier) assigned.add(unary.operand.text);
+        }
+        break;
+      }
+      case SyntaxKind.PostfixUnaryExpression: {
+        const unary = node as PostfixUnaryExpression;
+        if (unary.operand.kind === SyntaxKind.Identifier) assigned.add(unary.operand.text);
+        break;
+      }
+      case SyntaxKind.BinaryExpression: {
+        const assignment = asAssignment(node);
+        if (assignment === undefined) break;
+        if (assignment.left.kind === SyntaxKind.Identifier) assigned.add(assignment.left.text);
+        const name = memberName(assignment.left);
+        if (name !== undefined) assignments.push({ name, right: assignment.right });
+        break;
+      }
+      case SyntaxKind.CallExpression: {
+        const call = node as CallExpression;
+        const name = memberName(call.expression);
+        if (name !== undefined) calls.push({ name, arguments: call.arguments });
+        break;
+      }
+      default:
+        break;
+    }
+  });
+
+  const resolve = (expression: Expression, stack: Set<string> = new Set()): string | undefined => {
+    const primitive = primitiveText(expression);
+    if (primitive !== undefined) return primitive;
+    switch (expression.kind) {
+      case SyntaxKind.StringLiteral:
+        return (expression as StringLiteral).value;
+      case SyntaxKind.NoSubstitutionTemplateLiteral:
+        return (expression as NoSubstitutionTemplateLiteral).value;
+      case SyntaxKind.TemplateLiteral: {
+        const template = expression as TemplateLiteral;
+        let text = template.head;
+        for (const span of template.spans) {
+          const value = resolve(span.expression, stack);
+          if (value === undefined) {
+            if (!isPrimitiveLiteral(span.expression)) return undefined;
+          } else {
+            text += value;
+          }
+          text += span.literal;
+        }
+        return text;
+      }
+      case SyntaxKind.Identifier: {
+        const name = (expression as Identifier).text;
+        if (assigned.has(name) || ambiguous.has(name)) return undefined;
+        const initializer = constants.get(name);
+        if (initializer === undefined || stack.has(name)) return undefined;
+        stack.add(name);
+        const value = resolve(initializer, stack);
+        stack.delete(name);
+        return value;
+      }
+      case SyntaxKind.ParenthesizedExpression:
+      case SyntaxKind.AsExpression:
+      case SyntaxKind.SatisfiesExpression:
+      case SyntaxKind.NonNullExpression: {
+        return resolve((expression as unknown as WrappedExpression).expression, stack);
+      }
+      case SyntaxKind.BinaryExpression: {
+        const binary = expression as BinaryExpression;
+        if (ASSIGNMENT_OPERATORS.has(String(binary.operator)) || binary.operator !== "+") return undefined;
+        const left = resolve(binary.left, stack);
+        const right = resolve(binary.right, stack);
+        return left === undefined || right === undefined ? undefined : left + right;
+      }
+      default:
+        return undefined;
+    }
+  };
+
+  let dynamicMarkup = false;
+  const getContextKinds: (string | undefined)[] = [];
+
+  const sink = (expression: Expression | undefined): void => {
+    if (expression === undefined) {
+      dynamicMarkup = true;
+      return;
+    }
+    const text = resolve(expression);
+    if (text === undefined) dynamicMarkup = true;
+    else strings.add(text);
+  };
+
+  const sinkAll = (expressions: readonly Expression[]): void => {
+    for (const expression of expressions) {
+      const text = resolve(expression);
+      if (text === undefined) dynamicMarkup = true;
+      else strings.add(text);
+    }
+  };
+
+  for (const site of calls) {
+    switch (site.name) {
+      case "getContext": {
+        const kind = site.arguments[0] === undefined ? undefined : resolve(site.arguments[0]);
+        getContextKinds.push(kind === undefined ? undefined : kind.toLowerCase());
+        break;
+      }
+      case "createElement": {
+        const tag = site.arguments[0] === undefined ? undefined : resolve(site.arguments[0]);
+        if (tag === undefined) dynamicMarkup = true;
+        else if (tag.toLowerCase() === "style") createsStyleElement = true;
+        break;
+      }
+      case "createElementNS": {
+        const tag = site.arguments[1] === undefined ? undefined : resolve(site.arguments[1]);
+        if (tag === undefined) dynamicMarkup = true;
+        else if (tag.toLowerCase() === "style") createsStyleElement = true;
+        break;
+      }
+      case "loadHTML":
+      case "parseFromString":
+      case "write":
+      case "writeln":
+        sink(site.arguments[0]);
+        break;
+      case "insertAdjacentHTML":
+        sink(site.arguments[1]);
+        break;
+      case "setAttribute": {
+        const attribute = site.arguments[0] === undefined ? undefined : resolve(site.arguments[0]);
+        if (attribute === undefined) dynamicMarkup = true;
+        else if (attribute.toLowerCase() === "style") sink(site.arguments[1]);
+        break;
+      }
+      case "setProperty": {
+        /* The property *name* decides whether a CSS feature is used; the value
+         * cannot introduce a new property. A computed name is therefore the
+         * only reason to be conservative here. */
+        if (site.arguments[0] === undefined || resolve(site.arguments[0]) === undefined) dynamicMarkup = true;
+        break;
+      }
+      case "insertRule":
+      case "addRule":
+      case "replaceSync":
+        sinkAll(site.arguments);
+        break;
+      default:
+        break;
+    }
+  }
+
+  for (const assignment of assignments) {
+    if (MARKUP_PROPERTIES.has(assignment.name)) {
+      sink(assignment.right);
+    } else if (assignment.name === "textContent" || assignment.name === "innerText") {
+      if (resolve(assignment.right) === undefined) unresolvedTextContent = true;
+    }
+  }
+
+  /* A `<style>` element created at run time is usually filled through
+   * `textContent`; if that value is not a literal, CSS (and therefore
+   * `mix-blend-mode`) may come from data the compiler cannot see. */
+  if (createsStyleElement && unresolvedTextContent) dynamicMarkup = true;
+
+  return {
+    strings: [...strings],
+    identifiers,
+    getContext: getContextKinds,
+    dynamicMarkup,
+  };
+}

package/src/driver/version.ts

@@ -9,4 +9,4 @@
  * `main`/`master` only (see `.githooks/pre-commit`), so feature branches never
  * change this line and merging two of them cannot conflict here.
  */
-export const COMPILER_VERSION = "0.5.45";
+export const COMPILER_VERSION = "0.5.52";

package/src/extensions/catalog.ts

@@ -13,9 +13,8 @@
 import type { Extension } from "./registry.js";
 import { nodeExtension } from "./node/index.js";
 import { guiExtension } from "./gui/index.js";
-import { mediaExtension } from "./media/index.js";
 
 /** Every extension bundled with xbintsc, in registration order. */
 export function bundledExtensions(): readonly Extension[] {
-  return [nodeExtension, guiExtension, mediaExtension];
+  return [nodeExtension, guiExtension];
 }

package/src/extensions/gui/features.ts

@@ -0,0 +1,166 @@
+/**
+ * Optional link features of the `gui` extension.
+ *
+ * The GUI engine itself is always linked with `--ext gui`; these are the two
+ * heavy halves a program may never touch:
+ *
+ *   - `media` — the FFmpeg decoder backend (`runtime/ext_media/`, `media.a`).
+ *     The DOM media surface lives in `gui.a`; only decoding is optional, and an
+ *     element without the backend still exists and fires `error`.
+ *   - `gpu` — glslang (+ SPIRV-Cross on macOS), the GLSL→SPIR-V translator used
+ *     by WebGL *and* by the `mix-blend-mode` / `backdrop-filter` offscreen
+ *     compositor. The engine's own shaders are precompiled, so a DOM page
+ *     never needs it.
+ *
+ * Detection is static: the compiler sees imported `.html`/`.css` assets and all
+ * bundled modules, so it can recognise `<video>`/`<audio>`, `getContext("webgl")`
+ * and `mix-blend-mode`/`backdrop-filter`. When markup can be built at run time
+ * the usage collector sets `dynamicMarkup`, which conservatively enables both
+ * features; users who know better can shrink the binary with `--no-feature`.
+ */
+
+import { join } from "node:path";
+import type { LinkFeature, ProgramUsage } from "../link-feature.js";
+import { findRuntimeDir, platformSlug } from "../../driver/paths.js";
+import { findRuntimeLibrary, runtimeLibDir } from "../../driver/runtime-lib.js";
+
+/** `<video …>` / `<audio …>` in an HTML string or asset. */
+const MEDIA_TAG = /<(?:video|audio)\b/i;
+/** A literal tag name handed to `createElement("video")`. */
+const MEDIA_TAG_NAME = /^(?:video|audio)$/i;
+/** Anything that needs the GLSL translator. */
+const GPU_TOKEN = /webgl|mix-blend-mode|mixBlendMode|backdrop-filter|backdropFilter/i;
+
+/** True when the program may create or drive a media element. */
+export function hasMediaUsage(usage: ProgramUsage): boolean {
+  if (usage.dynamicMarkup) return true;
+  for (const name of ["Audio", "HTMLMediaElement", "HTMLVideoElement", "HTMLAudioElement", "decodeAudioData"]) {
+    if (usage.identifiers.has(name)) return true;
+  }
+  return usage.strings.some((value) => MEDIA_TAG.test(value) || MEDIA_TAG_NAME.test(value));
+}
+
+/** True when the program may compile GLSL at run time (WebGL or blending). */
+export function hasGpuUsage(usage: ProgramUsage): boolean {
+  if (usage.dynamicMarkup) return true;
+  if (usage.identifiers.has("mixBlendMode") || usage.identifiers.has("backdropFilter")) return true;
+  if (usage.getContext.some((kind) => kind === undefined || /webgl/i.test(kind))) return true;
+  return usage.strings.some((value) => GPU_TOKEN.test(value));
+}
+
+/** True when the program may ask for a WebGL context (not just blending). */
+export function hasWebglUsage(usage: ProgramUsage): boolean {
+  if (usage.dynamicMarkup) return true;
+  if (usage.getContext.some((kind) => kind === undefined || /webgl/i.test(kind))) return true;
+  return usage.strings.some((value) => /webgl/i.test(value));
+}
+
+/** True when the program may draw a bitmap or SVG. */
+export function hasImageUsage(usage: ProgramUsage): boolean {
+  if (usage.dynamicMarkup) return true;
+  for (const name of ["Image", "ImageBitmap", "createImageBitmap", "drawImage"]) {
+    if (usage.identifiers.has(name)) return true;
+  }
+  return usage.strings.some((value) =>
+    /<img\b|<svg\b|background-image|url\(|\.svg\b|drawImage|createImageBitmap/i.test(value),
+  );
+}
+
+/** True when the program may need full OpenType shaping. Non-Latin text needs it
+ * for shaping, and an author `@font-face` often points at a CFF/OTF font that
+ * the default stb_truetype backend cannot outline. */
+export function hasShapingUsage(usage: ProgramUsage): boolean {
+  if (usage.dynamicMarkup) return true;
+  return usage.strings.some((value) => {
+    if (/@font-face\b/i.test(value)) return true;
+    for (const character of value) {
+      if ((character.codePointAt(0) ?? 0) > 0x7f) return true;
+    }
+    return /\\u\{[0-9a-fA-F]+\}|\\u[0-9a-fA-F]{4}|&#(?:x[0-9a-fA-F]+|\d+);/.test(value);
+  });
+}
+
+/** Absolute path to the per-platform prebuilt media archive. */
+function mediaArchive(): string {
+  return join(runtimeLibDir(), process.platform === "win32" ? "media.lib" : "media.a");
+}
+
+export const guiLinkFeatures: readonly LinkFeature[] = [
+  {
+    name: "media",
+    description: "FFmpeg decoding for <video>/<audio>",
+    /**
+     * The registration bridge is a tiny C file compiled and linked only when
+     * the feature is active. Its constructor installs the decoder table into
+     * the engine and references the backend entry points, which is what makes
+     * the linker extract `media.a` — an archive whose only entry point is a
+     * constructor would otherwise never be pulled in.
+     */
+    runtimeSources: () => [join(findRuntimeDir(), "ext_media", "media_bridge.c")],
+    nativeObjects: () => {
+      const archive = findRuntimeLibrary("media");
+      if (archive === undefined) {
+        throw new Error(
+          `media native library not found at ${mediaArchive()} (media.a or media.lib).\n` +
+            `The optional @xbintsc/${platformSlug()} package ships it: reinstall xbintsc ` +
+            `without --omit=optional, or build it with \`npm run media\` (see doc/gui/build.md).`,
+        );
+      }
+      return [archive];
+    },
+    /** `media.a` is C++ and FFmpeg itself needs libm; the GUI extension already
+     * contributes the C++ runtime and the OS frameworks. On Windows the FFmpeg
+     * objects reference the Win32 crypto/COM services (`bcrypt`, `ole32`) and
+     * `user32`. */
+    linkerFlags: () => (process.platform === "win32" ? ["-lbcrypt", "-lole32", "-luser32"] : ["-lm"]),
+    used: hasMediaUsage,
+  },
+  {
+    name: "gpu",
+    description: "GLSL translation (WebGL, mix-blend-mode and backdrop-filter) via glslang",
+    /**
+     * `gpu_bridge.c` is linked only when the feature is active. It calls into
+     * `gpu_feature.cpp` inside `gui.a`, which installs the shader-translation
+     * table and references `compile_glsl`/`cross_compile_msl`; those references
+     * are what pull the glslang members out of `gui.a`. Without the bridge the
+     * engine's shader paths see a null table and fail gracefully (blend falls
+     * back, WebGL reports a compile log).
+     */
+    runtimeSources: () => [join(findRuntimeDir(), "ext_gui", "gpu_bridge.c")],
+    used: hasGpuUsage,
+  },
+  {
+    name: "images",
+    description: "stb_image/NanoSVG decoding for <img>, CSS backgrounds and inline <svg>",
+    /**
+     * `image_bridge.c` installs `XtImageApi` and references the decoders; a page
+     * with no `<img>`/SVG/`background-image`/`drawImage` links neither
+     * stb_image nor NanoSVG.
+     */
+    runtimeSources: () => [join(findRuntimeDir(), "ext_gui", "image_bridge.c")],
+    used: hasImageUsage,
+  },
+  {
+    name: "shaping",
+    description: "HarfBuzz/FreeType shaping for complex scripts and CFF/OTF fonts",
+    /**
+     * `text_bridge.c` installs `TextApi` and references `text_hb.cpp`, pulling
+     * HarfBuzz and FreeType out of `gui.a`. A Latin-only page keeps the faster
+     * stb_truetype path and links neither library.
+     */
+    runtimeSources: () => [join(findRuntimeDir(), "ext_gui", "text_bridge.c")],
+    used: hasShapingUsage,
+  },
+  {
+    name: "webgl",
+    description: "WebGL context and DOM API (requires gpu)",
+    requires: ["gpu"],
+    /**
+     * `webgl_bridge.c` installs `XtWebglApi` and references the WebGL context
+     * and DOM bindings, pulling them out of `gui.a`. A page that never asks for
+     * WebGL therefore links none of `webgl_*`/`dom_api_webgl*`.
+     */
+    runtimeSources: () => [join(findRuntimeDir(), "ext_gui", "webgl_bridge.c")],
+    used: hasWebglUsage,
+  },
+];

package/src/extensions/gui/index.ts

@@ -27,6 +27,7 @@ import { platformSlug } from "../../driver/paths.js";
 import { findRuntimeLibrary, runtimeLibDir } from "../../driver/runtime-lib.js";
 import { loadHtmlAsset } from "./html.js";
 import { loadScriptAsset } from "./three.js";
+import { guiLinkFeatures } from "./features.js";
 
 /** Top-level `gui` module bindings. */
 const guiModule: ExtensionModule = {
@@ -141,9 +142,8 @@ export const guiExtension: Extension = {
   },
   /**
    * System libraries the archive itself depends on. The vendored third-party
-   * libraries (GPU backend, HarfBuzz, FreeType, ...) are linked *into* `gui.a`
-   * by its build script, so only OS frameworks remain here. TODO(gui): confirm
-   * the exact set once the GPU backend is chosen (see doc/gui.md).
+   * libraries (GPU backend, stb_truetype, stb_image/NanoSVG, ...) are linked
+   * *into* `gui.a` by its build script, so only OS frameworks remain here.
    */
   linkerFlags: () => {
     if (process.platform === "darwin") {
@@ -162,7 +162,7 @@ export const guiExtension: Extension = {
         "-framework", "GameController",
         "-framework", "Metal",
         "-framework", "QuartzCore",
-        /* HarfBuzz's CoreText shaper (macOS system fonts). */
+        /* Cocoa/system text and graphics services used by SDL. */
         "-framework", "CoreText",
         "-framework", "CoreGraphics",
         "-framework", "CoreFoundation",
@@ -216,4 +216,10 @@ export const guiExtension: Extension = {
   globalValues: () => browserGlobals,
   /** Rewrite imported `.html` assets and patch three.js's shader unroller. */
   assetLoaders: () => ({ ".html": loadHtmlAsset, ".js": loadScriptAsset, ".mjs": loadScriptAsset }),
+  /**
+   * FFmpeg and glslang are optional halves of the engine, selected from the
+   * program (see `features.ts`). A program that only renders HTML/CSS never
+   * links either.
+   */
+  linkFeatures: () => guiLinkFeatures,
 };

package/src/extensions/link-feature.ts

@@ -0,0 +1,72 @@
+/**
+ * Optional link features: runtime capabilities an extension can contribute
+ * without making every program pay for them.
+ *
+ * A feature is *not* an extension: the extension is the compile-time unit
+ * (`--ext gui`), while a feature is a heavy optional half of it (`FFmpeg`,
+ * `glslang`). The driver decides which features a program may use from a static
+ * scan of the bundled AST (see `src/driver/usage.ts`) and then links the
+ * feature's registration object and archives only for those.
+ *
+ * The registration object is the "strong reference": it is a C translation unit
+ * linked directly only when the feature is active. Its constructor installs the
+ * feature's dispatch table into the core, and its references force the linker to
+ * extract the archive members that implement the feature. This is the same
+ * mechanism the former `media` extension used for `media_bridge.c`.
+ */
+
+/** Facts about a bundled program that features use to decide whether they are needed. */
+export interface ProgramUsage {
+  /**
+   * Every string literal value in the bundle, including the HTML/CSS of
+   * imported `.html` assets and the static chunks of template literals.
+   */
+  readonly strings: readonly string[];
+  /** Identifiers and property names referenced anywhere in the bundle. */
+  readonly identifiers: ReadonlySet<string>;
+  /**
+   * One entry per `getContext(...)` call: the context kind when the argument
+   * could be resolved to a literal, or `undefined` when it is decided at run
+   * time (which must be treated conservatively as "might be WebGL").
+   */
+  readonly getContext: readonly (string | undefined)[];
+  /**
+   * True when the program can build HTML/CSS from data the compiler cannot
+   * see (`innerHTML = fetched`, `loadHTML(buildPage())`, …). Features must
+   * assume they may be used when this is set.
+   */
+  readonly dynamicMarkup: boolean;
+}
+
+/**
+ * One optional capability an extension can contribute.
+ *
+ * `used()` is only consulted when the providing extension is enabled. When it
+ * returns true (or the user forces the feature) the driver compiles
+ * `runtimeSources()` and links `nativeObjects()`, which makes the implementations
+ * reachable. Nothing else about the feature exists at compile time.
+ */
+export interface LinkFeature {
+  /** Stable name used by `--feature` / `--no-feature`, e.g. `media`. */
+  readonly name: string;
+  /** One-line description for diagnostics and `--verbose`. */
+  readonly description: string;
+  /**
+   * C sources compiled and linked only when the feature is active. At least one
+   * of them must reference the feature's implementation so the linker extracts
+   * it from its archive.
+   */
+  runtimeSources?(): readonly string[];
+  /**
+   * Pre-built objects/archives linked only when the feature is active. Throwing
+   * here means "the feature is unavailable on this host"; the driver turns that
+   * into a warning for auto-detected features and an error for forced ones.
+   */
+  nativeObjects?(): readonly string[];
+  /** Extra linker flags contributed only when the feature is active. */
+  linkerFlags?(): readonly string[];
+  /** Other link features this one needs (activated with it). */
+  readonly requires?: readonly string[];
+  /** Whether the program may use this feature. */
+  used(usage: ProgramUsage): boolean;
+}