dsh-image-gen 0.10.0 → 0.10.2

package/lib/types/client/tl/trace-playback.d.ts

@@ -0,0 +1,101 @@
+import type { Editor } from 'tldraw';
+import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment';
+interface TraceStep {
+    layer: number;
+    d: string;
+    area: number;
+}
+interface TracePlan {
+    viewBox: [number, number, number, number];
+    fills: string[];
+    steps: TraceStep[];
+}
+export interface CanvasTraceProps {
+    editor: Editor;
+    traceId: string;
+    /** Region count reported by the tool, shown before the plan arrives. */
+    steps: number;
+    /**
+     * The absolutely-positioned host the surface is rendered into. Its rect is
+     * the origin this component must subtract from tldraw's window-relative
+     * screen coordinates.
+     */
+    hostRef?: {
+        readonly current: HTMLDivElement | null;
+    };
+    /**
+     * Receives the finished drawing as a rail image plus the page rectangle it
+     * was drawn in, so the canvas can place it exactly where the playback was.
+     */
+    onLand?: ((attachment: ImageAttachmentRef, placement: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    }) => void | Promise<void>) | undefined;
+    onClose: () => void;
+    lang?: 'zh' | 'en';
+}
+/**
+ * Revealed region count at elapsed time `t`. Squaring the normalised time
+ * gives the first (largest) regions most of the screen time and then speeds up
+ * through the tiny ones, which is the same curve the drawai workbench uses.
+ */
+export declare function traceRevealCount(total: number, elapsedMs: number, durationMs: number): number;
+/** Total playback time for a plan: short plans stay readable, long ones stay bounded. */
+export declare function tracePlaybackDuration(total: number): number;
+/** Paint order prefix: the first `count` steps accumulated per colour layer. */
+export declare function traceLayerPaths(plan: TracePlan, count: number): string[];
+/** Rebuild the finished SVG document from the plan, for download. */
+export declare function tracePlanToSvg(plan: TracePlan): string;
+/**
+ * Draw the finished SVG into a canvas and encode it as PNG.
+ *
+ * SVG reaches the document as a bitmap because tldraw's image shapes render
+ * through `<img>`, where an SVG with only a viewBox has no intrinsic size and
+ * collapses to the 300x150 default. Width and height are injected for the same
+ * reason: without them the browser has nothing to scale from.
+ */
+export declare function rasterizeSvg(svg: string, width: number, height: number): Promise<Blob>;
+/** Upload rasterised bytes as a durable attachment so the canvas can land them. */
+export declare function uploadDrawing(blob: Blob, name: string): Promise<ImageAttachmentRef>;
+/** Rasterise one plan at a bounded resolution, then store it as an attachment. */
+export declare function realizeDrawing(plan: TracePlan, name: string): Promise<ImageAttachmentRef>;
+/** Page-space rectangle the drawing occupies, frozen when the trace starts. */
+export interface TraceAnchor {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/**
+ * Pick the page rectangle for a drawing of `aspect` (w/h): centred on what the
+ * user is looking at right now, at 72% of the viewport. Frozen in page space so
+ * later panning and zooming move it like canvas content instead of resizing it
+ * to the window.
+ */
+export declare function anchorTraceInViewport(viewport: {
+    center: {
+        x: number;
+        y: number;
+    };
+    w: number;
+    h: number;
+}, aspect: number): TraceAnchor;
+export declare function CanvasTrace({ editor, traceId, steps, hostRef, onLand, onClose, lang }: CanvasTraceProps): import("react").JSX.Element;
+/**
+ * Map a page rectangle into the surface's own coordinate space.
+ *
+ * tldraw's screen space is window-relative (`pageToScreen` returns client
+ * coordinates, which is why collaborator cursors need no offset), while the
+ * surface is an absolutely positioned child of the canvas host. Subtracting the
+ * host's own rect is what turns one into the other; without it the drawing is
+ * pushed off the panel and clipped.
+ */
+export declare function projectAnchor(editor: Editor, anchor: TraceAnchor, host: HTMLElement | null): {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+};
+export {};

package/lib/types/image-tool-context.d.ts

@@ -1,3 +1,3 @@
 /** Live, credential-free instructions for the conversation model's image tools. */
 import { type Config } from './config.js';
-export declare function imageToolContext(config: Config): string;
+export declare function imageToolContext(config: Config, configuredProviders?: readonly string[]): string;

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

@@ -1,5 +1,6 @@
 import type { Context } from '@deepseek-ai/cordis';
 import { SubscriptionManager } from './manager.js';
+import { type WebAdmission } from '../web-route.js';
 export { SUBSCRIPTION_LOGIN_ROUTE, SUBSCRIPTION_STATUS_ROUTE } from '../shared.js';
 /** Register the login/status routes on the plugin's web server. */
-export declare function registerSubscriptionRoutes(ctx: Context, manager: SubscriptionManager): void;
+export declare function registerSubscriptionRoutes(ctx: Context, manager: SubscriptionManager, admission?: () => WebAdmission | undefined): void;

package/lib/types/trace-drawing.d.ts

@@ -0,0 +1,102 @@
+/** Named trace styles exposed by the tool. */
+export declare const TRACE_PRESET_NAMES: readonly ["default", "lineart", "photo", "simple"];
+export type TracePresetName = (typeof TRACE_PRESET_NAMES)[number];
+/** Fragment density tiers, mirroring the workbench's three calibrated档. */
+export declare const TRACE_FRAGMENT_NAMES: readonly ["low", "medium", "high"];
+export type TraceFragments = (typeof TRACE_FRAGMENT_NAMES)[number];
+/** One connected region of one colour: a self-contained path plus its area. */
+export interface TraceDrawingStep {
+    /** Index into `fills`; steps sharing a layer share a fill colour. */
+    layer: number;
+    /** SVG path data for this region, including its holes (nonzero winding). */
+    d: string;
+    /** Signed pixel area used for ordering; steps arrive largest first. */
+    area: number;
+}
+/** The replayable drawing: paint `steps` in order, grouped by `fills`. */
+export interface TraceDrawingPlan {
+    viewBox: [number, number, number, number];
+    fills: string[];
+    steps: TraceDrawingStep[];
+}
+/** Numbers the model gets instead of the path data. */
+export interface TraceSummary {
+    width: number;
+    height: number;
+    colors: number;
+    paths: number;
+    loops: number;
+    steps: number;
+    svgChars: number;
+    budget: number;
+    attempts: number;
+    drawnPixels: number | null;
+    exactPixelCoverage: boolean;
+    sourceWidth: number;
+    sourceHeight: number;
+}
+/** Everything one trace produces. */
+export interface TraceOutcome {
+    /** Full SVG document, for export — never sent to the model verbatim. */
+    svg: string;
+    plan: TraceDrawingPlan;
+    /**
+     * Optional pencil pass derived from the same source, played before `plan`.
+     * Null when the caller asked for no sketch or the edge pass found nothing.
+     */
+    sketch: TraceDrawingPlan | null;
+    summary: TraceSummary;
+    /** One-line tuning advice from upstream's own heuristics. */
+    hint: string;
+}
+/**
+ * One complete drawing session: the contour pass an illustrator starts with,
+ * then the colour pass that fills it in.
+ */
+export interface TraceShow {
+    sketch?: TraceDrawingPlan;
+    colour: TraceDrawingPlan;
+}
+/** Trace knobs shared by the decoded-pixels and encoded-bytes entry points. */
+export interface TraceOptions {
+    /** Required: keep or drop the background. There is no automatic answer. */
+    removeBg: boolean;
+    preset?: TracePresetName;
+    fragments?: TraceFragments;
+    /** Palette size, 2–24. Also caps the number of visible colour layers. */
+    colors?: number;
+    /** RDP tolerance in work pixels; lower keeps more contour fidelity. */
+    epsilon?: number;
+    /** Regions under this area are merged into a neighbour. */
+    minArea?: number;
+    /** Long side cap for the work image; defaults to the calibrated 887. */
+    maxLongSide?: number;
+    /** SVG character budget; upstream default is 248000. */
+    budget?: number;
+    /** Derive a pencil sketch to play first; defaults to true. */
+    sketch?: boolean;
+}
+/** One trace over an encoded image. */
+export interface TraceRequest extends TraceOptions {
+    /** Encoded image bytes (PNG is dependency free; JPEG/WebP need sharp). */
+    bytes: Uint8Array;
+}
+/**
+ * Trace an encoded raster into an SVG plus its replayable drawing plan.
+ * @param request - image bytes and trace knobs.
+ * @returns the SVG, the ordered plan, a model-facing summary and a tuning hint.
+ */
+export declare function traceImageToDrawing(request: TraceRequest): Promise<TraceOutcome>;
+/**
+ * Trace an already-decoded RGBA8 raster. Split out from `traceImageToDrawing`
+ * so tests can exercise the pipeline without encoding a PNG first.
+ *
+ * Produces the colour pass plus, unless disabled, a pencil pass derived from
+ * the same pixels. The sketch is best-effort: a picture with no edges worth
+ * drawing simply plays the colour pass alone.
+ */
+export declare function traceRasterToDrawing(raster: {
+    width: number;
+    height: number;
+    data: Uint8Array;
+}, options: TraceOptions): TraceOutcome;

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

@@ -0,0 +1,12 @@
+/** Read-only route that hands one stored trace plan to the canvas. */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { TracePlanStore } from './trace-store.js';
+export interface TraceRouteDeps {
+    store: TracePlanStore;
+}
+/**
+ * Serve one drawing plan by id. GET only: the plan is produced by the
+ * `draw_reference` tool and never written from the browser, so there is
+ * nothing to accept here.
+ */
+export declare function serveTracePlan(req: IncomingMessage, res: ServerResponse, deps: TraceRouteDeps): Promise<void>;

package/lib/types/trace-sketch.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Derive a pencil-sketch raster from a reference image.
+ *
+ * The tracer can only reproduce what is in the pixels, so "先起稿再上色" needs
+ * an actual contour drawing to reproduce. Spending a model call on one would be
+ * slow, non-deterministic and — for a picture the model has already been given
+ * — redundant. Derive it locally instead: grayscale, Sobel magnitude, an
+ * adaptive threshold, then a one-pixel dilation so the lines survive the
+ * downsampling the tracer does internally.
+ *
+ * The result is a black-on-white line drawing: the contour pass an illustrator
+ * makes before blocking in colour.
+ */
+/** RGBA8 bitmap, the same shape the tracer consumes. */
+export interface SketchRaster {
+    width: number;
+    height: number;
+    data: Uint8Array;
+}
+/**
+ * Build a line drawing from a raster.
+ * @param raster - source pixels (RGBA8).
+ * @param maxSide - long side to compute the edges at; defaults to 1200.
+ * @returns a black-on-white RGBA8 bitmap of the detected contours.
+ */
+export declare function sketchRaster(raster: SketchRaster, maxSide?: number): SketchRaster;

package/lib/types/trace-store.d.ts

@@ -0,0 +1,23 @@
+import type { TraceShow } from './trace-drawing.js';
+export interface TracePlanStoreOptions {
+    /** Directory for restart-surviving copies; omit to stay memory-only. */
+    dir?: string | undefined;
+}
+export declare class TracePlanStore {
+    private readonly entries;
+    private readonly dir;
+    constructor(options?: TracePlanStoreOptions);
+    /** Store one show and return the id the browser will use. */
+    put(show: TraceShow): Promise<string>;
+    /** The show behind an id: memory first, then the disk copy, else undefined. */
+    get(id: string): Promise<TraceShow | undefined>;
+    /** Write the disk copy; failures are logged and otherwise ignored. */
+    private persist;
+    /** Read one disk copy, dropping it when expired or malformed. */
+    private read;
+    private remove;
+    /** Drop expired entries, then the oldest ones past the cap, in memory and on disk. */
+    private evict;
+    /** Delete disk copies left behind by a previous host process. */
+    private evictDisk;
+}

package/lib/types/vendor/drawai/raster.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Vendored from dsh-drawai v0.3.4 - https://github.com/fourzkw/dsh-drawai
+ * MIT License, Copyright (c) 2026 fourzkw.
+ * Copied verbatim from lib/raster.js apart from this header.
+ *
+ * PNG decoding is dependency free (node:zlib only). JPEG/GIF/WebP go through an
+ * optional sharp install, which this plugin does not rely on.
+ */
+/**
+ * 位图解码 —— 把图片文件解成原始 RGBA 像素，供「逐像素矢量化」使用。
+ *
+ * 两条路：
+ *   1. **纯 Node 的 PNG 解码器**（零依赖，只用 node:zlib）：PNG 是矢量化最常见的输入
+ *      （截图、导出的角色图），自己解能保证"宿主装了什么依赖都能用"。
+ *   2. **可选 sharp**：非 PNG（JPEG / WebP / GIF…）自己没有解码器，装了 sharp 就用它。
+ *      sharp 是可选依赖：没装时只报"这个格式解不开"，不影响 PNG 那条主路。
+ *
+ * 解码结果是 `{ width, height, data }`，data 是 **RGBA8**（`width*height*4` 字节），
+ * 也就是矢量化的**唯一真相**：后面所有轮廓都从它算，中间不再碰文件。
+ */
+/**
+ * 解一份 PNG 成 RGBA8。
+ *
+ * 支持：颜色类型 0/2/3/4/6、位深 1/2/4/8/16、Adam7 隔行、tRNS 透明。
+ * 不支持（会明确报错）：颜色类型 1（已废弃）。
+ */
+export declare function decodePng(bytes: any): {
+    width: number;
+    height: number;
+    data: Buffer<ArrayBuffer>;
+};
+/** 是不是能被本模块解开的图片（按文件头判，不看后缀）。 */
+export declare function looksLikeRaster(bytes: any): boolean;
+/**
+ * 解一份图片文件成 RGBA8。
+ *
+ * PNG 走自带解码器（零依赖、结果确定）；其余格式试 sharp，没有就给可执行的建议。
+ */
+export declare function decodeRaster(bytes: any): Promise<{
+    width: any;
+    height: any;
+    data: any;
+}>;

package/lib/types/vendor/drawai/trace-image.d.ts

@@ -0,0 +1,257 @@
+/**
+ * Vendored from dsh-drawai v0.3.4 - https://github.com/fourzkw/dsh-drawai
+ * MIT License, Copyright (c) 2026 fourzkw.
+ * Copied verbatim from lib/trace-image.js apart from this header.
+ *
+ * Self-contained raster-to-SVG tracer: it takes RGBA pixels, quantizes with
+ * k-means, traces pixel-grid contours, simplifies with RDP, and emits one
+ * nonzero path per colour. With includeDrawing it also returns an ordered plan
+ * (largest area first) that a canvas can replay step by step.
+ */
+/**
+ * 逐像素矢量化 —— 把一张位图变成一段内嵌 SVG 标记（DrawAI 的 svg 内容节点用）。
+ *
+ * 这里只有**像素进、SVG 出**，不碰文件系统、不碰 ctx：宿主工具与命令行脚本共用同一份。
+ *
+ * 管线（每一步都能在返回的 metrics 里看到数字）：
+ *   ① 工作图尺寸 = src/scale，再套 grid（宽）/ gridH（高）上限；透明像素合成到 bgColor
+ *   ② 去背景：由调用方显式传 removeBg true/false（无 auto）。true 时先识纯色底再泛洪，识不到走近白回退
+ *   ③ 分层 k-means（colorsDark 暗色 + colorsFill 填充）定调色板；暗像素进保护区
+ *   ④ 3× 超采样归类 → 条件众数（高对比跳过）→ despeckle / minRegionArea（保护区不并）
+ *   ⑤ 每色按连通域取闭合轮廓：像素**格边**上的有向图 + 左转跟随（区域恒在左侧）
+ *   ⑥ RDP + 预算阶梯（受保护环不因 minLoopArea 丢弃）→ 每色一条 <path fill-rule="nonzero">
+ *
+ * 为什么是"格边跟随"而不是 marching squares：标签图在鞍点（对角相接）处 marching squares
+ * 要人为定连通性，而格边有向图本身就无歧义 —— 每条边只属于一个区域，走完一圈恰好回到起点。
+ * 代价是必须用 4 连通分区（对角相接算两个区域），见下面 connectedRegions 的注释。
+ */
+/** 矢量化的默认参数（宿主工具与命令行共用）。 */
+export declare const TRACE_DEFAULTS: {
+    preset: string;
+    colors: number;
+    colorsDark: number;
+    colorsFill: number;
+    grid: number;
+    gridH: number;
+    scale: number;
+    epsilon: number;
+    precision: number;
+    minArea: number;
+    minRegionArea: number;
+    protectLuma: number;
+    majorityContrast: number;
+    bgBright: number;
+    bgTol: number;
+    bgColor: number[];
+    bgSolidTol: number;
+    bgSolidBorderRatio: number;
+    seeds: number;
+    maxBytes: number;
+    includeLabels: boolean;
+};
+/**
+ * 命名预设：AI 先选场景，再按需覆盖单个字段。
+ * 合并顺序：TRACE_DEFAULTS ← preset ← 显式字段。
+ */
+export declare const TRACE_PRESETS: {
+    default: {};
+    /** 插画 / 线稿：多留暗色、严保细线、轮廓更细 */
+    lineart: {
+        colorsDark: number;
+        protectLuma: number;
+        majorityContrast: number;
+        minArea: number;
+        epsilon: number;
+        precision: number;
+    };
+    /** 照片 / 渐变：少暗色配额、碎块并多一点、轮廓可粗 */
+    photo: {
+        colors: number;
+        colorsDark: number;
+        protectLuma: number;
+        majorityContrast: number;
+        minArea: number;
+        epsilon: number;
+    };
+    /** 图标 / 简单截图：少色 + 降采样，压字符数 */
+    simple: {
+        colors: number;
+        colorsDark: number;
+        scale: number;
+        grid: number;
+        epsilon: number;
+        minArea: number;
+        protectLuma: number;
+    };
+};
+/** 合法预设名列表（给报错 / 提示用）。 */
+export declare const TRACE_PRESET_NAMES: string[];
+/** 按用户参考图校准：保持同一棱角化色块管线，主要以采样密度区分三档。 */
+export declare const TRACE_FRAGMENT_LEVELS: Readonly<{
+    low: Readonly<{
+        resolutionRatio: number;
+        tolerance: 0.1;
+    }>;
+    medium: Readonly<{
+        resolutionRatio: number;
+        tolerance: 0.08;
+    }>;
+    high: Readonly<{
+        resolutionRatio: 1;
+        tolerance: 0.04;
+    }>;
+}>;
+export declare function traceRasterForToolbar(raster: any, raw?: {}): any;
+/**
+ * 合并默认值 + 预设 + 显式覆盖。未知 preset 抛错（让 AI 立刻改，而不是静默当 default）。
+ * @returns {{options:object, preset:string}}
+ */
+export declare function resolveTraceOptions(rawOptions: any): {
+    options: any;
+    preset: any;
+};
+/**
+ * 根据 metrics 生成一句调参建议（给 AI 读，不是给用户的长文）。
+ */
+export declare function hintTraceTune(metrics: any): string;
+/**
+ * 把普通 JSON 数据收成 DSH 工具返回值能过关的"无损 JSON"：
+ *   · 丢掉值为 undefined 的自有属性（`{crop:undefined}` 会被 isJsonValue 判死刑，
+ *     而 JSON.stringify 却会默默省略 —— 这正是 traceImage 回执曾触发
+ *     `tool "diagram_apply" returned invalid output: value is not lossless JSON` 的根因）
+ *   · 把 -0 收成 0（DSH 的 walkJsonValue 同样拒 -0）
+ *   · 非有限数字 → 0（宁可变钝，也不让整次工具调用被宿主打回）
+ */
+export declare function toLosslessJson(value: any): any;
+/**
+ * 压缩给 AI 的结构化调参回执（diagram_apply.trace[]）。
+ *
+ * 可选字段（image / nodeId / crop）**缺就不要挂键** —— 宿主对工具输出走
+ * lossless JSON 校验，自有属性值为 undefined 会整次失败。
+ */
+export declare function summarizeTraceForAi(metrics: any, extra: any): any;
+/**
+ * 位图 → SVG 标记。
+ *
+ * @param {{width:number,height:number,data:Buffer|Uint8Array}} raster RGBA8
+ * @param {object} [rawOptions] 见 TRACE_DEFAULTS / TRACE_PRESETS（可用 preset）
+ * @returns {{svg:string, metrics:object}}
+ */
+export declare function traceRasterToSvg(raster: any, rawOptions: any): {
+    labels: {
+        width: number;
+        height: number;
+        colors: number;
+        palette: string[];
+        labels: string;
+    } | null;
+    metrics: {
+        preset: any;
+        source: {
+            width: any;
+            height: any;
+        };
+        work: {
+            width: number;
+            height: number;
+            scale: number;
+        };
+        scaleRequested: number;
+        scaleApplied: number;
+        grid: number;
+        gridH: number;
+        bgColor: any[];
+        sizeNotes: string;
+        colors: number;
+        colorsDark: number;
+        colorsFill: any;
+        darkSamples: number;
+        fillSamples: any;
+        protectLuma: number;
+        protectPixels: number;
+        fgRelabeledFromBg: number;
+        bgForced: number;
+        bgRemoved: boolean;
+        bgDetect: {
+            hasSolid: boolean;
+            mode: string;
+            matchRatio: number;
+            kind: null;
+            color: null;
+        };
+        majorityContrast: number;
+        majoritySkipped: number;
+        majorityApplied: number;
+        palette: string[];
+        backgroundPixels: number;
+        foregroundPixels: number;
+        despeckle: {
+            mergedPixels: number;
+            blocksMerged: number;
+            blocks: number;
+            protectedSkipped: number;
+        };
+        regionMerge: {
+            mergedPixels: number;
+            blocksMerged: number;
+            blocks: number;
+            protectedSkipped: number;
+        };
+        regions: number;
+        regionsProtected: number;
+        loops: number;
+        paths: number;
+        loopsKept: number;
+        fragments: number;
+        loopsProtectedKept: number;
+        drawnPixels: number | null;
+        totalPixels: number;
+        exactPixelCoverage: boolean;
+        labelPartitionComplete: boolean;
+        coverageBasis: string;
+        loopsDropped: number;
+        budgetExceeded: boolean;
+        appliedEpsilon: any;
+        svgChars: number;
+        budget: any;
+        attempts: number;
+        paletteAreaSum: number;
+        optionsApplied: {
+            preset: any;
+            colors: number;
+            colorsDark: number;
+            colorsFill: any;
+            grid: number;
+            gridH: number;
+            scale: number;
+            epsilon: any;
+            precision: any;
+            minArea: number;
+            minRegionArea: number;
+            protectLuma: number;
+            majorityContrast: number;
+            removeBg: string;
+            bgSolidTol: any;
+            bgSolidBorderRatio: any;
+        };
+    };
+    drawing?: {
+        viewBox: number[];
+        fills: string[];
+        steps: {
+            layer: number;
+            d: any;
+            area: any;
+        }[];
+    };
+    svg: string;
+};
+/**
+ * 把 SVG 标记编码进 drawio 的 `image=` 值（`data:image/svg+xml,<百分号编码>`）。
+ *
+ * 为什么用百分号编码而不是 base64：编码后的串里一个 `;` 都没有，而 drawio 与本内核的
+ * style 解析都是按 `;` 分段 —— base64 形态的 `data:image/svg+xml;base64,` 那个分号是解析器的雷。
+ * 这里编得比 JSON 严格一点（`<` `>` `#` `%` `"` 和空格），换来的好处是：不管宿主把它塞进
+ * 属性还是直接写进 style，都不会有歧义。
+ */
+export declare function svgToImageValue(svg: any): string;

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

@@ -0,0 +1,4 @@
+import type { ConnectionRequestRejection, ConnectionTrustRequest } from '@deepseek-ai/dsh-client-connection';
+import type { WebRoute } from '@deepseek-ai/dsh-host-webserver';
+export type WebAdmission = (request: ConnectionTrustRequest) => ConnectionRequestRejection;
+export declare function withWebAdmission(route: WebRoute, admission: () => WebAdmission | undefined): WebRoute;