claude-artifact-framework 0.17.0 → 0.19.0

package/llms.txt

@@ -32,7 +32,8 @@ https://cdn.jsdelivr.net/npm/claude-artifact-framework/dist/index.global.js
   (+ 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
+  tools, model, maxTokens; steps step: title, text, fields, result,
+  blocks (result steps only — end a wizard on charts/text under the stats)
 - Formats: money, percent (0-100), number, date. Output/chart/compute items:
   { label, value, format, big }
 
@@ -50,8 +51,9 @@ https://cdn.jsdelivr.net/npm/claude-artifact-framework/dist/index.global.js
 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.
+6. Row callbacks (when AND run) receive (record, data, viewerId); block
+   actions (data, viewerId). Stop early if you like; a 2nd param literally
+   named viewerId is matched by name and gets the viewer id.
 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-artifact-framework",
-  "version": "0.17.0",
+  "version": "0.19.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",

package/src/app.js

@@ -312,7 +312,7 @@ function validate(spec) {
     if (!Array.isArray(steps) || steps.length === 0) {
       throw new Error('claude-artifact-framework: layout "steps" needs `steps: [...]` with at least one step.');
     }
-    const STEP_KEYS = ["title", "text", "fields", "result"];
+    const STEP_KEYS = ["title", "text", "fields", "result", "blocks"];
     const seen = new Set();
     steps.forEach((st, i) => {
       if (!st || typeof st !== "object") {
@@ -327,6 +327,15 @@ function validate(spec) {
       if (!st.fields && !st.text && !st.result) {
         throw new Error(`claude-artifact-framework: steps[${i}] needs \`fields\`, \`text\`, or \`result\`.`);
       }
+      // A result step may close on more than stats: `blocks` renders any
+      // block set (charts, text, lists) under the result grid. Measured
+      // miss: a wizard that wanted to END on a chart had nowhere to put it.
+      if (st.blocks !== undefined) {
+        if (typeof st.result !== "function") {
+          throw new Error(`claude-artifact-framework: steps[${i}].blocks only renders on a result step — add \`result\` or move the blocks to the step's fields.`);
+        }
+        checkBlocks(st.blocks);
+      }
       checkFields(st.fields, `steps[${i}]`);
       for (const f of st.fields || []) {
         if (seen.has(f.key)) {
@@ -920,7 +929,10 @@ function DocumentsLayout({ spec, ctx }) {
     { className: "caf-documents" },
     h(DocTabbar, { docs, active, dspec, types, close, onAdd, label, ctx }),
     typePicker,
-    h(Panel, { spec: { blocks: aspec.blocks }, ctx: scoped })
+    // Keyed by document id: switching tabs REMOUNTS the pane, so DOM-held
+    // state can't leak across documents. Measured: the native file input
+    // kept showing the previous document's filename.
+    h(Panel, { key: active.id, spec: { blocks: aspec.blocks }, ctx: scoped })
   );
 }
 
@@ -1133,6 +1145,7 @@ export function createApp(spec = {}) {
       colors: (n) => seriesColors(spec.theme && spec.theme.seed, n),
       viewport: narrow ? "mobile" : "desktop",
       _navTabs: narrow && spec.mobile && spec.mobile.nav === "bottom" ? findNavTabs(spec) : null,
+      _Block: Block, // for layouts in other modules (steps) that render blocks
       machine: spec.machine || null,
       send: spec.machine
         ? (eventName, payload) => runMachineEvent(spec.machine, state.update, eventName, payload)
@@ -1157,13 +1170,15 @@ export function createApp(spec = {}) {
       : h(
           "span",
           { className: "caf-logo caf-logo-mono", "aria-hidden": true },
+          // First letter/digit of each word — punctuation "words" like the
+          // "-" in "Caja - Camión" must not become half the monogram.
           (spec.title || "?")
             .split(/\s+/)
-            .map((w) => w[0])
+            .map((w) => (w.match(/[\p{L}\p{N}]/u) || [])[0])
             .filter(Boolean)
             .slice(0, 2)
             .join("")
-            .toUpperCase()
+            .toUpperCase() || "?"
         );
 
     return h(
@@ -1192,7 +1207,11 @@ export function createApp(spec = {}) {
           )
         : !state.isHydrated() || libsState === "loading"
         ? h("div", { className: "caf-block caf-loading" }, libsState === "loading" ? "Loading libraries…" : "Loading…")
-        : h(Layout, { spec, ctx }),
+        : // The same containment blocks get, one level up: a crash inside a
+          // layout (a throwing sort, a bad row callback) shows a named error
+          // under the header instead of killing the whole app. Measured: an
+          // unhandled row-action throw once blanked an entire blind app.
+          h(boundary(ctx.React), null, h(Layout, { spec, ctx })),
       spec.brand && spec.brand.footer ? h("footer", { className: "caf-footer" }, spec.brand.footer) : null
     );
   };
@@ -1204,7 +1223,9 @@ const BASE_CSS = `
   --caf-control-radius: 7px; /* one radius for every control: buttons, inputs, rows */
   --caf-btn-pad-y: 0.45rem;
   --caf-btn-pad-x: 0.8rem;
-  --caf-num-primary: 2.1rem; /* the one size for a block's dominant number */
+  --caf-num-primary: 2.6rem; /* the one size for a block's dominant number — the largest thing on screen, bigger than the H1 */
+  --caf-accent-tint: color-mix(in srgb, var(--caf-accent) 7%, var(--caf-surface)); /* soft accent surface for the feature card */
+  --caf-block-gap: 1.75rem; /* ONE value for air between blocks, every layout (audited: workspace used a smaller gap for the same visual role) */
   box-sizing: border-box;
   min-height: 100vh;
   padding: 2rem 1.25rem 4rem;
@@ -1220,7 +1241,9 @@ const BASE_CSS = `
 .caf-header h1 { margin: 0; font-size: 1.5rem; font-weight: 650; letter-spacing: -0.01em; text-wrap: balance; }
 .caf-header p { margin: 0.4rem 0 0; color: var(--caf-muted); font-size: 0.95rem; line-height: 1.5; }
 /* Between-card air must beat within-card padding (1.1rem), or groups dissolve. */
-.caf-panel { max-width: 760px; margin: 0 auto; display: grid; grid-template-columns: 1fr 1fr; gap: 1.75rem 1rem; }
+/* align-items: start — a short card must not stretch to its tall neighbor's
+   height; the stretched version reads as dead air (audited). */
+.caf-panel { max-width: 760px; margin: 0 auto; display: grid; grid-template-columns: 1fr 1fr; gap: var(--caf-block-gap) 1rem; align-items: start; }
 .caf-slot { grid-column: span 2; min-width: 0; }
 @media (min-width: 720px) { .caf-slot { grid-column: span 1; } .caf-slot-wide { grid-column: span 2; } }
 .caf-block {
@@ -1314,8 +1337,11 @@ const BASE_CSS = `
 .caf-timer-done { color: var(--caf-accent); }
 .caf-timer-fill { transition: width 0.9s linear; }
 .caf-timer-controls { display: flex; gap: 0.6rem; }
-.caf-btn:disabled { opacity: 0.45; cursor: not-allowed; }
+/* Disabled goes NEUTRAL, not pale-accent: a washed-out primary reads as
+   broken (audited on the chat Send with an empty input). */
+.caf-btn:disabled { cursor: not-allowed; background: var(--caf-sunken); color: var(--caf-muted); border-color: var(--caf-border); opacity: 1; }
 .caf-steps-progress { display: flex; flex-direction: column; gap: 0.35rem; margin-bottom: 0.2rem; }
+.caf-steps-result { display: flex; flex-direction: column; gap: 1rem; min-width: 0; }
 .caf-steps-fill { transition: width 0.25s ease; }
 .caf-step-text { margin: 0; color: var(--caf-muted); font-size: 0.92rem; line-height: 1.55; }
 .caf-step-nav { display: flex; justify-content: space-between; gap: 0.6rem; margin-top: 0.4rem; }
@@ -1345,7 +1371,9 @@ const BASE_CSS = `
 .caf-row-wrap { display: flex; align-items: center; gap: 0.4rem; }
 .caf-row-wrap .caf-row { flex: 1; min-width: 0; }
 .caf-row-actions { display: flex; gap: 0.35rem; flex: none; padding-right: 0.3rem; }
-.caf-btn-sm { font-size: 0.78rem; padding: calc(var(--caf-btn-pad-y) * 0.67) calc(var(--caf-btn-pad-x) * 0.75); }
+/* min-width keeps row actions' left edges aligned across rows even when
+   labels differ ("Hecho" vs "Desmarcar" — audited misalignment). */
+.caf-btn-sm { font-size: 0.78rem; padding: calc(var(--caf-btn-pad-y) * 0.67) calc(var(--caf-btn-pad-x) * 0.75); min-width: 76px; text-align: center; }
 .caf-items { display: flex; flex-direction: column; gap: 0.5rem; border-top: 1px solid var(--caf-border); padding-top: 0.7rem; }
 .caf-item-row { display: flex; align-items: flex-end; gap: 0.5rem; }
 .caf-item-row .caf-field { flex: 1; min-width: 0; }
@@ -1359,8 +1387,8 @@ const BASE_CSS = `
 .caf-md-li { display: block; padding-left: 1rem; position: relative; }
 .caf-md-li::before { content: "•"; position: absolute; left: 0.2rem; opacity: 0.6; }
 .caf-workspace { max-width: 1200px; margin: 0 auto; display: flex; gap: 1rem; align-items: flex-start; }
-.caf-ws-main { flex: 1; min-width: 0; display: flex; flex-direction: column; gap: 1rem; }
-.caf-ws-side { width: 340px; flex: none; display: flex; flex-direction: column; gap: 1rem; position: sticky; top: 1rem; }
+.caf-ws-main { flex: 1; min-width: 0; display: flex; flex-direction: column; gap: var(--caf-block-gap); }
+.caf-ws-side { width: 340px; flex: none; display: flex; flex-direction: column; gap: var(--caf-block-gap); position: sticky; top: 1rem; }
 .caf-ws-slot { min-width: 0; }
 .caf-chat-panel { display: flex; flex-direction: column; min-height: 0; }
 .caf-ws-side .caf-chat-log { max-height: calc(100vh - 220px); }
@@ -1445,6 +1473,11 @@ const BASE_CSS = `
 /* Never-clip guarantee: content inside a custom block that is wider than the
    phone (column grids, week views) must scroll, not disappear off-screen. */
 .caf-custom { overflow-x: auto; }
+/* The one differentiated surface per screen: accent top rule + tinted bg on
+   the block holding the hero number. Everything-is-the-same-card was the
+   audited root cause of the "generic template" look. (Late in the sheet on
+   purpose — it must win over .caf-block's border/background.) */
+.caf-block-feature { border-top: 3px solid var(--caf-accent); background: var(--caf-accent-tint); }
 /* mobile.nav: "bottom" — the app-shell tab bar pinned to the thumb zone.
    Tabs share the width evenly so every section stays visible; the root
    reserves space so the bar never covers the end of the content. */

package/src/blocks.js

@@ -178,9 +178,14 @@ export function OutputBlock({ spec, ctx }) {
   if (!items.length) {
     return h("div", { className: "caf-block caf-empty" }, spec.empty || "Nothing to show yet.");
   }
+  // The block holding the screen's hero number (a `big` stat) gets the one
+  // differentiated surface — an accent-tinted feature card. Audited miss:
+  // with a single card chrome, the most important number on screen weighed
+  // exactly the same as everything else.
+  const hero = items.some((it) => it && it.big);
   return h(
     "div",
-    { className: "caf-block caf-output" },
+    { className: hero ? "caf-block caf-output caf-block-feature" : "caf-block caf-output" },
     spec.title ? h("h2", { className: "caf-block-title" }, spec.title) : null,
     h(
       "div",
@@ -202,12 +207,14 @@ export function OutputBlock({ spec, ctx }) {
 // 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 }) {
+export function BannerBlock({ spec }) {
   const b = typeof spec.banner === "string" ? { title: spec.banner } : spec.banner || {};
-  const [c1, c2] = ctx.colors(2);
+  // Tonal gradient, one hue family: the golden-angle series palette is for
+  // CHARTS (categorical distinction) — on a brand surface its second hue
+  // clashes (audited: an orange seed produced an orange→green banner).
   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})`;
+    : `linear-gradient(135deg, color-mix(in srgb, var(--caf-accent) 82%, #000), var(--caf-accent) 55%, color-mix(in srgb, var(--caf-accent) 72%, #fff))`;
   return h(
     "div",
     { className: "caf-banner", style: { background } },

package/src/records.js

@@ -54,6 +54,27 @@ function makeId() {
   return "r" + Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
 }
 
+// Call-by-name for row callbacks. The measured 50/50 trap: both
+// `when: (r, viewerId)` (the old documented form) and `run: (r, viewerId)`
+// (the mistake that killed an entire blind app — `data` skipped, so `d`
+// held a viewer-id string) exist in the wild. Positions lie; names don't:
+// if the second declared parameter is named like the viewer id, hand it
+// the viewer id. Every callback gets what its own names ask for, and the
+// uniform (record, data, viewerId) order in the docs stays the one truth.
+const rowCallLegacy = new WeakMap();
+function rowCall(fn, rec, data, viewerId) {
+  let legacy = rowCallLegacy.get(fn);
+  if (legacy === undefined) {
+    const src = String(fn);
+    const arrow = src.match(/^\s*(?:async\s+)?([\w$]+)\s*=>/); // one bare param
+    const parens = src.match(/^[^(]*\(([^)]*)\)/);
+    const params = arrow ? [arrow[1]] : parens ? parens[1].split(",").map((s) => s.trim().split(/[=\s:]/)[0]) : [];
+    legacy = /viewer|voter|usuario|user/i.test(params[1] || "");
+    rowCallLegacy.set(fn, legacy);
+  }
+  return legacy ? fn(rec, viewerId) : fn(rec, data, viewerId);
+}
+
 // 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 }) {
@@ -82,9 +103,13 @@ function Summary({ spec, records }) {
   if (!spec.summary) return null;
   const items = spec.summary(records) || [];
   if (!items.length) return null;
+  // Same rule as OutputBlock: the hero (big) stat promotes its card to the
+  // screen's feature surface. Re-audit caught this second render path
+  // missing the treatment — the rule must hold wherever big stats render.
+  const hero = items.some((it) => it && it.big);
   return h(
     "div",
-    { className: "caf-block caf-output" },
+    { className: hero ? "caf-block caf-output caf-block-feature" : "caf-block caf-output" },
     h(
       "div",
       { className: "caf-output-grid" },
@@ -184,7 +209,7 @@ function ListScreen({ spec, ctx }) {
                     "div",
                     { className: "caf-row-actions" },
                     spec.actions
-                      .filter((a) => !a.when || a.when(rec, ctx.viewerId))
+                      .filter((a) => !a.when || rowCall(a.when, rec, ctx.data, ctx.viewerId))
                       .map((a) =>
                         h(
                           "button",
@@ -195,7 +220,7 @@ function ListScreen({ spec, ctx }) {
                             onClick: () =>
                               ctx.update((d) => {
                                 const live = d.records.find((x) => x.id === rec.id);
-                                if (live) a.run(live, d, ctx.viewerId);
+                                if (live) rowCall(a.run, live, d, ctx.viewerId);
                               }),
                           },
                           a.label

package/src/steps.js

@@ -22,23 +22,32 @@ function stepErrors(step, data) {
 
 function ResultScreen({ step, ctx }) {
   const items = step.result(ctx.data) || [];
+  const Block = ctx._Block;
   return h(
     "div",
-    { className: "caf-block caf-output" },
-    step.title ? h("h2", { className: "caf-block-title" }, step.title) : null,
+    { className: "caf-steps-result" },
     h(
       "div",
-      { className: "caf-output-grid" },
-      items.map((item, i) =>
-        h(
-          "div",
-          { key: item.label ?? i, className: item.big ? "caf-stat caf-stat-big" : "caf-stat" },
-          h("span", { className: "caf-stat-label" }, item.label),
-          h("span", { className: "caf-stat-value" }, formatValue(item.value, item.format)),
-          item.hint ? h("small", { className: "caf-hint" }, item.hint) : null
+      // Same rule as OutputBlock: the hero (big) result gets the feature card.
+      { className: items.some((it) => it && it.big) ? "caf-block caf-output caf-block-feature" : "caf-block caf-output" },
+      step.title ? h("h2", { className: "caf-block-title" }, step.title) : null,
+      h(
+        "div",
+        { className: "caf-output-grid" },
+        items.map((item, i) =>
+          h(
+            "div",
+            { key: item.label ?? i, className: item.big ? "caf-stat caf-stat-big" : "caf-stat" },
+            h("span", { className: "caf-stat-label" }, item.label),
+            h("span", { className: "caf-stat-value" }, formatValue(item.value, item.format)),
+            item.hint ? h("small", { className: "caf-hint" }, item.hint) : null
+          )
         )
       )
     ),
+    // A result can end on more than stats: any declared blocks (charts,
+    // text, lists) render under the grid with full block services.
+    (step.blocks || []).map((b, i) => h(Block, { key: "rb" + i, block: b, ctx })),
     h(
       "div",
       { className: "caf-step-nav" },