@jxsuite/studio 0.35.0 → 0.37.0

package/src/tabs/transact.ts

@@ -79,22 +79,64 @@ export type JxNodeValue =
 
 // ─── Transactional layer ─────────────────────────────────────────────────────
 
+/**
+ * Where a transaction came from: a direct user/tool edit, the undo/redo machinery replaying
+ * recorded ops, or a remote collaborator's ops applied locally. Observers use this to avoid
+ * republishing what they themselves applied.
+ */
+export type TransactOrigin = "user" | "history" | "remote";
+
+/**
+ * Module-level hook invoked at the end of every transactDoc (after the canvas patch apply and the
+ * dirty mark). Registered by the collab layer to mirror local edits into a shared document; at most
+ * one observer exists. `record.docOps` may be empty for un-instrumented mutations — observers must
+ * handle that (e.g. by diffing).
+ */
+export type TransactObserver = (
+  tab: Tab,
+  record: TransactionRecord,
+  origin: TransactOrigin,
+) => void;
+
+let _transactObserver: TransactObserver | null = null;
+
+export function setTransactObserver(fn: TransactObserver | null) {
+  _transactObserver = fn;
+}
+
+/**
+ * Module-level gate consulted at transactDoc entry: return a refusal reason to block the mutation
+ * (the collab layer soft-freezes structural editing while a peer holds source-canonical), or null
+ * to proceed. Remote-origin transactions always pass — they ARE the frozen representation's
+ * mirror.
+ */
+export type TransactGate = (tab: Tab, origin: TransactOrigin) => string | null;
+
+let _transactGate: TransactGate | null = null;
+
+export function setTransactGate(fn: TransactGate | null) {
+  _transactGate = fn;
+}
+
 /**
  * Apply a document mutation transactionally: push to history and mark dirty. The mutationFn
  * receives the tab and should mutate tab.doc.document in place.
  *
  * @param {Tab | null} tab
  * @param {(tab: Tab) => void} mutationFn
- * @param {{ skipHistory?: boolean }} [opts]
+ * @param {{ skipHistory?: boolean; origin?: TransactOrigin }} [opts]
  */
 export function transactDoc(
   tab: Tab | null,
   mutationFn: (tab: Tab) => void,
-  { skipHistory = false }: { skipHistory?: boolean } = {},
+  { skipHistory = false, origin = "user" }: { skipHistory?: boolean; origin?: TransactOrigin } = {},
 ) {
   if (!tab) {
     return;
   }
+  if (origin !== "remote" && _transactGate?.(tab, origin)) {
+    return;
+  }
   const selectionBefore = tab.session.selection ? [...tab.session.selection] : null;
   beginRecording();
   let record: TransactionRecord;
@@ -141,6 +183,8 @@ export function transactDoc(
   }
 
   tab.doc.dirty = true;
+
+  _transactObserver?.(tab, record, origin);
 }
 
 /**
@@ -215,16 +259,38 @@ function materializeState(
  *
  * @param {Tab | null} tab
  * @param {(doc: JxMutableNode) => void} fn
- * @param {{ skipHistory?: boolean }} [opts]
+ * @param {{ skipHistory?: boolean; origin?: TransactOrigin }} [opts]
  */
 export function transact(
   tab: Tab | null,
   fn: (doc: JxMutableNode) => void,
-  opts?: { skipHistory?: boolean },
+  opts?: { skipHistory?: boolean; origin?: TransactOrigin },
 ) {
   transactDoc(tab, (t) => fn(t.doc.document), opts);
 }
 
+/**
+ * Apply externally-produced doc ops (a remote collaborator's edits) through the normal transaction
+ * pipeline: the canvas patches surgically exactly as it does for undo/redo replay, panels' effects
+ * fire, and — because the origin is "remote" — the transact observer will not republish them.
+ * History is skipped; while a collab session is attached, undo is delegated (see
+ * setHistoryDelegate) and local-only.
+ *
+ * @param {Tab} tab
+ * @param {JxDocOp[]} ops
+ */
+export function applyExternalDocOps(tab: Tab, ops: JxDocOp[]) {
+  transactDoc(
+    tab,
+    (t) => {
+      for (const op of ops) {
+        applyDocOp(t, op);
+      }
+    },
+    { origin: "remote", skipHistory: true },
+  );
+}
+
 // ─── Document-op application ─────────────────────────────────────────────────
 
 /** Document-level keys whose changes require a full scope/panel rebuild on the canvas. */
@@ -289,26 +355,40 @@ function applyDocOp(tab: Tab, op: JxDocOp) {
 
 let _batchTab: Tab | null = null;
 
+/** Module-level hook invoked when a batch closes (collab flushes its buffered ops as one step). */
+export type BatchEndNotifier = (tab: Tab) => void;
+
+let _batchEndNotifier: BatchEndNotifier | null = null;
+
+export function setBatchEndNotifier(fn: BatchEndNotifier | null) {
+  _batchEndNotifier = fn;
+}
+
 export function beginBatch(tab: Tab | null) {
   _batchTab = tab;
 }
 
 export function endBatch() {
-  if (_batchTab) {
-    const raw = toRaw(_batchTab.doc.document);
+  const tab = _batchTab;
+  // A history delegate owns undo grouping while registered; the snapshot push would be dead weight.
+  if (tab && !_historyDelegates.has(tab)) {
+    const raw = toRaw(tab.doc.document);
     const snapshot = {
       document: jsonClone(raw),
-      selection: _batchTab.session.selection ? [..._batchTab.session.selection] : null,
+      selection: tab.session.selection ? [...tab.session.selection] : null,
     };
-    const truncated = _batchTab.history.snapshots.slice(0, _batchTab.history.index + 1);
+    const truncated = tab.history.snapshots.slice(0, tab.history.index + 1);
     truncated.push(snapshot);
     if (truncated.length > HISTORY_LIMIT) {
       truncated.shift();
     }
-    _batchTab.history.snapshots = truncated;
-    _batchTab.history.index = truncated.length - 1;
+    tab.history.snapshots = truncated;
+    tab.history.index = truncated.length - 1;
   }
   _batchTab = null;
+  if (tab) {
+    _batchEndNotifier?.(tab);
+  }
 }
 
 export function isBatching(): boolean {
@@ -317,6 +397,42 @@ export function isBatching(): boolean {
 
 // ─── Undo / Redo ─────────────────────────────────────────────────────────────
 
+/**
+ * Per-tab replacement for the built-in op-log history. While a delegate is registered (a collab
+ * session's Y.UndoManager), undo/redo route to it and the snapshot history is bypassed — keeping
+ * this module free of any yjs knowledge.
+ */
+export interface HistoryDelegate {
+  undo: (tab: Tab) => void;
+  redo: (tab: Tab) => void;
+  canUndo: (tab: Tab) => boolean;
+  canRedo: (tab: Tab) => boolean;
+}
+
+const _historyDelegates = new WeakMap<Tab, HistoryDelegate>();
+
+export function setHistoryDelegate(tab: Tab, delegate: HistoryDelegate | null) {
+  if (delegate) {
+    _historyDelegates.set(tab, delegate);
+  } else {
+    _historyDelegates.delete(tab);
+  }
+}
+
+export function getHistoryDelegate(tab: Tab): HistoryDelegate | null {
+  return _historyDelegates.get(tab) ?? null;
+}
+
+export function canUndo(tab: Tab): boolean {
+  const delegate = _historyDelegates.get(tab);
+  return delegate ? delegate.canUndo(tab) : tab.history.index > 0;
+}
+
+export function canRedo(tab: Tab): boolean {
+  const delegate = _historyDelegates.get(tab);
+  return delegate ? delegate.canRedo(tab) : tab.history.index < tab.history.snapshots.length - 1;
+}
+
 /** Restore a materialized snapshot state (full-render path). */
 function restoreState(tab: Tab, index: number) {
   const { snapshots } = tab.history;
@@ -345,6 +461,11 @@ function assertHistoryConsistency(tab: Tab, index: number) {
 
 /** @param {Tab} tab */
 export function undo(tab: Tab) {
+  const delegate = _historyDelegates.get(tab);
+  if (delegate) {
+    delegate.undo(tab);
+    return;
+  }
   if (tab.history.index <= 0) {
     return;
   }
@@ -360,7 +481,7 @@ export function undo(tab: Tab) {
           applyDocOp(t, toRaw(inverseOps[i]) as JxDocOp);
         }
       },
-      { skipHistory: true },
+      { origin: "history", skipHistory: true },
     );
     tab.session.selection = entry.selectionBefore ? [...toRaw(entry.selectionBefore)] : null;
     tab.history.index -= 1;
@@ -374,6 +495,11 @@ export function undo(tab: Tab) {
 
 /** @param {Tab} tab */
 export function redo(tab: Tab) {
+  const delegate = _historyDelegates.get(tab);
+  if (delegate) {
+    delegate.redo(tab);
+    return;
+  }
   if (tab.history.index >= tab.history.snapshots.length - 1) {
     return;
   }
@@ -387,7 +513,7 @@ export function redo(tab: Tab) {
           applyDocOp(t, toRaw(op) as JxDocOp);
         }
       },
-      { skipHistory: true },
+      { origin: "history", skipHistory: true },
     );
     tab.session.selection = entry.selection ? [...toRaw(entry.selection)] : null;
     tab.history.index += 1;

package/src/types.ts

@@ -1,168 +1,59 @@
 /// <reference lib="dom" />
-import type {
-  JsonValue as SchemaJsonValue,
-  JxMutableNode,
-  JxPath,
-  ProjectConfig,
-} from "@jxsuite/schema/types";
-
-// ─── Git & Platform Types ───────────────────────────────────────────────────
-
-export interface GitFileStatus {
-  status: string;
-  path: string;
-  staged?: boolean;
-}
-
-export interface GitStatusResult {
-  branch: string;
-  files: GitFileStatus[];
-  ahead: number;
-  behind: number;
-  isRepo: boolean;
-  remotes: string[];
-}
-
-export interface GitBranchesResult {
-  current: string;
-  branches: string[];
-}
-
-export interface GitLogEntry {
-  hash: string;
-  message: string;
-  author: string;
-  date: string;
-}
-
-export interface ComponentSlotMeta {
-  name: string;
-  description?: string;
-  fallback?: (JxMutableNode | string)[];
-}
-
-export interface ComponentMeta {
-  tagName: string;
-  $id?: string | null;
-  path: string;
-  props?: { name: string; type?: string; default?: JsonValue; [k: string]: unknown }[];
-  slots?: ComponentSlotMeta[];
-  hasElements?: boolean;
-}
-
-export interface PackageInfo {
-  name: string;
-  version: string;
-  /** True when the dependency lives in `devDependencies` rather than `dependencies`. */
-  dev?: boolean;
-}
-
-/** A dependency with a newer version available, as reported by `bun outdated` / the npm registry. */
-export interface OutdatedInfo {
-  name: string;
-  /** The version range pinned in package.json (e.g. "^0.19.0"). */
-  current: string;
-  /** The newest published version. */
-  latest: string;
-  /** The newest version satisfying the current range, if known. */
-  wanted?: string;
-  dev?: boolean;
-}
-
-/** Result of a package mutation that runs `bun install` (install / set-versions). */
-export interface PackageOpResult {
-  ok: boolean;
-  /** Combined stdout/stderr from the bun invocation, surfaced to the user on failure. */
-  log?: string;
-}
-
-/** Desktop app/build info surfaced in the About screen. */
-export interface AppInfo {
-  version: string;
-  channel: string;
-  hash: string;
-  /** Human-readable update status (e.g. "Up to date", "Update available"), if known. */
-  updateStatus?: string;
-}
-
-export interface CodeServiceResult {
-  code?: string;
-  diagnostics?: unknown[];
-  [key: string]: unknown;
-}
+import type { CollabHandle } from "@jxsuite/collab/provider";
+import type { JxMutableNode, JxPath, ProjectConfig } from "@jxsuite/schema/types";
 
-export interface DirEntry {
-  name: string;
-  path: string;
-  type: "file" | "directory";
-  size?: number;
-  modified?: string;
-}
-
-/** A filesystem change pushed from the backend (project-relative, forward-slashed path). */
-export interface FsEvent {
-  type: "add" | "change" | "unlink" | "addDir" | "unlinkDir";
-  path: string;
-  isDir: boolean;
-}
-
-/** Result of a rename, including the references rewritten across the project (refactor report). */
-export interface RenameResult {
-  ok: boolean;
-  from: string;
-  to: string;
-  isDir?: boolean;
-  references?: {
-    filesChanged: number;
-    refsUpdated: number;
-    files: { path: string; count: number }[];
-  };
-  errors?: { path: string; error: string }[];
-  tag?: { from: string; to: string; filesChanged: number; refsUpdated: number };
-  tagSkipped?: string;
-  error?: string;
-}
-
-/** A starter template surfaced in the New Project picker (mirrors @jxsuite/starters StarterMeta). */
-export interface StarterInfo {
-  id: string;
-  name: string;
-  industry: string;
-  tagline: string;
-  description: string;
-  features: string[];
-  accent: string;
-  /** Preview image as a self-contained `data:` URI. */
-  thumbnail: string;
-}
+// ─── Wire types (the Studio Backend Protocol) ───────────────────────────────
+/* The request/response shapes every backend serves live in @jxsuite/protocol;
+   re-exported here so existing `../types` imports keep working. */
 
-/** A progress line from the AI-guided site import (mirrors @jxsuite/import ImportProgressEvent). */
-export interface ImportProgressEvent {
-  phase: string;
-  message: string;
-  current?: number;
-  total?: number;
-}
+import type {
+  AppInfo,
+  CfConnection,
+  CodeServiceResult,
+  ComponentMeta,
+  DirEntry,
+  FsEvent,
+  GitBranchesResult,
+  GitLogEntry,
+  GitStatusResult,
+  ImportProgressEvent,
+  ImportSiteOptions,
+  OutdatedInfo,
+  PackageInfo,
+  PackageOpResult,
+  ProjectListEntry,
+  RecentProjectEntry,
+  RenameResult,
+  StarterInfo,
+} from "@jxsuite/protocol";
 
-/** Options for {@link StudioPlatform.importSite}. */
-export interface ImportSiteOptions {
-  /** The live site to clone; must be http(s). */
-  url: string;
-  /** Display name for the new project. */
-  name: string;
-  /** Destination directory (platform-interpreted: project-relative on the dev server). */
-  directory: string;
-  /** Max crawl depth; 0 = single page. */
-  depth: number;
-  /** Max pages to capture. */
-  maxPages: number;
-  /** Refine component/prop names with the LLM (requires a key). */
-  aiComponents: boolean;
-  /** OpenAI-compatible credentials, from the user's AI settings. */
-  apiKey?: string;
-  baseUrl?: string;
-  model?: string;
-}
+export type {
+  AiModelInfo,
+  AiModelsResponse,
+  AppInfo,
+  CfConnection,
+  CodeServiceResult,
+  ComponentMeta,
+  ComponentSlotMeta,
+  DirEntry,
+  ErrorBody,
+  FsEvent,
+  GitBranchesResult,
+  GitFileStatus,
+  GitLogEntry,
+  GitStatusResult,
+  ImportProgressEvent,
+  ImportSiteOptions,
+  JsonValue,
+  OutdatedInfo,
+  PackageInfo,
+  PackageOpResult,
+  ProjectListEntry,
+  PullRequestInfo,
+  RecentProjectEntry,
+  RenameResult,
+  StarterInfo,
+} from "@jxsuite/protocol";
 
 export interface StudioPlatform {
   id: string;
@@ -326,6 +217,49 @@ export interface StudioPlatform {
   getRecentProjects?: () => Promise<RecentProjectEntry[]>;
   /** Persist the full recent-projects list to the backend store. */
   saveRecentProjects?: (projects: RecentProjectEntry[]) => Promise<void>;
+  // ─── Project catalogue (platforms that can enumerate openable projects) ─────
+  /**
+   * Enumerate every project this platform can open — the dev server's sites under its root, a cloud
+   * platform's remote projects. Entry `root` values re-open through the same paths as recent
+   * projects (openRecentProject). Absent on desktop, where the OS file system is the catalogue and
+   * projects are found via the native picker instead.
+   */
+  listProjects?: () => Promise<ProjectListEntry[]>;
+  /**
+   * Open a realtime co-editing session for a project-relative document path. Optional: platforms
+   * without a collab backend omit it and Studio edits solo with file-level saves. Resolves null
+   * when the backend refuses a room for this doc (binary, oversized). The returned handle's Y.Doc
+   * starts empty and fills from the provider — see `@jxsuite/collab/provider` for the contract.
+   */
+  collab?: (docPath: string) => Promise<CollabHandle | null>;
+  // ─── Identity & hosting connections (publish surface) ───────────────────────
+  /** The signed-in user's identity, when the platform has one (cloud). */
+  getUser?: () => Promise<{ login: string; name?: string; avatarUrl?: string } | null>;
+  /**
+   * Open a pull request for the current branch. Cloud platforms implement it against their session;
+   * local platforms omit it and Studio falls back to a direct GitHub API call with the user's
+   * stored token.
+   */
+  createPullRequest?: (opts: {
+    title: string;
+    body?: string;
+    head?: string;
+    base?: string;
+  }) => Promise<{ url: string; number: number }>;
+  /** Current Cloudflare connection state, when the platform can broker one. */
+  cfConnection?: () => Promise<CfConnection | null>;
+  /**
+   * Interactively connect a Cloudflare account (hosted OAuth on the cloud platform). Local
+   * platforms omit it — the publish UI collects an API token instead and verifies via
+   * cfConnection.
+   */
+  cfConnect?: () => Promise<CfConnection | null>;
+  /**
+   * Allowlisted Cloudflare API passthrough (accounts, Pages projects and deployments). The backend
+   * injects credentials — an OAuth token on the cloud platform, the user's pasted API token locally
+   * — so no secret ever rides in the request body.
+   */
+  cfApi?: (path: string, init?: { method?: string; body?: unknown }) => Promise<unknown>;
   // ─── User settings (backend-persisted; undefined on dev-server) ─────────────
   /**
    * Read the user-level settings map (e.g. the AI connection parameters) from a backend store
@@ -337,13 +271,6 @@ export interface StudioPlatform {
   saveSettings?: (settings: Record<string, string>) => Promise<void>;
 }
 
-/** A recently-opened project, keyed by its re-openable `root` (platform-specific). */
-export interface RecentProjectEntry {
-  name: string;
-  root: string;
-  timestamp: number;
-}
-
 // ─── Studio Types ───────────────────────────────────────────────────────────
 
 export interface CanvasPanel {
@@ -409,9 +336,3 @@ export interface ProjectState {
   projectDirs?: string[];
   [key: string]: unknown;
 }
-
-/**
- * A JSON document value, or `undefined` to signal property removal in the mutators. Re-uses the
- * schema's precise recursive JSON model.
- */
-export type JsonValue = SchemaJsonValue | undefined;

package/src/workspace/workspace.ts

@@ -1,4 +1,5 @@
 import { computed, reactive, toRaw } from "../reactivity";
+import { ensureCollab, rekeyCollab } from "../collab/collab-session";
 import { createTab, disposeTab } from "../tabs/tab";
 import type { Tab } from "../tabs/tab";
 
@@ -96,6 +97,7 @@ export function openTab(opts: {
   workspace.tabs.set(tab.id, tab);
   workspace.tabOrder.push(tab.id);
   workspace.activeTabId = tab.id;
+  ensureCollab(tab);
   return tab;
 }
 
@@ -155,6 +157,7 @@ export function replaceAllTabs(newTabOpts: {
   workspace.tabs.set(newTab.id, newTab);
   workspace.activeTabId = newTab.id;
   workspace.tabOrder = [newTab.id];
+  ensureCollab(newTab);
 
   for (const id of oldIds) {
     if (id === newTab.id) {
@@ -201,4 +204,5 @@ export function renameTab(oldId: string, newId: string, newDocumentPath: string)
   if (workspace.activeTabId === oldId) {
     workspace.activeTabId = newId;
   }
+  rekeyCollab(tab);
 }