@tangle-network/sandbox-ui 0.28.0 → 0.29.0

package/dist/{chunk-I3IVCGND.js → chunk-AUFV7766.js}

@@ -813,10 +813,69 @@ function RuntimePane({
 }
 
 // src/workspace/session-sidebar.tsx
-import { useCallback, useMemo as useMemo3, useRef as useRef3, useState as useState3 } from "react";
+import { useCallback as useCallback2, useImperativeHandle, useMemo as useMemo3, useRef as useRef4, useState as useState4 } from "react";
 import { ArrowLeft, FolderTree, MessageSquareText, Plus, Search as Search2, Settings, Sparkles } from "lucide-react";
 import { useNavbarSessions } from "@tangle-network/ui/stores";
+
+// src/workspace/session-optimistic.ts
+import { useCallback, useEffect as useEffect3, useRef as useRef3, useState as useState3 } from "react";
+var SESSION_CREATED_EVENT = "sandbox-thread-created";
+function dispatchSessionCreated(detail, eventName = SESSION_CREATED_EVENT) {
+  if (typeof window === "undefined") return;
+  window.dispatchEvent(new CustomEvent(eventName, { detail }));
+}
+function toItem(detail) {
+  return { updatedAt: /* @__PURE__ */ new Date(), ...detail };
+}
+function useOptimisticSessionItems(items, options = {}) {
+  const { listenForCreate = true, eventName = SESSION_CREATED_EVENT } = options;
+  const [optimisticItems, setOptimisticItems] = useState3(items);
+  useEffect3(() => {
+    setOptimisticItems(items);
+  }, [items]);
+  const add = useCallback((detail) => {
+    const next = toItem(detail);
+    setOptimisticItems((prev) => [next, ...prev.filter((item) => item.id !== next.id)]);
+  }, []);
+  const update = useCallback((id, patch) => {
+    setOptimisticItems(
+      (prev) => prev.map((item) => item.id === id ? { ...item, ...patch } : item)
+    );
+  }, []);
+  const remove = useCallback((id) => {
+    setOptimisticItems((prev) => prev.filter((item) => item.id !== id));
+  }, []);
+  const reset = useCallback(() => setOptimisticItems(items), [items]);
+  const addRef = useRef3(add);
+  addRef.current = add;
+  useEffect3(() => {
+    if (!listenForCreate || typeof window === "undefined") return;
+    function onCreated(event) {
+      const detail = event.detail;
+      if (!detail?.id || !detail.title) return;
+      addRef.current(detail);
+    }
+    window.addEventListener(eventName, onCreated);
+    return () => window.removeEventListener(eventName, onCreated);
+  }, [listenForCreate, eventName]);
+  return {
+    items: optimisticItems,
+    controller: { add, update, remove, reset }
+  };
+}
+
+// src/workspace/session-sidebar.tsx
 import { jsx as jsx7, jsxs as jsxs7 } from "react/jsx-runtime";
+var NO_CONTROLLER = {
+  add: () => {
+  },
+  update: () => {
+  },
+  remove: () => {
+  },
+  reset: () => {
+  }
+};
 function statusDot(status) {
   switch (status) {
     case "running":
@@ -888,24 +947,24 @@ function navigateToHref(href) {
   window.location.assign(href);
 }
 function useResizable(defaultWidth, min, max, onChange) {
-  const [width, setWidth] = useState3(defaultWidth);
-  const dragging = useRef3(false);
-  const startX = useRef3(0);
-  const startW = useRef3(0);
-  const onPointerDown = useCallback((e) => {
+  const [width, setWidth] = useState4(defaultWidth);
+  const dragging = useRef4(false);
+  const startX = useRef4(0);
+  const startW = useRef4(0);
+  const onPointerDown = useCallback2((e) => {
     dragging.current = true;
     startX.current = e.clientX;
     startW.current = width;
     e.currentTarget.setPointerCapture(e.pointerId);
   }, [width]);
-  const onPointerMove = useCallback((e) => {
+  const onPointerMove = useCallback2((e) => {
     if (!dragging.current) return;
     const delta = e.clientX - startX.current;
     const next = Math.min(max, Math.max(min, startW.current + delta));
     setWidth(next);
     onChange?.(next);
   }, [min, max, onChange]);
-  const onPointerUp = useCallback(() => {
+  const onPointerUp = useCallback2(() => {
     dragging.current = false;
   }, []);
   return { width, onPointerDown, onPointerMove, onPointerUp };
@@ -933,18 +992,32 @@ function SessionSidebar({
   minWidth = 200,
   maxWidth = 400,
   onWidthChange,
-  renderItemActions
+  renderItemActions,
+  optimistic = false,
+  optimisticRef
 }) {
-  const [query, setQuery] = useState3("");
-  const [activeFilterId, setActiveFilterId] = useState3(defaultFilterId ?? filters[0]?.id ?? "all");
+  const [query, setQuery] = useState4("");
+  const [activeFilterId, setActiveFilterId] = useState4(defaultFilterId ?? filters[0]?.id ?? "all");
+  const optimisticOptions = typeof optimistic === "object" ? optimistic : void 0;
+  const optimisticState = useOptimisticSessionItems(
+    items,
+    optimistic === false ? { listenForCreate: false } : optimisticOptions
+  );
+  const optimisticEnabled = optimistic !== false;
+  const effectiveItems = optimisticEnabled ? optimisticState.items : items;
+  useImperativeHandle(
+    optimisticRef,
+    () => optimisticEnabled ? optimisticState.controller : NO_CONTROLLER,
+    [optimisticEnabled, optimisticState.controller]
+  );
   const activeSessions = useNavbarSessions(projectId);
   const sessionsById = useMemo3(
     () => new Map(activeSessions.map((session) => [session.sessionId, session])),
     [activeSessions]
   );
   const orderedItems = useMemo3(
-    () => sortItems(items, sessionsById),
-    [items, sessionsById]
+    () => sortItems(effectiveItems, sessionsById),
+    [effectiveItems, sessionsById]
   );
   const visibleItems = useMemo3(() => {
     const normalizedQuery = query.trim().toLowerCase();
@@ -998,7 +1071,7 @@ function SessionSidebar({
           ] })
         ] }) }),
         (enableSearch && items.length > 0 || filters.length > 0) && /* @__PURE__ */ jsxs7("div", { className: "shrink-0 border-b border-border px-3 py-2.5", children: [
-          enableSearch && items.length > 0 && /* @__PURE__ */ jsxs7("div", { className: "relative", children: [
+          enableSearch && effectiveItems.length > 0 && /* @__PURE__ */ jsxs7("div", { className: "relative", children: [
             /* @__PURE__ */ jsx7(Search2, { className: "pointer-events-none absolute left-2 top-1/2 h-3.5 w-3.5 -translate-y-1/2 text-muted-foreground" }),
             /* @__PURE__ */ jsx7(
               "input",
@@ -1136,6 +1209,20 @@ function SessionSidebar({
   );
 }
 
+// src/workspace/shell-revalidation.ts
+function createShellShouldRevalidate(options = {}) {
+  const appPathPrefix = options.appPathPrefix ?? "/app";
+  return function shouldRevalidate(args) {
+    const { currentUrl, nextUrl, formMethod, defaultShouldRevalidate } = args;
+    if (formMethod && formMethod !== "GET") return true;
+    if (currentUrl.pathname !== nextUrl.pathname && currentUrl.pathname.startsWith(appPathPrefix) && nextUrl.pathname.startsWith(appPathPrefix)) {
+      return false;
+    }
+    return defaultShouldRevalidate;
+  };
+}
+var shellShouldRevalidate = createShellShouldRevalidate();
+
 // src/workspace/session-activity-monitor.tsx
 import { Activity, AlertCircle as AlertCircle2, LoaderCircle, MessageSquareText as MessageSquareText2 } from "lucide-react";
 import {
@@ -1238,7 +1325,7 @@ function SessionActivityMonitor({
 }
 
 // src/workspace/sandbox-workbench.tsx
-import { useEffect as useEffect3, useMemo as useMemo4, useState as useState4 } from "react";
+import { useEffect as useEffect4, useMemo as useMemo4, useState as useState5 } from "react";
 import {
   Bot,
   Boxes,
@@ -1438,10 +1525,10 @@ function SandboxWorkbench({
   emptyArtifactState,
   className
 }) {
-  const [uncontrolledArtifactId, setUncontrolledArtifactId] = useState4(
+  const [uncontrolledArtifactId, setUncontrolledArtifactId] = useState5(
     activeArtifactId ?? artifacts[0]?.id
   );
-  useEffect3(() => {
+  useEffect4(() => {
     if (activeArtifactId !== void 0) return;
     setUncontrolledArtifactId((current) => {
       if (artifacts.length === 0) return void 0;
@@ -1593,7 +1680,7 @@ function AgentWorkbench(props) {
 }
 
 // src/workspace/audit-results.tsx
-import { useState as useState5 } from "react";
+import { useState as useState6 } from "react";
 import { CheckCircle as CheckCircle2, XCircle, ChevronRight, Shield } from "lucide-react";
 import { jsx as jsx10, jsxs as jsxs10 } from "react/jsx-runtime";
 function AuditResults({ forms, crossFormChecks = [], overallScore, className }) {
@@ -1624,7 +1711,7 @@ function AuditResults({ forms, crossFormChecks = [], overallScore, className })
   ] });
 }
 function FormAuditCard({ form }) {
-  const [expanded, setExpanded] = useState5(form.failed > 0);
+  const [expanded, setExpanded] = useState6(form.failed > 0);
   const allPassed = form.failed === 0 && form.found;
   return /* @__PURE__ */ jsxs10("div", { className: "rounded-[var(--radius-md)] border border-border overflow-hidden", children: [
     /* @__PURE__ */ jsxs10(
@@ -1762,7 +1849,7 @@ function TaskBoard({
 }
 
 // src/workspace/calendar-view.tsx
-import { useState as useState6, useMemo as useMemo6 } from "react";
+import { useState as useState7, useMemo as useMemo6 } from "react";
 import { Fragment as Fragment3, jsx as jsx12, jsxs as jsxs12 } from "react/jsx-runtime";
 function toDateKey(d) {
   return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
@@ -1806,11 +1893,11 @@ function CalendarView({
 }) {
   const today = /* @__PURE__ */ new Date();
   const todayKey = toDateKey(today);
-  const [internalMonth, setInternalMonth] = useState6({
+  const [internalMonth, setInternalMonth] = useState7({
     year: today.getFullYear(),
     month: today.getMonth()
   });
-  const [internalSelectedDay, setInternalSelectedDay] = useState6(
+  const [internalSelectedDay, setInternalSelectedDay] = useState7(
     todayKey
   );
   const viewYear = controlledYear ?? internalMonth.year;
@@ -1983,7 +2070,7 @@ function CalendarView({
 }
 
 // src/workspace/approval-queue.tsx
-import { useState as useState7, useMemo as useMemo7 } from "react";
+import { useState as useState8, useMemo as useMemo7 } from "react";
 import { jsx as jsx13, jsxs as jsxs13 } from "react/jsx-runtime";
 function ApprovalQueue({
   items,
@@ -1998,9 +2085,9 @@ function ApprovalQueue({
   emptyState,
   showResolved: controlledShowResolved
 }) {
-  const [rejectingId, setRejectingId] = useState7(null);
-  const [rejectReason, setRejectReason] = useState7("");
-  const [showResolved, setShowResolved] = useState7(controlledShowResolved ?? false);
+  const [rejectingId, setRejectingId] = useState8(null);
+  const [rejectReason, setRejectReason] = useState8("");
+  const [showResolved, setShowResolved] = useState8(controlledShowResolved ?? false);
   const pending = useMemo7(
     () => items.filter((a) => a.status === "pending"),
     [items]
@@ -2209,7 +2296,12 @@ export {
   StatusBar,
   TerminalPanel,
   RuntimePane,
+  SESSION_CREATED_EVENT,
+  dispatchSessionCreated,
+  useOptimisticSessionItems,
   SessionSidebar,
+  createShellShouldRevalidate,
+  shellShouldRevalidate,
   SessionActivityMonitor,
   SandboxWorkbench,
   AgentWorkbench,

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { ArtifactPane, ArtifactPaneProps, Avatar, AvatarFallback, AvatarImage, Badge, BadgeProps, Button, ButtonProps, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, CodeBlock, CodeBlockProps, CopyButton, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DropZone, DropZoneProps, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, EmptyState, EmptyStateProps, InlineCode, InlineCodeProps, Input, InputProps, Label, Progress, SegmentedControl, SegmentedControlOption, SegmentedControlProps, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, SidebarDropZone, SidebarDropZoneProps, Skeleton, SkeletonCard, SkeletonTable, StatCard, StatCardProps, Switch, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, TabsTrigger, TerminalDisplay, TerminalCursor as TerminalDisplayCursor, TerminalInput as TerminalDisplayInput, TerminalLine as TerminalDisplayLine, Textarea, TextareaProps, ThemeToggle, Toast, ToastContainer, ToastProvider, UploadFile, UploadProgress, UploadProgressProps, badgeVariants, buttonVariants, useTheme, useToast } from '@tangle-network/ui/primitives';
 export { Logo, LogoProps, TangleKnot } from './primitives.js';
 export { CodeBlock as CodeBlockDisplay, Markdown, MarkdownProps } from '@tangle-network/ui/markdown';
-export { AgentWorkbench, ApprovalConfidenceStat, ApprovalItem, ApprovalQueue, ApprovalQueueProps, AuditCheck, AuditResults, AuditResultsProps, BannerType, CalendarEvent, CalendarView, CalendarViewProps, ContextBadge, DirectoryPane, DirectoryPaneProps, FormAudit, RuntimePane, RuntimePaneProps, SandboxWorkbench, SandboxWorkbenchArtifact, SandboxWorkbenchCustomArtifact, SandboxWorkbenchFileArtifact, SandboxWorkbenchLayoutOptions, SandboxWorkbenchMarkdownArtifact, SandboxWorkbenchOpenUIArtifact, SandboxWorkbenchProps, SandboxWorkbenchSessionProps, SessionActivityMonitor, SessionActivityMonitorProps, SessionSidebar, SessionSidebarBadge, SessionSidebarFilter, SessionSidebarItem, SessionSidebarLink, SessionSidebarProps, StatusBanner, StatusBannerProps, StatusBar, StatusBarProps, TaskBoard, TaskBoardColumn, TaskBoardItem, TaskBoardProps, TerminalLine, TerminalPanel, TerminalProps, WorkspaceLayout, WorkspaceLayoutProps } from './workspace.js';
+export { AgentWorkbench, ApprovalConfidenceStat, ApprovalItem, ApprovalQueue, ApprovalQueueProps, AuditCheck, AuditResults, AuditResultsProps, BannerType, CalendarEvent, CalendarView, CalendarViewProps, ContextBadge, DirectoryPane, DirectoryPaneProps, FormAudit, RuntimePane, RuntimePaneProps, SESSION_CREATED_EVENT, SandboxWorkbench, SandboxWorkbenchArtifact, SandboxWorkbenchCustomArtifact, SandboxWorkbenchFileArtifact, SandboxWorkbenchLayoutOptions, SandboxWorkbenchMarkdownArtifact, SandboxWorkbenchOpenUIArtifact, SandboxWorkbenchProps, SandboxWorkbenchSessionProps, SessionActivityMonitor, SessionActivityMonitorProps, SessionCreatedDetail, SessionOptimisticController, SessionSidebar, SessionSidebarBadge, SessionSidebarFilter, SessionSidebarItem, SessionSidebarLink, SessionSidebarProps, ShellShouldRevalidateArgs, ShellShouldRevalidateOptions, StatusBanner, StatusBannerProps, StatusBar, StatusBarProps, TaskBoard, TaskBoardColumn, TaskBoardItem, TaskBoardProps, TerminalLine, TerminalPanel, TerminalProps, UseOptimisticSessionItemsOptions, WorkspaceLayout, WorkspaceLayoutProps, createShellShouldRevalidate, dispatchSessionCreated, shellShouldRevalidate, useOptimisticSessionItems } from './workspace.js';
 export { OpenUIAction, OpenUIActionsNode, OpenUIArtifactRenderer, OpenUIArtifactRendererProps, OpenUIBadgeNode, OpenUICardNode, OpenUICodeNode, OpenUIComponentNode, OpenUIGridNode, OpenUIHeadingNode, OpenUIKeyValueNode, OpenUIMarkdownNode, OpenUIPrimitive, OpenUISeparatorNode, OpenUIStackNode, OpenUIStatNode, OpenUITableNode, OpenUITextNode } from '@tangle-network/ui/openui';
 export { AgentTimeline, AgentTimelineArtifactItem, AgentTimelineCustomItem, AgentTimelineItem, AgentTimelineMessageItem, AgentTimelineProps, AgentTimelineStatusItem, AgentTimelineTone, AgentTimelineToolGroupItem, AgentTimelineToolItem, ChatContainer, ChatContainerProps, ChatInput, ChatInputProps, ChatMessage, ChatMessageProps, MessageList, MessageListProps, MessageRole, PendingFile, ThinkingIndicator, ThinkingIndicatorProps, UserMessage, UserMessageProps } from '@tangle-network/ui/chat';
 export { AgentSessionControls, AgentSessionControlsProps, AgentSessionHarnessControl, AgentSessionModelControl, AgentSessionReasoningControl, ArtifactAgentDock, ArtifactAgentDockProps, ArtifactAgentDockTransport, ArtifactDockMessage, ArtifactDockStreamEvent, ArtifactKind, ArtifactScope, DEFAULT_REASONING_LEVEL_OPTIONS, HARNESS_MODEL_POLICIES, ReasoningLevel, ReasoningLevelOption, ReasoningLevelPicker, ReasoningLevelPickerProps, createFetchTransport, isModelCompatibleWithHarness, modelProvider, snapHarnessToModel, snapModelToHarness } from './chat.js';

package/dist/index.js

@@ -120,6 +120,7 @@ import {
   CalendarView,
   DirectoryPane,
   RuntimePane,
+  SESSION_CREATED_EVENT,
   SandboxWorkbench,
   SessionActivityMonitor,
   SessionSidebar,
@@ -127,8 +128,12 @@ import {
   StatusBar,
   TaskBoard,
   TerminalPanel,
-  WorkspaceLayout
-} from "./chunk-I3IVCGND.js";
+  WorkspaceLayout,
+  createShellShouldRevalidate,
+  dispatchSessionCreated,
+  shellShouldRevalidate,
+  useOptimisticSessionItems
+} from "./chunk-AUFV7766.js";
 import {
   OpenUIArtifactRenderer
 } from "./chunk-AZ3AWMTM.js";
@@ -442,6 +447,7 @@ export {
   RichFileTree,
   RunGroup,
   RuntimePane,
+  SESSION_CREATED_EVENT,
   SIDEBAR_MOBILE_WIDTH,
   SIDEBAR_PANEL_WIDTH,
   SIDEBAR_RAIL_WIDTH,
@@ -534,8 +540,10 @@ export {
   copyText,
   createAuthFetcher,
   createFetchTransport,
+  createShellShouldRevalidate,
   dedupeModels,
   disconnectSession,
+  dispatchSessionCreated,
   filterFileTree,
   formatBytes,
   formatContext,
@@ -569,6 +577,7 @@ export {
   setActiveSessionError,
   setActiveSessionRunning,
   setForegroundActiveSession,
+  shellShouldRevalidate,
   snapHarnessToModel,
   snapModelToHarness,
   timeAgo,
@@ -588,6 +597,7 @@ export {
   useHasBackgroundRunningSessions,
   useLiveTime,
   useNavbarSessions,
+  useOptimisticSessionItems,
   useProjectActivity,
   useProjectSessions,
   usePtySession,

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.29.0",
   "description": "Unified UI component library for Tangle Sandbox — primitives, chat, dashboard, terminal, editor, and workspace components",
   "repository": {
     "type": "git",