@usethrottle/builder-schema 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,39 @@
1
- # Temporary Holding Version
1
+ # @usethrottle/builder-schema
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The page document, site settings, responsive rules, limits, basic widget
4
+ definitions and document edit operations for Throttle Builder. Pure TypeScript
5
+ plus zod 4.
6
+
7
+ ## Document edit operations
8
+
9
+ `applyOps(doc, ops, ctx)` applies a batch of `DocOp`s atomically: either every
10
+ op applies and the result passes the schema and limits, or nothing changes and
11
+ `issues[]` says why. It is pure and never throws on bad input. Validate untrusted
12
+ ops (autosave, MCP, import) with `docOpSchema` first.
13
+
14
+ `invertOps(before, ops, ctx)` returns the ops that undo the batch. The undo
15
+ contract is **deep equality** (`toEqual`), not byte equality:
16
+
17
+ - key order inside objects may differ;
18
+ - a prop or override stored as an explicit `null` comes back **absent** (both
19
+ mean the definition's default);
20
+ - empty `responsive` containers come back absent.
21
+
22
+ Undoing a `remove` is checked again as an insert, so it can be refused (for
23
+ example when the node's widget is no longer available, spec 8.5). Callers must
24
+ handle `applyOps` refusing an inverse batch. `invertOps` throws if `ops` do not
25
+ apply to `before`.
26
+
27
+ ## Who may send which op
28
+
29
+ - `docOpSchema` is for the editor's own autosave and undo. It allows
30
+ `upgradeNode.restore` (the undo of an upgrade) and `replaceDocument`. `applyOps`
31
+ accepts a `restore` only when migrating it forward reproduces the node's current
32
+ props and overrides (spec 8.5: forward migrations only).
33
+ - `agentDocOpSchema` / `agentDocOpsSchema` are for MCP `apply_ops` and the Widget
34
+ API. They refuse `restore` and `replaceDocument` (spec 8.4) and cap a batch at
35
+ 500 ops. Never accept agent input through `docOpSchema`.
36
+ - `hidden`, `anchor`, `spacingTop` and `spacingBottom` are common node props:
37
+ `setProps`, `setResponsive` and inserted nodes accept them on every widget
38
+ (custom ones included), checked by `COMMON_WIDGET_SETTINGS`, not by the
39
+ widget's own settings.