@jxsuite/compiler 1.0.0 → 1.2.0

package/src/site/site-build.ts

@@ -9,7 +9,6 @@
  */
 
 import {
-  copyFileSync,
   cpSync,
   existsSync,
   mkdirSync,
@@ -19,8 +18,16 @@ import {
   statSync,
   writeFileSync,
 } from "node:fs";
-import { basename, dirname, join, resolve } from "node:path";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { isMappedArray, isRef } from "@jxsuite/schema/guards";
+import { isNpmSpecifier, sidecarAssetPath } from "@jxsuite/schema/asset-paths";
+import {
+  CLIENT_EXTERNALS,
+  bundleEntry,
+  bundleWorkerSource,
+  isBundleableSrc,
+  resolveSidecarEntry,
+} from "./bundler.ts";
 import { loadProjectConfig } from "./site-loader.ts";
 import { discoverPages, expandDynamicRoutes, readPageDocument } from "./pages-discovery.ts";
 import { buildProjectExtensionRegistry } from "./format-host.ts";
@@ -40,10 +47,12 @@ import {
   buildInitialScope,
   collectServerEntries,
   collectStyles,
+  colorSchemePrePaintScript,
   evaluateStaticTemplate,
   isComponentFullyStatic,
   isTemplateString,
   preRenderComponentHtml,
+  pureSchemeOf,
   renderStaticNode,
   resolveRefValue,
   resolveStaticValue,
@@ -106,6 +115,43 @@ export async function buildSite(
   const publicDir = resolve(projectRoot, "public");
   const trailingSlash = projectConfig.build.trailingSlash ?? "always";
 
+  // Client sidecar bundles: bundleable Function-def `$src` specifiers (and lowered-def `$bundle`
+  // Hints) are rewritten to their /assets/ URL during compilation, registered here, and bundled
+  // In step 6d (spec.md §12). Keyed by asset path so duplicate specifiers bundle once.
+  const sidecarBundles = new Map<string, { entryPath: string; specifier: string }>();
+  const rewriteSidecarSrc = (specifier: string, docDir: string | null): string => {
+    if (!isBundleableSrc(specifier)) {
+      return specifier;
+    }
+    try {
+      const entryPath = resolveSidecarEntry(specifier, docDir ?? projectRoot, projectRoot);
+      // A declared-but-absent relative sidecar keeps its verbatim import (the historical
+      // Behavior) with a warning — the doc may only ever run interpreted. Unresolvable npm
+      // Specifiers stay hard errors: a missing dependency should fail the build.
+      if (!isNpmSpecifier(specifier) && !existsSync(entryPath)) {
+        console.warn(`Sidecar "${specifier}" not found at ${entryPath} — emitting unbundled`);
+        return specifier;
+      }
+      // Relative specifiers key on their project-relative resolved path so `./x.js` declared in
+      // Two directories cannot collide on one slug; npm specifiers are location-independent.
+      const assetKey = isNpmSpecifier(specifier)
+        ? specifier
+        : `./${relative(projectRoot, entryPath)}`;
+      const assetPath = sidecarAssetPath(assetKey);
+      const existing = sidecarBundles.get(assetPath);
+      if (existing && existing.entryPath !== entryPath) {
+        throw new Error(
+          `"${specifier}" and "${existing.specifier}" both bundle to ${assetPath} — rename one`,
+        );
+      }
+      sidecarBundles.set(assetPath, { entryPath, specifier });
+      return assetPath;
+    } catch (error) {
+      errors.push(`Sidecar "${specifier}": ${(error as Error).message}`);
+      return specifier;
+    }
+  };
+
   // ── 1b. Build the extension registry from project.json#/extensions ─────
   const registry = await buildProjectExtensionRegistry(projectRoot, projectConfig);
   const formatRegistry = registry.formats;
@@ -194,6 +240,7 @@ export async function buildSite(
         const result = await compileElement(componentPath, {
           ...(projectConfig.$media ? { $media: projectConfig.$media } : {}),
           formats: formatRegistry,
+          rewriteSrc: rewriteSidecarSrc,
         });
         for (const f of result.files) {
           // Reduce the emitted path (an absolute source path with .json swapped to .js) to a bare
@@ -277,6 +324,7 @@ export async function buildSite(
         imageMetaCache,
         formatRegistry,
         registry,
+        rewriteSidecarSrc,
       );
 
       // Determine which component tags are fully static (for script omission)
@@ -367,7 +415,9 @@ export async function buildSite(
 
   // ── 6b. Save image cache and copy variants to dist ──────────────────────
   if (imageCache && projectConfig.images.optimize) {
-    saveCache(projectRoot, imageCache);
+    // Prune only on fully successful builds — a route that failed to compile never
+    // Touched its images, and pruning would evict their still-valid entries.
+    saveCache(projectRoot, imageCache, { prune: errors.length === 0 });
     const cacheOptimizedDir = resolve(getImageCacheDir(projectRoot), "_optimized");
     if (existsSync(cacheOptimizedDir)) {
       const distOptimizedDir = resolve(outDir, "images/_optimized");
@@ -410,10 +460,23 @@ export async function buildSite(
       : compileSiteServer([...deduped.values()], { adapter, connectors, mounts });
 
     if (workerSource) {
+      // Bundle the worker self-contained for the adapter's runtime (compiler.md §12): mount
+      // Modules, connectors, hono, and user server functions are inlined, so dist deploys
+      // Without node_modules or deploy-time bundling.
       const workerName = adapter === "cloudflare-pages" ? "_worker.js" : "worker.js";
-      writeFileSync(resolve(outDir, workerName), workerSource, "utf8");
-      fileCount += 1;
-      log(`  Generated dist/${workerName} (${deduped.size} server function(s))`);
+      try {
+        await bundleWorkerSource(workerSource, {
+          adapter,
+          outfile: resolve(outDir, workerName),
+          projectRoot,
+        });
+        fileCount += 1;
+        log(`  Generated dist/${workerName} (bundled, ${deduped.size} server function(s))`);
+      } catch (error) {
+        const msg = `Error bundling dist/${workerName}: ${(error as Error).message}`;
+        errors.push(msg);
+        console.error(msg);
+      }
 
       if (adapter === "cloudflare-pages") {
         // Only invoke the worker for server routes; everything else stays static.
@@ -424,24 +487,76 @@ export async function buildSite(
         );
         fileCount += 1;
       }
+    }
+  }
 
-      // Copy server source files into dist/components/ so worker imports resolve
-      const distComponentsDir = resolve(outDir, "components");
-      mkdirSync(distComponentsDir, { recursive: true });
-      for (const { src } of deduped.values()) {
-        const srcFile = resolve(projectRoot, src.replace(/^\.\//, ""));
-        const destFile = resolve(distComponentsDir, src.replace(/^\.\/components\//, ""));
-        if (existsSync(srcFile)) {
-          copyFileSync(srcFile, destFile);
+  // ── 6d. Bundle client sidecar modules (spec.md §12) ─────────────────────
+  if (sidecarBundles.size > 0) {
+    log(`Bundling ${sidecarBundles.size} client sidecar module(s)...`);
+    for (const [assetPath, bundle] of sidecarBundles) {
+      try {
+        const outfile = resolve(outDir, assetPath.replace(/^\//, ""));
+        mkdirSync(dirname(outfile), { recursive: true });
+        await bundleEntry(
+          { entryPath: bundle.entryPath, outfile },
+          { external: CLIENT_EXTERNALS, target: "browser" },
+        );
+        fileCount += 1;
+        log(`  ${bundle.specifier} → ${assetPath}`);
+      } catch (error) {
+        const msg = `Error bundling sidecar "${bundle.specifier}": ${(error as Error).message}`;
+        errors.push(msg);
+        console.error(msg);
+      }
+    }
+  }
+
+  // ── 6e. Extension-emitted assets (extensions.md §8.4) ───────────────────
+  // Section-owner classes with an `emit` capability contribute derived build artifacts
+  // (search indexes, feeds, …). The host writes the returned files so extensions stay pure;
+  // Paths are outDir-relative and guarded against traversal. Note the `public/` copy (7c)
+  // Runs later and can shadow emitted files — same semantics as sitemap.xml.
+  for (const entry of registry.emitters()) {
+    const sectionKey = entry.project?.key;
+    const sectionValue = sectionKey
+      ? (projectConfig as unknown as Record<string, unknown>)[sectionKey]
+      : undefined;
+    if (
+      sectionKey &&
+      (sectionValue == null ||
+        (typeof sectionValue === "object" && Object.keys(sectionValue).length === 0))
+    ) {
+      continue; // Section owner with nothing declared — same gating as sections/mounts
+    }
+    try {
+      const emitted = (await entry.call("emit", sectionValue ?? null, {
+        projectConfig,
+        root: projectRoot,
+        routes,
+        sections,
+      })) as { path: string; content: string | Uint8Array }[] | null;
+      for (const file of emitted ?? []) {
+        const target = resolve(outDir, file.path.replace(/^\//, ""));
+        if (!target.startsWith(outDir + sep)) {
+          throw new Error(`emit path escapes outDir: ${file.path}`);
         }
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, file.content);
+        fileCount += 1;
+        log(`  ${entry.name} emitted ${file.path}`);
       }
+    } catch (error) {
+      const msg = `Error in ${entry.name}.emit: ${(error as Error).message}`;
+      errors.push(msg);
+      console.error(msg);
     }
   }
 
   // ── 7. Generate redirects ───────────────────────────────────────────────
   if (projectConfig.redirects && Object.keys(projectConfig.redirects).length > 0) {
     log("Generating redirects...");
-    const redirectFiles = generateRedirects(projectConfig.redirects, outDir);
+    const compiledUrls = new Set(routes.map((r) => r.urlPattern));
+    const redirectFiles = generateRedirects(projectConfig.redirects, outDir, compiledUrls);
     fileCount += redirectFiles;
   }
 
@@ -514,6 +629,7 @@ async function compilePage(
   imageMetaCache: ImageMetaCache | null = null,
   formatRegistry?: FormatRegistry,
   registry?: ExtensionRegistry,
+  rewriteSidecarSrc?: (specifier: string, docDir: string | null) => string,
 ) {
   // Load the raw page document (.json natively, other formats via the registry)
   const pageDoc = await readPageDocument(route.sourcePath as string, formatRegistry);
@@ -538,6 +654,13 @@ async function compilePage(
     config: projectConfig,
     sections,
     ...(registry === undefined ? {} : { registry }),
+    ...(rewriteSidecarSrc === undefined
+      ? {}
+      : {
+          registerBundle: (specifier: string) => {
+            rewriteSidecarSrc(specifier, null);
+          },
+        }),
   });
 
   // Build scope from resolved state so template strings in title/$head can be evaluated
@@ -606,6 +729,13 @@ async function compilePage(
     layoutDoc.$media = { ...projectConfig.$media, ...layoutDoc.$media };
   }
 
+  // Declaring a pure color-scheme query opts the page into the forced-scheme contract: restore
+  // The visitor's persisted scheme before first paint (spec §9.5). Injected after the
+  // Charset/viewport defaults and ahead of every preserved <style> block.
+  if (Object.values(layoutDoc.$media ?? {}).some((q) => pureSchemeOf(String(q)) !== null)) {
+    mergedHead.splice(2, 0, { tagName: "script", textContent: colorSchemePrePaintScript() });
+  }
+
   // Transform <img> nodes for responsive image optimization
   if (projectConfig.images?.optimize && (imageCache || imageMetaCache)) {
     await transformImageNodes(
@@ -620,7 +750,14 @@ async function compilePage(
   // Compile the document using the existing compiler
   const result = await compile(layoutDoc, {
     lang: projectConfig.defaults?.lang ?? "en",
+    prePaintScheme: false, // Injected via the merged <head> above, not the target template
     projectStyle: projectConfig.style ?? null,
+    ...(rewriteSidecarSrc === undefined
+      ? {}
+      : {
+          rewriteSrc: (specifier: string) =>
+            rewriteSidecarSrc(specifier, dirname(route.sourcePath as string)),
+        }),
     title,
   });
 
@@ -1315,14 +1452,18 @@ function routeToOutputPath(urlPattern: string, outDir: string, trailingSlash: st
  *
  * @param {Record<string, string | { destination: string; status?: number }>} redirects
  * @param {string} outDir
+ * @param {Set<string>} [compiledUrls] - URL patterns of compiled routes, for conflict warnings
  * @returns {number} Number of files written
  */
 function generateRedirects(
   redirects: Record<string, string | { destination: string; status?: number }>,
   outDir: string,
+  compiledUrls = new Set<string>(),
 ) {
   let count = 0;
   const redirectLines: string[] = [];
+  const normalizeUrl = (u: string) => (u.length > 1 && u.endsWith("/") ? u.slice(0, -1) : u);
+  const compiled = new Set([...compiledUrls].map((u) => normalizeUrl(u)));
 
   for (const [source, target] of Object.entries(redirects)) {
     const dest = typeof target === "object" ? target.destination : target;
@@ -1334,6 +1475,13 @@ function generateRedirects(
       continue;
     }
 
+    if (compiled.has(normalizeUrl(source))) {
+      console.warn(
+        `Redirect "${source}" overwrites a compiled page at the same route — ` +
+          `remove the redirect or the page.`,
+      );
+    }
+
     // Static redirect — emit an HTML file with meta refresh
     const htmlPath = routeToOutputPath(source, outDir, "always");
     const html = `<!DOCTYPE html>

package/src/targets/compile-client.ts

@@ -16,21 +16,27 @@ import {
   DEFAULT_LIT_HTML_SRC,
   DEFAULT_REACTIVITY_SRC,
   buildAttrs,
+  colorSchemePrePaintScript,
   compileExpression,
+  compileStatements,
   compileStyles,
   createCompileContext,
+  emitFormulaFn,
   escapeHtml,
   isMutating,
   isRefObject,
   isSchemaOnly,
   isTemplateString,
+  pureSchemeOf,
   resolveStaticValue,
 } from "../shared.ts";
 import {
+  hasStructuredBody,
   isExpandedSignal,
   isExpressionDef,
   isFunctionDef,
   isMappedArray,
+  isNamedFormulaDef,
   isPrototypeDef,
   paramNames,
 } from "@jxsuite/schema/guards";
@@ -72,6 +78,7 @@ export function compileClient(
     litHtmlSrc?: string;
     modulePath?: string;
     projectStyle?: JxStyle | null;
+    prePaintScheme?: boolean;
     [key: string]: unknown;
   },
 ) {
@@ -124,7 +131,11 @@ export function compileClient(
         eventParam: "e",
         statePrefix: "state",
       });
-      if (isMutating(node.operator)) {
+      if (isNamedFormulaDef(def)) {
+        // Named formula → a scope callable mapping positional args onto declared parameters.
+        // Call sites stay positional, matching the interpreter.
+        initBlocks.push(`state[${JSON.stringify(key)}] = ${emitFormulaFn(def, compiled)};`);
+      } else if (isMutating(node.operator)) {
         onEntries.push([key, { args: ["state", "e"], body: compiled }]);
       } else {
         computedEntries.push([key, `() => ${compiled}`]);
@@ -135,7 +146,18 @@ export function compileClient(
     // $prototype: "Function"
     if (isFunctionDef(def)) {
       const args = def.parameters ? paramNames(def.parameters) : def.arguments;
-      if (def.$src) {
+      if (hasStructuredBody(def)) {
+        // Structured body (spec §20) → an event handler compiled from statements.
+        // With parameters, a positional callable like a named formula.
+        const compiled = compileStatements(def.body, { eventParam: "e", statePrefix: "state" });
+        if (def.parameters && def.parameters.length > 0) {
+          initBlocks.push(
+            `state[${JSON.stringify(key)}] = ${emitFormulaFn(def, `(() => {\n${compiled}\n})()`)};`,
+          );
+        } else {
+          onEntries.push([key, { args: ["state", "e"], body: compiled }]);
+        }
+      } else if (def.$src) {
         if (!srcImportMap.has(def.$src)) {
           srcImportMap.set(def.$src, new Set());
         }
@@ -143,12 +165,12 @@ export function compileClient(
 
         // $src functions always produce computed entries (they return values)
         computedEntries.push([key, `() => { return ${key}(state); }`]);
-      } else if (def.body && def.body.includes("return")) {
+      } else if (typeof def.body === "string" && def.body.includes("return")) {
         // Body contains return → computed
         computedEntries.push([key, `() => { ${def.body} }`]);
       } else {
         // No return → event handler
-        onEntries.push([key, { args: args ?? ["state"], body: def.body }]);
+        onEntries.push([key, { args: args ?? ["state"], body: def.body as string | undefined }]);
       }
       continue;
     }
@@ -219,6 +241,7 @@ export function compileClient(
     srcImportMap,
     counter,
     reactivitySrc,
+    opts.rewriteSrc as ((specifier: string) => string) | undefined,
   );
 
   // Build importmap entries — always include lit-html since compiled custom elements need it
@@ -227,13 +250,20 @@ export function compileClient(
     `      "lit-html": "${litHtmlSrc}"`,
   ];
 
+  // Forced-scheme contract (spec §9.5): restore the persisted scheme before any styles apply
+  const prePaint =
+    opts.prePaintScheme !== false &&
+    Object.values(raw.$media ?? {}).some((q) => pureSchemeOf(String(q)) !== null)
+      ? `<script>${colorSchemePrePaintScript()}</script>\n  `
+      : "";
+
   const html = `<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>${escapeHtml(title)}</title>
-  <script type="importmap">
+  ${prePaint}<script type="importmap">
   {
     "imports": {
 ${importmapEntries.join(",\n")}
@@ -335,13 +365,22 @@ function buildClientNode(
       const key = refToBindingKey(val.$ref);
       bindAttrs.push(`@${eventName}="${key}"`);
       needsBind = true;
+    } else if (hasStructuredBody(val)) {
+      const key = `_h${counter.h}`;
+      counter.h += 1;
+      bindAttrs.push(`@${eventName}="${key}"`);
+      handlers.set(key, {
+        args: ["state", "e"],
+        body: compileStatements(val.body, { eventParam: "e", statePrefix: "state" }),
+      });
+      needsBind = true;
     } else if (isFunctionDef(val)) {
       const key = `_h${counter.h}`;
       counter.h += 1;
       bindAttrs.push(`@${eventName}="${key}"`);
       handlers.set(key, {
         args: val.parameters ? paramNames(val.parameters) : (val.arguments ?? ["state", "event"]),
-        body: val.body,
+        body: val.body as string | undefined,
       });
       needsBind = true;
     } else if (isExpressionDef(val)) {
@@ -594,6 +633,9 @@ function emitLitMapTemplate(def: JxMutableNode | undefined) {
     if (isRefObject(val)) {
       const key = refToBindingKey((val as JxMutableNode).$ref as string);
       attrs += ` @${eventName}=\${(e) => { state.$map = { item, index }; on.${key}(e); }}`;
+    } else if (hasStructuredBody(val)) {
+      const compiled = compileStatements(val.body, { eventParam: "e", statePrefix: "state" });
+      attrs += ` @${eventName}=\${(e) => { state.$map = { item, index }; ${compiled} }}`;
     } else if (val && typeof val === "object" && (val as JxMutableNode).$prototype === "Function") {
       const body = mapRefsToLit((val as JxMutableNode).body as string);
       attrs += ` @${eventName}=\${(e) => { ${body} }}`;
@@ -726,6 +768,7 @@ function emitClientModule(
     needsLit: boolean;
   },
   _reactivitySrc: string,
+  rewriteSrc?: (specifier: string) => string,
 ) {
   const lines: string[] = [];
   const { needsLit } = counter;
@@ -745,9 +788,11 @@ function emitClientModule(
     lines.push("import { html, render } from 'lit-html';");
   }
 
-  // $src imports
+  // $src imports — bundleable specifiers (npm:…, ./relative) are rewritten to their /assets/
+  // Bundle URL; the site build bundles them after all documents compile (spec.md §12).
   for (const [src, names] of srcImportMap) {
-    lines.push(`import { ${[...names].join(", ")} } from '${src}';`);
+    const importPath = rewriteSrc ? rewriteSrc(src) : src;
+    lines.push(`import { ${[...names].join(", ")} } from '${importPath}';`);
   }
 
   // State — reactive state

package/src/targets/compile-element.ts

@@ -9,15 +9,19 @@ import { RESERVED_KEYS, camelToKebab } from "@jxsuite/runtime";
 import {
   collectStyles,
   compileExpression,
+  compileStatements,
+  emitFormulaFn,
   escapeHtml,
   isMutating,
   isSchemaOnly,
   tagNameToClassName,
 } from "../shared.ts";
 import {
+  hasStructuredBody,
   isExpressionDef,
   isFunctionDef,
   isMappedArray,
+  isNamedFormulaDef,
   isRef,
   paramNames,
 } from "@jxsuite/schema/guards";
@@ -37,6 +41,12 @@ import type {
 export interface CompileElementOptions {
   /** Resolve an `$elements` ref path to its emitted JS module path. */
   resolveElementPath?: (refPath: string, currentDir: string | null) => string;
+  /**
+   * Rewrite a Function-def `$src` specifier to its served URL (bundleable specifiers → their
+   * `/assets/` bundle path). Receives the directory of the declaring document for relative
+   * specifiers. Identity when omitted.
+   */
+  rewriteSrc?: (specifier: string, docDir: string | null) => string;
   $media?: Record<string, string>;
   formats?: FormatRegistry;
   basePath?: string | null;
@@ -131,7 +141,13 @@ export async function compileElement(
     if (optsMedia) {
       doc.$media = { ...optsMedia, ...doc.$media };
     }
-    const jsContent = emitElementModule(doc, className, elementImports);
+    const { rewriteSrc } = opts;
+    const jsContent = emitElementModule(
+      doc,
+      className,
+      elementImports,
+      rewriteSrc ? (spec: string) => rewriteSrc(spec, currentDir) : undefined,
+    );
     const outputPath = filePath ? filePath.replace(/\.json$/, ".js") : `${tagName}.js`;
     files.push({ content: jsContent, path: outputPath, tagName });
   }
@@ -240,7 +256,12 @@ function extractInitialValue(def: JxMutableNode) {
  * @param {string[]} elementImports
  * @returns {string}
  */
-export function emitElementModule(doc: JxDocument, className: string, elementImports: string[]) {
+export function emitElementModule(
+  doc: JxDocument,
+  className: string,
+  elementImports: string[],
+  rewriteSrc?: (specifier: string) => string,
+) {
   const lines: string[] = ["// Generated by @jxsuite/compiler — do not edit manually"];
 
   if (doc.$id) {
@@ -265,7 +286,10 @@ export function emitElementModule(doc: JxDocument, className: string, elementImp
     }
   }
   for (const [srcPath, names] of srcImportMap) {
-    lines.push(`import { ${names.join(", ")} } from '${srcPath}';`);
+    // Bundleable specifiers (npm:…, ./relative) are rewritten to their /assets/ bundle URL;
+    // The site build bundles them after all documents compile (spec.md §12).
+    const importPath = rewriteSrc ? rewriteSrc(srcPath) : srcPath;
+    lines.push(`import { ${names.join(", ")} } from '${importPath}';`);
   }
 
   lines.push(
@@ -284,11 +308,14 @@ export function emitElementModule(doc: JxDocument, className: string, elementImp
   const computedEntries: [string, JxExpressionDef | JxFunctionDef][] = [];
   const functionEntries: [string, JxExpressionDef | JxFunctionDef][] = [];
 
+  const formulaEntries: [string, JxExpressionDef][] = [];
   for (const [key, def] of Object.entries(defs)) {
     const d = def as JxMutableNode;
     if (isExpressionDef(d)) {
       const node = d.$expression as ExpressionNode;
-      if (isMutating(node.operator)) {
+      if (isNamedFormulaDef(d)) {
+        formulaEntries.push([key, d]);
+      } else if (isMutating(node.operator)) {
         functionEntries.push([key, d]);
       } else {
         computedEntries.push([key, d]);
@@ -324,6 +351,16 @@ export function emitElementModule(doc: JxDocument, className: string, elementImp
         statePrefix: "s",
       });
       lines.push(`    this.state.${key} = (s, e) => { ${compiled}; };`);
+    } else if (hasStructuredBody(def)) {
+      // Structured body (spec §20) — statements compiled against this.state; dispatch target is
+      // The component instance itself (WHATWG dispatchEvent on the custom element).
+      const compiled = compileStatements(def.body, {
+        dispatchTarget: "this",
+        eventParam: "e",
+        indent: "      ",
+        statePrefix: "this.state",
+      });
+      lines.push(`    this.state.${key} = (s, e) => {`, compiled, "    };");
     } else {
       const args = def.parameters ? paramNames(def.parameters) : (def.arguments ?? ["state"]);
       const paramList = args.join(", ");
@@ -333,13 +370,23 @@ export function emitElementModule(doc: JxDocument, className: string, elementImp
       } else {
         lines.push(
           `    this.state.${key} = (${paramList}) => {`,
-          `      ${def.body ?? ""}`,
+          `      ${typeof def.body === "string" ? def.body : ""}`,
           "    };",
         );
       }
     }
   }
 
+  // Emit named formulas — scope callables mapping positional args onto declared parameters
+  for (const [key, def] of formulaEntries) {
+    lines.push("");
+    const compiled = compileExpression(def.$expression as ExpressionNode, {
+      eventParam: "e",
+      statePrefix: "this.state",
+    });
+    lines.push(`    this.state.${key} = ${emitFormulaFn(def, compiled)};`);
+  }
+
   // Emit computed signals — $src or inline body
   for (const [key, def] of computedEntries) {
     lines.push("");
@@ -353,7 +400,10 @@ export function emitElementModule(doc: JxDocument, className: string, elementImp
       lines.push(`    this.state.${key} = computed(() => ${key}(this.state));`);
     } else {
       lines.push(`    this.state.${key} = computed(() => {`);
-      const body = (def.body ?? "").replaceAll("state.", "this.state.");
+      const body = (typeof def.body === "string" ? def.body : "").replaceAll(
+        "state.",
+        "this.state.",
+      );
       lines.push(`      ${body}`, "    });");
     }
   }
@@ -456,11 +506,16 @@ export function emitElementModule(doc: JxDocument, className: string, elementImp
     );
   }
   lines.push(
+    // Lifecycle: onMount (spec §16.4) — same microtask contract as the runtime
+    "    if (typeof this.state.onMount === 'function') {",
+    "      queueMicrotask(() => this.state.onMount(this.state));",
+    "    }",
     "  }",
     "",
     // DisconnectedCallback
     "  disconnectedCallback() {",
     "    if (this.#dispose) { this.#dispose(); this.#dispose = null; }",
+    "    if (typeof this.state.onUnmount === 'function') { this.state.onUnmount(this.state); }",
     "  }",
     "}",
     "",
@@ -765,7 +820,14 @@ function toLitTextContent(value: unknown) {
  * @returns {string}
  */
 function inlineHandlerBody(def: JxFunctionDef) {
-  const body = def.body ?? "";
+  if (hasStructuredBody(def)) {
+    return compileStatements(def.body, {
+      dispatchTarget: "e.currentTarget",
+      eventParam: "e",
+      statePrefix: "s",
+    });
+  }
+  const body = typeof def.body === "string" ? def.body : "";
   return body.replaceAll(/(?<!this\.)state\./g, "s.").replaceAll(/(?<!this\.)state(?!\.)/g, "s");
 }