Reference API Sketch

This is code-shaped design input, not production code.

Engine Boundary

type CvlSubstrate = "local" | "yjs" | "loro-tree" | "loro-extended";

type CvlEngine = {
  change(fn: (draft: CvlDraft) => void): CvlTransition;
  applyOp(op: CvlOp): CvlTransition;
  selectors: CvlSelectors;
  encodeUpdate(from?: Uint8Array): Uint8Array;
  applyUpdate(update: Uint8Array): CvlTransition;
};

Draft Facade

type CvlDraft = {
  node(id: NodeId): NodeDraft;
  group(id: GroupId): GroupDraft;
  parent(id: NodeId): ParentDraft;
};

type NodeDraft = {
  moveTo(parentId: NodeId, index?: number): void;
  setText(text: string): void;
  setMetrics(metrics: Metrics): void;
};

type GroupDraft = {
  select(memberIds: NodeId[]): void;
  setExact(count: number): void;
  addMember(nodeId: NodeId, index?: number): void;
  removeMember(nodeId: NodeId): void;
};

type ParentDraft = {
  addNode(input: CvlNodeInput, options?: { groupId?: GroupId; select?: boolean }): NodeId;
  createGroup(input: CvlGroupInput): GroupId;
};

Selectors

type CvlSelectors = {
  documentSummary(): Selector<DocumentSummaryVm>;
  section(sectionId: NodeId): Selector<SectionVm>;
  group(groupId: GroupId): Selector<GroupVm>;
  renderProjection(): Selector<RenderVm>;
  metrics(nodeId: NodeId): Selector<MetricsVm>;
};

type Selector<T> = {
  read(): T;
  subscribe(fn: (value: T, transition: CvlTransition) => void): () => void;
};

Transition Report

type CvlTransition = {
  revision: number;
  changedNodeIds: NodeId[];
  changedGroupIds: GroupId[];
  changedParentIds: NodeId[];
  renderProjectionChanged: boolean;
  metricsInvalidatedNodeIds: NodeId[];
  diagnostics: CvlDiagnostic[];
};

Design Notes

• This facade should be substrate-neutral. Svelte, MCP, Typst, and tailoring should not know whether the backing engine is Yjs, Loro, or local.
• The operation vocabulary should encode CVL invariants. Raw map/list writes should stay behind the engine boundary.
• Selector outputs should be immutable snapshots or structurally shared view models, never mutable CRDT refs.
• Agents should see group policies, candidates, active selections, fit metrics, and diagnostics through this same API.