extrojs 0.3.0 → 0.3.1

package/dist/plugin/emit-assets.d.ts

@@ -30,6 +30,12 @@ export interface AssetOptions {
 export interface Artifacts {
     manifest: ManifestV3;
     html: Partial<Record<RoutableSurface, string>>;
+    /**
+     * The dev probe (`extro-dev.js`) the dev shells load to reveal the
+     * offline screen when the dev server is unreachable. Absent in prod
+     * builds and when there are no HTML surfaces to probe for.
+     */
+    devProbe?: string;
 }
 /**
  * Pure projection from inputs to artifact strings: no filesystem access (the

package/dist/plugin/emit-assets.js

@@ -1,5 +1,5 @@
 import { generateManifest } from "./manifest.js";
-import { generateHTML } from "./generators/html.js";
+import { DEV_PROBE_FILE, generateDevProbe, generateHTML, } from "./generators/html.js";
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -11,14 +11,18 @@ import { generateHTML } from "./generators/html.js";
  */
 export function composeArtifacts(opts) {
     const manifest = generateManifest(opts);
+    const surfaces = Object.keys(opts.tree.surfaces);
     const html = {};
-    for (const surface of Object.keys(opts.tree.surfaces)) {
+    for (const surface of surfaces) {
         html[surface] = generateHTML({
             surface,
             dev: opts.dev ? { port: opts.dev.port } : undefined,
         });
     }
-    return { manifest, html };
+    const devProbe = opts.dev && surfaces.length > 0
+        ? generateDevProbe({ port: opts.dev.port })
+        : undefined;
+    return { manifest, html, devProbe };
 }
 /**
  * Canonical emission of Extro's static outputs (manifest + per-surface HTML).
@@ -30,8 +34,11 @@ export function composeArtifacts(opts) {
  * `viteBuild` already wrote them to disk).
  */
 export async function emitAssets(opts, emit) {
-    const { manifest, html } = composeArtifacts(opts);
+    const { manifest, html, devProbe } = composeArtifacts(opts);
     await emit("manifest.json", JSON.stringify(manifest, null, 2));
+    if (devProbe) {
+        await emit(DEV_PROBE_FILE, devProbe);
+    }
     for (const [surface, body] of Object.entries(html)) {
         if (!body)
             continue;

package/dist/plugin/generators/html.d.ts

@@ -4,13 +4,19 @@ interface GenerateHTMLOptions {
         port: number;
     };
 }
+/**
+ * The dev probe script emitted next to the HTML shells in the dev output
+ * dir. Referenced by the shells and reserved against Public assets, so the
+ * name lives here once.
+ */
+export declare const DEV_PROBE_FILE = "extro-dev.js";
 /**
  * @describe Generates the HTML shell for a surface. In dev mode, the shell
  * points at the Vite dev server (with @vite/client for HMR) instead of the
- * built bundle, and pre-renders a brand-styled "dev server offline" screen
- * inside #root. React's createRoot replaces #root's children on mount, so
- * the screen vanishes on a normal start; if the dev server never comes up,
- * the screen stays visible.
+ * built bundle, and carries a hidden brand-styled "dev server offline"
+ * screen inside #root. The probe script (generateDevProbe) reveals it only
+ * when the dev server is unreachable; on a normal start it never paints,
+ * and React's createRoot replaces #root's children on mount.
  */
 export declare function generateHTML({ surface, dev }: GenerateHTMLOptions): string;
 export interface DevScreen {
@@ -23,17 +29,36 @@ export interface DevScreen {
      * (popup), the screen sizes to content with a fixed minimum.
      */
     fill?: boolean;
+    /**
+     * When true, the screen ships with the `hidden` attribute and stays out
+     * of the first paint until something removes it (the dev probe, for the
+     * offline screen).
+     */
+    hidden?: boolean;
 }
 /**
  * @describe Renders a brand-styled "developer screen" card. Used as the
  * pre-render inside #root for offline-dev-server fallback today, intended
  * for reuse in other build-time / runtime dev panels.
  */
-export declare const renderDevScreen: ({ title, body, fill }: DevScreen) => string;
+export declare const renderDevScreen: ({ title, body, fill, hidden, }: DevScreen) => string;
 /**
  * @describe Global styles for any `.extro-dev-screen` rendered in dev. Body
- * is painted dark only while a screen is in the DOM (via `:has()`), so the
- * user's app reverts to default styling once React mounts.
+ * is painted dark only while a visible screen is in the DOM (via `:has()`),
+ * so the user's app keeps default styling both before React mounts (screen
+ * still hidden) and after (screen wiped from #root).
  */
 export declare const devScreenStyles: () => string;
+/**
+ * @describe Generates the dev probe (`extro-dev.js`), emitted into the dev
+ * output dir next to the HTML shells. MV3 CSP bans inline scripts but allows
+ * 'self', so the probe loads from the extension origin and runs even when
+ * the Vite dev server is down. It reveals the hidden offline screen only
+ * when the @vite/client script fails to fetch, the one unambiguous signal
+ * that the server is unreachable; a failing user module while the server is
+ * up stays Vite's error overlay's problem.
+ */
+export declare const generateDevProbe: ({ port }: {
+    port: number;
+}) => string;
 export {};

package/dist/plugin/generators/html.js

@@ -1,15 +1,22 @@
+/**
+ * The dev probe script emitted next to the HTML shells in the dev output
+ * dir. Referenced by the shells and reserved against Public assets, so the
+ * name lives here once.
+ */
+export const DEV_PROBE_FILE = "extro-dev.js";
 /**
  * @describe Generates the HTML shell for a surface. In dev mode, the shell
  * points at the Vite dev server (with @vite/client for HMR) instead of the
- * built bundle, and pre-renders a brand-styled "dev server offline" screen
- * inside #root. React's createRoot replaces #root's children on mount, so
- * the screen vanishes on a normal start; if the dev server never comes up,
- * the screen stays visible.
+ * built bundle, and carries a hidden brand-styled "dev server offline"
+ * screen inside #root. The probe script (generateDevProbe) reveals it only
+ * when the dev server is unreachable; on a normal start it never paints,
+ * and React's createRoot replaces #root's children on mount.
  */
 export function generateHTML({ surface, dev }) {
     const title = surface.charAt(0).toUpperCase() + surface.slice(1);
     const scripts = dev
         ? `
+      <script src="./${DEV_PROBE_FILE}"></script>
       <script type="module" src="http://localhost:${dev.port}/@vite/client"></script>
       <script type="module" src="http://localhost:${dev.port}/@id/@vitejs/plugin-react/preamble"></script>
       <script type="module" src="http://localhost:${dev.port}/@id/virtual:extro/runtime/${surface}"></script>
@@ -25,6 +32,10 @@ export function generateHTML({ surface, dev }) {
             // Popups size to content (no viewport to fill); everything else
             // (options/sidepanel/tab) gets a full-viewport centered layout.
             fill: surface !== "popup",
+            // Hidden until the probe proves the dev server is down, so a normal
+            // start never paints it (the screen used to flash for the moment
+            // between document load and React mount).
+            hidden: true,
         })
         : "";
     return `
@@ -46,10 +57,10 @@ export function generateHTML({ surface, dev }) {
  * pre-render inside #root for offline-dev-server fallback today, intended
  * for reuse in other build-time / runtime dev panels.
  */
-export const renderDevScreen = ({ title, body, fill = false }) => {
+export const renderDevScreen = ({ title, body, fill = false, hidden = false, }) => {
     const cls = `extro-dev-screen${fill ? " extro-dev-screen--fill" : ""}`;
     return `
-<div class="${cls}">
+<div class="${cls}"${hidden ? " hidden" : ""}>
   <div class="extro-dev-screen__card">
     <span class="extro-dev-screen__tag">EXTRO</span>
     <h1>${title}</h1>
@@ -60,13 +71,14 @@ export const renderDevScreen = ({ title, body, fill = false }) => {
 };
 /**
  * @describe Global styles for any `.extro-dev-screen` rendered in dev. Body
- * is painted dark only while a screen is in the DOM (via `:has()`), so the
- * user's app reverts to default styling once React mounts.
+ * is painted dark only while a visible screen is in the DOM (via `:has()`),
+ * so the user's app keeps default styling both before React mounts (screen
+ * still hidden) and after (screen wiped from #root).
  */
 export const devScreenStyles = () => `
 <style>
   body { margin: 0; }
-  body:has(.extro-dev-screen) { background: #0a0a0a; }
+  body:has(.extro-dev-screen:not([hidden])) { background: #0a0a0a; }
   .extro-dev-screen {
     box-sizing: border-box;
     min-width: 360px;
@@ -77,7 +89,10 @@ export const devScreenStyles = () => `
     align-items: center;
     justify-content: center;
     opacity: 0;
-    animation: extro-dev-screen-in 0.18s 0.05s forwards;
+    animation: extro-dev-screen-in 0.18s forwards;
+  }
+  .extro-dev-screen[hidden] {
+    display: none;
   }
   .extro-dev-screen--fill {
     min-height: 100vh;
@@ -125,3 +140,28 @@ export const devScreenStyles = () => `
   @keyframes extro-dev-screen-in { to { opacity: 1; } }
 </style>
 `.trim();
+/**
+ * @describe Generates the dev probe (`extro-dev.js`), emitted into the dev
+ * output dir next to the HTML shells. MV3 CSP bans inline scripts but allows
+ * 'self', so the probe loads from the extension origin and runs even when
+ * the Vite dev server is down. It reveals the hidden offline screen only
+ * when the @vite/client script fails to fetch, the one unambiguous signal
+ * that the server is unreachable; a failing user module while the server is
+ * up stays Vite's error overlay's problem.
+ */
+export const generateDevProbe = ({ port }) => `
+// Generated by Extro. Reveals the "dev server isn't running" screen when
+// the Vite dev server can't be reached. Script fetch errors don't bubble,
+// hence the capture-phase listener; this classic script runs before the
+// module scripts below it can fail.
+window.addEventListener(
+  "error",
+  (event) => {
+    const el = event.target;
+    if (!(el instanceof HTMLScriptElement)) return;
+    if (el.src !== "http://localhost:${port}/@vite/client") return;
+    document.querySelector(".extro-dev-screen")?.removeAttribute("hidden");
+  },
+  true,
+);
+`.trimStart();

package/dist/plugin/public.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { DEV_PROBE_FILE } from "./generators/html.js";
 /**
  * @file public.ts
  * @description Discovers Public assets (static files under the project-root
@@ -31,6 +32,11 @@ function walk(dir, base) {
 function isReservedName(name, tree) {
     if (name === "manifest.json")
         return true;
+    // Dev-only output, but reserved in all modes so the partition (and the
+    // web_accessible_resources list derived from it) doesn't depend on the
+    // build mode.
+    if (name === DEV_PROBE_FILE)
+        return true;
     if (name === "icons" || name.startsWith("icons/"))
         return true;
     for (const surface of Object.keys(tree.surfaces)) {

package/dist/router/link.d.ts

@@ -15,6 +15,7 @@ interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href"
 export declare const Link: ({ href, replace, onClick, ...rest }: LinkProps) => import("react").DetailedReactHTMLElement<{
     content?: string | undefined | undefined;
     title?: string | undefined | undefined;
+    hidden?: boolean | undefined | undefined;
     type?: string | undefined | undefined;
     slot?: string | undefined | undefined;
     style?: import("react").CSSProperties | undefined;
@@ -39,7 +40,6 @@ export declare const Link: ({ href, replace, onClick, ...rest }: LinkProps) => i
     dir?: string | undefined | undefined;
     draggable?: (boolean | "true" | "false") | undefined;
     enterKeyHint?: "enter" | "done" | "go" | "next" | "previous" | "search" | "send" | undefined | undefined;
-    hidden?: boolean | undefined | undefined;
     id?: string | undefined | undefined;
     lang?: string | undefined | undefined;
     nonce?: string | undefined | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "extrojs",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Next.js for Chrome extensions. File-based entrypoints, automatic Manifest V3 generation, and React routing in a single Vite-powered CLI.",
   "keywords": [
     "extro",