@bytesbrains/weblocks 0.3.0 → 0.4.0

package/AGENT.md

@@ -46,7 +46,7 @@ its exact config schema:
 - `catalogPrompt()` — a compact text menu for a system prompt.
 - `CATALOG.md` — the same, human-readable.
 
-The 39 block types, by group:
+The 40 block types, by group:
 
 - **Chrome/app-shell:** `nav`, `app-shell`, `sidebar`, `announcement-bar`, `footer`
 - **Heroes:** `hero`, `hero-app`
@@ -58,6 +58,7 @@ The 39 block types, by group:
 - **Collections:** `blog-list`, `blog-post`, `feed`
 - **Dynamic (powered):** `contact-form`, `newsletter`, `search`, `auth`
 - **Conversion/rhythm:** `cta`, `social-links`, `contact-details`, `divider`, `spacer`
+- **Legal:** `legal` (terms/privacy links that open safe-Markdown dialogs; content is Markdown, never raw HTML)
 
 ## Composing a manifest
 

package/CATALOG.md

@@ -1,8 +1,8 @@
-# @bytesbrains/weblocks — Block Catalog (v0.3.0)
+# @bytesbrains/weblocks — Block Catalog (v0.4.0)
 
 The AI composes a `SiteManifest` (`{ meta, design, blocks[] }`) using **only** the block types below, then the engine validates + renders it to static HTML. This file is generated from the code (`npm run emit:catalog`) — do not edit by hand.
 
-**Block types:** `app-shell` · `nav` · `announcement-bar` · `sidebar` · `hero` · `hero-app` · `features` · `about` · `rich-text` · `split` · `steps` · `stats` · `services-catalogue` · `pricing` · `logos` · `team` · `gallery` · `carousel` · `video` · `map` · `timeline` · `tabs` · `accordion` · `testimonials` · `faq` · `blog-list` · `blog-post` · `feed` · `contact-form` · `newsletter` · `search` · `auth` · `cta` · `social-links` · `contact-details` · `directions` · `divider` · `spacer` · `footer`
+**Block types:** `app-shell` · `nav` · `announcement-bar` · `sidebar` · `hero` · `hero-app` · `features` · `about` · `rich-text` · `split` · `steps` · `stats` · `services-catalogue` · `pricing` · `logos` · `team` · `gallery` · `carousel` · `video` · `map` · `timeline` · `tabs` · `accordion` · `testimonials` · `faq` · `blog-list` · `blog-post` · `feed` · `contact-form` · `newsletter` · `search` · `auth` · `cta` · `social-links` · `contact-details` · `directions` · `legal` · `divider` · `spacer` · `footer`
 
 ## `app-shell`
 
@@ -386,6 +386,17 @@ A location card with deep links that open the visitor’s map app (Google/Apple
 | `directionsLabel` | string |  |  |
 | `appleMaps` | boolean |  |  |
 
+## `legal`
+
+Policy links (terms, privacy, cookies, …) that open as scrollable, dismissible dialogs; each body is safe Markdown (never raw HTML). No JavaScript.
+
+| field | type | required | notes |
+|---|---|---|---|
+| `title` | string |  |  |
+| `align` | undefined (start\|center\|end) |  |  |
+| `separator` | string |  |  |
+| `documents` | array |  |  |
+
 ## `divider`
 
 A visual section break rendered as a thin line, a dotted rule, or a gradient bar.

package/CHANGELOG.md

@@ -5,6 +5,19 @@ follows [semantic versioning](https://semver.org): the **block catalog** and the
 **`SiteManifest` shape** are the public contract — additive block/field changes
 are minor, breaking changes to either are major.
 
+## 0.4.0 — 2026-07-16
+
+Additive and non-breaking — every `0.3.0` manifest still validates and renders
+identically. Catalog 39 → 40.
+
+### Added
+- **`legal` block** — policy links (Terms, Privacy, Cookies, …) that open as
+  **scrollable, dismissible dialogs** (pure CSS `:target`, no JavaScript). Each
+  document's body is authored in a **safe Markdown subset** (headings, lists,
+  links, emphasis, quotes, rules) — rich formatting, but **never raw HTML** (any
+  literal HTML is escaped, not executed). Exports `renderMarkdown`. Catalog now
+  40 blocks.
+
 ## 0.3.0 — 2026-07-16
 
 Additive and non-breaking — every `0.2.0` manifest still validates and renders

package/README.md

@@ -139,7 +139,7 @@ import catalogJson from '@bytesbrains/weblocks/catalog.json' with { type: 'json'
 
 ## Block catalog
 
-**39 typed blocks.** Full field reference in [`CATALOG.md`](./CATALOG.md).
+**40 typed blocks.** Full field reference in [`CATALOG.md`](./CATALOG.md).
 
 | Group | Blocks |
 |---|---|
@@ -152,6 +152,7 @@ import catalogJson from '@bytesbrains/weblocks/catalog.json' with { type: 'json'
 | Collections | `blog-list` · `blog-post` · `feed` |
 | Dynamic (powered) | `contact-form` · `newsletter` · `search` · `auth` |
 | Conversion / rhythm | `cta` · `social-links` · `contact-details` · `divider` · `spacer` |
+| Legal | `legal` (terms/privacy links → safe-Markdown dialogs) |
 
 `rich-text` and `blog-post` carry **typed** content nodes (headings, paragraphs,
 quotes, lists) — a safe freeform-content escape hatch that is never raw HTML.

package/catalog.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "package": "@bytesbrains/weblocks",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Block catalog for @bytesbrains/weblocks. Send this to the model as its API reference; it composes a SiteManifest ({ meta, design, blocks[] }) using ONLY these block types. The engine then validates and renders it.",
   "blockTypes": [
     "app-shell",
@@ -40,6 +40,7 @@
     "social-links",
     "contact-details",
     "directions",
+    "legal",
     "divider",
     "spacer",
     "footer"
@@ -1862,6 +1863,62 @@
         "additionalProperties": false
       }
     },
+    {
+      "type": "legal",
+      "description": "Policy links (terms, privacy, cookies, …) that open as scrollable, dismissible dialogs; each body is safe Markdown (never raw HTML). No JavaScript.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "title": {
+            "type": "string",
+            "maxLength": 120,
+            "default": ""
+          },
+          "align": {
+            "enum": [
+              "start",
+              "center",
+              "end"
+            ],
+            "default": "center"
+          },
+          "separator": {
+            "type": "string",
+            "maxLength": 4,
+            "default": "·"
+          },
+          "documents": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "label": {
+                  "type": "string",
+                  "maxLength": 60,
+                  "default": ""
+                },
+                "title": {
+                  "type": "string",
+                  "maxLength": 120,
+                  "default": ""
+                },
+                "content": {
+                  "type": "string",
+                  "maxLength": 40000,
+                  "default": ""
+                }
+              },
+              "required": [
+                "label"
+              ],
+              "additionalProperties": false
+            },
+            "maxItems": 8
+          }
+        },
+        "additionalProperties": false
+      }
+    },
     {
       "type": "divider",
       "description": "A visual section break rendered as a thin line, a dotted rule, or a gradient bar.",

package/lib/blocks/legal.d.ts

@@ -0,0 +1,2 @@
+import type { BlockSpec } from '../registry.js';
+export declare const legal: BlockSpec;

package/lib/blocks/legal.js

@@ -0,0 +1,100 @@
+/**
+ * `legal` — policy links (Terms, Privacy, Cookies, …) that open as **scrollable,
+ * dismissible dialogs**. Each document's body is authored in a SAFE Markdown
+ * subset (see markdown.ts) — rich formatting, but never raw HTML (any literal
+ * HTML is escaped, not executed). Static brick: the dialog is pure CSS
+ * (`:target`), so it works with zero JavaScript — click a link to open, click
+ * the ✕ or the backdrop to dismiss.
+ *
+ * Drop it near the `footer` for the familiar "Terms · Privacy" footer row.
+ */
+import { escapeAttr, escapeHtml } from '../schema.js';
+import { renderMarkdown } from '../markdown.js';
+const schema = {
+    title: { kind: 'string', default: '', max: 120 },
+    align: { kind: 'enum', values: ['start', 'center', 'end'], default: 'center' },
+    separator: { kind: 'string', default: '·', max: 4 },
+    documents: {
+        kind: 'array', max: 8,
+        of: {
+            kind: 'object',
+            fields: {
+                label: { kind: 'string', required: true, default: '', max: 60 }, // link text
+                title: { kind: 'string', default: '', max: 120 }, // dialog heading (defaults to label)
+                content: { kind: 'string', default: '', max: 40000 }, // Markdown body
+            },
+        },
+    },
+};
+const css = `
+.blk-legal{padding:var(--space) var(--space);background:var(--bg);color:var(--text)}
+.blk-legal .links{display:flex;flex-wrap:wrap;align-items:center;gap:.35em .8em;max-width:1080px;margin:0 auto}
+.blk-legal.align-center .links{justify-content:center}
+.blk-legal.align-end .links{justify-content:flex-end}
+.blk-legal .lead{color:var(--muted);font-size:var(--fs-base)}
+.blk-legal .links a.open{color:var(--muted);text-decoration:none;font-size:var(--fs-base);border-bottom:1px solid transparent}
+.blk-legal .links a.open:hover,.blk-legal .links a.open:focus-visible{color:var(--primary);border-bottom-color:currentColor}
+.blk-legal .sep{color:var(--muted);opacity:.6;user-select:none}
+/* Dialog — hidden until its id is the URL :target. */
+.blk-legal .modal{position:fixed;inset:0;z-index:1000;display:none;padding:calc(var(--space)*1.2)}
+.blk-legal .modal:target{display:grid;place-items:center}
+.blk-legal .backdrop{position:absolute;inset:0;background:color-mix(in srgb,#000 55%,transparent);border:0;display:block}
+.blk-legal .panel{position:relative;display:flex;flex-direction:column;width:min(680px,100%);max-height:85vh;background:var(--surface);color:var(--text);border-radius:var(--radius);box-shadow:0 24px 60px -12px rgba(0,0,0,.5);overflow:hidden}
+.blk-legal .pbar{display:flex;align-items:center;justify-content:space-between;gap:1em;padding:calc(var(--space)*1.1) calc(var(--space)*1.3);border-bottom:1px solid color-mix(in srgb,var(--text) 12%,transparent)}
+.blk-legal .pbar h2{margin:0;font-size:var(--fs-lg);font-weight:800}
+.blk-legal .close{flex:0 0 auto;display:inline-flex;align-items:center;justify-content:center;width:2em;height:2em;border-radius:999px;text-decoration:none;color:var(--muted);font-size:1.3em;line-height:1;background:color-mix(in srgb,var(--text) 6%,transparent)}
+.blk-legal .close:hover,.blk-legal .close:focus-visible{color:var(--text);background:color-mix(in srgb,var(--text) 12%,transparent)}
+.blk-legal .body{overflow:auto;padding:calc(var(--space)*1.3);line-height:1.65;overscroll-behavior:contain}
+.blk-legal .body>:first-child{margin-top:0}
+.blk-legal .body>:last-child{margin-bottom:0}
+.blk-legal .body h2{font-size:var(--fs-lg);font-weight:800;margin:1.4em 0 .4em}
+.blk-legal .body h3{font-size:var(--fs-lg);font-weight:700;margin:1.2em 0 .3em}
+.blk-legal .body h4{font-size:var(--fs-base);font-weight:700;margin:1em 0 .3em;text-transform:uppercase;letter-spacing:.03em;color:var(--muted)}
+.blk-legal .body p{margin:0 0 1em}
+.blk-legal .body ul,.blk-legal .body ol{margin:0 0 1em;padding-left:1.4em}
+.blk-legal .body li{margin:.3em 0}
+.blk-legal .body a{color:var(--primary);text-decoration:underline;text-underline-offset:2px}
+.blk-legal .body blockquote{margin:1em 0;padding:.2em 0 .2em 1em;border-left:3px solid var(--accent);color:var(--muted)}
+.blk-legal .body code{background:color-mix(in srgb,var(--text) 8%,transparent);padding:.1em .35em;border-radius:4px;font-size:.9em}
+.blk-legal .body hr{border:0;border-top:1px solid color-mix(in srgb,var(--text) 15%,transparent);margin:1.4em 0}
+/* Lock background scroll while a dialog is open (progressive; no-op if unsupported). */
+html:has(.blk-legal .modal:target){overflow:hidden}
+`.trim();
+function render(config, _tokens, ctx) {
+    const bid = String(ctx?.id ?? 'legal').replace(/[^A-Za-z0-9_-]/g, '') || 'legal';
+    const title = config.title;
+    const align = ['start', 'center', 'end'].includes(config.align) ? config.align : 'center';
+    const sep = escapeHtml(config.separator || '·');
+    const docs = (config.documents ?? []).filter((d) => d && d.label);
+    const links = docs
+        .map((d, i) => `<a class="open" id="open-${bid}-${i}" href="#${bid}-${i}">${escapeHtml(d.label)}</a>`)
+        .join(`<span class="sep" aria-hidden="true">${sep}</span>`);
+    const dialogs = docs.map((d, i) => {
+        const did = `${bid}-${i}`;
+        const heading = d.title || d.label;
+        return `<div class="modal" id="${did}" role="dialog" aria-modal="true" aria-labelledby="h-${did}">
+    <a class="backdrop" href="#open-${did}" aria-label="Close" tabindex="-1"></a>
+    <div class="panel">
+      <div class="pbar">
+        <h2 id="h-${did}">${escapeHtml(heading)}</h2>
+        <a class="close" href="#open-${did}" aria-label="Close dialog">&times;</a>
+      </div>
+      <div class="body">${renderMarkdown(d.content)}</div>
+    </div>
+  </div>`;
+    }).join('\n  ');
+    return `<section class="blk-legal align-${align}" aria-label="${escapeAttr(title || 'Legal')}">
+  <div class="links">
+    ${title ? `<span class="lead">${escapeHtml(title)}</span>` : ''}
+    ${links}
+  </div>
+  ${dialogs}
+</section>`;
+}
+export const legal = {
+    type: 'legal',
+    description: 'Policy links (terms, privacy, cookies, …) that open as scrollable, dismissible dialogs; each body is safe Markdown (never raw HTML). No JavaScript.',
+    schema,
+    css,
+    render,
+};

package/lib/index.d.ts

@@ -14,6 +14,7 @@ export { NOOP_RUNTIME, pathRuntime, runtimeNeeds, type RuntimeAdapter, type Runt
 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 { renderMarkdown } from './markdown.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

@@ -6,6 +6,7 @@ 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 { renderMarkdown } from './markdown.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/markdown.d.ts

@@ -0,0 +1,2 @@
+/** Render a Markdown-subset string to safe HTML. */
+export declare function renderMarkdown(src: unknown): string;

package/lib/markdown.js

@@ -0,0 +1,90 @@
+/**
+ * A tiny, SAFE Markdown-subset renderer — escape-first, whitelist-only.
+ *
+ * This is NOT a raw-HTML passthrough (that would break the engine's no-injection
+ * invariant, see VISION.md §3). Every character of the source is HTML-escaped
+ * BEFORE any formatting is applied, so a literal `<script>` renders as text,
+ * never markup. Only a fixed set of safe elements is ever produced, and link
+ * hrefs are scheme-sanitized. Total: it never throws.
+ *
+ * Supported:
+ *   #, ##, ###…        headings (→ h2…h6)
+ *   -  or  *           unordered list        1.  ordered list
+ *   >                  blockquote            --- / *** / ___  horizontal rule
+ *   blank line         paragraph break
+ *   **bold**  *italic*  _italic_  `code`  [text](url)
+ */
+import { escapeHtml, sanitizeUrl } from './schema.js';
+/** Inline formatting. Operates on ALREADY-ESCAPED text; only adds safe tags. */
+function inline(escaped) {
+    let s = escaped;
+    // `code` first, so its contents aren't touched by the emphasis rules.
+    s = s.replace(/`([^`]+)`/g, (_m, c) => `<code>${c}</code>`);
+    // [text](url) — url is taken from escaped text (already attribute-safe) and
+    // scheme-sanitized; not re-escaped (that would double-encode `&`).
+    s = s.replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, (_m, text, url) => `<a href="${sanitizeUrl(url)}" rel="noopener">${text}</a>`);
+    s = s.replace(/\*\*([^*]+)\*\*/g, (_m, t) => `<strong>${t}</strong>`);
+    s = s.replace(/(^|[^*])\*([^*\s][^*]*?)\*/g, (_m, pre, t) => `${pre}<em>${t}</em>`);
+    s = s.replace(/(^|[^_\w])_([^_]+)_/g, (_m, pre, t) => `${pre}<em>${t}</em>`);
+    return s;
+}
+const esc = (raw) => inline(escapeHtml(raw));
+/** Render a Markdown-subset string to safe HTML. */
+export function renderMarkdown(src) {
+    const lines = String(src ?? '').replace(/\r\n?/g, '\n').split('\n');
+    const out = [];
+    let para = [];
+    const flush = () => { if (para.length) {
+        out.push(`<p>${esc(para.join(' '))}</p>`);
+        para = [];
+    } };
+    for (let i = 0; i < lines.length;) {
+        const t = lines[i].trim();
+        if (!t) {
+            flush();
+            i++;
+            continue;
+        }
+        if (/^(-{3,}|\*{3,}|_{3,})$/.test(t)) {
+            flush();
+            out.push('<hr>');
+            i++;
+            continue;
+        }
+        const h = /^(#{1,6})\s+(.*)$/.exec(t);
+        if (h) {
+            flush();
+            out.push(`<h${Math.min(h[1].length + 1, 6)}>${esc(h[2].trim())}</h${Math.min(h[1].length + 1, 6)}>`);
+            i++;
+            continue;
+        }
+        if (/^>\s?/.test(t)) {
+            flush();
+            const q = [];
+            for (; i < lines.length && /^>\s?/.test(lines[i].trim()); i++)
+                q.push(lines[i].trim().replace(/^>\s?/, ''));
+            out.push(`<blockquote>${esc(q.join(' '))}</blockquote>`);
+            continue;
+        }
+        if (/^[-*]\s+/.test(t)) {
+            flush();
+            const items = [];
+            for (; i < lines.length && /^[-*]\s+/.test(lines[i].trim()); i++)
+                items.push(lines[i].trim().replace(/^[-*]\s+/, ''));
+            out.push(`<ul>${items.map((it) => `<li>${esc(it)}</li>`).join('')}</ul>`);
+            continue;
+        }
+        if (/^\d+\.\s+/.test(t)) {
+            flush();
+            const items = [];
+            for (; i < lines.length && /^\d+\.\s+/.test(lines[i].trim()); i++)
+                items.push(lines[i].trim().replace(/^\d+\.\s+/, ''));
+            out.push(`<ol>${items.map((it) => `<li>${esc(it)}</li>`).join('')}</ol>`);
+            continue;
+        }
+        para.push(t);
+        i++;
+    }
+    flush();
+    return out.join('\n');
+}

package/lib/registry.js

@@ -32,6 +32,7 @@ import { cta } from './blocks/cta.js';
 import { socialLinks } from './blocks/socialLinks.js';
 import { contactDetails } from './blocks/contactDetails.js';
 import { directions } from './blocks/directions.js';
+import { legal } from './blocks/legal.js';
 import { divider } from './blocks/divider.js';
 import { spacer } from './blocks/spacer.js';
 import { appShell } from './blocks/appShell.js';
@@ -56,7 +57,7 @@ const SPECS = [
     // dynamic / powered
     contactForm, newsletter, search, auth,
     // conversion / contact
-    cta, socialLinks, contactDetails, directions,
+    cta, socialLinks, contactDetails, directions, legal,
     // rhythm
     divider, spacer,
     footer,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bytesbrains/weblocks",
-  "version": "0.3.0",
+  "version": "0.4.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",