claude-artifact-framework 0.4.0 → 0.5.1

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.4.0/dist/index.global.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/claude-artifact-framework@0.5.1/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.4.0/dist/index.esm.js";
+  } from "https://cdn.jsdelivr.net/npm/claude-artifact-framework@0.5.1/dist/index.esm.js";
 </script>
 ```
 
-Pin a version (`@0.4.0`) for reproducible artifacts, or drop the version
+Pin a version (`@0.5.1`) for reproducible artifacts, or drop the version
 (`claude-artifact-framework/dist/...`) to always get the latest release.
 
 ### Inside a React artifact
@@ -175,6 +175,122 @@ blocks: [
 `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.
+
+## API reference
+
+Everything an app can declare, in one place.
+
+**Top-level keys**: `title`, `subtitle`, `theme: { seed }`, `layout`, `blocks`,
+`records`, `steps`, `chat`, `data`, `shared`. Anything else throws.
+
+**Layouts** (`layout:`): `panel` (default — grid of blocks), `records` (CRUD
+list), `steps` (wizard), `chat` (conversation with Claude). Each requires its
+matching key (`blocks` / `records` / `steps` / `chat`).
+
+**Block types** (entries of `blocks`): `fields`, `output`, `text`, `list`,
+`chart`, `timer`, `custom`. One type per entry, plus optional `title`, `empty`,
+`wide`. In the `records` layout, `blocks` render below the list (never on the
+detail screen); their functions receive the same `data` object as everywhere
+else — the collection lives at `d.records`.
+
+**Field types** (`type:` on any field): `text` (default), `textarea`,
+`number`, `money`, `percent`, `check` (checkbox), `date`, `select` (needs
+`options`). Other field keys: `key` (required), `label`, `value` (initial),
+`required`, `min`, `max`, `step`, `placeholder`, `hint`, `rows`, `options`.
+An unknown `type` throws naming the valid ones.
+
+**`records` keys**: `label`, `fields`, `title(r)`, `subtitle(r)`, `sort(a,b)`,
+`summary(all)`, `empty`, `search`, `compute`. `id` is framework-assigned and
+reserved.
+
+**`steps` keys** (per step): `title`, `text`, `fields`, `result(d)`. Field
+keys must be unique across steps.
+
+**`chat` keys**: `system` (string or `(d) => string`), `greeting`,
+`placeholder`, `tools`, `model`, `maxTokens`. Each tool:
+`{ description, input, run(input, ctx) }`.
+
+**Formats** (`format:` on output/chart/compute items): `money`, `percent`,
+`number`, `date`.
+
 ## `storage`
 
 Thin wrapper over `window.storage`, the persistence API Claude injects into a