@jxsuite/studio 1.0.0 → 1.2.0

package/src/canvas/iframe-protocol.ts

@@ -11,7 +11,7 @@
 
 import type { JxDocOp } from "../tabs/patch-ops";
 import type { JxContentResult, SlashCommand } from "../editor/inline-edit";
-import type { JxMutableNode } from "@jxsuite/schema/types";
+import type { JxExpressionNode, JxMutableNode } from "@jxsuite/schema/types";
 
 /**
  * The wire form of a value-carrying document op (the `forward` half of a recorded
@@ -61,8 +61,21 @@ export type ParentToIframe =
       docBase: string;
       mapperCtx: WireMapperCtx;
       siteStyle: Record<string, unknown> | null;
+      // Forced color-scheme preview (spec §9.5): "light"/"dark" sets data-color-scheme on the
+      // Iframe root, null clears it (auto — follow the OS).
+      colorScheme: "light" | "dark" | null;
       gen: number;
     }
+  // Flip the forced color-scheme preview on the iframe root without re-rendering — a document-level
+  // Idempotent attribute write, deliberately gen-less (like endEdit).
+  | { kind: "setColorScheme"; scheme: "light" | "dark" | null }
+  // Replace the injected site-style sheet in place (live design-token editing) — idempotent and
+  // Render-free; the superseding render carries the same style via its own siteStyle.
+  | {
+      kind: "siteStyleUpdate";
+      siteStyle: Record<string, unknown> | null;
+      media: Record<string, string>;
+    }
   // Ask the iframe to measure the given document paths and post their current rects back. Used to
   // Draw the selection overlay regardless of where the selection change originated (canvas click,
   // Layers panel, keyboard) — the parent can't measure iframe nodes itself (cross-origin bridge).
@@ -110,6 +123,21 @@ export type ParentToIframe =
         | { command: "link"; href: string | null } // Null/"" = remove
         | { command: "insertData"; token: string };
     }
+  // ─── Live expression preview (M6) ───────────────────────────────────────────
+  // Evaluate expression nodes against the iframe's LIVE resolved scope (real repeater items, real
+  // Window#/ globals) and post per-node display values back. `contextPath` is the document path of
+  // The node whose scope context the expressions bind to (null = the root scope); when it sits
+  // Inside a repeater template, the iframe binds the first rendered item's $map context. `reqId`
+  // Correlates the reply (measure/geometry precedent); `gen` is the render the request targets —
+  // The iframe refuses to evaluate against a different render, and the parent drops replies whose
+  // Gen no longer matches its last-rendered one.
+  | {
+      kind: "evalExpr";
+      exprs: { id: string; node: JxExpressionNode }[];
+      contextPath: (string | number)[] | null;
+      reqId: number;
+      gen: number;
+    }
   // ─── Cross-frame DnD (Phase 4c spike) ──────────────────────────────────────
   // Begin a drag session in the iframe: `src` is the realm-agnostic source kind, `dragSeq` is the
   // Per-session id (parent drops any reply with a different seq), `gen` is the render the session
@@ -125,6 +153,19 @@ export type ParentToIframe =
   // The drag was cancelled (Escape/abort from the parent realm) — same teardown as dragEnd.
   | { kind: "dragCancel"; dragSeq: number };
 
+/**
+ * One expression's live evaluation outcome (M6). `values` are path-key → display-string pairs — the
+ * trace hook's per-node values, already formatted INSIDE the iframe (same truncation rules as the
+ * parent's snapshot preview) so only postMessage-safe strings cross the boundary. `error` carries
+ * the thrown message when this expression failed (its `values` then hold whatever nodes reported
+ * before the throw).
+ */
+export interface EvalExprResult {
+  id: string;
+  values: [string, string][];
+  error?: string;
+}
+
 /** A node's bounding box, in the iframe's own viewport coordinates. */
 export interface SerializableRect {
   x: number;
@@ -229,6 +270,10 @@ export type IframeToParent =
   // Response to `measure`: the rects of whichever requested paths resolved to a node (missing paths
   // Are simply omitted). `reqId` echoes the request so the parent can drop stale responses.
   | { kind: "geometry"; reqId: number; hits: NodeHit[] }
+  // Response to `evalExpr`: one result per requested expression (empty when the request's gen no
+  // Longer matches the live render — the iframe never evaluates against the wrong scope). `reqId`/
+  // `gen` echo the request so the parent can drop stale replies (measure/geometry precedent).
+  | { kind: "evalResult"; reqId: number; gen: number; results: EvalExprResult[] }
   // A patch applied cleanly (echoes gen so the host can re-measure the selection overlay).
   | { kind: "patchComplete"; gen: number }
   // A patch could not be applied surgically — the parent escalates to a full render.
@@ -248,8 +293,9 @@ export type IframeToParent =
       metaKey: boolean;
       shiftKey: boolean;
     }
-  // Inline editing started in the iframe (the parent shows the format toolbar from here).
-  | { kind: "editStart"; path: (string | number)[] }
+  // Inline editing started in the iframe (the parent shows the format toolbar from here). `prop`
+  // Names the component-instance prop when the session edits prop-bound text (plain sessions).
+  | { kind: "editStart"; path: (string | number)[]; prop?: string }
   // Committed inline-edit content (rich `children` else `textContent`) for the parent to persist.
   | {
       kind: "editCommit";
@@ -257,6 +303,13 @@ export type IframeToParent =
       children: (JxMutableNode | string)[] | null;
       textContent: string | null;
     }
+  // Committed prop-bound text: persist `value` into `$props[prop]` of the instance at `path`.
+  | {
+      kind: "editCommitProp";
+      path: (string | number)[];
+      prop: string;
+      value: string;
+    }
   // Enter split a paragraph: keep `before` in the node, insert a new one with `after`.
   | {
       kind: "editSplit";

package/src/canvas/iframe-render.ts

@@ -20,9 +20,11 @@ import {
   setCanvasViewportTranspose,
   setRootMedia,
   setSkipServerFunctions,
+  setStampPropBindings,
   transposeCanvasUnits,
 } from "@jxsuite/runtime";
 import { classifyRenderNode, serializeJxPath } from "./path-mapping";
+import { SITE_STYLE_ID, buildSiteStyleCSS } from "./site-style-css";
 import type { CanvasMode } from "./iframe-protocol";
 import type { JxDocument } from "@jxsuite/schema/types";
 import type { PathMapCtx } from "./path-mapping";
@@ -150,6 +152,18 @@ export const EDIT_PLACEHOLDER_CSS = `
   font-size: 13px;
   pointer-events: none;
 }
+[data-jx-bound-prop]:hover {
+  cursor: text;
+  outline: 1px dashed color-mix(in srgb, #808080 40%, transparent);
+  outline-offset: 1px;
+}
+[data-jx-bound-prop]:empty:not([contenteditable="plaintext-only"]):not([contenteditable="true"])::after {
+  content: "Empty \\2014  double-click to edit";
+  color: color-mix(in srgb, #808080 40%, transparent);
+  font-style: italic;
+  font-size: 13px;
+  pointer-events: none;
+}
 `;
 
 /**
@@ -281,22 +295,42 @@ export function syncStylebookCss(doc: Document, mode: CanvasMode): void {
   doc.head.append(style);
 }
 
-/** Apply the project's site style: custom properties on :root, plain properties on <body>. */
-export function applySiteStyle(siteStyle: Record<string, unknown> | null | undefined): void {
+/**
+ * Apply the project's site style as a real stylesheet (replace-in-place): custom properties on
+ * `:root`, plain properties on `body`, conditional blocks dual-emitted per the forced-scheme
+ * contract. A stylesheet — not inline root properties — so `:root[data-color-scheme]` override
+ * selectors can win (spec §9.5), and so removed tokens can't linger on reused iframes.
+ */
+export function applySiteStyle(
+  siteStyle: Record<string, unknown> | null | undefined,
+  mediaQueries: Record<string, string> = {},
+): void {
+  const existing = document.head.querySelector(`#${SITE_STYLE_ID}`);
   if (!siteStyle || typeof siteStyle !== "object") {
+    existing?.remove();
     return;
   }
-  const rootStyle = document.documentElement.style;
-  const bodyStyle = document.body.style as unknown as Record<string, string>;
-  for (const [key, value] of Object.entries(siteStyle)) {
-    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
-      continue;
-    }
-    if (key.startsWith("--")) {
-      rootStyle.setProperty(key, transposeCanvasUnits(String(value)));
-    } else {
-      bodyStyle[key] = transposeCanvasUnits(String(value));
-    }
+  const css = buildSiteStyleCSS(siteStyle, mediaQueries, transposeCanvasUnits);
+  if (existing) {
+    existing.textContent = css;
+    return;
+  }
+  const tag = document.createElement("style");
+  tag.id = SITE_STYLE_ID;
+  tag.textContent = css;
+  document.head.append(tag);
+}
+
+/**
+ * Force or clear the color-scheme preview on the iframe's root element (the platform's
+ * data-color-scheme contract, spec §9.5). Survives re-renders and patches — renders only replace
+ * the container's children, never the root element.
+ */
+export function applyPreviewColorScheme(doc: Document, scheme: "light" | "dark" | null): void {
+  if (scheme) {
+    doc.documentElement.dataset.colorScheme = scheme;
+  } else {
+    delete doc.documentElement.dataset.colorScheme;
   }
 }
 
@@ -425,7 +459,12 @@ export async function renderResolvedDocument(opts: {
   // De-link `<a href>` in design/edit so clicks select the anchor instead of navigating the iframe;
   // Preview keeps real links live (mirrors the server-function gate above).
   setCanvasDelinkAnchors(opts.mode !== "preview");
-  applySiteStyle(opts.siteStyle);
+  // Stamp `data-jx-bound-prop` on component-internal invertible text bindings in design/edit only —
+  // The inline prop-edit affordance. Set every render so a preview/stylebook render in the same
+  // Iframe clears it (page-level templates are inert in design/edit via prepareForEditMode, so only
+  // Component internals get stamped).
+  setStampPropBindings(opts.mode === "design" || opts.mode === "edit");
+  applySiteStyle(opts.siteStyle, (opts.doc as { $media?: Record<string, string> }).$media ?? {});
   injectHead(opts.doc);
   syncEditModeCss(opts.container.ownerDocument, opts.mode);
   syncStylebookCss(opts.container.ownerDocument, opts.mode);

package/src/canvas/site-style-css.ts

@@ -0,0 +1,121 @@
+/// <reference lib="dom" />
+/**
+ * Site-style stylesheet builder — pure functions extracted for testability.
+ *
+ * The canvas iframe injects the project's `style` as a real stylesheet instead of inline properties
+ * on the root element: inline custom properties would defeat the forced-scheme override selectors
+ * (`:root[data-color-scheme]`, spec §9.5), and object-valued `@--name` blocks used to be dropped
+ * entirely. Scheme-query blocks dual-emit through the runtime's schemeSelectors so the canvas
+ * honors both the OS preference and the preview toggle.
+ */
+
+import { pureSchemeOf, schemeSelectors, camelToKebab } from "@jxsuite/runtime";
+
+/** Id of the injected site-style tag (replace-in-place, never accumulate). */
+export const SITE_STYLE_ID = "jx-site-style";
+
+/** Serialize scalar declarations, kebab-casing property names and transposing values. */
+function toDecls(props: Record<string, unknown>, transpose: (value: string) => string): string {
+  return Object.entries(props)
+    .map(([key, value]) => `${camelToKebab(key)}: ${transpose(String(value))}`)
+    .join("; ");
+}
+
+/**
+ * Build the site-style sheet text: custom properties on `:root`, plain properties on `body`,
+ * conditional `@`-blocks resolved against `mediaQueries` (scheme queries dual-emitted per the
+ * forced-scheme contract), and `color-scheme: light dark` declared when a scheme query exists.
+ *
+ * @param {Record<string, unknown>} siteStyle
+ * @param {Record<string, string>} mediaQueries
+ * @param {(value: string) => string} transpose - Unit transposer (canvas vh→cqh etc.)
+ * @returns {string}
+ */
+export function buildSiteStyleCSS(
+  siteStyle: Record<string, unknown>,
+  mediaQueries: Record<string, string>,
+  transpose: (value: string) => string,
+): string {
+  const rules: string[] = [];
+  const rootProps: Record<string, unknown> = {};
+  const bodyProps: Record<string, unknown> = {};
+  const condBlocks: [string, Record<string, unknown>][] = [];
+
+  for (const [key, value] of Object.entries(siteStyle)) {
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+      if (key.startsWith("@")) {
+        condBlocks.push([key, value as Record<string, unknown>]);
+      }
+      // Non-@ objects (nested element selectors) are page-content styling — the resolved doc's
+      // Own style pass covers those; the site sheet handles tokens + conditional overrides.
+      continue;
+    }
+    if (key.startsWith(":") || key.startsWith(".") || key.startsWith("[") || key.startsWith("@")) {
+      continue;
+    }
+    if (key.startsWith("--")) {
+      rootProps[key] = value;
+    } else {
+      bodyProps[key] = value;
+    }
+  }
+
+  const rootCSS = toDecls(rootProps, transpose);
+  if (rootCSS) {
+    rules.push(`:root { ${rootCSS} }`);
+  }
+  const bodyCSS = toDecls(bodyProps, transpose);
+  if (bodyCSS) {
+    rules.push(`body { ${bodyCSS} }`);
+  }
+
+  for (const [atKey, block] of condBlocks) {
+    const query = atKey.startsWith("@--")
+      ? (mediaQueries[atKey.slice(1)] ?? atKey.slice(1))
+      : atKey.startsWith("@(")
+        ? atKey.slice(1)
+        : null;
+    if (query === null) {
+      continue;
+    }
+    const scheme = pureSchemeOf(query);
+    const emit = (selector: string, props: string) => {
+      if (!props) {
+        return;
+      }
+      if (scheme) {
+        const { auto, forced } = schemeSelectors(selector, scheme);
+        rules.push(`@media ${query} { ${auto} { ${props} } }`, `${forced} { ${props} }`);
+      } else {
+        rules.push(`@media ${query} { ${selector} { ${props} } }`);
+      }
+    };
+    const condRoot: Record<string, unknown> = {};
+    const condBody: Record<string, unknown> = {};
+    const condSubs: [string, Record<string, unknown>][] = [];
+    for (const [k, v] of Object.entries(block)) {
+      if (v !== null && typeof v === "object" && !Array.isArray(v)) {
+        if (!k.startsWith("@")) {
+          condSubs.push([k, v as Record<string, unknown>]);
+        }
+        continue;
+      }
+      if (k.startsWith("--")) {
+        condRoot[k] = v;
+      } else {
+        condBody[k] = v;
+      }
+    }
+    emit(":root", toDecls(condRoot, transpose));
+    emit("body", toDecls(condBody, transpose));
+    for (const [sel, sub] of condSubs) {
+      emit(sel, toDecls(sub, transpose));
+    }
+  }
+
+  if (Object.values(mediaQueries).some((q) => pureSchemeOf(q) !== null)) {
+    rules.push(":root { color-scheme: light dark }");
+  }
+
+  return rules.join("\n");
+}

package/src/collab/collab-session.ts

@@ -7,8 +7,14 @@
  * before-image). Inbound: remote Y transactions convert back into JxDocOps and replay through
  * `applyExternalDocOps`, riding the surgical canvas patcher; unconvertible shapes hard-reconcile
  * the tab from the Y tree. Undo becomes a local-origin-scoped Y.UndoManager registered as the tab's
- * history delegate. While attached, the shared session persists automatically: `dirty` stays false
- * and Cmd+S becomes a serialize→flush.
+ * history delegate.
+ *
+ * Saving is EXPLICIT even while attached: syncing edits to peers (the Y.Doc) is automatic, but
+ * folding the shared source to disk is not. Local edits mark `tab.doc.dirty` immediately for
+ * instant Save-button feedback; the room-level, server-authoritative unsaved state then arrives via
+ * `handle.onDirty` (any peer's edit dirties the room for everyone; a save clears it for everyone).
+ * Cmd+S / Save runs a serialize→mirror→flush, and the provider broadcasts the room clean once the
+ * write lands.
  *
  * All yjs code sits behind a dynamic import: the unsplit bundle inlines the bytes, but module
  * evaluation defers until a collab session actually attaches.
@@ -177,17 +183,18 @@ function onTransact(tab: Tab, record: TransactionRecord, origin: TransactOrigin)
   }
   session.lastSeenRef = toRaw(tab.doc.document) as object;
   if (origin === "remote") {
-    // The reconciler keeps source text fresh regardless of WHO edited the structure.
+    // The reconciler keeps source text fresh regardless of WHO edited the structure. The tab's
+    // Dirty state is driven by the server's room-level `doc-dirty` broadcast (see onDirty in
+    // CreateSession), not forced here.
     scheduleMirror(session);
-    tab.doc.dirty = false;
     return;
   }
   if (session.canWrite) {
     publishRecord(session, record);
     scheduleMirror(session);
   }
-  // The shared session persists automatically; the dirty dot means "unsaved" and stays off.
-  tab.doc.dirty = false;
+  // Local edits leave the tab dirty (transactDoc already set it) until an explicit save flushes and
+  // The provider broadcasts the room clean.
 }
 
 function onBatchEnd(tab: Tab): void {
@@ -673,7 +680,15 @@ function createSession(
     });
   }
   session.lastSeenRef = toRaw(tab.doc.document) as object;
-  tab.doc.dirty = false;
+
+  // The server owns the room-level unsaved state: `onDirty` fires synchronously with the current
+  // Value on subscribe (delivered during the open handshake), so attaching to a clean room clears
+  // Any dirty the initial reconcile set, and attaching to an already-dirty room shows dirty.
+  session.disposers.push(
+    handle.onDirty((dirty) => {
+      tab.doc.dirty = dirty;
+    }),
+  );
 
   // Presence identity + write capability (drives reconciler election).
   handle.awareness.setLocalState({
@@ -864,7 +879,7 @@ function createSession(
         session.lastSeenRef = nowRef;
         publishDiff(session);
         scheduleMirror(session);
-        tab.doc.dirty = false;
+        // Dirty stays as the edit left it; the server's doc-dirty broadcast is authoritative.
       });
     });
   });

package/src/collab/collab-state.ts

@@ -4,7 +4,7 @@
  * fs-sync/reload guards without importing the session machinery.
  */
 
-import { reactive } from "../reactivity";
+import { reactive, toRaw } from "../reactivity";
 import type { Tab } from "../tabs/tab";
 import type { CollabAwarenessState } from "@jxsuite/collab/awareness-types";
 
@@ -33,7 +33,10 @@ const states = new WeakMap<Tab, TabCollabState>();
 const attachedPaths = new Map<string, number>();
 
 export function collabState(tab: Tab): TabCollabState {
-  let state = states.get(tab);
+  // Key on the raw tab: writers (the collab session, via ensureCollab's raw tab) and readers
+  // (toolbar/tab-strip, via reactive `workspace.tabs.get` proxies) must resolve the same entry.
+  const key = toRaw(tab as unknown as object) as Tab;
+  let state = states.get(key);
   if (!state) {
     state = reactive({
       active: false,
@@ -42,7 +45,7 @@ export function collabState(tab: Tab): TabCollabState {
       sourceCanonical: false,
       status: "detached",
     }) as TabCollabState;
-    states.set(tab, state);
+    states.set(key, state);
   }
   return state;
 }

package/src/component-props.ts

@@ -0,0 +1,104 @@
+/**
+ * Component test props (M6) — the previewParams mirror for component docs. A non-instantiated
+ * component definition renders on the canvas with its state defaults; "test values" let the author
+ * pick per-prop values that the canvas render seeds into the definition's state, so templates,
+ * dataScope snapshots, and live/snapshot expression previews all see real data.
+ *
+ * Pure and DOM-free: {@link componentPropEntries} derives the editable prop rows from the doc's
+ * state (the same plain-data entries the CEM export publishes as fields), and
+ * {@link substitutePreviewProps} rebuilds a render doc with chosen values seeded — never mutating
+ * the source document (the substitutePreviewParams contract).
+ */
+
+import type { JsonValue } from "./types";
+import type { JxMutableNode } from "@jxsuite/schema/types";
+
+/** One editable prop row: the state key and its current default value (undefined = none). */
+export interface ComponentPropEntry {
+  name: string;
+  value: JsonValue | undefined;
+}
+
+/** Whether the doc is a component definition (a custom-element root) rather than a page. */
+export function isComponentDoc(doc: JxMutableNode | null | undefined): boolean {
+  return typeof doc?.tagName === "string" && doc.tagName.includes("-");
+}
+
+/**
+ * Classify a state entry as a prop (plain data the CEM export publishes as a field): naked
+ * literals/arrays/objects and expanded/typed signal defs — never expressions, computeds, functions,
+ * templates, or $prototype data sources (overriding those would clobber behavior, the boundPropKey
+ * rule).
+ */
+function propShape(def: unknown): "literal" | "signal" | null {
+  if (def === null || typeof def === "number" || typeof def === "boolean") {
+    return "literal";
+  }
+  if (typeof def === "string") {
+    return def.includes("${") ? null : "literal"; // Template strings render computed values.
+  }
+  if (Array.isArray(def)) {
+    return "literal";
+  }
+  if (typeof def === "object") {
+    const d = def as Record<string, unknown>;
+    if (d.$expression || d.$compute || d.$prototype || d.$handler) {
+      return null;
+    }
+    // An expanded signal ({default}) or a typed prop def ({type}/schema keywords) seeds through
+    // Its `default`; any other plain object is a Shape-1 naked value.
+    return "default" in d || "type" in d ? "signal" : "literal";
+  }
+  return null;
+}
+
+/**
+ * The component's editable prop entries, derived from the doc's state — non-private plain-data
+ * entries with their current default values (the CEM-export "field" subset).
+ */
+export function componentPropEntries(doc: JxMutableNode | null | undefined): ComponentPropEntry[] {
+  const state = (doc?.state ?? {}) as Record<string, unknown>;
+  const out: ComponentPropEntry[] = [];
+  for (const [name, def] of Object.entries(state)) {
+    if (name.startsWith("#")) {
+      continue; // Private entries are not props (the CEM-export rule).
+    }
+    const shape = propShape(def);
+    if (!shape) {
+      continue;
+    }
+    const value =
+      shape === "signal"
+        ? ((def as { default?: JsonValue }).default as JsonValue | undefined)
+        : (def as JsonValue);
+    out.push({ name, value });
+  }
+  return out;
+}
+
+/**
+ * Rebuild `renderDoc` with the chosen test-prop values seeded into its state: a literal entry is
+ * replaced by the value; a signal/typed entry keeps its metadata and gets the value as `default`
+ * (exactly what buildScope reads). Pure — returns a shallow rebuild; the render doc shares node
+ * references with the tab's source document, so in-place mutation would corrupt the edited doc.
+ */
+export function substitutePreviewProps(
+  renderDoc: JxMutableNode,
+  props: Record<string, JsonValue>,
+): JxMutableNode {
+  const state = { ...((renderDoc.state ?? {}) as Record<string, unknown>) };
+  let seeded = false;
+  for (const [name, value] of Object.entries(props)) {
+    const shape = propShape(state[name]);
+    if (!shape) {
+      continue; // Unknown/behavioral entries are never overridden by a stale test value.
+    }
+    state[name] =
+      shape === "signal" ? { ...(state[name] as Record<string, unknown>), default: value } : value;
+    seeded = true;
+  }
+  if (!seeded) {
+    return renderDoc;
+  }
+  return { ...renderDoc, state } as JxMutableNode;
+}

package/src/editor/inline-edit-apply.ts

@@ -9,7 +9,12 @@
 
 import { childIndex, getNodeAtPath, parentElementPath } from "../store";
 import { isTabActive } from "../workspace/workspace";
-import { mutateInsertNode, mutateUpdateProperty, transactDoc } from "../tabs/transact";
+import {
+  mutateInsertNode,
+  mutateUpdateProp,
+  mutateUpdateProperty,
+  transactDoc,
+} from "../tabs/transact";
 import { defaultDef } from "../panels/shared";
 
 import type { JxContentResult, SlashCommand } from "./inline-edit";
@@ -83,6 +88,36 @@ export function applyInlineCommit(
   }
 }
 
+/**
+ * Commit a prop-bound inline edit: persist `value` into `$props[prop]` of the component instance at
+ * `path`. The unchanged-value no-op is LOAD-BEARING, not cosmetic: Escape-cancel and
+ * patch-disturbed sessions post unchanged values, and without the equality check a commit→patch→
+ * disturb→re-commit cycle loops (and pollutes undo history). An empty value deletes the prop
+ * (mutateUpdateProp), reverting the instance to the definition default — same as clearing the
+ * sidebar field.
+ */
+export function applyInlinePropCommit(
+  tab: Tab | null,
+  path: JxPath,
+  prop: string,
+  value: string,
+): void {
+  if (!tab) {
+    return;
+  }
+  const node = getNodeAtPath(tab.doc.document, path);
+  if (!node) {
+    return;
+  }
+  const current = (node.$props as Record<string, unknown> | undefined)?.[prop];
+  if (`${current ?? ""}` === value) {
+    return;
+  }
+  transactDoc(tab, (t) => {
+    mutateUpdateProp(t, path, prop, value);
+  });
+}
+
 /**
  * Apply a paragraph split to `tab`'s document: keep `before` in the node, insert a new `<p>` with
  * `after`. Returns its path (unchanged when `tab` is gone — the caller may still use it for