@yadsh/dsh-qa-surface 0.1.0

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

@@ -0,0 +1,43 @@
+import type { ResolvedQaSurfaceConfig } from "../types.js";
+export interface QaRouteSnapshot {
+    readonly pathname: string;
+    readonly active: boolean;
+}
+interface NavigationHistory {
+    pushState(data: unknown, unused: string, url?: string | URL | null): void;
+    replaceState(data: unknown, unused: string, url?: string | URL | null): void;
+}
+interface NavigationWindow {
+    readonly location: {
+        readonly pathname: string;
+        readonly search?: string;
+    };
+    readonly history: NavigationHistory;
+    addEventListener(type: "popstate", listener: () => void): void;
+    removeEventListener(type: "popstate", listener: () => void): void;
+}
+export declare function matchesQaRoute(pathname: string, route: ResolvedQaSurfaceConfig["route"]): boolean;
+/** Observable route matcher with reversible History API instrumentation. */
+export declare class QaRouteController {
+    private readonly target;
+    private readonly listeners;
+    private route;
+    private enabled;
+    private snapshot;
+    private readonly originalPushState;
+    private readonly originalReplaceState;
+    private readonly wrappedPushState;
+    private readonly wrappedReplaceState;
+    private disposed;
+    constructor(target?: NavigationWindow);
+    private readonly removePopstate;
+    getSnapshot: () => QaRouteSnapshot;
+    subscribe: (listener: () => void) => (() => void);
+    configure(config: ResolvedQaSurfaceConfig, ready?: boolean): void;
+    dispose(): void;
+    private project;
+    private restoreRedirectedPath;
+    private refresh;
+}
+export {};
+//# sourceMappingURL=QaRouteController.d.ts.map

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

@@ -0,0 +1,59 @@
+import type { HostDescriptionSource, IApiClient } from "@deepseek-ai/dsh-client-connection/client";
+import type { ISessions, SessionListState } from "@deepseek-ai/dsh-client-runtime/client";
+import type { QaSessionState, ResolvedQaSurfaceConfig } from "../types.js";
+type QaSessionsApi = Pick<IApiClient["sessions"], "create" | "selectModel">;
+export interface StorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+export interface QaSessionControllerOptions {
+    readonly sessions: ISessions;
+    readonly api: QaSessionsApi;
+    readonly connection: HostDescriptionSource;
+    readonly config: ResolvedQaSurfaceConfig;
+    readonly storage?: StorageLike;
+    readonly timeoutMs?: number;
+}
+/** The only module that couples QA behavior to DSH Session/client APIs. */
+export declare class QaSessionController {
+    private readonly listeners;
+    private readonly sessions;
+    private readonly api;
+    private readonly connection;
+    private readonly config;
+    private readonly storage;
+    private readonly timeoutMs;
+    private state;
+    private session;
+    private unsubscribeSession;
+    private readonly unsubscribeConnection;
+    private ensuring;
+    private operationError;
+    private admissionPending;
+    private connectedOnce;
+    private disposed;
+    private generation;
+    constructor(options: QaSessionControllerOptions);
+    getSnapshot: () => QaSessionState;
+    subscribe: (listener: () => void) => (() => void);
+    ensureSession(): Promise<void>;
+    send(text: string): Promise<boolean>;
+    stop(): Promise<void>;
+    reset(): Promise<void>;
+    dispose(): void;
+    private ensureSessionNow;
+    private createSession;
+    private bind;
+    private unbind;
+    private waitForConnection;
+    private publish;
+    private fail;
+    private storageKey;
+    private readPersisted;
+    private persist;
+    private clearPersisted;
+    private emit;
+}
+export type { SessionListState };
+//# sourceMappingURL=QaSessionController.d.ts.map

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

@@ -0,0 +1,16 @@
+import type { HostDescriptionSource, IApiClient } from "@deepseek-ai/dsh-client-connection/client";
+import type { ISessions } from "@deepseek-ai/dsh-client-runtime/client";
+import type { InjectFace, PropsRuntime } from "@deepseek-ai/dsh-client-ui-slots";
+import type { QaConfigController } from "./QaConfigController.js";
+import type { QaRouteController } from "./QaRouteController.js";
+export interface QaSurfaceFace {
+    readonly route: QaRouteController;
+    readonly config: QaConfigController;
+    readonly sessions: ISessions;
+    readonly api: Pick<IApiClient["sessions"], "create" | "selectModel">;
+    readonly connection: HostDescriptionSource;
+}
+type QaSurfaceProps = PropsRuntime<"shell.overlay"> & InjectFace<QaSurfaceFace>;
+export declare function QaSurface(props: QaSurfaceProps): import("react/jsx-runtime").JSX.Element | null;
+export {};
+//# sourceMappingURL=QaSurface.d.ts.map

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

@@ -0,0 +1,7 @@
+import type { ConversationSnapshot } from "@deepseek-ai/dsh-client-runtime/client";
+import type { QaMessage } from "../types.js";
+/** Project only end-user-safe text from the public DSH conversation snapshot. */
+export declare function projectTranscript(snapshot: ConversationSnapshot, options?: {
+    readonly showToolActivity?: boolean;
+}): readonly QaMessage[];
+//# sourceMappingURL=QaTranscriptAdapter.d.ts.map

package/lib/types/client/components/Markdown.d.ts

@@ -0,0 +1,5 @@
+/** Deliberately small, HTML-free Markdown renderer for assistant-visible text. */
+export declare function Markdown({ text }: {
+    readonly text: string;
+}): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=Markdown.d.ts.map

package/lib/types/client/components/QaComposer.d.ts

@@ -0,0 +1,11 @@
+export interface QaComposerProps {
+    readonly placeholder: string;
+    readonly canSend: boolean;
+    readonly canStop: boolean;
+    readonly running: boolean;
+    readonly showStop: boolean;
+    readonly onSend: (text: string) => Promise<boolean>;
+    readonly onStop: () => Promise<void>;
+}
+export declare function QaComposer(props: QaComposerProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=QaComposer.d.ts.map

package/lib/types/client/components/QaMessage.d.ts

@@ -0,0 +1,8 @@
+import type { QaMessage as QaMessageModel } from "../../types.js";
+export interface QaMessageProps {
+    readonly message: QaMessageModel;
+    readonly renderMarkdown: boolean;
+    readonly showTimestamp: boolean;
+}
+export declare function QaMessage({ message, renderMarkdown, showTimestamp, }: QaMessageProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=QaMessage.d.ts.map

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

@@ -0,0 +1,19 @@
+import type { Context } from "@deepseek-ai/cordis";
+import type { ConnectionHandle } from "@deepseek-ai/dsh-client-connection/client";
+import type { ISessions } from "@deepseek-ai/dsh-client-runtime/client";
+import type { SettingsScopeBinder } from "@deepseek-ai/dsh-client-ui-settings/client";
+declare module "@deepseek-ai/cordis" {
+    interface Context {
+        connection: ConnectionHandle;
+        sessions: ISessions;
+        settingsScope: SettingsScopeBinder;
+    }
+}
+export declare const inject: string[];
+/** Register the route-aware, full-frame QA entry in the additive overlay slot. */
+export declare function apply(ctx: Context): void;
+export { QaConfigController } from "./QaConfigController.js";
+export { QaRouteController, matchesQaRoute } from "./QaRouteController.js";
+export { QaSessionController } from "./QaSessionController.js";
+export { projectTranscript } from "./QaTranscriptAdapter.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,2 @@
+export declare const QA_SURFACE_STYLES: string;
+//# sourceMappingURL=styles.d.ts.map

package/lib/types/config.d.ts

@@ -0,0 +1,5 @@
+import z from "@deepseek-ai/schemastery";
+import type { QaSurfaceConfig } from "./types.js";
+export declare const ConfigSchema: z<QaSurfaceConfig>;
+export { DEFAULT_QA_SURFACE_CONFIG, normalizeRoutePath, resolveConfig, } from "./resolve-config.js";
+//# sourceMappingURL=config.d.ts.map

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

@@ -0,0 +1,9 @@
+import type { WebServer } from "@deepseek-ai/dsh-host-webserver";
+import type { ResolvedQaSurfaceConfig } from "./types.js";
+/**
+ * DSH 0.1.1 static hosting returns 404 for missing paths. Redirect a browser
+ * navigation through its canonical index entry; the client restores the
+ * requested pathname before activating the QA overlay.
+ */
+export declare function registerQaNavigationRoute(webServer: Pick<WebServer, "register">, config: ResolvedQaSurfaceConfig): () => void;
+//# sourceMappingURL=host-route.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,29 @@
+import { Service, type Context } from "@deepseek-ai/cordis";
+import type { QaSurfaceConfig, ResolvedQaSurfaceConfig } from "./types.js";
+export declare const name = "qa-surface";
+export declare const inject: readonly string[];
+export declare const QA_SURFACE_SETTINGS_NAMESPACE: import("@deepseek-ai/dsh-settings").SettingsNamespace;
+export declare const Config: import("@deepseek-ai/schemastery").default<QaSurfaceConfig>;
+declare module "@deepseek-ai/cordis" {
+    interface Context {
+        qaSurface: QaSurface;
+    }
+}
+/** Small Host companion: validates config and exposes it through DSH settings. */
+export declare class QaSurface extends Service {
+    static inject: readonly string[];
+    static Config: import("@deepseek-ai/schemastery").default<QaSurfaceConfig>;
+    private source;
+    private readonly logger;
+    private webServer;
+    private disposeRoute;
+    private routeKey;
+    constructor(ctx: Context, entry?: QaSurfaceConfig);
+    getConfig(): ResolvedQaSurfaceConfig;
+    private refreshRoute;
+}
+export { ConfigSchema, DEFAULT_QA_SURFACE_CONFIG, normalizeRoutePath, resolveConfig, } from "./config.js";
+export { registerQaNavigationRoute } from "./host-route.js";
+export type * from "./types.js";
+export default QaSurface;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/navigation-marker.d.ts

@@ -0,0 +1,3 @@
+/** Query hand-off used only by the Host navigation compatibility redirect. */
+export declare const QA_NAVIGATION_MARKER = "__dsh_qa_route";
+//# sourceMappingURL=navigation-marker.d.ts.map

package/lib/types/resolve-config.d.ts

@@ -0,0 +1,6 @@
+import type { QaSurfaceConfig, ResolvedQaSurfaceConfig } from "./types.js";
+export declare const DEFAULT_QA_SURFACE_CONFIG: ResolvedQaSurfaceConfig;
+export declare function normalizeRoutePath(value: string): string;
+/** Materialize defaults and enforce route/session/model safety constraints. */
+export declare function resolveConfig(input?: QaSurfaceConfig): ResolvedQaSurfaceConfig;
+//# sourceMappingURL=resolve-config.d.ts.map

package/lib/types/types.d.ts

@@ -0,0 +1,114 @@
+export type QaSessionPolicy = "browser-persistent" | "new-on-load" | "fixed";
+export interface QaSurfaceConfig {
+    readonly enabled?: boolean;
+    readonly route?: {
+        readonly path?: string;
+        readonly matchChildren?: boolean;
+    };
+    readonly branding?: {
+        readonly title?: string;
+        readonly subtitle?: string;
+        readonly welcomeMessage?: string;
+        readonly placeholder?: string;
+        readonly logoUrl?: string | null;
+    };
+    readonly session?: {
+        readonly policy?: QaSessionPolicy;
+        readonly storageKey?: string;
+        readonly workspaceId?: string | null;
+        readonly fixedSessionId?: string | null;
+        readonly agentPreset?: string | null;
+        readonly provider?: string | null;
+        readonly model?: string | null;
+        readonly reasoningEffort?: string | null;
+    };
+    readonly ui?: {
+        readonly showHeader?: boolean;
+        readonly showReset?: boolean;
+        readonly showStop?: boolean;
+        readonly showTimestamps?: boolean;
+        readonly showToolActivity?: boolean;
+        readonly showReasoning?: boolean;
+        readonly renderMarkdown?: boolean;
+        readonly maxContentWidth?: number;
+    };
+    readonly suggestedQuestions?: readonly string[];
+    readonly interaction?: {
+        readonly approvals?: "blocked";
+        readonly questions?: "unsupported";
+    };
+    readonly embedding?: {
+        readonly frameAncestors?: string | null;
+    };
+}
+export interface ResolvedQaSurfaceConfig {
+    readonly enabled: boolean;
+    readonly route: {
+        readonly path: string;
+        readonly matchChildren: boolean;
+    };
+    readonly branding: {
+        readonly title: string;
+        readonly subtitle: string;
+        readonly welcomeMessage: string;
+        readonly placeholder: string;
+        readonly logoUrl: string | null;
+    };
+    readonly session: {
+        readonly policy: QaSessionPolicy;
+        readonly storageKey: string;
+        readonly workspaceId: string | null;
+        readonly fixedSessionId: string | null;
+        readonly agentPreset: string | null;
+        readonly provider: string | null;
+        readonly model: string | null;
+        readonly reasoningEffort: string | null;
+    };
+    readonly ui: {
+        readonly showHeader: boolean;
+        readonly showReset: boolean;
+        readonly showStop: boolean;
+        readonly showTimestamps: boolean;
+        readonly showToolActivity: boolean;
+        readonly showReasoning: false;
+        readonly renderMarkdown: boolean;
+        readonly maxContentWidth: number;
+    };
+    readonly suggestedQuestions: readonly string[];
+    readonly interaction: {
+        readonly approvals: "blocked";
+        readonly questions: "unsupported";
+    };
+    readonly embedding: {
+        readonly frameAncestors: string | null;
+    };
+}
+export type QaMessage = {
+    readonly id: string;
+    readonly role: "user";
+    readonly text: string;
+    readonly status: "committed";
+    readonly timestamp?: number;
+} | {
+    readonly id: string;
+    readonly role: "assistant";
+    readonly text: string;
+    readonly status: "streaming" | "committed" | "failed";
+    readonly timestamp?: number;
+} | {
+    readonly id: string;
+    readonly role: "system";
+    readonly text: string;
+    readonly status: "info" | "error";
+    readonly timestamp?: number;
+};
+export type QaSessionPhase = "idle" | "creating" | "ready" | "running" | "reconnecting" | "blocked" | "error";
+export interface QaSessionState {
+    readonly phase: QaSessionPhase;
+    readonly sessionId: string | null;
+    readonly messages: readonly QaMessage[];
+    readonly error: string | null;
+    readonly canSend: boolean;
+    readonly canStop: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,137 @@
+{
+  "name": "@yadsh/dsh-qa-surface",
+  "version": "0.1.0",
+  "description": "A focused end-user QA surface backed by native DeepSeek Harness sessions",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xarleyn/dsh-plugins.git",
+    "directory": "plugins/dsh-qa-surface"
+  },
+  "homepage": "https://github.com/xarleyn/dsh-plugins/tree/main/plugins/dsh-qa-surface#readme",
+  "bugs": {
+    "url": "https://github.com/xarleyn/dsh-plugins/issues"
+  },
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "external": [
+        "@deepseek-ai/dsh-client-ui-slots"
+      ],
+      "inject": [
+        "@deepseek-ai/dsh-api-gateway",
+        "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-layout",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-theme"
+      ],
+      "platform": "web"
+    }
+  },
+  "files": [
+    "lib/**/*.js",
+    "lib/**/*.js.map",
+    "lib/types/**/*.d.ts",
+    "cordis.patch.yml",
+    "compatibility.json",
+    "README.md",
+    "CHANGELOG.md",
+    "docs/*.md",
+    "SPEC-dsh-qa-surface.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('lib', { recursive: true, force: true })\"",
+    "build": "pnpm run clean && tsdown && tsc -p tsconfig.build.json",
+    "lint": "eslint src tests scripts tsdown.config.ts",
+    "format": "prettier --check . --end-of-line auto",
+    "format:write": "prettier --write . --end-of-line auto",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "verify": "node scripts/verify-package.mjs",
+    "smoke:packed": "node scripts/smoke-packed-dsh.mjs",
+    "e2e:browser": "node scripts/smoke-packed-dsh.mjs --browser",
+    "check": "pnpm run format && pnpm run lint && pnpm run typecheck && pnpm run test && pnpm run build && pnpm run verify",
+    "prepack": "pnpm run build && pnpm run verify",
+    "prepublishOnly": "pnpm run check"
+  },
+  "keywords": [
+    "deepseek",
+    "deepseek-harness",
+    "dsh",
+    "dsh-plugin",
+    "qa",
+    "chat",
+    "web-ui"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "catalog:dsh",
+    "@deepseek-ai/schemastery": "catalog:dsh",
+    "@deepseek-ai/dsh-api-gateway": "catalog:dsh",
+    "@deepseek-ai/dsh-client-connection": "catalog:dsh",
+    "@deepseek-ai/dsh-client-runtime": "catalog:dsh",
+    "@deepseek-ai/dsh-client-ui-layout": "catalog:dsh",
+    "@deepseek-ai/dsh-client-ui-settings": "catalog:dsh",
+    "@deepseek-ai/dsh-client-ui-slots": "catalog:dsh",
+    "@deepseek-ai/dsh-client-ui-theme": "catalog:dsh",
+    "@deepseek-ai/dsh-host-webserver": "catalog:dsh",
+    "@deepseek-ai/dsh-settings": "catalog:dsh",
+    "react": "^18.2.0"
+  },
+  "dependencies": {
+    "@yadsh/dsh-plugin-log": "workspace:^"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "catalog:dsh-dev",
+    "@deepseek-ai/schemastery": "catalog:dsh-dev",
+    "@deepseek-ai/dsh-api-gateway": "catalog:dsh-dev",
+    "@deepseek-ai/dsh-client-connection": "catalog:dsh-dev",
+    "@deepseek-ai/dsh-client-runtime": "catalog:dsh-dev",
+    "@deepseek-ai/dsh-client-ui-layout": "catalog:dsh-dev",
+    "@deepseek-ai/dsh-client-ui-settings": "catalog:dsh-dev",
+    "@deepseek-ai/dsh-client-ui-slots": "catalog:dsh-dev",
+    "@deepseek-ai/dsh-client-ui-theme": "catalog:dsh-dev",
+    "@deepseek-ai/dsh-host-webserver": "catalog:dsh-dev",
+    "@deepseek-ai/dsh-settings": "catalog:dsh-dev",
+    "@testing-library/react": "^16.3.0",
+    "@types/node": "catalog:tooling",
+    "@types/react": "catalog:frontend-dev",
+    "@yadsh/dsh-config": "workspace:^",
+    "eslint": "catalog:tooling",
+    "jsdom": "catalog:tooling",
+    "playwright": "catalog:tooling",
+    "prettier": "catalog:tooling",
+    "react": "catalog:frontend-dev",
+    "tsdown": "catalog:tooling",
+    "typescript": "catalog:plugin-tooling",
+    "vitest": "catalog:tooling"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}