@discourse/types 2026.8.0-fb9247e0 → 2026.9.0-c0ef3a11

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

@@ -1,27 +1,37 @@
 /**
- * Validates the arg schema definition passed to the @blockCondition decorator.
+ * Condition-specific arg validation.
+ *
+ * This module adapts the shared arg validation utilities from args.ts
+ * for use with block conditions. Key differences from block arg validation:
+ * - Error messages use "Condition" instead of "Block"
+ * - The "default" property is not allowed (conditions don't use defaults)
+ * - Type validation happens at registration time
+ */
+import type { ArgSchema } from "discourse/blocks/types";
+/**
+ * Valid properties for condition arg schemas.
+ * Includes all standard arg properties except those in DISALLOWED_CONDITION_PROPERTIES.
+ */
+export declare const VALID_CONDITION_ARG_PROPERTIES: readonly string[];
+/**
+ * Validates the arg schema definition passed to the `@blockCondition` decorator.
  * Enforces strict schema format - unknown properties are not allowed.
  * Called at decoration time to catch schema errors early.
  *
- * @param {Object} argsSchema - The args schema object from decorator options.
- * @param {string} conditionType - Condition type name for error messages.
- * @throws {Error} If schema is invalid.
+ * @param argsSchema - The args schema object from decorator options.
+ * @param conditionType - Condition type name for error messages.
+ * @throws Error if schema is invalid.
  */
-export function validateConditionArgsSchema(argsSchema: any, conditionType: string): void;
+export declare function validateConditionArgsSchema(argsSchema: Record<string, ArgSchema> | null | undefined, conditionType: string): void;
 /**
  * Validates provided arg values against the condition's schema.
  * Called at block registration time to catch invalid values early.
  *
- * @param {Object} args - The arguments provided to the condition.
- * @param {Object} argsSchema - The condition's args schema.
- * @param {string} conditionType - The condition type for error messages.
- * @param {string} path - The path to this condition in the block tree.
- * @throws {BlockError} If validation fails.
- */
-export function validateConditionArgValues(args: any, argsSchema: any, conditionType: string, path: string): void;
-/**
- * Valid properties for condition arg schemas.
- * Includes all standard arg properties except those in DISALLOWED_CONDITION_PROPERTIES.
+ * @param args - The arguments provided to the condition.
+ * @param argsSchema - The condition's args schema.
+ * @param conditionType - The condition type for error messages.
+ * @param path - The path to this condition in the block tree.
+ * @throws BlockError if validation fails.
  */
-export const VALID_CONDITION_ARG_PROPERTIES: readonly string[];
+export declare function validateConditionArgValues(args: Record<string, unknown>, argsSchema: Record<string, ArgSchema>, conditionType: string, path: string): void;
 //# sourceMappingURL=condition-args.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"condition-args.d.ts","sourceRoot":"","sources":["../../../../../../../discourse/app/lib/blocks/-internals/validation/condition-args.js"],"names":[],"mappings":"AAyCA;;;;;;;;GAQG;AACH,4EAHW,MAAM,QA2BhB;AAcD;;;;;;;;;GASG;AACH,sFAJW,MAAM,QACN,MAAM,QAsChB;AAtGD;;;GAGG;AACH,+DAIE"}
+{"version":3,"file":"condition-args.d.ts","sourceRoot":"","sources":["../../../../../../../discourse/app/lib/blocks/-internals/validation/condition-args.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAoBxD;;;GAGG;AACH,eAAO,MAAM,8BAA8B,EAAE,SAAS,MAAM,EAI3D,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,IAAI,GAAG,SAAS,EACxD,aAAa,EAAE,MAAM,GACpB,IAAI,CAwBN;AAkBD;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EACrC,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,MAAM,GACX,IAAI,CA8BN"}

package/declarations/app/lib/blocks/-internals/validation/conditions.d.ts

@@ -1,3 +1,11 @@
+import type { BlockCondition } from "discourse/blocks/conditions";
+/** The result of `validateConditionSource()`: error info, or `null` if valid. */
+export interface ConditionSourceError {
+    /** The error message. */
+    message: string;
+    /** The path to the invalid `source` parameter. */
+    path?: string;
+}
 /**
  * Validates the `source` parameter based on the condition's `sourceType`.
  *
@@ -5,25 +13,22 @@
  * - `sourceType: "outletArgs"`: Validates format is `@outletArgs.propertyPath`
  * - `sourceType: "object"`: Validates `source` is an object if provided
  *
- * @param {"none"|"outletArgs"|"object"} sourceType - The condition's source type.
- * @param {Object} args - The condition arguments from the layout entry.
- * @returns {{ message: string, path?: string } | null} Error info or null if valid.
+ * @param sourceType - The condition's source type.
+ * @param args - The condition arguments from the layout entry.
+ * @returns Error info or null if valid.
  */
-export function validateConditionSource(sourceType: "none" | "outletArgs" | "object", args: any): {
-    message: string;
-    path?: string;
-} | null;
+export declare function validateConditionSource(sourceType: "none" | "outletArgs" | "object", args: Record<string, unknown>): ConditionSourceError | null;
 /**
  * Validates that all provided args are recognized by a condition.
  * Suggests corrections for typos using fuzzy string matching.
  *
- * @param {import("discourse/blocks/conditions").BlockCondition} instance - The condition instance.
- * @param {string} type - The condition type name.
- * @param {Object} args - The args provided to the condition.
- * @param {string} path - The path to this condition in the block tree.
- * @throws {BlockError} If an unrecognized arg key is found.
+ * @param instance - The condition instance.
+ * @param type - The condition type name.
+ * @param args - The args provided to the condition.
+ * @param path - The path to this condition in the block tree.
+ * @throws BlockError if an unrecognized arg key is found.
  */
-export function validateConditionArgKeys(instance: import("discourse/blocks/conditions").BlockCondition, type: string, args: any, path: string): void;
+export declare function validateConditionArgKeys(instance: BlockCondition, type: string, args: Record<string, unknown>, path: string): void;
 /**
  * Validates condition specs at block registration time.
  * Recursively validates nested conditions in `any` and `not` combinators.
@@ -38,11 +43,11 @@ export function validateConditionArgKeys(instance: import("discourse/blocks/cond
  * This is acceptable since condition keys come from theme/plugin layouts
  * where unusual characters are rare.
  *
- * @param {Object|Array<Object>} conditionSpec - Condition spec(s) to validate.
- * @param {Map<string, import("discourse/blocks/conditions").BlockCondition>} conditionTypes - Map of registered condition types.
- * @param {string} [path=""] - The path to this condition relative to conditions root
+ * @param conditionSpec - Condition spec(s) to validate.
+ * @param conditionTypes - Map of registered condition types.
+ * @param path - The path to this condition relative to conditions root
  *   (e.g., "", "[0]", "any[1]", "params.categoryId").
- * @throws {BlockError} If validation fails.
+ * @throws BlockError if validation fails.
  */
-export function validateConditions(conditionSpec: any | Array<any>, conditionTypes: Map<string, import("discourse/blocks/conditions").BlockCondition>, path?: string): void;
+export declare function validateConditions(conditionSpec: unknown, conditionTypes: Map<string, BlockCondition>, path?: string): void;
 //# sourceMappingURL=conditions.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"conditions.d.ts","sourceRoot":"","sources":["../../../../../../../discourse/app/lib/blocks/-internals/validation/conditions.js"],"names":[],"mappings":"AAeA;;;;;;;;;;GAUG;AACH,oDAJW,MAAM,GAAC,YAAY,GAAC,QAAQ,cAE1B;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CA0CrD;AAED;;;;;;;;;GASG;AACH,mDANW,OAAO,6BAA6B,EAAE,cAAc,QACpD,MAAM,mBAEN,MAAM,QAmBhB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,kDANW,MAAO,KAAK,KAAQ,kBACpB,GAAG,CAAC,MAAM,EAAE,OAAO,6BAA6B,EAAE,cAAc,CAAC,SACjE,MAAM,QA+BhB"}
+{"version":3,"file":"conditions.d.ts","sourceRoot":"","sources":["../../../../../../../discourse/app/lib/blocks/-internals/validation/conditions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAelE,iFAAiF;AACjF,MAAM,WAAW,oBAAoB;IACnC,yBAAyB;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,MAAM,GAAG,YAAY,GAAG,QAAQ,EAC5C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,oBAAoB,GAAG,IAAI,CAwC7B;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,IAAI,EAAE,MAAM,GACX,IAAI,CAoBN;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,OAAO,EACtB,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,EAC3C,IAAI,SAAK,GACR,IAAI,CAuCN"}

package/declarations/app/lib/blocks/-internals/validation/constraints.d.ts

@@ -1,3 +1,21 @@
+/**
+ * Cross-arg constraint validation for blocks.
+ *
+ * This module handles validation rules that span multiple arguments, such as
+ * "at least one of these args must be provided" or "these args must be provided together."
+ *
+ * Supported constraint types:
+ * - atLeastOne: At least one of the specified args must be provided
+ * - exactlyOne: Exactly one of the specified args must be provided
+ * - allOrNone: Either all or none of the specified args must be provided
+ * - atMostOne: At most one of the specified args may be provided (0 or 1)
+ * - requires: If a dependent arg is provided, its required arg must also be provided
+ */
+import type { ArgSchema, BlockConstraints, BlockValidateFn } from "discourse/blocks/types";
+/**
+ * Valid constraint types for cross-arg validation.
+ */
+export declare const VALID_CONSTRAINT_TYPES: readonly string[];
 /**
  * Validates the constraints schema at decoration time.
  * Checks for:
@@ -7,31 +25,27 @@
  * - Incompatible constraints (exactlyOne + allOrNone, exactlyOne + atLeastOne)
  * - Vacuous constraints (constraints rendered always true/false by defaults)
  *
- * @param {Object} constraints - The constraints object from decorator options.
- * @param {Object} argsSchema - The args schema object from decorator options.
- * @param {string} blockName - Block name for error messages.
+ * @param constraints - The constraints object from decorator options.
+ * @param argsSchema - The args schema object from decorator options.
+ * @param blockName - Block name for error messages.
  */
-export function validateConstraintsSchema(constraints: any, argsSchema: any, blockName: string): void;
+export declare function validateConstraintsSchema(constraints: BlockConstraints | null | undefined, argsSchema: Record<string, ArgSchema> | null | undefined, blockName: string): void;
 /**
  * Validates constraints against the provided args at runtime.
  * Called after defaults are applied.
  *
- * @param {Object} constraints - The constraints from block metadata.
- * @param {Object} args - The resolved args (with defaults applied).
- * @param {string} blockName - Block name for error messages.
- * @returns {string|null} Error message if validation fails, null otherwise.
+ * @param constraints - The constraints from block metadata.
+ * @param args - The resolved args (with defaults applied).
+ * @param blockName - Block name for error messages.
+ * @returns Error message if validation fails, null otherwise.
  */
-export function validateConstraints(constraints: any, args: any, blockName: string): string | null;
+export declare function validateConstraints(constraints: BlockConstraints | null | undefined, args: Record<string, unknown>, blockName: string): string | null;
 /**
  * Runs a custom validation function if provided.
  *
- * @param {Function} validateFn - The custom validate function.
- * @param {Object} args - The resolved args (with defaults applied).
- * @returns {string[]|null} Array of error messages if validation fails, null otherwise.
- */
-export function runCustomValidation(validateFn: Function, args: any): string[] | null;
-/**
- * Valid constraint types for cross-arg validation.
+ * @param validateFn - The custom validate function.
+ * @param args - The resolved args (with defaults applied).
+ * @returns Array of error messages if validation fails, null otherwise.
  */
-export const VALID_CONSTRAINT_TYPES: readonly string[];
+export declare function runCustomValidation(validateFn: BlockValidateFn | null | undefined, args: Record<string, unknown>): string[] | null;
 //# sourceMappingURL=constraints.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"constraints.d.ts","sourceRoot":"","sources":["../../../../../../../discourse/app/lib/blocks/-internals/validation/constraints.js"],"names":[],"mappings":"AAyCA;;;;;;;;;;;;GAYG;AACH,wFAFW,MAAM,QAmHhB;AAkID;;;;;;;;GAQG;AACH,4EAHW,MAAM,GACJ,MAAM,GAAC,IAAI,CAuCvB;AAiHD;;;;;;GAMG;AACH,sEAFa,MAAM,EAAE,GAAC,IAAI,CA0BzB;AAndD;;GAEG;AACH,uDAMG"}
+{"version":3,"file":"constraints.d.ts","sourceRoot":"","sources":["../../../../../../../discourse/app/lib/blocks/-internals/validation/constraints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EACV,SAAS,EACT,gBAAgB,EAChB,eAAe,EAChB,MAAM,wBAAwB,CAAC;AAIhC;;GAEG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAMlD,CAAC;AAYH;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,EAChD,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,IAAI,GAAG,SAAS,EACxD,SAAS,EAAE,MAAM,GAChB,IAAI,CAuHN;AAsID;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,EAChD,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,IAAI,CA0Cf;AAqID;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,EAC9C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,MAAM,EAAE,GAAG,IAAI,CA6BjB"}

package/declarations/app/lib/blocks/-internals/validation/layout.d.ts

@@ -1,12 +1,37 @@
+import type { ChildArgSchema, LayoutEntry } from "discourse/blocks/types";
+import { OPTIONAL_MISSING } from "discourse/lib/blocks/-internals/patterns";
+import type { BlockClass } from "discourse/lib/blocks/-internals/types";
+import type Blocks from "discourse/services/blocks";
 /**
  * Validates that a block entry's `id` matches the required pattern.
  * IDs must start with a lowercase letter and contain only lowercase letters,
  * numbers, and hyphens (same format as block names).
  *
- * @param {Object} entry - The block entry.
- * @throws {BlockError} If the id format is invalid.
+ * @param entry - The block entry.
+ * @throws BlockError if the id format is invalid.
  */
-export function validateEntryIdFormat(entry: any): void;
+export declare function validateEntryIdFormat(entry: LayoutEntry): void;
+/** Context accepted by `resolveBlockForValidation`. */
+interface ResolveBlockForValidationContext {
+    /** Path to this entry in the block tree. */
+    path?: string;
+    /** The block entry object. */
+    entry?: LayoutEntry | null;
+    /** Error capturing call site location. */
+    callSiteError?: Error | null;
+    /** Root layout array for error display. */
+    rootLayout?: LayoutEntry[] | null;
+}
+/**
+ * Marker returned by `resolveBlockForValidation()` for an optional block
+ * reference (`name?`) that isn't registered, keyed by the `OPTIONAL_MISSING`
+ * symbol (distinct from the `registry/block.ts` `OptionalMissingMarker` shape,
+ * which is keyed by the plain `"optionalMissing"` property).
+ */
+type ResolveOptionalMissingMarker = {
+    [OPTIONAL_MISSING]: true;
+    name: string;
+};
 /**
  * Resolves a block reference (string or class) to a BlockClass for validation.
  *
@@ -25,25 +50,19 @@ export function validateEntryIdFormat(entry: any): void;
  * is returned instead of throwing an error. The calling code should check for this
  * marker and skip validation/rendering for the block.
  *
- * @param {string | Object} blockRef - Block name string (possibly with `?` suffix) or BlockClass.
- * @param {string} outletName - Outlet name for error messages.
- * @param {Object} [context] - Context for error messages.
- * @param {string} [context.path] - Path to this entry in the block tree.
- * @param {Object} [context.entry] - The block entry object.
- * @param {Error} [context.callSiteError] - Error capturing call site location.
- * @param {Array} [context.rootLayout] - Root layout array for error display.
- * @returns {Promise<Object | string | { [OPTIONAL_MISSING]: true, name: string }>}
- *   Resolved BlockClass, string name if deferred, or optional missing marker object.
- * @throws {Error} If required block is not registered.
+ * @param blockRef - Block name string (possibly with `?` suffix) or BlockClass.
+ * @param outletName - Outlet name for error messages.
+ * @param context - Context for error messages.
+ * @returns Resolved BlockClass, string name if deferred, or optional missing marker object.
+ * @throws Error if required block is not registered.
  */
-export function resolveBlockForValidation(blockRef: string | any, outletName: string, context?: {
-    path?: string;
-    entry?: any;
-    callSiteError?: Error;
-    rootLayout?: any[];
-}): Promise<any | string | {
-    name: string;
-}>;
+export declare function resolveBlockForValidation(blockRef: string | BlockClass, outletName: string, context?: ResolveBlockForValidationContext): Promise<BlockClass | string | ResolveOptionalMissingMarker | null | undefined>;
+/**
+ * Valid top-level keys in block entry objects.
+ * Any key not in this list will trigger a validation error, helping catch
+ * common typos like `condition` instead of `conditions`.
+ */
+export declare const VALID_ENTRY_KEYS: readonly string[];
 /**
  * Validates that a block entry only uses known keys.
  * Uses fuzzy matching to suggest corrections for typos like "condition",
@@ -52,26 +71,29 @@ export function resolveBlockForValidation(blockRef: string | any, outletName: st
  * Internal keys (starting with `__`) are skipped as they are added by the
  * system during preprocessing (e.g., `__visible`, `__failureReason`).
  *
- * @param {Object} entry - The block entry object.
- * @throws {BlockError} If unknown keys are found.
+ * @param entry - The block entry object.
+ * @throws BlockError if unknown keys are found.
  */
-export function validateEntryKeys(entry: any): void;
+export declare function validateEntryKeys(entry: LayoutEntry): void;
 /**
  * Validates the types of optional entry fields.
  * Iterates over ENTRY_TYPE_RULES to check each field's type.
  *
- * @param {Object} entry - The block entry object.
- * @throws {BlockError} If any field has an invalid type.
+ * @param entry - The block entry object.
+ * @throws BlockError if any field has an invalid type.
  */
-export function validateEntryTypes(entry: any): void;
+export declare function validateEntryTypes(entry: LayoutEntry): void;
 /**
  * Validation context passed through layout validation recursion.
  * Created at the root level and shared across all entries to enable
  * cross-cutting validation (e.g., ID uniqueness across the entire tree).
- *
- * @typedef {Object} LayoutValidationContext
- * @property {Map<string, {path: string}>} seenIds - Map of entry IDs to their paths for uniqueness validation.
  */
+export interface LayoutValidationContext {
+    /** Map of entry IDs to their paths for uniqueness validation. */
+    seenIds: Map<string, {
+        path: string;
+    }>;
+}
 /**
  * Recursively validates an outlet layout (array of block entries).
  * Validates each block entry and traverses nested children.
@@ -80,26 +102,25 @@ export function validateEntryTypes(entry: any): void;
  * - In dev/test: Eagerly resolves all factories for early error detection.
  * - In production: Defers factory resolution to render time.
  *
- * @param {Array<Object>} layout - The outlet layout (array of block entries) to validate.
- * @param {string} outletName - The outlet these blocks belong to.
- * @param {import("discourse/services/blocks").default} blocksService - Service for validating conditions.
- * @param {string} [parentPath=""] - JSON-path style parent location for error context.
- * @param {Error | null} [callSiteError] - Where renderBlocks() was called from.
- * @param {Array<Object>} [rootLayout] - The root layout array for error context display.
- * @param {Object|null} [parentChildArgsSchema=null] - The parent container's childArgs schema, if any.
- * @param {string|null} [parentBlockName=null] - The parent container's block name for error messages.
- * @param {number} [depth=0] - Current nesting depth for recursion limit checking.
- * @param {LayoutValidationContext} [context] - Validation context for cross-cutting concerns like ID uniqueness.
- * @returns {Promise<void>} Resolves when validation completes.
- * @throws {Error} If any block entry is invalid or nesting depth exceeds MAX_LAYOUT_DEPTH.
+ * @param layout - The outlet layout (array of block entries) to validate.
+ * @param outletName - The outlet these blocks belong to.
+ * @param blocksService - Service for validating conditions.
+ * @param parentPath - JSON-path style parent location for error context.
+ * @param callSiteError - Where renderBlocks() was called from.
+ * @param rootLayout - The root layout array for error context display.
+ * @param parentChildArgsSchema - The parent container's childArgs schema, if any.
+ * @param parentBlockName - The parent container's block name for error messages.
+ * @param depth - Current nesting depth for recursion limit checking.
+ * @param context - Validation context for cross-cutting concerns like ID uniqueness.
+ * @throws Error if any block entry is invalid or nesting depth exceeds MAX_LAYOUT_DEPTH.
  */
-export function validateLayout(layout: Array<any>, outletName: string, blocksService: import("discourse/services/blocks").default, parentPath?: string, callSiteError?: Error | null, rootLayout?: Array<any>, parentChildArgsSchema?: any | null, parentBlockName?: string | null, depth?: number, context?: LayoutValidationContext): Promise<void>;
+export declare function validateLayout(layout: LayoutEntry[], outletName: string, blocksService: Blocks | undefined, parentPath?: string, callSiteError?: Error | null, rootLayout?: LayoutEntry[] | null, parentChildArgsSchema?: Record<string, ChildArgSchema> | null, parentBlockName?: string | null, depth?: number, context?: LayoutValidationContext): Promise<void>;
 /**
  * Validates a single block entry object.
  *
  * Performs comprehensive validation including:
  * - Outlet name is a valid registered outlet (core or custom)
- * - Block reference is valid (string name or @block-decorated class)
+ * - Block reference is valid (string name or `@block`-decorated class)
  * - Block is registered in the registry
  * - Container/children relationship is valid
  * - No reserved arg names are used
@@ -110,46 +131,17 @@ export function validateLayout(layout: Array<any>, outletName: string, blocksSer
  * if a block reference is a string pointing to an unresolved factory, full
  * validation is deferred to render time.
  *
- * @param {Object} entry - The block entry object.
- * @param {typeof import("@glimmer/component").default | string} entry.block - Block class or name string.
- * @param {Object} [entry.args] - Args to pass to the block.
- * @param {Object} [entry.containerArgs] - Args required by parent container's childArgs schema.
- * @param {Array<Object>} [entry.children] - Nested block entries.
- * @param {Array<Object>|Object} [entry.conditions] - Conditions for rendering.
- * @param {string} outletName - The outlet this block belongs to.
- * @param {import("discourse/services/blocks").default} blocksService - Service for validating conditions.
- * @param {string} [path] - JSON-path style location in layout (e.g., "[3].children[0]").
- * @param {Error | null} [callSiteError] - Where renderBlocks() was called from.
- * @param {Array<Object>} [rootLayout] - The root layout array for error context display.
- * @param {Object|null} [parentChildArgsSchema=null] - The parent container's childArgs schema, if any.
- * @param {string|null} [parentBlockName=null] - The parent container's block name for error messages.
- * @returns {Promise<Object|null>} The block's childArgsSchema if it's a container with childArgs, otherwise null.
- * @throws {Error} If validation fails.
- */
-export function validateEntry(entry: {
-    block: typeof import("@glimmer/component").default | string;
-    args?: any;
-    containerArgs?: any;
-    children?: Array<any>;
-    conditions?: Array<any> | any;
-}, outletName: string, blocksService: import("discourse/services/blocks").default, path?: string, callSiteError?: Error | null, rootLayout?: Array<any>, parentChildArgsSchema?: any | null, parentBlockName?: string | null): Promise<any | null>;
-/**
- * Valid top-level keys in block entry objects.
- * Any key not in this list will trigger a validation error, helping catch
- * common typos like `condition` instead of `conditions`.
+ * @param entry - The block entry object.
+ * @param outletName - The outlet this block belongs to.
+ * @param blocksService - Service for validating conditions.
+ * @param path - JSON-path style location in layout (e.g., "[3].children[0]").
+ * @param callSiteError - Where renderBlocks() was called from.
+ * @param rootLayout - The root layout array for error context display.
+ * @param parentChildArgsSchema - The parent container's childArgs schema, if any.
+ * @param parentBlockName - The parent container's block name for error messages.
+ * @returns The block's childArgsSchema if it's a container with childArgs, otherwise null.
+ * @throws Error if validation fails.
  */
-export const VALID_ENTRY_KEYS: readonly string[];
-/**
- * Validation context passed through layout validation recursion.
- * Created at the root level and shared across all entries to enable
- * cross-cutting validation (e.g., ID uniqueness across the entire tree).
- */
-export type LayoutValidationContext = {
-    /**
-     * - Map of entry IDs to their paths for uniqueness validation.
-     */
-    seenIds: Map<string, {
-        path: string;
-    }>;
-};
+export declare function validateEntry(entry: LayoutEntry, outletName: string, blocksService: Blocks | undefined, path: string, callSiteError?: Error | null, rootLayout?: LayoutEntry[] | null, parentChildArgsSchema?: Record<string, ChildArgSchema> | null, parentBlockName?: string | null): Promise<Record<string, ChildArgSchema> | null>;
+export {};
 //# sourceMappingURL=layout.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../../../../../../discourse/app/lib/blocks/-internals/validation/layout.js"],"names":[],"mappings":"AA+RA;;;;;;;GAOG;AACH,wDAYC;AAmFD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,oDAXW,MAAM,MAAS,cACf,MAAM,YAEd;IAAyB,IAAI,GAArB,MAAM;IACW,KAAK;IACN,aAAa,GAA7B,KAAK;IACW,UAAU;CAClC,GAAU,OAAO,CAAC,MAAS,MAAM,GAAG;IAA4B,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAkDjF;AA+DD;;;;;;;;;;GAUG;AACH,oDAmBC;AAED;;;;;;GAMG;AACH,qDAYC;AAED;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,uCAbW,KAAK,KAAQ,cACb,MAAM,iBACN,OAAO,2BAA2B,EAAE,OAAO,eAC3C,MAAM,kBACN,KAAK,GAAG,IAAI,eACZ,KAAK,KAAQ,0BACb,MAAO,IAAI,oBACX,MAAM,GAAC,IAAI,UACX,MAAM,YACN,uBAAuB,GACrB,OAAO,CAAC,IAAI,CAAC,CAiIzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qCAfG;IAAoE,KAAK,EAAjE,cAAc,oBAAoB,EAAE,OAAO,GAAG,MAAM;IACrC,IAAI;IACJ,aAAa;IACN,QAAQ,GAA9B,KAAK,KAAQ;IACgB,UAAU,GAAvC,KAAK,KAAQ,MAAO;CAC5B,cAAQ,MAAM,iBACN,OAAO,2BAA2B,EAAE,OAAO,SAC3C,MAAM,kBACN,KAAK,GAAG,IAAI,eACZ,KAAK,KAAQ,0BACb,MAAO,IAAI,oBACX,MAAM,GAAC,IAAI,GACT,OAAO,CAAC,MAAO,IAAI,CAAC,CAmLhC;AAheD;;;;GAIG;AACH,iDAQG;;;;;;;;;;aA2GW,GAAG,CAAC,MAAM,EAAE;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,CAAC"}
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../../../../../../discourse/app/lib/blocks/-internals/validation/layout.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAEV,cAAc,EACd,WAAW,EACZ,MAAM,wBAAwB,CAAC;AAOhC,OAAO,EAEL,gBAAgB,EAGjB,MAAM,0CAA0C,CAAC;AAUlD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uCAAuC,CAAC;AAcxE,OAAO,KAAK,MAAM,MAAM,2BAA2B,CAAC;AAkRpD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAY9D;AAwFD,uDAAuD;AACvD,UAAU,gCAAgC;IACxC,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,KAAK,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3B,0CAA0C;IAC1C,aAAa,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;IAC7B,2CAA2C;IAC3C,UAAU,CAAC,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;CACnC;AAED;;;;;GAKG;AACH,KAAK,4BAA4B,GAAG;IAAE,CAAC,gBAAgB,CAAC,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,yBAAyB,CAC7C,QAAQ,EAAE,MAAM,GAAG,UAAU,EAC7B,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,gCAAqC,GAC7C,OAAO,CACR,UAAU,GAAG,MAAM,GAAG,4BAA4B,GAAG,IAAI,GAAG,SAAS,CACtE,CA0CA;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EAQ5C,CAAC;AAwDH;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAmB1D;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAe3D;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,iEAAiE;IACjE,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACxC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,WAAW,EAAE,EACrB,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,UAAU,SAAK,EACf,aAAa,GAAE,KAAK,GAAG,IAAW,EAClC,UAAU,GAAE,WAAW,EAAE,GAAG,IAAW,EACvC,qBAAqB,GAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,IAAW,EACnE,eAAe,GAAE,MAAM,GAAG,IAAW,EACrC,KAAK,SAAI,EACT,OAAO,GAAE,uBAAgD,GACxD,OAAO,CAAC,IAAI,CAAC,CAkHf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,WAAW,EAClB,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,GAAG,SAAS,EACjC,IAAI,EAAE,MAAM,EACZ,aAAa,GAAE,KAAK,GAAG,IAAW,EAClC,UAAU,GAAE,WAAW,EAAE,GAAG,IAAW,EACvC,qBAAqB,GAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,IAAW,EACnE,eAAe,GAAE,MAAM,GAAG,IAAW,GACpC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,IAAI,CAAC,CA0LhD"}

package/declarations/app/lib/blocks/index.d.ts

@@ -1,7 +1,132 @@
+/**
+ * Public API for the Discourse Block system.
+ *
+ * This module exposes constants and utilities that plugin and theme developers
+ * can use when working with blocks. Internal implementation details are kept
+ * in the `-internals/` directory and should not be imported directly.
+ *
+ * @example
+ * ```javascript
+ * import {
+ *   VALID_BLOCK_NAME_PATTERN,
+ *   parseBlockName,
+ *   VALID_ARG_TYPES,
+ *   matchValue,
+ * } from "discourse/lib/blocks";
+ * ```
+ */
+/**
+ * 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 { VALID_BLOCK_NAME_PATTERN } from "discourse/lib/blocks/-internals/patterns";
+/**
+ * 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`
+ *
+ * @example
+ * ```
+ * // Valid patterns:
+ * "group"                      // Core block
+ * "chat:message-widget"        // Plugin block
+ * "theme:tactile:hero-banner"  // Theme block
+ * ```
+ */
+export { VALID_NAMESPACED_BLOCK_PATTERN } from "discourse/lib/blocks/-internals/patterns";
+/**
+ * Parses a full block name into its components.
+ *
+ * @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: "tactile", name: "hero-banner" }
+ * ```
+ */
+export { parseBlockName } from "discourse/lib/blocks/-internals/patterns";
+/**
+ * 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.
+ *
+ * @example
+ * ```
+ * parseBlockReference("chat:widget?")
+ * // => { name: "chat:widget", optional: true }
+ *
+ * parseBlockReference("hero-banner")
+ * // => { name: "hero-banner", optional: false }
+ * ```
+ */
+export { parseBlockReference } from "discourse/lib/blocks/-internals/patterns";
+/**
+ * Valid arg types for schema definitions.
+ * Types: "string", "number", "boolean", "array", "any"
+ */
+export { VALID_ARG_TYPES } from "discourse/lib/blocks/-internals/validation/args";
+/**
+ * Valid item types for array args.
+ * Types: "string", "number", "boolean"
+ */
+export { VALID_ITEM_TYPES } from "discourse/lib/blocks/-internals/validation/args";
+/**
+ * Valid constraint types for cross-arg validation.
+ * Types: "atLeastOne", "exactlyOne", "allOrNone", "atMostOne", "requires"
+ */
 export { VALID_CONSTRAINT_TYPES } from "discourse/lib/blocks/-internals/validation/constraints";
+/**
+ * Array of all valid page type names for the route condition.
+ * Types: "CATEGORY_PAGES", "TAG_PAGES", "DISCOVERY_PAGES", "HOMEPAGE",
+ *        "TOP_MENU", "TOPIC_PAGES", "USER_PAGES", "ADMIN_PAGES", "GROUP_PAGES"
+ */
 export { VALID_PAGE_TYPES } from "discourse/lib/blocks/-internals/matching/page-definitions";
+/**
+ * Retrieves a value from a nested object using dot-notation path.
+ *
+ * This utility safely navigates through nested object properties using a
+ * dot-separated path string. It handles null/undefined values gracefully
+ * at any level of the path.
+ *
+ * @example
+ * ```
+ * const user = { profile: { name: "Alice", settings: { theme: "dark" } } };
+ * getByPath(user, "profile.name"); // "Alice"
+ * getByPath(user, "profile.settings.theme"); // "dark"
+ * getByPath(user, "profile.missing"); // undefined
+ * ```
+ */
 export { getByPath } from "discourse/lib/blocks/-internals/utils";
+/**
+ * Evaluates a value matcher spec against an actual value.
+ * Supports the same AND/OR/NOT logic as condition evaluation.
+ *
+ * Supports:
+ * - Exact match: `123`, `"foo"`
+ * - Array of simple values (OR): `[123, 456]` matches if actual is any of these
+ * - Array of complex specs (AND): `[{ not: "a" }, { not: "b" }]` all specs must match
+ * - RegExp: `/^foo/` matches if actual matches the pattern
+ * - NOT: `{ not: value }` matches if actual does NOT match value
+ * - ANY (OR): `{ any: [...] }` matches if actual matches any spec in array
+ *
+ * @example
+ * ```
+ * matchValue({ actual: 5, expected: 5 }) // true
+ * matchValue({ actual: 5, expected: [3, 5, 7] }) // true (OR)
+ * matchValue({ actual: "hello", expected: /^hel/ }) // true
+ * matchValue({ actual: 5, expected: { not: 3 } }) // true
+ * ```
+ */
 export { matchValue } from "discourse/lib/blocks/-internals/matching/value-matcher";
-export { VALID_BLOCK_NAME_PATTERN, VALID_NAMESPACED_BLOCK_PATTERN, parseBlockName, parseBlockReference } from "discourse/lib/blocks/-internals/patterns";
-export { VALID_ARG_TYPES, VALID_ITEM_TYPES } from "discourse/lib/blocks/-internals/validation/args";
 //# sourceMappingURL=index.d.ts.map

package/declarations/app/lib/blocks/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../discourse/app/lib/blocks/index.js"],"names":[],"mappings":""}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../discourse/app/lib/blocks/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH;;;;;GAKG;AACH,OAAO,EAAE,wBAAwB,EAAE,MAAM,0CAA0C,CAAC;AAEpF;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,8BAA8B,EAAE,MAAM,0CAA0C,CAAC;AAE1F;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,0CAA0C,CAAC;AAE1E;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,0CAA0C,CAAC;AAI/E;;;GAGG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,iDAAiD,CAAC;AAElF;;;GAGG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,iDAAiD,CAAC;AAInF;;;GAGG;AACH,OAAO,EAAE,sBAAsB,EAAE,MAAM,wDAAwD,CAAC;AAIhG;;;;GAIG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,2DAA2D,CAAC;AAI7F;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,uCAAuC,CAAC;AAElE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,wDAAwD,CAAC"}

package/declarations/app/lib/codeblock-buttons.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codeblock-buttons.d.ts","sourceRoot":"","sources":["../../../../discourse/app/lib/codeblock-buttons.js"],"names":[],"mappings":"AAgCA;IAGE,uBAeC;IAdC,kCAAuC;IACvC,+BAAoC;IAWpC,oBAAyC;IACzC,cAA6B;IAG/B,gDASC;IAED,oCAUC;IAED,gBAYC;IAED,wDAWC;IAED,kCAIC;IAED,sCAgCC;IAED,mCAEC;IAED,+BA2CC;IAED,iCAiBC;;CACF"}
+{"version":3,"file":"codeblock-buttons.d.ts","sourceRoot":"","sources":["../../../../discourse/app/lib/codeblock-buttons.js"],"names":[],"mappings":"AAgCA;IAGE,uBAeC;IAdC,kCAAuC;IACvC,+BAAoC;IAWpC,oBAAyC;IACzC,cAA6B;IAG/B,gDASC;IAED,oCAUC;IAED,gBAYC;IAED,wDAWC;IAED,kCAIC;IAED,sCA0CC;IAED,mCAEC;IAED,+BA2CC;IAED,iCAiBC;;CACF"}

package/declarations/app/lib/composer/actions-registry.d.ts

@@ -0,0 +1,4 @@
+export function registerComposerAction(opts: any): void;
+export function registeredComposerActions(): any[];
+export function _clearRegisteredActions(): void;
+//# sourceMappingURL=actions-registry.d.ts.map

package/declarations/app/lib/composer/actions-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions-registry.d.ts","sourceRoot":"","sources":["../../../../../discourse/app/lib/composer/actions-registry.js"],"names":[],"mappings":"AAEA,wDAEC;AAED,mDAEC;AAED,gDAEC"}

package/declarations/app/lib/composer/composer-position.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"composer-position.d.ts","sourceRoot":"","sources":["../../../../../discourse/app/lib/composer/composer-position.js"],"names":[],"mappings":"AAIA;;eA4IC"}
+{"version":3,"file":"composer-position.d.ts","sourceRoot":"","sources":["../../../../../discourse/app/lib/composer/composer-position.js"],"names":[],"mappings":"AAIA;;eAiJC"}

package/declarations/app/lib/composer/preview-block.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Builds the source of a preview block, trimmed of the padding cooked markup
+ * puts around it.
+ *
+ * @param {import("prosemirror-model").Schema} schema
+ * @param {string} source
+ * @param {string} [params] language the source is highlighted as
+ * @returns {import("prosemirror-model").Node} a `preview_source` node
+ */
+export function previewSourceNode(schema: import("prosemirror-model").Schema, source: string, params?: string): import("prosemirror-model").Node;
+/**
+ * Puts the caret in the source of a preview block a transaction just inserted.
+ *
+ * Fitting the block in can move it past `from`, so the first `preview_source`
+ * at or after it is the one that was just created.
+ *
+ * @param {import("prosemirror-state").Transaction} tr
+ * @param {typeof import("prosemirror-state").TextSelection} TextSelection
+ * @param {number} from position the block was written to
+ * @returns {import("prosemirror-state").Transaction} the same transaction
+ */
+export function selectPreviewSource(tr: import("prosemirror-state").Transaction, TextSelection: typeof import("prosemirror-state").TextSelection, from: number): import("prosemirror-state").Transaction;
+//# sourceMappingURL=preview-block.d.ts.map

package/declarations/app/lib/composer/preview-block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-block.d.ts","sourceRoot":"","sources":["../../../../../discourse/app/lib/composer/preview-block.js"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,0CALW,OAAO,mBAAmB,EAAE,MAAM,UAClC,MAAM,WACN,MAAM,GACJ,OAAO,mBAAmB,EAAE,IAAI,CAS5C;AAED;;;;;;;;;;GAUG;AACH,wCALW,OAAO,mBAAmB,EAAE,WAAW,iBACvC,cAAc,mBAAmB,EAAE,aAAa,QAChD,MAAM,GACJ,OAAO,mBAAmB,EAAE,WAAW,CAmBnD"}