proto-plugin 0.1.8 → 0.1.9

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.9",
   "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

@@ -16,17 +16,17 @@ export function PrototypePluginUpdatePopup() {
     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",
       });
     }
   };
@@ -36,37 +36,33 @@ export function PrototypePluginUpdatePopup() {
       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]",
+        "pointer-events-auto fixed bottom-4 left-4 z-[1050] relative isolate flex w-fit max-w-[min(18rem,calc(100vw-2rem))] flex-col gap-2 rounded-lg bg-[var(--tool-chrome-surface)] p-2.5 pr-7 shadow-[var(--tool-review-card-shadow)] ring-[0.5px] ring-[var(--tool-chrome-border)]",
       )}
     >
-      <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>
-        <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"
-          onClick={dismiss}
-        >
-          <X size={14} />
-        </button>
-      </div>
+      <button
+        type="button"
+        aria-label="Dismiss update notification"
+        className="absolute right-1.5 top-1.5 rounded p-0.5 text-[var(--tool-chrome-text-muted)] transition-colors duration-200 ease hover:text-[var(--tool-chrome-text-heading)]"
+        onClick={dismiss}
+      >
+        <X size={12} />
+      </button>
+
+      <p className="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="outline"
+        variant="chrome"
         size="sm"
-        className="h-8 w-fit cursor-pointer gap-1.5"
+        className="h-7 w-fit cursor-pointer gap-1 px-2 text-[11px]"
         onClick={() => {
-          void handleCopy();
+          void handleCopyPrompt();
         }}
-        aria-label="Copy upgrade prompt"
+        aria-label="Copy update prompt"
       >
-        {isCopied ? "Copied prompt" : "Copy prompt"}
+        {isCopied ? "Copied update prompt" : "Copy update prompt"}
         {icon}
       </Button>
     </div>

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/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/server/proto-plugin-version-route.ts

@@ -5,7 +5,6 @@ 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,9 +19,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;
@@ -76,18 +72,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 +85,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,7 +102,9 @@ 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();
@@ -135,5 +120,7 @@ export async function GET() {
     repositoryUrl,
   };
 
-  return NextResponse.json(status);
+  return NextResponse.json(status, {
+    headers: { "Cache-Control": "no-store, max-age=0" },
+  });
 }