@atom.io/template-preact-realtime-vector-editor 0.0.0-stage → 0.0.0

package/.oxlintrc.json

@@ -0,0 +1,12 @@
+{
+	"$schema": "./node_modules/oxlint/configuration_schema.json",
+	"extends": ["./node_modules/atom.io/oxlint.json"],
+	"plugins": ["typescript", "react"],
+	"rules": {
+		"react/jsx-key": "error",
+		"react/jsx-no-duplicate-props": "error",
+		"react/no-children-prop": "error",
+		"react/no-danger-with-children": "error",
+		"react/rules-of-hooks": "error"
+	}
+}

package/INNOVATIONS.md

@@ -0,0 +1,43 @@
+# Innovations and boundaries
+
+## Integrity is the model boundary
+
+Plane's durable object is one closed contour value. It contains an ordered list of three to sixty-four uniquely identified finite points. The renderer joins adjacent points and closes the final point to the first. There is no durable edge registry, path order, subpath order, curve control, or close command.
+
+That representation removes an entire class of reconciliation bugs. Every node has exactly two implicit neighbors. Branching, dangling edges, missing close operations, cross-member identity mismatches, and partially undone structural batches have no representable object state.
+
+The schema validates proposals, checkpoint hydration, and direct reducer use. The reducer parses before accumulation, so application code cannot bypass integrity by calling it locally.
+
+## One durable member and complete history states
+
+The `contour` member is a deterministic register of complete validated contour snapshots. A pointer-up, insertion, deletion, or replacement contributes one operation to that member. Undo and redo compensate only the authenticated actor's operations, then materialize another complete validated snapshot. Foreign snapshots remain active.
+
+The collaboration regression exercises the failure that motivated this design: one actor inserts a node, another actor moves that node, and the creator undoes the insertion. The participating actor's complete contour remains visible and valid. Undoing that participation returns to the valid default contour. The test checks the server and both clients and proves every visible node has degree two.
+
+The deliberate tradeoff is coarse contention. Simultaneous gestures based on the same contour are complete alternatives, and deterministic register order chooses one. This small example prefers an obvious integrity boundary over teaching an application-specific operation algebra. A product that needs disjoint contour edits to merge should define a single contour model whose operations replay into a validated contour; it should not split topology across independently undoable members.
+
+## The richer SVG tutorial stays separate
+
+The local `preact-svg-editor` still demonstrates paths, subpaths, line and cubic edges, ordering, and local transactions. Plane uses the constrained `./contour` export from that package. This keeps the reusable contour schema, reducer, Domain, and editor in one module without pretending that the Bezier tutorial's representational freedom is safe for this collaborative product.
+
+The legacy multi-member editor also adopts the complete subpath when a participant reorders it. That compatibility hardening prevents a foreign order receipt from outliving the creator's subpath, node, and edge receipts. Plane does not rely on that repair; its normal path has no independent order or edge members.
+
+## Presence is lossy and session-scoped
+
+Collaborator presence carries simulated identity, logical-coordinate pointer, and selected node ID. Drag presence carries one node ID and preview point. Both are ephemeral, authenticated by actor and session, absent from durable history, and cleared by disconnect or expiry. DOM elements, pointer capture, zoom, pan, and workspace selection remain local.
+
+Here, “authenticated” means bound to the actor and session accepted by the Domain controllers. The template handshake only allowlists simulated actors and can be impersonated. A deployed application must derive those values from verified credentials and provide its own batch authorization policy.
+
+The UI publishes pointer movement without waiting for acknowledgement. Pointer-up is the durable boundary.
+
+## Recovery and restart
+
+The Node service accepts a `MosaicDomainCheckpointStorageAdapter`. It serializes proposals with checkpoint publication so member reads belong to the accepted revision being published. Checkpoint compaction keeps the visible contour and protected receipts, and a fresh server generation reconstructs the same validated contour before serving recovery.
+
+This template keeps one small contour resident and uses the reference in-memory checkpoint adapter. Large design applications should provide durable storage and application-defined residency cuts. Scale policy belongs outside the contour reducer.
+
+## Renderer and transport boundaries
+
+The shipped application renders with Preact. Its `multiClient` fixture uses Testing Library's React renderer to drive the same Socket.IO client runtime, so React and ReactDOM remain test-only dependencies.
+
+The browser connects to its current origin. Vite proxies `/socket.io` and `/health` to the Node process in development and preview. Event names are application protocol; validation, atomic settlement, recovery, presence expiry, history, and actor authorization remain public Atom.io controllers.

package/README.md

@@ -1,3 +1,17 @@
-# Temporary Holding Version
+# Plane: Preact realtime contour editor
 
-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.
+Plane is a deliberately small collaborative editor for one closed, straight-line contour. It demonstrates a design application built on an Atom.io Mosaic Domain without asking a tutorial model to carry paths, subpaths, curves, edge handles, and independent topology registries.
+
+Run `npm run dev`, then open two tabs and choose different simulated identities from the header. Vite proxies both health and Socket.IO traffic to the Node service, so the browser connects through `window.location.origin`.
+
+The identity picker is an exploration aid, not authentication. Before deployment, derive actor and session identity from verified credentials and supply an application authorization policy to the collaboration service.
+
+The canvas supports node dragging, node insertion and deletion, private zoom, advisory focus, lossy remote pointers and drag previews, actor-selective undo and redo, offline replay, and visible pending or rejected work. A contour always has three to sixty-four uniquely identified finite points. Straight edges and closure are implicit, so a dangling edge, branch, curve, or node with degree other than two cannot be represented.
+
+The separate `preact-svg-editor` application remains the richer local Bezier tutorial. Plane imports its constrained contour module instead of putting that richer topology into a collaborative Domain.
+
+Read `INNOVATIONS.md` before adapting the example. It explains why the integrity boundary is one durable aggregate, what selective history can expose, and the deliberate concurrency tradeoff of this spartan model.
+
+## Quality Checks
+
+Run `npm run lint` before committing. It enforces ESLint, type-aware Oxlint, React hook call-order correctness, TypeScript, and CSS-module reachability with zero warnings. Run `npm run fmt:check` in CI and `npm run fmt` to apply the pinned dprint configuration locally.

package/_gitignore

@@ -0,0 +1,6 @@
+node_modules
+dist
+.turbo
+*.local
+*.log
+*.tsbuildinfo

package/dprint.json

@@ -0,0 +1,33 @@
+{
+	"$schema": "https://dprint.dev/schemas/v0.json",
+	"lineWidth": 81,
+	"useTabs": true,
+	"indentWidth": 2,
+	"includes": ["**/*.{ts,tsx,js,jsx,mjs,cjs,json,jsonc,md,mdx,css}"],
+	"excludes": [
+		"**/dist/**",
+		"**/node_modules/**",
+		"**/playwright-report/**",
+		"**/test-results/**"
+	],
+	"oxc": {
+		"associations": ["**/*.{ts,tsx,js,jsx,mjs,cjs}"],
+		"semicolons": "asNeeded",
+		"trailingCommas": "all"
+	},
+	"json": {
+		"associations": ["**/*.{json,jsonc}"]
+	},
+	"markdown": {
+		"associations": ["**/*.{md,mdx}"]
+	},
+	"malva": {
+		"associations": ["**/*.css"]
+	},
+	"plugins": [
+		"./node_modules/@dprint/oxc/plugin.wasm",
+		"./node_modules/@dprint/json/plugin.wasm",
+		"./node_modules/@dprint/markdown/plugin.wasm",
+		"./node_modules/dprint-plugin-malva/plugin.wasm"
+	]
+}

package/eslint.config.ts

@@ -0,0 +1,37 @@
+import * as tsParser from "@typescript-eslint/parser"
+import AtomIOPlugin from "@atom.io/eslint-plugin"
+import type { Linter } from "eslint"
+import LasertagPlugin from "lasertag/eslint-plugin"
+
+const ERROR = 2
+
+export default [
+	{ ignores: [`**/dist/**`, `**/node_modules/**`] },
+	{
+		files: [`**/*.ts`, `**/*.tsx`],
+		languageOptions: {
+			parser: tsParser,
+			parserOptions: { projectService: true, sourceType: `module` },
+		},
+		plugins: { "atom.io": AtomIOPlugin },
+		rules: {
+			"atom.io/exact-catch-types": ERROR,
+			"atom.io/explicit-state-types": [ERROR, { permitAnnotation: true }],
+			"atom.io/naming-convention": ERROR,
+			quotes: [ERROR, `backtick`],
+		},
+	},
+	{
+		files: [`src/**/*.tsx`],
+		plugins: { lasertag: LasertagPlugin },
+		rules: {
+			"lasertag/access-css-module-class-only": ERROR,
+			"lasertag/ban-div": ERROR,
+			"lasertag/export-own-component-only": ERROR,
+			"lasertag/header-main-footer-as-group": ERROR,
+			"lasertag/import-own-css-module-only": ERROR,
+			"lasertag/name-imported-css-module-as-css": ERROR,
+			"lasertag/render-tag-with-own-name": ERROR,
+		},
+	},
+] satisfies Linter.Config[]

package/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<meta name="description" content="Plane, a realtime vector editor built with Atom.io Mosaic Domains." />
+		<title>Plane · Shared vectors</title>
+	</head>
+	<body>
+		<main id="root"></main>
+		<script type="module" src="/src/main.tsx"></script>
+	</body>
+</html>

package/mise.toml

@@ -0,0 +1 @@
+[tools]

package/node/server.ts

@@ -0,0 +1,54 @@
+import { createServer } from "node:http"
+
+import { Server } from "socket.io"
+
+import { identityById } from "../src/identities.ts"
+import { createVectorCollaborationService } from "./service.ts"
+
+const PORT = 3000
+const collaboration = await createVectorCollaborationService()
+const httpServer = createServer((request, response) => {
+	if (request.url === `/health`) {
+		response.writeHead(200, { "content-type": `application/json` })
+		response.end(JSON.stringify({ ok: true, revision: collaboration.revision }))
+		return
+	}
+	response.writeHead(404)
+	response.end()
+})
+const socketServer = new Server(httpServer)
+
+socketServer.on(`connection`, (socket) => {
+	const requestedActor =
+		typeof socket.handshake.auth.actor === `string`
+			? socket.handshake.auth.actor
+			: undefined
+	const session =
+		typeof socket.handshake.auth.session === `string`
+			? socket.handshake.auth.session
+			: ``
+	const identity = identityById(requestedActor)
+	if (
+		identity.id !== requestedActor ||
+		session.length === 0 ||
+		session.includes(`::`)
+	) {
+		socket.disconnect(true)
+		return
+	}
+	void collaboration.bindSocket({ actor: identity.id, session, socket })
+})
+
+httpServer.listen(PORT, () => {
+	console.log(
+		`Vector collaboration server listening on http://localhost:${PORT}`,
+	)
+})
+
+const shutdown = (): void => {
+	collaboration[Symbol.dispose]()
+	void socketServer.close()
+	httpServer.close()
+}
+process.once(`SIGINT`, shutdown)
+process.once(`SIGTERM`, shutdown)

package/node/service.ts

@@ -0,0 +1,280 @@
+import { Silo } from "atom.io"
+import type { Json } from "atom.io/foundations/json"
+import type {
+	MosaicDomainBatchProposal,
+	MosaicDomainResidencyTransport,
+} from "@atom.io/realtime"
+import {
+	bindMosaicDomainHistoryServerSocket,
+	bindMosaicDomainPresenceServerSocket,
+	createMosaicDomainBatchServer,
+	createMosaicDomainCheckpointCoordinator,
+	createMosaicDomainHistoryCoordinator,
+	createMosaicDomainPresenceServer,
+	createMosaicDomainResidencyServer,
+	InMemoryMosaicDomainCheckpointStorage,
+	type MosaicDomainBatchAuthorizationContext,
+	type MosaicDomainBatchConnection,
+	type MosaicDomainCheckpointCoordinator,
+	type MosaicDomainCheckpointStorageAdapter,
+	type MosaicDomainHistoryCoordinator,
+} from "@atom.io/realtime/server"
+import type { Socket as ServerSocket } from "socket.io"
+
+import {
+	activateSvgContourDomain,
+	type SvgContourDomain,
+	type SvgContourStateAccess,
+} from "../src/design-model.ts"
+import {
+	VECTOR_BATCH_EVENTS,
+	VECTOR_RESIDENCY_EVENTS,
+	type VectorAcknowledgement,
+} from "../src/protocol.ts"
+
+export type VectorCollaborationService = Disposable & {
+	bindSocket(options: {
+		readonly actor: string
+		readonly session: string
+		readonly socket: ServerSocket
+	}): Promise<() => Promise<void>>
+	readonly checkpoints: MosaicDomainCheckpointCoordinator<
+		SvgContourDomain[`identity`]
+	>
+	readonly domain: SvgContourDomain
+	readonly history: MosaicDomainHistoryCoordinator<SvgContourDomain[`identity`]>
+	readonly revision: number
+}
+
+export async function createVectorCollaborationService(
+	options: {
+		readonly authorize?: (
+			context: MosaicDomainBatchAuthorizationContext,
+		) => boolean | Promise<boolean>
+		readonly silo?: Silo
+		readonly storage?: MosaicDomainCheckpointStorageAdapter
+	} = {},
+): Promise<VectorCollaborationService> {
+	const silo =
+		options.silo ??
+		new Silo({
+			name: `vector-collaboration-server`,
+			// Domain families acquire physical members from authenticated addresses.
+			lifespan: `ephemeral`,
+			isProduction: process.env.NODE_ENV === `production`,
+		})
+	const storage = options.storage ?? new InMemoryMosaicDomainCheckpointStorage()
+	const domain = await activateSvgContourDomain({
+		instance: `shared-drawing`,
+		silo,
+	})
+	const readState = silo.getState as SvgContourStateAccess[`getState`]
+	const batchServer = createMosaicDomainBatchServer({
+		...(options.authorize === undefined ? {} : { authorize: options.authorize }),
+		domain,
+		storage,
+	})
+	let history!: MosaicDomainHistoryCoordinator<SvgContourDomain[`identity`]>
+	const checkpoints = createMosaicDomainCheckpointCoordinator({
+		domain: domain.identity,
+		indexes: (context) => history.checkpoint.indexes(context),
+		readMember: async ({ address, revision }) => {
+			if (revision !== batchServer.revision) {
+				throw new Error(
+					`Plane checkpoints require a quiescent accepted revision.`,
+				)
+			}
+			const parsed = await domain.parseAddress(address)
+			const acquired = await domain.acquire(parsed)
+			return history.checkpoint.compactMember({
+				address,
+				revision,
+				value: readState(acquired.token) as Json.Serializable,
+			})
+		},
+		storage,
+	})
+	history = createMosaicDomainHistoryCoordinator({
+		batches: batchServer,
+		checkpoint: checkpoints,
+		domain,
+		storage,
+	})
+	const presenceServer = createMosaicDomainPresenceServer({ domain })
+	const residencyServer = createMosaicDomainResidencyServer({
+		batches: batchServer,
+		checkpoint: checkpoints,
+		domain,
+		maxResidentMembers: 512,
+	})
+	type VectorResidencyTransport = MosaicDomainResidencyTransport<
+		SvgContourDomain[`identity`]
+	>
+	const cleanups = new Set<() => Promise<void>>()
+	let disposed = false
+	let serial = Promise.resolve()
+	const exclusively = <Value>(work: () => Promise<Value>): Promise<Value> => {
+		const result = serial.then(work)
+		serial = result.then(
+			() => undefined,
+			() => undefined,
+		)
+		return result
+	}
+	const acknowledge = <Value>(
+		work: Promise<Value>,
+		respond: (acknowledgement: VectorAcknowledgement<Value>) => void,
+	): void => {
+		void work.then(
+			(value) => {
+				respond({ ok: true, value })
+			},
+			(error: unknown) => {
+				respond({
+					ok: false,
+					reason: error instanceof Error ? error.message : String(error),
+				})
+			},
+		)
+	}
+
+	return {
+		bindSocket({ actor, session, socket }) {
+			if (disposed) {
+				return Promise.reject(new Error(`The vector service is disposed.`))
+			}
+			const batch = batchServer.connect({ actor, session })
+			const presence = presenceServer.connect({ actor, session })
+			const residency = residencyServer.connect({ actor, session })
+			const unbindHistory = bindMosaicDomainHistoryServerSocket(
+				history.connect({ actor, session }),
+				socket,
+				{ session },
+			)
+			const unsubscribeBatch = batch.subscribe((accepted) => {
+				socket.emit(VECTOR_BATCH_EVENTS.accepted, accepted)
+			})
+			const residencySubscriptions = new Map<string, () => void>()
+			const unbindPresence = bindMosaicDomainPresenceServerSocket(
+				presence,
+				socket,
+			)
+			const onPropose = (
+				proposal: MosaicDomainBatchProposal,
+				respond: (
+					acknowledgement: VectorAcknowledgement<
+						Awaited<ReturnType<MosaicDomainBatchConnection[`propose`]>>
+					>,
+				) => void,
+			): void => {
+				acknowledge(
+					exclusively(() => batch.propose(proposal)),
+					respond,
+				)
+			}
+			const onRecover = (
+				afterRevision: number,
+				respond: (
+					acknowledgement: VectorAcknowledgement<
+						Awaited<ReturnType<MosaicDomainBatchConnection[`recover`]>>
+					>,
+				) => void,
+			): void => {
+				acknowledge(batch.recover(afterRevision), respond)
+			}
+			const onResidencyHydrate = (
+				requests: unknown,
+				respond: (
+					acknowledgement: VectorAcknowledgement<
+						Awaited<ReturnType<VectorResidencyTransport[`hydrate`]>>
+					>,
+				) => void,
+			): void => {
+				acknowledge(residency.hydrate(requests as never), respond)
+			}
+			const onResidencyPropose = (
+				proposal: unknown,
+				respond: (
+					acknowledgement: VectorAcknowledgement<
+						Awaited<ReturnType<VectorResidencyTransport[`propose`]>>
+					>,
+				) => void,
+			): void => {
+				acknowledge(residency.propose(proposal as never), respond)
+			}
+			const onResidencySubscribe = (
+				id: string,
+				requests: unknown,
+				respond: (acknowledgement: VectorAcknowledgement<void>) => void,
+			): void => {
+				acknowledge(
+					Promise.resolve(
+						residency.subscribe(requests as never, (accepted) => {
+							socket.emit(VECTOR_RESIDENCY_EVENTS.accepted, id, accepted)
+						}),
+					).then((stop) => {
+						residencySubscriptions.get(id)?.()
+						residencySubscriptions.set(id, stop)
+					}),
+					respond,
+				)
+			}
+			const onResidencyUnsubscribe = (id: string): void => {
+				residencySubscriptions.get(id)?.()
+				residencySubscriptions.delete(id)
+			}
+			socket.on(VECTOR_BATCH_EVENTS.propose, onPropose)
+			socket.on(VECTOR_BATCH_EVENTS.recover, onRecover)
+			socket.on(VECTOR_RESIDENCY_EVENTS.hydrate, onResidencyHydrate)
+			socket.on(VECTOR_RESIDENCY_EVENTS.propose, onResidencyPropose)
+			socket.on(VECTOR_RESIDENCY_EVENTS.subscribe, onResidencySubscribe)
+			socket.on(VECTOR_RESIDENCY_EVENTS.unsubscribe, onResidencyUnsubscribe)
+			let cleaned = false
+			const cleanup = async (): Promise<void> => {
+				if (cleaned) return
+				cleaned = true
+				socket.off(VECTOR_BATCH_EVENTS.propose, onPropose)
+				socket.off(VECTOR_BATCH_EVENTS.recover, onRecover)
+				socket.off(`disconnect`, onDisconnect)
+				unsubscribeBatch()
+				for (const stop of residencySubscriptions.values()) stop()
+				residencySubscriptions.clear()
+				socket.off(VECTOR_RESIDENCY_EVENTS.hydrate, onResidencyHydrate)
+				socket.off(VECTOR_RESIDENCY_EVENTS.propose, onResidencyPropose)
+				socket.off(VECTOR_RESIDENCY_EVENTS.subscribe, onResidencySubscribe)
+				socket.off(VECTOR_RESIDENCY_EVENTS.unsubscribe, onResidencyUnsubscribe)
+				await Promise.resolve(residency.dispose?.()).catch(() => undefined)
+				unbindHistory()
+				await unbindPresence()
+				cleanups.delete(cleanup)
+			}
+			const onDisconnect = (): void => {
+				void cleanup().catch(() => undefined)
+			}
+			socket.on(`disconnect`, onDisconnect)
+			cleanups.add(cleanup)
+			return Promise.resolve(cleanup)
+		},
+		checkpoints: {
+			checkpoint: () => exclusively(() => checkpoints.checkpoint()),
+			readIndex: checkpoints.readIndex,
+			recover: checkpoints.recover,
+		},
+		domain,
+		history,
+		get revision() {
+			return batchServer.revision
+		},
+		[Symbol.dispose]() {
+			if (disposed) return
+			disposed = true
+			for (const cleanup of cleanups) void cleanup().catch(() => undefined)
+			cleanups.clear()
+			presenceServer[Symbol.dispose]()
+			residencyServer[Symbol.dispose]()
+			history[Symbol.dispose]()
+			batchServer.dispose()
+			domain[Symbol.dispose]()
+		},
+	}
+}

package/package.json

@@ -1,6 +1,68 @@
 {
-  "name": "@atom.io/template-preact-realtime-vector-editor",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@atom.io/template-preact-realtime-vector-editor",
+	"version": "0.0.0",
+	"description": "A realtime collaborative vector editor built with Atom.io Mosaic Domains and Preact.",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/jeremybanka/atom.io.git",
+		"directory": "templates/preact-realtime-vector-editor"
+	},
+	"license": "Apache-2.0",
+	"type": "module",
+	"scripts": {
+		"dev": "concurrently vite \"node --watch node/server.ts\"",
+		"build": "tsc -b && vite build",
+		"fmt": "dprint fmt .",
+		"fmt:check": "dprint check .",
+		"lint": "npm run lint:eslint && npm run lint:oxlint && npm run lint:lasertag && npm run lint:types",
+		"lint:eslint": "eslint --max-warnings 0 .",
+		"lint:lasertag": "lasertag check \"src/**/*.module.css\"",
+		"lint:oxlint": "oxlint --deny-warnings .",
+		"lint:types": "tsc -b",
+		"preview": "concurrently \"vite preview\" \"node node/server.ts\"",
+		"test": "vitest run",
+		"test:once": "vitest run"
+	},
+	"dependencies": {
+		"@atom.io/react": "workspace:*",
+		"@atom.io/realtime": "workspace:*",
+		"@atom.io/template-preact-svg-editor": "workspace:*",
+		"atom.io": "workspace:*",
+		"preact": "11.0.1",
+		"socket.io": "4.8.4",
+		"socket.io-client": "4.8.4"
+	},
+	"devDependencies": {
+		"@atom.io/eslint-plugin": "workspace:*",
+		"@dprint/json": "0.25.2",
+		"@dprint/markdown": "0.27.1",
+		"@dprint/oxc": "0.47.0",
+		"@preact/preset-vite": "2.10.6",
+		"@testing-library/dom": "10.4.2",
+		"@testing-library/react": "16.3.3",
+		"@types/node": "26.6.5",
+		"@types/react": "19.3.0",
+		"@types/react-dom": "19.3.0",
+		"@typescript-eslint/parser": "8.72.0",
+		"@typescript/native": "npm:typescript@7.0.2",
+		"concurrently": "10.0.6",
+		"dprint": "0.64.1",
+		"dprint-plugin-malva": "0.16.0",
+		"eslint": "10.13.0",
+		"happy-dom": "21.0.4",
+		"lasertag": "0.8.8",
+		"oxlint": "1.89.0",
+		"oxlint-tsgolint": "7.0.2004",
+		"react": "19.3.1",
+		"react-dom": "19.3.1",
+		"typescript": "npm:@typescript/typescript6@6.0.2",
+		"vite": "8.3.5",
+		"vitest": "5.0.5"
+	},
+	"engines": {
+		"node": ">=24.12.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}