@avocadostudio-ai/shared 0.1.0

package/dist/draft-mode.d.ts

@@ -0,0 +1,10 @@
+export type DraftSecretValidationResult = {
+    ok: true;
+    reason: null;
+} | {
+    ok: false;
+    reason: "missing_config" | "invalid_secret";
+};
+export declare function getConfiguredDraftSecret(env: Record<string, string | undefined>, keys?: readonly string[]): string | null;
+export declare function validateDraftSecret(receivedSecret: string | null | undefined, env: Record<string, string | undefined>, keys?: readonly string[]): DraftSecretValidationResult;
+export declare function getSafeInternalRedirectPath(value: string | null): string;

package/dist/draft-mode.js

@@ -0,0 +1,29 @@
+// Accept multiple env var names so the same secret works across site and editor.
+// VITE_SITE_DRAFT_SECRET is the editor's name; accepting it here means you can
+// set one var in a shared .env and it works for both site and editor.
+const DEFAULT_DRAFT_SECRET_KEYS = ["DRAFT_MODE_SECRET", "VITE_SITE_DRAFT_SECRET", "NEXT_DRAFT_MODE_SECRET"];
+export function getConfiguredDraftSecret(env, keys = DEFAULT_DRAFT_SECRET_KEYS) {
+    for (const key of keys) {
+        const value = env[key]?.trim();
+        if (value)
+            return value;
+    }
+    return null;
+}
+export function validateDraftSecret(receivedSecret, env, keys = DEFAULT_DRAFT_SECRET_KEYS) {
+    const configuredSecret = getConfiguredDraftSecret(env, keys);
+    const normalizedReceived = receivedSecret?.trim() ?? "";
+    if (!configuredSecret)
+        return { ok: false, reason: "missing_config" };
+    if (!normalizedReceived || normalizedReceived !== configuredSecret)
+        return { ok: false, reason: "invalid_secret" };
+    return { ok: true, reason: null };
+}
+export function getSafeInternalRedirectPath(value) {
+    if (!value)
+        return "/";
+    const decoded = decodeURIComponent(value).trim();
+    if (!decoded.startsWith("/") || decoded.startsWith("//"))
+        return "/";
+    return decoded;
+}

package/dist/editable-path.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Utilities for working with editable-target path strings.
+ *
+ * Paths follow the conventions: `imageUrl`, `cards[0].imageUrl`, `right[0].src`.
+ */
+/** Returns true if the editable path points to an image field. */
+export declare function isImagePath(editablePath: string): boolean;
+/** Derives the companion alt-text path from an image path. Returns the path unchanged if it is not an image path. */
+export declare function toAltPath(editablePath: string): string;
+/**
+ * Return a copy of `props` with `value` written at `editablePath`, using
+ * copy-on-write so the input (and every untouched subtree) is shared by reference.
+ *
+ * Used by the live-draft preview store to layer a streamed field value over the
+ * committed block props. The path must address structure that already exists in
+ * `props`: if an intermediate object/array is missing or an array index is out of
+ * range, the original `props` reference is returned unchanged — drafts preview
+ * existing editable targets, they never create new blocks/items/fields.
+ */
+export declare function setPropAtPath(props: Record<string, unknown>, editablePath: string, value: unknown): Record<string, unknown>;

package/dist/editable-path.js

@@ -0,0 +1,101 @@
+/**
+ * Utilities for working with editable-target path strings.
+ *
+ * Paths follow the conventions: `imageUrl`, `cards[0].imageUrl`, `right[0].src`.
+ */
+/** Matches editable paths that point to an image field (imageUrl or indexed .src). */
+const IMAGE_PATH_RE = /(imageUrl|\.src)$/i;
+/** Returns true if the editable path points to an image field. */
+export function isImagePath(editablePath) {
+    return IMAGE_PATH_RE.test(editablePath);
+}
+/** Derives the companion alt-text path from an image path. Returns the path unchanged if it is not an image path. */
+export function toAltPath(editablePath) {
+    return editablePath.replace(/imageUrl$/i, "imageAlt").replace(/\.src$/i, ".alt");
+}
+/**
+ * Parse an editable-target path into a flat list of access steps.
+ *
+ * The grammar mirrors what `flattenPatchToScopedDrafts` (orchestrator planner) and
+ * each renderer's `data-editable-target` emit: a dotted sequence of tokens, where
+ * each token is `name` or `name[index]`. Examples:
+ *   "title"                      → [key title]
+ *   "headers[0]"                 → [key headers, idx 0]            (array of strings)
+ *   "cards[0].title"             → [key cards, idx 0, key title]
+ *   "links[0].children[1].label" → [key links, idx 0, key children, idx 1, key label]
+ *
+ * Returns null for any token that doesn't fit the grammar (so the caller no-ops
+ * rather than guessing at an unknown shape).
+ */
+function parseEditablePath(path) {
+    if (!path)
+        return null;
+    const steps = [];
+    for (const token of path.split(".")) {
+        const match = /^([A-Za-z_][A-Za-z0-9_]*)(\[\d+\])?$/.exec(token);
+        if (!match)
+            return null;
+        steps.push({ kind: "key", key: match[1] });
+        if (match[2])
+            steps.push({ kind: "index", index: Number(match[2].slice(1, -1)) });
+    }
+    return steps.length ? steps : null;
+}
+/** Immutably apply the remaining steps to a container, returning whether anything changed. */
+function setSteps(container, steps, value) {
+    const [step, ...rest] = steps;
+    if (!step)
+        return { changed: false, next: container };
+    if (step.kind === "key") {
+        // A key step expects a plain object. Anything else means the committed props
+        // don't have the structure this draft addresses → no-op (never invent it).
+        if (!container || typeof container !== "object" || Array.isArray(container)) {
+            return { changed: false, next: container };
+        }
+        const obj = container;
+        if (rest.length === 0) {
+            if (obj[step.key] === value)
+                return { changed: false, next: obj };
+            return { changed: true, next: { ...obj, [step.key]: value } };
+        }
+        const res = setSteps(obj[step.key], rest, value);
+        if (!res.changed)
+            return { changed: false, next: obj };
+        return { changed: true, next: { ...obj, [step.key]: res.next } };
+    }
+    // An index step expects an array, with the index in range. Out-of-range → no-op
+    // so a draft for `cards[5]` never grows a 3-card list.
+    if (!Array.isArray(container) || step.index < 0 || step.index >= container.length) {
+        return { changed: false, next: container };
+    }
+    if (rest.length === 0) {
+        if (container[step.index] === value)
+            return { changed: false, next: container };
+        const copy = container.slice();
+        copy[step.index] = value;
+        return { changed: true, next: copy };
+    }
+    const res = setSteps(container[step.index], rest, value);
+    if (!res.changed)
+        return { changed: false, next: container };
+    const copy = container.slice();
+    copy[step.index] = res.next;
+    return { changed: true, next: copy };
+}
+/**
+ * Return a copy of `props` with `value` written at `editablePath`, using
+ * copy-on-write so the input (and every untouched subtree) is shared by reference.
+ *
+ * Used by the live-draft preview store to layer a streamed field value over the
+ * committed block props. The path must address structure that already exists in
+ * `props`: if an intermediate object/array is missing or an array index is out of
+ * range, the original `props` reference is returned unchanged — drafts preview
+ * existing editable targets, they never create new blocks/items/fields.
+ */
+export function setPropAtPath(props, editablePath, value) {
+    const steps = parseEditablePath(editablePath);
+    if (!steps)
+        return props;
+    const res = setSteps(props, steps, value);
+    return res.changed ? res.next : props;
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { EDITOR_PROTOCOL_VERSION } from "./protocol.ts";
+export { getConfiguredDraftSecret, getSafeInternalRedirectPath, validateDraftSecret, type DraftSecretValidationResult } from "./draft-mode.ts";
+export type { FieldDiffKind, FieldDiff, BlockDiffStatus, BlockDiff, PageDiffStatus, PageDiff, PublishDiff, SiteConfigFieldDiff, SiteConfigDiff, } from "./publish-diff.ts";
+export { isImagePath, toAltPath, setPropAtPath } from "./editable-path.ts";
+export { blockDefinitionSchema, blockManifestSchema, jsonSchemaLikeSchema, validateByJsonSchemaLike, validateManifestDefaultProps, deriveFieldMetaFromSchema, type BlockDefinition, type BlockManifest } from "./block-manifest.ts";
+export { type FieldKind, type ImageSpec, type FieldMeta, type ListFieldMeta, type BlockMeta, type BlockType, type BlockInstance, type BlockRegistration, IMAGE_PLACEHOLDER, isImagePlaceholder, registerBlock, getBlockMeta, getAllBlockMeta, getImageFields, getListImageFields, isFieldInlineEditable, getImageSpec, isChrome, getChromeTypes, blockSchemas, allowedBlockTypes, getPropDisplayName, defaultListItemForBlock, blockInstanceSchema, blockInstanceSchemaLenient, validateBlockProps, getBlockJsonSchema, } from "./blocks/_registry.ts";
+export { defaultPropsForType, resolveHeadingTag, resolveItemHeadingTag, DEFAULT_HEADING_LEVELS, } from "./blocks/index.ts";
+export { blockTypeToCamel, camelToBlockType, blockTypeToLower, lowerToBlockType, } from "./block-names.ts";
+export { makeAddBlock, generateBlockId, makeAddItem, generateItemId, ensureItemIds, type AddBlockOp, type MakeAddBlockOptions, type AddItemOp, type MakeAddItemOptions, } from "./ops/builders.ts";
+export { THEME_TOKEN_TO_CSS_VARS, themeTokenKeys, semanticThemeTokensSchema, mapSemanticThemeTokens, type ThemeTokenKey, type SemanticThemeTokens, } from "./ops/theme-tokens.ts";
+export { chatStreamEventSchema, parseChatStreamFrame, type ChatStreamEvent, type ChatStreamEventType, type ChatStreamFrame, } from "./chat-events.ts";
+export { type PageMeta, type PageDoc, type SiteConfig, type Operation, type EditPlan, type PatchRejectReason, type ApplyPatchMessage, type PatchAckMessage, type ResetToServerMessage, pageMetaSchema, pageDocSchema, pageDocSchemaLenient, siteConfigSchema, operationSchema, editPlanSchema, demoPublishedPages, demoSiteConfig, } from "./schemas.ts";
+export { assistantResponseSchema, chatStartResponseSchema, slugsResponseSchema, bootstrapResponseSchema, cancelResponseSchema, type AssistantResponseParsed, } from "./api-responses.ts";

package/dist/index.js

@@ -0,0 +1,26 @@
+export { EDITOR_PROTOCOL_VERSION } from "./protocol.js";
+export { getConfiguredDraftSecret, getSafeInternalRedirectPath, validateDraftSecret } from "./draft-mode.js";
+export { isImagePath, toAltPath, setPropAtPath } from "./editable-path.js";
+export { blockDefinitionSchema, blockManifestSchema, jsonSchemaLikeSchema, validateByJsonSchemaLike, validateManifestDefaultProps, deriveFieldMetaFromSchema } from "./block-manifest.js";
+export { 
+// Constants & helpers
+IMAGE_PLACEHOLDER, isImagePlaceholder, 
+// Registry functions
+registerBlock, getBlockMeta, getAllBlockMeta, getImageFields, getListImageFields, isFieldInlineEditable, getImageSpec, isChrome, getChromeTypes, 
+// Backwards-compatible exports
+blockSchemas, allowedBlockTypes, 
+// Utility functions
+getPropDisplayName, defaultListItemForBlock, 
+// Schemas & validation
+blockInstanceSchema, blockInstanceSchemaLenient, validateBlockProps, getBlockJsonSchema, } from "./blocks/_registry.js";
+export { defaultPropsForType, resolveHeadingTag, resolveItemHeadingTag, DEFAULT_HEADING_LEVELS, } from "./blocks/index.js";
+export { blockTypeToCamel, camelToBlockType, blockTypeToLower, lowerToBlockType, } from "./block-names.js";
+export { makeAddBlock, generateBlockId, makeAddItem, generateItemId, ensureItemIds, } from "./ops/builders.js";
+export { THEME_TOKEN_TO_CSS_VARS, themeTokenKeys, semanticThemeTokensSchema, mapSemanticThemeTokens, } from "./ops/theme-tokens.js";
+export { chatStreamEventSchema, parseChatStreamFrame, } from "./chat-events.js";
+export { 
+// Schemas
+pageMetaSchema, pageDocSchema, pageDocSchemaLenient, siteConfigSchema, operationSchema, editPlanSchema, 
+// Demo data
+demoPublishedPages, demoSiteConfig, } from "./schemas.js";
+export { assistantResponseSchema, chatStartResponseSchema, slugsResponseSchema, bootstrapResponseSchema, cancelResponseSchema, } from "./api-responses.js";

package/dist/ops/builders.d.ts

@@ -0,0 +1,62 @@
+import type { Operation } from "../schemas.ts";
+import type { BlockType } from "./../blocks/_registry.ts";
+export type AddBlockOp = Extract<Operation, {
+    op: "add_block";
+}>;
+export type MakeAddBlockOptions = {
+    /** Insert the new block immediately after this block id. Omit to insert at the top of the page. */
+    afterBlockId?: string;
+    /** Override the auto-generated block id. Must be unique within the target page. */
+    id?: string;
+};
+/**
+ * Build a canonical `add_block` op from a block type and partial props.
+ *
+ * The returned op's `block` merges `defaultPropsForType(type)` with `partialProps`
+ * (partial wins) and carries a generated id, so it is valid against the strict
+ * operation schema and ready to send to the orchestrator.
+ *
+ * @example
+ * makeAddBlock("/", "Hero", { heading: "Welcome" })
+ * // → { op: "add_block", pageSlug: "/", block: { id: "b_hero_a1b2c3d4", type: "Hero", props: { ...defaults, heading: "Welcome" } } }
+ */
+export declare function makeAddBlock(pageSlug: string, type: BlockType, partialProps?: Record<string, unknown>, options?: MakeAddBlockOptions): AddBlockOp;
+/** Generate a readable, collision-resistant block id, e.g. `b_hero_a1b2c3d4`. */
+export declare function generateBlockId(type: string): string;
+export type AddItemOp = Extract<Operation, {
+    op: "add_item";
+}>;
+export type MakeAddItemOptions = {
+    /** Insert the new item immediately after the item with this id. Omit to append. */
+    afterItemId?: string;
+    /** Override the auto-generated item id. */
+    id?: string;
+};
+/**
+ * Build a canonical `add_item` op. The item is given a stable `id` (generated if
+ * the caller didn't supply one) so it can be targeted by later ops without a
+ * fragile array index.
+ *
+ * @example
+ * makeAddItem("/", "b_features", "features", { title: "New", description: "..." })
+ * // → { op: "add_item", pageSlug: "/", blockId: "b_features", listKey: "features",
+ * //      item: { id: "i_a1b2c3d4", title: "New", description: "..." } }
+ */
+export declare function makeAddItem(pageSlug: string, blockId: string, listKey: string, item?: Record<string, unknown>, options?: MakeAddItemOptions): AddItemOp;
+/** Generate a readable, collision-resistant list-item id, e.g. `i_a1b2c3d4`. */
+export declare function generateItemId(): string;
+/**
+ * Backfill stable `id`s onto every list item declared by a block's manifest
+ * `listFields`, mirroring how blocks carry stable ids. Mutates `blocks` in place
+ * and returns `true` if anything changed (so callers can persist).
+ *
+ * Items that already have a non-empty string `id` are left untouched, so ids
+ * stay stable across loads — which is what lets a planner read an id via
+ * `get_page` and have it still resolve at apply time. Only object items in
+ * declared lists are touched (e.g. Table `rows`, which are `string[][]`, have no
+ * place for an id and are skipped — those ops fall back to positional `index`).
+ */
+export declare function ensureItemIds(blocks: Array<{
+    type: string;
+    props: unknown;
+}>): boolean;

package/dist/ops/builders.js

@@ -0,0 +1,111 @@
+// Ergonomic builders for Avocado `Operation`s.
+//
+// The canonical `add_block` op carries a fully-formed `BlockInstance`
+// (`{ id, type, props }`) under `op.block` — the ops engine requires the id to
+// be present and unique, and validates props against the per-type schema. That
+// canonical shape is exactly right for the wire/persisted op, but heavy to
+// construct by hand for the common "add a block of type X" intent: the caller
+// must mint an id and supply a full prop set.
+//
+// `makeAddBlock` closes that gap without denormalizing the op: it generates a
+// collision-resistant id and fills `defaultPropsForType(type)` under any
+// partial props you pass, returning a canonical, schema-valid `add_block`.
+//
+// External integrators: prefer this over hand-constructing the op (and never
+// hand-write the `Operation` union — import it from this package, or validate
+// against `contract/operation.schema.json`).
+import { getBlockMeta } from "./../blocks/_registry.js";
+import { defaultPropsForType } from "../blocks/index.js";
+/**
+ * Build a canonical `add_block` op from a block type and partial props.
+ *
+ * The returned op's `block` merges `defaultPropsForType(type)` with `partialProps`
+ * (partial wins) and carries a generated id, so it is valid against the strict
+ * operation schema and ready to send to the orchestrator.
+ *
+ * @example
+ * makeAddBlock("/", "Hero", { heading: "Welcome" })
+ * // → { op: "add_block", pageSlug: "/", block: { id: "b_hero_a1b2c3d4", type: "Hero", props: { ...defaults, heading: "Welcome" } } }
+ */
+export function makeAddBlock(pageSlug, type, partialProps = {}, options = {}) {
+    const block = {
+        id: options.id ?? generateBlockId(type),
+        type,
+        props: { ...defaultPropsForType(type), ...partialProps },
+    };
+    return options.afterBlockId
+        ? { op: "add_block", pageSlug, afterBlockId: options.afterBlockId, block }
+        : { op: "add_block", pageSlug, block };
+}
+/** Generate a readable, collision-resistant block id, e.g. `b_hero_a1b2c3d4`. */
+export function generateBlockId(type) {
+    const slug = String(type)
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "") || "block";
+    return `b_${slug}_${randomSuffix()}`;
+}
+/**
+ * Build a canonical `add_item` op. The item is given a stable `id` (generated if
+ * the caller didn't supply one) so it can be targeted by later ops without a
+ * fragile array index.
+ *
+ * @example
+ * makeAddItem("/", "b_features", "features", { title: "New", description: "..." })
+ * // → { op: "add_item", pageSlug: "/", blockId: "b_features", listKey: "features",
+ * //      item: { id: "i_a1b2c3d4", title: "New", description: "..." } }
+ */
+export function makeAddItem(pageSlug, blockId, listKey, item = {}, options = {}) {
+    const id = options.id ?? (typeof item.id === "string" && item.id ? item.id : generateItemId());
+    const withId = { ...item, id };
+    return options.afterItemId
+        ? { op: "add_item", pageSlug, blockId, listKey, item: withId, afterItemId: options.afterItemId }
+        : { op: "add_item", pageSlug, blockId, listKey, item: withId };
+}
+/** Generate a readable, collision-resistant list-item id, e.g. `i_a1b2c3d4`. */
+export function generateItemId() {
+    return `i_${randomSuffix()}`;
+}
+/**
+ * Backfill stable `id`s onto every list item declared by a block's manifest
+ * `listFields`, mirroring how blocks carry stable ids. Mutates `blocks` in place
+ * and returns `true` if anything changed (so callers can persist).
+ *
+ * Items that already have a non-empty string `id` are left untouched, so ids
+ * stay stable across loads — which is what lets a planner read an id via
+ * `get_page` and have it still resolve at apply time. Only object items in
+ * declared lists are touched (e.g. Table `rows`, which are `string[][]`, have no
+ * place for an id and are skipped — those ops fall back to positional `index`).
+ */
+export function ensureItemIds(blocks) {
+    let changed = false;
+    for (const block of blocks) {
+        const listFields = getBlockMeta(block.type)?.listFields;
+        if (!listFields)
+            continue;
+        const props = block.props;
+        if (!props || typeof props !== "object" || Array.isArray(props))
+            continue;
+        for (const listKey of Object.keys(listFields)) {
+            const list = props[listKey];
+            if (!Array.isArray(list))
+                continue;
+            for (const item of list) {
+                if (!item || typeof item !== "object" || Array.isArray(item))
+                    continue;
+                const rec = item;
+                if (typeof rec.id !== "string" || rec.id.length === 0) {
+                    rec.id = generateItemId();
+                    changed = true;
+                }
+            }
+        }
+    }
+    return changed;
+}
+function randomSuffix() {
+    const c = globalThis.crypto;
+    if (c?.randomUUID)
+        return c.randomUUID().replace(/-/g, "").slice(0, 8);
+    return Math.random().toString(36).slice(2, 10).padEnd(8, "0");
+}

package/dist/ops/theme-tokens.d.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+/**
+ * Canonical map: semantic token → the CSS custom properties it sets.
+ *
+ * One semantic token may fan out to several vars so that intuitive requests
+ * ("round the corners", "use a serif heading") change everything a user would
+ * expect in one shot. Keep this list conservative and well-understood — every
+ * key here becomes part of the public operation contract.
+ */
+export declare const THEME_TOKEN_TO_CSS_VARS: {
+    readonly brandColor: readonly ["--brand", "--brand-hover", "--link"];
+    readonly accentColor: readonly ["--accent", "--accent-hover"];
+    readonly backgroundColor: readonly ["--bg-0", "--bg-000"];
+    readonly surfaceColor: readonly ["--surface", "--card-bg", "--bg-100"];
+    readonly headingColor: readonly ["--heading", "--text-100"];
+    readonly textColor: readonly ["--body", "--text-200"];
+    readonly mutedTextColor: readonly ["--body-secondary", "--text-300", "--caption"];
+    readonly headingFont: readonly ["--font-heading"];
+    readonly bodyFont: readonly ["--font-body"];
+    readonly radius: readonly ["--radius", "--radius-btn", "--radius-card", "--radius-feature", "--radius-input"];
+};
+export type ThemeTokenKey = keyof typeof THEME_TOKEN_TO_CSS_VARS;
+export declare const themeTokenKeys: ThemeTokenKey[];
+/**
+ * Zod shape for the semantic patch carried by `update_theme.patch`. Every token
+ * is an optional string (a color, font stack, or length). Set a token to the
+ * empty string to clear its overrides and fall back to the theme default.
+ */
+export declare const semanticThemeTokensSchema: z.ZodObject<{
+    brandColor: z.ZodOptional<z.ZodString>;
+    accentColor: z.ZodOptional<z.ZodString>;
+    backgroundColor: z.ZodOptional<z.ZodString>;
+    surfaceColor: z.ZodOptional<z.ZodString>;
+    headingColor: z.ZodOptional<z.ZodString>;
+    textColor: z.ZodOptional<z.ZodString>;
+    mutedTextColor: z.ZodOptional<z.ZodString>;
+    headingFont: z.ZodOptional<z.ZodString>;
+    bodyFont: z.ZodOptional<z.ZodString>;
+    radius: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SemanticThemeTokens = z.infer<typeof semanticThemeTokensSchema>;
+/**
+ * Expand a semantic token patch into a flat CSS-variable map.
+ *
+ * Empty-string values are preserved (mapped to each underlying var) so the
+ * engine can interpret them as "clear this override". Raw `cssVars` from the op
+ * should be merged AFTER this result so explicit vars win over the semantic
+ * expansion.
+ */
+export declare function mapSemanticThemeTokens(patch: SemanticThemeTokens): Record<string, string>;

package/dist/ops/theme-tokens.js

@@ -0,0 +1,73 @@
+// Semantic theme tokens for the `update_theme` operation.
+//
+// Block renderers style themselves entirely from CSS custom properties (see
+// `packages/blocks/src/blocks/_tokens.css`), and a site's overrides live in
+// `siteConfig.themeOverrides` (a raw `--var` → value map) consumed at runtime
+// by the site's `ThemeOverrides` component.
+//
+// Exposing those raw var names directly to the planner is error-prone — the
+// LLM has to know that "make the brand blue" means `--brand` (and `--link`,
+// and `--brand-hover`). Instead the `update_theme` op accepts a small, stable
+// SEMANTIC vocabulary (meaning, not var names) which the ops engine expands to
+// the underlying CSS variables via the table below. Integrators who need a var
+// we don't model can still pass a raw `cssVars` map on the op as an escape
+// hatch (merged after the semantic expansion, so raw always wins).
+import { z } from "zod";
+/**
+ * Canonical map: semantic token → the CSS custom properties it sets.
+ *
+ * One semantic token may fan out to several vars so that intuitive requests
+ * ("round the corners", "use a serif heading") change everything a user would
+ * expect in one shot. Keep this list conservative and well-understood — every
+ * key here becomes part of the public operation contract.
+ */
+export const THEME_TOKEN_TO_CSS_VARS = {
+    brandColor: ["--brand", "--brand-hover", "--link"],
+    accentColor: ["--accent", "--accent-hover"],
+    backgroundColor: ["--bg-0", "--bg-000"],
+    surfaceColor: ["--surface", "--card-bg", "--bg-100"],
+    headingColor: ["--heading", "--text-100"],
+    textColor: ["--body", "--text-200"],
+    mutedTextColor: ["--body-secondary", "--text-300", "--caption"],
+    headingFont: ["--font-heading"],
+    bodyFont: ["--font-body"],
+    radius: ["--radius", "--radius-btn", "--radius-card", "--radius-feature", "--radius-input"],
+};
+export const themeTokenKeys = Object.keys(THEME_TOKEN_TO_CSS_VARS);
+/**
+ * Zod shape for the semantic patch carried by `update_theme.patch`. Every token
+ * is an optional string (a color, font stack, or length). Set a token to the
+ * empty string to clear its overrides and fall back to the theme default.
+ */
+export const semanticThemeTokensSchema = z.object({
+    brandColor: z.string().optional().describe("Primary brand color (sets --brand, --brand-hover, --link). Any CSS color."),
+    accentColor: z.string().optional().describe("Secondary accent color (sets --accent, --accent-hover)."),
+    backgroundColor: z.string().optional().describe("Page background color (sets --bg-0, --bg-000)."),
+    surfaceColor: z.string().optional().describe("Card/panel surface color (sets --surface, --card-bg, --bg-100)."),
+    headingColor: z.string().optional().describe("Heading text color (sets --heading, --text-100)."),
+    textColor: z.string().optional().describe("Body text color (sets --body, --text-200)."),
+    mutedTextColor: z.string().optional().describe("Secondary/muted text color (sets --body-secondary, --text-300, --caption)."),
+    headingFont: z.string().optional().describe("Heading font stack (sets --font-heading), e.g. 'Georgia, serif'."),
+    bodyFont: z.string().optional().describe("Body font stack (sets --font-body)."),
+    radius: z.string().optional().describe("Corner radius applied across buttons/cards/inputs (sets --radius and friends), e.g. '12px'."),
+});
+/**
+ * Expand a semantic token patch into a flat CSS-variable map.
+ *
+ * Empty-string values are preserved (mapped to each underlying var) so the
+ * engine can interpret them as "clear this override". Raw `cssVars` from the op
+ * should be merged AFTER this result so explicit vars win over the semantic
+ * expansion.
+ */
+export function mapSemanticThemeTokens(patch) {
+    const out = {};
+    for (const key of themeTokenKeys) {
+        const value = patch[key];
+        if (value === undefined)
+            continue;
+        for (const cssVar of THEME_TOKEN_TO_CSS_VARS[key]) {
+            out[cssVar] = value;
+        }
+    }
+    return out;
+}

package/dist/protocol.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Identifier for the postMessage protocol used between the editor and the
+ * preview iframe (preview-adapter). Bumped only when the wire shape of
+ * messages changes in an incompatible way. Self-host CLI checks this at
+ * boot against the orchestrator's reported value to warn on drift.
+ */
+export declare const EDITOR_PROTOCOL_VERSION = "site-editor/v1";

package/dist/protocol.js

@@ -0,0 +1,7 @@
+/**
+ * Identifier for the postMessage protocol used between the editor and the
+ * preview iframe (preview-adapter). Bumped only when the wire shape of
+ * messages changes in an incompatible way. Self-host CLI checks this at
+ * boot against the orchestrator's reported value to warn on drift.
+ */
+export const EDITOR_PROTOCOL_VERSION = "site-editor/v1";

package/dist/publish-diff.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Types for the "what will change on publish" diff.
+ *
+ * The orchestrator computes a PublishDiff by comparing session draft pages
+ * to the currently-published pages. Shape is intentionally lightweight so
+ * the editor (and later the immersive widget) can render it without extra
+ * work.
+ */
+export type FieldDiffKind = "text" | "image" | "other";
+export type FieldDiff = {
+    /** Dotted/bracketed path inside the block's props, e.g. `heading` or `items[2].quote`. */
+    path: string;
+    before: unknown;
+    after: unknown;
+    /** Rendering hint for the UI (text diff vs thumbnail vs generic). */
+    kind: FieldDiffKind;
+};
+export type BlockDiffStatus = "added" | "removed" | "modified" | "moved" | "unchanged";
+export type BlockDiff = {
+    blockId: string;
+    type: string;
+    status: BlockDiffStatus;
+    /** When status === "modified" (or "moved" with prop changes) — field-level leaves that changed. */
+    fieldDiffs?: FieldDiff[];
+    /** 0-based index in published page. Omitted when block was added. */
+    positionBefore?: number;
+    /** 0-based index in draft page. Omitted when block was removed. */
+    positionAfter?: number;
+};
+export type PageDiffStatus = "added" | "removed" | "modified" | "unchanged";
+export type PageDiff = {
+    slug: string;
+    status: PageDiffStatus;
+    titleBefore?: string;
+    titleAfter?: string;
+    blockDiffs: BlockDiff[];
+};
+/**
+ * Per-key change inside the SiteHeader-shaped portion of siteConfig.
+ * `path` uses dot/bracket notation rooted at the config (e.g. `name`,
+ * `navLabels["/pricing"]`, `navGroups["Products"]`).
+ */
+export type SiteConfigFieldDiff = {
+    path: string;
+    before: unknown;
+    after: unknown;
+    kind: FieldDiffKind;
+};
+export type SiteConfigDiff = {
+    status: "added" | "removed" | "modified" | "unchanged";
+    fieldDiffs: SiteConfigFieldDiff[];
+};
+export type PublishDiff = {
+    summary: {
+        pagesAdded: number;
+        pagesRemoved: number;
+        pagesModified: number;
+        pagesUnchanged: number;
+        /** Total number of field-level changes across all pages. Useful for CTA labels. */
+        totalChangedFields: number;
+        /** Total number of changed siteConfig fields (header chrome). */
+        siteConfigChangedFields: number;
+    };
+    pages: PageDiff[];
+    /** Diff of the SiteHeader-driving siteConfig (name, logo, navLabels, navGroups). Always present; `unchanged` when no diff. */
+    siteConfig: SiteConfigDiff;
+};

package/dist/publish-diff.js

@@ -0,0 +1,9 @@
+/**
+ * Types for the "what will change on publish" diff.
+ *
+ * The orchestrator computes a PublishDiff by comparing session draft pages
+ * to the currently-published pages. Shape is intentionally lightweight so
+ * the editor (and later the immersive widget) can render it without extra
+ * work.
+ */
+export {};