@llui/compiler 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Franco Ponticelli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/accessor-resolver.d.ts

@@ -0,0 +1,58 @@
+import ts from 'typescript';
+/**
+ * Helpers for resolving identifier references at reactive-accessor
+ * positions. Shared by `transform.ts` (compile-time prop classification
+ * + Pass 2 mask injection) and `collect-deps.ts` (state-path scanning
+ * for `__dirty` / `__maskLegend`).
+ *
+ * The compiler must distinguish the legitimate accessor shapes:
+ *
+ *   - Inline arrow / function expression at the call site
+ *   - Inline `memo(arrow)` at the call site
+ *   - Identifier referencing a const-bound arrow / function expression
+ *   - Identifier referencing a hoisted function declaration
+ *   - Identifier referencing `const x = memo(arrow)`
+ *
+ * …from values we can't classify (imports, parameters, opaque calls), so
+ * those can be bailed-to-runtime instead of silently miscompiled. See the
+ * `disabled` binding bug, where a function reference at a reactive prop
+ * position was statically assigned (`__e.disabled = isGated`) — writing
+ * the function object onto the boolean DOM property and never re-evaluating.
+ */
+/**
+ * Walk parent chains to find a `const X = ...` declaration matching
+ * `use.text`, or a hoisted `function X(...)` declaration. Returns the
+ * resolved declaration or `null` for unresolvable references (imports,
+ * parameters, this-bindings, etc.).
+ *
+ * Limitations:
+ *   - Only `const`. `let` resolution is unsafe — we can't track later
+ *     reassignments without a type checker.
+ *   - Only single-binding declarations (`const a = …`, not `const a = …, b = …`).
+ *   - The declaration must dominate the use (lexical scope).
+ */
+export declare function resolveLocalConstInitializer(use: ts.Identifier): ts.Expression | ts.FunctionDeclaration | null;
+/**
+ * Recognize `memo(arrow)` / `memo(fn)` calls so the inner accessor can
+ * be analyzed for state-path masking. The runtime `memo()` returns a
+ * cached accessor — its body's reads determine when it re-evaluates,
+ * not the call site.
+ */
+export declare function isMemoCallWithArrowArg(expr: ts.Expression): expr is ts.CallExpression & {
+    arguments: readonly [ts.ArrowFunction | ts.FunctionExpression, ...ts.Expression[]];
+};
+/**
+ * Resolve a value at a reactive-accessor position down to the callable
+ * AST node we can mask-analyze. Returns `null` when the value isn't a
+ * recognized accessor shape — caller leaves the call unchanged (runtime
+ * falls back to FULL_MASK, which is correct just slower).
+ *
+ * Recognized shapes:
+ *   - `(s) => …` (ArrowFunction)
+ *   - `function (s) { … }` (FunctionExpression)
+ *   - `memo((s) => …)` — returns the inner arrow
+ *   - `someIdentifier` resolving to any of the above (or to a hoisted
+ *     `function X(s) { … }` declaration)
+ */
+export declare function resolveAccessorBody(value: ts.Expression): ts.ArrowFunction | ts.FunctionExpression | ts.FunctionDeclaration | null;
+//# sourceMappingURL=accessor-resolver.d.ts.map

package/dist/accessor-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accessor-resolver.d.ts","sourceRoot":"","sources":["../src/accessor-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAA;AAE3B;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;;;;;;;GAWG;AACH,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,EAAE,CAAC,UAAU,GACjB,EAAE,CAAC,UAAU,GAAG,EAAE,CAAC,mBAAmB,GAAG,IAAI,CA8B/C;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,GAAG,IAAI,IAAI,EAAE,CAAC,cAAc,GAAG;IACvF,SAAS,EAAE,SAAS,CAAC,EAAE,CAAC,aAAa,GAAG,EAAE,CAAC,kBAAkB,EAAE,GAAG,EAAE,CAAC,UAAU,EAAE,CAAC,CAAA;CACnF,CAQA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,EAAE,CAAC,UAAU,GACnB,EAAE,CAAC,aAAa,GAAG,EAAE,CAAC,kBAAkB,GAAG,EAAE,CAAC,mBAAmB,GAAG,IAAI,CAoB1E"}

package/dist/accessor-resolver.js

@@ -0,0 +1,119 @@
+import ts from 'typescript';
+/**
+ * Helpers for resolving identifier references at reactive-accessor
+ * positions. Shared by `transform.ts` (compile-time prop classification
+ * + Pass 2 mask injection) and `collect-deps.ts` (state-path scanning
+ * for `__dirty` / `__maskLegend`).
+ *
+ * The compiler must distinguish the legitimate accessor shapes:
+ *
+ *   - Inline arrow / function expression at the call site
+ *   - Inline `memo(arrow)` at the call site
+ *   - Identifier referencing a const-bound arrow / function expression
+ *   - Identifier referencing a hoisted function declaration
+ *   - Identifier referencing `const x = memo(arrow)`
+ *
+ * …from values we can't classify (imports, parameters, opaque calls), so
+ * those can be bailed-to-runtime instead of silently miscompiled. See the
+ * `disabled` binding bug, where a function reference at a reactive prop
+ * position was statically assigned (`__e.disabled = isGated`) — writing
+ * the function object onto the boolean DOM property and never re-evaluating.
+ */
+/**
+ * Walk parent chains to find a `const X = ...` declaration matching
+ * `use.text`, or a hoisted `function X(...)` declaration. Returns the
+ * resolved declaration or `null` for unresolvable references (imports,
+ * parameters, this-bindings, etc.).
+ *
+ * Limitations:
+ *   - Only `const`. `let` resolution is unsafe — we can't track later
+ *     reassignments without a type checker.
+ *   - Only single-binding declarations (`const a = …`, not `const a = …, b = …`).
+ *   - The declaration must dominate the use (lexical scope).
+ */
+export function resolveLocalConstInitializer(use) {
+    const name = use.text;
+    let node = use;
+    while (node.parent) {
+        const parent = node.parent;
+        let statements = null;
+        if (ts.isBlock(parent) || ts.isSourceFile(parent) || ts.isModuleBlock(parent)) {
+            statements = parent.statements;
+        }
+        else if (ts.isCaseClause(parent) || ts.isDefaultClause(parent)) {
+            statements = parent.statements;
+        }
+        if (statements) {
+            for (const stmt of statements) {
+                if (ts.isFunctionDeclaration(stmt)) {
+                    if (stmt.name && stmt.name.text === name)
+                        return stmt;
+                    continue;
+                }
+                if (!ts.isVariableStatement(stmt))
+                    continue;
+                const flags = stmt.declarationList.flags;
+                if (!(flags & ts.NodeFlags.Const))
+                    continue;
+                if (stmt.declarationList.declarations.length !== 1)
+                    continue;
+                const decl = stmt.declarationList.declarations[0];
+                if (!ts.isIdentifier(decl.name) || decl.name.text !== name)
+                    continue;
+                if (!decl.initializer)
+                    continue;
+                return decl.initializer;
+            }
+        }
+        node = parent;
+    }
+    return null;
+}
+/**
+ * Recognize `memo(arrow)` / `memo(fn)` calls so the inner accessor can
+ * be analyzed for state-path masking. The runtime `memo()` returns a
+ * cached accessor — its body's reads determine when it re-evaluates,
+ * not the call site.
+ */
+export function isMemoCallWithArrowArg(expr) {
+    return (ts.isCallExpression(expr) &&
+        ts.isIdentifier(expr.expression) &&
+        expr.expression.text === 'memo' &&
+        expr.arguments.length >= 1 &&
+        (ts.isArrowFunction(expr.arguments[0]) || ts.isFunctionExpression(expr.arguments[0])));
+}
+/**
+ * Resolve a value at a reactive-accessor position down to the callable
+ * AST node we can mask-analyze. Returns `null` when the value isn't a
+ * recognized accessor shape — caller leaves the call unchanged (runtime
+ * falls back to FULL_MASK, which is correct just slower).
+ *
+ * Recognized shapes:
+ *   - `(s) => …` (ArrowFunction)
+ *   - `function (s) { … }` (FunctionExpression)
+ *   - `memo((s) => …)` — returns the inner arrow
+ *   - `someIdentifier` resolving to any of the above (or to a hoisted
+ *     `function X(s) { … }` declaration)
+ */
+export function resolveAccessorBody(value) {
+    if (ts.isArrowFunction(value) || ts.isFunctionExpression(value))
+        return value;
+    if (isMemoCallWithArrowArg(value)) {
+        return value.arguments[0];
+    }
+    if (ts.isIdentifier(value)) {
+        const resolved = resolveLocalConstInitializer(value);
+        if (!resolved)
+            return null;
+        if (ts.isArrowFunction(resolved) ||
+            ts.isFunctionExpression(resolved) ||
+            ts.isFunctionDeclaration(resolved)) {
+            return resolved;
+        }
+        if (isMemoCallWithArrowArg(resolved)) {
+            return resolved.arguments[0];
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=accessor-resolver.js.map

package/dist/accessor-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accessor-resolver.js","sourceRoot":"","sources":["../src/accessor-resolver.ts"],"names":[],"mappings":"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","sourcesContent":["import ts from 'typescript'\n\n/**\n * Helpers for resolving identifier references at reactive-accessor\n * positions. Shared by `transform.ts` (compile-time prop classification\n * + Pass 2 mask injection) and `collect-deps.ts` (state-path scanning\n * for `__dirty` / `__maskLegend`).\n *\n * The compiler must distinguish the legitimate accessor shapes:\n *\n *   - Inline arrow / function expression at the call site\n *   - Inline `memo(arrow)` at the call site\n *   - Identifier referencing a const-bound arrow / function expression\n *   - Identifier referencing a hoisted function declaration\n *   - Identifier referencing `const x = memo(arrow)`\n *\n * …from values we can't classify (imports, parameters, opaque calls), so\n * those can be bailed-to-runtime instead of silently miscompiled. See the\n * `disabled` binding bug, where a function reference at a reactive prop\n * position was statically assigned (`__e.disabled = isGated`) — writing\n * the function object onto the boolean DOM property and never re-evaluating.\n */\n\n/**\n * Walk parent chains to find a `const X = ...` declaration matching\n * `use.text`, or a hoisted `function X(...)` declaration. Returns the\n * resolved declaration or `null` for unresolvable references (imports,\n * parameters, this-bindings, etc.).\n *\n * Limitations:\n *   - Only `const`. `let` resolution is unsafe — we can't track later\n *     reassignments without a type checker.\n *   - Only single-binding declarations (`const a = …`, not `const a = …, b = …`).\n *   - The declaration must dominate the use (lexical scope).\n */\nexport function resolveLocalConstInitializer(\n  use: ts.Identifier,\n): ts.Expression | ts.FunctionDeclaration | null {\n  const name = use.text\n  let node: ts.Node = use\n  while (node.parent) {\n    const parent = node.parent\n    let statements: readonly ts.Statement[] | null = null\n    if (ts.isBlock(parent) || ts.isSourceFile(parent) || ts.isModuleBlock(parent)) {\n      statements = parent.statements\n    } else if (ts.isCaseClause(parent) || ts.isDefaultClause(parent)) {\n      statements = parent.statements\n    }\n    if (statements) {\n      for (const stmt of statements) {\n        if (ts.isFunctionDeclaration(stmt)) {\n          if (stmt.name && stmt.name.text === name) return stmt\n          continue\n        }\n        if (!ts.isVariableStatement(stmt)) continue\n        const flags = stmt.declarationList.flags\n        if (!(flags & ts.NodeFlags.Const)) continue\n        if (stmt.declarationList.declarations.length !== 1) continue\n        const decl = stmt.declarationList.declarations[0]!\n        if (!ts.isIdentifier(decl.name) || decl.name.text !== name) continue\n        if (!decl.initializer) continue\n        return decl.initializer\n      }\n    }\n    node = parent\n  }\n  return null\n}\n\n/**\n * Recognize `memo(arrow)` / `memo(fn)` calls so the inner accessor can\n * be analyzed for state-path masking. The runtime `memo()` returns a\n * cached accessor — its body's reads determine when it re-evaluates,\n * not the call site.\n */\nexport function isMemoCallWithArrowArg(expr: ts.Expression): expr is ts.CallExpression & {\n  arguments: readonly [ts.ArrowFunction | ts.FunctionExpression, ...ts.Expression[]]\n} {\n  return (\n    ts.isCallExpression(expr) &&\n    ts.isIdentifier(expr.expression) &&\n    expr.expression.text === 'memo' &&\n    expr.arguments.length >= 1 &&\n    (ts.isArrowFunction(expr.arguments[0]!) || ts.isFunctionExpression(expr.arguments[0]!))\n  )\n}\n\n/**\n * Resolve a value at a reactive-accessor position down to the callable\n * AST node we can mask-analyze. Returns `null` when the value isn't a\n * recognized accessor shape — caller leaves the call unchanged (runtime\n * falls back to FULL_MASK, which is correct just slower).\n *\n * Recognized shapes:\n *   - `(s) => …` (ArrowFunction)\n *   - `function (s) { … }` (FunctionExpression)\n *   - `memo((s) => …)` — returns the inner arrow\n *   - `someIdentifier` resolving to any of the above (or to a hoisted\n *     `function X(s) { … }` declaration)\n */\nexport function resolveAccessorBody(\n  value: ts.Expression,\n): ts.ArrowFunction | ts.FunctionExpression | ts.FunctionDeclaration | null {\n  if (ts.isArrowFunction(value) || ts.isFunctionExpression(value)) return value\n  if (isMemoCallWithArrowArg(value)) {\n    return value.arguments[0] as ts.ArrowFunction | ts.FunctionExpression\n  }\n  if (ts.isIdentifier(value)) {\n    const resolved = resolveLocalConstInitializer(value)\n    if (!resolved) return null\n    if (\n      ts.isArrowFunction(resolved) ||\n      ts.isFunctionExpression(resolved) ||\n      ts.isFunctionDeclaration(resolved)\n    ) {\n      return resolved\n    }\n    if (isMemoCallWithArrowArg(resolved)) {\n      return resolved.arguments[0] as ts.ArrowFunction | ts.FunctionExpression\n    }\n  }\n  return null\n}\n"]}

package/dist/binding-descriptors.d.ts

@@ -0,0 +1,105 @@
+import ts from 'typescript';
+/**
+ * Compiler passes that surface the Msg variants currently dispatchable
+ * from rendered UI to the agent layer's `list_actions`. Two passes
+ * cover two distinct dispatch shapes:
+ *
+ * 1. `tagEventHandlerSends` — tags event-handler arrow functions
+ *    (`onClick`, `onInput`, …) whose body contains literal
+ *    `<id>({type: 'X', …})` call sites. Wraps with
+ *    `Object.assign(arrow, { __lluiVariants: ['X', …] })`. The
+ *    runtime in `@llui/dom` `elements.ts` / `el-split.ts` reads the
+ *    metadata at bind time and registers the variants on the active
+ *    component instance for the lifetime of the binding's scope.
+ *
+ * 2. `injectScopeVariantRegistrations` — handles the
+ *    dispatch-translation case that pass (1) can't follow:
+ *    `<bag>.connect(get, sendFn, …)` where `sendFn` is a user-
+ *    defined function that translates library Msgs into app Msgs via
+ *    `dispatch({type: 'X', …})`. Static analysis of the library's
+ *    internal onClick can't see across this hop. The pass detects the
+ *    `*.connect(get, sendFn, …)` syntactic pattern, follows `sendFn`
+ *    to its declaration, scans the body for literal dispatches, and
+ *    inserts a runtime `__registerScopeVariants(['X', …])` call
+ *    immediately before the connect call. Lifetime semantics fall
+ *    out of the render context: the call's active scope is whatever
+ *    `each(...)` / `branch(...)` / root scope happens to be live when
+ *    the view evaluates that statement.
+ *
+ * Both passes are gated on `devMode || emitAgentMetadata` in
+ * `transform.ts`. Production bundles without agent integration get
+ * neither the per-handler `Object.assign` cost nor the registration
+ * statements.
+ *
+ * False positives are deliberate. The alternative — proving the
+ * callee resolves to the destructured `send` from a `View` bag, or
+ * tracing function calls across files — would require full scope
+ * tracking the compiler doesn't do. In practice the patterns
+ * `<id>({type:'X',…})` and `*.connect(get, fn, …)` are reliable
+ * shape-level signals; an extra entry in the live descriptor
+ * registry just means the agent sees one more "affordable variant"
+ * than necessary — never a wrong dispatch, never a runtime error.
+ *
+ * False negatives stay where they were: non-literal `type` values
+ * (`send({ type: nextStep })`), and dispatch translators bound via
+ * patterns other than `*.connect(get, fn, …)`. Apps that hit those
+ * cases declare `agentAffordances` on the component def — the
+ * documented escape hatch.
+ *
+ * @see agent spec §5.2, §12.2
+ * @see @llui/dom binding-descriptors.ts (runtime registry + helper)
+ */
+/**
+ * Walks every `ArrowFunction` and `FunctionExpression` in the source
+ * and wraps any whose body contains literal `<id>({type:'X', …})`
+ * dispatches with `Object.assign(fn, {__lluiVariants: ['X', …]})`.
+ *
+ * The runtime (in `@llui/dom` `elements.ts` / `el-split.ts`) reads
+ * `__lluiVariants` from event-handler bindings only — so tags placed
+ * on functions in non-handler positions (a const declared but never
+ * bound, an arrow passed to `Array.filter`, a view function whose
+ * body has nested handlers with dispatches) are runtime-inert. The
+ * compiler tags generously; the runtime registers selectively.
+ *
+ * Universal scope means three concrete patterns all surface their
+ * variants without the app author having to think about it:
+ *
+ * 1. **Inline event-handler arrows** —
+ *    `onClick: () => send({type:'X'})` (the original Pass 1 case).
+ * 2. **Const-bound translator functions** —
+ *    `const sendMenu = (m) => dispatch({type:'Y'})` paired with
+ *    `*.connect(get, sendMenu, …)` (the original Pass 3 case). The
+ *    tag travels with the function reference; library connect impls
+ *    use `tagSend(send, libVariants, fn)` to propagate it onto
+ *    returned handlers.
+ * 3. **Positional-arg handlers** —
+ *    `helper(label, () => send({type:'Z'}))` where `helper` is an
+ *    app-defined wrapper like `navButton(label, onClick)` that
+ *    eventually binds the function as an event listener. The arrow
+ *    is still tagged at its declaration site, and the runtime reads
+ *    the tag when the wrapper binds it.
+ *
+ * False positives are deliberate. The alternative — proving that a
+ * tagged arrow actually reaches an event-handler binding — would
+ * require cross-function, cross-file flow analysis the compiler
+ * doesn't do. In practice the cost of an over-tagged arrow is bytes,
+ * not behavior: the runtime never reads the tag from non-handler
+ * bindings.
+ *
+ * Pass 2's `collectLocalFns` resolves identifiers to their original
+ * arrow/function initializers; this pass replaces those initializers
+ * with `Object.assign(arrow, {…})` wrappers. Run Pass 2 BEFORE Pass 1
+ * so the resolver still sees raw arrows.
+ *
+ * Already-wrapped functions (CallExpressions, including user-applied
+ * `tagSend(...)` or this pass's own prior output) are skipped — the
+ * pass only fires on bare arrow/function expressions.
+ */
+export declare function tagDispatchHandlers(node: ts.SourceFile, f: ts.NodeFactory): ts.SourceFile;
+export interface InjectResult {
+    sf: ts.SourceFile;
+    /** True when at least one `__registerScopeVariants(...)` call was inserted. */
+    injected: boolean;
+}
+export declare function injectScopeVariantRegistrations(node: ts.SourceFile, f: ts.NodeFactory): InjectResult;
+//# sourceMappingURL=binding-descriptors.d.ts.map

package/dist/binding-descriptors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding-descriptors.d.ts","sourceRoot":"","sources":["../src/binding-descriptors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAA;AAE3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,EAAE,CAAC,EAAE,EAAE,CAAC,WAAW,GAAG,EAAE,CAAC,UAAU,CA0BzF;AA8BD,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,EAAE,CAAC,UAAU,CAAA;IACjB,+EAA+E;IAC/E,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,EAAE,CAAC,UAAU,EACnB,CAAC,EAAE,EAAE,CAAC,WAAW,GAChB,YAAY,CA0Fd"}

package/dist/binding-descriptors.js

@@ -0,0 +1,340 @@
+import ts from 'typescript';
+/**
+ * Compiler passes that surface the Msg variants currently dispatchable
+ * from rendered UI to the agent layer's `list_actions`. Two passes
+ * cover two distinct dispatch shapes:
+ *
+ * 1. `tagEventHandlerSends` — tags event-handler arrow functions
+ *    (`onClick`, `onInput`, …) whose body contains literal
+ *    `<id>({type: 'X', …})` call sites. Wraps with
+ *    `Object.assign(arrow, { __lluiVariants: ['X', …] })`. The
+ *    runtime in `@llui/dom` `elements.ts` / `el-split.ts` reads the
+ *    metadata at bind time and registers the variants on the active
+ *    component instance for the lifetime of the binding's scope.
+ *
+ * 2. `injectScopeVariantRegistrations` — handles the
+ *    dispatch-translation case that pass (1) can't follow:
+ *    `<bag>.connect(get, sendFn, …)` where `sendFn` is a user-
+ *    defined function that translates library Msgs into app Msgs via
+ *    `dispatch({type: 'X', …})`. Static analysis of the library's
+ *    internal onClick can't see across this hop. The pass detects the
+ *    `*.connect(get, sendFn, …)` syntactic pattern, follows `sendFn`
+ *    to its declaration, scans the body for literal dispatches, and
+ *    inserts a runtime `__registerScopeVariants(['X', …])` call
+ *    immediately before the connect call. Lifetime semantics fall
+ *    out of the render context: the call's active scope is whatever
+ *    `each(...)` / `branch(...)` / root scope happens to be live when
+ *    the view evaluates that statement.
+ *
+ * Both passes are gated on `devMode || emitAgentMetadata` in
+ * `transform.ts`. Production bundles without agent integration get
+ * neither the per-handler `Object.assign` cost nor the registration
+ * statements.
+ *
+ * False positives are deliberate. The alternative — proving the
+ * callee resolves to the destructured `send` from a `View` bag, or
+ * tracing function calls across files — would require full scope
+ * tracking the compiler doesn't do. In practice the patterns
+ * `<id>({type:'X',…})` and `*.connect(get, fn, …)` are reliable
+ * shape-level signals; an extra entry in the live descriptor
+ * registry just means the agent sees one more "affordable variant"
+ * than necessary — never a wrong dispatch, never a runtime error.
+ *
+ * False negatives stay where they were: non-literal `type` values
+ * (`send({ type: nextStep })`), and dispatch translators bound via
+ * patterns other than `*.connect(get, fn, …)`. Apps that hit those
+ * cases declare `agentAffordances` on the component def — the
+ * documented escape hatch.
+ *
+ * @see agent spec §5.2, §12.2
+ * @see @llui/dom binding-descriptors.ts (runtime registry + helper)
+ */
+// ── Pass 1: dispatch-handler tagger (universal) ─────────────────────
+/**
+ * Walks every `ArrowFunction` and `FunctionExpression` in the source
+ * and wraps any whose body contains literal `<id>({type:'X', …})`
+ * dispatches with `Object.assign(fn, {__lluiVariants: ['X', …]})`.
+ *
+ * The runtime (in `@llui/dom` `elements.ts` / `el-split.ts`) reads
+ * `__lluiVariants` from event-handler bindings only — so tags placed
+ * on functions in non-handler positions (a const declared but never
+ * bound, an arrow passed to `Array.filter`, a view function whose
+ * body has nested handlers with dispatches) are runtime-inert. The
+ * compiler tags generously; the runtime registers selectively.
+ *
+ * Universal scope means three concrete patterns all surface their
+ * variants without the app author having to think about it:
+ *
+ * 1. **Inline event-handler arrows** —
+ *    `onClick: () => send({type:'X'})` (the original Pass 1 case).
+ * 2. **Const-bound translator functions** —
+ *    `const sendMenu = (m) => dispatch({type:'Y'})` paired with
+ *    `*.connect(get, sendMenu, …)` (the original Pass 3 case). The
+ *    tag travels with the function reference; library connect impls
+ *    use `tagSend(send, libVariants, fn)` to propagate it onto
+ *    returned handlers.
+ * 3. **Positional-arg handlers** —
+ *    `helper(label, () => send({type:'Z'}))` where `helper` is an
+ *    app-defined wrapper like `navButton(label, onClick)` that
+ *    eventually binds the function as an event listener. The arrow
+ *    is still tagged at its declaration site, and the runtime reads
+ *    the tag when the wrapper binds it.
+ *
+ * False positives are deliberate. The alternative — proving that a
+ * tagged arrow actually reaches an event-handler binding — would
+ * require cross-function, cross-file flow analysis the compiler
+ * doesn't do. In practice the cost of an over-tagged arrow is bytes,
+ * not behavior: the runtime never reads the tag from non-handler
+ * bindings.
+ *
+ * Pass 2's `collectLocalFns` resolves identifiers to their original
+ * arrow/function initializers; this pass replaces those initializers
+ * with `Object.assign(arrow, {…})` wrappers. Run Pass 2 BEFORE Pass 1
+ * so the resolver still sees raw arrows.
+ *
+ * Already-wrapped functions (CallExpressions, including user-applied
+ * `tagSend(...)` or this pass's own prior output) are skipped — the
+ * pass only fires on bare arrow/function expressions.
+ */
+export function tagDispatchHandlers(node, f) {
+    const transformer = (ctx) => {
+        const visit = (n) => {
+            if (ts.isArrowFunction(n) || ts.isFunctionExpression(n)) {
+                // Visit children first so nested arrows are tagged before
+                // their parents see them. The parent's
+                // `collectLiteralSendVariants` walks the original (unwrapped)
+                // body — the recursive collect doesn't descend into nested
+                // function bodies (that would cause an outer arrow to inherit
+                // every dispatch from every closure within it, which is too
+                // permissive).
+                const inner = ts.visitEachChild(n, visit, ctx);
+                const variants = collectLiteralSendVariants(inner.body);
+                if (variants.length > 0) {
+                    return wrapWithVariants(inner, variants, f);
+                }
+                return inner;
+            }
+            return ts.visitEachChild(n, visit, ctx);
+        };
+        return (sf) => ts.visitEachChild(sf, visit, ctx);
+    };
+    const result = ts.transform(node, [transformer]);
+    const out = result.transformed[0];
+    result.dispose();
+    return out;
+}
+function wrapWithVariants(arrow, variants, f) {
+    return f.createCallExpression(f.createPropertyAccessExpression(f.createIdentifier('Object'), 'assign'), undefined, [
+        arrow,
+        f.createObjectLiteralExpression([
+            f.createPropertyAssignment('__lluiVariants', f.createArrayLiteralExpression(variants.map((v) => f.createStringLiteral(v)), false)),
+        ], false),
+    ]);
+}
+export function injectScopeVariantRegistrations(node, f) {
+    let injected = false;
+    const transformer = (ctx) => {
+        /**
+         * Tracks whether we're inside a function body. Top-level
+         * (module-scope) connect calls are skipped — there's no render
+         * context active when module code runs, so the registration
+         * would silently no-op anyway, and emitting it adds noise. Apps
+         * with module-scope translators (a single shared `parts` re-used
+         * across views) declare `agentAffordances` instead.
+         */
+        let inFunction = 0;
+        function rewriteBlock(block) {
+            const stmts = block.statements;
+            const localFns = collectLocalFns(stmts);
+            const out = [];
+            for (const stmt of stmts) {
+                const visited = ts.visitNode(stmt, (n) => visitNode(n, localFns));
+                out.push(visited);
+            }
+            if (ts.isSourceFile(block)) {
+                return f.updateSourceFile(block, out);
+            }
+            return f.updateBlock(block, out);
+        }
+        function visitNode(n, localFns) {
+            if (ts.isBlock(n)) {
+                return rewriteBlock(n);
+            }
+            // Track function-body nesting so we know whether the current
+            // call site can plausibly run within a render context. Arrow
+            // functions and function expressions/declarations both qualify.
+            if (ts.isArrowFunction(n) ||
+                ts.isFunctionExpression(n) ||
+                ts.isFunctionDeclaration(n) ||
+                ts.isMethodDeclaration(n)) {
+                inFunction++;
+                const r = ts.visitEachChild(n, (c) => visitNode(c, localFns), ctx);
+                inFunction--;
+                return r;
+            }
+            if (ts.isCallExpression(n) && inFunction > 0 && isConnectCallShape(n)) {
+                const sendArg = n.arguments[1];
+                const sendFn = resolveSendFn(sendArg, localFns);
+                if (sendFn) {
+                    const variants = collectLiteralSendVariants(sendFn.body);
+                    if (variants.length > 0) {
+                        // Replace the call expression with a comma expression:
+                        //   (__registerScopeVariants([...]), originalCall)
+                        // The comma keeps the call's value position intact (so
+                        // `const parts = popover.connect(...)` still binds the
+                        // original return), and ensures the registration fires
+                        // *before* the call returns. This positions correctly
+                        // regardless of the surrounding function context: view
+                        // body, render callback inside `each(...)`, or any
+                        // nested helper called from within a view.
+                        injected = true;
+                        const inner = ts.visitEachChild(n, (c) => visitNode(c, localFns), ctx);
+                        return f.createParenthesizedExpression(f.createBinaryExpression(emitRegisterCall(variants, f), f.createToken(ts.SyntaxKind.CommaToken), inner));
+                    }
+                }
+            }
+            return ts.visitEachChild(n, (c) => visitNode(c, localFns), ctx);
+        }
+        return (sf) => rewriteBlock(sf);
+    };
+    const result = ts.transform(node, [transformer]);
+    const out = result.transformed[0];
+    result.dispose();
+    return { sf: out, injected };
+}
+/**
+ * Collect `const fn = (m) => { … }` / `const fn = function(m){ … }`
+ * declarations in `stmts` so an identifier passed to a connect call
+ * later in the same scope can resolve to its body. Conservative —
+ * only direct function-valued initializers count; aliasing
+ * (`const a = b`) is not followed.
+ */
+function collectLocalFns(stmts) {
+    const out = new Map();
+    for (const stmt of stmts) {
+        if (!ts.isVariableStatement(stmt))
+            continue;
+        for (const decl of stmt.declarationList.declarations) {
+            if (!ts.isIdentifier(decl.name))
+                continue;
+            const init = decl.initializer;
+            if (init && (ts.isArrowFunction(init) || ts.isFunctionExpression(init))) {
+                out.set(decl.name.text, init);
+            }
+        }
+    }
+    return out;
+}
+function isConnectCallShape(node) {
+    if (!ts.isPropertyAccessExpression(node.expression))
+        return false;
+    if (node.expression.name.text !== 'connect')
+        return false;
+    return node.arguments.length >= 2;
+}
+function resolveSendFn(arg, localFns) {
+    if (ts.isArrowFunction(arg) || ts.isFunctionExpression(arg))
+        return arg;
+    if (ts.isIdentifier(arg))
+        return localFns.get(arg.text) ?? null;
+    return null;
+}
+function emitRegisterCall(variants, f) {
+    return f.createCallExpression(f.createIdentifier('__registerScopeVariants'), undefined, [
+        f.createArrayLiteralExpression(variants.map((v) => f.createStringLiteral(v)), false),
+    ]);
+}
+// ── Shared: literal-send variant collection ──────────────────────────
+/**
+ * Walk `node`, collecting every literal type string from
+ * `<id>({ type: 'literal', … })` call sites. De-dupes while preserving
+ * first-seen order so the emitted array reads naturally for anyone
+ * inspecting the compiled output.
+ *
+ * The walk stops at nested function/arrow boundaries — every function
+ * "owns" its own dispatches, and the universal tagger visits each
+ * function separately. Without this guard, an outer arrow whose body
+ * includes a nested onClick arrow would be tagged with the inner
+ * arrow's variants too: a parent view tagged with every dispatch in
+ * every child handler. The runtime only reads the tag from event-
+ * handler bindings, so functionally that's harmless — but it bloats
+ * the wrapped output and obscures intent.
+ */
+function collectLiteralSendVariants(body) {
+    const seen = new Set();
+    const out = [];
+    function visit(n) {
+        // Stop at every nested function/arrow boundary — those functions
+        // own their own variants and are tagged independently. An outer
+        // arrow whose body contains `setTimeout(() => send(...), 100)`
+        // doesn't dispatch directly when invoked; the inner arrow does
+        // when the timer fires. Counting the inner's variants on the
+        // outer would be too permissive.
+        if (ts.isArrowFunction(n) ||
+            ts.isFunctionExpression(n) ||
+            ts.isFunctionDeclaration(n) ||
+            ts.isMethodDeclaration(n)) {
+            return;
+        }
+        if (ts.isCallExpression(n)) {
+            const callee = n.expression;
+            const first = n.arguments[0];
+            if (callee &&
+                ts.isIdentifier(callee) &&
+                isDispatcherName(callee.text) &&
+                first &&
+                ts.isObjectLiteralExpression(first)) {
+                const variant = readTypeLiteral(first);
+                if (variant !== null && !seen.has(variant)) {
+                    seen.add(variant);
+                    out.push(variant);
+                }
+            }
+        }
+        ts.forEachChild(n, visit);
+    }
+    visit(body);
+    return out;
+}
+/**
+ * Recognize a callee as a dispatcher by name. The convention in LLui
+ * apps is `send` (the framework-provided dispatch) or `dispatch` (a
+ * common app-level alias), plus `send*` / `dispatch*` prefixes for
+ * named translators (`sendMenu`, `dispatchMenu`).
+ *
+ * Without this filter, the tagger would treat element-helper calls
+ * like `button({type: 'button'})` and `input({type: 'email'})` as
+ * dispatch sites — they syntactically match `<Identifier>({type:
+ * literal})`, but they construct DOM, not Msgs. Phantom variants
+ * like `button` and `email` would then leak into the binding-
+ * descriptor registry and surface as agent affordances. Filtering
+ * by name keeps the convention narrow enough that false positives
+ * are nearly zero while leaving room for translator naming.
+ *
+ * Apps that use unconventional dispatcher names (`forward`,
+ * `tellMenu`) need to either rename to the convention or wrap their
+ * handlers with the runtime `tagSend`/`tagVariants` helpers
+ * explicitly — the same escape hatch library code already uses.
+ */
+function isDispatcherName(name) {
+    return /^(send|dispatch)/i.test(name);
+}
+function readTypeLiteral(obj) {
+    for (const prop of obj.properties) {
+        if (!ts.isPropertyAssignment(prop))
+            continue;
+        if (!prop.name)
+            continue;
+        const nameOk = (ts.isIdentifier(prop.name) && prop.name.text === 'type') ||
+            (ts.isStringLiteral(prop.name) && prop.name.text === 'type');
+        if (!nameOk)
+            continue;
+        const init = prop.initializer;
+        if (ts.isStringLiteral(init))
+            return init.text;
+        if (ts.isNoSubstitutionTemplateLiteral(init))
+            return init.text;
+    }
+    return null;
+}
+//# sourceMappingURL=binding-descriptors.js.map