@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/VisuallyHidden/VisuallyHidden.spec.md

@@ -1,170 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:VisuallyHidden
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-27
-owners: [cixzhang]
-review_triggers: [public-api, behavior, accessibility]
-verified_by:
-  [
-    .github/visual-baseline/manifest.json,
-    packages/core/src/VisuallyHidden/VisuallyHidden.test.tsx,
-    apps/storybook/stories/VisuallyHidden.stories.tsx,
-  ]
-modules: []
-families: []
-design_specs: []
-architecture: [architecture:public-component-api]
-contributing: []
-system_specs: [spec:AST-009, spec:AST-071]
----
-
-# VisuallyHidden component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                    |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | A wrapper with required `children` and an optional `as` element; accessibility and data props pass through. It accepts no `className` or `style` and ignores `xstyle` today (FR3 gap, OQ1). |
-| Behavior                | Content is clipped from sight by a fixed style block no caller input can displace, and stays in the accessibility tree unless the caller passes `hidden`, `inert`, or `aria-hidden`.        |
-| End-user impact         | Screen-reader users hear names and announcements that sighted users do not need to see.                                                                                                     |
-| Builder impact          | None; the record describes shipped behavior.                                                                                                                                                |
-| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. One implementation gap is listed under Current-state impact; OQ1 is open.                                        |
-| Review checks           | Reject a `display: none` or `visibility: hidden` hide, a caller input that displaces the clip, or dropped `aria-*` passthrough.                                                             |
-| Governing rules         | `architecture:public-component-api/INV5,INV6,INV8`; `spec:AST-071` FR2.                                                                                                                     |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-VisuallyHidden exposes content to assistive technology while keeping it out of
-sight: names for icon-only controls, live announcement regions, and
-supplementary screen-reader context. It owns the hiding technique and the
-guarantee that the hidden node cannot be styled visible.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`
-- Compatibility class: records shipped behavior; no public prop, default, or
-  DOM output changes. `xstyle` is accepted by the type and ignored;
-  `className` and `style` are not accepted; the styling surface is the FR3 gap (OQ1)
-- Controlled/uncontrolled behavior: not applicable
-- Migration decision: none
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Current-state impact
-
-- **Styling inputs not accepted (FR3).** VisuallyHidden drops `className` and
-  `style` and ignores `xstyle`, so callers cannot style the element, where
-  `architecture:public-component-api` INV6 and `spec:AST-071` FR2 have root
-  styling inputs compose. The consumer docs plan to remove `xstyle`; OQ1
-  decides whether the component conforms or INV6's owner records it as an
-  exception.
-
-## Ownership boundary
-
-**Owns**
-
-- The rendered element and its fixed clip style block.
-- Passing accessibility, identity, data, and event props through.
-
-**Does not own / non-goals**
-
-- What the hidden content says and whether it is a live region — owned by the
-  caller, through `children`, `as`, and ARIA props.
-- Shared status announcements — owned by `spec:AST-086` and its shared channel.
-- Theming — VisuallyHidden has no theming target.
-
-## Public concepts
-
-| Concept | Closed values or states                                                                            | Meaning                                | Availability by variant/orientation/state | Default | Owner                      | Stability | Invalid-value behavior                                                                                          |
-| ------- | -------------------------------------------------------------------------------------------------- | -------------------------------------- | ----------------------------------------- | ------- | -------------------------- | --------- | --------------------------------------------------------------------------------------------------------------- |
-| Element | An intrinsic element, or a component that forwards `className` and `ref` to the element it renders | The rendered element, inline or block. | Always                                    | `span`  | `component:VisuallyHidden` | Stable    | A component that does not forward `className` and `ref` renders its content unclipped, and the ref stays unset. |
-
-## Behavioral and layout contract
-
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Basis                    |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| FR1 | VisuallyHidden renders `children` in the element named by `as` (default `span`). Its own hiding keeps the content in the accessibility tree; a caller's `hidden`, `inert`, or `aria-hidden` passes through and removes it, by the caller's choice.                                                                                                                                                                                                                                                                                                                                          | Current source and tests |
-| FR2 | When `as` is an intrinsic element or forwards `className` to the element it renders, that element is absolutely positioned at the inline-start and block-start of its containing block, 1px by 1px with a −1px margin, no padding or border, clipped to an empty rectangle with hidden overflow, unwrapped, and ignores pointer events and selection.                                                                                                                                                                                                                                       | Current source and tests |
-| FR3 | `ref` reaches the element (for a component `as`, when it forwards `ref`), and supported `aria-*`, `role`, `id`, `data-*`, and event props reach it. The clip styles apply after every caller input, so nothing displaces the clip. Root styling inputs compose on the element (`architecture:public-component-api` INV6, `spec:AST-071` FR2). Implementation gap: `className` and `style` are not accepted and `xstyle` is ignored; the consumer docs plan to remove `xstyle`, and OQ1 decides whether VisuallyHidden conforms or becomes a recorded INV6 exception (Current-state impact). | Current source and tests |
-
-### Allowed variation
-
-- **AV1 — Element choice.** Callers choose an inline or block element, such as
-  a `div` for block content or a live region.
-
-### Representative states
-
-| State             | Required invariant                                                      | Allowed variation |
-| ----------------- | ----------------------------------------------------------------------- | ----------------- |
-| Icon-only label   | Hidden `span` gives the control its accessible name.                    | Text.             |
-| Live region       | Block element with caller `aria-live` stays hidden and announced.       | Politeness.       |
-| Styling attempted | The clip still wins; caller styling has no effect today (FR3 gap, OQ1). | —                 |
-
-### Transformation and precedence order
-
-- **ORD1 — Props.** Caller props → fixed clip styles, so the clip wins.
-
-### Performance and resources
-
-- **PR1 — Static render.** VisuallyHidden holds no state and uses no hooks.
-
-## Accessibility contract
-
-- **AR1 — Perceivable to assistive technology.** Hiding uses clipping, never
-  `display: none`, `visibility: hidden`, or `aria-hidden`, so the content is
-  read and can name or describe other elements.
-- **AR2 — Live regions and hiding by caller choice.** VisuallyHidden adds no
-  role or live region of its own; a caller's `role`, `aria-live`, `hidden`,
-  `inert`, and `aria-hidden` pass through.
-
-## Design relationships
-
-| Anatomy or state | Design requirement                                  | Representation authority | Hierarchy role | Component contract |
-| ---------------- | --------------------------------------------------- | ------------------------ | -------------- | ------------------ |
-| Hidden content   | Present to assistive technology, absent from sight. | Current source and docs  | Supporting     | FR1–FR3, AR1, AR2  |
-
-Theming: VisuallyHidden has no theming target, by design; a visible style on a
-hidden node would defeat its purpose.
-
-## Family and system relationships
-
-- `architecture:public-component-api` owns passthrough, ref, and styling-input
-  rules; FR3 applies INV5, INV6, and INV8 and records the INV6 gap.
-
-## Verification map
-
-| Contract | Verification                                                                                     | Representative states                                                                   | Mutation or failure expectation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Audit section                   |
-| -------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
-| FR1, AR1 | `VisuallyHidden.test.tsx` render and icon-label tests                                            | Default, `as`, icon-only control                                                        | Content leaving the accessibility tree or a lost accessible name fails. Gap: no test covers a caller `hidden`, `inert`, or `aria-hidden` passing through.                                                                                                                                                                                                                                                                                                                                                                                             | `audit:VisuallyHidden/a11y`     |
-| FR2      | `VisuallyHidden.test.tsx` clip-style test; stable visual baseline `core-visuallyhidden--default` | Default                                                                                 | A `hidden` attribute fails the unit test; content that becomes visible comes back changed in the visual baseline. Gap: no unit test asserts a clip declaration, although the test environment exposes them.                                                                                                                                                                                                                                                                                                                                           | `audit:VisuallyHidden/behavior` |
-| FR3, AR2 | `VisuallyHidden.test.tsx` `as`, ref, passthrough, and styling tests                              | `as` with `aria-live`; ref; `id`, `role`, `data-testid`; `className`, `style`, `xstyle` | A lost `aria-live`, a missed ref, or a dropped `id` or `role` fails. The styling tests pin today's dropped `className`, `style`, and `xstyle` attribute, which pins the recorded FR3 gap, not the contract. Gap: no test asserts that VisuallyHidden adds no role or live region of its own; the ref test still passes when a wrapper receives the ref; no test asserts other `aria-*` or event props; no test checks that the clip wins over caller styles; and no test covers a component `as` that does or does not forward `className` and `ref`. | `audit:VisuallyHidden/behavior` |
-| PR1      | Source review                                                                                    | Every state                                                                             | Gap: no automated check fails if VisuallyHidden adds state or a hook.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `audit:VisuallyHidden/behavior` |
-| AR1      | Accessibility-tree evidence (`spec:AST-009` FR3)                                                 | Icon-only label; live region                                                            | Gap: no accessibility-tree check proves the hidden content stays in the tree; the unit tests query the DOM.                                                                                                                                                                                                                                                                                                                                                                                                                                           | `audit:VisuallyHidden/a11y`     |
-
-## Decision log
-
-None recorded. The record describes shipped behavior; OQ1 is open.
-
-## Open questions
-
-- **OQ1 — Should VisuallyHidden accept root styling inputs?** (`human-api`)
-  `architecture:public-component-api` INV6 has root styling inputs compose
-  unless a family decision names an exception, and the consumer docs plan to
-  remove `xstyle`; until an owner decides, the styling-free surface is the FR3
-  gap. If styling-free is a deliberate exception, INV6's owner
-  records it (with a `spec:AST-071` known-gap entry) and FR3 links it, and
-  callers keep no way to style the element. If composition is the direction,
-  FR3 stays as written and a conforming implementation closes the gap.
-
-## 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.

package/src/i18n/InternationalizationProvider.spec.md

@@ -1,252 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:InternationalizationProvider
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: nynexman4464
-approved_at: 2026-10-15
-owners: [nynexman4464, cixzhang]
-review_triggers: [public-api, behavior, accessibility]
-verified_by:
-  [
-    packages/core/src/i18n/__tests__/resolve.test.ts,
-    packages/core/src/i18n/__tests__/InternationalizationProvider.test.tsx,
-    packages/core/src/i18n/__tests__/useDirection.test.tsx,
-    packages/core/src/i18n/__tests__/getLocaleDirection.test.ts,
-    packages/core/src/i18n/__tests__/useLocale.test.tsx,
-    packages/core/src/i18n/useTranslator.test.tsx,
-  ]
-modules: []
-families: []
-design_specs: []
-architecture: [architecture:internationalization]
-contributing: []
-system_specs: []
----
-
-# InternationalizationProvider component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | `messages` accepts `ProviderMessagesByLocale`: each locale maps to a rich `Catalog` or a generated `RuntimeCatalog` string map. `RuntimeCatalog` and `ProviderMessagesByLocale` are exported from `@astryxdesign/core/i18n`. Existing props and the rich `MessagesByLocale` context shape are unchanged.                                                                                                                                        |
-| Behavior                | Astryx strings resolve override → supplied catalog → shipped English, walking exact → parent locale. Rich and runtime catalogs resolve identically; the context always exposes the rich shape. Changing any provider prop updates the subtree. A nested provider replaces its parent's context. Without a provider: locale `en`, direction `ltr`, shipped English.                                                                              |
-| End-user impact         | People using a translated locale see Astryx interface and assistive text in that locale where a translation exists and meaningful English otherwise; a missing translation never removes an accessible name or announcement.                                                                                                                                                                                                                    |
-| Builder impact          | Optional: import `@astryxdesign/core/locales/<tag>.generated.js` for a smaller bundle; `<tag>.json` keeps working. Render the provider once, supply partial catalogs freely, and keep DOM `dir` aligned with the provider direction.                                                                                                                                                                                                            |
-| Compatibility/readiness | Released default preserved; the provider, subpath, props, hooks, and rich context shape are stable public API; runtime-catalog input is additive. Re-render, nested-provider, and runtime-catalog behavior is covered by focused tests.                                                                                                                                                                                                         |
-| Review checks           | Reject reordering fallback (FR1, ORD1); hiding a key missing from every applicable source, including shipped English (FR2); a nested provider that merges parent context (FR8); the provider setting DOM `lang`/`dir` (FR5) or persisting locale (FR4); non-string translator results (FR7); host-locale output without a provider (FR6); a context value that exposes string-map entries or resolves rich and runtime input differently (FR9). |
-| Governing rules         | `architecture:internationalization` INV2–INV5, INV7, INV12, INV13, INV15.                                                                                                                                                                                                                                                                                                                                                                       |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-InternationalizationProvider binds one subtree to Astryx's active locale,
-translation catalogs, sparse Astryx string overrides, and direction default. It
-lets Astryx components localize their own interface while applications keep
-ownership of product copy and locale persistence.
-
-## Compatibility and migration
-
-- Released default preserved: `yes` — a tree with no provider continues to render
-  shipped English strings with locale `en` and direction `ltr`.
-- Compatibility class: the released provider name, `@astryxdesign/core/i18n`
-  subpath, props, context behavior, and hooks are stable public API.
-- Controlled/uncontrolled behavior: controlled. The caller supplies locale,
-  messages, overrides, and optional direction on every render.
-- Migration decision: a replacement provider or hook requires an accepted
-  compatibility and migration decision under
-  `architecture:internationalization/INV2`.
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Ownership boundary
-
-**Owns**
-
-- The active Astryx locale and optional explicit direction for one React subtree.
-- Binding supplied locale catalogs, rich or generated, and sparse overrides to a
-  stable translator function, and exposing them to consumers in the rich shape.
-- Updating provider consumers when any provider input changes.
-- The no-provider English/LTR context defaults exposed by the i18n entry point.
-
-**Does not own / non-goals**
-
-- Application locale selection, routing, persistence, or account preferences —
-  owned by the product.
-- Product-authored strings and application catalogs — owned by product call sites
-  or their chosen i18n runtime.
-- DOM `lang` or `dir` attributes — owned by the application document or region.
-- A server/RSC translation context — unresolved separate API work.
-- Rich React-node/function messages — outside the supported string catalog model.
-
-## Public concepts
-
-| Concept   | Closed values or states                | Meaning                                                                                                                                                                   | Availability by variant/orientation/state | Default                                     | Owner                                    | Stability | Invalid-value behavior                                                                                                                                                                                     |
-| --------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------- | ---------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Locale    | Valid BCP 47 locale string             | Selects lookup, ICU formatting, and provider-aware locale operations                                                                                                      | Every provider subtree                    | Required on provider; `en` without one      | `component:InternationalizationProvider` | stable    | Callers must pass a valid tag; malformed tags may throw when formatting or collating, while static key lookup may still reach English                                                                      |
-| Messages  | locale → `Catalog` or `RuntimeCatalog` | Adds translated or application-supplied catalogs, as rich `{defaultMessage, description?}` entries or as a generated key-to-string map, without replacing shipped English | Every locale                              | `{}`                                        | `component:InternationalizationProvider` | stable    | Missing entries fall back through the active locale's parent chain, then to shipped English; a supplied `en` catalog is read only when that chain includes `en`; mixed shapes within one call are accepted |
-| Overrides | locale → sparse key/string map         | Rewords individual Astryx strings before catalog lookup                                                                                                                   | Every locale                              | none                                        | `component:InternationalizationProvider` | stable    | `null` does not become visible content; unresolved keys continue through fallback                                                                                                                          |
-| Direction | `ltr` or `rtl`                         | Exposes the provider's semantic direction default                                                                                                                         | Every provider subtree                    | derived from locale; `ltr` without provider | `component:InternationalizationProvider` | stable    | Invalid values are rejected by the type contract                                                                                                                                                           |
-
-Consumer prop syntax and examples remain in
-`InternationalizationProvider.doc.mjs` and `astryx docs internationalization`.
-
-## Behavioral and layout contract
-
-| ID  | Candidate invariant                                                                                                                                                                                                     | Basis                                                                                  | Draft review state |
-| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------ |
-| FR1 | The provider MUST resolve Astryx strings through exact-locale overrides, parent-locale overrides, exact/parent supplied catalogs, then shipped English.                                                                 | Current resolver and focused tests                                                     | settled            |
-| FR2 | A missing translated key MUST fall back silently; a key absent from every applicable source, including shipped English, MUST warn once in development and render the key visibly.                                       | Released resolver and tests                                                            | settled            |
-| FR3 | Re-rendering with changed locale, messages, overrides, or direction MUST update the context value and translator used by descendants.                                                                                   | Released provider and rerender tests                                                   | settled            |
-| FR4 | The provider MUST NOT select, persist, or mutate application locale state.                                                                                                                                              | Released API ownership                                                                 | settled            |
-| FR5 | The provider MUST NOT set DOM `lang` or `dir`. Its direction value and the application's DOM direction are separate inputs the application keeps aligned.                                                               | `architecture:internationalization/INV12`                                              | settled            |
-| FR6 | Without a provider, the public context and hooks MUST expose locale `en`, direction `ltr`, an empty supplied-catalog map, and a translator backed by shipped English.                                                   | Released context and tests                                                             | settled            |
-| FR7 | The provider MUST preserve a string-returning translator suitable for visible and assistive attributes.                                                                                                                 | Released catalog/runtime contract                                                      | settled            |
-| FR8 | A nested provider MUST replace locale, messages, overrides, and direction with values derived solely from the child provider's own props rather than merge parent context.                                              | Released provider and nested-provider tests                                            | settled            |
-| FR9 | The provider MUST accept a `RuntimeCatalog` string map or a rich `Catalog` per locale, resolve both to the same strings, and expose `messages` on the context in the rich `MessagesByLocale` shape regardless of input. | `architecture:internationalization/INV15`; provider and resolver runtime-catalog tests | settled            |
-
-### Allowed variation
-
-- **AV1 — Catalog completeness.** A non-English supplied catalog may contain any
-  subset of English keys; missing entries use fallback. Today that fallback
-  reaches shipped English only, so it covers Astryx keys; see OQ1.
-- **AV2 — Locale specificity.** Callers may provide a regional, script, or base
-  locale. The resolver canonicalizes and walks the corresponding parent chain.
-- **AV3 — Application integration.** Another i18n provider may wrap Astryx inside
-  or outside this provider as long as the application keeps locale state aligned.
-- **AV4 — Catalog form.** A caller may pass the shipped rich JSON, the shipped
-  generated string map, or a local catalog in either shape, per locale.
-
-### Representative states
-
-| State                             | Required invariant | Allowed variation                            |
-| --------------------------------- | ------------------ | -------------------------------------------- |
-| no provider                       | FR6                | none                                         |
-| English provider                  | FR1–FR4, FR7       | messages and overrides may be omitted        |
-| exact translated locale           | FR1–FR4, FR7, FR9  | complete or partial catalog, rich or runtime |
-| regional locale with base catalog | FR1–FR4, FR7       | number of parent tags                        |
-| runtime locale swap               | FR3                | application persistence mechanism            |
-| explicit direction override       | FR3, FR5           | locale may remain LTR for testing            |
-| nested provider                   | FR1–FR8            | child props fully replace parent context     |
-| generated runtime catalog input   | FR9                | mixed rich and runtime locales               |
-
-### Transformation and precedence order
-
-- **ORD1 — Message resolution.** Read exact-locale override → walk parent-locale
-  overrides → read exact-locale supplied catalog → walk parent supplied catalogs
-  → read shipped English → warn and render the key if absent everywhere.
-- **ORD1a — Input normalization.** A `RuntimeCatalog` entry is treated as a rich
-  entry with that string as `defaultMessage` and no description before ORD1 runs;
-  the context receives the normalized rich map.
-- **ORD2 — Direction resolution.** Use explicit `dir` when supplied; otherwise
-  derive direction from locale; outside a provider use `ltr`.
-
-### Performance and resources
-
-- **PR1 — Stable translator identity.** A provider render with referentially
-  unchanged inputs SHOULD preserve its memoized context value and translator.
-- **PR2 — Parsed message reuse.** ICU formatter instances MAY be cached by locale
-  and message while output remains equivalent to fresh formatting.
-
-## Accessibility contract
-
-- **AR1 — Assistive strings use the same resolution contract.** `aria-label`,
-  `title`, live announcements, and other AT-facing Astryx strings MUST use the
-  active translator and remain strings; assembling them from fragments or
-  hand-rolled plurals is a bypass under `architecture:internationalization/INV1a`.
-- **AR2 — Missing translations remain usable.** Expected non-English gaps MUST
-  fall back to meaningful English rather than remove an accessible name or
-  announcement.
-- **AR3 — Direction remains available to browser semantics.** The provider MUST
-  document that applications set DOM `dir`; a context value alone does not fix
-  browser text flow, punctuation, focus order, or platform bidi behavior.
-
-## Design relationships
-
-| Anatomy or state     | Design requirement                                                            | Representation authority            | Hierarchy role | Component contract |
-| -------------------- | ----------------------------------------------------------------------------- | ----------------------------------- | -------------- | ------------------ |
-| Provider subtree     | Product chooses the locale and region direction consistently.                 | application-owned                   | supporting     | FR3–FR5            |
-| Astryx system string | Astryx supplies a localized default; caller content may specialize semantics. | `architecture:internationalization` | supporting     | FR1, FR7, AR1      |
-| Missing translation  | Interface remains understandable through English fallback.                    | `architecture:internationalization` | supporting     | FR2, AR2           |
-
-### Theming anatomy
-
-<!-- anatomy-theming:v1 -->
-
-```json
-{
-  "Provider boundary": {
-    "none": {
-      "reason": "intentional: InternationalizationProvider renders no DOM element and exposes no theming anatomy."
-    }
-  }
-}
-```
-
-## Family and system relationships
-
-- `architecture:internationalization` owns cross-library catalog, locale,
-  formatter, date-calendar, output-type, external-runtime, and generated
-  runtime-catalog delivery boundaries (which files are authored, which are
-  derived, how they are published and resolved).
-- Component contracts own which strings are Astryx-authored and which content is
-  caller-authored.
-
-## Verification map
-
-| Contract       | Verification                                                                            | Representative states                                       | Mutation or failure expectation                                                                    | Audit section                                      |
-| -------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
-| FR1, FR2, ORD1 | `resolve.test.ts`                                                                       | exact, parent, English, missing source key                  | Reordering fallback or hiding a missing source key fails focused tests                             | `audit:InternationalizationProvider/behavior`      |
-| FR3, PR1       | `useTranslator.test.tsx`, `useLocale.test.tsx`, `InternationalizationProvider.test.tsx` | stable inputs; locale, message, override, and dir swaps     | A stale translator/direction or needless identity churn fails these tests                          | `audit:InternationalizationProvider/performance`   |
-| FR5, ORD2      | `useDirection.test.tsx`, `getLocaleDirection.test.ts`                                   | derived, explicit, invalid locale, no provider              | Setting DOM direction or ignoring explicit override fails source/tests                             | `audit:InternationalizationProvider/rtl`           |
-| FR6            | `useTranslator.test.tsx`, `useLocale.test.tsx`, `useDirection.test.tsx`                 | no provider                                                 | Host locale or missing English output fails                                                        | `audit:InternationalizationProvider/behavior`      |
-| FR7, AR1, AR2  | component translation tests and hardcoded-string lint                                   | visible text, aria label, announcement, missing translation | Non-string output or untranslated owned text fails tests/lint                                      | `audit:InternationalizationProvider/accessibility` |
-| FR8            | `InternationalizationProvider.test.tsx`                                                 | parent plus child provider                                  | Parent messages, overrides, or direction leaking into the child fails                              | `audit:InternationalizationProvider/behavior`      |
-| FR9, ORD1a     | `useTranslator.test.tsx`, `resolve.test.ts` runtime-catalog cases                       | generated string map, rich catalog, mixed                   | A rejected string map, a string-map entry on the context, or divergent output between shapes fails | `audit:InternationalizationProvider/behavior`      |
-
-## Decision log
-
-### DEC-1 — Keep the released Astryx runtime narrow
-
-**Reference:** `component:InternationalizationProvider/DEC-1`
-**Decider:** `nynexman4464`, `2026-09-03`
-
-Astryx keeps `InternationalizationProvider` and the released i18n hooks as its
-canonical runtime. Astryx may support small applications, but it does not absorb
-application-owned rich messages and functions to compete with full i18n
-frameworks. Applications with larger needs use an established application i18n
-runtime alongside Astryx; an adapter remains possible as additive follow-up.
-
-Rejected: a parallel provider/hook runtime that replaces the released surface
-and mixes Astryx string ownership with application rich-message ownership.
-
-## Open questions
-
-- **OQ1 — Supplied `en` as a fallback for non-Astryx keys (known bug).** The
-  shipped English runtime catalog is the only cross-locale fallback and it holds
-  Astryx keys only. An application or library key that is missing from the active
-  locale therefore renders as its raw key even when the caller supplied an `en`
-  catalog. This is a known cross-locale fallback defect. The contract describes
-  the shipped behavior without endorsing the limitation; a supplied-English
-  fallback requires a corresponding FR1/ORD1 amendment and a regression test
-  using a partially translated non-Astryx key. (`human-api`)
-- **OQ2 — Malformed locale behavior.** Decide whether a future release should
-  reject invalid BCP 47 tags at the provider boundary or preserve today's
-  formatter-specific throws. (`human-api`)
-- **OQ3 — External runtime adapter.** Decide the exact additive `Translator`
-  adapter contract, including who owns lookup, fallback, and formatter failures.
-  (`human-api`)
-- **OQ4 — Server translation runtime.** Decide whether the small set of otherwise
-  server-safe consumers justifies a separate RSC translation API and request
-  isolation model. (`human-api`)
-
-## Content boundary
-
-This file does not duplicate consumer prop tables/examples, catalog validation
-implementation, runtime-catalog generation, current translation coverage, or
-cross-library i18n rules. It links to their owners.