@fluixi/compiler 1.0.0-alpha.68 → 1.0.0-alpha.70

package/dist/frontend/babel/plugin.js

@@ -11,6 +11,11 @@
  * - Control flow optimization
  */
 import { declare } from '@babel/helper-plugin-utils';
+import { createComponentResolver, } from '../../resolve/component-resolver.js';
+import { resolveComponentSources } from '../../resolve/resolve-ir.js';
+import { collapseStrategies } from '../../optimize/collapse-strategies.js';
+import { EAGER, isDeferred, isLoadDirective, parseLoadDirective, LoadDirectiveError, } from '../../resolve/load-directive.js';
+import { DOM_CONTROL_FLOW, CORE_CONTROL_FLOW, ROUTER_COMPONENTS as ROUTER_COMPONENT_NAMES, } from '../../resolve/builtins.js';
 import { types as t, template, } from '@babel/core';
 import { buildIR } from './build-ir.js';
 import { buildIRFromLit } from './build-ir-lit.js';
@@ -18,27 +23,17 @@ import { imperativeBackend } from '../../codegen/backends/imperative.js';
 // ============================================================================
 // Constants
 // ============================================================================
-const CONTROL_FLOW_COMPONENTS = new Set([
-    'Show',
-    'For',
-    'Index',
-    'Switch',
-    'Match',
-    'Portal',
-    'Dynamic',
-    'ErrorBoundary',
-    'Suspense',
-    'SuspenseList',
-    'Await',
-]);
+// The names come from `resolve/builtins.ts`, which publishes them for the TS plugin,
+// the language server and codemods — tools that need to know where `<Show>` comes from
+// but must not re-derive it. What stays here is the part that is genuinely codegen:
+// which names get special lowering, reactive-getter props, and memo exemption.
+const CONTROL_FLOW_COMPONENTS = new Set([...DOM_CONTROL_FLOW, ...CORE_CONTROL_FLOW]);
 // Control-flow components that live in @fluixi/core, NOT @fluixi/dom — they must
 // be auto-imported from core (dom doesn't export them).
-const CORE_ONLY_CONTROL_FLOW = new Set(['Suspense', 'SuspenseList', 'Await']);
+const CORE_ONLY_CONTROL_FLOW = new Set(CORE_CONTROL_FLOW);
 // Router components auto-imported (from routerModule) the same way control flow is:
 // use `<Router>`/`<Outlet>`/… in a template and the import is injected if absent.
-// (`Routes` isn't a component — routing is `<Router routes={…}>`; `lazy` is a function
-// call, not a tag, so neither can be auto-imported this way.)
-const ROUTER_COMPONENTS = new Set(['Router', 'Outlet', 'Redirect', 'Link']);
+const ROUTER_COMPONENTS = new Set(ROUTER_COMPONENT_NAMES);
 // Control-flow components read a single reactive *value* prop inside their own tracking
 // scope. Emit that prop as a getter (like `children`) so reading it re-runs the caller's
 // expression — otherwise `each={items()}` / `when={cond()}` snapshot once and never update.
@@ -84,17 +79,24 @@ const DELEGATABLE_EVENTS = [
 // ============================================================================
 export default declare((api, options = {}) => {
     api.assertVersion(7);
-    const { runtime = 'automatic', importSource = '@fluixi/jsx', pragma = 'jsx', pragmaFrag = 'Fragment', development = false, detectReactivity = true, useLitHTML = true, hoistStatics = true, delegateEvents = true, delegatedEvents = DELEGATABLE_EVENTS, optimizeControlFlow = true, sourceMaps = true, signalModule = '@fluixi/dom', controlFlowModule = '@fluixi/dom', routerModule = '@fluixi/core/router-next', reactiveModule = '@fluixi/reactive/signal', autoShowTransform = false, backend = 'imperative', codegen = 'inline', 
+    const { runtime = 'automatic', importSource = '@fluixi/jsx', pragma = 'jsx', pragmaFrag = 'Fragment', development = false, detectReactivity = true, useLitHTML = true, hoistStatics = true, delegateEvents = true, delegatedEvents = DELEGATABLE_EVENTS, optimizeControlFlow = true, sourceMaps = true, signalModule = '@fluixi/dom', controlFlowModule = '@fluixi/dom', routerModule = '@fluixi/core/router-next', reactiveModule = '@fluixi/reactive/signal', autoShowTransform = false, backend = 'imperative', codegen = 'inline', templateClone = true, partialTemplates = true, 
     // `both` by default: JSX and html`` are compiled out of the box, so
     // `fluixi()` needs no `format` option. Injected imports are deduped, so a
     // file mixing the two styles won't redeclare a binding.
-    format = 'both', litTag = 'html', } = options;
+    format = 'both', litTag = 'html', resolve: resolveRules = [], } = options;
+    // Built once per plugin instance, not per file: the rules are static and the
+    // resolver memoises lookups, so every file in the build shares one cache.
+    const componentResolver = createComponentResolver(resolveRules);
     const compileLit = format === 'lit' || format === 'both';
     const pluginState = {
         backend,
         codegen,
         irImports: new Set(),
         libModule: '@fluixi/core',
+        controlFlowModule,
+        routerModule,
+        templateClone,
+        partialTemplates,
         hasJSX: false,
         hasReactivity: false,
         hasLitHTML: false,
@@ -102,8 +104,12 @@ export default declare((api, options = {}) => {
         needsControlFlowImport: false,
         needsCreateMemo: false,
         controlFlowComponents: new Set(),
+        resolvedComponents: new Map(),
+        deferredComponents: new Map(),
+        componentResolver,
         delegatedEvents: new Set(),
         staticElements: new Map(),
+        staticTemplates: new Map(),
         staticCounter: 0,
     };
     return {
@@ -139,11 +145,19 @@ export default declare((api, options = {}) => {
                         needsControlFlowImport: false,
                         needsCreateMemo: false,
                         controlFlowComponents: new Set(),
+                        resolvedComponents: new Map(),
+                        deferredComponents: new Map(),
+                        componentResolver,
                         delegatedEvents: new Set(),
                         staticElements: new Map(),
+                        staticTemplates: new Map(),
                         autoShow: autoShowTransform,
                         staticCounter: 0,
                         libModule: '@fluixi/core',
+                        controlFlowModule,
+                        routerModule,
+                        templateClone,
+                        partialTemplates,
                         backend,
                         codegen,
                         irImports: new Set(),
@@ -211,7 +225,10 @@ export default declare((api, options = {}) => {
                                 imports.push(t.importDeclaration(specifiers, t.stringLiteral(signalModule)));
                             }
                         }
-                        else if (state.hasJSX && runtime === 'automatic') {
+                        else if (state.hasJSX && runtime === 'automatic' && backend !== 'imperative') {
+                            // Not under the imperative backend: `codegen: 'ir'` lands here because the
+                            // branch above excludes it, and emitted an unused jsx/jsxs/Fragment import.
+                            // The IR path produces runtime calls, never JSX factory calls.
                             // Add JSX runtime imports
                             const specifiers = [
                                 t.importSpecifier(t.identifier('jsx'), t.identifier('jsx')),
@@ -255,6 +272,50 @@ export default declare((api, options = {}) => {
                             if (fromRouter.length > 0)
                                 imports.push(declFor(fromRouter, routerModule));
                         }
+                        // Imports for tags matched by the `resolve` rules. Same binding guard as
+                        // control flow: a hand-written import or a local of the same name wins, so
+                        // enabling resolution can never change what an existing file means.
+                        //
+                        // Grouped by module so several components from one package share a single
+                        // declaration, and emitted with the local name equal to the tag — the
+                        // generated code refers to the tag, not to the export.
+                        // Deferred components become value bindings, not imports: a literal
+                        // `import()` is what lets the bundler split, hash and tree-shake the chunk
+                        // as ordinary behaviour rather than as an integration.
+                        const deferredDecls = [];
+                        if (state.deferredComponents.size > 0) {
+                            for (const [local, entry] of state.deferredComponents) {
+                                if (path.scope.hasBinding(local))
+                                    continue;
+                                deferredDecls.push(t.variableDeclaration('const', [
+                                    t.variableDeclarator(t.identifier(local), t.callExpression(t.identifier('deferred'), [
+                                        t.arrowFunctionExpression([], t.callExpression(t.import(), [t.stringLiteral(entry.module)])),
+                                        t.objectExpression([
+                                            t.objectProperty(t.identifier('strategy'), strategyLiteral(entry.strategy)),
+                                            t.objectProperty(t.identifier('export'), t.stringLiteral(entry.export)),
+                                        ]),
+                                    ])),
+                                ]));
+                            }
+                            if (deferredDecls.length > 0 && !path.scope.hasBinding('deferred')) {
+                                imports.push(t.importDeclaration([t.importSpecifier(t.identifier('deferred'), t.identifier('deferred'))], t.stringLiteral(state.libModule ?? '@fluixi/core')));
+                            }
+                        }
+                        if (state.resolvedComponents.size > 0) {
+                            const byModule = new Map();
+                            for (const [local, resolved] of state.resolvedComponents) {
+                                if (path.scope.hasBinding(local))
+                                    continue;
+                                const list = byModule.get(resolved.module) ?? [];
+                                list.push({ local, exported: resolved.export });
+                                byModule.set(resolved.module, list);
+                            }
+                            for (const [mod, entries] of byModule) {
+                                imports.push(t.importDeclaration(entries.map(({ local, exported }) => exported === 'default'
+                                    ? t.importDefaultSpecifier(t.identifier(local))
+                                    : t.importSpecifier(t.identifier(local), t.identifier(exported))), t.stringLiteral(mod)));
+                            }
+                        }
                         // Add event delegation setup if needed
                         if (delegateEvents && state.delegatedEvents.size > 0) {
                             imports.push(t.importDeclaration([
@@ -275,6 +336,28 @@ export default declare((api, options = {}) => {
                             });
                             path.node.body.unshift(...hoisted);
                         }
+                        // After the hoisted statics but before imports are unshifted, so the
+                        // final order is: imports, deferred bindings, everything else.
+                        if (deferredDecls.length > 0) {
+                            path.node.body.unshift(...deferredDecls);
+                        }
+                        // Static templates, parsed once per module rather than per instance.
+                        if (state.staticTemplates.size > 0) {
+                            const decls = [];
+                            for (const [key, name] of state.staticTemplates) {
+                                const svg = key.startsWith('svg:');
+                                const html = svg ? key.slice(4) : key;
+                                decls.push(t.variableDeclaration('const', [
+                                    t.variableDeclarator(t.identifier(name), 
+                                    // Just the HTML. Parsing is deferred to `templateNode`, which
+                                    // knows whether this is a server render, a hydration or a fresh
+                                    // client render — a module-scope `createTemplate` would touch
+                                    // `document` at import time and break SSR outright.
+                                    t.stringLiteral(html)),
+                                ]));
+                            }
+                            path.node.body.unshift(...decls);
+                        }
                     }
                     // Add all imports at the top, deduped. When a file mixes inline JSX
                     // and html`` (format 'both'), the two injection paths can each emit an
@@ -296,9 +379,12 @@ export default declare((api, options = {}) => {
                 const element = path.node;
                 const openingElement = element.openingElement;
                 // Router components auto-import like control flow, but aren't optimized —
-                // just register the name so the import gets injected if it isn't bound.
+                // just register the name so the import gets injected if it isn't bound. A
+                // configured rule takes precedence; registering anyway would inject the
+                // router's import alongside the resolved one and bind the name twice.
                 if (t.isJSXIdentifier(openingElement.name) &&
-                    ROUTER_COMPONENTS.has(openingElement.name.name)) {
+                    ROUTER_COMPONENTS.has(openingElement.name.name) &&
+                    !state.componentResolver?.resolve(openingElement.name.name)) {
                     state.controlFlowComponents.add(openingElement.name.name);
                     state.needsControlFlowImport = true;
                 }
@@ -494,11 +580,102 @@ function emitImperativeElement(tag, isNative, props, spreads, children, state) {
  * `createMemo(() => createComponent(Comp, props))` — same shape jsx-runtime
  * produces for components, so it stays reactive when used as a child.
  */
+/**
+ * Read a `load:` attribute's literal value. A `${…}` hole is rejected: the strategy
+ * decides how the module is emitted, so it has to be known at compile time.
+ */
+function readLoadDirective(name, attr) {
+    let value = null;
+    if (attr.value) {
+        if (t.isStringLiteral(attr.value))
+            value = attr.value.value;
+        else {
+            throw new LoadDirectiveError(`'${name}' needs a literal value, not an expression — the strategy is compile-time.`);
+        }
+    }
+    return parseLoadDirective(name, value);
+}
+/**
+ * Two usages of one component in the same file share a binding, so their strategies
+ * have to agree. The earlier-loading one wins: the module is in whichever chunk loads
+ * first regardless, so deferring the other buys nothing — the same reasoning as the
+ * collapse pass, applied within a file.
+ */
+/** The strategy as an object literal the runtime can read. */
+function strategyLiteral(strategy) {
+    const props = [
+        t.objectProperty(t.identifier('kind'), t.stringLiteral(strategy.kind)),
+    ];
+    if (strategy.kind === 'visible' && strategy.rootMargin) {
+        props.push(t.objectProperty(t.identifier('rootMargin'), t.stringLiteral(strategy.rootMargin)));
+    }
+    if (strategy.kind === 'interaction') {
+        props.push(t.objectProperty(t.identifier('events'), t.arrayExpression(strategy.events.map((e) => t.stringLiteral(e)))));
+    }
+    if (strategy.kind === 'media') {
+        props.push(t.objectProperty(t.identifier('query'), t.stringLiteral(strategy.query)));
+    }
+    return t.objectExpression(props);
+}
+function mergeStrategy(existing, incoming) {
+    if (!isDeferred(existing) || !isDeferred(incoming))
+        return EAGER;
+    return existing;
+}
 function emitComponentCall(comp, propsObj, state) {
-    // Router components (Router/Outlet/…) auto-import like control flow — register the
-    // name here (the nested lowering chokepoint) so `<Outlet/>` inside markup is caught,
-    // not only a top-level router tag. Unbound names are injected at Program.exit.
-    if (t.isIdentifier(comp) && ROUTER_COMPONENTS.has(comp.name)) {
+    // Configured tags register here rather than in the JSX element visitor: this is the
+    // chokepoint every component passes through, and the visitor missed children because
+    // a lowered parent is replaced before its subtree is walked.
+    //
+    // A configured rule wins over the router built-ins. Those are only an import — no
+    // special lowering, no reactive-getter props — so letting a project's own `Link` lose
+    // to them silently was the same failure `Switch` has: the tag renders the router's
+    // component and nothing reports it. Control flow still wins, because there the name
+    // selects codegen and a rule cannot supply that.
+    // Control flow needs its import injected too, and registering it here rather than in
+    // the JSX visitor is what makes nested usage work: a lowered parent is replaced before
+    // its subtree is walked, so `<div><Show/></div>` never reached the visitor and `Show`
+    // compiled to a reference to nothing. Every fixture imported Show by hand, so nothing
+    // caught it.
+    if (t.isIdentifier(comp) && CONTROL_FLOW_COMPONENTS.has(comp.name)) {
+        state.controlFlowComponents.add(comp.name);
+        state.needsControlFlowImport = true;
+    }
+    let resolvedByRule = false;
+    if (t.isIdentifier(comp) && !CONTROL_FLOW_COMPONENTS.has(comp.name) && state.componentResolver) {
+        const resolved = state.componentResolver.resolve(comp.name);
+        if (resolved) {
+            const strategy = state.pendingLoad ?? EAGER;
+            // An eager usage seen earlier in the file already put the module in the chunk,
+            // so a later deferred usage of the same name collapses to eager. Without this the
+            // file gets both a static import and a `const` for one name — a redeclaration.
+            const alreadyEager = state.resolvedComponents.has(comp.name);
+            if (isDeferred(strategy) && !alreadyEager) {
+                // A deferred component becomes a `deferred(() => import(...))` binding rather
+                // than a static import, so the bundler puts it in its own chunk.
+                const existing = state.deferredComponents.get(comp.name);
+                const merged = existing ? mergeStrategy(existing.strategy, strategy) : strategy;
+                if (isDeferred(merged)) {
+                    state.deferredComponents.set(comp.name, { ...resolved, strategy: merged });
+                }
+                else {
+                    state.deferredComponents.delete(comp.name);
+                    state.resolvedComponents.set(comp.name, resolved);
+                }
+            }
+            else {
+                // An eager usage anywhere wins: the module is in the chunk already.
+                state.deferredComponents.delete(comp.name);
+                state.resolvedComponents.set(comp.name, resolved);
+            }
+            resolvedByRule = true;
+        }
+    }
+    state.pendingLoad = undefined;
+    // Router components auto-import like control flow — register the name here so
+    // `<Outlet/>` nested in markup is caught, not only a top-level router tag. Unbound
+    // names are injected at Program.exit.
+    if (!resolvedByRule && t.isIdentifier(comp) && ROUTER_COMPONENTS.has(comp.name)) {
         state.controlFlowComponents.add(comp.name);
         state.needsControlFlowImport = true;
     }
@@ -518,17 +695,54 @@ function emitComponentCall(comp, propsObj, state) {
  * Produces the same runtime calls as the inline path — this is the route a future
  * swc front-end reuses.
  */
+/**
+ * Hoist the backend's static templates to module scope and rewrite the emitted code to
+ * reference them. Deduped by HTML, so a subtree repeated in a file is parsed once.
+ */
+function adoptTemplates(code, templates, state) {
+    if (!templates || templates.length === 0)
+        return code;
+    const rename = new Map();
+    for (const tpl of templates) {
+        const key = `${tpl.svg ? 'svg:' : ''}${tpl.html}`;
+        let name = state.staticTemplates.get(key);
+        if (!name) {
+            name = `_tmpl$${state.staticTemplates.size}`;
+            state.staticTemplates.set(key, name);
+        }
+        rename.set(tpl.id, name);
+    }
+    // One pass, not one replacement per id. The backend's local ids and the hoisted names
+    // share the `_tmpl$N` namespace, so replacing them in sequence can rewrite a name that
+    // an earlier replacement just produced — which silently points a template at another
+    // template's HTML.
+    return code.replace(/_tmpl\$\d+/g, (id) => rename.get(id) ?? id);
+}
 function emitViaIR(node, state) {
     // `used` collects runtime symbols emitted for JSX nested inside expressions
     // (render-props, ternaries, fallback={<p/>}, …) so we import them too.
     const used = new Set();
     const ir = buildIR(node, used);
-    const { code, imports } = imperativeBackend.emit(ir, {});
+    // The same passes the lit path runs. Without them `codegen: 'ir'` silently skipped
+    // resolution entirely — a resolved tag compiled to a reference with no import.
+    resolveComponentSources(ir, {
+        resolver: state.componentResolver,
+        modules: {
+            controlFlowModule: state.controlFlowModule,
+            coreModule: state.libModule,
+            routerModule: state.routerModule,
+        },
+        strategyFor: (n) => n.load,
+    });
+    collapseStrategies(ir);
+    const { code, imports, templates } = imperativeBackend.emit(ir, { templateClone: state.templateClone, partialTemplates: state.partialTemplates });
     for (const s of imports)
         used.add(s);
     for (const s of used)
         state.irImports.add(s);
-    return template.expression(code, { placeholderPattern: false, plugins: ['typescript'] })();
+    collectRuntimeNeeds(ir, state);
+    const adopted = adoptTemplates(code, templates, state);
+    return template.expression(adopted, { placeholderPattern: false, plugins: ['typescript'] })();
 }
 /**
  * Merge injected import declarations so no module/name pair is imported twice.
@@ -572,7 +786,23 @@ function emitLitViaIR(node, state) {
     const used = new Set();
     const svg = t.isIdentifier(node.tag) && node.tag.name === 'svg';
     const ir = buildIRFromLit(node, used, { svg });
-    const { code, imports } = imperativeBackend.emit(ir, {});
+    // Resolve pass: annotate each component reference with where it comes from, before
+    // codegen. Bindings are not checked here — Program.exit knows the whole file's scope
+    // and drops any injected import whose name turns out to be bound.
+    resolveComponentSources(ir, {
+        resolver: state.componentResolver,
+        modules: {
+            controlFlowModule: state.controlFlowModule,
+            coreModule: state.libModule,
+            routerModule: state.routerModule,
+        },
+        strategyFor: (node) => node.load,
+    });
+    // Demote deferred references whose module is already in this chunk: a lazy boundary
+    // around something already present adds a wrapper, a promise and a re-render to
+    // fetch nothing.
+    collapseStrategies(ir);
+    const { code, imports, templates } = imperativeBackend.emit(ir, { templateClone: state.templateClone, partialTemplates: state.partialTemplates });
     for (const s of imports)
         used.add(s);
     for (const s of used)
@@ -583,7 +813,7 @@ function emitLitViaIR(node, state) {
     // position — which is why compiled html`` had no source map at all. Give every
     // generated node the template's own location so a breakpoint or stack frame
     // lands on the template instead of nowhere.
-    const expression = template.expression(code, {
+    const expression = template.expression(adoptTemplates(code, templates, state), {
         placeholderPattern: false,
         plugins: ['typescript'],
     })();
@@ -630,10 +860,29 @@ function inheritLocation(target, source) {
  * (-> auto-import from the control-flow module, like the inline JSX path).
  */
 function collectRuntimeNeeds(node, state) {
-    if (node.kind === 'component' &&
-        (CONTROL_FLOW_COMPONENTS.has(node.name) || ROUTER_COMPONENTS.has(node.name))) {
-        state.controlFlowComponents.add(node.name);
-        state.needsControlFlowImport = true;
+    if (node.kind === 'component' && node.source) {
+        // Provenance was decided by the resolve pass and recorded on the node; this only
+        // translates it into the two things Program.exit wires. Reading it here rather
+        // than re-resolving is the point — one decision, so import injection and every
+        // later pass cannot disagree.
+        if (node.source.origin === 'builtin') {
+            state.controlFlowComponents.add(node.name);
+            state.needsControlFlowImport = true;
+        }
+        else if (isDeferred(node.source.loading) && !state.resolvedComponents.has(node.name)) {
+            state.deferredComponents.set(node.name, {
+                module: node.source.module,
+                export: node.source.export,
+                strategy: node.source.loading,
+            });
+        }
+        else {
+            state.deferredComponents.delete(node.name);
+            state.resolvedComponents.set(node.name, {
+                module: node.source.module,
+                export: node.source.export,
+            });
+        }
     }
     if (node.kind === 'element' || node.kind === 'component' || node.kind === 'control') {
         if ('props' in node) {
@@ -836,6 +1085,9 @@ function transformAttributes(attributes, state, isNativeElement = true, tagName
     const props = [];
     const spreads = [];
     const cfValueProp = CONTROL_FLOW_VALUE_PROPS[tagName];
+    // `load:` is a directive, not a prop — it says when this component's module is
+    // fetched. Cleared per element so a strategy cannot leak onto the next tag.
+    state.pendingLoad = undefined;
     for (const attr of attributes) {
         if (t.isJSXSpreadAttribute(attr)) {
             // Collect spread expressions separately
@@ -843,6 +1095,11 @@ function transformAttributes(attributes, state, isNativeElement = true, tagName
         }
         else if (t.isJSXAttribute(attr)) {
             const name = getAttributeName(attr.name);
+            if (isLoadDirective(name)) {
+                // Same parser the html`` lowering uses, so the two syntaxes cannot drift.
+                state.pendingLoad = readLoadDirective(name, attr);
+                continue;
+            }
             const value = transformAttributeValue(attr.value, state, name, isNativeElement);
             // Detect event handlers for delegation
             if (EVENT_PROPS.test(name)) {