@object-ui/core 17.1.0 → 17.2.0

package/dist/actions/ActionRunner.d.ts

@@ -5,6 +5,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+import type { ActionInput as SpecActionInput } from '@objectstack/spec/ui';
 import { ExpressionEvaluator } from '../evaluator/ExpressionEvaluator';
 import { type UndoableOperation } from './UndoManager';
 export interface ActionResult {
@@ -65,7 +66,12 @@ export interface ActionDef {
     /** Action type identifier — a `RunnableActionType` (the spec's six plus the
      *  `navigation` alias of `url`) or a custom type with a registered handler. */
     type?: string;
-    /** Legacy action type field */
+    /**
+     * Legacy action type field.
+     *
+     * @deprecated objectui dialect — use the spec spelling `type`. Both are read,
+     * `type` first (objectstack#4075 step 2).
+     */
     actionType?: string;
     /** Action name (from UIActionSchema) */
     name?: string;
@@ -84,13 +90,36 @@ export interface ActionDef {
     condition?: string;
     /** Disabled expression — if truthy, skip action */
     disabled?: string | boolean;
-    /** API endpoint (string URL or complex config) */
+    /**
+     * API endpoint (string URL or complex config).
+     *
+     * @deprecated objectui dialect — the spec spells an `api` action's endpoint
+     * `target` (with the verb in `method`). `executeAPI` resolves
+     * `api || endpoint || target`, so `target` alone is sufficient. The
+     * `ApiConfig` object form has no spec counterpart and is objectui-only
+     * (objectstack#4075 step 2).
+     */
     api?: string | ApiConfig;
-    /** API endpoint URL (spec v2.0.1 alias) */
+    /**
+     * API endpoint URL.
+     *
+     * @deprecated objectui dialect — this was the "spec v2.0.1 alias", but spec 17
+     * spells it `target`. `executeAPI` resolves `api || endpoint || target`
+     * (objectstack#4075 step 2).
+     */
     endpoint?: string;
     /** HTTP method */
     method?: string;
-    /** Navigation target */
+    /**
+     * Navigation target — a nested envelope carrying the `navigation` alias's own
+     * spelling (`to` / `external` / `newTab` / `replace`).
+     *
+     * @deprecated objectui dialect — the spec has no nested navigation envelope;
+     * it spells a navigation action `{ type: 'url', target, openIn }`.
+     * `executeNavigation` reads `navigate.to || navigate.target || navigate.redirect`,
+     * falling back to the same keys on the action itself, so a flat `target` works
+     * today (objectstack#4075 step 2).
+     */
     navigate?: any;
     /** onClick callback (legacy) */
     onClick?: () => void | Promise<void>;
@@ -177,10 +206,82 @@ export interface ActionDef {
      *  must perform all auth/authz itself (e.g. the cloud `/sso-open` endpoint,
      *  which re-runs every check the POST half would have done). */
     newTabUrl?: string;
+    /** Where this action renders (`record_header`, `list_toolbar`, …). Read by
+     *  `ActionEngine.registerActions` to seed the location filter. */
+    locations?: SpecActionInput['locations'];
+    /**
+     * Visibility predicate, evaluated against the runner's context.
+     *
+     * The `boolean` arm is objectui's own, deliberately wider than the spec:
+     * `ActionSchema.visible` admits only a CEL string or a `{ dialect, source }`
+     * envelope, while `ActionEngine.getActionsForLocation` also honours a literal
+     * `visible: true` / `false` (pinned by `ActionEngine.visibility.test.ts`).
+     * Declared rather than left to the index signature so the tolerance is
+     * auditable instead of invisible — but it IS a dialect, and objectstack#4075
+     * step 3 has to decide whether the spec adopts the boolean or objectui drops
+     * it. Do not widen this further.
+     */
+    visible?: SpecActionInput['visible'] | boolean;
+    /** System permissions the caller must ALL hold for the action to be offered
+     *  (ADR-0066 D4 UI half — the server enforces the source of truth). */
+    requiredPermissions?: SpecActionInput['requiredPermissions'];
+    /** Icon name for the rendered control. */
+    icon?: SpecActionInput['icon'];
+    /** Visual emphasis of the rendered control (`primary`, `danger`, …). */
+    variant?: SpecActionInput['variant'];
+    /** Sort weight among sibling actions. */
+    order?: SpecActionInput['order'];
+    /** Which renderer surfaces the action (`action:button`, `action:menu`, …). */
+    component?: SpecActionInput['component'];
+    /** Object this action is declared against. */
+    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'];
+    /** Execution mode of the action. */
+    mode?: SpecActionInput['mode'];
+    /** Field on the record supplying the record id sent to the endpoint. */
+    recordIdField?: SpecActionInput['recordIdField'];
+    /** Request-parameter name carrying the record id. */
+    recordIdParam?: SpecActionInput['recordIdParam'];
+    /** Auth/tenancy feature the action requires before it is offered. */
+    requiresFeature?: SpecActionInput['requiresFeature'];
+    /**
+     * @deprecated Retired in `@objectstack/spec` 17 as a `retiredKey()` tombstone —
+     * authoring it is a hard parse rejection, so this resolves to `undefined` and
+     * assigning a value is a compile error. A HOST may still pass a shortcut
+     * explicitly via `ActionEngine.registerAction(action, { shortcut })`; it is
+     * only no longer sourced from authored metadata. No replacement key.
+     */
+    shortcut?: SpecActionInput['shortcut'];
+    /**
+     * @deprecated Retired in `@objectstack/spec` 17 as a `retiredKey()` tombstone —
+     * authoring it is a hard parse rejection, so this resolves to `undefined` and
+     * assigning a value is a compile error. Use the list view's `bulkActions` /
+     * `bulkActionDefs` instead; `ActionEngine.registerAction(action, { bulkEnabled })`
+     * remains available to a HOST passing it explicitly.
+     */
+    bulkEnabled?: SpecActionInput['bulkEnabled'];
     /** Any additional properties */
     [key: string]: any;
 }
-export type ActionHandler = (action: ActionDef, context: ActionContext) => Promise<ActionResult> | ActionResult;
+/**
+ * A handler registered with {@link ActionRunner} — the client-side action
+ * dispatch seam: given an authored `ActionDef` and the invocation context,
+ * produce an `ActionResult`.
+ *
+ * NOT the spec's `ActionHandler` (`@objectstack/spec/ui`), whose name this type
+ * carried until objectstack#4115. That one is the SERVER-side objectql action
+ * handler — a different calling convention entirely (`(ctx) => unknown`, with
+ * validated params and a trusted engine facade on `ctx`) and a different
+ * execution site.
+ */
+export type ActionRunnerHandler = (action: ActionDef, context: ActionContext) => Promise<ActionResult> | ActionResult;
 /**
  * Confirmation handler — replaces window.confirm.
  * Consumers can provide an async implementation (e.g., Shadcn AlertDialog).
@@ -353,7 +454,7 @@ export declare class ActionRunner {
      * values the user must copy now (2FA codes, OAuth client_secret).
      */
     setResultDialogHandler(handler: ResultDialogHandler): void;
-    registerHandler(actionName: string, handler: ActionHandler): void;
+    registerHandler(actionName: string, handler: ActionRunnerHandler): void;
     unregisterHandler(actionName: string): void;
     /**
      * Register a named script handler. When a `script` action's
@@ -361,7 +462,7 @@ export declare class ActionRunner {
      * instead of the expression evaluator. Lets dashboards/views wire
      * symbolic action names (e.g. 'export_dashboard_pdf') to JS callbacks.
      */
-    registerScript(scriptName: string, handler: ActionHandler): void;
+    registerScript(scriptName: string, handler: ActionRunnerHandler): void;
     unregisterScript(scriptName: string): void;
     execute(action: ActionDef): Promise<ActionResult>;
     /**
@@ -467,9 +568,15 @@ export declare class ActionRunner {
      * fragment.
      *
      * `ctx.origin`, `ctx.user.*`, `ctx.org.*`, `ctx.recordId` are surfaced
-     * implicitly from the runner's ActionContext + window. Consumers can
-     * extend by stuffing extra keys under `context.ctx = {...}` before
-     * calling `runner.execute()`.
+     * implicitly from the runner's ActionContext + window, and
+     * `ctx.selection.ids` / `ctx.selection.count` reflect the grid's current
+     * checkbox selection (`context.selectedRecords`) — `${ctx.selection.ids}`
+     * comma-joins the ids via the standard `String(array)` behaviour, so a
+     * list_toolbar url/api action can carry the selection without any bulk
+     * plumbing (objectui#3139). In an aggregate bulk dispatch,
+     * `${param._selectedIds}` interpolates the same ids from the injected
+     * param. Consumers can extend by stuffing extra keys under
+     * `context.ctx = {...}` before calling `runner.execute()`.
      */
     private interpolateTarget;
     /**

package/dist/actions/ActionRunner.js

@@ -802,9 +802,15 @@ export class ActionRunner {
      * fragment.
      *
      * `ctx.origin`, `ctx.user.*`, `ctx.org.*`, `ctx.recordId` are surfaced
-     * implicitly from the runner's ActionContext + window. Consumers can
-     * extend by stuffing extra keys under `context.ctx = {...}` before
-     * calling `runner.execute()`.
+     * implicitly from the runner's ActionContext + window, and
+     * `ctx.selection.ids` / `ctx.selection.count` reflect the grid's current
+     * checkbox selection (`context.selectedRecords`) — `${ctx.selection.ids}`
+     * comma-joins the ids via the standard `String(array)` behaviour, so a
+     * list_toolbar url/api action can carry the selection without any bulk
+     * plumbing (objectui#3139). In an aggregate bulk dispatch,
+     * `${param._selectedIds}` interpolates the same ids from the injected
+     * param. Consumers can extend by stuffing extra keys under
+     * `context.ctx = {...}` before calling `runner.execute()`.
      */
     interpolateTarget(target, action) {
         if (typeof target !== 'string' || target.indexOf('${') === -1)
@@ -839,6 +845,22 @@ export class ActionRunner {
             user: this.context.user ?? {},
             org: this.context.org ?? this.context.organization ?? {},
             recordId: this.context.record?.id ?? this.context.recordId,
+            // Current list selection (published by the grid as `selectedRecords`).
+            // `${ctx.selection.ids}` in a url/api target comma-joins the ids —
+            // String(array) — giving toolbar actions selection access without any
+            // bulk-executor involvement (objectui#3139). Empty when nothing is
+            // selected, so authors can treat "" as "no selection".
+            selection: {
+                ids: Array.isArray(this.context.selectedRecords)
+                    ? this.context.selectedRecords
+                        .map((r) => r?.id)
+                        .filter((v) => v != null)
+                        .map(String)
+                    : [],
+                count: Array.isArray(this.context.selectedRecords)
+                    ? this.context.selectedRecords.length
+                    : 0,
+            },
         };
         if (this.context.ctx && typeof this.context.ctx === 'object') {
             Object.assign(ctx, this.context.ctx);

package/dist/actions/actionKeys.d.ts

@@ -32,25 +32,42 @@
  * interface it mirrors would be the same "declared ≠ enforced" trap this whole
  * thread is about.
  *
- * ── What the inventory found, i.e. step 2's worklist ─────────────────────────
- * `ActionDef` declares 34 keys, the spec's `ActionSchema` declares 36, and they
- * overlap on 17. The two halves of the difference are different problems:
+ * ── What the inventory found, and what step 2 did with it ────────────────────
+ * Step 1 found `ActionDef` declaring 34 keys against the spec `ActionSchema`'s
+ * 36, overlapping on 17. The two halves of the difference were different
+ * problems, and step 2 (objectstack#4075) treated them differently:
  *
  * 18 keys the SPEC owns that `ActionDef` never declared — `ai`, `aria`,
  * `bodyExtra`, `bodyShape`, `bulkEnabled`, `component`, `icon`, `locations`,
  * `mode`, `objectName`, `order`, `recordIdField`, `recordIdParam`,
  * `requiredPermissions`, `requiresFeature`, `shortcut`, `variant`, `visible`.
- * These are authored today and reach readers through the index signature.
- * `ActionEngine` reads two of them (`visible` at the location filter, `locations`
- * at registration) through an `as any` cast — a cast that exists ONLY because the
- * field is undeclared, and that goes away when step 2 promotes them.
+ * These are authored today and used to reach readers through the index
+ * signature. **Step 2 promoted all 18 to explicit optional fields**, typed by
+ * DERIVATION from `@objectstack/spec`'s `ActionInput` rather than by hand-copied
+ * shapes. The `as any` casts `ActionEngine` needed to read `visible`,
+ * `locations` and `requiredPermissions` are gone with them — those casts existed
+ * only because the fields were undeclared.
+ *
+ * Two of the 18 landed as `undefined` rather than as usable types, which is the
+ * correct outcome: spec 17 retired `shortcut` and `bulkEnabled` as `retiredKey()`
+ * tombstones (`z.never()`), so deriving turns "authoring this is a parse
+ * rejection" into a compile error at no cost. Hand-copying would have quietly
+ * re-legitimized two dead keys — which is why the types are derived.
  *
  * 17 keys `ActionDef` declares that the spec does not own — `actionType`, `api`,
  * `chain`, `chainMode`, `close`, `condition`, `confirm`, `endpoint`, `modal`,
  * `navigate`, `onClick`, `onFailure`, `onSuccess`, `redirect`, `reload`, `toast`,
- * `actionParams`. Several are already marked legacy at their declaration. These
- * are objectui's own dialect and need the #4115 treatment: kept and documented as
- * deliberate, or retired — but not silently carried.
+ * `actionParams`. Step 2 marked `@deprecated`, with the spec spelling to use
+ * instead, ONLY the four the runner itself proves are aliases: `actionType` (→
+ * `type`), `api` and `endpoint` (→ `target`; `executeAPI` resolves
+ * `api || endpoint || target`), and `navigate` (→ flat `target`/`openIn`;
+ * `executeNavigation` already falls back to them). The rest are runner mechanics
+ * with no spec counterpart — chaining, toasts, post-execution reload/close — and
+ * deprecating them toward a spelling that does not exist would be worse than
+ * leaving them declared.
+ *
+ * Step 3 remains: remove the index signature, at which point `tsc` catches both
+ * typos and retired keys and the dev-mode warning below can retire with it.
  */
 /**
  * Every property `ActionDef` declares, in declaration order.
@@ -59,7 +76,7 @@
  * `keyof ActionDef` cannot substitute for this list: the index signature widens
  * it to `string | number`, which is precisely the problem being worked around.
  */
-export declare const ACTION_DEF_KEYS: readonly ["type", "actionType", "name", "label", "confirmText", "confirm", "condition", "disabled", "api", "endpoint", "method", "navigate", "onClick", "reload", "close", "redirect", "toast", "successMessage", "errorMessage", "refreshAfter", "undoable", "params", "actionParams", "resultDialog", "target", "body", "openIn", "modal", "chain", "chainMode", "onSuccess", "onFailure", "opensInNewTab", "newTabUrl"];
+export declare const ACTION_DEF_KEYS: readonly ["type", "actionType", "name", "label", "confirmText", "confirm", "condition", "disabled", "api", "endpoint", "method", "navigate", "onClick", "reload", "close", "redirect", "toast", "successMessage", "errorMessage", "refreshAfter", "undoable", "params", "actionParams", "resultDialog", "target", "body", "openIn", "modal", "chain", "chainMode", "onSuccess", "onFailure", "opensInNewTab", "newTabUrl", "locations", "visible", "requiredPermissions", "icon", "variant", "order", "component", "objectName", "ai", "aria", "bodyExtra", "bodyShape", "mode", "recordIdField", "recordIdParam", "requiresFeature", "shortcut", "bulkEnabled"];
 /**
  * Every property `@objectstack/spec`'s `ActionSchema` declares.
  *

package/dist/actions/actionKeys.js

@@ -32,25 +32,42 @@
  * interface it mirrors would be the same "declared ≠ enforced" trap this whole
  * thread is about.
  *
- * ── What the inventory found, i.e. step 2's worklist ─────────────────────────
- * `ActionDef` declares 34 keys, the spec's `ActionSchema` declares 36, and they
- * overlap on 17. The two halves of the difference are different problems:
+ * ── What the inventory found, and what step 2 did with it ────────────────────
+ * Step 1 found `ActionDef` declaring 34 keys against the spec `ActionSchema`'s
+ * 36, overlapping on 17. The two halves of the difference were different
+ * problems, and step 2 (objectstack#4075) treated them differently:
  *
  * 18 keys the SPEC owns that `ActionDef` never declared — `ai`, `aria`,
  * `bodyExtra`, `bodyShape`, `bulkEnabled`, `component`, `icon`, `locations`,
  * `mode`, `objectName`, `order`, `recordIdField`, `recordIdParam`,
  * `requiredPermissions`, `requiresFeature`, `shortcut`, `variant`, `visible`.
- * These are authored today and reach readers through the index signature.
- * `ActionEngine` reads two of them (`visible` at the location filter, `locations`
- * at registration) through an `as any` cast — a cast that exists ONLY because the
- * field is undeclared, and that goes away when step 2 promotes them.
+ * These are authored today and used to reach readers through the index
+ * signature. **Step 2 promoted all 18 to explicit optional fields**, typed by
+ * DERIVATION from `@objectstack/spec`'s `ActionInput` rather than by hand-copied
+ * shapes. The `as any` casts `ActionEngine` needed to read `visible`,
+ * `locations` and `requiredPermissions` are gone with them — those casts existed
+ * only because the fields were undeclared.
+ *
+ * Two of the 18 landed as `undefined` rather than as usable types, which is the
+ * correct outcome: spec 17 retired `shortcut` and `bulkEnabled` as `retiredKey()`
+ * tombstones (`z.never()`), so deriving turns "authoring this is a parse
+ * rejection" into a compile error at no cost. Hand-copying would have quietly
+ * re-legitimized two dead keys — which is why the types are derived.
  *
  * 17 keys `ActionDef` declares that the spec does not own — `actionType`, `api`,
  * `chain`, `chainMode`, `close`, `condition`, `confirm`, `endpoint`, `modal`,
  * `navigate`, `onClick`, `onFailure`, `onSuccess`, `redirect`, `reload`, `toast`,
- * `actionParams`. Several are already marked legacy at their declaration. These
- * are objectui's own dialect and need the #4115 treatment: kept and documented as
- * deliberate, or retired — but not silently carried.
+ * `actionParams`. Step 2 marked `@deprecated`, with the spec spelling to use
+ * instead, ONLY the four the runner itself proves are aliases: `actionType` (→
+ * `type`), `api` and `endpoint` (→ `target`; `executeAPI` resolves
+ * `api || endpoint || target`), and `navigate` (→ flat `target`/`openIn`;
+ * `executeNavigation` already falls back to them). The rest are runner mechanics
+ * with no spec counterpart — chaining, toasts, post-execution reload/close — and
+ * deprecating them toward a spelling that does not exist would be worse than
+ * leaving them declared.
+ *
+ * Step 3 remains: remove the index signature, at which point `tsc` catches both
+ * typos and retired keys and the dev-mode warning below can retire with it.
  */
 /**
  * Every property `ActionDef` declares, in declaration order.
@@ -94,6 +111,29 @@ export const ACTION_DEF_KEYS = [
     'onFailure',
     'opensInNewTab',
     'newTabUrl',
+    // Promoted out of the index signature by objectstack#4075 step 2 — the 18 keys
+    // the spec owns that `ActionDef` had never declared. Their types are derived
+    // from `@objectstack/spec`'s `ActionInput`, so this list is the only
+    // hand-maintained half, and `actionKeys.pin.test.ts` re-derives it from the
+    // interface's AST.
+    'locations',
+    'visible',
+    'requiredPermissions',
+    'icon',
+    'variant',
+    'order',
+    'component',
+    'objectName',
+    'ai',
+    'aria',
+    'bodyExtra',
+    'bodyShape',
+    'mode',
+    'recordIdField',
+    'recordIdParam',
+    'requiresFeature',
+    'shortcut',
+    'bulkEnabled',
 ];
 /**
  * Every property `@objectstack/spec`'s `ActionSchema` declares.

package/dist/query/query-ast.d.ts

@@ -1,14 +1,14 @@
 /**
  * ObjectUI - Query AST Builder
- * Phase 3.3: QuerySchema AST implementation
+ * Phase 3.3: DriverQueryConfig AST implementation
  * ObjectStack Spec v2.0.1: Window functions support
  */
-import type { QueryAST, QuerySchema } from '@object-ui/types';
+import type { SqlQueryAST, DriverQueryConfig } from '@object-ui/types';
 /**
- * Query AST Builder - Converts QuerySchema to AST
+ * Query AST Builder - Converts DriverQueryConfig to AST
  */
 export declare class QueryASTBuilder {
-    build(query: QuerySchema): QueryAST;
+    build(query: DriverQueryConfig): SqlQueryAST;
     private buildSelect;
     private buildFrom;
     private buildWhere;
@@ -26,7 +26,7 @@ export declare class QueryASTBuilder {
      * Build window function node (ObjectStack Spec v2.0.1)
      */
     private buildWindow;
-    optimize(ast: QueryAST): QueryAST;
+    optimize(ast: SqlQueryAST): SqlQueryAST;
 }
 export declare const defaultQueryASTBuilder: QueryASTBuilder;
-export declare function buildQueryAST(query: QuerySchema): QueryAST;
+export declare function buildQueryAST(query: DriverQueryConfig): SqlQueryAST;

package/dist/query/query-ast.js

@@ -1,10 +1,10 @@
 /**
  * ObjectUI - Query AST Builder
- * Phase 3.3: QuerySchema AST implementation
+ * Phase 3.3: DriverQueryConfig AST implementation
  * ObjectStack Spec v2.0.1: Window functions support
  */
 /**
- * Query AST Builder - Converts QuerySchema to AST
+ * Query AST Builder - Converts DriverQueryConfig to AST
  */
 export class QueryASTBuilder {
     build(query) {

package/dist/registry/PluginSystem.d.ts

@@ -7,7 +7,17 @@
  */
 import type { Registry } from './Registry.js';
 import type { PluginScope, PluginScopeConfig, AppMetadataPlugin, AppPluginContext } from '@object-ui/types';
-export interface PluginDefinition {
+/**
+ * A plugin for objectui's component REGISTRY: it declares its name/version and
+ * a `register(registry | scope)` callback that contributes renderers.
+ *
+ * NOT the spec's `PluginDefinition` (`@objectstack/spec/kernel`), whose name
+ * this interface carried until objectstack#4115. That one is the platform
+ * PACKAGE manifest — `{ id?, type?, slug?, staticPath?, version?, author?,
+ * homepage?, onInstall?, onEnable?, … }` — a marketplace/install-time document
+ * with no `register` seam, and it shares no required member with this type.
+ */
+export interface RegistryPluginDefinition {
     name: string;
     version: string;
     dependencies?: string[];
@@ -28,7 +38,7 @@ export declare class PluginSystem {
      * @param useScope Whether to use scoped loading (default: true for better isolation)
      * @throws Error if dependencies are missing
      */
-    loadPlugin(plugin: PluginDefinition, registry: Registry, useScope?: boolean): Promise<void>;
+    loadPlugin(plugin: RegistryPluginDefinition, registry: Registry, useScope?: boolean): Promise<void>;
     /**
      * Unload a plugin from the system
      * @param name The name of the plugin to unload
@@ -52,7 +62,7 @@ export declare class PluginSystem {
      * @param name The name of the plugin
      * @returns The plugin definition or undefined
      */
-    getPlugin(name: string): PluginDefinition | undefined;
+    getPlugin(name: string): RegistryPluginDefinition | undefined;
     /**
      * Get all loaded plugin names
      * @returns Array of loaded plugin names
@@ -62,11 +72,11 @@ export declare class PluginSystem {
      * Get all plugin definitions
      * @returns Array of all plugin definitions
      */
-    getAllPlugins(): PluginDefinition[];
+    getAllPlugins(): RegistryPluginDefinition[];
     /**
      * Install an AppMetadataPlugin at runtime.
      *
-     * Wraps the plugin as a PluginDefinition, calls its `init()` and `start()`
+     * Wraps the plugin as a RegistryPluginDefinition, calls its `init()` and `start()`
      * lifecycle hooks, and loads it into the system.
      *
      * @param plugin - An AppMetadataPlugin instance

package/dist/registry/PluginSystem.js

@@ -142,7 +142,7 @@ export class PluginSystem {
     /**
      * Install an AppMetadataPlugin at runtime.
      *
-     * Wraps the plugin as a PluginDefinition, calls its `init()` and `start()`
+     * Wraps the plugin as a RegistryPluginDefinition, calls its `init()` and `start()`
      * lifecycle hooks, and loads it into the system.
      *
      * @param plugin - An AppMetadataPlugin instance

package/dist/registry/WidgetRegistry.d.ts

@@ -9,12 +9,12 @@
  * WidgetRegistry - Runtime widget management with auto-discovery.
  *
  * Provides registration, loading, and lookup of runtime widgets
- * described by WidgetManifest objects. Widgets can be loaded from
+ * described by RuntimeWidgetManifest objects. Widgets can be loaded from
  * ES module URLs, provided inline, or resolved from the component registry.
  *
  * @module
  */
-import type { WidgetManifest, ResolvedWidget, WidgetRegistryListener } from '@object-ui/types';
+import type { RuntimeWidgetManifest, ResolvedWidget, WidgetRegistryListener } from '@object-ui/types';
 import type { Registry } from './Registry.js';
 /**
  * Options for creating a WidgetRegistry instance.
@@ -54,11 +54,11 @@ export declare class WidgetRegistry {
      * Register a widget manifest.
      * Does not load the widget; call `load()` to resolve it.
      */
-    register(manifest: WidgetManifest): void;
+    register(manifest: RuntimeWidgetManifest): void;
     /**
      * Register multiple widget manifests at once.
      */
-    registerAll(manifests: WidgetManifest[]): void;
+    registerAll(manifests: RuntimeWidgetManifest[]): void;
     /**
      * Unregister a widget by name.
      */
@@ -66,15 +66,15 @@ export declare class WidgetRegistry {
     /**
      * Get a widget manifest by name.
      */
-    getManifest(name: string): WidgetManifest | undefined;
+    getManifest(name: string): RuntimeWidgetManifest | undefined;
     /**
      * Get all registered widget manifests.
      */
-    getAllManifests(): WidgetManifest[];
+    getAllManifests(): RuntimeWidgetManifest[];
     /**
      * Get manifests filtered by category.
      */
-    getByCategory(category: string): WidgetManifest[];
+    getByCategory(category: string): RuntimeWidgetManifest[];
     /**
      * Check if a widget is registered.
      */

package/dist/registry/WidgetRegistry.js

@@ -244,7 +244,7 @@ export class WidgetRegistry {
                 // source.url is only known at runtime.
                 //
                 // Security: Widget URLs must be from trusted sources only. Never pass
-                // user-supplied URLs directly to WidgetManifest. URLs should be validated
+                // user-supplied URLs directly to RuntimeWidgetManifest. URLs should be validated
                 // and controlled by the application developer.
                 //
                 // CSP Consideration: If your application uses strict Content Security Policy,

package/dist/styling/scoped-styles.d.ts

@@ -19,14 +19,20 @@
  * `large` is the unconditional base; `medium`/`small`/`xsmall` are `max-width`
  * overrides.
  */
-export type StyleMap = Record<string, string | number>;
-export interface ResponsiveStyles {
-    /** Unconditional base (desktop-first). */
-    large?: StyleMap;
-    medium?: StyleMap;
-    small?: StyleMap;
-    xsmall?: StyleMap;
-}
+import type { ResponsiveStyles } from '@objectstack/spec/ui';
+/**
+ * `StyleMap` / `ResponsiveStyles` are **owned by the spec** (ADR-0065,
+ * `@objectstack/spec/ui`) and re-exported here, not re-declared.
+ *
+ * They used to be hand-written copies under the spec's own names. Both were
+ * member-for-member identical to the spec's at the time of the burn-down
+ * (objectstack#4115), which is exactly what makes a copy dangerous: it passes
+ * every structural comparison right up until the spec adds a breakpoint or
+ * widens a value type, and the doc comment above claims spec canonicity the
+ * whole time. Binding the names to the spec at compile time is the only form
+ * that cannot drift.
+ */
+export type { StyleMap, ResponsiveStyles } from '@objectstack/spec/ui';
 /** max-width breakpoints (px), mirroring Builder.io's default device sizes. */
 export declare const STYLE_BREAKPOINTS: Record<'medium' | 'small' | 'xsmall', number>;
 /** True when a node actually carries responsive styles worth compiling. */

package/dist/utils/chart-series.d.ts

@@ -26,14 +26,26 @@ export interface ChartResultField {
     label?: string;
     format?: string;
 }
-export interface ChartSeries {
+/**
+ * One renderer-internal series binding produced by {@link buildChartSeries}:
+ * WHICH result-set column to draw and what to call it.
+ *
+ * NOT the spec's `ChartSeries` (`@objectstack/spec/ui`), which this type was
+ * named after until objectstack#4115. That one is the AUTHORED dataset-binding
+ * descriptor — `{ name, label?, type?, color?, stack?, yAxis, variant?,
+ * dashArray?, opacity? }`, where `name` is a measure and no `data` is carried.
+ * A third shape, `ChartDataSeries` in `@object-ui/types` (renamed in the same
+ * burn-down), is the inline static-data series of an SDUI `ChartSchema` node.
+ * Three different concepts; this is the one the chart renderers consume.
+ */
+export interface ChartSeriesBinding {
     dataKey: string;
     label: string;
 }
 export interface ChartSeriesResult {
     data: Array<Record<string, unknown>>;
     xAxisKey: string | undefined;
-    series: ChartSeries[];
+    series: ChartSeriesBinding[];
 }
 export declare function buildChartSeries(rows: Array<Record<string, unknown>> | null | undefined, dimensions: string[] | null | undefined, values: string[] | null | undefined, fields?: ChartResultField[] | null): ChartSeriesResult;
 /**

package/dist/utils/dashboard-filters.d.ts

@@ -78,6 +78,15 @@ export declare function dashboardFilterVariableDefs(defs: DashboardFilterDef[]):
  * Build the operator shape (the value side of a `FilterCondition` entry) for
  * one filter's current value. Returns `undefined` when the value imposes no
  * constraint. The caller keys the result by the bound field name.
+ *
+ * A `date`/`dateRange` value is held to three spellings (#3151): a known
+ * preset name → range bounds; a date-macro token or ISO date → equality on
+ * that day; **anything else → skipped with a console warning**, never
+ * silently downgraded to an equality nothing can match. That last branch is
+ * the same strictness `buildWidgetScopedFilter` applies to a default binding
+ * on an unknown field name, for the same reason: a query the backend answers
+ * `200 OK` with zero rows is indistinguishable from "this range has no data",
+ * so the typo has to be said out loud somewhere.
  */
 export declare function buildFilterCondition(def: DashboardFilterDef, value: unknown): Record<string, unknown> | unknown | undefined;
 /**