@chatcode/cco-better-sidebar 0.18.0-alpha.0

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

@@ -0,0 +1,345 @@
+import type { BrowserProbeResult } from './browser.ts';
+/** One wire failure. */
+export declare class SidebarApiError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Whether a wire failure is the workspace fence refusing a path outside the
+ * session workspace (the host message reads `path "..." is outside
+ * workspace`). The request-trust fence answers code `forbidden` with the
+ * bare message 'forbidden', so the message fragment — not the code alone —
+ * identifies this case.
+ */
+export declare function isOutsideWorkspaceError(error: unknown): boolean;
+/** Message-level variant for surfaces that stored the raw text (file-tree level errors). */
+export declare function isOutsideWorkspaceMessage(message: string): boolean;
+/** 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;
+}
+/** 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;
+};
+/** Display-only CodingPlan model returned by the sidebar host. Provider
+ * endpoints, protocol details, and API keys intentionally do not exist in
+ * this browser-facing type. */
+export interface CodingPlanModel {
+    logicalModelId: string;
+    displayName: string;
+    description?: string;
+    accessType?: string;
+    maxToken?: number;
+    contextWindow?: number;
+}
+/** Cached CodingPlan catalogue state. */
+export interface CodingPlanCatalogue {
+    status: 'loading' | 'ready' | 'unavailable';
+    models: CodingPlanModel[];
+    fetchedAt?: string;
+}
+/** Browser-safe ChatCode account state returned by the optional host plugin. */
+export interface ChatCodeAuthState {
+    required?: boolean;
+    validation?: 'valid' | 'invalid' | 'unavailable' | 'none';
+    login?: {
+        sessionId: string;
+        state: 'pending' | 'succeeded' | 'failed' | 'timed-out' | 'cancelled';
+        expiresAtMs: number;
+    };
+    available: boolean;
+    configured?: boolean;
+    expired?: boolean;
+    userName?: string;
+    emailAddress?: string;
+}
+/** One day of personal token usage (the platform userTokenTrend row). */
+export interface ChatCodeTokenDay {
+    statDate: string;
+    tokensIn: number;
+    tokensOut: number;
+    totalTokens: number;
+}
+/** One personal commit record (the platform gitCommitRecord row; numeric
+ *  fields are coerced defensively at render time). */
+export interface ChatCodeCommitRecord {
+    projectName: string;
+    name: string;
+    email: string;
+    authorEmail: string;
+    additions: number;
+    deletions: number;
+    total: number;
+    aiTotal: number;
+    orgname: string;
+    deptname: string;
+    title: string;
+    shortId: string;
+    authoredDate: string;
+}
+/** Exact release note for the running package version. */
+export interface ReleaseNoteResult {
+    registered: boolean;
+    release: null | {
+        id: number;
+        packageName: string;
+        versionNum: string;
+        title?: string;
+        contentMd: string;
+        updatedAt?: string;
+    };
+}
+/** The package the "update" section's action upgrades. */
+export declare const CHATCODE_CLI_PKG = "@chatcode/chatcode-cli";
+/** One package's version-check result (mirror of the host chatcode-update). */
+export interface ChatCodeUpdateCheck {
+    packageName: string;
+    current: string | null;
+    latest: string | null;
+    needsUpdate: boolean;
+}
+/** One package's perform-update result (mirror of the host chatcode-update). */
+export interface ChatCodeUpdateResult {
+    packageName: string;
+    from: string | null;
+    to: string | null;
+    ok: boolean;
+    message: 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: {
+    chatcodeStatus: (signal?: AbortSignal) => Promise<ChatCodeAuthState>;
+    chatcodeStart: () => Promise<{
+        sessionId: string;
+        url: string;
+    }>;
+    chatcodeCancel: (sessionId: string) => Promise<{
+        ok: true;
+    }>;
+    chatcodeLogout: () => Promise<{
+        ok: true;
+    }>;
+    /** Check both ChatCode packages (web + CLI) against the npm registry. */
+    chatcodeUpdateCheck: (signal?: AbortSignal) => Promise<{
+        packages: ChatCodeUpdateCheck[];
+    }>;
+    /** Upgrade both ChatCode packages to their npm-latest versions. */
+    chatcodeUpdatePerform: (signal?: AbortSignal) => Promise<{
+        results: ChatCodeUpdateResult[];
+    }>;
+    releaseNoteCurrent: (packageName: string, versionNum: string, signal?: AbortSignal) => Promise<ReleaseNoteResult>;
+    /** Per-day token usage of one day range (`YYYY-MM-DD`). */
+    chatcodeTokenTrend: (begin: string, end: string, signal?: AbortSignal) => Promise<ChatCodeTokenDay[]>;
+    /** Personal commit records of one day range (AI-ratio view). */
+    chatcodeGitCommitStats: (begin: string, end: string, signal?: AbortSignal) => Promise<ChatCodeCommitRecord[]>;
+    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 effective terminal shell and its display name (plugin-global). */
+    shellGet: () => Promise<{
+        shell: string;
+        name: string;
+    }>;
+    /** The local display name used by the bottom-left account menu. */
+    accountGet: () => Promise<{
+        userName: string;
+    }>;
+    /** Read the host-cached CodingPlan model catalogue. */
+    codingPlanModels: () => Promise<CodingPlanCatalogue>;
+    /** Refresh the host-cached CodingPlan catalogue. */
+    codingPlanRefresh: () => Promise<CodingPlanCatalogue>;
+    /** 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;

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

@@ -0,0 +1,11 @@
+import type { Context } from '../../context-types.ts';
+import type { TabDescriptor } from '../service.ts';
+/** How many UI-owned terminals may be open at once (agent-owned ones are uncapped). */
+export declare const TERMINAL_LIMIT = 3;
+/** Optional per-registration builtin behavior (currently terminal title). */
+export interface BuiltinTabOptions {
+    /** Returns the display title for newly opened terminal tabs. */
+    terminalTitle?: () => string;
+}
+/** The 5 built-in tab descriptors. */
+export declare function builtinTabs(ctx: Context, options?: BuiltinTabOptions): readonly TabDescriptor[];

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

@@ -0,0 +1,3 @@
+import type { FileViewerDescriptor } from '../service.ts';
+/** The 6 built-in file viewer descriptors. */
+export declare function builtinViewers(): readonly FileViewerDescriptor[];

package/lib/types/client/chat-presentation.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Narrow compatibility polish for the host Chat surface.
+ *
+ * DSH does not currently expose extension seats for the running-status copy
+ * or for suppressing one producer's context row. Keep the adaptation at the
+ * rendered DOM boundary, keyed by stable semantics (`role=status` and the
+ * context producer marker), and make every mutation reversible on unload.
+ */
+/**
+ * Apply the Chat presentation compatibility layer and observe late React
+ * mounts/updates. The disposer restores every row hidden by this activation.
+ */
+export declare function registerChatPresentationCompatibility(): () => void;

package/lib/types/client/chunk-loader.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Lazy chunk loader for the client bundle. The heavy preview/terminal
+ * libraries (CodeMirror, xterm — the editor/terminal stacks, several MB)
+ * live in separate build-time bundles (`lib/client-<name>.js`) fetched only
+ * on first use of the feature that needs them, so startup downloads/parses
+ * only the ~1MB core bundle. (The office stack — Univer / docx-preview /
+ * pptx-renderer — is no longer bundled here: Office previews moved to the
+ * recommended office plugin, see plugins-viewers.ts.)
+ *
+ * How a chunk script works (see tsdown.config.ts chunkBundle):
+ *
+ *   globalThis.__dshChunks__ = globalThis.__dshChunks__ || {};
+ *   globalThis.__dshChunks__["terminal"] = (require) => { ...exports };
+ *
+ * The script registers its factory on a plugin-owned global registry (NOT
+ * through window.__ModuleLoader__.load — the module loader's import() only
+ * resolves seed words, shell-own modules, registered factories, and boot
+ * graph rows; a chunk id is none of those, so resolution would be version-
+ * dependent). Materialization is plugin-owned:
+ *
+ * 1. inject <script src="/sidebar/bundle/<name>.js"> (classic same-origin
+ *    script; the official /plugins/<id>/client.js route cannot serve
+ *    arbitrary file names, so the plugin's own host route serves the chunks),
+ * 2. read the factory from the global registry,
+ * 3. call it with a require that resolves the platform externals through
+ *    `__DSH_MODULES__.import(spec)` — the seed-word branch, the one part of
+ *    the module system that is stable across versions.
+ *
+ * Caching contract (three layers, each with a failure path):
+ * - In-memory: one in-flight promise per chunk, memoized until
+ *   {@link resetChunks}; a failed load removes its entry so the next call
+ *   retries from scratch. HMR re-activation keeps the resolved exports of
+ *   unchanged chunks (ETag revalidation via
+ *   {@link revalidateChunksOnReactivate}) — the next lazy open skips the
+ *   re-inject / re-execute.
+ * - Script execution: each re-execution overwrites the global registry slot
+ *   (assignment, never registration) — no "duplicate factory registration"
+ *   class of errors; a failed materialization clears the cache so the retry
+ *   re-injects and re-executes.
+ * - HTTP: the bundle route revalidates every request (`cache-control:
+ *   no-cache` + ETag, 304 when unchanged), so page refreshes and HMR
+ *   re-activations never re-download a multi-MB chunk that did not change.
+ *
+ * HMR: each plugin activation calls {@link revalidateChunksOnReactivate},
+ * which HEADs every loaded chunk against the bundle route and keeps the
+ * in-memory cache for the ones whose ETag is unchanged (a hot-reloaded core
+ * bundle therefore does not re-execute multi-MB chunk scripts). Chunk-only
+ * source edits still need a manual page refresh (the HMR poll watches only
+ * client.js); an edit that does land while a core HMR happens is caught by
+ * the ETag comparison on the next activation.
+ */
+export type ChunkName = 'terminal' | 'editor' | 'mermaid';
+/** The module exports a chunk factory provides (namespace-ish record). */
+export type ChunkExports = Record<string, unknown>;
+/**
+ * The platform externals a chunk bundle may require (mirror of
+ * CLIENT_EXTERNALS in tsdown.config.ts — the chunk builds keep these
+ * external and the loader resolves them here). A superset is safe: the
+ * require only answers what the chunk actually asks for. The shell's static
+ * module table seeds React, Cordis, and the UI libraries (primitives/slots).
+ * `@deepseek-ai/dsh-client-runtime` was removed upstream in DSH 0.1.2-alpha
+ * (its seed row became bare-name `@deepseek-ai/dsh-client-store`) and no
+ * chunk ever required it, so its row is gone; so are dsh-client-web-react /
+ * dsh-client-schema-form, dropped back in DSH 0.1.0-rc.8.
+ */
+export declare const CHUNK_EXTERNALS: readonly string[];
+/**
+ * The client module system surface this loader needs to resolve externals.
+ * DSH 0.1.0-rc.8 provides it as the `ctx.modules` service (no page global
+ * anymore); the plugin injects it at activation via
+ * {@link setChunkModuleSystem}. The rc.7-era `window.__DSH_MODULES__` global
+ * remains as a fallback so older hosts and the test harness keep working.
+ */
+export interface ChunkModuleSystem {
+    import(specifier: string): Promise<unknown>;
+}
+/**
+ * Inject the client module system the chunk externals resolve through.
+ * Called by the client half's apply() with `ctx.modules` (rc.8+); pass
+ * undefined to clear (tests). Survives {@link resetChunks} — the module
+ * system is shell state, not chunk state, and stays live across HMR.
+ */
+export declare function setChunkModuleSystem(system: ChunkModuleSystem | undefined): void;
+/** Script-load hook; tests replace it with a stub (the default needs a real DOM + network). */
+export type ChunkScriptLoader = (src: string) => Promise<void>;
+/** Test hook: replace the chunk-script loader (pass null to restore the default). */
+export declare function setChunkScriptLoaderForTests(loader: ChunkScriptLoader | null): void;
+export declare function registerChunkForTests(name: ChunkName, loader: () => Promise<ChunkExports>): void;
+/**
+ * Load (once) and materialize a lazy chunk, returning its module exports.
+ * Concurrent callers share one in-flight load; a failure clears the cache
+ * entry so the next call retries (the script re-executes and overwrites its
+ * global registry slot — assignments are idempotent).
+ * @param name - the chunk to load.
+ */
+export declare function loadChunk(name: ChunkName): Promise<ChunkExports>;
+/**
+ * Drop all chunk state for a fresh plugin activation (HMR-safe): clear the
+ * in-memory cache and any test-registry entries, so the next lazy open
+ * re-fetches and re-executes the current chunk scripts (the registry slots
+ * are overwritten by the re-execution — no cleanup needed). A pending
+ * revalidation barrier is cleared too: it was only guarding the cache reads
+ * of the state being dropped, so the next load must not wait on it (the
+ * orphaned task still settles and its identity-guarded `finally` no-ops).
+ */
+export declare function resetChunks(): void;
+/**
+ * HMR-safe re-activation hook (index.tsx calls this instead of a full
+ * reset): keep the resolved exports of every loaded chunk and drop only the
+ * ones whose script changed on disk — the bundle route revalidates every
+ * request (cache-control: no-cache + ETag), so an unchanged chunk keeps its
+ * memory cache and the next lazy open skips the re-inject / re-execute.
+ * Fail-open: an unreachable, ETag-less, or timed-out chunk is dropped
+ * (re-fetch on next open). Test-registry entries are always cleared
+ * (per-test fixtures).
+ * A page refresh remains the authoritative reset (the HMR poll watches only
+ * client.js; chunk-only edits surface here on the next core re-activation).
+ *
+ * The returned promise is also a BARRIER for {@link loadChunk}: while a
+ * revalidation is pending, every chunk load awaits it before serving cache,
+ * so a lazy tab opening mid-revalidation can never render stale exports
+ * that the sweep is about to invalidate (CR #232 P1).
+ */
+export declare function revalidateChunksOnReactivate(): Promise<void>;

package/lib/types/client/chunks/editor.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Lazy chunk entry: the code/markdown/html text editor (CodeMirror 6 + the
+ * language packages). Built as `lib/client-editor.js` and registered under
+ * `dsh-better-sidebar/editor` — fetched only when a text file is first
+ * opened (see chunk-loader.ts and docs/plans/2026-08-12-lazy-chunks-design.md).
+ * Never import this module from the core bundle: it pulls CodeMirror into
+ * the startup path.
+ */
+export { TextEditor } from '../TextEditor.tsx';

package/lib/types/client/chunks/mermaid.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Lazy chunk entry: the mermaid diagram renderer for the markdown preview
+ * (mermaid + its d3/dagre/cytoscape graph deps). Built as
+ * lib/client-mermaid.js and registered under the `mermaid` global chunk
+ * slot — fetched only when a previewed markdown file contains a mermaid
+ * fence (see chunk-loader.ts and the mermaid markdown preview design doc).
+ * Never import this module from the core bundle: it pulls mermaid into the
+ * startup path.
+ */
+export { MermaidMarkdown } from '../mermaid.tsx';

package/lib/types/client/chunks/terminal.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Lazy chunk entry: the interactive terminal (xterm + fit addon). Built as
+ * `lib/client-terminal.js` and registered under
+ * `dsh-better-sidebar/terminal` — fetched only when a terminal tab is first
+ * opened (see chunk-loader.ts and docs/plans/2026-08-12-lazy-chunks-design.md).
+ * Never import this module from the core bundle: it pulls xterm (and its
+ * stylesheet) into the startup path.
+ */
+export { TerminalView } from '../TerminalView.tsx';

package/lib/types/client/cm-themes.d.ts

@@ -0,0 +1,24 @@
+/**
+ * CodeMirror 6 theme pieces for the sidebar editor. The editor surface
+ * (background, caret, gutter) rides the DSH theme tokens so it blends with
+ * the panel in both schemes; only the syntax token colors need concrete
+ * values, and those come from the same designed palettes the app's code
+ * surfaces use — the one-dark family for dark, the one-light family for
+ * light. The scheme flip reconfigures these via a compartment (see
+ * TextEditor), so the document, undo history and scroll survive re-theming.
+ */
+import { Compartment } from '@codemirror/state';
+/** Token-driven surface shared by both schemes (pure CSS values). */
+export declare const cmSurfaceTheme: import("@codemirror/state").Extension;
+/**
+ * A Compartment holding the two scheme-dependent extensions. Created once
+ * per editor view; a scheme flip dispatches `reconfigure(dark)` on it, so
+ * the document, undo history, scroll and keymaps survive re-theming.
+ */
+export declare class CmThemeCompartment {
+    private readonly compartment;
+    /** `of(...)` payload for EditorState.create. */
+    of(dark: boolean): ReturnType<Compartment['of']>;
+    /** Reconfigure for a new scheme. */
+    reconfigure(dark: boolean): ReturnType<Compartment['reconfigure']>;
+}