@firsthandjs/compiler 0.9.0 → 0.10.0

package/dist/components.d.ts

@@ -0,0 +1,25 @@
+/**
+ * What a `component(...)` call gains on the way through (ADR-0004).
+ *
+ * A stable build id, a display name, props rewritten into live reads, and —
+ * under the `devtools` option only — a label on each cell the module creates.
+ */
+import type { NodePath } from '@babel/traverse';
+import * as t from '@babel/types';
+import type { FirsthandPluginOptions } from './options.js';
+import { type State } from './state.js';
+/**
+ * Gives every `component(...)` call a stable build id and a display name, and
+ * rejects props destructuring.
+ */
+export declare function annotateComponent(path: NodePath<t.CallExpression>, state: State, options: FirsthandPluginOptions): void;
+/**
+ * Labels `const count = signal(0)` with `count` and where it was written.
+ *
+ * Emitted only under the `devtools` option, so a production build is
+ * byte-identical to one compiled without it. The label is wrapped around the
+ * call rather than passed into it: `signal` keeps its signature, and a cell
+ * created any other way is simply unnamed rather than special.
+ */
+export declare function nameCell(path: NodePath<t.VariableDeclarator>, state: State): void;
+//# sourceMappingURL=components.d.ts.map

package/dist/components.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"components.d.ts","sourceRoot":"","sources":["../src/components.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEhD,OAAO,KAAK,CAAC,MAAM,cAAc,CAAC;AAIlC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAM3D,OAAO,EAAW,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AAEjD;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC,EAChC,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,sBAAsB,GAC9B,IAAI,CA2BN;AASD;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,kBAAkB,CAAC,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CA2BjF"}

package/dist/guarded.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A write a run performs, guarded by what it last put there.
+ *
+ * Its own module because two callers need it and neither should import the
+ * other: an attribute is written this way, and so is a child.
+ */
+import * as t from '@babel/types';
+import { type Build, type State } from './state.js';
+/**
+ * A write the run performs, guarded by what it last put there.
+ *
+ * ```js
+ * const _w$1 = _$site(_store, 3), _x$1 = u.kind;
+ * if (_w$1.last !== _x$1) { _w$1.last = _x$1; _$applyProp(_el$, "class", _x$1); }
+ * ```
+ *
+ * The comparison is against a remembered value rather than against the DOM:
+ * reading an attribute or a text node back costs more than writing it, which
+ * is the one thing measuring this changed my mind about.
+ */
+export declare function guardedWrite(build: Build, state: State, value: t.Expression, write: (held: t.Identifier) => t.Expression): void;
+//# sourceMappingURL=guarded.d.ts.map

package/dist/guarded.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guarded.d.ts","sourceRoot":"","sources":["../src/guarded.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,CAAC,MAAM,cAAc,CAAC;AAIlC,OAAO,EAAqB,KAAK,KAAK,EAAmB,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AAExF;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,CAAC,CAAC,UAAU,EACnB,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,UAAU,GAC1C,IAAI,CA8BN"}

package/dist/html.d.ts

@@ -16,4 +16,16 @@ export declare function escapeText(value: string): string;
 export declare function escapeAttribute(value: string): string;
 /** `onPointerDown` -> `pointerdown`. */
 export declare function eventName(attribute: string): string;
+/**
+ * Whether an attribute name is a listener.
+ *
+ * `onClick` and `on:sl-change` are both listeners; `once` and `onwards` are
+ * not, which is what the third character decides — a capital or a colon after
+ * `on` is the only thing that makes the rest a type name.
+ *
+ * One definition rather than two, because the browser path and the server path
+ * both need it and have to agree: a name the server skips and the browser
+ * attaches would be a listener nobody could reach.
+ */
+export declare function isEventName(name: string): boolean;
 //# sourceMappingURL=html.d.ts.map

package/dist/html.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["../src/html.ts"],"names":[],"mappings":"AAAA,wEAAwE;AAExE,wCAAwC;AACxC,eAAO,MAAM,aAAa,aAexB,CAAC;AAEH,2EAA2E;AAC3E,eAAO,MAAM,kBAAkB,aAa7B,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,cAAc,aAWzB,CAAC;AAEH,mEAAmE;AACnE,eAAO,MAAM,YAAY,aAsBvB,CAAC;AAEH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,wCAAwC;AACxC,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEnD"}
+{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["../src/html.ts"],"names":[],"mappings":"AAAA,wEAAwE;AAExE,wCAAwC;AACxC,eAAO,MAAM,aAAa,aAexB,CAAC;AAEH,2EAA2E;AAC3E,eAAO,MAAM,kBAAkB,aAa7B,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,cAAc,aAWzB,CAAC;AAEH,mEAAmE;AACnE,eAAO,MAAM,YAAY,aAsBvB,CAAC;AAEH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,wCAAwC;AACxC,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjD"}

package/dist/index.js

@@ -3,7 +3,7 @@ import {
   firsthandPlugin,
   stableId,
   transform
-} from "./chunk-ACKKPAGI.js";
+} from "./chunk-JEIWCE46.js";
 export {
   compileModule,
   firsthandPlugin,

package/dist/jsx.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Where a JSX node goes: a component call, a server's markup, or a template.
+ *
+ * `compileNode` is the fork, and the two branches below it are the whole of
+ * what a component needs — its props as accessors, and the machinery that lets
+ * a run keep the child it made last time.
+ */
+import type { NodePath } from '@babel/traverse';
+import * as t from '@babel/types';
+import { type State } from './state.js';
+export declare function compileNode(path: NodePath<t.JSXElement | t.JSXFragment>, state: State): t.Expression;
+/**
+ * Compiles the children of a fragment, or of a component that takes children.
+ *
+ * A dynamic child becomes a `part(...)`, not a bare thunk. An array has no
+ * parent element, so its dynamic children cannot be bound where they are
+ * written — and deferring them to insertion time would evaluate them under
+ * whoever inserts the array, which loses the scope they belong to and does not
+ * make them reactive at all. `part` carries that scope along with an anchor,
+ * and the runtime binds it once the array is in the DOM.
+ */
+export declare function compileChildren(children: t.JSXElement['children'], state: State, kept?: Kept): t.Expression[];
+/**
+ * How a kept child is told what its run currently says.
+ *
+ * A component inside a run is made once, so an expression it is given cannot be
+ * left as a binding of the run that made it — the second run has its own, and
+ * the child would go on reading the first for ever.
+ */
+type Kept = {
+    /** Whether an expression names anything belonging to the run. */
+    depends(value: t.Expression): boolean;
+    /** The expression, read through a cell the run writes on every run. */
+    cell(value: t.Expression): t.Expression;
+    /** A value, written to a cell on every run and read from it. */
+    value(value: t.Expression): t.Expression;
+};
+export {};
+//# sourceMappingURL=jsx.d.ts.map

package/dist/jsx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsx.d.ts","sourceRoot":"","sources":["../src/jsx.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEhD,OAAO,KAAK,CAAC,MAAM,cAAc,CAAC;AAqBlC,OAAO,EAA4B,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AAIlE,wBAAgB,WAAW,CACzB,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,WAAW,CAAC,EAC5C,KAAK,EAAE,KAAK,GACX,CAAC,CAAC,UAAU,CASd;AA6ND;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,CAAC,CAAC,UAAU,CAAC,UAAU,CAAC,EAClC,KAAK,EAAE,KAAK,EACZ,IAAI,CAAC,EAAE,IAAI,GACV,CAAC,CAAC,UAAU,EAAE,CAuBhB;AAED;;;;;;GAMG;AACH,KAAK,IAAI,GAAG;IACV,iEAAiE;IACjE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,UAAU,GAAG,OAAO,CAAC;IACtC,uEAAuE;IACvE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC;IACxC,gEAAgE;IAChE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC;CAC1C,CAAC"}

package/dist/lists.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `items.map(row => <Row key={row.id} />)` becomes a keyed list part.
+ *
+ * A rewrite rather than a compilation: what comes out is still JSX, and the
+ * passes after this one compile it without knowing a list was involved. The
+ * mark `LIST_CALL` is how they find out where it matters.
+ */
+import type { NodePath } from '@babel/traverse';
+import * as t from '@babel/types';
+import { type State } from './state.js';
+/**
+ * Rewrites `items.map(item => <Row key={item.id} .../>)` into a keyed list part.
+ *
+ * The callback's item parameter becomes a reactive cell and every reference to
+ * it becomes a live read, so a row whose data changes updates in place instead
+ * of being re-created. The key expression is extracted first, because it is
+ * computed from the raw item, once per reconcile.
+ *
+ * A `.map()` without a `key` stays an ordinary array child: it is reconciled by
+ * node identity, which for freshly created nodes means "replace". That is the
+ * documented cost of leaving the key out.
+ */
+export declare function rewriteKeyedMaps(path: NodePath<t.JSXElement | t.JSXFragment>, state: State): void;
+//# sourceMappingURL=lists.d.ts.map

package/dist/lists.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lists.d.ts","sourceRoot":"","sources":["../src/lists.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEhD,OAAO,KAAK,CAAC,MAAM,cAAc,CAAC;AAIlC,OAAO,EAAW,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,WAAW,CAAC,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CASjG"}

package/dist/marks.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The marks the compiler leaves on nodes it wrote.
+ *
+ * Three symbols and the predicates that read them. A symbol rather than a
+ * property name because these travel on Babel nodes, which are shared with
+ * every other plugin in the pipeline: a name could collide, and a mark that
+ * collided would silently change what the compiler decides about a node.
+ */
+import * as t from '@babel/types';
+/**
+ * Marks an arrow the compiler wrote for a child slot.
+ *
+ * Whatever sits directly in one is already inside a reactive scope, so a view
+ * function there can be called where it stands instead of being wrapped in a
+ * part of its own.
+ */
+export declare const CHILD_THUNK: unique symbol;
+/**
+ * Marks a wrapper the compiler wrote, which is not a scope of anyone's.
+ *
+ * A template compiles to an immediately invoked arrow, and that arrow is a
+ * function — so walking up from markup inside it would stop there and lose the
+ * run it belongs to. It is machinery, not a boundary, and is walked through.
+ */
+export declare const GENERATED: unique symbol;
+export declare function generated(arrow: t.ArrowFunctionExpression): t.ArrowFunctionExpression;
+/** Marks a call the map rewrite produced, so it is not wrapped in a thunk. */
+export declare const LIST_CALL: unique symbol;
+/** Whether an expression is the keyed-list call `rewriteKeyedMaps` produced. */
+export declare function isKeyedList(node: t.Node): boolean;
+//# sourceMappingURL=marks.d.ts.map

package/dist/marks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"marks.d.ts","sourceRoot":"","sources":["../src/marks.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,CAAC,MAAM,cAAc,CAAC;AAElC;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,eAAiC,CAAC;AAE1D;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,eAAgC,CAAC;AAEvD,wBAAgB,SAAS,CAAC,KAAK,EAAE,CAAC,CAAC,uBAAuB,GAAG,CAAC,CAAC,uBAAuB,CAGrF;AAED,8EAA8E;AAC9E,eAAO,MAAM,SAAS,eAA2B,CAAC;AAElD,gFAAgF;AAChF,wBAAgB,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,GAAG,OAAO,CAEjD"}

package/dist/markup.d.ts

@@ -0,0 +1,27 @@
+/**
+ * A host element, for a server render: the static chunks and the values
+ * between them.
+ *
+ * The structure has to be the structure the browser would have built, node for
+ * node, or hydration walks into the wrong place. Every decision here mirrors
+ * one in `template.ts`.
+ */
+import type { NodePath } from '@babel/traverse';
+import * as t from '@babel/types';
+import { type State } from './state.js';
+/**
+ * Compiles an element to the markup a server sends.
+ *
+ * The structure has to be **the same structure** the browser would have built,
+ * node for node, or hydration walks into the wrong place: the client navigates
+ * a template by `firstChild` and `nextSibling`, and a comment the server left
+ * out is a step the client takes anyway. So the decisions here mirror
+ * `emitChildren` exactly, including the marker comment after a dynamic child
+ * that is not the last one.
+ *
+ * That mirroring is a promise between two files, which is the kind of promise
+ * that rots. It is held by `packages/server/test/parity.test.tsx`, which
+ * renders every shape both ways and compares what comes out.
+ */
+export declare function compileMarkup(path: NodePath<t.JSXElement>, state: State): t.Expression;
+//# sourceMappingURL=markup.d.ts.map

package/dist/markup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markup.d.ts","sourceRoot":"","sources":["../src/markup.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEhD,OAAO,KAAK,CAAC,MAAM,cAAc,CAAC;AAoBlC,OAAO,EAAW,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AAoBjD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,KAAK,GAAG,CAAC,CAAC,UAAU,CAatF"}

package/dist/nodes.d.ts

@@ -0,0 +1,55 @@
+/**
+ * What a node is, asked of the node.
+ *
+ * Small, total questions about a Babel AST: is this tag a component, is this
+ * value static, what is this attribute called. Nothing here reads the
+ * compiler's state or emits anything, which is what makes them safe to call
+ * from any pass — and why they are in one module rather than repeated in
+ * three.
+ */
+import type { NodePath } from '@babel/traverse';
+import * as t from '@babel/types';
+export declare function isComponentTag(node: t.JSXElement): boolean;
+export declare function tagExpression(name: t.JSXIdentifier | t.JSXMemberExpression): t.Expression;
+/**
+ * Whether evaluating an expression is something nobody could notice.
+ *
+ * Names, member chains, literals and the operators over them: reading them
+ * early is the same as reading them late. A call is not — it may do anything,
+ * including not returning — and neither is anything that writes, waits or
+ * constructs. Deliberately conservative: a shape not listed here is treated as
+ * observable, which costs an accessor and never a wrong answer.
+ */
+export declare function isPure(node: t.Expression): boolean;
+export declare function propertyKey(name: string): t.Identifier | t.StringLiteral;
+export declare function attributeName(attribute: t.JSXAttribute): string;
+export declare function attributeValue(attribute: t.JSXAttribute): t.Expression | null;
+export declare function isStaticValue(value: t.Expression): boolean;
+export declare function canInlineAttribute(name: string): boolean;
+export declare function isFirsthandImport(binding: {
+    path: NodePath;
+}): boolean;
+export declare function declaredName(path: NodePath<t.CallExpression>): string;
+export type ChildEntry = {
+    kind: 'text' | 'element' | 'dynamic' | 'list';
+    text?: string;
+    element?: t.JSXElement;
+    expression?: t.Expression;
+};
+/**
+ * Groups JSX children into DOM nodes.
+ *
+ * Adjacent text and static expressions merge into one text node, which is what
+ * the HTML parser will produce, so child indices stay correct.
+ */
+export declare function planChildren(children: t.JSXElement['children']): ChildEntry[];
+/**
+ * The text a static attribute value stands for.
+ *
+ * `false` and `null` are absences rather than values — an attribute written
+ * with either is not written at all — so they are `null` here and the caller
+ * omits the attribute. Both paths need this and have to agree: a value the
+ * server writes and the browser omits is a hydration mismatch.
+ */
+export declare function staticLiteral(value: t.Expression): string | null;
+//# sourceMappingURL=nodes.d.ts.map

package/dist/nodes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodes.d.ts","sourceRoot":"","sources":["../src/nodes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEhD,OAAO,KAAK,CAAC,MAAM,cAAc,CAAC;AAQlC,wBAAgB,cAAc,CAAC,IAAI,EAAE,CAAC,CAAC,UAAU,GAAG,OAAO,CAS1D;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC,aAAa,GAAG,CAAC,CAAC,mBAAmB,GAAG,CAAC,CAAC,UAAU,CAKzF;AAED;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,UAAU,GAAG,OAAO,CAWlD;AAuED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,aAAa,CAExE;AAED,wBAAgB,aAAa,CAAC,SAAS,EAAE,CAAC,CAAC,YAAY,GAAG,MAAM,CAG/D;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,UAAU,GAAG,IAAI,CAc7E;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,CAAC,CAAC,UAAU,GAAG,OAAO,CAO1D;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOxD;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAAG,OAAO,CAOtE;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC,GAAG,MAAM,CAMrE;AAED,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,CAAC,CAAC,UAAU,CAAC;IACvB,UAAU,CAAC,EAAE,CAAC,CAAC,UAAU,CAAC;CAC3B,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,CAAC,CAAC,UAAU,CAAC,UAAU,CAAC,GAAG,UAAU,EAAE,CAsC7E;AAqBD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,CAAC,CAAC,UAAU,GAAG,MAAM,GAAG,IAAI,CAWhE"}

package/dist/options.d.ts

@@ -0,0 +1,48 @@
+/** The options the Babel plugin takes. */
+export type FirsthandPluginOptions = {
+    /** Package name used when hashing stable component ids (ADR-0004). */
+    packageName?: string;
+    /**
+     * Refuse to compile a value that is read once in a setup and then kept.
+     *
+     * **On by default.** The rule only sees declarations whose initialiser is
+     * nothing but a read, which is the shape that is almost always a mistake;
+     * anything containing a call is left alone. `false` turns it off for a
+     * codebase that has such a read on purpose and would rather not mark it with
+     * `snapshot()` — see `checkKeptReads` (ADR-0019).
+     */
+    strictReactivity?: boolean;
+    /**
+     * Name the cells a module creates, for devtools.
+     *
+     * A runtime cannot see that `const count = signal(0)` is called `count`, and
+     * `new Error().stack` reports a position in the *compiled* module — the
+     * browser does not apply source maps to `error.stack`, so the line it names
+     * is not the line that was written. The compiler knows both, so it says so.
+     *
+     * Off by default and turned on by the Vite plugin while serving: a
+     * production build emits nothing.
+     */
+    devtools?: boolean;
+    /**
+     * Compile for a server render.
+     *
+     * The same source, emitted against `@firsthandjs/server/internal` instead of
+     * `@firsthandjs/dom/internal`: markup is built as a string rather than as
+     * nodes, and the things a server cannot do — listeners, refs, retained
+     * sites — are not emitted at all.
+     *
+     * The Vite plugin sets this from the bundler's own `ssr` flag, so an
+     * application configures nothing.
+     */
+    ssr?: boolean;
+    /**
+     * Emit navigation that can walk server markup.
+     *
+     * An application that hydrates needs it; one that does not should leave it
+     * off, because it turns two property reads per dynamic position into two
+     * calls. The Vite plugin sets it for a project that has a server build.
+     */
+    hydratable?: boolean;
+};
+//# sourceMappingURL=options.d.ts.map

package/dist/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAE1C,MAAM,MAAM,sBAAsB,GAAG;IACnC,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;;;;;OAUG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;IACd;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC"}

package/dist/plugin.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The Babel plugin: the visitors, and the order the passes run in.
+ *
+ * Two passes run on `Program` before anything is compiled, because both answer
+ * questions that must not depend on the order Babel walks in. Everything the
+ * module accumulates — templates, imports, view registrations — is written
+ * back out on the way past `Program` again.
+ */
+import type { PluginObject } from '@babel/core';
+import type { FirsthandPluginOptions } from './options.js';
+export default function firsthandPlugin(_api: unknown, options?: FirsthandPluginOptions): PluginObject;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAchD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAQ3D,MAAM,CAAC,OAAO,UAAU,eAAe,CACrC,IAAI,EAAE,OAAO,EACb,OAAO,GAAE,sBAA2B,GACnC,YAAY,CA+Cd"}

package/dist/positions.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Source positions, for the debugger rather than for the compiler.
+ *
+ * None of this changes what the emitted code does. It decides which line a
+ * breakpoint can be set on and which column a debugger draws a marker in,
+ * which is the difference between a source map that is technically correct
+ * and one somebody can work in. The reasoning is in the comments below,
+ * because every one of these was arrived at by watching a debugger get it
+ * wrong.
+ */
+import * as t from '@babel/types';
+/**
+ * Wraps an expression so a part can re-read it, and gives the wrapper its
+ * position.
+ *
+ * The position moves from the expression to the thunk rather than being copied
+ * to both. A debugger draws one marker per distinct original column on a line,
+ * and an expression that kept its own position produced two — one where it
+ * begins and one where it ends — which look identical and do the same thing.
+ * With the wrapper owning the position, every breakable place inside it
+ * reports the same column: one marker, on the expression, hit on the first
+ * evaluation and on every later one.
+ */
+export declare function thunk(expression: t.Expression): t.ArrowFunctionExpression;
+/**
+ * Moves an expression's position onto the thing the compiler wrapped it in.
+ *
+ * A point rather than a range. The generator maps both ends of a node, and an
+ * end one column along is a second marker that looks identical to the first
+ * and does the same thing. A wrapper the compiler invented does not span
+ * anything in the source anyway — it belongs where the expression begins.
+ *
+ * It matters for more than tidiness: a debugger offers a breakpoint on a line
+ * only where a *statement* is mapped to it. An expression buried in a getter
+ * the compiler wrote has no statement of its own, and the line it came from
+ * cannot be stopped on at all until one carries its position.
+ */
+export declare function takePosition(target: t.Node, expression: t.Expression): void;
+export declare function expressionStatement(expression: t.Expression): t.Statement;
+/**
+ * Gives a node the compiler built the position of the code it stands for.
+ *
+ * Without this the generated statement has no position at all, so the source
+ * map has nothing to say about it — and a debugger cannot put a breakpoint on
+ * a line it cannot find. `{v}` becoming `_$insert(el, () => props.v)` is the
+ * case that matters: that call *is* the expression, and should be reachable
+ * where the expression was written.
+ */
+export declare function located<T extends t.Node>(node: T, source: t.Node | null | undefined): T;
+//# sourceMappingURL=positions.d.ts.map

package/dist/positions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"positions.d.ts","sourceRoot":"","sources":["../src/positions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,CAAC,MAAM,cAAc,CAAC;AAIlC;;;;;;;;;;;GAWG;AACH,wBAAgB,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,uBAAuB,CAKzE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC,UAAU,GAAG,IAAI,CAM3E;AAED,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,SAAS,CAEzE;AAED;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,IAAI,GAAG,IAAI,GAAG,SAAS,GAAG,CAAC,CAUvF"}

package/dist/props.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Destructured props, rewritten into live reads (ADR-0005).
+ *
+ * The one pass that changes what the author wrote rather than adding to it,
+ * and the reasoning for that is under `rewritePropsDestructuring`.
+ */
+import type { NodePath } from '@babel/traverse';
+import * as t from '@babel/types';
+import { type State } from './state.js';
+/**
+ * Rewrites destructured props into live reads.
+ *
+ * `component(({ todo }) => ...)` is the shape people want to write, and it is
+ * also the shape that silently snapshots: the binding is captured once, at
+ * setup, and never changes again. The compiler makes it mean what it looks
+ * like instead — every reference to `todo` becomes `props.todo`, which is a
+ * live read that subscribes only the part performing it.
+ *
+ * The rewrite is a rename, not a wrapper: there is no runtime cost, and the
+ * emitted code is what a developer would have written by hand. What cannot be
+ * rewritten soundly is still an error rather than a guess — assigning to a
+ * destructured prop, or an array pattern, which props are not.
+ */
+export declare function rewritePropsDestructuring(call: NodePath<t.CallExpression>, name: string, state: State): void;
+//# sourceMappingURL=props.d.ts.map

package/dist/props.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"props.d.ts","sourceRoot":"","sources":["../src/props.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEhD,OAAO,KAAK,CAAC,MAAM,cAAc,CAAC;AAIlC,OAAO,EAAW,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC,EAChC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,KAAK,GACX,IAAI,CAwCN"}

package/dist/runs.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Which function a piece of markup belongs to, and what that function owns.
+ *
+ * Two passes run before anything is compiled — `collectViews` and
+ * `collectRuns` — because both answer questions that must not depend on the
+ * order Babel happens to walk in. Everything else here is asked later, of one
+ * node at a time, and answered from what those two found.
+ */
+import type { NodePath } from '@babel/traverse';
+import * as t from '@babel/types';
+import { type Build, type RunContext, type State } from './state.js';
+/**
+ * Finds every function this module writes markup inside, before anything is
+ * compiled.
+ *
+ * This is the line between a view of ours and a component of somebody else's,
+ * and it is drawn where it can actually be seen: **which compiler turned the
+ * markup into code.** A function that builds its result with another
+ * framework's `createElement` contains no markup for this compiler to
+ * translate, so it is not ours and is left to the adapter — even though it is
+ * a local function that returns something renderable.
+ *
+ * A pass of its own rather than a note taken while compiling, because a tag
+ * can stand above the function it names and the answer must not depend on the
+ * order Babel happens to walk in.
+ *
+ * Every enclosing function is recorded, not only the innermost: a view that
+ * builds its markup in a helper closure is still a view.
+ */
+export declare function collectViews(program: NodePath<t.Program>, state: State): void;
+/**
+ * Whether a tag names a plain function declared in this module.
+ *
+ * Then the compiler knows what it is — it compiled the markup inside it — and
+ * emits the call itself. Nothing is looked up at runtime, so an installed
+ * adapter for another framework never sees it, and the decision cannot be
+ * wrong. An imported name is left to `createComponent`, which reads the mark.
+ */
+export declare function isLocalView(path: NodePath<t.JSXElement>, state: State): boolean;
+/**
+ * Finds the functions that run again as a whole, and gives each one a store.
+ *
+ * A render function is the one a setup returns. The setup runs once per
+ * instance, so a `const` declared there is per instance too — which is exactly
+ * what a store has to be, and why this needs no registry and no ambient state.
+ */
+export declare function collectRuns(program: NodePath<t.Program>, state: State): void;
+/** The run this markup belongs to, or `null` when it is built once. */
+export declare function enclosingRun(path: NodePath, state: State): RunContext | null;
+/**
+ * Whether an expression needs a value that belongs to one run of the function.
+ *
+ * This is the whole classification, and it is forced rather than chosen: an
+ * expression that names nothing from the run can be given a scope of its own
+ * and left to update itself, and one that names something from the run cannot
+ * — that value belongs to the call that produced it, so the run must write it.
+ */
+export declare function dependsOnRun(node: t.Node, run: RunContext | null, at: NodePath): boolean;
+/**
+ * Whether a site can be kept between runs.
+ *
+ * Everything a run needs to write has to be something this compiler knows how
+ * to write. A spread, a `ref` or a keyed list is made once by its nature, and
+ * making one once out of a value that belongs to a single run would hold that
+ * run's value for ever — so such a site is built afresh instead, which is what
+ * happens today and is never wrong.
+ */
+export declare function canRetain(node: t.JSXElement, build: Build): boolean;
+//# sourceMappingURL=runs.d.ts.map

package/dist/runs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runs.d.ts","sourceRoot":"","sources":["../src/runs.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEhD,OAAO,KAAK,CAAC,MAAM,cAAc,CAAC;AAMlC,OAAO,EAAW,KAAK,KAAK,EAAE,KAAK,UAAU,EAAE,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AAE9E;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAiB7E;AA6BD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAuB/E;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAM5E;AAwGD,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,GAAG,UAAU,GAAG,IAAI,CAa5E;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,UAAU,GAAG,IAAI,EAAE,EAAE,EAAE,QAAQ,GAAG,OAAO,CAmBxF;AA4CD;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,UAAU,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAuBnE"}

package/dist/site.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The site a template occupies, in its two forms.
+ *
+ * Built every time it is reached, or built once and written into afterwards —
+ * which one is decided before anything is emitted, so that what comes out is
+ * all of one kind (ADR-0026).
+ */
+import type { NodePath } from '@babel/traverse';
+import * as t from '@babel/types';
+import { type State } from './state.js';
+export declare function compileTemplate(path: NodePath<t.JSXElement>, state: State): t.Expression;
+//# sourceMappingURL=site.d.ts.map

package/dist/site.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"site.d.ts","sourceRoot":"","sources":["../src/site.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEhD,OAAO,KAAK,CAAC,MAAM,cAAc,CAAC;AAQlC,OAAO,EAAwC,KAAK,KAAK,EAAE,MAAM,YAAY,CAAC;AAI9E,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,KAAK,GAAG,CAAC,CAAC,UAAU,CAWxF"}

package/dist/state.d.ts

@@ -0,0 +1,84 @@
+/**
+ * What one module's compilation knows about itself.
+ *
+ * Everything here is per-file and lives for one `transform()`. The two import
+ * helpers are the only way a pass names something from the runtime, which is
+ * what keeps the import list at the top of the output correct without anyone
+ * maintaining it: asking for a name is what adds it.
+ */
+import type { PluginPass } from '@babel/core';
+import type { NodePath } from '@babel/traverse';
+import * as t from '@babel/types';
+export type FirsthandState = {
+    imports: Map<string, t.Identifier>;
+    templates: t.VariableDeclarator[];
+    counter: number;
+    moduleId: string;
+    /** Module-level functions markup was compiled into, in source order. */
+    views: Map<string, t.Identifier>;
+    /** Every function markup was written inside, for resolving tags locally. */
+    viewNodes: Set<t.Node>;
+    /** Whether this module is being compiled for a server render. */
+    ssr: boolean;
+    /** Whether this module's output has to be able to adopt server markup. */
+    hydratable: boolean;
+    /** Functions that run again as a whole, and where each keeps its sites. */
+    runs: Map<t.Node, RunContext>;
+};
+/**
+ * What a re-running function needs in order to keep its DOM.
+ *
+ * `store` is an array declared once per instance — in the setup, which runs
+ * once — and every site inside the run takes a numbered place in it. The index
+ * is fixed at compile time, so a site inside an `if` keeps its own place
+ * whether or not the branch was taken: nothing depends on the order the run
+ * happens to reach things in, which is the rule React needs for hooks and this
+ * does not.
+ */
+export type RunContext = {
+    /** The function whose body re-runs. Bindings inside it belong to one run. */
+    node: t.Node;
+    store: t.Identifier;
+    next: () => number;
+};
+declare module '@babel/core' {
+    interface PluginPass {
+        firsthand: FirsthandState;
+    }
+}
+export type State = PluginPass;
+export type Build = {
+    html: string[];
+    /** Navigation to the nodes a template's parts need. Runs every time. */
+    statements: t.Statement[];
+    /** Work done when the site is made: parts, listeners, refs. */
+    once: t.Statement[];
+    /** Writes the run performs into a site it already made. */
+    each: t.Statement[];
+    run: RunContext | null;
+    /** Where to resolve names from, when deciding what belongs to the run. */
+    at: NodePath;
+    next: () => t.Identifier;
+    name: (prefix: string) => t.Identifier;
+};
+export declare function pushOnce(build: Build, statement: t.Statement): void;
+export declare function pushEach(build: Build, statement: t.Statement): void;
+export declare function runtime(state: State, name: string, source?: string): t.Identifier;
+export declare function runtimeFrom(state: State, name: string, source: string): t.Identifier;
+/**
+ * The element an attribute or a child is being emitted onto.
+ *
+ * Four things that always travel together — where the output goes, which
+ * variable holds the node, the module's state, and the tag, which decides
+ * whether a name is a DOM property. `deferred` is the work that cannot happen
+ * until the opening tag is closed: a listener needs the node, and the node does
+ * not exist while its attributes are still being written into the HTML.
+ */
+export type Host = {
+    build: Build;
+    self: t.Identifier;
+    state: State;
+    deferred: (() => void)[];
+    tag: string;
+};
+//# sourceMappingURL=state.d.ts.map

package/dist/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEhD,OAAO,KAAK,CAAC,MAAM,cAAc,CAAC;AAKlC,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC;IACnC,SAAS,EAAE,CAAC,CAAC,kBAAkB,EAAE,CAAC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC;IACjC,4EAA4E;IAC5E,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACvB,iEAAiE;IACjE,GAAG,EAAE,OAAO,CAAC;IACb,0EAA0E;IAC1E,UAAU,EAAE,OAAO,CAAC;IACpB,2EAA2E;IAC3E,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;CAC/B,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,6EAA6E;IAC7E,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC;IACb,KAAK,EAAE,CAAC,CAAC,UAAU,CAAC;IACpB,IAAI,EAAE,MAAM,MAAM,CAAC;CACpB,CAAC;AAEF,OAAO,QAAQ,aAAa,CAAC;IAC3B,UAAU,UAAU;QAClB,SAAS,EAAE,cAAc,CAAC;KAC3B;CACF;AAED,MAAM,MAAM,KAAK,GAAG,UAAU,CAAC;AAE/B,MAAM,MAAM,KAAK,GAAG;IAClB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,wEAAwE;IACxE,UAAU,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC;IAC1B,+DAA+D;IAC/D,IAAI,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC;IACpB,2DAA2D;IAC3D,IAAI,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC;IACpB,GAAG,EAAE,UAAU,GAAG,IAAI,CAAC;IACvB,0EAA0E;IAC1E,EAAE,EAAE,QAAQ,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,CAAC,UAAU,CAAC;IACzB,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,CAAC,CAAC,UAAU,CAAC;CACxC,CAAC;AAEF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,GAAG,IAAI,CAEnE;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,GAAG,IAAI,CAEnE;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,UAAU,CAEjF;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,CAAC,CAAC,UAAU,CAQpF;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,IAAI,GAAG;IACjB,KAAK,EAAE,KAAK,CAAC;IACb,IAAI,EAAE,CAAC,CAAC,UAAU,CAAC;IACnB,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;CACb,CAAC"}