@object-ui/core 16.1.0 → 17.2.0

package/dist/actions/actionKeys.js

@@ -0,0 +1,283 @@
+/**
+ * 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, 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 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`. 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.
+ *
+ * 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',
+    // 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.
+ *
+ * `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/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