@oddsquad/vite-plugin-lit 0.2.2 → 0.3.0

package/lib/timeline-plugin.js

@@ -3,12 +3,19 @@
  * Copyright 2026 Google LLC
  * SPDX-License-Identifier: BSD-3-Clause
  */
-import { existsSync } from 'node:fs';
-import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { SETTINGS_OVERRIDE_CHANNEL, } from '../types/timeline.js';
-import { INSPECT_CMD_CHANNEL, INSPECT_DATA_CHANNEL, INSPECT_OVERLAY_TOGGLE_CHANNEL, INSPECT_PATH, INSPECT_SSE_EVENT, } from '../types/inspector.js';
+import {existsSync} from 'node:fs';
+import {readFile} from 'node:fs/promises';
+import {join} from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {isTrustedRequest} from './http.js';
+import {SETTINGS_OVERRIDE_CHANNEL} from '../types/timeline.js';
+import {
+  INSPECT_CMD_CHANNEL,
+  INSPECT_DATA_CHANNEL,
+  INSPECT_OVERLAY_TOGGLE_CHANNEL,
+  INSPECT_PATH,
+  INSPECT_SSE_EVENT,
+} from '../types/inspector.js';
 // ---------------------------------------------------------------------------
 // SSE push channel — streams batches of TimelineEvents from the server to
 // the panel iframe. The panel subscribes to /__lit-devtools-events using the
@@ -26,11 +33,12 @@ const SETTINGS_PATH = '/__lit-devtools-settings';
 // 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>';
+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>';
 const LIT_LOGO_ICON = `data:image/svg+xml,${encodeURIComponent(LIT_LOGO_SVG)}`;
 /**
  * Resolves the panel files, checking the compiled output first (`panel/`) then
@@ -38,18 +46,18 @@ const LIT_LOGO_ICON = `data:image/svg+xml,${encodeURIComponent(LIT_LOGO_SVG)}`;
  * served via Vite's /@fs/ handler so TypeScript is compiled on the fly.
  */
 const resolvePanel = () => {
-    for (const [htmlRel, appRel] of [
-        ['../panel/index.html', '../panel/lit-devtools-panel.js'],
-        ['../src/panel/index.html', '../src/panel/lit-devtools-panel.ts'],
-    ]) {
-        const htmlUrl = new URL(htmlRel, import.meta.url);
-        if (existsSync(htmlUrl)) {
-            const htmlDir = fileURLToPath(new URL('.', htmlUrl));
-            const appModule = fileURLToPath(new URL(appRel, import.meta.url));
-            return { htmlDir, appModule };
-        }
+  for (const [htmlRel, appRel] of [
+    ['../panel/index.html', '../panel/lit-devtools-panel.js'],
+    ['../src/panel/index.html', '../src/panel/lit-devtools-panel.ts'],
+  ]) {
+    const htmlUrl = new URL(htmlRel, import.meta.url);
+    if (existsSync(htmlUrl)) {
+      const htmlDir = fileURLToPath(new URL('.', htmlUrl));
+      const appModule = fileURLToPath(new URL(appRel, import.meta.url));
+      return {htmlDir, appModule};
     }
-    throw new Error('[lit-plugin:timeline] panel directory not found');
+  }
+  throw new Error('[lit-plugin:timeline] panel directory not found');
 };
 /**
  * Reads and JSON-parses a request body, invoking `done` with the parsed object
@@ -57,320 +65,295 @@ const resolvePanel = () => {
  * endpoints.
  */
 const readJsonBody = (req, done) => {
-    const chunks = [];
-    req.on?.('data', (chunk) => chunks.push(chunk));
-    req.on?.('end', () => {
-        try {
-            done(JSON.parse(Buffer.concat(chunks).toString()));
-        }
-        catch {
-            done(null);
-        }
-    });
-};
-/** True when the request carries no `Origin` or one whose host matches the
- *  dev-server `Host`. These endpoints drive local dev tooling and (for SSE)
- *  carry source paths and inspected element data, so we reject cross-origin
- *  callers — a page the developer happens to visit — rather than opening them
- *  up with wildcard CORS. */
-const isSameOrigin = (headers) => {
-    const { origin, host } = headers;
-    if (origin === undefined || origin === 'null')
-        return true;
+  const chunks = [];
+  req.on?.('data', (chunk) => chunks.push(chunk));
+  req.on?.('end', () => {
     try {
-        return new URL(origin).host === host;
-    }
-    catch {
-        return false;
+      done(JSON.parse(Buffer.concat(chunks).toString()));
+    } catch {
+      done(null);
     }
+  });
 };
 const installSseMiddleware = (server, clients, onConnect) => {
-    server.middlewares.use(SSE_PATH, (req, res, next) => {
-        if (req.method !== 'GET') {
-            next();
-            return;
-        }
-        if (!isSameOrigin(req.headers ?? {})) {
-            res.statusCode = 403;
-            res.end?.('forbidden');
-            return;
-        }
-        res.statusCode = 200;
-        res.setHeader('Content-Type', 'text/event-stream');
-        res.setHeader('Cache-Control', 'no-cache');
-        res.setHeader('Connection', 'keep-alive');
-        res.flushHeaders?.();
-        res.write(':\n\n'); // keep-alive comment
-        clients.add(res);
-        res.on('close', () => clients.delete(res));
-        // Replay a just-emitted overlay pick to a panel that connects right after
-        // it (the cold-start case: picking an element opens the dock, but the
-        // panel iframe subscribes here only after the `pick` was already
-        // broadcast to zero clients). See `pendingPick` in `litTimelinePlugin`.
-        onConnect?.(res);
-    });
+  server.middlewares.use(SSE_PATH, (req, res, next) => {
+    if (req.method !== 'GET') {
+      next();
+      return;
+    }
+    if (!isTrustedRequest(req.headers ?? {})) {
+      res.statusCode = 403;
+      res.end?.('forbidden');
+      return;
+    }
+    res.statusCode = 200;
+    res.setHeader('Content-Type', 'text/event-stream');
+    res.setHeader('Cache-Control', 'no-cache');
+    res.setHeader('Connection', 'keep-alive');
+    res.flushHeaders?.();
+    res.write(':\n\n'); // keep-alive comment
+    clients.add(res);
+    res.on('close', () => clients.delete(res));
+    // Replay a just-emitted overlay pick to a panel that connects right after
+    // it (the cold-start case: picking an element opens the dock, but the
+    // panel iframe subscribes here only after the `pick` was already
+    // broadcast to zero clients). See `pendingPick` in `litTimelinePlugin`.
+    onConnect?.(res);
+  });
 };
 /** How long a pending overlay pick stays replayable to a freshly-connected
  *  panel. Long enough to cover the dock iframe mounting + subscribing, short
  *  enough that an unrelated later reconnect won't resurrect a stale selection. */
 const PICK_REPLAY_WINDOW_MS = 3000;
 export const litTimelinePlugin = (getSettings) => {
-    const sseClients = new Set();
-    // Captured in configureServer so the (server-side) DevTools command handler
-    // can broadcast to the app runtime; it only runs after the server is up.
-    let devServer;
-    // The most recent overlay `pick`, framed as an SSE payload, kept briefly so a
-    // panel that mounts in response to the pick (cold start) still receives it.
-    let pendingPick = null;
-    /** Write a pre-framed SSE payload to every client, pruning dead sockets. */
-    const broadcast = (payload) => {
-        for (const client of sseClients) {
-            try {
-                client.write(payload);
-            }
-            catch {
-                sseClients.delete(client);
+  const sseClients = new Set();
+  // Captured in configureServer so the (server-side) DevTools command handler
+  // can broadcast to the app runtime; it only runs after the server is up.
+  let devServer;
+  // The most recent overlay `pick`, framed as an SSE payload, kept briefly so a
+  // panel that mounts in response to the pick (cold start) still receives it.
+  let pendingPick = null;
+  /** Write a pre-framed SSE payload to every client, pruning dead sockets. */
+  const broadcast = (payload) => {
+    for (const client of sseClients) {
+      try {
+        client.write(payload);
+      } catch {
+        sseClients.delete(client);
+      }
+    }
+  };
+  /** Push a batch of events to all subscribed panel SSE clients. */
+  const pushToPanel = (events) => {
+    if (sseClients.size === 0 || events.length === 0) return;
+    broadcast(`data: ${JSON.stringify(events)}\n\n`);
+  };
+  /** Push a named SSE event (the panel listens via `addEventListener(name)`). */
+  const pushEvent = (name, data) => {
+    if (sseClients.size === 0) return;
+    broadcast(`event: ${name}\ndata: ${JSON.stringify(data)}\n\n`);
+  };
+  return {
+    name: 'lit-devtools',
+    apply: 'serve',
+    configureServer(server) {
+      devServer = server;
+      // SSE endpoint: panel iframe subscribes here for event push. A client that
+      // connects within the replay window gets the pending pick replayed.
+      installSseMiddleware(server, sseClients, (client) => {
+        if (pendingPick === null) return;
+        if (Date.now() >= pendingPick.expires) {
+          pendingPick = null;
+          return;
+        }
+        // Replay to every client connecting within the window, not just the
+        // first: the panel opens two SSE subscriptions (components-view and
+        // timeline-view) and only components-view acts on `pick`. A one-shot
+        // replay could land on timeline-view and be dropped. Replaying to all
+        // is safe — timeline-view ignores the event, and components-view's
+        // selection is idempotent. The pick clears on expiry, below.
+        try {
+          client.write(pendingPick.payload);
+        } catch {
+          // Socket already gone — nothing to replay to.
+        }
+      });
+      // Settings endpoint. GET returns the resolved feature settings (the
+      // baseline the panel renders). POST carries a SettingsOverride which we
+      // rebroadcast to the app runtime via HMR so it takes effect live.
+      server.middlewares.use(SETTINGS_PATH, (req, res, next) => {
+        if (!isTrustedRequest(req.headers ?? {})) {
+          res.statusCode = 403;
+          res.end('forbidden');
+          return;
+        }
+        if (req.method === 'GET') {
+          res.statusCode = 200;
+          res.setHeader('Content-Type', 'application/json; charset=utf-8');
+          res.setHeader('Cache-Control', 'no-cache');
+          res.end(JSON.stringify(getSettings?.() ?? null));
+          return;
+        }
+        if (req.method === 'POST') {
+          readJsonBody(req, (body) => {
+            if (body !== null) {
+              server.hot.send(SETTINGS_OVERRIDE_CHANNEL, body);
             }
+            res.statusCode = 204;
+            res.end();
+          });
+          return;
         }
-    };
-    /** Push a batch of events to all subscribed panel SSE clients. */
-    const pushToPanel = (events) => {
-        if (sseClients.size === 0 || events.length === 0)
+        next();
+      });
+      // Serve the panel HTML with the Lit SPA entry injected via /@fs/ so
+      // Vite can transform the TypeScript source on the fly.
+      let panel;
+      try {
+        panel = resolvePanel();
+      } catch (e) {
+        console.warn(String(e));
+      }
+      if (panel !== undefined) {
+        const {htmlDir, appModule} = panel;
+        server.middlewares.use(PANEL_PATH, async (req, res, next) => {
+          const url = req.url ?? '/';
+          if (url !== '/' && url !== '' && url !== '/index.html') {
+            next();
             return;
-        broadcast(`data: ${JSON.stringify(events)}\n\n`);
-    };
-    /** Push a named SSE event (the panel listens via `addEventListener(name)`). */
-    const pushEvent = (name, data) => {
-        if (sseClients.size === 0)
+          }
+          let html;
+          try {
+            html = await readFile(join(htmlDir, 'index.html'), 'utf-8');
+          } catch {
+            next();
             return;
-        broadcast(`event: ${name}\ndata: ${JSON.stringify(data)}\n\n`);
-    };
-    return {
-        name: 'lit-devtools',
-        apply: 'serve',
-        configureServer(server) {
-            devServer = server;
-            // SSE endpoint: panel iframe subscribes here for event push. A client that
-            // connects within the replay window gets the pending pick replayed.
-            installSseMiddleware(server, sseClients, (client) => {
-                if (pendingPick === null)
-                    return;
-                if (Date.now() >= pendingPick.expires) {
-                    pendingPick = null;
-                    return;
-                }
-                // Replay to every client connecting within the window, not just the
-                // first: the panel opens two SSE subscriptions (components-view and
-                // timeline-view) and only components-view acts on `pick`. A one-shot
-                // replay could land on timeline-view and be dropped. Replaying to all
-                // is safe — timeline-view ignores the event, and components-view's
-                // selection is idempotent. The pick clears on expiry, below.
-                try {
-                    client.write(pendingPick.payload);
-                }
-                catch {
-                    // Socket already gone — nothing to replay to.
-                }
-            });
-            // Settings endpoint. GET returns the resolved feature settings (the
-            // baseline the panel renders). POST carries a SettingsOverride which we
-            // rebroadcast to the app runtime via HMR so it takes effect live.
-            server.middlewares.use(SETTINGS_PATH, (req, res, next) => {
-                if (!isSameOrigin(req.headers ?? {})) {
-                    res.statusCode = 403;
-                    res.end('forbidden');
-                    return;
-                }
-                if (req.method === 'GET') {
-                    res.statusCode = 200;
-                    res.setHeader('Content-Type', 'application/json; charset=utf-8');
-                    res.setHeader('Cache-Control', 'no-cache');
-                    res.end(JSON.stringify(getSettings?.() ?? null));
-                    return;
-                }
-                if (req.method === 'POST') {
-                    readJsonBody(req, (body) => {
-                        if (body !== null) {
-                            server.hot.send(SETTINGS_OVERRIDE_CHANNEL, body);
-                        }
-                        res.statusCode = 204;
-                        res.end();
-                    });
-                    return;
-                }
-                next();
-            });
-            // Serve the panel HTML with the Lit SPA entry injected via /@fs/ so
-            // Vite can transform the TypeScript source on the fly.
-            let panel;
-            try {
-                panel = resolvePanel();
+          }
+          // Inject the panel entry as a /@fs/ module so Vite's transform
+          // pipeline compiles TypeScript and resolves bare specifiers (lit, etc).
+          const scriptTag = `  <script type="module" src="/@fs${appModule}"></script>\n`;
+          html = html.replace('</body>', scriptTag + '</body>');
+          res.statusCode = 200;
+          res.setHeader('Content-Type', 'text/html; charset=utf-8');
+          res.end(html);
+        });
+      }
+      // Control endpoint: the panel POSTs recording/layer state changes here.
+      // The server rebroadcasts the state to all connected app tabs via HMR.
+      server.middlewares.use(CONTROL_PATH, (req, res, next) => {
+        const method = req.method;
+        if (method !== 'POST') {
+          next();
+          return;
+        }
+        const r403 = res;
+        if (!isTrustedRequest(req.headers ?? {})) {
+          r403.statusCode = 403;
+          r403.end('forbidden');
+          return;
+        }
+        readJsonBody(req, (body) => {
+          if (body !== null) {
+            if (typeof body.recording === 'boolean') {
+              server.hot.send('lit:timeline:recording-changed', {
+                recording: body.recording,
+              });
             }
-            catch (e) {
-                console.warn(String(e));
+            const layerKeys = [
+              'litLifecycleEnabled',
+              'litRenderEnabled',
+              'mouseEventEnabled',
+              'keyboardEventEnabled',
+            ];
+            const layersUpdate = {};
+            for (const key of layerKeys) {
+              if (typeof body[key] === 'boolean') {
+                layersUpdate[key] = body[key];
+              }
             }
-            if (panel !== undefined) {
-                const { htmlDir, appModule } = panel;
-                server.middlewares.use(PANEL_PATH, async (req, res, next) => {
-                    const url = req.url ?? '/';
-                    if (url !== '/' && url !== '' && url !== '/index.html') {
-                        next();
-                        return;
-                    }
-                    let html;
-                    try {
-                        html = await readFile(join(htmlDir, 'index.html'), 'utf-8');
-                    }
-                    catch {
-                        next();
-                        return;
-                    }
-                    // Inject the panel entry as a /@fs/ module so Vite's transform
-                    // pipeline compiles TypeScript and resolves bare specifiers (lit, etc).
-                    const scriptTag = `  <script type="module" src="/@fs${appModule}"></script>\n`;
-                    html = html.replace('</body>', scriptTag + '</body>');
-                    res.statusCode = 200;
-                    res.setHeader('Content-Type', 'text/html; charset=utf-8');
-                    res.end(html);
-                });
+            if (Object.keys(layersUpdate).length > 0) {
+              server.hot.send('lit:timeline:layers-changed', layersUpdate);
             }
-            // Control endpoint: the panel POSTs recording/layer state changes here.
-            // The server rebroadcasts the state to all connected app tabs via HMR.
-            server.middlewares.use(CONTROL_PATH, (req, res, next) => {
-                const method = req.method;
-                if (method !== 'POST') {
-                    next();
-                    return;
-                }
-                const r403 = res;
-                if (!isSameOrigin(req.headers ?? {})) {
-                    r403.statusCode = 403;
-                    r403.end('forbidden');
-                    return;
-                }
-                readJsonBody(req, (body) => {
-                    if (body !== null) {
-                        if (typeof body.recording === 'boolean') {
-                            server.hot.send('lit:timeline:recording-changed', {
-                                recording: body.recording,
-                            });
-                        }
-                        const layerKeys = [
-                            'litLifecycleEnabled',
-                            'litRenderEnabled',
-                            'mouseEventEnabled',
-                            'keyboardEventEnabled',
-                        ];
-                        const layersUpdate = {};
-                        for (const key of layerKeys) {
-                            if (typeof body[key] === 'boolean') {
-                                layersUpdate[key] = body[key];
-                            }
-                        }
-                        if (Object.keys(layersUpdate).length > 0) {
-                            server.hot.send('lit:timeline:layers-changed', layersUpdate);
-                        }
-                    }
-                    const r = res;
-                    r.statusCode = 204;
-                    r.end();
-                });
-            });
-            // Accept batches of events from the browser runtime via Vite HMR.
-            server.hot.on('lit:timeline:push-event', (data) => {
-                pushToPanel(data.events ?? []);
-            });
-            // Legacy: panel postMessage → devtools shell → server (keep for compat).
-            server.hot.on('lit:timeline:set-recording', (data) => {
-                server.hot.send('lit:timeline:recording-changed', {
-                    recording: data.recording,
-                });
-            });
-            // Custom layer announced by app code via addTimelineLayer().
-            // Forward to the panel as a named SSE event so it can add the layer.
-            server.hot.on('lit:timeline:custom-layer', (data) => {
-                if (!data.layer?.id)
-                    return;
-                pushEvent('layer', data.layer);
-            });
-            // Components inspector. The panel POSTs an InspectorCommand here; we
-            // forward it to the app runtime over HMR. The runtime answers over
-            // INSPECT_DATA_CHANNEL, which we relay to the panel as a named SSE event.
-            server.middlewares.use(INSPECT_PATH, (req, res, next) => {
-                const method = req.method;
-                if (method !== 'POST') {
-                    next();
-                    return;
-                }
-                const r403 = res;
-                if (!isSameOrigin(req.headers ?? {})) {
-                    r403.statusCode = 403;
-                    r403.end('forbidden');
-                    return;
-                }
-                readJsonBody(req, (body) => {
-                    if (body !== null) {
-                        // "Pick" starts the overlay's inspect picker (a server-side toggle),
-                        // not a runtime query, so it's routed to the overlay channel.
-                        if (body.type === 'pick') {
-                            server.hot.send(INSPECT_OVERLAY_TOGGLE_CHANNEL);
-                        }
-                        else {
-                            server.hot.send(INSPECT_CMD_CHANNEL, body);
-                        }
-                    }
-                    const r = res;
-                    r.statusCode = 204;
-                    r.end();
-                });
-            });
-            server.hot.on(INSPECT_DATA_CHANNEL, (data) => {
-                // Remember overlay picks so a cold-started panel (opened by the pick
-                // itself) can replay it on connect — see `pendingPick`.
-                if (data.type === 'pick') {
-                    pendingPick = {
-                        payload: `event: ${INSPECT_SSE_EVENT}\ndata: ${JSON.stringify(data)}\n\n`,
-                        expires: Date.now() + PICK_REPLAY_WINDOW_MS,
-                    };
-                }
-                pushEvent(INSPECT_SSE_EVENT, data);
-            });
-        },
-        devtools: {
-            setup(ctx) {
-                // Register the dock entry. HTML is served by the configureServer
-                // middleware above (with /@fs/ injection); hostStatic is not used.
-                ctx.docks.register({
-                    id: 'lit-devtools',
-                    type: 'iframe',
-                    // This dock represents the whole Lit plugin (HMR, source overlay,
-                    // timeline), so it's branded "Lit" rather than the timeline panel
-                    // it currently opens.
-                    title: 'Lit',
-                    // Square, inlined Lit logo — see LIT_LOGO_ICON above. DevTools renders
-                    // a `data:` icon directly as an <img>, no Iconify API fetch.
-                    icon: LIT_LOGO_ICON,
-                    url: PANEL_PATH + '/',
-                    category: 'framework',
-                });
-                // Register the overlay toggle as a DevTools command so it shows in the
-                // command palette and as a managed shortcut. The handler runs
-                // server-side; it broadcasts to the app runtime, which toggles the
-                // overlay. Only meaningful when the overlay is enabled.
-                const so = getSettings?.()?.sourceOverlay;
-                if (so?.enabled && ctx.commands?.register) {
-                    ctx.commands.register({
-                        id: 'lit:overlay:toggle',
-                        title: 'Pick Lit Element',
-                        description: 'Click to inspect in the Components panel, hold Meta/Ctrl and click to open in your editor',
-                        icon: 'ph:crosshair-duotone',
-                        category: 'Lit',
-                        keybindings: [{ key: 'Meta+Shift+E' }],
-                        handler: () => devServer?.hot.send(INSPECT_OVERLAY_TOGGLE_CHANNEL),
-                    });
-                }
-            },
-        },
-    };
+          }
+          const r = res;
+          r.statusCode = 204;
+          r.end();
+        });
+      });
+      // Accept batches of events from the browser runtime via Vite HMR.
+      server.hot.on('lit:timeline:push-event', (data) => {
+        pushToPanel(data.events ?? []);
+      });
+      // Legacy: panel postMessage → devtools shell → server (keep for compat).
+      server.hot.on('lit:timeline:set-recording', (data) => {
+        server.hot.send('lit:timeline:recording-changed', {
+          recording: data.recording,
+        });
+      });
+      // Custom layer announced by app code via addTimelineLayer().
+      // Forward to the panel as a named SSE event so it can add the layer.
+      server.hot.on('lit:timeline:custom-layer', (data) => {
+        if (!data.layer?.id) return;
+        pushEvent('layer', data.layer);
+      });
+      // Components inspector. The panel POSTs an InspectorCommand here; we
+      // forward it to the app runtime over HMR. The runtime answers over
+      // INSPECT_DATA_CHANNEL, which we relay to the panel as a named SSE event.
+      server.middlewares.use(INSPECT_PATH, (req, res, next) => {
+        const method = req.method;
+        if (method !== 'POST') {
+          next();
+          return;
+        }
+        const r403 = res;
+        if (!isTrustedRequest(req.headers ?? {})) {
+          r403.statusCode = 403;
+          r403.end('forbidden');
+          return;
+        }
+        readJsonBody(req, (body) => {
+          if (body !== null) {
+            // "Pick" starts the overlay's inspect picker (a server-side toggle),
+            // not a runtime query, so it's routed to the overlay channel.
+            if (body.type === 'pick') {
+              server.hot.send(INSPECT_OVERLAY_TOGGLE_CHANNEL);
+            } else {
+              server.hot.send(INSPECT_CMD_CHANNEL, body);
+            }
+          }
+          const r = res;
+          r.statusCode = 204;
+          r.end();
+        });
+      });
+      server.hot.on(INSPECT_DATA_CHANNEL, (data) => {
+        // Remember overlay picks so a cold-started panel (opened by the pick
+        // itself) can replay it on connect — see `pendingPick`.
+        if (data.type === 'pick') {
+          pendingPick = {
+            payload: `event: ${INSPECT_SSE_EVENT}\ndata: ${JSON.stringify(data)}\n\n`,
+            expires: Date.now() + PICK_REPLAY_WINDOW_MS,
+          };
+        }
+        pushEvent(INSPECT_SSE_EVENT, data);
+      });
+    },
+    devtools: {
+      setup(ctx) {
+        // Register the dock entry. HTML is served by the configureServer
+        // middleware above (with /@fs/ injection); hostStatic is not used.
+        ctx.docks.register({
+          id: 'lit-devtools',
+          type: 'iframe',
+          // This dock represents the whole Lit plugin (HMR, source overlay,
+          // timeline), so it's branded "Lit" rather than the timeline panel
+          // it currently opens.
+          title: 'Lit',
+          // Square, inlined Lit logo — see LIT_LOGO_ICON above. DevTools renders
+          // a `data:` icon directly as an <img>, no Iconify API fetch.
+          icon: LIT_LOGO_ICON,
+          url: PANEL_PATH + '/',
+          category: 'framework',
+        });
+        // Register the overlay toggle as a DevTools command so it shows in the
+        // command palette and as a managed shortcut. The handler runs
+        // server-side; it broadcasts to the app runtime, which toggles the
+        // overlay. Only meaningful when the overlay is enabled.
+        const so = getSettings?.()?.sourceOverlay;
+        if (so?.enabled && ctx.commands?.register) {
+          ctx.commands.register({
+            id: 'lit:overlay:toggle',
+            title: 'Pick Lit Element',
+            description:
+              'Click to inspect in the Components panel, hold Meta/Ctrl and click to open in your editor',
+            icon: 'ph:crosshair-duotone',
+            category: 'Lit',
+            keybindings: [{key: 'Meta+Shift+E'}],
+            handler: () => devServer?.hot.send(INSPECT_OVERLAY_TOGGLE_CHANNEL),
+          });
+        }
+      },
+    },
+  };
 };
-//# sourceMappingURL=timeline-plugin.js.map
+//# sourceMappingURL=timeline-plugin.js.map