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

package/dist/ir/nodes.d.ts

@@ -4,6 +4,8 @@
  * between parsing and code generation — the layer your own improvements
  * (hoisting, islands, resumability hints) transform.
  */
+import type { IRLoadStrategy } from '../resolve/load-directive.js';
+export type { IRLoadStrategy };
 export interface SourceSpan {
     start: number;
     end: number;
@@ -46,11 +48,52 @@ export interface IRElement {
     static: boolean;
     loc?: SourceSpan;
 }
+/**
+ * Where a component reference comes from, attached to the reference itself.
+ *
+ * A capitalised tag with no binding in the file is supplied by the compiler — from a
+ * `resolve` rule, or from the built-in control-flow/router sets. That decision used to
+ * live only in the Babel plugin's state, which meant the IR could not see which
+ * components a template referenced: no pass could vary a decision per usage, group
+ * references into chunks, or drop a subtree it knows is server-only. Recording it on
+ * the node is what turns resolution from a convenience into something later passes can
+ * read.
+ *
+ * `origin` distinguishes the two suppliers because they behave differently: a `rule`
+ * is configuration and may be overridden or re-targeted, while a `builtin` control-flow
+ * name also selects codegen and cannot be re-pointed at another module.
+ */
+export interface IRComponentSource {
+    module: string;
+    /** The export to import, or `default`. */
+    export: string;
+    origin: 'rule' | 'builtin';
+    /**
+     * When the module is fetched. Set from a `load:` directive at the usage site, and
+     * `eager` otherwise — resolution decides where a component comes from, this decides
+     * when, and the two vary independently.
+     */
+    loading: IRLoadStrategy;
+    /** Assigned by the optimizer once references are grouped. */
+    chunk?: string;
+}
 export interface IRComponent {
     kind: 'component';
     name: string;
     props: IRProp[];
     children: IRNode[];
+    /**
+     * Set by the resolve pass when the compiler supplies this reference. Absent when the
+     * name is bound in the file — an ordinary import the author wrote — or when nothing
+     * claims it, which is a diagnostic rather than a resolution.
+     */
+    source?: IRComponentSource;
+    /**
+     * A `load:` strategy read off the tag by the frontend. The resolve pass folds it into
+     * `source.loading`; it lives here first because the frontend knows the directive and
+     * the resolve pass knows whether the name is deferrable at all.
+     */
+    load?: IRLoadStrategy;
     loc?: SourceSpan;
 }
 export interface IRText {

package/dist/ir/nodes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nodes.d.ts","sourceRoot":"","sources":["../../src/ir/nodes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IAAG,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;CAAE;AAE3D,MAAM,MAAM,MAAM,GACd,SAAS,GACT,WAAW,GACX,MAAM,GACN,YAAY,GACZ,SAAS,GACT,UAAU,CAAC;AAEf,MAAM,MAAM,UAAU,GAClB,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAC;AAErE,MAAM,WAAW,MAAM;IACrB,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,CAAC;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;IAC3C,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oFAAoF;IACpF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,sEAAsE;IACtE,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC;CAC9C;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,SAAS,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,iFAAiF;IACjF,MAAM,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,UAAU,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,GAAG,CAAC,EAAE,UAAU,CAAC;CAClB;AAED,MAAM,WAAW,MAAM;IAAG,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,UAAU,CAAC;CAAE;AAE1E,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;IAClB,GAAG,CAAC,EAAE,UAAU,CAAC;CAClB;AAED,MAAM,WAAW,UAAU;IAAG,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,GAAG,CAAC,EAAE,UAAU,CAAC;CAAE;AAEvF,MAAM,MAAM,WAAW,GACnB,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAC7C,SAAS,GAAG,eAAe,GAAG,UAAU,CAAC;AAE7C,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,WAAW,CAAC;IACrB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,GAAG,CAAC,EAAE,UAAU,CAAC;CAClB"}
+{"version":3,"file":"nodes.d.ts","sourceRoot":"","sources":["../../src/ir/nodes.ts"],"names":[],"mappings":"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"}

package/dist/optimize/analyze-static.cjs

@@ -0,0 +1 @@
+"use strict";var a=Object.defineProperty;var l=Object.getOwnPropertyDescriptor;var f=Object.getOwnPropertyNames;var p=Object.prototype.hasOwnProperty;var d=(r,e)=>{for(var s in e)a(r,s,{get:e[s],enumerable:!0})},u=(r,e,s,n)=>{if(e&&typeof e=="object"||typeof e=="function")for(let t of f(e))!p.call(r,t)&&t!==s&&a(r,t,{get:()=>e[t],enumerable:!(n=l(e,t))||n.enumerable});return r};var R=r=>u(a({},"__esModule",{value:!0}),r);var y={};d(y,{analyzeStatic:()=>m,staticRoots:()=>x});module.exports=R(y);function h(r){switch(r.kind){case"event":return"event";case"ref":return"ref";case"spread":return"spread";case"class":case"style":return"class-or-style-directive";case"attr":case"prop":return r.reactive?"reactive-prop":r.expr!==void 0?"expression-prop":void 0;default:return"expression-prop"}}function m(r){let e=[],s=new Map,n=t=>{switch(t.kind){case"text":return!0;case"expr":return!1;case"component":case"control":for(let i of t.children)n(i);return!1;case"fragment":for(let i of t.children)n(i);return!1;case"element":{let i=!0;for(let o of t.children)n(o)||(i=!1);let c;for(let o of t.props)if(c=h(o),c)break;return!c&&!i&&(c=I(t)),t.static=!c,c?s.set(t,c):e.push(t),t.static}default:return!1}};for(let t of Array.isArray(r)?r:[r])n(t);return{staticElements:e,reasons:s}}function I(r){for(let e of r.children){if(e.kind==="expr")return"expression-child";if(e.kind==="component")return"component-child";if(e.kind==="control")return"control-child";if(e.kind==="element"&&!e.static||e.kind==="fragment")return"expression-child"}return"expression-child"}function x(r){let e=[],s=n=>{if(n.kind==="element"&&n.static){e.push(n);return}let t=n.children;if(t)for(let i of t)s(i)};for(let n of Array.isArray(r)?r:[r])s(n);return e}

package/dist/optimize/analyze-static.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Static analysis: mark the element subtrees that never change after creation.
+ *
+ * A static subtree can be built once as an HTML string and cloned per instance, instead
+ * of constructed an element at a time. That is the difference between one `cloneNode`
+ * and N `createElement` + N `spread` calls — measured at 2.1x faster for a three-element
+ * row and 2.4x for a nine-element card, with the gap widening as components grow.
+ *
+ * `IRElement.static` has existed since the IR was written, documented as
+ * "subtree has no dynamic parts → hoistable (template-clone)", but was hardcoded `false`
+ * with no producer. This is the producer.
+ *
+ * The analysis is deliberately conservative: marking something static that is not is a
+ * correctness bug (a shared DOM node across renders), while missing one is only a lost
+ * optimisation. Anything not positively known to be inert makes its whole ancestry
+ * dynamic.
+ */
+import type { IRNode, IRElement } from '../ir/nodes.js';
+/** Why a subtree could not be treated as static. Useful for diagnostics and tests. */
+export type DynamicReason = 'reactive-prop' | 'expression-prop' | 'event' | 'ref' | 'spread' | 'class-or-style-directive' | 'expression-child' | 'component-child' | 'control-child';
+export interface StaticReport {
+    /** Elements marked static, in visit order. */
+    staticElements: IRElement[];
+    /** Why each non-static element was rejected, keyed by the element node. */
+    reasons: Map<IRElement, DynamicReason>;
+}
+/**
+ * Mark every static element in the tree, returning what was decided.
+ *
+ * Mutates `IRElement.static` in place, since that field is the contract codegen reads.
+ */
+export declare function analyzeStatic(root: IRNode | IRNode[]): StaticReport;
+/**
+ * The outermost static elements — the roots worth turning into templates.
+ *
+ * Cloning a static child of a static parent is wasted: the parent's template already
+ * contains it.
+ */
+export declare function staticRoots(root: IRNode | IRNode[]): IRElement[];
+//# sourceMappingURL=analyze-static.d.ts.map

package/dist/optimize/analyze-static.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze-static.d.ts","sourceRoot":"","sources":["../../src/optimize/analyze-static.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAU,MAAM,gBAAgB,CAAC;AAEhE,sFAAsF;AACtF,MAAM,MAAM,aAAa,GACrB,eAAe,GACf,iBAAiB,GACjB,OAAO,GACP,KAAK,GACL,QAAQ,GACR,0BAA0B,GAC1B,kBAAkB,GAClB,iBAAiB,GACjB,eAAe,CAAC;AAEpB,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,cAAc,EAAE,SAAS,EAAE,CAAC;IAC5B,2EAA2E;IAC3E,OAAO,EAAE,GAAG,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;CACxC;AA+BD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,YAAY,CA2DnE;AAeD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,EAAE,CAchE"}

package/dist/optimize/analyze-static.js

@@ -0,0 +1,131 @@
+/**
+ * A prop is inert only when it is a plain attribute or property with a literal value.
+ *
+ * `expr` means arbitrary JS, which may read a signal or allocate, so it is dynamic even
+ * when `reactive` is false — a non-reactive expression still has to run per instance.
+ */
+function propReason(prop) {
+    switch (prop.kind) {
+        case 'event':
+            return 'event';
+        case 'ref':
+            return 'ref';
+        case 'spread':
+            return 'spread';
+        case 'class':
+        case 'style':
+            // classList/style objects are built from expressions even when they look literal.
+            return 'class-or-style-directive';
+        case 'attr':
+        case 'prop':
+            if (prop.reactive)
+                return 'reactive-prop';
+            if (prop.expr !== undefined)
+                return 'expression-prop';
+            return undefined;
+        /* c8 ignore next 2 */
+        default:
+            return 'expression-prop';
+    }
+}
+/**
+ * Mark every static element in the tree, returning what was decided.
+ *
+ * Mutates `IRElement.static` in place, since that field is the contract codegen reads.
+ */
+export function analyzeStatic(root) {
+    const staticElements = [];
+    const reasons = new Map();
+    /** Returns whether `node` is static, marking elements bottom-up. */
+    const visit = (node) => {
+        switch (node.kind) {
+            case 'text':
+                return true;
+            case 'expr':
+                // A hole is dynamic even when it is not reactive: its value is computed.
+                return false;
+            case 'component':
+            case 'control':
+                // Both produce their own subtree at runtime, so an ancestor cannot be cloned
+                // wholesale. Still walk in, so nested elements are marked for their own sake.
+                for (const child of node.children)
+                    visit(child);
+                return false;
+            case 'fragment':
+                // A fragment is not an element and cannot itself be cloned, but its children
+                // can be considered independently.
+                for (const child of node.children)
+                    visit(child);
+                return false;
+            case 'element': {
+                // Children are visited first and unconditionally, so a static subtree nested
+                // under a dynamic parent is still marked and can be cloned on its own.
+                let childrenStatic = true;
+                for (const child of node.children) {
+                    if (!visit(child))
+                        childrenStatic = false;
+                }
+                let reason;
+                for (const prop of node.props) {
+                    reason = propReason(prop);
+                    if (reason)
+                        break;
+                }
+                if (!reason && !childrenStatic) {
+                    reason = childReason(node);
+                }
+                node.static = !reason;
+                if (reason)
+                    reasons.set(node, reason);
+                else
+                    staticElements.push(node);
+                return node.static;
+            }
+            /* c8 ignore next 2 */
+            default:
+                return false;
+        }
+    };
+    for (const node of Array.isArray(root) ? root : [root])
+        visit(node);
+    return { staticElements, reasons };
+}
+/** The most specific reason a child made its parent dynamic. */
+function childReason(node) {
+    for (const child of node.children) {
+        if (child.kind === 'expr')
+            return 'expression-child';
+        if (child.kind === 'component')
+            return 'component-child';
+        if (child.kind === 'control')
+            return 'control-child';
+        if (child.kind === 'element' && !child.static)
+            return 'expression-child';
+        if (child.kind === 'fragment')
+            return 'expression-child';
+    }
+    /* c8 ignore next */
+    return 'expression-child';
+}
+/**
+ * The outermost static elements — the roots worth turning into templates.
+ *
+ * Cloning a static child of a static parent is wasted: the parent's template already
+ * contains it.
+ */
+export function staticRoots(root) {
+    const roots = [];
+    const visit = (node) => {
+        if (node.kind === 'element' && node.static) {
+            roots.push(node);
+            return; // its subtree is inside this template
+        }
+        const children = node.children;
+        if (children)
+            for (const child of children)
+                visit(child);
+    };
+    for (const node of Array.isArray(root) ? root : [root])
+        visit(node);
+    return roots;
+}

package/dist/optimize/analyze-static.mjs

@@ -0,0 +1 @@
+function a(r){switch(r.kind){case"event":return"event";case"ref":return"ref";case"spread":return"spread";case"class":case"style":return"class-or-style-directive";case"attr":case"prop":return r.reactive?"reactive-prop":r.expr!==void 0?"expression-prop":void 0;default:return"expression-prop"}}function f(r){let t=[],c=new Map,n=e=>{switch(e.kind){case"text":return!0;case"expr":return!1;case"component":case"control":for(let s of e.children)n(s);return!1;case"fragment":for(let s of e.children)n(s);return!1;case"element":{let s=!0;for(let o of e.children)n(o)||(s=!1);let i;for(let o of e.props)if(i=a(o),i)break;return!i&&!s&&(i=l(e)),e.static=!i,i?c.set(e,i):t.push(e),e.static}default:return!1}};for(let e of Array.isArray(r)?r:[r])n(e);return{staticElements:t,reasons:c}}function l(r){for(let t of r.children){if(t.kind==="expr")return"expression-child";if(t.kind==="component")return"component-child";if(t.kind==="control")return"control-child";if(t.kind==="element"&&!t.static||t.kind==="fragment")return"expression-child"}return"expression-child"}function p(r){let t=[],c=n=>{if(n.kind==="element"&&n.static){t.push(n);return}let e=n.children;if(e)for(let s of e)c(s)};for(let n of Array.isArray(r)?r:[r])c(n);return t}export{f as analyzeStatic,p as staticRoots};

package/dist/optimize/collapse-strategies.cjs

@@ -0,0 +1 @@
+"use strict";var d=Object.defineProperty;var f=Object.getOwnPropertyDescriptor;var g=Object.getOwnPropertyNames;var R=Object.prototype.hasOwnProperty;var x=(e,o)=>{for(var t in o)d(e,t,{get:o[t],enumerable:!0})},v=(e,o,t,i)=>{if(o&&typeof o=="object"||typeof o=="function")for(let n of g(o))!R.call(e,n)&&n!==t&&d(e,n,{get:()=>o[n],enumerable:!(i=f(o,n))||i.enumerable});return e};var S=e=>v(d({},"__esModule",{value:!0}),e);var E={};x(E,{collapseStrategies:()=>I});module.exports=S(E);function l(e){return e.kind!=="eager"&&e.kind!=="never"}var u=["Show","For","Index","Switch","Match","Portal","Dynamic","ErrorBoundary"],p=["Suspense","SuspenseList","Await"],m=["Router","Outlet","Redirect","Link"],O=[...u,...p,...m],C=new Set([...u,...p]);function c(e,o){let t=Array.isArray(e)?e:[e];for(let i of t){o(i);let n=i.children;n&&c(n,o)}}function I(e){let o=[];c(e,r=>{r.kind==="component"&&r.source&&o.push(r)});let t=new Set,i=new Set;for(let r of o){let{module:s,loading:a}=r.source;a.kind==="eager"&&t.add(s),a.kind==="never"&&i.add(s)}let n=new Map;for(let r of o){let s=r.source;l(s.loading)&&t.has(s.module)&&(s.loading={kind:"eager"},n.set(s.module,(n.get(s.module)??0)+1))}return{collapsed:n,conflicted:[...i].filter(r=>t.has(r))}}

package/dist/optimize/collapse-strategies.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Strategy collapsing — demote a deferred reference whose module is already present.
+ *
+ * This is not a nice-to-have. Without it the naive feature is a regression: if a module
+ * is referenced eagerly anywhere in the compilation unit, it is in the parent chunk
+ * already, so a `load:visible` boundary elsewhere adds a wrapper, a promise and a
+ * re-render in order to fetch nothing. The bytes are paid twice — once in the chunk,
+ * once in the deferral machinery — and the component renders later than it needs to.
+ *
+ * Collapsing runs per module, not per component name, because a chunk is a module:
+ * `<Button>` eager and `<ButtonGroup load:visible>` from the same package means the
+ * package is already loaded, so deferring the second buys nothing.
+ *
+ * `never` is not collapsed. It means "no client code at all", which is a statement about
+ * what should exist rather than about when to fetch it; an eager sibling does not make a
+ * server-only component suddenly belong in the client bundle. That combination is
+ * contradictory and reported instead.
+ */
+import type { IRNode } from '../ir/nodes.js';
+export interface CollapseReport {
+    /** Modules demoted to eager, with the reference count that was demoted. */
+    collapsed: Map<string, number>;
+    /**
+     * Modules referenced both as `load:never` and in a way that needs client code.
+     * Contradictory rather than optimisable, so it is reported and left alone.
+     */
+    conflicted: string[];
+}
+/** Demote deferred references to modules that are already in the chunk. */
+export declare function collapseStrategies(root: IRNode | IRNode[]): CollapseReport;
+//# sourceMappingURL=collapse-strategies.d.ts.map

package/dist/optimize/collapse-strategies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collapse-strategies.d.ts","sourceRoot":"","sources":["../../src/optimize/collapse-strategies.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,MAAM,EAAe,MAAM,gBAAgB,CAAC;AAI1D,MAAM,WAAW,cAAc;IAC7B,2EAA2E;IAC3E,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B;;;OAGG;IACH,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,2EAA2E;AAC3E,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,cAAc,CA2B1E"}

package/dist/optimize/collapse-strategies.js

@@ -0,0 +1,33 @@
+import { isDeferred } from '../resolve/load-directive.js';
+import { walk } from '../resolve/resolve-ir.js';
+/** Demote deferred references to modules that are already in the chunk. */
+export function collapseStrategies(root) {
+    const components = [];
+    walk(root, (node) => {
+        if (node.kind === 'component' && node.source)
+            components.push(node);
+    });
+    const eager = new Set();
+    const never = new Set();
+    for (const node of components) {
+        const { module, loading } = node.source;
+        if (loading.kind === 'eager')
+            eager.add(module);
+        if (loading.kind === 'never')
+            never.add(module);
+    }
+    const collapsed = new Map();
+    for (const node of components) {
+        const source = node.source;
+        if (!isDeferred(source.loading))
+            continue;
+        if (!eager.has(source.module))
+            continue;
+        source.loading = { kind: 'eager' };
+        collapsed.set(source.module, (collapsed.get(source.module) ?? 0) + 1);
+    }
+    return {
+        collapsed,
+        conflicted: [...never].filter((m) => eager.has(m)),
+    };
+}

package/dist/optimize/collapse-strategies.mjs

@@ -0,0 +1 @@
+function a(o){return o.kind!=="eager"&&o.kind!=="never"}var l=["Show","For","Index","Switch","Match","Portal","Dynamic","ErrorBoundary"],u=["Suspense","SuspenseList","Await"],p=["Router","Outlet","Redirect","Link"],g=[...l,...u,...p],m=new Set([...l,...u]);function d(o,t){let i=Array.isArray(o)?o:[o];for(let s of i){t(s);let r=s.children;r&&d(r,t)}}function w(o){let t=[];d(o,e=>{e.kind==="component"&&e.source&&t.push(e)});let i=new Set,s=new Set;for(let e of t){let{module:n,loading:c}=e.source;c.kind==="eager"&&i.add(n),c.kind==="never"&&s.add(n)}let r=new Map;for(let e of t){let n=e.source;a(n.loading)&&i.has(n.module)&&(n.loading={kind:"eager"},r.set(n.module,(r.get(n.module)??0)+1))}return{collapsed:r,conflicted:[...s].filter(e=>i.has(e))}}export{w as collapseStrategies};

package/dist/options.cjs

@@ -1 +1 @@
-"use strict";var r=Object.defineProperty;var n=Object.getOwnPropertyDescriptor;var s=Object.getOwnPropertyNames;var m=Object.prototype.hasOwnProperty;var p=(o,e)=>{for(var a in e)r(o,a,{get:e[a],enumerable:!0})},d=(o,e,a,l)=>{if(e&&typeof e=="object"||typeof e=="function")for(let t of s(e))!m.call(o,t)&&t!==a&&r(o,t,{get:()=>e[t],enumerable:!(l=n(e,t))||l.enumerable});return o};var i=o=>d(r({},"__esModule",{value:!0}),o);var u={};p(u,{defaultOptions:()=>v});module.exports=i(u);var v={backend:"imperative",generate:"dom",moduleName:"@fluixi/dom",delegateEvents:!0,hydratable:!1,sourceMaps:!0,dev:!1};
+"use strict";var l=Object.defineProperty;var n=Object.getOwnPropertyDescriptor;var s=Object.getOwnPropertyNames;var p=Object.prototype.hasOwnProperty;var m=(o,e)=>{for(var t in e)l(o,t,{get:e[t],enumerable:!0})},d=(o,e,t,r)=>{if(e&&typeof e=="object"||typeof e=="function")for(let a of s(e))!p.call(o,a)&&a!==t&&l(o,a,{get:()=>e[a],enumerable:!(r=n(e,a))||r.enumerable});return o};var i=o=>d(l({},"__esModule",{value:!0}),o);var b={};m(b,{defaultOptions:()=>v});module.exports=i(b);var v={backend:"imperative",generate:"dom",moduleName:"@fluixi/dom",delegateEvents:!0,hydratable:!1,sourceMaps:!0,dev:!1};

package/dist/options.d.ts

@@ -4,6 +4,24 @@ import type { ComponentResolverRule } from './resolve/component-resolver.js';
  * as backends change. Switching DOM strategy is `backend`, not a rewrite.
  */
 export interface CompilerOptions {
+    /**
+     * Clone static subtrees from a `<template>` instead of building them element by
+     * element. Roughly 2x faster to instantiate, but **client-only**: `createTemplate`
+     * produces real DOM nodes, which the SSR renderer's ServerElement tree rejects, and a
+     * clone creates a fresh node where hydration must adopt the existing one. Opt in for
+     * a client-rendered app; leave off wherever SSR or hydration is involved.
+     */
+    templateClone?: boolean;
+    /**
+     * Also clone subtrees whose *structure* is static but which contain dynamic holes —
+     * the common shape. Roughly halves the emitted code for such a subtree and replaces
+     * per-element construction with one clone.
+     *
+     * Works under SSR and hydration: each hole is bracketed by `<!--fx-->` markers, so its
+     * content is exactly the nodes between them and the server's markup has the same shape
+     * as the client's template. Hydration adopts those nodes rather than rebuilding them.
+     */
+    partialTemplates?: boolean;
     /** which codegen backend to use */
     backend?: 'imperative' | 'template-clone';
     /** output target */

package/dist/options.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AAE7E;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,mCAAmC;IACnC,OAAO,CAAC,EAAE,YAAY,GAAG,gBAAgB,CAAC;IAC1C,oBAAoB;IACpB,QAAQ,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,SAAS,CAAC;IACrC,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd;;;OAGG;IACH,OAAO,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;CAC5C;AAED,eAAO,MAAM,cAAc,EAAE,eAQ5B,CAAC"}
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AAE7E;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B,mCAAmC;IACnC,OAAO,CAAC,EAAE,YAAY,GAAG,gBAAgB,CAAC;IAC1C,oBAAoB;IACpB,QAAQ,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,SAAS,CAAC;IACrC,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd;;;OAGG;IACH,OAAO,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;CAC5C;AAED,eAAO,MAAM,cAAc,EAAE,eAQ5B,CAAC"}

package/dist/resolve/builtins.cjs

@@ -0,0 +1 @@
+"use strict";var l=Object.defineProperty;var a=Object.getOwnPropertyDescriptor;var m=Object.getOwnPropertyNames;var d=Object.prototype.hasOwnProperty;var M=(o,t)=>{for(var e in t)l(o,e,{get:t[e],enumerable:!0})},O=(o,t,e,s)=>{if(t&&typeof t=="object"||typeof t=="function")for(let n of m(t))!d.call(o,n)&&n!==e&&l(o,n,{get:()=>t[n],enumerable:!(s=a(t,n))||s.enumerable});return o};var f=o=>O(l({},"__esModule",{value:!0}),o);var E={};M(E,{BUILTIN_COMPONENTS:()=>x,CORE_CONTROL_FLOW:()=>u,DOM_CONTROL_FLOW:()=>i,RESERVED_COMPONENTS:()=>R,ROUTER_COMPONENTS:()=>c,builtinComponentMap:()=>p,builtinComponents:()=>C,routerComponents:()=>g});module.exports=f(E);var i=["Show","For","Index","Switch","Match","Portal","Dynamic","ErrorBoundary"],u=["Suspense","SuspenseList","Await"],c=["Router","Outlet","Redirect","Link"],x=[...i,...u,...c],R=new Set([...i,...u]);function p(o={}){let{controlFlowModule:t="@fluixi/dom",coreModule:e="@fluixi/core",routerModule:s="@fluixi/core/router-next"}=o,n={};for(let r of i)n[r]=t;for(let r of u)n[r]=e;for(let r of c)n[r]=s;return n}function C(o={}){return{components:p(o)}}function g(o){let t=o??"@fluixi/core/router-next";return{components:Object.fromEntries(c.map(e=>[e,t]))}}

package/dist/resolve/builtins.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The components the compiler supplies without an import, as data.
+ *
+ * Two different things have always been bundled into one hardcoded `Set` per group:
+ * *which module a name comes from*, and *whether the name has special lowering*. Only
+ * the first is interesting outside the compiler, and every tool needs it — the TS
+ * plugin, to resolve `<Show>` for hover and go-to-definition; the language server, to
+ * complete and validate tags inside `` html`…` ``; a codemod, to materialise imports.
+ * Having no published source, `@fluixi/ts-plugin` duplicated the list and pinned it
+ * with a test that fails when the two drift.
+ *
+ * So the names live here, shaped as {@link ComponentMapRule} so they compose with
+ * user-configured `resolve` rules, and the compiler keeps its own sets for the parts
+ * that are genuinely about codegen.
+ *
+ * The split matters: control-flow names cannot become ordinary rules. `Show`, `For`,
+ * `Index` and `Match` read a reactive *value* prop inside their own tracking scope, so
+ * the compiler emits that prop as a getter — without it `each={items()}` snapshots once
+ * and never updates. They are also exempted from `createMemo` wrapping and may be
+ * replaced outright by `optimizeControlFlowComponent`. A rule only injects an import,
+ * so converting them would keep the import and silently drop the reactivity.
+ *
+ * Router components have no such behaviour — every reference to them in the plugin is
+ * import plumbing — so they are a plain rule.
+ */
+import type { ComponentMapRule } from './component-resolver.js';
+/** Where the built-in groups come from when the host does not override the module. */
+export interface BuiltinModules {
+    /** Control flow that lives in the DOM package. Default `@fluixi/dom`. */
+    controlFlowModule?: string;
+    /** Control flow that only exists in core. Default `@fluixi/core`. */
+    coreModule?: string;
+    /** Router components. Default `@fluixi/core/router-next`. */
+    routerModule?: string;
+}
+/** Control flow lowered against the DOM runtime. */
+export declare const DOM_CONTROL_FLOW: readonly ["Show", "For", "Index", "Switch", "Match", "Portal", "Dynamic", "ErrorBoundary"];
+/** Control flow that only `@fluixi/core` exports — importing it from dom resolves to nothing. */
+export declare const CORE_CONTROL_FLOW: readonly ["Suspense", "SuspenseList", "Await"];
+/**
+ * Router components.
+ *
+ * `Routes` is not a component (routing is `<Router routes={…}>`) and `lazy` is a call
+ * rather than a tag, so neither can be supplied this way.
+ */
+export declare const ROUTER_COMPONENTS: readonly ["Router", "Outlet", "Redirect", "Link"];
+/** Every name the compiler supplies without an import. */
+export declare const BUILTIN_COMPONENTS: readonly string[];
+/**
+ * Names whose meaning is fixed by the compiler and cannot be reassigned by a rule.
+ *
+ * A rule naming one of these is a silent no-op — the compiler matches the built-in
+ * first and the tag renders control flow instead of the intended component, with no
+ * error. Rule authors should check against this set and report rather than emit.
+ */
+export declare const RESERVED_COMPONENTS: ReadonlySet<string>;
+/** Name → module for every built-in, honouring host module overrides. */
+export declare function builtinComponentMap(modules?: BuiltinModules): Record<string, string>;
+/**
+ * The built-ins as a resolver rule, for tools that want one uniform lookup.
+ *
+ * Note this is the *naming* half only. Feeding it to the compiler would not make
+ * control flow work through resolution — the compiler still recognises those names
+ * itself, for the codegen reasons above.
+ */
+export declare function builtinComponents(modules?: BuiltinModules): ComponentMapRule;
+/** Just the router group as a rule — the one group that is purely an import. */
+export declare function routerComponents(routerModule?: string): ComponentMapRule;
+//# sourceMappingURL=builtins.d.ts.map

package/dist/resolve/builtins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../../src/resolve/builtins.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,sFAAsF;AACtF,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,oDAAoD;AACpD,eAAO,MAAM,gBAAgB,4FASnB,CAAC;AAEX,iGAAiG;AACjG,eAAO,MAAM,iBAAiB,gDAAiD,CAAC;AAEhF;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,mDAAoD,CAAC;AAEnF,0DAA0D;AAC1D,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAI/C,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAGlD,CAAC;AAEH,yEAAyE;AACzE,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,cAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAYxF;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,cAAmB,GAAG,gBAAgB,CAEhF;AAED,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAGxE"}

package/dist/resolve/builtins.js

@@ -0,0 +1,64 @@
+/** Control flow lowered against the DOM runtime. */
+export const DOM_CONTROL_FLOW = [
+    'Show',
+    'For',
+    'Index',
+    'Switch',
+    'Match',
+    'Portal',
+    'Dynamic',
+    'ErrorBoundary',
+];
+/** Control flow that only `@fluixi/core` exports — importing it from dom resolves to nothing. */
+export const CORE_CONTROL_FLOW = ['Suspense', 'SuspenseList', 'Await'];
+/**
+ * Router components.
+ *
+ * `Routes` is not a component (routing is `<Router routes={…}>`) and `lazy` is a call
+ * rather than a tag, so neither can be supplied this way.
+ */
+export const ROUTER_COMPONENTS = ['Router', 'Outlet', 'Redirect', 'Link'];
+/** Every name the compiler supplies without an import. */
+export const BUILTIN_COMPONENTS = [
+    ...DOM_CONTROL_FLOW,
+    ...CORE_CONTROL_FLOW,
+    ...ROUTER_COMPONENTS,
+];
+/**
+ * Names whose meaning is fixed by the compiler and cannot be reassigned by a rule.
+ *
+ * A rule naming one of these is a silent no-op — the compiler matches the built-in
+ * first and the tag renders control flow instead of the intended component, with no
+ * error. Rule authors should check against this set and report rather than emit.
+ */
+export const RESERVED_COMPONENTS = new Set([
+    ...DOM_CONTROL_FLOW,
+    ...CORE_CONTROL_FLOW,
+]);
+/** Name → module for every built-in, honouring host module overrides. */
+export function builtinComponentMap(modules = {}) {
+    const { controlFlowModule = '@fluixi/dom', coreModule = '@fluixi/core', routerModule = '@fluixi/core/router-next', } = 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;
+}
+/**
+ * The built-ins as a resolver rule, for tools that want one uniform lookup.
+ *
+ * Note this is the *naming* half only. Feeding it to the compiler would not make
+ * control flow work through resolution — the compiler still recognises those names
+ * itself, for the codegen reasons above.
+ */
+export function builtinComponents(modules = {}) {
+    return { components: builtinComponentMap(modules) };
+}
+/** Just the router group as a rule — the one group that is purely an import. */
+export function routerComponents(routerModule) {
+    const module = routerModule ?? '@fluixi/core/router-next';
+    return { components: Object.fromEntries(ROUTER_COMPONENTS.map((n) => [n, module])) };
+}

package/dist/resolve/builtins.mjs

@@ -0,0 +1 @@
+var s=["Show","For","Index","Switch","Match","Portal","Dynamic","ErrorBoundary"],i=["Suspense","SuspenseList","Await"],u=["Router","Outlet","Redirect","Link"],p=[...s,...i,...u],a=new Set([...s,...i]);function l(o={}){let{controlFlowModule:e="@fluixi/dom",coreModule:r="@fluixi/core",routerModule:c="@fluixi/core/router-next"}=o,n={};for(let t of s)n[t]=e;for(let t of i)n[t]=r;for(let t of u)n[t]=c;return n}function m(o={}){return{components:l(o)}}function d(o){let e=o??"@fluixi/core/router-next";return{components:Object.fromEntries(u.map(r=>[r,e]))}}export{p as BUILTIN_COMPONENTS,i as CORE_CONTROL_FLOW,s as DOM_CONTROL_FLOW,a as RESERVED_COMPONENTS,u as ROUTER_COMPONENTS,l as builtinComponentMap,m as builtinComponents,d as routerComponents};

package/dist/resolve/component-globals.cjs

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

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

@@ -0,0 +1,73 @@
+/**
+ * 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;
+    /** 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;AAkCjC,MAAM,WAAW,uBAAuB;IACtC;;;;;;;;;;OAUG;IACH,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC7B;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,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,CAyFxB"}