claude-artifact-framework 0.6.0 → 0.7.1

package/package.json

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

@@ -17,13 +17,13 @@ import { RecordsLayout } from "./records.js";
 import { StepsLayout } from "./steps.js";
 import { ChatLayout, CHAT_KEYS } from "./chat.js";
 
-const LAYOUTS = ["panel", "records", "steps", "chat"];
+const LAYOUTS = ["panel", "records", "steps", "chat", "workspace"];
 const RESERVED = ["title", "empty", "wide", "onSelect", "subtitle"];
 
 // 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"];
+const TOP_KEYS = ["title", "subtitle", "theme", "layout", "blocks", "records", "steps", "chat", "data", "shared", "main", "sidebar"];
 
 // An unknown field type used to fall through silently to a text input — the
 // exact quiet degradation the framework exists to prevent (a blind-tested
@@ -36,6 +36,32 @@ function checkFields(fields, where) {
         `claude-artifact-framework: field "${f.key}" in ${where} has unknown type "${f.type}". Valid types: ${FIELD_TYPES.join(", ")}.`
       );
     }
+    if (f.type === "select" && f.options !== undefined && !Array.isArray(f.options) && typeof f.options !== "function") {
+      throw new Error(
+        `claude-artifact-framework: field "${f.key}" in ${where}: \`options\` must be an array or a function of data returning one.`
+      );
+    }
+  }
+}
+
+function checkChatConfig(c, where) {
+  if (!c || (typeof c.system !== "string" && typeof c.system !== "function")) {
+    throw new Error(
+      `claude-artifact-framework: ${where} needs \`{ system: "..." }\` (a string or a function of data).`
+    );
+  }
+  const unknown = Object.keys(c).filter((k) => !CHAT_KEYS.includes(k));
+  if (unknown.length) {
+    throw new Error(
+      `claude-artifact-framework: ${where} has unknown keys (${unknown.join(", ")}). Valid keys: ${CHAT_KEYS.join(", ")}.`
+    );
+  }
+  for (const [name, tool] of Object.entries(c.tools || {})) {
+    if (!tool || typeof tool.description !== "string" || typeof tool.run !== "function") {
+      throw new Error(
+        `claude-artifact-framework: chat tool "${name}" needs a \`description\` string and a \`run(input, ctx)\` function.`
+      );
+    }
   }
 }
 
@@ -84,6 +110,7 @@ function checkBlocks(blocks) {
     }
     checkFields(block.fields, `blocks[${i}]`);
     if (known[0] === "actions") checkActions(block.actions, `blocks[${i}].actions`);
+    if (known[0] === "chat") checkChatConfig(block.chat, `blocks[${i}].chat`);
   });
 }
 
@@ -133,25 +160,28 @@ function validate(spec) {
     return layout;
   }
   if (layout === "chat") {
-    const c = spec.chat;
-    if (!c || (typeof c.system !== "string" && typeof c.system !== "function")) {
+    checkChatConfig(spec.chat, "chat");
+    return layout;
+  }
+  if (layout === "workspace") {
+    if (!Array.isArray(spec.main) || spec.main.length === 0) {
       throw new Error(
-        'claude-artifact-framework: layout "chat" needs `chat: { system: "..." }` (a string or a function of data).'
+        'claude-artifact-framework: layout "workspace" needs `main: [...]` (an array of blocks). `sidebar: [...]` is optional.'
       );
     }
-    const unknown = Object.keys(c).filter((k) => !CHAT_KEYS.includes(k));
-    if (unknown.length) {
+    checkBlocks(spec.main);
+    if (spec.sidebar !== undefined) {
+      if (!Array.isArray(spec.sidebar)) {
+        throw new Error("claude-artifact-framework: workspace `sidebar` must be an array of blocks.");
+      }
+      checkBlocks(spec.sidebar);
+    }
+    const chats = [...spec.main, ...(spec.sidebar || [])].filter((b) => b && b.chat);
+    if (chats.length > 1) {
       throw new Error(
-        `claude-artifact-framework: chat has unknown keys (${unknown.join(", ")}). Valid keys: ${CHAT_KEYS.join(", ")}.`
+        "claude-artifact-framework: only one chat block per app — the conversation persists under data.chat and there is exactly one."
       );
     }
-    for (const [name, tool] of Object.entries(c.tools || {})) {
-      if (!tool || typeof tool.description !== "string" || typeof tool.run !== "function") {
-        throw new Error(
-          `claude-artifact-framework: chat tool "${name}" needs a \`description\` string and a \`run(input, ctx)\` function.`
-        );
-      }
-    }
     return layout;
   }
   if (layout === "records") {
@@ -222,10 +252,12 @@ function defaultsFrom(spec) {
   if ((spec.layout || "panel") === "records" && !Array.isArray(data.records)) {
     data.records = [];
   }
-  if ((spec.layout || "panel") === "chat" && !data.chat) {
+  const allBlocks = [...(spec.blocks || []), ...(spec.main || []), ...(spec.sidebar || [])];
+  const hasChat = (spec.layout || "panel") === "chat" || allBlocks.some((b) => b && b.chat);
+  if (hasChat && !data.chat) {
     data.chat = { api: [], log: [] };
   }
-  for (const block of [...(spec.blocks || []), ...(spec.steps || [])]) {
+  for (const block of [...allBlocks, ...(spec.steps || [])]) {
     for (const field of block.fields || []) {
       if (field && field.key !== undefined && !(field.key in data)) {
         data[field.key] = field.value !== undefined ? field.value : field.type === "check" ? false : "";
@@ -312,7 +344,20 @@ function RecordsWithBlocks({ spec, ctx }) {
   );
 }
 
-const LAYOUT_COMPONENTS = { panel: Panel, records: RecordsWithBlocks, steps: StepsLayout, chat: ChatLayout };
+// The "content + copilot" shape: a full-width main column and a sidebar.
+// Stacks vertically on narrow screens (sidebar after main).
+function WorkspaceLayout({ spec, ctx }) {
+  const render = (blocks) =>
+    (blocks || []).map((block, i) => h("section", { key: i, className: "caf-ws-slot" }, h(Block, { block, ctx })));
+  return h(
+    "div",
+    { className: "caf-workspace" },
+    h("div", { className: "caf-ws-main" }, render(spec.main)),
+    spec.sidebar && spec.sidebar.length ? h("div", { className: "caf-ws-side" }, render(spec.sidebar)) : null
+  );
+}
+
+const LAYOUT_COMPONENTS = { panel: Panel, records: RecordsWithBlocks, steps: StepsLayout, chat: ChatLayout, workspace: WorkspaceLayout };
 
 export function createApp(spec = {}) {
   const layout = validate(spec);
@@ -505,6 +550,16 @@ const BASE_CSS = `
 .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-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-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); }
+@media (max-width: 900px) {
+  .caf-workspace { flex-direction: column; align-items: stretch; }
+  .caf-ws-side { width: 100%; position: static; }
+}
 .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

@@ -11,6 +11,7 @@
 // Bound lazily rather than snapshotted as `React.createElement`, because this
 // runs at module load — before the host has had a chance to hand React over.
 import { createElement as h, useState, useEffect } from "react";
+import { ChatPanel } from "./chat.js";
 
 const FIELD_TYPES = ["text", "textarea", "number", "money", "percent", "check", "date", "select"];
 
@@ -49,7 +50,7 @@ export function validateField(field, value) {
   return null;
 }
 
-export function Field({ field, value, onChange }) {
+export function Field({ field, value, onChange, data }) {
   const error = validateField(field, value);
   const id = `caf-f-${field.key}`;
   const numeric = field.type === "number" || field.type === "money" || field.type === "percent";
@@ -79,11 +80,14 @@ export function Field({ field, value, onChange }) {
   if (field.type === "textarea") {
     control = h("textarea", { ...common, rows: field.rows || 3 });
   } else if (field.type === "select") {
+    // Options may be declared as a function of the app data, for selects
+    // whose choices come from what the user has entered elsewhere.
+    const options = typeof field.options === "function" ? field.options(data) || [] : field.options || [];
     control = h(
       "select",
       common,
       h("option", { value: "" }, field.placeholder || "Select…"),
-      (field.options || []).map((opt) => {
+      options.map((opt) => {
         const val = typeof opt === "string" ? opt : opt.value;
         const label = typeof opt === "string" ? opt : opt.label;
         return h("option", { key: val, value: val }, label);
@@ -126,6 +130,7 @@ export function FieldsBlock({ spec, ctx }) {
       h(Field, {
         key: field.key,
         field,
+        data: ctx.data,
         value: ctx.data[field.key],
         onChange: (v) => ctx.update((d) => { d[field.key] = v; }),
       })
@@ -170,13 +175,18 @@ export function TextBlock({ spec, ctx }) {
 
 export function ListBlock({ spec, ctx }) {
   const rows = (typeof spec.list === "function" ? spec.list(ctx.data) : spec.list) || [];
+  // `title` follows the same convention as every other block: a string is the
+  // block heading. A function is the per-row title. Both are supported —
+  // making list the odd one out was an API inconsistency a blind test caught.
+  const heading = typeof spec.title === "string" ? spec.title : null;
+  const rowTitle = typeof spec.title === "function" ? spec.title : (r) => r.title ?? r.name ?? r.label ?? r.text ?? String(r);
   if (!rows.length) {
     return h("div", { className: "caf-block caf-empty" }, spec.empty || "Nothing here yet.");
   }
-  const title = spec.title || ((r) => r.title ?? r.name ?? r.label ?? String(r));
   return h(
     "div",
     { className: "caf-block caf-list" },
+    heading ? h("h2", { className: "caf-block-title" }, heading) : null,
     rows.map((row, i) =>
       h(
         "button",
@@ -186,7 +196,7 @@ export function ListBlock({ spec, ctx }) {
           type: "button",
           onClick: spec.onSelect ? () => spec.onSelect(row, ctx) : undefined,
         },
-        h("span", { className: "caf-row-title" }, title(row)),
+        h("span", { className: "caf-row-title" }, rowTitle(row)),
         spec.subtitle ? h("span", { className: "caf-row-sub" }, spec.subtitle(row)) : null
       )
     )
@@ -416,6 +426,7 @@ export const BLOCKS = {
   chart: ChartBlock,
   timer: TimerBlock,
   actions: ActionsBlock,
+  chat: ({ spec, ctx }) => h(ChatPanel, { cfg: spec.chat, ctx }),
   custom: CustomBlock,
 };
 

package/src/chat.js

@@ -168,8 +168,11 @@ function Bubble({ m }) {
   });
 }
 
-export function ChatLayout({ spec, ctx }) {
-  const c = spec.chat;
+// The embeddable core: everything the chat layout does, as a single column
+// that can live in a workspace sidebar (or any block slot) as well as fill
+// the whole app. One conversation per app — it persists under data.chat.
+export function ChatPanel({ cfg, ctx }) {
+  const c = cfg;
   const [draft, setDraft] = useState("");
   const [busy, setBusy] = useState(false);
   const [live, setLive] = useState(null);
@@ -243,7 +246,7 @@ export function ChatLayout({ spec, ctx }) {
 
   return h(
     "div",
-    { className: "caf-panel caf-panel-single" },
+    { className: "caf-chat-panel" },
     h(
       "div",
       { className: "caf-block caf-chat-log" },
@@ -287,3 +290,7 @@ export function ChatLayout({ spec, ctx }) {
     )
   );
 }
+
+export function ChatLayout({ spec, ctx }) {
+  return h("div", { className: "caf-panel caf-panel-single" }, h(ChatPanel, { cfg: spec.chat, ctx }));
+}

package/src/records.js

@@ -199,6 +199,7 @@ function DetailScreen({ spec, ctx, record }) {
       h(Field, {
         key: field.key,
         field,
+        data: ctx.data,
         value: record[field.key],
         onChange: (v) =>
           ctx.update((d) => {
@@ -272,6 +273,7 @@ function ItemsEditor({ spec, ctx, record }) {
               h(Field, {
                 key: field.key,
                 field,
+                data: ctx.data,
                 value: item[field.key],
                 onChange: (v) =>
                   mutate((rec) => {

package/src/steps.js

@@ -78,6 +78,7 @@ export function StepsLayout({ spec, ctx }) {
             h(Field, {
               key: field.key,
               field,
+              data: ctx.data,
               value: ctx.data[field.key],
               onChange: (v) => ctx.update((d) => { d[field.key] = v; }),
             })