@atom.io/template-preact-svg-editor 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @atom.io/template-preact-svg-editor
 
+## 0.1.1
+
+### Patch Changes
+
+- bb1d8de: Expose reusable contour, convergence, Domain, and editor-model modules for collaborative consumers while retaining the local Bezier editor. Harden subpath reordering against selective-undo holes. Report rejection using each contour edit's own submission receipt so another edit or accepted broadcast cannot overwrite its outcome.
+
+  Use the standalone `@atom.io/react`, `@atom.io/realtime`, and `@atom.io/eslint-plugin` packages. Build with TypeScript 7 while providing TypeScript 6 for ESLint's compiler API. Pin dprint 0.64.1 to distrust the compromised eMudhra certificates when downloading formatter plugins.
+- Updated dependencies [bb1d8de]
+- Updated dependencies [aa30b42]
+- Updated dependencies [bb1d8de]
+  - atom.io@0.54.0
+  - @atom.io/realtime@0.1.0
+  - @atom.io/react@0.1.0
+
 ## 0.1.0
 
 ### Minor Changes

package/COLLABORATION.md

@@ -0,0 +1,132 @@
+# Collaborative SVG Model Decisions
+
+This template is the model-level fixture beneath Atom.io's collaborative vector
+design vertical. The same ordinary atoms, families, selectors, and transactions
+remain useful in a local editor and are now registered directly in a public
+Mosaic Domain.
+
+## Durable Shape
+
+Path order, path entities, subpath order, subpath entities, nodes, and edges are
+separate ordinary Atom.io states. Drawing is a selector projection. There is no
+SVG registry in the renderer or in realtime core.
+
+Order members use rational ranks and immutable, idempotent operations. Concurrent
+placements at the same rank use stable entry identity as their tie-breaker.
+Geometry and entity members use deterministic last-operation-wins registers.
+Both reducers are independent of delivery order, reject operation-ID collisions,
+and publish strict Zod schemas for the future MOS-11 member-model hook.
+Register receipts remain in the fixture state so that reuse of a superseded
+operation ID still fails closed regardless of delivery order. The reducers and
+their Standard-Schema operation boundaries register directly with the public
+Domain member-model API. Bounding retained receipts is deliberately reserved
+for MOS-16 model-aware compaction.
+
+The local structural operations are transactions. Import validates the complete
+fixture before writing. Insert, delete, split, and reorder update every required
+member and its order state within one observable settlement. The invariant
+selector reports duplicate references, absent entities, wrong ownership, absent
+node or edge registers, and invalid close-node pairs.
+
+## Gesture and Presence Boundary
+
+One pointer-down creates one actor/session-scoped gesture identity backed by a
+logical clock. All member operations produced by that gesture derive stable,
+totally ordered operation identities from it.
+
+Pointer moves update only ephemeral presence in SVG document coordinates. The
+ordinary drawing selector projects that preview for immediate feedback. Pointer-up
+coalesces the entire drag into one durable geometry transaction; cancellation
+drops the presence and writes nothing durable. Rejection still releases local
+pointer and presence state. A disconnect can therefore expire the preview rather
+than leaving partially committed geometry.
+
+DOM references, the actual pointer-capture owner, active drag, zoom, pan,
+selection, and workspace state have explicit local atoms. Presence is keyed by
+logical actor and session, so concurrent sessions for one identity cannot
+overwrite or clear each other. It carries a logical resource target and
+coordinates, never a DOM identity or client viewport coordinate.
+
+## Why This Takes Its Own Path
+
+The public Mosaic Domain contract classifies and addresses members, and its
+atomic heterogeneous batches invoke registered per-member convergence models.
+This fixture plugs synchronous pure reducers and Standard-Schema-compatible
+operation schemas into those public seams without inventing a private batch
+envelope or registration system.
+
+The current `OList` transceiver is intentionally not used for collaborative
+ordering. Its index-based mutations are useful locally but do not by themselves
+converge when concurrent operations arrive in different orders. Rational order
+operations make the required contention behavior executable while remaining
+ordinary atom values.
+
+## Domain Batches and Observation
+
+`svg-domain.ts` registers path order, paths, subpath order, subpaths, nodes, and
+edges as durable Domain members with their public value models. Import, insert,
+delete, split, reorder, and coalesced geometry commits plan explicit public
+member operations and submit one heterogeneous batch carrying the stable gesture
+ID. The application does not maintain a parallel registry.
+
+Complete preflight precedes a single Store settlement. A rejected final member
+therefore rolls back the whole optimistic gesture, and the invariant selector
+never observes an accepted subpath order entry without its entity, node, and
+edge. Duplicate delivery is idempotent. Offline work remains a complete pending
+batch and replays after recovery.
+
+Independent node families settle independently. Same-node register operations
+retain immutable receipts and choose by stable operation identity, so arrival
+order and a durable mutex do not affect the result.
+
+## Selective Compensation
+
+Undo does not rewind an Atom.io timeline. Each reducer can accept a compensation
+receipt naming exact earlier operation IDs to hide. The editor records only its
+own successfully submitted gestures and appends all receipts for one undo in one
+new batch. Later foreign operations remain candidates and therefore remain
+visible.
+
+Every Domain operation also carries its claimed actor. The member model compares
+that actor with authenticated batch context and permits compensation targets only
+when their retained receipt belongs to the same actor. A client cannot construct
+a compensating batch that hides another participant's work.
+
+## Generic Presence Innovation
+
+MOS-11 supplied durable batching but no public ephemeral controller. This work
+adds a generic Mosaic Domain presence protocol, client, server, and Socket.IO
+adapter rather than hiding an SVG-specific event channel in the template.
+
+Presence addresses public ephemeral members and passes their Standard Schema
+boundary. The server binds authorship to the authenticated actor and session,
+requires a monotonically increasing session sequence, and retains cleared
+session cursors so a delayed update cannot resurrect a preview. One physical
+presence address has one live actor-session owner; separate sessions for one
+actor use separate family keys and cannot overwrite or clear each other.
+
+Payload size, update rate, live session count, client queue, server queue, and
+socket request queue are bounded. Disconnect and expiry publish monotonic clear
+envelopes, do not append durable history, and expose cleanup subscriptions plus
+an explicit quiescent-session retirement hook for future residency work.
+
+The SVG projection carries only logical target identity and document
+coordinates. DOM nodes, pointer capture, active drag, viewport, zoom, and
+workspace state remain local atoms. Pointer moves update ephemeral presence;
+pointer-up contributes at most one durable geometry operation.
+Presence publication is advisory: a transient transport failure updates the
+controller's status but never aborts a local drag or its durable commit. Disposing
+the controller immediately removes every ephemeral projection it owns, so a
+recreated client cannot briefly display a cursor or preview from its predecessor.
+
+## Executable Conformance and Remaining Gates
+
+The local suite covers every structural planner, settled invariants, independent
+and contended geometry, malicious foreign compensation, whole-batch rejection,
+offline replay, and selective undo. The `@atom.io/realtime/testing` suite drives
+real Socket.IO clients through the public Domain, server, client, batch, and
+presence seams. It covers duplicate delivery, final-member rejection, offline
+replay, same-node contention, and disconnect during drag.
+
+Partial residency, checkpoint recovery, and process restart remain explicitly
+gated on MOS-12 and MOS-13. The canonical multiplayer renderer remains MOS-23.

package/README.md

@@ -1,13 +1,26 @@
 # Preact SVG Editor
 
-A Preact + Vite starter that uses `atom.io` to model an editable SVG path.
+A Preact + Vite starter that uses `atom.io` to model an editable SVG path. Its
+state model is also the local conformance foundation for collaborative vector
+editing with Mosaic Domains.
 
 ## What It Shows
 
-- atom families for keyed path nodes, edges, and subpaths
-- selector families for deriving SVG path data from small pieces of state
-- transactions for resetting and rebuilding the drawing in one user action
-- `useAtomicRef` for keeping a DOM ref available to atom.io logic
+- ordinary atoms and atom families for path order, paths, subpath order,
+  subpaths, nodes, and edges
+- deterministic sequence and register reducers with strict operation schemas
+- selector families that derive SVG path data from the ordinary state graph
+- atomic transactions for import, insert, delete, split, reorder, and geometry
+  gestures
+- public Mosaic Domain registration and heterogeneous batch planners for every
+  structural gesture
+- deterministic same-node contention, offline replay, duplicate delivery,
+  whole-batch rejection, and actor-selective compensation
+- actor/session-scoped logical-coordinate drag presence with one durable commit
+  at pointer-up
+- explicit local-only workspace, viewport, DOM reference, pointer capture, and
+  active-drag state
+- `useAtomicRef` for keeping the local SVG element available to atom.io logic
 
 ## Run It
 
@@ -26,14 +39,34 @@ npm run preview
 
 Run `npm run lint` before committing. It enforces ESLint, type-aware Oxlint, React hook call-order correctness, and TypeScript with zero warnings. Run `npm run fmt:check` in CI and `npm run fmt` to apply the pinned dprint configuration locally.
 
+Run the model conformance tests:
+
+```sh
+npm test
+```
+
+## Quality Checks
+
+Run `npm run lint` before committing. It enforces ESLint, type-aware Oxlint, and TypeScript with zero warnings. Run `npm run fmt:check` in CI and `npm run fmt` to apply the pinned dprint configuration locally.
+
 ## Where To Look
 
 - `src/index.tsx`: Preact entry point and resource links.
-- `src/BezierPlayground.tsx`: the atom.io state model and SVG editor UI.
+- `src/svg-convergence.ts`: pure convergent sequence/register schemas and
+  reducers.
+- `src/svg-editor-state.ts`: the durable graph, local/ephemeral boundaries,
+  selectors, transactions, and gesture identities.
+- `src/svg-domain.ts`: public Domain registration, structural batch planning,
+  presence projection, and actor-selective compensating batches.
+- `src/BezierPlayground.tsx`: the Preact renderer and pointer adapter.
+- `COLLABORATION.md`: correctness decisions, innovations, and remaining
+  persistence gates.
 - `src/style.css`: layout and editor styling.
 
-## Next Ideas
+## Realtime Boundary
 
-- Add undo and redo with an atom.io timeline.
-- Persist the SVG path to local storage.
-- Export the current drawing as an `.svg` file.
+The reusable model fixture now synchronizes through public Mosaic Domain batch
+and presence APIs. The visible playground intentionally remains a small local
+renderer; MOS-23 consumes this fixture in the canonical realtime vector-editor
+template. Partial residency, checkpoints, and process restart remain gated on
+MOS-12 and MOS-13 rather than being simulated by application state.

package/eslint.config.ts

@@ -1,6 +1,6 @@
+import AtomIOPlugin from "@atom.io/eslint-plugin"
 import { default as TypeScriptPlugin } from "@typescript-eslint/eslint-plugin"
 import * as parser from "@typescript-eslint/parser"
-import AtomIOPlugin from "atom.io/eslint-plugin"
 import type { Linter } from "eslint"
 import * as ImportPlugin from "eslint-plugin-import-x"
 import { default as SimpleImportSortPlugin } from "eslint-plugin-simple-import-sort"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atom.io/template-preact-svg-editor",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/jeremybanka/atom.io.git",
@@ -8,28 +8,40 @@
   },
   "license": "Apache-2.0",
   "type": "module",
+  "exports": {
+    "./contour": "./src/svg-contour.ts",
+    "./convergence": "./src/svg-convergence.ts",
+    "./domain": "./src/svg-domain.ts",
+    "./model": "./src/svg-editor-state.ts"
+  },
   "dependencies": {
-    "atom.io": "0.53.3",
-    "preact": "11.0.0",
+    "@atom.io/react": "0.1.0",
+    "@atom.io/realtime": "0.1.0",
+    "atom.io": "0.54.0",
+    "preact": "11.0.1",
     "react": "npm:@preact/compat@18.3.2",
-    "react-dom": "npm:@preact/compat@18.3.2"
+    "react-dom": "npm:@preact/compat@18.3.2",
+    "zod": "4.6.7"
   },
   "devDependencies": {
-    "@dprint/json": "0.25.0",
-    "@dprint/markdown": "0.24.0",
-    "@dprint/oxc": "0.42.0",
+    "@atom.io/eslint-plugin": "0.1.0",
+    "@dprint/json": "0.25.2",
+    "@dprint/markdown": "0.28.0",
+    "@dprint/oxc": "0.47.0",
     "@preact/preset-vite": "2.10.6",
-    "@typescript-eslint/eslint-plugin": "8.71.0",
-    "@typescript-eslint/parser": "8.71.0",
-    "dprint": "0.58.0",
+    "@typescript-eslint/eslint-plugin": "8.72.0",
+    "@typescript-eslint/parser": "8.72.0",
+    "@typescript/native": "npm:typescript@7.0.2",
+    "dprint": "0.64.1",
     "dprint-plugin-malva": "0.16.0",
-    "eslint": "10.11.0",
+    "eslint": "10.13.0",
     "eslint-plugin-import-x": "4.17.1",
     "eslint-plugin-simple-import-sort": "14.0.0",
-    "oxlint": "1.86.0",
-    "oxlint-tsgolint": "7.0.2003",
-    "typescript": "7.0.2",
-    "vite": "8.3.1"
+    "oxlint": "1.89.0",
+    "oxlint-tsgolint": "7.0.2004",
+    "typescript": "npm:@typescript/typescript6@6.0.2",
+    "vite": "8.3.5",
+    "vitest": "5.0.5"
   },
   "publishConfig": {
     "access": "public"
@@ -43,6 +55,8 @@
     "lint:eslint": "eslint --max-warnings 0 .",
     "lint:oxlint": "oxlint --deny-warnings .",
     "lint:types": "tsc -b",
-    "preview": "vite preview"
+    "preview": "vite preview",
+    "test": "vitest run",
+    "test:once": "vitest run"
   }
 }