npm - azoxjs - Versions diffs - 0.3.0 → 1.0.1 - Mend

azoxjs 0.3.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/README.md +49 -6
package/core/build.js +21 -4
package/core/commands/create.js +1 -2
package/core/compiler/compileToJs.js +240 -19
package/core/compiler/parser.js +18 -2
package/core/index.js +12 -1
package/core/reactivity/signal.js +101 -1
package/core/renderer/renderToHtml.js +27 -2
package/core/renderer/serverScope.js +14 -0
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -11,8 +11,11 @@ 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: early development (v0.3.0). APIs are unstable and will
-> change without notice until v1.0.
+> Status: stable (v1.0.1). 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
+> points, not bugs.
 ## Why Azox
@@ -187,6 +190,39 @@ There is still no component instance at runtime: the compiler wraps
 each use in its own JavaScript scope, which is ordinary scoping
 rather than a framework construct.
+## Lifecycle
+`onMount` runs once the DOM is in the document; `onCleanup` runs when
+the scope goes away.
+```html
+<script>
+  import { signal, onMount, onCleanup } from 'azox/reactivity';
+  const width = signal(0);
+  let box;
+  onMount(() => {
+    // The nodes exist now, so they can be measured.
+    const onResize = () => width.set(box.clientWidth);
+    onResize();
+    window.addEventListener('resize', onResize);
+    // Returned from onMount, so it is the cleanup for this setup.
+    return () => window.removeEventListener('resize', onResize);
+  });
+  onCleanup(() => console.log('gone'));
+</script>
+<div>{width()}px</div>
+```
+A scope goes away when a row leaves a keyed list, or when an `<if>`
+takes the other branch. At the top level of a page nothing ever removes
+it, so `onCleanup` there never runs — that is a page living as long as
+the document, not a failure.
 ## Layouts and the document head
 A component can carry a `<head>` block, so one shared component holds
@@ -330,10 +366,17 @@ npm run build
 ```
 The build lands in `.azox/build/` as a self-contained static bundle —
-an `index.html` per route, a compiled hydration module beside it, and
-one shared copy of the runtime. No dev machinery is included. Serve
-that directory with any static host and it works with no install
-step and no rewrite configuration.
+an `index.html` per route, a compiled hydration module beside it where
+one is needed, and one shared copy of the runtime. No dev machinery is
+included. Serve that directory with any static host and it works with
+no install step and no rewrite configuration.
+A page with no bindings and no listeners ships **no JavaScript at
+all**: it arrives complete from the build, so the document references
+no module and none is written. An expression that reads only
+build-time constants — a version from `package.json`, say — is folded
+into the markup rather than wrapped in an effect, which is often what
+decides whether a page needs a module in the first place.
 ## CLI

package/core/build.js CHANGED Viewed

@@ -17,7 +17,7 @@ import { createRequire } from 'node:module';
 import { parseAzox } from './compiler/parser.js';
 import { resolveComponents } from './compiler/resolveComponents.js';
-import { compileToModule } from './compiler/compileToJs.js';
+import { compileToModule, STATIC_MARKER } from './compiler/compileToJs.js';
 import { renderToHtml } from './renderer/renderToHtml.js';
 import { parseImports } from './renderer/moduleBindings.js';
 import { evaluateScript } from './renderer/serverScope.js';
@@ -107,7 +107,18 @@ export function buildRoute(projectDir, route, { transformHtml } = {}) {
   );
   assertValidJavaScript(clientModule, name);
-  writeFileSync(clientPath, clientModule, 'utf8');
+  // A page with no bindings and no listeners does nothing on load, so
+  // the document does not reference its module — and without a reference
+  // there is no reason to write it. The page still arrives complete,
+  // because the markup was rendered during the build.
+  const isStatic = clientModule.includes(STATIC_MARKER);
+  if (isStatic) {
+    // A previous build may have left one behind.
+    if (existsSync(clientPath)) rmSync(clientPath);
+  } else {
+    writeFileSync(clientPath, clientModule, 'utf8');
+  }
   // One runtime at the build root, shared by every page.
   const runtimePath = resolve(buildRoot, RUNTIME_FILENAME);
@@ -125,6 +136,7 @@ export function buildRoute(projectDir, route, { transformHtml } = {}) {
   let document = wrapDocument(html, projectTitle(projectDir), head, {
     routerSrc: router ? `${route.assetPrefix}${ROUTER_FILENAME}` : null,
+    clientSrc: isStatic ? null : './page.client.js',
   });
   if (transformHtml) document = transformHtml(document);
@@ -598,7 +610,12 @@ function normaliseHeadLine(line) {
 // A page's own <head> block wins over the fallback title, so a page
 // can set its own <title>, stylesheets and meta tags.
-function wrapDocument(bodyHtml, title, head = '', { routerSrc = null } = {}) {
+function wrapDocument(
+  bodyHtml,
+  title,
+  head = '',
+  { routerSrc = null, clientSrc = './page.client.js' } = {}
+) {
   const hasOwnTitle = /<title>/i.test(head);
   // The router is loaded after the page's own module, so a page is
@@ -615,7 +632,7 @@ function wrapDocument(bodyHtml, title, head = '', { routerSrc = null } = {}) {
 ${hasOwnTitle ? '' : `  <title>${escapeHtml(title)}</title>\n`}${head ? indent(head) + '\n' : ''}</head>
 <body>
 <div data-azox-root>${bodyHtml}</div>
-<script type="module" src="./page.client.js"></script>${router}
+${clientSrc ? `<script type="module" src="${clientSrc}"></script>` : ''}${router}
 </body>
 </html>
 `;

package/core/commands/create.js CHANGED Viewed

@@ -119,8 +119,7 @@ function starterPage(name) {
   </ul>
   <input
-    value={draft()}
-    on:input={(e) => draft.set(e.target.value)}
+    bind:value={draft}
     placeholder="Add a task"
   />
   <button on:click={() => {

package/core/compiler/compileToJs.js CHANGED Viewed

@@ -10,6 +10,52 @@
 let uid = 0;
 const nextId = () => `_el${uid++}`;
+// Names the build resolved to constants — an inlined JSON import, say.
+// An expression reading only these can never change, so it is emitted
+// as text rather than wrapped in an effect. Set per compile.
+let constantNames = new Set();
+let constantValues = {};
+// True when `expr` reads nothing that could ever change: literals,
+// operators, and property paths rooted in a build-time constant.
+//
+// Deliberately conservative. A call, an unknown identifier, or anything
+// it cannot account for means "assume it changes" — being wrong that way
+// costs an effect that never fires, while the opposite silently freezes
+// a binding that should update.
+function isConstantExpression(expr) {
+  if (!constantNames.size) return false;
+  const source = expr.trim();
+  if (!source) return false;
+  // A call could return anything, and assignment or increment means the
+  // value is meant to change.
+  if (/[(]/.test(source)) return false;
+  if (/(\+\+|--|[^=!<>]=[^=])/.test(source)) return false;
+  // Strip strings and template literals before looking at identifiers,
+  // so words inside them are not mistaken for names.
+  const withoutStrings = source
+    .replace(/'(?:[^'\\]|\\.)*'/g, "''")
+    .replace(/"(?:[^"\\]|\\.)*"/g, '""')
+    .replace(/`(?:[^`\\$]|\\.|\$(?!\{))*`/g, '``');
+  // A template literal with a placeholder is not handled here.
+  if (/`/.test(withoutStrings) && /\$\{/.test(source)) return false;
+  // Every identifier that is not a property access must be a known
+  // constant. `pkg.version` yields `pkg`; `a.b.c` yields `a`.
+  const roots = [...withoutStrings.matchAll(/(\.)?\b([A-Za-z_$][\w$]*)\b/g)]
+    .filter(([, dot]) => !dot)
+    .map(([, , name]) => name);
+  if (!roots.length) return false;
+  const allowed = new Set(['true', 'false', 'null', 'undefined']);
+  return roots.every((name) => constantNames.has(name) || allowed.has(name));
+}
 // runtimeSpecifier: how the emitted module should import the Azox
 //   runtime — a relative path to the copied runtime for a build, or
 //   whatever the playground wants to point at.
@@ -32,6 +78,11 @@ export function compileToModule(
   { runtimeSpecifier, rewriteImports, inlineModules, routeParams }
 ) {
   uid = 0;
+  // 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');
@@ -65,13 +116,15 @@ export function compileToModule(
   // A keyed list disposes the effects of rows that leave, so the
   // module needs dispose as well as effect.
   const needsDispose = statements.some((line) => line.includes('dispose('));
+  const needsUntracked = statements.some((line) => line.includes('untracked('));
   const { imports, body } = mergeImports(
     script,
     hoisted,
     runtimeSpecifier,
     needsDispose,
-    inlineModules
+    inlineModules,
+    needsUntracked
   );
   // Narrowed to what the module actually reads, so importing
@@ -102,7 +155,8 @@ function mergeImports(
   componentImports,
   runtimeSpecifier,
   needsDispose = false,
-  inlineModules = null
+  inlineModules = null,
+  needsUntracked = false
 ) {
   const pageImports = [...script.matchAll(/^\s*(import\s[^;\n]+;?)\s*$/gm)]
     .map((m) => m[1].trim())
@@ -116,6 +170,24 @@ function mergeImports(
   const named = new Map();
   const verbatim = new Set();
+  // A page writes `azox/reactivity`; the compiler's own imports use
+  // whatever runtimeSpecifier it was given. They name the same module,
+  // so they are grouped under one key — otherwise a page importing
+  // `signal` and a keyed list needing it emit two imports that the
+  // build later rewrites to the same path, which is a redeclaration and
+  // a syntax error.
+  //
+  // Only the grouping is normalised. The emitted specifier stays as
+  // written, because rewriting it to a path on disk is the build's job —
+  // the playground compiles in the browser with no build at all.
+  const RUNTIME_ALIASES = new Set([
+    'azox',
+    'azox/reactivity',
+    'azoxjs',
+    'azoxjs/reactivity',
+    runtimeSpecifier,
+  ]);
   const record = (statement) => {
     const match = statement.match(/^import\s*\{([^}]*)\}\s*from\s*['"]([^'"]+)['"]/);
@@ -124,7 +196,13 @@ function mergeImports(
       return;
     }
-    const [, bindings, specifier] = match;
+    const [, bindings, rawSpecifier] = match;
+    // Grouped under the first spelling seen for the runtime, so the
+    // page's own `azox/reactivity` survives into the output when that is
+    // what was written.
+    const specifier = RUNTIME_ALIASES.has(rawSpecifier)
+      ? runtimeKey(named, rawSpecifier, RUNTIME_ALIASES)
+      : rawSpecifier;
     const set = named.get(specifier) ?? new Set();
     for (const binding of bindings.split(',')) {
       if (binding.trim()) set.add(binding.trim());
@@ -132,10 +210,17 @@ function mergeImports(
     named.set(specifier, set);
   };
+  // The author's imports are recorded first, so the runtime group keeps
+  // the spelling they wrote — `azox/reactivity`, which the build rewrites
+  // later. Recording the compiler's own first would name the group after
+  // runtimeSpecifier and rewrite the author's import here, which is the
+  // build's job and would break the playground's build-free compile.
+  for (const statement of [...componentImports, ...pageImports]) record(statement);
   // `effect` is always needed: the compiler emits calls to it.
   record(`import { effect } from '${runtimeSpecifier}';`);
   if (needsDispose) record(`import { dispose } from '${runtimeSpecifier}';`);
-  for (const statement of [...componentImports, ...pageImports]) record(statement);
+  if (needsUntracked) record(`import { untracked } from '${runtimeSpecifier}';`);
   const lines = [
     ...[...named].map(([specifier, bindings]) => {
@@ -147,6 +232,15 @@ function mergeImports(
   return { imports: lines.join('\n'), body };
 }
+// Returns the key the runtime's imports are already grouped under, or
+// this spelling if it is the first one seen.
+function runtimeKey(named, specifier, aliases) {
+  for (const existing of named.keys()) {
+    if (aliases.has(existing)) return existing;
+  }
+  return specifier;
+}
 // An import is inlined when every binding it declares was loaded by
 // the build. Matching on the specifier would be wrong: the same file
 // could be imported for some other reason.
@@ -195,10 +289,20 @@ function emitInlineModules(inlineModules, usage = '') {
   const entries = Object.entries(inlineModules);
   if (!entries.length) return '';
-  const lines = entries.map(
-    ([name, value]) => `const ${name} = ${JSON.stringify(narrow(name, value, usage))};`
-  );
-  return `${lines.join('\n')}\n`;
+  const lines = entries
+    // A value whose every read was folded into the markup needs no
+    // declaration at all. Emitting it anyway would publish the rest of
+    // the file — an author's address included — for nothing.
+    .filter(([name]) => isRead(name, usage))
+    .map(([name, value]) => `const ${name} = ${JSON.stringify(narrow(name, value, usage))};`);
+  return lines.length ? `${lines.join('\n')}\n` : '';
+}
+// Whether the emitted code still mentions the binding.
+function isRead(name, usage) {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`\\b${escaped}\\b`).test(usage);
 }
 // Keeps only the properties the module reads by name. A page that
@@ -253,11 +357,17 @@ function resolveRouteDeclarations(script, routeParams) {
     .replace(/\bparams\s*\(\s*\)/g, JSON.stringify(routeParams));
 }
+// Marks a module that does nothing on load. The build reads it to decide
+// whether the page needs to reference the module at all — a static page
+// that still downloads it pays for a render() nobody calls, and pulls in
+// the runtime with it.
+export const STATIC_MARKER = 'azox:static';
 function staticNote() {
   return `
-// This page has no bindings and no listeners, so the server-rendered
-// markup is already complete and is left untouched. render() is
-// exported for anyone who wants to mount it somewhere else.
+// ${STATIC_MARKER} — this page has no bindings and no listeners, so the
+// server-rendered markup is already complete and is left untouched.
+// render() is exported for anyone who wants to mount it somewhere else.
 `;
 }
@@ -297,7 +407,7 @@ function emitNode(node, statements, fallbackVar) {
   statements.push(`const ${varName} = document.createElement(${JSON.stringify(node.name)});`);
   for (const [key, attr] of Object.entries(node.attrs)) {
-    emitAttr(varName, key, attr, statements);
+    emitAttr(varName, key, attr, statements, node.name);
   }
   appendChildren(varName, node.children, statements, fallbackVar);
@@ -410,7 +520,7 @@ function emitEach(node, statements) {
 // inside their own effect scope rather than inside the block's, since
 // re-running the block must not tear down rows it is keeping.
 function emitKeyedEach(node, statements) {
-  const params = node.index ? `${node.alias}, ${node.index}` : node.alias;
+  const buildParams = node.index ? `${node.alias}, ${node.index}` : node.alias;
   const start = nextId();
   const end = nextId();
@@ -432,12 +542,28 @@ function emitKeyedEach(node, statements) {
   const bodyLines = [];
   const roots = node.children.map((child) => emitNode(child, bodyLines, 'root'));
-  statements.push(`const ${build} = (${params}) => {`);
+  // The index is the position the row was built at, and a keyed row is
+  // built once. Reordering therefore moves rows without renumbering
+  // them — the cost of keeping a row rather than rebuilding it. Use the
+  // index for a stable list, and read the position from the data when a
+  // list reorders.
+  statements.push(`const ${build} = (${buildParams}) => {`);
   statements.push(`  let _nodes;`);
-  statements.push(`  const _scope = effect(() => {`);
+  // untracked: the row is built while the list's effect is running, so
+  // without this it becomes that effect's child — and the next list
+  // change tears the row down even though it survived, leaving its
+  // bindings dead and its onCleanup callbacks fired.
+  statements.push(`  const _scope = untracked(() => effect(() => {`);
   for (const line of bodyLines) statements.push(`    ${line}`);
-  statements.push(`    _nodes = [${roots.filter((r) => r !== 'null').join(', ')}];`);
-  statements.push(`  });`);
+  // A root may be a DocumentFragment — a component with several roots
+  // returns one. A fragment empties when it is inserted and has no
+  // .remove(), so its children are recorded instead; otherwise removing
+  // the row threw and left it on screen with its cleanups unrun.
+  statements.push(
+    `    _nodes = [${roots.filter((r) => r !== 'null').join(', ')}]` +
+      `.flatMap((_n) => (_n instanceof DocumentFragment ? [..._n.childNodes] : [_n]));`
+  );
+  statements.push(`  }));`);
   statements.push(`  return { nodes: _nodes, scope: _scope };`);
   statements.push(`};`);
@@ -575,7 +701,7 @@ function foldLiteralParts(parts) {
 function emitText(node, statements, fallbackVar) {
   const isFixed = (part) => part.kind === 'static' || part.kind === 'literal';
-  node = { ...node, parts: foldLiteralParts(node.parts) };
+  node = { ...node, parts: foldConstantParts(foldLiteralParts(node.parts)) };
   // Nothing dynamic: one text node, no effect needed.
   if (node.parts.every(isFixed)) {
@@ -595,6 +721,46 @@ function emitText(node, statements, fallbackVar) {
   return varName;
 }
+// Turns an expression the build already resolved into a literal part, so
+// the text node is created with the value rather than an effect being
+// attached to write it. The page whose only "dynamic" text is a version
+// number then ships as a static page.
+function foldConstantParts(parts) {
+  if (!constantNames.size) return parts;
+  return parts.map((part) => {
+    if (part.kind !== 'expr' || !isConstantExpression(part.expr)) return part;
+    const value = evaluateInlinedExpression(part.expr);
+    if (value === undefined) return part;
+    return { kind: 'literal', value: String(value) };
+  });
+}
+// Evaluates a constant expression against the values the build resolved.
+// Returns undefined when it cannot be evaluated, which leaves the part
+// dynamic — the safe direction.
+//
+// Named for this file: the playground concatenates the compiler's
+// modules into one scope, so a bare `evaluateConstant` collides with the
+// one in resolveComponents.js and the whole bundle fails to parse.
+function evaluateInlinedExpression(expr) {
+  try {
+    const names = [...constantNames];
+    const fn = new Function(...names, `return (${expr});`);
+    const value = fn(...names.map((name) => constantValues[name]));
+    // Only a primitive can be written into the markup as text.
+    if (value === null || value === undefined) return undefined;
+    if (typeof value === 'object' || typeof value === 'function') return undefined;
+    return value;
+  } catch {
+    return undefined;
+  }
+}
 // The five entities that matter for text content. Numeric forms are
 // handled too, since documentation snippets tend to use them.
 function decodeEntities(text) {
@@ -608,22 +774,77 @@ function decodeEntities(text) {
     .replace(/&amp;/g, '&');
 }
-function emitAttr(varName, key, attr, statements) {
+// Properties that must be set as properties rather than attributes:
+// setAttribute("value") only sets the *initial* value, so after a user
+// types, writing the attribute changes nothing they can see.
+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);
     statements.push(`${varName}.addEventListener(${JSON.stringify(event)}, ${attr.expr});`);
     return;
   }
+  if (key.startsWith('bind:')) {
+    emitBinding(varName, key.slice(5), attr, statements, tagName);
+    return;
+  }
   if (attr.kind === 'static') {
     statements.push(`${varName}.setAttribute(${JSON.stringify(key)}, ${JSON.stringify(attr.value)});`);
     return;
   }
+  // A property has to be assigned, not set as an attribute — see
+  // DOM_PROPERTIES. Everything else is an attribute.
+  if (DOM_PROPERTIES.has(key)) {
+    statements.push(`effect(() => { ${varName}.${key} = ${attr.expr}; });`);
+    return;
+  }
   // Dynamic attribute: wrap in its own effect, same fine-grained rule as text.
   statements.push(`effect(() => { ${varName}.setAttribute(${JSON.stringify(key)}, String(${attr.expr})); });`);
 }
+// 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 —
+// a checkbox reports `checked`, not `value`, and a number input reports
+// a string.
+function emitBinding(varName, property, attr, statements, tagName) {
+  const signal = attr.expr.trim();
+  // The signal itself, not a call: `bind:value={draft}`. Binding needs
+  // to write back, which a value cannot do.
+  if (!/^[A-Za-z_$][\w$]*$/.test(signal)) {
+    throw new Error(
+      `Azox: bind:${property}={${signal}} needs a signal by name — ` +
+        `write bind:${property}={draft}, not bind:${property}={draft()}`
+    );
+  }
+  // A checkbox's state is `checked`, and the event that reports it is
+  // "change" rather than "input".
+  const isCheckbox = property === 'checked';
+  const event = isCheckbox || tagName === 'select' ? 'change' : 'input';
+  statements.push(`effect(() => { ${varName}.${property} = ${signal}(); });`);
+  statements.push(
+    `${varName}.addEventListener(${JSON.stringify(event)}, (_e) => ` +
+      `${signal}.set(${readTarget(property, tagName)}));`
+  );
+}
+// How the value is read back off the element. A number input reports a
+// string, so it is converted — otherwise arithmetic on the signal
+// silently concatenates.
+function readTarget(property, tagName) {
+  if (property === 'checked') return '_e.target.checked';
+  if (tagName === 'input') return '(_e.target.type === "number" ? _e.target.valueAsNumber : _e.target.value)';
+  return '_e.target.value';
+}
 // Component imports are resolved at build time and inlined, so the
 // .azox specifier must not survive into JavaScript the browser loads.
 function dropComponentImports(script) {

package/core/compiler/parser.js CHANGED Viewed

@@ -31,15 +31,31 @@ export function parseAzox(source) {
     .trim();
   const tokens = tokenize(template);
-  const { node, rest } = parseNode(tokens);
+  // Several roots become one fragment, so a component can return a pair
+  // of <li>s or a label beside its input without a wrapper element that
+  // exists only to satisfy the parser.
+  const roots = [];
+  let rest = tokens;
+  while (rest.length) {
+    const parsed = parseNode(rest);
+    if (!parsed.node) break;
+    roots.push(parsed.node);
+    rest = parsed.rest;
+  }
   if (rest.length) {
     throw new ParseError(`Azox parse error: unexpected trailing markup near "${rest[0]?.value ?? ''}"`);
   }
+  const markup = roots.length === 1 ? roots[0] : { type: 'fragment', children: roots };
   return {
     script,
     head,
-    markup: node,
+    markup,
     components: parseComponentImports(script),
     props: parsePropNames(script),
     // A dynamic page destructures its route parameters the same way a

package/core/index.js CHANGED Viewed

@@ -1,6 +1,17 @@
 // Public entry point for `import ... from 'azoxjs'`.
-export { signal, effect, computed } from './reactivity/signal.js';
+// The whole reactivity surface, so `azoxjs` and `azoxjs/reactivity`
+// offer the same thing rather than the main entry quietly omitting the
+// newer half.
+export {
+  signal,
+  effect,
+  computed,
+  dispose,
+  untracked,
+  onMount,
+  onCleanup,
+} from './reactivity/signal.js';
 export { parseAzox } from './compiler/parser.js';
 export { compileToModule } from './compiler/compileToJs.js';
 export { renderToHtml } from './renderer/renderToHtml.js';

package/core/reactivity/signal.js CHANGED Viewed

@@ -32,6 +32,23 @@ export function signal(initialValue) {
   return read;
 }
+// Runs `fn` with no effect considered active, so anything it creates
+// belongs to nobody and survives the caller re-running.
+//
+// A keyed list needs this: its rows are built inside the list's own
+// effect, which would make them its children — and re-running the list
+// then tears down every surviving row, leaving it on screen but no
+// longer reactive.
+export function untracked(fn) {
+  const previous = activeEffect;
+  activeEffect = null;
+  try {
+    return fn();
+  } finally {
+    activeEffect = previous;
+  }
+}
 export function effect(fn) {
   const wrapped = () => {
     // Drop last run's subscriptions before re-reading. Without this,
@@ -55,25 +72,108 @@ export function effect(fn) {
   if (activeEffect) activeEffect.children.add(wrapped);
   wrapped.children = new Set();
+  // Callbacks registered by onCleanup() while this effect runs.
+  wrapped.cleanups = new Set();
   wrapped();
   return wrapped;
 }
+// Registers work to undo when the surrounding scope goes away: a
+// timer to clear, a listener to remove, a subscription to close.
+//
+// Called inside a component's script it runs when the component is
+// removed — a row leaving a keyed list, or a branch of an <if> that is
+// no longer taken. Called at the top level of a page there is nothing
+// that ever removes it, so it never runs; that is a page living as long
+// as the document, not a failure.
+export function onCleanup(fn) {
+  if (typeof fn !== 'function') {
+    throw new TypeError('onCleanup() needs a function to call when the scope goes away');
+  }
+  if (!activeEffect) return;
+  activeEffect.cleanups.add(fn);
+}
+// Runs after the DOM this scope builds is in the document.
+//
+// A component's script runs while its nodes are still being created,
+// so measuring an element or focusing an input has to wait. Queued as
+// a microtask, which is after the synchronous render and before the
+// browser paints.
+export function onMount(fn) {
+  if (typeof fn !== 'function') {
+    throw new TypeError('onMount() needs a function to call once the DOM is ready');
+  }
+  // Captured now: by the time the microtask runs, the effect that owns
+  // this registration is no longer the active one.
+  const owner = activeEffect;
+  queueMicrotask(() => {
+    // The scope was disposed before it ever mounted — a row added and
+    // removed in the same tick. Running setup for something already
+    // gone would leak whatever it creates.
+    if (owner && owner.disposed) return;
+    const result = fn();
+    // A function returned from onMount is treated as its cleanup, so
+    // the common setup-and-teardown pair can stay in one place.
+    if (typeof result === 'function') {
+      if (owner && !owner.disposed) owner.cleanups.add(result);
+      else result();
+    }
+  });
+}
 // Detaches an effect from every signal it read, and disposes anything
 // it created. Called before a re-run and by dispose().
 function unsubscribe(effectFn) {
   for (const child of effectFn.children) unsubscribe(child);
   effectFn.children.clear();
+  // Cleanups run before the effect is detached, so they still see the
+  // state they were registered against. One throwing must not stop the
+  // rest — a half-cleaned scope leaks whatever the others held.
+  for (const cleanup of effectFn.cleanups ?? []) {
+    try {
+      cleanup();
+    } catch (error) {
+      reportCleanupError(error);
+    }
+  }
+  effectFn.cleanups?.clear();
   for (const subscribers of effectFn.sources) subscribers.delete(effectFn);
   effectFn.sources.clear();
 }
+// A cleanup that throws is a bug in the callback, not in the scope
+// being torn down. Reported rather than swallowed, and rather than
+// taking the rest of the teardown with it.
+function reportCleanupError(error) {
+  if (typeof console !== 'undefined') {
+    console.error('Azox: an onCleanup callback threw', error);
+  }
+}
 // Stops an effect permanently. Control-flow blocks use this to clean
 // up the effects belonging to content they are about to remove;
 // without it, every list item ever rendered would stay subscribed.
 export function dispose(effectFn) {
-  if (effectFn) unsubscribe(effectFn);
+  if (!effectFn) return;
+  // Marked before the walk, so an onMount microtask that has not run
+  // yet knows its scope is gone and skips its setup.
+  markDisposed(effectFn);
+  unsubscribe(effectFn);
+}
+function markDisposed(effectFn) {
+  effectFn.disposed = true;
+  for (const child of effectFn.children) markDisposed(child);
 }
 export function computed(fn) {

package/core/renderer/renderToHtml.js CHANGED Viewed

@@ -45,8 +45,26 @@ function renderNode(node, scope, outer, modules = {}) {
   const attrs = Object.entries(node.attrs)
     .filter(([key]) => !key.startsWith('on:'))
     .map(([key, attr]) => {
-      const value = attr.kind === 'static' ? attr.value : String(evalExpr(attr.expr, scope));
-      return ` ${key}="${escapeHtml(value)}"`;
+      // bind:value={draft} renders as the plain attribute, so the input
+      // arrives holding its value rather than showing "bind:value" in
+      // the markup and filling in once scripts run.
+      //
+      // A binding names the signal rather than calling it — that is what
+      // lets it write back — so it has to be read here.
+      const bound = key.startsWith('bind:');
+      const name = bound ? key.slice(5) : key;
+      const raw = attr.kind === 'static'
+        ? attr.value
+        : readAttrValue(attr.expr, scope, bound);
+      // A checkbox is checked by the attribute being present at all, so
+      // a falsy value must omit it rather than render checked="false".
+      if (name === 'checked' || name === 'selected') {
+        return raw ? ` ${name}` : '';
+      }
+      return ` ${name}="${escapeHtml(String(raw ?? ''))}"`;
     })
     .join('');
@@ -111,6 +129,13 @@ function renderIf(node, scope, outer, modules = {}) {
   return branch.map((child) => renderNode(child, scope, outer, modules)).join('');
 }
+// Reads an attribute expression. A bound one names a signal, so it is
+// called; anything else is evaluated as written.
+function readAttrValue(expr, scope, bound) {
+  const value = evalExpr(expr, scope);
+  return bound && typeof value === 'function' ? value() : value;
+}
 // Three kinds of text, three rules:
 //   static  — markup the author wrote, so an entity they typed
 //             (&lt;) is meant to stay an entity. Passed through.

package/core/renderer/serverScope.js CHANGED Viewed

@@ -28,6 +28,16 @@ export function serverComputed(fn) {
   return () => fn();
 }
+// Server rendering produces a string: there is no DOM to mount into,
+// and nothing is ever removed, so both hooks do nothing here. The real
+// ones take over in the browser.
+//
+// They still have to exist, or a component that uses them fails the
+// build with "onMount is not defined" — the page would be unbuildable
+// rather than merely non-reactive on the server.
+export function serverOnMount() {}
+export function serverOnCleanup() {}
 // Every top-level binding the script introduces, so they can all be
 // handed to the markup. Function and class declarations count too — a
 // component may well define a helper the template calls.
@@ -75,6 +85,8 @@ export function evaluateScript(body, params = [], args = [], modules = {}, extra
   const fn = new Function(
     'signal',
     'computed',
+    'onMount',
+    'onCleanup',
     ...imported,
     ...extraNames,
     ...params,
@@ -84,6 +96,8 @@ export function evaluateScript(body, params = [], args = [], modules = {}, extra
   const declared = fn(
     serverSignal,
     serverComputed,
+    serverOnMount,
+    serverOnCleanup,
     ...imported.map((n) => modules[n]),
     ...extraNames.map((n) => extras[n]),
     ...args

package/package.json CHANGED Viewed

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