@growgroup/visual-editor 0.4.1 → 0.7.0

package/src/editor/collab/morph.ts

@@ -0,0 +1,113 @@
+/**
+ * 他人の変更(共有する本文)を、編集中の紙面(#artboard)へ当てる。idiomorph で差分だけを書き換え、
+ * エディタが紙面に持っているもの(選択・編集用の属性・一時クラス・選択枠などの表示専用ノード)は残す。
+ */
+
+import { Idiomorph } from 'idiomorph';
+
+/** 紙面の中身ではなく、エディタが差し込んでいる表示専用のノード。当て込みの間だけ外して、あとで戻す */
+const PRESERVE_SELECTOR = [
+  '.selection-box',
+  '.marquee-selection-box',
+  '.drag-ghost',
+  '.flex-drop-indicator',
+  '.nesting-drop-indicator',
+  '.auto-layout-drop-indicator',
+  '.drawing-preview',
+  '.gg-comment-layer',
+  '.gg-collab-layer',
+  '.gg-crop-ui',
+  '#gg-measure-layer',
+  '#gg-smart-guides',
+  '#gg-reorder-indicator',
+].join(',');
+
+/**
+ * エディタだけが付ける属性。共有する本文(getCleanHtml)には無いので、当てるときに消させない。
+ * data-gg-base / data-gg-prestyle / data-gg-pre-overflow は開いた直後の指紋(保存時の書き戻しの判定に使う)
+ */
+const EDITOR_ATTRS = new Set([
+  'contenteditable',
+  'data-editable',
+  'data-element-id',
+  'data-shape-type',
+  'data-inline',
+  'data-gg-base',
+  'data-gg-prestyle',
+  'data-gg-pre-overflow',
+]);
+
+/** getCleanHtml が消す一時クラス。class 属性は丸ごと置き換わるので、当てたあとに付け直す */
+const TRANSIENT_CLASSES = [
+  'selected', 'dragging', 'editing', 'rotating', 'panning',
+  'hover-preview', 'marquee-hover', 'marquee-active', 'text-editable-hover', 'drag-ghost',
+];
+
+const isEditorAttr = (name: string) => EDITOR_ATTRS.has(name) || name.startsWith('data-original-');
+
+/** 比べるための姿(エディタの属性・一時クラス・表示専用ノード・書き戻しの印を除く) */
+function comparableHtml(el: Element): string {
+  const clone = el.cloneNode(true) as Element;
+  clone.querySelectorAll(PRESERVE_SELECTOR).forEach((n) => n.remove());
+  for (const node of [clone, ...Array.from(clone.querySelectorAll('*'))]) {
+    for (const attr of Array.from(node.attributes)) {
+      if (isEditorAttr(attr.name) || attr.name === 'data-gg-dirty') node.removeAttribute(attr.name);
+    }
+    node.classList.remove(...TRANSIENT_CLASSES);
+    if (node.getAttribute('class') === '') node.removeAttribute('class');
+  }
+  return clone.outerHTML;
+}
+
+/**
+ * 紙面を html の姿にする。
+ * hold(打鍵中の要素)には触らない。hold に掛かる変更があったら heldChanged が立つ(blur のあとにもう一度当てる)
+ */
+export function morphArtboard(artboard: HTMLElement, html: string, hold: HTMLElement | null): { heldChanged: boolean } {
+  // 表示専用のノード(一番外側だけ)を外す。消させないだけだと、似た形の本文の要素として使い回されることがある
+  const chrome = Array.from(artboard.querySelectorAll<HTMLElement>(PRESERVE_SELECTOR)).filter(
+    (el) => !el.parentElement?.closest(PRESERVE_SELECTOR),
+  );
+  const placements = chrome.map((el) => ({ el, parent: el.parentElement, next: el.nextSibling }));
+  chrome.forEach((el) => el.remove());
+
+  const transient: [Element, string[]][] = [];
+  artboard.querySelectorAll(TRANSIENT_CLASSES.map((c) => `.${c}`).join(',')).forEach((el) => {
+    transient.push([el, TRANSIENT_CLASSES.filter((c) => el.classList.contains(c))]);
+  });
+
+  let heldChanged = false;
+  try {
+    Idiomorph.morph(artboard, html, {
+      morphStyle: 'innerHTML',
+      callbacks: {
+        beforeNodeMorphed: (oldNode, newNode) => {
+          if (hold && oldNode === hold) {
+            if (!heldChanged && (newNode.nodeType !== 1 || comparableHtml(hold) !== comparableHtml(newNode as Element))) {
+              heldChanged = true;
+            }
+            return false;
+          }
+          return true;
+        },
+        beforeNodeRemoved: (node) => {
+          if (hold && (node === hold || node.contains?.(hold))) {
+            heldChanged = true;
+            return false;
+          }
+          return true;
+        },
+        beforeAttributeUpdated: (name, _node, mutation) => !(mutation === 'remove' && isEditorAttr(name)),
+      },
+    });
+  } finally {
+    for (const [el, classes] of transient) {
+      if (el.isConnected) el.classList.add(...classes);
+    }
+    for (const { el, parent, next } of placements) {
+      const target = parent && artboard.contains(parent) ? parent : artboard;
+      target.insertBefore(el, next && next.parentNode === target ? next : null);
+    }
+  }
+  return { heldChanged };
+}

package/src/editor/collab/room.ts

@@ -0,0 +1,82 @@
+/**
+ * 中継(gg-manager の hocuspocus-server)が保存する部屋名の形。
+ *
+ * 形を外れた部屋も**中継はされる**ので動いているように見えるが、サーバーは保存しない
+ * (全員が抜けるか、翌日の掃除で中身が消える)。繋ぐ前にここで検査し、外れたら共同編集を始めない。
+ *
+ * 規則(取り決め §3 / サーバー側の persistence.ts と同じ):
+ * - 部屋名は `wf/<room>__<route の encodeURIComponent>` か `wf/<room>__@project`
+ * - room は `[A-Za-z0-9_-]` の 8〜100 文字(`__` が混ざっても、後半は `@` か `%` で始まるので境界は一意)
+ * - route の部分は `/` 始まり = `%2F` 始まりで、`encodeURIComponent` の正規形
+ *   (decode してから encode し直すと同じ文字列。16 進は大文字)
+ * - encode 後の route は 1024 文字以内
+ *
+ * この検査は殻(書き戻し役・ホスト側)でも使えるように公開している(`checkCollabRoom`)。
+ * 部屋名そのものが鍵なので、外れたことを知らせるときも名前は出さない。
+ */
+
+export type CollabRoomCheck = { ok: true } | { ok: false; reason: string };
+
+/** サーバーが保存する部屋名(persistence.ts の WF_DOCUMENT_NAME と同じ) */
+const WF_DOCUMENT_NAME = /^wf\/([A-Za-z0-9_-]{8,100})__(@project|%2F[A-Za-z0-9%._~!*'()-]*)$/;
+/** 部屋名を分けるためだけの緩い形(どこが外れているかを言うために使う) */
+const WF_LOOSE = /^wf\/([A-Za-z0-9_-]+)__([\s\S]*)$/;
+const PROJECT_PAGE = '@project';
+/** encodeURIComponent 済み route の長さの上限 */
+const ROUTE_MAX_LENGTH = 1024;
+
+const SHAPE = '部屋名は wf/<room>__<route> か wf/<room>__@project の形にする';
+const ROOM = 'room は [A-Za-z0-9_-] の 8〜100 文字にする';
+const ROUTE_HEAD = 'route の部分は @project か、/ 始まりの route を encodeURIComponent した形(%2F…)にする';
+const ROUTE_CANONICAL = 'route は encodeURIComponent の正規形にする(16 進は大文字。%2f は不可)';
+const ROUTE_LENGTH = `encode 後の route は ${ROUTE_MAX_LENGTH} 文字以内にする`;
+
+/** encodeURIComponent の正規形か(長さの上限も含めて、サーバーの isCanonicalEncodedRoute と同じ) */
+function isCanonicalEncodedRoute(encoded: string): boolean {
+  if (encoded.length > ROUTE_MAX_LENGTH) return false;
+  try {
+    return encodeURIComponent(decodeURIComponent(encoded)) === encoded;
+  } catch {
+    return false; // 壊れた % 列(URIError)
+  }
+}
+
+/**
+ * 部屋名がサーバーに保存される形か。
+ * 外れていれば理由を返す(繋がずに、接続状態へエラーとして出すため)
+ */
+export function checkCollabRoom(name: unknown): CollabRoomCheck {
+  if (typeof name !== 'string' || !name) return { ok: false, reason: SHAPE };
+  if (WF_DOCUMENT_NAME.test(name) && isCanonicalEncodedRoute(pageOf(name))) return { ok: true };
+
+  const loose = WF_LOOSE.exec(name);
+  let room: string;
+  let page: string;
+  if (loose) {
+    room = loose[1];
+    page = loose[2];
+  } else {
+    // room に使えない文字が入っているときも「room が悪い」と言えるようにする
+    const rest = name.startsWith('wf/') ? name.slice(3) : null;
+    const at = rest ? rest.indexOf('__') : -1;
+    if (rest == null || at < 0) return { ok: false, reason: SHAPE };
+    room = rest.slice(0, at);
+    page = rest.slice(at + 2);
+  }
+  if (!/^[A-Za-z0-9_-]{8,100}$/.test(room)) return { ok: false, reason: ROOM };
+  if (page === PROJECT_PAGE) return { ok: true };
+  if (page.length > ROUTE_MAX_LENGTH) return { ok: false, reason: ROUTE_LENGTH };
+  // encode していない(/ のまま)・@project でも %2F でもない
+  if (page.startsWith('/') || (!page.startsWith('%2F') && isCanonicalEncodedRoute(page))) {
+    return { ok: false, reason: ROUTE_HEAD };
+  }
+  if (!isCanonicalEncodedRoute(page)) return { ok: false, reason: ROUTE_CANONICAL };
+  // ここまで通って全体の形に合わないのは、route に使えない文字が残っているとき
+  return { ok: false, reason: ROUTE_HEAD };
+}
+
+/** `wf/<room>__<page>` の page の部分(検査を通った名前にだけ使う) */
+function pageOf(name: string): string {
+  const m = WF_DOCUMENT_NAME.exec(name);
+  return m ? m[2] : '';
+}

package/src/editor/collab/runtime.ts

@@ -0,0 +1,442 @@
+/**
+ * 共同編集の実体。io.collab があるときだけ動的に読まれる(yjs / Hocuspocus / idiomorph / fast-diff を束ねる側)。
+ *
+ * - 案件の部屋: 居場所(`{ user, kind: "editor", contentId, route }`)・書き戻し役の数・`Y.Map("pages")` の rev
+ * - ページの部屋: いま編集中のページの本文(binding.ts)と、選択・カーソル・打鍵中の要素
+ *   (`{ user, kind: "editor", selection, cursor, editing }`)
+ * 表示は store.ts に書くだけ。ヘッダーや紙面の描画はそれを購読する
+ */
+
+import { WebSocketStatus } from '@hocuspocus/provider';
+import type * as Y from 'yjs';
+import type { EditorCollab } from '../../io';
+import { acquireRoom, acquireSocket, peekRoom, releaseRoom, releaseSocket, type Room } from './connection';
+import { colorFor } from './color';
+import { checkCollabRoom } from './room';
+import { PageBinding } from './binding';
+import {
+  collabStore,
+  setCollabSharedReader,
+  type CollabPagePeer,
+  type CollabPeer,
+  type CollabStatus,
+  type CollabUser,
+} from './store';
+
+/** カーソルを送る間隔(ms) */
+const CURSOR_THROTTLE_MS = 50;
+/** 案件の部屋の pages の rev を進める間隔(ms。取り決め §5 の「1 秒に 1 回まで」) */
+const REV_INTERVAL_MS = 1000;
+/** 見るだけの紙面を読み直すために入った部屋を、抜けるまでの猶予(ms) */
+const PREVIEW_ROOM_GRACE_MS = 15000;
+/** 見るだけの紙面の本文を待つ上限(ms) */
+const READ_SHARED_TIMEOUT_MS = 4000;
+
+type AwarenessState = Record<string, unknown>;
+
+function toUser(raw: unknown): CollabUser | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const { id, name, color } = raw as { id?: unknown; name?: unknown; color?: unknown };
+  if (typeof id !== 'string' || !id) return null;
+  const label = typeof name === 'string' && name.trim() ? name : id;
+  return { id, name: label, color: colorFor(id, typeof color === 'string' ? color : undefined) };
+}
+
+function toCursor(raw: unknown): { x: number; y: number } | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const { x, y } = raw as { x?: unknown; y?: unknown };
+  return typeof x === 'number' && typeof y === 'number' && Number.isFinite(x) && Number.isFinite(y) ? { x, y } : null;
+}
+
+function waitSynced(room: Room, timeoutMs: number): Promise<boolean> {
+  if (room.provider.synced) return Promise.resolve(true);
+  return new Promise((resolve) => {
+    const done = () => {
+      clearTimeout(timer);
+      room.provider.off('synced', done);
+      resolve(room.provider.synced);
+    };
+    const timer = setTimeout(done, timeoutMs);
+    room.provider.on('synced', done);
+  });
+}
+
+export type PageSession = {
+  room: Room;
+  contentId: string;
+};
+
+/** 編集中の紙面と部屋の本文の束縛(binding.ts)のうち、エディタから呼ぶもの */
+export type CollabDocBinding = {
+  scheduleSend(): void;
+  flush(): void;
+  undo(): void;
+  redo(): void;
+  sharedHtml(): string | null;
+  destroy(): void;
+};
+
+export type CollabRuntime = {
+  readonly config: EditorCollab;
+  readonly self: CollabUser;
+  /** 編集中のページが変わった(null = どのページも編集していない) */
+  setPage(contentId: string | null): void;
+  setSelection(anchors: string[]): void;
+  setCursor(cursor: { x: number; y: number } | null): void;
+  setEditing(anchor: string | null): void;
+  /** いまのページの部屋。入っていなければ null */
+  page(): PageSession | null;
+  /**
+   * 初期化を終えた紙面をページの部屋の本文につなぐ。そのページの部屋に入っていなければ null。
+   * initialShared は読み込み直後の姿(encode 済み。種まきに使う)
+   */
+  bind(options: { doc: Document; contentId: string; initialShared: string; onApplied: (artboardHtml: string) => void }): CollabDocBinding | null;
+  /** 他の人がそのページ(route)の本文を送った。登録した時点で rev のあるページにも 1 回ずつ呼ぶ */
+  onRemoteRev(listener: (route: string) => void): () => void;
+  /** そのページの部屋の本文(decode 済み)。部屋に入って同期を待つ。空・同期できなければ null */
+  readShared(contentId: string): Promise<string | null>;
+  destroy(): void;
+};
+
+export function createCollabRuntime(config: EditorCollab): CollabRuntime {
+  const self: CollabUser = { id: config.user.id, name: config.user.name || config.user.id, color: colorFor(config.user.id, config.user.color) };
+  const encode = config.encode ?? ((clean: string) => clean);
+  const decodeFor = (contentId: string) => (shared: string) => (config.decode ? config.decode(shared, contentId) : shared);
+  const socket = acquireSocket(config.url);
+  const project = acquireRoom(config.url, config.projectRoom, config.token);
+  const revOrigin = { collab: 'rev' };
+  let destroyed = false;
+  let currentContentId: string | null = null;
+  let page: (PageSession & { off: () => void }) | null = null;
+  let localPending = false;
+  let roomError: string | null = null;
+  let selection: string[] = [];
+  let editing: string | null = null;
+  let cursorLatest: { x: number; y: number } | null = null;
+  let cursorSent: string | undefined;
+  let cursorTimer: ReturnType<typeof setTimeout> | null = null;
+
+  collabStore.set({
+    enabled: true,
+    ready: false,
+    self,
+    requireBridge: !!config.requireBridge,
+    status: 'offline',
+    peers: [],
+    pagePeers: [],
+    bridges: 0,
+    pageActive: false,
+    pending: false,
+    unsynced: 0,
+    canUndo: false,
+    canRedo: false,
+    roomError: null,
+  });
+
+  /**
+   * 中継が保存する部屋名か。外れていれば null を返す(その部屋には繋がない)。
+   * report は編集中のページのときだけ true にする(見るだけの紙面の分で接続状態を赤くしない)
+   */
+  const warned = new Set<string>();
+  const usableRoom = (name: string | null, report = false): string | null => {
+    if (!name) return null;
+    const room = checkCollabRoom(name);
+    if (room.ok) return name;
+    if (!warned.has(room.reason)) {
+      warned.add(room.reason);
+      console.warn(`[collab] 部屋名が中継に保存されない形なので、この部屋は共同編集しません: ${room.reason}`);
+    }
+    if (report) roomError = room.reason;
+    return null;
+  };
+
+  const setProjectPresence = () => {
+    project.provider.awareness?.setLocalState({
+      user: self,
+      kind: 'editor',
+      contentId: currentContentId,
+      route: currentContentId ? config.routeFor(currentContentId) : null,
+    });
+  };
+
+  const readPeers = () => {
+    const aw = project.provider.awareness;
+    if (!aw) return;
+    const peers: CollabPeer[] = [];
+    const seen = new Set<string>();
+    let bridges = 0;
+    const states = Array.from(aw.getStates().entries()).sort((a, b) => a[0] - b[0]);
+    for (const [clientId, raw] of states) {
+      if (clientId === aw.clientID || !raw) continue;
+      const state = raw as AwarenessState;
+      if (state.kind === 'bridge') {
+        bridges += 1;
+        continue;
+      }
+      if (state.kind !== 'editor') continue;
+      const user = toUser(state.user);
+      // 同じ人が別のタブで開いていても 1 人として出す(自分の別タブは出さない)
+      if (!user || user.id === self.id || seen.has(user.id)) continue;
+      seen.add(user.id);
+      peers.push({
+        clientId,
+        user,
+        contentId: typeof state.contentId === 'string' ? state.contentId : null,
+        route: typeof state.route === 'string' ? state.route : null,
+      });
+    }
+    collabStore.set({ peers, bridges });
+  };
+
+  const readPagePeers = () => {
+    const aw = page?.room.provider.awareness;
+    if (!aw) {
+      collabStore.set({ pagePeers: [] });
+      return;
+    }
+    const list: CollabPagePeer[] = [];
+    aw.getStates().forEach((raw, clientId) => {
+      if (clientId === aw.clientID || !raw) return;
+      const state = raw as AwarenessState;
+      if (state.kind !== 'editor') return;
+      const user = toUser(state.user);
+      if (!user) return;
+      list.push({
+        clientId,
+        user,
+        selection: Array.isArray(state.selection) ? state.selection.filter((v): v is string => typeof v === 'string') : [],
+        cursor: toCursor(state.cursor),
+        editing: typeof state.editing === 'string' ? state.editing : null,
+      });
+    });
+    list.sort((a, b) => a.clientId - b.clientId);
+    collabStore.set({ pagePeers: list });
+  };
+
+  const refresh = () => {
+    if (destroyed) return;
+    const connected = socket.status === WebSocketStatus.Connected;
+    const target = page?.room ?? project;
+    const unsynced = page ? page.room.provider.unsyncedChanges : 0;
+    const status: CollabStatus = roomError
+      ? 'error'
+      : !connected
+        ? 'offline'
+        : !target.provider.synced || unsynced > 0 || localPending
+          ? 'syncing'
+          : 'synced';
+    collabStore.set({ status, unsynced, roomError, ready: project.provider.synced || collabStore.get().ready });
+  };
+
+  const setLocalPending = (pending: boolean) => {
+    if (pending === localPending) return;
+    localPending = pending;
+    refresh();
+  };
+
+  // ---- 案件の部屋の pages(rev)
+  const pagesMap = project.doc.getMap<unknown>('pages');
+  const revListeners = new Set<(route: string) => void>();
+  const onPages = (event: Y.YMapEvent<unknown>, tx: Y.Transaction) => {
+    if (tx.origin === revOrigin) return;
+    event.keysChanged.forEach((route) => revListeners.forEach((listener) => listener(route)));
+  };
+  pagesMap.observe(onPages);
+  const revTimers = new Map<string, { last: number; timer: ReturnType<typeof setTimeout> | null }>();
+  const writeRev = (route: string) => {
+    if (destroyed) return;
+    project.doc.transact(() => {
+      const prev = pagesMap.get(route) as { rev?: unknown } | undefined;
+      const rev = typeof prev?.rev === 'number' ? prev.rev + 1 : 1;
+      pagesMap.set(route, { rev, by: self.id, at: new Date().toISOString() });
+    }, revOrigin);
+  };
+  const bumpRev = (route: string) => {
+    const entry = revTimers.get(route) ?? { last: 0, timer: null };
+    revTimers.set(route, entry);
+    if (entry.timer) return;
+    const wait = REV_INTERVAL_MS - (Date.now() - entry.last);
+    if (wait <= 0) {
+      entry.last = Date.now();
+      writeRev(route);
+      return;
+    }
+    entry.timer = setTimeout(() => {
+      entry.timer = null;
+      entry.last = Date.now();
+      writeRev(route);
+    }, wait);
+  };
+
+  const onProjectAwareness = () => readPeers();
+  project.provider.awareness?.on('change', onProjectAwareness);
+  project.provider.on('synced', refresh);
+  socket.on('status', refresh);
+  setProjectPresence();
+  readPeers();
+  refresh();
+
+  // 共同編集中のページ切替で、部屋に同期済みの本文があればそれを使わせる
+  setCollabSharedReader((contentId) => {
+    const name = usableRoom(config.roomFor(contentId));
+    const room = name ? peekRoom(config.url, name) : null;
+    if (!room || !room.provider.synced) return null;
+    const text = room.doc.getText('html').toString();
+    return text ? decodeFor(contentId)(text) : null;
+  });
+
+  const joinPage = (contentId: string, name: string) => {
+    const room = acquireRoom(config.url, name, config.token);
+    selection = [];
+    editing = null;
+    cursorLatest = null;
+    cursorSent = undefined;
+    room.provider.awareness?.setLocalState({ user: self, kind: 'editor', selection, cursor: null, editing });
+    const onAwareness = () => readPagePeers();
+    room.provider.awareness?.on('change', onAwareness);
+    room.provider.on('synced', refresh);
+    room.provider.on('unsyncedChanges', refresh);
+    page = {
+      room,
+      contentId,
+      off: () => {
+        room.provider.awareness?.off('change', onAwareness);
+        room.provider.off('synced', refresh);
+        room.provider.off('unsyncedChanges', refresh);
+      },
+    };
+    readPagePeers();
+  };
+
+  const leavePage = () => {
+    if (!page) return;
+    page.off();
+    releaseRoom(page.room);
+    page = null;
+    collabStore.set({ pagePeers: [] });
+  };
+
+  const sendCursor = () => {
+    const aw = page?.room.provider.awareness;
+    if (!aw) return;
+    const key = JSON.stringify(cursorLatest);
+    if (key === cursorSent) return;
+    cursorSent = key;
+    aw.setLocalStateField('cursor', cursorLatest);
+  };
+
+  return {
+    config,
+    self,
+    setPage(contentId) {
+      if (destroyed) return;
+      currentContentId = contentId;
+      setProjectPresence();
+      // 部屋名が保存されない形のページは、繋がずにエラーを出す(自動保存は今までどおり動く)
+      roomError = null;
+      const name = contentId ? usableRoom(config.roomFor(contentId), true) : null;
+      if (page && contentId && name && page.room.name === name) {
+        page.contentId = contentId;
+      } else {
+        leavePage();
+        if (contentId && name) joinPage(contentId, name);
+      }
+      collabStore.set({ pageActive: !!page, pending: false });
+      refresh();
+    },
+    setSelection(anchors) {
+      if (JSON.stringify(anchors) === JSON.stringify(selection)) return;
+      selection = anchors;
+      page?.room.provider.awareness?.setLocalStateField('selection', anchors);
+    },
+    setCursor(cursor) {
+      cursorLatest = cursor;
+      if (cursorTimer) return;
+      sendCursor();
+      cursorTimer = setTimeout(() => {
+        cursorTimer = null;
+        sendCursor();
+      }, CURSOR_THROTTLE_MS);
+    },
+    setEditing(anchor) {
+      if (anchor === editing) return;
+      editing = anchor;
+      page?.room.provider.awareness?.setLocalStateField('editing', anchor);
+    },
+    page: () => (page ? { room: page.room, contentId: page.contentId } : null),
+    bind({ doc, contentId, initialShared, onApplied }) {
+      if (destroyed || !page || page.contentId !== contentId) return null;
+      const route = config.routeFor(contentId);
+      const binding = new PageBinding({
+        room: page.room,
+        doc,
+        initialShared,
+        encode,
+        decode: decodeFor(contentId),
+        onApplied,
+        onLocalSent: () => {
+          if (route) bumpRev(route);
+        },
+        onState: (state) => {
+          collabStore.set({ pending: state.pending, canUndo: state.canUndo, canRedo: state.canRedo });
+          setLocalPending(state.localPending);
+        },
+      });
+      return {
+        scheduleSend: () => binding.scheduleSend(),
+        flush: () => binding.flush(),
+        undo: () => binding.undo(),
+        redo: () => binding.redo(),
+        sharedHtml: () => binding.sharedHtml(),
+        destroy: () => {
+          binding.destroy();
+          collabStore.set({ pending: false, canUndo: false, canRedo: false });
+          setLocalPending(false);
+        },
+      };
+    },
+    onRemoteRev(listener) {
+      revListeners.add(listener);
+      pagesMap.forEach((_value, route) => listener(route));
+      return () => {
+        revListeners.delete(listener);
+      };
+    },
+    async readShared(contentId) {
+      const name = usableRoom(config.roomFor(contentId));
+      if (destroyed || !name) return null;
+      const fresh = !peekRoom(config.url, name);
+      const room = acquireRoom(config.url, name, config.token);
+      // 見るだけの紙面のために入る部屋では、居場所を出さない
+      if (fresh) room.provider.awareness?.setLocalState(null);
+      try {
+        if (!(await waitSynced(room, READ_SHARED_TIMEOUT_MS))) return null;
+        const text = room.doc.getText('html').toString();
+        return text ? decodeFor(contentId)(text) : null;
+      } finally {
+        releaseRoom(room, PREVIEW_ROOM_GRACE_MS);
+      }
+    },
+    destroy() {
+      if (destroyed) return;
+      leavePage();
+      // 間引き中の rev は捨てずに書く
+      revTimers.forEach((entry, route) => {
+        if (!entry.timer) return;
+        clearTimeout(entry.timer);
+        entry.timer = null;
+        writeRev(route);
+      });
+      destroyed = true;
+      if (cursorTimer) clearTimeout(cursorTimer);
+      setCollabSharedReader(null);
+      pagesMap.unobserve(onPages);
+      project.provider.awareness?.off('change', onProjectAwareness);
+      project.provider.off('synced', refresh);
+      socket.off('status', refresh);
+      releaseRoom(project);
+      releaseSocket(config.url);
+      collabStore.reset();
+    },
+  };
+}

package/src/editor/collab/signals.ts

@@ -0,0 +1,11 @@
+/**
+ * EditorCanvas と共同編集の間の合図(依存なし)。
+ * EditorCanvas は初期化(initLayout)を終えた文書をこのイベントで知らせる(io.collab があるときだけ)。
+ */
+
+/** 「この文書は読み込みと初期化を終えた」。detail は CollabDocumentReadyDetail */
+export const COLLAB_DOCUMENT_READY_EVENT = 'gg:editor-document-ready';
+/** 初期化を終えた文書の <html> に付く印。値はそのときのページ(イベントを聞き逃したときの確認用) */
+export const COLLAB_DOCUMENT_READY_ATTR = 'data-gg-ready';
+
+export type CollabDocumentReadyDetail = { doc: Document; contentId: string | null };