@vedivad/typst-web-service 0.8.1 → 0.9.0

package/dist/index.d.ts

@@ -27,6 +27,8 @@ interface LspCompletionItem {
     detail?: string;
     documentation?: string | LspMarkupContent;
     insertText?: string;
+    /** LSP InsertTextFormat: 1 = PlainText, 2 = Snippet (TextMate syntax). */
+    insertTextFormat?: number;
     filterText?: string;
     sortText?: string;
     textEdit?: {
@@ -75,18 +77,24 @@ declare class TypstAnalyzer {
     private readonly proxy;
     private readonly worker;
     private versionCounter;
-    private openedUris;
+    /**
+     * Last content pushed to the worker per URI. Presence is the source of
+     * truth for "is this URI opened on the worker?"; value drives own-RPC dedup.
+     */
+    private readonly content;
     private constructor();
     static create(options: TypstAnalyzerOptions): Promise<TypstAnalyzer>;
     didOpen(uri: string, content: string): Promise<void>;
     didClose(uri: string): Promise<void>;
     /**
-     * Notify the analyzer that a document has changed.
+     * Notify the analyzer that a document has changed. Skips the RPC when the
+     * content matches what the worker last saw.
      */
     didChange(uri: string, content: string): Promise<void>;
     /**
      * Batch document changes. Splits inputs into opens (first-time URIs) and
      * changes (already-open URIs) and sends them in a single worker roundtrip.
+     * Skips unchanged documents; returns without an RPC if nothing is pending.
      */
     didChangeMany(docs: Record<string, string>): Promise<void>;
     /**
@@ -94,8 +102,20 @@ declare class TypstAnalyzer {
      * in a single worker roundtrip.
      */
     didCloseMany(uris: string[]): Promise<void>;
-    completion(uri: string, line: number, character: number): Promise<LspCompletionResponse>;
-    hover(uri: string, line: number, character: number): Promise<LspHover | null>;
+    /**
+     * Request completion at `position` for `uri`, with `content` as the current
+     * document state. Bundles the didChange notification with the request in one
+     * worker roundtrip; degrades to a plain completion request when the worker
+     * already has this exact content.
+     */
+    completion(uri: string, content: string, position: LspPosition): Promise<LspCompletionResponse>;
+    /**
+     * Request hover at `position` for `uri`, with `content` as the current
+     * document state. Bundles the didChange notification with the request in one
+     * worker roundtrip; degrades to a plain hover request when the worker
+     * already has this exact content.
+     */
+    hover(uri: string, content: string, position: LspPosition): Promise<LspHover | null>;
     destroy(): void;
 }
 
@@ -163,7 +183,7 @@ interface TypstCompilerOptions {
     /**
      * Explicit Worker instance. When omitted, an inlined blob worker is created automatically.
      * Use this for Vite apps to get proper source maps:
-     *   `await TypstCompiler.create({ worker: new Worker(new URL('typst-web-service/worker', import.meta.url)) })`
+     *   `await TypstCompiler.create({ worker: new Worker(new URL('typst-web-service/compiler-worker', import.meta.url)) })`
      */
     worker?: Worker;
     /**
@@ -194,6 +214,8 @@ declare class TypstCompiler {
     private readonly proxy;
     private readonly worker;
     private readonly encoder;
+    /** Last text content pushed per path. Drives own-RPC dedup. Invalidated by binary writes. */
+    private readonly content;
     private constructor();
     static create(options?: TypstCompilerOptions): Promise<TypstCompiler>;
     /**
@@ -208,14 +230,18 @@ declare class TypstCompiler {
      * override with `entry`.
      */
     compilePdf(entry?: string): Promise<Uint8Array>;
-    /** Add or overwrite a text file in the virtual compiler filesystem. */
+    /**
+     * Add or overwrite a text file in the virtual compiler filesystem. Skips
+     * the worker RPC when `source` matches the last value pushed for `path`.
+     */
     setText(path: string, source: string): Promise<void>;
     /** Add or overwrite a JSON file in the virtual compiler filesystem. */
     setJson(path: string, value: unknown, replacer?: (this: unknown, key: string, value: unknown) => unknown, space?: string | number): Promise<void>;
     /**
      * Add or overwrite multiple files in the virtual compiler filesystem in a
-     * single worker roundtrip. Strings are UTF-8 encoded; Uint8Arrays are passed
-     * through.
+     * single worker roundtrip. Strings are UTF-8 encoded; Uint8Arrays are
+     * passed through. Text entries unchanged since their last push are skipped;
+     * binary entries always push and invalidate the text cache for their path.
      */
     setMany(files: Record<string, string | Uint8Array>): Promise<void>;
     /** Add or overwrite a binary file in the virtual compiler filesystem. */
@@ -285,6 +311,18 @@ interface TypstProjectOptions {
      * and project VFS use the raw paths unchanged.
      */
     analyzerUriRoot?: string;
+    /**
+     * Idle time (ms) after the last VFS mutation before an auto-compile fires.
+     * Default: 0 — compile fires on the next macrotask. Set higher (e.g. 150) to
+     * coalesce rapid edits.
+     */
+    compileDebounceMs?: number;
+    /**
+     * Maximum time (ms) between auto-compiles during sustained mutation bursts.
+     * Guarantees progress while the user is actively typing. Default: 0 (no
+     * throttle — only debounce applies).
+     */
+    compileThrottleMs?: number;
 }
 /**
  * Coordinates a compiler + analyzer pair for multi-file Typst projects.
@@ -303,15 +341,27 @@ declare class TypstProject {
     private readonly compiler;
     private readonly analyzer?;
     private readonly analyzerUriRoot;
-    private readonly trackedTextPaths;
-    /** Last content written via setText/setMany, per path. Used to skip redundant writes to compiler + analyzer. */
-    private readonly lastSyncedContent;
+    /**
+     * Tracked text files: path → latest content observed. Presence in this map
+     * is the source of truth for "is this a tracked text file?"; insertion
+     * order drives the `files` getter. Per-sink dedup lives in the compiler and
+     * analyzer.
+     */
+    private readonly contentByPath;
     private readonly compileListeners;
+    private readonly scheduler;
     private compileVersion;
     private _lastResult;
     private _entry;
     private destroyed;
     constructor(options: TypstProjectOptions);
+    /**
+     * Schedule an auto-compile after VFS mutations. Coalesces rapid calls via
+     * the configured debounce/throttle. Errors surface through `onCompile`
+     * listeners via a synthetic diagnostic; callers awaiting a specific compile
+     * should call `compile()` directly.
+     */
+    private scheduleCompile;
     /** Current entry file path. Assign to change the sticky entry used by subsequent `compile()` calls. */
     get entry(): Path;
     set entry(path: Path);
@@ -337,8 +387,9 @@ declare class TypstProject {
     getText(path: Path): string | undefined;
     /**
      * Add or overwrite a text file. Goes to the compiler's VFS and, when an
-     * analyzer is attached, to the analyzer as a document change. Redundant
-     * calls with unchanged content are skipped.
+     * analyzer is attached, to the analyzer as a document change. No-op when
+     * the tracked path already has this exact content — skips both worker RPCs
+     * and the auto-scheduled compile.
      */
     setText(path: Path, content: string): Promise<void>;
     /**
@@ -350,7 +401,9 @@ declare class TypstProject {
     setBinary(path: Path, content: ArrayBuffer | ArrayBufferView): Promise<void>;
     /**
      * Batch set multiple files. Strings route to both compiler and analyzer;
-     * Uint8Array entries go to the compiler only.
+     * Uint8Array entries go to the compiler only. Strings matching the last
+     * tracked content for their path are skipped on both sinks. Binary entries
+     * always go through (no content cache, so no dedup).
      */
     setMany(files: Record<Path, string | Uint8Array>): Promise<void>;
     /**
@@ -374,15 +427,28 @@ declare class TypstProject {
      * callers and listeners always receive a `CompileResult`. Listeners are
      * notified only for the most recent compile — results from an earlier call
      * that resolves after a later one are suppressed.
+     *
+     * VFS mutations (`setText`, `remove`, etc.) auto-schedule a debounced
+     * compile; call this directly only when you need an awaitable handle on the
+     * result (e.g., to flush before rendering to PDF).
      */
     compile(): Promise<CompileResult>;
     /** Compile the current VFS state to PDF using the sticky entry. */
     compilePdf(): Promise<Uint8Array>;
     private requireAnalyzer;
-    /** Request completions at the given position. Throws when no analyzer is attached. */
-    completion(path: Path, line: number, character: number): Promise<LspCompletionResponse>;
-    /** Request hover info at the given position. Throws when no analyzer is attached. */
-    hover(path: Path, line: number, character: number): Promise<LspHover | null>;
+    /**
+     * Request completion for `path` at `position`, using `source` as the
+     * current document state. One analyzer roundtrip; compiler is not touched —
+     * the compile sync path writes to the compiler separately. Throws when no
+     * analyzer is attached.
+     */
+    completion(path: Path, source: string, position: LspPosition): Promise<LspCompletionResponse>;
+    /**
+     * Request hover for `path` at `position`, using `source` as the current
+     * document state. One analyzer roundtrip; compiler is not touched. Throws
+     * when no analyzer is attached.
+     */
+    hover(path: Path, source: string, position: LspPosition): Promise<LspHover | null>;
     /**
      * Tear down the project and the services it owns. Destroys the attached
      * compiler and analyzer, drops all listeners, and clears VFS tracking state.
@@ -400,6 +466,16 @@ interface TypstRendererOptions {
     /** URL to the typst-ts-renderer WASM binary. Defaults to jsDelivr CDN. */
     wasmUrl?: string;
 }
+interface RenderedSvgPage {
+    /** Zero-based page index within the document. */
+    index: number;
+    /** Page width in typographic points. */
+    width: number;
+    /** Page height in typographic points. */
+    height: number;
+    /** Standalone SVG string for just this page. */
+    svg: string;
+}
 /**
  * Converts Typst vector artifacts to SVG strings.
  *
@@ -419,6 +495,15 @@ declare class TypstRenderer {
     destroy(): Promise<void>;
     /** Render a Typst vector artifact to an SVG string. */
     renderSvg(vector: Uint8Array): Promise<string>;
+    /**
+     * Render a Typst vector artifact into one self-contained SVG string per
+     * physical page. The merged SVG is split by `<g class="typst-page">`
+     * children; each group's `data-page-width` / `data-page-height` give the
+     * page-local viewBox. Shared `<defs>` / `<style>` are duplicated into each
+     * page so the output SVGs render independently. Returns an empty array if
+     * the document has no page groups.
+     */
+    renderSvgPages(vector: Uint8Array): Promise<RenderedSvgPage[]>;
 }
 
-export { type AnalyzerUri, type CompileResult, type DiagnosticMessage, type DiagnosticRange, type FormatConfig, type FormatRangeResult, type LspCompletionItem, type LspCompletionList, type LspCompletionResponse, type LspDiagnostic, type LspHover, type LspHoverContents, type LspMarkupContent, type LspPosition, type LspRange, type Path, TypstAnalyzer, type TypstAnalyzerOptions, TypstCompiler, type TypstCompilerOptions, TypstFormatter, TypstProject, type TypstProjectOptions, TypstRenderer, normalizePath, normalizeRoot, pathToAnalyzerUri };
+export { type AnalyzerUri, type CompileResult, type DiagnosticMessage, type DiagnosticRange, type FormatConfig, type FormatRangeResult, type LspCompletionItem, type LspCompletionList, type LspCompletionResponse, type LspDiagnostic, type LspHover, type LspHoverContents, type LspMarkupContent, type LspPosition, type LspRange, type Path, type RenderedSvgPage, TypstAnalyzer, type TypstAnalyzerOptions, TypstCompiler, type TypstCompilerOptions, TypstFormatter, TypstProject, type TypstProjectOptions, TypstRenderer, type TypstRendererOptions, normalizePath, normalizeRoot, pathToAnalyzerUri };