@crosery/dsh-viewer 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,32 @@
+/**
+ * Where a card's durable image bytes come from — pure, so it is testable
+ * without a DOM.
+ * @module @crosery/dsh-viewer/client/sources
+ */
+import type { ModelImage } from '../contract.ts';
+/**
+ * The chat's own durable-image loader, as the 0.1.7 tool-view owner supplies
+ * it. Its parameter is the harness's branded `ImageAttachmentRef`, which a
+ * {@link ModelImage} matches field for field; `never` keeps any train's exact
+ * loader type assignable here without importing the brand.
+ */
+export type OwnerImageLoader = (attachment: never) => Promise<string>;
+/** How one displayed file reaches its bytes and its Host-side opener. */
+export interface ViewerSources {
+    /** Resolve one durable image to a URL. */
+    loadImage: (image: ModelImage) => Promise<string>;
+    /** Open the file through the Host, when the surrounding view offers that. */
+    openFile?: ((path: string) => unknown) | undefined;
+}
+/**
+ * The loader a card uses for durable images: the chat's own where the owner
+ * supplies one (0.1.7+), the plugin's attachment reader otherwise.
+ *
+ * The chat's loader is preferred because it shares one read and one browser URL
+ * per image across every view of the session and releases them with the
+ * session; the plugin's reader keeps its own URLs until the plugin unloads.
+ * @param owner - the owner's optional loader.
+ * @param fallback - the plugin's reader, by attachment id.
+ * @returns a loader over the card's image facts.
+ */
+export declare function imageLoaderFor(owner: OwnerImageLoader | undefined, fallback: (attachmentId: string) => Promise<string>): ViewerSources['loadImage'];

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

@@ -0,0 +1,14 @@
+/**
+ * The card's own stylesheet, injected for exactly this plugin's lifetime.
+ *
+ * Plain prefixed class names rather than CSS Modules: the repository's module
+ * pipeline is not published, so an out-of-tree package that wants a hashed class
+ * map has to reproduce it. Colors come from `--dsw-alias-*` semantic tokens, so
+ * the card follows the active palette with no theme branch of its own.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/**
+ * Mount the card stylesheet for the owning plugin lifetime.
+ * @param ctx - owning plugin context.
+ */
+export declare function installViewerStyles(ctx: Context): void;

package/lib/types/client/turn-tail.d.ts

@@ -0,0 +1,373 @@
+/**
+ * Keeping displayed files on screen after their turn completes.
+ *
+ * From 0.1.6 the chat folds a completed turn's work — every tool row, this
+ * card included — behind one "used N s" disclosure, and from 0.1.7 that is the
+ * default (`transcriptView: standard`). A viewer whose purpose is putting a
+ * file in front of the user then hides it the moment the answer lands. The
+ * harness's own deliverables solve the same problem through two public
+ * surfaces, and this module uses the same two:
+ *
+ * - a Conversation Definition (`uiConversation.events.register`) that folds a
+ *   turn's events into Turn-scoped data — here, the turn's successful
+ *   `display_file` results; and
+ * - an entry in the chat's `conversation.chat.turnTail` list, which renders
+ *   between a completed turn's closing reply and its action row, outside the
+ *   fold. The component lives in `ViewerTail.tsx`.
+ *
+ * A `display_file` called from inside `run_code` never appears as a
+ * `tool/call`: the code-mode bridge logs it as `tool/ptc-dispatch-start` and
+ * `tool/ptc-dispatch`, and neither carries a turn number, so the turn-keyed
+ * Definition above cannot be routed one. Two more Definitions cover it, using
+ * the engine's own placement instead: each nested display starts a context
+ * that records the turn the engine located it in and links to the nested
+ * display before it, and each `turn/end` starts a context that walks that
+ * chain back through its own turn and publishes what it finds. The engine
+ * replays a start whenever the predecessor it read changes, which keeps the
+ * chain honest when older history loads. The same turn-end context records the
+ * turn's last human input, which the 0.1.7 chat's fold rule needs and which a
+ * `user/message` event cannot be routed to a turn to report either.
+ *
+ * Everything here is pure and structurally typed: the events come from a
+ * session log this build may not have written, and the Definition contract is
+ * declared by a package (`dsh-client-ui-conversation` 0.1.6+) that older
+ * trains do not publish in this shape.
+ * @module @crosery/dsh-viewer/client/turn-tail
+ */
+import { type DisplayValue } from '../contract.ts';
+/** Definition kind, and the key the turn's data is published under. */
+export declare const VIEWER_TURN_DATA = "crosery-viewer";
+/** Definition kind of one `display_file` dispatched from inside `run_code`. */
+export declare const VIEWER_NESTED = "crosery-viewer-nested";
+/** Definition kind of one human input message. */
+export declare const VIEWER_INPUT = "crosery-viewer-input";
+/** Definition kind, and Turn data key, of what a completed turn collects at its end. */
+export declare const VIEWER_TURN_END = "crosery-viewer-turn-end";
+/** The chat's own Turn data key for its fold boundaries (`dsh-client-ui-chat` 0.1.6+). */
+export declare const CHAT_TURN_PROCESS = "turn-process";
+/** One file a turn displayed. */
+export interface TurnDisplay {
+    /** Log sequence of the settled result. */
+    seq: number;
+    /** The call that displayed it. */
+    callId: string;
+    /** What the card shows. */
+    value: DisplayValue;
+}
+/** Turn-scoped data this Definition publishes. */
+export interface ViewerTurnData {
+    displayed: readonly TurnDisplay[];
+}
+/** The Definition's per-turn accumulator. */
+export interface ViewerTurnState {
+    turn: number;
+    /** `display_file` calls of this turn, by call id. */
+    calls: ReadonlySet<string>;
+    displayed: readonly TurnDisplay[];
+}
+/** The slice of a session event this module reads. */
+export interface EventLike {
+    type?: unknown;
+    seq?: unknown;
+    data?: unknown;
+    /** How a surface event entered the log; replacement copies are model-only. */
+    surfaceOp?: unknown;
+}
+/** A Definition match, as far as this module reads one. */
+export interface MatchLike {
+    event: EventLike;
+    /** Where the engine placed the event: `{ kind: 'turn' | 'step', turn: { turn } }` inside a turn. */
+    location?: unknown;
+}
+/** The engine's backward lookup, handed to a Definition's `start`. */
+export interface ReaderLike {
+    previous?(kind: string): {
+        state?: unknown;
+    } | undefined;
+}
+/** One nested display, linked to the nested display before it. */
+export interface NestedDisplay {
+    /** The turn the engine located the dispatch in, when it resolved one. */
+    turn: number | undefined;
+    /** The display, when the dispatch succeeded with a displayable result. */
+    display: TurnDisplay | undefined;
+    previous: NestedDisplay | undefined;
+}
+/** One human input message, where the engine placed it. */
+export interface HumanInput {
+    turn: number | undefined;
+    seq: number;
+}
+/** Turn-scoped data published when a turn ends. */
+export interface ViewerTurnEndData {
+    /** `display_file` results dispatched from inside `run_code` during the turn, oldest first. */
+    nested: readonly TurnDisplay[];
+    /** Log sequence of the turn's last human input message, when it had one. */
+    lastInputSeq?: number | undefined;
+}
+/** The turn-end Definition's state. */
+export interface ViewerTurnEndState extends ViewerTurnEndData {
+    turn: number;
+}
+/**
+ * The card payload a settled `display_file` result carries.
+ *
+ * The same recovery the tool row performs: the presentation metadata first,
+ * then the plugin's own envelope for a result written without it.
+ * @param data - the `tool/result` event's data.
+ * @returns the payload, or `undefined` when the result is not a displayable success.
+ */
+export declare function displayedValueOf(data: unknown): DisplayValue | undefined;
+/**
+ * The Conversation Definition that collects each turn's displayed files.
+ *
+ * Shaped after the harness's own deliverables Definition: `turn/start` opens a
+ * turn's context, `display_file` calls are remembered by id, and their
+ * successful results are appended in log order. Nothing is published as a view
+ * node — only Turn data, which the tail entry reads.
+ */
+export declare const viewerTurnDefinition: {
+    kind: string;
+    match(event: EventLike): {
+        id: string;
+        role: "start" | "update";
+    } | null;
+    start(_context: unknown, match: MatchLike): ViewerTurnState;
+    update(context: {
+        state: ViewerTurnState;
+    }, match: MatchLike): ViewerTurnState;
+    buildLocationData(context: {
+        state?: ViewerTurnState | undefined;
+    }, scope: string, previous?: {
+        kind?: string;
+        turn?: number;
+        key?: string;
+        value?: ViewerTurnData;
+    } | null): {
+        kind: "turn";
+        turn: number;
+        key: string;
+        value: ViewerTurnData;
+    } | null;
+};
+/**
+ * Each `display_file` dispatched from inside `run_code`, chained in log order.
+ *
+ * Keyed by the sub-call id, one context per dispatch, publishing nothing on
+ * its own: the turn-end Definition reads the chain. The payload is recovered
+ * the way the nested tool row recovers it — a nested dispatch has no
+ * presentation metadata, so from the plugin's own envelope.
+ */
+export declare const nestedDisplayDefinition: {
+    kind: string;
+    match(event: EventLike): {
+        id: string;
+        role: "start";
+    } | null;
+    start(_context: unknown, match: MatchLike, reader?: ReaderLike): NestedDisplay;
+    update(context: {
+        state: NestedDisplay;
+    }): NestedDisplay;
+    publication(): "none";
+};
+/**
+ * Each human input message: the prompt that opens a turn, and anything the
+ * user sends while it runs (a steer, or a message the turn picks up).
+ *
+ * The same messages the chat renders as `user` and `steering` rows — an
+ * appended `user/message` whose source is the user. Injected context is not
+ * one, and neither is the context row that wakes a turn: the chat counts that
+ * as input too, but it only ever opens a turn, which the fold rule ignores.
+ */
+export declare const humanInputDefinition: {
+    kind: string;
+    match(event: EventLike): {
+        id: string;
+        role: "start";
+    } | null;
+    start(_context: unknown, match: MatchLike): HumanInput;
+    update(context: {
+        state: HumanInput;
+    }): HumanInput;
+    publication(): "none";
+};
+/**
+ * What a turn collects once it ends, from the Definitions that cannot be
+ * routed to it by turn number.
+ *
+ * Started by `turn/end`, so it reads each chain once, backwards from the end
+ * of the turn, and stops at the first entry the engine placed in another turn.
+ */
+export declare const turnEndDefinition: {
+    kind: string;
+    match(event: EventLike): {
+        id: string;
+        role: "start";
+    } | null;
+    start(_context: unknown, match: MatchLike, reader?: ReaderLike): ViewerTurnEndState;
+    update(context: {
+        state: ViewerTurnEndState;
+    }): ViewerTurnEndState;
+    buildLocationData(context: {
+        state?: ViewerTurnEndState | undefined;
+    }, scope: string, previous?: {
+        kind?: string;
+        turn?: number;
+        key?: string;
+        value?: ViewerTurnEndData;
+    } | null): {
+        kind: "turn";
+        turn: number;
+        key: string;
+        value: ViewerTurnEndData;
+    } | null;
+};
+/** Every Definition the turn tail's data comes from, in registration order. */
+export declare const viewerTurnDefinitions: readonly [{
+    kind: string;
+    match(event: EventLike): {
+        id: string;
+        role: "start" | "update";
+    } | null;
+    start(_context: unknown, match: MatchLike): ViewerTurnState;
+    update(context: {
+        state: ViewerTurnState;
+    }, match: MatchLike): ViewerTurnState;
+    buildLocationData(context: {
+        state?: ViewerTurnState | undefined;
+    }, scope: string, previous?: {
+        kind?: string;
+        turn?: number;
+        key?: string;
+        value?: ViewerTurnData;
+    } | null): {
+        kind: "turn";
+        turn: number;
+        key: string;
+        value: ViewerTurnData;
+    } | null;
+}, {
+    kind: string;
+    match(event: EventLike): {
+        id: string;
+        role: "start";
+    } | null;
+    start(_context: unknown, match: MatchLike, reader?: ReaderLike): NestedDisplay;
+    update(context: {
+        state: NestedDisplay;
+    }): NestedDisplay;
+    publication(): "none";
+}, {
+    kind: string;
+    match(event: EventLike): {
+        id: string;
+        role: "start";
+    } | null;
+    start(_context: unknown, match: MatchLike): HumanInput;
+    update(context: {
+        state: HumanInput;
+    }): HumanInput;
+    publication(): "none";
+}, {
+    kind: string;
+    match(event: EventLike): {
+        id: string;
+        role: "start";
+    } | null;
+    start(_context: unknown, match: MatchLike, reader?: ReaderLike): ViewerTurnEndState;
+    update(context: {
+        state: ViewerTurnEndState;
+    }): ViewerTurnEndState;
+    buildLocationData(context: {
+        state?: ViewerTurnEndState | undefined;
+    }, scope: string, previous?: {
+        kind?: string;
+        turn?: number;
+        key?: string;
+        value?: ViewerTurnEndData;
+    } | null): {
+        kind: "turn";
+        turn: number;
+        key: string;
+        value: ViewerTurnEndData;
+    } | null;
+}];
+/** The slice of the tail owner's `turn` this module reads. */
+export interface TurnLike {
+    status?: unknown;
+    start?: unknown;
+    end?: unknown;
+    data?: {
+        get?: (key: string) => unknown;
+    } | undefined;
+}
+/**
+ * Whether the user spoke again after the turn got to work: the 0.1.7 chat's
+ * `hasInterleavedInput`, reproduced from the data the tail can read.
+ *
+ * The chat anchors a turn's process at its first assistant or tool activity
+ * (`controlAnchorSeq`, published as its `turn-process` data). Input before
+ * that opened the turn; input after it was interleaved. With no activity at
+ * all the anchor is the turn's own start, and the chat counts every input as
+ * opening.
+ * @param turn - the tail owner's turn.
+ * @returns true when the turn holds human input after its process began.
+ */
+export declare function hasInterleavedInput(turn: TurnLike): boolean;
+/**
+ * Whether the chat keeps this turn's work open, in which case the tool rows
+ * are already on screen and a tail would only repeat them: a turn still
+ * running, one that ended aborted or in error, and — in the chat that has the
+ * rule (0.1.7) — one the user steered while it ran.
+ * @param turn - the tail owner's turn.
+ * @param steeredStaysOpen - whether the running chat keeps a steered turn open.
+ * @returns true when the turn's process is not foldable.
+ */
+export declare function turnStaysOpen(turn: TurnLike, steeredStaysOpen?: boolean): boolean;
+/**
+ * The files a completed turn's tail shows.
+ *
+ * Top-level and `run_code` displays alike; only results logged before the
+ * closing reply belong to it, and a file displayed several times appears once,
+ * where it was last displayed.
+ * @param turn - the tail owner's turn.
+ * @param closingSeq - the closing reply's log sequence.
+ * @param steeredStaysOpen - whether the running chat keeps a steered turn open.
+ * @returns the displays to render, oldest first; empty when there are none.
+ */
+export declare function tailDisplays(turn: TurnLike, closingSeq: number, steeredStaysOpen?: boolean): readonly TurnDisplay[];
+/** An observable boolean the tail reads with `useSyncExternalStore`. */
+export interface FoldSource {
+    getSnapshot(): boolean;
+    subscribe(listener: () => void): () => void;
+    /**
+     * Whether the running chat keeps a turn the user steered open. Read on each
+     * render rather than observed: the answer is fixed by which chat is running.
+     */
+    keepsSteeredTurnsOpen?(): boolean;
+}
+/**
+ * Whether a transcript mode folds completed turns.
+ *
+ * `verbose` (0.1.7) never folds; every other mode does on the trains that have
+ * the turn tail, including the unset value, whose default is `standard` on
+ * 0.1.7 and `compact` on 0.1.6.
+ * @param mode - the persisted `transcriptView`, verbatim.
+ * @returns whether the tail should carry the turn's displays.
+ */
+export declare function foldsCompletedTurns(mode: unknown): boolean;
+/**
+ * Follow the chat's transcript preference, read from the chat's own settings
+ * form (`configForms.get('ui-chat')`).
+ *
+ * Looked up on every read rather than once: the form service arrives with the
+ * settings plugin, which need not have activated before this one. A train with
+ * no such form is treated as folding — its default.
+ *
+ * The form's existence also tells the two chats with a turn tail apart. Every
+ * 0.1.7 chat requires `configForms` and keeps a steered turn open; no 0.1.6
+ * chat has either, and folds a steered turn like any other.
+ * @param forms - reads the optional `configForms` service.
+ * @returns the fold preference as an observable.
+ */
+export declare function foldSourceOf(forms: () => unknown): FoldSource;

package/lib/types/contract.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Viewer taxonomy, field names, and wire shapes shared by both halves.
+ *
+ * Deliberately free of `@deepseek-ai/schemastery` and of every `node:` import:
+ * the browser half imports this module, so a validator or a Node builtin
+ * reaching it would be inlined into (or break) the client bundle. The Host
+ * schema is built over this module in `settings.ts`.
+ */
+/** Wire name of the display tool this plugin registers. */
+export declare const DISPLAY_TOOL = "display_file";
+/**
+ * Wire name of the shipped `dsh-tool-fs` image reader. This plugin does not own
+ * it — it only registers a card for it, so an image the model pulled in through
+ * the shipped tool is shown as a picture too instead of a bare text row.
+ */
+export declare const READ_IMAGE_TOOL = "read_image";
+/** Wire name of the shipped text read, whose binary-media calls get redirected. */
+export declare const READ_TOOL = "read";
+/** Settings namespace this plugin owns. */
+export declare const VIEWER_SETTINGS_NAMESPACE = "crosery-viewer";
+/**
+ * HTTP route serving one asset's bytes to the browser half.
+ *
+ * Scoped, because a duplicate exact route fails the WHOLE plugin tree at boot,
+ * not just the offender.
+ */
+export declare const ASSET_ROUTE = "/crosery/dsh-viewer/asset";
+/**
+ * How the browser half renders one file.
+ *
+ * The axis is "which element plays this", not "what is this file" — `svg` and
+ * `png` are both `image` because both go in an `<img>`, and everything with no
+ * player at all lands on `file`, which still gets a card with the file's facts
+ * and a link. There is no kind that renders nothing.
+ */
+export type ViewerKind = 'image' | 'video' | 'audio' | 'pdf' | 'document' | 'html' | 'file';
+/** One extension's classification. */
+interface MediaSpec {
+    /** Which element plays it. */
+    readonly kind: ViewerKind;
+    /** Content type the asset route sends, and the card's declared type. */
+    readonly mediaType: string;
+}
+/** Media type of a raster the durable attachment service admits. */
+export type ModelImageMediaType = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif';
+/** {@link ModelImageMediaType} as a runtime set, for narrowing replayed JSON. */
+export declare const MODEL_IMAGE_MEDIA_TYPES: readonly ModelImageMediaType[];
+/**
+ * Lowercased extension (dot included) to its classification.
+ *
+ * Only formats a mainstream browser actually plays are listed: an entry here is
+ * a promise that the card will render something, so a codec the browser would
+ * refuse belongs on the `file` fallback instead of in this table.
+ */
+export declare const MEDIA_TABLE: Readonly<Record<string, MediaSpec>>;
+/** Classification used for an extension {@link MEDIA_TABLE} does not list. */
+export declare const UNKNOWN_MEDIA: MediaSpec;
+/**
+ * The extensions whose bytes the durable attachment service admits, mapped to
+ * the media type it verifies them as. A file outside this set can still be
+ * displayed — it just cannot enter model context, because there is no durable
+ * attachment to reference it by.
+ */
+export declare const MODEL_IMAGE_EXTENSIONS: Readonly<Record<string, ModelImageMediaType>>;
+/**
+ * Viewer kinds whose bytes are useless as UTF-8 text, so a `read` naming one is
+ * a mistake worth correcting rather than a decode that yields replacement
+ * characters. `html` is absent on purpose: reading HTML source is a legitimate
+ * text read, and displaying it is a different intent.
+ */
+export declare const OPAQUE_KINDS: readonly ViewerKind[];
+/**
+ * Extract a path's lowercased extension, dot included.
+ *
+ * Hand-rolled rather than `node:path`'s `extname` because the browser half
+ * calls this too. A leading dot is a dotfile, not an empty extension, and both
+ * separators are honored so a Windows-style path from a remote workspace still
+ * classifies.
+ * @param filePath - the raw path as the model wrote it; not yet resolved.
+ * @returns the extension including its dot, or `undefined` when there is none.
+ */
+export declare function extensionOf(filePath: string): string | undefined;
+/**
+ * Classify a path into the element that will render it.
+ * @param filePath - the raw path as the model wrote it.
+ * @returns the viewer kind and the content type the asset route will send;
+ *   {@link UNKNOWN_MEDIA} for anything the table does not list.
+ */
+export declare function classifyPath(filePath: string): MediaSpec;
+/**
+ * The media type the attachment service would verify this path's bytes as.
+ * @param filePath - the raw path as the model wrote it.
+ * @returns the admissible media type, or `undefined` when the bytes could never
+ *   become a durable attachment.
+ */
+export declare function modelImageMediaTypeForPath(filePath: string): ModelImageMediaType | undefined;
+/**
+ * Whether a `read` naming this path is decoding bytes that are not text.
+ * @param filePath - the raw path as the model wrote it.
+ * @returns true when the path names an opaque binary medium.
+ */
+export declare function isOpaqueMediaPath(filePath: string): boolean;
+/**
+ * Durable image facts for a raster that also reached the attachment store.
+ *
+ * Structurally the attachment service's `ImageAttachmentRef` minus the fields a
+ * card never reads. Restated instead of imported so the browser half stays free
+ * of Host packages; the Host half projects a real reference into this shape.
+ */
+export interface ModelImage {
+    /** Opaque durable storage id; never a filesystem path or a bearer URL. */
+    attachmentId: string;
+    /** Media type verified from the stored bytes. */
+    mediaType: ModelImageMediaType;
+    /** Exact encoded byte length. */
+    bytes: number;
+    /** Intrinsic encoded width in pixels. */
+    width: number;
+    /** Intrinsic encoded height in pixels. */
+    height: number;
+    /** Display name stripped of local path information. */
+    name?: string;
+}
+/**
+ * Canonical `display_file` outcome — what `execute` returns, what a `run_code`
+ * program receives, and (verbatim) what rides `tool/result` as presentation
+ * metadata so a reopened session rebuilds the same card.
+ */
+export interface DisplayValue {
+    /** The backend-resolved path that was displayed. */
+    path: string;
+    /** Which element the card renders. */
+    kind: ViewerKind;
+    /** Content type the asset route sends for this file. */
+    mediaType: string;
+    /** Byte size, or 0 when the backend does not report one. */
+    bytes: number;
+    /**
+     * Same-origin signed URL the card loads. Absent when the filesystem backend
+     * exposes no local path for the target (a remote workspace), in which case an
+     * admissible raster still reaches the card through {@link ModelImage}.
+     */
+    assetUrl?: string;
+    /** Present only for a raster this call committed to the attachment store. */
+    image?: ModelImage;
+    /**
+     * Why there is nothing to render, when the call succeeded but produced no
+     * viewable bytes — a document whose conversion is unavailable, typically.
+     * The card shows this verbatim instead of a generic placeholder.
+     */
+    unavailable?: string;
+    /**
+     * Whether the image ALSO entered model context. False is the ordinary
+     * outcome for every non-raster and for every text-only model route: the file
+     * is on the user's screen, not in the model's context.
+     */
+    inContext: boolean;
+}
+/** Narrow one unknown value to {@link ModelImage}. */
+export declare function modelImageFrom(value: unknown): ModelImage | undefined;
+/**
+ * Narrow opaque live or replayed result metadata to a {@link DisplayValue}.
+ *
+ * Defensive because the browser side reads data written by an older version of
+ * this plugin (or by nothing at all). Malformed metadata returns `undefined` so
+ * the card falls back to a plain row instead of throwing during replay.
+ * @param meta - the `tool/result` metadata, verbatim.
+ * @returns the validated projection, or `undefined` when absent or malformed.
+ */
+export declare function displayValueFrom(meta: unknown): DisplayValue | undefined;
+/**
+ * Render a byte count the way a file manager does.
+ * @param bytes - non-negative byte count.
+ * @returns a short human string, or an empty string when the size is unknown.
+ */
+export declare function formatBytes(bytes: number): string;
+/** Durable settings section owned by this plugin. */
+export interface ViewerSettings {
+    /** Whether to register the `display_file` tool at all. */
+    tool: boolean;
+    /**
+     * Whether to refuse `read` on an opaque binary medium and point the model at
+     * `display_file`. Off leaves the shipped `read` free to decode a raster as
+     * UTF-8, which yields replacement characters rather than an error.
+     */
+    redirectRead: boolean;
+    /**
+     * Whether `display_file` may also put an admissible raster into model context
+     * on routes that accept image input. Off keeps every display UI-only, which is
+     * the cheaper choice when the files are for the human, not the model.
+     */
+    feedModel: boolean;
+    /**
+     * Whether to hide the shipped `read_image` from every agent, making
+     * `display_file` the single image entry point. On is the default because the
+     * two tools overlap on model-context ingestion, and a model offered both uses
+     * both — the same image then enters context twice in one turn.
+     */
+    supersedeReadImage: boolean;
+}
+/** Field carrying {@link ViewerSettings.tool}. */
+export declare const TOOL_FIELD = "tool";
+/** Field carrying {@link ViewerSettings.redirectRead}. */
+export declare const REDIRECT_READ_FIELD = "redirectRead";
+/** Field carrying {@link ViewerSettings.feedModel}. */
+export declare const FEED_MODEL_FIELD = "feedModel";
+/** Field carrying {@link ViewerSettings.supersedeReadImage}. */
+export declare const SUPERSEDE_READ_IMAGE_FIELD = "supersedeReadImage";
+export {};