[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10,"_11":12},"actionData","errors","root",{"_228":-5,"_231":232,"_233":234},"routes/shell",{"_40":41,"_227":-5,"_228":-5,"_229":230},"routes/repo",{"_33":-7,"_34":35,"_36":37,"_38":39,"_40":41,"_42":31,"_43":31,"_44":31,"_45":31,"_46":31,"_47":31,"_48":49,"_50":49,"_51":31,"_52":-7,"_53":-7,"_54":55,"_56":57,"_58":59,"_60":-5,"_61":62,"_63":64,"_65":66,"_67":68},"routes/repo.blob",{"_13":14,"_15":16,"_17":18,"_19":20,"_21":14,"_22":23,"_24":-5,"_25":26,"_27":28,"_28":29,"_30":31,"_32":14},"ref","5d33a70a3bc01df2cf2ed6eab3d1c876fe8c7b54","path","apps/server/src/plan/room.ts","oid","ba6985d98aef404e6915dab26722a00c6e0f060a","size",30185,"commit","mounts",[],"source","plain",{"_13":14,"_15":16},"kind","text","/**\n * The authoritative collaborative document.\n *\n * The server owns the Y.Doc and a headless Lexical editor bound to it. That\n * mirror is what lets the server reason about the document at all: it turns\n * opaque CRDT updates into a tree that can be validated and projected back to\n * canonical MDX, with nobody connected.\n *\n * Clients never bootstrap. Two browsers opening an empty plan at the same time\n * would otherwise both seed it and duplicate the content, so the server creates\n * the initial state and everyone else syncs to it.\n */\n\nimport { createHash } from \"node:crypto\";\n\nimport { createHeadlessEditor } from \"@lexical/headless\";\nimport { createYjsBinding, syncLexicalUpdateToYjs, syncYjsChangesToLexical } from \"@lexical/yjs\";\nimport * as Y from \"yjs\";\n\nimport {\n\t$createDecisionNode,\n\t$createPlanNodes,\n\t$createQuestionnaireNode,\n\t$exportPlan,\n\t$importPlan,\n\texportPlan,\n\tlimits,\n\tparse,\n\tPlanValidationError,\n\tQuestionnaireNode,\n\tregistry as buildRegistry,\n\tserialize,\n\tulid,\n} from \"@chopin/dialect\";\nimport { $getAnchorAndFocusForUserState } from \"@lexical/yjs\";\nimport { $getNodeByKey, $getRoot, $isElementNode, $isParagraphNode, $nodesOfType } from \"lexical\";\n\nimport type { Binding, Provider } from \"@lexical/yjs\";\nimport type { LexicalEditor, LexicalNode } from \"lexical\";\nimport type { Root, RootContent } from \"mdast\";\nimport type { Decision, Questionnaire, Registry } from \"@chopin/dialect\";\nimport type { Plan } from \"@chopin/protocol\";\n\ntype Anchor = Plan.Anchor;\ntype Passage = Plan.Passage;\n\n/** Awareness is relayed, never interpreted here, so a no-op provider suffices. */\nconst PROVIDER = {\n\tawareness: {\n\t\tgetLocalState: () => null,\n\t\tgetStates: () => new Map(),\n\t\toff() {},\n\t\ton() {},\n\t\tsetLocalState() {},\n\t\tsetLocalStateField() {},\n\t},\n\tconnect() {},\n\tdisconnect() {},\n\toff() {},\n\ton() {},\n} as unknown as Provider;\n\nconst DOC = \"plan\";\nconst REMOTE = \"remote\";\n\n/** Yjs state size past which history is compacted into a fresh epoch. */\nconst MAX_STATE = limits.MAX_COLLAB_BYTES;\n\nexport const LIMITS = {\n\tsource: limits.MAX_SOURCE_BYTES,\n\tupdate: limits.MAX_UPDATE_BYTES,\n\tdepth: limits.MAX_DEPTH,\n};\n\nexport type Document = {\n\t/** Identifies one Yjs history. Updates carrying another are rejected. */\n\tepoch: string;\n\tdoc: Y.Doc;\n\teditor: LexicalEditor;\n\tbinding: Binding;\n\t/** Monotonic within an epoch. */\n\tseq: number;\n\t/**\n\t * Last known-good Yjs state, and the source that matched it.\n\t *\n\t * Yjs cannot undo a transaction, so an update that turns out to be invalid\n\t * cannot be rolled back — the document is rebuilt from here instead. This\n\t * is refreshed when the room snapshots rather than on every commit: an\n\t * invalid update means a bug somewhere, and paying to re-encode the whole\n\t * document on the common path to soften a case that should never happen is\n\t * the wrong trade.\n\t */\n\tcheckpoint: Uint8Array;\n};\n\n/**\n * The schema, built once per process.\n *\n * Registry construction walks every plugin, and the result is immutable and\n * shared. Rooms differ in their content, never in what content is legal.\n */\nlet registry: Registry | undefined;\n\nfunction schema(): Registry {\n\treturn registry ??= buildRegistry();\n}\n\n/** Remote updates reach Lexical on a microtask; let the mirror catch up. */\nexport async function settle(): Promise {\n\tfor (let i = 0; i < 3; i++) await new Promise(resolve => setTimeout(resolve, 0));\n}\n\nfunction build(epoch: string): Document {\n\tlet reg = schema();\n\tlet editor = createHeadlessEditor({\n\t\tnodes: reg.nodes,\n\t\tonError(err) {\n\t\t\tconsole.error(\"[plan] lexical:\", err);\n\t\t},\n\t});\n\n\tlet doc = new Y.Doc();\n\tlet binding = createYjsBinding({ editor, id: DOC, doc, docMap: new Map([[DOC, doc]]) });\n\n\teditor.registerUpdateListener(\n\t\t({ dirtyElements, dirtyLeaves, editorState, normalizedNodes, prevEditorState, tags }) => {\n\t\t\tif (tags.has(\"skip-collab\")) return;\n\t\t\tsyncLexicalUpdateToYjs(\n\t\t\t\tbinding,\n\t\t\t\tPROVIDER,\n\t\t\t\tprevEditorState,\n\t\t\t\teditorState,\n\t\t\t\tdirtyElements,\n\t\t\t\tdirtyLeaves,\n\t\t\t\tnormalizedNodes,\n\t\t\t\ttags,\n\t\t\t);\n\t\t},\n\t);\n\n\tbinding.root.getSharedType().observeDeep((events, transaction) => {\n\t\tif (transaction.origin !== binding) syncYjsChangesToLexical(binding, PROVIDER, events, false);\n\t});\n\n\treturn { epoch, doc, editor, binding, seq: 0, checkpoint: Y.encodeStateAsUpdate(doc) };\n}\n\n/**\n * Seed from canonical MDX, through the mirror so Yjs sees real structure.\n *\n * Validation is on by default because the usual caller is a snapshot read back\n * from disk, which a person can edit between runs. Internally produced source —\n * a compaction, a replacement we just projected — has already been proven and\n * says so.\n */\nfunction seed(target: Document, source: string, validated = false): void {\n\tif (!source.trim()) return;\n\n\t// Lexical routes anything thrown inside an update to the editor's onError,\n\t// which logs. Left alone, a plan that fails to import would produce an\n\t// empty document and no failure — so the error is carried out by hand.\n\tlet failure: unknown;\n\ttarget.editor.update(\n\t\t() => {\n\t\t\ttry {\n\t\t\t\t$importPlan(source, { registry: schema(), validate: !validated });\n\t\t\t} catch (err) {\n\t\t\t\tfailure = err;\n\t\t\t}\n\t\t},\n\t\t{ discrete: true },\n\t);\n\tif (failure) throw failure;\n}\n\n/** Canonical MDX for the current shared state. Throws if it is not valid. */\nexport function project(target: Document): string {\n\tlet source = \"\";\n\tlet failure: unknown;\n\ttarget.editor.getEditorState().read(() => {\n\t\ttry {\n\t\t\tsource = $exportPlan({ registry: schema() });\n\t\t} catch (err) {\n\t\t\tfailure = err;\n\t\t}\n\t});\n\tif (failure) throw failure;\n\treturn source;\n}\n\n/**\n * Prove source survives the same Lexical import/export path as a live room.\n *\n * MDAST validation alone cannot catch a visitor that accepts a node but fails\n * to construct or export it. Anything about to be written to a real document\n * runs this scratch pass first.\n */\nexport function validate(source: string): void {\n\tlet reg = schema();\n\tlet editor = createHeadlessEditor({\n\t\tnodes: reg.nodes,\n\t\tonError(err) {\n\t\t\tthrow err;\n\t\t},\n\t});\n\n\tlet failure: unknown;\n\teditor.update(\n\t\t() => {\n\t\t\ttry {\n\t\t\t\t$importPlan(source, { registry: reg });\n\t\t\t} catch (err) {\n\t\t\t\tfailure = err;\n\t\t\t}\n\t\t},\n\t\t{ discrete: true },\n\t);\n\tif (failure) throw failure;\n\n\t// Export is part of the proof: we have to be able to snapshot what we\n\t// imported, not merely hold it in memory.\n\tlet output = exportPlan(editor, { registry: reg });\n\tif (JSON.stringify(semantic(parse(output))) !== JSON.stringify(semantic(parse(source)))) {\n\t\tthrow new Error(\"plan source changes during its Lexical round trip\");\n\t}\n}\n\n/** MDAST equality without source positions or JSX attribute ordering. */\nfunction semantic(value: unknown, key = \"\"): unknown {\n\tif (Array.isArray(value)) {\n\t\tlet items = value.map(item => semantic(item));\n\t\treturn key === \"attributes\"\n\t\t\t? items.toSorted((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)))\n\t\t\t: items;\n\t}\n\tif (!value || typeof value !== \"object\") return value;\n\n\tlet out: Record = {};\n\tfor (let [name, child] of Object.entries(value)) {\n\t\tif (name === \"position\") continue;\n\t\tout[name] = semantic(child, name);\n\t}\n\treturn out;\n}\n\n/** Create a document, optionally seeded from source that survived a restart. */\nexport async function create(source = \"\", validated = false): Promise {\n\tlet created = build(ulid());\n\tseed(created, source, validated);\n\tawait settle();\n\tcreated.checkpoint = Y.encodeStateAsUpdate(created.doc);\n\treturn created;\n}\n\n/** State the given client is missing, or the whole document when it has none. */\nexport function sync(target: Document, vector?: Uint8Array): Uint8Array {\n\treturn Y.encodeStateAsUpdate(target.doc, vector);\n}\n\nexport function stateSize(target: Document): number {\n\treturn Y.encodeStateAsUpdate(target.doc).byteLength;\n}\n\nexport function needsCompaction(target: Document): boolean {\n\treturn stateSize(target) >= MAX_STATE;\n}\n\n/** Record the current state as the one a rebuild should restore. */\nexport function mark(target: Document): void {\n\ttarget.checkpoint = Y.encodeStateAsUpdate(target.doc);\n}\n\nexport type Applied =\n\t| { ok: true; seq: number }\n\t| { ok: false; issues: string[] };\n\n/**\n * Apply a batch of client updates.\n *\n * Batched because validation is the expensive part: projecting the whole\n * document proves the shared tree still serialises to something the dialect\n * accepts, and doing that per keystroke would be absurd.\n */\nexport async function apply(target: Document, updates: Uint8Array[]): Promise {\n\tif (updates.length === 0) return { ok: true, seq: target.seq };\n\n\tfor (let update of updates) Y.applyUpdate(target.doc, update, REMOTE);\n\tawait settle();\n\n\ttry {\n\t\tproject(target);\n\t} catch (err) {\n\t\tif (!(err instanceof PlanValidationError)) throw err;\n\t\treturn { ok: false, issues: err.issues.map(issue => issue.code) };\n\t}\n\n\ttarget.seq += updates.length;\n\treturn { ok: true, seq: target.seq };\n}\n\n/**\n * Restore the last known-good state under a new epoch.\n *\n * Everyone loses undo history and cursor positions, which is the price of the\n * document being coherent again.\n */\nexport async function rebuild(target: Document): Promise {\n\tlet restored = build(ulid());\n\tY.applyUpdate(restored.doc, target.checkpoint, REMOTE);\n\tawait settle();\n\trestored.checkpoint = Y.encodeStateAsUpdate(restored.doc);\n\treturn restored;\n}\n\n/**\n * Replace the content wholesale under a fresh epoch.\n *\n * For deliberate discontinuities only: clearing, and history compaction.\n * Ordinary agent edits reconcile into the live tree instead, so node identity,\n * selection and scroll position survive them.\n */\nexport async function replace(source: string): Promise {\n\t// Already projected from a live document, or validated by its caller.\n\treturn create(source, true);\n}\n\n/**\n * Compact history once it outgrows its budget.\n *\n * Yjs keeps tombstones for everything ever deleted, so a long-lived document\n * grows well past the size of its content. Callers do this while the room is\n * idle, because it costs every client their undo history.\n */\nexport async function compact(target: Document): Promise {\n\tif (!needsCompaction(target)) return undefined;\n\treturn replace(project(target));\n}\n\n// -- server-authored mutations ---------------------------------------------\n\nexport type Mutation = {\n\t/** Yjs delta covering only what this mutation changed. */\n\tupdate: Uint8Array;\n\t/** Canonical source afterwards. */\n\tsource: string;\n};\n\n/**\n * Apply a change of our own to the live document.\n *\n * Returns the delta since before the change so it can be relayed as an\n * ordinary update. Peers reconcile it into the document they already have,\n * which is why an agent edit does not cost anyone their cursor or undo\n * history the way an epoch rotation would.\n */\nfunction mutate(target: Document, change: () => boolean): Mutation | undefined {\n\tlet vector = Y.encodeStateVector(target.doc);\n\tlet changed = false;\n\tlet failure: unknown;\n\n\ttarget.editor.update(\n\t\t() => {\n\t\t\ttry {\n\t\t\t\tchanged = change();\n\t\t\t} catch (err) {\n\t\t\t\tfailure = err;\n\t\t\t}\n\t\t},\n\t\t{ discrete: true },\n\t);\n\tif (failure) throw failure;\n\tif (!changed) return undefined;\n\n\treturn { update: Y.encodeStateAsUpdate(target.doc, vector), source: project(target) };\n}\n\n/** Append a questionnaire to the plan. */\nexport function insertQuestionnaire(\n\ttarget: Document,\n\tvalue: Questionnaire,\n): Mutation | undefined {\n\treturn mutate(target, () => {\n\t\t$getRoot().append($createQuestionnaireNode(value));\n\t\treturn true;\n\t});\n}\n\n/**\n * Append an accepted comment thread to the plan.\n *\n * At the end rather than beside the prose it concerns: the node renders as\n * nothing, so its position only affects how `plan.mdx` reads, and decisions\n * gathered in one place read as the record they are. Written once and never\n * revised — what marks the prose is the passage, which keeps moving.\n */\nexport function insertDecision(target: Document, value: Decision): Mutation | undefined {\n\treturn mutate(target, () => {\n\t\t$getRoot().append($createDecisionNode(value));\n\t\treturn true;\n\t});\n}\n\n/**\n * Write a resolved answer into the document.\n *\n * The sidecar record is authoritative; this only makes the plan read correctly\n * on its own. A discrepancy means the projection is stale, never that the\n * document has decided something different.\n */\nexport function projectAnswer(\n\ttarget: Document,\n\tid: string,\n\tanswers: Record,\n): Mutation | undefined {\n\treturn mutate(target, () => {\n\t\tlet found = false;\n\t\tfor (let node of $nodesOfType(QuestionnaireNode)) {\n\t\t\tif (node.getId() !== id) continue;\n\t\t\tfound = true;\n\t\t\tlet value = node.getQuestionnaire();\n\t\t\tnode.setQuestionnaire({\n\t\t\t\t...value,\n\t\t\t\tquestions: value.questions.map(question => {\n\t\t\t\t\tlet answer = answers[question.id];\n\t\t\t\t\treturn answer === undefined ? question : { ...question, answer };\n\t\t\t\t}),\n\t\t\t});\n\t\t}\n\t\treturn found;\n\t});\n}\n\n/** Take a questionnaire out of the plan, leaving its record as history. */\nexport function removeQuestionnaire(target: Document, id: string): Mutation | undefined {\n\treturn mutate(target, () => {\n\t\tlet found = false;\n\t\tfor (let node of $nodesOfType(QuestionnaireNode)) {\n\t\t\tif (node.getId() !== id) continue;\n\t\t\tfound = true;\n\t\t\tnode.remove();\n\t\t}\n\t\treturn found;\n\t});\n}\n\n/**\n * Reconcile a validated sequence of top-level blocks into the live document.\n *\n * Object identity in `after` is what distinguishes a block that came from the\n * source the agent read from one it has just written. The former map to the\n * Lexical nodes already there, so they keep their keys through the edit and\n * through every move around them — which is why an agent rewriting one\n * paragraph does not cost everyone else their cursor, their selection or their\n * undo history. Only genuinely new blocks are constructed, and they have to be\n * constructed in this editor: Lexical nodes cannot be carried in from another.\n */\nexport function reconcile(\n\ttarget: Document,\n\tbefore: RootContent[],\n\tafter: RootContent[],\n): Mutation | undefined {\n\treturn mutate(target, () => {\n\t\tlet root = $getRoot();\n\t\tlet all = root.getChildren();\n\n\t\t// An empty paragraph is a caret affordance, not a block the agent can\n\t\t// address, so it has no place in the mapping and this edit may remove it.\n\t\tlet live = all.filter(node => !($isParagraphNode(node) && node.getChildrenSize() === 0));\n\t\tif (live.length !== before.length) {\n\t\t\tthrow new Error(\"the plan changed while the edit was being applied\");\n\t\t}\n\n\t\tlet nodes = new Map();\n\t\tbefore.forEach((node, index) => nodes.set(node, live[index]!));\n\n\t\tlet fresh = after.filter(node => !nodes.has(node));\n\t\tlet created = $createPlanNodes(\n\t\t\t{ type: \"root\", children: fresh } as Root,\n\t\t\t{ registry: schema(), validate: false },\n\t\t);\n\t\tif (created.length !== fresh.length) {\n\t\t\tthrow new Error(\"a plan block did not import to exactly one node\");\n\t\t}\n\t\tfresh.forEach((node, index) => nodes.set(node, created[index]!));\n\n\t\troot.splice(\n\t\t\t0,\n\t\t\tall.length,\n\t\t\tafter.map(node => {\n\t\t\t\tlet found = nodes.get(node);\n\t\t\t\tif (!found) throw new Error(\"a plan block has no live node\");\n\t\t\t\treturn found;\n\t\t\t}),\n\t\t);\n\t\treturn true;\n\t});\n}\n\n// -- anchors ---------------------------------------------------------------\n\n/**\n * Where a decision sits in the prose.\n *\n * A Yjs relative position rather than an index, because an index is wrong the\n * moment anybody inserts a paragraph above it. The relative position survives\n * edits around the block it names; the digest is what recovers it when the\n * position cannot be resolved at all — after the block moves, or after an\n * epoch rotation throws away the history the position was expressed in.\n */\n\n/** Blocks an anchor can name: the ones the source addresses. */\nfunction addressable(): LexicalNode[] {\n\treturn $getRoot().getChildren().filter(\n\t\tnode => !($isParagraphNode(node) && node.getChildrenSize() === 0),\n\t);\n}\n\nexport function digest(source: string): string {\n\treturn `sha256:${createHash(\"sha256\").update(source).digest(\"hex\")}`;\n}\n\n/** Canonical hash of each top-level block, in order. */\nexport function digests(target: Document): string[] {\n\treturn parse(project(target)).children.map(node =>\n\t\tdigest(serialize({ type: \"root\", children: [node] }))\n\t);\n}\n\nfunction anchorForKey(target: Document, key: string | undefined, hash: string): Anchor {\n\tlet collab = key ? target.binding.collabNodeMap.get(key) : undefined;\n\tlet type = collab?.getSharedType();\n\tif (!type) throw new Error(\"anchored block has no collaborative identity\");\n\n\treturn {\n\t\tepoch: target.epoch,\n\t\tposition: Buffer.from(\n\t\t\tY.encodeRelativePosition(Y.createRelativePositionFromTypeIndex(type, 0, -1)),\n\t\t).toString(\"base64\"),\n\t\tdigest: hash,\n\t};\n}\n\n/** Anchor the block currently at `index`. */\nexport function anchorAt(target: Document, index: number, hash: string): Anchor {\n\tlet key: string | undefined;\n\ttarget.editor.getEditorState().read(() => {\n\t\tkey = addressable()[index]?.getKey();\n\t});\n\treturn anchorForKey(target, key, hash);\n}\n\n/** The local node an anchor names, if it still names one. */\nexport function resolveAnchor(target: Document, anchor: Anchor): string | undefined {\n\tif (anchor.epoch !== target.epoch) return undefined;\n\ttry {\n\t\tlet relative = Y.decodeRelativePosition(Buffer.from(anchor.position, \"base64\"));\n\t\tlet absolute = Y.createAbsolutePositionFromRelativePosition(relative, target.doc, false);\n\t\tif (!absolute) return undefined;\n\t\tfor (let [key, collab] of target.binding.collabNodeMap) {\n\t\t\tif (collab.getSharedType() === absolute.type) return key;\n\t\t}\n\t} catch {\n\t\t// A position from a history this document no longer has. The digest is\n\t\t// the fallback, and the caller is about to try it.\n\t}\n\treturn undefined;\n}\n\n/**\n * Bring anchors forward onto the document as it is now.\n *\n * Resolvable positions are re-expressed against the block they still name, so\n * a digest kept up to date with the content. Anything that cannot be resolved\n * is matched by digest — and only when exactly one block matches, because two\n * identical paragraphs give no way to tell which was meant. The rest are kept\n * and marked orphaned rather than guessed at: a relationship pointing at the\n * wrong passage is worse than one admitting it is lost.\n */\nexport function rebase(target: Document, anchors: Anchor[]): Anchor[] {\n\tlet hashes = digests(target);\n\tlet keys: string[] = [];\n\ttarget.editor.getEditorState().read(() => {\n\t\tkeys = addressable().map(node => node.getKey());\n\t});\n\n\tlet byDigest = new Map();\n\thashes.forEach((hash, index) => {\n\t\tlet key = keys[index];\n\t\tif (!key) return;\n\t\tbyDigest.set(hash, [...byDigest.get(hash) ?? [], key]);\n\t});\n\n\treturn anchors.map(anchor => {\n\t\tif (anchor.orphaned) return { ...anchor, epoch: target.epoch };\n\n\t\tlet key = resolveAnchor(target, anchor);\n\t\tif (key) {\n\t\t\tlet index = keys.indexOf(key);\n\t\t\tlet hash = hashes[index];\n\t\t\tif (hash) return anchorForKey(target, key, hash);\n\t\t}\n\n\t\tlet matches = byDigest.get(anchor.digest) ?? [];\n\t\treturn matches.length === 1\n\t\t\t? anchorForKey(target, matches[0], anchor.digest)\n\t\t\t: { ...anchor, epoch: target.epoch, orphaned: true as const };\n\t});\n}\n\n// -- passages --------------------------------------------------------------\n\n/**\n * A phrase of the plan, to the character.\n *\n * An anchor names a whole block, which is the right grain for a decision and\n * the wrong one for a remark about a single sentence. A passage is therefore\n * the block run plus a range inside it, and the range is expressed twice for\n * the same reason the block is: relative positions, so it stretches as somebody\n * types inside the phrase, and the quoted text, which finds it again when they\n * cannot be resolved.\n *\n * The quote is a bounded locator, not the whole phrase, so `length` carries the\n * real extent — find the prefix, then run on. That is what lets a passage be\n * longer than the bound instead of being refused for it.\n */\n\n/** Blocks are one string; this joins them. Only consistency matters. */\nconst RUN = \"\\n\";\n\n/** One text node's place in a block run's plain text. */\ntype Span = { key: string; start: number; length: number };\n\n/**\n * A block run as one string, with where each of its text nodes sits in it.\n *\n * Call inside a read. Blocks with no text — a decorator, a rule — contribute\n * nothing but still take their separator, so a run can span across one.\n */\nfunction runOf(nodes: LexicalNode[]): { text: string; spans: Span[] } {\n\tlet spans: Span[] = [];\n\tlet text = \"\";\n\n\tfor (let [i, node] of nodes.entries()) {\n\t\tif (i > 0) text += RUN;\n\t\tif (!$isElementNode(node)) continue;\n\t\tfor (let leaf of node.getAllTextNodes()) {\n\t\t\tlet value = leaf.getTextContent();\n\t\t\tspans.push({ key: leaf.getKey(), start: text.length, length: value.length });\n\t\t\ttext += value;\n\t\t}\n\t}\n\n\treturn { text, spans };\n}\n\n/** Where an index in the run's text sits, as a Lexical text point. */\nfunction place(spans: Span[], index: number): { key: string; offset: number } | undefined {\n\tfor (let span of spans) {\n\t\t// An index inside a separator lands at the start of the block after it.\n\t\tif (index <= span.start + span.length) {\n\t\t\treturn { key: span.key, offset: Math.max(0, index - span.start) };\n\t\t}\n\t}\n\tlet last = spans.at(-1);\n\treturn last ? { key: last.key, offset: last.length } : undefined;\n}\n\n/** The run index of a Lexical text point, if the point is in this run. */\nfunction indexOfPoint(spans: Span[], key: string | null, offset: number): number | undefined {\n\tif (!key) return undefined;\n\tfor (let span of spans) {\n\t\tif (span.key === key) return span.start + Math.min(offset, span.length);\n\t}\n\treturn undefined;\n}\n\n/**\n * Where the quote is now, or nothing if that cannot be said.\n *\n * The recorded offset breaks ties, because a phrase can legitimately appear\n * twice in one paragraph. Two occurrences equally near it recover neither —\n * the rule `rebase` applies to two identical blocks, for the same reason.\n */\nfunction seek(text: string, quote: string, offset: number): number | undefined {\n\tif (!quote) return undefined;\n\n\tlet found: number[] = [];\n\tfor (let at = text.indexOf(quote); at !== -1; at = text.indexOf(quote, at + 1)) found.push(at);\n\tif (found.length === 0) return undefined;\n\tif (found.length === 1) return found[0];\n\n\tlet best = found.reduce((a, b) => Math.abs(a - offset) <= Math.abs(b - offset) ? a : b);\n\tlet near = Math.abs(best - offset);\n\treturn found.filter(at => Math.abs(at - offset) === near).length === 1 ? best : undefined;\n}\n\n/** The parts of a collab text node this needs, named structurally. */\ntype CollabText = { _parent?: { getSharedType(): unknown }; getOffset(): number };\n\n/**\n * A Yjs position for a point inside a block's text.\n *\n * `@lexical/yjs` computes this for every remote cursor and does not export it,\n * so the arithmetic is repeated here: a text node's characters live in its\n * parent's `XmlText`, one slot past the node's own entry, which is the `+ 1`.\n * The inverse *is* exported, so this is the only half that is ours to keep\n * right — and it is pinned by `passages.test.ts` rather than by inspection.\n */\nfunction positionAt(target: Document, key: string, offset: number): string {\n\tlet collab = target.binding.collabNodeMap.get(key) as CollabText | undefined;\n\tlet type = collab?._parent?.getSharedType();\n\tif (!collab || !(type instanceof Y.XmlText)) {\n\t\tthrow new Error(\"passage names text with no collaborative identity\");\n\t}\n\n\tlet base = collab.getOffset();\n\tif (base === -1) throw new Error(\"passage names text that is no longer in the document\");\n\n\treturn Buffer.from(\n\t\tY.encodeRelativePosition(Y.createRelativePositionFromTypeIndex(type, base + 1 + offset)),\n\t).toString(\"base64\");\n}\n\n/** The nodes a passage's blocks name, if every one of them still resolves. */\nfunction runNodes(target: Document, blocks: Anchor[]): LexicalNode[] | undefined {\n\tlet keys = blocks.map(block => resolveAnchor(target, block));\n\tif (keys.some(key => !key)) return undefined;\n\n\tlet nodes: LexicalNode[] = [];\n\ttarget.editor.getEditorState().read(() => {\n\t\tfor (let key of keys) {\n\t\t\tlet node = $getNodeByKey(key!);\n\t\t\tif (node) nodes.push(node);\n\t\t}\n\t});\n\n\treturn nodes.length === blocks.length ? nodes : undefined;\n}\n\n/** Build a passage over a resolved run, from a range in its text. */\nfunction cut(\n\ttarget: Document,\n\tblocks: Anchor[],\n\trun: { text: string; spans: Span[] },\n\tfrom: number,\n\tto: number,\n): Passage {\n\tlet start = place(run.spans, from);\n\tlet end = place(run.spans, to);\n\tif (!start || !end) throw new Error(\"passage names a run with no text in it\");\n\n\treturn {\n\t\tblocks,\n\t\tstart: positionAt(target, start.key, start.offset),\n\t\tend: positionAt(target, end.key, end.offset),\n\t\tquote: run.text.slice(from, to).slice(0, limits.MAX_QUOTE),\n\t\toffset: from,\n\t\tlength: to - from,\n\t};\n}\n\n/**\n * Mark a phrase, from what the client could prove it read.\n *\n * Block digests are a precondition, as they are for anchoring a decision: if\n * one does not match, the plan moved between reading and marking, and placing\n * the passage against prose that has since changed would be worse than saying\n * so. The offset is a hint rather than a coordinate — the quote is searched\n * for near it — so the client's idea of where text begins never has to agree\n * with this one exactly.\n */\nexport function passageAt(\n\ttarget: Document,\n\tblocks: Array<{ index: number; digest: string }>,\n\tquote: string,\n\toffset: number,\n\tlength: number,\n): Passage {\n\tif (blocks.length === 0) throw new Error(\"a passage must name at least one block\");\n\n\tlet current = digests(target);\n\tlet anchors: Anchor[] = [];\n\tfor (let block of blocks) {\n\t\tlet hash = current[block.index];\n\t\tif (!hash) throw new Error(`no block at index ${block.index}`);\n\t\tif (hash !== block.digest) {\n\t\t\tthrow new Error(`block ${block.index} has changed; read the plan again`);\n\t\t}\n\t\tanchors.push(anchorAt(target, block.index, hash));\n\t}\n\n\tlet nodes = runNodes(target, anchors);\n\tif (!nodes) throw new Error(\"a block in the passage has no collaborative identity\");\n\n\tlet run = { text: \"\", spans: [] as Span[] };\n\ttarget.editor.getEditorState().read(() => {\n\t\trun = runOf(nodes);\n\t});\n\n\tlet from = seek(run.text, quote, offset);\n\tif (from === undefined) throw new Error(\"the quoted text is not in those blocks\");\n\n\treturn cut(target, anchors, run, from, Math.min(from + length, run.text.length));\n}\n\n/** The Lexical points a passage names, if it still names any. */\nexport function locate(\n\ttarget: Document,\n\tpassage: Passage,\n): { anchorKey: string; anchorOffset: number; focusKey: string; focusOffset: number } | undefined {\n\tif (passage.drifted) return undefined;\n\tif (passage.blocks[0]?.epoch !== target.epoch) return undefined;\n\n\ttry {\n\t\tlet state = {\n\t\t\tanchorPos: Y.decodeRelativePosition(Buffer.from(passage.start, \"base64\")),\n\t\t\tfocusPos: Y.decodeRelativePosition(Buffer.from(passage.end, \"base64\")),\n\t\t\tcolor: \"\",\n\t\t\tfocusing: false,\n\t\t\tname: \"\",\n\t\t\tawarenessData: {},\n\t\t};\n\n\t\tlet found: ReturnType | undefined;\n\t\ttarget.editor.getEditorState().read(() => {\n\t\t\tfound = $getAnchorAndFocusForUserState(target.binding, state);\n\t\t});\n\t\tif (!found) return undefined;\n\n\t\tlet { anchorKey, anchorOffset, focusKey, focusOffset } = found;\n\t\tif (!anchorKey || !focusKey) return undefined;\n\t\treturn { anchorKey, anchorOffset: anchorOffset ?? 0, focusKey, focusOffset: focusOffset ?? 0 };\n\t} catch {\n\t\t// A position from a history this document no longer holds. The quote is\n\t\t// the fallback, and `rebasePassage` is about to try it.\n\t\treturn undefined;\n\t}\n}\n\n/** The plain text of a run of blocks, addressed the way the agent addresses them. */\nexport function blockText(target: Document, indices: number[]): string {\n\tlet text = \"\";\n\ttarget.editor.getEditorState().read(() => {\n\t\tlet all = addressable();\n\t\tlet nodes = indices.map(index => all[index]).filter(node => !!node);\n\t\tif (nodes.length === indices.length) text = runOf(nodes).text;\n\t});\n\treturn text;\n}\n\n/** The current text of the blocks a passage covers, for saying what it now reads. */\nexport function passageText(target: Document, passage: Passage): string | undefined {\n\tlet nodes = runNodes(target, passage.blocks);\n\tif (!nodes) return undefined;\n\n\tlet text = \"\";\n\ttarget.editor.getEditorState().read(() => {\n\t\ttext = runOf(nodes).text;\n\t});\n\treturn text;\n}\n\n/**\n * Bring a passage forward onto the document as it is now.\n *\n * Same ladder as an anchor, one level finer. The blocks are rebased first,\n * because a range means nothing without them. Positions that still resolve are\n * kept and the quote refreshed from what they now cover, so the fallback keeps\n * describing the prose rather than a memory of it. Positions that do not are\n * re-derived by finding the quote. Anything left over is marked drifted and\n * kept: a comment pointing at the wrong sentence is worse than one admitting\n * its sentence is gone, and the thread is still worth reading either way.\n */\nexport function rebasePassage(target: Document, passage: Passage): Passage {\n\tlet resolvable = !passage.drifted && passage.blocks[0]?.epoch === target.epoch;\n\tlet blocks = rebase(target, passage.blocks);\n\tlet nodes = blocks.some(block => block.orphaned) ? undefined : runNodes(target, blocks);\n\tif (!nodes) return { ...passage, blocks, drifted: true };\n\n\tlet run = { text: \"\", spans: [] as Span[] };\n\ttarget.editor.getEditorState().read(() => {\n\t\trun = runOf(nodes);\n\t});\n\n\tif (resolvable) {\n\t\tlet points = locate(target, { ...passage, blocks: passage.blocks });\n\t\tlet from = points && indexOfPoint(run.spans, points.anchorKey, points.anchorOffset);\n\t\tlet to = points && indexOfPoint(run.spans, points.focusKey, points.focusOffset);\n\n\t\tif (from !== undefined && to !== undefined) {\n\t\t\ttry {\n\t\t\t\treturn cut(target, blocks, run, Math.min(from, to), Math.max(from, to));\n\t\t\t} catch {\n\t\t\t\t// The points resolved but no longer sit in text we can address.\n\t\t\t\t// Fall through to the quote.\n\t\t\t}\n\t\t}\n\t}\n\n\tlet found = seek(run.text, passage.quote, passage.offset);\n\tif (found === undefined) return { ...passage, blocks, drifted: true };\n\n\ttry {\n\t\treturn cut(target, blocks, run, found, Math.min(found + passage.length, run.text.length));\n\t} catch {\n\t\treturn { ...passage, blocks, drifted: true };\n\t}\n}\n","editable",false,"branch","documentNavigation","repo","githubnext/chopin","repoId","7d1a8ac3-35b0-4dea-85d4-06a980f3bada","ownerId","org:89615882","site","nexthub","private","admin","settings","maintainer","triage","starred","stars",0,"watchers","watching","pinned","notify","views",[183,184,185,186,187,188,189,190,191,192,193,194,195],"navigation",{"_54":55,"_139":140,"_141":142,"_143":144,"_145":146,"_147":148,"_149":150},"sources",[],"viewer","meta",{"_131":132,"_133":134,"_135":136,"_42":31,"_137":126,"_138":31,"_48":49,"_50":49},"branches",[73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130],"tags",[69,70,71,72],"cloneUrl","https://git.nexthub.sh/githubnext/chopin.git","color-controls-slice-1","color-controls-slice-2","color-controls-slice-3","color-controls-slice-4","Krzysztof-Cieslak-patch-1","Krzysztof-Cieslak-patch-2","Maggie/app-preview-toolkit","Maggie/ci-playwright-install-timeout","Maggie/collaborative-visual-decision","Maggie/design-audit","Maggie/generic-visual-decision-runtime","Maggie/impeccable-chopin-metadata","Maggie/jev-chat-product","Maggie/jev-composed-assessment","Maggie/native-document-layouts","Maggie/openui-composition-product","Maggie/openui-composition-trial","Maggie/planner-visual-authoring","Maggie/planner-visual-requests","Maggie/visual-selection-eval","artifacts/pr-419-live-preview-20261009","automation/pr-maintenance-state","automation/use-effect/callout-disabled-picker-8cf9e49ba5c09471","automation/use-effect/collaboration-options-ref-4e3a5a08a879a5ae","automation/use-effect/room-workspace-effective-access-a57d40866c71bed0","chore/bun-1.4.2","color-controls","color-controls-plan","comments","design-pr-assets","design/archived-decisions-badge","design/channel-route-remount","design/chat-decision-entry","design/conversation-analysis-markers","design/decision-evidence","design/settled-line-icon","dev/integration","diagram-step-controls","feat/liveapp-frontend-pilot","feat/local-experiments","feat/local-launcher-tracer","fix/autolink-mdx-crash","github-pills/2-pills","github-pills/3-hover-card","maggie/app-preview-toolkit","maggie/ci-playwright-install-timeout","maggie/collaborative-visual-decision","maggie/design-audit","maggie/generic-visual-decision-runtime","maggie/impeccable-chopin-metadata","maggie/jev-composed-assessment","maggie/native-document-layouts","maggie/openui-composition-product","maggie/openui-composition-trial","maggie/planner-visual-authoring","maggie/planner-visual-requests","maggie/visual-selection-eval","main","plain-text-fence-chrome","tokens/09-copy","wireframes/2-renderer","wireframes/3-planner","description","Let's compose rich plans together","owner","githubnext","section","","head","empty","pins",[165,166,167],"documents",{"_160":161,"_162":163},"code",{"_156":157,"_158":159},"automations",{"_153":154,"_155":-5},"delivery",{"_151":49,"_152":-5},"tag","04zvKQ8QOrDUF8TO1Ovz0Zy8_TT","releases","applications","workflows",3,"deployments","commits",1000,"changes",13,"counts",{"_164":163},"total",11,"issue",{"_168":158,"_170":181,"_15":158,"_172":182,"_52":174,"_175":31,"_176":174,"_177":159},{"_168":178,"_170":179,"_15":178,"_172":180,"_52":174,"_175":31,"_176":174,"_177":49},{"_168":169,"_170":171,"_15":169,"_172":173,"_52":174,"_175":31,"_176":174,"_177":163},"id","issues","name","Issues","filters",{},true,"saved","pinnable","count","tasks","Tasks",{},"Changes",{},{"_168":158,"_170":181,"_15":158,"_172":226,"_52":174,"_175":31,"_176":174},{"_168":178,"_170":179,"_15":178,"_172":225,"_52":174,"_175":31,"_176":174},{"_168":169,"_170":171,"_15":169,"_172":224,"_52":174,"_175":31,"_176":174},{"_168":221,"_170":222,"_15":221,"_172":223,"_52":31,"_175":31,"_176":174},{"_168":218,"_170":219,"_15":218,"_172":220,"_52":31,"_175":31,"_176":174},{"_168":153,"_170":216,"_15":145,"_172":217,"_52":31,"_175":31,"_176":174},{"_168":155,"_170":213,"_15":214,"_172":215,"_52":31,"_175":31,"_176":174},{"_168":151,"_170":211,"_15":151,"_172":212,"_52":31,"_175":31,"_176":174},{"_168":207,"_170":208,"_15":209,"_172":210,"_52":31,"_175":31,"_176":174},{"_168":141,"_170":205,"_15":141,"_172":206,"_52":31,"_175":31,"_176":31},{"_168":202,"_170":203,"_15":202,"_172":204,"_52":31,"_175":31,"_176":31},{"_168":199,"_170":200,"_15":199,"_172":201,"_52":31,"_175":31,"_176":31},{"_168":196,"_170":197,"_15":196,"_172":198,"_52":31,"_175":31,"_176":31},"decisions","Decisions",{},"changelog","Changelog",{},"roadmap","Roadmap",{},"Documents",{},"activity","Activity","insights",{},"Releases",{},"Deployments","automations/deployments",{},"Workflows",{},"discussions","Discussions",{},"goals","Goals",{},{},{},{},"groups","user","agents",[],"now",1794576132635,"sidebar","expanded"]