@bytesbrains/weblocks 0.2.0

package/lib/generate.d.ts

@@ -0,0 +1,35 @@
+import { type BatchResult, type EditOp } from './ops.js';
+import type { SiteManifest } from './types.js';
+export type ModelCall = (args: {
+    system: string;
+    user: string;
+}) => Promise<string>;
+export declare function buildGenerationPrompt(brief: string): {
+    system: string;
+    user: string;
+};
+export interface ComposeResult {
+    ok: boolean;
+    manifest: SiteManifest;
+    errors: string[];
+    warnings: string[];
+}
+/** Compose a manifest from a brief using the injected model. */
+export declare function generateSite(brief: string, callModel: ModelCall): Promise<ComposeResult>;
+/** Extract + coerce + validate a manifest from a model reply. Never throws. */
+export declare function parseManifestResponse(text: string): ComposeResult;
+export declare function buildEditPrompt(manifest: SiteManifest, message: string): {
+    system: string;
+    user: string;
+};
+export interface EditResult extends BatchResult {
+    parsedOps: EditOp[];
+    parseError?: string;
+}
+/** Interpret a natural-language edit against the manifest via the injected model. */
+export declare function editSite(manifest: SiteManifest, message: string, callModel: ModelCall): Promise<EditResult>;
+/** Extract a JSON array of ops from a model reply. */
+export declare function parseOpsResponse(text: string): {
+    ops: EditOp[];
+    error?: string;
+};

package/lib/generate.js

@@ -0,0 +1,160 @@
+/**
+ * AI compose + edit orchestration.
+ *
+ * The deterministic parts live here — building the prompt from the catalog,
+ * extracting/validating the model's JSON, and turning an edit reply into
+ * validated ops. The actual model call is INJECTED (`ModelCall`) — bring your
+ * own provider — so this stays provider-agnostic and unit-testable with a fake.
+ * Validity comes from the schema + ops, never from the model being right
+ * (invariant: validity ⟂ AI quality).
+ */
+import { catalogPrompt } from './catalog.js';
+import { blockTypes } from './registry.js';
+import { presetNames } from './presets.js';
+import { normalizeTokens, DEFAULT_TOKENS } from './tokens.js';
+import { validateManifest } from './validate.js';
+import { applyOps } from './ops.js';
+// ── Compose: brief → manifest ──────────────────────────────────────────────────
+export function buildGenerationPrompt(brief) {
+    const system = [
+        'You are a web designer that composes a single-page site by ARRANGING pre-built blocks.',
+        'You do NOT write HTML, CSS, or JavaScript. You output ONLY a JSON site manifest.',
+        '',
+        'Available blocks (config keys; `*` = should be provided):',
+        catalogPrompt(),
+        '',
+        'Also set `design` tokens: { mode: light|dark|auto, palette:{bg,surface,text,muted,primary,accent (hex)},',
+        '  typography:{fontStack,scale: compact|default|expressive}, radius: sharp|soft|round,',
+        '  spacing: tight|default|airy, motion: none|subtle|lively }.',
+        '  mode:auto follows the viewer\'s OS light/dark; supply an optional darkPalette:{...same keys...} for the dark side.',
+        '  (Text on primary/accent fills is auto-contrasted — never hand-set button text colours.)',
+        `  (For a quick coherent look, base it on a named preset: ${presetNames().join(', ')}.)`,
+        '',
+        'Rules:',
+        '- Use ONLY the block types listed above; never invent a type or a config key.',
+        '- Write real, specific copy for the described business — no lorem ipsum, no placeholders.',
+        '- Order blocks top-to-bottom as a visitor would read them.',
+        'Respond with ONLY the JSON object, no prose, no code fences:',
+        '{ "meta": { "title", "description", "lang" }, "design": {...}, "blocks": [ { "type", "config": {...} } ] }',
+    ].join('\n');
+    return { system, user: `Brief:\n${brief}` };
+}
+/** Compose a manifest from a brief using the injected model. */
+export async function generateSite(brief, callModel) {
+    const { system, user } = buildGenerationPrompt(brief);
+    const raw = await callModel({ system, user });
+    return parseManifestResponse(raw);
+}
+/** Extract + coerce + validate a manifest from a model reply. Never throws. */
+export function parseManifestResponse(text) {
+    const json = extractJson(text);
+    if (json === undefined)
+        return { ok: false, manifest: emptyManifest(), errors: ['no JSON object in model reply'], warnings: [] };
+    const manifest = coerceManifest(json);
+    const v = validateManifest(manifest);
+    return { ok: v.ok, manifest, errors: v.errors, warnings: v.warnings };
+}
+// ── Edit: message + manifest → ops → new manifest ──────────────────────────────
+export function buildEditPrompt(manifest, message) {
+    const outline = manifest.blocks.map((b, i) => `  ${i}. ${b.id} (${b.type})`).join('\n') || '  (empty)';
+    const system = [
+        'You edit a single-page site by emitting JSON EDIT OPERATIONS over its blocks. You never write HTML/CSS/JS.',
+        '',
+        'Ops (emit a JSON array):',
+        '- { "op":"addBlock", "type":..., "config":{...}, "at":<index?> }',
+        '- { "op":"updateBlock", "id":..., "config":{ ...only changed keys... } }',
+        '- { "op":"removeBlock", "id":... }',
+        '- { "op":"moveBlock", "id":..., "to":<index> }',
+        '- { "op":"setVisible", "id":..., "visible":true|false }',
+        '- { "op":"setDesignTokens", "patch":{ ...design keys... } }',
+        '- { "op":"setMeta", "patch":{ title?, description?, lang? } }',
+        '// Surgical array-item edits — change ONE item without resending the block:',
+        '- { "op":"addItem", "id":..., "field":"items", "item":{...}, "at":<index?> }',
+        '- { "op":"updateItem", "id":..., "field":"items", "index":<n>, "patch":{...} }',
+        '- { "op":"removeItem", "id":..., "field":"items", "index":<n> }',
+        '- { "op":"moveItem", "id":..., "field":"items", "from":<n>, "to":<n> }',
+        '// Theming:',
+        `- { "op":"applyPreset", "name":"<one of: ${presetNames().join(' | ')}>" }`,
+        '- { "op":"setOverrides", "id":..., "overrides":{ primary?, accent?, bg?, surface?, text?, muted?, radius?, spacing? } | null }',
+        '',
+        `Block types available: ${blockTypes().join(', ')}.`,
+        'Block configs (for add/update):',
+        catalogPrompt(),
+        '',
+        'Current page blocks (top→bottom):',
+        outline,
+        '',
+        'Emit ONLY the JSON array of ops needed for the request. Empty array [] if nothing to do.',
+    ].join('\n');
+    return { system, user: message };
+}
+/** Interpret a natural-language edit against the manifest via the injected model. */
+export async function editSite(manifest, message, callModel) {
+    const { system, user } = buildEditPrompt(manifest, message);
+    const raw = await callModel({ system, user });
+    const { ops, error } = parseOpsResponse(raw);
+    const batch = applyOps(manifest, ops);
+    return { ...batch, parsedOps: ops, parseError: error };
+}
+/** Extract a JSON array of ops from a model reply. */
+export function parseOpsResponse(text) {
+    const json = extractJson(text, 'array');
+    if (json === undefined)
+        return { ops: [], error: 'no JSON array in model reply' };
+    if (!Array.isArray(json))
+        return { ops: [], error: 'expected a JSON array of ops' };
+    const ops = json.filter((o) => !!o && typeof o === 'object' && typeof o.op === 'string');
+    return { ops };
+}
+// ── helpers ────────────────────────────────────────────────────────────────────
+function extractJson(text, want = 'object') {
+    const t = (text ?? '').trim().replace(/^```[a-zA-Z]*\r?\n?/, '').replace(/\r?\n?```$/, '').trim();
+    const open = want === 'array' ? '[' : '{';
+    const close = want === 'array' ? ']' : '}';
+    const start = t.indexOf(open);
+    const end = t.lastIndexOf(close);
+    if (start < 0 || end <= start)
+        return undefined;
+    try {
+        return JSON.parse(t.slice(start, end + 1));
+    }
+    catch {
+        return undefined;
+    }
+}
+function coerceManifest(raw) {
+    const r = (raw && typeof raw === 'object') ? raw : {};
+    const meta = (r.meta && typeof r.meta === 'object') ? r.meta : {};
+    const rawBlocks = Array.isArray(r.blocks) ? r.blocks : [];
+    const used = new Set();
+    const blocks = rawBlocks.map((b) => {
+        const bb = (b && typeof b === 'object') ? b : {};
+        const type = typeof bb.type === 'string' ? bb.type : '';
+        let id = typeof bb.id === 'string' && bb.id ? bb.id : '';
+        if (!id || used.has(id)) {
+            let n = 1;
+            while (used.has(`${type || 'block'}-${n}`))
+                n++;
+            id = `${type || 'block'}-${n}`;
+        }
+        used.add(id);
+        return {
+            id, type,
+            visible: bb.visible !== false,
+            config: (bb.config && typeof bb.config === 'object') ? bb.config : {},
+        };
+    });
+    return {
+        meta: {
+            title: typeof meta.title === 'string' ? meta.title : 'Untitled site',
+            description: typeof meta.description === 'string' ? meta.description : '',
+            lang: typeof meta.lang === 'string' ? meta.lang : 'en',
+        },
+        design: normalizeTokens((r.design ?? DEFAULT_TOKENS)),
+        blocks,
+        version: typeof r.version === 'number' ? r.version : 1,
+    };
+}
+function emptyManifest() {
+    return { meta: { title: 'Untitled site', description: '', lang: 'en' }, design: DEFAULT_TOKENS, blocks: [], version: 1 };
+}

package/lib/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @bytesbrains/weblocks — the block engine for AI-composable Apps.
+ *
+ * Pipeline: a `SiteManifest` (design tokens + ordered typed blocks) is
+ * validated (strict, for edit ops) and rendered (total, for serving) into one
+ * self-contained static HTML document. See docs/APPS_BLOCKS_ARCHITECTURE.md.
+ */
+export type { SiteManifest, Block, DesignTokens, Palette, SiteMeta, SectionOverrides, PwaConfig, SeoConfig, Mode, Scale, Radius, Spacing, Motion, } from './types.js';
+export { DEFAULT_TOKENS, normalizeTokens, tokensToCss, sectionOverrideCss, readableOn } from './tokens.js';
+export { PRESETS, presetNames, getPreset } from './presets.js';
+export { REGISTRY, getSpec, blockTypes, needsIsland, type BlockSpec, type RenderContext } from './registry.js';
+export { renderSite, type RenderOptions } from './render.js';
+export { NOOP_RUNTIME, pathRuntime, runtimeNeeds, type RuntimeAdapter, type RuntimeAction, type BlockRuntimeNeeds, } from './runtime.js';
+export { buildWebManifest, buildWebManifestJson, buildServiceWorker, emitPwa, type WebAppManifest, } from './pwa.js';
+export { validateBlock, validateManifest, type Validation } from './validate.js';
+export { parse, escapeHtml, escapeAttr, sanitizeUrl, type Field, type Schema, type ParseResult } from './schema.js';
+export { catalog, catalogPrompt, type BlockCatalogEntry, type JsonSchema } from './catalog.js';
+export { applyOp, applyOps, type EditOp, type OpResult, type BatchResult } from './ops.js';
+export { generateSite, editSite, buildGenerationPrompt, buildEditPrompt, parseManifestResponse, parseOpsResponse, type ModelCall, type ComposeResult, type EditResult, } from './generate.js';

package/lib/index.js

@@ -0,0 +1,11 @@
+export { DEFAULT_TOKENS, normalizeTokens, tokensToCss, sectionOverrideCss, readableOn } from './tokens.js';
+export { PRESETS, presetNames, getPreset } from './presets.js';
+export { REGISTRY, getSpec, blockTypes, needsIsland } from './registry.js';
+export { renderSite } from './render.js';
+export { NOOP_RUNTIME, pathRuntime, runtimeNeeds, } from './runtime.js';
+export { buildWebManifest, buildWebManifestJson, buildServiceWorker, emitPwa, } from './pwa.js';
+export { validateBlock, validateManifest } from './validate.js';
+export { parse, escapeHtml, escapeAttr, sanitizeUrl } from './schema.js';
+export { catalog, catalogPrompt } from './catalog.js';
+export { applyOp, applyOps } from './ops.js';
+export { generateSite, editSite, buildGenerationPrompt, buildEditPrompt, parseManifestResponse, parseOpsResponse, } from './generate.js';

package/lib/ops.d.ts

@@ -0,0 +1,85 @@
+import type { DesignTokens, SectionOverrides, SiteManifest, SiteMeta } from './types.js';
+export type EditOp = {
+    op: 'addBlock';
+    type: string;
+    config?: Record<string, unknown>;
+    at?: number;
+    id?: string;
+} | {
+    op: 'updateBlock';
+    id: string;
+    config: Record<string, unknown>;
+} | {
+    op: 'removeBlock';
+    id: string;
+} | {
+    op: 'moveBlock';
+    id: string;
+    to: number;
+} | {
+    op: 'setVisible';
+    id: string;
+    visible: boolean;
+} | {
+    op: 'setDesignTokens';
+    patch: Partial<DesignTokens>;
+} | {
+    op: 'setMeta';
+    patch: Partial<SiteMeta>;
+} | {
+    op: 'addItem';
+    id: string;
+    field: string;
+    item: unknown;
+    at?: number;
+} | {
+    op: 'updateItem';
+    id: string;
+    field: string;
+    index: number;
+    patch: unknown;
+} | {
+    op: 'removeItem';
+    id: string;
+    field: string;
+    index: number;
+} | {
+    op: 'moveItem';
+    id: string;
+    field: string;
+    from: number;
+    to: number;
+} | {
+    op: 'applyPreset';
+    name: string;
+} | {
+    op: 'setOverrides';
+    id: string;
+    overrides: SectionOverrides | null;
+};
+export interface OpResult {
+    ok: boolean;
+    manifest: SiteManifest;
+    errors: string[];
+    warnings: string[];
+    /** For addBlock: the id of the created block. */
+    id?: string;
+}
+/** Apply one op. Pure: never mutates `manifest`. */
+export declare function applyOp(manifest: SiteManifest, op: EditOp): OpResult;
+export interface BatchResult {
+    manifest: SiteManifest;
+    results: Array<{
+        op: EditOp;
+        ok: boolean;
+        errors: string[];
+        warnings: string[];
+    }>;
+    applied: number;
+}
+/**
+ * Apply a sequence of ops (a chat turn). Each is validated independently against
+ * the running manifest; a failing op is skipped (recorded), the rest proceed —
+ * so one bad tool-call doesn't discard the whole turn.
+ */
+export declare function applyOps(manifest: SiteManifest, ops: EditOp[]): BatchResult;

package/lib/ops.js

@@ -0,0 +1,248 @@
+/**
+ * Edit operations — the verbs of the vocabulary, and the tools a chat-edit agent
+ * calls. Each op is validated BEFORE it is applied (illegal states
+ * unrepresentable): a malformed op is a no-op with errors, never a corrupted
+ * manifest. Applying returns a NEW manifest with `version` bumped, so
+ * undo/history/diff come for free.
+ */
+import { getSpec, blockTypes } from './registry.js';
+import { normalizeTokens } from './tokens.js';
+import { parse } from './schema.js';
+import { getPreset, presetNames } from './presets.js';
+const OVERRIDE_KEYS = ['bg', 'surface', 'text', 'muted', 'primary', 'accent'];
+const clone = (v) => structuredClone(v);
+const find = (m, id) => m.blocks.findIndex((b) => b.id === id);
+/** A deterministic, unique id: `<type>-N` with the smallest free N. */
+function freshId(m, type) {
+    const used = new Set(m.blocks.map((b) => b.id));
+    for (let n = 1;; n++) {
+        const id = `${type}-${n}`;
+        if (!used.has(id))
+            return id;
+    }
+}
+function fail(m, ...errors) {
+    return { ok: false, manifest: m, errors, warnings: [] };
+}
+/** Apply one op. Pure: never mutates `manifest`. */
+export function applyOp(manifest, op) {
+    const next = clone(manifest);
+    next.version = (manifest.version ?? 0) + 1;
+    switch (op.op) {
+        case 'addBlock': {
+            const spec = getSpec(op.type);
+            if (!spec)
+                return fail(manifest, `addBlock: unknown type "${op.type}" (choose from: ${blockTypes().join(', ')})`);
+            const parsed = parse(spec.schema, op.config ?? {});
+            if (!parsed.ok)
+                return fail(manifest, ...parsed.errors.map((e) => `addBlock(${op.type}): ${e}`));
+            const id = op.id && !next.blocks.some((b) => b.id === op.id) ? op.id : freshId(next, op.type);
+            const block = { id, type: op.type, visible: true, config: parsed.value };
+            const at = clamp(op.at ?? next.blocks.length, 0, next.blocks.length);
+            next.blocks.splice(at, 0, block);
+            return { ok: true, manifest: next, errors: [], warnings: parsed.warnings, id };
+        }
+        case 'updateBlock': {
+            const i = find(next, op.id);
+            if (i < 0)
+                return fail(manifest, `updateBlock: no block "${op.id}"`);
+            const cur = next.blocks[i];
+            const spec = getSpec(cur.type);
+            // The block may carry an unknown/deprecated type (e.g. a hand-edited or
+            // legacy manifest); reject rather than dereferencing undefined.
+            if (!spec)
+                return fail(manifest, `updateBlock: unknown block type "${cur.type}" for "${op.id}"`);
+            // Merge patch onto current config, then re-validate the whole config.
+            const merged = { ...cur.config, ...(op.config ?? {}) };
+            const parsed = parse(spec.schema, merged);
+            if (!parsed.ok)
+                return fail(manifest, ...parsed.errors.map((e) => `updateBlock(${op.id}): ${e}`));
+            next.blocks[i] = { ...cur, config: parsed.value };
+            return { ok: true, manifest: next, errors: [], warnings: parsed.warnings };
+        }
+        case 'removeBlock': {
+            const i = find(next, op.id);
+            if (i < 0)
+                return fail(manifest, `removeBlock: no block "${op.id}"`);
+            next.blocks.splice(i, 1);
+            return { ok: true, manifest: next, errors: [], warnings: [] };
+        }
+        case 'moveBlock': {
+            const i = find(next, op.id);
+            if (i < 0)
+                return fail(manifest, `moveBlock: no block "${op.id}"`);
+            const [b] = next.blocks.splice(i, 1);
+            const to = clamp(op.to, 0, next.blocks.length);
+            next.blocks.splice(to, 0, b);
+            return { ok: true, manifest: next, errors: [], warnings: [] };
+        }
+        case 'setVisible': {
+            const i = find(next, op.id);
+            if (i < 0)
+                return fail(manifest, `setVisible: no block "${op.id}"`);
+            next.blocks[i] = { ...next.blocks[i], visible: op.visible };
+            return { ok: true, manifest: next, errors: [], warnings: [] };
+        }
+        case 'setDesignTokens': {
+            next.design = normalizeTokens({ ...next.design, ...(op.patch ?? {}) });
+            return { ok: true, manifest: next, errors: [], warnings: [] };
+        }
+        case 'setMeta': {
+            next.meta = { ...next.meta, ...(op.patch ?? {}) };
+            return { ok: true, manifest: next, errors: [], warnings: [] };
+        }
+        // ── §8 array-item ops ────────────────────────────────────────────────────
+        case 'addItem': {
+            const r = withArrayField(manifest, next, op.id, op.field);
+            if ('error' in r)
+                return r.error;
+            const at = clamp(op.at ?? r.arr.length, 0, r.arr.length);
+            r.arr.splice(at, 0, op.item);
+            return commitBlockConfig(manifest, next, r);
+        }
+        case 'updateItem': {
+            const r = withArrayField(manifest, next, op.id, op.field);
+            if ('error' in r)
+                return r.error;
+            if (!inBounds(op.index, r.arr.length))
+                return fail(manifest, `updateItem: index ${op.index} out of range for "${op.field}" (len ${r.arr.length})`);
+            const cur = r.arr[op.index];
+            // Merge patch onto object items; replace for scalar-item arrays.
+            r.arr[op.index] = (isObject(cur) && isObject(op.patch)) ? { ...cur, ...op.patch } : op.patch;
+            return commitBlockConfig(manifest, next, r);
+        }
+        case 'removeItem': {
+            const r = withArrayField(manifest, next, op.id, op.field);
+            if ('error' in r)
+                return r.error;
+            if (!inBounds(op.index, r.arr.length))
+                return fail(manifest, `removeItem: index ${op.index} out of range for "${op.field}" (len ${r.arr.length})`);
+            r.arr.splice(op.index, 1);
+            return commitBlockConfig(manifest, next, r);
+        }
+        case 'moveItem': {
+            const r = withArrayField(manifest, next, op.id, op.field);
+            if ('error' in r)
+                return r.error;
+            if (!inBounds(op.from, r.arr.length))
+                return fail(manifest, `moveItem: from ${op.from} out of range for "${op.field}" (len ${r.arr.length})`);
+            const [it] = r.arr.splice(op.from, 1);
+            r.arr.splice(clamp(op.to, 0, r.arr.length), 0, it);
+            return commitBlockConfig(manifest, next, r);
+        }
+        // ── theming ──────────────────────────────────────────────────────────────
+        case 'applyPreset': {
+            const preset = getPreset(op.name);
+            if (!preset)
+                return fail(manifest, `applyPreset: unknown preset "${op.name}" (choose from: ${presetNames().join(', ')})`);
+            next.design = normalizeTokens(preset);
+            return { ok: true, manifest: next, errors: [], warnings: [] };
+        }
+        case 'setOverrides': {
+            const i = find(next, op.id);
+            if (i < 0)
+                return fail(manifest, `setOverrides: no block "${op.id}"`);
+            const block = next.blocks[i];
+            if (op.overrides === null) {
+                delete block.overrides;
+            }
+            else {
+                const clean = cleanOverrides(op.overrides);
+                if (!clean) {
+                    delete block.overrides;
+                }
+                else {
+                    block.overrides = clean;
+                }
+            }
+            return { ok: true, manifest: next, errors: [], warnings: [] };
+        }
+        default:
+            return fail(manifest, `unknown op: ${op.op}`);
+    }
+}
+/**
+ * Apply a sequence of ops (a chat turn). Each is validated independently against
+ * the running manifest; a failing op is skipped (recorded), the rest proceed —
+ * so one bad tool-call doesn't discard the whole turn.
+ */
+export function applyOps(manifest, ops) {
+    let m = manifest;
+    let applied = 0;
+    const results = ops.map((op) => {
+        const r = applyOp(m, op);
+        if (r.ok) {
+            m = r.manifest;
+            applied++;
+        }
+        return { op, ok: r.ok, errors: r.errors, warnings: r.warnings };
+    });
+    return { manifest: m, results, applied };
+}
+function clamp(n, lo, hi) {
+    return Math.max(lo, Math.min(hi, Math.trunc(Number.isFinite(n) ? n : hi)));
+}
+function inBounds(i, len) {
+    return typeof i === 'number' && Number.isInteger(i) && i >= 0 && i < len;
+}
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/**
+ * Locate a block's ARRAY field for an item op: the block must exist, its type be
+ * known, and `field` be an array field in the schema. Returns a fresh copy of
+ * the current array to mutate, or a ready-made failure (a bad op is a no-op).
+ */
+function withArrayField(orig, next, id, field) {
+    const i = find(next, id);
+    if (i < 0)
+        return { error: fail(orig, `item op: no block "${id}"`) };
+    const block = next.blocks[i];
+    const spec = getSpec(block.type);
+    if (!spec)
+        return { error: fail(orig, `item op: unknown block type "${block.type}" for "${id}"`) };
+    const fs = spec.schema[field];
+    if (!fs || fs.kind !== 'array')
+        return { error: fail(orig, `item op: "${field}" is not an array field of "${block.type}"`) };
+    const raw = block.config?.[field];
+    return { i, block, field, arr: Array.isArray(raw) ? [...raw] : [] };
+}
+/** Re-validate the whole config with the mutated array applied; reject on hard errors. */
+function commitBlockConfig(orig, next, ctx) {
+    const merged = { ...ctx.block.config, [ctx.field]: ctx.arr };
+    const spec = getSpec(ctx.block.type);
+    const parsed = parse(spec.schema, merged);
+    if (!parsed.ok)
+        return fail(orig, ...parsed.errors.map((e) => `item op(${ctx.block.id}.${ctx.field}): ${e}`));
+    next.blocks[ctx.i] = { ...ctx.block, config: parsed.value };
+    return { ok: true, manifest: next, errors: [], warnings: parsed.warnings };
+}
+const OVERRIDE_RADII = ['sharp', 'soft', 'round'];
+const OVERRIDE_SPACINGS = ['tight', 'default', 'airy'];
+/**
+ * Keep only known override keys with valid values: palette roles (strings) plus
+ * an optional radius / spacing enum. Null when nothing usable — so a junk
+ * override clears rather than corrupts.
+ */
+function cleanOverrides(input) {
+    if (!isObject(input))
+        return null;
+    const out = {};
+    let any = false;
+    for (const k of OVERRIDE_KEYS) {
+        const v = input[k];
+        if (typeof v === 'string' && v) {
+            out[k] = v;
+            any = true;
+        }
+    }
+    if (typeof input.radius === 'string' && OVERRIDE_RADII.includes(input.radius)) {
+        out.radius = input.radius;
+        any = true;
+    }
+    if (typeof input.spacing === 'string' && OVERRIDE_SPACINGS.includes(input.spacing)) {
+        out.spacing = input.spacing;
+        any = true;
+    }
+    return any ? out : null;
+}

package/lib/presets.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Named `DesignTokens` presets (§9) — coherent palettes + scale/radius/spacing/
+ * motion the AI (or a human picker) selects by NAME instead of hand-mixing hexes.
+ * "Make it feel like 'midnight'" becomes one op. Each preset is a complete,
+ * valid token set, so applying one is total and never leaves a hole.
+ *
+ * Presets are additive and stable: add new ones freely, but keep existing names
+ * and their intent so old manifests that reference a preset stay reproducible.
+ */
+import type { DesignTokens } from './types.js';
+/** The built-in presets, keyed by name. Values are complete token sets. */
+export declare const PRESETS: Readonly<Record<string, DesignTokens>>;
+/** Preset names the AI/picker may choose from. */
+export declare function presetNames(): string[];
+/** A named preset as a fresh, complete token set (deep copy — never aliased). */
+export declare function getPreset(name: string): DesignTokens | undefined;

package/lib/presets.js

@@ -0,0 +1,50 @@
+const SANS = "system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif";
+const SERIF = "'Iowan Old Style', Georgia, Cambria, 'Times New Roman', serif";
+/** The built-in presets, keyed by name. Values are complete token sets. */
+export const PRESETS = {
+    // Warm, editorial default (matches DEFAULT_TOKENS' spirit).
+    sand: {
+        mode: 'light',
+        palette: { bg: '#f7f4ee', surface: '#ffffff', text: '#2a2622', muted: '#6b6459', primary: '#3a5a40', accent: '#c2703d' },
+        typography: { fontStack: SANS, scale: 'default' }, radius: 'soft', spacing: 'default', motion: 'subtle',
+    },
+    // Dark, high-contrast, product-y.
+    midnight: {
+        mode: 'dark',
+        palette: { bg: '#0d1117', surface: '#161b22', text: '#e6edf3', muted: '#8b949e', primary: '#4c8dff', accent: '#f778ba' },
+        typography: { fontStack: SANS, scale: 'default' }, radius: 'soft', spacing: 'default', motion: 'subtle',
+    },
+    // Calm, natural, spacious.
+    forest: {
+        mode: 'light',
+        palette: { bg: '#f3f6f2', surface: '#ffffff', text: '#1f2a24', muted: '#5c6b60', primary: '#2f6f4e', accent: '#b5832f' },
+        typography: { fontStack: SANS, scale: 'default' }, radius: 'round', spacing: 'airy', motion: 'subtle',
+    },
+    // Minimal black-on-white, sharp, editorial serif.
+    mono: {
+        mode: 'light',
+        palette: { bg: '#ffffff', surface: '#fafafa', text: '#111111', muted: '#666666', primary: '#111111', accent: '#555555' },
+        typography: { fontStack: SERIF, scale: 'default' }, radius: 'sharp', spacing: 'default', motion: 'none',
+    },
+    // Playful, bright, rounded.
+    candy: {
+        mode: 'light',
+        palette: { bg: '#fff7fb', surface: '#ffffff', text: '#2b1f2b', muted: '#7a6b78', primary: '#e0468b', accent: '#7c5cff' },
+        typography: { fontStack: SANS, scale: 'expressive' }, radius: 'round', spacing: 'airy', motion: 'lively',
+    },
+    // Cool, corporate, trustworthy.
+    ocean: {
+        mode: 'light',
+        palette: { bg: '#f4f8fb', surface: '#ffffff', text: '#0f2233', muted: '#5a6b78', primary: '#1668b0', accent: '#0aa5a5' },
+        typography: { fontStack: SANS, scale: 'default' }, radius: 'soft', spacing: 'default', motion: 'subtle',
+    },
+};
+/** Preset names the AI/picker may choose from. */
+export function presetNames() {
+    return Object.keys(PRESETS);
+}
+/** A named preset as a fresh, complete token set (deep copy — never aliased). */
+export function getPreset(name) {
+    const p = PRESETS[name];
+    return p ? structuredClone(p) : undefined;
+}

package/lib/pwa.d.ts

@@ -0,0 +1,30 @@
+import type { SiteManifest } from './types.js';
+export interface WebAppManifest {
+    name: string;
+    short_name: string;
+    description?: string;
+    start_url: string;
+    scope: string;
+    display: string;
+    theme_color: string;
+    background_color: string;
+    icons: Array<{
+        src: string;
+        sizes: string;
+        type?: string;
+        purpose?: string;
+    }>;
+}
+/** Build the Web App Manifest object from meta + design tokens + `pwa` opts. */
+export declare function buildWebManifest(manifest: SiteManifest): WebAppManifest;
+/** Serialized `manifest.webmanifest` content. */
+export declare function buildWebManifestJson(manifest: SiteManifest): string;
+/**
+ * A minimal, dependency-free service worker: precache the app shell, serve
+ * cache-first for same-origin GETs, and fall back to the cached shell offline.
+ * The cache name is derived from the manifest `version` so a new publish
+ * invalidates the old cache deterministically (no timestamps — reproducible).
+ */
+export declare function buildServiceWorker(manifest: SiteManifest): string;
+/** Files to serve for an installable PWA, or null when not opted in. */
+export declare function emitPwa(manifest: SiteManifest): Record<string, string> | null;