@tangle-network/sandbox-ui 0.28.0 → 0.30.0

package/dist/tokens.css

@@ -45,25 +45,25 @@
   --md3-inverse-on-surface: #000000;
   --md3-surface-tint: #818CF8;
 
-  /* Semantic HSL bridge */
-  --hsl-background: 244 28% 5%;
-  --hsl-foreground: 240 18% 94%;
-  --hsl-card: 246 30% 11%;
-  --hsl-card-foreground: 240 18% 94%;
-  --hsl-popover: 246 28% 14%;
-  --hsl-popover-foreground: 240 18% 94%;
+  /* Semantic HSL bridge — flat neutral spine (Tangle Quiet) */
+  --hsl-background: 240 8% 5%;     /* #0b0b0d */
+  --hsl-foreground: 240 6% 93%;    /* #ececee */
+  --hsl-card: 240 5% 8%;           /* #141416 surface */
+  --hsl-card-foreground: 240 6% 93%;
+  --hsl-popover: 240 4% 13%;       /* #202023 elevated */
+  --hsl-popover-foreground: 240 6% 93%;
   --hsl-primary: 239 84% 67%;
   --hsl-primary-foreground: 0 0% 100%;
-  --hsl-secondary: 248 24% 18%;
-  --hsl-secondary-foreground: 240 16% 90%;
-  --hsl-muted: 246 22% 15%;
-  --hsl-muted-foreground: 240 14% 58%;
-  --hsl-accent: 248 26% 20%;
-  --hsl-accent-foreground: 240 16% 92%;
+  --hsl-secondary: 240 5% 11%;     /* #1a1a1d surface-2 */
+  --hsl-secondary-foreground: 240 6% 93%;
+  --hsl-muted: 240 5% 11%;         /* #1a1a1d — neutral hover well */
+  --hsl-muted-foreground: 240 4% 62%;  /* #9a9aa2 text-muted */
+  --hsl-accent: 240 5% 11%;        /* neutral hover (indigo lives in accent-surface-strong) */
+  --hsl-accent-foreground: 240 6% 93%;
   --hsl-destructive: 348 90% 60%;
   --hsl-destructive-foreground: 0 0% 100%;
-  --hsl-border: 244 14% 22%;
-  --hsl-input: 246 28% 14%;
+  --hsl-border: 240 3% 13%;        /* hairline ≈ rgba(255,255,255,0.07) */
+  --hsl-input: 240 5% 11%;
   --hsl-ring: 239 84% 67%;
   --hsl-success: 160 84% 39%;
   --hsl-warning: 40 94% 56%;
@@ -94,21 +94,21 @@
   --error: var(--hsl-destructive);
   --info: var(--hsl-info);
 
-  /* Sidebar tokens */
-  --sidebar-background: 244 28% 5%;
-  --sidebar-foreground: 240 18% 94%;
+  /* Sidebar tokens — flat surface + hairline */
+  --sidebar-background: 240 5% 8%;   /* #141416 surface */
+  --sidebar-foreground: 240 6% 93%;
   --sidebar-primary: 239 84% 67%;
   --sidebar-primary-foreground: 0 0% 100%;
-  --sidebar-accent: 248 26% 20%;
-  --sidebar-accent-foreground: 240 16% 92%;
-  --sidebar-border: 244 14% 17%;
+  --sidebar-accent: 240 5% 11%;      /* neutral hover */
+  --sidebar-accent-foreground: 240 6% 93%;
+  --sidebar-border: 240 3% 13%;      /* hairline */
   --sidebar-ring: 239 84% 67%;
 
-  /* Depth scale — Tangle deep purple surfaces */
-  --depth-1: #0C0B1D;
-  --depth-2: #141328;
-  --depth-3: #1D1B38;
-  --depth-4: #262448;
+  /* Depth scale — flat neutral spine (Tangle Quiet) */
+  --depth-1: #0b0b0d;
+  --depth-2: #141416;
+  --depth-3: #1a1a1d;
+  --depth-4: #202023;
 
   /* Status colors */
   --status-running: #10B981;
@@ -152,36 +152,35 @@
   --glass-border-hover: var(--border-default);
   --glass-blur: 0px;
 
-  /* Mesh gradient — Tangle brand glows */
-  --mesh-teal: rgba(16, 185, 129, 0.05);
-  --mesh-violet: rgba(99, 102, 241, 0.07);
-  --mesh-blue: rgba(129, 140, 248, 0.04);
+  /* Mesh glows — quieted to off; chrome is flat in Tangle Quiet */
+  --mesh-teal: transparent;
+  --mesh-violet: transparent;
+  --mesh-blue: transparent;
 
-  /* Brand gradients — Tangle */
+  /* Brand gradients — the indigo spark, kept ONLY for the logo mark + send button */
   --tangle-gradient: linear-gradient(135deg, #6366F1, #818CF8);
   --tangle-gradient-text: linear-gradient(135deg, #A5AAFC, #818CF8);
   --accent-gradient-strong: linear-gradient(135deg, #6366F1, #818CF8);
-  --accent-surface-soft: rgba(99, 102, 241, 0.12);
-  --accent-surface-strong: rgba(99, 102, 241, 0.20);
-  --accent-text: #A5AAFC;
-
-  /* Surfaces */
-  --bg-root: radial-gradient(ellipse 70% 50% at 20% 0%, rgba(99, 102, 241, 0.08), transparent),
-             radial-gradient(ellipse 50% 40% at 80% 10%, rgba(129, 140, 248, 0.06), transparent),
-             linear-gradient(180deg, var(--depth-1), #0D0C1E 100%);
+  /* Accent wells — soft = hover neutral, strong = active/selected row (indigo) */
+  --accent-surface-soft: rgba(255, 255, 255, 0.04);
+  --accent-surface-strong: rgba(129, 140, 248, 0.14);
+  --accent-text: #b9bffb;
+
+  /* Surfaces — flat single-neutral (no radial mesh) */
+  --bg-root: #0b0b0d;
   --bg-dark: var(--depth-1);
-  --bg-card: hsl(var(--hsl-card));
-  --bg-elevated: hsl(246 28% 17%);
-  --bg-section: hsl(246 28% 9%);
-  --bg-input: hsl(var(--hsl-input));
-  --bg-hover: rgba(99, 102, 241, 0.08);
-  --bg-selection: rgba(99, 102, 241, 0.18);
-
-  /* Text */
-  --text-primary: hsl(var(--hsl-foreground));
-  --text-secondary: hsl(240 16% 85%);
-  --text-muted: #8688B0;
-  --text-dim: #606294;
+  --bg-card: var(--depth-2);
+  --bg-elevated: var(--depth-4);
+  --bg-section: var(--depth-1);
+  --bg-input: var(--depth-3);
+  --bg-hover: rgba(255, 255, 255, 0.04);
+  --bg-selection: rgba(129, 140, 248, 0.14);
+
+  /* Text — neutral */
+  --text-primary: #ececee;
+  --text-secondary: #c8c8cd;
+  --text-muted: #9a9aa2;
+  --text-dim: #6b6b73;
 
   /* Brand accents — Tangle */
   --brand-primary: #6366F1;
@@ -195,12 +194,12 @@
   --brand-vibrant: #6366F1;
   --brand-emerald: #10B981;
 
-  /* Borders */
-  --border-subtle: rgba(100, 100, 148, 0.10);
-  --border-default: rgba(100, 100, 148, 0.18);
-  --border-hover: rgba(100, 100, 148, 0.28);
-  --border-accent: rgba(99, 102, 241, 0.18);
-  --border-accent-hover: rgba(99, 102, 241, 0.35);
+  /* Borders — neutral hairlines */
+  --border-subtle: rgba(255, 255, 255, 0.05);
+  --border-default: rgba(255, 255, 255, 0.07);
+  --border-hover: rgba(255, 255, 255, 0.12);
+  --border-accent: rgba(129, 140, 248, 0.20);
+  --border-accent-hover: rgba(129, 140, 248, 0.35);
 
   /* Buttons */
   --btn-primary-bg: #6366F1;
@@ -218,11 +217,11 @@
   --code-comment: #606294;
   --code-error: #FF4D6D;
 
-  /* Shadows */
-  --shadow-card: 0 1px 3px rgba(0, 0, 0, 0.4), 0 0 0 1px rgba(255, 255, 255, 0.04);
-  --shadow-dropdown: 0 8px 32px rgba(0, 0, 0, 0.6), 0 0 0 1px rgba(255, 255, 255, 0.06);
-  --shadow-glow: 0 0 32px rgba(99, 102, 241, 0.18);
-  --shadow-accent: 0 1px 3px rgba(0, 0, 0, 0.3), 0 0 0 1px rgba(99, 102, 241, 0.2);
+  /* Shadows — flat, no inner ring, no indigo glow */
+  --shadow-card: 0 1px 2px rgba(0, 0, 0, 0.3);
+  --shadow-dropdown: 0 8px 30px rgba(0, 0, 0, 0.45);
+  --shadow-glow: none;
+  --shadow-accent: 0 1px 2px rgba(0, 0, 0, 0.3);
   --shadow-status-running: 0 0 6px rgba(16, 185, 129, 0.5);
   --shadow-status-creating: 0 0 6px rgba(99, 102, 241, 0.5);
   --shadow-status-error: 0 0 6px rgba(255, 77, 109, 0.5);
@@ -230,11 +229,12 @@
   /* Radii */
   --radius-sm: 6px;
   --radius-md: 8px;
-  --radius-lg: 12px;
-  --radius-xl: 16px;
+  --radius-lg: 10px;
+  --radius-xl: 12px;          /* chrome stays tight (was 16px) */
   --radius-pill: 999px;
   --radius-full: 999px;
-  --radius: 0.625rem;
+  --radius-composer: 26px;    /* centered composer pill */
+  --radius: 0.5rem;           /* 8px chrome default (was 10px) */
 
   /* Density */
   --control-height: 2.25rem;
@@ -249,8 +249,8 @@
   --font-size-lg: 1rem;           /* 16px — emphasized text */
   --font-size-xl: 1.25rem;        /* 20px — section headers */
   --line-height-tight: 1.3;
-  --line-height-base: 1.75;       /* matches leading-7 */
-  --line-height-relaxed: 1.8;
+  --line-height-base: 1.6;        /* tighter body rhythm (was 1.75) */
+  --line-height-relaxed: 1.75;
 
   /* Component spacing — override per-app for tighter/looser layouts */
   --avatar-size: 2rem;            /* 32px — chat avatars */
@@ -284,9 +284,9 @@
   --transition-default: 0.16s ease;
   --transition-medium: 0.24s ease;
 
-  /* Fonts */
-  --font-sans: "Geist", "DM Sans", ui-sans-serif, system-ui, sans-serif;
-  --font-display: "Outfit", "Geist", sans-serif;
+  /* Fonts — unified on Inter (dark + light) */
+  --font-sans: "Inter", "Geist", ui-sans-serif, system-ui, -apple-system, sans-serif;
+  --font-display: "Inter", "Geist", sans-serif;
   --font-mono: "Geist Mono", "JetBrains Mono", ui-monospace, monospace;
 }
 
@@ -336,34 +336,34 @@
   --md3-inverse-on-surface: #f0f1f4;
   --md3-surface-tint: #6366F1;
 
-  /* Semantic HSL bridge */
-  --hsl-background: 225 20% 97%;
-  --hsl-foreground: 228 20% 12%;
-  --hsl-card: 0 0% 100%;
-  --hsl-card-foreground: 228 20% 12%;
+  /* Semantic HSL bridge — flat neutral light (Tangle Quiet) */
+  --hsl-background: 0 0% 100%;      /* #ffffff */
+  --hsl-foreground: 0 0% 5%;        /* #0d0d0d */
+  --hsl-card: 240 7% 97%;           /* #f7f7f8 surface */
+  --hsl-card-foreground: 0 0% 5%;
   --hsl-popover: 0 0% 100%;
-  --hsl-popover-foreground: 228 20% 12%;
-  --hsl-primary: 239 84% 67%;
+  --hsl-popover-foreground: 0 0% 5%;
+  --hsl-primary: 245 62% 57%;       /* #5B4ED4 light accent */
   --hsl-primary-foreground: 0 0% 100%;
-  --hsl-secondary: 242 22% 42%;
-  --hsl-secondary-foreground: 0 0% 100%;
-  --hsl-muted: 240 14% 89%;
-  --hsl-muted-foreground: 240 10% 36%;
-  --hsl-accent: 248 22% 86%;
-  --hsl-accent-foreground: 248 38% 30%;
+  --hsl-secondary: 240 6% 93%;      /* #ececee surface-2 */
+  --hsl-secondary-foreground: 0 0% 10%;
+  --hsl-muted: 240 6% 93%;          /* #ececee neutral hover */
+  --hsl-muted-foreground: 240 5% 38%;  /* #5d5d66 text-muted */
+  --hsl-accent: 240 6% 93%;         /* neutral hover */
+  --hsl-accent-foreground: 0 0% 10%;
   --hsl-destructive: 0 72% 41%;
   --hsl-destructive-foreground: 0 0% 100%;
-  --hsl-border: 244 14% 78%;
-  --hsl-input: 244 12% 80%;
-  --hsl-ring: 239 84% 67%;
+  --hsl-border: 240 6% 89%;         /* hairline ≈ rgba(0,0,0,0.08) */
+  --hsl-input: 240 6% 89%;
+  --hsl-ring: 245 62% 57%;
   --hsl-success: 160 84% 30%;
   --hsl-warning: 41 96% 50%;
   --hsl-info: 212 80% 50%;
 
-  --depth-1: #f4f4f9;
-  --depth-2: #edecf4;
-  --depth-3: #e5e4ee;
-  --depth-4: #dcdbe8;
+  --depth-1: #ffffff;
+  --depth-2: #f7f7f8;
+  --depth-3: #ececee;
+  --depth-4: #e3e3e6;
 
   --status-running: #059669;
   --status-creating: #3E349E;
@@ -404,33 +404,34 @@
   --surface-neutral-border: var(--border-subtle);
   --surface-neutral-text: var(--text-muted);
 
-  /* Sidebar — light */
-  --sidebar-background: 232 18% 96%;
-  --sidebar-foreground: 228 20% 12%;
-  --sidebar-primary: 239 84% 67%;
+  /* Sidebar — light, flat surface + hairline */
+  --sidebar-background: 240 7% 97%;   /* #f7f7f8 surface */
+  --sidebar-foreground: 0 0% 5%;
+  --sidebar-primary: 245 62% 57%;     /* #5B4ED4 */
   --sidebar-primary-foreground: 0 0% 100%;
-  --sidebar-accent: 240 18% 90%;
-  --sidebar-accent-foreground: 240 38% 30%;
-  --sidebar-border: 244 14% 78%;
-  --sidebar-ring: 239 84% 67%;
-
-  --mesh-teal: rgba(5, 150, 105, 0.04);
-  --mesh-violet: rgba(99, 102, 241, 0.03);
-  --mesh-blue: rgba(129, 140, 248, 0.03);
-
-  --bg-root: #f4f4f9;
-  --bg-dark: #edecf4;
-  --bg-card: #ffffff;
-  --bg-elevated: #e5e4ee;
-  --bg-section: #edecf4;
-  --bg-input: #edecf4;
-  --bg-hover: rgba(99, 102, 241, 0.05);
-  --bg-selection: rgba(99, 102, 241, 0.10);
-
-  --text-primary: #191c24;
-  --text-secondary: #3a3a50;
-  --text-muted: #5E5E7A;
-  --text-dim: #A0A0B8;
+  --sidebar-accent: 240 6% 93%;       /* neutral hover */
+  --sidebar-accent-foreground: 0 0% 10%;
+  --sidebar-border: 240 6% 89%;       /* hairline */
+  --sidebar-ring: 245 62% 57%;
+
+  --mesh-teal: transparent;
+  --mesh-violet: transparent;
+  --mesh-blue: transparent;
+
+  /* Surfaces — flat single-neutral light */
+  --bg-root: #ffffff;
+  --bg-dark: #f7f7f8;
+  --bg-card: #f7f7f8;
+  --bg-elevated: #ffffff;
+  --bg-section: #f7f7f8;
+  --bg-input: #ececee;
+  --bg-hover: rgba(0, 0, 0, 0.04);
+  --bg-selection: rgba(91, 78, 212, 0.10);
+
+  --text-primary: #0d0d0d;
+  --text-secondary: #2a2a30;
+  --text-muted: #5d5d66;
+  --text-dim: #8e8e98;
 
   --brand-primary: #6366F1;
   --brand-strong: #2E2A5E;
@@ -443,16 +444,16 @@
   --brand-vibrant: #6366F1;
   --brand-emerald: #059669;
 
-  --border-subtle: rgba(110, 108, 148, 0.20);
-  --border-default: rgba(110, 108, 148, 0.35);
-  --border-hover: rgba(110, 108, 148, 0.50);
-  --border-accent: rgba(99, 102, 241, 0.15);
-  --border-accent-hover: rgba(99, 102, 241, 0.30);
+  --border-subtle: rgba(0, 0, 0, 0.06);
+  --border-default: rgba(0, 0, 0, 0.08);
+  --border-hover: rgba(0, 0, 0, 0.13);
+  --border-accent: rgba(91, 78, 212, 0.18);
+  --border-accent-hover: rgba(91, 78, 212, 0.35);
 
-  --btn-primary-bg: #6366F1;
+  --btn-primary-bg: #5B4ED4;
   --btn-primary-hover: #4F46E5;
   --btn-primary-text: #ffffff;
-  --btn-cta-bg: #6366F1;
+  --btn-cta-bg: #5B4ED4;
   --btn-cta-text: #ffffff;
 
   --code-keyword: #3E349E;
@@ -463,30 +464,33 @@
   --code-comment: #6B6E8A;
   --code-error: #ba1a1a;
 
-  --shadow-card: 0 1px 3px rgba(25, 28, 36, 0.05), 0 0 0 1px rgba(200, 198, 218, 0.22);
-  --shadow-dropdown: 0 8px 32px rgba(25, 28, 36, 0.10), 0 0 0 1px rgba(200, 198, 218, 0.28);
+  /* Shadows — flat, no inner ring, no glow */
+  --shadow-card: 0 1px 2px rgba(25, 28, 36, 0.06);
+  --shadow-dropdown: 0 8px 30px rgba(25, 28, 36, 0.10);
   --shadow-glow: none;
-  --shadow-accent: 0 1px 3px rgba(25, 28, 36, 0.05), 0 0 0 1px rgba(99, 102, 241, 0.15);
-
-  --tangle-gradient: linear-gradient(135deg, #6366F1, #818CF8);
-  --tangle-gradient-text: linear-gradient(135deg, #4F46E5, #6366F1);
-  --accent-gradient-strong: linear-gradient(135deg, #6366F1, #818CF8);
-  --accent-surface-soft: rgba(99, 102, 241, 0.06);
-  --accent-surface-strong: rgba(99, 102, 241, 0.12);
+  --shadow-accent: 0 1px 2px rgba(25, 28, 36, 0.06);
+
+  /* Indigo spark kept for logo + send; accent-fill is the active row well */
+  --tangle-gradient: linear-gradient(135deg, #4F46E5, #5B4ED4);
+  --tangle-gradient-text: linear-gradient(135deg, #4F46E5, #5B4ED4);
+  --accent-gradient-strong: linear-gradient(135deg, #4F46E5, #5B4ED4);
+  --accent-surface-soft: rgba(0, 0, 0, 0.04);
+  --accent-surface-strong: rgba(91, 78, 212, 0.10);
   --accent-text: #4F46E5;
 
-  /* Typography — Manrope (headlines) + Inter (body/labels) */
-  --font-sans: "Inter", "Geist", ui-sans-serif, system-ui, sans-serif;
-  --font-display: "Manrope", "Inter", sans-serif;
+  /* Typography — unified on Inter */
+  --font-sans: "Inter", "Geist", ui-sans-serif, system-ui, -apple-system, sans-serif;
+  --font-display: "Inter", "Geist", sans-serif;
   --font-mono: "Geist Mono", "JetBrains Mono", ui-monospace, monospace;
 
-  /* Tighter border radius for enterprise precision */
-  --radius: 0.375rem;
-  --radius-sm: 2px;
-  --radius-md: 4px;
-  --radius-lg: 6px;
-  --radius-xl: 8px;
+  /* Radius — unified chrome scale (matches dark; 8px md) */
+  --radius: 0.5rem;
+  --radius-sm: 6px;
+  --radius-md: 8px;
+  --radius-lg: 10px;
+  --radius-xl: 12px;
   --radius-pill: 999px;
   --radius-full: 999px;
+  --radius-composer: 26px;
 }
 

package/dist/workspace.d.ts

@@ -1,5 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ReactNode } from 'react';
+import { ReactNode, Ref } from 'react';
 export { ArtifactPane, ArtifactPaneProps } from '@tangle-network/ui/primitives';
 import { FileNode, FileTreeVisibilityOptions, FileTabData } from '@tangle-network/ui/files';
 import { SessionProjectKey, ActiveSessionStatus, ActiveSessionRecord } from '@tangle-network/ui/stores';
@@ -160,6 +160,67 @@ interface RuntimePaneProps {
  */
 declare function RuntimePane({ title, subtitle, statusBanner, statusBar, content, terminal, audit, inspector, footer, className, }: RuntimePaneProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * Optimistic session/thread list: reflect a just-created / renamed / deleted
+ * item in the sidebar INSTANTLY, before the server loader round-trips.
+ *
+ * The shell loader is the source of truth and reconciles in the background
+ * (typically the app calls `useRevalidator().revalidate()` after its mutation
+ * fetch settles). Until that lands, a local mirror of the loader items carries
+ * the optimistic edit so a delete / rename / new-thread does not feel broken
+ * for the duration of a D1 round-trip.
+ *
+ * Two ways to drive it, usable together:
+ *   1. A window `CustomEvent` (default name {@link SESSION_CREATED_EVENT}) — the
+ *      surface that creates a thread (often a different route from the sidebar's
+ *      route) dispatches it; the sidebar prepends the item with no prop wiring.
+ *   2. The imperative {@link SessionOptimisticController} returned here — the
+ *      sidebar's own action handlers (rename / delete / pin) call it directly.
+ */
+/** Default window-event name for "a session/thread was just created". */
+declare const SESSION_CREATED_EVENT = "sandbox-thread-created";
+/**
+ * Payload of a {@link SESSION_CREATED_EVENT}. Only `id` + `title` are required;
+ * everything else mirrors {@link SessionSidebarItem}. `updatedAt` defaults to
+ * now so the new item sorts to the top.
+ */
+interface SessionCreatedDetail extends Partial<Omit<SessionSidebarItem, "id" | "title">> {
+    id: string;
+    title: string;
+}
+/** Dispatch the shared "session created" event so any mounted sidebar updates. */
+declare function dispatchSessionCreated(detail: SessionCreatedDetail, eventName?: string): void;
+/** Imperative handle for driving optimistic edits from a mutation handler. */
+interface SessionOptimisticController {
+    /** Prepend (or move to top) an item — call before the create fetch settles. */
+    add: (item: SessionCreatedDetail) => void;
+    /** Patch an existing item in place — e.g. a rename or category change. */
+    update: (id: string, patch: Partial<SessionSidebarItem>) => void;
+    /** Drop an item — call before the delete fetch settles. */
+    remove: (id: string) => void;
+    /** Discard all optimistic edits and snap back to the loader items. */
+    reset: () => void;
+}
+interface UseOptimisticSessionItemsOptions {
+    /**
+     * Listen for the shared window create-event and prepend its item. Set `false`
+     * to drive optimistic state purely through the imperative controller.
+     * Defaults to `true`.
+     */
+    listenForCreate?: boolean;
+    /** Override the window event name to listen for. */
+    eventName?: string;
+}
+/**
+ * Mirror `items` with optimistic add/update/remove on top. The mirror re-syncs
+ * whenever `items` changes (the loader is authoritative), so an optimistic edit
+ * is naturally superseded once the server result arrives.
+ */
+declare function useOptimisticSessionItems(items: SessionSidebarItem[], options?: UseOptimisticSessionItemsOptions): {
+    items: SessionSidebarItem[];
+    controller: SessionOptimisticController;
+};
+
 interface SessionSidebarItem {
     id: string;
     title: string;
@@ -218,8 +279,97 @@ interface SessionSidebarProps {
         session: ActiveSessionRecord | null;
         isActive: boolean;
     }) => ReactNode;
+    /**
+     * Opt into optimistic item updates: the sidebar keeps a local mirror of
+     * `items` so a just-created / renamed / deleted thread shows instantly,
+     * before the loader round-trips. Pass `true` for defaults, or an options
+     * object to tune the window create-event. Off by default — existing callers
+     * render `items` verbatim and are unaffected.
+     */
+    optimistic?: boolean | UseOptimisticSessionItemsOptions;
+    /**
+     * Ref to the imperative optimistic controller (`add` / `update` / `remove` /
+     * `reset`). Drive optimistic edits from the consumer's own rename/delete/pin
+     * handlers. Only populated when `optimistic` is enabled.
+     */
+    optimisticRef?: Ref<SessionOptimisticController | null>;
 }
-declare function SessionSidebar({ title, subtitle, projectId, items, currentItemId, createLabel, onCreate, onSelectItem, onSelectLink, links, className, emptyMessage, searchPlaceholder, enableSearch, activityMonitor, filters, defaultFilterId, resizable, defaultWidth, minWidth, maxWidth, onWidthChange, renderItemActions, }: SessionSidebarProps): react_jsx_runtime.JSX.Element;
+declare function SessionSidebar({ title, subtitle, projectId, items, currentItemId, createLabel, onCreate, onSelectItem, onSelectLink, links, className, emptyMessage, searchPlaceholder, enableSearch, activityMonitor, filters, defaultFilterId, resizable, defaultWidth, minWidth, maxWidth, onWidthChange, renderItemActions, optimistic, optimisticRef, }: SessionSidebarProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Snappy in-app navigation: a shared `shouldRevalidate` rule for the agent-app
+ * shell route(s) that own the workspace-list / sidebar loader.
+ *
+ * The shell loader (user + workspace list, sidebar state) runs on every
+ * navigation, but its data does not change just by moving between in-app pages.
+ * Refetching it on every internal GET nav adds a loader round-trip to each
+ * click — on Cloudflare Workers + D1 (HTTP-proxied) that is a visible stall.
+ *
+ * This helper encodes the rule that makes nav feel instant WITHOUT stranding
+ * freshly-mutated data:
+ *
+ *   - Non-GET navigation (form submit / action) → always revalidate.
+ *   - Internal app→app navigation that CHANGES the path → skip revalidation.
+ *   - Imperative `useRevalidator().revalidate()` (which targets the SAME url,
+ *     so `currentUrl.pathname === nextUrl.pathname`) → revalidate. Creating a
+ *     project / thread typically goes through a raw `fetch`, so a same-url
+ *     revalidate is the ONLY way the new row reaches the shell loader; the
+ *     same-path carve-out below is what keeps that working. Suppressing it is
+ *     the project-switcher regression — do not "simplify" it away.
+ *   - Anything else (cross-path-prefix nav, entering/leaving the app) →
+ *     defer to `defaultShouldRevalidate`.
+ *
+ * Framework-agnostic by design: sandbox-ui does not depend on react-router, so
+ * this takes a plain args object. The shape is a structural subset of
+ * react-router's `ShouldRevalidateFunctionArgs`, so an app can wire it as a
+ * route export with no adapter:
+ *
+ * ```ts
+ * // app/routes/app.tsx
+ * import { shellShouldRevalidate } from "@tangle-network/sandbox-ui/workspace";
+ * export const shouldRevalidate = shellShouldRevalidate;
+ * ```
+ *
+ * `shouldRevalidate` MUST be a per-app react-router route export — it cannot be
+ * exported FROM a library on the app's behalf — so the "out of the box" win is
+ * the one-line re-export above instead of every app re-deriving the rule (and
+ * re-introducing the same-url bug).
+ */
+/**
+ * The subset of react-router's `ShouldRevalidateFunctionArgs` this rule reads.
+ * Kept structural so callers can pass the full react-router args object as-is.
+ */
+interface ShellShouldRevalidateArgs {
+    currentUrl: URL;
+    nextUrl: URL;
+    formMethod?: string;
+    defaultShouldRevalidate: boolean;
+}
+interface ShellShouldRevalidateOptions {
+    /**
+     * Path prefix that marks "inside the app shell". Internal navigation between
+     * two paths under this prefix skips the shell-loader refetch. Defaults to
+     * `"/app"`.
+     */
+    appPathPrefix?: string;
+}
+/**
+ * Build a `shouldRevalidate` function for the shell route under `appPathPrefix`.
+ * Use this when the app mounts under a non-default prefix; otherwise prefer the
+ * ready-made {@link shellShouldRevalidate} export.
+ */
+declare function createShellShouldRevalidate(options?: ShellShouldRevalidateOptions): (args: ShellShouldRevalidateArgs) => boolean;
+/**
+ * Ready-made shell `shouldRevalidate` for apps mounted under `/app`. Wire it as
+ * a one-line route export:
+ *
+ * ```ts
+ * export const shouldRevalidate = shellShouldRevalidate;
+ * ```
+ *
+ * For a non-`/app` prefix, use {@link createShellShouldRevalidate}.
+ */
+declare const shellShouldRevalidate: (args: ShellShouldRevalidateArgs) => boolean;
 
 interface SessionActivityMonitorProps {
     className?: string;
@@ -478,4 +628,4 @@ interface ApprovalQueueProps {
  */
 declare function ApprovalQueue({ items, className, onApprove, onReject, renderItemDetail, renderTypeBadge, renderStats, canResolve, header, emptyState, showResolved: controlledShowResolved, }: ApprovalQueueProps): react_jsx_runtime.JSX.Element;
 
-export { AgentWorkbench, type ApprovalConfidenceStat, type ApprovalItem, ApprovalQueue, type ApprovalQueueProps, type AuditCheck, AuditResults, type AuditResultsProps, type BannerType, type CalendarEvent, CalendarView, type CalendarViewProps, type ContextBadge, DirectoryPane, type DirectoryPaneProps, type FormAudit, RuntimePane, type RuntimePaneProps, SandboxWorkbench, type SandboxWorkbenchArtifact, type SandboxWorkbenchCustomArtifact, type SandboxWorkbenchFileArtifact, type SandboxWorkbenchLayoutOptions, type SandboxWorkbenchMarkdownArtifact, type SandboxWorkbenchOpenUIArtifact, type SandboxWorkbenchProps, type SandboxWorkbenchSessionProps, SessionActivityMonitor, type SessionActivityMonitorProps, SessionSidebar, type SessionSidebarBadge, type SessionSidebarFilter, type SessionSidebarItem, type SessionSidebarLink, type SessionSidebarProps, StatusBanner, type StatusBannerProps, StatusBar, type StatusBarProps, TaskBoard, type TaskBoardColumn, type TaskBoardItem, type TaskBoardProps, type TerminalLine, TerminalPanel, type TerminalProps, WorkspaceLayout, type WorkspaceLayoutProps };
+export { AgentWorkbench, type ApprovalConfidenceStat, type ApprovalItem, ApprovalQueue, type ApprovalQueueProps, type AuditCheck, AuditResults, type AuditResultsProps, type BannerType, type CalendarEvent, CalendarView, type CalendarViewProps, type ContextBadge, DirectoryPane, type DirectoryPaneProps, type FormAudit, RuntimePane, type RuntimePaneProps, SESSION_CREATED_EVENT, SandboxWorkbench, type SandboxWorkbenchArtifact, type SandboxWorkbenchCustomArtifact, type SandboxWorkbenchFileArtifact, type SandboxWorkbenchLayoutOptions, type SandboxWorkbenchMarkdownArtifact, type SandboxWorkbenchOpenUIArtifact, type SandboxWorkbenchProps, type SandboxWorkbenchSessionProps, SessionActivityMonitor, type SessionActivityMonitorProps, type SessionCreatedDetail, type SessionOptimisticController, SessionSidebar, type SessionSidebarBadge, type SessionSidebarFilter, type SessionSidebarItem, type SessionSidebarLink, type SessionSidebarProps, type ShellShouldRevalidateArgs, type ShellShouldRevalidateOptions, StatusBanner, type StatusBannerProps, StatusBar, type StatusBarProps, TaskBoard, type TaskBoardColumn, type TaskBoardItem, type TaskBoardProps, type TerminalLine, TerminalPanel, type TerminalProps, type UseOptimisticSessionItemsOptions, WorkspaceLayout, type WorkspaceLayoutProps, createShellShouldRevalidate, dispatchSessionCreated, shellShouldRevalidate, useOptimisticSessionItems };

package/dist/workspace.js

@@ -6,6 +6,7 @@ import {
   CalendarView,
   DirectoryPane,
   RuntimePane,
+  SESSION_CREATED_EVENT,
   SandboxWorkbench,
   SessionActivityMonitor,
   SessionSidebar,
@@ -13,8 +14,12 @@ import {
   StatusBar,
   TaskBoard,
   TerminalPanel,
-  WorkspaceLayout
-} from "./chunk-I3IVCGND.js";
+  WorkspaceLayout,
+  createShellShouldRevalidate,
+  dispatchSessionCreated,
+  shellShouldRevalidate,
+  useOptimisticSessionItems
+} from "./chunk-AUFV7766.js";
 import "./chunk-EI44GEQ5.js";
 export {
   AgentWorkbench,
@@ -24,6 +29,7 @@ export {
   CalendarView,
   DirectoryPane,
   RuntimePane,
+  SESSION_CREATED_EVENT,
   SandboxWorkbench,
   SessionActivityMonitor,
   SessionSidebar,
@@ -31,5 +37,9 @@ export {
   StatusBar,
   TaskBoard,
   TerminalPanel,
-  WorkspaceLayout
+  WorkspaceLayout,
+  createShellShouldRevalidate,
+  dispatchSessionCreated,
+  shellShouldRevalidate,
+  useOptimisticSessionItems
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/sandbox-ui",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "description": "Unified UI component library for Tangle Sandbox — primitives, chat, dashboard, terminal, editor, and workspace components",
   "repository": {
     "type": "git",
@@ -114,7 +114,7 @@
     "test:bridge": "pnpm build && vitest run src/__tests__/re-export-identity.test.ts"
   },
   "peerDependencies": {
-    "@tangle-network/brand": "^0.3.0",
+    "@tangle-network/brand": "^0.4.0",
     "@tangle-network/ui": "^1.0.1",
     "react": "^18 || ^19",
     "react-dom": "^18 || ^19"
@@ -161,7 +161,7 @@
     "@storybook/react-vite": "^8.6.18",
     "@tailwindcss/postcss": "^4.2.2",
     "@tailwindcss/vite": "^4.2.2",
-    "@tangle-network/brand": "^0.3.0",
+    "@tangle-network/brand": "^0.4.0",
     "@tangle-network/ui": "^1.0.1",
     "@tanstack/react-query": "^5.91.0",
     "@testing-library/dom": "^10.4.1",