claude-artifact-framework 0.7.2 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-artifact-framework",
-  "version": "0.7.2",
+  "version": "0.8.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",
@@ -18,7 +18,7 @@
     "build": "node scripts/build.mjs",
     "build:watch": "node scripts/build.mjs --watch",
     "prepublishOnly": "npm run build",
-    "release": "bash scripts/publish.sh"
+    "release": "node scripts/check-docs.mjs && bash scripts/publish.sh"
   },
   "devDependencies": {
     "esbuild": "^0.25.0"

package/src/app.js

@@ -18,12 +18,12 @@ import { StepsLayout } from "./steps.js";
 import { ChatLayout, CHAT_KEYS } from "./chat.js";
 
 const LAYOUTS = ["panel", "records", "steps", "chat", "workspace"];
-const RESERVED = ["title", "empty", "wide", "onSelect", "subtitle", "when", "collapsible"];
+const RESERVED = ["title", "empty", "wide", "onSelect", "subtitle", "when", "collapsible", "fill"];
 
 // 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"];
+const TOP_KEYS = ["title", "subtitle", "theme", "layout", "blocks", "records", "steps", "chat", "data", "shared", "main", "sidebar", "libs"];
 
 // 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
@@ -129,6 +129,9 @@ function checkBlocks(blocks) {
     if (block.when !== undefined && typeof block.when !== "function") {
       throw new Error(`claude-artifact-framework: blocks[${i}].when must be a function of data returning true/false.`);
     }
+    if (block.fill !== undefined && known[0] !== "custom") {
+      throw new Error(`claude-artifact-framework: \`fill\` is only valid on custom blocks — blocks[${i}] is "${known[0]}".`);
+    }
   });
 }
 
@@ -139,6 +142,11 @@ function validate(spec) {
       `claude-artifact-framework: unknown top-level keys (${unknownTop.join(", ")}). Valid keys: ${TOP_KEYS.join(", ")}.`
     );
   }
+  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.");
+    }
+  }
   const layout = spec.layout || "panel";
   if (!LAYOUTS.includes(layout)) {
     throw new Error(
@@ -217,6 +225,11 @@ function validate(spec) {
       );
     }
     checkFields(r.fields, "records");
+    if (r.fields.some((f) => f.type === "file") || (r.items && r.items.fields.some((f) => f.type === "file"))) {
+      throw new Error(
+        'claude-artifact-framework: `file` fields live in the flat data pool (panel blocks or steps) — they are not supported inside records or items.'
+      );
+    }
     const seen = new Set();
     for (const f of r.fields) {
       if (f.key === "id") throw new Error('claude-artifact-framework: "id" is reserved on records — the framework assigns it.');
@@ -455,10 +468,31 @@ function WorkspaceLayout({ spec, ctx }) {
 
 const LAYOUT_COMPONENTS = { panel: Panel, records: RecordsWithBlocks, steps: StepsLayout, chat: ChatLayout, workspace: WorkspaceLayout };
 
+// Deduped by src: two apps (or re-mounts) asking for the same lib share one
+// tag, mirroring how the PDF annotator loads pdf.js by hand.
+function loadScript(src) {
+  return new Promise((resolve, reject) => {
+    const existing = document.querySelector(`script[src="${src}"]`);
+    if (existing) {
+      if (existing.dataset.cafReady === "1") return resolve();
+      existing.addEventListener("load", resolve);
+      existing.addEventListener("error", () => reject(new Error(`failed to load ${src}`)));
+      return;
+    }
+    const tag = document.createElement("script");
+    tag.src = src;
+    tag.onload = () => { tag.dataset.cafReady = "1"; resolve(); };
+    tag.onerror = () => reject(new Error(`failed to load ${src}`));
+    document.head.appendChild(tag);
+  });
+}
+
 export function createApp(spec = {}) {
   const layout = validate(spec);
   const state = createAppState(defaultsFrom(spec), { shared: Boolean(spec.shared) });
   const css = themeCss(spec.theme && spec.theme.seed) + BASE_CSS;
+  // Live File objects picked by `file` fields — in memory only, never persisted.
+  const files = {};
 
   return function App() {
     if (!hasReact()) {
@@ -469,6 +503,15 @@ export function createApp(spec = {}) {
       );
     }
     const [, force] = useState(0);
+    const [libsState, setLibsState] = useState(spec.libs && spec.libs.length ? "loading" : "ready");
+    const [libsError, setLibsError] = useState(null);
+    useEffect(() => {
+      if (!spec.libs || !spec.libs.length) return;
+      Promise.all(spec.libs.map(loadScript)).then(
+        () => setLibsState("ready"),
+        (e) => { setLibsError(String((e && e.message) || e)); setLibsState("error"); }
+      );
+    }, []);
     useEffect(() => {
       const unsubscribe = state.subscribe(() => force((n) => n + 1));
       // Hydration can finish before this effect runs — its notify() then lands
@@ -486,6 +529,8 @@ export function createApp(spec = {}) {
       go: state.go,
       back: state.back,
       setStep: (n) => state.setView({ step: n }),
+      files,
+      viewerId: state.getViewerId(),
       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),
@@ -503,9 +548,16 @@ export function createApp(spec = {}) {
         spec.title ? h("h1", null, spec.title) : null,
         spec.subtitle ? h("p", null, spec.subtitle) : null
       ),
-      state.isHydrated()
-        ? h(Layout, { spec, ctx })
-        : h("div", { className: "caf-block caf-loading" }, "Loading…")
+      libsState === "error"
+        ? h(
+            "div",
+            { className: "caf-block caf-block-error" },
+            h("strong", null, "A library failed to load"),
+            h("code", null, libsError)
+          )
+        : !state.isHydrated() || libsState === "loading"
+        ? h("div", { className: "caf-block caf-loading" }, libsState === "loading" ? "Loading libraries…" : "Loading…")
+        : h(Layout, { spec, ctx })
     );
   };
 }
@@ -679,6 +731,7 @@ const BASE_CSS = `
 .caf-collapse-head:focus-visible { outline: 2px solid var(--caf-accent); outline-offset: 1px; }
 .caf-chevron { transition: transform 0.15s ease; color: var(--caf-muted); }
 .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); }

package/src/appState.js

@@ -14,6 +14,7 @@
 import { storage } from "./storage.js";
 
 const DATA_KEY = "caf:data";
+const VIEWER_KEY = "caf:viewer";
 const VIEW_KEY = "caf:view";
 
 const EMPTY_VIEW = { screen: null, arg: null, stack: [], step: 0, selected: null, tabs: {}, collapsed: {} };
@@ -54,6 +55,7 @@ export function createAppState(defaults, { debounceMs = 400, shared = false, pol
   let data = structuredCloneish(defaults);
   let view = { ...EMPTY_VIEW };
   let hydrated = false;
+  let viewerId = null;
   // Counts update() calls so a poll never overwrites edits that haven't been
   // persisted yet: remote state only applies when we owe storage nothing.
   let writes = 0;
@@ -97,10 +99,20 @@ export function createAppState(defaults, { debounceMs = 400, shared = false, pol
   }
 
   const ready = (async () => {
-    const [storedData, storedView] = await Promise.all([
+    const [storedData, storedView, storedViewer] = await Promise.all([
       dataStore.get(DATA_KEY, undefined),
       storage.get(VIEW_KEY, undefined),
+      storage.get(VIEWER_KEY, undefined),
     ]);
+    // A stable anonymous per-viewer id, ALWAYS in the personal scope — in a
+    // shared app it lets declarations express "one vote per person" and
+    // "added by", without any account system.
+    if (typeof storedViewer === "string" && storedViewer) {
+      viewerId = storedViewer;
+    } else {
+      viewerId = "v" + Math.random().toString(36).slice(2, 10) + Math.random().toString(36).slice(2, 6);
+      storage.set(VIEWER_KEY, viewerId).catch?.(() => {});
+    }
     if (storedData !== undefined) data = mergeDefaults(defaults, storedData);
     if (storedView !== undefined) view = { ...EMPTY_VIEW, ...storedView };
     hydrated = true;
@@ -126,6 +138,7 @@ export function createAppState(defaults, { debounceMs = 400, shared = false, pol
   return {
     ready,
     isHydrated: () => hydrated,
+    getViewerId: () => viewerId,
     getData: () => data,
     getView: () => view,
     update,

package/src/blocks.js

@@ -13,7 +13,7 @@
 import { createElement as h, useState, useEffect } from "react";
 import { ChatPanel } from "./chat.js";
 
-const FIELD_TYPES = ["text", "textarea", "number", "money", "percent", "check", "date", "select"];
+const FIELD_TYPES = ["text", "textarea", "number", "money", "percent", "check", "date", "select", "file"];
 
 export function formatValue(value, format) {
   if (value === null || value === undefined || value === "") return "—";
@@ -55,6 +55,29 @@ export function Field({ field, value, onChange, data }) {
   const id = `caf-f-${field.key}`;
   const numeric = field.type === "number" || field.type === "money" || field.type === "percent";
 
+  if (field.type === "file") {
+    // The File object itself lives at ctx.files[key] (in memory only — the
+    // 5MB/key storage limit makes real files unpersistable); `data` gets
+    // serializable metadata. After a reload the metadata survives but the
+    // file must be picked again.
+    return h(
+      "div",
+      { className: "caf-field" },
+      h("label", { htmlFor: id }, field.label || field.key),
+      h("input", {
+        id,
+        type: "file",
+        accept: field.accept,
+        onChange: (e) => onChange(e.target.files && e.target.files[0] ? e.target.files[0] : null),
+      }),
+      value && value.name
+        ? h("small", { className: "caf-hint" }, `${value.name} (${Math.round((value.size || 0) / 1024)} KB)${value.stale ? " — re-pick after reload" : ""}`)
+        : field.hint
+        ? h("small", { className: "caf-hint" }, field.hint)
+        : null
+    );
+  }
+
   if (field.type === "check") {
     return h(
       "label",
@@ -120,6 +143,18 @@ function toNumber(raw) {
   return Number.isFinite(n) ? n : raw;
 }
 
+// One write path for every field container: file fields park the live File
+// at ctx.files[key] and store metadata; everything else writes the value.
+export function writeField(ctx, key, field, v, setter) {
+  if (field.type === "file") {
+    ctx.files[key] = v || null;
+    const meta = v ? { name: v.name, size: v.size, type: v.type } : null;
+    ctx.update((d) => setter(d, meta));
+    return;
+  }
+  ctx.update((d) => setter(d, v));
+}
+
 export function FieldsBlock({ spec, ctx }) {
   const fields = spec.fields || [];
   return h(
@@ -132,7 +167,7 @@ export function FieldsBlock({ spec, ctx }) {
         field,
         data: ctx.data,
         value: ctx.data[field.key],
-        onChange: (v) => ctx.update((d) => { d[field.key] = v; }),
+        onChange: (v) => writeField(ctx, field.key, field, v, (d, val) => { d[field.key] = val; }),
       })
     )
   );
@@ -379,7 +414,7 @@ export function TimerBlock({ spec, ctx }) {
 // 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));
+  const visible = actions.filter((a) => !a.when || a.when(ctx.data, ctx.viewerId));
   return h(
     "div",
     { className: "caf-block caf-actions" },
@@ -399,7 +434,7 @@ export function ActionsBlock({ spec, ctx }) {
                 : a.kind === "primary"
                 ? "caf-btn caf-btn-primary"
                 : "caf-btn",
-            onClick: () => ctx.update((d) => a.run(d)),
+            onClick: () => ctx.update((d) => a.run(d, ctx.viewerId)),
           },
           a.label
         )
@@ -412,10 +447,13 @@ export function ActionsBlock({ spec, ctx }) {
 // custom block keeps persistence, theming, navigation and the error boundary.
 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";
   if (typeof rendered === "string") {
-    return h("div", { className: "caf-block", dangerouslySetInnerHTML: { __html: rendered } });
+    return h("div", { className: cls, dangerouslySetInnerHTML: { __html: rendered } });
   }
-  return h("div", { className: "caf-block" }, rendered);
+  return h("div", { className: cls }, rendered);
 }
 
 export const BLOCKS = {

package/src/records.js

@@ -152,7 +152,7 @@ function ListScreen({ spec, ctx }) {
                     "div",
                     { className: "caf-row-actions" },
                     spec.actions
-                      .filter((a) => !a.when || a.when(rec))
+                      .filter((a) => !a.when || a.when(rec, ctx.viewerId))
                       .map((a) =>
                         h(
                           "button",
@@ -163,7 +163,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);
+                                if (live) a.run(live, d, ctx.viewerId);
                               }),
                           },
                           a.label

package/src/steps.js

@@ -14,7 +14,7 @@
 //                   on the step the user was on, holding their answers.
 
 import { createElement as h } from "react";
-import { Field, validateField, formatValue } from "./blocks.js";
+import { Field, validateField, formatValue, writeField } from "./blocks.js";
 
 function stepErrors(step, data) {
   return (step.fields || []).some((f) => validateField(f, data[f.key]) !== null);
@@ -80,7 +80,7 @@ export function StepsLayout({ spec, ctx }) {
               field,
               data: ctx.data,
               value: ctx.data[field.key],
-              onChange: (v) => ctx.update((d) => { d[field.key] = v; }),
+              onChange: (v) => writeField(ctx, field.key, field, v, (d, val) => { d[field.key] = val; }),
             })
           ),
           h(