@fluixi/compiler 1.0.0-alpha.100

package/dist/resolve/component-globals.cjs

@@ -0,0 +1,272 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/resolve/component-globals.ts
+var component_globals_exports = {};
+__export(component_globals_exports, {
+  componentGlobals: () => componentGlobals
+});
+module.exports = __toCommonJS(component_globals_exports);
+
+// src/resolve/component-resolver.ts
+var isMapRule = (rule) => "components" in rule;
+function substitute(template, match) {
+  return template.replace(/\$(\d+)/g, (whole, index) => {
+    const group = match[Number(index)];
+    return group ?? whole;
+  });
+}
+function normalise(name, entry) {
+  return typeof entry === "string" ? { module: entry, export: name } : entry;
+}
+function createComponentResolver(rules = []) {
+  const exact = /* @__PURE__ */ new Map();
+  const conflicts = [];
+  const patterns = [];
+  for (const rule of rules) {
+    if (!isMapRule(rule)) {
+      patterns.push(rule);
+      continue;
+    }
+    for (const [name, entry] of Object.entries(rule.components)) {
+      const resolved = normalise(name, entry);
+      const existing = exact.get(name);
+      if (existing && existing.module !== resolved.module) {
+        const conflict = conflicts.find((c) => c.name === name);
+        if (conflict) conflict.modules.push(resolved.module);
+        else conflicts.push({ name, modules: [existing.module, resolved.module] });
+        continue;
+      }
+      exact.set(name, resolved);
+    }
+  }
+  const cache = /* @__PURE__ */ new Map();
+  const resolve = (name) => {
+    if (cache.has(name)) return cache.get(name);
+    let result = exact.get(name);
+    if (!result) {
+      for (const rule of patterns) {
+        const match = name.match(new RegExp(rule.match.source, rule.match.flags.replace("g", "")));
+        if (!match) continue;
+        result = {
+          module: substitute(rule.module, match),
+          export: rule.export ? substitute(rule.export, match) : name
+        };
+        break;
+      }
+    }
+    cache.set(name, result);
+    return result;
+  };
+  return {
+    resolve,
+    names: () => [...exact.keys()],
+    conflicts: () => conflicts
+  };
+}
+
+// src/resolve/builtins.ts
+var DOM_CONTROL_FLOW = [
+  "Show",
+  "For",
+  "Index",
+  "Switch",
+  "Match",
+  "Portal",
+  "Dynamic",
+  "ErrorBoundary"
+];
+var CORE_CONTROL_FLOW = ["Suspense", "SuspenseList", "Await"];
+var ROUTER_COMPONENTS = ["Router", "Outlet", "Redirect", "Link"];
+var BUILTIN_COMPONENTS = [
+  ...DOM_CONTROL_FLOW,
+  ...CORE_CONTROL_FLOW,
+  ...ROUTER_COMPONENTS
+];
+var RESERVED_COMPONENTS = /* @__PURE__ */ new Set([
+  ...DOM_CONTROL_FLOW,
+  ...CORE_CONTROL_FLOW
+]);
+function builtinComponentMap(modules = {}) {
+  const {
+    controlFlowModule = "@fluixi/dom",
+    coreModule = "@fluixi/core",
+    routerModule = "@fluixi/core/router"
+  } = modules;
+  const map = {};
+  for (const name of DOM_CONTROL_FLOW) map[name] = controlFlowModule;
+  for (const name of CORE_CONTROL_FLOW) map[name] = coreModule;
+  for (const name of ROUTER_COMPONENTS) map[name] = routerModule;
+  return map;
+}
+
+// src/analyze/intrinsics.ts
+var REACTIVE_MODULE = "@fluixi/reactive/signal";
+var INTRINSICS = {
+  $signal: { export: "signal", module: REACTIVE_MODULE, returns: "signal-handle" },
+  $memo: { export: "memo", module: REACTIVE_MODULE, returns: "memo-handle" },
+  $effect: { export: "effect", module: REACTIVE_MODULE, returns: "effect" },
+  $store: { export: "store", module: "@fluixi/reactive/store", returns: "store-handle" },
+  $resource: { export: "resource", module: REACTIVE_MODULE, returns: "resource-handle" },
+  $cachedResource: { export: "cachedResource", module: "@fluixi/reactive/cached-resource", returns: "resource-handle" },
+  // No short runtime form for these yet, so the intrinsic stands for the `create*`
+  // name. Still worth having: no import to write, and when a shorter form is
+  // designed, the change is this line rather than a compiler pass.
+  $selector: { export: "createSelector", module: REACTIVE_MODULE, returns: "memo-accessor" },
+  $deferred: { export: "createDeferred", module: REACTIVE_MODULE, returns: "memo-accessor" },
+  // Not value constructors, but the compiler has to know them: they change what a read
+  // does. `untrack` suppresses dependency collection, which is exactly the kind of thing
+  // dependency analysis must not guess at.
+  $untrack: { export: "untrack", module: REACTIVE_MODULE, returns: "plain" },
+  $untrackStore: { export: "untrackStore", module: "@fluixi/reactive/store", returns: "plain" },
+  // Scopes, scheduling and lifecycle: no value to classify, but the same authoring promise,
+  // no import to write. `$cleanup` registers a callback on the current owner (`onCleanup`).
+  $batch: { export: "batch", module: REACTIVE_MODULE, returns: "plain" },
+  $cleanup: { export: "onCleanup", module: REACTIVE_MODULE, returns: "plain" },
+  $root: { export: "root", module: REACTIVE_MODULE, returns: "plain" },
+  $context: { export: "context", module: REACTIVE_MODULE, returns: "plain" },
+  $renderEffect: { export: "renderEffect", module: REACTIVE_MODULE, returns: "effect" },
+  $computed: { export: "computed", module: REACTIVE_MODULE, returns: "effect" },
+  // Storage for where the code runs, and a signal kept in it. `$persisted` is a signal
+  // handle as far as reads go: the same accessor with `set` on it.
+  $storage: { export: "useStorage", module: "@fluixi/core/storage", returns: "plain" },
+  $asyncStorage: { export: "useAsyncStorage", module: "@fluixi/core/storage", returns: "plain" },
+  $persisted: { export: "persisted", module: "@fluixi/core/storage", returns: "signal-handle" },
+  // An environment variable, public or server-only; the browser build refuses a secret.
+  $env: { export: "env", module: "@fluixi/start/env", returns: "plain" }
+};
+var TAG_INTRINSICS = {
+  $html: { export: "html", module: "@fluixi/core" },
+  $svg: { export: "svg", module: "@fluixi/core" },
+  $css: { export: "css", module: "@fluixi/core" }
+};
+var INTRINSIC_CALL = new RegExp(`\\$(?:${Object.keys(INTRINSICS).map((n) => n.slice(1)).join("|")})\\s*\\(`);
+
+// src/resolve/component-globals.ts
+var DOM_GLOBALS = /* @__PURE__ */ new Set([
+  "Text",
+  "Image",
+  "Option",
+  "Audio",
+  "Comment",
+  "Range",
+  "Selection",
+  "Notification",
+  "Event",
+  "Document",
+  "Element",
+  "Node",
+  "Screen",
+  "Window",
+  "Location",
+  "History",
+  "Storage",
+  "Response",
+  "Request",
+  "Headers"
+]);
+function packageOf(specifier) {
+  if (specifier.startsWith(".") || specifier.startsWith("/")) return void 0;
+  if (/^[~@]\//.test(specifier)) return void 0;
+  const parts = specifier.split("/");
+  return specifier.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
+}
+function namespaceAlias(module2) {
+  return `_${module2.replace(/[^A-Za-z0-9]/g, "_")}`;
+}
+function componentGlobals(rules, options = {}) {
+  const {
+    available: availableList,
+    builtins = true,
+    intrinsics = true,
+    generator = "@fluixi/compiler",
+    specifier = (module2) => module2,
+    candidates = []
+  } = options;
+  const all = [...rules];
+  if (builtins) {
+    all.push({ components: builtinComponentMap() });
+  }
+  const resolver = createComponentResolver(all);
+  const available = availableList ? new Set(availableList) : void 0;
+  const declared = [];
+  const shadowedByDom = [];
+  const unavailable = [];
+  const resolved = /* @__PURE__ */ new Map();
+  const names = /* @__PURE__ */ new Set([...resolver.names(), ...[...candidates].filter((n) => /^[A-Za-z_$][\w$]*$/.test(n))]);
+  for (const name of [...names].sort()) {
+    const target = resolver.resolve(name);
+    if (!target) continue;
+    const pkg = packageOf(target.module);
+    if (DOM_GLOBALS.has(name)) shadowedByDom.push(name);
+    else if (available && pkg && !available.has(pkg)) unavailable.push(name);
+    else {
+      declared.push(name);
+      resolved.set(name, target);
+    }
+  }
+  const usableIntrinsics = intrinsics ? Object.entries({ ...INTRINSICS, ...TAG_INTRINSICS }).filter(([, i]) => {
+    const pkg = packageOf(i.module);
+    return !available || !pkg || available.has(pkg);
+  }) : [];
+  const intrinsicModules = [...new Set(usableIntrinsics.map(([, i]) => i.module))];
+  const modules = [
+    .../* @__PURE__ */ new Set([...declared.map((name) => resolved.get(name).module), ...intrinsicModules])
+  ].sort();
+  const imports = modules.map(
+    (m) => `import * as ${namespaceAlias(m)} from '${specifier(m)}';`
+  );
+  const lines = declared.map((name) => {
+    const target = resolved.get(name);
+    const ns = namespaceAlias(target.module);
+    return target.export === "default" ? `  const ${name}: typeof ${ns}.default;` : `  export import ${name} = ${ns}.${target.export};`;
+  });
+  const note = shadowedByDom.length > 0 ? `//
+// Import these explicitly: lib.dom already declares the name, so an ambient
+// declaration cannot win:
+` + shadowedByDom.map((n) => {
+    const module2 = resolver.resolve(n)?.module;
+    return `//   import { ${n} } from '${module2 ? specifier(module2) : ""}';
+`;
+  }).join("") : "";
+  const intrinsicLines = usableIntrinsics.map(
+    ([name, intrinsic]) => `  const ${name}: typeof ${namespaceAlias(intrinsic.module)}.${intrinsic.export};`
+  );
+  const patternRules = rules.filter((rule) => "match" in rule).length;
+  const patternNote = patternRules === 0 ? "" : options.candidates ? `//
+// ${patternRules} pattern rule${patternRules === 1 ? "" : "s"}: declared for the files the module path
+// points at. A name with no such file still resolves at build time; declare it by hand.
+` : `//
+// ${patternRules} pattern rule${patternRules === 1 ? "" : "s"} cannot be declared:
+// a pattern matches unboundedly many names, so there is no list to emit. Those
+// tags still resolve at build time; declare them by hand if the editor needs them.
+`;
+  const source = `// GENERATED by ${generator}, do not edit.
+//
+// The components \`resolve\` supplies without an import. This describes what the
+// compiler already does; it does not enable it.
+` + note + patternNote + (imports.length > 0 ? `
+${imports.join("\n")}
+` : "\n") + `
+declare global {
+${[...lines, ...intrinsicLines].join("\n")}
+}
+`;
+  return { source, declared, shadowedByDom, unavailable, patternRules };
+}

package/dist/resolve/component-globals.d.cts

@@ -0,0 +1,88 @@
+/**
+ * Ambient declarations for the components `resolve` supplies without an import.
+ *
+ * The compiler injects the import, so nothing in the source imports these, which leaves
+ * TypeScript reporting `TS2304: Cannot find name`. The code compiles and runs; the editor
+ * is unusable and `tsc` fails. These declarations describe what the compiler already
+ * does. They do not enable it.
+ *
+ * This lives next to the resolver, and takes rules rather than a flat map, because the
+ * resolver is the only thing that knows the whole picture: a UI library's components, the
+ * project's own, and the framework builtins all arrive through the same config. A
+ * component library cannot generate this on its own, it does not know what else the
+ * project resolves: which is why the generator belongs here and the library-specific CLI
+ * that predates it does not.
+ *
+ * Pure, like the resolver: rules in, source out, no filesystem. Writing the file is the
+ * caller's job (the Vite plugin does it on config resolve; a CLI can do it in CI).
+ */
+import { type ComponentResolverRule } from './component-resolver.cjs';
+export interface ComponentGlobalsOptions {
+    /**
+     * Packages the project can actually resolve: normally its declared dependencies.
+     *
+     * Declaring a component from a package the project does not depend on produces an
+     * unresolvable `import(...)`, and under the usual `skipLibCheck: true` that failure is
+     * silent: the component degrades to `any` and every prop typo type-checks, which is
+     * worse than the error it replaced. Omit to declare everything, which is only correct
+     * when every package is present.
+     *
+     * Relative and alias specifiers are never filtered, there is no package to check.
+     */
+    available?: Iterable<string>;
+    /**
+     * Declare the framework builtins (`Show`, `For`, `Portal`, `Router`, …) too.
+     *
+     * On by default because the compiler resolves them whether or not a rule mentions
+     * them, so declaring them is what matches reality. A real import shadows the ambient
+     * declaration, so this stays safe for code that imports them explicitly.
+     */
+    builtins?: boolean;
+    /**
+     * Declare the `$` reactive intrinsics (`$signal`, `$memo`, …).
+     *
+     * On by default, matching the compiler: it rewrites those calls whether or not
+     * anything declares them, and without the declaration the editor reports
+     * "Cannot find name '$signal'" for code that builds correctly.
+     */
+    intrinsics?: boolean;
+    /**
+     * Names to try against the pattern rules.
+     *
+     * A pattern has no name list of its own, but the files it points at do: the caller lists
+     * them (the generator stays off the filesystem) and each name the resolver answers is
+     * declared like any other.
+     */
+    candidates?: Iterable<string>;
+    /** Attribution written into the header. */
+    generator?: string;
+    /**
+     * Rewrite a module specifier for the file being generated.
+     *
+     * A bundler and TypeScript do not agree on every specifier: Vite resolves a
+     * root-absolute `/src/x.tsx` that TypeScript cannot see at all. The caller knows where
+     * the file will land and so is the only one able to fix that up; the generator stays
+     * pure and just asks.
+     */
+    specifier?: (module: string) => string;
+}
+export interface ComponentGlobalsResult {
+    /** The `.d.ts` source to write. */
+    source: string;
+    /** Components declared. */
+    declared: string[];
+    /** Left out because `lib.dom` already claims the name. */
+    shadowedByDom: string[];
+    /** Left out because the project does not depend on their package. */
+    unavailable: string[];
+    /**
+     * Pattern rules, which have no finite name list and so cannot be declared.
+     *
+     * `Icon(.+) -> @/icons/$1` matches unboundedly many names; the resolver answers them on
+     * demand but cannot enumerate them. Those tags stay manual, and the caller is told how
+     * many rules are in that position rather than left to wonder why nothing appeared.
+     */
+    patternRules: number;
+}
+/** Build the ambient `.d.ts` for the components a project's `resolve` config supplies. */
+export declare function componentGlobals(rules: readonly ComponentResolverRule[], options?: ComponentGlobalsOptions): ComponentGlobalsResult;

package/dist/resolve/component-globals.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Ambient declarations for the components `resolve` supplies without an import.
+ *
+ * The compiler injects the import, so nothing in the source imports these, which leaves
+ * TypeScript reporting `TS2304: Cannot find name`. The code compiles and runs; the editor
+ * is unusable and `tsc` fails. These declarations describe what the compiler already
+ * does. They do not enable it.
+ *
+ * This lives next to the resolver, and takes rules rather than a flat map, because the
+ * resolver is the only thing that knows the whole picture: a UI library's components, the
+ * project's own, and the framework builtins all arrive through the same config. A
+ * component library cannot generate this on its own, it does not know what else the
+ * project resolves: which is why the generator belongs here and the library-specific CLI
+ * that predates it does not.
+ *
+ * Pure, like the resolver: rules in, source out, no filesystem. Writing the file is the
+ * caller's job (the Vite plugin does it on config resolve; a CLI can do it in CI).
+ */
+import { type ComponentResolverRule } from './component-resolver.js';
+export interface ComponentGlobalsOptions {
+    /**
+     * Packages the project can actually resolve: normally its declared dependencies.
+     *
+     * Declaring a component from a package the project does not depend on produces an
+     * unresolvable `import(...)`, and under the usual `skipLibCheck: true` that failure is
+     * silent: the component degrades to `any` and every prop typo type-checks, which is
+     * worse than the error it replaced. Omit to declare everything, which is only correct
+     * when every package is present.
+     *
+     * Relative and alias specifiers are never filtered, there is no package to check.
+     */
+    available?: Iterable<string>;
+    /**
+     * Declare the framework builtins (`Show`, `For`, `Portal`, `Router`, …) too.
+     *
+     * On by default because the compiler resolves them whether or not a rule mentions
+     * them, so declaring them is what matches reality. A real import shadows the ambient
+     * declaration, so this stays safe for code that imports them explicitly.
+     */
+    builtins?: boolean;
+    /**
+     * Declare the `$` reactive intrinsics (`$signal`, `$memo`, …).
+     *
+     * On by default, matching the compiler: it rewrites those calls whether or not
+     * anything declares them, and without the declaration the editor reports
+     * "Cannot find name '$signal'" for code that builds correctly.
+     */
+    intrinsics?: boolean;
+    /**
+     * Names to try against the pattern rules.
+     *
+     * A pattern has no name list of its own, but the files it points at do: the caller lists
+     * them (the generator stays off the filesystem) and each name the resolver answers is
+     * declared like any other.
+     */
+    candidates?: Iterable<string>;
+    /** Attribution written into the header. */
+    generator?: string;
+    /**
+     * Rewrite a module specifier for the file being generated.
+     *
+     * A bundler and TypeScript do not agree on every specifier: Vite resolves a
+     * root-absolute `/src/x.tsx` that TypeScript cannot see at all. The caller knows where
+     * the file will land and so is the only one able to fix that up; the generator stays
+     * pure and just asks.
+     */
+    specifier?: (module: string) => string;
+}
+export interface ComponentGlobalsResult {
+    /** The `.d.ts` source to write. */
+    source: string;
+    /** Components declared. */
+    declared: string[];
+    /** Left out because `lib.dom` already claims the name. */
+    shadowedByDom: string[];
+    /** Left out because the project does not depend on their package. */
+    unavailable: string[];
+    /**
+     * Pattern rules, which have no finite name list and so cannot be declared.
+     *
+     * `Icon(.+) -> @/icons/$1` matches unboundedly many names; the resolver answers them on
+     * demand but cannot enumerate them. Those tags stay manual, and the caller is told how
+     * many rules are in that position rather than left to wonder why nothing appeared.
+     */
+    patternRules: number;
+}
+/** Build the ambient `.d.ts` for the components a project's `resolve` config supplies. */
+export declare function componentGlobals(rules: readonly ComponentResolverRule[], options?: ComponentGlobalsOptions): ComponentGlobalsResult;
+//# sourceMappingURL=component-globals.d.ts.map

package/dist/resolve/component-globals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-globals.d.ts","sourceRoot":"","sources":["../../src/resolve/component-globals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAEL,KAAK,qBAAqB,EAE3B,MAAM,yBAAyB,CAAC;AAmCjC,MAAM,WAAW,uBAAuB;IACtC;;;;;;;;;;OAUG;IACH,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC7B;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC9B,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;CACxC;AAED,MAAM,WAAW,sBAAsB;IACrC,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,2BAA2B;IAC3B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,0DAA0D;IAC1D,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,qEAAqE;IACrE,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB;;;;;;OAMG;IACH,YAAY,EAAE,MAAM,CAAC;CACtB;AAgBD,0FAA0F;AAC1F,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,SAAS,qBAAqB,EAAE,EACvC,OAAO,GAAE,uBAA4B,GACpC,sBAAsB,CAoHxB"}

package/dist/resolve/component-globals.js

@@ -0,0 +1,160 @@
+/**
+ * Ambient declarations for the components `resolve` supplies without an import.
+ *
+ * The compiler injects the import, so nothing in the source imports these, which leaves
+ * TypeScript reporting `TS2304: Cannot find name`. The code compiles and runs; the editor
+ * is unusable and `tsc` fails. These declarations describe what the compiler already
+ * does. They do not enable it.
+ *
+ * This lives next to the resolver, and takes rules rather than a flat map, because the
+ * resolver is the only thing that knows the whole picture: a UI library's components, the
+ * project's own, and the framework builtins all arrive through the same config. A
+ * component library cannot generate this on its own, it does not know what else the
+ * project resolves: which is why the generator belongs here and the library-specific CLI
+ * that predates it does not.
+ *
+ * Pure, like the resolver: rules in, source out, no filesystem. Writing the file is the
+ * caller's job (the Vite plugin does it on config resolve; a CLI can do it in CI).
+ */
+import { createComponentResolver, } from './component-resolver.js';
+import { builtinComponentMap } from './builtins.js';
+import { INTRINSICS, TAG_INTRINSICS } from '../analyze/intrinsics.js';
+/**
+ * Names `lib.dom` already declares as globals.
+ *
+ * An ambient `const Text` cannot beat `lib.dom`'s `var Text`, so for these the editor
+ * would disagree with the compiler: resolution still works at runtime, but the type
+ * shown would be the DOM node's. They are left out and reported instead, since importing
+ * them explicitly makes both agree.
+ */
+const DOM_GLOBALS = new Set([
+    'Text',
+    'Image',
+    'Option',
+    'Audio',
+    'Comment',
+    'Range',
+    'Selection',
+    'Notification',
+    'Event',
+    'Document',
+    'Element',
+    'Node',
+    'Screen',
+    'Window',
+    'Location',
+    'History',
+    'Storage',
+    'Response',
+    'Request',
+    'Headers',
+]);
+/** The package a specifier belongs to, or undefined when it is not a package import. */
+function packageOf(specifier) {
+    if (specifier.startsWith('.') || specifier.startsWith('/'))
+        return undefined;
+    // Alias specifiers (`@/x`, `~/x`) are project-local and resolve through tsconfig paths.
+    if (/^[~@]\//.test(specifier))
+        return undefined;
+    const parts = specifier.split('/');
+    return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+}
+/** A valid identifier for the namespace import of `module`. */
+function namespaceAlias(module) {
+    return `_${module.replace(/[^A-Za-z0-9]/g, '_')}`;
+}
+/** Build the ambient `.d.ts` for the components a project's `resolve` config supplies. */
+export function componentGlobals(rules, options = {}) {
+    const { available: availableList, builtins = true, intrinsics = true, generator = '@fluixi/compiler', specifier = (module) => module, candidates = [], } = options;
+    const all = [...rules];
+    if (builtins) {
+        // Appended, so an explicit rule for the same name still wins, the resolver is
+        // first-match, and a project retargeting `Router` should keep its own answer.
+        all.push({ components: builtinComponentMap() });
+    }
+    const resolver = createComponentResolver(all);
+    const available = availableList ? new Set(availableList) : undefined;
+    const declared = [];
+    const shadowedByDom = [];
+    const unavailable = [];
+    const resolved = new Map();
+    const names = new Set([...resolver.names(), ...[...candidates].filter((n) => /^[A-Za-z_$][\w$]*$/.test(n))]);
+    for (const name of [...names].sort()) {
+        const target = resolver.resolve(name);
+        if (!target)
+            continue;
+        const pkg = packageOf(target.module);
+        if (DOM_GLOBALS.has(name))
+            shadowedByDom.push(name);
+        else if (available && pkg && !available.has(pkg))
+            unavailable.push(name);
+        else {
+            declared.push(name);
+            resolved.set(name, target);
+        }
+    }
+    // The `$` intrinsics need declaring too, or the editor says "Cannot find name
+    // '$signal'" for code that compiles. tsc doesn't load language-service plugins, so an
+    // ambient declaration is the only thing that answers for both the editor and the
+    // command line.
+    // Only the intrinsics whose package the project has: `$env` comes from `@fluixi/start`, and
+    // an app without it would otherwise get a declaration that fails to resolve.
+    const usableIntrinsics = intrinsics
+        ? Object.entries({ ...INTRINSICS, ...TAG_INTRINSICS }).filter(([, i]) => {
+            const pkg = packageOf(i.module);
+            return !available || !pkg || available.has(pkg);
+        })
+        : [];
+    const intrinsicModules = [...new Set(usableIntrinsics.map(([, i]) => i.module))];
+    const modules = [
+        ...new Set([...declared.map((name) => resolved.get(name).module), ...intrinsicModules]),
+    ].sort();
+    const imports = modules.map((m) => `import * as ${namespaceAlias(m)} from '${specifier(m)}';`);
+    // `export import X = ns.X` rather than `const X: typeof import('…').X`: an alias
+    // resolves to the original symbol, so hover shows the real declaration
+    // (`Button(props: ButtonProps): ComponentChild`) and go-to-definition lands on the
+    // source. Both forms keep the JSDoc; the alias also keeps the shape.
+    //
+    // A default export cannot use it: `import X = ns.default` is a syntax error, since
+    // `default` is a reserved word in that position, so those fall back to the `const`
+    // form, which types and documents correctly but renders as an anonymous arrow.
+    const lines = declared.map((name) => {
+        const target = resolved.get(name);
+        const ns = namespaceAlias(target.module);
+        return target.export === 'default'
+            ? `  const ${name}: typeof ${ns}.default;`
+            : `  export import ${name} = ${ns}.${target.export};`;
+    });
+    const note = shadowedByDom.length > 0
+        ? `//\n// Import these explicitly: lib.dom already declares the name, so an ambient\n` +
+            `// declaration cannot win:\n` +
+            shadowedByDom
+                .map((n) => {
+                const module = resolver.resolve(n)?.module;
+                return `//   import { ${n} } from '${module ? specifier(module) : ''}';\n`;
+            })
+                .join('')
+        : '';
+    // `typeof ns.signal` rather than an alias: the intrinsic is a global that stands for
+    // the runtime call, so it takes the runtime's signature without claiming to be that
+    // symbol: go-to-definition on `$signal` should land on what it compiles to.
+    const intrinsicLines = usableIntrinsics.map(([name, intrinsic]) => `  const ${name}: typeof ${namespaceAlias(intrinsic.module)}.${intrinsic.export};`);
+    const patternRules = rules.filter((rule) => 'match' in rule).length;
+    const patternNote = patternRules === 0
+        ? ''
+        : options.candidates
+            ? `//\n// ${patternRules} pattern rule${patternRules === 1 ? '' : 's'}: declared for the files the module path\n` +
+                `// points at. A name with no such file still resolves at build time; declare it by hand.\n`
+            : `//\n// ${patternRules} pattern rule${patternRules === 1 ? '' : 's'} cannot be declared:\n` +
+                `// a pattern matches unboundedly many names, so there is no list to emit. Those\n` +
+                `// tags still resolve at build time; declare them by hand if the editor needs them.\n`;
+    const source = `// GENERATED by ${generator}, do not edit.\n` +
+        `//\n` +
+        `// The components \`resolve\` supplies without an import. This describes what the\n` +
+        `// compiler already does; it does not enable it.\n` +
+        note +
+        patternNote +
+        (imports.length > 0 ? `\n${imports.join('\n')}\n` : '\n') +
+        `\ndeclare global {\n${[...lines, ...intrinsicLines].join('\n')}\n}\n`;
+    return { source, declared, shadowedByDom, unavailable, patternRules };
+}