proto-plugin 0.1.8 → 0.1.10

package/README.md

@@ -56,7 +56,17 @@ export default page.default;
 export const generateStaticParams = page.generateStaticParams;
 ```
 
-4. **Next.js config** — transpile the package (use a relative import so CSS is not loaded during config evaluation):
+4. **Component library** — `src/app/component-library/page.tsx` (created automatically on `pnpm install` if missing; or run `pnpm --dir node_modules/proto-plugin setup-host`):
+
+```tsx
+import { createPrototypeComponentLibraryPage } from "proto-plugin";
+
+export default createPrototypeComponentLibraryPage();
+```
+
+Pass `children` once you've synced UI from source. Until then, the page shows an empty state with a copyable agent prompt.
+
+5. **Next.js config** — transpile the package (use a relative import so CSS is not loaded during config evaluation):
 
 ```ts
 import { withPrototype } from "./packages/prototype/src/config/with-prototype";
@@ -64,7 +74,7 @@ import { withPrototype } from "./packages/prototype/src/config/with-prototype";
 export default withPrototype({ nextConfig: { /* … */ } });
 ```
 
-5. **Tailwind** — scan prototype package components from the host `globals.css`. Register semantic `--color-*` tokens as self-referential vars so utilities like `text-muted-foreground` resolve from `[data-prototype-root]` at runtime — **do not** map `--color-foreground` / `--color-background` to product `:root` tokens (that breaks gallery contrast):
+6. **Tailwind** — scan prototype package components from the host `globals.css`. Register semantic `--color-*` tokens as self-referential vars so utilities like `text-muted-foreground` resolve from `[data-prototype-root]` at runtime — **do not** map `--color-foreground` / `--color-background` to product `:root` tokens (that breaks gallery contrast):
 
 ```css
 @import "tailwindcss";
@@ -79,7 +89,7 @@ export default withPrototype({ nextConfig: { /* … */ } });
 
 Product tokens use separate names (e.g. `--product-background`) scoped to `[data-prototype-screenshot]`.
 
-6. **Root layout + tool themes** — wrap routes with `createPrototypeSiteLayout()` and import package chrome CSS (dark/light themes live here, not in host `globals.css`):
+7. **Root layout + tool themes** — wrap routes with `createPrototypeSiteLayout()` and import package chrome CSS (dark/light themes live here, not in host `globals.css`):
 
 ```tsx
 import { createPrototypeSiteLayout } from "proto-plugin";
@@ -89,7 +99,7 @@ import "./globals.css";
 const PrototypeSiteLayout = createPrototypeSiteLayout();
 ```
 
-7. **tsconfig paths** (optional, for tool internal `@prototype/*` alias when developing the package):
+8. **tsconfig paths** (optional, for tool internal `@prototype/*` alias when developing the package):
 
 ```json
 {
@@ -102,7 +112,7 @@ const PrototypeSiteLayout = createPrototypeSiteLayout();
 }
 ```
 
-8. **Dev server port** — run the host on port **1985** so it stays separate from a typical source app on 3000. In the host `package.json`:
+9. **Dev server port** — run the host on port **1985** so it stays separate from a typical source app on 3000. In the host `package.json`:
 
 ```json
 {
@@ -120,6 +130,7 @@ Open [http://localhost:1985](http://localhost:1985) when developing.
 | --- | --- |
 | `definePrototypeConfig` | Register prototypes (sets global config as a side effect) |
 | `createPrototypePage` | Factory for `/prototypes/[slug]` page + `generateStaticParams` |
+| `createPrototypeComponentLibraryPage` | Factory for `/component-library` (empty state until host passes `children`) |
 | `createPrototypeRegistry` | Server helpers: `getAllPrototypes`, `getPrototype`, … |
 | `PrototypeComponent`, `PrototypeControl` | Comment-anchorable UI wrappers |
 | `PrototypeShell` | Review chrome (comments sidebar, screenshot capture) |
@@ -261,16 +272,17 @@ Follow the package README (`node_modules/proto-plugin/README.md`) and implement
 1. **`prototype.config.ts`** at the repo root — start with an empty `prototypes: []` array using `definePrototypeConfig` from `proto-plugin`.
 2. **Gallery home** — `src/app/page.tsx` via `createPrototypeGalleryPage(prototypeConfig)`.
 3. **Prototype route** — `src/app/prototypes/[slug]/page.tsx` via `createPrototypePage(prototypeConfig)` (export `default` + `generateStaticParams`).
-4. **Root layout** — wrap children with `createPrototypeSiteLayout()` from `proto-plugin` in `src/app/layout.tsx`, and import the tool chrome theme:
+4. **Component library** — `src/app/component-library/page.tsx` via `createPrototypeComponentLibraryPage()` (auto-scaffolded on `pnpm install` if missing; shows empty state + copyable populate prompt until synced UI is wired as `children`).
+5. **Root layout** — wrap children with `createPrototypeSiteLayout()` from `proto-plugin` in `src/app/layout.tsx`, and import the tool chrome theme:
 
    ```tsx
    import { createPrototypeSiteLayout } from "proto-plugin";
    import "proto-plugin/styles/globals.css";
    import "./globals.css";
    ```
-5. **API catch-all** — `src/app/api/[...path]/route.ts` using `createPrototypeApiRoute(prototypeConfig)` from `proto-plugin/server`; export `GET`, `POST`, and `PUT` handlers that call `dispatch`.
-6. **`next.config.ts`** — wrap with `withPrototype` from `proto-plugin/with-prototype` and ensure `proto-plugin` is transpiled.
-7. **`src/app/globals.css`** — Tailwind v4 + product tokens synced from source. **Do not** put tool chrome dark/light mode here (no `prefers-color-scheme`, no hardcoded gallery colors). Scan package components:
+6. **API catch-all** — `src/app/api/[...path]/route.ts` using `createPrototypeApiRoute(prototypeConfig)` from `proto-plugin/server`; export `GET`, `POST`, and `PUT` handlers that call `dispatch`.
+7. **`next.config.ts`** — wrap with `withPrototype` from `proto-plugin/with-prototype` and ensure `proto-plugin` is transpiled.
+8. **`src/app/globals.css`** — Tailwind v4 + product tokens synced from source. **Do not** put tool chrome dark/light mode here (no `prefers-color-scheme`, no hardcoded gallery colors). Scan package components:
 
    ```css
    @import "tailwindcss";
@@ -279,7 +291,7 @@ Follow the package README (`node_modules/proto-plugin/README.md`) and implement
 
    Tool themes live in `proto-plugin/styles/globals.css` (import in layout). The package toggles dark/light on `[data-prototype-root]` via `data-prototype-comment-theme`.
 
-8. **`package.json` scripts** — set dev to port 1985 and forward CLI commands to the installed package:
+9. **`package.json` scripts** — set dev to port 1985 and forward CLI commands to the installed package:
 
    ```json
    {
@@ -292,9 +304,9 @@ Follow the package README (`node_modules/proto-plugin/README.md`) and implement
    }
    ```
 
-9. **`.env.example` and `.env.local`** — document and set `SOURCE_PATH` to the source app path I provided. Add comment/screenshot storage vars only if I asked for them in step 5 — the app should run without them, but comments won't persist.
+10. **`.env.example` and `.env.local`** — document and set `SOURCE_PATH` to the source app path I provided. Add comment/screenshot storage vars only if I asked for them in step 5 — the app should run without them, but comments won't persist.
 
-Run `pnpm dev` and confirm [http://localhost:1985](http://localhost:1985) shows the empty gallery and the app builds cleanly before continuing.
+Run `pnpm dev` and confirm [http://localhost:1985](http://localhost:1985) shows the empty gallery, `/component-library` renders (empty state is fine), and the app builds cleanly before continuing.
 
 ## 3. Link the source app
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proto-plugin",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "type": "module",
   "publishConfig": {
     "registry": "https://registry.npmjs.org"
@@ -31,6 +31,8 @@
     "./styles/globals.css": "./src/styles/globals.css"
   },
   "scripts": {
+    "postinstall": "node scripts/ensure-component-library-page.mjs",
+    "setup-host": "node scripts/ensure-component-library-page.mjs",
     "verify:prototype-ids": "node scripts/verify-prototype-component-ids.mjs",
     "verify:prototype-preview-states": "node scripts/verify-prototype-preview-states.mjs",
     "link-source": "./scripts/link-source.sh",

package/scripts/ensure-component-library-page.mjs

@@ -0,0 +1,89 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { resolveHostRoot } from "./lib/resolve-host-root.mjs";
+
+const PAGE_CONTENT = `import { createPrototypeComponentLibraryPage } from "proto-plugin";
+
+// Scaffolded by proto-plugin — pass \`children\` once you've synced UI from source.
+export default createPrototypeComponentLibraryPage();
+`;
+
+function resolveAppDir(hostRoot) {
+  const srcApp = path.join(hostRoot, "src", "app");
+  if (fs.existsSync(srcApp)) {
+    return srcApp;
+  }
+
+  const app = path.join(hostRoot, "app");
+  if (fs.existsSync(app)) {
+    return app;
+  }
+
+  return null;
+}
+
+function isPrototypeHost(hostRoot) {
+  if (fs.existsSync(path.join(hostRoot, "prototype.config.ts"))) {
+    return true;
+  }
+
+  const packageJsonPath = path.join(hostRoot, "package.json");
+  if (!fs.existsSync(packageJsonPath)) {
+    return false;
+  }
+
+  try {
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+    const deps = {
+      ...packageJson.dependencies,
+      ...packageJson.devDependencies,
+    };
+    return Boolean(deps["proto-plugin"]);
+  } catch {
+    return false;
+  }
+}
+
+export function ensureComponentLibraryPage(hostRoot) {
+  if (!isPrototypeHost(hostRoot)) {
+    return { created: false, reason: "not-a-prototype-host" };
+  }
+
+  const appDir = resolveAppDir(hostRoot);
+  if (!appDir) {
+    return { created: false, reason: "missing-app-dir" };
+  }
+
+  const pageDir = path.join(appDir, "component-library");
+  const pagePath = path.join(pageDir, "page.tsx");
+
+  if (fs.existsSync(pagePath)) {
+    return { created: false, reason: "already-exists", pagePath };
+  }
+
+  fs.mkdirSync(pageDir, { recursive: true });
+  fs.writeFileSync(pagePath, PAGE_CONTENT, "utf8");
+
+  return { created: true, pagePath };
+}
+
+function main() {
+  const toolRoot = path.resolve(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "..",
+  );
+  const hostRoot = resolveHostRoot(toolRoot);
+  const result = ensureComponentLibraryPage(hostRoot);
+
+  if (result.created) {
+    console.log(
+      `proto-plugin: created component library route at ${path.relative(hostRoot, result.pagePath)}`,
+    );
+  }
+}
+
+if (import.meta.url === new URL(process.argv[1], "file:").href) {
+  main();
+}

package/scripts/link-source.sh

@@ -38,3 +38,5 @@ fi
 
 ln -s "$TARGET" "$LINK"
 echo "Linked source/ -> $TARGET"
+
+node "$TOOL_ROOT/scripts/ensure-component-library-page.mjs"

package/src/app.ts

@@ -2,3 +2,4 @@ import "server-only";
 
 export { createPrototypeGalleryPage } from "./config/create-prototype-gallery-page";
 export { createPrototypeCatchAllPage } from "./config/create-prototype-host-app";
+export { createPrototypeComponentLibraryPage } from "./config/create-prototype-component-library-page";

package/src/components/shell/prototype-plugin-update-popup.tsx

@@ -3,72 +3,84 @@
 import { Button } from "@prototype/components/ui/button";
 import { buildUpgradeProtoPluginCopyText } from "@prototype/lib/prototypes/upgrade-proto-plugin-prompt";
 import { useProtoPluginVersionCheck } from "@prototype/lib/prototypes/use-proto-plugin-version-check";
+import { useActivePrototypeToolTheme } from "@prototype/lib/prototypes/use-prototype-tool-theme";
 import useCopyToClipboard from "@prototype/lib/use-copy-to-clipboard";
 import { cn } from "@prototype/lib/utils";
 import { X } from "lucide-react";
+import { useEffect, useState } from "react";
+import { createPortal } from "react-dom";
 import { toast } from "sonner";
 
 export function PrototypePluginUpdatePopup() {
   const { status, shouldShowPopup, dismiss } = useProtoPluginVersionCheck();
   const { copy, icon, isCopied } = useCopyToClipboard();
+  const theme = useActivePrototypeToolTheme();
+  const [mounted, setMounted] = useState(false);
 
-  if (!shouldShowPopup || !status?.installed || !status.latest) {
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  if (!shouldShowPopup || !status?.installed || !status.latest || !mounted) {
     return null;
   }
 
-  const handleCopy = async () => {
+  const handleCopyPrompt = async () => {
     try {
       await copy(
         buildUpgradeProtoPluginCopyText({
-          installed: status.installed!,
-          latest: status.latest!,
+          installed: status.installed,
+          latest: status.latest,
         }),
       );
     } catch {
       toast.error("Copy error", {
-        description: "Failed to copy upgrade prompt",
+        description: "Failed to copy update prompt",
       });
     }
   };
 
-  return (
+  return createPortal(
     <div
-      role="status"
-      aria-live="polite"
-      className={cn(
-        "border-border bg-card ring-border pointer-events-auto fixed bottom-4 left-4 z-[1050] flex w-[min(20rem,calc(100vw-2rem))] flex-col gap-3 rounded-xl border p-4 shadow-lg ring-[0.5px]",
-      )}
+      data-prototype-root
+      data-prototype-comment-theme={theme}
+      className="pointer-events-none fixed bottom-4 right-4 z-[1050] !bg-transparent"
     >
-      <div className="flex items-start justify-between gap-2">
-        <div className="min-w-0 flex-1">
-          <p className="text-sm font-medium text-foreground">Update proto-plugin</p>
-          <p className="mt-1 text-sm text-muted-foreground">
-            v{status.latest} is available. You&apos;re on v{status.installed}.
-          </p>
-        </div>
+      <div
+        role="status"
+        aria-live="polite"
+        className={cn(
+          "pointer-events-auto relative flex w-[15rem] flex-col gap-3 rounded-lg bg-[var(--tool-chrome-surface)] p-4 shadow-md ring-[0.5px] ring-[var(--tool-chrome-border)]",
+        )}
+      >
         <button
           type="button"
           aria-label="Dismiss update notification"
-          className="text-muted-foreground hover:text-foreground shrink-0 rounded p-1 transition-colors duration-200 ease"
+          className="absolute right-2 top-2 rounded p-1 text-[var(--tool-chrome-text-muted)] transition-colors duration-200 ease hover:text-[var(--tool-chrome-text-heading)]"
           onClick={dismiss}
         >
-          <X size={14} />
+          <X size={12} />
         </button>
-      </div>
 
-      <Button
-        type="button"
-        variant="outline"
-        size="sm"
-        className="h-8 w-fit cursor-pointer gap-1.5"
-        onClick={() => {
-          void handleCopy();
-        }}
-        aria-label="Copy upgrade prompt"
-      >
-        {isCopied ? "Copied prompt" : "Copy prompt"}
-        {icon}
-      </Button>
-    </div>
+        <p className="pr-4 text-xs leading-relaxed text-[var(--tool-chrome-text-muted)]">
+          A new version of Proto is available, copy the prompt below into your agent to update
+        </p>
+
+        <Button
+          type="button"
+          variant="chrome"
+          size="sm"
+          className="h-7 w-fit cursor-pointer gap-1 px-2 text-[11px]"
+          onClick={() => {
+            void handleCopyPrompt();
+          }}
+          aria-label="Copy update prompt"
+        >
+          {isCopied ? "Copied update prompt" : "Copy update prompt"}
+          {icon}
+        </Button>
+      </div>
+    </div>,
+    document.body,
   );
 }

package/src/config/create-prototype-host-app.tsx

@@ -10,9 +10,12 @@ import type {
   PrototypeExtraRoute,
 } from "@prototype/lib/prototypes/prototype-config-types";
 
+import { createPrototypeComponentLibraryPage } from "./create-prototype-component-library-page";
 import { createPrototypePage } from "./create-prototype-page";
 import { createPrototypeStateMapPage } from "./create-prototype-state-map-page";
 
+const ComponentLibraryPage = createPrototypeComponentLibraryPage();
+
 function matchExtraRoute(
   path: string[],
   pattern: string[],
@@ -61,7 +64,11 @@ export function createPrototypeCatchAllPage(config: PrototypeConfig) {
       path: ["prototypes", slug, "states"],
     }));
 
-    return [...prototypePaths, ...stateMapPaths];
+    return [
+      { path: ["component-library"] },
+      ...prototypePaths,
+      ...stateMapPaths,
+    ];
   }
 
   async function CatchAllPage({
@@ -71,6 +78,10 @@ export function createPrototypeCatchAllPage(config: PrototypeConfig) {
   }) {
     const { path = [] } = await params;
 
+    if (path.length === 1 && path[0] === "component-library") {
+      return <ComponentLibraryPage />;
+    }
+
     if (path.length === 2 && path[0] === "prototypes") {
       const slug = path[1]!;
       return prototypePage.default({ params: Promise.resolve({ slug }) });

package/src/config/prototype-site-layout-client.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import { PrototypeProvider } from "@prototype/components/prototype-provider";
 import { PrototypePluginUpdatePopup } from "@prototype/components/shell/prototype-plugin-update-popup";
 import { usePathname } from "next/navigation";
 import type { ComponentType, ReactNode } from "react";
@@ -29,7 +30,7 @@ export function PrototypeSiteLayoutClient({
 
   if (isGalleryRoute) {
     return (
-      <div className="bg-[var(--bg-main)] flex h-svh min-h-svh w-full flex-col overflow-hidden">
+      <PrototypeProvider className="bg-[var(--bg-main)] flex h-svh min-h-svh w-full flex-col overflow-hidden">
         <GalleryShell
           sourceDirectoryName={sourceDirectoryName}
           sourcePath={sourcePath}
@@ -38,15 +39,15 @@ export function PrototypeSiteLayoutClient({
         </GalleryShell>
         <PrototypePluginUpdatePopup />
         {toaster}
-      </div>
+      </PrototypeProvider>
     );
   }
 
   return (
-    <div className="bg-[var(--bg-ground)] flex h-svh overflow-hidden">
+    <PrototypeProvider className="bg-[var(--bg-ground)] flex h-svh overflow-hidden">
       {children}
       <PrototypePluginUpdatePopup />
       {toaster}
-    </div>
+    </PrototypeProvider>
   );
 }

package/src/lib/prototypes/proto-plugin-semver.ts

@@ -0,0 +1,18 @@
+export function isNewerProtoPluginVersion(latest: string, installed: string): boolean {
+  const latestParts = parseSemver(latest);
+  const installedParts = parseSemver(installed);
+  if (!latestParts || !installedParts) return false;
+
+  for (let index = 0; index < 3; index += 1) {
+    if (latestParts[index]! > installedParts[index]!) return true;
+    if (latestParts[index]! < installedParts[index]!) return false;
+  }
+
+  return false;
+}
+
+function parseSemver(version: string): [number, number, number] | null {
+  const match = /^(\d+)\.(\d+)\.(\d+)/.exec(version.trim());
+  if (!match) return null;
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}

package/src/lib/prototypes/proto-plugin-version.ts

@@ -1,3 +1,5 @@
+import { isNewerProtoPluginVersion } from "@prototype/lib/prototypes/proto-plugin-semver";
+
 export type ProtoPluginVersionStatus = {
   installed: string | null;
   latest: string | null;
@@ -8,12 +10,73 @@ export type ProtoPluginVersionStatus = {
 
 export const PROTOTYPE_PLUGIN_VERSION_PATH = "/api/proto-plugin/version";
 
+const NPM_LATEST_URL = "https://registry.npmjs.org/proto-plugin/latest";
+
+type NpmLatestResponse = {
+  version?: string;
+  repository?: { url?: string };
+};
+
+function normalizeRepositoryUrl(url: string | undefined): string | undefined {
+  return url?.replace(/^git\+/, "").replace(/\.git$/, "");
+}
+
+async function fetchLatestFromNpmRegistry(): Promise<{
+  latest: string | null;
+  repositoryUrl?: string;
+}> {
+  try {
+    const response = await fetch(NPM_LATEST_URL, { cache: "no-store" });
+    if (!response.ok) {
+      return { latest: null };
+    }
+
+    const data = (await response.json()) as NpmLatestResponse;
+    return {
+      latest: data.version ?? null,
+      repositoryUrl: normalizeRepositoryUrl(data.repository?.url),
+    };
+  } catch {
+    return { latest: null };
+  }
+}
+
+/** Client-side npm check when the server route is stale (older plugin releases cached npm for 1h). */
+async function reconcileWithNpmRegistry(
+  status: ProtoPluginVersionStatus,
+): Promise<ProtoPluginVersionStatus> {
+  if (status.isWorkspaceLink || !status.installed) {
+    return status;
+  }
+
+  if (
+    status.updateAvailable &&
+    status.latest &&
+    isNewerProtoPluginVersion(status.latest, status.installed)
+  ) {
+    return status;
+  }
+
+  const { latest, repositoryUrl } = await fetchLatestFromNpmRegistry();
+  if (!latest || !isNewerProtoPluginVersion(latest, status.installed)) {
+    return status;
+  }
+
+  return {
+    ...status,
+    latest,
+    updateAvailable: true,
+    repositoryUrl: repositoryUrl ?? status.repositoryUrl,
+  };
+}
+
 export async function fetchProtoPluginVersionStatus(): Promise<ProtoPluginVersionStatus> {
-  const response = await fetch(PROTOTYPE_PLUGIN_VERSION_PATH);
+  const response = await fetch(PROTOTYPE_PLUGIN_VERSION_PATH, { cache: "no-store" });
 
   if (!response.ok) {
     throw new Error("Failed to check proto-plugin version.");
   }
 
-  return (await response.json()) as ProtoPluginVersionStatus;
+  const status = (await response.json()) as ProtoPluginVersionStatus;
+  return reconcileWithNpmRegistry(status);
 }

package/src/lib/prototypes/upgrade-proto-plugin-prompt.ts

@@ -38,3 +38,9 @@ export function buildUpgradeProtoPluginCopyText(
 ): string {
   return buildUpgradeProtoPluginPrompt(options);
 }
+
+export function buildUpgradeProtoPluginCommand({
+  latest,
+}: Pick<UpgradeProtoPluginPromptOptions, "latest">): string {
+  return `pnpm add proto-plugin@${latest}`;
+}

package/src/lib/prototypes/use-proto-plugin-version-check.ts

@@ -8,12 +8,20 @@ import { usePersistedLocalString } from "@prototype/lib/prototypes/use-persisted
 import { useCallback, useEffect, useMemo, useState } from "react";
 
 const DISMISSED_VERSION_KEY = "prototype-review:global:dismissed-plugin-version";
+const PREVIEW_PLUGIN_UPDATE_PARAM = "previewPluginUpdate";
+
+function readPreviewPluginUpdateParam(): boolean {
+  if (process.env.NODE_ENV !== "development") return false;
+  if (typeof window === "undefined") return false;
+  return new URLSearchParams(window.location.search).has(PREVIEW_PLUGIN_UPDATE_PARAM);
+}
 
 export function useProtoPluginVersionCheck() {
   const [status, setStatus] = useState<ProtoPluginVersionStatus | null>(null);
   const [isLoading, setIsLoading] = useState(true);
   const { value: dismissedVersion, updateValue: setDismissedVersion } =
     usePersistedLocalString(DISMISSED_VERSION_KEY, "");
+  const forcePreview = readPreviewPluginUpdateParam();
 
   useEffect(() => {
     let cancelled = false;
@@ -46,7 +54,35 @@ export function useProtoPluginVersionCheck() {
     }
   }, [setDismissedVersion, status?.latest]);
 
+  const previewStatus = useMemo<ProtoPluginVersionStatus | null>(() => {
+    if (!forcePreview) return null;
+
+    const installed = status?.installed ?? "0.1.7";
+    let latest = status?.latest ?? "0.1.9";
+
+    if (latest === installed) {
+      const match = /^(\d+)\.(\d+)\.(\d+)/.exec(installed);
+      latest = match
+        ? `${match[1]}.${match[2]}.${Number(match[3]) + 1}`
+        : "0.1.9";
+    }
+
+    return {
+      installed,
+      latest,
+      updateAvailable: true,
+      isWorkspaceLink: false,
+      repositoryUrl: status?.repositoryUrl,
+    };
+  }, [forcePreview, status]);
+
+  const effectiveStatus = previewStatus ?? status;
+
   const shouldShowPopup = useMemo(() => {
+    if (forcePreview) {
+      return Boolean(effectiveStatus?.installed && effectiveStatus.latest);
+    }
+
     if (isLoading || !status?.updateAvailable || !status.latest || !status.installed) {
       return false;
     }
@@ -56,10 +92,10 @@ export function useProtoPluginVersionCheck() {
     }
 
     return dismissedVersion !== status.latest;
-  }, [dismissedVersion, isLoading, status]);
+  }, [dismissedVersion, effectiveStatus, forcePreview, isLoading, status]);
 
   return {
-    status,
+    status: effectiveStatus,
     shouldShowPopup,
     dismiss,
     isLoading,

package/src/lib/prototypes/use-prototype-tool-theme.tsx

@@ -7,7 +7,9 @@ import {
   createContext,
   useCallback,
   useContext,
+  useEffect,
   useMemo,
+  useState,
   type ReactNode,
 } from "react";
 
@@ -113,3 +115,37 @@ export function usePrototypeToolTheme(): PrototypeToolThemeContextValue {
 
   return context;
 }
+
+function readActivePrototypeToolTheme(): PrototypeToolTheme {
+  if (typeof document === "undefined") return DEFAULT_THEME;
+
+  const roots = document.querySelectorAll<HTMLElement>("[data-prototype-root]");
+  const activeRoot = roots[roots.length - 1] ?? roots[0];
+  return normalizeTheme(activeRoot?.getAttribute("data-prototype-comment-theme") ?? DEFAULT_THEME);
+}
+
+/** Syncs with the innermost tool theme root (e.g. portaled UI outside nested providers). */
+export function useActivePrototypeToolTheme(): PrototypeToolTheme {
+  const { theme: contextTheme } = usePrototypeToolTheme();
+  const [theme, setTheme] = useState<PrototypeToolTheme>(contextTheme);
+
+  useEffect(() => {
+    const syncTheme = () => {
+      setTheme(readActivePrototypeToolTheme());
+    };
+
+    syncTheme();
+
+    const observer = new MutationObserver(syncTheme);
+    for (const root of document.querySelectorAll("[data-prototype-root]")) {
+      observer.observe(root, {
+        attributes: true,
+        attributeFilter: ["data-prototype-comment-theme"],
+      });
+    }
+
+    return () => observer.disconnect();
+  }, []);
+
+  return theme;
+}

package/src/server/proto-plugin-version-route.ts

@@ -1,11 +1,11 @@
 import { readFileSync } from "fs";
 import { join } from "path";
 
+import { isNewerProtoPluginVersion } from "@prototype/lib/prototypes/proto-plugin-semver";
 import { NextResponse } from "next/server";
 
 const PACKAGE_NAME = "proto-plugin";
 const NPM_LATEST_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
-const CACHE_TTL_MS = 60 * 60 * 1000;
 
 export type ProtoPluginVersionStatus = {
   installed: string | null;
@@ -20,28 +20,6 @@ type NpmLatestResponse = {
   repository?: { url?: string };
 };
 
-let cachedLatest: { version: string; repositoryUrl?: string; fetchedAt: number } | null =
-  null;
-
-function parseSemver(version: string): [number, number, number] | null {
-  const match = /^(\d+)\.(\d+)\.(\d+)/.exec(version.trim());
-  if (!match) return null;
-  return [Number(match[1]), Number(match[2]), Number(match[3])];
-}
-
-export function isNewerVersion(latest: string, installed: string): boolean {
-  const latestParts = parseSemver(latest);
-  const installedParts = parseSemver(installed);
-  if (!latestParts || !installedParts) return false;
-
-  for (let index = 0; index < 3; index += 1) {
-    if (latestParts[index]! > installedParts[index]!) return true;
-    if (latestParts[index]! < installedParts[index]!) return false;
-  }
-
-  return false;
-}
-
 function readIsWorkspaceDependency(cwd: string): boolean {
   try {
     const hostPkg = JSON.parse(readFileSync(join(cwd, "package.json"), "utf8")) as {
@@ -76,18 +54,9 @@ async function fetchLatestFromNpm(): Promise<{
   version: string | null;
   repositoryUrl?: string;
 }> {
-  const now = Date.now();
-
-  if (cachedLatest && now - cachedLatest.fetchedAt < CACHE_TTL_MS) {
-    return {
-      version: cachedLatest.version,
-      repositoryUrl: cachedLatest.repositoryUrl,
-    };
-  }
-
   try {
     const response = await fetch(NPM_LATEST_URL, {
-      next: { revalidate: 3600 },
+      cache: "no-store",
     });
 
     if (!response.ok) {
@@ -98,10 +67,6 @@ async function fetchLatestFromNpm(): Promise<{
     const version = data.version ?? null;
     const repositoryUrl = data.repository?.url?.replace(/^git\+/, "").replace(/\.git$/, "");
 
-    if (version) {
-      cachedLatest = { version, repositoryUrl, fetchedAt: now };
-    }
-
     return { version, repositoryUrl };
   } catch {
     return { version: null };
@@ -119,13 +84,17 @@ export async function GET() {
       updateAvailable: false,
       isWorkspaceLink: true,
     };
-    return NextResponse.json(status);
+    return NextResponse.json(status, {
+      headers: { "Cache-Control": "no-store, max-age=0" },
+    });
   }
 
   const { version: latest, repositoryUrl } = await fetchLatestFromNpm();
 
   const updateAvailable =
-    installed != null && latest != null && isNewerVersion(latest, installed);
+    installed != null &&
+    latest != null &&
+    isNewerProtoPluginVersion(latest, installed);
 
   const status: ProtoPluginVersionStatus = {
     installed,
@@ -135,5 +104,7 @@ export async function GET() {
     repositoryUrl,
   };
 
-  return NextResponse.json(status);
+  return NextResponse.json(status, {
+    headers: { "Cache-Control": "no-store, max-age=0" },
+  });
 }