dsh-coding-sidebar 1.0.0

package/lib/types/client/terminal-links.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Terminal URL hyperlinks: xterm's `registerLinkProvider` is fed per-line
+ * link descriptors built from the pty stream, so URLs printed by any tool
+ * become hoverable / clickable spans.
+ *
+ * To stay out of the user's way (a terminal's primary interaction is text
+ * selection, not browsing), a click only activates when the user holds
+ * Ctrl (Win/Linux) or Cmd (mac) — a plain click is left for xterm's
+ * normal selection handling. Only http(s) URLs are dispatched to the
+ * browser; other schemes (`file://`, `mailto:`, `javascript:`, …) are
+ * underlined for visibility but rejected at activation, so a `file://`
+ * URL printed by a tool stays inert instead of being handed to
+ * `window.open`.
+ *
+ * Kept as a pure module (no xterm import) so the regex, the line
+ * scanner, the modifier gate and the scheme guard are unit-testable
+ * without mounting a terminal. `buildTerminalLinks` returns plain-object
+ * descriptors whose shape matches xterm's `ILink` minus the `activate`
+ * callback — the caller attaches `activate` (which closes over the
+ * event modifier check + `openTerminalUrl`) so this module never
+ * imports xterm types.
+ */
+/**
+ * The URL pattern used to scan each terminal line.
+ *
+ * A word boundary (`\b`) guards the leading scheme so `notttps://…` does
+ * not match. The character class excludes ASCII whitespace and the
+ * wrapping punctuation that shells commonly emit around URLs (quotes,
+ * angle brackets, brackets/braces, pipes, backslashes, backticks) so a
+ * URL printed as `"https://example.com"` or `<https://example.com>` does
+ * not drag the wrapping character into the link target.
+ *
+ * Carries the `g` flag so `findTerminalUrlsInLine` can iterate every
+ * match on a line; callers must reset `lastIndex` before reuse (the
+ * helper does this defensively).
+ */
+export declare const TERMINAL_URL_REGEX: RegExp;
+/** A URL match in a terminal line: the text and its 0-based start offset. */
+export interface TerminalUrlMatch {
+    /** 0-based start index of the URL within the line string. */
+    start: number;
+    /** The matched URL text. */
+    text: string;
+}
+/**
+ * Find every http(s) URL in a line of terminal text, in source order
+ * with 0-based start offsets. A link provider maps these to buffer
+ * ranges for xterm's `registerLinkProvider`.
+ *
+ * Trailing unmatched closing parens are trimmed from each match (see
+ * {@link trimUnbalancedTrailingParens}), so a URL wrapped in parens by
+ * a shell opens without the trailing `)`, while Wikipedia-style URLs
+ * with balanced parens stay intact.
+ *
+ * Resets the regex's `lastIndex` before and after the scan so a
+ * previous partial iteration can't desynchronize a later one (the
+ * regex carries the `g` flag and is module-shared).
+ */
+export declare function findTerminalUrlsInLine(line: string): TerminalUrlMatch[];
+/**
+ * A buffer range in xterm's coordinate system. xterm's cell `x` is
+ * 1-based (1..cols) and `y` is the buffer line number; the `end` is
+ * inclusive (the last cell covered by the link). Structurally
+ * compatible with xterm's `IBufferRange` so the caller can pass it
+ * straight through without importing xterm types here.
+ */
+export interface TerminalLinkRange {
+    start: {
+        x: number;
+        y: number;
+    };
+    end: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * A link descriptor: a buffer range plus the URL text. The caller
+ * (the link provider in `TerminalView`) attaches the `activate`
+ * callback, which closes over the modifier gate and `openTerminalUrl`.
+ */
+export interface TerminalLinkDescriptor {
+    range: TerminalLinkRange;
+    text: string;
+}
+/**
+ * Build link descriptors for every URL found in a terminal line.
+ *
+ * @param lineText - the line's text (e.g. from
+ *   `IBufferLine.translateToString(true)`).
+ * @param lineNumber - the buffer line number xterm passed to
+ *   `ILinkProvider.provideLinks` (used as the `y` of every range; URLs
+ *   never span wrapped lines because each wrapped row is its own
+ *   buffer line).
+ * @returns descriptors in source order; empty when the line has no URL.
+ */
+export declare function buildTerminalLinks(lineText: string, lineNumber: number): TerminalLinkDescriptor[];
+/**
+ * Decide whether a click on a terminal link should activate (open the URL).
+ *
+ * Mirrors what every modern terminal does (Windows Terminal, iTerm2, the
+ * VSCode integrated terminal): a plain click stays a text-selection
+ * gesture, and only Ctrl (Win/Linux) or Cmd (mac) hands the URL to the
+ * browser. The modifier is read off the activating `MouseEvent`, not
+ * tracked separately, so a key-up between hover and click never
+ * desynchronizes the gate.
+ */
+export declare function shouldActivateTerminalLink(event: MouseEvent): boolean;
+/**
+ * Open a URL matched in the terminal, with a scheme guard so a printed
+ * `file://` or anything that slipped past the regex cannot reach
+ * `window.open`. The URL is constructed via `new URL(...)` which throws
+ * on malformed input; the catch makes the function total so the xterm
+ * handler never throws into the terminal's event loop.
+ *
+ * @returns `true` when the URL was dispatched to `window.open`, `false`
+ *   when it was rejected (bad URL, disallowed scheme, no `window`).
+ */
+export declare function openTerminalUrl(uri: string): boolean;

package/lib/types/client/theme.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Live theme access for surfaces that cannot consume the token colors
+ * directly — xterm's palette and CodeMirror's theme extensions need concrete
+ * values, but the app's scheme flips at runtime (ui-layout's ThemePresenter
+ * projects prefers-color-scheme and the user's choice onto
+ * body[data-ds-dark-theme] and html { color-scheme }). This module reads the
+ * resolved scheme and token values, and notifies subscribers on flips, so
+ * the terminal and the editor re-theme in place instead of freezing in the
+ * scheme they happened to be created under.
+ */
+/** Whether the app shell resolved to the dark scheme.
+ *
+ * The presenter sets `html { color-scheme }` together with the body palette
+ * attribute, so a set color-scheme means the decision is authoritative (an
+ * absent attribute is then LIGHT even when the OS prefers dark — the user
+ * chose light). Before the presenter has run, fall back to the OS media
+ * query as the best guess.
+ */
+export declare function isDarkScheme(): boolean;
+/** One token's computed value on <body> ('' while the theme has not applied). */
+export declare function tokenValue(name: string): string;
+/** The alpha channel of a computed CSS color, or null when the format is
+ *  not parseable (named colors, `color()`… — treated as opaque). Handles
+ *  the shapes getComputedStyle actually returns: the rgb()/rgba() and
+ *  hsl()/hsla() function forms (comma or space syntax, with or without the
+ *  `/ alpha` slot) and the #rgb/#rgba/#rrggbb/#rrggbbaa hex family. */
+export declare function colorAlpha(color: string): number | null;
+/**
+ * A token value that actually PAINTS something — the guard for text
+ * surfaces (issue #90). Skin systems routinely set global tokens to
+ * `transparent` (glass skins) or translucent glass values (`rgba(…,0.16–0.7)`,
+ * e.g. the dsh-web-ui skins) — both are truthy strings, so callers using
+ * `|| fallback` never fire and the terminal/editor goes see-through over
+ * the skin's backdrop. This returns '' for visually inert values (unset
+ * keywords, transparent, and any color below the opacity floor) so the
+ * caller's fallback chain engages; effectively opaque values pass through.
+ */
+export declare function effectiveTokenValue(name: string): string;
+/**
+ * Subscribe to color-scheme flips (the presenter toggles the body
+ * attribute). The callback fires after the attribute changed; re-read the
+ * scheme inside it.
+ * @returns the disposer.
+ */
+export declare function subscribeColorScheme(callback: () => void): () => void;

package/lib/types/client/titlebar-strip.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The title-bar strip resolution chain — the ONE place that decides how
+ * many pixels the sidebar yields at the top. Standard signals first, then
+ * the user's chosen scheme; never a per-shell branch:
+ *
+ *   0. `web` scheme — EXPLICIT "DSH official web": never adapt, not even
+ *      standard WCO geometry (the user declares the plain web UI).
+ *   1. Window Controls Overlay real geometry (standard API, authoritative
+ *      when present — even 0, e.g. the overlay is hidden while maximized).
+ *   2. The `dsh-desktop-titlebar-inset` URL contract parameter (a shell
+ *      declares the exact pixels it reserves).
+ *   3. The active shell preset's strip (scheme `preset` — opt-in data).
+ *   4. The legacy manual `titleBarStripPx` (scheme `custom`).
+ *   5. 0 — plain-browser semantics, nothing modified.
+ *
+ * The result drives `--dsh-title-bar-strip` + `body[data-dsh-title-bar-compat]`
+ * exactly like the legacy boolean did; only the VALUE source changed.
+ */
+import type { DesktopEnv } from './desktop-env.ts';
+import type { TitleBarScheme } from '../prefs-shared.ts';
+import type { WcoSnapshot } from './wco.ts';
+import { type ShellPreset } from './shell-presets.ts';
+export declare function computeTitleBarStrip(env: DesktopEnv, wco: WcoSnapshot, scheme: TitleBarScheme, preset: ShellPreset | undefined, customStripPx: number): number;

package/lib/types/client/upload.d.ts

@@ -0,0 +1,69 @@
+/**
+ * File-upload plumbing for the files window: turn a file picker or a drag-drop
+ * into per-file raw-byte uploads through the sidebar's `/sidebar/upload` route.
+ *
+ * Folders keep their tree in both flows: the picker's `webkitdirectory`
+ * selection arrives as Files with `webkitRelativePath` filled, and dropped
+ * folders — which never surface in `dataTransfer.files` — are traversed via
+ * `webkitGetAsEntry`, so the relative path is preserved for every nested file
+ * and the host recreates the tree under the chosen directory. The File is
+ * streamed straight into the POST body (no base64 inflation); uploads run
+ * sequentially so one slow file cannot starve the others, and each result
+ * reports its own outcome (the tree keeps going after a failure). An
+ * optional `AbortSignal` stops the queue at the next item boundary and
+ * aborts the in-flight request; the host cleans up its temp file when the
+ * request stream dies.
+ */
+import { type SessionScope } from './api.ts';
+import type { CopyKey } from './locales.ts';
+/** One pending file: the browser File plus the workspace-relative target path. */
+export interface UploadItem {
+    file: File;
+    relativePath: string;
+}
+/** One settled upload. */
+export interface UploadResult {
+    relativePath: string;
+    ok: boolean;
+    path?: string;
+    /** Wire error code when the host refused the upload ('too-large', ...). */
+    code?: string;
+    /** The host's error message (English wire text; localize via `code`). */
+    error?: string;
+}
+/** Collect a picker selection (webkitdirectory folders carry relative paths). */
+export declare function uploadItemsFromFiles(files: FileList | readonly File[]): UploadItem[];
+/**
+ * Collect a drag-drop payload. Dropped folders do NOT surface in
+ * `dataTransfer.files` — they arrive as directory items, so entries are
+ * captured via `webkitGetAsEntry` and traversed (draining readEntries
+ * batches), keeping each nested file's relative path. MUST be invoked
+ * synchronously from the drop handler: the dataTransfer enters protected
+ * mode once the event dispatch ends, while the captured entry handles stay
+ * readable asynchronously. Falls back to the flat file list when the entry
+ * API is unavailable; an entry that fails to read is skipped, not fatal.
+ */
+export declare function uploadItemsFromDrop(data: DataTransfer | undefined): Promise<UploadItem[]>;
+/**
+ * Client-side pre-check cap. Mirrors the host's default (config `uploadLimit`)
+ * only — the host enforces the real, configurable limit, so a lowered host
+ * limit surfaces as a `too-large` wire error, never as a silent pass.
+ */
+export declare const MAX_UPLOAD_BYTES: number;
+/** How long a success hint stays before fading (failures stay until the next action). */
+export declare const UPLOAD_HINT_MS = 3500;
+/**
+ * One-line upload progress text: 'Uploading into {dir}…' while no file is in
+ * flight, then 'Uploading {done}/{total}: {name}' per file. Shared by the tree
+ * hint and the full-window upload overlay.
+ */
+export declare function uploadHintText(done: number, total: number, current: string, dir: string, t: (key: CopyKey, params?: Record<string, string | number>) => string): string;
+/**
+ * Upload every item into `dir` (absolute, inside the session workspace),
+ * sequentially, reporting progress as `(done, total, currentRelativePath)`.
+ * Resolves with one result per item — never rejects; `signal.aborted` stops
+ * the queue at the next item boundary (completed items stay uploaded).
+ */
+export declare function uploadToDir(scope: SessionScope, dir: string, items: UploadItem[], onProgress?: (done: number, total: number, current: string) => void, signal?: AbortSignal): Promise<UploadResult[]>;
+/** Fold a result list into a one-line status for the tree hint. */
+export declare function summarizeResults(results: UploadResult[], t: (key: CopyKey, params?: Record<string, string | number>) => string): string;

package/lib/types/client/wco.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Reactive Window Controls Overlay geometry — the STANDARD web mechanism
+ * for frameless Chromium shells that draw the native caption buttons
+ * (minimize / maximize / close) OVER the web content (Electron
+ * `titleBarOverlay` on Windows; issue #257). Feature-detected: absent in
+ * plain browsers, macOS, Tauri etc., where the snapshot stays `NONE` and
+ * the sidebar adapts nothing — this is the conservative "auto" signal.
+ *
+ * The API reports the real titlebar rect (CSS px), which differs between
+ * shells and Electron versions (32 / 36 …), and fires `geometrychange`
+ * when the window maximizes / restores / moves — so the strip must be
+ * reactive, not memoized like the URL stamps.
+ *
+ * Module-level store so the Sidebar shell can subscribe via
+ * `useSyncExternalStore`; `setWcoSourceForTests` swaps the source for unit
+ * tests (no real API exists in jsdom/headless).
+ */
+export interface WcoSource {
+    readonly visible: boolean;
+    getTitlebarAreaRect(): {
+        readonly x: number;
+        readonly y: number;
+        readonly width: number;
+        readonly height: number;
+    };
+    addEventListener(type: 'geometrychange', listener: () => void): void;
+    removeEventListener(type: 'geometrychange', listener: () => void): void;
+}
+/** The current overlay geometry (present=false = API unavailable). */
+export interface WcoSnapshot {
+    readonly present: boolean;
+    readonly height: number;
+}
+/** Snapshot when the API is unavailable (plain browser / non-overlay shell). */
+export declare const WCO_NONE: WcoSnapshot;
+type Listener = () => void;
+/** Read the current snapshot (returns the frozen NONE when unavailable). */
+export declare function getWcoSnapshot(): WcoSnapshot;
+/**
+ * Subscribe to overlay geometry changes. Attaches to the real
+ * `navigator.windowControlsOverlay` on first subscribe; the disposer
+ * detaches the native listener when the last subscriber leaves.
+ */
+export declare function subscribeWco(onChange: Listener): () => void;
+/** Test hook: swap the geometry source (undefined = API unavailable). */
+export declare function setWcoSourceForTests(next: WcoSource | undefined): void;
+export {};

package/lib/types/config.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Serializable configuration and defaults for the sidebar host half. Loader
+ * schema validation normally fills defaults; {@link resolveSidebarConfig}
+ * applies the same defaults for direct callers that bypass the Loader.
+ * @module dsh-coding-sidebar/config
+ */
+import z from 'schemastery';
+import { type SidebarPrefs } from './prefs-shared.ts';
+export { SIDEBAR_PREFS_DEFAULTS, SIDEBAR_PREFS_NS, TERMINAL_FONT_SIZE_DEFAULT, TERMINAL_FONT_SIZE_MAX, TERMINAL_FONT_SIZE_MIN, TITLE_BAR_STRIP_DEFAULT, TITLE_BAR_STRIP_MAX, TITLE_BAR_STRIP_MIN, WIDTH_PERCENT_DEFAULT, WIDTH_PERCENT_MAX, WIDTH_PERCENT_MIN, type SidebarPrefs, } from './prefs-shared.ts';
+/** Tunable sidebar host limits (every field optional; defaults fill in). */
+export interface SidebarConfig {
+    /** Read cap of one text file (bytes); larger files return truncated. */
+    readLimit?: number;
+    /** Media route cap (bytes); larger binaries are refused. */
+    mediaLimit?: number;
+    /** Upload route cap (bytes); larger files are refused without touching disk. */
+    uploadLimit?: number;
+    /** Explorer row bound of one level. */
+    listLimit?: number;
+    /** Terminals per session. */
+    terminalsPerSession?: number;
+    /** How long a disconnected terminal process survives awaiting a reconnect. */
+    reconnectGraceMs?: number;
+    /**
+     * Terminal shell (absolute path or bare executable name) for BOTH the UI
+     * terminal tabs and the model-facing `terminal_*` tools. Empty = auto:
+     * POSIX follows `$SHELL` then the account login shell; Windows follows
+     * `DSH_SIDEBAR_SHELL`, then probes for `pwsh.exe`, then falls back to the
+     * inbox `powershell.exe` (5.1). Set it from `cordis.patch.yml` / profile
+     * plugin config, e.g. `config: { shell: /bin/zsh }`.
+     */
+    shell?: string;
+    /**
+     * Optional arguments passed to the shell executable. When non-empty these
+     * REPLACE the automatic platform defaults (POSIX `-l` / Windows none), so
+     * the deployment has full control over how the shell starts. When omitted
+     * the existing default behavior is kept.
+     */
+    shellArgs?: string[];
+}
+/** Schemastery schema for the plugin configuration. */
+export declare const Config: z<SidebarConfig>;
+/** Fully defaulted sidebar host settings. */
+export interface ResolvedSidebarConfig {
+    readLimit: number;
+    mediaLimit: number;
+    uploadLimit: number;
+    listLimit: number;
+    terminalsPerSession: number;
+    reconnectGraceMs: number;
+    /** The configured terminal shell; empty means the host auto-resolves it. */
+    shell: string;
+    /** Explicit shell arguments; empty means use the platform defaults. */
+    shellArgs: string[];
+}
+/**
+ * Apply direct-call defaults after Loader schema validation has normally run.
+ *
+ * @param config - Deployment-provided sidebar host settings.
+ * @returns Complete settings consumed by the host half.
+ */
+export declare function resolveSidebarConfig(config: SidebarConfig | undefined): ResolvedSidebarConfig;
+/** Schemastery schema for the user-facing preferences (validated by the settings service). */
+export declare const PrefsSchema: z<SidebarPrefs>;