@pm-cm/yjs 0.0.1

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/bridge.ts","../src/types.ts","../src/awareness-proxy.ts","../src/collab-plugins.ts","../src/bridge-sync-plugin.ts","../src/cursor-sync-plugin.ts"],"sourcesContent":["export { createYjsBridge, replaceSharedText, replaceSharedProseMirror } from './bridge.js'\nexport type { YjsBridgeOptions, ReplaceResult, ReplaceTextResult, ReplaceProseMirrorResult } from './bridge.js'\nexport { createAwarenessProxy } from './awareness-proxy.js'\nexport { createCollabPlugins } from './collab-plugins.js'\nexport type { CollabPluginsOptions, ProseMirrorMapping, YCursorPluginOpts, YUndoPluginOpts } from './collab-plugins.js'\nexport {\n  ORIGIN_TEXT_TO_PM,\n  ORIGIN_PM_TO_TEXT,\n  ORIGIN_INIT,\n} from './types.js'\nexport type {\n  BootstrapResult,\n  YjsBridgeConfig,\n  YjsBridgeHandle,\n  WarningCode,\n  WarningEvent,\n  OnWarning,\n} from './types.js'\n\n// Cursor mapping re-exported from @pm-cm/core\nexport { buildCursorMap, cursorMapLookup, reverseCursorMapLookup } from '@pm-cm/core'\nexport type { TextSegment, CursorMap, LocateText } from '@pm-cm/core'\n\n// Bridge sync plugin (auto PM→Y.Text wiring)\nexport { createBridgeSyncPlugin, bridgeSyncPluginKey } from './bridge-sync-plugin.js'\nexport type { BridgeSyncPluginOptions } from './bridge-sync-plugin.js'\n\n// Cursor sync plugin\nexport { createCursorSyncPlugin, cursorSyncPluginKey, syncCmCursor } from './cursor-sync-plugin.js'\nexport type { CursorSyncState, CursorSyncPluginOptions } from './cursor-sync-plugin.js'\n\n// Re-export types from @pm-cm/core\nexport type { Serialize, Parse, Normalize, OnError, ErrorCode, ErrorEvent } from '@pm-cm/core'\n","import type { Node } from 'prosemirror-model'\nimport type { Transaction } from 'prosemirror-state'\nimport { prosemirrorToYXmlFragment, yXmlFragmentToProseMirrorRootNode, ySyncPluginKey } from 'y-prosemirror'\nimport type { Doc, Text as YText, XmlFragment as YXmlFragment } from 'yjs'\nimport type { Normalize, OnError } from '@pm-cm/core'\nimport type { BootstrapResult, YjsBridgeConfig, YjsBridgeHandle } from './types.js'\nimport { ORIGIN_INIT, ORIGIN_TEXT_TO_PM, ORIGIN_PM_TO_TEXT } from './types.js'\n\nconst defaultNormalize: Normalize = (s) => s.replace(/\\r\\n?/g, '\\n')\nconst defaultOnError: OnError = (event) => console.error(`[bridge] ${event.code}: ${event.message}`, event.cause)\n\n/** Result of {@link replaceSharedText}. */\nexport type ReplaceTextResult =\n  | { ok: true }\n  | { ok: false; reason: 'unchanged' }\n  | { ok: false; reason: 'detached' }\n\n/** Result of {@link replaceSharedProseMirror}. */\nexport type ReplaceProseMirrorResult =\n  | { ok: true }\n  | { ok: false; reason: 'parse-error' }\n  | { ok: false; reason: 'detached' }\n\n/**\n * Union of all replace-result types. Kept for backward compatibility.\n * Prefer the narrower {@link ReplaceTextResult} / {@link ReplaceProseMirrorResult}.\n */\nexport type ReplaceResult = ReplaceTextResult | ReplaceProseMirrorResult\n\n/**\n * Replace `Y.Text` content using a minimal diff (common prefix/suffix trimming).\n * Returns a {@link ReplaceResult} indicating success or failure reason.\n */\nexport function replaceSharedText(\n  sharedText: YText,\n  next: string,\n  origin: unknown,\n  normalize: Normalize = defaultNormalize,\n): ReplaceTextResult {\n  if (!sharedText.doc) {\n    return { ok: false, reason: 'detached' }\n  }\n\n  const normalized = normalize(next)\n  const current = sharedText.toString()\n  if (current === normalized) {\n    return { ok: false, reason: 'unchanged' }\n  }\n\n  // Minimal diff: find common prefix and suffix, replace only the changed middle.\n  let start = 0\n  const minLen = Math.min(current.length, normalized.length)\n  while (start < minLen && current.charCodeAt(start) === normalized.charCodeAt(start)) {\n    start++\n  }\n\n  let endCurrent = current.length\n  let endNext = normalized.length\n  while (endCurrent > start && endNext > start && current.charCodeAt(endCurrent - 1) === normalized.charCodeAt(endNext - 1)) {\n    endCurrent--\n    endNext--\n  }\n\n  sharedText.doc.transact(() => {\n    const deleteCount = endCurrent - start\n    if (deleteCount > 0) {\n      sharedText.delete(start, deleteCount)\n    }\n    const insertStr = normalized.slice(start, endNext)\n    if (insertStr.length > 0) {\n      sharedText.insert(start, insertStr)\n    }\n  }, origin)\n\n  return { ok: true }\n}\n\n/**\n * Replace `Y.XmlFragment` by parsing serialized text into a ProseMirror document.\n * Returns a {@link ReplaceResult} indicating success or failure reason.\n */\nexport function replaceSharedProseMirror(\n  doc: Doc,\n  fragment: YXmlFragment,\n  text: string,\n  origin: unknown,\n  config: Pick<YjsBridgeConfig, 'schema' | 'parse' | 'normalize' | 'onError'>,\n): ReplaceProseMirrorResult {\n  if (!fragment.doc) {\n    return { ok: false, reason: 'detached' }\n  }\n  if (fragment.doc !== doc) {\n    throw new Error('fragment belongs to a different Y.Doc than the provided doc')\n  }\n\n  const normalize = config.normalize ?? defaultNormalize\n  const onError = config.onError ?? defaultOnError\n  let nextDoc: Node\n  try {\n    nextDoc = config.parse(normalize(text), config.schema)\n  } catch (error) {\n    onError({ code: 'parse-error', message: 'failed to parse text into ProseMirror document', cause: error })\n    return { ok: false, reason: 'parse-error' }\n  }\n\n  doc.transact(() => {\n    prosemirrorToYXmlFragment(nextDoc, fragment)\n  }, origin)\n  return { ok: true }\n}\n\n/** Options for {@link createYjsBridge}. */\nexport type YjsBridgeOptions = {\n  initialText?: string\n  /** Which side wins when both sharedText and sharedProseMirror exist and differ. Default `'text'`. */\n  prefer?: 'text' | 'prosemirror'\n}\n\n/**\n * Create a collaborative bridge that keeps `Y.Text` and `Y.XmlFragment` in sync.\n *\n * Runs a synchronous bootstrap to reconcile existing state, then installs a\n * `Y.Text` observer for the text → ProseMirror direction.\n *\n * @throws If `sharedText` or `sharedProseMirror` belong to a different `Y.Doc`.\n */\nexport function createYjsBridge(\n  config: YjsBridgeConfig,\n  options?: YjsBridgeOptions,\n): YjsBridgeHandle {\n  const {\n    doc,\n    sharedText,\n    sharedProseMirror,\n    schema,\n    serialize,\n    parse,\n  } = config\n  const normalize = config.normalize ?? defaultNormalize\n  const onError = config.onError ?? defaultOnError\n\n  if (!sharedText.doc) {\n    throw new Error('sharedText is not attached to any Y.Doc')\n  }\n  if (sharedText.doc !== doc) {\n    throw new Error('sharedText belongs to a different Y.Doc than the provided doc')\n  }\n  if (!sharedProseMirror.doc) {\n    throw new Error('sharedProseMirror is not attached to any Y.Doc')\n  }\n  if (sharedProseMirror.doc !== doc) {\n    throw new Error('sharedProseMirror belongs to a different Y.Doc than the provided doc')\n  }\n\n  let lastBridgedText: string | null = null\n\n  /** Returns `true` if the parse succeeded. */\n  const syncTextToProsemirror = (origin: unknown): boolean => {\n    const text = normalize(sharedText.toString())\n    if (lastBridgedText === text) {\n      return true\n    }\n\n    const result = replaceSharedProseMirror(doc, sharedProseMirror, text, origin, {\n      schema,\n      parse,\n      normalize,\n      onError,\n    })\n    if (result.ok) {\n      lastBridgedText = text\n    }\n    return result.ok\n  }\n\n  const sharedProseMirrorToText = (fragment: YXmlFragment): string | null => {\n    try {\n      const pmDoc = yXmlFragmentToProseMirrorRootNode(fragment, schema)\n      return normalize(serialize(pmDoc))\n    } catch (error) {\n      onError({ code: 'serialize-error', message: 'failed to convert ProseMirror fragment to text', cause: error })\n      return null\n    }\n  }\n\n  // Bootstrap\n  const bootstrap = (): BootstrapResult => {\n    const text = normalize(sharedText.toString())\n    const hasText = text.length > 0\n    const hasProsemirror = sharedProseMirror.length > 0\n\n    if (!hasText && !hasProsemirror) {\n      const initial = options?.initialText ?? ''\n      if (initial.length > 0) {\n        // Set Y.XmlFragment first, then derive Y.Text from serialize(parse(initial))\n        // to ensure both shared types are in the same canonical form.\n        const initResult = replaceSharedProseMirror(doc, sharedProseMirror, initial, ORIGIN_INIT, {\n          schema,\n          parse,\n          normalize,\n          onError,\n        })\n        if (!initResult.ok) {\n          return { source: 'initial', parseError: true }\n        }\n        const pmDoc = yXmlFragmentToProseMirrorRootNode(sharedProseMirror, schema)\n        const canonicalText = serialize(pmDoc)\n        replaceSharedText(sharedText, canonicalText, ORIGIN_INIT, normalize)\n        lastBridgedText = normalize(canonicalText)\n        return { source: 'initial' }\n      }\n      return { source: 'empty' }\n    }\n\n    if (hasText && !hasProsemirror) {\n      const ok = syncTextToProsemirror(ORIGIN_INIT)\n      return { source: 'text', ...(!ok && { parseError: true }) }\n    }\n\n    if (!hasText && hasProsemirror) {\n      const textFromProsemirror = sharedProseMirrorToText(sharedProseMirror)\n      if (textFromProsemirror !== null) {\n        replaceSharedText(sharedText, textFromProsemirror, ORIGIN_INIT, normalize)\n        lastBridgedText = normalize(textFromProsemirror)\n        return { source: 'prosemirror' }\n      }\n      return { source: 'prosemirror', parseError: true }\n    }\n\n    const prosemirrorText = sharedProseMirrorToText(sharedProseMirror)\n    if (prosemirrorText === null) {\n      const fallbackText = hasText ? text : (options?.initialText ?? '')\n      let parseError = false\n      if (fallbackText.length > 0) {\n        replaceSharedText(sharedText, fallbackText, ORIGIN_INIT, normalize)\n        const fallbackResult = replaceSharedProseMirror(doc, sharedProseMirror, fallbackText, ORIGIN_INIT, {\n          schema,\n          parse,\n          normalize,\n          onError,\n        })\n        if (!fallbackResult.ok) parseError = true\n      }\n      return { source: 'text', ...(parseError && { parseError: true }) }\n    }\n\n    if (prosemirrorText !== text) {\n      const prefer = options?.prefer ?? 'text'\n      if (prefer === 'prosemirror') {\n        replaceSharedText(sharedText, prosemirrorText, ORIGIN_INIT, normalize)\n        lastBridgedText = normalize(prosemirrorText)\n        return { source: 'prosemirror' }\n      } else {\n        const ok = syncTextToProsemirror(ORIGIN_INIT)\n        return { source: 'text', ...(!ok && { parseError: true }) }\n      }\n    } else {\n      lastBridgedText = text\n      return { source: 'both-match' }\n    }\n  }\n\n  const textObserver = (\n    _: unknown,\n    transaction: { origin: unknown },\n  ) => {\n    if (transaction.origin === ORIGIN_PM_TO_TEXT || transaction.origin === ORIGIN_INIT) {\n      return\n    }\n\n    syncTextToProsemirror(ORIGIN_TEXT_TO_PM)\n  }\n\n  // Run bootstrap synchronously before installing the observer so that\n  // an exception during bootstrap cannot leave a dangling observer.\n  const bootstrapResult = bootstrap()\n\n  sharedText.observe(textObserver)\n\n  return {\n    bootstrapResult,\n    syncToSharedText(doc: Node): ReplaceTextResult {\n      const text = serialize(doc)\n      const result = replaceSharedText(sharedText, text, ORIGIN_PM_TO_TEXT, normalize)\n      // Always update lastBridgedText unless truly failed (detached).\n      // 'unchanged' means Y.Text already has this content — still need to\n      // record it so the reverse observer doesn't trigger a redundant sync.\n      if (result.ok || result.reason === 'unchanged') {\n        lastBridgedText = normalize(text)\n      }\n      return result\n    },\n    isYjsSyncChange(tr: Transaction): boolean {\n      // Internal meta shape from y-prosemirror's ySyncPlugin (tested against ^1.3.x).\n      const meta = tr.getMeta(ySyncPluginKey)\n      return (\n        typeof meta === 'object' &&\n        meta !== null &&\n        'isChangeOrigin' in meta &&\n        (meta as Record<string, unknown>).isChangeOrigin === true\n      )\n    },\n    dispose() {\n      sharedText.unobserve(textObserver)\n    },\n  }\n}\n","import type { Node, Schema } from 'prosemirror-model'\nimport type { Transaction } from 'prosemirror-state'\nimport type { Serialize, Parse, Normalize, OnError } from '@pm-cm/core'\nimport type { Doc, Text as YText, XmlFragment as YXmlFragment } from 'yjs'\nimport type { ReplaceTextResult } from './bridge.js'\n\n/** Known warning codes emitted by the yjs bridge and plugins. */\nexport type WarningCode = 'bridge-already-wired' | 'sync-failed' | 'ysync-plugin-missing' | 'cursor-sync-not-installed'\n\n/** Structured warning event for non-fatal warnings. */\nexport type WarningEvent = {\n  code: WarningCode\n  message: string\n}\n\n/**\n * Warning handler callback for non-fatal warnings.\n *\n * Known codes:\n * - `'bridge-already-wired'` — the same bridge handle is wired to multiple plugin instances.\n * - `'sync-failed'` — `syncToSharedText` failed (e.g. Y.Text detached).\n * - `'ysync-plugin-missing'` — ySyncPlugin state is not available; cursor broadcast skipped.\n * - `'cursor-sync-not-installed'` — cursor sync plugin is not installed on the EditorView.\n */\nexport type OnWarning = (event: WarningEvent) => void\n\n/** Yjs transaction origin: text → ProseMirror direction. */\nexport const ORIGIN_TEXT_TO_PM = 'bridge:text-to-prosemirror'\n\n/** Yjs transaction origin: ProseMirror → text direction. */\nexport const ORIGIN_PM_TO_TEXT = 'bridge:prosemirror-to-text'\n\n/** Yjs transaction origin: bootstrap initialization. */\nexport const ORIGIN_INIT = 'bridge:init'\n\n/** Configuration for {@link createYjsBridge}. */\nexport type YjsBridgeConfig = {\n  doc: Doc\n  sharedText: YText\n  sharedProseMirror: YXmlFragment\n  schema: Schema\n  serialize: Serialize\n  parse: Parse\n  normalize?: Normalize\n  /** Called on non-fatal errors (e.g. parse failures). Defaults to `console.error`. */\n  onError?: OnError\n}\n\n/**\n * Result of the bootstrap phase in {@link createYjsBridge}.\n * Indicates which source was used to initialize the shared types.\n */\nexport type BootstrapResult = {\n  source: 'text' | 'prosemirror' | 'both-match' | 'empty' | 'initial'\n  /** `true` when format conversion (parse or serialize) failed during bootstrap. The bridge is still usable but the affected shared type may be stale. */\n  parseError?: boolean\n}\n\n/** Handle returned by {@link createYjsBridge}. */\nexport type YjsBridgeHandle = {\n  /** Result of the synchronous bootstrap phase. */\n  readonly bootstrapResult: BootstrapResult\n  /** Serialize `doc` and push to `Y.Text` using minimal diff. */\n  syncToSharedText(doc: Node): ReplaceTextResult\n  /** Returns `true` if the transaction originated from `y-prosemirror` sync. */\n  isYjsSyncChange(tr: Transaction): boolean\n  /** Remove the Y.Text observer. Call when tearing down. */\n  dispose(): void\n}\n","import type { Awareness } from 'y-protocols/awareness'\n\n/**\n * Create a Proxy around a Yjs {@link Awareness} that suppresses the specified\n * cursor field. This prevents y-prosemirror's built-in cursor management from\n * conflicting with the PM↔CM cursor sync plugin.\n *\n * Other `setLocalStateField` calls are passed through unchanged.\n */\nexport function createAwarenessProxy(awareness: Awareness, cursorField = 'pmCursor'): Awareness {\n  return new Proxy(awareness, {\n    get(target, prop, receiver) {\n      if (prop === 'getLocalState') {\n        return () => {\n          const state = target.getLocalState()\n          return state ? { ...state, [cursorField]: null } : state\n        }\n      }\n      if (prop === 'setLocalStateField') {\n        return (field: string, value: unknown) => {\n          // Only suppress the cursor field; pass through other fields\n          if (field === cursorField) return\n          target.setLocalStateField(field, value)\n        }\n      }\n      const value = Reflect.get(target, prop, receiver) as unknown\n      return typeof value === 'function' ? (value as Function).bind(target) : value\n    },\n  }) as Awareness\n}\n","import type { Node, Schema } from 'prosemirror-model'\nimport type { EditorState, Plugin } from 'prosemirror-state'\nimport type { DecorationAttrs } from 'prosemirror-view'\nimport type { Awareness } from 'y-protocols/awareness'\nimport type { Serialize, LocateText } from '@pm-cm/core'\nimport { initProseMirrorDoc, yCursorPlugin, ySyncPlugin, yUndoPlugin } from 'y-prosemirror'\nimport type { AbstractType, Text as YText, UndoManager } from 'yjs'\nimport type { XmlFragment as YXmlFragment } from 'yjs'\nimport { createAwarenessProxy } from './awareness-proxy.js'\nimport { createBridgeSyncPlugin } from './bridge-sync-plugin.js'\nimport { createCursorSyncPlugin } from './cursor-sync-plugin.js'\nimport type { YjsBridgeHandle, OnWarning } from './types.js'\n\n/** Yjs ↔ ProseMirror node mapping used by `y-prosemirror`. */\nexport type ProseMirrorMapping = Map<AbstractType<unknown>, Node | Node[]>\n\n/** Options forwarded to `yCursorPlugin` from y-prosemirror. */\nexport type YCursorPluginOpts = {\n  awarenessStateFilter?: (currentClientId: number, userClientId: number, user: unknown) => boolean\n  cursorBuilder?: (user: unknown, clientId: number) => HTMLElement\n  selectionBuilder?: (user: unknown, clientId: number) => DecorationAttrs\n  getSelection?: (state: EditorState) => unknown\n}\n\n/** Options forwarded to `yUndoPlugin` from y-prosemirror. */\nexport type YUndoPluginOpts = {\n  protectedNodes?: Set<string>\n  trackedOrigins?: unknown[]\n  undoManager?: UndoManager | null\n}\n\n/** Options for {@link createCollabPlugins}. */\nexport type CollabPluginsOptions = {\n  /** Shared ProseMirror document in Yjs. */\n  sharedProseMirror: YXmlFragment\n  awareness: Awareness\n  cursorFieldName?: string\n  serialize?: Serialize\n  /** Awareness field used for CM/Y.Text cursor payloads. Default `'cursor'`. */\n  cmCursorFieldName?: string\n  locate?: LocateText\n  /**\n   * Enable PM↔CM cursor sync. Default `false`.\n   *\n   * When enabled, an {@link createAwarenessProxy | awareness proxy} is applied\n   * to suppress y-prosemirror's built-in cursor management.\n   */\n  cursorSync?: boolean\n  /**\n   * The shared `Y.Text` instance. When provided, the cursor sync plugin also\n   * broadcasts CM-format cursor positions so remote `yCollab` instances render them.\n   */\n  sharedText?: YText\n  /**\n   * When provided, a bridge sync plugin is inserted before the cursor sync plugin\n   * to ensure Y.Text is synced before cursor positions are computed. This guarantees\n   * that serialize-based offsets match Y.Text indices.\n   */\n  bridge?: YjsBridgeHandle\n  /** Extra options forwarded to `yCursorPlugin`. */\n  yCursorPluginOpts?: YCursorPluginOpts\n  /** Extra options forwarded to `yUndoPlugin`. */\n  yUndoPluginOpts?: YUndoPluginOpts\n  /** Called for non-fatal warnings. Propagated to child plugins. Default `console.warn`. */\n  onWarning?: OnWarning\n}\n\n/**\n * Bundle `ySyncPlugin`, `yCursorPlugin`, `yUndoPlugin` from y-prosemirror,\n * plus an optional PM↔CM cursor sync plugin.\n *\n * @throws If `cursorSync: true` but `serialize` is not provided.\n */\nexport function createCollabPlugins(\n  schema: Schema,\n  options: CollabPluginsOptions,\n): { plugins: Plugin[]; doc: Node; mapping: ProseMirrorMapping } {\n  const cursorFieldName = options.cursorFieldName ?? 'pmCursor'\n  const enableCursorSync = options.cursorSync ?? false\n  const { sharedProseMirror } = options\n\n  if (enableCursorSync && !options.serialize) {\n    throw new Error('createCollabPlugins: cursorSync requires serialize to be provided')\n  }\n  const { doc, mapping: rawMapping } = initProseMirrorDoc(sharedProseMirror, schema)\n  const mapping = rawMapping as ProseMirrorMapping\n  const pmAwareness = enableCursorSync\n    ? createAwarenessProxy(options.awareness, cursorFieldName)\n    : options.awareness\n\n  const plugins: Plugin[] = [\n    ySyncPlugin(sharedProseMirror, { mapping: rawMapping }),\n    yCursorPlugin(pmAwareness, options.yCursorPluginOpts ?? {}, cursorFieldName),\n    yUndoPlugin(options.yUndoPluginOpts),\n  ]\n\n  // Bridge sync plugin must run before cursor sync plugin so that\n  // Y.Text is updated before cursor positions are computed.\n  if (options.bridge) {\n    plugins.push(createBridgeSyncPlugin(options.bridge, { onWarning: options.onWarning }))\n  }\n\n  if (enableCursorSync && options.serialize) {\n    plugins.push(\n      createCursorSyncPlugin({\n        awareness: options.awareness,\n        serialize: options.serialize,\n        cursorFieldName,\n        cmCursorFieldName: options.cmCursorFieldName,\n        locate: options.locate,\n        sharedText: options.sharedText,\n        onWarning: options.onWarning,\n      }),\n    )\n  }\n\n  return { plugins, doc, mapping }\n}\n","import { Plugin, PluginKey } from 'prosemirror-state'\nimport type { EditorView } from 'prosemirror-view'\nimport type { YjsBridgeHandle, OnWarning } from './types.js'\n\ntype BridgeSyncState = { needsSync: boolean }\n\ntype BridgeSyncFailure = { ok: false; reason: 'detached' }\n\n/** Options for {@link createBridgeSyncPlugin}. */\nexport type BridgeSyncPluginOptions = {\n  /** Called when `syncToSharedText` fails (excludes `reason: 'unchanged'`). */\n  onSyncFailure?: (result: BridgeSyncFailure, view: EditorView) => void\n  /** Called for non-fatal warnings. Default `console.warn`. */\n  onWarning?: OnWarning\n}\n\n/** ProseMirror plugin key for {@link createBridgeSyncPlugin}. Use to read the plugin state. */\nexport const bridgeSyncPluginKey = new PluginKey<BridgeSyncState>('pm-cm-bridge-sync')\n\nconst wiredBridges = new WeakSet<YjsBridgeHandle>()\n\nconst defaultOnWarning: OnWarning = (event) => console.warn(`[pm-cm] ${event.code}: ${event.message}`)\n\n/**\n * ProseMirror plugin that automatically syncs PM doc changes to Y.Text\n * via the bridge handle. Skips Yjs-originated changes to avoid loops.\n *\n * A warning is logged if the same bridge handle is wired more than once.\n * The guard is cleaned up when the plugin is destroyed.\n */\nexport function createBridgeSyncPlugin(\n  bridge: YjsBridgeHandle,\n  options: BridgeSyncPluginOptions = {},\n): Plugin {\n  const warn = options.onWarning ?? defaultOnWarning\n  if (wiredBridges.has(bridge)) {\n    warn({ code: 'bridge-already-wired', message: 'this bridge is already wired to another plugin instance' })\n  }\n  wiredBridges.add(bridge)\n\n  return new Plugin<BridgeSyncState>({\n    key: bridgeSyncPluginKey,\n\n    state: {\n      init(): BridgeSyncState {\n        return { needsSync: false }\n      },\n      apply(tr, _prev): BridgeSyncState {\n        if (!tr.docChanged) return { needsSync: false }\n        if (bridge.isYjsSyncChange(tr)) return { needsSync: false }\n        return { needsSync: true }\n      },\n    },\n\n    view() {\n      return {\n        update(view) {\n          const state = bridgeSyncPluginKey.getState(view.state)\n          if (state?.needsSync) {\n            const result = bridge.syncToSharedText(view.state.doc)\n            if (!result.ok) {\n              if (result.reason === 'detached') {\n                options.onSyncFailure?.(result, view)\n                warn({ code: 'sync-failed', message: `bridge sync failed: ${result.reason}` })\n              }\n            }\n          }\n        },\n        destroy() {\n          wiredBridges.delete(bridge)\n        },\n      }\n    },\n  })\n}\n","import { Plugin, PluginKey } from 'prosemirror-state'\nimport type { Node } from 'prosemirror-model'\nimport type { EditorView } from 'prosemirror-view'\nimport type { Awareness } from 'y-protocols/awareness'\nimport { absolutePositionToRelativePosition, ySyncPluginKey } from 'y-prosemirror'\nimport { createRelativePositionFromTypeIndex } from 'yjs'\nimport type { Text as YText, XmlFragment as YXmlFragment } from 'yjs'\nimport type { Serialize, LocateText, CursorMap } from '@pm-cm/core'\nimport { buildCursorMap, cursorMapLookup, reverseCursorMapLookup } from '@pm-cm/core'\nimport type { OnWarning } from './types.js'\n\n/** Plugin state for the cursor sync plugin. Read via {@link cursorSyncPluginKey}. */\nexport type CursorSyncState = {\n  /** Pending CodeMirror cursor to broadcast. Set by {@link syncCmCursor}. */\n  pendingCm: { anchor: number; head: number } | null\n  /** Text offset mapped from the current PM selection anchor. `null` when no mapping is available. */\n  mappedTextOffset: number | null\n}\n\n/** ProseMirror plugin key for {@link createCursorSyncPlugin}. Use to read the plugin state. */\nexport const cursorSyncPluginKey = new PluginKey<CursorSyncState>('pm-cm-cursor-sync')\n\n/**\n * Internal shape of `ySyncPluginKey` state from y-prosemirror.\n * Not exported by upstream — kept here for explicit tracking.\n * Tested against y-prosemirror ^1.3.x.\n */\ntype YSyncPluginState = { type: YXmlFragment; binding: { mapping: Map<unknown, unknown> } }\n\nfunction getYSyncState(view: EditorView): YSyncPluginState | null {\n  const raw = ySyncPluginKey.getState(view.state) as Record<string, unknown> | undefined\n  if (!raw) return null\n  if (\n    typeof raw === 'object' &&\n    'type' in raw && raw.type &&\n    'binding' in raw && raw.binding &&\n    typeof raw.binding === 'object' &&\n    'mapping' in (raw.binding as Record<string, unknown>) &&\n    (raw.binding as Record<string, unknown>).mapping instanceof Map\n  ) {\n    return raw as unknown as YSyncPluginState\n  }\n  return null\n}\n\nfunction toRelativePosition(\n  view: EditorView,\n  pmPos: number,\n): unknown | null {\n  const ySyncState = getYSyncState(view)\n  if (!ySyncState) return null\n\n  return absolutePositionToRelativePosition(\n    pmPos,\n    ySyncState.type,\n    ySyncState.binding.mapping as any, // eslint-disable-line @typescript-eslint/no-explicit-any -- y-prosemirror internal mapping type\n  )\n}\n\n/** Returns `false` when ySyncPlugin state is unavailable (plugin not installed). */\nfunction broadcastPmCursor(\n  awareness: Awareness,\n  cursorFieldName: string,\n  view: EditorView,\n  pmAnchor: number,\n  pmHead: number,\n): boolean {\n  const relAnchor = toRelativePosition(view, pmAnchor)\n  const relHead = toRelativePosition(view, pmHead)\n  if (relAnchor === null || relHead === null) return false\n\n  awareness.setLocalStateField(cursorFieldName, { anchor: relAnchor, head: relHead })\n  return true\n}\n\nfunction broadcastTextCursor(\n  awareness: Awareness,\n  cmCursorFieldName: string,\n  sharedText: YText,\n  textAnchor: number,\n  textHead: number,\n): void {\n  const len = sharedText.length\n  const clamp = (v: number) => Math.max(0, Math.min(v, len))\n  const relAnchor = createRelativePositionFromTypeIndex(sharedText, clamp(textAnchor))\n  const relHead = createRelativePositionFromTypeIndex(sharedText, clamp(textHead))\n  awareness.setLocalStateField(cmCursorFieldName, { anchor: relAnchor, head: relHead })\n}\n\nconst defaultOnWarning: OnWarning = (event) => console.warn(`[pm-cm] ${event.code}: ${event.message}`)\n\n/** Options for {@link createCursorSyncPlugin}. */\nexport type CursorSyncPluginOptions = {\n  awareness: Awareness\n  serialize: Serialize\n  cursorFieldName?: string\n  /** Awareness field used for CM/Y.Text cursor payloads. Default `'cursor'`. */\n  cmCursorFieldName?: string\n  locate?: LocateText\n  /**\n   * When provided, the plugin also broadcasts CM-format cursor positions\n   * (Y.Text relative positions) to the awareness field specified by\n   * `cmCursorFieldName`, so that remote `yCollab` instances can render the cursor.\n   */\n  sharedText?: YText\n  /** Called for non-fatal warnings. Default `console.warn`. */\n  onWarning?: OnWarning\n}\n\n/**\n * ProseMirror plugin that synchronizes cursor positions between PM and CM via Yjs awareness.\n *\n * - PM → awareness: automatically broadcasts when the PM view is focused and selection changes.\n * - CM → awareness: triggered by dispatching {@link syncCmCursor}.\n */\nexport function createCursorSyncPlugin(options: CursorSyncPluginOptions): Plugin {\n  const { awareness, serialize, locate, sharedText } = options\n  const warn = options.onWarning ?? defaultOnWarning\n  const cursorFieldName = options.cursorFieldName ?? 'pmCursor'\n  const cmCursorFieldName = options.cmCursorFieldName ?? 'cursor'\n\n  let warnedSyncPluginMissing = false\n\n  // Cached cursor map (serialize-based) — rebuilt only when doc changes\n  let cachedMap: CursorMap | null = null\n  let cachedMapDoc: Node | null = null\n\n  function getOrBuildMap(doc: Node): CursorMap {\n    if (cachedMapDoc !== doc || !cachedMap) {\n      cachedMap = buildCursorMap(doc, serialize, locate)\n      cachedMapDoc = doc\n    }\n    return cachedMap\n  }\n\n  return new Plugin<CursorSyncState>({\n    key: cursorSyncPluginKey,\n\n    state: {\n      init(): CursorSyncState {\n        return { pendingCm: null, mappedTextOffset: null }\n      },\n      apply(tr, prev, _oldState, newState): CursorSyncState {\n        const cmMeta = tr.getMeta(cursorSyncPluginKey) as\n          | { anchor: number; head: number }\n          | undefined\n        if (cmMeta) {\n          return { pendingCm: cmMeta, mappedTextOffset: prev.mappedTextOffset }\n        }\n\n        // Compute PM → text offset when selection or doc changes\n        let mappedTextOffset = prev.mappedTextOffset\n        if (tr.selectionSet || tr.docChanged) {\n          const map = getOrBuildMap(newState.doc)\n          mappedTextOffset = cursorMapLookup(map, newState.selection.anchor)\n        }\n\n        return {\n          pendingCm: prev.pendingCm !== null ? null : prev.pendingCm,\n          mappedTextOffset,\n        }\n      },\n    },\n\n    view() {\n      return {\n        update(view, prevState) {\n          const pluginState = cursorSyncPluginKey.getState(view.state)\n          const prevPluginState = cursorSyncPluginKey.getState(prevState)\n\n          // CM → awareness: broadcast when pendingCm is newly set\n          if (\n            pluginState?.pendingCm != null &&\n            pluginState.pendingCm !== prevPluginState?.pendingCm\n          ) {\n            const map = getOrBuildMap(view.state.doc)\n            const pmAnchor = reverseCursorMapLookup(map, pluginState.pendingCm.anchor)\n            const pmHead = reverseCursorMapLookup(map, pluginState.pendingCm.head)\n            if (pmAnchor !== null && pmHead !== null) {\n              const ok = broadcastPmCursor(awareness, cursorFieldName, view, pmAnchor, pmHead)\n              if (!ok && !warnedSyncPluginMissing) {\n                warnedSyncPluginMissing = true\n                warn({ code: 'ysync-plugin-missing', message: 'ySyncPlugin state not available — cursor broadcast skipped' })\n              }\n            }\n            // Also broadcast CM-format cursor so remote yCollab can render it\n            if (sharedText) {\n              broadcastTextCursor(\n                awareness,\n                cmCursorFieldName,\n                sharedText,\n                pluginState.pendingCm.anchor,\n                pluginState.pendingCm.head,\n              )\n            }\n            return\n          }\n\n          // PM → awareness: auto-broadcast on selection/doc change when focused\n          if (\n            view.hasFocus() &&\n            (view.state.selection !== prevState.selection ||\n              view.state.doc !== prevState.doc)\n          ) {\n            const { anchor, head } = view.state.selection\n            const ok = broadcastPmCursor(awareness, cursorFieldName, view, anchor, head)\n            if (!ok && !warnedSyncPluginMissing) {\n              warnedSyncPluginMissing = true\n              warn({ code: 'ysync-plugin-missing', message: 'ySyncPlugin state not available — cursor broadcast skipped' })\n            }\n            // Also broadcast CM-format cursor so remote yCollab can render it.\n            // When bridgeSyncPlugin runs before this plugin, Y.Text is already\n            // synced so serialize-based offsets match Y.Text indices.\n            if (sharedText) {\n              const map = getOrBuildMap(view.state.doc)\n              const textAnchor = cursorMapLookup(map, anchor)\n              const textHead = cursorMapLookup(map, head)\n              if (textAnchor !== null && textHead !== null) {\n                broadcastTextCursor(awareness, cmCursorFieldName, sharedText, textAnchor, textHead)\n              }\n            }\n          }\n        },\n      }\n    },\n  })\n}\n\n/**\n * Dispatch a CodeMirror cursor offset (or range) to the cursor sync plugin.\n * The plugin will convert it to a ProseMirror position and broadcast via awareness.\n *\n * @param view - The ProseMirror EditorView that has the cursor sync plugin installed.\n * @param anchor - CodeMirror text offset for the anchor.\n * @param head - CodeMirror text offset for the head (defaults to `anchor` for a collapsed cursor).\n * @param onWarning - Optional warning callback. Default `console.warn`.\n */\nexport function syncCmCursor(view: EditorView, anchor: number, head?: number, onWarning?: OnWarning): void {\n  if (!cursorSyncPluginKey.getState(view.state)) {\n    (onWarning ?? defaultOnWarning)({ code: 'cursor-sync-not-installed', message: 'cursor sync plugin is not installed on this EditorView' })\n    return\n  }\n  const sanitize = (v: number) => Math.max(0, Math.floor(v))\n  view.dispatch(\n    view.state.tr.setMeta(cursorSyncPluginKey, {\n      anchor: sanitize(anchor),\n      head: sanitize(head ?? anchor),\n    }),\n  )\n}\n"],"mappings":"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","names":["doc","value","import_y_prosemirror","import_prosemirror_state","import_y_prosemirror","defaultOnWarning","import_core"]}

package/dist/index.d.cts

@@ -0,0 +1,259 @@
+import { Doc, Text, XmlFragment, UndoManager, AbstractType } from 'yjs';
+import { Serialize, Parse, Normalize, OnError, LocateText } from '@pm-cm/core';
+export { CursorMap, ErrorCode, ErrorEvent, LocateText, Normalize, OnError, Parse, Serialize, TextSegment, buildCursorMap, cursorMapLookup, reverseCursorMapLookup } from '@pm-cm/core';
+import { Node, Schema } from 'prosemirror-model';
+import { Transaction, EditorState, Plugin, PluginKey } from 'prosemirror-state';
+import { Awareness } from 'y-protocols/awareness';
+import { DecorationAttrs, EditorView } from 'prosemirror-view';
+
+/** Known warning codes emitted by the yjs bridge and plugins. */
+type WarningCode = 'bridge-already-wired' | 'sync-failed' | 'ysync-plugin-missing' | 'cursor-sync-not-installed';
+/** Structured warning event for non-fatal warnings. */
+type WarningEvent = {
+    code: WarningCode;
+    message: string;
+};
+/**
+ * Warning handler callback for non-fatal warnings.
+ *
+ * Known codes:
+ * - `'bridge-already-wired'` — the same bridge handle is wired to multiple plugin instances.
+ * - `'sync-failed'` — `syncToSharedText` failed (e.g. Y.Text detached).
+ * - `'ysync-plugin-missing'` — ySyncPlugin state is not available; cursor broadcast skipped.
+ * - `'cursor-sync-not-installed'` — cursor sync plugin is not installed on the EditorView.
+ */
+type OnWarning = (event: WarningEvent) => void;
+/** Yjs transaction origin: text → ProseMirror direction. */
+declare const ORIGIN_TEXT_TO_PM = "bridge:text-to-prosemirror";
+/** Yjs transaction origin: ProseMirror → text direction. */
+declare const ORIGIN_PM_TO_TEXT = "bridge:prosemirror-to-text";
+/** Yjs transaction origin: bootstrap initialization. */
+declare const ORIGIN_INIT = "bridge:init";
+/** Configuration for {@link createYjsBridge}. */
+type YjsBridgeConfig = {
+    doc: Doc;
+    sharedText: Text;
+    sharedProseMirror: XmlFragment;
+    schema: Schema;
+    serialize: Serialize;
+    parse: Parse;
+    normalize?: Normalize;
+    /** Called on non-fatal errors (e.g. parse failures). Defaults to `console.error`. */
+    onError?: OnError;
+};
+/**
+ * Result of the bootstrap phase in {@link createYjsBridge}.
+ * Indicates which source was used to initialize the shared types.
+ */
+type BootstrapResult = {
+    source: 'text' | 'prosemirror' | 'both-match' | 'empty' | 'initial';
+    /** `true` when format conversion (parse or serialize) failed during bootstrap. The bridge is still usable but the affected shared type may be stale. */
+    parseError?: boolean;
+};
+/** Handle returned by {@link createYjsBridge}. */
+type YjsBridgeHandle = {
+    /** Result of the synchronous bootstrap phase. */
+    readonly bootstrapResult: BootstrapResult;
+    /** Serialize `doc` and push to `Y.Text` using minimal diff. */
+    syncToSharedText(doc: Node): ReplaceTextResult;
+    /** Returns `true` if the transaction originated from `y-prosemirror` sync. */
+    isYjsSyncChange(tr: Transaction): boolean;
+    /** Remove the Y.Text observer. Call when tearing down. */
+    dispose(): void;
+};
+
+/** Result of {@link replaceSharedText}. */
+type ReplaceTextResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'unchanged';
+} | {
+    ok: false;
+    reason: 'detached';
+};
+/** Result of {@link replaceSharedProseMirror}. */
+type ReplaceProseMirrorResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'parse-error';
+} | {
+    ok: false;
+    reason: 'detached';
+};
+/**
+ * Union of all replace-result types. Kept for backward compatibility.
+ * Prefer the narrower {@link ReplaceTextResult} / {@link ReplaceProseMirrorResult}.
+ */
+type ReplaceResult = ReplaceTextResult | ReplaceProseMirrorResult;
+/**
+ * Replace `Y.Text` content using a minimal diff (common prefix/suffix trimming).
+ * Returns a {@link ReplaceResult} indicating success or failure reason.
+ */
+declare function replaceSharedText(sharedText: Text, next: string, origin: unknown, normalize?: Normalize): ReplaceTextResult;
+/**
+ * Replace `Y.XmlFragment` by parsing serialized text into a ProseMirror document.
+ * Returns a {@link ReplaceResult} indicating success or failure reason.
+ */
+declare function replaceSharedProseMirror(doc: Doc, fragment: XmlFragment, text: string, origin: unknown, config: Pick<YjsBridgeConfig, 'schema' | 'parse' | 'normalize' | 'onError'>): ReplaceProseMirrorResult;
+/** Options for {@link createYjsBridge}. */
+type YjsBridgeOptions = {
+    initialText?: string;
+    /** Which side wins when both sharedText and sharedProseMirror exist and differ. Default `'text'`. */
+    prefer?: 'text' | 'prosemirror';
+};
+/**
+ * Create a collaborative bridge that keeps `Y.Text` and `Y.XmlFragment` in sync.
+ *
+ * Runs a synchronous bootstrap to reconcile existing state, then installs a
+ * `Y.Text` observer for the text → ProseMirror direction.
+ *
+ * @throws If `sharedText` or `sharedProseMirror` belong to a different `Y.Doc`.
+ */
+declare function createYjsBridge(config: YjsBridgeConfig, options?: YjsBridgeOptions): YjsBridgeHandle;
+
+/**
+ * Create a Proxy around a Yjs {@link Awareness} that suppresses the specified
+ * cursor field. This prevents y-prosemirror's built-in cursor management from
+ * conflicting with the PM↔CM cursor sync plugin.
+ *
+ * Other `setLocalStateField` calls are passed through unchanged.
+ */
+declare function createAwarenessProxy(awareness: Awareness, cursorField?: string): Awareness;
+
+/** Yjs ↔ ProseMirror node mapping used by `y-prosemirror`. */
+type ProseMirrorMapping = Map<AbstractType<unknown>, Node | Node[]>;
+/** Options forwarded to `yCursorPlugin` from y-prosemirror. */
+type YCursorPluginOpts = {
+    awarenessStateFilter?: (currentClientId: number, userClientId: number, user: unknown) => boolean;
+    cursorBuilder?: (user: unknown, clientId: number) => HTMLElement;
+    selectionBuilder?: (user: unknown, clientId: number) => DecorationAttrs;
+    getSelection?: (state: EditorState) => unknown;
+};
+/** Options forwarded to `yUndoPlugin` from y-prosemirror. */
+type YUndoPluginOpts = {
+    protectedNodes?: Set<string>;
+    trackedOrigins?: unknown[];
+    undoManager?: UndoManager | null;
+};
+/** Options for {@link createCollabPlugins}. */
+type CollabPluginsOptions = {
+    /** Shared ProseMirror document in Yjs. */
+    sharedProseMirror: XmlFragment;
+    awareness: Awareness;
+    cursorFieldName?: string;
+    serialize?: Serialize;
+    /** Awareness field used for CM/Y.Text cursor payloads. Default `'cursor'`. */
+    cmCursorFieldName?: string;
+    locate?: LocateText;
+    /**
+     * Enable PM↔CM cursor sync. Default `false`.
+     *
+     * When enabled, an {@link createAwarenessProxy | awareness proxy} is applied
+     * to suppress y-prosemirror's built-in cursor management.
+     */
+    cursorSync?: boolean;
+    /**
+     * The shared `Y.Text` instance. When provided, the cursor sync plugin also
+     * broadcasts CM-format cursor positions so remote `yCollab` instances render them.
+     */
+    sharedText?: Text;
+    /**
+     * When provided, a bridge sync plugin is inserted before the cursor sync plugin
+     * to ensure Y.Text is synced before cursor positions are computed. This guarantees
+     * that serialize-based offsets match Y.Text indices.
+     */
+    bridge?: YjsBridgeHandle;
+    /** Extra options forwarded to `yCursorPlugin`. */
+    yCursorPluginOpts?: YCursorPluginOpts;
+    /** Extra options forwarded to `yUndoPlugin`. */
+    yUndoPluginOpts?: YUndoPluginOpts;
+    /** Called for non-fatal warnings. Propagated to child plugins. Default `console.warn`. */
+    onWarning?: OnWarning;
+};
+/**
+ * Bundle `ySyncPlugin`, `yCursorPlugin`, `yUndoPlugin` from y-prosemirror,
+ * plus an optional PM↔CM cursor sync plugin.
+ *
+ * @throws If `cursorSync: true` but `serialize` is not provided.
+ */
+declare function createCollabPlugins(schema: Schema, options: CollabPluginsOptions): {
+    plugins: Plugin[];
+    doc: Node;
+    mapping: ProseMirrorMapping;
+};
+
+type BridgeSyncState = {
+    needsSync: boolean;
+};
+type BridgeSyncFailure = {
+    ok: false;
+    reason: 'detached';
+};
+/** Options for {@link createBridgeSyncPlugin}. */
+type BridgeSyncPluginOptions = {
+    /** Called when `syncToSharedText` fails (excludes `reason: 'unchanged'`). */
+    onSyncFailure?: (result: BridgeSyncFailure, view: EditorView) => void;
+    /** Called for non-fatal warnings. Default `console.warn`. */
+    onWarning?: OnWarning;
+};
+/** ProseMirror plugin key for {@link createBridgeSyncPlugin}. Use to read the plugin state. */
+declare const bridgeSyncPluginKey: PluginKey<BridgeSyncState>;
+/**
+ * ProseMirror plugin that automatically syncs PM doc changes to Y.Text
+ * via the bridge handle. Skips Yjs-originated changes to avoid loops.
+ *
+ * A warning is logged if the same bridge handle is wired more than once.
+ * The guard is cleaned up when the plugin is destroyed.
+ */
+declare function createBridgeSyncPlugin(bridge: YjsBridgeHandle, options?: BridgeSyncPluginOptions): Plugin;
+
+/** Plugin state for the cursor sync plugin. Read via {@link cursorSyncPluginKey}. */
+type CursorSyncState = {
+    /** Pending CodeMirror cursor to broadcast. Set by {@link syncCmCursor}. */
+    pendingCm: {
+        anchor: number;
+        head: number;
+    } | null;
+    /** Text offset mapped from the current PM selection anchor. `null` when no mapping is available. */
+    mappedTextOffset: number | null;
+};
+/** ProseMirror plugin key for {@link createCursorSyncPlugin}. Use to read the plugin state. */
+declare const cursorSyncPluginKey: PluginKey<CursorSyncState>;
+/** Options for {@link createCursorSyncPlugin}. */
+type CursorSyncPluginOptions = {
+    awareness: Awareness;
+    serialize: Serialize;
+    cursorFieldName?: string;
+    /** Awareness field used for CM/Y.Text cursor payloads. Default `'cursor'`. */
+    cmCursorFieldName?: string;
+    locate?: LocateText;
+    /**
+     * When provided, the plugin also broadcasts CM-format cursor positions
+     * (Y.Text relative positions) to the awareness field specified by
+     * `cmCursorFieldName`, so that remote `yCollab` instances can render the cursor.
+     */
+    sharedText?: Text;
+    /** Called for non-fatal warnings. Default `console.warn`. */
+    onWarning?: OnWarning;
+};
+/**
+ * ProseMirror plugin that synchronizes cursor positions between PM and CM via Yjs awareness.
+ *
+ * - PM → awareness: automatically broadcasts when the PM view is focused and selection changes.
+ * - CM → awareness: triggered by dispatching {@link syncCmCursor}.
+ */
+declare function createCursorSyncPlugin(options: CursorSyncPluginOptions): Plugin;
+/**
+ * Dispatch a CodeMirror cursor offset (or range) to the cursor sync plugin.
+ * The plugin will convert it to a ProseMirror position and broadcast via awareness.
+ *
+ * @param view - The ProseMirror EditorView that has the cursor sync plugin installed.
+ * @param anchor - CodeMirror text offset for the anchor.
+ * @param head - CodeMirror text offset for the head (defaults to `anchor` for a collapsed cursor).
+ * @param onWarning - Optional warning callback. Default `console.warn`.
+ */
+declare function syncCmCursor(view: EditorView, anchor: number, head?: number, onWarning?: OnWarning): void;
+
+export { type BootstrapResult, type BridgeSyncPluginOptions, type CollabPluginsOptions, type CursorSyncPluginOptions, type CursorSyncState, ORIGIN_INIT, ORIGIN_PM_TO_TEXT, ORIGIN_TEXT_TO_PM, type OnWarning, type ProseMirrorMapping, type ReplaceProseMirrorResult, type ReplaceResult, type ReplaceTextResult, type WarningCode, type WarningEvent, type YCursorPluginOpts, type YUndoPluginOpts, type YjsBridgeConfig, type YjsBridgeHandle, type YjsBridgeOptions, bridgeSyncPluginKey, createAwarenessProxy, createBridgeSyncPlugin, createCollabPlugins, createCursorSyncPlugin, createYjsBridge, cursorSyncPluginKey, replaceSharedProseMirror, replaceSharedText, syncCmCursor };

package/dist/index.d.ts

@@ -0,0 +1,259 @@
+import { Doc, Text, XmlFragment, UndoManager, AbstractType } from 'yjs';
+import { Serialize, Parse, Normalize, OnError, LocateText } from '@pm-cm/core';
+export { CursorMap, ErrorCode, ErrorEvent, LocateText, Normalize, OnError, Parse, Serialize, TextSegment, buildCursorMap, cursorMapLookup, reverseCursorMapLookup } from '@pm-cm/core';
+import { Node, Schema } from 'prosemirror-model';
+import { Transaction, EditorState, Plugin, PluginKey } from 'prosemirror-state';
+import { Awareness } from 'y-protocols/awareness';
+import { DecorationAttrs, EditorView } from 'prosemirror-view';
+
+/** Known warning codes emitted by the yjs bridge and plugins. */
+type WarningCode = 'bridge-already-wired' | 'sync-failed' | 'ysync-plugin-missing' | 'cursor-sync-not-installed';
+/** Structured warning event for non-fatal warnings. */
+type WarningEvent = {
+    code: WarningCode;
+    message: string;
+};
+/**
+ * Warning handler callback for non-fatal warnings.
+ *
+ * Known codes:
+ * - `'bridge-already-wired'` — the same bridge handle is wired to multiple plugin instances.
+ * - `'sync-failed'` — `syncToSharedText` failed (e.g. Y.Text detached).
+ * - `'ysync-plugin-missing'` — ySyncPlugin state is not available; cursor broadcast skipped.
+ * - `'cursor-sync-not-installed'` — cursor sync plugin is not installed on the EditorView.
+ */
+type OnWarning = (event: WarningEvent) => void;
+/** Yjs transaction origin: text → ProseMirror direction. */
+declare const ORIGIN_TEXT_TO_PM = "bridge:text-to-prosemirror";
+/** Yjs transaction origin: ProseMirror → text direction. */
+declare const ORIGIN_PM_TO_TEXT = "bridge:prosemirror-to-text";
+/** Yjs transaction origin: bootstrap initialization. */
+declare const ORIGIN_INIT = "bridge:init";
+/** Configuration for {@link createYjsBridge}. */
+type YjsBridgeConfig = {
+    doc: Doc;
+    sharedText: Text;
+    sharedProseMirror: XmlFragment;
+    schema: Schema;
+    serialize: Serialize;
+    parse: Parse;
+    normalize?: Normalize;
+    /** Called on non-fatal errors (e.g. parse failures). Defaults to `console.error`. */
+    onError?: OnError;
+};
+/**
+ * Result of the bootstrap phase in {@link createYjsBridge}.
+ * Indicates which source was used to initialize the shared types.
+ */
+type BootstrapResult = {
+    source: 'text' | 'prosemirror' | 'both-match' | 'empty' | 'initial';
+    /** `true` when format conversion (parse or serialize) failed during bootstrap. The bridge is still usable but the affected shared type may be stale. */
+    parseError?: boolean;
+};
+/** Handle returned by {@link createYjsBridge}. */
+type YjsBridgeHandle = {
+    /** Result of the synchronous bootstrap phase. */
+    readonly bootstrapResult: BootstrapResult;
+    /** Serialize `doc` and push to `Y.Text` using minimal diff. */
+    syncToSharedText(doc: Node): ReplaceTextResult;
+    /** Returns `true` if the transaction originated from `y-prosemirror` sync. */
+    isYjsSyncChange(tr: Transaction): boolean;
+    /** Remove the Y.Text observer. Call when tearing down. */
+    dispose(): void;
+};
+
+/** Result of {@link replaceSharedText}. */
+type ReplaceTextResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'unchanged';
+} | {
+    ok: false;
+    reason: 'detached';
+};
+/** Result of {@link replaceSharedProseMirror}. */
+type ReplaceProseMirrorResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'parse-error';
+} | {
+    ok: false;
+    reason: 'detached';
+};
+/**
+ * Union of all replace-result types. Kept for backward compatibility.
+ * Prefer the narrower {@link ReplaceTextResult} / {@link ReplaceProseMirrorResult}.
+ */
+type ReplaceResult = ReplaceTextResult | ReplaceProseMirrorResult;
+/**
+ * Replace `Y.Text` content using a minimal diff (common prefix/suffix trimming).
+ * Returns a {@link ReplaceResult} indicating success or failure reason.
+ */
+declare function replaceSharedText(sharedText: Text, next: string, origin: unknown, normalize?: Normalize): ReplaceTextResult;
+/**
+ * Replace `Y.XmlFragment` by parsing serialized text into a ProseMirror document.
+ * Returns a {@link ReplaceResult} indicating success or failure reason.
+ */
+declare function replaceSharedProseMirror(doc: Doc, fragment: XmlFragment, text: string, origin: unknown, config: Pick<YjsBridgeConfig, 'schema' | 'parse' | 'normalize' | 'onError'>): ReplaceProseMirrorResult;
+/** Options for {@link createYjsBridge}. */
+type YjsBridgeOptions = {
+    initialText?: string;
+    /** Which side wins when both sharedText and sharedProseMirror exist and differ. Default `'text'`. */
+    prefer?: 'text' | 'prosemirror';
+};
+/**
+ * Create a collaborative bridge that keeps `Y.Text` and `Y.XmlFragment` in sync.
+ *
+ * Runs a synchronous bootstrap to reconcile existing state, then installs a
+ * `Y.Text` observer for the text → ProseMirror direction.
+ *
+ * @throws If `sharedText` or `sharedProseMirror` belong to a different `Y.Doc`.
+ */
+declare function createYjsBridge(config: YjsBridgeConfig, options?: YjsBridgeOptions): YjsBridgeHandle;
+
+/**
+ * Create a Proxy around a Yjs {@link Awareness} that suppresses the specified
+ * cursor field. This prevents y-prosemirror's built-in cursor management from
+ * conflicting with the PM↔CM cursor sync plugin.
+ *
+ * Other `setLocalStateField` calls are passed through unchanged.
+ */
+declare function createAwarenessProxy(awareness: Awareness, cursorField?: string): Awareness;
+
+/** Yjs ↔ ProseMirror node mapping used by `y-prosemirror`. */
+type ProseMirrorMapping = Map<AbstractType<unknown>, Node | Node[]>;
+/** Options forwarded to `yCursorPlugin` from y-prosemirror. */
+type YCursorPluginOpts = {
+    awarenessStateFilter?: (currentClientId: number, userClientId: number, user: unknown) => boolean;
+    cursorBuilder?: (user: unknown, clientId: number) => HTMLElement;
+    selectionBuilder?: (user: unknown, clientId: number) => DecorationAttrs;
+    getSelection?: (state: EditorState) => unknown;
+};
+/** Options forwarded to `yUndoPlugin` from y-prosemirror. */
+type YUndoPluginOpts = {
+    protectedNodes?: Set<string>;
+    trackedOrigins?: unknown[];
+    undoManager?: UndoManager | null;
+};
+/** Options for {@link createCollabPlugins}. */
+type CollabPluginsOptions = {
+    /** Shared ProseMirror document in Yjs. */
+    sharedProseMirror: XmlFragment;
+    awareness: Awareness;
+    cursorFieldName?: string;
+    serialize?: Serialize;
+    /** Awareness field used for CM/Y.Text cursor payloads. Default `'cursor'`. */
+    cmCursorFieldName?: string;
+    locate?: LocateText;
+    /**
+     * Enable PM↔CM cursor sync. Default `false`.
+     *
+     * When enabled, an {@link createAwarenessProxy | awareness proxy} is applied
+     * to suppress y-prosemirror's built-in cursor management.
+     */
+    cursorSync?: boolean;
+    /**
+     * The shared `Y.Text` instance. When provided, the cursor sync plugin also
+     * broadcasts CM-format cursor positions so remote `yCollab` instances render them.
+     */
+    sharedText?: Text;
+    /**
+     * When provided, a bridge sync plugin is inserted before the cursor sync plugin
+     * to ensure Y.Text is synced before cursor positions are computed. This guarantees
+     * that serialize-based offsets match Y.Text indices.
+     */
+    bridge?: YjsBridgeHandle;
+    /** Extra options forwarded to `yCursorPlugin`. */
+    yCursorPluginOpts?: YCursorPluginOpts;
+    /** Extra options forwarded to `yUndoPlugin`. */
+    yUndoPluginOpts?: YUndoPluginOpts;
+    /** Called for non-fatal warnings. Propagated to child plugins. Default `console.warn`. */
+    onWarning?: OnWarning;
+};
+/**
+ * Bundle `ySyncPlugin`, `yCursorPlugin`, `yUndoPlugin` from y-prosemirror,
+ * plus an optional PM↔CM cursor sync plugin.
+ *
+ * @throws If `cursorSync: true` but `serialize` is not provided.
+ */
+declare function createCollabPlugins(schema: Schema, options: CollabPluginsOptions): {
+    plugins: Plugin[];
+    doc: Node;
+    mapping: ProseMirrorMapping;
+};
+
+type BridgeSyncState = {
+    needsSync: boolean;
+};
+type BridgeSyncFailure = {
+    ok: false;
+    reason: 'detached';
+};
+/** Options for {@link createBridgeSyncPlugin}. */
+type BridgeSyncPluginOptions = {
+    /** Called when `syncToSharedText` fails (excludes `reason: 'unchanged'`). */
+    onSyncFailure?: (result: BridgeSyncFailure, view: EditorView) => void;
+    /** Called for non-fatal warnings. Default `console.warn`. */
+    onWarning?: OnWarning;
+};
+/** ProseMirror plugin key for {@link createBridgeSyncPlugin}. Use to read the plugin state. */
+declare const bridgeSyncPluginKey: PluginKey<BridgeSyncState>;
+/**
+ * ProseMirror plugin that automatically syncs PM doc changes to Y.Text
+ * via the bridge handle. Skips Yjs-originated changes to avoid loops.
+ *
+ * A warning is logged if the same bridge handle is wired more than once.
+ * The guard is cleaned up when the plugin is destroyed.
+ */
+declare function createBridgeSyncPlugin(bridge: YjsBridgeHandle, options?: BridgeSyncPluginOptions): Plugin;
+
+/** Plugin state for the cursor sync plugin. Read via {@link cursorSyncPluginKey}. */
+type CursorSyncState = {
+    /** Pending CodeMirror cursor to broadcast. Set by {@link syncCmCursor}. */
+    pendingCm: {
+        anchor: number;
+        head: number;
+    } | null;
+    /** Text offset mapped from the current PM selection anchor. `null` when no mapping is available. */
+    mappedTextOffset: number | null;
+};
+/** ProseMirror plugin key for {@link createCursorSyncPlugin}. Use to read the plugin state. */
+declare const cursorSyncPluginKey: PluginKey<CursorSyncState>;
+/** Options for {@link createCursorSyncPlugin}. */
+type CursorSyncPluginOptions = {
+    awareness: Awareness;
+    serialize: Serialize;
+    cursorFieldName?: string;
+    /** Awareness field used for CM/Y.Text cursor payloads. Default `'cursor'`. */
+    cmCursorFieldName?: string;
+    locate?: LocateText;
+    /**
+     * When provided, the plugin also broadcasts CM-format cursor positions
+     * (Y.Text relative positions) to the awareness field specified by
+     * `cmCursorFieldName`, so that remote `yCollab` instances can render the cursor.
+     */
+    sharedText?: Text;
+    /** Called for non-fatal warnings. Default `console.warn`. */
+    onWarning?: OnWarning;
+};
+/**
+ * ProseMirror plugin that synchronizes cursor positions between PM and CM via Yjs awareness.
+ *
+ * - PM → awareness: automatically broadcasts when the PM view is focused and selection changes.
+ * - CM → awareness: triggered by dispatching {@link syncCmCursor}.
+ */
+declare function createCursorSyncPlugin(options: CursorSyncPluginOptions): Plugin;
+/**
+ * Dispatch a CodeMirror cursor offset (or range) to the cursor sync plugin.
+ * The plugin will convert it to a ProseMirror position and broadcast via awareness.
+ *
+ * @param view - The ProseMirror EditorView that has the cursor sync plugin installed.
+ * @param anchor - CodeMirror text offset for the anchor.
+ * @param head - CodeMirror text offset for the head (defaults to `anchor` for a collapsed cursor).
+ * @param onWarning - Optional warning callback. Default `console.warn`.
+ */
+declare function syncCmCursor(view: EditorView, anchor: number, head?: number, onWarning?: OnWarning): void;
+
+export { type BootstrapResult, type BridgeSyncPluginOptions, type CollabPluginsOptions, type CursorSyncPluginOptions, type CursorSyncState, ORIGIN_INIT, ORIGIN_PM_TO_TEXT, ORIGIN_TEXT_TO_PM, type OnWarning, type ProseMirrorMapping, type ReplaceProseMirrorResult, type ReplaceResult, type ReplaceTextResult, type WarningCode, type WarningEvent, type YCursorPluginOpts, type YUndoPluginOpts, type YjsBridgeConfig, type YjsBridgeHandle, type YjsBridgeOptions, bridgeSyncPluginKey, createAwarenessProxy, createBridgeSyncPlugin, createCollabPlugins, createCursorSyncPlugin, createYjsBridge, cursorSyncPluginKey, replaceSharedProseMirror, replaceSharedText, syncCmCursor };