@12-apps/ui 1.6.0 → 1.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/ui",
-  "version": "1.6.0",
+  "version": "1.6.2",
   "license": "MIT",
   "packageManager": "pnpm@9.0.0",
   "type": "module",
@@ -194,7 +194,7 @@
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@12-apps/forms-core": "^1.5.0",
+    "@12-apps/forms-core": "^1.5.2",
     "@emotion/react": "^11.14.0",
     "@emotion/styled": "^11.14.0",
     "@monaco-editor/react": "^4.7.0",
@@ -209,8 +209,8 @@
     "recharts": "^3.5.1"
   },
   "devDependencies": {
-    "@12-apps/eslint-config": "^1.6.0",
-    "@12-apps/typescript-config": "^1.6.0",
+    "@12-apps/eslint-config": "^1.6.2",
+    "@12-apps/typescript-config": "^1.6.2",
     "@playwright/test": "^1.55.0",
     "@storybook/addon-docs": "^9.1.10",
     "@storybook/addon-links": "^9.1.10",

package/src/components/data-display/DataViews/data-views-day-input.tsx

@@ -0,0 +1,133 @@
+'use client';
+
+/**
+ * A day bound as a MASKED `dd/mm/aaaa` text field, replacing `<input type="date">`.
+ *
+ * The native control is three separate segments wearing one box. Typing a date
+ * means filling a segment, being jumped to the next, and starting over — and
+ * which segment comes first is the BROWSER's locale, not ours, so the same
+ * field reads `dd/mm/aaaa` for one merchant and `mm/dd/yyyy` for the next with
+ * nothing in our code saying which. There is no way to type a date as one
+ * continuous run of digits, which is how people actually type dates.
+ *
+ * A mask gives that back: eight digits straight through, separators inserted as
+ * you go, backspace walking back through them.
+ *
+ * Measured, driving both controls in Chromium with the same eight keystrokes
+ * (`01072026`, one `keydown` at a time):
+ *
+ *   native  →  field ends EMPTY, no filter applied, 0 requests
+ *   masked  →  field reads `01/07/2026`, filter applied, 1 request
+ *
+ * The native result is the whole complaint: you type a date and nothing lands.
+ *
+ * The second half of the fix is WHEN the bound is written. A partially-typed
+ * year is itself a valid date — `2026` passes through `0002`, `0020`, `0202` on
+ * the way — so committing on every keystroke would send the grid off to fetch
+ * years nobody meant. A bound is written only once the text is a WHOLE, real
+ * date, which is what keeps the run above at one request rather than four.
+ */
+import { TextField } from '@mui/material';
+import React, { useEffect, useState } from 'react';
+
+/** `AAAA-MM-DD` (the wire) → `dd/mm/aaaa` (what the merchant reads). */
+export function isoToBr(iso: string): string {
+  const parts = /^(\d{4})-(\d{2})-(\d{2})$/.exec(iso);
+  return parts ? `${parts[3]}/${parts[2]}/${parts[1]}` : '';
+}
+
+/**
+ * `dd/mm/aaaa` → `AAAA-MM-DD`, but ONLY for a day that exists. `31/02/2026`
+ * parses fine as three numbers and is not a date, and `Date` would silently
+ * roll it into March rather than reject it — so the round trip through UTC is
+ * the check: if the month or day comes back changed, the input was not a day.
+ */
+export function brToIso(text: string): string {
+  const parts = /^(\d{2})\/(\d{2})\/(\d{4})$/.exec(text);
+  if (!parts) return '';
+  const [, dd, mm, yyyy] = parts;
+  const day = Number(dd);
+  const month = Number(mm);
+  const year = Number(yyyy);
+  if (year < 1000) return '';
+  const probe = new Date(Date.UTC(year, month - 1, day));
+  if (probe.getUTCMonth() !== month - 1 || probe.getUTCDate() !== day) return '';
+  return `${yyyy}-${mm}-${dd}`;
+}
+
+/**
+ * Digits only, capped at eight, with the separators put back as you type.
+ *
+ * Deriving the whole string from the digits — rather than editing the text in
+ * place — is what makes backspace behave. Four digits render as `06/08`, not
+ * `06/08/`, so deleting the first digit of the year removes the trailing
+ * separator with it instead of leaving a dead keystroke that changes nothing.
+ */
+export function maskBrDate(raw: string): string {
+  const digits = raw.replace(/\D/g, '').slice(0, 8);
+  if (digits.length <= 2) return digits;
+  if (digits.length <= 4) return `${digits.slice(0, 2)}/${digits.slice(2)}`;
+  return `${digits.slice(0, 2)}/${digits.slice(2, 4)}/${digits.slice(4)}`;
+}
+
+/**
+ * One end of a day window. The BOUND stays `AAAA-MM-DD` — the form the backend's
+ * inclusive day comparison already speaks, and the form the chip label reads —
+ * so only the typing surface changes.
+ */
+export function DayBoundInput({
+  label,
+  value,
+  onChange,
+  testId,
+}: {
+  label: string;
+  /** The applied bound, `AAAA-MM-DD`, or undefined when this end is open. */
+  value: string | undefined;
+  onChange: (bound: string | undefined) => void;
+  testId: string;
+}): React.JSX.Element {
+  const applied = value ?? '';
+  const [text, setText] = useState(() => isoToBr(applied));
+
+  // The bound is the APPLIED filter; `text` is what is being typed. Re-sync only
+  // when the applied value moved somewhere the text does not already mean — a
+  // "Limpar", a saved view, the other pill resetting the pair. Without that
+  // guard the field's own write bounces straight back mid-edit and resets the
+  // caret, which is the native control's worst habit reproduced by hand.
+  useEffect(() => {
+    setText((current) => (brToIso(current) === applied ? current : isoToBr(applied)));
+  }, [applied]);
+
+  return (
+    <TextField
+      size="small"
+      type="text"
+      label={label}
+      // The mask IS the placeholder, so the expected order is on screen before
+      // the first keystroke rather than discovered by getting it wrong.
+      placeholder="dd/mm/aaaa"
+      // A numeric keypad on a phone, while still accepting a paste with slashes.
+      inputMode="numeric"
+      value={text}
+      onChange={(event) => {
+        const next = maskBrDate(event.target.value);
+        setText(next);
+        // Emptying clears the bound. A COMPLETE day applies it. A partial one
+        // does NEITHER — it leaves whatever is applied alone, so typing is never
+        // fought and a half-typed year never reaches the backend.
+        if (next === '') return onChange(undefined);
+        const iso = brToIso(next);
+        if (iso) onChange(iso);
+      }}
+      // Leaving a half-typed (or impossible) date on screen would show a filter
+      // the list is not actually using. On blur the field snaps back to what IS
+      // applied; a complete date already equals it, so this only ever tidies.
+      onBlur={() => setText(isoToBr(applied))}
+      // The placeholder occupies the space an un-shrunk label would render into.
+      InputLabelProps={{ shrink: true }}
+      inputProps={{ 'data-testid': testId, maxLength: 10 }}
+      sx={{ width: 165 }}
+    />
+  );
+}

package/src/components/data-display/DataViews/data-views-number-input.tsx

@@ -0,0 +1,157 @@
+'use client';
+
+/**
+ * A numeric bound typed the way Brazilians write numbers, replacing
+ * `<input type="number">`.
+ *
+ * The native control parses in the BROWSER's locale, and it does not fail
+ * loudly when the text does not match — it drops what it cannot read and keeps
+ * the rest. Typing `50,00` into it, measured in Chromium:
+ *
+ *     digitado "50,00"  ->  campo "5000"   ->  filtro R$ 5.000
+ *     digitado "17,50"  ->  campo "1750"   ->  filtro R$ 1.750
+ *     digitado "50.00"  ->  campo "500"    ->  filtro R$ 500
+ *
+ * The comma is deleted and the digits close ranks, so the merchant asks for
+ * fifty reais and gets a filter a HUNDRED times larger. The list empties, the
+ * chip reads `Valor: ≥ R$ 5000`, and nothing on screen connects that to the
+ * `50,00` they typed. It reads as "the value filter is broken", which is how it
+ * was reported.
+ *
+ * So the field parses pt-BR itself: `,` is the decimal separator and `.` groups
+ * thousands, which is what `R$ 1.234,56` means to the person reading it. A
+ * plain `50` still works, and so does `50.00` — a dot with exactly two digits
+ * after it is far more likely to be a decimal typed on a numeric keypad than a
+ * thousands group, and reading it as `5000` is the very failure this replaces.
+ */
+import { Box, TextField } from '@mui/material';
+import React, { useEffect, useState } from 'react';
+
+/** Everything this field lets through: digits and the two separators. */
+const ALLOWED = /[^\d.,]/g;
+
+/**
+ * pt-BR text → number, or `undefined` when it is not one (yet).
+ *
+ * `.` is a thousands group and `,` is the decimal point, EXCEPT when a lone dot
+ * is followed by one or two digits and no comma is present — `50.00` and `1.5`
+ * are decimals somebody typed, while `1.234` is a thousand.
+ */
+export function parsePtBrNumber(text: string): number | undefined {
+  const cleaned = text.replace(ALLOWED, '');
+  if (cleaned === '') return undefined;
+  const hasComma = cleaned.includes(',');
+  const dots = cleaned.split('.').length - 1;
+  const lastDot = cleaned.lastIndexOf('.');
+  const dotIsDecimal =
+    !hasComma && dots === 1 && cleaned.length - lastDot - 1 > 0 && cleaned.length - lastDot - 1 <= 2;
+  const normalized = dotIsDecimal
+    ? cleaned
+    : cleaned.replace(/\./g, '').replace(',', '.');
+  const amount = Number(normalized);
+  return Number.isFinite(amount) ? amount : undefined;
+}
+
+/**
+ * A stored bound → the text the merchant reads, with a comma for the decimal
+ * point.
+ *
+ * It takes a STRING too, and that is not defensive typing: a range restored
+ * from the URL arrives as one (`?totalCents_gte=5000`). Narrowing to `number`
+ * and dropping the rest emptied the field on every reload — and then the next
+ * keystroke wrote a bound built from nothing.
+ */
+export function formatPtBrNumber(amount: number | string | undefined): string {
+  if (amount == null || amount === '') return '';
+  return String(amount).replace('.', ',');
+}
+
+/** The same, as a number — `undefined` when the bound is unset or unusable. */
+function boundAsNumber(amount: number | string | undefined): number | undefined {
+  if (amount == null || amount === '') return undefined;
+  const parsed = typeof amount === 'number' ? amount : Number(amount);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+/**
+ * One end of a numeric range. The BOUND stays a plain `number` — nothing
+ * downstream learns that the typing surface changed.
+ */
+export function NumberBoundInput({
+  label,
+  value,
+  unit,
+  onChange,
+  testId,
+}: {
+  label: string;
+  /** The applied bound. A range restored from the URL hands this over as a string. */
+  value: number | string | undefined;
+  /** Rendered as a start adornment ("R$"), not parsed out of the text. */
+  unit?: string;
+  onChange: (bound: number | undefined) => void;
+  testId: string;
+}): React.JSX.Element {
+  const applied = boundAsNumber(value);
+  const [text, setText] = useState(() => formatPtBrNumber(value));
+
+  // Re-sync only when the applied bound moved somewhere the text does not
+  // already mean — a "Limpar", a saved view. Comparing through the PARSE rather
+  // than the string keeps `50,` and `50,00` from being rewritten mid-edit.
+  useEffect(() => {
+    setText((current) => (parsePtBrNumber(current) === applied ? current : formatPtBrNumber(applied)));
+  }, [applied]);
+
+  return (
+    <TextField
+      size="small"
+      type="text"
+      label={label}
+      // Not `numeric`: that keypad has no comma on iOS, which is the separator
+      // this field exists to accept.
+      inputMode="decimal"
+      value={text}
+      onChange={(event) => {
+        // Reject the characters rather than silently dropping them AFTER
+        // parsing — a letter should not move the number.
+        const next = event.target.value.replace(ALLOWED, '');
+        setText(next);
+        const amount = parsePtBrNumber(next);
+        // A bare separator (`50,`) parses to nothing yet; leave the applied
+        // bound alone rather than clearing it half-way through a decimal.
+        if (next === '') return onChange(undefined);
+        if (amount !== undefined) onChange(amount);
+      }}
+      // Blur TIDIES, it does not rewrite. Text that already means the applied
+      // bound is left exactly as typed — `20`, `17,50` and `1.234,56` all stay
+      // — and only something that does not (`50,,`) snaps back.
+      //
+      // Padding the field to the chip's precision was tried and is worse than
+      // the mismatch it closed: settling `20` to `20,00` means the next edit
+      // starts from text the merchant did not write, so appending a digit to
+      // make it 200 produces `20,000`, which parses back to 20. The filter then
+      // ignores the keystroke, which is exactly the "não funciona" this whole
+      // control exists to end. An input must hold what was typed into it; the
+      // CHIP is where the applied window gets written in full.
+      onBlur={() =>
+        setText((current) =>
+          parsePtBrNumber(current) === applied ? current : formatPtBrNumber(applied),
+        )
+      }
+      InputLabelProps={{ shrink: true }}
+      inputProps={{ 'data-testid': testId }}
+      InputProps={
+        unit
+          ? {
+              startAdornment: (
+                <Box component="span" sx={{ mr: 0.5, color: 'text.secondary' }}>
+                  {unit}
+                </Box>
+              ),
+            }
+          : undefined
+      }
+      sx={{ width: 140 }}
+    />
+  );
+}

package/src/components/data-display/DataViews/data-views-range-pill.tsx

@@ -13,10 +13,12 @@
  */
 import CloseIcon from '@mui/icons-material/Close';
 import ChevronDownIcon from '@mui/icons-material/KeyboardArrowDown';
-import { Box, Button, Popover, TextField, Typography } from '@mui/material';
+import { Box, Button, Popover, Typography } from '@mui/material';
 import React, { useState } from 'react';
 
 import { TableFilter } from '../../layout/TableFilter';
+import { DayBoundInput } from './data-views-day-input';
+import { NumberBoundInput } from './data-views-number-input';
 import {
   isRangeInverted,
   isRangeSet,
@@ -27,15 +29,12 @@ import type { RangeFieldConfig, RangeValue } from './data-views-types';
 
 
 
-/** A bound as the input's string value ('' when unset). */
-function inputValue(bound: number | string | undefined): string {
-  return bound == null ? '' : String(bound);
-}
-
 /**
  * One end of the range. A day keeps its `AAAA-MM-DD` string verbatim (the form
- * both the native picker and the backend speak); a number parses, and an
- * unparseable/blank entry CLEARS the bound rather than writing `NaN`.
+ * both the field and the backend speak) and is typed through the masked
+ * `dd/mm/aaaa` field rather than a native date input — see
+ * {@link DayBoundInput} for why. A number parses, and an unparseable/blank
+ * entry CLEARS the bound rather than writing `NaN`.
  */
 function BoundField<T extends Record<string, unknown>>({
   field,
@@ -50,30 +49,23 @@ function BoundField<T extends Record<string, unknown>>({
   onChange: (bound: number | string | undefined) => void;
   testId: string;
 }): React.JSX.Element {
-  const isDay = field.kind === 'day';
+  if (field.kind === 'day') {
+    return (
+      <DayBoundInput
+        label={label}
+        value={value == null ? undefined : String(value)}
+        onChange={onChange}
+        testId={testId}
+      />
+    );
+  }
   return (
-    <TextField
-      size="small"
-      type={isDay ? 'date' : 'number'}
+    <NumberBoundInput
       label={label}
-      value={inputValue(value)}
-      onChange={(event) => {
-        const raw = event.target.value;
-        if (raw === '') return onChange(undefined);
-        if (isDay) return onChange(raw);
-        const amount = Number(raw);
-        return onChange(Number.isNaN(amount) ? undefined : amount);
-      }}
-      // A native date input ALWAYS paints its `dd/mm/aaaa` placeholder, and a
-      // start adornment occupies the same space — so a label left to MUI's
-      // default (shrink only once filled) renders ON TOP of it.
-      InputLabelProps={{ shrink: true }}
-      inputProps={{
-        'data-testid': testId,
-        ...(isDay ? {} : { step: field.step ?? 1, min: 0 }),
-      }}
-      InputProps={!isDay && field.unit ? { startAdornment: <Box component="span" sx={{ mr: 0.5, color: 'text.secondary' }}>{field.unit}</Box> } : undefined}
-      sx={{ width: isDay ? 165 : 140 }}
+      value={value}
+      unit={field.unit}
+      onChange={onChange}
+      testId={testId}
     />
   );
 }
@@ -338,7 +330,6 @@ export function PanelRangeField<T extends Record<string, unknown>>({
     <TableFilter.RangeField
       label={field.label}
       unit={field.unit}
-      step={field.step}
       value={numericRange(value)}
       onChange={(range) => onChange(range)}
       testId={testId}

package/src/components/data-display/DataViews/data-views-range-values.ts

@@ -18,13 +18,44 @@ function shortDay(day: string): string {
   const [, month, date] = day.split('-');
   return month && date ? `${date}/${month}` : day;
 }
+/**
+ * How many decimals a bound is WRITTEN with, taken from the field's own `step`.
+ *
+ * `step` is already the field's statement about its precision — money declares
+ * `0.01` — so nothing new has to be configured for a chip to know that R$ 17,50
+ * has two decimals and a quantity has none.
+ */
+function decimalsFor(step: number | undefined): number {
+  if (!step || Number.isInteger(step)) return 0;
+  return String(step).split('.')[1]?.length ?? 0;
+}
+
+/**
+ * A numeric bound as the merchant writes it: decimal COMMA, thousands grouped.
+ *
+ * `String(17.5)` reads `17.5` — a decimal point in a currency that has none —
+ * and padding it to the field's own precision is what makes `R$ 17,50` instead
+ * of `R$ 17,5`. Shared with the input's blur so the chip and the field it was
+ * typed into can never disagree, which matters because the chip is the ONLY
+ * place the applied window is stated once the popover closes.
+ */
+export function formatBoundNumber(amount: number, step?: number): string {
+  const decimals = decimalsFor(step);
+  return new Intl.NumberFormat('pt-BR', {
+    minimumFractionDigits: decimals,
+    maximumFractionDigits: Math.max(decimals, 2),
+  }).format(amount);
+}
+
 /** One bound, rendered for the chip: money in reais, a day as `DD/MM`. */
 function boundLabel<T extends Record<string, unknown>>(
   field: RangeFieldConfig<T>,
   bound: number | string,
 ): string {
   if (field.kind === 'day') return shortDay(String(bound));
-  return field.unit ? `${field.unit} ${bound}` : String(bound);
+  const amount = typeof bound === 'number' ? bound : Number(bound);
+  const text = Number.isFinite(amount) ? formatBoundNumber(amount, field.step) : String(bound);
+  return field.unit ? `${field.unit} ${text}` : text;
 }
 /**
  * The chip text for an applied range: "Data: 01/07–31/07" when both ends are

package/src/components/utility/InstallPrompt/InstallPrompt.earlyCapture.ts

@@ -0,0 +1,117 @@
+import type { BeforeInstallPromptEvent, PwaInstallStash } from './InstallPrompt.types';
+
+/**
+ * Holds `beforeinstallprompt` from before the app exists.
+ *
+ * `usePwaInstall` cannot attach its own listener early enough, and no React
+ * hook can. Chromium fires the event once, during initial page load, the
+ * moment it has a manifest and a registered worker — which in a real app is
+ * before hydration, and often before the chunk containing the component has
+ * even been downloaded. A listener registered in an effect is not late by
+ * milliseconds; it can be late by entire navigations. Nothing calls
+ * `preventDefault()` in time, the browser keeps the event, and the page can
+ * never ask again.
+ *
+ * So the capture has to live outside React, and the host has to install it as
+ * the very first thing the document does. Two supported ways, in order of
+ * reliability:
+ *
+ * 1. An inline `<script>` in `<head>`, which beats a deferred module bundle:
+ *
+ *        <script>
+ *          window.addEventListener('beforeinstallprompt', function (e) {
+ *            e.preventDefault();
+ *            var s = (window.__pwaInstall = window.__pwaInstall || {});
+ *            s.event = e; s.firedAt = Date.now();
+ *            window.dispatchEvent(new Event('pwa-install-available'));
+ *          });
+ *        </script>
+ *
+ * 2. `capturePwaInstallEvent()` as the first statement of the entry module,
+ *    before `createRoot`. Simpler to wire and correct in most apps, but a
+ *    module is still deferred, so a very early event can outrun it.
+ *
+ * Both write the same shape, so the hook does not care which was used.
+ */
+
+/** Property on `window` holding the captured event. Shared with the inline snippet. */
+export const PWA_INSTALL_STASH_KEY = '__pwaInstall';
+
+/** Fired after a capture, so an app already running can adopt the event. */
+export const PWA_INSTALL_AVAILABLE_EVENT = 'pwa-install-available';
+
+type StashHost = Window & { [PWA_INSTALL_STASH_KEY]?: PwaInstallStash };
+
+/** The stash, or `null` when no capture ever ran (SSR, or a host that skipped wiring). */
+export const readPwaInstallStash = (): PwaInstallStash | null => {
+  if (typeof window === 'undefined') return null;
+  return (window as StashHost)[PWA_INSTALL_STASH_KEY] ?? null;
+};
+
+const ensureStash = (): PwaInstallStash => {
+  const host = window as StashHost;
+  host[PWA_INSTALL_STASH_KEY] ??= { event: null, firedAt: null, installedAt: null };
+  return host[PWA_INSTALL_STASH_KEY];
+};
+
+/**
+ * The teardown for the capture currently running, so `resetPwaInstallStash`
+ * can unwind completely. Held here rather than on the stash because it must
+ * survive the stash being deleted, and because it must never be serialised
+ * into the diagnostic payload.
+ */
+let activeTeardown: (() => void) | null = null;
+
+/**
+ * Starts capturing. Returns a teardown, and is safe to call twice — a second
+ * call is a no-op rather than a duplicate listener, so a host that wires both
+ * the inline snippet and this function does not double-handle the event.
+ */
+export const capturePwaInstallEvent = (): (() => void) => {
+  if (typeof window === 'undefined') return () => undefined;
+
+  const stash = ensureStash();
+  if (stash.capturing === true) return () => undefined;
+  stash.capturing = true;
+
+  const onBeforeInstall = (event: Event): void => {
+    // The line the whole component depends on. Without it the browser owns the
+    // event, shows at most its own mini-infobar, and discards the handle.
+    event.preventDefault();
+    stash.event = event as BeforeInstallPromptEvent;
+    stash.firedAt = Date.now();
+    window.dispatchEvent(new Event(PWA_INSTALL_AVAILABLE_EVENT));
+  };
+
+  const onInstalled = (): void => {
+    stash.installedAt = Date.now();
+    stash.event = null;
+  };
+
+  window.addEventListener('beforeinstallprompt', onBeforeInstall);
+  window.addEventListener('appinstalled', onInstalled);
+
+  const teardown = () => {
+    window.removeEventListener('beforeinstallprompt', onBeforeInstall);
+    window.removeEventListener('appinstalled', onInstalled);
+    stash.capturing = false;
+    if (activeTeardown === teardown) activeTeardown = null;
+  };
+
+  activeTeardown = teardown;
+  return teardown;
+};
+
+/**
+ * Returns the page to its pre-capture state: listeners removed, stash gone.
+ *
+ * Exists for tests and stories, which need a clean page per case. It unwinds
+ * the listeners as well as the data, because a leaked capture from a previous
+ * case would go on suppressing events that the next case expects to observe.
+ */
+export const resetPwaInstallStash = (): void => {
+  if (typeof window === 'undefined') return;
+  activeTeardown?.();
+  activeTeardown = null;
+  delete (window as StashHost)[PWA_INSTALL_STASH_KEY];
+};

package/src/components/utility/InstallPrompt/InstallPrompt.md

@@ -85,6 +85,54 @@ raised from a timer or an effect.
 All copy defaults to English and every string is a prop — this package is
 locale-neutral and the consuming app supplies its own wording.
 
+## Wiring the capture
+
+**Required on Chromium.** Without it this component can never offer an install,
+and it will fail silently — no error, no warning, just an affordance that never
+appears.
+
+Chromium fires `beforeinstallprompt` once, during page load, as soon as it has a
+manifest and a registered worker. That is before hydration, and in a code-split
+app it can be before the chunk holding this component has been downloaded at
+all. No React hook can attach a listener in time, and the event is not reissued
+on request. So the capture has to run outside React, and first.
+
+Paste this into `<head>`, above the app bundle. A classic inline script is the
+only thing guaranteed to beat a deferred module:
+
+```html
+<script>
+  (function () {
+    var stash = (window.__pwaInstall = { event: null, firedAt: null, installedAt: null });
+    window.addEventListener('beforeinstallprompt', function (event) {
+      event.preventDefault();
+      stash.event = event;
+      stash.firedAt = Date.now();
+      window.dispatchEvent(new Event('pwa-install-available'));
+    });
+    window.addEventListener('appinstalled', function () {
+      stash.installedAt = Date.now();
+      stash.event = null;
+    });
+  })();
+</script>
+```
+
+Or call `capturePwaInstallEvent()` as the first statement of your entry module,
+before `createRoot`. Simpler to wire, but a module is still deferred, so a very
+early event can outrun it. Doing both is safe — the capture is idempotent.
+
+```ts
+import { capturePwaInstallEvent } from '@12-apps/ui/utility/InstallPrompt';
+
+capturePwaInstallEvent();
+```
+
+`readPwaInstallStash()` exposes what was captured (`event`, `firedAt`,
+`installedAt`), which is worth logging when the prompt does not appear:
+`firedAt` set with no visible affordance means something downstream suppressed
+it, whereas an absent stash means the wiring above is missing.
+
 ## Hook API
 
 `usePwaInstall(options)` returns:
@@ -107,7 +155,7 @@ locale-neutral and the consuming app supplies its own wording.
 - **Storage failures are swallowed.** `localStorage` throws rather than returning
   `null` in Safari private mode and wherever cookies are blocked; an uncaught throw
   would break the page on exactly the browsers this component serves.
-- **A missed first event recovers on its own.** The listener attaches on mount,
-  which can be after a cold-load event. Chromium re-fires on navigation and on
-  re-evaluation of the criteria. A host that needs the very first one can capture
-  it in its HTML entry point and re-dispatch it once the app has mounted.
+- **A missed event does NOT recover.** Chromium fires `beforeinstallprompt` once
+  and will not reissue it on request, so a listener that attaches on mount has
+  already lost. This is why "Wiring the capture" above is a requirement rather
+  than an optimisation.

package/src/components/utility/InstallPrompt/InstallPrompt.types.ts

@@ -15,6 +15,25 @@ export interface BeforeInstallPromptEvent extends Event {
   prompt: () => Promise<void>;
 }
 
+/**
+ * What the pre-React capture left on `window` for the hook to pick up.
+ *
+ * This is the handoff between code that runs before the app exists and code
+ * that runs inside it. Written either by `capturePwaInstallEvent()` or by the
+ * equivalent inline snippet in the host's HTML, and read on mount — the event
+ * has almost always fired long before any component is alive to hear it.
+ */
+export interface PwaInstallStash {
+  /** The held event, or `null` if none has fired or it was already spent. */
+  event: BeforeInstallPromptEvent | null;
+  /** When it was captured. Diagnostic: proves the capture ran and the browser offered. */
+  firedAt: number | null;
+  /** When `appinstalled` was seen, if it arrived before the app mounted. */
+  installedAt: number | null;
+  /** Guards against a host wiring both the inline snippet and the function. */
+  capturing?: boolean;
+}
+
 /**
  * How — or whether — this browser can install the app.
  *

package/src/components/utility/InstallPrompt/index.ts

@@ -1,10 +1,18 @@
 export { InstallPrompt } from './InstallPrompt';
 export { usePwaInstall } from './usePwaInstall';
+export {
+  capturePwaInstallEvent,
+  readPwaInstallStash,
+  resetPwaInstallStash,
+  PWA_INSTALL_AVAILABLE_EVENT,
+  PWA_INSTALL_STASH_KEY,
+} from './InstallPrompt.earlyCapture';
 export type {
   BeforeInstallPromptEvent,
   InstallOutcome,
   InstallPlatform,
   InstallPromptProps,
   PwaInstallState,
+  PwaInstallStash,
   UsePwaInstallOptions,
 } from './InstallPrompt.types';

package/src/components/utility/InstallPrompt/usePwaInstall.ts

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 
+import { PWA_INSTALL_AVAILABLE_EVENT, readPwaInstallStash } from './InstallPrompt.earlyCapture';
 import {
   DEFAULT_DISMISS_DAYS,
   DEFAULT_STORAGE_KEY,
@@ -50,7 +51,9 @@ const useInstalledState = (onInstalled?: () => void) => {
   }, [onInstalled]);
 
   useEffect(() => {
-    setIsInstalled(isStandaloneDisplay());
+    // `appinstalled` can also land before the app mounts, so the stash is
+    // consulted for the same reason the deferred event is.
+    setIsInstalled(isStandaloneDisplay() || readPwaInstallStash()?.installedAt != null);
 
     const markInstalled = () => {
       setIsInstalled(true);
@@ -65,29 +68,54 @@ const useInstalledState = (onInstalled?: () => void) => {
 };
 
 /**
- * Captures and holds the deferred `beforeinstallprompt` event.
+ * Holds the deferred `beforeinstallprompt` event.
  *
- * The listener is attached on mount, which is normally AFTER the browser would
- * have fired the event on a cold load. Chromium re-fires it on navigation and
- * on re-evaluation of the install criteria, so a missed first event resolves
- * itself; a host that needs the very first one can attach an early capture in
- * its HTML entry point and re-dispatch it.
+ * The stash written by `capturePwaInstallEvent` is the PRIMARY source, not a
+ * fallback. Chromium fires the event once, during initial page load; a
+ * listener attached in an effect runs after hydration and, when the component
+ * is code-split, after a download that may not happen until a later route. In
+ * a real browser it essentially never catches the event, and the event is not
+ * reissued on request — so a hook that relies on its own listener reports
+ * "cannot install" forever on the one platform that can.
+ *
+ * The live listeners below therefore cover only the narrow case they can
+ * actually serve: a browser re-evaluating installability while the app is
+ * already running, and a host that never wired the capture at all.
  */
 const useDeferredPrompt = () => {
   const deferredRef = useRef<BeforeInstallPromptEvent | null>(null);
   const [promptReady, setPromptReady] = useState(false);
 
   useEffect(() => {
+    const hold = (event: BeforeInstallPromptEvent) => {
+      deferredRef.current = event;
+      setPromptReady(true);
+    };
+
+    // Whatever fired before this component existed.
+    const held = readPwaInstallStash()?.event;
+    if (held) hold(held);
+
+    // The capture rang the bell after mount: adopt what it is holding.
+    const adopt = () => {
+      const fresh = readPwaInstallStash()?.event;
+      if (fresh) hold(fresh);
+    };
+
     const capture = (event: Event) => {
       // Without preventDefault the browser owns the event and the handle dies
-      // with it — this is the line that makes an in-page install button possible.
+      // with it. The capture has normally done this already; repeating it is
+      // harmless and keeps the hook correct on a host that skipped wiring.
       event.preventDefault();
-      deferredRef.current = event as BeforeInstallPromptEvent;
-      setPromptReady(true);
+      hold(event as BeforeInstallPromptEvent);
     };
 
+    window.addEventListener(PWA_INSTALL_AVAILABLE_EVENT, adopt);
     window.addEventListener('beforeinstallprompt', capture);
-    return () => window.removeEventListener('beforeinstallprompt', capture);
+    return () => {
+      window.removeEventListener(PWA_INSTALL_AVAILABLE_EVENT, adopt);
+      window.removeEventListener('beforeinstallprompt', capture);
+    };
   }, []);
 
   const clearPrompt = useCallback(() => {