@jxsuite/collab 0.1.0 → 0.2.1

package/README.md

@@ -68,7 +68,8 @@ one `error{read-only}`.
 ## Awareness (`./awareness-types`)
 
 One project-level `Awareness` per connection. State shape:
-`{ user: {login, name?, avatarUrl?, color}, focusedPath, mode?, selection? }` — file-tree presence
+`{ user: {login, name?, avatarUrl?, color}, focusedPath, mode?, structuralSelection?, selection? }` —
+file-tree presence (the plain `selection` field is y-monaco's in-buffer cursor)
 and per-document cursor overlays both filter the same states. Identity comes from the server
 `hello`; colors are deterministic (`colorForKey`).
 
@@ -77,3 +78,9 @@ and per-document cursor overlays both filter the same states. Identity comes fro
 `StudioPlatform.collab?: (docPath) => Promise<CollabHandle | null>` where a handle carries
 `{doc, awareness, whenSynced, identity(), flush(), onStatus(), onReset(), destroy()}`. `onReset`
 fires on a `doc-reset`: the handle is dead — destroy it and re-acquire.
+
+## Versioning
+
+Published to npm as `@jxsuite/collab` — TypeScript source, like every `@jxsuite`
+package, following the monorepo's release train. Within the monorepo, other
+packages (`@jxsuite/server`, `@jxsuite/studio`) depend on it via `workspace:^`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/collab",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Realtime co-editing for Jx Studio — Y.Doc schema, op bridge, structural differ, wire envelope, and provider contracts shared by every collab backend",
   "license": "MIT",
   "repository": {
@@ -25,14 +25,14 @@
     "./room": "./src/ws-room.ts"
   },
   "publishConfig": {
-    "provenance": false
+    "provenance": true
   },
   "scripts": {
     "test": "bun test --isolate",
     "test:coverage": "bun test --isolate --coverage"
   },
   "dependencies": {
-    "@jxsuite/schema": "workspace:^",
+    "@jxsuite/schema": "^0.35.0",
     "lib0": "^0.2.99",
     "y-protocols": "^1.0.6",
     "yjs": "13.6.27"

package/src/awareness-types.ts

@@ -21,8 +21,14 @@ export interface CollabAwarenessState {
   focusedPath: string | null;
   /** Which representation the client is editing (drives the Phase-B canonical lock). */
   mode?: "structure" | "source";
-  /** The client's structural selection in the focused document. */
-  selection?: JxPath | null;
+  /** The client's structural (canvas) selection in the focused document. */
+  structuralSelection?: JxPath | null;
+  /**
+   * RESERVED for y-monaco: the in-buffer text cursor as {anchor, head} Y.RelativePosition JSON.
+   * MonacoBinding owns this field via setLocalStateField("selection", …) while a code view is
+   * bound; nothing else may write it.
+   */
+  selection?: { anchor: unknown; head: unknown } | null;
   /**
    * Whether this client may write (from the server hello). Drives reconciler election — the lowest
    * write-capable clientID mirrors derived representations. Advisory only: the server drops updates

package/src/index.ts

@@ -29,6 +29,15 @@ export {
   yEventsToDocOps,
 } from "./op-bridge.ts";
 export { deepEqual, diffDocs, replaceYStructure } from "./diff.ts";
+export {
+  acquireSourceCanonical,
+  canonicalOf,
+  canonicalRevOf,
+  isSourceReconciler,
+  otherSourceEditors,
+  releaseSourceCanonical,
+} from "./source-lock.ts";
+export type { CanonicalRepresentation } from "./source-lock.ts";
 export type { DiffOptions } from "./diff.ts";
 export {
   decodeFrame,

package/src/source-lock.ts

@@ -0,0 +1,98 @@
+/**
+ * The canonical-representation lock for source-mode co-editing (the Phase-B dual-representation
+ * design). `meta.canonical` says which representation is authoritative: "structure" (the default —
+ * canvas/inspector edits flow through the op bridge and the elected reconciler mirrors them into
+ * source text) or "source" (Monaco co-edits the Y.Text character-level; structural surfaces
+ * soft-freeze and the source reconciler mirrors parses back into the structure tree for live
+ * previews).
+ *
+ * Every flip bumps `meta.canonicalRev`; derived-representation writers stamp the rev they computed
+ * against and observers discard stale mirrors. Flips are LWW-idempotent under concurrency: both
+ * flippers serialize the same structure, so the merged text converges.
+ */
+
+import type { Doc } from "yjs";
+import type { Awareness } from "y-protocols/awareness";
+import { metaMap, updateSourceText } from "./schema.ts";
+import type { CollabAwarenessState } from "./awareness-types.ts";
+
+export type CanonicalRepresentation = "structure" | "source";
+
+export function canonicalOf(doc: Doc): CanonicalRepresentation {
+  return metaMap(doc).get("canonical") === "source" ? "source" : "structure";
+}
+
+export function canonicalRevOf(doc: Doc): number {
+  return Number(metaMap(doc).get("canonicalRev") ?? 0);
+}
+
+/**
+ * Flip canonical to "source", seeding the text from `serialized` (the flipper's serialization of
+ * the current structure). No-op (false) when source already holds the lock.
+ */
+export function acquireSourceCanonical(doc: Doc, serialized: string, origin: unknown): boolean {
+  if (canonicalOf(doc) === "source") {
+    return false;
+  }
+  doc.transact(() => {
+    updateSourceText(doc, serialized, origin);
+    const meta = metaMap(doc);
+    meta.set("canonical", "source");
+    meta.set("canonicalRev", canonicalRevOf(doc) + 1);
+  }, origin);
+  return true;
+}
+
+/** Flip canonical back to "structure" (the mirror is the caller's responsibility beforehand). */
+export function releaseSourceCanonical(doc: Doc, origin: unknown): boolean {
+  if (canonicalOf(doc) !== "source") {
+    return false;
+  }
+  doc.transact(() => {
+    const meta = metaMap(doc);
+    meta.set("canonical", "structure");
+    meta.set("canonicalRev", canonicalRevOf(doc) + 1);
+  }, origin);
+  return true;
+}
+
+/** Peers (excluding `selfClientId`) currently source-editing this doc, per awareness. */
+export function otherSourceEditors(
+  awareness: Awareness,
+  path: string,
+  selfClientId: number,
+): number[] {
+  const editors: number[] = [];
+  for (const [clientId, raw] of awareness.getStates()) {
+    const state = raw as Partial<CollabAwarenessState>;
+    if (clientId !== selfClientId && state.mode === "source" && state.focusedPath === path) {
+      editors.push(clientId);
+    }
+  }
+  return editors;
+}
+
+/**
+ * The source reconciler — the lowest write-capable clientID among this doc's source editors
+ * (including self when in source mode) — owns parsing Y.Text back into the structure tree.
+ */
+export function isSourceReconciler(awareness: Awareness, path: string): boolean {
+  const self = awareness.clientID;
+  const selfState = awareness.getStates().get(self) as Partial<CollabAwarenessState> | undefined;
+  if (selfState?.mode !== "source" || selfState.focusedPath !== path) {
+    return false;
+  }
+  let lowest = self;
+  for (const [clientId, raw] of awareness.getStates()) {
+    const state = raw as Partial<CollabAwarenessState>;
+    if (
+      state.mode === "source" &&
+      state.focusedPath === path &&
+      state.canWrite !== false &&
+      clientId < lowest
+    ) {
+      lowest = clientId;
+    }
+  }
+  return lowest === self;
+}