@discourse/types 2026.1.0-a5a0839 → 2026.3.0-887c5be4

package/declarations/app/blocks/builtin/block-head.d.ts

@@ -0,0 +1,67 @@
+/**
+ * A container block that renders only its first visible child.
+ *
+ * Use this for prioritized conditional rendering where you want fallback logic:
+ * show the first child whose conditions pass, ignore the rest. This is useful
+ * for "if X, else if Y, else Z" patterns.
+ *
+ * ## Debug Visual Overlay Handling
+ *
+ * Unlike most containers that render all their children, the head block
+ * intentionally only renders one child (the first visible one). This means
+ * the block must handle the debug visual overlay ghosts itself.
+ *
+ * The preprocessing phase passes ALL children that passed their conditions,
+ * plus ghost blocks for children that failed conditions. Since we choose to
+ * not display children 2+, we are responsible for:
+ *
+ * 1. Rendering ghosts for children that failed their own conditions
+ *    (already ghost blocks in @children)
+ * 2. Converting children that passed conditions but aren't rendered
+ *    (because another sibling was first) into ghosts with an explanation
+ *
+ * This ensures the debug overlay accurately shows why each child is or
+ * isn't visible.
+ *
+ * The system wrapper provides standard BEM classes:
+ * - `{outletName}__head` - Standard block class
+ *
+ * System args (curried at creation time, not passed from parent):
+ * - `@outletName` - The outlet identifier this block belongs to
+ * - `@outletArgs` - Outlet args available for condition evaluation and access
+ *
+ * @example
+ * ```javascript
+ * api.renderBlocks("category-sidebar-blocks", [
+ *   {
+ *     block: "head",
+ *     children: [
+ *       // Show support panel for support category
+ *       { block: InfoPanel, args: {...}, conditions: [{ type: "route", params: { categorySlug: "support" } }] },
+ *       // Show dev panel for dev categories
+ *       { block: InfoPanel, args: {...}, conditions: [{ type: "route", params: { categorySlug: "dev" } }] },
+ *       // Default fallback (no conditions = always matches)
+ *       { block: InfoPanel, args: {...} },
+ *     ],
+ *   },
+ * ]);
+ * ```
+ */
+export default class HeadBlock extends Component<any> {
+    constructor(owner: import("@ember/-internals/owner").default, args: any);
+    blocks: any;
+    /**
+     * Children that passed their conditions and could be rendered.
+     *
+     * @returns {Array<import("discourse/lib/blocks/-internals/entry-processing").ChildBlockResult>}
+     */
+    get renderableChildren(): Array<import("discourse/lib/blocks/-internals/entry-processing").ChildBlockResult>;
+    /**
+     * The one child we actually render (first that passed conditions).
+     *
+     * @returns {import("discourse/lib/blocks/-internals/entry-processing").ChildBlockResult|undefined}
+     */
+    get firstChild(): import("discourse/lib/blocks/-internals/entry-processing").ChildBlockResult | undefined;
+}
+import Component from "@glimmer/component";
+//# sourceMappingURL=block-head.d.ts.map

package/declarations/app/blocks/builtin/block-head.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-head.d.ts","sourceRoot":"","sources":["../../../../../discourse/app/blocks/builtin/block-head.gjs"],"names":[],"mappings":"AA6HA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH;;IAKE,YAAgB;IAEhB;;;;OAIG;IACH,0BAFa,KAAK,CAAC,OAAO,kDAAkD,EAAE,gBAAgB,CAAC,CAI9F;IAED;;;;OAIG;IACH,kBAFa,OAAO,kDAAkD,EAAE,gBAAgB,GAAC,SAAS,CAIjG;CA4CF;sBA1HqB,oBAAoB"}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../discourse/app/blocks/builtin/index.js"],"names":[],"mappings":""}

package/declarations/app/blocks/conditions/condition.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Base class for all block conditions.
+ *
+ * Subclasses must:
+ * - Use the `@blockCondition` decorator with `type` and `args` schema config
+ * - Implement the `evaluate(args, context)` method
+ * - Optionally provide a `validate` function in the decorator config for custom validation
+ * - Optionally pass `sourceType` to the decorator to enable `source` parameter support
+ *
+ * Condition classes can inject services using `@service` decorator.
+ * The Blocks service sets the owner on condition instances, enabling dependency injection.
+ *
+ * ## Validation Flow
+ *
+ * Validation happens at block registration time in this order:
+ * 1. Unknown args are detected (typo detection with suggestions)
+ * 2. Arg values are validated against the `args` schema (type, min, max, pattern, etc.)
+ * 3. Constraints are validated (atLeastOne, exactlyOne, allOrNone, atMostOne)
+ * 4. Source parameter is validated (based on sourceType)
+ * 5. Custom `validate` function from decorator config is called (if provided)
+ *
+ * ## Source Parameter Support
+ *
+ * Conditions can declare support for the `source` parameter via `static sourceType`:
+ *
+ * - `"none"` (default): `source` parameter is disallowed
+ * - `"outletArgs"`: `source` must be `@outletArgs.propertyPath`; base class resolves it
+ * - `"object"`: `source` is passed directly as an object (e.g., for settings)
+ *
+ * When `sourceType` is `"outletArgs"`, use `resolveSource(args, context)` to get the
+ * resolved value from outlet args.
+ *
+ * @experimental This API is under active development and may change or be removed
+ * in future releases without prior notice. Use with caution in production environments.
+ *
+ * @class BlockCondition
+ *
+ * @example
+ * ```javascript
+ * import { blockCondition, BlockCondition } from "discourse/blocks/conditions";
+ *
+ * @blockCondition({
+ *   type: "my-condition",
+ *   sourceType: "outletArgs",
+ *   args: {
+ *     requiredArg: { type: "string", required: true },
+ *     optionalCount: { type: "number", min: 0, max: 10 },
+ *   },
+ *   validate(args) {
+ *     // Custom validation that can't be expressed in schema
+ *     if (args.requiredArg === "forbidden") {
+ *       return "requiredArg cannot be 'forbidden'";
+ *     }
+ *     return null;
+ *   }
+ * })
+ * export default class BlockMyCondition extends BlockCondition {
+ *   @service myService;
+ *
+ *   evaluate(args, context) {
+ *     // Get value from source (outlet args) or fall back to service
+ *     const value = this.resolveSource(args, context) ?? this.myService.defaultValue;
+ *     return this.myService.someCheck(value, args.requiredArg);
+ *   }
+ * }
+ * ```
+ */
+export class BlockCondition {
+    /**
+     * Unique identifier for this condition type.
+     * Used in condition specs: `{ type: "route", ... }`
+     *
+     * This property is defined by the `@blockCondition` decorator and should not
+     * be set directly. Pass the `type` option to the decorator instead.
+     *
+     * @type {string}
+     */
+    static type: string;
+    /**
+     * Declares how this condition handles the `source` parameter.
+     *
+     * - `"none"` (default): `source` parameter is disallowed
+     * - `"outletArgs"`: `source` must be `@outletArgs.propertyPath`; base class resolves it
+     * - `"object"`: `source` is passed directly as an object (e.g., settings object)
+     *
+     * This property is defined by the `@blockCondition` decorator and should not
+     * be set directly. Pass the `sourceType` option to the decorator instead.
+     *
+     * @type {"none" | "outletArgs" | "object"}
+     */
+    static sourceType: "none" | "outletArgs" | "object";
+    /**
+     * Arg schema definitions for this condition.
+     *
+     * This property is defined by the `@blockCondition` decorator and should not
+     * be overridden directly. The decorator creates a non-configurable getter
+     * that returns a frozen object.
+     *
+     * @type {Object}
+     */
+    static argsSchema: any;
+    /**
+     * Cross-arg constraint definitions for this condition.
+     *
+     * This property is defined by the `@blockCondition` decorator and should not
+     * be overridden directly. The decorator creates a non-configurable getter
+     * that returns a frozen object or undefined.
+     *
+     * @type {Object|undefined}
+     */
+    static constraints: any | undefined;
+    /**
+     * Custom validation function for this condition.
+     *
+     * This property is defined by the `@blockCondition` decorator and should not
+     * be overridden directly. The decorator creates a non-configurable getter
+     * that returns the validate function or undefined.
+     *
+     * @type {Function|undefined}
+     */
+    static validateFn: Function | undefined;
+    /**
+     * Valid argument keys for this condition.
+     *
+     * This property is derived from the `args` schema by the `@blockCondition`
+     * decorator and should not be overridden directly.
+     *
+     * The `source` key is automatically added by the decorator when
+     * `sourceType !== "none"`.
+     *
+     * @type {readonly string[]}
+     */
+    static validArgKeys: readonly string[];
+    /**
+     * Resolves the `source` parameter value based on the condition's `sourceType`.
+     *
+     * - `sourceType: "outletArgs"`: Extracts the property path from `@outletArgs.path.to.value`
+     *   and retrieves the corresponding value from `context.outletArgs`.
+     * - `sourceType: "object"`: Returns the `source` value directly.
+     *
+     * @param {Object} args - The condition arguments containing `source`.
+     * @param {Object} context - Evaluation context containing `outletArgs`.
+     * @param {Object} [context.outletArgs] - The outlet args passed to the block.
+     * @returns {*} The resolved value from outlet args, or undefined if not found.
+     */
+    resolveSource(args: any, context: {
+        outletArgs?: any;
+    }): any;
+    /**
+     * Default source value when `source` parameter is not provided.
+     * Override in subclasses to provide a fallback (e.g., currentUser, siteSettings).
+     *
+     * @type {*}
+     */
+    get defaultSource(): any;
+    /**
+     * Resolves the source value, falling back to defaultSource when not provided.
+     *
+     * @param {Object} args - The condition arguments.
+     * @param {Object} [context] - Evaluation context.
+     * @returns {*} The resolved source or defaultSource.
+     */
+    getSourceValue(args: any, context?: any): any;
+    /**
+     * Evaluates whether the condition passes.
+     * Called at render time to determine if a block should be shown.
+     *
+     * **Note: This method MUST be pure and idempotent.** It may be called
+     * multiple times during a single render cycle (e.g., when debug logging
+     * is enabled), and should not have side effects.
+     *
+     * @param {Object} args - The condition arguments from the layout entry.
+     * @param {Object} [context] - Evaluation context from the blocks service.
+     * @param {boolean} [context.debug] - Whether debug logging is enabled.
+     * @param {Object} [context.outletArgs] - Outlet args for source resolution.
+     * @param {number} [context._depth] - Current nesting depth for logging.
+     * @returns {boolean} True if condition passes, false otherwise.
+     */
+    evaluate(args: any, context?: {
+        debug?: boolean;
+        outletArgs?: any;
+        _depth?: number;
+    }): boolean;
+    /**
+     * Returns the resolved value for debug logging purposes.
+     *
+     * Override this method in subclasses to provide custom resolved values
+     * for conditions that don't use the standard `source` parameter.
+     * For example, the `outletArg` condition uses a `path` parameter
+     * to resolve values from outlet args.
+     *
+     * @param {Object} args - The condition arguments from the layout entry.
+     * @param {Object} [context] - Evaluation context containing outletArgs.
+     * @returns {{ value: *, hasValue: true }|undefined} Object with resolved value,
+     *   or undefined if this condition doesn't resolve values.
+     */
+    getResolvedValueForLogging(args: any, context?: any): {
+        value: any;
+        hasValue: true;
+    } | undefined;
+}
+//# sourceMappingURL=condition.d.ts.map

package/declarations/app/blocks/conditions/condition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"condition.d.ts","sourceRoot":"","sources":["../../../../../discourse/app/blocks/conditions/condition.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH;IACE;;;;;;;;OAQG;IACH,aAFU,MAAM,CAEJ;IAEZ;;;;;;;;;;;OAWG;IACH,mBAFU,MAAM,GAAG,YAAY,GAAG,QAAQ,CAEf;IAE3B;;;;;;;;OAQG;IACH,uBAAkB;IAElB;;;;;;;;OAQG;IACH,oBAFU,MAAO,SAAS,CAEP;IAEnB;;;;;;;;OAQG;IACH,mBAFU,WAAS,SAAS,CAEV;IAElB;;;;;;;;;;OAUG;IACH,qBAFU,SAAS,MAAM,EAAE,CAEP;IAEpB;;;;;;;;;;;OAWG;IACH,kCAHG;QAAyB,UAAU;KACnC,GAAU,GAAC,CAuBb;IAED;;;;;OAKG;IACH,qBAFU,GAAC,CAIV;IAED;;;;;;OAMG;IACH,0CAFa,GAAC,CAMb;IAED;;;;;;;;;;;;;;OAcG;IAEH,8BANG;QAA0B,KAAK,GAAvB,OAAO;QACU,UAAU;QACV,MAAM,GAAvB,MAAM;KACd,GAAU,OAAO,CAKnB;IAED;;;;;;;;;;;;OAYG;IACH,sDAHa;QAAE,KAAK,EAAE,GAAC,CAAC;QAAC,QAAQ,EAAE,IAAI,CAAA;KAAE,GAAC,SAAS,CASlD;CACF"}

package/declarations/app/blocks/conditions/decorator.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Checks if a class was decorated with @blockCondition.
+ * Used by the block registration system to reject non-decorated classes.
+ *
+ * @experimental This API is under active development and may change or be removed
+ * in future releases without prior notice. Use with caution in production environments.
+ *
+ * @param {Function} ConditionClass - The class to check.
+ * @returns {boolean} True if the class was decorated.
+ */
+export function isDecoratedCondition(ConditionClass: Function): boolean;
+/**
+ * Decorator to define a block condition with declarative arg validation.
+ *
+ * The class must extend BlockCondition. The decorator adds static getters
+ * for type, sourceType, argsSchema, constraints, validateFn, and validArgKeys
+ * based on the provided config. Unknown config keys are rejected with helpful suggestions.
+ *
+ * @experimental This API is under active development and may change or be removed
+ * in future releases without prior notice. Use with caution in production environments.
+ *
+ * @param {Object} config - Condition configuration.
+ * @param {string} config.type - Unique condition type identifier.
+ * @param {"none"|"outletArgs"|"object"} [config.sourceType="none"] - How source parameter is handled.
+ * @param {Object} [config.args={}] - Arg schema definitions (type, required, min, max, pattern, etc.).
+ *   Use `{ type: "any" }` to allow any type.
+ * @param {Object} [config.constraints] - Cross-arg constraints (atLeastOne, exactlyOne, allOrNone, atMostOne).
+ * @param {Function} [config.validate] - Custom validation function called at registration time.
+ *   Receives args object, returns error string/array or null.
+ * @throws {Error} If config is invalid or class doesn't extend BlockCondition.
+ *
+ * @example
+ * import { blockCondition, BlockCondition } from "discourse/blocks/conditions";
+ *
+ * @blockCondition({
+ *   type: "user",
+ *   sourceType: "outletArgs",
+ *   args: {
+ *     loggedIn: { type: "boolean" },
+ *     admin: { type: "boolean" },
+ *     minTrustLevel: { type: "number", min: 0, max: 4, integer: true },
+ *     groups: { type: "array", itemType: "string" },
+ *   },
+ *   validate(args) {
+ *     if (args.loggedIn === false && args.admin) {
+ *       return "Cannot use loggedIn: false with admin condition.";
+ *     }
+ *     return null;
+ *   }
+ * })
+ * export default class BlockUserCondition extends BlockCondition {
+ *   @service currentUser;
+ *   evaluate(args, context) { ... }
+ * }
+ *
+ * @example
+ * // With constraints
+ * @blockCondition({
+ *   type: "setting",
+ *   sourceType: "object",
+ *   args: {
+ *     name: { type: "string", required: true },
+ *     enabled: { type: "boolean" },
+ *     equals: { type: "any" },
+ *     includes: { type: "array" },
+ *   },
+ *   constraints: {
+ *     atMostOne: ["enabled", "equals", "includes"],
+ *   },
+ * })
+ */
+export function blockCondition(config: {
+    type: string;
+    sourceType?: "none" | "outletArgs" | "object";
+    args?: any;
+    constraints?: any;
+    validate?: Function;
+}): (TargetClass: any) => any;
+//# sourceMappingURL=decorator.d.ts.map

package/declarations/app/blocks/conditions/decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorator.d.ts","sourceRoot":"","sources":["../../../../../discourse/app/blocks/conditions/decorator.js"],"names":[],"mappings":"AAmCA;;;;;;;;;GASG;AACH,gEAFa,OAAO,CAInB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,uCAjDG;IAAuB,IAAI,EAAnB,MAAM;IACgC,UAAU,GAAhD,MAAM,GAAC,YAAY,GAAC,QAAQ;IACZ,IAAI;IAEJ,WAAW;IACT,QAAQ;CAElC,IA6HyB,gBAAW,SA0BtC"}

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

@@ -0,0 +1,8 @@
+export { BlockCondition } from "./condition";
+export { blockCondition } from "./decorator";
+export { default as BlockOutletArgCondition } from "./outlet-arg";
+export { default as BlockRouteCondition } from "./route";
+export { default as BlockUserCondition } from "./user";
+export { default as BlockSettingCondition } from "./setting";
+export { default as BlockViewportCondition } from "./viewport";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../discourse/app/blocks/conditions/index.js"],"names":[],"mappings":""}

package/declarations/app/blocks/conditions/outlet-arg.d.ts

@@ -0,0 +1,89 @@
+/**
+ * A condition that evaluates based on outlet arg values.
+ *
+ * Checks properties passed via `@outletArgs` on the BlockOutlet. Supports
+ * dot-notation paths for nested properties and flexible value matching.
+ *
+ * @class BlockOutletArgCondition
+ * @extends BlockCondition
+ *
+ * @param {string} path - Dot-notation path to the property (required).
+ *   E.g., `"topic.closed"`, `"user.trust_level"`, `"category.id"`.
+ * @param {*} [value] - Value to match against (see matching rules below).
+ * @param {boolean} [exists] - If true, passes when property exists (not undefined);
+ *   if false, passes when property is undefined.
+ *
+ * ## Value Matching Rules
+ *
+ * Uses the shared `matchValue` utility:
+ *
+ * - **Primitive**: Passes if `actual === value` (strict equality)
+ * - **RegExp**: Passes if `actual` (coerced to string) matches the pattern
+ * - **[...values]**: Passes if `actual` matches ANY element (OR logic)
+ * - **`{ not: value }`**: Passes if `actual` does NOT match `value`
+ * - **`{ any: [...] }`**: Passes if `actual` matches ANY spec in array (OR logic)
+ *
+ * @example
+ * // Check if topic is closed
+ * { type: "outlet-arg", path: "topic.closed", value: true }
+ *
+ * @example
+ * // Check user trust level is 2 or higher
+ * { type: "outlet-arg", path: "user.trust_level", value: [2, 3, 4] }
+ *
+ * @example
+ * // Check category is one of several IDs
+ * { type: "outlet-arg", path: "category.id", value: [1, 2, 3] }
+ *
+ * @example
+ * // Check if topic property exists
+ * { type: "outlet-arg", path: "topic", exists: true }
+ *
+ * @example
+ * // Check topic is NOT closed
+ * { type: "outlet-arg", path: "topic.closed", value: { not: true } }
+ *
+ * @example
+ * // Check category slug matches pattern
+ * { type: "outlet-arg", path: "category.slug", value: /^support/ }
+ *
+ * @example
+ * // Check topic is closed OR archived (using any)
+ * { type: "outlet-arg", path: "topic.closed", value: { any: [true, { not: false }] } }
+ */
+export default class BlockOutletArgCondition extends BlockCondition {
+    /**
+     * Evaluates whether the outlet arg condition passes.
+     *
+     * @param {Object} args - The condition arguments.
+     * @param {Object} [context] - Evaluation context.
+     * @returns {boolean} True if the condition passes.
+     */
+    evaluate(args: any, context?: any): boolean;
+    /**
+     * Returns the resolved value at the path for debug logging.
+     *
+     * @param {Object} args - The condition arguments containing `path`, `value`, `exists`.
+     * @param {Object} [context] - Evaluation context containing outletArgs.
+     * @returns {{
+     *   hasValue: true,
+     *   formatted: {
+     *     path: string,
+     *     actual: *,
+     *     configured: * | { exists: boolean }
+     *   }
+     * }} Object with formatted log data showing path, actual value, and configured expectation.
+     */
+    getResolvedValueForLogging(args: any, context?: any): {
+        hasValue: true;
+        formatted: {
+            path: string;
+            actual: any;
+            configured: any | {
+                exists: boolean;
+            };
+        };
+    };
+}
+import { BlockCondition } from "./condition";
+//# sourceMappingURL=outlet-arg.d.ts.map

package/declarations/app/blocks/conditions/outlet-arg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outlet-arg.d.ts","sourceRoot":"","sources":["../../../../../discourse/app/blocks/conditions/outlet-arg.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH;IAiCE;;;;;;OAMG;IACH,oCAFa,OAAO,CAiBnB;IAED;;;;;;;;;;;;;OAaG;IAEH,sDAVa;QACR,QAAQ,EAAE,IAAI,CAAC;QACf,SAAS,EAAE;YACT,IAAI,EAAE,MAAM,CAAC;YACb,MAAM,EAAE,GAAC,CAAC;YACV,UAAU,EAAE,GAAC,GAAG;gBAAE,MAAM,EAAE,OAAO,CAAA;aAAE,CAAA;SACpC,CAAA;KACF,CAaH;CACF;+BAjJ8B,aAAa"}

package/declarations/app/blocks/conditions/route.d.ts

@@ -0,0 +1,96 @@
+/**
+ * A condition that evaluates based on the current URL path, semantic page types,
+ * route parameters, and query parameters.
+ *
+ * URL patterns use picomatch glob syntax:
+ * - `*` matches a single path segment (no slashes)
+ * - `**` matches zero or more path segments
+ * - `?` matches a single character
+ * - `[abc]` matches any character in the brackets
+ * - `{a,b}` matches any of the comma-separated patterns
+ *
+ * Page types match semantic page contexts without requiring knowledge of URL structure:
+ * - `CATEGORY_PAGES` - any category page (when `discovery.category` is set)
+ * - `TAG_PAGES` - any tag page (when `discovery.tag` is set)
+ * - `DISCOVERY_PAGES` - discovery routes (latest, top, etc.) excluding custom homepage
+ * - `HOMEPAGE` - custom homepage only
+ * - `TOP_MENU` - discovery routes that appear in the top navigation menu
+ * - `TOPIC_PAGES` - individual topic pages
+ * - `USER_PAGES` - user profile pages
+ * - `ADMIN_PAGES` - admin section pages
+ * - `GROUP_PAGES` - group pages
+ *
+ * URL matching automatically handles Discourse subfolder installations by
+ * normalizing URLs before matching. Theme authors don't need to know if
+ * Discourse runs on `/forum` or root - patterns like `/c/**` work everywhere.
+ *
+ * @class BlockRouteCondition
+ * @extends BlockCondition
+ *
+ * @param {string[]} [urls] - URL patterns to match (passes if ANY match).
+ * @param {string[]} [pages] - Page types to match (passes if ANY match).
+ * @param {Object} [params] - Page parameters to match (only valid with `pages`).
+ * @param {Object} [queryParams] - Query parameters to match. Note: queryParams alone
+ *   is not sufficient - the condition requires `urls` or `pages` to match first.
+ *   This creates implicit AND behavior between route and query params.
+ *
+ * @example
+ * // Match category pages using page type
+ * { type: "route", pages: ["CATEGORY_PAGES"] }
+ *
+ * @example
+ * // Match category pages using URL pattern
+ * { type: "route", urls: ["/c/**"] }
+ *
+ * @example
+ * // Match multiple page types (OR logic)
+ * { type: "route", pages: ["CATEGORY_PAGES", "TAG_PAGES"] }
+ *
+ * @example
+ * // Match specific category by ID
+ * { type: "route", pages: ["CATEGORY_PAGES"], params: { categoryId: 5 } }
+ *
+ * @example
+ * // Match with query params
+ * { type: "route", urls: ["/latest"], queryParams: { filter: "solved" } }
+ *
+ * @example
+ * // Exclude pages using NOT combinator
+ * { not: { type: "route", pages: ["ADMIN_PAGES"] } }
+ */
+export default class BlockRouteCondition extends BlockCondition {
+    router: any;
+    discovery: any;
+    /**
+     * Returns the current URL path, normalized for matching.
+     *
+     * Normalization strips the subfolder prefix, query strings, hash fragments,
+     * and trailing slashes. This allows patterns to work consistently regardless
+     * of Discourse's installation configuration.
+     *
+     * @returns {string} The normalized URL path.
+     */
+    get currentPath(): string;
+    /**
+     * Evaluates whether the current route matches the condition.
+     *
+     * Evaluation logic:
+     * - With `urls`: passes if ANY URL pattern matches
+     * - With `pages`: passes if ANY page type matches
+     * - With `params`: additionally requires all params to match (only with `pages`)
+     * - With `queryParams`: additionally requires all query params to match
+     *
+     * **Important:** `queryParams` alone is not sufficient to match. The condition
+     * will only pass if BOTH the route (via `urls` or `pages`) AND the queryParams
+     * match. This is implicit AND behavior. To match only based on query parameters,
+     * use `urls: ["**"]` to match all routes first.
+     *
+     * @param {Object} args - The condition arguments.
+     * @param {Object} [context={}] - Evaluation context (for debugging).
+     * @returns {boolean} True if the condition passes.
+     */
+    evaluate(args: any, context?: any): boolean;
+    #private;
+}
+import { BlockCondition } from "./condition";
+//# sourceMappingURL=route.d.ts.map

package/declarations/app/blocks/conditions/route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../../../../discourse/app/blocks/conditions/route.js"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH;IAgEE,YAAgB;IAChB,eAAmB;IAEnB;;;;;;;;OAQG;IACH,mBAFa,MAAM,CAIlB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,oCAFa,OAAO,CA4InB;;CAkIF;+BA7a8B,aAAa"}

package/declarations/app/blocks/conditions/setting.d.ts

@@ -0,0 +1,88 @@
+/**
+ * A condition that evaluates based on site setting or custom settings object values.
+ *
+ * Supports multiple condition types for different setting formats:
+ * - `enabled` - For boolean settings (truthy/falsy check)
+ * - `equals` - For exact value matching (strings, numbers, enums)
+ * - `includes` - When setting is a single value: check if it matches one of YOUR provided options
+ * - `contains` - When setting is a list: check if it contains YOUR single value
+ * - `containsAny` - When setting is a list: check if it contains ANY of YOUR provided values
+ *
+ * **`includes` vs `contains` - Key Difference:**
+ *
+ * | Condition    | Setting type               | Question answered                        |
+ * |--------------|----------------------------|------------------------------------------|
+ * | `includes`   | Single value (enum/string) | Is the setting value IN my list?         |
+ * | `contains`   | List (pipe-separated)      | Does the setting list CONTAIN my value?  |
+ *
+ * **Theme Settings Support:**
+ * Pass a custom settings object via `source` (e.g., from `import { settings } from "virtual:theme"`)
+ * to check theme-specific settings instead of site settings.
+ *
+ * **Note:** Setting name validation is deferred to evaluate time since it requires
+ * access to the siteSettings service. Unknown settings will cause the condition to
+ * return false rather than throw an error at registration time.
+ *
+ * @class BlockSettingCondition
+ * @extends BlockCondition
+ *
+ * @param {string} name - The setting key to check (required).
+ * @param {Object} [source] - Custom settings object (e.g., theme settings). If not provided, uses siteSettings.
+ * @param {boolean} [enabled] - If true, passes when setting is truthy; if false, passes when falsy.
+ * @param {*} [equals] - Passes when setting exactly equals this value.
+ * @param {Array<*>} [includes] - For single-value settings: passes when setting value is in this array.
+ * @param {string} [contains] - For list settings: passes when the setting list contains this value.
+ * @param {Array<string>} [containsAny] - For list settings: passes when setting list contains ANY of these.
+ *
+ * @example
+ * // Boolean setting check
+ * { type: "setting", name: "enable_badges", enabled: true }
+ *
+ * @example
+ * // Exact value match
+ * { type: "setting", name: "desktop_category_page_style", equals: "categories_and_latest_topics" }
+ *
+ * @example
+ * // Setting is one of several values
+ * { type: "setting", name: "desktop_category_page_style", includes: ["categories_and_latest_topics", "categories_and_top_topics"] }
+ *
+ * @example
+ * // List setting contains value
+ * { type: "setting", name: "top_menu", contains: "hot" }
+ *
+ * @example
+ * // List setting contains any of values
+ * { type: "setting", name: "share_links", containsAny: ["twitter", "facebook"] }
+ *
+ * @example
+ * // Theme setting check (pass settings object from "virtual:theme")
+ * import { settings } from "virtual:theme";
+ * { type: "setting", source: settings, name: "show_sidebar", enabled: true }
+ */
+export default class BlockSettingCondition extends BlockCondition {
+    siteSettings: any;
+    /**
+     * Evaluates whether the setting condition passes.
+     *
+     * @param {Object} args - The condition arguments.
+     * @param {Object} [context] - Evaluation context.
+     * @returns {boolean} True if the condition passes.
+     */
+    evaluate(args: any, context?: any): boolean;
+    /**
+     * Returns the resolved setting value for debug logging.
+     * Includes a warning note with "did you mean" suggestion if the setting doesn't exist.
+     *
+     * @param {Object} args - The condition arguments.
+     * @param {Object} [context] - Evaluation context.
+     * @returns {{ value: *, hasValue: true, note?: string }}
+     */
+    getResolvedValueForLogging(args: any, context?: any): {
+        value: any;
+        hasValue: true;
+        note?: string;
+    };
+    #private;
+}
+import { BlockCondition } from "./condition";
+//# sourceMappingURL=setting.d.ts.map

package/declarations/app/blocks/conditions/setting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setting.d.ts","sourceRoot":"","sources":["../../../../../discourse/app/blocks/conditions/setting.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH;IAmBE,kBAAsB;IAWtB;;;;;;OAMG;IACH,oCAFa,OAAO,CA6CnB;IA6BD;;;;;;;OAOG;IACH,sDAFa;QAAE,KAAK,EAAE,GAAC,CAAC;QAAC,QAAQ,EAAE,IAAI,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAoCvD;;CACF;+BAxN8B,aAAa"}