claude-artifact-framework 0.14.1 → 0.16.0

package/llms.txt

@@ -12,16 +12,21 @@ 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
+  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, chat, tabs,
-  records, custom — plus per-block title, when:(d)=>bool, state:"fase",
-  collapsible, wide, fill (custom only)
+- 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 (+ key when used as a block)
+  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
@@ -56,6 +61,13 @@ https://cdn.jsdelivr.net/npm/claude-artifact-framework/dist/index.global.js
     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.
+14. Column grids in custom (kanban, week views) branch on ctx.viewport
+    ("mobile" < 720px | "desktop", reactive) — stack columns on mobile; half
+    the viewers are on a phone. The framework never clips (wide custom
+    content scrolls), but scrolling is the fallback, not the design.
 
 ## Canonical example
 

package/package.json

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

@@ -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;
@@ -991,6 +1029,17 @@ export function createApp(spec = {}) {
       );
     }
     const [, force] = useState(0);
+    // ctx.viewport shares the 720px breakpoint the block grid already uses,
+    // so a custom block that branches on it flips in sync with the layout.
+    const [narrow, setNarrow] = useState(
+      () => typeof window !== "undefined" && window.matchMedia("(max-width: 719px)").matches
+    );
+    useEffect(() => {
+      const mq = window.matchMedia("(max-width: 719px)");
+      const onChange = (e) => setNarrow(e.matches);
+      mq.addEventListener("change", onChange);
+      return () => mq.removeEventListener("change", onChange);
+    }, []);
     const [libsState, setLibsState] = useState(spec.libs && spec.libs.length ? "loading" : "ready");
     const [libsError, setLibsError] = useState(null);
     useEffect(() => {
@@ -1043,6 +1092,7 @@ export function createApp(spec = {}) {
       setTab: (key, i) => state.setView({ tabs: { ...state.getView().tabs, [key]: i } }),
       toggleCollapsed: (key, val) => state.setView({ collapsed: { ...state.getView().collapsed, [key]: val } }),
       colors: (n) => seriesColors(spec.theme && spec.theme.seed, n),
+      viewport: narrow ? "mobile" : "desktop",
       machine: spec.machine || null,
       send: spec.machine
         ? (eventName, payload) => runMachineEvent(spec.machine, state.update, eventName, payload)
@@ -1053,6 +1103,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 +1134,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 +1152,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,10 +1367,47 @@ 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; }
 .caf-block-error { border-color: var(--caf-danger); gap: 0.4rem; }
 .caf-block-error strong { font-size: 0.9rem; color: var(--caf-danger); }
 .caf-block-error code { font-size: 0.78rem; color: var(--caf-muted); word-break: break-word; }
+/* 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; }
+/* 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; }
+  .caf-btn-sm, .caf-doc-close, .caf-item-remove { min-height: 40px; }
+}
 `;

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(
@@ -449,7 +485,10 @@ export function CustomBlock({ spec, ctx }) {
   const rendered = spec.custom(ctx);
   // `fill: true` frees the block from the card chrome so it can own a large
   // scrollable surface (a viewer, a canvas) — the workspace main-area case.
-  const cls = spec.fill ? "caf-block caf-block-fill" : "caf-block";
+  // caf-custom guarantees a custom block can never CLIP its content on a
+  // narrow screen: wide hand-built grids become scrollable, not amputated
+  // (measured: a week grid cut off its last column at 390px with no way in).
+  const cls = spec.fill ? "caf-block caf-block-fill caf-custom" : "caf-block caf-custom";
   if (typeof rendered === "string") {
     return h("div", { className: cls, dangerouslySetInnerHTML: { __html: rendered } });
   }
@@ -464,6 +503,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(