@vedivad/typst-web-service 0.8.0 → 0.9.0

package/dist/index.d.ts

@@ -1,3 +1,59 @@
+/** LSP Position (0-based line and character). */
+interface LspPosition {
+    line: number;
+    character: number;
+}
+/** LSP Range. */
+interface LspRange {
+    start: LspPosition;
+    end: LspPosition;
+}
+/** LSP Diagnostic as returned by tinymist. */
+interface LspDiagnostic {
+    range: LspRange;
+    severity?: number;
+    message: string;
+    source?: string;
+}
+/** LSP MarkupContent (markdown or plaintext). */
+interface LspMarkupContent {
+    kind: "markdown" | "plaintext";
+    value: string;
+}
+/** LSP CompletionItem (subset actually populated by tinymist). */
+interface LspCompletionItem {
+    label: string;
+    kind?: number;
+    detail?: string;
+    documentation?: string | LspMarkupContent;
+    insertText?: string;
+    /** LSP InsertTextFormat: 1 = PlainText, 2 = Snippet (TextMate syntax). */
+    insertTextFormat?: number;
+    filterText?: string;
+    sortText?: string;
+    textEdit?: {
+        range: LspRange;
+        newText: string;
+    };
+}
+/** LSP CompletionList. */
+interface LspCompletionList {
+    isIncomplete: boolean;
+    items: LspCompletionItem[];
+}
+/** Response shape for `textDocument/completion`. */
+type LspCompletionResponse = LspCompletionList | LspCompletionItem[] | null;
+/** LSP Hover contents — legacy and current forms tinymist may emit. */
+type LspHoverContents = string | LspMarkupContent | (string | {
+    language: string;
+    value: string;
+})[];
+/** Response shape for `textDocument/hover`. */
+interface LspHover {
+    contents: LspHoverContents;
+    range?: LspRange;
+}
+
 interface TypstAnalyzerOptions {
     /**
      * Explicit Worker instance. When omitted, an inlined blob worker is created automatically.
@@ -21,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>;
     /**
@@ -40,31 +102,62 @@ declare class TypstAnalyzer {
      * in a single worker roundtrip.
      */
     didCloseMany(uris: string[]): Promise<void>;
-    completion(uri: string, line: number, character: number): Promise<unknown>;
-    hover(uri: string, line: number, character: number): Promise<unknown>;
+    /**
+     * 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;
 }
 
-/** LSP Diagnostic as returned by tinymist. */
-interface LspDiagnostic {
-    range: {
-        start: {
-            line: number;
-            character: number;
-        };
-        end: {
-            line: number;
-            character: number;
-        };
-    };
-    severity?: number;
-    message: string;
-    source?: string;
-}
-
-declare function normalizeUntitledUri(uri: string): string;
-declare function normalizePath(path: string): string;
+/**
+ * Two addressing schemes live in this codebase. This file is the only place
+ * that knows how they relate. Keeping the vocabulary and conversions colocated
+ * means a new contributor can read one file and understand the model.
+ *
+ * 1. Path          — "/main.typ". Always leading-slash, always forward slashes.
+ *                    Used by the compiler VFS, the `TypstProject` public API,
+ *                    and the `typstFilePath` facet. Addresses a file within
+ *                    the project.
+ *
+ * 2. AnalyzerUri   — "untitled:project/main.typ". What tinymist's LSP expects.
+ *                    Derived from a Path plus the analyzer URI root.
+ *
+ * The types below are type aliases, not branded/opaque types. That's
+ * deliberate: callers can pass string literals where a Path is expected
+ * without wrapping, and the aliases only serve as self-documenting
+ * signatures. Ingress points still need to call `normalizePath` to defend
+ * against un-normalized input — the alias does not imply the string has
+ * been normalized.
+ */
+/** `/path/to/file.typ` — leading-slash, forward slashes only. */
+type Path = string;
+/** `untitled:project/path/to/file.typ` — what tinymist's LSP consumes. */
+type AnalyzerUri = string;
+/** Ensure a path starts with a leading slash. Idempotent. */
+declare function normalizePath(path: string): Path;
+/**
+ * Normalize an analyzer URI root. Ensures leading slash, strips trailing
+ * slashes. Special-cases "/" → "" so URIs don't end up with a leading
+ * `untitled://`.
+ */
 declare function normalizeRoot(rootPath: string): string;
+/**
+ * Build the analyzer URI for a given project path. `root` is expected to
+ * already be normalized (see `normalizeRoot`).
+ *
+ *   pathToAnalyzerUri("/main.typ", "/project") -> "untitled:project/main.typ"
+ */
+declare function pathToAnalyzerUri(path: Path, root: string): AnalyzerUri;
 
 /** Source range for a diagnostic. All values are 0-indexed. */
 interface DiagnosticRange {
@@ -90,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;
     /**
@@ -121,32 +214,34 @@ declare class TypstCompiler {
     private readonly proxy;
     private readonly worker;
     private readonly encoder;
-    /** The most recent vector artifact from a compile, if any. */
-    lastVector?: Uint8Array;
+    /** 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>;
     /**
-     * Compile. Pass a source string (written to the entry path) or a map of
-     * files to register before compiling; omit to compile whatever is currently
-     * in the VFS (populated via setText/setBinary/setJson/setMany).
-     * Defaults to compiling "/main.typ"; override with `entry`.
+     * Compile whatever is currently in the VFS (populated via
+     * setText/setBinary/setJson/setMany). Defaults to compiling "/main.typ";
+     * override with `entry`.
      */
-    compile(source?: string | Record<string, string>, entry?: string): Promise<CompileResult>;
+    compile(entry?: string): Promise<CompileResult>;
     /**
-     * Compile to PDF. Pass a source string (written to the entry path) or a map
-     * of files to register before compiling; omit to compile whatever is
-     * currently in the VFS (populated via setText/setBinary/setJson/setMany).
-     * Defaults to compiling "/main.typ"; override with `entry`.
+     * Compile to PDF. Operates on whatever is currently in the VFS (populated
+     * via setText/setBinary/setJson/setMany). Defaults to compiling "/main.typ";
+     * override with `entry`.
+     */
+    compilePdf(entry?: string): Promise<Uint8Array>;
+    /**
+     * Add or overwrite a text file in the virtual compiler filesystem. Skips
+     * the worker RPC when `source` matches the last value pushed for `path`.
      */
-    compilePdf(source?: string | Record<string, string>, entry?: string): Promise<Uint8Array>;
-    /** Add or overwrite a text file in the virtual compiler filesystem. */
     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. */
@@ -210,11 +305,24 @@ interface TypstProjectOptions {
     /** Default entry file path. Default: "/main.typ". */
     entry?: string;
     /**
-     * Project root used to build stable analyzer URIs. Default: "/project".
-     * URIs are formed as `untitled:<root-without-leading-slash><path>` — so
-     * `/main.typ` becomes `untitled:project/main.typ`.
+     * Prefix used to build the `untitled:` URIs handed to the analyzer.
+     * Default: "/project". A path of `/main.typ` becomes
+     * `untitled:project/main.typ`. Only affects URI construction — the compiler
+     * and project VFS use the raw paths unchanged.
      */
-    rootPath?: string;
+    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.
@@ -228,62 +336,146 @@ interface TypstProjectOptions {
  *   await project.setMany({ "/main.typ": "...", "/utils.typ": "..." });
  *   const result = await project.compile();
  */
+type CompileListener = (result: CompileResult) => void;
 declare class TypstProject {
     private readonly compiler;
     private readonly analyzer?;
-    private readonly rootPath;
-    private readonly trackedTextPaths;
-    /** Last content written via setText/setMany, per path. Used to skip redundant writes to compiler + analyzer. */
-    private readonly lastSyncedContent;
+    private readonly analyzerUriRoot;
+    /**
+     * 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);
-    /** Current entry file path. */
-    get entry(): string;
+    /**
+     * 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);
     /** Whether an analyzer is attached. */
     get hasAnalyzer(): boolean;
-    /** Change the sticky entry file used by subsequent compile() calls. */
-    setEntry(path: string): void;
+    /**
+     * Most recent compile result, or `undefined` before the first compile has
+     * settled. Useful for lazy-mounted UI that subscribes after boot and needs
+     * an initial value.
+     */
+    get lastResult(): CompileResult | undefined;
+    /**
+     * Snapshot of tracked text file paths, in insertion order. Updated by
+     * `setText`, `setMany`, `remove`, and `clear`. Returns a fresh array — mutate
+     * freely without affecting project state.
+     */
+    get files(): Path[];
+    /**
+     * Current text content for a tracked file, or `undefined` if the path was
+     * never written via `setText`/`setMany` (or was removed). Read-through to the
+     * project's sync cache — lets consumers avoid shadowing the VFS themselves.
+     */
+    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: string, content: string): Promise<void>;
+    setText(path: Path, content: string): Promise<void>;
     /**
      * Add or overwrite a JSON file. Compiler-only — the analyzer does not track
      * data files.
      */
-    setJson(path: string, value: unknown): Promise<void>;
+    setJson(path: Path, value: unknown): Promise<void>;
     /** Add or overwrite a binary file. Compiler-only. */
-    setBinary(path: string, content: ArrayBuffer | ArrayBufferView): Promise<void>;
+    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<string, string | Uint8Array>): Promise<void>;
+    setMany(files: Record<Path, string | Uint8Array>): Promise<void>;
     /**
      * Remove a file. Always removed from the compiler's VFS; also closed on the
      * analyzer when it was previously tracked as text.
      */
-    remove(path: string): Promise<void>;
+    remove(path: Path): Promise<void>;
     /** Clear all files from both compiler VFS and analyzer document set. */
     clear(): Promise<void>;
-    /** Compile the current VFS state using the sticky entry. */
+    /**
+     * Subscribe to compile results. Fires after every `compile()` whose result is
+     * still current (stale results from out-of-order concurrent compiles are
+     * dropped). If a compile has already settled, the most recent result is
+     * delivered synchronously so late-mounted listeners aren't stuck blank until
+     * the next compile. Returns an unsubscribe function.
+     */
+    onCompile(listener: CompileListener): () => void;
+    /**
+     * Compile the current VFS state using the sticky entry. Errors from the
+     * underlying compiler are converted into a synthetic error diagnostic so
+     * 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: string, line: number, character: number): Promise<unknown>;
-    /** Request hover info at the given position. Throws when no analyzer is attached. */
-    hover(path: string, line: number, character: number): Promise<unknown>;
-    private toUri;
+    /**
+     * 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.
+     * Idempotent — calling twice is a no-op. After destruction, further calls on
+     * the project are not supported; construct a new one.
+     *
+     * If you need to share a compiler or analyzer across projects, destroy them
+     * yourself and don't call this method — the project does not provide an
+     * ownership toggle.
+     */
+    destroy(): void;
 }
 
 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.
  *
@@ -303,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 CompileResult, type DiagnosticMessage, type DiagnosticRange, type FormatConfig, type FormatRangeResult, type LspDiagnostic, TypstAnalyzer, type TypstAnalyzerOptions, TypstCompiler, type TypstCompilerOptions, TypstFormatter, TypstProject, type TypstProjectOptions, TypstRenderer, normalizePath, normalizeRoot, normalizeUntitledUri };
+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 };