@vizejs/plugin-sdk 0.716.0 → 0.718.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,7 +1,7 @@
1
1
  # @vizejs/plugin-sdk
2
2
 
3
3
  Author synchronous rules, fact providers, native template transforms and compiled
4
- output hooks. Install `@vizejs/native` **0.716.0 or newer** to execute plugins.
4
+ output hooks. Install `@vizejs/native` **0.718.0 or newer** to execute plugins.
5
5
  The optional native peer lets this package install independently for authoring;
6
6
  its helpers alone do not compile or lint Vue files. Node 22 or newer is required.
7
7
 
package/facts.d.ts CHANGED
@@ -1,7 +1,9 @@
1
+ /** Template binding name and the position that introduced it. */
1
2
  export interface TemplateScopeEntry {
2
3
  readonly name: string;
3
4
  readonly position: "value" | "key" | "index" | "slot";
4
5
  }
6
+ /** Host classification for a script binding exposed to plugin facts. */
5
7
  export type BindingKind =
6
8
  | "setup-let"
7
9
  | "setup-maybe-ref"
@@ -20,6 +22,7 @@ export type BindingKind =
20
22
  | "js-global-bun"
21
23
  | "vue-global"
22
24
  | "external-module";
25
+ /** Script-setup marker or resolved classification for one binding. */
23
26
  export type BindingFact =
24
27
  | Readonly<{ scriptSetup: true }>
25
28
  | Readonly<{
@@ -27,39 +30,47 @@ export type BindingFact =
27
30
  span: readonly [number, number] | null;
28
31
  propKey: string | null;
29
32
  }>;
33
+ /** Unresolved template reference and its authored byte offset. */
30
34
  export interface UndefinedRefFact {
31
35
  readonly name: string;
32
36
  readonly offset: number;
33
37
  readonly context: string;
34
38
  }
39
+ /** Authored byte span for a binding with no observed reads. */
35
40
  export interface UnusedBindingFact {
36
41
  readonly span: readonly [number, number];
37
42
  }
43
+ /** Half-open UTF-8 byte range shared by source-backed facts. */
38
44
  export interface FactRange {
39
45
  readonly start: number;
40
46
  readonly end: number;
41
47
  }
48
+ /** One component prop occurrence, including dynamic-name and value state. */
42
49
  export interface ComponentPropUsage extends FactRange {
43
50
  readonly name: string;
44
51
  readonly nameIsDynamic: boolean;
45
52
  readonly value: string | null;
46
53
  readonly isDynamic: boolean;
47
54
  }
55
+ /** One component event-handler occurrence and its modifiers. */
48
56
  export interface ComponentEventUsage extends FactRange {
49
57
  readonly name: string;
50
58
  readonly nameIsDynamic: boolean;
51
59
  readonly handler: string | null;
52
60
  readonly modifiers: readonly string[];
53
61
  }
62
+ /** One component slot occurrence and its introduced scope variables. */
54
63
  export interface ComponentSlotUsage extends FactRange {
55
64
  readonly name: string;
56
65
  readonly nameIsDynamic: boolean;
57
66
  readonly scopeVars: readonly string[];
58
67
  readonly hasScope: boolean;
59
68
  }
69
+ /** One spread-prop expression applied to a component. */
60
70
  export interface ComponentSpreadUsage extends FactRange {
61
71
  readonly expression: string;
62
72
  }
73
+ /** Complete normalized usage of one component node. */
63
74
  export interface ComponentUsage extends FactRange {
64
75
  readonly name: string;
65
76
  readonly props: readonly ComponentPropUsage[];
@@ -70,19 +81,24 @@ export interface ComponentUsage extends FactRange {
70
81
  readonly scopeId: number;
71
82
  readonly vifGuard: string | null;
72
83
  }
84
+ /** Resolved component tag paired with its optional usage record. */
73
85
  export interface ComponentUsageSite {
74
86
  readonly tag: string;
75
87
  readonly usage: ComponentUsage | null;
76
88
  readonly usageIndex: number | null;
77
89
  readonly nameOrdinal: number | null;
78
90
  }
91
+ /** Import/export identity and every observed site for one component. */
79
92
  export interface ComponentUsagesFact {
80
93
  readonly module: string | null;
81
94
  readonly export: string;
82
95
  readonly sites: readonly ComponentUsageSite[];
83
96
  }
97
+ /** Stability class inferred for a reactive source. */
84
98
  export type ReactivityClass = "static" | "props-stable" | "reactive" | "unstable";
99
+ /** Confidence verdict attached to an inferred contract. */
85
100
  export type Verdict = "proven" | "refuted" | "unknown";
101
+ /** Effect that contributes to a reactive stability verdict. */
86
102
  export type ReactivityEffect =
87
103
  | "freeze"
88
104
  | "capture"
@@ -92,6 +108,7 @@ export type ReactivityEffect =
92
108
  | "mutate-global"
93
109
  | "call-unknown"
94
110
  | "allocate";
111
+ /** Vue API that created a reactive source. */
95
112
  export type ReactiveSourceKind =
96
113
  | "ref"
97
114
  | "shallow-ref"
@@ -102,6 +119,7 @@ export type ReactiveSourceKind =
102
119
  | "shallow-readonly"
103
120
  | "to-ref"
104
121
  | "to-refs";
122
+ /** Authored operation that loses or obscures reactive ownership. */
105
123
  export type ReactivityLoss =
106
124
  | Readonly<{
107
125
  kind: "reactive-destructure" | "ref-value-destructure";
@@ -137,6 +155,7 @@ export type ReactivityLoss =
137
155
  targetName: string;
138
156
  }>
139
157
  | Readonly<{ kind: "reactive-spread" | "reactive-reassign"; sourceName: string }>;
158
+ /** Reactive source classification or a detected reactivity-loss site. */
140
159
  export type ReactivityFact =
141
160
  | Readonly<{
142
161
  kind: "source";
@@ -154,14 +173,17 @@ export type ReactivityFact =
154
173
  end: number;
155
174
  }>;
156
175
 
176
+ /** Normalized string or symbol key used by provide/inject. */
157
177
  export interface ProvideKey {
158
178
  readonly kind: "string" | "symbol";
159
179
  readonly name: string;
160
180
  }
181
+ /** Shape through which an injected value is consumed. */
161
182
  export type InjectPattern =
162
183
  | Readonly<{ kind: "simple" }>
163
184
  | Readonly<{ kind: "object" | "array"; props: readonly string[] }>
164
185
  | Readonly<{ kind: "indirect"; injectVar: string; props: readonly string[]; offset: number }>;
186
+ /** Provide, inject, or composable-boundary fact from one source file. */
165
187
  export type ProvideInjectFact =
166
188
  | Readonly<{
167
189
  kind: "provide";
@@ -196,6 +218,7 @@ export type ProvideInjectFact =
196
218
  end: number;
197
219
  }>;
198
220
 
221
+ /** Async scheduling pattern that may race with a later mutation. */
199
222
  export type RaceRisk =
200
223
  | Readonly<{
201
224
  kind: "async-watcher";
@@ -215,10 +238,12 @@ export type RaceRisk =
215
238
  mutatedTargets: readonly string[];
216
239
  }>
217
240
  | Readonly<{ kind: "scheduled"; schedulerName: string; mutatedTargets: readonly string[] }>;
241
+ /** Source-backed asynchronous race-risk observation. */
218
242
  export interface RaceConditionFact extends FactRange {
219
243
  readonly kind: RaceRisk;
220
244
  }
221
245
 
246
+ /** Closed reason why complete public type information was unavailable. */
222
247
  export type UnresolvedTypeReason =
223
248
  | "external-world-unavailable"
224
249
  | "unbound"
@@ -229,6 +254,7 @@ export type UnresolvedTypeReason =
229
254
  | "ambiguous-export"
230
255
  | "resolution-cycle"
231
256
  | "resolution-limit";
257
+ /** Authored or resolved dependency reachable from a public type. */
232
258
  export interface TypeDependency {
233
259
  readonly name: string;
234
260
  readonly kind: "alias" | "interface" | "imported" | "unresolved";
@@ -240,15 +266,18 @@ export interface TypeDependency {
240
266
  readonly extends: readonly string[];
241
267
  readonly unresolved_reason: UnresolvedTypeReason | null;
242
268
  }
269
+ /** Resolution state and dependencies for a public type contract. */
243
270
  export interface TypeEnvironment {
244
271
  /** False means some reachable type information could not be resolved. */
245
272
  readonly complete: boolean;
246
273
  readonly declarations: readonly TypeDependency[];
247
274
  }
275
+ /** Name and optional type for a value exposed from a component instance. */
248
276
  export interface ExposeContract {
249
277
  readonly name: string;
250
278
  readonly type: string | null;
251
279
  }
280
+ /** Complete public component signature discovered from authored source. */
252
281
  export interface SignatureContract {
253
282
  readonly schema: 1;
254
283
  readonly name: string;
@@ -268,6 +297,7 @@ export interface SignatureContract {
268
297
  readonly exposes: readonly ExposeContract[];
269
298
  readonly type_dependencies: TypeEnvironment;
270
299
  }
300
+ /** Resolved public prop type, requirement, default, and dependencies. */
271
301
  export interface PropContract {
272
302
  readonly schema: 1;
273
303
  readonly name: string;
@@ -277,6 +307,7 @@ export interface PropContract {
277
307
  readonly model_modifiers: string | null;
278
308
  readonly type_dependencies: TypeEnvironment;
279
309
  }
310
+ /** Resolved public event payloads, validators, and dependencies. */
280
311
  export interface EmitContract {
281
312
  readonly schema: 1;
282
313
  readonly name: string;
@@ -287,12 +318,14 @@ export interface EmitContract {
287
318
  readonly validator_type_annotations: readonly string[];
288
319
  readonly type_dependencies: TypeEnvironment;
289
320
  }
321
+ /** Resolved public slot props and their type dependencies. */
290
322
  export interface SlotContract {
291
323
  readonly schema: 1;
292
324
  readonly name: string;
293
325
  readonly props: string | null;
294
326
  readonly type_dependencies: TypeEnvironment;
295
327
  }
328
+ /** Public spelling of a supported Vue reactive constructor. */
296
329
  export type AlphaReactiveKind =
297
330
  | "ref"
298
331
  | "shallowRef"
@@ -303,6 +336,7 @@ export type AlphaReactiveKind =
303
336
  | "shallowReadonly"
304
337
  | "toRef"
305
338
  | "toRefs";
339
+ /** Public reactivity contract for one component binding. */
306
340
  export interface ReactivityContract {
307
341
  readonly schema: 1;
308
342
  readonly name: string;
@@ -313,6 +347,7 @@ export interface ReactivityContract {
313
347
  readonly effects: readonly ReactivityEffect[];
314
348
  readonly type_dependencies: TypeEnvironment;
315
349
  }
350
+ /** Module and export identity for a component dependency. */
316
351
  export interface ComponentContract {
317
352
  readonly schema: 1;
318
353
  readonly module: string | null;
@@ -341,8 +376,11 @@ export interface FactGroups {
341
376
  readonly "reactivity-classes": ReadonlyMap<string, ReactivityContract>;
342
377
  readonly "component-references": ReadonlyMap<string, ComponentContract>;
343
378
  }
379
+ /** Key type used by one named host fact group. */
344
380
  export type FactKey<K extends keyof FactGroups> =
345
381
  FactGroups[K] extends ReadonlyMap<infer Key, unknown> ? Key : never;
382
+ /** Value type used by one named host fact group. */
346
383
  export type FactValue<K extends keyof FactGroups> =
347
384
  FactGroups[K] extends ReadonlyMap<unknown, infer Value> ? Value : never;
385
+ /** Serialized key/value entry used by one named host fact group. */
348
386
  export type FactEntry<K extends keyof FactGroups> = readonly [FactKey<K>, FactValue<K>];
package/fixes.d.ts CHANGED
@@ -1,3 +1,4 @@
1
+ /** Host-owned UTF-8 replacement proposed by a plugin rule. */
1
2
  export interface PluginFix {
2
3
  ruleId?: string;
3
4
  plugin?: string;
package/index.d.ts CHANGED
@@ -1,6 +1,8 @@
1
1
  import type { FactGroups } from "./facts.js";
2
2
 
3
+ /** Schema version accepted by rule-plugin batch payloads. */
3
4
  export declare const BATCH_SCHEMA: 1;
5
+ /** Host-owned syntax node exposed to deterministic rule plugins. */
4
6
  export interface PluginNode {
5
7
  readonly id: number;
6
8
  readonly parent?: number;
@@ -14,10 +16,12 @@ export interface PluginNode {
14
16
  readonly index: string | null;
15
17
  };
16
18
  }
19
+ /** Template binding visible at a node and the role that introduced it. */
17
20
  export interface ScopeEntry {
18
21
  readonly name: string;
19
22
  readonly position: "value" | "key" | "index" | "slot";
20
23
  }
24
+ /** Read-only host facts and reporting operations available to one rule. */
21
25
  export interface RuleContext {
22
26
  readonly nodes: readonly PluginNode[];
23
27
  facts(name: "templateScopes"): ReadonlyMap<number, readonly ScopeEntry[]>;
@@ -27,6 +31,7 @@ export interface RuleContext {
27
31
  /** Replace the whole reported node span; ranges are assigned by the host. */
28
32
  report(node: PluginNode, message: string, fix?: string): void;
29
33
  }
34
+ /** Authored rule-plugin definition before normalization and fingerprinting. */
30
35
  export interface PluginDefinition {
31
36
  name: string;
32
37
  version: string;
@@ -44,6 +49,7 @@ export interface Plugin extends Omit<PluginDefinition, "visit" | "demands" | "ca
44
49
  readonly fingerprint: string;
45
50
  run(batchJson: string): string;
46
51
  }
52
+ /** Serializable syntax and fact payload delivered to a rule plugin. */
47
53
  export interface VisitBatch {
48
54
  schema: 1;
49
55
  plugin?: string;
@@ -52,12 +58,15 @@ export interface VisitBatch {
52
58
  nodes: PluginNode[];
53
59
  facts: Record<string, Array<[string | number, unknown]>>;
54
60
  }
61
+ /** Validate, freeze, and fingerprint an authored rule-plugin definition. */
55
62
  export declare function definePlugin(definition: PluginDefinition): Plugin;
63
+ /** Run a normalized plugin against a serialized visit batch. */
56
64
  export declare function runBatch(
57
65
  plugin: Plugin,
58
66
  batch: VisitBatch,
59
67
  ): Array<{ rule: string; node: number; message: string; fix?: string }>;
60
68
 
69
+ /** Run every rule against an already decoded host source. */
61
70
  export declare function runRules(
62
71
  plugin: Plugin,
63
72
  source: {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vizejs/plugin-sdk",
3
- "version": "0.716.0",
3
+ "version": "0.718.0",
4
4
  "description": "Deterministic authoring and isolated execution for Vize JavaScript plugins",
5
5
  "homepage": "https://github.com/ubugeeei-prod/vize",
6
6
  "bugs": {
@@ -53,7 +53,7 @@
53
53
  "access": "public"
54
54
  },
55
55
  "devDependencies": {
56
- "@vizejs/native": "0.716.0"
56
+ "@vizejs/native": "0.718.0"
57
57
  },
58
58
  "peerDependencies": {
59
59
  "@vizejs/native": ">=0.429.0"
package/sandbox.d.ts CHANGED
@@ -4,17 +4,20 @@ import type { NativeHook, JsonValue, HookIdentity } from "./stages.js";
4
4
  * Closures and host imports are unavailable; process access stays in the container.
5
5
  */
6
6
  export type CallbackSource = string;
7
+ /** Stable hook identity and captured inputs accepted by the sandbox boundary. */
7
8
  export interface SandboxIdentity extends HookIdentity {
8
9
  visit?: readonly string[];
9
10
  demands?: readonly string[];
10
11
  configuration?: JsonValue;
11
12
  }
13
+ /** Rule, provider, transform, formatter, or output hook executable in isolation. */
12
14
  export type SandboxDefinition = SandboxIdentity &
13
15
  (
14
16
  | { family?: "rule"; rules: Readonly<Record<string, CallbackSource>> }
15
17
  | { family: "provider"; provides: readonly string[]; callback: CallbackSource }
16
18
  | { family: "transform" | "formatter" | "output"; callback: CallbackSource }
17
19
  );
20
+ /** Per-invocation time and serialized-byte limits for a sandbox process. */
18
21
  export interface SandboxLimits {
19
22
  /** 100..60000 ms; default 5000. Runtime check and cleanup each add at most 5000 ms. */
20
23
  timeoutMs?: number;
@@ -27,6 +30,7 @@ export interface SandboxLimits {
27
30
  * Runtime filesystem contents remain readable. Native callbacks are trusted.
28
31
  */
29
32
  export type SandboxHook = NativeHook & { readonly visit?: string[]; readonly demands?: string[] };
33
+ /** Validate a sandbox definition and create its isolated native-hook adapter. */
30
34
  export declare function createSandboxRunner(
31
35
  definition: SandboxIdentity & {
32
36
  family: "provider";
@@ -43,6 +47,7 @@ export declare function createSandboxRunner(
43
47
  definition: SandboxDefinition,
44
48
  limits?: SandboxLimits,
45
49
  ): SandboxHook;
50
+ /** Stable failure code reported by the sandbox runtime boundary. */
46
51
  export type SandboxErrorCode =
47
52
  | "runtime_unavailable"
48
53
  | "execution_stopped"
@@ -57,10 +62,12 @@ export interface SandboxExecutionObservation {
57
62
  readonly stdout: string | null;
58
63
  readonly stderr: string | null;
59
64
  }
65
+ /** Runtime failure with a stable code and optional partial execution evidence. */
60
66
  export declare class SandboxRuntimeError extends Error {
61
67
  readonly code: SandboxErrorCode;
62
68
  /** Frozen and non-enumerable; the request and environment are not copied into it. */
63
69
  readonly execution?: SandboxExecutionObservation;
64
70
  constructor(code: SandboxErrorCode, message: string, options?: ErrorOptions);
65
71
  }
72
+ /** Immutable container image reference required by sandbox runners. */
66
73
  export declare const SANDBOX_IMAGE: string;
package/stages.d.ts CHANGED
@@ -1,3 +1,4 @@
1
+ /** JSON-compatible value accepted across plugin process boundaries. */
1
2
  export type JsonValue =
2
3
  | null
3
4
  | boolean
@@ -5,6 +6,7 @@ export type JsonValue =
5
6
  | string
6
7
  | readonly JsonValue[]
7
8
  | { readonly [key: string]: JsonValue };
9
+ /** Authored hook identity and every input captured by its fingerprint. */
8
10
  export interface HookIdentity {
9
11
  name: string;
10
12
  version: string;
@@ -16,6 +18,7 @@ export interface NativeHook extends Omit<HookIdentity, "cacheInputs"> {
16
18
  readonly fingerprint: string;
17
19
  run(batchJson: string): string;
18
20
  }
21
+ /** Precanonical element and attribute payload delivered to transform hooks. */
19
22
  export interface StaticAttributeTransformBatch {
20
23
  readonly schema: 1;
21
24
  readonly stage: "s2-precanonical-static-attributes";
@@ -29,6 +32,7 @@ export interface StaticAttributeTransformBatch {
29
32
  readonly attrs: readonly { readonly name: string; readonly value: string | null }[];
30
33
  }[];
31
34
  }
35
+ /** Static attribute names that a precanonical transform may replace. */
32
36
  export type StaticAttributeName =
33
37
  | "class"
34
38
  | "id"
@@ -37,17 +41,20 @@ export type StaticAttributeName =
37
41
  | "alt"
38
42
  | `data-${string}`
39
43
  | `aria-${string}`;
44
+ /** Deterministic replacement for one static element attribute. */
40
45
  export interface StaticAttributeEdit {
41
46
  kind: "replace-static-attribute";
42
47
  node: number;
43
48
  name: StaticAttributeName;
44
49
  value: string | null;
45
50
  }
51
+ /** Validate and fingerprint a static-attribute transform hook. */
46
52
  export declare function defineTransformPlugin(
47
53
  definition: HookIdentity & {
48
54
  transform(batch: StaticAttributeTransformBatch): readonly StaticAttributeEdit[];
49
55
  },
50
56
  ): NativeHook;
57
+ /** Compiled module output visible to formatter and output hooks. */
51
58
  export interface CompiledArtifact {
52
59
  readonly code: string;
53
60
  readonly preamble: string;
@@ -56,6 +63,7 @@ export interface CompiledArtifact {
56
63
  readonly helpers: readonly string[];
57
64
  readonly templates?: readonly string[] | null;
58
65
  }
66
+ /** Shared host payload delivered after compilation. */
59
67
  export interface OutputBatch {
60
68
  readonly schema: 1;
61
69
  readonly plugin: string;
@@ -63,21 +71,26 @@ export interface OutputBatch {
63
71
  readonly offsetEncoding: "utf8";
64
72
  readonly compiled: CompiledArtifact;
65
73
  }
74
+ /** UTF-8 replacement emitted by a formatter hook. */
66
75
  export interface FormatEdit {
67
76
  start: number;
68
77
  end: number;
69
78
  text: string;
70
79
  }
80
+ /** Comment-only addition emitted before or after compiled code. */
71
81
  export interface OutputAddition {
72
82
  placement: "prepend" | "append";
73
83
  comment: string;
74
84
  }
85
+ /** Post-compilation payload specialized for formatter hooks. */
75
86
  export interface FormatterBatch extends OutputBatch {
76
87
  readonly family: "formatter";
77
88
  }
89
+ /** Post-compilation payload specialized for output hooks. */
78
90
  export interface OutputHookBatch extends OutputBatch {
79
91
  readonly family: "output";
80
92
  }
93
+ /** Validate and fingerprint a formatter or output hook. */
81
94
  export declare function defineOutputPlugin(
82
95
  definition: HookIdentity & {
83
96
  family: "formatter";
@@ -90,6 +103,7 @@ export declare function defineOutputPlugin(
90
103
  output(batch: OutputHookBatch): readonly OutputAddition[];
91
104
  },
92
105
  ): NativeHook & { readonly family: "output" };
106
+ /** Syntax and existing facts delivered to a fact-provider hook. */
93
107
  export interface FactProviderBatch {
94
108
  readonly schema: 1;
95
109
  readonly plugin: string;
@@ -98,6 +112,7 @@ export interface FactProviderBatch {
98
112
  readonly nodes: readonly import("./index.js").PluginNode[];
99
113
  readonly facts: Readonly<Record<string, readonly (readonly [string | number, JsonValue])[]>>;
100
114
  }
115
+ /** Validate and fingerprint a deterministic fact-provider hook. */
101
116
  export declare function defineFactProvider(
102
117
  definition: HookIdentity & {
103
118
  visit?: readonly string[];
package/visitor.d.ts CHANGED
@@ -1,7 +1,9 @@
1
1
  import type { PluginNode } from "./index.js";
2
2
  import type { JsonValue } from "./stages.js";
3
3
 
4
+ /** Visitor protocol version understood by this SDK. */
4
5
  export declare const VISITOR_API_VERSION: 1;
6
+ /** Closed capability vocabulary accepted during visitor negotiation. */
5
7
  export declare const VISITOR_CAPABILITIES: readonly [
6
8
  "sfc",
7
9
  "template",
@@ -13,7 +15,9 @@ export declare const VISITOR_CAPABILITIES: readonly [
13
15
  "format",
14
16
  "devtools-trace",
15
17
  ];
18
+ /** One capability from the versioned visitor vocabulary. */
16
19
  export type VisitorCapability = (typeof VISITOR_CAPABILITIES)[number];
20
+ /** Stable validation or negotiation failure reported by the visitor API. */
17
21
  export type VisitorErrorCode =
18
22
  | "invalid-definition"
19
23
  | "invalid-name"
@@ -34,16 +38,19 @@ export type VisitorErrorCode =
34
38
  | "invalid-event"
35
39
  | "invalid-visitor-result";
36
40
 
41
+ /** Definition or host-contract error with a stable code and field path. */
37
42
  export declare class VisitorPluginValidationError extends TypeError {
38
43
  readonly code: VisitorErrorCode;
39
44
  readonly field: string;
40
45
  }
41
46
 
47
+ /** Half-open UTF-8 byte range used by visitor payloads. */
42
48
  export interface VisitorRange {
43
49
  readonly start: number;
44
50
  readonly end: number;
45
51
  readonly encoding: "utf8";
46
52
  }
53
+ /** Diagnostic delivered to a visitor with source and severity metadata. */
47
54
  export interface VisitorDiagnostic {
48
55
  readonly code: string;
49
56
  readonly message: string;
@@ -51,55 +58,67 @@ export interface VisitorDiagnostic {
51
58
  readonly range: VisitorRange;
52
59
  readonly source?: string;
53
60
  }
61
+ /** Replacement edit associated with a lint visitor payload. */
54
62
  export interface VisitorFix {
55
63
  readonly range: VisitorRange;
56
64
  readonly text: string;
57
65
  }
66
+ /** One parsed block in an SFC visitor payload. */
58
67
  export interface VisitorSfcBlock {
59
68
  readonly kind: "template" | "script" | "script-setup" | "style" | "custom";
60
69
  readonly language: string | null;
61
70
  readonly range: VisitorRange;
62
71
  readonly attributes: Readonly<Record<string, string | null>>;
63
72
  }
73
+ /** Complete authored SFC source and its parsed block inventory. */
64
74
  export interface VisitorSfcPayload {
65
75
  readonly source: string;
66
76
  readonly blocks: readonly VisitorSfcBlock[];
67
77
  }
78
+ /** Normalized template nodes delivered to template visitors. */
68
79
  export interface VisitorTemplatePayload {
69
80
  readonly nodes: readonly PluginNode[];
70
81
  }
82
+ /** Authored script source, language, and optional negotiated syntax data. */
71
83
  export interface VisitorScriptPayload {
72
84
  readonly source: string;
73
85
  readonly language: "js" | "jsx" | "ts" | "tsx";
74
86
  /** Host-owned serialized syntax data. Its schema belongs to the negotiated host. */
75
87
  readonly syntax?: JsonValue;
76
88
  }
89
+ /** Authored style source and its scoped or module mode. */
77
90
  export interface VisitorStylePayload {
78
91
  readonly source: string;
79
92
  readonly language: string;
80
93
  readonly scoped: boolean;
81
94
  readonly module: boolean | string;
82
95
  }
96
+ /** Source-to-generated range pair for virtual TypeScript. */
83
97
  export interface VisitorVirtualTsMapping {
84
98
  readonly source: VisitorRange;
85
99
  readonly generated: VisitorRange;
86
100
  }
101
+ /** Virtual TypeScript code, file identities, and source mappings. */
87
102
  export interface VisitorVirtualTsPayload {
88
103
  readonly sourceFile: string;
89
104
  readonly virtualFile: string;
90
105
  readonly code: string;
91
106
  readonly mappings: readonly VisitorVirtualTsMapping[];
92
107
  }
108
+ /** Diagnostics currently owned by the host pipeline. */
93
109
  export interface VisitorDiagnosticsPayload {
94
110
  readonly diagnostics: readonly VisitorDiagnostic[];
95
111
  }
112
+ /** Lint diagnostics together with their available fixes. */
96
113
  export interface VisitorLintPayload extends VisitorDiagnosticsPayload {
97
114
  readonly fixes: readonly VisitorFix[];
98
115
  }
116
+ /** Authored and formatted source delivered to format visitors. */
99
117
  export interface VisitorFormatPayload {
100
118
  readonly source: string;
101
119
  readonly formatted: string;
102
120
  }
121
+ /** One parented timing event from the devtools trace pipeline. */
103
122
  export interface VisitorDevtoolsTraceEvent {
104
123
  readonly id: string;
105
124
  readonly parentId: string | null;
@@ -109,9 +128,11 @@ export interface VisitorDevtoolsTraceEvent {
109
128
  readonly durationNs: number;
110
129
  readonly data?: JsonValue;
111
130
  }
131
+ /** Ordered trace events delivered to a devtools visitor. */
112
132
  export interface VisitorDevtoolsTracePayload {
113
133
  readonly events: readonly VisitorDevtoolsTraceEvent[];
114
134
  }
135
+ /** Capability-to-payload mapping for every visitor event family. */
115
136
  export interface VisitorPayloads {
116
137
  readonly sfc: VisitorSfcPayload;
117
138
  readonly template: VisitorTemplatePayload;
@@ -123,20 +144,25 @@ export interface VisitorPayloads {
123
144
  readonly format: VisitorFormatPayload;
124
145
  readonly "devtools-trace": VisitorDevtoolsTracePayload;
125
146
  }
147
+ /** Versioned host event specialized by one visitor capability. */
126
148
  export interface VisitorEvent<C extends VisitorCapability = VisitorCapability> {
127
149
  readonly apiVersion: 1;
128
150
  readonly capability: C;
129
151
  readonly file: string;
130
152
  readonly payload: VisitorPayloads[C];
131
153
  }
154
+ /** Synchronous handler for one negotiated visitor event. */
132
155
  export type VisitorHandler<C extends VisitorCapability> = (event: VisitorEvent<C>) => void;
156
+ /** Exact handler map required by a capability tuple. */
133
157
  export type VisitorHandlers<C extends readonly VisitorCapability[]> = {
134
158
  readonly [K in C[number]]: VisitorHandler<K>;
135
159
  };
160
+ /** Captured ambient or configuration input included in a visitor fingerprint. */
136
161
  export interface VisitorCacheInput {
137
162
  readonly name: string;
138
163
  readonly value: string;
139
164
  }
165
+ /** Authored visitor descriptor before validation and fingerprinting. */
140
166
  export interface VisitorPluginDefinition<C extends readonly VisitorCapability[]> {
141
167
  readonly apiVersion: 1;
142
168
  readonly name: string;
@@ -146,6 +172,7 @@ export interface VisitorPluginDefinition<C extends readonly VisitorCapability[]>
146
172
  readonly cacheInputs: readonly VisitorCacheInput[];
147
173
  readonly visitors: VisitorHandlers<C>;
148
174
  }
175
+ /** Immutable visitor descriptor accepted by host negotiation. */
149
176
  export interface VisitorPlugin<
150
177
  C extends readonly VisitorCapability[] = readonly VisitorCapability[],
151
178
  > {
@@ -158,16 +185,19 @@ export interface VisitorPlugin<
158
185
  readonly visitors: VisitorHandlers<C>;
159
186
  readonly fingerprint: string;
160
187
  }
188
+ /** Visitor protocol version and capabilities supplied by a host. */
161
189
  export interface VisitorHostContract<
162
190
  C extends readonly VisitorCapability[] = readonly VisitorCapability[],
163
191
  > {
164
192
  readonly apiVersion: 1;
165
193
  readonly capabilities: C;
166
194
  }
195
+ /** Exact capabilities retained after successful host negotiation. */
167
196
  export interface NegotiatedVisitorContract<C extends readonly VisitorCapability[]> {
168
197
  readonly apiVersion: 1;
169
198
  readonly capabilities: C;
170
199
  }
200
+ /** Native host adapter for a virtual-TypeScript-only visitor plugin. */
171
201
  export interface VirtualTsVisitorHostPlugin {
172
202
  readonly name: string;
173
203
  readonly version: string;
@@ -175,6 +205,7 @@ export interface VirtualTsVisitorHostPlugin {
175
205
  /** Host-only serialized boundary consumed by `typeCheckWithVirtualTsVisitors`. */
176
206
  readonly run: (eventJson: string) => string;
177
207
  }
208
+ /** Devtools host adapter for a trace-only visitor plugin. */
178
209
  export interface DevtoolsTraceVisitorHostPlugin {
179
210
  readonly name: string;
180
211
  readonly version: string;