@zseven-w/dsh-openpencil 0.1.0-rc.1

package/lib/renderer.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Offscreen rendering + signed HTTP delivery for `.op` documents.
+ *
+ * `openpencil_render` snapshots the source document, uses OpenPencil's own
+ * headless exporter for design-fidelity PNG output, retaining every
+ * top-level frame for the conversation gallery, and only invokes Jian
+ * as an explicitly disclosed runtime-preview fallback when the exact binary
+ * is unavailable. Content-addressed image/document capabilities bind name,
+ * byte length, and SHA-256 without exposing arbitrary host paths. Serving
+ * refuses symbolic links so a delivered artifact cannot be redirected.
+ *
+ * Model-visible result values stay plain JSON; the browser-only envelope
+ * rides `presentationMeta` (see `tool.ts`). Never return an ImageBlock.
+ * @module dsh-openpencil/renderer
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { JsonValue } from '@deepseek-ai/dsh-tools';
+import type { ViewerGrant } from './viewer-assets.js';
+import type { EditorGrant } from './editor-host.js';
+import { OPENPENCIL_RENDER_TOOL_NAME } from './tool-names.js';
+/** HTTP prefix owned by the render capability route. */
+export declare const RENDER_ROUTE_PREFIX = "/_dsh/dsh-openpencil/render";
+/** Presentation metadata key reserved by the browser half of this package. */
+export declare const PRESENTATION_META_KEY = "$dshOpenPencil";
+/** Refuse to deliver anything above this size (also enforced at render time). */
+export declare const MAX_RENDER_BYTES: number;
+/** Refuse unusually large source documents before copying them into managed state. */
+export declare const MAX_DOCUMENT_BYTES: number;
+/** One render delivery capability. */
+interface LegacyRenderTokenPayload {
+    v: 1;
+    path: string;
+    filename: string;
+    bytes: number;
+}
+interface ArtifactTokenPayload {
+    v: 2;
+    kind: 'image' | 'document';
+    filename: string;
+    bytes: number;
+    sha256: string;
+}
+type RenderTokenPayload = LegacyRenderTokenPayload | ArtifactTokenPayload;
+/** Browser grant paired to one rendered PNG. */
+export interface RenderGrant {
+    path: string;
+    previewUrl: string;
+    downloadUrl: string;
+    width?: number;
+    height?: number;
+    id?: string;
+    name?: string;
+    index?: number;
+}
+/** One immutable top-level frame retained from an exact render. */
+export interface RenderFrame {
+    path: string;
+    filename: string;
+    mimeType: 'image/png';
+    bytes: number;
+    width: number;
+    height: number;
+    sha256: string;
+    /** Canonical top-level node identity and user-facing name. */
+    id?: string;
+    name?: string;
+    index?: number;
+}
+export interface DocumentSnapshot {
+    path: string;
+    filename: string;
+    mimeType: 'application/json';
+    bytes: number;
+    sha256: string;
+}
+export interface DocumentGrant extends DocumentSnapshot {
+    url: string;
+    previewUrl: string;
+    downloadUrl: string;
+}
+/** Canonical result shape the tool returns and the envelope enriches. */
+export interface RenderResult {
+    path: string;
+    filename: string;
+    mimeType: 'image/png';
+    kind: 'image';
+    description: string;
+    sourceTool: typeof OPENPENCIL_RENDER_TOOL_NAME;
+    previewIntent: 'image';
+    bytes: number;
+    width?: number;
+    height?: number;
+    sha256?: string;
+    sourcePath?: string;
+    renderer?: 'openpencil' | 'jian';
+    rendererBinary?: string;
+    fidelity?: 'exact' | 'runtime-preview';
+    warnings?: string[];
+    /** Ordered top-level frames. The first entry is also exposed by legacy image fields. */
+    frames?: RenderFrame[];
+    frameCount?: number;
+    editable?: boolean;
+    /** Live-card intent: expand the editor once after a newly-created design renders. */
+    autoOpenEditor?: boolean;
+    document?: DocumentSnapshot;
+    note?: string;
+}
+/** Plugin-managed state root (mirrors the dsh-vision-toolkit convention). */
+export declare function stateRoot(): string;
+/** Plugin-managed render output directory. */
+export declare function renderDir(): string;
+/** Content-addressed immutable `.op` snapshots served to the web viewer. */
+export declare function snapshotDir(): string;
+/** Load or atomically create the per-DSH-home signing key. */
+export declare function prepareRenderAccessKey(): Promise<Buffer>;
+/** Signed render-capability encoder and safe route handler. */
+export declare class RenderAccessController {
+    private readonly key;
+    private routeCount;
+    constructor(key: Buffer);
+    /** Whether at least one HTTP carrier currently owns the route. */
+    get routeAvailable(): boolean;
+    /** Mark one route attachment; the returned disposer removes that attachment. */
+    attachRoute(): () => void;
+    /** Mint a deterministic, tamper-evident capability for one render result. */
+    sign(result: RenderResult): string;
+    /** Mint an immutable capability without embedding an absolute local path. */
+    signArtifact(artifact: Omit<ArtifactTokenPayload, 'v'>): string;
+    /** Verify and decode one capability without touching the filesystem. */
+    verify(token: string): RenderTokenPayload | undefined;
+    /** Serve one GET/HEAD capability request. */
+    handle(req: IncomingMessage, res: ServerResponse): Promise<void>;
+}
+/** Expand `~` / `~/` prefixes (the model frequently writes home-relative paths). */
+export declare function expandUserHome(raw: string): string;
+/**
+ * Validate the `.op` input path: expand `~`, resolve against the session
+ * workspace, realpath, and require a regular `.op` file.
+ */
+export declare function resolveInputFile(raw: string, cwd: string): Promise<string>;
+/** Freeze source bytes before rendering so preview and web viewer cannot diverge. */
+export declare function createDocumentSnapshot(input: string): Promise<DocumentSnapshot>;
+/** Locate the exact OpenPencil renderer, preferring an explicit override. */
+export declare function findOpenPencilBinary(): string | undefined;
+/** Locate the `jian` binary: env override, known build location, then PATH. */
+export declare function findJianBinary(): string;
+/** Parse the physical size from `jian render`'s success line. */
+export declare function parseRenderSize(stdout: string): {
+    width?: number;
+    height?: number;
+};
+/**
+ * Run `jian render` for one input and wait for the PNG on disk.
+ * Observes `signal` so caller cancellation stops the child promptly.
+ */
+export declare function runJianRender(options: {
+    binary: string;
+    input: string;
+    out: string;
+    width?: number;
+    height?: number;
+    scale?: number;
+    signal: AbortSignal;
+}): Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export declare class RendererBinaryMissingError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Render all top-level active-page nodes through OpenPencil's exact scene exporter. */
+export declare function runOpenPencilRender(options: {
+    binary: string;
+    input: string;
+    scale?: number;
+    signal: AbortSignal;
+}): Promise<{
+    png: string;
+    frames: Array<{
+        png: string;
+        id?: string;
+        name?: string;
+        index: number;
+    }>;
+    warnings: string[];
+    stdout: string;
+    stderr: string;
+}>;
+/**
+ * Purely enrich a canonical tool-result value with a browser render grant.
+ * Returns the value unchanged when no route/artifact exists.
+ */
+export declare function projectRenderGrant(value: JsonValue, controller: RenderAccessController, viewer?: ViewerGrant, editor?: EditorGrant): JsonValue;
+/** Reserve a fresh output path inside the managed render directory. */
+export declare function createRenderOutput(): Promise<string>;
+/** Stat + cap-check a freshly rendered PNG. */
+export declare function verifyRenderOutput(out: string): Promise<{
+    bytes: number;
+    width: number;
+    height: number;
+    sha256: string;
+}>;
+export {};