@object-ui/core 16.1.0 → 17.1.0

package/dist/actions/actionKeys.js

@@ -0,0 +1,243 @@
+/**
+ * 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.
+ */
+/**
+ * What an action is allowed to carry — objectstack#4075 step 1.
+ *
+ * `ActionDef` ends with `[key: string]: any`, so it accepts any key of any type.
+ * Concretely (objectui#2990): deleting `ActionDef.execute` produced ZERO compile
+ * errors even though the field had just been removed, and stale metadata still
+ * authoring `execute: 'markDone'` type-checks today. The same deletion against
+ * `@object-ui/types`' `ActionSchema` — which has no index signature — correctly
+ * produced `TS2353` at the authoring site. One of the two readers can catch a
+ * retired key; the other is structurally incapable.
+ *
+ * That asymmetry is the issue. An open key set on a DECLARED METADATA CONTRACT
+ * is what lets a typo (`targt`, `exectue`) and a tombstoned key (`execute`) both
+ * sail through to a runner that then silently does nothing — the #2169 "Mark
+ * Done does nothing" shape.
+ *
+ * This module is step 1 of the staged narrowing: it makes the key set VISIBLE
+ * and warns on anything outside it, without changing a single type. Nothing
+ * breaks, and an invisible failure becomes an audible one. Steps 2 and 3 —
+ * promoting the legitimate keys to explicit optional fields, then removing the
+ * index signature — are what finally let `tsc` catch typos and retired keys.
+ *
+ * The lists are pinned by `__tests__/actionKeys.pin.test.ts`, which re-derives
+ * each one from its actual source. A hand-maintained list that drifts from the
+ * 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:
+ *
+ * 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.
+ *
+ * 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.
+ */
+/**
+ * Every property `ActionDef` declares, in declaration order.
+ *
+ * Kept as data because TypeScript types do not survive to runtime — and
+ * `keyof ActionDef` cannot substitute for this list: the index signature widens
+ * it to `string | number`, which is precisely the problem being worked around.
+ */
+export const ACTION_DEF_KEYS = [
+    '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',
+];
+/**
+ * Every property `@objectstack/spec`'s `ActionSchema` declares.
+ *
+ * `ActionDef` mirrors that schema, so a key the spec owns is legitimate even
+ * when `ActionDef` has not declared it yet — several are read today only through
+ * an `as any` cast (`visible` and `locations` in `ActionEngine`), which is the
+ * cast this list exists to eventually retire.
+ *
+ * Pinned rather than read off the schema at runtime: the spec exports
+ * `ActionSchema` as a lazy proxy that does not forward `.shape`, so resolving it
+ * means walking zod internals (`_def.in` / `_def.innerType`). That is fine in a
+ * test and wrong in shipped code — `@object-ui/types` made the same call for
+ * `ActionComponent`. The pin test does the walk and fails the day this drifts.
+ */
+export const SPEC_ACTION_KEYS = [
+    'ai',
+    'aria',
+    'body',
+    'bodyExtra',
+    'bodyShape',
+    'bulkEnabled',
+    'component',
+    'confirmText',
+    'disabled',
+    'errorMessage',
+    'execute',
+    'icon',
+    'label',
+    'locations',
+    'method',
+    'mode',
+    'name',
+    'newTabUrl',
+    'objectName',
+    'openIn',
+    'opensInNewTab',
+    'order',
+    'params',
+    'recordIdField',
+    'recordIdParam',
+    'refreshAfter',
+    'requiredPermissions',
+    'requiresFeature',
+    'resultDialog',
+    'shortcut',
+    'successMessage',
+    'target',
+    'type',
+    'undoable',
+    'variant',
+    'visible',
+];
+/**
+ * The `navigation` alias's own spelling of a target, read off the action itself
+ * when no nested `navigate` object is present (`ActionRunner.executeNavigation`).
+ *
+ * A declared objectui-side dialect, not spec vocabulary: `replace` is documented
+ * at its read site as "the one thing the `navigation` shape carries that
+ * `ActionSchema` has no field for". Listing it here is what keeps it from being
+ * silent dialect — the alternative is a warning that cries wolf on a shape the
+ * runner itself supports.
+ */
+export const NAVIGATION_ALIAS_KEYS = ['to', 'external', 'newTab', 'replace'];
+/**
+ * Keys the spec has TOMBSTONED: still present in `ActionSchema` so the parser can
+ * reject them BY NAME with a rename prescription, rather than fail with a bare
+ * "unrecognized key".
+ *
+ * Warned about separately from unknown keys, and more loudly: an unknown key is
+ * probably a typo, while a retired key is metadata that used to work. That
+ * distinction is why `executeScript` carries a runtime branch returning the
+ * rename prescription — a branch that exists solely to compensate for the index
+ * signature, and that can retire with it in step 3.
+ */
+export const RETIRED_ACTION_KEYS = {
+    execute: '`execute` was removed in @objectstack/spec 17 (#3855) — rename the key to `target`. ' +
+        'The value (a script name or expression) is unchanged. ' +
+        'Run `os migrate meta --from 16` to rewrite it automatically.',
+};
+/** Every key an action may legitimately carry today. */
+export const KNOWN_ACTION_KEYS = new Set([
+    ...ACTION_DEF_KEYS,
+    ...SPEC_ACTION_KEYS,
+    ...NAVIGATION_ALIAS_KEYS,
+].filter((key) => !(key in RETIRED_ACTION_KEYS)));
+/** Split an action's own keys into the two things worth saying out loud. */
+export function classifyActionKeys(action) {
+    const unknown = [];
+    const retired = [];
+    if (!action || typeof action !== 'object')
+        return { unknown, retired };
+    for (const key of Object.keys(action)) {
+        if (key in RETIRED_ACTION_KEYS)
+            retired.push(key);
+        else if (!KNOWN_ACTION_KEYS.has(key))
+            unknown.push(key);
+    }
+    return { unknown, retired };
+}
+// Warn once per (action, problem), not once per execution: an unrecognized key
+// usually sits in metadata driving a button that gets clicked repeatedly, and a
+// warning that floods the console is a warning that gets muted.
+//
+// Keyed by action name as well as by the keys, deliberately. Keying on the keys
+// alone would report the FIRST action carrying `targt` and stay silent about
+// every other one — sending the author to fix a button that was only the first
+// symptom. The memo is bounded by the number of authored actions either way.
+const warned = new Set();
+/** Reset the warn-once memo. Exported for tests. */
+export function resetActionKeyWarnings() {
+    warned.clear();
+}
+const isDev = () => globalThis.process?.env?.NODE_ENV !==
+    'production';
+/**
+ * Dev-mode only: name the keys an action carries that no reader will ever look
+ * at. Non-breaking by construction — it changes no types and rejects nothing.
+ *
+ * Silently binding no handler is the #2169 "Mark Done does nothing" shape, and
+ * the compiler cannot help while the index signature stands. Until it comes
+ * down, this is the audible half.
+ */
+export function warnOnUnknownActionKeys(action, where = 'ActionRunner') {
+    if (!isDev())
+        return;
+    const { unknown, retired } = classifyActionKeys(action);
+    const name = action?.name ?? action?.type ?? '(unnamed)';
+    for (const key of retired) {
+        const memo = `retired:${String(name)}:${key}`;
+        if (warned.has(memo))
+            continue;
+        warned.add(memo);
+        console.warn(`[${where}] action "${String(name)}" carries the retired key \`${key}\`. ${RETIRED_ACTION_KEYS[key]}`);
+    }
+    if (unknown.length === 0)
+        return;
+    const memo = `unknown:${String(name)}:${unknown.slice().sort().join(',')}`;
+    if (warned.has(memo))
+        return;
+    warned.add(memo);
+    console.warn(`[${where}] action "${String(name)}" carries ${unknown.length === 1 ? 'a key' : 'keys'} no reader ` +
+        `recognizes: \`${unknown.join('`, `')}\`. Nothing will read ${unknown.length === 1 ? 'it' : 'them'} — ` +
+        'check for a typo, or promote the key to an explicit field on `ActionDef` ' +
+        '(packages/core/src/actions/actionKeys.ts). Warned rather than rejected because `ActionDef` ' +
+        'still carries `[key: string]: any`, so the compiler cannot see this (objectstack#4075).');
+}

package/dist/actions/index.d.ts

@@ -7,6 +7,7 @@
  */
 export * from './ActionRunner.js';
 export * from './ActionEngine.js';
+export * from './actionKeys.js';
 export * from './TransactionManager.js';
 export * from './UndoManager.js';
 export * from './bulkFastPath.js';

package/dist/actions/index.js

@@ -7,6 +7,7 @@
  */
 export * from './ActionRunner.js';
 export * from './ActionEngine.js';
+export * from './actionKeys.js';
 export * from './TransactionManager.js';
 export * from './UndoManager.js';
 export * from './bulkFastPath.js';

package/dist/adapters/ApiDataSource.js

@@ -44,7 +44,16 @@ function queryParamsToRecord(params) {
         out.$filter = JSON.stringify(params.$filter);
     }
     if (params.$orderby) {
-        if (Array.isArray(params.$orderby)) {
+        if (typeof params.$orderby === 'string') {
+            // Already an OData order clause ('name asc', 'a asc,b desc'). It MUST be
+            // passed through verbatim: the `Object.entries` branch below would walk a
+            // string index-by-index and emit `0 n,1 a,2 m,…`, which the server dutifully
+            // sorts by — columns that don't exist — and the whole page comes back empty
+            // (objectstack#3821). Callers that build the clause by hand (ObjectGrid's
+            // schema `sort`, RecipientPickerField) hit exactly that.
+            out.$orderby = params.$orderby;
+        }
+        else if (Array.isArray(params.$orderby)) {
             if (typeof params.$orderby[0] === 'string') {
                 out.$orderby = params.$orderby.join(',');
             }

package/dist/adapters/ValueDataSource.d.ts

@@ -8,7 +8,7 @@
  * A DataSource adapter for the `provider: 'value'` ViewData mode.
  * Operates entirely on an in-memory array — no network requests.
  */
-import type { DataSource, BatchTransactionOperation, MutationEvent, QueryParams, QueryResult, AggregateParams, AggregateResult } from '@object-ui/types';
+import type { DataSource, BatchTransactionOperation, DataSourceMutationEvent, QueryParams, QueryResult, AggregateParams, AggregateResult } from '@object-ui/types';
 export interface ValueDataSourceConfig<T = any> {
     /** The static data array */
     items: T[];
@@ -60,7 +60,7 @@ export declare class ValueDataSource<T = any> implements DataSource<T> {
     getView(_objectName: string, _viewId: string): Promise<any | null>;
     getApp(_appId: string): Promise<any | null>;
     aggregate(_resource: string, params: AggregateParams): Promise<AggregateResult[]>;
-    onMutation(callback: (event: MutationEvent<T>) => void): () => void;
+    onMutation(callback: (event: DataSourceMutationEvent<T>) => void): () => void;
     /** Get the current number of items */
     get count(): number;
     /** Get a snapshot of all items (cloned) */

package/dist/evaluator/fieldRules.d.ts

@@ -37,8 +37,6 @@ export declare function resolveFieldRuleState(rules: {
     visibleWhen?: FieldRulePredicate;
     readonlyWhen?: FieldRulePredicate;
     requiredWhen?: FieldRulePredicate;
-    /** Back-compat alias of `requiredWhen` (spec @deprecated). */
-    conditionalRequired?: FieldRulePredicate;
 }, record: Record<string, unknown>, statics: {
     required?: boolean;
     readonly?: boolean;

package/dist/evaluator/fieldRules.js

@@ -79,8 +79,9 @@ export function resolveFieldRuleState(rules, record, statics, previous, scope) {
         (rules.readonlyWhen != null
             ? evalFieldPredicate(rules.readonlyWhen, record, false, previous, scope)
             : false);
-    const requiredPred = rules.requiredWhen ?? rules.conditionalRequired;
     const required = statics.required === true ||
-        (requiredPred != null ? evalFieldPredicate(requiredPred, record, false, previous, scope) : false);
+        (rules.requiredWhen != null
+            ? evalFieldPredicate(rules.requiredWhen, record, false, previous, scope)
+            : false);
     return { visible, readonly, required };
 }

package/dist/evaluator/optionLint.js

@@ -109,7 +109,10 @@ export function lintOptionPredicates(fields) {
             continue;
         knownFields.add(f.name);
         if (OPTION_FIELD_TYPES.has(fieldType(f)) && f.options && f.options.length > 0) {
-            domainByField.set(f.name, new Set(f.options.map((o) => o.value)));
+            // Values stringify at this boundary (#3090 widened OptionLike.value):
+            // the domain is compared against CEL literal TEXT, so the canonical
+            // string form is the right footing for numeric/boolean options too.
+            domainByField.set(f.name, new Set(f.options.map((o) => String(o.value))));
         }
     }
     const issues = [];
@@ -123,7 +126,7 @@ export function lintOptionPredicates(fields) {
             const source = predicateSource(opt.visibleWhen);
             if (!source.trim())
                 continue;
-            const option = opt.value;
+            const option = String(opt.value); // report key — display form (#3090)
             // 1. Syntax — canonical CEL parse (no schema hint = no scope false-positives).
             const parsed = validateExpression('predicate', source);
             if (!parsed.ok) {

package/dist/evaluator/optionRules.d.ts

@@ -28,6 +28,7 @@
  * security boundary: when an option is gated for access-control reasons the
  * server must also reject writes of its value.
  */
+import type { DependsOnInput } from '@object-ui/types';
 import { type FieldRulePredicate } from './fieldRules.js';
 /**
  * Minimal shape of a select/radio option this module reads. Deliberately has no
@@ -36,15 +37,21 @@ import { type FieldRulePredicate } from './fieldRules.js';
  */
 export interface OptionLike {
     label: string;
-    value: string;
+    /** Widened with `SelectOption.value` (#3090): the option engines treat the
+     * value opaquely (gate/filter by `visibleWhen`, compare by identity), so a
+     * numeric/boolean authored value flows through unchanged. */
+    value: string | number | boolean;
     /** Per-option visibility predicate (CEL). Omit = always available. */
     visibleWhen?: FieldRulePredicate;
 }
-/** A field's `dependsOn` as authored: a bare name, or a list of names / `{field,param}`. */
-export type DependsOnInput = string | Array<string | {
-    field: string;
-    param?: string;
-}> | undefined | null;
+/**
+ * A field's `dependsOn` as authored — imported from `@object-ui/types`, where
+ * `FormField.dependsOn` is declared with it (framework#4074; formerly a local
+ * declaration that only the reader knew about, while the public
+ * `FormField.dependsOn` said `string`). Re-exported for this module's existing
+ * consumers.
+ */
+export type { DependsOnInput } from '@object-ui/types';
 /**
  * Normalize a field's `dependsOn` to the list of sibling field names it reacts
  * to. The lookup-only `{field,param}` form contributes just its `field`.

package/dist/evaluator/optionRules.js

@@ -5,29 +5,6 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-/**
- * Client-side resolution of per-option visibility for `select` / `radio` /
- * `multiselect` fields — cascading (dependent) options and role/context gating.
- *
- * An option carries an optional `visibleWhen` CEL predicate; the option is
- * offered only when it evaluates TRUE against the live record + `current_user`
- * (the SAME engine and binding environment as a field-level `visibleWhen`, via
- * {@link evalFieldPredicate}). This expresses both:
- *   - cascades — `record.country == 'cn'` (the dependent list narrows as the
- *     controlling field changes), and
- *   - role/context gating — `'admin' in current_user.positions`.
- *
- * A field declares which sibling fields its option list reacts to via
- * `dependsOn` (aligns with `@objectstack/spec` Field.dependsOn — the same knob
- * lookups use). While any dependency is empty the list is *gated*: we surface a
- * "select the parent first" hint instead of an unfiltered set, mirroring the
- * dependent-lookup UX (#2215).
- *
- * Evaluation is fail-open (a broken/absent predicate keeps the option) — the
- * same safe default as field visibility. Client-side hiding is UX, not a
- * security boundary: when an option is gated for access-control reasons the
- * server must also reject writes of its value.
- */
 import { evalFieldPredicate } from './fieldRules.js';
 /**
  * Normalize a field's `dependsOn` to the list of sibling field names it reacts

package/dist/index.d.ts

@@ -17,6 +17,8 @@ export * from './utils/filter-converter.js';
 export * from './utils/managedBy.js';
 export * from './utils/extract-records.js';
 export * from './utils/expand-fields.js';
+export * from './utils/column-identity.js';
+export * from './utils/sort-values.js';
 export * from './evaluator/index.js';
 export * from './actions/index.js';
 export * from './query/index.js';
@@ -40,6 +42,7 @@ export * from './runtime/capabilities.js';
 export { composeStacks } from '@objectstack/spec';
 export * from './utils/drill-down.js';
 export * from './utils/date-macros.js';
+export * from './utils/filter-tokens.js';
 export * from './utils/dashboard-filters.js';
 export * from './utils/merge-filters.js';
 export * from './utils/compare-to.js';
@@ -48,3 +51,4 @@ export * from './utils/dataset-format.js';
 export * from './utils/record-title.js';
 export * from './utils/export-filename.js';
 export * from './utils/reference-keys.js';
+export * from './utils/normalize-list-view.js';

package/dist/index.js

@@ -16,6 +16,8 @@ export * from './utils/filter-converter.js';
 export * from './utils/managedBy.js';
 export * from './utils/extract-records.js';
 export * from './utils/expand-fields.js';
+export * from './utils/column-identity.js';
+export * from './utils/sort-values.js';
 export * from './evaluator/index.js';
 export * from './actions/index.js';
 export * from './query/index.js';
@@ -39,6 +41,10 @@ export * from './runtime/capabilities.js';
 export { composeStacks } from '@objectstack/spec';
 export * from './utils/drill-down.js';
 export * from './utils/date-macros.js';
+// Session-scoped filter placeholders ({current_user_id} / {current_org_id})
+// plus `resolveFilterPlaceholders`, the single entry point every surface
+// should call so no vocabulary is silently skipped (framework #3574).
+export * from './utils/filter-tokens.js';
 export * from './utils/dashboard-filters.js';
 export * from './utils/merge-filters.js';
 export * from './utils/compare-to.js';
@@ -47,3 +53,4 @@ export * from './utils/dataset-format.js';
 export * from './utils/record-title.js';
 export * from './utils/export-filename.js';
 export * from './utils/reference-keys.js';
+export * from './utils/normalize-list-view.js';

package/dist/registry/Registry.d.ts

@@ -62,6 +62,22 @@ export type ComponentConfig<T = any> = ComponentMeta & {
     type: string;
     component: ComponentRenderer<T>;
 };
+/**
+ * A CONTRACT-surface entry (ADR-0080), as returned by
+ * {@link Registry.getPublicConfigs}.
+ *
+ * Same shape as {@link ComponentConfig} except `component` is absent while the
+ * entry is still a pending `registerLazy` stub: the plugin module has not been
+ * imported yet, so there is no renderer to hand out. Consumers render such an
+ * entry through `SchemaRenderer`, which triggers the loader and shows a
+ * placeholder in the meantime (objectui#2953).
+ */
+export type PublicComponentConfig<T = any> = ComponentMeta & {
+    type: string;
+    component?: ComponentRenderer<T>;
+    /** True while this entry is a `registerLazy` stub whose loader has not run. */
+    lazy?: boolean;
+};
 /**
  * Lazy loader function used by `Registry.registerLazy`. The loader is invoked
  * the first time a missing component type is requested through `getAsync`/the
@@ -79,6 +95,14 @@ export declare class Registry<T = any> {
      * load completes.
      */
     private listeners;
+    /**
+     * Bumped whenever the set of KNOWN types changes — a registration, an
+     * unregistration, or a new lazy stub. A cheap cache key for consumers that
+     * derive something from the whole registry (whitelists, manifests, palettes)
+     * and need to rebuild when it grows. Counting types is not a substitute: a
+     * registration paired with an unregistration leaves the count untouched.
+     */
+    private version;
     /**
      * Register a component with optional namespace support.
      * If namespace is provided in meta, the component will be registered as "namespace:type".
@@ -141,6 +165,11 @@ export declare class Registry<T = any> {
      */
     subscribe(listener: () => void): () => void;
     private notify;
+    /**
+     * Monotonic counter of changes to the set of known types. Rebuild anything
+     * derived from the whole registry when this moves — see {@link getKnownTypes}.
+     */
+    getVersion(): number;
     /**
      * Get a component by type. Supports both namespaced and non-namespaced lookups.
      *
@@ -164,6 +193,13 @@ export declare class Registry<T = any> {
     /**
      * Get component configuration by type with namespace support.
      *
+     * LOADED registrations only — a type that exists solely as a `registerLazy`
+     * stub returns `undefined` here, because callers read `.component` off the
+     * result and a stub has no renderer until its loader runs. The *contract*
+     * question ("is this tag part of the public surface?") must not depend on
+     * load order, so {@link getPublicConfigs} resolves lazy stubs separately
+     * (objectui#2953). Use {@link hasLazy} / {@link loadLazy} to reach a stub.
+     *
      * @param type - Component type (e.g., 'button' or 'ui:button')
      * @param namespace - Optional namespace for lookup priority
      * @returns Component configuration or undefined
@@ -178,23 +214,66 @@ export declare class Registry<T = any> {
      */
     has(type: string, namespace?: string): boolean;
     /**
-     * Get all registered component types.
+     * Get all LOADED component types — what can be rendered right now.
+     *
+     * Pending `registerLazy` stubs are not included; use {@link getKnownTypes}
+     * for the question "is this a type this app knows about", which is what a
+     * whitelist or manifest wants (objectui#2953).
      *
      * @returns Array of all component type identifiers
      */
     getAllTypes(): string[];
+    /**
+     * Every type the registry can resolve — loaded registrations PLUS pending
+     * lazy stubs, deduped. Both the bare and namespaced keys are included, as
+     * they are in {@link getAllTypes}.
+     *
+     * This is the set to build a whitelist or a manifest from. Keying one off
+     * `getAllTypes()` instead makes it depend on which plugin chunks happen to
+     * have loaded: a lazily-registered block gets rejected as unknown, and
+     * whether it does varies by session (objectui#2953).
+     */
+    getKnownTypes(): string[];
+    /**
+     * Metadata for `type` — from the loaded registration when there is one,
+     * otherwise from a pending `registerLazy` stub.
+     *
+     * Use this when you need to know what a type IS (namespace, container-ness,
+     * declared inputs). {@link getConfig} answers a different question — "can I
+     * render this right now" — and is deliberately loaded-only, since callers
+     * read `.component` off it.
+     *
+     * A stub carries only what `registerLazy` was given, so `inputs` is usually
+     * absent until the chunk loads. Consumers should treat that as "not yet
+     * known", not as "declares no props".
+     */
+    getMeta(type: string, namespace?: string): ComponentMeta | undefined;
     /**
      * Get all registered component configurations.
      *
      * @returns Array of all component configurations
      */
     getAllConfigs(): ComponentConfig<T>[];
+    /**
+     * Resolve `tag` for the CONTRACT surface: the loaded registration when the
+     * component is already in the registry, otherwise the metadata of a pending
+     * `registerLazy` stub.
+     *
+     * A block registered lazily is a first-class member of the contract — the
+     * loader is recorded at boot and the plugin chunk is imported on first use —
+     * so contract membership must not hinge on whether that import happened to
+     * have run yet (objectui#2953).
+     */
+    private getContractConfig;
     /**
      * Get the curated PUBLIC-tier component configs (ADR-0080) — those registered
      * with `tier: 'public'`. This is the contract/AI-vocabulary surface, a subset
      * of the full rendering capability returned by {@link getAllConfigs}.
+     *
+     * Includes blocks that are only lazily registered so far; those come back
+     * with `lazy: true` and no `component` (see {@link PublicComponentConfig}).
      */
-    getPublicConfigs(): ComponentConfig<T>[];
+    getPublicConfigs(): PublicComponentConfig<T>[];
     /**
      * Get all components in a specific namespace.
      *