@wildo-ai/saas-frontend-lib 1.0.1 → 1.1.0

package/dist/esm/core/config/settings-hub.frontend.schemas.d.ts

@@ -0,0 +1,320 @@
+/**
+ * Settings Hub — Declarative Section Registry
+ *
+ * The Settings Hub is the framework's single point of configuration: one overlay
+ * surface that consolidates every settings destination (account, security,
+ * appearance, organization, members, billing, …) behind a vertical `Tabs` rail
+ * grouped by category. Many entry points (user dropdown, sidebar, command menu)
+ * all converge on this one hub; links differ only by which section they pre-open.
+ *
+ * This file owns the **config-time** registry contract. It is declaration-first
+ * and mirrors `launcher-items.frontend.schemas.ts`:
+ * - `SettingsSectionTarget` is an interface-based discriminated union on `kind`
+ *   (exactly like `LauncherItemRef`), because section targets are config-time
+ *   descriptors resolved by the runtime — not Zod-validated wire payloads.
+ * - The framework seeds a default `SettingsHubConfig`; apps merge/extend it
+ *   (same model as the sidebar/launcher config).
+ *
+ * Runtime concerns live elsewhere:
+ * - `NavigationContentType.SETTINGS_HUB` (navigation.schemas.ts) — what renders
+ *   in the overlay zone.
+ * - `SettingsHub` component (components/settings/) — resolves a section's target
+ *   to a rendered panel.
+ *
+ * @see launcher-items.frontend.schemas.ts — the sibling launcher registry this mirrors
+ * @see .claude/plans/unified-settings-hub.md — design + layer trace
+ */
+import { ResourcePrimaryScope } from '@wildo-ai/saas-models';
+import type { RequiredFeaturesConfig } from '@wildo-ai/saas-models';
+import type { LauncherRuntimeAvailabilityConfig } from './launcher-items.frontend.schemas';
+/**
+ * What a settings section renders in its content panel.
+ *
+ * Discriminant for the `SettingsSectionTarget` union. The default for
+ * data-backed settings is `RESOURCE_OPERATION` (reuse the auto-rendered
+ * resource surface); `ENGINE_PANEL` is reserved for the few sections whose
+ * bespoke layout earns it (Security, Appearance).
+ */
+export declare enum SettingsSectionTargetKind {
+    /** A framework-owned bespoke panel (Security, Appearance, …). */
+    ENGINE_PANEL = "engine_panel",
+    /** An auto-rendered resource-operation surface (members, API tokens, billing, preferences). */
+    RESOURCE_OPERATION = "resource_operation",
+    /** An app-registered custom React component (resolved via the component registry). */
+    CUSTOM_COMPONENT = "custom_component",
+    /** A section that itself splits into horizontal sub-tabs (e.g. Teams → Members / Roles & Permissions). */
+    SUB_TABS = "sub_tabs"
+}
+/**
+ * Framework-provided settings panels with bespoke (non-CRUD) layout.
+ *
+ * Closed enum — only framework panels belong here. Most settings sections should
+ * be `RESOURCE_OPERATION` targets instead; a panel earns a slot here only when a
+ * standard resource surface cannot express it (multi-factor enrollment flows,
+ * theme/dark-mode toggles, …).
+ *
+ * The runtime maps each ref to a registered panel component in the
+ * `SettingsHub` resolver.
+ */
+export declare enum SettingsPanelRef {
+    /** Password, MFA enrollment, passkeys, identity links (wraps the former `AppPage_SecuritySettings`). */
+    SECURITY = "security",
+    /** Theme, dark-mode, density and other look-and-feel preferences. */
+    APPEARANCE = "appearance",
+    /** The caller's own pending org invitations — accept/reject in-app (Approach P). */
+    INVITATIONS = "invitations",
+    /**
+     * The billing home: subscription status, plan catalog + checkout, usage,
+     * invoices and the provider portal link — composed from the BillingContext
+     * aggregated state (`GET_STATE`), NOT from per-resource LIST surfaces.
+     *
+     * Bespoke on purpose: the billing child resources (subscriptions, invoice
+     * refs, usage records) are routed UNDER the billing account
+     * (`REQUIRES_CONTEXT`), so a generic org-scoped `RESOURCE_OPERATION` panel
+     * cannot build their URLs. The aggregated billing state is org-addressable
+     * and auto-creates the account, which makes it the correct settings-surface
+     * data source.
+     */
+    BILLING = "billing"
+}
+/** Renders a framework-owned bespoke panel. */
+export interface SettingsEnginePanelTarget {
+    kind: SettingsSectionTargetKind.ENGINE_PANEL;
+    panelRef: SettingsPanelRef;
+}
+/**
+ * Renders an auto-generated resource-operation surface inside the section panel.
+ * Resolved against the resource registry exactly like a launcher
+ * `RESOURCE_OPERATION` target.
+ */
+export interface SettingsResourceOperationTarget {
+    kind: SettingsSectionTargetKind.RESOURCE_OPERATION;
+    resourceType: string;
+    operation: string;
+    operationVariant?: string;
+}
+/** Renders an app-registered custom React component (resolved by `componentRef`). */
+export interface SettingsCustomComponentTarget {
+    kind: SettingsSectionTargetKind.CUSTOM_COMPONENT;
+    componentRef: string;
+}
+/**
+ * Leaf targets renderable directly in a panel. Sub-tabs may only point at leaf
+ * targets — sub-tabs cannot nest further sub-tabs (one level of in-section
+ * tabbing, matching the BetterStack reference).
+ */
+export type SettingsLeafTarget = SettingsEnginePanelTarget | SettingsResourceOperationTarget | SettingsCustomComponentTarget;
+/**
+ * One horizontal sub-tab within a section (e.g. the "Members" / "Roles &
+ * Permissions" tabs inside a Teams section).
+ */
+export interface SettingsSubTab {
+    /** Sub-tab reference — app-defined, used for i18n + the `value` of the inner Tabs. */
+    ref: string;
+    /** Display label (i18n ref). */
+    label: string;
+    /** Optional icon ref for the sub-tab trigger. */
+    icon?: string;
+    /** What this sub-tab renders. Sub-tabs hold leaf targets only. */
+    target: SettingsLeafTarget;
+}
+/** Splits a section into horizontal sub-tabs rendered above the panel content. */
+export interface SettingsSubTabsTarget {
+    kind: SettingsSectionTargetKind.SUB_TABS;
+    subTabs: SettingsSubTab[];
+}
+/**
+ * What a settings section renders. Discriminated on `kind`; the `SettingsHub`
+ * resolver dispatches on it to produce the panel content.
+ */
+export type SettingsSectionTarget = SettingsLeafTarget | SettingsSubTabsTarget;
+/**
+ * A category groups sections in the vertical rail (the `Account` / `Organization`
+ * group headers in the BetterStack reference). Rendered as a label + separator
+ * inside the `TabsList` — NOT a separate nav widget (the `Tabs` primitive stays
+ * the section mechanism).
+ *
+ * `scope` ties the category to a primary-scope axis so the runtime can hide it
+ * when the scope is unavailable — e.g. an `ORGANIZATIONS` category is hidden when
+ * no organization is selected. It is derived against `AppScope`, not authored
+ * per-user.
+ */
+export interface SettingsCategory {
+    /** Category reference — app-defined, referenced by `SettingsSection.categoryRef`. */
+    ref: string;
+    /** Group header label (i18n ref). */
+    label: string;
+    /**
+     * Primary scope this category belongs to. Drives rail grouping order and
+     * scope-gated visibility (org categories hide when no org is selected).
+     * Omit for a scope-agnostic category.
+     */
+    scope?: ResourcePrimaryScope;
+    /** Optional icon ref for the group header. */
+    icon?: string;
+    /** Sort order among categories in the rail (lower = higher). */
+    order?: number;
+}
+/** @wildo_source:part:start saas.frontend.settings-hub.placement facet:layer:frontend facet:family:config facet:audience:app-developer */
+/**
+ * An addressable settings DESTINATION — what a settings surface *is*, with no
+ * opinion on where it appears.
+ *
+ * This is the half the engine ships (`ENGINE_SETTINGS_DESTINATIONS`). It carries
+ * the target and the gating stack, and deliberately carries **no `categoryRef`,
+ * no `order` and no `label`**: those are placement, and placement is the
+ * application's decision (`SettingsPlacement`).
+ *
+ * The split exists because the engine shipping a PLACED hub is what made the
+ * settings rail unauthorable — an application could not add, remove, reorder or
+ * rename a section without the framework agreeing. Splitting destination from
+ * placement lets the engine keep owning what a destination MEANS (its target,
+ * its roles, its entitlement) while the application owns where it sits.
+ */
+export interface SettingsDestination {
+    /** Destination reference — the `/settings/:sectionRef` URL segment and the id a placement names. */
+    ref: string;
+    /** What the destination renders in its content panel. */
+    target: SettingsSectionTarget;
+    /** Declarative runtime capability gating (same contract as launcher items). */
+    runtimeAvailability?: LauncherRuntimeAvailabilityConfig;
+    /** Feature flags required to surface this destination (plan/subscription gating). */
+    requiredFeatures?: RequiredFeaturesConfig;
+    /** RBAC roles required to surface this destination (OR semantics). */
+    requiredRoles?: string[];
+    /** Optional CoreFeature id this destination's content is ENTITLED by (soft gate — renders an upgrade prompt). */
+    entitlementFeatureId?: string;
+}
+/**
+ * An application's explicit PLACEMENT of one destination in its settings rail.
+ *
+ * Authored in the application's own config. Nothing is placed implicitly: a
+ * destination the application does not place does not render, which is the whole
+ * point — "we should just place things", with no automatic inference.
+ *
+ * `label` is optional and is an OVERRIDE. The resolved label otherwise comes from
+ * the `settings_hub.sections.<ref>.label` key, so a placed section is localizable
+ * without the application authoring an English string.
+ *
+ * That namespace and its resolver (`tSettingsHubSection`) EXIST and already fall
+ * back to the authored label. What does not exist is anything that generates the
+ * units: `LabellingTypes.SETTINGS_HUB` is declared with an empty pattern and the
+ * companion plans nothing for it, so today every rail label is the authored
+ * English string. R9 is a wiring job, not a new mechanism.
+ */
+export interface SettingsPlacement {
+    /** The {@link SettingsDestination.ref} being placed. Refused at DEV startup when unknown. */
+    destinationRef: string;
+    /** Which category (rail group) this destination sits under. */
+    categoryRef: string;
+    /** Sort order within the category (lower = higher). */
+    order?: number;
+    /** Optional icon ref for the rail entry. */
+    icon?: string;
+    /** Rail label override. Omit to take `settings_hub.sections.<ref>.label`. */
+    label?: string;
+}
+/** @wildo_source:part:end saas.frontend.settings-hub.placement */
+/**
+ * A settings section is one entry in the vertical rail (one `TabsTrigger`) —
+ * the RESOLVED union of a {@link SettingsDestination} and the
+ * {@link SettingsPlacement} that placed it.
+ *
+ * Produced by `resolveSettingsHubConfig()`; never authored directly. It
+ * belongs to a category, addresses a target, and reuses the existing launcher
+ * gating stack:
+ * - `runtimeAvailability` — survives the app-shell filtering pass (capabilities).
+ * - `requiredFeatures` — plan/subscription gating once resolved.
+ * - `requiredRoles` — RBAC gating (e.g. org-admin-only sections).
+ *
+ * `ref` is the URL-addressable section id (`/settings/:sectionRef`).
+ */
+export interface SettingsSection {
+    /** Section reference — app-defined; the `/settings/:sectionRef` URL segment + Tabs `value`. */
+    ref: string;
+    /** Which category (rail group) this section sits under. */
+    categoryRef: string;
+    /** Rail label (i18n ref). */
+    label: string;
+    /** Optional icon ref for the rail entry. */
+    icon?: string;
+    /** Sort order within the category (lower = higher). */
+    order?: number;
+    /** What the section renders in its content panel. */
+    target: SettingsSectionTarget;
+    /** Declarative runtime capability gating (same contract as launcher items). */
+    runtimeAvailability?: LauncherRuntimeAvailabilityConfig;
+    /**
+     * Feature flags required to surface this section (plan/subscription gating).
+     *
+     * Uses the framework-canonical {@link RequiredFeaturesConfig} contract shared
+     * with views and resource operations — shorthand `string[]` (OR semantics) or
+     * the full `{ features, mode: 'OR' | 'AND' }` form. `limitChecks` are not
+     * evaluated for section visibility (a section is shown or hidden, never
+     * "over-limit"); use {@link requiredRoles} / capabilities for hard gating.
+     */
+    requiredFeatures?: RequiredFeaturesConfig;
+    /**
+     * RBAC roles required to surface this section (OR semantics — the user needs
+     * ANY one of these roles). Evaluated against the merged app-level + current-
+     * organization role set, the same effective surface the rest of the frontend
+     * gating layer resolves (see `buildFeaturePolicyRoles`). Org-management
+     * sections gate on `[CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN]`.
+     */
+    requiredRoles?: string[];
+    /**
+     * Optional CoreFeature id this section's content is ENTITLED by. Distinct from
+     * {@link requiredFeatures} (a HARD hide-gate): when set, the section still
+     * SURVIVES (per `runtimeAvailability`/roles) and its body is wrapped in a
+     * `FeatureGate` so an OFFERED-but-not-yet-entitled feature renders the
+     * policy-driven upgrade/add-on prompt (`unavailabilityPolicy`) instead of
+     * vanishing. Pair with a `runtimeAvailability.requiredCapabilities` gate whose
+     * capability is the plan-independent "app offers X" signal, so a feature the
+     * app does NOT offer at all is hidden outright while an offered one prompts.
+     */
+    entitlementFeatureId?: string;
+}
+/** @wildo_source:part:start saas.frontend.settings-hub.placement */
+/**
+ * The AUTHORED Settings Hub registry — an application's own settings rail.
+ *
+ * The framework ships destinations (`ENGINE_SETTINGS_DESTINATIONS`), never a
+ * placed hub. This is the application's half: which categories exist, and which
+ * destinations are placed where. `wildo init` scaffolds the full destination list
+ * as placements so a new application starts complete and edits down.
+ *
+ * Resolve it with `resolveSettingsHubConfig()` to get the rendered
+ * {@link SettingsSection} list; the render path never reads this shape directly.
+ */
+export interface SettingsHubConfig {
+    /** Rail groups, in render order (also orderable via `SettingsCategory.order`). */
+    categories: SettingsCategory[];
+    /**
+     * Every destination this application places, and where.
+     *
+     * A destination that appears in no placement does not render. That is
+     * deliberate: absence is how an application removes a settings section, and it
+     * must not be second-guessed by a merge against a framework default.
+     */
+    placements: SettingsPlacement[];
+    /**
+     * Section opened when the hub is launched without an explicit section
+     * (`/settings` with no `:sectionRef`). Falls back to the first section of the
+     * first category when omitted.
+     */
+    defaultSectionRef?: string;
+}
+/**
+ * The RESOLVED hub — categories plus fully-resolved sections, ready to render.
+ *
+ * Distinct from {@link SettingsHubConfig} (what an application AUTHORS) because
+ * conflating the two is what let a placed default ship from the engine. A
+ * consumer that renders takes this; a consumer that configures takes the other.
+ */
+export interface ResolvedSettingsHubConfig {
+    categories: SettingsCategory[];
+    sections: SettingsSection[];
+    defaultSectionRef?: string;
+}
+/** @wildo_source:part:end saas.frontend.settings-hub.placement */
+//# sourceMappingURL=settings-hub.frontend.schemas.d.ts.map

package/dist/esm/core/config/settings-hub.frontend.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-hub.frontend.schemas.d.ts","sourceRoot":"","sources":["../../../../../src/core/config/settings-hub.frontend.schemas.ts"],"names":[],"mappings":"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"}

package/dist/esm/core/config/settings-hub.frontend.schemas.js

@@ -0,0 +1,86 @@
+/**
+ * Settings Hub — Declarative Section Registry
+ *
+ * The Settings Hub is the framework's single point of configuration: one overlay
+ * surface that consolidates every settings destination (account, security,
+ * appearance, organization, members, billing, …) behind a vertical `Tabs` rail
+ * grouped by category. Many entry points (user dropdown, sidebar, command menu)
+ * all converge on this one hub; links differ only by which section they pre-open.
+ *
+ * This file owns the **config-time** registry contract. It is declaration-first
+ * and mirrors `launcher-items.frontend.schemas.ts`:
+ * - `SettingsSectionTarget` is an interface-based discriminated union on `kind`
+ *   (exactly like `LauncherItemRef`), because section targets are config-time
+ *   descriptors resolved by the runtime — not Zod-validated wire payloads.
+ * - The framework seeds a default `SettingsHubConfig`; apps merge/extend it
+ *   (same model as the sidebar/launcher config).
+ *
+ * Runtime concerns live elsewhere:
+ * - `NavigationContentType.SETTINGS_HUB` (navigation.schemas.ts) — what renders
+ *   in the overlay zone.
+ * - `SettingsHub` component (components/settings/) — resolves a section's target
+ *   to a rendered panel.
+ *
+ * @see launcher-items.frontend.schemas.ts — the sibling launcher registry this mirrors
+ * @see .claude/plans/unified-settings-hub.md — design + layer trace
+ */
+// ════════════════════════════════════════════════════════════════
+// Section Target Kind — discriminant for SettingsSectionTarget
+// ════════════════════════════════════════════════════════════════
+/**
+ * What a settings section renders in its content panel.
+ *
+ * Discriminant for the `SettingsSectionTarget` union. The default for
+ * data-backed settings is `RESOURCE_OPERATION` (reuse the auto-rendered
+ * resource surface); `ENGINE_PANEL` is reserved for the few sections whose
+ * bespoke layout earns it (Security, Appearance).
+ */
+export var SettingsSectionTargetKind;
+(function (SettingsSectionTargetKind) {
+    /** A framework-owned bespoke panel (Security, Appearance, …). */
+    SettingsSectionTargetKind["ENGINE_PANEL"] = "engine_panel";
+    /** An auto-rendered resource-operation surface (members, API tokens, billing, preferences). */
+    SettingsSectionTargetKind["RESOURCE_OPERATION"] = "resource_operation";
+    /** An app-registered custom React component (resolved via the component registry). */
+    SettingsSectionTargetKind["CUSTOM_COMPONENT"] = "custom_component";
+    /** A section that itself splits into horizontal sub-tabs (e.g. Teams → Members / Roles & Permissions). */
+    SettingsSectionTargetKind["SUB_TABS"] = "sub_tabs";
+})(SettingsSectionTargetKind || (SettingsSectionTargetKind = {}));
+// ════════════════════════════════════════════════════════════════
+// Engine Panel Ref — framework-owned bespoke settings panels
+// ════════════════════════════════════════════════════════════════
+/**
+ * Framework-provided settings panels with bespoke (non-CRUD) layout.
+ *
+ * Closed enum — only framework panels belong here. Most settings sections should
+ * be `RESOURCE_OPERATION` targets instead; a panel earns a slot here only when a
+ * standard resource surface cannot express it (multi-factor enrollment flows,
+ * theme/dark-mode toggles, …).
+ *
+ * The runtime maps each ref to a registered panel component in the
+ * `SettingsHub` resolver.
+ */
+export var SettingsPanelRef;
+(function (SettingsPanelRef) {
+    /** Password, MFA enrollment, passkeys, identity links (wraps the former `AppPage_SecuritySettings`). */
+    SettingsPanelRef["SECURITY"] = "security";
+    /** Theme, dark-mode, density and other look-and-feel preferences. */
+    SettingsPanelRef["APPEARANCE"] = "appearance";
+    /** The caller's own pending org invitations — accept/reject in-app (Approach P). */
+    SettingsPanelRef["INVITATIONS"] = "invitations";
+    /**
+     * The billing home: subscription status, plan catalog + checkout, usage,
+     * invoices and the provider portal link — composed from the BillingContext
+     * aggregated state (`GET_STATE`), NOT from per-resource LIST surfaces.
+     *
+     * Bespoke on purpose: the billing child resources (subscriptions, invoice
+     * refs, usage records) are routed UNDER the billing account
+     * (`REQUIRES_CONTEXT`), so a generic org-scoped `RESOURCE_OPERATION` panel
+     * cannot build their URLs. The aggregated billing state is org-addressable
+     * and auto-creates the account, which makes it the correct settings-surface
+     * data source.
+     */
+    SettingsPanelRef["BILLING"] = "billing";
+})(SettingsPanelRef || (SettingsPanelRef = {}));
+/** @wildo_source:part:end saas.frontend.settings-hub.placement */
+//# sourceMappingURL=settings-hub.frontend.schemas.js.map

package/dist/esm/core/config/settings-hub.frontend.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-hub.frontend.schemas.js","sourceRoot":"","sources":["../../../../../src/core/config/settings-hub.frontend.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAMH,mEAAmE;AACnE,+DAA+D;AAC/D,mEAAmE;AAEnE;;;;;;;GAOG;AACH,MAAM,CAAN,IAAY,yBASX;AATD,WAAY,yBAAyB;IACnC,iEAAiE;IACjE,0DAA6B,CAAA;IAC7B,+FAA+F;IAC/F,sEAAyC,CAAA;IACzC,sFAAsF;IACtF,kEAAqC,CAAA;IACrC,0GAA0G;IAC1G,kDAAqB,CAAA;AACvB,CAAC,EATW,yBAAyB,KAAzB,yBAAyB,QASpC;AAED,mEAAmE;AACnE,6DAA6D;AAC7D,mEAAmE;AAEnE;;;;;;;;;;GAUG;AACH,MAAM,CAAN,IAAY,gBAoBX;AApBD,WAAY,gBAAgB;IAC1B,wGAAwG;IACxG,yCAAqB,CAAA;IACrB,qEAAqE;IACrE,6CAAyB,CAAA;IACzB,oFAAoF;IACpF,+CAA2B,CAAA;IAC3B;;;;;;;;;;;OAWG;IACH,uCAAmB,CAAA;AACrB,CAAC,EApBW,gBAAgB,KAAhB,gBAAgB,QAoB3B;AAgRD,kEAAkE","sourcesContent":["/**\n * Settings Hub — Declarative Section Registry\n *\n * The Settings Hub is the framework's single point of configuration: one overlay\n * surface that consolidates every settings destination (account, security,\n * appearance, organization, members, billing, …) behind a vertical `Tabs` rail\n * grouped by category. Many entry points (user dropdown, sidebar, command menu)\n * all converge on this one hub; links differ only by which section they pre-open.\n *\n * This file owns the **config-time** registry contract. It is declaration-first\n * and mirrors `launcher-items.frontend.schemas.ts`:\n * - `SettingsSectionTarget` is an interface-based discriminated union on `kind`\n *   (exactly like `LauncherItemRef`), because section targets are config-time\n *   descriptors resolved by the runtime — not Zod-validated wire payloads.\n * - The framework seeds a default `SettingsHubConfig`; apps merge/extend it\n *   (same model as the sidebar/launcher config).\n *\n * Runtime concerns live elsewhere:\n * - `NavigationContentType.SETTINGS_HUB` (navigation.schemas.ts) — what renders\n *   in the overlay zone.\n * - `SettingsHub` component (components/settings/) — resolves a section's target\n *   to a rendered panel.\n *\n * @see launcher-items.frontend.schemas.ts — the sibling launcher registry this mirrors\n * @see .claude/plans/unified-settings-hub.md — design + layer trace\n */\n\nimport { ResourcePrimaryScope } from '@wildo-ai/saas-models';\nimport type { RequiredFeaturesConfig } from '@wildo-ai/saas-models';\nimport type { LauncherRuntimeAvailabilityConfig } from './launcher-items.frontend.schemas';\n\n// ════════════════════════════════════════════════════════════════\n// Section Target Kind — discriminant for SettingsSectionTarget\n// ════════════════════════════════════════════════════════════════\n\n/**\n * What a settings section renders in its content panel.\n *\n * Discriminant for the `SettingsSectionTarget` union. The default for\n * data-backed settings is `RESOURCE_OPERATION` (reuse the auto-rendered\n * resource surface); `ENGINE_PANEL` is reserved for the few sections whose\n * bespoke layout earns it (Security, Appearance).\n */\nexport enum SettingsSectionTargetKind {\n  /** A framework-owned bespoke panel (Security, Appearance, …). */\n  ENGINE_PANEL = 'engine_panel',\n  /** An auto-rendered resource-operation surface (members, API tokens, billing, preferences). */\n  RESOURCE_OPERATION = 'resource_operation',\n  /** An app-registered custom React component (resolved via the component registry). */\n  CUSTOM_COMPONENT = 'custom_component',\n  /** A section that itself splits into horizontal sub-tabs (e.g. Teams → Members / Roles & Permissions). */\n  SUB_TABS = 'sub_tabs',\n}\n\n// ════════════════════════════════════════════════════════════════\n// Engine Panel Ref — framework-owned bespoke settings panels\n// ════════════════════════════════════════════════════════════════\n\n/**\n * Framework-provided settings panels with bespoke (non-CRUD) layout.\n *\n * Closed enum — only framework panels belong here. Most settings sections should\n * be `RESOURCE_OPERATION` targets instead; a panel earns a slot here only when a\n * standard resource surface cannot express it (multi-factor enrollment flows,\n * theme/dark-mode toggles, …).\n *\n * The runtime maps each ref to a registered panel component in the\n * `SettingsHub` resolver.\n */\nexport enum SettingsPanelRef {\n  /** Password, MFA enrollment, passkeys, identity links (wraps the former `AppPage_SecuritySettings`). */\n  SECURITY = 'security',\n  /** Theme, dark-mode, density and other look-and-feel preferences. */\n  APPEARANCE = 'appearance',\n  /** The caller's own pending org invitations — accept/reject in-app (Approach P). */\n  INVITATIONS = 'invitations',\n  /**\n   * The billing home: subscription status, plan catalog + checkout, usage,\n   * invoices and the provider portal link — composed from the BillingContext\n   * aggregated state (`GET_STATE`), NOT from per-resource LIST surfaces.\n   *\n   * Bespoke on purpose: the billing child resources (subscriptions, invoice\n   * refs, usage records) are routed UNDER the billing account\n   * (`REQUIRES_CONTEXT`), so a generic org-scoped `RESOURCE_OPERATION` panel\n   * cannot build their URLs. The aggregated billing state is org-addressable\n   * and auto-creates the account, which makes it the correct settings-surface\n   * data source.\n   */\n  BILLING = 'billing',\n}\n\n// ════════════════════════════════════════════════════════════════\n// Section Target — discriminated union on `kind`\n// ════════════════════════════════════════════════════════════════\n\n/** Renders a framework-owned bespoke panel. */\nexport interface SettingsEnginePanelTarget {\n  kind: SettingsSectionTargetKind.ENGINE_PANEL;\n  panelRef: SettingsPanelRef;\n}\n\n/**\n * Renders an auto-generated resource-operation surface inside the section panel.\n * Resolved against the resource registry exactly like a launcher\n * `RESOURCE_OPERATION` target.\n */\nexport interface SettingsResourceOperationTarget {\n  kind: SettingsSectionTargetKind.RESOURCE_OPERATION;\n  resourceType: string;\n  operation: string;\n  operationVariant?: string;\n}\n\n/** Renders an app-registered custom React component (resolved by `componentRef`). */\nexport interface SettingsCustomComponentTarget {\n  kind: SettingsSectionTargetKind.CUSTOM_COMPONENT;\n  componentRef: string;\n}\n\n/**\n * Leaf targets renderable directly in a panel. Sub-tabs may only point at leaf\n * targets — sub-tabs cannot nest further sub-tabs (one level of in-section\n * tabbing, matching the BetterStack reference).\n */\nexport type SettingsLeafTarget =\n  | SettingsEnginePanelTarget\n  | SettingsResourceOperationTarget\n  | SettingsCustomComponentTarget;\n\n/**\n * One horizontal sub-tab within a section (e.g. the \"Members\" / \"Roles &\n * Permissions\" tabs inside a Teams section).\n */\nexport interface SettingsSubTab {\n  /** Sub-tab reference — app-defined, used for i18n + the `value` of the inner Tabs. */\n  ref: string;\n  /** Display label (i18n ref). */\n  label: string;\n  /** Optional icon ref for the sub-tab trigger. */\n  icon?: string;\n  /** What this sub-tab renders. Sub-tabs hold leaf targets only. */\n  target: SettingsLeafTarget;\n}\n\n/** Splits a section into horizontal sub-tabs rendered above the panel content. */\nexport interface SettingsSubTabsTarget {\n  kind: SettingsSectionTargetKind.SUB_TABS;\n  subTabs: SettingsSubTab[];\n}\n\n/**\n * What a settings section renders. Discriminated on `kind`; the `SettingsHub`\n * resolver dispatches on it to produce the panel content.\n */\nexport type SettingsSectionTarget = SettingsLeafTarget | SettingsSubTabsTarget;\n\n// ════════════════════════════════════════════════════════════════\n// Category — the rail group\n// ════════════════════════════════════════════════════════════════\n\n/**\n * A category groups sections in the vertical rail (the `Account` / `Organization`\n * group headers in the BetterStack reference). Rendered as a label + separator\n * inside the `TabsList` — NOT a separate nav widget (the `Tabs` primitive stays\n * the section mechanism).\n *\n * `scope` ties the category to a primary-scope axis so the runtime can hide it\n * when the scope is unavailable — e.g. an `ORGANIZATIONS` category is hidden when\n * no organization is selected. It is derived against `AppScope`, not authored\n * per-user.\n */\nexport interface SettingsCategory {\n  /** Category reference — app-defined, referenced by `SettingsSection.categoryRef`. */\n  ref: string;\n  /** Group header label (i18n ref). */\n  label: string;\n  /**\n   * Primary scope this category belongs to. Drives rail grouping order and\n   * scope-gated visibility (org categories hide when no org is selected).\n   * Omit for a scope-agnostic category.\n   */\n  scope?: ResourcePrimaryScope;\n  /** Optional icon ref for the group header. */\n  icon?: string;\n  /** Sort order among categories in the rail (lower = higher). */\n  order?: number;\n}\n\n// ════════════════════════════════════════════════════════════════\n// Section — one vertical tab in the rail\n// ════════════════════════════════════════════════════════════════\n\n/** @wildo_source:part:start saas.frontend.settings-hub.placement facet:layer:frontend facet:family:config facet:audience:app-developer */\n/**\n * An addressable settings DESTINATION — what a settings surface *is*, with no\n * opinion on where it appears.\n *\n * This is the half the engine ships (`ENGINE_SETTINGS_DESTINATIONS`). It carries\n * the target and the gating stack, and deliberately carries **no `categoryRef`,\n * no `order` and no `label`**: those are placement, and placement is the\n * application's decision (`SettingsPlacement`).\n *\n * The split exists because the engine shipping a PLACED hub is what made the\n * settings rail unauthorable — an application could not add, remove, reorder or\n * rename a section without the framework agreeing. Splitting destination from\n * placement lets the engine keep owning what a destination MEANS (its target,\n * its roles, its entitlement) while the application owns where it sits.\n */\nexport interface SettingsDestination {\n  /** Destination reference — the `/settings/:sectionRef` URL segment and the id a placement names. */\n  ref: string;\n  /** What the destination renders in its content panel. */\n  target: SettingsSectionTarget;\n  /** Declarative runtime capability gating (same contract as launcher items). */\n  runtimeAvailability?: LauncherRuntimeAvailabilityConfig;\n  /** Feature flags required to surface this destination (plan/subscription gating). */\n  requiredFeatures?: RequiredFeaturesConfig;\n  /** RBAC roles required to surface this destination (OR semantics). */\n  requiredRoles?: string[];\n  /** Optional CoreFeature id this destination's content is ENTITLED by (soft gate — renders an upgrade prompt). */\n  entitlementFeatureId?: string;\n}\n\n/**\n * An application's explicit PLACEMENT of one destination in its settings rail.\n *\n * Authored in the application's own config. Nothing is placed implicitly: a\n * destination the application does not place does not render, which is the whole\n * point — \"we should just place things\", with no automatic inference.\n *\n * `label` is optional and is an OVERRIDE. The resolved label otherwise comes from\n * the `settings_hub.sections.<ref>.label` key, so a placed section is localizable\n * without the application authoring an English string.\n *\n * That namespace and its resolver (`tSettingsHubSection`) EXIST and already fall\n * back to the authored label. What does not exist is anything that generates the\n * units: `LabellingTypes.SETTINGS_HUB` is declared with an empty pattern and the\n * companion plans nothing for it, so today every rail label is the authored\n * English string. R9 is a wiring job, not a new mechanism.\n */\nexport interface SettingsPlacement {\n  /** The {@link SettingsDestination.ref} being placed. Refused at DEV startup when unknown. */\n  destinationRef: string;\n  /** Which category (rail group) this destination sits under. */\n  categoryRef: string;\n  /** Sort order within the category (lower = higher). */\n  order?: number;\n  /** Optional icon ref for the rail entry. */\n  icon?: string;\n  /** Rail label override. Omit to take `settings_hub.sections.<ref>.label`. */\n  label?: string;\n}\n/** @wildo_source:part:end saas.frontend.settings-hub.placement */\n\n/**\n * A settings section is one entry in the vertical rail (one `TabsTrigger`) —\n * the RESOLVED union of a {@link SettingsDestination} and the\n * {@link SettingsPlacement} that placed it.\n *\n * Produced by `resolveSettingsHubConfig()`; never authored directly. It\n * belongs to a category, addresses a target, and reuses the existing launcher\n * gating stack:\n * - `runtimeAvailability` — survives the app-shell filtering pass (capabilities).\n * - `requiredFeatures` — plan/subscription gating once resolved.\n * - `requiredRoles` — RBAC gating (e.g. org-admin-only sections).\n *\n * `ref` is the URL-addressable section id (`/settings/:sectionRef`).\n */\nexport interface SettingsSection {\n  /** Section reference — app-defined; the `/settings/:sectionRef` URL segment + Tabs `value`. */\n  ref: string;\n  /** Which category (rail group) this section sits under. */\n  categoryRef: string;\n  /** Rail label (i18n ref). */\n  label: string;\n  /** Optional icon ref for the rail entry. */\n  icon?: string;\n  /** Sort order within the category (lower = higher). */\n  order?: number;\n  /** What the section renders in its content panel. */\n  target: SettingsSectionTarget;\n  /** Declarative runtime capability gating (same contract as launcher items). */\n  runtimeAvailability?: LauncherRuntimeAvailabilityConfig;\n  /**\n   * Feature flags required to surface this section (plan/subscription gating).\n   *\n   * Uses the framework-canonical {@link RequiredFeaturesConfig} contract shared\n   * with views and resource operations — shorthand `string[]` (OR semantics) or\n   * the full `{ features, mode: 'OR' | 'AND' }` form. `limitChecks` are not\n   * evaluated for section visibility (a section is shown or hidden, never\n   * \"over-limit\"); use {@link requiredRoles} / capabilities for hard gating.\n   */\n  requiredFeatures?: RequiredFeaturesConfig;\n  /**\n   * RBAC roles required to surface this section (OR semantics — the user needs\n   * ANY one of these roles). Evaluated against the merged app-level + current-\n   * organization role set, the same effective surface the rest of the frontend\n   * gating layer resolves (see `buildFeaturePolicyRoles`). Org-management\n   * sections gate on `[CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN]`.\n   */\n  requiredRoles?: string[];\n  /**\n   * Optional CoreFeature id this section's content is ENTITLED by. Distinct from\n   * {@link requiredFeatures} (a HARD hide-gate): when set, the section still\n   * SURVIVES (per `runtimeAvailability`/roles) and its body is wrapped in a\n   * `FeatureGate` so an OFFERED-but-not-yet-entitled feature renders the\n   * policy-driven upgrade/add-on prompt (`unavailabilityPolicy`) instead of\n   * vanishing. Pair with a `runtimeAvailability.requiredCapabilities` gate whose\n   * capability is the plan-independent \"app offers X\" signal, so a feature the\n   * app does NOT offer at all is hidden outright while an offered one prompts.\n   */\n  entitlementFeatureId?: string;\n}\n\n// ════════════════════════════════════════════════════════════════\n// Hub Config — the registry root\n// ════════════════════════════════════════════════════════════════\n\n/** @wildo_source:part:start saas.frontend.settings-hub.placement */\n/**\n * The AUTHORED Settings Hub registry — an application's own settings rail.\n *\n * The framework ships destinations (`ENGINE_SETTINGS_DESTINATIONS`), never a\n * placed hub. This is the application's half: which categories exist, and which\n * destinations are placed where. `wildo init` scaffolds the full destination list\n * as placements so a new application starts complete and edits down.\n *\n * Resolve it with `resolveSettingsHubConfig()` to get the rendered\n * {@link SettingsSection} list; the render path never reads this shape directly.\n */\nexport interface SettingsHubConfig {\n  /** Rail groups, in render order (also orderable via `SettingsCategory.order`). */\n  categories: SettingsCategory[];\n  /**\n   * Every destination this application places, and where.\n   *\n   * A destination that appears in no placement does not render. That is\n   * deliberate: absence is how an application removes a settings section, and it\n   * must not be second-guessed by a merge against a framework default.\n   */\n  placements: SettingsPlacement[];\n  /**\n   * Section opened when the hub is launched without an explicit section\n   * (`/settings` with no `:sectionRef`). Falls back to the first section of the\n   * first category when omitted.\n   */\n  defaultSectionRef?: string;\n}\n\n/**\n * The RESOLVED hub — categories plus fully-resolved sections, ready to render.\n *\n * Distinct from {@link SettingsHubConfig} (what an application AUTHORS) because\n * conflating the two is what let a placed default ship from the engine. A\n * consumer that renders takes this; a consumer that configures takes the other.\n */\nexport interface ResolvedSettingsHubConfig {\n  categories: SettingsCategory[];\n  sections: SettingsSection[];\n  defaultSectionRef?: string;\n}\n/** @wildo_source:part:end saas.frontend.settings-hub.placement */\n"]}

package/dist/esm/core/config/useSettingsHubConfig.d.ts

@@ -0,0 +1,25 @@
+import type { ResolvedSettingsHubConfig, SettingsHubConfig } from './settings-hub.frontend.schemas';
+/**
+ * Pure (React-free) resolution — the single source of truth shared by
+ * {@link useSettingsHubConfig} (render path) and the DEV-startup
+ * `verifySettingsHubContent` pass.
+ *
+ * Keeping resolution here, not inlined in the hook, is what lets the verifier
+ * check the EXACT config the hub renders. Do not inline it into either caller:
+ * the moment the two derive their config separately, the verifier starts
+ * attesting to something nobody renders.
+ *
+ * A placement naming a ref absent from the catalog is DROPPED here and reported
+ * by the verifier rather than throwing. Resolution runs on the render path, and
+ * a hard throw there would take down the whole hub over one bad ref; the DEV
+ * startup pass is where an author is present to read the diagnostic.
+ */
+export declare function resolveSettingsHubConfig(authored: SettingsHubConfig | undefined): ResolvedSettingsHubConfig;
+/**
+ * Every destination ref an authored config places that the catalog does not
+ * ship. Reported by `verifySettingsHubContent`; see the note on
+ * {@link resolveSettingsHubConfig} for why resolution drops rather than throws.
+ */
+export declare function findUnknownDestinationRefs(authored: SettingsHubConfig | undefined): string[];
+export declare function useSettingsHubConfig(): ResolvedSettingsHubConfig;
+//# sourceMappingURL=useSettingsHubConfig.d.ts.map

package/dist/esm/core/config/useSettingsHubConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSettingsHubConfig.d.ts","sourceRoot":"","sources":["../../../../../src/core/config/useSettingsHubConfig.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EACV,yBAAyB,EAEzB,iBAAiB,EAElB,MAAM,iCAAiC,CAAC;AAQzC;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,SAAS,GAAG,yBAAyB,CA0C3G;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,iBAAiB,GAAG,SAAS,GAAG,MAAM,EAAE,CAO5F;AAED,wBAAgB,oBAAoB,IAAI,yBAAyB,CAGhE"}

package/dist/esm/core/config/useSettingsHubConfig.js

@@ -0,0 +1,94 @@
+/**
+ * Resolves an application's authored Settings Hub config into the rendered shape.
+ *
+ * Resolution is the join between the two halves of the placement split: the
+ * engine's destination catalog (`ENGINE_SETTINGS_DESTINATIONS` — what a settings
+ * surface IS) and the application's placements (where each one sits). Neither
+ * half renders alone.
+ *
+ * There is deliberately **no framework default and no merge**. An earlier
+ * revision returned `DEFAULT_SETTINGS_HUB_CONFIG`, a fully placed hub the engine
+ * owned, and that is precisely why an application could not remove or reorder a
+ * settings section: the render path read the framework's arrangement, so an
+ * application's absence of an arrangement was indistinguishable from agreement
+ * with it. Here, an unplaced destination does not render — absence is how a
+ * section is removed, and nothing reasserts it.
+ */
+import { ENGINE_SETTINGS_DESTINATIONS } from './engine-settings-destinations.js';
+import { useUI } from '../../core/ui/useUI.js';
+/** Catalog lookup by ref, built once — resolution runs on every hub render. */
+const DESTINATIONS_BY_REF = new Map(ENGINE_SETTINGS_DESTINATIONS.map(destination => [destination.ref, destination]));
+/**
+ * Pure (React-free) resolution — the single source of truth shared by
+ * {@link useSettingsHubConfig} (render path) and the DEV-startup
+ * `verifySettingsHubContent` pass.
+ *
+ * Keeping resolution here, not inlined in the hook, is what lets the verifier
+ * check the EXACT config the hub renders. Do not inline it into either caller:
+ * the moment the two derive their config separately, the verifier starts
+ * attesting to something nobody renders.
+ *
+ * A placement naming a ref absent from the catalog is DROPPED here and reported
+ * by the verifier rather than throwing. Resolution runs on the render path, and
+ * a hard throw there would take down the whole hub over one bad ref; the DEV
+ * startup pass is where an author is present to read the diagnostic.
+ */
+export function resolveSettingsHubConfig(authored) {
+    if (authored === undefined) {
+        return { categories: [], sections: [] };
+    }
+    const sections = [];
+    for (const placement of authored.placements) {
+        const destination = DESTINATIONS_BY_REF.get(placement.destinationRef);
+        if (destination === undefined) {
+            continue;
+        }
+        sections.push({
+            ref: destination.ref,
+            categoryRef: placement.categoryRef,
+            // The authored label, falling back to the ref so an unlabelled placement is
+            // visibly wrong in the rail rather than rendering an empty tab.
+            //
+            // It is NOT superseded by label generation, and deleting it is a
+            // regression rather than a tidy-up. `tSettingsHubSection(ref, label)`
+            // takes this as the fallback when no key exists — and, more importantly,
+            // the companion feeds this exact string to the labellize prompt as the
+            // key's `purpose`. Generating without it made the model invent from the
+            // ref: "User provisioning" became "SCIM", "Audit streaming" became
+            // "SIEM", and a generated key WINS over the fallback, so the rail's
+            // wording changed. The authored string is the intent; generation
+            // translates it.
+            label: placement.label ?? destination.ref,
+            icon: placement.icon,
+            order: placement.order,
+            target: destination.target,
+            runtimeAvailability: destination.runtimeAvailability,
+            requiredFeatures: destination.requiredFeatures,
+            requiredRoles: destination.requiredRoles,
+            entitlementFeatureId: destination.entitlementFeatureId,
+        });
+    }
+    return {
+        categories: authored.categories,
+        sections,
+        defaultSectionRef: authored.defaultSectionRef,
+    };
+}
+/**
+ * Every destination ref an authored config places that the catalog does not
+ * ship. Reported by `verifySettingsHubContent`; see the note on
+ * {@link resolveSettingsHubConfig} for why resolution drops rather than throws.
+ */
+export function findUnknownDestinationRefs(authored) {
+    if (authored === undefined) {
+        return [];
+    }
+    return authored.placements
+        .map(placement => placement.destinationRef)
+        .filter(ref => !DESTINATIONS_BY_REF.has(ref));
+}
+export function useSettingsHubConfig() {
+    const { settingsHub } = useUI();
+    return resolveSettingsHubConfig(settingsHub);
+}
+//# sourceMappingURL=useSettingsHubConfig.js.map

package/dist/esm/core/config/useSettingsHubConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSettingsHubConfig.js","sourceRoot":"","sources":["../../../../../src/core/config/useSettingsHubConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,4BAA4B,EAAE,MAAM,gCAAgC,CAAC;AAO9E,OAAO,EAAE,KAAK,EAAE,MAAM,mCAAmC,CAAC;AAE1D,+EAA+E;AAC/E,MAAM,mBAAmB,GAA6C,IAAI,GAAG,CAC3E,4BAA4B,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC,CAChF,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,wBAAwB,CAAC,QAAuC;IAC9E,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IAC1C,CAAC;IAED,MAAM,QAAQ,GAAsB,EAAE,CAAC;IACvC,KAAK,MAAM,SAAS,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC;QAC5C,MAAM,WAAW,GAAG,mBAAmB,CAAC,GAAG,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC;QACtE,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;YAC9B,SAAS;QACX,CAAC;QACD,QAAQ,CAAC,IAAI,CAAC;YACZ,GAAG,EAAE,WAAW,CAAC,GAAG;YACpB,WAAW,EAAE,SAAS,CAAC,WAAW;YAClC,4EAA4E;YAC5E,gEAAgE;YAChE,EAAE;YACF,iEAAiE;YACjE,sEAAsE;YACtE,yEAAyE;YACzE,uEAAuE;YACvE,wEAAwE;YACxE,mEAAmE;YACnE,oEAAoE;YACpE,iEAAiE;YACjE,iBAAiB;YACjB,KAAK,EAAE,SAAS,CAAC,KAAK,IAAI,WAAW,CAAC,GAAG;YACzC,IAAI,EAAE,SAAS,CAAC,IAAI;YACpB,KAAK,EAAE,SAAS,CAAC,KAAK;YACtB,MAAM,EAAE,WAAW,CAAC,MAAM;YAC1B,mBAAmB,EAAE,WAAW,CAAC,mBAAmB;YACpD,gBAAgB,EAAE,WAAW,CAAC,gBAAgB;YAC9C,aAAa,EAAE,WAAW,CAAC,aAAa;YACxC,oBAAoB,EAAE,WAAW,CAAC,oBAAoB;SACvD,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,UAAU,EAAE,QAAQ,CAAC,UAAU;QAC/B,QAAQ;QACR,iBAAiB,EAAE,QAAQ,CAAC,iBAAiB;KAC9C,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CAAC,QAAuC;IAChF,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,QAAQ,CAAC,UAAU;SACvB,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,SAAS,CAAC,cAAc,CAAC;SAC1C,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,mBAAmB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,oBAAoB;IAClC,MAAM,EAAE,WAAW,EAAE,GAAG,KAAK,EAAE,CAAC;IAChC,OAAO,wBAAwB,CAAC,WAAW,CAAC,CAAC;AAC/C,CAAC","sourcesContent":["/**\n * Resolves an application's authored Settings Hub config into the rendered shape.\n *\n * Resolution is the join between the two halves of the placement split: the\n * engine's destination catalog (`ENGINE_SETTINGS_DESTINATIONS` — what a settings\n * surface IS) and the application's placements (where each one sits). Neither\n * half renders alone.\n *\n * There is deliberately **no framework default and no merge**. An earlier\n * revision returned `DEFAULT_SETTINGS_HUB_CONFIG`, a fully placed hub the engine\n * owned, and that is precisely why an application could not remove or reorder a\n * settings section: the render path read the framework's arrangement, so an\n * application's absence of an arrangement was indistinguishable from agreement\n * with it. Here, an unplaced destination does not render — absence is how a\n * section is removed, and nothing reasserts it.\n */\nimport { ENGINE_SETTINGS_DESTINATIONS } from './engine-settings-destinations';\nimport type {\n  ResolvedSettingsHubConfig,\n  SettingsDestination,\n  SettingsHubConfig,\n  SettingsSection,\n} from './settings-hub.frontend.schemas';\nimport { useUI } from '~wildo-frontend-lib/core/ui/useUI';\n\n/** Catalog lookup by ref, built once — resolution runs on every hub render. */\nconst DESTINATIONS_BY_REF: ReadonlyMap<string, SettingsDestination> = new Map(\n  ENGINE_SETTINGS_DESTINATIONS.map(destination => [destination.ref, destination]),\n);\n\n/**\n * Pure (React-free) resolution — the single source of truth shared by\n * {@link useSettingsHubConfig} (render path) and the DEV-startup\n * `verifySettingsHubContent` pass.\n *\n * Keeping resolution here, not inlined in the hook, is what lets the verifier\n * check the EXACT config the hub renders. Do not inline it into either caller:\n * the moment the two derive their config separately, the verifier starts\n * attesting to something nobody renders.\n *\n * A placement naming a ref absent from the catalog is DROPPED here and reported\n * by the verifier rather than throwing. Resolution runs on the render path, and\n * a hard throw there would take down the whole hub over one bad ref; the DEV\n * startup pass is where an author is present to read the diagnostic.\n */\nexport function resolveSettingsHubConfig(authored: SettingsHubConfig | undefined): ResolvedSettingsHubConfig {\n  if (authored === undefined) {\n    return { categories: [], sections: [] };\n  }\n\n  const sections: SettingsSection[] = [];\n  for (const placement of authored.placements) {\n    const destination = DESTINATIONS_BY_REF.get(placement.destinationRef);\n    if (destination === undefined) {\n      continue;\n    }\n    sections.push({\n      ref: destination.ref,\n      categoryRef: placement.categoryRef,\n      // The authored label, falling back to the ref so an unlabelled placement is\n      // visibly wrong in the rail rather than rendering an empty tab.\n      //\n      // It is NOT superseded by label generation, and deleting it is a\n      // regression rather than a tidy-up. `tSettingsHubSection(ref, label)`\n      // takes this as the fallback when no key exists — and, more importantly,\n      // the companion feeds this exact string to the labellize prompt as the\n      // key's `purpose`. Generating without it made the model invent from the\n      // ref: \"User provisioning\" became \"SCIM\", \"Audit streaming\" became\n      // \"SIEM\", and a generated key WINS over the fallback, so the rail's\n      // wording changed. The authored string is the intent; generation\n      // translates it.\n      label: placement.label ?? destination.ref,\n      icon: placement.icon,\n      order: placement.order,\n      target: destination.target,\n      runtimeAvailability: destination.runtimeAvailability,\n      requiredFeatures: destination.requiredFeatures,\n      requiredRoles: destination.requiredRoles,\n      entitlementFeatureId: destination.entitlementFeatureId,\n    });\n  }\n\n  return {\n    categories: authored.categories,\n    sections,\n    defaultSectionRef: authored.defaultSectionRef,\n  };\n}\n\n/**\n * Every destination ref an authored config places that the catalog does not\n * ship. Reported by `verifySettingsHubContent`; see the note on\n * {@link resolveSettingsHubConfig} for why resolution drops rather than throws.\n */\nexport function findUnknownDestinationRefs(authored: SettingsHubConfig | undefined): string[] {\n  if (authored === undefined) {\n    return [];\n  }\n  return authored.placements\n    .map(placement => placement.destinationRef)\n    .filter(ref => !DESTINATIONS_BY_REF.has(ref));\n}\n\nexport function useSettingsHubConfig(): ResolvedSettingsHubConfig {\n  const { settingsHub } = useUI();\n  return resolveSettingsHubConfig(settingsHub);\n}\n"]}

package/dist/esm/core/config/useVisibleSettingsHubConfig.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Resolves the Settings Hub config gated to what the current user may see.
+ *
+ * Layered on {@link useSettingsHubConfig} (which resolves the application's
+ * authored placements against the engine destination catalog): this hook
+ * collects the live gating signals — primary scope, effective roles, resolved
+ * features, runtime capabilities — and runs the pure
+ * {@link filterSettingsHubConfig}. The hub component consumes the already-gated
+ * config, so it never has to know about scope/role/feature evaluation.
+ *
+ * Note the two stages answer different questions and must stay separate. This
+ * one asks "may THIS USER see the section" and its answer changes as the user's
+ * scope and roles change. Resolution asks "did the APPLICATION place it at all",
+ * and a `no` there is authorship, not gating — it must never be recoverable by a
+ * user gaining a role.
+ *
+ * Signals are sourced from the SAME hooks the rest of the frontend gating layer
+ * uses, so a settings section appears under exactly the same conditions as the
+ * equivalent sidebar/command-menu entry:
+ * - scope → `useAppScopeSafe`
+ * - effective roles → `buildFeaturePolicyRoles(permissions, currentOrganizationId)`
+ * - features → `useFeatures().resolvedFeatures`
+ * - capabilities → `useLauncherRuntimeAvailabilityContext`
+ */
+import type { ResolvedSettingsHubConfig } from './settings-hub.frontend.schemas';
+export declare function useVisibleSettingsHubConfig(): ResolvedSettingsHubConfig;
+//# sourceMappingURL=useVisibleSettingsHubConfig.d.ts.map

package/dist/esm/core/config/useVisibleSettingsHubConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useVisibleSettingsHubConfig.d.ts","sourceRoot":"","sources":["../../../../../src/core/config/useVisibleSettingsHubConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAUH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,iCAAiC,CAAC;AAEjF,wBAAgB,2BAA2B,IAAI,yBAAyB,CAoCvE"}