@bytesbrains/weblocks 0.2.0

package/lib/tokens.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Design tokens → CSS custom properties (the shared "baseplate").
+ *
+ * Every brick styles itself from these variables, so a single token edit
+ * ("make the whole site warmer") restyles the entire page — coherence by
+ * construction. [normalizeTokens] is total: any missing field falls back to a
+ * default, so the renderer never sees a hole.
+ *
+ * Two derived colours — `--on-primary` / `--on-accent` — carry a legible text
+ * colour for anything sitting on a primary/accent fill, computed from the
+ * palette so contrast holds on ANY colours (no hardcoded `#fff`). And when
+ * `mode: 'auto'`, a `@media (prefers-color-scheme: dark)` block swaps the palette
+ * to the viewer's OS preference.
+ */
+import type { DesignTokens, SectionOverrides } from './types.js';
+export declare const DEFAULT_TOKENS: DesignTokens;
+/**
+ * A legible text colour (near-black or white) for text on a given fill, by
+ * WCAG relative luminance. Total: any unparseable colour falls back to white.
+ */
+export declare function readableOn(color: string): string;
+/**
+ * Fill missing tokens with defaults AND coerce any out-of-range enum back to its
+ * default. Never throws. This is what keeps the renderer total: an AI-emitted
+ * `mode: "neon"` or `scale: "huge"` can't reach `tokensToCss` (which would index
+ * to `undefined`/`NaN`) — it lands on a valid value here first.
+ */
+export declare function normalizeTokens(input: Partial<DesignTokens> | undefined): DesignTokens;
+/** The `:root` variable block, plus a dark-palette override when `mode: 'auto'`. */
+export declare function tokensToCss(tokens: DesignTokens): string;
+/**
+ * Inline CSS-variable declarations for a block's opt-in per-section overrides —
+ * a palette subset (each re-deriving its on-fill colour) plus optional radius /
+ * spacing. Returns '' when there's nothing to scope. The caller escapes this for
+ * the `style` attribute.
+ */
+export declare function sectionOverrideCss(o: SectionOverrides | undefined): string;

package/lib/tokens.js

@@ -0,0 +1,136 @@
+export const DEFAULT_TOKENS = {
+    mode: 'light',
+    palette: {
+        bg: '#f7f4ee',
+        surface: '#ffffff',
+        text: '#2a2622',
+        muted: '#6b6459',
+        primary: '#3a5a40',
+        accent: '#c2703d',
+    },
+    typography: {
+        fontStack: "system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif",
+        scale: 'default',
+    },
+    radius: 'soft',
+    spacing: 'default',
+    motion: 'subtle',
+};
+/** Fallback dark palette for `mode: 'auto'` when no `darkPalette` is supplied. */
+const DARK_FALLBACK = {
+    bg: '#0d1117', surface: '#161b22', text: '#e6edf3', muted: '#8b949e', primary: '#4c8dff', accent: '#f778ba',
+};
+const SCALE_BASE_PX = { compact: 15, default: 16, expressive: 18 };
+const RADIUS_PX = { sharp: '0px', soft: '12px', round: '24px' };
+const SPACE_MULT = { tight: 0.8, default: 1, airy: 1.4 };
+/** Coerce to one of `allowed`, else the default — so a bad enum never leaks into CSS. */
+function oneOf(value, allowed, def) {
+    return allowed.includes(value) ? value : def;
+}
+/**
+ * A legible text colour (near-black or white) for text on a given fill, by
+ * WCAG relative luminance. Total: any unparseable colour falls back to white.
+ */
+export function readableOn(color) {
+    const h = String(color ?? '').trim().replace(/^#/, '');
+    const full = h.length === 3 ? h.split('').map((c) => c + c).join('') : h;
+    if (!/^[0-9a-fA-F]{6}$/.test(full))
+        return '#ffffff';
+    const chan = (i) => parseInt(full.slice(i, i + 2), 16) / 255;
+    const lin = (c) => (c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+    const L = 0.2126 * lin(chan(0)) + 0.7152 * lin(chan(2)) + 0.0722 * lin(chan(4));
+    return L > 0.45 ? '#111111' : '#ffffff';
+}
+/** The six palette roles + the two derived on-fill text colours. */
+function paletteVars(p) {
+    return [
+        `--bg:${p.bg}`,
+        `--surface:${p.surface}`,
+        `--text:${p.text}`,
+        `--muted:${p.muted}`,
+        `--primary:${p.primary}`,
+        `--accent:${p.accent}`,
+        `--on-primary:${readableOn(p.primary)}`,
+        `--on-accent:${readableOn(p.accent)}`,
+    ];
+}
+/**
+ * Fill missing tokens with defaults AND coerce any out-of-range enum back to its
+ * default. Never throws. This is what keeps the renderer total: an AI-emitted
+ * `mode: "neon"` or `scale: "huge"` can't reach `tokensToCss` (which would index
+ * to `undefined`/`NaN`) — it lands on a valid value here first.
+ */
+export function normalizeTokens(input) {
+    const t = input ?? {};
+    const d = DEFAULT_TOKENS;
+    const core = {
+        mode: oneOf(t.mode, ['light', 'dark', 'auto'], d.mode),
+        palette: { ...d.palette, ...(t.palette ?? {}) },
+        typography: {
+            fontStack: t.typography?.fontStack ?? d.typography.fontStack,
+            scale: oneOf(t.typography?.scale, ['compact', 'default', 'expressive'], d.typography.scale),
+        },
+        radius: oneOf(t.radius, ['sharp', 'soft', 'round'], d.radius),
+        spacing: oneOf(t.spacing, ['tight', 'default', 'airy'], d.spacing),
+        motion: oneOf(t.motion, ['none', 'subtle', 'lively'], d.motion),
+    };
+    // Keep a dark palette only when supplied (merged onto the fallback so a partial
+    // one is still complete). Consulted only for `mode: 'auto'`.
+    if (t.darkPalette)
+        core.darkPalette = { ...DARK_FALLBACK, ...t.darkPalette };
+    return core;
+}
+/** The `:root` variable block, plus a dark-palette override when `mode: 'auto'`. */
+export function tokensToCss(tokens) {
+    const t = normalizeTokens(tokens);
+    const base = SCALE_BASE_PX[t.typography.scale];
+    const space = SPACE_MULT[t.spacing];
+    const sizeVars = [
+        `--font:${t.typography.fontStack}`,
+        `--fs-base:${base}px`,
+        `--fs-lg:${(base * 1.35).toFixed(1)}px`,
+        `--fs-xl:${(base * 2.4).toFixed(1)}px`,
+        `--radius:${RADIUS_PX[t.radius]}`,
+        `--space:${space}rem`,
+        `--space-lg:${(space * 3).toFixed(2)}rem`,
+        `--motion:${t.motion === 'none' ? '0ms' : t.motion === 'lively' ? '320ms' : '180ms'}`,
+    ];
+    const root = `:root{${[...paletteVars(t.palette), ...sizeVars].join(';')}}`;
+    if (t.mode !== 'auto')
+        return root;
+    // Only the palette (colours + on-fill text) flips with the OS theme; sizes,
+    // radius, spacing, and font stay put.
+    const dark = t.darkPalette ?? DARK_FALLBACK;
+    return `${root}\n@media(prefers-color-scheme:dark){:root{${paletteVars(dark).join(';')}}}`;
+}
+/**
+ * Inline CSS-variable declarations for a block's opt-in per-section overrides —
+ * a palette subset (each re-deriving its on-fill colour) plus optional radius /
+ * spacing. Returns '' when there's nothing to scope. The caller escapes this for
+ * the `style` attribute.
+ */
+export function sectionOverrideCss(o) {
+    if (!o || typeof o !== 'object')
+        return '';
+    const decls = [];
+    const roles = [
+        ['bg', '--bg'], ['surface', '--surface'], ['text', '--text'],
+        ['muted', '--muted'], ['primary', '--primary'], ['accent', '--accent'],
+    ];
+    for (const [key, cssVar] of roles) {
+        const v = o[key];
+        if (typeof v === 'string' && v)
+            decls.push(`${cssVar}:${v}`);
+    }
+    if (typeof o.primary === 'string' && o.primary)
+        decls.push(`--on-primary:${readableOn(o.primary)}`);
+    if (typeof o.accent === 'string' && o.accent)
+        decls.push(`--on-accent:${readableOn(o.accent)}`);
+    if (o.radius && RADIUS_PX[o.radius] !== undefined)
+        decls.push(`--radius:${RADIUS_PX[o.radius]}`);
+    if (o.spacing && SPACE_MULT[o.spacing] !== undefined) {
+        const m = SPACE_MULT[o.spacing];
+        decls.push(`--space:${m}rem`, `--space-lg:${(m * 3).toFixed(2)}rem`);
+    }
+    return decls.join(';');
+}

package/lib/types.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Core types for the block engine (see docs/APPS_BLOCKS_ARCHITECTURE.md).
+ *
+ * A `SiteManifest` is the single source of truth the AI *composes and edits* —
+ * design tokens (the shared "baseplate") plus an ordered list of typed blocks
+ * (the "bricks"). It is never raw HTML: the renderer turns a manifest into a
+ * self-contained static document, and every reachable manifest is valid by
+ * construction (schema-validated before it is applied).
+ */
+export type Mode = 'light' | 'dark' | 'auto';
+export type Scale = 'compact' | 'default' | 'expressive';
+export type Radius = 'sharp' | 'soft' | 'round';
+export type Spacing = 'tight' | 'default' | 'airy';
+export type Motion = 'none' | 'subtle' | 'lively';
+/** The shared design system every block inherits (coherence = one edit changes the whole site). */
+export interface Palette {
+    bg: string;
+    surface: string;
+    text: string;
+    muted: string;
+    primary: string;
+    accent: string;
+}
+export interface DesignTokens {
+    mode: Mode;
+    palette: Palette;
+    /**
+     * Optional dark-mode palette. Only consulted when `mode: 'auto'`: the base
+     * `palette` renders by default and this one takes over under
+     * `@media (prefers-color-scheme: dark)`. Absent + `auto` → a built-in default
+     * dark palette. Ignored for `mode: 'light' | 'dark'` (the palette is used as-is).
+     */
+    darkPalette?: Palette;
+    typography: {
+        fontStack: string;
+        scale: Scale;
+    };
+    radius: Radius;
+    spacing: Spacing;
+    motion: Motion;
+}
+/**
+ * Per-section design overrides (opt-in). A block may tint itself away from the
+ * shared baseplate for a subset of palette roles; the renderer scopes these as
+ * CSS custom properties on a wrapper so only that section is affected and the
+ * rest of the site stays coherent. Additive + optional — absent = inherit.
+ */
+export type SectionOverrides = Partial<Palette> & {
+    radius?: Radius;
+    spacing?: Spacing;
+};
+/** One placed brick: a type from the closed catalog + its typed, validated config. */
+export interface Block {
+    id: string;
+    type: string;
+    visible: boolean;
+    config: Record<string, unknown>;
+    /** Opt-in per-section palette overrides (§ theming). Absent = inherit tokens. */
+    overrides?: SectionOverrides;
+}
+export interface SiteMeta {
+    title: string;
+    description: string;
+    lang: string;
+}
+/**
+ * Optional PWA descriptor. When present the engine can emit a Web App Manifest
+ * + service worker alongside the HTML, and the document gains installability
+ * meta. Additive: a manifest without a `pwa` block renders exactly as before.
+ */
+export interface PwaConfig {
+    name?: string;
+    shortName?: string;
+    description?: string;
+    themeColor?: string;
+    backgroundColor?: string;
+    display?: 'standalone' | 'fullscreen' | 'minimal-ui' | 'browser';
+    startUrl?: string;
+    scope?: string;
+    icons?: Array<{
+        src: string;
+        sizes: string;
+        type?: string;
+        purpose?: string;
+    }>;
+    /** Precache the static shell + offer an offline fallback. */
+    offline?: boolean;
+}
+/** Optional SEO/social descriptor emitted into <head>. Additive + optional. */
+export interface SeoConfig {
+    canonical?: string;
+    ogTitle?: string;
+    ogDescription?: string;
+    ogImage?: string;
+    twitterCard?: 'summary' | 'summary_large_image';
+    noindex?: boolean;
+}
+export interface SiteManifest {
+    meta: SiteMeta;
+    design: DesignTokens;
+    blocks: Block[];
+    /** Bumped on each accepted edit → undo / history / draft-vs-publish. */
+    version: number;
+    /** Optional: emit a Web App Manifest + service worker (installable PWA). */
+    pwa?: PwaConfig;
+    /** Optional: SEO/social meta for <head>. */
+    seo?: SeoConfig;
+}

package/lib/types.js

@@ -0,0 +1,10 @@
+/**
+ * Core types for the block engine (see docs/APPS_BLOCKS_ARCHITECTURE.md).
+ *
+ * A `SiteManifest` is the single source of truth the AI *composes and edits* —
+ * design tokens (the shared "baseplate") plus an ordered list of typed blocks
+ * (the "bricks"). It is never raw HTML: the renderer turns a manifest into a
+ * self-contained static document, and every reachable manifest is valid by
+ * construction (schema-validated before it is applied).
+ */
+export {};

package/lib/validate.d.ts

@@ -0,0 +1,10 @@
+import type { SiteManifest } from './types.js';
+export interface Validation {
+    ok: boolean;
+    errors: string[];
+    warnings: string[];
+}
+/** Validate one block's config against its brick schema. */
+export declare function validateBlock(type: string, config: unknown): Validation;
+/** Validate a whole manifest: shape + every block. */
+export declare function validateManifest(manifest: SiteManifest): Validation;

package/lib/validate.js

@@ -0,0 +1,48 @@
+/**
+ * Strict validation — the gate an *edit operation* passes before it is applied.
+ * `ok` keys off HARD errors only (wrong type / invalid enum / unknown type /
+ * duplicate id): those mean the op is malformed and must be rejected. Missing
+ * content (a headline not yet written) is a `warning` — the block renders with a
+ * placeholder, so it never blocks the edit.
+ */
+import { parse } from './schema.js';
+import { getSpec } from './registry.js';
+/** Validate one block's config against its brick schema. */
+export function validateBlock(type, config) {
+    const spec = getSpec(type);
+    if (!spec)
+        return { ok: false, errors: [`unknown block type: ${type}`], warnings: [] };
+    const r = parse(spec.schema, config ?? {});
+    return {
+        ok: r.ok,
+        errors: r.errors.map((e) => `${type}.${e}`),
+        warnings: r.warnings.map((w) => `${type}.${w}`),
+    };
+}
+/** Validate a whole manifest: shape + every block. */
+export function validateManifest(manifest) {
+    const errors = [];
+    const warnings = [];
+    if (!manifest || typeof manifest !== 'object')
+        return { ok: false, errors: ['manifest: required'], warnings: [] };
+    if (!Array.isArray(manifest.blocks)) {
+        errors.push('blocks: must be an array');
+    }
+    else {
+        const seen = new Set();
+        manifest.blocks.forEach((b, i) => {
+            if (!b || typeof b.id !== 'string' || !b.id)
+                errors.push(`blocks[${i}].id: required`);
+            else if (seen.has(b.id))
+                errors.push(`blocks[${i}].id: duplicate "${b.id}"`);
+            else
+                seen.add(b.id);
+            const v = validateBlock(b?.type, b?.config);
+            for (const e of v.errors)
+                errors.push(`blocks[${i}].${e}`);
+            for (const w of v.warnings)
+                warnings.push(`blocks[${i}].${w}`);
+        });
+    }
+    return { ok: errors.length === 0, errors, warnings };
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@bytesbrains/weblocks",
+  "version": "0.2.0",
+  "description": "Block engine for AI-composable web apps — the AI composes a SiteManifest from a fixed block catalog; the engine validates and renders it to static HTML. Snap-together \"Lego\" web building blocks, shareable across repos.",
+  "keywords": [
+    "ai",
+    "llm",
+    "web-builder",
+    "site-generator",
+    "blocks",
+    "components",
+    "lego",
+    "manifest",
+    "static-site",
+    "structured-output",
+    "function-calling"
+  ],
+  "license": "MIT",
+  "author": "bytesbrains",
+  "type": "module",
+  "engines": { "node": ">=20" },
+  "sideEffects": false,
+  "main": "./lib/index.js",
+  "module": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    },
+    "./catalog.json": "./catalog.json"
+  },
+  "files": [
+    "lib",
+    "!lib/**/*.test.js",
+    "!lib/**/*.test.d.ts",
+    "!lib/example.*",
+    "catalog.json",
+    "CATALOG.md",
+    "AGENT.md",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bytesbrains/weblocks.git"
+  },
+  "homepage": "https://github.com/bytesbrains/weblocks#readme",
+  "bugs": { "url": "https://github.com/bytesbrains/weblocks/issues" },
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "emit:catalog": "node scripts/emit-catalog.mjs",
+    "test": "tsc -p tsconfig.json && node --test lib/*.test.js",
+    "example": "tsc -p tsconfig.json && node lib/example.js",
+    "ai": "tsc -p tsconfig.json && node scripts/ai-run.mjs",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build && npm run emit:catalog && npm test"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}