@houston-ai/workspace 0.2.0

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@houston-ai/workspace",
+  "version": "0.2.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src"
+  ],
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@houston-ai/core": "workspace:*"
+  },
+  "dependencies": {
+    "lucide-react": "^0.577.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/drop-zone.tsx

@@ -0,0 +1,90 @@
+/**
+ * Drop zone hooks for drag-and-drop.
+ * Container handles ALL drops. Folders only provide visual highlight state.
+ */
+import { useCallback, useRef, useState } from "react"
+
+/** MIME type used for internal file moves. */
+export const INTERNAL_DRAG_TYPE = "application/x-houston-file"
+
+function hasDragData(e: React.DragEvent) {
+  return e.dataTransfer.types.includes("Files") || e.dataTransfer.types.includes(INTERNAL_DRAG_TYPE)
+}
+
+/** Container-level drop zone. Handles ALL drop events (both external and internal). */
+export function useDropZone(
+  onFilesDropped?: (files: File[], targetFolder?: string) => void,
+  onMove?: (sourcePath: string, targetFolder: string | null) => void,
+) {
+  const [isDragging, setIsDragging] = useState(false)
+  const counter = useRef(0)
+
+  const onDragEnter = useCallback((e: React.DragEvent) => {
+    e.preventDefault()
+    counter.current++
+    if (hasDragData(e)) setIsDragging(true)
+  }, [])
+
+  const onDragLeave = useCallback((e: React.DragEvent) => {
+    e.preventDefault()
+    counter.current--
+    if (counter.current === 0) setIsDragging(false)
+  }, [])
+
+  const onDragOver = useCallback((e: React.DragEvent) => {
+    e.preventDefault()
+  }, [])
+
+  const onDrop = useCallback(
+    (e: React.DragEvent) => {
+      e.preventDefault()
+      counter.current = 0
+      setIsDragging(false)
+      const internal = e.dataTransfer.getData(INTERNAL_DRAG_TYPE)
+      if (internal && onMove) { onMove(internal, null); return }
+      if (!onFilesDropped) return
+      const files = Array.from(e.dataTransfer.files)
+      if (files.length > 0) onFilesDropped(files)
+    },
+    [onFilesDropped, onMove],
+  )
+
+  return {
+    isDragging,
+    dragHandlers: { onDragEnter, onDragLeave, onDragOver, onDrop },
+  }
+}
+
+/** Folder-level highlight only — does NOT handle the drop (container does). */
+export function useFolderDropTarget() {
+  const [isOver, setIsOver] = useState(false)
+  const counter = useRef(0)
+
+  const onDragEnter = useCallback((e: React.DragEvent) => {
+    e.preventDefault()
+    counter.current++
+    if (hasDragData(e)) setIsOver(true)
+  }, [])
+
+  const onDragLeave = useCallback((e: React.DragEvent) => {
+    e.preventDefault()
+    counter.current--
+    if (counter.current === 0) setIsOver(false)
+  }, [])
+
+  const onDragOver = useCallback((e: React.DragEvent) => {
+    e.preventDefault()
+  }, [])
+
+  const onDrop = useCallback((e: React.DragEvent) => {
+    e.preventDefault()
+    // Do NOT stopPropagation — let container handle the actual drop
+    counter.current = 0
+    setIsOver(false)
+  }, [])
+
+  return {
+    isOver,
+    folderHandlers: { onDragEnter, onDragLeave, onDragOver, onDrop },
+  }
+}

package/src/file-menu.tsx

@@ -0,0 +1,68 @@
+/**
+ * Lightweight right-click context menu for file rows.
+ * Portal-based — renders at cursor position, closes on outside click or Escape.
+ */
+import type { ReactNode } from "react"
+import { createPortal } from "react-dom"
+import { ExternalLink, FolderSearch, Trash2 } from "lucide-react"
+import type { FileEntry } from "./types"
+
+export function FileMenu({
+  file,
+  position,
+  onClose,
+  onOpen,
+  onReveal,
+  onDelete,
+}: {
+  file: FileEntry
+  position: { x: number; y: number }
+  onClose: () => void
+  onOpen?: (file: FileEntry) => void
+  onReveal?: (file: FileEntry) => void
+  onDelete?: (file: FileEntry) => void
+}) {
+  return createPortal(
+    <>
+      <div
+        className="fixed inset-0 z-40"
+        onClick={onClose}
+        onContextMenu={(e) => { e.preventDefault(); onClose() }}
+      />
+      <div
+        className="fixed z-50 min-w-[160px] rounded-md border bg-popover p-1 text-popover-foreground shadow-md"
+        style={{ left: position.x, top: position.y }}
+        onKeyDown={(e) => e.key === "Escape" && onClose()}
+      >
+        {onOpen && (
+          <MenuItem onClick={() => { onOpen(file); onClose() }} icon={<ExternalLink />} label="Open" />
+        )}
+        {onReveal && (
+          <MenuItem onClick={() => { onReveal(file); onClose() }} icon={<FolderSearch />} label="Show in Finder" />
+        )}
+        {(onOpen || onReveal) && onDelete && <div className="-mx-1 my-1 h-px bg-border" />}
+        {onDelete && (
+          <MenuItem onClick={() => { onDelete(file); onClose() }} icon={<Trash2 />} label="Move to Trash" destructive />
+        )}
+      </div>
+    </>,
+    document.body,
+  )
+}
+
+function MenuItem({ onClick, icon, label, destructive }: {
+  onClick: () => void
+  icon: ReactNode
+  label: string
+  destructive?: boolean
+}) {
+  return (
+    <button
+      onClick={onClick}
+      className={`flex w-full items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-none select-none hover:bg-accent [&_svg]:size-4 [&_svg]:shrink-0 [&_svg]:text-muted-foreground ${destructive ? "text-destructive [&_svg]:text-destructive" : ""}`}
+    >
+      {icon}
+      {label}
+    </button>
+  )
+}

package/src/file-row.tsx

@@ -0,0 +1,198 @@
+/**
+ * Finder-style file and folder rows.
+ * Files: click to select, double-click to open, right-click context menu, draggable.
+ * Folders: click to expand/collapse, drop target for moves.
+ */
+import { useEffect, useRef, useState } from "react"
+import { cn } from "@houston-ai/core"
+import type { FileEntry } from "./types"
+import type { FolderNode } from "./tree"
+import { INTERNAL_DRAG_TYPE, useFolderDropTarget } from "./drop-zone"
+import { FolderIcon, DisclosureChevron, getFileIcon } from "./finder-icons"
+import { formatSize, formatFinderDate, getKind } from "./utils"
+import { FileMenu } from "./file-menu"
+
+const DEPTH_INDENT = 20
+const BASE_INDENT = 12
+const TRIANGLE_AREA = 16
+
+/** Column grid shared between header and rows. */
+export const COL_GRID = "1fr 190px 80px 130px"
+
+export function FolderSection({
+  node, depth, selectedPath, onSelect, onOpen, onReveal, onDelete,
+  onRename, onFilesDropped, onDragActive, onMove,
+}: {
+  node: FolderNode
+  depth: number
+  selectedPath?: string | null
+  onSelect?: (file: FileEntry) => void
+  onOpen?: (file: FileEntry) => void
+  onReveal?: (file: FileEntry) => void
+  onDelete?: (file: FileEntry) => void
+  onRename?: (file: FileEntry, newName: string) => void
+  onFilesDropped?: (files: File[], targetFolder?: string) => void
+  onDragActive?: (folder: string | null) => void
+  onMove?: (sourcePath: string, targetFolder: string | null) => void
+}) {
+  const [open, setOpen] = useState(true)
+  const [dragging, setDragging] = useState(false)
+  const { isOver, folderHandlers } = useFolderDropTarget()
+
+  useEffect(() => {
+    onDragActive?.(isOver ? node.path : null)
+  }, [isOver, node.path, onDragActive])
+
+  const padLeft = BASE_INDENT + depth * DEPTH_INDENT
+
+  return (
+    <>
+      <div
+        role="button"
+        tabIndex={0}
+        draggable={!!onMove}
+        onDragStart={(e) => { e.dataTransfer.setData(INTERNAL_DRAG_TYPE, node.path); e.dataTransfer.effectAllowed = "move"; setDragging(true) }}
+        onDragEnd={() => setDragging(false)}
+        onClick={() => setOpen(!open)}
+        onKeyDown={(e) => e.key === "Enter" && setOpen(!open)}
+        className={cn(
+          "h-[24px] select-none cursor-default items-center",
+          isOver ? "!bg-[rgba(0,122,255,0.12)] !rounded-lg" : "",
+          dragging && "opacity-40",
+        )}
+        style={{ display: "grid", gridTemplateColumns: COL_GRID }}
+        {...folderHandlers}
+      >
+        <div className="flex items-center gap-1.5 min-w-0" style={{ paddingLeft: padLeft }}>
+          <DisclosureChevron open={open} />
+          <FolderIcon />
+          <span className="text-[13px] truncate">{node.name}</span>
+        </div>
+        <span className="text-[11px] text-[#6d6d6d] truncate px-2">{"\u2014"}</span>
+        <span className="text-[11px] text-[#6d6d6d] text-right px-2">--</span>
+        <span className="text-[11px] text-[#6d6d6d] truncate px-2">Folder</span>
+      </div>
+      {open &&
+        node.children.map((child) =>
+          child.kind === "folder" ? (
+            <FolderSection
+              key={child.path} node={child} depth={depth + 1}
+              selectedPath={selectedPath} onSelect={onSelect}
+              onOpen={onOpen} onReveal={onReveal} onDelete={onDelete}
+              onRename={onRename}
+              onFilesDropped={onFilesDropped} onDragActive={onDragActive} onMove={onMove}
+            />
+          ) : (
+            <FileRow
+              key={child.entry.path} file={child.entry} depth={depth + 1}
+              selected={selectedPath === child.entry.path}
+              onSelect={onSelect} onOpen={onOpen}
+              onReveal={onReveal} onDelete={onDelete} onRename={onRename} onMove={onMove}
+            />
+          ),
+        )}
+    </>
+  )
+}
+
+export function FileRow({
+  file, depth = 0, selected, onSelect, onOpen, onReveal, onDelete, onRename, onMove,
+}: {
+  file: FileEntry
+  depth?: number
+  selected?: boolean
+  onSelect?: (file: FileEntry) => void
+  onOpen?: (file: FileEntry) => void
+  onReveal?: (file: FileEntry) => void
+  onDelete?: (file: FileEntry) => void
+  onRename?: (file: FileEntry, newName: string) => void
+  onMove?: (sourcePath: string, targetFolder: string | null) => void
+}) {
+  const [menu, setMenu] = useState<{ x: number; y: number } | null>(null)
+  const [dragging, setDragging] = useState(false)
+  const [renaming, setRenaming] = useState(false)
+  const [renameValue, setRenameValue] = useState("")
+  const renameRef = useRef<HTMLInputElement>(null)
+  const padLeft = BASE_INDENT + depth * DEPTH_INDENT + TRIANGLE_AREA
+  const hasMenu = onOpen || onReveal || onDelete
+  const sec = selected ? "text-white/80" : "text-[#6d6d6d]"
+
+  const startRename = () => {
+    if (!onRename) return
+    setRenameValue(file.name)
+    setRenaming(true)
+    requestAnimationFrame(() => {
+      const input = renameRef.current
+      if (!input) return
+      input.focus()
+      const dot = file.name.lastIndexOf(".")
+      input.setSelectionRange(0, dot > 0 ? dot : file.name.length)
+    })
+  }
+
+  const commitRename = () => {
+    const trimmed = renameValue.trim()
+    setRenaming(false)
+    if (trimmed && trimmed !== file.name) onRename?.(file, trimmed)
+  }
+
+  return (
+    <>
+      <div
+        role="row"
+        tabIndex={0}
+        draggable={!!onMove && !renaming}
+        onDragStart={(e) => { e.dataTransfer.setData(INTERNAL_DRAG_TYPE, file.path); e.dataTransfer.effectAllowed = "move"; setDragging(true) }}
+        onDragEnd={() => setDragging(false)}
+        onClick={() => !renaming && onSelect?.(file)}
+        onDoubleClick={() => !renaming && onOpen?.(file)}
+        onKeyDown={(e) => {
+          if (e.key === "Enter" && selected && !renaming) { e.preventDefault(); startRename() }
+          if (e.key === "Escape" && renaming) setRenaming(false)
+        }}
+        onContextMenu={(e) => {
+          if (!hasMenu || renaming) return
+          e.preventDefault()
+          onSelect?.(file)
+          setMenu({ x: e.clientX, y: e.clientY })
+        }}
+        data-selected={selected || undefined}
+        className={cn(
+          "h-[24px] cursor-default select-none items-center outline-none",
+          selected && "!bg-[#2068d0] text-white rounded-lg",
+          dragging && "opacity-40",
+        )}
+        style={{ display: "grid", gridTemplateColumns: COL_GRID }}
+      >
+        <div className="flex items-center gap-1.5 min-w-0" style={{ paddingLeft: padLeft }}>
+          {getFileIcon(file.extension)}
+          {renaming ? (
+            <input
+              ref={renameRef}
+              value={renameValue}
+              onChange={(e) => setRenameValue(e.target.value)}
+              onKeyDown={(e) => {
+                if (e.key === "Enter") { e.preventDefault(); commitRename() }
+                if (e.key === "Escape") { e.stopPropagation(); setRenaming(false) }
+              }}
+              onBlur={commitRename}
+              className="flex-1 text-[13px] bg-white text-[#0d0d0d] outline-none rounded px-1 -ml-1 min-w-0 border border-[#2068d0] shadow-sm"
+            />
+          ) : (
+            <span className="text-[13px] truncate">{file.name}</span>
+          )}
+        </div>
+        <span className={cn("text-[11px] truncate px-2", sec)}>{formatFinderDate(file.dateModified)}</span>
+        <span className={cn("text-[11px] text-right px-2", sec)}>{formatSize(file.size)}</span>
+        <span className={cn("text-[11px] truncate px-2", sec)}>{getKind(file.extension)}</span>
+      </div>
+      {menu && (
+        <FileMenu
+          file={file} position={menu}
+          onClose={() => setMenu(null)}
+          onOpen={onOpen} onReveal={onReveal} onDelete={onDelete}
+        />
+      )}
+    </>
+  )
+}

package/src/files-browser.tsx

@@ -0,0 +1,294 @@
+/**
+ * FilesBrowser — macOS Finder list-view clone.
+ * Column headers with sort, file/folder tree, status bar, drag-and-drop.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from "react"
+import { createPortal } from "react-dom"
+import { cn, Button } from "@houston-ai/core"
+import { Upload } from "lucide-react"
+import type { FileEntry } from "./types"
+import { useDropZone } from "./drop-zone"
+import { FileRow, FolderSection, COL_GRID } from "./file-row"
+import { NewFolderInput } from "./new-folder-input"
+import { buildTree } from "./tree"
+import { sortTree, type SortKey, type SortDirection } from "./utils"
+
+export interface FilesBrowserProps {
+  files: FileEntry[]
+  loading?: boolean
+  selectedPath?: string | null
+  onSelect?: (file: FileEntry) => void
+  onOpen?: (file: FileEntry) => void
+  onReveal?: (file: FileEntry) => void
+  onDelete?: (file: FileEntry) => void
+  onFilesDropped?: (files: File[], targetFolder?: string) => void
+  /** Move a file/folder to a new location (null = root) */
+  onMove?: (sourcePath: string, targetFolder: string | null) => void
+  onRename?: (file: FileEntry, newName: string) => void
+  onCreateFolder?: (name: string) => void
+  onBrowse?: () => void
+  emptyTitle?: string
+  emptyDescription?: string
+}
+
+export function FilesBrowser({
+  files, loading, selectedPath: controlledSelected, onSelect, onOpen, onReveal, onDelete,
+  onFilesDropped, onMove, onRename, onCreateFolder, onBrowse,
+  emptyTitle = "No files yet",
+  emptyDescription = "When agents create files, they\u2019ll appear here.",
+}: FilesBrowserProps) {
+  // Internal selection state — used when consumer doesn't control selection
+  const [internalSelected, setInternalSelected] = useState<string | null>(null)
+  const selectedPath = controlledSelected !== undefined ? controlledSelected : internalSelected
+  const handleSelect = useCallback((file: FileEntry) => {
+    setInternalSelected(file.path)
+    onSelect?.(file)
+  }, [onSelect])
+
+  const [creatingFolder, setCreatingFolder] = useState(false)
+  const [bgMenu, setBgMenu] = useState<{ x: number; y: number } | null>(null)
+
+  const [folderDropTarget, setFolderDropTarget] = useState<string | null>(null)
+  const folderTargetRef = useRef<string | null>(null)
+  const [sortKey, setSortKey] = useState<SortKey>("name")
+  const [sortDir, setSortDir] = useState<SortDirection>("asc")
+
+  const onDragActive = useCallback((f: string | null) => {
+    setFolderDropTarget(f)
+    folderTargetRef.current = f
+  }, [])
+
+  // Wrap callbacks so container drops target the hovered folder (or root)
+  const handleDrop = useCallback((files: File[]) => {
+    onFilesDropped?.(files, folderTargetRef.current ?? undefined)
+  }, [onFilesDropped])
+  const handleMove = useCallback((src: string) => {
+    onMove?.(src, folderTargetRef.current)
+  }, [onMove])
+  const { isDragging, dragHandlers } = useDropZone(handleDrop, handleMove)
+
+  const isEmpty = !loading && files.length === 0
+  const isRootTarget = isDragging && folderDropTarget === null
+
+  const handleSort = useCallback((key: SortKey) => {
+    setSortKey((prev) => {
+      if (prev === key) { setSortDir((d) => (d === "asc" ? "desc" : "asc")); return prev }
+      setSortDir("asc")
+      return key
+    })
+  }, [])
+
+  const tree = useMemo(() => {
+    if (isEmpty) return null
+    return sortTree(buildTree(files), sortKey, sortDir)
+  }, [files, isEmpty, sortKey, sortDir])
+
+  const fileCount = useMemo(() => {
+    if (!tree) return 0
+    let count = 0
+    const walk = (children: typeof tree.children) => {
+      for (const c of children) {
+        count++
+        if (c.kind === "folder") walk(c.children)
+      }
+    }
+    walk(tree.children)
+    return count
+  }, [tree])
+
+  if (isEmpty) {
+    return (
+      <div className="flex-1 flex flex-col items-center pt-[20vh] gap-4 px-8">
+        <div className="space-y-2 text-center max-w-md">
+          <h1 className="text-2xl font-semibold tracking-tight">{emptyTitle}</h1>
+          <p className="text-sm text-muted-foreground">{emptyDescription}</p>
+        </div>
+        {onBrowse && (
+          <Button variant="default" size="sm" onClick={onBrowse}>
+            <Upload className="size-4 mr-1.5" /> Browse files
+          </Button>
+        )}
+      </div>
+    )
+  }
+
+  return (
+    <div
+      className="relative flex flex-col overflow-hidden bg-white border border-[#e0e0e0] rounded-xl m-4 h-[calc(100%-2rem)]"
+      {...(onFilesDropped || onMove ? dragHandlers : {})}
+    >
+      <div className="h-[24px] shrink-0 border-b border-[#e5e5e5] bg-[#fafafa] select-none flex items-center rounded-t-xl">
+        <div className="flex-1 min-w-0 items-center h-full" style={{ display: "grid", gridTemplateColumns: COL_GRID }}>
+          <HeaderCell label="Name" col="name" sortKey={sortKey} sortDir={sortDir} onSort={handleSort} className="pl-7" />
+          <HeaderCell label="Date Modified" col="dateModified" sortKey={sortKey} sortDir={sortDir} onSort={handleSort} />
+          <HeaderCell label="Size" col="size" sortKey={sortKey} sortDir={sortDir} onSort={handleSort} className="justify-end" />
+          <HeaderCell label="Kind" col="kind" sortKey={sortKey} sortDir={sortDir} onSort={handleSort} last />
+        </div>
+      </div>
+
+      <div
+        className="flex-1 flex flex-col overflow-y-auto px-1"
+        style={{
+          backgroundColor: isRootTarget ? "rgba(0,122,255,0.06)" : undefined,
+        }}
+        onClick={(e) => {
+          if (e.target === e.currentTarget) {
+            setInternalSelected(null)
+            setBgMenu(null)
+          }
+        }}
+        onContextMenu={(e) => {
+          if (e.target === e.currentTarget && onCreateFolder) {
+            e.preventDefault()
+            setInternalSelected(null)
+            setBgMenu({ x: e.clientX, y: e.clientY })
+          }
+        }}
+      >
+        {loading ? (
+          <div className="flex items-center justify-center py-16">
+            <p className="text-sm text-muted-foreground/50">Loading\u2026</p>
+          </div>
+        ) : (
+          <>
+            <div className="shrink-0 [&>:nth-child(even)]:bg-[#f5f5f5] [&>:nth-child(even)]:rounded-lg">
+              {creatingFolder && (
+                <NewFolderInput
+                  onConfirm={(n) => { onCreateFolder?.(n); setCreatingFolder(false) }}
+                  onCancel={() => setCreatingFolder(false)}
+                />
+              )}
+              {tree?.children.map((child) =>
+                child.kind === "folder" ? (
+                  <FolderSection
+                    key={child.path} node={child} depth={0}
+                    selectedPath={selectedPath} onSelect={handleSelect}
+                    onOpen={onOpen} onReveal={onReveal} onDelete={onDelete}
+                    onRename={onRename}
+                    onFilesDropped={onFilesDropped} onDragActive={onDragActive} onMove={onMove}
+                  />
+                ) : (
+                  <FileRow
+                    key={child.entry.path} file={child.entry}
+                    selected={selectedPath === child.entry.path}
+                    onSelect={handleSelect} onOpen={onOpen}
+                    onReveal={onReveal} onDelete={onDelete} onRename={onRename} onMove={onMove}
+                  />
+                ),
+              )}
+            </div>
+            <FillerStripes
+              startIndex={fileCount}
+              onDeselect={() => { setInternalSelected(null); setBgMenu(null) }}
+              onContextMenu={onCreateFolder ? (e) => {
+                e.preventDefault()
+                setInternalSelected(null)
+                setBgMenu({ x: e.clientX, y: e.clientY })
+              } : undefined}
+            />
+          </>
+        )}
+      </div>
+
+      {bgMenu && (
+        <BgContextMenu
+          position={bgMenu}
+          onNewFolder={() => { setCreatingFolder(true); setBgMenu(null) }}
+          onClose={() => setBgMenu(null)}
+        />
+      )}
+    </div>
+  )
+}
+
+/** Fills remaining vertical space with real rounded stripe divs. */
+function FillerStripes({ startIndex, onDeselect, onContextMenu }: {
+  startIndex: number
+  onDeselect: () => void
+  onContextMenu?: (e: React.MouseEvent) => void
+}) {
+  const containerRef = useRef<HTMLDivElement>(null)
+  const [count, setCount] = useState(0)
+
+  useEffect(() => {
+    const el = containerRef.current
+    if (!el) return
+    const update = () => {
+      const h = el.clientHeight
+      setCount(Math.ceil(h / 24))
+    }
+    update()
+    const obs = new ResizeObserver(update)
+    obs.observe(el)
+    return () => obs.disconnect()
+  }, [])
+
+  return (
+    <div ref={containerRef} className="flex-1 min-h-0">
+      {Array.from({ length: count }, (_, i) => (
+        <div
+          key={i}
+          className={cn("h-[24px]", (startIndex + i) % 2 === 1 && "bg-[#f5f5f5] rounded-lg")}
+          onClick={onDeselect}
+          onContextMenu={onContextMenu}
+        />
+      ))}
+    </div>
+  )
+}
+
+function BgContextMenu({ position, onNewFolder, onClose }: {
+  position: { x: number; y: number }
+  onNewFolder: () => void
+  onClose: () => void
+}) {
+  return createPortal(
+    <>
+      <div className="fixed inset-0 z-50" onClick={onClose} onContextMenu={(e) => { e.preventDefault(); onClose() }} />
+      <div
+        className="fixed z-50 bg-white/95 backdrop-blur-xl border border-black/10 rounded-lg shadow-lg py-1 min-w-[160px]"
+        style={{ left: position.x, top: position.y }}
+      >
+        <button
+          onClick={onNewFolder}
+          className="w-full text-left px-3 py-1.5 text-[13px] hover:bg-[#2068d0] hover:text-white rounded-md mx-0.5"
+          style={{ width: "calc(100% - 4px)" }}
+        >
+          New Folder
+        </button>
+      </div>
+    </>,
+    document.body,
+  )
+}
+
+function HeaderCell({ label, col, sortKey, sortDir, onSort, className, last }: {
+  label: string
+  col: SortKey
+  sortKey: SortKey
+  sortDir: SortDirection
+  onSort: (key: SortKey) => void
+  className?: string
+  last?: boolean
+}) {
+  const active = sortKey === col
+  return (
+    <button
+      onClick={() => onSort(col)}
+      className={cn(
+        "flex items-center h-full px-2 text-[11px] font-medium text-[#6d6d6d] hover:bg-[#eaeaea] transition-colors",
+        !last && "border-r border-[#e5e5e5]",
+        className,
+      )}
+    >
+      <span className="truncate">{label}</span>
+      {active && (
+        <svg className="size-[6px] ml-1 shrink-0" viewBox="0 0 8 5" fill="#6d6d6d">
+          {sortDir === "asc"
+            ? <path d="M0 5L4 0L8 5Z" />
+            : <path d="M0 0L4 5L8 0Z" />}
+        </svg>
+      )}
+    </button>
+  )
+}

package/src/finder-icons.tsx

@@ -0,0 +1,175 @@
+/**
+ * macOS Finder-style file icons and disclosure triangle.
+ * SVGs designed to match Finder's 16x16 list-view icons.
+ */
+import type { ReactNode } from "react"
+import { cn } from "@houston-ai/core"
+
+const IC = "size-4 shrink-0"
+
+// Shared document outline
+const BODY =
+  "M3.5 1.5C3.5 1.22 3.72 1 4 1H10L13 4V14.5C13 14.78 12.78 15 12.5 15H4C3.72 15 3.5 14.78 3.5 14.5V1.5Z"
+const FOLD =
+  "M10 1L13 4H10.5C10.22 4 10 3.78 10 3.5V1Z"
+
+function DocBase({ children }: { children?: ReactNode }) {
+  return (
+    <svg className={IC} viewBox="0 0 16 16" fill="none">
+      <path d={BODY} fill="white" stroke="#BEBEBE" strokeWidth="0.6" />
+      <path
+        d={FOLD}
+        fill="#E8E8E8"
+        stroke="#BEBEBE"
+        strokeWidth="0.6"
+        strokeLinejoin="round"
+      />
+      {children}
+    </svg>
+  )
+}
+
+/** Blue macOS folder */
+export function FolderIcon() {
+  return (
+    <svg className={IC} viewBox="0 0 16 16" fill="none">
+      <path
+        d="M1.5 3C1.5 2.45 1.95 2 2.5 2H6.29L7.79 3.5H13.5C14.05 3.5 14.5 3.95 14.5 4.5V13C14.5 13.55 14.05 14 13.5 14H2.5C1.95 14 1.5 13.55 1.5 13V3Z"
+        fill="#A0D0F8"
+      />
+      <path
+        d="M1.5 5.5C1.5 4.95 1.95 4.5 2.5 4.5H13.5C14.05 4.5 14.5 4.95 14.5 5.5V13C14.5 13.55 14.05 14 13.5 14H2.5C1.95 14 1.5 13.55 1.5 13V5.5Z"
+        fill="#5DB5F5"
+      />
+    </svg>
+  )
+}
+
+/** White document (generic) */
+export function DocumentIcon() {
+  return <DocBase />
+}
+
+/** Red-badged PDF document */
+export function PdfIcon() {
+  return (
+    <DocBase>
+      <rect x="4.5" y="9" width="7" height="4.5" rx="0.5" fill="#E5252A" />
+      <text
+        x="8"
+        y="12.5"
+        textAnchor="middle"
+        fill="white"
+        fontSize="4"
+        fontWeight="700"
+        fontFamily="system-ui, sans-serif"
+      >
+        PDF
+      </text>
+    </DocBase>
+  )
+}
+
+/** Image document with landscape */
+export function ImageDocIcon() {
+  return (
+    <DocBase>
+      <path d="M5 12.5L7.5 8.5L9 10.5L10 9L12 12.5H5Z" fill="#4CAF50" opacity="0.6" />
+      <circle cx="10.5" cy="7" r="1" fill="#FFC107" opacity="0.6" />
+    </DocBase>
+  )
+}
+
+/** Code document with angle brackets */
+export function CodeDocIcon() {
+  return (
+    <DocBase>
+      <path
+        d="M7 7L5.5 9.5L7 12"
+        stroke="#777"
+        strokeWidth="0.8"
+        fill="none"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+      <path
+        d="M9.5 7L11 9.5L9.5 12"
+        stroke="#777"
+        strokeWidth="0.8"
+        fill="none"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </DocBase>
+  )
+}
+
+/** Spreadsheet with green grid */
+export function SheetDocIcon() {
+  return (
+    <DocBase>
+      <rect x="5" y="7" width="6.5" height="5.5" rx="0.3" fill="none" stroke="#34A853" strokeWidth="0.6" />
+      <line x1="7.2" y1="7" x2="7.2" y2="12.5" stroke="#34A853" strokeWidth="0.4" />
+      <line x1="9.3" y1="7" x2="9.3" y2="12.5" stroke="#34A853" strokeWidth="0.4" />
+      <line x1="5" y1="9" x2="11.5" y2="9" stroke="#34A853" strokeWidth="0.4" />
+      <line x1="5" y1="10.8" x2="11.5" y2="10.8" stroke="#34A853" strokeWidth="0.4" />
+    </DocBase>
+  )
+}
+
+/** Archive/zip document */
+export function ArchiveDocIcon() {
+  return (
+    <DocBase>
+      <rect x="7.2" y="5.5" width="1.6" height="1" rx="0.2" fill="#999" />
+      <rect x="7.2" y="7.5" width="1.6" height="1" rx="0.2" fill="#999" />
+      <rect x="7.2" y="9.5" width="1.6" height="1" rx="0.2" fill="#999" />
+      <rect x="6.8" y="11.5" width="2.4" height="2" rx="0.5" fill="#999" />
+    </DocBase>
+  )
+}
+
+/** Chevron disclosure indicator (rotates 90deg when open) */
+export function DisclosureChevron({
+  open,
+  className,
+}: {
+  open: boolean
+  className?: string
+}) {
+  return (
+    <svg
+      className={cn(
+        "size-[10px] shrink-0 transition-transform duration-150",
+        open && "rotate-90",
+        className,
+      )}
+      viewBox="0 0 10 10"
+      fill="none"
+      stroke="#8e8e8e"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <path d="M3.5 1.5L7 5L3.5 8.5" />
+    </svg>
+  )
+}
+
+// --- Extension mapping ---
+
+const IMAGE_EXT = new Set(["png", "jpg", "jpeg", "gif", "svg", "webp", "ico", "bmp", "tiff", "heic"])
+const CODE_EXT = new Set(["js", "ts", "tsx", "jsx", "rs", "py", "go", "rb", "sh", "c", "cpp", "h", "java", "swift", "kt", "html", "css", "scss", "vue", "svelte"])
+const SHEET_EXT = new Set(["xlsx", "xls", "csv", "numbers", "ods"])
+const ARCHIVE_EXT = new Set(["zip", "gz", "tar", "7z", "rar", "dmg", "iso"])
+
+/** Return the appropriate Finder-style icon for a file extension. */
+export function getFileIcon(extension: string): ReactNode {
+  const ext = extension.toLowerCase()
+  if (ext === "pdf") return <PdfIcon />
+  if (IMAGE_EXT.has(ext)) return <ImageDocIcon />
+  if (CODE_EXT.has(ext)) return <CodeDocIcon />
+  if (SHEET_EXT.has(ext)) return <SheetDocIcon />
+  if (ARCHIVE_EXT.has(ext)) return <ArchiveDocIcon />
+  return <DocumentIcon />
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+// Types
+export type { FileEntry, InstructionFile } from "./types"
+export type { FolderNode, FileNode, TreeNode } from "./tree"
+export { buildTree, countFiles } from "./tree"
+
+// Components
+export { FilesBrowser } from "./files-browser"
+export type { FilesBrowserProps } from "./files-browser"
+
+export { InstructionsPanel } from "./instructions-panel"
+export type { InstructionsPanelProps } from "./instructions-panel"
+
+// Hooks
+export { useDropZone, useFolderDropTarget, INTERNAL_DRAG_TYPE } from "./drop-zone"
+
+// Utilities
+export { formatSize, formatFinderDate, getKind } from "./utils"
+export type { SortKey, SortDirection } from "./utils"

package/src/instructions-panel.tsx

@@ -0,0 +1,97 @@
+/**
+ * InstructionsPanel — editable instruction files for an agent workspace.
+ * Visual style matches Houston's ContextTab exactly: labeled textareas
+ * with auto-save on blur, bg-[#f9f9f9], subtle borders.
+ */
+import { useEffect, useState } from "react"
+import type { InstructionFile } from "./types"
+
+export interface InstructionsPanelProps {
+  /** Instruction files to display */
+  files: InstructionFile[]
+  /** Called when a file is edited and the textarea loses focus */
+  onSave: (name: string, content: string) => Promise<void>
+  /** Title for empty state */
+  emptyTitle?: string
+  /** Description for empty state */
+  emptyDescription?: string
+}
+
+export function InstructionsPanel({
+  files,
+  onSave,
+  emptyTitle = "No instructions yet",
+  emptyDescription = "Add a CLAUDE.md to this workspace to configure how the agent behaves.",
+}: InstructionsPanelProps) {
+  if (files.length === 0) {
+    return (
+      <div className="flex-1 flex flex-col items-center pt-[20vh] gap-4 px-8">
+        <div className="space-y-2 text-center max-w-md">
+          <h1 className="text-2xl font-semibold text-foreground tracking-tight">
+            {emptyTitle}
+          </h1>
+          <p className="text-sm text-muted-foreground">{emptyDescription}</p>
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div className="flex-1 overflow-y-auto">
+      <div className="px-6 py-6">
+        <div className="space-y-4">
+          {files.map((file) => (
+            <InstructionField
+              key={file.name}
+              file={file}
+              onSave={(content) => onSave(file.name, content)}
+            />
+          ))}
+        </div>
+      </div>
+    </div>
+  )
+}
+
+function InstructionField({
+  file,
+  onSave,
+}: {
+  file: InstructionFile
+  onSave: (content: string) => Promise<void>
+}) {
+  const [value, setValue] = useState(file.content)
+  const [saving, setSaving] = useState(false)
+
+  useEffect(() => {
+    setValue(file.content)
+  }, [file.content])
+
+  const handleBlur = async () => {
+    if (value !== file.content) {
+      setSaving(true)
+      await onSave(value)
+      setSaving(false)
+    }
+  }
+
+  return (
+    <div className="space-y-1.5">
+      <label className="text-xs font-medium text-muted-foreground/50 px-1 flex items-center gap-2">
+        {file.label}
+        {saving && (
+          <span className="text-[10px] text-muted-foreground/30">
+            Saving...
+          </span>
+        )}
+      </label>
+      <textarea
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+        onBlur={handleBlur}
+        rows={Math.max(4, value.split("\n").length + 1)}
+        className="w-full text-sm text-foreground leading-relaxed bg-[#f9f9f9] outline-none rounded-xl px-4 py-3 border border-black/[0.04] hover:border-black/[0.1] focus:border-black/[0.15] focus:bg-white transition-all duration-200 resize-none placeholder:text-muted-foreground/30"
+      />
+    </div>
+  )
+}

package/src/new-folder-input.tsx

@@ -0,0 +1,52 @@
+/**
+ * Inline new-folder input, styled as a selected folder row.
+ */
+import { useRef, useState } from "react"
+import { FolderIcon, DisclosureChevron } from "./finder-icons"
+import { COL_GRID } from "./file-row"
+
+export function NewFolderInput({ onConfirm, onCancel }: {
+  onConfirm: (name: string) => void
+  onCancel: () => void
+}) {
+  const [value, setValue] = useState("")
+  const committed = useRef(false)
+
+  const commit = () => {
+    if (committed.current) return
+    const trimmed = value.trim()
+    if (trimmed) {
+      committed.current = true
+      onConfirm(trimmed)
+    } else {
+      onCancel()
+    }
+  }
+
+  return (
+    <div
+      className="h-[24px] bg-[#2068d0] rounded-lg items-center"
+      style={{ display: "grid", gridTemplateColumns: COL_GRID }}
+    >
+      <div className="flex items-center gap-1.5 min-w-0 pl-3">
+        <DisclosureChevron open={false} className="invisible" />
+        <FolderIcon />
+        <input
+          autoFocus
+          value={value}
+          onChange={(e) => setValue(e.target.value)}
+          onKeyDown={(e) => {
+            if (e.key === "Enter") commit()
+            if (e.key === "Escape") onCancel()
+          }}
+          onBlur={commit}
+          placeholder="untitled folder"
+          className="flex-1 text-[13px] bg-transparent text-white outline-none placeholder:text-white/50 min-w-0"
+        />
+      </div>
+      <span />
+      <span />
+      <span className="text-[11px] text-white/70 px-2">Folder</span>
+    </div>
+  )
+}

package/src/tree.ts

@@ -0,0 +1,79 @@
+/**
+ * Tree types and builder for the FilesBrowser hierarchy.
+ * Converts a flat list of FileEntry (with relative paths) into a nested tree.
+ */
+import type { FileEntry } from "./types"
+
+export interface FolderNode {
+  kind: "folder"
+  name: string
+  /** Relative path from workspace root (e.g. "2025/Investments - Fidelity") */
+  path: string
+  children: TreeNode[]
+}
+
+export interface FileNode {
+  kind: "file"
+  entry: FileEntry
+}
+
+export type TreeNode = FolderNode | FileNode
+
+/**
+ * Convert a flat list of FileEntry (with relative paths) into a tree.
+ * Path separators are "/" (as produced by the Rust backend).
+ *
+ * Example: ["2025/Investments - Fidelity/statement.pdf", "2025/W2.pdf"]
+ * Produces: root → 2025 → [Investments - Fidelity → [statement.pdf], W2.pdf]
+ */
+export function buildTree(files: FileEntry[]): FolderNode {
+  const root: FolderNode = { kind: "folder", name: "", path: "", children: [] }
+
+  for (const file of files) {
+    // Directory entries become folder nodes directly
+    if (file.is_directory) {
+      const parts = file.path.split("/")
+      let node = root
+      for (const segment of parts) {
+        let child = node.children.find(
+          (c): c is FolderNode => c.kind === "folder" && c.name === segment,
+        )
+        if (!child) {
+          const folderPath = parts.slice(0, parts.indexOf(segment) + 1).join("/")
+          child = { kind: "folder", name: segment, path: folderPath, children: [] }
+          node.children.push(child)
+        }
+        node = child
+      }
+      continue
+    }
+
+    const parts = file.path.split("/")
+    let node = root
+    for (let i = 0; i < parts.length - 1; i++) {
+      const segment = parts[i]
+      const folderPath = parts.slice(0, i + 1).join("/")
+      let child = node.children.find(
+        (c): c is FolderNode => c.kind === "folder" && c.name === segment,
+      )
+      if (!child) {
+        child = { kind: "folder", name: segment, path: folderPath, children: [] }
+        node.children.push(child)
+      }
+      node = child
+    }
+    node.children.push({ kind: "file", entry: file })
+  }
+
+  return root
+}
+
+/** Count all file descendants of a folder node (recursively). */
+export function countFiles(node: FolderNode): number {
+  let count = 0
+  for (const child of node.children) {
+    if (child.kind === "file") count++
+    else count += countFiles(child)
+  }
+  return count
+}

package/src/types.ts

@@ -0,0 +1,27 @@
+// --- Files browser ---
+
+export interface FileEntry {
+  /** Relative path from workspace root (e.g., "docs/readme.md") */
+  path: string
+  /** File name with extension */
+  name: string
+  /** File extension without dot (e.g., "md", "pdf") */
+  extension: string
+  /** File size in bytes */
+  size: number
+  /** Whether this entry is a directory */
+  is_directory?: boolean
+  /** Last modified timestamp in milliseconds (Date.now() format) */
+  dateModified?: number
+}
+
+// --- Instructions panel ---
+
+export interface InstructionFile {
+  /** File name (e.g., "CLAUDE.md") */
+  name: string
+  /** Human-readable label shown above the field (e.g., "CLAUDE.md") */
+  label: string
+  /** Current file content */
+  content: string
+}

package/src/utils.ts

@@ -0,0 +1,132 @@
+/**
+ * Finder-style formatting and sorting utilities.
+ */
+import type { FolderNode, FileNode } from "./tree"
+
+/** Format bytes like Finder (SI units: 1000, not 1024). */
+export function formatSize(bytes: number): string {
+  if (bytes === 0) return "Zero bytes"
+  if (bytes < 1000) return `${bytes} bytes`
+  if (bytes < 1000000) return `${Math.round(bytes / 1000)} KB`
+  if (bytes < 1000000000) return `${(bytes / 1000000).toFixed(1)} MB`
+  return `${(bytes / 1000000000).toFixed(1)} GB`
+}
+
+/** Format a timestamp like Finder: "Today at 3:24 PM", "Yesterday", "Apr 3 at 2:30 PM". */
+export function formatFinderDate(timestamp?: number): string {
+  if (!timestamp) return "\u2014"
+  const date = new Date(timestamp)
+  const now = new Date()
+  const today = new Date(now.getFullYear(), now.getMonth(), now.getDate())
+  const yesterday = new Date(today.getTime() - 86400000)
+  const time = date.toLocaleTimeString("en-US", {
+    hour: "numeric",
+    minute: "2-digit",
+  })
+  if (date >= today) return `Today at ${time}`
+  if (date >= yesterday) return `Yesterday at ${time}`
+  if (date.getFullYear() === now.getFullYear()) {
+    return (
+      date.toLocaleDateString("en-US", { month: "short", day: "numeric" }) +
+      ` at ${time}`
+    )
+  }
+  return date.toLocaleDateString("en-US", {
+    month: "short",
+    day: "numeric",
+    year: "numeric",
+  })
+}
+
+const KIND_MAP: Record<string, string> = {
+  pdf: "PDF Document",
+  md: "Markdown",
+  txt: "Plain Text",
+  rtf: "Rich Text Document",
+  png: "PNG Image",
+  jpg: "JPEG Image",
+  jpeg: "JPEG Image",
+  gif: "GIF Image",
+  svg: "SVG Image",
+  webp: "WebP Image",
+  heic: "HEIC Image",
+  mp3: "MP3 Audio",
+  wav: "WAV Audio",
+  aac: "AAC Audio",
+  mp4: "MPEG-4 Movie",
+  mov: "QuickTime Movie",
+  json: "JSON",
+  js: "JavaScript",
+  ts: "TypeScript",
+  tsx: "TypeScript JSX",
+  jsx: "JavaScript JSX",
+  css: "CSS Stylesheet",
+  html: "HTML Document",
+  xml: "XML Document",
+  yaml: "YAML",
+  yml: "YAML",
+  toml: "TOML",
+  rs: "Rust Source",
+  py: "Python Script",
+  go: "Go Source",
+  rb: "Ruby Script",
+  sh: "Shell Script",
+  zip: "ZIP Archive",
+  gz: "GZ Archive",
+  tar: "Tar Archive",
+  dmg: "Apple Disk Image",
+  xlsx: "Excel Spreadsheet",
+  xls: "Excel Spreadsheet",
+  csv: "CSV Document",
+  doc: "Word Document",
+  docx: "Word Document",
+}
+
+/** Get Finder-style "Kind" string from file extension. */
+export function getKind(extension: string): string {
+  return KIND_MAP[extension.toLowerCase()] || `${extension.toUpperCase()} File`
+}
+
+// --- Sort ---
+
+export type SortKey = "name" | "dateModified" | "size" | "kind"
+export type SortDirection = "asc" | "desc"
+
+/** Recursively sort a tree (folders first, then by selected column). */
+export function sortTree(
+  node: FolderNode,
+  key: SortKey,
+  direction: SortDirection,
+): FolderNode {
+  const sorted = [...node.children].sort((a, b) => {
+    if (a.kind !== b.kind) return a.kind === "folder" ? -1 : 1
+    if (a.kind === "folder" && b.kind === "folder") {
+      const cmp = a.name.localeCompare(b.name)
+      return direction === "asc" ? cmp : -cmp
+    }
+    const fa = (a as FileNode).entry
+    const fb = (b as FileNode).entry
+    let cmp = 0
+    switch (key) {
+      case "name":
+        cmp = fa.name.localeCompare(fb.name)
+        break
+      case "dateModified":
+        cmp = (fa.dateModified ?? 0) - (fb.dateModified ?? 0)
+        break
+      case "size":
+        cmp = fa.size - fb.size
+        break
+      case "kind":
+        cmp = getKind(fa.extension).localeCompare(getKind(fb.extension))
+        break
+    }
+    return direction === "asc" ? cmp : -cmp
+  })
+  return {
+    ...node,
+    children: sorted.map((c) =>
+      c.kind === "folder" ? sortTree(c, key, direction) : c,
+    ),
+  }
+}