@particle-academy/fancy-doc-commons

The shared, pure, zero-dependency core for the Fancy document / surface packages — the model an agent or a human emits and edits. Sibling of fancy-file-commons (which owns file / diff concerns); this owns node / tree / op concerns.

Design doc: .ai/plans/fancy-doc-commons.md in the envelope. This package is the Phase-1 substrate: the parts every "agent emits a surface" model needs, so they stop diverging into N incompatible schemas + N bespoke bridges.

No React, no DOM. JSON-friendly, deterministic, and safe to hand across an MCP bridge.

What it owns

| Area | Exports | |---|---| | Ordering | fractionalKey(a, b) — collab-safe sibling order (a node always inserts between two others without renumbering). | | Document tree | DocNode / DocTree (a flat Record<id, node> map with parent + order), childrenOf, roots, descendantsOf, ancestorsOf, isAncestorOrSelf, appendOrder. | | Op-spine | DocReducer<Doc, Op> (the reduce + invert contract every surface implements), reduceAll, and a reference treeReducer() / TreeOp over DocTree with exact inverses. | | Canvas | Viewport / PositionedItem / Connector (the shape triplicated in whiteboard / artboard / flow), byZ, topZ, screenToWorld, worldToScreen. | | Staged writes | AcceptanceState / AcceptanceStatus / Proposal / StagePolicy — one trust-but-verify (accept / reject) model for every surface. | | Style + CSS | StyleProps / Constraints / PerBreakpoint / StyledNode + emitTreeCss — the per-breakpoint style model and its deterministic CSS emitter (sorted decls/ids, fixed media format), so a doc gets responsive styling + an SSR first byte. Pass your own selectorFor to match an existing convention byte-for-byte (cms uses [data-cms]). |

The idea

Model every mutation as a typed op with a pure reduce and a computable invert, over a flat node tree addressed by stable ids. Then undo, redo, staged writes, presence, and collaboration all derive from one code path — instead of the five bespoke ones the kit has today. fancy-cms's PageDoc / PageOp and fancy-slides' Deck / DeckOp are the two mature spines this generalizes; other surfaces adopt the contract incrementally.

import { treeReducer, reduceAll, appendOrder, type DocTree } from "@particle-academy/fancy-doc-commons";

const r = treeReducer();
const op = { t: "insert", node: { id: "n1", type: "text", parent: null, order: appendOrder(doc, null), props: { content: "hi" } } };
const next = r.reduce(doc, op);
const undo = r.invert(doc, op);      // → [{ t: "remove", id: "n1" }]
const back = reduceAll(r, next, undo); // deep-equals doc

Status

Phase 1, v0.1: ordering · tree · op-spine · canvas · staged writes · style + CSS emitter. Next (Phase 2): registerDocBridge in agent-integrations — generate a surface's MCP tools (read + typed op tools + uniform undo/pending/activity) from a DocReducer, and build the greenfield registerCmsBridge on it. Later slices: data-binding ({$bind}) + actions + motion.