@bytesbrains/weblocks 0.2.0

package/AGENT.md

@@ -0,0 +1,214 @@
+# AGENT.md — using `@bytesbrains/weblocks` from an AI
+
+This guide is written for a **model or agent** that will build and edit web apps
+with this package. Hand it to an LLM (as context or a system prompt), or read it
+as the coding agent integrating the package. For the *why*, see
+[`VISION.md`](./VISION.md); for internals, [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md).
+
+---
+
+## What you are doing
+
+You do **not** write HTML, CSS, or JavaScript. You produce a **`SiteManifest`** — a
+JSON document of design tokens plus an ordered list of typed **blocks** chosen
+from a fixed **catalog**. The engine validates your manifest and renders it to one
+self-contained static HTML document. It cannot render a broken page, so your job
+is to compose *good, specific* content — validity is guaranteed for you.
+
+Two things you produce:
+
+1. **Compose** — a full `SiteManifest` from a brief (one shot).
+2. **Edit** — a JSON array of **edit ops** that change an existing manifest.
+
+## Prime directives
+
+1. **Use only catalog block types and config keys.** Never invent a `type` or a
+   field. The catalog (`catalog.json` / `catalogPrompt()`) is your complete,
+   closed API. If a request doesn’t fit, get as close as you can with existing
+   blocks — do not fabricate markup.
+2. **Never output raw HTML/CSS/JS.** There is no “custom HTML” block by design.
+   For freeform prose use the `rich-text` block’s *typed* nodes.
+3. **Write real, specific copy** for the described subject — no lorem ipsum, no
+   `[placeholder]`.
+4. **Order blocks top-to-bottom** as a visitor reads the page (`nav` first,
+   `footer` last).
+5. **Theme with tokens, not per-block colors.** Set `design` once; the whole app
+   inherits it. Never hand-set text colors on buttons — contrast is automatic.
+6. **Output only the JSON** asked for (a manifest object, or an ops array). No
+   prose, no code fences.
+
+## The catalog is your contract
+
+Always work from the shipped catalog — it lists every block, its description, and
+its exact config schema:
+
+- `catalog.json` — JSON Schema per block (ideal as a function-calling schema).
+- `catalogPrompt()` — a compact text menu for a system prompt.
+- `CATALOG.md` — the same, human-readable.
+
+The 37 block types, by group:
+
+- **Chrome/app-shell:** `nav`, `app-shell`, `sidebar`, `announcement-bar`, `footer`
+- **Heroes:** `hero`, `hero-app`
+- **Content:** `features`, `about`, `rich-text`, `split`, `steps`, `stats`,
+  `services-catalogue`, `pricing`, `logos`, `team`
+- **Media:** `gallery`, `carousel`, `video`, `map`
+- **Structured:** `timeline`, `tabs`, `accordion`, `testimonials`, `faq`
+- **Collections:** `blog-list`, `blog-post`, `feed`
+- **Dynamic (powered):** `contact-form`, `newsletter`, `auth`
+- **Conversion/rhythm:** `cta`, `social-links`, `contact-details`, `divider`, `spacer`
+
+## Composing a manifest
+
+Emit exactly this shape (a block’s `id` is optional — the engine assigns one):
+
+```json
+{
+  "meta": { "title": "…", "description": "…", "lang": "en" },
+  "design": {
+    "mode": "light",
+    "palette": { "bg": "#…", "surface": "#…", "text": "#…", "muted": "#…", "primary": "#…", "accent": "#…" },
+    "typography": { "fontStack": "system-ui, sans-serif", "scale": "default" },
+    "radius": "soft", "spacing": "default", "motion": "subtle"
+  },
+  "blocks": [
+    { "type": "nav", "config": { "brand": "…", "links": [ { "label": "…", "href": "#…" } ] } },
+    { "type": "hero", "config": { "headline": "…", "subhead": "…", "cta": { "label": "…", "href": "#…" } } }
+  ]
+}
+```
+
+Worked example — a bakery landing page:
+
+```json
+{
+  "meta": { "title": "Loam & Ember — wood-fired bakery", "description": "Naturally-leavened bread from a neighbourhood oven.", "lang": "en" },
+  "design": {
+    "mode": "auto",
+    "palette": { "bg": "#fbf5ec", "surface": "#ffffff", "text": "#2a201a", "muted": "#7c6a58", "primary": "#b04d2b", "accent": "#c8892f" },
+    "typography": { "fontStack": "system-ui, sans-serif", "scale": "expressive" },
+    "radius": "round", "spacing": "airy", "motion": "subtle"
+  },
+  "blocks": [
+    { "type": "nav", "config": { "brand": "Loam & Ember", "links": [ { "label": "Bread", "href": "#bread" }, { "label": "Classes", "href": "#classes" } ], "cta": { "label": "Order", "href": "#order" } } },
+    { "type": "hero", "config": { "eyebrow": "Neighbourhood bakery", "headline": "Bread with a long, slow memory", "subhead": "Naturally leavened, wood-fired at dawn.", "align": "center", "cta": { "label": "See this week’s bakes", "href": "#bread" } } },
+    { "type": "stats", "config": { "title": "From the oven", "columns": 3, "items": [ { "value": "36", "suffix": "h", "label": "Fermentation" }, { "value": "480", "suffix": "°C", "label": "Hearth" }, { "value": "3", "label": "Ingredients" } ] } },
+    { "type": "pricing", "config": { "title": "This week’s bakes", "plans": [ { "name": "Country sourdough", "price": "$9", "period": "/ loaf", "features": ["1kg boule", "Blistered crust"], "ctaLabel": "Add to order", "ctaHref": "#order" } ] } },
+    { "type": "contact-details", "config": { "title": "Visit", "address": "42 Kiln Row", "hours": "Wed–Sun · 8am–2pm" } },
+    { "type": "footer", "config": { "brand": "Loam & Ember", "copyright": "© 2026 Loam & Ember" } }
+  ]
+}
+```
+
+## Design tokens & theming
+
+Set `design` once; every block styles from it.
+
+- `mode`: `light` | `dark` | `auto`. Use **`auto`** to follow the viewer’s OS
+  theme; optionally add a `darkPalette` (same keys as `palette`) for the dark side.
+- `palette`: 6 hex roles — `bg`, `surface`, `text`, `muted`, `primary`, `accent`.
+- `typography.scale`: `compact` | `default` | `expressive`; `fontStack`: any CSS
+  font stack (no web font is loaded for you).
+- `radius`: `sharp` | `soft` | `round`; `spacing`: `tight` | `default` | `airy`;
+  `motion`: `none` | `subtle` | `lively`.
+- **Presets:** instead of hand-mixing hex, base the palette on a named preset —
+  `sand`, `midnight`, `forest`, `mono`, `candy`, `ocean` — or apply one via the
+  `applyPreset` op when editing.
+- **Do not set text colors on buttons.** `--on-primary` / `--on-accent` are
+  derived automatically and stay legible on any palette.
+
+## Editing with ops
+
+To change an existing manifest, emit a **JSON array of ops**. Each is validated
+before it applies; a bad op is skipped (not a corruption), and the manifest
+`version` bumps per accepted edit.
+
+```json
+[
+  { "op": "updateBlock", "id": "hero-1", "config": { "headline": "New headline" } },
+  { "op": "applyPreset", "name": "midnight" },
+  { "op": "addBlock", "type": "faq", "at": 4, "config": { "items": [ { "question": "…", "answer": "…" } ] } }
+]
+```
+
+Op vocabulary:
+
+| Op | Purpose |
+|---|---|
+| `addBlock` `{ type, config?, at?, id? }` | insert a block |
+| `updateBlock` `{ id, config }` | patch a block’s config (only changed keys) |
+| `removeBlock` `{ id }` / `moveBlock` `{ id, to }` / `setVisible` `{ id, visible }` | block-level edits |
+| `addItem` / `updateItem` / `removeItem` / `moveItem` `{ id, field, … }` | edit **one item** of an array field (e.g. one `features` item) without rewriting the block |
+| `setDesignTokens` `{ patch }` / `applyPreset` `{ name }` | site-wide theming |
+| `setOverrides` `{ id, overrides }` | per-section palette / `radius` / `spacing` (or `null` to clear) |
+| `setMeta` `{ patch }` | title / description / lang |
+
+Prefer **array-item ops** for “change one thing” requests — they’re surgical and
+cheap:
+
+```json
+[ { "op": "updateItem", "id": "features-1", "field": "items", "index": 0, "patch": { "text": "Now twice as fast" } } ]
+```
+
+## Powered (dynamic) blocks
+
+`contact-form`, `newsletter`, and `auth` need a backend. You still only fill their
+typed config (fields, labels, providers). The block declares the runtime
+capability it needs; the **host** wires the endpoint. If no runtime is wired, the
+block renders inert-but-valid — that is expected, not an error. Never put secrets,
+endpoints, captcha keys, or backend logic in the config.
+
+## PWA & SEO (optional, additive)
+
+Add top-level fields to make the app installable / discoverable:
+
+```json
+{ "pwa": { "name": "My App", "shortName": "App", "offline": true },
+  "seo": { "ogImage": "https://…/card.png", "twitterCard": "summary_large_image" } }
+```
+
+## Programmatic integration (for the app developer)
+
+The engine is provider-agnostic — you inject the model call:
+
+```ts
+import { generateSite, editSite, renderSite } from '@bytesbrains/weblocks';
+
+const callModel = async ({ system, user }) => /* call any LLM */ '…';
+
+const { ok, manifest } = await generateSite(brief, callModel);   // brief → manifest
+const html = renderSite(manifest);                                // manifest → static HTML
+const { manifest: next } = await editSite(manifest, 'go dark', callModel); // NL → validated ops
+```
+
+`buildGenerationPrompt(brief)` and `buildEditPrompt(manifest, message)` return the
+exact `{ system, user }` prompts (with the catalog embedded) if you want to call
+the model yourself; `parseManifestResponse` / `parseOpsResponse` turn a raw reply
+into a validated result.
+
+## Guarantees you can rely on
+
+- **Validity ⟂ your quality.** Whatever you emit is schema-validated and totally
+  rendered. A malformed or partial reply degrades gracefully — worst case is a
+  rejected op or a defaulted field, never a broken page or an injection.
+- **Non-breaking.** The catalog and manifest shape are versioned; existing
+  manifests keep rendering. Grow by adding typed blocks/fields, never escape
+  hatches.
+
+---
+
+## For agents extending the package
+
+If you are modifying this repo (not just using it):
+
+- A block is a `BlockSpec` (`type`, `description`, `schema`, `css`, `render`,
+  optional `island` / `runtime`) in `src/blocks/`, registered in
+  `src/registry.ts`.
+- **Definition of done:** typed schema (no raw-HTML field), consumes shared design
+  tokens, total render (default every field, escape all text via
+  `escapeHtml`/`escapeAttr`, sanitize URLs via `sanitizeUrl`, never throw), a
+  single top-level landmark, additive & non-breaking.
+- After changes: `npm run build && npm test && npm run emit:catalog` (the shared
+  suite in `src/blocks.test.ts` enforces the DoD for every block), and update the
+  closed-vocabulary list in `blocks.test.ts`.
+- Keep everything **consumer-neutral** — no host, backend, or downstream names.

package/CATALOG.md

@@ -0,0 +1,387 @@
+# @bytesbrains/weblocks — Block Catalog (v0.2.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` · `auth` · `cta` · `social-links` · `contact-details` · `divider` · `spacer` · `footer`
+
+## `app-shell`
+
+A persistent bottom tab bar for app-like navigation, each tab an optional icon plus a label linking to a view.
+
+| field | type | required | notes |
+|---|---|---|---|
+| `brand` | string |  |  |
+| `tabs` | array |  |  |
+
+## `nav`
+
+Top navigation bar: brand/logo text, a row of links, and an optional call-to-action button. Place first.
+
+| field | type | required | notes |
+|---|---|---|---|
+| `brand` | string | yes |  |
+| `sticky` | boolean |  |  |
+| `links` | array |  |  |
+| `cta` | object |  |  |
+
+## `announcement-bar`
+
+A dismissible full-width strip for a short promo or notice, with an optional inline link and info/promo/warning tone.
+
+| field | type | required | notes |
+|---|---|---|---|
+| `text` | string | yes |  |
+| `linkLabel` | string |  |  |
+| `href` | string |  |  |
+| `tone` | undefined (info\|promo\|warning) |  |  |
+| `dismissible` | boolean |  |  |
+
+## `sidebar`
+
+A vertical section/drawer navigation for multi-view apps: an optional title over a list of icon-and-label links.
+
+| field | type | required | notes |
+|---|---|---|---|
+| `title` | string |  |  |
+| `links` | array |  |  |
+
+## `hero`
+
+Top-of-page banner: a big headline with an optional eyebrow, subheading, and one call-to-action button.
+
+| field | type | required | notes |
+|---|---|---|---|
+| `eyebrow` | string |  |  |
+| `headline` | string | yes |  |
+| `subhead` | string |  |  |
+| `align` | undefined (center\|left) |  |  |
+| `cta` | object |  |  |
+
+## `hero-app`
+
+An app landing hero: a headline and subhead over a primary install button, with a horizontal scroll row of app screenshots.
+
+| field | type | required | notes |
+|---|---|---|---|
+| `headline` | string | yes |  |
+| `subhead` | string |  |  |
+| `installLabel` | string |  |  |
+| `installHref` | string |  |  |
+| `screenshots` | array |  |  |
+
+## `features`
+
+A grid of value propositions, each with an optional icon/emoji, a title, and a short line of text.
+
+| field | type | required | notes |
+|---|---|---|---|
+| `title` | string |  |  |
+| `subtitle` | string |  |  |
+| `columns` | integer (2\|3\|4) |  |  |
+| `items` | array |  |  |
+
+## `about`
+
+A story/mission section: eyebrow, title, prose body, and an optional side image (choose which side).
+
+| field | type | required | notes |
+|---|---|---|---|
+| `eyebrow` | string |  |  |
+| `title` | string |  |  |
+| `body` | string |  |  |
+| `image` | string |  |  |
+| `imageAlt` | string |  |  |
+| `imageSide` | undefined (left\|right) |  |  |
+
+## `rich-text`
+
+A typed prose section with ordered headings, paragraphs, quotes, and bullet/numbered lists — a safe freeform-content block, never raw HTML.
+
+| field | type | required | notes |
+|---|---|---|---|
+| `blocks` | array |  |  |
+
+## `split`
+
+Alternating image-and-text rows; the image side flips each row, and rows without an image collapse to centered text.
+
+| field | type | required | notes |
+|---|---|---|---|
+| `rows` | array |  |  |
+
+## `steps`
+
+A numbered how-it-works / process list: an optional title and subtitle over auto-numbered step cards, each with a title and short text.
+
+| field | type | required | notes |
+|---|---|---|---|
+| `title` | string |  |  |
+| `subtitle` | string |  |  |
+| `items` | array |  |  |
+
+## `stats`
+
+A grid of metric counters: each stat shows an optional prefix/suffix around a big value with a muted label, with an optional count-up animation.
+
+| field | type | required | notes |
+|---|---|---|---|
+| `title` | string |  |  |
+| `columns` | integer (2\|3\|4) |  |  |
+| `items` | array |  |  |
+
+## `services-catalogue`
+
+A grid of services or products, each with a name, optional price, description, and link. Use for "what we offer".
+
+| field | type | required | notes |
+|---|---|---|---|
+| `title` | string |  |  |
+| `subtitle` | string |  |  |
+| `items` | array |  |  |
+
+## `pricing`
+
+A row of pricing/tier cards, each with a name, price, feature list, and a call-to-action button; one plan can be highlighted.
+
+| field | type | required | notes |
+|---|---|---|---|
+| `title` | string |  |  |
+| `subtitle` | string |  |  |
+| `plans` | array |  |  |
+
+## `logos`
+
+A centered strip of client or partner logos (grayscale until hover), each optionally linking out, under a short heading.
+
+| field | type | required | notes |
+|---|---|---|---|
+| `title` | string |  |  |
+| `items` | array |  |  |
+
+## `team`
+
+A grid of people cards with photo (or initials), name, role, a short bio, and optional social links.
+
+| field | type | required | notes |
+|---|---|---|---|
+| `title` | string |  |  |
+| `subtitle` | string |  |  |
+| `columns` | integer (2\|3\|4) |  |  |
+| `members` | array |  |  |
+
+## `gallery`
+
+A responsive image grid (grid/masonry/carousel) with an optional click-to-zoom lightbox. Each item needs a src and alt text.
+
+| field | type | required | notes |
+|---|---|---|---|
+| `layout` | undefined (grid\|masonry\|carousel) |  |  |
+| `columns` | integer (2\|3\|4) |  |  |
+| `gap` | undefined (sm\|md\|lg) |  |  |
+| `lightbox` | boolean |  |  |
+| `items` | array |  |  |
+
+## `carousel`
+
+A horizontal, swipeable carousel of image slides with optional captions; scrolls natively and can be enhanced with arrows/autoplay.
+
+| field | type | required | notes |
+|---|---|---|---|
+| `title` | string |  |  |
+| `items` | array |  |  |
+| `autoplay` | boolean |  |  |
+
+## `video`
+
+A responsive embedded video from YouTube or Vimeo (by id or URL) or a self-hosted file, with an optional caption.
+
+| field | type | required | notes |
+|---|---|---|---|
+| `provider` | undefined (youtube\|vimeo\|file) |  |  |
+| `src` | string | yes |  |
+| `title` | string |  |  |
+| `poster` | string |  |  |
+| `caption` | string |  |  |
+
+## `map`
+
+An embedded location map for a place or address query, with configurable zoom and height and a link to the full map.
+
+| field | type | required | notes |
+|---|---|---|---|
+| `query` | string | yes |  |
+| `zoom` | integer |  |  |
+| `height` | integer |  |  |
+| `label` | string |  |  |
+
+## `timeline`
+
+A vertical timeline of chronological milestones, each with an optional date, a title, and supporting text.
+
+| field | type | required | notes |
+|---|---|---|---|
+| `title` | string |  |  |
+| `items` | array |  |  |
+
+## `tabs`
+
+Tabbed content panels that switch with no JavaScript; each tab has a label and a text panel.
+
+| field | type | required | notes |
+|---|---|---|---|
+| `items` | array |  |  |
+
+## `accordion`
+
+Generic collapsible disclosure panels (native details/summary, no JavaScript); each panel has a heading and body.
+
+| field | type | required | notes |
+|---|---|---|---|
+| `title` | string |  |  |
+| `items` | array |  |  |
+
+## `testimonials`
+
+A grid of customer quotes, each with the quote text and an optional author name and role.
+
+| field | type | required | notes |
+|---|---|---|---|
+| `title` | string |  |  |
+| `items` | array |  |  |
+
+## `faq`
+
+An accordion of question/answer pairs. Expands/collapses natively (no JS).
+
+| field | type | required | notes |
+|---|---|---|---|
+| `title` | string |  |  |
+| `items` | array |  |  |
+
+## `blog-list`
+
+A post index as a grid of cards, each with an optional cover image, tag, date, title, and excerpt linking to the post.
+
+| field | type | required | notes |
+|---|---|---|---|
+| `title` | string |  |  |
+| `columns` | integer (2\|3) |  |  |
+| `posts` | array |  |  |
+
+## `blog-post`
+
+A single article layout with an optional cover, title, author/date, and a typed body (headings, paragraphs, quotes, bullets).
+
+| field | type | required | notes |
+|---|---|---|---|
+| `title` | string | yes |  |
+| `date` | string |  |  |
+| `author` | string |  |  |
+| `cover` | string |  |  |
+| `coverAlt` | string |  |  |
+| `body` | array |  |  |
+
+## `feed`
+
+A generic data-driven list of items in a list or card layout, each with a title, optional subtitle/text, badge, image, and link.
+
+| field | type | required | notes |
+|---|---|---|---|
+| `title` | string |  |  |
+| `layout` | undefined (list\|cards) |  |  |
+| `items` | array |  |  |
+
+## `contact-form`
+
+A configurable contact form with typed fields (text, email, tel, textarea, select, checkbox) that posts to a host-provided runtime. No raw HTML.
+
+| field | type | required | notes |
+|---|---|---|---|
+| `title` | string |  |  |
+| `intro` | string |  |  |
+| `submitLabel` | string |  |  |
+| `successMessage` | string |  |  |
+| `fields` | array |  |  |
+
+## `newsletter`
+
+An email-capture form that posts to a host-provided runtime; renders inert until a runtime is wired.
+
+| field | type | required | notes |
+|---|---|---|---|
+| `title` | string |  |  |
+| `intro` | string |  |  |
+| `placeholder` | string |  |  |
+| `submitLabel` | string |  |  |
+| `successMessage` | string |  |  |
+
+## `auth`
+
+A provider-agnostic sign in / sign up panel: social provider buttons and an optional email form that start auth via a host runtime.
+
+| field | type | required | notes |
+|---|---|---|---|
+| `mode` | undefined (signin\|signup) |  |  |
+| `title` | string |  |  |
+| `providers` | array |  |  |
+| `showEmail` | boolean |  |  |
+
+## `cta`
+
+A full-width call-to-action band: a headline, optional subheading, and one button. Use near the bottom.
+
+| field | type | required | notes |
+|---|---|---|---|
+| `headline` | string | yes |  |
+| `subhead` | string |  |  |
+| `background` | undefined (primary\|accent\|surface) |  |  |
+| `button` | object |  |  |
+
+## `social-links`
+
+A centered row of links to social or external profiles, each an optional icon plus a label.
+
+| field | type | required | notes |
+|---|---|---|---|
+| `title` | string |  |  |
+| `links` | array |  |  |
+
+## `contact-details`
+
+A contact info block: address, phone, email, and opening hours (each optional). Read-only — no form.
+
+| field | type | required | notes |
+|---|---|---|---|
+| `title` | string |  |  |
+| `address` | string |  |  |
+| `phone` | string |  |  |
+| `email` | string |  |  |
+| `hours` | string |  |  |
+
+## `divider`
+
+A visual section break rendered as a thin line, a dotted rule, or a gradient bar.
+
+| field | type | required | notes |
+|---|---|---|---|
+| `style` | undefined (line\|dots\|gradient) |  |  |
+
+## `spacer`
+
+Deliberate vertical whitespace between sections, in one of four sizes (sm, md, lg, xl).
+
+| field | type | required | notes |
+|---|---|---|---|
+| `size` | undefined (sm\|md\|lg\|xl) |  |  |
+
+## `footer`
+
+Page footer: brand, tagline, a row of links, and a copyright line. Place last.
+
+| field | type | required | notes |
+|---|---|---|---|
+| `brand` | string |  |  |
+| `tagline` | string |  |  |
+| `links` | array |  |  |
+| `copyright` | string |  |  |
+

package/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+All notable changes to `@bytesbrains/weblocks` are documented here. The package
+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.2.0 — 2026-07-16
+
+Rich, app-like PWAs. Additive and **non-breaking**: every `0.1.0` manifest still
+validates and renders identically.
+
+### Added
+- **27 new blocks** (catalog now 37), all typed + totally-rendered:
+  - chrome / app-shell: `app-shell`, `sidebar`, `announcement-bar`, `hero-app`
+  - content: `about`, `rich-text`, `split`, `steps`, `stats`, `pricing`,
+    `logos`, `team`
+  - media: `carousel`, `video`, `map`
+  - structured: `timeline`, `tabs`, `accordion`
+  - collections: `blog-list`, `blog-post`, `feed`
+  - dynamic (powered): `contact-form`, `newsletter`, `auth`
+  - rhythm / links: `social-links`, `divider`, `spacer`
+  - `rich-text` / `blog-post` use **typed content nodes** (never raw HTML).
+- **Dynamic-block runtime contract** (`runtime.ts`): powered bricks declare
+  `runtime.capabilities`; hosts wire them via a `RuntimeAdapter`
+  (`NOOP_RUNTIME`, `pathRuntime`, `runtimeNeeds`). The engine bundles no backend.
+- **Array-item edit ops** (`addItem` / `updateItem` / `removeItem` / `moveItem`)
+  for surgical, single-item edits within a block's array field.
+- **Theming**: named `DesignTokens` presets (`presets.ts` — `applyPreset`,
+  `presetNames`, `getPreset`) and opt-in per-section `setOverrides` (palette
+  **plus** `radius` / `spacing`).
+- **Automatic light/dark**: `mode: 'auto'` now emits a
+  `@media (prefers-color-scheme: dark)` palette that follows the viewer's OS
+  theme; supply an optional `darkPalette` for the dark side (else a built-in
+  default). `mode: 'light' | 'dark'` render single-palette as before.
+- **Contrast-safe fills**: derived `--on-primary` / `--on-accent` tokens (via a
+  WCAG-luminance `readableOn`) replace hardcoded `#fff` button text, so contrast
+  holds on any palette. `readableOn` and `sectionOverrideCss` are exported.
+- **PWA layer** (`pwa.ts`): derive `manifest.webmanifest` + a service worker from
+  a `SiteManifest`; optional `pwa` / `seo` manifest fields; `renderSite` emits the
+  matching `<head>` tags when opted in.
+- `renderSite(manifest, { runtime })` to supply a host runtime.
+- `VISION.md`; `docs/ARCHITECTURE.md` rewritten to cover only the engine.
+
+## 0.1.0 — first shareable release
+
+First release packaged for reuse across repositories.
+
+- **Block engine**: compose a `SiteManifest` (design tokens + ordered typed
+  blocks) → validate (strict) → total-render → one self-contained static HTML
+  document. Rendering is a total function (never throws; unknown/invalid blocks
+  are skipped).
+- **10 blocks**: `nav`, `hero`, `features`, `services-catalogue`, `gallery`,
+  `testimonials`, `faq`, `cta`, `contact-details`, `footer`.
+- **AI contract**: `catalog()` / `catalogPrompt()` expose the block vocabulary as
+  JSON Schema (for function-calling) and a compact prompt menu. `generateSite()`
+  composes a manifest from a brief via an injected `ModelCall`; `editSite()`
+  applies JSON edit ops. Validity is independent of model quality.
+- **Design tokens**: a theme is a `DesignTokens` object (palette + scale/radius/
+  spacing/motion); every block styles itself from CSS variables, so one token
+  edit restyles the whole site.
+- **Shareable artifacts**: `catalog.json` (the machine-readable contract) and
+  `CATALOG.md` are generated on publish (`npm run emit:catalog`).

package/LICENSE

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