@signal9/era-ui 2.8.3 → 2.9.0

package/dist/ai/confirmation/approval.svelte.d.ts

@@ -0,0 +1,42 @@
+/** How a single argument field is rendered and coerced. */
+export type FieldKind = 'string' | 'number' | 'boolean' | 'json';
+/**
+ * Drives editable approval of a tool call's arguments. Holds the original
+ * args, the user's live edits, which keys are dirty, whether every JSON field
+ * still parses, and a {@link diff} of only the changed keys so a consumer can
+ * send overrides only when something actually changed.
+ */
+export declare class ApprovalController {
+    #private;
+    /** The arguments as the tool proposed them — never mutated. */
+    readonly original: Record<string, unknown>;
+    /** Live edited values, keyed like {@link original}. */
+    edits: Record<string, unknown>;
+    constructor(args?: Record<string, unknown>);
+    /** Original entries in insertion order — the stable render list. */
+    get entries(): [string, unknown][];
+    /** Per-key dirty flags (edited value differs from the original). */
+    dirty: Record<string, boolean>;
+    /** True when every JSON field currently parses. */
+    valid: boolean;
+    /** How to render/coerce the field for `key`. */
+    kindOf(key: string): FieldKind;
+    isDirty(key: string): boolean;
+    isValid(key: string): boolean;
+    /** Pretty JSON for object/array fields' textarea seed content. */
+    json(key: string): string;
+    /** Display string for a primitive field. */
+    text(key: string): string;
+    /** Set a boolean field directly (from a switch). */
+    setBoolean(key: string, value: boolean): void;
+    /** Set a string/number field from raw input, coercing to the original type. */
+    setPrimitive(key: string, raw: string): void;
+    /** Parse a JSON field; on failure keep the last valid value and flag invalid. */
+    setJson(key: string, raw: string): void;
+    /** Restore a single field (or all fields) to its original value. */
+    reset(key?: string): void;
+    /** Only the changed keys and their edited values — send these as overrides. */
+    diff(): Record<string, unknown>;
+}
+export declare function setApprovalContext(ctrl: ApprovalController): ApprovalController;
+export declare function getApprovalContext(): ApprovalController;

package/dist/ai/confirmation/approval.svelte.js

@@ -0,0 +1,122 @@
+import { getContext, setContext } from 'svelte';
+function kindOf(value) {
+    if (typeof value === 'boolean')
+        return 'boolean';
+    if (typeof value === 'number' && Number.isFinite(value))
+        return 'number';
+    if (value !== null && typeof value === 'object')
+        return 'json';
+    return 'string';
+}
+/** Structural equality good enough for JSON-shaped tool arguments. */
+function equal(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+/**
+ * Drives editable approval of a tool call's arguments. Holds the original
+ * args, the user's live edits, which keys are dirty, whether every JSON field
+ * still parses, and a {@link diff} of only the changed keys so a consumer can
+ * send overrides only when something actually changed.
+ */
+export class ApprovalController {
+    /** The arguments as the tool proposed them — never mutated. */
+    original;
+    /** Live edited values, keyed like {@link original}. */
+    edits = $state({});
+    /** Per-key JSON parse validity; primitives are always valid. */
+    #valid = $state({});
+    constructor(args = {}) {
+        this.original = { ...args };
+        for (const [key, value] of Object.entries(args)) {
+            this.edits[key] = structuredClone(value);
+            this.#valid[key] = true;
+        }
+    }
+    /** Original entries in insertion order — the stable render list. */
+    get entries() {
+        return Object.entries(this.original);
+    }
+    /** Per-key dirty flags (edited value differs from the original). */
+    dirty = $derived.by(() => {
+        const out = {};
+        for (const key of Object.keys(this.original)) {
+            out[key] = !equal(this.original[key], this.edits[key]);
+        }
+        return out;
+    });
+    /** True when every JSON field currently parses. */
+    valid = $derived.by(() => Object.values(this.#valid).every(Boolean));
+    /** How to render/coerce the field for `key`. */
+    kindOf(key) {
+        return kindOf(this.original[key]);
+    }
+    isDirty(key) {
+        return this.dirty[key] ?? false;
+    }
+    isValid(key) {
+        return this.#valid[key] ?? true;
+    }
+    /** Pretty JSON for object/array fields' textarea seed content. */
+    json(key) {
+        return JSON.stringify(this.edits[key] ?? this.original[key], null, 2);
+    }
+    /** Display string for a primitive field. */
+    text(key) {
+        const value = this.edits[key];
+        if (value === null)
+            return 'null';
+        return String(value ?? '');
+    }
+    /** Set a boolean field directly (from a switch). */
+    setBoolean(key, value) {
+        this.edits[key] = value;
+    }
+    /** Set a string/number field from raw input, coercing to the original type. */
+    setPrimitive(key, raw) {
+        if (this.kindOf(key) === 'number') {
+            const n = Number(raw);
+            this.edits[key] = raw.trim() !== '' && Number.isFinite(n) ? n : raw;
+        }
+        else {
+            this.edits[key] = raw;
+        }
+    }
+    /** Parse a JSON field; on failure keep the last valid value and flag invalid. */
+    setJson(key, raw) {
+        try {
+            this.edits[key] = JSON.parse(raw);
+            this.#valid[key] = true;
+        }
+        catch {
+            this.#valid[key] = false;
+        }
+    }
+    /** Restore a single field (or all fields) to its original value. */
+    reset(key) {
+        const keys = key === undefined ? Object.keys(this.original) : [key];
+        for (const k of keys) {
+            this.edits[k] = structuredClone(this.original[k]);
+            this.#valid[k] = true;
+        }
+    }
+    /** Only the changed keys and their edited values — send these as overrides. */
+    diff() {
+        const out = {};
+        for (const key of Object.keys(this.original)) {
+            if (this.dirty[key])
+                out[key] = this.edits[key];
+        }
+        return out;
+    }
+}
+const KEY = Symbol('era-ai-approval');
+export function setApprovalContext(ctrl) {
+    setContext(KEY, ctrl);
+    return ctrl;
+}
+export function getApprovalContext() {
+    const ctx = getContext(KEY);
+    if (!ctx)
+        throw new Error('Approval parts must be used inside a Confirmation with a controller.');
+    return ctx;
+}

package/dist/ai/confirmation/confirmation-args.svelte

@@ -0,0 +1,67 @@
+<script lang="ts">
+	import { cn } from '../../utils/index.js';
+	import { Input, Textarea } from '../../ui/input/index.js';
+	import { Switch } from '../../ui/switch/index.js';
+	import { ApprovalController, getApprovalContext } from './approval.svelte.js';
+
+	let {
+		controller,
+		class: className
+	}: { controller?: ApprovalController; class?: string } = $props();
+
+	const ctrl = $derived(controller ?? getApprovalContext());
+
+	// JSON fields are edited as free text: we keep the raw string locally so the
+	// textarea keeps showing what the user typed even while it fails to parse
+	// (the controller only adopts the value once it parses again). Entries seed
+	// lazily from `ctrl.json(key)` until the field is first edited.
+	const jsonText = $state<Record<string, string>>({});
+</script>
+
+<div class={cn('flex min-w-0 flex-col gap-(--era-gap)', className)}>
+	{#if ctrl.entries.length === 0}
+		<span class="text-body text-muted">No arguments</span>
+	{:else}
+		{#each ctrl.entries as [key] (key)}
+			{@const kind = ctrl.kindOf(key)}
+			<div
+				class={cn(
+					'flex min-w-0 flex-col gap-(--era-gap)',
+					ctrl.isDirty(key) && 'border-s-2 border-warning ps-(--era-pad-sm)'
+				)}
+			>
+				<span class="text-[0.625rem] leading-none tracking-[0.15em] text-muted uppercase">{key}</span>
+
+				{#if kind === 'boolean'}
+					<Switch
+						checked={ctrl.edits[key] === true}
+						onCheckedChange={(value) => ctrl.setBoolean(key, value)}
+					/>
+				{:else if kind === 'json'}
+					<Textarea
+						value={jsonText[key] ?? ctrl.json(key)}
+						oninput={(event) => {
+							jsonText[key] = event.currentTarget.value;
+							ctrl.setJson(key, event.currentTarget.value);
+						}}
+						spellcheck={false}
+						class={cn(
+							'min-h-(--era-h-lg) font-mono text-body',
+							!ctrl.isValid(key) && 'border border-destructive'
+						)}
+					/>
+					{#if !ctrl.isValid(key)}
+						<span class="text-body text-destructive era-text-trim">Invalid JSON</span>
+					{/if}
+				{:else}
+					<Input
+						value={ctrl.text(key)}
+						oninput={(event) => ctrl.setPrimitive(key, event.currentTarget.value)}
+						inputmode={kind === 'number' ? 'decimal' : undefined}
+						spellcheck={false}
+					/>
+				{/if}
+			</div>
+		{/each}
+	{/if}
+</div>

package/dist/ai/confirmation/confirmation-args.svelte.d.ts

@@ -0,0 +1,8 @@
+import { ApprovalController } from './approval.svelte.js';
+type $$ComponentProps = {
+    controller?: ApprovalController;
+    class?: string;
+};
+declare const ConfirmationArgs: import("svelte").Component<$$ComponentProps, {}, "">;
+type ConfirmationArgs = ReturnType<typeof ConfirmationArgs>;
+export default ConfirmationArgs;

package/dist/ai/confirmation/index.d.ts

@@ -1,2 +1,4 @@
 export { default as Root, type ApprovalState } from './confirmation.svelte';
 export { default as Actions } from './confirmation-actions.svelte';
+export { default as Args } from './confirmation-args.svelte';
+export { ApprovalController, setApprovalContext, getApprovalContext, type FieldKind } from './approval.svelte.js';

package/dist/ai/confirmation/index.js

@@ -1,2 +1,4 @@
 export { default as Root } from './confirmation.svelte';
 export { default as Actions } from './confirmation-actions.svelte';
+export { default as Args } from './confirmation-args.svelte';
+export { ApprovalController, setApprovalContext, getApprovalContext } from './approval.svelte.js';

package/dist/ai/conversations/conversations-group.svelte

@@ -0,0 +1,28 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { cn } from '../../utils/index.js';
+
+	let {
+		label,
+		children,
+		class: className,
+		...restProps
+	}: HTMLAttributes<HTMLDivElement> & {
+		/** Tiny uppercase bucket header — Today / Yesterday / Starred / … */
+		label?: string;
+		children?: Snippet;
+	} = $props();
+</script>
+
+<!-- A time-bucket section: the step-section label idiom over its stack of rows. -->
+<div class={cn('flex min-w-0 flex-col gap-(--era-gap)', className)} {...restProps}>
+	{#if label}
+		<span
+			class="px-(--era-inset-md) text-[0.625rem] leading-none tracking-[0.15em] text-muted uppercase era-text-trim-caps"
+		>
+			{label}
+		</span>
+	{/if}
+	{@render children?.()}
+</div>

package/dist/ai/conversations/conversations-group.svelte.d.ts

@@ -0,0 +1,10 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+type $$ComponentProps = HTMLAttributes<HTMLDivElement> & {
+    /** Tiny uppercase bucket header — Today / Yesterday / Starred / … */
+    label?: string;
+    children?: Snippet;
+};
+declare const ConversationsGroup: import("svelte").Component<$$ComponentProps, {}, "">;
+type ConversationsGroup = ReturnType<typeof ConversationsGroup>;
+export default ConversationsGroup;

package/dist/ai/conversations/conversations-item.svelte

@@ -0,0 +1,208 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import MessageSquare from '@lucide/svelte/icons/message-square';
+	import Star from '@lucide/svelte/icons/star';
+	import X from '@lucide/svelte/icons/x';
+	import Trash2 from '@lucide/svelte/icons/trash-2';
+	import Check from '@lucide/svelte/icons/check';
+	import { Button } from '../../ui/button/index.js';
+	import { cn } from '../../utils/index.js';
+	import type { ConversationStatus } from './conversations.svelte.js';
+
+	let {
+		title = $bindable(''),
+		starred = $bindable(false),
+		status,
+		active = false,
+		leading,
+		onSelect,
+		onRename,
+		onStar,
+		onCancel,
+		onDelete,
+		class: className,
+		...restProps
+	}: Omit<HTMLAttributes<HTMLDivElement>, 'title'> & {
+		/** Conversation label; double-click to rename in place. Bindable. */
+		title?: string;
+		/** Bindable star state; the rail's star button toggles it. */
+		starred?: boolean;
+		/** Drives the status dot tone; omit for no dot. */
+		status?: ConversationStatus;
+		/** Highlighted as the open conversation. */
+		active?: boolean;
+		/** Overrides the leading icon (e.g. an expand chevron). */
+		leading?: Snippet;
+		/** Row activated (click / Enter on the title). */
+		onSelect?: () => void;
+		/** Fired after a non-empty rename commits, with the new title. */
+		onRename?: (title: string) => void;
+		/** Fired when the star toggles, with the new starred state. */
+		onStar?: (starred: boolean) => void;
+		/** Fired by the cancel button (shown while queued / running). */
+		onCancel?: () => void;
+		/** Fired on the confirming second delete click. */
+		onDelete?: () => void;
+	} = $props();
+
+	// The status dot: tone token per state; `running` breathes via animate-pulse.
+	const DOT: Record<ConversationStatus, { class: string; label: string }> = {
+		idle: { class: 'bg-muted', label: 'Idle' },
+		queued: { class: 'bg-warning', label: 'Queued' },
+		running: { class: 'bg-primary animate-pulse', label: 'Running' },
+		done: { class: 'bg-success', label: 'Done' },
+		error: { class: 'bg-destructive', label: 'Error' }
+	};
+
+	const showCancel = $derived(status === 'queued' || status === 'running');
+
+	// Inline rename. `draft` mirrors the title while editing; the bindable
+	// `title` only changes when a non-empty edit commits.
+	let editing = $state(false);
+	let draft = $state('');
+	let input = $state<HTMLInputElement | null>(null);
+
+	$effect(() => {
+		if (editing && input) {
+			input.focus();
+			input.select();
+		}
+	});
+
+	function startEditing() {
+		draft = title;
+		editing = true;
+	}
+
+	function commitRename() {
+		if (!editing) return;
+		const next = draft.trim();
+		editing = false;
+		if (next.length === 0 || next === title) return; // empty rejected; no-op unchanged
+		title = next;
+		onRename?.(next);
+	}
+
+	function cancelRename() {
+		editing = false;
+	}
+
+	function onTitleKeydown(event: KeyboardEvent) {
+		if (event.key === 'Enter') {
+			event.preventDefault();
+			commitRename();
+		} else if (event.key === 'Escape') {
+			event.preventDefault();
+			cancelRename();
+		}
+	}
+
+	function toggleStar() {
+		starred = !starred;
+		onStar?.(starred);
+	}
+
+	// Two-click delete: the first click arms (Trash → Check), the second within
+	// the window confirms. An optional timer and pointer-leave both disarm.
+	let armed = $state(false);
+	let disarmTimer: ReturnType<typeof setTimeout> | undefined;
+
+	function disarm() {
+		armed = false;
+		clearTimeout(disarmTimer);
+	}
+
+	function onDeleteClick() {
+		if (armed) {
+			disarm();
+			onDelete?.();
+			return;
+		}
+		armed = true;
+		clearTimeout(disarmTimer);
+		disarmTimer = setTimeout(() => (armed = false), 3000);
+	}
+</script>
+
+<div
+	data-active={active || undefined}
+	class={cn(
+		'group/row relative flex h-(--era-h-md) items-center gap-(--era-gap) rounded-(--era-rd-md) px-(--era-inset-md) text-body transition-colors duration-(--era-duration) ease-(--era-ease)',
+		active ? 'bg-hover text-bright' : 'text-fg hover:bg-(--era-highlight)',
+		className
+	)}
+	onmouseleave={disarm}
+	{...restProps}
+>
+	<!-- Leading: a chevron/expander slot, else the default conversation glyph. -->
+	{#if leading}
+		{@render leading()}
+	{:else}
+		<MessageSquare class="size-(--era-h-xs) shrink-0 text-muted" aria-hidden="true" />
+	{/if}
+
+	{#if status}
+		<span
+			class={cn('size-2 shrink-0 rounded-full', DOT[status].class)}
+			title={DOT[status].label}
+			aria-hidden="true"
+		></span>
+	{/if}
+
+	{#if editing}
+		<input
+			bind:this={input}
+			bind:value={draft}
+			onkeydown={onTitleKeydown}
+			onblur={commitRename}
+			aria-label="Rename conversation"
+			class="min-w-0 flex-1 border-b border-primary bg-transparent text-body text-bright outline-none era-text-trim"
+		/>
+	{:else}
+		<button
+			type="button"
+			onclick={onSelect}
+			ondblclick={startEditing}
+			class="min-w-0 flex-1 cursor-pointer truncate text-left outline-none era-text-trim"
+		>
+			{title}
+		</button>
+	{/if}
+
+	<!-- Action rail: hidden at rest, revealed on row hover or keyboard focus. -->
+	<div
+		class="flex shrink-0 items-center gap-(--era-gap) opacity-0 transition-opacity duration-(--era-duration) ease-(--era-ease) group-hover/row:opacity-100 focus-within:opacity-100"
+	>
+		<Button
+			icon
+			size="icon"
+			aria-label={starred ? 'Unstar conversation' : 'Star conversation'}
+			aria-pressed={starred}
+			onclick={toggleStar}
+		>
+			<Star class={cn('size-(--era-h-xs)', starred && 'fill-warning text-warning')} />
+		</Button>
+
+		{#if showCancel}
+			<Button icon size="icon" aria-label="Cancel generation" onclick={() => onCancel?.()}>
+				<X class="size-(--era-h-xs)" />
+			</Button>
+		{/if}
+
+		<Button
+			icon
+			size="icon"
+			tone="destructive"
+			active={armed}
+			aria-label={armed ? 'Confirm delete conversation' : 'Delete conversation'}
+			onclick={onDeleteClick}
+		>
+			{#if armed}
+				<Check class="size-(--era-h-xs)" />
+			{:else}
+				<Trash2 class="size-(--era-h-xs)" />
+			{/if}
+		</Button>
+	</div>
+</div>

package/dist/ai/conversations/conversations-item.svelte.d.ts

@@ -0,0 +1,28 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import type { ConversationStatus } from './conversations.svelte.js';
+type $$ComponentProps = Omit<HTMLAttributes<HTMLDivElement>, 'title'> & {
+    /** Conversation label; double-click to rename in place. Bindable. */
+    title?: string;
+    /** Bindable star state; the rail's star button toggles it. */
+    starred?: boolean;
+    /** Drives the status dot tone; omit for no dot. */
+    status?: ConversationStatus;
+    /** Highlighted as the open conversation. */
+    active?: boolean;
+    /** Overrides the leading icon (e.g. an expand chevron). */
+    leading?: Snippet;
+    /** Row activated (click / Enter on the title). */
+    onSelect?: () => void;
+    /** Fired after a non-empty rename commits, with the new title. */
+    onRename?: (title: string) => void;
+    /** Fired when the star toggles, with the new starred state. */
+    onStar?: (starred: boolean) => void;
+    /** Fired by the cancel button (shown while queued / running). */
+    onCancel?: () => void;
+    /** Fired on the confirming second delete click. */
+    onDelete?: () => void;
+};
+declare const ConversationsItem: import("svelte").Component<$$ComponentProps, {}, "title" | "starred">;
+type ConversationsItem = ReturnType<typeof ConversationsItem>;
+export default ConversationsItem;

package/dist/ai/conversations/conversations-root.svelte

@@ -0,0 +1,27 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { cn } from '../../utils/index.js';
+
+	let {
+		header,
+		children,
+		class: className,
+		...restProps
+	}: HTMLAttributes<HTMLDivElement> & {
+		/** Pinned above the scroll area — a "New chat" button, a filter, etc. */
+		header?: Snippet;
+		children?: Snippet;
+	} = $props();
+</script>
+
+<!-- The rail: a sticky header slot over a chromeless scroll column. min-h-0 lets
+     the list shrink inside a flex parent so only the list scrolls, not the page. -->
+<div class={cn('flex min-h-0 flex-col gap-(--era-gap)', className)} {...restProps}>
+	{#if header}
+		<div class="shrink-0">{@render header()}</div>
+	{/if}
+	<div class="scrollbar-none flex min-h-0 flex-1 flex-col gap-(--era-gap) overflow-y-auto">
+		{@render children?.()}
+	</div>
+</div>

package/dist/ai/conversations/conversations-root.svelte.d.ts

@@ -0,0 +1,10 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+type $$ComponentProps = HTMLAttributes<HTMLDivElement> & {
+    /** Pinned above the scroll area — a "New chat" button, a filter, etc. */
+    header?: Snippet;
+    children?: Snippet;
+};
+declare const ConversationsRoot: import("svelte").Component<$$ComponentProps, {}, "">;
+type ConversationsRoot = ReturnType<typeof ConversationsRoot>;
+export default ConversationsRoot;

package/dist/ai/conversations/conversations.svelte.d.ts

@@ -0,0 +1,38 @@
+/** Execution state of a conversation, drives the row's status dot tone. */
+export type ConversationStatus = 'idle' | 'queued' | 'running' | 'done' | 'error';
+/** Ordered time buckets. `starred` floats to the top, ahead of any age band. */
+export type TimeBucket = 'starred' | 'today' | 'yesterday' | 'last7days' | 'older';
+/** One conversation, as fed to the bucketer. `updatedAt` is epoch ms. */
+export interface ConversationEntry {
+    id: string;
+    title: string;
+    /** Epoch ms of last activity — both bucketed and sorted (newest-first) by this. */
+    updatedAt: number;
+    starred?: boolean;
+    status?: ConversationStatus;
+}
+/** A rendered section: a bucket, its display label, and its member rows. */
+export interface ConversationGroup {
+    bucket: TimeBucket;
+    label: string;
+    items: ConversationEntry[];
+}
+/**
+ * Group conversations for the rail: a leading `Starred` section (any age),
+ * then the non-empty age bands in order. Items within a group are newest-first.
+ * Pure — the `now` epoch (ms) is the only clock input.
+ */
+export declare function bucketConversations(items: ConversationEntry[], now: number): ConversationGroup[];
+/**
+ * Optional runes-class helper mirroring `BranchController`: holds the raw item
+ * list and a `now` epoch, and exposes reactively-bucketed `groups`. Feeding
+ * `now` from a consumer-owned `$state` re-buckets as the clock advances. Using
+ * the class is never required — `bucketConversations` covers the stateless case.
+ */
+export declare class ConversationsController {
+    items: ConversationEntry[];
+    /** Epoch ms; caller-supplied so the class never touches the clock. */
+    now: number;
+    constructor(items?: ConversationEntry[], now?: number);
+    readonly groups: ConversationGroup[];
+}

package/dist/ai/conversations/conversations.svelte.js

@@ -0,0 +1,73 @@
+// Headless bucketing for the conversation history rail. The library never
+// reads the clock itself — the caller passes a `now` epoch (ms) so the same
+// input always produces the same grouping (testable, SSR-safe). Consumers own
+// `Date.now()`, we own the relative-age math.
+const BUCKET_LABELS = {
+    starred: 'Starred',
+    today: 'Today',
+    yesterday: 'Yesterday',
+    last7days: 'Last 7 Days',
+    older: 'Older'
+};
+const AGE_ORDER = ['today', 'yesterday', 'last7days', 'older'];
+const DAY_MS = 86_400_000;
+/** Which age band a timestamp falls in, measured from the local start-of-today. */
+function ageBucket(updatedAt, now) {
+    // Local calendar start-of-today, built without mutating a Date instance.
+    const d = new Date(now);
+    const startOfToday = new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime();
+    if (updatedAt >= startOfToday)
+        return 'today';
+    if (updatedAt >= startOfToday - DAY_MS)
+        return 'yesterday';
+    if (updatedAt >= startOfToday - 7 * DAY_MS)
+        return 'last7days';
+    return 'older';
+}
+/**
+ * Group conversations for the rail: a leading `Starred` section (any age),
+ * then the non-empty age bands in order. Items within a group are newest-first.
+ * Pure — the `now` epoch (ms) is the only clock input.
+ */
+export function bucketConversations(items, now) {
+    const starred = [];
+    const byAge = {
+        today: [],
+        yesterday: [],
+        last7days: [],
+        older: []
+    };
+    for (const item of items) {
+        if (item.starred)
+            starred.push(item);
+        else
+            byAge[ageBucket(item.updatedAt, now)].push(item);
+    }
+    const newestFirst = (a, b) => b.updatedAt - a.updatedAt;
+    const groups = [];
+    if (starred.length > 0) {
+        groups.push({ bucket: 'starred', label: BUCKET_LABELS.starred, items: starred.sort(newestFirst) });
+    }
+    for (const bucket of AGE_ORDER) {
+        if (byAge[bucket].length > 0) {
+            groups.push({ bucket, label: BUCKET_LABELS[bucket], items: byAge[bucket].sort(newestFirst) });
+        }
+    }
+    return groups;
+}
+/**
+ * Optional runes-class helper mirroring `BranchController`: holds the raw item
+ * list and a `now` epoch, and exposes reactively-bucketed `groups`. Feeding
+ * `now` from a consumer-owned `$state` re-buckets as the clock advances. Using
+ * the class is never required — `bucketConversations` covers the stateless case.
+ */
+export class ConversationsController {
+    items = $state([]);
+    /** Epoch ms; caller-supplied so the class never touches the clock. */
+    now = $state(0);
+    constructor(items = [], now = 0) {
+        this.items = items;
+        this.now = now;
+    }
+    groups = $derived.by(() => bucketConversations(this.items, this.now));
+}