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

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.17.1
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/content-ir-react/v0.17.0..npm/content-ir-react/v0.17.1 -- apps/shared/content-ir-react`).
+No source changes intended and no consumer action required.
+
+## 0.17.0 — 2026-10-02
+
+- **A failed apply speaks plainly.** The card no longer prints the server's text as its
+  sentence (G5 review: "unknown / non-writable noun 'task'. Writable: [...]"). It says what
+  failed and what to do — "The task wasn't created. Try again in a moment." / "1 of 2 weren't
+  created. Retry to try those again." — and keeps the raw text behind a **Details** toggle
+  (`data-apply-failure`, `data-apply-failure-details`). New host seam
+  `DirectiveHost.explainFailure(failure) → { what, next } | null` names failures the host
+  recognises; `defaultFailureWords` / `failureWords` are exported. Guard:
+  `__tests__/directive-failure-words.test.tsx` (3 red on 0.16.1).
+
+Consumer action: a host whose `confirm` rejected with a person-ready sentence should map it
+in `explainFailure`; otherwise that sentence now sits behind Details under the default words.
+
 ## 0.16.1 — 2026-10-02
 
 - **A record's title column reads "Title" everywhere.** `itemChanges(item, current,

package/README.md

@@ -74,5 +74,5 @@ cannot express what your host needs, add a seam; never fork the route.
 ## Docs
 
 - Package internals and boundary: `FEATURE.md` beside this file.
-- Cross-repo system-of-record: `common-docs/systems/content-ir-twin/FEATURE.md`.
+- Cross-repo system-of-record: `common-docs/systems/architecture/content-ir/content-ir-twin-FEATURE.md`.
 - Shape System semantics: `matrx-frontend/features/content-ir/docs/SHAPE_SYSTEM.md`.

package/dist/{component-resolution.types-DLO2w-0n.d.cts → component-resolution.types-DY4pGymy.d.cts}

@@ -29,7 +29,7 @@ declare const consoleErrorReporter: ContentIrErrorReporter;
  * resolver contract (rulings R1 + R6), stated once for every UI.
  *
  * Cross-repo system-of-record:
- * `common-docs/systems/content-ir-twin/FEATURE.md` (package boundary) and
+ * `common-docs/systems/architecture/content-ir/content-ir-twin-FEATURE.md` (package boundary) and
  * `matrx-frontend/features/content-ir/docs/SHAPE_SYSTEM.md` (the semantics).
  *
  * Nothing here knows where a row comes from. A host supplies rows from

package/dist/{component-resolution.types-DLO2w-0n.d.ts → component-resolution.types-DY4pGymy.d.ts}

@@ -29,7 +29,7 @@ declare const consoleErrorReporter: ContentIrErrorReporter;
  * resolver contract (rulings R1 + R6), stated once for every UI.
  *
  * Cross-repo system-of-record:
- * `common-docs/systems/content-ir-twin/FEATURE.md` (package boundary) and
+ * `common-docs/systems/architecture/content-ir/content-ir-twin-FEATURE.md` (package boundary) and
  * `matrx-frontend/features/content-ir/docs/SHAPE_SYSTEM.md` (the semantics).
  *
  * Nothing here knows where a row comes from. A host supplies rows from

package/dist/{component-resolution.types-C1MzCf2s.d.cts → component-resolution.types-DwKSF64x.d.cts}

@@ -29,7 +29,7 @@ declare const consoleErrorReporter: ContentIrErrorReporter;
  * resolver contract (rulings R1 + R6), stated once for every UI.
  *
  * Cross-repo system-of-record:
- * `common-docs/systems/content-ir-twin/FEATURE.md` (package boundary) and
+ * `common-docs/systems/architecture/content-ir/content-ir-twin-FEATURE.md` (package boundary) and
  * `matrx-frontend/features/content-ir/docs/SHAPE_SYSTEM.md` (the semantics).
  *
  * Nothing here knows where a row comes from. A host supplies rows from

package/dist/{component-resolution.types-C1MzCf2s.d.ts → component-resolution.types-DwKSF64x.d.ts}

@@ -29,7 +29,7 @@ declare const consoleErrorReporter: ContentIrErrorReporter;
  * resolver contract (rulings R1 + R6), stated once for every UI.
  *
  * Cross-repo system-of-record:
- * `common-docs/systems/content-ir-twin/FEATURE.md` (package boundary) and
+ * `common-docs/systems/architecture/content-ir/content-ir-twin-FEATURE.md` (package boundary) and
  * `matrx-frontend/features/content-ir/docs/SHAPE_SYSTEM.md` (the semantics).
  *
  * Nothing here knows where a row comes from. A host supplies rows from

package/dist/db-component.d.cts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { C as ComponentResolution, a as ContentIrErrorReporter } from './component-resolution.types-C1MzCf2s.cjs';
+import { C as ComponentResolution, a as ContentIrErrorReporter } from './component-resolution.types-DwKSF64x.cjs';
 
 /**
  * The DB-component COMPILE CACHE — session-scoped, keyed per winning row

package/dist/db-component.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { C as ComponentResolution, a as ContentIrErrorReporter } from './component-resolution.types-C1MzCf2s.js';
+import { C as ComponentResolution, a as ContentIrErrorReporter } from './component-resolution.types-DwKSF64x.js';
 
 /**
  * The DB-component COMPILE CACHE — session-scoped, keyed per winning row

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

@@ -166,6 +166,32 @@ interface DirectiveHost {
     itemKind?: DirectiveItemKindLookup;
     /** Where a decode failure or an unhonourable shell is reported. Default: console.error. */
     reportError?: (message: string) => void;
+    /**
+     * Plain words for a failed apply the host recognises ("This button can't
+     * create a task yet." + "Create it from Tasks instead."). The card never shows
+     * the server's raw text as its sentence: it shows these words — or its own
+     * verb-aware default — and keeps the raw text behind "Details". Return null
+     * to use the default.
+     */
+    explainFailure?: (failure: DirectiveFailure) => DirectiveFailureWords | null;
+}
+/** One failed apply, as the card knows it. */
+interface DirectiveFailure {
+    /** The server's / host's own text — technical; shown only behind Details. */
+    raw: string;
+    directiveClass: string;
+    noun: string;
+    /** The noun's display label ("Task"). */
+    nounLabel: string;
+    /** Items that failed, when some applied and some did not. */
+    failed?: number;
+    /** Items in the block. */
+    total?: number;
+}
+/** What failed and what to do — each one short sentence. */
+interface DirectiveFailureWords {
+    what: string;
+    next: string;
 }
 /** Where a directive renders — today, the conversation it sits in (if any). */
 interface DirectiveScope {
@@ -193,4 +219,4 @@ declare function DirectiveHostProvider({ host, children }: DirectiveHostProvider
  */
 declare function useDirectiveHost(): DirectiveHost;
 
-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 };
+export { type DirectiveFailure as D, type DirectiveFailureWords as a, type DirectiveRecordRef as b, type DirectiveApplyResult as c, type DirectiveApplyState as d, type DirectiveAskRequest as e, type DirectiveCopyProps as f, type DirectiveHost as g, DirectiveHostProvider as h, type DirectiveHostProviderProps as i, type DirectiveOpenItemOptions as j, type DirectiveRecordProps as k, type DirectiveScope as l, DirectiveScopeProvider as m, type DirectiveShell as n, useDirectiveScope as o, useDirectiveHost as u };

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

@@ -166,6 +166,32 @@ interface DirectiveHost {
     itemKind?: DirectiveItemKindLookup;
     /** Where a decode failure or an unhonourable shell is reported. Default: console.error. */
     reportError?: (message: string) => void;
+    /**
+     * Plain words for a failed apply the host recognises ("This button can't
+     * create a task yet." + "Create it from Tasks instead."). The card never shows
+     * the server's raw text as its sentence: it shows these words — or its own
+     * verb-aware default — and keeps the raw text behind "Details". Return null
+     * to use the default.
+     */
+    explainFailure?: (failure: DirectiveFailure) => DirectiveFailureWords | null;
+}
+/** One failed apply, as the card knows it. */
+interface DirectiveFailure {
+    /** The server's / host's own text — technical; shown only behind Details. */
+    raw: string;
+    directiveClass: string;
+    noun: string;
+    /** The noun's display label ("Task"). */
+    nounLabel: string;
+    /** Items that failed, when some applied and some did not. */
+    failed?: number;
+    /** Items in the block. */
+    total?: number;
+}
+/** What failed and what to do — each one short sentence. */
+interface DirectiveFailureWords {
+    what: string;
+    next: string;
 }
 /** Where a directive renders — today, the conversation it sits in (if any). */
 interface DirectiveScope {
@@ -193,4 +219,4 @@ declare function DirectiveHostProvider({ host, children }: DirectiveHostProvider
  */
 declare function useDirectiveHost(): DirectiveHost;
 
-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 };
+export { type DirectiveFailure as D, type DirectiveFailureWords as a, type DirectiveRecordRef as b, type DirectiveApplyResult as c, type DirectiveApplyState as d, type DirectiveAskRequest as e, type DirectiveCopyProps as f, type DirectiveHost as g, DirectiveHostProvider as h, type DirectiveHostProviderProps as i, type DirectiveOpenItemOptions as j, type DirectiveRecordProps as k, type DirectiveScope as l, DirectiveScopeProvider as m, type DirectiveShell as n, useDirectiveScope as o, useDirectiveHost as u };

package/dist/directives.cjs

@@ -31,7 +31,9 @@ __export(directives_exports, {
   DirectiveScopeProvider: () => DirectiveScopeProvider,
   SideEffectDirectiveCard: () => SideEffectDirectiveCard,
   TARGETING_CLASSES: () => TARGETING_CLASSES,
+  defaultFailureWords: () => defaultFailureWords,
   describeChangeValue: () => describeChangeValue,
+  failureWords: () => failureWords,
   fieldLabel: () => fieldLabel,
   getDirectiveRenderer: () => getDirectiveRenderer,
   itemChanges: () => itemChanges,
@@ -167,6 +169,30 @@ function itemChanges(item, current, options = {}) {
   return out;
 }
 
+// directives/failure-words.ts
+var PAST = {
+  create: "created",
+  update: "updated",
+  delete: "deleted"
+};
+function defaultFailureWords(failure) {
+  const verbed = PAST[failure.directiveClass] ?? "applied";
+  const noun = failure.nounLabel.trim().toLowerCase() || "item";
+  if (failure.failed && failure.total && failure.total > 1) {
+    return {
+      what: `${failure.failed} of ${failure.total} weren't ${verbed}.`,
+      next: "Retry to try those again."
+    };
+  }
+  return {
+    what: `The ${noun} wasn't ${verbed}.`,
+    next: "Try again in a moment."
+  };
+}
+function failureWords(failure, explain) {
+  return explain?.(failure) ?? defaultFailureWords(failure);
+}
+
 // directives/icons.tsx
 var import_jsx_runtime2 = require("react/jsx-runtime");
 function Svg({ children, ...props }) {
@@ -424,10 +450,23 @@ function ApplyDirectiveButton({
         children: [
           /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("span", { className: "inline-flex min-w-0 items-start gap-1", children: [
             bad ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(AlertIcon, { className: "mt-px h-3.5 w-3.5 shrink-0" }) : /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(CheckCircleIcon, { className: "mt-px h-3.5 w-3.5 shrink-0" }),
-            /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("span", { className: "min-w-0", children: [
-              state.message ?? `Applied ${state.applied}`,
-              bad && !state.message ? ` \xB7 ${state.failed} failed` : ""
-            ] })
+            bad ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+              FailureNotice,
+              {
+                words: failureWords(
+                  {
+                    raw: state.message ?? `${state.failed} failed`,
+                    directiveClass: directive.directiveClass,
+                    noun: directive.noun,
+                    nounLabel: nounText,
+                    failed: state.failed,
+                    total: state.applied + state.failed
+                  },
+                  host.explainFailure
+                ),
+                raw: state.message
+              }
+            ) : /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("span", { className: "min-w-0", children: state.message ?? `Applied ${state.applied}` })
           ] }),
           state.copies > 1 ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
             "span",
@@ -504,10 +543,64 @@ function ApplyDirectiveButton({
         ]
       }
     ),
-    state.status === "error" ? /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("span", { className: "inline-flex max-w-sm items-start gap-1 text-xs text-destructive", children: [
-      /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(AlertIcon, { className: "mt-0.5 h-3.5 w-3.5 shrink-0" }),
-      /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("span", { children: state.message })
-    ] }) : null
+    state.status === "error" ? /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)(
+      "span",
+      {
+        className: "inline-flex max-w-sm items-start gap-1 text-xs text-destructive",
+        "data-apply-state": "error",
+        children: [
+          /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(AlertIcon, { className: "mt-0.5 h-3.5 w-3.5 shrink-0" }),
+          /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+            FailureNotice,
+            {
+              words: failureWords(
+                {
+                  raw: state.message,
+                  directiveClass: directive.directiveClass,
+                  noun: directive.noun,
+                  nounLabel: nounText
+                },
+                host.explainFailure
+              ),
+              raw: state.message
+            }
+          )
+        ]
+      }
+    ) : null
+  ] });
+}
+function FailureNotice({
+  words,
+  raw
+}) {
+  const [open, setOpen] = (0, import_react2.useState)(false);
+  const detail = raw?.trim() ?? "";
+  return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("span", { className: "flex min-w-0 flex-col gap-0.5", "data-apply-failure": true, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("span", { className: "min-w-0", children: [
+      words.what,
+      " ",
+      words.next,
+      detail ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+        "button",
+        {
+          type: "button",
+          onClick: () => setOpen((v) => !v),
+          "aria-expanded": open,
+          className: "ml-1 underline underline-offset-2 hover:no-underline",
+          "data-apply-failure-details-toggle": true,
+          children: open ? "Hide details" : "Details"
+        }
+      ) : null
+    ] }),
+    open && detail ? /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+      "span",
+      {
+        className: "block max-w-sm select-text break-words font-mono text-[11px] text-muted-foreground",
+        "data-apply-failure-details": true,
+        children: detail
+      }
+    ) : null
   ] });
 }