claude-artifact-framework 0.13.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-artifact-framework",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "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",

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];