vite-devtools-svelte 0.3.0 → 0.4.0

package/dist/collector.d.ts

@@ -0,0 +1,284 @@
+import { CaptureInfoMap, CompilerWarning, ComponentInstance, FpsSample, LoadProfile, ReactiveGraph, ReactiveGraphRequest, ReactiveGraphResult, ReactiveSummary, ReactiveSummaryRequest, RenderProfile, RuntimeError, StateChange, StateTimelineDelta, StateTimelineEntry, DatasetVersions } from './types.js';
+export declare const LIMITS: {
+    readonly liveComponents: 50000;
+    readonly renderProfiles: 5000;
+    readonly stateTimeline: 500;
+    readonly reactiveNodes: 5000;
+    readonly reactiveEdges: 20000;
+    readonly fpsSamples: 1200;
+    readonly runtimeErrors: 200;
+    readonly loadProfiles: 200;
+    readonly compilerWarnings: 500;
+};
+/** How long a pull request to the browser runtime may take before we answer from cache. */
+export declare const RUNTIME_REQUEST_TIMEOUT = 1000;
+/** A pull answered within this window is reused instead of asking the runtime again. */
+export declare const PULL_FRESHNESS = 1000;
+/** Byte budget (JSON length, measured once at ingest) for the server-side state timeline. */
+export declare const STATE_TIMELINE_BYTES: number;
+export type DatasetKey = keyof DatasetVersions;
+/** App page loads (tabs / reloads) whose component tree + profiles are kept, LRU. */
+export declare const MAX_EPOCHS = 4;
+/** Hot-channel event names shared with `runtime.ts` (stable contract, see docs/devframe-migration.md §6). */
+export declare const HOT_EVENTS: {
+    readonly components: "svelte-devtools:components";
+    readonly profiles: "svelte-devtools:profiles";
+    readonly stateTimeline: "svelte-devtools:state-timeline";
+    readonly fps: "svelte-devtools:fps";
+    readonly runtimeError: "svelte-devtools:runtime-error";
+    readonly reactiveGraph: "svelte-devtools:reactive-graph";
+    readonly requestReactiveGraph: "svelte-devtools:request-reactive-graph";
+    /** server → runtime `{ requestId, epoch?, topK, windowMs }`; reply `reactiveSummary` (§6.7 I). */
+    readonly requestReactiveSummary: "svelte-devtools:request-reactive-summary";
+    readonly reactiveSummary: "svelte-devtools:reactive-summary";
+    readonly requestStateTimeline: "svelte-devtools:request-state-timeline";
+    readonly clearStateTimeline: "svelte-devtools:clear-state-timeline";
+    /** runtime → server, once per page load: "send me the current subscription state". */
+    readonly runtimeReady: "svelte-devtools:runtime-ready";
+    /** server → runtime(s): `{ active: boolean }` — whether any consumer is watching. */
+    readonly subscription: "svelte-devtools:subscription";
+};
+/** Defaults and bounds for `get-reactive-summary` (§6.7 I). */
+export declare const SUMMARY_DEFAULTS: {
+    readonly topK: 50;
+    readonly maxTopK: 200;
+    readonly windowMs: 10000;
+    readonly minWindowMs: 1000;
+    readonly maxWindowMs: 60000;
+};
+/** A consumer (DevTools UI tab, MCP agent) counts as watching until its lease expires. */
+export declare const LEASE_TTL = 15000;
+export interface HotClient {
+    send(event: string, payload: unknown): void;
+}
+export interface HotChannel {
+    send(event: string, payload: unknown): void;
+    on(event: string, listener: (payload: any, client: HotClient) => void): void;
+    off?(event: string, listener: (payload: any, client: HotClient) => void): void;
+}
+export interface CollectorHooks {
+    onFpsSample?: (sample: FpsSample) => void;
+    onLoadProfile?: (profile: LoadProfile) => void;
+}
+/**
+ * Host-side store for everything the browser runtime and the instrumentation
+ * transforms report. Independent of Vite and of devframe: the Vite plugin
+ * feeds it, the devframe RPC layer and the MCP server read from it.
+ */
+export declare class Collector {
+    private readonly hooks;
+    private epochs;
+    private servedEpoch;
+    private liveCache;
+    loadProfiles: LoadProfile[];
+    reactiveGraph: ReactiveGraph;
+    compilerWarnings: CompilerWarning[];
+    runtimeErrors: RuntimeError[];
+    fpsSamples: FpsSample[];
+    readonly versions: DatasetVersions;
+    private bump;
+    private timeline;
+    /** Parallel to `timeline`: JSON size and source epoch (app page load) of each entry. */
+    private timelineSizes;
+    private timelineEpochs;
+    private timelineBytes;
+    /** Newest seq issued by this collector (= the current cursor). */
+    private timelineSeq;
+    /** Cursor value at the last removal; older cursors must start over. */
+    private timelineResetAt;
+    /** Seq of the newest entry trimmed by the caps; cursors below it missed entries. */
+    private timelineTrimmedAt;
+    private lastPull;
+    private inflight;
+    private pulls;
+    private pullCache;
+    private pullInflight;
+    private requestSeq;
+    /** The most recent graph reply, for capture info. */
+    private lastGraph;
+    private timelineDrops;
+    /** Per epoch: whether the runtime has a first sample of every tracked $state yet. */
+    private timelineBaseline;
+    private timelineTooLarge;
+    private received;
+    private hot;
+    private detachHot;
+    private leases;
+    private snapshotWaiters;
+    private active;
+    private sweepTimer;
+    private stateTimelineResolvers;
+    constructor(hooks?: CollectorHooks);
+    /**
+     * Subscribe to the runtime's hot-channel events. Re-attaching (dev server
+     * restart) detaches the previous channel first so listeners never pile up.
+     */
+    attach(hot: HotChannel): void;
+    detach(): void;
+    /** What the runtime is told: collect/poll only while somebody is watching. */
+    get subscription(): {
+        active: boolean;
+        componentDeltas: true;
+    };
+    /** Epochs we asked for a full snapshot (delta without a base); answered once per epoch. */
+    private resyncRequested;
+    /** Components of the served epoch, parents first, capped at {@link LIMITS.liveComponents}. */
+    get liveComponents(): ComponentInstance[];
+    /**
+     * The served epoch's components with that epoch, read together, so a
+     * component id is never paired with another page load's epoch (several app
+     * tabs keep separate trees; nothing is merged).
+     */
+    get liveSnapshot(): {
+        epoch: string | null;
+        total: number;
+        components: ComponentInstance[];
+    };
+    /** Instances the served epoch has mounted, including those beyond the cap. */
+    get liveComponentsTotal(): number;
+    get renderProfiles(): RenderProfile[];
+    /** The epoch currently served and how many app page loads are tracked. */
+    get epochInfo(): {
+        epoch: string | undefined;
+        epochs: number;
+    };
+    private servedState;
+    /**
+     * Get (creating, LRU-bounded) the state for `epoch` and mark it as the most
+     * recent pusher. It becomes the served epoch only once it holds a full
+     * component snapshot — an epoch known only from profiles/timeline would
+     * otherwise show an empty tree (review B1).
+     */
+    private touchEpoch;
+    private newestBasedEpoch;
+    private serve;
+    /**
+     * Mark `id` as watching for `ttl` ms (renewed by heartbeats). The first
+     * lease activates the runtime's polling/FPS sampling, the last expiry or
+     * release pauses it.
+     */
+    lease(id: string, ttl?: number): boolean;
+    /**
+     * Resolve once the runtime has sent its activation snapshot (components,
+     * profiles, then a `reset: true` timeline — the last part) or after
+     * `timeout`, so a consumer that just activated the runtime doesn't read
+     * the stale pre-activation state.
+     */
+    waitForSnapshot(timeout: number): Promise<void>;
+    release(id: string): void;
+    private updateSubscription;
+    /**
+     * Full form `{ epoch?, reset?, components }` replaces the epoch's tree;
+     * delta form `{ epoch, added, removed }` (ids) patches it (§6.5). A delta
+     * for an epoch we hold no full snapshot of (new to us, or evicted) is not
+     * applied — a partial tree would persist — and the sender is asked to
+     * resync. Entries stay in registration order (parents first); an instance
+     * is stored only while its parent is and the cap allows, otherwise only its
+     * id is tracked, so the stored part is always a rooted, orphan-free tree.
+     */
+    ingestComponents(data: {
+        components?: unknown;
+        epoch?: unknown;
+        added?: unknown;
+        removed?: unknown;
+    } | undefined, client?: HotClient): void;
+    ingestProfiles(data: {
+        profiles?: unknown;
+        epoch?: unknown;
+        total?: unknown;
+    } | undefined): void;
+    /**
+     * What the server holds versus what was reported, per dataset (§6.7 B).
+     * `total: null` means unknown; nothing is estimated.
+     */
+    getCaptureInfo(): CaptureInfoMap;
+    /** The server-side timeline (all tracked epochs, oldest first). */
+    get stateTimeline(): StateTimelineEntry[];
+    /**
+     * Two payload shapes (docs/devframe-migration.md §6.4):
+     * - delta: `{ epoch, changes, reset? }` — `changes` are new since the
+     *   previous push from that page load (`epoch`); `reset` replaces that
+     *   epoch's entries. Entries are kept per epoch, so several app tabs (or a
+     *   reload) interleave instead of wiping each other.
+     * - legacy full snapshot: `{ changes }` — we append only the entries after
+     *   the newest one we already hold, so clients still get deltas.
+     */
+    ingestStateTimeline(data: {
+        changes?: unknown;
+        epoch?: unknown;
+        reset?: unknown;
+        dropped?: unknown;
+        valueTooLarge?: unknown;
+        baseline?: unknown;
+    } | undefined): void;
+    /**
+     * Add the runtime's own losses (unsent entries it evicted, §6.7 C) and
+     * too-large values to the epoch's counters. Only runtime reasons are
+     * accepted from the runtime; server reasons are counted here.
+     */
+    private countRuntimeLosses;
+    private addDrop;
+    /** Changes after `since` (a previous `cursor`), or the whole buffer when the cursor is stale. */
+    getStateTimelineDelta(since?: number): StateTimelineDelta;
+    /** Invalidate every cursor issued so far (entries were removed, not just appended). */
+    private markTimelineReset;
+    private dropEpoch;
+    private appendTimeline;
+    private resolveSnapshotWaiters;
+    /**
+     * A graph reply. With a `requestId` (§6.7 A) it resolves only that request,
+     * and only if its epoch matches the one asked for; a reply nobody waits for
+     * (another app tab, too late) is ignored. Without one (an older runtime) it
+     * is a whole-app graph and answers every pending graph pull, scoped ones by
+     * filtering here.
+     */
+    ingestReactiveGraph(data: Record<string, any> | undefined): void;
+    /**
+     * Shape a runtime reply into a {@link ReactiveGraphResult}: apply the
+     * collector caps (nodes, then only edges between kept nodes, then the edge
+     * cap) and report what was left out. Totals come from the runtime; an older
+     * runtime's are the counts it sent (`nodesKind: 'sent'`), or unknown when
+     * the server had to scope its whole-app graph.
+     */
+    private normalizeGraph;
+    private storeGraph;
+    /** A summary reply (§6.7 I): resolves only the matching request. */
+    ingestReactiveSummary(data: Record<string, any> | undefined): void;
+    private normalizeSummary;
+    ingestFps(sample: FpsSample): void;
+    ingestRuntimeError(error: RuntimeError): void;
+    recordLoadProfile(profile: LoadProfile): void;
+    recordCompilerWarning(warning: CompilerWarning): void;
+    clearLoadProfiles(): void;
+    clearErrors(): void;
+    clearFps(): void;
+    clearStateTimeline(): void;
+    /**
+     * Ask the browser runtime for the graph of one component instance (or the
+     * whole app), built by the runtime within the caps (§6.7 A). Falls back to
+     * the last result for the same scope, marked `stale`.
+     */
+    requestReactiveGraph(req?: ReactiveGraphRequest): Promise<ReactiveGraphResult>;
+    /** Ask the runtime for the overview aggregate (§6.7 I); never captures the graph. */
+    requestReactiveSummary(req?: ReactiveSummaryRequest): Promise<ReactiveSummary>;
+    /**
+     * One pull per key at a time; a result younger than {@link PULL_FRESHNESS}
+     * is reused. The request carries a requestId and the served epoch; only
+     * the matching reply resolves it. On timeout (or without a runtime) the
+     * last result for the same key is returned with `stale: true`.
+     */
+    private keyedPull;
+    /** Resolve a pending pull with a fresh result and cache it under its key. */
+    private settle;
+    /** Answer every pending keyed pull from its cache (or empty), marked stale. */
+    private flushPulls;
+    /** Ask the browser runtime for a fresh state timeline; falls back to the last one. */
+    requestStateTimeline(): Promise<StateChange[]>;
+    /**
+     * Concurrent callers share one in-flight pull, and a result younger than
+     * {@link PULL_FRESHNESS} is reused, so several polling clients never make
+     * the user's app rebuild the same data more than once a second.
+     */
+    private pull;
+    private flushStateTimeline;
+}

package/dist/devframe.d.ts

@@ -0,0 +1,90 @@
+import { DevframeDefinition } from 'devframe';
+import { z } from 'zod';
+import { GraphModuleLike } from './analyzers/module-graph.js';
+import { Collector } from './collector.js';
+import { ApiResponse, InspectResult, OGPreview, ReactiveGraphResult, ReactiveSummary, StateTimelineDelta, LiveComponentsMeta } from './types.js';
+export declare const DEVFRAME_ID = "svelte-devtools";
+/** Mount base for both hosts (standalone and Vite DevTools), so the SPA URL never changes. */
+export declare const DEVFRAME_BASE = "/.svelte-devtools/";
+/**
+ * Everything the portable devframe needs from whatever hosts it. The Vite
+ * plugin implements this over its dev server; tests implement it directly.
+ * Getters are lazy because the host resolves config after construction.
+ */
+export interface SvelteDevtoolsHost {
+    collector: Collector;
+    /** Absolute project root. */
+    root: () => string;
+    /** Public base the dev server serves the app (and static files) under. */
+    publicBase: () => string;
+    /** Every module the dev server currently knows about, across environments. */
+    modules: () => GraphModuleLike[];
+    /** Compile a project file through the dev server's pipeline (absent without a server). */
+    transformRequest?: (file: string) => Promise<{
+        code: string;
+        map?: {
+            mappings?: string;
+            sources?: string[];
+        } | string | null;
+    } | null>;
+    /** Origins the dev server itself is reachable at (API playground / OG preview may call them). */
+    serverOrigins: () => string[];
+    /** Open `file[:line]` in the user's editor. */
+    openInEditor: (target: string) => void;
+}
+export declare function createRpcFunctions(host: SvelteDevtoolsHost): readonly [import('devframe/rpc').RpcFunctionDefinitionWithoutSchemas<"get-project", "query", [], import('./types.js').ProjectInfo, undefined, undefined, import('devframe').DevframeNodeContext>, import('devframe/rpc').RpcFunctionDefinitionWithoutSchemas<"get-routes", "query", [], import('./types.js').RouteInfo[], undefined, undefined, import('devframe').DevframeNodeContext>, import('devframe/rpc').RpcFunctionDefinitionWithoutSchemas<"get-assets", "query", [], import('./types.js').AssetInfo[], undefined, undefined, import('devframe').DevframeNodeContext>, import('devframe/rpc').RpcFunctionDefinitionWithoutSchemas<"get-component-relations", "query", [], import('./types.js').ComponentRelation[], undefined, undefined, import('devframe').DevframeNodeContext>, import('devframe/rpc').RpcFunctionDefinitionWithoutSchemas<"get-svelte-files", "query", [], {
+    file: string;
+    name: string;
+}[], undefined, undefined, import('devframe').DevframeNodeContext>, import('devframe/rpc').RpcFunctionDefinitionWithoutSchemas<"get-live-components", "query", [], import('./types.js').ComponentInstance[], undefined, undefined, import('devframe').DevframeNodeContext>, import('devframe/rpc').RpcFunctionDefinitionWithoutSchemas<"get-live-components-meta", "query", [], LiveComponentsMeta, undefined, undefined, import('devframe').DevframeNodeContext>, import('devframe/rpc').RpcFunctionDefinitionWithSchemas<"set-active", "action", readonly [z.ZodObject<{
+    client: z.ZodString;
+    active: z.ZodBoolean;
+}, z.core.$strip>], z.ZodVoid, import('devframe').DevframeNodeContext>, import('devframe/rpc').RpcFunctionDefinitionWithSchemas<"open-in-editor", "action", readonly [z.ZodObject<{
+    file: z.ZodString;
+    line: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>], z.ZodVoid, import('devframe').DevframeNodeContext>, import('devframe/rpc').RpcFunctionDefinitionWithSchemas<"open-reactive-in-editor", "action", readonly [z.ZodObject<{
+    file: z.ZodString;
+    name: z.ZodString;
+    type: z.ZodString;
+}, z.core.$strip>], z.ZodVoid, import('devframe').DevframeNodeContext>, import('devframe/rpc').RpcFunctionDefinitionWithoutSchemas<"get-render-profiles", "query", [], import('./types.js').RenderProfile[], undefined, undefined, import('devframe').DevframeNodeContext>, import('devframe/rpc').RpcFunctionDefinitionWithSchemas<"get-reactive-graph", "query", readonly [z.ZodOptional<z.ZodObject<{
+    componentId: z.ZodOptional<z.ZodNumber>;
+    epoch: z.ZodOptional<z.ZodString>;
+    maxNodes: z.ZodOptional<z.ZodNumber>;
+    maxEdges: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>>], z.ZodCustom<ReactiveGraphResult, ReactiveGraphResult>, import('devframe').DevframeNodeContext>, import('devframe/rpc').RpcFunctionDefinitionWithSchemas<"get-reactive-summary", "query", readonly [z.ZodOptional<z.ZodObject<{
+    topK: z.ZodOptional<z.ZodNumber>;
+    windowMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>>], z.ZodCustom<ReactiveSummary, ReactiveSummary>, import('devframe').DevframeNodeContext>, import('devframe/rpc').RpcFunctionDefinitionWithoutSchemas<"get-capture-info", "query", [], Partial<Record<import('./types.js').CaptureKey, import('./types.js').CaptureInfo>>, undefined, undefined, import('devframe').DevframeNodeContext>, import('devframe/rpc').RpcFunctionDefinitionWithoutSchemas<"get-load-profiles", "query", [], import('./types.js').LoadProfile[], undefined, undefined, import('devframe').DevframeNodeContext>, import('devframe/rpc').RpcFunctionDefinitionWithoutSchemas<"clear-load-profiles", "action", [], void, undefined, undefined, import('devframe').DevframeNodeContext>, import('devframe/rpc').RpcFunctionDefinitionWithoutSchemas<"get-state-timeline", "query", [], Promise<import('./types.js').StateChange[]>, undefined, undefined, import('devframe').DevframeNodeContext>, import('devframe/rpc').RpcFunctionDefinitionWithSchemas<"get-state-timeline-delta", "query", readonly [z.ZodObject<{
+    since: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>], z.ZodCustom<StateTimelineDelta, StateTimelineDelta>, import('devframe').DevframeNodeContext>, import('devframe/rpc').RpcFunctionDefinitionWithoutSchemas<"get-versions", "query", [], {
+    components: number;
+    renderProfiles: number;
+    loadProfiles: number;
+    stateTimeline: number;
+    reactiveGraph: number;
+    errors: number;
+    fps: number;
+}, undefined, undefined, import('devframe').DevframeNodeContext>, import('devframe/rpc').RpcFunctionDefinitionWithoutSchemas<"clear-state-timeline", "action", [], void, undefined, undefined, import('devframe').DevframeNodeContext>, import('devframe/rpc').RpcFunctionDefinitionWithoutSchemas<"get-api-endpoints", "query", [], import('./types.js').ApiEndpoint[], undefined, undefined, import('devframe').DevframeNodeContext>, import('devframe/rpc').RpcFunctionDefinitionWithSchemas<"send-api-request", "action", readonly [z.ZodObject<{
+    url: z.ZodString;
+    method: z.ZodEnum<{
+        GET: "GET";
+        POST: "POST";
+        PUT: "PUT";
+        PATCH: "PATCH";
+        DELETE: "DELETE";
+        HEAD: "HEAD";
+        OPTIONS: "OPTIONS";
+    }>;
+    headers: z.ZodString;
+    body: z.ZodString;
+}, z.core.$strip>], z.ZodCustom<ApiResponse, ApiResponse>, import('devframe').DevframeNodeContext>, import('devframe/rpc').RpcFunctionDefinitionWithoutSchemas<"get-compiler-warnings", "query", [], import('./types.js').CompilerWarning[], undefined, undefined, import('devframe').DevframeNodeContext>, import('devframe/rpc').RpcFunctionDefinitionWithoutSchemas<"get-runtime-errors", "query", [], import('./types.js').RuntimeError[], undefined, undefined, import('devframe').DevframeNodeContext>, import('devframe/rpc').RpcFunctionDefinitionWithoutSchemas<"clear-errors", "action", [], void, undefined, undefined, import('devframe').DevframeNodeContext>, import('devframe/rpc').RpcFunctionDefinitionWithSchemas<"inspect-file", "query", readonly [z.ZodObject<{
+    file: z.ZodString;
+}, z.core.$strip>], z.ZodCustom<InspectResult, InspectResult>, import('devframe').DevframeNodeContext>, import('devframe/rpc').RpcFunctionDefinitionWithoutSchemas<"get-module-graph", "query", [], import('./types.js').ModuleGraphData, undefined, undefined, import('devframe').DevframeNodeContext>, import('devframe/rpc').RpcFunctionDefinitionWithSchemas<"get-og-preview", "action", readonly [z.ZodObject<{
+    url: z.ZodString;
+}, z.core.$strip>], z.ZodCustom<OGPreview, OGPreview>, import('devframe').DevframeNodeContext>, import('devframe/rpc').RpcFunctionDefinitionWithoutSchemas<"get-build-analysis", "query", [], import('./types.js').BuildAnalysis, undefined, undefined, import('devframe').DevframeNodeContext>, import('devframe/rpc').RpcFunctionDefinitionWithoutSchemas<"get-fps", "query", [], import('./types.js').FpsSample[], undefined, undefined, import('devframe').DevframeNodeContext>, import('devframe/rpc').RpcFunctionDefinitionWithoutSchemas<"clear-fps", "action", [], void, undefined, undefined, import('devframe').DevframeNodeContext>];
+/**
+ * The portable Svelte DevTools tool. Host-agnostic: the same definition is
+ * mounted standalone (`initDevframe`) or inside Vite DevTools
+ * (`createPluginFromDevframe`); the SPA in `dist/client` connects with
+ * `connectDevframe()` either way.
+ */
+export declare function createSvelteDevframe(host: SvelteDevtoolsHost): DevframeDefinition;