@object-ui/core 17.5.0 → 17.7.0

package/dist/registry/Registry.d.ts

@@ -5,26 +5,150 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { SchemaNode } from '../types/index.js';
+import type { ComponentMeta as CanonicalComponentMeta } from '@object-ui/types';
+import type { ComponentConfig } from '@object-ui/types';
+/**
+ * The renderer a registration carries — the IDENTITY alias, deliberately.
+ *
+ * ⚠️ Load-bearing for objectui#6298, which is why it is documented rather than
+ * left as a bare line. `ComponentRenderer<T>` resolves to `T` and contributes
+ * NO type information: that is the entire reason `@object-ui/types` can declare
+ * the one `ComponentConfig` with `component: T` and mean exactly what this
+ * package used to mean by `component: ComponentRenderer<T>`, WITHOUT
+ * `@object-ui/types` needing to reach this declaration. It could not have
+ * reached it: `@object-ui/types` is the bottom layer (`packages/types/package.json`
+ * depends on `@objectstack/spec` and `zod` only) and this package depends on it,
+ * so an edge in that direction would be a cycle.
+ *
+ * The alias survives as the NAME this package's own renderer-shaped positions
+ * are spelled with ({@link withElementDataSourceInput}, {@link PublicComponentConfig}).
+ * If it is ever given real content, `component: T` over in `@object-ui/types`
+ * stops being the same slot — `__tests__/component-config-single-declaration.test.ts`
+ * asserts the identity so that change cannot pass unnoticed.
+ */
 export type ComponentRenderer<T = any> = T;
-export type ComponentInput = {
-    name: string;
-    type: 'string' | 'number' | 'boolean' | 'enum' | 'array' | 'object' | 'color' | 'date' | 'code' | 'file' | 'slot';
-    label?: string;
-    defaultValue?: any;
-    required?: boolean;
-    enum?: string[] | {
-        label: string;
-        value: any;
-    }[];
-    description?: string;
-    advanced?: boolean;
-    inputType?: string;
+/**
+ * What a registration DECLARES about one authorable prop.
+ *
+ * This is the declaration the component registrations themselves import, so it
+ * is the one an author's manifest is ultimately built from — and it is now
+ * RE-EXPORTED from `@object-ui/types` rather than restated here
+ * (objectui#4972), the disposition objectui#4580 ruled for the identical
+ * shape: *a structural copy would reproduce the defect the moment either side
+ * moved.* This package already depends on `@object-ui/types`, so the edge
+ * exists and adds no cycle, and `src/types/index.ts` re-exports `SchemaNode`
+ * from there the same way.
+ *
+ * The copy this replaces had ALREADY moved, which is why the card is not
+ * hypothetical: it carried nine keys while `base.ts` carried thirteen, so
+ * `min` / `max` / `step` / `placeholder` were missing from *the copy every
+ * registration actually imports*. Those four keys were therefore unwritable at
+ * any real registration — a plain TS error — while `ComponentInputSchema` (the
+ * zod schema) and `ComponentMeta.inputs` both accepted them. The publication
+ * face advertised four keys the authoring face rejected; the divergence was
+ * dormant only because no registration had tried to write one yet.
+ */
+export type { ComponentInput } from '@object-ui/types';
+/**
+ * An AUTHORING SURFACE a component type can be reached from — the two this
+ * engine has, named as its own code already names them.
+ *
+ * - `'json'` — the JSON/SDUI authoring surface. A node an author (or an AI)
+ *   writes as `{ "type": "…" }` in metadata.
+ * - `'html'` — a `kind:'html'` page, written as constrained JSX text that
+ *   `@object-ui/sdui-parser` COMPILES (never executes) into SDUI nodes, tag
+ *   name straight through. `isHtmlTierNode` marks what that parser emitted.
+ *
+ * The distinction is not decorative here: it is the whole reason
+ * {@link ComponentDeprecation} carries a surface list rather than a boolean.
+ */
+export type AuthoringSurface = 'json' | 'html';
+/**
+ * That a component type is DEPRECATED for authoring — the machine-readable
+ * statement of it (objectui#6674).
+ *
+ * ## Why this exists at all
+ *
+ * Before this type, a deprecation was stated in exactly two places, neither of
+ * which any gate, test or type can consult: a `console.warn` STRING LITERAL
+ * inside the renderer, and the word "(Deprecated)" inside a human-readable
+ * `label`. So the question "is this type deprecated?" had no asker. The two
+ * gates that touch component types — `examples/schema-catalog/test/
+ * catalog-gallery-render.test.tsx` and `scripts/check-doc-component-types.mjs`
+ * — both ask only whether a type RESOLVES, and a deprecated type resolves
+ * perfectly well. The measurement objectui#6674 filed is what that costs: the
+ * catalog suite passes 583/583 with 85 authored `div` nodes in the corpus. The
+ * green was the finding.
+ *
+ * This is a layer BELOW the usual "declared but enforced nowhere" defect: there
+ * was nothing declared to enforce.
+ *
+ * ## Why `surfaces` is required, and why a boolean would have been wrong
+ *
+ * `deprecated: true` would restate, as a contract, the exact falsehood the
+ * maintainer ruled against on 2026-08-10 (objectui#4000): the `span` notice is
+ * scoped BY PROVENANCE because that tag is deprecated on the JSON surface and
+ * simultaneously vocabulary of the `kind:'html'` tier — an author there writes
+ * the plain tag, our own parser maps it straight through, and no other
+ * spelling exists for them to migrate to. "A notice that says the type is
+ * deprecated FULL STOP is therefore false for one of its two readers"
+ * (`span.tsx`), and the reader it was false for was the one who could do
+ * nothing about it. (`div` carried the same scope until ruling A on
+ * objectstack#20112 deprecated it on the html surface too, with `box` as its
+ * replacement; it now declares both surfaces — objectui#10757. The list is
+ * what let that be one edit.) A declaration that dropped the scope
+ * would hand every future gate the same false premise, in a form that is harder
+ * to see than a console string. So the scope travels WITH the declaration, and
+ * {@link Registry.deprecationFor} makes callers name the surface they are
+ * asking about instead of re-deriving the exemption locally.
+ *
+ * ## What it deliberately does not do
+ *
+ * Nothing here fails a build, and nothing here deprecates anything: this is the
+ * vocabulary plus the reader. Which types get marked, and when, is
+ * objectui#3965's to decide — the ordering matters, because marking a type
+ * while the corpus still authors it 85 times produces a red with nowhere to go.
+ */
+export type ComponentDeprecation = {
+    /**
+     * The surfaces on which authoring this type is deprecated. A surface NOT
+     * listed keeps the type as first-class vocabulary there — that is the whole
+     * content of the objectui#4000 ruling, said once, in the declaration.
+     *
+     * Required and expected non-empty: an empty list declares a deprecation that
+     * applies to no reader, which is indistinguishable from not declaring one.
+     */
+    surfaces: AuthoringSurface[];
+    /**
+     * One line of migration guidance for the surfaces above — what to author
+     * instead. Optional, but it is what makes a gate's failure ACTIONABLE: a gate
+     * that can only say "deprecated" sends its reader back to the console string
+     * this declaration exists to replace.
+     */
+    replacement?: string;
 };
-export type ComponentMeta = {
-    label?: string;
-    icon?: string;
-    category?: string;
+/**
+ * The keys the REGISTRY adds on top of the one `ComponentMeta` declaration:
+ * registration mechanics (`tier` / `namespace` / `skipFallback`), the
+ * host-labelling contract (`labelling`), and the authoring-time
+ * `deprecated` declaration. None of the five has a counterpart on
+ * the general type in `@object-ui/types`, and none is being moved there —
+ * publishing registry mechanics on the general type was the alternative
+ * objectui#6067 weighed and rejected.
+ *
+ * They live in their OWN named type so that `ComponentMeta` below can be
+ * DERIVED from the canonical declaration instead of restating it. Until
+ * objectui#6067 this file carried a second, thirteen-key structural copy of
+ * the name: the nine shared members restated from `@object-ui/types`' `base.ts`,
+ * these four added here, and `tags` / `description` — declared on the canonical
+ * type and on the `ComponentMetaSchema` zod mirror — simply absent. That is
+ * objectui#4580's ruling coming true for the third type in a row: *a
+ * structural copy would reproduce the defect the moment either side moved.*
+ * objectui#5671 executed the same convergence for `ComponentInput` in this very
+ * file, and objectui#5893 closed the identical two-key delta inside
+ * `@object-ui/types`.
+ */
+export type RegistryComponentMetaExtras = {
     /**
      * Public contract tier (ADR-0080). `'public'` = part of the curated,
      * type-checked, AI-facing block set (gets a strengthened contract, the
@@ -38,6 +162,12 @@ export type ComponentMeta = {
      * Use this when a component should only be accessible via its full namespaced key.
      * This avoids conflicts with other components that share the same base name.
      *
+     * ⚠️ That promise covers BOTH registry tables since objectui#9839, and it did
+     * not before. Declining the bare key used to leave `register` deleting a bare
+     * lazy stub anyway, so a registration that opted out still took the bare key
+     * off its owner — and then refused to replace it, leaving it claimed by
+     * nobody. An opt-out now leaves the bare key exactly where it was.
+     *
      * @example
      * // Register as 'view:form' only, don't overwrite 'form'
      * registry.register('form', FormView, { namespace: 'view', skipFallback: true });
@@ -45,7 +175,11 @@ export type ComponentMeta = {
     skipFallback?: boolean;
     /**
      * How a HOST must associate its own visible label with what this component
-     * renders (objectui#3961). Read by the form renderer; absent ⇒ `'control'`.
+     * renders (objectui#3961, extended by objectui#4857). Read by the form
+     * renderer; absent ⇒ `'control'`. This closed three-value vocabulary is the
+     * single repo-wide answer to "how does a host learn what a widget will
+     * render" (maintainer ruling of 2026-08-17, joint with objectui#4871) — no
+     * host may keep a local variant of it.
      *
      * - `'control'` — the component's outermost rendered element is a LABELABLE
      *   HTML element (`input` / `textarea` / `select` / `button` / …), so the host
@@ -58,7 +192,18 @@ export type ComponentMeta = {
      *   nothing and contributes no accessible name (`HTMLLabelElement.control` is
      *   `null`) — so the host must instead give its label an `id` and hand the
      *   component `aria-labelledby`, which associates by IDREF and works on any
-     *   element.
+     *   element. The COMPONENT consumes those keys on its own surface.
+     * - `'display'` — the rendered surface is a pure display in EVERY state:
+     *   there is no focusable control and the component itself spreads nothing
+     *   (computed / system-generated values such as `formula` / `summary` /
+     *   `auto_number` / `vector`). The host must not emit a `<label for>` at all
+     *   — no labelable element will ever exist for it to reach, in the editable
+     *   state as much as the readonly one — and instead wraps the component's
+     *   output in the host's own container carrying the field id,
+     *   `aria-labelledby`, `aria-describedby` and `role="group"` (the
+     *   objectui#4788 channel, driven by this declaration rather than by
+     *   `readonly` alone). Unlike `'group'`, the WIDGET is not expected to
+     *   consume anything: the host's wrapper is the named surface.
      *
      * This is a DECLARATION, not a guess: the host cannot infer it from the DOM a
      * widget happens to render, and a widget that fails to declare it falls back
@@ -66,38 +211,126 @@ export type ComponentMeta = {
      * label-association tests (objectui#3952) instead of silently producing an
      * unlabelled group.
      */
-    labelling?: 'control' | 'group';
-    inputs?: ComponentInput[];
-    defaultProps?: Record<string, any>;
-    defaultChildren?: SchemaNode[];
-    examples?: Record<string, any>;
-    isContainer?: boolean;
-    resizable?: boolean;
-    resizeConstraints?: {
-        width?: boolean;
-        height?: boolean;
-        minWidth?: number;
-        maxWidth?: number;
-        minHeight?: number;
-        maxHeight?: number;
-    };
-};
-export type ComponentConfig<T = any> = ComponentMeta & {
-    type: string;
-    component: ComponentRenderer<T>;
+    labelling?: 'control' | 'group' | 'display';
+    /**
+     * That authoring this type is DEPRECATED, and on which surfaces
+     * (objectui#6674). Absent ⇒ not deprecated anywhere; see
+     * {@link ComponentDeprecation} for why the surfaces are part of the
+     * declaration rather than a boolean, and {@link Registry.deprecationFor} for
+     * the reader a gate asks.
+     *
+     * This is a DECLARATION about the TYPE, which is why it sits on the
+     * registration rather than on a node: every node of a deprecated type is
+     * deprecated, and the one place that fact can be stated once is where the
+     * type is registered.
+     */
+    deprecated?: ComponentDeprecation;
 };
+/**
+ * What a registration DECLARES about one component — the type every
+ * `ComponentRegistry.register` / `registerLazy` call is checked against.
+ *
+ * ONE declaration of the shared members: this is `@object-ui/types`'
+ * `ComponentMeta` (the declaration `ComponentMetaSchema` mirrors and the
+ * plugin-facing surface publishes) intersected with the registry-only keys
+ * above. The nine shared members are no longer restated here, so they cannot
+ * drift again, and `tags` / `description` now reach the registration surface —
+ * the two keys the divergence had made unwritable at the very declaration most
+ * component registrations import.
+ *
+ * NOTE for anyone pinning this: every member of both halves is OPTIONAL, so
+ * `extends` is mutually TRUE between the two shapes even when their key sets
+ * differ. Measured on the EMITTED `.d.ts` of both packages immediately before
+ * this convergence: `Core extends Canonical` and `Canonical extends Core` were
+ * BOTH `true` while `tags` / `description` were missing and four keys were
+ * extra. An assignability assertion is therefore a ghost here — it was green on
+ * the diverged tree. `__tests__/component-meta-derives-from-canonical.test.ts`
+ * compares `keyof` sets instead and keeps the assignability check beside it as
+ * the labelled control that shows why.
+ */
+export type ComponentMeta = CanonicalComponentMeta & RegistryComponentMetaExtras;
+/**
+ * ONE authority for `ComponentConfig` (objectui#6298) — this package RE-EXPORTS
+ * `@object-ui/types`' declaration instead of declaring a second one, the same
+ * disposition objectui#5671 gave `ComponentInput` a few lines above and
+ * objectui#4580 ruled for the whole family: *a structural copy would reproduce
+ * the defect the moment either side moved.*
+ *
+ * ## What was wrong
+ *
+ * Both spellings were PUBLISHED — `@object-ui/types`' `src/index.ts` exports its
+ * one, and this file reaches `@object-ui/core`'s public entry through
+ * `src/index.ts`'s `export * from './registry/Registry.js'`. An IDE auto-import
+ * therefore picked between two different types by alphabetical order. After
+ * objectui#6067 / PR #6297 single-sourced the `ComponentMeta` half, what still
+ * differed was GENERICITY AND THE `component` SLOT: `@object-ui/types`' was
+ * non-generic with `component: any`, this one was `<T = any>` with
+ * `component: ComponentRenderer<T>`.
+ *
+ * ⚠️ Measured on the EMITTED `.d.ts` of both packages immediately before this
+ * convergence, `Exact<TypesConfig, CoreConfig>` — mutual assignability — read
+ * `true` on the DIVERGED pair, because `component: any` absorbs everything and
+ * every other member is optional. An assignability assertion is a GHOST here,
+ * exactly as `__tests__/component-meta-derives-from-canonical.test.ts` records
+ * for the sibling type. The readings that actually moved were "is
+ * `@object-ui/types`' declaration generic" (`TS2315: Type 'ComponentConfig' is
+ * not generic` before, no error after) and the symmetric key-set difference.
+ *
+ * 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 `ComponentConfig` off that gate's
+ * `KNOWN_COLLISIONS` baseline. Deriving a new declaration here instead would
+ * NOT have: `ComponentMeta` was converged that way by PR #6297 and is still a
+ * row on that baseline today.
+ */
+export type { ComponentConfig } from '@object-ui/types';
+/**
+ * What the registry actually STORES and hands back — `ComponentConfig` plus the
+ * registry-only keys, as a NAMED extension (objectui#6298).
+ *
+ * This is type-identical to the `ComponentConfig` this file used to declare:
+ * `CanonicalComponentMeta & RegistryComponentMetaExtras & { type; component }`,
+ * reached from the other side. The two halves are named rather than restated —
+ * one declaration for the shared members ({@link ComponentConfig}, in
+ * `@object-ui/types`), a named extension for the rest
+ * ({@link RegistryComponentMetaExtras}) — which is the shape PR #6297 gave
+ * {@link ComponentMeta}.
+ *
+ * It exists because the extras are NOT optional decoration on a registry entry:
+ * {@link Registry.getNamespaceComponents} filters on `config.namespace`, and
+ * `tier` / `labelling` / `deprecated` are read off registrations elsewhere. A
+ * bare re-export as the entry type would have silently dropped them.
+ *
+ * ⚠️ `ComponentConfig` remains the AUTHORING vocabulary and the general name;
+ * registrations are checked against {@link ComponentMeta}, never against this.
+ * Nothing writes a `RegistryComponentConfig` literal — the registry builds them.
+ */
+export type RegistryComponentConfig<T = any> = ComponentConfig<T> & RegistryComponentMetaExtras;
 /**
  * A CONTRACT-surface entry (ADR-0080), as returned by
  * {@link Registry.getPublicConfigs}.
  *
- * Same shape as {@link ComponentConfig} except `component` is absent while the
+ * Same shape as {@link RegistryComponentConfig} 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).
+ *
+ * `tier` is widened by one PROJECTION-ONLY value, `'html'`: an entry the html
+ * tier's intrinsic roster contributed (objectui#10735). No registration
+ * declares it — `RegistryComponentMetaExtras.tier` stays `'public' | 'internal'`
+ * — the read stamps it, and `manifestFromConfigs` carries it into the manifest
+ * so a consumer that means the CURATED vocabulary can filter it out.
  */
-export type PublicComponentConfig<T = any> = ComponentMeta & {
+export type PublicComponentConfig<T = any> = Omit<ComponentMeta, 'tier'> & {
     type: string;
+    /**
+     * The registration's declared tier, or `'html'` for an entry that reaches the
+     * contract through {@link HTML_TIER_INTRINSICS} rather than through the
+     * curated roster or a `tier: 'public'` opt-in. Absent or `'public'` = the
+     * curated JSON-surface vocabulary.
+     */
+    tier?: ComponentMeta['tier'] | 'html';
     component?: ComponentRenderer<T>;
     /** True while this entry is a `registerLazy` stub whose loader has not run. */
     lazy?: boolean;
@@ -110,6 +343,58 @@ export type PublicComponentConfig<T = any> = ComponentMeta & {
  * `register()` for that type.
  */
 export type LazyComponentLoader = () => Promise<unknown>;
+/**
+ * Emit the spec's `dataSource` input for a registration whose renderer wraps
+ * `ElementDataSourceGate` (objectui#6678).
+ *
+ * ## The one place, and why it is this one
+ *
+ * The maintainer ruling of 2026-08-29 adopted option B **in the injection
+ * form**: the declaration is emitted mechanically at the wrapping seam so every
+ * gate-wrapping registration declares the key from the same place that reads it
+ * — one mechanism rather than nine hand-kept copies across nine packages, which
+ * drift and which a tenth block would simply forget. `register()` is where every
+ * one of those registrations passes through, so it is where the emission lands;
+ * the DECLARATION itself is `ELEMENT_DATA_SOURCE_INPUT`, which lives beside the
+ * binding's own semantics in `data-scope/element-data-source.ts`.
+ *
+ * ## What it must NOT do, which is half the ruling
+ *
+ * Widening this to every registration is option A wearing a different hat: it
+ * would silence `dataSource` on `flex` and `card`, which do not read it, and the
+ * diagnostic would lie in the other direction instead of the one it lied in
+ * before. So the condition is the marker and nothing else — no heuristic over
+ * `objectName`, no "looks object-bound".
+ *
+ * ## Idempotent, and it never overwrites
+ *
+ * A registration that declares `dataSource` ITSELF keeps its own entry: the
+ * emission fills a gap, it does not own the key. (Nothing declares it today —
+ * that is the defect — but a block whose binding needs a narrower description
+ * later must be able to say so without fighting this function.) Re-registering
+ * the same component, which the registry allows and tests do constantly, is
+ * likewise a no-op rather than a growing `inputs` array.
+ *
+ * ## Typed end to end — the cast is gone (`9e37d9b39`)
+ *
+ * The spliced element is an `InjectedComponentInput` (`@object-ui/types`): a
+ * `ComponentInput` plus the framework-set `binding` marker, so it is a plain
+ * subtype of the array's element type and the return value type-checks as a
+ * `ComponentMeta` with no assertion. This used to read `as ComponentMeta`,
+ * because `ELEMENT_DATA_SOURCE_INPUT` carried a hand-written inline type and
+ * `binding` had no declared home — and a cast at the one place the key is
+ * written is exactly what would have hidden any later drift between the
+ * constant and the type. The absence is held by `eslint.config.js`, which
+ * scopes `@typescript-eslint/consistent-type-assertions` with
+ * `assertionStyle: 'never'` to THIS FILE (objectui#8316) — an AST rule,
+ * because `tsc --noEmit` stays at exit 0 with the cast re-added and the
+ * source-text pin that used to stand here was green for `<ComponentMeta>{…}`,
+ * the same assertion in the other spelling.
+ * `packages/types/src/__tests__/injected-component-input-6950.test.ts` still
+ * pins the positive half, that the local below is ANNOTATED. Keep it typed: if
+ * the shape ever stops fitting, that line is where the compiler should say so.
+ */
+export declare function withElementDataSourceInput<T>(component: ComponentRenderer<T>, meta?: ComponentMeta): ComponentMeta | undefined;
 export declare class Registry<T = any> {
     private components;
     private lazyEntries;
@@ -149,9 +434,28 @@ export declare class Registry<T = any> {
     /**
      * Remove a previously registered component. Mirrors {@link register} by
      * clearing both the namespaced key and the bare-name fallback (when the
-     * fallback still points at this registration), plus any matching lazy stub.
+     * fallback still points at this registration), plus any matching lazy stub —
+     * where "matching" means the same thing on both tables: a stub that still
+     * belongs to THIS registration (objectui#9839).
      * Notifies subscribers only when something was actually removed.
      *
+     * ⭐ Why "matching" cannot mean "a stub under either key". This function
+     * already answers that question for the bare `components` key and answers it
+     * "ownership" — it will not drop bare `dashboard` when it resolves to
+     * `plugin-dashboard:dashboard`. Reading the next line as an unconditional
+     * delete makes the SAME call, on the SAME bare key, with the SAME owner,
+     * take the opposite decision purely because the owner happens to be sitting
+     * in the other table at that instant — and which table it is sitting in is
+     * exactly the "has the chunk loaded yet" race that objectui#9533 and
+     * objectui#9821 are about. A policy that flips on chunk-load timing is not a
+     * policy, so the stub gets the ownership test too.
+     *
+     * ⚠️ The BARE form (`unregister(type)` with no namespace) is unchanged and
+     * is still the unconditional one, on both tables: `fullType === type` there,
+     * so the deletes below address the bare key directly. That is the "force"
+     * form teardown sites pair with the namespaced call, and taking it away
+     * would break them.
+     *
      * Mainly used by tests that install a stub renderer and need to restore the
      * prior registry state on teardown, since the registry is a process-level
      * singleton shared across test files.
@@ -228,7 +532,7 @@ export declare class Registry<T = any> {
      * @param namespace - Optional namespace for lookup priority
      * @returns Component configuration or undefined
      */
-    getConfig(type: string, namespace?: string): ComponentConfig<T> | undefined;
+    getConfig(type: string, namespace?: string): RegistryComponentConfig<T> | undefined;
     /**
      * Check if a component type is registered.
      *
@@ -272,12 +576,48 @@ export declare class Registry<T = any> {
      * known", not as "declares no props".
      */
     getMeta(type: string, namespace?: string): ComponentMeta | undefined;
+    /**
+     * The deprecation `type` declares FOR `surface` — or `undefined` when it
+     * declares none there (objectui#6674).
+     *
+     * ## The question this makes askable
+     *
+     * "Is this type deprecated?" — which, before the {@link ComponentDeprecation}
+     * declaration existed, nothing could ask. The only two statements of a
+     * deprecation were a `console.warn` string literal in a renderer and the word
+     * "(Deprecated)" inside a human `label`; no gate, test or type can consult
+     * either. Both gates that touch component types ask whether a type RESOLVES,
+     * and a deprecated type resolves.
+     *
+     * ## Why the caller must name a surface
+     *
+     * Because the honest answer differs by surface, and a reader that dropped the
+     * distinction would let every caller re-derive it — which is how the same
+     * exemption ends up written N times and wrong in N-1 of them. `span` is
+     * deprecated for JSON-authored pages and is vocabulary of the `kind:'html'`
+     * tier (objectui#4000). Asking `deprecationFor('span', 'html')` therefore
+     * correctly answers `undefined` even when the type declares a `'json'`
+     * deprecation, while `deprecationFor('div', 'html')` answers the declaration,
+     * because `div` names both surfaces (objectui#10757). A gate over html-tier
+     * sources gets the right answer for either without knowing the rulings: the
+     * console's html compile reads exactly this to decide what it refuses.
+     *
+     * Returning the DECLARATION rather than a boolean is deliberate: the caller
+     * that has to report the finding also needs `replacement` to say what to
+     * author instead, and a boolean would send it back to the console string.
+     *
+     * Resolution is {@link getMeta}'s, so both spellings of a namespaced
+     * registration answer alike (`div` and `ui:div`), a `skipFallback` type
+     * answers only under its namespaced key, and a pending `registerLazy` stub
+     * answers from the meta it was registered with.
+     */
+    deprecationFor(type: string, surface: AuthoringSurface, namespace?: string): ComponentDeprecation | undefined;
     /**
      * Get all registered component configurations.
      *
      * @returns Array of all component configurations
      */
-    getAllConfigs(): ComponentConfig<T>[];
+    getAllConfigs(): RegistryComponentConfig<T>[];
     /**
      * Resolve `tag` for the CONTRACT surface: the loaded registration when the
      * component is already in the registry, otherwise the metadata of a pending
@@ -290,9 +630,18 @@ export declare class Registry<T = any> {
      */
     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}.
+     * Get the CONTRACT-surface component configs (ADR-0080) — what the published
+     * `sdui.manifest.json` serialises. A subset of the full rendering capability
+     * returned by {@link getAllConfigs}, made of two tiers:
+     *
+     *   - the curated PUBLIC tier — `PUBLIC_BLOCKS` plus registrations that opted
+     *     in with `tier: 'public'` — the JSON-surface AI-authoring vocabulary;
+     *   - the html tier's registered intrinsic elements — `HTML_TIER_INTRINSICS`,
+     *     each entry stamped `tier: 'html'` (objectui#10735). A `kind:'html'` page
+     *     may author these tags and the gate that reads the manifest must accept
+     *     them; they are NOT part of the curated vocabulary, so a consumer that
+     *     means that vocabulary alone — the `kind:'react'` JSX scope, the block
+     *     list, a census of curated blocks — filters on the stamp.
      *
      * Includes blocks that are only lazily registered so far; those come back
      * with `lazy: true` and no `component` (see {@link PublicComponentConfig}).
@@ -304,6 +653,6 @@ export declare class Registry<T = any> {
      * @param namespace - Namespace to filter by
      * @returns Array of component configurations in the namespace
      */
-    getNamespaceComponents(namespace: string): ComponentConfig<T>[];
+    getNamespaceComponents(namespace: string): RegistryComponentConfig<T>[];
 }
 export declare const ComponentRegistry: Registry<any>;