@object-ui/core 17.6.0 → 18.0.0

package/dist/actions/ActionRunner.d.ts

@@ -19,43 +19,37 @@
  * Features: conditional execution, confirmation, toast notifications,
  * redirect handling, action chaining, custom handler registration.
  */
-import type { UIActionSchema } from '@object-ui/types';
+import type { ActionContext, ActionResult, UIActionSchema } from '@object-ui/types';
 import type { Action as SpecActionInput } from '@objectstack/spec/ui';
 import { ExpressionEvaluator } from '../evaluator/ExpressionEvaluator.js';
-import { type UndoableOperation } from './UndoManager.js';
-export interface ActionResult {
-    success: boolean;
-    data?: any;
-    error?: string;
-    reload?: boolean;
-    close?: boolean;
-    redirect?: string;
-    /** Modal schema to render (for type: 'modal') */
-    modal?: any;
-    /**
-     * Suppress the automatic success toast for this result. A handler sets this
-     * when the action only HANDED OFF to a follow-up UI rather than completing —
-     * e.g. a `flow` action that paused at a screen and opened the flow-runner. The
-     * action hasn't "completed yet", so a "success" toast on open would be
-     * misleading; the follow-up surface owns its own completion messaging.
-     */
-    silent?: boolean;
-    /**
-     * An undoable operation captured by the handler (e.g. an `undoable` update
-     * action's prior field values). When present, the runner pushes it onto the
-     * global UndoManager and the success toast offers an "Undo" affordance.
-     */
-    undo?: UndoableOperation;
-}
-export interface ActionContext {
-    data?: Record<string, any>;
-    record?: any;
-    selectedRecords?: Record<string, any>[];
-    /** Live page-variable snapshot (ADR-0049), published by PageVariableActionBridge. */
-    pageVariables?: Record<string, any>;
-    user?: any;
-    [key: string]: any;
-}
+import { type FieldContainerLike } from '../utils/predicate-record.js';
+/**
+ * What an action handler returns and the runner reads — ONE authority, in
+ * `@object-ui/types` (objectui#6349, batch 4), re-exported here exactly as
+ * {@link ActionContext} is below. The members this module used to declare
+ * (`reload`, `redirect`, `modal`, `silent`, `undo`) moved down with it, and
+ * `UndoableOperation`, which types `undo`, moved down beside it
+ * (`./UndoManager.js` re-exports that one). The gate that counts authorities is
+ * `scripts/__tests__/one-authority-per-exported-name-6273.test.ts`; a re-export
+ * is not one.
+ */
+export type { ActionResult } from '@object-ui/types';
+/**
+ * The context a runner executes actions in — ONE authority, in
+ * `@object-ui/types` (objectui#6349, batch 4). This module RE-EXPORTS that
+ * declaration instead of declaring a second one, so an import of
+ * `ActionContext` from `@object-ui/core` and one from `@object-ui/types` are
+ * the same type. `@object-ui/types` is the dependency-legal side: it depends on
+ * no `@object-ui/*` package, and this package depends on it.
+ *
+ * A re-export is not a second authority —
+ * `scripts/__tests__/one-authority-per-exported-name-6273.test.ts` counts
+ * declarations and ALIASING re-exports, never `export type { X } from …` —
+ * which is why this convergence takes `ActionContext` off that gate's
+ * `KNOWN_COLLISIONS` baseline. The member drift it removed is recorded on the
+ * declaration itself.
+ */
+export type { ActionContext } from '@object-ui/types';
 /**
  * API configuration for complex requests.
  */
@@ -168,8 +162,8 @@ export interface ActionDef {
      * field, because the 2026-08-06 maintainer ruling on objectstack#4075 gave
      * both keys ONE shape: `boolean | string(CEL) | { dialect, source }` —
      * "boolean = 条件的退化形字面量,string = CEL 简写,信封 = 完整形". The
-     * envelope arm arrived in `@objectstack/spec` 17.0.0-rc.6 (objectstack#5970,
-     * PR objectstack#6450); until then this was a hand-written `string | boolean`
+     * envelope arm arrived in `@objectstack/spec` 17.0.0-rc.6 (objectstack
+     * `97e7e3caa`); until then this was a hand-written `string | boolean`
      * that could not describe the envelope, which is why `DeclaredActionsBar`
      * read it through an `(action as any).disabled` cast. Derived, not restated,
      * so the two keys cannot drift apart again.
@@ -233,7 +227,8 @@ export interface ActionDef {
         showOnError?: boolean;
         duration?: number;
     };
-    /** Success message (from UIActionSchema) */
+    /** Success message (from UIActionSchema). The success toast's second rung,
+     *  after {@link outcomeMessages}; may interpolate `${result.*}`. */
     successMessage?: string;
     /** Error message (from UIActionSchema) */
     errorMessage?: string;
@@ -256,9 +251,9 @@ export interface ActionDef {
      * `'url'`, flow name for `'flow'`, modal/page for `'modal'`, endpoint for
      * `'api'`, FormView name for `'form'`.
      *
-     * The `execute` alias was REMOVED in @objectstack/spec 17 (#3855) and is not
-     * read here (#3856) — don't re-add it. Two handler slots is how one action ran
-     * one script server-side and a different one client-side (#3713).
+     * The `execute` alias was REMOVED in @objectstack/spec 17 (objectstack-ai/objectstack#3855) and is not
+     * read here (objectstack-ai/objectstack#3856) — don't re-add it. Two handler slots is how one action ran
+     * one script server-side and a different one client-side (objectstack-ai/objectstack#3713).
      */
     target?: string;
     /**
@@ -291,8 +286,6 @@ export interface ActionDef {
     chain?: ActionDef[];
     /** Chain execution mode */
     chainMode?: 'sequential' | 'parallel';
-    /** Callback on success */
-    onSuccess?: ActionDef | ActionDef[];
     /** Callback on failure */
     onFailure?: ActionDef | ActionDef[];
     /** When true, the runner pre-opens about:blank synchronously on click so the
@@ -323,7 +316,7 @@ export interface ActionDef {
      * spec 采纳 —— `visible` / `disabled` 两键在 spec 侧统一收敛为
      * `boolean | string(CEL) | {dialect, source}`(boolean = 条件的退化形字面量,
      * string = CEL 简写,信封 = 完整形)". `@objectstack/spec` 17.0.0-rc.6 carries
-     * it (objectstack#5970, PR objectstack#6450), so the local `| boolean` is no
+     * it (objectstack `97e7e3caa`), so the local `| boolean` is no
      * longer a tolerance to declare — it is part of the derived type, and adding
      * it back would restate a spec arm rather than widen anything.
      */
@@ -343,12 +336,42 @@ export interface ActionDef {
     objectName?: SpecActionInput['objectName'];
     /** AI affordance metadata (tool exposure, prompts). */
     ai?: SpecActionInput['ai'];
-    /** Accessibility overrides for the rendered control. */
-    aria?: SpecActionInput['aria'];
     /** Extra properties merged into the request body alongside the collected params. */
     bodyExtra?: SpecActionInput['bodyExtra'];
     /** How collected params are shaped into the request body (`flat` or nested). */
     bodyShape?: SpecActionInput['bodyShape'];
+    /**
+     * The declarative single-record field write — a parallel key BESIDE `type`,
+     * never a member of it.
+     *
+     * `ActionType` did not gain a member: the spec materializes `type: 'script'`
+     * on an `operation: 'update'` action, because the write is performed on the
+     * platform action route — `POST /api/v1/actions/{object}/{action}`, the route
+     * the registered `script` dispatch already posts — as the CALLER, so the
+     * caller's permissions, the object's hooks and its validations all fire as
+     * for a user edit. That is why {@link execute} reads this key BEFORE `type`:
+     * by the time `type` is consulted an update action is indistinguishable from
+     * any other script action, and it would run without the update path's Undo
+     * capture and its no-route refusal.
+     */
+    operation?: SpecActionInput['operation'];
+    /**
+     * For `operation: 'update'` — static field values written to the current
+     * record, merged UNDER the collected `params` so a fixed value can be
+     * declared without exposing it in the dialog. The spec refuses it on an
+     * action without `operation: 'update'`, where it would be silently dropped.
+     *
+     * The ROUTE applies it, from the declaration it resolves by name; this
+     * runner never sends it (objectui#12941) and reads it only to know which
+     * fields an Undo must restore.
+     *
+     * It is a DECLARATION's key here: a host that dispatches an object's action
+     * whole hands it along. No action renderer forwards a page row's own `patch`
+     * (objectui#13022, following `@objectstack/spec` 18's retirement of the row
+     * key), and the runner reads the host-published declaration ahead of this
+     * one (`declaredUpdatePatch`).
+     */
+    patch?: SpecActionInput['patch'];
     /** Execution mode of the action. */
     mode?: SpecActionInput['mode'];
     /** Field on the record supplying the record id sent to the endpoint. */
@@ -357,6 +380,41 @@ export interface ActionDef {
     recordIdParam?: SpecActionInput['recordIdParam'];
     /** Auth/tenancy feature the action requires before it is offered. */
     requiresFeature?: SpecActionInput['requiresFeature'];
+    /**
+     * Declared post-success navigation — the spec's closed strict
+     * `{ navigate, openIn }` block (`ActionSchema.onSuccess`, authorable since
+     * `@objectstack/spec` 17.1.0, objectui#5328). Read by `handlePostExecution`
+     * → `readOnSuccessNavigation` → `navigateOnSuccess`.
+     *
+     * This key carried a SECOND, older meaning until objectui#5934: the runner's
+     * own chained-callback channel, `ActionDef | ActionDef[]`, dispatched through
+     * `executeChain`. The maintainer retired that channel on 2026-08-31 — the
+     * spec strict-refuses a callback shape here (`{ type: … }` fails parse with
+     * `unrecognized_keys`, so no validated metadata could ever reach it), and the
+     * census found zero producers outside the channel's own pins. `onSuccess`
+     * now means exactly what the contract declares, nothing else; a callback
+     * shape gets NO reading (not a fallback, not an error — the same "a shape
+     * the spec refuses gets no new reading here" rule the discrimination branch
+     * used to apply, now with nothing left to discriminate). `onFailure`, in the
+     * runner-native section above, is untouched: the spec declares no such key,
+     * so it has only ever had its one runner-native meaning.
+     */
+    onSuccess?: SpecActionInput['onSuccess'];
+    /**
+     * Success copy per handler outcome (`ActionSchema.outcomeMessages`, ruling A
+     * on objectstack-ai/cloud#2315): the server answers with a closed `outcome`
+     * fact and this map holds the sentence for each, keyed by the snake_case
+     * outcome name. Read by `handlePostExecution` → `composeSuccessMessage`, the
+     * success toast's FIRST rung: the entry named by the payload's top-level
+     * `outcome` (the payload `${result.*}` reads), then {@link successMessage},
+     * then the runner's own default text.
+     *
+     * Derived, so an entry is an `I18nLabel` — a string or an inline per-locale
+     * map. The runner composes from strings only: the host's localizer
+     * (`useActionTextLocalizer` in `@object-ui/react`) resolves each entry to the
+     * active language before dispatch, because the runner has no language.
+     */
+    outcomeMessages?: SpecActionInput['outcomeMessages'];
     /**
      * @deprecated Retired in `@objectstack/spec` 17 as a `retiredKey()` tombstone —
      * authoring it is a hard parse rejection, so this resolves to `undefined` and
@@ -404,6 +462,11 @@ export type ActionRunnerHandler = (action: ActionDef, context: ActionContext) =>
  * `.cancel`), and `app-shell`'s `ActionConfirmDialog.tsx` renders them in
  * place of its generic `actionConfirm.*` fallbacks. Line numbers are left out
  * on purpose: #5205's pointer had already drifted by the time it was executed.
+ * The record delete is a second producer (objectui#11695): `app-shell`'s
+ * `useObjectActions` (the list's row and bulk Delete) and `RecordDetailView`
+ * (the record page's Delete) hand it `recordDelete.confirmCopy`'s title and
+ * confirm label with `destructive: true`, which paints the confirm button in
+ * the destructive button style.
  *
  * So re-measure across the repo, not this package: grep for two-argument
  * calls of `ConfirmationHandler`-typed values (`confirmHandler(`, `onConfirm(`)
@@ -417,6 +480,8 @@ export type ConfirmationHandler = (message: string, options?: {
     title?: string;
     confirmText?: string;
     cancelText?: string;
+    /** The confirmed action destroys data: paint the confirm button destructive. */
+    destructive?: boolean;
 }) => Promise<boolean>;
 /**
  * Toast handler — consumers can wire to Sonner or any toast library.
@@ -446,12 +511,58 @@ export type NavigationHandler = (url: string, options?: {
  * Param collection handler — consumers provide to show a dialog
  * for collecting ActionParam values before action execution.
  * Returns collected values, or null if cancelled.
+ *
+ * `interpolate` fills the `${...}` holes of the dialog's authored copy (the
+ * action's `description`, each param's `helpText`) in the same template scope
+ * the runner reads `confirmText` in — for a row dispatch, the row is `record`
+ * (see `templateEvaluatorFor`). The runner cannot fill them itself before the
+ * call: the handler localizes that copy AFTER it receives it (a translation
+ * bundle entry or an inline per-locale map), so the hole has to be filled on
+ * the text the user will actually read (objectui#12967).
+ *
+ * `run` lets the handler keep its dialog open until the run its values start
+ * has an outcome (objectui#13161). Called with the collected values, it
+ * dispatches the action with them and resolves with that run's
+ * {@link ActionResult} (a dispatch that throws resolves as a refused run, the
+ * way `execute` reports one). A refused run has already had its
+ * post-execution (the error toast, `onFailure`), so the handler can show the
+ * refusal beside the values the user typed and call `run` again with the
+ * edited values. A successful run's post-execution (success toast, result
+ * dialog, chain, `onSuccess`) waits until the handler settles its promise,
+ * so the dialog is closed before any of it shows. A call made while an
+ * earlier one is still in flight returns that earlier run, and dispatches
+ * nothing new.
+ *
+ * Once `run` has been called, the handler's own promise only ends the
+ * session: the runner never dispatches the values it resolves with. `null`
+ * after a refused run is a cancel, reported exactly as a cancel before any
+ * run. A handler that never calls `run` keeps the old contract: the runner
+ * dispatches once with the values it resolves.
+ */
+export type ParamCollectionHandler = (params: ActionParamDef[], action?: ActionDef, interpolate?: (text: string) => string, run?: (values: Record<string, any>) => Promise<ActionResult>) => Promise<Record<string, any> | null>;
+/**
+ * The contract's own result-dialog block, and one entry of its field list.
+ *
+ * ⭐ The two interfaces below DERIVE their label members from these instead of
+ * restating them, and that is the whole repair of `43c0d1710`: the three
+ * label members were hand-written `string` while the producer declares each as
+ * `I18nLabel` — a plain string **or** an inline per-locale map, both authorized
+ * and neither deprecated — so this mirror refused what the platform accepts
+ * while its own docblock claimed the alignment. A hand copy can drift again the
+ * moment the contract moves; a derived member makes `tsc` re-check the claim on
+ * every build instead of trusting a sentence written once.
+ *
+ * ⛔ Local, deliberately not exported: the two interfaces below stay the only
+ * names this module publishes for the block.
  */
-export type ParamCollectionHandler = (params: ActionParamDef[], action?: ActionDef) => Promise<Record<string, any> | null>;
+type SpecResultDialog = NonNullable<SpecActionInput['resultDialog']>;
+type SpecResultDialogField = NonNullable<SpecResultDialog['fields']>[number];
 /**
  * Result dialog spec — declarative description of how to render a
  * one-shot reveal of an action's API response. Mirrors
- * `Action.resultDialog` in @objectstack/spec.
+ * `Action.resultDialog` in @objectstack/spec — derived from it member by
+ * member for the labels, so the claim in this sentence is enforced rather
+ * than asserted.
  *
  * When set on an action and the action succeeds, the runner suppresses
  * the success toast and awaits a ResultDialogHandler instead. Used for
@@ -460,13 +571,22 @@ export type ParamCollectionHandler = (params: ActionParamDef[], action?: ActionD
  */
 export interface ResultDialogFieldSpec {
     path: string;
-    label?: string;
+    /**
+     * Derived `I18nLabel` — a plain string, or an inline per-locale map. A
+     * renderer must RESOLVE it (`resolveI18nLabel` in `@objectstack/spec/ui`)
+     * before it reaches the DOM; passed through as-is, the map arm is an object
+     * and React refuses an object as a child.
+     */
+    label?: SpecResultDialogField['label'];
     format?: 'qrcode' | 'code-list' | 'secret' | 'text' | 'json';
 }
 export interface ResultDialogSpec {
-    title?: string;
-    description?: string;
-    acknowledge?: string;
+    /** Derived `I18nLabel` — see `ResultDialogFieldSpec.label` on resolving it. */
+    title?: SpecResultDialog['title'];
+    /** Derived `I18nLabel` — see `ResultDialogFieldSpec.label` on resolving it. */
+    description?: SpecResultDialog['description'];
+    /** Derived `I18nLabel` — see `ResultDialogFieldSpec.label` on resolving it. */
+    acknowledge?: SpecResultDialog['acknowledge'];
     format?: 'qrcode' | 'code-list' | 'secret' | 'text' | 'json';
     fields?: ResultDialogFieldSpec[];
 }
@@ -486,7 +606,7 @@ export type ResultDialogHandler = (spec: ResultDialogSpec, data: unknown, action
  * `visibleWhen` (the CEL predicate `resolveVisibleOptions()` filters on —
  * ADR-0058 / #2284), `color`, `icon`, `disabled`.
  *
- * The catch-all is deliberate rather than a closed key list (objectui#3559).
+ * The catch-all is deliberate rather than a closed key list (`fbc23e094`).
  * A field's option vocabulary is owned by the field metadata (`@objectstack/spec`'s
  * `SelectOptionSchema`) and read by the option widgets; a param's option list is
  * only a CONDUIT between the two. When this type restated that vocabulary as
@@ -530,19 +650,36 @@ export interface ActionParamDef {
     placeholder?: string;
     /**
      * Visibility predicate (CEL) evaluated against the same scope as action
-     * `visible` (`current_user` / `app` / `data` / `features`). When it evaluates
+     * `visible` (`current_user` / `data` / `features` — ⛔ not `app`, unbound by
+     * objectui#8155). When it evaluates
      * false the param dialog omits this param — used to hide a param the backend
      * only accepts under an opt-in capability (e.g. `create_user.phoneNumber`
      * gated on `features.phoneNumber`). Absent = always visible.
      */
     visible?: string;
+    /**
+     * Carry-over declaration — `@objectstack/spec`'s `ActionParamSchema.carryOver`
+     * (the 2026-08-25 ruling whose spec half is objectstack `0e4e51b0a`,
+     * objectui#6246), passed through unchanged by
+     * `resolveActionParams()`. The param's value is carried through the dialog
+     * rather than collected from the user: seeded from the row (the spec refuses
+     * the key without `defaultFromRow: true`), rendered by `ActionParamDialog` as
+     * a collapsed read-only summary with no editing affordance, and submitted
+     * verbatim.
+     *
+     * ⛔ Not a styling hint. The permission-set Clone action declares it on its
+     * JSON permission facets because an editable facet lets a hand-edited but
+     * valid blob clone a set that grants MORE than its base; a renderer that
+     * merely greys the control out still offers that edit.
+     */
+    carryOver?: boolean;
     /** Accepted upload types (MIME types / extensions) for `file`/`image` params. */
     accept?: string[];
     /** Max upload size in bytes for `file`/`image` params. */
     maxSize?: number;
     /** Allow multiple values (file/image/lookup/user params → array value). */
     multiple?: boolean;
-    /** Object name the lookup picker queries (`reference_to` on the field). */
+    /** Object name the lookup picker queries (`reference` on the field). */
     referenceTo?: string;
     /** Field on the referenced record used as the human label (default `name`). */
     displayField?: string;
@@ -560,7 +697,87 @@ export interface ActionParamDef {
     lookupPageSize?: number;
     /** Form-field dependencies that gate / parameterise the picker query. */
     dependsOn?: unknown[];
+    /**
+     * Set by `resolveActionParams()` when a FIELD-BACKED param (`{ field }`)
+     * named a field that is not in the object metadata the resolver was given,
+     * carrying `<object>.<field>` — the pair that could not be resolved.
+     *
+     * It exists because the alternative is a SILENT one. Without it the resolver
+     * hands back `type: param.type ?? 'text'`, and every downstream reader of the
+     * degradation is blind to it: the param is a `text` param by then, so
+     * `paramDegradesWithoutTarget()` answers false, `paramToField()` emits no
+     * "no reference target" warning, and the objectstack-ai/objectstack#3405 "paste a record id" hints do
+     * not apply either. A lookup param that should have rendered a record picker
+     * renders an unannotated empty box instead — no options, no dropdown, and no
+     * request for the referenced object on the wire, because no picker was ever
+     * built (`6cc910b6d`).
+     *
+     * ⛔ It is not a widget config key and `paramToField()` deliberately does not
+     * map it: the whole point is that the param's type is UNKNOWN, so there is no
+     * widget to configure. `ActionParamDialog` reads it and refuses.
+     */
+    unresolvedField?: string;
 }
+/**
+ * The fields an `operation: 'update'` action writes, and their prior values.
+ *
+ * `undoable` promises to restore EXACTLY the fields the action wrote, so the
+ * captured set is the effective payload — `patch` merged under the collected
+ * `params` — and never `patch` alone: a param-collected field left out of the
+ * capture would make Undo restore SOME of the edit and report a full one, which
+ * is worse than offering no Undo at all.
+ *
+ * Prior values come from the row record the invoking surface stashed under
+ * `params._rowRecord` (the same client-side stash the record-id dance reads).
+ * A field the row carries as `null` is captured as `null`: it was empty, and
+ * clearing it back to empty is what restoring it means on the data plane.
+ *
+ * ⛔ A field the row does not CARRY is never captured as `null`
+ * (objectui#10404). Absent is not empty: a list row is projected by `$select`,
+ * and a written field no column shows is missing from the row while the server
+ * holds a real value for it. Recording `null` there made Undo write `null` over
+ * the value it existed to restore. The list harvest (`listViewPredicates`) now
+ * asks for the written fields of an `undoable` action, so a projected row
+ * carries them; this is the backstop for the ones it cannot ask for (a field
+ * the object does not declare or the principal may not read, a row no harvest
+ * shaped). "Carries" means an own key whose value is not `undefined`: JSON
+ * cannot send `undefined`, so such a value says nothing about what is stored.
+ *
+ * Answers `undefined` when any written field is not carried, and the caller
+ * then offers no Undo at all. Capturing only the carried fields is not an
+ * option, for the reason above: a partial restore reported as a full one is
+ * worse than no Undo.
+ *
+ * ⛔ A relation's prior value is its STORED id, never the record `$expand`
+ * put in its place (objectui#11122). Surfaces read rows with `$expand` on the
+ * relations they show (a grid, its visible and grouping columns; the record
+ * page, every relation the reader may read), and the server replaces the id
+ * in place with the related record. Copied verbatim, that record became the
+ * Undo value and Undo wrote it into the reference slot, which stores an id:
+ * refused under a strict value-shape posture, stored as corruption under the
+ * lenient one. So each carried value goes through `toPredicateRecord`, the one
+ * rule that binds a fetched record the way the server stores it: a field the
+ * object DECLARES relational (`EXPANDABLE_FIELD_TYPES`, the set that decides
+ * what is expanded in the first place) collapses to its id, element-wise for a
+ * `multiple` relation, and every other field is left exactly as the row
+ * carries it. It is read from `fields`, never from the value's shape: a `json`
+ * field may hold an object with an `id`, and that object is its stored value.
+ *
+ * `fields` is the written object's field definitions (`objectSchema.fields`,
+ * either served shape), and it is REQUIRED so that a caller without them has
+ * to say so: `undefined` collapses nothing, because a caller that cannot name
+ * the relations must not guess them.
+ *
+ * Exported (objectui#11082) because it is THE rule, not this runner's: every
+ * surface that builds an `update` Undo snapshot itself calls it rather than
+ * restating it. Today that is the console runtime's `api` handler
+ * (`useConsoleActionRuntime`) and the record page's own `api` handler
+ * (`RecordDetailView`), which reads prior values off the page's loaded record;
+ * that record lacks a written field when field-level security hides it from
+ * the reader. To name the fields that blocked a capture, ask per field:
+ * `captureUpdateUndoData([field], rowRecord, fields) === undefined`.
+ */
+export declare function captureUpdateUndoData(writtenFields: readonly string[], rowRecord: Record<string, unknown>, fields: FieldContainerLike): Record<string, unknown> | undefined;
 export declare class ActionRunner {
     private handlers;
     private scripts;
@@ -572,6 +789,7 @@ export declare class ActionRunner {
     private navigationHandler;
     private paramCollectionHandler;
     private resultDialogHandler;
+    private translate;
     /**
      * Built-in dispatch, one entry per runnable action type.
      *
@@ -588,6 +806,20 @@ export declare class ActionRunner {
      */
     private readonly builtinExecutors;
     constructor(context?: ActionContext);
+    /**
+     * Set the translator for the text the runner supplies itself — the host's
+     * `t`, injected so this package takes no i18n dependency. That text is the
+     * `RUNNER_TEXT` table in this file: the generic success toast shown when an
+     * action declares neither an `outcomeMessages` entry for the answer nor a
+     * `successMessage`, the error fallbacks when no readable error message
+     * reached the runner, and the Undo label of an undoable success toast. An
+     * author's `outcomeMessages` / `successMessage` / `errorMessage` and an
+     * action's own error never go through this translator: the host localizes
+     * authored copy before dispatch. With no translator the text stays English.
+     */
+    setTranslator(translate: (key: string, options: {
+        defaultValue: string;
+    }) => string): void;
     /**
      * Set a custom confirmation handler (e.g., Shadcn AlertDialog).
      */
@@ -625,11 +857,72 @@ export declare class ActionRunner {
      */
     registerScript(scriptName: string, handler: ActionRunnerHandler): void;
     unregisterScript(scriptName: string): void;
-    execute(action: ActionDef): Promise<ActionResult>;
+    /**
+     * Run `action`; with `callContext`, run it against that context for this
+     * one dispatch (objectui#13063).
+     *
+     * The runner's context names the PAGE: its `record` and its `objectName`.
+     * A dispatch that runs against some other record, such as a related-list
+     * row on a record page, which is a record of the CHILD object, hands that
+     * record here as `{ record, objectName }`. Every executor then reads it as
+     * the record the action runs against, the way a dispatch from that record's
+     * own page does: `executeForm` forwards its id and object, and its
+     * boundary check compares the target view against the child object instead
+     * of the page's.
+     *
+     * The runner's own context is not touched: the dispatch runs on a one-shot
+     * runner over the merged context that shares this runner's handlers (see
+     * {@link ActionRunner.scopedTo}).
+     */
+    execute(action: ActionDef, callContext?: Partial<ActionContext>): Promise<ActionResult>;
+    /**
+     * Dispatch an action whose params are collected, and answer what it
+     * returned — WITHOUT post-execution, which each caller runs itself:
+     * `execute` right after a lone run, and the param-collection session
+     * (`ParamCollectionHandler`'s `run`, objectui#13161) once per refused attempt
+     * and once for the successful one when the session ends.
+     */
+    private dispatchCollected;
     /**
      * Execute multiple actions in sequence or parallel.
      */
     executeChain(actions: ActionDef[], mode?: 'sequential' | 'parallel'): Promise<ActionResult>;
+    /**
+     * One entry of `RUNNER_TEXT`, in the installed translator's language. An
+     * empty answer from the translator falls back to the English source rather
+     * than raising an empty toast or an empty label.
+     */
+    private runnerText;
+    /**
+     * The success toast's text, by the contract's three rungs
+     * (`ActionSchema.outcomeMessages`, objectui#11344):
+     *
+     * 1. `outcomeMessages[outcome]`, where `outcome` is the top-level `outcome`
+     *    of the handler's return value — the payload `${result.*}` reads, so it
+     *    is the same fact an author writes as `${result.outcome}`;
+     * 2. `successMessage`;
+     * 3. the runner's own default text, in its translator's language.
+     *
+     * Rungs 1 and 2 are the author's copy. Both arrive already localized — the
+     * host's localizer resolves the bundle entry or the inline `I18nLabel` map
+     * before dispatch — and both have their `${result.*}` tokens filled in here,
+     * through the one token grammar and scope `onSuccess.navigate` reads
+     * (`substituteScopeTokens` over `readActionPayload(result.data)`). Only the
+     * sink differs: a toast is text, so a value is inserted as-is, where a URL
+     * position percent-encodes it.
+     *
+     * ⛔ `result.data.message` is not a rung. It used to outrank both rungs of
+     * author copy, which put whatever language the server happened to write in
+     * front of the user's locale; the contract names no server-message rung, and
+     * an author who wants the server's sentence can still write
+     * `${result.message}` as the copy.
+     *
+     * A rung counts only when it is a non-empty string. An `I18nLabel` map that
+     * reached the runner without passing through a localizer has no language to
+     * resolve against here, so it is skipped rather than handed to the toast as
+     * an object — the React #31 crash the error branch below guards against.
+     */
+    private composeSuccessMessage;
     /**
      * Post-execution: emit toast notifications, handle chaining, callbacks.
      */
@@ -642,7 +935,9 @@ export declare class ActionRunner {
      * react-router's `navigate` — so `openIn: 'self'` is a real SPA route hop,
      * in place, immune to popup blocking. No `window.location` / `window.open`
      * mechanism is introduced here; the no-handler fallback is the same
-     * `result.redirect` hand-off `navigateTo` already uses.
+     * `result.redirect` hand-off `navigateTo` already uses. The one exception is
+     * shared with `navigateTo`: a `mailto:` target is not a route, so it is a
+     * full-page navigation in place (objectui#12191).
      *
      * **No default is written here.** `openIn` is a materialised
      * `.default('self')` in the spec, so parse output always carries a resolved
@@ -658,6 +953,59 @@ export declare class ActionRunner {
      * one authors are validated against.
      */
     private navigateOnSuccess;
+    /**
+     * `operation: 'update'` — the declarative single-record field write.
+     *
+     * ## The write is the ROUTE's, never this client's
+     *
+     * This method composes a request and hands it to the registered `script`
+     * dispatch; it does not touch a `DataSource`. That is a security boundary,
+     * not an implementation preference. `POST /api/v1/actions/{object}/{action}`
+     * runs the write AS THE CALLER — the caller's permissions, the object's hooks
+     * and its validations all fire as for a user edit — while a client-side
+     * `dataSource.update()` reaches the data plane having consulted none of them.
+     * The spec says the same thing from its end by refusing `target`, `body`,
+     * `method` and `bodyExtra` beside this key and pinning `type` to `'script'`:
+     * there is exactly one execution surface for an update action, and it is the
+     * route.
+     *
+     * Consequently, a consumer that has registered NO server-action dispatch gets
+     * a loud refusal naming the remedy. The two silent alternatives were both
+     * available and both wrong: falling through to `executeScript` ends at "No
+     * script provided" (an update action declares no `target` — the author is
+     * sent hunting for a field they were right not to write), and falling through
+     * to `executeActionSchema` reports on an action that never ran.
+     *
+     * ## `patch` is the route's: it never rides on the wire (objectui#12941)
+     *
+     * The request carries the values collected for the action's declared
+     * `params`, plus the transport keys the dispatch reads (`recordId`, and the
+     * `_rowRecord` stash it strips before POSTing) — and NOTHING from `patch`.
+     * The route applies the declared `patch` itself, from the declaration it
+     * resolves by the action's name (`@objectstack/runtime`'s
+     * `declarativeUpdateWrite`, which writes `{ ...patch, ...params }`). The
+     * patch keys are not params the action declares, so posting them makes every
+     * declarative-update button a request carrying undeclared params — the very
+     * request the ADR-0104 D2 param contract refuses (objectstack#24268). A
+     * client copy of `patch` on the wire also adds nothing: the server never
+     * reads it.
+     *
+     * The spec's words for the merge the route performs: static field values
+     * "merged UNDER the user-supplied `params` so a fixed value can be declared
+     * without exposing it in the dialog". So a collected param of the same name
+     * WINS — the author declared a default, and the user answered it. This
+     * runner still computes that same merge, but only to know what the route
+     * WROTE, which is what an Undo snapshot must cover; it is never sent.
+     *
+     * ## The `patch` in that merge is the DECLARATION's (objectui#13022)
+     *
+     * The route writes the `patch` of the declaration the action's `name` names,
+     * so that is the `patch` the snapshot covers: read by
+     * {@link declaredUpdatePatch} from the declarations the host published, else
+     * off a def that is the declaration itself. A page action row's own `patch`
+     * is never written (`@objectstack/spec` 18 retires it) and never covered.
+     */
+    private executeUpdateOperation;
     /**
      * Execute script action — evaluates client-side expression via ExpressionEvaluator.
      * Supports ${} template expressions referencing data, record, user context.
@@ -668,6 +1016,24 @@ export declare class ActionRunner {
      * Uses navigationHandler for SPA routing, falls back to window.location.
      */
     private executeUrl;
+    /**
+     * A navigation announces nothing unless its action declares the copy
+     * (objectui#12755).
+     *
+     * `type: 'url'`, its `navigation` alias and `type: 'form'` only change the
+     * route: nothing was written, so there is nothing to confirm. Their
+     * `{ success: true }` used to reach `handlePostExecution` like a write's, and
+     * the generic `completedSuccessfully` toast ("操作已成功完成") told the user an
+     * operation had completed when a page had merely opened (objectstack-ai/cloud#2909:
+     * an "invite member" button that only navigated read as "invitation sent").
+     *
+     * The result keeps `success: true` (callers read it as "the navigation
+     * happened") and is marked `silent`, the flag that already means "no success
+     * toast for this result". An author who wants a toast after the navigation
+     * declares `successMessage`, and that copy still shows: the declaration is the
+     * only signal, so there is no separate switch to forget.
+     */
+    private announceNavigation;
     /**
      * The one navigator behind `type: 'url'` and its `navigation` alias.
      *
@@ -772,7 +1138,7 @@ export declare class ActionRunner {
      * 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
+     * objectstack-ai/objectstack#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
@@ -792,10 +1158,6 @@ export declare class ActionRunner {
      * Execute API action — supports both simple string endpoint and complex ApiConfig.
      */
     private executeAPI;
-    /**
-     * Validate URL to prevent javascript: or data: protocol injection.
-     */
-    private isValidUrl;
     /**
      * Substitute `${param.X}` and `${ctx.X}` tokens in an action target.
      *
@@ -830,8 +1192,51 @@ export declare class ActionRunner {
      * placed under context.ctx is merged on top.
      */
     private buildInterpolationContext;
+    /**
+     * The evaluator a dispatch's authored copy is read through: `confirmText`,
+     * and the param dialog's `description` / `helpText` via the handler's
+     * `interpolate` argument.
+     *
+     * One rule for every door (objectui#12967): the record the action runs
+     * against is `record`. The record header binds it in the runner's context
+     * (`RecordDetailView`'s `ActionProvider`). A row surface does not — it
+     * stashes the clicked row under `params._rowRecord` (ObjectGrid's row
+     * actions, a related list's row actions, `DeclaredActionsBar`, a page
+     * header, `action:button`'s update write) and fires through the shared
+     * runner, whose context names the page, not the row. So when the dispatch
+     * carries a row, the row is bound as `record` for this dispatch's templates,
+     * and it wins over a page-level `record` (a related-list row on a record page
+     * is the child, not the page's record). Nothing else in the scope changes,
+     * and the runner's own context is not touched.
+     *
+     * A hole naming a field the record does not carry degrades the way the
+     * header's always has: the evaluator reads `undefined` and the hole prints
+     * empty.
+     */
+    private templateEvaluatorFor;
     updateContext(newContext: Partial<ActionContext>): void;
     getContext(): ActionContext;
+    /**
+     * A one-shot runner for {@link ActionRunner.execute}'s `callContext`
+     * (objectui#13063): this runner's context with `callContext` merged over it,
+     * and this runner's handlers, translator and registries, shared rather than
+     * copied, so the dispatch confirms, collects params, toasts and navigates
+     * exactly as this runner does.
+     *
+     * Two keys follow the merge rather than the base:
+     *
+     *  - `ctx`, the `ctx.*` mirror `ActionProvider` publishes beside the flat
+     *    keys. A `${ctx.record.…}` hole has to read the same record as a
+     *    `${record.…}` one.
+     *  - `objectFields` / `objectActions`. A host publishes them BESIDE
+     *    `objectName`, so the pair names one object (objectui#11122,
+     *    objectui#13022). When `callContext` names another object and brings no
+     *    definitions of its own, the base's are dropped: the page object's field
+     *    types and declarations must not answer for the child's record. That is
+     *    what a dispatch with no `callContext` already gets for a retargeted
+     *    action, so the update path's capture sees the same input either way.
+     */
+    private scopedTo;
     /**
      * Get the expression evaluator (for components that need to evaluate visibility, etc.)
      */
@@ -848,14 +1253,13 @@ export interface OnSuccessNavigation {
     openIn?: unknown;
 }
 /**
- * Is this `onSuccess` the SPEC's navigation block, or this runner's older
- * chained-callback channel (`ActionDef | ActionDef[]`)?
+ * Is this `onSuccess` the spec's navigation block?
  *
  * The test IS the spec's declaration: a non-array object carrying a STRING
- * `navigate`. Nothing else can produce that shape — the spec object is strict
- * with `navigate: z.string()` required, and on a callback `ActionDef`,
- * `navigate` is the deprecated nested navigation ENVELOPE that
- * `executeNavigation` reads `to`/`target`/`redirect` off, so a bare string
- * there has never been runnable.
+ * `navigate`. Stored rows are rehydrated UNPARSED (objectstack-ai/objectstack#3903), so the runner reads
+ * the value as data and anything else gets NO reading — since objectui#5934
+ * retired the legacy chained-callback channel (`ActionDef | ActionDef[]`),
+ * there is no other channel for an off-contract shape to fall into. This is a
+ * shape GUARD on unparsed data, not a discriminator between two meanings.
  */
 export declare function readOnSuccessNavigation(value: unknown): OnSuccessNavigation | null;