claude-artifact-framework 0.14.0 → 0.14.1

package/README.md

@@ -890,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/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.14.0",
+  "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",