@mohasinac/appkit 4.70.0 → 4.71.2

package/dist/ui/widgets/index.d.ts

@@ -0,0 +1,7 @@
+export type { ResolvedWidget, WidgetBlockReason, WidgetConfigProblem, WidgetContentTag, WidgetDef, WidgetInstance, WidgetRegionDef, WidgetResolveContext, WidgetTier, WidgetTreeResult, } from "./types";
+export { partitionRequiredRules, resolveWidgetTree } from "./resolve";
+export { findInstanceByRef, findRefCollisions, instanceRefs, mergeStoredWithDefaults, mergedInstances, } from "./merge";
+export type { MergedWidgetInstance, WidgetInstanceOrigin } from "./merge";
+export type { ReachabilityRule, RequiredRulePartition } from "./resolve";
+export { PILOT_REGIONS, PILOT_WIDGET_DEFS, RELATED_DEFAULT_INSTANCES, RELATED_SOURCES, asRelatedScrollerConfig, resolveScrollerTitle, } from "./pilot-registry";
+export type { RelatedScrollerConfig, RelatedSource } from "./pilot-registry";

package/dist/ui/widgets/index.js

@@ -0,0 +1,3 @@
+export { partitionRequiredRules, resolveWidgetTree } from "./resolve.js";
+export { findInstanceByRef, findRefCollisions, instanceRefs, mergeStoredWithDefaults, mergedInstances, } from "./merge.js";
+export { PILOT_REGIONS, PILOT_WIDGET_DEFS, RELATED_DEFAULT_INSTANCES, RELATED_SOURCES, asRelatedScrollerConfig, resolveScrollerTitle, } from "./pilot-registry.js";

package/dist/ui/widgets/merge.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Template defaults ⊕ stored overrides, and alias-aware lookup.
+ *
+ * Pure. No React, no I/O — the storage layer
+ * (`_internal/server/features/widgets/widget-instances.ts`) answers "what is
+ * stored"; this answers "what does that MEAN against the template", which is
+ * the part worth asserting.
+ *
+ * ---------------------------------------------------------------------------
+ * THE RESOLUTION ORDER
+ * ---------------------------------------------------------------------------
+ *
+ *   1. start from the registry's template defaults for the region
+ *   2. a stored row with the SAME id OVERRIDES that default, field by field
+ *   3. a stored row with a NEW id is APPENDED (an added widget)
+ *   4. a stored row may not resurrect a default that was removed from code —
+ *      see `DEFAULT_REMOVED` below
+ *
+ * 🛑 Step 2 is a FIELD-WISE merge, not a replacement. A stored row that only
+ * says `{ id, state: "off" }` must not wipe the default's `config` — that is
+ * the same whole-map-replace failure `HomepageSectionsRepository` already had
+ * to patch around, where "every config key a caller omitted was silently
+ * deleted" behind an HTTP 200. Storing a partial override is the NORMAL case
+ * here (switching one rail off is one field), so getting this wrong would be
+ * the common path, not an edge case.
+ */
+import type { WidgetInstance } from "./types";
+/**
+ * How a resolved row came to be. Useful to an editor ("this one is customised")
+ * and to the drift tracking A16 asks for, and it costs nothing to return.
+ */
+export type WidgetInstanceOrigin = "default" | "overridden" | "added";
+export interface MergedWidgetInstance {
+    instance: WidgetInstance;
+    origin: WidgetInstanceOrigin;
+}
+/**
+ * Merge stored rows onto the template defaults for ONE region.
+ *
+ * Both inputs are treated as read-only; nothing is mutated, because callers
+ * hold the registry's `readonly` default array and mutating it would leak
+ * one request's config into the next (the module-level array is shared for
+ * the process lifetime).
+ */
+export declare function mergeStoredWithDefaults(defaults: readonly WidgetInstance[], stored: readonly WidgetInstance[]): MergedWidgetInstance[];
+/** Just the instances, for handing straight to `resolveWidgetTree`. */
+export declare function mergedInstances(defaults: readonly WidgetInstance[], stored: readonly WidgetInstance[]): WidgetInstance[];
+/**
+ * Find an instance by its id OR by any legacy key it answers to.
+ *
+ * 🛑 THIS IS THE WHOLE POINT OF `aliases`, and it exists because of a real,
+ * live failure mode. `src/constants/navigation.tsx` derives a nav item's `id`
+ * from its `href` at module scope, and that derived id is the live key for
+ * `siteSettings.navConfig` and for the attention-count registry. Change the
+ * href and the re-derived key matches nothing: every badge silently vanishes
+ * while the route still returns 200. The same file records the sibling
+ * failure, two surfaces deriving two spellings (`nav-brands` vs
+ * `nav-public-brands`) with each believing it had saved.
+ *
+ * So: a widget instance's identity is MINTED AND STORED, and any derived key
+ * it used to be known by is recorded ONCE in `aliases` and never re-derived.
+ * This function is the only place that knows those legacy keys existed.
+ *
+ * Exact id wins over an alias, always — an alias must never shadow a real
+ * instance, or a newly minted id colliding with somebody's old derived key
+ * would resolve to the wrong widget.
+ */
+export declare function findInstanceByRef(instances: readonly WidgetInstance[], ref: string): WidgetInstance | undefined;
+/**
+ * Every key an instance answers to — its id plus its aliases.
+ *
+ * For a migration or an audit that needs to prove no legacy key was dropped:
+ * diff this against the keys actually present in `siteSettings.navConfig`
+ * before switching a surface over.
+ */
+export declare function instanceRefs(instance: WidgetInstance): string[];
+/**
+ * Detect two instances claiming the same ref — which would make
+ * `findInstanceByRef` return an arbitrary one of them.
+ *
+ * Returns the colliding refs, empty when clean. An alias collision is exactly
+ * the `nav-brands`/`nav-public-brands` defect in its new home, so it is worth
+ * a cheap explicit check rather than trusting that nobody does it.
+ */
+export declare function findRefCollisions(instances: readonly WidgetInstance[]): string[];

package/dist/ui/widgets/merge.js

@@ -0,0 +1,162 @@
+/**
+ * Template defaults ⊕ stored overrides, and alias-aware lookup.
+ *
+ * Pure. No React, no I/O — the storage layer
+ * (`_internal/server/features/widgets/widget-instances.ts`) answers "what is
+ * stored"; this answers "what does that MEAN against the template", which is
+ * the part worth asserting.
+ *
+ * ---------------------------------------------------------------------------
+ * THE RESOLUTION ORDER
+ * ---------------------------------------------------------------------------
+ *
+ *   1. start from the registry's template defaults for the region
+ *   2. a stored row with the SAME id OVERRIDES that default, field by field
+ *   3. a stored row with a NEW id is APPENDED (an added widget)
+ *   4. a stored row may not resurrect a default that was removed from code —
+ *      see `DEFAULT_REMOVED` below
+ *
+ * 🛑 Step 2 is a FIELD-WISE merge, not a replacement. A stored row that only
+ * says `{ id, state: "off" }` must not wipe the default's `config` — that is
+ * the same whole-map-replace failure `HomepageSectionsRepository` already had
+ * to patch around, where "every config key a caller omitted was silently
+ * deleted" behind an HTTP 200. Storing a partial override is the NORMAL case
+ * here (switching one rail off is one field), so getting this wrong would be
+ * the common path, not an edge case.
+ */
+/**
+ * Merge stored rows onto the template defaults for ONE region.
+ *
+ * Both inputs are treated as read-only; nothing is mutated, because callers
+ * hold the registry's `readonly` default array and mutating it would leak
+ * one request's config into the next (the module-level array is shared for
+ * the process lifetime).
+ */
+export function mergeStoredWithDefaults(defaults, stored) {
+    const storedById = new Map(stored.map((s) => [s.id, s]));
+    const out = [];
+    for (const def of defaults) {
+        const override = storedById.get(def.id);
+        if (!override) {
+            out.push({ instance: def, origin: "default" });
+            continue;
+        }
+        storedById.delete(def.id);
+        out.push({ instance: applyOverride(def, override), origin: "overridden" });
+    }
+    // Anything left is a widget somebody ADDED that the template does not know.
+    for (const added of storedById.values()) {
+        out.push({ instance: added, origin: "added" });
+    }
+    out.sort((a, b) => a.instance.order - b.instance.order);
+    return out;
+}
+/**
+ * Field-wise override. A key absent from the stored row keeps the template's
+ * value; a key present replaces it.
+ *
+ * 🛑 `state` is the one key where "absent" is a THIRD value, not a missing
+ * one: absent means "inherit the definition default". So an override that
+ * omits `state` must leave the default's `state` alone, and an override that
+ * sets it must win — which is what `"state" in override` tests. A truthiness
+ * check here would make `state: "off"`… fine, but would silently ignore a
+ * deliberate clear-back-to-inherit.
+ */
+function applyOverride(base, override) {
+    const merged = { ...base };
+    if (override.regionId)
+        merged.regionId = override.regionId;
+    if ("parentId" in override)
+        merged.parentId = override.parentId;
+    if (typeof override.order === "number")
+        merged.order = override.order;
+    if (override.span)
+        merged.span = override.span;
+    if ("state" in override)
+        merged.state = override.state;
+    /*
+     * `config` is merged one level deep, for the same reason step 2 exists: a
+     * stored `{ titleTemplate }` must not erase the default's `source` and
+     * `fallbackTitle`. One level is deliberate and sufficient — a widget config
+     * is a flat bag of scalars by convention (see `RelatedScrollerConfig`), and
+     * a deep merge would make "clear this key" inexpressible.
+     */
+    if (override.config)
+        merged.config = { ...(base.config ?? {}), ...override.config };
+    if (override.contentTags)
+        merged.contentTags = override.contentTags;
+    if (override.templateId)
+        merged.templateId = override.templateId;
+    if (typeof override.templateVersion === "number")
+        merged.templateVersion = override.templateVersion;
+    if (override.templateSlot)
+        merged.templateSlot = override.templateSlot;
+    if (override.aliases)
+        merged.aliases = override.aliases;
+    // The TYPE is never overridable. Changing a type changes which config shape
+    // is valid, so it is a delete + create, not an edit — otherwise a stored
+    // row could point a `card.product` default at a `section.offerBoard`
+    // definition and keep the old config bag.
+    merged.type = base.type;
+    return merged;
+}
+/** Just the instances, for handing straight to `resolveWidgetTree`. */
+export function mergedInstances(defaults, stored) {
+    return mergeStoredWithDefaults(defaults, stored).map((m) => m.instance);
+}
+// ---------------------------------------------------------------------------
+// Alias-aware lookup — the nav-trap defence
+// ---------------------------------------------------------------------------
+/**
+ * Find an instance by its id OR by any legacy key it answers to.
+ *
+ * 🛑 THIS IS THE WHOLE POINT OF `aliases`, and it exists because of a real,
+ * live failure mode. `src/constants/navigation.tsx` derives a nav item's `id`
+ * from its `href` at module scope, and that derived id is the live key for
+ * `siteSettings.navConfig` and for the attention-count registry. Change the
+ * href and the re-derived key matches nothing: every badge silently vanishes
+ * while the route still returns 200. The same file records the sibling
+ * failure, two surfaces deriving two spellings (`nav-brands` vs
+ * `nav-public-brands`) with each believing it had saved.
+ *
+ * So: a widget instance's identity is MINTED AND STORED, and any derived key
+ * it used to be known by is recorded ONCE in `aliases` and never re-derived.
+ * This function is the only place that knows those legacy keys existed.
+ *
+ * Exact id wins over an alias, always — an alias must never shadow a real
+ * instance, or a newly minted id colliding with somebody's old derived key
+ * would resolve to the wrong widget.
+ */
+export function findInstanceByRef(instances, ref) {
+    const exact = instances.find((i) => i.id === ref);
+    if (exact)
+        return exact;
+    return instances.find((i) => i.aliases?.includes(ref));
+}
+/**
+ * Every key an instance answers to — its id plus its aliases.
+ *
+ * For a migration or an audit that needs to prove no legacy key was dropped:
+ * diff this against the keys actually present in `siteSettings.navConfig`
+ * before switching a surface over.
+ */
+export function instanceRefs(instance) {
+    return [instance.id, ...(instance.aliases ?? [])];
+}
+/**
+ * Detect two instances claiming the same ref — which would make
+ * `findInstanceByRef` return an arbitrary one of them.
+ *
+ * Returns the colliding refs, empty when clean. An alias collision is exactly
+ * the `nav-brands`/`nav-public-brands` defect in its new home, so it is worth
+ * a cheap explicit check rather than trusting that nobody does it.
+ */
+export function findRefCollisions(instances) {
+    const seen = new Map();
+    for (const inst of instances) {
+        for (const ref of instanceRefs(inst)) {
+            seen.set(ref, (seen.get(ref) ?? 0) + 1);
+        }
+    }
+    return [...seen.entries()].filter(([, n]) => n > 1).map(([ref]) => ref);
+}

package/dist/ui/widgets/pilot-registry.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The pilot widget registry — one real region, proved end to end.
+ *
+ * ---------------------------------------------------------------------------
+ * WHY THIS REGION AND NOT A SYNTHETIC ONE
+ * ---------------------------------------------------------------------------
+ *
+ * `appkit/src/features/products/components/RelatedItemsSection.tsx` is 55
+ * lines and is the owner's own example, four times over, hardcoded:
+ *
+ *   {relatedItems.length   > 0 && <RelatedProductsCarousel items={relatedItems}   title={`More in ${categoryLabel}`} />}
+ *   {relatedByBrand.length > 0 && <RelatedProductsCarousel items={relatedByBrand} title={`More by ${brandLabel}`} />}
+ *   {relatedByTags.length  > 0 && <RelatedProductsCarousel items={relatedByTags}  title="You might also like" />}
+ *   {relatedByStore.length > 0 && <RelatedProductsCarousel items={relatedByStore} title={`More from ${storeLabel}`} />}
+ *
+ * Owner: *"similarly for horizontal scrollers, related items, recommendations,
+ * sellers other items can be a widget with cards where a widget inside
+ * another widget"* — all four of those are the four lines above. They differ
+ * ONLY in data source and title, i.e. in config, and are expressed as four
+ * JSX branches with four hardcoded strings. One widget type with four
+ * instances is a strict reduction in code, and it is the first thing in this
+ * tree that is honestly a container widget with card children.
+ *
+ * The region is the PDP's real one: `pageId="products-slug"`, mounted at
+ * `ProductDetailPageView.tsx:1410`. Not invented — chosen because it already
+ * exists, is already admin-composable, and already carries the two real
+ * `FunctionalSlotId` values.
+ *
+ * ---------------------------------------------------------------------------
+ * HOW THE REQUIRED-FIELD HALF IS PROVED ON THE SAME REGION
+ * ---------------------------------------------------------------------------
+ *
+ * The PDP's offer board is the one widget on this surface that OWNS fields
+ * (`offerAmount`, `offerMessage`), so blocking it is the real instance of the
+ * owner's rule: *"if the user blocks the widgets tag or stuff they become
+ * disabled and not required."* The live-media widget is included because it
+ * owns `video.url`, which Lane G's module classifies **system** tier
+ * (safety — *"buyers must see the actual animal/plant moving before
+ * purchase"*). Blocking that one must NOT silently drop the requirement; it
+ * must be refused. Both branches of the rule therefore sit on one region, and
+ * one assertion run covers both.
+ *
+ * 🛑 This file is DATA, not rendering. Renderers live in a separate `.tsx`
+ * that only the rendering surface imports — see `types.ts`'s header for the
+ * Root Cause #76 reason.
+ */
+import type { WidgetDef, WidgetInstance, WidgetRegionDef } from "./types";
+/** The one real region this pilot covers. `products-slug` is the live `pageId`. */
+export declare const PILOT_REGIONS: readonly WidgetRegionDef[];
+/**
+ * Where a related scroller gets its items. A CLOSED vocabulary, not free text
+ * — the same reasoning `FunctionalSlotId` states for itself: *"the id is the
+ * ONLY thing standing between an admin picking from a short, pre-vetted list
+ * and an admin naming arbitrary code to execute."* Each value maps 1:1 onto a
+ * prop `RelatedItemsSection` already receives.
+ */
+export declare const RELATED_SOURCES: readonly ["category", "brand", "tags", "store"];
+export type RelatedSource = (typeof RELATED_SOURCES)[number];
+/**
+ * `row.horizontalScroller`'s config bag. The four hardcoded JSX branches
+ * become four of these.
+ *
+ * 🛑 `titleTemplate` + `fallbackTitle` rather than one `title`, because the
+ * four branches being replaced do NOT have fixed titles — three of them
+ * interpolate a label that may be absent:
+ *
+ *   title={categoryLabel ? `More in ${categoryLabel}` : "More in this category"}
+ *
+ * Collapsing that to a single `title` would silently change what three of the
+ * four carousels say the moment a product has no category/brand/store label.
+ * The value-validation bar for this slice is "the page renders the same
+ * headings it rendered before", so the config has to express the conditional,
+ * not approximate it.
+ */
+export interface RelatedScrollerConfig {
+    source: RelatedSource;
+    /** `{label}` is substituted with the source's label when one is available. */
+    titleTemplate: string;
+    /** Used verbatim when the source has no label. */
+    fallbackTitle: string;
+    maxItems?: number;
+}
+/** Narrow a stored `config` bag to this widget's shape, tolerating a malformed row. */
+export declare function asRelatedScrollerConfig(config: Record<string, unknown> | undefined): RelatedScrollerConfig | undefined;
+/** Resolve a scroller's heading exactly as the hardcoded branches did. */
+export declare function resolveScrollerTitle(cfg: RelatedScrollerConfig, label: string | undefined): string;
+/**
+ * The DEFAULT instance list for `products-slug:related` — the four hardcoded
+ * carousels in `RelatedItemsSection.tsx`, expressed as data.
+ *
+ * 🛑 This lives in CODE on purpose. It is the TEMPLATE DEFAULT, and §12.4's
+ * second cost control depends on it: a default row costs **zero** config rows
+ * until somebody changes it. Stored rows exist only for divergence, which is
+ * what keeps the ~5,210-key ceiling theoretical rather than a table someone
+ * has to populate.
+ *
+ * 🛑 Ids are hand-written and STABLE FOREVER, never minted per render. They are
+ * the identity an override targets, so a render-time `genCardId()` would make
+ * every override orphan itself on the next paint — the same class of failure
+ * as deriving a nav id from an href. Hand-written is right for a template
+ * default precisely because there is exactly one of it.
+ */
+export declare const RELATED_DEFAULT_INSTANCES: readonly WidgetInstance[];
+export declare const PILOT_WIDGET_DEFS: readonly WidgetDef[];

package/dist/ui/widgets/pilot-registry.js

@@ -0,0 +1,305 @@
+/**
+ * The pilot widget registry — one real region, proved end to end.
+ *
+ * ---------------------------------------------------------------------------
+ * WHY THIS REGION AND NOT A SYNTHETIC ONE
+ * ---------------------------------------------------------------------------
+ *
+ * `appkit/src/features/products/components/RelatedItemsSection.tsx` is 55
+ * lines and is the owner's own example, four times over, hardcoded:
+ *
+ *   {relatedItems.length   > 0 && <RelatedProductsCarousel items={relatedItems}   title={`More in ${categoryLabel}`} />}
+ *   {relatedByBrand.length > 0 && <RelatedProductsCarousel items={relatedByBrand} title={`More by ${brandLabel}`} />}
+ *   {relatedByTags.length  > 0 && <RelatedProductsCarousel items={relatedByTags}  title="You might also like" />}
+ *   {relatedByStore.length > 0 && <RelatedProductsCarousel items={relatedByStore} title={`More from ${storeLabel}`} />}
+ *
+ * Owner: *"similarly for horizontal scrollers, related items, recommendations,
+ * sellers other items can be a widget with cards where a widget inside
+ * another widget"* — all four of those are the four lines above. They differ
+ * ONLY in data source and title, i.e. in config, and are expressed as four
+ * JSX branches with four hardcoded strings. One widget type with four
+ * instances is a strict reduction in code, and it is the first thing in this
+ * tree that is honestly a container widget with card children.
+ *
+ * The region is the PDP's real one: `pageId="products-slug"`, mounted at
+ * `ProductDetailPageView.tsx:1410`. Not invented — chosen because it already
+ * exists, is already admin-composable, and already carries the two real
+ * `FunctionalSlotId` values.
+ *
+ * ---------------------------------------------------------------------------
+ * HOW THE REQUIRED-FIELD HALF IS PROVED ON THE SAME REGION
+ * ---------------------------------------------------------------------------
+ *
+ * The PDP's offer board is the one widget on this surface that OWNS fields
+ * (`offerAmount`, `offerMessage`), so blocking it is the real instance of the
+ * owner's rule: *"if the user blocks the widgets tag or stuff they become
+ * disabled and not required."* The live-media widget is included because it
+ * owns `video.url`, which Lane G's module classifies **system** tier
+ * (safety — *"buyers must see the actual animal/plant moving before
+ * purchase"*). Blocking that one must NOT silently drop the requirement; it
+ * must be refused. Both branches of the rule therefore sit on one region, and
+ * one assertion run covers both.
+ *
+ * 🛑 This file is DATA, not rendering. Renderers live in a separate `.tsx`
+ * that only the rendering surface imports — see `types.ts`'s header for the
+ * Root Cause #76 reason.
+ */
+/** The one real region this pilot covers. `products-slug` is the live `pageId`. */
+export const PILOT_REGIONS = [
+    {
+        id: "products-slug:body",
+        surface: "product",
+        label: "Product detail — body",
+        allowedTypes: ["row.horizontalScroller", "card.product", "section.offerBoard", "section.liveMediaProof"],
+    },
+    /**
+     * The LIVE region this slice actually drives — `RelatedItemsSection`'s four
+     * carousels. Separate from `:body` because they are different holes in the
+     * same template: `:body` is `AdminComposableRegion`'s admin-curated grid
+     * (mounted at `ProductDetailPageView.tsx:1409`), this one is the
+     * `renderRelated` slot a few lines above it.
+     */
+    {
+        id: "products-slug:related",
+        surface: "product",
+        label: "Product detail — related items",
+        allowedTypes: ["row.horizontalScroller"],
+    },
+];
+/**
+ * Where a related scroller gets its items. A CLOSED vocabulary, not free text
+ * — the same reasoning `FunctionalSlotId` states for itself: *"the id is the
+ * ONLY thing standing between an admin picking from a short, pre-vetted list
+ * and an admin naming arbitrary code to execute."* Each value maps 1:1 onto a
+ * prop `RelatedItemsSection` already receives.
+ */
+export const RELATED_SOURCES = ["category", "brand", "tags", "store"];
+/** Narrow a stored `config` bag to this widget's shape, tolerating a malformed row. */
+export function asRelatedScrollerConfig(config) {
+    const source = config?.source;
+    if (typeof source !== "string" || !RELATED_SOURCES.includes(source)) {
+        return undefined;
+    }
+    const titleTemplate = typeof config?.titleTemplate === "string" ? config.titleTemplate : "";
+    const fallbackTitle = typeof config?.fallbackTitle === "string" ? config.fallbackTitle : "";
+    const maxItems = typeof config?.maxItems === "number" ? config.maxItems : undefined;
+    return { source: source, titleTemplate, fallbackTitle, maxItems };
+}
+/** Resolve a scroller's heading exactly as the hardcoded branches did. */
+export function resolveScrollerTitle(cfg, label) {
+    if (label && cfg.titleTemplate.includes("{label}")) {
+        return cfg.titleTemplate.replace("{label}", label);
+    }
+    if (label && cfg.titleTemplate)
+        return cfg.titleTemplate;
+    return cfg.fallbackTitle || cfg.titleTemplate;
+}
+/**
+ * The DEFAULT instance list for `products-slug:related` — the four hardcoded
+ * carousels in `RelatedItemsSection.tsx`, expressed as data.
+ *
+ * 🛑 This lives in CODE on purpose. It is the TEMPLATE DEFAULT, and §12.4's
+ * second cost control depends on it: a default row costs **zero** config rows
+ * until somebody changes it. Stored rows exist only for divergence, which is
+ * what keeps the ~5,210-key ceiling theoretical rather than a table someone
+ * has to populate.
+ *
+ * 🛑 Ids are hand-written and STABLE FOREVER, never minted per render. They are
+ * the identity an override targets, so a render-time `genCardId()` would make
+ * every override orphan itself on the next paint — the same class of failure
+ * as deriving a nav id from an href. Hand-written is right for a template
+ * default precisely because there is exactly one of it.
+ */
+export const RELATED_DEFAULT_INSTANCES = [
+    {
+        id: "w-related-category",
+        type: "row.horizontalScroller",
+        regionId: "products-slug:related",
+        parentId: null,
+        order: 0,
+        config: { source: "category", titleTemplate: "More in {label}", fallbackTitle: "More in this category" },
+    },
+    {
+        id: "w-related-brand",
+        type: "row.horizontalScroller",
+        regionId: "products-slug:related",
+        parentId: null,
+        order: 1,
+        config: { source: "brand", titleTemplate: "More by {label}", fallbackTitle: "More by this brand" },
+    },
+    {
+        /*
+         * The owner's "recommendations". Its title never interpolated a label in
+         * the original, so template and fallback are identical — the shape still
+         * carries both so ONE config type covers all four.
+         */
+        id: "w-related-tags",
+        type: "row.horizontalScroller",
+        regionId: "products-slug:related",
+        parentId: null,
+        order: 2,
+        config: { source: "tags", titleTemplate: "You might also like", fallbackTitle: "You might also like" },
+    },
+    {
+        /** The owner's "sellers other items". */
+        id: "w-related-store",
+        type: "row.horizontalScroller",
+        regionId: "products-slug:related",
+        parentId: null,
+        order: 3,
+        config: { source: "store", titleTemplate: "More from {label}", fallbackTitle: "More from this seller" },
+    },
+];
+export const PILOT_WIDGET_DEFS = [
+    /*
+     * T2 — the container. `childTypes: ["card.product"]` is what makes "a
+     * widget inside another widget" a declared capability rather than an
+     * accident, and what caps nesting depth without a runtime guard.
+     */
+    {
+        type: "row.horizontalScroller",
+        tier: "section",
+        label: "Related items scroller",
+        surfaces: ["product", "category", "store"],
+        childTypes: ["card.product"],
+    },
+    /*
+     * T3 — the card. 🛑 A CONTAINER, not a leaf, as of the owner's granularity
+     * ruling (2026-11-08): *"`price` on a product card is a WIDGET, not a
+     * field."* So a card holds element widgets, and the containment tree the
+     * mock's Composition page draws is now the real one:
+     *
+     *   region > row.horizontalScroller > card.product > element.price
+     *
+     * This was `childTypes: []` in the first draft and the change is structural,
+     * not a config tweak — the resolver's leaf-nesting refusal, its cycle guard
+     * cost and five assertions all moved with it.
+     *
+     * 🛑 Registry keys are `category.type`, deliberately matching the key
+     * convention the concurrent mock-UI session already settled on
+     * (`mocks/01-widgets.qm`, page "Catalogue": *"Registry key = category.type"*
+     * — `card.product`, `row.horizontalScroller`, `section.clearanceStrip`,
+     * `form.section`). Adopted rather than invented: two spellings for one
+     * registry is precisely the defect that produced `nav-brands` vs
+     * `nav-public-brands` and three incompatible `HomepageSectionType`
+     * vocabularies. The `category.` prefix also carries real information — it
+     * is the tier, readable without a registry lookup.
+     */
+    {
+        type: "card.product",
+        tier: "section",
+        label: "Product card",
+        surfaces: ["product", "category", "store", "homepage"],
+        childTypes: [
+            "element.image",
+            "element.title",
+            "element.price",
+            "element.condition",
+            "element.badge",
+            "element.cta",
+            "element.link",
+        ],
+    },
+    /*
+     * T3 leaf elements — the bottom of the addressable model. Below these are
+     * only T5 atoms (`Div`, `Stack`, `Row`, `Grid`), which stay token-themed and
+     * never get a config key. Measured: 5,210 leaf render sites across 888
+     * components in `appkit/src` vs 4,604 pure-layout sites that do NOT get keys.
+     *
+     * 🛑 `removable: false` on price and condition is A16's guardrail with a
+     * mechanism behind it for the first time: *"Required elements cannot be
+     * removed: price, condition, authenticity claim, the risk banner, consent
+     * affordances … A vendor may restyle them, never hide them."* Before the
+     * owner's ruling this was a required-FIELD rule; now that `price` is a
+     * widget, it has to be a widget capability or it has no enforcement at all.
+     */
+    {
+        type: "element.price",
+        tier: "element",
+        label: "Price",
+        surfaces: ["product", "category", "store", "homepage"],
+        childTypes: [],
+        removable: false,
+        ownsFields: ["price"],
+    },
+    {
+        type: "element.condition",
+        tier: "element",
+        label: "Condition",
+        surfaces: ["product", "category", "store", "homepage"],
+        childTypes: [],
+        removable: false,
+        ownsFields: ["condition"],
+    },
+    {
+        type: "element.title",
+        tier: "element",
+        label: "Title",
+        surfaces: ["product", "category", "store", "homepage"],
+        childTypes: [],
+        ownsFields: ["name"],
+    },
+    {
+        type: "element.image",
+        tier: "element",
+        label: "Image",
+        surfaces: ["product", "category", "store", "homepage"],
+        childTypes: [],
+        ownsFields: ["images"],
+    },
+    {
+        type: "element.badge",
+        tier: "element",
+        label: "Badge",
+        surfaces: ["product", "category", "store", "homepage"],
+        childTypes: [],
+    },
+    {
+        type: "element.cta",
+        tier: "element",
+        label: "Call to action",
+        surfaces: ["product", "category", "store", "homepage"],
+        childTypes: [],
+    },
+    /** The owner's "down to a single link". A leaf that carries its own `href` + `label` in config. */
+    {
+        type: "element.link",
+        tier: "element",
+        label: "Link",
+        surfaces: ["product", "category", "store", "homepage"],
+        childTypes: [],
+    },
+    /*
+     * T2 — owns CONFIG-tier fields. Blocking it must make `offerAmount` /
+     * `offerMessage` disabled AND NOT REQUIRED.
+     *
+     * `requiredPermission` rather than a role check: a permission is a grant,
+     * and a role is a named bundle of them. The owner's own case — *"if I give
+     * a user permission for viewing sellers' lists, that can happen"* — is only
+     * possible this way.
+     */
+    {
+        type: "section.offerBoard",
+        tier: "section",
+        label: "Offer board",
+        surfaces: ["product"],
+        childTypes: [],
+        requiredPermission: "offers.view",
+        ownsFields: ["offerAmount", "offerMessage"],
+        governedBy: [{ governs: "listingType", value: "standard" }],
+    },
+    /*
+     * T2 — owns a SYSTEM-tier field (`video.url`). Blocking it must NOT drop
+     * the requirement; the configuration has to be refused instead, because no
+     * default video of an unfilmed animal exists.
+     */
+    {
+        type: "section.liveMediaProof",
+        tier: "section",
+        label: "Live-item media proof",
+        surfaces: ["product"],
+        childTypes: [],
+        ownsFields: ["video.url"],
+        governedBy: [{ governs: "listingType", value: "live" }],
+    },
+];