@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.
- package/LICENSE +202 -0
- package/PLAN.md +27 -0
- package/README.md +243 -0
- package/ai/accepts.test.ts +69 -0
- package/ai/accepts.ts +57 -0
- package/ai/ai.css +127 -0
- package/ai/client-door.test.ts +70 -0
- package/ai/client-door.ts +56 -0
- package/ai/contract.test.ts +158 -0
- package/ai/contract.ts +285 -0
- package/ai/interaction-layer.test.ts +270 -0
- package/ai/interaction-layer.ts +138 -0
- package/ai/manifest-dom.test.ts +176 -0
- package/ai/manifest-dom.ts +187 -0
- package/ai/manifest.test.ts +71 -0
- package/ai/manifest.ts +57 -0
- package/ai/markdown.test.ts +68 -0
- package/ai/markdown.ts +74 -0
- package/ai/model-chat.test.ts +131 -0
- package/ai/model-chat.ts +151 -0
- package/ai/model-reasoner.test.ts +152 -0
- package/ai/model-reasoner.ts +146 -0
- package/ai/model.test.ts +148 -0
- package/ai/model.ts +200 -0
- package/ai/reasoner-kit.test.ts +142 -0
- package/ai/reasoner-kit.ts +159 -0
- package/ai/reasoner.test.ts +227 -0
- package/ai/reasoner.ts +446 -0
- package/ai/timeline-log.test.ts +55 -0
- package/ai/timeline-log.ts +50 -0
- package/ai/vocab-reference.test.ts +43 -0
- package/ai/vocab-reference.ts +107 -0
- package/ai/webllm.test.ts +79 -0
- package/ai/webllm.ts +125 -0
- package/assets/figure-sample.svg +14 -0
- package/assets/sprite.svg +22 -0
- package/catalog/catalog.test.ts +37 -0
- package/catalog/catalog.ts +424 -0
- package/components/atoms/action-badge/action-badge.css +17 -0
- package/components/atoms/action-badge/action-badge.html +6 -0
- package/components/atoms/action-badge/action-badge.md +23 -0
- package/components/atoms/b-badge/b-badge.css +15 -0
- package/components/atoms/b-badge/b-badge.html +2 -0
- package/components/atoms/b-badge/b-badge.md +16 -0
- package/components/atoms/b-button/b-button.ai.md +22 -0
- package/components/atoms/b-button/b-button.css +87 -0
- package/components/atoms/b-button/b-button.html +5 -0
- package/components/atoms/b-button/b-button.md +77 -0
- package/components/atoms/b-icon/b-icon.css +10 -0
- package/components/atoms/b-icon/b-icon.html +5 -0
- package/components/atoms/b-icon/b-icon.md +36 -0
- package/components/atoms/b-icon-button/b-icon-button.ai.md +11 -0
- package/components/atoms/b-icon-button/b-icon-button.css +43 -0
- package/components/atoms/b-icon-button/b-icon-button.html +8 -0
- package/components/atoms/b-icon-button/b-icon-button.md +33 -0
- package/components/atoms/b-input/b-input.css +36 -0
- package/components/atoms/b-input/b-input.html +8 -0
- package/components/atoms/b-input/b-input.md +59 -0
- package/components/atoms/b-kbd/b-kbd.css +11 -0
- package/components/atoms/b-kbd/b-kbd.html +3 -0
- package/components/atoms/b-kbd/b-kbd.md +13 -0
- package/components/atoms/b-list/b-list.css +21 -0
- package/components/atoms/b-list/b-list.html +6 -0
- package/components/atoms/b-list/b-list.md +24 -0
- package/components/atoms/b-meter/b-meter.css +39 -0
- package/components/atoms/b-meter/b-meter.md +44 -0
- package/components/atoms/b-select/b-select.css +35 -0
- package/components/atoms/b-select/b-select.md +75 -0
- package/components/atoms/b-switch/b-switch.css +61 -0
- package/components/atoms/b-switch/b-switch.html +6 -0
- package/components/atoms/b-switch/b-switch.md +40 -0
- package/components/atoms/b-text/b-text.ai.md +29 -0
- package/components/atoms/b-text/b-text.css +2 -0
- package/components/atoms/b-text/b-text.html +3 -0
- package/components/atoms/b-text/b-text.md +23 -0
- package/components/atoms/code-block/code-block.css +42 -0
- package/components/atoms/code-block/code-block.md +23 -0
- package/components/examples.test.ts +23 -0
- package/components/molecules/callout/callout.css +19 -0
- package/components/molecules/callout/callout.md +15 -0
- package/components/molecules/card/card.css +28 -0
- package/components/molecules/card/card.md +30 -0
- package/components/molecules/chat-message/chat-message.css +83 -0
- package/components/molecules/chat-message/chat-message.md +52 -0
- package/components/molecules/chip-group/chip-group.css +35 -0
- package/components/molecules/chip-group/chip-group.md +42 -0
- package/components/molecules/content-index/content-index.css +87 -0
- package/components/molecules/content-index/content-index.md +27 -0
- package/components/molecules/content-source/content-source.css +6 -0
- package/components/molecules/content-source/content-source.md +13 -0
- package/components/molecules/figure/figure.css +19 -0
- package/components/molecules/figure/figure.md +20 -0
- package/components/molecules/lede/lede.css +17 -0
- package/components/molecules/lede/lede.md +17 -0
- package/components/molecules/made-with/made-with.css +25 -0
- package/components/molecules/made-with/made-with.md +35 -0
- package/components/molecules/nav-item/nav-item.css +19 -0
- package/components/molecules/nav-item/nav-item.md +21 -0
- package/components/molecules/stat-tile/stat-tile.css +34 -0
- package/components/molecules/stat-tile/stat-tile.md +50 -0
- package/components/molecules/status-list/status-list.css +47 -0
- package/components/molecules/status-list/status-list.md +62 -0
- package/components/molecules/tab/tab.css +32 -0
- package/components/molecules/tab/tab.md +27 -0
- package/components/molecules/table/table.css +23 -0
- package/components/molecules/table/table.md +18 -0
- package/components/organisms/activity-bar/activity-bar.css +36 -0
- package/components/organisms/activity-bar/activity-bar.md +43 -0
- package/components/organisms/app-shell/app-shell.css +193 -0
- package/components/organisms/app-shell/app-shell.md +58 -0
- package/components/organisms/app-shell/app-shell.test.ts +74 -0
- package/components/organisms/app-window/app-window.css +111 -0
- package/components/organisms/app-window/app-window.md +53 -0
- package/components/organisms/chat-log/chat-log.css +5 -0
- package/components/organisms/chat-log/chat-log.md +14 -0
- package/components/organisms/code-editor/code-editor.ai.md +31 -0
- package/components/organisms/code-editor/code-editor.css +111 -0
- package/components/organisms/code-editor/code-editor.md +122 -0
- package/components/organisms/console/console.css +112 -0
- package/components/organisms/console/console.md +66 -0
- package/components/organisms/file-tree/file-tree.css +85 -0
- package/components/organisms/file-tree/file-tree.md +49 -0
- package/components/organisms/note/note.css +19 -0
- package/components/organisms/note/note.md +20 -0
- package/components/organisms/notepad/notepad.css +60 -0
- package/components/organisms/notepad/notepad.md +40 -0
- package/components/organisms/side-rail/side-rail.css +55 -0
- package/components/organisms/side-rail/side-rail.md +24 -0
- package/components/organisms/sidebar-panel/sidebar-panel.css +69 -0
- package/components/organisms/sidebar-panel/sidebar-panel.md +47 -0
- package/components/organisms/status-bar/status-bar.css +33 -0
- package/components/organisms/status-bar/status-bar.md +28 -0
- package/components/organisms/tab-bar/tab-bar.css +48 -0
- package/components/organisms/tab-bar/tab-bar.md +26 -0
- package/components/organisms/timeline/timeline.css +51 -0
- package/components/organisms/timeline/timeline.md +42 -0
- package/components/organisms/topbar/topbar.css +8 -0
- package/components/organisms/topbar/topbar.md +26 -0
- package/components/responsive-polish.test.ts +43 -0
- package/components/tokens.test.ts +39 -0
- package/fonts/redaction-35-400.woff2 +0 -0
- package/fonts/redaction-400.woff2 +0 -0
- package/fonts/redaction-50-400.woff2 +0 -0
- package/fonts/redaction-70-400.woff2 +0 -0
- package/package.json +46 -0
- package/scripts/ai-dispatch.js +583 -0
- package/scripts/ai-dispatch.test.ts +85 -0
- package/scripts/ai-spotlight.d.ts +23 -0
- package/scripts/ai-spotlight.js +139 -0
- package/scripts/ai-spotlight.test.ts +31 -0
- package/scripts/catalog-peek.js +156 -0
- package/scripts/catalog-peek.test.ts +31 -0
- package/scripts/cmdk.js +159 -0
- package/scripts/demo-box.js +53 -0
- package/scripts/handoff.js +64 -0
- package/scripts/handoff.test.ts +36 -0
- package/scripts/lightbox.js +144 -0
- package/scripts/lightbox.test.ts +23 -0
- package/scripts/made-with.d.ts +2 -0
- package/scripts/made-with.js +22 -0
- package/scripts/made-with.test.ts +25 -0
- package/scripts/notepad.js +100 -0
- package/scripts/shell.js +204 -0
- package/scripts/shell.test.ts +50 -0
- package/scripts/tabs.js +127 -0
- package/scripts/tabs.test.ts +40 -0
- package/scripts/terminal.js +271 -0
- package/scripts/terminal.test.ts +36 -0
- package/scripts/theme-boot.js +15 -0
- package/scripts/theme.js +87 -0
- package/scripts/type-effect.js +25 -0
- package/scripts/xray.js +79 -0
- package/scripts/xray.test.ts +43 -0
- package/styles/cmdk.css +65 -0
- package/styles/global.css +80 -0
- package/styles/grain.css +47 -0
- package/styles/lightbox.css +78 -0
- package/styles/themes/_template.css +48 -0
- package/styles/themes/baguette.css +30 -0
- package/styles/themes/brioche.css +30 -0
- 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
|
+
}
|