@ai-matrx/content-ir-react 0.15.2 → 0.16.1

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 0.16.1 — 2026-10-02
+
+- **A record's title column reads "Title" everywhere.** `itemChanges(item, current,
+  { titleColumn })` labels the noun's title column "Title" (a note's is stored in
+  `label`, and the confirm said "Label" while the form said "Title"); the card's update
+  row passes `nounTitleColumn`. Guard: `__tests__/directive-card-g3.test.tsx` ("a
+  record's title column…", 2 red on 0.16.0).
+
+Consumer action: a host's own confirm passes `{ titleColumn }` to `itemChanges`.
+
+## 0.16.0 — 2026-10-02
+
+The G3 review of the action cards (nightly clone). Guard: `__tests__/directive-card-g3.test.tsx`
+(7 cases, every one red on 0.15.2).
+
+- **An update says old → new.** New host seam `DirectiveHost.readRecord({noun, id})` →
+  the record's current fields (or null). `itemChanges(item, current)` now carries `before`
+  and `same`; the new `DirectiveChangeList` draws "Label old → new" (old struck through,
+  "empty" for a blank field, "(no change)" when it already holds the value). ONE component
+  for the card row and a host's confirm dialog. `useRecordValues(read, ref)` reads it.
+- **A Delete card's Apply looks destructive** (`data-apply-tone="destructive"`), not the
+  neutral grey of a create's.
+- **Run again shows the copies.** `DirectiveApplyState.copies` (1 + every Run again) and
+  `records` = the LATEST copy's. The tally says "2 copies" (create) / "Ran 2 times" and
+  links the newest copy; a yes to Run again counts one more.
+- **The card's state belongs to the block, not its slot.** A host that keys blocks by
+  position handed one card instance a different directive when a block was inserted
+  above it; an applied Update card flipped back to "Apply" until a reload. The Apply
+  control now resets and re-reads the ledger whenever the block it draws changes, and an
+  apply that finishes after its block moved away never lands on the new one.
+
+Consumer action: pass `readRecord` on the directive host for old → new; a host's own
+confirm dialog draws changes through `DirectiveChangeList`; an `applyState` answer passes
+`copies` when its ledger knows it.
+
 ## 0.15.2 — 2026-10-02
 
 - While "Run again" asks, the tally stays on screen (only its own button goes

package/dist/{directive-host-DJfF35FD.d.cts → directive-host-C4TcPpxX.d.cts}

@@ -32,8 +32,17 @@ interface DirectiveApplyState {
     state: "not_applied" | "in_flight" | "applied";
     /** The ledger row's sentence ("Created task."), never composed client-side. */
     message?: string | null;
-    /** The records the original apply wrote — the tally's doors. */
+    /**
+     * The records the LATEST apply wrote — the tally's doors. After "Run again"
+     * that is the newest copy, never the first.
+     */
     records?: DirectiveRecordRef[];
+    /**
+     * How many times the ledger holds this block as applied: 1 for the original,
+     * one more for every "Run again". Absent → 1. A create that ran twice made
+     * two records, and the card says so (reviewer, 2026-10-02).
+     */
+    copies?: number;
 }
 /** One record a directive names: the noun it is, and its id. */
 interface DirectiveRecordRef {
@@ -132,6 +141,14 @@ interface DirectiveHost {
      * is idempotent. Absent → the card starts at Apply, as before.
      */
     applyState?: (shell: DirectiveShell) => Promise<DirectiveApplyState>;
+    /**
+     * Read the CURRENT values of ONE existing record, so an update says what it
+     * replaces — "Status open → done", never just "→ done" (reviewer,
+     * 2026-10-02). Resolve `null` when the record cannot be read (no access, no
+     * such record, a noun the host cannot read); reject only for a real failure.
+     * Absent → an update row shows the new values alone, as before.
+     */
+    readRecord?: (ref: DirectiveRecordRef) => Promise<Record<string, unknown> | null>;
     /**
      * Draw ONE existing record by its live name, as a way to open it. Used on
      * update/delete rows (the record that will change), in the host's own ask
@@ -176,4 +193,4 @@ declare function DirectiveHostProvider({ host, children }: DirectiveHostProvider
  */
 declare function useDirectiveHost(): DirectiveHost;
 
-export { type DirectiveApplyResult as D, type DirectiveApplyState as a, type DirectiveAskRequest as b, type DirectiveCopyProps as c, type DirectiveHost as d, DirectiveHostProvider as e, type DirectiveHostProviderProps as f, type DirectiveOpenItemOptions as g, type DirectiveRecordProps as h, type DirectiveRecordRef as i, type DirectiveScope as j, DirectiveScopeProvider as k, type DirectiveShell as l, useDirectiveScope as m, useDirectiveHost as u };
+export { type DirectiveRecordRef as D, type DirectiveApplyResult as a, type DirectiveApplyState as b, type DirectiveAskRequest as c, type DirectiveCopyProps as d, type DirectiveHost as e, DirectiveHostProvider as f, type DirectiveHostProviderProps as g, type DirectiveOpenItemOptions as h, type DirectiveRecordProps as i, type DirectiveScope as j, DirectiveScopeProvider as k, type DirectiveShell as l, useDirectiveScope as m, useDirectiveHost as u };

package/dist/{directive-host-DJfF35FD.d.ts → directive-host-C4TcPpxX.d.ts}

@@ -32,8 +32,17 @@ interface DirectiveApplyState {
     state: "not_applied" | "in_flight" | "applied";
     /** The ledger row's sentence ("Created task."), never composed client-side. */
     message?: string | null;
-    /** The records the original apply wrote — the tally's doors. */
+    /**
+     * The records the LATEST apply wrote — the tally's doors. After "Run again"
+     * that is the newest copy, never the first.
+     */
     records?: DirectiveRecordRef[];
+    /**
+     * How many times the ledger holds this block as applied: 1 for the original,
+     * one more for every "Run again". Absent → 1. A create that ran twice made
+     * two records, and the card says so (reviewer, 2026-10-02).
+     */
+    copies?: number;
 }
 /** One record a directive names: the noun it is, and its id. */
 interface DirectiveRecordRef {
@@ -132,6 +141,14 @@ interface DirectiveHost {
      * is idempotent. Absent → the card starts at Apply, as before.
      */
     applyState?: (shell: DirectiveShell) => Promise<DirectiveApplyState>;
+    /**
+     * Read the CURRENT values of ONE existing record, so an update says what it
+     * replaces — "Status open → done", never just "→ done" (reviewer,
+     * 2026-10-02). Resolve `null` when the record cannot be read (no access, no
+     * such record, a noun the host cannot read); reject only for a real failure.
+     * Absent → an update row shows the new values alone, as before.
+     */
+    readRecord?: (ref: DirectiveRecordRef) => Promise<Record<string, unknown> | null>;
     /**
      * Draw ONE existing record by its live name, as a way to open it. Used on
      * update/delete rows (the record that will change), in the host's own ask
@@ -176,4 +193,4 @@ declare function DirectiveHostProvider({ host, children }: DirectiveHostProvider
  */
 declare function useDirectiveHost(): DirectiveHost;
 
-export { type DirectiveApplyResult as D, type DirectiveApplyState as a, type DirectiveAskRequest as b, type DirectiveCopyProps as c, type DirectiveHost as d, DirectiveHostProvider as e, type DirectiveHostProviderProps as f, type DirectiveOpenItemOptions as g, type DirectiveRecordProps as h, type DirectiveRecordRef as i, type DirectiveScope as j, DirectiveScopeProvider as k, type DirectiveShell as l, useDirectiveScope as m, useDirectiveHost as u };
+export { type DirectiveRecordRef as D, type DirectiveApplyResult as a, type DirectiveApplyState as b, type DirectiveAskRequest as c, type DirectiveCopyProps as d, type DirectiveHost as e, DirectiveHostProvider as f, type DirectiveHostProviderProps as g, type DirectiveOpenItemOptions as h, type DirectiveRecordProps as i, type DirectiveScope as j, DirectiveScopeProvider as k, type DirectiveShell as l, useDirectiveScope as m, useDirectiveHost as u };

package/dist/directives.cjs

@@ -23,6 +23,7 @@ var directives_exports = {};
 __export(directives_exports, {
   ApplyDirectiveButton: () => ApplyDirectiveButton,
   CHANGE_VALUE_MAX: () => CHANGE_VALUE_MAX,
+  DirectiveChangeList: () => DirectiveChangeList,
   DirectiveFallbackCard: () => DirectiveFallbackCard,
   DirectiveHostProvider: () => DirectiveHostProvider,
   DirectiveProvisionalCard: () => DirectiveProvisionalCard,
@@ -30,6 +31,7 @@ __export(directives_exports, {
   DirectiveScopeProvider: () => DirectiveScopeProvider,
   SideEffectDirectiveCard: () => SideEffectDirectiveCard,
   TARGETING_CLASSES: () => TARGETING_CLASSES,
+  describeChangeValue: () => describeChangeValue,
   fieldLabel: () => fieldLabel,
   getDirectiveRenderer: () => getDirectiveRenderer,
   itemChanges: () => itemChanges,
@@ -39,7 +41,8 @@ __export(directives_exports, {
   registerDirectiveRenderer: () => registerDirectiveRenderer,
   resetDirectiveRenderers: () => resetDirectiveRenderers,
   useDirectiveHost: () => useDirectiveHost,
-  useDirectiveScope: () => useDirectiveScope
+  useDirectiveScope: () => useDirectiveScope,
+  useRecordValues: () => useRecordValues
 });
 module.exports = __toCommonJS(directives_exports);
 
@@ -107,6 +110,9 @@ function recordFallbackName(nounLabel3, id) {
   const short = (0, import_uuid.isUuidShape)(id) ? id.slice(0, 8) : id.length > 12 ? `${id.slice(0, 12)}\u2026` : id;
   return `${nounLabel3} ${short}`;
 }
+function describeChangeValue(value) {
+  return describeValue(value);
+}
 function describeValue(value) {
   if (value === null || value === void 0) return { value: "cleared", full: "cleared", clears: true };
   if (typeof value === "string") {
@@ -135,11 +141,28 @@ function safeJson(value) {
     return String(value);
   }
 }
-function itemChanges(item) {
+function sameValue(a, b) {
+  if (a === b) return true;
+  if (a === null || a === void 0 || b === null || b === void 0) {
+    const emptyA = a === null || a === void 0 || a === "";
+    const emptyB = b === null || b === void 0 || b === "";
+    return emptyA && emptyB;
+  }
+  if (typeof a === "object" || typeof b === "object") return safeJson(a) === safeJson(b);
+  return false;
+}
+function itemChanges(item, current, options = {}) {
   const out = [];
+  const titleColumn = options.titleColumn ?? null;
   for (const [key, raw] of Object.entries(item)) {
     if (NOT_A_CHANGE.has(key)) continue;
-    out.push({ key, label: fieldLabel(key), ...describeValue(raw) });
+    const label = key === titleColumn ? "Title" : fieldLabel(key);
+    const change = { key, label, ...describeValue(raw) };
+    if (current && Object.prototype.hasOwnProperty.call(current, key)) {
+      change.before = describeValue(current[key]);
+      change.same = sameValue(current[key], raw);
+    }
+    out.push(change);
   }
   return out;
 }
@@ -252,12 +275,23 @@ function ApplyDirectiveButton({
   const conversationId = scope.conversationId || void 0;
   const items = directive.items;
   const readsLedger = !!host.applyState && !!host.confirm && directive.parsed.executes && items.length > 0;
-  const [state, setState] = (0, import_react2.useState)(
-    readsLedger ? { status: "checking" } : { status: "idle" }
-  );
+  const initial = readsLedger ? { status: "checking" } : { status: "idle" };
+  const [state, setState] = (0, import_react2.useState)(initial);
   const [elapsed, setElapsed] = (0, import_react2.useState)(0);
   const [askingAgain, setAskingAgain] = (0, import_react2.useState)(false);
   const startedAt = (0, import_react2.useRef)(null);
+  const identity = JSON.stringify([directive.slug, items, conversationId ?? null]);
+  const [stateFor, setStateFor] = (0, import_react2.useState)(identity);
+  if (stateFor !== identity) {
+    setStateFor(identity);
+    setState(initial);
+    setAskingAgain(false);
+    setElapsed(0);
+  }
+  const currentIdentity = (0, import_react2.useRef)(identity);
+  (0, import_react2.useEffect)(() => {
+    currentIdentity.current = identity;
+  }, [identity]);
   const nounText = (0, import_content_ir2.nounLabel)(directive.noun, host.nouns);
   const shellKey = readsLedger ? JSON.stringify([directive.slug, items, conversationId ?? null]) : "";
   const read = host.applyState;
@@ -280,7 +314,8 @@ function ApplyDirectiveButton({
               applied: shellItems.length,
               failed: 0,
               message: answer.message?.trim() ? answer.message.trim() : null,
-              records: answer.records ?? []
+              records: answer.records ?? [],
+              copies: Math.max(1, answer.copies ?? 1)
             } : prev
           );
         } else if (answer.state === "in_flight" && polls < FINISH_POLLS_MAX) {
@@ -320,6 +355,9 @@ function ApplyDirectiveButton({
   async function handleApply(again = false) {
     if (!confirm) return;
     const before = state;
+    const askedFor = identity;
+    const stillHere = () => currentIdentity.current === askedFor;
+    const priorCopies = state.status === "applied" ? state.copies : 0;
     if (host.ask) {
       if (again) setAskingAgain(true);
       else setState({ status: "asking" });
@@ -332,6 +370,7 @@ function ApplyDirectiveButton({
           ...again ? { again: true } : {}
         });
       } catch (error) {
+        if (!stillHere()) return;
         setAskingAgain(false);
         setState({
           status: "error",
@@ -339,6 +378,7 @@ function ApplyDirectiveButton({
         });
         return;
       }
+      if (!stillHere()) return;
       setAskingAgain(false);
       if (!ok) {
         setState(again ? before : { status: "idle" });
@@ -352,15 +392,19 @@ function ApplyDirectiveButton({
       if (conversationId) shell.conversationId = conversationId;
       if (again) shell.force = true;
       const result = await confirm(shell);
+      if (!stillHere()) return;
       setState({
         status: "applied",
         applied: result.applied,
         failed: result.failed,
         message: result.message?.trim() ? result.message.trim() : null,
-        records: result.records ?? []
+        records: result.records ?? [],
+        // "Run again" made one more; a first apply (or a replay of one) is one.
+        copies: again ? Math.max(1, priorCopies) + 1 : Math.max(1, priorCopies)
       });
       onApplied?.();
     } catch (error) {
+      if (!stillHere()) return;
       setState({
         status: "error",
         message: error instanceof Error && error.message ? error.message : "That couldn't be applied just now. Please try again."
@@ -385,6 +429,15 @@ function ApplyDirectiveButton({
               bad && !state.message ? ` \xB7 ${state.failed} failed` : ""
             ] })
           ] }),
+          state.copies > 1 ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+            "span",
+            {
+              className: "shrink-0 text-muted-foreground",
+              "data-apply-copies": state.copies,
+              title: records.length > 0 ? directive.directiveClass === "create" ? "Links to the latest copy." : "Links to the latest run." : void 0,
+              children: directive.directiveClass === "create" ? `${state.copies} copies` : `Ran ${state.copies} times`
+            }
+          ) : null,
           records.map((record) => /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("span", { className: "inline-flex min-w-0 items-center", children: host.renderRecord?.({
             ...record,
             fallback: recordFallbackName(label2, record.id),
@@ -435,6 +488,7 @@ function ApplyDirectiveButton({
       }
     );
   }
+  const destructive = directive.directiveClass === "delete";
   return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("span", { className: "inline-flex items-center gap-2", children: [
     /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(
       "button",
@@ -442,7 +496,8 @@ function ApplyDirectiveButton({
         type: "button",
         onClick: () => void handleApply(),
         disabled: state.status === "applying" || state.status === "asking" || items.length === 0,
-        className: "inline-flex items-center gap-1 rounded-md border border-border bg-background px-2 py-1 text-xs font-medium hover:bg-accent disabled:opacity-50",
+        "data-apply-tone": destructive ? "destructive" : "default",
+        className: `inline-flex items-center gap-1 rounded-md border px-2 py-1 text-xs font-medium disabled:opacity-50 ${destructive ? "border-destructive/50 bg-background text-destructive hover:bg-destructive/10" : "border-border bg-background hover:bg-accent"}`,
         children: [
           state.status === "applying" ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(LoaderIcon, { className: "h-3.5 w-3.5 animate-spin" }) : /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(PlayIcon, { className: "h-3.5 w-3.5" }),
           state.status === "applying" ? `Applying${itemCount ? ` ${itemCount} ${itemCount === 1 ? "item" : "items"}` : ""}\u2026${elapsed ? ` ${elapsed}s` : ""}` : label
@@ -457,8 +512,41 @@ function ApplyDirectiveButton({
 }
 
 // directives/SideEffectDirectiveCard.tsx
-var import_react3 = require("react");
+var import_react4 = require("react");
 var import_content_ir3 = require("@ai-matrx/content-ir");
+
+// directives/record-values.ts
+var import_react3 = require("react");
+function useRecordValues(read, ref) {
+  const key = ref && read ? `${ref.noun}:${ref.id}` : "";
+  const [result, setResult] = (0, import_react3.useState)({
+    key: "",
+    values: null,
+    status: "idle"
+  });
+  (0, import_react3.useEffect)(() => {
+    if (!key || !read) return;
+    const split = key.indexOf(":");
+    const target = { noun: key.slice(0, split), id: key.slice(split + 1) };
+    let live = true;
+    setResult({ key, values: null, status: "loading" });
+    read(target).then((values) => {
+      if (!live) return;
+      setResult({ key, values, status: values ? "ready" : "unavailable" });
+    }).catch(() => {
+      if (!live) return;
+      setResult({ key, values: null, status: "unavailable" });
+    });
+    return () => {
+      live = false;
+    };
+  }, [key, read]);
+  if (!key) return { values: null, status: "idle" };
+  if (result.key !== key) return { values: null, status: "loading" };
+  return { values: result.values, status: result.status };
+}
+
+// directives/SideEffectDirectiveCard.tsx
 var import_jsx_runtime4 = require("react/jsx-runtime");
 var ROWS_BEFORE_FOLD = 3;
 function ItemRow({
@@ -512,44 +600,73 @@ function ItemRow({
     host.renderCopy?.({ label: title, value: item, kind, size: "xs" })
   ] });
 }
-function TargetRow({
-  directive,
-  item,
-  recordId
+function DirectiveChangeList({
+  changes,
+  className
 }) {
-  const host = useDirectiveHost();
-  const fallback = recordFallbackName((0, import_content_ir3.nounLabel)(directive.noun, host.nouns), recordId);
-  const changes = directive.directiveClass === "update" ? itemChanges(item) : [];
-  const name = host.renderRecord ? host.renderRecord({ noun: directive.noun, id: recordId, fallback, context: "row" }) : /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("span", { className: "truncate font-medium text-foreground", children: fallback });
-  return /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)("div", { className: "py-1 text-xs", "data-directive-target": recordId, children: [
-    /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)("div", { className: "flex min-w-0 items-center gap-2", children: [
-      /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("span", { className: "flex min-w-0 flex-1 items-center gap-1 px-1", children: name }),
-      host.renderCopy?.({ label: fallback, value: item, size: "xs" })
-    ] }),
-    directive.directiveClass === "update" ? changes.length === 0 ? /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("p", { className: "px-1 text-[11px] text-muted-foreground", children: "Sets no fields \u2014 nothing would change." }) : /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("ul", { className: "mt-0.5 space-y-0.5 px-1", children: changes.map((change) => /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)(
+  if (changes.length === 0) {
+    return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("p", { className: `text-[11px] text-muted-foreground${className ? ` ${className}` : ""}`, children: "Sets no fields \u2014 nothing would change." });
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("ul", { className: `space-y-0.5${className ? ` ${className}` : ""}`, "data-directive-changes": "", children: changes.map((change) => {
+    const before = change.before && !change.same ? change.before : null;
+    const was = before ? before.clears ? "empty" : before.value : null;
+    return /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)(
       "li",
       {
         className: "flex min-w-0 items-baseline gap-1.5 text-[11px]",
-        title: `${change.label} \u2192 ${change.full}`,
+        title: before ? `${change.label}: ${before.clears ? "empty" : before.full} \u2192 ${change.full}` : `${change.label} \u2192 ${change.full}`,
+        "data-change-key": change.key,
         children: [
           /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("span", { className: "shrink-0 text-muted-foreground", children: change.label }),
+          was !== null ? /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
+            "span",
+            {
+              className: "min-w-0 max-w-[40%] shrink truncate text-muted-foreground line-through",
+              "data-change-before": "",
+              children: was
+            }
+          ) : null,
           /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("span", { "aria-hidden": true, className: "shrink-0 text-muted-foreground", children: "\u2192" }),
           /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
             "span",
             {
               className: `min-w-0 truncate ${change.clears ? "italic text-muted-foreground" : "text-foreground"}`,
+              "data-change-after": "",
               children: change.value
             }
-          )
+          ),
+          change.same ? /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("span", { className: "shrink-0 text-muted-foreground", children: "(no change)" }) : null
         ]
       },
       change.key
-    )) }) : null
+    );
+  }) });
+}
+function TargetRow({
+  directive,
+  item,
+  recordId
+}) {
+  const host = useDirectiveHost();
+  const fallback = recordFallbackName((0, import_content_ir3.nounLabel)(directive.noun, host.nouns), recordId);
+  const isUpdate = directive.directiveClass === "update";
+  const current = useRecordValues(
+    isUpdate ? host.readRecord : void 0,
+    isUpdate ? { noun: directive.noun, id: recordId } : null
+  );
+  const changes = isUpdate ? itemChanges(item, current.values, { titleColumn: (0, import_content_ir3.nounTitleColumn)(directive.noun, host.nouns) }) : [];
+  const name = host.renderRecord ? host.renderRecord({ noun: directive.noun, id: recordId, fallback, context: "row" }) : /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("span", { className: "truncate font-medium text-foreground", children: fallback });
+  return /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)("div", { className: "py-1 text-xs", "data-directive-target": recordId, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)("div", { className: "flex min-w-0 items-center gap-2", children: [
+      /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("span", { className: "flex min-w-0 flex-1 items-center gap-1 px-1", children: name }),
+      host.renderCopy?.({ label: fallback, value: item, size: "xs" })
+    ] }),
+    isUpdate ? /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(DirectiveChangeList, { changes, className: "mt-0.5 px-1" }) : null
   ] });
 }
 function SideEffectDirectiveCard({ directive }) {
   const host = useDirectiveHost();
-  const [expanded, setExpanded] = (0, import_react3.useState)(false);
+  const [expanded, setExpanded] = (0, import_react4.useState)(false);
   const items = directive.items;
   const total = items.length;
   const display = (0, import_content_ir3.directiveDisplay)(directive.directiveClass, directive.noun, host.nouns);