azoxjs 0.1.0 → 0.3.0

package/core/dev/watcher.js

@@ -11,7 +11,10 @@ import { join } from 'node:path';
 
 const DEBOUNCE_MS = 40;
 
-export function watchDirectory(dir, onChange, { filter = () => true } = {}) {
+// `recursive: false` watches only the directory itself. The project
+// root holds the build output and node_modules, so sweeping it
+// recursively would rebuild in a loop.
+export function watchDirectory(dir, onChange, { filter = () => true, recursive = true } = {}) {
   const watchers = [];
   let timer = null;
 
@@ -22,6 +25,14 @@ export function watchDirectory(dir, onChange, { filter = () => true } = {}) {
     timer = setTimeout(() => onChange(filename), DEBOUNCE_MS);
   };
 
+  if (!recursive) {
+    watchers.push(watch(dir, (_event, filename) => trigger(filename)));
+    return () => {
+      clearTimeout(timer);
+      for (const watcher of watchers) watcher.close();
+    };
+  }
+
   try {
     watchers.push(watch(dir, { recursive: true }, (_event, filename) => trigger(filename)));
   } catch {

package/core/nodeResolver.js

@@ -0,0 +1,15 @@
+// The filesystem-backed resolver used by the CLI.
+//
+// It lives outside core/compiler/ on purpose: everything under
+// core/compiler/ must stay free of Node built-ins so it can run in a
+// browser. This is the one place that bridges the compiler to disk.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+export function createNodeResolver() {
+  return {
+    resolve: (specifier, fromId) => resolve(dirname(fromId), specifier),
+    read: (id) => (existsSync(id) ? readFileSync(id, 'utf8') : null),
+  };
+}

package/core/reactivity/signal.js

@@ -11,7 +11,12 @@ export function signal(initialValue) {
   const subscribers = new Set();
 
   function read() {
-    if (activeEffect) subscribers.add(activeEffect);
+    if (activeEffect) {
+      subscribers.add(activeEffect);
+      // Remember the link from both ends, so disposing an effect can
+      // remove it from every signal it read.
+      activeEffect.sources.add(subscribers);
+    }
     return value;
   }
 
@@ -29,6 +34,10 @@ export function signal(initialValue) {
 
 export function effect(fn) {
   const wrapped = () => {
+    // Drop last run's subscriptions before re-reading. Without this,
+    // an effect stays subscribed to signals it no longer reads.
+    unsubscribe(wrapped);
+
     const previous = activeEffect;
     activeEffect = wrapped;
     try {
@@ -37,10 +46,36 @@ export function effect(fn) {
       activeEffect = previous;
     }
   };
+
+  wrapped.sources = new Set();
+
+  // Effects created while another effect runs — a control-flow block
+  // rebuilding its body, say — belong to it, so they can be disposed
+  // together when it re-runs.
+  if (activeEffect) activeEffect.children.add(wrapped);
+  wrapped.children = new Set();
+
   wrapped();
   return wrapped;
 }
 
+// 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();
+
+  for (const subscribers of effectFn.sources) subscribers.delete(effectFn);
+  effectFn.sources.clear();
+}
+
+// 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);
+}
+
 export function computed(fn) {
   const derived = signal(undefined);
   effect(() => derived.set(fn()));

package/core/renderer/moduleBindings.js

@@ -0,0 +1,88 @@
+// Parses the import statements in a <script> block so the server can
+// supply what they bring in.
+//
+// The compiler hoists a plain JS import into the emitted module, so
+// the browser loads it natively. Server rendering has no module
+// context — the script runs inside a `new Function` — so the bindings
+// are resolved here and passed in as arguments instead.
+//
+// `azox/reactivity` is the exception: the server supplies its own
+// non-reactive primitives rather than loading the real runtime.
+
+const RUNTIME_SPECIFIERS = new Set(['azox/reactivity', 'azoxjs/reactivity']);
+
+// Matches the import forms a .azox script can use:
+//   import x from '…'              default
+//   import { a, b as c } from '…'  named
+//   import * as ns from '…'        namespace
+//   import '…'                     side effect only
+//
+// A trailing import attribute — `with { type: 'json' }`, which is how
+// a script reads package.json — is matched and ignored; Node applies
+// it when the module is actually loaded.
+const IMPORT_RE =
+  /^[ \t]*import\s+(?:([\s\S]*?)\s+from\s+)?['"]([^'"]+)['"][ \t]*(?:(?:with|assert)\s*\{[^}]*\})?[ \t]*;?[ \t]*$/gm;
+
+// Returns one entry per import that the server must resolve, each
+// naming the specifier and the local bindings it introduces.
+export function parseImports(script) {
+  if (!script) return [];
+
+  const found = [];
+
+  for (const match of script.matchAll(IMPORT_RE)) {
+    const [, clause, specifier] = match;
+
+    if (RUNTIME_SPECIFIERS.has(specifier)) continue;
+    // A .azox import is a component, resolved at build time.
+    if (specifier.endsWith('.azox')) continue;
+    // Side-effect-only import introduces no bindings, and the server
+    // has nothing to bind, so there is nothing to do.
+    if (!clause) continue;
+
+    found.push({ specifier, bindings: parseClause(clause) });
+  }
+
+  return found;
+}
+
+// Turns the text between `import` and `from` into the local names it
+// declares, each paired with the export it comes from. A default
+// import reads the `default` export; a namespace import takes the
+// module object itself.
+function parseClause(clause) {
+  const bindings = [];
+  const text = clause.trim();
+
+  const namespace = text.match(/^\*\s+as\s+([A-Za-z_$][\w$]*)$/);
+  if (namespace) return [{ local: namespace[1], imported: '*' }];
+
+  // A default import may be followed by a named list:
+  //   import def, { a, b } from '…'
+  const braceAt = text.indexOf('{');
+  const head = (braceAt === -1 ? text : text.slice(0, braceAt)).replace(/,\s*$/, '').trim();
+
+  if (head) {
+    const ns = head.match(/^\*\s+as\s+([A-Za-z_$][\w$]*)$/);
+    if (ns) bindings.push({ local: ns[1], imported: '*' });
+    else if (/^[A-Za-z_$][\w$]*$/.test(head)) bindings.push({ local: head, imported: 'default' });
+  }
+
+  if (braceAt !== -1) {
+    const closeAt = text.lastIndexOf('}');
+    const names = text.slice(braceAt + 1, closeAt === -1 ? undefined : closeAt);
+
+    for (const part of names.split(',')) {
+      const entry = part.trim();
+      if (!entry) continue;
+
+      const aliased = entry.match(/^(.+?)\s+as\s+([A-Za-z_$][\w$]*)$/);
+      const imported = (aliased ? aliased[1] : entry).trim();
+      const local = aliased ? aliased[2] : imported;
+
+      if (/^[A-Za-z_$][\w$]*$/.test(local)) bindings.push({ local, imported });
+    }
+  }
+
+  return bindings;
+}

package/core/renderer/renderToHtml.js

@@ -6,27 +6,42 @@
 // top of this markup.
 
 import { BuildError } from '../buildError.js';
+import { VOID_TAGS, escapeHtml } from '../compiler/html.js';
+import { evaluateScript } from './serverScope.js';
 
-const VOID_TAGS = new Set(['br', 'hr', 'img', 'input', 'meta', 'link']);
-
-export function renderToHtml(ast, scope) {
-  return renderNode(ast.markup, scope);
+// `modules` is what the page's and its components' imports brought in,
+// as local name → value. A component's script is evaluated here too,
+// and its imports were hoisted to the page, so the bindings have to be
+// handed down rather than re-resolved — this file has no filesystem
+// access by design.
+export function renderToHtml(ast, scope, modules = {}) {
+  return renderNode(ast.markup, scope, scope, modules);
 }
 
-function renderNode(node, scope) {
+// `outer` is the scope the surrounding markup was written in. It is
+// almost always the same as `scope`; they differ inside a component,
+// where slot content belongs to whoever wrote the tag rather than to
+// the component rendering it.
+function renderNode(node, scope, outer, modules = {}) {
   if (!node) return '';
 
-  // A fragment (from <slot />) contributes only its children.
+  // A fragment contributes only its children. Slot content is the one
+  // place the two scopes come apart.
   if (node.type === 'fragment') {
-    return node.children.map((child) => renderNode(child, scope)).join('');
+    const childScope = node.slot ? outer : scope;
+    return node.children.map((child) => renderNode(child, childScope, outer, modules)).join('');
   }
 
   if (node.type === 'text') {
-    return node.parts
-      .map((part) => (part.kind === 'static' ? escapeHtml(part.value) : escapeHtml(String(evalExpr(part.expr, scope)))))
-      .join('');
+    return node.parts.map((part) => renderTextPart(part, scope)).join('');
   }
 
+  // Control flow is evaluated once here, so the page arrives with its
+  // list already rendered rather than filling in when scripts run.
+  if (node.type === 'each') return renderEach(node, scope, outer, modules);
+  if (node.type === 'if') return renderIf(node, scope, outer, modules);
+  if (node.type === 'scope') return renderScope(node, scope, modules);
+
   const attrs = Object.entries(node.attrs)
     .filter(([key]) => !key.startsWith('on:'))
     .map(([key, attr]) => {
@@ -37,10 +52,78 @@ function renderNode(node, scope) {
 
   if (VOID_TAGS.has(node.name)) return `<${node.name}${attrs}>`;
 
-  const inner = node.children.map((child) => renderNode(child, scope)).join('');
+  const inner = node.children.map((child) => renderNode(child, scope, outer, modules)).join('');
   return `<${node.name}${attrs}>${inner}</${node.name}>`;
 }
 
+// A stateful component runs its script here too, with the caller's
+// prop values bound as arguments, so the server sees the same initial
+// state the browser will build. Its declarations are added to a copy
+// of the scope, so they cannot leak into the surrounding page.
+function renderScope(node, scope, modules = {}) {
+  const args = node.args.map((expr) => evalExpr(expr, scope));
+
+  let declared;
+  try {
+    // A component's own imports were hoisted to the page and loaded
+    // there, so they are passed in rather than resolved again.
+    declared = evaluateScript(node.script, node.params, args, modules);
+  } catch (error) {
+    throw new BuildError(`in <${node.name}>: ${error.message}`);
+  }
+
+  const inner = { ...scope, ...declared };
+  for (const [i, param] of node.params.entries()) inner[param] = args[i];
+
+  // `scope` is passed on as the outer one: slot content nested in
+  // this component was written by whoever used the tag.
+  return node.children.map((child) => renderNode(child, inner, scope, modules)).join('');
+}
+
+// Each iteration renders with the loop variable added to the scope,
+// 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 (typeof items[Symbol.iterator] !== 'function') {
+    throw new BuildError(
+      `<each item={${node.expr}}> needs something iterable, such as an array — got ${typeof items}`
+    );
+  }
+
+  let html = '';
+  let index = 0;
+
+  for (const item of items) {
+    const inner = { ...scope, [node.alias]: item };
+    if (node.index) inner[node.index] = index;
+
+    html += node.children.map((child) => renderNode(child, inner, outer, modules)).join('');
+    index++;
+  }
+
+  return 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('');
+}
+
+// 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.
+//   literal — content of a <text> block, meant to appear exactly as
+//             written, so it is escaped into entities.
+//   expr    — data, which is where untrusted content could enter.
+//             Always escaped.
+function renderTextPart(part, scope) {
+  if (part.kind === 'static') return part.value;
+  if (part.kind === 'literal') return escapeHtml(part.value);
+  return escapeHtml(String(evalExpr(part.expr, scope)));
+}
+
 function evalExpr(expr, scope) {
   const keys = Object.keys(scope);
 
@@ -58,10 +141,3 @@ function evalExpr(expr, scope) {
   }
 }
 
-function escapeHtml(str) {
-  return str
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;');
-}

package/core/renderer/serverScope.js

@@ -0,0 +1,95 @@
+// Runs a page's or a component's <script> block during server
+// rendering, and hands back the bindings it declared.
+//
+// The script is trusted project source, not user input — the same
+// assumption any template engine's server step makes. It must never
+// be pointed at .azox content submitted by someone else.
+//
+// One implementation, used by both the build and the renderer: two
+// copies drifted apart once already, leaving pages able to use
+// `computed` while components could not.
+
+// Server rendering needs only the current value, not reactivity, so
+// a signal here is a plain box. The real runtime takes over in the
+// browser.
+export function serverSignal(initial) {
+  let value = initial;
+
+  const read = () => value;
+  read.set = (next) => {
+    value = typeof next === 'function' ? next(value) : next;
+  };
+  read.peek = () => value;
+
+  return read;
+}
+
+export function serverComputed(fn) {
+  return () => fn();
+}
+
+// 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.
+export function declaredNames(script) {
+  const names = new Set();
+
+  for (const match of script.matchAll(/(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=/g)) {
+    names.add(match[1]);
+  }
+  for (const match of script.matchAll(/function\s+([A-Za-z_$][\w$]*)\s*\(/g)) {
+    names.add(match[1]);
+  }
+  for (const match of script.matchAll(/class\s+([A-Za-z_$][\w$]*)/g)) {
+    names.add(match[1]);
+  }
+
+  // Destructured declarations: const { a, b: c, d = 1 } = …
+  for (const match of script.matchAll(/(?:const|let|var)\s*\{([^}]*)\}\s*=/g)) {
+    for (const part of match[1].split(',')) {
+      const name = part.split(':').pop().split('=')[0].trim();
+      if (/^[A-Za-z_$][\w$]*$/.test(name)) names.add(name);
+    }
+  }
+
+  return [...names];
+}
+
+// Evaluates a script body and returns its declarations. `params` and
+// `args` pass a component's props in as arguments.
+//
+// `extras` are further bindings the caller supplies by name — `params`
+// for a dynamic page, and `routes` while its route list is collected.
+//
+// `modules` carries what the script's imports brought in, as local
+// name → value. The body runs inside a `new Function`, which cannot
+// use `import`, so the bindings arrive as arguments instead — the
+// build resolves them, since loading a module needs the filesystem
+// and this file has to stay usable in a browser.
+export function evaluateScript(body, params = [], args = [], modules = {}, extras = {}) {
+  const imported = Object.keys(modules);
+  const extraNames = Object.keys(extras);
+  const reserved = new Set([...imported, ...extraNames]);
+  const names = declaredNames(body).filter((name) => !reserved.has(name));
+
+  const fn = new Function(
+    'signal',
+    'computed',
+    ...imported,
+    ...extraNames,
+    ...params,
+    `${body}\nreturn { ${names.join(', ')} };`
+  );
+
+  const declared = fn(
+    serverSignal,
+    serverComputed,
+    ...imported.map((n) => modules[n]),
+    ...extraNames.map((n) => extras[n]),
+    ...args
+  );
+
+  // An imported binding is in scope for the markup too, the same way
+  // it is in the compiled module.
+  return { ...modules, ...declared };
+}

package/core/router/navigate.js

@@ -0,0 +1,211 @@
+// Client-side navigation for Azox.
+//
+// Swaps one page's markup for another without a full reload, and
+// keeps the browser's history in step. Deliberately small: there is
+// no route table, no matching, and no component tree to keep alive —
+// the server already produced every page, so navigating is fetching
+// the next one and putting it in place.
+//
+// Everything here is an enhancement over links that already work.
+// With the script absent or broken, an <a> is still an <a>.
+
+const ROOT = '[data-azox-root]';
+const PREFETCH_LIMIT = 24;
+
+// Documents already fetched, keyed by URL. Bounded so a long session
+// browsing a large site cannot grow it without limit.
+const cache = new Map();
+
+let currentUrl = location.href;
+
+/** Starts intercepting navigation. Safe to call more than once. */
+export function startRouter(options = {}) {
+  if (typeof document === 'undefined' || document.__azoxRouter) return;
+  document.__azoxRouter = true;
+
+  const prefetch = options.prefetch !== false;
+
+  document.addEventListener('click', onClick);
+  window.addEventListener('popstate', onPopState);
+
+  if (prefetch) {
+    document.addEventListener('pointerenter', onPointerEnter, { capture: true });
+    document.addEventListener('touchstart', onPointerEnter, { capture: true, passive: true });
+  }
+}
+
+function onClick(event) {
+  // Leave anything the browser should handle itself: modified clicks
+  // open in a new tab or window, and a non-primary button is not a
+  // plain navigation.
+  if (event.defaultPrevented || event.button !== 0) return;
+  if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+
+  const link = event.target.closest?.('a');
+  const url = navigableUrl(link);
+  if (!url) return;
+
+  event.preventDefault();
+
+  // Clicking the current page's own link should not push a duplicate
+  // entry onto the history stack.
+  if (url.href === location.href) return;
+
+  history.pushState(null, '', url.href);
+  go(url.href);
+}
+
+function onPopState() {
+  go(location.href, { restore: true });
+}
+
+function onPointerEnter(event) {
+  const link = event.target?.closest?.('a');
+  const url = navigableUrl(link);
+  if (url) load(url.href);
+}
+
+// Decides whether a link is one this router should handle. Anything
+// off-site, downloadable, or explicitly opted out is left alone.
+function navigableUrl(link) {
+  if (!link || !link.href) return null;
+  if (link.target && link.target !== '_self') return null;
+  if (link.hasAttribute('download') || link.hasAttribute('data-no-router')) return null;
+  if (link.getAttribute('rel')?.includes('external')) return null;
+
+  let url;
+  try {
+    url = new URL(link.href, location.href);
+  } catch {
+    return null;
+  }
+
+  if (url.origin !== location.origin) return null;
+
+  // A link to a different spot on the same page is the browser's job.
+  if (url.pathname === location.pathname && url.hash) return null;
+
+  return url;
+}
+
+function load(href) {
+  if (cache.has(href)) return cache.get(href);
+
+  const pending = fetch(href, { headers: { Accept: 'text/html' } })
+    .then((response) => {
+      if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);
+      return response.text();
+    })
+    .catch((error) => {
+      // A failed prefetch must not poison the cache: the click that
+      // follows should be able to try again, and fall back to a real
+      // navigation if it fails too.
+      cache.delete(href);
+      throw error;
+    });
+
+  if (cache.size >= PREFETCH_LIMIT) cache.delete(cache.keys().next().value);
+  cache.set(href, pending);
+
+  return pending;
+}
+
+async function go(href, { restore = false } = {}) {
+  let html;
+
+  try {
+    html = await load(href);
+  } catch {
+    // Anything unexpected — a network failure, a 404, a redirect to
+    // another origin — hands control back to the browser rather than
+    // leaving the reader on a page that did not change.
+    location.href = href;
+    return;
+  }
+
+  // A second navigation may have started while this one was in
+  // flight. Comparing against the address bar is enough to tell: it
+  // already holds wherever the reader last asked to go.
+  if (location.href !== href) return;
+
+  const next = new DOMParser().parseFromString(html, 'text/html');
+  const incoming = next.querySelector(ROOT);
+  const target = document.querySelector(ROOT);
+
+  if (!incoming || !target) {
+    location.href = href;
+    return;
+  }
+
+  document.title = next.title;
+  syncHead(next);
+  target.replaceWith(incoming.cloneNode(true));
+
+  await runPageModule(next, href);
+
+  currentUrl = href;
+  restoreScroll(restore);
+}
+
+// Brings across anything in the new page's head that this one lacks —
+// its description, its canonical link — and drops what it no longer
+// needs. Stylesheets are left in place: they are shared across pages,
+// and removing one mid-navigation causes a visible flash.
+function syncHead(next) {
+  const selector = 'meta[name], link[rel="canonical"]';
+  const keep = new Set();
+
+  for (const node of next.head.querySelectorAll(selector)) {
+    const key = node.outerHTML;
+    keep.add(key);
+
+    const existing = [...document.head.querySelectorAll(selector)].find(
+      (candidate) => candidate.outerHTML === key
+    );
+    if (!existing) document.head.append(node.cloneNode(true));
+  }
+
+  for (const node of document.head.querySelectorAll(selector)) {
+    if (!keep.has(node.outerHTML)) node.remove();
+  }
+}
+
+// Each page ships its own module of bindings. Importing it runs its
+// hydration, which is what makes the newly inserted markup live.
+//
+// `pageHref` matters: a page's module is referenced relatively, and
+// resolving that against the address bar is wrong. Every route is a
+// directory, so "/about" and "/about/" resolve "./page.client.js"
+// differently — the first lands on the *root* page's module, which
+// then hydrates the page you just navigated away from back into place.
+async function runPageModule(next, pageHref) {
+  const script = next.querySelector('script[type="module"][src]');
+  if (!script) return;
+
+  const base = pageHref.endsWith('/') ? pageHref : `${pageHref}/`;
+  const url = new URL(script.getAttribute('src'), base).href;
+
+  try {
+    // The cache-busting parameter matters: a module is evaluated once
+    // per URL, so returning to a page would otherwise insert markup
+    // that nothing ever binds to.
+    await import(/* @vite-ignore */ `${url}${url.includes('?') ? '&' : '?'}azox=${Date.now()}`);
+  } catch {
+    // A page whose bindings fail still shows its server-rendered
+    // markup, which is better than replacing it with nothing.
+  }
+}
+
+function restoreScroll(restore) {
+  if (restore) return; // The browser restores the position itself.
+
+  const { hash } = location;
+  const target = hash && document.querySelector(hash);
+
+  if (target) target.scrollIntoView();
+  else window.scrollTo(0, 0);
+}
+
+export function currentHref() {
+  return currentUrl;
+}