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

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,75 @@ 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`.
+ */
+declare function itemChanges(item: Record<string, unknown>, current?: Record<string, unknown> | null): 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 +161,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 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,26 @@ 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) {
   const out = [];
   for (const [key, raw] of Object.entries(item)) {
     if (NOT_A_CHANGE.has(key)) continue;
-    out.push({ key, label: fieldLabel(key), ...describeValue(raw) });
+    const change = { key, label: fieldLabel(key), ...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 +229,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 +268,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 +309,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 +324,7 @@ function ApplyDirectiveButton({
           ...again ? { again: true } : {}
         });
       } catch (error) {
+        if (!stillHere()) return;
         setAskingAgain(false);
         setState({
           status: "error",
@@ -298,6 +332,7 @@ function ApplyDirectiveButton({
         });
         return;
       }
+      if (!stillHere()) return;
       setAskingAgain(false);
       if (!ok) {
         setState(again ? before : { status: "idle" });
@@ -311,15 +346,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 +383,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 +442,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 +450,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 +466,7 @@ function ApplyDirectiveButton({
 }
 
 // directives/SideEffectDirectiveCard.tsx
-import { useState as useState2 } from "react";
+import { useState as useState3 } from "react";
 import {
   asKindInstance,
   directiveDisplay,
@@ -426,6 +476,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 +562,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) : [];
+  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 +780,7 @@ function DirectiveRenderInner({ content, className, streaming }) {
 export {
   ApplyDirectiveButton,
   CHANGE_VALUE_MAX,
+  DirectiveChangeList,
   DirectiveFallbackCard,
   DirectiveHostProvider,
   DirectiveProvisionalCard,
@@ -675,6 +788,7 @@ export {
   DirectiveScopeProvider,
   SideEffectDirectiveCard,
   TARGETING_CLASSES,
+  describeChangeValue,
   fieldLabel,
   getDirectiveRenderer,
   itemChanges,
@@ -684,6 +798,7 @@ export {
   registerDirectiveRenderer,
   resetDirectiveRenderers,
   useDirectiveHost,
-  useDirectiveScope
+  useDirectiveScope,
+  useRecordValues
 };
 //# sourceMappingURL=directives.js.map