@geastack/compiler 1.0.15

package/dist/plugins/gea/render-bridge.js

@@ -0,0 +1,281 @@
+import { operationOfResult } from '../../identity/ids.js';
+import { operandOf } from '../../semantics/model/operands.js';
+import { IrLoweringBlockedError } from '../../ir/lower-graph.js';
+import { namedOperand, registerResult, requireLineage, resolveRequiredOperand } from '../../ir/lower-operands.js';
+import { geaAfterRenderMemberName, geaMountedElementMemberName, geaRenderBridgeMemberName, geaRenderMemberName } from './contract.js';
+/**
+ * `primitives.ts`'s mount-time bridge, ported rather than redesigned.
+ *
+ * v1 shares this repo's *same* `@geastack/core` runtime with v2 -- the same
+ * `Component`/`mount()` (`core/packages/core/index.d.ts:610-613`,
+ * `core/packages/core/runtime/primitives.ts:11-25`) -- so `render` is not a
+ * declared TypeScript member in v1 either; `mount()`'s structural cast is
+ * the identical escape hatch in both compilers, not a v2-specific gap. What
+ * v1 does about it is `cpp-source-replacements.ts`'s
+ * `insertComponentBridgeMethods` (that file's lines 76-117): a narrow,
+ * *textual* post-processing pass over already-emitted C++, entirely outside
+ * geatsc's semantic/IR pipeline, that adds a natively-typed `render`/
+ * `dispose` pair to a class that also got a "mounted renderer" (a template
+ * compiled to a standalone C++ function -- `cpp-template-renderer.ts`'s
+ * `templateMountedRenderer`, line 126). The convention it writes -- one
+ * parameter for the mount parent, a second, always-unused `_index`
+ * (`(void)_index;`, line 100), calling the compiled template and attaching
+ * what it returns under the parent -- is v1's real, native answer to "what
+ * does a render bridge do", ported here rather than redesigned
+ * (`citations.md` section 1). v1's own version boxes every part of it
+ * (`gea_cpp_value parent`, `gea_cpp_value _index`, `gea_cpp_value el`,
+ * lines 96-99) -- the repo-wide "No Boxing" rule this port follows instead
+ * is what makes `root` a real native handle here and drops `el`/`dispose`
+ * rather than reaching for the same box.
+ *
+ * v2 has no external base-swap tool, and `Component` (`compiler.ts`) is
+ * deliberately left without a `render` method of its own -- declaring one
+ * there breaks embedded codegen (its own comment). So there is no ordinary
+ * declaration for this member anywhere in a v2 program: `render` is a name
+ * `mount()`'s own structural cast spells (`geaRenderBridgeMemberName`), never
+ * a method any class writes. `unwrapErased` still resolves the cast's
+ * receiver to the real, monomorphized component class -- so the read is a
+ * real "get" of a real class instance, on a member that plainly is not one of
+ * its fields, accessors, or methods, which is exactly the refusal this ports
+ * v1's answer to close.
+ *
+ * The fix recognizes the one call shape `mount()`'s cast produces --
+ * `instance.render(root, depth)` on an instance of a class this file's sibling
+ * `component-classes.ts` has already told gea is one of its own -- and
+ * rebuilds it as what it means: call the class's own `template` member (the
+ * same member and the same calling convention `lower.ts`'s `lowerClassComponent`
+ * already calls for a JSX-constructed child of this class), then attach what
+ * it returns under `root`. `depth` is read nowhere in v1's own body either
+ * (`(void)_index;`, `cpp-source-replacements.ts:113`) and is dropped here the
+ * same way.
+ *
+ * `el` is written, natively. v1 boxes it (`gea_cpp_value el`) because its
+ * bridge is a textual pass with no type in hand; here the field is a real
+ * member of the component's struct -- `component-classes.ts` publishes the
+ * `define-field` event `Component`'s ambient body never did -- and the node
+ * goes in as the host handle it already is. That matters beyond tidiness: six
+ * corpus apps (`bubble-grid`, `canvas-3d-cube`, `e-reader`, `image-demo`,
+ * `maps`, `ttf-bench`) do all of their work from `onAfterRender()`, and every
+ * one of them guards on `this.el` before doing any of it.
+ *
+ * `onAfterRender` is then called, because otherwise nothing calls it: the hook
+ * is a method no other code reaches, so the emitter -- correctly -- emits
+ * nothing for it, and the app compiles clean, links clean, and draws nothing.
+ * `bubble-grid` did exactly that. The framework's own JS component runtime ends
+ * its `render` with the same two steps, and v1 gets them by keeping that
+ * runtime whole for any component declaring a lifecycle member
+ * (`geatsc-plugin-gea/src/index.ts`'s `componentHasRuntimeLifecycle`); this
+ * bridge performs them directly instead, which is the same behaviour without
+ * the boxed runtime.
+ *
+ * `dispose` is still not allocated. `mount()` is fire-and-forget -- no corpus
+ * program calls `.dispose()` on a mounted root -- and a disposer whose only
+ * caller does not exist would be storage nothing ever reads.
+ */
+/**
+ * The `FunctionId` that calls a class's own `template` member, or `null` when
+ * it declares none of its own.
+ *
+ * An inherited `template` is a gap this shares with `lower.ts`'s
+ * `lowerClassComponent`, not a new one: that lowering already refuses "a
+ * render inherited from a base is entered through the base that declares it,
+ * which this lowering does not yet resolve", and a class this bridge cannot
+ * find an own member for is refused the same honest way -- by declining to
+ * redirect it, leaving the core's ordinary "not a field, accessor, or method"
+ * refusal to name the gap.
+ */
+const templateCallableOf = (ctx, declaration) => {
+    const layout = ctx.program.classes.get(declaration);
+    const member = layout?.methods.find((method) => method.key === geaRenderMemberName);
+    return member?.callable ?? null;
+};
+/**
+ * A method of this class or of any class it derives from, by key.
+ *
+ * A lifecycle hook is written wherever the author put it -- a shared base that
+ * several screens extend is the ordinary way to write one -- and a lookup that
+ * stopped at the class's own members would silently skip the hook rather than
+ * refuse it. The walk is the same one `classMemberOf` performs for an ordinary
+ * inherited member: own members first, then the base, so an override wins.
+ */
+const inheritedMethodOf = (ctx, declaration, key) => {
+    let current = declaration;
+    const seen = new Set();
+    while (current !== null && !seen.has(current)) {
+        seen.add(current);
+        const layout = ctx.program.classes.get(current);
+        if (!layout)
+            return null;
+        const member = layout.methods.find((method) => method.key === key);
+        if (member)
+            return member.callable;
+        current = layout.base;
+    }
+    return null;
+};
+/**
+ * Whether this class -- or a base -- really has storage for `el`.
+ *
+ * `component-classes.ts` publishes the field for every class it recognizes as
+ * one of gea's, so this is normally true; it is asked rather than assumed
+ * because a class whose layout does not carry the member has nowhere to put the
+ * node, and writing one anyway would emit a struct member reference that does
+ * not exist. Answering `false` leaves the tree attached and the hook uncalled,
+ * which is what this bridge did before the field existed at all.
+ */
+const hasMountedElementField = (ctx, declaration) => {
+    let current = declaration;
+    const seen = new Set();
+    while (current !== null && !seen.has(current)) {
+        seen.add(current);
+        const layout = ctx.program.classes.get(current);
+        if (!layout)
+            return false;
+        if (layout.fields.some((field) => field.key === geaMountedElementMemberName))
+            return true;
+        current = layout.base;
+    }
+    return false;
+};
+/**
+ * The declaration a `class-ref` receiver operand names, when it is both one
+ * of gea's own component classes and one this compilation can actually call
+ * `template` on -- or `null` for anything else.
+ *
+ * Read straight from the sealed plan rather than through `resolveRequiredOperand`:
+ * an operand this bridge ultimately declines to redirect must not have picked
+ * up an extra IR read as a side effect of merely being asked about, or the
+ * core's own, unintercepted lowering of the same operand would mint a second,
+ * redundant one right behind it.
+ */
+const eligibleClassOf = (ctx, operand, componentClasses) => {
+    if (!operand || operand.source.kind !== 'result')
+        return null;
+    const representation = ctx.plan.selected.get(operand.source.result);
+    if (!representation || representation.kind !== 'class-ref')
+        return null;
+    if (!componentClasses.has(representation.declaration))
+        return null;
+    return templateCallableOf(ctx, representation.declaration) ? representation.declaration : null;
+};
+/** Whether `operand` is the constant text `text`. */
+const isConstantText = (operand, text) => operand !== undefined && operand.source.kind === 'constant' && operand.source.text === text;
+/**
+ * The property "get" half: `instance.render`, read but never called, is not
+ * this bridge's concern (nothing in the corpus does that -- `citations.md`
+ * section 2c) -- but the "get" that *is* about to be called still has to stop
+ * being lowered here, before the core's generic property path mints a real
+ * `get` IR operation for a member `class-layout.ts` was never told about,
+ * which is the operation `emit-properties.ts`'s `classMemberText` refuses by
+ * name today. This half builds nothing and registers nothing: the call that
+ * immediately follows (`tryLowerRenderBridgeCall` below) rebuilds the whole
+ * expression from its own `receiver` operand, which every method-shaped call
+ * carries independent of how its callee was read (`ir/lower.ts`'s own
+ * comment on `lowerInvocation`), so nothing downstream ever asks for a value
+ * this "get" would have produced.
+ */
+const tryLowerRenderBridgeGet = (ctx, operation, componentClasses) => {
+    if (operation.family !== 'property' || operation.internalMethod !== 'get')
+        return false;
+    if (!isConstantText(operandOf(operation, 'key', 0), geaRenderBridgeMemberName))
+        return false;
+    return eligibleClassOf(ctx, operandOf(operation, 'receiver', 0), componentClasses) !== null;
+};
+/**
+ * The call half: `instance.render(root, depth)` itself.
+ *
+ * Recognizing it needs both ends of the call: the receiver has to be an
+ * instance of a class gea claims (the same test the "get" half above already
+ * makes), and the callee has to actually be a read of `render` -- an eligible
+ * receiver calling some *other* method it declares must not be redirected.
+ * The callee is reached by walking back from the call's own `callee` operand
+ * to the "get" operation that published it (`operationOfResult`), the same
+ * indirection every consumer of a published result already goes through;
+ * there is no second, faster path to the same fact.
+ */
+const tryLowerRenderBridgeCall = (ctx, block, operation, componentClasses) => {
+    if (operation.family !== 'invocation' || operation.internalMethod !== 'call')
+        return false;
+    const receiverOperand = operandOf(operation, 'receiver', 0);
+    const declaration = eligibleClassOf(ctx, receiverOperand, componentClasses);
+    if (!declaration || !receiverOperand)
+        return false;
+    const calleeOperand = namedOperand(operation, 'callee');
+    if (calleeOperand.source.kind !== 'result')
+        return false;
+    const calleeOperation = ctx.graph.operations.get(operationOfResult(calleeOperand.source.result));
+    if (!calleeOperation || calleeOperation.family !== 'property' || calleeOperation.internalMethod !== 'get')
+        return false;
+    if (!isConstantText(operandOf(calleeOperation, 'key', 0), geaRenderBridgeMemberName))
+        return false;
+    const callable = templateCallableOf(ctx, declaration);
+    if (!callable)
+        return false;
+    const templateAbi = ctx.program.abis.get(callable);
+    if (!templateAbi) {
+        throw new IrLoweringBlockedError(`class ${declaration}'s "${geaRenderMemberName}" member has no projected calling convention for the render bridge to call`);
+    }
+    if (templateAbi.parameters.length > 0) {
+        throw new IrLoweringBlockedError(`class ${declaration}'s "${geaRenderMemberName}" declares ${templateAbi.parameters.length} parameter(s); the render bridge ` +
+            'calls it with none, the same as mounting a component with no attributes');
+    }
+    const lineage = requireLineage(operation);
+    const receiver = resolveRequiredOperand(ctx, block, lineage, receiverOperand);
+    const rootOperand = operandOf(operation, 'argument', 0);
+    if (!rootOperand) {
+        throw new IrLoweringBlockedError('a render-bridge call names no root argument to attach the rendered tree under');
+    }
+    const root = resolveRequiredOperand(ctx, block, lineage, rootOperand);
+    if (root.representation.kind !== 'native-handle') {
+        throw new IrLoweringBlockedError(`a render-bridge call's root argument carries "${root.representation.kind}"; only a native host handle names a real place ` +
+            'to attach the rendered tree');
+    }
+    // The render call's second argument (`depth`) is read nowhere: v1's own
+    // bridge casts it away unconditionally (`(void)_index;`), and no lowering
+    // in either compiler ever gives it operational meaning. Not resolving it
+    // at all is that same fact, not an omission of it.
+    const templateRepresentation = { kind: 'function-value-dispatch', abi: templateAbi };
+    const bound = ctx.builder.allocateCallable(block, lineage, callable, [], templateRepresentation);
+    const templateResult = ctx.builder.call(block, lineage, { value: bound, representation: templateRepresentation }, receiver, [], templateAbi.result);
+    if (templateResult === null) {
+        throw new IrLoweringBlockedError(`class ${declaration}'s "${geaRenderMemberName}" returns "void"; a render bridge has nothing to attach`);
+    }
+    // Never a text leaf: what is attached here is a component's rendered SUBTREE,
+    // a host node -- the one thing `isTextLeaf` refuses by carrier anyway.
+    ctx.builder.elementChild(block, lineage, root, { value: templateResult, representation: templateAbi.result }, false);
+    // The two steps the framework's own component runtime performs immediately
+    // after attaching, in its order: install the root element, then run the
+    // hook. `CompiledReactiveComponent.render` (the JS runtime v1 keeps whole for
+    // any component declaring a lifecycle member) ends
+    //
+    //     this[GEA_ELEMENT] = node; this.rendered = true; this.onAfterRender()
+    //
+    // and this bridge is what stands in for that runtime natively. Without them
+    // the hook is unreachable code: it is never emitted, the app's whole
+    // start-up -- every `requestAnimationFrame` loop the corpus starts from one
+    // -- never runs, and the program still compiles clean. That is the failure
+    // mode this pair closes, and it is why they belong to the attach rather than
+    // to a later pass.
+    if (hasMountedElementField(ctx, declaration)) {
+        const key = ctx.builder.constant(block, lineage, geaMountedElementMemberName, 'string', { kind: 'string' });
+        ctx.builder.set(block, lineage, receiver, { value: key, representation: { kind: 'string' } }, { value: templateResult, representation: templateAbi.result }, true, null);
+    }
+    const afterRender = inheritedMethodOf(ctx, declaration, geaAfterRenderMemberName);
+    const afterRenderAbi = afterRender ? ctx.program.abis.get(afterRender) : undefined;
+    if (afterRender && afterRenderAbi) {
+        if (afterRenderAbi.parameters.length > 0) {
+            throw new IrLoweringBlockedError(`class ${declaration}'s "${geaAfterRenderMemberName}" declares ${afterRenderAbi.parameters.length} parameter(s); the ` +
+                'lifecycle hook is called with none');
+        }
+        const hookRepresentation = { kind: 'function-value-dispatch', abi: afterRenderAbi };
+        const hook = ctx.builder.allocateCallable(block, lineage, afterRender, [], hookRepresentation);
+        ctx.builder.call(block, lineage, { value: hook, representation: hookRepresentation }, receiver, [], afterRenderAbi.result);
+    }
+    // `render`'s own declared return type is `void` -- the structural cast
+    // `mount()` writes states that, and nothing this compiler derives disagrees
+    // -- so the call itself publishes nothing to register.
+    registerResult(ctx, operation, null);
+    return true;
+};
+/** Both halves, tried in the order they are read: a "get" first, the call that reads it second. */
+export const lowerGeaRenderBridge = (ctx, block, operation, componentClasses) => tryLowerRenderBridgeGet(ctx, operation, componentClasses) || tryLowerRenderBridgeCall(ctx, block, operation, componentClasses);

package/dist/plugins/gea/slots.d.ts

@@ -0,0 +1,15 @@
+import type { OperationId } from '../../identity/ids.js';
+import type { SlotHook } from '../../projection/slots.js';
+import type { GeaElementFacts } from './contract.js';
+/**
+ * The slot census's answer for the one element shape this plugin lowers its
+ * own way: a CLASS component. Its props object is not the tag's parameter
+ * (the class is constructed with none) but the first formal of the render
+ * member the library points at, and only this plugin knows which member that
+ * is (`contract.ts`'s `elementFactsOf`). The core census answers function
+ * components itself, from the tag's own convention.
+ *
+ * States exactly what `lower.ts`'s `lowerClassComponent` builds: the same
+ * layout, keyed by the same member, so the two cannot drift.
+ */
+export declare const createGeaSlotHook: (facts: ReadonlyMap<OperationId, GeaElementFacts>) => SlotHook;

package/dist/plugins/gea/slots.js

@@ -0,0 +1,36 @@
+import { abiOfCallee } from '../../projection/callee.js';
+import { operandOf } from '../../semantics/model/operands.js';
+/**
+ * The slot census's answer for the one element shape this plugin lowers its
+ * own way: a CLASS component. Its props object is not the tag's parameter
+ * (the class is constructed with none) but the first formal of the render
+ * member the library points at, and only this plugin knows which member that
+ * is (`contract.ts`'s `elementFactsOf`). The core census answers function
+ * components itself, from the tag's own convention.
+ *
+ * States exactly what `lower.ts`'s `lowerClassComponent` builds: the same
+ * layout, keyed by the same member, so the two cannot drift.
+ */
+export const createGeaSlotHook = (facts) => (census, operation, operand) => {
+    if (operation.family !== 'element' || operation.form !== 'value')
+        return null;
+    const resolved = facts.get(operation.id);
+    if (!resolved || resolved.invocation !== 'construct' || resolved.renderMember === null)
+        return null;
+    if (operand.role !== 'prop-value' && operand.role !== 'child')
+        return null;
+    const tagOperand = operandOf(operation, 'tag');
+    const tag = tagOperand ? census.carrierOf(operation, tagOperand) : null;
+    const instance = tag ? abiOfCallee(tag)?.result : undefined;
+    if (instance?.kind !== 'class-ref')
+        return null;
+    const member = census.input.classes.get(instance.declaration)?.methods.find((method) => method.key === resolved.renderMember);
+    const render = member?.callable ? census.input.abis.get(member.callable) : undefined;
+    const props = render?.parameters[0]?.value;
+    if (!props)
+        return null;
+    if (operand.role === 'child')
+        return operation.childrenKey === null ? null : census.fieldSlot(props, operation.childrenKey);
+    const key = operandOf(operation, 'prop-key', operand.ordinal);
+    return key?.source.kind === 'constant' ? census.fieldSlot(props, key.source.text) : null;
+};

package/dist/plugins/gea/template-analysis.d.ts

@@ -0,0 +1,151 @@
+import type { SemanticGraph } from '../../semantics/model/graph.js';
+import { type SemanticOperand } from '../../semantics/model/operands.js';
+import type { ElementOperation } from '../../semantics/model/operations.js';
+/**
+ * Splits a component's `template()` element tree into static structure and
+ * dynamic slots, from the compiler's own semantic graph rather than from a
+ * Babel AST.
+ *
+ * gea's real build tool (`packages/vite-plugin-gea/src/closure-codegen/`)
+ * does this exact split -- `walkJsxToTemplate` produces a `TemplateSpec
+ * {html, slots}`, and `GeaIrSlot` is `{index, kind, walk, walkKinds?, expr?,
+ * payload?}`. This module produces the same shape for the same reason gea
+ * does: a reactive renderer needs to know, ahead of any render, which DOM
+ * positions never change (bake them into a template) and which ones do
+ * (patch only those). But gea's `expr` is a *generated code string* --
+ * `generate(expr).code` -- and that is exactly what this architecture
+ * forbids: generated text is never authority here. A slot below cites the
+ * `SemanticOperand` that produces its value (which, when its source is a
+ * published result, already carries the `SemanticResultId` a consumer needs)
+ * so a later stage resolves it through the ordinary typed operand machinery
+ * instead of re-parsing a string this analysis would otherwise have invented.
+ *
+ * This is pure analysis: no lowering, no emission, no mutation of the graph
+ * it reads. Someone else (unwritten as of this file) consumes the result to
+ * decide how to actually build and patch DOM.
+ */
+/** One static attribute: a name and the constant value baked into the template. */
+export interface StaticAttribute {
+    readonly name: string;
+    readonly value: string;
+}
+/** A text run that never changes -- baked into the template verbatim. */
+export interface StaticTextChild {
+    readonly kind: 'text';
+    readonly text: string;
+}
+/**
+ * A child position occupied by a dynamic slot. This node carries no value of
+ * its own -- `slotIndex` is a pointer into the sibling `slots` array, which is
+ * where the value (and the operand that produces it) actually lives. Keeping
+ * the anchor separate from the slot mirrors gea's own split between the
+ * template HTML (which has a bare `<!--N-->` comment at this position) and
+ * `TemplateSpec.slots` (which has the slot's behavior) -- except this analysis
+ * has no HTML to put the marker in, so the anchor node stands in its place.
+ */
+export interface SlotAnchorChild {
+    readonly kind: 'anchor';
+    readonly slotIndex: number;
+}
+export type StaticChild = StaticElement | StaticTextChild | SlotAnchorChild;
+/** A static intrinsic element: a fixed tag, with its own mix of static and dynamic content. */
+export interface StaticElement {
+    readonly kind: 'element';
+    readonly tag: string;
+    readonly attributes: readonly StaticAttribute[];
+    readonly children: readonly StaticChild[];
+}
+/**
+ * One step of a `walk`, element-aware.
+ *
+ * `{elem: N}` means "the N-th element among this level's siblings" (every
+ * static-element and dynamic-text/mount position counts toward sibling order,
+ * but only elements advance N); `{child: N}` means "the N-th child of any
+ * kind," which is what a comment-marker or text-node position needs since it
+ * is not itself an element. This is the same distinction gea's `walkKinds`
+ * draws, kept alongside the plain index-path `walk` for the same reason gea
+ * keeps both: `walk` is what every consumer needs at minimum, `walkKinds` is
+ * what lets one use `firstElementChild`/`nextElementSibling` chains instead of
+ * `childNodes[i]` indexing when it wants to.
+ */
+export type WalkStep = {
+    readonly elem: number;
+} | {
+    readonly child: number;
+};
+/**
+ * Attribute-slot kinds -- what a dynamic attribute *does* when it changes.
+ *
+ * This vocabulary ('class' writes className, 'style' writes a
+ * CSSStyleDeclaration, an event name wires a listener rather than writing a
+ * property at all) is not a fact about JSX or about this compiler's semantic
+ * graph: it is gea's own policy for what its attribute names mean, and a
+ * different library rendering through the same element operations is free to
+ * classify them differently. That is exactly why `classifyAttrKind` below
+ * lives in this file, behind the plugin boundary, instead of in
+ * `src/semantics/` where it would silently become every framework's answer.
+ */
+export type AttributeSlotKind = 'event' | 'class' | 'style' | 'value' | 'bool' | 'ref' | 'html' | 'attr';
+/** Every slot kind: the attribute kinds above, plus a reactive text child and a mounted component. */
+export type TemplateSlotKind = AttributeSlotKind | 'text' | 'mount';
+/**
+ * One dynamic position in the tree.
+ *
+ * `walk`/`walkKinds` locate the position from the template root -- see the
+ * module doc comment above for why every slot's walk must be captured
+ * *before* any of them act: this analysis never acts on anything, but a
+ * consumer that does (mounting a component, materializing a conditional
+ * branch, splicing in a list) mutates the live parent's child list when it
+ * does, and a walk computed against the pristine tree is only valid if it is
+ * captured before that mutation runs. gea's own emitter states this exact
+ * rule in `compileJsxToBlock` (`emit/emit-core.ts`): "hoist ALL walk captures
+ * ... before any slot action runs, because slot actions ... mutate the
+ * parent's childNodes list and would shift literal-index walks for subsequent
+ * slots." A consumer of this module's output must hoist the same way gea's
+ * emitter does; this module simply hands it every walk up front so there is
+ * nothing left to compute mid-mutation.
+ *
+ * `operand` is the citation, never a generated string: it is the exact
+ * `SemanticOperand` (attribute prop-value or element child) whose evaluation
+ * produces this slot's value, so a consumer reads its `.source`/`.type`
+ * through the ordinary typed operand machinery rather than through text this
+ * analysis would have had to generate and the consumer would have had to
+ * re-parse.
+ */
+export interface TemplateSlot {
+    readonly index: number;
+    readonly kind: TemplateSlotKind;
+    readonly walk: readonly number[];
+    readonly walkKinds: readonly WalkStep[];
+    /** The attribute name, for an attribute-kind slot; `null` for 'text' and 'mount'. */
+    readonly attributeName: string | null;
+    readonly operand: SemanticOperand;
+}
+/**
+ * The outcome of analyzing one template root.
+ *
+ * `blocked` is a first-class answer, not an exception: every construct this
+ * analysis cannot describe faithfully (a spread, a fragment root, a
+ * conditional or list child whose branches are elements) is refused with a
+ * stated reason instead of guessed at. A caller that wants a partial answer
+ * for a partially-describable tree is asking this analysis to invent
+ * authority for the part it could not prove, which is the one thing it must
+ * never do.
+ */
+export type TemplateAnalysisResult = {
+    readonly kind: 'ok';
+    readonly root: StaticElement;
+    readonly slots: readonly TemplateSlot[];
+} | {
+    readonly kind: 'blocked';
+    readonly reason: string;
+};
+/**
+ * Split a component's template root into static structure and dynamic slots.
+ *
+ * `root` must be the `ElementOperation` a `template()` body's JSX evaluates to
+ * -- the caller is the one that knows which operation that is (it resolved the
+ * component's render member and found the operation its body publishes); this
+ * function only knows how to walk one, given the graph it belongs to.
+ */
+export declare const analyzeTemplate: (root: ElementOperation, graph: SemanticGraph) => TemplateAnalysisResult;