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

package/dist/directives.d.ts

@@ -1,4 +1,5 @@
-export { D as DirectiveApplyResult, a as DirectiveApplyState, b as DirectiveAskRequest, c as DirectiveCopyProps, d as DirectiveHost, e as DirectiveHostProvider, f as DirectiveHostProviderProps, g as DirectiveOpenItemOptions, h as DirectiveRecordProps, i as DirectiveRecordRef, j as DirectiveScope, k as DirectiveScopeProvider, l as DirectiveShell, u as useDirectiveHost, m as useDirectiveScope } from './directive-host-DJfF35FD.js';
+import { D as DirectiveRecordRef } from './directive-host-C4TcPpxX.js';
+export { a as DirectiveApplyResult, b as DirectiveApplyState, c as DirectiveAskRequest, d as DirectiveCopyProps, e as DirectiveHost, f as DirectiveHostProvider, g as DirectiveHostProviderProps, h as DirectiveOpenItemOptions, i as DirectiveRecordProps, j as DirectiveScope, k as DirectiveScopeProvider, l as DirectiveShell, u as useDirectiveHost, m as useDirectiveScope } from './directive-host-C4TcPpxX.js';
 import * as react from 'react';
 import { ComponentType } from 'react';
 import { DecodedDirective, DirectiveClass } from '@ai-matrx/content-ir';
@@ -48,9 +49,84 @@ interface ApplyDirectiveButtonProps {
 }
 declare function ApplyDirectiveButton({ directive, label, itemCount, onApplied, }: ApplyDirectiveButtonProps): react.JSX.Element | null;
 
+/**
+ * WHAT A DIRECTIVE ITEM WILL DO TO AN EXISTING RECORD — for the card, the
+ * confirm dialog, and anything else that must say it before the click.
+ *
+ * WHY (reviewer, 2026-09-30): an Update card and a Delete card showed each item
+ * as "Item" — they never named the record they would change, and an Update card
+ * never said what it would change. The item-summary helpers name a thing to be
+ * CREATED from its own fields; an update or delete item carries the TARGET's id
+ * and, for an update, the NEW values — so its "title" field is the new title,
+ * not the name of the record being changed. Naming the target is the host's
+ * live lookup (`DirectiveHost.renderRecord`); what changes is right here.
+ *
+ * Law: common-docs/policies/destructive-and-expensive-actions.md — the sentence
+ * names what changes.
+ */
+/** Classes whose items point at an EXISTING record by `id`. */
+declare const TARGETING_CLASSES: ReadonlySet<string>;
+/** How long a changed value may read before it is shortened (full value on hover). */
+declare const CHANGE_VALUE_MAX = 60;
+/** The id of the existing record an update/delete item targets, or null. */
+declare function itemRecordId(item: Record<string, unknown>): string | null;
+/** "due_date" → "Due date". Underscores read as developer output. */
+declare function fieldLabel(key: string): string;
+/** A short, honest name for a record we could not look up: "Task 1a2b3c4d". */
+declare function recordFallbackName(nounLabel: string, id: string): string;
+/** One value as a row reads it: shortened, the whole of it, and whether it is empty. */
+interface ChangeValue {
+    value: string;
+    full: string;
+    clears: boolean;
+}
+interface ItemChange extends ChangeValue {
+    key: string;
+    /** "Due date". */
+    label: string;
+    /**
+     * What the field holds NOW, when the host could read the record — so an
+     * update reads "old → new", never just the new value (reviewer, 2026-10-02).
+     * Absent when the current record is unknown.
+     */
+    before?: ChangeValue;
+    /** True when the record already holds exactly this value — nothing changes. */
+    same?: boolean;
+}
+/** One value, described for a change row (`value` shortened, `full` whole). */
+declare function describeChangeValue(value: unknown): ChangeValue;
+/**
+ * Every field an UPDATE item sets, in the order the item carries them — ALL of
+ * them, never a sample: a person approving an overwrite sees the whole of it.
+ *
+ * Pass `current` — the record as it is now (`DirectiveHost.readRecord`) — and
+ * each change also carries what it REPLACES (`before`) and whether it changes
+ * anything at all (`same`). A field the record does not carry gets no `before`.
+ */
+interface ItemChangesOptions {
+    /**
+     * The noun's title column (catalog `title_column` — `nounTitleColumn`). It is
+     * labelled "Title" whatever it is called: a note's title is stored in
+     * `label`, and the confirm said "Label" while the form said "Title"
+     * (reviewer, 2026-10-02). The same rule the directive builder's form uses.
+     */
+    titleColumn?: string | null;
+}
+declare function itemChanges(item: Record<string, unknown>, current?: Record<string, unknown> | null, options?: ItemChangesOptions): ItemChange[];
+
 interface SideEffectDirectiveCardProps {
     directive: DecodedDirective;
 }
+/**
+ * THE CHANGE LIST — every field an update sets, as "Label  old → new" when the
+ * record's current value is known, "Label → new" when it is not. ONE component
+ * for the card row and the host's confirm dialog, so the two can never read
+ * differently (reviewer, 2026-10-02: the confirm showed only the new value).
+ */
+declare function DirectiveChangeList({ changes, className, }: {
+    changes: ItemChange[];
+    className?: string;
+}): react.JSX.Element;
 declare function SideEffectDirectiveCard({ directive }: SideEffectDirectiveCardProps): react.JSX.Element;
 
 interface DirectiveFallbackCardProps {
@@ -94,45 +170,13 @@ interface DirectiveRenderProps {
 }
 declare function DirectiveRender({ conversationId, ...props }: DirectiveRenderProps): react.JSX.Element;
 
-/**
- * WHAT A DIRECTIVE ITEM WILL DO TO AN EXISTING RECORD — for the card, the
- * confirm dialog, and anything else that must say it before the click.
- *
- * WHY (reviewer, 2026-09-30): an Update card and a Delete card showed each item
- * as "Item" — they never named the record they would change, and an Update card
- * never said what it would change. The item-summary helpers name a thing to be
- * CREATED from its own fields; an update or delete item carries the TARGET's id
- * and, for an update, the NEW values — so its "title" field is the new title,
- * not the name of the record being changed. Naming the target is the host's
- * live lookup (`DirectiveHost.renderRecord`); what changes is right here.
- *
- * Law: common-docs/policies/destructive-and-expensive-actions.md — the sentence
- * names what changes.
- */
-/** Classes whose items point at an EXISTING record by `id`. */
-declare const TARGETING_CLASSES: ReadonlySet<string>;
-/** How long a changed value may read before it is shortened (full value on hover). */
-declare const CHANGE_VALUE_MAX = 60;
-/** The id of the existing record an update/delete item targets, or null. */
-declare function itemRecordId(item: Record<string, unknown>): string | null;
-/** "due_date" → "Due date". Underscores read as developer output. */
-declare function fieldLabel(key: string): string;
-/** A short, honest name for a record we could not look up: "Task 1a2b3c4d". */
-declare function recordFallbackName(nounLabel: string, id: string): string;
-interface ItemChange {
-    key: string;
-    /** "Due date". */
-    label: string;
-    /** What it becomes, shortened for a row; `full` carries the whole value. */
-    value: string;
-    full: string;
-    /** True when the new value empties the field. */
-    clears: boolean;
+type RecordValuesStatus = "idle" | "loading" | "ready" | "unavailable";
+interface RecordValues {
+    /** The record's fields now, or null until (or unless) they are read. */
+    values: Record<string, unknown> | null;
+    status: RecordValuesStatus;
 }
-/**
- * Every field an UPDATE item sets, in the order the item carries them — ALL of
- * them, never a sample: a person approving an overwrite sees the whole of it.
- */
-declare function itemChanges(item: Record<string, unknown>): ItemChange[];
+type RecordReader = (ref: DirectiveRecordRef) => Promise<Record<string, unknown> | null>;
+declare function useRecordValues(read: RecordReader | undefined, ref: DirectiveRecordRef | null): RecordValues;
 
-export { ApplyDirectiveButton, type ApplyDirectiveButtonProps, CHANGE_VALUE_MAX, DirectiveFallbackCard, type DirectiveFallbackCardProps, DirectiveProvisionalCard, type DirectiveProvisionalCardProps, DirectiveRender, type DirectiveRenderProps, type DirectiveRenderer, type DirectiveRendererProps, type ItemChange, SideEffectDirectiveCard, type SideEffectDirectiveCardProps, TARGETING_CLASSES, fieldLabel, getDirectiveRenderer, itemChanges, itemRecordId, provisionalDirectiveSlug, recordFallbackName, registerDirectiveRenderer, resetDirectiveRenderers };
+export { ApplyDirectiveButton, type ApplyDirectiveButtonProps, CHANGE_VALUE_MAX, type ChangeValue, DirectiveChangeList, DirectiveFallbackCard, type DirectiveFallbackCardProps, DirectiveProvisionalCard, type DirectiveProvisionalCardProps, DirectiveRecordRef, DirectiveRender, type DirectiveRenderProps, type DirectiveRenderer, type DirectiveRendererProps, type ItemChange, type ItemChangesOptions, type RecordReader, type RecordValues, type RecordValuesStatus, SideEffectDirectiveCard, type SideEffectDirectiveCardProps, TARGETING_CLASSES, describeChangeValue, fieldLabel, getDirectiveRenderer, itemChanges, itemRecordId, provisionalDirectiveSlug, recordFallbackName, registerDirectiveRenderer, resetDirectiveRenderers, useRecordValues };

package/dist/directives.js

@@ -66,6 +66,9 @@ function recordFallbackName(nounLabel3, id) {
   const short = 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") {
@@ -94,11 +97,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;
 }
@@ -211,12 +231,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] = useState(
-    readsLedger ? { status: "checking" } : { status: "idle" }
-  );
+  const initial = readsLedger ? { status: "checking" } : { status: "idle" };
+  const [state, setState] = useState(initial);
   const [elapsed, setElapsed] = useState(0);
   const [askingAgain, setAskingAgain] = useState(false);
   const startedAt = useRef(null);
+  const identity = JSON.stringify([directive.slug, items, conversationId ?? null]);
+  const [stateFor, setStateFor] = useState(identity);
+  if (stateFor !== identity) {
+    setStateFor(identity);
+    setState(initial);
+    setAskingAgain(false);
+    setElapsed(0);
+  }
+  const currentIdentity = useRef(identity);
+  useEffect(() => {
+    currentIdentity.current = identity;
+  }, [identity]);
   const nounText = nounLabel(directive.noun, host.nouns);
   const shellKey = readsLedger ? JSON.stringify([directive.slug, items, conversationId ?? null]) : "";
   const read = host.applyState;
@@ -239,7 +270,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) {
@@ -279,6 +311,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" });
@@ -291,6 +326,7 @@ function ApplyDirectiveButton({
           ...again ? { again: true } : {}
         });
       } catch (error) {
+        if (!stillHere()) return;
         setAskingAgain(false);
         setState({
           status: "error",
@@ -298,6 +334,7 @@ function ApplyDirectiveButton({
         });
         return;
       }
+      if (!stillHere()) return;
       setAskingAgain(false);
       if (!ok) {
         setState(again ? before : { status: "idle" });
@@ -311,15 +348,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."
@@ -344,6 +385,15 @@ function ApplyDirectiveButton({
               bad && !state.message ? ` \xB7 ${state.failed} failed` : ""
             ] })
           ] }),
+          state.copies > 1 ? /* @__PURE__ */ jsx3(
+            "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__ */ jsx3("span", { className: "inline-flex min-w-0 items-center", children: host.renderRecord?.({
             ...record,
             fallback: recordFallbackName(label2, record.id),
@@ -394,6 +444,7 @@ function ApplyDirectiveButton({
       }
     );
   }
+  const destructive = directive.directiveClass === "delete";
   return /* @__PURE__ */ jsxs2("span", { className: "inline-flex items-center gap-2", children: [
     /* @__PURE__ */ jsxs2(
       "button",
@@ -401,7 +452,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__ */ jsx3(LoaderIcon, { className: "h-3.5 w-3.5 animate-spin" }) : /* @__PURE__ */ jsx3(PlayIcon, { className: "h-3.5 w-3.5" }),
           state.status === "applying" ? `Applying${itemCount ? ` ${itemCount} ${itemCount === 1 ? "item" : "items"}` : ""}\u2026${elapsed ? ` ${elapsed}s` : ""}` : label
@@ -416,7 +468,7 @@ function ApplyDirectiveButton({
 }
 
 // directives/SideEffectDirectiveCard.tsx
-import { useState as useState2 } from "react";
+import { useState as useState3 } from "react";
 import {
   asKindInstance,
   directiveDisplay,
@@ -426,6 +478,39 @@ import {
   nounLabel as nounLabel2,
   nounTitleColumn
 } from "@ai-matrx/content-ir";
+
+// directives/record-values.ts
+import { useEffect as useEffect2, useState as useState2 } from "react";
+function useRecordValues(read, ref) {
+  const key = ref && read ? `${ref.noun}:${ref.id}` : "";
+  const [result, setResult] = useState2({
+    key: "",
+    values: null,
+    status: "idle"
+  });
+  useEffect2(() => {
+    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
 import { Fragment, jsx as jsx4, jsxs as jsxs3 } from "react/jsx-runtime";
 var ROWS_BEFORE_FOLD = 3;
 function ItemRow({
@@ -479,44 +564,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(nounLabel2(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__ */ jsx4("span", { className: "truncate font-medium text-foreground", children: fallback });
-  return /* @__PURE__ */ jsxs3("div", { className: "py-1 text-xs", "data-directive-target": recordId, children: [
-    /* @__PURE__ */ jsxs3("div", { className: "flex min-w-0 items-center gap-2", children: [
-      /* @__PURE__ */ jsx4("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__ */ jsx4("p", { className: "px-1 text-[11px] text-muted-foreground", children: "Sets no fields \u2014 nothing would change." }) : /* @__PURE__ */ jsx4("ul", { className: "mt-0.5 space-y-0.5 px-1", children: changes.map((change) => /* @__PURE__ */ jsxs3(
+  if (changes.length === 0) {
+    return /* @__PURE__ */ jsx4("p", { className: `text-[11px] text-muted-foreground${className ? ` ${className}` : ""}`, children: "Sets no fields \u2014 nothing would change." });
+  }
+  return /* @__PURE__ */ jsx4("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__ */ jsxs3(
       "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__ */ jsx4("span", { className: "shrink-0 text-muted-foreground", children: change.label }),
+          was !== null ? /* @__PURE__ */ jsx4(
+            "span",
+            {
+              className: "min-w-0 max-w-[40%] shrink truncate text-muted-foreground line-through",
+              "data-change-before": "",
+              children: was
+            }
+          ) : null,
           /* @__PURE__ */ jsx4("span", { "aria-hidden": true, className: "shrink-0 text-muted-foreground", children: "\u2192" }),
           /* @__PURE__ */ jsx4(
             "span",
             {
               className: `min-w-0 truncate ${change.clears ? "italic text-muted-foreground" : "text-foreground"}`,
+              "data-change-after": "",
               children: change.value
             }
-          )
+          ),
+          change.same ? /* @__PURE__ */ jsx4("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(nounLabel2(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: nounTitleColumn(directive.noun, host.nouns) }) : [];
+  const name = host.renderRecord ? host.renderRecord({ noun: directive.noun, id: recordId, fallback, context: "row" }) : /* @__PURE__ */ jsx4("span", { className: "truncate font-medium text-foreground", children: fallback });
+  return /* @__PURE__ */ jsxs3("div", { className: "py-1 text-xs", "data-directive-target": recordId, children: [
+    /* @__PURE__ */ jsxs3("div", { className: "flex min-w-0 items-center gap-2", children: [
+      /* @__PURE__ */ jsx4("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__ */ jsx4(DirectiveChangeList, { changes, className: "mt-0.5 px-1" }) : null
   ] });
 }
 function SideEffectDirectiveCard({ directive }) {
   const host = useDirectiveHost();
-  const [expanded, setExpanded] = useState2(false);
+  const [expanded, setExpanded] = useState3(false);
   const items = directive.items;
   const total = items.length;
   const display = directiveDisplay(directive.directiveClass, directive.noun, host.nouns);
@@ -668,6 +782,7 @@ function DirectiveRenderInner({ content, className, streaming }) {
 export {
   ApplyDirectiveButton,
   CHANGE_VALUE_MAX,
+  DirectiveChangeList,
   DirectiveFallbackCard,
   DirectiveHostProvider,
   DirectiveProvisionalCard,
@@ -675,6 +790,7 @@ export {
   DirectiveScopeProvider,
   SideEffectDirectiveCard,
   TARGETING_CLASSES,
+  describeChangeValue,
   fieldLabel,
   getDirectiveRenderer,
   itemChanges,
@@ -684,6 +800,7 @@ export {
   registerDirectiveRenderer,
   resetDirectiveRenderers,
   useDirectiveHost,
-  useDirectiveScope
+  useDirectiveScope,
+  useRecordValues
 };
 //# sourceMappingURL=directives.js.map