claude-artifact-framework 0.3.0 → 0.5.0

package/README.md

@@ -12,7 +12,7 @@ mirrors npm packages automatically.
 ### As a global script (`<script>` tag)
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/claude-artifact-framework@0.3.0/dist/index.global.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/claude-artifact-framework@0.5.0/dist/index.global.js"></script>
 <script>
   const { storage, createStore, createPersistedStore, createSharedStore } = ArtifactKit;
 </script>
@@ -27,11 +27,11 @@ mirrors npm packages automatically.
     createStore,
     createPersistedStore,
     createSharedStore,
-  } from "https://cdn.jsdelivr.net/npm/claude-artifact-framework@0.3.0/dist/index.esm.js";
+  } from "https://cdn.jsdelivr.net/npm/claude-artifact-framework@0.5.0/dist/index.esm.js";
 </script>
 ```
 
-Pin a version (`@0.3.0`) for reproducible artifacts, or drop the version
+Pin a version (`@0.5.0`) for reproducible artifacts, or drop the version
 (`claude-artifact-framework/dist/...`) to always get the latest release.
 
 ### Inside a React artifact
@@ -123,6 +123,137 @@ persistence path as everything else. `id` is assigned by the framework and
 reserved. Optional: `title(r)` / `subtitle(r)` for rows, `sort(a, b)`,
 `summary(records)` for stats above the list, `empty` for the empty-state text.
 
+### The `steps` layout — wizards, quizzes, staged calculators
+
+Declare the sequence; next/back/progress/result are framework-owned. Step
+fields write into the same flat `data` pool, so the result step is just a
+function of data. Next is gated on the current step's validation; the current
+step survives a reload.
+
+```js
+ArtifactKit.createApp({
+  title: "Quiz de riesgo",
+  layout: "steps",
+  steps: [
+    { title: "Tu edad",   fields: [{ key: "edad", type: "number", required: true, min: 18 }] },
+    { title: "Tu perfil", fields: [{ key: "perfil", type: "select", required: true, options: ["conservador", "moderado", "agresivo"] }] },
+    { title: "Resultado", result: (d) => [{ label: "Puntaje", value: score(d), big: true }] },
+  ],
+});
+```
+
+Field keys must be unique across all steps (they share one data pool); a
+duplicate throws at creation, as does an unknown step key.
+
+### The `chart` block — bar, line, donut
+
+Same vocabulary as `output` (items of `{ label, value }` plus an optional
+`format`), so declaring one teaches nothing new. Colors derive from the theme
+seed by golden-angle rotation — a chart can't clash with the app it lives in.
+
+```js
+blocks: [
+  { chart: (d) => ({ type: "bar", format: "money", items: monthlyTotals(d) }), title: "Ventas", wide: true },
+  { chart: { type: "donut", items: [{ label: "Comida", value: 45 }, { label: "Otros", value: 55 }] } },
+]
+```
+
+### The `timer` block — countdowns that persist their effects
+
+The interval is framework-owned and cleaned up on unmount (a leaked
+`setInterval` is a classic half-built artifact bug). The countdown itself is
+deliberately ephemeral; what you declare is what happens when it finishes —
+`onDone` runs through `update()`, so its effects persist like any other change.
+
+```js
+blocks: [
+  { timer: { minutes: 25, label: "Focus", onDone: (d) => { d.completados = (d.completados || 0) + 1; } } },
+  { output: (d) => [{ label: "Pomodoros", value: d.completados || 0, big: true }] },
+]
+```
+
+`text` blocks also accept a function of data — `{ text: (d) => "Hola " + d.nombre }` —
+with the same contract as `output`.
+
+### The `chat` layout — apps that talk to Claude
+
+Tutors, advisors, generators, roleplay. Every piece of the network contract is
+copied from code proven inside the real artifact runtime: the artifact fetches
+`https://api.anthropic.com/v1/messages` directly with **no API key** (the
+runtime proxies the call and injects auth), `stream: true` works, and tools
+are prompted (the proxy does not support native function calling).
+
+The author declares the system prompt and, optionally, tools that operate on
+the app's data — a chat that can drive the app. The framework owns message
+state, live streaming, the busy state, the tool loop, and errors as visible
+bubbles. The conversation persists and survives reload.
+
+```js
+ArtifactKit.createApp({
+  title: "Asistente de gastos",
+  theme: { seed: "#0f766e" },
+  layout: "chat",
+  chat: {
+    system: (d) => "Eres un asistente de gastos. Total actual: " + (d.total || 0),
+    greeting: "¡Hola! Contame tus gastos.",
+    tools: {
+      agregar_gasto: {
+        description: "Agrega un gasto",
+        input: { concepto: "string", monto: "number" },
+        run: (input, ctx) => {
+          ctx.update((d) => { d.total = (d.total || 0) + Number(input.monto); });
+          return { ok: true };
+        },
+      },
+    },
+  },
+});
+```
+
+`system` is a string or a function of data. Tool `run(input, ctx)` returns a
+JSON-serializable result that is fed back to the model; an unknown tool name
+is answered in-band so the model corrects itself. Optional: `greeting`,
+`placeholder`, `model` (default `claude-sonnet-4-6`, proven through the
+proxy), `maxTokens`.
+
+### Search, computed fields, and shared data
+
+Three record-app multipliers, all declarative:
+
+```js
+ArtifactKit.createApp({
+  title: "Inventario del club",
+  layout: "records",
+  shared: true,                 // one copy of the data for every viewer
+  records: {
+    search: true,               // search box over all field values
+    fields: [
+      { key: "nombre",   type: "text", required: true },
+      { key: "cantidad", type: "number", value: 1, min: 0 },
+      { key: "precio",   type: "money", value: 0, min: 0 },
+    ],
+    compute: {                  // derived per record, never stored
+      subtotal: { label: "Subtotal", format: "money", value: (r) => r.cantidad * r.precio },
+    },
+    summary: (all) => [
+      { label: "Valor total", value: all.reduce((s, r) => s + r.subtotal, 0), format: "money", big: true },
+    ],
+  },
+});
+```
+
+- `search: true` adds a filter box over every field's value; the count shows
+  "n of total" while filtering.
+- `compute` entries are functions of the record (or `{ label, format, value }`).
+  Computed values appear read-only in the detail screen and are available to
+  `title` / `subtitle` / `sort` / `summary` as if they were fields. A compute
+  key that collides with a field key throws.
+- `shared: true` (top level) stores the app's data in the shared scope: every
+  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.
+
 ## `storage`
 
 Thin wrapper over `window.storage`, the persistence API Claude injects into a