@aglyn/aglyn 1.0.0-beta.143

package/src/lib/plugin-manager/feature-plugins.d.ts

@@ -0,0 +1,1314 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { OrgPermissions } from '../app-utils/org-permissions';
+import type { SeoListingFieldKey } from '../app-utils/seo-listing-fields';
+import type { AglynOrgBilling, OrgFeatureFlags } from '../foundation';
+import type { ComponentSchema, MdiIconProps, PresetSchema } from '../types/nodes';
+import type { Plugin, PluginId } from './plugin-manager';
+import type { HostThemeSource } from '../app-utils/marketplace-theme';
+import type { HostTheme, HostThemeScheme } from '@aglyn/shared-data-types';
+import type { ComponentType } from 'react';
+export type { ConsoleProductCopyValues, ConsoleProductDraft, ConsoleProductEditorZoneProps, ConsoleProductImportZoneProps, ConsoleProductOption, ConsoleProductSummary, ConsoleProductType, ConsoleProductsHubZoneProps, ConsoleProposedDiscount, ConsoleProposedProduct, } from './commerce-zone-props';
+export type { ConsoleImportMappingZoneProps, ConsoleRecordEmailZoneProps, ConsoleRecordInsightsZoneProps, } from './record-zone-props';
+/** The mui bundle id every UI feature bundle depends on. */
+export declare const MUI_BUNDLE_ID: PluginId;
+export interface FeatureBundleEntry {
+    component: any;
+    schema: ComponentSchema<any>;
+    presets?: PresetSchema[];
+}
+/** The slice of ComponentManager a feature bundle needs (structural). */
+export interface ComponentRegistrar {
+    registerComponent(component: any, schema: ComponentSchema<any>): void;
+    registerPreset(presets: PresetSchema[]): void;
+    unregisterComponent(componentId: string): void;
+    unregisterPreset(presetIds: string[]): void;
+}
+export interface UiFeatureBundleOptions {
+    /** Stable bundle id — persisted as `pluginId` in screen docs; never rename. */
+    bundleId: PluginId;
+    displayName: string;
+    description?: string;
+    icon?: MdiIconProps;
+    /** Extra bundle ids this feature needs beyond mui. */
+    dependsOn?: PluginId[];
+    components: FeatureBundleEntry[];
+}
+/**
+ * UI half of the pattern: a plugin-registry bundle whose load/destroy
+ * register the feature's components + presets against the given
+ * registrar (`Aglyn.components` in apps), declared as depending on the
+ * mui bundle so the registry loads mui first.
+ */
+export declare function defineUiFeatureBundle(options: UiFeatureBundleOptions, registrar: ComponentRegistrar): Plugin;
+/**
+ * One of the organization's sites, as the shell hands them to a surface
+ * mounted at the ORGANIZATION level (AGL-2630).
+ *
+ * The three facts a cross-site surface needs and a record never carries: a
+ * record holds a host DOCUMENT ID, a console URL under `/hosts/[host]` takes
+ * the SUBDOMAIN, and a person reads the NAME. `subdomain` is null for a site
+ * whose document did not answer — such a site is still named (the
+ * relationship is real) and never linked (the route would not exist).
+ */
+export interface ConsolePluginOrgHost {
+    id: string;
+    name: string;
+    subdomain: string | null;
+}
+/**
+ * The organization a surface is mounted under when it is mounted at the
+ * org level rather than under a site (AGL-2630).
+ *
+ * The CRM exists at two levels: the site hub, where `hostId` names the site
+ * and every read is scoped to it, and `/[orgSlug]/crm`, where an org-wide
+ * member sees every site's records at once. At the org level there is no
+ * site, so the shell hands the org's own site list instead — the pickers a
+ * create needs (a record is always captured BY a site) and the names a
+ * cross-site fact is shown under. `hostsReady` separates "no sites" from
+ * "not yet".
+ */
+export interface ConsolePluginOrgMount {
+    orgId: string;
+    hosts: readonly ConsolePluginOrgHost[];
+    hostsReady: boolean;
+    /**
+     * The console path every site's own hub hangs beneath — `/[orgSlug]/hosts`
+     * — so a cross-site fact can link a person into the site that holds them:
+     * a site's CRM is `${hostsPath}/${subdomain}/crm`. A path rather than a
+     * builder because the mount is data the shell hands over and a plugin
+     * cannot import the console's route table.
+     */
+    hostsPath: string;
+}
+/**
+ * Props every plugin-contributed console page receives from the shell's
+ * generic host route. The shell owns auth + chrome + flag gating and
+ * passes the resolved host and entitlement state in, so plugin pages stay
+ * free of console-app hooks.
+ */
+export interface ConsolePluginPageProps {
+    /**
+     * The site this surface is mounted under — or `null` when it is mounted at
+     * the ORGANIZATION level, where there is no site and {@link orgMount} says
+     * which org (AGL-2630). Two things mount there: the CRM's own org route,
+     * and every {@link ConsoleExtension.orgNavItems} surface through the
+     * generic org route (AGL-2974). A surface reached through a site route
+     * always receives a string.
+     */
+    hostId: string | null;
+    /** Present only at an org-level mount — see {@link ConsolePluginOrgMount}. */
+    orgMount?: ConsolePluginOrgMount;
+    /** True when the org holds the extension's `featureFlag` entitlement. */
+    entitled: boolean;
+    /**
+     * The absolute console path this surface is mounted at — the nav item's
+     * `href` under the active org and site, e.g. `/acme/hosts/shop/products`
+     * (AGL-2501).
+     *
+     * A plugin page is handed a host DOC ID and nothing else, so building a
+     * link to itself meant resolving the org slug and subdomain from Firestore
+     * — two `getDoc`s that answer `null` on first paint, which for a section
+     * rail means drawing it without hrefs. The shell already knows this string
+     * synchronously; the alternative is paying for it again, later, per page.
+     */
+    basePath?: string;
+    /**
+     * The nav item's declared {@link ConsoleNavItem.sections}, resolved: an
+     * absolute `href` per section, and the release-flag verdict already applied
+     * to `visible` (AGL-2501).
+     *
+     * The plugin DECLARES sections; the shell RESOLVES them. Release flags live
+     * in `scope:app` and a `scope:lib` plugin may not import the hooks that read
+     * them, so a page that filtered its own rail could only do it by guessing —
+     * and a rail offering a link into the shell's own "coming soon" notice is
+     * the guess going wrong. Feed this straight to `HubSections`.
+     */
+    sections?: readonly ResolvedConsoleNavSection[];
+    /**
+     * The id of the section the URL names, or undefined on the nav item's own
+     * href (AGL-2501).
+     *
+     * Always one of the declared `sections` — the shell 404s an id it does not
+     * recognize rather than passing it down, so a page may switch on this
+     * without a fallback branch for a section it does not have.
+     */
+    section?: string;
+    /**
+     * Path segments beneath `basePath`, `[]` on the nav item's own href
+     * (AGL-2501). `segments[0]` is `section`; anything after it is the section's
+     * own, so a section can own deeper routes (`…/orders/ord_123`) without a
+     * further registry change.
+     */
+    segments?: readonly string[];
+    /**
+     * The ORG billing doc (`orgs/{orgId}`) the shell already loaded to
+     * compute `entitled` (prop renamed from `tenant` in AGL-444). Passed
+     * through so a plugin page can run its own `checkEntitlement`/
+     * `checkQuota` (e.g. per-plan service limits) without reaching for the
+     * console-app org/session hooks.
+     */
+    org?: Partial<AglynOrgBilling>;
+    /**
+     * The signed-in user's resolved org permissions (AGL-395), passed through
+     * so a plugin page can gate actions (e.g. install/publish) without the
+     * console-app session/permission hooks.
+     */
+    /**
+     * Widened past the legacy six (AGL-2474): plugin-declared keys such as
+     * commerce's `managePos` are resolved into the same map, and typing this
+     * `Partial<OrgPermissions>` meant a plugin could not read its OWN
+     * permission without a cast — the declared key was not assignable.
+     */
+    permissions?: Partial<OrgPermissions> & Record<string, boolean | undefined>;
+    /**
+     * The verdict for the release flag that governs this surface (AGL-1662),
+     * resolved by the shell from the nav item's `navTabId` — the same flag
+     * `FeatureGate` applies around the page body.
+     *
+     * `FeatureGate` admits staff with the flag OFF, so a plugin page can be
+     * looking at an org that does not have the feature and is not being
+     * billed for it. Anything the page says about MONEY has to follow the
+     * flag rather than the viewer, and this is how a plugin page gets that
+     * answer without reaching for the console-app release-flag hooks (which
+     * live in `scope:app` and are off-limits to a `scope:lib` plugin).
+     */
+    releaseFlag?: {
+        /**
+         * The rollout verdict for this ORG — staff bypass deliberately NOT
+         * applied. `visible` is what decides who sees a page; this is what
+         * decides what the invoice carries, and staff opening a page must not
+         * put a line on a customer's bill.
+         */
+        released: boolean;
+        /**
+         * True once the flag verdict has settled. Release flags are default-off
+         * before Remote Config activation, so an ungated claim asserts the
+         * withheld case for one paint on an org that may well be billed.
+         */
+        ready: boolean;
+    };
+    /**
+     * What the viewer's role on THIS SITE lets them do, for a surface that
+     * publishes.
+     *
+     * The `author` host role edits content and may not make it live; that is
+     * enforced in the Firestore rules and by the promotion routes, and the
+     * console's job is to say no with a reason rather than let a click come
+     * back as a bare `permission-denied`. Resolving it needs the org member
+     * document and the host-access predicate over it, which the shell already
+     * reaches for — a plugin cannot, for the same reason it cannot read a
+     * release flag.
+     *
+     * `loaded` separates "no" from "not yet", so a surface disables with a
+     * reason rather than hiding a control that is about to be allowed. Read it
+     * the safe way round: `canPublish` is false until the read lands.
+     */
+    hostRole?: {
+        canPublish: boolean;
+        loaded: boolean;
+    };
+}
+export type ConsolePluginPage = ComponentType<ConsolePluginPageProps>;
+/**
+ * One routed section of a plugin console page (AGL-2501).
+ *
+ * A section is a real URL beneath the nav item's `href`, not a panel: it is
+ * linkable, the back button walks sections, and the page mounts the one being
+ * read. That last part is the reason this exists — a six-panel hub subscribes
+ * every panel's queries on load, and the reader is looking at one.
+ */
+export interface ConsoleNavSection {
+    /**
+     * URL segment beneath the nav item's `href`, and the id the shell hands the
+     * page as `section`. Appears in links people keep — treat it as persisted.
+     */
+    id: string;
+    label: string;
+    /**
+     * Release-flag nav-tab id gating THIS section, when it ships on a different
+     * schedule than the surface around it. Omit to inherit the nav item's gate,
+     * which is the common case.
+     *
+     * Declaring one NARROWS, never widens: the nav item's own gate is applied
+     * outside this one, so a section of a flagged-off surface stays unreachable
+     * whatever it declares. A section gated by its own flag is refused on a deep
+     * link exactly as it is hidden from the rail — one verdict, both places.
+     */
+    navTabId?: string;
+    /**
+     * Entitlement flag gating THIS section, when the org's plan may include
+     * the surface and not the whole of it (AGL-2611). Omit to inherit the
+     * extension's `featureFlag`, which is the common case.
+     *
+     * Composes by AND with the extension's, the way `navTabId` composes with
+     * the nav item's release gate: the shell answers the extension's flag
+     * first and this one inside it, so a section can only ever be NARROWER
+     * than the surface holding it. A section this refuses is resolved
+     * `locked` for the rail and refused on a deep link with the shell's own
+     * upgrade notice — one verdict, both places — and the page body never
+     * mounts, which is the whole of the shell's promise about entitlements.
+     *
+     * The case it exists for is a hub whose first section ships on every
+     * plan and whose others do not: the CRM's contacts list is on Free, and
+     * the sales suite built on that list starts at Starter.
+     */
+    featureFlag?: keyof OrgFeatureFlags;
+}
+/** A {@link ConsoleNavSection} with the shell's answers filled in. */
+export interface ResolvedConsoleNavSection {
+    id: string;
+    label: string;
+    /** Absolute console path — `${basePath}/${id}`. */
+    href: string;
+    /** False when this section's release flag hides it from this viewer. */
+    visible: boolean;
+    /**
+     * True when the org's SETTLED plan does not carry the section's
+     * `featureFlag` (AGL-2611). The rail draws it locked and still links it —
+     * the notice behind the link is the way to buy it — and the shell refuses
+     * the body. Never true while the org read is pending: an unsettled plan
+     * is not a refusal, and a lock that appeared for one paint on a paying
+     * workspace would be the AGL-1380 defect in a new place.
+     */
+    locked?: boolean;
+}
+export interface ConsoleNavItem {
+    label: string;
+    /**
+     * Host-relative console route (e.g. '/events'). The shell mounts it
+     * under the active host ('/[hostId]/events') via its generic plugin
+     * route, so the same string keys both the nav link and the page.
+     */
+    href: string;
+    icon?: MdiIconProps;
+    /**
+     * Release-flag nav-tab id (e.g. 'nav-tab-events'). Lets the shell apply
+     * the same staff-preview gating hardcoded tabs get; omit for always-on.
+     */
+    navTabId?: string;
+    /**
+     * The permission THIS surface requires, when it is narrower than the
+     * extension's own {@link ConsoleExtension.permission}.
+     *
+     * Declaring one NARROWS, never widens: the extension's requirement is
+     * applied alongside this one and both must be held, so a surface cannot
+     * escape its extension's gate by naming a key its reader happens to have.
+     * The composition is the release-flag one a nav item and its section
+     * already have, for the same reason.
+     *
+     * The granularity exists because one extension can register surfaces with
+     * genuinely different answers — a catalog anyone who edits the site may
+     * open, beside a register that takes money.
+     */
+    permission?: string;
+    /**
+     * Page body rendered by the shell's generic host route. When present,
+     * the plugin owns the whole surface — no core page file needed.
+     */
+    Component?: ConsolePluginPage;
+    /**
+     * Routed sections of this page (AGL-2501). Each becomes a URL at
+     * `${href}/${section.id}`, and the shell tells the page which one it is on.
+     *
+     * Optional, and omitting it is not a lesser option — it means the surface is
+     * ONE page, which is what every plugin surface was before this existed and
+     * what most should stay. A nav item without sections resolves exactly as it
+     * always has: its own href and nothing beneath it, so a path under it is a
+     * 404 rather than this page rendered again.
+     */
+    sections?: readonly ConsoleNavSection[];
+    /**
+     * Whether this nav item claims every path beneath its own href, with no
+     * declared section naming them.
+     *
+     * The case is a surface whose deeper URLs are ENTITIES rather than
+     * sections: `/forms` is a list, `/forms/{formId}` is one of its rows, and
+     * the set of ids is a property of the workspace's data, so no static
+     * `sections` list could enumerate them. Without this a nav item matches its
+     * own href and nothing else, and every row's page is a 404.
+     *
+     * The trade is deliberate and is why it must be asked for. A surface that
+     * owns its subtree can no longer distinguish a typo'd path from an entity
+     * id — `/forms/bogus` reaches the page rather than the shell's 404 — so it
+     * takes on the duty of saying "no such thing" itself, which a list-detail
+     * surface has to be able to do anyway for an id that was deleted while a
+     * link to it was still in someone's inbox.
+     *
+     * Sections win where both are declared: an id the `sections` list names is
+     * resolved as a section, and this only widens what happens when none
+     * matches.
+     */
+    ownsSubtree?: boolean;
+    /**
+     * Hrefs this nav item answered to before it moved (AGL-2595).
+     *
+     * A console path is something people keep — a bookmark, a docs link, an
+     * email from the console itself — and a nav item that changes its `href`
+     * would otherwise turn every one of them into the shell's "not available"
+     * notice. Matching here is identical to matching on `href` (the same
+     * sections, the same subtree rule), and the resolved page carries
+     * `legacy: true` so the shell can replace the address with the current one
+     * rather than leave a moved page living at two.
+     */
+    legacyHrefs?: readonly string[];
+    /**
+     * Dashboard header for the plugin page (title + icon), and the docs topic
+     * its help `?` explains.
+     *
+     * `docsTopic` is a plain string rather than the console's
+     * `DocsHelpTopicKey` because that registry lives in `apps/console` and a
+     * lib cannot import from an app. The console validates it and falls back
+     * to the marketplace topic when it does not resolve — which is not just
+     * defensive: a third-party plugin can name any string, and the alternative
+     * to a fallback is a help button that throws on hover (AGL-1074).
+     *
+     * Every surface mounted by the shell's generic plugin route shares one
+     * `help=` prop, so a surface that omits this is not "help-less" — it
+     * inherits Plugins & Marketplace, which reads as if it were its own.
+     */
+    header?: {
+        title: string;
+        icon?: MdiIconProps;
+        docsTopic?: string;
+    };
+}
+export interface ConsoleDashboardCard {
+    /** Card registry key the dashboard resolves to a component. */
+    cardId: string;
+    title: string;
+}
+export interface ConsoleSettingsSection {
+    sectionId: string;
+    title: string;
+    /** Rendered inside the org/host settings surface when present (AGL-419). */
+    Component?: ComponentType<ConsolePluginPageProps>;
+}
+/**
+ * The injection-zone catalog (AGL-433, Strapi injection-zone parity):
+ * every named slot the console shell renders through `PluginWidgetSlot`,
+ * with what the slot receives. `slot` stays an open string so apps can
+ * add custom zones without a core release; these are the guaranteed ones.
+ */
+export declare const CONSOLE_WIDGET_SLOTS: {
+    /** Host dashboard + screen view activity column. Props: hostId. */
+    readonly hostActivity: "hostActivity";
+    /**
+     * The host dashboard's glance row — one card per capability the site
+     * actually has. Props: hostId.
+     *
+     * The dashboard's own cards used to be imported by the page, which made
+     * enablement a decision nobody was making: `New site users` rendered on a
+     * site that has never turned member accounts on, and `Last campaign` on a
+     * workspace with the email plugin switched off. A card that answers a
+     * question about a capability belongs to the capability, so it registers
+     * here and the shell's entitlement + enablement gate decides.
+     */
+    readonly hostDashboard: "hostDashboard";
+    /**
+     * The organization's sites page, above the site grid (AGL-2636): the
+     * org-level twin of `hostDashboard`, for a card that totals the
+     * organization rather than one site. Props: `hostId` (always `null`),
+     * `orgMount` (the org and its sites — the {@link ConsolePluginOrgMount}
+     * the org-level hub page hands its plugin page), `basePath` (that hub's
+     * own path, `/[orgSlug]/crm`, for the links a widget builds when there is
+     * no site to derive them from).
+     *
+     * Every widget here reads ACROSS the host boundary — an org-wide total
+     * carries no scope clause — which is the one read a site collaborator may
+     * never make, so the page gates the whole row on the org hub's own access
+     * verdict before any widget mounts, and renders nothing at all (no empty
+     * row, no heading) when no widget survives the gates.
+     */
+    readonly orgDashboard: "orgDashboard";
+    /** Host dashboard commerce summary. Props: hostId, org. */
+    readonly commerceGlance: "commerceGlance";
+    /** Org Data page body. Props: orgId, org. */
+    readonly orgData: "orgData";
+    /** Besigner functions (ƒx) panel. Props: hostId. */
+    readonly besignerFunctions: "besignerFunctions";
+    /** Marketplace listing detail body. Props: hostId, listingId, permissions. */
+    readonly marketplaceListing: "marketplaceListing";
+    /**
+     * Org marketplace browse body (AGL-772). Props: hostId (acting site),
+     * permissions, orgScoped. The single org-scope place to browse + install,
+     * replacing the per-site marketplace tab.
+     */
+    readonly orgMarketplace: "orgMarketplace";
+    /** Plugins & add-ons hub installs section. Props: hostId. */
+    readonly orgAddons: "orgAddons";
+    /** Bottom of the host dashboard. Props: hostId, org. (AGL-433) */
+    readonly dashboardFooter: "dashboardFooter";
+    /** Org settings page, below the tabbed cards. Props: orgId, org. */
+    readonly orgSettings: "orgSettings";
+    /** Host setup page, below the built-in cards. Props: hostId, org. */
+    readonly hostSettings: "hostSettings";
+    /**
+     * The top of the page a newly created site lands on (AGL-2918): where a
+     * widget may offer to START the site for the person rather than leave them
+     * an empty one. Props: {@link ConsoleHostFirstRunZoneProps}.
+     *
+     * ── The blank path is the default, not the fallback ──────────────────────
+     *
+     * The site already exists, blank, and the page beneath this zone is the
+     * ordinary one every site gets. A widget here is an OFFER on top of that
+     * page: it asks the person what they want, it builds only what they then
+     * confirm, and everything it makes is a draft the site does not serve.
+     *
+     * So a zone with no widget — no plugin loaded, a feature not released, a
+     * reader without the permission — is not a degraded state. It is the blank
+     * path, unchanged and complete, which is why nothing on the page below
+     * depends on anything here.
+     *
+     * ── A widget here MUST offer `startBlank` ────────────────────────────────
+     *
+     * A guided start that a person cannot leave turns creating a site into a
+     * funnel, so `startBlank` is handed down rather than left to each widget to
+     * invent: a widget draws it where its questions START, not at the end of
+     * them, and taking it leaves the person on this same page with nothing
+     * begun behind them. The shell remembers the choice for this site and stops
+     * asking.
+     *
+     * A widget that takes the screen rather than sitting on the page — a full
+     * screen dialog, an overlay — owes the same exit in every shape it has one:
+     * a close control, and the key a person presses to dismiss it. Each of them
+     * is `startBlank`, because a takeover somebody can only dismiss BACK INTO is
+     * the funnel this zone exists to refuse, and nothing here is a half-answered
+     * state worth returning to.
+     */
+    readonly hostFirstRun: "hostFirstRun";
+    /**
+     * The host setup Theme section, between the "What you have changed" card
+     * and the editor (AGL-2938). Props: {@link ConsoleHostThemeZoneProps} — the
+     * site, the theme the editor shows, where that theme came from, the
+     * editor's own preview, and `proposeDraft`, which puts a theme in the
+     * editor as unsaved changes.
+     *
+     * A widget here proposes and never writes. The person saves what it
+     * proposed through the editor's own Save — the guarded write that stores
+     * an installed theme's edits as its override patch — or discards it. A
+     * palette importer, a brand kit and a generator are the same shape of
+     * widget.
+     */
+    readonly hostTheme: "hostTheme";
+    /**
+     * Staff admin org detail (staff-only surfaces). Props: orgId. A staff
+     * zone — see {@link CONSOLE_STAFF_WIDGET_SLOTS}.
+     */
+    readonly adminOrgDetail: "adminOrgDetail";
+    /**
+     * Billing → Usage, below the meters (AGL-2940). Props: `orgId`, `org` (the
+     * billing-merged org doc), `canManage` (the reader holds
+     * `billing.manage`). A card here explains or controls consumption the
+     * meters above it show.
+     */
+    readonly orgBillingUsage: "orgBillingUsage";
+    /**
+     * Billing → Overview, among the plan and add-on cards (AGL-2940). Props:
+     * `orgId`, `org`, `plan` (the page's own defaulted plan), `canManage`.
+     */
+    readonly orgBillingOverview: "orgBillingOverview";
+    /**
+     * The staff org page, among its cards (AGL-2940). Props: `orgId`. Staff
+     * only — the page is behind `StaffOnly`, and a widget here may read the
+     * staff-only routes. A staff zone — see {@link CONSOLE_STAFF_WIDGET_SLOTS}.
+     */
+    readonly staffOrg: "staffOrg";
+    /**
+     * The staff user page, below the account's activity. Props: `uid`. A
+     * staff zone — see {@link CONSOLE_STAFF_WIDGET_SLOTS}.
+     */
+    readonly staffUser: "staffUser";
+    /**
+     * A COLUMN of the staff Organizations list (AGL-2984) — see
+     * {@link ConsoleWidget.column}. The list renders the widget's component
+     * once per row with `{ row, orgId, orgIds }`: the row as the list route
+     * serves it, that row's org id, and every org id on the page, so a column
+     * that reads figures of its own asks once for the page rather than once
+     * per row. Its `Header` receives `{ orgIds }` beside the sort props. A
+     * staff zone — see {@link CONSOLE_STAFF_WIDGET_SLOTS}.
+     */
+    readonly staffOrgsListColumn: "staffOrgsListColumn";
+    /**
+     * The staff org usage table (AGL-2984): the monthly rollups on the staff
+     * org page and in the Organizations list's usage dialog. A widget with a
+     * `column` is a column of the table, between Forms and Cost, rendered once
+     * per month with `{ month, orgId }` — `month` is the rollup row as
+     * `/api/admin/org-usage` serves it. A widget without one renders above
+     * the table with `{ orgId, org }`, where `org` is the org document when the
+     * surface holds one and `undefined` when it does not. A staff zone — see
+     * {@link CONSOLE_STAFF_WIDGET_SLOTS}.
+     */
+    readonly staffOrgUsageColumn: "staffOrgUsageColumn";
+    /**
+     * The org's team member detail page, below the member's activity
+     * (AGL-2940). Props: `orgId`, `orgSlug`, `uid`, `member` (the org member
+     * document as the page loaded it), `hosts` (the org's sites, for naming
+     * them), `canManage` (the reader may manage the org).
+     */
+    readonly orgMember: "orgMember";
+    /**
+     * A COLUMN of the org Team table (AGL-2940) — see
+     * {@link ConsoleWidget.column}: the widget declares the header and the
+     * shell renders its component once per row with `{ member, orgId,
+     * canManage }`. A widget on this slot without a `column` renders nothing.
+     */
+    readonly orgMembersListColumn: "orgMembersListColumn";
+    /**
+     * The site collaborators card (AGL-2940). A widget with a `column` is a
+     * column of its table, rendered per row with `{ member, orgId, hostId,
+     * canManage }` — the owner's row too, with `member` carrying the owner's
+     * `uid` and `role: 'owner'`; a widget without one renders beneath the
+     * table with `{ hostId, canManage }`.
+     */
+    readonly hostMembers: "hostMembers";
+    /**
+     * The console shell's assistant dock (AGL-2940): the one position above
+     * every route boundary in both the `(app)` and `(editor)` shells, where a
+     * floating helper survives a navigation. Props: none — a widget here
+     * resolves its own scope from the URL, as the shell's own chrome does.
+     */
+    readonly assistPanel: "assistPanel";
+    /**
+     * A section at the bottom of the besigner's Attributes panel (AGL-2940),
+     * under the selected element's own fields. Props: `hostId` (`null` on an
+     * editor that names no site), and `node`, the selected element (AGL-2984)
+     * — present wherever the designer draws the panel for a selection.
+     */
+    readonly besignerInspector: "besignerInspector";
+    /**
+     * Inside a SEARCH LISTING editor (AGL-2910), under its fields. Props:
+     * {@link ConsoleSeoFieldsZoneProps} — what the listing describes, the
+     * fields the editor edits and what they hold, and `proposeValues`, which
+     * stages values in those fields as unsaved edits.
+     *
+     * Two editors host it: the screen detail page's SEO card, and the commerce
+     * product editor's search engine listing, which draws it through
+     * `useConsoleWidgetSlot` because a plugin's dialog cannot mount the shell's
+     * slot itself. A widget here proposes and never writes: the editor's own
+     * Save is the write, with the guards that write carries. A keyword checker,
+     * a translation memory and a generator are the same shape of widget.
+     */
+    readonly seoFields: "seoFields";
+    /**
+     * The host setup SEO section, above the site SEO form (AGL-2910). Props:
+     * {@link ConsoleHostSeoZoneProps} — the site, its stored SEO settings, and
+     * `proposeDraft`, which puts values in the form as unsaved edits. The
+     * form's Update stores them; nothing a widget proposes reaches the
+     * published site before that.
+     */
+    readonly hostSeo: "hostSeo";
+    /** {@link ConsoleRecordInsightsZoneProps} */
+    readonly recordInsights: "recordInsights";
+    /** {@link ConsoleRecordEmailZoneProps} */
+    readonly recordEmail: "recordEmail";
+    /** {@link ConsoleImportMappingZoneProps} */
+    readonly importMapping: "importMapping";
+    /**
+     * The besigner's secondary toolbar, after the undo and redo controls
+     * (AGL-2984), on every editor the designer opens: screens, layouts,
+     * components, forms, templates and email designs. A control here acts on
+     * the document in the editor. Props: `hostId` (`null` on an editor that
+     * names no site).
+     */
+    readonly besignerToolbar: "besignerToolbar";
+    /**
+     * A site's Screens page, beside its Templates and Create New Screen actions
+     * (AGL-2907): another way to start a screen. Props:
+     * {@link ConsoleHostScreensZoneProps}. A widget here runs its own flow and
+     * writes nothing through the page; the screens list shows what it makes once
+     * it exists.
+     */
+    readonly hostScreens: "hostScreens";
+    /**
+     * A site's Templates page, beside its Create Template action (AGL-3043):
+     * another way to start a template. Props:
+     * {@link ConsoleHostTemplatesZoneProps}. The `hostScreens` contract: a
+     * widget here runs its own flow and writes nothing through the page, and
+     * the template list shows what it makes once it exists.
+     */
+    readonly hostTemplates: "hostTemplates";
+    /**
+     * A site's Layouts page, beside its Templates and Create New Layout actions
+     * (AGL-3043): another way to start a layout. Props:
+     * {@link ConsoleHostLayoutsZoneProps}, on the `hostScreens` contract.
+     */
+    readonly hostLayouts: "hostLayouts";
+    /**
+     * The Forms page of a site, beside its Create Form action (AGL-3043):
+     * another way to start a form. Props: {@link ConsoleHostFormsZoneProps}, on
+     * the `hostScreens` contract.
+     *
+     * The Forms page is the forms plugin's own surface, so the plugin HOSTS
+     * this zone: it draws the renderer `useConsoleWidgetSlot` hands down, as
+     * the product editor draws `seoFields`, and every gate a console page's
+     * slot applies applies here too.
+     */
+    readonly hostForms: "hostForms";
+    /**
+     * A site's Components page, beside its Templates and Create Component
+     * actions (AGL-3051): another way to start a reusable component. Props:
+     * {@link ConsoleHostComponentsZoneProps}, on the `hostScreens` contract.
+     */
+    readonly hostComponents: "hostComponents";
+    /**
+     * The organization's sites page, beside the sites themselves (AGL-2911):
+     * an action a member takes across MANY of the org's sites at once, rather
+     * than a card totaling them. Props: {@link ConsoleOrgSitesZoneProps}.
+     *
+     * Distinct from `orgDashboard`, which is on the same page and gated on the
+     * org CRM hub's reach verdict because every card there reads across the
+     * host boundary. A widget here reads nothing of the kind: the sites it acts
+     * on are the ones the page already resolved for this reader, and its own
+     * door proves the reader's permission on each of them again. So the zone
+     * carries no gate beyond the slot's own — enablement, entitlement, and the
+     * widget's declared permission.
+     */
+    readonly orgSites: "orgSites";
+    /**
+     * The Automation page's Actions, beside Add action and Recipes (AGL-2919):
+     * another way to start an automation. Props:
+     * {@link ConsoleHostAutomationsZoneProps}.
+     *
+     * The Automation page is the workflows plugin's own surface, so the plugin
+     * HOSTS this zone through the renderer `useConsoleWidgetSlot` hands down, as
+     * the product editor hosts `seoFields`, and every gate a console page's slot
+     * applies applies here too. A widget here writes nothing through the page:
+     * the Actions list shows what it makes once it exists, and `openAction`
+     * opens a listed action in the Actions editor.
+     */
+    readonly hostAutomations: "hostAutomations";
+    /**
+     * The editor of one SAVED automation — an action or a workflow — on the
+     * Automation page (AGL-2919). Props: {@link ConsoleAutomationEditorZoneProps}.
+     * Hosted by the workflows plugin, as `hostAutomations` is. A widget here
+     * reads the automation as it is stored and changes nothing in the editor.
+     */
+    readonly automationEditor: "automationEditor";
+    /**
+     * One FAILED run in an automation's run history (AGL-2919), drawn once per
+     * failed row. Props: {@link ConsoleAutomationRunZoneProps}. Hosted by the
+     * workflows plugin. A widget here reads the run as it was recorded and
+     * changes nothing.
+     */
+    readonly automationRun: "automationRun";
+    /** The commerce product editor's fields (AGL-2916). Props: {@link ConsoleProductEditorZoneProps}. */
+    readonly productEditor: "productEditor";
+    /** Above the commerce products hub's catalog table (AGL-2916). Props: {@link ConsoleProductsHubZoneProps}. */
+    readonly productsHub: "productsHub";
+    /** Inside the commerce CSV import dialog (AGL-2916). Props: {@link ConsoleProductImportZoneProps}. */
+    readonly productImport: "productImport";
+};
+export type ConsoleWidgetSlot = (typeof CONSOLE_WIDGET_SLOTS)[keyof typeof CONSOLE_WIDGET_SLOTS];
+/** What the `hostScreens` zone hands each widget (AGL-2907). */
+export interface ConsoleHostScreensZoneProps {
+    hostId: string;
+    /** The org the page names; `undefined` while it resolves. */
+    orgId: string | undefined;
+}
+/**
+ * What the `hostTemplates`, `hostLayouts` and `hostForms` zones (AGL-3043) and
+ * the `hostComponents` zone (AGL-3051) hand each widget: the site and its org,
+ * as `hostScreens` hands them.
+ */
+export type ConsoleHostTemplatesZoneProps = ConsoleHostScreensZoneProps;
+/** See {@link ConsoleHostTemplatesZoneProps}. */
+export type ConsoleHostLayoutsZoneProps = ConsoleHostScreensZoneProps;
+/** See {@link ConsoleHostTemplatesZoneProps}. */
+export type ConsoleHostFormsZoneProps = ConsoleHostScreensZoneProps;
+/** See {@link ConsoleHostTemplatesZoneProps}. */
+export type ConsoleHostComponentsZoneProps = ConsoleHostScreensZoneProps;
+/** What the `hostAutomations` zone hands each widget (AGL-2919). */
+export interface ConsoleHostAutomationsZoneProps {
+    hostId: string;
+    /** The org the page names; `undefined` while it resolves. */
+    orgId: string | undefined;
+    /**
+     * Opens the Actions editor on a listed action. `false` when the id names no
+     * action the list has read yet, which is how a widget whose draft was just
+     * written tells a list that has not caught up from one that opened it.
+     */
+    openAction: (actionId: string) => boolean;
+}
+/** One automation on the Automation page: an action, or a workflow (AGL-2919). */
+export interface ConsoleAutomationTarget {
+    type: 'action' | 'workflow';
+    id: string;
+    name: string;
+}
+/** What the `automationEditor` zone hands each widget (AGL-2919). */
+export interface ConsoleAutomationEditorZoneProps {
+    hostId: string;
+    /** The org the page names; `undefined` while it resolves. */
+    orgId: string | undefined;
+    /** The automation the editor has open, as it is stored. */
+    target: ConsoleAutomationTarget;
+}
+/** What the `automationRun` zone hands each widget (AGL-2919). */
+export interface ConsoleAutomationRunZoneProps {
+    hostId: string;
+    /** The org the page names; `undefined` while it resolves. */
+    orgId: string | undefined;
+    /** The automation the run belongs to. */
+    target: ConsoleAutomationTarget;
+    /** The run's entry in the site's activity log. */
+    runId: string;
+}
+/** What the `orgSites` zone hands each widget (AGL-2911). */
+export interface ConsoleOrgSitesZoneProps {
+    /** Always `null`: the zone belongs to the organization, not to one site. */
+    hostId: null;
+    /** The org and the sites the page resolved for this reader. */
+    orgMount: ConsolePluginOrgMount;
+    /** The sites page's own path, for the links a widget builds. */
+    basePath: string;
+}
+/** What the `hostFirstRun` zone hands each widget (AGL-2918). */
+export interface ConsoleHostFirstRunZoneProps {
+    hostId: string;
+    /** The org the page names; `undefined` while it resolves. */
+    orgId: string | undefined;
+    /** Path slug for building `/[orgSlug]/…` links. */
+    orgSlug: string;
+    /** The site's subdomain, which is what a console URL names a site by. */
+    host: string | null;
+    /**
+     * Leaves the guided start for the blank site the person already has: this
+     * same page, with nothing created and nothing begun. The shell records the
+     * choice for this site and draws the zone no more.
+     *
+     * Required of every widget on this zone, drawn where its questions start
+     * rather than after them, and — for a widget that takes the screen — what
+     * every way of dismissing it does. See `hostFirstRun` in
+     * {@link CONSOLE_WIDGET_SLOTS}.
+     */
+    startBlank: () => void;
+}
+/** What the `hostTheme` zone hands each widget (AGL-2938). */
+export interface ConsoleHostThemeZoneProps {
+    hostId: string;
+    /** The org the page names; `undefined` while it resolves. */
+    orgId: string | undefined;
+    /** Path slug for building `/[orgSlug]/…` links. */
+    orgSlug: string;
+    /** The site's subdomain, which is what a console URL names a site by. */
+    host: string | null;
+    /** The theme the editor shows: the site's theme with its overrides resolved. */
+    theme: HostTheme | undefined;
+    /** Where that theme came from, which decides how an edit to it is stored. */
+    themeSource: HostThemeSource;
+    /** The editor's own preview, which renders a theme over the brand base. */
+    ThemePreview: ComponentType<{
+        theme: HostTheme;
+        scheme: HostThemeScheme;
+    }>;
+    /**
+     * Puts `theme` in the editor as unsaved changes under `key`. A new key
+     * replaces the previous draft; the same key again changes nothing until
+     * the editor has saved or discarded it.
+     */
+    proposeDraft: (theme: HostTheme, key: string) => void;
+}
+/**
+ * The zones on the STAFF pages (AGL-2939): the staff org page, its detail
+ * zone, and the staff user page.
+ *
+ * No workspace names the plugin set there. A staff page is ABOUT an org or
+ * an account, and the reader's own memberships have nothing to do with what
+ * it shows, so the console reads these zones from the plugins it loads for
+ * the staff area — every plugin that declares a `staff` register surface —
+ * and consults neither a widget's entitlement nor its permission: both are
+ * answers about a workspace, and the staff area's guard is what admits the
+ * reader.
+ */
+export declare const CONSOLE_STAFF_WIDGET_SLOTS: readonly ConsoleWidgetSlot[];
+/** Whether a slot is one of the {@link CONSOLE_STAFF_WIDGET_SLOTS}. */
+export declare function isConsoleStaffWidgetSlot(slot: string): boolean;
+/** Search listing values by field; a field the editor does not hold is absent. */
+export type ConsoleSeoFieldValues = Partial<Record<SeoListingFieldKey, string>>;
+/**
+ * What a search listing describes (AGL-2910). A screen is read from its own
+ * documents by whoever needs more than its name; a product travels with its
+ * name and description, because the product document is the commerce
+ * plugin's and nothing else reads it.
+ */
+export type ConsoleSeoFieldsSubject = {
+    kind: 'screen';
+    /** The screen document id. */
+    id: string;
+    /** The version the page is showing, whose content the listing is about. */
+    versionId: string | null;
+    name: string;
+} | {
+    kind: 'product';
+    /** `null` for a product that has not been saved yet. */
+    id: string | null;
+    name: string;
+    description: string;
+};
+/** What the `seoFields` zone hands each widget (AGL-2910). */
+export interface ConsoleSeoFieldsZoneProps {
+    hostId: string;
+    /** The org the page names; `undefined` while it resolves. */
+    orgId: string | undefined;
+    /** Path slug for building `/[orgSlug]/…` links. */
+    orgSlug: string;
+    subject: ConsoleSeoFieldsSubject;
+    /**
+     * The fields this editor edits, in its order — the only ones a widget may
+     * propose. Keys of the `seo-listing-fields` catalog, which carries each
+     * field's label and length.
+     */
+    fields: readonly SeoListingFieldKey[];
+    /** What each field holds as the editor shows it: saved, or staged and unsaved. */
+    values: ConsoleSeoFieldValues;
+    /** Whether the listing has a social image — an image description needs one. */
+    hasImage: boolean;
+    /**
+     * Stages `values` in the editor as unsaved edits under `key`. Fields the
+     * editor does not edit are ignored. The editor's own Save is what stores
+     * them; a widget never writes the listing itself.
+     */
+    proposeValues: (values: ConsoleSeoFieldValues, key: string) => void;
+}
+/** What the `hostSeo` zone hands each widget (AGL-2910). */
+export interface ConsoleHostSeoZoneProps {
+    hostId: string;
+    /** The org the page names; `undefined` while it resolves. */
+    orgId: string | undefined;
+    /** Path slug for building `/[orgSlug]/…` links. */
+    orgSlug: string;
+    /** The site's subdomain, which is what a console URL names a site by. */
+    host: string | null;
+    /** The site's stored `seo` settings, as the form was seeded with them. */
+    seo: Record<string, unknown> | undefined;
+    /**
+     * Puts `values` in the site SEO form as unsaved edits, keyed by the form's
+     * field names (`seo.entity.description`, `seo.agent.whenToUse`). Proposals
+     * land in the form's draft beside what was typed, the same `key` twice
+     * applies once, and the form's Update is what stores them.
+     */
+    proposeDraft: (values: Record<string, string>, key: string) => void;
+}
+/**
+ * A column a widget contributes to a shell-owned table (AGL-2940) — the org
+ * Team table and the site collaborators table read these. The widget's
+ * `Component` is the CELL renderer, mounted once per row with the row as a
+ * prop beside the slot's own props; the header and the sort key are the
+ * table's to draw.
+ */
+export interface ConsoleWidgetColumn {
+    /** The header cell's text, and the column's name wherever it is listed. */
+    header: string;
+    /**
+     * The row field a table that sorts orders this column by. Carried for
+     * every column contract so a sortable table can honor it; the two member
+     * tables render in fetch order and do not read it today.
+     */
+    sortKey?: string;
+    align?: 'left' | 'right' | 'center';
+    /**
+     * The header cell's content when a plain `header` is not enough
+     * (AGL-2939): a hint, or a sort over values only the plugin can read.
+     * Mounted once per table with the slot's props beside
+     * {@link ConsoleWidgetColumnHeaderProps}; without it the table draws
+     * `header` as text.
+     */
+    Header?: ComponentType<any>;
+}
+/**
+ * What a column's own header receives beside the slot's props (AGL-2939).
+ * The table keeps one sort at a time, so a column that sorts replaces
+ * another's order.
+ */
+export interface ConsoleWidgetColumnHeaderProps {
+    /**
+     * Hands the table a row comparator, or `null` to put the rows back in the
+     * table's own order. Stable for the life of the table.
+     */
+    onSort: (compare: ((a: never, b: never) => number) | null) => void;
+    /** Whether the rows are in this column's order. */
+    sorted: boolean;
+}
+/**
+ * A component a plugin renders into a NAMED console slot (AGL-419/433) —
+ * see {@link CONSOLE_WIDGET_SLOTS} for the guaranteed zones and their
+ * props. The shell owns placement; the plugin owns the UI.
+ */
+export interface ConsoleWidget {
+    slot: string;
+    /**
+     * Present when the widget is a table COLUMN rather than a card (AGL-2940)
+     * — see {@link ConsoleWidgetColumn}. Only the slots documented as column
+     * slots read it; elsewhere it is ignored.
+     */
+    column?: ConsoleWidgetColumn;
+    /**
+     * Stable identity for this widget, unique within the plugin per slot.
+     * The id names the CARD, not its placement: the same card registered on
+     * a second slot — the CRM's glance on the host dashboard and again on the
+     * org's sites page — carries one id on both.
+     *
+     * A PERSISTED IDENTIFIER wherever the shell lets someone arrange the
+     * surface it lands on — the console stores dashboard cards a reader has
+     * switched off by this string, and reads it back sessions later. Giving a
+     * retired id to a different card therefore shows that reader an
+     * arrangement they never chose. Retire an id by leaving it reserved and
+     * minting a new one, never by reusing it.
+     */
+    widgetId: string;
+    /**
+     * What to call this widget where it is LISTED rather than rendered — the
+     * console's dashboard customize dialog is the one such place today.
+     *
+     * Match the card's own heading: the two names sit a click apart, and a
+     * switch labeled differently from the card it controls reads as a switch
+     * for something else. Omitting it falls back to the extension's
+     * `displayName`, which is right for a plugin contributing one card and
+     * ambiguous for one contributing several.
+     */
+    title?: string;
+    /**
+     * The permission a reader must hold for this card, when it is narrower
+     * than its extension's own {@link ConsoleExtension.permission}.
+     *
+     * Composes by AND with the extension's, like a nav item's does: a widget
+     * cannot escape its extension's gate by naming a key its reader happens to
+     * hold, and declaring nothing here inherits the extension's requirement
+     * rather than clearing it.
+     *
+     * A card is a surface the reader never asked for — the shell drops it onto
+     * a page they opened for something else — so there is nowhere in it to put
+     * an upsell or a refusal, and a widget its reader may not have is simply
+     * absent. That is the same treatment the entitlement gate gives a widget,
+     * and for the same reason.
+     */
+    permission?: string;
+    /**
+     * The entitlement THIS card needs, when it is narrower than its
+     * extension's {@link ConsoleExtension.featureFlag} (AGL-2611).
+     *
+     * Composes by AND with the extension's, exactly as `permission` above
+     * does: a card cannot escape its extension's gate by declaring nothing,
+     * and declaring one here can only narrow. The case is an extension whose
+     * surface ships on every plan while one of its cards belongs to a paid
+     * part of it. Absent without an upsell, for the reason `permission` gives.
+     */
+    featureFlag?: keyof OrgFeatureFlags;
+    Component: ComponentType<any>;
+}
+/**
+ * Console half of the pattern: everything a feature contributes to the
+ * console shell. Declarative — the shell owns rendering and applies the
+ * feature-flag gate, so extensions cannot bypass entitlements.
+ *
+ * That sentence describes `apps/console/utils/extension-entitlement.ts`,
+ * which the plugin route and `PluginWidgetSlot` both call before they mount
+ * anything an extension registered (AGL-2484). It was an aspiration until
+ * then: the route resolved the entitlement and handed it to the extension as
+ * the `entitled` PROP, and the widget slot did not resolve it at all, so
+ * enforcement rested on each extension policing itself — which one
+ * first-party page did not do.
+ *
+ * What the gate covers, exactly: a `featureFlag` refuses to RENDER the
+ * extension's page body and its widgets. Nav items stay visible on purpose.
+ * Hiding the tab would hide the only route most workspaces have to the page
+ * that sells the feature, and a nav entry leading to the shell's own upgrade
+ * notice bypasses nothing.
+ *
+ * TWO QUESTIONS, BOTH ANSWERED BY THE SHELL. `featureFlag` is about the
+ * organization's plan; `permission` is about the person reading, and it is
+ * enforced in the same place and the same way — resolved from the member's
+ * own permission map, never from anything the extension supplies, and read
+ * before the surface is constructed. An extension declares what it requires
+ * and the shell decides whether the requirement is met, so the sentence
+ * above holds for authorization as well as for entitlements.
+ */
+/**
+ * What a blocked org is told about a feature it does not hold, in the
+ * extension's own words.
+ *
+ * PRESENTATION ONLY. The shell decides entitlement from the org billing doc
+ * and this extension's `featureFlag`, and reads this object solely to render
+ * a refusal it has ALREADY decided on. Nothing here is an input to that
+ * decision, and an extension supplying it gains no access — the surface it
+ * describes stays unmounted either way.
+ *
+ * It exists because the shell's own copy can only speak in generalities. An
+ * entitlement that no plan grants — one sold as a per-organization add-on —
+ * is described exactly wrong by "not included in your current plan", which
+ * sends the reader to compare plan tiers that would not have helped.
+ */
+export interface ConsoleUpgradeNotice {
+    /**
+     * The sentence a blocked org reads. Plain text: the shell renders it as a
+     * string, never as markup, and a third-party extension writes this.
+     */
+    message: string;
+    /**
+     * Which card on the billing page sells it, as a bare fragment id
+     * ('addons'). The console validates it against the anchors that page
+     * actually has and drops it otherwise — the `docsTopic` treatment, for the
+     * same reason: an extension can name any string, and an unrecognized one
+     * must degrade to the plain Billing link rather than build a dead URL.
+     *
+     * Deliberately not an href. A full URL from an extension would be an
+     * open redirect rendered by the console's own chrome; the shell keeps
+     * ownership of the route and accepts only which part of it to scroll to.
+     */
+    billingAnchor?: string;
+}
+/** What the console's generic staff route hands a staff page. */
+export interface ConsoleStaffPageProps {
+    /** The page's own console path, `/admin/{id}`. */
+    basePath: string;
+}
+/**
+ * A page a plugin adds to the STAFF area (AGL-2939): a tab in the staff
+ * strip and a page at `/admin/{id}`, rendered by the console's generic staff
+ * route. The shell owns the layout, the header, the breadcrumbs, the staff
+ * guard and the tab; the plugin owns the body.
+ *
+ * Staff pages load with the staff area's plugins — those declaring a `staff`
+ * register surface — not with a workspace's, because no org names the plugin
+ * set on `/admin`. They are admitted by the staff claim alone, so the
+ * extension's `featureFlag` and `permission` do not apply, and every read a
+ * staff page makes is refused server-side to a caller without the claim.
+ */
+export interface ConsoleStaffPage {
+    /**
+     * The URL segment under `/admin`, and the page's identity. The console's
+     * own staff routes win a segment they use, so pick one they do not. It is
+     * in links staff keep — treat it as persisted.
+     */
+    id: string;
+    /** The tab's label in the staff strip. */
+    label: string;
+    /**
+     * The page header (title and icon), and the docs topic its help `?`
+     * explains — a plain string for the reason {@link ConsoleNavItem.header}
+     * gives, validated by the console.
+     */
+    header?: {
+        title: string;
+        icon?: MdiIconProps;
+        docsTopic?: string;
+    };
+    Component: ComponentType<ConsoleStaffPageProps>;
+}
+export interface ConsoleExtension {
+    pluginId: PluginId;
+    displayName: string;
+    /** Entitlement flag gating every surface this extension registers. */
+    featureFlag?: keyof OrgFeatureFlags;
+    /**
+     * The permission a reader must hold for every surface this extension
+     * registers — the AUTHORIZATION half of the sentence above `featureFlag`.
+     *
+     * `featureFlag` answers what the ORGANIZATION bought; this answers what
+     * the PERSON reading may open, and the two are independent: an org can
+     * hold a feature that most of its members have no business using.
+     *
+     * A key in the console's permission vocabulary, which is two spaces and
+     * they are not interchangeable. Either a dotted {@link OrgPermission} from
+     * the built-in catalog ('data.manage'), which the shell answers from the
+     * member's resolved granular map; or a key some plugin declared through
+     * `registerPluginPermissions` ('managePos'), which the shell answers from
+     * the resolved permission map that carries those keys. A key belonging to
+     * NEITHER space refuses the surface rather than passing it — a requirement
+     * nothing can answer is not a requirement that has been met.
+     *
+     * Declared here rather than checked inside the page for the reason the
+     * entitlement gate moved out of the pages: a check the extension performs
+     * on itself is enforcement only for as long as every extension remembers
+     * to perform it, and the surface has already mounted and opened its
+     * listeners by the time it runs.
+     *
+     * Omit for a surface every member of the workspace may open.
+     */
+    permission?: string;
+    /**
+     * Refusal copy for an org that does not hold `featureFlag`, rendered by
+     * the shell in place of the surface. Omit to get the shell's generic
+     * plan-tier sentence.
+     */
+    upgradeNotice?: ConsoleUpgradeNotice;
+    navItems?: ConsoleNavItem[];
+    /**
+     * Surfaces mounted at the ORGANIZATION level rather than under a site
+     * (AGL-2974): each is served at `/[orgSlug]{href}` by the console's generic
+     * org route and listed on the organization's tab strip.
+     *
+     * A separate list rather than a flag on {@link ConsoleNavItem}, because the
+     * two levels are read by different consumers. The site strip, the site
+     * route and every title and section lookup iterate `navItems`, and a scope
+     * field on one of those entries would reach each of them as a site surface
+     * until every one of them learned to skip it. Nothing that reads `navItems`
+     * sees these.
+     *
+     * The same contract a site nav item has, with the site taken away: the
+     * page receives `hostId: null` and an `orgMount` naming the organization
+     * and its sites, sections resolve and gate the same way, and the
+     * extension's `featureFlag` and `permission` apply unchanged. The shell
+     * admits only a reader whose reach is the whole organization, because a
+     * surface with no site has no scope to narrow a site collaborator to.
+     *
+     * The href must not name one of the console's own organization routes
+     * (`/hosts`, `/team`, `/settings`, `/crm` and the rest): a named route
+     * always wins over the generic one, so such a surface would never render.
+     */
+    orgNavItems?: ConsoleNavItem[];
+    dashboardCards?: ConsoleDashboardCard[];
+    settingsSections?: ConsoleSettingsSection[];
+    /** Slot-addressed components the shell renders in place (AGL-419). */
+    widgets?: ConsoleWidget[];
+    /**
+     * Pages in the STAFF area (AGL-2939) — see {@link ConsoleStaffPage}.
+     * Neither `featureFlag` nor `permission` applies to them.
+     */
+    staffPages?: readonly ConsoleStaffPage[];
+    /**
+     * App-level providers the shell mounts around every console page
+     * (AGL-419) — e.g. the marketplace plugin's AI-assist provider.
+     */
+    providers?: Array<ComponentType<any>>;
+}
+/** Idempotent by pluginId — re-registration replaces the previous entry. */
+export declare function registerConsoleExtension(extension: ConsoleExtension): void;
+export declare function unregisterConsoleExtension(pluginId: PluginId): void;
+/**
+ * Registration-ordered extensions; the console shell filters by flag.
+ *
+ * AGL-758: the registry is a module-global that only ever grows — nothing
+ * outside tests unregisters, and loaded chunks can't unload — so after
+ * visiting two workspaces it holds the UNION of both plugin sets. Every
+ * read is therefore scoped by the caller's effective enabled set; pass the
+ * current org's plugin ids so one workspace never serves another's nav
+ * items, widgets, pages or providers. Omitting the argument keeps the
+ * unfiltered union (tests, and non-org surfaces that have no such set).
+ */
+export declare function listConsoleExtensions(enabledPluginIds?: readonly PluginId[]): ConsoleExtension[];
+/** A nav item flattened with its owning extension's id + entitlement flag. */
+export interface ConsoleNavEntry extends ConsoleNavItem {
+    pluginId: PluginId;
+    featureFlag?: keyof OrgFeatureFlags;
+}
+/**
+ * Every registered nav item, flattened for the shell's nav strip. The
+ * shell appends these to its static tabs, so a plugin adds a menu item
+ * by registering here — no edit to the console's nav constants.
+ */
+export declare function listConsoleNavItems(enabledPluginIds?: readonly PluginId[]): ConsoleNavEntry[];
+/** What {@link resolveConsolePluginPage} answers for a matched href. */
+export interface ResolvedConsolePluginPage {
+    extension: ConsoleExtension;
+    navItem: ConsoleNavItem;
+    /**
+     * The section the href names, when the nav item declares sections and the
+     * href reaches past its own. Undefined on the nav item's own href.
+     */
+    section?: ConsoleNavSection;
+    /** Path segments beneath `navItem.href`; `[]` on the nav item's own href. */
+    segments: readonly string[];
+    /**
+     * The href was one of the nav item's `legacyHrefs`, not its current one.
+     * The shell redirects to `navItem.href` plus the same section and segments.
+     */
+    legacy?: boolean;
+}
+/**
+ * Resolves a host-relative href (e.g. '/events', '/products/orders') to the
+ * extension + nav item that owns a renderable page for it, and the section
+ * within it. The shell's generic host route uses this to render plugin pages
+ * without a per-plugin page file.
+ *
+ * ## Which registration wins (AGL-2501)
+ *
+ * LONGEST declared `href` wins, and an exact match therefore always beats a
+ * section match — an exact `href` spans the whole path, so nothing matching a
+ * prefix of it can be longer. `/products/orders` goes to a plugin that
+ * declares that path over one that declares `/products` with an `orders`
+ * section, and a prefix only matches on a SEGMENT boundary, so `/products`
+ * never claims `/products-archive`.
+ *
+ * A TIE REFUSES. Two enabled plugins matching the same path at the same length
+ * resolve to nothing, and the console 404s. Registry insertion order is an
+ * accident of which chunk loaded first, so picking from it means one
+ * workspace serves plugin A's page at a URL where another serves plugin B's —
+ * silently, and differently per session. Nobody can debug that from the
+ * symptom, so it is refused and logged instead. Two nav items of the SAME
+ * extension are not a tie: that order is authored, and the first wins as it
+ * always has.
+ *
+ * This is a rule rather than an accident because the registry is a
+ * session-wide UNION across plugins from different authors (AGL-758) — one
+ * plugin registering `/products` and another `/products/orders` is two
+ * workspaces' code meeting in one module-global, not one author's tidiness
+ * problem. Scoping is unchanged and load-bearing: every candidate still comes
+ * from `listConsoleExtensions(enabledPluginIds)`, so a plugin the current org
+ * has not enabled cannot win a path — or collide with one.
+ */
+export declare function resolveConsolePluginPage(href: string, enabledPluginIds?: readonly PluginId[]): ResolvedConsolePluginPage | undefined;
+/** One organization-level nav item with the extension that declared it. */
+export interface ConsoleOrgNavEntry {
+    extension: ConsoleExtension;
+    navItem: ConsoleNavItem;
+}
+/**
+ * Every registered {@link ConsoleExtension.orgNavItems} entry, in
+ * registration order, for the organization's tab strip (AGL-2974).
+ *
+ * Carries the extension whole rather than a flattened copy of two of its
+ * fields: a tab for a surface the reader cannot open is hidden, and deciding
+ * that takes the extension's `permission`, `featureFlag` and
+ * `upgradeNotice`, which is the same set the org route reads.
+ */
+export declare function listConsoleOrgNavItems(enabledPluginIds?: readonly PluginId[]): ConsoleOrgNavEntry[];
+/**
+ * {@link resolveConsolePluginPage} for the ORGANIZATION level (AGL-2974): an
+ * org-relative href (`/outreach/sequences`) against every enabled
+ * extension's `orgNavItems`, with the same matching, the same longest-href
+ * rule and the same refusal of a tie between two plugins. Site nav items are
+ * never candidates, so a surface registered under a site cannot be opened
+ * without one.
+ */
+export declare function resolveConsoleOrgPluginPage(href: string, enabledPluginIds?: readonly PluginId[]): ResolvedConsolePluginPage | undefined;
+/** A staff page flattened with its owning extension's id. */
+export interface ConsoleStaffPageEntry extends ConsoleStaffPage {
+    pluginId: PluginId;
+}
+/**
+ * Every registered staff page, in registration order — the staff strip's
+ * plugin tabs, after the console's own.
+ */
+export declare function listConsoleStaffPages(enabledPluginIds?: readonly PluginId[]): ConsoleStaffPageEntry[];
+/**
+ * The staff page at `/admin/{id}` (AGL-2939), or `undefined`.
+ *
+ * Two plugins claiming one id resolve to nothing, and say so: registry order
+ * is an accident of which chunk loaded first, and a staff page that is one
+ * plugin's on one load and another's on the next cannot be debugged from the
+ * symptom — the same rule {@link resolveConsolePluginPage} applies to paths.
+ */
+export declare function resolveConsoleStaffPage(id: string, enabledPluginIds?: readonly PluginId[]): ConsoleStaffPageEntry | undefined;
+/** Widgets registered for a slot, across every extension (AGL-419). */
+export declare function listConsoleWidgets(slot: string, enabledPluginIds?: readonly PluginId[]): Array<{
+    extension: ConsoleExtension;
+    widget: ConsoleWidget;
+}>;
+/** Providers registered by every extension, in registration order. */
+export declare function listConsoleProviders(enabledPluginIds?: readonly PluginId[]): Array<ComponentType<any>>;