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

azoxjs 1.0.1 → 1.2.0

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 (12) hide show

package/README.md +1 -1
package/core/build.js +30 -2
package/core/compiler/compileToJs.js +39 -6
package/core/compiler/index.d.ts +41 -0
package/core/compiler/parser.js +38 -6
package/core/compiler/resolveComponents.js +67 -7
package/core/compiler/scopeStyles.js +151 -0
package/core/index.d.ts +41 -0
package/core/reactivity/signal.d.ts +88 -0
package/core/renderer/serverScope.js +102 -4
package/core/router/navigate.js +25 -2
package/package.json +17 -7

package/README.md CHANGED Viewed

@@ -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.0.1). The template syntax, the reactivity exports
+> Status: stable (v1.2.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/build.js CHANGED Viewed

@@ -132,7 +132,18 @@ export function buildRoute(projectDir, route, { transformHtml } = {}) {
   // A component's <head> block is merged in behind the page's own, so
   // a layout can carry the stylesheet and fonts every page needs while
   // the page keeps the last word on its title and description.
-  const head = mergeHeads(ast.head, ast.componentHeads ?? []);
+  // A component's scoped CSS is plain stylesheet text by this point,
+  // with every selector already rewritten to require its scope
+  // attribute. One <style> carries all of them, so a page makes no
+  // extra request for styles that are only a few lines each.
+  // A page's own <style> is global: it has no caller to be scoped
+  // against, and `body { … }` in a page should mean what it says.
+  // Without this it was extracted by the parser and then silently
+  // dropped, which is worse than the error it used to raise.
+  const scoped = [ast.style, ...(ast.componentStyles ?? [])].filter(Boolean);
+  const styleTag = scoped.length ? `<style>\n${scoped.join('\n')}\n</style>` : '';
+  const head = mergeHeads(ast.head, [...(ast.componentHeads ?? []), styleTag].filter(Boolean));
   let document = wrapDocument(html, projectTitle(projectDir), head, {
     routerSrc: router ? `${route.assetPrefix}${ROUTER_FILENAME}` : null,
@@ -337,6 +348,17 @@ function removeStaleOutput(projectDir, results, assets = []) {
 // Everything in public/ is copied to the build root untouched, so a
 // stylesheet, font or image is referenced by the same path in source
 // and in the built site: public/style.css -> /style.css.
+// Files an editor or OS leaves behind, which should not be published.
+//
+// Every dotfile used to be skipped, which also dropped the ones a static
+// host needs: .nojekyll tells GitHub Pages not to run Jekyll over the
+// output, and .well-known/ is how a domain or certificate is verified.
+const EDITOR_JUNK = new Set(['.DS_Store', 'Thumbs.db', '.git', 'node_modules']);
+function isEditorJunk(name) {
+  return EDITOR_JUNK.has(name);
+}
 export function copyPublicAssets(projectDir) {
   const publicDir = resolve(projectDir, PUBLIC_DIR);
   if (!existsSync(publicDir)) return [];
@@ -346,7 +368,7 @@ export function copyPublicAssets(projectDir) {
   const walk = (dir, relativeDir) => {
     for (const entry of readdirSync(dir, { withFileTypes: true })) {
-      if (entry.name.startsWith('.')) continue;
+      if (isEditorJunk(entry.name)) continue;
       const from = join(dir, entry.name);
       const to = join(buildRoot, relativeDir, entry.name);
@@ -589,6 +611,12 @@ function uniqueTagName(line) {
   const meta = line.match(/^<meta\s[^>]*name=["']([^"']+)["']/i);
   if (meta) return `meta:${meta[1].toLowerCase()}`;
+  // Open Graph and Twitter cards key on `property`, not `name`. Without
+  // this a shared default and a page's own tag both shipped, and a
+  // scraper takes whichever it sees first.
+  const property = line.match(/^<meta\s[^>]*property=["']([^"']+)["']/i);
+  if (property) return `meta:${property[1].toLowerCase()}`;
   return null;
 }

package/core/compiler/compileToJs.js CHANGED Viewed

@@ -10,6 +10,14 @@
 let uid = 0;
 const nextId = () => `_el${uid++}`;
+// 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.
+//
+// <a> and <script> exist in both languages; they are left as HTML,
+// which is what they almost always are on a page.
+const SVG_TAGS = new Set(['svg']);
 // 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.
@@ -375,15 +383,31 @@ function hydrateBlock() {
   return `
 // Hydrate: the SSR markup is already on the page, so clear it and
 // mount the reactive version in its place.
+//
+// Everything inside the root is replaced, so a listener another script
+// attached to server-rendered markup is discarded with it — a menu
+// button that looked right and did nothing. The event says the DOM has
+// been rebuilt, and is the same one the router dispatches after a
+// navigation, so one listener covers both.
 if (typeof document !== 'undefined') {
   const mount = document.querySelector('[data-azox-root]') ?? document.body;
   mount.innerHTML = '';
   render(mount);
+  // 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.
+  if (typeof CustomEvent === 'function' && typeof document.dispatchEvent === 'function') {
+    document.dispatchEvent(
+      new CustomEvent('azox:navigate', {
+        detail: { url: typeof location !== 'undefined' ? location.href : null, from: null, hydrated: true },
+      })
+    );
+  }
 }
 `;
 }
-function emitNode(node, statements, fallbackVar) {
+function emitNode(node, statements, fallbackVar, inSvg = false) {
   if (!node) return 'null';
   if (node.type === 'text') {
@@ -395,7 +419,7 @@ function emitNode(node, statements, fallbackVar) {
   if (node.type === 'fragment') {
     const varName = nextId();
     statements.push(`const ${varName} = document.createDocumentFragment();`);
-    appendChildren(varName, node.children, statements, fallbackVar);
+    appendChildren(varName, node.children, statements, fallbackVar, inSvg);
     return varName;
   }
@@ -404,13 +428,22 @@ function emitNode(node, statements, fallbackVar) {
   if (node.type === 'scope') return emitScope(node, statements, fallbackVar);
   const varName = nextId();
-  statements.push(`const ${varName} = document.createElement(${JSON.stringify(node.name)});`);
+  // An SVG element needs its namespace. createElement always makes an
+  // 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)});`
+  );
   for (const [key, attr] of Object.entries(node.attrs)) {
     emitAttr(varName, key, attr, statements, node.name);
   }
-  appendChildren(varName, node.children, statements, fallbackVar);
+  appendChildren(varName, node.children, statements, fallbackVar, svg);
   return varName;
 }
@@ -669,9 +702,9 @@ function emitIf(node, statements) {
   );
 }
-function appendChildren(parentVar, children, statements, fallbackVar) {
+function appendChildren(parentVar, children, statements, fallbackVar, inSvg = false) {
   for (const child of children) {
-    const childVar = emitNode(child, statements, fallbackVar);
+    const childVar = emitNode(child, statements, fallbackVar, inSvg);
     if (childVar !== 'null') statements.push(`${parentVar}.appendChild(${childVar});`);
   }
 }

package/core/compiler/index.d.ts ADDED Viewed

@@ -0,0 +1,41 @@
+// Types for `azoxjs/compiler`.
+//
+// The compiler is free of Node built-ins on purpose, so these describe
+// an API that runs in a browser as well as in the build.
+/** A parsed `.azox` file. The node shapes are internal and may change. */
+export interface AzoxAst {
+  /** The `<script>` block, with its imports intact. */
+  script: string;
+  /** The `<head>` block, verbatim. */
+  head: string;
+  /** The markup, as a tree the compiler and renderer both walk. */
+  markup: unknown;
+  /** Component name → the specifier it was imported from. */
+  components: Record<string, string>;
+  /** Prop names the file declared with `props()`. */
+  props: string[];
+  /** Route parameter names the file declared with `params()`. */
+  params: string[];
+}
+export interface CompileOptions {
+  /** How the emitted module should import the runtime. */
+  runtimeSpecifier: string;
+  /**
+   * Rebases the author's relative imports, since compiled output does
+   * not sit beside the source. Called with the file an import was
+   * written in, which differs from the page for a hoisted one.
+   */
+  rewriteImports?: (script: string, sourcePath?: string) => string;
+  /** Values the build resolved, inlined instead of imported. */
+  inlineModules?: Record<string, unknown>;
+  /** Resolved parameters for one page of a dynamic route. */
+  routeParams?: Record<string, string> | null;
+}
+/** Parses a `.azox` file. Throws on malformed markup, naming the tag. */
+export declare function parseAzox(source: string): AzoxAst;
+/** Compiles a parsed file into a JavaScript module, as a string. */
+export declare function compileToModule(ast: AzoxAst, options: CompileOptions): string;

package/core/compiler/parser.js CHANGED Viewed

@@ -16,19 +16,40 @@ export class ParseError extends BuildError {}
 const isComponentName = (name) => /^[A-Z]/.test(name);
 export function parseAzox(source) {
-  const scriptMatch = source.match(/<script>([\s\S]*?)<\/script>/);
+  // <script>, <head> and <style> are pulled out of the source before
+  // anything else looks at it. A literal <text> block may contain those
+  // very tags — documenting them requires it — so the spans are blanked
+  // first, and only what is left is searched. Without this, a code
+  // sample showing a <style> block was eaten as the page's own CSS.
+  const searchable = blankTextBlocks(source);
+  const scriptMatch = searchable.match(/<script>([\s\S]*?)<\/script>/);
   const script = scriptMatch ? scriptMatch[1].trim() : '';
   // An optional <head> block is copied into the document head
   // verbatim: stylesheets, meta tags, fonts. It is markup for the
   // document, not for the page body, so it skips the AST entirely.
-  const headMatch = source.match(/<head>([\s\S]*?)<\/head>/);
+  const headMatch = searchable.match(/<head>([\s\S]*?)<\/head>/);
   const head = headMatch ? headMatch[1].trim() : '';
-  const template = source
-    .replace(/<script>[\s\S]*?<\/script>/, '')
-    .replace(/<head>[\s\S]*?<\/head>/, '')
-    .trim();
+  // A <style> block is CSS, not markup. It has to come out before the
+  // tokeniser runs: left in, its braces are read as {expressions} and a
+  // rule like `.a { color: red }` failed the build with "Unexpected
+  // token ':'" — an error about JavaScript, pointing at a stylesheet.
+  const styleMatch = searchable.match(/<style>([\s\S]*?)<\/style>/);
+  const style = styleMatch ? styleMatch[1].trim() : '';
+  // Cut by position rather than by pattern: replacing on the source
+  // would remove the first match anywhere, including one inside a
+  // <text> block that was deliberately ignored above.
+  const cuts = [scriptMatch, headMatch, styleMatch]
+    .filter(Boolean)
+    .map((match) => [match.index, match.index + match[0].length])
+    .sort((a, b) => b[0] - a[0]);
+  let template = source;
+  for (const [from, to] of cuts) template = template.slice(0, from) + template.slice(to);
+  template = template.trim();
   const tokens = tokenize(template);
@@ -55,6 +76,7 @@ export function parseAzox(source) {
   return {
     script,
     head,
+    style,
     markup,
     components: parseComponentImports(script),
     props: parsePropNames(script),
@@ -64,6 +86,16 @@ export function parseAzox(source) {
   };
 }
+// Replaces the contents of every <text> block with spaces, keeping the
+// length and therefore every offset in the original. What a <text>
+// block holds is literal by definition, so nothing inside one should be
+// mistaken for the page's script, head or style.
+function blankTextBlocks(source) {
+  return source.replace(/<text>[\s\S]*?<\/text>/g, (block) =>
+    `<text>${' '.repeat(Math.max(0, block.length - '<text></text>'.length))}</text>`
+  );
+}
 // Component imports are written as ordinary import statements, so an
 // editor treats them like any other module reference:
 //   import Card from '../components/Card.azox';

package/core/compiler/resolveComponents.js CHANGED Viewed

@@ -7,6 +7,7 @@
 // been written by hand.
 import { parseAzox } from './parser.js';
+import { scopeId, scopeAttribute, scopeCss } from './scopeStyles.js';
 import { BuildError } from '../buildError.js';
 // Extends BuildError so the CLI reports it as a user-facing problem
@@ -20,7 +21,14 @@ export class ComponentError extends BuildError {}
 // `resolver` decides how an import specifier becomes source text, so
 // this runs unchanged against disk or against an in-memory map. See
 // sourceResolver.js.
-export function resolveComponents(ast, sourcePath, resolver, seen = new Set(), heads = null) {
+export function resolveComponents(
+  ast,
+  sourcePath,
+  resolver,
+  seen = new Set(),
+  heads = null,
+  styles = null
+) {
   // Imports from stateful components are hoisted here: they cannot
   // live inside the scope function the compiler builds for each one.
   //
@@ -37,17 +45,31 @@ export function resolveComponents(ast, sourcePath, resolver, seen = new Set(), h
   // now only a page could put one there.
   const collected = heads ?? new Map();
-  const markup = expand(ast.markup, ast, sourcePath, resolver, seen, hoisted, collected);
+  // A component's <style> block is collected the same way and keyed by
+  // the same path, so a component used twice contributes its CSS once.
+  const collectedStyles = styles ?? new Map();
+  const markup = expand(
+    ast.markup,
+    ast,
+    sourcePath,
+    resolver,
+    seen,
+    hoisted,
+    collected,
+    collectedStyles
+  );
   return {
     ...ast,
     markup,
     componentImports: [...hoisted.values()],
     componentHeads: [...collected.values()],
+    componentStyles: [...collectedStyles.values()],
   };
 }
-function expand(node, ast, sourcePath, resolver, seen, hoisted, heads) {
+function expand(node, ast, sourcePath, resolver, seen, hoisted, heads, styles) {
   if (!node || node.type === 'text') return node;
   // <if> keeps its children in two branches rather than in `children`,
@@ -57,16 +79,16 @@ function expand(node, ast, sourcePath, resolver, seen, hoisted, heads) {
     return {
       ...node,
       then: node.then.map((child) =>
-        expand(child, ast, sourcePath, resolver, seen, hoisted, heads)
+        expand(child, ast, sourcePath, resolver, seen, hoisted, heads, styles)
       ),
       otherwise: node.otherwise.map((child) =>
-        expand(child, ast, sourcePath, resolver, seen, hoisted, heads)
+        expand(child, ast, sourcePath, resolver, seen, hoisted, heads, styles)
       ),
     };
   }
   const children = (node.children ?? []).map((child) =>
-    expand(child, ast, sourcePath, resolver, seen, hoisted, heads)
+    expand(child, ast, sourcePath, resolver, seen, hoisted, heads, styles)
   );
   if (node.type !== 'component') {
@@ -83,13 +105,27 @@ function expand(node, ast, sourcePath, resolver, seen, hoisted, heads) {
     component.path,
     resolver,
     new Set([...seen, component.path]),
-    heads
+    heads,
+    styles
   );
   // Keyed by path: a component used on a page twice must not emit its
   // stylesheet link twice.
   if (component.ast.head) heads.set(component.path, component.ast.head);
+  // A <style> block scopes to this component: its selectors are
+  // rewritten to require an attribute, and that attribute is put on the
+  // markup below. Both halves key off the same path, so the CSS and the
+  // elements it targets always agree.
+  let scope = null;
+  if (component.ast.style) {
+    scope = scopeId(component.path);
+    styles.set(component.path, scopeCss(component.ast.style, scope));
+  }
+  if (scope) markScope(inner.markup, scopeAttribute(scope));
   const values = propValues(node, component.ast.props);
   const { logic, imports } = componentLogic(component.ast.script);
@@ -160,6 +196,30 @@ function componentLogic(script) {
   return { logic: meaningful.trim() ? body.trim() : null, imports };
 }
+// Puts the scope attribute on every element the component owns.
+//
+// Slot content is skipped: it was written by whoever used the tag, so
+// it belongs to the caller's scope, and a component must not restyle
+// markup it did not write.
+function markScope(node, attribute) {
+  if (!node || node.type === 'text') return;
+  if (node.type === 'fragment' && node.slot) return;
+  if (node.type === 'element' || node.type === 'component') {
+    node.attrs = { ...node.attrs, [attribute]: { kind: 'static', value: '' } };
+  }
+  if (node.type === 'if') {
+    for (const child of [...(node.then ?? []), ...(node.otherwise ?? [])]) {
+      markScope(child, attribute);
+    }
+    return;
+  }
+  for (const child of node.children ?? []) markScope(child, attribute);
+}
 function loadComponent(name, ast, sourcePath, resolver, seen) {
   const specifier = ast.components[name];

package/core/compiler/scopeStyles.js ADDED Viewed

@@ -0,0 +1,151 @@
+// Scoped styles: a component's CSS applies to that component's markup
+// and nothing else.
+//
+// The mechanism is the one most frameworks settled on, because it needs
+// no runtime: every element the component owns gets an attribute, and
+// every selector in its <style> block is rewritten to require that
+// attribute. The result is plain CSS a browser can parse — no shadow
+// DOM, no class-name mangling, nothing to ship.
+//
+// This file has no Node built-ins on purpose: it runs in the browser
+// playground like the rest of the compiler.
+// A short, stable id from the component's path. Not cryptographic — it
+// only has to be stable across builds and unlikely to collide between
+// the files of one project.
+export function scopeId(path) {
+  let hash = 0;
+  for (let i = 0; i < path.length; i++) {
+    hash = (hash * 31 + path.charCodeAt(i)) | 0;
+  }
+  return `a${(hash >>> 0).toString(36).slice(0, 6)}`;
+}
+export const scopeAttribute = (id) => `data-azox-${id}`;
+// At-rules whose body is more CSS, so the selectors inside them need
+// rewriting too — a rule in a @media block still belongs to the
+// component.
+const NESTED_AT_RULES = /^@(media|supports|container|layer)\b/;
+// At-rules that contain no selectors. @keyframes names its steps `from`
+// and `50%`, and scoping those would break the animation.
+const OPAQUE_AT_RULES =
+  /^@(keyframes|-\w+-keyframes|font-face|import|charset|namespace|property)\b/;
+/**
+ * Rewrites every selector in `css` to require the scope attribute.
+ *
+ *   .title { … }        →  .title[data-azox-a1b2c3] { … }
+ *   .a, .b { … }        →  .a[data-azox-a1b2c3], .b[data-azox-a1b2c3] { … }
+ *   :global(.x) { … }   →  .x { … }
+ */
+export function scopeCss(css, id) {
+  return rewriteBlock(css, `[${scopeAttribute(id)}]`);
+}
+function rewriteBlock(css, attr) {
+  let out = '';
+  let i = 0;
+  while (i < css.length) {
+    const open = css.indexOf('{', i);
+    // Trailing text with no rule after it: a stray comment, or nothing.
+    if (open === -1) {
+      out += css.slice(i);
+      break;
+    }
+    const prelude = css.slice(i, open);
+    const close = matchingBrace(css, open);
+    const body = css.slice(open + 1, close);
+    const trimmed = prelude.trim();
+    if (OPAQUE_AT_RULES.test(trimmed)) {
+      // Kept whole: its body is not selectors.
+      out += `${prelude}{${body}}`;
+    } else if (NESTED_AT_RULES.test(trimmed)) {
+      // The condition stays; what is inside it is scoped.
+      out += `${prelude}{${rewriteBlock(body, attr)}}`;
+    } else {
+      out += `${scopeSelectorList(prelude, attr)}{${body}}`;
+    }
+    i = close + 1;
+  }
+  return out;
+}
+// Finds the brace closing the one at `open`, so a @media body is taken
+// whole rather than cut at its first inner rule.
+function matchingBrace(css, open) {
+  let depth = 0;
+  for (let i = open; i < css.length; i++) {
+    if (css[i] === '{') depth++;
+    else if (css[i] === '}' && --depth === 0) return i;
+  }
+  return css.length;
+}
+// A placeholder for a comment while the selector list is split on
+// commas. Printable on purpose: a control character would be invisible
+// in any output that quotes this source.
+const COMMENT_MARK = (n) => `/*__azox${n}__*/`;
+function scopeSelectorList(prelude, attr) {
+  // Comments carry no selectors and may contain commas.
+  const comments = [];
+  const stripped = prelude.replace(/\/\*[\s\S]*?\*\//g, (comment) => {
+    comments.push(comment);
+    return COMMENT_MARK(comments.length - 1);
+  });
+  const scoped = stripped
+    .split(',')
+    .map((selector) => scopeSelector(selector, attr))
+    .join(',');
+  return scoped.replace(/\/\*__azox(\d+)__\*\//g, (_, n) => comments[Number(n)]);
+}
+function scopeSelector(selector, attr) {
+  const trimmed = selector.trim();
+  if (!trimmed) return selector;
+  // An escape hatch for the times a component must reach outside
+  // itself — a body class, or markup it renders into a portal.
+  const global = trimmed.match(/^:global\(([\s\S]*)\)$/);
+  if (global) return selector.replace(trimmed, global[1].trim());
+  const leading = selector.slice(0, selector.length - selector.trimStart().length);
+  const trailing = selector.slice(selector.trimEnd().length);
+  // The attribute goes on the last compound of the selector, so
+  // `.card .title` scopes the element actually being styled rather than
+  // its ancestor. Combinators are left where they are.
+  const parts = trimmed.split(/(\s+|\s*[>+~]\s*)/);
+  for (let i = parts.length - 1; i >= 0; i--) {
+    if (!parts[i].trim() || /^[>+~\s]+$/.test(parts[i])) continue;
+    parts[i] = attachAttribute(parts[i], attr);
+    break;
+  }
+  return leading + parts.join('') + trailing;
+}
+// Placed before any pseudo-element or pseudo-class: `.a[attr]:hover` is
+// what was meant, and `.a:hover[attr]` would not match a browser's
+// reading of it.
+function attachAttribute(compound, attr) {
+  const pseudo = compound.search(/::?[a-z-]/i);
+  if (pseudo === -1) return compound + attr;
+  return compound.slice(0, pseudo) + attr + compound.slice(pseudo);
+}

package/core/index.d.ts ADDED Viewed

@@ -0,0 +1,41 @@
+// Types for `azoxjs`.
+//
+// The whole reactivity surface, plus the compiler and renderer, so this
+// entry point and `azoxjs/reactivity` offer the same thing.
+export {
+  signal,
+  effect,
+  computed,
+  dispose,
+  untracked,
+  onMount,
+  onCleanup,
+  type Signal,
+  type ReadonlySignal,
+  type EffectHandle,
+} from './reactivity/signal.js';
+export { parseAzox, compileToModule } from './compiler/index.js';
+// Imported as well as re-exported: a type-only re-export names the type
+// for consumers but does not put it in scope here, and renderToHtml
+// below refers to it.
+import type { AzoxAst } from './compiler/index.js';
+export type { AzoxAst, CompileOptions } from './compiler/index.js';
+/**
+ * Renders a parsed file to HTML, evaluating its expressions once.
+ *
+ * `scope` holds the bindings the markup reads. `modules` carries what
+ * the file's imports brought in, which the build resolves.
+ */
+export declare function renderToHtml(
+  ast: AzoxAst,
+  scope: Record<string, unknown>,
+  modules?: Record<string, unknown>
+): string;
+/** The version this copy of Azox reports. */
+export declare const VERSION: string;
+export declare const TAGLINE: string;

package/core/reactivity/signal.d.ts ADDED Viewed

@@ -0,0 +1,88 @@
+// Types for `azoxjs/reactivity`.
+//
+// Written by hand rather than generated: the runtime carries no JSDoc,
+// so `tsc --declaration` produces `signal(initialValue: any)`, which
+// type-checks nothing. These describe what the implementation actually
+// guarantees.
+/**
+ * A reactive value. Call it to read — and, inside an `effect`, to
+ * subscribe to it.
+ */
+export interface Signal<T> {
+  (): T;
+  /**
+   * Replaces the value, or derives it from the current one.
+   *
+   * Setting a value equal to the current one (`===`) notifies nobody.
+   *
+   * A function is treated as an updater, so a signal *holding* a
+   * function cannot be replaced by passing it directly — pass
+   * `() => theFunction` instead.
+   */
+  set(next: T | ((previous: T) => T)): void;
+  /** Reads without subscribing, even inside an effect. */
+  peek(): T;
+}
+/** A read-only reactive value. `computed` returns one of these. */
+export interface ReadonlySignal<T> {
+  (): T;
+  peek(): T;
+}
+/**
+ * The handle `effect` returns. Its only public use is `dispose`; its
+ * internals are not part of the API and may change.
+ */
+export interface EffectHandle {
+  (): void;
+}
+/** Creates a reactive value. */
+export declare function signal<T>(initialValue: T): Signal<T>;
+/**
+ * Runs `fn` now, and again whenever a signal it read changes.
+ *
+ * Effects created while another is running belong to it, and are
+ * disposed with it. Use `untracked` to opt out of that ownership.
+ */
+export declare function effect(fn: () => void): EffectHandle;
+/**
+ * A value derived from other signals, recomputed when they change.
+ *
+ * Read-only by design. The runtime object does carry `set`, but the
+ * deriving effect overwrites whatever you assign on its next run, so
+ * it is not offered here.
+ */
+export declare function computed<T>(fn: () => T): ReadonlySignal<T>;
+/**
+ * Runs `fn` with no effect considered active, so anything it creates
+ * is owned by nobody and survives the caller re-running.
+ */
+export declare function untracked<T>(fn: () => T): T;
+/** Stops an effect and everything it created. Ignores null. */
+export declare function dispose(handle: EffectHandle | null | undefined): void;
+/**
+ * Runs once the DOM this scope built is in the document.
+ *
+ * A function returned from `fn` becomes the scope's cleanup, so setup
+ * and teardown can stay together.
+ */
+export declare function onMount(fn: () => void | (() => void)): void;
+/**
+ * Registers work to undo when the surrounding scope goes away: a row
+ * leaving a keyed list, or a branch of an `<if>` no longer taken.
+ *
+ * Called outside any scope it does nothing, which is the case at the
+ * top level of a page — nothing ever removes it.
+ */
+export declare function onCleanup(fn: () => void): void;

package/core/renderer/serverScope.js CHANGED Viewed

@@ -44,18 +44,25 @@ export function serverOnCleanup() {}
 export function declaredNames(script) {
   const names = new Set();
-  for (const match of script.matchAll(/(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=/g)) {
+  // Only what the script declares at its top level. A name declared
+  // inside a callback — `const timer` within onMount, say — is a local
+  // of that function, so returning it from the outer scope throws
+  // "timer is not defined" and takes the whole page down.
+  const topLevel = topLevelSource(script);
+  for (const match of topLevel.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)) {
+  for (const match of topLevel.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)) {
+  for (const match of topLevel.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 match of topLevel.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);
@@ -65,6 +72,97 @@ export function declaredNames(script) {
   return [...names];
 }
+// Blanks out everything nested inside braces, brackets or parentheses,
+// leaving the top-level text with its offsets intact — so a declaration
+// inside a function body is no longer visible to the patterns above.
+//
+// Strings, template literals and comments are blanked too: a brace in
+// one of them would otherwise throw the depth count off.
+function topLevelSource(script) {
+  let out = '';
+  let depth = 0;
+  let i = 0;
+  while (i < script.length) {
+    const c = script[i];
+    const next = script[i + 1];
+    // Comments.
+    if (c === '/' && next === '/') {
+      const end = script.indexOf('\n', i);
+      const stop = end === -1 ? script.length : end;
+      out += ' '.repeat(stop - i);
+      i = stop;
+      continue;
+    }
+    if (c === '/' && next === '*') {
+      const end = script.indexOf('*/', i + 2);
+      const stop = end === -1 ? script.length : end + 2;
+      out += ' '.repeat(stop - i);
+      i = stop;
+      continue;
+    }
+    // Strings and template literals: skipped whole, so braces inside
+    // them do not count. A template's ${...} is skipped with it, which
+    // is fine — nothing is declared at the top level in there.
+    if (c === '"' || c === "'" || c === '`') {
+      const quote = c;
+      let j = i + 1;
+      while (j < script.length) {
+        if (script[j] === '\\') j += 2;
+        else if (script[j] === quote) break;
+        else j++;
+      }
+      const stop = Math.min(j + 1, script.length);
+      out += ' '.repeat(stop - i);
+      i = stop;
+      continue;
+    }
+    // The delimiter itself is kept when it opens at the top level, so
+    // `function f(` and `const { a } =` still match; what is nested
+    // inside is blanked.
+    //
+    // The exception is a destructuring pattern — `const { a, b } = …` —
+    // whose names are the thing being declared, so its contents are
+    // kept even though they sit one level in.
+    if (c === '{' || c === '(' || c === '[') {
+      const destructuring = c === '{' && depth === 0 && /(?:const|let|var)\s*$/.test(out);
+      out += depth === 0 ? c : ' ';
+      depth++;
+      if (destructuring) {
+        const close = script.indexOf('}', i + 1);
+        if (close !== -1) {
+          out += script.slice(i + 1, close + 1);
+          depth--;
+          i = close + 1;
+          continue;
+        }
+      }
+      i++;
+      continue;
+    }
+    if (c === '}' || c === ')' || c === ']') {
+      depth = Math.max(0, depth - 1);
+      out += depth === 0 ? c : ' ';
+      i++;
+      continue;
+    }
+    // Newlines are kept at any depth so line-anchored patterns still
+    // behave; everything else nested is blanked.
+    out += depth === 0 || c === '\n' ? c : ' ';
+    i++;
+  }
+  return out;
+}
 // Evaluates a script body and returns its declarations. `params` and
 // `args` pass a component's props in as arguments.
 //

package/core/router/navigate.js CHANGED Viewed

@@ -128,6 +128,7 @@ async function go(href, { restore = false } = {}) {
   // already holds wherever the reader last asked to go.
   if (location.href !== href) return;
+  const previous = currentUrl;
   const next = new DOMParser().parseFromString(html, 'text/html');
   const incoming = next.querySelector(ROOT);
   const target = document.querySelector(ROOT);
@@ -145,6 +146,18 @@ async function go(href, { restore = false } = {}) {
   currentUrl = href;
   restoreScroll(restore);
+  // The page's own module is re-run above, but a classic <script> that
+  // enhances the markup — syntax highlighting, heading anchors, a
+  // table of contents — is not: it ran once on first load and the
+  // nodes it worked on have just been replaced. This event is how such
+  // a script knows to run again.
+  //
+  // Dispatched after the swap and after the module, so a listener sees
+  // the finished page.
+  document.dispatchEvent(
+    new CustomEvent('azox:navigate', { detail: { url: href, from: previous } })
+  );
 }
 // Brings across anything in the new page's head that this one lacks —
@@ -199,13 +212,23 @@ async function runPageModule(next, pageHref) {
 function restoreScroll(restore) {
   if (restore) return; // The browser restores the position itself.
-  const { hash } = location;
-  const target = hash && document.querySelector(hash);
+  const target = elementForHash(location.hash);
   if (target) target.scrollIntoView();
   else window.scrollTo(0, 0);
 }
+// A hash is not always a selector. A page may use it to carry state —
+// "#template=landing" — and handing that to querySelector throws
+// "not a valid selector", which stopped the scroll being restored at
+// all and put an error in every visitor's console.
+function elementForHash(hash) {
+  if (!hash || hash.length < 2) return null;
+  // getElementById takes an id, not a selector, so nothing can throw.
+  return document.getElementById(decodeURIComponent(hash.slice(1)));
+}
 export function currentHref() {
   return currentUrl;
 }

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "azoxjs",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "Azox Framework — The Sound of Future Web",
   "type": "module",
   "license": "MIT",
@@ -9,17 +9,26 @@
     "type": "git",
     "url": "git+https://github.com/darilpratomo/azox.git"
   },
-  "homepage": "https://github.com/darilpratomo/azox#readme",
+  "homepage": "https://azox.dev",
   "bugs": {
     "url": "https://github.com/darilpratomo/azox/issues"
   },
   "bin": {
-    "azox": "./bin/azox.js"
+    "azox": "bin/azox.js"
   },
   "exports": {
-    ".": "./core/index.js",
-    "./reactivity": "./core/reactivity/signal.js",
-    "./compiler": "./core/compiler/index.js",
+    ".": {
+      "types": "./core/index.d.ts",
+      "default": "./core/index.js"
+    },
+    "./reactivity": {
+      "types": "./core/reactivity/signal.d.ts",
+      "default": "./core/reactivity/signal.js"
+    },
+    "./compiler": {
+      "types": "./core/compiler/index.d.ts",
+      "default": "./core/compiler/index.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -43,5 +52,6 @@
     "compiler",
     "ssr",
     "no-virtual-dom"
-  ]
+  ],
+  "types": "./core/index.d.ts"
 }