@lijian-ui/dsh-file-manager 0.1.20

package/src/client/drag.ts

@@ -0,0 +1,154 @@
+/**
+ * Framework-free drag machinery shared by the React hook (useResizableSplit)
+ * and the DOM layout controller: one pointer-down handler that owns capture,
+ * the rAF-flush loop, the e.buttons === 0 fallback, every end path, and the
+ * drag styles. Pure DOM — no React, so both callers run the exact same
+ * smoothness core (FileManager's useResizableSplit architecture, re-implemented).
+ * @module dsh-filemgr/client/drag
+ */
+
+export interface DragStartOptions {
+  /** Drag left = grow (handle on the left edge of its container). */
+  reverse: boolean
+  /** Width at drag start (read at pointer-down time). */
+  getStartWidth: () => number
+  /** Clamped width from the raw delta (px mode adds deltaX directly). */
+  compute: (startWidth: number, deltaX: number) => number
+  /** Per-frame flush (rAF-merged; called at most once per frame). */
+  onFrame: (width: number) => void
+  /** Final commit (also fired on every end path). */
+  onEnd: (width: number) => void
+}
+
+/** Whether a pointer event is the primary (left) button or touch. */
+function isPrimaryPointer(event: PointerEvent): boolean {
+  return event.pointerType === 'touch' || event.button === 0
+}
+
+/**
+ * Handle one pointer-down: wire capture + window listeners, run the rAF
+ * loop, and end on any of the five termination paths. Call from a
+ * onPointerDown handler (React or plain DOM).
+ * @param event - the raw pointerdown event.
+ * @param el - the handle element (capture target + reverse marker source).
+ * @param opts - drag behavior.
+ * @returns a disposer (idempotent; also called internally on end).
+ */
+export function handlePointerDragStart(event: PointerEvent, el: HTMLElement, opts: DragStartOptions): () => void {
+  if (!isPrimaryPointer(event)) return () => {}
+  event.preventDefault()
+
+  const startX = event.clientX
+  const startWidth = opts.getStartWidth()
+  const pointerId = event.pointerId
+  const reverse = opts.reverse
+
+  let rafId: number | null = null
+  let pendingWidth: number | null = null
+  let latestWidth = startWidth
+  let isDragging = true
+  let cleanup: (() => void) | null = null
+
+  const flushPending = (): void => {
+    if (pendingWidth === null) return
+    latestWidth = pendingWidth
+    opts.onFrame(pendingWidth)
+  }
+
+  const addWindowListener = <K extends keyof WindowEventMap>(
+    key: K,
+    handler: (e: WindowEventMap[K]) => void,
+  ): (() => void) => {
+    window.addEventListener(key, handler)
+    return () => window.removeEventListener(key, handler)
+  }
+
+  const computeWidth = (clientX: number): number => {
+    const deltaX = reverse ? startX - clientX : clientX - startX
+    return opts.compute(startWidth, deltaX)
+  }
+
+  const finishDrag = (e?: PointerEvent | MouseEvent | FocusEvent): void => {
+    if (!isDragging) return
+    isDragging = false
+    if (rafId !== null) {
+      cancelAnimationFrame(rafId)
+      rafId = null
+    }
+    flushPending()
+    let finalWidth = latestWidth
+    if (e !== undefined && 'clientX' in e && typeof e.clientX === 'number') {
+      finalWidth = computeWidth(e.clientX)
+    }
+    opts.onEnd(finalWidth)
+    cleanup?.()
+  }
+
+  const handlePointerMove = (e: PointerEvent): void => {
+    if (!isDragging) return
+    if (e.buttons === 0) {
+      // Lost pointerup (capture steal / release outside): end now.
+      finishDrag(e)
+      return
+    }
+    pendingWidth = computeWidth(e.clientX)
+    if (rafId === null) {
+      rafId = requestAnimationFrame(() => {
+        rafId = null
+        flushPending()
+      })
+    }
+  }
+  const handlePointerUp = (e: PointerEvent): void => finishDrag(e)
+  const handlePointerCancel = (e: PointerEvent): void => finishDrag(e)
+  const handleMouseUp = (e: MouseEvent): void => finishDrag(e)
+  const handleLostCapture = (): void => finishDrag()
+
+  // Drag styles: no text selection, col-resize cursor, disable transitions.
+  const previousUserSelect = document.body.style.userSelect
+  const previousCursor = document.body.style.cursor
+  document.body.style.userSelect = 'none'
+  document.body.style.cursor = 'col-resize'
+  const frame = el.closest('[data-dsh-frame]')
+  frame?.setAttribute('data-filemgr-instant', '')
+
+  const restore = (): void => {
+    document.body.style.userSelect = previousUserSelect
+    document.body.style.cursor = previousCursor
+    frame?.removeAttribute('data-filemgr-instant')
+  }
+
+  if (el.setPointerCapture) {
+    try {
+      el.setPointerCapture(pointerId)
+      el.addEventListener('lostpointercapture', handleLostCapture)
+    } catch {
+      // capture failed; the window listeners cover the drag
+    }
+  }
+
+  const releaseCapture = (): void => {
+    try {
+      if (el.releasePointerCapture && el.hasPointerCapture?.(pointerId)) {
+        el.releasePointerCapture(pointerId)
+      }
+    } catch {
+      // already released
+    }
+    el.removeEventListener('lostpointercapture', handleLostCapture)
+  }
+
+  const listeners = [
+    addWindowListener('pointermove', handlePointerMove),
+    addWindowListener('pointerup', handlePointerUp),
+    addWindowListener('pointercancel', handlePointerCancel),
+    addWindowListener('mouseup', handleMouseUp),
+    addWindowListener('blur', () => finishDrag()),
+  ]
+  cleanup = () => {
+    restore()
+    releaseCapture()
+    for (const dispose of listeners) dispose()
+  }
+  return cleanup
+}

package/src/client/file-source.ts

@@ -0,0 +1,58 @@
+/**
+ * The `file` input-trigger source: registers the reference codec the shell's
+ * submit pipeline needs to serialize a file chip (`slash: no serializer for
+ * reference source "file"` disappears once this source is in the roster).
+ *
+ * The source is deliberately INERT as a menu participant: the file picker is
+ * our own pi-desktop-style tree modal (see picker/FilePickerModal.tsx), not
+ * the shell's flat trigger menu, so `candidates` returns nothing and `onPick`
+ * never fires. Its only jobs are (1) to be findable by
+ * `inputTriggers.serializeReference('file', ref)` and (2) to own the model
+ * projection of a chip — the `@path:lines` plain-text token.
+ *
+ * Trigger '@' keeps the chip family visually consistent with the other '@'
+ * sources; the menu group this source contributes is empty and is covered by
+ * the picker modal the moment a bare `@` lands.
+ * @module dsh-filemgr/client/file-source
+ */
+
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+import type { InputTriggerSource } from '@deepseek-ai/dsh-client-ui-input-trigger/client'
+
+/** The roster name the chip occurrences address (see reference.ts). */
+export const FILE_SOURCE_NAME = 'file'
+
+/** Required services: the trigger roster plus the session scope carrier. */
+export const inject = ['inputTriggers']
+
+/**
+ * Register the inert `file` reference source (codec only). Safe to call
+ * multiple times (each call returns a disposer; the roster rejects a
+ * duplicate (trigger, name) seat, so guard with a module flag).
+ */
+export function registerFileReferenceSource(ctx: ClientContext): () => void {
+  // ctx.get — not property access: the caller (index.ts apply) does not
+  // declare 'inputTriggers' in its inject list, and property access would
+  // throw "cannot get property without inject". get() needs no inject.
+  const inputTriggers = (ctx.get as (name: string) => unknown)('inputTriggers') as
+    | { registerSource(src: InputTriggerSource): () => void }
+    | undefined
+  if (inputTriggers === undefined) return () => {}
+  const source: InputTriggerSource = {
+    trigger: '@',
+    name: FILE_SOURCE_NAME,
+    candidates: async () => [],
+    onPick: () => undefined,
+    codec: {
+      clipboardText: (ref) => ref,
+      serialize: (ref, _signal) => Promise.resolve(ref),
+    },
+  }
+  try {
+    return inputTriggers.registerSource(source)
+  } catch (error) {
+    // Duplicate registration (HMR remount) is not a failure.
+    console.warn('[dsh-filemgr] file reference source already registered:', error)
+    return () => {}
+  }
+}

package/src/client/fileType.ts

@@ -0,0 +1,129 @@
+/**
+ * Preview content-type detection from a file name — the router's single
+ * source of truth for what a file becomes when opened (mirrors FileManager's
+ * getFileTypeInfo table, re-derived for the panel's format set).
+ * @module dsh-filemgr/client/fileType
+ */
+
+import type { PreviewContentType } from '../core/types.ts'
+
+/** Markdown extensions. */
+const MARKDOWN_EXT = new Set(['md', 'markdown', 'mdx'])
+/** HTML extensions. */
+const HTML_EXT = new Set(['html', 'htm', 'xhtml'])
+/** Diff extensions. */
+const DIFF_EXT = new Set(['diff', 'patch'])
+/** CSV. */
+const CSV_EXT = new Set(['csv'])
+/** PDF. */
+const PDF_EXT = new Set(['pdf'])
+/** Office documents. */
+const WORD_EXT = new Set(['doc', 'docx', 'odt', 'rtf'])
+const EXCEL_EXT = new Set(['xls', 'xlsx', 'ods'])
+const PPT_EXT = new Set(['ppt', 'pptx', 'odp'])
+/** Images. */
+const IMAGE_EXT = new Set(['png', 'jpg', 'jpeg', 'gif', 'webp', 'svg', 'ico', 'bmp', 'avif'])
+/** Extensions treated as editable code/text. */
+const CODE_EXT = new Set([
+  'ts', 'tsx', 'js', 'jsx', 'mjs', 'cjs', 'json', 'jsonc', 'css', 'scss', 'less',
+  'yml', 'yaml', 'toml', 'xml', 'sh', 'bash', 'zsh', 'fish', 'rs', 'py', 'go',
+  'java', 'c', 'h', 'cpp', 'hpp', 'cc', 'cs', 'sql', 'php', 'rb', 'swift', 'kt',
+  'vue', 'svelte', 'astro', 'txt', 'log', 'ini', 'env', 'conf', 'cfg', 'gitignore',
+  'dockerfile', 'makefile', 'graphql', 'proto', 'prisma', 'zig', 'lua', 'r', 'dart',
+  'ex', 'exs', 'erl', 'hs', 'clj', 'scala', 'groovy', 'vb', 'ps1', 'bat', 'cmd',
+  'pl', 'pm', 'tcl', 'asm', 's', 'f', 'f90', 'jl', 'nim', 'ml', 'elm', 'purs',
+  'solidity', 'sol', 'tf', 'hcl', 'dockerignore', 'editorconfig', 'prettierrc',
+  'eslintrc', 'babelrc', 'npmrc', 'nix', 'lock', 'map',
+])
+/** No-extension names that are plain text. */
+const TEXT_NAMES = new Set([
+  'license', 'licence', 'readme', 'changelog', 'contributing', 'authors', 'notice',
+  'makefile', 'dockerfile', 'justfile', 'gemfile', 'rakefile', 'procfile',
+])
+/**
+ * Leading-dot config dotfiles whose full (dotted) basename is plain text. The
+ * de-dot rule below maps most single-dot files (`.gitignore` -> ext `gitignore`)
+ * into CODE_EXT; these multi-suffix / uncommon ones have no useful extension
+ * (`.env.local` -> `local`), so we match them by their whole dotted name.
+ */
+const DOTFILE_TEXT_NAMES = new Set([
+  '.gitignore', '.gitattributes', '.gitmodules', '.env', '.env.local',
+  '.env.production', '.env.development', '.env.test', '.npmrc', '.npmrc.template',
+  '.prettierrc', '.prettierrc.json', '.prettierrc.yaml', '.babelrc', '.babelrc.json',
+  '.eslintrc', '.eslintrc.json', '.eslintrc.js', '.editorconfig', '.dockerignore',
+  '.eslintignore', '.prettierignore', '.gitignore.local', '.hgignore',
+])
+
+/** Detect the preview content type of a file by name (lowercased). */
+export function detectContentType(name: string): PreviewContentType {
+  const base = name.split('/').pop() ?? name
+  const lower = base.toLowerCase()
+  const dot = lower.lastIndexOf('.')
+  // Leading-dot files: the first dot is the hidden-file marker, not a
+  // separator — take the text after it (`.gitignore` -> `gitignore`).
+  const ext = lower[0] === '.'
+    ? (dot > 0 ? lower.slice(dot + 1) : lower.slice(1))
+    : (dot > 0 ? lower.slice(dot + 1) : '')
+  const stem = dot > 0 ? lower.slice(0, dot) : lower
+  if (lower[0] === '.' && DOTFILE_TEXT_NAMES.has(lower)) return 'text'
+  if (ext === '' && TEXT_NAMES.has(stem)) return 'text'
+  if (ext === '') return 'unsupported'
+  if (MARKDOWN_EXT.has(ext)) return 'markdown'
+  if (HTML_EXT.has(ext)) return 'html'
+  if (DIFF_EXT.has(ext)) return 'diff'
+  if (CSV_EXT.has(ext)) return 'csv'
+  if (PDF_EXT.has(ext)) return 'pdf'
+  if (WORD_EXT.has(ext)) return 'word'
+  if (EXCEL_EXT.has(ext)) return 'excel'
+  if (PPT_EXT.has(ext)) return 'ppt'
+  if (IMAGE_EXT.has(ext)) return 'image'
+  if (CODE_EXT.has(ext)) return 'code'
+  return 'unsupported'
+}
+
+/** Whether the type can be edited and saved back. */
+export function isEditableType(type: PreviewContentType): boolean {
+  return type === 'markdown' || type === 'html' || type === 'code' || type === 'csv' || type === 'text'
+}
+
+/** Whether the type reads its content as text (vs image data URL). */
+export function isTextType(type: PreviewContentType): boolean {
+  return type !== 'image' && type !== 'pdf' && type !== 'word' && type !== 'excel'
+    && type !== 'ppt' && type !== 'unsupported' && type !== 'url'
+}
+
+/** A stable tab id from the file identity (root + path + type). */
+export function tabIdOf(root: string, path: string, type: PreviewContentType): string {
+  return `${root}\u0000${path}\u0000${type}`
+}
+
+/** The language hint for code tabs (extension without the dot). */
+export function languageOf(name: string): string {
+  const base = name.split('/').pop() ?? name
+  const dot = base.lastIndexOf('.')
+  return dot > 0 ? base.slice(dot + 1) : ''
+}
+
+/** The title for a tab: the basename. */
+export function basenameOf(path: string): string {
+  const parts = path.split('/')
+  return parts[parts.length - 1] ?? path
+}
+
+/** The parent relative path of a path ('' for a root-level item). */
+export function parentRel(path: string): string {
+  const idx = path.lastIndexOf('/')
+  return idx > 0 ? path.slice(0, idx) : ''
+}
+
+/**
+ * The streaming URL a pdf tab renders: the host raw route serves the bytes
+ * with mime application/pdf, so the preview iframe loads them directly — no
+ * base64 round-trip and no read-size cap. The nonce defeats browser caching
+ * when the tab is refreshed after the file changed on disk.
+ *
+ * Contributed by EricWang1358 (#239).
+ */
+export function pdfPreviewUrl(root: string, path: string, nonce: number): string {
+  return `/filemgr/raw?root=${encodeURIComponent(root)}&path=${encodeURIComponent(path)}&v=${nonce}`
+}

package/src/client/floating.ts

@@ -0,0 +1,63 @@
+/**
+ * Floating expand button geometry (issues #374 / #292): the button is a
+ * fixed chrome element docked at the viewport's top-right corner, just
+ * below the shell conversation header — the horizontal divider under the
+ * "Session log" row — so the re-expand control sits below the header
+ * chrome instead of overlapping it. Its top stays below the Window
+ * Controls Overlay titlebar strip when dsh-desktop reports one (issue
+ * #292). Every computed position is clamped into the usable range.
+ * @module dsh-filemgr/client/floating
+ */
+
+/** Breathing room above/below the button (px). */
+export const FLOATING_MARGIN_PX = 6
+/** Gap between the shell header's bottom divider and the button top (px). */
+export const FLOATING_HEADER_GAP_PX = 8
+/** The button's rendered size (kept in sync with tokens.module.css). */
+export const FLOATING_BUTTON_HEIGHT_PX = 24
+/** Top offset of the explorer's collapse chevron inside its tab bar (px).
+ * Used only as a fallback when the shell conversation header is not found
+ * (kept in sync with the chevron rule in tokens.module.css). */
+export const COLLAPSE_CHEVRON_TOP_PX = 6
+
+/** Minimal Window Controls Overlay surface (untyped in older TS DOM libs). */
+interface WindowControlsOverlayLike {
+  visible: boolean
+  getTitlebarAreaRect?: () => { height?: number }
+}
+
+/** The WCO titlebar height when visible; 0 in a plain browser tab. */
+export function titlebarAreaHeight(): number {
+  const wco = (navigator as Navigator & { windowControlsOverlay?: WindowControlsOverlayLike }).windowControlsOverlay
+  if (wco === undefined || !wco.visible || wco.getTitlebarAreaRect === undefined) return 0
+  try {
+    const rect = wco.getTitlebarAreaRect()
+    const height = rect?.height ?? 0
+    return height > 0 ? Math.round(height) : 0
+  } catch {
+    return 0
+  }
+}
+
+/** Clamp a requested top px into the usable vertical range. */
+export function clampFloatingTop(
+  top: number,
+  viewportHeight: number,
+  buttonHeight: number,
+  titlebar: number,
+): number {
+  const min = titlebar + FLOATING_MARGIN_PX
+  const max = Math.max(min, viewportHeight - buttonHeight - FLOATING_MARGIN_PX)
+  if (!Number.isFinite(top)) return min
+  return Math.min(max, Math.max(min, top))
+}
+
+/** The default top: aligned with the collapse chevron at the top-right. */
+export function topAlignedFloatingTop(viewportHeight: number, buttonHeight: number, titlebar: number): number {
+  return clampFloatingTop(
+    titlebar + COLLAPSE_CHEVRON_TOP_PX,
+    viewportHeight,
+    buttonHeight,
+    titlebar,
+  )
+}

package/src/client/hooks/useResizableSplit.ts

@@ -0,0 +1,91 @@
+/**
+ * The panel system's single drag engine hook — a thin React wrapper over the
+ * framework-free machinery in drag.ts (FileManager's useResizableSplit
+ * architecture, re-implemented): px or ratio units, range-validated
+ * localStorage persistence, double-click reset to the default width.
+ * @module dsh-filemgr/client/hooks/useResizableSplit
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+import type { PointerEvent as ReactPointerEvent } from 'react'
+import { handlePointerDragStart } from '../drag.ts'
+import { readStoredNumber, writeStoredNumber } from '../persist.ts'
+
+export interface UseResizableSplitOptions {
+  /** Default width (px or percent). */
+  defaultWidth?: number
+  /** Minimum (same unit). */
+  minWidth?: number
+  /** Maximum (same unit). */
+  maxWidth?: number
+  /** localStorage key (preference persistence). */
+  storageKey?: string
+  /** 'px' for fixed pixel widths, 'ratio' for percents (default 'ratio'). */
+  unit?: 'px' | 'ratio'
+}
+
+export interface DragHandleProps {
+  onPointerDown: (event: ReactPointerEvent<HTMLDivElement>) => void
+  onDoubleClick: () => void
+}
+
+/**
+ * Resizable-split engine.
+ * @param options - width contract + persistence key.
+ * @returns current width, the committed setter, handle props, and the clamp.
+ */
+export function useResizableSplit(options: UseResizableSplitOptions = {}) {
+  const {
+    defaultWidth = 50,
+    minWidth = 20,
+    maxWidth = 80,
+    storageKey,
+    unit = 'ratio',
+  } = options
+  const isPx = unit === 'px'
+
+  const [width, setWidthState] = useState(() =>
+    storageKey === undefined
+      ? defaultWidth
+      : readStoredNumber(storageKey, minWidth, maxWidth, defaultWidth))
+
+  // The pointer-down closure reads the width at drag START without rebinding.
+  const widthRef = useRef(width)
+  useEffect(() => {
+    widthRef.current = width
+  }, [width])
+
+  /** The committed setter: state + storage (validated) + resize event. */
+  const setWidth = useCallback((value: number) => {
+    setWidthState(value)
+    if (storageKey !== undefined) writeStoredNumber(storageKey, value)
+    try {
+      window.dispatchEvent(new CustomEvent('preview-panel-resize', { detail: { width: value } }))
+    } catch {
+      // event dispatch is best-effort
+    }
+  }, [storageKey])
+
+  const clamp = useCallback((value: number): number => {
+    return Math.min(maxWidth, Math.max(minWidth, value))
+  }, [minWidth, maxWidth])
+
+  const handlePointerDown = useCallback((event: ReactPointerEvent<HTMLDivElement>) => {
+    const el = event.currentTarget as HTMLDivElement
+    handlePointerDragStart(event.nativeEvent, el, {
+      reverse: el.dataset.reverse === 'true',
+      getStartWidth: () => widthRef.current,
+      compute: (startWidth, deltaX) => clamp(startWidth + deltaX),
+      onFrame: (value) => setWidthState(value),
+      onEnd: (value) => setWidth(value),
+    })
+  }, [clamp, setWidth])
+
+  const handleDoubleClick = useCallback(() => {
+    setWidth(defaultWidth)
+  }, [defaultWidth, setWidth])
+
+  const handleProps: DragHandleProps = { onPointerDown: handlePointerDown, onDoubleClick: handleDoubleClick }
+
+  return { width, setWidth, handleProps, clamp, isPx }
+}

package/src/client/hooks/useStore.ts

@@ -0,0 +1,15 @@
+/**
+ * React bindings for the framework-free stores: useSyncExternalStore with a
+ * stable snapshot (the stores return immutable snapshots, so selector-free
+ * subscription is safe), plus a stable-callback helper for event handlers.
+ * @module dsh-filemgr/client/hooks/useStore
+ */
+
+import { useSyncExternalStore } from 'react'
+import type { StateHandle } from '../store.ts'
+
+/** Subscribe a component to one store (full snapshot). */
+export function useStore<S>(store: StateHandle<S>): S {
+  return useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot)
+}
+