@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/Timer/Timer.spec.md

@@ -1,215 +0,0 @@
----
-schema_version: 3
-template_version: 5
-kind: component
-id: component:Timer
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-09-22
-owners: [cixzhang]
-review_triggers: [public-api, behavior, theming, accessibility, react-runtime]
-verified_by:
-  [
-    packages/core/src/Timer/Timer.test.tsx,
-    packages/core/src/theme/themingTargets.test.ts,
-    scripts/check-knowledge.mjs,
-  ]
-modules: []
-families: []
-design_specs: []
-architecture:
-  [
-    architecture:public-component-api,
-    architecture:component-theming-surface,
-    architecture:react-component-runtime,
-  ]
-contributing: []
-system_specs:
-  [
-    spec:AST-002/DEC-1,
-    spec:AST-037/DEC-1,
-    spec:AST-037/DEC-2,
-    spec:AST-037/DEC-3,
-  ]
----
-
-# Timer component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                                                                                      |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | `Timer`, `TimerProps`, `TimerFormat`, optional `startTime` Unix milliseconds, `elapsed` or `clock` format, Timestamp-equivalent `type`, `size`, `color`, and `weight`, `<time>` ref, and `BaseProps<HTMLTimeElement>`.                                                        |
-| Behavior                | One semantic duration uses a standardized seconds-to-hours ladder and updates its owned DOM node without React tick renders; elapsed output drops to minute cadence after one hour.                                                                                           |
-| End-user impact         | People watching active work see a stable, consistent duration without unnecessary timer work competing with the surrounding interface.                                                                                                                                        |
-| Builder impact          | Zero-config starts on mount with Timestamp's supporting typography; callers choose only an earlier origin, standard format, or standard typography override.                                                                                                                  |
-| Compatibility/readiness | Additive first release implementing current `spec:AST-037`; no existing API or behavior changes.                                                                                                                                                                              |
-| Review checks           | Reject custom formatters/cadence, state-driven ticks, callback-count drift, post-hour elapsed second wakes, typography divergence from Timestamp, leaked resources, negative output, lost passthrough/ref behavior, unsolicited live announcements, or extra anatomy/targets. |
-| Governing rules         | `spec:AST-037`; `architecture:public-component-api`; `architecture:react-component-runtime`; `architecture:component-theming-surface`.                                                                                                                                        |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-Timer is the stable Core projection of `spec:AST-037`. It presents a standardized
-elapsed duration for active work while keeping clock ticks outside React's render
-lifecycle. Its typography surface and defaults match Timestamp so the two temporal
-content components behave consistently.
-
-## Compatibility and migration
-
-- Released default preserved: `not yet released`
-- Compatibility class: additive component and type exports
-- Controlled/uncontrolled behavior: not applicable
-- Migration decision: `spec:AST-037/DEC-1`, `spec:AST-037/DEC-2`, and
-  `spec:AST-037/DEC-3`
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Ownership boundary
-
-**Owns**
-
-- Elapsed calculation from mount or a finite caller origin.
-- The `elapsed` and `clock` representation ladders and their visible precision.
-- One `<time>` element, its visible value, synchronized ISO duration, and timer
-  resource lifecycle.
-- Avoiding React update commits for clock ticks.
-- Timestamp-equivalent `type`, `size`, `color`, and `weight` behavior.
-- The `timer` theming target on the Text wrapper.
-
-**Does not own / non-goals**
-
-- Loading indicators, waiting copy, status, or visibility — product composition.
-- Dates, relative calendar language, time zones, or absolute instants — Timestamp.
-- Pause, resume, countdown, deadlines, alarms, laps, sub-second precision, custom
-  formatters, or caller-controlled scheduling cadence.
-- Automatic live-region announcements.
-
-Countdown is deferred to a later contract. The standard formatting and scheduling
-helpers remain direction-independent so that extension does not require replacing
-the current format API.
-
-## Public concepts
-
-| Concept         | Closed values or states                   | Meaning                                              | Availability | Default                                                                        | Owner             | Stability | Invalid-value behavior                                     |
-| --------------- | ----------------------------------------- | ---------------------------------------------------- | ------------ | ------------------------------------------------------------------------------ | ----------------- | --------- | ---------------------------------------------------------- |
-| Elapsed origin  | Mount time or finite `startTime`          | Unix-millisecond origin for elapsed duration         | Always       | Mount time                                                                     | `component:Timer` | Stable    | Non-finite values fall back to mount time                  |
-| Duration format | `elapsed`, `clock`                        | Compact units or stopwatch notation                  | Always       | `elapsed`                                                                      | `component:Timer` | Stable    | Types reject other values; runtime falls back to `elapsed` |
-| Typography      | `type`, `size`, `color`, `weight`         | Same Text-backed surface and resolution as Timestamp | Always       | Timestamp defaults: supporting type, secondary color, type-derived size/weight | Timestamp/Text    | Stable    | Existing Text type behavior                                |
-| Time surface    | `<time>` with visible text and `dateTime` | Semantic elapsed duration and time-element props/ref | Always       | Selected format's zero value and `PT0S` before client synchronization          | `component:Timer` | Stable    | Timer-owned `dateTime` wins                                |
-
-## Behavioral and layout contract
-
-| ID   | Candidate invariant                                                                                                                                                                                                                                                                | Basis                        | Draft review state |
-| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ------------------ |
-| FR1  | Timer MUST render one `<time>` element with selected-format text and matching non-negative ISO 8601 duration.                                                                                                                                                                      | `spec:AST-037` FR1, FR3, FR5 | Settled            |
-| FR2  | Omitted or non-finite `startTime` MUST use the mount origin; a finite value MUST use that caller origin.                                                                                                                                                                           | `spec:AST-037` FR2           | Settled            |
-| FR3  | Ticks MUST recompute from the clock and origin, directly update the owned node, and produce zero React update commits.                                                                                                                                                             | `spec:AST-037` FR3–FR4       | Settled            |
-| FR4  | Prop changes MUST take effect without remounting or duplicate resources; every setup MUST clean up its resource.                                                                                                                                                                   | `spec:AST-037` FR6–FR7       | Settled            |
-| FR5  | `type`, `size`, `color`, `weight`, `xstyle`, `className`, and `style` MUST resolve on the Text wrapper exactly as Timestamp does; other admitted DOM, data, ARIA, and event props and the ref MUST reach `<time>`.                                                                 | `spec:AST-037` FR8           | Settled            |
-| FR6  | Timer MUST NOT add live-region semantics by default.                                                                                                                                                                                                                               | `spec:AST-037` FR9           | Settled            |
-| FR7  | The Text wrapper MUST carry exactly the `timer` target for this component.                                                                                                                                                                                                         | `spec:AST-037` FR10          | Settled            |
-| FR8  | Initial markup MUST use the selected format's zero value and `PT0S` without exposing a clock read in rendered markup.                                                                                                                                                              | `spec:AST-037` FR11          | Settled            |
-| FR9  | `elapsed` and `clock` MUST update on second boundaries below one hour; `elapsed` MUST update on minute boundaries at or above one hour while `clock` remains second-precise. A future origin MUST schedule toward its first visible change rather than waking each second at zero. | `spec:AST-037` FR12          | Settled            |
-| FR10 | Timer SHOULD skip DOM writes while the represented text and duration are unchanged.                                                                                                                                                                                                | `spec:AST-037` FR13          | Settled            |
-
-### Allowed variation
-
-- **AV1 — Scheduling mechanism.** The private browser scheduling mechanism may
-  change while format-aware cadence, clock derivation, no-render ticks, and
-  complete cleanup remain true.
-- **AV2 — Composition.** Callers may use the supported typography and styling
-  inputs without changing timing behavior.
-
-### Representative states
-
-| State            | Required invariant                                             | Allowed variation                       |
-| ---------------- | -------------------------------------------------------------- | --------------------------------------- |
-| Initial elapsed  | `0s` and `PT0S` on one `<time>`                                | Root props and styling                  |
-| Initial clock    | `0:00` and `PT0S` on one `<time>`                              | Root props and styling                  |
-| Seconds/minutes  | `34s`, `2m 08s`, `0:34`, or `2:08` with whole-second semantics | Finite elapsed value                    |
-| Hour-scale       | `1h 02m` at minute cadence or `1:02:33` at second cadence      | Format                                  |
-| Delayed callback | Catch up to clock without accumulated drift                    | Delay length                            |
-| Prop update      | New origin or format applies on the same `<time>`              | Parent render cause                     |
-| Replay/unmount   | Each acquired resource is released                             | Development replay count                |
-| Typography       | Timestamp defaults or explicit Text-family overrides           | Supported type, size, color, and weight |
-
-### Transformation and precedence order
-
-- **ORD1 — Resolve → calculate → clamp → floor to visible precision → format →
-  write → schedule next visible boundary.** Apply the pipeline from `spec:AST-037`
-  to visible text and machine-readable duration.
-- **ORD2 — Timestamp styling split.** Typography, `xstyle`, `className`, `style`,
-  and the `timer` target compose on the Text wrapper. Time-element props and the ref
-  compose on `<time>`; Timer owns `dateTime`.
-
-### Performance and resources
-
-- **PR1 — No tick renders.** Advancing time produces zero React update commits.
-- **PR2 — One resource.** Each mounted Timer owns at most one active timer resource,
-  and each setup cleanup releases its resource.
-- **PR3 — Visible cadence.** Elapsed output at or above one hour does not wake for
-  hidden second changes; clock output remains second-precise.
-- **PR4 — Bounded writes.** Unchanged represented text and duration are not rewritten.
-
-## Accessibility contract
-
-- **AR1 — Semantic duration.** The `<time>` element exposes the current non-negative
-  ISO 8601 duration at the same precision as its visible output.
-- **AR2 — Quiet by default.** No role or `aria-live` value is added automatically;
-  deliberate caller ARIA passes through.
-- **AR3 — Perceivable text.** The formatted duration remains real text content.
-
-## Design relationships
-
-| Anatomy or state | Design requirement                                                                                                 | Representation authority                   | Hierarchy role | Component contract      |
-| ---------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ | -------------- | ----------------------- |
-| Elapsed time     | One stable inline duration with Timestamp-equivalent supporting typography by default and standard Text overrides. | `spec:AST-037/DEC-1`, `spec:AST-037/DEC-3` | Supporting     | FR1, FR3, FR5, AR1, AR3 |
-
-### Theming anatomy
-
-<!-- anatomy-theming:v1 -->
-
-```json
-{
-  "Elapsed time": {"target": "timer"}
-}
-```
-
-## Family and system relationships
-
-- Timer and Timestamp are temporal Text-family content components: Timer owns
-  durations; Timestamp owns instants. Their typography API and defaults match.
-- `spec:AST-037` owns the public behavior, API, accessibility, performance, and
-  first-Core-admission decisions projected here.
-- `architecture:public-component-api` owns exports, BaseProps, styling, ref, and
-  caller-choice rules.
-- `architecture:react-component-runtime` owns Effect and resource lifecycle.
-- `architecture:component-theming-surface` owns target qualification.
-
-## Verification map
-
-| Contract                    | Verification                                                                     | Representative states                                                                                                        | Mutation or failure expectation                                                                                                                                            | Audit section               |
-| --------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
-| FR1–FR4, FR8–FR10, AR1, AR3 | `Timer.test.tsx` controlled-clock tests                                          | Initial formats, origin variants including future scheduling, delayed callback, format change, second/minute/hour boundaries | State ticks, callback accumulation, wrong ladder/padding, negative values, needless pre-origin wakes, stale semantics, wrong cadence, or clock-derived initial markup fail | `audit:Timer/behavior`      |
-| FR3, PR1                    | React Profiler commit-count test                                                 | Several ticks                                                                                                                | A state-based implementation adds update commits and fails                                                                                                                 | `audit:Timer/performance`   |
-| FR4, PR2                    | Resource spies under rerender, StrictMode, and unmount                           | Setup, dependency change, replay, cleanup                                                                                    | Duplicate or leaked resources fail counts                                                                                                                                  | `audit:Timer/resources`     |
-| FR5                         | Public import, Timestamp-default typography, overrides, BaseProps, and ref tests | Default and explicit typography, ref, event, ARIA, class, style                                                              | Missing export, styling divergence, or dropped input fails                                                                                                                 | `audit:Timer/api`           |
-| FR6, AR2                    | Accessibility attribute tests                                                    | Default and deliberate caller ARIA                                                                                           | Unsolicited live semantics or dropped ARIA fails                                                                                                                           | `audit:Timer/accessibility` |
-| FR7                         | `themingTargets.test.ts` and `scripts/check-knowledge.mjs`                       | One wrapper target                                                                                                           | Missing, extra, or misplaced target fails                                                                                                                                  | `audit:Timer/theming`       |
-
-## Decision log
-
-No additional decision. This component projects `spec:AST-037` without widening it.
-
-## Open questions
-
-None.
-
-## Content boundary
-
-This file does not duplicate consumer examples, implementation code, private
-scheduling mechanics, measurements, or system rules. It links to their owners.

package/src/Timestamp/Timestamp.spec.md

@@ -1,246 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:Timestamp
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-27
-owners: [cixzhang]
-review_triggers: [public-api, behavior, layout, theming, accessibility]
-verified_by:
-  [
-    packages/core/src/hooks/useClipboard.test.tsx,
-    .github/visual-baseline/manifest.json,
-    packages/core/src/Timestamp/Timestamp.test.tsx,
-    packages/core/src/Timestamp/tooltipEntries.test.ts,
-    packages/core/src/theme/themingTargets.test.ts,
-    apps/storybook/stories/Timestamp.stories.tsx,
-    scripts/check-knowledge.mjs,
-  ]
-modules: []
-families: []
-design_specs: []
-architecture:
-  [
-    architecture:component-theming-surface,
-    architecture:internationalization,
-    architecture:public-component-api,
-    architecture:react-component-runtime,
-  ]
-contributing: []
-system_specs: [spec:AST-009, spec:AST-085]
----
-
-# Timestamp component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                                           |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | A `time` element for a `value` (Unix seconds, milliseconds, or ISO 8601) in one of twelve `format`s, with optional live updates, time-zone suffix, and a copyable hover card.                                                      |
-| Behavior                | Relative output carries the full absolute date as its default accessible name; relative output, or configured `tooltipEntries`, attach a keyboard-reachable hover card of copyable rows.                                           |
-| End-user impact         | Readers see compact or exact times in their locale; screen-reader users hear the full date and time zone; keyboard users can open and copy the exact time.                                                                         |
-| Builder impact          | None; the record describes shipped behavior.                                                                                                                                                                                       |
-| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Three implementation gaps are listed under Current-state impact.                                                                                        |
-| Review checks           | Reject a relative timestamp without the full absolute name when the caller names nothing, a hover card without a tab stop, a change that makes more server markup depend on the server's zone, or a crash on an unparseable value. |
-| Governing rules         | `architecture:internationalization/INV4,INV8,INV10`; `architecture:react-component-runtime/INV1,INV3,INV5`; `architecture:public-component-api/INV5,INV6,INV8`.                                                                    |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-Timestamp shows one instant as human-readable text with machine-readable
-semantics. It owns choosing and formatting the display, keeping relative
-output current, the accessible name, and the hover card that reveals and copies
-the exact time.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`
-- Compatibility class: records shipped behavior; no public prop, default, DOM,
-  or styling output changes
-- Controlled/uncontrolled behavior: not applicable; the current clock is
-  internal state
-- Migration decision: none
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Current-state impact
-
-- **Focus lost when the card attaches (FR6, AR3).** While the card module
-  loads, a fallback `time` with the tab stop renders; when the card attaches it
-  replaces that element, so keyboard focus placed on it falls to the page body
-  and no card opens, where `spec:AST-085` FR4 keeps focus on a control that
-  stays available.
-- **Card fails the description-list structure (FR7).** Once any row is
-  copyable, every row puts an action cell, a `div` (empty on read-only rows),
-  inside its row group in the card's `dl`, so the open card fails the
-  `definition-list` structure check (WCAG 2.2 1.3.1); the default card always
-  has a copyable row. A card with no labelled rows,
-  the default card included, also renders each row as a lone `dd` with no
-  `dt`, so its values have no names.
-- **Absolute formats depend on the server's zone (FR3).** An absolute format
-  other than `unix_seconds` renders in the host's time zone, so the same instant reads "Mar 25" from a
-  UTC server and "Mar 26" from a Tokyo server, and a viewer in another zone
-  gets a hydration text mismatch.
-
-## Ownership boundary
-
-**Owns**
-
-- The `time` element, its `datetime` attribute, and the Text wrapper carrying
-  the `timestamp` target.
-- Value parsing, format selection, formatting, the time-zone suffix, and live
-  updates.
-- The accessible name of relative output.
-- The hover card's rows, layout, copy buttons, and copy announcement.
-
-**Does not own / non-goals**
-
-- Hover card opening, placement, and dismissal — owned by HoverCard.
-- Typography — delegated to `component:Text`.
-- Locale and calendar resolution — owned by `architecture:internationalization`
-  helpers.
-- Clipboard writing and its live-region announcement mechanics — owned by the
-  shared clipboard hook.
-
-## Public concepts
-
-| Concept         | Closed values or states                                                                                                                                          | Meaning                                                   | Availability by variant/orientation/state   | Default  | Owner                 | Stability | Invalid-value behavior                                         |
-| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------- | -------- | --------------------- | --------- | -------------------------------------------------------------- |
-| Value           | Unix seconds (below 10¹²), Unix milliseconds, or an ISO 8601 string                                                                                              | The instant shown.                                        | Always                                      | Required | `component:Timestamp` | Stable    | An unparseable value renders nothing and warns in development. |
-| Format          | `relative`, `relative_short`, `auto`, `date`, `date_long`, `date_weekday`, `date_time`, `time`, `system_date`, `system_date_time`, `system_time`, `unix_seconds` | How the instant is written.                               | Always                                      | `auto`   | `component:Timestamp` | Stable    | TypeScript rejects other values.                               |
-| Hover card rows | default (one copyable full-date row); configured `tooltipEntries`                                                                                                | What the hover card shows; each row may opt into copying. | Relative output, or any output with entries | default  | `component:Timestamp` | Stable    | An empty entry list counts as no configuration.                |
-| Live            | on; off                                                                                                                                                          | Whether relative output refreshes.                        | Relative output                             | off      | `component:Timestamp` | Stable    | —                                                              |
-
-## Behavioral and layout contract
-
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Basis                    |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| FR1 | Timestamp renders a Text element (default `type="supporting"`, `color="secondary"`, with `size` and `weight` passed through) carrying the `timestamp` target, which reflects the resolved format beside Text's type and color reflection; inside it an inline `time` element inherits the typography and carries the instant's ISO 8601 `datetime`. An unparseable value renders nothing and logs a development warning.                                                                                                                                                                                                                                                                                                                                                                                                                                       | Current source and tests |
-| FR2 | `auto` shows `relative` when the instant is within `autoThreshold` seconds of now (default seven days) and `date_time` otherwise. `relative` uses the locale's long relative phrase and `relative_short` its narrow phrase; a value a few seconds in the future reads as "now". Absolute formats use the shared instant formatter in the provider locale with Gregorian years; `system_*` formats are machine-readable, and `unix_seconds` is zone-independent. `isTimezoneShown` appends the zone abbreviation to `date_time` and `time` only.                                                                                                                                                                                                                                                                                                                | Current source and tests |
-| FR3 | Server markup does not depend on the server's time zone and hydrates without a mismatch. A format that needs the clock renders `date_time` in UTC with the zone shown until the client can read the clock; the client then shows the resolved format without committing the UTC placeholder. Implementation gap: absolute formats other than `unix_seconds` render in the host's time zone, so their server markup depends on the server's zone and hydrating it in another zone produces a text mismatch (Current-state impact).                                                                                                                                                                                                                                                                                                                              | Current source and tests |
-| FR4 | With `isLive` and relative output, the clock refreshes every second under a minute old, every 30 seconds under an hour, every minute under a day, and every five minutes beyond; the timer is cleared on unmount or when the inputs change. Locale changes update the output live.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Current source and tests |
-| FR5 | Relative output is named by the full absolute date and the long time-zone name unless a caller names the element; absolute output adds no name. A caller's explicit `aria-label` reaches the element (`architecture:public-component-api` INV5).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Current source and tests |
-| FR6 | When `hasTooltip` is true and the output is relative or `tooltipEntries` is non-empty, a lazily loaded HoverCard named "Timestamp details" attaches above the timestamp, opening on hover and on keyboard focus; the `time` element gains `tabIndex={0}`. Otherwise no card renders and no tab stop is added. Focus placed on the timestamp stays there when the card attaches (`spec:AST-085` FR4). Implementation gap: while the card module loads, a fallback `time` with the tab stop renders, and attaching the card replaces it, so focus placed on it falls to the page body and no card opens (Current-state impact).                                                                                                                                                                                                                                  | Current source and tests |
-| FR7 | The card is a description list in a grid: an optional label column (present when any row has a label), the value column, and a trailing action column (present when any row is copyable). Without entries it has one copyable row with the full absolute time in the viewer's zone. Each configured entry is one row in the given order, rendered in its own time zone and format, read-only unless `isCopyable`. An unknown time zone does not crash. A description list holds only name-value groups (WCAG 2.2 1.3.1). Implementation gaps: once any row is copyable, every row carries an action-cell `div` inside its row group (empty on read-only rows), so the open card fails the `definition-list` structure check, and a card with no labelled rows, the default card included, renders each row as a lone `dd` with no `dt` (Current-state impact). | Current source and tests |
-| FR8 | A copy button is a small ghost IconButton on the `timestamp-copy-button` target, named "Copy {value}" with a "Copy" tooltip; activating it writes the row's value to the clipboard, switches to a check icon and the "Copied" name and tooltip for 1.5 seconds, and announces "Copied" politely. A clipboard rejection does nothing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Current source and tests |
-| FR9 | `ref`, `data-testid`, and other supported DOM, ARIA, data, and event props reach the `time` element; `xstyle`, `className`, and `style` reach the Text wrapper. A caller `aria-labelledby` names the element in place of FR5's name. A caller's explicit `tabIndex` reaches the element (`architecture:public-component-api` INV5).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Current source and tests |
-
-### Allowed variation
-
-- **AV1 — Locale wording.** Phrases, month names, and zone names follow the
-  provider locale.
-- **AV2 — Theme paint.** A theme may restyle `timestamp` per format, type, and
-  color, and `timestamp-copy-button`, without changing the output text.
-
-### Representative states
-
-| State                 | Required invariant                                                                                                                                        | Allowed variation |
-| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
-| Relative, recent      | Relative phrase; full-date name; tab stop; hover card with one copyable row.                                                                              | Locale.           |
-| Auto, old             | `date_time`; no name; no card unless entries are configured.                                                                                              | Threshold.        |
-| Absolute with entries | Card attached with configured rows; tab stop; no added name.                                                                                              | Entries.          |
-| Server render         | Markup identical across server zones; clock-dependent formats show UTC `date_time` with zone (absolute formats use the server's zone today, the FR3 gap). | —                 |
-| Live                  | Relative phrase refreshes at the tier's interval.                                                                                                         | —                 |
-| Unparseable           | Nothing rendered; development warning.                                                                                                                    | —                 |
-| `hasTooltip={false}`  | No card and no tab stop, even with entries.                                                                                                               | —                 |
-
-### Transformation and precedence order
-
-- **ORD1 — Display format.** Clock pending → UTC `date_time`; else `auto` →
-  relative or `date_time` by threshold; else `format`.
-- **ORD2 — Card rows.** Non-empty `tooltipEntries` → the default full-date row.
-- **ORD3 — Time element attributes.** `datetime` and `data-testid` are set,
-  then caller props; the relative name and the card's tab stop apply only
-  where the caller sets no `aria-label` or `tabIndex`.
-
-### Performance and resources
-
-- **PR1 — Bounded work.** Only relative output with `isLive` runs a timer, at
-  most one per instance, cleared on change or unmount; the hover card module
-  loads only when a card is attached; copy state exists only for copyable rows.
-
-## Accessibility contract
-
-- **AR1 — Machine-readable instant.** The `time` element carries the ISO 8601
-  instant in `datetime`.
-- **AR2 — Full name for relative output.** Relative output is named by the full
-  absolute date with the spelled-out time zone (WCAG 2.2 3.1.4).
-- **AR3 — Keyboard-reachable card.** While a card is attached the timestamp is
-  a tab stop and the card opens on focus; the trigger carries no
-  `aria-expanded`. Without a card there is no tab stop. Implementation gap:
-  focus placed on the timestamp before the card module loads is lost when the
-  card attaches (FR6). The popup relationship sits on the Text wrapper rather
-  than the focused `time` and is not contracted.
-- **AR4 — Copy feedback.** Copy buttons are named with their value, and a copy
-  is announced politely.
-
-## Design relationships
-
-| Anatomy or state | Design requirement                                                   | Representation authority | Hierarchy role | Component contract |
-| ---------------- | -------------------------------------------------------------------- | ------------------------ | -------------- | ------------------ |
-| Formatted text   | The instant in compact or exact form, in supporting type by default. | Current source and docs  | Prominent      | FR1–FR5            |
-| Hover card       | A copyable card with the exact time or configured rows.              | Current source and docs  | Supporting     | FR6, FR7, AR3      |
-| Hover card row   | An optional label beside one rendering of the instant.               | Current source and docs  | Supporting     | FR7                |
-| Copy button      | Copies one row's value with brief confirmation.                      | Current source and docs  | Supporting     | FR8, AR4           |
-
-### Theming anatomy
-
-<!-- anatomy-theming:v1 -->
-
-```json
-{
-  "Formatted text": {"target": "timestamp"},
-  "Hover card": {
-    "delegatesTo": {"owner": "component:HoverCard", "target": "hover-card"}
-  },
-  "Hover card row": {
-    "none": {
-      "reason": "reachability-gap: rows render inside the hover card content without a component-owned class"
-    }
-  },
-  "Copy button": {"target": "timestamp-copy-button"}
-}
-```
-
-## Family and system relationships
-
-- `architecture:internationalization` owns locale resolution, live locale
-  changes, the shared formatter, and Gregorian defaults; FR2 and FR4 rely on
-  them.
-- `architecture:react-component-runtime` owns valid initial render and timer
-  cleanup; FR3 and FR4 apply them.
-- HoverCard owns the card surface; Timestamp supplies its content, name, and
-  trigger focusability.
-
-## Verification map
-
-| Contract            | Verification                                                                                                         | Representative states                                          | Mutation or failure expectation                                                                                                                                                                                                                                                                                                                                                                                                                           | Audit section              |
-| ------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
-| FR1, FR2            | `Timestamp.test.tsx` format, auto, locale, and invalid-value tests; stable visual baseline `core-timestamp--default` | Every format; thresholds; locales; unparseable values; default | A wrong phrase, a crossed tier, a non-Gregorian year, a missing `time` element or `datetime`, a crash, or a missing development warning for an unparseable value fails; a changed default type or color comes back changed for review. Gap: no test asserts the `timestamp` target or its format reflection.                                                                                                                                              | `audit:Timestamp/behavior` |
-| FR3                 | `Timestamp.test.tsx` server-rendering suite                                                                          | Server zones; hydration                                        | Zone-dependent markup, a hydration mismatch, or a committed placeholder fails. Gap: no test covers an absolute format rendered on a server in another zone.                                                                                                                                                                                                                                                                                               | `audit:Timestamp/behavior` |
-| FR4, PR1            | `Timestamp.test.tsx` live-update and locale tests                                                                    | Live relative output; locale change                            | A missing refresh or a stale locale fails. Gap: the per-tier refresh intervals and the timer cleanup on unmount or input change have no automated check.                                                                                                                                                                                                                                                                                                  | `audit:Timestamp/behavior` |
-| FR5, AR2            | `Timestamp.test.tsx` naming tests                                                                                    | Relative, absolute, time-zone spelling                         | A missing or short-zone name, or a name on absolute output, fails. A caller `aria-label` replaced on relative output fails.                                                                                                                                                                                                                                                                                                                               | `audit:Timestamp/a11y`     |
-| FR6, AR3            | `Timestamp.test.tsx` keyboard-reachability suite                                                                     | Relative, absolute, disabled, entries removed                  | A missing tab stop, `aria-expanded` on the trigger, or a stray tab stop fails. The aria-expanded test also pins `aria-haspopup` on the Text wrapper, which is current behavior, not contract. Gap: no test covers focus on the timestamp while the card module loads, or `aria-controls`.                                                                                                                                                                 | `audit:Timestamp/a11y`     |
-| FR7, FR8, AR4       | `Timestamp.test.tsx` hover-card suites; `tooltipEntries.test.ts`; `useClipboard.test.tsx`                            | Default row, entries, copyable rows, unknown zone              | A wrong row count or order, an unpaired label, a copy button on a read-only row, a wrong copied value, a missing copied state, or a missing announcement fails. Gap: no check runs the `definition-list` structure rule on the open card (the recorded gap); the grid columns and the 1.5-second reset have no automated check; `useClipboard.test.tsx` covers the clipboard-rejection no-op. The lone-`dd` rows of a label-less card are also unchecked. | `audit:Timestamp/behavior` |
-| FR9                 | `Timestamp.test.tsx` ref, test-id, and pass-through tests                                                            | Ref, test id, caller props                                     | A ref, test id, or caller prop missing from the `time` element fails. A caller `tabIndex` replaced while a card is attached fails. Gap: no test asserts that `xstyle`, `className`, and `style` reach the Text wrapper, or covers a caller `aria-labelledby`.                                                                                                                                                                                             | `audit:Timestamp/behavior` |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                        | Consumer anatomy, targets, HoverCard delegate                  | Missing, extra, or stale mappings fail repository validation.                                                                                                                                                                                                                                                                                                                                                                                             | `audit:Timestamp/theming`  |
-| AR1                 | `Timestamp.test.tsx` `datetime` tests                                                                                | `date_time`; `date`                                            | A missing or wrong ISO `datetime` on `date_time`, or a missing one on `date`, fails. Gap: no test asserts the exact `datetime` on relative or other absolute formats.                                                                                                                                                                                                                                                                                     | `audit:Timestamp/a11y`     |
-| AR2, AR4            | Accessibility-tree evidence (`spec:AST-009` FR3)                                                                     | Relative output; copy buttons                                  | Gap: no accessibility-tree check proves the computed name of relative output or the copy-button names; the unit tests query the DOM.                                                                                                                                                                                                                                                                                                                      | `audit:Timestamp/a11y`     |
-
-## Decision log
-
-None recorded. The record describes shipped behavior.
-
-## Open questions
-
-None.
-
-## Content boundary
-
-This file does not duplicate consumer prop tables/examples, current audit
-results, implementation steps, or family/system rules. It links to their owners.