azoxjs 1.2.0 → 1.3.0

package/README.md

@@ -11,7 +11,7 @@ third-party CLI dependencies, no borrowed syntax from React, Vue, or
 Next.js. It compiles `.azox` components directly into fine-grained,
 signal-driven DOM updates.
 
-> Status: stable (v1.2.0). The template syntax, the reactivity exports
+> Status: stable (v1.3.0). The template syntax, the reactivity exports
 > and the shape of the build output will not change without a 2.0. What
 > Azox does **not** do is listed in
 > [Limitations](https://azox.dev/docs/limitations) — those are stopping

package/core/compiler/compileToJs.js

@@ -7,9 +7,27 @@
 // the browser, which is what makes the playground possible. Anything
 // that needs to know about paths on disk belongs in build.js.
 
+// Control-flow markers carry a label. An empty comment serialises to
+// <!---->, so two adjacent blocks produce four identical nodes and a
+// walker adopting server markup cannot tell a start from an end, nor
+// one block from the next. The server emits the same pair.
+//
+// See docs/hydration.md.
+export const BLOCK_START = '[';
+export const BLOCK_END = ']';
+
 let uid = 0;
 const nextId = () => `_el${uid++}`;
 
+// Node variable -> the binding holding what the cursor handed back for
+// it, or absent when the node was created outright. Whoever appends a
+// node consults this: an adopted node is already in place, and
+// appending an existing child detaches and re-attaches it, which blurs
+// it and loses the reader's focus. Set per compile, and cleared with
+// the variable counter — a page compiles twice when it adopts, and the
+// second pass reuses the same names.
+let adoptedOf = new Map();
+
 // Tags that open an SVG document fragment. Everything inside one is in
 // the SVG namespace too, which is threaded down as `inSvg` — <circle>
 // and <path> carry no hint of their own.
@@ -86,13 +104,42 @@ export function compileToModule(
   { runtimeSpecifier, rewriteImports, inlineModules, routeParams }
 ) {
   uid = 0;
+  adoptedOf = new Map();
   // Values the build resolved: their bindings need no effect, which is
   // what lets a page whose only "dynamic" text is a version number ship
   // as a static page.
   constantValues = inlineModules ?? {};
   constantNames = new Set(Object.keys(constantValues));
-  const statements = [];
-  const rootVar = emitNode(ast.markup, statements, 'root');
+  let statements = [];
+  let rootVar = emitNode(ast.markup, statements, 'root');
+
+  // Adoption reuses the nodes the server sent instead of rebuilding
+  // them, which is what preserves focus, a caret position and an open
+  // <details> across hydration.
+  //
+  // Control flow is excluded for now. An <if> or <each> creates its
+  // marker pair and its rows fresh on every run, so a page mixing
+  // adopted markup with a rebuilt block would bind effects across two
+  // generations of nodes — worse than the wholesale rebuild it
+  // replaces. Pages carrying a block keep that rebuild until the
+  // walker can adopt between the markers too; see docs/hydration.md.
+  const hasControlFlow = statements.some((line) => line.includes('createComment('));
+  // A static page ships no hydration block, so no cursor can ever reach
+  // its render(): adopting there would import the walker for nothing.
+  // Decided from this pass, whose effect and listener lines are the same
+  // ones the second pass emits.
+  const staticFirstPass = !statements.some(
+    (line) => line.startsWith('effect(') || line.includes('.addEventListener(')
+  );
+  const adopts = !hasControlFlow && !staticFirstPass;
+  if (adopts) {
+    // Emitted again from a clean slate: the cursor changes almost every
+    // creation site, and reusing the first pass's variable counter
+    // would leave gaps in the names.
+    uid = 0;
+    statements = [];
+    rootVar = emitNode(ast.markup, statements, 'root', false, '_cursor');
+  }
 
   let script = dropComponentImports(ast.script);
   script = resolveRouteDeclarations(script, routeParams);
@@ -125,6 +172,10 @@ export function compileToModule(
   // module needs dispose as well as effect.
   const needsDispose = statements.some((line) => line.includes('dispose('));
   const needsUntracked = statements.some((line) => line.includes('untracked('));
+  const needsAdopt = statements.some((line) => line.includes('adopt('));
+  // The root is adopted from the mount the same way children are, so it
+  // must not be re-appended either.
+  const rootTaken = adoptedOf.get(rootVar);
 
   const { imports, body } = mergeImports(
     script,
@@ -132,7 +183,8 @@ export function compileToModule(
     runtimeSpecifier,
     needsDispose,
     inlineModules,
-    needsUntracked
+    needsUntracked,
+    needsAdopt
   );
 
   // Narrowed to what the module actually reads, so importing
@@ -143,12 +195,12 @@ export function compileToModule(
 ${imports}
 ${inlined}${body}
 
-export function render(mount) {
+export function render(mount${adopts ? ', _cursor = null' : ''}) {
 ${statements.map((line) => '  ' + line).join('\n')}
-  mount.appendChild(${rootVar});
+${rootTaken ? `  if (!${rootTaken}) mount.appendChild(${rootVar});` : `  mount.appendChild(${rootVar});`}
   return ${rootVar};
 }
-${isStatic ? staticNote() : hydrateBlock()}`.trimStart();
+${isStatic ? staticNote() : hydrateBlock(adopts)}`.trimStart();
 }
 
 // Collects every import the module needs into one set of statements,
@@ -164,7 +216,8 @@ function mergeImports(
   runtimeSpecifier,
   needsDispose = false,
   inlineModules = null,
-  needsUntracked = false
+  needsUntracked = false,
+  needsAdopt = false
 ) {
   const pageImports = [...script.matchAll(/^\s*(import\s[^;\n]+;?)\s*$/gm)]
     .map((m) => m[1].trim())
@@ -229,6 +282,7 @@ function mergeImports(
   record(`import { effect } from '${runtimeSpecifier}';`);
   if (needsDispose) record(`import { dispose } from '${runtimeSpecifier}';`);
   if (needsUntracked) record(`import { untracked } from '${runtimeSpecifier}';`);
+  if (needsAdopt) record(`import { adopt } from '${runtimeSpecifier}';`);
 
   const lines = [
     ...[...named].map(([specifier, bindings]) => {
@@ -379,7 +433,18 @@ function staticNote() {
 `;
 }
 
-function hydrateBlock() {
+function hydrateBlock(adopts = false) {
+  const mountLines = adopts
+    ? `  // Adopting: the walker takes each node the server already sent,
+  // so focus, a caret position and an open <details> survive. Anything
+  // that does not match is created instead, and anything left over is
+  // removed — a stale page costs the rebuild we used to do always.
+  const _cursor = adopt(mount);
+  render(mount, _cursor);
+  _cursor.done();`
+    : `  mount.innerHTML = '';
+  render(mount);`;
+
   return `
 // Hydrate: the SSR markup is already on the page, so clear it and
 // mount the reactive version in its place.
@@ -391,8 +456,7 @@ function hydrateBlock() {
 // navigation, so one listener covers both.
 if (typeof document !== 'undefined') {
   const mount = document.querySelector('[data-azox-root]') ?? document.body;
-  mount.innerHTML = '';
-  render(mount);
+${mountLines}
   // Guarded: the emitted module is also run against minimal DOM stubs —
   // in tests, and anywhere rendering happens outside a browser — where
   // CustomEvent and dispatchEvent need not exist.
@@ -407,11 +471,11 @@ if (typeof document !== 'undefined') {
 `;
 }
 
-function emitNode(node, statements, fallbackVar, inSvg = false) {
+function emitNode(node, statements, fallbackVar, inSvg = false, cursor = null) {
   if (!node) return 'null';
 
   if (node.type === 'text') {
-    return emitText(node, statements, fallbackVar);
+    return emitText(node, statements, fallbackVar, cursor);
   }
 
   // A fragment (from <slot />) has no element of its own; it wraps
@@ -419,7 +483,9 @@ function emitNode(node, statements, fallbackVar, inSvg = false) {
   if (node.type === 'fragment') {
     const varName = nextId();
     statements.push(`const ${varName} = document.createDocumentFragment();`);
-    appendChildren(varName, node.children, statements, fallbackVar, inSvg);
+    // A fragment owns no node of its own, so its children are adopted
+    // against the parent's cursor rather than a new one.
+    appendChildren(varName, node.children, statements, fallbackVar, inSvg, cursor, true);
     return varName;
   }
 
@@ -433,17 +499,35 @@ function emitNode(node, statements, fallbackVar, inSvg = false) {
   // HTML element, so an inline <svg> compiled to something the browser
   // laid out as an unknown HTML tag: present in the DOM, 0×0 on screen.
   const svg = inSvg || SVG_TAGS.has(node.name);
-  statements.push(
-    svg
-      ? `const ${varName} = document.createElementNS("http://www.w3.org/2000/svg", ${JSON.stringify(node.name)});`
-      : `const ${varName} = document.createElement(${JSON.stringify(node.name)});`
-  );
+  // With a cursor, take the node the server already sent when it
+  // matches. A mismatch yields null and this falls back to creating, so
+  // a stale page costs the work we do today rather than breaking.
+  const create = svg
+    ? `document.createElementNS("http://www.w3.org/2000/svg", ${JSON.stringify(node.name)})`
+    : `document.createElement(${JSON.stringify(node.name)})`;
+
+  // Optional call: render() is exported, and a direct caller passes no
+  // cursor at all. Without the guard the root line would throw on null
+  // instead of falling back to creating the node.
+  //
+  // The adopted node is kept in its own binding so whoever appends this
+  // one can tell the two cases apart: an adopted node is already in
+  // place, and re-appending it would detach and re-attach it, which
+  // blurs it. See docs/hydration.md.
+  if (cursor) {
+    const taken = nextId();
+    statements.push(`const ${taken} = ${cursor}?.next(${JSON.stringify(node.name)});`);
+    statements.push(`const ${varName} = ${taken} ?? ${create};`);
+    adoptedOf.set(varName, taken);
+  } else {
+    statements.push(`const ${varName} = ${create};`);
+  }
 
   for (const [key, attr] of Object.entries(node.attrs)) {
     emitAttr(varName, key, attr, statements, node.name);
   }
 
-  appendChildren(varName, node.children, statements, fallbackVar, svg);
+  appendChildren(varName, node.children, statements, fallbackVar, svg, cursor);
 
   return varName;
 }
@@ -495,8 +579,8 @@ function emitControlBlock(statements, buildBody, sourceExpr, renderCall) {
 
   const holder = nextId();
 
-  statements.push(`const ${start} = document.createComment('');`);
-  statements.push(`const ${end} = document.createComment('');`);
+  statements.push(`const ${start} = document.createComment('${BLOCK_START}');`);
+  statements.push(`const ${end} = document.createComment('${BLOCK_END}');`);
 
   // The markers go into their own fragment straight away, so they
   // always have a parent to insert into. Waiting for the page to be
@@ -561,8 +645,8 @@ function emitKeyedEach(node, statements) {
   const rows = nextId();
   const holder = nextId();
 
-  statements.push(`const ${start} = document.createComment('');`);
-  statements.push(`const ${end} = document.createComment('');`);
+  statements.push(`const ${start} = document.createComment('${BLOCK_START}');`);
+  statements.push(`const ${end} = document.createComment('${BLOCK_END}');`);
   statements.push(`const ${holder} = document.createDocumentFragment();`);
   statements.push(`${holder}.append(${start}, ${end});`);
 
@@ -628,8 +712,10 @@ function emitKeyedEach(node, statements) {
   statements.push(`      ${rows}.set(_key, _row);`);
   statements.push(`    }`);
   statements.push(``);
-  statements.push(`    // Moving a node that is already in place is a no-op in`);
-  statements.push(`    // the DOM, so ordering costs nothing when nothing moved.`);
+  statements.push(`    // insertBefore detaches and re-attaches, even when the node`);
+  statements.push(`    // is already where it belongs — so this re-seeds the row and`);
+  statements.push(`    // would blur anything focused inside it. Harmless while rows`);
+  statements.push(`    // are built fresh, and the thing to fix when they are adopted.`);
   statements.push(`    for (const _node of _row.nodes) _parent.insertBefore(_node, ${end});`);
   statements.push(`    _i++;`);
   statements.push(`  }`);
@@ -702,11 +788,48 @@ function emitIf(node, statements) {
   );
 }
 
-function appendChildren(parentVar, children, statements, fallbackVar, inSvg = false) {
+function appendChildren(
+  parentVar,
+  children,
+  statements,
+  fallbackVar,
+  inSvg = false,
+  cursor = null,
+  reuseCursor = false
+) {
+  // Each element walks its own children, so a nested cursor is opened
+  // for it. A node the cursor handed back is already in place and must
+  // not be appended: appending an existing child detaches and
+  // re-attaches it, which blurs it and loses the reader's focus. Only a
+  // created node is appended. See docs/hydration.md.
+  //
+  // A fragment is the exception: it owns no node in the document, so
+  // there is nothing to open a cursor against. Its children continue
+  // the parent's walk, and the parent closes it.
+  //
+  // Nothing to walk: a void element like <input> would otherwise open a
+  // cursor and close it again without ever calling next().
+  if (!children.length) return;
+
+  let inner = reuseCursor ? cursor : null;
+  if (!reuseCursor && cursor) {
+    inner = nextId();
+    statements.push(`const ${inner} = adopt(${parentVar});`);
+  }
+
   for (const child of children) {
-    const childVar = emitNode(child, statements, fallbackVar, inSvg);
-    if (childVar !== 'null') statements.push(`${parentVar}.appendChild(${childVar});`);
+    const childVar = emitNode(child, statements, fallbackVar, inSvg, inner);
+    if (childVar === 'null') continue;
+    const taken = adoptedOf.get(childVar);
+    statements.push(
+      taken
+        ? `if (!${taken}) ${parentVar}.appendChild(${childVar});`
+        : `${parentVar}.appendChild(${childVar});`
+    );
   }
+
+  // Anything the server sent that the module did not claim is stale.
+  if (inner && !reuseCursor) statements.push(`${inner}.done();`);
 }
 
 // createTextNode takes text, not markup, so an entity the author
@@ -732,7 +855,7 @@ function foldLiteralParts(parts) {
   });
 }
 
-function emitText(node, statements, fallbackVar) {
+function emitText(node, statements, fallbackVar, cursor = null) {
   const isFixed = (part) => part.kind === 'static' || part.kind === 'literal';
   node = { ...node, parts: foldConstantParts(foldLiteralParts(node.parts)) };
 
@@ -740,13 +863,29 @@ function emitText(node, statements, fallbackVar) {
   if (node.parts.every(isFixed)) {
     const value = node.parts.map(textValue).join('');
     const varName = nextId();
-    statements.push(`const ${varName} = document.createTextNode(${JSON.stringify(value)});`);
+    if (cursor) {
+      const taken = nextId();
+      statements.push(`const ${taken} = ${cursor}?.next(null);`);
+      statements.push(
+        `const ${varName} = ${taken} ?? document.createTextNode(${JSON.stringify(value)});`
+      );
+      adoptedOf.set(varName, taken);
+    } else {
+      statements.push(`const ${varName} = document.createTextNode(${JSON.stringify(value)});`);
+    }
     return varName;
   }
 
   // Dynamic text: one text node, one effect that rewrites its data.
   const varName = nextId();
-  statements.push(`const ${varName} = document.createTextNode('');`);
+  if (cursor) {
+    const taken = nextId();
+    statements.push(`const ${taken} = ${cursor}?.next(null);`);
+    statements.push(`const ${varName} = ${taken} ?? document.createTextNode('');`);
+    adoptedOf.set(varName, taken);
+  } else {
+    statements.push(`const ${varName} = document.createTextNode('');`);
+  }
   const expr = node.parts
     .map((part) => (isFixed(part) ? JSON.stringify(textValue(part)) : `String(${part.expr})`))
     .join(' + ');
@@ -815,6 +954,7 @@ const DOM_PROPERTIES = new Set(['value', 'checked', 'selected', 'indeterminate']
 function emitAttr(varName, key, attr, statements, tagName) {
   if (key.startsWith('on:')) {
     const event = key.slice(3);
+    assertHandler(key, attr.expr);
     statements.push(`${varName}.addEventListener(${JSON.stringify(event)}, ${attr.expr});`);
     return;
   }
@@ -840,6 +980,43 @@ function emitAttr(varName, key, attr, statements, tagName) {
   statements.push(`effect(() => { ${varName}.setAttribute(${JSON.stringify(key)}, String(${attr.expr})); });`);
 }
 
+// A listener is the expression itself, so `on:click={n.set(1)}` passes
+// addEventListener whatever the call returned — and the call already ran
+// while the page was being built. The button then appears to fire once on
+// load and never again, with no error anywhere. Caught here instead.
+//
+// Only a call at the top level is rejected. A handler is far more often a
+// name (`handler`, `obj.method`, `fns[i]`) or an arrow whose body happens
+// to contain a call, and all of those have to keep working.
+function assertHandler(key, rawExpr) {
+  const expr = rawExpr.trim();
+
+  if (/=>/.test(expr)) return;
+  if (/^(async\s+)?function\b/.test(expr)) return;
+
+  const opening = /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*|\[[^\]]*\])*\(/.exec(expr);
+  if (!opening || !expr.endsWith(')')) return;
+
+  // Balanced from the first `(`: only a call that closes at the very end
+  // is the whole expression. `f(1) || g` is something else, and left
+  // alone.
+  let depth = 0;
+  for (let i = opening[0].length - 1; i < expr.length; i++) {
+    if (expr[i] === '(') depth++;
+    else if (expr[i] === ')') {
+      depth--;
+      if (depth === 0 && i !== expr.length - 1) return;
+    }
+  }
+
+  const name = opening[0].slice(0, -1);
+  throw new Error(
+    `Azox: ${key}={${expr}} calls ${name}() while the page is built, and ` +
+      `passes the result as the listener — ` +
+      `write ${key}={() => ${expr}} to call it on the event instead`
+  );
+}
+
 // Two-way binding: the element shows the signal, and the signal follows
 // the element. Writing it by hand means a value= and an on:input= that
 // have to agree, and getting the event or the property wrong is easy —

package/core/index.d.ts

@@ -11,9 +11,11 @@ export {
   untracked,
   onMount,
   onCleanup,
+  adopt,
   type Signal,
   type ReadonlySignal,
   type EffectHandle,
+  type AdoptCursor,
 } from './reactivity/signal.js';
 
 export { parseAzox, compileToModule } from './compiler/index.js';

package/core/index.js

@@ -11,6 +11,7 @@ export {
   untracked,
   onMount,
   onCleanup,
+  adopt,
 } from './reactivity/signal.js';
 export { parseAzox } from './compiler/parser.js';
 export { compileToModule } from './compiler/compileToJs.js';

package/core/reactivity/signal.d.ts

@@ -86,3 +86,21 @@ export declare function onMount(fn: () => void | (() => void)): void;
  * top level of a page — nothing ever removes it.
  */
 export declare function onCleanup(fn: () => void): void;
+
+/** A cursor over server-rendered nodes, used by hydration. */
+export interface AdoptCursor {
+  /**
+   * The next node if it matches — a tag name, null for text, or
+   * '#comment' for a control-flow marker.
+   */
+  next(expect: string | null): Node | null;
+  /** Removes anything the module did not claim. */
+  done(): void;
+}
+
+/**
+ * Walks a parent's existing children so hydration can bind to them
+ * rather than replacing them. Returns a cursor that yields null on any
+ * mismatch, at which point the caller creates the node instead.
+ */
+export declare function adopt(parent: Node | null): AdoptCursor;

package/core/reactivity/signal.js

@@ -181,3 +181,64 @@ export function computed(fn) {
   effect(() => derived.set(fn()));
   return derived;
 }
+
+/* ---------- hydration ---------- */
+
+// A cursor over server-rendered nodes, so hydration can bind to what is
+// already on the page instead of replacing it. Replacing destroys the
+// reader's focus, caret and anything they had expanded.
+//
+// `next` returns the node the compiled module expected, or null when the
+// markup does not match — a stale cache, an edited page, a host without
+// a walkable DOM. The module then creates that node as it always did, so
+// a mismatch costs the work we already do rather than a broken page.
+export function adopt(parent) {
+  // A minimal DOM stub — the compiler's own tests use one — has no
+  // childNodes to walk. Creating is then the only option.
+  if (!parent || typeof parent !== 'object' || !parent.firstChild) {
+    return { next: () => null, done: () => {} };
+  }
+
+  // Snapshotted rather than walked through `nextSibling`. The caller
+  // appends each node it adopts, and appending a node that is already a
+  // child detaches and re-attaches it — which rewrites `nextSibling` for
+  // whatever preceded it. A lazy walk therefore ends up pointing at a
+  // node it already handed out, and the sweep below deletes the live
+  // page. Measured: every child adopted in the right order, and every
+  // one removed a moment later. The list is fixed before any of that can
+  // happen, so reordering cannot move the cursor.
+  const kids = [];
+  for (let child = parent.firstChild; child; child = child.nextSibling) kids.push(child);
+  let i = 0;
+
+  return {
+    // `expect` is a tag name for an element, null for a text node, or
+    // '#comment' for one of the markers a control-flow block anchors on.
+    // A block's markers are the nodes it later inserts and removes
+    // against, so adopting the region between them means adopting the
+    // pair itself first.
+    next(expect) {
+      const current = kids[i];
+      if (!current) return null;
+
+      const type = current.nodeType;
+      const matches =
+        expect === null
+          ? type === 3
+          : expect === '#comment'
+            ? type === 8
+            : type !== 3 && type !== 8 && current.nodeName?.toLowerCase() === expect;
+
+      if (!matches) return null;
+
+      i++;
+      return current;
+    },
+
+    // Anything the server sent that the module did not claim is stale
+    // and has to go, or it would linger below the adopted nodes.
+    done() {
+      for (; i < kids.length; i++) kids[i].remove?.();
+    },
+  };
+}

package/core/renderer/renderToHtml.js

@@ -102,7 +102,7 @@ function renderScope(node, scope, modules = {}) {
 // so the body sees it the same way the compiled version does.
 function renderEach(node, scope, outer, modules = {}) {
   const items = evalExpr(node.expr, scope);
-  if (items === null || items === undefined) return '';
+  if (items === null || items === undefined) return wrapBlock('');
 
   if (typeof items[Symbol.iterator] !== 'function') {
     throw new BuildError(
@@ -121,12 +121,23 @@ function renderEach(node, scope, outer, modules = {}) {
     index++;
   }
 
-  return html;
+  return wrapBlock(html);
 }
 
 function renderIf(node, scope, outer, modules = {}) {
   const branch = evalExpr(node.expr, scope) ? node.then : node.otherwise;
-  return branch.map((child) => renderNode(child, scope, outer, modules)).join('');
+  const inner = branch.map((child) => renderNode(child, scope, outer, modules)).join('');
+
+  return wrapBlock(inner);
+}
+
+// The same start/end pair the compiler builds, so hydration can adopt
+// the server's nodes instead of discarding them. Labelled, because an
+// empty comment cannot be told apart from its neighbour.
+//
+// See docs/hydration.md.
+function wrapBlock(html) {
+  return `<!--[-->${html}<!--]-->`;
 }
 
 // Reads an attribute expression. A bound one names a signal, so it is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "azoxjs",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Azox Framework — The Sound of Future Web",
   "type": "module",
   "license": "MIT",