@gogitcms/editor 0.23.0

package/app/vendor/plugin-sdk/src/types.ts

@@ -0,0 +1,230 @@
+// The declarative plugin API. A plugin is an npm package whose entrypoint
+// default-exports `setup(cms, options)`; every registration made through `cms`
+// is scoped to that plugin (see registry.ts). Docs: docs/plugin-system.md.
+
+import type { ComponentType } from "react";
+import type { CollabApi, EntryField, IconName } from "@gogitcms/design-system";
+
+// A component contribution is always the loader form — `() => import("./X")`
+// or `async () => ({ default: X })` for an already-loaded component. A direct
+// function component would be indistinguishable from a loader at runtime, so
+// the loader form is the only accepted shape; it is also what makes each
+// screen its own lazy chunk under a bundler.
+export type PluginComponentLoader<P> = () => Promise<{ default: ComponentType<P> }>;
+
+// Field types a plugin field component may attach to. Mirrors the schema's
+// closed `type` set (packages/importer/schema).
+export type PluginFieldType = "string" | "boolean" | "integer" | "float" | "array" | "object";
+
+/**
+ * A document as a plugin sees it — the editor's in-flight state, not the saved
+ * row. `fields` is the whole document rather than a diff, because a plugin that
+ * renders a preview needs every value, not only the changed ones.
+ */
+export type PluginDocument = {
+  id: string;
+  collection: string;
+  /** Repo-relative path, e.g. "content/blog/hello.md". */
+  path: string;
+  fields: Record<string, unknown>;
+  body?: string;
+  /** The field name the body is exposed as, when the schema declares one. */
+  bodyField?: string;
+};
+
+/**
+ * Extra props a route gets when it is rendered as a *tab* beside the editor
+ * rather than as a full screen at its URL.
+ *
+ * Absent on a screen. A route can serve both — it just checks whether this is
+ * there — which is what makes "open this route in a tab" a property of how the
+ * route was opened rather than a second kind of registration.
+ */
+export type PluginTabContext = {
+  /** The tab's id, as passed to openTab. */
+  id: string;
+  /** The document that was open when the tab was opened, or null. */
+  document: PluginDocument | null;
+  /**
+   * Subscribe to that document's in-flight edits. The host debounces before
+   * calling (~150 ms), so a subscriber does not need its own timer. Returns an
+   * unsubscribe function.
+   */
+  onDraft: (cb: (doc: PluginDocument) => void) => () => void;
+  /** Open a document in the editor — the inverse direction, for click-to-edit. */
+  openDocument: (id: string, field?: string) => void;
+  /** Close this tab. */
+  close: () => void;
+};
+
+/** Props handed to a plugin route's screen. */
+export type PluginScreenProps = {
+  workspaceId: string;
+  repositoryId: string;
+  branchId?: string;
+  /** Git ref name of the branch, when the host knows it. */
+  ref?: string;
+  /** Matched `:segment` params from the route path, plus any openTab params. */
+  params: Record<string, string>;
+  /** Navigate to another of this plugin's routes (a registered route path). */
+  navigate: (to: string) => void;
+  /** Base URL of the CMS API, for authenticated fetches. */
+  apiUrl: string;
+  /** Set only when this route is rendered as a tab (see PluginTabContext). */
+  tab?: PluginTabContext;
+};
+
+/**
+ * Props handed to a plugin field component — the field's data as one object.
+ * This is deliberately the design-system's FieldSlotArgs shape (the
+ * `renderField` seam), so plugin fields plug in exactly where the ProseMirror
+ * body editor already does.
+ */
+export type PluginFieldProps = {
+  /** The full schema field: name, label, type, constraints, nested fields. */
+  field: EntryField;
+  value: unknown;
+  onChange: (value: unknown) => void;
+  readOnly?: boolean;
+  /** Dotted path of the field within the document (present under collab). */
+  path?: string;
+  /** Live-collaboration binding when a collab session is active. */
+  collab?: CollabApi;
+};
+
+export type PluginRoute = {
+  /** Relative path under the plugin's mount, e.g. "dashboard" or "reports/:kind". */
+  path: string;
+  title?: string;
+  component: PluginComponentLoader<PluginScreenProps>;
+};
+
+export type PluginSidebarLink = {
+  label: string;
+  icon?: IconName;
+  /** One of this plugin's route paths. */
+  to: string;
+  /** Sidebar section title to group under. Default: "Plugins". */
+  section?: string;
+};
+
+export type PluginUserMenuLink = {
+  label: string;
+  icon?: IconName;
+  /** One of this plugin's route paths… */
+  to?: string;
+  /** …or an action. Exactly one of `to`/`onSelect` is required. */
+  onSelect?: () => void;
+};
+
+/** Where a plugin asks the host to open one of its routes as a tab. */
+export type PluginTabSpec = {
+  /**
+   * Stable tab id. Opening the same id again activates the existing tab rather
+   * than stacking duplicates — so pressing Preview twice on one document does
+   * not end up with two preview columns.
+   */
+  id: string;
+  /** Column header label. */
+  title: string;
+  /** One of this plugin's registered route paths. */
+  route: string;
+  /** Merged into the route component's `params`. */
+  params?: Record<string, string>;
+};
+
+/** What a document action is handed when the user presses its button. */
+export type PluginDocumentActionContext = {
+  workspaceId: string;
+  repositoryId: string;
+  branchId?: string;
+  ref?: string;
+  apiUrl: string;
+  /** The document whose toolbar the button was pressed in. */
+  document: PluginDocument;
+  /** Open one of this plugin's routes as a column tab. */
+  openTab: (spec: PluginTabSpec) => void;
+  /** Open a document in the editor. */
+  openDocument: (id: string, field?: string) => void;
+};
+
+/**
+ * A button in a document's toolbar.
+ *
+ * `available` is what keeps the toolbar honest: a preview plugin configured for
+ * three of a repository's eight collections should show a Preview button on
+ * three of them, not eight with five that error. Returning false hides the
+ * button entirely rather than disabling it, because a disabled button the user
+ * cannot ever enable is worse than no button.
+ */
+export type PluginDocumentAction = {
+  /** Stable id, unique within the plugin. */
+  id: string;
+  label: string;
+  icon?: IconName;
+  /** Restrict to some collections; omitted means all. */
+  collections?: string[];
+  /** Final say on whether the button renders for a particular document. */
+  available?: (doc: PluginDocument) => boolean;
+  onSelect: (ctx: PluginDocumentActionContext) => void | Promise<void>;
+};
+
+export type PluginFieldComponent = {
+  /**
+   * Bare component name; schemas address it as `plugin:<name>`. One global
+   * namespace across plugins — a collision is rejected with an error and the
+   * first registration wins.
+   */
+  name: string;
+  /** Schema field types the component accepts. */
+  types: PluginFieldType[];
+  component: PluginComponentLoader<PluginFieldProps>;
+};
+
+/** The declarative API a plugin's setup function receives. */
+export interface CmsPluginApi {
+  /** The plugin's own id (its package name) — for display/debugging. */
+  readonly id: string;
+  /**
+   * Mint a short-lived credential for a preview service, scoped to one
+   * repository.
+   *
+   * This is how a plugin authenticates to something that trusts the CMS without
+   * ever holding the user's access token — that one authenticates everything
+   * else the CMS can do, and a plugin is third-party code by design. The token
+   * expires in minutes and every CMS endpoint refuses it.
+   *
+   * Rejects when the host cannot mint them (an older host, or one with no CMS
+   * session).
+   */
+  getPreviewToken(repositoryId: string): Promise<string>;
+  /** Register a screen at …/plugins/<pluginId>/<path> (repo-scoped). */
+  addRoute(route: PluginRoute): void;
+  /** Add a row to the sidebar linking to one of this plugin's routes. */
+  addSidebarLink(link: PluginSidebarLink): void;
+  /** Add an item to the user (avatar) menu. */
+  addUserMenuLink(link: PluginUserMenuLink): void;
+  /** Register an editor field component, addressed as `plugin:<name>`. */
+  registerFieldComponent(reg: PluginFieldComponent): void;
+  /**
+   * Add a button to the toolbar of an open document. Its handler can open one
+   * of this plugin's routes as a tab beside the editor — which is how a preview
+   * pane is built without the CMS knowing anything about previews.
+   */
+  addDocumentAction(action: PluginDocumentAction): void;
+}
+
+/** A plugin's setup function — the package entrypoint's default export. */
+export type PluginSetup = (cms: CmsPluginApi, options?: unknown) => void | Promise<void>;
+
+export type PluginStatus = "pending" | "ready" | "failed";
+
+/** One entry to load: how `loadPlugins` reaches a plugin's module. */
+export type PluginLoadEntry = {
+  /** The plugin id (package name). */
+  id: string;
+  /** Options forwarded as the setup function's second argument. */
+  options?: unknown;
+  /** Imports the plugin module (dynamic `import()` in both hosts). */
+  load: () => Promise<unknown>;
+};

package/app/vendor/realtime/src/__tests__/pure.test.ts

@@ -0,0 +1,58 @@
+import { colorForId, computeSplice } from "../pure";
+
+describe("computeSplice", () => {
+  // Applying the returned splice to `cur` must reproduce `next` exactly.
+  const apply = (cur: string, next: string) => {
+    const { index, deleteCount, insert } = computeSplice(cur, next);
+    return cur.slice(0, index) + insert + cur.slice(index + deleteCount);
+  };
+
+  const cases: Array<[string, string]> = [
+    ["", ""],
+    ["", "hello"],
+    ["hello", ""],
+    ["hello", "hello"],
+    ["hello", "hello world"], // append
+    ["hello world", "hello"], // truncate
+    ["hello", "jello"], // replace head
+    ["hello", "helLo"], // replace middle
+    ["cat", "cart"], // insert middle
+    ["cart", "cat"], // delete middle
+    ["aaaa", "aa"], // ambiguous repeats
+    ["The quick brown fox", "The slow brown fox"],
+  ];
+
+  test.each(cases)("apply(computeSplice(%j, %j)) === next", (cur, next) => {
+    expect(apply(cur, next)).toBe(next);
+  });
+
+  test("edits only the changed middle (preserves shared prefix/suffix)", () => {
+    // "Seeded title" -> "Seeded NEW title": prefix "Seeded ", suffix "title".
+    const s = computeSplice("Seeded title", "Seeded NEW title");
+    expect(s).toEqual({ index: 7, deleteCount: 0, insert: "NEW " });
+  });
+
+  test("a pure append does not delete anything", () => {
+    expect(computeSplice("abc", "abcdef")).toEqual({ index: 3, deleteCount: 0, insert: "def" });
+  });
+
+  test("a pure deletion inserts nothing", () => {
+    expect(computeSplice("abcdef", "abc")).toEqual({ index: 3, deleteCount: 3, insert: "" });
+  });
+});
+
+describe("colorForId", () => {
+  test("is deterministic for the same id", () => {
+    expect(colorForId("user-123")).toBe(colorForId("user-123"));
+  });
+
+  test("produces a valid hsl string", () => {
+    expect(colorForId("abc")).toMatch(/^hsl\(\d{1,3} 70% 45%\)$/);
+  });
+
+  test("varies across different ids", () => {
+    const colors = new Set(["a", "b", "c", "d", "e", "f", "g", "h"].map(colorForId));
+    // Not all identical — the hash spreads ids across hues.
+    expect(colors.size).toBeGreaterThan(1);
+  });
+});

package/app/vendor/realtime/src/__tests__/seeded-room.base64

@@ -0,0 +1 @@
+AQjYhJqjDwAEAQ9mOnNlby5tZXRhVGl0bGUJU0VPIHRpdGxlBAEHZjp0aXRsZQVBbHBoYSgBA3JlZwhmZWF0dXJlZAF4KAEDcmVnBWNvdW50AXxAQAAAKAEDcmVnC3Nlby5ub2luZGV4AXkoAQNyZWcGYmxvY2tzAXUCdgIIX3ZhcmlhbnR3BGhlcm8HaGVhZGluZ3cHV2VsY29tZXYCCF92YXJpYW50dwdtZXRyaWNzBWl0ZW1zdQF2AgVsYWJlbHcHRGVwbG95cwV2YWx1ZXcCMTQoAQNyZWcEdGFncwF1AncCZ293A2NtcygBBG1ldGEEYmFzZQF35AF7ImJsb2NrcyI6W3siX3ZhcmlhbnQiOiJoZXJvIiwiaGVhZGluZyI6IldlbGNvbWUifSx7Il92YXJpYW50IjoibWV0cmljcyIsIml0ZW1zIjpbeyJsYWJlbCI6IkRlcGxveXMiLCJ2YWx1ZSI6IjE0In1dfV0sImNvdW50IjozLCJmZWF0dXJlZCI6dHJ1ZSwic2VvIjp7Im1ldGFUaXRsZSI6IlNFTyB0aXRsZSIsIm5vaW5kZXgiOmZhbHNlfSwidGFncyI6WyJnbyIsImNtcyJdLCJ0aXRsZSI6IkFscGhhIn0A

package/app/vendor/realtime/src/__tests__/seeding.test.ts

@@ -0,0 +1,70 @@
+// What the server seeds has to be what the editor can render.
+//
+// The Go tests prove the collab server converges with itself. They cannot prove
+// the part the browser depends on: that Yjs decodes a seeded list into a real JS
+// array of plain objects. A control that renders a list checks `Array.isArray`
+// and shows nothing when that is false, which is indistinguishable — on screen —
+// from a document with no items. Mixed lists sat in exactly that state, so the
+// encoding gets a test rather than an assumption.
+//
+// The fixture is the literal update a seeded room sends a client, generated by
+// packages/collab's TestFixtureForYjsDecode (WRITE_FIXTURE=1). Regenerate it
+// there if the seeded shapes change.
+
+import { readFileSync } from "fs";
+import { join } from "path";
+import * as Y from "yjs";
+
+const FIELD_PREFIX = "f:";
+
+function seededDoc(): Y.Doc {
+  const base64 = readFileSync(join(__dirname, "seeded-room.base64"), "utf8").trim();
+  const doc = new Y.Doc();
+  Y.applyUpdate(doc, new Uint8Array(Buffer.from(base64, "base64")));
+  return doc;
+}
+
+describe("a room seeded by the Go server, read through Yjs", () => {
+  it("gives a mixed list back as an array the editor can render", () => {
+    const blocks = seededDoc().getMap("reg").get("blocks");
+
+    // The check every list control makes before it renders anything.
+    expect(Array.isArray(blocks)).toBe(true);
+    expect(blocks).toEqual([
+      { _variant: "hero", heading: "Welcome" },
+      { _variant: "metrics", items: [{ label: "Deploys", value: "14" }] },
+    ]);
+  });
+
+  it("keeps a variant's own nested list nested", () => {
+    const blocks = seededDoc().getMap("reg").get("blocks") as Record<string, unknown>[];
+    const metrics = blocks[1];
+    // An item whose fields arrived as something other than a plain object
+    // renders as an empty row inside a list that looks populated.
+    expect(Object.getPrototypeOf(metrics)).toBe(Object.prototype);
+    expect(Array.isArray(metrics.items)).toBe(true);
+  });
+
+  it("gives a list of primitives back as an array too", () => {
+    expect(seededDoc().getMap("reg").get("tags")).toEqual(["go", "cms"]);
+  });
+
+  it("puts scalars in the register and strings in their own text", () => {
+    const doc = seededDoc();
+    const reg = doc.getMap("reg");
+    expect(reg.get("featured")).toBe(true);
+    expect(reg.get("count")).toBe(3);
+    expect(doc.getText(`${FIELD_PREFIX}title`).toString()).toBe("Alpha");
+    // Nested group leaves land at their dotted path, which is what the field
+    // controls bind to.
+    expect(doc.getText(`${FIELD_PREFIX}seo.metaTitle`).toString()).toBe("SEO title");
+    expect(reg.get("seo.noindex")).toBe(false);
+  });
+
+  it("hands out a stable reference for an unchanged value", () => {
+    // useSyncExternalStore re-renders until getSnapshot returns the same value
+    // twice; a decoder that rebuilt the array per read would spin the editor.
+    const reg = seededDoc().getMap("reg");
+    expect(reg.get("blocks")).toBe(reg.get("blocks"));
+  });
+});

package/app/vendor/realtime/src/collab.ts

@@ -0,0 +1,308 @@
+import * as Y from "yjs";
+import { WebsocketProvider } from "y-websocket";
+import { colorForId, computeSplice } from "./pure";
+
+export { colorForId } from "./pure";
+
+// A collaborator's identity, surfaced to presence UI.
+export type CollabPeer = { id: string; name: string; color: string };
+
+// A connected collaborator plus the field they are currently focused on (null
+// when not editing any field). Drives the document's stacked presence avatars.
+export type CollabParticipant = { id: string; name: string; color: string; focus: string | null };
+
+// A live binding to one text field's Y.Text. Values converge across clients.
+export type CollabText = {
+  get(): string;
+  set(next: string): void;
+  // Peers currently focused on this field (excludes the local user).
+  peers(): CollabPeer[];
+  // Fires on value change OR presence change for this field. Returns unsubscribe.
+  subscribe(cb: () => void): () => void;
+};
+
+// A live binding to one scalar field (select/boolean/number/date) held as a
+// last-writer-wins register in the shared "reg" Y.Map.
+export type CollabRegister = {
+  get(): unknown;
+  set(next: unknown): void;
+  subscribe(cb: () => void): () => void;
+};
+
+export type CollabStatus = "connecting" | "connected" | "disconnected";
+
+export type CollabUser = { id: string; name: string; color?: string };
+
+// The per-document collaboration handle. Structurally matches design-system's
+// CollabApi so it can be handed to <ContentBrowser> without either package
+// importing the other.
+export type DocCollab = {
+  text(path: string): CollabText;
+  register(path: string): CollabRegister;
+  // Announce/clear which field this user is editing (null = not focused).
+  setFocus(path: string | null): void;
+  // Presence for any field path (text or not), excluding the local user.
+  peersAt(path: string): CollabPeer[];
+  // Presence anywhere under a group path ("seo" matches focus "seo.title"),
+  // used to highlight a collapsed group whose child a peer is editing.
+  peersUnder(prefix: string): CollabPeer[];
+  // Every connected collaborator (excluding self), for the document's stacked
+  // presence avatars, each with the field they are currently editing.
+  participants(): CollabParticipant[];
+  subscribeAwareness(cb: () => void): () => void;
+  // Monotonic counter bumped on every awareness change, for tick-based presence
+  // subscriptions (useSyncExternalStore) that then read peersAt/peersUnder.
+  awarenessVersion(): number;
+  status(): CollabStatus;
+  subscribeStatus(cb: () => void): () => void;
+  // Whether the provider has completed its initial sync with the server room.
+  // Distinct from status(): a socket is "connected" before the first sync-step
+  // exchange finishes, and anything that reads the shared doc to decide
+  // something (e.g. "is the body fragment empty?") must wait for this.
+  synced(): boolean;
+  subscribeSynced(cb: () => void): () => void;
+  // Opaque handles the body (ProseMirror) editor binds to in a later phase.
+  readonly ydoc: Y.Doc;
+  readonly awareness: WebsocketProvider["awareness"];
+  destroy(): void;
+};
+
+export type CreateDocCollabOptions = {
+  // Base WebSocket URL of the collab endpoint, e.g. "wss://host/collab/ws".
+  wsBase: string;
+  // Room = "<repositoryId>_<documentId>".
+  room: string;
+  user: CollabUser;
+  // Returns the current access token; called on every (re)connect so a refreshed
+  // token is used. The token rides the WebSocket subprotocol, never the URL.
+  getToken: () => string;
+};
+
+const FIELD_PREFIX = "f:";
+
+// Shallow equality of two peer lists (by id set, order-insensitive) so cached
+// snapshots keep a stable reference across awareness events with no real change.
+function samePeers(a: CollabPeer[], b: CollabPeer[]): boolean {
+  if (a.length !== b.length) return false;
+  const ids = new Set(a.map((p) => p.id));
+  return b.every((p) => ids.has(p.id));
+}
+
+// createDocCollab wires a Yjs doc to the collab server for one document.
+export function createDocCollab(opts: CreateDocCollabOptions): DocCollab {
+  const color = opts.user.color ?? colorForId(opts.user.id);
+  const ydoc = new Y.Doc();
+
+  // Authenticate via a query-string token, the standard y-websocket pattern.
+  // (A subprotocol token was tried first, but Chrome resets a connection when
+  // the client offers a subprotocol the server does not echo, and ygo's
+  // upgrader cannot be made to echo one.) The token is short-lived and the
+  // server's request logger records only the path, never the query string, so
+  // it is not leaked to logs. `params` is a live reference: refreshing it before
+  // a reconnect lets the socket pick up a newer token.
+  const params: Record<string, string> = { token: opts.getToken() };
+  if (typeof console !== "undefined") {
+    console.log(`[collab ${opts.room}] connecting to ${opts.wsBase}/${opts.room}`, {
+      hasToken: !!params.token,
+    });
+  }
+  const provider = new WebsocketProvider(opts.wsBase, opts.room, ydoc, { params });
+  const awareness = provider.awareness;
+  awareness.setLocalStateField("user", { id: opts.user.id, name: opts.user.name, color });
+  awareness.setLocalStateField("focus", null);
+
+  // ---- presence snapshots (stable refs for useSyncExternalStore) ----
+  let peerBuckets = new Map<string, CollabPeer[]>();
+  const awarenessListeners = new Set<() => void>();
+  const recomputePeers = () => {
+    const next = new Map<string, CollabPeer[]>();
+    awareness.getStates().forEach((state, clientId) => {
+      if (clientId === awareness.clientID) return; // exclude self
+      const focus = state?.focus as string | null | undefined;
+      const user = state?.user as CollabPeer | undefined;
+      if (!focus || !user) return;
+      const list = next.get(focus) ?? [];
+      list.push(user);
+      next.set(focus, list);
+    });
+    // Preserve array references where the peer set is unchanged.
+    const merged = new Map<string, CollabPeer[]>();
+    const paths = new Set([...peerBuckets.keys(), ...next.keys()]);
+    paths.forEach((path) => {
+      const prev = peerBuckets.get(path) ?? [];
+      const cur = next.get(path) ?? [];
+      merged.set(path, samePeers(prev, cur) ? prev : cur);
+    });
+    peerBuckets = merged;
+  };
+  let awarenessVer = 0;
+  recomputePeers();
+  awareness.on("change", () => {
+    recomputePeers();
+    awarenessVer++;
+    awarenessListeners.forEach((cb) => cb());
+  });
+  const emptyPeers: CollabPeer[] = [];
+
+  // peersUnder returns every peer whose focus is the prefix itself or nested
+  // beneath it ("seo" matches "seo.title"), deduped by user id.
+  const peersUnder = (prefix: string): CollabPeer[] => {
+    const seen = new Set<string>();
+    const out: CollabPeer[] = [];
+    peerBuckets.forEach((peers, focus) => {
+      if (focus === prefix || focus.startsWith(prefix + ".")) {
+        for (const p of peers) {
+          if (!seen.has(p.id)) {
+            seen.add(p.id);
+            out.push(p);
+          }
+        }
+      }
+    });
+    return out;
+  };
+
+  // ---- connection status ----
+  let status: CollabStatus = "connecting";
+  const statusListeners = new Set<() => void>();
+  const tag = `[collab ${opts.room}]`;
+  provider.on("status", (e: { status: "connecting" | "connected" | "disconnected" }) => {
+    status = e.status;
+    // Refresh the query token before the next connect so a reconnect after a
+    // token rotation uses the current one.
+    if (e.status !== "connected") params.token = opts.getToken();
+    if (typeof console !== "undefined") console.debug(`${tag} status: ${e.status}`);
+    statusListeners.forEach((cb) => cb());
+  });
+  const syncListeners = new Set<() => void>();
+  provider.on("sync", (isSynced: boolean) => {
+    if (typeof console !== "undefined") console.debug(`${tag} synced: ${isSynced}`);
+    syncListeners.forEach((cb) => cb());
+  });
+  // Surface handshake rejections (e.g. a blocked cross-origin upgrade or an
+  // invalid token) that otherwise look like a silent "connected but no sync".
+  provider.on("connection-close", (event: CloseEvent | null) => {
+    if (event && (event.code !== 1000 || event.reason) && typeof console !== "undefined") {
+      console.warn(`${tag} connection closed: code=${event.code} reason=${event.reason || "(none)"}`);
+    }
+  });
+  provider.on("connection-error", (event: Event) => {
+    if (typeof console !== "undefined") console.warn(`${tag} connection error`, event);
+  });
+  // One-shot probe: report the raw socket state a few seconds in, so a hung
+  // upgrade (readyState stays 0 = CONNECTING) is distinguishable from a silent
+  // close (3 = CLOSED) or a working connection (1 = OPEN).
+  setTimeout(() => {
+    if (typeof console === "undefined") return;
+    const p = provider as unknown as { ws?: WebSocket | null; wsconnected?: boolean };
+    const rs = p.ws ? p.ws.readyState : "no-socket";
+    const names: Record<number, string> = { 0: "CONNECTING", 1: "OPEN", 2: "CLOSING", 3: "CLOSED" };
+    console.log(`${tag} probe`, {
+      readyState: typeof rs === "number" ? `${rs} (${names[rs]})` : rs,
+      wsconnected: p.wsconnected,
+      synced: provider.synced,
+    });
+  }, 3000);
+
+  // ---- text bindings (memoized per path) ----
+  const textCache = new Map<string, CollabText>();
+  const textBinding = (path: string): CollabText => {
+    const existing = textCache.get(path);
+    if (existing) return existing;
+    const ytext = ydoc.getText(FIELD_PREFIX + path);
+    const binding: CollabText = {
+      get: () => ytext.toString(),
+      set: (next: string) => {
+        const cur = ytext.toString();
+        if (cur === next) return;
+        // Minimal splice: replace only the changed middle so unaffected text
+        // (and other clients' concurrent edits there) survive.
+        const { index, deleteCount, insert } = computeSplice(cur, next);
+        ydoc.transact(() => {
+          if (deleteCount > 0) ytext.delete(index, deleteCount);
+          if (insert) ytext.insert(index, insert);
+        });
+      },
+      peers: () => peerBuckets.get(path) ?? emptyPeers,
+      subscribe: (cb: () => void) => {
+        const onText = () => cb();
+        ytext.observe(onText);
+        awarenessListeners.add(cb);
+        return () => {
+          ytext.unobserve(onText);
+          awarenessListeners.delete(cb);
+        };
+      },
+    };
+    textCache.set(path, binding);
+    return binding;
+  };
+
+  // ---- register bindings (memoized per path) ----
+  const reg = ydoc.getMap("reg");
+  const regCache = new Map<string, CollabRegister>();
+  const registerBinding = (path: string): CollabRegister => {
+    const existing = regCache.get(path);
+    if (existing) return existing;
+    const binding: CollabRegister = {
+      get: () => reg.get(path),
+      set: (next: unknown) => {
+        if (reg.get(path) === next) return;
+        reg.set(path, next);
+      },
+      subscribe: (cb: () => void) => {
+        // Y.Map observe fires for any key; the component re-reads its own key.
+        const onChange = () => cb();
+        reg.observe(onChange);
+        return () => reg.unobserve(onChange);
+      },
+    };
+    regCache.set(path, binding);
+    return binding;
+  };
+
+  return {
+    text: textBinding,
+    register: registerBinding,
+    setFocus: (path: string | null) => awareness.setLocalStateField("focus", path),
+    peersAt: (path: string) => peerBuckets.get(path) ?? emptyPeers,
+    peersUnder,
+    participants: () => {
+      const byId = new Map<string, CollabParticipant>();
+      awareness.getStates().forEach((state, clientId) => {
+        if (clientId === awareness.clientID) return; // exclude self
+        const user = state?.user as CollabPeer | undefined;
+        if (!user) return;
+        const focus = (state?.focus as string | null | undefined) ?? null;
+        const existing = byId.get(user.id);
+        // Dedup by user id (multiple tabs); prefer an entry that has a focus.
+        if (!existing || (!existing.focus && focus)) {
+          byId.set(user.id, { id: user.id, name: user.name, color: user.color, focus });
+        }
+      });
+      return [...byId.values()];
+    },
+    awarenessVersion: () => awarenessVer,
+    subscribeAwareness: (cb: () => void) => {
+      awarenessListeners.add(cb);
+      return () => awarenessListeners.delete(cb);
+    },
+    status: () => status,
+    subscribeStatus: (cb: () => void) => {
+      statusListeners.add(cb);
+      return () => statusListeners.delete(cb);
+    },
+    synced: () => provider.synced,
+    subscribeSynced: (cb: () => void) => {
+      syncListeners.add(cb);
+      return () => syncListeners.delete(cb);
+    },
+    ydoc,
+    awareness,
+    destroy: () => {
+      awareness.setLocalState(null);
+      provider.destroy();
+      ydoc.destroy();
+    },
+  };
+}