@crosery/dsh-viewer 0.0.0-stage → 0.3.0

package/lib/types/asset-route.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The asset route: bytes for one signed reference, with range support.
+ *
+ * Range handling is not an optimization here — it is what makes `<video>` and
+ * `<audio>` seekable at all. Chrome and Safari will not expose a scrub bar for
+ * a response that does not advertise `accept-ranges`, and Safari refuses to
+ * start playback of a media response that answers a range request with 200.
+ *
+ * Bytes are streamed from the process path rather than pulled through
+ * `ctx.fs.readBytes`, which materializes a whole file in memory: a two-hour
+ * video is exactly the case this plugin exists for. The tradeoff is that the
+ * route is only available on a backend that exposes a local path — `index.ts`
+ * degrades that case to the attachment path for admissible rasters, and to an
+ * unavailable card otherwise.
+ * @module @crosery/dsh-viewer/asset-route
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type ViewerKind } from './contract.ts';
+/** One parsed, satisfiable byte range. */
+interface ByteRange {
+    start: number;
+    end: number;
+}
+/**
+ * Parse a single-range `Range` header against a known size.
+ *
+ * Only the single-range form is honored. A multipart range response is a
+ * different content type with its own framing, and no browser media element
+ * needs one; answering the whole entity is the specified fallback.
+ * @param header - the raw header value, or undefined.
+ * @param size - the entity's total byte length.
+ * @returns the resolved range, `undefined` for no usable range, or `'invalid'`
+ *   when the client named a range that cannot be satisfied.
+ */
+export declare function parseRange(header: string | undefined, size: number): ByteRange | undefined | 'invalid';
+/**
+ * Response headers that keep an inline-served asset from becoming an XSS
+ * vector.
+ *
+ * The route answers on the app's own origin, so a user who opens an asset URL
+ * in a tab navigates to it as a document. For `text/html` and `image/svg+xml`
+ * that document would otherwise run its own script with the app's origin. The
+ * CSP header removes that: `sandbox` puts a navigated HTML asset in an opaque
+ * origin, and `default-src 'none'` leaves an SVG document with no script at
+ * all. Both are inert when the asset is loaded as a subresource, which is the
+ * normal path.
+ * @param kind - the classified viewer kind.
+ * @returns extra headers for this kind, possibly empty.
+ */
+export declare function guardHeaders(kind: ViewerKind): Record<string, string>;
+/** Optional behavior of {@link assetHandler}. */
+export interface AssetHandlerOptions {
+    /**
+     * The converted-document cache. Serving one of its artifacts marks it used,
+     * so the artifact behind a card someone is looking at is not evicted.
+     */
+    cacheDir?: string;
+}
+/**
+ * Build the asset route's handler.
+ * @param secret - a thunk returning the harness MAC key, or `undefined` while
+ *   key material is still loading (the route answers 503 until it resolves).
+ * @param options - optional behavior; see {@link AssetHandlerOptions}.
+ * @returns the `webServer` route handler.
+ */
+export declare function assetHandler(secret: () => Buffer | undefined, options?: AssetHandlerOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+export {};

package/lib/types/asset-token.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Signed asset references: how a card names a file to the asset route without
+ * the route ever trusting a path the browser supplied.
+ *
+ * The design constraint is that a card must survive a harness restart. A card
+ * rebuilt from a replayed session log holds only the URL that was minted months
+ * ago, so an in-process token table would leave every reopened video dead. The
+ * reference is therefore self-contained — the path travels in the URL and a
+ * keyed MAC travels beside it — and the route accepts a path only when the MAC
+ * proves this harness minted it.
+ *
+ * The MAC key is the whole security boundary: without it the route would be an
+ * arbitrary-file-read endpoint on a port the user's browser can reach. It is
+ * generated once per harness home, stored 0600, and never leaves the Host.
+ * @module @crosery/dsh-viewer/asset-token
+ */
+/** Query parameter carrying the base64url-encoded absolute path. */
+export declare const PATH_PARAM = "p";
+/** Query parameter carrying the hex MAC over that path. */
+export declare const SIGNATURE_PARAM = "s";
+/**
+ * Load the harness-local MAC key, generating it on first use.
+ *
+ * Written with the exclusive flag so two harness processes racing on a fresh
+ * home cannot end up with different keys — the loser reads the winner's file
+ * instead of overwriting it, which would have invalidated every URL the winner
+ * had already minted.
+ * @param keyPath - absolute path of the key file inside the harness home.
+ * @returns the raw key bytes.
+ */
+export declare function loadAssetSecret(keyPath: string): Promise<Buffer>;
+/**
+ * Mint the same-origin URL a card loads for one file.
+ * @param secret - the harness MAC key.
+ * @param processPath - the canonical absolute path in the backend's execution
+ *   world, as `ctx.fs.processPath` reports it.
+ * @returns the signed, root-relative asset URL.
+ */
+export declare function assetUrlFor(secret: Buffer, processPath: string): string;
+/**
+ * Recover the path one asset request names, after proving this harness minted
+ * the reference.
+ *
+ * Comparison is constant-time over equal-length buffers; a length mismatch is
+ * rejected before the compare, because `timingSafeEqual` throws on unequal
+ * lengths and a length difference leaks nothing an attacker did not already
+ * choose.
+ * @param secret - the harness MAC key.
+ * @param search - the request URL's query string, leading `?` optional.
+ * @returns the verified absolute path, or `undefined` for a missing, malformed,
+ *   or unsigned reference.
+ */
+export declare function verifyAssetRequest(secret: Buffer, search: string): string | undefined;

package/lib/types/cache.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Bounds on the converted-document cache.
+ *
+ * Every conversion leaves one PDF in a directory beside the asset key, shared
+ * by every profile on the machine. Without a bound that directory only grows:
+ * a user who previews a few documents a day accumulates gigabytes nobody asked
+ * to keep. So the cache is least-recently-used with three caps — age, entry
+ * count and total bytes — and "used" means either converted-or-hit by
+ * `display_file` or served to a card by the asset route, which is what keeps
+ * the artifact behind a card someone is looking at from aging out.
+ *
+ * Pruning is lazy: once when the plugin activates and after each write, never
+ * on a timer. It only ever considers regular files in the cache directory
+ * itself whose names this plugin writes, so a stray file, a symlink or a
+ * subdirectory placed there is never touched, and nothing outside the
+ * directory is reachable at all.
+ * @module @crosery/dsh-viewer/cache
+ */
+/** The three caps one prune enforces. */
+export interface CacheLimits {
+    /** An artifact unused for longer than this is removed. */
+    maxAgeMs: number;
+    /** At most this many artifacts are kept, most recently used first. */
+    maxEntries: number;
+    /** Kept artifacts total at most this many bytes. */
+    maxBytes: number;
+}
+/**
+ * The shipped caps: a month unused, 256 documents, 512 MiB. Generous enough
+ * that a card in an active conversation never loses its artifact; small enough
+ * that the directory stays an unremarkable size on a laptop.
+ */
+export declare const CACHE_LIMITS: CacheLimits;
+/**
+ * Whether a file name is one of this cache's artifacts.
+ * @param name - a bare file name.
+ * @returns true for a name a converter writes.
+ */
+export declare function isArtifactName(name: string): boolean;
+/**
+ * Write an artifact into place.
+ *
+ * The bytes land under a unique partial name beside the artifact — in the cache
+ * directory itself, never in the system temp directory — and are renamed into
+ * place last. Beside it because `rename` only works within one filesystem: a
+ * temp directory on another mount (a Linux `tmpfs` `/tmp`) fails it with
+ * `EXDEV`. Renamed last so a reader either finds no artifact or a complete
+ * one, never a half-written file served to a PDF viewer. The partial name is
+ * one {@link pruneCache} recognizes, so even a process killed mid-write leaves
+ * nothing behind for long; any failure here removes it at once.
+ * @param artifact - the artifact's absolute path.
+ * @param write - writes the complete bytes to the path it is given.
+ */
+export declare function placeArtifact(artifact: string, write: (partial: string) => Promise<void>): Promise<void>;
+/**
+ * Stamp an artifact as used now, if it exists.
+ *
+ * Doubles as the cache-hit test: a successful stamp is a hit, and the stamp is
+ * what moves the artifact to the front of the eviction order.
+ * @param path - the artifact's absolute path.
+ * @returns true when the artifact exists.
+ */
+export declare function useArtifact(path: string): Promise<boolean>;
+/**
+ * Refresh a served file's last-use stamp when it is one of this cache's
+ * artifacts. Any other file the asset route serves — the user's own images and
+ * videos — is left exactly as it is.
+ * @param cacheDir - the cache directory.
+ * @param path - the absolute path the route is serving.
+ * @param mtimeMs - its modification time, as the route's `stat` saw it.
+ * @param now - the current time.
+ */
+export declare function useServedArtifact(cacheDir: string, path: string, mtimeMs: number, now?: number): Promise<void>;
+/**
+ * Enforce the caps once.
+ *
+ * The most recently used artifact always survives, whatever the caps say: it
+ * is the one a card was most likely just handed.
+ * @param cacheDir - the cache directory; a missing directory is an empty cache.
+ * @param limits - the caps to enforce.
+ * @param now - the current time.
+ * @returns the absolute paths removed.
+ */
+export declare function pruneCache(cacheDir: string, limits?: CacheLimits, now?: number): Promise<string[]>;
+/**
+ * Prune in the background.
+ *
+ * Calls that arrive while a prune of the same directory runs fold into one
+ * more pass after it, so a burst of conversions costs two directory scans, not
+ * one per conversion. A failure is logged, never thrown: a cache that could not
+ * be trimmed still serves every card.
+ * @param cacheDir - the cache directory.
+ * @param limits - the caps to enforce.
+ * @returns settles when the directory has been pruned; never rejects.
+ */
+export declare function schedulePrune(cacheDir: string, limits?: CacheLimits): Promise<void>;

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

@@ -0,0 +1,77 @@
+/**
+ * The tool card: one row plus whatever element actually plays the file.
+ *
+ * Registered for both `display_file` and the shipped `read_image`, so an image
+ * the model pulled in through the shipped tool is shown as a picture rather
+ * than as a bare text row on the trains whose `read_image` has no view of its
+ * own (see `client/index.ts` for how the two coexist where it does).
+ *
+ * Two byte sources, in priority order. A signed asset URL streams straight from
+ * the Host and is the only one that can carry video, audio, PDF or HTML — and
+ * the only one that supports range requests, which is what makes a `<video>`
+ * seekable. A durable attachment is the fallback: it is images-only, but it
+ * works when the filesystem backend exposes no local path, and it is the only
+ * source a shipped `read_image` result has at all. From 0.1.7 the chat hands
+ * every tool view its own session-authorized image loader, and the card uses
+ * it; on older trains the plugin's own attachment reader stands in.
+ */
+import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots';
+import { type DisplayValue } from '../contract.ts';
+import { cardModel } from './card-model.ts';
+import { type OwnerImageLoader, type ViewerSources } from './sources.ts';
+/** Business face the plugin injects into every card occurrence. */
+export interface ViewerCardInjected {
+    /**
+     * Resolve one durable attachment into a browser URL scoped to this session.
+     * The fallback for trains whose tool-view owner carries no `loadImage`.
+     * @param attachmentId - the opaque durable id.
+     * @returns a URL valid until the plugin unloads.
+     */
+    loadAttachment: (attachmentId: string) => Promise<string>;
+}
+/** The runtime share this card actually reads off the toolview slot. */
+export interface ViewerCardOwner {
+    /** Wire tool name this entry was dispatched for. */
+    toolName: string;
+    /** Frozen running call or settled result node. */
+    block: Parameters<typeof cardModel>[0];
+    /**
+     * Open a path through the Host: the operating system's default application
+     * up to 0.1.5, the right-Sidebar preview from 0.1.7. Every supported train
+     * supplies it; optional only so a card rendered outside a tool row (the turn
+     * tail) or by a test can omit it.
+     */
+    openFile?: ((path: string) => unknown) | undefined;
+    /** 0.1.7+: the chat's session-authorized loader for durable images. */
+    loadImage?: OwnerImageLoader | undefined;
+}
+/** Full card props: owner share, injected face, and the locale seat. */
+export type ViewerCardProps = ViewerCardOwner & ViewerCardInjected & {
+    t: TranslateNS<'tool.viewer'>;
+};
+/** The element that plays one file, or the reason there is none. */
+export declare function Viewer({ value, sources, t }: {
+    value: DisplayValue;
+    sources: ViewerSources;
+    t: TranslateNS<'tool.viewer'>;
+}): import("react").JSX.Element;
+/**
+ * One settled, displayable file: the header and its player.
+ *
+ * Shared by the tool row and by the turn tail, so a file shown after a turn
+ * completes looks exactly like the one shown while it ran.
+ * @param props - the display, how to reach its bytes, the tool it came from, and `t`.
+ * @returns the card.
+ */
+export declare function DisplayedFile({ value, toolName, sources, t }: {
+    value: DisplayValue;
+    toolName: string;
+    sources: ViewerSources;
+    t: TranslateNS<'tool.viewer'>;
+}): import("react").JSX.Element;
+/**
+ * One `display_file` (or `read_image`) call, as a row plus its player.
+ * @param props - the toolview owner share, the injected loader, and `t`.
+ * @returns the card.
+ */
+export declare function ViewerCard({ toolName, block, t, openFile, loadImage, loadAttachment }: ViewerCardProps): import("react").JSX.Element;

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

@@ -0,0 +1,40 @@
+/**
+ * The turn-tail entry: a completed turn's displayed files, outside the fold.
+ *
+ * Rendered by the chat between a completed turn's closing reply and its action
+ * row, which is the one place a folded turn keeps visible — the harness's own
+ * delivery cards live there for the same reason. See `turn-tail.ts` for where
+ * the data comes from and when it is empty.
+ * @module @crosery/dsh-viewer/client/ViewerTail
+ */
+import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots';
+import { type ViewerCardInjected } from './ViewerCard.tsx';
+import { type FoldSource, type TurnLike } from './turn-tail.ts';
+/** What the plugin injects into the tail entry. */
+export interface ViewerTailInjected extends ViewerCardInjected {
+    /** Whether the chat currently folds completed turns. */
+    folds: FoldSource;
+}
+/** The tail owner's share, as far as this entry reads it. */
+export interface ViewerTailOwner {
+    /** The completed turn. */
+    turn: TurnLike;
+    /** The closing reply's log sequence. */
+    seq: number;
+    /** Open a path through the Host. */
+    openFile?: ((path: string) => unknown) | undefined;
+}
+/** Full tail props: owner share, injected face, and the locale seat. */
+export type ViewerTailProps = ViewerTailOwner & ViewerTailInjected & {
+    t: TranslateNS<'tool.viewer'>;
+};
+/**
+ * The completed turn's displays, or nothing.
+ *
+ * Nothing whenever the rows are on screen anyway — the chat does not fold, or
+ * this turn is still open, aborted, failed, or (0.1.7) was steered — so the
+ * tail never repeats a card the reader can already see.
+ * @param props - owner share, injected face, and `t`.
+ * @returns the tail section, or `null`.
+ */
+export declare function ViewerTail({ turn, seq, openFile, folds, loadAttachment, t }: ViewerTailProps): import("react").JSX.Element | null;

package/lib/types/client/card-model.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Pure derivation of a card's state from one tool block.
+ *
+ * Everything here runs during replay of a session logged by an older build, so
+ * every read is defensive and every failure mode is a narrower card rather than
+ * a throw: a crashing entry is removed from its slot for the rest of the
+ * session, which would take the whole conversation's viewer cards down with it.
+ *
+ * Content blocks are narrowed structurally instead of through the Host's
+ * `ContentBlock` union. The union is merge-extensible, so a build that knows
+ * fewer arms than the log contains must still find the image arm it does know.
+ * @module @crosery/dsh-viewer/client/card-model
+ */
+import { type DisplayValue } from '../contract.ts';
+/**
+ * The slice of one tool-call block this card reads, declared structurally.
+ *
+ * NOT imported from the client shell's package: that block type has lived in
+ * two different packages across harness trains (`dsh-client-runtime` up to
+ * 0.1.1, `dsh-client-ui-chat` from 0.1.2) and the older one stopped publishing
+ * entirely. A type-only import would pin this plugin's toolchain to one train
+ * and make the other fail to typecheck — the same class of breakage as an
+ * import of a removed value export, one compilation later.
+ *
+ * Structure is also what this module actually uses. Every read below is
+ * defensive and every field is optional: the block may be a live call, a
+ * replayed log entry from an older build, or a shape a newer build wrote.
+ */
+export interface ToolCallBlockLike {
+    /** Discriminates the running arm from the settled one. */
+    kind?: string;
+    /** Raw arguments, on the running arm. */
+    argsRaw?: string;
+    /** The settled call this result belongs to. */
+    call?: {
+        argsRaw?: string;
+    } | null;
+    /** Whether the tool reported a failure. */
+    isError?: boolean;
+    /** Model-facing content blocks. */
+    content?: readonly unknown[];
+    /** Structured failure, when there is one. */
+    error?: {
+        code?: string;
+    } | null;
+    /** Presentation metadata this plugin wrote, on the settled arm. */
+    meta?: unknown;
+}
+/** What the card renders right now. */
+export type CardState = 
+/** The call is dispatched and no result has landed. */
+{
+    phase: 'running';
+    path: string | undefined;
+}
+/** The call failed; `message` is the tool's own text. */
+ | {
+    phase: 'failed';
+    path: string | undefined;
+    message: string;
+}
+/** A displayable file, with everything the viewer needs. */
+ | {
+    phase: 'ready';
+    value: DisplayValue;
+}
+/**
+ * The call settled, but this build could not recover a viewer payload from
+ * it — an older log, a truncated window, a shape a newer build wrote. The row
+ * still renders; it just has nothing to play.
+ */
+ | {
+    phase: 'bare';
+    path: string | undefined;
+    message: string;
+};
+/**
+ * Recover the `file_path` argument from either arm of the block.
+ *
+ * The raw arguments are whatever the model emitted, so a parse failure is an
+ * ordinary outcome — a card with no path in its header, not an error.
+ * @param block - the running or settled call.
+ * @returns the requested path, or `undefined` when it cannot be read.
+ */
+export declare function argumentPathOf(block: ToolCallBlockLike): string | undefined;
+/**
+ * Find the first durable image carried by a settled result's content.
+ *
+ * This is what lets the plugin render the SHIPPED `read_image` tool, which
+ * writes no presentation metadata at all: its image rides the model-facing
+ * content blocks, and those are persisted with the result.
+ * @param content - the settled result's content blocks.
+ * @returns the validated image facts, or `undefined` when there is no image.
+ */
+export declare function contentImageOf(content: readonly unknown[]): DisplayValue['image'] | undefined;
+/**
+ * Rebuild a viewer payload from this plugin's own result envelope.
+ *
+ * The recovery path for a NESTED dispatch: the registry projects
+ * `presentationMeta` only for top-level calls, so a `display_file` invoked from
+ * inside `run_code` persists content blocks and nothing else. The envelope is
+ * this plugin's own structured output, and the result is validated through the
+ * same narrowing every replayed payload goes through — including the guard that
+ * refuses an asset URL which is not this plugin's route.
+ * @param content - the settled result's content blocks.
+ * @param inContext - whether the result also carried a durable image block.
+ * @returns the validated payload, or `undefined` when the envelope is not ours.
+ */
+export declare function envelopeValueOf(content: readonly unknown[], inContext: boolean): DisplayValue | undefined;
+/**
+ * Derive the card state for one call.
+ * @param block - the running or settled call.
+ * @param toolName - the wire tool name this entry was dispatched for; it selects
+ *   which recovery path applies, since only `display_file` writes metadata.
+ * @returns the state to render.
+ */
+export declare function cardModel(block: ToolCallBlockLike, toolName: string): CardState;

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

@@ -0,0 +1,54 @@
+/**
+ * What the page the card lives in can do, decided by capability — never by the
+ * user agent.
+ *
+ * The desktop app runs the same web consumer as `dsh web`, so nothing in the
+ * plugin contract tells the two apart. Two facts do. The desktop renderer loads
+ * the app from its own `dsh-app:` scheme, and its preload publishes
+ * `__DSH_HOST_PATHS__` (the dropped-file path bridge) on the main frame only.
+ * Either one means the page is the desktop window, and with it the desktop's
+ * rules that matter to a card: `target=_blank` links to app URLs are silently
+ * denied (only http(s) leaves the window), and media loaded through the app's
+ * protocol forwarder is not seekable on first load (see {@link mediaSourceFor}).
+ * Images and PDF frames behave as in a browser tab — the window keeps
+ * Chromium's PDF viewer — so nothing else branches on this.
+ * @module @crosery/dsh-viewer/client/host
+ */
+/** The globals {@link isDesktopShell} probes. */
+interface HostGlobals {
+    __DSH_HOST_PATHS__?: unknown;
+    location?: {
+        protocol?: string;
+    };
+}
+/**
+ * Whether this page is the desktop app's window.
+ * @param globals - the global object to probe; the real one by default.
+ * @returns true inside the desktop renderer.
+ */
+export declare function isDesktopShell(globals?: HostGlobals): boolean;
+/** The desktop renderer's transport facts (`__DSH_TRANSPORT__`), as far as media needs them. */
+interface TransportGlobals extends HostGlobals {
+    __DSH_TRANSPORT__?: {
+        streamBaseUrl?: unknown;
+    } | undefined;
+}
+/**
+ * The URL a `<video>` or `<audio>` element should load an asset from.
+ *
+ * On the web this is the signed same-origin path unchanged. In the desktop
+ * window a same-origin path travels through the app's `dsh-app:` protocol
+ * forwarder, which drops `Content-Length`; Chromium then treats the FIRST load
+ * of a media URL as an unseekable stream (`seekable` is `[0, 0]`, measured on
+ * 0.1.7-rc.2) even though every response is a correct 206 with
+ * `Content-Range`. The desktop publishes the Host's own loopback address as
+ * `__DSH_TRANSPORT__.streamBaseUrl` — its WebSocket base — and a media element
+ * pointed there issues ordinary HTTP range requests and seeks from the start.
+ * The asset route needs no cookie (it authorizes by signature), so nothing but
+ * the origin changes. Anything other than an http(s) loopback base is ignored.
+ * @param assetUrl - the signed same-origin asset path.
+ * @param globals - the global object to probe; the real one by default.
+ * @returns the URL to hand the media element.
+ */
+export declare function mediaSourceFor(assetUrl: string, globals?: TransportGlobals): string;
+export {};

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

@@ -0,0 +1,59 @@
+/**
+ * Browser half of the viewer plugin.
+ *
+ * Registers one card into the tool-view slot for two keys: the plugin's own
+ * `display_file`, and the shipped `read_image`. The two registrations differ in
+ * one way that matters. Up to 0.1.2 upstream renders `read_image` as a plain
+ * text row, so the plugin's card is the only picture of an image the model
+ * pulled into context. From 0.1.3 upstream ships its own `read_image` view at
+ * the default priority, and a second entry for the same key AT THE SAME
+ * PRIORITY is a hard error in the slot core — which is how v0.1.1 took its own
+ * `display_file` card down with it on 0.1.7. So `read_image` is registered one
+ * step behind the default: the core renders the lowest priority, which is
+ * upstream's view wherever one exists and this card everywhere else.
+ *
+ * Every registration is isolated from the others. A registration that throws
+ * inside `slots.inject` while its slot is already declared rethrows into this
+ * plugin's `apply`, and cordis answers a failed apply by unloading the whole
+ * client half — so one bad key must never be able to take the rest with it.
+ *
+ * From 0.1.6 a third registration keeps displayed files visible after their
+ * turn completes and folds; see `turn-tail.ts`.
+ *
+ * The card's only Host dependencies are durable image bytes — through the
+ * chat's own loader from 0.1.7, through `ctx.sessions` before — and everything
+ * else (video, audio, PDF, HTML) arrives over the Host's signed asset route as an
+ * ordinary same-origin URL.
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+import { type ViewerKey } from './locales.ts';
+export type { CardState } from './card-model.ts';
+export { cardModel, argumentPathOf, contentImageOf } from './card-model.ts';
+export type { ViewerCardInjected, ViewerCardOwner } from './ViewerCard.tsx';
+export { imageLoaderFor, type OwnerImageLoader, type ViewerSources } from './sources.ts';
+export type { ViewerTailInjected } from './ViewerTail.tsx';
+export type { ViewerKey } from './locales.ts';
+export { isDesktopShell, mediaSourceFor } from './host.ts';
+export { READ_IMAGE_PRIORITY, TURN_TAIL_SLOT, VIEWER_NS, contribute, turnTailJoinable } from './registration.ts';
+export { VIEWER_INPUT, VIEWER_NESTED, VIEWER_TURN_DATA, VIEWER_TURN_END, displayedValueOf, foldSourceOf, foldsCompletedTurns, hasInterleavedInput, humanInputDefinition, nestedDisplayDefinition, tailDisplays, turnEndDefinition, turnStaysOpen, viewerTurnDefinition, viewerTurnDefinitions, } from './turn-tail.ts';
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** The viewer card's copy. */
+        'tool.viewer': ViewerKey;
+    }
+}
+/**
+ * Required services: the registration surface and the copy, nothing else.
+ *
+ * `sessions` is read by name when an image actually needs its bytes, not
+ * required: from 0.1.7 the chat supplies its own image loader and the plugin's
+ * reader is only the fallback, and an entry that never activates is a hard
+ * boot failure rather than a graceful skip.
+ */
+export declare const inject: string[];
+export declare const name = "@crosery/dsh-viewer";
+/**
+ * Client plugin body: own the URL cache and register the card under both keys.
+ * @param ctx - client cordis context.
+ */
+export declare function apply(ctx: ClientContext): void;

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

@@ -0,0 +1,11 @@
+/**
+ * Card copy. Two dictionaries with identical key sets — the locale service
+ * fails a namespace whose dictionaries disagree, so a key added here has to be
+ * added to both.
+ */
+/** Dictionary key domain of this plugin's namespace. */
+export type ViewerKey = 'title.image' | 'title.video' | 'title.audio' | 'title.pdf' | 'title.document' | 'title.html' | 'title.file' | 'title.readImage' | 'state.running' | 'state.loading' | 'state.loadFailed' | 'state.retry' | 'state.unavailable' | 'state.unsupported' | 'badge.inContext' | 'badge.screenOnly' | 'action.open' | 'action.openNew' | 'action.openSidebar' | 'action.close' | 'action.expand' | 'action.collapse' | 'media.noVideo' | 'media.noAudio' | 'tail.label';
+/** Simplified Chinese copy. */
+export declare const zh: Record<ViewerKey, string>;
+/** English copy. */
+export declare const en: Record<ViewerKey, string>;

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

@@ -0,0 +1,55 @@
+/**
+ * How the browser half joins the slot registry — the part of `index.ts` that
+ * carries no component, so it can be exercised against the real slot core in
+ * tests on every train.
+ * @module @crosery/dsh-viewer/client/registration
+ */
+/** Namespace owning this card's copy. */
+export declare const VIEWER_NS = "tool.viewer";
+/**
+ * Priority of the `read_image` card: one behind the default, so a view the
+ * harness registers for the same key renders instead (the slot core renders
+ * the lowest priority per key, and refuses a second entry at an occupied one),
+ * and this one renders where there is none.
+ */
+export declare const READ_IMAGE_PRIORITY = 1;
+/** List slot the chat renders after a completed turn's closing reply (0.1.6+). */
+export declare const TURN_TAIL_SLOT = "conversation.chat.turnTail";
+/**
+ * The slot registry as this plugin drives it: by name, including slots whose
+ * declarations this build does not import (the turn tail is declared by
+ * `dsh-client-ui-chat`, which the oldest supported train does not publish).
+ */
+export interface LooseSlots {
+    inject(key: string, callback: () => () => void): () => void;
+    register(options: Record<string, unknown>, component: unknown): () => void;
+    spec?(key: string): {
+        kind?: string;
+    } | undefined;
+}
+/**
+ * Register one slot entry so that its failure stays its own.
+ *
+ * `slots.inject` runs the callback synchronously when the slot is already
+ * declared and rethrows what it throws — into `apply`, where cordis unloads the
+ * whole plugin. The callback therefore never throws: a refused registration is
+ * reported and replaced by a no-op disposer, and every other entry lives on.
+ * @param slots - the slot registry.
+ * @param key - the slot to register into.
+ * @param register - performs the registration; returns its disposer.
+ * @param warn - where a refusal is reported.
+ */
+export declare function contribute(slots: Pick<LooseSlots, 'inject'>, key: string, register: () => () => void, warn?: (message: string, error: unknown) => void): void;
+/**
+ * Whether the turn tail may be joined.
+ *
+ * Up to 0.1.5 the slot is a CHAIN — one winner per turn — so an entry there
+ * would compete with the harness's own delivery cards instead of sitting beside
+ * them. Only the list form (0.1.6+) is joined; a registry that cannot say which
+ * form it has is trusted to be the one the Conversation registry came with.
+ * @param spec - the slot's declared spec, when the registry exposes it.
+ * @returns true for a list slot, or an unknown one.
+ */
+export declare function turnTailJoinable(spec: {
+    kind?: string;
+} | undefined): boolean;