dsh-coding-sidebar 1.0.0

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

@@ -0,0 +1,74 @@
+import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import { type SidebarPrefs } from '../prefs-shared.ts';
+import type { SidebarStore } from './state.ts';
+import type { BetterSidebarService, FileViewerDescriptor, SidebarSettingToggle, TabDescriptor } from './service.ts';
+/** Injected business face: the shared store (prefs cache) + the sidebar service (registries). */
+export interface SideCardSectionInjected {
+    store: SidebarStore;
+    service: BetterSidebarService;
+}
+/** Full section props: the runtime share plus the injected face. */
+export type SideCardSectionProps = PropsRuntime<'settings.section'> & SideCardSectionInjected;
+/**
+ * Merge one plugin-owned setting into a pluginSettings map (pure, v0.12.0+).
+ * Sequential merges are additive: each call spreads the map it was GIVEN,
+ * so building from the latest optimistic map keeps earlier keys intact
+ * (two same-tick writes must not drop each other).
+ */
+export declare function mergePluginSetting(pluginSettings: Record<string, Record<string, unknown>>, descriptorId: string, key: string, value: unknown): Record<string, Record<string, unknown>>;
+/**
+ * The body of a feature's secondary settings popup: one row (title/desc +
+ * control) per declared setting. Switches render the custom switch; text and
+ * number rows render a free-form / numeric input committed on blur/Enter
+ * (clamped to the declared min/max). Extracted so the rows are testable
+ * without opening the Modal (the Modal portal renders only while open).
+ */
+export declare function FeatureSettingsRows(props: {
+    toggles: readonly SidebarSettingToggle[];
+    prefs: SidebarPrefs;
+    onToggle: (toggle: SidebarSettingToggle, next: boolean) => void;
+    /** Commit one text/number row; returns the canonical value the row should
+     *  display (clamped for numbers, the current pref when the input is
+     *  invalid). Optional: rows with no handler keep their draft. */
+    onCommit?: (toggle: SidebarSettingToggle, raw: string) => string;
+    /** Commit one select row: the picked option's value (single) or the array
+     *  of picked values (`multi: true`). Optional: rows with no handler are
+     *  display-only. */
+    onSelectValue?: (toggle: SidebarSettingToggle, next: unknown) => void;
+    /** Explicit value source (v0.12.0+): when given, rows read their values
+     *  from it instead of the `prefs` face — plugin-owned rows read their
+     *  own blob, so a plugin key can never collide with (or silently read)
+     *  a host pref of the same name. (Named `valueSource`, not `valueOf`:
+     *  the latter collides with the inherited Object.prototype.valueOf.) */
+    valueSource?: (key: string) => unknown;
+}): import("react").JSX.Element;
+/**
+ * The secondary settings popup body of one feature (tab or viewer):
+ * - the host-prefs `toggles` rows, then the plugin-owned `pluginToggles`
+ *   rows (their values live in `pluginSettings[feature.id]`, projected onto
+ *   the prefs face so the shared row renderer reads them);
+ * - `settings.render` (custom panel) AFTER those rows when declared — the
+ *   custom panel is an extension of the row list, not a replacement, so a
+ *   feature can keep its declarative rows (e.g. the editor's
+ *   open-behavior picker) and still ship a custom configuration area.
+ */
+export declare function SettingsBody(props: {
+    feature: TabDescriptor | FileViewerDescriptor;
+    prefs: SidebarPrefs;
+    store: SidebarStore;
+    service: BetterSidebarService;
+    onToggle: (toggle: SidebarSettingToggle, next: boolean) => void;
+    onCommit: (toggle: SidebarSettingToggle, raw: string) => string;
+    onSelectValue: (toggle: SidebarSettingToggle, next: unknown) => void;
+    onPluginToggle: (toggle: SidebarSettingToggle, next: boolean) => void;
+    onPluginCommit: (toggle: SidebarSettingToggle, raw: string) => string;
+    onPluginSelectValue: (toggle: SidebarSettingToggle, next: unknown) => void;
+    onPluginWrite: (key: string, value: unknown) => void;
+    onClose: () => void;
+}): import("react").JSX.Element | null;
+/**
+ * Render the Side card preferences section.
+ * @param props - composed slot props (runtime share + injected store/service).
+ * @returns the section element tree.
+ */
+export declare function SideCardSection({ store, service }: SideCardSectionProps): import("react").JSX.Element;

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

@@ -0,0 +1,16 @@
+import type { Context } from '../context-types.ts';
+import type { SessionScope } from './api.ts';
+import type { SidebarTab } from './state.ts';
+/** The thread a tab is bound to (durable in tab.meta across refreshes). */
+export declare function sidechatThreadIdOf(tab: SidebarTab): string | undefined;
+/** Park a thread id for the NEXT sidechat openTab to reattach. */
+export declare function parkSidechatReopen(threadId: string): void;
+/** Consume the parked reopen target (undefined = mint a fresh thread tab). */
+export declare function consumeSidechatSeed(): string | undefined;
+/** One side conversation tab (one thread per tab, Codex-style). */
+export declare function SideChatView(props: {
+    ctx: Context;
+    scope: SessionScope;
+    tab: SidebarTab;
+    visible: boolean;
+}): React.ReactNode;

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

@@ -0,0 +1,6 @@
+import type { Context } from '../context-types.ts';
+import { type SidebarStore } from './state.ts';
+export declare function Sidebar(props: {
+    ctx: Context;
+    store: SidebarStore;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,16 @@
+import type { Context, SidebarSubagentAddress } from '../context-types.ts';
+/**
+ * The sidebar's Subagent topology page.
+ * @param props - current session id, whether the page is actually visible
+ *   (active tab + open panel), the client context, and an optional
+ *   jump-notify hook fired right before `openSubagent` (lets the sidebar
+ *   shell re-open the Subagent page after the conversation switch lands on
+ *   the child session).
+ * @returns the main agent's topology tree, or the empty/error/loading states.
+ */
+export declare function SubagentView(props: {
+    sessionId: string;
+    active: boolean;
+    ctx: Context;
+    onOpenChild?: (address: SidebarSubagentAddress) => void;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,54 @@
+/**
+ * The tab strip of one pane: tabs capped at TAB_MAX_WIDTH (ellipsized),
+ * overflow scrolls horizontally, a close button per tab, a four-way split
+ * button cluster, and the + menu that opens new tabs (explorer / git /
+ * terminal). Tabs are draggable; dropping onto another tab inserts before it,
+ * dropping on the strip background appends to this pane. Right-clicking a
+ * tab opens the tab context menu (float as a free window / close / close
+ * others / close to the left / close to the right, the close ones scoped to
+ * this pane).
+ */
+import { type ReactNode } from 'react';
+import type { SidebarTab } from './state.ts';
+/** One + menu option. */
+export interface NewTabOption {
+    id: string;
+    label: string;
+    disabled?: boolean;
+    /** Leading icon (Menu row). */
+    icon?: ReactNode;
+}
+/** Drag payload for tab moves (HTML5 DnD dataTransfer). */
+export declare const TAB_DRAG_TYPE = "application/x-dsh-tab";
+export interface TabDragPayload {
+    tabId: string;
+    paneId: string;
+}
+export declare function serializeDrag(payload: TabDragPayload): string;
+export declare function parseDrag(raw: string): TabDragPayload | null;
+export declare function TabBar(props: {
+    paneId: string;
+    tabs: SidebarTab[];
+    active: string | null;
+    onActivate: (tabId: string) => void;
+    onClose: (tabId: string) => void;
+    onNewTab: (optionId: string) => void;
+    newTabOptions: NewTabOption[];
+    /** Drop of a tab from any pane: (payload, insertBeforeTabId | null). */
+    onDropTab: (payload: TabDragPayload, before: string | null) => void;
+    /** Float a tab out as a free window (the tab context menu's entry; the
+     *  drag-to-conversation gesture is handled at the Sidebar shell level). */
+    onFloatTab: (tabId: string) => void;
+    /**
+     * Pin/unpin a terminal tab (v0.17.0+). Called with `'workspace'` or
+     * `'global'` to pin (the shell snapshots the home cwd), or `null` to
+     * unpin. Non-terminal tabs never trigger this callback. Optional: the
+     * menu hides the pin entry when unset (legacy callers).
+     */
+    onPinTab?: (tabId: string, scope: 'workspace' | 'global' | null) => void;
+    /** Icon resolver for tab labels (reads from the tab descriptor registry). */
+    getTabIcon?: (tab: SidebarTab) => ReactNode;
+    /** Badge resolver for tab labels (reads the descriptor's `badge`; the
+     *  resolver returns the rendered pill or null). */
+    getTabBadge?: (tab: SidebarTab) => ReactNode;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,24 @@
+import '@xterm/xterm/css/xterm.css';
+import { type SessionScope, type TerminalDepsStatus } from './api.ts';
+import { type SidebarStore } from './state.ts';
+/** The degraded-mode payload rendered by {@link TerminalDepsBanner}. */
+type TerminalDepsInfo = Extract<TerminalDepsStatus, {
+    ok: false;
+}>;
+export declare function TerminalView(props: {
+    scope: SessionScope;
+    tabId: string;
+    store: SidebarStore;
+}): import("react").JSX.Element;
+/**
+ * The node-pty dependency failure banner (issue #140): explains that the
+ * terminal's native dependency failed to load and shows the PASTEABLE repair
+ * command (bash / cmd / PowerShell) with a copy button — the user pastes it
+ * into a terminal where their DSH profile lives and runs it, then retries.
+ * Extracted as a standalone component for direct testing.
+ */
+export declare function TerminalDepsBanner(props: {
+    deps: TerminalDepsInfo;
+    onRetry: () => void;
+}): import("react").JSX.Element;
+export {};

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

@@ -0,0 +1,10 @@
+import type { FileViewerProps } from './service.ts';
+/**
+ * The sandbox tokens of the HTML preview iframe. NO allow-same-origin (the
+ * preview must stay in an opaque origin — with the route's own origin it
+ * could read session data) and NO allow-top-navigation (a previewed page
+ * must not hijack the GUI). The user can disable the sandbox per-feature
+ * in the side card settings (warned); the toggle below reflects it.
+ */
+export declare const HTML_IFRAME_SANDBOX = "allow-scripts allow-popups allow-downloads allow-modals";
+export declare function TextEditor(props: FileViewerProps): import("react").JSX.Element;

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

@@ -0,0 +1,24 @@
+import type { OpenWithTarget } from './open-with.ts';
+export declare function TreePanel(props: {
+    sessionId: string;
+    cwd: string | undefined;
+    expanded: string[];
+    revealed: string[];
+    onToggle: (path: string) => void;
+    onOpenFile: (path: string) => void;
+    /** File context-menu "open in a new tab" (passed through to FileTree). */
+    onOpenFileNewTab?: (path: string) => void;
+    /** File context-menu "open to the side" (passed through to FileTree). */
+    onOpenFileSide?: (path: string) => void;
+    /** The "open with" menu surface (passed through to FileTree; absent →
+     *  the whole section is hidden). */
+    openWithTargets?: OpenWithTarget[];
+    openWithPinned?: string[];
+    openWithSsh?: boolean;
+    onOpenWith?: (targetId: string, path: string) => void;
+    onToggleOpenWithPin?: (targetId: string) => void;
+    onReferenceFile: (path: string) => void;
+    /** Full-window presentation: the panel fills its host instead of docking
+     *  at a fixed width. */
+    full?: boolean;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,20 @@
+/**
+ * Full-window upload progress over the files tree: a blurred scrim (same mask
+ * token as the repo's Modal primitive) with a card showing the target
+ * directory, file-level progress, and a cancel button. Esc cancels too —
+ * clicking the scrim does not, so a stray click can never abort an upload.
+ * Rendered inside TreePanel (absolute inset-0), so it covers only the file
+ * window and never the conversation column.
+ */
+import { type ReactNode } from 'react';
+export declare function UploadOverlay(props: {
+    /** Absolute upload directory (the session workspace or a tree directory). */
+    dir: string;
+    done: number;
+    total: number;
+    /** Relative path of the file being uploaded ('' when none is in flight). */
+    current: string;
+    onCancel: () => void;
+    /** True while cancellation is in flight (disables the cancel button). */
+    cancelling?: boolean;
+}): ReactNode;

package/lib/types/client/add-plugin-modal.d.ts

@@ -0,0 +1,15 @@
+import type { BetterSidebarService } from './service.ts';
+/** Which extension point the modal is adding a plugin for. */
+export type PluginKind = 'tab' | 'viewer';
+/** The modal body: the GitHub topic button + the recommended plugin list
+ *  with per-entry jump/copy buttons (extracted for direct testing). */
+export declare function PluginListBody(props: {
+    service: BetterSidebarService;
+    kind: PluginKind;
+}): import("react").JSX.Element;
+/** The modal itself (mounted only while open — see the module comment). */
+export declare function AddPluginModal(props: {
+    service: BetterSidebarService;
+    onClose: () => void;
+    kind: PluginKind;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,275 @@
+import type { LastActivity } from '../subagent-activity.ts';
+import type { SidechatThreadInfo } from '../sidechat-core.ts';
+import type { BrowserProbeResult } from './browser.ts';
+/** One wire failure. */
+export declare class SidebarApiError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Explorer row (host fs-tree shape). */
+export interface FsEntry {
+    name: string;
+    path: string;
+    isDir: boolean;
+    hidden: boolean;
+    /** Whether the row is a symlink; `isDir` then describes the link's target. */
+    isSymlink: boolean;
+    /** For symlinks: the target is missing or unreadable (stat failed). */
+    broken: boolean;
+}
+/** Git status entry (host git shape). */
+export interface GitStatusEntry {
+    path: string;
+    xy: string;
+}
+/** Git status snapshot. */
+export interface GitStatusResult {
+    isRepo: boolean;
+    branch?: string;
+    entries: GitStatusEntry[];
+    /** True when the host capped `entries` (huge untracked set); the panel
+     *  shows a truncation notice instead of freezing (#369). */
+    truncated?: boolean;
+    root?: string;
+    repositories?: string[];
+}
+/** One linked Git checkout. */
+export interface GitWorktree {
+    path: string;
+    branch: string;
+    current: boolean;
+    changes: number;
+}
+/** One git log row. */
+export interface GitLogEntry {
+    /** Short hash (7+ chars, display). */
+    hash: string;
+    /** Full 40-char hash (advanced operations). */
+    hashFull: string;
+    subject: string;
+    author: string;
+    /** ISO 8601 author date (`%ai`). */
+    date: string;
+    /** Ref decorations (--decorate=short), e.g. `HEAD -> main, origin/main`; '' when none. */
+    refs: string;
+}
+/** Text read result. */
+export interface FsTextResult {
+    kind: 'text';
+    content: string;
+    truncated: boolean;
+}
+/** Binary read result (no content; images load through the media route).
+ *  `head` carries the first bytes (base64) for viewer detect sniffing. */
+export interface FsBinaryResult {
+    kind: 'binary';
+    size: number;
+    truncated: boolean;
+    head: string;
+}
+/**
+ * One jobs.output response: the output the MODEL has read so far for the
+ * job (replayed from the owner session's event log — the model's
+ * job_output cursor is never touched, so the pane can never steal the
+ * agent's bytes). `read` is false until the model actually called
+ * job_output for the job.
+ */
+export interface JobOutputResult {
+    text: string;
+    /** True when the host capped the text at its output limit. */
+    truncated: boolean;
+    /** Whether the model has read the job at least once. */
+    read: boolean;
+}
+/** The `subagents.live` response: running child id → latest activity. */
+export type SubagentLiveResult = {
+    live: Record<string, LastActivity>;
+};
+/** Terminal dependency status (mirror of the host's depsStatus; issue #140). */
+export type TerminalDepsStatus = {
+    ok: true;
+} | {
+    ok: false;
+    /** The require-time error message (module missing, native binding broken…). */
+    cause: string;
+    /** The pasteable repair command (terminal/cmd). */
+    command: string;
+    /** The detected profile name (null when undetected → the command defaults to web). */
+    profile: string | null;
+    /** Optional supplementary hint (fallback command only). */
+    note?: string;
+};
+/** One request's session scope: the conversation id plus its cwd when known. */
+export interface SessionScope {
+    sessionId: string;
+    /** The session's working directory from the client list summary (optional). */
+    cwd?: string;
+    /** Selected Git repository when cwd is a workspace container. */
+    repoRoot?: string;
+}
+/** The sidebar API surface (session scope threaded through every call). */
+export declare const api: {
+    sessionCwd: (scope: SessionScope, signal?: AbortSignal) => Promise<{
+        sessionId: string;
+        cwd: string;
+        root: string;
+        parent: string | null;
+    }>;
+    fsTree: (scope: SessionScope, path: string, signal?: AbortSignal) => Promise<{
+        path: string;
+        entries: FsEntry[];
+        truncated: boolean;
+    }>;
+    /** Global recursive file-name search rooted at the session cwd (the editor
+     *  side panel's search box); matches are cwd-relative '/'-separated paths. */
+    fsSearch: (scope: SessionScope, query: string, signal?: AbortSignal) => Promise<{
+        matches: string[];
+        truncated: boolean;
+    }>;
+    fsRead: (scope: SessionScope, path: string, signal?: AbortSignal) => Promise<FsTextResult | FsBinaryResult>;
+    fsWrite: (scope: SessionScope, path: string, content: string) => Promise<{
+        ok: true;
+    }>;
+    /** Upload one file's raw bytes into `dir` (keeps the folder tree via
+     *  `relativePath`); the host streams it under the session workspace. */
+    uploadFile: (scope: SessionScope, dir: string, relativePath: string, body: Blob, signal?: AbortSignal) => Promise<{
+        path: string;
+        size: number;
+    }>;
+    gitWorktrees: (scope: SessionScope, signal?: AbortSignal) => Promise<GitWorktree[]>;
+    gitStatus: (scope: SessionScope, worktree?: string, signal?: AbortSignal) => Promise<GitStatusResult>;
+    gitDiff: (scope: SessionScope, path: string | undefined, staged: boolean, worktree?: string, signal?: AbortSignal) => Promise<{
+        diff: string;
+    }>;
+    gitStage: (scope: SessionScope, path?: string, worktree?: string) => Promise<{
+        ok: true;
+    }>;
+    gitUnstage: (scope: SessionScope, path?: string, worktree?: string) => Promise<{
+        ok: true;
+    }>;
+    gitCommit: (scope: SessionScope, message: string, worktree?: string) => Promise<{
+        ok: true;
+    }>;
+    gitBranch: (scope: SessionScope, worktree?: string, signal?: AbortSignal) => Promise<{
+        current: string;
+        names: string[];
+    }>;
+    gitCheckout: (scope: SessionScope, branch: string, worktree?: string) => Promise<{
+        ok: true;
+    }>;
+    /** Recent commit history, lazily pageable (skip/count; defaults 0/30). */
+    gitLog: (scope: SessionScope, count?: number, skip?: number, worktree?: string, signal?: AbortSignal) => Promise<GitLogEntry[]>;
+    /** Full patch text of one commit (diff display for the history rows). */
+    gitCommitDiff: (scope: SessionScope, hash: string, worktree?: string, signal?: AbortSignal) => Promise<{
+        diff: string;
+    }>;
+    /** Discard the worktree changes of one file (the index is untouched). */
+    gitDiscard: (scope: SessionScope, path: string, worktree?: string) => Promise<{
+        ok: true;
+    }>;
+    /** Revert one commit onto the current branch. */
+    gitRevert: (scope: SessionScope, hash: string, worktree?: string) => Promise<{
+        ok: true;
+    }>;
+    /** Cherry-pick one commit onto the current branch. */
+    gitCherryPick: (scope: SessionScope, hash: string, worktree?: string) => Promise<{
+        ok: true;
+    }>;
+    /** Release a terminal's process immediately (tab closed; the WS close frame
+     *  may be unreachable while the socket is down, so the host also accepts
+     *  this explicit route). */
+    ptyClose: (scope: SessionScope, tab: string) => Promise<{
+        ok: true;
+    }>;
+    /** Release an agent terminal by uuid (tab closed while WS was down). */
+    agentPtyClose: (uuid: string) => Promise<{
+        ok: true;
+    }>;
+    /** Terminal dependency status (issue #140): after a WS close 1011 with
+     *  reason `pty-deps-missing` the view fetches the full repair details here
+     *  (the close reason itself is capped at 123 bytes). */
+    terminalDeps: () => Promise<TerminalDepsStatus>;
+    /**
+     * The output the model has read so far for one background job (replayed
+     * from the owner session's event log — never the model's job_output
+     * cursor). The scope MUST be the job's OWNER session.
+     */
+    jobOutput: (scope: SessionScope, id: string, signal?: AbortSignal) => Promise<JobOutputResult>;
+    /** Request cancellation of one background job (live jobs flip to stopping). */
+    jobKill: (scope: SessionScope, id: string, reason?: string) => Promise<{
+        ok: true;
+        outcome: "requested" | "already-finished";
+    }>;
+    /**
+     * One batch live-preview fetch for the whole Subagent tree. The payload is
+     * the already-resolved topology ROOT (not a session scope); the host
+     * enumerates descendants once and folds running children's activity.
+     */
+    subagentsLive: (rootSessionId: string, signal?: AbortSignal) => Promise<SubagentLiveResult>;
+    /** Create a Side Chat thread: a child session seeded with the parent's
+     *  full log up to now. Empty question = immediate create (Codex-style):
+     *  the thread opens empty, the first prompt carries the boundary. */
+    sidechatStart: (sessionId: string, question?: string) => Promise<{
+        childId: string;
+    }>;
+    /** Deliver one follow-up message to a Side Chat thread. */
+    sidechatPrompt: (childId: string, text: string) => Promise<{
+        accepted: true;
+    }>;
+    /** Abort a Side Chat thread's running turn (queued work is preserved). */
+    sidechatCancel: (childId: string) => Promise<{
+        accepted: true;
+    }>;
+    /** Release a Side Chat thread's live agent (history stays persisted). */
+    sidechatDispose: (childId: string) => Promise<{
+        accepted: true;
+    }>;
+    /** Live state + agent identity (provider/model/preset) of a thread. */
+    sidechatInfo: (childId: string) => Promise<SidechatThreadInfo>;
+    /** The effective terminal shell and its display name (plugin-global). */
+    shellGet: () => Promise<{
+        shell: string;
+        name: string;
+    }>;
+    /** Read the side card preferences (plugin-global, no session scope). */
+    settingsGet: () => Promise<{
+        value?: unknown;
+        revision?: number;
+        externalDisable?: boolean;
+    }>;
+    /** Merge a patch into the side card preferences (revision-guarded). */
+    settingsUpdate: (patch: Record<string, unknown>, expectedRevision?: number) => Promise<{
+        value?: unknown;
+        revision?: number;
+    }>;
+    /** Probe a URL's response headers (the sidebar browser's embeddability
+     *  check; see the host's browser.probe route). */
+    browserProbe: (url: string, signal?: AbortSignal) => Promise<BrowserProbeResult>;
+    /** External open for the file tree's "open with" menu: reveal a path in
+     *  the OS file manager, or hand a custom-scheme URL (vscode://, cursor://,
+     *  zed://, custom editors) to its registered handler. The host launches
+     *  the platform opener (argv, no shell). */
+    openExternal: (payload: {
+        action: "reveal";
+        path: string;
+    } | {
+        action: "url";
+        url: string;
+    }) => Promise<{
+        started: boolean;
+    }>;
+};
+/** Absolute URL of the media route for one path (images only). */
+export declare function mediaUrl(scope: SessionScope, path: string): string;
+/** Absolute URL of the download route: serves raw bytes (binary-safe) with
+ *  `Content-Disposition: attachment`, so the browser saves the file. */
+export declare function downloadUrl(scope: SessionScope, path: string): string;
+/**
+ * Absolute URL of the HTML preview route (see html-route.ts): the path is
+ * fully encoded so the previewed page's relative assets resolve back into
+ * the same route with the session scope intact. The UNC marker is
+ * platform-neutral — the host's requireAbsolute resolves the decoded
+ * forward-slash `//server/share/...` form on both win32 and POSIX — so no
+ * client-side platform signal is needed.
+ */
+export declare function htmlUrl(scope: SessionScope, path: string): string;

package/lib/types/client/binary-download.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The "no preview — download instead" pane: shown by the editor host when no
+ * viewer can render a file (binary without a registered renderer, or the
+ * `binary-download` strategy) and registered as the `binary-download` viewer
+ * component so the declarative route and the host fallback share one UI.
+ */
+import type { ReactNode } from 'react';
+import type { SessionScope } from './api.ts';
+export declare function BinaryDownload(props: {
+    scope: SessionScope;
+    path: string;
+}): ReactNode;

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

@@ -0,0 +1,17 @@
+/** Viewport widths strictly below this are "mobile" (paired CSS: max-width: 767px). */
+export declare const NARROW_MAX_WIDTH = 768;
+/** Whether a viewport width is narrow (mobile). */
+export declare function isNarrowWidth(width: number): boolean;
+export interface ViewportSize {
+    width: number;
+    height: number;
+}
+/**
+ * Live narrow-viewport flag for components. Reads `window.innerWidth` and
+ * re-measures on resize (rAF-throttled, the repo's existing drag pattern).
+ * Deliberately avoids `matchMedia` (jsdom does not implement it) — the
+ * resize listener is equally exact for a breakpoint that never changes
+ * while the page is open.
+ */
+export declare function useViewportSize(): ViewportSize;
+export declare function useNarrowViewport(): boolean;

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

@@ -0,0 +1,60 @@
+/**
+ * Pure URL policy for the built-in browser tab: normalize user input into
+ * an http(s) URL, and refuse destinations that would be dangerous to embed
+ * in the sidebar iframe. Kept dependency-free so it is unit-testable.
+ *
+ * The iframe sandbox (opaque origin, no allow-same-origin / top-navigation)
+ * is the primary security boundary; this module is the address-bar gate on
+ * top of it: only http/https may be navigated, and loopback addresses are
+ * refused so a browsed page cannot probe local services by user action.
+ * The GUI's OWN origin is explicitly ALLOWED — the user may open the GUI
+ * itself in the sidebar (debugging, mirroring); the sandbox still renders
+ * it in an opaque origin with no same-origin privileges, exactly like any
+ * other site.
+ */
+/** Why a navigation attempt was refused. */
+export type BrowserBlockReason = 'scheme' | 'loopback';
+/** Result of normalizing one address-bar input. */
+export type BrowserNavigateResult = {
+    kind: 'ok';
+    url: string;
+} | {
+    kind: 'blocked';
+    reason: BrowserBlockReason;
+} | {
+    kind: 'invalid';
+};
+/** One browser.probe wire result (host fetch of the target's headers). */
+export interface BrowserProbeResult {
+    reachable: boolean;
+    /** The final (post-redirect) URL; present when reachable. */
+    url?: string;
+    status?: number;
+    xFrameOptions?: string;
+    /** The CSP frame-ancestors source list; present when the directive exists. */
+    frameAncestors?: string[];
+}
+/** Embeddability verdict of one probe. */
+export type Embeddability = 'embeddable' | 'blocked' | 'unknown';
+/**
+ * Decide whether a site can render inside the sidebar iframe. The signals
+ * are exactly the ones the BROWSER enforces when it refuses an iframe load:
+ * X-Frame-Options DENY/SAMEORIGIN, or a frame-ancestors directive that does
+ * not allow `*` ('self' here means the SITE's own origin — never ours, so
+ * it also blocks the sidebar). A site we could not reach yields 'unknown'
+ * and the plain iframe stays.
+ */
+export declare function embeddabilityOf(probe: BrowserProbeResult): Embeddability;
+/** A loopback hostname (localhost, IPv6 ::1, 127.0.0.0/8, 0.0.0.0). */
+export declare function isLoopbackHostname(hostname: string): boolean;
+/** Parse the loopback allowlist into a matcher predicate over host:port. */
+export declare function parseLoopbackAllowlist(allowlist: string): (host: string, port: string) => boolean;
+/**
+ * Whether a loopback URL is explicitly allowlisted by the side card prefs
+ * (`browserAllowedLoopback`). Only allowlisted local addresses may run with
+ * `allow-same-origin` in the sidebar iframe — needed for local dev servers
+ * (Vite etc.) whose module/HMR/fetch pipeline requires a real origin, while
+ * the page stays cross-origin to the GUI and to every other site.
+ */
+export declare function isAllowedLoopbackUrl(url: string, allowlist: string): boolean;
+export declare function normalizeBrowserUrl(input: string, selfOrigin: string, allowedLoopback?: string): BrowserNavigateResult;

package/lib/types/client/builtins/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Built-in registration: the plugin registers its own tab pages and file
+ * previewers through the same {@link BetterSidebarService} external plugins
+ * use — eating its own dogfood. The descriptors live next to their feature
+ * modules (tabs.tsx / viewers.tsx); this module only aggregates them and
+ * owns the disposer lifecycle (cordis auto-invokes it on fiber disposal,
+ * HMR-safe).
+ */
+import type { Context } from '../../context-types.ts';
+import type { BetterSidebarService } from '../service.ts';
+import { type BuiltinTabOptions } from './tabs.tsx';
+/**
+ * Register all built-in tabs and viewers with the service. Returns a
+ * disposer that unregisters everything (cordis auto-invokes it on fiber
+ * disposal). The `ctx` is threaded into tab descriptors that need it
+ * (EditorHost reads `ctx.betterSidebar` for file-viewer matching).
+ */
+export declare function registerBuiltins(ctx: Context, service: BetterSidebarService, options?: BuiltinTabOptions): () => void;