@oddsquad/vite-plugin-lit 0.2.3 → 0.4.0

package/lib/devframe/icon.js

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+// The official Lit logo mark (Iconify `logos:lit-icon`). Its native viewBox is
+// 256×320 — taller than wide — so when the DevTools dock sizes an icon to its
+// width it overflowed the square slot and looked bigger than the other icons.
+// We pad it to a square viewBox (-32 0 320 320, centering the 256-wide art) so
+// it renders at the same box size as the built-in phosphor icons. Inlined as a
+// data: URI rather than `logos:lit-icon` so it also works offline (no Iconify
+// API fetch).
+const LIT_LOGO_SVG =
+  '<svg xmlns="http://www.w3.org/2000/svg" viewBox="-32 0 320 320">' +
+  '<path fill="#00e8ff" d="m64 192l25.926-44.727l38.233-19.114l63.974 63.974l10.833 61.754L192 320l-64-64l-38.074-25.615z"/>' +
+  '<path fill="#283198" d="M128 256V128l64-64v128zM0 256l64 64l9.202-60.602L64 192l-37.542 23.71z"/>' +
+  '<path fill="#324fff" d="M64 192V64l64-64v128zm128 128V192l64-64v128zM0 256V128l64 64z"/>' +
+  '<path fill="#0ff" d="M64 320V192l64 64z"/></svg>';
+/** Dock icon for the Lit devframe. */
+export const LIT_LOGO_ICON = `data:image/svg+xml,${encodeURIComponent(LIT_LOGO_SVG)}`;
+//# sourceMappingURL=icon.js.map

package/lib/devframe/icon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"icon.js","sourceRoot":"","sources":["../../src/lib/devframe/icon.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,+EAA+E;AAC/E,8EAA8E;AAC9E,8EAA8E;AAC9E,+EAA+E;AAC/E,+EAA+E;AAC/E,8EAA8E;AAC9E,cAAc;AACd,MAAM,YAAY,GAChB,kEAAkE;IAClE,2HAA2H;IAC3H,mGAAmG;IACnG,0FAA0F;IAC1F,kDAAkD,CAAC;AAErD,sCAAsC;AACtC,MAAM,CAAC,MAAM,aAAa,GAAG,sBAAsB,kBAAkB,CACnE,YAAY,CACb,EAAE,CAAC","sourcesContent":["/**\n * @license\n * Copyright 2026 Google LLC\n * SPDX-License-Identifier: BSD-3-Clause\n */\n\n// The official Lit logo mark (Iconify `logos:lit-icon`). Its native viewBox is\n// 256×320 — taller than wide — so when the DevTools dock sizes an icon to its\n// width it overflowed the square slot and looked bigger than the other icons.\n// We pad it to a square viewBox (-32 0 320 320, centering the 256-wide art) so\n// it renders at the same box size as the built-in phosphor icons. Inlined as a\n// data: URI rather than `logos:lit-icon` so it also works offline (no Iconify\n// API fetch).\nconst LIT_LOGO_SVG =\n  '<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"-32 0 320 320\">' +\n  '<path fill=\"#00e8ff\" d=\"m64 192l25.926-44.727l38.233-19.114l63.974 63.974l10.833 61.754L192 320l-64-64l-38.074-25.615z\"/>' +\n  '<path fill=\"#283198\" d=\"M128 256V128l64-64v128zM0 256l64 64l9.202-60.602L64 192l-37.542 23.71z\"/>' +\n  '<path fill=\"#324fff\" d=\"M64 192V64l64-64v128zm128 128V192l64-64v128zM0 256V128l64 64z\"/>' +\n  '<path fill=\"#0ff\" d=\"M64 320V192l64 64z\"/></svg>';\n\n/** Dock icon for the Lit devframe. */\nexport const LIT_LOGO_ICON = `data:image/svg+xml,${encodeURIComponent(\n  LIT_LOGO_SVG\n)}`;\n"]}

package/lib/devframe/paths.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+/** Absolute path of this package's root directory. */
+export declare const PACKAGE_ROOT: string;
+/** This package's version, as published. Surfaced by the `get-meta` query. */
+export declare const PACKAGE_VERSION: string;
+/** Where `vp run build:panel` writes the panel SPA the host serves. */
+export declare const PANEL_DIST_DIR: string;
+//# sourceMappingURL=paths.d.ts.map

package/lib/devframe/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/lib/devframe/paths.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA6BH,sDAAsD;AACtD,eAAO,MAAM,YAAY,EAAE,MAA0B,CAAC;AAEtD,8EAA8E;AAC9E,eAAO,MAAM,eAAe,EAAE,MAKR,CAAC;AAEvB,uEAAuE;AACvE,eAAO,MAAM,cAAc,EAAE,MAA6C,CAAC"}

package/lib/devframe/paths.js

@@ -0,0 +1,38 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+/**
+ * Package-root resolution for the devframe.
+ *
+ * `tsc` flattens `src/lib/devframe/*.ts` to `lib/devframe/*.js`, so a path
+ * relative to `import.meta.url` lands one directory apart depending on
+ * whether the module was loaded from source (tests, `vite dev` on this repo)
+ * or from the published output. Walking up to the nearest `package.json`
+ * instead is correct in both layouts — the same reason
+ * `resolveRuntimeModule()` in plugin.ts probes for both extensions.
+ */
+import {existsSync, readFileSync} from 'node:fs';
+import {dirname, join} from 'node:path';
+import {fileURLToPath} from 'node:url';
+const findPackageRoot = () => {
+  let dir = dirname(fileURLToPath(import.meta.url));
+  // 6 levels is more than either layout needs; the loop exits at the root.
+  for (let depth = 0; depth < 6; depth++) {
+    if (existsSync(join(dir, 'package.json'))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error('[lit-plugin] could not locate the package root');
+};
+/** Absolute path of this package's root directory. */
+export const PACKAGE_ROOT = findPackageRoot();
+/** This package's version, as published. Surfaced by the `get-meta` query. */
+export const PACKAGE_VERSION =
+  JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8'))
+    .version ?? '0.0.0';
+/** Where `vp run build:panel` writes the panel SPA the host serves. */
+export const PANEL_DIST_DIR = join(PACKAGE_ROOT, 'dist', 'client');
+//# sourceMappingURL=paths.js.map

package/lib/devframe/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/lib/devframe/paths.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;GASG;AAEH,OAAO,EAAC,UAAU,EAAE,YAAY,EAAC,MAAM,SAAS,CAAC;AACjD,OAAO,EAAC,OAAO,EAAE,IAAI,EAAC,MAAM,WAAW,CAAC;AACxC,OAAO,EAAC,aAAa,EAAC,MAAM,UAAU,CAAC;AAEvC,MAAM,eAAe,GAAG,GAAW,EAAE;IACnC,IAAI,GAAG,GAAG,OAAO,CAAC,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAClD,yEAAyE;IACzE,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC;QACvC,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;YAAE,OAAO,GAAG,CAAC;QACtD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,MAAM,KAAK,GAAG;YAAE,MAAM;QAC1B,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;AACpE,CAAC,CAAC;AAEF,sDAAsD;AACtD,MAAM,CAAC,MAAM,YAAY,GAAW,eAAe,EAAE,CAAC;AAEtD,8EAA8E;AAC9E,MAAM,CAAC,MAAM,eAAe,GAExB,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,YAAY,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAGpE,CAAC,OAAO,IAAI,OAAO,CAAC;AAEvB,uEAAuE;AACvE,MAAM,CAAC,MAAM,cAAc,GAAW,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC","sourcesContent":["/**\n * @license\n * Copyright 2026 Google LLC\n * SPDX-License-Identifier: BSD-3-Clause\n */\n\n/**\n * Package-root resolution for the devframe.\n *\n * `tsc` flattens `src/lib/devframe/*.ts` to `lib/devframe/*.js`, so a path\n * relative to `import.meta.url` lands one directory apart depending on\n * whether the module was loaded from source (tests, `vite dev` on this repo)\n * or from the published output. Walking up to the nearest `package.json`\n * instead is correct in both layouts — the same reason\n * `resolveRuntimeModule()` in plugin.ts probes for both extensions.\n */\n\nimport {existsSync, readFileSync} from 'node:fs';\nimport {dirname, join} from 'node:path';\nimport {fileURLToPath} from 'node:url';\n\nconst findPackageRoot = (): string => {\n  let dir = dirname(fileURLToPath(import.meta.url));\n  // 6 levels is more than either layout needs; the loop exits at the root.\n  for (let depth = 0; depth < 6; depth++) {\n    if (existsSync(join(dir, 'package.json'))) return dir;\n    const parent = dirname(dir);\n    if (parent === dir) break;\n    dir = parent;\n  }\n  throw new Error('[lit-plugin] could not locate the package root');\n};\n\n/** Absolute path of this package's root directory. */\nexport const PACKAGE_ROOT: string = findPackageRoot();\n\n/** This package's version, as published. Surfaced by the `get-meta` query. */\nexport const PACKAGE_VERSION: string =\n  (\n    JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8')) as {\n      version?: string;\n    }\n  ).version ?? '0.0.0';\n\n/** Where `vp run build:panel` writes the panel SPA the host serves. */\nexport const PANEL_DIST_DIR: string = join(PACKAGE_ROOT, 'dist', 'client');\n"]}

package/lib/devframe/protocol.d.ts

@@ -0,0 +1,218 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+import type { FeatureSettings, SettingsOverride, TimelineEvent, TimelineLayer, TimelineLayersState } from '../../types/timeline.js';
+import type { InspectorCommand, InspectorDetails, InspectorMessage, InspectorTreeNode } from '../../types/inspector.js';
+import type { HmrIncompatibilityEvent } from '../../types/hmr-incompatibility.js';
+import type { ComponentRollup, UpdateCycle } from '../timeline/derive.js';
+/** The devframe's scope id. RPC names become `lit:*`, MCP wire names `lit_*`. */
+export declare const LIT_DEVFRAME_ID = "lit";
+/** Shared-state key holding the {@link SessionState} snapshot. */
+export declare const SESSION_STATE_KEY = "session";
+/** Streaming channel name the timeline event batches are pushed on. */
+export declare const TIMELINE_STREAM_NAME = "timeline";
+/**
+ * Id of the one long-lived timeline stream. Fixed rather than discovered:
+ * there is exactly one page feed per dev session, so the panel can subscribe
+ * without a round trip to look the id up. The node side re-`start()`s this id
+ * if the transport dropped the stream after the last subscriber left.
+ */
+export declare const TIMELINE_STREAM_ID = "live";
+/**
+ * Cap on the node-side recent-events ring buffer, matching the timeline
+ * stream's own `replayWindow` so an agent and a (re)connecting panel see
+ * comparable history.
+ */
+export declare const RECENT_EVENTS_BUFFER_SIZE = 512;
+/** Bare (unscoped) name of the `get-meta` query. */
+export declare const RPC_GET_META = "get-meta";
+/** Bare name of the `list-components` query. */
+export declare const RPC_LIST_COMPONENTS = "list-components";
+/** Bare name of the `component-details` query. */
+export declare const RPC_COMPONENT_DETAILS = "component-details";
+/** Bare name of the `recent-events` query. */
+export declare const RPC_RECENT_EVENTS = "recent-events";
+/** Bare name of the `update-summary` query. */
+export declare const RPC_UPDATE_SUMMARY = "update-summary";
+/** Bare name of the `inspect` action. */
+export declare const RPC_INSPECT = "inspect";
+/** Bare name of the `set-recording` action. */
+export declare const RPC_SET_RECORDING = "set-recording";
+/** Bare name of the `toggle-layer` action. */
+export declare const RPC_TOGGLE_LAYER = "toggle-layer";
+/** Bare name of the `set-settings-override` action. */
+export declare const RPC_SET_SETTINGS_OVERRIDE = "set-settings-override";
+/** Bare name of the `open-source` action. */
+export declare const RPC_OPEN_SOURCE = "open-source";
+/** Arguments for {@link RPC_OPEN_SOURCE}. */
+export interface OpenSourceArgs {
+    /**
+     * The path as the panel has it: what the transform injected, so relative
+     * to the Vite root (or absolute, when the file lives outside it).
+     */
+    file: string;
+    line?: number;
+}
+/** What {@link RPC_OPEN_SOURCE} reports back. */
+export interface OpenSourceResult {
+    /**
+     * False when no open service is installed on the host, which is the
+     * panel's cue to fall back to `/__lit-open-in-editor`.
+     */
+    opened: boolean;
+}
+/** Freeze the current session into a static panel directory. */
+export declare const RPC_EXPORT_SNAPSHOT = "export-snapshot";
+/** Arguments for {@link RPC_EXPORT_SNAPSHOT}. */
+export interface ExportSnapshotArgs {
+    /**
+     * Where to write. Relative paths resolve against the dev server's cwd.
+     * Defaults to `lit-devtools-snapshot`.
+     */
+    outDir?: string;
+}
+/** What {@link RPC_EXPORT_SNAPSHOT} reports back, for the panel to display. */
+export interface ExportSnapshotResult {
+    outDir: string;
+    events: number;
+    components: number;
+    details: number;
+}
+/** Bare name of the `inspector-message` client (node → panel) event. */
+export declare const RPC_INSPECTOR_MESSAGE = "inspector-message";
+/** Bare name of the `hmr-incompatibilities` query. */
+export declare const RPC_HMR_INCOMPATIBILITIES = "hmr-incompatibilities";
+/** Bare name of the `hmr-incompatible` client (node → panel) event. */
+export declare const RPC_HMR_INCOMPATIBLE = "hmr-incompatible";
+/**
+ * Recording/layers snapshot shared between every surface (panel, page
+ * runtime, MCP). Survives reconnect; mutated either by the `set-recording` /
+ * `toggle-layer` actions below or directly by a panel through the generic
+ * shared-state RPC devframe provides.
+ *
+ * `layers.recordingState` is the single authority for "is recording" — the
+ * runtime's own layer state carries it, so a separate flag here would be a
+ * second copy to keep in sync.
+ */
+export interface SessionState {
+    layers: TimelineLayersState;
+    /** Layers announced at runtime by app code through `addTimelineLayer()`. */
+    customLayers: TimelineLayer[];
+}
+export declare const DEFAULT_SESSION_STATE: SessionState;
+/** Result of the `get-meta` query. */
+export interface LitGetMetaResult {
+    version: string;
+    /** Built-in layers followed by any runtime-announced custom ones. */
+    layers: TimelineLayer[];
+    features: FeatureSettings | null;
+    /** Channel and id to pass to `rpc.streaming.subscribe()`. */
+    stream: {
+        channel: string;
+        id: string;
+    };
+}
+/** Argument of the `component-details` query. */
+export interface ComponentDetailsArgs {
+    id: number;
+}
+/** Argument of the `recent-events` query. */
+export interface RecentEventsArgs {
+    layerId?: string;
+    elementId?: number;
+    /**
+     * Only events from the last `sinceMs` milliseconds, measured against
+     * the newest event currently in the buffer — not wall-clock time.
+     * `TimelineEvent.time` is "ms since recording started" in the page
+     * (see `runtime/timeline/clock.ts`), which has no fixed relationship
+     * to this process's clock.
+     */
+    sinceMs?: number;
+    /** Default 50, hard ceiling 200 regardless of what's requested. */
+    limit?: number;
+}
+/** Result of the `recent-events` query. */
+export interface RecentEventsResult {
+    /** Whether the timeline is currently recording. */
+    recording: boolean;
+    /** Most recent events matching the filters, oldest first. */
+    events: TimelineEvent[];
+    /** Total events currently held in the ring buffer, before filtering. */
+    bufferSize: number;
+    /** True if filtering matched more events than were returned. */
+    truncated: boolean;
+}
+/** Argument of the `update-summary` query. */
+export interface UpdateSummaryArgs {
+    /** Restrict to one component, by tag name. */
+    tagName?: string;
+    /** Same window semantics as {@link RecentEventsArgs.sinceMs}. */
+    sinceMs?: number;
+    /** Cycles returned (the component totals always cover the whole window).
+     *  Default 50, hard ceiling 200. */
+    limit?: number;
+}
+/** Result of the `update-summary` query. */
+export interface UpdateSummaryResult {
+    /** Whether the timeline is currently recording. */
+    recording: boolean;
+    /** Per-component totals over the window, slowest first. */
+    components: ComponentRollup[];
+    /** The most recent update cycles in the window, oldest first. */
+    cycles: UpdateCycle[];
+    /** Total events currently held in the ring buffer, before derivation. */
+    bufferSize: number;
+    /** True if more cycles were derived than were returned. */
+    truncated: boolean;
+}
+/** Argument of the `set-recording` action. */
+export interface SetRecordingArgs {
+    recording: boolean;
+}
+/** Argument of the `toggle-layer` action. */
+export interface ToggleLayerArgs {
+    layerId: string;
+    enabled: boolean;
+}
+/**
+ * Maps a {@link TimelineLayer.id} to the {@link TimelineLayersState} flag
+ * that gates it. Custom layers have no flag and are always on.
+ */
+export declare const LAYER_FLAGS: Readonly<Record<string, keyof TimelineLayersState>>;
+declare module 'devframe' {
+    interface DevframeRpcServerFunctions {
+        'lit:get-meta': () => Promise<LitGetMetaResult>;
+        'lit:list-components': () => Promise<InspectorTreeNode[]>;
+        'lit:component-details': (args: ComponentDetailsArgs) => Promise<InspectorDetails | null>;
+        'lit:recent-events': (args?: RecentEventsArgs) => Promise<RecentEventsResult>;
+        'lit:update-summary': (args?: UpdateSummaryArgs) => Promise<UpdateSummaryResult>;
+        'lit:inspect': (command: InspectorCommand) => Promise<void>;
+        'lit:set-recording': (args: SetRecordingArgs) => Promise<void>;
+        'lit:toggle-layer': (args: ToggleLayerArgs) => Promise<void>;
+        'lit:set-settings-override': (override: SettingsOverride) => Promise<void>;
+        'lit:open-source': (args: OpenSourceArgs) => Promise<OpenSourceResult>;
+        'lit:export-snapshot': (args: ExportSnapshotArgs) => Promise<ExportSnapshotResult>;
+        'lit:hmr-incompatibilities': () => Promise<HmrIncompatibilityEvent[]>;
+    }
+    interface DevframeRpcClientFunctions {
+        'lit:inspector-message': (message: InspectorMessage) => void;
+        'lit:hmr-incompatible': (event: HmrIncompatibilityEvent) => void;
+    }
+    interface DevframeSettingsRegistry {
+        lit: {
+            /** Panel chrome preference. Mirrors `COLOR_SCHEME_LS_KEY`. */
+            appearance?: 'auto' | 'dark' | 'light';
+            /**
+             * The Settings tab's live overrides, stored as one blob the way the
+             * panel already treats them. Mirrors `SETTINGS_OVERRIDE_LS_KEY`, which
+             * stays: the page runtime reads it synchronously at module-init time,
+             * long before any client exists, and every settings-store read is
+             * async by design.
+             */
+            override?: SettingsOverride;
+        };
+    }
+}
+//# sourceMappingURL=protocol.d.ts.map

package/lib/devframe/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/lib/devframe/protocol.ts"],"names":[],"mappings":"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"}

package/lib/devframe/protocol.js

@@ -0,0 +1,77 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+/**
+ * Shared wire contract between the Lit devframe's node-side definition
+ * ({@link ../definition.ts}) and its panel: shared-state / streaming /
+ * RPC-function names, their payload shapes, and the `devframe` registry
+ * augmentations that type them end to end.
+ *
+ * @see plans/devframe-foundation.md
+ */
+import {DEFAULT_LAYERS_STATE} from '../../types/timeline.js';
+/** The devframe's scope id. RPC names become `lit:*`, MCP wire names `lit_*`. */
+export const LIT_DEVFRAME_ID = 'lit';
+/** Shared-state key holding the {@link SessionState} snapshot. */
+export const SESSION_STATE_KEY = 'session';
+/** Streaming channel name the timeline event batches are pushed on. */
+export const TIMELINE_STREAM_NAME = 'timeline';
+/**
+ * Id of the one long-lived timeline stream. Fixed rather than discovered:
+ * there is exactly one page feed per dev session, so the panel can subscribe
+ * without a round trip to look the id up. The node side re-`start()`s this id
+ * if the transport dropped the stream after the last subscriber left.
+ */
+export const TIMELINE_STREAM_ID = 'live';
+/**
+ * Cap on the node-side recent-events ring buffer, matching the timeline
+ * stream's own `replayWindow` so an agent and a (re)connecting panel see
+ * comparable history.
+ */
+export const RECENT_EVENTS_BUFFER_SIZE = 512;
+/** Bare (unscoped) name of the `get-meta` query. */
+export const RPC_GET_META = 'get-meta';
+/** Bare name of the `list-components` query. */
+export const RPC_LIST_COMPONENTS = 'list-components';
+/** Bare name of the `component-details` query. */
+export const RPC_COMPONENT_DETAILS = 'component-details';
+/** Bare name of the `recent-events` query. */
+export const RPC_RECENT_EVENTS = 'recent-events';
+/** Bare name of the `update-summary` query. */
+export const RPC_UPDATE_SUMMARY = 'update-summary';
+/** Bare name of the `inspect` action. */
+export const RPC_INSPECT = 'inspect';
+/** Bare name of the `set-recording` action. */
+export const RPC_SET_RECORDING = 'set-recording';
+/** Bare name of the `toggle-layer` action. */
+export const RPC_TOGGLE_LAYER = 'toggle-layer';
+/** Bare name of the `set-settings-override` action. */
+export const RPC_SET_SETTINGS_OVERRIDE = 'set-settings-override';
+/** Bare name of the `open-source` action. */
+export const RPC_OPEN_SOURCE = 'open-source';
+/** Freeze the current session into a static panel directory. */
+export const RPC_EXPORT_SNAPSHOT = 'export-snapshot';
+/** Bare name of the `inspector-message` client (node → panel) event. */
+export const RPC_INSPECTOR_MESSAGE = 'inspector-message';
+/** Bare name of the `hmr-incompatibilities` query. */
+export const RPC_HMR_INCOMPATIBILITIES = 'hmr-incompatibilities';
+/** Bare name of the `hmr-incompatible` client (node → panel) event. */
+export const RPC_HMR_INCOMPATIBLE = 'hmr-incompatible';
+export const DEFAULT_SESSION_STATE = {
+  layers: DEFAULT_LAYERS_STATE,
+  customLayers: [],
+};
+/**
+ * Maps a {@link TimelineLayer.id} to the {@link TimelineLayersState} flag
+ * that gates it. Custom layers have no flag and are always on.
+ */
+export const LAYER_FLAGS = {
+  'lit-lifecycle': 'litLifecycleEnabled',
+  'lit-render': 'litRenderEnabled',
+  'lit-render-verbose': 'litRenderVerboseEnabled',
+  mouse: 'mouseEventEnabled',
+  keyboard: 'keyboardEventEnabled',
+};
+//# sourceMappingURL=protocol.js.map

package/lib/devframe/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/lib/devframe/protocol.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;GAOG;AAEH,OAAO,EAAC,oBAAoB,EAAC,MAAM,yBAAyB,CAAC;AAiB7D,iFAAiF;AACjF,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,CAAC;AAErC,kEAAkE;AAClE,MAAM,CAAC,MAAM,iBAAiB,GAAG,SAAS,CAAC;AAE3C,uEAAuE;AACvE,MAAM,CAAC,MAAM,oBAAoB,GAAG,UAAU,CAAC;AAE/C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAEzC;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,GAAG,CAAC;AAE7C,oDAAoD;AACpD,MAAM,CAAC,MAAM,YAAY,GAAG,UAAU,CAAC;AAEvC,gDAAgD;AAChD,MAAM,CAAC,MAAM,mBAAmB,GAAG,iBAAiB,CAAC;AAErD,kDAAkD;AAClD,MAAM,CAAC,MAAM,qBAAqB,GAAG,mBAAmB,CAAC;AAEzD,8CAA8C;AAC9C,MAAM,CAAC,MAAM,iBAAiB,GAAG,eAAe,CAAC;AAEjD,+CAA+C;AAC/C,MAAM,CAAC,MAAM,kBAAkB,GAAG,gBAAgB,CAAC;AAEnD,yCAAyC;AACzC,MAAM,CAAC,MAAM,WAAW,GAAG,SAAS,CAAC;AAErC,+CAA+C;AAC/C,MAAM,CAAC,MAAM,iBAAiB,GAAG,eAAe,CAAC;AAEjD,8CAA8C;AAC9C,MAAM,CAAC,MAAM,gBAAgB,GAAG,cAAc,CAAC;AAE/C,uDAAuD;AACvD,MAAM,CAAC,MAAM,yBAAyB,GAAG,uBAAuB,CAAC;AAEjE,6CAA6C;AAC7C,MAAM,CAAC,MAAM,eAAe,GAAG,aAAa,CAAC;AAqB7C,gEAAgE;AAChE,MAAM,CAAC,MAAM,mBAAmB,GAAG,iBAAiB,CAAC;AAmBrD,wEAAwE;AACxE,MAAM,CAAC,MAAM,qBAAqB,GAAG,mBAAmB,CAAC;AAEzD,sDAAsD;AACtD,MAAM,CAAC,MAAM,yBAAyB,GAAG,uBAAuB,CAAC;AAEjE,uEAAuE;AACvE,MAAM,CAAC,MAAM,oBAAoB,GAAG,kBAAkB,CAAC;AAkBvD,MAAM,CAAC,MAAM,qBAAqB,GAAiB;IACjD,MAAM,EAAE,oBAAoB;IAC5B,YAAY,EAAE,EAAE;CACjB,CAAC;AAiFF;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GACtB;IACE,eAAe,EAAE,qBAAqB;IACtC,YAAY,EAAE,kBAAkB;IAChC,oBAAoB,EAAE,yBAAyB;IAC/C,KAAK,EAAE,mBAAmB;IAC1B,QAAQ,EAAE,sBAAsB;CACjC,CAAC","sourcesContent":["/**\n * @license\n * Copyright 2026 Google LLC\n * SPDX-License-Identifier: BSD-3-Clause\n */\n\n/**\n * Shared wire contract between the Lit devframe's node-side definition\n * ({@link ../definition.ts}) and its panel: shared-state / streaming /\n * RPC-function names, their payload shapes, and the `devframe` registry\n * augmentations that type them end to end.\n *\n * @see plans/devframe-foundation.md\n */\n\nimport {DEFAULT_LAYERS_STATE} from '../../types/timeline.js';\nimport type {\n  FeatureSettings,\n  SettingsOverride,\n  TimelineEvent,\n  TimelineLayer,\n  TimelineLayersState,\n} from '../../types/timeline.js';\nimport type {\n  InspectorCommand,\n  InspectorDetails,\n  InspectorMessage,\n  InspectorTreeNode,\n} from '../../types/inspector.js';\nimport type {HmrIncompatibilityEvent} from '../../types/hmr-incompatibility.js';\nimport type {ComponentRollup, UpdateCycle} from '../timeline/derive.js';\n\n/** The devframe's scope id. RPC names become `lit:*`, MCP wire names `lit_*`. */\nexport const LIT_DEVFRAME_ID = 'lit';\n\n/** Shared-state key holding the {@link SessionState} snapshot. */\nexport const SESSION_STATE_KEY = 'session';\n\n/** Streaming channel name the timeline event batches are pushed on. */\nexport const TIMELINE_STREAM_NAME = 'timeline';\n\n/**\n * Id of the one long-lived timeline stream. Fixed rather than discovered:\n * there is exactly one page feed per dev session, so the panel can subscribe\n * without a round trip to look the id up. The node side re-`start()`s this id\n * if the transport dropped the stream after the last subscriber left.\n */\nexport const TIMELINE_STREAM_ID = 'live';\n\n/**\n * Cap on the node-side recent-events ring buffer, matching the timeline\n * stream's own `replayWindow` so an agent and a (re)connecting panel see\n * comparable history.\n */\nexport const RECENT_EVENTS_BUFFER_SIZE = 512;\n\n/** Bare (unscoped) name of the `get-meta` query. */\nexport const RPC_GET_META = 'get-meta';\n\n/** Bare name of the `list-components` query. */\nexport const RPC_LIST_COMPONENTS = 'list-components';\n\n/** Bare name of the `component-details` query. */\nexport const RPC_COMPONENT_DETAILS = 'component-details';\n\n/** Bare name of the `recent-events` query. */\nexport const RPC_RECENT_EVENTS = 'recent-events';\n\n/** Bare name of the `update-summary` query. */\nexport const RPC_UPDATE_SUMMARY = 'update-summary';\n\n/** Bare name of the `inspect` action. */\nexport const RPC_INSPECT = 'inspect';\n\n/** Bare name of the `set-recording` action. */\nexport const RPC_SET_RECORDING = 'set-recording';\n\n/** Bare name of the `toggle-layer` action. */\nexport const RPC_TOGGLE_LAYER = 'toggle-layer';\n\n/** Bare name of the `set-settings-override` action. */\nexport const RPC_SET_SETTINGS_OVERRIDE = 'set-settings-override';\n\n/** Bare name of the `open-source` action. */\nexport const RPC_OPEN_SOURCE = 'open-source';\n\n/** Arguments for {@link RPC_OPEN_SOURCE}. */\nexport interface OpenSourceArgs {\n  /**\n   * The path as the panel has it: what the transform injected, so relative\n   * to the Vite root (or absolute, when the file lives outside it).\n   */\n  file: string;\n  line?: number;\n}\n\n/** What {@link RPC_OPEN_SOURCE} reports back. */\nexport interface OpenSourceResult {\n  /**\n   * False when no open service is installed on the host, which is the\n   * panel's cue to fall back to `/__lit-open-in-editor`.\n   */\n  opened: boolean;\n}\n\n/** Freeze the current session into a static panel directory. */\nexport const RPC_EXPORT_SNAPSHOT = 'export-snapshot';\n\n/** Arguments for {@link RPC_EXPORT_SNAPSHOT}. */\nexport interface ExportSnapshotArgs {\n  /**\n   * Where to write. Relative paths resolve against the dev server's cwd.\n   * Defaults to `lit-devtools-snapshot`.\n   */\n  outDir?: string;\n}\n\n/** What {@link RPC_EXPORT_SNAPSHOT} reports back, for the panel to display. */\nexport interface ExportSnapshotResult {\n  outDir: string;\n  events: number;\n  components: number;\n  details: number;\n}\n\n/** Bare name of the `inspector-message` client (node → panel) event. */\nexport const RPC_INSPECTOR_MESSAGE = 'inspector-message';\n\n/** Bare name of the `hmr-incompatibilities` query. */\nexport const RPC_HMR_INCOMPATIBILITIES = 'hmr-incompatibilities';\n\n/** Bare name of the `hmr-incompatible` client (node → panel) event. */\nexport const RPC_HMR_INCOMPATIBLE = 'hmr-incompatible';\n\n/**\n * Recording/layers snapshot shared between every surface (panel, page\n * runtime, MCP). Survives reconnect; mutated either by the `set-recording` /\n * `toggle-layer` actions below or directly by a panel through the generic\n * shared-state RPC devframe provides.\n *\n * `layers.recordingState` is the single authority for \"is recording\" — the\n * runtime's own layer state carries it, so a separate flag here would be a\n * second copy to keep in sync.\n */\nexport interface SessionState {\n  layers: TimelineLayersState;\n  /** Layers announced at runtime by app code through `addTimelineLayer()`. */\n  customLayers: TimelineLayer[];\n}\n\nexport const DEFAULT_SESSION_STATE: SessionState = {\n  layers: DEFAULT_LAYERS_STATE,\n  customLayers: [],\n};\n\n/** Result of the `get-meta` query. */\nexport interface LitGetMetaResult {\n  version: string;\n  /** Built-in layers followed by any runtime-announced custom ones. */\n  layers: TimelineLayer[];\n  features: FeatureSettings | null;\n  /** Channel and id to pass to `rpc.streaming.subscribe()`. */\n  stream: {channel: string; id: string};\n}\n\n/** Argument of the `component-details` query. */\nexport interface ComponentDetailsArgs {\n  id: number;\n}\n\n/** Argument of the `recent-events` query. */\nexport interface RecentEventsArgs {\n  layerId?: string;\n  elementId?: number;\n  /**\n   * Only events from the last `sinceMs` milliseconds, measured against\n   * the newest event currently in the buffer — not wall-clock time.\n   * `TimelineEvent.time` is \"ms since recording started\" in the page\n   * (see `runtime/timeline/clock.ts`), which has no fixed relationship\n   * to this process's clock.\n   */\n  sinceMs?: number;\n  /** Default 50, hard ceiling 200 regardless of what's requested. */\n  limit?: number;\n}\n\n/** Result of the `recent-events` query. */\nexport interface RecentEventsResult {\n  /** Whether the timeline is currently recording. */\n  recording: boolean;\n  /** Most recent events matching the filters, oldest first. */\n  events: TimelineEvent[];\n  /** Total events currently held in the ring buffer, before filtering. */\n  bufferSize: number;\n  /** True if filtering matched more events than were returned. */\n  truncated: boolean;\n}\n\n/** Argument of the `update-summary` query. */\nexport interface UpdateSummaryArgs {\n  /** Restrict to one component, by tag name. */\n  tagName?: string;\n  /** Same window semantics as {@link RecentEventsArgs.sinceMs}. */\n  sinceMs?: number;\n  /** Cycles returned (the component totals always cover the whole window).\n   *  Default 50, hard ceiling 200. */\n  limit?: number;\n}\n\n/** Result of the `update-summary` query. */\nexport interface UpdateSummaryResult {\n  /** Whether the timeline is currently recording. */\n  recording: boolean;\n  /** Per-component totals over the window, slowest first. */\n  components: ComponentRollup[];\n  /** The most recent update cycles in the window, oldest first. */\n  cycles: UpdateCycle[];\n  /** Total events currently held in the ring buffer, before derivation. */\n  bufferSize: number;\n  /** True if more cycles were derived than were returned. */\n  truncated: boolean;\n}\n\n/** Argument of the `set-recording` action. */\nexport interface SetRecordingArgs {\n  recording: boolean;\n}\n\n/** Argument of the `toggle-layer` action. */\nexport interface ToggleLayerArgs {\n  layerId: string;\n  enabled: boolean;\n}\n\n/**\n * Maps a {@link TimelineLayer.id} to the {@link TimelineLayersState} flag\n * that gates it. Custom layers have no flag and are always on.\n */\nexport const LAYER_FLAGS: Readonly<Record<string, keyof TimelineLayersState>> =\n  {\n    'lit-lifecycle': 'litLifecycleEnabled',\n    'lit-render': 'litRenderEnabled',\n    'lit-render-verbose': 'litRenderVerboseEnabled',\n    mouse: 'mouseEventEnabled',\n    keyboard: 'keyboardEventEnabled',\n  };\n\n// Hand-typed rather than derived through `RpcDefinitionsToFunctionsWithNamespace`\n// (also exported by `devframe/rpc`): the definitions themselves live in\n// definition.ts next to their handlers, and hand-typing here avoids a\n// value-level dependency from this shared-contract module back onto it.\ndeclare module 'devframe' {\n  interface DevframeRpcServerFunctions {\n    'lit:get-meta': () => Promise<LitGetMetaResult>;\n    'lit:list-components': () => Promise<InspectorTreeNode[]>;\n    'lit:component-details': (\n      args: ComponentDetailsArgs\n    ) => Promise<InspectorDetails | null>;\n    'lit:recent-events': (\n      args?: RecentEventsArgs\n    ) => Promise<RecentEventsResult>;\n    'lit:update-summary': (\n      args?: UpdateSummaryArgs\n    ) => Promise<UpdateSummaryResult>;\n    'lit:inspect': (command: InspectorCommand) => Promise<void>;\n    'lit:set-recording': (args: SetRecordingArgs) => Promise<void>;\n    'lit:toggle-layer': (args: ToggleLayerArgs) => Promise<void>;\n    'lit:set-settings-override': (override: SettingsOverride) => Promise<void>;\n    'lit:open-source': (args: OpenSourceArgs) => Promise<OpenSourceResult>;\n    'lit:export-snapshot': (\n      args: ExportSnapshotArgs\n    ) => Promise<ExportSnapshotResult>;\n    'lit:hmr-incompatibilities': () => Promise<HmrIncompatibilityEvent[]>;\n  }\n\n  interface DevframeRpcClientFunctions {\n    'lit:inspector-message': (message: InspectorMessage) => void;\n    'lit:hmr-incompatible': (event: HmrIncompatibilityEvent) => void;\n  }\n\n  interface DevframeSettingsRegistry {\n    lit: {\n      /** Panel chrome preference. Mirrors `COLOR_SCHEME_LS_KEY`. */\n      appearance?: 'auto' | 'dark' | 'light';\n      /**\n       * The Settings tab's live overrides, stored as one blob the way the\n       * panel already treats them. Mirrors `SETTINGS_OVERRIDE_LS_KEY`, which\n       * stays: the page runtime reads it synchronously at module-init time,\n       * long before any client exists, and every settings-store read is\n       * async by design.\n       */\n      override?: SettingsOverride;\n    };\n  }\n}\n"]}

package/lib/devframe/source.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+/**
+ * The `TimelineSource` port: the abstraction over "where page-runtime
+ * traffic comes from". The framework-neutral definition
+ * ({@link ../definition.ts}) only ever talks to this interface, so it can run
+ * under `createDevServer()` with no Vite installed. `vite.ts` supplies the
+ * real implementation (an `import.meta.hot` bridge); `createDevServer()` /
+ * `createBuild()` / an MCP server use {@link createNullSource} instead, since
+ * no page is attached.
+ */
+import type { InspectorCommand, InspectorMessage } from '../../types/inspector.js';
+import type { SettingsOverride, TimelineEvent, TimelineLayer, TimelineLayersState } from '../../types/timeline.js';
+import type { HmrIncompatibilityEvent } from '../../types/hmr-incompatibility.js';
+/** The definition's sink for events arriving from the page runtime. */
+export interface TimelineSink {
+    pushEvents(events: TimelineEvent[]): void;
+    addLayer(layer: TimelineLayer): void;
+    inspectorMessage(msg: InspectorMessage): void;
+    hmrIncompatible(event: HmrIncompatibilityEvent): void;
+    /**
+     * A page runtime just connected (first load, reload, or HMR reconnect). It
+     * starts from the compiled-in defaults, so whatever recording/layer state
+     * this session already holds has to be replayed to it — otherwise a page
+     * loaded while recording is on silently captures nothing.
+     */
+    runtimeReady(): void;
+}
+/** Where the definition sends/receives page-runtime traffic. */
+export interface TimelineSource {
+    /** Start forwarding page-runtime traffic to `sink`. Returns a detach function. */
+    attach(sink: TimelineSink): () => void;
+    sendInspector(cmd: InspectorCommand): void;
+    toggleOverlay(): void;
+    setRecording(r: boolean): void;
+    setLayers(l: TimelineLayersState): void;
+    /** Apply a live feature-settings override to the running page. */
+    setSettingsOverride(override: SettingsOverride): void;
+}
+/**
+ * No-op source used wherever no page is attached (`createDevServer()`,
+ * `createBuild()`, an MCP server). `attach()` never calls the sink; every
+ * other method is a no-op.
+ */
+export declare function createNullSource(): TimelineSource;
+//# sourceMappingURL=source.d.ts.map

package/lib/devframe/source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../src/lib/devframe/source.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,gBAAgB,EACjB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EACV,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,mBAAmB,EACpB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAC,uBAAuB,EAAC,MAAM,oCAAoC,CAAC;AAEhF,uEAAuE;AACvE,MAAM,WAAW,YAAY;IAC3B,UAAU,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,IAAI,CAAC;IAC1C,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IACrC,gBAAgB,CAAC,GAAG,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC9C,eAAe,CAAC,KAAK,EAAE,uBAAuB,GAAG,IAAI,CAAC;IACtD;;;;;OAKG;IACH,YAAY,IAAI,IAAI,CAAC;CACtB;AAED,gEAAgE;AAChE,MAAM,WAAW,cAAc;IAC7B,kFAAkF;IAClF,MAAM,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,IAAI,CAAC;IACvC,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC3C,aAAa,IAAI,IAAI,CAAC;IACtB,YAAY,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/B,SAAS,CAAC,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACxC,kEAAkE;IAClE,mBAAmB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;CACvD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,cAAc,CAWjD"}

package/lib/devframe/source.js

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+/**
+ * No-op source used wherever no page is attached (`createDevServer()`,
+ * `createBuild()`, an MCP server). `attach()` never calls the sink; every
+ * other method is a no-op.
+ */
+export function createNullSource() {
+  return {
+    attach() {
+      return () => {};
+    },
+    sendInspector() {},
+    toggleOverlay() {},
+    setRecording() {},
+    setLayers() {},
+    setSettingsOverride() {},
+  };
+}
+//# sourceMappingURL=source.js.map

package/lib/devframe/source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.js","sourceRoot":"","sources":["../../src/lib/devframe/source.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAmDH;;;;GAIG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO;QACL,MAAM;YACJ,OAAO,GAAG,EAAE,GAAE,CAAC,CAAC;QAClB,CAAC;QACD,aAAa,KAAI,CAAC;QAClB,aAAa,KAAI,CAAC;QAClB,YAAY,KAAI,CAAC;QACjB,SAAS,KAAI,CAAC;QACd,mBAAmB,KAAI,CAAC;KACzB,CAAC;AACJ,CAAC","sourcesContent":["/**\n * @license\n * Copyright 2026 Google LLC\n * SPDX-License-Identifier: BSD-3-Clause\n */\n\n/**\n * The `TimelineSource` port: the abstraction over \"where page-runtime\n * traffic comes from\". The framework-neutral definition\n * ({@link ../definition.ts}) only ever talks to this interface, so it can run\n * under `createDevServer()` with no Vite installed. `vite.ts` supplies the\n * real implementation (an `import.meta.hot` bridge); `createDevServer()` /\n * `createBuild()` / an MCP server use {@link createNullSource} instead, since\n * no page is attached.\n */\n\nimport type {\n  InspectorCommand,\n  InspectorMessage,\n} from '../../types/inspector.js';\nimport type {\n  SettingsOverride,\n  TimelineEvent,\n  TimelineLayer,\n  TimelineLayersState,\n} from '../../types/timeline.js';\nimport type {HmrIncompatibilityEvent} from '../../types/hmr-incompatibility.js';\n\n/** The definition's sink for events arriving from the page runtime. */\nexport interface TimelineSink {\n  pushEvents(events: TimelineEvent[]): void;\n  addLayer(layer: TimelineLayer): void;\n  inspectorMessage(msg: InspectorMessage): void;\n  hmrIncompatible(event: HmrIncompatibilityEvent): void;\n  /**\n   * A page runtime just connected (first load, reload, or HMR reconnect). It\n   * starts from the compiled-in defaults, so whatever recording/layer state\n   * this session already holds has to be replayed to it — otherwise a page\n   * loaded while recording is on silently captures nothing.\n   */\n  runtimeReady(): void;\n}\n\n/** Where the definition sends/receives page-runtime traffic. */\nexport interface TimelineSource {\n  /** Start forwarding page-runtime traffic to `sink`. Returns a detach function. */\n  attach(sink: TimelineSink): () => void;\n  sendInspector(cmd: InspectorCommand): void;\n  toggleOverlay(): void;\n  setRecording(r: boolean): void;\n  setLayers(l: TimelineLayersState): void;\n  /** Apply a live feature-settings override to the running page. */\n  setSettingsOverride(override: SettingsOverride): void;\n}\n\n/**\n * No-op source used wherever no page is attached (`createDevServer()`,\n * `createBuild()`, an MCP server). `attach()` never calls the sink; every\n * other method is a no-op.\n */\nexport function createNullSource(): TimelineSource {\n  return {\n    attach() {\n      return () => {};\n    },\n    sendInspector() {},\n    toggleOverlay() {},\n    setRecording() {},\n    setLayers() {},\n    setSettingsOverride() {},\n  };\n}\n"]}

package/lib/devframe/vite.d.ts

@@ -0,0 +1,116 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+/**
+ * Mounts the Lit devframe ({@link createLitDevframe}) into the Vite DevTools
+ * hub and bridges the page runtime's `import.meta.hot` transport to the
+ * definition's `TimelineSource` port. Everything Vite-specific lives here:
+ * the definition itself must keep running under `createDevServer()` with no
+ * Vite installed.
+ *
+ * Vite DevTools 0.7+ is itself built on devframe, so its plugin context is a
+ * devframe hub context: `ctx.install(definition)` serves the panel SPA from
+ * the definition's `clientAssets`, registers its dock, and exposes its RPC
+ * over the hub's authenticated WebSocket. That is all
+ * `createPluginFromDevframe()` from `@vitejs/devtools-kit` does, so calling
+ * `install` directly keeps DevTools an optional peer we never import at
+ * runtime — the hook below is duck-typed, exactly as the panel's previous
+ * dock registration was.
+ *
+ * @see plans/devframe-foundation.md
+ */
+import type { Plugin, ViteDevServer } from 'vite';
+import type { DevframeDefinition } from 'devframe';
+import type { InspectorCommand } from '../../types/inspector.js';
+import type { FeatureSettings, SettingsOverride, TimelineLayersState } from '../../types/timeline.js';
+import { createLitDevframe } from './definition.js';
+import type { TimelineSink, TimelineSource } from './source.js';
+export { createLitDevframe };
+/**
+ * The slice of the Vite DevTools hub context this plugin uses. Structurally a
+ * subset of `ViteDevToolsNodeContext` from `@vitejs/devtools-kit/node`;
+ * declared here so the package never imports that optional peer at runtime.
+ * Install `@vitejs/devtools-kit` as a dev dependency to check it against the
+ * real declarations.
+ */
+interface DevToolsHubContext {
+    readonly viteServer?: ViteDevServer;
+    /** Serve a devframe's SPA, register its dock, and run its `setup()`. */
+    install: (devframe: DevframeDefinition, options?: {
+        base?: string;
+        dock?: Record<string, unknown>;
+    }) => Promise<void>;
+    docks?: {
+        activate?: (dockId: string, params?: Record<string, unknown>) => void;
+    };
+    commands?: {
+        register?: (command: Record<string, unknown>) => unknown;
+    };
+    /**
+     * The hub's host runtime. Structurally the slice of devframe's
+     * `DevframeHost` {@link registerInstance} needs; `DevframeHubContext`
+     * extends `DevframeNodeContext`, which carries it.
+     */
+    host?: {
+        resolveOrigin?: () => string;
+    };
+}
+declare module 'vite' {
+    interface Plugin {
+        /** Vite DevTools plugin hook, contributed by `@vitejs/devtools`. */
+        devtools?: {
+            capabilities?: {
+                dev?: boolean;
+                build?: boolean;
+            };
+            setup: (ctx: DevToolsHubContext) => void | Promise<void>;
+        };
+    }
+}
+export interface CreateLitDevframePluginOptions {
+    version: string;
+    features?: () => FeatureSettings | null;
+    /** Override the built panel SPA directory. Defaults to `dist/client`. */
+    clientAssets?: string;
+}
+/**
+ * `TimelineSource` over a Vite dev server's `hot` channel.
+ *
+ * `install()` runs the definition's `setup()` — and therefore
+ * `source.attach()` — before it resolves, so this is attached before a dev
+ * server is necessarily in hand. Calls made before {@link bind} are dropped
+ * rather than buffered: nothing can emit a page-runtime event until a page
+ * has connected to a bound server.
+ */
+export declare class HotTimelineSource implements TimelineSource {
+    #private;
+    /**
+     * Wire the source to a live dev server. Call once, from `devtools.setup()`.
+     * `hub` is optional: without it the bridge still carries page traffic both
+     * ways, it just cannot bring the dock to the front on an overlay pick.
+     */
+    bind(server: ViteDevServer, hub?: DevToolsHubContext): void;
+    /** Toggle the page's inspect overlay. Also used by the palette command. */
+    toggleOverlay(): void;
+    attach(sink: TimelineSink): () => void;
+    sendInspector(cmd: InspectorCommand): void;
+    setRecording(recording: boolean): void;
+    setLayers(layers: TimelineLayersState): void;
+    setSettingsOverride(override: SettingsOverride): void;
+}
+/**
+ * The Vite plugin that mounts the Lit devframe on the DevTools hub. A no-op
+ * when DevTools is not active: without it nothing calls `devtools.setup()`,
+ * so the definition is never installed and the panel simply isn't there.
+ */
+export declare function createLitDevframePlugin(options: CreateLitDevframePluginOptions): Plugin;
+/**
+ * The page-runtime bridge on its own, for a host that drives its own mount
+ * (or a test that wants to observe page traffic without a hub). Bind it to a
+ * dev server, then either hand it to {@link createLitDevframe} or
+ * {@link TimelineSource.attach} your own sink.
+ */
+export declare const createHotTimelineSource: () => HotTimelineSource;
+//# sourceMappingURL=vite.d.ts.map

package/lib/devframe/vite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite.d.ts","sourceRoot":"","sources":["../../src/lib/devframe/vite.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAE,aAAa,EAAC,MAAM,MAAM,CAAC;AAChD,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,UAAU,CAAC;AAMjD,OAAO,KAAK,EACV,gBAAgB,EAEjB,MAAM,0BAA0B,CAAC;AAIlC,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EAGhB,mBAAmB,EACpB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAC,iBAAiB,EAAC,MAAM,iBAAiB,CAAC;AAElD,OAAO,KAAK,EAAC,YAAY,EAAE,cAAc,EAAC,MAAM,aAAa,CAAC;AAE9D,OAAO,EAAC,iBAAiB,EAAC,CAAC;AAE3B;;;;;;GAMG;AACH,UAAU,kBAAkB;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,aAAa,CAAC;IACpC,wEAAwE;IACxE,OAAO,EAAE,CACP,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,CAAC,EAAE;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAC,KACtD,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,KAAK,CAAC,EAAE;QACN,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;KACvE,CAAC;IACF,QAAQ,CAAC,EAAE;QAAC,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAA;KAAC,CAAC;IACtE;;;;OAIG;IACH,IAAI,CAAC,EAAE;QAAC,aAAa,CAAC,EAAE,MAAM,MAAM,CAAA;KAAC,CAAC;CACvC;AAED,OAAO,QAAQ,MAAM,CAAC;IACpB,UAAU,MAAM;QACd,oEAAoE;QACpE,QAAQ,CAAC,EAAE;YACT,YAAY,CAAC,EAAE;gBAAC,GAAG,CAAC,EAAE,OAAO,CAAC;gBAAC,KAAK,CAAC,EAAE,OAAO,CAAA;aAAC,CAAC;YAChD,KAAK,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;SAC1D,CAAC;KACH;CACF;AAED,MAAM,WAAW,8BAA8B;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,eAAe,GAAG,IAAI,CAAC;IACxC,yEAAyE;IACzE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,qBAAa,iBAAkB,YAAW,cAAc;;IAKtD;;;;OAIG;IACH,IAAI,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAuC1D;IAED,2EAA2E;IAC3E,aAAa,IAAI,IAAI,CAEpB;IAED,MAAM,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,IAAI,CAKrC;IAED,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,IAAI,CAEzC;IAED,YAAY,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,CAErC;IAED,SAAS,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAU3C;IAED,mBAAmB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAEpD;CACF;AAqJD;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,8BAA8B,GACtC,MAAM,CAmDR;AAED;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,QAAO,iBAClB,CAAC"}