@jxsuite/studio 1.0.0 → 1.1.0

package/src/canvas/iframe-host.ts

@@ -12,6 +12,7 @@ import { canvasBaseOrigin } from "./canvas-origin";
 import { resolveCanvasDocument } from "./canvas-live-render";
 import {
   applyInlineCommit,
+  applyInlinePropCommit,
   applyInlineInsert,
   applyInlineSplit,
 } from "../editor/inline-edit-apply";
@@ -31,6 +32,7 @@ import type {
   ApplyFormatIntent,
   CanvasMode,
   DragSrcKind,
+  EvalExprResult,
   IframeToParent,
   InsertZone,
   NodeHit,
@@ -43,13 +45,15 @@ import type { IframeChannel } from "./iframe-channel";
 import type { OverlayLayer, OverlayPlacement } from "./iframe-overlay";
 import type { SlashCommand } from "../editor/inline-edit";
 import type { Tab } from "../tabs/tab";
-import type { JxMutableNode } from "@jxsuite/schema/types";
+import type { JxExpressionNode, JxMutableNode } from "@jxsuite/schema/types";
 
 /** A rect in PARENT coordinates (overlay-local from {@link canvasRectToParent}, same field shape). */
 type ParentRect = OverlayPlacement;
 
 interface HostState {
   iframe: HTMLIFrameElement;
+  /** The `.canvas-panel-canvas` element hosting the iframe + overlay (the WeakMap key). */
+  canvasEl: HTMLElement;
   channel: IframeChannel<ParentToIframe, IframeToParent>;
   /**
    * The resolved canvasUrl this iframe was built with — so a host built early with the default URL
@@ -70,6 +74,8 @@ interface HostState {
   presenceMeta: Map<string, { color: string; label: string }>;
   /** Whether an inline-edit session is live in this host's iframe (drives the format toolbar). */
   editing: boolean;
+  /** The prop a live plain session edits (prop-bound text) — null for rich sessions/none. */
+  editingProp: string | null;
   /** The latest selection snapshot from this host's iframe (active tags + caret rect + link). */
   snapshot: SelectionSnapshot | null;
   /** Highest snapshot `seq` seen, so stale (re-ordered) snapshots are dropped. */
@@ -176,6 +182,72 @@ export function sawIframeDragOver(seq: number): boolean {
   );
 }
 
+// ─── Live expression preview (M6) ───────────────────────────────────────────────
+// The parent asks a live iframe to evaluate expression nodes against its LIVE resolved scope and
+// Correlates the `evalResult` reply by reqId (the measure/geometry precedent), gen-gating it so a
+// Reply computed against a superseded render never paints badges.
+
+/** Monotonic eval request id (shared across hosts; stale replies carry an older/unknown id). */
+let evalReqId = 0;
+
+/** Pending eval resolvers keyed by reqId; a timeout or stale reply resolves null. */
+const pendingEvals = new Map<number, (results: EvalExprResult[] | null) => void>();
+
+/** How long (ms) the parent waits for an `evalResult` before falling back to the snapshot. */
+export const EVAL_TIMEOUT_MS = 300;
+
+/**
+ * Post an `evalExpr` request to the live, ready iframe host rendering `tabId`'s document and
+ * resolve with its results. Resolves `null` when no such host exists (caller falls back to the
+ * snapshot evaluator immediately), when no reply lands within `timeoutMs`, or when the reply's gen
+ * shows it was computed against a superseded render.
+ */
+export function requestCanvasEval(
+  tabId: string | null,
+  exprs: { id: string; node: unknown }[],
+  contextPath: (string | number)[] | null,
+  timeoutMs: number = EVAL_TIMEOUT_MS,
+): Promise<EvalExprResult[] | null> {
+  let target: HostState | null = null;
+  for (const host of liveHosts) {
+    if (!host.iframe.isConnected) {
+      liveHosts.delete(host);
+      continue;
+    }
+    // Only a document host can answer (never a stylebook specimen catalog or a null-tab override
+    // Doc like git-diff), and only the one whose iframe DOM reflects this tab's document.
+    if (host.ready && !host.stylebook && tabId !== null && host.tabId === tabId) {
+      target = host;
+      break;
+    }
+  }
+  if (!target) {
+    return Promise.resolve(null);
+  }
+  evalReqId += 1;
+  const reqId = evalReqId;
+  // Expression nodes come off the reactive document — only plain values may cross postMessage.
+  // oxlint-disable-next-line unicorn/prefer-structured-clone
+  const wireExprs = JSON.parse(JSON.stringify(exprs)) as { id: string; node: JxExpressionNode }[];
+  target.channel.post({
+    contextPath: contextPath ? [...contextPath] : null,
+    exprs: wireExprs,
+    gen: target.lastRenderedGen,
+    kind: "evalExpr",
+    reqId,
+  });
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      pendingEvals.delete(reqId);
+      resolve(null);
+    }, timeoutMs);
+    pendingEvals.set(reqId, (results) => {
+      clearTimeout(timer);
+      resolve(results);
+    });
+  });
+}
+
 /** The host backing a given canvas element (or null), for the coordinator's host resolution. */
 export function hostForCanvas(canvasEl: HTMLElement): HostState | null {
   return hosts.get(canvasEl) ?? null;
@@ -263,6 +335,25 @@ export function hostDragGeometry(host: HostState): {
   return { rect, scale };
 }
 
+/**
+ * Pin the `.canvas-panel-viewport` (the white "page" surface, the canvas element's parent) to the
+ * SCALED content height when edit-mode content zoom is active. A `transform: scale()` on the canvas
+ * element rescales its painted box but never its ancestor's auto-height, so without this write the
+ * viewport background would stay sized to the UN-zoomed iframe height. The scale is read from the
+ * canvas element's own inline transform (written only by `applyEditZoom`) — NOT from
+ * {@link hostDragGeometry}, whose empirical ratio also reflects design mode's panzoom-wrap
+ * transform, where the viewport must keep its unscaled auto height.
+ */
+function syncEditZoomViewportHeight(state: HostState): void {
+  const viewport = state.canvasEl.parentElement;
+  if (!viewport) {
+    return;
+  }
+  const match = /scale\(([\d.]+)\)/.exec(state.canvasEl.style.transform);
+  const scale = match ? Number(match[1]!) : 1;
+  viewport.style.height = scale === 1 ? "" : `${state.iframe.offsetHeight * scale}px`;
+}
+
 /** Post a parent→iframe drag message to `host`'s channel (the coordinator builds it purely). */
 export function postDragMessage(host: HostState, msg: ParentToIframe): void {
   if (!host.iframe.isConnected) {
@@ -662,9 +753,11 @@ function ensureHost(canvasEl: HTMLElement): HostState {
   });
 
   const state: HostState = {
+    canvasEl,
     canvasUrl,
     channel,
     editing: false,
+    editingProp: null,
     iframe,
     insertHideTimer: null,
     insertZone: null,
@@ -875,6 +968,18 @@ function handleMessage(state: HostState, msg: IframeToParent): void {
       }
       return;
     }
+    case "evalResult": {
+      // A live expression-preview reply (M6). Resolve the pending request by reqId (unknown ids —
+      // Already timed out or from a torn-down request — are dropped), gen-gating it so values
+      // Computed against a superseded render resolve null (the caller keeps the snapshot preview).
+      const resolve = pendingEvals.get(msg.reqId);
+      if (!resolve) {
+        return;
+      }
+      pendingEvals.delete(msg.reqId);
+      resolve(msg.gen === state.lastRenderedGen ? msg.results : null);
+      return;
+    }
     case "renderComplete": {
       // Adopt the tab identity this render was mounted with. host.tabId flips ONLY here — after any
       // Edit-session commit the iframe posted ahead of this ack on the FIFO channel — so a commit
@@ -922,6 +1027,7 @@ function handleMessage(state: HostState, msg: IframeToParent): void {
       // Component leaves dead space below — pages keep the floor and stay tall via #jx-canvas-root).
       state.iframe.style.height = `${msg.height}px`;
       state.iframe.style.minHeight = msg.fragment ? "0px" : "480px";
+      syncEditZoomViewportHeight(state);
       return;
     }
     case "dragOver": {
@@ -1025,10 +1131,12 @@ function handleMessage(state: HostState, msg: IframeToParent): void {
       // Tear down any other host's editing state and make this the single active edit host.
       if (activeEditHost && activeEditHost !== state) {
         activeEditHost.editing = false;
+        activeEditHost.editingProp = null;
         activeEditHost.snapshot = null;
       }
       activeEditHost = state;
       state.editing = true;
+      state.editingProp = msg.prop ?? null;
       state.snapshot = null;
       state.lastSnapshotSeq = 0;
       toolbarRefresh?.();
@@ -1050,6 +1158,12 @@ function handleMessage(state: HostState, msg: IframeToParent): void {
       applyInlineCommit(hostTab(state), msg.path, msg.children, msg.textContent);
       return;
     }
+    case "editCommitProp": {
+      // A prop-bound plain session committed: persist into the instance's $props (same host-tab
+      // Routing as editCommit; the unchanged-value no-op lives in the apply).
+      applyInlinePropCommit(hostTab(state), msg.path, msg.prop, msg.value);
+      return;
+    }
     case "editSplit": {
       // The mutation lands now (surgical patch or escalated render); re-entry on the new paragraph
       // Is deferred until this host acks the DOM that contains it (see deferEnterEdit).
@@ -1109,6 +1223,7 @@ function handleMessage(state: HostState, msg: IframeToParent): void {
         return;
       }
       state.editing = false;
+      state.editingProp = null;
       state.snapshot = null;
       if (activeEditHost === state) {
         activeEditHost = null;
@@ -1381,11 +1496,19 @@ export function getActiveEditHost(): HostState | null {
 }
 
 /** The current edit session's editing flag + latest selection snapshot, for the parent toolbar. */
-export function getEditSnapshot(): { editing: boolean; snapshot: SelectionSnapshot | null } {
+export function getEditSnapshot(): {
+  editing: boolean;
+  editingProp: string | null;
+  snapshot: SelectionSnapshot | null;
+} {
   if (!activeEditHost) {
-    return { editing: false, snapshot: null };
+    return { editing: false, editingProp: null, snapshot: null };
   }
-  return { editing: activeEditHost.editing, snapshot: activeEditHost.snapshot };
+  return {
+    editing: activeEditHost.editing,
+    editingProp: activeEditHost.editingProp,
+    snapshot: activeEditHost.snapshot,
+  };
 }
 
 /** Post an `applyFormat` intent to the active edit host's iframe (no-op when none/not ready). */
@@ -1423,7 +1546,10 @@ function hostForActivePanel(): HostState | null {
  * UNSCALED iframe-viewport px (D-2: the overlay draws them inside the scaled panzoom-wrap, so the
  * browser applies the zoom there); the fixed bar gets no such free ride, so scale by the live
  * empirical zoom ({@link hostDragGeometry}) and add the iframe's on-screen offset, whose GBCR
- * already bakes in pan + zoom + ancestor scroll. Edit mode has no transform → scale is 1.
+ * already bakes in pan + zoom + ancestor scroll. The empirical ratio covers BOTH scale sources:
+ * design mode's panzoom-wrap transform and edit mode's content-zoom counter-scale (where it
+ * evaluates to exactly `editZoom` — the iframe's layout width is `renderWidth / editZoom` while its
+ * rendered width is `renderWidth`).
  */
 export function getEditBarAnchorRect(): ParentRect | null {
   // The format toolbar follows the live caret/selection snapshot of the active edit session; the

package/src/canvas/iframe-inline-edit.ts

@@ -33,6 +33,7 @@ import { isTagActiveInSelection, toggleInlineFormat } from "../editor/inline-for
 import { applyLink, insertTemplateToken, linkStateForSelection } from "../editor/inline-link";
 import { restoreTemplateExpressions } from "../utils/edit-display";
 import { rectOfRange } from "../utils/geometry";
+import { getNodeAtPath } from "../state";
 import { parseJxPath, serializeJxPath } from "./path-mapping";
 import type { IframeChannel } from "./iframe-channel";
 import type {
@@ -43,6 +44,7 @@ import type {
   SerializableRect,
 } from "./iframe-protocol";
 import type { JxPath } from "../state";
+import type { JxMutableNode } from "@jxsuite/schema/types";
 
 /** Toolbar command → inline tag (mirrors the parent's old `cmdToTag`, now iframe-side). */
 const CMD_TO_TAG: Record<string, string> = {
@@ -74,6 +76,43 @@ function findEditableTarget(target: EventTarget | null): { el: HTMLElement; path
   return null;
 }
 
+/**
+ * Walk up from an event target to the nearest element carrying `data-jx-bound-prop` (a component-
+ * internal element whose text is an invertible prop binding — stamped by the runtime, see
+ * setStampPropBindings). Component internals are unstamped, so hitting a `data-jx-path` element
+ * first means the target sits in page-level DOM (or slotted content) — not a prop-bound target.
+ */
+function findPropBoundTarget(target: EventTarget | null): { el: HTMLElement; prop: string } | null {
+  let el = target instanceof Element ? target : null;
+  while (el) {
+    if (el instanceof HTMLElement) {
+      if (el.dataset.jxBoundProp) {
+        return { el, prop: el.dataset.jxBoundProp };
+      }
+      if (el.dataset.jxPath) {
+        return null;
+      }
+    }
+    el = el.parentElement;
+  }
+  return null;
+}
+
+/**
+ * The instance that owns a prop-bound element: its nearest custom-element ancestor (that element's
+ * connectedCallback rendered the marker with its state, so the walk can never skip the owner).
+ */
+function ownerInstanceOf(el: HTMLElement): HTMLElement | null {
+  let cur = el.parentElement;
+  while (cur) {
+    if (cur.tagName.includes("-")) {
+      return cur;
+    }
+    cur = cur.parentElement;
+  }
+  return null;
+}
+
 /** Locate the rendered element for a document path via its stamped `data-jx-path`. */
 function elementForPath(container: HTMLElement, path: JxPath): HTMLElement | null {
   const serialized = serializeJxPath(path);
@@ -95,7 +134,7 @@ function toSerializableRect(rect: DOMRect): SerializableRect {
 export function startIframeInlineEdit(
   channel: IframeChannel<IframeToParent, ParentToIframe>,
   container: HTMLElement,
-  opts?: { getMode?: () => string },
+  opts?: { getMode?: () => string; getShadowDoc?: () => JxMutableNode | null },
 ): () => void {
   const doc = container.ownerDocument;
 
@@ -251,6 +290,56 @@ export function startIframeInlineEdit(
     onSelectionChange();
   };
 
+  /**
+   * Whether the instance's RAW `$props[prop]` value (from the pre-edit-display shadow doc) is
+   * plain-text editable. Template-valued (`"${...}"`) and `$ref`-valued props render display sugar,
+   * not the value — committing typed text would silently destroy the binding, so they're blocked.
+   * An absent getShadowDoc is permissive (tests, same contract as getMode).
+   */
+  const propEditableAt = (hostPath: JxPath, prop: string): boolean => {
+    const shadowDoc = opts?.getShadowDoc?.();
+    if (!shadowDoc) {
+      return true;
+    }
+    const node = getNodeAtPath(shadowDoc, hostPath) as JxMutableNode | undefined;
+    const raw = (node?.$props as Record<string, unknown> | undefined)?.[prop];
+    if (raw == null) {
+      return true; // Unset — editing ADDS the prop, overriding the definition default.
+    }
+    if (typeof raw === "object") {
+      return false;
+    }
+    return !(typeof raw === "string" && raw.includes("${"));
+  };
+
+  /**
+   * Enter a plain (plaintext-only) session on a prop-bound component-internal element. The session
+   * path is the INSTANCE path — the marker element has no path of its own, and an external `$props`
+   * patch at the host path must disturb (commit + end) this session before detaching its element.
+   */
+  const enterPropEditAt = (el: HTMLElement, hostPath: JxPath, prop: string) => {
+    channel.post({ kind: "editStart", path: hostPath, prop });
+    suspendBlurClose();
+    startEditing(
+      el,
+      hostPath,
+      {
+        onCommit: (p, _children, textContent) =>
+          channel.post({ kind: "editCommitProp", path: p, prop, value: textContent ?? "" }),
+        onEnd: () => {
+          resumeBlurClose();
+          clearHighlight();
+          lastNonEmptyRange = null;
+          channel.post({ kind: "editEnd" });
+        },
+        // Prop values are single plain strings — no split, no slash-insert.
+        onInsert: () => {},
+        onSplit: () => {},
+      },
+      { plainText: true },
+    );
+  };
+
   /** Apply a format/link/insert intent to the iframe's cached selection range. */
   const applyFormatIntent = (intent: ApplyFormatIntent) => {
     const el = getActiveElement();
@@ -290,6 +379,23 @@ export function startIframeInlineEdit(
     if (!editingAllowed()) {
       return;
     }
+    // Prop-bound targets win: they sit in unstamped component internals, deeper than any editable
+    // Page block, and once a marker is hit the event must NOT fall through to rich editing (an
+    // Instance nested inside a page-level editable would otherwise rich-edit that whole ancestor).
+    const propHit = findPropBoundTarget(e.target);
+    if (propHit) {
+      const host = ownerInstanceOf(propHit.el);
+      const hostPathRaw = host?.dataset.jxPath;
+      if (host && hostPathRaw) {
+        const hostPath = parseJxPath(hostPathRaw);
+        if (propEditableAt(hostPath, propHit.prop)) {
+          enterPropEditAt(propHit.el, hostPath, propHit.prop);
+        }
+      }
+      // A path-less host is itself internal to another definition — its $props live in a document
+      // Not open in this tab, so there is no write-back target: blocked.
+      return;
+    }
     const hit = findEditableTarget(e.target);
     if (hit) {
       enterEditAt(hit.el, hit.path);

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
@@ -110,6 +110,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 +140,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 +257,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 +280,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 +290,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,6 +20,7 @@ import {
   setCanvasViewportTranspose,
   setRootMedia,
   setSkipServerFunctions,
+  setStampPropBindings,
   transposeCanvasUnits,
 } from "@jxsuite/runtime";
 import { classifyRenderNode, serializeJxPath } from "./path-mapping";
@@ -150,6 +151,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;
+}
 `;
 
 /**
@@ -425,6 +438,11 @@ 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");
+  // 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);
   injectHead(opts.doc);
   syncEditModeCss(opts.container.ownerDocument, opts.mode);

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;
 }