@graview/core 0.1.0 → 0.1.2

package/dist/persistence/sqlite.js

@@ -1,3 +1,5 @@
+import { createSqlAdapter } from "./sql.js";
+export { createSqlAdapter } from "./sql.js";
 /**
  * The Drizzle/SQLite table shapes this adapter reads and writes, for an app
  * that wants to declare them in its own Drizzle schema:
@@ -25,107 +27,41 @@ export const SQLITE_TABLE_SHAPE = {
 };
 /**
  * Reads and writes an app's existing `graph_nodes` / `graph_edges` tables —
- * the shape the household example already stores. `data` is schemaless JSON on disk and
- * becomes a typed node on the way in, validated by the schema registry when
- * the snapshot is loaded into a Graph.
+ * the shape the household example already stores — through better-sqlite3.
+ * The SQL adapter over `sqlFromDatabase(database)`: one implementation, so
+ * what holds here holds over a Durable Object's storage too (FR-09).
  */
 export function createSqliteAdapter(options) {
-    const db = options.database;
-    const nodeTable = options.nodeTable ?? "graph_nodes";
-    const edgeTable = options.edgeTable ?? "graph_edges";
-    const opTable = options.opTable ?? "graview_ops";
-    const scope = options.scopeColumn ?? "household_id";
-    if (options.createTables) {
-        db.exec(`
-      CREATE TABLE IF NOT EXISTS ${nodeTable} (
-        ${scope} TEXT NOT NULL, id TEXT NOT NULL,
-        kind TEXT NOT NULL, data TEXT NOT NULL,
-        PRIMARY KEY (${scope}, id)
-      );
-      CREATE TABLE IF NOT EXISTS ${edgeTable} (
-        ${scope} TEXT NOT NULL, position INTEGER NOT NULL,
-        kind TEXT NOT NULL, from_id TEXT NOT NULL, to_id TEXT NOT NULL,
-        PRIMARY KEY (${scope}, position)
-      );
-      CREATE TABLE IF NOT EXISTS ${opTable} (
-        ${scope} TEXT NOT NULL, seq INTEGER NOT NULL, data TEXT NOT NULL,
-        PRIMARY KEY (${scope}, seq)
-      );
-    `);
-    }
-    const selectNodes = db.prepare(`SELECT id, kind, data FROM ${nodeTable} WHERE ${scope} = ?`);
-    const selectEdges = db.prepare(`SELECT kind, from_id, to_id FROM ${edgeTable} WHERE ${scope} = ? ORDER BY position ASC`);
-    const deleteNodes = db.prepare(`DELETE FROM ${nodeTable} WHERE ${scope} = ?`);
-    const deleteEdges = db.prepare(`DELETE FROM ${edgeTable} WHERE ${scope} = ?`);
-    const insertNode = db.prepare(`INSERT INTO ${nodeTable} (${scope}, id, kind, data) VALUES (?, ?, ?, ?)`);
-    const insertEdge = db.prepare(`INSERT INTO ${edgeTable} (${scope}, position, kind, from_id, to_id) VALUES (?, ?, ?, ?, ?)`);
-    /**
-     * The op table is the framework's own, not the app's, so it is created on
-     * demand. The node and edge tables are the app's and are never touched
-     * unless `createTables` explicitly asks for them.
-     */
-    let opTableReady = false;
-    function ensureOpTable() {
-        if (opTableReady)
-            return;
-        db.exec(`CREATE TABLE IF NOT EXISTS ${opTable} (
-         ${scope} TEXT NOT NULL, seq INTEGER NOT NULL, data TEXT NOT NULL,
-         PRIMARY KEY (${scope}, seq)
-       )`);
-        opTableReady = true;
-    }
-    const write = db.transaction(((key, snapshot) => {
-        deleteEdges.run(key);
-        deleteNodes.run(key);
-        for (const node of snapshot.nodes) {
-            insertNode.run(key, node.id, node.kind, JSON.stringify(node));
+    const { database, ...tables } = options;
+    return createSqlAdapter({ ...sqlFromDatabase(database), ...tables });
+}
+/**
+ * better-sqlite3 as the SQL adapter's `exec`, with its own transaction.
+ * Each statement is prepared once and kept, and a statement that reads
+ * nothing is `run` rather than asked for rows (better-sqlite3 refuses that).
+ */
+export function sqlFromDatabase(database) {
+    const prepared = new Map();
+    const statement = (sql) => {
+        let found = prepared.get(sql);
+        if (!found) {
+            found = database.prepare(sql);
+            prepared.set(sql, found);
         }
-        snapshot.edges.forEach((edge, position) => {
-            insertEdge.run(key, position, edge.kind, edge.from, edge.to);
-        });
-    }));
+        return found;
+    };
     return {
-        name: "sqlite",
-        async load(key) {
-            const nodeRows = selectNodes.all(key);
-            if (nodeRows.length === 0)
-                return null;
-            const edgeRows = selectEdges.all(key);
-            const nodes = nodeRows.map((row) => {
-                const parsed = JSON.parse(row.data);
-                // `id` and `kind` live in columns as well as the JSON blob; the
-                // columns win so a row is never internally inconsistent.
-                return { ...parsed, id: row.id, kind: row.kind };
-            });
-            const edges = edgeRows.map((row) => ({
-                kind: row.kind,
-                from: row.from_id,
-                to: row.to_id,
-            }));
-            return { nodes, edges };
-        },
-        async save(key, snapshot) {
-            write(key, snapshot);
-        },
-        async delete(key) {
-            deleteEdges.run(key);
-            deleteNodes.run(key);
-        },
-        async loadLog(key) {
-            ensureOpTable();
-            const rows = db
-                .prepare(`SELECT data FROM ${opTable} WHERE ${scope} = ? ORDER BY seq ASC`)
-                .all(key);
-            return rows.map((row) => JSON.parse(row.data));
-        },
-        async appendOps(key, ops) {
-            if (ops.length === 0)
-                return;
-            ensureOpTable();
-            const insert = db.prepare(`INSERT OR REPLACE INTO ${opTable} (${scope}, seq, data) VALUES (?, ?, ?)`);
-            for (const op of ops)
-                insert.run(key, op.seq, JSON.stringify(op));
+        sql: {
+            exec(sql, ...params) {
+                const prepared = statement(sql);
+                const reads = prepared.reader ?? /^\s*(SELECT|WITH|PRAGMA|VALUES)\b/i.test(sql);
+                if (reads)
+                    return prepared.all(...params);
+                prepared.run(...params);
+                return [];
+            },
         },
+        transaction: (fn) => database.transaction(fn)(),
     };
 }
 //# sourceMappingURL=sqlite.js.map

package/dist/persistence/sqlite.js.map

@@ -1 +1 @@
-{"version":3,"file":"sqlite.js","sourceRoot":"","sources":["../../src/persistence/sqlite.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sqlite.js","sourceRoot":"","sources":["../../src/persistence/sqlite.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAgB,MAAM,UAAU,CAAC;AAG1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAgC5C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,KAAK,EAAE,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC;IACtC,KAAK,EAAE,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC;CAChD,CAAC;AAEX;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAA6B;IAC/D,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC;IACxC,OAAO,gBAAgB,CAAC,EAAE,GAAG,eAAe,CAAC,QAAQ,CAAC,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;AACvE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,QAAwB;IACtD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA2B,CAAC;IACpD,MAAM,SAAS,GAAG,CAAC,GAAW,EAAmB,EAAE;QACjD,IAAI,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAC9B,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC3B,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;IACF,OAAO;QACL,GAAG,EAAE;YACH,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM;gBACjB,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;gBAChC,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,IAAI,oCAAoC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBAChF,IAAI,KAAK;oBAAE,OAAO,QAAQ,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC;gBAC1C,QAAQ,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC;gBACxB,OAAO,EAAE,CAAC;YACZ,CAAC;SACF;QACD,WAAW,EAAE,CAAI,EAAW,EAAK,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAa,CAAC,EAAO;KAC/E,CAAC;AACJ,CAAC"}

package/dist/persistence/types.d.ts

@@ -1,4 +1,5 @@
 import type { GraphSnapshot } from "../graph/types.js";
+import type { Epoch, LogArchive } from "../ops/log.js";
 import type { Operation } from "../ops/types.js";
 /**
  * The framework owns the reactive graph, invariants, diff and undo;
@@ -18,5 +19,23 @@ export interface PersistenceAdapter<Scope = string> {
     /** Optional: adapters that keep history append the log too. */
     loadLog?(scope: Scope): Promise<Operation[]>;
     appendOps?(scope: Scope, ops: readonly Operation[]): Promise<void>;
+    /**
+     * Optional: the epochs the log folds from (FR-27), kept beside it. An
+     * adapter without them reopens a store with none recorded, and ship has
+     * it adopt what it holds as its first epoch on each open.
+     */
+    loadEpochs?(scope: Scope): Promise<Epoch[]>;
+    saveEpochs?(scope: Scope, epochs: readonly Epoch[]): Promise<void>;
+    /**
+     * Optional (FR-23): compaction behind an undo horizon. Moves the ops
+     * before `checkpoint.seq`, and the epochs before it, into the archive,
+     * and makes `checkpoint` the first epoch. From then on `loadLog` returns
+     * the ops from its seq on and `loadEpochs` the checkpoint and what came
+     * after it, so a normal open loads nothing older; `loadArchive` returns
+     * what was moved, oldest first, for a full export. Nothing is deleted.
+     * An adapter that keeps no epochs keeps no checkpoint, and has neither.
+     */
+    compact?(scope: Scope, checkpoint: Epoch): Promise<void>;
+    loadArchive?(scope: Scope): Promise<LogArchive>;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/persistence/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/persistence/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;GAIG;AACH,MAAM,WAAW,kBAAkB,CAAC,KAAK,GAAG,MAAM;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IAClD,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,+DAA+D;IAC/D,OAAO,CAAC,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IAC7C,SAAS,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,SAAS,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpE"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/persistence/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;GAIG;AACH,MAAM,WAAW,kBAAkB,CAAC,KAAK,GAAG,MAAM;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IAClD,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,+DAA+D;IAC/D,OAAO,CAAC,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IAC7C,SAAS,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,SAAS,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnE;;;;OAIG;IACH,UAAU,CAAC,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IAC5C,UAAU,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,KAAK,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnE;;;;;;;;OAQG;IACH,OAAO,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,WAAW,CAAC,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACjD"}

package/dist/presence.d.ts

@@ -28,6 +28,37 @@ export interface PresenceChannel {
 }
 /** How long a presence stands after its last word: three missed heartbeats at the poll's own pace. */
 export declare const PRESENCE_TTL_MS = 2500;
+/**
+ * HOW LONG A PRESENCE FROM SOMEWHERE ELSE STANDS (FR-13). A list that came
+ * over a wire was stamped by a server's clock and read by a browser's, and
+ * it arrives at the poll's pace rather than the heartbeat's, so it is given
+ * four times a tab's own grace. Past it a participant is gone whether or
+ * not the channel ever said so: a host's channel that forgets to drop
+ * somebody does not keep them on the map.
+ */
+export declare const REMOTE_PRESENCE_TTL_MS: number;
+/** The parts of a participant key: who, and which tab of theirs. */
+export interface Participant {
+    readonly kind: "human" | "agent" | "rule" | "system";
+    readonly id?: string;
+    readonly session?: string;
+}
+/**
+ * THE ONE DIALECT. A participant is `kind:id:session`: the op log's own
+ * reading of an author (`Author.kind`, `.id`, `.session`), a figure's key on
+ * the map, and what the wire's presence routes carry, so a figure and its
+ * edits are the same person by construction. A host that says who is here
+ * from its own server writes this, and only this.
+ */
+export declare function participantKey(participant: Participant): string;
+/**
+ * A participant key read back. The kind is everything before the first
+ * colon and the session everything after the last, so an id that holds a
+ * colon (`mcp:claude`) survives. Null for anything that is not a key.
+ */
+export declare function parseParticipant(key: string): (Participant & {
+    readonly session: string;
+}) | null;
 /**
  * The others as they are now: what arrived, minus what has gone quiet, minus
  * yourself. Pure, so a test can ask what a viewer sees without a channel.

package/dist/presence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"presence.d.ts","sourceRoot":"","sources":["../src/presence.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,aAAa;IAC5B,gFAAgF;IAChF,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,QAAQ;IACvB,kGAAkG;IAClG,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2FAA2F;IAC3F,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,sDAAsD;IACtD,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;IAC/B,mCAAmC;IACnC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,IAAI,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC/B,yFAAyF;IACzF,KAAK,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,SAAS,QAAQ,EAAE,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAChE,mCAAmC;IACnC,KAAK,IAAI,IAAI,CAAC;CACf;AAED,sGAAsG;AACtG,eAAO,MAAM,eAAe,OAAO,CAAC;AAEpC;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,EACpC,OAAO,EAAE,SAAS,QAAQ,EAAE,EAC5B,GAAG,EAAE,MAAM,EACX,KAAK,GAAE,MAAwB,EAC/B,IAAI,CAAC,EAAE,MAAM,GACZ,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAevB;AAED,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,CAAC,EAAE,QAAQ,GAAG,SAAS,EAAE,CAAC,EAAE,QAAQ,GAAG,SAAS,GAAG,OAAO,CAWtF"}
+{"version":3,"file":"presence.d.ts","sourceRoot":"","sources":["../src/presence.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,aAAa;IAC5B,gFAAgF;IAChF,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,QAAQ;IACvB,kGAAkG;IAClG,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2FAA2F;IAC3F,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,sDAAsD;IACtD,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;IAC/B,mCAAmC;IACnC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,IAAI,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC/B,yFAAyF;IACzF,KAAK,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,SAAS,QAAQ,EAAE,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAChE,mCAAmC;IACnC,KAAK,IAAI,IAAI,CAAC;CACf;AAED,sGAAsG;AACtG,eAAO,MAAM,eAAe,OAAO,CAAC;AAEpC;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,QAAsB,CAAC;AAE1D,oEAAoE;AACpE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;IACrD,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAID;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,CAE/D;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,WAAW,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,IAAI,CAQjG;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,EACpC,OAAO,EAAE,SAAS,QAAQ,EAAE,EAC5B,GAAG,EAAE,MAAM,EACX,KAAK,GAAE,MAAwB,EAC/B,IAAI,CAAC,EAAE,MAAM,GACZ,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAevB;AAED,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,CAAC,EAAE,QAAQ,GAAG,SAAS,EAAE,CAAC,EAAE,QAAQ,GAAG,SAAS,GAAG,OAAO,CAWtF"}

package/dist/presence.js

@@ -12,6 +12,42 @@
  */
 /** How long a presence stands after its last word: three missed heartbeats at the poll's own pace. */
 export const PRESENCE_TTL_MS = 2500;
+/**
+ * HOW LONG A PRESENCE FROM SOMEWHERE ELSE STANDS (FR-13). A list that came
+ * over a wire was stamped by a server's clock and read by a browser's, and
+ * it arrives at the poll's pace rather than the heartbeat's, so it is given
+ * four times a tab's own grace. Past it a participant is gone whether or
+ * not the channel ever said so: a host's channel that forgets to drop
+ * somebody does not keep them on the map.
+ */
+export const REMOTE_PRESENCE_TTL_MS = PRESENCE_TTL_MS * 4;
+const PARTICIPANT_KINDS = new Set(["human", "agent", "rule", "system"]);
+/**
+ * THE ONE DIALECT. A participant is `kind:id:session`: the op log's own
+ * reading of an author (`Author.kind`, `.id`, `.session`), a figure's key on
+ * the map, and what the wire's presence routes carry, so a figure and its
+ * edits are the same person by construction. A host that says who is here
+ * from its own server writes this, and only this.
+ */
+export function participantKey(participant) {
+    return `${participant.kind}:${participant.id ?? ""}:${participant.session ?? ""}`;
+}
+/**
+ * A participant key read back. The kind is everything before the first
+ * colon and the session everything after the last, so an id that holds a
+ * colon (`mcp:claude`) survives. Null for anything that is not a key.
+ */
+export function parseParticipant(key) {
+    const first = key.indexOf(":");
+    const last = key.lastIndexOf(":");
+    if (first < 0 || last === first)
+        return null;
+    const kind = key.slice(0, first);
+    if (!PARTICIPANT_KINDS.has(kind))
+        return null;
+    const id = key.slice(first + 1, last);
+    return { kind: kind, ...(id ? { id } : {}), session: key.slice(last + 1) };
+}
 /**
  * The others as they are now: what arrived, minus what has gone quiet, minus
  * yourself. Pure, so a test can ask what a viewer sees without a channel.

package/dist/presence.js.map

@@ -1 +1 @@
-{"version":3,"file":"presence.js","sourceRoot":"","sources":["../src/presence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAiCH,sGAAsG;AACtG,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC;AAEpC;;;GAGG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAoC,EACpC,OAA4B,EAC5B,GAAW,EACX,QAAgB,eAAe,EAC/B,IAAa;IAEb,MAAM,IAAI,GAAG,IAAI,GAAG,EAAoB,CAAC;IACzC,KAAK,MAAM,CAAC,WAAW,EAAE,QAAQ,CAAC,IAAI,KAAK,EAAE,CAAC;QAC5C,IAAI,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,GAAG,KAAK;YAAE,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IAC7E,CAAC;IACD,KAAK,MAAM,QAAQ,IAAI,OAAO,EAAE,CAAC;QAC/B,IAAI,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC;YAC3C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;YAClC,SAAS;QACX,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;QAC5C,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;YAAE,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IACxG,CAAC;IACD,IAAI,IAAI,KAAK,SAAS;QAAE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC1C,OAAO,IAAI,CAAC;AACd,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,YAAY,CAAC,CAAuB,EAAE,CAAuB;IAC3E,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;QAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAC7B,OAAO,CACL,CAAC,CAAC,WAAW,KAAK,CAAC,CAAC,WAAW;QAC/B,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI;QACjB,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG;QACf,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI;QACjB,CAAC,CAAC,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,IAAI,CAAC;QACrC,CAAC,CAAC,CAAC,KAAK,EAAE,EAAE,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,EAAE,EAAE,IAAI,IAAI,CAAC;QAC/C,CAAC,CAAC,CAAC,KAAK,EAAE,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,EAAE,IAAI,IAAI,IAAI,CAAC,CACpD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"presence.js","sourceRoot":"","sources":["../src/presence.ts"],"names":[],"mappings":"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"}

package/dist/scaffold/from-template.d.ts

@@ -0,0 +1,16 @@
+import type { GraviewTemplate } from "../document/graview-template.js";
+import { type Ids } from "./names.js";
+/** The kind a project's UI leads with, and the act its seat is gated on: the first kind something creates. */
+export declare function templateKind(template: GraviewTemplate): {
+    readonly kind: string;
+    readonly plural: string;
+    readonly gate: string;
+};
+export declare function documentJson(template: GraviewTemplate): string;
+export declare function templateJson(template: GraviewTemplate): string;
+export declare function documentAppTs(ids: Ids): string;
+export declare function documentSchemaTs(ids: Ids): string;
+export declare function documentBrandTs(ids: Ids): string;
+export declare function documentTest(ids: Ids): string;
+export declare function documentReadmeLayout(ids: Ids, run: string): string;
+//# sourceMappingURL=from-template.d.ts.map

package/dist/scaffold/from-template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"from-template.d.ts","sourceRoot":"","sources":["../../src/scaffold/from-template.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AACvE,OAAO,EAAE,KAAK,GAAG,EAAyB,MAAM,YAAY,CAAC;AAmB7D,8GAA8G;AAC9G,wBAAgB,YAAY,CAAC,QAAQ,EAAE,eAAe,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAQjI;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,CAE9D;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,CAE9D;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAkC9C;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAOjD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAiBhD;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CA+C7C;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAalE"}

package/dist/scaffold/from-template.js

@@ -0,0 +1,157 @@
+import { escapeString, slugify } from "./names.js";
+/*
+ * A PROJECT FROM A TEMPLATE (FR-08): the same checkout `graview create`
+ * always writes, with the declaration KEPT AS THE DOCUMENT.
+ *
+ * `src/domain/app.json` is the template's document, and `src/domain/app.ts`
+ * compiles it with `compileDocument` when the domain loads. The other choice
+ * — writing TypeScript from the document — would need a generator for every
+ * construct the document has (expression rules, effects, guards, refusal
+ * sentences, view specs) and would then be a second declaration that could
+ * drift from the first. Kept as the document, the project IS the template's
+ * app: `graview describe` says the same of both by construction, the studio
+ * and `editDocument` change it as data, and a template shared back out is the
+ * file as it stands. The UI, the tests, the CI and the scripts are the ones
+ * every project gets; the template itself sits at the root as
+ * `template.json`, for `graview apply --template` to set a store up from.
+ */
+/** The kind a project's UI leads with, and the act its seat is gated on: the first kind something creates. */
+export function templateKind(template) {
+    const document = template.document;
+    const kinds = Object.keys(document.kinds ?? {});
+    const acts = Object.entries(document.acts ?? {});
+    const creating = kinds.map((kind) => [kind, acts.find(([, act]) => act.creates === kind)?.[0]]).find(([, act]) => act !== undefined);
+    const kind = creating?.[0] ?? kinds[0] ?? "item";
+    const plural = slugify(document.kinds?.[kind]?.plural ?? `${kind}s`) || `${kind}s`;
+    return { kind, plural, gate: creating?.[1] ?? acts[0]?.[0] ?? `add-${kind}` };
+}
+export function documentJson(template) {
+    return `${JSON.stringify(template.document, null, 2)}\n`;
+}
+export function templateJson(template) {
+    return `${JSON.stringify(template, null, 2)}\n`;
+}
+export function documentAppTs(ids) {
+    return `import { Store, type AnySchema, type GraviewApp, type StoreOptions } from "@graview/core";
+import { compileDocument, sayFindings } from "@graview/core/document";
+import document from "./app.json" with { type: "json" };
+
+/**
+ * THE DECLARATION IS A DOCUMENT: app.json, compiled when this module loads.
+ * It runs no code of its own, so it is the same app here, in a host that
+ * accepts documents from strangers, and in the template it came from.
+ * \`graview check\` and \`graview describe\` read it through this module or
+ * straight from the file; edit it, or open it in the studio, and the
+ * compiler says what is wrong with the JSON path to fix it at.
+ */
+const compiled = compileDocument(document);
+if (!compiled.ok) {
+  throw new Error(\`src/domain/app.json does not compile:\\n\${sayFindings(compiled.findings)}\`);
+}
+
+export const ${ids.appVar}: GraviewApp = compiled.app;
+
+export type ${ids.StoreType} = Store<AnySchema>;
+
+export function createStore(options: Partial<StoreOptions<AnySchema>> = {}): ${ids.StoreType} {
+  return new Store<AnySchema>({
+    schema: ${ids.appVar}.schema,
+    mutations: ${ids.appVar}.mutations ?? [],
+    invariants: ${ids.appVar}.invariants ?? [],
+    ...(${ids.appVar}.policy ? { policy: ${ids.appVar}.policy } : {}),
+    ...options,
+  });
+}
+
+export default ${ids.appVar};
+`;
+}
+export function documentSchemaTs(ids) {
+    return `import { ${ids.appVar} } from "./app.js";
+
+/** The schema the document compiles to, under the name the UI imports it by. */
+export const ${ids.schemaVar} = ${ids.appVar}.schema;
+export type ${ids.SchemaType} = typeof ${ids.schemaVar};
+`;
+}
+export function documentBrandTs(ids) {
+    return `import { brandFromAccent, DARK, LIGHT, type Brand } from "@graview/core";
+import { ${ids.appVar} } from "./app.js";
+
+/**
+ * The document's brand when it declares one (\`brand.accent\` in app.json);
+ * otherwise both schemes derived from one accent, measured against AA.
+ */
+function brandOf(): Brand {
+  if (${ids.appVar}.brand) return ${ids.appVar}.brand;
+  const derived = brandFromAccent({ accent: "${ids.accent}", base: { dark: DARK, light: LIGHT } });
+  if (!derived.ok) throw new Error(\`${escapeString(ids.name)} cannot be derived from ${ids.accent}: \${derived.why}\`);
+  return { name: ${ids.appVar}.name, schemes: derived.schemes };
+}
+
+export const ${ids.brandVar}: Brand = brandOf();
+`;
+}
+export function documentTest(ids) {
+    return `import { checkApp, type Principal } from "@graview/core";
+import { instantiateTemplate } from "@graview/core/document";
+import { describe, expect, it } from "vitest";
+import template from "../template.json" with { type: "json" };
+import document from "../src/domain/app.json" with { type: "json" };
+import { ${ids.appVar}, createStore } from "../src/domain/app.js";
+
+/**
+ * The domain tier has no DOM in it, so these run headless. The declaration
+ * is the template's document until you change it; the setup test holds the
+ * template's own acts to the document as it stands.
+ */
+
+describe("the declaration", () => {
+  it("passes its own check", () => {
+    const result = checkApp(${ids.appVar});
+    expect(result.findings.filter((f) => f.severity === "error")).toEqual([]);
+    expect(result.ok).toBe(true);
+  });
+
+  it("compiles from the document it keeps", () => {
+    expect(${ids.appVar}.name).toBe(document.name);
+  });
+});
+
+describe("the template's setup", () => {
+  const setUp = () => {
+    const made = instantiateTemplate({ ...template, document });
+    if (!made.ok) throw new Error(made.findings.map((f) => \`\${f.path}: \${f.message}\`).join("\\n"));
+    return made;
+  };
+
+  it("runs as one batch, and one undo takes it back", () => {
+    const store = createStore();
+    const author: Principal = { kind: "system", id: "template:${escapeString(ids.packageName)}" };
+    const calls = setUp().setup;
+    if (calls.length === 0) return;
+    for (const call of calls) {
+      store.apply({ name: call.name, args: call.args }, { author, batch: "setup", intent: call.intent });
+    }
+    expect(new Set(store.log.all().map((op) => op.batch))).toEqual(new Set(["setup"]));
+    store.undo("setup", { author });
+    expect(store.graph.allNodes()).toEqual([]);
+  });
+});
+`;
+}
+export function documentReadmeLayout(ids, run) {
+    return `src/domain/      the declaration — no React in here; this is what graview check reads
+  app.json       the declaration document: kinds, acts, rules, policy, brand, views
+  app.ts         compiles app.json with compileDocument; createStore
+  schema.ts      the compiled schema, under the name the UI imports
+  brand.ts       the document's brand, or one derived from an accent
+src/ui/
+  views.tsx      registerDefaultViews, then your own where the generic one is wrong
+  app.tsx        the provider, the Shell primitive, and a seat — under sixty lines
+  pages.tsx      the ${ids.kind}'s page on the routed face, in your words, over the derived ones
+src/main.tsx     the theme, the store that remembers, the two faces
+template.json    the template this project was made from: \`${run} apply-template\` sets a store up from it
+tests/           the declaration checks clean, and the template's setup runs as one undoable batch`;
+}
+//# sourceMappingURL=from-template.js.map

package/dist/scaffold/from-template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"from-template.js","sourceRoot":"","sources":["../../src/scaffold/from-template.ts"],"names":[],"mappings":"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"}

package/dist/scaffold/index.d.ts

@@ -1,3 +1,4 @@
+import type { GraviewTemplate } from "../document/graview-template.js";
 export { pascal, slugify, titleCase, validateScaffoldOptions } from "./names.js";
 export { GRAVIEW_PACKAGES, LINKED_PACKAGES } from "./project.js";
 export interface ScaffoldOptions {
@@ -47,6 +48,14 @@ export interface ScaffoldOptions {
      * Two is a gap rather than a taste.
      */
     readonly workspace?: boolean;
+    /**
+     * A template made anywhere — Graview Cloud's shape (FR-08). The project
+     * keeps its document as the declaration (`src/domain/app.json`, compiled
+     * when the domain loads) and the template beside it as `template.json`,
+     * for `graview apply --template` to set a store up from. Read it with
+     * `readGraviewTemplate` first; this trusts what it is handed.
+     */
+    readonly template?: GraviewTemplate;
 }
 export interface ScaffoldFile {
     readonly path: string;
@@ -62,5 +71,5 @@ export interface Scaffold {
     readonly port: number;
     readonly linked: boolean;
 }
-export declare function scaffoldProject(options: ScaffoldOptions): Scaffold;
+export declare function scaffoldProject(given: ScaffoldOptions): Scaffold;
 //# sourceMappingURL=index.d.ts.map

package/dist/scaffold/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scaffold/index.ts"],"names":[],"mappings":"AAmCA,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AACjF,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEjE,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,iEAAiE;IACjE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACzC,6BAA6B;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,yCAAyC;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,KAAK,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAID,wBAAgB,eAAe,CAAC,OAAO,EAAE,eAAe,GAAG,QAAQ,CA6HlE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scaffold/index.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAEvE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AACjF,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEjE,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,iEAAiE;IACjE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACzC,6BAA6B;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,yCAAyC;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,eAAe,CAAC;CACrC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,KAAK,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAID,wBAAgB,eAAe,CAAC,KAAK,EAAE,eAAe,GAAG,QAAQ,CAyJhE"}

package/dist/scaffold/index.js

@@ -17,15 +17,26 @@ import { slugify, titleCase, camel, pascal, validateScaffoldOptions } from "./na
 import { SURVEY_SAYS, AUDIT_SAYS, A11Y_SAYS, harness, workspaceRoot, tsconfigBase, rootVitest, packageJson, tsconfig, tsconfigBuild, viteConfig, gitignore, readme, ciYml, } from "./project.js";
 import { schemaTs, mutationsTs, invariantsTs, brandTs, appTs, domainTest } from "./domain.js";
 import { indexHtml, embedHtml, embedTsx, viewsTsx, uiAppTsx, pagesTsx, mainTsx } from "./ui.js";
+import { documentAppTs, documentBrandTs, documentJson, documentSchemaTs, documentTest, templateJson, templateKind } from "./from-template.js";
 export { pascal, slugify, titleCase, validateScaffoldOptions } from "./names.js";
 export { GRAVIEW_PACKAGES, LINKED_PACKAGES } from "./project.js";
-export function scaffoldProject(options) {
+export function scaffoldProject(given) {
+    /*
+     * FROM A TEMPLATE, the kind the UI leads with is the template's first kind
+     * that something creates, and its seat is gated on that act — unless the
+     * caller named a kind of the document's itself.
+     */
+    const led = given.template ? templateKind(given.template) : undefined;
+    const options = led
+        ? { ...given, kind: given.kind ?? led.kind, plural: given.plural ?? (given.kind === undefined ? led.plural : `${given.kind}s`) }
+        : given;
     const problems = validateScaffoldOptions(options);
     if (problems.length > 0)
         throw new Error(problems.join("\n"));
     const name = options.name.trim();
     const kind = options.kind ?? "item";
     const plural = options.plural ?? `${kind}s`;
+    const template = options.template;
     const packageName = options.packageName ?? slugify(name);
     const packageManager = options.packageManager ?? "pnpm";
     const port = options.port ?? 5170;
@@ -77,7 +88,27 @@ export function scaffoldProject(options) {
         range,
         packageManager,
         packageName,
+        gate: led && given.kind === undefined ? led.gate : `add-${kind}`,
+        fromTemplate: template !== undefined,
     };
+    /*
+     * THE DECLARATION: TypeScript written for one kind, or — from a template —
+     * the template's document kept as the document (see ./from-template.ts).
+     */
+    const domain = template
+        ? [
+            { path: "src/domain/app.json", contents: documentJson(template) },
+            { path: "src/domain/app.ts", contents: documentAppTs(ids) },
+            { path: "src/domain/schema.ts", contents: documentSchemaTs(ids) },
+            { path: "src/domain/brand.ts", contents: documentBrandTs(ids) },
+        ]
+        : [
+            { path: "src/domain/schema.ts", contents: schemaTs(ids) },
+            { path: "src/domain/mutations.ts", contents: mutationsTs(ids) },
+            { path: "src/domain/invariants.ts", contents: invariantsTs(ids) },
+            { path: "src/domain/brand.ts", contents: brandTs(ids) },
+            { path: "src/domain/app.ts", contents: appTs(ids) },
+        ];
     const files = [
         { path: "package.json", contents: packageJson(ids, workspace) },
         { path: "tsconfig.json", contents: tsconfig(workspace) },
@@ -87,18 +118,15 @@ export function scaffoldProject(options) {
         { path: "embed.html", contents: embedHtml(ids) },
         { path: ".gitignore", contents: gitignore() },
         { path: "README.md", contents: readme(ids) },
-        { path: "src/domain/schema.ts", contents: schemaTs(ids) },
-        { path: "src/domain/mutations.ts", contents: mutationsTs(ids) },
-        { path: "src/domain/invariants.ts", contents: invariantsTs(ids) },
-        { path: "src/domain/brand.ts", contents: brandTs(ids) },
-        { path: "src/domain/app.ts", contents: appTs(ids) },
+        ...domain,
         { path: "src/ui/views.tsx", contents: viewsTsx(ids) },
         { path: "src/ui/app.tsx", contents: uiAppTsx(ids) },
         { path: "src/ui/pages.tsx", contents: pagesTsx(ids) },
         { path: "src/main.tsx", contents: mainTsx(ids) },
         { path: "src/embed.tsx", contents: embedTsx(ids) },
-        { path: "tests/domain.test.ts", contents: domainTest(ids) },
+        { path: "tests/domain.test.ts", contents: template ? documentTest(ids) : domainTest(ids) },
         { path: ".github/workflows/ci.yml", contents: ciYml(ids) },
+        ...(template ? [{ path: "template.json", contents: templateJson(template) }] : []),
     ];
     if (!workspace) {
         return { files, name, packageName, kind, plural, packageManager, port, linked: link !== undefined };