claude-artifact-framework 0.13.1 → 0.14.1

package/README.md

@@ -107,6 +107,12 @@ already on `globalThis`, it is picked up automatically and the call is a no-op.
 > extra closing brace at the tail. Indented, multi-line specs have never
 > produced one. Format like every example in this document.
 
+> **Don't hand-build empty, loading, or error states.** Every block that can
+> be empty (`output`, `chart`, `list`, `records`) shows a named empty state
+> by itself; hydration shows a loading screen; a block that throws shows a
+> named error in its own slot. Code like `if (!d.items.length) return "No
+> hay datos"` duplicates what the framework already guarantees.
+
 ### The `records` layout — a full CRUD app from a declaration
 
 For "list of things" apps (expenses, habits, notes, todos), declare what a
@@ -272,7 +278,13 @@ ArtifactKit.createApp({
   viewer of the published artifact converges on the same data via polling.
   Conflict handling is last-write-wins; a poll never overwrites local edits
   that haven't been persisted yet. View state (which screen is open) stays
-  personal per viewer.
+  personal per viewer. **Design for last-write-wins**: two viewers writing
+  within the same couple of seconds means one write can be lost — prefer
+  per-viewer marks in arrays (`votantes: [...viewerIds]`, like the voting
+  pattern) over several people editing the same field, and don't build
+  anything where a lost write really hurts (money, bookings). Measured in
+  practice: appending to your own mark converges; racing on one value
+  doesn't.
 
 ### `items` — a child collection per record
 
@@ -302,7 +314,10 @@ records: {
 ```
 
 `items` keys: `label`, `fields`, `empty`. Each child gets a framework
-`id`; a parent field can't be named `items`.
+`id`; a parent field can't be named `items`. The smell this replaces:
+**never ask the user to type JSON (or comma-separated rows) into a
+`textarea`** — if a record has parts, declare `items` and each part gets
+real fields, validation, and its own remove button.
 
 ### `actions` — one-tap buttons that mutate data
 
@@ -328,10 +343,17 @@ blocks: [
 ```
 
 Action keys: `label`, `run`, optional `when` (hides the button when false)
-and `kind` (`"primary"` / `"danger"`). Row actions receive the record;
-block actions receive data. Changes persist like any other update. Give the
-constructive action `kind: "primary"` — a "Vote"/"Add"/"Done" left as the
-neutral default reads weaker than a `"danger"` next to it.
+and `kind` (`"primary"` / `"danger"`). Row actions receive
+`(record, data, viewerId)`, block actions `(data, viewerId)`. Stopping
+early is fine (`run: (r) => ...`), but **never skip a middle argument**:
+`run: (r, viewerId)` reads `data` as your viewer id and breaks silently —
+if you need `viewerId`, name everything before it: `run: (r, d, viewerId)`.
+Changes persist like any other update.
+Give the constructive action `kind: "primary"` — a "Vote"/"Add"/"Done" left
+as the neutral default reads weaker than a `"danger"` next to it. And a
+smell to avoid: **a number that changes by pressing is an `action`, not an
+editable `number` field** — votes, counters, and streaks as editable inputs
+invite typos and lie about intent.
 
 Chat bubbles render the assistant's **markdown** (bold, code, lists,
 headings) automatically — HTML is escaped first, so model output can't
@@ -400,6 +422,63 @@ The active tab and each accordion's open/closed state are framework-owned
 view state — they survive reload, per viewer. Tabs cannot nest inside tabs;
 `when` must be a function; both throw otherwise.
 
+### The `machine` — declared phases instead of hand-rolled state logic
+
+If your app has **phases** — a game (choosing → comparing → won), a turn
+cycle, a multi-stage process — never track them by hand with flags and
+`setTimeout`s: that is the single most measured source of broken apps
+(a memory game died because its compare logic fired in the wrong phase).
+Declare the machine instead:
+
+```js
+ArtifactKit.createApp({
+  title: "Memoria",
+  machine: {
+    key: "fase",                    // d.fase holds the current state — persisted
+    initial: "eligiendo",
+    states: {
+      eligiendo: {},
+      comparando: {                 // timed transition, framework-owned timer
+        after: { seconds: 1, then: "eligiendo", do: (d) => { d.reveladas = []; } },
+      },
+      ganado: {},
+    },
+    events: {
+      elegir: {
+        from: ["eligiendo"],        // ONLY legal here — elsewhere it's a no-op
+        do: (d, carta) => { d.reveladas = [...d.reveladas, carta]; },
+        then: (d) => d.pares === d.total ? "ganado" : d.reveladas.length === 2 ? "comparando" : "eligiendo",
+      },
+      reiniciar: { from: "*", do: (d) => { d.reveladas = []; d.pares = 0; }, then: "eligiendo" },
+    },
+  },
+  blocks: [
+    { custom: (ctx) => /* cards call ctx.send("elegir", i) */ null },
+    { text: "¡Ganaste!", state: "ganado" },   // block exists only in that phase
+  ],
+})
+```
+
+The contract:
+
+- **`ctx.send(event, payload)` is the only door.** An unknown event throws
+  naming the valid ones; a legal event sent from the wrong phase is a
+  silent no-op — a user mashing buttons is normal, not a bug. Never write
+  `d.fase = ...` yourself.
+- `do` mutates data (it receives `(d, payload)`), `then` names the next
+  state — a string, or a function of data returning one. Omit `then` to
+  stay in the same state.
+- `after: { seconds, then, do }` on a state is a **framework-owned timer**:
+  armed on entry, cancelled on leaving the state, cleaned up on unmount.
+  No `setTimeout` to forget.
+- The current state lives in `data` under `machine.key` (default `"fase"`),
+  so it **persists and resumes** — reloading mid-game continues the phase.
+- Blocks take `state: "nombre"` as sugar for "visible only in that phase";
+  `when:` still works for anything more complex.
+- Machine keys: `key`, `initial`, `states`, `events`. Event keys: `from`
+  (state, array, or `"*"`), `do`, `then`. One machine per app, app-wide
+  (inside `documents` it is NOT per-document).
+
 ### `records` as a block — a CRUD collection inside any screen
 
 The full records machinery (list, add-then-edit, detail, search, summary,
@@ -661,6 +740,29 @@ custom: (ctx) => {
 }
 ```
 
+- **Never render a `<form>`.** The published-artifact iframe sandbox lacks
+  `allow-forms`: a form that works in preview dies on the phone. Inputs +
+  a button with `onClick` (plus Enter via `onKeyDown` if you want it) do
+  the same job — that is why every framework block is formless.
+- **Use the theme, not hardcoded colors.** The app ships a light AND dark
+  palette; a custom block painted with `#fff` backgrounds or `#dc2626`
+  reds looks broken the moment the viewer is in dark mode. Use the CSS
+  variables — `var(--caf-text)`, `var(--caf-muted)`, `var(--caf-accent)`,
+  `var(--caf-surface)`, `var(--caf-sunken)`, `var(--caf-border)`,
+  `var(--caf-danger)` — and `ctx.colors(n)` for chart-like series:
+
+```js
+custom: (ctx) => React.createElement("div", {
+  style: { background: "var(--caf-sunken)", color: "var(--caf-text)",
+           border: "1px solid var(--caf-border)", borderRadius: "7px", padding: "0.6rem" }
+}, "se ve bien en ambos temas")
+```
+
+- **Never write big strings into `data`.** Storage allows ~5MB per key and
+  the whole pool is one key: a data-URL preview of a photo written to
+  `d.preview` can kill persistence for the entire app. Big things (data
+  URLs, file contents, parse results) live in `React.useState` or come from
+  `ctx.files`; `data` holds what is small and serializable.
 - Custom re-renders whenever `data` or `view` change; it receives the full
   `ctx` (`data`, `update`, `view`, `files`, `viewerId`, `colors`, `go`,
   `back`) and lives inside the block error boundary — a bug in your custom
@@ -671,17 +773,18 @@ custom: (ctx) => {
 Everything an app can declare, in one place.
 
 **Top-level keys**: `title`, `subtitle`, `theme: { seed }`, `layout`, `blocks`,
-`records`, `steps`, `chat`, `main`, `sidebar` (workspace panes), `data`,
-`shared`. Anything else throws.
+`records`, `steps`, `chat`, `main`, `sidebar` (workspace panes), `documents`,
+`data`, `shared`, `libs`. Anything else throws.
 
 **Layouts** (`layout:`): `panel` (default — grid of blocks), `records` (CRUD
 list), `steps` (wizard), `chat` (conversation with Claude), `workspace`
-(main column + sidebar). Each requires its matching key (`blocks` /
-`records` / `steps` / `chat` / `main`+`sidebar`).
+(main column + sidebar), `documents` (parallel documents in top tabs).
+Each requires its matching key (`blocks` / `records` / `steps` / `chat` /
+`main`+`sidebar` / `documents`).
 
-**Block types** (entries of `blocks`, `main`, or `sidebar`): `fields`,
-`output`, `text`, `list`, `chart`, `timer`, `actions`, `chat`, `tabs`,
-`custom`. Any block also accepts `when: (d) => bool` (conditional
+**Block types** (entries of `blocks`, `main`, `sidebar`, or a document's
+`blocks`): `fields`, `output`, `text`, `list`, `chart`, `timer`, `actions`,
+`chat`, `tabs`, `records`, `custom`. Any block also accepts `when: (d) => bool` (conditional
 visibility) and `collapsible: true | "collapsed"` (accordion; needs `title`).
 On every block `title` is the heading string; `list` additionally accepts a
 function as `title`, used as the per-row title (rows fall back to
@@ -787,3 +890,35 @@ board.stop(); // stop polling, e.g. on teardown
 Conflict handling is last-write-wins: if two viewers change the same key
 within one poll window, whichever write reaches storage last overwrites the
 other. There is no merge/CRDT logic.
+
+## Hard rules — the short list
+
+The rules that decide whether a generated app works, all in one place
+(each is explained in its section above):
+
+1. **Indented, never minified** — the only measured syntax errors came from
+   single-line output.
+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)`, and
+   `ctx.colors(n)` for series. A custom block painted with `#fff` or
+   `#ef4444` breaks in dark mode.
+3. **Never render a `<form>`** — the published sandbox lacks `allow-forms`;
+   use inputs plus a button with `onClick`.
+4. **Never write big strings into `data`** (data URLs, file contents) —
+   the whole pool shares one ~5MB key; big things live in `React.useState`
+   or `ctx.files`.
+5. **Phases belong to the `machine`** — never track game/process phases
+   with hand-rolled flags and `setTimeout`; `ctx.send` is the only door.
+6. **Never skip a middle positional argument** — `run: (r, d, viewerId)`,
+   never `run: (r, viewerId)`.
+7. **One `big: true` per screen** — it marks THE result, not every stat.
+8. **The constructive action takes `kind: "primary"`**; a counter changed
+   by pressing is an `action`, not an editable `number` field.
+9. **Parts of a record are `items`** — never JSON in a `textarea`.
+10. **Don't hand-build empty/loading/error states** — the framework owns
+    them.
+11. **CDN libs: call the method, not the global** (`marked.parse`, not
+    `marked(...)`); pin versions; when unsure of the file path use the bare
+    package URL.
+12. **Framework ids are strings** — never `Number(record.id)`.

package/dist/index.esm.js

@@ -1394,8 +1394,12 @@ function StepsLayout({ spec, ctx }) {
 
 // src/app.js
 var LAYOUTS = ["panel", "records", "steps", "chat", "workspace", "documents"];
-var RESERVED = ["title", "empty", "wide", "onSelect", "subtitle", "when", "collapsible", "fill"];
-var TOP_KEYS = ["title", "subtitle", "theme", "layout", "blocks", "records", "steps", "chat", "data", "shared", "main", "sidebar", "libs", "documents"];
+var RESERVED = ["title", "empty", "wide", "onSelect", "subtitle", "when", "collapsible", "fill", "state"];
+var TOP_KEYS = ["title", "subtitle", "theme", "layout", "blocks", "records", "steps", "chat", "data", "shared", "main", "sidebar", "libs", "documents", "machine"];
+var MACHINE_KEYS = ["key", "initial", "states", "events"];
+var MACHINE_STATE_KEYS = ["after"];
+var MACHINE_AFTER_KEYS = ["seconds", "then", "do"];
+var MACHINE_EVENT_KEYS = ["from", "do", "then"];
 var DOCUMENTS_KEYS = ["label", "title", "blocks", "empty", "types"];
 var RECORDS_KEYS = ["label", "fields", "title", "subtitle", "sort", "summary", "empty", "search", "compute", "items", "actions"];
 var ITEMS_KEYS = ["label", "fields", "empty"];
@@ -1500,6 +1504,81 @@ function checkBlocks(blocks) {
     }
   });
 }
+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 !== void 0 && (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 !== void 0) {
+      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 !== void 0 && 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: {...} }` \u2014 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 !== void 0 && 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 !== void 0 && 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 !== void 0 && 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) {
@@ -1507,6 +1586,7 @@ function validate(spec) {
       `claude-artifact-framework: unknown top-level keys (${unknownTop.join(", ")}). Valid keys: ${TOP_KEYS.join(", ")}.`
     );
   }
+  if (spec.machine !== void 0) checkMachine(spec.machine);
   if (spec.libs !== void 0) {
     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.");
@@ -1743,6 +1823,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) {
@@ -1826,6 +1910,7 @@ var ALL_BLOCKS = { ...BLOCKS, tabs: TabsBlock, records: RecordsBlock };
 var ALL_NAMES = [...BLOCK_NAMES, "tabs", "records"];
 function Block({ block, ctx }) {
   if (typeof block.when === "function" && !block.when(ctx.data)) return null;
+  if (block.state !== void 0 && ctx.machine && ctx.data[ctx.machine.key || "fase"] !== block.state) return null;
   const name = Object.keys(block).find((k) => ALL_NAMES.includes(k));
   const Component2 = ALL_BLOCKS[name];
   const inner = createElement(
@@ -2103,8 +2188,52 @@ function loadScript(src) {
     document.head.appendChild(tag);
   });
 }
+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]);
+}
+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 === void 0 ? "*" : 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 !== void 0 && 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;
+    }
+  });
+}
 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 !== void 0 && !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 !== void 0) {
+        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;
   const files = {};
@@ -2132,6 +2261,21 @@ function createApp(spec = {}) {
       if (state.isHydrated()) force((n) => n + 1);
       return unsubscribe;
     }, []);
+    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 * 1e3);
+      return () => clearTimeout(timer);
+    }, [machineState, state.isHydrated()]);
     const ctx = {
       React: getReact(),
       data: state.getData(),
@@ -2144,7 +2288,11 @@ function createApp(spec = {}) {
       viewerId: state.getViewerId(),
       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)
+      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];
     return createElement(