@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,107 @@
|
|
|
1
|
+
// grain/ai/vocab-reference.ts — a GENERATED reference for the AI vocabulary contract
|
|
2
|
+
// (https://tjakoen.github.io/grain/docs/ai-interface), for the developer-docs `/reference` route (../../DEV-DOCS.md
|
|
3
|
+
// step 5). This renders the REAL registries at request time — never a hand-copied
|
|
4
|
+
// table — so the reference can't drift from `contract.ts` the way prose easily does.
|
|
5
|
+
//
|
|
6
|
+
// What's genuinely reflectable at runtime vs. what isn't:
|
|
7
|
+
// - ActionName + ACTIONS: real runtime values — read directly, zero copy.
|
|
8
|
+
// - SurfaceKind: not a runtime value (a type alias), but every kind IN USE is
|
|
9
|
+
// recoverable as the union of every action's `accepts` — derived, not copied.
|
|
10
|
+
// - RenderOpKind + the HTTP endpoints: pure type aliases / literal strings with no
|
|
11
|
+
// backing runtime array anywhere in the codebase. Hardcoded below, but GUARDED —
|
|
12
|
+
// see vocab-reference.test.ts, which greps contract.ts / ai-routes.ts's source so
|
|
13
|
+
// a mismatch fails a test instead of silently drifting.
|
|
14
|
+
import { ACTIONS, type ActionDef, type SurfaceKind } from "./contract.ts";
|
|
15
|
+
|
|
16
|
+
const esc = (s: string) =>
|
|
17
|
+
s.replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">").replace(/"/g, """);
|
|
18
|
+
|
|
19
|
+
// Kept here (not derivable) — guarded by vocab-reference.test.ts against contract.ts's
|
|
20
|
+
// `RenderOpKind` union.
|
|
21
|
+
export const RENDER_OP_KINDS: readonly { kind: string; means: string }[] = [
|
|
22
|
+
{ kind: "replace", means: "swap the target's HTML — the confirmed/committed fragment" },
|
|
23
|
+
{ kind: "append", means: "add HTML to the end of the target (a chat log, a plan list, the console)" },
|
|
24
|
+
{ kind: "remove", means: "delete the target element" },
|
|
25
|
+
{ kind: "flash", means: "a transient note; also rolls back an optimistic pending state" },
|
|
26
|
+
{ kind: "type", means: "stream one text token into the target, or (done) settle it" },
|
|
27
|
+
{ kind: "spotlight", means: "show the AI as actor — dim everything, light (and optionally pulse) the target" },
|
|
28
|
+
{ kind: "log", means: "append one provenance-tagged entry to the interaction timeline (the unified human+AI log)" },
|
|
29
|
+
{ kind: "navigate", means: "change the browser's location (href) — same-origin, root-relative only" },
|
|
30
|
+
{ kind: "choices", means: "the AI asks the human to pick — a chat bubble with a row of choice buttons (each a chat.send)" },
|
|
31
|
+
{ kind: "fill", means: "prefill a registered form field's value — persists for human review (the AI never submits)" },
|
|
32
|
+
];
|
|
33
|
+
|
|
34
|
+
// The one door's HTTP surface (AI-INTERFACE.md) — guarded by vocab-reference.test.ts
|
|
35
|
+
// against the literal path strings in tjakoen.github.io/routes/ai-routes.ts.
|
|
36
|
+
export const ENDPOINTS: readonly { method: string; path: string; means: string }[] = [
|
|
37
|
+
{ method: "POST", path: "/intent", means: "the one door — every human/AI interaction enters here" },
|
|
38
|
+
{ method: "GET", path: "/stream", means: "the per-session SSE channel render ops are pushed back over" },
|
|
39
|
+
{ method: "GET", path: "/ai/manifest", means: "the machine-readable index of what's operable right now" },
|
|
40
|
+
];
|
|
41
|
+
|
|
42
|
+
// Every SurfaceKind currently reachable by at least one verb — derived from the real
|
|
43
|
+
// ACTIONS registry, not hand-listed (a kind no verb accepts wouldn't show; today every
|
|
44
|
+
// declared SurfaceKind accepts at least one verb, so this reconstructs the full set).
|
|
45
|
+
function surfaceKindsInUse(): SurfaceKind[] {
|
|
46
|
+
const kinds = new Set<SurfaceKind>();
|
|
47
|
+
for (const a of Object.values(ACTIONS)) for (const k of a.accepts) kinds.add(k);
|
|
48
|
+
return [...kinds].sort();
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
async function readTokenSlots(variablesCssPath: string): Promise<{ name: string; value: string }[]> {
|
|
52
|
+
const css = await Bun.file(variablesCssPath).text();
|
|
53
|
+
const root = css.match(/:root\s*{([^}]*)}/s)?.[1] ?? "";
|
|
54
|
+
const out: { name: string; value: string }[] = [];
|
|
55
|
+
for (const m of root.matchAll(/(--[a-z0-9-]+)\s*:\s*([^;]+);/g)) out.push({ name: m[1], value: m[2].trim() });
|
|
56
|
+
return out;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
const table = (head: string[], rows: string[][]) =>
|
|
60
|
+
`<table><thead><tr>${head.map((h) => `<th>${esc(h)}</th>`).join("")}</tr></thead>` +
|
|
61
|
+
`<tbody>${rows.map((r) => `<tr>${r.map((c) => `<td>${c}</td>`).join("")}</tr>`).join("")}</tbody></table>`;
|
|
62
|
+
|
|
63
|
+
/** The reference page's BODY content (no page shell — the composition root wraps it). */
|
|
64
|
+
export async function buildVocabReference(variablesCssPath: string): Promise<string> {
|
|
65
|
+
// payload + description are DERIVED from the registry too (never a hand-copied column): a field
|
|
66
|
+
// renders as name*:type (star = required), so the generated reference shows HOW to call each verb.
|
|
67
|
+
const payloadCell = (payload: ActionDef["payload"]): string => {
|
|
68
|
+
const fields = Object.entries(payload)
|
|
69
|
+
.map(([name, f]) => `<code>${esc(name)}${f.required ? "*" : ""}:${esc(f.type)}</code>${f.note ? ` <span class="muted">(${esc(f.note)})</span>` : ""}`);
|
|
70
|
+
return fields.length ? fields.join(", ") : `<span class="muted">no args</span>`;
|
|
71
|
+
};
|
|
72
|
+
// hints (MCP-style annotations) render as flags; a verb with none reads "—".
|
|
73
|
+
const hintsCell = (hints: ActionDef["hints"]): string => {
|
|
74
|
+
const flags = Object.entries(hints).filter(([, v]) => v).map(([k]) => `<code>${esc(k)}</code>`);
|
|
75
|
+
return flags.length ? flags.join(", ") : `<span class="muted">—</span>`;
|
|
76
|
+
};
|
|
77
|
+
const actionRows = Object.values(ACTIONS)
|
|
78
|
+
.map((a) => [`<code>${esc(a.name)}</code>`, payloadCell(a.payload),
|
|
79
|
+
a.accepts.map((k) => `<code>${esc(k)}</code>`).join(", "), esc(a.depth), hintsCell(a.hints), esc(a.description)]);
|
|
80
|
+
const kindRows = surfaceKindsInUse().map((k) => [`<code>${esc(k)}</code>`]);
|
|
81
|
+
const opRows = RENDER_OP_KINDS.map((o) => [`<code>${esc(o.kind)}</code>`, esc(o.means)]);
|
|
82
|
+
const endpointRows = ENDPOINTS.map((e) => [`<code>${esc(e.method)} ${esc(e.path)}</code>`, esc(e.means)]);
|
|
83
|
+
const tokens = await readTokenSlots(variablesCssPath);
|
|
84
|
+
const tokenRows = tokens.map((t) => [`<code>${esc(t.name)}</code>`, `<code>${esc(t.value)}</code>`]);
|
|
85
|
+
|
|
86
|
+
return `
|
|
87
|
+
<div class="section-head"><span>Actions</span></div>
|
|
88
|
+
<p class="muted">Generated from <code>grain/ai/contract.ts</code>'s <code>ACTIONS</code> registry — the single source of truth. Payload fields marked <code>*</code> are required; hints are MCP-style behaviour flags.</p>
|
|
89
|
+
${table(["verb", "payload", "accepts (surface kinds)", "depth", "hints", "what it does"], actionRows)}
|
|
90
|
+
|
|
91
|
+
<div class="section-head"><span>Surface kinds</span></div>
|
|
92
|
+
<p class="muted">Every kind at least one verb above accepts.</p>
|
|
93
|
+
${table(["kind"], kindRows)}
|
|
94
|
+
|
|
95
|
+
<div class="section-head"><span>Render ops</span></div>
|
|
96
|
+
<p class="muted">The effect kinds the client dispatcher applies (see <a href="/grain/docs/ai-interface">AI-INTERFACE.md</a>).</p>
|
|
97
|
+
${table(["op", "means"], opRows)}
|
|
98
|
+
|
|
99
|
+
<div class="section-head"><span>The one door</span></div>
|
|
100
|
+
<p class="muted">The HTTP surface every human/AI interaction enters through.</p>
|
|
101
|
+
${table(["endpoint", "means"], endpointRows)}
|
|
102
|
+
|
|
103
|
+
<div class="section-head"><span>Token slots</span></div>
|
|
104
|
+
<p class="muted">Every custom property GRAIN's default theme sets on <code>:root</code> — override these to re-skin (see <a href="/grain/docs/re-skin-via-tokens">RE-SKIN-VIA-TOKENS.md</a>), never a component's own CSS.</p>
|
|
105
|
+
${table(["token", "default value"], tokenRows)}
|
|
106
|
+
`;
|
|
107
|
+
}
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
// grain/ai/webllm.test.ts — UNIT: the WebGPU probe. loadEngine itself does a real CDN dynamic import,
|
|
2
|
+
// so it isn't unit-tested (no network in tests); webgpuAvailable is pure logic over a probed navigator,
|
|
3
|
+
// so we drive it with a fake navigator on globalThis and prove every gate. Each test restores the
|
|
4
|
+
// original navigator so the suite stays order-independent.
|
|
5
|
+
import { test, expect, afterEach } from "bun:test";
|
|
6
|
+
import { webgpuAvailable, probeDevice, canRunModel } from "./webllm.ts";
|
|
7
|
+
|
|
8
|
+
const g = globalThis as unknown as { navigator?: unknown };
|
|
9
|
+
const original = g.navigator;
|
|
10
|
+
afterEach(() => { g.navigator = original; });
|
|
11
|
+
|
|
12
|
+
function withNavigator(n: unknown): void { g.navigator = n; }
|
|
13
|
+
|
|
14
|
+
test("webgpuAvailable: no navigator → false", async () => {
|
|
15
|
+
withNavigator(undefined);
|
|
16
|
+
expect(await webgpuAvailable()).toBe(false);
|
|
17
|
+
});
|
|
18
|
+
|
|
19
|
+
test("webgpuAvailable: no gpu on navigator → false", async () => {
|
|
20
|
+
withNavigator({});
|
|
21
|
+
expect(await webgpuAvailable()).toBe(false);
|
|
22
|
+
});
|
|
23
|
+
|
|
24
|
+
test("webgpuAvailable: gpu.requestAdapter returns an adapter → true", async () => {
|
|
25
|
+
withNavigator({ gpu: { requestAdapter: async () => ({}) } });
|
|
26
|
+
expect(await webgpuAvailable()).toBe(true);
|
|
27
|
+
});
|
|
28
|
+
|
|
29
|
+
test("webgpuAvailable: gpu present but no adapter → false", async () => {
|
|
30
|
+
withNavigator({ gpu: { requestAdapter: async () => null } });
|
|
31
|
+
expect(await webgpuAvailable()).toBe(false);
|
|
32
|
+
});
|
|
33
|
+
|
|
34
|
+
test("webgpuAvailable: a known-low deviceMemory rules it out up front", async () => {
|
|
35
|
+
withNavigator({ deviceMemory: 2, gpu: { requestAdapter: async () => ({}) } });
|
|
36
|
+
expect(await webgpuAvailable()).toBe(false);
|
|
37
|
+
});
|
|
38
|
+
|
|
39
|
+
test("webgpuAvailable: absent deviceMemory never blocks (Firefox/Safari don't report it)", async () => {
|
|
40
|
+
withNavigator({ gpu: { requestAdapter: async () => ({}) } }); // no deviceMemory key
|
|
41
|
+
expect(await webgpuAvailable()).toBe(true);
|
|
42
|
+
});
|
|
43
|
+
|
|
44
|
+
test("webgpuAvailable: a throwing requestAdapter degrades to false, not a hang", async () => {
|
|
45
|
+
withNavigator({ gpu: { requestAdapter: async () => { throw new Error("no device"); } } });
|
|
46
|
+
expect(await webgpuAvailable()).toBe(false);
|
|
47
|
+
});
|
|
48
|
+
|
|
49
|
+
test("probeDevice: reports webgpu + deviceMemory + cores + maxBufferSize (for a tiering caller)", async () => {
|
|
50
|
+
withNavigator({ deviceMemory: 8, hardwareConcurrency: 8, gpu: { requestAdapter: async () => ({ limits: { maxBufferSize: 4294967292 } }) } });
|
|
51
|
+
expect(await probeDevice()).toEqual({ webgpu: true, deviceMemory: 8, cores: 8, maxBufferSize: 4294967292 });
|
|
52
|
+
});
|
|
53
|
+
|
|
54
|
+
test("probeDevice: absent deviceMemory → undefined, but cores still read (Safari omits memory, reports cores)", async () => {
|
|
55
|
+
withNavigator({ hardwareConcurrency: 8, gpu: { requestAdapter: async () => ({ limits: { maxBufferSize: 1073741824 } }) } });
|
|
56
|
+
expect(await probeDevice()).toEqual({ webgpu: true, deviceMemory: undefined, cores: 8, maxBufferSize: 1073741824 });
|
|
57
|
+
});
|
|
58
|
+
|
|
59
|
+
test("probeDevice: an adapter with no limits.maxBufferSize → undefined, never fabricated", async () => {
|
|
60
|
+
withNavigator({ hardwareConcurrency: 6, gpu: { requestAdapter: async () => ({}) } });
|
|
61
|
+
expect(await probeDevice()).toEqual({ webgpu: true, deviceMemory: undefined, cores: 6, maxBufferSize: undefined });
|
|
62
|
+
});
|
|
63
|
+
|
|
64
|
+
test("probeDevice: reports deviceMemory + cores even when WebGPU is absent (a caller still tiers/logs)", async () => {
|
|
65
|
+
withNavigator({ deviceMemory: 4, hardwareConcurrency: 4 });
|
|
66
|
+
expect(await probeDevice()).toEqual({ webgpu: false, deviceMemory: 4, cores: 4 });
|
|
67
|
+
});
|
|
68
|
+
|
|
69
|
+
test("probeDevice: a throwing requestAdapter degrades to webgpu:false, keeping deviceMemory + cores", async () => {
|
|
70
|
+
withNavigator({ deviceMemory: 8, hardwareConcurrency: 8, gpu: { requestAdapter: async () => { throw new Error("no device"); } } });
|
|
71
|
+
expect(await probeDevice()).toEqual({ webgpu: false, deviceMemory: 8, cores: 8 });
|
|
72
|
+
});
|
|
73
|
+
|
|
74
|
+
test("canRunModel: pure gate — webgpu AND not a known-tiny device", () => {
|
|
75
|
+
expect(canRunModel({ webgpu: true, deviceMemory: 8 })).toBe(true);
|
|
76
|
+
expect(canRunModel({ webgpu: true, deviceMemory: 2 })).toBe(false); // known-tiny → OOM even for the smallest
|
|
77
|
+
expect(canRunModel({ webgpu: true })).toBe(true); // unknown memory never blocks
|
|
78
|
+
expect(canRunModel({ webgpu: false, deviceMemory: 8 })).toBe(false); // no adapter → no model
|
|
79
|
+
});
|
package/ai/webllm.ts
ADDED
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
// grain/ai/webllm.ts — grain's ONE WebGPU/CDN transport edge: load an in-browser model (WebLLM over
|
|
2
|
+
// WebGPU) as a `StreamingChatEngine` (model-chat.ts). This is the concrete transport a composition root
|
|
3
|
+
// picks; it is NOT imported by the reasoning core (model.ts) — the core stays pure + DOM-free, and this
|
|
4
|
+
// module is the single place that touches `navigator.gpu` and the CDN. That mirrors the OpChannel
|
|
5
|
+
// substrate PORT (contract.ts §19.3): one engine shape, many loaders; the root chooses.
|
|
6
|
+
//
|
|
7
|
+
// CLIENT-SAFE (ARCHITECTURE §19.2): no BARE npm import (the module server refuses those) — WebLLM is
|
|
8
|
+
// pulled from a pinned https URL via dynamic import, so there is NO package.json entry and no bundling.
|
|
9
|
+
// The URL is held in a variable so tsc treats the import as `any` (it can't resolve a URL specifier)
|
|
10
|
+
// rather than failing to type it. The engine's published types are never imported either — grain
|
|
11
|
+
// depends on the STRUCTURAL `StreamingChatEngine`, so there is no `@mlc-ai/web-llm` devDependency.
|
|
12
|
+
//
|
|
13
|
+
// WHAT'S PARAMETERIZED: the model id, the CDN pin, and the context window all come from the caller —
|
|
14
|
+
// grain owns the machinery, the app owns the model choice. Weights (hundreds of MB) come from the model
|
|
15
|
+
// host's CDN on first use and are cached by the browser's Cache API; a second visit skips the download.
|
|
16
|
+
// GitHub Pages can't send COOP/COEP, so this is WebGPU-only (no SharedArrayBuffer path) — exactly the
|
|
17
|
+
// gate `webgpuAvailable` enforces up front.
|
|
18
|
+
|
|
19
|
+
import type { StreamingChatEngine } from "./model-chat.ts";
|
|
20
|
+
|
|
21
|
+
// A recent, widely-mirrored esm.run pin. Overridable per call — a root that wants a different version
|
|
22
|
+
// (or a self-hosted mirror) passes `webllmUrl`; pinned by default so a CDN-side change can't silently
|
|
23
|
+
// alter behaviour.
|
|
24
|
+
const DEFAULT_WEBLLM_URL = "https://esm.run/@mlc-ai/web-llm@0.2.79";
|
|
25
|
+
const DEFAULT_CONTEXT_WINDOW = 2048;
|
|
26
|
+
|
|
27
|
+
/** Model-load progress, normalized from WebLLM's initProgressCallback. */
|
|
28
|
+
export interface EngineProgress {
|
|
29
|
+
progress: number; // 0..1
|
|
30
|
+
text: string; // the engine's human-readable status ("Fetching param cache…")
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
export interface LoadEngineOptions {
|
|
34
|
+
/** The model id to load (e.g. "Qwen2.5-0.5B-Instruct-q4f16_1-MLC"). The app's choice, not grain's. */
|
|
35
|
+
modelId: string;
|
|
36
|
+
/** Progress ticks during the one-time weight download — drive a progress bar with these. */
|
|
37
|
+
onProgress?: (p: EngineProgress) => void;
|
|
38
|
+
/** Override the pinned CDN url (a different version, or a self-hosted mirror). */
|
|
39
|
+
webllmUrl?: string;
|
|
40
|
+
/** The engine's context window in tokens (default 2048 — a small model wants a small window). */
|
|
41
|
+
contextWindow?: number;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
// Narrow shims for the browser globals we probe — grain's tsc has no DOM lib (bun-types only), so we
|
|
45
|
+
// reach them through a typed view of globalThis rather than pulling the whole DOM in.
|
|
46
|
+
interface GpuAdapterLike { limits?: { maxBufferSize?: number } }
|
|
47
|
+
interface GpuAdapterSource { requestAdapter(): Promise<GpuAdapterLike | null> }
|
|
48
|
+
interface ProbeNavigator { gpu?: GpuAdapterSource; deviceMemory?: number; hardwareConcurrency?: number }
|
|
49
|
+
const nav = (): ProbeNavigator | undefined =>
|
|
50
|
+
(globalThis as unknown as { navigator?: ProbeNavigator }).navigator;
|
|
51
|
+
|
|
52
|
+
/** What a WebGPU/memory probe reports about this device — enough for a caller to both GATE (can a
|
|
53
|
+
* model run at all?) and TIER (which size fits?). `deviceMemory` is coarse (GB, capped at 8) and
|
|
54
|
+
* Chrome-only — Firefox/Safari omit it, so `undefined` means "unknown", never "small". A tiering
|
|
55
|
+
* caller combines these: `deviceMemory` where present, else `cores` + `maxBufferSize`. */
|
|
56
|
+
export interface DeviceCapability {
|
|
57
|
+
/** A WebGPU adapter is present (the hard requirement — no adapter, no model). */
|
|
58
|
+
webgpu: boolean;
|
|
59
|
+
/** `navigator.deviceMemory` when the browser reports it, else undefined. */
|
|
60
|
+
deviceMemory?: number;
|
|
61
|
+
/** `navigator.hardwareConcurrency` (logical cores) — a device-class signal that survives where
|
|
62
|
+
* deviceMemory is absent: Safari omits deviceMemory but reports cores (a Mac is 8+, an iPhone ~6). */
|
|
63
|
+
cores?: number;
|
|
64
|
+
/** The WebGPU adapter's `maxBufferSize` limit in bytes — a GPU-capacity signal for TIERING. NOTE:
|
|
65
|
+
* Safari CAPS this (~1GB even on an Apple-Silicon Mac that Chrome reports at 4GB), so a raw
|
|
66
|
+
* threshold separates device classes only where a browser reports it truthfully; on Safari pair it
|
|
67
|
+
* with `cores`. Undefined when there's no adapter or the browser doesn't expose the limit. */
|
|
68
|
+
maxBufferSize?: number;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/** Probe the device once and report its raw capability. Any throw degrades to `webgpu: false` (a caller
|
|
72
|
+
* degrades honestly rather than hang). This is the single probe; `webgpuAvailable` and `canRunModel`
|
|
73
|
+
* are thin readings of it, and a tiering caller maps the fields to a model choice itself. */
|
|
74
|
+
export async function probeDevice(): Promise<DeviceCapability> {
|
|
75
|
+
const n = nav();
|
|
76
|
+
const deviceMemory = typeof n?.deviceMemory === "number" ? n.deviceMemory : undefined;
|
|
77
|
+
const cores = typeof n?.hardwareConcurrency === "number" ? n.hardwareConcurrency : undefined;
|
|
78
|
+
if (!n || !n.gpu || typeof n.gpu.requestAdapter !== "function") return { webgpu: false, deviceMemory, cores };
|
|
79
|
+
try {
|
|
80
|
+
const adapter = await n.gpu.requestAdapter();
|
|
81
|
+
const maxBufferSize = typeof adapter?.limits?.maxBufferSize === "number" ? adapter.limits.maxBufferSize : undefined;
|
|
82
|
+
return { webgpu: Boolean(adapter), deviceMemory, cores, maxBufferSize };
|
|
83
|
+
} catch {
|
|
84
|
+
return { webgpu: false, deviceMemory, cores };
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
/** Would ANY local WebLLM model load here? WebGPU present AND not a known-tiny device — a `deviceMemory`
|
|
89
|
+
* under 4 (when reported) is an almost-certain OOM even for the smallest model. Pure over a probe, so a
|
|
90
|
+
* caller can reuse one `probeDevice()` result for both this gate and its own size tiering. */
|
|
91
|
+
export function canRunModel(cap: DeviceCapability): boolean {
|
|
92
|
+
if (typeof cap.deviceMemory === "number" && cap.deviceMemory < 4) return false;
|
|
93
|
+
return cap.webgpu;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
/** Can this browser run a local WebLLM model? The gate above applied to a fresh probe — kept as the
|
|
97
|
+
* one-call convenience the up-front UX check uses. Any throw counts as unavailable. */
|
|
98
|
+
export async function webgpuAvailable(): Promise<boolean> {
|
|
99
|
+
return canRunModel(await probeDevice());
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
// The sliver of WebLLM's module surface we call — structural, so there's no SDK import. `CreateMLCEngine`
|
|
103
|
+
// builds and warms an engine; the result is asserted to `StreamingChatEngine` (model-chat.ts).
|
|
104
|
+
interface WebLLMModule {
|
|
105
|
+
CreateMLCEngine(
|
|
106
|
+
modelId: string,
|
|
107
|
+
opts: { initProgressCallback: (r: { progress?: number; text?: string }) => void },
|
|
108
|
+
config: { context_window_size: number },
|
|
109
|
+
): Promise<unknown>;
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
/** Load and warm a WebLLM engine, reporting download progress, as a `StreamingChatEngine` ready for
|
|
113
|
+
* `streamChat` (model-chat.ts). Dynamic-imports WebLLM from the pinned URL (held in a variable so tsc
|
|
114
|
+
* yields `Promise<any>` rather than trying to resolve a URL specifier). Throws on any failure — the
|
|
115
|
+
* caller degrades (e.g. an offline notice), grain never swallows it. */
|
|
116
|
+
export async function loadEngine(opts: LoadEngineOptions): Promise<StreamingChatEngine> {
|
|
117
|
+
const url = opts.webllmUrl ?? DEFAULT_WEBLLM_URL; // non-literal → tsc treats the import as `any`
|
|
118
|
+
const webllm = (await import(url)) as WebLLMModule;
|
|
119
|
+
const engine = await webllm.CreateMLCEngine(
|
|
120
|
+
opts.modelId,
|
|
121
|
+
{ initProgressCallback: (r) => opts.onProgress?.({ progress: r.progress ?? 0, text: r.text ?? "" }) },
|
|
122
|
+
{ context_window_size: opts.contextWindow ?? DEFAULT_CONTEXT_WINDOW },
|
|
123
|
+
);
|
|
124
|
+
return engine as StreamingChatEngine;
|
|
125
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 360" role="img" aria-label="Sample figure: an abstract field of grain strokes">
|
|
2
|
+
<!-- Neutral doc-example image for the figure component (referenced from figure.md).
|
|
3
|
+
Fixed grays on purpose: this is content, not themed UI chrome. -->
|
|
4
|
+
<rect width="640" height="360" fill="#efece6"/>
|
|
5
|
+
<g stroke="#8a857c" stroke-width="3" stroke-linecap="round" fill="none">
|
|
6
|
+
<path d="M80 300 q6 -60 0 -120 m0 -30 q-18 24 -36 30 m36 -30 q18 24 36 30"/>
|
|
7
|
+
<path d="M180 305 q-6 -70 0 -135 m0 -30 q-18 24 -36 30 m36 -30 q18 24 36 30"/>
|
|
8
|
+
<path d="M280 298 q8 -55 0 -110 m0 -30 q-18 24 -36 30 m36 -30 q18 24 36 30"/>
|
|
9
|
+
<path d="M380 306 q-8 -72 0 -140 m0 -30 q-18 24 -36 30 m36 -30 q18 24 36 30"/>
|
|
10
|
+
<path d="M480 300 q6 -62 0 -122 m0 -30 q-18 24 -36 30 m36 -30 q18 24 36 30"/>
|
|
11
|
+
<path d="M560 304 q-5 -50 0 -100 m0 -30 q-18 24 -36 30 m36 -30 q18 24 36 30"/>
|
|
12
|
+
</g>
|
|
13
|
+
<line x1="40" y1="312" x2="600" y2="312" stroke="#c9c3b8" stroke-width="2"/>
|
|
14
|
+
</svg>
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
<!-- grain/assets/sprite.svg — GRAIN's monochrome line-icon set, served at /assets/sprite.svg.
|
|
2
|
+
One <symbol> per glyph; stroke="currentColor" so an icon inherits ink/grain from its
|
|
3
|
+
surroundings (b-icon references these via <use href="…#name">). 24×24 grid, 1.6 stroke. -->
|
|
4
|
+
<svg xmlns="http://www.w3.org/2000/svg" style="display:none" aria-hidden="true">
|
|
5
|
+
<symbol id="loop" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M4 12a8 8 0 1 1 2.3 5.6"/><path d="M4 20v-4h4"/></symbol>
|
|
6
|
+
<symbol id="tasks" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><rect x="4" y="5" width="16" height="14" rx="2"/><path d="M8 11l2.5 2.5L16 8"/></symbol>
|
|
7
|
+
<symbol id="knowledge" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M5 5h11a3 3 0 0 1 3 3v11H8a3 3 0 0 1-3-3z"/><path d="M8 5v11"/></symbol>
|
|
8
|
+
<symbol id="rules" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M4 8h9M4 16h5"/><circle cx="17" cy="8" r="2.4"/><circle cx="13" cy="16" r="2.4"/></symbol>
|
|
9
|
+
<symbol id="traces" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M4 13l4 1 3-8 3 14 3-7h3"/></symbol>
|
|
10
|
+
<symbol id="settings" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="3"/><path d="M12 3v3M12 18v3M3 12h3M18 12h3M6 6l2 2M16 16l2 2M18 6l-2 2M8 16l-2 2"/></symbol>
|
|
11
|
+
<symbol id="menu" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M4 7h16M4 12h16M4 17h16"/></symbol>
|
|
12
|
+
<symbol id="close" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M6 6l12 12M18 6L6 18"/></symbol>
|
|
13
|
+
<symbol id="chevron-left" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M15 6l-6 6 6 6"/></symbol>
|
|
14
|
+
<symbol id="chevron-right" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M9 6l6 6-6 6"/></symbol>
|
|
15
|
+
<symbol id="send" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M4 12l16-8-6 16-3-6-7-2z"/></symbol>
|
|
16
|
+
<symbol id="search" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><circle cx="11" cy="11" r="6"/><path d="M20 20l-4-4"/></symbol>
|
|
17
|
+
<symbol id="spark" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M12 4v16M4 12h16M6.3 6.3l11.4 11.4M17.7 6.3L6.3 17.7"/></symbol>
|
|
18
|
+
<symbol id="check" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M5 12l4 4 10-10"/></symbol>
|
|
19
|
+
<symbol id="plus" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M12 5v14M5 12h14"/></symbol>
|
|
20
|
+
<symbol id="files" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M9 4h6l4 4v8a2 2 0 0 1-2 2H9a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2z"/><path d="M15 4v4h4"/><path d="M5 8v10a2 2 0 0 0 2 2h8"/></symbol>
|
|
21
|
+
<symbol id="pin" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M12 17v4"/><path d="M9 3h6l-1 6 3 3H7l3-3z"/></symbol>
|
|
22
|
+
</svg>
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
// grain/catalog/catalog.test.ts — the catalog page shell honors the injection seams.
|
|
2
|
+
// The catalog builds its OWN <html> shell (it isn't a pages/ file), so it must accept the
|
|
3
|
+
// same global assets the page server injects — otherwise it becomes the one page that
|
|
4
|
+
// drifts from the rest (the saved-theme bug that motivated the seam).
|
|
5
|
+
import { expect, test, describe, beforeAll, afterAll } from "bun:test";
|
|
6
|
+
import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
|
|
7
|
+
import { tmpdir } from "node:os";
|
|
8
|
+
import { join } from "node:path";
|
|
9
|
+
import { createCatalog } from "./catalog.ts";
|
|
10
|
+
|
|
11
|
+
describe("createCatalog inject seams", () => {
|
|
12
|
+
let dir: string;
|
|
13
|
+
|
|
14
|
+
beforeAll(async () => {
|
|
15
|
+
dir = await mkdtemp(join(tmpdir(), "batch-catalog-"));
|
|
16
|
+
await mkdir(join(dir, "atoms", "b-x"), { recursive: true });
|
|
17
|
+
await writeFile(join(dir, "atoms", "b-x", "b-x.md"), `# B X\n\nA test atom.\n`);
|
|
18
|
+
});
|
|
19
|
+
afterAll(() => rm(dir, { recursive: true, force: true }));
|
|
20
|
+
|
|
21
|
+
test("headEnd lands in <head>, bodyEnd before </body>", async () => {
|
|
22
|
+
const catalog = createCatalog(dir, undefined,
|
|
23
|
+
{ headEnd: `<script src="/boot.js"></script>`, bodyEnd: `<script src="/island.js" defer></script>` });
|
|
24
|
+
const html = await catalog.html();
|
|
25
|
+
const head = html.slice(0, html.indexOf("</head>"));
|
|
26
|
+
const body = html.slice(html.indexOf("<body>"));
|
|
27
|
+
expect(head).toContain(`<script src="/boot.js"></script>`);
|
|
28
|
+
expect(body).toContain(`<script src="/island.js" defer></script>`);
|
|
29
|
+
});
|
|
30
|
+
|
|
31
|
+
test("no inject → shell renders without placeholders", async () => {
|
|
32
|
+
const catalog = createCatalog(dir);
|
|
33
|
+
const html = await catalog.html();
|
|
34
|
+
expect(html).toContain("<title>Component Catalog</title>");
|
|
35
|
+
expect(html).not.toContain("undefined");
|
|
36
|
+
});
|
|
37
|
+
});
|