@tjakoen/grain 0.1.12

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.
Files changed (181) hide show
  1. package/LICENSE +202 -0
  2. package/PLAN.md +27 -0
  3. package/README.md +243 -0
  4. package/ai/accepts.test.ts +69 -0
  5. package/ai/accepts.ts +57 -0
  6. package/ai/ai.css +127 -0
  7. package/ai/client-door.test.ts +70 -0
  8. package/ai/client-door.ts +56 -0
  9. package/ai/contract.test.ts +158 -0
  10. package/ai/contract.ts +285 -0
  11. package/ai/interaction-layer.test.ts +270 -0
  12. package/ai/interaction-layer.ts +138 -0
  13. package/ai/manifest-dom.test.ts +176 -0
  14. package/ai/manifest-dom.ts +187 -0
  15. package/ai/manifest.test.ts +71 -0
  16. package/ai/manifest.ts +57 -0
  17. package/ai/markdown.test.ts +68 -0
  18. package/ai/markdown.ts +74 -0
  19. package/ai/model-chat.test.ts +131 -0
  20. package/ai/model-chat.ts +151 -0
  21. package/ai/model-reasoner.test.ts +152 -0
  22. package/ai/model-reasoner.ts +146 -0
  23. package/ai/model.test.ts +148 -0
  24. package/ai/model.ts +200 -0
  25. package/ai/reasoner-kit.test.ts +142 -0
  26. package/ai/reasoner-kit.ts +159 -0
  27. package/ai/reasoner.test.ts +227 -0
  28. package/ai/reasoner.ts +446 -0
  29. package/ai/timeline-log.test.ts +55 -0
  30. package/ai/timeline-log.ts +50 -0
  31. package/ai/vocab-reference.test.ts +43 -0
  32. package/ai/vocab-reference.ts +107 -0
  33. package/ai/webllm.test.ts +79 -0
  34. package/ai/webllm.ts +125 -0
  35. package/assets/figure-sample.svg +14 -0
  36. package/assets/sprite.svg +22 -0
  37. package/catalog/catalog.test.ts +37 -0
  38. package/catalog/catalog.ts +424 -0
  39. package/components/atoms/action-badge/action-badge.css +17 -0
  40. package/components/atoms/action-badge/action-badge.html +6 -0
  41. package/components/atoms/action-badge/action-badge.md +23 -0
  42. package/components/atoms/b-badge/b-badge.css +15 -0
  43. package/components/atoms/b-badge/b-badge.html +2 -0
  44. package/components/atoms/b-badge/b-badge.md +16 -0
  45. package/components/atoms/b-button/b-button.ai.md +22 -0
  46. package/components/atoms/b-button/b-button.css +87 -0
  47. package/components/atoms/b-button/b-button.html +5 -0
  48. package/components/atoms/b-button/b-button.md +77 -0
  49. package/components/atoms/b-icon/b-icon.css +10 -0
  50. package/components/atoms/b-icon/b-icon.html +5 -0
  51. package/components/atoms/b-icon/b-icon.md +36 -0
  52. package/components/atoms/b-icon-button/b-icon-button.ai.md +11 -0
  53. package/components/atoms/b-icon-button/b-icon-button.css +43 -0
  54. package/components/atoms/b-icon-button/b-icon-button.html +8 -0
  55. package/components/atoms/b-icon-button/b-icon-button.md +33 -0
  56. package/components/atoms/b-input/b-input.css +36 -0
  57. package/components/atoms/b-input/b-input.html +8 -0
  58. package/components/atoms/b-input/b-input.md +59 -0
  59. package/components/atoms/b-kbd/b-kbd.css +11 -0
  60. package/components/atoms/b-kbd/b-kbd.html +3 -0
  61. package/components/atoms/b-kbd/b-kbd.md +13 -0
  62. package/components/atoms/b-list/b-list.css +21 -0
  63. package/components/atoms/b-list/b-list.html +6 -0
  64. package/components/atoms/b-list/b-list.md +24 -0
  65. package/components/atoms/b-meter/b-meter.css +39 -0
  66. package/components/atoms/b-meter/b-meter.md +44 -0
  67. package/components/atoms/b-select/b-select.css +35 -0
  68. package/components/atoms/b-select/b-select.md +75 -0
  69. package/components/atoms/b-switch/b-switch.css +61 -0
  70. package/components/atoms/b-switch/b-switch.html +6 -0
  71. package/components/atoms/b-switch/b-switch.md +40 -0
  72. package/components/atoms/b-text/b-text.ai.md +29 -0
  73. package/components/atoms/b-text/b-text.css +2 -0
  74. package/components/atoms/b-text/b-text.html +3 -0
  75. package/components/atoms/b-text/b-text.md +23 -0
  76. package/components/atoms/code-block/code-block.css +42 -0
  77. package/components/atoms/code-block/code-block.md +23 -0
  78. package/components/examples.test.ts +23 -0
  79. package/components/molecules/callout/callout.css +19 -0
  80. package/components/molecules/callout/callout.md +15 -0
  81. package/components/molecules/card/card.css +28 -0
  82. package/components/molecules/card/card.md +30 -0
  83. package/components/molecules/chat-message/chat-message.css +83 -0
  84. package/components/molecules/chat-message/chat-message.md +52 -0
  85. package/components/molecules/chip-group/chip-group.css +35 -0
  86. package/components/molecules/chip-group/chip-group.md +42 -0
  87. package/components/molecules/content-index/content-index.css +87 -0
  88. package/components/molecules/content-index/content-index.md +27 -0
  89. package/components/molecules/content-source/content-source.css +6 -0
  90. package/components/molecules/content-source/content-source.md +13 -0
  91. package/components/molecules/figure/figure.css +19 -0
  92. package/components/molecules/figure/figure.md +20 -0
  93. package/components/molecules/lede/lede.css +17 -0
  94. package/components/molecules/lede/lede.md +17 -0
  95. package/components/molecules/made-with/made-with.css +25 -0
  96. package/components/molecules/made-with/made-with.md +35 -0
  97. package/components/molecules/nav-item/nav-item.css +19 -0
  98. package/components/molecules/nav-item/nav-item.md +21 -0
  99. package/components/molecules/stat-tile/stat-tile.css +34 -0
  100. package/components/molecules/stat-tile/stat-tile.md +50 -0
  101. package/components/molecules/status-list/status-list.css +47 -0
  102. package/components/molecules/status-list/status-list.md +62 -0
  103. package/components/molecules/tab/tab.css +32 -0
  104. package/components/molecules/tab/tab.md +27 -0
  105. package/components/molecules/table/table.css +23 -0
  106. package/components/molecules/table/table.md +18 -0
  107. package/components/organisms/activity-bar/activity-bar.css +36 -0
  108. package/components/organisms/activity-bar/activity-bar.md +43 -0
  109. package/components/organisms/app-shell/app-shell.css +193 -0
  110. package/components/organisms/app-shell/app-shell.md +58 -0
  111. package/components/organisms/app-shell/app-shell.test.ts +74 -0
  112. package/components/organisms/app-window/app-window.css +111 -0
  113. package/components/organisms/app-window/app-window.md +53 -0
  114. package/components/organisms/chat-log/chat-log.css +5 -0
  115. package/components/organisms/chat-log/chat-log.md +14 -0
  116. package/components/organisms/code-editor/code-editor.ai.md +31 -0
  117. package/components/organisms/code-editor/code-editor.css +111 -0
  118. package/components/organisms/code-editor/code-editor.md +122 -0
  119. package/components/organisms/console/console.css +112 -0
  120. package/components/organisms/console/console.md +66 -0
  121. package/components/organisms/file-tree/file-tree.css +85 -0
  122. package/components/organisms/file-tree/file-tree.md +49 -0
  123. package/components/organisms/note/note.css +19 -0
  124. package/components/organisms/note/note.md +20 -0
  125. package/components/organisms/notepad/notepad.css +60 -0
  126. package/components/organisms/notepad/notepad.md +40 -0
  127. package/components/organisms/side-rail/side-rail.css +55 -0
  128. package/components/organisms/side-rail/side-rail.md +24 -0
  129. package/components/organisms/sidebar-panel/sidebar-panel.css +69 -0
  130. package/components/organisms/sidebar-panel/sidebar-panel.md +47 -0
  131. package/components/organisms/status-bar/status-bar.css +33 -0
  132. package/components/organisms/status-bar/status-bar.md +28 -0
  133. package/components/organisms/tab-bar/tab-bar.css +48 -0
  134. package/components/organisms/tab-bar/tab-bar.md +26 -0
  135. package/components/organisms/timeline/timeline.css +51 -0
  136. package/components/organisms/timeline/timeline.md +42 -0
  137. package/components/organisms/topbar/topbar.css +8 -0
  138. package/components/organisms/topbar/topbar.md +26 -0
  139. package/components/responsive-polish.test.ts +43 -0
  140. package/components/tokens.test.ts +39 -0
  141. package/fonts/redaction-35-400.woff2 +0 -0
  142. package/fonts/redaction-400.woff2 +0 -0
  143. package/fonts/redaction-50-400.woff2 +0 -0
  144. package/fonts/redaction-70-400.woff2 +0 -0
  145. package/package.json +46 -0
  146. package/scripts/ai-dispatch.js +583 -0
  147. package/scripts/ai-dispatch.test.ts +85 -0
  148. package/scripts/ai-spotlight.d.ts +23 -0
  149. package/scripts/ai-spotlight.js +139 -0
  150. package/scripts/ai-spotlight.test.ts +31 -0
  151. package/scripts/catalog-peek.js +156 -0
  152. package/scripts/catalog-peek.test.ts +31 -0
  153. package/scripts/cmdk.js +159 -0
  154. package/scripts/demo-box.js +53 -0
  155. package/scripts/handoff.js +64 -0
  156. package/scripts/handoff.test.ts +36 -0
  157. package/scripts/lightbox.js +144 -0
  158. package/scripts/lightbox.test.ts +23 -0
  159. package/scripts/made-with.d.ts +2 -0
  160. package/scripts/made-with.js +22 -0
  161. package/scripts/made-with.test.ts +25 -0
  162. package/scripts/notepad.js +100 -0
  163. package/scripts/shell.js +204 -0
  164. package/scripts/shell.test.ts +50 -0
  165. package/scripts/tabs.js +127 -0
  166. package/scripts/tabs.test.ts +40 -0
  167. package/scripts/terminal.js +271 -0
  168. package/scripts/terminal.test.ts +36 -0
  169. package/scripts/theme-boot.js +15 -0
  170. package/scripts/theme.js +87 -0
  171. package/scripts/type-effect.js +25 -0
  172. package/scripts/xray.js +79 -0
  173. package/scripts/xray.test.ts +43 -0
  174. package/styles/cmdk.css +65 -0
  175. package/styles/global.css +80 -0
  176. package/styles/grain.css +47 -0
  177. package/styles/lightbox.css +78 -0
  178. package/styles/themes/_template.css +48 -0
  179. package/styles/themes/baguette.css +30 -0
  180. package/styles/themes/brioche.css +30 -0
  181. package/styles/variables.css +217 -0
@@ -0,0 +1,138 @@
1
+ // /app/ai/interaction-layer.ts — THE ONE DOOR (the single internal AI interaction
2
+ // layer; MVP §"One interface, one path"). Every Intent — from a human click or an
3
+ // AI decision — enters here, is validated against the closed vocabulary, handed to
4
+ // the reasoner (the single writer), and the resulting RenderOps are PUSHED back to
5
+ // the originating session over SSE. Nothing reaches the DOM by any other path.
6
+
7
+ import type { Reasoner, ReasonTools } from "./reasoner.ts";
8
+ import type { Intent, Decision, Surface, OpChannel, LogSink, Provenance } from "./contract.ts";
9
+ import { ACTIONS, isAction, surfaceKind, actionsForKind, OP_EVENT, STOP_ACTION } from "./contract.ts";
10
+
11
+ export interface LayerDeps {
12
+ reasoner: Reasoner;
13
+ stream: OpChannel; // the push port — GRAIN depends on this, not on BATCH's SSE hub
14
+ archiveItem: (id: string) => Promise<void>; // the scoped write capability
15
+ renderSurface: (surface: Surface) => Promise<string>; // committed HTML for a surface
16
+ logSink?: LogSink; // OPTIONAL: record every door crossing (the interaction timeline, §5g)
17
+ }
18
+
19
+ export interface InteractionLayer {
20
+ /** Handle one intent end-to-end; ops are pushed over `stream`. Returns the
21
+ * decision so callers/tests can inspect it (routes fire-and-forget). */
22
+ handleIntent(intent: Intent): Promise<Decision>;
23
+ }
24
+
25
+ const delay = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
26
+
27
+ export function createInteractionLayer(deps: LayerDeps): InteractionLayer {
28
+ const { reasoner, stream, archiveItem, renderSurface, logSink } = deps;
29
+
30
+ // Record one door crossing on the LOG PORT (if wired). Both the incoming REQUEST (kind
31
+ // "intent", provenance = who raised it) and the outgoing DECISION (kind "response",
32
+ // provenance = who authored the render — ai on success, system on a rejection/rollback)
33
+ // are logged, so the timeline reads as request → response, source-tagged and identical
34
+ // for a human click or an AI decision (AI-INTERFACE §5g).
35
+ const logIntent = (intent: Intent) => logSink?.record({
36
+ session: intent.session, source: intent.source, kind: "intent",
37
+ screen: intent.screen, surface: intent.surface, action: intent.action, ok: true, ops: 0,
38
+ });
39
+ // opCount = every RenderOp this crossing produced: the reasoner's mid-decision `emit`s (streamed
40
+ // tokens/appends) PLUS the ops in the returned decision. The streaming verbs return ops:[] and emit
41
+ // inline, so counting decision.ops alone would read a chat or demo as "0 ops" — hence both.
42
+ const logResponse = (intent: Intent, decision: Decision, opCount = decision.ops.length) => {
43
+ if (!logSink) return;
44
+ const source: Provenance = decision.ops.some((o) => o.provenance === "ai") ? "ai"
45
+ : decision.ok ? "ai" : "system";
46
+ logSink.record({
47
+ session: intent.session, source, kind: "response",
48
+ screen: intent.screen, surface: intent.surface, action: intent.action,
49
+ ok: decision.ok, ops: opCount,
50
+ });
51
+ };
52
+
53
+ const reject = (intent: Intent, reason: string, message: string): Decision => ({
54
+ ok: false,
55
+ reason,
56
+ ops: [{ target: intent.surface, op: "flash", message, provenance: "system", commit: "committed" }],
57
+ });
58
+
59
+ // Stop is keyed PER TURN, not per session. Each turn (one reasoner run) gets a unique id;
60
+ // the reasoner polls cancelled() for ITS id and halts at a clean boundary. `desk.stop` flags
61
+ // every turn currently running for the session. This way a concurrent intent (e.g. a chat sent
62
+ // mid-run) can never clear another running turn's stop flag (never a force-kill; §"Rollback"/§9).
63
+ let turnSeq = 0;
64
+ const activeTurns = new Map<string, Set<number>>(); // session → its running turn ids
65
+ const stoppedTurns = new Set<number>(); // turn ids asked to stop
66
+
67
+ async function handleIntent(intent: Intent): Promise<Decision> {
68
+ logIntent(intent); // record the crossing the moment it enters the one door (both operators, uniformly)
69
+
70
+ // `desk.stop` is a CONTROL signal: it never reaches the reasoner. It flags every turn
71
+ // running for this session; each running decision notices and hands back cleanly.
72
+ if (intent.action === STOP_ACTION) {
73
+ for (const id of activeTurns.get(intent.session) ?? []) stoppedTurns.add(id);
74
+ const stop: Decision = { ok: true, ops: [], reply: "Asked the AI to stop." };
75
+ logResponse(intent, stop);
76
+ return stop;
77
+ }
78
+
79
+ const turn = ++turnSeq;
80
+ const running = activeTurns.get(intent.session) ?? new Set<number>();
81
+ running.add(turn); activeTurns.set(intent.session, running);
82
+
83
+ let emitted = 0; // RenderOps the reasoner streams mid-decision (the timeline counts these too)
84
+ let decision: Decision;
85
+ try {
86
+ // "See if it's possible with the interfaces given" (MVP step 5): a lookup. A rejection ECHOES
87
+ // the moves that WOULD work — the valid verbs the vocabulary offers (unknown action) or the
88
+ // verbs this surface actually accepts (wrong surface) — so a reasoner reading the Decision can
89
+ // self-correct on its next turn instead of dead-ending on a bare "no" (AI-INTERFACE §0, the
90
+ // "surface has physics" direction). The `reason` is the machine-facing trace the model reads;
91
+ // the `flash` message stays short and human-facing.
92
+ if (!isAction(intent.action)) {
93
+ const known = Object.keys(ACTIONS).join(", ");
94
+ decision = reject(intent, `unknown action: ${intent.action}; known verbs: ${known}`,
95
+ "That action isn't available.");
96
+ } else if (!ACTIONS[intent.action].accepts.includes(surfaceKind(intent.surface))) {
97
+ const valid = actionsForKind(surfaceKind(intent.surface));
98
+ const accepts = valid.length ? `${intent.surface} accepts: ${valid.join(", ")}` : `${intent.surface} accepts no verbs`;
99
+ decision = reject(intent, `surface ${intent.surface} rejects ${intent.action}; ${accepts}`,
100
+ valid.length ? `Can't do that here — this surface takes: ${valid.join(", ")}.` : "Can't do that here.");
101
+ } else {
102
+ const tools: ReasonTools = {
103
+ archiveItem: (id) => archiveItem(id),
104
+ renderSurface: (s) => renderSurface(s),
105
+ emit: (op) => { emitted++; stream.push(intent.session, OP_EVENT, op); }, // stream tokens mid-decision
106
+ cancelled: () => stoppedTurns.has(turn), // per-turn — no cross-turn clobber
107
+ delay,
108
+ };
109
+ decision = await reasoner.decide(intent, tools);
110
+ }
111
+ } catch (e) {
112
+ console.error("[interaction-layer]", e);
113
+ decision = reject(intent, "internal error", "Something went wrong.");
114
+ } finally {
115
+ running.delete(turn);
116
+ if (running.size === 0) activeTurns.delete(intent.session);
117
+ stoppedTurns.delete(turn);
118
+ }
119
+
120
+ // When the AI itself is the actor (not a human click), bracket the ops with a
121
+ // spotlight so the user can SEE the AI acting (AI-INTERFACE §5c). The demo
122
+ // sequence emits its own spotlights; this covers real AI/worker-initiated intents.
123
+ const aiActing = intent.source === "ai" && decision.ops.length > 0;
124
+ if (aiActing) stream.push(intent.session, OP_EVENT,
125
+ { target: intent.surface, op: "spotlight", active: true, provenance: "ai", commit: "pending" });
126
+
127
+ // Push every op back to the session that raised the intent (MVP step 8).
128
+ for (const op of decision.ops) stream.push(intent.session, OP_EVENT, op);
129
+
130
+ if (aiActing) stream.push(intent.session, OP_EVENT,
131
+ { target: intent.surface, op: "spotlight", active: false, provenance: "ai", commit: "committed" });
132
+
133
+ logResponse(intent, decision, emitted + decision.ops.length); // record the outcome — the response half of the crossing
134
+ return decision;
135
+ }
136
+
137
+ return { handleIntent };
138
+ }
@@ -0,0 +1,176 @@
1
+ // grain/ai/manifest-dom.test.ts — UNIT: the client-side DOM→manifest projection.
2
+ // The DOM walk is exercised with plain fakes (the module takes a structural DomRoot, not
3
+ // lib.dom), so kind derivation, accepts intersection/inversion, and push-only classification
4
+ // are all testable without a browser. Full DOM behavior is covered by the terminal e2e.
5
+ import { test, expect } from "bun:test";
6
+ import { deriveKind, deriveAccepts, targetLabel, harvestTargets, harvestReadable, collapseReadable, domManifest, manifestForReasoner, READABLE_CAP, type DomEl } from "./manifest-dom.ts";
7
+ import { actionsForKind } from "./contract.ts";
8
+
9
+ // `text` seeds textContent (the readable state); attrs seed getAttribute. Both default to absent.
10
+ const el = (attrs: Record<string, string>, text: string | null = null): DomEl =>
11
+ ({ getAttribute: (n) => attrs[n] ?? null, textContent: text });
12
+
13
+ test("deriveKind: explicit data-kind wins; a registered kind is not push-only", () => {
14
+ expect(deriveKind("item:ITM-1", "item")).toEqual({ kind: "item", pushOnly: false });
15
+ });
16
+
17
+ test("deriveKind: derives kind from the address prefix when data-kind is absent", () => {
18
+ expect(deriveKind("item:ITM-9", null)).toEqual({ kind: "item", pushOnly: false });
19
+ expect(deriveKind("chat-log", null)).toEqual({ kind: "chat-log", pushOnly: false });
20
+ });
21
+
22
+ test("deriveKind: a display feed no verb targets is push-only", () => {
23
+ expect(deriveKind("console", null)).toEqual({ kind: "console", pushOnly: true });
24
+ expect(deriveKind("plan", null)).toEqual({ kind: "plan", pushOnly: true });
25
+ });
26
+
27
+ test("deriveKind: an unknown explicit data-kind is push-only (not a registry kind)", () => {
28
+ expect(deriveKind("weird", "made-up")).toEqual({ kind: "made-up", pushOnly: true });
29
+ });
30
+
31
+ test("deriveAccepts: explicit data-accepts is intersected with the real registry", () => {
32
+ expect(deriveAccepts("item", "item.archive")).toEqual(["item.archive"]);
33
+ // a stray/misspelled verb is dropped, not trusted
34
+ expect(deriveAccepts("item", "item.archive bogus.verb")).toEqual(["item.archive"]);
35
+ });
36
+
37
+ test("deriveAccepts: with no explicit list, a registered kind inverts the registry", () => {
38
+ expect(deriveAccepts("chat-log", null)).toEqual(actionsForKind("chat-log"));
39
+ expect(deriveAccepts("chat-log", null)).toContain("chat.send");
40
+ });
41
+
42
+ test("deriveAccepts: a push-only kind accepts nothing", () => {
43
+ expect(deriveAccepts("console", null)).toEqual([]);
44
+ });
45
+
46
+ test("targetLabel: verbs joined, else push-only", () => {
47
+ expect(targetLabel({ id: "item:1", kind: "item", accepts: ["item.archive"] })).toBe("item · item.archive");
48
+ expect(targetLabel({ id: "console", kind: "console", accepts: [], pushOnly: true })).toBe("console · push-only");
49
+ });
50
+
51
+ test("harvestTargets: walks [data-surface], skips empties, derives each", () => {
52
+ const root = {
53
+ querySelectorAll: () => [
54
+ el({ "data-surface": "item:ITM-1", "data-kind": "item", "data-accepts": "item.archive" }),
55
+ el({ "data-surface": "chat-log" }),
56
+ el({ "data-surface": "console" }),
57
+ el({ "data-surface": "" }), // skipped
58
+ ],
59
+ };
60
+ const targets = harvestTargets(root);
61
+ expect(targets.map((t) => t.id)).toEqual(["item:ITM-1", "chat-log", "console"]);
62
+ expect(targets[0]).toMatchObject({ kind: "item", accepts: ["item.archive"], pushOnly: false });
63
+ expect(targets[1].accepts).toContain("chat.send");
64
+ expect(targets[2]).toMatchObject({ kind: "console", accepts: [], pushOnly: true });
65
+ });
66
+
67
+ test("domManifest: same shape as the server manifest, marked a live-DOM projection", () => {
68
+ const doc = {
69
+ body: el({ "data-screen": "grain" }),
70
+ querySelectorAll: () => [el({ "data-surface": "chat-log" })],
71
+ };
72
+ const m = domManifest(doc);
73
+ expect(m.screen).toBe("grain");
74
+ expect(m.actions.length).toBeGreaterThan(0); // the full verb registry, as the server sends
75
+ // each advertised action carries its calling contract — description + payload schema
76
+ for (const a of m.actions) {
77
+ expect(typeof a.description).toBe("string");
78
+ expect(a.description.length).toBeGreaterThan(0);
79
+ expect(typeof a.payload).toBe("object");
80
+ }
81
+ const chat = m.actions.find((a) => a.name === "chat.send")!;
82
+ expect(chat.payload.text).toMatchObject({ type: "string", required: true });
83
+ expect(m.targets[0].id).toBe("chat-log");
84
+ // inView carries the addressable surfaces AND the readable-state array (empty: no data-read here)
85
+ expect(m.inView).toEqual({ surfaces: ["chat-log"], readable: [] });
86
+ expect(m.note).toMatch(/live dom/i);
87
+ });
88
+
89
+ test("collapseReadable: trims, squeezes whitespace/newlines to single spaces", () => {
90
+ expect(collapseReadable(" buy milk\n\n and eggs ")).toBe("buy milk and eggs");
91
+ expect(collapseReadable(null)).toBe("");
92
+ expect(collapseReadable(" ")).toBe("");
93
+ });
94
+
95
+ test("collapseReadable: caps overlong text with a trailing ellipsis", () => {
96
+ const long = "x".repeat(READABLE_CAP + 50);
97
+ const out = collapseReadable(long);
98
+ expect(out.length).toBe(READABLE_CAP);
99
+ expect(out.endsWith("…")).toBe(true);
100
+ });
101
+
102
+ test("harvestReadable: only surfaces that opted in with data-read, with their live text", () => {
103
+ const root = {
104
+ querySelectorAll: () => [
105
+ el({ "data-surface": "reflection", "data-read": "" }, " Noted: buy milk "),
106
+ el({ "data-surface": "notepad-body", "data-kind": "notepad", "data-read": "" }, "## Notes\ncall the bank"),
107
+ el({ "data-surface": "chat-log" }, "unmarked — not harvested"), // no data-read → skipped
108
+ el({ "data-surface": "console", "data-read": "" }, " "), // marked but empty → skipped
109
+ ],
110
+ };
111
+ const readable = harvestReadable(root);
112
+ expect(readable).toEqual([
113
+ { id: "reflection", kind: "reflection", text: "Noted: buy milk" },
114
+ { id: "notepad-body", kind: "notepad", text: "## Notes call the bank" },
115
+ ]);
116
+ });
117
+
118
+ test("manifestForReasoner: renders an 'in view' block for data-read surfaces", () => {
119
+ const doc = {
120
+ body: el({ "data-screen": "loop" }),
121
+ querySelectorAll: () => [
122
+ el({ "data-surface": "reflection", "data-read": "" }, "Noted: buy milk"),
123
+ ],
124
+ };
125
+ const text = manifestForReasoner(doc);
126
+ expect(text).toContain('in view: (1)\n- reflection [reflection] "Noted: buy milk"');
127
+ });
128
+
129
+ test("manifestForReasoner: deterministic, prompt-ready text — same fixed DOM in, same string out", () => {
130
+ const doc = {
131
+ body: el({ "data-screen": "notes" }),
132
+ querySelectorAll: () => [
133
+ el({ "data-surface": "item:ITM-1", "data-kind": "item", "data-accepts": "item.archive" }),
134
+ el({ "data-surface": "chat-log" }),
135
+ el({ "data-surface": "console" }), // push-only — no verb targets it
136
+ ],
137
+ };
138
+ const first = manifestForReasoner(doc);
139
+ const second = manifestForReasoner(doc);
140
+ expect(first).toBe(second); // deterministic
141
+
142
+ // Structure: screen line, then the full MOVE SET (actions with payload shape), then targets.
143
+ expect(first.startsWith("screen: notes\nactions: (")).toBe(true);
144
+ // a no-arg verb, a required-text verb, and a noted markdown verb — the payload contract, surfaced
145
+ expect(first).toContain("- item.archive [light] (no args) — Archive an item");
146
+ expect(first).toContain("- chat.send [light] (text*:string) — Send a chat message");
147
+ expect(first).toContain("- note.append [light] (text*:string (markdown)) — Append one markdown entry");
148
+ expect(first).toContain("- navigate [light] (href*:string (root-relative path, e.g. /notes)) —");
149
+ // behaviour hints ride along in braces so the reasoner can retry/choose safely
150
+ expect(first).toContain("- note.replace [light] (text*:string (markdown)) — Rewrite the whole notepad from one markdown body. {destructive, idempotent}");
151
+ expect(first).toContain("- navigate [light] (href*:string (root-relative path, e.g. /notes)) — Change screens — same-origin, root-relative href only (validated at the door). {read");
152
+ // the targets tail is exact and comes after the actions block
153
+ expect(first.endsWith(
154
+ "targets: (3)\n" +
155
+ "- item:ITM-1 [item] -> item.archive\n" +
156
+ "- chat-log [chat-log] -> chat.send\n" +
157
+ "- console [console] -> (no verb currently targets this)"
158
+ )).toBe(true);
159
+ });
160
+
161
+ test("manifestForReasoner: a screen-kind surface lists navigate among its accepted verbs", () => {
162
+ const doc = {
163
+ body: el({ "data-screen": "grain" }),
164
+ querySelectorAll: () => [el({ "data-surface": "screen", "data-kind": "screen" })],
165
+ };
166
+ const text = manifestForReasoner(doc);
167
+ expect(text).toContain("- screen [screen] ->");
168
+ expect(text).toContain("navigate");
169
+ });
170
+
171
+ test("manifestForReasoner: no [data-surface] elements — says so plainly, doesn't crash", () => {
172
+ const doc = { body: el({ "data-screen": "empty" }), querySelectorAll: () => [] };
173
+ const text = manifestForReasoner(doc);
174
+ expect(text.startsWith("screen: empty\nactions: (")).toBe(true); // the move set is always listed
175
+ expect(text.endsWith("targets: (none — this page declares no [data-surface] elements)")).toBe(true);
176
+ });
@@ -0,0 +1,187 @@
1
+ // grain/ai/manifest-dom.ts — the manifest, HARVESTED FROM THE LIVE DOM (client-side).
2
+ //
3
+ // The server builds a manifest from component state (ai/manifest.ts + accepts.ts, harvested
4
+ // from .html at rest). This is the SAME projection, but read off the rendered page in the
5
+ // browser: walk every [data-surface], derive each one's kind + accepted verbs, and hand back
6
+ // the identical Manifest shape. It's the honest answer to "what can the AI do on THIS page,
7
+ // right now" (AI-INTERFACE §4) — and, because it reads the DOM, it works on a static host with
8
+ // no /ai/manifest route. It powers the terminal's `context` command and x-ray mode.
9
+ //
10
+ // CLIENT-SAFE (ARCHITECTURE §19.2): imports only the pure contract + manifest builder — no
11
+ // server-only modules, no secrets. The DOM is reached through a MINIMAL STRUCTURAL interface
12
+ // (DomEl/DomRoot below), not the global `lib.dom` types, so this compiles without pulling DOM
13
+ // globals into the server build AND the derivation logic is unit-testable with plain objects.
14
+
15
+ import { ACTIONS, isAction, actionsForKind, surfaceKind, type ActionName, type SurfaceKind } from "./contract.ts";
16
+ import { buildManifest, type Manifest, type ManifestTarget } from "./manifest.ts";
17
+
18
+ // ── the sliver of the DOM this module touches (structural, not lib.dom) ───────────────────────
19
+ export interface DomEl {
20
+ getAttribute(name: string): string | null;
21
+ textContent: string | null; // read to harvest a surface's current READABLE state (data-read opt-in)
22
+ }
23
+ export interface DomRoot {
24
+ querySelectorAll(selectors: string): Iterable<DomEl>;
25
+ }
26
+ /** A document, structurally: a root to walk plus the screen name off <body data-screen>. */
27
+ export interface DomDoc extends DomRoot {
28
+ body: DomEl | null;
29
+ }
30
+
31
+ const KNOWN_KINDS = new Set<string>(Object.values(ACTIONS).flatMap((a) => a.accepts));
32
+ const isKind = (s: string): s is SurfaceKind => KNOWN_KINDS.has(s);
33
+
34
+ /** A surface's kind + whether it's push-only (a display feed no verb targets). The kind is the
35
+ * explicit data-kind, else the address prefix ("item" of "item:ITM-1", or a bare "chat-log")
36
+ * when that names a real SurfaceKind. Anything else (console, plan, …) is push-only. */
37
+ export function deriveKind(surface: string, dataKind: string | null): { kind: string; pushOnly: boolean } {
38
+ if (dataKind && dataKind.trim()) return { kind: dataKind.trim(), pushOnly: !isKind(dataKind.trim()) };
39
+ const prefix = surfaceKind(surface); // "item:ITM-1" → "item"; "chat-log" → "chat-log"
40
+ if (isKind(prefix)) return { kind: prefix, pushOnly: false };
41
+ return { kind: surface, pushOnly: true };
42
+ }
43
+
44
+ /** The verbs valid on a target: its declared data-accepts (∩ the registry, so a stray verb is
45
+ * dropped), else — for a registered kind with no explicit list — the registry inversion. */
46
+ export function deriveAccepts(kind: string, dataAccepts: string | null): ActionName[] {
47
+ if (dataAccepts && dataAccepts.trim()) {
48
+ return dataAccepts.trim().split(/\s+/).filter(isAction);
49
+ }
50
+ return isKind(kind) ? actionsForKind(kind) : [];
51
+ }
52
+
53
+ /** The one-line x-ray label for a target: "kind · verb verb", or "kind · push-only". */
54
+ export function targetLabel(t: ManifestTarget & { pushOnly?: boolean }): string {
55
+ const verbs = t.accepts.length ? t.accepts.join(" ") : (t.pushOnly ? "push-only" : "—");
56
+ return `${t.kind} · ${verbs}`;
57
+ }
58
+
59
+ export interface DomManifestTarget extends ManifestTarget {
60
+ pushOnly: boolean;
61
+ }
62
+
63
+ // ── readable in-view state: the MCP "resources" analog ─────────────────────────────────────────
64
+ // `targets`/`actions` say what a reasoner can ADDRESS and INVOKE; they don't say what a surface
65
+ // currently CONTAINS. `data-read` closes that gap: a surface OPTS IN to exposing its live text —
66
+ // exactly as `data-accepts` opts a target into a verb (AI-INTERFACE §4). The framework harvests
67
+ // it, never authors it, so it stays app-agnostic (grain never knows the content, only that it was
68
+ // flagged) and prompt-economic (only marked surfaces, each capped — not the whole DOM dumped in).
69
+
70
+ /** One surface's current readable state — the manifest's MCP-resource analog: `id` is its address
71
+ * (the uri), `kind` its surface kind, `text` its live, collapsed, capped textContent. */
72
+ export interface ReadableSurface {
73
+ id: string;
74
+ kind: string;
75
+ text: string;
76
+ }
77
+
78
+ /** Per-surface character cap on harvested text — keeps the observe prompt tight; a marked surface
79
+ * is meant to expose a line or a short body, not a whole document. Truncation is signalled with "…". */
80
+ export const READABLE_CAP = 400;
81
+
82
+ /** Collapse a surface's textContent to one prompt-safe line: trim, squeeze whitespace runs (incl.
83
+ * newlines) to single spaces, and cap length with a trailing "…" so a reader knows it was clipped. */
84
+ export function collapseReadable(raw: string | null): string {
85
+ const text = (raw ?? "").replace(/\s+/g, " ").trim();
86
+ return text.length > READABLE_CAP ? text.slice(0, READABLE_CAP - 1).trimEnd() + "…" : text;
87
+ }
88
+
89
+ /** Walk every surface that OPTED IN with `data-read` and harvest its current readable state. Filters
90
+ * on the attribute (not just the selector) so it's correct even against a structural fake root; skips
91
+ * a marked-but-empty surface (no text = nothing to read). Document order → deterministic. */
92
+ export function harvestReadable(root: DomRoot): ReadableSurface[] {
93
+ const out: ReadableSurface[] = [];
94
+ for (const el of root.querySelectorAll("[data-surface]")) {
95
+ if (el.getAttribute("data-read") === null) continue; // opt-in only
96
+ const surface = el.getAttribute("data-surface");
97
+ if (!surface) continue;
98
+ const text = collapseReadable(el.textContent);
99
+ if (!text) continue;
100
+ const { kind } = deriveKind(surface, el.getAttribute("data-kind"));
101
+ out.push({ id: surface, kind, text });
102
+ }
103
+ return out;
104
+ }
105
+
106
+ /** Walk every [data-surface] under `root` and derive its manifest target. */
107
+ export function harvestTargets(root: DomRoot): DomManifestTarget[] {
108
+ const out: DomManifestTarget[] = [];
109
+ for (const el of root.querySelectorAll("[data-surface]")) {
110
+ const surface = el.getAttribute("data-surface");
111
+ if (!surface) continue;
112
+ const { kind, pushOnly } = deriveKind(surface, el.getAttribute("data-kind"));
113
+ const accepts = deriveAccepts(kind, el.getAttribute("data-accepts"));
114
+ out.push({ id: surface, kind, accepts, pushOnly });
115
+ }
116
+ return out;
117
+ }
118
+
119
+ /** Build the full client-side manifest for a document: the same shape the server emits, noted
120
+ * as a live-DOM projection so a reader knows where it came from. */
121
+ export function domManifest(doc: DomDoc): Manifest {
122
+ const screen = doc.body?.getAttribute("data-screen") ?? "";
123
+ const targets = harvestTargets(doc);
124
+ const readable = harvestReadable(doc); // current text of every data-read surface (MCP-resources analog)
125
+ const m = buildManifest(screen, targets, { surfaces: targets.map((t) => t.id), readable });
126
+ m.note = "Client-side projection of the LIVE DOM: every [data-surface] on this page, its kind, " +
127
+ "the verbs the registry allows on it, and — for any surface that opted in with data-read — " +
128
+ "its current readable state in inView.readable. Same shape as the server manifest (AI-INTERFACE §4).";
129
+ return m;
130
+ }
131
+
132
+ /** A compact, deterministic, PLAIN-TEXT rendering of `domManifest()` — meant to be dropped
133
+ * straight into an LLM system/user prompt so a consumer reasoner (a real model) decides what to
134
+ * click/navigate from the REAL, live affordances on screen, instead of a hardcoded address list
135
+ * that can silently drift from the UI (the same anti-drift promise `domManifest` already makes —
136
+ * this is just its prose form). Built ON `domManifest`, not a second harvest: one truth, two
137
+ * shapes (JSON for code, text for a prompt). Deterministic: the same DOM in always yields the
138
+ * same string out — target order follows `harvestTargets`' DOM walk (document order), never a
139
+ * Set/Map/Object whose iteration order could vary across engines. Pure — no DOM writes, no I/O. */
140
+ export function manifestForReasoner(doc: DomDoc): string {
141
+ return manifestToText(domManifest(doc));
142
+ }
143
+
144
+ /** Render a Manifest OBJECT to the same prompt-ready text `manifestForReasoner` emits — split out so a
145
+ * reasoner that already holds a Manifest (e.g. built server-side, or reused for validation) can get
146
+ * the prompt text WITHOUT a second DOM harvest, and so this stays a pure Manifest→string function
147
+ * (DOM-free, one truth two shapes). `manifestForReasoner(doc)` is just `manifestToText(domManifest(doc))`. */
148
+ export function manifestToText(m: Manifest): string {
149
+ const lines: string[] = [`screen: ${m.screen || "(none)"}`];
150
+
151
+ // The MOVE SET: every verb the vocabulary offers, with the payload shape a reasoner needs to
152
+ // CALL it (field*:type — "*" = required) and a one-line description of what it does. Without
153
+ // this a model sees which verbs a target accepts (below) but has to guess the payload — the gap
154
+ // this section closes (AI-INTERFACE §1b). Order follows the ACTIONS registry (buildManifest).
155
+ lines.push(`actions: (${m.actions.length})`);
156
+ for (const a of m.actions) {
157
+ const fields = Object.entries(a.payload)
158
+ .map(([name, f]) => `${name}${f.required ? "*" : ""}:${f.type}${f.note ? ` (${f.note})` : ""}`);
159
+ const args = fields.length ? fields.join(", ") : "no args";
160
+ // behaviour hints (read-only / destructive / idempotent) so the reasoner chooses + retries safely
161
+ const flags = Object.entries(a.hints).filter(([, v]) => v).map(([k]) => k);
162
+ const hints = flags.length ? ` {${flags.join(", ")}}` : "";
163
+ lines.push(`- ${a.name} [${a.depth}] (${args}) — ${a.description}${hints}`);
164
+ }
165
+
166
+ if (!m.targets.length) {
167
+ lines.push("targets: (none — this page declares no [data-surface] elements)");
168
+ return lines.join("\n");
169
+ }
170
+ lines.push(`targets: (${m.targets.length})`);
171
+ for (const t of m.targets) {
172
+ const verbs = t.accepts.length ? t.accepts.join(", ") : "(no verb currently targets this)";
173
+ lines.push(`- ${t.id} [${t.kind}] -> ${verbs}`);
174
+ }
175
+
176
+ // IN VIEW: the current readable STATE of every surface that opted in with data-read (the MCP
177
+ // "resources" analog). Emitted ONLY when something is readable — a page with no marked surface
178
+ // yields the exact same string as before, so the block never adds noise where there's no state.
179
+ // This is the "read the result" half of the observe loop: after acting, the reasoner sees not
180
+ // just what it can do next but what the surfaces now SAY.
181
+ const readable = (m.inView.readable as ReadableSurface[] | undefined) ?? [];
182
+ if (readable.length) {
183
+ lines.push(`in view: (${readable.length})`);
184
+ for (const r of readable) lines.push(`- ${r.id} [${r.kind}] "${r.text}"`);
185
+ }
186
+ return lines.join("\n");
187
+ }
@@ -0,0 +1,71 @@
1
+ // grain/ai/manifest.test.ts — UNIT: manifest builder in isolation.
2
+ import { test, expect } from "bun:test";
3
+ import { buildManifest } from "./manifest.ts";
4
+ import { ACTIONS } from "./contract.ts";
5
+ import type { ManifestTarget } from "./manifest.ts";
6
+
7
+ const targets: ManifestTarget[] = [
8
+ { id: "item:ITM-1", kind: "item", accepts: ["item.archive"] },
9
+ { id: "reflection", kind: "reflection", accepts: ["say.set"] },
10
+ ];
11
+
12
+ test("buildManifest: actions list matches ACTIONS registry exactly", () => {
13
+ const m = buildManifest("loop", targets);
14
+ const registryNames = Object.keys(ACTIONS).sort();
15
+ const manifestNames: string[] = m.actions.map((a) => a.name as string).sort();
16
+ expect(manifestNames).toEqual(registryNames);
17
+ });
18
+
19
+ test("buildManifest: each action entry has name, depth, accepts, description, payload", () => {
20
+ const m = buildManifest("loop", targets);
21
+ for (const a of m.actions) {
22
+ expect(typeof a.name).toBe("string");
23
+ expect(["light", "heavy"]).toContain(a.depth);
24
+ expect(Array.isArray(a.accepts)).toBe(true);
25
+ expect(typeof a.description).toBe("string");
26
+ expect(a.description.length).toBeGreaterThan(0);
27
+ expect(typeof a.payload).toBe("object");
28
+ expect(typeof a.hints).toBe("object");
29
+ }
30
+ });
31
+
32
+ test("buildManifest: hints are carried through from the registry", () => {
33
+ const m = buildManifest("loop", targets);
34
+ const replace = m.actions.find((a) => a.name === "note.replace")!;
35
+ expect(replace.hints).toMatchObject({ destructive: true, idempotent: true });
36
+ });
37
+
38
+ test("buildManifest: payload schema is carried through from the registry (name → {type,required})", () => {
39
+ const m = buildManifest("loop", targets);
40
+ const note = m.actions.find((a) => a.name === "note.append")!;
41
+ expect(note.payload.text).toMatchObject({ type: "string", required: true, note: "markdown" });
42
+ const archive = m.actions.find((a) => a.name === "item.archive")!;
43
+ expect(archive.payload).toEqual({}); // a no-argument verb advertises an empty schema
44
+ });
45
+
46
+ test("buildManifest: targets are passed through unchanged", () => {
47
+ const m = buildManifest("loop", targets);
48
+ expect(m.targets).toEqual(targets);
49
+ });
50
+
51
+ test("buildManifest: screen is set correctly", () => {
52
+ const m = buildManifest("grain", targets);
53
+ expect(m.screen).toBe("grain");
54
+ });
55
+
56
+ test("buildManifest: inView defaults to empty object", () => {
57
+ const m = buildManifest("loop", targets);
58
+ expect(m.inView).toEqual({});
59
+ });
60
+
61
+ test("buildManifest: inView is threaded through when provided", () => {
62
+ const inView = { items: [{ id: "ITM-1" }] };
63
+ const m = buildManifest("loop", targets, inView);
64
+ expect(m.inView).toEqual(inView);
65
+ });
66
+
67
+ test("buildManifest: note is a non-empty string", () => {
68
+ const m = buildManifest("loop", targets);
69
+ expect(typeof m.note).toBe("string");
70
+ expect(m.note.length).toBeGreaterThan(0);
71
+ });
package/ai/manifest.ts ADDED
@@ -0,0 +1,57 @@
1
+ // /app/ai/manifest.ts — the AI's instruction manual, per screen.
2
+ //
3
+ // A machine-readable projection of what's addressable (targets) and invokable
4
+ // (actions) on a screen, plus the in-view state the reasoner needs (MVP steps 2–4).
5
+ // The AI reads this; it is never hand-maintained against the UI.
6
+ //
7
+ // Accepts are HARVESTED from components (data-accepts) and inverted from the action
8
+ // registry — never hand-typed — so the manifest provably can't drift from what's on
9
+ // screen or from the allowed vocabulary. See AI-INTERFACE §4 and framework/render/accepts.ts.
10
+
11
+ import type { ActionName, PayloadSchema, ActionHints } from "./contract.ts";
12
+ import { ACTIONS } from "./contract.ts";
13
+
14
+ export interface ManifestTarget {
15
+ id: string; // a surface address, e.g. "item:ITM-1"
16
+ kind: string; // "item"
17
+ accepts: ActionName[]; // verbs valid on this target right now
18
+ }
19
+
20
+ // Each advertised action carries its full calling contract: not just name + where it applies,
21
+ // but a one-line description and the payload schema — so a reasoner reading the manifest knows
22
+ // HOW to invoke it, not merely that it exists (AI-INTERFACE §1b, §4).
23
+ export interface ManifestAction {
24
+ name: ActionName;
25
+ depth: string;
26
+ accepts: string[];
27
+ description: string;
28
+ payload: PayloadSchema;
29
+ hints: ActionHints;
30
+ }
31
+
32
+ export interface Manifest {
33
+ screen: string;
34
+ actions: ManifestAction[];
35
+ targets: ManifestTarget[];
36
+ inView: Record<string, unknown>;
37
+ note: string;
38
+ }
39
+
40
+ export function buildManifest(
41
+ screen: string,
42
+ targets: ManifestTarget[],
43
+ inView: Record<string, unknown> = {},
44
+ ): Manifest {
45
+ return {
46
+ screen,
47
+ actions: Object.values(ACTIONS).map((a) => ({
48
+ name: a.name, depth: a.depth, accepts: a.accepts,
49
+ description: a.description, payload: a.payload, hints: a.hints,
50
+ })),
51
+ targets,
52
+ inView,
53
+ note: "Accepts are derived, never hand-typed: item targets are harvested from the " +
54
+ "component's data-accepts; regions are inverted from the action registry. So the " +
55
+ "manifest can't drift from the UI or the allowed vocabulary (AI-INTERFACE §4).",
56
+ };
57
+ }