@ai-matrx/content-ir-react 0.17.1 → 0.18.1

package/dist/directives.d.ts

@@ -1,5 +1,5 @@
-import { D as DirectiveFailure, a as DirectiveFailureWords, b as DirectiveRecordRef } from './directive-host-BOML4BQ7.js';
-export { c as DirectiveApplyResult, d as DirectiveApplyState, e as DirectiveAskRequest, f as DirectiveCopyProps, g as DirectiveHost, h as DirectiveHostProvider, i as DirectiveHostProviderProps, j as DirectiveOpenItemOptions, k as DirectiveRecordProps, l as DirectiveScope, m as DirectiveScopeProvider, n as DirectiveShell, u as useDirectiveHost, o as useDirectiveScope } from './directive-host-BOML4BQ7.js';
+import { D as DirectiveFailure, a as DirectiveFailureWords, b as DirectiveRecordRef } from './directive-host-Bw2_PrgL.js';
+export { c as DirectiveApplyResult, d as DirectiveApplyState, e as DirectiveAskRequest, f as DirectiveCopyProps, g as DirectiveHost, h as DirectiveHostProvider, i as DirectiveHostProviderProps, j as DirectiveOpenItemOptions, k as DirectiveRecordProps, l as DirectiveScope, m as DirectiveScopeProvider, n as DirectiveShell, u as useDirectiveHost, o as useDirectiveScope } from './directive-host-Bw2_PrgL.js';
 import * as react from 'react';
 import { ComponentType } from 'react';
 import { DecodedDirective, DirectiveClass } from '@ai-matrx/content-ir';
@@ -40,14 +40,42 @@ declare function getDirectiveRenderer(directive: Pick<DecodedDirective, "slug" |
 /** Tests only. */
 declare function resetDirectiveRenderers(): void;
 
+/**
+ * What the Apply control knows about its block, for the rest of the card:
+ *  - `pending` — the ledger has not answered yet;
+ *  - `open`    — nothing applied: rows compare against the record as it is now;
+ *  - `applied` — the change happened: rows draw it from `before` (the server's
+ *                record of what it replaced), never from a live re-read, which
+ *                now holds the NEW value.
+ */
+type DirectiveApplyPhase = {
+    phase: "pending";
+} | {
+    phase: "open";
+} | {
+    phase: "applied";
+    before: ReadonlyArray<Record<string, unknown> | null> | null;
+};
+/** Does this card read the ledger before offering Apply? (One rule, card and control.) */
+declare function readsApplyLedger(host: {
+    applyState?: unknown;
+    confirm?: unknown;
+}, directive: DecodedDirective): boolean;
 interface ApplyDirectiveButtonProps {
     directive: DecodedDirective;
     label?: string;
     /** How many things this will write — shown during the wait so a long apply reads as work, not a frozen spinner. */
     itemCount?: number;
     onApplied?: () => void;
+    /** Told whenever what the control knows about its block changes. */
+    onPhase?: (phase: DirectiveApplyPhase) => void;
+    /**
+     * The block would change nothing (an update that sets no field). Apply stays
+     * — validation offers, never blocks — but muted, with the reason beside it.
+     */
+    nothingToChange?: boolean;
 }
-declare function ApplyDirectiveButton({ directive, label, itemCount, onApplied, }: ApplyDirectiveButtonProps): react.JSX.Element | null;
+declare function ApplyDirectiveButton({ directive, label, itemCount, onApplied, onPhase, nothingToChange, }: ApplyDirectiveButtonProps): react.JSX.Element | null;
 
 /**
  * WHAT A DIRECTIVE ITEM WILL DO TO AN EXISTING RECORD — for the card, the
@@ -61,7 +89,7 @@ declare function ApplyDirectiveButton({ directive, label, itemCount, onApplied,
  * 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
+ * Law: common-docs/policies/no-dead-ends.md — the sentence
  * names what changes.
  */
 /** Classes whose items point at an EXISTING record by `id`. */
@@ -195,4 +223,4 @@ interface RecordValues {
 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, type ChangeValue, DirectiveChangeList, DirectiveFailure, DirectiveFailureWords, 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, defaultFailureWords, describeChangeValue, failureWords, fieldLabel, getDirectiveRenderer, itemChanges, itemRecordId, provisionalDirectiveSlug, recordFallbackName, registerDirectiveRenderer, resetDirectiveRenderers, useRecordValues };
+export { ApplyDirectiveButton, type ApplyDirectiveButtonProps, CHANGE_VALUE_MAX, type ChangeValue, type DirectiveApplyPhase, DirectiveChangeList, DirectiveFailure, DirectiveFailureWords, 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, defaultFailureWords, describeChangeValue, failureWords, fieldLabel, getDirectiveRenderer, itemChanges, itemRecordId, provisionalDirectiveSlug, readsApplyLedger, recordFallbackName, registerDirectiveRenderer, resetDirectiveRenderers, useRecordValues };

package/dist/directives.js

@@ -44,7 +44,7 @@ function resetDirectiveRenderers() {
 }
 
 // directives/ApplyDirectiveButton.tsx
-import { useEffect, useRef, useState } from "react";
+import { useEffect, useRef, useState, useSyncExternalStore } from "react";
 import { nounLabel } from "@ai-matrx/content-ir";
 
 // directives/item-changes.ts
@@ -242,19 +242,52 @@ function classIcon(directiveClass, noun) {
 
 // directives/ApplyDirectiveButton.tsx
 import { jsx as jsx3, jsxs as jsxs2 } from "react/jsx-runtime";
+var applyOutcomes = /* @__PURE__ */ new WeakMap();
+var EMPTY_AUTHORITY = {};
+var outcomeListeners = /* @__PURE__ */ new Set();
+function outcomesOf(host) {
+  let held = applyOutcomes.get(host);
+  if (!held) {
+    held = /* @__PURE__ */ new Map();
+    applyOutcomes.set(host, held);
+  }
+  return held;
+}
+function publishOutcome(host, identity, outcome) {
+  outcomesOf(host).set(identity, outcome);
+  for (const listener of outcomeListeners) listener();
+}
+function subscribeOutcomes(listener) {
+  outcomeListeners.add(listener);
+  return () => {
+    outcomeListeners.delete(listener);
+  };
+}
+function useApplyOutcome(host, identity) {
+  return useSyncExternalStore(
+    subscribeOutcomes,
+    () => applyOutcomes.get(host)?.get(identity) ?? null,
+    () => null
+  );
+}
 var FINISH_POLL_MS = 2e3;
 var FINISH_POLLS_MAX = 30;
+function readsApplyLedger(host, directive) {
+  return !!host.applyState && !!host.confirm && directive.parsed.executes && directive.items.length > 0;
+}
 function ApplyDirectiveButton({
   directive,
   label = "Apply",
   itemCount,
-  onApplied
+  onApplied,
+  onPhase,
+  nothingToChange = false
 }) {
   const host = useDirectiveHost();
   const scope = useDirectiveScope();
   const conversationId = scope.conversationId || void 0;
   const items = directive.items;
-  const readsLedger = !!host.applyState && !!host.confirm && directive.parsed.executes && items.length > 0;
+  const readsLedger = readsApplyLedger(host, directive);
   const initial = readsLedger ? { status: "checking" } : { status: "idle" };
   const [state, setState] = useState(initial);
   const [elapsed, setElapsed] = useState(0);
@@ -268,6 +301,8 @@ function ApplyDirectiveButton({
     setAskingAgain(false);
     setElapsed(0);
   }
+  const shared = useApplyOutcome(host.confirm ?? EMPTY_AUTHORITY, identity);
+  const view = state.status === "asking" || !shared ? state : shared;
   const currentIdentity = useRef(identity);
   useEffect(() => {
     currentIdentity.current = identity;
@@ -295,7 +330,8 @@ function ApplyDirectiveButton({
               failed: 0,
               message: answer.message?.trim() ? answer.message.trim() : null,
               records: answer.records ?? [],
-              copies: Math.max(1, answer.copies ?? 1)
+              copies: Math.max(1, answer.copies ?? 1),
+              before: answer.before ?? null
             } : prev
           );
         } else if (answer.state === "in_flight" && polls < FINISH_POLLS_MAX) {
@@ -320,24 +356,34 @@ function ApplyDirectiveButton({
       if (timer) clearTimeout(timer);
     };
   }, [shellKey, read, report]);
+  const appliedClean = view.status === "applied" && view.failed === 0 ? view : null;
+  const appliedBefore = appliedClean ? appliedClean.before : null;
+  const phaseKey = view.status === "checking" || view.status === "finishing" ? "pending" : appliedClean ? `applied:${JSON.stringify(appliedBefore)}` : "open";
+  useEffect(() => {
+    if (!onPhase) return;
+    if (phaseKey === "pending") onPhase({ phase: "pending" });
+    else if (phaseKey === "open") onPhase({ phase: "open" });
+    else onPhase({ phase: "applied", before: appliedBefore });
+  }, [phaseKey, onPhase, appliedBefore]);
+  const applyingSince = view.status === "applying" ? view.startedAt : null;
   useEffect(() => {
-    if (state.status !== "applying") return;
-    startedAt.current = Date.now();
+    if (applyingSince === null) return;
+    startedAt.current = applyingSince;
     const id = setInterval(
       () => setElapsed(Math.round((Date.now() - (startedAt.current ?? 0)) / 1e3)),
       1e3
     );
     return () => clearInterval(id);
-  }, [state.status]);
+  }, [applyingSince]);
   if (!directive.parsed.executes) return null;
   const confirm = host.confirm;
   if (!confirm) return null;
   async function handleApply(again = false) {
     if (!confirm) return;
-    const before = state;
+    const prior = view;
     const askedFor = identity;
     const stillHere = () => currentIdentity.current === askedFor;
-    const priorCopies = state.status === "applied" ? state.copies : 0;
+    const priorCopies = view.status === "applied" ? view.copies : 0;
     if (host.ask) {
       if (again) setAskingAgain(true);
       else setState({ status: "asking" });
@@ -361,41 +407,43 @@ function ApplyDirectiveButton({
       if (!stillHere()) return;
       setAskingAgain(false);
       if (!ok) {
-        setState(again ? before : { status: "idle" });
+        setState(again ? prior : { status: "idle" });
         return;
       }
     }
     setElapsed(0);
-    setState({ status: "applying" });
+    setState((prev) => prev.status === "asking" ? { status: "idle" } : prev);
+    publishOutcome(confirm, askedFor, { status: "applying", startedAt: Date.now() });
     try {
       const shell = { __kind: directive.slug, items };
       if (conversationId) shell.conversationId = conversationId;
       if (again) shell.force = true;
       const result = await confirm(shell);
-      if (!stillHere()) return;
-      setState({
+      publishOutcome(confirm, askedFor, {
         status: "applied",
         applied: result.applied,
         failed: result.failed,
         message: result.message?.trim() ? result.message.trim() : null,
         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)
+        copies: again ? Math.max(1, priorCopies) + 1 : Math.max(1, priorCopies),
+        // "Run again" wrote the same values over themselves; what the FIRST
+        // apply replaced is still the change this block made.
+        before: again && prior.status === "applied" && prior.before ? prior.before : result.before ?? null
       });
-      onApplied?.();
+      if (stillHere()) onApplied?.();
     } catch (error) {
-      if (!stillHere()) return;
-      setState({
+      publishOutcome(confirm, askedFor, {
         status: "error",
         message: error instanceof Error && error.message ? error.message : "That couldn't be applied just now. Please try again."
       });
     }
   }
-  if (state.status === "applied") {
-    const bad = state.failed > 0;
+  if (view.status === "applied") {
+    const bad = view.failed > 0;
     const trashed = directive.directiveClass === "delete";
     const label2 = nounText;
-    const records = host.renderRecord ? state.records : [];
+    const records = host.renderRecord ? view.records : [];
     return /* @__PURE__ */ jsxs2(
       "span",
       {
@@ -409,26 +457,26 @@ function ApplyDirectiveButton({
               {
                 words: failureWords(
                   {
-                    raw: state.message ?? `${state.failed} failed`,
+                    raw: view.message ?? `${view.failed} failed`,
                     directiveClass: directive.directiveClass,
                     noun: directive.noun,
                     nounLabel: nounText,
-                    failed: state.failed,
-                    total: state.applied + state.failed
+                    failed: view.failed,
+                    total: view.applied + view.failed
                   },
                   host.explainFailure
                 ),
-                raw: state.message
+                raw: view.message
               }
-            ) : /* @__PURE__ */ jsx3("span", { className: "min-w-0", children: state.message ?? `Applied ${state.applied}` })
+            ) : /* @__PURE__ */ jsx3("span", { className: "min-w-0", children: view.message ?? `Applied ${view.applied}` })
           ] }),
-          state.copies > 1 ? /* @__PURE__ */ jsx3(
+          view.copies > 1 ? /* @__PURE__ */ jsx3(
             "span",
             {
               className: "shrink-0 text-muted-foreground",
-              "data-apply-copies": state.copies,
+              "data-apply-copies": view.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`
+              children: directive.directiveClass === "create" ? `${view.copies} copies` : `Ran ${view.copies} times`
             }
           ) : null,
           records.map((record) => /* @__PURE__ */ jsx3("span", { className: "inline-flex min-w-0 items-center", children: host.renderRecord?.({
@@ -455,7 +503,7 @@ function ApplyDirectiveButton({
       }
     );
   }
-  if (state.status === "checking") {
+  if (view.status === "checking") {
     return /* @__PURE__ */ jsx3(
       "span",
       {
@@ -467,7 +515,7 @@ function ApplyDirectiveButton({
       }
     );
   }
-  if (state.status === "finishing") {
+  if (view.status === "finishing") {
     return /* @__PURE__ */ jsxs2(
       "span",
       {
@@ -482,22 +530,25 @@ function ApplyDirectiveButton({
     );
   }
   const destructive = directive.directiveClass === "delete";
+  const muted = nothingToChange && view.status === "idle";
   return /* @__PURE__ */ jsxs2("span", { className: "inline-flex items-center gap-2", children: [
+    muted ? /* @__PURE__ */ jsx3("span", { className: "text-xs text-muted-foreground", "data-apply-nothing": "", children: "Nothing to change" }) : null,
     /* @__PURE__ */ jsxs2(
       "button",
       {
         type: "button",
         onClick: () => void handleApply(),
-        disabled: state.status === "applying" || state.status === "asking" || items.length === 0,
-        "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"}`,
+        disabled: view.status === "applying" || view.status === "asking" || items.length === 0,
+        "data-apply-tone": muted ? "muted" : destructive ? "destructive" : "default",
+        title: muted ? "It sets no fields, so applying it changes nothing." : void 0,
+        className: `inline-flex items-center gap-1 rounded-md border px-2 py-1 text-xs font-medium disabled:opacity-50 ${muted ? "border-border/60 bg-background text-muted-foreground hover:bg-accent" : 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
+          view.status === "applying" ? /* @__PURE__ */ jsx3(LoaderIcon, { className: "h-3.5 w-3.5 animate-spin" }) : /* @__PURE__ */ jsx3(PlayIcon, { className: "h-3.5 w-3.5" }),
+          view.status === "applying" ? `Applying${itemCount ? ` ${itemCount} ${itemCount === 1 ? "item" : "items"}` : ""}\u2026${elapsed ? ` ${elapsed}s` : ""}` : label
         ]
       }
     ),
-    state.status === "error" ? /* @__PURE__ */ jsxs2(
+    view.status === "error" ? /* @__PURE__ */ jsxs2(
       "span",
       {
         className: "inline-flex max-w-sm items-start gap-1 text-xs text-destructive",
@@ -509,14 +560,14 @@ function ApplyDirectiveButton({
             {
               words: failureWords(
                 {
-                  raw: state.message,
+                  raw: view.message,
                   directiveClass: directive.directiveClass,
                   noun: directive.noun,
                   nounLabel: nounText
                 },
                 host.explainFailure
               ),
-              raw: state.message
+              raw: view.message
             }
           )
         ]
@@ -608,12 +659,13 @@ function ItemRow({
   directive,
   item,
   index,
-  total
+  total,
+  phase
 }) {
   const host = useDirectiveHost();
   const recordId = TARGETING_CLASSES.has(directive.directiveClass) ? itemRecordId(item) : null;
   if (recordId) {
-    return /* @__PURE__ */ jsx4(TargetRow, { directive, item, recordId });
+    return /* @__PURE__ */ jsx4(TargetRow, { directive, item, recordId, index, phase });
   }
   const titleColumn = nounTitleColumn(directive.noun, host.nouns);
   const title = itemTitle(item, titleColumn, index, total);
@@ -700,16 +752,20 @@ function DirectiveChangeList({
 function TargetRow({
   directive,
   item,
-  recordId
+  recordId,
+  index,
+  phase
 }) {
   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 readsLive = isUpdate && phase.phase === "open";
+  const live = useRecordValues(
+    readsLive ? host.readRecord : void 0,
+    readsLive ? { noun: directive.noun, id: recordId } : null
   );
-  const changes = isUpdate ? itemChanges(item, current.values, { titleColumn: nounTitleColumn(directive.noun, host.nouns) }) : [];
+  const compareTo = phase.phase === "applied" ? phase.before?.[index] ?? null : readsLive ? live.values : null;
+  const changes = isUpdate ? itemChanges(item, compareTo, { 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: [
@@ -726,6 +782,10 @@ function SideEffectDirectiveCard({ directive }) {
   const total = items.length;
   const display = directiveDisplay(directive.directiveClass, directive.noun, host.nouns);
   const Icon = classIcon(directive.directiveClass, directive.noun);
+  const [phase, setPhase] = useState3(
+    () => readsApplyLedger(host, directive) ? { phase: "pending" } : { phase: "open" }
+  );
+  const nothingToChange = directive.directiveClass === "update" && total > 0 && items.every((item) => itemChanges(item).length === 0);
   const shown = expanded ? items : items.slice(0, ROWS_BEFORE_FOLD);
   const hidden = total - shown.length;
   return /* @__PURE__ */ jsxs3("div", { className: "my-3 rounded-md border border-border bg-card px-2.5 py-1.5", "data-directive": directive.slug, children: [
@@ -740,13 +800,21 @@ function SideEffectDirectiveCard({ directive }) {
       ] }),
       /* @__PURE__ */ jsxs3("div", { className: "ml-auto flex items-center gap-1", children: [
         host.renderCopy?.({ label: display.title, value: directive.shell, size: "icon" }),
-        /* @__PURE__ */ jsx4(ApplyDirectiveButton, { directive, itemCount: total })
+        /* @__PURE__ */ jsx4(
+          ApplyDirectiveButton,
+          {
+            directive,
+            itemCount: total,
+            onPhase: setPhase,
+            nothingToChange
+          }
+        )
       ] })
     ] }),
     total === 0 ? (
       // Stated, never silent: an empty batch is a real (and suspicious) state.
       /* @__PURE__ */ jsx4("p", { className: "mt-1 text-xs text-muted-foreground", children: "No items \u2014 nothing would be written." })
-    ) : /* @__PURE__ */ jsx4("div", { className: "mt-0.5 divide-y divide-border/60", children: shown.map((item, i) => /* @__PURE__ */ jsx4(ItemRow, { directive, item, index: i, total }, i)) }),
+    ) : /* @__PURE__ */ jsx4("div", { className: "mt-0.5 divide-y divide-border/60", children: shown.map((item, i) => /* @__PURE__ */ jsx4(ItemRow, { directive, item, index: i, total, phase }, i)) }),
     hidden > 0 || expanded ? /* @__PURE__ */ jsxs3(
       "button",
       {
@@ -889,6 +957,7 @@ export {
   itemChanges,
   itemRecordId,
   provisionalDirectiveSlug,
+  readsApplyLedger,
   recordFallbackName,
   registerDirectiveRenderer,
   resetDirectiveRenderers,