@getvitops/emdash 1.0.0-alpha.0 → 2.0.0-alpha.0

package/CHANGELOG.md

@@ -1,12 +1,288 @@
 # @getvitops/emdash
 
+## 2.0.0-alpha.0
+
+### Minor Changes
+
+- 161c7f3: A contact form that works end to end: `vitops setup turnstile`, `<wc-turnstile>`, the `vitops.form` EmDash block, and the route the emdash template ships to receive it.
+
+  **CSS, all formats** (no existing class changes): `forms.css` gains `.form-notice--target:not(:target)` (a message revealed only when the URL fragment names it, which is how a prerendered page shows a no-JS form's result) and `:where(wc-turnstile) { display: block }`.
+
+  **`@getvitops/core`:** new `<wc-turnstile sitekey="…">` in `elements.js`. It loads Cloudflare Turnstile on the first interaction with its form (no request to `challenges.cloudflare.com` for a visitor who only reads the page), holds an early submit until the token arrives, and leaves its slotted no-JS explanation in place until JS takes over. Turnstile is category `necessary`, so it is not behind the consent banner.
+
+  **`@getvitops/utils` / `@getvitops/cli`:** new `@getvitops/utils/turnstile` and `vitops setup turnstile [--dry] [--check] [--no-write] [--no-secret]`. It plans from the site's hostnames, creates a managed widget unless one already covers them (an existing widget is adopted, never edited, rotated or deleted), writes the public key to `site.security.turnstile.siteKey`, and pipes the one-time secret to `wrangler secret put VITOPS_TURNSTILE_SECRET` without writing it to any file. Needs `CLOUDFLARE_API_TOKEN` with **Account > Turnstile > Edit** and `CLOUDFLARE_ACCOUNT_ID`.
+
+  **`@getvitops/astro`:** `virtual:getvitops/head` gains `turnstileSiteKey` (read from `site.security.turnstile.siteKey`) so blocks can render the widget. No other change.
+
+  **`@getvitops/generator`:** `TIERS` gains a `turnstile` entry (wc-turnstile, claimed by `vitops.form`); `wc-multi-field`'s `emdashExempt` reason is reworded now the form block exists.
+
+  **`@getvitops/emdash`:** new `vitops.form` block: a field repeater (text, email, phone, long text, choose one, tick box), required flags, help text, success/error messages, optional Turnstile. It renders a semantic `<form method="post">` that works with no JavaScript, with a honeypot named per `createConversionRoute`'s defaults. A field named `phone` submits as `tel`, because the route reserves `phone` and `event`.
+
+  **`@getvitops/create`:** the emdash template ships `src/pages/api/track.ts` (`prerender = false`, `createConversionRoute()`), a seeded contact form, and `challenges.cloudflare.com` in both templates' Report-Only CSP (`script-src`, `frame-src`). The route refuses a post with nowhere to deliver and fails closed when a site key exists without `VITOPS_TURNSTILE_SECRET`. SETUP.html gains the Turnstile step. Existing sites: copy the route and the CSP change, then run `vitops setup turnstile`.
+
+- 1e36b83: Seven new blocks, a section block type, and a shared `tone`.
+
+  **New Portable Text blocks:** `vitops.logos` (a still grid; `marquee` only scrolls), `vitops.steps`, `vitops.stats` (each figure is a `<Counter>`; a `tiles` style adds group, change and good/bad state), `vitops.callout` (a call-to-action band, not the dismissible `banner`), `vitops.entries` (wraps `<wc-entries>`), `vitops.pricing` (aligned plan cards) and `vitops.embed` (a video or map that loads only after consent: the iframe ships with no `src`, the address rides on `data-consent-src`, and a `title` is required).
+
+  **New block TYPE `vitops_section`** (kicker, heading with a level, lead-in, tone, an optional heading-left `split` layout, and a Portable Text body that accepts every `vitops.*` block). It is a schema-level block type, not a Portable Text block, because Block Kit fields cannot hold rich text. Add `...vitopsBlockTypes()` to `seed.json`'s `blockTypes`, allow `vitops_section` on the collection's `blocks` field, and map it with `blockTypeComponents` from `@getvitops/emdash/astro` (`defineBlockComponents`).
+
+  **Extended, non-breaking:** `vitops.hero` gains accent marks (`*words*` in the heading), a heading `level`, `tone`/`color` and an optional row of cards. `vitops.cards` gains a `panel` style (tone, checklist, button), a heading `level`, `tone`/`color`, and `[text](/url)` inline links in the body. **Cards fix:** the card title is now a real heading element (default `h3`, `font-heading`) instead of `<p class="font-heading">`; saved content is unchanged, but the markup and the page outline change. Set `level` to taste.
+
+  **Shared `tone` + `color`** on every block that colours anything: a role from `site.json`, falling back through its semantic relatives to `neutral`, or a palette hue/step. Renderers emit `--tone-*` custom properties (never a class built from a value, which Tailwind cannot see). New option `vitopsEmdash({ tones })` (or the roles are read from `designSystemEditor.config`) fills each block's `tone` select with the site's own roles through a `tones/list` plugin route; with neither, the select offers the semantic names. `vitops.banner.tone` and `vitops.actionLink.role` keep their existing values.
+
+  **Render tests:** `pnpm --filter @getvitops/emdash run test:render` renders the block adapters through Astro's container API in a separate vitest config.
+
+- 175d16e: **Added: `vitops.reviews` and `vitops.nav` EmDash blocks.** Non-breaking.
+
+  - **`vitops.reviews`** renders Google reviews from the committed `.vitops/reviews.json` cache (`vitops reviews`) as a grid, carousel or marquee of `<ReviewCard>`. Fields: location key, layout, columns, limit, lowest rating, order, featured ids, reviewer photos (off by default), tone/colour. Which reviews show is `selectReviews()`, the one shared decision. Review JSON-LD is not offered (Google treats self-marked-up reviews as ineligible for rich results). A new review reaches the page after `vitops reviews` is re-run, committed and the site rebuilt, not when an editor saves; with no cache file the block renders nothing (a note in `astro dev`).
+  - **`vitops.nav`** renders a named EmDash menu inside page content (site map, section links, footer-style columns), never the header. Fields: menu (picked from the site's menus via a new `menus/list` plugin route, with `footer-sitemap`/`footer-legal`/`primary` as the static fallback), accessible name, visible heading and level, layout `list | inline | columns | sitenav`, depth 1-3, tone/colour. It is a `<nav>` with a name that is never `Primary`, `Site map` or `Legal` (the layout's landmarks), `aria-current="page"`, no runtime JS; a missing or empty menu renders nothing.
+  - `@getvitops/astro`: **`virtual:getvitops/reviews`**, served by `vitops()`, is `.vitops/reviews.json` as a build-time import (an empty cache when absent or unreadable), because a Worker cannot read the file. `<ReviewCard>` now renders the review's source link (`.review__source`, `rel="nofollow noopener noreferrer"`), which the pattern already styled. **Fix:** `src/json-ld.ts` was missing from the published `files`, so any consumer importing `<ReviewCard>` (which composes `schemas/Review.astro`) failed to build with an unresolved import. `@getvitops/emdash` now needs this version of `@getvitops/astro` for the `vitops.reviews` block.
+  - `@getvitops/utils`: new Worker-safe subpath **`@getvitops/utils/reviews/select`** (`selectReviews` and the review types, no `node:fs`). `selectReviews` now takes only the display fields (`featured`, `minRating`, `limit`, `sort`), so a caller with no configured `locationId` can use it; existing calls are unchanged.
+  - `@getvitops/core`: new `.navlist` pattern in `patterns/sitenav.css` (`.navlist`, `__item`, `__link`, `__label`, `__sub`, `--inline`, `--columns`). **All formats** (css, bricks, tailwind). No existing class changes.
+  - `@getvitops/generator`: `TIERS.review` lists `vitops.reviews` and `TIERS.sitenav` lists `vitops.nav` (and `.navlist`), so `vitops docs components` and the docsite show them.
+
+- 06d6112: Fix the EmDash `/design-system` admin page erroring on a tailwind site. It fetches `/vitops/design-manifest.json`, which the `tailwind` format never emitted and the integration only mirrored under `editor: true` (which also loads `editor.js` on every public page).
+
+  - **generator** (`tailwind` format only): `design-manifest.json` is now emitted alongside `tailwind.css`. No change to the CSS.
+  - **astro**: new `vitops({ editorManifest: true })` writes everything an outside host needs into `public/vitops/` (`design-manifest.json`, `editor.js`, a standalone `editor.css`, and `design-system-editor.html`) without loading the editor on public pages. `editor: true` still loads it from `<Head />`.
+  - **vite**: `editorManifestDir` also writes `vitops/editor.css`, from a throwaway `css`-format pass on tailwind sites.
+  - **emdash**: the `/design-system` admin page was unstyled and overflowed the admin, because the editor borrows the framework CSS and the admin never loads it. It now embeds `/vitops/design-system-editor.html` in an iframe, so the design system can't leak into the admin's styles. **Requires `editorManifest: true`** in `vitops({ … })`.
+  - **create**: the EmDash template sets `editorManifest: true`. Existing sites: add it to `vitops({ … })` in `astro.config.mjs`.
+
+  No consumer-facing change in the other toolchain packages.
+
+### Patch Changes
+
+- Updated dependencies [efd4e72]
+- Updated dependencies [93d2067]
+- Updated dependencies [161c7f3]
+- Updated dependencies [175d16e]
+- Updated dependencies [83d6f3c]
+- Updated dependencies [892b204]
+- Updated dependencies [06d6112]
+- Updated dependencies [6297337]
+- Updated dependencies [224a731]
+- Updated dependencies [55061e2]
+- Updated dependencies [b47df4d]
+  - @getvitops/astro@8.3.0-alpha.0
+  - @getvitops/core@8.3.0-alpha.0
+  - @getvitops/generator@8.3.0-alpha.0
+  - @getvitops/utils@8.3.0-alpha.0
+
+## 1.0.0
+
+### Major Changes
+
+- c3c1bcb: **New: the design-system editor, mounted inside the EmDash admin.** `vitopsEmdash({
+  designSystemEditor: { config } })` (`config` is your `site.json`, e.g. `import config from
+  './site.json' with { type: 'json' }`) adds a `/design-system` admin page mounting
+  `<wc-theme-editor>` — the same live token editor `@getvitops/vite`'s dev server has always
+  offered, now usable by the client directly, no dev server required. An edit is visible
+  site-wide immediately (a runtime `:root` override, served via a new plugin API route and
+  `page:fragments`) and — once `site.deployment.repo`/`branch` and a `VITOPS_GITHUB_TOKEN`
+  secret are set (see the scaffold's `SETUP.html`) — auto-commits to your `dev` branch, so it
+  reaches the git-tracked `site.json` through your repo's normal review path rather than
+  becoming a second, unreviewed source of truth. Until that's configured, the live half still
+  works; only the auto-commit half is skipped (and says so in the admin page). The save route
+  runs the exact same accessibility (APCA contrast) gate `generate()` enforces at build time,
+  synchronously, before persisting — nothing non-compliant ever goes live even momentarily.
+
+  Requires `@astrojs/react` + `react` + `react-dom` (already scaffold dependencies, for
+  EmDash's own admin) and `@getvitops/core` (added as a new scaffold dependency this release).
+  Declares two new plugin capabilities when enabled: `network:request` (for the GitHub
+  auto-commit) and `hooks.page-fragments:register` (for the live override) — reviewed once at
+  plugin-install time.
+
+  **Breaking for `@getvitops/emdash`**: `vitopsEmdash()`'s `hooks.page-fragments:register`
+  capability is now also granted whenever `designSystemEditor` is set, independent of the
+  existing `scripts: 'fragments'` option (which governs something unrelated — web-component
+  script delivery). No change if you don't use `designSystemEditor`.
+
+  Also new, supporting the above:
+
+  - `@getvitops/generator`: `validateColorContract()` and `buildReverseIndex()` (both
+    `/tokens` subpath, Worker-safe) — the monotonicity/contrast gate and the
+    `design-manifest.json` reverse-index, each extracted from `generate()`'s `build()` into
+    standalone, non-throwing functions. `patchToOverrideCss()` turns a design-system patch
+    into the `:root` override `<style>` block. `designSystemPath`/`getAt`/`setAt`/
+    `mergePatch`/`formatConfig` moved from `@getvitops/vite` into `@getvitops/generator/config`
+    (re-exported from `@getvitops/vite` unchanged) — one "patch a config file's design-system
+    subtree" implementation shared by the dev endpoint and the new plugin route. New
+    `site.deployment.repo`/`branch` config fields.
+  - `@getvitops/utils`: new `/git` subpath — `commitFile()`, a Worker-safe (fetch-only)
+    wrapper over GitHub's Contents API.
+  - `@getvitops/core`: `<wc-theme-editor>` gains a `save-endpoint` attribute (default
+    unchanged — `/__vitops/design-system`) so the same element can target the new plugin
+    route instead of the dev-only Vite endpoint.
+
+- 0574388: Bump `emdash`/`@emdash-cms/cloudflare` peers to `>=1.0.0 <2` and `vite-plus` to `^1.0.0`, following
+  both projects' GA releases.
+
+  **Breaking for `@getvitops/emdash` consumers on EmDash 0.x**: the peer range no longer admits
+  `emdash@0.31.x`/`@emdash-cms/cloudflare@0.31.x`. Upgrade `emdash` and `@emdash-cms/cloudflare` to
+  `^1.0.1` first — nothing in `@getvitops/emdash`'s own plugin surface (`admin.portableTextBlocks`,
+  the `hooks.page-fragments:register` capability, `definePlugin()`) changed against EmDash 1.0, so no
+  code here needed to change, only the declared range.
+
+  The `emdash` scaffold template (`vp create @getvitops:emdash`) picks up several fixes alongside
+  the version bump:
+
+  - `tailwindcss`/`@tailwindcss/vite` are now real dependencies — the template selected
+    `css.format: 'tailwind'` without installing either, which threw on build.
+  - `site.json` now sets `site.icons.sprite: true` plus the full `semantic` list the
+    `vitops.actionLink` block's icon picker offers — previously its sprite icons pointed at a file
+    the build never generated.
+  - `astro.config.mjs` sets `migrations: { runtime: 'check', dev: 'auto' }`, and
+    `site-deploy-emdash.yml` runs EmDash 1.0's documented `build → status → apply → deploy → check`
+    migration sequence explicitly, rather than relying solely on first-request auto-migration. This
+    needs a new GitHub Environment variable, `EMDASH_TARGET_FINGERPRINT` (one per environment),
+    which only a human can set — run `emdash migrate --status` against the real deployed database,
+    review the printed identity, then `gh variable set EMDASH_TARGET_FINGERPRINT --env <env> --body
+    <value>`. Deploys fail clearly on the migration-apply step until it's set.
+  - `lint.options.typeAware`/`typeCheck` in the template's own `vite.config.ts` are commented out,
+    not deleted: vite-plus 1.0 only honours that option in a project's actual root config, and hard
+    errors on it in a nested one (which this file is, sitting inside the `design-system` monorepo).
+    Uncomment it once scaffolded into its own repo.
+
+  No config schema changes. `@getvitops/generator` also switches from the `zod/mini` subpath import
+  to the standalone `@zod/mini` package (zod 4.5+; same API) and fixes `validateConfig()` silently
+  losing the offending key name on an `unrecognized_keys` error (e.g. a typo'd `site.ads` platform
+  now names the bad key instead of reporting a bare "Invalid input").
+
+  Also fixed: `vp check`'s `tsconfig-error` for `packages/create/templates/emdash/tsconfig.json`
+  (`extends: "astro/tsconfigs/strict"`, unresolvable from inside this monorepo since the template
+  has no `node_modules` of its own — a pre-existing, structural gap, newly surfaced as a hard error
+  by oxlint 1.85's deeper config discovery, and blocking on every commit since this repo's pre-commit
+  hook runs `vp check --fix`). Fixed with a new `scripts/link-template-deps.mjs`, wired as the root
+  `postinstall` script: symlinks `astro`/`emdash`/`@emdash-cms/cloudflare` into the template's own
+  `node_modules/` (resolved fresh from sibling packages that already depend on them for real, not a
+  hardcoded `.pnpm` hash) and writes a minimal `astro:content` ambient shim at `.astro/types.d.ts`
+  (the same path `astro sync` would generate for real). Both are gitignored and only ever exist
+  inside this monorepo's copy of the template — a real scaffold installs its own real copies instead.
+  Considered and rejected first: inlining astro's strict preset (drift risk against astro's own
+  evolving default) and making the template a real pnpm workspace member (would change how its
+  `@getvitops/*: "latest"` deps resolve locally, which `templates.test.ts` exists to protect).
+
+  **Known gap, not fixed here**: `packages/astro/src/components/container.test.ts` (the
+  `AstroContainer`-based render tests) fails to even load under vite-plus 1.0's Vite 8 — direct
+  `.astro` imports in a Vitest file need the Astro Vite plugin registered, which nothing in this
+  repo's test config actually does (Astro's own docs call for `getViteConfig()`, which doesn't
+  compose with vite-plus's own `defineConfig`). A type-level shim
+  (`packages/astro/src/components/astro-modules.d.ts`) fixes `vp check`'s type-aware pass, but the
+  runtime `vp test` failure for this one file is still open.
+
+### Minor Changes
+
+- b3d9c07: `vitops docs blocks` prints every EmDash block type and its fields, so an agent can write valid Portable Text without reading the plugin source. It reads `@getvitops/emdash` from the project (and says so if it isn't installed); `@getvitops/emdash` exports `renderBlocksDoc()` for it.
+- 2ef2d41: **Tested against EmDash 1.4.** `emdash` and `@emdash-cms/cloudflare` are now `^1.4.0` in the
+  `emdash` template, and `@getvitops/emdash`'s peer ranges for both moved from `>=1.0.0 <2` to
+  `>=1.3.0 <2` — **breaking for a site still on EmDash 1.0–1.2**: upgrade `emdash` and
+  `@emdash-cms/cloudflare` together (EmDash warns at build when the two differ) before upgrading
+  this package. 1.4 fixes a stored XSS in the visual-editing toolbar (an author's published content
+  could run script for a signed-in editor), so an existing client site should take it promptly.
+
+  - **`vitopsHosting()` coalesces D1 reads by default** — new `cloudflare.coalesce` option
+    (default `true`, passed to `d1({ coalesce })`). With `session: 'auto'`, EmDash 1.3 stops
+    preloading settings/menus/widgets for logged-out visitors unless reads are coalesced, so this
+    restores one round trip instead of several. It is experimental upstream: a read and a write
+    started together may run write-first, so `await` a read before a write that must not affect it.
+    Set `coalesce: false` to opt out. No effect without a session.
+  - **Template:** `AGENTS.md` gains an "EmDash 1.x behaviours" section (passkeys are bound to a
+    hostname so use _Change domain_ at cutover; admin-authored HTML blocks run JS and conflict with
+    Astro CSP; link by `entry.data.slug`, not `entry.id`; submit `/sitemap.xml`; clearing a stuck D1
+    lock with `emdash migrate --take-over-lock`).
+  - **Upstream behaviour changes to know about (no code change here):** `cacheHint.lastModified` is
+    no longer auto-populated and pages lose the implicit `Cache-Control: no-cache`; collection
+    sitemaps paginate at 2,000 entries; `entry.id` is always locale-prefixed on multilingual sites.
+
+  No consumer-facing change in `@getvitops/core`, `@getvitops/generator`, `@getvitops/utils`,
+  `@getvitops/cli` or `@getvitops/vite`. `@getvitops/astro` has one — see the scaffold changeset.
+
+- 1a8231d: **EmDash blocks are now a tier of the component manifest, and there are four more of them.**
+
+  `@getvitops/emdash` adds `vitops.gallery`, `vitops.cards`, `vitops.accordion` and `vitops.marquee`
+  (each a thin adapter over the matching `@getvitops/astro` component), and `vitops.carousel` now edits
+  its slides as a **Slides repeater** instead of two newline-separated fields. Blocks saved before this
+  keep rendering: with no `slides`, the carousel still reads `images`/`alts`, and both legacy fields stay
+  in the editor, labelled as legacy. The editor's field type now admits `repeater` and `media_picker`.
+
+  - **New `blocks` plugin option** — `vitopsEmdash({ blocks: { include, exclude, extra } })`. `include` is
+    an allowlist, `exclude` drops blocks, `extra` adds the site's own **editor** definitions (the site
+    supplies their renderers via `<PortableText components={{ type }}>`, the same route that overrides a
+    `vitops.*` renderer). An unknown name or a colliding `type` throws at plugin construction.
+  - Link and image URLs in blocks with a scheme other than `http`, `https`, `mailto` or `tel` are
+    dropped (see the security entry).
+
+  `@getvitops/generator`: `TierEntry` gains an optional `emdash: string[]` (block `_type`s) and `Tier`
+  gains `'emdash'`, so `tierPatterns('emdash')` projects it. **Breaking only for code that exhaustively
+  switches on `Tier` or builds a `Record<Tier, …>`** — add an `emdash` case. The agent doc
+  `vitops docs components` gains an "EmDash blocks" table and the docsite a `components/emdash` page. The
+  guard that every block and every `emdash` entry agree lives in `@getvitops/emdash`'s `blocks.test.ts`,
+  because the generator cannot import the plugin.
+
+  `@getvitops/create`: the EmDash template's agent guidance explains the blocks, their limits (a block
+  cannot contain blocks; `vitops.*` blocks do not render inside EmDash's built-in `columns`) and the
+  `blocks` option.
+
+  Formats reached: none — no CSS change. Other packages in the `fixed` group: No consumer-facing change
+  in this package.
+
+- 779d22e: Add a `vitops.hero` EmDash block (eyebrow, heading, text, two links, optional image; centered or split layout) built on the `.centered`/`.split` layout primitives. The EmDash template's home page now seeds one of each of hero, cards, accordion and marquee. `@getvitops/generator`: the `split` pattern lists the new block in `TIERS`.
+
+### Patch Changes
+
+- 734ab60: EmDash gallery and carousel blocks now derive their element id from the block's `_key`, so two blocks with the same label on one page no longer open each other's dialog. `<wc-entries>` column navigation now honours `prefers-reduced-motion`.
+- 7f4f50e: `@getvitops/utils/url` exports `safeHref()` (a Worker-safe scheme allowlist: http, https, mailto, tel and relative), shared by the EmDash blocks and the Astro components. It now also guards the EmDash image-compare block, the review avatar and the cookie-notice policy link. `nodesToHtml`/`toHtml` throw on invalid tag or attribute names and on `on*` event-handler attributes, and drop `href`/`src`-style values that fail `safeHref`. EmDash cards link text now names the card for screen readers.
+- e5bc937: **Security: JSON-LD can no longer break out of its `<script>` tag.** All 24 `schemas/*.astro`
+  components inlined `JSON.stringify(jsonLd)` as-is, so a review, FAQ answer or forum post containing
+  `</script><script>…` ran as script on the page. They now go through `jsonLdScript()`, which escapes
+  `<`, `>`, `&`, U+2028 and U+2029 (still valid JSON — consumers and search engines parse the same
+  document). Sites rendering any user-supplied text through a schema component should upgrade promptly.
+
+  **`createConversionRoute()` hardening** — behaviour changes:
+
+  - The body-size cap is now enforced on the stream itself, not only on `Content-Length`; a chunked
+    request with no header is refused with 413 once it passes `maxBodyBytes`.
+  - **Breaking for non-Cloudflare hosts:** `X-Forwarded-For` is no longer used as the rate-limit key by
+    default, since off Cloudflare a client can set it freely and mint a new bucket per request. Pass
+    `trustForwardedFor: true` when running behind a proxy that overwrites it. Without
+    `CF-Connecting-IP` or that opt-in there is no IP and rate limiting is skipped. No change on
+    Cloudflare Workers.
+
+  `@getvitops/emdash`: the link/button block (`vitops.actionLink`) drops hrefs with a scheme other
+  than `http`, `https`, `mailto` or `tel` (e.g. `javascript:`, `data:`) and renders nothing for them.
+
+  Formats reached: none — no CSS change. Other packages in the `fixed` group: No consumer-facing
+  change in this package.
+
+- Updated dependencies [65a13cc]
+- Updated dependencies [67e2088]
+- Updated dependencies [89265af]
+- Updated dependencies [0574388]
+- Updated dependencies [c3c1bcb]
+- Updated dependencies [0574388]
+- Updated dependencies [1a8231d]
+- Updated dependencies [779d22e]
+- Updated dependencies [0574388]
+- Updated dependencies [8d8aad7]
+- Updated dependencies [0574388]
+- Updated dependencies [1a3e811]
+- Updated dependencies [0574388]
+- Updated dependencies [dde3df3]
+- Updated dependencies [d9f213b]
+- Updated dependencies [7f4f50e]
+- Updated dependencies [7fd5f8f]
+- Updated dependencies [ceb8310]
+  - @getvitops/generator@8.2.0
+  - @getvitops/utils@8.2.0
+
 ## 1.0.0-alpha.0
 
 ### Major Changes
 
 - c3c1bcb: **New: the design-system editor, mounted inside the EmDash admin.** `vitopsEmdash({
-designSystemEditor: { config } })` (`config` is your `site.json`, e.g. `import config from
-'./site.json' with { type: 'json' }`) adds a `/design-system` admin page mounting
+  designSystemEditor: { config } })` (`config` is your `site.json`, e.g. `import config from
+  './site.json' with { type: 'json' }`) adds a `/design-system` admin page mounting
   `<wc-theme-editor>` — the same live token editor `@getvitops/vite`'s dev server has always
   offered, now usable by the client directly, no dev server required. An edit is visible
   site-wide immediately (a runtime `:root` override, served via a new plugin API route and
@@ -67,7 +343,7 @@ designSystemEditor: { config } })` (`config` is your `site.json`, e.g. `import c
     needs a new GitHub Environment variable, `EMDASH_TARGET_FINGERPRINT` (one per environment),
     which only a human can set — run `emdash migrate --status` against the real deployed database,
     review the printed identity, then `gh variable set EMDASH_TARGET_FINGERPRINT --env <env> --body
-<value>`. Deploys fail clearly on the migration-apply step until it's set.
+    <value>`. Deploys fail clearly on the migration-apply step until it's set.
   - `lint.options.typeAware`/`typeCheck` in the template's own `vite.config.ts` are commented out,
     not deleted: vite-plus 1.0 only honours that option in a project's actual root config, and hard
     errors on it in a nested one (which this file is, sitting inside the `design-system` monorepo).

package/README.md

@@ -36,7 +36,7 @@ export default defineConfig({
 });
 ```
 
-Tested against `emdash@1.0.x`.
+Tested against `emdash@1.4.x`.
 
 ## Rendering mode
 
@@ -125,19 +125,60 @@ export default defineConfig({
   in the database (D1 export / EmDash seed round-trip), media in the storage
   backend (bucket/directory copy). Both directions work.
 
-## Editor blocks (v1)
-
-| Slash-menu entry | `_type`               | Renders                                         |
-| ---------------- | --------------------- | ----------------------------------------------- |
-| Link or button   | `vitops.actionLink`   | sprite-icon `<a>`, styled `.link`/`.btn`/`.cta` |
-| Image compare    | `vitops.imageCompare` | `<wc-image-compare>` before/after slider        |
-| Copy snippet     | `vitops.copyButton`   | `<wc-copy>` with code/inline fallback           |
-| Banner           | `vitops.banner`       | `<wc-dismissable>` banner with tone colours     |
-| Disclosure       | `vitops.details`      | native `<details>`/`<summary>`                  |
-| Carousel         | `vitops.carousel`     | `@getvitops/astro`'s `<Carousel />`             |
+## Editor blocks
+
+| Slash-menu entry | `_type`               | Renders                                                    |
+| ---------------- | --------------------- | ---------------------------------------------------------- |
+| Link or button   | `vitops.actionLink`   | sprite-icon `<a>`, styled `.link`/`.btn`/`.cta`            |
+| Image compare    | `vitops.imageCompare` | `<wc-image-compare>` before/after slider                   |
+| Copy snippet     | `vitops.copyButton`   | `<wc-copy>` with code/inline fallback                      |
+| Banner           | `vitops.banner`       | `<wc-dismissable>` banner with tone colours                |
+| Disclosure       | `vitops.details`      | native `<details>`/`<summary>`                             |
+| Accordion        | `vitops.accordion`    | a group of `<details>`; optionally one-open-at-a-time      |
+| Carousel         | `vitops.carousel`     | `@getvitops/astro`'s `<Carousel />` over a Slides repeater |
+| Gallery          | `vitops.gallery`      | `<Gallery />` — thumbnail grid opening a lightbox carousel |
+| Cards            | `vitops.cards`        | `<Cards />` — a grid of `.card`s, whole-card click with JS |
+| Marquee          | `vitops.marquee`      | `<Marquee />` — a continuously scrolling row               |
 
 All blocks render accessible markup that works without JavaScript; the
-web components progressively enhance it.
+web components progressively enhance it. Each is a thin adapter over the matching
+`@getvitops/astro` component, so the markup exists once. `@getvitops/generator`'s `TIERS`
+manifest lists which block renders which pattern (its `emdash` key, the `vitops docs components`
+"EmDash blocks" table), and `blocks.test.ts` fails if a block and the manifest disagree.
+
+Repeating data (cards, gallery images, accordion items, marquee items, carousel slides) is a
+**repeater** field; images can be a media-library URL or any `http(s)`/relative URL. Link and image
+URLs with any other scheme (`javascript:`, `data:`) are dropped at render time.
+
+### Choosing and extending the blocks
+
+```js
+vitopsEmdash({
+  blocks: {
+    exclude: ['vitops.marquee'], // or `include: [...]` as an allowlist
+    extra: [
+      {
+        type: 'acme.pricing',
+        label: 'Pricing table',
+        fields: [/* Block Kit */],
+      },
+    ],
+  },
+});
+```
+
+`extra` adds **editor** definitions only. This plugin cannot render a block it has never heard of,
+so the site maps each of its own types to a component, and can replace a `vitops.*` renderer the same way:
+
+```astro
+<PortableText
+  value={page.data.content}
+  components={{ type: { 'acme.pricing': PricingTable, 'vitops.cards': MyCards } }}
+/>
+```
+
+EmDash merges renderers as built-ins, then plugin `blockComponents`, then this `components` prop, so
+the site's entry wins.
 
 ## Script delivery
 
@@ -154,17 +195,21 @@ loaded on pages that render these blocks. Pick **one**:
 Enabling both would load the scripts twice (harmless — element registration is
 guarded — but wasteful).
 
-## Repeating structured patterns
+## Patterns that contain other blocks
+
+A Portable Text block cannot hold other blocks — a repeater's rows are scalar fields. So a section
+with columns, a hero, or a card holding a button is not a `vitops.*` block. Two routes:
+
+- A **`blocks` field** (EmDash's typed page-composition field): define block types such as `hero` or
+  `split` in the seed, and map each to an Astro component built from `@getvitops/astro`
+  (`Subgrid`, `Cards`, the `.split` classes) with `defineBlockComponents`.
+- **Sections** (`/section`): compose the pattern once as reusable content and let editors insert copies.
 
-EmDash's Portable Text block fields are flat, so patterns with repeating data
-(card grids, FAQ lists, spec tables via `wc-entries`, forms) are deliberately
-**not** v1 blocks. Use instead:
+EmDash's built-in `columns` block renders its children with marks only, so a `vitops.*` block placed
+inside one does not render. Use a `blocks` field for layout instead.
 
-- **Sections** (`/section`): compose the pattern once as reusable content and
-  let editors insert copies.
-- **Field Kit `list` widgets** on `json` collection fields: model the repeating
-  rows in the collection schema and render them at the template level with
-  `Cards.astro` / `NodeRenderer.astro` from `@getvitops/astro`.
+Not yet blocks: tree, entries, reviews (`ReviewCard` reads `.vitops/reviews.json`, which needs a
+build-time import rather than a filesystem read on a Worker), dialog and tabs (no component yet).
 
 ## Changelog
 

package/dist/index.d.mts

@@ -1,6 +1,34 @@
-import { PluginDescriptor, PortableTextBlockConfig } from "emdash";
+import { ApplySeedBlockTypeInput, PluginDescriptor, PortableTextBlockConfig } from "emdash";
 import { AstroIntegration } from "astro";
-//#region src/design-system-route.d.ts
+/** The subset of EmDash Block Kit field elements these blocks use. */
+type BlockKitFieldDef = Extract<NonNullable<PortableTextBlockConfig['fields']>[number], {
+  type: 'text_input' | 'number_input' | 'select' | 'toggle' | 'combobox' | 'repeater' | 'media_picker';
+}>;
+type PortableTextBlockDef = Omit<PortableTextBlockConfig, 'fields'> & {
+  fields?: BlockKitFieldDef[];
+};
+export declare const BLOCKS: PortableTextBlockDef[];
+/** Which Vitops blocks a site's editor offers, and any it adds of its own. */
+interface BlockSelection {
+  /** Offer only these `vitops.*` types. Unknown names throw — a typo must not silently offer nothing. */
+  include?: string[];
+  /** Drop these `vitops.*` types. Applied after `include`. */
+  exclude?: string[];
+  /**
+   * The site's own blocks. These are EDITOR definitions only: the plugin cannot render a
+   * block it has never heard of, so the site maps each `type` to a component with
+   * `<PortableText components={{ type: { … } }} />`. A type that collides with an existing
+   * one throws, since the later definition would silently replace the earlier one's fields.
+   */
+  extra?: PortableTextBlockDef[];
+}
+/**
+ * Resolve {@link BlockSelection} against {@link BLOCKS}.
+ *
+ * Pure so a misconfiguration fails at plugin construction, with the offending name in the
+ * message, rather than as an editor menu that is quietly missing something.
+ */
+export declare function selectBlocks(selection?: BlockSelection): PortableTextBlockDef[];
 interface DesignSystemEditorOptions {
   /**
    * The site's own config, typically `import config from '../../site.json'
@@ -13,18 +41,37 @@ interface DesignSystemEditorOptions {
   /** Which `designSystem.themes` entry this edits. Default: `'default'`. */
   theme?: string;
 }
-//#endregion
-//#region src/blocks.d.ts
-/** The v1 subset of EmDash Block Kit field elements used by these blocks. */
-type BlockKitFieldDef = Extract<NonNullable<PortableTextBlockConfig['fields']>[number], {
-  type: 'text_input' | 'number_input' | 'select' | 'toggle' | 'combobox';
-}>;
-type PortableTextBlockDef = Omit<PortableTextBlockConfig, 'fields'> & {
-  fields?: BlockKitFieldDef[];
-};
-export declare const BLOCKS: PortableTextBlockDef[];
-//#endregion
-//#region src/hosting.d.ts
+/**
+ * The block reference an agent reads via `vitops docs blocks`: every Portable Text `_type`,
+ * its fields and what each saves. Rendered from the same `BLOCKS` the editor menu uses, so
+ * it cannot describe a field the editor doesn't offer.
+ */
+export declare function renderBlocksDoc(blocks?: readonly PortableTextBlockDef[]): string;
+/** Block-type slugs may not contain a dot, so `vitops.section` is stored as `vitops_section`. */
+export declare const SECTION_SLUG = "vitops_section";
+/** `vitops.section`: kicker, heading, lead-in, tone/backdrop, optional heading-left layout, and a body of blocks. */
+export declare const SECTION_BLOCK_TYPE: ApplySeedBlockTypeInput;
+/**
+ * Every block type this plugin ships, in the shape `seed.json`'s `blockTypes` takes. Spread
+ * it into the seed (and allow the slugs on the collection's `blocks` field), e.g.
+ * `blockTypes: [...vitopsBlockTypes()]`.
+ */
+export declare function vitopsBlockTypes(): ApplySeedBlockTypeInput[];
+/** The role chain for a tone: itself, its relatives, then `neutral`. Pure and exported for tests. */
+export declare function toneChain(tone: unknown): string[];
+interface ResolvedTone {
+  /** Always `tone`; a block adds `tone--solid` itself when it fills rather than tints. */
+  className: string;
+  /** Inline `style` value of `--tone-*` properties (no trailing semicolon). Empty when unset. */
+  style: string;
+}
+/**
+ * Resolve a block's `tone` / `color` fields.
+ *
+ * Returns an empty style when neither is set, so an unconfigured block carries no tone at
+ * all (rather than a neutral one) and stays transparent.
+ */
+export declare function resolveTone(tone?: unknown, color?: unknown): ResolvedTone;
 type HostingTarget = 'cloudflare' | 'node';
 interface VitopsHostingOptions {
   /** Hosting target. Overridden by the `HOSTING` env var. Default 'cloudflare'. */
@@ -36,6 +83,13 @@ interface VitopsHostingOptions {
     mediaBinding?: string;
     /** D1 Sessions API read-replication mode (default 'auto'). */
     session?: string;
+    /**
+     * Batch reads issued together into one D1 round trip (default true).
+     * Experimental in emdash: a read and a write started together may run
+     * write-first, so await a read before a write that must not affect it.
+     * No effect without a session.
+     */
+    coalesce?: boolean;
   };
   node?: {
     /** SQLite URL (default `DATABASE_PATH` env or 'file:./data/emdash.db'). */
@@ -57,8 +111,6 @@ interface VitopsHosting {
   storage: unknown;
 }
 export declare function vitopsHosting(options?: VitopsHostingOptions): Promise<VitopsHosting>;
-//#endregion
-//#region src/index.d.ts
 export interface VitopsEmdashOptions {
   /**
    * How the web-component runtime scripts reach the page:
@@ -82,6 +134,19 @@ export interface VitopsEmdashOptions {
    * reviewed once at plugin-install time, same as any other capability.
    */
   designSystemEditor?: DesignSystemEditorOptions | false;
+  /**
+   * Which blocks the editor offers. All of the `vitops.*` blocks by default. Use `exclude` to
+   * drop one a client should not see, `include` for an allowlist, and `extra` to add the
+   * site's own — whose renderers the site supplies, see {@link BlockSelection}.
+   */
+  blocks?: BlockSelection;
+  /**
+   * The site's colour role names (`Object.keys(site.designSystem.colors.roles)`), offered in
+   * every block's `tone` select next to the semantic names. When omitted and
+   * `designSystemEditor.config` is set, they are read from that config. With neither, the
+   * select offers only the semantic names — an editor can still type a palette colour.
+   */
+  tones?: string[];
 }
 /**
  * Descriptor factory — import in `astro.config.mjs` and pass to the emdash()
@@ -90,6 +155,5 @@ export interface VitopsEmdashOptions {
 export declare function vitopsEmdash(options?: VitopsEmdashOptions): PluginDescriptor;
 /** Runtime side — EmDash imports and calls this from the descriptor's entrypoint. */
 export declare function createPlugin(options?: VitopsEmdashOptions): import("emdash").ResolvedPlugin<import("emdash").PluginStorageConfig>;
-//#endregion
-export { type BlockKitFieldDef, type DesignSystemEditorOptions, type HostingTarget, type PortableTextBlockDef, type VitopsHosting, type VitopsHostingOptions, createPlugin as default };
+export { type BlockKitFieldDef, type BlockSelection, type DesignSystemEditorOptions, type HostingTarget, type PortableTextBlockDef, type VitopsHosting, type VitopsHostingOptions, createPlugin as default };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/design-system-route.ts","../src/blocks.ts","../src/hosting.ts","../src/index.ts"],"mappings":";;;UAuDiB;;;;;;;;EAQf;;EAEA;;;;;KCjDU,mBAAmB,QAC7B,YAAY;EACV;;KAGQ,uBAAuB,KAAK;EACtC,SAAS;;qBAGE,QAAQ;;;KCOT;UAIK;;EAEf,SAAS;EACT;;IAEE;;IAEA;;IAEA;;EAEF;;IAEE;;IAEA;;IAEA;;IAEA;;;UAIa;EACf,QAAQ;EACR,SAAS;;EAET;;EAEA;;wBAoBoB,cAAc,UAAS,uBAA4B,QAAQ;;;iBCxBhE;;;;;;;;;;;EAWf;;EAEA;;;;;;;;;EASA,qBAAqB;;;;;;wBAOP,aAAa,UAAS,sBAA2B;;wBAmBjD,aAAa,UAAS,uCAAwB,gCAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/blocks.ts","../src/design-system-route.ts","../src/blocks-doc.ts","../src/block-types.ts","../src/astro/blocks/tone.ts","../src/hosting.ts","../src/index.ts"],"mappings":";;;KAuBY,mBAAmB,QAC7B,YAAY;EAEV;;KAWQ,uBAAuB,KAAK;EACtC,SAAS;;qBAmDE,QAAQ;;UA62BJ;;EAEf;;EAEA;;;;;;;EAOA,QAAQ;;;;;;;;wBASM,aAAa,YAAW,iBAAsB;UCn6B7C;;;;;;;;EAQf;;EAEA;;;;;;;wBC9Bc,gBAAgB,kBAAiB;;qBCZpC;;qBAqCA,oBAAoB;;;;;;wBAejB,oBAAoB;;wBCzBpB,UAAU;UAcT;;EAEf;;EAEA;;;;;;;;wBASc,YAAY,gBAAgB,kBAAkB;KC7ClD;UAIK;;EAEf,SAAS;EACT;;IAEE;;IAEA;;IAEA;;;;;;;IAOA;;EAEF;;IAEE;;IAEA;;IAEA;;IAEA;;;UAIa;EACf,QAAQ;EACR,SAAS;;EAET;;EAEA;;wBAoBoB,cAAc,UAAS,uBAA4B,QAAQ;iBCzBhE;;;;;;;;;;;EAWf;;EAEA;;;;;;;;;EASA,qBAAqB;;;;;;EAMrB,SAAS;;;;;;;EAOT;;;;;;wBAOc,aAAa,UAAS,sBAA2B;;wBAmBjD,aAAa,UAAS,uCAAwB,gCAAA"}