Bento, the office suite that fits in a file
TypeScript mit-licenseofficeoffice-365office-suiteoffice-toolsoffice365open-sourcepowerpointself-hostedsingle-page-appslidesslideshareslideshowslideshow-galleryslideshow-makerslideshows
sync: name the document shape, so one engine can serve two apps (#247)
nyblnetc84284e4cfcd
diff --git a/slides/src/sync/crdt.ts b/slides/src/sync/crdt.tsindex aad5f415..6c99349a 100644--- a/slides/src/sync/crdt.ts+++ b/slides/src/sync/crdt.ts@@ -37,6 +37,81 @@import type { BentoDoc, Slide, SlideElement } from '../model'+// ---------------------------------------------------------------------------+// document shape+// ---------------------------------------------------------------------------++/**+ * WHICH KEYS HOLD THE TWO CONTAINER LEVELS.+ *+ * The engine's algebra — composite node keys, fractional position keys,+ * per-(node,key) registers, the token RGA over `html` — has nothing to do with+ * slides. Only the two property names do: the doc key holding the parent array+ * (`slides`) and the parent key holding the child array (`elements`).+ * bento/spaces has the same two levels under different names (`pages`,+ * `blocks`), so naming them is the whole of what it takes for one engine to+ * serve both apps.+ *+ * BOUND AT MODULE LEVEL, NEVER SERIALIZED, NEVER ON THE WIRE. A room is+ * single-app by construction (the room id is minted per file), so no frame+ * ever has to say which shape it came from — and putting a shape tag in+ * SyncStateJSON would change the bytes of every bento/slides file already on+ * a disk. That constraint is not a style preference: scripts/test-sync-equiv.ts+ * asserts byte-identity against the engine as shipped, and a `state-key-order`+ * mutant exists precisely to prove the comparator notices.+ *+ * The WIRE VOCABULARY is deliberately not parameterized. Ops keep saying+ * `kind:'slide'|'element'` and carrying `sl`/`el` for every app: renaming them+ * per app buys prettier debug output and costs a second binding on the+ * highest-consequence bytes in the system.+ */+export interface DocShape {+ /** doc-level key holding the PARENT array: 'slides' | 'pages' */+ readonly parents: string+ /** parent-level key holding the CHILD array: 'elements' | 'blocks' */+ readonly children: string+ /**+ * Doc-level keys the differ never syncs.+ *+ * MUST contain `parents`, which is why `shape()` below DERIVES it rather+ * than taking it: the container is synced structurally — per node, with its+ * own position key — so listing it as an ordinary doc property instead would+ * collapse the whole document into ONE last-writer-wins register, and every+ * concurrent edit would destroy every other. Deriving it means no caller can+ * get it wrong; when this becomes a constructor argument, that has to become+ * an assertion instead.+ */+ readonly skipDoc: ReadonlySet<string>+}++/** Derived, never authored: the volatile set is the same for every app apart+ * from the container name, so writing it out twice invites them to drift. */+const shape = (parents: string, children: string): DocShape => {+ const skipDoc = new Set([parents, 'modified', 'collab', 'format', 'version'])+ return { parents, children, skipDoc }+}++export const SLIDES_SHAPE = shape('slides', 'elements')++/** The shape this module is bound to. Becomes a constructor argument in the+ * next step; today it is exactly what the file hardcoded before. */+const S: DocShape = SLIDES_SHAPE++/** The parent array of a document, and the child array of a parent. Indexed+ * access through the descriptor: `d['slides']` is the same lookup `d.slides`+ * was, so these are byte-neutral by construction. */+const P = (d: BentoDoc): Slide[] => (d as unknown as Record<string, Slide[]>)[S.parents]+const C = (p: Slide): SlideElement[] => (p as unknown as Record<string, SlideElement[]>)[S.children]+/**+ * …and the write-back form for the child array.+ *+ * There is deliberately no `setP`. The engine mutates the PARENT array only in+ * place (push/splice/sort), never by assignment — worth knowing, because a+ * future edit that reassigns it would be replacing the array the caller's+ * document still points at.+ */+const setC = (p: Slide, v: SlideElement[]): void => { (p as unknown as Record<string, SlideElement[]>)[S.children] = v }+export const DOC_NODE = '@doc'/**@@ -322,11 +397,11 @@ export class SyncState {* keys) with the null register [0,''] that loses to every real op.*/adopt(doc: BentoDoc) {- const ns = doc.slides.length- doc.slides.forEach((sl, i) => {+ const ns = P(doc).length+ P(doc).forEach((sl, i) => {if (!this.pos[sl.id]) this.pos[sl.id] = { p: DOC_NODE, o: spreadKey(i, ns), r: [0, ''] }- const ne = sl.elements.length- sl.elements.forEach((el, j) => {+ const ne = C(sl).length+ C(sl).forEach((el, j) => {const k = elKey(sl.id, el.id)if (!this.pos[k]) this.pos[k] = { p: sl.id, o: spreadKey(j, ne), r: [0, ''] }})@@ -348,7 +423,7 @@ export class SyncState {}// ---- doc-level props- const SKIP_DOC = new Set(['slides', 'modified', 'collab', 'format', 'version'])+ const SKIP_DOC = S.skipDocconst b = before as unknown as Record<string, unknown>const a = after as unknown as Record<string, unknown>for (const k of new Set([...Object.keys(b), ...Object.keys(a)])) {@@ -378,30 +453,30 @@ export class SyncState {// ---- slides by id; elements by COMPOSITE key (slide + bare id) — the// same element id on many slides is the morph idiom, each copy is its// own node. A cross-slide move therefore diffs as del(old)+ins(new).- const bSlides = new Map(before.slides.map((s) => [s.id, s]))- const aSlides = new Map(after.slides.map((s) => [s.id, s]))+ const bSlides = new Map(P(before).map((s) => [s.id, s]))+ const aSlides = new Map(P(after).map((s) => [s.id, s]))const bEls = new Map<string, { sl: string; el: SlideElement }>()const aEls = new Map<string, { sl: string; el: SlideElement }>()- before.slides.forEach((s) => s.elements.forEach((el) => bEls.set(elKey(s.id, el.id), { sl: s.id, el })))- after.slides.forEach((s) => s.elements.forEach((el) => aEls.set(elKey(s.id, el.id), { sl: s.id, el })))+ P(before).forEach((s) => C(s).forEach((el) => bEls.set(elKey(s.id, el.id), { sl: s.id, el })))+ P(after).forEach((s) => C(s).forEach((el) => aEls.set(elKey(s.id, el.id), { sl: s.id, el })))// deleted slides (cascade the elements the deleter saw, minus survivors)for (const [id, sl] of bSlides) {if (aSlides.has(id)) continue- const cas = sl.elements.map((e) => elKey(id, e.id)).filter((k) => !aEls.has(k))+ const cas = C(sl).map((e) => elKey(id, e.id)).filter((k) => !aEls.has(k))const o = push<DelOp>({ ...this.stamp(), op: 'del', kind: 'slide', id, cas })this.tombs[id] = [o.l, o.a]this.stashNode(sl as unknown as Record<string, unknown>, id)cas.forEach((ek) => {this.tombs[ek] = [o.l, o.a]- const node = sl.elements.find((e) => elKey(id, e.id) === ek)+ const node = C(sl).find((e) => elKey(id, e.id) === ek)if (node) this.stashNode(node as unknown as Record<string, unknown>, ek)delete this.limbo[ek]delete this.txt[ek] // local tomb is the freshest stamp — always out-ranks})}// inserted (or resurrected) slides- const afterIds = after.slides.map((s) => s.id)+ const afterIds = P(after).map((s) => s.id)for (let i = 0; i < afterIds.length; i++) {const id = afterIds[i]if (bSlides.has(id)) continue@@ -412,8 +487,8 @@ export class SyncState {this.pos[id] = { p: DOC_NODE, o: ord, r: [o.l, o.a] }delete this.txt[id]delete this.stash[id] // fresh birth voids parked values (receivers do this in replayStash)- const ne = sl.elements.length- sl.elements.forEach((el, j) => {+ const ne = C(sl).length+ C(sl).forEach((el, j) => {const k = elKey(id, el.id)this.births[k] = [o.l, o.a]this.pos[k] = { p: id, o: spreadKey(j, ne), r: [o.l, o.a] }@@ -428,7 +503,7 @@ export class SyncState {const bp = prev as unknown as Record<string, unknown>const ap = sl as unknown as Record<string, unknown>for (const k of new Set([...Object.keys(bp), ...Object.keys(ap)])) {- if (k === 'elements' || k === 'id') continue+ if (k === S.children || k === 'id') continueif (JSON.stringify(bp[k]) === JSON.stringify(ap[k])) continueconst o = push<SetOp>({ ...this.stamp(), op: 'set', sl: id, k, v: clone(ap[k]) })this.regs[`${id} ${k}`] = [o.l, o.a]@@ -453,7 +528,7 @@ export class SyncState {const prev = bEls.get(id)if (!prev) {if (this.births[id] && !this.dead(id) && this.pos[id]?.p === sl) continue // came with a fresh slide ins above- const sib = aSlides.get(sl)!.elements.map((e) => elKey(sl, e.id))+ const sib = C(aSlides.get(sl)!).map((e) => elKey(sl, e.id))const ord = this.keyAround(sl, sib, sib.indexOf(id))const o = push<InsOp>({ ...this.stamp(), op: 'ins', kind: 'element', id, sl, ord, node: clone(el) })this.births[id] = [o.l, o.a]@@ -486,7 +561,7 @@ export class SyncState {// element order within each surviving slide (all ids — see slide pass)for (const [id, sl] of aSlides) {if (!bSlides.has(id)) continue- this.diffOrder(sl.elements.map((e) => elKey(id, e.id)), id, 'element', push)+ this.diffOrder(C(sl).map((e) => elKey(id, e.id)), id, 'element', push)}// remote ops that pended awaiting a seed can resolve against seeds this@@ -675,14 +750,14 @@ export class SyncState {}private findSlide(doc: BentoDoc, id: string): Slide | undefined {- return doc.slides.find((s) => s.id === id)+ return P(doc).find((s) => s.id === id)}/** composite-key lookup: an element node only ever lives on its key's* slide (or in limbo) — the same bare id on other slides is other nodes */private findEl(doc: BentoDoc, key: string): SlideElement | undefined {const s = this.findSlide(doc, keySlide(key))const bare = keyEl(key)- return s?.elements.find((e) => e.id === bare) ?? this.limbo[key]+ return (s ? C(s) : undefined)?.find((e) => e.id === bare) ?? this.limbo[key]}private applySet(doc: BentoDoc, op: SetOp, res: ApplyResult) {@@ -763,10 +838,10 @@ export class SyncState {// first ran it, so everyone must.const src = op.node as Slidethis.insertSlideLevel(doc, op.id, op.ord, src, stamp, res)- const ne = src.elements.length- src.elements.forEach((e, j) => this.insertElement(doc, elKey(op.id, e.id), op.id, spreadKey(j, ne), e, stamp, res))+ const ne = C(src).length+ C(src).forEach((e, j) => this.insertElement(doc, elKey(op.id, e.id), op.id, spreadKey(j, ne), e, stamp, res))this.drainPending(doc, op.id)- src.elements.forEach((e) => this.drainPending(doc, elKey(op.id, e.id)))+ C(src).forEach((e) => this.drainPending(doc, elKey(op.id, e.id)))} else {this.insertElement(doc, op.id, op.sl!, op.ord, op.node as SlideElement, stamp, res)this.drainPending(doc, op.id)@@ -787,11 +862,11 @@ export class SyncState {if (this.dead(id)) return // a delete still out-stamps this insertconst existing = this.findSlide(doc, id)if (existing) {- this.assignNode(existing as unknown as Record<string, unknown>, src as unknown as Record<string, unknown>, id, stamp, ['id', 'elements'])+ this.assignNode(existing as unknown as Record<string, unknown>, src as unknown as Record<string, unknown>, id, stamp, ['id', S.children])} else {const sl = clone(src)- sl.elements = [] // members materialize separately via insertElement- doc.slides.push(sl)+ setC(sl, []) // members materialize separately via insertElement+ P(doc).push(sl)this.replayStash(sl as unknown as Record<string, unknown>, id, stamp)}}@@ -822,7 +897,7 @@ export class SyncState {const el = clone(node)const p = this.pos[id].pconst sl = this.findSlide(doc, p)- if (sl && !this.dead(p)) sl.elements.push(el)+ if (sl && !this.dead(p)) C(sl).push(el)else this.limbo[id] = elthis.replayStash(el as unknown as Record<string, unknown>, id, stamp)live = el@@ -935,10 +1010,10 @@ export class SyncState {if (g && cmpReg(this.tombs[key] ?? [0, ''], g.sd) > 0) delete this.txt[key]const s = this.findSlide(doc, keySlide(key))const bare = keyEl(key)- const i = s ? s.elements.findIndex((e) => e.id === bare) : -1+ const i = s ? C(s).findIndex((e) => e.id === bare) : -1if (s && i >= 0) {- this.stashNode(s.elements[i] as unknown as Record<string, unknown>, key)- s.elements.splice(i, 1)+ this.stashNode(C(s)[i] as unknown as Record<string, unknown>, key)+ C(s).splice(i, 1)}}bump(op.id)@@ -950,12 +1025,12 @@ export class SyncState {if (this.dead(eid)) removeElement(eid)}if (this.dead(op.id)) {- const i = doc.slides.findIndex((s) => s.id === op.id)+ const i = P(doc).findIndex((s) => s.id === op.id)if (i >= 0) {- const [gone] = doc.slides.splice(i, 1)+ const [gone] = P(doc).splice(i, 1)this.stashNode(gone as unknown as Record<string, unknown>, op.id)// survivors (concurrently inserted) park in limbo under their key- for (const el of gone.elements) {+ for (const el of C(gone)) {const k = elKey(op.id, el.id)if (!this.dead(k)) this.limbo[k] = el}@@ -1066,13 +1141,13 @@ export class SyncState {if (a !== b) return a < b ? -1 : 1return x < y ? -1 : 1}- doc.slides.sort((s1, s2) => cmp(s1.id, s2.id))- const slideById = new Map(doc.slides.map((s) => [s.id, s]))+ P(doc).sort((s1, s2) => cmp(s1.id, s2.id))+ const slideById = new Map(P(doc).map((s) => [s.id, s]))for (const [key, el] of Object.entries(this.limbo)) {const p = this.pos[key]?.pif (p && slideById.has(p) && !this.dead(p) && !this.dead(key)) {const dest = slideById.get(p)!- if (!dest.elements.some((e) => e.id === el.id)) dest.elements.push(el)+ if (!C(dest).some((e) => e.id === el.id)) C(dest).push(el)else dbg(key, `limbo-restore DROP dup x=${(el as any).x}`)delete this.limbo[key]this.drainPending(doc, key)@@ -1081,13 +1156,13 @@ export class SyncState {// elements never relocate across slides (the composite key pins them to// one slide for life) — only sort by pos key and dedupe within the slide// (a node whose data travelled two routes can transiently duplicate)- for (const sl of doc.slides) {- sl.elements.sort((e1, e2) => cmp(elKey(sl.id, e1.id), elKey(sl.id, e2.id)))- sl.elements = sl.elements.filter((e, i) => {- const dup = i > 0 && e.id === sl.elements[i - 1].id+ for (const sl of P(doc)) {+ C(sl).sort((e1, e2) => cmp(elKey(sl.id, e1.id), elKey(sl.id, e2.id)))+ setC(sl, C(sl).filter((e, i) => {+ const dup = i > 0 && e.id === C(sl)[i - 1].idif (dup) dbg(elKey(sl.id, e.id), `remat dedupe DROP x=${(e as any).x}`)return !dup- })+ }))}}@@ -1141,12 +1216,12 @@ export class SyncState {}}// drop nodes that are dead under merged liveness- for (let i = doc.slides.length - 1; i >= 0; i--) {- const sl = doc.slides[i]+ for (let i = P(doc).length - 1; i >= 0; i--) {+ const sl = P(doc)[i]if (this.dead(sl.id)) {- doc.slides.splice(i, 1)+ P(doc).splice(i, 1)this.stashNode(sl as unknown as Record<string, unknown>, sl.id)- for (const el of sl.elements) {+ for (const el of C(sl)) {const k = elKey(sl.id, el.id)if (!this.dead(k)) this.limbo[k] = elelse this.stashNode(el as unknown as Record<string, unknown>, k)@@ -1154,11 +1229,11 @@ export class SyncState {res.structure = trueres.changed = true} else {- for (let j = sl.elements.length - 1; j >= 0; j--) {- const k = elKey(sl.id, sl.elements[j].id)+ for (let j = C(sl).length - 1; j >= 0; j--) {+ const k = elKey(sl.id, C(sl)[j].id)if (this.dead(k)) {- this.stashNode(sl.elements[j] as unknown as Record<string, unknown>, k)- sl.elements.splice(j, 1)+ this.stashNode(C(sl)[j] as unknown as Record<string, unknown>, k)+ C(sl).splice(j, 1)res.structure = trueres.changed = true}@@ -1175,12 +1250,12 @@ export class SyncState {// keyed composite; remote limbo nodes count — they're invisible but// their data is real)const rEls = new Map<string, SlideElement>()- rdoc.slides.forEach((s) => s.elements.forEach((e) => rEls.set(elKey(s.id, e.id), e)))+ P(rdoc).forEach((s) => C(s).forEach((e) => rEls.set(elKey(s.id, e.id), e)))for (const [key, el] of Object.entries(rstate.limbo ?? {})) if (!rEls.has(key)) rEls.set(key, el)- for (const sl of rdoc.slides) {+ for (const sl of P(rdoc)) {if (this.dead(sl.id) || this.findSlide(doc, sl.id)) continueconst copy = clone(sl)- copy.elements = copy.elements+ setC(copy, C(copy).filter((e) => !this.dead(elKey(sl.id, e.id))).map((e) => {const lb = this.limbo[elKey(sl.id, e.id)]@@ -1189,8 +1264,8 @@ export class SyncState {return lb}return e- })- doc.slides.push(copy)+ }))+ P(doc).push(copy)res.changed = trueres.structure = true}@@ -1198,13 +1273,13 @@ export class SyncState {if (this.dead(key) || this.findEl(doc, key)) continueconst p = this.pos[key]?.pconst host = p ? this.findSlide(doc, p) : undefined- if (host && !this.dead(host.id)) host.elements.push(clone(el))+ if (host && !this.dead(host.id)) C(host).push(clone(el))else this.limbo[key] = clone(el)res.changed = trueres.structure = true}// property registers: the winning side's value lives in its doc- const rSlides = new Map(rdoc.slides.map((s) => [s.id, s]))+ const rSlides = new Map(P(rdoc).map((s) => [s.id, s]))const rNode = (id: string): Record<string, unknown> | undefined =>id === DOC_NODE? (rdoc as unknown as Record<string, unknown>)@@ -1223,7 +1298,7 @@ export class SyncState {const dst = lNode(id)if (!src || !dst) continueconst isSlide = rSlides.has(id) || !!this.findSlide(doc, id)- this.assignNode(dst, src, id, this.births[id], isSlide ? ['id', 'elements'] : ['id'])+ this.assignNode(dst, src, id, this.births[id], isSlide ? ['id', S.children] : ['id'])res.changed = trueif (isSlide) res.structure = true}