@vedivad/typst-web-service 0.7.12 → 0.8.1

package/dist/index.d.ts

@@ -1,21 +1,57 @@
+/** 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: {
-        start: {
-            line: number;
-            character: number;
-        };
-        end: {
-            line: number;
-            character: number;
-        };
-    };
+    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;
+    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;
+}
 
-type DiagnosticsListener = (uri: string, diagnostics: LspDiagnostic[]) => void;
 interface TypstAnalyzerOptions {
     /**
      * Explicit Worker instance. When omitted, an inlined blob worker is created automatically.
@@ -31,111 +67,77 @@ interface TypstAnalyzerOptions {
 }
 /**
  * Manages a tinymist language server in a Web Worker. Provides LSP-based
- * diagnostics, completion, and hover for Typst documents.
- *
- * Diagnostics are push-based: call `didChange()` to notify the analyzer of
- * content changes, and receive diagnostics via `onDiagnostics()` listeners
- * whenever tinymist publishes them.
+ * completion and hover for Typst documents.
  *
  *   const analyzer = await TypstAnalyzer.create({ wasmUrl: '...' });
- *   analyzer.onDiagnostics((uri, diags) => { ... });
  */
 declare class TypstAnalyzer {
     private readonly proxy;
     private readonly worker;
     private versionCounter;
     private openedUris;
-    private diagnosticsListeners;
     private constructor();
     static create(options: TypstAnalyzerOptions): Promise<TypstAnalyzer>;
-    /**
-     * Register a listener for push-based diagnostics.
-     * Returns an unsubscribe function.
-     */
-    onDiagnostics(listener: DiagnosticsListener): () => void;
     didOpen(uri: string, content: string): Promise<void>;
     didClose(uri: string): Promise<void>;
     /**
      * Notify the analyzer that a document has changed.
-     * Diagnostics will arrive asynchronously via `onDiagnostics()` listeners.
      */
     didChange(uri: string, content: string): Promise<void>;
-    completion(uri: string, line: number, character: number): Promise<unknown>;
-    hover(uri: string, line: number, character: number): Promise<unknown>;
-    destroy(): void;
-}
-
-type DiagnosticsSubscriber = (diagnostics: LspDiagnostic[]) => void;
-interface AnalyzerSessionOptions {
-    analyzer: Pick<TypstAnalyzer, "didOpen" | "didChange" | "completion" | "hover" | "onDiagnostics">;
-    /** Project root used to build stable in-memory analyzer URIs. Default: "/project". */
-    rootPath?: string;
-    /** Entry file path within the project. Synced last to ensure dependencies load first. Default: "/main.typ". */
-    entryPath?: string;
-}
-/**
- * Synchronizes an in-memory Typst project with a TypstAnalyzer.
- * Handles multi-file ordering, request queueing, and diagnostic subscriptions.
- *
- * Diagnostics arrive via the analyzer's push mechanism and are forwarded
- * to subscribers registered with `subscribe()`.
- *
- *   const session = new AnalyzerSession({ analyzer });
- *   session.subscribe("/main.typ", (diags) => { ... });
- *   await session.sync("/main.typ", files);
- */
-declare class AnalyzerSession {
-    private readonly analyzer;
-    private readonly rootPath;
-    private readonly entryPath;
-    private readonly syncedFiles;
-    private queue;
-    private readonly listenersByUri;
-    /** Last push received per URI. Replayed on subscribe() so tab-back shows correct diagnostics instantly. */
-    private readonly diagnosticsCache;
-    private readonly unsubscribeAnalyzer;
-    constructor(options: AnalyzerSessionOptions);
-    /** Build a tinymist URI from a project-relative path. */
-    toUri(path: string): string;
     /**
-     * Subscribe to push-based diagnostics for a file path.
-     * Returns an unsubscribe function.
+     * Batch document changes. Splits inputs into opens (first-time URIs) and
+     * changes (already-open URIs) and sends them in a single worker roundtrip.
      */
-    subscribe(path: string, listener: DiagnosticsSubscriber): () => void;
+    didChangeMany(docs: Record<string, string>): Promise<void>;
     /**
-     * Sync all project files with the analyzer.
-     * `files` must include the active file's current content under `path`.
-     *
-     * If the active file's content hasn't changed since the last sync, a
-     * lightweight hover is triggered to ensure the analyzer re-analyzes with
-     * the current project state and publishes fresh diagnostics.
-     */
-    sync(path: string, files: Record<string, string>): Promise<void>;
-    /**
-     * Sync files and request completions at the given position.
-     * Returns the raw LSP CompletionList/CompletionItem[] from tinymist.
-     */
-    completion(path: string, files: Record<string, string>, line: number, character: number): Promise<unknown>;
-    /**
-     * Sync files and request hover info at the given position.
-     * Returns the raw LSP Hover result from tinymist.
+     * Batch document closes. Filters to currently-open URIs and sends the set
+     * in a single worker roundtrip.
      */
-    hover(path: string, files: Record<string, string>, line: number, character: number): Promise<unknown>;
+    didCloseMany(uris: string[]): Promise<void>;
+    completion(uri: string, line: number, character: number): Promise<LspCompletionResponse>;
+    hover(uri: string, line: number, character: number): Promise<LspHover | null>;
     destroy(): void;
-    /**
-     * Sync all project files: dependencies first, active file last.
-     * Returns whether the active file's content was actually sent to the analyzer.
-     */
-    private syncFiles;
-    /** Sync a single file. Returns true if content was sent to the analyzer. */
-    private syncFile;
-    private orderedPaths;
-    private enqueue;
 }
 
-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 {
@@ -192,29 +194,30 @@ declare class TypstCompiler {
     private readonly proxy;
     private readonly worker;
     private readonly encoder;
-    /** The most recent vector artifact from a compile, if any. */
-    lastVector?: Uint8Array;
     private constructor();
     static create(options?: TypstCompilerOptions): Promise<TypstCompiler>;
-    /** Compile a single source string (treated as /main.typ) or a map of files. */
-    compile(source: string | Record<string, string>): Promise<CompileResult>;
-    /** Compile to PDF from a single source string (treated as /main.typ) or a map of files. */
-    compilePdf(source: string | Record<string, string>): Promise<Uint8Array>;
-    /** Add or overwrite a text source file. */
-    addSource(path: string, source: string): Promise<void>;
-    /** Add or overwrite an in-memory shadow file (text or binary). */
-    mapShadow(path: string, content: Uint8Array): Promise<void>;
-    /** Remove an in-memory shadow file by path. */
-    unmapShadow(path: string): Promise<void>;
     /**
-     * Clear all shadow files held by the compiler.
-     * Note: this also clears files previously added via addSource in the compiler runtime.
+     * Compile whatever is currently in the VFS (populated via
+     * setText/setBinary/setJson/setMany). Defaults to compiling "/main.typ";
+     * override with `entry`.
+     */
+    compile(entry?: string): Promise<CompileResult>;
+    /**
+     * 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`.
      */
-    resetShadow(): Promise<void>;
+    compilePdf(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.
+     */
+    setMany(files: Record<string, string | Uint8Array>): Promise<void>;
     /** Add or overwrite a binary file in the virtual compiler filesystem. */
     setBinary(path: string, content: ArrayBuffer | ArrayBufferView): Promise<void>;
     /** Remove a file from the virtual compiler filesystem. */
@@ -266,6 +269,133 @@ declare class TypstFormatter {
     formatRange(source: string, start: number, end: number): Promise<FormatRangeResult>;
 }
 
+interface TypstProjectOptions {
+    compiler: TypstCompiler;
+    /**
+     * Optional analyzer. When provided, text file operations also sync with the
+     * analyzer so completions / hover reflect the current state.
+     */
+    analyzer?: TypstAnalyzer;
+    /** Default entry file path. Default: "/main.typ". */
+    entry?: string;
+    /**
+     * 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.
+     */
+    analyzerUriRoot?: string;
+}
+/**
+ * Coordinates a compiler + analyzer pair for multi-file Typst projects.
+ *
+ * Owns the project's virtual filesystem state. Editors push incremental
+ * `setText` updates as the user types; the project mirrors those edits to
+ * both the compiler's shadow VFS and the analyzer's open-document set, then
+ * compiles or services LSP requests against the current state.
+ *
+ *   const project = new TypstProject({ compiler, analyzer });
+ *   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 analyzerUriRoot;
+    private readonly trackedTextPaths;
+    /** Last content written via setText/setMany, per path. Used to skip redundant writes to compiler + analyzer. */
+    private readonly lastSyncedContent;
+    private readonly compileListeners;
+    private compileVersion;
+    private _lastResult;
+    private _entry;
+    private destroyed;
+    constructor(options: TypstProjectOptions);
+    /** 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;
+    /**
+     * 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.
+     */
+    setText(path: Path, content: string): Promise<void>;
+    /**
+     * Add or overwrite a JSON file. Compiler-only — the analyzer does not track
+     * data files.
+     */
+    setJson(path: Path, value: unknown): Promise<void>;
+    /** Add or overwrite a binary file. Compiler-only. */
+    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.
+     */
+    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: Path): Promise<void>;
+    /** Clear all files from both compiler VFS and analyzer document set. */
+    clear(): Promise<void>;
+    /**
+     * 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.
+     */
+    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>;
+    /**
+     * 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;
@@ -291,4 +421,4 @@ declare class TypstRenderer {
     renderSvg(vector: Uint8Array): Promise<string>;
 }
 
-export { AnalyzerSession, type AnalyzerSessionOptions, type CompileResult, type DiagnosticMessage, type DiagnosticRange, type DiagnosticsSubscriber, type FormatConfig, type FormatRangeResult, type LspDiagnostic, TypstAnalyzer, type TypstAnalyzerOptions, TypstCompiler, type TypstCompilerOptions, TypstFormatter, TypstRenderer, type TypstRendererOptions, 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, TypstAnalyzer, type TypstAnalyzerOptions, TypstCompiler, type TypstCompilerOptions, TypstFormatter, TypstProject, type TypstProjectOptions, TypstRenderer, normalizePath, normalizeRoot, pathToAnalyzerUri };