@firsthandjs/compiler 0.9.1 → 0.10.1

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"}

package/dist/strict.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The four things strict reactivity refuses to compile (ADR-0019).
+ *
+ * Every rule here stops a build, so every rule here is deliberately narrow:
+ * a false positive costs somebody a working program, and a false negative
+ * costs them the warning they would have got anyway the first time they looked
+ * at the screen. Where a shape could go either way, it is allowed.
+ *
+ * All four are *refusals*. Nothing in this module rewrites anything.
+ */
+import type { NodePath } from '@babel/traverse';
+import * as t from '@babel/types';
+/**
+ * Rejects a value that is read once in a setup and then kept (ADR-0019).
+ *
+ * The setup runs one time per instance, so `const total = props.total` is a
+ * number from the moment it is read and will not move again. Nothing throws at
+ * runtime — the number is simply old — which is why this exists.
+ *
+ * Deliberately narrow, because a false positive here stops a build. Only a
+ * declaration whose initialiser is *nothing but* a read is reported:
+ * identifiers, member accesses, literals and the operators between them. A
+ * call is never reported, which leaves `signal(props.initial)`, `peek()`,
+ * `computed(...)` and every handler alone — including `snapshot(...)`, the way
+ * to say that reading once is the point.
+ */
+export declare function checkKeptReads(setup: NodePath<t.Function>, name: string): void;
+/**
+ * Rejects a view chosen once, in the setup, from something that changes.
+ *
+ * ```tsx
+ * // Decided while the component was built, and never again:
+ * return open.value ? <Form /> : <Button />;
+ *
+ * // A part, re-evaluated when `open` changes:
+ * return <>{open.value ? <Form /> : <Button />}</>;
+ * ```
+ *
+ * The two look the same and behave completely differently, because a setup
+ * runs once per instance: the first form freezes whichever branch was true at
+ * setup, and nothing throws — the screen is simply wrong, later, in a way that
+ * reads as a broken button.
+ *
+ * Only the **returned expression** is examined, and only when a signal decides
+ * which view it produces. A read *inside* JSX is a part and is left alone; so
+ * is a return with no JSX in it at all, which is somebody's helper rather than
+ * a view.
+ *
+ * Deliberately narrow, because a false positive here stops a build. A `.value`
+ * read is reported and a **prop read is not**: a signal exists in order to
+ * change, while a prop may be fixed for the life of an instance — a recursive
+ * `<Nested depth={props.depth - 1} />` chooses its shape once on purpose, and
+ * a rule that could not tell the difference would refuse it.
+ */
+export declare function checkDecidedOnce(setup: NodePath<t.Function>, name: string): void;
+/**
+ * Rejects the two things a render function cannot do.
+ *
+ * **Nothing persistent is made in a run.** A signal, a computed, an effect or
+ * a resource is a thing that outlives the moment it was made; a run happens
+ * again, so one made there would be made again, and the one before it thrown
+ * away. That is not a rule about order — it is the same rule as everywhere
+ * else in Firsthand, said once: persistent things are made in the setup.
+ *
+ * **Repeated markup carries a key.** A site is identified by where it stands,
+ * which answers for markup that appears once. Markup inside a loop appears
+ * many times from one place, and only a key can say which of them is which.
+ * Without one, a run would take the rows apart and build them again — silently,
+ * losing whatever they held.
+ */
+export declare function checkRunBody(setup: NodePath<t.Function>, name: string): void;
+//# sourceMappingURL=strict.d.ts.map

package/dist/strict.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strict.d.ts","sourceRoot":"","sources":["../src/strict.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEhD,OAAO,KAAK,CAAC,MAAM,cAAc,CAAC;AAMlC;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CA8B9E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CA+BhF;AAmCD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAoB5E"}

package/dist/template.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A host element: the markup that goes into the `<template>`, and the parts
+ * that write into a clone of it (ADR-0009).
+ *
+ * Where that clone lives between runs — built every time, or built once and
+ * written into — is `site.ts`.
+ */
+import * as t from '@babel/types';
+import { type Build, type State } from './state.js';
+export declare function emitElement(node: t.JSXElement, build: Build, self: t.Identifier, state: State): void;
+//# sourceMappingURL=template.d.ts.map

package/dist/template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../src/template.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,CAAC,MAAM,cAAc,CAAC;AAmBlC,OAAO,EAIL,KAAK,KAAK,EAGV,KAAK,KAAK,EACX,MAAM,YAAY,CAAC;AAEpB,wBAAgB,WAAW,CACzB,IAAI,EAAE,CAAC,CAAC,UAAU,EAClB,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,CAAC,CAAC,UAAU,EAClB,KAAK,EAAE,KAAK,GACX,IAAI,CA2BN"}

package/dist/transform.d.ts

@@ -10,92 +10,20 @@
  *
  * The transform emits calls against the published protocol in
  * `@firsthandjs/dom/internal` and has no privileged access to the runtime.
- */
-import type { PluginObject } from '@babel/core';
-import * as t from '@babel/types';
-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.
+ * | Module          | What it decides                                     |
+ * | --------------- | --------------------------------------------------- |
+ * | `plugin.ts`     | which pass runs when                                |
+ * | `components.ts` | what a `component(...)` call gains                  |
+ * | `strict.ts`     | what will not compile at all (ADR-0019)             |
+ * | `props.ts`      | destructured props as live reads (ADR-0005)         |
+ * | `runs.ts`       | which function a piece of markup belongs to         |
+ * | `lists.ts`      | `.map` with a key as a keyed list part              |
+ * | `jsx.ts`        | component call, server markup, or template          |
+ * | `template.ts`   | the browser's `<template>` and the parts into it    |
+ * | `markup.ts`     | the server's string and the holes in it             |
+ * | `attributes.ts` | one attribute, inlined or written                   |
  */
-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 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;
-};
-export default function firsthandPlugin(_api: unknown, options?: FirsthandPluginOptions): PluginObject;
-export {};
+export { default } from './plugin.js';
+export type { FirsthandPluginOptions } from './options.js';
 //# sourceMappingURL=transform.d.ts.map

package/dist/transform.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transform.d.ts","sourceRoot":"","sources":["../src/transform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAc,MAAM,aAAa,CAAC;AAE5D,OAAO,KAAK,CAAC,MAAM,cAAc,CAAC;AAgBlC,KAAK,cAAc,GAAG;IACpB,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,KAAK,UAAU,GAAG;IAChB,6EAA6E;IAC7E,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC;IACb,KAAK,EAAE,CAAC,CAAC,UAAU,CAAC;IACpB,IAAI,EAAE,MAAM,MAAM,CAAC;CACpB,CAAC;AAyBF,OAAO,QAAQ,aAAa,CAAC;IAC3B,UAAU,UAAU;QAClB,SAAS,EAAE,cAAc,CAAC;KAC3B;CACF;AA2BD,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;AAEF,MAAM,CAAC,OAAO,UAAU,eAAe,CACrC,IAAI,EAAE,OAAO,EACb,OAAO,GAAE,sBAA2B,GACnC,YAAY,CAiFd"}
+{"version":3,"file":"transform.d.ts","sourceRoot":"","sources":["../src/transform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAEtC,YAAY,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC"}

package/dist/vite.js

@@ -1,6 +1,6 @@
 import {
   compileModule
-} from "./chunk-GUVVHV7H.js";
+} from "./chunk-SRIXSLZ7.js";
 
 // packages/compiler/src/vite.ts
 function firsthand(options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firsthandjs/compiler",
-  "version": "0.9.1",
+  "version": "0.10.1",
   "description": "Build-time TSX transform for Firsthand: static markup into templates, dynamic expressions into DOM parts.",
   "license": "MIT",
   "type": "module",