claude-artifact-framework 0.14.0 → 0.15.0

package/llms.txt

@@ -0,0 +1,98 @@
+# 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,
+  brand:{logo, footer} (logo: emoji | inline <svg> | https URL | omit for an
+  automatic monogram)
+- Layouts: panel (default), records, steps, chat, workspace, documents
+- Block types: fields, output, text, list, chart, timer, actions, banner
+  ({image?, title, subtitle} — no image paints a seed-derived gradient),
+  image ({src: url|inline-svg, caption, fit, height}), chat, tabs, records,
+  custom — plus per-block title, icon (an emoji, prefixes the 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, avatar (true = initials circles per row)
+  (+ 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.
+13. Brand is zero-asset-first: monogram/gradient/emoji defaults before URLs;
+    inline <svg> over remote images; one icon style per app (emoji-first);
+    avatar: true instead of hand-built initials circles.
+
+## 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.15.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",
@@ -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",

package/src/app.js

@@ -18,12 +18,15 @@ 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", "state"];
+const RESERVED = ["title", "empty", "wide", "onSelect", "subtitle", "when", "collapsible", "fill", "state", "icon"];
+const BRAND_KEYS = ["logo", "footer"];
+const BANNER_KEYS = ["image", "title", "subtitle"];
+const IMAGE_KEYS = ["src", "caption", "fit", "height"];
 
 // 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", "machine"];
+const TOP_KEYS = ["title", "subtitle", "theme", "layout", "blocks", "records", "steps", "chat", "data", "shared", "main", "sidebar", "libs", "documents", "machine", "brand"];
 
 const MACHINE_KEYS = ["key", "initial", "states", "events"];
 const MACHINE_STATE_KEYS = ["after"];
@@ -31,7 +34,7 @@ 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"];
+const RECORDS_KEYS = ["label", "fields", "title", "subtitle", "sort", "summary", "empty", "search", "compute", "items", "actions", "avatar"];
 const ITEMS_KEYS = ["label", "fields", "empty"];
 
 // An unknown field type used to fall through silently to a text input — the
@@ -121,6 +124,25 @@ function checkBlocks(blocks) {
     if (known[0] === "actions") checkActions(block.actions, `blocks[${i}].actions`);
     if (known[0] === "chat") checkChatConfig(block.chat, `blocks[${i}].chat`);
     if (known[0] === "records") checkRecordsSpec(block.records, `blocks[${i}].records`, true);
+    if (known[0] === "banner" && typeof block.banner === "object" && block.banner !== null) {
+      const unknownBn = Object.keys(block.banner).filter((k) => !BANNER_KEYS.includes(k));
+      if (unknownBn.length) {
+        throw new Error(
+          `claude-artifact-framework: blocks[${i}].banner has unknown keys (${unknownBn.join(", ")}). Valid keys: ${BANNER_KEYS.join(", ")}.`
+        );
+      }
+    }
+    if (known[0] === "image" && typeof block.image === "object" && block.image !== null) {
+      const unknownIm = Object.keys(block.image).filter((k) => !IMAGE_KEYS.includes(k));
+      if (unknownIm.length) {
+        throw new Error(
+          `claude-artifact-framework: blocks[${i}].image has unknown keys (${unknownIm.join(", ")}). Valid keys: ${IMAGE_KEYS.join(", ")}.`
+        );
+      }
+    }
+    if (block.icon !== undefined && typeof block.icon !== "string") {
+      throw new Error(`claude-artifact-framework: blocks[${i}].icon must be a string (an emoji works best).`);
+    }
     if (known[0] === "tabs") {
       const tabs = block.tabs;
       if (!Array.isArray(tabs) || tabs.length === 0) {
@@ -234,6 +256,17 @@ function validate(spec) {
     );
   }
   if (spec.machine !== undefined) checkMachine(spec.machine);
+  if (spec.brand !== undefined) {
+    const unknownB = Object.keys(spec.brand || {}).filter((k) => !BRAND_KEYS.includes(k));
+    if (unknownB.length) {
+      throw new Error(
+        `claude-artifact-framework: brand has unknown keys (${unknownB.join(", ")}). Valid keys: ${BRAND_KEYS.join(", ")}.`
+      );
+    }
+    if (spec.brand.logo !== undefined && typeof spec.brand.logo !== "string") {
+      throw new Error("claude-artifact-framework: brand.logo must be a string — an emoji, an inline <svg>...</svg>, or an https URL. Omit it for an automatic monogram.");
+    }
+  }
   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.");
@@ -350,7 +383,7 @@ function validate(spec) {
       }
       for (const name of names) {
         const t = d.types[name];
-        const TYPE_KEYS = ["label", "title", "blocks", "empty"];
+        const TYPE_KEYS = ["label", "title", "blocks", "empty", "icon"];
         const unknownT = Object.keys(t || {}).filter((k) => !TYPE_KEYS.includes(k));
         if (unknownT.length) {
           throw new Error(
@@ -565,7 +598,7 @@ function TabsBlock({ spec, ctx }) {
             className: i === active ? "caf-tab caf-tab-active" : "caf-tab",
             onClick: () => ctx.setTab(key, i),
           },
-          t.label
+          t.icon ? `${t.icon} ${t.label}` : t.label
         )
       )
     ),
@@ -585,6 +618,8 @@ function Block({ block, ctx }) {
   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;
+  // `icon` is sugar: it prefixes the title everywhere titles render.
+  if (block.icon && typeof block.title === "string") block = { ...block, title: `${block.icon} ${block.title}` };
   const name = Object.keys(block).find((k) => ALL_NAMES.includes(k));
   const Component = ALL_BLOCKS[name];
   const inner = h(
@@ -623,9 +658,9 @@ function Panel({ spec, ctx }) {
     (spec.blocks || []).map((block, i) =>
       h(
         "section",
-        // A collapsible is always full-width: half-width accordions leave an
-        // orphaned right edge on desktop and change width across breakpoints.
-        { key: i, className: block.wide || block.collapsible ? "caf-slot caf-slot-wide" : "caf-slot" },
+        // Collapsibles and banners are always full-width: half-width versions
+        // leave an orphaned right edge on desktop and change across breakpoints.
+        { key: i, className: block.wide || block.collapsible || block.banner ? "caf-slot caf-slot-wide" : "caf-slot" },
         h(Block, { block, ctx })
       )
     )
@@ -650,9 +685,9 @@ function RecordsWithBlocks({ spec, ctx }) {
           spec.blocks.map((block, i) =>
             h(
               "section",
-              // A collapsible is always full-width: half-width accordions leave an
-        // orphaned right edge on desktop and change width across breakpoints.
-        { key: i, className: block.wide || block.collapsible ? "caf-slot caf-slot-wide" : "caf-slot" },
+              // Collapsibles and banners are always full-width: half-width versions
+        // leave an orphaned right edge on desktop and change across breakpoints.
+        { key: i, className: block.wide || block.collapsible || block.banner ? "caf-slot caf-slot-wide" : "caf-slot" },
               h(Block, { block, ctx })
             )
           )
@@ -734,7 +769,10 @@ function DocumentsLayout({ spec, ctx }) {
   const types = dspec.types || null;
   const typeNames = types ? Object.keys(types) : [];
   const specFor = (doc) => (types ? types[doc.type] : dspec);
-  const typeLabel = (name) => (types[name] && types[name].label) || name;
+  const typeLabel = (name) => {
+    const t = types[name] || {};
+    return (t.icon ? t.icon + " " : "") + (t.label || name);
+  };
   const [picking, setPicking] = useState(false);
 
   const storedId = ctx.view.tabs ? ctx.view.tabs[DOC_TAB_KEY] : undefined;
@@ -1053,6 +1091,29 @@ export function createApp(spec = {}) {
 
     const Layout = LAYOUT_COMPONENTS[layout];
 
+    // Zero-asset-first logo ladder: emoji → automatic monogram (initials over
+    // the accent) → inline SVG → URL. The brand never NEEDS an uploaded file.
+    const logo = spec.brand && spec.brand.logo;
+    const logoEl = !spec.brand
+      ? null
+      : logo && logo.trim().startsWith("<svg")
+      ? h("span", { className: "caf-logo caf-logo-svg", dangerouslySetInnerHTML: { __html: logo } })
+      : logo && /^https?:\/\//.test(logo)
+      ? h("img", { className: "caf-logo", src: logo, alt: "" })
+      : logo
+      ? h("span", { className: "caf-logo caf-logo-emoji", "aria-hidden": true }, logo)
+      : h(
+          "span",
+          { className: "caf-logo caf-logo-mono", "aria-hidden": true },
+          (spec.title || "?")
+            .split(/\s+/)
+            .map((w) => w[0])
+            .filter(Boolean)
+            .slice(0, 2)
+            .join("")
+            .toUpperCase()
+        );
+
     return h(
       "div",
       // The layout class lets shared CSS follow the active container width —
@@ -1061,9 +1122,14 @@ export function createApp(spec = {}) {
       h("style", { dangerouslySetInnerHTML: { __html: css } }),
       h(
         "header",
-        { className: "caf-header" },
-        spec.title ? h("h1", null, spec.title) : null,
-        spec.subtitle ? h("p", null, spec.subtitle) : null
+        { className: spec.brand ? "caf-header caf-header-brand" : "caf-header" },
+        logoEl,
+        h(
+          "div",
+          { className: "caf-header-text" },
+          spec.title ? h("h1", null, spec.title) : null,
+          spec.subtitle ? h("p", null, spec.subtitle) : null
+        )
       ),
       libsState === "error"
         ? h(
@@ -1074,7 +1140,8 @@ export function createApp(spec = {}) {
           )
         : !state.isHydrated() || libsState === "loading"
         ? h("div", { className: "caf-block caf-loading" }, libsState === "loading" ? "Loading libraries…" : "Loading…")
-        : h(Layout, { spec, ctx })
+        : h(Layout, { spec, ctx }),
+      spec.brand && spec.brand.footer ? h("footer", { className: "caf-footer" }, spec.brand.footer) : null
     );
   };
 }
@@ -1288,6 +1355,35 @@ const BASE_CSS = `
 .caf-empty .caf-btn { margin-top: 0.6rem; }
 .caf-records-block { display: flex; flex-direction: column; gap: 1rem; min-width: 0; }
 .caf-doc-typemenu { display: flex; gap: 0.5rem; flex-wrap: wrap; }
+.caf-header-brand { display: flex; align-items: center; gap: 0.8rem; }
+.caf-header-text { min-width: 0; }
+.caf-logo { flex: none; width: 40px; height: 40px; border-radius: 9px; object-fit: contain; }
+.caf-logo-emoji { display: flex; align-items: center; justify-content: center; font-size: 1.7rem; background: var(--caf-surface); border: 1px solid var(--caf-border); }
+.caf-logo-mono {
+  display: flex; align-items: center; justify-content: center;
+  background: var(--caf-accent); color: var(--caf-accentText);
+  font-size: 0.95rem; font-weight: 700; letter-spacing: 0.02em;
+}
+.caf-logo-svg { display: flex; align-items: center; justify-content: center; overflow: hidden; }
+.caf-logo-svg svg { width: 100%; height: 100%; }
+.caf-banner {
+  border-radius: var(--caf-radius); padding: 1.6rem 1.4rem; min-height: 110px;
+  display: flex; flex-direction: column; justify-content: flex-end; gap: 0.2rem;
+}
+.caf-banner-title { margin: 0; color: #fff; font-size: 1.4rem; font-weight: 700; letter-spacing: -0.01em; text-shadow: 0 1px 3px rgba(0,0,0,0.35); }
+.caf-banner-sub { margin: 0; color: rgba(255,255,255,0.92); font-size: 0.9rem; text-shadow: 0 1px 2px rgba(0,0,0,0.35); }
+.caf-image { margin: 0; }
+.caf-image img { width: 100%; border-radius: 7px; display: block; }
+.caf-image-svg svg { width: 100%; height: auto; display: block; }
+.caf-footer { max-width: 760px; margin: 2rem auto 0; padding-top: 0.8rem; border-top: 1px solid var(--caf-border); color: var(--caf-muted); font-size: 0.78rem; text-align: center; }
+.caf-layout-workspace .caf-footer { max-width: 1200px; }
+.caf-avatar {
+  flex: none; width: 30px; height: 30px; border-radius: 50%;
+  display: flex; align-items: center; justify-content: center;
+  color: #fff; font-size: 0.7rem; font-weight: 700; letter-spacing: 0.02em;
+}
+.caf-row-avatar { flex-direction: row; align-items: center; gap: 0.6rem; }
+.caf-row-main { display: flex; flex-direction: column; gap: 0.15rem; min-width: 0; }
 .caf-chevron-closed { transform: rotate(-90deg); }
 .caf-block-fill { border: none; background: transparent; padding: 0; overflow: auto; min-height: 320px; }
 .caf-empty, .caf-loading { color: var(--caf-muted); font-size: 0.9rem; text-align: center; padding: 1.6rem 1rem; }

package/src/blocks.js

@@ -198,6 +198,42 @@ export function OutputBlock({ spec, ctx }) {
   );
 }
 
+// Brand elements follow the zero-asset-first principle: every form works
+// with nothing uploaded (artifacts can't persist real images — the ~5MB
+// pool). banner's default face is a gradient derived from the theme seed;
+// image accepts a URL or an inline SVG string (LLMs generate SVG well).
+export function BannerBlock({ spec, ctx }) {
+  const b = typeof spec.banner === "string" ? { title: spec.banner } : spec.banner || {};
+  const [c1, c2] = ctx.colors(2);
+  const background = b.image
+    ? `linear-gradient(rgba(0,0,0,0.35), rgba(0,0,0,0.35)), url(${JSON.stringify(b.image)}) center / cover`
+    : `linear-gradient(135deg, ${c1}, ${c2})`;
+  return h(
+    "div",
+    { className: "caf-banner", style: { background } },
+    b.title ? h("h2", { className: "caf-banner-title" }, b.title) : null,
+    b.subtitle ? h("p", { className: "caf-banner-sub" }, b.subtitle) : null
+  );
+}
+
+export function ImageBlock({ spec }) {
+  const im = typeof spec.image === "string" ? { src: spec.image } : spec.image || {};
+  const isSvg = typeof im.src === "string" && im.src.trim().startsWith("<svg");
+  return h(
+    "figure",
+    { className: "caf-block caf-image" },
+    spec.title ? h("h2", { className: "caf-block-title" }, spec.title) : null,
+    isSvg
+      ? h("div", { className: "caf-image-svg", dangerouslySetInnerHTML: { __html: im.src } })
+      : h("img", {
+          src: im.src,
+          alt: im.caption || spec.title || "",
+          style: { objectFit: im.fit || "cover", maxHeight: im.height ? `${im.height}px` : undefined },
+        }),
+    im.caption ? h("figcaption", { className: "caf-hint" }, im.caption) : null
+  );
+}
+
 export function TextBlock({ spec, ctx }) {
   const body = typeof spec.text === "function" ? spec.text(ctx.data) : spec.text;
   return h(
@@ -464,6 +500,8 @@ export const BLOCKS = {
   chart: ChartBlock,
   timer: TimerBlock,
   actions: ActionsBlock,
+  banner: BannerBlock,
+  image: ImageBlock,
   chat: ({ spec, ctx }) => h(ChatPanel, { cfg: spec.chat, ctx, title: spec.title }),
   custom: CustomBlock,
 };

package/src/records.js

@@ -54,6 +54,22 @@ function makeId() {
   return "r" + Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
 }
 
+// avatar: true — an initials circle per row, colored deterministically from
+// the row title through the theme's series palette. Identity without assets.
+function Avatar({ title, ctx }) {
+  const initials = String(title)
+    .split(/\s+/)
+    .map((w) => w[0])
+    .filter(Boolean)
+    .slice(0, 2)
+    .join("")
+    .toUpperCase() || "?";
+  let hash = 0;
+  for (const ch of String(title)) hash = (hash * 31 + ch.charCodeAt(0)) >>> 0;
+  const palette = ctx.colors(8);
+  return h("span", { className: "caf-avatar", style: { background: palette[hash % palette.length] } }, initials);
+}
+
 function rowTitle(spec, rec) {
   if (spec.title) return spec.title(rec);
   // Default: the first text-ish field, which is what a human would label by.
@@ -152,11 +168,16 @@ function ListScreen({ spec, ctx }) {
                 "button",
                 {
                   type: "button",
-                  className: "caf-row",
+                  className: spec.avatar ? "caf-row caf-row-avatar" : "caf-row",
                   onClick: () => ctx.go("record", rec.id),
                 },
-                h("span", { className: "caf-row-title" }, rowTitle(spec, rec)),
-                spec.subtitle ? h("span", { className: "caf-row-sub" }, spec.subtitle(rec)) : null
+                spec.avatar ? h(Avatar, { title: rowTitle(spec, rec), ctx }) : null,
+                h(
+                  "span",
+                  { className: "caf-row-main" },
+                  h("span", { className: "caf-row-title" }, rowTitle(spec, rec)),
+                  spec.subtitle ? h("span", { className: "caf-row-sub" }, spec.subtitle(rec)) : null
+                )
               ),
               spec.actions
                 ? h(