claude-artifact-framework 0.7.3 → 0.8.0

package/README.md

@@ -20,7 +20,7 @@ mirrors npm packages automatically.
 ### As a global script (`<script>` tag)
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/claude-artifact-framework@0.7.3/dist/index.global.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/claude-artifact-framework@0.8.0/dist/index.global.js"></script>
 <script>
   ArtifactKit.useReact(React); // hand over the page's React once
   const App = ArtifactKit.createApp({ title: "Mi app", blocks: [ /* ... */ ] });
@@ -38,11 +38,11 @@ mirrors npm packages automatically.
     createStore,
     createPersistedStore,
     createSharedStore,
-  } from "https://cdn.jsdelivr.net/npm/claude-artifact-framework@0.7.3/dist/index.esm.js";
+  } from "https://cdn.jsdelivr.net/npm/claude-artifact-framework@0.8.0/dist/index.esm.js";
 </script>
 ```
 
-Pin a version (`@0.7.3`) for reproducible artifacts, or drop the version
+Pin a version (`@0.8.0`) for reproducible artifacts, or drop the version
 (`claude-artifact-framework/dist/...`) to always get the latest release.
 
 ### Inside a React artifact
@@ -388,6 +388,54 @@ The active tab and each accordion's open/closed state are framework-owned
 view state — they survive reload, per viewer. Tabs cannot nest inside tabs;
 `when` must be a function; both throw otherwise.
 
+### External libraries, uploaded files, full-bleed custom, viewer identity
+
+Four primitives for the custom-heavy end of the spectrum (document viewers,
+canvases, analyzers):
+
+```js
+ArtifactKit.createApp({
+  title: "Visor de PDF",
+  layout: "workspace",
+  libs: ["https://cdn.jsdelivr.net/npm/pdfjs-dist@3.11.174/build/pdf.min.js"],
+  main: [
+    { fields: [{ key: "doc", label: "Documento", type: "file", accept: "application/pdf" }] },
+    { custom: (ctx) => renderPdf(ctx.files.doc), fill: true },
+  ],
+  sidebar: [ { chat: { system: "Sos un asistente de lectura." } } ],
+})
+```
+
+- **`libs: ["https://..."]`** loads external scripts before the app mounts,
+  deduped by URL, with a "Loading libraries…" state and a named error block
+  if one fails. No hand-written `loadScript` in custom code.
+- **`type: "file"`** fields hand the live `File` to your code at
+  `ctx.files[key]` (in memory only — the 5MB/key storage limit makes real
+  files unpersistable); `data[key]` gets serializable metadata
+  (`{ name, size, type }`) that survives reload, after which the file must
+  be picked again. `accept` filters the picker. File fields live in the flat
+  data pool (panel blocks or steps) — declaring one inside records/items
+  throws.
+- **`fill: true`** on a `custom` block drops the card chrome so the block
+  owns a large scrollable surface — the workspace main-area case.
+- **`ctx.viewerId`** is a stable anonymous id per viewer, always in the
+  personal scope. In a `shared` app it expresses "one vote per person" and
+  "added by" with no account system. It is available on the `ctx` that
+  `custom` blocks and chat tools receive; row/block actions receive it as a
+  third argument:
+
+```js
+records: {
+  fields: [{ key: "nombre", type: "text" }],
+  actions: [{
+    label: "Votar",
+    when: (r, viewerId) => !(r.votantes || []).includes(viewerId),
+    run: (r, d, viewerId) => { r.votantes = [...(r.votantes || []), viewerId]; },
+  }],
+  subtitle: (r) => (r.votantes || []).length + " votos",
+}
+```
+
 ## API reference
 
 Everything an app can declare, in one place.

package/dist/index.esm.js

@@ -133,6 +133,7 @@ var Component = React && React.Component || class ReactMissing {
 
 // src/appState.js
 var DATA_KEY = "caf:data";
+var VIEWER_KEY = "caf:viewer";
 var VIEW_KEY = "caf:view";
 var EMPTY_VIEW = { screen: null, arg: null, stack: [], step: 0, selected: null, tabs: {}, collapsed: {} };
 function isPlainObject(v) {
@@ -160,6 +161,7 @@ function createAppState(defaults, { debounceMs = 400, shared = false, pollMs = 2
   let data = structuredCloneish(defaults);
   let view = { ...EMPTY_VIEW };
   let hydrated = false;
+  let viewerId = null;
   let writes = 0;
   let persistedWrites = 0;
   const listeners = /* @__PURE__ */ new Set();
@@ -194,10 +196,18 @@ function createAppState(defaults, { debounceMs = 400, shared = false, pollMs = 2
     }, pollMs);
   }
   const ready = (async () => {
-    const [storedData, storedView] = await Promise.all([
+    const [storedData, storedView, storedViewer] = await Promise.all([
       dataStore.get(DATA_KEY, void 0),
-      storage.get(VIEW_KEY, void 0)
+      storage.get(VIEW_KEY, void 0),
+      storage.get(VIEWER_KEY, void 0)
     ]);
+    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 !== void 0) data = mergeDefaults(defaults, storedData);
     if (storedView !== void 0) view = { ...EMPTY_VIEW, ...storedView };
     hydrated = true;
@@ -219,6 +229,7 @@ function createAppState(defaults, { debounceMs = 400, shared = false, pollMs = 2
   return {
     ready,
     isHydrated: () => hydrated,
+    getViewerId: () => viewerId,
     getData: () => data,
     getView: () => view,
     update,
@@ -608,7 +619,7 @@ function ChatLayout({ spec, ctx }) {
 }
 
 // src/blocks.js
-var FIELD_TYPES = ["text", "textarea", "number", "money", "percent", "check", "date", "select"];
+var FIELD_TYPES = ["text", "textarea", "number", "money", "percent", "check", "date", "select", "file"];
 function formatValue(value, format) {
   if (value === null || value === void 0 || value === "") return "\u2014";
   const n = Number(value);
@@ -642,6 +653,20 @@ 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";
+  if (field.type === "file") {
+    return createElement(
+      "div",
+      { className: "caf-field" },
+      createElement("label", { htmlFor: id }, field.label || field.key),
+      createElement("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 ? createElement("small", { className: "caf-hint" }, `${value.name} (${Math.round((value.size || 0) / 1024)} KB)${value.stale ? " \u2014 re-pick after reload" : ""}`) : field.hint ? createElement("small", { className: "caf-hint" }, field.hint) : null
+    );
+  }
   if (field.type === "check") {
     return createElement(
       "label",
@@ -700,6 +725,15 @@ function toNumber(raw) {
   const n = Number(raw);
   return Number.isFinite(n) ? n : raw;
 }
+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));
+}
 function FieldsBlock({ spec, ctx }) {
   const fields = spec.fields || [];
   return createElement(
@@ -712,8 +746,8 @@ 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;
         })
       })
     )
@@ -935,7 +969,7 @@ function TimerBlock({ spec, ctx }) {
 }
 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 createElement(
     "div",
     { className: "caf-block caf-actions" },
@@ -950,7 +984,7 @@ function ActionsBlock({ spec, ctx }) {
             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))
+            onClick: () => ctx.update((d) => a.run(d, ctx.viewerId))
           },
           a.label
         )
@@ -960,10 +994,11 @@ function ActionsBlock({ spec, ctx }) {
 }
 function CustomBlock({ spec, ctx }) {
   const rendered = spec.custom(ctx);
+  const cls = spec.fill ? "caf-block caf-block-fill" : "caf-block";
   if (typeof rendered === "string") {
-    return createElement("div", { className: "caf-block", dangerouslySetInnerHTML: { __html: rendered } });
+    return createElement("div", { className: cls, dangerouslySetInnerHTML: { __html: rendered } });
   }
-  return createElement("div", { className: "caf-block" }, rendered);
+  return createElement("div", { className: cls }, rendered);
 }
 var BLOCKS = {
   fields: FieldsBlock,
@@ -1089,7 +1124,7 @@ function ListScreen({ spec, ctx }) {
         spec.actions ? createElement(
           "div",
           { className: "caf-row-actions" },
-          spec.actions.filter((a) => !a.when || a.when(rec)).map(
+          spec.actions.filter((a) => !a.when || a.when(rec, ctx.viewerId)).map(
             (a) => createElement(
               "button",
               {
@@ -1098,7 +1133,7 @@ function ListScreen({ spec, ctx }) {
                 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);
+                  if (live) a.run(live, d, ctx.viewerId);
                 })
               },
               a.label
@@ -1291,8 +1326,8 @@ 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;
           })
         })
       ),
@@ -1317,8 +1352,8 @@ function StepsLayout({ spec, ctx }) {
 
 // src/app.js
 var LAYOUTS = ["panel", "records", "steps", "chat", "workspace"];
-var RESERVED = ["title", "empty", "wide", "onSelect", "subtitle", "when", "collapsible"];
-var TOP_KEYS = ["title", "subtitle", "theme", "layout", "blocks", "records", "steps", "chat", "data", "shared", "main", "sidebar"];
+var RESERVED = ["title", "empty", "wide", "onSelect", "subtitle", "when", "collapsible", "fill"];
+var TOP_KEYS = ["title", "subtitle", "theme", "layout", "blocks", "records", "steps", "chat", "data", "shared", "main", "sidebar", "libs"];
 function checkFields(fields, where) {
   for (const f of fields || []) {
     if (!f || !f.key) throw new Error(`claude-artifact-framework: every field in ${where} needs a \`key\`.`);
@@ -1414,6 +1449,9 @@ function checkBlocks(blocks) {
     if (block.when !== void 0 && 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 !== void 0 && known[0] !== "custom") {
+      throw new Error(`claude-artifact-framework: \`fill\` is only valid on custom blocks \u2014 blocks[${i}] is "${known[0]}".`);
+    }
   });
 }
 function validate(spec) {
@@ -1423,6 +1461,11 @@ function validate(spec) {
       `claude-artifact-framework: unknown top-level keys (${unknownTop.join(", ")}). Valid keys: ${TOP_KEYS.join(", ")}.`
     );
   }
+  if (spec.libs !== void 0) {
+    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(
@@ -1501,6 +1544,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) \u2014 they are not supported inside records or items."
+      );
+    }
     const seen = /* @__PURE__ */ new Set();
     for (const f of r.fields) {
       if (f.key === "id") throw new Error('claude-artifact-framework: "id" is reserved on records \u2014 the framework assigns it.');
@@ -1704,10 +1752,30 @@ function WorkspaceLayout({ spec, ctx }) {
   );
 }
 var LAYOUT_COMPONENTS = { panel: Panel, records: RecordsWithBlocks, steps: StepsLayout, chat: ChatLayout, workspace: WorkspaceLayout };
+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);
+  });
+}
 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;
+  const files = {};
   return function App() {
     if (!hasReact()) {
       throw new Error(
@@ -1715,6 +1783,18 @@ 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));
       if (state.isHydrated()) force((n) => n + 1);
@@ -1728,6 +1808,8 @@ 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)
@@ -1743,7 +1825,12 @@ function createApp(spec = {}) {
         spec.title ? createElement("h1", null, spec.title) : null,
         spec.subtitle ? createElement("p", null, spec.subtitle) : null
       ),
-      state.isHydrated() ? createElement(Layout, { spec, ctx }) : createElement("div", { className: "caf-block caf-loading" }, "Loading\u2026")
+      libsState === "error" ? createElement(
+        "div",
+        { className: "caf-block caf-block-error" },
+        createElement("strong", null, "A library failed to load"),
+        createElement("code", null, libsError)
+      ) : !state.isHydrated() || libsState === "loading" ? createElement("div", { className: "caf-block caf-loading" }, libsState === "loading" ? "Loading libraries\u2026" : "Loading\u2026") : createElement(Layout, { spec, ctx })
     );
   };
 }
@@ -1916,6 +2003,7 @@ var 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); }