@poodle64/ui 2026.9.7 → 2026.9.8

package/README.md

@@ -164,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
@@ -1230,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/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/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/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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@poodle64/ui",
-	"version": "2026.9.7",
+	"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",

package/registry/component-map.json

@@ -1,10 +1,10 @@
 {
 	"meta": {
 		"package": "@poodle64/ui",
-		"version": "2026.9.7",
+		"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.7`. 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.* |