@astryxdesign/core 0.1.8 → 0.1.9-canary.09e9ddd

package/src/i18n/index.ts

@@ -10,10 +10,14 @@
  * The public API is deliberately small:
  *   - InternationalizationProvider — provider component
  *   - useTranslator               — hook returning a translator function
+ *   - useDirection                — hook returning the ambient text direction
+ *   - getLocaleDirection          — server-safe locale → direction helper
  *   - Translator                  — interface for consumer-injected runtimes
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/index.ts
+ * - /packages/core/src/i18n/useDirection.ts
+ * - /packages/core/src/i18n/getLocaleDirection.ts
  */
 
 export {InternationalizationProvider} from './InternationalizationProvider';
@@ -22,6 +26,8 @@ export {InternationalizationContext} from './InternationalizationContext';
 export type {InternationalizationContextValue} from './InternationalizationContext';
 export {useTranslator} from './useTranslator';
 export type {TranslatorFn} from './useTranslator';
+export {useDirection} from './useDirection';
+export {getLocaleDirection} from './getLocaleDirection';
 export type {Translator} from './translator';
 export type {
   Locale,

package/src/i18n/resolve.ts

@@ -22,6 +22,7 @@
 import IntlMessageFormat from 'intl-messageformat';
 import type {Catalog, Locale, MessagesByLocale, Overrides} from './types';
 import enSource from '../../locales/en.json' with {type: 'json'};
+import {warnOnce, __resetDevWarnings} from '../utils/devWarning';
 
 const EN_CATALOG = enSource as Catalog;
 
@@ -72,23 +73,6 @@ export function resolveLocaleChain(locale: Locale): Locale[] {
   return chain;
 }
 
-/**
- * Missing-key warn-once tracking. Fires ONLY when a key is missing from
- * every source including the shipped `en` catalog — that's a real bug
- * (typo, stale catalog, deleted key). Fallback to `en` from a non-en
- * locale is expected and silent, matching the FormatJS / i18next default
- * of not spamming the console when a translation simply hasn't been
- * written yet.
- */
-const warnedMissing = new Set<string>();
-
-function warnOnce(bucket: Set<string>, key: string, message: string): void {
-  if (!bucket.has(key)) {
-    bucket.add(key);
-    console.warn(message);
-  }
-}
-
 function lookup(
   key: string,
   locale: Locale,
@@ -135,10 +119,14 @@ export function resolve(
   const result = lookup(key, locale, messages, overrides);
 
   if (result === null) {
+    // Fires ONLY when a key is missing from every source including the
+    // shipped `en` catalog — a real bug (typo, stale catalog, deleted key).
+    // Fallback to `en` from a non-en locale is expected and stays silent,
+    // matching the FormatJS / i18next default.
     warnOnce(
-      warnedMissing,
-      `${locale}::${key}`,
-      `[astryx-i18n] missing key: ${key} (locale: ${locale})`,
+      `astryx-i18n:${locale}::${key}`,
+      'astryx-i18n',
+      `missing key: ${key} (locale: ${locale})`,
     );
     return key;
   }
@@ -161,5 +149,5 @@ export function resolve(
  */
 export function __resetForTests(): void {
   formatterCache.clear();
-  warnedMissing.clear();
+  __resetDevWarnings();
 }

package/src/i18n/useDirection.ts

@@ -0,0 +1,29 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useDirection.ts
+ * @input InternationalizationContext (via use())
+ * @output 'ltr' | 'rtl'
+ * @position Client hook for reading the ambient text direction. Returns 'ltr'
+ *   when called outside a provider (matches the silent-en-fallback pattern of
+ *   useTranslator).
+ *
+ * Use this in components that need to swap directional icons, mirror
+ * behavioral logic (slider math, keyboard nav), or apply direction-specific
+ * styling that CSS logical properties can't express.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/i18n/InternationalizationContext.ts
+ * - /packages/core/src/i18n/getLocaleDirection.ts (server-safe counterpart)
+ * - /packages/core/src/i18n/index.ts
+ */
+
+import {use} from 'react';
+import {InternationalizationContext} from './InternationalizationContext';
+
+export function useDirection(): 'ltr' | 'rtl' {
+  const ctx = use(InternationalizationContext);
+  return ctx.direction;
+}

package/src/reset.css

@@ -360,32 +360,6 @@
     -webkit-tap-highlight-color: transparent;
   }
 
-  /* ===========================================================================
-     Touch Devices
-     =========================================================================== */
-
-  /*
-   * Suppress focus-visible outlines on touch-only devices.
-   *
-   * Focus rings exist to show keyboard users where focus is. On devices
-   * with no hover capability and a coarse pointer (phones, tablets),
-   * there's no keyboard navigation — focus rings are visual noise that
-   * can flash on tap, on dialog open (showModal auto-focus), or on
-   * programmatic focus.
-   *
-   * This targets touch-only devices specifically:
-   * - (hover: none) — no hover capability (not a mouse)
-   * - (pointer: coarse) — imprecise pointer (finger, not stylus)
-   *
-   * Hybrid devices (laptop with touchscreen) are NOT affected because
-   * their primary pointer is fine (trackpad/mouse) and hover is available.
-   */
-  @media (hover: none) and (pointer: coarse) {
-    :where(:focus-visible) {
-      outline: none;
-    }
-  }
-
   /* ===========================================================================
      Color Scheme
      =========================================================================== */

package/src/reset.test.ts

@@ -0,0 +1,60 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Tests for reset.css invariants that components rely on.
+ *
+ * reset.css is a plain stylesheet, so these tests assert on its source
+ * text (same approach as the reset.css baseline checks in
+ * theme/onMediaTokens.test.ts and AspectRatio/AspectRatio.test.tsx).
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+import {beforeAll, describe, expect, it} from 'vitest';
+
+describe('reset.css accessibility invariants', () => {
+  let ruleBlocks: {selector: string; body: string}[];
+
+  beforeAll(() => {
+    const resetCSS = fs.readFileSync(
+      path.resolve(__dirname, './reset.css'),
+      'utf-8',
+    );
+    // Strip comments, then collect every innermost `selector { body }`
+    // block. `[^{}]` keeps at-rule preludes (@media, @layer) out of the
+    // selector capture, since their own `{` terminates any earlier match.
+    const stripped = resetCSS.replace(/\/\*[\s\S]*?\*\//g, '');
+    ruleBlocks = [...stripped.matchAll(/([^{}]+)\{([^{}]*)\}/g)].map(
+      ([, selector, body]) => ({selector: selector.trim(), body}),
+    );
+  });
+
+  it('parses rule blocks out of reset.css', () => {
+    // Guards the WCAG assertion below against silently passing if the
+    // block parsing ever breaks.
+    expect(ruleBlocks.length).toBeGreaterThan(20);
+    expect(
+      ruleBlocks.some(({body}) => body.includes('box-sizing: border-box')),
+    ).toBe(true);
+  });
+
+  /**
+   * WCAG 2.4.7 (Focus Visible, Level AA): keyboard focus indicators must
+   * not be suppressed. `:focus-visible` only matches keyboard-style focus,
+   * so any `outline: none` on it removes the focus indicator for keyboard
+   * users — and a `@media (hover: none) and (pointer: coarse)` guard does
+   * not exempt keyboard users on coarse-pointer devices (iPad/phone with a
+   * Bluetooth keyboard, switch-control users).
+   */
+  it('does not suppress :focus-visible outlines (WCAG 2.4.7)', () => {
+    const focusVisibleBlocks = ruleBlocks.filter(({selector}) =>
+      selector.includes(':focus-visible'),
+    );
+    for (const {selector, body} of focusVisibleBlocks) {
+      expect
+        .soft(body, `":focus-visible" rule "${selector}" must keep the outline`)
+        .not.toMatch(/outline(?:-style|-width)?\s*:\s*(?:none|0)/);
+    }
+  });
+});

package/src/theme/Theme.tsx

@@ -45,6 +45,7 @@ import {registerIcons} from '../Icon/globalIconRegistry';
 import {generateThemeCSS, type DefinedTheme} from './defineTheme';
 import {dataAttr} from '../naming';
 import {ThemeContext} from './useTheme';
+import {warnOnce} from '../utils/devWarning';
 
 /**
  * Theme provider props
@@ -97,9 +98,6 @@ ThemeNestingContext.displayName = 'ThemeNestingContext';
 /** Track which themes have already been injected */
 const injectedThemes = new Set<string>();
 
-/** Track which themes have already logged the perf warning */
-const warnedThemes = new Set<string>();
-
 /**
  * Hook to inject theme CSS into the document.
  * Built themes (from `astryx theme build`) skip injection — their CSS
@@ -120,17 +118,16 @@ function useThemeStyleInjection(theme: DefinedTheme): void {
     }
 
     // One-time perf hint per theme
-    if (!warnedThemes.has(theme.name)) {
-      warnedThemes.add(theme.name);
-      console.warn(
-        `[Astryx] Theme "${theme.name}" is using runtime style injection. ` +
-          `For better performance, use the pre-built theme:\n\n` +
-          `  import {${theme.name}Theme} from '@astryxdesign/theme-${theme.name}/built';\n` +
-          `  import '@astryxdesign/theme-${theme.name}/theme.css';\n\n` +
-          `For custom themes, run \`npx @astryxdesign/cli theme build <file>\` to generate ` +
-          `the built artifacts.`,
-      );
-    }
+    warnOnce(
+      `theme-injection:${theme.name}`,
+      'Theme',
+      `"${theme.name}" is using runtime style injection. ` +
+        `For better performance, use the pre-built theme:\n\n` +
+        `  import {${theme.name}Theme} from '@astryxdesign/theme-${theme.name}/built';\n` +
+        `  import '@astryxdesign/theme-${theme.name}/theme.css';\n\n` +
+        `For custom themes, run \`npx @astryxdesign/cli theme build <file>\` to generate ` +
+        `the built artifacts.`,
+    );
 
     const {prose, component} = generateThemeCSS(theme);
     if (!prose && !component) {

package/src/theme/derivedVarRegistry.test.ts

@@ -186,6 +186,7 @@ function discoverComponents(): ComponentInfo[] {
 // ---------------------------------------------------------------------------
 
 const DIR_TO_REGISTRY_KEY: Record<string, string> = {
+  Avatar: 'avatar',
   Banner: 'banner',
   Button: 'button',
   Card: 'card',

package/src/theme/derivedVarRegistry.ts

@@ -35,6 +35,12 @@ export interface DerivedVarEntry {
  * entries share the same property.
  */
 export const derivedVarRegistry: Record<string, DerivedVarEntry[]> = {
+  avatar: [
+    {property: 'fontSize', vars: ['--_avatar-fallback-font-size']},
+    {property: 'fontWeight', vars: ['--_avatar-fallback-font-weight']},
+    {property: 'color', vars: ['--_avatar-fallback-color']},
+    {property: 'backgroundColor', vars: ['--_avatar-fallback-background']},
+  ],
   banner: [{property: 'borderRadius', vars: ['--_banner-radius']}],
   button: [{property: 'borderRadius', vars: ['--_button-radius']}],
   card: [

package/src/theme/generateThemeRules.test.ts

@@ -190,6 +190,61 @@ describe('generateThemeRules', () => {
     expect(rules.some(r => r.includes('.astryx-text.accent'))).toBe(true);
   });
 
+  // --- Size-prop overrides (so `size` beats a themed `type`) ---
+
+  it('emits Text size-prop font-size overrides in the same layer as type rules', () => {
+    // Digit-leading sizes are prefixed (size-2xs); word sizes stay bare.
+    const sizeRule = rules.find(
+      r => r.includes('.astryx-text.size-2xs') && r.includes('font-size'),
+    );
+    expect(sizeRule).toBeDefined();
+    expect(sizeRule).toContain('var(--font-size-2xs)');
+
+    // `xsm` maps to the --font-size-xs token (matches sizeStyles).
+    const xsmRule = rules.find(r => r.includes('.astryx-text.xsm'));
+    expect(xsmRule).toBeDefined();
+    expect(xsmRule).toContain('var(--font-size-xs)');
+
+    // Overrides set only font-size — line-height/family come from `type`.
+    expect(xsmRule).not.toContain('line-height');
+  });
+
+  it('emits a size override for every TextSize value', () => {
+    const sizes = [
+      'size-4xs',
+      'size-3xs',
+      'size-2xs',
+      'xsm',
+      'sm',
+      'base',
+      'lg',
+      'xl',
+      'size-2xl',
+      'size-3xl',
+      'size-4xl',
+    ];
+    for (const cls of sizes) {
+      expect(
+        rules.some(
+          r => r.includes(`.astryx-text.${cls}`) && r.includes('font-size'),
+        ),
+      ).toBe(true);
+    }
+  });
+
+  it('orders size overrides after the themed type font-size rules', () => {
+    // Source order breaks specificity ties within a layer, so the size
+    // override must come after the `.astryx-text.<type>` type rule.
+    const typeIdx = rules.findIndex(
+      r => r.includes('.astryx-text.supporting') && r.includes('font-size'),
+    );
+    const sizeIdx = rules.findIndex(
+      r => r.includes('.astryx-text.size-2xs') && r.includes('font-size'),
+    );
+    expect(typeIdx).toBeGreaterThanOrEqual(0);
+    expect(sizeIdx).toBeGreaterThan(typeIdx);
+  });
+
   // --- Consistency ---
 
   it('generateThemeCSS returns prose and component blocks with @scope', () => {
@@ -202,6 +257,16 @@ describe('generateThemeRules', () => {
       expect(combined).toContain(rule);
     }
   });
+
+  it('routes Text size overrides into the component (astryx-theme) block', () => {
+    // The size override only beats a themed type if it lands in the same
+    // layer as the type rules (astryx-theme / component block), not the
+    // reset-tier prose block.
+    const {prose, component} = generateThemeCSS(theme);
+    expect(component).toContain('.astryx-text.size-2xs');
+    expect(component).toContain('.astryx-text.xsm');
+    expect(prose).not.toContain('.astryx-text.size-2xs');
+  });
 });
 
 describe('generateThemeRules with weight overrides', () => {
@@ -320,6 +385,48 @@ describe('derived var expansion', () => {
     expect(rule).toContain('--_button-radius: 8px');
   });
 
+  it('emits internal vars for avatar fallback typography (base)', () => {
+    const theme = defineTheme({
+      name: 'test-derived-avatar',
+      components: {
+        avatar: {
+          base: {
+            fontWeight: 'var(--font-weight-normal)',
+            color: 'var(--color-text-secondary)',
+            backgroundColor: 'var(--color-accent-muted)',
+          },
+        },
+      },
+    });
+    const rules = generateThemeRules(theme);
+    const rule = rules.find(r => r.includes('.astryx-avatar'));
+    expect(rule).toBeDefined();
+    expect(rule).toContain(
+      '--_avatar-fallback-font-weight: var(--font-weight-normal)',
+    );
+    expect(rule).toContain(
+      '--_avatar-fallback-color: var(--color-text-secondary)',
+    );
+    expect(rule).toContain(
+      '--_avatar-fallback-background: var(--color-accent-muted)',
+    );
+  });
+
+  it('emits a per-size fallback font-size for avatar (size:sm)', () => {
+    const theme = defineTheme({
+      name: 'test-derived-avatar-size',
+      components: {
+        avatar: {
+          'size:sm': {fontSize: '9px'},
+        },
+      },
+    });
+    const rules = generateThemeRules(theme);
+    const rule = rules.find(r => r.includes('.astryx-avatar.sm'));
+    expect(rule).toBeDefined();
+    expect(rule).toContain('--_avatar-fallback-font-size: 9px');
+  });
+
   it('does not emit derived vars for components without registry entries', () => {
     const theme = defineTheme({
       name: 'test-no-derived',

package/src/theme/generateThemeRules.ts

@@ -301,6 +301,10 @@ export function generateThemeRules(theme: DefinedTheme): string[] {
   // 4. Prop-level color overrides (for text/heading/link specificity)
   generateColorOverrides(theme.components || {}, parts);
 
+  // 5. Text `size`-prop font-size overrides (so an explicit size beats a
+  //    themed type's font-size across the astryx-base → astryx-theme layers)
+  generateSizeOverrides(theme.components || {}, parts);
+
   // (on-media rules are generated separately — see generateOnMediaCSS)
 
   return parts;
@@ -500,6 +504,58 @@ function generateColorOverrides(
   }
 }
 
+/**
+ * Map a Text `size` prop value to its raw font-size token.
+ * Mirrors `sizeStyles` in `Text/text.stylex.ts` (note `xsm` → `--font-size-xs`).
+ * <!-- SYNC: packages/core/src/Text/text.stylex.ts (sizeStyles) -->
+ */
+const TEXT_SIZE_TOKEN_MAP: Record<string, string> = {
+  '4xs': 'var(--font-size-4xs)',
+  '3xs': 'var(--font-size-3xs)',
+  '2xs': 'var(--font-size-2xs)',
+  xsm: 'var(--font-size-xs)',
+  sm: 'var(--font-size-sm)',
+  base: 'var(--font-size-base)',
+  lg: 'var(--font-size-lg)',
+  xl: 'var(--font-size-xl)',
+  '2xl': 'var(--font-size-2xl)',
+  '3xl': 'var(--font-size-3xl)',
+  '4xl': 'var(--font-size-4xl)',
+};
+
+/**
+ * Generate `size`-prop font-size overrides for the Text component.
+ *
+ * The `size` prop is documented as a font-size override that wins over the
+ * size implied by `type`. Its StyleX class lives in `@layer astryx-base`, but a
+ * theme's per-type font-size rule (`.astryx-text.<type>`) lives in the higher
+ * `@layer astryx-theme`, so the layer cascade let the theme silently shadow
+ * `size` for any `type` the theme styled. Re-emitting the size classes here —
+ * same layer as the type rules, same `.astryx-text.<x>` specificity, later in
+ * source — restores `size` as a real override.
+ *
+ * Only `font-size` is overridden; line-height and other type properties are
+ * intentionally preserved, matching the prop's documented contract.
+ *
+ * Gated on the theme touching `text` (which includes the auto-generated
+ * type-scale rules) — with no theme type rule to beat, the base-layer StyleX
+ * class already wins and no override is needed.
+ */
+function generateSizeOverrides(
+  components: Record<string, unknown>,
+  parts: string[],
+): void {
+  if (!('text' in components)) {
+    return;
+  }
+  for (const [sizeName, sizeValue] of Object.entries(TEXT_SIZE_TOKEN_MAP)) {
+    const suffix = parseStyleKey(`size:${sizeName}`);
+    parts.push(
+      `  ${componentClassSelector('text', suffix)} { font-size: ${sizeValue}; }`,
+    );
+  }
+}
+
 /**
  * Generate theme rules split into component and prose groups.
  *

package/src/theme/hct.ts

@@ -110,7 +110,7 @@ function labToXyz(L: number, a: number, b: number): [number, number, number] {
 // Tone <-> Y (CIE Luminance)
 // =============================================================================
 
-export function toneToY(tone: number): number {
+function toneToY(tone: number): number {
   return labFInv((tone + 16) / 116);
 }
 

package/src/theme/syntax/defineSyntaxTheme.ts

@@ -12,6 +12,7 @@
  */
 
 import {syntaxTokenDefaults, type SyntaxTokenName} from './tokens';
+import {devWarn} from '../../utils/devWarning';
 
 // =============================================================================
 // Types
@@ -139,12 +140,10 @@ export function defineSyntaxTheme(
 ): SyntaxThemeDefinition {
   const missing = ALL_SYNTAX_KEYS.filter(key => !(key in input.tokens));
   if (missing.length > 0) {
-    console.warn(
-      '[Astryx] defineSyntaxTheme("' +
-        input.name +
-        '"): missing tokens: ' +
-        missing.join(', ') +
-        '. All 14 syntax tokens are required.',
+    devWarn(
+      'defineSyntaxTheme',
+      `"${input.name}": missing tokens: ${missing.join(', ')}. ` +
+        `All 14 syntax tokens are required.`,
     );
   }
 

package/src/utils/devWarning.test.ts

@@ -0,0 +1,56 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {afterEach, describe, expect, it, vi} from 'vitest';
+import {
+  devWarn,
+  devError,
+  warnOnce,
+  formatDevMessage,
+  __resetDevWarnings,
+} from './devWarning';
+
+afterEach(() => {
+  __resetDevWarnings();
+  vi.restoreAllMocks();
+});
+
+describe('formatDevMessage', () => {
+  it('formats as "Component: message"', () => {
+    expect(formatDevMessage('Field', 'oops')).toBe('Field: oops');
+  });
+});
+
+describe('devWarn', () => {
+  it('warns in the standardized format and forwards extra args', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const detail = {a: 1};
+    devWarn('Popover', 'no button', detail);
+    expect(warn).toHaveBeenCalledWith('Popover: no button', detail);
+  });
+});
+
+describe('devError', () => {
+  it('errors in the standardized format', () => {
+    const error = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const err = new Error('boom');
+    devError('Table', 'plugin threw:', err);
+    expect(error).toHaveBeenCalledWith('Table: plugin threw:', err);
+  });
+});
+
+describe('warnOnce', () => {
+  it('fires at most once per key', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    warnOnce('k', 'Theme', 'runtime injection');
+    warnOnce('k', 'Theme', 'runtime injection');
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn).toHaveBeenCalledWith('Theme: runtime injection');
+  });
+
+  it('fires again for a different key', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    warnOnce('a', 'Theme', 'one');
+    warnOnce('b', 'Theme', 'two');
+    expect(warn).toHaveBeenCalledTimes(2);
+  });
+});

package/src/utils/devWarning.ts

@@ -0,0 +1,102 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file devWarning.ts
+ * @input A component/hook name and a message
+ * @output Standardized `Component: message` console warnings and errors
+ * @position Shared dev-logging utility used across components and hooks
+ *
+ * Standardizes how the design system surfaces information to the builder:
+ * every message reads `Component: message` (e.g. `Field: isOptional and
+ * isRequired are mutually exclusive.`), so the source is always obvious in
+ * the console.
+ *
+ * Prefer the `useDevWarning` hook inside components — it guards against
+ * repeating a warning on every render. These imperative helpers exist for
+ * the non-render contexts a hook can't cover: plain functions, module
+ * initialization, and inside effects.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/utils/index.ts
+ * - /packages/core/src/hooks/useDevWarning.ts (the render-path counterpart)
+ */
+
+const isDev = process.env.NODE_ENV !== 'production';
+
+/** Format a message as `Component: message`. */
+export function formatDevMessage(component: string, message: string): string {
+  return `${component}: ${message}`;
+}
+
+/**
+ * Dev-only `console.warn` in the standardized `Component: message` format.
+ * A no-op in production — warnings are builder guardrails, not shipped noise.
+ * Extra args (e.g. an offending value) are forwarded to `console.warn`.
+ *
+ * @example
+ * ```
+ * devWarn('Popover', 'children must contain a <button>.');
+ * ```
+ */
+export function devWarn(
+  component: string,
+  message: string,
+  ...args: unknown[]
+): void {
+  if (!isDev) {
+    return;
+  }
+  console.warn(formatDevMessage(component, message), ...args);
+}
+
+/**
+ * `console.error` in the standardized `Component: message` format. Unlike
+ * {@link devWarn}, this runs in production too: it reports real runtime
+ * failures (e.g. a thrown callback) that should reach error telemetry.
+ *
+ * @example
+ * ```
+ * devError('Table', 'Plugin at index 0 threw in transform:', error);
+ * ```
+ */
+export function devError(
+  component: string,
+  message: string,
+  ...args: unknown[]
+): void {
+  console.error(formatDevMessage(component, message), ...args);
+}
+
+const warnedKeys = new Set<string>();
+
+/**
+ * Dev-only warning that fires at most once per `key` for the lifetime of the
+ * app. Use for singleton warnings that aren't tied to a component instance —
+ * a missing translation key, a per-theme perf hint, a one-time fallback.
+ * For per-component-instance warnings, use the `useDevWarning` hook instead.
+ *
+ * @example
+ * ```
+ * warnOnce(`theme:${name}`, 'Theme', `"${name}" uses runtime injection.`);
+ * ```
+ */
+export function warnOnce(
+  key: string,
+  component: string,
+  message: string,
+  ...args: unknown[]
+): void {
+  if (!isDev || warnedKeys.has(key)) {
+    return;
+  }
+  warnedKeys.add(key);
+  console.warn(formatDevMessage(component, message), ...args);
+}
+
+/**
+ * Clear `warnOnce` dedup state. Test-only.
+ * @internal
+ */
+export function __resetDevWarnings(): void {
+  warnedKeys.clear();
+}