@discourse/types 2026.1.0-c7e9cdd → 2026.3.0-d02b2966

package/declarations/app/lib/blocks/-internals/patterns.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Checks if a resolved block is an optional missing block marker.
+ *
+ * @param {*} resolvedBlock - The result from tryResolveBlock.
+ * @returns {boolean} True if the block is an optional missing marker.
+ */
+export function isOptionalMissing(resolvedBlock: any): boolean;
+/**
+ * The parsed components of a block name.
+ *
+ * @typedef {{
+ *   type: "core"|"plugin"|"theme",
+ *   namespace: string|null,
+ *   name: string
+ * }} ParsedBlockName
+ */
+/**
+ * Parses a full block name into its components.
+ *
+ * @param {string} fullName - The full block name.
+ * @returns {ParsedBlockName|null}
+ *   An object with the parsed components, or `null` if the name is invalid.
+ *
+ * @example
+ * parseBlockName("group")
+ * // => { type: "core", namespace: null, name: "group" }
+ *
+ * parseBlockName("chat:message-widget")
+ * // => { type: "plugin", namespace: "chat", name: "message-widget" }
+ *
+ * parseBlockName("theme:tactile:hero-banner")
+ * // => { type: "theme", namespace: "theme:tactile", name: "hero-banner" }
+ *
+ * parseBlockName("Invalid_Name")
+ * // => null
+ */
+export function parseBlockName(fullName: string): ParsedBlockName | null;
+/**
+ * Parses a block reference string to extract the block name and optional flag.
+ *
+ * Block references can be marked as optional by appending a `?` suffix to the
+ * name. Optional blocks that are not registered will be silently skipped
+ * instead of throwing an error.
+ *
+ * Supports all namespaced formats:
+ * - Core: `"block-name"` or `"block-name?"`
+ * - Plugin: `"plugin:block"` or `"plugin:block?"`
+ * - Theme: `"theme:namespace:block"` or `"theme:namespace:block?"`
+ *
+ * @param {string|Object} blockRef - The block reference. If a string, may have an
+ *   optional `?` suffix. Non-string references (e.g., component classes) are
+ *   returned as-is in the `name` property with `optional: false`.
+ * @returns {{ name: string|Object, optional: boolean }} Parsed result with the clean
+ *   block name (or original reference) and whether it's optional.
+ *
+ * @example
+ * parseBlockReference("chat:widget?")
+ * // => { name: "chat:widget", optional: true }
+ *
+ * parseBlockReference("hero-banner")
+ * // => { name: "hero-banner", optional: false }
+ */
+export function parseBlockReference(blockRef: string | any): {
+    name: string | any;
+    optional: boolean;
+};
+/**
+ * Pattern constants for block name validation.
+ *
+ * @module discourse/lib/blocks/-internals/patterns
+ */
+/**
+ * Maximum allowed nesting depth for block layouts.
+ *
+ * Prevents stack overflow from deeply nested configurations. This limit is
+ * enforced at layout validation time with a clear error message, and as a
+ * defense-in-depth measure during ghost component rendering.
+ *
+ * A depth of 20 is generous for real-world use cases while protecting against
+ * malicious or buggy configurations that could cause infinite recursion.
+ *
+ * @type {number}
+ */
+export const MAX_LAYOUT_DEPTH: number;
+/**
+ * Maximum allowed length for block names.
+ *
+ * Prevents potential memory and performance issues from extremely long names.
+ * A limit of 100 characters is generous for real-world use cases while
+ * protecting against malicious or buggy configurations.
+ *
+ * This applies to the full namespaced name (e.g., "theme:my-theme:my-block").
+ *
+ * @type {number}
+ */
+export const MAX_BLOCK_NAME_LENGTH: number;
+/**
+ * Symbol used to mark a block reference as optional and missing from the registry.
+ * When this marker is returned from resolution functions, it signals that the block
+ * should be silently skipped rather than throwing an error.
+ *
+ * Used in layout validation and block registration to identify optional
+ * blocks that aren't registered and should be skipped during validation and rendering.
+ *
+ * @type {symbol}
+ */
+export const OPTIONAL_MISSING: symbol;
+/**
+ * Constants for failure type codes used by ghost blocks.
+ *
+ * These are internal codes for logic comparisons (e.g., determining which
+ * section to show in the ghost tooltip). Display messages are generated
+ * at render time in ghost-block.gjs based on these types.
+ *
+ * Custom failure reasons (like "hidden by priority" from the head block)
+ * don't need a type constant - they're passed as display strings directly
+ * via the `failureReason` field.
+ */
+export const FAILURE_TYPE: Readonly<{
+    /** Block's conditions evaluated to false. */
+    CONDITION_FAILED: "condition-failed";
+    /** Container block has no children that passed their conditions. */
+    NO_VISIBLE_CHILDREN: "no-visible-children";
+    /** Block reference uses `?` suffix but isn't registered. */
+    OPTIONAL_MISSING: "optional-missing";
+}>;
+/**
+ * Valid block name pattern: lowercase letters, numbers, and hyphens.
+ * Must start with a letter. Examples: "hero-banner", "sidebar-blocks", "my-block-1"
+ *
+ * Used for both block names and outlet names since they follow the same format.
+ */
+export const VALID_BLOCK_NAME_PATTERN: RegExp;
+/**
+ * Valid block ID pattern for the `id` entry property.
+ * Same format as block names: lowercase letters, numbers, and hyphens,
+ * must start with a letter.
+ *
+ * Examples: "featured-banner", "sidebar-1", "main-content"
+ */
+export const VALID_BLOCK_ID_PATTERN: RegExp;
+/**
+ * Valid namespaced block name pattern. Supports three formats:
+ *
+ * - **Core blocks**: `block-name` (no prefix)
+ * - **Plugin blocks**: `plugin-name:block-name` (where plugin-name is not "theme")
+ * - **Theme blocks**: `theme:theme-name:block-name`
+ *
+ * Each segment must start with a letter and contain only lowercase letters,
+ * numbers, and hyphens.
+ *
+ * @example
+ * // Valid patterns:
+ * "group"                      // Core block
+ * "chat:message-widget"        // Plugin block
+ * "theme:tactile:hero-banner"  // Theme block
+ *
+ * // Invalid patterns:
+ * "Theme:Name:block"           // Uppercase not allowed
+ * "theme:block"                // Theme requires namespace segment
+ * "my_block"                   // Underscores not allowed
+ */
+export const VALID_NAMESPACED_BLOCK_PATTERN: RegExp;
+/**
+ * The parsed components of a block name.
+ */
+export type ParsedBlockName = {
+    type: "core" | "plugin" | "theme";
+    namespace: string | null;
+    name: string;
+};
+//# sourceMappingURL=patterns.d.ts.map

package/declarations/app/lib/blocks/-internals/patterns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patterns.d.ts","sourceRoot":"","sources":["../../../../../../discourse/app/lib/blocks/-internals/patterns.js"],"names":[],"mappings":"AAkEA;;;;;GAKG;AACH,iDAHW,GAAC,GACC,OAAO,CAInB;AA2CD;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,yCAjBW,MAAM,GACJ,eAAe,GAAC,IAAI,CA0ChC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,8CAbW,MAAM,MAAO,GAGX;IAAE,IAAI,EAAE,MAAM,MAAO,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAetD;AA5MD;;;;GAIG;AAEH;;;;;;;;;;;GAWG;AACH,+BAFU,MAAM,CAEmB;AAEnC;;;;;;;;;;GAUG;AACH,oCAFU,MAAM,CAEyB;AAEzC;;;;;;;;;GASG;AACH,+BAFU,MAAM,CAE2C;AAE3D;;;;;;;;;;GAUG;AACH;IACE,6CAA6C;;IAE7C,oEAAoE;;IAEpE,4DAA4D;;GAE3D;AAYH;;;;;GAKG;AACH,8CAA4D;AAE5D;;;;;;GAMG;AACH,4CAA+D;AAE/D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,oDAC0G;;;;8BAK7F;IACR,IAAI,EAAE,MAAM,GAAC,QAAQ,GAAC,OAAO,CAAC;IAC9B,SAAS,EAAE,MAAM,GAAC,IAAI,CAAC;IACvB,IAAI,EAAE,MAAM,CAAA;CACb"}

package/declarations/app/lib/blocks/-internals/registry/block.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Returns whether the block registry is frozen.
+ *
+ * @returns {boolean}
+ */
+export function isBlockRegistryFrozen(): boolean;
+/**
+ * Checks if a block is registered (by name or class reference).
+ *
+ * This is a synchronous check that does not resolve factory functions.
+ * Use this to verify a block exists before attempting resolution.
+ *
+ * @param {string | BlockClass} nameOrClass - Block name string or BlockClass.
+ * @returns {boolean} True if the block is registered.
+ */
+export function hasBlock(nameOrClass: string | BlockClass): boolean;
+/**
+ * Returns the registry entry for a block (class or factory).
+ *
+ * @param {string} name - The block name.
+ * @returns {BlockRegistryEntry | undefined} The registry entry, or undefined if not found.
+ */
+export function getBlockEntry(name: string): BlockRegistryEntry | undefined;
+/**
+ * Returns all block entries with their names as [name, entry] pairs.
+ * Used by Blocks service for listing and introspection.
+ *
+ * @returns {Array<[string, BlockRegistryEntry]>} Array of [name, entry] pairs.
+ */
+export function getAllBlockEntries(): Array<[string, BlockRegistryEntry]>;
+/**
+ * Checks if a block is registered and fully resolved (not a pending factory).
+ *
+ * @param {string} name - The block name to check.
+ * @returns {boolean} True if registered and resolved.
+ */
+export function isBlockResolved(name: string): boolean;
+/**
+ * Checks if a registry entry is a factory function (not a resolved class).
+ *
+ * Factory functions are plain functions not registered in the block metadata WeakMap.
+ * BlockClasses are tracked by the `@block` decorator.
+ *
+ * @param {BlockRegistryEntry} entry - The registry entry to check.
+ * @returns {entry is BlockFactory} True if the entry is a factory function.
+ */
+export function isBlockFactory(entry: BlockRegistryEntry): entry is BlockFactory;
+/**
+ * Resolves a block reference (string name or class) to a BlockClass.
+ *
+ * - If given a BlockClass, returns it directly.
+ * - If given a string, looks up in registry and resolves factory if needed.
+ * - Caches resolved factories to avoid re-resolving.
+ *
+ * @param {string | BlockClass} nameOrClass - Block name string or BlockClass.
+ * @returns {Promise<BlockClass|undefined>} The resolved block class, or undefined if resolution previously failed.
+ * @throws {Error} If block not registered or factory resolution fails on first attempt.
+ *
+ * @example
+ * ```javascript
+ * const BlockClass = await resolveBlock("hero-banner");
+ * const BlockClass = await resolveBlock(HeroBanner); // Returns directly
+ * ```
+ */
+export function resolveBlock(nameOrClass: string | BlockClass): Promise<BlockClass | undefined>;
+/**
+ * Attempts to resolve a block reference to a BlockClass synchronously.
+ *
+ * If the block is already resolved, returns the BlockClass immediately.
+ * If the block is a factory that hasn't resolved yet, triggers async resolution
+ * and returns null. The calling component will automatically re-render when the
+ * factory resolves.
+ *
+ * @param {string | BlockClass} blockRef - Block reference (string name or class).
+ *   String names may include a trailing "?" to mark the block as optional.
+ * @returns {BlockClass | { optionalMissing: symbol, name: string } | null}
+ *   - The BlockClass if found and resolved
+ *   - An object with `optionalMissing` marker if the block is optional and not registered
+ *   - null if the block is not registered (non-optional) or is a factory awaiting resolution
+ */
+export function tryResolveBlock(blockRef: string | BlockClass): BlockClass | {
+    optionalMissing: symbol;
+    name: string;
+} | null;
+/**
+ * Freezes the registry, preventing further registrations.
+ * Called by the "freeze-block-registry" initializer during app boot.
+ *
+ * @internal
+ */
+export function _freezeBlockRegistry(): void;
+/**
+ * Registers a block component in the registry.
+ * Must be called before any renderBlocks() configuration is registered.
+ *
+ * The block component must be decorated with `@block`. Block metadata
+ * (including `blockName`) is stored in an internal WeakMap and accessed
+ * via `getBlockMetadata()`.
+ *
+ * @param {BlockClass} BlockClass - The block component class
+ * @throws {Error} If called after registry is locked, or if block is invalid
+ *
+ * @example
+ * ```javascript
+ * // In a plugin's pre-initializer (plugins/my-plugin/assets/javascripts/pre-initializers/...)
+ * import { withPluginApi } from "discourse/lib/plugin-api";
+ * import MyBlock from "../blocks/my-block";
+ *
+ * export default {
+ *   initialize() {
+ *     withPluginApi("1.0", (api) => {
+ *       api.registerBlock(MyBlock);
+ *     });
+ *   },
+ * };
+ * ```
+ */
+export function _registerBlock(BlockClass: BlockClass): void;
+/**
+ * Registers a factory function for lazy loading a block.
+ *
+ * The factory will be called when the block is first needed. It must return
+ * a Promise that resolves to a BlockClass (or a module with a default export).
+ *
+ * @param {string} name - The name to register the block under.
+ * @param {BlockFactory} factory - Factory function returning Promise<BlockClass>.
+ * @throws {Error} If registry is locked, name is invalid, or factory is not a function.
+ *
+ * @example
+ * ```javascript
+ * api.registerBlock("hero-banner", () => import("../blocks/hero-banner"));
+ * ```
+ *
+ * @internal
+ */
+export function _registerBlockFactory(name: string, factory: BlockFactory): void;
+/**
+ * Resets the block registry state for testing.
+ *
+ * USE ONLY FOR TESTING PURPOSES.
+ *
+ * @internal Called by `resetBlockRegistryForTesting`, not meant for direct use.
+ */
+export function _resetBlockRegistryState(): void;
+/**
+ * Temporarily unfreezes the block registry for testing.
+ *
+ * USE ONLY FOR TESTING PURPOSES.
+ *
+ * @param {Function} callback - Function to execute with unfrozen registry.
+ */
+export const withTestBlockRegistration: (callback: Function) => void;
+/**
+ * A block class decorated with `@block`.
+ *
+ * Block metadata is stored in an internal WeakMap and accessed via the
+ * `getBlockMetadata()` function from the decorator module.
+ */
+export type BlockClass = typeof import("@glimmer/component").default;
+/**
+ * Metadata object containing block configuration set by the `@block` decorator.
+ * Includes args schema, container settings, validation, and outlet restrictions.
+ */
+export type BlockMetadata = {
+    blockName: string;
+    shortName: string;
+    namespace: string | null;
+    namespaceType: "core" | "plugin" | "theme";
+    description: string;
+    isContainer: boolean;
+    decoratorClassNames: string | Array<string> | Function | null;
+    args: any | null;
+    childArgs: any | null;
+    constraints: any | null;
+    validate: Function | null;
+    allowedOutlets: ReadonlyArray<string> | null;
+    deniedOutlets: ReadonlyArray<string> | null;
+};
+/**
+ * A factory function that returns a Promise resolving to a BlockClass or module with default export.
+ */
+export type BlockFactory = () => Promise<BlockClass | {
+    default: BlockClass;
+}>;
+/**
+ * Registry entry: either a resolved BlockClass or a factory function for lazy loading.
+ */
+export type BlockRegistryEntry = BlockClass | BlockFactory;
+//# sourceMappingURL=block.d.ts.map

package/declarations/app/lib/blocks/-internals/registry/block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block.d.ts","sourceRoot":"","sources":["../../../../../../../discourse/app/lib/blocks/-internals/registry/block.js"],"names":[],"mappings":"AAkHA;;;;GAIG;AACH,yCAFa,OAAO,CAInB;AAED;;;;;;;;GAQG;AACH,sCAHW,MAAM,GAAG,UAAU,GACjB,OAAO,CAQnB;AAED;;;;;GAKG;AACH,oCAHW,MAAM,GACJ,kBAAkB,GAAG,SAAS,CAI1C;AAED;;;;;GAKG;AACH,sCAFa,KAAK,CAAC,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAI/C;AAED;;;;;GAKG;AACH,sCAHW,MAAM,GACJ,OAAO,CAQnB;AAED;;;;;;;;GAQG;AACH,sCAHW,kBAAkB,GAChB,KAAK,IAAI,YAAY,CAIjC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,0CAVW,MAAM,GAAG,UAAU,GACjB,OAAO,CAAC,UAAU,GAAC,SAAS,CAAC,CAkDzC;AAED;;;;;;;;;;;;;;GAcG;AACH,0CAPW,MAAM,GAAG,UAAU,GAEjB,UAAU,GAAG;IAAE,eAAe,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAgDzE;AAMD;;;;;GAKG;AACH,6CAEC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,2CAlBW,UAAU,QAoDpB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,4CAXW,MAAM,WACN,YAAY,QA0CtB;AAyED;;;;;;GAMG;AACH,iDAcC;AAxCD;;;;;;GAMG;AACH,qEAUG;;;;;;;yBA/dU,cAAc,oBAAoB,EAAE,OAAO;;;;;4BAO3C;IACR,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,GAAC,IAAI,CAAC;IACvB,aAAa,EAAE,MAAM,GAAC,QAAQ,GAAC,OAAO,CAAC;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;IACrB,mBAAmB,EAAE,MAAM,GAAC,KAAK,CAAC,MAAM,CAAC,cAAU,IAAI,CAAC;IACxD,IAAI,EAAE,MAAO,IAAI,CAAC;IAClB,SAAS,EAAE,MAAO,IAAI,CAAC;IACvB,WAAW,EAAE,MAAO,IAAI,CAAC;IACzB,QAAQ,EAAE,WAAS,IAAI,CAAC;IACxB,cAAc,EAAE,aAAa,CAAC,MAAM,CAAC,GAAC,IAAI,CAAC;IAC3C,aAAa,EAAE,aAAa,CAAC,MAAM,CAAC,GAAC,IAAI,CAAA;CAC1C;;;;2BAMS,MAAM,OAAO,CAAC,UAAU,GAAG;IAAE,OAAO,EAAE,UAAU,CAAA;CAAE,CAAC;;;;iCAMnD,UAAU,GAAG,YAAY"}

package/declarations/app/lib/blocks/-internals/registry/condition.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Returns whether the condition type registry is frozen.
+ *
+ * @returns {boolean}
+ */
+export function isConditionTypeRegistryFrozen(): boolean;
+/**
+ * Checks if a condition type is registered.
+ *
+ * @param {string} type - The condition type name.
+ * @returns {boolean}
+ */
+export function hasConditionType(type: string): boolean;
+/**
+ * Returns all condition type entries as [type, ConditionClass] pairs.
+ * Used by Blocks service for lazy initialization.
+ *
+ * @returns {Array<[string, typeof import("discourse/blocks/conditions").BlockCondition]>}
+ */
+export function getAllConditionTypeEntries(): Array<[string, typeof import("discourse/blocks/conditions").BlockCondition]>;
+/**
+ * Freezes the condition type registry, preventing further registrations.
+ * Called by the "freeze-block-registry" initializer during app boot.
+ *
+ * @internal
+ */
+export function _freezeConditionTypeRegistry(): void;
+/**
+ * Registers a condition type class in the registry.
+ * Must be called before the registry is frozen by the "freeze-block-registry" initializer.
+ *
+ * The condition class must be decorated with `@blockCondition`
+ *
+ * @param {typeof import("discourse/blocks/conditions").BlockCondition} ConditionClass - The condition class to register.
+ *
+ * @example
+ * ```javascript
+ * import { withPluginApi } from "discourse/lib/plugin-api";
+ * import MyCondition from "../conditions/my-condition";
+ *
+ * export default {
+ *   initialize() {
+ *     withPluginApi((api) => {
+ *       api.registerBlockConditionType(MyCondition);
+ *     });
+ *   },
+ * };
+ * ```
+ *
+ * @internal
+ */
+export function _registerConditionType(ConditionClass: typeof import("discourse/blocks/conditions").BlockCondition): void;
+/**
+ * Resets the condition registry state for testing.
+ *
+ * USE ONLY FOR TESTING PURPOSES.
+ *
+ * @internal Called by `resetBlockRegistryForTesting`, not meant for direct use.
+ */
+export function _resetConditionRegistryState(): void;
+/**
+ * Temporarily unfreezes the condition type registry for testing purposes.
+ * Call this before registering condition types in tests.
+ *
+ * USE ONLY FOR TESTING PURPOSES.
+ *
+ * @param {Function} callback - Function to execute with unfrozen registry.
+ *
+ * @example
+ * ```javascript
+ * withTestConditionRegistration(() => {
+ *   _registerConditionType(MyTestCondition);
+ * });
+ * ```
+ */
+export const withTestConditionRegistration: (callback: Function) => void;
+//# sourceMappingURL=condition.d.ts.map

package/declarations/app/lib/blocks/-internals/registry/condition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"condition.d.ts","sourceRoot":"","sources":["../../../../../../../discourse/app/lib/blocks/-internals/registry/condition.js"],"names":[],"mappings":"AA2CA;;;;GAIG;AACH,iDAFa,OAAO,CAInB;AAED;;;;;GAKG;AACH,uCAHW,MAAM,GACJ,OAAO,CAInB;AAED;;;;;GAKG;AACH,8CAFa,KAAK,CAAC,CAAC,MAAM,EAAE,cAAc,6BAA6B,EAAE,cAAc,CAAC,CAAC,CAIxF;AAMD;;;;;GAKG;AACH,qDAEC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,uDAlBW,cAAc,6BAA6B,EAAE,cAAc,QAyDrE;AAiCD;;;;;;GAMG;AACH,qDAWC;AA7CD;;;;;;;;;;;;;;GAcG;AACH,yEAUG"}

package/declarations/app/lib/blocks/-internals/registry/helpers.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Asserts that a registry is not frozen before registration.
+ *
+ * @param {Object} options - Validation options.
+ * @param {boolean} options.frozen - Whether the registry is frozen.
+ * @param {string} options.apiMethod - The API method name for the error message.
+ * @param {string} options.entityType - Type of entity (e.g., "Block", "Outlet", "Condition").
+ * @param {string} options.entityName - Name of the entity being registered.
+ * @returns {boolean} True if not frozen, false if frozen (error was raised).
+ */
+export function assertRegistryNotFrozen({ frozen, apiMethod, entityType, entityName, }: {
+    frozen: boolean;
+    apiMethod: string;
+    entityType: string;
+    entityName: string;
+}): boolean;
+/**
+ * Validates that a name follows the namespaced block/outlet name pattern.
+ *
+ * Checks both the pattern format and maximum length to prevent memory and
+ * performance issues from extremely long names.
+ *
+ * @param {string} name - The name to validate.
+ * @param {string} entityType - Type of entity for error messages (e.g., "Block", "Outlet").
+ * @returns {boolean} True if valid, false if invalid (error was raised).
+ */
+export function validateNamePattern(name: string, entityType: string): boolean;
+/**
+ * Asserts that an entry is not already registered.
+ *
+ * @param {Map} registry - The registry to check.
+ * @param {string} name - The name to check.
+ * @param {string} entityType - Type of entity for error messages.
+ * @returns {boolean} True if not duplicate, false if duplicate (error was raised).
+ */
+export function assertNotDuplicate(registry: Map<any, any>, name: string, entityType: string): boolean;
+/**
+ * Validates that a block or outlet name follows namespace requirements for themes and plugins.
+ *
+ * This helper enforces the following rules:
+ * - Themes must use `theme:namespace:name` format
+ * - Plugins must use `namespace:name` format
+ * - Optionally enforces that each source uses a consistent namespace across all registrations
+ *
+ * @param {Object} options - Validation options.
+ * @param {string} options.name - The name being registered.
+ * @param {"block"|"outlet"|"condition"} options.entityType - Type of entity for error messages.
+ * @param {boolean} [options.enforceConsistency=true] - Whether to enforce single namespace per source.
+ * @returns {boolean} True if validation passes, false if it failed (error was raised).
+ */
+export function validateSourceNamespace({ name, entityType, enforceConsistency, }: {
+    name: string;
+    entityType: "block" | "outlet" | "condition";
+    enforceConsistency?: boolean;
+}): boolean;
+/**
+ * Creates a test registration wrapper function for temporarily unfreezing a registry.
+ *
+ * USE ONLY FOR TESTING PURPOSES.
+ *
+ * @param {Object} options - Options object.
+ * @param {() => boolean} options.getFrozen - Function to get frozen state.
+ * @param {(value: boolean) => void} options.setFrozen - Function to set frozen state.
+ * @param {() => boolean|null} options.getSavedState - Function to get saved test state.
+ * @param {(value: boolean|null) => void} options.setSavedState - Function to set saved test state.
+ * @param {string} options.name - Name for error message.
+ * @returns {((callback: Function) => void)|undefined} The wrapper function.
+ */
+export function createTestRegistrationWrapper({ getFrozen, setFrozen, getSavedState, setSavedState, name, }: {
+    getFrozen: () => boolean;
+    setFrozen: (value: boolean) => void;
+    getSavedState: () => boolean | null;
+    setSavedState: (value: boolean | null) => void;
+    name: string;
+}): ((callback: Function) => void) | undefined;
+/**
+ * Internal implementation for setting the test source identifier.
+ *
+ * USE ONLY FOR TESTING PURPOSES.
+ *
+ * @param {string|null} sourceId - Source identifier to use, or null to clear.
+ * @internal Called by `setTestSourceIdentifier` in block-testing.js.
+ */
+export function _setTestSourceIdentifierInternal(sourceId: string | null): void;
+/**
+ * Resets the source namespace map and test source identifier.
+ *
+ * USE ONLY FOR TESTING PURPOSES.
+ *
+ * @internal Called by `resetBlockRegistryForTesting`, not meant for direct use.
+ */
+export function _resetSourceNamespaceState(): void;
+//# sourceMappingURL=helpers.d.ts.map

package/declarations/app/lib/blocks/-internals/registry/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../../../../../discourse/app/lib/blocks/-internals/registry/helpers.js"],"names":[],"mappings":"AAgCA;;;;;;;;;GASG;AACH,wFANG;IAAyB,MAAM,EAAvB,OAAO;IACS,SAAS,EAAzB,MAAM;IACU,UAAU,EAA1B,MAAM;IACU,UAAU,EAA1B,MAAM;CACd,GAAU,OAAO,CAiBnB;AAED;;;;;;;;;GASG;AACH,0CAJW,MAAM,cACN,MAAM,GACJ,OAAO,CAsBnB;AAED;;;;;;;GAOG;AACH,kEAJW,MAAM,cACN,MAAM,GACJ,OAAO,CAQnB;AAED;;;;;;;;;;;;;GAaG;AACH,mFALG;IAAwB,IAAI,EAApB,MAAM;IACgC,UAAU,EAAhD,OAAO,GAAC,QAAQ,GAAC,WAAW;IACV,kBAAkB,GAApC,OAAO;CACf,GAAU,OAAO,CA6DnB;AAED;;;;;;;;;;;;GAYG;AACH,6GAPG;IAA+B,SAAS,EAAhC,MAAM,OAAO;IACqB,SAAS,EAA3C,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI;IACI,aAAa,EAAzC,MAAM,OAAO,GAAC,IAAI;IACqB,aAAa,EAApD,CAAC,KAAK,EAAE,OAAO,GAAC,IAAI,KAAK,IAAI;IACb,IAAI,EAApB,MAAM;CACd,GAAU,CAAC,CAAC,QAAQ,UAAU,KAAK,IAAI,CAAC,GAAC,SAAS,CA6BpD;AAuDD;;;;;;;GAOG;AACH,2DAHW,MAAM,GAAC,IAAI,QASrB;AAED;;;;;;GAMG;AACH,mDAUC"}

package/declarations/app/lib/blocks/-internals/registry/outlet.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Returns whether the outlet registry is frozen.
+ *
+ * @returns {boolean}
+ */
+export function isOutletRegistryFrozen(): boolean;
+/**
+ * Returns all valid outlet names (both core and custom).
+ *
+ * @returns {string[]} Array of all outlet names.
+ */
+export function getAllOutlets(): string[];
+/**
+ * Checks if an outlet name is valid (registered as core or custom).
+ *
+ * @param {string} name - The outlet name to check.
+ * @returns {boolean} True if the outlet is registered.
+ */
+export function isValidOutlet(name: string): boolean;
+/**
+ * Gets metadata for a custom outlet.
+ *
+ * @param {string} name - The outlet name.
+ * @returns {{ name: string, description?: string } | undefined} Outlet metadata or undefined.
+ */
+export function getCustomOutlet(name: string): {
+    name: string;
+    description?: string;
+} | undefined;
+/**
+ * Freezes the outlet registry, preventing further registrations.
+ * Called by the "freeze-block-registry" initializer during app boot.
+ *
+ * @internal
+ */
+export function _freezeOutletRegistry(): void;
+/**
+ * Registers a custom block outlet.
+ *
+ * Custom outlets follow the same naming conventions as blocks:
+ * - Core outlets: `outlet-name` (kebab-case)
+ * - Plugin outlets: `namespace:outlet-name`
+ * - Theme outlets: `theme:namespace:outlet-name`
+ *
+ * @param {string} outletName - The outlet name (must follow naming conventions).
+ * @param {Object} [options] - Outlet options.
+ * @param {string} [options.description] - Human-readable description.
+ *
+ * @internal
+ */
+export function _registerOutlet(outletName: string, options?: {
+    description?: string;
+}): void;
+/**
+ * Resets the outlet registry state for testing.
+ *
+ * USE ONLY FOR TESTING PURPOSES.
+ *
+ * @internal Called by `resetBlockRegistryForTesting`, not meant for direct use.
+ */
+export function _resetOutletRegistryState(): void;
+//# sourceMappingURL=outlet.d.ts.map

package/declarations/app/lib/blocks/-internals/registry/outlet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outlet.d.ts","sourceRoot":"","sources":["../../../../../../../discourse/app/lib/blocks/-internals/registry/outlet.js"],"names":[],"mappings":"AAgCA;;;;GAIG;AACH,0CAFa,OAAO,CAInB;AAED;;;;GAIG;AACH,iCAFa,MAAM,EAAE,CAIpB;AAED;;;;;GAKG;AACH,oCAHW,MAAM,GACJ,OAAO,CAInB;AAED;;;;;GAKG;AACH,sCAHW,MAAM,GACJ;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAI9D;AAMD;;;;;GAKG;AACH,8CAEC;AAED;;;;;;;;;;;;;GAaG;AACH,4CANW,MAAM,YAEd;IAAyB,WAAW,GAA5B,MAAM;CAEd,QA8CF;AAMD;;;;;;GAMG;AACH,kDAUC"}