@formspec/language-server 0.1.0-alpha.23 → 0.1.0-alpha.25

package/dist/language-server-beta.d.ts

@@ -33,11 +33,14 @@ import type { Location } from 'vscode-languageserver/node.js';
 import type { TextDocument } from 'vscode-languageserver-textdocument';
 
 /** @public */
-export declare interface CommentSpan {
+export declare interface CommentSourceSpan {
     readonly start: number;
     readonly end: number;
 }
 
+/** @public */
+export declare type CommentSpan = CommentSourceSpan;
+
 /**
  * Creates and configures the FormSpec language server connection.
  *
@@ -69,6 +72,17 @@ export declare interface CreateServerOptions {
     readonly diagnosticSource?: string;
 }
 
+/**
+ * Converts a `file://` URI to an absolute filesystem path.
+ *
+ * Returns `null` for any URI that is not a valid `file://` URI (e.g. `untitled:`, `vscode-notebook-cell:`,
+ * malformed URIs). On Windows the returned path uses backslash separators as produced by
+ * `url.fileURLToPath`.
+ *
+ * @public
+ */
+export declare function fileUriToPathOrNull(uri: string): string | null;
+
 /**
  * File-local diagnostic derived from comment parsing or semantic analysis.
  *
@@ -110,6 +124,83 @@ export declare interface FormSpecAnalysisDiagnosticLocation {
     readonly message?: string;
 }
 
+/** @public */
+declare type FormSpecPlacement = "class" | "class-field" | "class-method" | "interface" | "interface-field" | "type-alias" | "type-alias-field" | "variable" | "function" | "function-parameter" | "method-parameter";
+
+/**
+ * Cursor-scoped completion context serialized for transport between the
+ * semantic tsserver plugin and the lightweight LSP.
+ *
+ * @public
+ */
+declare type FormSpecSerializedCompletionContext = {
+    readonly kind: "tag-name";
+    readonly prefix: string;
+    readonly availableTags: readonly FormSpecSerializedTagDefinition[];
+} | {
+    readonly kind: "target";
+    readonly semantic: FormSpecSerializedTagSemanticContext;
+} | {
+    readonly kind: "argument";
+    readonly semantic: FormSpecSerializedTagSemanticContext;
+    readonly valueLabels: readonly string[];
+} | {
+    readonly kind: "none";
+};
+
+/**
+ * Hover payload for a single comment token under the cursor.
+ *
+ * @public
+ */
+declare interface FormSpecSerializedHoverInfo {
+    readonly kind: "tag-name" | "target" | "argument";
+    readonly markdown: string;
+}
+
+/**
+ * Serializable subset of tag metadata needed by hover and completion UIs.
+ *
+ * @public
+ */
+declare interface FormSpecSerializedTagDefinition {
+    readonly canonicalName: string;
+    readonly completionDetail: string;
+    readonly hoverMarkdown: string;
+}
+
+/**
+ * Semantic facts about one parsed tag, reduced to JSON-safe data for IPC.
+ *
+ * @public
+ */
+declare interface FormSpecSerializedTagSemanticContext {
+    readonly tagName: string;
+    readonly tagDefinition: FormSpecSerializedTagDefinition | null;
+    readonly placement: FormSpecPlacement | null;
+    readonly supportedTargets: readonly FormSpecTargetKind[];
+    readonly targetCompletions: readonly string[];
+    readonly compatiblePathTargets: readonly string[];
+    readonly valueLabels: readonly string[];
+    readonly signatures: readonly FormSpecSerializedTagSignature[];
+    readonly tagHoverMarkdown: string | null;
+    readonly targetHoverMarkdown: string | null;
+    readonly argumentHoverMarkdown: string | null;
+}
+
+/**
+ * Serializable overload/signature summary for one comment tag form.
+ *
+ * @public
+ */
+declare interface FormSpecSerializedTagSignature {
+    readonly label: string;
+    readonly placements: readonly FormSpecPlacement[];
+}
+
+/** @public */
+declare type FormSpecTargetKind = "none" | "path" | "member" | "variant";
+
 /**
  * Returns the full set of tag-name completions currently known to FormSpec.
  *
@@ -117,6 +208,17 @@ export declare interface FormSpecAnalysisDiagnosticLocation {
  */
 export declare function getCompletionItems(extensions?: readonly ExtensionDefinition[]): CompletionItem[];
 
+/**
+ * Returns completion items for the cursor position at `offset` in `documentText`.
+ *
+ * When `semanticContext` is supplied (e.g. from {@link getPluginCompletionContextForDocument}),
+ * it is used directly to produce target-value or tag-name completions. Pass `null` or omit it
+ * to fall back to syntax-only analysis, which works without the TypeScript plugin.
+ *
+ * @public
+ */
+export declare function getCompletionItemsAtOffset(documentText: string, offset: number, extensions?: readonly ExtensionDefinition[], semanticContext?: FormSpecSerializedCompletionContext | null): CompletionItem[];
+
 /**
  * Returns the definition location for a symbol at the given position.
  *
@@ -127,6 +229,18 @@ export declare function getCompletionItems(extensions?: readonly ExtensionDefini
  */
 export declare function getDefinition(): Location | null;
 
+/**
+ * Returns LSP hover content for the cursor position at `offset` in `documentText`.
+ *
+ * When `semanticHover` is supplied (e.g. from {@link getPluginHoverForDocument}), it is used
+ * directly as the hover source. Pass `null` or omit it to fall back to syntax-only analysis,
+ * which works without the TypeScript plugin. Returns `null` when the cursor is not over a
+ * recognised FormSpec tag.
+ *
+ * @public
+ */
+export declare function getHoverAtOffset(documentText: string, offset: number, extensions?: readonly ExtensionDefinition[], semanticHover?: FormSpecSerializedHoverInfo | null): Hover | null;
+
 /**
  * Returns hover content for a single FormSpec tag name.
  *
@@ -134,6 +248,22 @@ export declare function getDefinition(): Location | null;
  */
 export declare function getHoverForTag(tagName: string, extensions?: readonly ExtensionDefinition[]): Hover | null;
 
+/**
+ * Queries the FormSpec TypeScript plugin for semantic completion context at `offset` in the
+ * document identified by `filePath`.
+ *
+ * The workspace root containing `filePath` is located automatically from `workspaceRoots`. The
+ * plugin manifest is read from disk on each call. Returns `null` when no matching workspace root
+ * is found, the manifest is missing or invalid, the IPC socket is unavailable, the plugin times
+ * out (default 2 s), or the plugin's response was computed against a different version of the
+ * document than `documentText` (stale response guard).
+ *
+ * Pass the result to {@link getCompletionItemsAtOffset} as `semanticContext`.
+ *
+ * @public
+ */
+export declare function getPluginCompletionContextForDocument(workspaceRoots: readonly string[], filePath: string, documentText: string, offset: number, timeoutMs?: number): Promise<FormSpecSerializedCompletionContext | null>;
+
 /**
  * Retrieves canonical FormSpec diagnostics for the current document revision
  * from the plugin transport. Returns `null` when the transport is missing,
@@ -143,6 +273,22 @@ export declare function getHoverForTag(tagName: string, extensions?: readonly Ex
  */
 export declare function getPluginDiagnosticsForDocument(workspaceRoots: readonly string[], filePath: string, documentText: string, timeoutMs?: number): Promise<readonly FormSpecAnalysisDiagnostic[] | null>;
 
+/**
+ * Queries the FormSpec TypeScript plugin for semantic hover information at `offset` in the
+ * document identified by `filePath`.
+ *
+ * The workspace root containing `filePath` is located automatically from `workspaceRoots`. The
+ * plugin manifest is read from disk on each call. Returns `null` when no matching workspace root
+ * is found, the manifest is missing or invalid, the IPC socket is unavailable, the plugin times
+ * out (default 2 s), or the plugin's response was computed against a different version of the
+ * document than `documentText` (stale response guard).
+ *
+ * Pass the result to {@link getHoverAtOffset} as `semanticHover`.
+ *
+ * @public
+ */
+export declare function getPluginHoverForDocument(workspaceRoots: readonly string[], filePath: string, documentText: string, offset: number, timeoutMs?: number): Promise<FormSpecSerializedHoverInfo | null>;
+
 /**
  * Converts canonical FormSpec diagnostics into LSP diagnostics.
  *

package/dist/language-server-internal.d.ts

@@ -33,11 +33,14 @@ import type { Location } from 'vscode-languageserver/node.js';
 import type { TextDocument } from 'vscode-languageserver-textdocument';
 
 /** @public */
-export declare interface CommentSpan {
+export declare interface CommentSourceSpan {
     readonly start: number;
     readonly end: number;
 }
 
+/** @public */
+export declare type CommentSpan = CommentSourceSpan;
+
 /**
  * Creates and configures the FormSpec language server connection.
  *
@@ -69,6 +72,17 @@ export declare interface CreateServerOptions {
     readonly diagnosticSource?: string;
 }
 
+/**
+ * Converts a `file://` URI to an absolute filesystem path.
+ *
+ * Returns `null` for any URI that is not a valid `file://` URI (e.g. `untitled:`, `vscode-notebook-cell:`,
+ * malformed URIs). On Windows the returned path uses backslash separators as produced by
+ * `url.fileURLToPath`.
+ *
+ * @public
+ */
+export declare function fileUriToPathOrNull(uri: string): string | null;
+
 /**
  * File-local diagnostic derived from comment parsing or semantic analysis.
  *
@@ -110,6 +124,83 @@ export declare interface FormSpecAnalysisDiagnosticLocation {
     readonly message?: string;
 }
 
+/** @public */
+declare type FormSpecPlacement = "class" | "class-field" | "class-method" | "interface" | "interface-field" | "type-alias" | "type-alias-field" | "variable" | "function" | "function-parameter" | "method-parameter";
+
+/**
+ * Cursor-scoped completion context serialized for transport between the
+ * semantic tsserver plugin and the lightweight LSP.
+ *
+ * @public
+ */
+declare type FormSpecSerializedCompletionContext = {
+    readonly kind: "tag-name";
+    readonly prefix: string;
+    readonly availableTags: readonly FormSpecSerializedTagDefinition[];
+} | {
+    readonly kind: "target";
+    readonly semantic: FormSpecSerializedTagSemanticContext;
+} | {
+    readonly kind: "argument";
+    readonly semantic: FormSpecSerializedTagSemanticContext;
+    readonly valueLabels: readonly string[];
+} | {
+    readonly kind: "none";
+};
+
+/**
+ * Hover payload for a single comment token under the cursor.
+ *
+ * @public
+ */
+declare interface FormSpecSerializedHoverInfo {
+    readonly kind: "tag-name" | "target" | "argument";
+    readonly markdown: string;
+}
+
+/**
+ * Serializable subset of tag metadata needed by hover and completion UIs.
+ *
+ * @public
+ */
+declare interface FormSpecSerializedTagDefinition {
+    readonly canonicalName: string;
+    readonly completionDetail: string;
+    readonly hoverMarkdown: string;
+}
+
+/**
+ * Semantic facts about one parsed tag, reduced to JSON-safe data for IPC.
+ *
+ * @public
+ */
+declare interface FormSpecSerializedTagSemanticContext {
+    readonly tagName: string;
+    readonly tagDefinition: FormSpecSerializedTagDefinition | null;
+    readonly placement: FormSpecPlacement | null;
+    readonly supportedTargets: readonly FormSpecTargetKind[];
+    readonly targetCompletions: readonly string[];
+    readonly compatiblePathTargets: readonly string[];
+    readonly valueLabels: readonly string[];
+    readonly signatures: readonly FormSpecSerializedTagSignature[];
+    readonly tagHoverMarkdown: string | null;
+    readonly targetHoverMarkdown: string | null;
+    readonly argumentHoverMarkdown: string | null;
+}
+
+/**
+ * Serializable overload/signature summary for one comment tag form.
+ *
+ * @public
+ */
+declare interface FormSpecSerializedTagSignature {
+    readonly label: string;
+    readonly placements: readonly FormSpecPlacement[];
+}
+
+/** @public */
+declare type FormSpecTargetKind = "none" | "path" | "member" | "variant";
+
 /**
  * Returns the full set of tag-name completions currently known to FormSpec.
  *
@@ -117,6 +208,17 @@ export declare interface FormSpecAnalysisDiagnosticLocation {
  */
 export declare function getCompletionItems(extensions?: readonly ExtensionDefinition[]): CompletionItem[];
 
+/**
+ * Returns completion items for the cursor position at `offset` in `documentText`.
+ *
+ * When `semanticContext` is supplied (e.g. from {@link getPluginCompletionContextForDocument}),
+ * it is used directly to produce target-value or tag-name completions. Pass `null` or omit it
+ * to fall back to syntax-only analysis, which works without the TypeScript plugin.
+ *
+ * @public
+ */
+export declare function getCompletionItemsAtOffset(documentText: string, offset: number, extensions?: readonly ExtensionDefinition[], semanticContext?: FormSpecSerializedCompletionContext | null): CompletionItem[];
+
 /**
  * Returns the definition location for a symbol at the given position.
  *
@@ -127,6 +229,18 @@ export declare function getCompletionItems(extensions?: readonly ExtensionDefini
  */
 export declare function getDefinition(): Location | null;
 
+/**
+ * Returns LSP hover content for the cursor position at `offset` in `documentText`.
+ *
+ * When `semanticHover` is supplied (e.g. from {@link getPluginHoverForDocument}), it is used
+ * directly as the hover source. Pass `null` or omit it to fall back to syntax-only analysis,
+ * which works without the TypeScript plugin. Returns `null` when the cursor is not over a
+ * recognised FormSpec tag.
+ *
+ * @public
+ */
+export declare function getHoverAtOffset(documentText: string, offset: number, extensions?: readonly ExtensionDefinition[], semanticHover?: FormSpecSerializedHoverInfo | null): Hover | null;
+
 /**
  * Returns hover content for a single FormSpec tag name.
  *
@@ -134,6 +248,22 @@ export declare function getDefinition(): Location | null;
  */
 export declare function getHoverForTag(tagName: string, extensions?: readonly ExtensionDefinition[]): Hover | null;
 
+/**
+ * Queries the FormSpec TypeScript plugin for semantic completion context at `offset` in the
+ * document identified by `filePath`.
+ *
+ * The workspace root containing `filePath` is located automatically from `workspaceRoots`. The
+ * plugin manifest is read from disk on each call. Returns `null` when no matching workspace root
+ * is found, the manifest is missing or invalid, the IPC socket is unavailable, the plugin times
+ * out (default 2 s), or the plugin's response was computed against a different version of the
+ * document than `documentText` (stale response guard).
+ *
+ * Pass the result to {@link getCompletionItemsAtOffset} as `semanticContext`.
+ *
+ * @public
+ */
+export declare function getPluginCompletionContextForDocument(workspaceRoots: readonly string[], filePath: string, documentText: string, offset: number, timeoutMs?: number): Promise<FormSpecSerializedCompletionContext | null>;
+
 /**
  * Retrieves canonical FormSpec diagnostics for the current document revision
  * from the plugin transport. Returns `null` when the transport is missing,
@@ -143,6 +273,22 @@ export declare function getHoverForTag(tagName: string, extensions?: readonly Ex
  */
 export declare function getPluginDiagnosticsForDocument(workspaceRoots: readonly string[], filePath: string, documentText: string, timeoutMs?: number): Promise<readonly FormSpecAnalysisDiagnostic[] | null>;
 
+/**
+ * Queries the FormSpec TypeScript plugin for semantic hover information at `offset` in the
+ * document identified by `filePath`.
+ *
+ * The workspace root containing `filePath` is located automatically from `workspaceRoots`. The
+ * plugin manifest is read from disk on each call. Returns `null` when no matching workspace root
+ * is found, the manifest is missing or invalid, the IPC socket is unavailable, the plugin times
+ * out (default 2 s), or the plugin's response was computed against a different version of the
+ * document than `documentText` (stale response guard).
+ *
+ * Pass the result to {@link getHoverAtOffset} as `semanticHover`.
+ *
+ * @public
+ */
+export declare function getPluginHoverForDocument(workspaceRoots: readonly string[], filePath: string, documentText: string, offset: number, timeoutMs?: number): Promise<FormSpecSerializedHoverInfo | null>;
+
 /**
  * Converts canonical FormSpec diagnostics into LSP diagnostics.
  *

package/dist/language-server.d.ts

@@ -33,11 +33,14 @@ import type { Location } from 'vscode-languageserver/node.js';
 import type { TextDocument } from 'vscode-languageserver-textdocument';
 
 /** @public */
-export declare interface CommentSpan {
+export declare interface CommentSourceSpan {
     readonly start: number;
     readonly end: number;
 }
 
+/** @public */
+export declare type CommentSpan = CommentSourceSpan;
+
 /**
  * Creates and configures the FormSpec language server connection.
  *
@@ -69,6 +72,17 @@ export declare interface CreateServerOptions {
     readonly diagnosticSource?: string;
 }
 
+/**
+ * Converts a `file://` URI to an absolute filesystem path.
+ *
+ * Returns `null` for any URI that is not a valid `file://` URI (e.g. `untitled:`, `vscode-notebook-cell:`,
+ * malformed URIs). On Windows the returned path uses backslash separators as produced by
+ * `url.fileURLToPath`.
+ *
+ * @public
+ */
+export declare function fileUriToPathOrNull(uri: string): string | null;
+
 /**
  * File-local diagnostic derived from comment parsing or semantic analysis.
  *
@@ -110,6 +124,83 @@ export declare interface FormSpecAnalysisDiagnosticLocation {
     readonly message?: string;
 }
 
+/** @public */
+declare type FormSpecPlacement = "class" | "class-field" | "class-method" | "interface" | "interface-field" | "type-alias" | "type-alias-field" | "variable" | "function" | "function-parameter" | "method-parameter";
+
+/**
+ * Cursor-scoped completion context serialized for transport between the
+ * semantic tsserver plugin and the lightweight LSP.
+ *
+ * @public
+ */
+declare type FormSpecSerializedCompletionContext = {
+    readonly kind: "tag-name";
+    readonly prefix: string;
+    readonly availableTags: readonly FormSpecSerializedTagDefinition[];
+} | {
+    readonly kind: "target";
+    readonly semantic: FormSpecSerializedTagSemanticContext;
+} | {
+    readonly kind: "argument";
+    readonly semantic: FormSpecSerializedTagSemanticContext;
+    readonly valueLabels: readonly string[];
+} | {
+    readonly kind: "none";
+};
+
+/**
+ * Hover payload for a single comment token under the cursor.
+ *
+ * @public
+ */
+declare interface FormSpecSerializedHoverInfo {
+    readonly kind: "tag-name" | "target" | "argument";
+    readonly markdown: string;
+}
+
+/**
+ * Serializable subset of tag metadata needed by hover and completion UIs.
+ *
+ * @public
+ */
+declare interface FormSpecSerializedTagDefinition {
+    readonly canonicalName: string;
+    readonly completionDetail: string;
+    readonly hoverMarkdown: string;
+}
+
+/**
+ * Semantic facts about one parsed tag, reduced to JSON-safe data for IPC.
+ *
+ * @public
+ */
+declare interface FormSpecSerializedTagSemanticContext {
+    readonly tagName: string;
+    readonly tagDefinition: FormSpecSerializedTagDefinition | null;
+    readonly placement: FormSpecPlacement | null;
+    readonly supportedTargets: readonly FormSpecTargetKind[];
+    readonly targetCompletions: readonly string[];
+    readonly compatiblePathTargets: readonly string[];
+    readonly valueLabels: readonly string[];
+    readonly signatures: readonly FormSpecSerializedTagSignature[];
+    readonly tagHoverMarkdown: string | null;
+    readonly targetHoverMarkdown: string | null;
+    readonly argumentHoverMarkdown: string | null;
+}
+
+/**
+ * Serializable overload/signature summary for one comment tag form.
+ *
+ * @public
+ */
+declare interface FormSpecSerializedTagSignature {
+    readonly label: string;
+    readonly placements: readonly FormSpecPlacement[];
+}
+
+/** @public */
+declare type FormSpecTargetKind = "none" | "path" | "member" | "variant";
+
 /**
  * Returns the full set of tag-name completions currently known to FormSpec.
  *
@@ -117,6 +208,17 @@ export declare interface FormSpecAnalysisDiagnosticLocation {
  */
 export declare function getCompletionItems(extensions?: readonly ExtensionDefinition[]): CompletionItem[];
 
+/**
+ * Returns completion items for the cursor position at `offset` in `documentText`.
+ *
+ * When `semanticContext` is supplied (e.g. from {@link getPluginCompletionContextForDocument}),
+ * it is used directly to produce target-value or tag-name completions. Pass `null` or omit it
+ * to fall back to syntax-only analysis, which works without the TypeScript plugin.
+ *
+ * @public
+ */
+export declare function getCompletionItemsAtOffset(documentText: string, offset: number, extensions?: readonly ExtensionDefinition[], semanticContext?: FormSpecSerializedCompletionContext | null): CompletionItem[];
+
 /**
  * Returns the definition location for a symbol at the given position.
  *
@@ -127,6 +229,18 @@ export declare function getCompletionItems(extensions?: readonly ExtensionDefini
  */
 export declare function getDefinition(): Location | null;
 
+/**
+ * Returns LSP hover content for the cursor position at `offset` in `documentText`.
+ *
+ * When `semanticHover` is supplied (e.g. from {@link getPluginHoverForDocument}), it is used
+ * directly as the hover source. Pass `null` or omit it to fall back to syntax-only analysis,
+ * which works without the TypeScript plugin. Returns `null` when the cursor is not over a
+ * recognised FormSpec tag.
+ *
+ * @public
+ */
+export declare function getHoverAtOffset(documentText: string, offset: number, extensions?: readonly ExtensionDefinition[], semanticHover?: FormSpecSerializedHoverInfo | null): Hover | null;
+
 /**
  * Returns hover content for a single FormSpec tag name.
  *
@@ -134,6 +248,22 @@ export declare function getDefinition(): Location | null;
  */
 export declare function getHoverForTag(tagName: string, extensions?: readonly ExtensionDefinition[]): Hover | null;
 
+/**
+ * Queries the FormSpec TypeScript plugin for semantic completion context at `offset` in the
+ * document identified by `filePath`.
+ *
+ * The workspace root containing `filePath` is located automatically from `workspaceRoots`. The
+ * plugin manifest is read from disk on each call. Returns `null` when no matching workspace root
+ * is found, the manifest is missing or invalid, the IPC socket is unavailable, the plugin times
+ * out (default 2 s), or the plugin's response was computed against a different version of the
+ * document than `documentText` (stale response guard).
+ *
+ * Pass the result to {@link getCompletionItemsAtOffset} as `semanticContext`.
+ *
+ * @public
+ */
+export declare function getPluginCompletionContextForDocument(workspaceRoots: readonly string[], filePath: string, documentText: string, offset: number, timeoutMs?: number): Promise<FormSpecSerializedCompletionContext | null>;
+
 /**
  * Retrieves canonical FormSpec diagnostics for the current document revision
  * from the plugin transport. Returns `null` when the transport is missing,
@@ -143,6 +273,22 @@ export declare function getHoverForTag(tagName: string, extensions?: readonly Ex
  */
 export declare function getPluginDiagnosticsForDocument(workspaceRoots: readonly string[], filePath: string, documentText: string, timeoutMs?: number): Promise<readonly FormSpecAnalysisDiagnostic[] | null>;
 
+/**
+ * Queries the FormSpec TypeScript plugin for semantic hover information at `offset` in the
+ * document identified by `filePath`.
+ *
+ * The workspace root containing `filePath` is located automatically from `workspaceRoots`. The
+ * plugin manifest is read from disk on each call. Returns `null` when no matching workspace root
+ * is found, the manifest is missing or invalid, the IPC socket is unavailable, the plugin times
+ * out (default 2 s), or the plugin's response was computed against a different version of the
+ * document than `documentText` (stale response guard).
+ *
+ * Pass the result to {@link getHoverAtOffset} as `semanticHover`.
+ *
+ * @public
+ */
+export declare function getPluginHoverForDocument(workspaceRoots: readonly string[], filePath: string, documentText: string, offset: number, timeoutMs?: number): Promise<FormSpecSerializedHoverInfo | null>;
+
 /**
  * Converts canonical FormSpec diagnostics into LSP diagnostics.
  *

package/dist/plugin-client.d.ts

@@ -1,6 +1,43 @@
 import { type FormSpecAnalysisDiagnostic, type FormSpecSerializedCompletionContext, type FormSpecSerializedHoverInfo } from "@formspec/analysis/protocol";
+/**
+ * Converts a `file://` URI to an absolute filesystem path.
+ *
+ * Returns `null` for any URI that is not a valid `file://` URI (e.g. `untitled:`, `vscode-notebook-cell:`,
+ * malformed URIs). On Windows the returned path uses backslash separators as produced by
+ * `url.fileURLToPath`.
+ *
+ * @public
+ */
 export declare function fileUriToPathOrNull(uri: string): string | null;
+/**
+ * Queries the FormSpec TypeScript plugin for semantic completion context at `offset` in the
+ * document identified by `filePath`.
+ *
+ * The workspace root containing `filePath` is located automatically from `workspaceRoots`. The
+ * plugin manifest is read from disk on each call. Returns `null` when no matching workspace root
+ * is found, the manifest is missing or invalid, the IPC socket is unavailable, the plugin times
+ * out (default 2 s), or the plugin's response was computed against a different version of the
+ * document than `documentText` (stale response guard).
+ *
+ * Pass the result to {@link getCompletionItemsAtOffset} as `semanticContext`.
+ *
+ * @public
+ */
 export declare function getPluginCompletionContextForDocument(workspaceRoots: readonly string[], filePath: string, documentText: string, offset: number, timeoutMs?: number): Promise<FormSpecSerializedCompletionContext | null>;
+/**
+ * Queries the FormSpec TypeScript plugin for semantic hover information at `offset` in the
+ * document identified by `filePath`.
+ *
+ * The workspace root containing `filePath` is located automatically from `workspaceRoots`. The
+ * plugin manifest is read from disk on each call. Returns `null` when no matching workspace root
+ * is found, the manifest is missing or invalid, the IPC socket is unavailable, the plugin times
+ * out (default 2 s), or the plugin's response was computed against a different version of the
+ * document than `documentText` (stale response guard).
+ *
+ * Pass the result to {@link getHoverAtOffset} as `semanticHover`.
+ *
+ * @public
+ */
 export declare function getPluginHoverForDocument(workspaceRoots: readonly string[], filePath: string, documentText: string, offset: number, timeoutMs?: number): Promise<FormSpecSerializedHoverInfo | null>;
 /**
  * Retrieves canonical FormSpec diagnostics for the current document revision

package/dist/plugin-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin-client.d.ts","sourceRoot":"","sources":["../src/plugin-client.ts"],"names":[],"mappings":"AAIA,OAAO,EAKL,KAAK,0BAA0B,EAE/B,KAAK,mCAAmC,EACxC,KAAK,2BAA2B,EAGjC,MAAM,6BAA6B,CAAC;AAyGrC,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM9D;AAqBD,wBAAsB,qCAAqC,CACzD,cAAc,EAAE,SAAS,MAAM,EAAE,EACjC,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,SAAS,SAAkC,GAC1C,OAAO,CAAC,mCAAmC,GAAG,IAAI,CAAC,CAiBrD;AAED,wBAAsB,yBAAyB,CAC7C,cAAc,EAAE,SAAS,MAAM,EAAE,EACjC,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,SAAS,SAAkC,GAC1C,OAAO,CAAC,2BAA2B,GAAG,IAAI,CAAC,CAiB7C;AAED;;;;;;GAMG;AACH,wBAAsB,+BAA+B,CACnD,cAAc,EAAE,SAAS,MAAM,EAAE,EACjC,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,SAAS,SAAkC,GAC1C,OAAO,CAAC,SAAS,0BAA0B,EAAE,GAAG,IAAI,CAAC,CAkBvD"}
+{"version":3,"file":"plugin-client.d.ts","sourceRoot":"","sources":["../src/plugin-client.ts"],"names":[],"mappings":"AAIA,OAAO,EAKL,KAAK,0BAA0B,EAE/B,KAAK,mCAAmC,EACxC,KAAK,2BAA2B,EAGjC,MAAM,6BAA6B,CAAC;AAyGrC;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM9D;AAqBD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,qCAAqC,CACzD,cAAc,EAAE,SAAS,MAAM,EAAE,EACjC,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,SAAS,SAAkC,GAC1C,OAAO,CAAC,mCAAmC,GAAG,IAAI,CAAC,CAiBrD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,yBAAyB,CAC7C,cAAc,EAAE,SAAS,MAAM,EAAE,EACjC,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,SAAS,SAAkC,GAC1C,OAAO,CAAC,2BAA2B,GAAG,IAAI,CAAC,CAiB7C;AAED;;;;;;GAMG;AACH,wBAAsB,+BAA+B,CACnD,cAAc,EAAE,SAAS,MAAM,EAAE,EACjC,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,SAAS,SAAkC,GAC1C,OAAO,CAAC,SAAS,0BAA0B,EAAE,GAAG,IAAI,CAAC,CAkBvD"}

package/dist/providers/completion.d.ts

@@ -13,6 +13,14 @@ import { CompletionItem } from "vscode-languageserver/node.js";
  * @public
  */
 export declare function getCompletionItems(extensions?: readonly ExtensionDefinition[]): CompletionItem[];
-/** @internal */
+/**
+ * Returns completion items for the cursor position at `offset` in `documentText`.
+ *
+ * When `semanticContext` is supplied (e.g. from {@link getPluginCompletionContextForDocument}),
+ * it is used directly to produce target-value or tag-name completions. Pass `null` or omit it
+ * to fall back to syntax-only analysis, which works without the TypeScript plugin.
+ *
+ * @public
+ */
 export declare function getCompletionItemsAtOffset(documentText: string, offset: number, extensions?: readonly ExtensionDefinition[], semanticContext?: FormSpecSerializedCompletionContext | null): CompletionItem[];
 //# sourceMappingURL=completion.d.ts.map

package/dist/providers/completion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"completion.d.ts","sourceRoot":"","sources":["../../src/providers/completion.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,KAAK,mCAAmC,EAKzC,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAsB,MAAM,+BAA+B,CAAC;AAEnF;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,CAAC,EAAE,SAAS,mBAAmB,EAAE,GAAG,cAAc,EAAE,CAMhG;AAkCD,gBAAgB;AAChB,wBAAgB,0BAA0B,CACxC,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,SAAS,mBAAmB,EAAE,EAC3C,eAAe,CAAC,EAAE,mCAAmC,GAAG,IAAI,GAC3D,cAAc,EAAE,CAkClB"}
+{"version":3,"file":"completion.d.ts","sourceRoot":"","sources":["../../src/providers/completion.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,KAAK,mCAAmC,EAKzC,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAsB,MAAM,+BAA+B,CAAC;AAEnF;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,CAAC,EAAE,SAAS,mBAAmB,EAAE,GAAG,cAAc,EAAE,CAMhG;AAkCD;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,SAAS,mBAAmB,EAAE,EAC3C,eAAe,CAAC,EAAE,mCAAmC,GAAG,IAAI,GAC3D,cAAc,EAAE,CAkClB"}

package/dist/providers/hover.d.ts

@@ -13,6 +13,15 @@ import type { Hover } from "vscode-languageserver/node.js";
  * @public
  */
 export declare function getHoverForTag(tagName: string, extensions?: readonly ExtensionDefinition[]): Hover | null;
-/** @internal */
+/**
+ * Returns LSP hover content for the cursor position at `offset` in `documentText`.
+ *
+ * When `semanticHover` is supplied (e.g. from {@link getPluginHoverForDocument}), it is used
+ * directly as the hover source. Pass `null` or omit it to fall back to syntax-only analysis,
+ * which works without the TypeScript plugin. Returns `null` when the cursor is not over a
+ * recognised FormSpec tag.
+ *
+ * @public
+ */
 export declare function getHoverAtOffset(documentText: string, offset: number, extensions?: readonly ExtensionDefinition[], semanticHover?: FormSpecSerializedHoverInfo | null): Hover | null;
 //# sourceMappingURL=hover.d.ts.map