@object-ui/core 17.2.0 → 17.5.0

package/dist/actions/ActionRunner.js

@@ -6,8 +6,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { ExpressionEvaluator } from '../evaluator/ExpressionEvaluator';
+import { hasDeclaredPredicate } from '../evaluator/declaredPredicate';
 import { globalUndoManager } from './UndoManager';
-import { warnOnUnknownActionKeys } from './actionKeys';
+import { warnOnDeprecatedObjectParams, warnOnUnknownActionKeys } from './actionKeys';
 /**
  * Bind the server-CEL-parity `os.user` identity alias into an action context
  * (#2358 trap 1). `@objectstack/spec` documents the canonical CEL identity
@@ -27,6 +28,145 @@ function withIdentityAlias(context) {
         return context;
     return { ...context, os: { ...(os && typeof os === 'object' ? os : {}), user } };
 }
+/**
+ * The query param naming the record a form route opens (`?recordId=<id>`).
+ *
+ * The console's reserved-param registry (`@object-ui/app-shell`,
+ * `src/urlParams.ts` → `RECORD_DRAWER_PARAM`) owns this spelling and
+ * `apps/console`'s `FormPage` re-declares it as `FORM_RECORD_ID_PARAM`. It is a
+ * literal in all three places because `@object-ui/core` sits BELOW both in the
+ * dependency graph and cannot import either; the console's `FormPage.test.ts`
+ * pins the spellings equal so they cannot drift apart in silence.
+ */
+const FORM_RECORD_ID_PARAM = 'recordId';
+/**
+ * The query param carrying the OBJECT the forwarded {@link FORM_RECORD_ID_PARAM}
+ * belongs to (objectui#4292).
+ *
+ * It is an ASSERTION, never an override: the form's object always comes from the
+ * FormView metadata, and this param exists solely so the consumer can refuse
+ * when the two disagree. (The registry's `formObject` is the other thing — it
+ * SELECTS which object the record-form overlay edits. Same `<param>Object`
+ * naming, deliberately opposite powers, which is why they are separate names on
+ * separate surfaces.) Widening it into a selector would hand any hand-authored
+ * URL the ability to point a form at an arbitrary object — the hole this closes,
+ * re-opened from the other side.
+ */
+const FORM_RECORD_OBJECT_PARAM = 'recordObject';
+/**
+ * The object the firing context's record belongs to, or `undefined` when the
+ * host did not say (objectui#4292).
+ *
+ * `context.objectName` is MEASURED to be this repo's one spelling of that fact,
+ * not a new convention invented here:
+ *
+ *  - `@object-ui/react`'s `ActionProvider` documents the flat trio `record`,
+ *    `user`, `objectName` and mirrors it into the canonical `ctx.*` scope;
+ *  - `useConsoleActionRuntime` seeds `context: { ...(objectName ? { objectName }
+ *    : {}), … }` — so every console surface that fires a record action
+ *    (`DeclaredActionsBar`, `ObjectView`, `RecordDetailView`) already publishes
+ *    it, and `RecordDetailView` passes it explicitly a second time;
+ *  - `app-shell`'s `recordFormNavigation` resolver already reads exactly this
+ *    key as its last precedence step for `navigate_create` / `navigate_edit`.
+ *
+ * `action.objectName` is deliberately NOT consulted. It declares which object an
+ * ACTION belongs to, which is a statement about the action's placement, not
+ * about the record the id was read from — and trusting metadata about the action
+ * to describe the record is precisely the conflation that made this defect
+ * possible.
+ */
+function readContextObjectName(context) {
+    const name = context.objectName;
+    return typeof name === 'string' && name.trim() !== '' ? name.trim() : undefined;
+}
+/**
+ * Whether opening FormView `viewName` from a record of `contextObject` would
+ * cross an object boundary (objectui#4292).
+ *
+ * View identity is `<object>.<key>` (ADR-0017; `viewEnvelope` builds exactly
+ * that, `defaultListViewId` compares exactly this way), so the question is
+ * answered as a PREFIX match against the object we already hold rather than by
+ * parsing an object name out of the view name — the target's object is a fact
+ * the metadata owns, and this runner only asks whether it is the one in hand.
+ *
+ * Answers `false` — "not comparable, carry on" — whenever either end is missing:
+ * no `contextObject` (host published none), or an unqualified `viewName` (no
+ * dot, so it names no object). Only a qualified name under a DIFFERENT object
+ * is a boundary crossing.
+ */
+function crossesObjectBoundary(viewName, contextObject) {
+    if (!contextObject)
+        return false;
+    if (!viewName.includes('.'))
+        return false;
+    return !viewName.startsWith(`${contextObject}.`);
+}
+/*
+ * ## The two predicate gates in `execute`, and the one question they ask first
+ *
+ * `execute` gates on `condition` and on `disabled`, and both need ONE question
+ * answered before evaluating — "is a gate DECLARED here, i.e. is there a
+ * condition to reach a verdict on?" — for OPPOSITE reasons, which is exactly why
+ * the question has to be asked separately from the verdict:
+ *
+ *   - `disabled` (objectui#3848): an EMPTY predicate must not be handed to
+ *     `evaluateCondition`, whose answer for "no condition" is `true` = BLOCKED.
+ *     Measured consequence of asking `!= null && !== false` instead:
+ *     `disabled: ''` returned `{ success: false, error: 'Action is disabled' }`
+ *     and the handler never ran.
+ *   - `condition` (objectui#3872): a DECLARED-FALSE predicate must not be
+ *     skipped by a truthiness test. `if (action.condition)` never asked whether
+ *     a gate was declared, so `condition: false` — the most explicit "never
+ *     execute" an author can write — landed on `if (false)`, the evaluator was
+ *     never consulted, and the action RAN. Measured on `origin/main` @
+ *     `2937bcf7d`: `condition: false` → `{"success":true}`, handler ran, while
+ *     the semantically identical `{ dialect: 'cel', source: 'false' }` was
+ *     refused. Asking "declared?" routes `false` to `evaluateCondition`, which
+ *     short-circuits booleans (`if (typeof condition === 'boolean') return
+ *     condition`) and blocks.
+ *
+ * Both read {@link hasDeclaredPredicate} — the repo's one definition of that
+ * question, in `evaluator/declaredPredicate.ts` beside the normalizer it is
+ * derived from, with the scope objectui#3850 ruled on (`''` / whitespace-only /
+ * empty-`source` envelope / non-predicate junk are NOT declared; a declared
+ * `false` IS). This gate arrived here first as a module-private helper with a
+ * scope note saying it stayed private until that ruling landed; it has, so the
+ * definition moved down a layer and the renderer side reads the same one
+ * (`components/renderers/action/visibility-gate.ts` re-exports it as
+ * `hasDeclaredVisibilityGate`, `SchemaRenderer`'s `disabled` chain calls it).
+ *
+ * ## Why the gates normalize to DECIDE but evaluate the RAW value
+ *
+ * Historically the two were not interchangeable for a string already spelled as
+ * a `${…}` template: `toPredicateInput` assumed a bare expression and wrapped
+ * unconditionally, so `'${x}'` became `'${${x}}'`, which no longer matched the
+ * single-template fast path and did not parse — leaving a constant verdict whose
+ * direction was set by the caller's error policy (fail-soft got the unparsed
+ * string back, `Boolean(…)` = `true`; fail-closed got a throw). On `disabled`
+ * that meant "always blocked", on `condition` the opposite ("always execute").
+ * That defect was objectui#3871, fixed at the normalizer: an already-`${…}`
+ * string is returned untouched, the normalizer is idempotent, and
+ * `evaluateCondition(toPredicateInput(raw))` agrees with
+ * `evaluateCondition(raw)` on every shape these gates accept.
+ *
+ * The gates still read the raw value. Nothing forces the change now that the two
+ * agree, and it would be churn on the execution path rather than a fix — but the
+ * reason has shifted from "must" to "no reason to", so the equality is pinned
+ * next to each gate's suite (`ActionRunner.disabledGate.test.ts` /
+ * `ActionRunner.conditionGate.test.ts`, the two cases that replaced the
+ * objectui#3871 tripwires) instead of being assumed. Every non-empty shape —
+ * boolean, bare CEL, `${…}` template, `{ dialect, source }` envelope — keeps the
+ * verdict it reaches today.
+ *
+ * The `visible`-filter template in `ActionEngine.getActionsForLocation` used to
+ * be the one place this scope was NOT shared: its non-predicate branch kept a
+ * historical `Boolean(raw)` coercion, so `0` there meant "hidden" — fail-CLOSED
+ * on junk, the opposite of what this module committed to for `disabled`
+ * (`catch { isDisabled = false }`). That filter now reads
+ * {@link hasDeclaredPredicate} too (objectui#3957), so a value that is not a
+ * predicate at all decides nothing on either key, at either entry: `0` / `{}` are
+ * "no gate" here, in the engine filter, and in the shared definition.
+ */
 export class ActionRunner {
     constructor(context = {}) {
         Object.defineProperty(this, "handlers", {
@@ -191,16 +331,45 @@ export class ActionRunner {
             // binds a handler, and binding no handler silently is the #2169 "Mark Done
             // does nothing" shape. Dev-only, warn-once, changes nothing (#4075 step 1).
             warnOnUnknownActionKeys(action);
+            // The compat window for the object-form `params` payload (#5777, maintainer
+            // ruling 2026-08-06 direction A). Checked HERE, before the param-collection
+            // block below rewrites `action.params` into a values map — after that point
+            // an action that authored a legitimate ActionParam[] DEFINITION array also
+            // carries an object under `params`, and the warning could no longer tell the
+            // two apart. Dev-only, warn-once, changes nothing.
+            warnOnDeprecatedObjectParams(action);
             // Resolve the action type
             const actionType = action.type || action.actionType || action.name || '';
-            // Conditional execution
-            if (action.condition) {
+            // Conditional execution. Ask "is a `condition` gate DECLARED?" — not "is
+            // the raw value truthy?" (objectui#3872). Truthiness cannot answer that
+            // question, and on this key it answered it in the OVER-PERMISSIVE
+            // direction: `condition: false` (the most explicit "never execute" an
+            // author can write, and what a template that switches an action off
+            // emits) fell on `if (false)`, so the evaluator was never consulted and
+            // the action executed anyway — while the semantically identical
+            // `{ dialect: 'cel', source: 'false' }` was refused. `evaluateCondition`
+            // short-circuits booleans, so once the gate asks the right question the
+            // verdict needs no boolean branch of its own. See `hasDeclaredPredicate`
+            // for the shared "declared?" scope (objectui#3850) and for why the verdict
+            // still reads the RAW value (`toPredicateInput` used to double-wrap an
+            // already-`${…}` string into a constant verdict — objectui#3871, fixed at
+            // the normalizer; on THIS key that constant meant "always execute").
+            if (hasDeclaredPredicate(action.condition)) {
                 const shouldExecute = this.evaluator.evaluateCondition(action.condition);
                 if (!shouldExecute) {
                     return { success: false, error: 'Action condition not met' };
                 }
             }
-            if (action.disabled != null && action.disabled !== false) {
+            // Ask "is a `disabled` gate DECLARED?" — not "is the key present and not
+            // `false`?" (objectui#3848). The old test let every EMPTY predicate reach
+            // `evaluateCondition`, whose answer for "no condition" is `true`, which on
+            // this key means BLOCKED: `disabled: ''` / `'   '` /
+            // `{ dialect: 'cel', source: '' }` all returned `Action is disabled` with
+            // the handler never invoked. See `hasDeclaredPredicate` above for why the
+            // gate normalizes to decide while the verdict below reads the RAW value
+            // (historically load-bearing: `toPredicateInput` double-wrapped an
+            // already-`${…}` string — objectui#3871, now fixed, so the two agree).
+            if (hasDeclaredPredicate(action.disabled)) {
                 // `disabled` may be a boolean, a CEL string, or the normalized envelope
                 // `{ dialect, source }` (what `objectstack build` emits). The previous
                 // code only evaluated the STRING form and treated any object as truthy,
@@ -448,15 +617,29 @@ export class ActionRunner {
                     success: false,
                     error: 'Action body must be executed server-side — this client runner does not interpret ' +
                         '`body` (sandboxed JS needs an isolated VM; expression bodies use the formula engine). ' +
-                        'Register a `script` handler that POSTs to /api/v1/actions/{object}/{action}.',
+                        'Register a `script` handler that POSTs to /api/v1/actions/{object}/{action} — ' +
+                        'build one with createServerActionHandler from @object-ui/core.',
                 };
             }
-            // ActionDef is open-ended (`[key: string]: any`), so hand-authored
-            // metadata that never passed through the spec parser still compiles with
-            // the retired key. Carry the same prescription the spec's tombstone does,
-            // for the same reason: a bare "no script provided" reads as "you forgot a
-            // field" to an author who did write one.
-            if (typeof action.execute === 'string') {
+            // Read off an UNTYPED view of the action on purpose, and this branch
+            // survives step 3 on purpose (objectstack#4075).
+            //
+            // `ActionDef` no longer declares `execute` — nor any open index signature
+            // — so `tsc` now catches the retired key at every site that AUTHORS an
+            // action literal in code. That is the half of the problem the type can
+            // reach. It is not this half: #3903 established that stored
+            // `sys_metadata` rows are rehydrated UNPARSED, so metadata written before
+            // spec 17 arrives here as a plain object the compiler never saw, still
+            // carrying `execute`. Declaring the key to make this read compile would
+            // re-legitimize a tombstone (#3855 removed it; the spec keeps it only to
+            // reject it BY NAME), and deleting the branch would send those rows back
+            // to a bare "no script provided" — which reads as "you forgot a field" to
+            // an author who did write one, the objectstack#2169 shape.
+            //
+            // So: the cast is the honest spelling of "a key this type deliberately
+            // does not have, read from a row this type never validated".
+            const retiredExecute = action.execute;
+            if (typeof retiredExecute === 'string') {
                 return {
                     success: false,
                     error: '`execute` was removed in @objectstack/spec 17 — rename the key to `target`. ' +
@@ -562,12 +745,24 @@ export class ActionRunner {
             return { success: true };
         }
         // `openIn` is the first-class, declarative switch (ActionSchema.openIn);
-        // it wins over the legacy `navigate.newTab` / `params.newTab` escape
-        // hatches and the external-URL heuristic.
+        // it wins over the legacy `navigate.newTab` escape hatch and the
+        // external-URL heuristic.
+        //
+        // `params.newTab` used to sit between them and is RETIRED (objectui#4097,
+        // executing the objectstack#6828 maintainer ruling of 2026-08-10). It could
+        // only ever fire on an OBJECT-form `params`, which the spec has always
+        // refused on an action (`params` is `z.array(ActionParamSchema)`), so no
+        // validated stack could reach it; and no internal caller synthesizes a
+        // navigation directive into that bag — the runtime value bags carry
+        // collected dialog values, `_selectedIds` and `_rowRecord`, never `newTab`.
+        // Removing it also closes the collision hazard where a params dialog
+        // declaring a field literally named `newTab` would have had the user's own
+        // input silently steer navigation. The spec's refusal message names the
+        // sanctioned spelling: `openIn: 'new-tab'`.
         const openIn = source.openIn ?? action.openIn;
         const newTab = openIn === 'new-tab' ? true
             : openIn === 'self' ? false
-                : (source.newTab ?? action.params?.newTab ?? isExternal);
+                : (source.newTab ?? isExternal);
         // History semantics, the one thing the `navigation` shape carries that
         // `ActionSchema` has no field for. Omitted from the handler call when
         // unset so hosts see the same options object they always did.
@@ -674,6 +869,37 @@ export class ActionRunner {
      * through to `executeActionSchema` and silently no-opped (the "Log Time does
      * nothing" report). The current record id is forwarded as `?recordId=` for
      * hosts that support it; the form route ignores unknown query params.
+     *
+     * ## An id never travels without its object (objectui#4292)
+     *
+     * `?recordId=` names an id and nothing else, so the consumer has to pick an
+     * object to resolve it against, and the only one it can pick is the FormView's
+     * own target object (`/forms/:name` does exactly that since objectui#4278).
+     * That is right whenever the action fired from a record OF that object, and
+     * nothing here used to check that it did: `target: 'showcase_task.edit'` on an
+     * Account record header is publishable metadata, and with per-table integer
+     * keys `GET /data/showcase_task/42` cheerfully answers for Account 42. Before
+     * #4278 the damage stopped at a duplicate insert; now that the route honours
+     * the param, the same mis-scoped action PATCHes a different object's record
+     * with no error anywhere. So the id is forwarded only when the two objects
+     * MATCH, and the object identity rides along as the consumer's second half of
+     * the check ({@link FORM_RECORD_OBJECT_PARAM}).
+     *
+     * The three outcomes, and why the third preserves rather than refuses:
+     *
+     *  - **match** — forward `?recordId=&recordObject=`. The #4278 edit path,
+     *    plus the identity the consumer re-checks against its own view metadata;
+     *  - **mismatch** — forward NEITHER, i.e. the bare `/forms/:name`. A "log
+     *    time" action fired from a Task at another object's create view is not a
+     *    broken edit, it is a CREATE that happens to be launched from a record —
+     *    which is exactly what this route did before #4278 taught it to read the
+     *    param. Refusing here would break a shape that works;
+     *  - **not comparable** — either end unknown ⇒ forward as before. A host that
+     *    publishes no `objectName`, or an unqualified target name, gives this
+     *    runner nothing to compare; tightening on absent information would turn
+     *    working edit flows into creates on every such host. The guard only ever
+     *    fires on information it actually has, and the consumer half applies the
+     *    same rule to a missing `recordObject`.
      */
     async executeForm(action) {
         const name = this.evaluator.evaluate(action.target);
@@ -683,7 +909,13 @@ export class ActionRunner {
         const recordId = (this.context.record && this.context.record.id) ??
             (this.context.data && this.context.data.id);
         const base = `/forms/${name}`;
-        const to = recordId != null ? `${base}?recordId=${encodeURIComponent(String(recordId))}` : base;
+        const contextObject = readContextObjectName(this.context);
+        const to = recordId == null || crossesObjectBoundary(name, contextObject)
+            ? base
+            : `${base}?${FORM_RECORD_ID_PARAM}=${encodeURIComponent(String(recordId))}` +
+                (contextObject
+                    ? `&${FORM_RECORD_OBJECT_PARAM}=${encodeURIComponent(contextObject)}`
+                    : '');
         if (this.navigationHandler) {
             this.navigationHandler(to, { external: false });
             return { success: true };
@@ -708,6 +940,60 @@ export class ActionRunner {
         }
         return this.navigateTo(action, rawUrl, nav);
     }
+    /**
+     * Assemble the request body for the runner's OWN `executeAPI` — the path taken
+     * when no host registered an `api` handler.
+     *
+     * `bodyExtra` is merged LAST, which is the spec's documented semantics for the
+     * key ("Static request-body fields for a `type:'api'` action, merged last
+     * (overrides user params)") and what the console's `apiHandler` already does on
+     * both of its branches. Before objectstack#6837 this path read `action.params`
+     * alone and never looked at `bodyExtra` at all, so an action whose payload lives
+     * entirely in `bodyExtra` — the shape the ADR-0087 conversion produces from an
+     * old object-form `params` page — POSTed an empty body here.
+     *
+     * `params` contributes only in its DEPRECATED non-array form (the compat window
+     * #5777 opened; see `warnOnDeprecatedObjectParams`). An ARRAY `params` is a
+     * parameter DEFINITION list, not a payload: it reaches this method unconsumed
+     * only when no `paramCollectionHandler` is mounted, and POSTing the definitions
+     * as the request body was never a payload any endpoint wanted. It now falls
+     * through to the context record like an absent `params` does.
+     *
+     * `bodyShape` then decides how that payload is WRAPPED, and the wrap covers the
+     * collected payload ONLY — `bodyExtra` stays at the top level. That is the
+     * spec's own wording for the key ("`{ wrap: 'data' }` nests the user-collected
+     * params under that key, while `recordIdParam` and other top-level keys stay
+     * flat") and what both console read-sites already do, so the key means one
+     * thing on every path that honours it. Until objectstack#6938 this path did not
+     * read it at all: the console `apiHandler` wrapped and the runner's own fallback
+     * did not, so the same action changed body shape with the host it ran under.
+     */
+    buildApiRequestBody(action) {
+        const asRecord = (value) => (value && typeof value === 'object' && !Array.isArray(value)
+            ? value
+            : undefined);
+        const bodyExtra = asRecord(action.bodyExtra);
+        const base = asRecord(action.params) ?? this.context.data;
+        // `'flat'` (and an absent//malformed value) means no wrapping — the same
+        // predicate the console read-sites use, so an off-spec `bodyShape` degrades
+        // to the documented default here too instead of producing a `{ undefined: … }`
+        // key on the wire.
+        const shape = action.bodyShape;
+        const wrap = shape && typeof shape === 'object' && typeof shape.wrap === 'string' && shape.wrap
+            ? shape.wrap
+            : undefined;
+        if (wrap) {
+            // The payload nests; `bodyExtra` rides flat beside it. No key collision to
+            // resolve in this branch — that is the point of the wrap — so "merged last"
+            // is preserved by construction.
+            return { [wrap]: base ?? {}, ...bodyExtra };
+        }
+        // Nothing to merge: hand back the historical value as-is, so a host passing a
+        // non-object `context.data` still serializes exactly what it used to.
+        if (!bodyExtra)
+            return base ?? {};
+        return { ...asRecord(base), ...bodyExtra };
+    }
     /**
      * Execute API action — supports both simple string endpoint and complex ApiConfig.
      */
@@ -727,7 +1013,7 @@ export class ActionRunner {
                 // Simple string endpoint
                 url = this.interpolateTarget(apiConfig, action);
                 method = action.method || 'POST';
-                body = JSON.stringify(action.params || this.context.data || {});
+                body = JSON.stringify(this.buildApiRequestBody(action));
             }
             else {
                 // Complex ApiConfig
@@ -748,7 +1034,7 @@ export class ActionRunner {
                         : JSON.stringify(config.body);
                 }
                 else if (method !== 'GET' && method !== 'HEAD') {
-                    body = JSON.stringify(action.params || this.context.data || {});
+                    body = JSON.stringify(this.buildApiRequestBody(action));
                 }
             }
             const fetchInit = { method, headers };
@@ -815,6 +1101,37 @@ export class ActionRunner {
     interpolateTarget(target, action) {
         if (typeof target !== 'string' || target.indexOf('${') === -1)
             return target;
+        // ── The `${param.X}` scope is an INTERNAL runtime value bag, not an
+        //    authoring surface (objectui#4097 ruling B, 2026-08-11) ──────────────
+        //
+        // A non-array `params` reaches this line from ONE direction only: a host
+        // synthesizing a value bag on its way into `runner.execute()` — the
+        // collected values a param dialog just gathered, `_selectedIds` from an
+        // aggregate bulk dispatch, `_rowRecord` from a row surface. Eight internal
+        // producers, measured. No AUTHOR can put a value here: `ActionSchema.params`
+        // is `z.array(ActionParamSchema)`, so the object form is refused at parse,
+        // and the refusal message names the sanctioned spellings.
+        //
+        // That refusal is why this branch survived objectui#4097 while its two
+        // siblings did not. The objectstack#6828 maintainer ruling targeted the
+        // AUTHORING vocabulary — "a key with three meanings and no authorized
+        // spelling for the third" — and both authored meanings are now handled
+        // upstream at parse; PR objectui#4262 removed the third runtime read
+        // (`params.newTab`). What is left here is a channel no author can reach or
+        // observe, so removing it would spend a four-package runtime-contract
+        // migration on an already-unreachable shape. Option A was declined for
+        // exactly that reason: "plumbing expansion with zero pull".
+        //
+        // ⚠️ The hazard the ruling flagged, recorded here so the next reader sees
+        // it at the code rather than in a closed thread: this line's safety rests
+        // ENTIRELY on the producer refusing an authored object-form `params`. If a
+        // future spec loosening ever admits one, an authored scope silently becomes
+        // reachable again — and it would arrive as an interpolation source for URLs
+        // and api targets, which is the shape a params dialog field named for a
+        // navigation directive could steer. The guards are the upstream refusal pin
+        // and the two local pins (`ActionRunner.resultDialog.test.ts`,
+        // `ActionRunner.test.ts`); a spec change that turns them red is the signal,
+        // not a nuisance.
         const params = (action.params && typeof action.params === 'object' && !Array.isArray(action.params))
             ? action.params
             : {};

package/dist/actions/actionErrorDetail.d.ts

@@ -0,0 +1,26 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Resolve a human-readable message out of an ObjectStack error payload.
+ *
+ * Always returns a STRING. The envelope nests the message as
+ * `{ error: { code, message } }`, and passing that object through as
+ * `ActionResult.error` reaches `toast.error()` as a React child and crashes the
+ * page (React #31). That shape used to be rare on the `/actions` route —
+ * failures came back as HTTP 200 with a plain-string `error` — but since
+ * objectstack#3913 a failed action answers with a real status and the nested
+ * object, so every `/actions` caller has to go through this.
+ *
+ * Handles, in order: `{error: 'msg'}`, `{error: {message: 'msg'}}`,
+ * `{message: 'msg'}`, else the caller's fallback.
+ *
+ * Moved here from `@object-ui/app-shell` (`utils/actionErrorDetail`) by
+ * objectui#2904 so `createServerActionHandler` — the core dispatch every
+ * consumer registers — can own the rule.
+ */
+export declare function actionErrorDetail(body: unknown, fallback: string): string;

package/dist/actions/actionErrorDetail.js

@@ -0,0 +1,37 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Resolve a human-readable message out of an ObjectStack error payload.
+ *
+ * Always returns a STRING. The envelope nests the message as
+ * `{ error: { code, message } }`, and passing that object through as
+ * `ActionResult.error` reaches `toast.error()` as a React child and crashes the
+ * page (React #31). That shape used to be rare on the `/actions` route —
+ * failures came back as HTTP 200 with a plain-string `error` — but since
+ * objectstack#3913 a failed action answers with a real status and the nested
+ * object, so every `/actions` caller has to go through this.
+ *
+ * Handles, in order: `{error: 'msg'}`, `{error: {message: 'msg'}}`,
+ * `{message: 'msg'}`, else the caller's fallback.
+ *
+ * Moved here from `@object-ui/app-shell` (`utils/actionErrorDetail`) by
+ * objectui#2904 so `createServerActionHandler` — the core dispatch every
+ * consumer registers — can own the rule.
+ */
+export function actionErrorDetail(body, fallback) {
+    const b = body;
+    const err = b?.error;
+    if (typeof err === 'string' && err.length > 0)
+        return err;
+    const nested = err?.message;
+    if (typeof nested === 'string' && nested.length > 0)
+        return nested;
+    if (typeof b?.message === 'string' && b.message.length > 0)
+        return b.message;
+    return fallback;
+}