@jxsuite/studio 0.36.0 → 0.37.0

package/src/collab/collab-state.ts

@@ -0,0 +1,71 @@
+/**
+ * Reactive per-tab collab state, kept OUTSIDE the Tab type: UI reads it through collabState(tab),
+ * and non-collab builds never touch it. The path registry answers "is this file co-edited?" for the
+ * fs-sync/reload guards without importing the session machinery.
+ */
+
+import { reactive } from "../reactivity";
+import type { Tab } from "../tabs/tab";
+import type { CollabAwarenessState } from "@jxsuite/collab/awareness-types";
+
+export type CollabTabStatus = "detached" | "connecting" | "synced" | "offline";
+
+export interface PeerPresence {
+  clientId: number;
+  state: CollabAwarenessState;
+}
+
+export interface TabCollabState {
+  status: CollabTabStatus;
+  /** True once a session is attached and past its initial sync. */
+  active: boolean;
+  readOnly: boolean;
+  /** Other clients' awareness states (this project connection, all docs). */
+  peers: PeerPresence[];
+  /**
+   * True while source holds the canonical lock (someone is co-editing the code view): structural
+   * surfaces soft-freeze and the canvas previews the source reconciler's parses.
+   */
+  sourceCanonical: boolean;
+}
+
+const states = new WeakMap<Tab, TabCollabState>();
+const attachedPaths = new Map<string, number>();
+
+export function collabState(tab: Tab): TabCollabState {
+  let state = states.get(tab);
+  if (!state) {
+    state = reactive({
+      active: false,
+      peers: [],
+      readOnly: false,
+      sourceCanonical: false,
+      status: "detached",
+    }) as TabCollabState;
+    states.set(tab, state);
+  }
+  return state;
+}
+
+export function isCollabActive(tab: Tab): boolean {
+  return states.get(tab)?.active === true;
+}
+
+/** Track which project-relative paths have live sessions (fs-event/reload suppression). */
+export function registerCollabPath(path: string): void {
+  attachedPaths.set(path, (attachedPaths.get(path) ?? 0) + 1);
+}
+
+export function unregisterCollabPath(path: string): void {
+  const count = attachedPaths.get(path) ?? 0;
+  if (count <= 1) {
+    attachedPaths.delete(path);
+  } else {
+    attachedPaths.set(path, count - 1);
+  }
+}
+
+/** True while some tab co-edits this path — its Y.Doc is ahead of any provider write-back. */
+export function isCollabPath(path: string): boolean {
+  return attachedPaths.has(path.replaceAll("\\", "/"));
+}

package/src/collab/monaco-cursors.ts

@@ -0,0 +1,69 @@
+/**
+ * Remote cursor colors for y-monaco. MonacoBinding decorates other clients' text cursors with
+ * per-client class names (`yRemoteSelection-<id>`, `yRemoteSelectionHead-<id>`) but ships no
+ * styling — this module maintains one injected <style> element with a rule set per remote client,
+ * colored from the presence palette (`user.color`) and labeled with the author's name on hover of
+ * the cursor head.
+ */
+
+/** The slice of y-protocols Awareness the style manager uses (duck-typed; stays yjs-free). */
+export interface AwarenessLike {
+  clientID: number;
+  getStates: () => Map<number, unknown>;
+  on: (event: "change", cb: () => void) => void;
+  off: (event: "change", cb: () => void) => void;
+}
+
+interface PeerStateShape {
+  user?: { color?: string; name?: string; login?: string };
+}
+
+/** CSS-escape for the content string (names come from GitHub logins/display names). */
+function cssString(value: string): string {
+  return `"${value.replaceAll("\\", String.raw`\\`).replaceAll('"', String.raw`\"`)}"`;
+}
+
+/** One client's rules: translucent selection band, solid caret, name flag above the caret. */
+export function cursorRulesFor(clientId: number, color: string, label: string): string {
+  return [
+    `.yRemoteSelection-${clientId}{background-color:${color}44;}`,
+    `.yRemoteSelectionHead-${clientId}{position:absolute;border-left:2px solid ${color};height:100%;box-sizing:border-box;}`,
+    `.yRemoteSelectionHead-${clientId}::after{content:${cssString(label)};position:absolute;top:-1.2em;left:-2px;padding:0 4px;border-radius:3px 3px 3px 0;font:10px/1.4 sans-serif;color:#fff;white-space:nowrap;background-color:${color};opacity:0;transition:opacity .15s;pointer-events:none;}`,
+    `.yRemoteSelectionHead-${clientId}:hover::after{opacity:1;}`,
+  ].join("\n");
+}
+
+/** Full stylesheet text for every remote client with a presence identity. */
+export function cursorStylesheet(awareness: AwarenessLike): string {
+  const rules: string[] = [];
+  for (const [clientId, raw] of awareness.getStates()) {
+    if (clientId === awareness.clientID) {
+      continue;
+    }
+    const { user } = raw as PeerStateShape;
+    if (!user?.color) {
+      continue;
+    }
+    rules.push(cursorRulesFor(clientId, user.color, user.name ?? user.login ?? String(clientId)));
+  }
+  return rules.join("\n");
+}
+
+/**
+ * Keep an injected <style> element in sync with the awareness roster while a code view is bound.
+ * Returns the disposer (removes the element and the listener).
+ */
+export function attachCursorStyles(awareness: AwarenessLike, doc: Document): () => void {
+  const style = doc.createElement("style");
+  style.dataset["jxCollabCursors"] = "true";
+  doc.head.append(style);
+  const refresh = () => {
+    style.textContent = cursorStylesheet(awareness);
+  };
+  refresh();
+  awareness.on("change", refresh);
+  return () => {
+    awareness.off("change", refresh);
+    style.remove();
+  };
+}

package/src/collab/presence-chips.ts

@@ -0,0 +1,58 @@
+/**
+ * Presence chips — who else is in this co-editing session, plus the sync-status pill that replaces
+ * the dirty dot for collab tabs. Pure lit templates over collabState(tab); the toolbar includes
+ * them and its render effect tracks the underlying reactive state.
+ */
+
+import { html, nothing } from "lit-html";
+import type { TemplateResult } from "lit-html";
+import { collabState } from "./collab-state";
+import type { PeerPresence } from "./collab-state";
+import type { Tab } from "../tabs/tab";
+
+function initialOf(peer: PeerPresence): string {
+  const name = peer.state.user.name ?? peer.state.user.login;
+  return (name[0] ?? "?").toUpperCase();
+}
+
+function titleOf(peer: PeerPresence, docPath: string | null): string {
+  const { user } = peer.state;
+  const who = user.name ? `${user.name} (${user.login})` : user.login;
+  const here = peer.state.focusedPath && peer.state.focusedPath === docPath;
+  return here ? who : `${who} — ${peer.state.focusedPath ?? "browsing"}`;
+}
+
+const STATUS_LABEL: Record<string, string> = {
+  connecting: "Connecting…",
+  offline: "Offline — changes sync on reconnect",
+  synced: "Live",
+};
+
+/** Chips + status pill for the toolbar; `nothing` while the tab isn't co-editing. */
+export function presenceChipsTemplate(tab: Tab | null): TemplateResult | typeof nothing {
+  if (!tab) {
+    return nothing;
+  }
+  const state = collabState(tab);
+  if (state.status === "detached") {
+    return nothing;
+  }
+  const label = STATUS_LABEL[state.status] ?? state.status;
+  return html`
+    <div class="jx-presence" title=${label}>
+      <span class="jx-presence-status" data-status=${state.status}>${label}</span>
+      ${state.peers.map(
+        (peer) => html`
+          <span
+            class="jx-presence-chip"
+            style="background:${peer.state.user.color}"
+            title=${titleOf(peer, tab.documentPath)}
+            >${peer.state.user.avatarUrl
+              ? html`<img src=${peer.state.user.avatarUrl} alt=${initialOf(peer)} />`
+              : initialOf(peer)}</span
+          >
+        `,
+      )}
+    </div>
+  `;
+}

package/src/files/file-ops.ts

@@ -13,6 +13,7 @@ import { statusMessage } from "../panels/statusbar";
 import { validateComponentSlots } from "../services/cem-export";
 import { getPlatform } from "../platform";
 import { activeTab, openTab } from "../workspace/workspace";
+import { collabSave } from "../collab/collab-session";
 import { isEditing, stopEditing } from "../editor/inline-edit";
 import {
   defaultContentFormat,
@@ -162,6 +163,11 @@ export async function saveFile() {
     return;
   }
   try {
+    // A co-edited tab persists through its provider (a direct file write would reset the room).
+    if (await collabSave(tab)) {
+      savedMessage(tab, "Synced");
+      return;
+    }
     const output = await serializeDocument(tab);
 
     if (tab.documentPath) {

package/src/files/files.ts

@@ -20,6 +20,7 @@ import { ensureDependenciesInstalled } from "../packages/ensure-deps";
 import { maybePromptJxsuiteUpdate } from "../packages/jxsuite-update";
 import { autoSyncProjectOnOpen } from "../packages/pull-package-sync";
 import { markLocalMutation } from "./fs-events";
+import { isCollabPath } from "../collab/collab-state";
 import {
   draggable,
   dropTargetForElements,
@@ -1078,6 +1079,11 @@ export async function openFileInTab(path: string) {
  */
 /** Reload an open tab from disk when an external change arrives — but only if it is not dirty. */
 export function reloadCleanTab(path: string): void {
+  // Co-edited docs never reload from disk: the shared Y.Doc is ahead of the provider's write-back
+  // (Which is what produced this event), and genuine external changes arrive as a collab reset.
+  if (isCollabPath(path)) {
+    return;
+  }
   for (const [, tab] of workspace.tabs.entries()) {
     if (tab.documentPath === path && !tab.doc.dirty) {
       void reloadFileInTab(path);

package/src/panels/git-panel.ts

@@ -6,6 +6,7 @@
 
 import { html, nothing } from "lit-html";
 import { errorMessage } from "@jxsuite/schema/parse";
+import { flushAllCollab } from "../collab/collab-session";
 import type {
   GitBranchesResult,
   GitDiffState,
@@ -263,6 +264,9 @@ export function renderGitPanel(
       return;
     }
     updateUi("gitCommitMessage", "");
+    // Fold co-editing sessions into the backend's tree first so the commit never misses
+    // Trailing keystrokes (the mirror is debounced).
+    await flushAllCollab();
     await gitAction("gitCommit", msg);
   };
 
@@ -275,6 +279,7 @@ export function renderGitPanel(
     updateUi("gitCommitMessage", "");
     updateUi("gitLoading", true);
     updateUi("gitError", null);
+    await flushAllCollab();
     const plat = getPlatform();
     try {
       await plat.gitCommit(msg);

package/src/panels/toolbar.ts

@@ -7,7 +7,14 @@
 import { html, render as litRender, nothing } from "lit-html";
 import { openPublishPanel } from "../publish/publish-panel";
 import { updateSession } from "../store";
-import { redo as tabRedo, undo as tabUndo } from "../tabs/transact";
+import {
+  canRedo as tabCanRedo,
+  canUndo as tabCanUndo,
+  redo as tabRedo,
+  undo as tabUndo,
+} from "../tabs/transact";
+import { collabState } from "../collab/collab-state";
+import { presenceChipsTemplate } from "../collab/presence-chips";
 import { effect, effectScope } from "../reactivity";
 import { activeTab } from "../workspace/workspace";
 import { applyPanelCollapse, view } from "../view";
@@ -101,6 +108,8 @@ export function mount(rootEl: HTMLElement, ctx: ToolbarCtx) {
         void tab.session.ui.gitStatus;
         void tab.history.index;
         void tab.history.snapshots.length;
+        void collabState(tab).status;
+        void collabState(tab).peers.length;
       }
       render();
     });
@@ -322,8 +331,8 @@ function toolbarTemplate() {
   }
 
   const allowedModes = new Set(tab.capabilities.modes);
-  const canUndo = tab.history.index > 0;
-  const canRedo = tab.history.index < tab.history.snapshots.length - 1;
+  const canUndo = tabCanUndo(tab);
+  const canRedo = tabCanRedo(tab);
   const canSave = tab.doc.dirty;
 
   const S = {
@@ -495,6 +504,7 @@ function toolbarTemplate() {
         ${toolbarIconMap["sp-icon-redo"]}<span class="tb-label">Redo</span>
       </sp-action-button>
     </sp-action-group>
+    ${presenceChipsTemplate(tab)}
     <div class="tb-spacer"></div>
     <sp-action-button
       class="tb-search-trigger"

package/src/platforms/cloud.ts

@@ -16,6 +16,7 @@
 import { transpileJxMarkdown } from "@jxsuite/parser/transpile";
 import { serializeJxMarkdown } from "@jxsuite/parser/serialize";
 import markdownClassDef from "@jxsuite/parser/Markdown.class.json";
+import type { WsCollabConnection } from "@jxsuite/collab/client";
 import type { JxDocument, ProjectConfig } from "@jxsuite/schema/types";
 import type {
   DirEntry,
@@ -197,6 +198,11 @@ export function parseRootKey(root: string): CloudProject | null {
 export function createCloudPlatform(project: CloudProject | null): StudioPlatform {
   const base = project ? sessionBase(project) : "";
   const root = project ? `${project.owner}/${project.repo}` : "";
+  /**
+   * One multiplexed collab socket per session; per-doc handles come from openDoc. Memoized as a
+   * promise so concurrent first opens share the connection instead of racing two sockets.
+   */
+  let collabConnection: Promise<WsCollabConnection> | null = null;
 
   function api(path: string, init?: RequestInit): Promise<Response> {
     if (!project) {
@@ -341,6 +347,31 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
       // Directories exist implicitly in the virtual tree (created on write).
     },
 
+    /**
+     * Realtime co-editing over the gateway's /collab WebSocket (rooms keyed by project-relative
+     * path, per the shared ProjectSession working tree). Backends without the endpoint (or with the
+     * flag off) refuse the upgrade and Studio degrades to solo editing. The wire client's
+     * evaluation defers behind the dynamic import until a doc opens.
+     */
+    async collab(docPath: string) {
+      if (!project || typeof WebSocket === "undefined" || typeof location === "undefined") {
+        return null;
+      }
+      collabConnection ??= (async () => {
+        const { createWsCollabConnection } = await import("@jxsuite/collab/client");
+        const scheme = location.protocol === "https:" ? "wss" : "ws";
+        return createWsCollabConnection({
+          hydratePath: async (path) => {
+            // The DO has no GitHub token on a WS message; a plain read hydrates + caches the row.
+            await api(`/file?path=${encodeURIComponent(path)}`);
+          },
+          url: `${scheme}://${location.host}${base}/collab`,
+        });
+      })();
+      const connection = await collabConnection;
+      return connection.openDoc(docPath);
+    },
+
     /**
      * Live session events over the gateway WebSocket. Reconnects with a small backoff; the DO
      * pushes {kind:"fs"} batches for file mutations (including those from other tabs) and

package/src/platforms/devserver.ts

@@ -9,6 +9,7 @@
  */
 
 import { streamImport } from "../services/import-client";
+import type { WsCollabConnection } from "@jxsuite/collab/client";
 import type { ProjectConfig } from "@jxsuite/schema/types";
 import type {
   DirEntry,
@@ -46,6 +47,13 @@ interface SiteEntry {
  */
 export function createDevServerPlatform() {
   let _projectRoot = "";
+  /** Lazy /__studio/collab capability probe (null = not asked yet). */
+  let _collabProbe: Promise<boolean> | null = null;
+  /**
+   * One multiplexed collab socket per page; per-doc handles come from openDoc. Memoized as a
+   * promise so concurrent first opens share the connection instead of racing two sockets.
+   */
+  let _collabConnection: Promise<WsCollabConnection> | null = null;
 
   /**
    * Prefix a project-relative path with the active project root for server API calls.
@@ -390,6 +398,35 @@ export function createDevServerPlatform() {
       };
     },
 
+    /**
+     * Realtime co-editing over the dev server's /__studio/collab endpoint (rooms keyed by
+     * server-root-relative path). Probes capability once — older servers without the endpoint
+     * degrade to solo editing; the wire client's evaluation defers behind the dynamic import until
+     * a doc opens.
+     */
+    async collab(docPath: string) {
+      if (typeof WebSocket === "undefined" || typeof location === "undefined") {
+        return null;
+      }
+      if (_collabProbe === null) {
+        _collabProbe = fetch("/__studio/collab")
+          .then((res) => res.ok)
+          .catch(() => false);
+      }
+      if (!(await _collabProbe)) {
+        return null;
+      }
+      _collabConnection ??= (async () => {
+        const { createWsCollabConnection } = await import("@jxsuite/collab/client");
+        const scheme = location.protocol === "https:" ? "wss" : "ws";
+        return createWsCollabConnection({
+          url: `${scheme}://${location.host}/__studio/collab`,
+        });
+      })();
+      const connection = await _collabConnection;
+      return connection.openDoc(serverPath(docPath));
+    },
+
     /** @param {string} _path */
     async createDirectory(_path: string) {
       // The server creates directories implicitly when writing files.

package/src/studio.ts

@@ -77,6 +77,11 @@ import {
   setupTreeKeyboard,
 } from "./files/files";
 import { startFsSync } from "./files/fs-events";
+import {
+  configureCollabNotifier,
+  configureCollabParser,
+  configureCollabSerializer,
+} from "./collab/collab-session";
 import { renderImportsTemplate } from "./panels/imports-panel";
 import { renderHeadTemplate } from "./panels/head-panel";
 import { exportCemManifest as _exportCemManifest } from "./services/cem-export";
@@ -571,6 +576,18 @@ function safeRenderRightPanel() {
 // Now that renderers are registered, bootstrap
 registerFunctionCompletions();
 
+// Collab sessions serialize/parse through the format host when mirroring between the structure
+// Tree and the shared source text, and surface freezes via the status bar.
+configureCollabSerializer(serializeDocument);
+configureCollabParser(async (tab, text) => {
+  if (tab.documentPath && formatForPath(tab.documentPath)) {
+    const parsed = await parseSourceForPath(tab.documentPath, text);
+    return { document: parsed.document as JxMutableNode, frontmatter: parsed.frontmatter };
+  }
+  return { document: JSON.parse(text) as JxMutableNode };
+});
+configureCollabNotifier(statusMessage);
+
 let fsUnsub: (() => void) | null = null;
 /** (Re)subscribe the sidebar to backend filesystem events for the active project. */
 function ensureFsSync() {

package/src/tabs/doc-op-apply.ts

@@ -4,86 +4,10 @@
  * from live editing: history replay in the parent ({@link file://./transact.ts}) and the iframe
  * canvas's non-reactive shadow doc (the patch source-of-truth across the cross-origin bridge).
  *
- * Dependency-light on purpose: it pulls only the pure path helper from `../state` and clones values
- * with a local JSON round-trip, so the slim canvas-iframe bundle can import it without dragging in
- * the editor's reactive store / format host.
+ * The implementation is the canonical one in `@jxsuite/collab/ops` (yjs-free, so the slim
+ * canvas-iframe bundle imports it without dragging yjs in); this module re-exports it so both sides
+ * of the frame boundary — and the collab bridge — replay ops through one code path.
  */
 
-import { getNodeAtPath } from "../state";
-import type { JxDocOp } from "./patch-ops";
-import type { JxMutableNode } from "@jxsuite/schema/types";
-
-/** JSON round-trip clone — also normalizes away reactive proxies / functions / undefined. */
-function jsonClone<T>(value: T): T {
-  // oxlint-disable-next-line unicorn/prefer-structured-clone -- structuredClone throws on reactive proxies; JSON normalization is the point
-  return JSON.parse(JSON.stringify(value)) as T;
-}
-
-/** Deep-clone a recorded value (undefined/null pass through; reactive proxies are read through). */
-export function cloneValue<T>(v: T): T {
-  return v === undefined || v === null ? v : (jsonClone(v as object) as T);
-}
-
-/** The node's children array, lazily created; throws if `node` is itself a children array or mapped. */
-export function childArray(node: JxMutableNode): (JxMutableNode | string)[] {
-  // Defense-in-depth: a path that resolves to a children array (rather than a node) would
-  // Otherwise get a bogus `.children` property tacked on here, silently storing the insert where
-  // Nothing renders. Callers must pass a node; fail loudly if they don't.
-  if (Array.isArray(node)) {
-    throw new TypeError("Cannot insert into a children array; parentPath must point at a node");
-  }
-  if (!node.children) {
-    node.children = [];
-  }
-  if (!Array.isArray(node.children)) {
-    throw new TypeError("Cannot insert into mapped-array children; edit the map template instead");
-  }
-  return node.children;
-}
-
-/**
- * Apply a replayable doc op to a bare document tree. Values/nodes are cloned in, so the tree never
- * aliases the op object. Throws (with a machine-readable reason) when a target path is missing.
- */
-export function applyDocOpToDoc(doc: JxMutableNode, op: JxDocOp): void {
-  switch (op.op) {
-    case "set-key": {
-      const node = getNodeAtPath(doc, op.path);
-      if (!node) {
-        throw new Error(`doc-op-node-not-found:${op.path.join("/")}`);
-      }
-      const target = node as Record<string, unknown>;
-      if (op.value === undefined) {
-        delete target[op.key];
-      } else {
-        target[op.key] = cloneValue(op.value);
-      }
-      return;
-    }
-    case "insert-child": {
-      const parent = getNodeAtPath(doc, op.parentPath);
-      childArray(parent).splice(op.index, 0, cloneValue(op.node) as JxMutableNode);
-      return;
-    }
-    case "remove-child": {
-      const parent = getNodeAtPath(doc, op.parentPath);
-      childArray(parent).splice(op.index, 1);
-      return;
-    }
-    case "set-child": {
-      const parent = getNodeAtPath(doc, op.parentPath);
-      childArray(parent).splice(op.index, 1, cloneValue(op.node) as JxMutableNode);
-      return;
-    }
-    case "move-child": {
-      const fromParent = getNodeAtPath(doc, op.fromParentPath);
-      const toParent = getNodeAtPath(doc, op.toParentPath);
-      const [node] = childArray(fromParent).splice(op.fromIndex, 1);
-      childArray(toParent).splice(op.toIndex, 0, node!);
-      return;
-    }
-    default: {
-      throw new Error(`unknown-doc-op:${(op as JxDocOp).op}`);
-    }
-  }
-}
+export { applyDocOpToDoc, childArray, cloneValue } from "@jxsuite/collab/ops";
+export type { JxDocOp } from "@jxsuite/collab/ops";

package/src/tabs/patch-ops.ts

@@ -5,6 +5,8 @@
  * document as the single source of truth.
  */
 
+// oxlint-disable-next-line unicorn/prefer-export-from -- JxDocOpPair is also used locally (TransactionRecord)
+import type { JxDocOpPair } from "@jxsuite/collab/ops";
 import type { JxPath } from "../state";
 import type { Tab } from "./tab.js";
 
@@ -31,30 +33,12 @@ export type JxPatchOp =
 /**
  * Value-carrying document mutation, replayable in either direction. Mutators record a
  * forward/inverse pair per change; history applies them for surgical undo/redo and for
- * materializing states from checkpoints — without whole-document snapshots per edit.
+ * materializing states from checkpoints — without whole-document snapshots per edit. The definition
+ * is canonical in `@jxsuite/collab/ops` (the collab bridge mirrors the same ops into a shared
+ * Y.Doc); re-exported here so studio call sites keep their import path.
  */
-export type JxDocOp =
-  /** Set (or delete, when value is undefined) a key on the node at path. */
-  | { op: "set-key"; path: JxPath; key: string; value?: unknown }
-  /** Insert a node at parentPath.children[index]. */
-  | { op: "insert-child"; parentPath: JxPath; index: number; node: unknown }
-  /** Remove parentPath.children[index]. */
-  | { op: "remove-child"; parentPath: JxPath; index: number }
-  /** Replace parentPath.children[index] with node. */
-  | { op: "set-child"; parentPath: JxPath; index: number; node: unknown }
-  /** Raw two-splice move: remove fromParent.children[fromIndex], insert at toParent[toIndex]. */
-  | {
-      op: "move-child";
-      fromParentPath: JxPath;
-      fromIndex: number;
-      toParentPath: JxPath;
-      toIndex: number;
-    };
-
-export interface JxDocOpPair {
-  forward: JxDocOp;
-  inverse: JxDocOp;
-}
+export type { JxDocOp } from "@jxsuite/collab/ops";
+export type { JxDocOpPair };
 
 /** Everything recorded during one transaction. */
 export interface TransactionRecord {