claude-artifact-framework 0.19.2 → 0.20.1

package/llms.txt

@@ -84,7 +84,9 @@ https://cdn.jsdelivr.net/npm/claude-artifact-framework/dist/index.global.js
 3. Icons: all siblings or none, one style (emoji), never half a set.
 4. Mid-tone saturated seed that names the domain; no grays/near-blacks.
 5. Never duplicate what the framework renders (title, totals, empties).
-6. Group, don't multiply cards: related inputs in ONE fields block;
+6. Group, don't multiply cards: related inputs in ONE fields block, and
+   their submit button INSIDE it — { fields: [...], actions: [...] } is
+   the one legal block-type pair (actions render as the card's footer);
    secondary content into tabs/collapsible; >5 cards on one screen = no
    hierarchy.
 7. State via when:, not more blocks.
@@ -121,3 +123,7 @@ Chat with tools (workspace copilot): sidebar block
   ctx.update((d) => { /* mutate */ }); return { ok: true }; } } } } }
 — the artifact runtime proxies api.anthropic.com with no API key; default
 model claude-sonnet-4-6; conversation persists under data.chat.
+
+Shared mode: records rows another viewer just added/edited flash the accent
+automatically; ctx.remote = { keys, at } names the top-level keys the last
+remote change touched (null before any) for custom blocks.

package/package.json

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

@@ -114,15 +114,19 @@ function checkBlocks(blocks) {
         }). Valid block types: ${[...BLOCK_NAMES, "tabs", "records"].join(", ")}.`
       );
     }
-    if (known.length > 1) {
+    // ONE legal pair: { fields, actions } — the actions render as the
+    // fields card's footer (round 21: the standalone submit button was an
+    // orphan card). Every other combination still throws.
+    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\` — 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) {
@@ -668,7 +672,8 @@ function Block({ block, ctx }) {
   const bottomNav = ctx._navTabs !== undefined && ctx._navTabs === block;
   // `icon` is sugar: it prefixes the title everywhere titles render.
   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));
+  // { fields, actions } is one block: fields owns it, actions are its footer.
+  const name = block.fields && block.actions ? "fields" : Object.keys(block).find((k) => ALL_NAMES.includes(k));
   const Component = ALL_BLOCKS[name];
   const inner = h(
     boundary(ctx.React),
@@ -749,11 +754,17 @@ function RecordsWithBlocks({ spec, ctx }) {
 function WorkspaceLayout({ spec, ctx }) {
   const render = (blocks) =>
     (blocks || []).map((block, i) => h("section", { key: i, className: "caf-ws-slot" }, h(Block, { block, ctx })));
+  // When main opens with a tabs block, its bar consumes height the sidebar
+  // doesn't have — the sidebar's first card floated above main's (audited
+  // twice). The offset class compensates with the tabbar's own height.
+  const mainStartsWithTabs = Array.isArray(spec.main) && spec.main[0] && Array.isArray(spec.main[0].tabs);
   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
+    spec.sidebar && spec.sidebar.length
+      ? h("div", { className: mainStartsWithTabs ? "caf-ws-side caf-ws-side-tabs" : "caf-ws-side" }, render(spec.sidebar))
+      : null
   );
 }
 
@@ -1144,6 +1155,9 @@ export 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
       machine: spec.machine || null,
@@ -1255,6 +1269,10 @@ const BASE_CSS = `
   flex-direction: column;
   gap: 0.8rem;
   height: 100%;
+  /* The one depth cue cards get — 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; }
@@ -1266,6 +1284,11 @@ const 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 —
+   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); }
@@ -1345,7 +1368,8 @@ const 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; }
@@ -1353,9 +1377,12 @@ const 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; }
@@ -1369,6 +1396,14 @@ const 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 — 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
@@ -1381,6 +1416,9 @@ const 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; }
@@ -1389,6 +1427,12 @@ const 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×0.45rem pad + ~1.02rem line + 1px border) plus the
+   .caf-tabs gap — 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); }
@@ -1433,11 +1477,22 @@ const BASE_CSS = `
 .caf-doc-close:hover { color: var(--caf-danger); }
 .caf-doc-add { font-size: 1rem; font-weight: 650; }
 .caf-empty .caf-btn { margin-top: 0.6rem; }
-.caf-records-block { display: flex; flex-direction: column; gap: 1rem; min-width: 0; }
+/* Tight gap: the block title is a SECTION head for the cards below — it
+   must hug its group, not float equidistant (audited on the retro board). */
+.caf-records-block { display: flex; flex-direction: column; gap: 0.6rem; min-width: 0; }
+.caf-stat-neg, .caf-stat-big .caf-stat-value.caf-stat-neg { color: var(--caf-danger); }
 .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 — 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 { flex: none; width: 40px; height: 40px; border-radius: 9px; object-fit: contain; overflow: hidden; }
 .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); }
 .caf-logo-mono {
   display: flex; align-items: center; justify-content: center;
@@ -1455,7 +1510,9 @@ const 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 — 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%;

package/src/appState.js

@@ -83,13 +83,23 @@ export function createAppState(defaults, { debounceMs = 400, shared = false, pol
   }, debounceMs);
   const persistView = debounce(() => storage.set(VIEW_KEY, view), debounceMs);
 
+  // The last change that arrived from ANOTHER viewer: which top-level keys
+  // it touched, and when. Ephemeral, never persisted. This is the minimal
+  // vocabulary for "notice teammates' changes" — the requirement a blind
+  // agent silently dropped because nothing in the API could express it.
+  let lastRemote = null;
   if (shared) {
     setInterval(async () => {
       if (!hydrated || writes > persistedWrites) return; // local edits in flight win
       try {
         const remote = await dataStore.get(DATA_KEY, undefined);
         if (remote !== undefined && JSON.stringify(remote) !== JSON.stringify(data)) {
-          data = mergeDefaults(defaults, remote);
+          const merged = mergeDefaults(defaults, remote);
+          const keys = [...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 {
@@ -139,6 +149,7 @@ export function createAppState(defaults, { debounceMs = 400, shared = false, pol
     ready,
     isHydrated: () => hydrated,
     getViewerId: () => viewerId,
+    getRemote: () => lastRemote,
     getData: () => data,
     getView: () => view,
     update,

package/src/blocks.js

@@ -63,7 +63,13 @@ export function validateField(field, value) {
 }
 
 export function Field({ field, value, onChange, data }) {
-  const error = validateField(field, value);
+  // A pristine empty field must not shout "Required" before the user ever
+  // touched it (audited on first load of a quick-add form). Range/format
+  // errors imply a non-empty value, so only the empty-required case waits.
+  const [touched, setTouched] = useState(false);
+  const rawError = validateField(field, value);
+  const pristineEmpty = !touched && (value === "" || value === null || value === undefined);
+  const error = pristineEmpty ? null : rawError;
   const id = `caf-f-${field.key}`;
   const numeric = field.type === "number" || field.type === "money" || field.type === "percent";
 
@@ -108,6 +114,7 @@ export function Field({ field, value, onChange, data }) {
     id,
     value: value === null || value === undefined ? "" : value,
     "aria-invalid": error ? "true" : undefined,
+    onBlur: () => setTouched(true),
     onChange: (e) => onChange(numeric ? toNumber(e.target.value) : e.target.value),
   };
 
@@ -120,7 +127,9 @@ export function Field({ field, value, onChange, data }) {
     const options = typeof field.options === "function" ? field.options(data) || [] : field.options || [];
     control = h(
       "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 ? undefined : "caf-select-empty" },
       h("option", { value: "" }, field.placeholder || "Select…"),
       options.map((opt) => {
         const val = typeof opt === "string" ? opt : opt.value;
@@ -169,6 +178,11 @@ export function writeField(ctx, key, field, v, setter) {
 
 export function FieldsBlock({ spec, ctx }) {
   const fields = spec.fields || [];
+  // A fields block may carry its own `actions`: they render as the card's
+  // footer, visually owned by the inputs they submit. Measured miss (round
+  // 21): the quick-add CTA as a separate block was an orphan card,
+  // equidistant from its form and from the next section.
+  const footer = (spec.actions || []).filter((a) => !a.when || a.when(ctx.data, ctx.viewerId));
   return h(
     "div",
     { className: "caf-block caf-fields" },
@@ -181,7 +195,30 @@ export function FieldsBlock({ spec, ctx }) {
         value: ctx.data[field.key],
         onChange: (v) => writeField(ctx, field.key, field, v, (d, val) => { d[field.key] = val; }),
       })
-    )
+    ),
+    footer.length
+      ? h(
+          "div",
+          { className: "caf-actions-row caf-fields-footer" },
+          footer.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, ctx.viewerId)),
+              },
+              a.label
+            )
+          )
+        )
+      : null
   );
 }
 
@@ -199,15 +236,19 @@ export function StatGrid({ items, title }) {
     h(
       "div",
       { className: "caf-output-grid" },
-      items.map((item, i) =>
-        h(
+      items.map((item, i) => {
+        // A negative money/number stat reads as a loss everywhere else on
+        // screen (list rows already color by sign) — the hero must agree,
+        // not paint a deficit in cheerful brand accent (audited).
+        const neg = (item.format === "money" || item.format === "number") && Number(item.value) < 0;
+        return h(
           "div",
           { key: item.label || i, className: item.big ? "caf-stat caf-stat-big" : "caf-stat" },
           h("span", { className: "caf-stat-label" }, item.label),
-          h("span", { className: "caf-stat-value" }, formatValue(item.value, item.format)),
+          h("span", { className: neg ? "caf-stat-value caf-stat-neg" : "caf-stat-value" }, formatValue(item.value, item.format)),
           item.hint ? h("small", { className: "caf-hint" }, item.hint) : null
-        )
-      )
+        );
+      })
     )
   );
 }

package/src/chat.js

@@ -244,33 +244,40 @@ export function ChatPanel({ cfg, ctx, title }) {
     }
   }
 
+  // ONE card holds the whole conversation: title, scrolling log, composer.
+  // The composer as a separate box below the card read as an unrelated
+  // sibling (audited) — inside the card with a hairline it reads as the
+  // conversation's own edge.
   return h(
     "div",
     { className: "caf-chat-panel" },
     h(
       "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 ? h("h2", { className: "caf-block-title" }, title) : 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", 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(
-      "div",
-      { className: "caf-chat-input" },
+      h(
+        "div",
+        { className: "caf-chat-log" },
+        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", 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(
+        "div",
+        { className: "caf-chat-input" },
       h("input", {
         value: draft,
         placeholder: c.placeholder || "Message…",
@@ -285,10 +292,11 @@ export function ChatPanel({ cfg, ctx, title }) {
         },
         "aria-label": "Message",
       }),
-      h(
-        "button",
-        { type: "button", className: "caf-btn caf-btn-primary", disabled: busy || !draft.trim(), onClick: send },
-        "Send"
+        h(
+          "button",
+          { type: "button", className: "caf-btn caf-btn-primary", disabled: busy || !draft.trim(), onClick: send },
+          "Send"
+        )
       )
     )
   );

package/src/records.js

@@ -18,7 +18,7 @@
 // in data — restoring it on reload is correct, and deleting the open record
 // simply falls back to the list.
 
-import { createElement as h, useState, useEffect } from "react";
+import { createElement as h, useState, useEffect, useRef } from "react";
 import { Field, formatValue, StatGrid } from "./blocks.js";
 
 // Computed fields are derived at render time and never stored, so they can't
@@ -141,6 +141,22 @@ function ListScreen({ spec, ctx }) {
     ctx.go("record", rec.id);
   }
 
+  // Rows another viewer just added or changed pulse once — the framework-
+  // owned answer to "notice teammates' changes" (round 20's silently
+  // dropped requirement), free wherever the data is records-shaped.
+  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 < 4000 && ctx.remote.keys.includes(ctx._recordsKey || "records");
+  const pulseIds = 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 h(
     "div",
     { className: "caf-block caf-list" },
@@ -176,7 +192,9 @@ 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 ? h(Avatar, { title: rowTitle(spec, rec), ctx }) : null,
@@ -368,6 +386,7 @@ export function RecordsBlock({ spec, ctx }) {
     update: (fn) => ctx.update((d) => fn(aliasRecords(d, key))),
     go: (_screen, id) => ctx.setTab(stateKey, id),
     back: () => ctx.setTab(stateKey, undefined),
+    _recordsKey: key, // so remote-change detection matches the REAL pool key
   };
 
   // A deleted or stale open record falls back to the list, never a blank pane.