claude-artifact-framework 0.5.1 → 0.6.0

package/package.json

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

@@ -39,6 +39,25 @@ function checkFields(fields, where) {
   }
 }
 
+const ACTION_KEYS = ["label", "run", "when", "kind"];
+
+function checkActions(actions, where) {
+  if (!Array.isArray(actions)) {
+    throw new Error(`claude-artifact-framework: ${where} must be an array of { label, run }.`);
+  }
+  actions.forEach((a, i) => {
+    if (!a || typeof a.label !== "string" || typeof a.run !== "function") {
+      throw new Error(`claude-artifact-framework: ${where}[${i}] needs a \`label\` string and a \`run\` function.`);
+    }
+    const unknown = Object.keys(a).filter((k) => !ACTION_KEYS.includes(k));
+    if (unknown.length) {
+      throw new Error(
+        `claude-artifact-framework: ${where}[${i}] has unknown keys (${unknown.join(", ")}). Valid keys: ${ACTION_KEYS.join(", ")}.`
+      );
+    }
+  });
+}
+
 function checkBlocks(blocks) {
   if (!Array.isArray(blocks)) {
     throw new Error("claude-artifact-framework: `blocks` must be an array.");
@@ -64,6 +83,7 @@ function checkBlocks(blocks) {
       );
     }
     checkFields(block.fields, `blocks[${i}]`);
+    if (known[0] === "actions") checkActions(block.actions, `blocks[${i}].actions`);
   });
 }
 
@@ -141,7 +161,7 @@ function validate(spec) {
         'claude-artifact-framework: layout "records" needs `records: { fields: [...] }` — the same field declarations the fields block uses.'
       );
     }
-    const RECORDS_KEYS = ["label", "fields", "title", "subtitle", "sort", "summary", "empty", "search", "compute"];
+    const RECORDS_KEYS = ["label", "fields", "title", "subtitle", "sort", "summary", "empty", "search", "compute", "items", "actions"];
     const unknownR = Object.keys(r).filter((k) => !RECORDS_KEYS.includes(k));
     if (unknownR.length) {
       throw new Error(
@@ -156,8 +176,28 @@ function validate(spec) {
       seen.add(f.key);
     }
     if (spec.blocks) checkBlocks(spec.blocks);
+    if (r.actions) checkActions(r.actions, "records.actions");
+    if (r.items) {
+      const ITEMS_KEYS = ["label", "fields", "empty"];
+      const unknownI = Object.keys(r.items).filter((k) => !ITEMS_KEYS.includes(k));
+      if (unknownI.length) {
+        throw new Error(
+          `claude-artifact-framework: records.items has unknown keys (${unknownI.join(", ")}). Valid keys: ${ITEMS_KEYS.join(", ")}.`
+        );
+      }
+      if (!Array.isArray(r.items.fields) || r.items.fields.length === 0) {
+        throw new Error("claude-artifact-framework: records.items needs `fields: [...]` — the same field declarations as everywhere else.");
+      }
+      checkFields(r.items.fields, "records.items");
+      for (const f of r.items.fields) {
+        if (f.key === "id") throw new Error('claude-artifact-framework: "id" is reserved on items — the framework assigns it.');
+      }
+      if (seen.has("items") || r.fields.some((f) => f.key === "items")) {
+        throw new Error('claude-artifact-framework: a records field cannot be named "items" when `items` is declared — that key holds the child collection.');
+      }
+    }
     for (const [key, c] of Object.entries(r.compute || {})) {
-      if (seen.has(key) || key === "id") {
+      if (seen.has(key) || key === "id" || (r.items && key === "items")) {
         throw new Error(
           `claude-artifact-framework: compute key "${key}" collides with a field key — computed values are derived, never stored.`
         );
@@ -449,6 +489,22 @@ const BASE_CSS = `
 .caf-search:focus-visible { outline: 2px solid var(--caf-accent); outline-offset: 1px; }
 .caf-computed { border-top: 1px solid var(--caf-border); padding-top: 0.7rem; }
 .caf-records-blocks { margin-top: 1rem; }
+.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: 0.3rem 0.6rem; border-radius: 6px; }
+.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; }
+.caf-item-row .caf-field label { font-size: 0.68rem; }
+.caf-item-remove { flex: none; margin-bottom: 0.15rem; }
+.caf-empty-sm { padding: 0.6rem; font-size: 0.82rem; }
+.caf-actions-row { display: flex; flex-wrap: wrap; gap: 0.6rem; }
+.caf-code { background: var(--caf-sunken); border-radius: 6px; padding: 0.55rem 0.7rem; font-size: 0.8rem; overflow-x: auto; margin: 0.3rem 0; font-family: ui-monospace, monospace; }
+.caf-msg code { background: color-mix(in srgb, currentColor 12%, transparent); border-radius: 4px; padding: 0.05rem 0.3rem; font-size: 0.85em; font-family: ui-monospace, monospace; }
+.caf-md-h { display: block; margin-top: 0.3rem; }
+.caf-md-li { display: block; padding-left: 1rem; position: relative; }
+.caf-md-li::before { content: "•"; position: absolute; left: 0.2rem; opacity: 0.6; }
 .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); }

package/src/blocks.js

@@ -365,6 +365,39 @@ export function TimerBlock({ spec, ctx }) {
   );
 }
 
+// Declarative buttons that mutate data — the one-tap interactions (counters,
+// check-ins, +1s) that previously forced an escape to custom code.
+export function ActionsBlock({ spec, ctx }) {
+  const actions = spec.actions || [];
+  const visible = actions.filter((a) => !a.when || a.when(ctx.data));
+  return h(
+    "div",
+    { className: "caf-block caf-actions" },
+    spec.title ? h("h2", { className: "caf-block-title" }, spec.title) : null,
+    h(
+      "div",
+      { className: "caf-actions-row" },
+      visible.map((a) =>
+        h(
+          "button",
+          {
+            key: a.label,
+            type: "button",
+            className:
+              a.kind === "danger"
+                ? "caf-btn caf-btn-danger"
+                : a.kind === "primary"
+                ? "caf-btn caf-btn-primary"
+                : "caf-btn",
+            onClick: () => ctx.update((d) => a.run(d)),
+          },
+          a.label
+        )
+      )
+    )
+  );
+}
+
 // The escape hatch. Receives the same ctx every built-in block gets, so a
 // custom block keeps persistence, theming, navigation and the error boundary.
 export function CustomBlock({ spec, ctx }) {
@@ -382,6 +415,7 @@ export const BLOCKS = {
   list: ListBlock,
   chart: ChartBlock,
   timer: TimerBlock,
+  actions: ActionsBlock,
   custom: CustomBlock,
 };
 

package/src/chat.js

@@ -125,6 +125,29 @@ function runTools(calls, tools, ctx) {
   });
 }
 
+// Claude answers in markdown; showing raw asterisks makes every chat app
+// look broken. Minimal renderer: HTML is escaped FIRST, then a small set of
+// markdown forms is layered on, so model output can never inject markup.
+const escHtml = (t) => String(t).replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c]));
+
+export function renderMarkdown(text) {
+  const codeBlocks = [];
+  let t = String(text).replace(/```[a-z]*\n?([\s\S]*?)```/g, (m, code) => {
+    codeBlocks.push(code.replace(/\n$/, ""));
+    return "\u0000" + (codeBlocks.length - 1) + "\u0000";
+  });
+  t = escHtml(t);
+  t = t.replace(/`([^`]+)`/g, "<code>$1</code>");
+  t = t.replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>");
+  t = t.replace(/(^|[^*])\*([^*\n]+)\*/g, "$1<em>$2</em>");
+  t = t.replace(/^#{1,3} (.+)$/gm, '<strong class="caf-md-h">$1</strong>');
+  t = t.replace(/^[-•*] (.+)$/gm, '<span class="caf-md-li">$1</span>');
+  t = t.replace(/^\d+\. (.+)$/gm, '<span class="caf-md-li caf-md-num">$1</span>');
+  t = t.replace(/\n/g, "<br>");
+  t = t.replace(/\u0000(\d+)\u0000/g, (m, i) => '<pre class="caf-code">' + escHtml(codeBlocks[Number(i)]) + "</pre>");
+  return t;
+}
+
 function Bubble({ m }) {
   if (m.role === "tools") {
     return h("div", { className: "caf-msg-tools" }, `used: ${m.tools.join(", ")}`);
@@ -138,7 +161,11 @@ function Bubble({ m }) {
       h("span", { className: "caf-hint" }, "Your message is kept — send again to retry.")
     );
   }
-  return h("div", { className: m.role === "user" ? "caf-msg caf-msg-user" : "caf-msg caf-msg-assistant" }, m.content);
+  if (m.role === "user") return h("div", { className: "caf-msg caf-msg-user" }, m.content);
+  return h("div", {
+    className: "caf-msg caf-msg-assistant",
+    dangerouslySetInnerHTML: { __html: renderMarkdown(m.content) },
+  });
 }
 
 export function ChatLayout({ spec, ctx }) {
@@ -220,29 +247,43 @@ export function ChatLayout({ spec, ctx }) {
     h(
       "div",
       { className: "caf-block caf-chat-log" },
-      c.greeting ? h("div", { className: "caf-msg caf-msg-assistant" }, c.greeting) : null,
+      c.greeting
+        ? h("div", { className: "caf-msg caf-msg-assistant", dangerouslySetInnerHTML: { __html: renderMarkdown(c.greeting) } })
+        : null,
       log.map((m, i) => h(Bubble, { key: i, m })),
-      live !== null ? h("div", { className: "caf-msg caf-msg-assistant caf-msg-live" }, live || "…") : null,
+      live !== null
+        ? h("div", { className: "caf-msg caf-msg-assistant caf-msg-live", dangerouslySetInnerHTML: { __html: renderMarkdown(live || "…") } })
+        : null,
       busy && live === null ? h("div", { className: "caf-msg-tools" }, "thinking…") : null,
       h("div", { ref: endRef })
     ),
+    // Deliberately NOT a <form>: the artifact iframe's sandbox lacks
+    // allow-forms, so native form submission is blocked there — and on mobile
+    // the keyboard's send key triggers exactly that implicit submission. A
+    // plain div with onClick + Enter via onKeyDown never touches the native
+    // form machinery, so it can't be sandboxed away.
     h(
-      "form",
-      {
-        className: "caf-chat-input",
-        onSubmit: (e) => {
-          e.preventDefault();
-          send();
-        },
-      },
+      "div",
+      { className: "caf-chat-input" },
       h("input", {
         value: draft,
         placeholder: c.placeholder || "Message…",
         disabled: busy,
+        enterKeyHint: "send",
         onChange: (e) => setDraft(e.target.value),
+        onKeyDown: (e) => {
+          if (e.key === "Enter") {
+            e.preventDefault();
+            send();
+          }
+        },
         "aria-label": "Message",
       }),
-      h("button", { type: "submit", className: "caf-btn caf-btn-primary", disabled: busy || !draft.trim() }, "Send")
+      h(
+        "button",
+        { type: "button", className: "caf-btn caf-btn-primary", disabled: busy || !draft.trim(), onClick: send },
+        "Send"
+      )
     )
   );
 }

package/src/records.js

@@ -99,6 +99,7 @@ function ListScreen({ spec, ctx }) {
 
   function add() {
     const rec = { id: makeId(), ...recordDefaults(spec.fields) };
+    if (spec.items) rec.items = [];
     ctx.update((d) => {
       d.records = [...d.records, rec];
     });
@@ -134,15 +135,42 @@ function ListScreen({ spec, ctx }) {
         ? h("div", { className: "caf-empty" }, spec.empty || `No ${label}s yet. Add the first one.`)
         : records.map((rec) =>
             h(
-              "button",
-              {
-                key: rec.id,
-                type: "button",
-                className: "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
+              "div",
+              { key: rec.id, className: "caf-row-wrap" },
+              h(
+                "button",
+                {
+                  type: "button",
+                  className: "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.actions
+                ? h(
+                    "div",
+                    { className: "caf-row-actions" },
+                    spec.actions
+                      .filter((a) => !a.when || a.when(rec))
+                      .map((a) =>
+                        h(
+                          "button",
+                          {
+                            key: a.label,
+                            type: "button",
+                            className: a.kind === "danger" ? "caf-btn caf-btn-danger caf-btn-sm" : "caf-btn caf-btn-sm",
+                            onClick: () =>
+                              ctx.update((d) => {
+                                const live = d.records.find((x) => x.id === rec.id);
+                                if (live) a.run(live, d);
+                              }),
+                          },
+                          a.label
+                        )
+                      )
+                  )
+                : null
             )
           )
   );
@@ -179,6 +207,7 @@ function DetailScreen({ spec, ctx, record }) {
           }),
       })
     ),
+    spec.items ? h(ItemsEditor, { spec, ctx, record }) : null,
     spec.compute
       ? h(
           "div",
@@ -197,6 +226,75 @@ function DetailScreen({ spec, ctx, record }) {
   );
 }
 
+// The child collection edits INLINE on the parent's detail screen — one
+// navigation level, no child screens. That bounds the feature honestly: items
+// are for small rows (2-4 fields), not for records that deserve their own
+// detail view.
+function ItemsEditor({ spec, ctx, record }) {
+  const ispec = spec.items;
+  const label = ispec.label || "item";
+
+  function mutate(fn) {
+    ctx.update((d) => {
+      const rec = d.records.find((r) => r.id === record.id);
+      if (!rec) return;
+      if (!Array.isArray(rec.items)) rec.items = [];
+      fn(rec);
+    });
+  }
+
+  const items = Array.isArray(record.items) ? record.items : [];
+
+  return h(
+    "div",
+    { className: "caf-items" },
+    h(
+      "div",
+      { className: "caf-toolbar" },
+      h("span", { className: "caf-count" }, `${items.length} ${label}${items.length === 1 ? "" : "s"}`),
+      h(
+        "button",
+        {
+          type: "button",
+          className: "caf-btn caf-btn-sm",
+          onClick: () => mutate((rec) => rec.items.push({ id: makeId(), ...recordDefaults(ispec.fields) })),
+        },
+        `Add ${label}`
+      )
+    ),
+    items.length === 0
+      ? h("div", { className: "caf-empty caf-empty-sm" }, ispec.empty || `No ${label}s yet.`)
+      : items.map((item) =>
+          h(
+            "div",
+            { key: item.id, className: "caf-item-row" },
+            ispec.fields.map((field) =>
+              h(Field, {
+                key: field.key,
+                field,
+                value: item[field.key],
+                onChange: (v) =>
+                  mutate((rec) => {
+                    const it = rec.items.find((x) => x.id === item.id);
+                    if (it) it[field.key] = v;
+                  }),
+              })
+            ),
+            h(
+              "button",
+              {
+                type: "button",
+                className: "caf-btn caf-btn-danger caf-btn-sm caf-item-remove",
+                "aria-label": `Remove ${label}`,
+                onClick: () => mutate((rec) => { rec.items = rec.items.filter((x) => x.id !== item.id); }),
+              },
+              "✕"
+            )
+          )
+        )
+  );
+}
+
 export function RecordsLayout({ spec, ctx }) {
   const rspec = spec.records;