@vedivad/typst-web-service 0.8.0 → 0.8.1

package/dist/index.d.ts

@@ -1,3 +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: 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;
+}
+
 interface TypstAnalyzerOptions {
     /**
      * Explicit Worker instance. When omitted, an inlined blob worker is created automatically.
@@ -40,31 +94,50 @@ 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>;
+    completion(uri: string, line: number, character: number): Promise<LspCompletionResponse>;
+    hover(uri: string, line: number, character: number): 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 {
@@ -121,24 +194,20 @@ 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. 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(source?: string | Record<string, string>, entry?: string): Promise<Uint8Array>;
+    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. */
@@ -210,11 +279,12 @@ 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;
 }
 /**
  * Coordinates a compiler + analyzer pair for multi-file Typst projects.
@@ -228,56 +298,102 @@ 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 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. */
-    get entry(): string;
+    /** 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.
      */
-    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.
      */
-    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.
+     */
     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>;
+    completion(path: Path, line: number, character: number): Promise<LspCompletionResponse>;
     /** Request hover info at the given position. Throws when no analyzer is attached. */
-    hover(path: string, line: number, character: number): Promise<unknown>;
-    private toUri;
+    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 {
@@ -305,4 +421,4 @@ declare class TypstRenderer {
     renderSvg(vector: Uint8Array): Promise<string>;
 }
 
-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, TypstAnalyzer, type TypstAnalyzerOptions, TypstCompiler, type TypstCompilerOptions, TypstFormatter, TypstProject, type TypstProjectOptions, TypstRenderer, normalizePath, normalizeRoot, pathToAnalyzerUri };