claude-artifact-framework 0.13.1 → 0.14.1

package/llms.txt

@@ -0,0 +1,90 @@
+# claude-artifact-framework
+
+> Declarative framework for building apps inside Claude Artifacts. Declare what
+> the app IS (fields, records, steps, chat with tools, workspace, documents);
+> the framework owns persistence, hydration, validation, empty/loading/error
+> states, light+dark theming, navigation, and the Claude tool loop.
+> Full documentation: README.md (this file is the compact digest).
+
+Load (classic script, global `ArtifactKit`; call `ArtifactKit.useReact(React)` once):
+https://cdn.jsdelivr.net/npm/claude-artifact-framework/dist/index.global.js
+
+## Registries (any other name throws, naming the valid set)
+
+- Top-level keys: title, subtitle, theme:{seed}, layout, blocks, records,
+  steps, chat, main, sidebar, documents, data, shared, libs, machine
+- Layouts: panel (default), records, steps, chat, workspace, documents
+- Block types: fields, output, text, list, chart, timer, actions, chat, tabs,
+  records, custom — plus per-block title, when:(d)=>bool, state:"fase",
+  collapsible, wide, fill (custom only)
+- Field types: text, textarea, number, money, percent, check, date, select,
+  file — attrs: key, label, value, required, min, max, step, placeholder,
+  hint, rows, options (array or (d)=>array), accept
+- records spec: label, fields, title, subtitle, sort, summary, empty, search,
+  compute, items, actions (+ key when used as a block)
+- documents: label, title, blocks OR types, empty; machine: key, initial,
+  states, events (event: from, do, then); chat: system, greeting, placeholder,
+  tools, model, maxTokens; steps step: title, text, fields, result
+- Formats: money, percent (0-100), number, date. Output/chart/compute items:
+  { label, value, format, big }
+
+## Hard rules
+
+1. Write the spec INDENTED, never minified (measured: minified output drops
+   closing braces).
+2. Theme variables, never hardcoded hex: var(--caf-text), var(--caf-surface),
+   var(--caf-accent), var(--caf-border), var(--caf-sunken), var(--caf-muted),
+   var(--caf-danger); ctx.colors(n) for series. Hardcoded #fff breaks dark mode.
+3. Never render a <form> (sandbox lacks allow-forms) — inputs + button onClick.
+4. Never write big strings (data URLs, file contents) into data — one ~5MB
+   storage key holds the whole pool; big things live in React.useState or
+   ctx.files.
+5. Phases (games, turns, processes) belong to `machine` — ctx.send(event,
+   payload) is the only door; events are no-ops outside their `from` states;
+   `after: {seconds, then, do}` timers are framework-owned.
+6. Row actions receive (record, data, viewerId); block actions (data,
+   viewerId). Stop early if you like, but never skip a middle argument.
+7. One big:true per screen; the constructive action takes kind:"primary"; a
+   counter changed by pressing is an action, not an editable number field.
+8. Parts of a record are `items` — never JSON in a textarea.
+9. Don't hand-build empty/loading/error states — the framework owns them.
+10. CDN libs via libs:[urls]: call the method, not the global (marked.parse);
+    pin versions; unsure of the file path → bare package URL
+    (https://cdn.jsdelivr.net/npm/<pkg>@<version>).
+11. Framework record ids are strings — never Number(record.id).
+12. In custom blocks: return strings/React elements (never DOM elements — use
+    ref + React.useEffect for libs that write into an element); hooks are
+    allowed; persistent state via ctx.update, ephemeral via React.useState,
+    never createStore for UI state.
+
+## Canonical example
+
+ArtifactKit.createApp({
+  title: "Gastos",
+  theme: { seed: "#c2410c" },
+  layout: "records",
+  shared: false,
+  records: {
+    label: "gasto",
+    fields: [
+      { key: "concepto", label: "Concepto", type: "text", required: true },
+      { key: "monto", label: "Monto", type: "money", value: 0, min: 0 },
+      { key: "categoria", label: "Categoría", type: "select", options: ["comida", "transporte", "otros"] },
+    ],
+    subtitle: (r) => r.categoria,
+    summary: (all) => [
+      { label: "Total", value: all.reduce((s, r) => s + (Number(r.monto) || 0), 0), format: "money", big: true },
+    ],
+    actions: [{ label: "Duplicar", run: (r, d) => { d.records = [...d.records, { ...r, id: undefined }]; } }],
+  },
+  blocks: [
+    { chart: (d) => ({ type: "donut", format: "money", items: porCategoria(d.records) }), title: "Por categoría" },
+  ],
+})
+
+Chat with tools (workspace copilot): sidebar block
+{ title: "Asistente", chat: { system: (d) => "...", tools: { nombre: {
+  description: "...", input: { campo: "string" }, run: (input, ctx) => {
+  ctx.update((d) => { /* mutate */ }); return { ok: true }; } } } } }
+— the artifact runtime proxies api.anthropic.com with no API key; default
+model claude-sonnet-4-6; conversation persists under data.chat.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-artifact-framework",
-  "version": "0.13.1",
+  "version": "0.14.1",
   "description": "Utilities for building apps inside Claude Artifacts: platform storage, chat tool-calling loops, and other primitives verified against the real runtime.",
   "type": "module",
   "main": "./dist/index.esm.js",
@@ -12,16 +12,21 @@
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "llms.txt"
   ],
   "scripts": {
     "build": "node scripts/build.mjs",
     "build:watch": "node scripts/build.mjs --watch",
+    "test": "npm run build && node test/e2e.mjs",
     "prepublishOnly": "npm run build",
-    "release": "node scripts/check-docs.mjs && bash scripts/publish.sh"
+    "release": "node scripts/check-docs.mjs && npm test && bash scripts/publish.sh"
   },
   "devDependencies": {
-    "esbuild": "^0.25.0"
+    "esbuild": "^0.25.0",
+    "playwright-core": "^1.45.0",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0"
   },
   "license": "MIT",
   "author": "Alejandro Cuartas",

package/src/app.js

@@ -18,12 +18,17 @@ import { StepsLayout } from "./steps.js";
 import { ChatLayout, CHAT_KEYS } from "./chat.js";
 
 const LAYOUTS = ["panel", "records", "steps", "chat", "workspace", "documents"];
-const RESERVED = ["title", "empty", "wide", "onSelect", "subtitle", "when", "collapsible", "fill"];
+const RESERVED = ["title", "empty", "wide", "onSelect", "subtitle", "when", "collapsible", "fill", "state"];
 
 // 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", "main", "sidebar", "libs", "documents"];
+const TOP_KEYS = ["title", "subtitle", "theme", "layout", "blocks", "records", "steps", "chat", "data", "shared", "main", "sidebar", "libs", "documents", "machine"];
+
+const MACHINE_KEYS = ["key", "initial", "states", "events"];
+const MACHINE_STATE_KEYS = ["after"];
+const MACHINE_AFTER_KEYS = ["seconds", "then", "do"];
+const MACHINE_EVENT_KEYS = ["from", "do", "then"];
 
 const DOCUMENTS_KEYS = ["label", "title", "blocks", "empty", "types"];
 const RECORDS_KEYS = ["label", "fields", "title", "subtitle", "sort", "summary", "empty", "search", "compute", "items", "actions"];
@@ -140,6 +145,87 @@ function checkBlocks(blocks) {
   });
 }
 
+// The measured failure class behind this: hand-rolled phase logic (a memory
+// game fired its comparison logic in the wrong phase and died). The machine
+// makes illegal transitions inexpressible: ctx.send() is the only door, an
+// event is a no-op outside its `from` states, and `after` timers are
+// framework-owned.
+function checkMachine(m) {
+  const unknown = Object.keys(m).filter((k) => !MACHINE_KEYS.includes(k));
+  if (unknown.length) {
+    throw new Error(
+      `claude-artifact-framework: machine has unknown keys (${unknown.join(", ")}). Valid keys: ${MACHINE_KEYS.join(", ")}.`
+    );
+  }
+  if (m.key !== undefined && (typeof m.key !== "string" || !m.key)) {
+    throw new Error("claude-artifact-framework: machine.key must be a non-empty string (where the current state lives in data).");
+  }
+  const stateNames = Object.keys(m.states || {});
+  if (!stateNames.length) {
+    throw new Error("claude-artifact-framework: machine needs `states: { nombre: {...} }` with at least one state.");
+  }
+  const validState = (name, where) => {
+    if (!stateNames.includes(name)) {
+      throw new Error(
+        `claude-artifact-framework: ${where} names unknown state "${name}". Valid states: ${stateNames.join(", ")}.`
+      );
+    }
+  };
+  if (typeof m.initial !== "string") {
+    throw new Error("claude-artifact-framework: machine needs `initial: \"...\"` naming the starting state.");
+  }
+  validState(m.initial, "machine.initial");
+  for (const [name, st] of Object.entries(m.states)) {
+    const unknownS = Object.keys(st || {}).filter((k) => !MACHINE_STATE_KEYS.includes(k));
+    if (unknownS.length) {
+      throw new Error(
+        `claude-artifact-framework: machine.states.${name} has unknown keys (${unknownS.join(", ")}). Valid keys: ${MACHINE_STATE_KEYS.join(", ")}.`
+      );
+    }
+    if (st && st.after !== undefined) {
+      const a = st.after;
+      const unknownA = Object.keys(a || {}).filter((k) => !MACHINE_AFTER_KEYS.includes(k));
+      if (unknownA.length) {
+        throw new Error(
+          `claude-artifact-framework: machine.states.${name}.after has unknown keys (${unknownA.join(", ")}). Valid keys: ${MACHINE_AFTER_KEYS.join(", ")}.`
+        );
+      }
+      if (typeof a.seconds !== "number" || a.seconds <= 0) {
+        throw new Error(`claude-artifact-framework: machine.states.${name}.after needs \`seconds\` > 0.`);
+      }
+      if (typeof a.then !== "string") {
+        throw new Error(`claude-artifact-framework: machine.states.${name}.after needs \`then: "estado"\`.`);
+      }
+      validState(a.then, `machine.states.${name}.after.then`);
+      if (a.do !== undefined && typeof a.do !== "function") {
+        throw new Error(`claude-artifact-framework: machine.states.${name}.after.do must be a function of data.`);
+      }
+    }
+  }
+  const eventNames = Object.keys(m.events || {});
+  if (!eventNames.length) {
+    throw new Error("claude-artifact-framework: machine needs `events: { nombre: {...} }` — ctx.send() is the only way to move it.");
+  }
+  for (const [name, ev] of Object.entries(m.events)) {
+    const unknownE = Object.keys(ev || {}).filter((k) => !MACHINE_EVENT_KEYS.includes(k));
+    if (unknownE.length) {
+      throw new Error(
+        `claude-artifact-framework: machine.events.${name} has unknown keys (${unknownE.join(", ")}). Valid keys: ${MACHINE_EVENT_KEYS.join(", ")}.`
+      );
+    }
+    if (ev.from !== undefined && ev.from !== "*") {
+      for (const f of [].concat(ev.from)) validState(f, `machine.events.${name}.from`);
+    }
+    if (typeof ev.then === "string") validState(ev.then, `machine.events.${name}.then`);
+    else if (ev.then !== undefined && typeof ev.then !== "function") {
+      throw new Error(`claude-artifact-framework: machine.events.${name}.then must be a state name or a function of data returning one.`);
+    }
+    if (ev.do !== undefined && typeof ev.do !== "function") {
+      throw new Error(`claude-artifact-framework: machine.events.${name}.do must be a function (data, payload).`);
+    }
+  }
+}
+
 function validate(spec) {
   const unknownTop = Object.keys(spec).filter((k) => !TOP_KEYS.includes(k));
   if (unknownTop.length) {
@@ -147,6 +233,7 @@ function validate(spec) {
       `claude-artifact-framework: unknown top-level keys (${unknownTop.join(", ")}). Valid keys: ${TOP_KEYS.join(", ")}.`
     );
   }
+  if (spec.machine !== undefined) checkMachine(spec.machine);
   if (spec.libs !== undefined) {
     if (!Array.isArray(spec.libs) || spec.libs.some((u) => typeof u !== "string" || !/^https?:\/\//.test(u))) {
       throw new Error("claude-artifact-framework: `libs` must be an array of https:// script URLs.");
@@ -399,6 +486,10 @@ function defaultsFrom(spec) {
   if ((spec.layout || "panel") === "documents" && !Array.isArray(data.docs)) {
     data.docs = [];
   }
+  if (spec.machine) {
+    const k = spec.machine.key || "fase";
+    if (!(k in data)) data[k] = spec.machine.initial;
+  }
   const allBlocks = flattenBlocks([...(spec.blocks || []), ...(spec.main || []), ...(spec.sidebar || [])]);
   const hasChat = (spec.layout || "panel") === "chat" || allBlocks.some((b) => b && b.chat);
   if (hasChat && !data.chat) {
@@ -492,6 +583,8 @@ const ALL_NAMES = [...BLOCK_NAMES, "tabs", "records"];
 function Block({ block, ctx }) {
   // `when` hides a block entirely — the primitive under conditional UIs.
   if (typeof block.when === "function" && !block.when(ctx.data)) return null;
+  // `state: "x"` — machine sugar: the block exists only in that phase.
+  if (block.state !== undefined && ctx.machine && ctx.data[ctx.machine.key || "fase"] !== block.state) return null;
   const name = Object.keys(block).find((k) => ALL_NAMES.includes(k));
   const Component = ALL_BLOCKS[name];
   const inner = h(
@@ -829,8 +922,61 @@ function loadScript(src) {
   });
 }
 
+// Every block anywhere in the spec, including inside documents types — for
+// cross-cutting checks like `state:` against the machine's states.
+function everyBlock(spec) {
+  const docs = spec.documents
+    ? spec.documents.blocks || Object.values(spec.documents.types || {}).flatMap((t) => t.blocks || [])
+    : [];
+  return flattenBlocks([...(spec.blocks || []), ...(spec.main || []), ...(spec.sidebar || []), ...docs]);
+}
+
+// ctx.send(event, payload) — the machine's only door. Unknown event throws
+// (naming the valid ones); a legal event fired from the wrong phase is a
+// silent no-op (a user mashing buttons is normal, not a bug).
+function runMachineEvent(machine, update, eventName, payload) {
+  const ev = machine.events[eventName];
+  if (!ev) {
+    throw new Error(
+      `claude-artifact-framework: unknown machine event "${eventName}". Valid events: ${Object.keys(machine.events).join(", ")}.`
+    );
+  }
+  const key = machine.key || "fase";
+  update((d) => {
+    const current = d[key];
+    const from = ev.from === undefined ? "*" : ev.from;
+    if (from !== "*" && ![].concat(from).includes(current)) return;
+    if (ev.do) ev.do(d, payload);
+    const next = typeof ev.then === "function" ? ev.then(d) : ev.then;
+    if (next !== undefined && next !== null) {
+      if (!machine.states[next]) {
+        throw new Error(
+          `claude-artifact-framework: machine event "${eventName}" resolved to unknown state "${next}". Valid states: ${Object.keys(machine.states).join(", ")}.`
+        );
+      }
+      d[key] = next;
+    }
+  });
+}
+
 export function createApp(spec = {}) {
   const layout = validate(spec);
+  if (spec.machine) {
+    const names = Object.keys(spec.machine.states);
+    for (const b of everyBlock(spec)) {
+      if (b && b.state !== undefined && !names.includes(b.state)) {
+        throw new Error(
+          `claude-artifact-framework: a block declares state: "${b.state}" but the machine's states are: ${names.join(", ")}.`
+        );
+      }
+    }
+  } else {
+    for (const b of everyBlock(spec)) {
+      if (b && b.state !== undefined) {
+        throw new Error('claude-artifact-framework: `state:` on a block needs a `machine` declared at the top level.');
+      }
+    }
+  }
   const state = createAppState(defaultsFrom(spec), { shared: Boolean(spec.shared) });
   const css = themeCss(spec.theme && spec.theme.seed) + BASE_CSS;
   // Live File objects picked by `file` fields — in memory only, never persisted.
@@ -863,6 +1009,27 @@ export function createApp(spec = {}) {
       return unsubscribe;
     }, []);
 
+    // Machine `after` timers are framework-owned: armed on entering a state,
+    // cancelled on leaving it (the dep is the current state), cleaned up on
+    // unmount. A reload mid-state re-arms the full duration. The timeout
+    // re-checks the state before firing — a transition that happened while
+    // it was pending wins.
+    const machineState = spec.machine ? state.getData()[spec.machine.key || "fase"] : null;
+    useEffect(() => {
+      if (!spec.machine || !state.isHydrated()) return;
+      const st = spec.machine.states[machineState];
+      if (!st || !st.after) return;
+      const timer = setTimeout(() => {
+        state.update((d) => {
+          const key = spec.machine.key || "fase";
+          if (d[key] !== machineState) return;
+          if (st.after.do) st.after.do(d);
+          d[key] = st.after.then;
+        });
+      }, st.after.seconds * 1000);
+      return () => clearTimeout(timer);
+    }, [machineState, state.isHydrated()]);
+
     const ctx = {
       React: getReact(),
       data: state.getData(),
@@ -876,6 +1043,12 @@ export function createApp(spec = {}) {
       setTab: (key, i) => state.setView({ tabs: { ...state.getView().tabs, [key]: i } }),
       toggleCollapsed: (key, val) => state.setView({ collapsed: { ...state.getView().collapsed, [key]: val } }),
       colors: (n) => seriesColors(spec.theme && spec.theme.seed, n),
+      machine: spec.machine || null,
+      send: spec.machine
+        ? (eventName, payload) => runMachineEvent(spec.machine, state.update, eventName, payload)
+        : () => {
+            throw new Error("claude-artifact-framework: ctx.send() needs a `machine` declared at the top level.");
+          },
     };
 
     const Layout = LAYOUT_COMPONENTS[layout];