docblocks-core 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,67 @@
+# docblocks-core
+
+## 0.1.0
+
+### Added
+
+- The initial release of the headless CRDT document engine
+  (dependencies: `yjs`, `y-protocols`; no UI dependencies — the server,
+  the blob resolution, and the persistence are consumer-side concerns).
+- The document data format (JSON `v: 1`): the document meta (`id`,
+  `title`, the optional `avatar`, `createdAt`) + the flat block map
+  (`id → block`) with the explicit order via `children: [blockId]`; the
+  JSON ↔ Yjs layout is isomorphic (every JSON field has exactly one Yjs
+  image — the root's `children` live in the registered `rootOrder` array,
+  and each non-root block carries a Yjs-layout-only `parent` field that
+  never reaches the JSON).
+- The block and mark registry as the single source of truth, with the
+  generated discriminated-union types (an invalid attribute is a type
+  error at the call site) and the typed command errors (the
+  `UnknownBlockError`, the `InvalidRangeError`, the `DetachedBlockError`, ...).
+- The v1 block types: `root`, `paragraph`, `quote`, `heading` (levels
+  1–6), `list-item` (`bullet` / `number` / `task`, the nesting over the
+  `indent` attribute), `callout` (the `variant` + the additive
+  `color?` / `icon?` overrides), `code`, `divider`, `image` (the opaque
+  `src` key), `embed`, the `table` / `table-row` / `table-cell` triple
+  (the cells are the mini-docs; the column set is the shared
+  `columnOrder` id array + the cell's `columnId` binding), the
+  `database` block (the inline `columns` + `rows` form and the external
+  `tableId` form), and the five canvas types (`surface`, `shape`,
+  `connector`, `frame`, `canvas-text`) with the optional `geometry`.
+- The text model: a single `Y.Text` per text block with the
+  character-attribute marks (`bold`, `italic`, `strike`, `underline`,
+  `code`, `link`, `color`, `highlight`, `mention`) and the JSON run
+  array (`content: [{ text, marks }]`); the formatting is a pure
+  attribute op, so the character identity survives the concurrent
+  formatting and deletion.
+- The semantic command API (the only path for the normal editing): the
+  block commands (`insertBlock` / `updateBlock` / `moveBlock` /
+  `removeBlock` / `changeBlockType`), the text commands (`insertText` /
+  `deleteText` / `setMark` / `unsetMark`), the document meta
+  (`setTitle` / `setAvatar`), the geometry and the z-order
+  (`setGeometry`, `setZOrder`), the database row commands, and the table
+  row / column commands; `transact` batches the commands into one undo
+  step and one wire update.
+- The selection view (points and ranges, the rebase rules over the
+  concurrent edits) and the per-document undo / redo history; the
+  selection is the client / view state, never document data (the other
+  clients' selections travel only in the ephemeral awareness).
+- The CRDT-level power-user API: `encode` / `encodeUpdate` /
+  `applyUpdate` / `toJSON` / `fromJSON`, and the explicit `doc.raw:
+  Y.Doc` escape hatch (not guaranteed across versions).
+- The transport layer: the `SyncProvider` interface + the
+  `WsSyncProvider` (the standard y-protocols over WebSocket,
+  wire-compatible with `y-websocket` / `pycrdt`) and the `attach(doc,
+  provider)` glue (the origin guard + the full-state bootstrap; the
+  send buffers over the not-open socket); the presence over the
+  y-protocols awareness (the selection + the `updatedAt` per peer, the
+  ~30 s staleness TTL).
+- The frame as the viewport window into its own surface (no children,
+  no content, no `zIndex`) + the page frame block (the `frameId?` weak
+  reference); the canvas z-order stands the derived dense 1..N mirror
+  (`derivedZIndex`, re-derived on load).
+- The complementary reader / validator postures: the strict validator
+  (only the known types and marks) and the lenient reader (the unknown
+  type → the placeholder fallback, the unknown mark → ignored, the
+  unknown attribute → ignored) — the forward-compatibility across the
+  minor versions of the major data format.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wereintouch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,168 @@
-# Temporary Holding Version
+# docblocks-core
 
-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.
+The headless CRDT document engine for docblocks — the data half: the
+document model, the editing commands, the selection, and the sync
+transport. There is no UI in this package; rendering and editing live in
+[`docblocks-react-ui`](https://www.npmjs.com/package/docblocks-react-ui).
+
+The engine is built on [Yjs](https://yjs.dev) (a CRDT): documents converge
+across peers even when updates arrive out of order, duplicated, or with
+losses. The only runtime dependencies are `yjs`, `y-protocols`, and `lib0`.
+
+## Install
+
+```sh
+npm i docblocks-core
+```
+
+The package is ESM-only (`import`, not `require`); it stands Node
+`^22.22.2 || ^24.15.0 || >=26.0.0` (the `engines` field).
+
+A document is created, edited with commands, and read back as plain JSON —
+every read returns a **snapshot** (a plain object), never a live Yjs
+reference, so mutating a returned block does nothing.
+
+```ts
+import { createDoc, fromJSON } from "docblocks-core";
+
+const doc = createDoc({ id: "my-doc" });
+
+const para = doc.insertBlock("paragraph");
+doc.insertText(para, 0, "hello world");
+doc.setMark(para, 0, 5, { type: "bold" });
+
+const json = doc.toJSON(); // { v, meta, blocks, children }
+// …persist or send `json` …
+const restored = fromJSON(json); // a fresh Doc over the same data
+```
+
+Commands are `Doc` methods. Each command runs inside a transaction — one
+undo step, one wire update. Batch several into a single step with
+`transact`:
+
+```ts
+doc.transact(() => {
+  const h = doc.insertBlock("heading", { level: 1 }, { after: para });
+  doc.insertText(h, 0, "Title");
+}); // one undo step, one wire update
+```
+
+The block and mark registries drive the command types: `doc.insertBlock`
+accepts only a known block type, and its `attrs` are required exactly when
+the type demands them — `doc.insertBlock("heading", { level: 7 })` is a
+compile-time error. Unknown input throws a typed error
+(`UnknownBlockError`, `InvalidRangeError`, …); commands never no-op
+silently.
+
+## The Doc
+
+`createDoc(options?)` builds a document with a root block and an empty,
+editable first paragraph. The other entry points:
+
+- `fromJSON(json)` — build a `Doc` from a JSON snapshot.
+- `loadDoc(bytes)` — build a `Doc` from an encoded full state (a base
+  snapshot; apply diffs with `applyUpdate`).
+- `doc.toJSON()` — the JSON snapshot (`{ v, meta, blocks, children }`).
+- `doc.encode()` / `doc.encodeUpdate(stateVector?)` — the encoded full
+  state / the incremental update.
+- `doc.applyUpdate(bytes)` — apply an encoded update (the remote-apply path).
+
+`doc.raw` exposes the underlying `Y.Doc`; it is an explicit escape hatch
+and its shape is not guaranteed.
+
+## Commands
+
+Editing goes through the semantic API (the only path for normal editing).
+The commands translate into `Y.Doc` mutations inside a transaction:
+
+- **Blocks** — `insertBlock`, `updateBlock`, `moveBlock`, `removeBlock`,
+  `changeBlockType`.
+- **Text** — `insertText`, `deleteText`, `setMark`, `unsetMark`, and the
+  range forms (`deleteTextRange`, `setMarkRange`).
+- **Document meta** — `setTitle`, `setAvatar`, `setGeometry`, `setZOrder`.
+- **Database rows** — the row commands (`insertRow`, `setCell`,
+  `removeRow`, `moveRow`, …).
+- **Table rows / columns** — `insertTableRow`, `removeTableRow`,
+  `insertTableColumn`, `removeTableColumn`, the move / duplicate / color /
+  width commands, and `setTableRowColor`.
+
+Reads: `getBlock(id)`, `getChildren(id)`, `getRuns(id)`, `getText(id)`,
+`getTextLength(id)`. History: `undo()` / `redo()` (with `canUndo()` /
+`canRedo()`) — one `transact` is one undo step, and a command batched
+into a `transact` is one step across the batch.
+
+## Sync
+
+`attach(doc, provider)` is the glue between a `Doc` and a
+`SyncProvider`: it bootstraps the session (sending the full local state
+first), then routes local transactions out and remote updates in. `detach()`
+on the returned session tears the session down.
+
+`WsSyncProvider` speaks the standard y-protocols wire over a WebSocket
+(wire-compatible with a standard y-websocket / pycrdt server):
+
+```ts
+import { WsSyncProvider, attach } from "docblocks-core";
+
+const provider = new WsSyncProvider("wss://my-server/ws/room-1", {
+  token: "…",
+});
+await provider.connect();
+const session = attach(doc, provider);
+// … on teardown:
+session.detach();
+```
+
+Reactivity: `doc.onChange(handler)` fires for every transaction;
+`doc.onRemoteChange(handler)` fires for non-local-origin transactions only
+(the feed a sync consumer's write-back guards hook into).
+
+## Selection
+
+Selection is client / view state, not document data — it is not in the JSON
+and not in document updates. `createSelection(doc)` builds a `SelectionView`
+over the doc; other clients' selections travel only in the ephemeral
+awareness channel (the presence payload). `presenceSelectionOf(selection)`
+projects a selection into the presence payload shape.
+
+## Data format
+
+The JSON format is `v: 1`: `meta` (the doc `id`, `title`, the optional
+`avatar`) plus a **flat block map** (`id → block`) with explicit order via
+`children: [blockId]`; nesting (lists, table cells) is `children`. The text
+of a text block is `content: [{ text, marks }]` runs. JSON ↔ Yjs is
+isomorphic — every JSON field has exactly one Yjs image.
+
+The v1 registry covers the page types (`paragraph`, `quote`, `heading`,
+`list-item`, `callout`, `code`, `divider`, `image`, `embed`, `table` /
+`table-row` / `table-cell`, `database`), the five canvas types (`surface`,
+`shape`, `connector`, `frame`, `canvas-text`), and `root`; the v1 marks
+are `bold`, `italic`, `strike`, `underline`, `code` (exclusive), `link`,
+`color`, `highlight`, and `mention`. The type lists stand exported
+(`PAGE_BLOCK_TYPES`, `LEAF_BLOCK_TYPES`, `BLOCK_REGISTRY`,
+`MARK_REGISTRY`, `CALLOUT_ICONS`).
+
+The block and mark registries are the extension point. Adding a block type
+or mark is additive (a minor): the registry entry plus a renderer; the
+validator and the commands stay registry-driven. The reader tolerates the
+unknown (an unknown block type renders a placeholder, an unknown mark is
+ignored and its text stays); the validator is strict (`validateDoc` reports
+only known types and marks — it protects the data you own). A breaking
+change is a major: the reader rejects the unknown major, and a migration
+helper converts the data. `flattenDoc(json)` normalizes the legacy nested
+shape into the flat page model at load.
+
+## Validation
+
+`validateDoc(json, lenient?)` returns the list of validation errors (empty
+is valid). Strict (the default) is the writer's contract — it checks the
+known types and mark values. Lenient is the reader boundary — unknown types
+and marks pass through (the reader preserves them), so a reader of `v1.0`
+can safely load `v1.5` data.
+
+## Non-goals
+
+This package is deliberately headless. It does not ship a UI (that is
+`docblocks-react-ui`), a server (any Yjs-compatible server is the receiving
+side), or blob resolution (the consumer provides a `BlobStore`). It holds no
+persistence — snapshot and update storage is a consumer-side concern.