@achasoft/dsh-advanced-sidebar 0.1.0 → 0.3.0

package/types/client/locales.d.ts

@@ -24,9 +24,19 @@ export declare const zh: {
     'menu.archive': string;
     'menu.preview': string;
     'menu.delete': string;
+    'menu.downloadLog': string;
+    'menu.downloadLog.busy': string;
+    'menu.downloadLog.unavailable': string;
     'menu.empty': string;
     'menu.noSession': string;
     'menu.noDirectory': string;
+    'logs.dialog.preparingTitle': string;
+    'logs.dialog.preparingDescription': string;
+    'logs.dialog.successTitle': string;
+    'logs.dialog.successDescription': string;
+    'logs.dialog.errorTitle': string;
+    'logs.dialog.close': string;
+    'logs.dialog.commandFailed': string;
     'panel.close': string;
     'panel.refresh': string;
     'panel.retry': string;
@@ -152,6 +162,46 @@ export declare const zh: {
     'preview.noUrl': string;
     'preview.empty': string;
     'preview.emptyFile': string;
+    'preview.modes': string;
+    'preview.mode.server': string;
+    'preview.mode.file': string;
+    'preview.mode.url': string;
+    'preview.mode.scratchpad': string;
+    'preview.frame.empty': string;
+    'preview.viewport.fit': string;
+    'preview.viewport.custom': string;
+    'preview.device.custom': string;
+    'preview.inspect': string;
+    'preview.inspectHint': string;
+    'preview.url.field': string;
+    'preview.url.placeholder': string;
+    'preview.url.go': string;
+    'preview.url.reload': string;
+    'preview.url.proxied': string;
+    'preview.url.crossOrigin': string;
+    'preview.url.empty': string;
+    'preview.file.field': string;
+    'preview.file.placeholder': string;
+    'preview.file.open': string;
+    'preview.file.empty': string;
+    'preview.file.noWorkspace': string;
+    'preview.file.facts': string;
+    'preview.file.overLimit': string;
+    'preview.file.notPreviewable': string;
+    'preview.file.readFailed': string;
+    'preview.kind.iframe': string;
+    'preview.kind.markdown': string;
+    'preview.kind.image': string;
+    'preview.kind.media': string;
+    'preview.kind.pdf': string;
+    'preview.kind.text': string;
+    'preview.kind.other': string;
+    'preview.scratch.editor': string;
+    'preview.scratch.render': string;
+    'preview.scratch.pending': string;
+    'preview.scratch.saved': string;
+    'preview.scratch.unsaved': string;
+    'preview.scratch.refused': string;
     'delete.title': string;
     'delete.body.archive': string;
     'delete.body.purge': string;
@@ -256,9 +306,19 @@ export declare const en: {
     'menu.archive': string;
     'menu.preview': string;
     'menu.delete': string;
+    'menu.downloadLog': string;
+    'menu.downloadLog.busy': string;
+    'menu.downloadLog.unavailable': string;
     'menu.empty': string;
     'menu.noSession': string;
     'menu.noDirectory': string;
+    'logs.dialog.preparingTitle': string;
+    'logs.dialog.preparingDescription': string;
+    'logs.dialog.successTitle': string;
+    'logs.dialog.successDescription': string;
+    'logs.dialog.errorTitle': string;
+    'logs.dialog.close': string;
+    'logs.dialog.commandFailed': string;
     'panel.close': string;
     'panel.refresh': string;
     'panel.retry': string;
@@ -384,6 +444,46 @@ export declare const en: {
     'preview.noUrl': string;
     'preview.empty': string;
     'preview.emptyFile': string;
+    'preview.modes': string;
+    'preview.mode.server': string;
+    'preview.mode.file': string;
+    'preview.mode.url': string;
+    'preview.mode.scratchpad': string;
+    'preview.frame.empty': string;
+    'preview.viewport.fit': string;
+    'preview.viewport.custom': string;
+    'preview.device.custom': string;
+    'preview.inspect': string;
+    'preview.inspectHint': string;
+    'preview.url.field': string;
+    'preview.url.placeholder': string;
+    'preview.url.go': string;
+    'preview.url.reload': string;
+    'preview.url.proxied': string;
+    'preview.url.crossOrigin': string;
+    'preview.url.empty': string;
+    'preview.file.field': string;
+    'preview.file.placeholder': string;
+    'preview.file.open': string;
+    'preview.file.empty': string;
+    'preview.file.noWorkspace': string;
+    'preview.file.facts': string;
+    'preview.file.overLimit': string;
+    'preview.file.notPreviewable': string;
+    'preview.file.readFailed': string;
+    'preview.kind.iframe': string;
+    'preview.kind.markdown': string;
+    'preview.kind.image': string;
+    'preview.kind.media': string;
+    'preview.kind.pdf': string;
+    'preview.kind.text': string;
+    'preview.kind.other': string;
+    'preview.scratch.editor': string;
+    'preview.scratch.render': string;
+    'preview.scratch.pending': string;
+    'preview.scratch.saved': string;
+    'preview.scratch.unsaved': string;
+    'preview.scratch.refused': string;
     'delete.title': string;
     'delete.body.archive': string;
     'delete.body.purge': string;

package/types/client/log-download.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Download session log, absorbed into this plugin's menu.
+ *
+ * The harness ships `@deepseek-ai/dsh-session-log-export`, whose browser half does two things: it
+ * provides a `sessionLogDownload` controller on the client context (`lib/client.js:263`: one
+ * in-flight export per session, and a snapshot store describing it), and it registers a SECOND "⋯"
+ * button into the same
+ * `conversation.session.header.utilities` row this plugin's menu sits in, whose only entry is
+ * "Download session log" and which also renders the progress dialog. Two identical-looking triggers
+ * side by side, one of them holding a single verb, is what this module removes.
+ *
+ * How, and why this way (installed harness 0.1.5-rc.2):
+ *
+ * - The verb is REUSED, not rebuilt. The menu calls the package's own controller, read through the
+ *   context service it provides, so the export request, the per-session de-duplication and the
+ *   browser save stay the harness's; nothing here knows the export endpoint.
+ * - The button is SHADOWED, not patched out. `…/dsh-session-log-export/lib/client.js:274-276` registers
+ *   into a `list` slot with `id: 'session-log-download'` at the default priority 0, and a list slot's
+ *   cell is its `id`: entries sharing one coexist at distinct priorities and the lowest live one
+ *   renders (`SlotCore.register` / `entriesOfSlot` in `@deepseek-ai/dsh-client-ui-slots`). This
+ *   plugin registers that same id at priority -1, so its entry takes the cell without the other
+ *   package noticing, and uninstalling this plugin hands the button straight back. The rejected
+ *   alternative was a profile `cordis.patch.yml` row disabling the package: that would also remove
+ *   the controller the menu calls and the `/export` command's dialog, and it asks every user to edit
+ *   their profile.
+ * - The dialog is RE-RENDERED here. The harness's entry renders its button and its dialog as one
+ *   component, and the module exports neither, so shadowing the cell takes the dialog with it. The
+ *   shadowing entry therefore renders the same `Modal` from the same primitives, bound to the same
+ *   store — which keeps `/export`, whose success also opens that dialog, working exactly as before.
+ *
+ * Everything degrades toward the harness's own behaviour rather than toward a missing verb: without
+ * the package, or with a controller whose shape no longer matches, nothing is shadowed and the menu
+ * has no Download entry; and the menu entry and the dialog appear only while the harness's button is
+ * actually being shadowed, so a future harness that renames or removes its seat can never produce
+ * two dialogs, or a verb in two places.
+ * @module @achasoft/dsh-advanced-sidebar/client/log-download
+ */
+import type { HostObservable } from '@deepseek-ai/dsh-client-ui-slots';
+/** The context service the harness package provides (`ctx.provide('sessionLogDownload', …)`). */
+export declare const LOG_DOWNLOAD_SERVICE = "sessionLogDownload";
+/** The header slot both the harness's button and this plugin's menu occupy. */
+export declare const LOG_DOWNLOAD_SLOT = "conversation.session.header.utilities";
+/** The list-slot cell the harness's download button occupies, and this plugin's entry shadows. */
+export declare const LOG_DOWNLOAD_SEAT_ID = "session-log-download";
+/**
+ * The shadowing rank. The harness registers at the default 0; one below is enough to render first,
+ * and staying next to the default leaves room for a profile to out-rank this plugin in turn.
+ */
+export declare const LOG_DOWNLOAD_SHADOW_PRIORITY = -1;
+/** One session's export, as the harness controller publishes it. */
+export interface LogDownloadEntry {
+    /** Whether the dialog is showing; dismissing it does not cancel the export. */
+    readonly open: boolean;
+    /** Where the export is. */
+    readonly status: 'downloading' | 'success' | 'error';
+    /** The failure text when `status` is `error`; null otherwise. */
+    readonly error: string | null;
+}
+/** The harness controller's store snapshot. */
+export interface LogDownloadState {
+    /** Export state by session id. */
+    readonly bySession: Readonly<Record<string, LogDownloadEntry | undefined>>;
+}
+/**
+ * The part of `SessionLogDownloadController` this plugin calls, typed locally.
+ *
+ * Deliberately not imported: the package is the harness's, not a dependency of this one, and a
+ * deployment composed without it must still load every other entry of the menu.
+ */
+export interface LogDownloadService {
+    /** Snapshot store the harness's own dialog reads. */
+    readonly store: HostObservable<LogDownloadState>;
+    /**
+     * Start one session's export; a second call while one is in flight joins it.
+     * @param sessionId - root session whose tree is exported.
+     * @returns after the browser save starts or the failure is published.
+     */
+    download(sessionId: string): Promise<void>;
+    /**
+     * Close one session's dialog without cancelling its export.
+     * @param sessionId - session whose dialog closes.
+     */
+    dismiss(sessionId: string): void;
+}
+/**
+ * Accept a context service only when it still has the shape this plugin calls.
+ *
+ * The service is another package's, versioned with the harness, so its shape is checked rather than
+ * trusted: an incompatible controller makes this plugin stand aside — no shadow, no menu entry —
+ * which leaves the harness's own button in place instead of a menu entry that throws.
+ * @param value - whatever `ctx.get('sessionLogDownload')` returned.
+ * @returns the service, or undefined when absent or incompatible.
+ */
+export declare function asLogDownloadService(value: unknown): LogDownloadService | undefined;
+/** The registry facts {@link shadowsHarnessSeat} reads; a structural subset of a stored entry. */
+export interface SeatEntryLike {
+    /** The entry's registration options. */
+    readonly options: {
+        readonly id?: string | undefined;
+        readonly priority?: number | undefined;
+    };
+}
+/**
+ * Whether the header row holds an entry this plugin's shadow is actually hiding.
+ *
+ * Checked against the live registry rather than assumed, because the id is the harness's and can
+ * change in an upgrade. Without an occupant to hide, the menu entry would duplicate a download
+ * affordance the harness moved elsewhere, and the dialog would open twice beside the harness's own.
+ * @param entries - the slot's raw entries, every priority included.
+ * @returns true when some entry of the download cell ranks after (numerically above) this plugin's
+ * shadow, and is therefore the one being hidden.
+ */
+export declare function shadowsHarnessSeat(entries: readonly SeatEntryLike[]): boolean;
+/** What the menu and the dialog render from. */
+export interface LogDownloadView {
+    /**
+     * True while a compatible controller is attached AND its header button is being shadowed: the
+     * one condition under which this plugin, rather than the harness, is the download surface.
+     */
+    readonly active: boolean;
+    /** The controller's per-session export state; empty while detached. */
+    readonly bySession: LogDownloadState['bySession'];
+}
+/**
+ * Whether one session's export is in flight.
+ * @param view - the bridge snapshot.
+ * @param sessionId - the session to ask about.
+ * @returns true while that session's export has not settled.
+ */
+export declare function isDownloading(view: LogDownloadView, sessionId: string): boolean;
+/**
+ * Bridges the harness controller, which may arrive late, leave, or never exist, into one observable
+ * the menu can bind unconditionally.
+ *
+ * A `use<Name>` hook cannot be bound conditionally, and the menu is registered before the harness
+ * package has necessarily loaded, so the menu binds to this instead of to the controller's store:
+ * detached it reports inactive, attached it mirrors the controller's state.
+ */
+export declare class LogDownloadBridge implements HostObservable<LogDownloadView> {
+    private state;
+    private readonly listeners;
+    private service;
+    private shadowing;
+    /**
+     * The current snapshot; stable between changes, as `useSyncExternalStore` requires.
+     * @returns the view.
+     */
+    getSnapshot(): LogDownloadView;
+    /**
+     * Listen for changes.
+     * @param listener - called after each change.
+     * @returns the unsubscribe.
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Attach a controller and mirror its store until the returned disposer runs.
+     * @param service - the harness controller.
+     * @returns the detach, which is a no-op once another controller has replaced this one.
+     */
+    attach(service: LogDownloadService): () => void;
+    /**
+     * Record whether the harness's button is currently being shadowed.
+     * @param shadowing - the result of {@link shadowsHarnessSeat} over the live registry.
+     */
+    setShadowing(shadowing: boolean): void;
+    /**
+     * Start one session's export through the harness controller.
+     * @param sessionId - the session to export.
+     * @returns false when no controller is attached, so the caller never reports a start that did not happen.
+     */
+    download(sessionId: string): boolean;
+    /**
+     * Close one session's dialog without cancelling the export.
+     * @param sessionId - the session whose dialog closes.
+     */
+    dismiss(sessionId: string): void;
+    /** Recompute the view and notify, keeping the identity when nothing a reader sees changed. */
+    private publish;
+}

package/types/client/panels/PreviewPanel.d.ts

@@ -1,25 +1,30 @@
 /**
- * The Preview panel: run the thing you are building and look at it without leaving the session.
+ * The Preview panel: one surface with four ways to point it at something.
  *
- * A launch configuration is started on the Host, its port is watched until it accepts, and the
- * result is rendered in a frame beside the conversation. The frame is a plain `<iframe>` pointed at
- * a loopback URL, which is what makes this work for any dev server rather than for a list of
- * blessed ones.
+ * - **Server** — a launch configuration is started on the Host, its port is watched until it
+ *   accepts, and the result is framed with its logs beside it. This is the original behaviour and it
+ *   is unchanged, including the two controls that are permanent rather than error states: **Logs**,
+ *   because a server that failed to start has only its stderr to explain itself, and **Open in a new
+ *   window**, because a page can refuse to be framed and a cross-origin frame gives the panel no way
+ *   to detect that the load event fired on an error page.
+ * - **Files** — any file in the session workspace, rendered by type: an HTML document is framed
+ *   live *through this Host's own route*, so it is same-origin and therefore inspectable; Markdown
+ *   is rendered as React elements with no raw HTML; images, PDF, audio and video go to the browser's
+ *   own elements; anything else is reported with its size and an "open it in the OS" action.
+ * - **URL** — any address, with a loopback one routed through this Host's proxy so that it too
+ *   becomes same-origin, and a public one framed as-is with the panel saying it is opaque.
+ * - **Scratchpad** — an HTML editor whose document is rendered beside it from this Host's route, so
+ *   the frame has a real URL and a real origin rather than `srcdoc`'s opaque one.
  *
- * Two things a person needs are therefore always present, not hidden behind a state:
- *
- * - **Logs.** A server that failed to start has nothing to show in the frame, and its stderr is the
- *   only place the reason exists. The log view is one toggle away at every state, and opens itself
- *   when a start fails.
- * - **Open in a new window.** A page can refuse to be framed (`X-Frame-Options`,
- *   `frame-ancestors`), and cross-origin framing gives the panel no way to detect that — the load
- *   event fires either way. So the escape hatch is a permanent control rather than an error
- *   recovery, and the panel says so instead of pretending a blank frame is a loading one.
+ * The panel also runs the browser end of the agent channel: a {@link PreviewDriver} polls for
+ * commands the model's `ui_preview` tool queued and executes them against whichever frame is
+ * mounted. That is the reason the same-origin work exists at all — a cross-origin frame's document
+ * is unreachable, so neither the panel nor the model could inspect it.
  * @module @achasoft/dsh-advanced-sidebar/client/panels/PreviewPanel
  */
 import { type PanelProps } from './shared.tsx';
 /**
- * The server picker, the frame, and the log view.
+ * The four-mode Preview surface, its frame, its logs, and the agent driver.
  * @param props - the target, the translator, and the dock's face.
  * @returns the panel body.
  * @see {@link PanelProps}

package/types/client/panels/preview-file.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The Preview panel's **Files** mode: preview any file in the session workspace by type.
+ *
+ * The mode is a thin control surface over one Host endpoint (`previewFileInfo`), which is what
+ * decides a file's kind, its size, its same-origin URL, and its change token. Deciding the kind on
+ * the Host rather than in the browser is deliberate: the same table then also types the bytes the
+ * file route serves, so what the panel renders and what the frame receives cannot disagree.
+ *
+ * The change token is what makes an edit on disk visible. It is re-read only while a file is
+ * previewed, at a cadence slow enough to be free and fast enough to feel live, and a token that
+ * moves REMOUNTS the frame rather than reloading it — a remount is the only way to be sure nothing
+ * the previous document cached survives into the new one.
+ * @module @achasoft/dsh-advanced-sidebar/client/panels/preview-file
+ */
+import type { PreviewFileInfo } from '../../host/types.ts';
+import type { PreviewModeProps } from './preview-mode.ts';
+import type { PanelFace } from '../preview-types.ts';
+/** What the file mode needs beyond the shared mode contract. */
+export interface FileModeProps extends PreviewModeProps {
+    /** The dock's face, for the one endpoint this mode calls. */
+    readonly face: PanelFace;
+    /** The workspace a path is resolved against, absent when the session has none. */
+    readonly workspace: string | undefined;
+    /** The file's description, owned by the panel because it decides the frame. */
+    readonly info: PreviewFileInfo | undefined;
+    /** True while a description is in flight. */
+    readonly busy: boolean;
+    /** Replace the description. */
+    readonly onInfo: (info: PreviewFileInfo | undefined) => void;
+    /** A failure phrased for the panel's error line. */
+    readonly onError: (message: string | undefined) => void;
+}
+/**
+ * Read one file's description, contained to the workspace by the Host.
+ *
+ * The workspace is sent with the path and the Host proves containment, so a mistyped absolute path
+ * is refused by the same check the Files panel uses rather than by a string comparison here.
+ * @param face - the dock's face.
+ * @param workspace - the workspace the path must stay inside.
+ * @param path - the file, absolute or relative.
+ * @param signal - cancellation for the read.
+ * @returns the description, or a failure.
+ */
+export declare function loadFileInfo(face: PanelFace, workspace: string, path: string, signal?: AbortSignal): Promise<PreviewFileInfo | {
+    error: string;
+}>;
+/**
+ * Re-read one open file's token and report when it moved.
+ * @param face - the dock's face.
+ * @param workspace - the workspace.
+ * @param path - the file on screen, or undefined to watch nothing.
+ * @param onInfo - called with every successful reading.
+ * @param onChanged - called when the file's token moved.
+ */
+export declare function useFileWatch(face: PanelFace, workspace: string | undefined, path: string | undefined, onInfo: (info: PreviewFileInfo) => void, onChanged: () => void): void;
+/**
+ * The path field, the file's facts, and the manual Refresh.
+ * @param props - the mode contract plus the file's state.
+ * @returns the mode's controls.
+ */
+export declare function PreviewFileMode({ t, face, state, setState, workspace, info, busy, onInfo, onError, }: FileModeProps): import("react").JSX.Element;

package/types/client/panels/preview-mode.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The contract every Preview mode's controls share with the panel that owns the frame.
+ *
+ * The panel owns one piece of state — what the frame is showing, in which mode, under which
+ * viewport — and each mode's controls are handed a patch function rather than a setter per field.
+ * One patch shape keeps the mode components from needing to know the whole state, and it is what
+ * lets the agent's `open` control land on the same state a person's click writes.
+ * @module @achasoft/dsh-advanced-sidebar/client/panels/preview-mode
+ */
+import type { Translate } from '../contract.ts';
+import type { PreviewMode } from '../preview-types.ts';
+/** What the panel is showing, as every mode reads it. */
+export interface PreviewModeState {
+    /**
+     * The URL of the framed document, as a frame can use it: an absolute URL for URL and Server
+     * modes, the same-origin file route for a framed file, or the scratchpad route.
+     *
+     * Separate from the address a person typed because the two differ exactly where it matters: the
+     * typed address is what an operator recognizes, the frame source is what makes the document
+     * same-origin.
+     */
+    readonly src: string;
+    /** The address as a person or the agent spelled it, for the address bar. */
+    readonly url: string;
+    /** The workspace this panel acts on, absent when the session has no directory. */
+    readonly workspace: string | undefined;
+    /** The same-origin proxy route, absent when the Host serves none. */
+    readonly proxyRoute: string | undefined;
+    /** Whether the framed document is same-origin with the GUI, so the agent can inspect it. */
+    readonly inspectable: boolean;
+    /** The file being previewed, in file mode. */
+    readonly filePath: string;
+    /** The frame viewport, pinned by the resize control or the agent; zero means "fit the dock". */
+    readonly viewport: {
+        readonly width: number;
+        readonly height: number;
+    };
+}
+/** One patch to {@link PreviewModeState}; only the named fields change. */
+export type PreviewModePatch = Partial<Omit<PreviewModeState, 'viewport'>> & {
+    /** Replace the pinned viewport; zero for both means "fit the dock". */
+    readonly viewport?: {
+        readonly width: number;
+        readonly height: number;
+    };
+    /**
+     * True when the patch is a person or agent COMMITTING a new document, which forces the frame to
+     * remount even when the source string is unchanged (the reload Go provides).
+     */
+    readonly committed?: boolean;
+};
+/** What every mode's controls are handed. */
+export interface PreviewModeProps {
+    /** The namespace translator. */
+    t: Translate;
+    /** The panel's current state. */
+    readonly state: PreviewModeState;
+    /** Apply a patch. */
+    readonly setState: (patch: PreviewModePatch) => void;
+    /** Remount the frame, reloading whatever it shows. */
+    readonly onReload: () => void;
+}
+/** The panel's own state, mode included. */
+export interface PreviewState extends PreviewModeState {
+    /** Which mode is showing. */
+    readonly mode: PreviewMode;
+}

package/types/client/panels/preview-scratchpad.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The Preview panel's **Scratchpad** mode: an editable HTML pane whose content renders live beside it.
+ *
+ * The document is saved per workspace in this browser's `localStorage`, and it is rendered from the
+ * Host's own scratchpad route rather than from `srcdoc`. Both are deliberate:
+ *
+ * - **Storage.** A scratchpad is a thought being worked out, not a deliverable; it must survive a
+ *   reload without anybody having to create a file. Per workspace, because two projects' experiments
+ *   have nothing to do with each other.
+ * - **A real URL.** `srcdoc` gives the frame an opaque origin, so `document.baseURI`, a relative
+ *   `fetch`, and `window.location` are all nonsense inside it, and the agent cannot inspect a
+ *   document that has no origin. Posting the text to the Host's route gives the frame this GUI's own
+ *   origin — the same property that makes Files mode inspectable.
+ *
+ * The editor and the render are debounced together at {@link RENDER_DEBOUNCE_MS}, because a frame
+ * remounted per keystroke is unusable and a save per keystroke is what fills a storage quota.
+ * @module @achasoft/dsh-advanced-sidebar/client/panels/preview-scratchpad
+ */
+import type { PreviewModeProps } from './preview-mode.ts';
+/** What the panel needs from the scratchpad, whose `src` it also frames. */
+export interface Scratchpad {
+    /** The document text. */
+    readonly text: string;
+    /** Replace the text, which schedules a save and a render. */
+    readonly setText: (value: string) => void;
+    /** True while a save and render are pending. */
+    readonly pending: boolean;
+    /** True when the last save was refused by the browser. */
+    readonly unsaved: boolean;
+}
+/**
+ * Own the scratchpad's text, its storage, and its debounce.
+ *
+ * The rendered document is not this hook's business: the panel holds the frame, so the hook reports
+ * the text and calls {@link onPublish} after the debounce, and the panel decides how a document
+ * becomes a frame source. Keeping one owner for the frame is what makes the agent's `open` and a
+ * person's keystroke land on the same state.
+ * @param workspace - the workspace whose scratchpad this is.
+ * @param onPublish - called with the document to render after the debounce.
+ * @returns the editor's state.
+ */
+export declare function useScratchpad(workspace: string | undefined, onPublish: (document_: string) => void): Scratchpad;
+/** What the scratchpad's controls need, beyond the shared mode contract. */
+export interface ScratchpadModeProps extends PreviewModeProps {
+    /** The editor's state, owned by the panel. */
+    readonly scratch: Scratchpad;
+}
+/**
+ * The editor pane, its Render button, and the storage note.
+ * @param props - the mode contract plus the editor state.
+ * @returns the mode's controls.
+ */
+export declare function PreviewScratchpadMode({ t, scratch }: ScratchpadModeProps): import("react").JSX.Element;

package/types/client/panels/preview-url.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The Preview panel's **URL** mode controls: type an address, frame it, reload it.
+ *
+ * The only decision here is what "same-origin" means for an address a person typed. A loopback URL
+ * is routed through the Host's own proxy so the frame becomes inspectable — which is the reason the
+ * mode exists beside the dev-server one — while anything else is framed exactly as typed. A public
+ * URL is not refused: looking at a page is what the person asked for. The panel says the frame will
+ * be opaque, and the agent tool reports that honestly rather than returning an empty DOM.
+ * @module @achasoft/dsh-advanced-sidebar/client/panels/preview-url
+ */
+import type { PreviewModeProps } from './preview-mode.ts';
+/**
+ * The address bar, its Go, and the cross-origin explanation.
+ * @param props - the panel's mode contract.
+ * @returns the mode's controls.
+ */
+export declare function PreviewUrlMode({ t, state, setState, onReload }: PreviewModeProps): import("react").JSX.Element;

package/types/client/panels/shared.d.ts

@@ -3,8 +3,9 @@
  * otherwise be written five times, and the path renderer.
  * @module @achasoft/dsh-advanced-sidebar/client/panels/shared
  */
-import type { PanelHostInjected, Translate } from '../contract.ts';
+import type { Translate } from '../contract.ts';
 import type { OperationTarget } from '../controller.ts';
+import type { PanelFace } from '../preview-types.ts';
 /** What every panel is handed by the dock. */
 export interface PanelProps {
     /** The session and directory this panel acts on. */
@@ -16,7 +17,7 @@ export interface PanelProps {
      * that with bound `use<Name>` selector props before the dock is rendered, so no panel ever sees
      * the sources themselves.
      */
-    face: Omit<PanelHostInjected, 'hooks'>;
+    face: PanelFace;
 }
 /**
  * Format a byte count for a file row.
@@ -63,3 +64,15 @@ export declare function useLatest<T>(value: T): {
  * @returns a single-line message.
  */
 export declare function transportMessage(reason: unknown, t: Translate): string;
+/**
+ * Join a typed path against the workspace unless it is already absolute.
+ *
+ * The Host proves containment either way — this is not a containment check — so the join only saves
+ * a person from typing a long prefix. It is deliberately string arithmetic rather than a resolution:
+ * the Host is the authority on what a path means, and a browser-side `..` walk would be a second,
+ * weaker copy of that rule.
+ * @param workspace - the absolute workspace directory.
+ * @param path - the typed path.
+ * @returns the absolute candidate the Host will resolve and contain.
+ */
+export declare function absoluteIn(workspace: string, path: string): string;