@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/hooks/useScrollOverflow.ts

@@ -4,28 +4,11 @@
 
 /**
  * @file useScrollOverflow.ts
- * @input Uses React useRef, useState, useCallback, useEffect
- * @output Exports useScrollOverflow hook for tracking scroll position edges
+ * @input React refs, state and effects
+ * @output useScrollOverflow, which tracks the overflow at the scroll edges
  * @position Core hook; used by Carousel and TabList for fade-edge and button
  *   state
  *
- * Observes a scroll container and reports whether content overflows at the
- * start, end, or both edges. Updates on every scroll, and while the container
- * is rendered on what else changes the overflow with or without the
- * container resizing: its own size, a child's size (a slide's content
- * growing), a child added or removed, and its class or style (a new gap or
- * padding). A layout read on an element the browser is not
- * rendering (an ancestor with `display: none`, or a `content-visibility:
- * hidden` subtree) either answers zeros or makes the browser lay out that
- * whole hidden subtree for the answer, so an observation delivered for a
- * hidden container, and the measurement at registration inside one, are
- * skipped; the hook keeps its last state until the resize observation that
- * follows the reveal (one frame after it paints). A scroll is measured
- * whether or not the container is rendered: a scroll of a hidden container
- * is script's (a selected tab revealed under a hidden panel), its layout is
- * already the scroll's, and a reveal at the same size brings no resize to
- * measure it with.
- *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts
  */
@@ -144,10 +127,10 @@ export function useScrollOverflow() {
     });
   }, []);
 
-  // Registration, resize and content changes: only a rendered container. A
-  // hidden one has no edges to report, and reading its layout would make the
-  // browser render the hidden subtree it sits in; the resize observation that
-  // follows the reveal measures again.
+  // Only a rendered container is measured at registration and on a resize or
+  // content change. A layout read on a hidden one makes the browser render
+  // its hidden subtree. The resize observation after the reveal measures
+  // again.
   const measure = useCallback(() => {
     const el = elRef.current;
     if (el && isRendered(el)) {
@@ -155,10 +138,9 @@ export function useScrollOverflow() {
     }
   }, [measureNow]);
 
-  // A scroll: measured hidden or not. Script scrolled the hidden container
-  // (its layout is already the scroll's), and a reveal at the same size
-  // brings no resize observation, so this is the read that keeps the edges
-  // right for it.
+  // A scroll is measured hidden or not. Script scrolled the hidden container,
+  // so its layout is already current. A reveal at the same size brings no
+  // resize observation, so this read keeps the edges right.
   const measureOnScroll = useCallback(() => {
     const el = elRef.current;
     if (el) {

package/src/hooks/useScrollableArea.ts

@@ -8,10 +8,8 @@
  * @output Safe prop getters, native keyboard entry, and stable per-axis effective scroll state
  * @position Canonical behavior core for ScrollableArea and structure-owning adopters
  *
- * Geometry and style signals coalesce into one full measurement per frame. A
- * scroll only moves the offset, so its event re-derives the logical edges
- * from box geometry: no computed-style read and no extra frame while the
- * user scrolls.
+ * Geometry and style signals cause one full measurement per frame. A scroll
+ * moves only the offset, so it reads only box geometry.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/useScrollableArea.doc.mjs
@@ -303,15 +301,12 @@ export function useScrollableArea({
       frame = window.requestAnimationFrame(measure);
     };
 
-    // A scroll moves the offset and nothing else, so it only re-derives the
-    // logical edges, from box geometry, as the scroll event is dispatched.
-    // Browsers fire it at most once per frame, before animation-frame
-    // callbacks, when style and layout are normally still clean from the last
-    // frame: no computed style is read, no frame is requested, and the edges
-    // are current in the frame that moved. Anything a scroll cannot explain
-    // (overflow appearing or going away on a requested axis, or an offset
-    // whose sign the measured writing direction rules out) schedules the
-    // full measurement, as every other invalidation does.
+    // A scroll moves only the offset, so it derives the logical edges from
+    // box geometry when the event fires. Style and layout are usually still
+    // clean then, so no computed style is read and no frame is requested.
+    // When the scroll cannot explain a change (overflow on a requested axis
+    // appears or goes away, or the offset sign does not match the writing
+    // direction), it schedules the full measurement.
     const onScroll = () => {
       if (!isActive || frame != null) {
         // A full measurement is already pending for this frame.
@@ -427,14 +422,12 @@ export function useScrollableArea({
     };
   }, [axis, content, viewport]);
 
-  // The first measure reads the viewport before this hook has let an
-  // overflowing axis scroll (it is `clip` until then), so it finds overflow
-  // but no scrollable axis yet. Measure again in the same commit once an axis
-  // has just gained overflow (or the axis mapping changed), so the viewport is
-  // a tab stop from the first frame it scrolls, not an animation frame later
-  // (`spec:AST-025` FR12). Only on a gain: content that fits only once a
-  // scrollbar takes space would otherwise flip overflow back and forth inside
-  // one commit; a loss waits for the next frame, as before.
+  // The first measure runs before an overflowing axis can scroll (it is
+  // `clip` until then). So when an axis gains overflow, or the axis mapping
+  // changes, measure again in the same commit. Then the viewport is a tab
+  // stop from the first frame it scrolls (AST-025). Do this only on a gain:
+  // content that fits only when a scrollbar takes space would flip in one
+  // commit. A loss waits for the next frame.
   const previousOverflowRef = useRef<LogicalOverflowGeometry>(INITIAL_OVERFLOW);
   const previousMappingRef = useRef<LogicalAxisMapping>(INITIAL_MAPPING);
   useIsomorphicLayoutEffect(() => {

package/src/hooks/useSettledOpen.ts

@@ -0,0 +1,51 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useSettledOpen.ts
+ * @input Uses React useState and useIsHydrating
+ * @output Exports useSettledOpen (internal; not re-exported from hooks/index.ts)
+ * @position Internal utility; read by Dialog, Drawer, BottomSheet and
+ *   BottomSheetSwitcher so an overlay open on the server opens settled after
+ *   hydration (spec:AST-013 FR13)
+ *
+ * An overlay open on the server renders closed until hydration, since nothing
+ * can make it modal before then. It was still present on page load, so the
+ * open right after hydration plays no entry motion. This hook remembers what
+ * was open on the server (an open flag, or a switcher's active step) until
+ * that first stops being in effect after hydration; later opens animate.
+ */
+
+import {useCallback, useState} from 'react';
+import {useIsHydrating} from './useIsHydrating';
+
+/**
+ * Returns `requested` as it was on the server and in the hydrating render,
+ * until `current` first differs from it after hydration or the caller
+ * releases it; `none` otherwise. Compare the result with `current` to know
+ * whether the open in effect is the settled one. The second element releases
+ * it: an overlay whose settled entry still runs a transition (a sheet's
+ * collapsed rise) calls it when that transition ends, so motion within the
+ * same open (a drag's settle) animates as usual.
+ *
+ * @param requested What the caller asks to have open (the `isOpen` prop, or
+ *   the switcher's `activeSheet` prop).
+ * @param current What is open in this render, once hydrated.
+ * @param none The value meaning nothing is open (`false` or `null`).
+ */
+export function useSettledOpen<T>(
+  requested: T,
+  current: T,
+  none: T,
+): [settled: T, release: () => void] {
+  const isHydrating = useIsHydrating();
+  const [settled, setSettled] = useState<T>(() =>
+    isHydrating ? requested : none,
+  );
+  if (settled !== none && !isHydrating && current !== settled) {
+    setSettled(none);
+  }
+  const release = useCallback(() => setSettled(none), [none]);
+  return [settled, release];
+}

package/src/hooks/useStreamingText.ts

@@ -4,21 +4,10 @@
 
 /**
  * @file useStreamingText.ts
- * @input Uses React useState, useEffect, useRef, useMediaQuery, useTheme
- * @output Exports useStreamingText hook for smooth text streaming
- * @position Core hook; smooths bursty streamed text into steady character reveal
- *
- * Decouples the arrival rate of streamed chunks from the display rate,
- * draining characters at a steady pace using requestAnimationFrame. The
- * reveal cadence advances by a fixed number of UTF-16 code units per tick;
- * the rendered slice is then snapped back to the nearest grapheme cluster
- * boundary (see snapToGraphemeBoundary) so a tick landing inside a
- * surrogate pair, flag sequence, or ZWJ emoji doesn't render a lone
- * surrogate or a partial glyph for one frame.
- *
- * Animation timing derives from Astryx motion tokens (via useTheme) when
- * an Theme provider is present. Falls back to sensible defaults when
- * used outside a theme provider.
+ * @input React state, effects and refs; useMediaQuery; useTheme
+ * @output useStreamingText hook for smooth text streaming
+ * @position Core hook; smooths bursty streamed text into a steady reveal.
+ *   Timing comes from the motion tokens, with defaults outside a theme.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts (exports)
@@ -71,9 +60,8 @@ const CHARS_PER_TICK = {
   instant: Infinity,
 } as const;
 
-// Reuse a single segmenter when the runtime supports Intl.Segmenter.
-// Granularity is fixed and locale doesn't affect grapheme-cluster
-// boundaries, so one instance is safe to share across calls.
+// One shared segmenter. The granularity is fixed, and the locale does not
+// change grapheme boundaries.
 const graphemeSegmenter =
   typeof Intl.Segmenter === 'function'
     ? new Intl.Segmenter(undefined, {granularity: 'grapheme'})
@@ -100,9 +88,8 @@ export function snapToGraphemeBoundary(text: string, offset: number): number {
     return offset;
   }
   if (graphemeSegmenter) {
-    // `containing` only returns undefined for an out-of-range index; offset
-    // is already guarded to [1, text.length - 1] above, so this is always
-    // defined at runtime — the `??` is to satisfy the type, which is wider.
+    // The guard above keeps offset in range, so `containing` is defined. The
+    // `??` satisfies the wider type.
     return graphemeSegmenter.segment(text).containing(offset)?.index ?? offset;
   }
   return isLowSurrogate(text.charCodeAt(offset)) ? offset - 1 : offset;
@@ -141,9 +128,8 @@ export function useStreamingText(
   const speed = options?.speed ?? 'natural';
   const charsPerTick = CHARS_PER_TICK[speed];
 
-  // Derive tick timing from Astryx motion tokens when available.
-  // natural → --duration-fast-min (frame-level cadence from the theme)
-  // fast → half that, floored at 4ms (roughly 2x speed)
+  // Tick timing comes from the motion tokens: natural uses
+  // --duration-fast-min, and fast uses half of it, at least 4ms.
   const {token} = useTheme();
   const tickMs = useMemo(() => {
     if (speed === 'instant') {
@@ -153,8 +139,8 @@ export function useStreamingText(
     if (base == null) {
       return speed === 'fast' ? FALLBACK_TICK_MS_FAST : FALLBACK_TICK_MS;
     }
-    // Scale: use ~1/10th of the theme's fast-min duration as the per-frame tick.
-    // This maps a 130ms token to ~13ms tick (natural) or ~6.5ms tick (fast).
+    // The per-frame tick is about 1/10 of the fast-min duration, so a 130ms
+    // token gives a 13ms tick (natural) or a 6.5ms tick (fast).
     const tick = speed === 'fast' ? base / 20 : base / 10;
     return Math.max(4, Math.round(tick));
   }, [token, speed]);
@@ -165,7 +151,6 @@ export function useStreamingText(
   const lastTickRef = useRef(0);
   const rafRef = useRef<number | null>(null);
 
-  // Keep target ref in sync
   targetRef.current = targetText;
 
   // Reset when target clears (new message)
@@ -178,7 +163,6 @@ export function useStreamingText(
     }
   }
 
-  // Snap to full text when streaming ends
   const prevIsStreamingRef = useRef(isStreaming);
   if (isStreaming !== prevIsStreamingRef.current) {
     prevIsStreamingRef.current = isStreaming;
@@ -188,15 +172,12 @@ export function useStreamingText(
     }
   }
 
-  // Respect the user's reduced-motion preference — skip the progressive
-  // reveal and snap straight to the full text. Uses the package's SSR-safe
-  // useMediaQuery (useMediaQuery.ts) so the read stays in sync if the
-  // preference changes mid-stream.
+  // Reduced motion skips the progressive reveal and shows the full text.
+  // useMediaQuery follows a preference change mid-stream.
   const prefersReducedMotion = useMediaQuery(
     '(prefers-reduced-motion: reduce)',
   );
 
-  // Animation loop
   useEffect(() => {
     if (!isStreaming || speed === 'instant' || prefersReducedMotion) {
       return;

package/src/hooks/useTreeFocus.doc.mjs

@@ -59,7 +59,7 @@ export const docs = {
     {
       name: 'options.typeahead',
       type: 'boolean',
-      description: 'Whether typeahead (jump to next item whose text starts with the typed characters) is enabled.',
+      description: 'Whether typeahead (jump to next item whose text starts with the typed characters, ignoring case, accents, the stroked letters đ ł ø ħ ŧ ƀ and Turkish ı/İ in every locale) is enabled.',
       default: 'true',
       required: false,
     },
@@ -119,7 +119,7 @@ export const docsDense = {
     'options.onActivate': 'called on Enter/Space activation. Return true when handled; else hook falls back to toggling expansion.',
     'options.onActiveChange': 'notified when focus moves to a treeitem. Use to move a single roving tab stop.',
     'options.hasRovingTabIndex': 'hook owns a single roving tab stop (stamps tabindex 0/-1, repairs on mount, moves w/ nav). Preserves an existing tabindex="0" seed. Attach handleFocus to sync after clicks.',
-    'options.typeahead': 'enable typeahead (jump to next item whose text starts with typed chars).',
+    'options.typeahead': 'enable typeahead (jump to next item whose text starts with typed chars, ignoring case, accents, stroked letters + Turkish ı/İ).',
   },
   returnDescriptions: {
     treeRef: 'ref to attach to tree container (role="tree").',

package/src/hooks/useTreeFocus.ts

@@ -17,6 +17,7 @@
 import {useCallback, useRef} from 'react';
 import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect';
 import {isRtlElement} from './isRtlElement';
+import {findTypeaheadMatch, nextTypeaheadBuffer} from '../utils/typeaheadMatch';
 
 /** Keys handled by the tree keyboard model (used to gate typeahead). */
 const NAVIGATION_KEYS = new Set([
@@ -235,8 +236,12 @@ export function useTreeFocus<T extends HTMLElement = HTMLElement>(
   options: UseTreeFocusOptions = {},
 ): UseTreeFocusReturn<T> {
   // The flag is pinned off here so an untyped options object cannot smuggle
-  // it through the public hook.
-  return useTreeFocusInternal<T>({...options, matchLabelledBy: false});
+  // it through the public hook, and the internal stop move stays internal.
+  const {takeTabStop: _takeTabStop, ...result} = useTreeFocusInternal<T>({
+    ...options,
+    matchLabelledBy: false,
+  });
+  return result;
 }
 
 /**
@@ -256,13 +261,25 @@ export type UseTreeFocusInternalOptions = UseTreeFocusOptions & {
   matchLabelledBy?: boolean;
 };
 
+/** What the package's own components get beyond the public hook. */
+export type UseTreeFocusInternalReturn<T extends HTMLElement = HTMLElement> =
+  UseTreeFocusReturn<T> & {
+    /**
+     * With `hasRovingTabIndex`, makes `item` the tree's one Tab stop, by the
+     * same rule the hook's own moves follow: a disabled or hidden row never
+     * takes it, and the stop stays where it is. TreeList calls it when it
+     * moves focus to a collapsing row.
+     */
+    takeTabStop: (item: HTMLElement) => void;
+  };
+
 /**
  * The implementation behind {@link useTreeFocus}. Not exported from the
  * package; the public hook calls it without the internal options.
  */
 export function useTreeFocusInternal<T extends HTMLElement = HTMLElement>(
   options: UseTreeFocusInternalOptions = {},
-): UseTreeFocusReturn<T> {
+): UseTreeFocusInternalReturn<T> {
   const {
     itemSelector = '[role="treeitem"]',
     isItemDisabled,
@@ -427,15 +444,16 @@ export function useTreeFocusInternal<T extends HTMLElement = HTMLElement>(
       currentIndex: number,
     ): void => {
       const state = typeaheadRef.current;
+      // The same buffer step as useTypeahead: a repeat means "next match", and
+      // a lone combining mark typed first is not a letter to jump to.
+      const nextBuffer = nextTypeaheadBuffer(state.buffer, e.key);
+      if (nextBuffer == null) {
+        return;
+      }
       if (state.timer != null) {
         clearTimeout(state.timer);
       }
-      // "aa" would match nothing; a repeat means "next match" (useTypeahead).
-      const char = e.key.toLowerCase();
-      const isRepeatSameChar =
-        state.buffer.length > 0 &&
-        state.buffer.split('').every(c => c === char);
-      state.buffer = isRepeatSameChar ? char : state.buffer + char;
+      state.buffer = nextBuffer;
       state.timer = setTimeout(() => {
         typeaheadRef.current.buffer = '';
       }, typeaheadResetMs) as unknown as number;
@@ -449,11 +467,15 @@ export function useTreeFocusInternal<T extends HTMLElement = HTMLElement>(
         ...items.slice(start + offset),
         ...items.slice(0, start + offset),
       ];
-      const match = ordered.find(
-        item =>
-          !itemDisabled(item) &&
-          itemLabelText(item, matchLabelledBy).toLowerCase().startsWith(query),
+      const enabled = ordered.filter(item => !itemDisabled(item));
+      // Case, accents, stroked letters and Turkish i fold away, and a typed
+      // mark prefers the exact match.
+      const matchIndex = findTypeaheadMatch(
+        enabled.map((_, i) => i),
+        i => itemLabelText(enabled[i], matchLabelledBy),
+        query,
       );
+      const match = matchIndex >= 0 ? enabled[matchIndex] : undefined;
       if (match != null) {
         e.preventDefault();
         focusItem(match);
@@ -624,11 +646,25 @@ export function useTreeFocusInternal<T extends HTMLElement = HTMLElement>(
     }
   }, [hasRovingTabIndex, syncTabStops]);
 
+  const takeTabStop = useCallback(
+    (item: HTMLElement) => {
+      if (!hasRovingTabIndex || itemDisabled(item)) {
+        return;
+      }
+      const items = getItems();
+      if (items.includes(item)) {
+        moveTabStop(items, item);
+      }
+    },
+    [getItems, hasRovingTabIndex, itemDisabled, moveTabStop],
+  );
+
   return {
     treeRef,
     handleKeyDown,
     handleFocus,
     focusFirst,
     focusLast,
+    takeTabStop,
   };
 }

package/src/hooks/useTypeahead.doc.mjs

@@ -75,7 +75,7 @@ export const docs = {
   ],
   usage: {
     description:
-      "Adds APG type-to-focus search to a collection: printable keystrokes are buffered (resetting after a pause), and the first item whose label starts with the buffer is reported through onMatch. Pressing the same letter repeatedly cycles through the matches rather than filtering deeper. It moves nothing itself; pair it with the collection's own focus management, most often useListFocus or useGridFocus.",
+      "Adds APG type-to-focus search to a collection: printable keystrokes are buffered (resetting after a pause), and the first item whose label starts with the buffer (ignoring case, accents, the stroked letters đ ł ø ħ ŧ ƀ and Turkish ı/İ, the same in every locale; a typed accent prefers the exact match) is reported through onMatch. Pressing the same letter repeatedly cycles through the matches rather than filtering deeper. It moves nothing itself; pair it with the collection's own focus management, most often useListFocus or useGridFocus.",
     bestPractices: [
       {
         guidance: true,
@@ -108,7 +108,7 @@ export const docs = {
 /** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
-    'APG type-to-focus search for a collection. Buffers printable keys (resets after pause), matches labels by prefix, reports index via onMatch. Same letter pressed repeatedly cycles matches. Moves nothing itself; pair w/ useListFocus / useGridFocus.',
+    'APG type-to-focus search for a collection. Buffers printable keys (resets after pause), matches labels by prefix ignoring case, accents, stroked letters + Turkish ı/İ in every locale (typed accent prefers exact match), reports index via onMatch. Same letter pressed repeatedly cycles matches. Moves nothing itself; pair w/ useListFocus / useGridFocus.',
   paramDescriptions: {
     options: 'config.',
     'options.getItemLabels':

package/src/hooks/useTypeahead.ts

@@ -4,7 +4,8 @@
 
 /**
  * @file useTypeahead.ts
- * @input Uses React useCallback/useEffect/useRef
+ * @input Uses React useCallback/useEffect/useRef, shared type-to-select
+ *   matching (utils/typeaheadMatch)
  * @output Exports useTypeahead hook for first-character (type-to-focus) search
  * @position Core hook; adds APG typeahead to menus, listboxes, and other
  *   collections. Composes with useListFocus/useGridFocus (or any collection)
@@ -15,6 +16,7 @@
  */
 
 import {useCallback, useEffect, useRef} from 'react';
+import {findTypeaheadMatch, nextTypeaheadBuffer} from '../utils/typeaheadMatch';
 
 export interface UseTypeaheadOptions {
   /**
@@ -94,7 +96,9 @@ function isComposingKey(e: React.KeyboardEvent | KeyboardEvent): boolean {
  * First-character ("type-ahead") search for a collection.
  *
  * Buffers printable keystrokes (resetting after `resetMs` of inactivity),
- * matches items whose label starts with the buffer, and cycles from the
+ * matches items whose label starts with the buffer (ignoring case, accents,
+ * stroked letters and Turkish dotted/dotless i, the same in every locale:
+ * `architecture:internationalization` INV17), and cycles from the
  * current index — so pressing "s" repeatedly walks through the "s" items
  * instead of sticking on the first. Space is reserved for activation and is
  * only treated as typeahead while a buffer is already active.
@@ -166,18 +170,19 @@ export function useTypeahead(options: UseTypeaheadOptions): UseTypeaheadReturn {
         return false;
       }
 
+      // A lone combining mark typed first is not a letter to jump to; after
+      // a letter it is part of that letter. A repeat of the same letter
+      // cycles rather than filtering deeper (APG behavior).
+      const nextBuffer = nextTypeaheadBuffer(bufferRef.current, e.key);
+      if (nextBuffer == null) {
+        return false;
+      }
+
       const labels = getItemLabels();
       if (labels.length === 0) {
         return false;
       }
 
-      // Pressing the SAME single character repeatedly cycles to the next match
-      // rather than filtering deeper (APG behavior).
-      const char = e.key.toLowerCase();
-      const isRepeatSameChar =
-        bufferRef.current.length > 0 &&
-        bufferRef.current.split('').every(c => c === char);
-      const nextBuffer = isRepeatSameChar ? char : bufferRef.current + char;
       bufferRef.current = nextBuffer;
       scheduleReset();
 
@@ -191,21 +196,17 @@ export function useTypeahead(options: UseTypeaheadOptions): UseTypeaheadReturn {
       // Once the buffer is longer it is refining a match, so the current item
       // stays in range. With nothing current there is nothing to advance past.
       const offset = hasCurrent && nextBuffer.length === 1 ? 1 : 0;
-
+      const order: number[] = [];
       for (let i = 0; i < count; i++) {
         const index = (start + offset + i + count) % count;
-        if (isDisabled?.(index)) {
-          continue;
-        }
-        const label = labels[index];
-        if (
-          label != null &&
-          label.trim().toLowerCase().startsWith(nextBuffer)
-        ) {
-          onMatch(index);
-          return true;
+        if (!isDisabled?.(index)) {
+          order.push(index);
         }
       }
+      const match = findTypeaheadMatch(order, i => labels[i], nextBuffer);
+      if (match >= 0) {
+        onMatch(match);
+      }
       return true;
     },
     [getItemLabels, onMatch, getCurrentIndex, scheduleReset, isDisabled],

package/src/i18n/InternationalizationContext.ts

@@ -35,7 +35,7 @@ export interface InternationalizationContextValue {
 }
 
 /**
- * Default value falls through to the shipped en catalog in resolve().
+ * Default value falls through to the shipped English fallback in resolve().
  * A consumer that doesn't render a provider still gets English defaults.
  */
 export const InternationalizationContext =

package/src/i18n/englishFallback.ts

@@ -0,0 +1,40 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file englishFallback.ts
+ * @input English key-to-message maps registered at module scope by the Core
+ *   modules that name those keys
+ * @output registerEnglishFallback and the read-only englishFallback map
+ * @position The shipped English fallback resolve.ts reads after the locale
+ *   chain.
+ *
+ * A Core module that names catalog keys registers the English for exactly
+ * those keys from its generated map (`i18n/generated-english/`, derived by
+ * scripts/generate-i18n-runtime.mjs):
+ *
+ *   import english from '../i18n/generated-english/Button/Button.generated';
+ *   registerEnglishFallback(english);
+ *
+ * so a component carries the English it can show rather than the whole
+ * catalog. Registration runs when the module loads, before any of its code
+ * can look a key up, so a key resolves wherever the module naming it is
+ * loaded. Public paths that resolve arbitrary Astryx keys register the whole
+ * catalog through fullEnglishFallback.ts.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/i18n/resolve.ts
+ * - /packages/core/src/i18n/fullEnglishFallback.ts
+ * - /scripts/i18n-english-fallback.mjs
+ */
+
+import type {RuntimeCatalog} from './types';
+
+const registered: Record<string, string> = {};
+
+/** The English registered so far, keyed by catalog key. */
+export const englishFallback: RuntimeCatalog = registered;
+
+/** Add a module's English to the shipped fallback. */
+export function registerEnglishFallback(messages: RuntimeCatalog): void {
+  Object.assign(registered, messages);
+}

package/src/i18n/fullEnglishFallback.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file fullEnglishFallback.ts
+ * @input The generated English runtime catalog
+ * @output registerFullEnglishFallback
+ * @position The only Core module that imports the whole English catalog.
+ *
+ * Called at module scope by the public paths that resolve arbitrary Astryx
+ * keys: the public `useTranslator`, the public `InternationalizationContext`
+ * export, and PowerSearch operator labels, whose `i18nKey` callers supply.
+ * Component modules register only their own keys (englishFallback.ts).
+ * scripts/i18n-english-fallback.mjs rejects any other caller.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/i18n/englishFallback.ts
+ * - /scripts/i18n-english-fallback.mjs
+ */
+
+import enCatalog from './generated-locales/en.generated';
+import {registerEnglishFallback} from './englishFallback';
+
+/** Make every shipped Astryx key resolve to its English. */
+export function registerFullEnglishFallback(): void {
+  registerEnglishFallback(enCatalog);
+}

package/src/i18n/generated-english/AlertDialog/AlertDialog.generated.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @generated by scripts/generate-i18n-runtime.mjs from packages/core/locales/en.json,
+ * holding the English for the catalog keys named in packages/core/src/AlertDialog/AlertDialog.tsx.
+ * Do not edit by hand. Run `pnpm generate:i18n-runtime` instead.
+ */
+
+const english: Readonly<Record<string, string>> = {
+  "@astryx.alertDialog.cancel": "Cancel"
+};
+
+export default english;

package/src/i18n/generated-english/AppShell/AppShell.generated.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @generated by scripts/generate-i18n-runtime.mjs from packages/core/locales/en.json,
+ * holding the English for the catalog keys named in packages/core/src/AppShell/AppShell.tsx.
+ * Do not edit by hand. Run `pnpm generate:i18n-runtime` instead.
+ */
+
+const english: Readonly<Record<string, string>> = {
+  "@astryx.appShell.mobileNavigation": "Mobile navigation",
+  "@astryx.appShell.skipToContent": "Skip to content"
+};
+
+export default english;

package/src/i18n/generated-english/Avatar/Avatar.generated.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @generated by scripts/generate-i18n-runtime.mjs from packages/core/locales/en.json,
+ * holding the English for the catalog keys named in packages/core/src/Avatar/Avatar.tsx.
+ * Do not edit by hand. Run `pnpm generate:i18n-runtime` instead.
+ */
+
+const english: Readonly<Record<string, string>> = {
+  "@astryx.avatar.nameWithStatus": "{name}, {status}"
+};
+
+export default english;