claude-artifact-framework 0.16.0 → 0.18.0

package/llms.txt

@@ -14,7 +14,10 @@ https://cdn.jsdelivr.net/npm/claude-artifact-framework/dist/index.global.js
 - 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)
+  automatic monogram), mobile:{nav:"bottom"} (phone: pins the first
+  top-level tabs block's bar to the bottom — declare it when one tabs
+  block with 4+ sections IS the app; a top bar overflows sideways at
+  phone width and hides the last sections)
 - 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),
@@ -29,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 }
 
@@ -47,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.16.0",
+  "version": "0.18.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

@@ -26,7 +26,8 @@ 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", "brand"];
+const TOP_KEYS = ["title", "subtitle", "theme", "layout", "blocks", "records", "steps", "chat", "data", "shared", "main", "sidebar", "libs", "documents", "machine", "brand", "mobile"];
+const MOBILE_KEYS = ["nav"];
 
 const MACHINE_KEYS = ["key", "initial", "states", "events"];
 const MACHINE_STATE_KEYS = ["after"];
@@ -248,6 +249,18 @@ function checkMachine(m) {
   }
 }
 
+// The tabs block mobile.nav moves: the first one at the top level of the
+// panel's `blocks` or the workspace's `main`. Nested tabs never qualify —
+// a bottom bar is app-shell navigation, not in-page structure.
+function findNavTabs(spec) {
+  for (const list of [spec.blocks, spec.main]) {
+    if (!Array.isArray(list)) continue;
+    const found = list.find((b) => b && Array.isArray(b.tabs));
+    if (found) return found;
+  }
+  return null;
+}
+
 function validate(spec) {
   const unknownTop = Object.keys(spec).filter((k) => !TOP_KEYS.includes(k));
   if (unknownTop.length) {
@@ -272,6 +285,22 @@ function validate(spec) {
       throw new Error("claude-artifact-framework: `libs` must be an array of https:// script URLs.");
     }
   }
+  if (spec.mobile !== undefined) {
+    const unknownM = Object.keys(spec.mobile || {}).filter((k) => !MOBILE_KEYS.includes(k));
+    if (unknownM.length) {
+      throw new Error(
+        `claude-artifact-framework: mobile has unknown keys (${unknownM.join(", ")}). Valid keys: ${MOBILE_KEYS.join(", ")}.`
+      );
+    }
+    if (spec.mobile.nav !== undefined && spec.mobile.nav !== "bottom") {
+      throw new Error('claude-artifact-framework: mobile.nav only accepts "bottom" (omit `mobile` for the default top tab bar).');
+    }
+    if (spec.mobile.nav === "bottom" && !findNavTabs(spec)) {
+      throw new Error(
+        'claude-artifact-framework: mobile.nav: "bottom" moves a top-level `tabs` block\'s bar to the bottom of the phone screen — this spec has no top-level tabs block (in `blocks` or `main`) to move.'
+      );
+    }
+  }
   const layout = spec.layout || "panel";
   if (!LAYOUTS.includes(layout)) {
     throw new Error(
@@ -283,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") {
@@ -298,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)) {
@@ -576,17 +614,21 @@ function boundary(React) {
 
 // Tabs are defined here (not blocks.js) because they render other blocks —
 // keeping the recursion in one file avoids an import cycle.
-function TabsBlock({ spec, ctx }) {
+function TabsBlock({ spec, ctx, bottomNav }) {
   const tabs = spec.tabs;
   const key = tabs.map((t) => t.label).join("|");
   const stored = ctx.view.tabs ? ctx.view.tabs[key] : undefined;
   const active = Math.min(stored === undefined ? 0 : stored, tabs.length - 1);
+  // mobile.nav: "bottom" — on a phone, this block's bar becomes a fixed
+  // bottom nav: every section stays visible and inside the thumb zone
+  // instead of hiding behind the tab bar's sideways scroll.
+  const bottom = !!bottomNav && ctx.viewport === "mobile";
   return h(
     "div",
     { className: "caf-tabs" },
     h(
       "div",
-      { className: "caf-tabbar", role: "tablist" },
+      { className: bottom ? "caf-tabbar caf-tabbar-bottom" : "caf-tabbar", role: "tablist" },
       tabs.map((t, i) =>
         h(
           "button",
@@ -598,7 +640,11 @@ function TabsBlock({ spec, ctx }) {
             className: i === active ? "caf-tab caf-tab-active" : "caf-tab",
             onClick: () => ctx.setTab(key, i),
           },
-          t.icon ? `${t.icon} ${t.label}` : t.label
+          bottom && t.icon
+            ? [h("span", { key: "i", className: "caf-tab-ico", "aria-hidden": true }, t.icon), h("span", { key: "l", className: "caf-tab-lbl" }, t.label)]
+            : t.icon
+            ? `${t.icon} ${t.label}`
+            : t.label
         )
       )
     ),
@@ -618,6 +664,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;
+  // Identity against the original spec object — before any sugar copies it.
+  const bottomNav = ctx._navTabs !== undefined && ctx._navTabs === block;
   // `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));
@@ -625,7 +673,7 @@ function Block({ block, ctx }) {
   const inner = h(
     boundary(ctx.React),
     null,
-    h(Component, { spec: block.collapsible ? { ...block, title: undefined } : block, ctx })
+    h(Component, { spec: block.collapsible ? { ...block, title: undefined } : block, ctx, bottomNav })
   );
   if (!block.collapsible) return inner;
   // Collapsed state is framework-owned view state, keyed by the block's title
@@ -881,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 })
   );
 }
 
@@ -1093,6 +1144,8 @@ export function createApp(spec = {}) {
       toggleCollapsed: (key, val) => state.setView({ collapsed: { ...state.getView().collapsed, [key]: val } }),
       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)
@@ -1130,7 +1183,7 @@ export function createApp(spec = {}) {
       "div",
       // The layout class lets shared CSS follow the active container width —
       // e.g. the header must share the workspace's wider axis, not panel's.
-      { className: `caf-root caf-layout-${layout}` },
+      { className: `caf-root caf-layout-${layout}${ctx._navTabs ? " caf-has-bottomnav" : ""}` },
       h("style", { dangerouslySetInnerHTML: { __html: css } }),
       h(
         "header",
@@ -1152,7 +1205,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
     );
   };
@@ -1276,6 +1333,7 @@ const BASE_CSS = `
 .caf-timer-controls { display: flex; gap: 0.6rem; }
 .caf-btn:disabled { opacity: 0.45; cursor: not-allowed; }
 .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; }
@@ -1405,6 +1463,27 @@ 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; }
+/* 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. */
+.caf-has-bottomnav { padding-bottom: 76px; }
+.caf-tabbar-bottom {
+  position: fixed; bottom: 0; left: 0; right: 0; z-index: 40;
+  gap: 0; margin: 0; overflow-x: visible;
+  background: var(--caf-surface); border-top: 1px solid var(--caf-border); border-bottom: none;
+  padding: 0.25rem 0.4rem calc(0.3rem + env(safe-area-inset-bottom, 0px));
+  box-shadow: 0 -1px 6px rgba(0, 0, 0, 0.07);
+}
+.caf-tabbar-bottom .caf-tab {
+  flex: 1 1 0; min-width: 0; min-height: 48px;
+  display: flex; flex-direction: column; align-items: center; justify-content: center;
+  gap: 0.15rem; padding: 0.25rem 0.2rem; margin-bottom: 0;
+  font-size: 0.66rem; border-bottom: none;
+  overflow: hidden; text-overflow: ellipsis;
+}
+.caf-tabbar-bottom .caf-tab-ico { font-size: 1.25rem; line-height: 1; }
+.caf-tabbar-bottom .caf-tab-lbl { max-width: 100%; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.caf-tabbar-bottom .caf-tab-active, .caf-tabbar-bottom .caf-tab-active:hover { border-bottom-color: transparent; }
 /* Touch devices get tappable framework controls regardless of the spec. */
 @media (pointer: coarse) {
   .caf-btn, .caf-tab, .caf-field input, .caf-field select { min-height: 44px; }

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 }) {
@@ -184,7 +205,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 +216,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,31 @@ 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
+      { className: "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" },