@wocart/theme 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to `@wocart/theme` are recorded here. The package follows
 major version, and an export is marked `@deprecated` for at least one minor
 release before a major removes it.
 
+## 1.6.0 — 2026-10-19
+
+An editor's change shows on the preview page at once.
+
+### Added
+
+- The preview protocol's `patch` message (`PreviewPatch`): a change the
+  editor has already made — move, duplicate, remove and restore a section,
+  hide or show one, a field's text — shown by the preview bridge on the page
+  as it stands, before the render that follows it. Patches are hints; the
+  render stays the page's truth, and a render already on its way when a
+  patch arrives is dropped so it cannot undo it. A page that does not know
+  patches ignores them. The protocol version stays 1.
+
 ## 1.5.0 — 2026-10-18
 
 The editor-facing contract: everything a visual editor needs to discover and

package/README.md

@@ -406,15 +406,28 @@ framing window, with `source: "wocart-editor"` and the protocol's `version`
 | The editor sends | The page answers |
 | --- | --- |
 | — | `ready` with every instance: `{ id, type, parent, hidden, rect }` |
-| `render` `{ draft, revision? }` | `rendered` `{ revision, instances }`, or `error` `{ revision, reason }`; an answer overtaken by a newer render is dropped |
+| `render` `{ draft, revision? }` | `rendered` `{ revision, instances }`, or `error` `{ revision, reason }`; an answer overtaken by a newer render or a patch is dropped |
+| `patch` `{ patches }` | the change shown at once, on the page as it stands, then `layout` (see below) |
 | `mode` `"edit"` \| `"interactive"` | in `edit`, links and forms do nothing and a click is `select` `{ id }` of the innermost instance |
 | `scroll-to` `{ id }` | the instance scrolls into view |
 | `token` `{ token }` | the next render uses it |
 | — | `hover` `{ id \| null }` as the pointer moves; `layout` after a scroll or resize |
 
+A `patch` shows a change the editor has already made to its draft before the
+render that follows it arrives — so moving, copying, removing or hiding a
+section, and typing a field's text, show on the page at once. Each patch
+(`PreviewPatch`) is a hint: the page applies what it finds — `move` a section
+to an index, `duplicate` an instance under new ids, `remove` one and
+`restore` it, `hide` one or show it again, replace `text` that reads `from`
+inside an instance with `to` — and leaves the rest to the render, which is
+the page's truth. An editor therefore always sends the render too; a page
+from before 1.6.0 ignores patches and still shows every change, a moment
+later.
+
 A swapped section's scripts do not run again. A section with browser behavior
 binds it again on `PREVIEW_SECTION_LOAD_EVENT` (`wocart:section-load`,
-dispatched on `document` with `detail.id`). When the bridge replaces the whole
+dispatched on `document` with `detail.id`) — also for a section a patch
+copied, restored or showed again. When the bridge replaces the whole
 page instead, it does what Astro's router does after a navigation — a new
 `<body>`, the root element's attributes, the title — and dispatches
 `astro:page-load`, so a script written for the router mounts again as it does

package/dist/index.d.ts

@@ -28,6 +28,6 @@ export type { MessageOptions, MessageValues, PluralCategory } from "./messages.j
 export { THEME_MANIFEST_CONTRACT_VERSION, THEME_MANIFEST_PATH, manifestCatalog, themeManifest, validateThemeManifest, } from "./manifest.js";
 export { diffThemeManifests } from "./manifest-diff.js";
 export { PREVIEW_PROTOCOL_VERSION, THEME_PREVIEW_PATH, parsePreviewMarker, previewEndMarker, previewStartMarker, } from "./preview-protocol.js";
-export type { PreviewEditorMessage, PreviewInstance, PreviewMode, PreviewPageMessage, PreviewRect, } from "./preview-protocol.js";
+export type { PreviewEditorMessage, PreviewInstance, PreviewMode, PreviewPageMessage, PreviewPatch, PreviewRect, } from "./preview-protocol.js";
 export type { ManifestChange, ManifestDiff } from "./manifest-diff.js";
 export type { JsonValue, JsonObject, LocaleCode, LocalizedText, ResolutionScope, FieldKind, FieldDefinition, FieldValue, InferProps, FieldValues, SlotDefinition, ComponentCapabilities, ComponentPreset, PresetInstance, SurfacePageType, ComponentDefinition, ComponentSpec, SurfaceSpec, ThemeDefinition, SettingsGroup, InferSettings, ThemeSettingsIssue, ThemeSettingsIssueCode, ThemeSettingsResult, NumberFieldDefinition, ColorFieldDefinition, MenuFieldDefinition, CollectionFieldDefinition, ProductFieldDefinition, CategoryFieldDefinition, ImageFieldDefinition, RichTextFieldDefinition, RichTextFormat, ListFieldDefinition, ListItemFieldDefinition, ListItem, MediaReference, ResolvedImage, RichTextValue, RichTextDocument, RichTextBlock, RichTextParagraph, RichTextHeading, RichTextList, RichTextListItem, RichTextInline, RichTextText, RichTextBreak, RichTextMark, ThemeManifest, ThemeManifestIssue, ThemeManifestIssueCode, ThemeManifestResult, ComponentInstance, PageData, ThemeRenderContext, LoadContext, LoadFn, ReadCache, PageDataIssue, PageDataIssueCode, PageDataResult, ResolvedInstance, ThemeDefinitionIssue, ThemeDefinitionIssueCode, ThemeValidationOptions, } from "./types.js";

package/dist/preview-bridge.js

@@ -6,12 +6,14 @@
  * at, and re-renders a draft the editor sends by posting it back to the
  * storefront and swapping in only the sections that changed — or, when the
  * page around them changed, the whole page, the way Astro's router swaps one.
+ * A change the editor patches is shown at once, on the page as it stands,
+ * until that render arrives.
  *
  * It draws nothing — outlines, toolbars and panels are the editor's. It posts
  * only to the editor origin it is given and reads only that origin's messages
  * from the framing window.
  */
-import { PREVIEW_PROTOCOL_VERSION, THEME_PREVIEW_PATH, parsePreviewMarker, } from "./preview-protocol.js";
+import { PREVIEW_PROTOCOL_VERSION, THEME_PREVIEW_PATH, parsePreviewMarker, previewEndMarker, previewStartMarker, } from "./preview-protocol.js";
 /**
  * Dispatched on `document` for each section the bridge swapped in, with the
  * instance id as `detail.id`: a section with browser behavior binds it again.
@@ -21,7 +23,9 @@ import { PREVIEW_PROTOCOL_VERSION, THEME_PREVIEW_PATH, parsePreviewMarker, } fro
 export const PREVIEW_SECTION_LOAD_EVENT = "wocart:section-load";
 const ASTRO_PAGE_LOAD_EVENT = "astro:page-load";
 const SHOW_COMMENT = 0x80;
+const SHOW_TEXT = 0x4;
 const ELEMENT_NODE = 1;
+const TEXT_NODE = 3;
 const COMMENT_NODE = 8;
 /**
  * Every complete marker pair under `root`, in document order, each with the
@@ -74,6 +78,30 @@ function markup(nodes) {
     })
         .join("");
 }
+/** An instance's nodes with its markers: what moves, copies or goes with it. */
+function withMarkers(entry) {
+    const inside = between(entry);
+    return inside === null ? null : [entry.start, ...inside, entry.end];
+}
+/** Text nodes under `nodes` that a merchant reads — never a script's or a style's. */
+function textNodes(nodes) {
+    const found = [];
+    for (const node of nodes) {
+        if (node.nodeType === TEXT_NODE) {
+            found.push(node);
+            continue;
+        }
+        if (node.nodeType !== ELEMENT_NODE)
+            continue;
+        const walker = node.ownerDocument.createTreeWalker(node, SHOW_TEXT);
+        for (let text = walker.nextNode(); text !== null; text = walker.nextNode()) {
+            const tag = text.parentElement?.tagName;
+            if (tag !== "SCRIPT" && tag !== "STYLE" && tag !== "TEMPLATE")
+                found.push(text);
+        }
+    }
+    return found;
+}
 /**
  * The page with every section's content left out — the root's attributes and
  * the body around the sections: what must not change for sections to be
@@ -229,6 +257,132 @@ export function startPreviewBridge(options) {
         }
         return swapped;
     };
+    /** What a `remove` or `hide` patch took off the page, to put back on `restore` or show. */
+    const removed = new Map();
+    const hiddenNodes = new Map();
+    const sectionsOf = () => marked.filter((entry) => entry.parent === null);
+    const find = (id) => marked.find((entry) => entry.id === id);
+    /** Puts `nodes` at `index` among the document's sections other than `id`. */
+    const place = (nodes, id, index) => {
+        const others = sectionsOf().filter((entry) => entry.id !== id);
+        if (!Number.isInteger(index) || index < 0 || index > others.length)
+            return false;
+        const before = others[index]?.start ?? others.at(-1)?.end.nextSibling ?? null;
+        const parent = others[index]?.start.parentNode ?? others.at(-1)?.end.parentNode;
+        if (!parent)
+            return false;
+        for (const node of nodes)
+            parent.insertBefore(node, before);
+        return true;
+    };
+    const relabel = (marker, ids) => {
+        const parsed = parsePreviewMarker(marker.data);
+        if (parsed === null || !Object.hasOwn(ids, parsed.id))
+            return;
+        const id = ids[parsed.id];
+        marker.data = parsed.kind === "start" ? previewStartMarker({ id, type: parsed.type, hidden: parsed.hidden }) : previewEndMarker({ id });
+    };
+    /** Applies one patch to the page as it stands; returns the sections it put in. */
+    const apply = (patch) => {
+        const entry = find(patch.id);
+        switch (patch.op) {
+            case "move": {
+                if (entry === undefined || entry.parent !== null)
+                    return [];
+                const nodes = withMarkers(entry);
+                if (nodes !== null)
+                    place(nodes, entry.id, patch.index);
+                return [];
+            }
+            case "duplicate": {
+                const nodes = entry === undefined ? null : withMarkers(entry);
+                if (entry === undefined || nodes === null || !Object.hasOwn(patch.ids, entry.id))
+                    return [];
+                const copies = nodes.map((node) => node.cloneNode(true));
+                for (const copy of copies) {
+                    if (copy.nodeType === COMMENT_NODE)
+                        relabel(copy, patch.ids);
+                    else if (copy.nodeType === ELEMENT_NODE) {
+                        const walker = doc.createTreeWalker(copy, SHOW_COMMENT);
+                        for (let node = walker.nextNode(); node !== null; node = walker.nextNode())
+                            relabel(node, patch.ids);
+                    }
+                }
+                const after = entry.end.nextSibling;
+                for (const copy of copies)
+                    entry.end.parentNode.insertBefore(copy, after);
+                return [patch.ids[entry.id]];
+            }
+            case "remove": {
+                const nodes = entry === undefined ? null : withMarkers(entry);
+                if (nodes === null)
+                    return [];
+                for (const node of nodes)
+                    node.parentNode?.removeChild(node);
+                removed.set(patch.id, nodes);
+                return [];
+            }
+            case "restore": {
+                const nodes = removed.get(patch.id);
+                if (entry !== undefined || nodes === undefined || !place(nodes, patch.id, patch.index))
+                    return [];
+                removed.delete(patch.id);
+                return [patch.id];
+            }
+            case "hide": {
+                if (entry === undefined || entry.hidden === patch.hidden)
+                    return [];
+                const inside = between(entry);
+                if (inside === null)
+                    return [];
+                if (patch.hidden) {
+                    for (const node of inside)
+                        node.parentNode?.removeChild(node);
+                    hiddenNodes.set(entry.id, inside);
+                }
+                else {
+                    const kept = hiddenNodes.get(entry.id);
+                    if (kept === undefined)
+                        return [];
+                    for (const node of kept)
+                        entry.end.parentNode.insertBefore(node, entry.end);
+                    hiddenNodes.delete(entry.id);
+                }
+                entry.start.data = previewStartMarker({ id: entry.id, type: entry.type, hidden: patch.hidden });
+                return patch.hidden ? [] : [entry.id];
+            }
+            case "text": {
+                const inside = entry === undefined ? null : between(entry);
+                const from = patch.from.trim();
+                if (inside === null || from === "" || typeof patch.to !== "string")
+                    return [];
+                for (const node of textNodes(inside)) {
+                    if (node.data.trim() !== from)
+                        continue;
+                    const lead = /^\s*/.exec(node.data)[0];
+                    const trail = /\s*$/.exec(node.data)[0];
+                    node.data = `${lead}${patch.to}${trail}`;
+                }
+                return [];
+            }
+            default:
+                return [];
+        }
+    };
+    /** Shows `patches` at once; a render already on its way would undo them, so it is dropped. */
+    const patchPage = (patches) => {
+        latest += 1;
+        const loaded = [];
+        for (const patch of patches) {
+            if (typeof patch !== "object" || patch === null || typeof patch.id !== "string")
+                continue;
+            loaded.push(...apply(patch));
+            marked = collect(doc.body);
+        }
+        for (const id of loaded)
+            doc.dispatchEvent(new win.CustomEvent(PREVIEW_SECTION_LOAD_EVENT, { detail: { id } }));
+        post({ type: "layout", instances: instances() });
+    };
     const render = async (draft, revision) => {
         const ticket = ++latest;
         try {
@@ -276,6 +430,10 @@ export function startPreviewBridge(options) {
                     void render(message.draft, typeof message.revision === "number" ? message.revision : null);
                 }
                 break;
+            case "patch":
+                if (Array.isArray(message.patches))
+                    patchPage(message.patches);
+                break;
             case "mode":
                 if (message.mode === "edit" || message.mode === "interactive")
                     mode = message.mode;

package/dist/preview-protocol.d.ts

@@ -56,10 +56,54 @@ export type PreviewPageMessage = {
 });
 /** The interaction an editor allows: `edit` turns clicks into selections; `interactive` lets the page behave. */
 export type PreviewMode = "edit" | "interactive";
+/**
+ * A change the editor has already made to its draft, for the page to show at
+ * once, before the `render` that follows it. A patch is a hint: the page
+ * applies what it can find and leaves the rest to that render, which is the
+ * page's truth — so an editor always sends the render too, and a page that
+ * does not know patches (before `@wocart/theme` 1.6.0) still shows every
+ * change, a moment later.
+ *
+ * - `move`: a section of the document to `index` among the sections, counted
+ *   once it has left its place (`moveInstance`).
+ * - `duplicate`: a copy of an instance right after it; `ids` maps every
+ *   instance id inside it, its own included, to its copy's.
+ * - `remove`: an instance and everything in it; `restore` puts what a
+ *   `remove` took back, as a section of the document at `index`.
+ * - `hide`: an instance switched off (it shows nothing) or back on.
+ * - `text`: inside an instance, text that reads `from` now reads `to` — a
+ *   field's text as the theme prints it.
+ */
+export type PreviewPatch = {
+    op: "move";
+    id: string;
+    index: number;
+} | {
+    op: "duplicate";
+    id: string;
+    ids: Readonly<Record<string, string>>;
+} | {
+    op: "remove";
+    id: string;
+} | {
+    op: "restore";
+    id: string;
+    index: number;
+} | {
+    op: "hide";
+    id: string;
+    hidden: boolean;
+} | {
+    op: "text";
+    id: string;
+    from: string;
+    to: string;
+};
 /**
  * What the editor tells the preview page. `draft` is a `PreviewDraft` of
  * `@wocart/storefront`; `revision`, when given, comes back on the `rendered`
- * or `error` it causes, and a render answered after a newer one is dropped.
+ * or `error` it causes, and a render answered after a newer one is dropped —
+ * as is one answered after a `patch`, which the next render follows.
  */
 export type PreviewEditorMessage = {
     source: "wocart-editor";
@@ -68,6 +112,9 @@ export type PreviewEditorMessage = {
     type: "render";
     draft: Record<string, unknown>;
     revision?: number;
+} | {
+    type: "patch";
+    patches: readonly PreviewPatch[];
 } | {
     type: "mode";
     mode: PreviewMode;

package/dist/version.d.ts

@@ -4,4 +4,4 @@
  * reads. Always equal to `package.json`'s version; the package check refuses
  * a release where they differ.
  */
-export declare const THEME_SDK_VERSION = "1.5.0";
+export declare const THEME_SDK_VERSION = "1.6.0";

package/dist/version.js

@@ -4,4 +4,4 @@
  * reads. Always equal to `package.json`'s version; the package check refuses
  * a release where they differ.
  */
-export const THEME_SDK_VERSION = "1.5.0";
+export const THEME_SDK_VERSION = "1.6.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wocart/theme",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "The Wocart theme contract: code-owned component definitions, JSON page documents, validation and resolution, and a reference Astro renderer.",
   "keywords": [
     "wocart",