@happyvertical/smrt-ui 0.43.4 → 0.43.6

package/AGENTS.md

@@ -112,6 +112,39 @@ other text pairing clears WCAG AA in both schemes.
   interaction registry. Keep chat/voice transports outside this package;
   mutations must retain sensitivity checks and the stage → confirmed apply
   policy.
+- Agent-originated form values remain proposals: the registry records their
+  provenance, timestamp, and revision, while `StagedControlReview` is the shared
+  review/apply surface mounted by both base and rich Forms. Agents can stage but
+  cannot self-confirm; only a local human handler submits confirmed apply,
+  discard, clear, or undo commands after the registry validates a trusted DOM
+  gesture while its event is actively dispatching. Retained events are rejected,
+  and the complete command or batch is snapshotted synchronously before gesture
+  consumption. Serialized or programmatic `source: 'user', confirmed: true`
+  input is not confirmation.
+  `StagedControlReview` marks its complete edited Apply value with
+  `reviewedValueIsCanonical: true`, but the marker grants no authority and is
+  honored only for a current staged entry under the registry's exact local
+  gesture proof. A control with proposal-relative preparation implements
+  `prepareReviewedValue` to validate/canonicalize the complete displayed value;
+  without that hook, marked edits still pass through ordinary `prepareValue`.
+  Only an unchanged value exactly equal to the stored staged canonical value can
+  reuse that trusted stored value without either hook.
+  Secret controls never accept staging, and sensitive/secret
+  values stay redacted in snapshots, events, policy callbacks, and review UI.
+  Batch execution is ordered best-effort and returns one result per command;
+  review-surface batch actions exclude stale and invalid proposals, which remain
+  visible with per-field feedback.
+  `executeBatch` is additive and optional for injected legacy registries; the
+  framework falls back to ordered `execute` calls without weakening the private
+  one-shot gesture proof on factory-created registries.
+  Rejecting async custom setters and clear handlers roll back by default;
+  controls that accept concurrent direct edits expose a monotonic revision and
+  user value from `getUserEditSnapshot()` so rollback restores newer human input;
+  fallible async setters expose an infallible `restoreValue()` path. Async hooks
+  issue nested commands through their optional final `ControlExtensionContext`;
+  same-control mutations are rejected there without timing out unrelated queued
+  commands. Context-aware setters implement the additive `setValueWithContext`
+  hook; legacy `setValue` is always invoked with exactly one argument.
 
 ## Gotchas
 

package/README.md

@@ -45,6 +45,34 @@ Svelte-free `/data-surface` entry exposes the registry contracts and shared
 protocol limits for server adapters. The package root remains a compatibility
 barrel.
 
+### Currency display
+
+`CurrencyDisplay` accepts ISO 4217 codes as a public `string` prop so persisted
+Commerce currency fields can be passed directly. Codes are trimmed and
+uppercased before `Intl.NumberFormat` formatting; the default remains CAD.
+Malformed or unsupported codes render an accessible inline error instead of
+throwing and interrupting a surrounding collection render.
+With the default historical `unit="cents"` setting, amounts are interpreted as
+the selected currency's ISO minor units (for example, 0 digits for JPY and 3
+for BHD). Minor-unit amounts must be finite safe integers; fractional or unsafe
+numeric values render an accessible inline error instead of being rounded.
+`unit="dollars"` means the value is already in major units.
+ISO fund, metal, test, and no-currency codes whose minor unit is `N.A.` require
+`unit="dollars"`; the default minor-unit mode renders an accessible inline
+error for those codes. Major-unit values for these codes use a stable two-digit
+display policy across server and browser runtimes. CAD and USD retain their
+symbol display; all other codes render their ISO code so SSR output does not
+depend on runtime-specific symbol data.
+
+```svelte
+<script lang="ts">
+  import { CurrencyDisplay } from '@happyvertical/smrt-ui';
+  let invoiceCurrency: string = 'eur';
+</script>
+
+<CurrencyDisplay amount={12345} currency={invoiceCurrency} />
+```
+
 ## Component standard
 
 Foundation components follow one contract:
@@ -99,10 +127,56 @@ without coupling controls to a transport:
 ```
 
 Controls publish serializable metadata, constraints, options, sensitivity, and
-capabilities. Adapters can focus, reveal, highlight, explain, validate, stage,
-apply, clear, or undo. Agent mutations are denied for secret/read-only controls
-and require explicit confirmation before apply, clear, or undo. Staging is
-separate so the UI can show a proposal before it changes user state.
+capabilities. Adapters can focus, reveal, highlight, explain, validate, and
+stage reviewable proposals. Agents cannot apply, discard, clear, or undo;
+those value-changing actions require a trusted local gesture handled by the
+framework review surface. Secret/read-only controls reject agent mutations.
+Staging remains separate so proposals never change user state before review.
+Custom local review controls can call `executeLocalControlCommand` or
+`executeLocalControlBatch` synchronously from their DOM handlers; the registry
+requires the event to still be actively dispatching, snapshots the complete
+command, and consumes the gesture before authorizing a value-changing command.
+Retaining an event for later use is rejected even when it remains trusted.
+Serialized or programmatic `source: 'user', confirmed: true` input is never
+confirmation. Sensitive and secret values, validation details, failures, and
+events remain redacted from every public surface.
+The shared review surface marks its complete edited Apply value with
+`reviewedValueIsCanonical: true`. That marker carries no authority: the registry
+honors it only for a current staged entry after validating the exact command
+under an actively dispatching local gesture. Controls with non-idempotent
+proposal preparation can implement `prepareReviewedValue(value)` to validate or
+canonicalize the complete displayed value without re-applying proposal-relative
+behavior. Controls without that hook route marked edits through their ordinary
+`prepareValue`, so a generic marker never bypasses custom normalization or
+rejection. An unchanged value exactly equal to the stored staged canonical value
+uses that trusted stored value directly.
+Registries expose optional `refresh(formId)` notification for hosts whose live
+metadata or runtime-state getters change without a registration event; it
+updates subscribers without discarding an internal staged proposal.
+`executeBatch` is an additive optional registry method; Forms fall back to
+ordered `execute` calls for older injected registries. Factory-created
+registries retain the framework's private, one-shot gesture proof, while an
+older custom registry remains responsible for its pre-existing execution
+policy and accepts review actions only from a trusted browser event.
+Custom controls whose clear operation is intentionally idempotent should return
+`true` from `clear()` to affirm that the unchanged cleared value was accepted.
+Async custom setters and clear handlers are rolled back when they reject. A
+control that permits direct edits while an async mutation is pending can expose
+`getUserEditSnapshot()` and update its revision and value only for direct user
+edits so rollback restores newer human input even if the handler mutates again
+before rejecting. A fallible async setter should also expose `restoreValue()` as
+an infallible state restoration path that does not repeat the external workflow.
+Async policy, validation, setter, clear, and restoration hooks receive an
+optional final `ControlExtensionContext`. Hooks that need to issue another
+control command should use `extension.execute()`; it rejects a mutation of the
+same control immediately, while commands from independent callers remain in
+the normal ordered queue regardless of how long the hook takes. Existing hooks
+that omit the additional argument remain compatible. Setters retain their exact
+legacy `setValue(value)` invocation; a setter that needs this context implements
+the additive `setValueWithContext(value, extension)` hook instead. A hook must
+not await a same-control mutation through a captured registry reference: that
+call is indistinguishable from an independent caller in browser runtimes and,
+like any hook that never settles, can hold the ordered queue indefinitely.
 
 ## DataTable controller
 

package/dist/components/display/CurrencyDisplay.contract.d.ts

@@ -0,0 +1,7 @@
+import type { ComponentProps } from 'svelte';
+import type CurrencyDisplay from './CurrencyDisplay.svelte';
+type Assert<T extends true> = T;
+/** Compile-time guard for Commerce models whose currency field is `string`. */
+export type CurrencyDisplayAcceptsCommerceCurrency = Assert<string extends NonNullable<ComponentProps<typeof CurrencyDisplay>['currency']> ? true : false>;
+export {};
+//# sourceMappingURL=CurrencyDisplay.contract.d.ts.map

package/dist/components/display/CurrencyDisplay.contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CurrencyDisplay.contract.d.ts","sourceRoot":"","sources":["../../../src/components/display/CurrencyDisplay.contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAC7C,OAAO,KAAK,eAAe,MAAM,0BAA0B,CAAC;AAE5D,KAAK,MAAM,CAAC,CAAC,SAAS,IAAI,IAAI,CAAC,CAAC;AAEhC,+EAA+E;AAC/E,MAAM,MAAM,sCAAsC,GAAG,MAAM,CACzD,MAAM,SAAS,WAAW,CAAC,cAAc,CAAC,OAAO,eAAe,CAAC,CAAC,UAAU,CAAC,CAAC,GAC1E,IAAI,GACJ,KAAK,CACV,CAAC"}

package/dist/components/display/CurrencyDisplay.contract.js

@@ -0,0 +1 @@
+export {};

package/dist/components/display/CurrencyDisplay.svelte

@@ -1,19 +1,89 @@
+<script module lang="ts">
+import { ISO_4217_MINOR_UNITS } from './currency-metadata.js';
+
+interface NormalizedCurrency {
+  code: string;
+  minorUnitDigits: number | null;
+}
+
+function normalizeCurrencyCode(value: unknown): NormalizedCurrency | null {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  if (!/^[A-Za-z]{3}$/.test(trimmed)) return null;
+  const code = trimmed.toUpperCase();
+
+  const minorUnitDigits = ISO_4217_MINOR_UNITS.get(code);
+  return minorUnitDigits === undefined ? null : { code, minorUnitDigits };
+}
+
+function invalidCurrencyCode(value: unknown): string {
+  if (typeof value !== 'string') return '(non-string)';
+  const characters = Array.from(value.trim());
+  if (characters.length === 0) return '(empty)';
+
+  let diagnostic = '';
+  let consumed = 0;
+  for (const character of characters) {
+    const codePoint = character.codePointAt(0);
+    if (codePoint === undefined) continue;
+    const visibleCharacter =
+      codePoint >= 0x20 && codePoint <= 0x7e
+        ? character.replace(/[a-z]/g, (ascii) => ascii.toUpperCase())
+        : `\\u{${codePoint.toString(16).toUpperCase()}}`;
+    if (diagnostic.length + visibleCharacter.length > 12) break;
+    diagnostic += visibleCharacter;
+    consumed += 1;
+  }
+
+  return consumed < characters.length ? `${diagnostic}…` : diagnostic;
+}
+
+function isStringNumericLiteral(
+  value: string,
+): value is Intl.StringNumericLiteral {
+  return /^(?:0|[1-9]\d*)\.\d+$/.test(value);
+}
+
+function exactMajorUnitValue(
+  amount: number,
+  minorUnitDigits: number,
+): bigint | Intl.StringNumericLiteral | null {
+  const absoluteAmount = Math.abs(amount);
+  if (!Number.isSafeInteger(absoluteAmount)) return null;
+
+  const minorUnits = BigInt(absoluteAmount);
+  if (minorUnitDigits === 0) return minorUnits;
+
+  const scale = 10n ** BigInt(minorUnitDigits);
+  const exactValue = `${minorUnits / scale}.${(minorUnits % scale)
+    .toString()
+    .padStart(minorUnitDigits, '0')}`;
+  return isStringNumericLiteral(exactValue) ? exactValue : null;
+}
+</script>
+
 <script lang="ts">
+import { M } from '../../i18n/strings.js';
+import { useI18n } from '../../i18n/use-i18n.js';
+
 /**
  * CurrencyDisplay - Formats and displays monetary values
  *
  * Displays formatted currency with configurable unit.
- * Use `unit="cents"` (default) when amount is in cents, or `unit="dollars"` for dollar values.
- * Supports CAD/USD with appropriate symbols and locale formatting.
+ * Use `unit="cents"` (default) when amount is in the currency's minor units,
+ * or `unit="dollars"` when it is already in major units.
+ * Accepts ISO 4217 currency codes, normalized by trimming whitespace and
+ * uppercasing before locale formatting. Unsupported codes render an accessible
+ * inline error instead of throwing during a collection render.
  */
 
 /** Props for CurrencyDisplay component */
 export interface Props {
   /** Amount value */
   amount: number;
-  /** Currency code */
-  currency?: 'CAD' | 'USD';
-  /** Whether amount is in cents or dollars (default: cents) */
+  /** ISO 4217 currency code. Whitespace is trimmed and letters are uppercased. */
+  currency?: string;
+  /** Whether amount is a safe integer of ISO minor units or a major-unit number */
   unit?: 'cents' | 'dollars';
   /** Show +/- sign for non-zero values */
   showSign?: boolean;
@@ -38,19 +108,75 @@ const {
   class: className = '',
 }: Props = $props();
 
-// Format amount using Intl.NumberFormat
-const formatted = $derived.by(() => {
-  const dollars = unit === 'cents' ? amount / 100 : amount;
-  const absValue = Math.abs(dollars);
+const { t } = useI18n();
+
+interface FormattedCurrency {
+  text: string;
+  invalidCode: string | null;
+}
+
+// Format amount using the platform's canonical currency formatter.
+const formatted = $derived.by((): FormattedCurrency => {
+  const normalizedCurrency = normalizeCurrencyCode(currency);
+  if (!normalizedCurrency) {
+    const invalidCode = invalidCurrencyCode(currency);
+    return {
+      text: t(M['ui.currency_display.invalid_code'], { code: invalidCode }),
+      invalidCode,
+    };
+  }
 
-  const formatter = new Intl.NumberFormat('en-CA', {
+  const formatOptions: Intl.NumberFormatOptions = {
     style: 'currency',
-    currency,
-    minimumFractionDigits: 2,
-    maximumFractionDigits: 2,
-  });
+    currency: normalizedCurrency.code,
+    // CAD and USD retain their historical symbol display. Using the ISO code
+    // for every other currency avoids ICU-dependent narrow-symbol differences
+    // between server and browser runtimes.
+    currencyDisplay:
+      normalizedCurrency.code === 'CAD' || normalizedCurrency.code === 'USD'
+        ? 'symbol'
+        : 'code',
+  };
+  const displayDigits = normalizedCurrency.minorUnitDigits ?? 2;
+  formatOptions.minimumFractionDigits = displayDigits;
+  formatOptions.maximumFractionDigits = displayDigits;
+
+  let formatter: Intl.NumberFormat;
+  try {
+    formatter = new Intl.NumberFormat('en-CA', formatOptions);
+  } catch {
+    return {
+      text: t(M['ui.currency_display.invalid_code'], {
+        code: normalizedCurrency.code,
+      }),
+      invalidCode: normalizedCurrency.code,
+    };
+  }
 
-  let display = formatter.format(absValue);
+  let majorAmount: number | bigint | Intl.StringNumericLiteral =
+    Math.abs(amount);
+  if (unit === 'cents') {
+    if (normalizedCurrency.minorUnitDigits == null) {
+      return {
+        text: t(M['ui.currency_display.no_minor_unit'], {
+          code: normalizedCurrency.code,
+        }),
+        invalidCode: normalizedCurrency.code,
+      };
+    }
+    const exactAmount = exactMajorUnitValue(
+      amount,
+      normalizedCurrency.minorUnitDigits,
+    );
+    if (exactAmount === null) {
+      return {
+        text: t(M['ui.currency_display.invalid_minor_unit_amount']),
+        invalidCode: normalizedCurrency.code,
+      };
+    }
+    majorAmount = exactAmount;
+  }
+  let display = formatter.format(majorAmount);
 
   // Add sign if requested
   if (showSign && amount !== 0) {
@@ -60,7 +186,7 @@ const formatted = $derived.by(() => {
     display = `-${display}`;
   }
 
-  return display;
+  return { text: display, invalidCode: null };
 });
 
 // Determine color class
@@ -77,8 +203,9 @@ const colorClass = $derived.by(() => {
   class:lg={size === 'lg'}
   class:negative={colorClass === 'negative'}
   class:positive={colorClass === 'positive'}
+  class:invalid={formatted.invalidCode !== null}
 >
-  {formatted}
+  {formatted.text}
 </span>
 
 <style>
@@ -103,4 +230,8 @@ const colorClass = $derived.by(() => {
   .currency-display.positive {
     color: var(--smrt-color-tertiary, #16a34a);
   }
+
+  .currency-display.invalid {
+    color: var(--smrt-color-error, #dc2626);
+  }
 </style>

package/dist/components/display/CurrencyDisplay.svelte.d.ts

@@ -2,16 +2,19 @@
  * CurrencyDisplay - Formats and displays monetary values
  *
  * Displays formatted currency with configurable unit.
- * Use `unit="cents"` (default) when amount is in cents, or `unit="dollars"` for dollar values.
- * Supports CAD/USD with appropriate symbols and locale formatting.
+ * Use `unit="cents"` (default) when amount is in the currency's minor units,
+ * or `unit="dollars"` when it is already in major units.
+ * Accepts ISO 4217 currency codes, normalized by trimming whitespace and
+ * uppercasing before locale formatting. Unsupported codes render an accessible
+ * inline error instead of throwing during a collection render.
  */
 /** Props for CurrencyDisplay component */
 export interface Props {
     /** Amount value */
     amount: number;
-    /** Currency code */
-    currency?: 'CAD' | 'USD';
-    /** Whether amount is in cents or dollars (default: cents) */
+    /** ISO 4217 currency code. Whitespace is trimmed and letters are uppercased. */
+    currency?: string;
+    /** Whether amount is a safe integer of ISO minor units or a major-unit number */
     unit?: 'cents' | 'dollars';
     /** Show +/- sign for non-zero values */
     showSign?: boolean;

package/dist/components/display/CurrencyDisplay.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CurrencyDisplay.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/display/CurrencyDisplay.svelte.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AAEH,0CAA0C;AAC1C,MAAM,WAAW,KAAK;IACpB,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,oBAAoB;IACpB,QAAQ,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC;IACzB,6DAA6D;IAC7D,IAAI,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3B,wCAAwC;IACxC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,mBAAmB;IACnB,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAC1B,uCAAuC;IACvC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,yCAAyC;IACzC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,yBAAyB;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAwDD,QAAA,MAAM,eAAe,2CAAwC,CAAC;AAC9D,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC;AAC1D,eAAe,eAAe,CAAC"}
+{"version":3,"file":"CurrencyDisplay.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/display/CurrencyDisplay.svelte.ts"],"names":[],"mappings":"AAsEA;;;;;;;;;GASG;AAEH,0CAA0C;AAC1C,MAAM,WAAW,KAAK;IACpB,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,IAAI,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3B,wCAAwC;IACxC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,mBAAmB;IACnB,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAC1B,uCAAuC;IACvC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,yCAAyC;IACzC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,yBAAyB;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAqHD,QAAA,MAAM,eAAe,2CAAwC,CAAC;AAC9D,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC;AAC1D,eAAe,eAAe,CAAC"}

package/dist/components/display/__tests__/CurrencyDisplay.test.js

@@ -8,20 +8,39 @@
  * code, sign handling (negative/zero/showSign), highlight classes, size
  * classes, and axe-cleanliness.
  */
+import { createHash } from 'node:crypto';
+import { svelte } from '@sveltejs/vite-plugin-svelte';
 import { render, screen } from '@testing-library/svelte';
+import { hydrate, unmount } from 'svelte';
+import { createServer } from 'vite';
 import { describe, expect, it } from 'vitest';
 import { expectNoA11yViolations } from '../../../test-support/a11y';
 import CurrencyDisplay from '../CurrencyDisplay.svelte';
+import { ISO_4217_MINOR_UNITS } from '../currency-metadata.js';
+import CurrencyDisplayI18nHarness from './CurrencyDisplayI18nHarness.svelte';
+import CurrencyDisplaySsrHarness from './CurrencyDisplaySsrHarness.svelte';
+function metadataDigest(metadata) {
+    const canonical = [...metadata.entries()]
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([code, minorUnits]) => `${code}:${minorUnits ?? 'N.A.'}`)
+        .join('\n');
+    return createHash('sha256').update(canonical).digest('hex');
+}
 /** Mirror the component's absolute-value currency formatting. */
-function money(absDollars, currency = 'CAD') {
+function money(absDollars, currency = 'CAD', minorUnitDigits) {
     return new Intl.NumberFormat('en-CA', {
         style: 'currency',
         currency,
-        minimumFractionDigits: 2,
-        maximumFractionDigits: 2,
+        currencyDisplay: currency === 'CAD' || currency === 'USD' ? 'symbol' : 'code',
+        minimumFractionDigits: minorUnitDigits,
+        maximumFractionDigits: minorUnitDigits,
     }).format(absDollars);
 }
 describe('CurrencyDisplay', () => {
+    it('matches the canonical digest of SIX List One 2026-01-01', () => {
+        expect(ISO_4217_MINOR_UNITS.size).toBe(178);
+        expect(metadataDigest(ISO_4217_MINOR_UNITS)).toBe('e1a3c502511fa784b38dd7ac2b4056d00f3f1a9f5781df93b0f2352f8eedc976');
+    });
     it('formats cents into dollars by default', () => {
         render(CurrencyDisplay, { props: { amount: 12345 } }); // cents → $123.45
         expect(screen.getByText(money(123.45))).toBeInTheDocument();
@@ -44,6 +63,142 @@ describe('CurrencyDisplay', () => {
         });
         expect(screen.getByText(money(1000, 'USD'))).toBeInTheDocument();
     });
+    it('formats an EUR amount through the public string currency prop', () => {
+        const commerceCurrency = 'EUR';
+        const { container } = render(CurrencyDisplay, {
+            props: { amount: 12345, currency: commerceCurrency },
+        });
+        expect(container.querySelector('span')?.textContent).toBe(money(123.45, 'EUR'));
+    });
+    it.each([
+        ['JPY', 12345, '12,345'],
+        ['BHD', 12345, '12.345'],
+        ['IQD', 12345, '12.345'],
+    ])('uses the ISO minor-unit scale for %s', (currency, amount, expected) => {
+        const { container } = render(CurrencyDisplay, {
+            props: { amount, currency },
+        });
+        expect(container.querySelector('span')?.textContent).toContain(expected);
+    });
+    it.each([
+        ['IQD', 3, '9,007,199,254,740.991'],
+        ['AFN', 2, '90,071,992,547,409.91'],
+        ['CLF', 4, '900,719,925,474.0991'],
+    ])('preserves the least-significant minor unit for large safe %s values', (currency, digits, expected) => {
+        const { container } = render(CurrencyDisplay, {
+            props: { amount: Number.MAX_SAFE_INTEGER, currency },
+        });
+        const text = container.querySelector('span')?.textContent;
+        expect(text).toContain(expected);
+        expect(text?.split('.').at(-1)).toHaveLength(digits);
+    });
+    it.each([
+        ['positive fractional', 1.5],
+        ['negative fractional', -1.5],
+        ['unsafe positive integer', Number.MAX_SAFE_INTEGER + 1],
+        ['unsafe negative integer', -(Number.MAX_SAFE_INTEGER + 1)],
+        ['NaN', Number.NaN],
+        ['positive infinity', Number.POSITIVE_INFINITY],
+        ['negative infinity', Number.NEGATIVE_INFINITY],
+    ])('rejects a %s amount in minor-unit mode', (_scenario, amount) => {
+        const { container } = render(CurrencyDisplay, {
+            props: { amount, currency: 'CAD' },
+        });
+        const display = container.querySelector('.currency-display');
+        expect(display).toHaveClass('invalid');
+        expect(display).toHaveTextContent('Invalid minor-unit amount');
+    });
+    it('preserves a negative safe integer through the exact string formatter path', () => {
+        const { container } = render(CurrencyDisplay, {
+            props: { amount: -Number.MAX_SAFE_INTEGER, currency: 'IQD' },
+        });
+        const text = container.querySelector('span')?.textContent;
+        expect(text).toContain('9,007,199,254,740.991');
+        expect(text?.startsWith('-IQD')).toBe(true);
+    });
+    it.each([
+        ['cad', 'CAD'],
+        ['  eur  ', 'EUR'],
+        ['ved', 'VED'],
+        ['xad', 'XAD'],
+    ])('normalizes the currency code %j to %s', (currency, normalized) => {
+        const { container } = render(CurrencyDisplay, {
+            props: { amount: 12345, currency },
+        });
+        expect(container.querySelector('span')?.textContent).toBe(money(123.45, normalized, 2));
+    });
+    it.each([
+        'US',
+        'AAA',
+        'ANG',
+        'BGN',
+        'CUC',
+        'HRK',
+        'SLL',
+        'ZWL',
+        'ZZZ',
+        '',
+    ])('renders invalid code %j without throwing', (currency) => {
+        const { container } = render(CurrencyDisplay, {
+            props: { amount: 12345, currency },
+        });
+        const normalized = currency
+            .trim()
+            .replace(/[a-z]/g, (character) => character.toUpperCase()) || '(empty)';
+        const display = container.querySelector('.currency-display');
+        expect(display).toHaveClass('invalid');
+        expect(display).toHaveTextContent(`Invalid currency code: ${normalized}`);
+    });
+    it.each([
+        ['uſd', 'U\\u{17F}D'],
+        ['ıqd', '\\u{131}QD'],
+        ['ßp', '\\u{DF}P'],
+        ['U\u200bSD', 'U\\u{200B}SD'],
+        ['USD\u202e', 'USD\\u{202E}'],
+        ['U\u2066SD', 'U\\u{2066}SD'],
+    ])('renders rejected non-ASCII input %j visibly as %s', (currency, diagnostic) => {
+        const { container } = render(CurrencyDisplay, {
+            props: { amount: 12345, currency },
+        });
+        expect(container.querySelector('.currency-display')).toHaveTextContent(`Invalid currency code: ${diagnostic}`);
+    });
+    it('bounds escaped astral input without splitting a code-point token', () => {
+        const { container } = render(CurrencyDisplay, {
+            props: { amount: 12345, currency: '😀😀' },
+        });
+        expect(container.querySelector('.currency-display')).toHaveTextContent('Invalid currency code: \\u{1F600}…');
+    });
+    it('bounds malformed currency text so one row cannot force table overflow', () => {
+        const { container } = render(CurrencyDisplay, {
+            props: { amount: 12345, currency: 'invalid-currency-code' },
+        });
+        expect(container.querySelector('.currency-display')).toHaveTextContent('Invalid currency code: INVALID-CURR…');
+    });
+    it('rejects a non-string currency from an untyped runtime caller without throwing', () => {
+        const { container } = render(CurrencyDisplay, {
+            // @ts-expect-error JavaScript callers can pass values outside the public type.
+            props: { amount: 12345, currency: null },
+        });
+        const display = container.querySelector('.currency-display');
+        expect(display).toHaveClass('invalid');
+        expect(display).toHaveTextContent('Invalid currency code: (non-string)');
+    });
+    it('requires major-unit input for ISO codes without a minor unit', async () => {
+        const { rerender } = render(CurrencyDisplay, {
+            props: { amount: 12.5, currency: 'XAU' },
+        });
+        const display = document.querySelector('.currency-display');
+        expect(display).toHaveClass('invalid');
+        expect(display).toHaveTextContent('Currency code has no minor unit: XAU');
+        await rerender({ amount: 12.5, currency: 'XAU', unit: 'dollars' });
+        expect(document.querySelector('.currency-display')?.textContent).toBe(money(12.5, 'XAU', 2));
+    });
+    it('resolves invalid-code prose through the active i18n snapshot', () => {
+        render(CurrencyDisplayI18nHarness);
+        expect(screen.getByText('Code monétaire invalide : ZZZ')).toBeVisible();
+        expect(screen.getByText('Devise sans unité mineure : XAU')).toBeVisible();
+        expect(screen.getByText('Montant en unité mineure invalide')).toBeVisible();
+    });
     it('shows an explicit + sign for positive amounts when showSign is set', () => {
         render(CurrencyDisplay, {
             props: { amount: 1000, unit: 'dollars', showSign: true },
@@ -111,4 +266,39 @@ describe('CurrencyDisplay', () => {
         });
         await expectNoA11yViolations(container);
     });
+    it('is axe-clean for an invalid currency code', async () => {
+        const { container } = render(CurrencyDisplay, {
+            props: { amount: 12345, currency: 'ZZZ' },
+        });
+        await expectNoA11yViolations(container);
+    });
+    it('renders and hydrates valid and invalid currencies safely', async () => {
+        const vite = await createServer({
+            appType: 'custom',
+            configFile: false,
+            plugins: [svelte()],
+            root: process.cwd(),
+            server: { middlewareMode: true },
+        });
+        try {
+            const { default: SsrHarness } = await vite.ssrLoadModule('/src/components/display/__tests__/CurrencyDisplaySsrHarness.svelte');
+            const { render: renderSsr } = await vite.ssrLoadModule('svelte/server');
+            const result = renderSsr(SsrHarness);
+            expect(result.body).toContain(money(123.45, 'EUR'));
+            expect(result.body).toContain('Invalid currency code: ZZZ');
+            expect(result.body).toContain('Currency code has no minor unit: XAU');
+            const host = document.createElement('div');
+            host.innerHTML = result.body;
+            document.body.append(host);
+            const instance = hydrate(CurrencyDisplaySsrHarness, { target: host });
+            expect(host.textContent).toContain(money(123.45, 'EUR'));
+            expect(host.textContent).toContain('Invalid currency code: ZZZ');
+            expect(host.textContent).toContain('Currency code has no minor unit: XAU');
+            await unmount(instance);
+            host.remove();
+        }
+        finally {
+            await vite.close();
+        }
+    });
 });

package/dist/components/display/__tests__/CurrencyDisplayI18nHarness.svelte

@@ -0,0 +1,20 @@
+<script lang="ts">
+import { createI18nContext, setI18nContext } from '../../../i18n/index.js';
+import CurrencyDisplay from '../CurrencyDisplay.svelte';
+
+setI18nContext(
+  createI18nContext({
+    locale: 'fr',
+    messages: {
+      'ui.currency_display.invalid_code': 'Code monétaire invalide : {code}',
+      'ui.currency_display.invalid_minor_unit_amount':
+        'Montant en unité mineure invalide',
+      'ui.currency_display.no_minor_unit': 'Devise sans unité mineure : {code}',
+    },
+  }),
+);
+</script>
+
+<CurrencyDisplay amount={12345} currency="ZZZ" />
+<CurrencyDisplay amount={12345} currency="XAU" />
+<CurrencyDisplay amount={1.5} currency="CAD" />

package/dist/components/display/__tests__/CurrencyDisplayI18nHarness.svelte.d.ts

@@ -0,0 +1,19 @@
+interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
+    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
+        $$bindings?: Bindings;
+    } & Exports;
+    (internal: unknown, props: {
+        $$events?: Events;
+        $$slots?: Slots;
+    }): Exports & {
+        $set?: any;
+        $on?: any;
+    };
+    z_$$bindings?: Bindings;
+}
+declare const CurrencyDisplayI18nHarness: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type CurrencyDisplayI18nHarness = InstanceType<typeof CurrencyDisplayI18nHarness>;
+export default CurrencyDisplayI18nHarness;
+//# sourceMappingURL=CurrencyDisplayI18nHarness.svelte.d.ts.map