fuzor 0.4.0 → 0.5.1

package/dist/compiler/index.js

@@ -1,12 +1,447 @@
+import { parseRoutePolicy, resolveRoutePolicies } from './route-policy.js';
+import { markComponentScriptSources, markPageScriptSources } from "./page-scripts.js";
+import { parseRouteMetadata, validateRouteMetadata } from "./metadata.js";
+import { createHash } from "node:crypto";
 import { readdir, readFile, stat } from "node:fs/promises";
+import { readFileSync } from "node:fs";
+import { pathToFileURL } from "node:url";
 import path from "node:path";
-import { Context, Effect, Layer } from "effect";
-import { parseMarkdown } from "@tanstack/markdown/parser";
-import { renderHtml } from "@tanstack/markdown/html";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import { routeKey, routeKeyFromSegments } from "../route-path.js";
+import { compileMarkdown } from "./markdown.js";
+import { pageText } from "./search.js";
+import { createCodeHighlighter } from "./highlight.js";
+import { collectAnchors, validateMarkdownLinks } from "./links.js";
+export { compileMarkdown } from "./markdown.js";
 import { parseFragment } from "parse5";
+import { isDocsDir, officialDocsLayout } from "./docs.js";
+export { isDocsDir, officialDocsLayout } from "./docs.js";
+const compilerVersion = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version;
+const digest = (...parts) => {
+    const hash = createHash("sha1");
+    for (const part of parts)
+        hash.update(`${part.length}:`).update(part);
+    return hash.digest("base64url");
+};
+/**
+ * Reuses per-page work between compilations of the same project, for dev servers and watch builds. Keys cover
+ * the compiler version, the options that change output and the page's own inputs (its text, layouts, route
+ * parameters, server module); entries also record what they read along the way (components by name, named
+ * layouts) and are only reused while those are unchanged. A completed compilation drops entries it did not use.
+ * The cache lives in memory; a fresh process compiles everything.
+ */
+export class CompileCache {
+    entries = new Map();
+    used = new Set();
+    hits = 0;
+    misses = 0;
+    /** Hits and misses of the latest compilation. */
+    stats() { return { hits: this.hits, misses: this.misses, entries: this.entries.size }; }
+    /** @internal */
+    begin() { this.used = new Set(); this.hits = 0; this.misses = 0; }
+    /** @internal */
+    lookup(key, current) {
+        const entry = this.entries.get(key);
+        if (entry)
+            for (const [dependency, value] of entry.dependencies) {
+                if (current(dependency) !== value) {
+                    this.entries.delete(key);
+                    this.misses++;
+                    return undefined;
+                }
+            }
+        if (!entry) {
+            this.misses++;
+            return undefined;
+        }
+        this.used.add(key);
+        this.hits++;
+        return entry.value;
+    }
+    /** @internal */
+    store(key, value, dependencies = new Map()) {
+        this.entries.set(key, { value, dependencies });
+        this.used.add(key);
+    }
+    /** @internal */
+    complete() { for (const key of this.entries.keys())
+        if (!this.used.has(key))
+            this.entries.delete(key); }
+}
+/** Validates redirects against compiled routes and collapses chains. */
+export function resolveRedirects(redirects, routes) {
+    const table = new Map();
+    for (const [from, to] of Object.entries(redirects)) {
+        const source = from.startsWith("/") && !from.startsWith("//") ? routeKey(new URL(from, "http://fuzor.local").pathname) : undefined;
+        if (!source || /[?#]/.test(from))
+            throw new Error(`Redirect source ${JSON.stringify(from)} must be a path such as "/old/".`);
+        if (routes.has(source))
+            throw new Error(`Redirect source ${from} is also a compiled route; remove the page or the redirect.`);
+        if (table.has(source))
+            throw new Error(`Redirect source ${from} is listed twice.`);
+        if (/^https?:\/\//i.test(to)) {
+            new URL(to);
+            table.set(source, to);
+            continue;
+        }
+        if (!to.startsWith("/") || to.startsWith("//"))
+            throw new Error(`Redirect target for ${from} must start with "/" or be an absolute HTTP(S) URL.`);
+        table.set(source, to);
+    }
+    const resolved = {};
+    for (const source of table.keys()) {
+        const seen = [source];
+        let target = table.get(source);
+        for (;;) {
+            if (/^https?:\/\//i.test(target))
+                break;
+            const url = new URL(target, "http://fuzor.local");
+            const key = routeKey(url.pathname);
+            if (key !== undefined && table.has(key)) {
+                if (seen.includes(key))
+                    throw new Error(`Redirect loop: ${[...seen, key].join(" -> ")}`);
+                seen.push(key);
+                const next = new URL(table.get(key), "http://fuzor.local");
+                // Query and hash on the earlier hop win, like browsers following a chain of Location headers.
+                target = /^https?:\/\//i.test(table.get(key)) ? table.get(key) : `${next.pathname}${url.search || next.search}${url.hash || next.hash}`;
+                continue;
+            }
+            if (key === undefined || !routes.has(key))
+                throw new Error(`Redirect ${source} -> ${target} does not reach a compiled route.`);
+            target = `${key}${url.search}${url.hash}`;
+            break;
+        }
+        resolved[source] = target;
+    }
+    return resolved;
+}
+const pathsModules = ["paths.ts", "paths.mts", "paths.js", "paths.mjs"];
+export const serverModules = ["server.ts", "server.mts", "server.js", "server.mjs"];
+/** `<fuzor-data name="user.name">fallback</fuzor-data>` slots require a server data module for the page. */
+function checkDataSlots(html, hasServerData, source) {
+    const visit = (node) => {
+        if (!("tagName" in node))
+            return;
+        if (node.tagName === "fuzor-data") {
+            const snippet = snippetOf(html, node.sourceCodeLocation);
+            const name = node.attrs.find(attribute => attribute.name === "name")?.value;
+            if (!name || !/^[A-Za-z_$][\w$]*(?:\.(?:[A-Za-z_$][\w$]*|\d+))*$/.test(name))
+                throw new SnippetError(`${source}: <fuzor-data> needs a name such as "user.name" or "items.0.title".`, snippet);
+            if (!node.sourceCodeLocation?.endTag)
+                throw new SnippetError(`${source}: <fuzor-data> must have a closing tag.`, snippet);
+            if (!hasServerData)
+                throw new SnippetError(`${source}: <fuzor-data name="${name}"> needs a server.ts module next to the page's index file.`, snippet);
+        }
+        for (const child of node.childNodes)
+            visit(child);
+        if (node.tagName === "template")
+            for (const child of node.content.childNodes)
+                visit(child);
+    };
+    parseFragment(html, { sourceCodeLocationInfo: true }).childNodes.forEach(visit);
+}
+/**
+ * `<fuzor-loading delay min>` indicators show while an island's code downloads (inside `<fuzor-island>`) or while
+ * the page's server data loads (anywhere else, on pages with `server.ts`). They are output hidden with
+ * `role="status"`, so pages without JavaScript never show them.
+ */
+function compileLoading(html, hasServerData, source) {
+    if (!/<fuzor-loading\b/i.test(html))
+        return html;
+    const replacements = [];
+    const visit = (node, island) => {
+        if (!("tagName" in node))
+            return;
+        if (node.tagName === "fuzor-loading") {
+            const location = node.sourceCodeLocation;
+            const snippet = snippetOf(html, location);
+            if (!location?.startTag || !location.endTag)
+                throw new SnippetError(`${source}: <fuzor-loading> must have a closing tag.`, snippet);
+            for (const attribute of node.attrs) {
+                if (["delay", "min"].includes(attribute.name)) {
+                    if (!/^\d+$/.test(attribute.value))
+                        throw new SnippetError(`${source}: <fuzor-loading ${attribute.name}> must be a number of milliseconds.`, snippet);
+                }
+                else if (!["class", "id", "style", "role", "aria-label", "aria-live", "hidden"].includes(attribute.name)) {
+                    throw new SnippetError(`${source}: <fuzor-loading> does not accept ${attribute.name}; use delay, min, class, id, style or ARIA attributes.`, snippet);
+                }
+            }
+            if (island && node.parentNode !== island)
+                throw new SnippetError(`${source}: <fuzor-loading> must be a direct child of its activation host.`, snippet);
+            if (!island && !hasServerData)
+                throw new SnippetError(`${source}: <fuzor-loading> shows while an island loads (put it inside <fuzor-island>) or while server data loads (the page needs server.ts).`, snippet);
+            const added = `${node.attrs.some(attribute => attribute.name === "hidden") ? "" : " hidden"}${node.attrs.some(attribute => attribute.name === "role") ? "" : ' role="status"'}`;
+            if (added)
+                replacements.push({ start: location.startTag.endOffset - 1, end: location.startTag.endOffset - 1, value: added });
+        }
+        const inside = ["fuzor-island"].includes(node.tagName) ? node : island;
+        for (const child of node.childNodes)
+            visit(child, inside);
+        if (node.tagName === "template")
+            for (const child of node.content.childNodes)
+                visit(child, inside);
+    };
+    parseFragment(html, { sourceCodeLocationInfo: true }).childNodes.forEach(node => visit(node, undefined));
+    for (const replacement of replacements.sort((a, b) => b.start - a.start)) {
+        html = html.slice(0, replacement.start) + replacement.value + html.slice(replacement.end);
+    }
+    return html;
+}
+function parseSegment(name) {
+    if (!name.includes("[") && !name.includes("]"))
+        return { kind: "static", value: name };
+    const match = /^\[(\.\.\.)?([a-zA-Z_][a-zA-Z0-9_]*)\]$/.exec(name);
+    if (!match)
+        return `Invalid dynamic folder name "${name}". Use [name] or [...name] with a letter, digit or underscore name.`;
+    return { kind: match[1] ? "rest" : "param", name: match[2] };
+}
+export function patternOf(segments) {
+    const parts = segments.map(segment => segment.kind === "static" ? encodeURIComponent(segment.value.normalize("NFC")) : segment.kind === "param" ? `[${segment.name}]` : `[...${segment.name}]`);
+    return parts.length ? `/${parts.join("/")}/` : "/";
+}
+function replaceParams(html, params) {
+    const fragment = parseFragment(html, { sourceCodeLocationInfo: true });
+    const replacements = [];
+    const visit = (node) => {
+        if (!("tagName" in node))
+            return;
+        if (node.tagName === "fuzor-param") {
+            const location = node.sourceCodeLocation;
+            const name = node.attrs.find(attribute => attribute.name === "name")?.value;
+            const snippet = snippetOf(html, location);
+            if (!location?.endTag)
+                throw new SnippetError("<fuzor-param> must have a closing tag.", snippet);
+            if (!params)
+                throw new SnippetError("<fuzor-param> is only available in dynamic route folders.", snippet);
+            if (!name || !Object.hasOwn(params, name))
+                throw new SnippetError(`Unknown route parameter ${JSON.stringify(name ?? "")}. Available: ${Object.keys(params).join(", ")}.`, snippet);
+            const value = params[name].replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+            replacements.push({ start: location.startOffset, end: location.endOffset, value });
+            return;
+        }
+        for (const child of node.childNodes)
+            visit(child);
+        if (node.tagName === "template")
+            for (const child of node.content.childNodes)
+                visit(child);
+    };
+    for (const node of fragment.childNodes)
+        visit(node);
+    for (const replacement of replacements.sort((a, b) => b.start - a.start)) {
+        html = html.slice(0, replacement.start) + replacement.value + html.slice(replacement.end);
+    }
+    return html;
+}
+/**
+ * `<fuzor-nav scope="/docs/" label="Documentation"></fuzor-nav>` becomes navigation for every route below
+ * `scope`, ordered by `order` metadata (pages without it last), then link text, then path. Pages with a
+ * `navGroup` are listed under group headings in order of first appearance. The current page is marked
+ * with `aria-current="page"`.
+ */
+function compileNav(html, current, routes, labels, source) {
+    if (!/<fuzor-nav\b/i.test(html))
+        return html;
+    const escapeText = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;");
+    const escapeAttr = (value) => escapeText(value).replaceAll('"', "&quot;");
+    const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+    const fragment = parseFragment(html, { sourceCodeLocationInfo: true });
+    const replacements = [];
+    const visit = (node) => {
+        if (!("tagName" in node))
+            return;
+        if (node.tagName === "fuzor-nav") {
+            const location = node.sourceCodeLocation;
+            if (!location?.endTag)
+                throw new SnippetError(`${source}: <fuzor-nav> must have a closing tag.`, snippetOf(html, location));
+            const scopeValue = node.attrs.find(attribute => attribute.name === "scope")?.value ?? "/";
+            const scope = routeKey(scopeValue);
+            if (!scope || !scopeValue.startsWith("/"))
+                throw new SnippetError(`${source}: <fuzor-nav scope="${scopeValue}"> must be a path such as "/docs/".`, snippetOf(html, location));
+            const label = node.attrs.find(attribute => attribute.name === "label")?.value ?? "Pages";
+            const entries = routes.filter(route => route.path.startsWith(scope)).map(route => ({
+                route, text: route.metadata?.navTitle ?? labels.get(route.path) ?? route.metadata?.title ?? decodeURIComponent(route.path)
+            })).sort((a, b) => {
+                const orderA = a.route.metadata?.order ?? Number.POSITIVE_INFINITY;
+                const orderB = b.route.metadata?.order ?? Number.POSITIVE_INFINITY;
+                return orderA !== orderB ? orderA - orderB : compare(a.text, b.text) || compare(a.route.path, b.route.path);
+            });
+            const list = (items) => `<ul>${items.map(({ route, text }) => `<li><a href="${escapeAttr(route.path)}"${route.path === current ? ' aria-current="page"' : ""}>${escapeText(text)}</a></li>`).join("")}</ul>`;
+            const renderGroups = (items) => {
+                const groups = new Map();
+                for (const entry of items) {
+                    const group = entry.route.metadata?.navGroup ?? "";
+                    groups.set(group, [...(groups.get(group) ?? []), entry]);
+                }
+                return [...groups].map(([group, grpItems]) => group ? `<p data-fuzor-nav-group>${escapeText(group)}</p>${list(grpItems)}` : list(grpItems)).join("");
+            };
+            const hasCategories = entries.some(entry => Boolean(entry.route.metadata?.navCategory));
+            let navHtml;
+            if (!hasCategories) {
+                navHtml = `<nav aria-label="${escapeAttr(label)}">${renderGroups(entries)}</nav>`;
+            }
+            else {
+                const categories = new Map();
+                for (const entry of entries) {
+                    const category = entry.route.metadata?.navCategory ?? "General";
+                    categories.set(category, [...(categories.get(category) ?? []), entry]);
+                }
+                const activeEntry = entries.find(entry => entry.route.path === current);
+                const activeCategory = activeEntry?.route.metadata?.navCategory ?? categories.keys().next().value ?? "General";
+                const navId = `fuzor-nav-${replacements.length + 1}`;
+                const tabsList = `<fuzor-tabs-list data-part="list" role="tablist" class="docs-category-list" aria-label="${escapeAttr(label)}">${[...categories.keys()].map((cat, index) => `<button type="button" data-part="trigger" data-value="${escapeAttr(cat)}" value="${escapeAttr(cat)}" role="tab" id="${navId}-trigger-${index}" aria-controls="${navId}-panel-${index}" aria-selected="${cat === activeCategory}" tabindex="${cat === activeCategory ? 0 : -1}" class="docs-category-tab"${cat === activeCategory ? ' data-state="active"' : ' data-state="inactive"'}>${escapeText(cat)}</button>`).join("")}</fuzor-tabs-list>`;
+                const tabsPanels = [...categories.entries()].map(([cat, catEntries], index) => {
+                    const isActive = cat === activeCategory;
+                    return `<fuzor-tabs-content data-part="content" role="tabpanel" id="${navId}-panel-${index}" aria-labelledby="${navId}-trigger-${index}" value="${escapeAttr(cat)}" class="docs-category-content"${isActive ? ' data-state="active"' : ' hidden data-state="inactive"'}><nav aria-label="${escapeAttr(cat)}">${renderGroups(catEntries)}</nav></fuzor-tabs-content>`;
+                }).join("");
+                const fallback = [...categories].map(([cat, catEntries]) => `<p class="docs-category-heading">${escapeText(cat)}</p><nav aria-label="${escapeAttr(cat)}">${renderGroups(catEntries)}</nav>`).join("");
+                navHtml = `<fuzor-tabs id="${navId}" data-fuzor-ui="tabs" value="${escapeAttr(activeCategory)}" defaultValue="${escapeAttr(activeCategory)}" class="docs-category-tabs">${tabsList}${tabsPanels}</fuzor-tabs><noscript><style>.docs-category-tabs { display: none !important; }</style>${fallback}</noscript>`;
+            }
+            replacements.push({ start: location.startOffset, end: location.endOffset, value: navHtml });
+            return;
+        }
+        for (const child of node.childNodes)
+            visit(child);
+        if (node.tagName === "template")
+            for (const child of node.content.childNodes)
+                visit(child);
+    };
+    fragment.childNodes.forEach(visit);
+    for (const replacement of replacements.sort((a, b) => b.start - a.start)) {
+        html = html.slice(0, replacement.start) + replacement.value + html.slice(replacement.end);
+    }
+    return html;
+}
+/** Text of the first `<h1>` in page content, before layouts. */
+function firstHeading(html) {
+    let found;
+    const text = (node) => "value" in node ? node.value : "childNodes" in node ? node.childNodes.map(text).join("") : "";
+    const visit = (node) => {
+        if (found !== undefined || !("tagName" in node))
+            return;
+        if (node.tagName === "h1") {
+            found = text(node).replace(/\s+/g, " ").trim();
+            return;
+        }
+        node.childNodes.forEach(visit);
+    };
+    parseFragment(html).childNodes.forEach(visit);
+    return found || undefined;
+}
+const issueText = (error) => (error instanceof Error ? error.message : String(error)).replace(/\s+/g, " ").trim();
+/**
+ * Validates a `paths` module result against the dynamic segments of the page that uses it. With a `params`
+ * Schema, entries hold decoded values: each is encoded to its URL form, which must decode again, so the
+ * values the browser reads back from the URL always satisfy the schema.
+ */
+function readPathEntries(value, dynamic, file, schema) {
+    if (!Array.isArray(value))
+        throw new Error(`${file} must export default an array of { params } entries, or a function returning one.`);
+    const names = dynamic.map(segment => segment.name);
+    return value.map((entry, index) => {
+        const where = `${file} entry ${index}`;
+        if (typeof entry !== "object" || entry === null || typeof entry.params !== "object" || entry.params === null) {
+            throw new Error(`${where} must be an object with params.`);
+        }
+        const { params: given, metadata, ...unknown } = entry;
+        if (Object.keys(unknown).length)
+            throw new Error(`${where} has unknown fields: ${Object.keys(unknown).join(", ")}.`);
+        let raw = given;
+        if (schema) {
+            try {
+                raw = Schema.encodeUnknownSync(schema)(given);
+            }
+            catch (error) {
+                throw new Error(`${where}: params do not match the params schema: ${issueText(error)}`);
+            }
+            if (typeof raw !== "object" || raw === null)
+                throw new Error(`${where}: the params schema must encode to an object of strings.`);
+        }
+        const extra = Object.keys(raw).filter(key => !names.includes(key));
+        if (extra.length)
+            throw new Error(`${where} has params not in the route: ${extra.join(", ")}.`);
+        const params = {};
+        const segments = {};
+        for (const segment of dynamic) {
+            const name = segment.name;
+            const value = raw[name];
+            if (segment.kind === "param") {
+                if (typeof value !== "string" || value === "" || value.includes("/"))
+                    throw new Error(`${where}: params.${name} must be a non-empty string without "/".`);
+                params[name] = value;
+                segments[name] = [value];
+            }
+            else {
+                const parts = typeof value === "string" ? value.split("/") : value;
+                if (!Array.isArray(parts) || parts.length === 0 || parts.some(part => typeof part !== "string" || part === "" || part.includes("/"))) {
+                    throw new Error(`${where}: params.${name} must be a non-empty array of path segments or a "a/b" string.`);
+                }
+                params[name] = parts.join("/");
+                segments[name] = parts;
+            }
+            if ([".", ".."].includes(params[name]))
+                throw new Error(`${where}: params.${name} cannot be a dot segment.`);
+        }
+        if (schema) {
+            try {
+                Schema.decodeUnknownSync(schema)(params);
+            }
+            catch (error) {
+                throw new Error(`${where}: the URL form ${JSON.stringify(params)} does not decode with the params schema: ${issueText(error)}`);
+            }
+        }
+        return { params, segments, ...(metadata === undefined ? {} : { metadata: validateRouteMetadata(metadata) }) };
+    });
+}
+async function defaultLoadModule(file) {
+    try {
+        return await import(pathToFileURL(file).href);
+    }
+    catch (error) {
+        if (error.code === "ERR_UNKNOWN_FILE_EXTENSION") {
+            throw new Error(`Cannot import ${file} with Node. Compile through fuzorPlugin() or pass a loadModule option.`);
+        }
+        throw error;
+    }
+}
 const slotPattern = /<slot\s*(?:\/\s*>|>\s*<\/slot\s*>)/i;
 export class CompilerError extends Error {
+    location;
     _tag = "CompilerError";
+    constructor(message, location) {
+        super(message);
+        this.location = location;
+    }
+}
+/**
+ * Problems found in assembled HTML (page plus layouts and components) carry the offending opening tag. The
+ * compiler finds that tag in the author's files to report a real file, line and column.
+ */
+class SnippetError extends Error {
+    snippet;
+    constructor(message, snippet) {
+        super(message);
+        this.snippet = snippet;
+    }
+}
+const snippetOf = (html, location) => location ? html.slice(location.startOffset, location.startTag?.endOffset ?? location.endOffset) : "";
+/** Line and column (1-based) of `snippet` in the first source that contains it, preferring `preferred`. */
+export function locateSnippet(sources, snippet, preferred) {
+    if (!snippet)
+        return undefined;
+    const files = preferred && sources.has(preferred) ? [preferred, ...[...sources.keys()].filter(file => file !== preferred)] : [...sources.keys()];
+    for (const file of files) {
+        const text = sources.get(file);
+        const index = text.indexOf(snippet);
+        if (index < 0)
+            continue;
+        const before = text.slice(0, index);
+        const line = before.split("\n").length;
+        return { file, line, column: index - before.lastIndexOf("\n") };
+    }
+    return undefined;
 }
 export const CompilerFileSystem = Context.Service("FuzorCompilerFileSystem");
 const io = (label, action) => Effect.tryPromise({ try: action, catch: (error) => new CompilerError(`${label}: ${String(error)}`) });
@@ -26,7 +461,7 @@ export const CompilerFileSystemLive = Layer.succeed(CompilerFileSystem, {
     })
 });
 function routePath(relativeDir) {
-    return relativeDir === "" ? "/" : `/${relativeDir.split(path.sep).join("/")}/`;
+    return routeKeyFromSegments(relativeDir.split(path.sep));
 }
 function fillSlot(layout, content, label) {
     if (!slotPattern.test(layout)) {
@@ -47,7 +482,7 @@ function expandComponents(html, components, stack = []) {
                 throw new Error(`Component cycle: ${[...stack, name].join(" -> ")}`);
             const location = node.sourceCodeLocation;
             if (!location?.startTag || !location.endTag)
-                throw new Error(`Component <${name}> must have a closing tag.`);
+                throw new SnippetError(`Component <${name}> must have a closing tag.`, snippetOf(html, location));
             const children = html.slice(location.startTag.endOffset, location.endTag.startOffset);
             const nested = expandComponents(children, components, stack);
             const body = slotPattern.test(source) ? fillSlot(source, nested, `Component ${name}`) : source;
@@ -81,7 +516,7 @@ function compileLinks(html) {
         if (node.tagName === "fuzor-link") {
             const location = node.sourceCodeLocation;
             if (!location?.startTag || !location.endTag)
-                throw new Error("<fuzor-link> must have a closing tag.");
+                throw new SnippetError("<fuzor-link> must have a closing tag.", snippetOf(html, location));
             const opening = html.slice(location.startTag.startOffset, location.startTag.endOffset)
                 .replace(/^<fuzor-link\b/i, "<a data-fuzor-link");
             replacements.push({ start: location.startTag.startOffset, end: location.startTag.endOffset, value: opening });
@@ -101,21 +536,112 @@ function compileLinks(html) {
     }
     return html;
 }
-export function compileProjectEffect(root) {
+const platformComment = /^fuzor:platform(?:\s+(--[a-z][a-z0-9-]*(?:\s+--[a-z][a-z0-9-]*)*))?\s*$/;
+const platformEndComment = /^\/fuzor:platform\s*$/;
+function platformNames(value) {
+    return value.split(/\s+/).filter(Boolean).map(name => name.slice(2));
+}
+function platformMatches(selectors, platform) {
+    return selectors.includes(platform) || (selectors.includes("native") && (platform === "desktop" || platform === "mobile"));
+}
+/** Selects compile-time platform blocks while keeping the source valid HTML. */
+export function compilePlatformBlocks(html, platform, source, found = new Set()) {
+    const fragment = parseFragment(html, { sourceCodeLocationInfo: true });
+    const comments = [];
+    const visit = (node) => {
+        if (node.nodeName === "#comment") {
+            const comment = node;
+            const location = node.sourceCodeLocation;
+            if (location)
+                comments.push({ data: comment.data, start: location.startOffset, end: location.endOffset });
+            return;
+        }
+        if ("childNodes" in node)
+            for (const child of node.childNodes)
+                visit(child);
+        if ("tagName" in node && node.tagName === "template") {
+            for (const child of node.content.childNodes)
+                visit(child);
+        }
+    };
+    for (const node of fragment.childNodes)
+        visit(node);
+    const replacements = [];
+    const stack = [];
+    for (const comment of comments) {
+        const opening = platformComment.exec(comment.data);
+        if (opening) {
+            if (stack.length)
+                throw new SnippetError("Platform blocks cannot be nested.", snippetOf(html, { startOffset: comment.start, endOffset: comment.end }));
+            const selectors = platformNames(opening[1] ?? "");
+            if (!selectors.length)
+                throw new SnippetError("Platform blocks need at least one selector such as --desktop.", snippetOf(html, { startOffset: comment.start, endOffset: comment.end }));
+            selectors.forEach(selector => found.add(selector));
+            stack.push({ selectors, start: comment.start, bodyStart: comment.end });
+            continue;
+        }
+        if (platformEndComment.test(comment.data)) {
+            const block = stack.pop();
+            if (!block)
+                throw new SnippetError("Unexpected platform block closing comment.", snippetOf(html, { startOffset: comment.start, endOffset: comment.end }));
+            replacements.push({
+                start: block.start,
+                end: comment.end,
+                value: platformMatches(block.selectors, platform) ? html.slice(block.bodyStart, comment.start) : ""
+            });
+        }
+    }
+    if (stack.length)
+        throw new SnippetError("Unclosed platform block.", `<!--fuzor:platform --${stack[0].selectors.join(" --")}-->`);
+    for (const replacement of replacements.sort((a, b) => b.start - a.start)) {
+        html = html.slice(0, replacement.start) + replacement.value + html.slice(replacement.end);
+    }
+    return html;
+}
+export function compileProjectEffect(root, options = {}) {
     return Effect.gen(function* () {
-        const fs = yield* CompilerFileSystem;
+        const fileSystem = yield* CompilerFileSystem;
+        // Every author file read is kept so errors in assembled HTML can point to their real location.
+        const sources = new Map();
+        const fs = { ...fileSystem, read: file => fileSystem.read(file).pipe(Effect.tap(text => Effect.sync(() => { sources.set(file, text); }))) };
+        const failure = (error, source, prefix = "") => {
+            const message = `${prefix}${error instanceof Error ? error.message : String(error)}`;
+            if (error instanceof CompilerError)
+                return error;
+            if (error instanceof SnippetError) {
+                const location = locateSnippet(sources, error.snippet, source);
+                const at = location ? ` (${path.relative(projectRoot, location.file).replaceAll("\\", "/")}:${location.line}:${location.column})` : "";
+                return new CompilerError(`${message}${at}`, location ?? (source ? { file: source } : undefined));
+            }
+            return new CompilerError(message, source ? { file: source } : undefined);
+        };
+        // YAML reports positions inside the frontmatter block, which starts on the file's second line.
+        const frontmatterFailure = (error, source, label = "Frontmatter error") => {
+            const message = error instanceof Error ? error.message : String(error);
+            const position = /at line (\d+), column (\d+)/.exec(message);
+            return new CompilerError(`${label} in ${source}: ${message}`, position ? { file: source, line: Number(position[1]) + 1, column: Number(position[2]) } : { file: source });
+        };
         const projectRoot = path.resolve(root);
+        const cache = options.cache;
+        cache?.begin();
+        const optionsKey = JSON.stringify([compilerVersion, options.platform ?? "web", options.markdown?.highlight ?? null]);
         const pagesRoot = path.join(projectRoot, "pages");
         const componentsRoot = path.join(projectRoot, "components");
         const layoutsRoot = path.join(projectRoot, "layouts");
-        for (const directory of [pagesRoot, componentsRoot]) {
-            const directoryStat = yield* fs.stat(directory);
-            if (!directoryStat.isDirectory())
-                yield* Effect.fail(new CompilerError(`${directory} must be a directory.`));
-        }
+        const pagesStat = yield* fs.stat(pagesRoot).pipe(Effect.mapError(() => new CompilerError(`${pagesRoot} must be a directory containing index.html or index.md.`)));
+        if (!pagesStat.isDirectory())
+            yield* Effect.fail(new CompilerError(`${pagesRoot} must be a directory.`));
+        // components/ is optional; a file with that name is still a mistake.
+        const componentsStat = yield* fs.stat(componentsRoot).pipe(Effect.option);
+        if (componentsStat._tag === "Some" && !componentsStat.value.isDirectory())
+            yield* Effect.fail(new CompilerError(`${componentsRoot} must be a directory.`));
+        const scriptsRoot = path.join(projectRoot, "client");
+        const scriptsStat = yield* fs.stat(scriptsRoot).pipe(Effect.option);
+        const scriptEntries = scriptsStat._tag === "Some" && scriptsStat.value.isDirectory() ? yield* fs.entries(scriptsRoot) : [];
+        const searchFile = scriptEntries.find(entry => entry.isFile() && /^docs-search\.(ts|js)$/.test(entry.name));
         const files = [];
         const components = new Map();
-        const componentEntries = yield* fs.entries(componentsRoot);
+        const componentEntries = componentsStat._tag === "Some" ? yield* fs.entries(componentsRoot) : [];
         yield* Effect.forEach(componentEntries, (entry) => Effect.gen(function* () {
             if (!entry.isFile() || !entry.name.endsWith(".html"))
                 return;
@@ -124,61 +650,332 @@ export function compileProjectEffect(root) {
                 yield* Effect.fail(new CompilerError(`Invalid component filename: ${entry.name}. Use kebab-case and reserve fuzor-* for the framework.`));
             }
             const file = path.join(componentsRoot, entry.name);
-            components.set(name, yield* fs.read(file));
+            const html = yield* fs.read(file);
+            const prepared = yield* Effect.try({ try: () => markComponentScriptSources(html, file), catch: error => new CompilerError(String(error)) });
+            components.set(name, prepared);
             files.push(file);
         }), { concurrency: 8, discard: true });
+        let rootLayout;
         const routes = [];
-        const visit = (directory, relativeDir, layouts) => Effect.gen(function* () {
+        const boundaries = [];
+        const markdownContent = new Map();
+        const labels = new Map();
+        const loadModule = options.loadModule ?? defaultLoadModule;
+        const highlightOption = options.markdown?.highlight;
+        const platform = options.platform ?? "web";
+        const platforms = new Set();
+        const highlight = highlightOption ? createCodeHighlighter(highlightOption === true ? {} : highlightOption) : undefined;
+        const pathEntries = new Map();
+        const namedLayouts = new Map();
+        /** Current fingerprint of something a cached page read: `component:<name>` or `layout:<file>`. */
+        const currentDependency = (dependency) => {
+            if (dependency.startsWith("component:")) {
+                const source = components.get(dependency.slice(10));
+                return source === undefined ? null : digest(source);
+            }
+            return namedLayouts.get(dependency.slice(7)) ?? null;
+        };
+        const assemble = (source, layouts) => Effect.gen(function* () {
+            const file = yield* fs.read(source);
+            files.push(source);
+            const key = cache && digest("assemble", optionsKey, source, file, ...layouts);
+            if (cache && key) {
+                // Named layouts are only known after parsing; read every named layout a cached entry depends on.
+                const entry = cache.lookup(key, currentDependency);
+                if (entry) {
+                    files.push(...entry.files);
+                    return entry;
+                }
+            }
+            const dependencies = new Map();
+            const readComponent = (name) => {
+                const value = components.get(name);
+                if (name.includes("-"))
+                    dependencies.set(`component:${name}`, value === undefined ? null : digest(value));
+                return value;
+            };
+            const tracked = { get: readComponent };
+            const assembledFiles = [source];
+            const compiledMarkdown = source.endsWith(".md") ? yield* Effect.try({
+                try: () => compileMarkdown(file, { elements: name => readComponent(name) !== undefined }),
+                catch: (error) => frontmatterFailure(error, source, "Markdown error")
+            }) : undefined;
+            const markdown = compiledMarkdown && highlight ? { ...compiledMarkdown, html: yield* Effect.tryPromise({
+                    try: () => highlight(compiledMarkdown.html),
+                    catch: error => new CompilerError(`Highlighting failed in ${source}: ${error instanceof Error ? error.message : String(error)}`, { file: source })
+                }) } : compiledMarkdown;
+            // HTML pages accept the same YAML frontmatter as Markdown, which is removed from the page body.
+            const htmlFrontmatter = markdown ? undefined : /^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/.exec(file);
+            const raw = markdown ? file : parseRoutePolicy(htmlFrontmatter ? file.slice(htmlFrontmatter[0].length) : file, source, source.startsWith(pagesRoot + path.sep) && path.basename(source) === "index.html").html;
+            const metadata = markdown?.metadata ?? (htmlFrontmatter ? yield* Effect.try({
+                try: () => parseRouteMetadata(htmlFrontmatter[1]),
+                catch: error => frontmatterFailure(error, source)
+            }) : {});
+            let routeLayouts = layouts;
+            if (metadata.layout) {
+                const named = path.join(layoutsRoot, `${metadata.layout}.html`);
+                if (!(yield* fs.exists(named)))
+                    return yield* Effect.fail(new CompilerError(`Unknown named layout ${metadata.layout} in ${source}: ${named}`));
+                const layoutSource = yield* fs.read(named);
+                const html = markPageScriptSources(layoutSource, named);
+                files.push(named);
+                assembledFiles.push(named);
+                namedLayouts.set(named, digest(layoutSource));
+                dependencies.set(`layout:${named}`, digest(layoutSource));
+                routeLayouts = rootLayout ? [rootLayout, html] : [html];
+            }
+            const heading = markdown ? markdown.headings.find(entry => entry.level === 1)?.text : firstHeading(raw);
+            const html = yield* Effect.try({
+                try: () => {
+                    let content = markPageScriptSources(markdown?.html ?? raw, source);
+                    for (let index = routeLayouts.length - 1; index >= 0; index--) {
+                        content = fillSlot(routeLayouts[index], content, `Layout ${index + 1} for ${source}`);
+                    }
+                    return compilePlatformBlocks(compileLinks(expandComponents(content, tracked)), platform, source, platforms)
+                        .replace(/<fuzor-toc\s*>\s*<\/fuzor-toc\s*>/gi, () => markdown?.toc ?? "");
+                },
+                catch: (error) => failure(error, source, `Compilation failed for ${source}: `)
+            });
+            const assembled = { html, markdown, heading, raw, metadata, files: assembledFiles };
+            if (cache && key)
+                cache.store(key, assembled, dependencies);
+            return assembled;
+        });
+        // Existence comes from the folder listing that visit() already has, instead of one stat per candidate file.
+        const pageSource = (directory, base, entries) => Effect.gen(function* () {
+            const html = path.join(directory, `${base}.html`);
+            const md = path.join(directory, `${base}.md`);
+            const hasHtml = entries.some(entry => entry.isFile() && entry.name === `${base}.html`);
+            const hasMarkdown = entries.some(entry => entry.isFile() && entry.name === `${base}.md`);
+            if (hasHtml && hasMarkdown)
+                return yield* Effect.fail(new CompilerError(`${directory} has both ${base}.html and ${base}.md.`));
+            return hasHtml ? html : hasMarkdown ? md : undefined;
+        });
+        const visit = (directory, relativeDir, context) => Effect.gen(function* () {
             const entries = yield* fs.entries(directory);
+            if (isDocsDir(relativeDir)) {
+                for (const entry of entries) {
+                    if (entry.isFile() && !entry.name.startsWith(".") && !entry.name.endsWith(".md")) {
+                        return yield* Effect.fail(new CompilerError(`Docs directory only allows Markdown (.md) files. Found "${entry.name}" in ${directory}.`));
+                    }
+                }
+            }
             const layoutFile = path.join(directory, "layout.html");
             const externalLayoutFile = relativeDir ? path.join(layoutsRoot, `${relativeDir}.html`) : "";
-            const hasLocalLayout = yield* fs.exists(layoutFile);
+            const hasLocalLayout = entries.some(entry => entry.isFile() && entry.name === "layout.html");
             const hasExternalLayout = externalLayoutFile ? yield* fs.exists(externalLayoutFile) : false;
             if (hasLocalLayout && hasExternalLayout) {
                 yield* Effect.fail(new CompilerError(`Duplicate layout for /${relativeDir}/: ${layoutFile} and ${externalLayoutFile}`));
             }
             const selectedLayout = hasLocalLayout ? layoutFile : hasExternalLayout ? externalLayoutFile : undefined;
+            const docsLayout = relativeDir === "docs" && !selectedLayout ? officialDocsLayout(searchFile ? { searchModule: `/client/${searchFile.name}` } : {}) : undefined;
             const ownLayouts = selectedLayout
-                ? [...layouts, yield* fs.read(selectedLayout)]
-                : [...layouts];
+                ? [...context.layouts, markPageScriptSources(yield* fs.read(selectedLayout), selectedLayout)]
+                : docsLayout
+                    ? [...context.layouts, docsLayout]
+                    : [...context.layouts];
             if (selectedLayout)
                 files.push(selectedLayout);
-            const htmlFile = path.join(directory, "index.html");
-            const mdFile = path.join(directory, "index.md");
-            const hasHtml = yield* fs.exists(htmlFile);
-            const hasMarkdown = yield* fs.exists(mdFile);
-            if (hasHtml && hasMarkdown)
-                yield* Effect.fail(new CompilerError(`${directory} has both index.html and index.md.`));
-            if (hasHtml || hasMarkdown) {
-                const source = hasHtml ? htmlFile : mdFile;
-                const raw = yield* fs.read(source);
-                files.push(source);
-                let content = hasMarkdown ? yield* Effect.try({
-                    try: () => renderHtml(parseMarkdown(raw)),
-                    catch: (error) => new CompilerError(`Markdown error in ${source}: ${String(error)}`)
-                }) : raw;
-                content = yield* Effect.try({
-                    try: () => {
-                        for (let index = ownLayouts.length - 1; index >= 0; index--) {
-                            content = fillSlot(ownLayouts[index], content, `Layout ${index + 1} for ${source}`);
+            if (!relativeDir)
+                rootLayout = ownLayouts[0];
+            const dynamic = context.segments.filter(segment => segment.kind !== "static");
+            const pathsFiles = entries.filter(entry => entry.isFile() && pathsModules.includes(entry.name)).map(entry => path.join(directory, entry.name));
+            if (pathsFiles.length > 1)
+                yield* Effect.fail(new CompilerError(`${directory} has more than one paths module: ${pathsFiles.map(file => path.basename(file)).join(", ")}.`));
+            const last = context.segments.at(-1);
+            if (pathsFiles.length && !dynamic.length)
+                yield* Effect.fail(new CompilerError(`${pathsFiles[0]} is only valid inside a dynamic route folder such as [slug].`));
+            // A new dynamic segment needs its own paths module; deeper static folders inherit the nearest one.
+            const pathsFile = pathsFiles[0] ?? (last && last.kind !== "static" ? undefined : context.pathsFile);
+            if (pathsFile)
+                files.push(pathsFile);
+            if (last?.kind === "rest" && entries.some(entry => entry.isDirectory() && !entry.name.startsWith("."))) {
+                yield* Effect.fail(new CompilerError(`Catch-all folder ${directory} cannot contain subfolders.`));
+            }
+            const serverFiles = entries.filter(entry => entry.isFile() && serverModules.includes(entry.name)).map(entry => path.join(directory, entry.name));
+            if (serverFiles.length > 1)
+                yield* Effect.fail(new CompilerError(`${directory} has more than one server module: ${serverFiles.map(file => path.basename(file)).join(", ")}.`));
+            const serverData = serverFiles[0];
+            const source = yield* pageSource(directory, "index", entries);
+            const declaration = source?.endsWith(".html") ? parseRoutePolicy(yield* fs.read(source), source, true).declaration : {};
+            const rendering = declaration.rendering ?? context.rendering ?? "static";
+            if (serverData && !source)
+                yield* Effect.fail(new CompilerError(`${serverData} has no index.html or index.md page to provide data for.`));
+            if (serverData)
+                files.push(serverData);
+            if (source) {
+                const { html, markdown, heading, raw, metadata: pageMetadata } = yield* assemble(source, ownLayouts);
+                const hasMetadata = Object.keys(pageMetadata).length > 0;
+                let paths;
+                if (dynamic.length && (pathsFile || rendering !== "request")) {
+                    if (!pathsFile) {
+                        return yield* Effect.fail(new CompilerError(`Dynamic route ${patternOf(context.segments)} (${source}) needs a paths module (paths.ts or paths.js) in ${directory} listing its parameters.`));
+                    }
+                    let loading = pathEntries.get(pathsFile);
+                    if (!loading) {
+                        loading = loadModule(pathsFile).then(async (module) => {
+                            if (module.params !== undefined && !Schema.isSchema(module.params))
+                                throw new Error("export const params must be an Effect Schema, such as Schema.Struct({ id: Schema.FiniteFromString })");
+                            const entries = typeof module.default === "function" ? await module.default() : module.default;
+                            return { entries, schema: module.params };
+                        });
+                        pathEntries.set(pathsFile, loading);
+                    }
+                    const value = yield* Effect.tryPromise({ try: () => loading, catch: error => new CompilerError(`Cannot load ${pathsFile}: ${error instanceof Error ? error.message : String(error)}`, { file: pathsFile }) });
+                    const list = yield* Effect.try({ try: () => readPathEntries(value.entries, dynamic, pathsFile, value.schema), catch: error => new CompilerError(error instanceof Error ? error.message : String(error), { file: pathsFile }) });
+                    paths = { list, schema: value.schema };
+                }
+                // Everything below is a function of the assembled page and its route inputs.
+                const pageKey = cache && digest("page", compilerVersion, source, html, raw, markdown?.html ?? "\0", heading ?? "\0", JSON.stringify(pageMetadata), serverData ?? "", rendering, patternOf(context.segments), paths ? JSON.stringify(paths.list) : routePath(relativeDir), paths?.schema && pathsFile ? pathsFile : "");
+                const cachedPage = pageKey ? cache.lookup(pageKey, currentDependency) : undefined;
+                if (cachedPage) {
+                    routes.push(...cachedPage.routes);
+                    for (const [route, content] of cachedPage.markdown)
+                        markdownContent.set(route, content);
+                    for (const [route, label] of cachedPage.labels)
+                        labels.set(route, label);
+                }
+                else {
+                    const output = { routes: [], markdown: [], labels: [] };
+                    yield* Effect.try({ try: () => checkDataSlots(html, Boolean(serverData), source), catch: error => failure(error, source) });
+                    const withLoading = yield* Effect.try({ try: () => compileLoading(html, Boolean(serverData), source), catch: error => failure(error, source) });
+                    if (!paths) {
+                        const route = routePath(relativeDir);
+                        const content = yield* Effect.try({ try: () => dynamic.length && rendering === "request" ? withLoading : replaceParams(withLoading, undefined), catch: error => failure(error, source, `${source}: `) });
+                        if (markdown)
+                            output.markdown.push([route, markdown.html]);
+                        if (heading)
+                            output.labels.push([route, heading]);
+                        output.routes.push({ path: route, source, html: content, search: pageText(markdown?.html ?? raw), ...(dynamic.length && rendering === "request" ? { requestPattern: patternOf(context.segments).replace(/\[\.\.\.(\w+)\]/g, ":$1*").replace(/\[(\w+)\]/g, ":$1") } : {}), ...(markdown || hasMetadata ? { metadata: pageMetadata } : {}), ...(serverData ? { serverData } : {}) });
+                    }
+                    else {
+                        for (const entry of paths.list) {
+                            const concrete = context.segments.flatMap(segment => segment.kind === "static" ? [segment.value] : entry.segments[segment.name]);
+                            const route = routeKeyFromSegments(concrete);
+                            const content = yield* Effect.try({ try: () => replaceParams(withLoading, entry.params), catch: error => failure(error, source, `${source}: `) });
+                            const metadata = markdown || hasMetadata || entry.metadata ? { ...pageMetadata, ...entry.metadata } : undefined;
+                            if (markdown)
+                                output.markdown.push([route, markdown.html]);
+                            const entryRaw = yield* Effect.try({ try: () => replaceParams(raw, entry.params), catch: error => failure(error, source, `${source}: `) });
+                            const entryHeading = markdown ? heading : firstHeading(entryRaw);
+                            if (entryHeading)
+                                output.labels.push([route, entryHeading]);
+                            output.routes.push({ path: route, source, html: content, search: pageText(markdown?.html ?? entryRaw), pattern: patternOf(context.segments), params: entry.params, ...(paths.schema && pathsFile ? { paramsSchema: pathsFile } : {}), ...(metadata ? { metadata } : {}), ...(serverData ? { serverData } : {}) });
                         }
-                        return compileLinks(expandComponents(content, components));
-                    },
-                    catch: (error) => new CompilerError(`Compilation failed for ${source}: ${String(error)}`)
-                });
-                routes.push({ path: routePath(relativeDir), source, html: content });
+                    }
+                    if (pageKey)
+                        cache.store(pageKey, output);
+                    routes.push(...output.routes);
+                    for (const [route, content] of output.markdown)
+                        markdownContent.set(route, content);
+                    for (const [route, label] of output.labels)
+                        labels.set(route, label);
+                }
+            }
+            for (const kind of ["not-found", "error"]) {
+                const boundary = yield* pageSource(directory, kind, entries);
+                if (!boundary)
+                    continue;
+                if (dynamic.length)
+                    return yield* Effect.fail(new CompilerError(`${boundary}: ${kind} pages must be in a static folder.`));
+                const { html, markdown, metadata: boundaryMetadata } = yield* assemble(boundary, ownLayouts);
+                yield* Effect.try({ try: () => checkDataSlots(html, false, boundary), catch: error => failure(error instanceof Error ? Object.assign(error, { message: `${error.message} Boundary pages cannot use server data.` }) : error, boundary) });
+                const content = yield* Effect.try({ try: () => replaceParams(compileLoading(html, false, boundary), undefined), catch: error => failure(error, boundary, `${boundary}: `) });
+                boundaries.push({ kind, scope: routePath(relativeDir), source: boundary, html: content, ...(markdown || Object.keys(boundaryMetadata).length ? { metadata: boundaryMetadata } : {}) });
             }
-            yield* Effect.forEach(entries.filter((entry) => entry.isDirectory() && !entry.name.startsWith(".")), (entry) => visit(path.join(directory, entry.name), path.join(relativeDir, entry.name), ownLayouts), { concurrency: 8, discard: true });
+            yield* Effect.forEach(entries.filter((entry) => entry.isDirectory() && !entry.name.startsWith(".")), (entry) => Effect.gen(function* () {
+                const segment = parseSegment(entry.name);
+                if (typeof segment === "string")
+                    return yield* Effect.fail(new CompilerError(`${path.join(directory, entry.name)}: ${segment}`));
+                const names = [...dynamic, segment].filter(item => item.kind !== "static").map(item => item.name);
+                if (new Set(names).size !== names.length)
+                    return yield* Effect.fail(new CompilerError(`${path.join(directory, entry.name)} repeats a route parameter name.`));
+                yield* visit(path.join(directory, entry.name), path.join(relativeDir, entry.name), { layouts: ownLayouts, rendering, segments: [...context.segments, segment], ...(pathsFile ? { pathsFile } : {}) });
+            }), { concurrency: 8, discard: true });
         });
-        yield* visit(pagesRoot, "", []);
+        if (cache) {
+            // Cached pages check their named layouts against the current files, so fingerprint layouts/ up front.
+            const readLayouts = (directory) => Effect.gen(function* () {
+                for (const entry of yield* fs.entries(directory)) {
+                    const file = path.join(directory, entry.name);
+                    if (entry.isDirectory())
+                        yield* readLayouts(file);
+                    else if (entry.isFile() && entry.name.endsWith(".html"))
+                        namedLayouts.set(file, digest(yield* fs.read(file)));
+                }
+            });
+            const layoutsStat = yield* fs.stat(layoutsRoot).pipe(Effect.option);
+            if (layoutsStat._tag === "Some" && layoutsStat.value.isDirectory())
+                yield* readLayouts(layoutsRoot);
+        }
+        yield* visit(pagesRoot, "", { layouts: [], segments: [] });
         if (!routes.some((route) => route.path === "/")) {
             yield* Effect.fail(new CompilerError(`${pagesRoot} requires index.html or index.md for the root route.`));
         }
-        routes.sort((a, b) => a.path.localeCompare(b.path));
-        return { routes, files };
+        // Code-unit order is locale independent; island IDs are derived from this order.
+        routes.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+        for (let index = 1; index < routes.length; index++) {
+            if (routes[index].path === routes[index - 1].path) {
+                yield* Effect.fail(new CompilerError(`Route conflict for ${routes[index].path}: ${routes[index - 1].source} and ${routes[index].source} resolve to the same URL.`));
+            }
+        }
+        // Generated navigation depends on every route's path, labels and navigation metadata.
+        let navKey;
+        const navFor = (html, current, source) => {
+            if (!cache || !/<fuzor-nav\b/i.test(html))
+                return compileNav(html, current, routes, labels, source);
+            navKey ??= digest(JSON.stringify(routes.map(route => [route.path, labels.get(route.path) ?? null, route.metadata?.title ?? null, route.metadata?.navTitle ?? null, route.metadata?.navGroup ?? null, route.metadata?.navCategory ?? null, route.metadata?.order ?? null])));
+            const key = digest("nav", compilerVersion, navKey, current, html);
+            const cached = cache.lookup(key, currentDependency);
+            if (cached !== undefined)
+                return cached;
+            const compiled = compileNav(html, current, routes, labels, source);
+            cache.store(key, compiled);
+            return compiled;
+        };
+        const withNav = yield* Effect.try({
+            try: () => ({
+                routes: routes.map(route => ({ ...route, html: navFor(route.html, route.path, route.source) })),
+                boundaries: boundaries.map(boundary => ({ ...boundary, html: navFor(boundary.html, "", boundary.source) }))
+            }),
+            catch: error => failure(error)
+        });
+        routes.splice(0, routes.length, ...withNav.routes);
+        boundaries.splice(0, boundaries.length, ...withNav.boundaries);
+        const linkCheck = options.markdown?.linkCheck ?? "error";
+        if (!["error", "warn", "off"].includes(linkCheck)) {
+            yield* Effect.fail(new CompilerError(`markdown.linkCheck must be "error", "warn" or "off"; received ${JSON.stringify(linkCheck)}.`));
+        }
+        const warnings = [];
+        if (markdownContent.size && linkCheck !== "off") {
+            const shellFile = path.join(projectRoot, "index.html");
+            const shellAnchors = (yield* fs.exists(shellFile)) ? collectAnchors(yield* fs.read(shellFile)) : new Set();
+            const { problems, assets } = validateMarkdownLinks({ routes, markdown: markdownContent, shellAnchors, ignorePaths: options.markdown?.ignorePaths ?? [] });
+            const publicRoot = path.join(projectRoot, "public");
+            for (const asset of assets) {
+                const file = path.resolve(publicRoot, `.${asset.publicPath}`);
+                if (!file.startsWith(publicRoot + path.sep) || !(yield* fs.exists(file)))
+                    problems.push(asset.problem);
+            }
+            if (problems.length && linkCheck === "warn")
+                warnings.push(...problems.map(problem => `Broken Markdown reference: ${problem}`));
+            else if (problems.length) {
+                yield* Effect.fail(new CompilerError(`Broken Markdown references:\n${problems.map(problem => `  ${problem}`).join("\n")}\n` +
+                    `Fix the links, list paths served outside Fuzor in fuzorPlugin({ markdown: { ignorePaths: ["/api/"] } }), or set markdown.linkCheck to "warn" while migrating.`));
+            }
+        }
+        const redirects = options.redirects ? yield* Effect.try({
+            try: () => resolveRedirects(options.redirects, new Set(routes.map(route => route.path))),
+            catch: error => new CompilerError(error instanceof Error ? error.message : String(error))
+        }) : undefined;
+        boundaries.sort((a, b) => a.scope < b.scope ? -1 : a.scope > b.scope ? 1 : a.kind < b.kind ? -1 : 1);
+        cache?.complete();
+        const policyRoutes = yield* Effect.tryPromise({ try: () => resolveRoutePolicies(routes, files, projectRoot), catch: error => failure(error) });
+        return { routes: policyRoutes, ...(redirects && Object.keys(redirects).length ? { redirects } : {}), ...(boundaries.length ? { boundaries } : {}), files: [...new Set(files)].sort(), ...(platforms.size ? { platforms: [...platforms].sort() } : {}), ...(warnings.length ? { warnings } : {}) };
     });
 }
-export function compileProject(root) {
-    return Effect.runPromise(compileProjectEffect(root).pipe(Effect.provide(CompilerFileSystemLive)));
+export function compileProject(root, options = {}) {
+    const { signal, ...compileOptions } = options;
+    return Effect.runPromise(compileProjectEffect(root, compileOptions).pipe(Effect.provide(CompilerFileSystemLive)), signal ? { signal } : {});
 }
 //# sourceMappingURL=index.js.map