@tristan2828/ui-foundation 4.28.0 → 4.29.1

package/conventions/AGENTS.md

@@ -47,7 +47,9 @@ is right. Do not disable, skip, or work around it.
 - NEVER use a raw hex value or a Tailwind palette color (`bg-blue-500`).
   Semantic tokens only: `bg-primary`, `text-muted-foreground`. (Enforced:
   the foundation's ESLint token rule; axe contrast in light and dark mode,
-  `e2e/a11y.spec.ts`.)
+  `e2e/a11y.spec.ts`.) The one exception is an app's `--brand-<name>`
+  tokens, for logos and brand marks only (`docs/foundation/design-language.md`
+  "Logos and brand marks").
 - NEVER fetch in `useEffect`. All server state goes through TanStack Query.
   (Enforced: eslint-plugin-query + the no-bare-fetch rule.)
 - NEVER read auth state outside `useAuth()`. The package exports nothing

package/conventions/docs/design-language.md

@@ -101,6 +101,50 @@ doesn't (2.7:1). A deliberately faint icon that carries nothing on its
 own (an "empty" star beside a rating's filled ones, pattern 9) may go
 lower; say so in a comment.
 
+## Logos and brand marks
+
+An app's own logo (`AppShell`'s `logo`) and the marks of the services it
+links to (a video site's mark on "Open on …", on a `WidgetCard` about it)
+are **icon components** (`IconComponent`): sized by a `size-*` class,
+`aria-hidden` passed through to the `<svg>`, with the same props as a
+Lucide icon, so they go wherever an icon goes. Lucide has no brand logos,
+and the package ships none: an app keeps the few it needs as its own
+components (Simple Icons' paths are CC0), with no icon pack as a
+dependency.
+
+Colour them in one of two ways:
+
+- **`currentColor`** for a one-colour mark that isn't a colour of its own
+  (a black or white logo): it takes the text colour around it, so it
+  turns over with the theme. The default.
+- **A brand token** for a mark whose colour *is* the brand (a red play
+  button). Define it in the app's `src/index.css`, the same value in both
+  themes, since a logo keeps its colours, and register it so it's a
+  class:
+
+  ```css
+  :root {
+    --brand-videosite: #ff0033;
+    --brand-videosite-foreground: #ffffff;
+  }
+  @theme inline {
+    --color-brand-videosite: var(--brand-videosite);
+    --color-brand-videosite-foreground: var(--brand-videosite-foreground);
+  }
+  ```
+
+  Then `fill-brand-videosite` on the mark's shape. This is the one place
+  a raw colour value is right, and it doesn't break "semantic tokens
+  only": the token's name says what it's for. **Brand tokens paint
+  marks only**: never text, a surface, a border, a focus ring or a tone.
+  A mark is decorative (whatever it sits beside names it), so it isn't
+  held to the 3:1 above, but check it against the page in both themes;
+  where it vanishes in one, give it a `currentColor` outline or use the
+  one-colour mark there.
+
+The package's own stories show the slots with made-up marks in
+`currentColor` (`app/AppShell` With logo, `app/WidgetCard` Brand mark).
+
 ## Categorical colour
 
 Tones say good, bad or *notice this*. A value that is merely *different* from its

package/conventions/docs/timed-screens.md

@@ -7,9 +7,9 @@ package has the parts, so a screen like this is assembled, not rebuilt:
 | Part | What it does |
 |---|---|
 | `SessionView` | The whole viewport over the app shell: a modal named by its title, focus kept inside, Esc closes it. Optional real fullscreen and a held wake lock |
-| `useSessionClock` | A clock that doesn't drift, with pause and resume: `idle`, `running`, `done` |
+| `useSessionClock` | A clock that doesn't drift, with pause, resume and seek: `idle`, `running`, `done` |
 | `useWakeLock` | Keeps the screen on while a session runs (`SessionView`'s `keepAwake` uses it) |
-| `unlockAudio`, `chime`, `sequence`, `say`, `hush`, `vibrate` | Sound cues with no audio files |
+| `unlockAudio`, `chime`, `sequence`, `cancelCues`, `say`, `hush`, `vibrate` | Sound cues with no audio files, booked ahead where they must be on time |
 | `canVibrate` | Whether this browser can vibrate, to offer a Vibrate setting only where it works |
 | `useMuted` | A mute toggle remembered on this device |
 | `usePrefersReducedMotion` | Whether to swap movement for a fade |
@@ -58,7 +58,7 @@ const primary = useRef<HTMLButtonElement>(null)
 ## The clock
 
 `useSessionClock({ running?, endsAt? })` returns
-`{ elapsed, status, paused, start, pause, resume, stop }`.
+`{ elapsed, status, paused, start, startFrom, seek, pause, resume, stop }`.
 
 - `elapsed` is in milliseconds, read from `performance.now()` each
   animation frame. It is never summed from ticks, so it doesn't drift.
@@ -73,8 +73,15 @@ const primary = useRef<HTMLButtonElement>(null)
   front of it.
 - It re-renders once per frame, only while counting. Format what it shows
   from `elapsed`, never by counting renders.
-- A hidden tab draws no frames, but its time still counts. The first frame
-  back catches up, and reaches `done` if it's due.
+- A hidden tab draws no frames, but its time still counts. While hidden,
+  the clock reads the time on a slow tick instead (once a second at most),
+  enough for a countdown in the tab's title, and coming back catches up
+  exactly, reaching `done` if it's due. See "Background tabs" below.
+- `startFrom(ms)` starts a run at a given elapsed time: one resumed from
+  storage after a reload. `seek(ms)` moves a running run there, paused or
+  not, for Skip and Back; at or past `endsAt` it's `done`. A seek while
+  idle or done does nothing: use `startFrom`. Pause and resume stay exact
+  after either. Don't keep a `Date.now()` clock of your own beside it.
 
 For phases (stretch two minutes, rest thirty seconds), keep one clock for
 the whole session and work out the phase from `elapsed`. A clock per
@@ -88,10 +95,13 @@ Browsers block sound until the person has clicked or tapped. So:
   click handler itself, not in an effect after it. Every cue before that
   is dropped rather than played late. iOS also needs speech started from
   a click, and `unlockAudio()` does that too.
-- `chime({ pitch?, volume?, duration? })`: a soft sine tone, a short
+- `chime({ pitch?, volume?, duration?, at? })`: a soft sine tone, a short
   attack and a slow fade. `pitch` is in Hz (660 by default). For a
   closing pair, use `sequence([{ pitch: 660 }, { pitch: 880 }])`, 180 ms
-  apart by default.
+  apart by default. `at` (a `Date.now()` time; `sequence` takes it in its
+  options) books it ahead: see "Background tabs". Each returns a handle
+  whose `cancel()` takes back what hasn't sounded yet, and `cancelCues()`
+  takes back every booked chime.
 - `say(text)` speaks a line ("Next: stretch, 2 minutes"), cutting off any
   line still being spoken. `hush()` stops it. Call `hush()` when the
   session stops or the view closes.
@@ -112,7 +122,42 @@ Browsers block sound until the person has clicked or tapped. So:
   (`aria-pressed={muted}`) named "Mute".
 - **Cue on a change of state** in an effect that compares the previous
   state with the current one, so the cue plays once. Never play a cue
-  during render.
+  during render. A cue that must be on time while the tab is in the
+  background (a phase ending) is booked ahead instead, below.
+
+## Background tabs
+
+A timer is often left running in a tab behind another. The browser draws
+no frames there and slows its timers (Chrome to about once a minute after
+a few minutes), so anything driven by them runs late: a chime from an
+effect on a phase change sounds when the person comes back, not when the
+phase ends. Web Audio's own clock keeps time, so:
+
+- **Book the cues ahead from the run's plan.** When counting starts
+  (start, resume, the view reopened, unmuted), work out when each coming
+  cue is due from the plan and the clock's position, and book it:
+  `sequence(closingPair, { at: Date.now() + endsAt - clock.elapsed })`,
+  a `chime({ at })` for each phase boundary. They strike on time whatever
+  the page's timers do.
+- **Take them back whenever counting stops, and rebook when the run
+  moves:** `cancelCues()` on pause, on closing the view, on mute and on
+  leaving the screen (an effect's cleanup); on Skip and Back, `seek`,
+  then `cancelCues()` and book again from the new position. A chime
+  already sounding rings out. Reaching `done` takes nothing back: the
+  closing cue is sounding then.
+- **Do it in the handlers**, where you know why counting stopped, not in
+  an effect on `paused`: an effect's cleanup can't tell pause from done.
+  The Timer story (`app/SessionView`) does exactly this.
+- **Speech can't be booked.** `say()` still comes when the clock's slow
+  tick reaches the moment, so in a background tab it may be late. Keep
+  what must be on time to chimes.
+- **The tab's title** (`Focus 18:42`) can count down from `elapsed`: the
+  clock's slow tick re-renders while hidden. Set it in an effect, and put
+  the plain title back when the run ends. A tick a browser has slowed to
+  once a minute shows a coarser countdown; the time itself is never off.
+- Booked cues need `unlockAudio()` from a click, like any other. iOS
+  Safari may suspend audio in a background tab altogether; nothing in a
+  web page gets round that.
 
 ## Motion
 
@@ -162,6 +207,67 @@ test('running, paused and done', async ({ page }) => {
   `page.addInitScript(() => localStorage.setItem('my-app:routine:muted', 'true'))`.
 - **Reduced motion:** `await page.emulateMedia({ reducedMotion: 'reduce' })`.
 
+**A background tab:** set the page's visibility yourself, stop its
+animation frames, and record what's booked on a stand-in `AudioContext`:
+
+```ts
+test.beforeEach(async ({ page }) => {
+  await page.clock.install()
+  await page.addInitScript(() => {
+    let visibility: DocumentVisibilityState = 'visible'
+    Object.defineProperty(document, 'visibilityState', { get: () => visibility })
+    Object.defineProperty(document, 'hidden', { get: () => visibility === 'hidden' })
+    const booked: { pitch: number; at: number; cancelled: boolean }[] = []
+    class RecordingAudioContext {
+      state = 'running'; currentTime = 0; destination = {}
+      resume = async () => {}
+      last = { pitch: 0, at: 0, cancelled: false }
+      createOscillator() {
+        const cue = (this.last = { pitch: 0, at: 0, cancelled: false })
+        return {
+          frequency: { setValueAtTime: (hz: number) => (cue.pitch = hz) },
+          connect: (node: unknown) => node,
+          start: (at: number) => booked.push(Object.assign(cue, { at })),
+          stop: () => {},
+        }
+      }
+      createGain() {
+        const cue = this.last
+        return {
+          gain: { setValueAtTime() {}, exponentialRampToValueAtTime() {} },
+          connect: (node: unknown) => node,
+          disconnect: () => (cue.cancelled = true),
+        }
+      }
+    }
+    Object.assign(window, {
+      AudioContext: RecordingAudioContext,
+      __booked: booked,
+      __hide() {
+        visibility = 'hidden'
+        window.requestAnimationFrame = () => 0   // a hidden tab draws no frames
+        document.dispatchEvent(new Event('visibilitychange'))
+      },
+    })
+  })
+})
+
+test('the end is booked ahead, and the title counts down while hidden', async ({ page }) => {
+  await page.goto('/routine')
+  await page.getByRole('button', { name: 'Start' }).click()
+  // Seconds ahead on the audio clock: the closing pair five minutes on.
+  const booked = () => page.evaluate(() => (window as any).__booked.map((c: any) => [c.pitch, Math.round(c.at), c.cancelled]))
+  await expect.poll(booked).toContainEqual([660, 300, false])
+
+  await page.evaluate(() => (window as any).__hide())
+  await page.clock.fastForward('00:10')
+  await expect(page).toHaveTitle(/^4:50/)
+})
+```
+
+Pause, Skip and Back are asserted the same way: the earlier booking's
+`cancelled` turns true and a new one appears at the new time.
+
 **An open-ended count-up: pause the fake clock.** After
 `clock.install()` the fake clock still moves in real time between
 steps, so every reading picks up however long the machine took since the

package/dist/components/app/app-shell.d.ts

@@ -1,6 +1,7 @@
 import { type ReactNode } from 'react';
 import { type NavEntry } from './app-shell-nav.js';
 import { type AppShellVersion } from './app-shell-version.js';
+import type { IconComponent } from './icon-component.js';
 export type { NavEntry, NavItem, NavSection } from './app-shell-nav.js';
 export type { AppShellVersion } from './app-shell-version.js';
 export type AppShellProps = {
@@ -12,6 +13,14 @@ export type AppShellProps = {
      * does, with its record's title).
      */
     title: string;
+    /**
+     * The app's mark, shown before `title` at the top of the sidebar, and
+     * alone, centred, at the top of the collapsed icon rail. Drawn like an
+     * icon (`IconComponent`: sized by the shell, `aria-hidden` passed
+     * through) and decorative, since `title` names the app. Its own colours,
+     * or `currentColor` for the sidebar's text colour.
+     */
+    logo?: IconComponent;
     /**
      * The app's primary navigation, in order: pages, and labelled sections of
      * pages (`{ label, items }`, one per module, say). A nav with no sections
@@ -44,4 +53,4 @@ export type AppShellProps = {
      */
     version?: AppShellVersion;
 };
-export declare function AppShell({ title, nav, sidebarExtra, defaultSidebarOpen, version }: AppShellProps): import("react").JSX.Element;
+export declare function AppShell({ title, logo: Logo, nav, sidebarExtra, defaultSidebarOpen, version }: AppShellProps): import("react").JSX.Element;

package/dist/components/app/app-shell.js

@@ -110,7 +110,7 @@ function CollapsibleNavGroup({ group, activeTo }) {
 function AppShellSkeleton() {
     return (_jsxs("div", { className: "flex h-screen w-full gap-4 p-4", "data-state": "loading", children: [_jsx(Skeleton, { className: "h-full w-56 shrink-0" }), _jsxs("div", { className: "flex-1 space-y-4 pt-2", children: [_jsx(Skeleton, { className: "h-8 w-64" }), _jsx(Skeleton, { className: "h-40 w-full" })] })] }));
 }
-export function AppShell({ title, nav, sidebarExtra, defaultSidebarOpen = true, version }) {
+export function AppShell({ title, logo: Logo, nav, sidebarExtra, defaultSidebarOpen = true, version }) {
     const { user, status, error, retry, logout } = useAuth();
     const location = useLocation();
     const reporter = useErrorReporter();
@@ -140,7 +140,7 @@ export function AppShell({ title, nav, sidebarExtra, defaultSidebarOpen = true,
         return _jsx(Navigate, { to: "/login", replace: true, state: isLoggingOut ? undefined : { from } });
     }
     const activeTo = activeNavTo(nav, location.pathname);
-    return (_jsxs(TooltipProvider, { children: [reporter && _jsx(ReportRoutePattern, { reporter: reporter }), _jsxs(SidebarProvider, { defaultOpen: storedSidebarOpen(defaultSidebarOpen), children: [_jsx(CloseMobileSidebarOnNavigate, {}), _jsx("nav", { "aria-label": "Primary", children: _jsxs(Sidebar, { collapsible: "icon", children: [_jsx(SidebarHeader, { children: _jsx("span", { className: "px-2 text-sm font-semibold text-sidebar-foreground group-data-[collapsible=icon]:hidden", children: title }) }), _jsxs(SidebarContent, { children: [navGroups(nav).map((group, groupIndex) => group.collapsible && group.label !== undefined ? (_jsx(CollapsibleNavGroup, { group: { ...group, label: group.label }, activeTo: activeTo }, `${groupIndex}:${group.label}`)) : (_jsxs(SidebarGroup, { children: [group.label !== undefined && _jsx(SidebarGroupLabel, { children: group.label }), _jsx(SidebarGroupContent, { children: _jsx(NavMenu, { items: group.items, activeTo: activeTo }) })] }, `${groupIndex}:${group.label ?? ''}`))), sidebarExtra] }), _jsxs(SidebarFooter, { children: [version && _jsx(VersionEntry, { version: version }), _jsxs("div", { className: "flex items-center justify-between gap-2 px-2 group-data-[collapsible=icon]:justify-center group-data-[collapsible=icon]:px-0", children: [_jsx("span", { className: "truncate type-caption text-sidebar-foreground/70 group-data-[collapsible=icon]:hidden", children: user.name }), _jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": "Log out", onClick: () => {
+    return (_jsxs(TooltipProvider, { children: [reporter && _jsx(ReportRoutePattern, { reporter: reporter }), _jsxs(SidebarProvider, { defaultOpen: storedSidebarOpen(defaultSidebarOpen), children: [_jsx(CloseMobileSidebarOnNavigate, {}), _jsx("nav", { "aria-label": "Primary", children: _jsxs(Sidebar, { collapsible: "icon", children: [_jsx(SidebarHeader, { children: _jsxs("div", { className: "flex items-center gap-2 px-2 group-data-[collapsible=icon]:justify-center group-data-[collapsible=icon]:px-0", children: [Logo && (_jsx(Logo, { "aria-hidden": "true", className: "size-5 shrink-0 text-sidebar-foreground group-data-[collapsible=icon]:size-4" })), _jsx("span", { className: "truncate text-sm font-semibold text-sidebar-foreground group-data-[collapsible=icon]:hidden", children: title })] }) }), _jsxs(SidebarContent, { children: [navGroups(nav).map((group, groupIndex) => group.collapsible && group.label !== undefined ? (_jsx(CollapsibleNavGroup, { group: { ...group, label: group.label }, activeTo: activeTo }, `${groupIndex}:${group.label}`)) : (_jsxs(SidebarGroup, { children: [group.label !== undefined && _jsx(SidebarGroupLabel, { children: group.label }), _jsx(SidebarGroupContent, { children: _jsx(NavMenu, { items: group.items, activeTo: activeTo }) })] }, `${groupIndex}:${group.label ?? ''}`))), sidebarExtra] }), _jsxs(SidebarFooter, { children: [version && _jsx(VersionEntry, { version: version }), _jsxs("div", { className: "flex items-center justify-between gap-2 px-2 group-data-[collapsible=icon]:justify-center group-data-[collapsible=icon]:px-0", children: [_jsx("span", { className: "truncate type-caption text-sidebar-foreground/70 group-data-[collapsible=icon]:hidden", children: user.name }), _jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": "Log out", onClick: () => {
                                                         setIsLoggingOut(true);
                                                         // A failed request still ends the session on screen
                                                         // (AuthProvider), so this stays a deliberate logout: a

package/dist/components/app/foundation-providers.js

@@ -1,20 +1,24 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { QueryClientProvider } from '@tanstack/react-query';
-import { useState } from 'react';
+import { useEffect, useState } from 'react';
 import { createQueryClient } from '../../api/query-client.js';
 import { AuthProvider } from '../../auth/use-auth.js';
 import { MockModeBanner } from './mock-mode-banner.js';
 import { ThemeProvider } from '../theme-provider.js';
 import { ErrorReportingProvider } from '../../error-reporting/error-reporting-provider.js';
 import { resolveErrorReporting } from '../../error-reporting/reporter.js';
+import { browserStaleChunkReload } from '../../lib/stale-chunk-reload.js';
 // Everything an app's root needs around its router, in the order that
 // works: the theme outermost, the mock-mode banner above the router so it
 // shows on every route (/login included), and AuthProvider inside
 // QueryClientProvider because it queries /auth/me through TanStack Query.
 // An app's DataEnvironmentBanner goes first among the children, before its
 // router: it queries too, and shows on every route like the mock banner.
+// It also reloads the page once when a lazy chunk is gone after a deploy
+// (lib/stale-chunk-reload.ts), so no app adds its own listener.
 export function FoundationProviders({ mockMode, queryClient, errorReporting, children, }) {
     const [client] = useState(() => queryClient ?? createQueryClient());
     const reporting = resolveErrorReporting(errorReporting);
+    useEffect(() => browserStaleChunkReload().install(window), []);
     return (_jsxs(ThemeProvider, { attribute: "class", defaultTheme: "system", enableSystem: true, children: [_jsx(MockModeBanner, { active: mockMode }), _jsx(QueryClientProvider, { client: client, children: _jsx(AuthProvider, { children: reporting ? _jsx(ErrorReportingProvider, { options: reporting, children: children }) : children }) })] }));
 }

package/dist/components/app/icon-component.d.ts

@@ -0,0 +1,12 @@
+import type { ComponentType } from 'react';
+/**
+ * Anything drawn like a Lucide icon: sized by a `size-*` class, coloured
+ * through `currentColor` or its own fills, and hidden from screen readers
+ * by `aria-hidden` (which it should pass to its `<svg>`). Every
+ * `LucideIcon` is one, and so is an app's own mark (a brand logo from
+ * Simple Icons' paths, say), so a slot typed with it takes either.
+ */
+export type IconComponent = ComponentType<{
+    className?: string;
+    'aria-hidden'?: boolean | 'true' | 'false';
+}>;

package/dist/components/app/icon-component.js

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

package/dist/components/app/widget-card.d.ts

@@ -1,11 +1,15 @@
 import { type ReactNode } from 'react';
 import { type To } from 'react-router';
-import { type LucideIcon } from 'lucide-react';
 import type { AppError } from '../../api/contracts.js';
+import type { IconComponent } from './icon-component.js';
 export interface WidgetCardProps {
     title: string;
-    /** A Lucide icon shown before the title. Decorative: the title names the card. */
-    icon?: LucideIcon;
+    /**
+     * An icon shown before the title: a Lucide icon, or an app's own mark (an
+     * outside service's logo on a card about that service). Decorative: the
+     * title names the card.
+     */
+    icon?: IconComponent;
     /** The title's heading level: 2 under the page's h1 (the default), deeper under a section. */
     headingLevel?: 2 | 3 | 4 | 5 | 6;
     /**

package/dist/error-reporting/error-reporting-provider.js

@@ -6,12 +6,18 @@ import { useQueryClient } from '@tanstack/react-query';
 import { useEffect, useState } from 'react';
 import { reportClientError } from '../api/gateway/client-errors.js';
 import { useAuth } from '../auth/use-auth.js';
+import { browserStaleChunkReload } from '../lib/stale-chunk-reload.js';
 import { ErrorReportingContext, useRoutePattern } from './error-reporting-context.js';
 import { createErrorReporter } from './reporter.js';
 export function ErrorReportingProvider({ options, children }) {
     const queryClient = useQueryClient();
     const { status } = useAuth();
-    const [reporter] = useState(() => createErrorReporter({ options, send: (report) => void reportClientError(report) }));
+    const [reporter] = useState(() => createErrorReporter({
+        options,
+        send: (report) => void reportClientError(report),
+        // A failure that sends the page to a new build is the old build going, not a bug.
+        muted: browserStaleChunkReload().isReloading,
+    }));
     useEffect(() => reporter.setSignedIn(status === 'authenticated'), [reporter, status]);
     useEffect(() => reporter.install(queryClient, window), [reporter, queryClient]);
     return _jsx(ErrorReportingContext.Provider, { value: reporter, children: children });

package/dist/error-reporting/reporter.d.ts

@@ -3,6 +3,11 @@ import type { ClientErrorReport } from "../api/gateway/client-errors.js";
 export type ErrorReportingOptions = {
     /** The frontend build a report names, e.g. the commit (`import.meta.env.VITE_RELEASE`). */
     release?: string;
+    /**
+     * Return true to drop a report: a known noise pattern the package doesn't
+     * filter yet. Sees every report, from every source, before it's sent.
+     */
+    ignore?: (report: ClientErrorReport) => boolean;
 };
 export type ReportSource = ClientErrorReport["source"];
 /** FoundationProviders' prop, as options, or null when reporting is off. */
@@ -10,6 +15,16 @@ export declare function resolveErrorReporting(option: boolean | ErrorReportingOp
 export declare function scrub(text: string, limit: number): string;
 /** `/widgets/7/edit` with `{ id: '7' }` → `/widgets/:id/edit`; a splat → `*`. */
 export declare function routePattern(pathname: string, params: Readonly<Record<string, string | undefined>>): string;
+/**
+ * Whether an uncaught error can't be the app's (#205): `Script error.` with
+ * nothing else, or every frame of its stack (else the event's file) outside
+ * the app's scripts. An error with no location at all is kept: a thrown
+ * string may well be the app's.
+ */
+export declare function fromOutsideApp(error: unknown, event: {
+    message?: string;
+    filename?: string;
+}, page: string): boolean;
 export type ErrorReporter = {
     /** Reports `error` from `source`, unless it's a duplicate or signed out. */
     report: (source: ReportSource, error: unknown, request?: {
@@ -23,8 +38,12 @@ export type ErrorReporter = {
     /** Listens on the window and the query client; returns the undo. */
     install: (queryClient: QueryClient, target: Pick<EventTarget, "addEventListener" | "removeEventListener">) => () => void;
 };
-export declare function createErrorReporter({ options, send, now, }: {
+export declare function createErrorReporter({ options, send, now, page, muted, }: {
     options: ErrorReportingOptions;
     send: (report: ClientErrorReport) => void;
     now?: () => number;
+    /** The page's address, which an injected script's frames carry. */
+    page?: () => string;
+    /** True while nothing should be reported: the page reloading onto a new build. */
+    muted?: () => boolean;
 }): ErrorReporter;

package/dist/error-reporting/reporter.js

@@ -51,12 +51,59 @@ function describe(error) {
         return { type: "ServerError", message: error.message };
     return { type: "Error", message: typeof error === "string" ? error : "A value that isn't an Error was thrown." };
 }
-export function createErrorReporter({ options, send, now = Date.now, }) {
+const EXTENSION_SCHEMES = /^(chrome-extension|moz-extension|safari-extension|safari-web-extension|ms-browser-extension):/i;
+const SCRIPT_FILE = /\.(?:[cm]?js|jsx|[cm]?ts|tsx)$/i;
+// A stack frame's location at the end of its line: `at f (url:1:2)`,
+// `at url:1:2`, `f@url:1:2`, `global code@url:1:2`.
+const FRAME_URL = /([a-z][a-z0-9+.-]*:\/\/[^\s()]+?):\d+(?::\d+)?\)?\s*$/i;
+function stackUrls(stack) {
+    if (!stack)
+        return [];
+    return stack.split("\n").flatMap((line) => {
+        const match = FRAME_URL.exec(line.trim());
+        return match ? [match[1]] : [];
+    });
+}
+/**
+ * Whether `url` is somewhere the app's own code can't be: an extension, or
+ * an address on the page's origin that isn't a script file (a page, as
+ * `/timers/2`, where only an injected or inline script runs).
+ */
+function outsideAppScripts(url, page) {
+    if (EXTENSION_SCHEMES.test(url))
+        return true;
+    let parsed;
+    let origin;
+    try {
+        parsed = new URL(url);
+        origin = new URL(page).origin;
+    }
+    catch {
+        return false;
+    }
+    return parsed.origin === origin && !SCRIPT_FILE.test(parsed.pathname);
+}
+/**
+ * Whether an uncaught error can't be the app's (#205): `Script error.` with
+ * nothing else, or every frame of its stack (else the event's file) outside
+ * the app's scripts. An error with no location at all is kept: a thrown
+ * string may well be the app's.
+ */
+export function fromOutsideApp(error, event, page) {
+    const stack = error instanceof Error ? error.stack : undefined;
+    if (!stack && error == null && /^Script error\.?$/.test(event.message ?? ""))
+        return true;
+    const urls = stackUrls(stack);
+    if (urls.length === 0 && event.filename)
+        urls.push(event.filename);
+    return urls.length > 0 && urls.every((url) => outsideAppScripts(url, page));
+}
+export function createErrorReporter({ options, send, now = Date.now, page = () => globalThis.location?.href ?? "", muted = () => false, }) {
     const lastSent = new Map();
     let route = null;
     let signedIn = false;
     const report = (source, error, request = {}) => {
-        if (!signedIn)
+        if (!signedIn || muted())
             return;
         const described = describe(error);
         const message = scrub(described.message, MAX_MESSAGE);
@@ -67,8 +114,7 @@ export function createErrorReporter({ options, send, now = Date.now, }) {
                 lastSent.delete(key);
         if (lastSent.has(signature))
             return;
-        lastSent.set(signature, at);
-        send({
+        const sent = {
             source,
             type: described.type.slice(0, 200),
             message,
@@ -77,7 +123,11 @@ export function createErrorReporter({ options, send, now = Date.now, }) {
             ...(request.method ? { method: request.method } : {}),
             ...(request.status ? { status: request.status } : {}),
             ...(options.release ? { release: options.release.slice(0, 100) } : {}),
-        });
+        };
+        if (options.ignore?.(sent))
+            return;
+        lastSent.set(signature, at);
+        send(sent);
     };
     const reportAppError = (source, error, method) => {
         if (!isAppError(error) || !REPORTED_KINDS.has(error.kind))
@@ -94,7 +144,9 @@ export function createErrorReporter({ options, send, now = Date.now, }) {
         },
         install: (queryClient, target) => {
             const onError = (event) => {
-                const { error, message } = event;
+                const { error, message, filename } = event;
+                if (fromOutsideApp(error, { message, filename }, page()))
+                    return;
                 report("window", error ?? message);
             };
             const onRejection = (event) => {
@@ -103,6 +155,8 @@ export function createErrorReporter({ options, send, now = Date.now, }) {
                 // ones that are bugs, and the rest are expected.
                 if (isAppError(reason))
                     return;
+                if (fromOutsideApp(reason, {}, page()))
+                    return;
                 report("unhandledrejection", reason);
             };
             target.addEventListener("error", onError);

package/dist/hooks/use-session-clock.d.ts

@@ -8,7 +8,14 @@ export type SessionClockState = {
     paused: boolean;
 };
 export type SessionClockStore = {
-    start: () => void;
+    /** Starts counting from `from` milliseconds (default 0), from any state. */
+    start: (from?: number) => void;
+    /**
+     * Moves a running clock to `elapsed` milliseconds, paused or not, without
+     * changing either; at or past `endsAt` it's `done`. Ignored while idle or
+     * done: `start(from)` begins again from a time.
+     */
+    seek: (elapsed: number) => void;
     pause: () => void;
     resume: () => void;
     /** Back to `idle` at zero. */
@@ -32,11 +39,19 @@ export type SessionClockOptions = {
     /** The elapsed milliseconds at which the session is `done`. Without it, it runs until stopped. */
     endsAt?: number;
 };
-export type SessionClock = SessionClockState & Pick<SessionClockStore, 'start' | 'pause' | 'resume' | 'stop'>;
+export type SessionClock = SessionClockState & Pick<SessionClockStore, 'seek' | 'pause' | 'resume' | 'stop'> & {
+    /** Starts counting from zero, from any state (a click handler as is). */
+    start: () => void;
+    /** Starts counting from `elapsed` milliseconds: a run resumed from storage. */
+    startFrom: (elapsed: number) => void;
+};
 /**
  * A drift-free clock with pause and resume, read from `performance.now()`
  * each animation frame. It re-renders once per frame only while counting.
- * A hidden tab draws no frames, but its time still counts: the first frame
- * back catches up (and reaches `done` if it's due).
+ * A hidden tab draws no frames, but its time still counts: while hidden it
+ * re-renders on a slow tick (once a second at most, for a countdown in the
+ * tab's title), and coming back catches up exactly (and reaches `done` if
+ * it's due). `startFrom(ms)` and `seek(ms)` begin from, and move to, a
+ * given elapsed time.
  */
 export declare function useSessionClock({ running, endsAt }?: SessionClockOptions): SessionClock;

package/dist/hooks/use-session-clock.js

@@ -21,6 +21,7 @@ export function createSessionClock(now) {
         if (counting() && since === null)
             since = now();
     };
+    const clamp = (ms) => Math.min(Math.max(Number.isFinite(ms) ? ms : 0, 0), endsAt ?? Infinity);
     const update = () => {
         let elapsed = banked + (since === null ? 0 : now() - since);
         if (status === 'running' && endsAt !== undefined && elapsed >= endsAt) {
@@ -37,10 +38,18 @@ export function createSessionClock(now) {
             listener();
     };
     return {
-        start() {
+        start(from = 0) {
             status = 'running';
             paused = false;
-            banked = 0;
+            banked = clamp(from);
+            since = null;
+            begin();
+            update();
+        },
+        seek(elapsed) {
+            if (status !== 'running')
+                return;
+            banked = clamp(elapsed);
             since = null;
             begin();
             update();
@@ -86,11 +95,17 @@ export function createSessionClock(now) {
         getSnapshot: () => snapshot,
     };
 }
+// How often a hidden tab reads the time. Browsers slow a background tab's
+// timers (Chrome to once a minute after a while), so this is at most.
+const HIDDEN_TICK_MS = 1000;
 /**
  * A drift-free clock with pause and resume, read from `performance.now()`
  * each animation frame. It re-renders once per frame only while counting.
- * A hidden tab draws no frames, but its time still counts: the first frame
- * back catches up (and reaches `done` if it's due).
+ * A hidden tab draws no frames, but its time still counts: while hidden it
+ * re-renders on a slow tick (once a second at most, for a countdown in the
+ * tab's title), and coming back catches up exactly (and reaches `done` if
+ * it's due). `startFrom(ms)` and `seek(ms)` begin from, and move to, a
+ * given elapsed time.
  */
 export function useSessionClock({ running = true, endsAt } = {}) {
     const [clock] = useState(() => createSessionClock(() => performance.now()));
@@ -105,7 +120,21 @@ export function useSessionClock({ running = true, endsAt } = {}) {
             clock.tick();
             frame = requestAnimationFrame(next);
         });
-        return () => cancelAnimationFrame(frame);
+        let hiddenTick;
+        const onVisibility = () => {
+            clearInterval(hiddenTick);
+            hiddenTick = document.hidden ? setInterval(clock.tick, HIDDEN_TICK_MS) : undefined;
+            clock.tick();
+        };
+        if (document.hidden)
+            hiddenTick = setInterval(clock.tick, HIDDEN_TICK_MS);
+        document.addEventListener('visibilitychange', onVisibility);
+        return () => {
+            cancelAnimationFrame(frame);
+            clearInterval(hiddenTick);
+            document.removeEventListener('visibilitychange', onVisibility);
+        };
     }, [clock, counting]);
-    return { ...state, start: clock.start, pause: clock.pause, resume: clock.resume, stop: clock.stop };
+    const [start] = useState(() => () => clock.start());
+    return { ...state, start, startFrom: clock.start, seek: clock.seek, pause: clock.pause, resume: clock.resume, stop: clock.stop };
 }

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { AppShell, type AppShellProps, type AppShellVersion, type NavEntry, type NavItem, type NavSection } from './components/app/app-shell.js';
+export type { IconComponent } from './components/app/icon-component.js';
 export { CountLink, type CountLinkProps } from './components/app/count-link.js';
 export { DataTable, type DataTableProps, type DataTableWidth, type SortingState } from './components/app/data-table.js';
 export { type RowGroup } from './components/app/table-groups.js';
@@ -57,4 +58,4 @@ export { usePrefersReducedMotion } from './hooks/use-prefers-reduced-motion.js';
 export { useMuted } from './hooks/use-muted.js';
 export { createPushController, usePushPermission, type PushController, type PushControllerOptions, type PushEnvironment, type PushPermission, type PushStatus, } from './hooks/use-push-permission.js';
 export { cn } from './lib/utils.js';
-export { canVibrate, chime, hush, say, sequence, unlockAudio, vibrate, type ChimeOptions, type SayOptions, type SequenceOptions, } from './lib/audio-cues.js';
+export { canVibrate, cancelCues, chime, hush, say, sequence, unlockAudio, vibrate, type ChimeOptions, type Cue, type CueTime, type SayOptions, type SequenceOptions, } from './lib/audio-cues.js';

package/dist/index.js

@@ -63,4 +63,4 @@ export { useMuted } from './hooks/use-muted.js';
 export { createPushController, usePushPermission, } from './hooks/use-push-permission.js';
 // Utilities
 export { cn } from './lib/utils.js';
-export { canVibrate, chime, hush, say, sequence, unlockAudio, vibrate, } from './lib/audio-cues.js';
+export { canVibrate, cancelCues, chime, hush, say, sequence, unlockAudio, vibrate, } from './lib/audio-cues.js';

package/dist/lib/audio-cues.d.ts

@@ -6,10 +6,23 @@ export type ChimeOptions = {
     /** Milliseconds from strike to silence (default 1200). */
     duration?: number;
 };
-export type SequenceOptions = {
+export type CueTime = {
+    /**
+     * When to strike, in `Date.now()` milliseconds, booked on the audio
+     * clock so it's on time in a background tab. Left out, or already past,
+     * it strikes now.
+     */
+    at?: number;
+};
+export type SequenceOptions = CueTime & {
     /** Milliseconds between one chime's strike and the next's (default 180). */
     spacing?: number;
 };
+/** A chime or sequence as booked. */
+export type Cue = {
+    /** Takes back its strikes that haven't sounded yet; one already sounding rings out. */
+    cancel: () => void;
+};
 export type SayOptions = {
     /** A BCP 47 tag; the browser's default voice when left out. */
     lang?: string;
@@ -23,13 +36,17 @@ export type AudioCuesEnvironment = {
     speechSynthesis?: Pick<SpeechSynthesis, 'speak' | 'cancel'>;
     SpeechSynthesisUtterance?: new (text?: string) => SpeechSynthesisUtterance;
     vibrate?: (pattern: number | number[]) => boolean;
+    /** The clock `at` is read on (default `Date.now`). */
+    now?: () => number;
 };
 export type AudioCues = {
     /** Call from the click or tap that starts a session; sound is allowed from then on. */
     unlockAudio: () => void;
-    chime: (options?: ChimeOptions) => void;
-    /** Several chimes in a row (a closing pair), `spacing` apart. */
-    sequence: (chimes: ChimeOptions[], options?: SequenceOptions) => void;
+    chime: (options?: ChimeOptions & CueTime) => Cue;
+    /** Several chimes in a row (a closing pair), `spacing` apart, from `at`. */
+    sequence: (chimes: ChimeOptions[], options?: SequenceOptions) => Cue;
+    /** Takes back every booked strike that hasn't sounded yet. */
+    cancelCues: () => void;
     /** Speaks `text`, cutting off any line still being spoken. */
     say: (text: string, options?: SayOptions) => void;
     /** Stops whatever is being spoken. */
@@ -47,10 +64,15 @@ export declare function createAudioCues(env: AudioCuesEnvironment): AudioCues;
 export declare function canVibrate(): boolean;
 /** Call from the click or tap that starts a session; sound is allowed from then on. */
 export declare const unlockAudio: AudioCues['unlockAudio'];
-/** A soft sine chime; dropped before unlockAudio() or where there's no Web Audio. */
+/**
+ * A soft sine chime, now or booked `at` a `Date.now()` time; dropped before
+ * unlockAudio() or where there's no Web Audio.
+ */
 export declare const chime: AudioCues['chime'];
-/** Several chimes `spacing` ms apart (a closing pair). */
+/** Several chimes `spacing` ms apart (a closing pair), now or from `at`. */
 export declare const sequence: AudioCues['sequence'];
+/** Takes back every booked chime that hasn't sounded yet: on pause, skip, back or leaving. */
+export declare const cancelCues: AudioCues['cancelCues'];
 /** Speaks a line, cutting off the one before. A no-op without speech synthesis. */
 export declare const say: AudioCues['say'];
 /** Stops whatever is being spoken. */

package/dist/lib/audio-cues.js

@@ -8,20 +8,30 @@
 // here is a no-op where the browser can't make the sound
 // (docs/foundation/timed-screens.md "Sound").
 //
+// A chime can be booked ahead (`at`, #193): it's scheduled on the Web
+// Audio clock, so it strikes on time in a background tab, whose timers
+// and frames the browser slows or stops. cancelCues() takes back every
+// booked strike that hasn't sounded yet (on pause, skip or leaving), so a
+// screen rebooks from its new position.
+//
 // createAudioCues takes the browser's APIs, so the rules are unit tested
 // against fakes (tests/audio-cues.test.ts); the functions exported below
 // are one shared instance over the real ones.
 const ATTACK = 0.015;
 // An exponential ramp can't reach zero, so a chime starts and ends here.
 const SILENT = 0.0001;
+const NO_CUE = { cancel: () => { } };
 export function createAudioCues(env) {
+    const now = env.now ?? Date.now;
     let context = null;
+    // Strikes booked and not yet over, so a cancel can reach them.
+    const booked = new Set();
     // A resume asked for from a click: the context is still "suspended" for
     // a moment, and a chime from that same click should still play.
     let resuming = false;
     const playable = () => context !== null && (context.state === 'running' || resuming);
     const strike = (ctx, { pitch = 660, volume = 0.25, duration = 1200 }, delay) => {
-        const start = ctx.currentTime + delay / 1000;
+        const start = ctx.currentTime + Math.max(delay, 0) / 1000;
         const end = start + Math.max(duration, 50) / 1000;
         const peak = Math.min(Math.max(volume, SILENT), 1);
         const oscillator = ctx.createOscillator();
@@ -34,7 +44,33 @@ export function createAudioCues(env) {
         oscillator.connect(gain).connect(ctx.destination);
         oscillator.start(start);
         oscillator.stop(end + 0.05);
+        const booking = { start, end, oscillator, gain };
+        for (const old of booked)
+            if (old.end < ctx.currentTime)
+                booked.delete(old);
+        booked.add(booking);
+        oscillator.onended = () => booked.delete(booking);
+        return booking;
+    };
+    // Silences a strike that hasn't sounded yet: one already sounding rings out.
+    const unbook = (ctx, booking) => {
+        if (!booked.has(booking))
+            return;
+        if (booking.start <= ctx.currentTime)
+            return;
+        booked.delete(booking);
+        try {
+            booking.gain.disconnect();
+            booking.oscillator.stop();
+        }
+        catch {
+            // Already stopped.
+        }
     };
+    const book = (ctx, strikes) => ({
+        cancel: () => strikes.forEach((booking) => unbook(ctx, booking)),
+    });
+    const delayUntil = (at) => (at === undefined ? 0 : at - now());
     return {
         unlockAudio() {
             if (env.AudioContext) {
@@ -62,16 +98,24 @@ export function createAudioCues(env) {
                 }
             }
         },
-        chime(options = {}) {
+        chime({ at, ...options } = {}) {
             if (!playable() || !context)
-                return;
-            strike(context, options, 0);
+                return NO_CUE;
+            return book(context, [strike(context, options, delayUntil(at))]);
         },
-        sequence(chimes, { spacing = 180 } = {}) {
+        sequence(chimes, { spacing = 180, at } = {}) {
             if (!playable() || !context)
+                return NO_CUE;
+            const ctx = context;
+            const delay = Math.max(delayUntil(at), 0);
+            return book(ctx, chimes.map((options, index) => strike(ctx, options, delay + index * spacing)));
+        },
+        cancelCues() {
+            if (!context)
                 return;
             const ctx = context;
-            chimes.forEach((options, index) => strike(ctx, options, index * spacing));
+            for (const booking of [...booked])
+                unbook(ctx, booking);
         },
         say(text, { lang, rate, volume } = {}) {
             if (!env.speechSynthesis || !env.SpeechSynthesisUtterance)
@@ -133,10 +177,15 @@ function browserCues() {
 }
 /** Call from the click or tap that starts a session; sound is allowed from then on. */
 export const unlockAudio = () => browserCues().unlockAudio();
-/** A soft sine chime; dropped before unlockAudio() or where there's no Web Audio. */
+/**
+ * A soft sine chime, now or booked `at` a `Date.now()` time; dropped before
+ * unlockAudio() or where there's no Web Audio.
+ */
 export const chime = (options) => browserCues().chime(options);
-/** Several chimes `spacing` ms apart (a closing pair). */
+/** Several chimes `spacing` ms apart (a closing pair), now or from `at`. */
 export const sequence = (chimes, options) => browserCues().sequence(chimes, options);
+/** Takes back every booked chime that hasn't sounded yet: on pause, skip, back or leaving. */
+export const cancelCues = () => browserCues().cancelCues();
 /** Speaks a line, cutting off the one before. A no-op without speech synthesis. */
 export const say = (text, options) => browserCues().say(text, options);
 /** Stops whatever is being spoken. */

package/dist/lib/stale-chunk-reload.d.ts

@@ -0,0 +1,14 @@
+export type StaleChunkReload = {
+    /** True from the reload asked for until the page goes: nothing that fails meanwhile is a bug. */
+    isReloading: () => boolean;
+    /** Listens for `vite:preloadError` on `target`; returns the undo. */
+    install: (target: Pick<EventTarget, 'addEventListener' | 'removeEventListener'>) => () => void;
+};
+export declare function createStaleChunkReload({ storage, reload, now, windowMs, }: {
+    storage: () => Pick<Storage, 'getItem' | 'setItem'> | undefined;
+    reload: () => void;
+    now?: () => number;
+    windowMs?: number;
+}): StaleChunkReload;
+/** The one instance over the real window, sessionStorage and reload. */
+export declare function browserStaleChunkReload(): StaleChunkReload;

package/dist/lib/stale-chunk-reload.js

@@ -0,0 +1,64 @@
+// After a deploy, a tab opened on the build before it still runs that
+// build, and its content-hashed chunks are gone from the server: the next
+// lazy import (the rich-text editor's, say) fails with "Failed to fetch
+// dynamically imported module" (#206). Vite's preload helper announces it
+// first as a cancelable `vite:preloadError` on `window`, for the package's
+// own lazy chunks too once the app's build bundles them. On it, the page
+// reloads once onto the new build, and the failure is not reported.
+//
+// Once, because a file missing from the new build too would reload
+// forever: the reload is remembered in sessionStorage, and a second
+// failure within `windowMs` of it is let through to the error boundary
+// (and reported, since that one is a real missing file). Where nothing
+// can be remembered, nothing reloads.
+//
+// createStaleChunkReload takes its storage, reload and clock, so the rules
+// are unit tested in node (tests/stale-chunk-reload.test.ts);
+// FoundationProviders installs the shared instance over the real ones.
+const KEY = 'ui-foundation:stale-chunk-reload';
+const WINDOW_MS = 60_000;
+export function createStaleChunkReload({ storage, reload, now = Date.now, windowMs = WINDOW_MS, }) {
+    let reloading = false;
+    const remember = () => {
+        try {
+            const store = storage();
+            if (!store)
+                return false;
+            const last = Number(store.getItem(KEY));
+            if (Number.isFinite(last) && last > 0 && now() - last < windowMs)
+                return false;
+            store.setItem(KEY, String(now()));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const onPreloadError = (event) => {
+        if (reloading) {
+            event.preventDefault();
+            return;
+        }
+        if (!remember())
+            return;
+        reloading = true;
+        event.preventDefault();
+        reload();
+    };
+    return {
+        isReloading: () => reloading,
+        install(target) {
+            target.addEventListener('vite:preloadError', onPreloadError);
+            return () => target.removeEventListener('vite:preloadError', onPreloadError);
+        },
+    };
+}
+let shared = null;
+/** The one instance over the real window, sessionStorage and reload. */
+export function browserStaleChunkReload() {
+    shared ??= createStaleChunkReload({
+        storage: () => (typeof sessionStorage === 'undefined' ? undefined : sessionStorage),
+        reload: () => window.location.reload(),
+    });
+    return shared;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "4.28.0",
+  "version": "4.29.1",
   "description": "Shared UI foundation for contract-first, database-backed React apps: shadcn primitives, DataTable/EntityForm composites, auth, the gateway error seam, design tokens, lint rules and the AI playbook.",
   "license": "MIT",
   "repository": {
@@ -94,7 +94,7 @@
     "tailwindcss": "^4.3.3",
     "typescript-eslint": "^8.70.0",
     "vite": "^8.3.4",
-    "zod": "^4.6.5"
+    "zod": "^4.6.7"
   },
   "peerDependenciesMeta": {
     "@axe-core/playwright": {
@@ -147,7 +147,7 @@
     "react-markdown": "^10.1.0",
     "remark-gfm": "^4.0.1",
     "remark-parse": "^11.0.0",
-    "shadcn": "^4.21.0",
+    "shadcn": "^4.22.1",
     "tw-animate-css": "^1.4.0",
     "unified": "^11.0.5"
   },
@@ -185,7 +185,7 @@
     "typescript-eslint": "^8.70.0",
     "vite": "^8.3.4",
     "vitest": "^5.0.1",
-    "zod": "^4.6.5"
+    "zod": "^4.6.7"
   },
   "publishConfig": {
     "access": "public",