@growgroup/visual-editor 0.4.0 → 0.6.0

package/src/editor/collab/connection.ts

@@ -0,0 +1,110 @@
+/**
+ * Hocuspocus への接続(1 タブ 1 本の WebSocket に部屋を相乗りさせる)。
+ *
+ * - WebSocket は URL ごとに 1 本(HocuspocusProviderWebsocket)。部屋(HocuspocusProvider)はそこへ attach する。
+ *   v3 は websocketProvider を共有すると attach() を呼ぶまで繋がらない(取り決め §2 の実測)
+ * - 部屋を手放すときは、まず自分の居場所(awareness)を消し、数秒の猶予のあと detach する。
+ *   猶予の間に同じ部屋へ戻れば(ページを行き来した・1 ページ表示でエディタが作り直された)繋ぎ直さない
+ * - WebSocket も最後の部屋が抜けてから猶予を置いて閉じる
+ */
+
+import { HocuspocusProvider, HocuspocusProviderWebsocket } from '@hocuspocus/provider';
+import * as Y from 'yjs';
+
+/** WebSocket を閉じるまでの猶予(ms) */
+const SOCKET_GRACE_MS = 5000;
+/** 部屋を detach するまでの猶予(ms) */
+export const ROOM_GRACE_MS = 4000;
+
+type SocketEntry = { socket: HocuspocusProviderWebsocket; refs: number; timer: ReturnType<typeof setTimeout> | null };
+const sockets = new Map<string, SocketEntry>();
+
+export function acquireSocket(url: string): HocuspocusProviderWebsocket {
+  let entry = sockets.get(url);
+  if (!entry) {
+    entry = { socket: new HocuspocusProviderWebsocket({ url }), refs: 0, timer: null };
+    sockets.set(url, entry);
+  }
+  if (entry.timer) {
+    clearTimeout(entry.timer);
+    entry.timer = null;
+  }
+  entry.refs += 1;
+  return entry.socket;
+}
+
+export function releaseSocket(url: string): void {
+  const entry = sockets.get(url);
+  if (!entry) return;
+  entry.refs = Math.max(0, entry.refs - 1);
+  if (entry.refs > 0 || entry.timer) return;
+  entry.timer = setTimeout(() => {
+    entry.timer = null;
+    if (entry.refs > 0) return;
+    sockets.delete(url);
+    entry.socket.destroy();
+  }, SOCKET_GRACE_MS);
+}
+
+/** いま張っている WebSocket(検証で切断・再接続を起こすのに使う) */
+export function socketFor(url: string): HocuspocusProviderWebsocket | null {
+  return sockets.get(url)?.socket ?? null;
+}
+
+export type Room = {
+  key: string;
+  url: string;
+  name: string;
+  doc: Y.Doc;
+  provider: HocuspocusProvider;
+  refs: number;
+  timer: ReturnType<typeof setTimeout> | null;
+};
+const rooms = new Map<string, Room>();
+
+export function acquireRoom(url: string, name: string, token?: () => Promise<string | undefined>): Room {
+  const key = `${url}\n${name}`;
+  const existing = rooms.get(key);
+  if (existing) {
+    if (existing.timer) {
+      clearTimeout(existing.timer);
+      existing.timer = null;
+    }
+    existing.refs += 1;
+    return existing;
+  }
+  const socket = acquireSocket(url);
+  const doc = new Y.Doc();
+  const provider = new HocuspocusProvider({
+    websocketProvider: socket,
+    name,
+    document: doc,
+    // 本番の wf/ の部屋は token 無し(空文字)で通る。渡されていればそれを使う
+    token: token ? async () => (await token()) ?? '' : '',
+  });
+  provider.attach();
+  const room: Room = { key, url, name, doc, provider, refs: 1, timer: null };
+  rooms.set(key, room);
+  return room;
+}
+
+/** 部屋を手放す。居場所はすぐ消し、接続は猶予のあと切る */
+export function releaseRoom(room: Room, graceMs = ROOM_GRACE_MS): void {
+  room.refs = Math.max(0, room.refs - 1);
+  if (room.refs > 0) return;
+  room.provider.awareness?.setLocalState(null);
+  if (room.timer) clearTimeout(room.timer);
+  room.timer = setTimeout(() => {
+    room.timer = null;
+    if (room.refs > 0) return;
+    rooms.delete(room.key);
+    room.provider.destroy();
+    room.doc.destroy();
+    releaseSocket(room.url);
+  }, graceMs);
+}
+
+/** 既に持っている部屋(猶予中も含む)。無ければ null */
+export function peekRoom(url: string, name: string): Room | null {
+  return rooms.get(`${url}\n${name}`) ?? null;
+}

package/src/editor/collab/layer.ts

@@ -0,0 +1,168 @@
+'use client';
+
+/**
+ * 紙面の中に、他人の選択枠(名前札)とカーソルを描く(.gg-collab-layer)。
+ * コメントのピン(.gg-comment-layer)と同じ作り: #artboard の中の表示専用の層で、座標は紙面の px。
+ * 線の太さ・名前札の大きさは「内側の倍率 × 外側のキャンバス倍率」で割って画面上で一定に保つ。
+ * 保存 HTML(getCleanHtml)・履歴・共有する本文には入らない
+ */
+
+import { useEffect } from 'react';
+import { findAnchored } from '../components/ppt/PptComments';
+import { useCanvasViewStateOptional } from '../contexts/MultiPageCanvasContext';
+import { collabStore } from './store';
+
+/** 要素の移動・編集にゆるく追従する間隔(ms) */
+const RENDER_INTERVAL_MS = 400;
+
+const CURSOR_SVG =
+  '<svg viewBox="0 0 16 16" width="16" height="16" style="display:block;overflow:visible">' +
+  '<path d="M1 1 L1 13.5 L4.6 10.1 L7.1 15.2 L9.4 14.1 L6.9 9.1 L11.8 9.1 Z" stroke="#fff" stroke-width="1.2" stroke-linejoin="round"/></svg>';
+
+/** 同じ値の再代入をしない(無駄な再計算を起こさない) */
+function applyStyles(el: HTMLElement, styles: Record<string, string>) {
+  const style = el.style as unknown as Record<string, string>;
+  for (const [key, value] of Object.entries(styles)) {
+    if (style[key] !== value) style[key] = value;
+  }
+}
+
+export function useCollabLayer(doc: Document | null, enabled: boolean): void {
+  const outerZoom = useCanvasViewStateOptional()?.canvasZoom ?? 1;
+
+  useEffect(() => {
+    if (!enabled || !doc) return;
+    let alive = true;
+
+    const render = () => {
+      if (!alive || !doc.defaultView) return;
+      const artboard = doc.getElementById('artboard');
+      if (!artboard) return;
+      const peers = collabStore.get().pagePeers;
+      let layer = artboard.querySelector<HTMLElement>(':scope > .gg-collab-layer');
+      if (!layer) {
+        if (peers.length === 0) return;
+        layer = doc.createElement('div');
+        layer.className = 'gg-collab-layer';
+        layer.setAttribute('aria-hidden', 'true');
+        layer.style.cssText = 'position:absolute;inset:0;pointer-events:none;z-index:9001;overflow:visible;';
+        artboard.appendChild(layer);
+      }
+      const root = artboard.getBoundingClientRect();
+      const inner = root.width / (artboard.offsetWidth || 1) || 1;
+      const scale = inner * outerZoom || 1;
+      const wanted = new Set<string>();
+      const ensure = (key: string, build: () => HTMLElement): HTMLElement => {
+        let el = layer!.querySelector<HTMLElement>(`:scope > [data-collab-key="${CSS.escape(key)}"]`);
+        if (!el) {
+          el = build();
+          el.setAttribute('data-collab-key', key);
+          layer!.appendChild(el);
+        }
+        wanted.add(key);
+        return el;
+      };
+      const nameTag = (label: string, color: string): HTMLElement => {
+        const tag = doc.createElement('span');
+        tag.setAttribute('data-collab-name', '');
+        tag.textContent = label;
+        tag.style.background = color;
+        return tag;
+      };
+
+      for (const peer of peers) {
+        const anchors = [...peer.selection];
+        if (peer.editing && !anchors.includes(peer.editing)) anchors.push(peer.editing);
+        anchors.forEach((anchor, index) => {
+          const target = findAnchored(artboard, anchor);
+          if (!target) return;
+          const r = target.getBoundingClientRect();
+          const editing = anchor === peer.editing;
+          const box = ensure(`sel:${peer.clientId}:${index}`, () => {
+            const el = doc.createElement('div');
+            el.setAttribute('data-collab-selection', String(peer.clientId));
+            el.appendChild(nameTag('', peer.user.color));
+            return el;
+          });
+          box.setAttribute('data-collab-user', peer.user.id);
+          box.toggleAttribute('data-collab-editing', editing);
+          applyStyles(box, {
+            position: 'absolute',
+            left: `${(r.left - root.left) / inner}px`,
+            top: `${(r.top - root.top) / inner}px`,
+            width: `${r.width / inner}px`,
+            height: `${r.height / inner}px`,
+            boxSizing: 'border-box',
+            border: `${2 / scale}px ${editing ? 'dashed' : 'solid'} ${peer.user.color}`,
+            borderRadius: `${2 / scale}px`,
+          });
+          const tag = box.firstElementChild as HTMLElement;
+          const label = editing ? `${peer.user.name}(入力中)` : peer.user.name;
+          if (tag.textContent !== label) tag.textContent = label;
+          applyStyles(tag, {
+            position: 'absolute',
+            left: `${-2 / scale}px`,
+            bottom: '100%',
+            marginBottom: `${2 / scale}px`,
+            background: peer.user.color,
+            color: '#fff',
+            font: `600 ${11 / scale}px/1.35 system-ui, -apple-system, sans-serif`,
+            padding: `${1 / scale}px ${5 / scale}px`,
+            borderRadius: `${3 / scale}px`,
+            whiteSpace: 'nowrap',
+          });
+        });
+
+        if (peer.cursor) {
+          const cursor = ensure(`cur:${peer.clientId}`, () => {
+            const el = doc.createElement('div');
+            el.setAttribute('data-collab-cursor', String(peer.clientId));
+            el.innerHTML = CURSOR_SVG;
+            el.appendChild(nameTag(peer.user.name, peer.user.color));
+            return el;
+          });
+          cursor.setAttribute('data-collab-user', peer.user.id);
+          applyStyles(cursor, {
+            position: 'absolute',
+            left: `${peer.cursor.x}px`,
+            top: `${peer.cursor.y}px`,
+            transform: `scale(${1 / scale})`,
+            transformOrigin: '0 0',
+          });
+          const path = cursor.querySelector('path');
+          if (path && path.getAttribute('fill') !== peer.user.color) path.setAttribute('fill', peer.user.color);
+          const tag = cursor.querySelector<HTMLElement>('[data-collab-name]')!;
+          if (tag.textContent !== peer.user.name) tag.textContent = peer.user.name;
+          applyStyles(tag, {
+            position: 'absolute',
+            left: '12px',
+            top: '15px',
+            background: peer.user.color,
+            color: '#fff',
+            font: '600 11px/1.35 system-ui, -apple-system, sans-serif',
+            padding: '1px 5px',
+            borderRadius: '3px',
+            whiteSpace: 'nowrap',
+          });
+        }
+      }
+      layer.querySelectorAll<HTMLElement>(':scope > [data-collab-key]').forEach((el) => {
+        if (!wanted.has(el.getAttribute('data-collab-key') ?? '')) el.remove();
+      });
+    };
+
+    render();
+    const unsubscribe = collabStore.subscribe(render);
+    const timer = setInterval(render, RENDER_INTERVAL_MS);
+    return () => {
+      alive = false;
+      unsubscribe();
+      clearInterval(timer);
+      try {
+        doc.querySelector('#artboard > .gg-collab-layer')?.remove();
+      } catch {
+        /* 文書が既に無い */
+      }
+    };
+  }, [doc, enabled, outerZoom]);
+}

package/src/editor/collab/merge.ts

@@ -0,0 +1,112 @@
+/**
+ * 共有する本文(文字列)の差分と、同時の変更の合わせ方。
+ *
+ * エディタは「最後に Y.Text と揃えた紙面の姿」(shadow)を持つ。自分の変更は
+ * shadow → いまの紙面 の差分(local)で、その間に届いた他人の変更は shadow → Y.Text の差分(remote)。
+ * local の位置を remote に通して Y.Text の位置へ写し、1 つの transaction で当てる。
+ *
+ * こうするのは、紙面と Y.Text が 1 文字も違わないとは限らないため:
+ * - 打鍵中の要素に掛かる他人の変更は blur まで紙面に入れない(その間も自分の打鍵は送る)
+ * - 他人の本文を当てた紙面を getCleanHtml すると、属性の並び・書き戻しの印(data-gg-dirty)などが
+ *   元の文字列と少し違うことがある
+ * 「Y.Text と今の紙面の差分」をそのまま送ると、前者では他人の変更を消し、後者では
+ * 同じ整形を何人もが送って挿入が重なる。
+ */
+
+import diff from 'fast-diff';
+
+/** base の [from, to) を insert に置き換える */
+export type Replacement = { from: number; to: number; insert: string };
+
+/** Y.Text に当てる 1 手(at は当てる前の Y.Text の位置) */
+export type TextOp = { at: number; deleteCount: number; insert: string };
+
+/** base → next の差分を、base の位置での置き換えの列にする(位置の昇順・重ならない) */
+export function replacementsOf(base: string, next: string): Replacement[] {
+  if (base === next) return [];
+  const out: Replacement[] = [];
+  let pos = 0;
+  let current: Replacement | null = null;
+  for (const [type, text] of diff(base, next)) {
+    if (type === diff.EQUAL) {
+      if (current) out.push(current);
+      current = null;
+      pos += text.length;
+    } else if (type === diff.DELETE) {
+      if (!current) current = { from: pos, to: pos, insert: '' };
+      current.to += text.length;
+      pos += text.length;
+    } else {
+      if (!current) current = { from: pos, to: pos, insert: '' };
+      current.insert += text;
+    }
+  }
+  if (current) out.push(current);
+  return out;
+}
+
+/**
+ * base の位置 → remote を当てたあとの位置。
+ * remote に置き換えられた範囲の中は、その置き換えの先頭へ寄せる。
+ * 同じ位置への挿入は remote が先(自分の挿入はその後ろ)
+ */
+function mapPosition(pos: number, remote: Replacement[]): number {
+  let delta = 0;
+  for (const r of remote) {
+    if (pos < r.from) break;
+    if (pos >= r.to) {
+      delta += r.insert.length - (r.to - r.from);
+      continue;
+    }
+    return r.from + delta;
+  }
+  return pos + delta;
+}
+
+/**
+ * local(base の位置)を remote を当てたあとの文字列の手に写す。
+ * - local の削除のうち、remote が既に置き換えた範囲は消さない(他人の挿入も消さない)
+ * - local の挿入は、写した位置に入れる
+ * 戻り値は位置の降順(前から当てると後ろの位置がずれるため)。同じ位置では削除 → 挿入の順
+ */
+export function transformReplacements(local: Replacement[], remote: Replacement[]): TextOp[] {
+  const ops: (TextOp & { order: number })[] = [];
+  let order = 0;
+  for (const l of local) {
+    // 削除: [from, to) から remote の範囲を抜いた残り。remote の挿入(幅 0)は切れ目にする
+    if (l.to > l.from) {
+      let start = l.from;
+      for (const r of remote) {
+        if (r.to < l.from || r.from > l.to) continue;
+        if (r.from === r.to) {
+          if (r.from > l.from && r.from < l.to) {
+            if (r.from > start) ops.push({ at: mapPosition(start, remote), deleteCount: r.from - start, insert: '', order: order++ });
+            start = r.from;
+          }
+          continue;
+        }
+        const cutFrom = Math.max(r.from, l.from);
+        const cutTo = Math.min(r.to, l.to);
+        if (cutTo <= cutFrom) continue;
+        if (cutFrom > start) ops.push({ at: mapPosition(start, remote), deleteCount: cutFrom - start, insert: '', order: order++ });
+        start = Math.max(start, cutTo);
+      }
+      if (l.to > start) ops.push({ at: mapPosition(start, remote), deleteCount: l.to - start, insert: '', order: order++ });
+    }
+    if (l.insert) ops.push({ at: mapPosition(l.from, remote), deleteCount: 0, insert: l.insert, order: order++ });
+  }
+  ops.sort((a, b) => {
+    if (a.at !== b.at) return b.at - a.at;
+    // 同じ位置: 削除を先に(挿入してから消すと、入れた文字を消してしまう)。挿入どうしは後のものを先に入れる
+    if ((a.deleteCount > 0) !== (b.deleteCount > 0)) return a.deleteCount > 0 ? -1 : 1;
+    return b.order - a.order;
+  });
+  return ops.map(({ at, deleteCount, insert }) => ({ at, deleteCount, insert }));
+}
+
+/** 文字列に手を当てる(検証と、Y.Text に当てる前の確かめに使う) */
+export function applyTextOps(text: string, ops: TextOp[]): string {
+  let out = text;
+  for (const op of ops) out = out.slice(0, op.at) + op.insert + out.slice(op.at + op.deleteCount);
+  return out;
+}

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] : '';
+}