@fluixi/compiler 1.0.0-alpha.69 → 1.0.0-alpha.71

package/dist/resolve/component-globals.js

@@ -0,0 +1,137 @@
+/**
+ * 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';
+/**
+ * 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, generator = '@fluixi/compiler', specifier = (module) => module, } = 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();
+    for (const name of [...resolver.names()].sort()) {
+        const target = resolver.resolve(name);
+        /* c8 ignore next */
+        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 modules = [...new Set(declared.map((name) => resolved.get(name).module))].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('')
+        : '';
+    const patternRules = rules.filter((rule) => 'match' in rule).length;
+    const patternNote = patternRules > 0
+        ? `//\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.join('\n')}\n}\n`;
+    return { source, declared, shadowedByDom, unavailable, patternRules };
+}

package/dist/resolve/component-globals.mjs

@@ -0,0 +1,22 @@
+var $=t=>"components"in t;function v(t,o){return t.replace(/\$(\d+)/g,(l,p)=>o[Number(p)]??l)}function N(t,o){return typeof o=="string"?{module:o,export:t}:o}function b(t=[]){let o=new Map,l=[],p=[];for(let r of t){if(!$(r)){p.push(r);continue}for(let[n,a]of Object.entries(r.components)){let s=N(n,a),m=o.get(n);if(m&&m.module!==s.module){let d=l.find(f=>f.name===n);d?d.modules.push(s.module):l.push({name:n,modules:[m.module,s.module]});continue}o.set(n,s)}}let i=new Map;return{resolve:r=>{if(i.has(r))return i.get(r);let n=o.get(r);if(!n)for(let a of p){let s=r.match(new RegExp(a.match.source,a.match.flags.replace("g","")));if(s){n={module:v(a.module,s),export:a.export?v(a.export,s):r};break}}return i.set(r,n),n},names:()=>[...o.keys()],conflicts:()=>l}}var C=["Show","For","Index","Switch","Match","Portal","Dynamic","ErrorBoundary"],h=["Suspense","SuspenseList","Await"],M=["Router","Outlet","Redirect","Link"],j=[...C,...h,...M],A=new Set([...C,...h]);function O(t={}){let{controlFlowModule:o="@fluixi/dom",coreModule:l="@fluixi/core",routerModule:p="@fluixi/core/router-next"}=t,i={};for(let u of C)i[u]=o;for(let u of h)i[u]=l;for(let u of M)i[u]=p;return i}var T=new Set(["Text","Image","Option","Audio","Comment","Range","Selection","Notification","Event","Document","Element","Node","Screen","Window","Location","History","Storage","Response","Request","Headers"]);function L(t){if(t.startsWith(".")||t.startsWith("/")||/^[~@]\//.test(t))return;let o=t.split("/");return t.startsWith("@")?o.slice(0,2).join("/"):o[0]}function y(t){return`_${t.replace(/[^A-Za-z0-9]/g,"_")}`}function W(t,o={}){let{available:l,builtins:p=!0,generator:i="@fluixi/compiler",specifier:u=e=>e}=o,r=[...t];p&&r.push({components:O()});let n=b(r),a=l?new Set(l):void 0,s=[],m=[],d=[],f=new Map;for(let e of[...n.names()].sort()){let c=n.resolve(e);if(!c)continue;let g=L(c.module);T.has(e)?m.push(e):a&&g&&!a.has(g)?d.push(e):(s.push(e),f.set(e,c))}let x=[...new Set(s.map(e=>f.get(e).module))].sort().map(e=>`import * as ${y(e)} from '${u(e)}';`),w=s.map(e=>{let c=f.get(e),g=y(c.module);return c.export==="default"?`  const ${e}: typeof ${g}.default;`:`  export import ${e} = ${g}.${c.export};`}),E=m.length>0?`//
+// Import these explicitly — lib.dom already declares the name, so an ambient
+// declaration cannot win:
+`+m.map(e=>{let c=n.resolve(e)?.module;return`//   import { ${e} } from '${c?u(c):""}';
+`}).join(""):"",R=t.filter(e=>"match"in e).length,S=R>0?`//
+// ${R} pattern rule${R===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.
+`:"";return{source:`// GENERATED by ${i} — do not edit.
+//
+// The components \`resolve\` supplies without an import. This describes what the
+// compiler already does; it does not enable it.
+`+E+S+(x.length>0?`
+${x.join(`
+`)}
+`:`
+`)+`
+declare global {
+${w.join(`
+`)}
+}
+`,declared:s,shadowedByDom:m,unavailable:d,patternRules:R}}export{W as componentGlobals};

package/dist/resolve/load-directive.cjs

@@ -0,0 +1 @@
+"use strict";var o=Object.defineProperty;var l=Object.getOwnPropertyDescriptor;var g=Object.getOwnPropertyNames;var u=Object.prototype.hasOwnProperty;var k=(e,n)=>{for(var t in n)o(e,t,{get:n[t],enumerable:!0})},p=(e,n,t,a)=>{if(n&&typeof n=="object"||typeof n=="function")for(let r of g(n))!u.call(e,r)&&r!==t&&o(e,r,{get:()=>n[r],enumerable:!(a=l(n,r))||a.enumerable});return e};var w=e=>p(o({},"__esModule",{value:!0}),e);var y={};k(y,{DEFAULT_INTERACTION_EVENTS:()=>c,EAGER:()=>d,LoadDirectiveError:()=>i,isDeferred:()=>m,isLoadDirective:()=>v,parseLoadDirective:()=>f,strategyKey:()=>x});module.exports=w(y);var d={kind:"eager"},c=["pointerdown","focusin","keydown"],s=new Set(["eager","idle","visible","interaction","media","never"]),i=class extends Error{};function v(e){return e.startsWith("load:")}function f(e,n){let t=e.slice(5);if(!s.has(t))throw new i(`Unknown load strategy 'load:${t}'. Expected one of ${[...s].join(", ")}.`);switch(t){case"eager":return d;case"idle":return{kind:"idle"};case"never":return{kind:"never"};case"visible":return n?{kind:"visible",rootMargin:n}:{kind:"visible"};case"interaction":return{kind:"interaction",events:n?h(n):[...c]};case"media":if(!n)throw new i(`'load:media' needs a query, e.g. load:media="(min-width: 1024px)".`);return{kind:"media",query:n};default:throw new i(`Unhandled load strategy '${t}'.`)}}function h(e){let n=e.split(/[\s,]+/).map(t=>t.trim()).filter(Boolean);if(n.length===0)throw new i("'load:interaction' was given no event names.");return n}function m(e){return e.kind!=="eager"&&e.kind!=="never"}function x(e){switch(e.kind){case"visible":return`visible:${e.rootMargin??""}`;case"interaction":return`interaction:${[...e.events].sort().join(",")}`;case"media":return`media:${e.query}`;default:return e.kind}}

package/dist/resolve/load-directive.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The `load:` directive — when a component's code is fetched.
+ *
+ * Resolution decides *where* a component comes from; this decides *when*. They are
+ * separate because they vary independently: the location of `<RevenueChart>` is the
+ * same everywhere and belongs in config, while whether this particular usage should
+ * wait for the viewport is a property of the usage. Fusing them — `<Chart lazy="./Chart">`
+ * — was rejected for exactly that reason.
+ *
+ * `load:` joins the existing `use:`/`prop:`/`attr:`/`bool:` namespace, so it cannot
+ * collide with a real prop and the parser already has a directive taxonomy to hang it on.
+ *
+ * One parser for both frontends. `load:visible` is already a valid `JSXNamespacedName`,
+ * so JSX needs no parser change, and the html`` path produces a `LoadDirective` node —
+ * but both funnel through {@link parseLoadDirective}, so the two syntaxes cannot drift.
+ */
+/** When a component's module is fetched. */
+export type IRLoadStrategy = {
+    kind: 'eager';
+} | {
+    kind: 'idle';
+} | {
+    kind: 'visible';
+    rootMargin?: string;
+} | {
+    kind: 'interaction';
+    events: string[];
+} | {
+    kind: 'media';
+    query: string;
+} | {
+    kind: 'never';
+};
+/** Everything is eager unless a directive says otherwise. */
+export declare const EAGER: IRLoadStrategy;
+/** Events that trigger an `interaction` load when none are named. */
+export declare const DEFAULT_INTERACTION_EVENTS: readonly ["pointerdown", "focusin", "keydown"];
+export declare class LoadDirectiveError extends Error {
+}
+/** True for an attribute name in the `load:` namespace. */
+export declare function isLoadDirective(name: string): boolean;
+/**
+ * Parse `load:<strategy>` plus its optional value into a strategy.
+ *
+ * `value` is the attribute's literal text — `load:visible="200px"` — or null for a bare
+ * directive. A `${…}` hole is rejected: the strategy has to be known at compile time
+ * because it decides how the module is emitted, and a runtime value cannot.
+ */
+export declare function parseLoadDirective(name: string, value: string | null): IRLoadStrategy;
+/** True when the strategy means "not in the parent chunk". */
+export declare function isDeferred(strategy: IRLoadStrategy): boolean;
+/** A stable key for grouping references that share a strategy. */
+export declare function strategyKey(strategy: IRLoadStrategy): string;
+//# sourceMappingURL=load-directive.d.ts.map

package/dist/resolve/load-directive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-directive.d.ts","sourceRoot":"","sources":["../../src/resolve/load-directive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,4CAA4C;AAC5C,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtB,6DAA6D;AAC7D,eAAO,MAAM,KAAK,EAAE,cAAkC,CAAC;AAEvD,qEAAqE;AACrE,eAAO,MAAM,0BAA0B,gDAAiD,CAAC;AAIzF,qBAAa,kBAAmB,SAAQ,KAAK;CAAG;AAEhD,2DAA2D;AAC3D,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,cAAc,CAqCrF;AAaD,8DAA8D;AAC9D,wBAAgB,UAAU,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAE5D;AAED,kEAAkE;AAClE,wBAAgB,WAAW,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,CAW5D"}

package/dist/resolve/load-directive.js

@@ -0,0 +1,93 @@
+/**
+ * The `load:` directive — when a component's code is fetched.
+ *
+ * Resolution decides *where* a component comes from; this decides *when*. They are
+ * separate because they vary independently: the location of `<RevenueChart>` is the
+ * same everywhere and belongs in config, while whether this particular usage should
+ * wait for the viewport is a property of the usage. Fusing them — `<Chart lazy="./Chart">`
+ * — was rejected for exactly that reason.
+ *
+ * `load:` joins the existing `use:`/`prop:`/`attr:`/`bool:` namespace, so it cannot
+ * collide with a real prop and the parser already has a directive taxonomy to hang it on.
+ *
+ * One parser for both frontends. `load:visible` is already a valid `JSXNamespacedName`,
+ * so JSX needs no parser change, and the html`` path produces a `LoadDirective` node —
+ * but both funnel through {@link parseLoadDirective}, so the two syntaxes cannot drift.
+ */
+/** Everything is eager unless a directive says otherwise. */
+export const EAGER = { kind: 'eager' };
+/** Events that trigger an `interaction` load when none are named. */
+export const DEFAULT_INTERACTION_EVENTS = ['pointerdown', 'focusin', 'keydown'];
+const STRATEGIES = new Set(['eager', 'idle', 'visible', 'interaction', 'media', 'never']);
+export class LoadDirectiveError extends Error {
+}
+/** True for an attribute name in the `load:` namespace. */
+export function isLoadDirective(name) {
+    return name.startsWith('load:');
+}
+/**
+ * Parse `load:<strategy>` plus its optional value into a strategy.
+ *
+ * `value` is the attribute's literal text — `load:visible="200px"` — or null for a bare
+ * directive. A `${…}` hole is rejected: the strategy has to be known at compile time
+ * because it decides how the module is emitted, and a runtime value cannot.
+ */
+export function parseLoadDirective(name, value) {
+    const strategy = name.slice('load:'.length);
+    if (!STRATEGIES.has(strategy)) {
+        throw new LoadDirectiveError(`Unknown load strategy 'load:${strategy}'. Expected one of ${[...STRATEGIES].join(', ')}.`);
+    }
+    switch (strategy) {
+        case 'eager':
+            return EAGER;
+        case 'idle':
+            return { kind: 'idle' };
+        case 'never':
+            return { kind: 'never' };
+        case 'visible':
+            // `load:visible="200px"` starts the fetch before the element reaches the
+            // viewport, which is usually what you want — arriving exactly on intersection
+            // means the user waits for the network.
+            return value ? { kind: 'visible', rootMargin: value } : { kind: 'visible' };
+        case 'interaction':
+            return {
+                kind: 'interaction',
+                events: value ? splitEvents(value) : [...DEFAULT_INTERACTION_EVENTS],
+            };
+        case 'media':
+            if (!value) {
+                throw new LoadDirectiveError(`'load:media' needs a query, e.g. load:media="(min-width: 1024px)".`);
+            }
+            return { kind: 'media', query: value };
+        default:
+            /* c8 ignore next */
+            throw new LoadDirectiveError(`Unhandled load strategy '${strategy}'.`);
+    }
+}
+function splitEvents(value) {
+    const events = value
+        .split(/[\s,]+/)
+        .map((e) => e.trim())
+        .filter(Boolean);
+    if (events.length === 0) {
+        throw new LoadDirectiveError(`'load:interaction' was given no event names.`);
+    }
+    return events;
+}
+/** True when the strategy means "not in the parent chunk". */
+export function isDeferred(strategy) {
+    return strategy.kind !== 'eager' && strategy.kind !== 'never';
+}
+/** A stable key for grouping references that share a strategy. */
+export function strategyKey(strategy) {
+    switch (strategy.kind) {
+        case 'visible':
+            return `visible:${strategy.rootMargin ?? ''}`;
+        case 'interaction':
+            return `interaction:${[...strategy.events].sort().join(',')}`;
+        case 'media':
+            return `media:${strategy.query}`;
+        default:
+            return strategy.kind;
+    }
+}

package/dist/resolve/load-directive.mjs

@@ -0,0 +1 @@
+var o={kind:"eager"},a=["pointerdown","focusin","keydown"],r=new Set(["eager","idle","visible","interaction","media","never"]),i=class extends Error{};function d(e){return e.startsWith("load:")}function c(e,n){let t=e.slice(5);if(!r.has(t))throw new i(`Unknown load strategy 'load:${t}'. Expected one of ${[...r].join(", ")}.`);switch(t){case"eager":return o;case"idle":return{kind:"idle"};case"never":return{kind:"never"};case"visible":return n?{kind:"visible",rootMargin:n}:{kind:"visible"};case"interaction":return{kind:"interaction",events:n?s(n):[...a]};case"media":if(!n)throw new i(`'load:media' needs a query, e.g. load:media="(min-width: 1024px)".`);return{kind:"media",query:n};default:throw new i(`Unhandled load strategy '${t}'.`)}}function s(e){let n=e.split(/[\s,]+/).map(t=>t.trim()).filter(Boolean);if(n.length===0)throw new i("'load:interaction' was given no event names.");return n}function l(e){return e.kind!=="eager"&&e.kind!=="never"}function g(e){switch(e.kind){case"visible":return`visible:${e.rootMargin??""}`;case"interaction":return`interaction:${[...e.events].sort().join(",")}`;case"media":return`media:${e.query}`;default:return e.kind}}export{a as DEFAULT_INTERACTION_EVENTS,o as EAGER,i as LoadDirectiveError,l as isDeferred,d as isLoadDirective,c as parseLoadDirective,g as strategyKey};

package/dist/resolve/resolve-ir.cjs

@@ -0,0 +1 @@
+"use strict";var c=Object.defineProperty;var M=Object.getOwnPropertyDescriptor;var y=Object.getOwnPropertyNames;var I=Object.prototype.hasOwnProperty;var w=(n,e)=>{for(var i in e)c(n,i,{get:e[i],enumerable:!0})},N=(n,e,i,s)=>{if(e&&typeof e=="object"||typeof e=="function")for(let o of y(e))!I.call(n,o)&&o!==i&&c(n,o,{get:()=>e[o],enumerable:!(s=M(e,o))||s.enumerable});return n};var k=n=>N(c({},"__esModule",{value:!0}),n);var h={};w(h,{resolveComponentSources:()=>b,walk:()=>f});module.exports=k(h);var l=["Show","For","Index","Switch","Match","Portal","Dynamic","ErrorBoundary"],p=["Suspense","SuspenseList","Await"],a=["Router","Outlet","Redirect","Link"],L=[...l,...p,...a],m=new Set([...l,...p]);function S(n={}){let{controlFlowModule:e="@fluixi/dom",coreModule:i="@fluixi/core",routerModule:s="@fluixi/core/router-next"}=n,o={};for(let d of l)o[d]=e;for(let d of p)o[d]=i;for(let d of a)o[d]=s;return o}var R={kind:"eager"};function b(n,e={}){let{resolver:i,isBound:s,modules:o,strategyFor:d}=e,g=S(o),x=new Map,v=new Set,E=t=>{let{name:r}=t;if(!r||r.includes(".")||s?.(r))return;let u=O(r);if(!u){v.add(r);return}let C=u.origin==="builtin"&&m.has(r)?R:d?.(t)??R;t.source={...u,loading:C},x.set(r,t.source)},O=t=>{if(m.has(t))return{module:g[t],export:t,origin:"builtin"};let r=i?.resolve(t);if(r)return{module:r.module,export:r.export,origin:"rule"};if(a.includes(t))return{module:g[t],export:t,origin:"builtin"}};return f(n,t=>{t.kind==="component"&&E(t)}),{resolved:x,unresolved:[...v]}}function f(n,e){let i=Array.isArray(n)?n:[n];for(let s of i){e(s);let o=s.children;o&&f(o,e)}}

package/dist/resolve/resolve-ir.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The resolve pass: annotate component references in the IR with where they come from.
+ *
+ * Runs between the frontends and the optimizer, so every later pass reads provenance off
+ * the node instead of re-deriving it. Nothing here emits code — the pass only records a
+ * decision, which is what lets the same answer drive import injection, chunk grouping,
+ * hint planning and diagnostics without any of them agreeing by coincidence.
+ *
+ * Two suppliers, in precedence order:
+ *
+ *  1. **Control flow** (`Show`, `For`, `Switch`, …) — the name selects a lowering, so a
+ *     rule cannot re-point it. Recorded as `builtin` so a later pass can tell the
+ *     difference between "configured here" and "fixed by the compiler".
+ *  2. **Configured rules**, then the **router built-ins**. Router components are only an
+ *     import, so a project's own `Link` wins; see `builtins.ts`.
+ *
+ * A name bound in the file is not resolved at all: the author's import always wins, and
+ * the caller supplies those bindings via `isBound`.
+ */
+import type { IRNode, IRComponent, IRComponentSource } from '../ir/nodes.js';
+import type { ComponentResolver } from './component-resolver.js';
+import { builtinComponentMap } from './builtins.js';
+import { type IRLoadStrategy } from './load-directive.js';
+export interface ResolveOptions {
+    /** Rules configured for the project. Omit when the project configures none. */
+    resolver?: ComponentResolver;
+    /** True when the name already has a binding in the file — an import the author wrote. */
+    isBound?: (name: string) => boolean;
+    /** Module overrides, so `routerModule` and friends are honoured. */
+    modules?: Parameters<typeof builtinComponentMap>[0];
+    /**
+     * The `load:` strategy for a reference, when the frontend found one on the tag.
+     * Keyed by node so two usages of the same component can load differently — the
+     * whole reason timing lives at the usage site and location does not.
+     */
+    strategyFor?: (node: IRComponent) => IRLoadStrategy | undefined;
+}
+export interface ResolveReport {
+    /** Every reference the pass annotated, by name. */
+    resolved: Map<string, IRComponentSource>;
+    /**
+     * Capitalised tags nothing supplies and nothing binds.
+     *
+     * These compile to a reference to an identifier that does not exist — the build
+     * succeeds and the page throws at runtime — so they are the pass's most useful
+     * output for diagnostics.
+     */
+    unresolved: string[];
+}
+/** Annotate every component reference in `root`, returning what was decided. */
+export declare function resolveComponentSources(root: IRNode | IRNode[], options?: ResolveOptions): ResolveReport;
+/** Depth-first walk over every node that can contain children. */
+export declare function walk(root: IRNode | IRNode[], visit: (node: IRNode) => void): void;
+//# sourceMappingURL=resolve-ir.d.ts.map

package/dist/resolve/resolve-ir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-ir.d.ts","sourceRoot":"","sources":["../../src/resolve/resolve-ir.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAC7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,EAA0C,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAC5F,OAAO,EAAS,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAEjE,MAAM,WAAW,cAAc;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,yFAAyF;IACzF,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACpC,oEAAoE;IACpE,OAAO,CAAC,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC;IACpD;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,cAAc,GAAG,SAAS,CAAC;CACjE;AAED,MAAM,WAAW,aAAa;IAC5B,mDAAmD;IACnD,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IACzC;;;;;;OAMG;IACH,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,gFAAgF;AAChF,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,EACvB,OAAO,GAAE,cAAmB,GAC3B,aAAa,CA8Cf;AAED,kEAAkE;AAClE,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAOjF"}

package/dist/resolve/resolve-ir.js

@@ -0,0 +1,58 @@
+import { RESERVED_COMPONENTS, ROUTER_COMPONENTS, builtinComponentMap } from './builtins.js';
+import { EAGER } from './load-directive.js';
+/** Annotate every component reference in `root`, returning what was decided. */
+export function resolveComponentSources(root, options = {}) {
+    const { resolver, isBound, modules, strategyFor } = options;
+    const builtins = builtinComponentMap(modules);
+    const resolved = new Map();
+    const unresolved = new Set();
+    const annotate = (node) => {
+        const { name } = node;
+        // A dotted path (`Ctx.Provider`) or a dynamic tag needs its root binding, which is
+        // an ordinary expression the author wrote — nothing to supply.
+        if (!name || name.includes('.'))
+            return;
+        if (isBound?.(name))
+            return;
+        const source = sourceFor(name);
+        if (!source) {
+            unresolved.add(name);
+            return;
+        }
+        // Control flow is lowered by name, so a load strategy on it has nothing to defer;
+        // ignoring it here keeps codegen from having to special-case the combination.
+        const loading = source.origin === 'builtin' && RESERVED_COMPONENTS.has(name)
+            ? EAGER
+            : (strategyFor?.(node) ?? EAGER);
+        node.source = { ...source, loading };
+        resolved.set(name, node.source);
+    };
+    const sourceFor = (name) => {
+        // Control flow first: the name is fixed by the compiler.
+        if (RESERVED_COMPONENTS.has(name)) {
+            return { module: builtins[name], export: name, origin: 'builtin' };
+        }
+        const rule = resolver?.resolve(name);
+        if (rule)
+            return { module: rule.module, export: rule.export, origin: 'rule' };
+        if (ROUTER_COMPONENTS.includes(name)) {
+            return { module: builtins[name], export: name, origin: 'builtin' };
+        }
+        return undefined;
+    };
+    walk(root, (node) => {
+        if (node.kind === 'component')
+            annotate(node);
+    });
+    return { resolved, unresolved: [...unresolved] };
+}
+/** Depth-first walk over every node that can contain children. */
+export function walk(root, visit) {
+    const nodes = Array.isArray(root) ? root : [root];
+    for (const node of nodes) {
+        visit(node);
+        const children = node.children;
+        if (children)
+            walk(children, visit);
+    }
+}

package/dist/resolve/resolve-ir.mjs

@@ -0,0 +1 @@
+var c=["Show","For","Index","Switch","Match","Portal","Dynamic","ErrorBoundary"],l=["Suspense","SuspenseList","Await"],a=["Router","Outlet","Redirect","Link"],C=[...c,...l,...a],p=new Set([...c,...l]);function x(t={}){let{controlFlowModule:i="@fluixi/dom",coreModule:d="@fluixi/core",routerModule:s="@fluixi/core/router-next"}=t,o={};for(let r of c)o[r]=i;for(let r of l)o[r]=d;for(let r of a)o[r]=s;return o}var m={kind:"eager"};function N(t,i={}){let{resolver:d,isBound:s,modules:o,strategyFor:r}=i,R=x(o),f=new Map,g=new Set,S=e=>{let{name:n}=e;if(!n||n.includes(".")||s?.(n))return;let u=E(n);if(!u){g.add(n);return}let O=u.origin==="builtin"&&p.has(n)?m:r?.(e)??m;e.source={...u,loading:O},f.set(n,e.source)},E=e=>{if(p.has(e))return{module:R[e],export:e,origin:"builtin"};let n=d?.resolve(e);if(n)return{module:n.module,export:n.export,origin:"rule"};if(a.includes(e))return{module:R[e],export:e,origin:"builtin"}};return v(t,e=>{e.kind==="component"&&S(e)}),{resolved:f,unresolved:[...g]}}function v(t,i){let d=Array.isArray(t)?t:[t];for(let s of d){i(s);let o=s.children;o&&v(o,i)}}export{N as resolveComponentSources,v as walk};

package/dist/resolve/write-globals.cjs

@@ -0,0 +1,22 @@
+"use strict";var x=Object.defineProperty;var D=Object.getOwnPropertyDescriptor;var L=Object.getOwnPropertyNames;var _=Object.prototype.hasOwnProperty;var W=(e,n)=>{for(var o in n)x(e,o,{get:n[o],enumerable:!0})},B=(e,n,o,r)=>{if(n&&typeof n=="object"||typeof n=="function")for(let t of L(n))!_.call(e,t)&&t!==o&&x(e,t,{get:()=>n[t],enumerable:!(r=D(n,t))||r.enumerable});return e};var P=e=>B(x({},"__esModule",{value:!0}),e);var Z={};W(Z,{DEFAULT_GLOBALS_PATH:()=>N,writeComponentGlobals:()=>V});module.exports=P(Z);var f=require("node:fs"),c=require("node:path");var F=e=>"components"in e;function O(e,n){return e.replace(/\$(\d+)/g,(o,r)=>n[Number(r)]??o)}function I(e,n){return typeof n=="string"?{module:n,export:e}:n}function w(e=[]){let n=new Map,o=[],r=[];for(let i of e){if(!F(i)){r.push(i);continue}for(let[l,p]of Object.entries(i.components)){let u=I(l,p),m=n.get(l);if(m&&m.module!==u.module){let g=o.find(R=>R.name===l);g?g.modules.push(u.module):o.push({name:l,modules:[m.module,u.module]});continue}n.set(l,u)}}let t=new Map;return{resolve:i=>{if(t.has(i))return t.get(i);let l=n.get(i);if(!l)for(let p of r){let u=i.match(new RegExp(p.match.source,p.match.flags.replace("g","")));if(u){l={module:O(p.module,u),export:p.export?O(p.export,u):i};break}}return t.set(i,l),l},names:()=>[...n.keys()],conflicts:()=>o}}var b=["Show","For","Index","Switch","Match","Portal","Dynamic","ErrorBoundary"],C=["Suspense","SuspenseList","Await"],M=["Router","Outlet","Redirect","Link"],ne=[...b,...C,...M],te=new Set([...b,...C]);function E(e={}){let{controlFlowModule:n="@fluixi/dom",coreModule:o="@fluixi/core",routerModule:r="@fluixi/core/router-next"}=e,t={};for(let a of b)t[a]=n;for(let a of C)t[a]=o;for(let a of M)t[a]=r;return t}var U=new Set(["Text","Image","Option","Audio","Comment","Range","Selection","Notification","Event","Document","Element","Node","Screen","Window","Location","History","Storage","Response","Request","Headers"]);function H(e){if(e.startsWith(".")||e.startsWith("/")||/^[~@]\//.test(e))return;let n=e.split("/");return e.startsWith("@")?n.slice(0,2).join("/"):n[0]}function S(e){return`_${e.replace(/[^A-Za-z0-9]/g,"_")}`}function $(e,n={}){let{available:o,builtins:r=!0,generator:t="@fluixi/compiler",specifier:a=s=>s}=n,i=[...e];r&&i.push({components:E()});let l=w(i),p=o?new Set(o):void 0,u=[],m=[],g=[],R=new Map;for(let s of[...l.names()].sort()){let d=l.resolve(s);if(!d)continue;let h=H(d.module);U.has(s)?m.push(s):p&&h&&!p.has(h)?g.push(s):(u.push(s),R.set(s,d))}let y=[...new Set(u.map(s=>R.get(s).module))].sort().map(s=>`import * as ${S(s)} from '${a(s)}';`),A=u.map(s=>{let d=R.get(s),h=S(d.module);return d.export==="default"?`  const ${s}: typeof ${h}.default;`:`  export import ${s} = ${h}.${d.export};`}),G=m.length>0?`//
+// Import these explicitly — lib.dom already declares the name, so an ambient
+// declaration cannot win:
+`+m.map(s=>{let d=l.resolve(s)?.module;return`//   import { ${s} } from '${d?a(d):""}';
+`}).join(""):"",v=e.filter(s=>"match"in s).length,k=v>0?`//
+// ${v} pattern rule${v===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.
+`:"";return{source:`// GENERATED by ${t} — do not edit.
+//
+// The components \`resolve\` supplies without an import. This describes what the
+// compiler already does; it does not enable it.
+`+G+k+(y.length>0?`
+${y.join(`
+`)}
+`:`
+`)+`
+declare global {
+${A.join(`
+`)}
+}
+`,declared:u,shadowedByDom:m,unavailable:g,patternRules:v}}var J="GENERATED by @fluixi/compiler",N="fluixi.d.ts";function q(e,n){let o;try{let t=(0,f.readFileSync)((0,c.resolve)(e,"tsconfig.json"),"utf8");o=JSON.parse(t.replace(/^\s*\/\/.*$/gm,""))}catch{return}if(o.extends!==void 0)return;if(!Array.isArray(o.include))return!0;let r=T(e,n);return o.include.some(t=>{if(typeof t!="string")return!1;let a=t.replace(/[.+^${}()|[\]\\]/g,"\\$&").replace(/\*\*\//g,"(?:.*/)?").replace(/\*/g,"[^/]*");return new RegExp(`^${a}(?:/.*)?$`).test(r)})}function T(e,n){return(0,c.relative)(e,n).split(c.sep).join("/")}function z(e,n,o){if(!e.startsWith("/"))return e;let r=(0,c.resolve)(o,e.slice(1)),t=(0,c.relative)(n,r).split(c.sep).join("/");return t.startsWith(".")||(t=`./${t}`),t.replace(/\.(tsx|ts|jsx|mts|cts)$/,".js")}function K(e){try{let n=JSON.parse((0,f.readFileSync)((0,c.resolve)(e,"package.json"),"utf8"));return[...Object.keys(n.dependencies??{}),...Object.keys(n.devDependencies??{}),...Object.keys(n.peerDependencies??{})]}catch{return}}function V(e,n){if(e.globals===!1)return{status:"skipped",reason:"disabled"};let o=e.resolve??[],r=(0,c.resolve)(n,e.globals??N),t;try{t=(0,f.readFileSync)(r,"utf8")}catch{t=void 0}if(t!==void 0&&!t.includes(J))return{status:"skipped",reason:"foreign-file",path:r};let{source:a,declared:i}=$(o,{available:K(n),specifier:l=>z(l,(0,c.dirname)(r),n)});return t===a?{status:"unchanged",path:r,declared:i.length,warning:j(n,r)}:((0,f.mkdirSync)((0,c.dirname)(r),{recursive:!0}),(0,f.writeFileSync)(r,a),{status:"written",path:r,declared:i.length,warning:j(n,r)})}function j(e,n){if(q(e,n)!==!1)return;let o=T(e,n);return`[fluixi] ${o} is not covered by "include" in tsconfig.json, so TypeScript will ignore it and every resolved component stays "Cannot find name". Add "${o}" to "include".`}

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

@@ -0,0 +1,31 @@
+import type { ComponentResolverRule } from './component-resolver.js';
+export declare const DEFAULT_GLOBALS_PATH = "fluixi.d.ts";
+export interface WriteGlobalsOptions {
+    resolve?: readonly ComponentResolverRule[];
+    globals?: string | false;
+}
+export type WriteGlobalsOutcome = ({
+    status: 'written';
+    path: string;
+    declared: number;
+} | {
+    status: 'unchanged';
+    path: string;
+    declared: number;
+} | {
+    status: 'skipped';
+    reason: 'disabled' | 'foreign-file';
+    path?: string;
+}) & {
+    /**
+     * Set when the file was written somewhere TypeScript will not read it.
+     *
+     * Worth surfacing because the symptom is indistinguishable from the generator never
+     * having run: every resolved tag is still `Cannot find name`, and the file sitting
+     * right there makes it look like it should have worked.
+     */
+    warning?: string;
+};
+/** Generate and write the declarations for `root`, returning what was done. */
+export declare function writeComponentGlobals(options: WriteGlobalsOptions, root: string): WriteGlobalsOutcome;
+//# sourceMappingURL=write-globals.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"write-globals.d.ts","sourceRoot":"","sources":["../../src/resolve/write-globals.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAKrE,eAAO,MAAM,oBAAoB,gBAAgB,CAAC;AAElD,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC3C,OAAO,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;CAC1B;AAED,MAAM,MAAM,mBAAmB,GAAG,CAC9B;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACvD;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,UAAU,GAAG,cAAc,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAC5E,GAAG;IACF;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AA2EF,+EAA+E;AAC/E,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,mBAAmB,EAC5B,IAAI,EAAE,MAAM,GACX,mBAAmB,CAwCrB"}