claude-artifact-framework 0.3.0 → 0.5.0

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 })
   );
 }

package/src/steps.js

@@ -0,0 +1,106 @@
+// steps.js — the wizard layout: quizzes, assessments, staged calculators,
+// long forms, onboarding.
+//
+// The author declares the sequence; next/back/progress/result are
+// framework-owned. Three rules keep it un-breakable:
+//
+//   one data pool   step fields write into the same flat `data` every other
+//                   block uses, so a result step is just a function of data —
+//                   no "collect answers" plumbing to half-build.
+//   gated next      Next is disabled while any field on the CURRENT step is
+//                   invalid; earlier steps are already valid by construction,
+//                   later ones aren't the user's problem yet.
+//   resumable       the current step lives in view state, so a reload lands
+//                   on the step the user was on, holding their answers.
+
+import { createElement as h } from "react";
+import { Field, validateField, formatValue } from "./blocks.js";
+
+function stepErrors(step, data) {
+  return (step.fields || []).some((f) => validateField(f, data[f.key]) !== null);
+}
+
+function ResultScreen({ step, ctx }) {
+  const items = step.result(ctx.data) || [];
+  return h(
+    "div",
+    { className: "caf-block caf-output" },
+    step.title ? h("h2", { className: "caf-block-title" }, step.title) : null,
+    h(
+      "div",
+      { className: "caf-output-grid" },
+      items.map((item, i) =>
+        h(
+          "div",
+          { key: item.label ?? i, className: item.big ? "caf-stat caf-stat-big" : "caf-stat" },
+          h("span", { className: "caf-stat-label" }, item.label),
+          h("span", { className: "caf-stat-value" }, formatValue(item.value, item.format)),
+          item.hint ? h("small", { className: "caf-hint" }, item.hint) : null
+        )
+      )
+    ),
+    h(
+      "div",
+      { className: "caf-step-nav" },
+      h("button", { type: "button", className: "caf-btn", onClick: () => ctx.setStep(0) }, "Start over")
+    )
+  );
+}
+
+export function StepsLayout({ spec, ctx }) {
+  const steps = spec.steps;
+  const i = Math.min(Math.max(ctx.view.step || 0, 0), steps.length - 1);
+  const step = steps[i];
+  const isResult = typeof step.result === "function";
+  const isLast = i === steps.length - 1;
+
+  return h(
+    "div",
+    { className: "caf-panel caf-panel-single" },
+    h(
+      "div",
+      { className: "caf-steps-progress" },
+      h("span", { className: "caf-hint" }, isResult ? "Result" : `Step ${i + 1} of ${steps.length}`),
+      h(
+        "div",
+        { className: "caf-bar-track" },
+        h("div", { className: "caf-bar-fill caf-steps-fill", style: { width: `${((i + 1) / steps.length) * 100}%` } })
+      )
+    ),
+    isResult
+      ? h(ResultScreen, { step, ctx })
+      : h(
+          "div",
+          { className: "caf-block caf-fields" },
+          step.title ? h("h2", { className: "caf-block-title" }, step.title) : null,
+          step.text ? h("p", { className: "caf-step-text" }, typeof step.text === "function" ? step.text(ctx.data) : step.text) : null,
+          (step.fields || []).map((field) =>
+            h(Field, {
+              key: field.key,
+              field,
+              value: ctx.data[field.key],
+              onChange: (v) => ctx.update((d) => { d[field.key] = v; }),
+            })
+          ),
+          h(
+            "div",
+            { className: "caf-step-nav" },
+            i > 0
+              ? h("button", { type: "button", className: "caf-btn", onClick: () => ctx.setStep(i - 1) }, "‹ Back")
+              : h("span"),
+            !isLast
+              ? h(
+                  "button",
+                  {
+                    type: "button",
+                    className: "caf-btn caf-btn-primary",
+                    disabled: stepErrors(step, ctx.data),
+                    onClick: () => ctx.setStep(i + 1),
+                  },
+                  "Next ›"
+                )
+              : null
+          )
+        )
+  );
+}

package/src/theme.js

@@ -146,3 +146,12 @@ export function themeCss(seed) {
 :root[data-theme="light"] { ${vars(p.light)} }
 `;
 }
+
+// Categorical series colors for charts, derived from the seed by golden-angle
+// hue rotation, so any number of segments stays distinguishable. Mid-tone
+// lightness reads on both the light and dark surface.
+export function seriesColors(seed, n) {
+  const [h0, s0] = rgbToHsl(hexToRgb(seed || "#3b6ef6"));
+  const s = clamp(s0, 45, 70);
+  return Array.from({ length: n }, (_, i) => hsl((h0 + i * 137.5) % 360, s, 52));
+}