spiracha 1.5.0 → 2.1.0

package/apps/ui/components.json

@@ -0,0 +1,21 @@
+{
+    "$schema": "https://ui.shadcn.com/schema.json",
+    "aliases": {
+        "components": "#/components",
+        "hooks": "#/hooks",
+        "lib": "#/lib",
+        "ui": "#/components/ui",
+        "utils": "#/lib/utils"
+    },
+    "iconLibrary": "lucide",
+    "rsc": false,
+    "style": "new-york",
+    "tailwind": {
+        "baseColor": "zinc",
+        "config": "",
+        "css": "src/styles.css",
+        "cssVariables": true,
+        "prefix": ""
+    },
+    "tsx": true
+}

package/apps/ui/package.json

@@ -0,0 +1,65 @@
+{
+    "dependencies": {
+        "@tailwindcss/vite": "4.3.1",
+        "@tanstack/match-sorter-utils": "8.19.4",
+        "@tanstack/react-devtools": "0.10.5",
+        "@tanstack/react-query": "5.101.2",
+        "@tanstack/react-query-devtools": "5.101.2",
+        "@tanstack/react-router": "1.170.15",
+        "@tanstack/react-router-devtools": "1.167.0",
+        "@tanstack/react-router-ssr-query": "1.167.1",
+        "@tanstack/react-start": "1.168.25",
+        "@tanstack/react-table": "8.21.3",
+        "@tanstack/react-virtual": "3.14.2",
+        "@tanstack/router-plugin": "1.168.18",
+        "class-variance-authority": "0.7.1",
+        "clsx": "2.1.1",
+        "lucide-react": "1.18.0",
+        "radix-ui": "1.5.0",
+        "react": "19.2.7",
+        "react-dom": "19.2.7",
+        "tailwind-merge": "3.6.0",
+        "tailwindcss": "4.3.1",
+        "tw-animate-css": "1.4.0",
+        "zod": "4.4.3"
+    },
+    "devDependencies": {
+        "@biomejs/biome": "2.5.0",
+        "@tailwindcss/typography": "0.5.20",
+        "@tanstack/devtools-vite": "0.7.0",
+        "@testing-library/dom": "10.4.1",
+        "@testing-library/react": "16.3.2",
+        "@types/node": "25.9.3",
+        "@types/react": "19.2.17",
+        "@types/react-dom": "19.2.3",
+        "@vitejs/plugin-react": "6.0.2",
+        "@vitest/coverage-v8": "4.1.8",
+        "jsdom": "29.1.1",
+        "typescript": "6.0.3",
+        "vite": "8.0.16",
+        "vitest": "4.1.8"
+    },
+    "imports": {
+        "#/*": "./src/*"
+    },
+    "name": "ui",
+    "pnpm": {
+        "onlyBuiltDependencies": [
+            "esbuild",
+            "lightningcss"
+        ]
+    },
+    "private": true,
+    "scripts": {
+        "build": "bun --bun vite build",
+        "check": "biome check",
+        "coverage": "vitest run --coverage",
+        "dev": "bun --bun vite dev --host 127.0.0.1 --port 3000",
+        "format": "biome format",
+        "lint": "biome lint",
+        "preview": "bun --bun vite preview",
+        "test": "vitest run",
+        "typecheck": "tsc --noEmit"
+    },
+    "type": "module"
+}

package/apps/ui/src/components/antigravity-conversations-table.tsx

@@ -0,0 +1,245 @@
+import type { AntigravityConversation } from '@spiracha/lib/antigravity-exporter-types';
+import type { AntigravityDecryptionState } from '@spiracha/lib/antigravity-keychain';
+import { Link } from '@tanstack/react-router';
+import type { SortingState } from '@tanstack/react-table';
+import { createColumnHelper } from '@tanstack/react-table';
+import { Download, LockKeyhole, MoreHorizontal, ScrollText, Trash2 } from 'lucide-react';
+import { useMemo } from 'react';
+import { DataTable } from '#/components/data-table';
+import { SelectionActionsToolbar } from '#/components/selection-actions-toolbar';
+import { Badge } from '#/components/ui/badge';
+import { Button } from '#/components/ui/button';
+import {
+    DropdownMenu,
+    DropdownMenuContent,
+    DropdownMenuItem,
+    DropdownMenuTrigger,
+} from '#/components/ui/dropdown-menu';
+import {
+    canExportAntigravityConversation,
+    hasEncryptedAntigravityConversation,
+    hasReadableAntigravityConversation,
+    isAntigravityConversationLocked,
+} from '#/lib/antigravity-conversation-state';
+import { formatBytes, formatDateTime, formatNumber } from '#/lib/formatters';
+
+type AntigravityConversationsTableProps = {
+    conversations: AntigravityConversation[];
+    decryptionState: AntigravityDecryptionState | null;
+    onDeleteConversation: (conversation: AntigravityConversation) => void;
+    onDeleteConversations: (conversationIds: string[]) => void;
+    onExportArtifacts: (conversation: AntigravityConversation) => void;
+    onExportConversation: (conversation: AntigravityConversation) => void;
+    onExportConversations: (conversationIds: string[]) => void;
+};
+
+type ConversationExportState = {
+    canExportConversation: boolean;
+    hasArtifacts: boolean;
+    hasTranscript: boolean;
+    lockedTranscript: boolean;
+    showConversationAction: boolean;
+};
+
+const columnHelper = createColumnHelper<AntigravityConversation>();
+const defaultSorting: SortingState = [{ desc: true, id: 'updatedAt' }];
+
+const getConversationExportState = (
+    conversation: AntigravityConversation,
+    decryptionState: AntigravityDecryptionState | null,
+): ConversationExportState => {
+    const hasArtifacts = conversation.artifactCount > 0;
+    const isUnlocked = Boolean(decryptionState?.isUnlocked);
+    const hasTranscript =
+        hasReadableAntigravityConversation(conversation) || hasEncryptedAntigravityConversation(conversation);
+    const canExportConversation = canExportAntigravityConversation(conversation, isUnlocked);
+    const lockedTranscript = isAntigravityConversationLocked(conversation, isUnlocked);
+    const showConversationAction = canExportConversation || lockedTranscript;
+
+    return {
+        canExportConversation,
+        hasArtifacts,
+        hasTranscript,
+        lockedTranscript,
+        showConversationAction,
+    };
+};
+
+const getTranscriptLabel = (
+    conversation: AntigravityConversation,
+    exportState: Pick<ConversationExportState, 'hasTranscript' | 'lockedTranscript'>,
+) => {
+    if (!exportState.hasTranscript) {
+        return 'Summary only';
+    }
+
+    const source = conversation.transcriptSource ? conversation.transcriptSource.replace(/-/gu, ' ') : 'transcript';
+    const status = exportState.lockedTranscript ? 'locked' : 'available';
+    return `${source} · ${status}`;
+};
+
+const getConversationSizeLabel = (conversation: AntigravityConversation): string => {
+    if (conversation.totalBytes > 0) {
+        return formatBytes(conversation.totalBytes);
+    }
+
+    return conversation.summaryPath ? 'Summary' : formatBytes(conversation.totalBytes);
+};
+
+const columns = (
+    decryptionState: AntigravityDecryptionState | null,
+    onDeleteConversation: (conversation: AntigravityConversation) => void,
+    onExportConversation: (conversation: AntigravityConversation) => void,
+    onExportArtifacts: (conversation: AntigravityConversation) => void,
+) =>
+    [
+        columnHelper.accessor('title', {
+            cell: (info) => {
+                const exportState = getConversationExportState(info.row.original, decryptionState);
+
+                return (
+                    <Link
+                        className="block w-[16rem] max-w-[22rem] space-y-1 rounded-md outline-none transition hover:opacity-80 focus-visible:ring-2 focus-visible:ring-[var(--accent)] lg:w-auto"
+                        params={{ conversationId: info.row.original.conversationId }}
+                        to="/antigravity-conversations/$conversationId"
+                    >
+                        <div className="flex items-center gap-2">
+                            <p className="truncate font-medium underline-offset-2 hover:underline">{info.getValue()}</p>
+                            {exportState.hasTranscript ? <Badge variant="secondary">transcript</Badge> : null}
+                            {exportState.hasArtifacts ? <Badge variant="outline">artifact</Badge> : null}
+                        </div>
+                        <p className="truncate text-[var(--muted-foreground)] text-xs">
+                            {info.row.original.conversationId}
+                        </p>
+                    </Link>
+                );
+            },
+            header: 'Conversation',
+        }),
+        columnHelper.accessor('lastUpdatedAtMs', {
+            cell: (info) => (
+                <span className="whitespace-nowrap text-sm" suppressHydrationWarning>
+                    {formatDateTime(info.getValue())}
+                </span>
+            ),
+            header: 'Updated',
+            id: 'updatedAt',
+        }),
+        columnHelper.display({
+            cell: (info) => {
+                const exportState = getConversationExportState(info.row.original, decryptionState);
+                return (
+                    <span className="text-sm">
+                        {getTranscriptLabel(info.row.original, exportState)}
+                        {info.row.original.transcriptEntryCount > 0
+                            ? ` · ${formatNumber(info.row.original.transcriptEntryCount)} entries`
+                            : ''}
+                    </span>
+                );
+            },
+            header: 'Transcript',
+            id: 'transcript',
+        }),
+        columnHelper.accessor('artifactCount', {
+            cell: (info) => <span className="font-mono text-sm">{formatNumber(info.getValue())}</span>,
+            header: 'Artifacts',
+        }),
+        columnHelper.accessor('totalBytes', {
+            cell: (info) => <span className="font-mono text-sm">{getConversationSizeLabel(info.row.original)}</span>,
+            header: 'Size',
+        }),
+        columnHelper.display({
+            cell: (info) => {
+                const exportState = getConversationExportState(info.row.original, decryptionState);
+                return (
+                    <DropdownMenu>
+                        <DropdownMenuTrigger asChild>
+                            <Button
+                                className="rounded-full"
+                                size="icon"
+                                type="button"
+                                variant="ghost"
+                                onClick={(event) => event.stopPropagation()}
+                            >
+                                <MoreHorizontal className="size-4" />
+                            </Button>
+                        </DropdownMenuTrigger>
+                        <DropdownMenuContent align="end">
+                            {exportState.showConversationAction ? (
+                                <DropdownMenuItem
+                                    disabled={!exportState.canExportConversation}
+                                    onClick={() => onExportConversation(info.row.original)}
+                                >
+                                    {exportState.lockedTranscript ? (
+                                        <LockKeyhole className="mr-2 size-4" />
+                                    ) : (
+                                        <Download className="mr-2 size-4" />
+                                    )}
+                                    {exportState.lockedTranscript
+                                        ? 'Unlock conversation export first'
+                                        : 'Export conversation'}
+                                </DropdownMenuItem>
+                            ) : null}
+                            {exportState.hasArtifacts ? (
+                                <DropdownMenuItem onClick={() => onExportArtifacts(info.row.original)}>
+                                    <ScrollText className="mr-2 size-4" />
+                                    Export artifacts
+                                </DropdownMenuItem>
+                            ) : null}
+                            <DropdownMenuItem
+                                className="text-[var(--destructive)]"
+                                onClick={() => onDeleteConversation(info.row.original)}
+                            >
+                                <Trash2 className="mr-2 size-4" />
+                                Delete conversation
+                            </DropdownMenuItem>
+                        </DropdownMenuContent>
+                    </DropdownMenu>
+                );
+            },
+            header: '',
+            id: 'actions',
+        }),
+    ] as const;
+
+export function AntigravityConversationsTable({
+    conversations,
+    decryptionState,
+    onDeleteConversation,
+    onDeleteConversations,
+    onExportArtifacts,
+    onExportConversation,
+    onExportConversations,
+}: AntigravityConversationsTableProps) {
+    const tableColumns = useMemo(
+        () => columns(decryptionState, onDeleteConversation, onExportConversation, onExportArtifacts),
+        [decryptionState, onDeleteConversation, onExportArtifacts, onExportConversation],
+    );
+
+    return (
+        <DataTable
+            columns={tableColumns}
+            data={conversations}
+            emptyMessage="No Antigravity conversations match the current workspace filter."
+            enableRowSelection
+            getRowId={(row) => row.conversationId}
+            initialSorting={defaultSorting}
+            renderToolbar={({ clearSelection, selectedRows }) => {
+                const selectedConversationIds = selectedRows.map((row) => row.conversationId);
+                const hasNonExportableSelection = selectedRows.some(
+                    (row) => !getConversationExportState(row, decryptionState).canExportConversation,
+                );
+                return (
+                    <SelectionActionsToolbar
+                        clearSelection={clearSelection}
+                        exportDisabled={hasNonExportableSelection}
+                        itemLabel="conversation"
+                        selectedCount={selectedRows.length}
+                        onDeleteSelected={() => onDeleteConversations(selectedConversationIds)}
+                        onExportSelected={() => onExportConversations(selectedConversationIds)}
+                    />
+                );
+            }}
+        />
+    );
+}

package/apps/ui/src/components/antigravity-keychain-panel.tsx

@@ -0,0 +1,76 @@
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { KeyRound, LockKeyhole, ShieldCheck, TriangleAlert } from 'lucide-react';
+import { Button } from '#/components/ui/button';
+import { antigravityDecryptionQueryOptions } from '#/lib/antigravity-queries';
+import { unlockAntigravityDecryptionFn } from '#/lib/antigravity-server';
+import { cn } from '#/lib/utils';
+
+export function AntigravityKeychainPanel() {
+    const queryClient = useQueryClient();
+    const decryptionQuery = useQuery(antigravityDecryptionQueryOptions());
+    const decryptionState = decryptionQuery.data ?? null;
+    const unlockMutation = useMutation({
+        mutationFn: () => unlockAntigravityDecryptionFn(),
+        onSuccess: (result) => {
+            queryClient.setQueryData(antigravityDecryptionQueryOptions().queryKey, result);
+            void Promise.all([
+                queryClient.invalidateQueries({ queryKey: antigravityDecryptionQueryOptions().queryKey }),
+                queryClient.invalidateQueries({ queryKey: ['antigravity-conversation'] }),
+            ]);
+        },
+    });
+
+    if (!decryptionState || decryptionState.status === 'unsupported') {
+        return null;
+    }
+
+    const isUnlocked = decryptionState.isUnlocked;
+    const error = unlockMutation.error?.message ?? decryptionState.error;
+
+    return (
+        <div
+            className={cn(
+                'flex flex-col gap-3 rounded-xl border px-4 py-3 sm:flex-row sm:items-center sm:justify-between',
+                isUnlocked ? 'border-emerald-500/30 bg-emerald-500/10' : 'border-[var(--border)] bg-[var(--panel)]',
+            )}
+        >
+            <div className="flex min-w-0 items-start gap-3">
+                <div
+                    className={cn(
+                        'mt-0.5 flex size-8 shrink-0 items-center justify-center rounded-md',
+                        isUnlocked ? 'bg-emerald-500/15 text-emerald-600' : 'bg-[var(--panel-secondary)]',
+                    )}
+                >
+                    {isUnlocked ? <ShieldCheck className="size-4" /> : <LockKeyhole className="size-4" />}
+                </div>
+                <div className="min-w-0">
+                    <p className="font-medium text-sm">
+                        {isUnlocked ? 'Keychain access enabled' : 'Unlock Antigravity transcript export'}
+                    </p>
+                    <p className="mt-1 text-[var(--muted-foreground)] text-xs">
+                        {isUnlocked
+                            ? 'The Antigravity key is cached in this server process only. Transcript exports are available for local logs and safe-storage payloads.'
+                            : `Spiracha needs one-time access to ${decryptionState.keychainService} to decrypt Antigravity transcript data. macOS will ask for approval after you click unlock.`}
+                    </p>
+                    {error ? (
+                        <p className="mt-2 flex items-center gap-1 text-[var(--destructive)] text-xs">
+                            <TriangleAlert className="size-3" />
+                            {error}
+                        </p>
+                    ) : null}
+                </div>
+            </div>
+            {!isUnlocked ? (
+                <Button
+                    className="shrink-0"
+                    disabled={!decryptionState.canRequestAccess || unlockMutation.isPending}
+                    type="button"
+                    onClick={() => unlockMutation.mutate()}
+                >
+                    <KeyRound className="size-4" />
+                    {unlockMutation.isPending ? 'Waiting...' : 'Unlock'}
+                </Button>
+            ) : null}
+        </div>
+    );
+}

package/apps/ui/src/components/antigravity-workspaces-table.tsx

@@ -0,0 +1,63 @@
+import type { AntigravityWorkspaceGroup } from '@spiracha/lib/antigravity-exporter-types';
+import { Link } from '@tanstack/react-router';
+import { createColumnHelper } from '@tanstack/react-table';
+import { DataTable } from '#/components/data-table';
+import { formatBytes, formatDateTime, formatNumber } from '#/lib/formatters';
+
+type AntigravityWorkspacesTableProps = {
+    workspaces: AntigravityWorkspaceGroup[];
+};
+
+const columnHelper = createColumnHelper<AntigravityWorkspaceGroup>();
+
+const columns = [
+    columnHelper.accessor('label', {
+        cell: (info) => (
+            <Link
+                className="block w-[16rem] max-w-[22rem] space-y-1 rounded-md outline-none transition hover:opacity-80 focus-visible:ring-2 focus-visible:ring-[var(--accent)] lg:w-auto"
+                params={{ workspaceKey: info.row.original.key }}
+                to="/antigravity/$workspaceKey"
+            >
+                <p className="font-medium underline-offset-2 hover:underline">{info.getValue()}</p>
+                <p className="truncate text-[var(--muted-foreground)] text-xs">
+                    {info.row.original.uri ?? 'Unknown root'}
+                </p>
+            </Link>
+        ),
+        header: 'Workspace',
+    }),
+    columnHelper.accessor('conversationCount', {
+        cell: (info) => <span className="font-mono text-sm">{formatNumber(info.getValue())}</span>,
+        header: 'Conversations',
+    }),
+    columnHelper.accessor('transcriptCount', {
+        cell: (info) => <span className="font-mono text-sm">{formatNumber(info.getValue())}</span>,
+        header: 'Transcripts',
+    }),
+    columnHelper.accessor('artifactCount', {
+        cell: (info) => <span className="font-mono text-sm">{formatNumber(info.getValue())}</span>,
+        header: 'Artifacts',
+    }),
+    columnHelper.accessor('totalBytes', {
+        cell: (info) => <span className="font-mono text-sm">{formatBytes(info.getValue())}</span>,
+        header: 'Size',
+    }),
+    columnHelper.accessor('lastActiveMs', {
+        cell: (info) => (
+            <span className="whitespace-nowrap text-sm" suppressHydrationWarning>
+                {formatDateTime(info.getValue())}
+            </span>
+        ),
+        header: 'Last updated',
+    }),
+] as const;
+
+export function AntigravityWorkspacesTable({ workspaces }: AntigravityWorkspacesTableProps) {
+    return (
+        <DataTable
+            columns={columns}
+            data={workspaces}
+            emptyMessage="No Antigravity workspaces match the current search."
+        />
+    );
+}

package/apps/ui/src/components/app-shell.tsx

@@ -0,0 +1,125 @@
+import { Link, useRouterState } from '@tanstack/react-router';
+import {
+    BarChart3,
+    Bot,
+    BrainCircuit,
+    Code2,
+    FolderOpen,
+    LayoutDashboard,
+    Settings2,
+    Sparkles,
+    SquareTerminal,
+    Workflow,
+} from 'lucide-react';
+import type { PropsWithChildren } from 'react';
+import { packageMetadata } from '#/lib/package-metadata';
+import { cn } from '#/lib/utils';
+import { ThemeToggle } from './theme-toggle';
+
+type NavItem = {
+    activePrefixes?: readonly string[];
+    icon: typeof LayoutDashboard;
+    label: string;
+    to: string;
+};
+
+const navItems: readonly NavItem[] = [
+    { icon: LayoutDashboard, label: 'Dashboard', to: '/' },
+    { activePrefixes: ['/codex', '/threads'], icon: FolderOpen, label: 'Codex', to: '/codex' },
+    {
+        activePrefixes: ['/claude-code', '/claude-code-sessions'],
+        icon: Bot,
+        label: 'Claude Code',
+        to: '/claude-code',
+    },
+    { activePrefixes: ['/grok', '/grok-sessions'], icon: Bot, label: 'Grok', to: '/grok' },
+    { activePrefixes: ['/kiro', '/kiro-sessions'], icon: BrainCircuit, label: 'Kiro', to: '/kiro' },
+    { activePrefixes: ['/qoder', '/qoder-sessions'], icon: Workflow, label: 'Qoder', to: '/qoder' },
+    {
+        activePrefixes: ['/antigravity', '/antigravity-conversations'],
+        icon: Sparkles,
+        label: 'Antigravity',
+        to: '/antigravity',
+    },
+    { activePrefixes: ['/cursor', '/cursor-threads'], icon: SquareTerminal, label: 'Cursor', to: '/cursor' },
+    { activePrefixes: ['/opencode', '/opencode-sessions'], icon: Code2, label: 'OpenCode', to: '/opencode' },
+    { icon: BarChart3, label: 'Analytics', to: '/analytics' },
+    { icon: Settings2, label: 'Settings', to: '/settings' },
+] as const;
+
+const isNavItemActive = (pathname: string, item: NavItem) => {
+    const prefixes = item.activePrefixes ?? [item.to];
+    return prefixes.some((prefix) => pathname === prefix || pathname.startsWith(`${prefix}/`));
+};
+
+const GitHubIcon = ({ className }: { className?: string }) => (
+    <svg aria-hidden="true" className={className} fill="currentColor" viewBox="0 0 24 24">
+        <path d="M12 2C6.48 2 2 6.59 2 12.25c0 4.53 2.87 8.36 6.84 9.72.5.09.68-.22.68-.49v-1.9c-2.78.62-3.37-1.22-3.37-1.22-.45-1.18-1.11-1.49-1.11-1.49-.91-.64.07-.63.07-.63 1 .07 1.53 1.06 1.53 1.06.9 1.56 2.35 1.11 2.92.85.09-.67.35-1.11.63-1.37-2.22-.26-4.56-1.14-4.56-5.06 0-1.12.39-2.03 1.03-2.75-.1-.26-.45-1.3.1-2.71 0 0 .84-.28 2.75 1.05A9.35 9.35 0 0 1 12 6.98c.85 0 1.7.12 2.5.35 1.9-1.33 2.74-1.05 2.74-1.05.55 1.41.2 2.45.1 2.71.64.72 1.03 1.63 1.03 2.75 0 3.93-2.34 4.79-4.57 5.05.36.32.68.95.68 1.91v2.78c0 .27.18.59.69.49A10.22 10.22 0 0 0 22 12.25C22 6.59 17.52 2 12 2Z" />
+    </svg>
+);
+
+export function AppShell({ children }: PropsWithChildren) {
+    const pathname = useRouterState({
+        select: (state) => state.location.pathname,
+    });
+
+    return (
+        <div className="min-h-screen bg-[var(--background)] text-[var(--foreground)]">
+            <div className="flex min-h-screen w-full flex-col lg:flex-row">
+                <aside className="border-[var(--border)] border-b bg-[var(--panel)]/90 px-5 py-5 backdrop-blur lg:sticky lg:top-0 lg:h-screen lg:w-[240px] lg:border-r lg:border-b-0 lg:px-5">
+                    <div className="flex items-start justify-between gap-4 lg:flex-col lg:items-stretch">
+                        <div className="space-y-1.5">
+                            <p className="font-semibold text-[10px] text-[var(--muted-foreground)] uppercase tracking-[0.18em]">
+                                Spiracha <span className="tracking-normal">v{packageMetadata.version}</span>
+                            </p>
+                            <div className="space-y-1">
+                                <h1 className="font-['IBM_Plex_Sans'] font-semibold text-lg tracking-[-0.02em]">
+                                    Spiracha Console
+                                </h1>
+                                {packageMetadata.homepage ? (
+                                    <a
+                                        aria-label="Open Spiracha GitHub repository"
+                                        className="inline-flex size-7 items-center justify-center rounded-md text-[var(--muted-foreground)] transition-colors hover:bg-[var(--panel-secondary)] hover:text-[var(--foreground)]"
+                                        href={packageMetadata.homepage}
+                                        rel="noreferrer"
+                                        target="_blank"
+                                    >
+                                        <GitHubIcon className="size-4" />
+                                    </a>
+                                ) : null}
+                            </div>
+                        </div>
+                        <ThemeToggle />
+                    </div>
+
+                    <nav className="mt-5 grid gap-1">
+                        {navItems.map((item) => {
+                            const active = isNavItemActive(pathname, item);
+                            const Icon = item.icon;
+
+                            return (
+                                <Link
+                                    activeOptions={{ includeSearch: false }}
+                                    aria-current={active ? 'page' : undefined}
+                                    key={item.to}
+                                    className={cn(
+                                        'flex items-center gap-2.5 rounded-lg px-3 py-2 text-sm transition-colors',
+                                        active
+                                            ? 'bg-[var(--accent-muted)] font-medium text-[var(--accent-foreground)]'
+                                            : 'text-[var(--muted-foreground)] hover:bg-[var(--panel-secondary)] hover:text-[var(--foreground)]',
+                                    )}
+                                    to={item.to}
+                                >
+                                    <Icon className="size-4 shrink-0" />
+                                    <span>{item.label}</span>
+                                </Link>
+                            );
+                        })}
+                    </nav>
+                </aside>
+
+                <main className="min-w-0 flex-1 px-4 py-4 sm:px-5 sm:py-5 lg:px-6">{children}</main>
+            </div>
+        </div>
+    );
+}

package/apps/ui/src/components/breadcrumbs.tsx

@@ -0,0 +1,71 @@
+import { Link } from '@tanstack/react-router';
+import { ChevronRight } from 'lucide-react';
+import type { ReactNode } from 'react';
+
+type BreadcrumbItem =
+    | {
+          label: string;
+          title?: string;
+          truncate?: boolean;
+      }
+    | {
+          label: string;
+          params?: Record<string, string>;
+          title?: string;
+          to: string;
+          truncate?: boolean;
+      };
+
+type BreadcrumbsProps = {
+    items: BreadcrumbItem[];
+};
+
+const isLinkItem = (item: BreadcrumbItem): item is Extract<BreadcrumbItem, { to: string }> => {
+    return 'to' in item;
+};
+
+const classNames = (...values: string[]) => values.filter(Boolean).join(' ');
+
+export const Breadcrumbs = ({ items }: BreadcrumbsProps) => {
+    return (
+        <nav aria-label="Breadcrumb" className="flex flex-wrap items-center gap-1 text-sm">
+            {items.map((item, index) => {
+                const title = item.title ?? (item.truncate ? item.label : undefined);
+                const truncateClassName = item.truncate
+                    ? 'inline-block max-w-[min(34rem,62vw)] truncate align-bottom'
+                    : '';
+                const content: ReactNode = isLinkItem(item) ? (
+                    <Link
+                        className={classNames(
+                            truncateClassName,
+                            'text-[var(--muted-foreground)] transition hover:text-[var(--foreground)]',
+                        )}
+                        params={item.params}
+                        title={title}
+                        to={item.to}
+                    >
+                        {item.label}
+                    </Link>
+                ) : (
+                    <span
+                        aria-current="page"
+                        className={classNames(truncateClassName, 'font-medium text-[var(--foreground)]')}
+                        title={title}
+                    >
+                        {item.label}
+                    </span>
+                );
+
+                return (
+                    <div
+                        className="flex min-w-0 items-center gap-1"
+                        key={isLinkItem(item) ? `${item.label}-${item.to}-${index}` : `${item.label}-current-${index}`}
+                    >
+                        {index > 0 ? <ChevronRight className="size-3.5 text-[var(--muted-foreground)]" /> : null}
+                        {content}
+                    </div>
+                );
+            })}
+        </nav>
+    );
+};