@bytesbrains/weblocks 0.2.0

package/lib/pwa.js

@@ -0,0 +1,79 @@
+/**
+ * PWA layer (§7) — derive an installable app shell from the `SiteManifest`.
+ *
+ * Two emitted artifacts sit alongside the rendered HTML:
+ *   - `manifest.webmanifest` — name/icons/colors/display, defaulted from meta +
+ *     design tokens so a bare `pwa: {}` already produces a valid, installable
+ *     manifest;
+ *   - `sw.js` — a tiny precache + offline-fallback service worker.
+ *
+ * Both are total (never throw) and host-neutral: the host serves the returned
+ * files at `/manifest.webmanifest` and `/sw.js`. `emitPwa` returns null when the
+ * manifest does not opt into PWA, so callers can `if (files) writeAll(files)`.
+ */
+import { normalizeTokens } from './tokens.js';
+const DEFAULT_ICONS = [
+    { src: '/icons/icon-192.png', sizes: '192x192', type: 'image/png' },
+    { src: '/icons/icon-512.png', sizes: '512x512', type: 'image/png' },
+    { src: '/icons/icon-maskable.png', sizes: '512x512', type: 'image/png', purpose: 'maskable' },
+];
+/** Build the Web App Manifest object from meta + design tokens + `pwa` opts. */
+export function buildWebManifest(manifest) {
+    const pwa = manifest?.pwa ?? {};
+    const tokens = normalizeTokens(manifest?.design);
+    const name = pwa.name || manifest?.meta?.title || 'App';
+    return {
+        name,
+        short_name: pwa.shortName || name.slice(0, 12),
+        ...(pwa.description || manifest?.meta?.description
+            ? { description: pwa.description || manifest.meta.description }
+            : {}),
+        start_url: pwa.startUrl || '/',
+        scope: pwa.scope || '/',
+        display: pwa.display || 'standalone',
+        theme_color: pwa.themeColor || tokens.palette.primary,
+        background_color: pwa.backgroundColor || tokens.palette.bg,
+        icons: pwa.icons && pwa.icons.length ? pwa.icons : DEFAULT_ICONS,
+    };
+}
+/** Serialized `manifest.webmanifest` content. */
+export function buildWebManifestJson(manifest) {
+    return JSON.stringify(buildWebManifest(manifest), null, 2) + '\n';
+}
+/**
+ * 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 function buildServiceWorker(manifest) {
+    const version = typeof manifest?.version === 'number' ? manifest.version : 1;
+    const cache = `weblocks-v${version}`;
+    const shell = JSON.stringify(['/', '/manifest.webmanifest']);
+    return `// Auto-generated by @bytesbrains/weblocks (PWA layer). Do not edit by hand.
+const CACHE='${cache}';
+const SHELL=${shell};
+self.addEventListener('install',function(e){e.waitUntil(caches.open(CACHE).then(function(c){return c.addAll(SHELL)}).then(function(){return self.skipWaiting()}))});
+self.addEventListener('activate',function(e){e.waitUntil(caches.keys().then(function(keys){return Promise.all(keys.filter(function(k){return k!==CACHE}).map(function(k){return caches.delete(k)}))}).then(function(){return self.clients.claim()}))});
+self.addEventListener('fetch',function(e){
+  var req=e.request;
+  if(req.method!=='GET'||new URL(req.url).origin!==self.location.origin)return;
+  e.respondWith(caches.match(req).then(function(hit){
+    return hit||fetch(req).then(function(res){
+      var copy=res.clone();caches.open(CACHE).then(function(c){c.put(req,copy)});return res;
+    }).catch(function(){return caches.match('/')});
+  }));
+});
+`;
+}
+/** Files to serve for an installable PWA, or null when not opted in. */
+export function emitPwa(manifest) {
+    if (!manifest?.pwa)
+        return null;
+    const files = {
+        'manifest.webmanifest': buildWebManifestJson(manifest),
+    };
+    if (manifest.pwa.offline !== false)
+        files['sw.js'] = buildServiceWorker(manifest);
+    return files;
+}

package/lib/registry.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The block registry — the *closed vocabulary*. A block type exists iff it is
+ * registered here; the AI can only compose from this set, and an unknown type
+ * is simply skipped by the renderer (total, never throws).
+ *
+ * Each brick owns its schema (studs), its own CSS (included once when used),
+ * and a markup renderer. Adding a capability = registering a new brick that
+ * clears the "brick definition-of-done" (see docs/APPS_BLOCKS_ARCHITECTURE.md).
+ */
+import type { Schema } from './schema.js';
+import type { DesignTokens } from './types.js';
+import type { RuntimeAdapter } from './runtime.js';
+/** What a brick's `render` receives beyond its config + tokens (powered bricks). */
+export interface RenderContext {
+    /** The placed block's id — stable handle for the runtime contract. */
+    id: string;
+    /** Host-provided runtime; `resolve` returns null when unwired (inert render). */
+    runtime: RuntimeAdapter;
+}
+export interface BlockSpec {
+    type: string;
+    /** One line the AI sees in its menu — what this brick is for. */
+    description: string;
+    /** Typed contract the config must satisfy (defaults + validation). */
+    schema: Schema;
+    /** The brick's own styles; emitted once per document if the brick is used. */
+    css?: string;
+    /**
+     * Markup only — receives an already-normalized config + the shared tokens.
+     * Powered bricks also read `ctx` (block id + runtime) to wire the §6 contract;
+     * static bricks ignore it (signature is backwards-compatible).
+     */
+    render(config: Record<string, unknown>, tokens: DesignTokens, ctx?: RenderContext): string;
+    /** Client island to hydrate (dynamic/interactive bricks). */
+    island?: string;
+    /**
+     * Powered brick: the host runtime capabilities this brick needs (§6). Absent =
+     * a pure static brick that works with no backend.
+     */
+    runtime?: {
+        capabilities: string[];
+    };
+}
+export declare const REGISTRY: ReadonlyMap<string, BlockSpec>;
+export declare function getSpec(type: string): BlockSpec | undefined;
+/** The vocabulary the AI is allowed to emit — its "menu" of brick types. */
+export declare function blockTypes(): string[];
+/**
+ * Whether a used block needs its island hydrated in THIS config. Static bricks
+ * (and interactive bricks with their behaviour toggled off, e.g. gallery with
+ * `lightbox:false`) ship zero JS — the "static-first" invariant.
+ */
+export declare function needsIsland(spec: BlockSpec, config: Record<string, unknown>): boolean;

package/lib/registry.js

@@ -0,0 +1,81 @@
+import { nav } from './blocks/nav.js';
+import { announcementBar } from './blocks/announcementBar.js';
+import { hero } from './blocks/hero.js';
+import { heroApp } from './blocks/heroApp.js';
+import { features } from './blocks/features.js';
+import { about } from './blocks/about.js';
+import { richText } from './blocks/richText.js';
+import { split } from './blocks/split.js';
+import { steps } from './blocks/steps.js';
+import { stats } from './blocks/stats.js';
+import { services } from './blocks/services.js';
+import { pricing } from './blocks/pricing.js';
+import { logos } from './blocks/logos.js';
+import { team } from './blocks/team.js';
+import { gallery } from './blocks/gallery.js';
+import { carousel } from './blocks/carousel.js';
+import { video } from './blocks/video.js';
+import { map } from './blocks/map.js';
+import { timeline } from './blocks/timeline.js';
+import { tabs } from './blocks/tabs.js';
+import { accordion } from './blocks/accordion.js';
+import { testimonials } from './blocks/testimonials.js';
+import { faq } from './blocks/faq.js';
+import { blogList } from './blocks/blogList.js';
+import { blogPost } from './blocks/blogPost.js';
+import { feed } from './blocks/feed.js';
+import { contactForm } from './blocks/contactForm.js';
+import { newsletter } from './blocks/newsletter.js';
+import { auth } from './blocks/auth.js';
+import { cta } from './blocks/cta.js';
+import { socialLinks } from './blocks/socialLinks.js';
+import { contactDetails } from './blocks/contactDetails.js';
+import { divider } from './blocks/divider.js';
+import { spacer } from './blocks/spacer.js';
+import { appShell } from './blocks/appShell.js';
+import { sidebar } from './blocks/sidebar.js';
+import { footer } from './blocks/footer.js';
+// Registration order = the order block CSS is emitted (stable output) and the
+// order bricks appear in the AI's menu. Roughly top-to-bottom on a page.
+const SPECS = [
+    // chrome / app shell
+    appShell, nav, announcementBar, sidebar,
+    // heroes
+    hero, heroApp,
+    // content
+    features, about, richText, split, steps, stats,
+    services, pricing, logos, team,
+    // media
+    gallery, carousel, video, map,
+    // structured content
+    timeline, tabs, accordion, testimonials, faq,
+    // collections
+    blogList, blogPost, feed,
+    // dynamic / powered
+    contactForm, newsletter, auth,
+    // conversion / contact
+    cta, socialLinks, contactDetails,
+    // rhythm
+    divider, spacer,
+    footer,
+];
+export const REGISTRY = new Map(SPECS.map((s) => [s.type, s]));
+export function getSpec(type) {
+    return REGISTRY.get(type);
+}
+/** The vocabulary the AI is allowed to emit — its "menu" of brick types. */
+export function blockTypes() {
+    return [...REGISTRY.keys()];
+}
+/**
+ * Whether a used block needs its island hydrated in THIS config. Static bricks
+ * (and interactive bricks with their behaviour toggled off, e.g. gallery with
+ * `lightbox:false`) ship zero JS — the "static-first" invariant.
+ */
+export function needsIsland(spec, config) {
+    if (!spec.island)
+        return false;
+    if (spec.type === 'gallery')
+        return config.lightbox === true;
+    return true;
+}

package/lib/render.d.ts

@@ -0,0 +1,8 @@
+import { type RuntimeAdapter } from './runtime.js';
+import type { SiteManifest } from './types.js';
+export interface RenderOptions {
+    /** Host runtime for powered bricks (§6). Defaults to the inert no-op adapter. */
+    runtime?: RuntimeAdapter;
+}
+/** The full document. */
+export declare function renderSite(manifest: SiteManifest, options?: RenderOptions): string;

package/lib/render.js

@@ -0,0 +1,105 @@
+/**
+ * The renderer — a *total* function: manifest → one self-contained static HTML
+ * document. It never throws. Unknown block types are skipped; missing config
+ * fields are defaulted by each brick's schema; only the CSS of bricks actually
+ * used is included. This is the second "wall" (the first being schema
+ * validation): together they make a broken page structurally impossible.
+ *
+ * Powered bricks (forms, auth, search) receive a `RuntimeAdapter` via the render
+ * options and speak the §6 contract; with the default no-op runtime they render
+ * inert-but-valid. PWA/SEO head tags are emitted only when the manifest opts in.
+ */
+import { escapeAttr, escapeHtml, parse } from './schema.js';
+import { getSpec, needsIsland, REGISTRY } from './registry.js';
+import { normalizeTokens, sectionOverrideCss, tokensToCss } from './tokens.js';
+import { NOOP_RUNTIME } from './runtime.js';
+const RESET_CSS = `
+*,*::before,*::after{box-sizing:border-box}
+body{margin:0;font-family:var(--font);font-size:var(--fs-base);color:var(--text);background:var(--bg);line-height:1.5;-webkit-font-smoothing:antialiased}
+img{max-width:100%}
+.blk-scope{display:block}
+@media(prefers-reduced-motion:reduce){*{transition:none!important;animation:none!important}}
+`.trim().replace(/\n/g, '');
+/** Render one block: normalize its config, then hand markup to the brick. */
+function renderBlock(block, manifest, runtime) {
+    const spec = getSpec(block.type);
+    if (!spec)
+        return ''; // unknown type → skip (closed vocabulary; total)
+    const { value } = parse(spec.schema, block.config ?? {});
+    const tokens = normalizeTokens(manifest.design);
+    const ctx = { id: block.id, runtime };
+    let html = spec.render(value, tokens, ctx);
+    // Opt-in per-section overrides: scope palette/radius/spacing as inherited CSS
+    // vars on a wrapper (escaped for the style attribute).
+    const style = sectionOverrideCss(block.overrides);
+    if (style)
+        html = `<div class="blk-scope" style="${escapeAttr(style)}">\n${html}\n</div>`;
+    return html;
+}
+/** The full document. */
+export function renderSite(manifest, options = {}) {
+    const runtime = options.runtime ?? NOOP_RUNTIME;
+    const tokens = normalizeTokens(manifest?.design);
+    const meta = manifest?.meta ?? { title: '', description: '', lang: '' };
+    const blocks = (manifest?.blocks ?? []).filter((b) => b && b.visible !== false && getSpec(b.type));
+    // Collect each used brick's CSS once, in registration order (stable output).
+    const usedTypes = new Set(blocks.map((b) => b.type));
+    const blockCss = [...REGISTRY.values()]
+        .filter((s) => usedTypes.has(s.type) && s.css)
+        .map((s) => s.css)
+        .join('\n');
+    const body = blocks.map((b) => renderBlock(b, manifest, runtime)).filter(Boolean).join('\n');
+    // Islands to hydrate. Static-only pages emit none.
+    const islands = new Set();
+    for (const b of blocks) {
+        const spec = getSpec(b.type);
+        const { value } = parse(spec.schema, b.config ?? {});
+        if (needsIsland(spec, value))
+            islands.add(spec.island);
+    }
+    const islandTags = [...islands]
+        .map((name) => `<script type="module" src="/_island/${escapeAttr(name)}.js" data-island="${escapeAttr(name)}"></script>`)
+        .join('\n');
+    return `<!doctype html>
+<html lang="${escapeAttr(meta.lang || 'en')}">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(meta.title || 'Untitled site')}</title>${meta.description ? `\n<meta name="description" content="${escapeAttr(meta.description)}">` : ''}${headExtras(manifest, tokens.palette.primary)}
+<style>${tokensToCss(tokens)}\n${RESET_CSS}\n${blockCss}</style>
+</head>
+<body>
+${body}${islandTags ? '\n' + islandTags : ''}
+</body>
+</html>`;
+}
+/** SEO + PWA <head> tags, emitted only when the manifest opts in. */
+function headExtras(manifest, primary) {
+    const out = [];
+    const seo = manifest?.seo;
+    const pwa = manifest?.pwa;
+    const title = manifest?.meta?.title ?? '';
+    const desc = manifest?.meta?.description ?? '';
+    if (seo) {
+        if (seo.canonical)
+            out.push(`<link rel="canonical" href="${escapeAttr(seo.canonical)}">`);
+        if (seo.noindex)
+            out.push('<meta name="robots" content="noindex">');
+        out.push(`<meta property="og:title" content="${escapeAttr(seo.ogTitle || title)}">`);
+        if (seo.ogDescription || desc)
+            out.push(`<meta property="og:description" content="${escapeAttr(seo.ogDescription || desc)}">`);
+        if (seo.ogImage)
+            out.push(`<meta property="og:image" content="${escapeAttr(seo.ogImage)}">`);
+        out.push(`<meta name="twitter:card" content="${escapeAttr(seo.twitterCard || 'summary_large_image')}">`);
+    }
+    if (pwa) {
+        out.push('<link rel="manifest" href="/manifest.webmanifest">');
+        out.push(`<meta name="theme-color" content="${escapeAttr(pwa.themeColor || primary)}">`);
+        out.push('<meta name="mobile-web-app-capable" content="yes">');
+        out.push('<meta name="apple-mobile-web-app-capable" content="yes">');
+        if (pwa.offline !== false) {
+            out.push(`<script>if('serviceWorker'in navigator){addEventListener('load',function(){navigator.serviceWorker.register('/sw.js').catch(function(){})})}</script>`);
+        }
+    }
+    return out.length ? '\n' + out.join('\n') : '';
+}

package/lib/runtime.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The dynamic-block runtime CONTRACT (§6).
+ *
+ * Static bricks are pure HTML. A few bricks are *powered* — a form submits, a
+ * search queries, an auth widget signs in — and can't be pure static markup.
+ * The engine stays host-neutral by **declaring** each powered brick's runtime
+ * needs (capabilities) and emitting a documented client contract; the HOST wires
+ * the actual endpoints through a small `RuntimeAdapter`. There is no bundled
+ * backend, and no bespoke per-block glue — one adapter serves every dynamic
+ * brick.
+ *
+ * The client contract every powered brick emits:
+ *   - the interactive element carries `data-wl-capability="<cap>"` and
+ *     `data-wl-block="<blockId>"`;
+ *   - a form's `action`/`method` are resolved by the adapter (or left inert with
+ *     a documented fallback when no runtime is configured).
+ * A host's client island can therefore find every powered element generically
+ * (`[data-wl-capability]`) and enhance it, and the server implements one route
+ * per capability — never one per block type.
+ */
+import type { SiteManifest } from './types.js';
+/** A resolved endpoint for one capability of one placed block. */
+export interface RuntimeAction {
+    url: string;
+    method: 'GET' | 'POST';
+}
+/**
+ * The host-provided runtime. Given a capability a brick declares and the id of
+ * the placed block, return where its client should talk to — or `null` when the
+ * host does not provide that capability (the brick then renders an inert,
+ * clearly-labelled fallback, never a broken element).
+ */
+export interface RuntimeAdapter {
+    resolve(capability: string, blockId: string): RuntimeAction | null;
+}
+/**
+ * The reference no-op adapter: provides nothing. Powered bricks render their
+ * markup in a documented "runtime not configured" state — valid HTML, visibly
+ * inert, with the `data-wl-capability` hooks intact so a host can still enhance
+ * them client-side. This is the default so `renderSite` needs no host wiring.
+ */
+export declare const NOOP_RUNTIME: RuntimeAdapter;
+/**
+ * Convenience adapter for the common case: every capability maps to one path
+ * template under a base, keyed by capability + block id. A host that exposes
+ * `POST /api/<capability>/<blockId>` can wire the whole catalog in one line.
+ */
+export declare function pathRuntime(base?: string, method?: 'GET' | 'POST'): RuntimeAdapter;
+/**
+ * Whitelist a form method to a safe lowercase token. A `RuntimeAdapter` is typed
+ * to return `'GET' | 'POST'`, but a host implements it at runtime — so a powered
+ * brick coerces the value before writing it into a `method` attribute (anything
+ * that isn't a clear GET falls back to POST). Defence-in-depth: no host string
+ * can break out of the attribute.
+ */
+export declare function safeMethod(method: unknown): 'get' | 'post';
+/** One block's declared runtime needs. */
+export interface BlockRuntimeNeeds {
+    blockId: string;
+    type: string;
+    capabilities: string[];
+}
+/**
+ * Aggregate the runtime capabilities a manifest requires — what a host must
+ * implement to make this site fully functional. Empty ⇒ a purely static site
+ * that needs no backend at all.
+ */
+export declare function runtimeNeeds(manifest: SiteManifest): BlockRuntimeNeeds[];

package/lib/runtime.js

@@ -0,0 +1,46 @@
+import { getSpec } from './registry.js';
+/**
+ * The reference no-op adapter: provides nothing. Powered bricks render their
+ * markup in a documented "runtime not configured" state — valid HTML, visibly
+ * inert, with the `data-wl-capability` hooks intact so a host can still enhance
+ * them client-side. This is the default so `renderSite` needs no host wiring.
+ */
+export const NOOP_RUNTIME = { resolve: () => null };
+/**
+ * Convenience adapter for the common case: every capability maps to one path
+ * template under a base, keyed by capability + block id. A host that exposes
+ * `POST /api/<capability>/<blockId>` can wire the whole catalog in one line.
+ */
+export function pathRuntime(base = '/api', method = 'POST') {
+    const root = base.replace(/\/+$/, '');
+    return {
+        resolve: (capability, blockId) => ({ url: `${root}/${capability}/${encodeURIComponent(blockId)}`, method }),
+    };
+}
+/**
+ * Whitelist a form method to a safe lowercase token. A `RuntimeAdapter` is typed
+ * to return `'GET' | 'POST'`, but a host implements it at runtime — so a powered
+ * brick coerces the value before writing it into a `method` attribute (anything
+ * that isn't a clear GET falls back to POST). Defence-in-depth: no host string
+ * can break out of the attribute.
+ */
+export function safeMethod(method) {
+    return String(method ?? '').toLowerCase() === 'get' ? 'get' : 'post';
+}
+/**
+ * Aggregate the runtime capabilities a manifest requires — what a host must
+ * implement to make this site fully functional. Empty ⇒ a purely static site
+ * that needs no backend at all.
+ */
+export function runtimeNeeds(manifest) {
+    const out = [];
+    for (const b of manifest?.blocks ?? []) {
+        if (!b || b.visible === false)
+            continue;
+        const spec = getSpec(b.type);
+        const caps = spec?.runtime?.capabilities;
+        if (caps && caps.length)
+            out.push({ blockId: b.id, type: b.type, capabilities: [...caps] });
+    }
+    return out;
+}

package/lib/schema.d.ts

@@ -0,0 +1,67 @@
+/**
+ * A tiny, dependency-free schema layer — the "studs" of a brick.
+ *
+ * It is the contract the AI must satisfy, and it separates two severities so
+ * edit ops can be strict about garbage yet lenient about incompleteness:
+ *   - errors (HARD): wrong type, invalid enum, out-of-range int, non-array →
+ *     the op is malformed; reject it (illegal states unrepresentable).
+ *   - warnings (SOFT): a required field is missing, or a value was truncated to
+ *     its max → apply with the default/truncation (the total renderer copes),
+ *     and tell the author.
+ *
+ * [parse] ALWAYS returns a fully-defaulted `value`, so the renderer never sees a
+ * hole even when the input was partial. (In production these descriptors would
+ * be generated from each component's Custom Elements Manifest.)
+ */
+export type Field = {
+    kind: 'string';
+    required?: boolean;
+    default?: string;
+    max?: number;
+} | {
+    kind: 'enum';
+    values: readonly string[];
+    required?: boolean;
+    default?: string;
+} | {
+    kind: 'boolean';
+    default?: boolean;
+} | {
+    kind: 'int';
+    oneOf?: readonly number[];
+    default?: number;
+    min?: number;
+    max?: number;
+} | {
+    kind: 'object';
+    fields: Schema;
+    required?: boolean;
+} | {
+    kind: 'array';
+    of: Field;
+    required?: boolean;
+    max?: number;
+};
+export type Schema = Record<string, Field>;
+export interface ParseResult {
+    ok: boolean;
+    value: Record<string, unknown>;
+    errors: string[];
+    warnings: string[];
+}
+/** Validate `input` against `schema`, applying defaults. Never throws. */
+export declare function parse(schema: Schema, input: unknown): ParseResult;
+export declare function escapeHtml(s: unknown): string;
+/** Attribute-safe escape (same set; kept separate for intent + future divergence). */
+export declare function escapeAttr(s: unknown): string;
+/**
+ * Neutralize a link target so a config value can't inject a scheme-based XSS.
+ * Relative/anchor URLs and the http(s)/mailto/tel schemes pass through; anything
+ * with another scheme (javascript:, data:, vbscript:, …) collapses to '#'.
+ *
+ * C0 control chars are stripped first — browsers ignore tabs/newlines when
+ * detecting a scheme, so `java\nscript:alert(1)` must be caught, not waved
+ * through as "no scheme". Always feed the result through [escapeAttr] for the
+ * attribute context.
+ */
+export declare function sanitizeUrl(url: unknown): string;

package/lib/schema.js

@@ -0,0 +1,150 @@
+/**
+ * A tiny, dependency-free schema layer — the "studs" of a brick.
+ *
+ * It is the contract the AI must satisfy, and it separates two severities so
+ * edit ops can be strict about garbage yet lenient about incompleteness:
+ *   - errors (HARD): wrong type, invalid enum, out-of-range int, non-array →
+ *     the op is malformed; reject it (illegal states unrepresentable).
+ *   - warnings (SOFT): a required field is missing, or a value was truncated to
+ *     its max → apply with the default/truncation (the total renderer copes),
+ *     and tell the author.
+ *
+ * [parse] ALWAYS returns a fully-defaulted `value`, so the renderer never sees a
+ * hole even when the input was partial. (In production these descriptors would
+ * be generated from each component's Custom Elements Manifest.)
+ */
+/** Validate `input` against `schema`, applying defaults. Never throws. */
+export function parse(schema, input) {
+    const ctx = { errors: [], warnings: [] };
+    const src = isObject(input) ? input : {};
+    const value = {};
+    for (const [key, field] of Object.entries(schema)) {
+        value[key] = parseField(field, src[key], key, ctx);
+    }
+    return { ok: ctx.errors.length === 0, value, errors: ctx.errors, warnings: ctx.warnings };
+}
+function parseField(field, raw, path, ctx) {
+    const present = raw !== undefined && raw !== null;
+    switch (field.kind) {
+        case 'string': {
+            if (!present)
+                return missing(field.required, path, ctx, field.default ?? '');
+            if (typeof raw !== 'string')
+                return hard(path, 'string', ctx, field.default ?? '');
+            if (field.max !== undefined && raw.length > field.max) {
+                ctx.warnings.push(`${path}: truncated to ${field.max} chars`);
+                return raw.slice(0, field.max);
+            }
+            return raw;
+        }
+        case 'enum': {
+            const fallback = field.default ?? field.values[0] ?? '';
+            if (!present)
+                return missing(field.required, path, ctx, fallback);
+            if (typeof raw !== 'string' || !field.values.includes(raw)) {
+                ctx.errors.push(`${path}: must be one of ${field.values.join(' | ')}`);
+                return fallback;
+            }
+            return raw;
+        }
+        case 'boolean': {
+            if (!present)
+                return field.default ?? false;
+            if (typeof raw !== 'boolean')
+                return hard(path, 'boolean', ctx, field.default ?? false);
+            return raw;
+        }
+        case 'int': {
+            const def = field.default ?? field.oneOf?.[0] ?? 0;
+            if (!present)
+                return def;
+            if (typeof raw !== 'number' || !Number.isInteger(raw))
+                return hard(path, 'integer', ctx, def);
+            if (field.oneOf && !field.oneOf.includes(raw)) {
+                ctx.errors.push(`${path}: must be one of ${field.oneOf.join(', ')}`);
+                return def;
+            }
+            if (field.min !== undefined && raw < field.min) {
+                ctx.errors.push(`${path}: below min ${field.min}`);
+                return field.min;
+            }
+            if (field.max !== undefined && raw > field.max) {
+                ctx.errors.push(`${path}: above max ${field.max}`);
+                return field.max;
+            }
+            return raw;
+        }
+        case 'object': {
+            if (!present) {
+                if (field.required)
+                    ctx.warnings.push(`${path}: missing`);
+                return parse(field.fields, {}).value;
+            }
+            const r = parse(field.fields, raw);
+            for (const e of r.errors)
+                ctx.errors.push(`${path}.${e}`);
+            for (const w of r.warnings)
+                ctx.warnings.push(`${path}.${w}`);
+            return r.value;
+        }
+        case 'array': {
+            if (!present)
+                return missing(field.required, path, ctx, []);
+            if (!Array.isArray(raw))
+                return hard(path, 'array', ctx, []);
+            const items = field.max !== undefined ? raw.slice(0, field.max) : raw;
+            if (field.max !== undefined && raw.length > field.max)
+                ctx.warnings.push(`${path}: truncated to ${field.max} items`);
+            return items.map((item, i) => parseField(field.of, item, `${path}[${i}]`, ctx));
+        }
+    }
+}
+/** Missing but not malformed → warning (soft); returns the default. */
+function missing(isRequired, path, ctx, fallback) {
+    if (isRequired)
+        ctx.warnings.push(`${path}: missing`);
+    return fallback;
+}
+/** Wrong type/shape → error (hard); returns the default so render stays total. */
+function hard(path, expected, ctx, fallback) {
+    ctx.errors.push(`${path}: expected ${expected}`);
+    return fallback;
+}
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+// ── HTML-escaping (every brick renders text through these — no injection) ───────
+const HTML_ESCAPES = {
+    '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
+};
+export function escapeHtml(s) {
+    return String(s ?? '').replace(/[&<>"']/g, (c) => HTML_ESCAPES[c] ?? c);
+}
+/** Attribute-safe escape (same set; kept separate for intent + future divergence). */
+export function escapeAttr(s) {
+    return escapeHtml(s);
+}
+// Link schemes allowed in an href. escapeAttr neutralizes the attribute
+// *delimiters* but not a dangerous *scheme*, so a link target must also pass
+// through here before it is escaped.
+const SAFE_URL_SCHEME = /^(?:https?|mailto|tel):/i;
+/**
+ * Neutralize a link target so a config value can't inject a scheme-based XSS.
+ * Relative/anchor URLs and the http(s)/mailto/tel schemes pass through; anything
+ * with another scheme (javascript:, data:, vbscript:, …) collapses to '#'.
+ *
+ * C0 control chars are stripped first — browsers ignore tabs/newlines when
+ * detecting a scheme, so `java\nscript:alert(1)` must be caught, not waved
+ * through as "no scheme". Always feed the result through [escapeAttr] for the
+ * attribute context.
+ */
+export function sanitizeUrl(url) {
+    // Strip C0 control chars + DEL (tab/newline/CR) before scheme detection.
+    const s = String(url ?? '').replace(/[\x00-\x1F\x7F]/g, '').trim();
+    if (!s)
+        return '#';
+    const hasScheme = /^[a-z][a-z0-9+.-]*:/i.test(s);
+    if (hasScheme && !SAFE_URL_SCHEME.test(s))
+        return '#';
+    return s;
+}