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

azoxjs 0.2.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 (11) hide show

package/README.md +77 -1
package/core/build.js +240 -10
package/core/commands/compile.js +5 -1
package/core/commands/dev.js +10 -1
package/core/compiler/compileToJs.js +24 -1
package/core/compiler/parser.js +15 -0
package/core/compiler/resolveComponents.js +22 -7
package/core/dev/watcher.js +12 -1
package/core/renderer/serverScope.js +15 -3
package/core/routes.js +44 -0
package/package.json +1 -1

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: early development (v0.2.0). APIs are unstable and will
+> Status: early development (v0.3.0). APIs are unstable and will
 > change without notice until v1.0.
 ## Why Azox
@@ -65,6 +65,46 @@ pages/blog/first-post.azox  →  /blog/first-post
 Build one page with `azox compile --page=blog/first-post`, or by its
 URL: `azox compile --page=/blog/first-post`.
+### Dynamic routes
+A bracketed segment in a filename is a parameter, and the file becomes
+a template that builds one page per entry it declares:
+```html
+<!-- pages/blog/[slug].azox -->
+<script>
+  import posts from '../../posts.json' with { type: 'json' };
+  // Which pages to build.
+  routes(posts.map((p) => ({ slug: p.slug })));
+  // The parameters of the page being built.
+  const { slug } = params();
+  const post = posts.find((p) => p.slug === slug);
+</script>
+<article>
+  <h1>{post.title}</h1>
+  <p>{post.body}</p>
+</article>
+```
+```
+posts.json with two entries  →  /blog/hello
+                             →  /blog/second
+```
+`routes()` takes an array of objects, one per page, each supplying
+every parameter the filename asks for. A filename may hold several
+(`pages/[lang]/[slug].azox`), and `params()` returns them all.
+Both are build-time declarations: neither reaches the browser. The
+parameters for each page are compiled into its module as a constant.
+A missing `routes()` call, an entry missing a parameter, a value
+containing a `/`, and two entries producing the same URL are all
+reported as build errors rather than producing a broken site.
 ## Components
 A component is a `.azox` file that declares what it accepts and
@@ -147,6 +187,42 @@ 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.
+## Layouts and the document head
+A component can carry a `<head>` block, so one shared component holds
+the stylesheet, fonts and scripts every page needs:
+```html
+<!-- components/Shell.azox -->
+<head>
+  <link rel="stylesheet" href="/style.css" />
+</head>
+<div class="shell">
+  <header>My site</header>
+  <slot />
+</div>
+```
+```html
+<!-- pages/index.azox -->
+<head>
+  <title>Home — my site</title>
+</head>
+<script>
+  import Shell from '../components/Shell.azox';
+</script>
+<Shell><main>Just this page's content.</main></Shell>
+```
+Blocks are merged with the component's first, so the page has the last
+word. Identical lines are emitted once, and a component used twice
+contributes once. A `<title>` or `<meta name="…">` set by the page
+replaces the component's rather than joining it — a document may hold
+only one of each — so a layout's title is a default, not a conflict.
 ## Loops and conditionals
 Control flow is expressed as tags, so it nests inside markup like

package/core/build.js CHANGED Viewed

@@ -22,7 +22,7 @@ import { renderToHtml } from './renderer/renderToHtml.js';
 import { parseImports } from './renderer/moduleBindings.js';
 import { evaluateScript } from './renderer/serverScope.js';
 import { escapeHtml } from './compiler/html.js';
-import { collectRoutes, findRoute } from './routes.js';
+import { collectRoutes, findRoute, resolveRoute, PAGE_EXTENSION } from './routes.js';
 import { createNodeResolver } from './nodeResolver.js';
 import { ROOT_DIR } from './meta.js';
 import { BuildError } from './buildError.js';
@@ -68,7 +68,11 @@ export function buildRoute(projectDir, route, { transformHtml } = {}) {
   // SSR pass: render initial markup without touching browser DOM APIs.
   let html;
   try {
-    html = renderToHtml(ast, buildServerScope(ast.script, inlineModules), inlineModules);
+    html = renderToHtml(
+      ast,
+      buildServerScope(ast.script, inlineModules, route.params),
+      inlineModules
+    );
   } catch (error) {
     if (!(error instanceof BuildError)) throw error;
     throw new BuildError(`in ${PAGES_DIR}/${name}.azox: ${error.message}`);
@@ -97,6 +101,7 @@ export function buildRoute(projectDir, route, { transformHtml } = {}) {
       rewriteImports: (script, from = sourcePath) =>
         rebaseImports(script, dirname(from), clientPath),
       inlineModules,
+      routeParams: route.params ?? null,
     }),
     runtimeSpecifier
   );
@@ -113,7 +118,12 @@ export function buildRoute(projectDir, route, { transformHtml } = {}) {
     copyFileSync(resolve(ROOT_DIR, 'core/router/navigate.js'), resolve(buildRoot, ROUTER_FILENAME));
   }
-  let document = wrapDocument(html, projectTitle(projectDir), ast.head, {
+  // 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 ?? []);
+  let document = wrapDocument(html, projectTitle(projectDir), head, {
     routerSrc: router ? `${route.assetPrefix}${ROUTER_FILENAME}` : null,
   });
   if (transformHtml) document = transformHtml(document);
@@ -133,13 +143,142 @@ export function buildAll(projectDir, options) {
     );
   }
-  const results = routes.map((route) => buildRoute(projectDir, route, options));
+  const results = expandTemplates(routes).map((route) =>
+    buildRoute(projectDir, route, options)
+  );
   const assets = copyPublicAssets(projectDir);
   removeStaleOutput(projectDir, results, assets);
   return results;
 }
+// Turns each template into the concrete routes it declares, leaving
+// ordinary pages as they are. A template stands in for however many
+// pages its routes() call names, and is never written at its own url.
+function expandTemplates(routes) {
+  const expanded = [];
+  const seen = new Map();
+  for (const route of routes) {
+    if (!route.isTemplate) {
+      expanded.push(route);
+      continue;
+    }
+    for (const values of discoverRoutes(route)) {
+      const resolved = resolveRoute(route, values);
+      // Two entries producing the same url would have one silently
+      // overwrite the other, leaving a page missing with no sign of it.
+      const clash = seen.get(resolved.url);
+      if (clash) {
+        throw new BuildError(
+          `${relative(process.cwd(), route.sourcePath)} declares ${resolved.url} twice — ` +
+            `route parameters must be unique`
+        );
+      }
+      seen.set(resolved.url, route);
+      expanded.push(resolved);
+    }
+  }
+  return expanded;
+}
+// Runs a template's <script> with `routes` bound to a collector, so
+// the page declares its own pages from whatever data it imports.
+//
+// The script runs twice per page in total — once here to discover the
+// list, then once per page to render it. That is the cost of letting
+// the declaration be ordinary JavaScript rather than a separate
+// manifest the author has to keep in step.
+function discoverRoutes(route) {
+  const source = readFileSync(route.sourcePath, 'utf8');
+  const parsed = parseAzox(source);
+  const where = `${PAGES_DIR}/${route.name}${PAGE_EXTENSION}`;
+  if (!/\broutes\s*\(/.test(parsed.script)) {
+    throw new BuildError(
+      `in ${where}: a page with a [parameter] in its name must declare its pages — ` +
+        `add routes([...]) to its <script> block, for example ` +
+        `routes(posts.map((p) => ({ ${route.paramNames[0]}: p.${route.paramNames[0]} })))`
+    );
+  }
+  const collected = [];
+  const body = parsed.script.replace(/^\s*import\s.+?;?\s*$/gm, '');
+  try {
+    evaluateScript(
+      body,
+      [],
+      [],
+      loadModules(parsed.script, route.sourcePath),
+      {
+        routes: (list) => {
+          collected.push(...normaliseRouteList(list, where, route.paramNames));
+          return list;
+        },
+        // Discovery happens before any page exists, so params() has
+        // nothing to report yet. Returning an empty object lets a
+        // script that destructures it run without a special case.
+        params: () => ({}),
+      }
+    );
+  } catch (error) {
+    if (error instanceof BuildError) throw error;
+    throw new BuildError(`in ${where}: failed to work out which pages to build: ${error.message}`);
+  }
+  if (!collected.length) {
+    throw new BuildError(
+      `in ${where}: routes() was called with nothing, so no pages would be built. ` +
+        `If the list can be empty, that is fine — but the build has nothing to write.`
+    );
+  }
+  return collected;
+}
+// Each entry must supply every parameter the filename asks for. A
+// missing one would otherwise land in a url as "undefined".
+function normaliseRouteList(list, where, names) {
+  if (!Array.isArray(list)) {
+    throw new BuildError(
+      `in ${where}: routes() needs an array of objects — got ${typeof list}`
+    );
+  }
+  return list.map((entry, index) => {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+      throw new BuildError(
+        `in ${where}: routes() entry ${index} must be an object like { ${names[0]}: 'value' }`
+      );
+    }
+    for (const name of names) {
+      const value = entry[name];
+      if (value === undefined || value === null || value === '') {
+        throw new BuildError(
+          `in ${where}: routes() entry ${index} is missing "${name}", ` +
+            `which the filename asks for`
+        );
+      }
+      if (String(value).includes('/')) {
+        throw new BuildError(
+          `in ${where}: routes() entry ${index} has "${name}" set to "${value}", ` +
+            `which contains a "/" — a parameter fills one url segment`
+        );
+      }
+    }
+    return entry;
+  });
+}
 // Deletes output belonging to pages that no longer exist. Without
 // this, deleting a page leaves its built copy behind and a deployed
 // site keeps serving it.
@@ -217,13 +356,28 @@ export function copyPublicAssets(projectDir) {
 // Builds a single page by route name or URL.
 export function buildPage(projectDir, pageName, options) {
-  const route = findRoute(listRoutes(projectDir), pageName);
+  const routes = listRoutes(projectDir);
+  const route = findRoute(routes, pageName);
-  if (!route) {
-    throw new BuildError(`page "${PAGES_DIR}/${pageName}.azox" not found in ${projectDir}`);
+  // A template cannot be built at its own url, so naming it builds
+  // every page it declares — which is what the author means by
+  // `azox compile --page=blog/[slug]`.
+  if (route?.isTemplate) {
+    return expandTemplates([route]).map((page) => buildRoute(projectDir, page, options));
   }
-  return buildRoute(projectDir, route, options);
+  if (route) return buildRoute(projectDir, route, options);
+  // Not a file, so it may be one of the pages a template declares.
+  // Expanding them is the only way to know.
+  const generated = findRoute(
+    expandTemplates(routes.filter((candidate) => candidate.isTemplate)),
+    pageName
+  );
+  if (generated) return buildRoute(projectDir, generated, options);
+  throw new BuildError(`page "${PAGES_DIR}/${pageName}.azox" not found in ${projectDir}`);
 }
 // Rewrites the bare specifier a page's own <script> uses to the same
@@ -300,14 +454,21 @@ function projectTitle(projectDir) {
 // evaluate the expressions the template references. The script is
 // trusted project source, not user input — the same assumption any
 // template engine's SSR step makes.
-function buildServerScope(script, modules = {}) {
+function buildServerScope(script, modules = {}, params = null) {
   // Strip imports: the server supplies its own primitives rather than
   // loading the real reactive runtime, and anything else a script
   // imports was resolved by loadModules and is passed in.
   const body = script.replace(/^\s*import\s.+?;?\s*$/gm, '');
+  // A dynamic page reads its own parameters through params(), and its
+  // routes() call has already been answered by discovery — calling it
+  // again here would collect the list a second time to no purpose.
+  const extras = params
+    ? { params: () => params, routes: (list) => list }
+    : {};
   try {
-    return evaluateScript(body, [], [], modules);
+    return evaluateScript(body, [], [], modules, extras);
   } catch (error) {
     if (error instanceof BuildError) throw error;
     throw new BuildError(`failed to evaluate the page's <script> block: ${error.message}`);
@@ -350,6 +511,11 @@ function loadModules(script, sourcePath, componentImports = []) {
     let loaded;
     try {
+      // require caches by resolved path, which is wrong for a build
+      // that runs repeatedly in one process: `azox dev` would keep
+      // serving the data as it was when the server started, so editing
+      // a post changed nothing. Dropping the entry re-reads the file.
+      delete require.cache[require.resolve(specifier)];
       loaded = require(specifier);
     } catch (error) {
       throw new BuildError(`cannot import '${specifier}': ${error.message.split('\n')[0]}`);
@@ -366,6 +532,70 @@ function loadModules(script, sourcePath, componentImports = []) {
 // The client module sits next to the page's index.html, so the src is
 // the same for every route regardless of how deep it is.
+// Combines the <head> blocks a page and its components contributed.
+//
+// Components come first so the page can override them: a <title> or a
+// <meta name="description"> set by a layout is a sensible default, and
+// the page that knows its own subject should win. Identical lines are
+// emitted once, so a layout and a page both asking for the same
+// stylesheet do not produce it twice.
+function mergeHeads(pageHead, componentHeads) {
+  const seen = new Set();
+  const lines = [];
+  // A page's <title> and description replace a component's rather than
+  // appearing alongside: two titles in one document is invalid.
+  const pageTags = uniqueHeadTags(pageHead);
+  for (const block of [...componentHeads, pageHead]) {
+    for (const line of (block ?? '').split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      const key = normaliseHeadLine(trimmed);
+      if (seen.has(key)) continue;
+      // Dropped in favour of the page's own.
+      const tag = uniqueTagName(trimmed);
+      if (tag && block !== pageHead && pageTags.has(tag)) continue;
+      seen.add(key);
+      lines.push(trimmed);
+    }
+  }
+  return lines.join('\n');
+}
+// Tags a document may only hold one of, so a component's must give way
+// to the page's. Keyed by tag name, plus the `name` of a <meta> — two
+// different meta tags are fine, two descriptions are not.
+function uniqueTagName(line) {
+  const title = /^<title[\s>]/i.test(line);
+  if (title) return 'title';
+  const meta = line.match(/^<meta\s[^>]*name=["']([^"']+)["']/i);
+  if (meta) return `meta:${meta[1].toLowerCase()}`;
+  return null;
+}
+function uniqueHeadTags(head) {
+  const names = new Set();
+  for (const line of (head ?? '').split('\n')) {
+    const tag = uniqueTagName(line.trim());
+    if (tag) names.add(tag);
+  }
+  return names;
+}
+// Whitespace inside a tag should not make two identical links differ.
+function normaliseHeadLine(line) {
+  return line.replace(/\s+/g, ' ');
+}
 // 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 } = {}) {

package/core/commands/compile.js CHANGED Viewed

@@ -15,7 +15,11 @@ export function compileCommand({ flags }) {
   const projectDir = process.cwd();
   try {
-    const results = flags.page ? [buildPage(projectDir, flags.page)] : buildAll(projectDir);
+    // Naming a [parameter] template builds every page it declares, so
+    // buildPage may answer with more than one.
+    const results = flags.page
+      ? [buildPage(projectDir, flags.page)].flat()
+      : buildAll(projectDir);
     console.log(BANNER);
     console.log('');

package/core/commands/dev.js CHANGED Viewed

@@ -82,11 +82,20 @@ export async function devCommand({ flags }) {
     // public/ holds stylesheets, fonts and images; any of them
     // changing is worth a reload.
     { dir: resolve(projectDir, PUBLIC_DIR), filter: () => true },
+    // A page can import a .json file for its content, and a dynamic
+    // route builds its pages from one. Editing the data has to rebuild
+    // or the new entry never appears. Not recursive: the project root
+    // also holds the build output, and watching that rebuilds forever.
+    {
+      dir: projectDir,
+      filter: (name) => name.endsWith('.json') && !name.includes('package-lock'),
+      recursive: false,
+    },
   ];
   const stoppers = watched
     .filter(({ dir }) => existsSync(dir))
-    .map(({ dir, filter }) => watchDirectory(dir, onChange, { filter }));
+    .map(({ dir, filter, recursive }) => watchDirectory(dir, onChange, { filter, recursive }));
   const stopWatching = () => {
     for (const stop of stoppers) stop();

package/core/compiler/compileToJs.js CHANGED Viewed

@@ -23,12 +23,20 @@ const nextId = () => `_el${uid++}`;
 //   value, whose import must not reach the browser. A JSON import
 //   points outside the build directory at a file that is never
 //   deployed, so the value is emitted as a constant instead.
-export function compileToModule(ast, { runtimeSpecifier, rewriteImports, inlineModules }) {
+// routeParams: the resolved parameters for this page of a dynamic
+//   route. routes() is a build-time declaration and params() is
+//   answered before the browser is involved, so both are removed from
+//   the emitted module and the values are inlined.
+export function compileToModule(
+  ast,
+  { runtimeSpecifier, rewriteImports, inlineModules, routeParams }
+) {
   uid = 0;
   const statements = [];
   const rootVar = emitNode(ast.markup, statements, 'root');
   let script = dropComponentImports(ast.script);
+  script = resolveRouteDeclarations(script, routeParams);
   if (rewriteImports) script = rewriteImports(script);
   // A page with no bindings and no listeners has nothing to hydrate:
@@ -230,6 +238,21 @@ function narrow(name, value, usage) {
   return narrowed;
 }
+// Removes the build-time route declarations from a page's script.
+//
+// routes([...]) says which pages to build, which the browser has no
+// use for — and calling it there is a ReferenceError that leaves the
+// page inert. params() is replaced by the values this page was built
+// with, so the markup reads them as plain data.
+function resolveRouteDeclarations(script, routeParams) {
+  if (!routeParams) return script;
+  return script
+    // A whole statement, so the trailing semicolon and newline go too.
+    .replace(/^[ \t]*routes\s*\([\s\S]*?\)\s*;?[ \t]*$/gm, '')
+    .replace(/\bparams\s*\(\s*\)/g, JSON.stringify(routeParams));
+}
 function staticNote() {
   return `
 // This page has no bindings and no listeners, so the server-rendered

package/core/compiler/parser.js CHANGED Viewed

@@ -42,6 +42,9 @@ export function parseAzox(source) {
     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),
   };
 }
@@ -63,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 [];

package/core/compiler/resolveComponents.js CHANGED Viewed

@@ -20,7 +20,7 @@ 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()) {
+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.
   //
@@ -30,16 +30,24 @@ export function resolveComponents(ast, sourcePath, resolver, seen = new Set()) {
   // rebasing a component's import against the page's directory points
   // it at a file that is not there.
   const hoisted = new Map();
-  const markup = expand(ast.markup, ast, sourcePath, resolver, seen, hoisted);
+  // 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, resolver, seen, hoisted) {
+function expand(node, ast, sourcePath, resolver, seen, hoisted, heads) {
   if (!node || node.type === 'text') return node;
   // <if> keeps its children in two branches rather than in `children`,
@@ -48,15 +56,17 @@ function expand(node, ast, sourcePath, resolver, seen, hoisted) {
   if (node.type === 'if') {
     return {
       ...node,
-      then: node.then.map((child) => expand(child, ast, sourcePath, resolver, seen, hoisted)),
+      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)
+        expand(child, ast, sourcePath, resolver, seen, hoisted, heads)
       ),
     };
   }
   const children = (node.children ?? []).map((child) =>
-    expand(child, ast, sourcePath, resolver, seen, hoisted)
+    expand(child, ast, sourcePath, resolver, seen, hoisted, heads)
   );
   if (node.type !== 'component') {
@@ -72,9 +82,14 @@ function expand(node, ast, sourcePath, resolver, seen, hoisted) {
     component.ast,
     component.path,
     resolver,
-    new Set([...seen, component.path])
+    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);

package/core/dev/watcher.js CHANGED Viewed

@@ -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/renderer/serverScope.js CHANGED Viewed

@@ -58,24 +58,36 @@ export function declaredNames(script) {
 // 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 = {}) {
+export function evaluateScript(body, params = [], args = [], modules = {}, extras = {}) {
   const imported = Object.keys(modules);
-  const names = declaredNames(body).filter((name) => !imported.includes(name));
+  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]), ...args);
+  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.

package/core/routes.js CHANGED Viewed

@@ -5,6 +5,11 @@
 //   pages/blog/index.azox   →  /blog          →  blog/index.html
 //   pages/blog/first.azox   →  /blog/first    →  blog/first/index.html
 //
+// A segment in brackets is a parameter, and the file is a template
+// rather than a route of its own:
+//
+//   pages/blog/[slug].azox  →  one page per entry the file declares
+//
 // Emitting a directory with an index.html means clean URLs work on
 // any static host without rewrite rules, since serving index.html
 // for a directory is universal behaviour.
@@ -43,6 +48,38 @@ function walk(dir, pagesDir) {
   return found;
 }
+// A bracketed segment names a parameter: [slug] matches one segment
+// and binds it to `slug`.
+const PARAM_SEGMENT = /^\[([A-Za-z_$][\w$]*)\]$/;
+export function paramNames(segments) {
+  return segments.map((segment) => segment.match(PARAM_SEGMENT)?.[1]).filter(Boolean);
+}
+// Fills a template's bracketed segments from a set of parameter
+// values, producing the concrete route that will be written.
+export function resolveRoute(route, values) {
+  const segments = route.templateSegments.map((segment) => {
+    const name = segment.match(PARAM_SEGMENT)?.[1];
+    if (!name) return segment;
+    return String(values[name]);
+  });
+  const url = segments.length ? `/${segments.join('/')}` : '/';
+  const outputDir = segments.join('/');
+  return {
+    ...route,
+    params: values,
+    isTemplate: false,
+    name: segments.join('/'),
+    url,
+    htmlPath: outputDir ? `${outputDir}/index.html` : 'index.html',
+    assetPrefix: '../'.repeat(segments.length) || './',
+    outputDir,
+  };
+}
 function describeRoute(pagesDir, sourcePath) {
   const relativePath = relative(pagesDir, sourcePath);
   const segments = relativePath.slice(0, -PAGE_EXTENSION.length).split(sep);
@@ -54,6 +91,8 @@ function describeRoute(pagesDir, sourcePath) {
   const url = routeSegments.length ? `/${routeSegments.join('/')}` : '/';
   const outputDir = routeSegments.join('/');
+  const params = paramNames(routeSegments);
   return {
     // The name used on the command line: `azox compile --page=blog/first`
     name: segments.join('/'),
@@ -64,6 +103,11 @@ function describeRoute(pagesDir, sourcePath) {
     // back out to reach the shared runtime at the build root.
     assetPrefix: '../'.repeat(routeSegments.length) || './',
     outputDir,
+    // A template is not a page: it stands in for however many the
+    // file declares, and is never written at this url.
+    isTemplate: params.length > 0,
+    paramNames: params,
+    templateSegments: routeSegments,
   };
 }

package/package.json CHANGED Viewed

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