claude-artifact-framework 0.4.0 → 0.5.0

package/src/app.js

@@ -15,14 +15,23 @@ import { themeCss, seriesColors } from "./theme.js";
 import { BLOCKS, BLOCK_NAMES } from "./blocks.js";
 import { RecordsLayout } from "./records.js";
 import { StepsLayout } from "./steps.js";
+import { ChatLayout, CHAT_KEYS } from "./chat.js";
 
-const LAYOUTS = ["panel", "records", "steps"];
+const LAYOUTS = ["panel", "records", "steps", "chat"];
 const RESERVED = ["title", "empty", "wide", "onSelect", "subtitle"];
 
 // Frontier models still invent identifiers a few percent of the time, so an
 // unknown name has to fail loudly and name the alternatives rather than
 // silently rendering nothing — a blank pane is indistinguishable from a bug.
+const TOP_KEYS = ["title", "subtitle", "theme", "layout", "blocks", "records", "steps", "chat", "data", "shared"];
+
 function validate(spec) {
+  const unknownTop = Object.keys(spec).filter((k) => !TOP_KEYS.includes(k));
+  if (unknownTop.length) {
+    throw new Error(
+      `claude-artifact-framework: unknown top-level keys (${unknownTop.join(", ")}). Valid keys: ${TOP_KEYS.join(", ")}.`
+    );
+  }
   const layout = spec.layout || "panel";
   if (!LAYOUTS.includes(layout)) {
     throw new Error(
@@ -61,6 +70,28 @@ function validate(spec) {
     });
     return layout;
   }
+  if (layout === "chat") {
+    const c = spec.chat;
+    if (!c || (typeof c.system !== "string" && typeof c.system !== "function")) {
+      throw new Error(
+        'claude-artifact-framework: layout "chat" needs `chat: { system: "..." }` (a string or a function of data).'
+      );
+    }
+    const unknown = Object.keys(c).filter((k) => !CHAT_KEYS.includes(k));
+    if (unknown.length) {
+      throw new Error(
+        `claude-artifact-framework: chat has unknown keys (${unknown.join(", ")}). Valid keys: ${CHAT_KEYS.join(", ")}.`
+      );
+    }
+    for (const [name, tool] of Object.entries(c.tools || {})) {
+      if (!tool || typeof tool.description !== "string" || typeof tool.run !== "function") {
+        throw new Error(
+          `claude-artifact-framework: chat tool "${name}" needs a \`description\` string and a \`run(input, ctx)\` function.`
+        );
+      }
+    }
+    return layout;
+  }
   if (layout === "records") {
     const r = spec.records;
     if (!r || !Array.isArray(r.fields) || r.fields.length === 0) {
@@ -68,6 +99,13 @@ function validate(spec) {
         'claude-artifact-framework: layout "records" needs `records: { fields: [...] }` — the same field declarations the fields block uses.'
       );
     }
+    const RECORDS_KEYS = ["label", "fields", "title", "subtitle", "sort", "summary", "empty", "search", "compute"];
+    const unknownR = Object.keys(r).filter((k) => !RECORDS_KEYS.includes(k));
+    if (unknownR.length) {
+      throw new Error(
+        `claude-artifact-framework: records has unknown keys (${unknownR.join(", ")}). Valid keys: ${RECORDS_KEYS.join(", ")}.`
+      );
+    }
     const seen = new Set();
     for (const f of r.fields) {
       if (!f || !f.key) throw new Error("claude-artifact-framework: every records field needs a `key`.");
@@ -75,6 +113,18 @@ function validate(spec) {
       if (seen.has(f.key)) throw new Error(`claude-artifact-framework: duplicate records field key "${f.key}".`);
       seen.add(f.key);
     }
+    for (const [key, c] of Object.entries(r.compute || {})) {
+      if (seen.has(key) || key === "id") {
+        throw new Error(
+          `claude-artifact-framework: compute key "${key}" collides with a field key — computed values are derived, never stored.`
+        );
+      }
+      if (typeof c !== "function" && typeof (c && c.value) !== "function") {
+        throw new Error(
+          `claude-artifact-framework: compute "${key}" must be a function of the record, or { label, format, value: (r) => ... }.`
+        );
+      }
+    }
     return layout;
   }
   const blocks = spec.blocks || [];
@@ -113,6 +163,9 @@ function defaultsFrom(spec) {
   if ((spec.layout || "panel") === "records" && !Array.isArray(data.records)) {
     data.records = [];
   }
+  if ((spec.layout || "panel") === "chat" && !data.chat) {
+    data.chat = { api: [], log: [] };
+  }
   for (const block of [...(spec.blocks || []), ...(spec.steps || [])]) {
     for (const field of block.fields || []) {
       if (field && field.key !== undefined && !(field.key in data)) {
@@ -173,11 +226,11 @@ function Panel({ spec, ctx }) {
   );
 }
 
-const LAYOUT_COMPONENTS = { panel: Panel, records: RecordsLayout, steps: StepsLayout };
+const LAYOUT_COMPONENTS = { panel: Panel, records: RecordsLayout, steps: StepsLayout, chat: ChatLayout };
 
 export function createApp(spec = {}) {
   const layout = validate(spec);
-  const state = createAppState(defaultsFrom(spec));
+  const state = createAppState(defaultsFrom(spec), { shared: Boolean(spec.shared) });
   const css = themeCss(spec.theme && spec.theme.seed) + BASE_CSS;
 
   return function App() {
@@ -330,6 +383,25 @@ const BASE_CSS = `
 .caf-steps-fill { transition: width 0.25s ease; }
 .caf-step-text { margin: 0; color: var(--caf-muted); font-size: 0.92rem; line-height: 1.55; }
 .caf-step-nav { display: flex; justify-content: space-between; gap: 0.6rem; margin-top: 0.4rem; }
+.caf-chat-log { min-height: 320px; max-height: 62vh; overflow-y: auto; gap: 0.55rem; }
+.caf-msg { max-width: 85%; padding: 0.55rem 0.75rem; border-radius: 12px; font-size: 0.92rem; line-height: 1.5; white-space: pre-wrap; word-break: break-word; }
+.caf-msg-user { align-self: flex-end; background: var(--caf-accent); color: var(--caf-accentText); border-bottom-right-radius: 4px; }
+.caf-msg-assistant { align-self: flex-start; background: var(--caf-sunken); border-bottom-left-radius: 4px; }
+.caf-msg-live::after { content: "▍"; opacity: 0.6; }
+.caf-msg-tools { align-self: flex-start; font-size: 0.74rem; color: var(--caf-muted); padding: 0.15rem 0.55rem; border: 1px solid var(--caf-border); border-radius: 999px; }
+.caf-msg-error { align-self: stretch; max-width: none; display: flex; flex-direction: column; gap: 0.2rem; background: transparent; border: 1px solid var(--caf-danger); }
+.caf-msg-error strong { color: var(--caf-danger); font-size: 0.85rem; }
+.caf-chat-input { display: flex; gap: 0.6rem; margin-top: 0.8rem; }
+.caf-chat-input input { flex: 1; font: inherit; font-size: 0.95rem; padding: 0.55rem 0.7rem; border-radius: 8px; border: 1px solid var(--caf-border); background: var(--caf-surface); color: var(--caf-text); }
+.caf-chat-input input:focus-visible { outline: 2px solid var(--caf-accent); outline-offset: 1px; }
+.caf-search {
+  font: inherit; font-size: 0.9rem; width: 100%;
+  padding: 0.5rem 0.65rem; margin: 0 0 0.3rem;
+  border-radius: 7px; border: 1px solid var(--caf-border);
+  background: var(--caf-sunken); color: var(--caf-text);
+}
+.caf-search:focus-visible { outline: 2px solid var(--caf-accent); outline-offset: 1px; }
+.caf-computed { border-top: 1px solid var(--caf-border); padding-top: 0.7rem; }
 .caf-empty, .caf-loading { color: var(--caf-muted); font-size: 0.9rem; text-align: center; padding: 1.6rem 1rem; }
 .caf-block-error { border-color: var(--caf-danger); gap: 0.4rem; }
 .caf-block-error strong { font-size: 0.9rem; color: var(--caf-danger); }

package/src/appState.js

@@ -44,10 +44,20 @@ function debounce(fn, ms) {
   };
 }
 
-export function createAppState(defaults, { debounceMs = 400 } = {}) {
+// With `shared: true` the DATA pool lives in the shared storage scope, so
+// every viewer of a published artifact converges on the same data (polled,
+// last-write-wins). View state — navigation, selection, the open record —
+// stays personal ALWAYS: two people looking at the same list should not
+// fight over which screen is open.
+export function createAppState(defaults, { debounceMs = 400, shared = false, pollMs = 2500 } = {}) {
+  const dataStore = shared ? storage.shared : storage;
   let data = structuredCloneish(defaults);
   let view = { ...EMPTY_VIEW };
   let hydrated = false;
+  // Counts update() calls so a poll never overwrites edits that haven't been
+  // persisted yet: remote state only applies when we owe storage nothing.
+  let writes = 0;
+  let persistedWrites = 0;
   const listeners = new Set();
 
   // Notification is batched to a microtask: three mutations in a row produce
@@ -63,12 +73,32 @@ export function createAppState(defaults, { debounceMs = 400 } = {}) {
     });
   }
 
-  const persistData = debounce(() => storage.set(DATA_KEY, data), debounceMs);
+  const persistData = debounce(() => {
+    const at = writes;
+    Promise.resolve(dataStore.set(DATA_KEY, data)).then(() => {
+      persistedWrites = Math.max(persistedWrites, at);
+    }).catch(() => {});
+  }, debounceMs);
   const persistView = debounce(() => storage.set(VIEW_KEY, view), debounceMs);
 
+  if (shared) {
+    setInterval(async () => {
+      if (!hydrated || writes > persistedWrites) return; // local edits in flight win
+      try {
+        const remote = await dataStore.get(DATA_KEY, undefined);
+        if (remote !== undefined && JSON.stringify(remote) !== JSON.stringify(data)) {
+          data = mergeDefaults(defaults, remote);
+          notify();
+        }
+      } catch {
+        // a failed poll just means we try again next tick
+      }
+    }, pollMs);
+  }
+
   const ready = (async () => {
     const [storedData, storedView] = await Promise.all([
-      storage.get(DATA_KEY, undefined),
+      dataStore.get(DATA_KEY, undefined),
       storage.get(VIEW_KEY, undefined),
     ]);
     if (storedData !== undefined) data = mergeDefaults(defaults, storedData);
@@ -82,6 +112,7 @@ export function createAppState(defaults, { debounceMs = 400 } = {}) {
     // Handlers may either mutate the draft or return a replacement.
     if (result !== undefined) data = result;
     data = { ...data };
+    writes++;
     persistData();
     notify();
   }

package/src/chat.js

@@ -0,0 +1,248 @@
+// chat.js — the conversation layout: tutors, advisors, generators, roleplay.
+//
+// Every piece of the network contract here is copied from code proven inside
+// the real artifact runtime (the PDF annotator), not designed on paper:
+//
+//   endpoint    fetch("https://api.anthropic.com/v1/messages") with NO api
+//               key — the artifact runtime proxies the call and injects auth.
+//   streaming   stream: true works; SSE parsed via content_block_delta.
+//   tools       the proxy does NOT support native function calling. Tools are
+//               prompted: the model replies with a ```tool_call fenced block
+//               holding a JSON array; results go back as a user message
+//               tagged [TOOL_RESULT]; loop capped at 8 rounds.
+//
+// The author declares the system prompt and optionally tools that operate on
+// the app's data through ctx.update — a chat that can drive the app. The
+// framework owns everything that normally ships half-built: message state,
+// live streaming, the busy state, the tool loop, and errors as visible
+// bubbles instead of silent console noise.
+//
+// State split, same philosophy as data/view: `api` holds the exact messages
+// the API needs (including raw tool_call text and [TOOL_RESULT] payloads);
+// `log` holds what a human should see (stripped text, tool pills, errors).
+// Both persist under data.chat, so a conversation survives reload. The
+// in-flight streaming bubble is deliberately ephemeral local state.
+
+import { createElement as h, useState, useEffect, useRef } from "react";
+
+export const CHAT_KEYS = ["system", "greeting", "placeholder", "tools", "model", "maxTokens"];
+
+// Proven default through the artifact proxy.
+const DEFAULT_MODEL = "claude-sonnet-4-6";
+const MAX_ROUNDS = 8;
+
+async function streamCall({ model, maxTokens, system, messages, onText }) {
+  const res = await fetch("https://api.anthropic.com/v1/messages", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ model, max_tokens: maxTokens, system, messages, stream: true }),
+  });
+  if (!res.ok || !res.body) {
+    let detail = "";
+    try {
+      const b = await res.json();
+      detail = (b && b.error && b.error.message) || JSON.stringify(b);
+    } catch {
+      detail = await res.text().catch(() => "");
+    }
+    throw new Error(`HTTP ${res.status}${detail ? ": " + detail : ""}`);
+  }
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let full = "";
+  let buf = ""; // reassembles SSE events split across network chunks
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buf += decoder.decode(value, { stream: true });
+    const lines = buf.split("\n");
+    buf = lines.pop();
+    for (const line of lines) {
+      if (!line.startsWith("data: ")) continue;
+      try {
+        const j = JSON.parse(line.slice(6));
+        if (j.type === "content_block_delta" && j.delta && j.delta.text) {
+          full += j.delta.text;
+          if (onText) onText(full);
+        }
+      } catch {
+        // non-JSON lines (pings, [DONE]) are expected — skip
+      }
+    }
+  }
+  return full;
+}
+
+export function parseToolCalls(text) {
+  const match = text.match(/```tool_call\s*\n?([\s\S]*?)```/);
+  if (!match) return null;
+  try {
+    const calls = JSON.parse(match[1]);
+    return Array.isArray(calls) && calls.length ? calls : null;
+  } catch {
+    return null;
+  }
+}
+
+export function stripToolCallBlock(text) {
+  return text.replace(/```tool_call\s*\n?[\s\S]*?```/, "").trim();
+}
+
+// The instructions the model needs to use prompted tools. Appended to the
+// author's system prompt only when tools are declared.
+function toolProtocol(tools) {
+  const list = Object.entries(tools)
+    .map(([name, t]) => `- ${name}: ${t.description}\n  Input: ${JSON.stringify(t.input || {})}`)
+    .join("\n");
+  return `
+
+You have tools available:
+${list}
+
+This environment does not support native function calling. To use a tool, reply ONLY with a \`\`\`tool_call code block containing a JSON array, with no other text in that turn. Example:
+
+\`\`\`tool_call
+[{ "name": "tool_name", "input": { "param": "value" } }]
+\`\`\`
+
+You may include several calls in one array. NEVER invent a tool's result — emit the pure tool_call block and wait for the real result, which arrives in the next message tagged [TOOL_RESULT]. When you have everything you need, answer in natural language with no tool_call block.`;
+}
+
+function runTools(calls, tools, ctx) {
+  return calls.map((call) => {
+    const tool = tools[call.name];
+    if (!tool) {
+      // Fed back to the model, loud and in-band: it can correct itself on the
+      // next round instead of hallucinating a result.
+      return { name: call.name, error: `unknown tool "${call.name}". Valid tools: ${Object.keys(tools).join(", ")}` };
+    }
+    try {
+      const result = tool.run(call.input || {}, ctx);
+      return { name: call.name, result: result === undefined ? { ok: true } : result };
+    } catch (e) {
+      return { name: call.name, error: String((e && e.message) || e) };
+    }
+  });
+}
+
+function Bubble({ m }) {
+  if (m.role === "tools") {
+    return h("div", { className: "caf-msg-tools" }, `used: ${m.tools.join(", ")}`);
+  }
+  if (m.role === "error") {
+    return h(
+      "div",
+      { className: "caf-msg caf-msg-error" },
+      h("strong", null, "The call failed"),
+      h("span", null, m.content),
+      h("span", { className: "caf-hint" }, "Your message is kept — send again to retry.")
+    );
+  }
+  return h("div", { className: m.role === "user" ? "caf-msg caf-msg-user" : "caf-msg caf-msg-assistant" }, m.content);
+}
+
+export function ChatLayout({ spec, ctx }) {
+  const c = spec.chat;
+  const [draft, setDraft] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [live, setLive] = useState(null);
+  const endRef = useRef(null);
+
+  const chat = ctx.data.chat || { api: [], log: [] };
+  const log = chat.log || [];
+
+  useEffect(() => {
+    if (endRef.current) endRef.current.scrollIntoView({ block: "end" });
+  }, [log.length, live]);
+
+  async function send() {
+    const text = draft.trim();
+    if (!text || busy) return;
+    setDraft("");
+    setBusy(true);
+
+    // api/log are threaded locally through the loop; ctx.data would be stale
+    // inside this closure after each update().
+    let api = [...(chat.api || []), { role: "user", content: text }];
+    let logNow = [...log, { role: "user", content: text }];
+    const commit = () => ctx.update((d) => { d.chat = { api, log: logNow }; });
+    commit();
+
+    try {
+      const system =
+        (typeof c.system === "function" ? c.system(ctx.data) : c.system || "") +
+        (c.tools ? toolProtocol(c.tools) : "");
+
+      for (let round = 0; round < MAX_ROUNDS; round++) {
+        const raw = await streamCall({
+          model: c.model || DEFAULT_MODEL,
+          maxTokens: c.maxTokens || 2000,
+          system,
+          messages: api,
+          onText: (t) => setLive(stripToolCallBlock(t)),
+        });
+
+        api = [...api, { role: "assistant", content: raw }];
+        const shown = stripToolCallBlock(raw);
+        const calls = c.tools ? parseToolCalls(raw) : null;
+
+        if (!calls) {
+          logNow = [...logNow, { role: "assistant", content: shown || raw }];
+          commit();
+          break;
+        }
+
+        const results = runTools(calls, c.tools, ctx);
+        if (shown) logNow = [...logNow, { role: "assistant", content: shown }];
+        logNow = [...logNow, { role: "tools", tools: calls.map((x) => x.name) }];
+        api = [
+          ...api,
+          {
+            role: "user",
+            content: `[TOOL_RESULT]\n${JSON.stringify(results)}\n[/TOOL_RESULT]\n\nContinue with this information. If you have everything you need, answer in natural language without further tool_call.`,
+          },
+        ];
+        commit();
+        setLive(null);
+      }
+    } catch (e) {
+      logNow = [...logNow, { role: "error", content: String((e && e.message) || e) }];
+      commit();
+    } finally {
+      setLive(null);
+      setBusy(false);
+    }
+  }
+
+  return h(
+    "div",
+    { className: "caf-panel caf-panel-single" },
+    h(
+      "div",
+      { className: "caf-block caf-chat-log" },
+      c.greeting ? h("div", { className: "caf-msg caf-msg-assistant" }, c.greeting) : null,
+      log.map((m, i) => h(Bubble, { key: i, m })),
+      live !== null ? h("div", { className: "caf-msg caf-msg-assistant caf-msg-live" }, live || "…") : null,
+      busy && live === null ? h("div", { className: "caf-msg-tools" }, "thinking…") : null,
+      h("div", { ref: endRef })
+    ),
+    h(
+      "form",
+      {
+        className: "caf-chat-input",
+        onSubmit: (e) => {
+          e.preventDefault();
+          send();
+        },
+      },
+      h("input", {
+        value: draft,
+        placeholder: c.placeholder || "Message…",
+        disabled: busy,
+        onChange: (e) => setDraft(e.target.value),
+        "aria-label": "Message",
+      }),
+      h("button", { type: "submit", className: "caf-btn caf-btn-primary", disabled: busy || !draft.trim() }, "Send")
+    )
+  );
+}

package/src/records.js

@@ -18,9 +18,29 @@
 // in data — restoring it on reload is correct, and deleting the open record
 // simply falls back to the list.
 
-import { createElement as h } from "react";
+import { createElement as h, useState } from "react";
 import { Field, formatValue } from "./blocks.js";
 
+// Computed fields are derived at render time and never stored, so they can't
+// go stale. Accepts `{ subtotal: (r) => ... }` or
+// `{ subtotal: { label, format, value: (r) => ... } }`.
+function computedEntries(spec) {
+  return Object.entries(spec.compute || {}).map(([k, v]) => [k, typeof v === "function" ? { value: v } : v]);
+}
+
+export function withComputed(spec, rec) {
+  if (!spec.compute) return rec;
+  const out = { ...rec };
+  for (const [key, c] of computedEntries(spec)) {
+    try {
+      out[key] = c.value(rec);
+    } catch {
+      out[key] = undefined;
+    }
+  }
+  return out;
+}
+
 export function recordDefaults(fields) {
   const rec = {};
   for (const f of fields) {
@@ -66,8 +86,16 @@ function Summary({ spec, records }) {
 
 function ListScreen({ spec, ctx }) {
   const label = spec.label || "item";
-  let records = ctx.data.records;
+  const [query, setQuery] = useState("");
+  let records = ctx.data.records.map((r) => withComputed(spec, r));
   if (spec.sort) records = records.slice().sort(spec.sort);
+  const total = records.length;
+  const q = query.trim().toLowerCase();
+  if (spec.search && q) {
+    records = records.filter((r) =>
+      spec.fields.some((f) => String(r[f.key] ?? "").toLowerCase().includes(q))
+    );
+  }
 
   function add() {
     const rec = { id: makeId(), ...recordDefaults(spec.fields) };
@@ -83,9 +111,25 @@ function ListScreen({ spec, ctx }) {
       h(
         "div",
         { className: "caf-toolbar" },
-        h("span", { className: "caf-count" }, `${records.length} ${label}${records.length === 1 ? "" : "s"}`),
+        h(
+          "span",
+          { className: "caf-count" },
+          spec.search && q ? `${records.length} of ${total}` : `${total} ${label}${total === 1 ? "" : "s"}`
+        ),
         h("button", { type: "button", className: "caf-btn caf-btn-primary", onClick: add }, `Add ${label}`)
       ),
+      spec.search
+        ? h("input", {
+            className: "caf-search",
+            value: query,
+            placeholder: `Search ${label}s…`,
+            "aria-label": "Search",
+            onChange: (e) => setQuery(e.target.value),
+          })
+        : null,
+      spec.search && q && records.length === 0 && total > 0
+        ? h("div", { className: "caf-empty" }, `Nothing matches "${query}".`)
+        : null,
       records.length === 0
         ? h("div", { className: "caf-empty" }, spec.empty || `No ${label}s yet. Add the first one.`)
         : records.map((rec) =>
@@ -134,7 +178,22 @@ function DetailScreen({ spec, ctx, record }) {
             if (rec) rec[field.key] = v;
           }),
       })
-    )
+    ),
+    spec.compute
+      ? h(
+          "div",
+          { className: "caf-output-grid caf-computed" },
+          computedEntries(spec).map(([key, c]) => {
+            const live = withComputed(spec, record);
+            return h(
+              "div",
+              { key, className: "caf-stat" },
+              h("span", { className: "caf-stat-label" }, c.label || key),
+              h("span", { className: "caf-stat-value" }, formatValue(live[key], c.format))
+            );
+          })
+        )
+      : null
   );
 }
 
@@ -152,7 +211,7 @@ export function RecordsLayout({ spec, ctx }) {
   return h(
     "div",
     { className: "caf-panel caf-panel-single" },
-    h(Summary, { spec: rspec, records: ctx.data.records }),
+    h(Summary, { spec: rspec, records: ctx.data.records.map((r) => withComputed(rspec, r)) }),
     h(ListScreen, { spec: rspec, ctx })
   );
 }