claude-artifact-framework 0.19.2 → 0.20.0

package/README.md

@@ -917,18 +917,25 @@ ONE number that is the screen's main result (a total, a final score), not
 for every stat; more than one hero per screen means no hero at all.
 
 **Quick-add pattern** — a lightweight alternative to `records` when you just
-need "type something, press a button, it lands in a list":
+need "type something, press a button, it lands in a list". Put the action
+IN the fields block — it renders as the card's footer, visually owned by
+the inputs it submits (a submit button in its own separate block is an
+orphan card):
 
 ```js
 blocks: [
-  { fields: [{ key: "nueva", label: "Persona", type: "text" }] },
-  { actions: [{ label: "Agregar", kind: "primary", run: (d) => {
+  { title: "Agregar persona",
+    fields: [{ key: "nueva", label: "Persona", type: "text" }],
+    actions: [{ label: "Agregar", kind: "primary", run: (d) => {
       if (d.nueva && d.nueva.trim()) { d.personas = [...(d.personas || []), d.nueva.trim()]; d.nueva = ""; }
-  }}]},
+    }}] },
   { text: (d) => (d.personas || []).join(", ") || "Sin personas todavía" },
 ]
 ```
 
+`{ fields, actions }` is the ONE legal block-type pair; any other
+combination still throws.
+
 ## `storage`
 
 Thin wrapper over `window.storage`, the persistence API Claude injects into a
@@ -990,6 +997,19 @@ Conflict handling is last-write-wins: if two viewers change the same key
 within one poll window, whichever write reaches storage last overwrites the
 other. There is no merge/CRDT logic.
 
+**Teammates' changes are visible by construction.** When another viewer's
+change arrives, rows they added or edited in any records list flash the
+accent once — nothing to declare. For custom blocks, `ctx.remote` is
+`{ keys, at }` for the last remote change (`keys` = the top-level data
+keys it touched, `at` = a `Date.now()` timestamp), or `null` before any:
+
+```js
+custom: (ctx) => {
+  const fresh = ctx.remote && Date.now() - ctx.remote.at < 4000 && ctx.remote.keys.includes("tarjetas");
+  return React.createElement("div", { className: fresh ? "mi-tablero pulso" : "mi-tablero" }, /* ... */);
+}
+```
+
 ## Design principles — composing a screen that reads
 
 The framework owns the CSS, but whether a screen has visual hierarchy is
@@ -1015,10 +1035,10 @@ these; every generic-looking one breaks at least two:
    repeating the app's own title (the header shows it), no hand-built
    totals when `summary`/`output` computes them, no "empty list" messages.
 6. **Group; don't multiply cards.** Related inputs belong in ONE `fields`
-   block with one title. Secondary content goes into `tabs` or a
-   collapsible. A first screen with more than ~5 cards has no hierarchy
-   left — and a block whose only content is one lonely button probably
-   belongs next to the fields it acts on.
+   block with one title, and their submit button belongs INSIDE it —
+   `{ fields: [...], actions: [...] }` renders the actions as the card's
+   footer. Secondary content goes into `tabs` or a collapsible. A first
+   screen with more than ~5 cards has no hierarchy left.
 7. **Say state with `when`, not with more blocks.** Hide what doesn't
    apply right now instead of stacking every possibility on screen.
 8. **Charts are support, not wallpaper.** At most two per screen; `wide:

package/dist/index.esm.js

@@ -182,13 +182,19 @@ function createAppState(defaults, { debounceMs = 400, shared = false, pollMs = 2
     });
   }, debounceMs);
   const persistView = debounce2(() => storage.set(VIEW_KEY, view), debounceMs);
+  let lastRemote = null;
   if (shared) {
     setInterval(async () => {
       if (!hydrated || writes > persistedWrites) return;
       try {
         const remote = await dataStore.get(DATA_KEY, void 0);
         if (remote !== void 0 && JSON.stringify(remote) !== JSON.stringify(data)) {
-          data = mergeDefaults(defaults, remote);
+          const merged = mergeDefaults(defaults, remote);
+          const keys = [.../* @__PURE__ */ new Set([...Object.keys(data || {}), ...Object.keys(merged || {})])].filter(
+            (k) => JSON.stringify(data[k]) !== JSON.stringify(merged[k])
+          );
+          data = merged;
+          lastRemote = { keys, at: Date.now() };
           notify();
         }
       } catch {
@@ -230,6 +236,7 @@ function createAppState(defaults, { debounceMs = 400, shared = false, pollMs = 2
     ready,
     isHydrated: () => hydrated,
     getViewerId: () => viewerId,
+    getRemote: () => lastRemote,
     getData: () => data,
     getView: () => view,
     update,
@@ -577,42 +584,46 @@ Continue with this information. If you have everything you need, answer in natur
     { className: "caf-chat-panel" },
     createElement(
       "div",
-      { className: "caf-block caf-chat-log" },
+      { className: "caf-block caf-chat-card" },
       // Every other block opens with its title label — a chat card that
       // starts straight at a bubble was the one heading-less block on screen.
       title ? createElement("h2", { className: "caf-block-title" }, title) : null,
-      c.greeting ? createElement("div", { className: "caf-msg caf-msg-assistant", dangerouslySetInnerHTML: { __html: renderMarkdown(c.greeting) } }) : null,
-      log.map((m, i) => createElement(Bubble, { key: i, m })),
-      live !== null ? createElement("div", { className: "caf-msg caf-msg-assistant caf-msg-live", dangerouslySetInnerHTML: { __html: renderMarkdown(live || "\u2026") } }) : null,
-      busy && live === null ? createElement("div", { className: "caf-msg-tools" }, "thinking\u2026") : null,
-      createElement("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.
-    createElement(
-      "div",
-      { className: "caf-chat-input" },
-      createElement("input", {
-        value: draft,
-        placeholder: c.placeholder || "Message\u2026",
-        disabled: busy,
-        enterKeyHint: "send",
-        onChange: (e) => setDraft(e.target.value),
-        onKeyDown: (e) => {
-          if (e.key === "Enter") {
-            e.preventDefault();
-            send();
-          }
-        },
-        "aria-label": "Message"
-      }),
       createElement(
-        "button",
-        { type: "button", className: "caf-btn caf-btn-primary", disabled: busy || !draft.trim(), onClick: send },
-        "Send"
+        "div",
+        { className: "caf-chat-log" },
+        c.greeting ? createElement("div", { className: "caf-msg caf-msg-assistant", dangerouslySetInnerHTML: { __html: renderMarkdown(c.greeting) } }) : null,
+        log.map((m, i) => createElement(Bubble, { key: i, m })),
+        live !== null ? createElement("div", { className: "caf-msg caf-msg-assistant caf-msg-live", dangerouslySetInnerHTML: { __html: renderMarkdown(live || "\u2026") } }) : null,
+        busy && live === null ? createElement("div", { className: "caf-msg-tools" }, "thinking\u2026") : null,
+        createElement("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.
+      createElement(
+        "div",
+        { className: "caf-chat-input" },
+        createElement("input", {
+          value: draft,
+          placeholder: c.placeholder || "Message\u2026",
+          disabled: busy,
+          enterKeyHint: "send",
+          onChange: (e) => setDraft(e.target.value),
+          onKeyDown: (e) => {
+            if (e.key === "Enter") {
+              e.preventDefault();
+              send();
+            }
+          },
+          "aria-label": "Message"
+        }),
+        createElement(
+          "button",
+          { type: "button", className: "caf-btn caf-btn-primary", disabled: busy || !draft.trim(), onClick: send },
+          "Send"
+        )
       )
     )
   );
@@ -704,7 +715,9 @@ function Field({ field, value, onChange, data }) {
     const options = typeof field.options === "function" ? field.options(data) || [] : field.options || [];
     control = createElement(
       "select",
-      common,
+      // Unchosen reads muted, like a text placeholder — "has a value" and
+      // "is empty" must differ at a glance (audited on the Select… state).
+      { ...common, className: value ? void 0 : "caf-select-empty" },
       createElement("option", { value: "" }, field.placeholder || "Select\u2026"),
       options.map((opt) => {
         const val = typeof opt === "string" ? opt : opt.value;
@@ -747,6 +760,7 @@ function writeField(ctx, key, field, v, setter) {
 }
 function FieldsBlock({ spec, ctx }) {
   const fields = spec.fields || [];
+  const footer = (spec.actions || []).filter((a) => !a.when || a.when(ctx.data, ctx.viewerId));
   return createElement(
     "div",
     { className: "caf-block caf-fields" },
@@ -761,7 +775,23 @@ function FieldsBlock({ spec, ctx }) {
           d[field.key] = val;
         })
       })
-    )
+    ),
+    footer.length ? createElement(
+      "div",
+      { className: "caf-actions-row caf-fields-footer" },
+      footer.map(
+        (a) => createElement(
+          "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, ctx.viewerId))
+          },
+          a.label
+        )
+      )
+    ) : null
   );
 }
 function StatGrid({ items, title }) {
@@ -1140,6 +1170,17 @@ function ListScreen({ spec, ctx }) {
     });
     ctx.go("record", rec.id);
   }
+  const prevRef = useRef(null);
+  const snapshot = {};
+  for (const r of ctx.data.records || []) if (r && r.id) snapshot[r.id] = JSON.stringify(r);
+  const remoteFresh = ctx.remote && Date.now() - ctx.remote.at < 4e3 && ctx.remote.keys.includes(ctx._recordsKey || "records");
+  const pulseIds = /* @__PURE__ */ new Set();
+  if (remoteFresh && prevRef.current) {
+    for (const id in snapshot) if (prevRef.current[id] !== snapshot[id]) pulseIds.add(id);
+  }
+  useEffect(() => {
+    prevRef.current = snapshot;
+  });
   return createElement(
     "div",
     { className: "caf-block caf-list" },
@@ -1169,7 +1210,7 @@ function ListScreen({ spec, ctx }) {
           "button",
           {
             type: "button",
-            className: spec.avatar ? "caf-row caf-row-avatar" : "caf-row",
+            className: (spec.avatar ? "caf-row caf-row-avatar" : "caf-row") + (pulseIds.has(rec.id) ? " caf-row-pulse" : ""),
             onClick: () => ctx.go("record", rec.id)
           },
           spec.avatar ? createElement(Avatar, { title: rowTitle(spec, rec), ctx }) : null,
@@ -1328,7 +1369,9 @@ function RecordsBlock({ spec, ctx }) {
     data: { ...ctx.data, records: arr },
     update: (fn) => ctx.update((d) => fn(aliasRecords(d, key))),
     go: (_screen, id) => ctx.setTab(stateKey, id),
-    back: () => ctx.setTab(stateKey, void 0)
+    back: () => ctx.setTab(stateKey, void 0),
+    _recordsKey: key
+    // so remote-change detection matches the REAL pool key
   };
   const record = openId ? arr.find((r) => r.id === openId) : null;
   return createElement(
@@ -1514,15 +1557,16 @@ function checkBlocks(blocks) {
         `claude-artifact-framework: blocks[${i}] has no recognised block type (found: ${keys.join(", ") || "nothing"}). Valid block types: ${[...BLOCK_NAMES, "tabs", "records"].join(", ")}.`
       );
     }
-    if (known.length > 1) {
+    const fieldsWithActions = known.length === 2 && known.includes("fields") && known.includes("actions");
+    if (known.length > 1 && !fieldsWithActions) {
       throw new Error(
         `claude-artifact-framework: blocks[${i}] declares more than one block type (${known.join(
           ", "
-        )}). Split them into separate entries of \`blocks\`.`
+        )}). Split them into separate entries of \`blocks\` \u2014 the one exception is { fields, actions }, which renders the actions as the fields card's footer.`
       );
     }
     checkFields(block.fields, `blocks[${i}]`);
-    if (known[0] === "actions") checkActions(block.actions, `blocks[${i}].actions`);
+    if (known.includes("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) {
@@ -2018,7 +2062,7 @@ function Block({ block, ctx }) {
   if (block.state !== void 0 && ctx.machine && ctx.data[ctx.machine.key || "fase"] !== block.state) return null;
   const bottomNav = ctx._navTabs !== void 0 && ctx._navTabs === block;
   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 name = block.fields && block.actions ? "fields" : Object.keys(block).find((k) => ALL_NAMES.includes(k));
   const Component2 = ALL_BLOCKS[name];
   const inner = createElement(
     boundary(ctx.React),
@@ -2083,11 +2127,12 @@ function RecordsWithBlocks({ spec, ctx }) {
 }
 function WorkspaceLayout({ spec, ctx }) {
   const render = (blocks) => (blocks || []).map((block, i) => createElement("section", { key: i, className: "caf-ws-slot" }, createElement(Block, { block, ctx })));
+  const mainStartsWithTabs = Array.isArray(spec.main) && spec.main[0] && Array.isArray(spec.main[0].tabs);
   return createElement(
     "div",
     { className: "caf-workspace" },
     createElement("div", { className: "caf-ws-main" }, render(spec.main)),
-    spec.sidebar && spec.sidebar.length ? createElement("div", { className: "caf-ws-side" }, render(spec.sidebar)) : null
+    spec.sidebar && spec.sidebar.length ? createElement("div", { className: mainStartsWithTabs ? "caf-ws-side caf-ws-side-tabs" : "caf-ws-side" }, render(spec.sidebar)) : null
   );
 }
 function docDefaults(dspec) {
@@ -2412,6 +2457,9 @@ function createApp(spec = {}) {
       toggleCollapsed: (key, val) => state.setView({ collapsed: { ...state.getView().collapsed, [key]: val } }),
       colors: (n) => seriesColors(spec.theme && spec.theme.seed, n),
       viewport: narrow ? "mobile" : "desktop",
+      // { keys, at } of the last change another viewer made (shared mode),
+      // null before any. The door to "notice teammates' changes".
+      remote: state.getRemote(),
       _navTabs: narrow && spec.mobile && spec.mobile.nav === "bottom" ? findNavTabs(spec) : null,
       _Block: Block,
       // for layouts in other modules (steps) that render blocks
@@ -2500,6 +2548,10 @@ var BASE_CSS = `
   flex-direction: column;
   gap: 0.8rem;
   height: 100%;
+  /* The one depth cue cards get \u2014 same as collapsible heads, so every
+     raised surface floats exactly the same amount (audited: buttons had
+     depth, cards didn't). */
+  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.06);
 }
 .caf-block-title { margin: 0; font-size: 0.78rem; font-weight: 650; text-transform: uppercase; letter-spacing: 0.06em; color: var(--caf-muted); }
 .caf-field { display: flex; flex-direction: column; gap: 0.3rem; }
@@ -2511,6 +2563,11 @@ var BASE_CSS = `
   border-radius: var(--caf-control-radius); border: 1px solid var(--caf-border);
   background: var(--caf-sunken); color: var(--caf-text); width: 100%;
 }
+/* "Has a value" and "is empty" must read differently at a glance \u2014
+   audited: a filled "0" and the neighboring placeholder shared one gray. */
+.caf-field input::placeholder, .caf-field textarea::placeholder,
+.caf-chat-input input::placeholder { color: var(--caf-muted); opacity: 0.75; }
+.caf-field select.caf-select-empty { color: var(--caf-muted); }
 .caf-field input:focus-visible, .caf-field select:focus-visible, .caf-field textarea:focus-visible,
 .caf-row:focus-visible { outline: 2px solid var(--caf-accent); outline-offset: 1px; }
 .caf-field input[aria-invalid="true"] { border-color: var(--caf-danger); }
@@ -2590,7 +2647,8 @@ var BASE_CSS = `
 .caf-steps-fill { transition: width 0.25s ease; }
 .caf-step-text { margin: 0; color: var(--caf-muted); font-size: 0.92rem; line-height: 1.55; }
 .caf-step-nav { display: flex; justify-content: space-between; gap: 0.6rem; margin-top: 0.4rem; }
-.caf-chat-log { min-height: 320px; max-height: 62vh; overflow-y: auto; gap: 0.55rem; }
+.caf-chat-card { min-width: 0; }
+.caf-chat-log { display: flex; flex-direction: column; min-height: 320px; max-height: 62vh; overflow-y: auto; gap: 0.55rem; }
 .caf-msg { max-width: 85%; padding: 0.55rem 0.75rem; border-radius: 12px; font-size: 0.92rem; line-height: 1.5; white-space: pre-wrap; word-break: break-word; }
 .caf-msg-user { align-self: flex-end; background: var(--caf-accent); color: var(--caf-accentText); border-bottom-right-radius: 4px; }
 .caf-msg-assistant { align-self: flex-start; background: var(--caf-sunken); border-bottom-left-radius: 4px; }
@@ -2598,9 +2656,12 @@ var BASE_CSS = `
 .caf-msg-tools { align-self: flex-start; font-size: 0.74rem; color: var(--caf-muted); padding: 0.15rem 0.55rem; border: 1px solid var(--caf-border); border-radius: 999px; }
 .caf-msg-error { align-self: stretch; max-width: none; display: flex; flex-direction: column; gap: 0.2rem; background: transparent; border: 1px solid var(--caf-danger); }
 .caf-msg-error strong { color: var(--caf-danger); font-size: 0.85rem; }
+/* The composer belongs to the conversation: a hairline continuation of the
+   same card, not a second bordered box floating 1rem below (audited: log
+   and input read as unrelated siblings). */
 .caf-chat-input {
-  display: flex; gap: 0.6rem; margin-top: 1rem; padding: 0.6rem;
-  background: var(--caf-surface); border: 1px solid var(--caf-border); border-radius: var(--caf-radius);
+  display: flex; gap: 0.6rem; margin-top: 0.2rem; padding: 0.7rem 0 0;
+  background: transparent; border: none; border-top: 1px solid var(--caf-border); border-radius: 0;
 }
 .caf-chat-input input { flex: 1; font: inherit; font-size: 0.95rem; padding: 0.55rem 0.7rem; border-radius: var(--caf-control-radius); border: 1px solid var(--caf-border); background: var(--caf-sunken); color: var(--caf-text); }
 .caf-chat-input input:focus-visible { outline: 2px solid var(--caf-accent); outline-offset: 1px; }
@@ -2614,6 +2675,14 @@ var BASE_CSS = `
 .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; }
+/* A teammate's change announces itself: rows another viewer just added or
+   edited flash the accent tint once (shared mode \u2014 round 20's dropped
+   "notice teammates' changes" requirement, framework-owned). */
+@keyframes caf-remote-pulse {
+  0% { background: var(--caf-accent-tint); box-shadow: 0 0 0 2px var(--caf-accent); }
+  100% { background: transparent; box-shadow: none; }
+}
+.caf-row-pulse { animation: caf-remote-pulse 2.4s ease-out; }
 .caf-row-wrap .caf-row { flex: 1; min-width: 0; }
 .caf-row-actions { display: flex; gap: 0.35rem; flex: none; padding-right: 0.3rem; }
 /* min-width keeps row actions' left edges aligned across rows even when
@@ -2626,6 +2695,9 @@ var BASE_CSS = `
 .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; }
+/* Footer actions inside a fields card: a hairline marks "this submits the
+   inputs above", the same attachment grammar as the chat composer. */
+.caf-fields-footer { border-top: 1px solid var(--caf-border); padding-top: 0.8rem; margin-top: 0.2rem; }
 .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; }
@@ -2634,6 +2706,12 @@ var BASE_CSS = `
 .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: var(--caf-block-gap); }
 .caf-ws-side { width: 340px; flex: none; display: flex; flex-direction: column; gap: var(--caf-block-gap); position: sticky; top: 1rem; }
+/* Tab bar height (2\xD70.45rem pad + ~1.02rem line + 1px border) plus the
+   .caf-tabs gap \u2014 so the sidebar's first card tops out level with main's
+   first card, not with the tab bar. Phones stack, no offset needed. */
+@media (min-width: 901px) {
+  .caf-ws-side-tabs { margin-top: calc(1.92rem + 1px + 0.8rem); }
+}
 .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); }
@@ -2681,6 +2759,14 @@ var BASE_CSS = `
 .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; }
+/* Where the page has a gutter, the logo lives in it: the title keeps the
+   exact left axis of tabs and cards below (audited twice \u2014 a logo pushed
+   every heading onto a third axis). On phones there is no gutter, so the
+   logo stays inline. */
+@media (min-width: 720px) {
+  .caf-header-brand { position: relative; }
+  .caf-header-brand .caf-logo { position: absolute; right: 100%; margin-right: 0.85rem; top: 0.1rem; }
+}
 .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); }
@@ -2700,7 +2786,9 @@ var BASE_CSS = `
 .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; }
+/* Left, like every other axis on the page \u2014 a centered footer was the one
+   element breaking the single left axis (audited). */
+.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; }
 .caf-layout-workspace .caf-footer { max-width: 1200px; }
 .caf-avatar {
   flex: none; width: 30px; height: 30px; border-radius: 50%;