dsh-side-chat-plus 0.3.1

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

@@ -0,0 +1,218 @@
+/**
+ * Client API client for the /sidechat JSON routes (same fetch pattern the
+ * better-sidebar built-ins use). All requests are same-origin POSTs; the host
+ * fence (loopback/trusted authority) passes them naturally.
+ */
+/** One API failure envelope. */
+export interface SidechatApiError {
+    code: string;
+    message: string;
+}
+/** The unwrapped success value of one API method. */
+export type SidechatResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: SidechatApiError;
+};
+/** Side-chat list row. */
+export interface SidechatListItem {
+    childId: string;
+    running: boolean;
+    runningSince?: number;
+}
+/** Browser-submitted prompt content part (text or base64 image). */
+export type PromptContentPart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    mediaType: string;
+    data: string;
+    name?: string;
+};
+/** One durable image reference returned by the host transcript. */
+export interface SidechatImageRef {
+    attachmentId: string;
+    mediaType: string;
+    bytes: number;
+    width: number;
+    height: number;
+    name?: string;
+}
+/** One transcript message block. */
+export type SidechatMessageBlock = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    ref: SidechatImageRef;
+} | {
+    type: 'reasoning';
+    text: string;
+};
+/** One transcript message. */
+export interface SidechatMessage {
+    role: 'user' | 'assistant';
+    blocks: SidechatMessageBlock[];
+}
+/** Model / effort directory (provider groups → models → reasoning efforts). */
+export interface SidechatDirectory {
+    groups: Array<{
+        id: string;
+        name: string;
+        models: Array<{
+            id: string;
+            name: string;
+            description?: string;
+            reasoning?: {
+                efforts: Array<{
+                    id: string;
+                    name: string;
+                }>;
+                defaultEffort?: string;
+            };
+        }>;
+    }>;
+}
+/** Permission options. */
+export interface SidechatPermissions {
+    options: Array<{
+        value: string;
+        name: string;
+        description?: string;
+    }>;
+    current: string;
+}
+export declare const api: {
+    start: (args: {
+        parentSessionId: string;
+        content: PromptContentPart[];
+        lookupEnabled: boolean;
+        provider?: string;
+        model?: string;
+        reasoningEffort?: string;
+        preset?: string;
+    }) => Promise<SidechatResult<{
+        childId: string;
+        provider: string;
+        model: string;
+        reasoningEffort?: string;
+    }>>;
+    followup: (args: {
+        childId: string;
+        content: PromptContentPart[];
+        lookupEnabled: boolean;
+    }) => Promise<SidechatResult<{
+        accepted: true;
+    }>>;
+    list: (args: {
+        parentSessionId: string;
+    }) => Promise<SidechatResult<{
+        items: SidechatListItem[];
+    }>>;
+    history: (args: {
+        childId: string;
+    }) => Promise<SidechatResult<{
+        messages: SidechatMessage[];
+    }>>;
+    stop: (args: {
+        childId: string;
+    }) => Promise<SidechatResult<{
+        accepted: true;
+    }>>;
+    selectModel: (args: {
+        childId: string;
+        provider: string;
+        model: string;
+        reasoningEffort?: string;
+    }) => Promise<SidechatResult<{
+        accepted: true;
+    }>>;
+    selectPermission: (args: {
+        childId: string;
+        presetName: string;
+    }) => Promise<SidechatResult<{
+        accepted: true;
+    }>>;
+    summarize: (args: {
+        parentSessionId: string;
+        text: string;
+        provider?: string;
+        model?: string;
+        reasoningEffort?: string;
+        locale?: string;
+    }) => Promise<SidechatResult<{
+        summary: string;
+    }>>;
+    inject: (args: {
+        parentSessionId: string;
+        text: string;
+        summary?: string;
+    }) => Promise<SidechatResult<{
+        accepted: true;
+    }>>;
+    directory: () => Promise<SidechatResult<SidechatDirectory>>;
+    permissions: () => Promise<SidechatResult<SidechatPermissions>>;
+    limits: () => Promise<SidechatResult<{
+        mediaTypes: string[];
+        maxImageBytes: number;
+        maxImagesPerMessage: number;
+        maxMessageImageBytes: number;
+        maxImagePixels: number;
+    }>>;
+    attachment: (args: {
+        childId: string;
+        attachmentId: string;
+    }) => Promise<SidechatResult<{
+        mediaType: string;
+        data: string;
+    }>>;
+    inherit: (args: {
+        parentSessionId: string;
+    }) => Promise<SidechatResult<{
+        provider: string;
+        model: string;
+        reasoningEffort?: string;
+    }>>;
+    commands: (args: {
+        childId: string;
+    }) => Promise<SidechatResult<{
+        commands: Array<{
+            name: string;
+            description: string;
+        }>;
+    }>>;
+    command: (args: {
+        childId: string;
+        line: string;
+    }) => Promise<SidechatResult<{
+        executed: boolean;
+    }>>;
+    state: (args: {
+        childId: string;
+    }) => Promise<SidechatResult<{
+        plan: {
+            active: boolean;
+            pending: boolean;
+        };
+        goal: {
+            id: string;
+            objective: string;
+        } | null;
+    }>>;
+    settingsGet: () => Promise<SidechatResult<{
+        value?: unknown;
+        revision?: number;
+    }>>;
+    settingsUpdate: (patch: Record<string, unknown>, expectedRevision?: number) => Promise<SidechatResult<{
+        value?: unknown;
+        revision?: number;
+    }>>;
+    dispose: (args: {
+        childId: string;
+    }) => Promise<SidechatResult<{
+        accepted: true;
+    }>>;
+};

package/lib/types/client/attachments/AttachmentRail.d.ts

@@ -0,0 +1,39 @@
+/** One rail thumbnail; strings arrive resolved (zero-cordis atom). */
+export interface AttachmentRailItem {
+    /** Stable identity for the React key. */
+    id: string;
+    /** Object or data URL rendered as the thumbnail. */
+    previewUrl: string;
+    /** Image alt text (display name with the owner's fallback applied). */
+    alt: string;
+    /** Accessible label of the item's remove control. */
+    removeLabel: string;
+}
+/** Rail-level strings the owner resolves from its own locale namespace. */
+export interface AttachmentRailLabels {
+    /** Accessible name of the rail group. */
+    group: string;
+    /** Thumbnail tooltip inviting the original-image preview. */
+    open: string;
+    /** Accessible label of the left paging arrow. */
+    scrollLeft: string;
+    /** Accessible label of the right paging arrow. */
+    scrollRight: string;
+}
+/**
+ * Horizontal thumbnail rail over the caller's draft attachments.
+ *
+ * The rail scrolls with its scrollbar hidden; overflow is announced by edge
+ * arrows recomputed from scroll geometry on scroll, item-count changes, and
+ * rail size changes (a ResizeObserver on the rail element, so sidebar or panel
+ * resizes count, not only window resizes). A vertical wheel pans the rail
+ * horizontally and is consumed exclusively, a newly added item is revealed at
+ * the rail's end, and each thumbnail opens on a single click while its remove
+ * control sits inside the card. The owner decides mounting.
+ */
+export declare function AttachmentRail<T extends AttachmentRailItem>({ items, labels, onOpen, onRemove }: {
+    items: readonly T[];
+    labels: AttachmentRailLabels;
+    onOpen: (item: T) => void;
+    onRemove: (item: T) => void;
+}): import("react").JSX.Element;

package/lib/types/client/attachments/DropOverlay.d.ts

@@ -0,0 +1,18 @@
+/** Drop-overlay strings the owner resolves from its own locale namespace. */
+export interface DropOverlayLabels {
+    /** Headline inviting the drop, or naming why it is unavailable. */
+    title: string;
+    /** Limits line under the title; shown only while drops are accepted. */
+    desc?: string | undefined;
+}
+/**
+ * Full-viewport invitation shown while a file drag is over the page.
+ * Decoration only: `pointer-events: none` keeps drag targeting on the page
+ * below, so the owner's document-level listeners keep an accurate enter/leave
+ * count and own accept/reject. Rendered through a body portal for the same
+ * transformed-ancestor reason as the lightbox.
+ */
+export declare function DropOverlay({ disabled, labels }: {
+    disabled: boolean;
+    labels: DropOverlayLabels;
+}): import("react").ReactPortal;

package/lib/types/client/attachments/ImageLightbox.d.ts

@@ -0,0 +1,20 @@
+/** Preview strings the owner resolves from its own locale namespace. */
+export interface ImageLightboxLabels {
+    /** Accessible name of the preview dialog. */
+    dialog: string;
+    /** Accessible label of the close control. */
+    close: string;
+}
+/**
+ * Document-level original-image preview opened by clicking a thumbnail.
+ * Closes on Escape, backdrop press, or the close control, and restores focus
+ * to the opener on unmount. Rendered through a body portal: an opener inside
+ * a transformed or filtered ancestor would otherwise trap the fixed backdrop
+ * in that ancestor's box instead of covering the viewport.
+ */
+export declare function ImageLightbox({ src, alt, labels, onClose }: {
+    src: string;
+    alt: string;
+    labels: ImageLightboxLabels;
+    onClose: () => void;
+}): import("react").ReactPortal;

package/lib/types/client/attachments/MessageImage.d.ts

@@ -0,0 +1,38 @@
+import type { SidechatImageRef } from '../api.ts';
+import type { ImageLightboxLabels } from './ImageLightbox.tsx';
+/** Loads one durable image's bytes into a displayable URL. */
+export type ImageLoader = (ref: SidechatImageRef) => Promise<string>;
+/** Message-image strings the owner resolves from its own locale namespace. */
+export interface MessageImageLabels {
+    /** Fallback display name for an unnamed image. */
+    image: string;
+    /** Thumbnail tooltip inviting the original-image preview. */
+    open: string;
+    /** Accessible thumbnail label; receives the image's display name. */
+    openNamed: (label: string) => string;
+    /** Loading placeholder shown until bytes resolve. */
+    loading: string;
+    /** Retry-control label shown when the load fails. */
+    loadFailed: string;
+    /** Lightbox strings forwarded to the opened preview. */
+    lightbox: ImageLightboxLabels;
+}
+/**
+ * Compact history renderer with retryable loading and click-to-open original
+ * preview. A lone image renders at its `singleFit` size; an image among
+ * several renders as a fixed 64px square tile.
+ */
+export declare function MessageImage({ image, load, variant, labels }: {
+    image: SidechatImageRef;
+    load: ImageLoader;
+    variant: 'single' | 'tile';
+    labels: MessageImageLabels;
+}): import("react").JSX.Element;
+/** Wrapping image group: a lone image renders large, several render as 64px
+ * square tiles. */
+export declare function ImageGallery({ images, load, align, labels }: {
+    images: readonly SidechatImageRef[];
+    load: ImageLoader;
+    align: 'start' | 'end';
+    labels: MessageImageLabels;
+}): import("react").JSX.Element | null;

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

@@ -0,0 +1,18 @@
+/**
+ * Image presentation owned by this plugin.
+ *
+ * The DSH attachment UI package registers these through conversation slots and
+ * exports no React components (`packages/client/AGENTS.md`: a feature plugin
+ * MUST NOT runtime-import another feature plugin's values — UI crosses
+ * packages through slots). A standalone side panel sits outside the
+ * conversation slot tree and cannot reach those slots, so it carries its own
+ * presentation, built only on `ui-primitives` (a sanctioned static owner).
+ */
+export { AttachmentRail } from './AttachmentRail.tsx';
+export type { AttachmentRailItem, AttachmentRailLabels } from './AttachmentRail.tsx';
+export { DropOverlay } from './DropOverlay.tsx';
+export type { DropOverlayLabels } from './DropOverlay.tsx';
+export { ImageGallery, MessageImage } from './MessageImage.tsx';
+export type { ImageLoader, MessageImageLabels } from './MessageImage.tsx';
+export { ImageLightbox } from './ImageLightbox.tsx';
+export type { ImageLightboxLabels } from './ImageLightbox.tsx';

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

@@ -0,0 +1,6 @@
+import type { Context } from '../context-types.ts';
+import './layout.css';
+/** Services required before mounting. */
+export declare const inject: string[];
+/** Client plugin body. */
+export declare function apply(ctx: Context): void;

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

@@ -0,0 +1,178 @@
+/**
+ * Client locale dictionaries for dsh-side-chat (zh + en), registered under the
+ * `sidechat` namespace.
+ */
+export declare const LOCALE_NS = "sidechat";
+export declare const zh: {
+    'ask.new': string;
+    'ask.continue': string;
+    'panel.title': string;
+    'panel.empty': string;
+    'panel.close': string;
+    'panel.input.placeholder': string;
+    'panel.send': string;
+    'panel.stop': string;
+    'panel.lookup': string;
+    'panel.model': string;
+    'panel.provider': string;
+    'panel.effort': string;
+    'panel.permission': string;
+    'panel.noModel': string;
+    'panel.effortDefault': string;
+    'panel.expand': string;
+    'panel.collapse': string;
+    'panel.dispose': string;
+    'panel.delete': string;
+    'panel.deleteAll': string;
+    'panel.error': string;
+    'panel.running': string;
+    'panel.copy': string;
+    'panel.copied': string;
+    'panel.footnotes': string;
+    'panel.think': string;
+    'panel.commands': string;
+    'command.model': string;
+    'command.permission': string;
+    'plan.chipTitle': string;
+    'plan.chipAria': string;
+    'goal.label': string;
+    'image.railGroup': string;
+    'image.railOpen': string;
+    'image.railScrollLeft': string;
+    'image.railScrollRight': string;
+    'image.remove': string;
+    'image.label': string;
+    'image.open': string;
+    'image.loading': string;
+    'image.loadFailed': string;
+    'image.lightboxDialog': string;
+    'image.close': string;
+    'image.dropTitle': string;
+    'image.dropDesc': string;
+    'image.unsupported': string;
+    'image.tooMany': string;
+    'image.fileTooLarge': string;
+    settingsNav: string;
+    'settings.lookupTitle': string;
+    'settings.lookupDesc': string;
+    'settings.sendImmediatelyTitle': string;
+    'settings.sendImmediatelyDesc': string;
+    'settings.defaultPromptTitle': string;
+    'settings.defaultPromptDesc': string;
+    'settings.defaultPromptPlaceholder': string;
+    'settings.bringModeTitle': string;
+    'settings.bringModeDesc': string;
+    'settings.bringModeDraftTitle': string;
+    'settings.bringModeDraftDesc': string;
+    'settings.bringModeContextTitle': string;
+    'settings.bringModeContextDesc': string;
+    'insert.direct': string;
+    'insert.summarize': string;
+    'insert.summarizing': string;
+    'insert.failed': string;
+    'insert.summarizeFailed': string;
+    'insert.contextSummary': string;
+    'insert.summarizeContextSummary': string;
+    'question.options': string;
+    'question.option': string;
+    'question.bringAll': string;
+    'question.bringAllNew': string;
+    'question.bringOne': string;
+    'question.bringOneNew': string;
+    'question.bringing': string;
+    'question.failed': string;
+    'question.delete': string;
+    'question.deleteAll': string;
+    'question.collapse': string;
+    'question.expand': string;
+    'question.allPrompt': string;
+    'question.onePrompt': string;
+    'question.openHint': string;
+};
+export declare const en: {
+    'ask.new': string;
+    'ask.continue': string;
+    'panel.title': string;
+    'panel.empty': string;
+    'panel.close': string;
+    'panel.input.placeholder': string;
+    'panel.send': string;
+    'panel.stop': string;
+    'panel.lookup': string;
+    'panel.model': string;
+    'panel.provider': string;
+    'panel.effort': string;
+    'panel.permission': string;
+    'panel.noModel': string;
+    'panel.effortDefault': string;
+    'panel.expand': string;
+    'panel.collapse': string;
+    'panel.dispose': string;
+    'panel.delete': string;
+    'panel.deleteAll': string;
+    'panel.error': string;
+    'panel.running': string;
+    'panel.copy': string;
+    'panel.copied': string;
+    'panel.footnotes': string;
+    'panel.think': string;
+    'panel.commands': string;
+    'command.model': string;
+    'command.permission': string;
+    'plan.chipTitle': string;
+    'plan.chipAria': string;
+    'goal.label': string;
+    'image.railGroup': string;
+    'image.railOpen': string;
+    'image.railScrollLeft': string;
+    'image.railScrollRight': string;
+    'image.remove': string;
+    'image.label': string;
+    'image.open': string;
+    'image.loading': string;
+    'image.loadFailed': string;
+    'image.lightboxDialog': string;
+    'image.close': string;
+    'image.dropTitle': string;
+    'image.dropDesc': string;
+    'image.unsupported': string;
+    'image.tooMany': string;
+    'image.fileTooLarge': string;
+    settingsNav: string;
+    'settings.lookupTitle': string;
+    'settings.lookupDesc': string;
+    'settings.sendImmediatelyTitle': string;
+    'settings.sendImmediatelyDesc': string;
+    'settings.defaultPromptTitle': string;
+    'settings.defaultPromptDesc': string;
+    'settings.defaultPromptPlaceholder': string;
+    'settings.bringModeTitle': string;
+    'settings.bringModeDesc': string;
+    'settings.bringModeDraftTitle': string;
+    'settings.bringModeDraftDesc': string;
+    'settings.bringModeContextTitle': string;
+    'settings.bringModeContextDesc': string;
+    'insert.direct': string;
+    'insert.summarize': string;
+    'insert.summarizing': string;
+    'insert.failed': string;
+    'insert.summarizeFailed': string;
+    'insert.contextSummary': string;
+    'insert.summarizeContextSummary': string;
+    'question.options': string;
+    'question.option': string;
+    'question.bringAll': string;
+    'question.bringAllNew': string;
+    'question.bringOne': string;
+    'question.bringOneNew': string;
+    'question.bringing': string;
+    'question.failed': string;
+    'question.delete': string;
+    'question.deleteAll': string;
+    'question.collapse': string;
+    'question.expand': string;
+    'question.allPrompt': string;
+    'question.onePrompt': string;
+    'question.openHint': string;
+};
+export type SidechatLocaleKey = keyof typeof zh;