@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/Toolbar/Toolbar.spec.md

@@ -1,227 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:Toolbar
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-27
-owners: [cixzhang]
-review_triggers: [layout, theming, accessibility]
-verified_by:
-  [
-    packages/core/src/Toolbar/Toolbar.test.tsx,
-    packages/core/src/Toolbar/__tests__/Toolbar.a11y.test.tsx,
-    packages/core/src/Toolbar/__tests__/Toolbar.a11y.chromium.spec.ts,
-    packages/core/src/Section/Section.test.tsx,
-    packages/core/src/theme/themingTargets.test.ts,
-    scripts/check-knowledge.mjs,
-  ]
-modules: []
-families: [family:layout-regions]
-design_specs: [design:reduced-motion]
-architecture:
-  [
-    architecture:component-theming-surface,
-    architecture:container-padding,
-    architecture:component-size-cascade,
-    architecture:interaction-modality,
-    architecture:public-component-api,
-  ]
-contributing: []
-system_specs: [spec:AST-020]
----
-
-# Toolbar component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                                            |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | `Toolbar` with `label`, `startContent`, `centerContent`, `endContent`, `size` (`md`), `gap` (`1`), `orientation` (`horizontal`), `variant` (`transparent`), and `dividers`; target `toolbar` with `size`.                           |
-| Behavior                | A Section-wrapped `role="toolbar"` row with start, optional center, and end lanes. The row is one tab stop; arrow keys, Home, and End move focus among its controls along its orientation.                                          |
-| End-user impact         | Keyboard users Tab into the toolbar once and move between its controls with arrows, without losing text-caret keys inside an input or arrow keys inside an open menu; screen-reader users hear a named toolbar and its orientation. |
-| Builder impact          | None.                                                                                                                                                                                                                               |
-| Compatibility/readiness | Records shipped behavior; no public change. Four implementation gaps (see Current-state impact).                                                                                                                                    |
-| Review checks           | Reject more than one tab stop, arrows that steal caret keys from a text input mid-line, caller props that replace `role`, `aria-label`, or `aria-orientation`, or moving outer chrome into Toolbar.                                 |
-| Governing rules         | `family:layout-regions`; `spec:AST-020` (toolbar pattern binding); `architecture:container-padding`.                                                                                                                                |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-Toolbar presents a named contextual action region with one semantic toolbar row
-inside Section-owned outer chrome. It owns the row's semantics, lane layout,
-keyboard model, and size cascade. Consumer usage lives in `Toolbar.doc.mjs`.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`
-- Compatibility class: records shipped behavior; runtime, DOM, styling,
-  targets, and public API remain unchanged
-- Controlled/uncontrolled behavior: not applicable
-- Migration decision: none
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Current-state impact
-
-- **The keyboard hint fades under reduced motion.** The arrow-key hint (FR6)
-  fades out over 150 ms (it appears at once) even when reduced motion is
-  requested;
-  `design:reduced-motion` DR3 allows no animated property for a fine pointer.
-- **A vertical toolbar with center content stays side by side.** With
-  `orientation="vertical"` and `centerContent`, the three lanes stay in one row
-  while `aria-orientation` is vertical and ArrowDown and ArrowUp move between
-  them, so the visual order and the announced axis disagree.
-- **The tab stop does not follow a pointer click.** After a click on a control
-  that does not hold the stop, the stop stays on the earlier control, so
-  Shift+Tab from the clicked control lands on that earlier control inside the
-  toolbar before leaving it.
-- **Some fields keep their own tab stops.** A `textarea` or `select` in the
-  row is outside the roving stop: it keeps its own tab stop and the arrow keys
-  skip it. The APG toolbar pattern makes the toolbar a single tab stop.
-
-## Ownership boundary
-
-**Owns**
-
-- The named toolbar row, toolbar semantics, start/optional-center/end layout,
-  keyboard movement, size cascade, and current `toolbar` target.
-
-**Does not own / non-goals**
-
-- The painted outer chrome, variant, block padding, and selected divider edges —
-  owned by Section and uncontracted here.
-- Content supplied through the three layout slots — owned by the caller or its
-  rendered components, except the press tracking `family:action-groups` FR5
-  gives Toolbar across its buttons.
-- A general arbitrary-child layout primitive contract.
-- Arrow-key handling inside composed menus or popovers — owned by those
-  components.
-
-## Public concepts
-
-No component-local concept beyond the consumer props; `family:layout-regions`
-owns the shared structural-region boundary.
-
-## Behavioral and layout contract
-
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Basis                                         |
-| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
-| FR1 | The render contains Section-owned Outer chrome around one Toolbar carrying `role="toolbar"`, `aria-label` from `label`, `aria-orientation`, and the `toolbar` target with `size`. Caller `role`, `aria-label`, and `aria-orientation` are dropped; other DOM props reach the toolbar row; `ref`, `className`, `style`, and `xstyle` reach the Section.                                                                                                                                                                                                                                                                                                                                                                                                    | Current source, docs, tests, and family       |
-| FR2 | Without center content the Toolbar is a flex line of the present start and end lanes, a row when horizontal and a column of lanes when vertical; with center content it is a three-lane grid whose lanes sit side by side in either orientation. Each lane lays its controls out in a row. No lane clips its content, and the center lane can shrink below its content width. `gap` spaces controls within and between lanes.                                                                                                                                                                                                                                                                                                                             | Current source and focused structure tests    |
-| FR3 | Variant (default `transparent`), selected divider edges, and block padding by size remain delegated to Section, while Toolbar retains toolbar semantics, keyboard behavior, and internal layout.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Current source, docs, and family contract     |
-| FR4 | The row MUST be a single tab stop. ArrowRight and ArrowLeft (horizontal) or ArrowDown and ArrowUp (vertical) move focus between its controls, wrapping at the ends and skipping disabled controls; Home and End move to the first and last. Implementation gap: only buttons, inputs, links, and elements with `tabindex` share the stop, so `textarea` and `select` carry their own tab stops, and a pointer click does not move the stop (Current-state impact). Arrows do not move focus out of a text input whose caret is mid-line, and inside an open composed menu arrow keys belong to the menu. The toolbar keeps its tab stop after a composed menu is dismissed from outside, and keeps its own arrow movement when rendered inside a popover. | APG toolbar pattern; current source and tests |
-| FR5 | Caller `onKeyDown`, `onFocus`, and `onBlur` run first; when the caller cancels the event, the built-in handling is skipped.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Current source and tests                      |
-| FR6 | Keyboard focus entering the row can show a brief, self-dismissing hint for its arrow-key axis.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Current source                                |
-| FR7 | `size` (default `md`) is provided to descendant controls as their default size; Toolbar starts its own size scope and does not inherit an outer size provider (`architecture:component-size-cascade` INV7).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Current source and tests                      |
-
-### Allowed variation
-
-- Caller content may be absent or supplied in the start, center, and end slots
-  without changing Outer chrome or Toolbar ownership.
-- Size and orientation may change the current row geometry and keyboard axis
-  without creating separate anatomy parts or targets.
-
-### Representative states
-
-| State             | Required invariant                                      | Allowed variation                                                                  |
-| ----------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------- |
-| Empty toolbar     | Outer chrome and named Toolbar remain rendered.         | No caller slot content.                                                            |
-| Two-lane layout   | Start and/or end content use the current flex layout.   | Either lane may be absent.                                                         |
-| Three-lane layout | Center content selects the current three-column layout. | Start or end content may be absent.                                                |
-| Vertical toolbar  | Toolbar semantics and target remain unchanged.          | Keyboard movement uses the vertical axis; lanes stack only without center content. |
-
-### Transformation and precedence order
-
-- **ORD1 — Events.** Caller handler, then the built-in handler unless cancelled
-  (FR5).
-
-### Performance and resources
-
-- No resource rule.
-
-## Accessibility contract
-
-- **AR1 — Named toolbar.** FR1's role, name, and orientation.
-- **AR2 — Keyboard.** FR4 follows the APG toolbar pattern, apart from FR4's
-  implementation gap.
-
-## Design relationships
-
-| Anatomy or state | Design requirement                                                               | Representation authority                  | Hierarchy role | Component contract |
-| ---------------- | -------------------------------------------------------------------------------- | ----------------------------------------- | -------------- | ------------------ |
-| Outer chrome     | Supplies the painted surface, padding, and selected boundaries around the row.   | Section                                   | Supporting     | FR1, FR3           |
-| Toolbar          | Presents the named toolbar semantics and current two- or three-lane arrangement. | Current source, docs, and family contract | Prominent      | FR1, FR2, FR3      |
-
-The slot contents are caller-owned content inside Toolbar's layout. They do not
-become additional Toolbar-owned anatomy or targets.
-
-### Theming anatomy
-
-<!-- anatomy-theming:v1 -->
-
-```json
-{
-  "Outer chrome": {
-    "delegatesTo": {"owner": "component:Section", "target": "section"}
-  },
-  "Toolbar": {"target": "toolbar"}
-}
-```
-
-## Family and system relationships
-
-- `family:layout-regions` owns the structural-region vocabulary and records
-  Toolbar as a Section-backed contextual action region.
-- `architecture:container-padding` owns the inherited inset and edge-compensation
-  geometry used by the composed Section and Toolbar.
-- `architecture:component-theming-surface` owns anatomy qualification, local
-  target mapping, and component delegation.
-- `architecture:public-component-api` owns the stable prop and slot surface.
-- `spec:AST-020` binds the toolbar accessibility pattern exercised by the
-  Toolbar a11y tests.
-
-## Verification map
-
-| Contract            | Verification                                                                                                 | Representative states                               | Mutation or failure expectation                                                                                  | Audit section                 |
-| ------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------- |
-| FR1                 | `Toolbar.test.tsx` role, name, pass-through, and Section suites                                              | Empty and populated Toolbar                         | Removing the role/name, Toolbar target, Section composition, or delegated Section target fails current evidence. | `audit:Toolbar/anatomy`       |
-| FR2                 | `Toolbar.test.tsx` slot and child-count suites                                                               | Start-only, end-only, two-lane, and three-lane      | Changing current slot presence or two-/three-lane structure fails focused assertions.                            | `audit:Toolbar/layout`        |
-| FR3                 | `Toolbar.test.tsx` variant and block-inset tests                                                             | Default and passed variant                          | A variant that no longer reaches Section fails.                                                                  | `audit:Toolbar/theming`       |
-| FR4, FR5, AR1–AR2   | `Toolbar.test.tsx` keyboard and composition suites; `Toolbar.a11y.test.tsx`; `Toolbar.a11y.chromium.spec.ts` | Horizontal, vertical, text input, MoreMenu, popover | Extra tab stops, stolen caret keys, or ignored caller cancellation fails.                                        | `audit:Toolbar/accessibility` |
-| Target inventory    | `packages/core/src/theme/themingTargets.test.ts`                                                             | Toolbar and delegated Section targets               | Runtime and documented target metadata drift fails target validation.                                            | `audit:Toolbar/theming`       |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                | Canonical anatomy and current local target          | Missing, extra, prefixed, or stale mappings fail repository validation.                                          | `audit:Toolbar/theming`       |
-
-Read from source, with no focused test yet:
-
-- FR1: caller `role`, `aria-label`, and `aria-orientation` being dropped, and
-  `className`, `style`, and `xstyle` reaching Section.
-- FR2: the flex and grid layouts themselves, and `gap` spacing.
-- FR3: divider edges.
-- FR5: caller `onFocus` and `onBlur` running first and their cancellation.
-- FR4: `textarea` and `select` keeping their own tab stops, and the stop
-  staying put after a pointer click.
-- FR6.
-- FR7: descendant controls taking `size` as their default, and the fresh size
-  scope.
-
-Computed inset and edge-compensation geometry for each parent padding state is
-not claimed.
-
-## Decision log
-
-No component-local decision is recorded.
-
-## Open questions
-
-None.
-
-## Content boundary
-
-This file does not duplicate consumer prop tables, examples, family layout
-rules, container-padding mechanics, keyboard algorithms, implementation steps,
-or system rules. It links to their owners.

package/src/Tooltip/Tooltip.spec.md

@@ -1,267 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:Tooltip
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-28
-owners: [cixzhang]
-review_triggers: [behavior, theming, accessibility]
-verified_by:
-  [
-    packages/core/src/Tooltip/Tooltip.test.tsx,
-    packages/core/src/Layer/__tests__/TouchTrigger.a11y.chromium.spec.ts,
-    packages/core/src/Tooltip/useTooltip.test.tsx,
-    packages/core/src/Tooltip/__tests__/Tooltip.a11y.test.tsx,
-    packages/core/src/Tooltip/__tests__/Tooltip.a11y.chromium.spec.ts,
-    packages/core/src/Tooltip/__tests__/TooltipHoverBridge.a11y.chromium.spec.ts,
-    packages/core/src/Tooltip/__tests__/TooltipFocusReturn.a11y.chromium.spec.ts,
-    scripts/check-knowledge.mjs,
-  ]
-modules: []
-families: [family:overlay-dismissal]
-design_specs: []
-architecture:
-  [
-    architecture:component-theming-surface,
-    architecture:interaction-modality,
-    architecture:layer-runtime,
-    architecture:public-component-api,
-  ]
-contributing: []
-system_specs: [spec:AST-003]
----
-
-# Tooltip component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                                                                                                  |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | `Tooltip` with `content`, `children` or `anchorRef`, `placement` (`above`), `alignment` (`center`), `delay` (200), `hideDelay` (0), `focusTrigger` (`auto`), `touchTrigger` (`auto`), `isEnabled`, `isOpen`, `isDefaultOpen`, `onOpenChange`, and `hasHoverIndication`; target `tooltip`. |
-| Behavior                | A `role="tooltip"` layer that describes its trigger. It opens on hover after `delay`, on keyboard focus, and on a qualifying tap; it stays open while the pointer moves onto it, and closes on leave, Escape, or pressing the trigger (a press that focuses a text field reopens it).     |
-| End-user impact         | Mouse, keyboard, and touch users can each reveal the hint, move onto it, and dismiss it; screen-reader users hear it as the trigger's description.                                                                                                                                        |
-| Builder impact          | None.                                                                                                                                                                                                                                                                                     |
-| Compatibility/readiness | Records shipped behavior; no public change. Nine implementation gaps (see Current-state impact).                                                                                                                                                                                          |
-| Review checks           | Reject a tooltip that cannot be hovered or dismissed (WCAG 1.4.13), one that opens on a tap's focus or on pointer focus of a trigger that is not a text field, or a lost `aria-describedby` link.                                                                                         |
-| Governing rules         | WCAG 1.4.13; `family:overlay-dismissal`; `architecture:layer-runtime`; `architecture:interaction-modality`; `architecture:component-theming-surface`.                                                                                                                                     |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-Tooltip renders supplied tooltip content on an owned overlay surface associated
-with a caller-owned trigger. It owns how the trigger is wired, when the tooltip
-opens and closes for each input, and the surface's anatomy. Consumer usage lives
-in `Tooltip.doc.mjs`.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`
-- Compatibility class: records shipped behavior; runtime, DOM, styling,
-  targets, and public API remain unchanged
-- Controlled/uncontrolled behavior: uncontrolled by default; `isOpen` forces the
-  state, and a controlled tooltip reports close requests through
-  `onOpenChange(false)` without closing itself (FR7)
-- Migration decision: none
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Current-state impact
-
-- **A held-closed tooltip still opens on focus.** With `isOpen={false}`, the
-  hover path stays shut but any focus FR4 opens on, keyboard focus or a click
-  into a text-field trigger, opens the tooltip and reports `onOpenChange(true)`, so a caller cannot hold it closed.
-  Escape then only reports `onOpenChange(false)`, which the caller already
-  holds, so the tooltip stays until focus or the pointer leaves the trigger or the tooltip, or the caller re-renders with
-  a new `onOpenChange` (FR7).
-- **Escape cannot close a tooltip in another document.** Tooltip listens for
-  Escape only in the page's document and its surface is a manual popover, so a
-  tooltip rendered into an iframe or a Picture-in-Picture window with no layer
-  beneath it is never closed by Escape. WCAG 1.4.13 requires such content to
-  be dismissible (FR6).
-- **The tooltip consumes Escape until AST-003 ships.** A visible, topmost
-  tooltip handles Escape, as `family:overlay-dismissal` records, so the layer
-  underneath it, such as a Dialog, stays open for that press. `spec:AST-003`
-  FR4, accepted and not yet implemented, makes Tooltip passive.
-- **Hover timing does not use the shared hover recognizer.** The tooltip runs
-  its own show and hide timers, without the recognizer's intent group that
-  shows the next trigger at once. `architecture:interaction-modality` INV11 has
-  `useTooltip` take its hover timing from the shared hover recognizer.
-- **A roving trigger may not open on focus.** Under `focusTrigger="auto"` the
-  tooltip reads the tab order only when it attaches the trigger's listeners, so
-  a roving toolbar button or menu item rendered with `tabindex="-1"` shows its
-  tooltip only on mouse hover after it takes keyboard focus, until a change to
-  `focusTrigger`, `isEnabled`, `isOpen`, `delay`, `hideDelay`, or
-  `onOpenChange` re-attaches them. A focusable trigger `auto` does not
-  recognize, such as a `<summary>` or an SVG link, never opens on focus.
-  `architecture:interaction-modality` INV4 keeps hover from being the only
-  discovery path.
-- **A changed trigger loses its wiring.** The tooltip wires its trigger only
-  when the trigger's listeners attach, which repeats only when `focusTrigger`,
-  `isEnabled`, `isOpen`, `delay`, `hideDelay`, or `onOpenChange` changes. Until
-  then, a replaced element child or `anchorRef` target gets no
-  `aria-describedby` and no hover or focus opening, and a trigger that
-  re-renders with its own new `aria-describedby` loses the tooltip id (FR2,
-  AR1).
-- **Script focus after an empty click opens the tooltip.** After a pointer
-  press that focuses nothing, such as a click on page text, script focus on a
-  trigger matches `:focus-visible` and opens the tooltip, though
-  `architecture:interaction-modality` INV1 counts that press as pointer input
-  (FR4).
-- **Mixed text children get no trigger.** Text children that reach React as
-  several strings, such as `Edited {when}`, take neither the text nor the
-  element path: no focusable span or `aria-describedby` is added, and hover and
-  focus never open the tooltip (FR2).
-- **The binding runs some adopted tooltip parts as advisory.** The tooltip
-  pattern binding still runs hiding when focus leaves, showing on hover, and
-  hiding on leave as advisory rows, so a regression there does not fail either
-  binding lane. `spec:AST-020` FR9 makes an adopted expectation required.
-
-## Ownership boundary
-
-**Owns**
-
-- The rendered tooltip surface and content inside that surface (FR1).
-- Trigger wiring and when the tooltip opens and closes for each input
-  (FR2–FR8).
-
-**Does not own / non-goals**
-
-- The trigger element — supplied by the caller or referenced externally and
-  outside Tooltip's owned anatomy.
-- An arrow element — the current implementation renders none.
-- Layer hosting and anchor positioning — owned by `architecture:layer-runtime`;
-  shared Escape ordering — owned by `family:overlay-dismissal`.
-- The `useTooltip` hook's public contract — an uncontracted module; this record
-  covers Tooltip's observable behavior.
-
-## Public concepts
-
-| Concept       | Closed values or states   | Meaning                                                                                        | Availability by variant/orientation/state | Default | Owner               | Stability | Invalid-value behavior           |
-| ------------- | ------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------- | ------- | ------------------- | --------- | -------------------------------- |
-| Focus trigger | `auto`, `always`, `never` | Whether keyboard focus opens the tooltip: on focusable triggers (FR4's gap), always, or never. | Every trigger mode.                       | `auto`  | `component:Tooltip` | Stable    | TypeScript rejects other values. |
-| Touch trigger | `auto`, `tap`, `none`     | Whether a tap opens it: unless the trigger performs its own action, always, or never.          | Touch and pen without hover.              | `auto`  | `component:Tooltip` | Stable    | TypeScript rejects other values. |
-
-## Behavioral and layout contract
-
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Basis                           |
-| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
-| FR1 | The rendered tooltip contains one owned surface, `role="tooltip"`, carrying the `tooltip` target, at most 300 px wide, with the supplied `content` inside; content has no separate target and there is no arrow.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Current source, docs, and tests |
-| FR2 | Trigger wiring: a single string or number child is wrapped in a focusable inline span; element `children` attach to their first element; `anchorRef` attaches to that element. The trigger's `aria-describedby` gains the tooltip id, merged with and later restored to any existing value. Implementation gap: the wiring runs only when the trigger's listeners attach, so a trigger element replaced after mount, or a trigger whose own `aria-describedby` changes, loses it until a re-render re-attaches them (Current-state impact).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Current source and tests        |
-| FR3 | On a hover-capable pointer, entering the trigger opens after `delay` ms; leaving closes after `hideDelay` ms. With `hideDelay` 0 a short bridge lets the pointer move onto the surface without closing it, and the surface stays open while hovered.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | WCAG 1.4.13; tests              |
-| FR4 | Focus that matches `:focus-visible` opens the tooltip per `focusTrigger`: keyboard focus, programmatic focus that follows keyboard input (AR4), pointer focus on a text-entry trigger, which browsers mark focus-visible, and programmatic focus on a text-entry trigger unless a finger or pen pressed that trigger and the last input was a pointer press, and on any other trigger unless the last input was a pointer (after keyboard input, as in AR4, or before any input). Implementation gap: script focus after a pointer press that focused nothing opens it, because the hook reads `:focus-visible` alone (Current-state impact). Focus a tap leaves behind, and other pointer focus, does not. Focus leaving the trigger schedules the hide as a pointer leave does. Under `focusTrigger="auto"`, focus opens the tooltip on any focusable trigger. Implementation gap: `auto` recognizes only an explicit non-negative `tabindex`, HTML links, buttons, form fields, and editable elements, so a `<summary>` or an SVG link never opens on keyboard focus; and it reads the tab order only when it attaches the trigger's listeners, on mount and again when `focusTrigger`, `isEnabled`, `isOpen`, `delay`, `hideDelay`, or `onOpenChange` changes, so a trigger rendered with `tabindex="-1"` does not open on focus until such a re-render follows its move into the tab order (Current-state impact). | Current source and tests        |
-| FR5 | On touch, a completed tap opens per `touchTrigger` when the finger lifts; a touch that becomes a scroll, or a press the browser does not count as a tap, does not open it. A second tap on the trigger, a tap outside, or a scroll starting outside closes it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Current source and tests        |
-| FR6 | Escape closes a visible tooltip; Escape during text composition is ignored. Escape routing follows `family:overlay-dismissal`: a visible topmost tooltip in the page handles that Escape, so a layer underneath stays open for that press. Implementation gap: a tooltip rendered into another document, such as an iframe or a Picture-in-Picture window, with no layer beneath it is never closed by Escape (Current-state impact). `spec:AST-003` FR4, accepted and not yet implemented, makes Tooltip passive (Current-state impact). Pressing an uncontrolled tooltip's trigger closes it; a press that focuses a text-entry trigger reopens it through FR4.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | WCAG 1.4.13; tests              |
-| FR7 | `isOpen` forces the tooltip shown or hidden, and `isOpen={true}` suppresses hover and focus hiding; a controlled tooltip answers Escape by calling `onOpenChange(false)` without hiding, and is not closed by pressing the trigger. `isDefaultOpen` opens it on mount, still dismissible. Implementation gap: with `isOpen={false}`, any focus FR4 opens on, keyboard focus or a click into a text-field trigger, still opens the tooltip and reports `onOpenChange(true)`, and Escape then only reports `onOpenChange(false)`, so it stays until focus or the pointer leaves the trigger or the tooltip, or the caller re-renders with a new `onOpenChange` (Current-state impact). `isEnabled={false}` disables triggers and drops a pending open.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Current source and tests        |
-| FR8 | `onOpenChange` reports each show and hide. `hasHoverIndication` (`auto`: a single string or number child) adds a hover cue to the inline trigger.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Current source and tests        |
-
-### Allowed variation
-
-- Supplied content may vary without adding a Tooltip-owned child target.
-
-### Representative states
-
-- The owned anatomy is unchanged across wrapped-trigger and external-anchor
-  modes; the trigger remains outside it.
-
-### Transformation and precedence order
-
-- **ORD1 — Open state.** `isOpen`, then the input triggers, apart from FR7's
-  focus gap.
-
-### Performance and resources
-
-- **PR1 — Timers.** A pending show is dropped when triggers are disabled or the
-  component unmounts.
-
-## Accessibility contract
-
-- **AR1 — Description.** The trigger's `aria-describedby` names the tooltip
-  (FR2), apart from FR2's changed-trigger gap.
-- **AR2 — Content on hover or focus.** The tooltip is hoverable, dismissible,
-  and persistent per WCAG 1.4.13 (FR3, FR6), except FR6's other-document gap and
-  FR7's held-closed Escape gap.
-- **AR3 — Focus modality.** Only `:focus-visible` focus opens it (FR4).
-- **AR4 — Focus return.** When closing a popover from the keyboard returns
-  focus to a trigger that carries a tooltip, the tooltip shows for that focus
-  without an error.
-- **AR5 — Tooltip pattern.** The record adopts the APG tooltip pattern's parts:
-  `role="tooltip"`, the trigger's `aria-describedby`, showing on keyboard focus
-  and hiding when focus leaves, Escape dismissal, and showing on hover and
-  hiding on leave (FR1–FR4, FR6), with FR6's other-document gap and FR7's
-  held-closed Escape gap as the exceptions to Escape dismissal. Hiding when focus leaves, showing on hover,
-  and hiding on leave go beyond the required parts `spec:AST-020` FR15 adopts
-  and are this record's named exception, kept because they ship.
-
-## Design relationships
-
-| Anatomy or state | Design requirement                                  | Representation authority       | Hierarchy role | Component contract |
-| ---------------- | --------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
-| Tooltip surface  | Presents the current painted overlay surface.       | Current source and public docs | Supporting     | FR1                |
-| Tooltip text     | Presents supplied content within the owned surface. | Current source and public docs | Prominent      | FR1                |
-
-The trigger is caller-owned and outside this anatomy. The current implementation
-has no arrow element.
-
-### Theming anatomy
-
-<!-- anatomy-theming:v1 -->
-
-```json
-{
-  "Tooltip surface": {"target": "tooltip"},
-  "Tooltip text": {"inherits": "tooltip"}
-}
-```
-
-## Family and system relationships
-
-- `family:overlay-dismissal` owns Escape routing and topmost handling.
-- `architecture:layer-runtime` owns hosting and positioning.
-- `architecture:interaction-modality` owns the focus-visible modality FR4 uses
-  and, through INV11, the hover timing source for FR3.
-- `architecture:component-theming-surface` owns the `tooltip` target.
-
-## Verification map
-
-| Contract            | Verification                                                                                                                                     | Representative states                               | Mutation or failure expectation                                                                                                                                     | Audit section                 |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
-| FR1                 | `Tooltip.test.tsx` role/content suite                                                                                                            | Rendered surface and supplied content               | Removing the surface or content fails existing tooltip role and text assertions.                                                                                    | `audit:Tooltip/anatomy`       |
-| FR2–FR8             | `Tooltip.test.tsx`; `useTooltip.test.tsx`                                                                                                        | Hover, focus, tap, Escape, controlled, default open | Wrong open or close for an input fails.                                                                                                                             | `audit:Tooltip/behavior`      |
-| AR1–AR4             | `Tooltip.a11y.test.tsx`; `Tooltip.a11y.chromium.spec.ts`; `TooltipHoverBridge.a11y.chromium.spec.ts`; `TooltipFocusReturn.a11y.chromium.spec.ts` | Real-browser hover bridge and focus return          | A tooltip that vanishes on the way to it or strands focus fails.                                                                                                    | `audit:Tooltip/accessibility` |
-| AR5                 | `Tooltip.a11y.test.tsx`; `Tooltip.a11y.chromium.spec.ts`                                                                                         | Wrapped, text, anchor, and hook triggers            | A lost role, description, keyboard-focus show, or Escape dismissal fails; focus-leave hide, hover show, and leave hide run as advisory rows (Current-state impact). | `audit:Tooltip/accessibility` |
-| FR5                 | `Tooltip.test.tsx` touch suite; `TouchTrigger.a11y.chromium.spec.ts`                                                                             | Tap open, scroll, second tap, tap outside           | A tap that fails to open or close as stated fails.                                                                                                                  | `audit:Tooltip/behavior`      |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                                    | Canonical anatomy and current target                | Missing, extra, prefixed, or stale mappings fail repository validation.                                                                                             | `audit:Tooltip/theming`       |
-
-Read from source, with no focused test yet:
-
-- FR2: a single number child, and restoring a trigger's own existing
-  `aria-describedby`.
-- FR6: a press that focuses a text-entry trigger reopening it, and Escape in
-  another document.
-- FR7: `isOpen={true}` suppressing focus hiding.
-- FR1: the 300 px maximum width, the `tooltip` target, and the absence of an
-  arrow.
-- FR4: `focusTrigger="always"`, `"never"`, and when `"auto"` reads the tab order,
-  programmatic focus on a text-entry trigger after pointer input opening it,
-  and not after a finger or pen pressed it when the last input was a pointer press, pointer focus on a text field
-  opening the tooltip, programmatic focus before any input, or after a pointer press onto a trigger that is not a text field, other pointer focus not opening it, and focus leaving the trigger
-  hiding it.
-- FR8: `hasHoverIndication`.
-
-## Decision log
-
-No component-local decision is recorded.
-
-## Open questions
-
-None.
-
-## Content boundary
-
-This file does not duplicate consumer prop tables, examples, layer-system rules,
-implementation steps, or system rules. It links to their owners.