@pcbjs/cli 0.0.0 → 0.0.1-next.e49dd98cbe255530f38a7eb0f82a8339af65dce7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yuxuan Zhang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/boards.d.ts

@@ -0,0 +1,92 @@
+import type { SiteData } from '@pcbjs/export/site-data';
+import type { Entry } from './config.js';
+import { type Compiled } from './project.js';
+export interface BoardSlot {
+    entry: Entry;
+    /** the last good compile, one per fab target in list order, kept while a later one fails */
+    compiled: Compiled[] | null;
+    /** formatted for the viewer */
+    error: string | null;
+    /** set when an earlier entry already uses this board's name */
+    conflict: string | null;
+    /** dev: size and mtime of every file of its module graph at the last good compile */
+    stamps?: Map<string, string>;
+    /** dev: Date.now() when the last good compile finished */
+    doneAt?: number;
+}
+export declare const slotsFor: (entries: Entry[]) => BoardSlot[];
+/** The first entry to claim a board name keeps it; every later one gets a conflict naming both files. */
+export declare function markConflicts(slots: BoardSlot[]): void;
+/** In entry order; a failed compile keeps its last good board. */
+export declare const liveSlots: (slots: BoardSlot[]) => BoardSlot[];
+export declare const errorOf: (s: BoardSlot) => string | null;
+export declare function errorsByEntry(slots: BoardSlot[]): Record<string, string | null>;
+export declare const slotName: (s: BoardSlot) => string;
+export interface BoardsIndex {
+    /** one per board, or per target of a board with variants */
+    boards: {
+        name: string;
+        variant?: string;
+        title: string;
+        revision: string;
+        file: string;
+        entry: string;
+        status: string;
+    }[];
+    /** one board, however many targets it has */
+    single: boolean;
+}
+export declare function boardsIndex(compiled: Compiled[], single: boolean): BoardsIndex;
+export interface BoardsPayload {
+    boards: SiteData[];
+    single: boolean;
+    /** by entry path, in entry order */
+    errors: Record<string, string | null>;
+    /** by board name */
+    entries: Record<string, string>;
+}
+/** What the virtual module and pcbjs:boards carry; `transient`, dev's isolated preview, goes last with `transient: true`. */
+export declare function boardsPayload(slots: BoardSlot[], transient?: Compiled | null): BoardsPayload;
+interface GraphNode {
+    file: string | null;
+    importers: Set<GraphNode>;
+}
+/** Walks importers up the module graph; null when the file is not in it, so the caller recompiles everything. */
+export declare function entriesReaching(modules: Iterable<GraphNode> | undefined, entryFiles: Iterable<string>): Set<string> | null;
+/** `<name>/<file>` or `<name>/<slug>/<file>`; anything else is the legacy single-board form and goes to the first board. */
+export declare function routeEndpoint(path: string, names: string[], slugs?: Record<string, string[]>): {
+    name: string;
+    variant?: string;
+    file: string;
+} | null;
+export declare function slugsOf(slots: BoardSlot[]): Record<string, string[]>;
+/** Vite's `moduleGraph`, or a stand-in in the tests. */
+export interface ModuleLookup {
+    getModulesByFile(file: string): Iterable<GraphNode> | undefined;
+}
+export interface FocusTarget {
+    /** the only live board holding the file, the viewer's own when it is one of several, else the first; null when none */
+    board: string | null;
+    /** or of the first entry that imports the file when none of them has a live board */
+    entry: string | null;
+    /** in entry order */
+    boards: string[];
+}
+/** A shared file never moves a viewer off `current`; an entry file always reaches its own board, also before the first compile. */
+export declare function focusTarget(graph: ModuleLookup | undefined, slots: BoardSlot[], file: string, current?: string | null): FocusTarget;
+export interface IdeBoard {
+    name: string;
+    title: string;
+    entry: string;
+    targets: string[];
+    status: 'ok' | 'error' | 'incomplete';
+    draft?: true;
+    skipped?: number;
+}
+/** One per entry with a board of its own; `error` marks a last good board, `incomplete` DRC errors or unconnected nets. */
+export declare function ideBoards(slots: BoardSlot[]): {
+    boards: IdeBoard[];
+    single: boolean;
+    errors: Record<string, string | null>;
+};
+export {};

package/dist/boards.js

@@ -0,0 +1,126 @@
+import { boardFile } from './project.js';
+import { variantSlug } from '@pcbjs/core/variants';
+export const slotsFor = (entries) => entries.map(entry => ({ entry, compiled: null, error: null, conflict: null }));
+/** The first entry to claim a board name keeps it; every later one gets a conflict naming both files. */
+export function markConflicts(slots) {
+    const owner = new Map();
+    for (const s of slots) {
+        s.conflict = null;
+        if (!s.compiled)
+            continue;
+        const name = s.compiled[0].board.name;
+        const first = owner.get(name);
+        if (first)
+            s.conflict = `board name "${name}" is used by both ${first.entry.rel} and ${s.entry.rel}`;
+        else
+            owner.set(name, s);
+    }
+}
+/** In entry order; a failed compile keeps its last good board. */
+export const liveSlots = (slots) => slots.filter(s => s.compiled && !s.conflict);
+export const errorOf = (s) => s.error ?? s.conflict;
+export function errorsByEntry(slots) {
+    const out = {};
+    for (const s of slots)
+        out[s.entry.rel] = errorOf(s);
+    return out;
+}
+export const slotName = (s) => s.compiled[0].board.name;
+export function boardsIndex(compiled, single) {
+    return {
+        boards: compiled.map(c => ({
+            name: c.board.name, ...(c.board.variant ? { variant: c.board.variant.name } : {}), title: c.board.title, revision: c.board.revision,
+            file: boardFile(c.board), entry: c.entry.rel, status: c.site.fab.status,
+        })),
+        single,
+    };
+}
+/** What the virtual module and pcbjs:boards carry; `transient`, dev's isolated preview, goes last with `transient: true`. */
+export function boardsPayload(slots, transient) {
+    const live = liveSlots(slots);
+    return {
+        boards: [...live.flatMap(s => s.compiled.map(c => c.site)), ...(transient ? [{ ...transient.site, transient: true }] : [])], single: slots.length === 1, errors: errorsByEntry(slots),
+        entries: Object.fromEntries(live.map(s => [slotName(s), s.entry.rel])),
+    };
+}
+/** Walks importers up the module graph; null when the file is not in it, so the caller recompiles everything. */
+export function entriesReaching(modules, entryFiles) {
+    const start = modules ? [...modules] : [];
+    if (!start.length)
+        return null;
+    const entries = new Set(entryFiles);
+    const hit = new Set();
+    const seen = new Set();
+    const stack = start;
+    while (stack.length) {
+        const m = stack.pop();
+        if (seen.has(m))
+            continue;
+        seen.add(m);
+        if (m.file && entries.has(m.file))
+            hit.add(m.file);
+        for (const i of m.importers)
+            stack.push(i);
+    }
+    return hit;
+}
+/** `<name>/<file>` or `<name>/<slug>/<file>`; anything else is the legacy single-board form and goes to the first board. */
+export function routeEndpoint(path, names, slugs = {}) {
+    const i = path.indexOf('/');
+    let name, rest;
+    if (i > 0 && names.includes(decodeURIComponent(path.slice(0, i)))) {
+        name = decodeURIComponent(path.slice(0, i));
+        rest = path.slice(i + 1);
+    }
+    else if (names.length) {
+        name = names[0];
+        rest = path;
+    }
+    else
+        return null;
+    const targets = slugs[name];
+    if (!targets?.length)
+        return { name, file: decodeURIComponent(rest) };
+    const j = rest.indexOf('/');
+    const head = j > 0 ? decodeURIComponent(rest.slice(0, j)) : null;
+    if (head !== null && targets.includes(head))
+        return { name, variant: head, file: decodeURIComponent(rest.slice(j + 1)) };
+    return { name, variant: targets[0], file: decodeURIComponent(rest) };
+}
+export function slugsOf(slots) {
+    const out = {};
+    for (const s of liveSlots(slots)) {
+        const v = s.compiled[0].board.variant;
+        if (v)
+            out[slotName(s)] = v.names.map(variantSlug);
+    }
+    return out;
+}
+/** A shared file never moves a viewer off `current`; an entry file always reaches its own board, also before the first compile. */
+export function focusTarget(graph, slots, file, current = null) {
+    const hit = entriesReaching(graph?.getModulesByFile(file), slots.map(s => s.entry.file)) ?? new Set();
+    if (slots.some(s => s.entry.file === file))
+        hit.add(file);
+    const reached = slots.filter(s => hit.has(s.entry.file));
+    const live = reached.filter(s => s.compiled && !s.conflict);
+    const names = live.map(slotName);
+    const board = current != null && names.includes(current) ? current : names[0] ?? null;
+    const at = board ? live[names.indexOf(board)] : reached[0];
+    return { board, entry: at ? at.entry.rel : null, boards: names };
+}
+/** One per entry with a board of its own; `error` marks a last good board, `incomplete` DRC errors or unconnected nets. */
+export function ideBoards(slots) {
+    return {
+        boards: liveSlots(slots).map(s => {
+            const c = s.compiled;
+            return {
+                name: slotName(s), title: c[0].board.title || slotName(s), entry: s.entry.rel,
+                targets: c.flatMap(t => (t.board.variant ? [t.board.variant.name] : [])),
+                status: s.error ? 'error' : c.some(t => t.site.fab.status !== 'ok') ? 'incomplete' : 'ok',
+                ...(c[0].site.draft ? { draft: true, skipped: c[0].site.draft.skipped } : {}),
+            };
+        }),
+        single: slots.length === 1,
+        errors: errorsByEntry(slots),
+    };
+}

package/dist/bridge.d.ts

@@ -0,0 +1,53 @@
+import type { Connect, ViteDevServer } from 'vite';
+import { type HostClient } from './host-client.js';
+export interface CursorEvent {
+    file: string;
+    line: number;
+    col: number;
+    target?: CursorTarget;
+}
+/** What the code under the cursor names, per board, from the language server; absent without one. */
+export interface CursorTarget {
+    kind: string;
+    boards: {
+        board: string;
+        ids: number[];
+        refs: string[];
+        points?: [number, number][];
+        reference?: string;
+        name: string;
+    }[];
+}
+export interface SelectEvent {
+    file: string;
+    line: number;
+    col: number;
+    endLine: number;
+    endCol: number;
+}
+/** A path as given by an editor or the viewer, absolute or relative to the root, both ways. */
+export declare function normalizeFile(root: string, file: string): {
+    abs: string;
+    rel: string;
+};
+export interface IdeBridge {
+    connected(): number;
+    middleware: Connect.NextHandleFunction;
+    cursor(file: string, line: unknown, col: unknown, target?: CursorTarget): void;
+    lastCursor(): CursorEvent | null;
+}
+export interface BridgeOptions {
+    /** gets selections ahead of the bridges while connected */
+    host?: () => HostClient | null;
+    /** an absolute or root-relative file */
+    onFocus?: (file: string) => void;
+    onClose?: (file: string) => void;
+    /** keyed 'host' or by Vite socket; a session that takes `pcbjs/select` gets it instead of `pcbjs:ide:select` */
+    lsp?: {
+        select(key: unknown, sel: SelectEvent): boolean;
+        keys(): unknown[];
+        padSource?(board: string, ref: string, num: string): SelectEvent | undefined;
+    };
+}
+/** Register the bridge events on the server's WebSocket and return the /__pcbjs/{cursor,open,ide} middleware. */
+export declare function ideBridge(server: ViteDevServer, rootOf: string | (() => string), opts?: BridgeOptions): IdeBridge;

package/dist/bridge.js

@@ -0,0 +1,147 @@
+// Editor bridges over Vite's HMR socket and the /__pcbjs HTTP endpoints. docs/ide-bridge.md has the protocol.
+import { existsSync } from 'node:fs';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import launch from 'launch-editor';
+import { helloWarning, parseHello } from './host-client.js';
+/** A path as given by an editor or the viewer, absolute or relative to the root, both ways. */
+export function normalizeFile(root, file) {
+    const abs = isAbsolute(file) ? resolve(file) : resolve(root, file);
+    return { abs, rel: relative(root, abs).split(sep).join('/') };
+}
+const int = (v, d) => {
+    const n = Number(v);
+    return Number.isFinite(n) && n >= 1 ? Math.floor(n) : d;
+};
+function readBody(req, limit = 64 * 1024) {
+    return new Promise((ok, fail) => {
+        let size = 0;
+        const chunks = [];
+        req.on('data', (c) => { size += c.length; if (size > limit) {
+            fail(new Error('body too large'));
+            req.destroy();
+        }
+        else
+            chunks.push(c); });
+        req.on('end', () => ok(Buffer.concat(chunks).toString('utf8')));
+        req.on('error', fail);
+    });
+}
+/** Register the bridge events on the server's WebSocket and return the /__pcbjs/{cursor,open,ide} middleware. */
+export function ideBridge(server, rootOf, opts = {}) {
+    // a workspace dev server passes the root of the displayed scope, which changes with it
+    const fixedRoot = typeof rootOf === 'string' ? rootOf : null;
+    const root = () => fixedRoot ?? rootOf();
+    const bridges = new Map();
+    let last = null;
+    const broadcastCursor = (file, line, col, target) => {
+        const data = { file: normalizeFile(root(), file).rel, line: int(line, 1), col: int(col, 1), ...(target ? { target } : {}) };
+        last = data;
+        server.ws.send({ type: 'custom', event: 'pcbjs:cursor', data });
+    };
+    server.ws.on('pcbjs:ide:hello', (data, client) => {
+        const known = bridges.has(client.socket);
+        const hello = parseHello(data);
+        bridges.set(client.socket, { client, ...hello });
+        // a repeated hello is the bridge's heartbeat
+        if (!known) {
+            client.socket.once('close', () => bridges.delete(client.socket));
+            server.config.logger.info(`[pcbjs] ide bridge connected: ${hello.name} ${hello.version}`.trimEnd(), { timestamp: true });
+            const w = helloWarning(hello);
+            if (w)
+                server.config.logger.warn(w, { timestamp: true });
+        }
+    });
+    server.ws.on('pcbjs:ide:bye', (_data, client) => { bridges.delete(client.socket); });
+    server.ws.on('pcbjs:ide:cursor', (data) => {
+        if (data && typeof data.file === 'string')
+            broadcastCursor(data.file, data.line, data.col);
+    });
+    server.ws.on('pcbjs:ide:focus', (data) => {
+        if (data && typeof data.file === 'string' && data.file)
+            opts.onFocus?.(data.file);
+    });
+    server.ws.on('pcbjs:ide:close', (data) => {
+        if (data && typeof data.file === 'string' && data.file)
+            opts.onClose?.(data.file);
+    });
+    // a file the editor may open: inside a directory Vite is allowed to serve, which holds the project root
+    const allowed = (abs) => [root(), ...server.config.server.fs.allow].some(d => abs === d || abs.startsWith(d.endsWith(sep) ? d : d + sep));
+    const middleware = (req, res, next) => {
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        const p = url.pathname;
+        if (p === '/__pcbjs/ide') {
+            res.setHeader('content-type', 'application/json');
+            const host = opts.host?.();
+            res.end(JSON.stringify({
+                connected: bridges.size, clients: [...bridges.values()].map(b => ({ name: b.name, version: b.version, protocol: b.protocol, major: b.major })),
+                host: host ? { connected: host.connected(), ...(host.hello() ?? {}) } : null,
+            }));
+            return;
+        }
+        if (p === '/__pcbjs/cursor') {
+            if (req.method !== 'POST') {
+                res.statusCode = 405;
+                res.setHeader('allow', 'POST');
+                res.end();
+                return;
+            }
+            readBody(req).then(text => {
+                const body = JSON.parse(text || '{}');
+                if (typeof body.file !== 'string' || !body.file) {
+                    res.statusCode = 400;
+                    res.end('file required');
+                    return;
+                }
+                broadcastCursor(body.file, body.line, body.col);
+                res.statusCode = 204;
+                res.end();
+            }).catch(e => { res.statusCode = 400; res.end(String(e?.message ?? e)); });
+            return;
+        }
+        if (p === '/__pcbjs/open') {
+            const q = url.searchParams;
+            const f = q.get('file');
+            if (!f) {
+                res.statusCode = 400;
+                res.end('file required');
+                return;
+            }
+            const { abs } = normalizeFile(root(), f);
+            if (!allowed(abs) || !existsSync(abs)) {
+                res.statusCode = 404;
+                res.end('not found');
+                return;
+            }
+            const line = int(q.get('line'), 1), col = int(q.get('col'), 1);
+            // a pad goes to its key in the part's connect call when the language server finds one
+            const pad = /^(.+)\.([^.]+)$/.exec(q.get('pad') ?? '');
+            const sel = (pad && opts.lsp?.padSource?.(q.get('board') ?? '', pad[1], pad[2])) || { file: abs, line, col, endLine: int(q.get('endLine'), line), endCol: int(q.get('endCol'), col) };
+            // the editor host first, then clients on the Vite socket, then launch-editor
+            const host = opts.host?.();
+            const lspKeys = (opts.lsp?.keys() ?? []).filter(k => k !== 'host' && !bridges.has(k));
+            if (host?.connected() && (opts.lsp?.select('host', sel) || host.send('pcbjs:ide:select', sel))) {
+                res.setHeader('x-pcbjs-opened', 'host');
+            }
+            else if (bridges.size || lspKeys.length) {
+                for (const b of bridges.values())
+                    if (!opts.lsp?.select(b.client.socket, sel))
+                        b.client.send({ type: 'custom', event: 'pcbjs:ide:select', data: sel });
+                for (const k of lspKeys)
+                    opts.lsp.select(k, sel);
+                res.setHeader('x-pcbjs-opened', 'ide');
+            }
+            else {
+                // as Vite's /__open-in-editor
+                launch(`${abs}:${line}:${col}`, (file, err) => {
+                    server.config.logger.warn(`[pcbjs] could not open ${file} in an editor${err ? ': ' + err : ''}`, { timestamp: true });
+                });
+                res.setHeader('x-pcbjs-opened', 'editor');
+            }
+            res.statusCode = 204;
+            res.end();
+            return;
+        }
+        next();
+    };
+    return { connected: () => bridges.size, middleware, cursor: broadcastCursor, lastCursor: () => last };
+}

package/dist/build.d.ts

@@ -0,0 +1,21 @@
+import { type PluginState } from './plugin.js';
+import { boardsPayload } from './boards.js';
+import { type OutputOptions } from './check.js';
+export interface BuildOptions extends OutputOptions {
+    entries?: string[];
+    root?: string;
+    config?: string;
+    outDir?: string;
+    date?: string;
+}
+export declare function build(opts: BuildOptions): Promise<void>;
+/** The boards a built site carries: every entry's, never the isolated preview of dev. */
+export declare const buildPayload: (state: PluginState) => ReturnType<typeof boardsPayload>;
+/** True for a base that names the site's URL path, such as `/` or `/repo/`, which prerendering needs. */
+export declare const isAbsoluteBase: (base: string) => boolean;
+/** Render every route with the SSR bundle to `<outDir>/<route>/index.html` and 404.html; returns the routes written. */
+export declare function prerenderSite(bundle: string, outDir: string, base: string, data: ReturnType<typeof boardsPayload>): Promise<string[]>;
+export declare function preview(opts: BuildOptions & {
+    port?: number;
+    host?: string | boolean;
+}): Promise<void>;

package/dist/build.js

@@ -0,0 +1,165 @@
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { build as viteBuild, preview as vitePreview } from 'vite';
+import { resolveConfig } from './config.js';
+import { CLIENT_DIR, viteConfig } from './vite.js';
+import { pluginState } from './plugin.js';
+import { boardDir, boardFile, writeFab } from './project.js';
+import { boardsIndex, boardsPayload } from './boards.js';
+import { CHECK_CAP, compileServer, compileSlots, errorText, logLevelFor, markStale, reportOf, slotLines, slotsFailed, totalLine, writeReport } from './check.js';
+import { msText } from '@pcbjs/export/findings';
+import { fabDate } from '@pcbjs/export/fab';
+import { pageHtml, previewPrerendered, safeSegment, scriptJson, siteRoutes } from './prerender.js';
+import { resolveRepo } from './repo.js';
+export async function build(opts) {
+    // createServer would set NODE_ENV to development, giving the builds below Vue's development build
+    process.env.NODE_ENV ??= 'production';
+    const cfg = await resolveConfig(opts.entries ?? [], 'build', opts.config, opts.root);
+    if (opts.outDir)
+        cfg.outDir = resolve(cfg.root, opts.outDir);
+    // one date for every file of every set: --date, else SOURCE_DATE_EPOCH, else now, see fabDate
+    cfg.fabDate = fabDate(opts.date);
+    // every fab set written is read back and compared with its board, see fab-check.ts in @pcbjs/export
+    cfg.fabCheck = true;
+    const state = pluginState(cfg);
+    const say = (line) => { if (!opts.quiet)
+        console.log(line); };
+    const rel = (p) => relative(cfg.root, p) || '.';
+    // a failed entry does not stop the others
+    const errors = new Map();
+    const server = await compileServer(cfg, state, { verbose: opts.verbose });
+    try {
+        await compileSlots(server, cfg, state.slots, errors);
+    }
+    finally {
+        await server.close();
+    }
+    const broken = state.slots.filter(s => !s.compiled || s.conflict);
+    // every entry: one per board, one per target of a board with variants
+    const all = state.slots.filter(s => s.compiled && !s.conflict).flatMap(s => s.compiled);
+    // the repository link for cmd+click on a source range, built sites only
+    const repo = resolveRepo(cfg.repo, cfg.root);
+    if (repo)
+        for (const c of all)
+            c.site.repo = repo;
+    // a failed entry keeps its last fab set, marked stale
+    if (!broken.length)
+        rmSync(cfg.fabDir, { recursive: true, force: true });
+    const fabs = new Map();
+    for (const c of all) {
+        const dir = join(cfg.fabDir, ...boardDir(c.board));
+        if (broken.length)
+            rmSync(dir, { recursive: true, force: true });
+        const names = writeFab(c, dir);
+        fabs.set(c, { dir, zip: join(dir, c.fab.zipName), files: names.length });
+    }
+    const more = opts.json ? `all in ${opts.json}` : 'all with --json <file>';
+    for (const s of state.slots)
+        for (const l of slotLines(s, errors.get(s), { root: cfg.root, cap: CHECK_CAP, verbose: opts.verbose, more }))
+            console.log(l);
+    const files = [...fabs.values()].reduce((n, f) => n + f.files, 0);
+    if (all.length)
+        say(`fab    ${rel(cfg.fabDir)}  ${all.length} set${all.length === 1 ? '' : 's'}, ${files} files`);
+    const report = (pages) => {
+        if (!opts.json)
+            return;
+        const boards = state.slots.flatMap(s => reportOf(cfg, s, errors.get(s), { pages, fab: c => fabs.get(c) ?? null }));
+        console.log(`json   ${writeReport(cfg, opts.json, { boards })}`);
+    };
+    if (broken.length) {
+        for (const s of broken) {
+            if (s.conflict)
+                continue;
+            const marked = markStale(cfg, s.entry.rel, errorText(errors.get(s), false, cfg.root).line);
+            if (marked.length)
+                say(`stale  ${marked.join(', ')}`);
+        }
+        say(`site   not rebuilt: ${broken.length} entr${broken.length === 1 ? 'y' : 'ies'} failed, ${rel(cfg.outDir)} is from an earlier build`);
+        console.log(totalLine(state.slots));
+        report([]);
+        process.exitCode = 1;
+        return;
+    }
+    // a relative base cannot name the routes' URLs, so only an absolute one is prerendered
+    const t0 = performance.now();
+    const vc = viteConfig(cfg, state, 'build');
+    const logLevel = logLevelFor(cfg, opts.verbose);
+    const prerender = isAbsoluteBase(cfg.base);
+    if (!prerender)
+        say(`site   base "${cfg.base}" is relative: client-rendered pages only, set an absolute base such as "/" to prerender every route`);
+    state.inline = !prerender;
+    await viteBuild({ ...vc, logLevel, mode: 'production', build: { ...vc.build, manifest: true } });
+    let pages = [];
+    if (prerender) {
+        const ssrDir = join(cfg.root, '.pcbjs', 'cache', 'ssr');
+        await viteBuild({
+            ...vc, mode: 'production', logLevel: logLevel === 'info' ? 'warn' : logLevel,
+            // everything is bundled, Vue included, so the bundle runs from the cache without the project resolving the client's dependencies
+            ssr: { ...vc.ssr, noExternal: true },
+            build: { ...vc.build, ssr: join(CLIENT_DIR, 'src', 'entry-server.ts'), outDir: ssrDir, emptyOutDir: true, copyPublicDir: false, rollupOptions: { output: { entryFileNames: 'entry-server.mjs', format: 'es' } } },
+        });
+        const data = buildPayload(state);
+        pages = await prerenderSite(join(ssrDir, 'entry-server.mjs'), cfg.outDir, cfg.base, data);
+        if (opts.verbose)
+            say(`pages  ${pages.length} prerendered: ${pages.map(p => '/' + p).join(' ')}`);
+    }
+    cpSync(cfg.fabDir, join(cfg.outDir, 'fab'), { recursive: true });
+    mkdirSync(join(cfg.outDir, 'boards'), { recursive: true });
+    for (const c of all) {
+        const file = join(cfg.outDir, ...boardFile(c.board).split('/').map(decodeURIComponent));
+        mkdirSync(join(file, '..'), { recursive: true });
+        writeFileSync(file, JSON.stringify(c.site));
+    }
+    writeFileSync(join(cfg.outDir, 'boards.json'), JSON.stringify(boardsIndex(all, state.slots.length === 1), null, 2));
+    const n = state.slots.length, targets = all.length > n ? `, ${all.length} entries` : '';
+    say(`site   ${rel(cfg.outDir)}  ${n} board${n === 1 ? '' : 's'}${targets}${prerender ? `, ${pages.length} pages` : ''}  ${msText(performance.now() - t0)}`);
+    console.log(totalLine(state.slots));
+    report(pages);
+    if (slotsFailed(state.slots))
+        process.exitCode = 1;
+}
+/** The boards a built site carries: every entry's, never the isolated preview of dev. */
+export const buildPayload = (state) => boardsPayload(state.slots);
+/** True for a base that names the site's URL path, such as `/` or `/repo/`, which prerendering needs. */
+export const isAbsoluteBase = (base) => base.startsWith('/');
+/** Render every route with the SSR bundle to `<outDir>/<route>/index.html` and 404.html; returns the routes written. */
+export async function prerenderSite(bundle, outDir, base, data) {
+    const { render } = await import(pathToFileURL(bundle).href + `?t=${Date.now()}`);
+    const template = readFileSync(join(outDir, 'index.html'), 'utf8');
+    const json = scriptJson(data);
+    const b = base.endsWith('/') ? base : base + '/';
+    const written = [];
+    // the root last, since the template is the root's index.html
+    const routes = siteRoutes(data);
+    for (const segs of [...routes.slice(1), routes[0]]) {
+        if (!segs.every(safeSegment)) {
+            console.warn(`pcbjs: no page for ${segs.join('/')}, the name cannot be a directory; the site still shows it from another page`);
+            continue;
+        }
+        const url = b + segs.map(encodeURIComponent).join('/');
+        const r = await render(url, data);
+        const dir = join(outDir, ...segs);
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, 'index.html'), pageHtml(template, json, r));
+        written.push(segs.join('/'));
+    }
+    // static hosts such as GitHub Pages answer an unknown path with 404.html; the app then shows its own "no such board" page
+    writeFileSync(join(outDir, '404.html'), pageHtml(template, json));
+    return written;
+}
+export async function preview(opts) {
+    const cfg = await resolveConfig(opts.entries ?? [], 'build', opts.config, opts.root);
+    if (opts.outDir)
+        cfg.outDir = resolve(cfg.root, opts.outDir);
+    if (!existsSync(cfg.outDir))
+        throw new Error(`${cfg.outDir} does not exist: run pcbjs build first`);
+    const vc = viteConfig(cfg, pluginState(cfg), 'build');
+    // a prerendered site is served as a static host serves it, a client-rendered one with Vite's index.html fallback
+    const prerendered = existsSync(join(cfg.outDir, '404.html')) && isAbsoluteBase(cfg.base);
+    const server = await vitePreview({
+        ...vc, preview: { port: opts.port ?? 4173, host: opts.host },
+        ...(prerendered ? { appType: 'mpa', plugins: [...(vc.plugins ?? []), previewPrerendered(cfg.outDir, cfg.base)] } : {}),
+    });
+    server.printUrls();
+}