@astryxdesign/core 0.5.2-canary.c9c8564 → 0.5.2-canary.e03511b

package/src/Typeahead/Typeahead.spec.md

@@ -0,0 +1,250 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:Typeahead
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [theming]
+verified_by:
+  [
+    packages/core/src/Typeahead/Typeahead.test.tsx,
+    packages/core/src/Typeahead/TypeaheadItem.test.tsx,
+    packages/core/src/Field/Field.test.tsx,
+    packages/core/src/Token/Token.test.tsx,
+    packages/core/src/Icon/Icon.test.tsx,
+    scripts/check-knowledge.mjs,
+  ]
+families: [family:overlay-dismissal]
+design_specs: []
+architecture:
+  [architecture:component-theming-surface, architecture:layer-runtime]
+contributing: []
+system_specs: []
+---
+
+# Typeahead component contract
+
+## Intent
+
+Typeahead renders a single-selection search control with an optional standalone
+Field shell and delegates its combobox engine and popup results to BaseTypeahead. This draft records current
+consumer anatomy, target reachability, and the shipped difference between the
+stable result row and its default TypeaheadItem content without changing runtime
+behavior, styling, targets, or public API.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: additive documentation only; runtime, DOM, styling,
+  targets, and public API remain unchanged
+- Controlled/uncontrolled behavior: unchanged
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The painted Input surface and its current `typeahead` target.
+- The Dropdown and Empty state rendered by BaseTypeahead and their current
+  `typeahead-dropdown` and `typeahead-empty-state` targets.
+- Default item content rendered by TypeaheadItem and its current
+  `typeahead-item` target.
+- The stable outer Result row, Result group heading, and Selected result state,
+  which currently have no Typeahead target.
+
+**Does not own / non-goals**
+
+- Standalone field-shell presentation — rendered by Field and themed through
+  Field's current `field` target; omitted when Typeahead is inside InputGroup.
+- The Selected token — rendered by Token and themed through Token's current
+  `token` target.
+- The Clear button — rendered by Field's InputClearButton and themed through
+  Field's current `input-clear-button` target.
+- General Icon presentation for an Icon-rendered start icon.
+- Arbitrary ReactNode start or item content supplied by the caller.
+- A target/state for the outer Result row, Result group heading, or selected-row
+  concept; none exists on current `main`.
+- Shared layer lifecycle, positioning, and dismissal behavior.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props and usage remain documented
+in `Typeahead.doc.mjs`; BaseTypeahead and TypeaheadItem retain their existing
+public component documentation.
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                                                                                                                                                                                                                       | Basis                           | Draft review state                                 |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------- |
+| FR1 | The current standalone presentation contains a Field and painted Input surface; the supported InputGroup path renders the same Input surface without a Field. The surface contains an editable input when unselected or editing, and a Selected token plus collapsed input when selected and not editing. | Current source, docs, and tests | Verified current behavior; no normalization        |
+| FR2 | Input surface, Dropdown, Empty state, and Default item content carry the four current Typeahead targets documented in `Typeahead.doc.mjs`.                                                                                                                                                                | Current source, docs, and tests | Verified current behavior; no target change        |
+| FR3 | Every result, whether default or caller-rendered, sits inside the same stable outer Result row that owns option semantics, highlight, selected styling, pointer interaction, and keyboard indexing.                                                                                                       | Current source and tests        | Verified current behavior; no new behavior decided |
+| FR4 | `typeahead-item` reaches only the standard TypeaheadItem label/supporting-content branch inside a Result row. A custom `renderItem` branch or caller-provided `item.element` does not receive that target, and no branch gives the outer Result row a Typeahead target.                                   | Current source and owner tests  | Verified current asymmetry; no normalization       |
+| FR5 | Result group heading and Selected result state are stable visible concepts but no current Typeahead target reaches them. The selected check uses a generic Icon, which does not expose a Typeahead-specific selected-row selector.                                                                        | Current source                  | Verified factual reachability gaps                 |
+| FR6 | When present, Field, Selected token, Clear button, and Icon-rendered start icon retain their Field, Token, and Icon theming owners; arbitrary ReactNode start and item content stays caller-owned.                                                                                                        | Current composition and owners  | Verified current behavior; no target change        |
+
+### Allowed variation
+
+- Standalone Typeahead renders Field; the supported InputGroup path omits it.
+- The Input surface shows an editable input while empty or editing and a Token
+  while a selected value is not being edited. This shipped asymmetry is recorded,
+  not normalized into a new shared part or target.
+- A Result row may contain standard TypeaheadItem content, custom `renderItem`
+  content, or a caller-provided `item.element`. Only the standard TypeaheadItem
+  label/supporting-content branch carries `typeahead-item`.
+- Results may be ungrouped or grouped. Group wrappers and headings do not gain a
+  target from that variation.
+- Semantic names and icon component types render through Icon. Arbitrary ReactNode
+  start content renders directly and stays caller-owned.
+
+### Representative states
+
+| State                         | Required invariant                                                                                 | Allowed variation                                                       |
+| ----------------------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| Standalone or InputGroup      | Field is present only standalone; Input surface anatomy and targets remain the same in both paths. | InputGroup owns grouped layout and labeling support.                    |
+| Empty or editing              | Editable input remains inside the `typeahead` Input surface.                                       | Query, loading state, and popup visibility may vary.                    |
+| Selected and not editing      | Token owns the selected-value presentation while the input is collapsed.                           | Clear button may be present according to `hasClear` and disabled state. |
+| Results with default renderer | Outer Result row remains untargeted; inner TypeaheadItem carries `typeahead-item`.                 | Item label, icon/avatar, and description may vary.                      |
+| Results with custom renderer  | Outer Result row remains untargeted; custom content receives no `typeahead-item`.                  | Caller owns the inner result content.                                   |
+| Grouped and selected results  | Group heading and selected-row concept remain untargeted by Typeahead.                             | A generic Icon paints the selected check.                               |
+| Empty completed search        | Empty state carries `typeahead-empty-state` inside the Dropdown.                                   | Consumer-supplied empty text may vary.                                  |
+
+### Transformation and precedence order
+
+- No new query, search-result, selection, edit-mode, or styling precedence rule is
+  introduced.
+
+### Performance and resources
+
+- No new performance or resource rule is introduced.
+
+## Accessibility contract
+
+This draft does not change or extend Typeahead's existing field, combobox,
+listbox, option, live-region, focus, or dismissal behavior.
+
+## Design relationships
+
+| Anatomy or state              | Design requirement                                                                                     | Representation authority       | Hierarchy role    | Component contract |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------ | ----------------- | ------------------ |
+| Field                         | Provides the label and optional supporting content outside InputGroup; omitted inside InputGroup.      | Field component                | Supporting        | FR1, FR6           |
+| Input surface                 | Paints the control around the editable input or selected token.                                        | Current source and public docs | Prominent         | FR1, FR2           |
+| Icon-rendered start icon      | Presents a semantic or component icon through Icon.                                                    | Icon component                 | Supporting        | FR6                |
+| Caller-rendered start content | Presents arbitrary caller content directly in the input surface's start slot.                          | Caller-supplied content        | Context-dependent | FR6                |
+| Selected token                | Presents the selected value outside edit mode through Token.                                           | Token component                | Prominent         | FR1, FR6           |
+| Clear button                  | Removes the selected value through the shared field clear action.                                      | Field component                | Supporting        | FR6                |
+| Dropdown                      | Paints the anchored listbox surface containing results or Empty state.                                 | Current source and public docs | Prominent         | FR2                |
+| Empty state                   | Presents the no-results message after a completed empty search.                                        | Current source and public docs | Prominent         | FR2                |
+| Result row                    | Owns option semantics, interaction, highlight, selection styling, and keyboard index for every result. | Current source and tests       | Prominent         | FR3, FR4           |
+| Default item content          | Presents the standard TypeaheadItem label and optional supporting content inside a Result row.         | TypeaheadItem component        | Prominent         | FR2, FR4           |
+| Caller-rendered item content  | Presents custom `renderItem` or `item.element` content inside the stable Result row.                   | Caller-supplied content        | Context-dependent | FR3, FR4, FR6      |
+| Result group heading          | Labels a visible group of Result rows.                                                                 | Current source                 | Supporting        | FR5                |
+| Selected result state         | Presents selected row weight and a trailing check without a Typeahead-specific target or target state. | Current source                 | Supporting        | FR5                |
+
+The current target placement is asymmetric: `typeahead-item` is on default inner
+TypeaheadItem content, while the stable outer Result row owns interaction and state
+for both default and custom content. Group headings and the selected-result concept
+are also untargeted. This record preserves those facts and does not move, add, or
+normalize targets.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Field": {"delegatesTo": {"owner": "component:Field", "target": "field"}},
+  "Input surface": {"target": "typeahead"},
+  "Icon-rendered start icon": {
+    "delegatesTo": {"owner": "component:Icon", "target": "icon"}
+  },
+  "Caller-rendered start content": {
+    "none": {
+      "reason": "intentional: Arbitrary ReactNode content is caller-owned and receives no Typeahead target."
+    }
+  },
+  "Selected token": {
+    "delegatesTo": {"owner": "component:Token", "target": "token"}
+  },
+  "Clear button": {
+    "delegatesTo": {
+      "owner": "component:Field",
+      "target": "input-clear-button"
+    }
+  },
+  "Dropdown": {"target": "typeahead-dropdown"},
+  "Empty state": {"target": "typeahead-empty-state"},
+  "Result row": {
+    "none": {
+      "reason": "reachability-gap: The stable outer option row owns interaction and state but has no current Typeahead target."
+    }
+  },
+  "Default item content": {"target": "typeahead-item"},
+  "Caller-rendered item content": {
+    "none": {
+      "reason": "intentional: Custom renderItem and item.element content is caller-owned and does not receive the standard TypeaheadItem target."
+    }
+  },
+  "Result group heading": {
+    "none": {
+      "reason": "reachability-gap: No current public target reaches the visible result-group heading."
+    }
+  },
+  "Selected result state": {
+    "none": {
+      "reason": "reachability-gap: No current Typeahead target or target state reaches the outer selected row and its selection concept."
+    }
+  }
+}
+```
+
+## Family and system relationships
+
+- `architecture:component-theming-surface` owns anatomy qualification, local
+  target mapping, delegation, and factual `none` dispositions.
+- `architecture:layer-runtime` owns the current Popover host, positioning, native
+  light-dismiss, and visibility reconciliation used by the Dropdown.
+- `family:overlay-dismissal` owns shared Escape and platform-close ordering;
+  Typeahead participates through its composed Popover owner.
+- Field, Token, and Icon retain ownership of their delegated targets and
+  presentation.
+
+## Verification map
+
+| Contract            | Verification                                                                          | Representative states                                              | Mutation or failure expectation                                                             | Audit section             |
+| ------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | ------------------------- |
+| FR1, FR6            | `Typeahead.test.tsx`, owner tests, and Typeahead composition source                   | Standalone/InputGroup, empty, editing, selected, clear, start icon | A documented composed part disappears, gains the wrong owner, or misreports Field presence. | `audit:Typeahead/anatomy` |
+| FR2                 | Source inspection, target inventories, empty-state test, and `TypeaheadItem.test.tsx` | Input, open Dropdown, empty search, default item                   | A current target is missed, invented, or documented on an element that does not carry it.   | `audit:Typeahead/theming` |
+| FR3, FR4, FR5       | BaseTypeahead source and result/group/selection tests                                 | Default/custom result, grouped result, selected row                | The record hides the outer/inner asymmetry or claims reachability that current code lacks.  | `audit:Typeahead/theming` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                         | Canonical anatomy and current target inventory                     | Missing, extra, prefixed, stale, or multiply assigned mappings fail repository validation.  | `audit:Typeahead/theming` |
+
+Existing tests directly assert Empty state and TypeaheadItem target presence,
+selected-value Token behavior, result semantics, selection state, and standalone
+Field content. Source inspection confirms InputGroup's Field omission and, with
+public target inventories, provides the current Input surface and Dropdown target
+evidence. No test is represented here as proof of a target it does not directly
+assert.
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design,
+API, theming, or layer-system decision.
+
+## Open questions
+
+- **OQ1 — Should the stable Result row, Result group heading, or Selected result
+  state gain a public Typeahead target?** (`human-api`) Their current lack of
+  reachability is an audit gap, not settled intent. This draft does not normalize
+  the existing outer-row/default-content asymmetry.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, search algorithms,
+implementation steps, or shared layer and theming rules. It links to their owners.

package/src/hooks/useAdaptivePresentation.ts

@@ -0,0 +1,35 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useAdaptivePresentation.ts
+ * @input Uses the shared SSR-safe media-query hook
+ * @output Resolves popover/bottom-sheet presentation policy
+ * @position Internal overlay policy shared across component families
+ */
+
+import {useMediaQuery} from './useMediaQuery';
+
+export type AdaptivePresentation = 'popover' | 'bottom-sheet' | 'adaptive';
+export type ResolvedAdaptivePresentation = Exclude<
+  AdaptivePresentation,
+  'adaptive'
+>;
+
+// Width keeps desktop-class tablets and large touch displays anchored by
+// default. Pointer capability, rather than `hover: none`, avoids excluding
+// touch browsers that also report hover capability.
+export const COMPACT_TOUCH_PRESENTATION_QUERY =
+  '(max-width: 768px) and (pointer: coarse)';
+
+export function useAdaptivePresentation(
+  presentation: AdaptivePresentation,
+): ResolvedAdaptivePresentation {
+  const isCompactTouch = useMediaQuery(COMPACT_TOUCH_PRESENTATION_QUERY);
+  return presentation === 'adaptive'
+    ? isCompactTouch
+      ? 'bottom-sheet'
+      : 'popover'
+    : presentation;
+}

package/src/hooks/useFocusReturnVisibility.ts

@@ -0,0 +1,45 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useFocusReturnVisibility.ts
+ * @input Uses the shared interaction-modality tracker
+ * @output Preserves returned focus while suppressing pointer-only focus rings
+ * @position Internal focus-return policy for adaptive overlays
+ */
+
+import {useCallback, useEffect, useState} from 'react';
+import {
+  getInteractionModality,
+  trackInteractionModality,
+} from '../utils/interactionModality';
+
+export function useFocusReturnVisibility() {
+  const [isFocusRingSuppressed, setIsFocusRingSuppressed] = useState(false);
+
+  useEffect(() => {
+    trackInteractionModality();
+  }, []);
+
+  const prepareFocusReturn = useCallback(() => {
+    setIsFocusRingSuppressed(getInteractionModality() === 'pointer');
+  }, []);
+
+  const resetFocusReturn = useCallback(() => {
+    setIsFocusRingSuppressed(false);
+  }, []);
+
+  const onFocusReturnTargetFocus = useCallback(() => {
+    if (getInteractionModality() === 'keyboard') {
+      setIsFocusRingSuppressed(false);
+    }
+  }, []);
+
+  return {
+    isFocusRingSuppressed,
+    onFocusReturnTargetFocus,
+    prepareFocusReturn,
+    resetFocusReturn,
+  };
+}

package/src/hooks/useFocusTrap.test.tsx

@@ -193,6 +193,46 @@ describe('useFocusTrap tabbable model (infra-8)', () => {
     expect(screen.getByTestId('first')).toHaveFocus();
   });
 
+  it('moves from a programmatic container focus target into the tabbable cycle', () => {
+    render(
+      <Trap>
+        <button type="button" data-testid="first">
+          First
+        </button>
+        <button type="button" data-testid="last">
+          Last
+        </button>
+      </Trap>,
+    );
+    const trap = screen.getByTestId('trap');
+    trap.tabIndex = -1;
+    trap.focus();
+
+    fireEvent.keyDown(document, {key: 'Tab'});
+
+    expect(screen.getByTestId('first')).toHaveFocus();
+  });
+
+  it('moves backward from a programmatic container focus target to the last tabbable control', () => {
+    render(
+      <Trap>
+        <button type="button" data-testid="first">
+          First
+        </button>
+        <button type="button" data-testid="last">
+          Last
+        </button>
+      </Trap>,
+    );
+    const trap = screen.getByTestId('trap');
+    trap.tabIndex = -1;
+    trap.focus();
+
+    fireEvent.keyDown(document, {key: 'Tab', shiftKey: true});
+
+    expect(screen.getByTestId('last')).toHaveFocus();
+  });
+
   it('keeps a programmatic focus target when the trap has no tabbable controls', () => {
     render(
       <Trap>

package/src/hooks/useFocusTrap.ts

@@ -375,6 +375,19 @@ export function useFocusTrap<T extends HTMLElement = HTMLElement>(
         const first = focusable[0];
         const last = focusable[focusable.length - 1];
 
+        if (document.activeElement === container) {
+          // Programmatic initial focus can sit on the trap container itself
+          // (for example a dialog panel with no content controls). Move into
+          // the tabbable cycle instead of letting Tab escape to the page.
+          event.preventDefault();
+          if (event.shiftKey) {
+            last.focus();
+          } else {
+            first.focus();
+          }
+          return;
+        }
+
         if (event.shiftKey) {
           // Shift+Tab: if on first element, wrap to last
           if (document.activeElement === first) {

package/src/theme/themingTargets.test.ts

@@ -3,8 +3,10 @@
 /* eslint-disable @typescript-eslint/no-require-imports */
 /**
  * @file Guards `theming.targets` against the real `themeProps()` call sites (#3741).
- * @input Component sources (*.tsx/*.ts) and their `{Name}.doc.mjs` files.
- * @output Vitest failures naming each undocumented class / visual prop.
+ * @input Core/Lab component sources (*.tsx/*.ts), their `{Name}.doc.mjs`
+ *   files, and the Lab promotion-candidate manifest.
+ * @output Vitest failures naming each undocumented class / visual prop on the
+ *   stable Core surface or a capability-participating Lab component.
  * @position Sibling of derivedVarRegistry.test.ts, which already validates the
  *   OTHER fields of the same `theming` block (`vars`, `derived`). `targets` was
  *   the one field with no machine check, so it drifted — twice (#3652, #3680).
@@ -22,6 +24,11 @@
  * `visualProps` or `states`. Docs may list MORE than the source passes —
  * components forward props they don't themselves reflect (Timestamp passes
  * `{format}` but documents `type`/`color`/`format`), and that is intentional.
+ *
+ * Lab is capability-based: a component participates when it already declares
+ * `theming.targets` or enters the existing promotion-candidate manifest. Other
+ * Lab components remain free to iterate with runtime hooks that are not yet a
+ * documented public theming promise.
  */
 
 import {describe, it, expect} from 'vitest';
@@ -30,7 +37,23 @@ import {join, relative} from 'node:path';
 import ts from 'typescript';
 import {stableClassName} from '../naming';
 
-const SRC_DIR = join(__dirname, '..');
+const CORE_SRC_DIR = join(__dirname, '..');
+const LAB_SRC_DIR = join(__dirname, '../../../lab/src');
+const LAB_PROMOTION_MANIFEST = join(
+  __dirname,
+  '../../../../internal/lab-readiness/manifest.mjs',
+);
+
+interface LabPromotionCandidate {
+  sourceDir: string;
+}
+
+const {CANDIDATES: labPromotionCandidates} = require(
+  LAB_PROMOTION_MANIFEST,
+) as {CANDIDATES: LabPromotionCandidate[]};
+const LAB_PROMOTION_DIRS = new Set(
+  labPromotionCandidates.map(candidate => candidate.sourceDir),
+);
 
 // ---------------------------------------------------------------------------
 // Source scanning: find themeProps() call sites via the TypeScript AST
@@ -314,6 +337,7 @@ type DocBlock = {theming?: {targets?: DocTarget[]}};
 type ComponentDocModule = {docs?: DocBlock; docsZh?: DocBlock};
 
 interface ComponentInfo {
+  packageName: 'core' | 'lab';
   dir: string;
   sites: ThemeTargetSite[];
   /** The doc blocks that carry theming.targets, by the key they live under. */
@@ -328,7 +352,10 @@ interface ComponentInfo {
  * Reads the file as text rather than requiring it: this runs for directories
  * that have no doc of their own, so most candidates are misses.
  */
-function docFilesDocumenting(classNames: Set<string>): string[] {
+function docFilesDocumenting(
+  srcDir: string,
+  classNames: Set<string>,
+): string[] {
   const matches: string[] = [];
   const walk = (dir: string): void => {
     for (const entry of readdirSync(dir, {withFileTypes: true})) {
@@ -346,18 +373,22 @@ function docFilesDocumenting(classNames: Set<string>): string[] {
       }
     }
   };
-  walk(SRC_DIR);
+  walk(srcDir);
   return matches;
 }
 
-function discoverComponents(): ComponentInfo[] {
+function discoverComponents(
+  srcDir: string,
+  packageName: ComponentInfo['packageName'],
+  requiredDirs: ReadonlySet<string> = new Set(),
+): ComponentInfo[] {
   const results: ComponentInfo[] = [];
-  const dirs = readdirSync(SRC_DIR, {withFileTypes: true})
+  const dirs = readdirSync(srcDir, {withFileTypes: true})
     .filter(d => d.isDirectory())
     .map(d => d.name);
 
   for (const dir of dirs) {
-    const dirPath = join(SRC_DIR, dir);
+    const dirPath = join(srcDir, dir);
     const dirEntries = readdirSync(dirPath);
 
     const sourceFiles = dirEntries.filter(
@@ -389,10 +420,7 @@ function discoverComponents(): ComponentInfo[] {
     // doc file that CI never checks. (Same guard as derivedVarRegistry.test.ts.)
     const docFiles = dirEntries.includes(`${dir}.doc.mjs`)
       ? [join(dirPath, `${dir}.doc.mjs`)]
-      : docFilesDocumenting(new Set(sites.map(s => s.className)));
-    if (docFiles.length === 0) {
-      continue;
-    }
+      : docFilesDocumenting(srcDir, new Set(sites.map(s => s.className)));
 
     const docBlocks: ComponentInfo['docBlocks'] = [];
     for (const docFile of docFiles) {
@@ -404,18 +432,23 @@ function discoverComponents(): ComponentInfo[] {
       }
       for (const key of ['docs', 'docsZh'] as const) {
         const targets = mod[key]?.theming?.targets;
-        // Only blocks that already document a theming surface are held to it —
-        // a doc with no theming block at all is a separate (documentation) gap.
+        // A normal Core or Lab component enrolls by declaring a theming
+        // surface. Promotion candidates are also enrolled here so a missing
+        // block is a failure rather than a silently skipped readiness gap.
         if (targets != null) {
-          docBlocks.push({key, file: relative(SRC_DIR, docFile), targets});
+          docBlocks.push({key, file: relative(srcDir, docFile), targets});
         }
       }
     }
-    if (docBlocks.length === 0) {
+    const participates =
+      packageName === 'core'
+        ? docBlocks.length > 0
+        : requiredDirs.has(dir) || docBlocks.length > 0;
+    if (!participates) {
       continue;
     }
 
-    results.push({dir, sites, docBlocks});
+    results.push({packageName, dir, sites, docBlocks});
   }
   return results;
 }
@@ -425,24 +458,57 @@ function discoverComponents(): ComponentInfo[] {
 // ---------------------------------------------------------------------------
 
 describe('theming.targets matches the themeProps() call sites', () => {
-  const components = discoverComponents();
+  const components = [
+    ...discoverComponents(CORE_SRC_DIR, 'core'),
+    ...discoverComponents(LAB_SRC_DIR, 'lab', LAB_PROMOTION_DIRS),
+  ];
+
+  it('finds participating Core and Lab components', () => {
+    // A refactor that renames themeProps or drops the Lab package from this
+    // inventory must not silently disable either side of the guard.
+    expect(components.some(component => component.packageName === 'core')).toBe(
+      true,
+    );
+    expect(components.some(component => component.packageName === 'lab')).toBe(
+      true,
+    );
+  });
 
-  it('finds components to check', () => {
-    // A refactor that renames themeProps must not silently disable this file.
-    expect(components.length).toBeGreaterThan(0);
+  it('enrolls every Lab promotion candidate and explicit theming capability', () => {
+    const labDirs = new Set(
+      components
+        .filter(component => component.packageName === 'lab')
+        .map(component => component.dir),
+    );
+    expect([...LAB_PROMOTION_DIRS].filter(dir => !labDirs.has(dir))).toEqual(
+      [],
+    );
+    expect(LAB_PROMOTION_DIRS.has('CircularProgress')).toBe(false);
+    expect(labDirs.has('CircularProgress')).toBe(true);
+    expect(labDirs.has('Schedule')).toBe(false);
   });
 
-  for (const {dir, sites, docBlocks} of components) {
+  for (const {packageName, dir, sites, docBlocks} of components) {
+    const componentLabel = `${packageName}/${dir}`;
     const renderedClasses = [...new Set(sites.map(s => s.className))].sort();
 
+    it(`${componentLabel}: participating components declare theming metadata`, () => {
+      expect(
+        docBlocks,
+        `${componentLabel} participates in the public theming contract but has ` +
+          `no loadable .doc.mjs theming.targets. Lab components participate ` +
+          `when they declare theming.targets or enter the promotion manifest.`,
+      ).not.toHaveLength(0);
+    });
+
     for (const {key, file, targets} of docBlocks) {
       const documented = new Set(targets.map(t => t.className));
 
-      it(`${dir} (${file} ${key}): every rendered class is documented`, () => {
+      it(`${componentLabel} (${file} ${key}): every rendered class is documented`, () => {
         const undocumented = renderedClasses.filter(c => !documented.has(c));
         expect(
           undocumented,
-          `${dir} renders ${undocumented.length} astryx-* class(es) that ` +
+          `${componentLabel} renders ${undocumented.length} astryx-* class(es) that ` +
             `${file} ${key}.theming.targets does not document: ` +
             `${undocumented.join(', ')}. An undocumented class is an ` +
             `unthemeable element — theme authors and codegen read targets[] ` +
@@ -450,7 +516,7 @@ describe('theming.targets matches the themeProps() call sites', () => {
         ).toEqual([]);
       });
 
-      it(`${dir} (${file} ${key}): every visual prop passed to themeProps is documented`, () => {
+      it(`${componentLabel} (${file} ${key}): every visual prop passed to themeProps is documented`, () => {
         const missing: string[] = [];
         for (const site of sites) {
           const target = targets.find(t => t.className === site.className);