@poodle64/ui 2026.9.19 → 2026.9.21

package/README.md

@@ -42,6 +42,8 @@ src/lib/
                           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)
+  components/alerts/    AlertBell: the top-bar bell over the app factory's alerts
+                          routes (see below)
 dist/                    generated by `pnpm build` (@sveltejs/package); never edit
 ```
 
@@ -402,6 +404,50 @@ all three serve any route:
 truncates. Carry one or the other. A page writes a run of `Panel`s and no
 wrapper: the pane stacks them on the package's section rhythm itself.
 
+### A working list beside a page's own content
+
+```svelte
+<script lang="ts">
+	import AppShell from '@poodle64/ui/app-shell';
+	import ListShell from '@poodle64/ui/list-shell';
+
+	// Bind it to whatever already persists a user preference for this module:
+	// a module-scoped `.svelte.ts` store backed by localStorage, or the app's
+	// own settings. ListShell holds no storage of its own.
+	let listOpen = $state(true);
+</script>
+
+<!-- padded={false}: the list has to reach the content area's edge, flush
+     against the rail, or it reads as a floating card. -->
+<AppShell {nav} currentPath={page.url.pathname} padded={false}>
+	<div class="flex min-h-0 flex-1">
+		<ListShell title="Waiting on you" bind:open={listOpen}>
+			{#snippet actions()}
+				<Button size="icon" variant="outline" aria-label="Add documents"><Plus /></Button>
+			{/snippet}
+			<!-- tabs, group headings, rows: entirely this module's own -->
+		</ListShell>
+		<div class="min-w-0 flex-1">
+			{#if !listOpen}
+				<!-- The reopen control is this module's own markup, at whatever
+				     position it chooses; ListShell never places it. -->
+				<Button onclick={() => (listOpen = true)} aria-expanded={listOpen}>
+					Waiting on you <Badge>{waitingCount}</Badge>
+				</Button>
+			{/if}
+			<!-- the module's own content -->
+		</div>
+	</div>
+</AppShell>
+```
+
+| Prop       | Purpose                                                                      |
+| ---------- | ----------------------------------------------------------------------------- |
+| `title`    | The list's heading, in the shell's display face.                              |
+| `open`     | Bindable. Not persisted by this component; bind it to what already persists a preference for this module. |
+| `label`    | The landmark's accessible name. Defaults to `title`.                          |
+| `actions`  | Leading header actions beside the title: an "Add" button, a filter.           |
+
 ### The content measure
 
 How wide the page body may get, chosen once in the layout from a scale of four:
@@ -1276,6 +1322,19 @@ 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 alerts bell
+
+`@poodle64/ui/alerts` (`AlertBell`) is app machinery of the same kind: the app
+factory's layout mounts it once, in the shell's `actions` slot, for callers
+holding `admin`. It shows what machines raised through the app's `/mcp` `alerts`
+tool, from the factory's routes under the `endpoint` prop (default
+`/api/alerts`): `GET <endpoint>/` lists `{ alerts, total, unread }`, `POST
+<endpoint>/<id>/read` marks one read, `DELETE <endpoint>/<id>` dismisses it.
+`src/test/alert-bell.test.ts` asserts each call. It renders nothing while no
+alert is open, polls once a minute and again as its panel opens, and reports a
+failed read or dismissal with `toast.error`, so `svelte-sonner` is required
+here. The app factory's `docs/design/alerts.md` carries the design.
+
 ## The gate: `ds-check-colour-surface`
 
 The package ships the gate that proves its own surface actually resolves in the

package/dist/components/alerts/alert-bell.svelte

@@ -0,0 +1,177 @@
+<script lang="ts" module>
+	/** One alert as the endpoint lists it: the app factory's `AlertRead`. */
+	export type Alert = {
+		id: number;
+		key: string;
+		title: string;
+		body: string | null;
+		link: string | null;
+		raised_at: string;
+		read_at: string | null;
+	};
+</script>
+
+<script lang="ts">
+	import Bell from '@lucide/svelte/icons/bell';
+	import X from '@lucide/svelte/icons/x';
+	import { onMount } from 'svelte';
+	import { toast } from 'svelte-sonner';
+	import { Badge } from '../ui/badge/index.js';
+	import { Button } from '../ui/button/index.js';
+	import * as Popover from '../ui/popover/index.js';
+	import { cn } from '../../utils';
+
+	// The alerts bell: what machines told this deployment's operator, in the
+	// shell's top-bar `actions` slot. App machinery like ReportWidget, mounted
+	// once by the layout and talking to the app factory's own routes: GET
+	// `<endpoint>/` lists, POST `<endpoint>/<id>/read` marks read, DELETE
+	// `<endpoint>/<id>` dismisses.
+	//
+	// It renders NOTHING while no alert is open, so an app no producer writes
+	// to carries no bell. The layout decides who may see it; the server's gate
+	// is the real one.
+
+	let {
+		/** The app's alerts route, defaulting to the one every factory app serves. */
+		endpoint = '/api/alerts'
+	}: { endpoint?: string } = $props();
+
+	const POLL_MS = 60_000;
+	const TIMEOUT_MS = 30_000;
+	const since = new Intl.RelativeTimeFormat(undefined, { numeric: 'auto' });
+
+	let alerts: Alert[] = $state([]);
+	let total = $state(0);
+	let unread = $state(0);
+	let open = $state(false);
+
+	function call(path: string, method = 'GET'): Promise<Response | null> {
+		return fetch(`${endpoint}/${path}`, { method, signal: AbortSignal.timeout(TIMEOUT_MS) }).catch(
+			() => null
+		);
+	}
+
+	// A failed poll keeps what the bell last showed and is not worth a toast:
+	// the next one, a minute on, tries again.
+	async function load() {
+		const response = await call('');
+		if (!response?.ok) return;
+		const data = (await response.json()) as { alerts: Alert[]; total: number; unread: number };
+		alerts = data.alerts;
+		total = data.total;
+		unread = data.unread;
+	}
+
+	async function act(path: string, method: string, failure: string) {
+		const response = await call(path, method);
+		if (!response?.ok) toast.error(failure);
+		await load();
+	}
+
+	function markRead(alert: Alert) {
+		if (alert.read_at) return;
+		void act(`${alert.id}/read`, 'POST', 'Could not mark the alert read');
+	}
+
+	// Following a link closes the panel; the read is recorded on the way out.
+	function follow(alert: Alert) {
+		open = false;
+		markRead(alert);
+	}
+
+	function age(iso: string): string {
+		const minutes = Math.round((new Date(iso).getTime() - Date.now()) / 60_000);
+		if (minutes > -60) return since.format(minutes, 'minute');
+		if (minutes > -60 * 24) return since.format(Math.round(minutes / 60), 'hour');
+		return since.format(Math.round(minutes / (60 * 24)), 'day');
+	}
+
+	onMount(() => {
+		void load();
+		const timer = setInterval(() => void load(), POLL_MS);
+		return () => clearInterval(timer);
+	});
+</script>
+
+{#if total > 0}
+	<Popover.Root bind:open onOpenChange={(opened) => opened && void load()}>
+		<Popover.Trigger>
+			{#snippet child({ props })}
+				<!-- size-9 is the shell's own top-bar control size (its search and
+				     theme buttons), which size="icon" follows at one density only. -->
+				<Button
+					{...props}
+					variant="outline"
+					size="icon"
+					class="relative size-9"
+					aria-label={unread > 0 ? `Alerts, ${unread} unread` : 'Alerts'}
+					data-testid="alert-bell"
+				>
+					<Bell />
+					{#if unread > 0}
+						<Badge
+							class="absolute -top-1.5 -right-1.5 h-4 min-w-4 px-1"
+							aria-hidden="true"
+							data-testid="alert-bell-unread"
+						>
+							{unread > 99 ? '99+' : unread}
+						</Badge>
+					{/if}
+				</Button>
+			{/snippet}
+		</Popover.Trigger>
+
+		<Popover.Content align="end" class="w-96 p-0">
+			<p class="border-b px-4 py-3 text-sm font-semibold">Alerts</p>
+			<ul class="divide-y">
+				{#each alerts as alert (alert.id)}
+					<li class="flex items-start gap-2 px-4 py-3" data-testid="alert-item">
+						<span
+							class={cn('mt-1.5 size-2 shrink-0 rounded-full', !alert.read_at && 'bg-primary')}
+							aria-hidden="true"
+						></span>
+						{#if alert.link}
+							<a
+								href={alert.link}
+								class="min-w-0 flex-1 text-left"
+								target={alert.link.startsWith('/') ? undefined : '_blank'}
+								rel={alert.link.startsWith('/') ? undefined : 'noreferrer'}
+								onclick={() => follow(alert)}
+							>
+								{@render content(alert)}
+							</a>
+						{:else}
+							<button type="button" class="min-w-0 flex-1 text-left" onclick={() => markRead(alert)}>
+								{@render content(alert)}
+							</button>
+						{/if}
+						<Button
+							variant="ghost"
+							size="icon-xs"
+							aria-label="Dismiss"
+							onclick={() => void act(String(alert.id), 'DELETE', 'Could not dismiss the alert')}
+							data-testid="alert-dismiss"
+						>
+							<X />
+						</Button>
+					</li>
+				{/each}
+			</ul>
+			{#if total > alerts.length}
+				<p class="text-muted-foreground border-t px-4 py-2 text-xs">
+					Showing the newest {alerts.length} of {total}.
+				</p>
+			{/if}
+		</Popover.Content>
+	</Popover.Root>
+{/if}
+
+{#snippet content(alert: Alert)}
+	<span class={cn('block text-sm leading-tight', !alert.read_at && 'font-medium')}>
+		{alert.title}
+	</span>
+	{#if alert.body}
+		<span class="text-muted-foreground mt-1 block text-xs whitespace-pre-line">{alert.body}</span>
+	{/if}
+	<span class="text-muted-foreground mt-1 block text-xs">{age(alert.raised_at)}</span>
+{/snippet}

package/dist/components/alerts/alert-bell.svelte.d.ts

@@ -0,0 +1,16 @@
+/** One alert as the endpoint lists it: the app factory's `AlertRead`. */
+export type Alert = {
+    id: number;
+    key: string;
+    title: string;
+    body: string | null;
+    link: string | null;
+    raised_at: string;
+    read_at: string | null;
+};
+type $$ComponentProps = {
+    endpoint?: string;
+};
+declare const AlertBell: import("svelte").Component<$$ComponentProps, {}, "">;
+type AlertBell = ReturnType<typeof AlertBell>;
+export default AlertBell;

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

@@ -0,0 +1,2 @@
+import AlertBell, { type Alert } from './alert-bell.svelte';
+export { AlertBell, AlertBell as default, type Alert };

package/dist/components/alerts/index.js

@@ -0,0 +1,2 @@
+import AlertBell, {} from './alert-bell.svelte';
+export { AlertBell, AlertBell as default };

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, {}, "open" | "ref" | "value">;
+declare const CommandDialog: import("svelte").Component<$$ComponentProps, {}, "ref" | "value" | "open">;
 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" | "url" | "hidden" | "color" | "submit" | "reset" | "button" | "search" | "checkbox" | "radio" | (string & {}) | "text" | "tel" | "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" | "week" | "date" | "time" | "image" | "datetime-local" | "password" | "range";
     files?: undefined;
 })) & {
     ref?: HTMLElement | null | undefined;

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

@@ -0,0 +1,2 @@
+export { default as ListShell } from './list-shell.svelte';
+export { default } from './list-shell.svelte';

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

@@ -0,0 +1,2 @@
+export { default as ListShell } from './list-shell.svelte';
+export { default } from './list-shell.svelte';

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

@@ -0,0 +1,85 @@
+<script lang="ts">
+	/**
+	 * ListShell — a module's working list, folded away and brought back by
+	 * the app that owns it, beside the content it serves. Not an AppShell
+	 * slot: `sidebar` was removed 2026.8.11 after two apps disagreed on
+	 * where a module's own PAGES render (operator ruling 21/08/2026); a
+	 * working list is data, not navigation, so it is a page-level companion
+	 * like `SettingsShell`/`ContextColumn` — pair with `padded={false}` on
+	 * AppShell, as `SettingsShell` requires. `open` is the caller's own
+	 * bindable state, never persisted here; closed, this renders nothing,
+	 * and reopening is the caller's own control, placed wherever the module
+	 * chooses. Hidden below `md` at every state.
+	 */
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { cn, type WithElementRef } from '../../../utils.js';
+	import PanelLeftClose from '@lucide/svelte/icons/panel-left-close';
+
+	let {
+		title,
+		label = title,
+		open = $bindable(true),
+		actions,
+		children,
+		ref = $bindable(null),
+		class: className,
+		...restProps
+	}: WithElementRef<HTMLAttributes<HTMLElement>> & {
+		/** The list's heading, in the shell's display face. */
+		title: string;
+		/**
+		 * The landmark's accessible name. Defaults to `title` — the visible
+		 * heading already says what this is, so a module only sets `label`
+		 * separately when the heading text would not stand alone as a name
+		 * (WCAG 2.4.1), e.g. a heading that leads with a live count.
+		 */
+		label?: string;
+		/**
+		 * Whether the list is open. Bindable, and NOT persisted by this
+		 * component — bind it to whatever the module already uses to persist a
+		 * user preference across a reload.
+		 */
+		open?: boolean;
+		/** Leading header actions beside the title — an "Add" button, a filter. */
+		actions?: Snippet;
+		/** The list body: tabs, group headings, rows — entirely the module's own. */
+		children: Snippet;
+	} = $props();
+
+	const listId = $props.id();
+</script>
+
+{#if open}
+	<aside
+		bind:this={ref}
+		id={listId}
+		aria-label={label}
+		class={cn(
+			'bg-shell text-shell-foreground border-border hidden w-[25rem] flex-none flex-col border-e md:flex',
+			className
+		)}
+		{...restProps}
+	>
+		<div class="flex flex-none items-center gap-2 px-5 pt-5 pb-3">
+			<h2 class="font-display text-display flex-1 truncate font-semibold tracking-tight">
+				{title}
+			</h2>
+			{#if actions}{@render actions()}{/if}
+			<button
+				type="button"
+				onclick={() => (open = false)}
+				aria-expanded="true"
+				aria-controls={listId}
+				aria-label={`Fold ${label} away`}
+				title={`Fold ${label} away`}
+				class="text-shell-muted-foreground hover:text-shell-foreground border-border grid size-9 flex-none place-items-center rounded-md border transition-colors"
+			>
+				<PanelLeftClose class="size-4" />
+			</button>
+		</div>
+		<div class="flex min-h-0 flex-1 flex-col overflow-y-auto">
+			{@render children()}
+		</div>
+	</aside>
+{/if}

package/dist/components/ui/list-shell/list-shell.svelte.d.ts

@@ -0,0 +1,39 @@
+/**
+     * ListShell — a module's working list, folded away and brought back by
+     * the app that owns it, beside the content it serves. Not an AppShell
+     * slot: `sidebar` was removed 2026.8.11 after two apps disagreed on
+     * where a module's own PAGES render (operator ruling 21/08/2026); a
+     * working list is data, not navigation, so it is a page-level companion
+     * like `SettingsShell`/`ContextColumn` — pair with `padded={false}` on
+     * AppShell, as `SettingsShell` requires. `open` is the caller's own
+     * bindable state, never persisted here; closed, this renders nothing,
+     * and reopening is the caller's own control, placed wherever the module
+     * chooses. Hidden below `md` at every state.
+     */
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import { type WithElementRef } from '../../../utils.js';
+type $$ComponentProps = WithElementRef<HTMLAttributes<HTMLElement>> & {
+    /** The list's heading, in the shell's display face. */
+    title: string;
+    /**
+     * The landmark's accessible name. Defaults to `title` — the visible
+     * heading already says what this is, so a module only sets `label`
+     * separately when the heading text would not stand alone as a name
+     * (WCAG 2.4.1), e.g. a heading that leads with a live count.
+     */
+    label?: string;
+    /**
+     * Whether the list is open. Bindable, and NOT persisted by this
+     * component — bind it to whatever the module already uses to persist a
+     * user preference across a reload.
+     */
+    open?: boolean;
+    /** Leading header actions beside the title — an "Add" button, a filter. */
+    actions?: Snippet;
+    /** The list body: tabs, group headings, rows — entirely the module's own. */
+    children: Snippet;
+};
+declare const ListShell: import("svelte").Component<$$ComponentProps, {}, "ref" | "open">;
+type ListShell = ReturnType<typeof ListShell>;
+export default ListShell;

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@poodle64/ui",
-	"version": "2026.9.19",
+	"version": "2026.9.21",
 	"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",
@@ -37,6 +37,10 @@
 			"types": "./dist/components/feedback/index.d.ts",
 			"svelte": "./dist/components/feedback/index.js"
 		},
+		"./alerts": {
+			"types": "./dist/components/alerts/index.d.ts",
+			"svelte": "./dist/components/alerts/index.js"
+		},
 		"./*": {
 			"types": "./dist/components/ui/*/index.d.ts",
 			"svelte": "./dist/components/ui/*/index.js"

package/registry/component-map.json

@@ -1,10 +1,10 @@
 {
 	"meta": {
 		"package": "@poodle64/ui",
-		"version": "2026.9.19",
+		"version": "2026.9.21",
 		"generatedBy": "scripts/generate-registry.mjs",
 		"source": "scripts/situations.json + package source (DO NOT EDIT the outputs by hand)",
-		"componentCount": 60,
+		"componentCount": 61,
 		"situationCount": 17
 	},
 	"situations": [
@@ -298,7 +298,7 @@
 		{
 			"key": "page-frame",
 			"title": "The frame every route shares",
-			"description": "The standing chrome — the app shell and its nav, the one page-title treatment, the persistent right-hand context column.",
+			"description": "The standing chrome — the app shell and its nav, the one page-title treatment, the persistent right-hand context column, a foldable working list beside the page's own content.",
 			"components": [
 				{
 					"name": "AppShell",
@@ -335,6 +335,13 @@
 					"props": "stats, statsTitle?, statsInfo?, detail?, ariaLabel?",
 					"insteadOf": "a hand-built right-hand <aside> with a stat card and a detail pane"
 				},
+				{
+					"name": "ListShell",
+					"dir": "list-shell",
+					"import": "@poodle64/ui/list-shell",
+					"props": "title, children, label?, open?, actions?",
+					"insteadOf": "a module hand-rolling its own foldable second column beside the rail — a queue, an inbox, a working list"
+				},
 				{
 					"name": "AppIdentity",
 					"dir": "app-identity",

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.19`. 60 components, 17 situations.
+Generated from `@poodle64/ui@2026.9.21`. 61 components, 17 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.
 
@@ -129,7 +129,7 @@ _One page at a time, fitted to its pane both ways so an A4 statement and a tall
 
 ## The frame every route shares
 
-_The standing chrome — the app shell and its nav, the one page-title treatment, the persistent right-hand context column._
+_The standing chrome — the app shell and its nav, the one page-title treatment, the persistent right-hand context column, a foldable working list beside the page's own content._
 
 | Component | Import | Key props | Reach for it instead of |
 | --- | --- | --- | --- |
@@ -138,6 +138,7 @@ _The standing chrome — the app shell and its nav, the one page-title treatment
 | `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 |
+| `ListShell` | `@poodle64/ui/list-shell` | `title, children, label?, open?, actions?` | a module hand-rolling its own foldable second column beside the rail — a queue, an inbox, a working list |
 | `AppIdentity` | `@poodle64/ui/app-identity` | `user, workspace?, role?, entitlements?, onSignOut, onAccountSettings?, onSwitchTheme?` | a hand-rolled account/avatar dropdown wired to raw DropdownMenu.* + Avatar.* |
 
 ## The settings destination