docs(spec): propose scoped Drawer contract

[imdreamrunner]

Why

Drawer is planned for Core, but #5550 exposes unresolved public decisions before promotion: whether an inspector belongs to the viewport or one region, whether regional blocking can honestly be called modal, whether modality and scrim are separate caller concepts, and how stacked Drawers behave across scopes.

What

• Adds draft system spec spec:AST-007 for Drawer scope, modality, scrim presentation, regional geometry, lifecycle, stacking, dismissal, and accessibility.
• Proposes containerRef as an explicit caller-owned regional target, with viewport scope on omission and a stable presented lifetime.
• Separates the candidate modality contract from scrim presentation while leaving that API choice open for owner judgment.
• Requires a regional blocking Drawer to stay outside the subtree it blocks, include the regional root itself, freeze blocked background scrolling, and avoid false aria-modal or body-lock claims.
• Defines scope-isolated visual/enforcement order, including regional targets inside versus outside an active document-modal subtree.
• Reconciles Drawer policy with accepted AST-003: eligible-owner and branch resolvers, same-gesture claims, local-dismissal migration, and modal outlets remain owned there rather than duplicated here.
• Explicitly leaves feat(Drawer): recede a buried drawer so a stack reads as layered pages #5652's recede presentation, hasStackRecede, and theming variables to a separate design/theming decision.

Relationship to #5550 and #5652

#5550 and #5652 remain implementation and presentation candidates. They establish feasibility and expose failure cases, but do not make this draft contract authoritative. The implementation must align with an accepted version of AST-007 before Core promotion.

AST-008 is already claimed by #5800; AST-007 is the lowest unclaimed system-spec ID on main and across open PRs.

Risk

Knowledge only. No Lab/Core runtime, public package, generated artifact, visual output, or consumer behavior changes. The record remains draft / proposed; no Drawer API is accepted until the open questions are resolved and the exact head receives owner approval. No Changeset.

Validation

• pnpm check:knowledge -- --base origin/main
• pnpm check:repo
• Prettier and staged diff checks
• Two independent contract reviews, including exact-head reconciliation with AST-002, AST-003, architecture:layer-runtime, family:overlay-dismissal, feat(Drawer): independent scope, modality, and scrim paint #5550, and feat(Drawer): recede a buried drawer so a stack reads as layered pages #5652

Review questions

1. Should containerRef be the explicit regional target, stable through each presented lifetime?
2. Should modality and hasScrim remain independent, including a visible modal scrim as the outside-pointer dismissal plane?
3. Should region-scoped blocking be called modal even though it is not document modality, aria-modal, showModal(), or body scroll locking?
4. Should a regional Drawer inside an active viewport modal be supported only as an explicitly associated child branch, with every unrelated regional target isolated as its own logical stack?

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
astryx	Ready	Preview	Sep 1, 2026 2:07am UTC