@stigmer/react 0.2.1 → 0.2.3

package/src/workspace/WorkspaceEditor.tsx

@@ -18,58 +18,60 @@ export interface WorkspaceEditorProps {
   readonly disabled?: boolean;
   /** GitHub connection state. When provided, enables the GitHub repo picker. */
   readonly gitHubConnection?: UseGitHubConnectionReturn;
-  /** Show the GitHub Repo tab. Default: true. */
+  /** Enable the "Connect GitHub" action. Default: true. */
   readonly enableGitHub?: boolean;
   /**
-   * Show the Local Folder tab. Default: false.
+   * Enable the "Browse Folder" action.
    *
-   * The tab is only rendered when `runnerId` is also provided, since the
-   * file browser requires a connected runner to query.
+   * The action is only functional when `runnerId` is also provided,
+   * since the file browser requires a connected runner to query.
+   * When `runnerId` is null (Auto selected), the action is disabled.
    */
   readonly enableLocal?: boolean;
   /**
    * ID of the runner to use for filesystem browsing.
    *
-   * When provided together with `enableLocal`, the Local Folder tab
-   * renders a {@link RunnerFileBrowser} that queries the runner's
-   * filesystem via the `ListDirectory` command.
+   * When provided together with `enableLocal`, the "Browse Folder"
+   * action drills into a {@link RunnerFileBrowser} that queries the
+   * runner's filesystem via the `ListDirectory` command.
    */
   readonly runnerId?: string | null;
   /**
    * Native folder picker callback for desktop environments.
    *
-   * @deprecated Prefer passing `runnerId` to enable the integrated
-   * {@link RunnerFileBrowser} which provides a consistent experience
-   * across web and desktop.
+   * When provided alongside `runnerId`, renders an "Open system dialog"
+   * button in the Browse Folder drill-in view. Desktop-only enhancement.
    */
   readonly onBrowseLocalFolder?: () => Promise<string | null>;
   /**
    * Display name of the currently selected runner.
-   *
-   * When provided, a contextual hint is shown above the manual local
-   * path input (fallback when `runnerId` is not set) indicating that
-   * paths are relative to this runner's filesystem.
+   * Passed through to {@link RunnerFileBrowser} for the context header.
    */
   readonly runnerName?: string;
+  /**
+   * Hostname of the runner's machine (e.g. "Alice's MacBook Pro").
+   * Passed through to {@link RunnerFileBrowser} for the context header.
+   */
+  readonly runnerHostname?: string;
 }
 
-type ActiveTab = "local" | "github";
+type ActivePanel = "browse" | "github" | null;
 
 const TYPE_LABELS: Record<string, string> = {
   git: "GitHub",
-  local: "Local",
 };
 
 /**
- * Styled component that renders add/remove UI for workspace entries.
+ * Styled component for managing workspace entries with a flat-list
+ * layout and drill-in sub-views.
  *
- * Uses a tabbed layout when multiple workspace sources are available:
- * - **Local Folder** (default when a runner is connected): Shows an
- *   interactive file browser via {@link RunnerFileBrowser}.
- * - **GitHub Repo**: Shows the repo picker or connect prompt.
+ * The default view shows:
+ * 1. Current workspace entries (with remove buttons)
+ * 2. Action items: "Browse Folder" and "Connect GitHub"
  *
- * When only one source is available, the tab bar is hidden and the
- * content renders directly.
+ * Each action drills into a sub-view (file browser or GitHub picker)
+ * with a back button to return to the list. This follows the same
+ * progressive-disclosure pattern as the Configure menu.
  *
  * All visual properties flow through `--stgm-*` tokens.
  *
@@ -101,19 +103,15 @@ export function WorkspaceEditor({
   runnerId,
   onBrowseLocalFolder,
   runnerName,
+  runnerHostname,
 }: WorkspaceEditorProps) {
-  const hasLocal = enableLocal && !!runnerId;
-  const hasGitHub = enableGitHub;
-  const hasBothTabs = hasLocal && hasGitHub;
-
-  const [activeTab, setActiveTab] = useState<ActiveTab>(
-    hasLocal ? "local" : "github",
-  );
-
+  const [activePanel, setActivePanel] = useState<ActivePanel>(null);
   const [manualUrl, setManualUrl] = useState("");
   const [manualBranch, setManualBranch] = useState("");
   const entryList = useScrollShadows();
 
+  const canBrowse = enableLocal && !!runnerId;
+
   const handleGitHubSelect = useCallback(
     (repoUrl: string, branch: string) => {
       workspace.addGitRepo(repoUrl, branch);
@@ -139,11 +137,87 @@ export function WorkspaceEditor({
     [],
   );
 
-  const effectiveTab: ActiveTab = hasLocal && activeTab === "local"
-    ? "local"
-    : hasGitHub
-      ? "github"
-      : "local";
+  const goBack = useCallback(() => setActivePanel(null), []);
+
+  // ---------------------------------------------------------------------------
+  // Drill-in: Browse Folder
+  // ---------------------------------------------------------------------------
+
+  if (activePanel === "browse" && canBrowse) {
+    return (
+      <div className={["space-y-2", className].filter(Boolean).join(" ")}>
+        <button
+          type="button"
+          onClick={goBack}
+          className="inline-flex items-center gap-1 text-[0.65rem] text-muted-foreground hover:text-foreground transition-colors"
+        >
+          <ChevronLeftIcon />
+          Back
+        </button>
+        <div className="space-y-2">
+          <RunnerFileBrowser
+            runnerId={runnerId!}
+            onSelect={(path) => {
+              workspace.addLocalPath(path);
+              setActivePanel(null);
+            }}
+            onCancel={goBack}
+            runnerName={runnerName}
+            runnerHostname={runnerHostname}
+          />
+        </div>
+      </div>
+    );
+  }
+
+  // ---------------------------------------------------------------------------
+  // Drill-in: Connect GitHub
+  // ---------------------------------------------------------------------------
+
+  if (activePanel === "github" && enableGitHub) {
+    return (
+      <div className={["space-y-2", className].filter(Boolean).join(" ")}>
+        <button
+          type="button"
+          onClick={goBack}
+          className="inline-flex items-center gap-1 text-[0.65rem] text-muted-foreground hover:text-foreground transition-colors"
+        >
+          <ChevronLeftIcon />
+          Back
+        </button>
+        {gitHubConnection ? (
+          <GitHubPanel
+            connection={gitHubConnection}
+            onSelect={(url, branch) => {
+              handleGitHubSelect(url, branch);
+              setActivePanel(null);
+            }}
+            onClose={goBack}
+          />
+        ) : (
+          <ManualGitPanel
+            url={manualUrl}
+            branch={manualBranch}
+            onUrlChange={setManualUrl}
+            onBranchChange={setManualBranch}
+            onAdd={() => {
+              handleManualAdd();
+              setActivePanel(null);
+            }}
+            onCancel={goBack}
+            onKeyDown={handleKeyDown(() => {
+              handleManualAdd();
+              setActivePanel(null);
+            })}
+          />
+        )}
+      </div>
+    );
+  }
+
+  // ---------------------------------------------------------------------------
+  // Default view: flat list (entries + actions)
+  // ---------------------------------------------------------------------------
 
   return (
     <div className={["space-y-2", className].filter(Boolean).join(" ")}>
@@ -152,15 +226,21 @@ export function WorkspaceEditor({
         <div className="relative">
           {entryList.canScrollUp && <ScrollFade position="top" />}
 
-          <div ref={entryList.scrollRef} className="max-h-28 space-y-2 overflow-y-auto">
+          <div ref={entryList.scrollRef} className="max-h-28 space-y-1 overflow-y-auto">
             {workspace.entries.map((entry) => (
               <div
                 key={entry.id}
                 className="flex items-center gap-2 rounded-md border border-border bg-muted-faint px-2.5 py-1.5 text-xs"
               >
-                <span className="shrink-0 rounded bg-muted px-1.5 py-0.5 text-[0.65rem] text-muted-foreground">
-                  {TYPE_LABELS[entry.type] ?? entry.type}
-                </span>
+                {TYPE_LABELS[entry.type] ? (
+                  <span className="shrink-0 rounded bg-muted px-1.5 py-0.5 text-[0.65rem] text-muted-foreground">
+                    {TYPE_LABELS[entry.type]}
+                  </span>
+                ) : (
+                  <span className="shrink-0 text-muted-foreground">
+                    <FolderIcon />
+                  </span>
+                )}
                 <span
                   className={[
                     "min-w-0 flex-1 truncate text-foreground",
@@ -187,81 +267,48 @@ export function WorkspaceEditor({
         </div>
       )}
 
-      {/* Tab bar (only when both sources are available) */}
-      {hasBothTabs && (
-        <div className="flex rounded-md border border-border bg-muted-faint p-0.5">
+      {/* Action items */}
+      <div className="space-y-0.5">
+        {enableLocal && (
           <button
             type="button"
-            onClick={() => setActiveTab("local")}
-            disabled={disabled}
-            className={[
-              "flex flex-1 items-center justify-center gap-1.5 rounded px-2 py-1 text-[0.65rem] font-medium transition-colors disabled:pointer-events-none disabled:opacity-50",
-              effectiveTab === "local"
-                ? "bg-background text-foreground shadow-sm"
-                : "text-muted-foreground hover:text-foreground",
-            ].join(" ")}
+            onClick={
+              onBrowseLocalFolder
+                ? async () => {
+                    const path = await onBrowseLocalFolder();
+                    if (path) workspace.addLocalPath(path);
+                  }
+                : () => setActivePanel("browse")
+            }
+            disabled={disabled || !runnerId}
+            className="flex w-full items-center gap-2 rounded-md px-2.5 py-2 text-xs text-foreground transition-colors hover:bg-accent-hover disabled:pointer-events-none disabled:opacity-40"
           >
             <FolderIcon />
-            Local Folder
+            <span className="flex-1 text-left">Browse Folder</span>
+            {!onBrowseLocalFolder && <ChevronRightIcon />}
           </button>
+        )}
+        {enableGitHub && (
           <button
             type="button"
-            onClick={() => setActiveTab("github")}
+            onClick={() => setActivePanel("github")}
             disabled={disabled}
-            className={[
-              "flex flex-1 items-center justify-center gap-1.5 rounded px-2 py-1 text-[0.65rem] font-medium transition-colors disabled:pointer-events-none disabled:opacity-50",
-              effectiveTab === "github"
-                ? "bg-background text-foreground shadow-sm"
-                : "text-muted-foreground hover:text-foreground",
-            ].join(" ")}
+            className="flex w-full items-center gap-2 rounded-md px-2.5 py-2 text-xs text-foreground transition-colors hover:bg-accent-hover disabled:pointer-events-none disabled:opacity-40"
           >
             <GitHubIcon />
-            GitHub Repo
+            <span className="flex-1 text-left">Connect GitHub</span>
+            <ChevronRightIcon />
           </button>
-        </div>
-      )}
-
-      {/* Tab content */}
-      <div className="rounded-md border border-border bg-card p-3">
-        {effectiveTab === "local" && hasLocal && (
-          <RunnerFileBrowser
-            runnerId={runnerId!}
-            onSelect={(path) => workspace.addLocalPath(path)}
-            onCancel={() => {
-              if (hasGitHub) setActiveTab("github");
-            }}
-          />
-        )}
-
-        {effectiveTab === "github" && hasGitHub && (
-          gitHubConnection ? (
-            <GitHubPanel
-              connection={gitHubConnection}
-              onSelect={handleGitHubSelect}
-              onClose={() => {
-                if (hasLocal) setActiveTab("local");
-              }}
-            />
-          ) : (
-            <ManualGitPanel
-              url={manualUrl}
-              branch={manualBranch}
-              onUrlChange={setManualUrl}
-              onBranchChange={setManualBranch}
-              onAdd={handleManualAdd}
-              onCancel={() => {
-                if (hasLocal) setActiveTab("local");
-              }}
-              onKeyDown={handleKeyDown(handleManualAdd)}
-            />
-          )
         )}
       </div>
     </div>
   );
 }
 
-/** GitHub panel with progressive disclosure: connect prompt or repo picker. */
+// ---------------------------------------------------------------------------
+// GitHub panel (progressive disclosure: connect prompt or repo picker)
+// ---------------------------------------------------------------------------
+
 function GitHubPanel({
   connection,
   onSelect,
@@ -295,16 +342,6 @@ function GitHubPanel({
 
     return (
       <div className="space-y-3 text-center">
-        <div className="flex justify-end">
-          <button
-            type="button"
-            onClick={onClose}
-            className="rounded p-0.5 text-muted-foreground hover:text-foreground transition-colors"
-            aria-label="Close"
-          >
-            <XIcon />
-          </button>
-        </div>
         <div className="space-y-1">
           <p className="text-xs font-medium text-foreground">
             Choose a GitHub repo to add to workspace
@@ -365,23 +402,13 @@ function GitHubPanel({
             {connection.user?.login ?? "Connected"}
           </span>
         </div>
-        <div className="flex items-center gap-2">
-          <button
-            type="button"
-            onClick={connection.disconnect}
-            className="text-[0.6rem] text-muted-foreground hover:text-destructive transition-colors"
-          >
-            Disconnect
-          </button>
-          <button
-            type="button"
-            onClick={onClose}
-            className="rounded p-0.5 text-muted-foreground hover:text-foreground transition-colors"
-            aria-label="Close"
-          >
-            <XIcon />
-          </button>
-        </div>
+        <button
+          type="button"
+          onClick={connection.disconnect}
+          className="text-[0.6rem] text-muted-foreground hover:text-destructive transition-colors"
+        >
+          Disconnect
+        </button>
       </div>
       <GitHubRepoPicker
         token={connection.token!}
@@ -392,7 +419,10 @@ function GitHubPanel({
   );
 }
 
-/** Fallback manual git URL input for platform builders without GitHub connection. */
+// ---------------------------------------------------------------------------
+// Manual git URL input (fallback for platform builders without GitHub OAuth)
+// ---------------------------------------------------------------------------
+
 function ManualGitPanel({
   url,
   branch,
@@ -450,6 +480,26 @@ function ManualGitPanel({
   );
 }
 
+// ---------------------------------------------------------------------------
+// Icons
+// ---------------------------------------------------------------------------
+
+function ChevronLeftIcon() {
+  return (
+    <svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round">
+      <path d="M7.5 2.5L4 6L7.5 9.5" />
+    </svg>
+  );
+}
+
+function ChevronRightIcon() {
+  return (
+    <svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" className="text-muted-foreground">
+      <path d="M4.5 2.5L8 6L4.5 9.5" />
+    </svg>
+  );
+}
+
 function XIcon() {
   return (
     <svg width="14" height="14" viewBox="0 0 14 14" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round">

package/src/workspace/index.ts

@@ -7,3 +7,8 @@ export { WorkspaceEditor } from "./WorkspaceEditor";
 export type { WorkspaceEditorProps } from "./WorkspaceEditor";
 export { WorkspaceSummary } from "./WorkspaceSummary";
 export type { WorkspaceSummaryProps } from "./WorkspaceSummary";
+export { useRecentWorkspaces } from "./useRecentWorkspaces";
+export type {
+  RecentWorkspace,
+  UseRecentWorkspacesReturn,
+} from "./useRecentWorkspaces";

package/src/workspace/useRecentWorkspaces.ts

@@ -0,0 +1,162 @@
+"use client";
+
+import { useCallback, useSyncExternalStore } from "react";
+
+const STORAGE_KEY_PREFIX = "stigmer:recent-workspaces:";
+const MAX_RECENT = 8;
+
+/** A recently used or favorited workspace path for a specific runner. */
+export interface RecentWorkspace {
+  /** Absolute path on the runner's filesystem. */
+  readonly path: string;
+  /** Whether the user pinned this path as a favorite. */
+  readonly pinned: boolean;
+  /** Epoch ms when this path was last selected. */
+  readonly lastUsed: number;
+}
+
+/** Return value of {@link useRecentWorkspaces}. */
+export interface UseRecentWorkspacesReturn {
+  /** Recent paths sorted: pinned first, then by recency. */
+  readonly entries: readonly RecentWorkspace[];
+  /** Record a path selection (adds or bumps it in the list). */
+  readonly recordSelection: (path: string) => void;
+  /** Toggle the pinned state of a path. */
+  readonly togglePin: (path: string) => void;
+  /** Remove a path from the recent list. */
+  readonly remove: (path: string) => void;
+}
+
+function storageKey(runnerId: string): string {
+  return `${STORAGE_KEY_PREFIX}${runnerId}`;
+}
+
+function readEntries(runnerId: string): RecentWorkspace[] {
+  try {
+    const raw = localStorage.getItem(storageKey(runnerId));
+    if (!raw) return [];
+    return JSON.parse(raw) as RecentWorkspace[];
+  } catch {
+    return [];
+  }
+}
+
+function writeEntries(runnerId: string, entries: RecentWorkspace[]): void {
+  try {
+    localStorage.setItem(storageKey(runnerId), JSON.stringify(entries));
+  } catch {
+    // localStorage full or unavailable — silently degrade.
+  }
+}
+
+function sortEntries(entries: RecentWorkspace[]): RecentWorkspace[] {
+  return [...entries].sort((a, b) => {
+    if (a.pinned !== b.pinned) return a.pinned ? -1 : 1;
+    return b.lastUsed - a.lastUsed;
+  });
+}
+
+const listeners = new Set<() => void>();
+let snapshotVersion = 0;
+
+function notifyListeners(): void {
+  snapshotVersion++;
+  for (const fn of listeners) fn();
+}
+
+function subscribe(callback: () => void): () => void {
+  listeners.add(callback);
+  return () => listeners.delete(callback);
+}
+
+const EMPTY: readonly RecentWorkspace[] = [];
+
+let cachedRunnerId: string | null = null;
+let cachedVersion = -1;
+let cachedResult: readonly RecentWorkspace[] = EMPTY;
+
+function getSnapshot(runnerId: string | null): readonly RecentWorkspace[] {
+  if (!runnerId) return EMPTY;
+  if (runnerId === cachedRunnerId && snapshotVersion === cachedVersion) {
+    return cachedResult;
+  }
+  cachedRunnerId = runnerId;
+  cachedVersion = snapshotVersion;
+  cachedResult = sortEntries(readEntries(runnerId));
+  return cachedResult;
+}
+
+/**
+ * Manages recently used workspace paths for a specific runner,
+ * persisted in `localStorage`.
+ *
+ * Entries are keyed by `runner_id` so each runner maintains its own
+ * history. Pinned paths appear first, then by most-recently-used.
+ *
+ * @param runnerId - Runner to scope the history to. When `null`, returns empty.
+ */
+export function useRecentWorkspaces(
+  runnerId: string | null,
+): UseRecentWorkspacesReturn {
+  const entries = useSyncExternalStore(
+    subscribe,
+    () => getSnapshot(runnerId),
+    () => EMPTY,
+  );
+
+  const recordSelection = useCallback(
+    (path: string) => {
+      if (!runnerId) return;
+      const existing = readEntries(runnerId);
+      const idx = existing.findIndex((e) => e.path === path);
+      const now = Date.now();
+
+      let updated: RecentWorkspace[];
+      if (idx >= 0) {
+        updated = [...existing];
+        updated[idx] = { ...updated[idx], lastUsed: now };
+      } else {
+        updated = [{ path, pinned: false, lastUsed: now }, ...existing];
+      }
+
+      if (updated.length > MAX_RECENT) {
+        const unpinned = updated.filter((e) => !e.pinned);
+        if (unpinned.length > 0) {
+          unpinned.sort((a, b) => a.lastUsed - b.lastUsed);
+          const oldest = unpinned[0];
+          updated = updated.filter((e) => e !== oldest);
+        }
+      }
+
+      writeEntries(runnerId, updated);
+      notifyListeners();
+    },
+    [runnerId],
+  );
+
+  const togglePin = useCallback(
+    (path: string) => {
+      if (!runnerId) return;
+      const existing = readEntries(runnerId);
+      const idx = existing.findIndex((e) => e.path === path);
+      if (idx < 0) return;
+      const updated = [...existing];
+      updated[idx] = { ...updated[idx], pinned: !updated[idx].pinned };
+      writeEntries(runnerId, updated);
+      notifyListeners();
+    },
+    [runnerId],
+  );
+
+  const remove = useCallback(
+    (path: string) => {
+      if (!runnerId) return;
+      const updated = readEntries(runnerId).filter((e) => e.path !== path);
+      writeEntries(runnerId, updated);
+      notifyListeners();
+    },
+    [runnerId],
+  );
+
+  return { entries, recordSelection, togglePin, remove };
+}

package/src/workspace/useWorkspaceEntries.ts

@@ -49,6 +49,14 @@ export interface UseWorkspaceEntriesReturn {
   readonly remove: (id: string) => void;
   /** Remove all entries. */
   readonly clear: () => void;
+  /**
+   * Remove all local folder entries, keeping git entries intact.
+   *
+   * Used when the user switches runners — local paths from the previous
+   * runner are invalid on the new runner, but git repos are
+   * runner-independent and can stay.
+   */
+  readonly clearLocal: () => void;
   /** Convert entries to the `WorkspaceEntryInput[]` shape required by the SDK. */
   readonly toInput: () => WorkspaceEntryInput[];
   /** `true` when at least one entry exists. */
@@ -133,6 +141,10 @@ export function useWorkspaceEntries(): UseWorkspaceEntriesReturn {
     setEntries([]);
   }, []);
 
+  const clearLocal = useCallback(() => {
+    setEntries((prev) => prev.filter((e) => e.type !== "local"));
+  }, []);
+
   const toInput = useCallback((): WorkspaceEntryInput[] => {
     return entries.map((entry): WorkspaceEntryInput => {
       const source: WorkspaceSourceInput =
@@ -150,6 +162,7 @@ export function useWorkspaceEntries(): UseWorkspaceEntriesReturn {
     addLocalPath,
     remove,
     clear,
+    clearLocal,
     toInput,
     hasEntries: entries.length > 0,
   };