@astryxdesign/core 0.7.2 → 0.7.3-canary.02f5fe4

package/dist/utils/disabledInteraction.js

@@ -0,0 +1,33 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file disabledInteraction.ts
+ * @input An optional caller keydown handler
+ * @output Event props that keep a focusable, aria-disabled control inert
+ * @position Shared by controls that replace native `disabled` with
+ *   `aria-disabled` under spec:AST-085 (FR1, FR2)
+ */
+
+/**
+ * Event props for a disabled control that stays focusable. Native `disabled`
+ * dispatched no click at all; without it, Enter and Space still synthesize a
+ * click that native listeners on the element (a wrapping Popover's trigger)
+ * receive. Cancelling those keys keeps the click from existing, and the click
+ * handler cancels pointer clicks and keeps them from reaching ancestors. Other
+ * keys still reach the caller's handler.
+ */
+export function disabledInteractionProps(onKeyDown) {
+  return {
+    onClick: event => {
+      event.preventDefault();
+      event.stopPropagation();
+    },
+    onKeyDown: event => {
+      if (event.key === 'Enter' || event.key === ' ') {
+        event.preventDefault();
+      } else {
+        onKeyDown?.(event);
+      }
+    }
+  };
+}

package/dist/utils/timeParser.d.ts

@@ -70,6 +70,10 @@ export declare function isTimeInRange(time: ISOTimeString, min?: ISOTimeString,
 export declare function clampTime(time: ISOTimeString, min?: ISOTimeString, max?: ISOTimeString, includeSeconds?: boolean): ISOTimeString;
 /**
  * Adjusts a time by adding/subtracting minutes.
+ *
+ * `deltaMinutes` is a whole number of minutes. A fractional delta leaves the
+ * time unchanged rather than returning a value that is no longer a time —
+ * `HH:MM` has no place for a fraction of a minute.
  */
 export declare function adjustTime(time: ISOTimeString, deltaMinutes: number, includeSeconds?: boolean): ISOTimeString;
 //# sourceMappingURL=timeParser.d.ts.map

package/dist/utils/timeParser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"timeParser.d.ts","sourceRoot":"","sources":["../../src/utils/timeParser.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AAEH;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG;IAAC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;CAAC,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAMvE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CA6B5D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,UAAU,EAChB,cAAc,GAAE,OAAe,GAC9B,aAAa,CAUf;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,aAAa,GAAG,SAAS,EAC/B,cAAc,GAAE,OAAe,GAC9B,MAAM,CAqBR;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,aAAa,GAAG,SAAS,EAC/B,cAAc,GAAE,OAAe,GAC9B,MAAM,CAmBR;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,cAAc,GAAE,OAAe,GAC9B,aAAa,GAAG,IAAI,CA6HtB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,CAAC,EAAE,aAAa,GAAG,SAAS,EAC5B,CAAC,EAAE,aAAa,GAAG,SAAS,GAC3B,MAAM,CA4BR;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,aAAa,EACnB,GAAG,CAAC,EAAE,aAAa,EACnB,GAAG,CAAC,EAAE,aAAa,GAClB,OAAO,CAQT;AAED;;GAEG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,aAAa,EACnB,GAAG,CAAC,EAAE,aAAa,EACnB,GAAG,CAAC,EAAE,aAAa,EACnB,cAAc,GAAE,OAAe,GAC9B,aAAa,CAoBf;AAED;;GAEG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,aAAa,EACnB,YAAY,EAAE,MAAM,EACpB,cAAc,GAAE,OAAe,GAC9B,aAAa,CAwBf"}
+{"version":3,"file":"timeParser.d.ts","sourceRoot":"","sources":["../../src/utils/timeParser.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AAEH;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG;IAAC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;CAAC,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAMvE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CA6B5D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,UAAU,EAChB,cAAc,GAAE,OAAe,GAC9B,aAAa,CAUf;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,aAAa,GAAG,SAAS,EAC/B,cAAc,GAAE,OAAe,GAC9B,MAAM,CAqBR;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,aAAa,GAAG,SAAS,EAC/B,cAAc,GAAE,OAAe,GAC9B,MAAM,CAmBR;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,cAAc,GAAE,OAAe,GAC9B,aAAa,GAAG,IAAI,CA6HtB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,CAAC,EAAE,aAAa,GAAG,SAAS,EAC5B,CAAC,EAAE,aAAa,GAAG,SAAS,GAC3B,MAAM,CA4BR;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,aAAa,EACnB,GAAG,CAAC,EAAE,aAAa,EACnB,GAAG,CAAC,EAAE,aAAa,GAClB,OAAO,CAQT;AAED;;GAEG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,aAAa,EACnB,GAAG,CAAC,EAAE,aAAa,EACnB,GAAG,CAAC,EAAE,aAAa,EACnB,cAAc,GAAE,OAAe,GAC9B,aAAa,CAoBf;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,aAAa,EACnB,YAAY,EAAE,MAAM,EACpB,cAAc,GAAE,OAAe,GAC9B,aAAa,CA2Bf"}

package/dist/utils/timeParser.js

@@ -313,6 +313,10 @@ export function clampTime(time, min, max, includeSeconds = false) {
 
 /**
  * Adjusts a time by adding/subtracting minutes.
+ *
+ * `deltaMinutes` is a whole number of minutes. A fractional delta leaves the
+ * time unchanged rather than returning a value that is no longer a time —
+ * `HH:MM` has no place for a fraction of a minute.
  */
 export function adjustTime(time, deltaMinutes, includeSeconds = false) {
   const parsed = parseISOTime(time);
@@ -321,8 +325,11 @@ export function adjustTime(time, deltaMinutes, includeSeconds = false) {
   }
 
   // A non-finite delta would spin the wrap-around forever (-Infinity) or
-  // produce "NaN:NaN" (NaN) — return the input unchanged instead.
-  if (!Number.isFinite(deltaMinutes)) {
+  // produce "NaN:NaN" (NaN), and a fractional one is never rounded on the way
+  // out — formatISOTime pads "30.5" to two characters and leaves it, so the
+  // caller gets back a value that is no longer a time. Steps are whole
+  // minutes: return the input unchanged instead.
+  if (!Number.isInteger(deltaMinutes)) {
     return time;
   }
   let totalMinutes = parsed.hour * 60 + parsed.minute + deltaMinutes;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.7.2",
+  "version": "0.7.3-canary.02f5fe4",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -792,6 +792,8 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
+    "@astryxdesign/a11y-spec": "0.7.3-canary.02f5fe4",
+    "@astryxdesign/cli": "0.7.3-canary.02f5fe4",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",
@@ -802,9 +804,7 @@
     "@testing-library/jest-dom": "^6.6.0",
     "@testing-library/react": "^16.3.2",
     "@types/babel__core": "^7.20.5",
-    "tailwindcss": "^4.3.2",
-    "@astryxdesign/a11y-spec": "0.0.0",
-    "@astryxdesign/cli": "0.7.2"
+    "tailwindcss": "^4.3.2"
   },
   "dependencies": {
     "intl-messageformat": "^11.2.9"

package/scripts/agent-doc-state.mjs

@@ -39,10 +39,31 @@ import * as path from 'node:path';
 export const AGENTS_MD = 'AGENTS.md';
 export const CLAUDE_MD = 'CLAUDE.md';
 export const CLAUDE_DIR_MD = '.claude/CLAUDE.md'; // cross-platform literal
+export const GEMINI_MD = 'GEMINI.md';
 export const CURSOR_RULES = '.cursorrules';
 export const HERMES_DOT_MD = '.hermes.md';
 export const HERMES_MD = 'HERMES.md';
 
+/**
+ * The page workflow every Astryx agent text gives, written with the command
+ * name `astryx`: the project agent docs and the computer-level skill both
+ * render these lines, so the two never drift.
+ */
+export const WORKFLOW_TITLE =
+  'WORKFLOW — start every page from a template, never from scratch:';
+export const WORKFLOW_STEPS = Object.freeze([
+  '1. `astryx build "<idea>"` — names the template to scaffold from and the parts it lacks.',
+  '2. `astryx template <name> <path>` — scaffold it; keep its frame, gap and padding; replace the content.',
+  '3. `astryx template <Block>` for parts it lacks; `astryx component <Name>` to read props before using one.',
+]);
+
+/**
+ * The self-check's fix for a project with no StyleX or Tailwind compiler,
+ * and for an agent outside a project.
+ */
+export const SELF_CHECK_CSS =
+  'replace any raw <div>/<span>, imported .css/@apply, or hardcoded #hex/px with the component or a token';
+
 export const MARKER_START = '<!-- ASTRYX:START -->';
 export const MARKER_END = '<!-- ASTRYX:END -->';
 // Legacy markers — read during migration so the script finds existing XDS blocks
@@ -51,15 +72,18 @@ export const LEGACY_MARKER_END = '<!-- XDS:END -->';
 
 /**
  * The canonical set of EVERY location an --agent preset (or the default) can
- * write the Astryx block. SINGLE SOURCE OF TRUTH: discovery, removal, and the
- * `isAstryxInitialized` predicate all derive from this list, so "where init
- * writes" and "where we look" can never drift. (Explicit --agent-docs-path
- * targets are user-chosen and not enumerable here.)
+ * write a managed Astryx block — the full block, or the one-line import of
+ * AGENTS.md that the default writes to GEMINI.md. SINGLE
+ * SOURCE OF TRUTH: discovery, removal, and the `isAstryxInitialized` predicate
+ * all derive from this list, so "where init writes" and "where we look" can
+ * never drift. (Explicit --agent-docs-path targets are user-chosen and not
+ * enumerable here.)
  */
 export const AGENT_DOC_PATHS = [
   AGENTS_MD, // Codex / ChatGPT / Muse / generic
   CLAUDE_MD, // Claude Code (root)
   CLAUDE_DIR_MD, // Claude Code (.claude/CLAUDE.md)
+  GEMINI_MD, // Gemini CLI
   CURSOR_RULES, // Cursor
   HERMES_DOT_MD, // Hermes
   HERMES_MD, // Hermes
@@ -74,7 +98,7 @@ export const INIT_MARKERS = [MARKER_START, LEGACY_MARKER_START];
 /**
  * Find all existing agent doc files in a directory, across EVERY location any
  * preset can write (see {@link AGENT_DOC_PATHS}: AGENTS.md, CLAUDE.md,
- * .claude/CLAUDE.md, .cursorrules, .hermes.md, HERMES.md).
+ * .claude/CLAUDE.md, GEMINI.md, .cursorrules, .hermes.md, HERMES.md).
  * @param {string} targetDir
  * @returns {string[]} Relative paths of existing agent doc files
  */
@@ -82,10 +106,35 @@ export function discoverAgentDocs(targetDir) {
   return AGENT_DOC_PATHS.filter(p => fs.existsSync(path.join(targetDir, p)));
 }
 
+/**
+ * Whether `content` holds an Astryx block. A managed block that only imports
+ * another file (the one-line `@./AGENTS.md` that init writes to GEMINI.md) does
+ * not count: it holds nothing once that file has lost its block. A malformed
+ * block still counts, so a half-written file reads as set up.
+ *
+ * @param {string} content
+ * @returns {boolean}
+ */
+export function holdsAstryxBlock(content) {
+  for (const marker of INIT_MARKERS) {
+    let at = content.indexOf(marker);
+    while (at !== -1) {
+      const from = at + marker.length;
+      const end = content.indexOf('<!--', from);
+      const inner = (
+        end === -1 ? content.slice(from) : content.slice(from, end)
+      ).trim();
+      if (!/^@\S+$/.test(inner)) return true;
+      at = content.indexOf(marker, from);
+    }
+  }
+  return false;
+}
+
 /**
  * Single source of truth for "is Astryx set up in this project?" — true when any
- * agent-doc file already carries the Astryx marker, i.e. `init` / `agent-docs`
- * has run. Reused by the init & upgrade commands, the per-command setup nudge
+ * agent-doc file already holds an Astryx block, i.e. `init` / `agent-docs` has
+ * run. Reused by the init & upgrade commands, the per-command setup nudge
  * (enforcement layer 3), and the cli postinstall nudge (layer 2). Core's
  * postinstall (separate package, layer 1) mirrors the same marker contract.
  *
@@ -96,7 +145,7 @@ export function isAstryxInitialized(targetDir = process.cwd()) {
   for (const rel of discoverAgentDocs(targetDir)) {
     try {
       const content = fs.readFileSync(path.join(targetDir, rel), 'utf-8');
-      if (INIT_MARKERS.some(m => content.includes(m))) {
+      if (holdsAstryxBlock(content)) {
         return true;
       }
     } catch {
@@ -136,7 +185,7 @@ export function isAstryxPromptInReach(startDir = process.cwd()) {
  * @returns {string | null}
  */
 function findRepositoryRoot(start) {
-  for (let dir = start; ; ) {
+  for (let dir = start; ;) {
     if (fs.existsSync(path.join(dir, '.git'))) return dir;
     const parent = path.dirname(dir);
     if (parent === dir) return null;

package/src/Banner/Banner.spec.md

@@ -42,29 +42,29 @@ separately targetable surface. The status and content targets remain unchanged.
 - Released default preserved: `no` — Banner no longer derives a live-region role from visual status
 - Compatibility class: breaking accessibility-semantic correction; visual output, DOM structure, props, theming targets, and interaction behavior are unchanged
 - Controlled/uncontrolled behavior: unchanged
-- Migration decision: announce async outcomes in their transition handler with `useAnnounce`; add an explicit `role="status"` only for a persistent semantic mirror, and reserve `role="alert"` for genuinely urgent interruption
+- Migration decision: announce async outcomes in their transition handler with `useAnnounce`; add an explicit `role="status"` only for a persistent semantic mirror, and reserve `role="alert"` for genuinely urgent interruption. Inside a mounted live container, `spec:AST-086` FR4 applies instead.
 
 Consumer migration instructions belong in consumer docs and release notes.
 
 ### DEP-0007 — Deprecate live-region roles derived from `status`
 
-| Field            | Value                                                                                                                                                                                                                                                                              |
-| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| id               | `DEP-0007`                                                                                                                                                                                                                                                                         |
-| cleanup          | `CLN-0015`                                                                                                                                                                                                                                                                         |
-| package          | `@astryxdesign/core`                                                                                                                                                                                                                                                               |
-| surface          | Default ARIA role of `Banner`: `role="alert"` for `warning` and `error`, `role="status"` for `info` and `success`, derived from `status` when the caller passes no `role`                                                                                                          |
-| old contract     | Visual `status` selects the live-region role of the Banner root                                                                                                                                                                                                                    |
-| replacement      | A caller that announces an async outcome calls `useAnnounce` from the transition that produced it. A caller whose Banner is a persistent semantic mirror passes `role="status"`; genuinely urgent content passes `role="alert"`. Both explicit roles already reach the Banner root |
-| direct authority | `component:Banner`. Owners: `cixzhang`, `imdreamrunner`                                                                                                                                                                                                                            |
-| warning          | Consumer docs and the release notes name `DEP-0007` and the explicit `role` that keeps the released semantics. No runtime warning (`spec:AST-017` FR29)                                                                                                                            |
-| migration        | Non-mechanical: a caller that announces an async outcome calls `useAnnounce` from the transition that produced it; a caller whose Banner is a persistent mirror or urgent content passes `role="status"` or `role="alert"`                                                         |
-| codemod          | None: whether a Banner needs an announcement, and when, depends on the transition that renders it, which only the caller knows; adding the released role everywhere would restore the coupling this cleanup removes                                                                |
-| downstream       | Maintained docs teach `useAnnounce` for async outcomes and explicit `role` for persistent mirrors                                                                                                                                                                                  |
-| transition       | no prior transition                                                                                                                                                                                                                                                                |
-| state            | `proposed`                                                                                                                                                                                                                                                                         |
-| open decision    | Banner FR and DEC entries that make `status` visual-only                                                                                                                                                                                                                           |
-| target plan      | `CLN-0015` in the next minor release                                                                                                                                                                                                                                               |
+| Field            | Value                                                                                                                                                                                                                                                                                                                                                    |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| id               | `DEP-0007`                                                                                                                                                                                                                                                                                                                                               |
+| cleanup          | `CLN-0015`                                                                                                                                                                                                                                                                                                                                               |
+| package          | `@astryxdesign/core`                                                                                                                                                                                                                                                                                                                                     |
+| surface          | Default ARIA role of `Banner`: `role="alert"` for `warning` and `error`, `role="status"` for `info` and `success`, derived from `status` when the caller passes no `role`                                                                                                                                                                                |
+| old contract     | Visual `status` selects the live-region role of the Banner root                                                                                                                                                                                                                                                                                          |
+| replacement      | A caller that announces an async outcome calls `useAnnounce` from the transition that produced it. A caller whose Banner is a persistent semantic mirror passes `role="status"`; genuinely urgent content passes `role="alert"`. Both explicit roles already reach the Banner root. Inside a mounted live container, `spec:AST-086` FR4 applies instead. |
+| direct authority | `component:Banner`. Owners: `cixzhang`, `imdreamrunner`                                                                                                                                                                                                                                                                                                  |
+| warning          | Consumer docs and the release notes name `DEP-0007` and the explicit `role` that keeps the released semantics. No runtime warning (`spec:AST-017` FR29)                                                                                                                                                                                                  |
+| migration        | Non-mechanical: a caller that announces an async outcome calls `useAnnounce` from the transition that produced it; a caller whose Banner is a persistent mirror or urgent content passes `role="status"` or `role="alert"`. Inside a mounted live container, `spec:AST-086` FR4 applies instead.                                                         |
+| codemod          | None: whether a Banner needs an announcement, and when, depends on the transition that renders it, which only the caller knows; adding the released role everywhere would restore the coupling this cleanup removes                                                                                                                                      |
+| downstream       | Maintained docs teach `useAnnounce` for async outcomes and explicit `role` for persistent mirrors. Inside a mounted live container, `spec:AST-086` FR4 applies instead.                                                                                                                                                                                  |
+| transition       | no prior transition                                                                                                                                                                                                                                                                                                                                      |
+| state            | `proposed`                                                                                                                                                                                                                                                                                                                                               |
+| open decision    | Banner FR and DEC entries that make `status` visual-only                                                                                                                                                                                                                                                                                                 |
+| target plan      | `CLN-0015` in the next minor release                                                                                                                                                                                                                                                                                                                     |
 
 ### CLN-0015 — Banner renders no live-region role by default
 
@@ -105,16 +105,16 @@ prop vocabulary or extensibility rule changes.
 The requirements below describe the current implementation and its additive
 frame target contract.
 
-| ID  | Invariant                                                                                                                                                                                                                                                                                                            | Basis                                                  | Contract state           |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------ |
-| FR1 | The current render places `banner` on the colored status surface, which is Banner's primary painted surface and reflects `container` and `status`.                                                                                                                                                                   | Current source, public docs, and tests                 | Current behavior         |
-| FR2 | The Banner frame receives the public ref, role, supported DOM props, `xstyle`, `className`, and `style`; it also paints the selected `boxShadow`.                                                                                                                                                                    | Current source and tests                               | Current behavior         |
-| FR3 | An elevated `card` frame also paints the whole-banner radius. A `section` frame remains square. A non-elevated frame does not receive the frame-radius style.                                                                                                                                                        | Current source and elevation tests                     | Current behavior         |
-| FR4 | Card shape is split across surface owners: the status surface owns all corners without visible content or the top corners with visible content; the content surface owns the bottom corners.                                                                                                                         | Current source                                         | Current behavior         |
-| FR5 | Theme-authored `borderRadius` on `banner` currently writes the private `--_banner-radius` variable on the Status surface only. CSS inheritance does not carry that value upward to the frame or sideways to the Content surface, so both keep their fallback radius.                                                 | Current compiler output and CSS inheritance            | Current reachability gap |
-| FR6 | The Banner frame exposes `banner-frame` and reflects `container` and `elevation`. The existing `banner` target remains on the Status surface rather than moving to the outermost DOM element.                                                                                                                        | Owner decision; current source and tests               | Current behavior         |
-| FR7 | `banner-frame` is additive. The existing `banner`, `banner-icon`, `banner-description`, and `banner-content` targets and their current axes remain unchanged.                                                                                                                                                        | Current target inventory; compatibility policy         | Current behavior         |
-| FR8 | `status` controls visual meaning only and MUST NOT derive `role`, `aria-live`, or an announcement. Standard DOM props MAY provide an explicit persistent role. Async outcomes MUST announce from the transition handler through `useAnnounce`; `role="alert"` is reserved for genuinely urgent interruptive content. | Accessibility Checklist §Announcements; owner decision | Current behavior         |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Basis                                                  | Contract state           |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------ |
+| FR1 | The current render places `banner` on the colored status surface, which is Banner's primary painted surface and reflects `container` and `status`.                                                                                                                                                                                                                                                                                                                            | Current source, public docs, and tests                 | Current behavior         |
+| FR2 | The Banner frame receives the public ref, role, supported DOM props, `xstyle`, `className`, and `style`; it also paints the selected `boxShadow`.                                                                                                                                                                                                                                                                                                                             | Current source and tests                               | Current behavior         |
+| FR3 | An elevated `card` frame also paints the whole-banner radius. A `section` frame remains square. A non-elevated frame does not receive the frame-radius style.                                                                                                                                                                                                                                                                                                                 | Current source and elevation tests                     | Current behavior         |
+| FR4 | Card shape is split across surface owners: the status surface owns all corners without visible content or the top corners with visible content; the content surface owns the bottom corners.                                                                                                                                                                                                                                                                                  | Current source                                         | Current behavior         |
+| FR5 | Theme-authored `borderRadius` on `banner` currently writes the private `--_banner-radius` variable on the Status surface only. CSS inheritance does not carry that value upward to the frame or sideways to the Content surface, so both keep their fallback radius.                                                                                                                                                                                                          | Current compiler output and CSS inheritance            | Current reachability gap |
+| FR6 | The Banner frame exposes `banner-frame` and reflects `container` and `elevation`. The existing `banner` target remains on the Status surface rather than moving to the outermost DOM element.                                                                                                                                                                                                                                                                                 | Owner decision; current source and tests               | Current behavior         |
+| FR7 | `banner-frame` is additive. The existing `banner`, `banner-icon`, `banner-description`, and `banner-content` targets and their current axes remain unchanged.                                                                                                                                                                                                                                                                                                                 | Current target inventory; compatibility policy         | Current behavior         |
+| FR8 | `status` controls visual meaning only and MUST NOT derive `role`, `aria-live`, or an announcement. Standard DOM props MAY provide an explicit persistent role, except on a Banner added inside a mounted live container (`spec:AST-086` FR4). Async outcomes MUST announce from the transition handler through `useAnnounce`, except inside a mounted live container, where `spec:AST-086` FR4 applies; `role="alert"` is reserved for genuinely urgent interruptive content. | Accessibility Checklist §Announcements; owner decision | Current behavior         |
 
 ### Allowed variation
 
@@ -154,11 +154,15 @@ runtime work.
 `status` communicates visual category through color and icon; it does not choose
 announcement urgency. Banner renders no live-region role by default. A caller may
 provide `role="status"` through the standard DOM surface when the visible banner
-is intentionally a persistent semantic mirror. Async outcomes use `useAnnounce`
+is intentionally a persistent semantic mirror, except on a Banner added inside a
+mounted live container. Async outcomes use `useAnnounce`
 from the transition handler, which writes into a previously mounted live region;
+inside a mounted live container, that container delivers them
+(`spec:AST-086` FR4);
 a Banner mounted together with its message is not a reliable announcement.
 `role="alert"` remains available as an explicit native role, but is reserved for
-genuinely urgent content that should interrupt current speech.
+genuinely urgent content that should interrupt current speech; it is not used on
+a Banner added inside a mounted live container.
 
 Dismissal focus handoff, disclosure controls, and accessible control names remain
 unchanged.
@@ -247,8 +251,9 @@ placement and would imply that the target must remain on the outermost element.
 Banner status selects color and icon only. It does not assign `role="status"` or
 `role="alert"`. Async outcomes announce through `useAnnounce` from the transition
 handler so the message reaches a persistent live region rather than one mounted
-with its content. An explicit native role remains available through BaseProps for
-a persistent semantic mirror or the rare genuinely urgent alert.
+with its content; inside a mounted live container, `spec:AST-086` FR4 applies. An explicit native role remains available through BaseProps for
+a persistent semantic mirror or the rare genuinely urgent alert, except on a
+Banner added inside a mounted live container.
 
 Rejected: deriving alert urgency from `warning` or `error`. Severity and urgency
 are independent, and a static error present on first paint is not an event that

package/src/BottomSheet/BottomSheet.spec.md

@@ -3,11 +3,11 @@ schema_version: 3
 template_version: 3
 kind: component
 id: component:BottomSheet
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: imdreamrunner
+approved_at: 2026-10-21
 owners: [cixzhang]
 review_triggers: [theming, layout, public-api]
 verified_by:
@@ -37,52 +37,24 @@ system_specs: [spec:AST-025]
 ## Intent
 
 BottomSheet presents caller-provided content in a panel that rises from the
-bottom edge. This draft records current consumer anatomy, keyboard-reachable
-scrolling, theming reachability, and the Content area's container padding.
+bottom edge. This record covers consumer anatomy, the native dialog every sheet
+renders, keyboard-reachable scrolling, theming reachability, and the Content
+area's container padding. Where the shipped sheet does not yet meet a
+requirement, the row carries a present-tense implementation gap note.
 
 ## Compatibility and migration
 
-- Released default preserved: `no` — with no `padding` prop and no theme
-  padding, the Content area insets by `--spacing-4` on every logical edge
-- Compatibility class: breaking default, scheduled for a minor release. Content
-  whose only child is a padded Section keeps its geometry because that Section
-  escapes the inset; content that supplies its own inset is padded twice until
-  it drops that inset or sets `padding={0}`
+- Released default preserved: `yes`; with no `padding` prop and no theme
+  padding, the Content area insets by `--spacing-4` on every logical edge, and
+  `padding={0}` keeps an unpadded Content area
+- Compatibility class: records the shipped anatomy, padded Content area, and
+  native dialog; no public prop, default, or export changes
 - Controlled/uncontrolled behavior: unchanged
-- Migration decision: `padding={0}` restores the released unpadded Content area
+- Migration decision: none; the precedence rule under Transformation and
+  precedence order is the whole contract
 
 Consumer migration instructions belong in consumer docs and release notes.
 
-### DEP-0009 — Deprecate the unpadded default Content area of `BottomSheet`
-
-| Field            | Value                                                                                                                                                               |
-| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| id               | `DEP-0009`                                                                                                                                                          |
-| cleanup          | `CLN-0018`                                                                                                                                                          |
-| package          | `@astryxdesign/core`                                                                                                                                                |
-| surface          | Default inset of the `BottomSheet` Content area when no `padding` prop and no theme padding are set                                                                 |
-| old contract     | The Content area has no padding                                                                                                                                     |
-| replacement      | `padding={0}` keeps the unpadded Content area; `padding` and theme padding already resolve before the default                                                       |
-| direct authority | `component:BottomSheet` Compatibility and migration. Owners: `cixzhang`                                                                                             |
-| warning          | Consumer docs and the release notes name `DEP-0009` and `padding={0}`. No runtime warning (`spec:AST-017` FR29)                                                     |
-| migration        | Mechanical: add `padding={0}` to a BottomSheet that sets no padding, unless its only child is a padded Section or a Layout                                          |
-| codemod          | `astryx upgrade` adds `padding={0}` before any spread, skips sheets whose only child is a core Section or Layout, and marks a nested padding-less Layout for review |
-| downstream       | In-repo sheets that supply their own inset pass `padding={0}`; consumer examples rely on the default inset                                                          |
-| transition       | no prior transition                                                                                                                                                 |
-| state            | `proposed`                                                                                                                                                          |
-| open decision    | This record is draft and needs approval                                                                                                                             |
-| target plan      | `CLN-0018` in the next minor release                                                                                                                                |
-
-### CLN-0018 — BottomSheet pads its Content area by default
-
-| Field     | Value                                                                                                                                |
-| --------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| id        | `CLN-0018`                                                                                                                           |
-| lifecycle | `DEP-0009`                                                                                                                           |
-| delta     | With no `padding` prop and no theme padding, the Content area insets by `--spacing-4` on every logical edge and publishes that inset |
-| rollback  | Restore the unpadded default from the final-patch baseline                                                                           |
-| state     | `pending` — lands in a declared minor with its `[breaking]` Changeset                                                                |
-
 ## Ownership boundary
 
 **Owns**
@@ -93,14 +65,19 @@ Consumer migration instructions belong in consumer docs and release notes.
 - The Content area's container padding, published per
   `architecture:container-padding`.
 - Standalone sheet presentation, including its optional native-dialog Scrim.
+- The native dialog every sheet renders, standalone or switcher-managed
+  (`component:BottomSheetSwitcher` DEC-1). Implementation gap: a
+  switcher-managed sheet renders a panel inside the switcher's one shared
+  dialog and owns no dialog of its own.
 
 **Does not own / non-goals**
 
 - Caller-provided content rendered inside the Content area.
 - A separate target for Content area, Handle, or Scrim; none exists on current
   `main`.
-- A shared switcher dialog or scrim — owned by BottomSheetSwitcher when the sheet
-  participates in that host.
+- The presentation lifecycle of its dialog and the flow's scrim ownership when
+  the sheet participates in a BottomSheetSwitcher — owned by BottomSheetSwitcher
+  (`component:BottomSheetSwitcher` DEC-1).
 - Shared layer hosting or dismissal policy.
 
 ## Public concepts
@@ -110,12 +87,12 @@ in `BottomSheet.doc.mjs`.
 
 ## Behavioral and layout contract
 
-| ID  | Candidate invariant                                                                                                                                                                                                                         | Basis                              | Draft review state                                 |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | -------------------------------------------------- |
-| FR1 | The current presented sheet contains one Sheet panel, one scrolling Content area, and one decorative Handle; a Scrim is present only in scrim-backed presentation.                                                                          | Current source, docs, and tests    | Verified current behavior; no new behavior decided |
-| FR2 | The Sheet panel carries `bottom-sheet`; Content area, Handle, and Scrim carry no BottomSheet public target.                                                                                                                                 | Current source, docs, and tests    | Verified current behavior; no target change        |
-| FR3 | Content renders in one real observed content box. Effective overflow, containment, and keyboard access come from `useScrollableArea`; the named overflowing body delegates forward Tab entry to a safe first sequential native link/button. | `spec:AST-025`; issue #5207; tests | Focus-time prototype for owner review              |
-| FR4 | The Content area pads caller content by the sheet's container inset and publishes the applied inset to descendants as a container publisher.                                                                                                | `architecture:container-padding`   | Admitted; implementation pending                   |
+| ID  | Invariant                                                                                                                                                                                                                                   | Basis                            |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
+| FR1 | The current presented sheet contains one Sheet panel, one scrolling Content area, and one decorative Handle; a Scrim is present only in scrim-backed presentation.                                                                          | Current source, docs, and tests  |
+| FR2 | The Sheet panel carries `bottom-sheet`; Content area, Handle, and Scrim carry no BottomSheet public target.                                                                                                                                 | Current source, docs, and tests  |
+| FR3 | Content renders in one real observed content box. Effective overflow, containment, and keyboard access come from `useScrollableArea`; the named overflowing body delegates forward Tab entry to a safe first sequential native link/button. | `spec:AST-025`; tests            |
+| FR4 | The Content area pads caller content by the sheet's container inset and publishes the applied inset to descendants as a container publisher.                                                                                                | `architecture:container-padding` |
 
 ### Allowed variation
 
@@ -128,8 +105,10 @@ in `BottomSheet.doc.mjs`.
 - A standalone modal sheet renders Sheet panel, Content area, Handle, and Scrim.
 - A standalone non-modal sheet renders Sheet panel, Content area, and Handle
   without a Scrim.
-- A switcher-managed sheet renders the same panel anatomy while
-  BottomSheetSwitcher owns the shared dialog and optional Scrim.
+- A switcher-managed sheet renders the same panel anatomy in its own dialog while
+  BottomSheetSwitcher coordinates that dialog's lifecycle and the flow's one Scrim
+  (`component:BottomSheetSwitcher` DEC-1). Implementation gap: the panel
+  renders inside the switcher's one shared dialog.
 
 ### Transformation and precedence order
 
@@ -184,7 +163,7 @@ a decision that they must remain unthemeable.
   },
   "Scrim": {
     "none": {
-      "reason": "reachability-gap: No BottomSheet public target reaches the native dialog backdrop or switcher-owned scrim."
+      "reason": "reachability-gap: No BottomSheet public target reaches the native dialog backdrop, standalone or switcher-coordinated."
     }
   }
 }
@@ -210,7 +189,8 @@ a decision that they must remain unthemeable.
 | ------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | --------------------------------- |
 | FR1                 | `BottomSheet.test.tsx` render, content, Handle, and scrim behavior suites                          | Modal, non-modal, and switcher presentations                             | Removing a documented part fails existing content, structure, or dismissal assertions.                  | `audit:BottomSheet/anatomy`       |
 | FR2                 | Panel target assertion, source inspection, and theming target inventories                          | Sheet panel, Content area, Handle, and Scrim                             | Removing the panel target or documenting an unshipped child target fails evidence or inventory.         | `audit:BottomSheet/theming`       |
-| FR3, AR1–AR2        | `BottomSheetKeyboard.test.tsx`; `BottomSheetKeyboard.a11y.browser.spec.ts`; open Storybook stories | fitting/overflow, plain text, usable/unusable/dynamic descendants, focus | Missing/duplicate keyboard access, stale ownership, focus movement, or broken content-box layout fails. | `audit:BottomSheet/accessibility` |     | Layout evidence | `BottomSheetPanel.test.tsx` | Floating Handle and scrolling Content area | Reordering or merging the stable parts fails existing panel structure and style assertions. | `audit:BottomSheet/anatomy` |
+| FR3, AR1–AR2        | `BottomSheetKeyboard.test.tsx`; `BottomSheetKeyboard.a11y.browser.spec.ts`; open Storybook stories | fitting/overflow, plain text, usable/unusable/dynamic descendants, focus | Missing/duplicate keyboard access, stale ownership, focus movement, or broken content-box layout fails. | `audit:BottomSheet/accessibility` |
+| Layout evidence     | `BottomSheetPanel.test.tsx`                                                                        | Floating Handle and scrolling Content area                               | Reordering or merging the stable parts fails existing panel structure and style assertions.             | `audit:BottomSheet/anatomy`       |
 | FR4                 | `BottomSheetPanel.test.tsx` container padding tests; `derivedVarRegistry.test.ts`                  | default, `padding` prop, theme `padding`, lone padded Section child      | The published inset differs from the applied padding, or a lone padded Section changes geometry.        | `audit:BottomSheet/anatomy`       |
 | 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:BottomSheet/theming`       |
 

package/src/BottomSheet/BottomSheet.test.tsx

@@ -498,6 +498,35 @@ describe('BottomSheet', () => {
     expect(dialog).toHaveStyle({'--_sheet-scrim-opacity': '1'});
   });
 
+  it('stays open when a file picker inside it is dismissed, and still closes on its own close request', () => {
+    // A file input fires a bubbling `cancel` at itself when its picker is
+    // dismissed. It reaches the <dialog> like a close request but is not one.
+    const onOpenChange = vi.fn();
+    render(
+      <BottomSheet
+        isOpen
+        purpose="form"
+        onOpenChange={onOpenChange}
+        label="Upload">
+        <input type="file" aria-label="Picture" />
+      </BottomSheet>,
+    );
+
+    const fromPicker = new Event('cancel', {bubbles: true, cancelable: true});
+    fireEvent(screen.getByLabelText('Picture'), fromPicker);
+
+    expect(onOpenChange).not.toHaveBeenCalled();
+    expect(fromPicker.defaultPrevented).toBe(false);
+
+    fireEvent(
+      screen.getByRole('dialog'),
+      new Event('cancel', {cancelable: true}),
+    );
+
+    expect(onOpenChange).toHaveBeenCalledTimes(1);
+    expect(onOpenChange).toHaveBeenCalledWith(false);
+  });
+
   it('keeps a standalone modal sheet presented through its exit animation', () => {
     render(<ExitHarness />);
     const dialog = screen.getByRole('dialog', {name: 'Filters'});

package/src/BottomSheet/BottomSheet.tsx

@@ -361,12 +361,16 @@ function StandaloneBottomSheet({
   });
 
   // The native `cancel` event is a close request the stack never saw a press
-  // for (Android back, the platform close watcher). Always preventDefault so
-  // the browser cannot close the controlled <dialog>, then answer with the
-  // stack's rules: only the top-most layer dismisses, and nothing dismisses
-  // during an IME composition.
+  // for (Android back, the platform close watcher). One that bubbles up from
+  // inside is not: a file input fires it when its picker is dismissed, so it is
+  // left alone. Otherwise always preventDefault so the browser cannot close the
+  // controlled <dialog>, then answer with the stack's rules: only the top-most
+  // layer dismisses, and nothing dismisses during an IME composition.
   const handleCancel = useCallback(
     (event: React.SyntheticEvent<HTMLDialogElement>) => {
+      if (event.target !== event.currentTarget) {
+        return;
+      }
       event.preventDefault();
       if (shouldDismissOnCloseRequest()) {
         dismissOnEscape();