@firsthandjs/compiler 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Firsthand contributors
+
+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/README.md

@@ -0,0 +1,28 @@
+# @firsthandjs/compiler
+
+The build-time half of Firsthand. Nothing here ships to the browser.
+
+**Documentation:** [guide](https://github.com/firsthandjs/firsthand/blob/main/docs/guide/14-building.md) · [API reference](https://github.com/firsthandjs/firsthand/blob/main/docs/reference/compiler.md) · [all docs](https://github.com/firsthandjs/firsthand/blob/main/docs/README.md)
+
+```ts
+// vite.config.ts
+import { firsthand } from '@firsthandjs/compiler/vite';
+
+export default { plugins: [firsthand({ packageName: 'my-app' })] };
+```
+
+What it does:
+
+- hoists static markup into one `<template>` per shape, cloned per instance;
+- turns every dynamic expression into a thunk handed to a specialised part;
+- rewrites a keyed `.map()` into a list part with live item reads;
+- gives each `component(...)` a stable build id that survives minification;
+- refuses to compile props destructuring, because that would snapshot.
+
+It emits calls against the published protocol in `@firsthandjs/dom/internal` and
+has no privileged access to the runtime.
+
+Full documentation: the [repository README](../../README.md) and
+[ADR-0009](../../docs/adr/0009-compiler-templates-and-thunks.md).
+
+MIT licensed.

package/dist/api.d.ts

@@ -0,0 +1,13 @@
+import { type FirsthandPluginOptions } from './transform.js';
+export interface TransformOptions extends FirsthandPluginOptions {
+    filename?: string;
+    /**
+     * Parse TypeScript syntax. The annotations are left in the output: stripping
+     * them is the bundler's job, and doing it here would duplicate work and
+     * source-map hops.
+     */
+    typescript?: boolean;
+}
+/** Compiles one module. Used by the Vite plugin and by the compiler tests. */
+export declare function transform(code: string, options?: TransformOptions): string;
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAGA,OAAwB,EAAE,KAAK,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAE9E,MAAM,WAAW,gBAAiB,SAAQ,sBAAsB;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,8EAA8E;AAC9E,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,MAAM,CAW9E"}

package/dist/chunk-HHKCDDN2.js

@@ -0,0 +1,841 @@
+// packages/compiler/src/ids.ts
+import { createHash } from "node:crypto";
+function stableId(packageName, filename) {
+  const normalised = filename.split(String.fromCharCode(92)).join("/").replace(/^(?:.*\/)?(?:src|lib)\//, "");
+  return createHash("sha256").update(`${packageName}:${normalised}`).digest("hex").slice(0, 8);
+}
+
+// packages/compiler/src/transform.ts
+import * as t from "@babel/types";
+
+// packages/compiler/src/html.ts
+var VOID_ELEMENTS = /* @__PURE__ */ new Set([
+  "area",
+  "base",
+  "br",
+  "col",
+  "embed",
+  "hr",
+  "img",
+  "input",
+  "link",
+  "meta",
+  "param",
+  "source",
+  "track",
+  "wbr"
+]);
+var BOOLEAN_PROPERTIES = /* @__PURE__ */ new Set([
+  "checked",
+  "disabled",
+  "multiple",
+  "muted",
+  "readOnly",
+  "selected",
+  "autofocus",
+  "autoplay",
+  "controls",
+  "loop",
+  "open",
+  "required"
+]);
+var DOM_PROPERTIES = /* @__PURE__ */ new Set([
+  "value",
+  "textContent",
+  "innerHTML",
+  "innerText",
+  "scrollTop",
+  "scrollLeft",
+  "volume",
+  "currentTime",
+  "playbackRate",
+  "srcObject"
+]);
+var SVG_ELEMENTS = /* @__PURE__ */ new Set([
+  "svg",
+  "path",
+  "circle",
+  "rect",
+  "line",
+  "polyline",
+  "polygon",
+  "ellipse",
+  "g",
+  "defs",
+  "use",
+  "text",
+  "tspan",
+  "symbol",
+  "mask",
+  "pattern",
+  "clipPath",
+  "linearGradient",
+  "radialGradient",
+  "stop",
+  "filter"
+]);
+function escapeText(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;");
+}
+function escapeAttribute(value) {
+  return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+}
+function eventName(attribute) {
+  return attribute.slice(2).toLowerCase();
+}
+
+// packages/compiler/src/transform.ts
+var RUNTIME = "@firsthandjs/dom/internal";
+var CORE = "@firsthandjs/core";
+function firsthandPlugin(_api, options = {}) {
+  return {
+    name: "firsthand",
+    visitor: {
+      Program: {
+        enter(_path, state) {
+          state.firsthand = {
+            imports: /* @__PURE__ */ new Map(),
+            templates: [],
+            counter: 0,
+            moduleId: stableId(options.packageName ?? "app", state.filename ?? "module")
+          };
+        },
+        exit(path, state) {
+          const { imports, templates } = state.firsthand;
+          if (templates.length > 0) {
+            path.node.body.unshift(t.variableDeclaration("const", templates));
+          }
+          for (const [source, names] of groupBySource(imports)) {
+            path.node.body.unshift(
+              t.importDeclaration(
+                names.map(([exported, local]) => t.importSpecifier(local, t.identifier(exported))),
+                t.stringLiteral(source)
+              )
+            );
+          }
+        }
+      },
+      // Babel enters the outermost JSX node first. Its nested elements are
+      // folded into the template and discarded; the nodes that survive (a
+      // component's children, a dynamic expression) are re-visited later, by
+      // which time they are no longer inside JSX.
+      JSXElement(path, state) {
+        rewriteKeyedMaps(path, state);
+        path.replaceWith(compileNode(path, state));
+      },
+      JSXFragment(path, state) {
+        rewriteKeyedMaps(path, state);
+        path.replaceWith(compileNode(path, state));
+      },
+      CallExpression(path, state) {
+        annotateComponent(path, state);
+      }
+    }
+  };
+}
+function groupBySource(imports) {
+  const grouped = /* @__PURE__ */ new Map();
+  for (const [key, local] of imports) {
+    const separator = key.indexOf("#");
+    const source = key.slice(0, separator);
+    const exported = key.slice(separator + 1);
+    const bucket = grouped.get(source);
+    if (bucket === void 0) {
+      grouped.set(source, [[exported, local]]);
+    } else {
+      bucket.push([exported, local]);
+    }
+  }
+  return grouped;
+}
+function runtime(state, name, source = RUNTIME) {
+  const key = `${source}#${name}`;
+  let local = state.firsthand.imports.get(key);
+  if (local === void 0) {
+    local = t.identifier(`_$${name}`);
+    state.firsthand.imports.set(key, local);
+  }
+  return t.cloneNode(local);
+}
+function annotateComponent(path, state) {
+  const callee = path.node.callee;
+  if (!t.isIdentifier(callee, { name: "component" }) || path.node.arguments.length > 2) {
+    return;
+  }
+  const binding = path.scope.getBinding("component");
+  if (binding === void 0 || !isFirsthandImport(binding)) {
+    return;
+  }
+  const setup = path.node.arguments[0];
+  if (!t.isArrowFunctionExpression(setup) && !t.isFunctionExpression(setup)) {
+    return;
+  }
+  const name = declaredName(path);
+  rewritePropsDestructuring(path, name, state);
+  path.node.arguments = [
+    setup,
+    path.node.arguments[1] ?? t.identifier("undefined"),
+    t.stringLiteral(`${state.firsthand.moduleId}/${name}`),
+    t.stringLiteral(name)
+  ];
+}
+function isFirsthandImport(binding) {
+  const parent = binding.path.parentPath;
+  if (!parent.isImportDeclaration()) {
+    return false;
+  }
+  const source = parent.node.source.value;
+  return source === CORE || source.startsWith("@firsthandjs/") || source === "firsthand";
+}
+function declaredName(path) {
+  const parent = path.parentPath;
+  if (parent.isVariableDeclarator() && t.isIdentifier(parent.node.id)) {
+    return parent.node.id.name;
+  }
+  return "Component";
+}
+function rewritePropsDestructuring(call, name, state) {
+  const setup = call.get("arguments.0");
+  const params = setup.get("params");
+  const param = params[0];
+  if (param === void 0 || param.isIdentifier()) {
+    return;
+  }
+  if (!param.isObjectPattern()) {
+    throw call.buildCodeFrameError(
+      `${name}: a component's props parameter must be an object pattern or a plain identifier. Props are an object, so an array pattern cannot destructure them.`
+    );
+  }
+  const propsId = setup.scope.generateUidIdentifier("props");
+  const reads = [];
+  const restNames = [];
+  collectPattern(param.node, t.cloneNode(propsId), reads, restNames, call, name);
+  setup.scope.crawl();
+  const references = [];
+  for (const read of [...reads, ...restNames.map((r) => ({ local: r.local, access: propsId }))]) {
+    const binding = setup.scope.getBinding(read.local);
+    if (binding.constantViolations.length > 0) {
+      throw call.buildCodeFrameError(
+        `${name}: \`${read.local}\` is destructured from props and then assigned to. Props are readonly; assign to a signal instead.`
+      );
+    }
+    references.push({ paths: binding.referencePaths, access: read.access });
+  }
+  param.replaceWith(propsId);
+  for (const entry of references) {
+    for (const reference of entry.paths) {
+      if (entry.access !== propsId) {
+        reference.replaceWith(t.cloneNode(entry.access));
+      }
+    }
+  }
+  if (restNames.length > 0) {
+    if (!setup.get("body").isBlockStatement()) {
+      const body = setup.node.body;
+      setup.node.body = t.blockStatement([t.returnStatement(body)]);
+    }
+    const block = setup.get("body");
+    for (const rest of restNames) {
+      block.node.body.unshift(
+        t.variableDeclaration("const", [
+          t.variableDeclarator(
+            t.identifier(rest.local),
+            t.callExpression(runtime(state, "rest"), [
+              t.cloneNode(propsId),
+              t.arrayExpression(rest.omit.map((key) => t.stringLiteral(key)))
+            ])
+          )
+        ])
+      );
+    }
+  }
+}
+function collectPattern(pattern, base, reads, rests, call, name) {
+  const seen = [];
+  for (const property of pattern.properties) {
+    if (t.isRestElement(property)) {
+      rests.push({ local: property.argument.name, omit: [...seen] });
+      continue;
+    }
+    if (property.computed || !t.isIdentifier(property.key)) {
+      throw call.buildCodeFrameError(
+        `${name}: props can only be destructured by plain key. A computed key would have to be resolved at setup time, which is exactly the snapshot this rewrite avoids.`
+      );
+    }
+    seen.push(property.key.name);
+    const access = t.memberExpression(
+      t.cloneNode(base),
+      t.identifier(property.key.name)
+    );
+    const value = property.value;
+    if (t.isIdentifier(value)) {
+      reads.push({ local: value.name, access });
+    } else if (t.isAssignmentPattern(value) && t.isIdentifier(value.left)) {
+      reads.push({
+        local: value.left.name,
+        access: t.logicalExpression("??", access, value.right)
+      });
+    } else if (t.isObjectPattern(value)) {
+      collectPattern(value, access, reads, rests, call, name);
+    } else {
+      throw call.buildCodeFrameError(
+        `${name}: this destructuring pattern cannot be rewritten into live reads. Take the props object and read from it where you need the value.`
+      );
+    }
+  }
+}
+function compileNode(path, state) {
+  if (path.isJSXFragment()) {
+    return t.arrayExpression(compileChildren(path.node.children, state));
+  }
+  const node = path.node;
+  if (isComponentTag(node)) {
+    return compileComponent(path, state);
+  }
+  return compileTemplate(path, state);
+}
+function isComponentTag(node) {
+  const name = node.openingElement.name;
+  if (t.isJSXMemberExpression(name)) {
+    return true;
+  }
+  if (!t.isJSXIdentifier(name)) {
+    return false;
+  }
+  return /^[A-Z]/.test(name.name);
+}
+function tagExpression(name) {
+  if (t.isJSXIdentifier(name)) {
+    return t.identifier(name.name);
+  }
+  return t.memberExpression(tagExpression(name.object), t.identifier(name.property.name));
+}
+function compileComponent(path, state) {
+  const node = path.node;
+  const properties = [];
+  for (const attribute of node.openingElement.attributes) {
+    if (t.isJSXSpreadAttribute(attribute)) {
+      properties.push(t.spreadElement(attribute.argument));
+      continue;
+    }
+    const name = attributeName(attribute);
+    const value = attributeValue(attribute);
+    if (value === null || isStaticValue(value)) {
+      properties.push(t.objectProperty(propertyKey(name), value ?? t.booleanLiteral(true)));
+    } else {
+      properties.push(
+        t.objectMethod("get", propertyKey(name), [], t.blockStatement([t.returnStatement(value)]))
+      );
+    }
+  }
+  const children = compileChildren(node.children, state);
+  if (children.length === 1) {
+    properties.push(
+      t.objectMethod(
+        "get",
+        t.identifier("children"),
+        [],
+        t.blockStatement([t.returnStatement(children[0])])
+      )
+    );
+  } else if (children.length > 1) {
+    properties.push(
+      t.objectMethod(
+        "get",
+        t.identifier("children"),
+        [],
+        t.blockStatement([t.returnStatement(t.arrayExpression(children))])
+      )
+    );
+  }
+  return t.callExpression(runtime(state, "createComponent"), [
+    // `isComponentTag` has already excluded namespaced names.
+    tagExpression(node.openingElement.name),
+    t.objectExpression(properties)
+  ]);
+}
+function propertyKey(name) {
+  return t.isValidIdentifier(name) ? t.identifier(name) : t.stringLiteral(name);
+}
+function attributeName(attribute) {
+  const name = attribute.name;
+  return t.isJSXNamespacedName(name) ? `${name.namespace.name}:${name.name.name}` : name.name;
+}
+function attributeValue(attribute) {
+  const value = attribute.value;
+  if (value === null || value === void 0) {
+    return null;
+  }
+  if (t.isStringLiteral(value)) {
+    return value;
+  }
+  if (t.isJSXExpressionContainer(value)) {
+    return value.expression;
+  }
+  throw new Error("An element is not a valid attribute value. Wrap it in braces: attr={<El />}.");
+}
+function isStaticValue(value) {
+  return t.isStringLiteral(value) || t.isNumericLiteral(value) || t.isBooleanLiteral(value) || t.isNullLiteral(value);
+}
+function compileTemplate(path, state) {
+  const build = {
+    html: [],
+    statements: [],
+    next: /* @__PURE__ */ (() => {
+      let n = 0;
+      return () => t.identifier(`_el$${String(++n)}`);
+    })()
+  };
+  const root = t.identifier("_el$");
+  emitElement(path.node, build, root, state);
+  const templateId = t.identifier(`_tmpl$${String(++state.firsthand.counter)}`);
+  state.firsthand.templates.push(
+    t.variableDeclarator(
+      templateId,
+      t.addComment(
+        t.callExpression(runtime(state, "template"), [t.stringLiteral(build.html.join(""))]),
+        "leading",
+        "#__PURE__"
+      )
+    )
+  );
+  const body = [
+    t.variableDeclaration("const", [
+      t.variableDeclarator(root, t.callExpression(t.cloneNode(templateId), []))
+    ]),
+    ...build.statements,
+    t.returnStatement(t.cloneNode(root))
+  ];
+  return t.callExpression(t.arrowFunctionExpression([], t.blockStatement(body)), []);
+}
+function emitElement(node, build, self, state) {
+  const name = node.openingElement.name;
+  if (!t.isJSXIdentifier(name)) {
+    const namespaced = name;
+    throw new Error(
+      `Namespaced element names are not supported: <${namespaced.namespace.name}:${namespaced.name.name}>. Write the element without a namespace; SVG children are resolved by the parser.`
+    );
+  }
+  const tag = name.name;
+  build.html.push(`<${tag}`);
+  const deferred = [];
+  for (const attribute of node.openingElement.attributes) {
+    emitAttribute(attribute, build, self, state, deferred, tag);
+  }
+  build.html.push(">");
+  for (const emit of deferred) {
+    emit();
+  }
+  emitChildren(node.children, build, self, state);
+  if (!VOID_ELEMENTS.has(tag)) {
+    build.html.push(`</${tag}>`);
+  }
+}
+function emitAttribute(attribute, build, self, state, deferred, tag) {
+  if (t.isJSXSpreadAttribute(attribute)) {
+    deferred.push(() => {
+      build.statements.push(
+        expressionStatement2(
+          t.callExpression(runtime(state, "bind"), [
+            t.arrowFunctionExpression(
+              [],
+              t.callExpression(runtime(state, "spread"), [t.cloneNode(self), attribute.argument])
+            )
+          ])
+        )
+      );
+    });
+    return;
+  }
+  const name = attributeName(attribute);
+  const value = attributeValue(attribute);
+  if (name === "ref") {
+    deferred.push(() => {
+      build.statements.push(
+        expressionStatement2(t.callExpression(value, [t.cloneNode(self)]))
+      );
+    });
+    return;
+  }
+  if (name.startsWith("on") && name.length > 2 && /[A-Z:]/.test(name[2])) {
+    const parts = name.split(":");
+    const literal = parts[0] === "on";
+    const type = literal ? parts[1] : eventName(parts[0]);
+    const modifier = parts[literal ? 2 : 1];
+    deferred.push(() => {
+      const args = [
+        t.cloneNode(self),
+        t.stringLiteral(type),
+        value
+      ];
+      if (modifier === "native") {
+        args.push(t.booleanLiteral(true));
+      } else if (modifier !== void 0) {
+        args.push(
+          t.objectExpression([t.objectProperty(propertyKey(modifier), t.booleanLiteral(true))])
+        );
+      }
+      build.statements.push(expressionStatement2(t.callExpression(runtime(state, "on"), args)));
+    });
+    return;
+  }
+  if (value !== null && isStaticValue(value) && canInlineAttribute(name)) {
+    if (t.isBooleanLiteral(value) && !value.value) {
+      return;
+    }
+    if (t.isNullLiteral(value)) {
+      return;
+    }
+    const literal = t.isStringLiteral(value) ? value.value : t.isNumericLiteral(value) ? String(value.value) : "";
+    build.html.push(` ${name}="${escapeAttribute(literal)}"`);
+    return;
+  }
+  if (value === null) {
+    build.html.push(` ${name}=""`);
+    return;
+  }
+  deferred.push(() => {
+    build.statements.push(
+      expressionStatement2(
+        t.callExpression(runtime(state, "bind"), [
+          t.arrowFunctionExpression([], dynamicAttributeCall(name, value, self, state, tag))
+        ])
+      )
+    );
+  });
+}
+function canInlineAttribute(name) {
+  return !name.startsWith("prop:") && !name.startsWith("attr:") && !DOM_PROPERTIES.has(name) && !BOOLEAN_PROPERTIES.has(name);
+}
+function dynamicAttributeCall(name, value, self, state, tag) {
+  if (name.startsWith("prop:")) {
+    return t.callExpression(runtime(state, "setProperty"), [
+      t.cloneNode(self),
+      t.stringLiteral(name.slice(5)),
+      value
+    ]);
+  }
+  if (name.startsWith("attr:")) {
+    return t.callExpression(runtime(state, "setAttribute"), [
+      t.cloneNode(self),
+      t.stringLiteral(name.slice(5)),
+      value
+    ]);
+  }
+  if (name === "class" || name === "className" || name === "style") {
+    return t.callExpression(runtime(state, "applyProp"), [
+      t.cloneNode(self),
+      t.stringLiteral(name),
+      value
+    ]);
+  }
+  if (BOOLEAN_PROPERTIES.has(name)) {
+    return t.callExpression(runtime(state, "setBoolean"), [
+      t.cloneNode(self),
+      t.stringLiteral(name),
+      value
+    ]);
+  }
+  if (DOM_PROPERTIES.has(name) && !SVG_ELEMENTS.has(tag)) {
+    return t.callExpression(runtime(state, "setProperty"), [
+      t.cloneNode(self),
+      t.stringLiteral(name),
+      value
+    ]);
+  }
+  return t.callExpression(runtime(state, "setAttribute"), [
+    t.cloneNode(self),
+    t.stringLiteral(name),
+    value
+  ]);
+}
+var LIST_CALL = /* @__PURE__ */ Symbol("firsthand.list");
+function rewriteKeyedMaps(path, state) {
+  path.traverse({
+    CallExpression(call) {
+      if (!isChildPosition(call)) {
+        return;
+      }
+      const callee = call.node.callee;
+      if (!t.isMemberExpression(callee) || callee.computed || !t.isIdentifier(callee.property, { name: "map" }) || call.node.arguments.length !== 1) {
+        return;
+      }
+      const callback = call.get("arguments.0");
+      if (!callback.isArrowFunctionExpression() && !callback.isFunctionExpression()) {
+        return;
+      }
+      const params = callback.node.params;
+      const itemParam = params[0];
+      const indexParam = params[1];
+      if (!t.isIdentifier(itemParam) || indexParam !== void 0 && !t.isIdentifier(indexParam)) {
+        return;
+      }
+      const root = keyedRoot(callback);
+      if (root === null) {
+        return;
+      }
+      const keyExpression = t.cloneNode(root.key);
+      root.element.openingElement.attributes = root.element.openingElement.attributes.filter(
+        (attribute) => attribute !== root.attribute
+      );
+      const itemCell = callback.scope.generateUidIdentifier("item");
+      const indexCell = callback.scope.generateUidIdentifier("index");
+      callback.scope.crawl();
+      liveRead(callback, itemParam.name, itemCell);
+      if (indexParam !== void 0) {
+        liveRead(callback, indexParam.name, indexCell);
+      }
+      callback.node.params = [itemCell, indexCell];
+      const listCall = t.callExpression(runtime(state, "list"), [
+        t.arrowFunctionExpression([], callee.object),
+        t.arrowFunctionExpression(
+          [t.cloneNode(itemParam), indexParam ?? callback.scope.generateUidIdentifier("i")],
+          keyExpression
+        ),
+        callback.node
+      ]);
+      listCall[LIST_CALL] = true;
+      call.replaceWith(listCall);
+      call.skip();
+    }
+  });
+}
+function isChildPosition(call) {
+  let child = call;
+  let parent = child.parentPath;
+  while (!parent.isJSXExpressionContainer()) {
+    const key = child.key;
+    const throughConditional = parent.isConditionalExpression() && (key === "consequent" || key === "alternate");
+    const throughLogical = parent.isLogicalExpression() && key === "right";
+    if (!throughConditional && !throughLogical) {
+      return false;
+    }
+    child = parent;
+    parent = parent.parentPath;
+  }
+  const holder = parent.parentPath;
+  return holder.isJSXElement() || holder.isJSXFragment();
+}
+function keyedRoot(callback) {
+  const body = callback.node.body;
+  let element = null;
+  if (t.isJSXElement(body)) {
+    element = body;
+  } else if (t.isBlockStatement(body)) {
+    const last = body.body[body.body.length - 1];
+    if (t.isReturnStatement(last) && t.isJSXElement(last.argument)) {
+      element = last.argument;
+    }
+  }
+  if (element === null || !t.isJSXElement(element)) {
+    return null;
+  }
+  for (const attribute of element.openingElement.attributes) {
+    if (t.isJSXAttribute(attribute) && t.isJSXIdentifier(attribute.name, { name: "key" }) && t.isJSXExpressionContainer(attribute.value)) {
+      return { element, attribute, key: attribute.value.expression };
+    }
+  }
+  return null;
+}
+function liveRead(scopePath, name, cell) {
+  const binding = scopePath.scope.getBinding(name);
+  for (const reference of binding.referencePaths) {
+    reference.replaceWith(t.memberExpression(t.cloneNode(cell), t.identifier("value")));
+  }
+}
+function emitChildren(children, build, self, state) {
+  const entries = planChildren(children);
+  let previous = null;
+  let previousIndex = 0;
+  let index = 0;
+  const reference = () => {
+    const id = build.next();
+    build.statements.push(
+      t.variableDeclaration("const", [
+        t.variableDeclarator(id, navigate(self, previous, previousIndex, index))
+      ])
+    );
+    previous = id;
+    previousIndex = index;
+    return id;
+  };
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i];
+    if (entry.kind === "text") {
+      build.html.push(escapeText(entry.text));
+      index++;
+      continue;
+    }
+    if (entry.kind === "element") {
+      const element = entry.element;
+      if (needsReference(element)) {
+        const id = reference();
+        emitElement(element, build, id, state);
+      } else {
+        emitElement(element, build, t.identifier("_unused$"), state);
+      }
+      index++;
+      continue;
+    }
+    const isLast = i === entries.length - 1;
+    const args = [
+      t.cloneNode(self),
+      // A list part is already a thunk that owns its rows; wrapping it would
+      // rebuild the whole list on every evaluation.
+      entry.kind === "list" ? entry.expression : t.arrowFunctionExpression([], entry.expression)
+    ];
+    if (!isLast) {
+      build.html.push("<!>");
+      const id = reference();
+      args.push(t.cloneNode(id));
+    }
+    build.statements.push(expressionStatement2(t.callExpression(runtime(state, "insert"), args)));
+    index++;
+  }
+}
+function needsReference(element) {
+  for (const attribute of element.openingElement.attributes) {
+    if (t.isJSXSpreadAttribute(attribute)) {
+      return true;
+    }
+    const name = attributeName(attribute);
+    if (name === "ref" || name.startsWith("on")) {
+      return true;
+    }
+    const value = attributeValue(attribute);
+    if (value !== null && (!isStaticValue(value) || !canInlineAttribute(name))) {
+      return true;
+    }
+  }
+  for (const entry of planChildren(element.children)) {
+    if (entry.kind === "dynamic" || entry.kind === "list") {
+      return true;
+    }
+    if (entry.kind === "element" && needsReference(entry.element)) {
+      return true;
+    }
+  }
+  return false;
+}
+function navigate(self, previous, previousIndex, index) {
+  let expression;
+  let steps;
+  if (previous === null) {
+    expression = t.memberExpression(t.cloneNode(self), t.identifier("firstChild"));
+    steps = index;
+  } else {
+    expression = t.cloneNode(previous);
+    steps = index - previousIndex;
+  }
+  for (let i = 0; i < steps; i++) {
+    expression = t.memberExpression(expression, t.identifier("nextSibling"));
+  }
+  return expression;
+}
+function planChildren(children) {
+  const entries = [];
+  let pending = "";
+  const flush = () => {
+    if (pending !== "") {
+      entries.push({ kind: "text", text: pending });
+      pending = "";
+    }
+  };
+  for (const child of children) {
+    if (t.isJSXText(child)) {
+      pending += cleanText(child.value);
+      continue;
+    }
+    if (t.isJSXExpressionContainer(child)) {
+      const expression = child.expression;
+      if (t.isJSXEmptyExpression(expression)) {
+        continue;
+      }
+      if (t.isStringLiteral(expression) || t.isNumericLiteral(expression)) {
+        pending += String(expression.value);
+        continue;
+      }
+      flush();
+      const isList = expression[LIST_CALL] === true;
+      entries.push({ kind: isList ? "list" : "dynamic", expression });
+      continue;
+    }
+    flush();
+    if (t.isJSXElement(child) && !isComponentTag(child)) {
+      entries.push({ kind: "element", element: child });
+      continue;
+    }
+    entries.push({ kind: "dynamic", expression: child });
+  }
+  flush();
+  return entries;
+}
+function cleanText(value) {
+  const lines = value.split(/\r\n|\n|\r/);
+  const kept = [];
+  for (let i = 0; i < lines.length; i++) {
+    let line = lines[i];
+    if (i > 0) {
+      line = line.replace(/^[\t ]+/, "");
+    }
+    if (i < lines.length - 1) {
+      line = line.replace(/[\t ]+$/, "");
+    }
+    if (line !== "") {
+      kept.push(line);
+    }
+  }
+  return kept.join(" ");
+}
+function compileChildren(children, state) {
+  const result = [];
+  for (const entry of planChildren(children)) {
+    if (entry.kind === "text") {
+      result.push(t.stringLiteral(entry.text));
+    } else if (entry.kind === "element") {
+      result.push(entry.element);
+    } else if (entry.kind === "list") {
+      result.push(t.callExpression(runtime(state, "part"), [entry.expression]));
+    } else {
+      result.push(
+        t.callExpression(runtime(state, "part"), [
+          t.arrowFunctionExpression([], entry.expression)
+        ])
+      );
+    }
+  }
+  return result;
+}
+function expressionStatement2(expression) {
+  return t.expressionStatement(expression);
+}
+
+// packages/compiler/src/api.ts
+import { transformSync } from "@babel/core";
+import jsxSyntax from "@babel/plugin-syntax-jsx";
+import typescriptSyntax from "@babel/plugin-syntax-typescript";
+function transform(code, options = {}) {
+  const result = transformSync(code, {
+    ...options.filename === void 0 ? {} : { filename: options.filename },
+    babelrc: false,
+    configFile: false,
+    sourceMaps: false,
+    plugins: buildPlugins(options)
+  });
+  return result.code;
+}
+function buildPlugins(options) {
+  const plugins = [];
+  if (options.typescript === true) {
+    plugins.push([typescriptSyntax, { isTSX: true }]);
+  }
+  plugins.push(jsxSyntax);
+  plugins.push([firsthandPlugin, { packageName: options.packageName }]);
+  return plugins;
+}
+
+export {
+  stableId,
+  firsthandPlugin,
+  transform
+};

package/dist/html.d.ts

@@ -0,0 +1,19 @@
+/** Static tables and escaping used while building a template's HTML. */
+/** Elements that must not be closed. */
+export declare const VOID_ELEMENTS: Set<string>;
+/** Attributes written as boolean DOM properties rather than attributes. */
+export declare const BOOLEAN_PROPERTIES: Set<string>;
+/**
+ * Attributes whose dynamic form must be a DOM property.
+ *
+ * `value` is the canonical example: setting the attribute does not change what
+ * the user sees once the field has been edited.
+ */
+export declare const DOM_PROPERTIES: Set<string>;
+/** SVG elements, so the compiler can emit namespaced templates. */
+export declare const SVG_ELEMENTS: Set<string>;
+export declare function escapeText(value: string): string;
+export declare function escapeAttribute(value: string): string;
+/** `onPointerDown` -> `pointerdown`. */
+export declare function eventName(attribute: string): string;
+//# sourceMappingURL=html.d.ts.map

package/dist/html.d.ts.map

@@ -0,0 +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"}

package/dist/ids.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A short, stable identifier for a module (ADR-0004).
+ *
+ * Derived from the package name and the module path relative to the project, so
+ * it survives minification — unlike `Function.name` — and stays the same across
+ * builds, unlike a runtime counter.
+ */
+export declare function stableId(packageName: string, filename: string): string;
+//# sourceMappingURL=ids.d.ts.map

package/dist/ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../src/ids.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAMtE"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `@firsthandjs/compiler` — the build-time half of Firsthand.
+ *
+ * Nothing here ships to the browser. The transform emits calls against the
+ * published protocol in `@firsthandjs/dom/internal`, so compiled output is code a
+ * developer could have written by hand (ARCHITECTURE section 1.1).
+ */
+export { default as firsthandPlugin } from './transform.js';
+export type { FirsthandPluginOptions } from './transform.js';
+export { transform } from './api.js';
+export { stableId } from './ids.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC5D,YAAY,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+import {
+  firsthandPlugin,
+  stableId,
+  transform
+} from "./chunk-HHKCDDN2.js";
+export {
+  firsthandPlugin,
+  stableId,
+  transform
+};

package/dist/transform.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The Firsthand TSX transform (ADR-0009).
+ *
+ * Static markup becomes one `<template>` per shape, created once and cloned per
+ * instance. Every dynamic expression becomes a thunk handed to a specialised
+ * DOM part, and the runtime decides by observation whether an effect needs to
+ * be retained. The compiler never tries to decide statically whether an
+ * expression is reactive — that question is undecidable in general, and being
+ * wrong about it means silently missing updates.
+ *
+ * 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';
+interface FirsthandState {
+    imports: Map<string, t.Identifier>;
+    templates: t.VariableDeclarator[];
+    counter: number;
+    moduleId: string;
+}
+declare module '@babel/core' {
+    interface PluginPass {
+        firsthand: FirsthandState;
+    }
+}
+export interface FirsthandPluginOptions {
+    /** Package name used when hashing stable component ids (ADR-0004). */
+    packageName?: string;
+}
+export default function firsthandPlugin(_api: unknown, options?: FirsthandPluginOptions): PluginObject;
+export {};
+//# sourceMappingURL=transform.d.ts.map

package/dist/transform.d.ts.map

@@ -0,0 +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;AAelC,UAAU,cAAc;IACtB,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;CAClB;AAED,OAAO,QAAQ,aAAa,CAAC;IAC3B,UAAU,UAAU;QAClB,SAAS,EAAE,cAAc,CAAC;KAC3B;CACF;AAUD,MAAM,WAAW,sBAAsB;IACrC,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,CAAC,OAAO,UAAU,eAAe,CACrC,IAAI,EAAE,OAAO,EACb,OAAO,GAAE,sBAA2B,GACnC,YAAY,CAgDd"}

package/dist/vite.d.ts

@@ -0,0 +1,18 @@
+import type { FirsthandPluginOptions } from './transform.js';
+/** Minimal shape of the Vite plugin contract, so the package needs no Vite dependency. */
+export interface VitePluginLike {
+    name: string;
+    enforce: 'pre';
+    transform(code: string, id: string): {
+        code: string;
+        map: null;
+    } | null;
+}
+/**
+ * Vite/Rollup plugin.
+ *
+ * Runs before the bundler's TypeScript step: Firsthand parses TS syntax but leaves
+ * the annotations in place, so exactly one tool strips them.
+ */
+export declare function firsthand(options?: FirsthandPluginOptions): VitePluginLike;
+//# sourceMappingURL=vite.d.ts.map

package/dist/vite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite.d.ts","sourceRoot":"","sources":["../src/vite.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAE7D,0FAA0F;AAC1F,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,KAAK,CAAC;IACf,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;CACzE;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,OAAO,GAAE,sBAA2B,GAAG,cAAc,CAmB9E"}

package/dist/vite.js

@@ -0,0 +1,28 @@
+import {
+  transform
+} from "./chunk-HHKCDDN2.js";
+
+// packages/compiler/src/vite.ts
+function firsthand(options = {}) {
+  return {
+    name: "firsthand",
+    enforce: "pre",
+    transform(code, id) {
+      const file = id.split("?")[0];
+      if (!file.endsWith(".tsx") && !file.endsWith(".jsx")) {
+        return null;
+      }
+      return {
+        code: transform(code, {
+          filename: file,
+          typescript: file.endsWith(".tsx"),
+          ...options
+        }),
+        map: null
+      };
+    }
+  };
+}
+export {
+  firsthand
+};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@firsthandjs/compiler",
+  "version": "0.1.0",
+  "description": "Build-time TSX transform for Firsthand: static markup into templates, dynamic expressions into DOM parts.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "default": "./dist/vite.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@babel/core": "^8.0.6",
+    "@babel/plugin-syntax-jsx": "^8.0.0",
+    "@babel/types": "^8.0.6",
+    "@babel/plugin-syntax-typescript": "^8.0.0"
+  },
+  "engines": {
+    "node": ">=20.11.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/firsthandjs/firsthand.git",
+    "directory": "packages/compiler"
+  },
+  "bugs": {
+    "url": "https://github.com/firsthandjs/firsthand/issues"
+  },
+  "homepage": "https://github.com/firsthandjs/firsthand#readme",
+  "keywords": [
+    "reactive",
+    "signals",
+    "fine-grained",
+    "web-components",
+    "ui",
+    "framework",
+    "jsx",
+    "no-virtual-dom"
+  ]
+}