@poodle64/ui 2026.9.6 → 2026.9.8

package/README.md

@@ -33,11 +33,15 @@ src/lib/
   utils.ts              cn() (clsx + tailwind-merge) and the shared TS helper types
   format.ts             the Australian value formatters: money, dates, percentages,
                           numbers — en-AU, AUD, Australia/Brisbane
+  telemetry.ts          browser telemetry: one initBrowserTelemetry() call, one Faro
+                          instance, one session id (see below)
   styles.css            the component stylesheet: scale keys, .ds-edge, .ds-chip/.ds-dot,
                           the dialogue-section divider rule
   components/ui/         one directory per component: the shadcn-svelte primitives
                           (bits-ui behaviour + shadcn markup/variants) and the composed
                           page-chrome components built on top of them
+  components/feedback/  ReportWidget: the fixed bottom-right "report a problem"
+                          trigger and dialogue every app mounts (see below)
 dist/                    generated by `pnpm build` (@sveltejs/package); never edit
 ```
 
@@ -160,6 +164,28 @@ That is the whole minimum. Everything below is optional.
 | `texture`                                         | The house atmosphere on the content region. Defaults to `grid`; `none` is the opt-out.                                  |
 | `padded`, `mainClass`                             | Padding, and extra classes on the scrolling content container.                                                          |
 
+The bar also names where you are — the active nav label, read off `nav` and
+`currentPath` — and carries the page's scope controls. A page registers them
+with `ShellControls`; they render after the location, inline from `xl` and on
+a second row of the bar below that:
+
+```svelte
+<script lang="ts">
+	import { ShellControls } from '@poodle64/ui/app-shell';
+	import { Segmented } from '@poodle64/ui/segmented';
+	let year = $state('FY26');
+</script>
+
+<ShellControls>
+	<Segmented bind:value={year} options={YEARS} label="Financial year" size="sm" />
+</ShellControls>
+```
+
+A scope control changes the view of the page you are on and never
+navigates; sub-routes are `NavItem.children`. The rail's right edge is a drag
+handle (200–420px, arrows nudge, Home resets, a drag below 170px collapses);
+the width persists in `localStorage` as `ds-shell-rail-width`.
+
 ### Nested navigation
 
 A section with its own navigation puts it on the item, as `children`, and the
@@ -1089,6 +1115,67 @@ one is bound to Xero tax codes besides. Relative time ("2 hours ago") is out
 too — it rides on `date-fns` in the one app that has it, and a display formatter
 is not worth making that a dependency of every consumer.
 
+## Browser telemetry and the feedback widget
+
+Two exports are app machinery rather than page chrome: `@poodle64/ui/telemetry`
+(Faro) and `@poodle64/ui/feedback` (`ReportWidget`). A household app mounts both
+once, in its client entry and root layout, and every app mounts the same pair.
+
+```ts
+// +layout.ts or the client entry — the browser leg only
+import { initBrowserTelemetry } from '@poodle64/ui/telemetry';
+
+initBrowserTelemetry({
+	app: 'cadmus',
+	version: APP_VERSION,
+	url: PUBLIC_FARO_URL
+});
+```
+
+`initBrowserTelemetry` is inert without a `url` — a private or unconfigured
+deployment ships no beacons and gets null from `getSessionId()`, with no branch
+at the call site. It is idempotent: a second call returns the first instance,
+so an HMR leg or a remounted layout cannot produce a second Faro global. The
+configuration is the house decision, not an app decision: session tracking on,
+the console captured nowhere (the console stays local by rule), and the
+tracing instrumentation on so every same-origin `fetch`/XHR carries a
+`traceparent` — the feedback POST and the page's server-side traces share one
+trace id. The faro packages are `dependencies`, not peers, for the same reason
+`bits-ui` is a peer: a duplicated Faro global would strand the session id the
+feedback widget reports against.
+
+`ReportWidget` is the user-facing other half: a fixed bottom-right trigger
+opening the one report dialogue — a labelled "What happened?" textarea, and a
+screenshot checkbox (on by default) that captures `document.body` with
+`html-to-image`. A capture the page cannot produce is tolerated silently: the
+report sends with a null image rather than not at all. Submitting POSTs one
+JSON body to the `endpoint` prop (default `/api/feedback`):
+
+```json
+{
+	"message": "string — the textarea, required",
+	"route": "string — location.pathname at send time",
+	"user_agent": "string — navigator.userAgent",
+	"viewport": { "width": 1024, "height": 768 },
+	"session_id": "string | null — Faro's session id",
+	"screenshot": "string | null — a PNG data URL, or null"
+}
+```
+
+That body is the interface the app's own route is written against, and
+`src/test/report-widget.test.ts` asserts it field for field. The endpoint
+answers `{ "id": "…" }`; the dialogue shows the id with a thank-you (quote it
+to follow up) and fires `onSubmitted(id)` so the app can log or route on it.
+A failure keeps the draft and offers Retry — the message the user typed is
+the hard half to reproduce, and losing it to a flaky connection would make
+the retry cost more than the first attempt.
+
+The widget lives under `components/feedback/`, not `components/ui/`: it is
+mounted by the layout, once, alongside the telemetry init — not composed into
+routes by situation, so it stands outside the situation→component registry
+for the same reason. `getSessionId()` reading null when telemetry is off is
+ordinary, not an error: the report sends with a null `session_id`.
+
 ## The gate: `ds-check-colour-surface`
 
 The package ships the gate that proves its own surface actually resolves in the
@@ -1165,17 +1252,6 @@ non-zero and naming the field on any difference.
 1. Change a component; bump `version` in `package.json` (CalVer).
 2. `pnpm build`, which runs `svelte-package` then `publint` (package.json/exports sanity).
 3. Commit, tag `ui-v<version>`, push the tag.
-4. `.github/workflows/publish.yaml` runs on that push and should publish via
-   npm OIDC trusted publishing: check it with
-   `gh run list --workflow=publish.yaml`. As of 2026.9.4 every run since
-   `ui-v2026.9.2` fails at the `npm publish` step with
-   `E404 Not Found - PUT .../@poodle64%2fui` (an OIDC/trusted-publisher
-   binding issue, since `Build and test package` passes first). Until that
-   is diagnosed and fixed, publish manually from `packages/ui/`:
-   ```bash
-   printf '//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}\n' > .npmrc
-   signet exec --identity huginn-claude --broker https://portcullis.godswood.au \
-     --credential npm-publish-token --env-var NODE_AUTH_TOKEN -- npm publish
-   rm -f .npmrc
-   ```
+4. `.github/workflows/publish.yaml` runs on that push and publishes via npm
+   OIDC trusted publishing: `gh run list --workflow=publish.yaml`.
    Confirm with `npm view @poodle64/ui version`.

package/dist/components/feedback/index.d.ts

@@ -0,0 +1,2 @@
+import ReportWidget from './report-widget.svelte';
+export { ReportWidget, ReportWidget as default };

package/dist/components/feedback/index.js

@@ -0,0 +1,2 @@
+import ReportWidget from './report-widget.svelte';
+export { ReportWidget, ReportWidget as default };

package/dist/components/feedback/report-widget.svelte

@@ -0,0 +1,174 @@
+<script lang="ts" module>
+	// In the module script so the instance script's typed state can reference
+	// it: svelte2tsx emits a component's instance-script type declarations
+	// below its `let`s, so a type both declared and referenced there turns
+	// into "used before its declaration".
+	type WidgetState = 'idle' | 'submitting' | 'done' | 'error';
+</script>
+
+<script lang="ts">
+	import { toPng } from 'html-to-image';
+	import Check from '@lucide/svelte/icons/check';
+	import CircleAlert from '@lucide/svelte/icons/circle-alert';
+	import LoaderCircle from '@lucide/svelte/icons/loader-circle';
+	import MessageSquarePlus from '@lucide/svelte/icons/message-square-plus';
+	import AppDialog from '../ui/app-dialog/app-dialog.svelte';
+	import { Button } from '../ui/button/index.js';
+	import { Checkbox } from '../ui/checkbox/index.js';
+	import { Label } from '../ui/label/index.js';
+	import Textarea from '../ui/textarea/textarea.svelte';
+	import { getSessionId } from '../../telemetry';
+
+	// The feedback widget every household app mounts: a fixed bottom-right
+	// trigger opening the one report dialogue. It is deliberately NOT under
+	// components/ui — it is app machinery the layout mounts once (alongside
+	// initBrowserTelemetry), not page chrome a route composes from, so it does
+	// not sit in the situation→component registry either.
+
+	let {
+		/** Where the report POSTs. The app's own route, defaulting to the one every household app serves. */
+		endpoint = '/api/feedback',
+		/** Fired with the id the endpoint returned, once, on the success leg. */
+		onSubmitted
+	}: {
+		endpoint?: string;
+		onSubmitted?: (id: string) => void;
+	} = $props();
+
+	let open = $state(false);
+	let message = $state('');
+	let includeScreenshot = $state(true);
+	let phase: WidgetState = $state('idle');
+	let submittedId: string | null = $state(null);
+
+	// Instance-scoped element ids: a label's `for` has to reach its control,
+	// and a page that mounts two widgets must not cross-wire their fields.
+	const uid = Math.random().toString(36).slice(2, 10);
+	const formId = `feedback-form-${uid}`;
+	const messageId = `feedback-message-${uid}`;
+	const screenshotId = `feedback-screenshot-${uid}`;
+
+	async function submit() {
+		phase = 'submitting';
+
+		// A screenshot the page cannot produce (canvas-tainted content, a
+		// browser without the API) is tolerated silently: the report still
+		// sends, with a null image rather than no report at all.
+		let screenshot: string | null = null;
+		if (includeScreenshot) {
+			screenshot = await toPng(document.body).catch(() => null);
+		}
+
+		try {
+			const response = await fetch(endpoint, {
+				method: 'POST',
+				headers: { 'Content-Type': 'application/json' },
+				body: JSON.stringify({
+					message,
+					route: location.pathname,
+					user_agent: navigator.userAgent,
+					viewport: { width: window.innerWidth, height: window.innerHeight },
+					session_id: getSessionId(),
+					screenshot
+				})
+			});
+
+			if (!response.ok) throw new Error(`the feedback endpoint answered ${response.status}`);
+
+			const { id } = (await response.json()) as { id: string };
+			submittedId = id;
+			phase = 'done';
+			onSubmitted?.(id);
+		} catch {
+			// The draft survives the failure — the message the user typed is
+			// the hard half to reproduce, and losing it on a flaky connection
+			// would make the retry cost more than the first attempt.
+			phase = 'error';
+		}
+	}
+
+	function reset() {
+		// A sent report clears the dialogue for the next one; an abandoned
+		// draft is kept, so an accidental close is not lost work.
+		if (phase === 'done') {
+			message = '';
+			submittedId = null;
+		}
+		phase = 'idle';
+	}
+</script>
+
+<!-- The floating trigger is the same shape the context column's is: a raw
+     button in the house chrome rather than the Button primitive, because a
+     Button's padding and text rhythm are for a row of actions, not a
+     44px disc pinned over the page. -->
+<button
+	type="button"
+	onclick={() => (open = true)}
+	class="border-border bg-card text-muted-foreground hover:text-foreground ds-edge fixed right-4 bottom-[calc(1rem+env(safe-area-inset-bottom))] z-50 grid size-11 flex-none place-items-center rounded-full border transition-colors"
+	aria-label="Report a problem"
+>
+	<MessageSquarePlus class="size-4.5" />
+	<span class="sr-only">Report a problem</span>
+</button>
+
+<AppDialog
+	bind:open
+	title="Report a problem"
+	subtitle="Describe what happened and the household team will take a look."
+	size="sm"
+	onOpenChange={(next) => !next && reset()}
+>
+	{#if phase === 'done'}
+		<div class="flex flex-col items-start gap-3" data-testid="feedback-done">
+			<span class="bg-primary/15 text-primary grid size-8 place-items-center rounded-md">
+				<Check class="size-4" />
+			</span>
+			<p class="font-medium">Thank you — your report was received.</p>
+			<p class="text-muted-foreground text-sm">
+				Its reference is <span class="text-foreground font-medium" data-testid="feedback-id">{submittedId}</span
+				>. Quote it if you follow it up.
+			</p>
+		</div>
+	{:else}
+		<form id={formId} onsubmit={(e) => { e.preventDefault(); submit(); }}>
+			<div class="space-y-2">
+				<Label for={messageId}>What happened?</Label>
+				<Textarea
+					id={messageId}
+					bind:value={message}
+					placeholder="What did you see, and what did you expect?"
+				/>
+			</div>
+			<div class="mt-4 flex items-center gap-2">
+				<Checkbox id={screenshotId} bind:checked={includeScreenshot} />
+				<Label for={screenshotId}>Include a screenshot of this page</Label>
+			</div>
+			{#if phase === 'error'}
+				<p class="text-destructive mt-4 flex items-center gap-2 text-sm" role="alert" data-testid="feedback-error">
+					<CircleAlert class="size-4 flex-none" />
+					Your report could not be sent. Check your connection and try again.
+				</p>
+			{/if}
+		</form>
+	{/if}
+
+	{#snippet footer()}
+		{#if phase === 'done'}
+			<Button variant="outline" onclick={() => (open = false)}>Close</Button>
+		{:else if phase === 'error'}
+			<Button variant="outline" onclick={() => (open = false)}>Cancel</Button>
+			<Button type="submit" form={formId} disabled={!message.trim()}>Retry</Button>
+		{:else}
+			<Button variant="outline" disabled={phase === 'submitting'} onclick={() => (open = false)}>
+				Cancel
+			</Button>
+			<Button type="submit" form={formId} disabled={phase === 'submitting' || !message.trim()}>
+				{#if phase === 'submitting'}
+					<LoaderCircle class="size-4 animate-spin" />
+				{/if}
+				{phase === 'submitting' ? 'Sending…' : 'Send report'}
+			</Button>
+		{/if}
+	{/snippet}
+</AppDialog>

package/dist/components/feedback/report-widget.svelte.d.ts

@@ -0,0 +1,7 @@
+type $$ComponentProps = {
+    endpoint?: string;
+    onSubmitted?: (id: string) => void;
+};
+declare const ReportWidget: import("svelte").Component<$$ComponentProps, {}, "">;
+type ReportWidget = ReturnType<typeof ReportWidget>;
+export default ReportWidget;

package/dist/components/ui/app-shell/app-shell.svelte

@@ -89,7 +89,8 @@
 	import PanelLeftClose from '@lucide/svelte/icons/panel-left-close';
 	import PanelLeftOpen from '@lucide/svelte/icons/panel-left-open';
 	import AppNav from './app-nav.svelte';
-	import { toItems, type NavSource } from './types.js';
+	import { activeNavLabel, toItems, type NavSource } from './types.js';
+	import { provideShellControls, type ShellControlsSlot } from './controls.js';
 	import { cn } from '../../../utils.js';
 
 	let {
@@ -214,6 +215,92 @@
 
 	const hasNav = $derived(toItems(nav).length > 0);
 
+	// Where the user is, in words: the rail is icons when collapsed and a closed
+	// drawer on a phone, so the bar names the section.
+	const location = $derived(activeNavLabel(nav, currentPath));
+
+	// The page's scope controls, registered by `<ShellControls>` from the route.
+	const controls: ShellControlsSlot = $state({ content: null });
+	provideShellControls(controls);
+
+	// Rail width is a personal preference: localStorage, one key across apps.
+	// A drag below RAIL_SNAP collapses; the width survives and returns on expand.
+	const RAIL_KEY = 'ds-shell-rail-width';
+	const RAIL_MIN = 200;
+	const RAIL_MAX = 420;
+	const RAIL_SNAP = 170;
+	const RAIL_STEP = 16;
+	let railWidth = $state<number | null>(null);
+	let resizing = $state(false);
+	$effect(() => {
+		try {
+			const stored = Number(localStorage.getItem(RAIL_KEY));
+			if (stored >= RAIL_MIN && stored <= RAIL_MAX) railWidth = stored;
+		} catch {
+			/* storage unavailable: the default width stands */
+		}
+	});
+	function clampRail(next: number) {
+		return Math.min(RAIL_MAX, Math.max(RAIL_MIN, Math.round(next)));
+	}
+	function setRailWidth(next: number) {
+		railWidth = clampRail(next);
+		try {
+			localStorage.setItem(RAIL_KEY, String(railWidth));
+		} catch {
+			/* storage unavailable: the width lasts the session */
+		}
+	}
+	function startResize(event: PointerEvent) {
+		const handle = event.currentTarget as HTMLElement;
+		const rail = handle.parentElement as HTMLElement;
+		const startX = event.clientX;
+		const startWidth = rail.getBoundingClientRect().width;
+		const before = railWidth;
+		resizing = true;
+		handle.setPointerCapture(event.pointerId);
+		const move = (e: PointerEvent) => {
+			const next = startWidth + (e.clientX - startX);
+			if (next < RAIL_SNAP) {
+				// A collapse keeps the width it had; only a resize stores one.
+				railWidth = before;
+				collapsed = true;
+				stop();
+			} else {
+				railWidth = clampRail(next);
+			}
+		};
+		const stop = () => {
+			resizing = false;
+			if (!collapsed && railWidth !== null) setRailWidth(railWidth);
+			handle.removeEventListener('pointermove', move);
+			handle.removeEventListener('pointerup', stop);
+			handle.removeEventListener('pointercancel', stop);
+			if (handle.hasPointerCapture(event.pointerId)) handle.releasePointerCapture(event.pointerId);
+		};
+		handle.addEventListener('pointermove', move);
+		handle.addEventListener('pointerup', stop);
+		handle.addEventListener('pointercancel', stop);
+	}
+	function resizeByKey(event: KeyboardEvent) {
+		const current = railWidth ?? RAIL_MIN + (RAIL_MAX - RAIL_MIN) / 4;
+		if (event.key === 'ArrowLeft') setRailWidth(current - RAIL_STEP);
+		else if (event.key === 'ArrowRight') setRailWidth(current + RAIL_STEP);
+		else if (event.key === 'Home') resetRailWidth();
+		else if (event.key === 'End') setRailWidth(RAIL_MAX);
+		else return;
+		event.preventDefault();
+	}
+	/** Back to the package default (Home, or a double-click on the handle). */
+	function resetRailWidth() {
+		railWidth = null;
+		try {
+			localStorage.removeItem(RAIL_KEY);
+		} catch {
+			/* storage unavailable */
+		}
+	}
+
 	// The measure is resolved ONCE, and the class and the attribute both read
 	// that one answer. Two independently-worded conditionals looked symmetric
 	// and were not: Svelte omits an attribute whose value is `null`, while a
@@ -478,8 +565,10 @@
 		-->
 		<aside
 			id={navRegionId}
-			class="ds-shell-rail bg-shell text-shell-foreground border-border flex-none flex-col border-r"
+			class="ds-shell-rail bg-shell text-shell-foreground border-border relative flex-none flex-col border-r"
+			style={railWidth ? `--ds-shell-rail-width: ${railWidth}px` : undefined}
 			data-collapsed={railCollapsed ? 'true' : undefined}
+			data-resizing={resizing ? 'true' : undefined}
 			data-drawer={mobileNavOpen ? 'true' : undefined}
 			data-testid={mobileNavOpen ? 'ds-shell-drawer' : undefined}
 			role={mobileNavOpen ? 'dialog' : undefined}
@@ -540,12 +629,33 @@
 				label={navLabel}
 				onNavigate={() => (mobileNavOpen = false)}
 			/>
+			{#if collapsible && !railCollapsed && !mobileNavOpen}
+				<!-- The rail's right edge: drag to resize, drag past the snap to
+				     collapse, arrows to nudge, Home to reset, double-click to reset.
+				     A focusable separator is the ARIA window-splitter pattern. -->
+				<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
+				<!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+				<div
+					role="separator"
+					aria-orientation="vertical"
+					aria-label="Resize sidebar"
+					aria-valuenow={railWidth ?? undefined}
+					aria-valuemin={RAIL_MIN}
+					aria-valuemax={RAIL_MAX}
+					tabindex="0"
+					class="ds-shell-rail-handle"
+					onpointerdown={startResize}
+					onkeydown={resizeByKey}
+					ondblclick={resetRailWidth}
+					data-testid="ds-rail-resize"
+				></div>
+			{/if}
 		</aside>
 	{/if}
 
 	<div class="flex min-h-0 min-w-0 flex-1 flex-col">
 		<header
-			class="ds-shell-bar bg-shell/80 text-shell-foreground border-border sticky top-0 z-20 flex min-h-14 flex-none items-center gap-2 border-b px-3 pt-[env(safe-area-inset-top)] backdrop-blur sm:gap-3 sm:px-5"
+			class="ds-shell-bar bg-shell/80 text-shell-foreground border-border sticky top-0 z-20 flex min-h-14 flex-none flex-wrap items-center gap-2 border-b px-3 pt-[env(safe-area-inset-top)] backdrop-blur sm:gap-3 sm:px-5 xl:flex-nowrap"
 		>
 			{#if hasNav}
 				<!-- `aria-controls` names the region this toggle opens. It is present
@@ -589,6 +699,28 @@
 			     leading slot that never had to. -->
 			{#if context}<div class="min-w-0">{@render context()}</div>{/if}
 
+			<!-- Where you are, then the page's scope controls. Inline with the
+			     rest of the bar from xl; below that, controls take a second row
+			     of the bar, and a bare label shows from md and not on a phone. -->
+			{#if location || controls.content}
+				<div
+					class={cn(
+						'flex min-w-0 items-center gap-2 sm:gap-3',
+						controls.content
+							? 'order-last basis-full pb-2 xl:order-none xl:basis-auto xl:pb-0'
+							: 'hidden md:flex'
+					)}
+					data-testid="ds-shell-location"
+				>
+					{#if location}
+						<span class="text-shell-muted-foreground max-w-48 flex-none truncate text-sm"
+							>{location}</span
+						>
+					{/if}
+					{#if controls.content}{@render controls.content()}{/if}
+				</div>
+			{/if}
+
 			{#if onSearch && searchPlacement === 'leading'}
 				{@render searchButton(
 					'h-9 w-9 flex-none justify-center px-0 sm:h-auto sm:w-[clamp(200px,32vw,560px)] sm:flex-1 sm:justify-start sm:gap-2 sm:px-3 sm:py-1.5'

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

@@ -0,0 +1,17 @@
+/**
+ * The page's scope controls in the shell's top bar: what changes the view of
+ * the page you are on (an entity, a financial year, chart/table) and never
+ * navigates. Sub-routes are the rail's (`NavItem.children`), never here.
+ *
+ * Controls belong to a route and the shell is composed once above every
+ * route, so the shell holds a mutable slot in context; `<ShellControls>` in a
+ * page registers its children on mount and withdraws them on unmount. One
+ * registration at a time; a later one replaces an earlier one.
+ */
+import { type Snippet } from 'svelte';
+export interface ShellControlsSlot {
+    content: Snippet | null;
+}
+export declare function provideShellControls(slot: ShellControlsSlot): void;
+/** Undefined outside a shell: `ShellControls` then renders nothing. */
+export declare function getShellControls(): ShellControlsSlot | undefined;

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

@@ -0,0 +1,19 @@
+/**
+ * The page's scope controls in the shell's top bar: what changes the view of
+ * the page you are on (an entity, a financial year, chart/table) and never
+ * navigates. Sub-routes are the rail's (`NavItem.children`), never here.
+ *
+ * Controls belong to a route and the shell is composed once above every
+ * route, so the shell holds a mutable slot in context; `<ShellControls>` in a
+ * page registers its children on mount and withdraws them on unmount. One
+ * registration at a time; a later one replaces an earlier one.
+ */
+import { getContext, setContext } from 'svelte';
+const KEY = Symbol('ds-shell-controls');
+export function provideShellControls(slot) {
+    setContext(KEY, slot);
+}
+/** Undefined outside a shell: `ShellControls` then renders nothing. */
+export function getShellControls() {
+    return getContext(KEY);
+}

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

@@ -1,6 +1,7 @@
 export { default as AppShell } from './app-shell.svelte';
 export { default as AppNav } from './app-nav.svelte';
+export { default as ShellControls } from './shell-controls.svelte';
 export { default } from './app-shell.svelte';
 export { SHELL_MEASURES, type ShellMeasure } from './measure.js';
 export { SHELL_TEXTURES, type ShellTexture } from './texture.js';
-export { hasActiveNavChild, isNavGroup, isNavItemActive, navChildren, toGroups, toItems, type IconComponent, type NavChildItem, type NavEntry, type NavGroup, type NavItem, type NavSource } from './types.js';
+export { activeNavLabel, hasActiveNavChild, isNavGroup, isNavItemActive, navChildren, toGroups, toItems, type IconComponent, type NavChildItem, type NavEntry, type NavGroup, type NavItem, type NavSource } from './types.js';

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

@@ -1,6 +1,7 @@
 export { default as AppShell } from './app-shell.svelte';
 export { default as AppNav } from './app-nav.svelte';
+export { default as ShellControls } from './shell-controls.svelte';
 export { default } from './app-shell.svelte';
 export { SHELL_MEASURES } from './measure.js';
 export { SHELL_TEXTURES } from './texture.js';
-export { hasActiveNavChild, isNavGroup, isNavItemActive, navChildren, toGroups, toItems } from './types.js';
+export { activeNavLabel, hasActiveNavChild, isNavGroup, isNavItemActive, navChildren, toGroups, toItems } from './types.js';

package/dist/components/ui/app-shell/shell-controls.svelte

@@ -0,0 +1,24 @@
+<script lang="ts">
+	/**
+	 * Registers this page's controls in the shell's top bar. Renders nothing
+	 * where it stands.
+	 *
+	 *     <ShellControls>
+	 *       <Segmented bind:value={fy} options={years} label="Financial year" />
+	 *     </ShellControls>
+	 */
+	import type { Snippet } from 'svelte';
+	import { getShellControls } from './controls.js';
+
+	let { children }: { children: Snippet } = $props();
+
+	const slot = getShellControls();
+
+	$effect(() => {
+		if (!slot) return;
+		slot.content = children;
+		return () => {
+			if (slot.content === children) slot.content = null;
+		};
+	});
+</script>

package/dist/components/ui/app-shell/shell-controls.svelte.d.ts

@@ -0,0 +1,15 @@
+/**
+     * Registers this page's controls in the shell's top bar. Renders nothing
+     * where it stands.
+     *
+     *     <ShellControls>
+     *       <Segmented bind:value={fy} options={years} label="Financial year" />
+     *     </ShellControls>
+     */
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    children: Snippet;
+};
+declare const ShellControls: import("svelte").Component<$$ComponentProps, {}, "">;
+type ShellControls = ReturnType<typeof ShellControls>;
+export default ShellControls;

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

@@ -149,3 +149,9 @@ export declare function isNavItemActive(item: NavItem, currentPath: string | und
  * when the children live at their own top-level routes.
  */
 export declare function hasActiveNavChild(item: NavItem, currentPath: string | undefined): boolean;
+/**
+ * The label of where the user is: the active child's where one matches, else
+ * the active item's. Undefined when nothing matches, so an unlisted route
+ * renders no label rather than a wrong one.
+ */
+export declare function activeNavLabel(nav: NavSource | undefined, currentPath: string | undefined): string | undefined;

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

@@ -110,3 +110,20 @@ export function hasActiveNavChild(item, currentPath) {
         return false;
     return navChildren(item).some((child) => isNavItemActive(child, currentPath));
 }
+/**
+ * The label of where the user is: the active child's where one matches, else
+ * the active item's. Undefined when nothing matches, so an unlisted route
+ * renders no label rather than a wrong one.
+ */
+export function activeNavLabel(nav, currentPath) {
+    if (!currentPath)
+        return undefined;
+    for (const item of toItems(nav)) {
+        const child = navChildren(item).find((c) => isNavItemActive(c, currentPath));
+        if (child)
+            return child.label;
+        if (isNavItemActive(item, currentPath))
+            return item.label;
+    }
+    return undefined;
+}

package/dist/components/ui/command/command-dialog.svelte.d.ts

@@ -9,6 +9,6 @@ type $$ComponentProps = WithoutChildrenOrChild<DialogPrimitive.RootProps> & With
     showCloseButton?: boolean;
     class?: string;
 };
-declare const CommandDialog: import("svelte").Component<$$ComponentProps, {}, "ref" | "value" | "open">;
+declare const CommandDialog: import("svelte").Component<$$ComponentProps, {}, "open" | "ref" | "value">;
 type CommandDialog = ReturnType<typeof CommandDialog>;
 export default CommandDialog;

package/dist/components/ui/input-group/input-group-input.svelte.d.ts

@@ -2,7 +2,7 @@ declare const InputGroupInput: import("svelte").Component<(Omit<import("svelte/e
     type: "file";
     files?: FileList;
 } | {
-    type?: "number" | "month" | "hidden" | "color" | "submit" | "reset" | "button" | "search" | "checkbox" | "radio" | (string & {}) | "text" | "tel" | "url" | "email" | "date" | "time" | "image" | "datetime-local" | "password" | "range" | "week";
+    type?: "number" | "month" | "url" | "hidden" | "color" | "submit" | "reset" | "button" | "search" | "checkbox" | "radio" | (string & {}) | "text" | "tel" | "email" | "date" | "time" | "image" | "datetime-local" | "password" | "range" | "week";
     files?: undefined;
 })) & {
     ref?: HTMLElement | null | undefined;

package/dist/components/ui/segmented/index.d.ts

@@ -0,0 +1,2 @@
+import Root, { type SegmentedOption } from './segmented.svelte';
+export { Root, Root as Segmented, type SegmentedOption };

package/dist/components/ui/segmented/index.js

@@ -0,0 +1,4 @@
+import Root, {} from './segmented.svelte';
+export { Root, 
+//
+Root as Segmented };

package/dist/components/ui/segmented/segmented.svelte

@@ -0,0 +1,62 @@
+<script lang="ts" module>
+	export interface SegmentedOption<T extends string = string> {
+		value: T;
+		label: string;
+	}
+</script>
+
+<script lang="ts" generics="T extends string">
+	/**
+	 * One value from a small fixed set, every option visible: the scope toggle
+	 * in the shell's top bar. Past about five options, use Select. A scope
+	 * always has one answer, so the value cannot be cleared.
+	 */
+	import { ToggleGroup } from 'bits-ui';
+	import { cn } from '../../../utils.js';
+
+	let {
+		value = $bindable(),
+		options,
+		label,
+		size = 'default',
+		class: className
+	}: {
+		value: T;
+		options: readonly SegmentedOption<T>[];
+		/** The control's accessible name: what the set is a choice of. */
+		label: string;
+		/** `sm` is the top-bar height; `default` sits in a page's own control row. */
+		size?: 'default' | 'sm';
+		class?: string;
+	} = $props();
+
+	const ITEM = {
+		default: 'h-8 px-3 text-sm',
+		sm: 'h-6 px-2 text-xs'
+	} as const;
+</script>
+
+<ToggleGroup.Root
+	type="single"
+	bind:value={() => value, (v) => { if (v) value = v as T; }}
+	aria-label={label}
+	class={cn(
+		'border-border bg-surface-1 inline-flex flex-none items-center gap-0.5 rounded-md border p-0.5',
+		className
+	)}
+	data-slot="segmented"
+>
+	{#each options as option (option.value)}
+		<ToggleGroup.Item
+			value={option.value}
+			class={cn(
+				'text-muted-foreground hover:text-foreground rounded-sm font-medium whitespace-nowrap transition-colors',
+				'focus-visible:ring-ring focus-visible:ring-2 focus-visible:outline-none',
+				'data-[state=on]:bg-surface-3 data-[state=on]:text-foreground data-[state=on]:font-semibold',
+				ITEM[size]
+			)}
+		>
+			{option.label}
+		</ToggleGroup.Item>
+	{/each}
+</ToggleGroup.Root>

package/dist/components/ui/segmented/segmented.svelte.d.ts

@@ -0,0 +1,36 @@
+export interface SegmentedOption<T extends string = string> {
+    value: T;
+    label: string;
+}
+declare function $$render<T extends string>(): {
+    props: {
+        value: T;
+        options: readonly SegmentedOption<T>[];
+        /** The control's accessible name: what the set is a choice of. */
+        label: string;
+        /** `sm` is the top-bar height; `default` sits in a page's own control row. */
+        size?: "default" | "sm";
+        class?: string;
+    };
+    exports: {};
+    bindings: "value";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T extends string> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "value";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T extends string>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T extends string>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const Segmented: $$IsomorphicComponent;
+type Segmented<T extends string> = InstanceType<typeof Segmented<T>>;
+export default Segmented;

package/dist/components/ui/select/select.svelte.d.ts

@@ -1,3 +1,3 @@
-declare const Select: import("svelte").Component<import("bits-ui").SelectRootPropsWithoutHTML, {}, "value" | "open">;
+declare const Select: import("svelte").Component<import("bits-ui").SelectRootPropsWithoutHTML, {}, "open" | "value">;
 type Select = ReturnType<typeof Select>;
 export default Select;

package/dist/styles.css

@@ -952,6 +952,36 @@
 		width: var(--ds-shell-rail-width-collapsed);
 	}
 
+	/* Width follows the pointer during a drag; the transition is for the
+	   collapse, not for every pixel of a resize. */
+	.ds-shell-rail[data-resizing='true'] {
+		transition: none;
+	}
+
+	/* The resize handle: a 6px grab strip astride the rail's right edge, md+
+	   only, showing the border colour under the pointer and keyboard focus. */
+	.ds-shell-rail-handle {
+		display: none;
+	}
+	@media (min-width: 48rem) {
+		.ds-shell-rail-handle {
+			display: block;
+			position: absolute;
+			inset-block: 0;
+			right: -3px;
+			width: 6px;
+			cursor: col-resize;
+			z-index: 1;
+			touch-action: none;
+		}
+		.ds-shell-rail-handle:hover,
+		.ds-shell-rail-handle:focus-visible {
+			background: var(--ds-color-primary);
+			opacity: 0.4;
+			outline: none;
+		}
+	}
+
 	/* The content measure: the shell's content box is ONE element in four
 	   states, the same shape as the rail above it.
 

package/dist/telemetry.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Browser telemetry for a household frontend: one `initBrowserTelemetry()`
+ * call in the client entry, one Faro instance for the app's lifetime.
+ *
+ * Both faro packages are ordinary `dependencies`, not peers: telemetry is not
+ * an optional flavour a consumer chooses per route, it is part of what every
+ * household app mounts, and a duplicated faro global would strand the session
+ * id the feedback widget reports against.
+ */
+import { type Faro } from '@grafana/faro-web-sdk';
+/** What an app supplies to switch telemetry on. */
+export interface BrowserTelemetryOptions {
+    /** The app's name, as it should appear in Faro's app metadata. */
+    app: string;
+    /** The app's version — the package's own CalVer, ordinarily. */
+    version: string;
+    /**
+     * The Faro collector endpoint. Empty means "no collector configured" and
+     * the whole module stays inert rather than shipping beacons that error.
+     */
+    url: string;
+}
+/**
+ * Start browser telemetry. Returns the Faro instance, or null when there is
+ * no collector to send to — the caller has nothing to clean up in that case,
+ * because nothing was created.
+ *
+ * Idempotent: a second call returns the first instance and initialises
+ * nothing. A layout remount, a dev-mode HMR leg or two init calls racing in
+ * different modules must not produce a second Faro global (faro-core refuses
+ * a second registration outright, and the session id a second instance would
+ * hand out would not be the one the first instance's events carry).
+ */
+export declare function initBrowserTelemetry({ app, version, url }: BrowserTelemetryOptions): Faro | null;
+/**
+ * Faro's current session id, or null when telemetry is not running (no URL, or
+ * init not yet called). The null leg is ordinary, not an error: the feedback
+ * widget's `session_id` field carries it as null and the report still sends.
+ */
+export declare function getSessionId(): string | null;

package/dist/telemetry.js

@@ -0,0 +1,63 @@
+/**
+ * Browser telemetry for a household frontend: one `initBrowserTelemetry()`
+ * call in the client entry, one Faro instance for the app's lifetime.
+ *
+ * Both faro packages are ordinary `dependencies`, not peers: telemetry is not
+ * an optional flavour a consumer chooses per route, it is part of what every
+ * household app mounts, and a duplicated faro global would strand the session
+ * id the feedback widget reports against.
+ */
+import { initializeFaro, getWebInstrumentations } from '@grafana/faro-web-sdk';
+import { TracingInstrumentation } from '@grafana/faro-web-tracing';
+/** The one Faro instance this browser tab holds, once initialised. */
+let faro = null;
+/**
+ * Start browser telemetry. Returns the Faro instance, or null when there is
+ * no collector to send to — the caller has nothing to clean up in that case,
+ * because nothing was created.
+ *
+ * Idempotent: a second call returns the first instance and initialises
+ * nothing. A layout remount, a dev-mode HMR leg or two init calls racing in
+ * different modules must not produce a second Faro global (faro-core refuses
+ * a second registration outright, and the session id a second instance would
+ * hand out would not be the one the first instance's events carry).
+ */
+export function initBrowserTelemetry({ app, version, url }) {
+    // No URL, no telemetry. An app that was never told where the collector
+    // lives ships a silent no-op rather than a transport that fails on every
+    // send — the call sites never branch on this; `getSessionId()` reads the
+    // same null either way.
+    if (!url)
+        return null;
+    if (faro)
+        return faro;
+    faro = initializeFaro({
+        url,
+        app: { name: app, version },
+        // Session tracking is Faro's default too, but the feedback widget's
+        // payload carries the session id, so the guarantee is stated here
+        // rather than inherited from a default that could change upstream.
+        sessionTracking: { enabled: true },
+        instrumentations: [
+            ...getWebInstrumentations({
+                // The console stays local by rule: a household app's logs are not
+                // shipped to the collector, only errors, events and measurements.
+                captureConsole: false
+            }),
+            // W3C trace context on same-origin fetch and XHR: every request the
+            // app's own backend serves carries a `traceparent`, so a feedback
+            // report can be correlated with the server-side trace of the page
+            // it was sent from.
+            new TracingInstrumentation()
+        ]
+    });
+    return faro;
+}
+/**
+ * Faro's current session id, or null when telemetry is not running (no URL, or
+ * init not yet called). The null leg is ordinary, not an error: the feedback
+ * widget's `session_id` field carries it as null and the report still sends.
+ */
+export function getSessionId() {
+    return faro?.api.getSession()?.id ?? null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@poodle64/ui",
-	"version": "2026.9.6",
+	"version": "2026.9.8",
 	"description": "Household shared component layer: shadcn-svelte primitives (bits-ui) plus the composed page chrome every app builds its routes from, restyled by each app's @poodle64/design-tokens alias layer. One fix reaches every app.",
 	"type": "module",
 	"license": "MIT",
@@ -29,6 +29,14 @@
 			"types": "./dist/format.d.ts",
 			"svelte": "./dist/format.js"
 		},
+		"./telemetry": {
+			"types": "./dist/telemetry.d.ts",
+			"svelte": "./dist/telemetry.js"
+		},
+		"./feedback": {
+			"types": "./dist/components/feedback/index.d.ts",
+			"svelte": "./dist/components/feedback/index.js"
+		},
 		"./*": {
 			"types": "./dist/components/ui/*/index.d.ts",
 			"svelte": "./dist/components/ui/*/index.js"
@@ -60,10 +68,13 @@
 		}
 	},
 	"dependencies": {
+		"@grafana/faro-web-sdk": "^2.11.0",
+		"@grafana/faro-web-tracing": "^2.11.0",
 		"@jsonforms/core": "^3.8.0",
 		"@lucide/svelte": "^1.25.0",
 		"@tanstack/table-core": "^8.21.3",
 		"clsx": "^2.1.1",
+		"html-to-image": "^1.11.13",
 		"tailwind-merge": "^3.6.0",
 		"tailwind-variants": "^3.2.2",
 		"tw-animate-css": "^1.4.0"

package/registry/component-map.json

@@ -1,10 +1,10 @@
 {
 	"meta": {
 		"package": "@poodle64/ui",
-		"version": "2026.9.6",
+		"version": "2026.9.8",
 		"generatedBy": "scripts/generate-registry.mjs",
 		"source": "scripts/situations.json + package source (DO NOT EDIT the outputs by hand)",
-		"componentCount": 56,
+		"componentCount": 57,
 		"situationCount": 15
 	},
 	"situations": [
@@ -286,6 +286,20 @@
 					"props": "nav, currentPath, brandTitle?, actions?, context?, children",
 					"insteadOf": "a bespoke nav rail + header layout per app"
 				},
+				{
+					"name": "ShellControls",
+					"dir": "app-shell",
+					"import": "@poodle64/ui/app-shell",
+					"props": "children",
+					"insteadOf": "a scope row (entity, financial year, chart/table) hand-placed above the page body; the shell's top bar carries it"
+				},
+				{
+					"name": "Segmented",
+					"dir": "segmented",
+					"import": "@poodle64/ui/segmented",
+					"props": "value, options, label, size?",
+					"insteadOf": "a hand-built row of aria-pressed buttons for a small fixed choice"
+				},
 				{
 					"name": "PageHeader",
 					"dir": "page-header",

package/registry/component-map.md

@@ -1,7 +1,7 @@
 # @poodle64/ui — situation → component map
 
 <!-- GENERATED by scripts/generate-registry.mjs from scripts/situations.json + package source. DO NOT EDIT. -->
-Generated from `@poodle64/ui@2026.9.6`. 56 components, 15 situations.
+Generated from `@poodle64/ui@2026.9.8`. 57 components, 15 situations.
 
 **Read this before writing a `<div>`.** Find the SITUATION you are in below, then compose the component named for it — do not hand-build it from raw `Card` or utility classes. Import is `import { Name } from '<import path>'`. Props marked `?` are optional. This map is the retrieval step the [`frontend-design` skill] makes mandatory; the [CHI 2026 study] measured composing-from-a-registry at 95% design-system compliance against 71% for writing the CSS from a prose style guide.
 
@@ -125,6 +125,8 @@ _The standing chrome — the app shell and its nav, the one page-title treatment
 | Component | Import | Key props | Reach for it instead of |
 | --- | --- | --- | --- |
 | `AppShell` | `@poodle64/ui/app-shell` | `nav, currentPath, brandTitle?, actions?, context?, children` | a bespoke nav rail + header layout per app |
+| `ShellControls` | `@poodle64/ui/app-shell` | `children` | a scope row (entity, financial year, chart/table) hand-placed above the page body; the shell's top bar carries it |
+| `Segmented` | `@poodle64/ui/segmented` | `value, options, label, size?` | a hand-built row of aria-pressed buttons for a small fixed choice |
 | `PageHeader` | `@poodle64/ui/page-header` | `title?, eyebrow?, breadcrumbs?, icon?, subtitle?, info?, meta?, actions?` | a hand-written <h1> and title bar (the drift gate fails this) |
 | `ContextColumn` | `@poodle64/ui/context-column` | `stats, statsTitle?, statsInfo?, detail?, ariaLabel?` | a hand-built right-hand <aside> with a stat card and a detail pane |
 | `AppIdentity` | `@poodle64/ui/app-identity` | `user, workspace?, role?, entitlements?, onSignOut, onAccountSettings?, onSwitchTheme?` | a hand-rolled account/avatar dropdown wired to raw DropdownMenu.* + Avatar.* |