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

azoxjs 0.1.0 → 0.3.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 (21) hide show

package/README.md +188 -5
package/core/build.js +472 -46
package/core/cli/router.js +28 -0
package/core/commands/compile.js +5 -1
package/core/commands/create.js +44 -10
package/core/commands/dev.js +42 -18
package/core/commands/doctor.js +6 -1
package/core/compiler/compileToJs.js +529 -36
package/core/compiler/html.js +28 -0
package/core/compiler/parser.js +219 -9
package/core/compiler/resolveComponents.js +227 -39
package/core/compiler/sourceResolver.js +42 -0
package/core/dev/watcher.js +12 -1
package/core/nodeResolver.js +15 -0
package/core/reactivity/signal.js +36 -1
package/core/renderer/moduleBindings.js +88 -0
package/core/renderer/renderToHtml.js +94 -18
package/core/renderer/serverScope.js +95 -0
package/core/router/navigate.js +211 -0
package/core/routes.js +44 -0
package/package.json +1 -1

package/core/compiler/parser.js CHANGED Viewed

@@ -4,13 +4,12 @@
 // job is narrow — turn markup + bindings into signal-driven DOM ops.
 import { BuildError } from '../buildError.js';
+import { VOID_TAGS } from './html.js';
 // Extends BuildError so a malformed page is reported as the user's
 // problem, not as an Azox crash.
 export class ParseError extends BuildError {}
-const VOID_TAGS = new Set(['br', 'hr', 'img', 'input', 'meta', 'link']);
 // A capitalised tag is a component, the way a lowercase one is an
 // HTML element. That keeps the distinction visible in the markup
 // itself, with no separate registration step.
@@ -19,7 +18,17 @@ const isComponentName = (name) => /^[A-Z]/.test(name);
 export function parseAzox(source) {
   const scriptMatch = source.match(/<script>([\s\S]*?)<\/script>/);
   const script = scriptMatch ? scriptMatch[1].trim() : '';
-  const template = source.replace(/<script>[\s\S]*?<\/script>/, '').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 head = headMatch ? headMatch[1].trim() : '';
+  const template = source
+    .replace(/<script>[\s\S]*?<\/script>/, '')
+    .replace(/<head>[\s\S]*?<\/head>/, '')
+    .trim();
   const tokens = tokenize(template);
   const { node, rest } = parseNode(tokens);
@@ -29,9 +38,13 @@ export function parseAzox(source) {
   return {
     script,
+    head,
     markup: node,
     components: parseComponentImports(script),
     props: parsePropNames(script),
+    // A dynamic page destructures its route parameters the same way a
+    // component destructures its props.
+    params: parseParamNames(script),
   };
 }
@@ -53,6 +66,18 @@ function parseComponentImports(script) {
 // `const { title, count } = props();` declares what a component
 // accepts. Declaring them explicitly lets the compiler reject a
 // caller that passes something the component never asked for.
+// `const { slug } = params()` names the route parameters the page
+// reads, mirroring how props() declares a component's inputs.
+function parseParamNames(script) {
+  const match = script.match(/const\s*\{([^}]*)\}\s*=\s*params\(\)/);
+  if (!match) return [];
+  return match[1]
+    .split(',')
+    .map((name) => name.trim())
+    .filter(Boolean);
+}
 function parsePropNames(script) {
   const match = script.match(/const\s*\{([^}]*)\}\s*=\s*props\(\)/);
   if (!match) return [];
@@ -69,6 +94,29 @@ function tokenize(html) {
   while (i < html.length) {
     if (html[i] === '<') {
+      // An HTML comment is skipped outright. Treating it as a tag
+      // would fail on the "--" and report a confusing error about an
+      // element that was never written.
+      if (html.startsWith('<!--', i)) {
+        const close = html.indexOf('-->', i);
+        if (close === -1) throw new ParseError('Azox parse error: a comment is never closed');
+        i = close + '-->'.length;
+        continue;
+      }
+      // <text> holds literal content: no tags, no {interpolation}.
+      // Without it there is no way to show markup or braces on a
+      // page, which documentation for this framework obviously needs.
+      if (html.startsWith('<text>', i)) {
+        const close = html.indexOf('</text>', i);
+        if (close === -1) throw new ParseError('Azox parse error: <text> is never closed');
+        tokens.push({ type: 'raw', value: html.slice(i + '<text>'.length, close) });
+        i = close + '</text>'.length;
+        continue;
+      }
       const isClose = html[i + 1] === '/';
       const end = findTagEnd(html, i);
       const raw = html.slice(i + (isClose ? 2 : 1), end).trim();
@@ -88,14 +136,82 @@ function tokenize(html) {
       }
       i = end + 1;
     } else {
-      const next = html.indexOf('<', i);
-      const text = html.slice(i, next === -1 ? undefined : next);
-      if (text.trim().length) tokens.push({ type: 'text', value: text.trim() });
-      i = next === -1 ? html.length : next;
+      const next = findTextEnd(html, i);
+      const text = html.slice(i, next);
+      const collapsed = collapseWhitespace(text);
+      if (collapsed) tokens.push({ type: 'text', value: collapsed });
+      i = next;
     }
   }
-  return tokens;
+  return trimEdgeWhitespace(tokens);
+}
+// Removes the space that sits immediately inside an element — right
+// after its opening tag, or right before its closing one. Nothing sits
+// on the other side of it to be kept apart, so it is indentation
+// rather than a real space, and keeping it would pad an element's text
+// content for no visible benefit.
+function trimEdgeWhitespace(tokens) {
+  const out = [];
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (token.type !== 'text') {
+      out.push(token);
+      continue;
+    }
+    const before = tokens[i - 1];
+    const after = tokens[i + 1];
+    let value = token.value;
+    if (!before || before.type === 'open') value = value.replace(/^ /, '');
+    if (!after || after.type === 'close') value = value.replace(/ $/, '');
+    if (value) out.push({ ...token, value });
+  }
+  return out;
+}
+// Collapses runs of whitespace to a single space, the way HTML does,
+// and drops text that is only whitespace between block-level tags.
+//
+// Trimming the edges outright — which this used to do — deletes the
+// space in "Read <a>this</a> for more", running the words together.
+// Keeping one space preserves the sentence while still discarding
+// the indentation between elements on their own lines.
+function collapseWhitespace(text) {
+  if (!text.trim()) {
+    // Whitespace containing a newline is layout indentation between
+    // elements; a space on one line is a real space between them.
+    return text.includes('\n') ? '' : ' ';
+  }
+  return text.replace(/\s+/g, ' ');
+}
+// Finds where a run of text ends: at the next tag, but skipping over
+// any {expression} on the way.
+//
+// Stopping at the first "<" is not enough — an expression may contain
+// one, in a comparison like {a() < b()} or a template literal holding
+// markup. Cutting there truncates the expression and reports a
+// confusing error about an unterminated tag.
+function findTextEnd(html, start) {
+  for (let i = start; i < html.length; i++) {
+    if (html[i] === '<') return i;
+    if (html[i] === '{') {
+      // Let the expression scanner find the matching brace; it already
+      // handles nesting and strings.
+      i = findExpressionEnd(html, i, 'an interpolated {expression}');
+    }
+  }
+  return html.length;
 }
 // Finds the ">" that actually closes a tag, ignoring any ">" inside
@@ -252,20 +368,111 @@ function findExpressionEnd(source, start, describe) {
   throw new ParseError(`Azox parse error: ${describe} is never closed`);
 }
+// <each> and <if> are control flow rather than markup, so they become
+// their own node types. Everything else is an element or a component.
+function nodeTypeFor(name) {
+  if (name === 'each') return 'each';
+  if (name === 'if') return 'if';
+  if (name === 'else') return 'else';
+  return isComponentName(name) ? 'component' : 'element';
+}
+// <each item={list()} as="thing"> — `as` names the loop variable so
+// the body can refer to it, the way a parameter names an argument.
+function buildEach(attrs, children) {
+  const list = attrs.item ?? attrs.of;
+  if (!list || list.kind !== 'expr') {
+    throw new ParseError(
+      'Azox parse error: <each> needs item={...} — for example <each item={todos()} as="todo">'
+    );
+  }
+  const alias = attrs.as;
+  if (!alias || alias.kind !== 'static' || !/^[A-Za-z_$][\w$]*$/.test(alias.value)) {
+    throw new ParseError(
+      'Azox parse error: <each> needs as="name", where name is a plain identifier'
+    );
+  }
+  // An optional index, declared the same way.
+  const indexAttr = attrs.index;
+  const index =
+    indexAttr && indexAttr.kind === 'static' && /^[A-Za-z_$][\w$]*$/.test(indexAttr.value)
+      ? indexAttr.value
+      : null;
+  // An optional key gives each row an identity, so a change to the
+  // list can move and keep rows rather than rebuilding all of them.
+  // It is an expression evaluated per row, so it can read the alias.
+  const keyAttr = attrs.key;
+  if (keyAttr && keyAttr.kind !== 'expr') {
+    throw new ParseError(
+      'Azox parse error: <each> needs key={...} as an expression — for example key={item.id}'
+    );
+  }
+  return {
+    type: 'each',
+    expr: list.expr,
+    alias: alias.value,
+    index,
+    key: keyAttr ? keyAttr.expr : null,
+    children,
+  };
+}
+// <if cond={...}> … <else /> … </if> — the marker splits the children
+// into the two branches.
+function buildIf(attrs, children) {
+  const condition = attrs.cond ?? attrs.when;
+  if (!condition || condition.kind !== 'expr') {
+    throw new ParseError(
+      'Azox parse error: <if> needs cond={...} — for example <if cond={user()}>'
+    );
+  }
+  const splitAt = children.findIndex((child) => child.type === 'else');
+  // A second <else /> has no meaning, and silently rendering it as a
+  // literal tag — which is what happened before — hides the mistake.
+  const markers = children.filter((child) => child.type === 'else').length;
+  if (markers > 1) {
+    throw new ParseError('Azox parse error: <if> may contain only one <else />');
+  }
+  return {
+    type: 'if',
+    expr: condition.expr,
+    then: splitAt === -1 ? children : children.slice(0, splitAt),
+    otherwise: splitAt === -1 ? [] : children.slice(splitAt + 1),
+  };
+}
 function parseNode(tokens) {
   const [token, ...rest] = tokens;
   if (!token) return { node: null, rest: [] };
+  // Literal content from <text>: one static part, never interpolated.
+  if (token.type === 'raw') {
+    return { node: { type: 'text', parts: [{ kind: 'literal', value: token.value }] }, rest };
+  }
   if (token.type === 'text') {
     return { node: { type: 'text', parts: splitInterpolation(token.value) }, rest };
   }
   if (token.type === 'open') {
     const { name, attrs, selfClosing } = token;
-    const type = isComponentName(name) ? 'component' : 'element';
+    const type = nodeTypeFor(name);
     if (selfClosing) {
+      // <else /> is a marker inside <if>, not a node of its own; the
+      // <if> handler below is what gives it meaning.
       return { node: { type, name, attrs, children: [] }, rest };
     }
@@ -283,6 +490,9 @@ function parseNode(tokens) {
     remaining = remaining.slice(1); // drop the matching close tag
+    if (type === 'each') return { node: buildEach(attrs, children), rest: remaining };
+    if (type === 'if') return { node: buildIf(attrs, children), rest: remaining };
     return { node: { type, name, attrs, children }, rest: remaining };
   }

package/core/compiler/resolveComponents.js CHANGED Viewed

@@ -6,9 +6,6 @@
 // of reuse, so the emitted code looks the same as if the markup had
 // been written by hand.
-import { readFileSync, existsSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
 import { parseAzox } from './parser.js';
 import { BuildError } from '../buildError.js';
@@ -19,31 +16,151 @@ export class ComponentError extends BuildError {}
 // Returns the AST with every component reference replaced by that
 // component's markup. The caller's script is untouched: components
 // contribute markup only.
-export function resolveComponents(ast, sourcePath, seen = new Set()) {
-  return { ...ast, markup: expand(ast.markup, ast, sourcePath, seen) };
+//
+// `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) {
+  // Imports from stateful components are hoisted here: they cannot
+  // live inside the scope function the compiler builds for each one.
+  //
+  // Each entry carries the file it was written in. A relative
+  // specifier means something different depending on where it was
+  // written, so the owning path has to travel with the statement —
+  // rebasing a component's import against the page's directory points
+  // it at a file that is not there.
+  const hoisted = new Map();
+  // A component's <head> block is collected the same way, keyed by the
+  // file it came from so the same component used twice contributes
+  // once. A stylesheet link belongs in the document head, and until
+  // now only a page could put one there.
+  const collected = heads ?? new Map();
+  const markup = expand(ast.markup, ast, sourcePath, resolver, seen, hoisted, collected);
+  return {
+    ...ast,
+    markup,
+    componentImports: [...hoisted.values()],
+    componentHeads: [...collected.values()],
+  };
 }
-function expand(node, ast, sourcePath, seen) {
+function expand(node, ast, sourcePath, resolver, seen, hoisted, heads) {
   if (!node || node.type === 'text') return node;
-  const children = (node.children ?? []).map((child) => expand(child, ast, sourcePath, seen));
+  // <if> keeps its children in two branches rather than in `children`,
+  // so walking only `children` would leave components inside a
+  // conditional unresolved — they would reach the output as raw tags.
+  if (node.type === 'if') {
+    return {
+      ...node,
+      then: node.then.map((child) =>
+        expand(child, ast, sourcePath, resolver, seen, hoisted, heads)
+      ),
+      otherwise: node.otherwise.map((child) =>
+        expand(child, ast, sourcePath, resolver, seen, hoisted, heads)
+      ),
+    };
+  }
+  const children = (node.children ?? []).map((child) =>
+    expand(child, ast, sourcePath, resolver, seen, hoisted, heads)
+  );
   if (node.type !== 'component') {
     return { ...node, children };
   }
-  const component = loadComponent(node.name, ast, sourcePath, seen);
+  const component = loadComponent(node.name, ast, sourcePath, resolver, seen);
   validateProps(node, component);
-  validateNoLocalState(node.name, component);
   // The component's own body may reference further components, so
-  // expand it in its own directory against its own imports.
-  const inner = resolveComponents(component.ast, component.path, new Set([...seen, component.path]));
+  // expand it against its own imports and its own location.
+  const inner = resolveComponents(
+    component.ast,
+    component.path,
+    resolver,
+    new Set([...seen, component.path]),
+    heads
+  );
+  // 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);
+  const values = propValues(node, component.ast.props);
+  const { logic, imports } = componentLogic(component.ast.script);
+  // Imports are hoisted whether or not the component has logic: a
+  // component whose script is only an import still has markup that
+  // references what it imported, and dropping the import left that
+  // name undefined.
+  for (const line of imports) {
+    hoisted.set(`${component.path}\u0000${line}`, { statement: line, path: component.path });
+  }
+  // Imports the component's own body pulled up are needed by anything
+  // nested inside it too, and keep the path they were written against.
+  for (const entry of inner.componentImports ?? []) {
+    hoisted.set(`${entry.path}\u0000${entry.statement}`, entry);
+  }
+  // Without logic the component is inlined outright, and its props are
+  // rewritten to the caller's expressions in place.
+  if (!logic) {
+    return substituteProps(inner.markup, values, children);
+  }
+  // With logic the markup gets a scope of its own, so each use has its
+  // own copy of whatever the component declares — two <Counter /> tags
+  // hold two independent counts rather than colliding over one
+  // binding. Props become parameters of that scope, so they are left
+  // as names here rather than being replaced by the caller's
+  // expressions; the values are passed in as arguments instead.
+  const markup = substituteProps(inner.markup, {}, children);
-  return substituteProps(inner.markup, propValues(node, component.ast.props), children);
+  // This is ordinary JavaScript scoping, not a component instance:
+  // nothing about it survives into the runtime.
+  return {
+    type: 'scope',
+    name: node.name,
+    script: logic,
+    params: component.ast.props,
+    args: component.ast.props.map((prop) => values[prop] ?? 'undefined'),
+    children: [markup],
+  };
 }
-function loadComponent(name, ast, sourcePath, seen) {
+// Splits a component's script into the imports it needs and the logic
+// that belongs inside its scope.
+//
+// Imports cannot live inside a function, so they are hoisted to the
+// module and collected on the AST for the compiler to emit. What is
+// left — minus the props() line, which becomes parameters — is the
+// component's own logic. `logic` is null when there is none, which is
+// what lets a purely presentational component stay inlined.
+function componentLogic(script) {
+  if (!script) return { logic: null, imports: [] };
+  const imports = [...script.matchAll(/^\s*(import\s[^;\n]+;?)\s*$/gm)]
+    .map((match) => match[1].trim())
+    // Component imports are resolved at build time and must not reach
+    // the browser as a .azox specifier.
+    .filter((line) => !/\.azox['"]/.test(line));
+  const body = script
+    .replace(/^\s*import\s.+?;?\s*$/gm, '')
+    .replace(/const\s*\{[^}]*\}\s*=\s*props\(\)\s*;?/, '');
+  // Comments alone are not logic.
+  const meaningful = body.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '');
+  return { logic: meaningful.trim() ? body.trim() : null, imports };
+}
+function loadComponent(name, ast, sourcePath, resolver, seen) {
   const specifier = ast.components[name];
   if (!specifier) {
@@ -52,38 +169,19 @@ function loadComponent(name, ast, sourcePath, seen) {
     );
   }
-  const path = resolve(dirname(sourcePath), specifier);
+  const path = resolver.resolve(specifier, sourcePath);
   if (seen.has(path)) {
     throw new ComponentError(`component cycle detected: ${name} eventually renders itself`);
   }
-  if (!existsSync(path)) {
+  const source = resolver.read(path);
+  if (source === null) {
     throw new ComponentError(`<${name}> points at ${specifier}, which does not exist`);
   }
-  return { path, ast: parseAzox(readFileSync(path, 'utf8')) };
-}
-// Components are presentational in this version: they take props and
-// render markup. Because a component is inlined into its caller,
-// state declared inside one would share the caller's scope and could
-// collide with it — so it is rejected outright rather than producing
-// a subtle bug. Lifting the restriction needs per-component scoping,
-// which is a deliberate design step, not an accident.
-function validateNoLocalState(name, component) {
-  const script = component.ast.script;
-  if (!script) return;
-  const withoutImports = script.replace(/^\s*import\s.+?;?\s*$/gm, '');
-  const withoutProps = withoutImports.replace(/const\s*\{[^}]*\}\s*=\s*props\(\)\s*;?/, '');
-  if (withoutProps.trim()) {
-    throw new ComponentError(
-      `<${name}> declares logic beyond props(), which this version does not support. ` +
-        'Components take props and render markup; keep state in the page that uses them.'
-    );
-  }
+  return { path, ast: parseAzox(source) };
 }
 // A caller passing something the component never declared is almost
@@ -147,12 +245,54 @@ function substituteProps(node, values, slotChildren) {
   }
   if (node.type === 'element' && node.name === 'slot') {
-    return { type: 'fragment', children: slotChildren };
+    // Marked as slot content: it was written by the caller, so it
+    // must be rendered against the caller's scope rather than the
+    // component's. Without this a component's own declarations would
+    // shadow — or hide entirely — whatever the caller referenced.
+    return { type: 'fragment', slot: true, children: slotChildren };
+  }
+  // Control flow holds its expression and its children outside the
+  // usual `attrs`/`children` shape, so it needs substituting by hand.
+  // Without this, a component that loops over one of its own props
+  // compiles to an expression referring to a name that does not exist.
+  if (node.type === 'each') {
+    // The list expression is evaluated outside the loop, so it still
+    // sees the props. Only the body is shadowed by the loop variable.
+    const inner = shadow(values, [node.alias, node.index]);
+    return {
+      ...node,
+      expr: rewrite(node.expr, values),
+      children: node.children.map((child) => substituteProps(child, inner, slotChildren)),
+    };
+  }
+  if (node.type === 'if') {
+    return {
+      ...node,
+      expr: rewrite(node.expr, values),
+      then: node.then.map((child) => substituteProps(child, values, slotChildren)),
+      otherwise: node.otherwise.map((child) => substituteProps(child, values, slotChildren)),
+    };
   }
   const attrs = {};
   for (const [key, attr] of Object.entries(node.attrs ?? {})) {
-    attrs[key] = attr.kind === 'expr' ? { ...attr, expr: rewrite(attr.expr, values) } : attr;
+    if (attr.kind !== 'expr' || key.startsWith('on:')) {
+      attrs[key] = attr;
+      continue;
+    }
+    const expr = rewrite(attr.expr, values);
+    // Once the caller's props are substituted in, an expression may
+    // have become entirely constant — `class={current === 'docs' ? …}`
+    // with a literal `current`, for instance. Folding it here means
+    // no effect is created for a value that can never change, and a
+    // page built only from such components stays static.
+    const folded = evaluateConstant(expr);
+    attrs[key] = folded === null ? { ...attr, expr } : { kind: 'static', value: folded };
   }
   return {
@@ -162,6 +302,41 @@ function substituteProps(node, values, slotChildren) {
   };
 }
+// Evaluates an expression that refers to nothing outside itself, and
+// returns the resulting string — or null if it cannot be folded.
+//
+// Deliberately conservative: anything containing an identifier that
+// is not a literal or a keyword is refused, so this can never run a
+// function call, read a signal, or touch anything with a side effect.
+// Only string, number and boolean results are folded, since those are
+// the only ones that render the same at build time as at runtime.
+const FOLDABLE_KEYWORDS = new Set(['true', 'false', 'null', 'undefined']);
+function evaluateConstant(expr) {
+  // Strip strings first, then look for anything identifier-shaped in
+  // what remains.
+  const withoutStrings = expr.replace(/"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'/g, '');
+  const identifiers = withoutStrings.match(/[A-Za-z_$][\w$]*/g) ?? [];
+  if (identifiers.some((name) => !FOLDABLE_KEYWORDS.has(name))) return null;
+  // With no identifiers left, a "(" can only be grouping — there is
+  // nothing available to call. Braces, brackets, semicolons, arrows
+  // and assignment are still refused outright.
+  if (/[{}[\];]|=>/.test(withoutStrings)) return null;
+  if (/(^|[^!=<>])=([^=]|$)/.test(withoutStrings)) return null;
+  try {
+    const value = new Function(`"use strict"; return (${expr});`)();
+    const type = typeof value;
+    if (type === 'string' || type === 'number' || type === 'boolean') return String(value);
+    return null;
+  } catch {
+    return null;
+  }
+}
 // Returns the string a wholly-literal expression represents, or null
 // when the expression is anything the compiler must evaluate.
 function asStringLiteral(expr) {
@@ -175,6 +350,19 @@ function asStringLiteral(expr) {
   }
 }
+// A loop variable shadows a prop of the same name, the way a
+// parameter shadows an outer binding in JavaScript. Removing the
+// shadowed names stops the loop body from being rewritten to the
+// caller's value.
+function shadow(values, names) {
+  const shadowed = names.filter(Boolean);
+  if (!shadowed.some((name) => name in values)) return values;
+  const next = { ...values };
+  for (const name of shadowed) delete next[name];
+  return next;
+}
 // Replaces whole-word prop identifiers. Property access (obj.title)
 // and string contents are left alone.
 function rewrite(expr, values) {

package/core/compiler/sourceResolver.js ADDED Viewed

@@ -0,0 +1,42 @@
+// How the compiler finds the source of an imported component.
+//
+// The compiler itself never touches a filesystem. It asks a resolver
+// to turn an import specifier into an identity and a source string,
+// which lets the same compiler run against files on disk (the CLI)
+// and against an in-memory map (the browser playground) with no
+// duplicated logic.
+//
+// A resolver implements:
+//   resolve(specifier, fromId) -> id      a stable, absolute identity
+//   read(id)                   -> string  the source, or null if absent
+// Joins POSIX-style paths and collapses "." and "..", so the browser
+// resolver behaves like the Node one without importing node:path.
+export function joinPath(base, specifier) {
+  const segments = specifier.startsWith('/')
+    ? specifier.split('/')
+    : [...base.split('/').slice(0, -1), ...specifier.split('/')];
+  const out = [];
+  for (const segment of segments) {
+    if (segment === '' || segment === '.') continue;
+    if (segment === '..') out.pop();
+    else out.push(segment);
+  }
+  return `/${out.join('/')}`;
+}
+// Resolver over a plain object of { "/path/File.azox": "source" }.
+// Used by the playground, and by tests that would rather not touch
+// the filesystem.
+export function createMemoryResolver(files) {
+  const normalised = new Map(
+    Object.entries(files).map(([path, source]) => [path.startsWith('/') ? path : `/${path}`, source])
+  );
+  return {
+    resolve: (specifier, fromId) => joinPath(fromId, specifier),
+    read: (id) => normalised.get(id) ?? null,
+  };
+}