kennel 0.2.6 → 0.2.7

package/README.md

@@ -116,14 +116,17 @@ diagnostics come from the declared schema and Markdown frontmatter. Pass
 list. See [Core folders and metadata indexing](../docs/core-folders.md) for
 patterns, parser support, navigation labels and refresh semantics.
 
-`kennel view` starts the source Vite viewer from a Kennel checkout when no
+`kennel view` starts the source Vite viewer from a Kennel checkout, also when
 external plugins are installed. React and CSS changes use HMR. Changes to
 schema and content files cause a metadata refetch without a full page reload.
-When external plugins are installed, `kennel view` uses the composed static
-kernel so `view`, `pop`, `serve`, default, `core`, and `init` all use the same
-kernel key. `kennel serve` starts the packaged static viewer. The hot viewer
-uses the current directory when no folder is given. It also reuses a Kennel Vite
-server that already runs on the selected port.
+The Vite viewer loads the installed external plugins and reports a
+runtime-independent plugin-set key from `/api/health`. `kennel serve` starts
+the packaged static viewer with its own runtime-specific cache key. The hot
+viewer uses the current directory when no folder is given. It reuses a Kennel Vite
+server on the selected port only when that server has the same kernel key. If
+the plugin set changed, stop the running viewer and run the command again. A
+local Vite viewer can open any local folder; the static viewer is reused only
+for its own root or a folder below it.
 
 `kennel publish init cloudflare` is the exception for deploy wiring: it scaffolds
 a Cloudflare Worker email-code gate for an existing docs workspace by writing

package/dist/cli/src/plugins/external.d.ts

@@ -26,6 +26,9 @@ export declare function readExternalPlugins(): ExternalPluginEntry[];
 export declare function installExternalPlugin(url: string, options?: {
     directory?: string;
 }): Promise<ExternalPluginEntry>;
+/** Identifies the installed plugin set, independent of the Node runtime. */
+export declare function hotKernelKey(plugins?: ExternalPluginEntry[]): string;
+/** Identifies a runtime-specific static kernel cache entry. */
 export declare function kernelKey(plugins?: ExternalPluginEntry[]): string;
 export type ActiveKernel = {
     buildIdentity: string;

package/dist/cli/src/plugins/external.js

@@ -373,21 +373,33 @@ export async function installExternalPlugin(url, options = {}) {
 function cliRoot() {
     return resolve(dirname(fileURLToPath(import.meta.url)), "../..");
 }
+function kernelPlugins(plugins) {
+    return plugins.map((plugin) => ({
+        url: plugin.url,
+        requestedRef: plugin.requestedRef ?? null,
+        packageName: plugin.packageName,
+        id: plugin.id,
+        directory: plugin.directory ?? null,
+        commit: plugin.commit,
+        trigger: plugin.trigger,
+        entries: plugin.entries,
+    }));
+}
+/** Identifies the installed plugin set, independent of the Node runtime. */
+export function hotKernelKey(plugins = readExternalPlugins()) {
+    return hash(JSON.stringify({
+        buildIdentity: BUILD_IDENTITY,
+        schema: KENNEL_KERNEL_SCHEMA,
+        plugins: kernelPlugins(plugins),
+    }));
+}
+/** Identifies a runtime-specific static kernel cache entry. */
 export function kernelKey(plugins = readExternalPlugins()) {
     return hash(JSON.stringify({
         buildIdentity: BUILD_IDENTITY,
         schema: KENNEL_KERNEL_SCHEMA,
         runtime: BUILD_RUNTIME,
-        plugins: plugins.map((plugin) => ({
-            url: plugin.url,
-            requestedRef: plugin.requestedRef ?? null,
-            packageName: plugin.packageName,
-            id: plugin.id,
-            directory: plugin.directory ?? null,
-            commit: plugin.commit,
-            trigger: plugin.trigger,
-            entries: plugin.entries,
-        })),
+        plugins: kernelPlugins(plugins),
     }));
 }
 function kernelRoot(key) {

package/dist/cli/src/site/hot-viewer.js

@@ -7,12 +7,15 @@ import { tmpdir } from 'node:os';
 import { dirname, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createKennelClient } from '../core/api-client.js';
+import { hotKernelKey, readExternalPlugins } from '../plugins/external.js';
 function sourceRoot() {
     return resolve(dirname(fileURLToPath(import.meta.url)), '../../..');
 }
 async function viewerStatus(url) {
     return createKennelClient({ baseUrl: url }).health({ signal: AbortSignal.timeout(1_000) })
-        .then((body) => body.viewer === 'kennel-vite' || body.viewer === 'kennel-core' ? 'running' : 'other')
+        .then((body) => body.viewer === 'kennel-vite' || body.viewer === 'kennel-core'
+        ? { viewer: body.viewer, kernelKey: body.kernelKey }
+        : 'other')
         .catch((error) => {
         // HTTP rejection means a different service owns the port; connection and
         // timeout failures mean the viewer is unavailable, so startup may retry.
@@ -20,17 +23,17 @@ async function viewerStatus(url) {
             ? 'other' : 'unavailable';
     });
 }
-async function viewerRunning(url, attempts = 1, waitOnOther = false) {
+async function runningViewer(url, attempts = 1, waitOnOther = false) {
     for (let attempt = 0; attempt < attempts; attempt += 1) {
         const status = await viewerStatus(url);
-        if (status === 'running')
-            return true;
+        if (typeof status === 'object')
+            return status;
         if (status === 'other' && !waitOnOther)
-            return false;
+            return undefined;
         if (attempt + 1 < attempts)
             await new Promise((done) => setTimeout(done, 250));
     }
-    return false;
+    return undefined;
 }
 async function portOpen(host, port) {
     return new Promise((done) => {
@@ -132,8 +135,20 @@ export async function hotViewer(options) {
         console.log(`bun ${[...args, ...(options.open ? ['--open', openPath] : [])].join(' ')}`);
         return;
     }
-    const status = await viewerStatus(url);
-    if (status === 'running') {
+    const plugins = readExternalPlugins();
+    // Must match the key apps/web/scripts/dev.mjs gives Vite as KENNEL_KERNEL_KEY.
+    const expectedKey = plugins.length > 0 ? hotKernelKey(plugins) : 'core';
+    // Reuse only a Vite viewer that serves the same plugin set. Anything else on
+    // the port is stale for this kernel and must be restarted, never reused.
+    const reuse = (running) => {
+        const restart = 'Stop that viewer (Ctrl+C in its terminal) and run this command again, or select another port.';
+        if (running.viewer !== 'kennel-vite') {
+            throw new Error(`Port ${options.port} runs the static Kennel viewer, not the hot viewer. ${restart}`);
+        }
+        if (running.kernelKey !== expectedKey) {
+            throw new Error(`The Kennel hot viewer on port ${options.port} uses kernel ${running.kernelKey}, `
+                + `but the installed plugins need kernel ${expectedKey}. ${restart}`);
+        }
         if (options.open) {
             // Do not stack another tab: the viewer is already open. Print the URL
             // so the caller can still get to it deliberately.
@@ -142,21 +157,19 @@ export async function hotViewer(options) {
         else {
             console.log('Kennel hot viewer is already running. Reusing it.');
         }
+    };
+    const status = await viewerStatus(url);
+    if (typeof status === 'object') {
+        reuse(status);
         return;
     }
     if (status === 'other') {
         throw new Error(`Port ${options.port} is used by another service. Stop it or select another port.`);
     }
     if (await portOpen(options.host, options.port)) {
-        if (await viewerRunning(url, 20, true)) {
-            if (options.open) {
-                // Do not stack another tab: the viewer is already open. Print the URL
-                // so the caller can still get to it deliberately.
-                console.log(`Kennel hot viewer is already running at ${viewerUrl}`);
-            }
-            else {
-                console.log('Kennel hot viewer is already running. Reusing it.');
-            }
+        const running = await runningViewer(url, 20, true);
+        if (running) {
+            reuse(running);
             return;
         }
         throw new Error(`Port ${options.port} is used by another service. Stop it or select another port.`);
@@ -164,15 +177,9 @@ export async function hotViewer(options) {
     const lock = startupLock(options.host, options.port);
     let token = await acquireLock(lock);
     if (!token) {
-        if (await viewerRunning(url, 40, true)) {
-            if (options.open) {
-                // Do not stack another tab: the viewer is already open. Print the URL
-                // so the caller can still get to it deliberately.
-                console.log(`Kennel hot viewer is already running at ${viewerUrl}`);
-            }
-            else {
-                console.log('Kennel hot viewer is already running. Reusing it.');
-            }
+        const running = await runningViewer(url, 40, true);
+        if (running) {
+            reuse(running);
             return;
         }
         await rm(lock, { force: true, recursive: true });
@@ -180,16 +187,10 @@ export async function hotViewer(options) {
     }
     if (!token)
         throw new Error(`Could not acquire the hot viewer startup lock for port ${options.port}.`);
-    if (await viewerRunning(url)) {
+    const running = await runningViewer(url);
+    if (running) {
         await releaseLock(lock, token);
-        if (options.open) {
-            // Do not stack another tab: the viewer is already open. Print the URL
-            // so the caller can still get to it deliberately.
-            console.log(`Kennel hot viewer is already running at ${viewerUrl}`);
-        }
-        else {
-            console.log('Kennel hot viewer is already running. Reusing it.');
-        }
+        reuse(running);
         return;
     }
     console.log(`bun ${args.join(' ')}`);
@@ -220,9 +221,15 @@ export async function hotViewer(options) {
                 done();
                 return;
             }
-            if (await viewerRunning(url, 20, true)) {
-                console.log('Kennel hot viewer is already running. Reusing it.');
-                done();
+            const existing = await runningViewer(url, 20, true);
+            if (existing) {
+                try {
+                    reuse(existing);
+                    done();
+                }
+                catch (error) {
+                    fail(error);
+                }
                 return;
             }
             fail(new Error(`Kennel hot viewer stopped with exit code ${code ?? 'unknown'}`));

package/dist/cli/src/site/viewer.js

@@ -259,17 +259,15 @@ function tailscaleHost() {
 export async function viewer(input) {
     const portExplicit = viewerPortWasExplicit(input);
     const options = splitViewerArgs(input);
-    const { ensureKernel, readExternalPlugins } = await import("../plugins/external.js");
-    const externalPlugins = readExternalPlugins();
-    if (options.hot && externalPlugins.length === 0) {
+    if (options.hot) {
         const { hotViewer } = await import("./hot-viewer.js");
         await hotViewer(options);
         return;
     }
-    if (options.hot && externalPlugins.length > 0) {
-        console.log("Kennel hot viewer is disabled for external plugin kernels; using the composed static kernel.");
-    }
+    const { ensureKernel, hotKernelKey, readExternalPlugins } = await import("../plugins/external.js");
+    const externalPlugins = readExternalPlugins();
     const kernel = await ensureKernel(externalPlugins);
+    const viteKernelKey = externalPlugins.length > 0 ? hotKernelKey(externalPlugins) : "core";
     const web = kernel.webRoot;
     if (!existsSync(resolve(web, "index.html"))) {
         throw new Error(`Kennel web app not found. Run the CLI build first.`);
@@ -298,9 +296,16 @@ export async function viewer(input) {
             .join(",");
     const initialViewerUrl = `http://${options.host}:${options.port}`;
     const existing = await runningViewer(initialViewerUrl);
+    // A local Vite viewer is not root-restricted, so it can open any local
+    // folder. The static kennel-core viewer is root-scoped: reuse it only for
+    // its own root or a descendant.
     if (existing &&
-        existing.kernelKey === kernel.key &&
-        isSameOrDescendant(existing.root, options.root)) {
+        ((existing.viewer === "kennel-vite" &&
+            !remote &&
+            existing.kernelKey === viteKernelKey) ||
+            (existing.viewer !== "kennel-vite" &&
+                existing.kernelKey === kernel.key &&
+                isSameOrDescendant(existing.root, options.root)))) {
         const viewerUrl = popUrl(displayHost, options.port, options);
         console.log(viewerUrl);
         console.log(`Kennel is already running at ${viewerUrl}`);

package/dist/plugins/external.d.ts

@@ -26,6 +26,9 @@ export declare function readExternalPlugins(): ExternalPluginEntry[];
 export declare function installExternalPlugin(url: string, options?: {
     directory?: string;
 }): Promise<ExternalPluginEntry>;
+/** Identifies the installed plugin set, independent of the Node runtime. */
+export declare function hotKernelKey(plugins?: ExternalPluginEntry[]): string;
+/** Identifies a runtime-specific static kernel cache entry. */
 export declare function kernelKey(plugins?: ExternalPluginEntry[]): string;
 export type ActiveKernel = {
     buildIdentity: string;

package/dist/plugins/external.js

@@ -373,21 +373,33 @@ export async function installExternalPlugin(url, options = {}) {
 function cliRoot() {
     return resolve(dirname(fileURLToPath(import.meta.url)), "../..");
 }
+function kernelPlugins(plugins) {
+    return plugins.map((plugin) => ({
+        url: plugin.url,
+        requestedRef: plugin.requestedRef ?? null,
+        packageName: plugin.packageName,
+        id: plugin.id,
+        directory: plugin.directory ?? null,
+        commit: plugin.commit,
+        trigger: plugin.trigger,
+        entries: plugin.entries,
+    }));
+}
+/** Identifies the installed plugin set, independent of the Node runtime. */
+export function hotKernelKey(plugins = readExternalPlugins()) {
+    return hash(JSON.stringify({
+        buildIdentity: BUILD_IDENTITY,
+        schema: KENNEL_KERNEL_SCHEMA,
+        plugins: kernelPlugins(plugins),
+    }));
+}
+/** Identifies a runtime-specific static kernel cache entry. */
 export function kernelKey(plugins = readExternalPlugins()) {
     return hash(JSON.stringify({
         buildIdentity: BUILD_IDENTITY,
         schema: KENNEL_KERNEL_SCHEMA,
         runtime: BUILD_RUNTIME,
-        plugins: plugins.map((plugin) => ({
-            url: plugin.url,
-            requestedRef: plugin.requestedRef ?? null,
-            packageName: plugin.packageName,
-            id: plugin.id,
-            directory: plugin.directory ?? null,
-            commit: plugin.commit,
-            trigger: plugin.trigger,
-            entries: plugin.entries,
-        })),
+        plugins: kernelPlugins(plugins),
     }));
 }
 function kernelRoot(key) {

package/dist/site/hot-viewer.js

@@ -7,12 +7,15 @@ import { tmpdir } from 'node:os';
 import { dirname, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createKennelClient } from '../core/api-client.js';
+import { hotKernelKey, readExternalPlugins } from '../plugins/external.js';
 function sourceRoot() {
     return resolve(dirname(fileURLToPath(import.meta.url)), '../../..');
 }
 async function viewerStatus(url) {
     return createKennelClient({ baseUrl: url }).health({ signal: AbortSignal.timeout(1_000) })
-        .then((body) => body.viewer === 'kennel-vite' || body.viewer === 'kennel-core' ? 'running' : 'other')
+        .then((body) => body.viewer === 'kennel-vite' || body.viewer === 'kennel-core'
+        ? { viewer: body.viewer, kernelKey: body.kernelKey }
+        : 'other')
         .catch((error) => {
         // HTTP rejection means a different service owns the port; connection and
         // timeout failures mean the viewer is unavailable, so startup may retry.
@@ -20,17 +23,17 @@ async function viewerStatus(url) {
             ? 'other' : 'unavailable';
     });
 }
-async function viewerRunning(url, attempts = 1, waitOnOther = false) {
+async function runningViewer(url, attempts = 1, waitOnOther = false) {
     for (let attempt = 0; attempt < attempts; attempt += 1) {
         const status = await viewerStatus(url);
-        if (status === 'running')
-            return true;
+        if (typeof status === 'object')
+            return status;
         if (status === 'other' && !waitOnOther)
-            return false;
+            return undefined;
         if (attempt + 1 < attempts)
             await new Promise((done) => setTimeout(done, 250));
     }
-    return false;
+    return undefined;
 }
 async function portOpen(host, port) {
     return new Promise((done) => {
@@ -132,8 +135,20 @@ export async function hotViewer(options) {
         console.log(`bun ${[...args, ...(options.open ? ['--open', openPath] : [])].join(' ')}`);
         return;
     }
-    const status = await viewerStatus(url);
-    if (status === 'running') {
+    const plugins = readExternalPlugins();
+    // Must match the key apps/web/scripts/dev.mjs gives Vite as KENNEL_KERNEL_KEY.
+    const expectedKey = plugins.length > 0 ? hotKernelKey(plugins) : 'core';
+    // Reuse only a Vite viewer that serves the same plugin set. Anything else on
+    // the port is stale for this kernel and must be restarted, never reused.
+    const reuse = (running) => {
+        const restart = 'Stop that viewer (Ctrl+C in its terminal) and run this command again, or select another port.';
+        if (running.viewer !== 'kennel-vite') {
+            throw new Error(`Port ${options.port} runs the static Kennel viewer, not the hot viewer. ${restart}`);
+        }
+        if (running.kernelKey !== expectedKey) {
+            throw new Error(`The Kennel hot viewer on port ${options.port} uses kernel ${running.kernelKey}, `
+                + `but the installed plugins need kernel ${expectedKey}. ${restart}`);
+        }
         if (options.open) {
             // Do not stack another tab: the viewer is already open. Print the URL
             // so the caller can still get to it deliberately.
@@ -142,21 +157,19 @@ export async function hotViewer(options) {
         else {
             console.log('Kennel hot viewer is already running. Reusing it.');
         }
+    };
+    const status = await viewerStatus(url);
+    if (typeof status === 'object') {
+        reuse(status);
         return;
     }
     if (status === 'other') {
         throw new Error(`Port ${options.port} is used by another service. Stop it or select another port.`);
     }
     if (await portOpen(options.host, options.port)) {
-        if (await viewerRunning(url, 20, true)) {
-            if (options.open) {
-                // Do not stack another tab: the viewer is already open. Print the URL
-                // so the caller can still get to it deliberately.
-                console.log(`Kennel hot viewer is already running at ${viewerUrl}`);
-            }
-            else {
-                console.log('Kennel hot viewer is already running. Reusing it.');
-            }
+        const running = await runningViewer(url, 20, true);
+        if (running) {
+            reuse(running);
             return;
         }
         throw new Error(`Port ${options.port} is used by another service. Stop it or select another port.`);
@@ -164,15 +177,9 @@ export async function hotViewer(options) {
     const lock = startupLock(options.host, options.port);
     let token = await acquireLock(lock);
     if (!token) {
-        if (await viewerRunning(url, 40, true)) {
-            if (options.open) {
-                // Do not stack another tab: the viewer is already open. Print the URL
-                // so the caller can still get to it deliberately.
-                console.log(`Kennel hot viewer is already running at ${viewerUrl}`);
-            }
-            else {
-                console.log('Kennel hot viewer is already running. Reusing it.');
-            }
+        const running = await runningViewer(url, 40, true);
+        if (running) {
+            reuse(running);
             return;
         }
         await rm(lock, { force: true, recursive: true });
@@ -180,16 +187,10 @@ export async function hotViewer(options) {
     }
     if (!token)
         throw new Error(`Could not acquire the hot viewer startup lock for port ${options.port}.`);
-    if (await viewerRunning(url)) {
+    const running = await runningViewer(url);
+    if (running) {
         await releaseLock(lock, token);
-        if (options.open) {
-            // Do not stack another tab: the viewer is already open. Print the URL
-            // so the caller can still get to it deliberately.
-            console.log(`Kennel hot viewer is already running at ${viewerUrl}`);
-        }
-        else {
-            console.log('Kennel hot viewer is already running. Reusing it.');
-        }
+        reuse(running);
         return;
     }
     console.log(`bun ${args.join(' ')}`);
@@ -220,9 +221,15 @@ export async function hotViewer(options) {
                 done();
                 return;
             }
-            if (await viewerRunning(url, 20, true)) {
-                console.log('Kennel hot viewer is already running. Reusing it.');
-                done();
+            const existing = await runningViewer(url, 20, true);
+            if (existing) {
+                try {
+                    reuse(existing);
+                    done();
+                }
+                catch (error) {
+                    fail(error);
+                }
                 return;
             }
             fail(new Error(`Kennel hot viewer stopped with exit code ${code ?? 'unknown'}`));

package/dist/site/viewer.js

@@ -259,17 +259,15 @@ function tailscaleHost() {
 export async function viewer(input) {
     const portExplicit = viewerPortWasExplicit(input);
     const options = splitViewerArgs(input);
-    const { ensureKernel, readExternalPlugins } = await import("../plugins/external.js");
-    const externalPlugins = readExternalPlugins();
-    if (options.hot && externalPlugins.length === 0) {
+    if (options.hot) {
         const { hotViewer } = await import("./hot-viewer.js");
         await hotViewer(options);
         return;
     }
-    if (options.hot && externalPlugins.length > 0) {
-        console.log("Kennel hot viewer is disabled for external plugin kernels; using the composed static kernel.");
-    }
+    const { ensureKernel, hotKernelKey, readExternalPlugins } = await import("../plugins/external.js");
+    const externalPlugins = readExternalPlugins();
     const kernel = await ensureKernel(externalPlugins);
+    const viteKernelKey = externalPlugins.length > 0 ? hotKernelKey(externalPlugins) : "core";
     const web = kernel.webRoot;
     if (!existsSync(resolve(web, "index.html"))) {
         throw new Error(`Kennel web app not found. Run the CLI build first.`);
@@ -298,9 +296,16 @@ export async function viewer(input) {
             .join(",");
     const initialViewerUrl = `http://${options.host}:${options.port}`;
     const existing = await runningViewer(initialViewerUrl);
+    // A local Vite viewer is not root-restricted, so it can open any local
+    // folder. The static kennel-core viewer is root-scoped: reuse it only for
+    // its own root or a descendant.
     if (existing &&
-        existing.kernelKey === kernel.key &&
-        isSameOrDescendant(existing.root, options.root)) {
+        ((existing.viewer === "kennel-vite" &&
+            !remote &&
+            existing.kernelKey === viteKernelKey) ||
+            (existing.viewer !== "kennel-vite" &&
+                existing.kernelKey === kernel.key &&
+                isSameOrDescendant(existing.root, options.root)))) {
         const viewerUrl = popUrl(displayHost, options.port, options);
         console.log(viewerUrl);
         console.log(`Kennel is already running at ${viewerUrl}`);

package/kernel/apps/web/scripts/dev.mjs

@@ -5,6 +5,7 @@ import { dirname, join, resolve } from "node:path"
 import { fileURLToPath } from "node:url"
 
 import {
+  hotKernelKey,
   prepareExternalPluginModules,
   readExternalPlugins,
 } from "../../../cli/src/plugins/external.ts"
@@ -30,6 +31,9 @@ try {
       stdio: "inherit",
       env: {
         ...process.env,
+        // Reported by /api/health so the CLI reuses this viewer only for the
+        // same plugin set; "core" matches the CLI kernel without plugins.
+        KENNEL_KERNEL_KEY: plugins.length > 0 ? hotKernelKey(plugins) : "core",
         KENNEL_KERNEL_SOURCE_ROOT: workspace,
         KENNEL_HOST_NODE_MODULES: resolve(workspace, "cli/node_modules"),
         KENNEL_EXTERNAL_CLIENT_MODULE: modules.clientModule,

package/kernel/apps/web/src/api/events.ts

@@ -4,39 +4,75 @@ export function subscribeFolderEvent(
   folder: string | undefined,
   listener: () => void,
 ) {
-  return subscribeApiEvent(event, (message) => {
-    let data: unknown
-    try {
-      data = JSON.parse((message as MessageEvent<string>).data)
-    } catch {
-      return
-    }
-    if (
-      data &&
-      typeof data === "object" &&
-      "path" in data &&
-      data.path === folder
-    )
-      listener()
-  })
+  return subscribeApiEvent(
+    event,
+    (message) => {
+      let data: unknown
+      try {
+        data = JSON.parse((message as MessageEvent<string>).data)
+      } catch {
+        return
+      }
+      if (
+        data &&
+        typeof data === "object" &&
+        "path" in data &&
+        data.path === folder
+      )
+        listener()
+    },
+    listener,
+  )
+}
+
+type Subscription = {
+  event: string
+  listener: (event: Event) => void
+  resume: () => void
 }
 
 let source: EventSource | undefined
-let subscribers = 0
-/** Share one SSE connection across mounted views; browser reconnects automatically. */
+const subscriptions = new Set<Subscription>()
+
+function connect() {
+  if (source || document.visibilityState !== "visible") return
+  source = new EventSource("/api/events")
+  for (const { event, listener } of subscriptions) {
+    source.addEventListener(event, listener)
+  }
+}
+
+function visibilityChanged() {
+  if (document.visibilityState !== "visible") {
+    source?.close()
+    source = undefined
+    return
+  }
+  connect()
+  // Hidden tabs missed notifications. Refresh each subscriber on return.
+  for (const subscription of subscriptions) subscription.resume()
+}
+
+/** Hidden tabs must not consume the browser's per-origin HTTP/1 connection limit. */
 export function subscribeApiEvent(
   event: string,
   listener: (event: Event) => void,
+  resume = () => listener(new Event(event)),
 ) {
-  source ??= new EventSource("/api/events")
-  const current = source
-  subscribers++
-  current.addEventListener(event, listener)
+  const subscription = { event, listener, resume }
+  subscriptions.add(subscription)
+  if (subscriptions.size === 1) {
+    document.addEventListener("visibilitychange", visibilityChanged)
+  }
+  if (source) source.addEventListener(event, listener)
+  else connect()
   return () => {
-    current.removeEventListener(event, listener)
-    if (--subscribers === 0) {
-      current.close()
+    if (!subscriptions.delete(subscription)) return
+    source?.removeEventListener(event, listener)
+    if (subscriptions.size === 0) {
+      source?.close()
       source = undefined
+      document.removeEventListener("visibilitychange", visibilityChanged)
     }
   }
 }

package/kernel/apps/web/vite.config.ts

@@ -215,6 +215,8 @@ export default defineConfig({
     corePlugin({
       remoteAccess,
       restrictToRoot: remoteAccess,
+      // /api/health reports this name so the CLI reuses only a hot viewer.
+      viewerName: "kennel-vite",
       root: process.env.KENNEL_VIEWER_ROOT || root,
       // `kennel pop <file>` (hot) locks document reads to exactly this file;
       // the static viewer applies the same lock in-process.