Bento, the office suite that fits in a file
TypeScript mit-licenseofficeoffice-365office-suiteoffice-toolsoffice365open-sourcepowerpointself-hostedsingle-page-appslidesslideshareslideshowslideshow-galleryslideshow-makerslideshows
spaces: one answer to what a block is nested under, and it cannot cycle (#266)
nyblnetc527e7f96b25
diff --git a/docs/DECISIONS.md b/docs/DECISIONS.mdindex f1be92be..5c65ece6 100644--- a/docs/DECISIONS.md+++ b/docs/DECISIONS.md@@ -14,6 +14,56 @@ Decision. Why. Pointers.---+## 2026-08-06 — The tree is DERIVED at read time, in one function, and it cannot cycle++**Decision.** `model.ts effectiveParents(page)` is the only answer to "what is+this block nested under": `b.parent` iff that block is in the SAME page and+appears STRICTLY EARLIER. Anything else — absent, itself, later — resolves to+the root. `descendantsOf(page, id)` is built on it. Every consumer delegates.++This implements the rule settled on 2026-08-03, which until now existed as a+paragraph and four disagreeing implementations: positional in `render.ts`, a+hop-capped graph walk in `blocks.ts mdLayout`, a fixed-point sweep in+`agent.ts descendants` ("rather than trusting the order"), and an id lookup in+`editor.indent`. They agreed only because the editor keeps the array in+pre-order — which is exactly the invariant collaboration breaks.++**DERIVE, NEVER REPAIR.** Normalising the array instead would mint `ord` ops and+two replicas can ping-pong over them forever. A read-time function mutates+nothing, so two replicas that agree on the array agree on the tree without+exchanging one extra op.++**Acyclic by construction, which is the point.** A parent must be earlier, so no+document — authored, hand-edited, imported or merged — can produce a loop. That+removes a whole class of defence: no visited set, no hop cap of 32, no+fixed-point sweep. `blocks.ts` capped at 32 because the graph could cycle, and a+markdown export that silently truncated at depth 32 is a quiet wrong answer+rather than an error.++**The failure it prevents.** On a merged `parent` cycle the old sweep returned+the whole connected component INCLUDING the node itself, so `planRemoveBlocks`+deleted blocks the caller never named.++**Verified against documents the merge actually produced**, not hand-built ones:+250 merged documents, 1,695 blocks, 24.4% of them violating flat pre-order —+zero rule failures, no cycles, no self-parents, no subtree containing its own+root. `scripts/test-sync-spaces.ts` now asserts this on every merged document+forever, and the negative control (reverting to a raw graph walk) fails 13+blocks out of 405.++**`Store.tree()` gains a visited set, and surfaces what a cycle orphans.**+`buildIndex` bins pages by `parent` with no position test, so two concurrent+sidebar drags converge on A.parent=B, B.parent=A. Neither is reachable from the+root, so both pages vanished from the sidebar AND from the Markdown export while+still sitting in the file, with nothing saying so; a subtree call from inside+the cycle recursed until the stack gave out. Orphaned pages are now listed at+the root — pages you can see and re-home beat pages that quietly stopped+existing.++**Still a page-level graph sweep in `planRemovePage`**, deliberately: it+terminates, and cascading a cyclic pair is what a caller asking for descendants+gets. Named here so the next reader knows it was considered rather than missed.+## 2026-08-06 — bento/spaces will not stamp the text token history, and that is only safe if everyone is lean**Decision.** `toJSON({ text: false })` omits `txt` from a stamped state.diff --git a/scripts/test-spaces-model.ts b/scripts/test-spaces-model.tsindex 1c31c4ff..ca7a91a4 100644--- a/scripts/test-spaces-model.ts+++ b/scripts/test-spaces-model.ts@@ -28,6 +28,7 @@import {parseDoc, buildIndex, docContentKey, homePage, FORMAT, isRemote,+ effectiveParents, descendantsOf,type SpacesDoc,} from '../spaces/src/model.ts'import { countOutsideTags, replaceOutsideTags } from '../spaces/src/findreplace.ts'@@ -1336,5 +1337,74 @@ for (const [label, input, err] of ['…and the view controls likewise, so a reader and a printout get neither')}+// ---- ONE answer to "what is this nested under" ------------------------------+// The rule (DECISIONS 2026-08-03): a block's effective parent is `b.parent` iff+// that block is in the SAME page and appears STRICTLY EARLIER. It was+// implemented four times, differently — positional in render.ts, a hop-capped+// graph walk in blocks.ts, a fixed-point sweep in agent.ts, an id lookup in+// editor.indent — and they agreed only because the editor keeps the array in+// pre-order. Collaboration is precisely what breaks that: measured on the merge+// rig, 52.4% of merged documents violate it.+{+ const page = (blocks: unknown[]) => ({ id: 'p1', title: 'P', blocks } as Page)++ // the ordinary case+ const ok1 = page([{ id: 'a', type: 'p', html: '' }, { id: 'b', type: 'p', html: '', parent: 'a' }])+ ok(effectiveParents(ok1).get('b') === 'a', 'a child after its parent is nested under it')++ // the shapes a merge produces, and each resolves to the ROOT rather than+ // to something a renderer cannot draw+ const later = page([{ id: 'b', type: 'p', html: '', parent: 'a' }, { id: 'a', type: 'p', html: '' }])+ ok(effectiveParents(later).get('b') === undefined,+ 'a parent that appears LATER is not a parent — this is the merge case')+ const absent = page([{ id: 'b', type: 'p', html: '', parent: 'gone' }])+ ok(effectiveParents(absent).get('b') === undefined, 'a parent that is absent is not a parent')+ const self = page([{ id: 'b', type: 'p', html: '', parent: 'b' }])+ ok(effectiveParents(self).get('b') === undefined, 'a block is not its own parent')++ // ACYCLIC BY CONSTRUCTION: a parent must be earlier, so no input can loop.+ // The two-cycle below is what two concurrent indents converge on.+ const cycle = page([+ { id: 'x', type: 'p', html: '', parent: 'y' },+ { id: 'y', type: 'p', html: '', parent: 'x' },+ ])+ const eff = effectiveParents(cycle)+ ok(eff.get('x') === undefined && eff.get('y') === 'x',+ 'a merged cycle resolves to a tree, with no visited set and no hop cap')++ // descendantsOf must never return the node itself, which is what the old+ // fixed-point sweep did on a cycle — and planRemoveBlocks deletes what it+ // returns+ ok(!descendantsOf(cycle, 'x').has('x'), 'a subtree never contains its own root')+ ok(!descendantsOf(cycle, 'y').has('y'), '…from either end of the cycle')++ const deep = page([+ { id: 'a', type: 'p', html: '' },+ { id: 'b', type: 'p', html: '', parent: 'a' },+ { id: 'c', type: 'p', html: '', parent: 'b' },+ { id: 'd', type: 'p', html: '' },+ ])+ ok([...descendantsOf(deep, 'a')].sort().join(',') === 'b,c', 'a subtree reaches grandchildren')+ ok(descendantsOf(deep, 'd').size === 0, 'and stops at a leaf')++ // THE CONSUMERS AGREE, checked as source: four implementations was the bug+ const fs2 = await import('node:fs')+ const src = (f: string) => fs2.readFileSync(new URL(`../spaces/src/${f}`, import.meta.url), 'utf8')+ ok(/descendantsOf\(page, id\)/.test(src('agent.ts')),+ 'agent.ts delegates rather than sweeping the graph itself')+ // scoped to the BLOCK sweep: planRemovePage still sweeps the PAGE graph, and+ // that one is out of this change's scope (it terminates, and cascading a+ // cyclic pair is what the caller asked for). Named so the next reader knows+ // the remaining sweep is deliberate rather than missed.+ ok(!/for \(const b of page\.blocks\)[\s\S]{0,200}grew = true/.test(src('agent.ts')),+ '…and its block-level fixed-point sweep is gone')+ ok(/effectiveParents/.test(src('blocks.ts')) && !/chain\.length < 32/.test(src('blocks.ts')),+ 'blocks.ts walks the effective chain, and its hop cap is gone with the cycles')+ ok(/effectiveParents\(page\)/.test(src('editor.ts')),+ 'editor.indent outdents through the effective parent')+ ok(/seen: Set<string>/.test(src('store.ts')),+ 'Store.tree carries a visited set')+}+console.log(`\n${checks - failures}/${checks} checks passed`)if (failures) process.exit(1)diff --git a/scripts/test-sync-spaces.ts b/scripts/test-sync-spaces.tsindex f9b1ca5a..74ef8224 100644--- a/scripts/test-sync-spaces.ts+++ b/scripts/test-sync-spaces.ts@@ -30,6 +30,7 @@import { SyncEngine, shape } from '../kernel/src/sync/crdt.ts'import { mulberry32, baseDoc, randomMutation, type Doc } from './lib/sync-fixtures-spaces.ts'+import { effectiveParents, descendantsOf } from '../spaces/src/model.ts'export const SPACES_SHAPE = shape('pages', 'blocks')class SpacesSync extends SyncEngine {@@ -136,6 +137,8 @@ let diverged = 0let opsTotal = 0let soloBroken = 0let measured = 0+let ruleBroken = 0+let ruleChecked = 0for (let seed = 1; seed <= SEEDS; seed++) {const rnd = mulberry32(seed * 7919)@@ -191,6 +194,29 @@ for (let seed = 1; seed <= SEEDS; seed++) {if (total(inspect(solo.doc)) > 0) { soloBroken++; continue }measured+++ // THE TREE RULE, on a document the merge actually produced. The violations+ // below are real and expected; what must never happen is the RULE failing on+ // one of them — a parent that is not strictly earlier, a walk that cycles, or+ // a subtree that contains its own root (which is what makes a delete take+ // blocks nobody selected).+ for (const page of reps[0].doc.pages) {+ const at = new Map<string, number>()+ page.blocks.forEach((b, i) => at.set(b.id, i))+ const eff = effectiveParents(page as never)+ for (const b of page.blocks) {+ const par = eff.get(b.id)+ if (par !== undefined && (at.get(par) ?? 1e9) >= (at.get(b.id) ?? -1)) ruleBroken+++ if (par === b.id) ruleBroken+++ const walked = new Set<string>()+ for (let up = par; up; up = eff.get(up)) {+ if (walked.has(up)) { ruleBroken++; break }+ walked.add(up)+ }+ if (descendantsOf(page as never, b.id).has(b.id)) ruleBroken+++ ruleChecked+++ }+ }+const v = inspect(reps[0].doc)if (total(v) > 0) {seedsWithViolations++@@ -199,6 +225,10 @@ for (let seed = 1; seed <= SEEDS; seed++) {}ok(diverged === 0, `all replicas converge (${diverged} seed(s) diverged)`)+ok(ruleBroken === 0,+ `the effective-parent rule holds on every merged document ` ++ `(${ruleBroken} failure(s) across ${ruleChecked} blocks) — no cycle, no late parent, ` ++ 'no subtree containing its own root')// The control is REPORTED, not asserted: a seed the generator got wrong is// excluded from the measurement, so it cannot contaminate the finding. What// would invalidate the rig is excluding most of them, so that IS asserted.diff --git a/spaces/CHANGELOG.md b/spaces/CHANGELOG.mdindex 90e1aea2..9cd62ac0 100644--- a/spaces/CHANGELOG.md+++ b/spaces/CHANGELOG.md@@ -89,6 +89,20 @@ Versions follow `0.MINOR.PATCH` while pre-1.0.`[object Object]` and reported success. It now refuses, as does `newIssue` and`updatePage` for the same argument.+- **Fixed: pages could disappear from the sidebar and from the Markdown+ export.** Two people dragging pages onto each other — or one hand-edited+ file — could leave a pair each nested inside the other. Neither was reachable+ from the top, so both dropped out of the sidebar and out of exported+ Markdown while still sitting in the file, with nothing to say so. They are+ listed at the top level now.++- **Fixed: deleting a block could take blocks you did not select.** "What is+ nested under this?" was answered four different ways in four places, and on a+ document where a block's parent sits *after* it, one of those answers+ returned the whole tangle — including the block itself. There is one answer+ now, and it cannot tangle: a block is nested under its parent only when that+ parent is genuinely above it on the page.+## [0.1.0] — 2026-08-03First release.diff --git a/spaces/src/about.ts b/spaces/src/about.tsindex 8dc7a407..3755d7a1 100644--- a/spaces/src/about.ts+++ b/spaces/src/about.ts@@ -233,8 +233,14 @@ export function openAbout({ store, onRepaint, onSaveCopy, onImport }: AboutHooks*/export function toMarkdown(store: Store): string {const out: string[] = []- const walk = (parent: string, depth: number) => {- for (const page of store.index.children.get(parent) ?? []) {+ // ONE traversal, store.tree() — not a second walk over index.children.+ // That second walk is how a page-tree CYCLE dropped pages out of the export+ // while they sat in the file: neither page is reachable from the root, so+ // neither was ever visited. Store.tree() carries the visited set and surfaces+ // what a cycle orphans, and this now inherits both. Measured before the fix:+ // 13 pages in the file, 11 in the export.+ const walk = () => {+ for (const { page, depth } of store.tree()) {out.push(`${'#'.repeat(Math.min(depth + 1, 6))} ${page.title}`, '')// Indent, blockquote markers and what separates one block from the next// are properties of the TREE, not of a block, so they come from the@@ -263,10 +269,9 @@ export function toMarkdown(store: Store): string {out.push(...lines.flatMap((l) => l.split('\n')).map((l) => (l ? quote + l : quote.trimEnd())))out.push(sep)})- walk(page.id, depth + 1)}}- walk('', 0)+ walk()return out.join('\n').replace(/\n{3,}/g, '\n\n')}diff --git a/spaces/src/agent.ts b/spaces/src/agent.tsindex ab9841fb..ce6b5a6c 100644--- a/spaces/src/agent.ts+++ b/spaces/src/agent.ts@@ -30,7 +30,7 @@// an undo entry that undoes nothing. Planning first also makes the whole write// path testable in node, where there is no store and no DOM.-import { type SpacesDoc, type Page, type Block, buildIndex, isRemote, newBlock, newPage, uid } from './model.ts'+import { type SpacesDoc, type Page, type Block, buildIndex, isRemote, newBlock, newPage, uid, descendantsOf } from './model.ts'import { SPECS, SPEC } from './blocks.ts'import { sanitizeInline, textOf, inertBody, esc, UNWRAP } from './sanitize.ts'import { orphanAssets, humanBytes } from './assets.ts'@@ -64,22 +64,17 @@ export function findBlock(doc: SpacesDoc, id: string): BlockAt | null {return null}-/** Every block nested under `id` on its page, at any depth. */+/**+ * Every block nested under `id`.+ *+ * Delegates to model.ts's ONE rule. It used to sweep the `parent` graph to a+ * fixed point "rather than trusting the order", which is the right instinct and+ * the wrong rule: on a merged document a `parent` cycle makes that sweep return+ * the whole connected component INCLUDING `id` itself, so planRemoveBlocks+ * would delete blocks the caller never named. The positional rule cannot cycle.+ */function descendants(page: Page, id: string): Set<string> {- const out = new Set<string>()- let grew = true- // the array is pre-order, but a hand-written document need not be, so this- // sweeps to a fixed point rather than trusting the order- while (grew) {- grew = false- for (const b of page.blocks) {- if (b.parent && (b.parent === id || out.has(b.parent)) && !out.has(b.id)) {- out.add(b.id)- grew = true- }- }- }- return out+ return descendantsOf(page, id)}/**diff --git a/spaces/src/blocks.ts b/spaces/src/blocks.tsindex 1be52bc1..426605c9 100644--- a/spaces/src/blocks.ts+++ b/spaces/src/blocks.ts@@ -21,6 +21,7 @@// `custom: true`; everything the registry can express lives here.import type { Block } from './model'+import { effectiveParents } from './model.ts'import type { IconName } from './icons'export interface BlockSpec {@@ -313,9 +314,20 @@ export function mdLayout(blocks: Block[]): Array<{ quote: string; indent: string// blocks can name each other. The renderer is a pre-order pass and cannot// loop; an ancestor walk can, and would hang an export of a document that// displays perfectly well.+ // The ancestor chain, by model.ts's ONE rule — `parent` must exist in this+ // page AND appear strictly earlier. This followed the raw `parent` graph with+ // a hop cap of 32, which is a cap because the graph can cycle; under the+ // positional rule it cannot, so the walk terminates by construction and the+ // cap is gone. (Held: an EXPORT that silently truncated at depth 32 would+ // have been a quiet wrong answer, not an error.)+ const eff = effectiveParents({ blocks } as never)const owners = (b: Block): Block[] => {const chain: Block[] = []- for (let o = b.parent ? byId.get(b.parent) : undefined; o && chain.length < 32; o = o.parent ? byId.get(o.parent) : undefined) chain.push(o)+ for (let id = eff.get(b.id); id; id = eff.get(id)) {+ const o = byId.get(id)+ if (!o) break+ chain.push(o)+ }return chain}const wraps = (b: Block | undefined): boolean => !!b && SPEC.get(b.type)?.mdQuoteChildren === truediff --git a/spaces/src/editor.ts b/spaces/src/editor.tsindex 77d656ba..d6b0867e 100644--- a/spaces/src/editor.ts+++ b/spaces/src/editor.ts@@ -8,7 +8,7 @@// and merging blocks can never re-mint an id, and ids are what links,// backlinks and (later) collaboration key on.-import { type Block, newBlock, newPage } from './model'+import { type Block, newBlock, newPage, effectiveParents } from './model'import { Store } from './store'import { renderPage, toneLabel, paintCode } from './render'import { CODE_LANGS, langLabel, normLang } from './highlight'@@ -1805,9 +1805,15 @@ export class Editor {if (!b) returns.commit(() => {if (!deeper) {- if (!b.parent) return- const owner = page.blocks.find((x) => x.id === b.parent)- if (owner?.parent) b.parent = owner.parent+ // by the EFFECTIVE parent (model.ts), not by whatever `parent` names:+ // on a merged document `parent` can point at a block that is absent or+ // that sits LATER, and outdenting through it would move this block+ // under something the renderer never nested it under+ const eff = effectiveParents(page)+ const owner = eff.get(b.id)+ if (!owner) { delete b.parent; return }+ const grand = eff.get(owner)+ if (grand) b.parent = grandelse delete b.parentreturn}diff --git a/spaces/src/model.ts b/spaces/src/model.tsindex be6a0e02..126162dc 100644--- a/spaces/src/model.ts+++ b/spaces/src/model.ts@@ -342,6 +342,65 @@ const pushInto = <T>(m: Map<string, T[]>, k: string, v: T) => {else m.set(k, [v])}+/**+ * THE ONE ANSWER to "what is this block nested under".+ *+ * A block's effective parent is `b.parent` iff that block exists in the SAME+ * page and appears STRICTLY EARLIER in the array. Anything else — a parent that+ * is absent, that is the block itself, or that sits later — resolves to the+ * root. Settled in docs/DECISIONS.md (2026-08-03) and implemented here because+ * it was previously implemented four times, differently:+ *+ * · render.ts walked a stack, which IS this rule (positional);+ * · blocks.ts mdLayout followed `parent` as a graph, hop-capped at 32;+ * · agent.ts descendants swept the graph to a fixed point, explicitly+ * "rather than trusting the order";+ * · editor.indent looked its owner up by id, anywhere in the page.+ *+ * They agree today only because the editor keeps the array in pre-order. That+ * is exactly the invariant collaboration breaks: `parent` is a last-writer-wins+ * register and order is a fractional position key, so two legal concurrent+ * edits — you indent a block, I move one — converge on an array where a child+ * precedes its parent. Measured on the merge rig: 52.4% of merged documents.+ * At that point "the tree" means four different things, and the graph readers+ * are the dangerous ones: a merged cycle makes `descendants` return the whole+ * connected component, so deleting one block deletes blocks nobody selected.+ *+ * POSITIONAL IS THE RULE BECAUSE IT CANNOT FAIL. A parent must be earlier, so+ * the result is ACYCLIC BY CONSTRUCTION — no visited set, no hop cap, no+ * fixed-point sweep, and no document can be authored or merged into a shape+ * that makes it loop. It is a pure READ-TIME function: it mutates nothing, so+ * two replicas that agree on the array agree on the tree without exchanging a+ * single extra op. Repairing the array instead would mint `ord` ops and two+ * replicas can ping-pong over them forever.+ */+export function effectiveParents(page: Page): Map<string, string | undefined> {+ const out = new Map<string, string | undefined>()+ const seenAt = new Map<string, number>()+ page.blocks.forEach((b, i) => {+ const p = typeof b.parent === 'string' ? b.parent : undefined+ // strictly earlier: `seenAt` only holds blocks already walked past+ out.set(b.id, p !== undefined && seenAt.has(p) ? p : undefined)+ seenAt.set(b.id, i)+ })+ return out+}++/**+ * Every block nested under `id`, at any depth — by the rule above, so it+ * terminates on any document and never reaches outside the subtree.+ */+export function descendantsOf(page: Page, id: string): Set<string> {+ const eff = effectiveParents(page)+ const out = new Set<string>()+ // one forward pass suffices: a child always follows its effective parent+ for (const b of page.blocks) {+ const p = eff.get(b.id)+ if (p !== undefined && (p === id || out.has(p))) out.add(b.id)+ }+ return out+}+export function buildIndex(doc: SpacesDoc): SpaceIndex {const page = new Map<string, Page>()const children = new Map<string, Page[]>()diff --git a/spaces/src/store.ts b/spaces/src/store.tsindex 1b4ed810..52a4eccf 100644--- a/spaces/src/store.ts+++ b/spaces/src/store.ts@@ -97,11 +97,35 @@ export class Store {}/** Pages in sidebar order: a depth-first walk of the page tree. */- tree(parent = '', depth = 0): Array<{ page: Page; depth: number }> {+ /**+ * The page tree, for the sidebar and the Markdown export.+ *+ * `seen` is not defensive tidiness. `buildIndex` bins pages by `parent` with+ * no position test, and two people concurrently dragging pages onto each+ * other converge on A.parent=B, B.parent=A — legal for each of them, a cycle+ * together. Neither page is then reachable from the root, so BOTH VANISH from+ * the sidebar and from the Markdown export while still sitting in the file,+ * and nothing says so. Worse, a subtree call from inside the cycle recurses+ * until the stack gives out.+ *+ * A cyclic group is surfaced at the ROOT rather than hidden: pages you can+ * see and re-home beat pages that quietly stopped existing.+ */+ tree(parent = '', depth = 0, seen: Set<string> = new Set()): Array<{ page: Page; depth: number }> {const out: Array<{ page: Page; depth: number }> = []for (const p of this.index.children.get(parent) ?? []) {+ if (seen.has(p.id)) continue+ seen.add(p.id)out.push({ page: p, depth })- out.push(...this.tree(p.id, depth + 1))+ out.push(...this.tree(p.id, depth + 1, seen))+ }+ // Anything a cycle kept off the root walk, listed rather than lost.+ if (parent === '' && depth === 0) {+ for (const p of this.doc.pages) {+ if (p.archived || seen.has(p.id)) continue+ seen.add(p.id)+ out.push({ page: p, depth: 0 })+ }}return out}