prototype-prd-vite-plugin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# prototype-prd-vite-plugin
+
+Local-first PRD workbench for Vite prototype projects.
+
+During `vite dev`, this plugin injects a small `PRD` button into the page. The button opens a right-side drawer where you can edit Markdown, preview it, save a local draft, export a project PRD, and optionally trigger AI generation from your local dev server.
+
+## Install
+
+```bash
+npm install -D prototype-prd-vite-plugin
+```
+
+## Usage
+
+```js
+// vite.config.js
+import { defineConfig } from "vite";
+import prototypePrd from "prototype-prd-vite-plugin";
+
+export default defineConfig({
+  plugins: [
+    prototypePrd()
+  ]
+});
+```
+
+The overlay only runs in Vite dev mode. It is disabled for production builds by default.
+
+## Configuration
+
+```js
+prototypePrd({
+  draftDir: ".prototype-prd",
+  draftFile: "current.md",
+  exportDir: "docs/prd",
+  defaultTitle: "Product Requirements Document",
+  ai: {
+    enabled: true,
+    model: "gpt-4.1-mini",
+    baseURL: "https://api.openai.com/v1"
+  }
+});
+```
+
+## Storage Model
+
+Drafts are local-first:
+
+- Draft file: `.prototype-prd/current.md`
+- Export directory: `docs/prd`
+- Export file shape: `YYYY-MM-DD-<slug>.md`
+
+If you want private drafts, keep `.prototype-prd/` in `.gitignore`. Exported PRDs under `docs/prd/` are intended to be committed and reviewed with the project.
+
+## AI Generation
+
+AI generation is manual. The plugin never calls an external API on startup or while you type. It only calls AI after you click `Generate Markdown`.
+
+Set your API key locally before starting Vite:
+
+```bash
+OPENAI_API_KEY=your_key npm run dev
+```
+
+The key is read only by the Vite dev server middleware. It is not sent to the browser, not written by this plugin, and not printed.
+
+By default the plugin calls the OpenAI Responses API at:
+
+```text
+POST https://api.openai.com/v1/responses
+```
+
+You can set `ai.baseURL` for a compatible local gateway or proxy.
+
+## Privacy And Safety
+
+- No production build injection by default.
+- No browser-side OpenAI API calls.
+- No API key creation or storage.
+- No automatic network requests for editing, saving, previewing, or exporting.
+- File access is constrained to the Vite project root.
+- AI context is limited to current PRD Markdown, current page URL, and notes you enter.
+
+## Local Development
+
+```bash
+npm test
+npm pack --dry-run
+```
+
+## Example
+
+See `examples/basic` for a minimal Vite app configuration.

package/client/overlay.css

@@ -0,0 +1,174 @@
+:host {
+  --prd-ink: #1f1c17;
+  --prd-paper: #fbf5e8;
+  --prd-panel: #fffaf0;
+  --prd-line: #ddccb1;
+  --prd-accent: #c9792b;
+  --prd-accent-dark: #8f4b1d;
+  --prd-muted: #74695d;
+  --prd-shadow: 0 24px 80px rgba(48, 35, 18, 0.22);
+  color: var(--prd-ink);
+  font-family: "Avenir Next", "Gill Sans", "Trebuchet MS", sans-serif;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+.toggle {
+  position: fixed;
+  right: 22px;
+  bottom: 22px;
+  z-index: 2147483646;
+  border: 1px solid rgba(255, 255, 255, 0.26);
+  border-radius: 999px;
+  background: #1f1c17;
+  color: #fff7e7;
+  box-shadow: 0 16px 40px rgba(31, 28, 23, 0.32);
+  cursor: pointer;
+  font-weight: 800;
+  letter-spacing: 0.08em;
+  padding: 13px 18px;
+}
+
+.drawer {
+  position: fixed;
+  inset: 0 0 0 auto;
+  z-index: 2147483647;
+  width: min(520px, 100vw);
+  transform: translateX(105%);
+  transition: transform 180ms ease;
+  background:
+    radial-gradient(circle at top left, rgba(201, 121, 43, 0.16), transparent 38%),
+    linear-gradient(180deg, var(--prd-panel), var(--prd-paper));
+  border-left: 1px solid var(--prd-line);
+  box-shadow: var(--prd-shadow);
+  display: grid;
+  grid-template-rows: auto auto 1fr auto;
+}
+
+.drawer.open {
+  transform: translateX(0);
+}
+
+.header,
+.footer {
+  padding: 16px;
+  border-bottom: 1px solid var(--prd-line);
+}
+
+.footer {
+  border-bottom: 0;
+  border-top: 1px solid var(--prd-line);
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+
+.title-row {
+  align-items: center;
+  display: flex;
+  gap: 12px;
+}
+
+.title-row h2 {
+  flex: 1;
+  font-family: Georgia, "Times New Roman", serif;
+  font-size: 22px;
+  line-height: 1.1;
+  margin: 0;
+}
+
+.status {
+  color: var(--prd-muted);
+  font-size: 12px;
+  margin-top: 8px;
+}
+
+.tabs {
+  display: flex;
+  gap: 8px;
+  padding: 12px 16px 0;
+}
+
+button {
+  border: 1px solid var(--prd-line);
+  border-radius: 999px;
+  background: rgba(255, 255, 255, 0.64);
+  color: var(--prd-ink);
+  cursor: pointer;
+  font: inherit;
+  font-weight: 700;
+  padding: 9px 12px;
+}
+
+button.primary {
+  background: var(--prd-accent);
+  border-color: var(--prd-accent-dark);
+  color: white;
+}
+
+button.active {
+  background: var(--prd-ink);
+  border-color: var(--prd-ink);
+  color: var(--prd-paper);
+}
+
+.content {
+  min-height: 0;
+  overflow: auto;
+  padding: 16px;
+}
+
+textarea,
+input {
+  width: 100%;
+  border: 1px solid var(--prd-line);
+  border-radius: 16px;
+  background: rgba(255, 255, 255, 0.76);
+  color: var(--prd-ink);
+  font: 14px/1.55 ui-monospace, "SFMono-Regular", Menlo, Consolas, monospace;
+  outline: none;
+  padding: 13px;
+}
+
+textarea {
+  min-height: 58vh;
+  resize: vertical;
+}
+
+label {
+  color: var(--prd-muted);
+  display: grid;
+  font-size: 12px;
+  gap: 6px;
+  margin-bottom: 12px;
+}
+
+.preview {
+  background: rgba(255, 255, 255, 0.62);
+  border: 1px solid var(--prd-line);
+  border-radius: 20px;
+  font-family: Georgia, "Times New Roman", serif;
+  line-height: 1.65;
+  padding: 18px;
+}
+
+.preview h1,
+.preview h2,
+.preview h3 {
+  line-height: 1.15;
+}
+
+.hint {
+  color: var(--prd-muted);
+  font-size: 13px;
+  line-height: 1.5;
+  margin: 0 0 12px;
+}
+
+@media (max-width: 640px) {
+  .drawer {
+    width: 100vw;
+  }
+}

package/client/overlay.js

@@ -0,0 +1,209 @@
+const API = "/__prototype_prd__";
+const CSS_URL = "/__prototype_prd__/client/overlay.css";
+
+const host = document.createElement("prototype-prd-overlay");
+const shadow = host.attachShadow({ mode: "open" });
+document.documentElement.append(host);
+
+shadow.innerHTML = `
+  <link rel="stylesheet" href="${CSS_URL}">
+  <button class="toggle" type="button">PRD</button>
+  <aside class="drawer" aria-label="PRD workbench">
+    <header class="header">
+      <div class="title-row">
+        <h2>Prototype PRD</h2>
+        <button class="close" type="button" aria-label="Close PRD panel">Close</button>
+      </div>
+      <div class="status">Loading local draft...</div>
+    </header>
+    <nav class="tabs">
+      <button class="tab active" type="button" data-tab="edit">Edit</button>
+      <button class="tab" type="button" data-tab="preview">Preview</button>
+      <button class="tab" type="button" data-tab="generate">Generate</button>
+    </nav>
+    <main class="content"></main>
+    <footer class="footer">
+      <button class="primary save" type="button">Save draft</button>
+      <button class="export" type="button">Export docs</button>
+      <button class="copy" type="button">Copy Markdown</button>
+    </footer>
+  </aside>
+`;
+
+const state = {
+  open: false,
+  tab: "edit",
+  title: "Product Requirements Document",
+  markdown: "",
+  aiConfigured: false
+};
+
+const elements = {
+  toggle: shadow.querySelector(".toggle"),
+  drawer: shadow.querySelector(".drawer"),
+  close: shadow.querySelector(".close"),
+  status: shadow.querySelector(".status"),
+  tabs: [...shadow.querySelectorAll(".tab")],
+  content: shadow.querySelector(".content"),
+  save: shadow.querySelector(".save"),
+  export: shadow.querySelector(".export"),
+  copy: shadow.querySelector(".copy")
+};
+
+elements.toggle.addEventListener("click", () => setOpen(true));
+elements.close.addEventListener("click", () => setOpen(false));
+elements.save.addEventListener("click", saveDraft);
+elements.export.addEventListener("click", exportDocs);
+elements.copy.addEventListener("click", copyMarkdown);
+elements.tabs.forEach((tab) => {
+  tab.addEventListener("click", () => {
+    state.tab = tab.dataset.tab;
+    render();
+  });
+});
+
+boot();
+
+async function boot() {
+  try {
+    const appState = await request("/state");
+    const draft = await request("/draft");
+    state.title = appState.title;
+    state.aiConfigured = appState.ai.configured;
+    state.markdown = draft.markdown;
+    setStatus(draft.exists ? "Loaded local draft." : "Started from PRD template.");
+    render();
+  } catch (error) {
+    setStatus(error.message);
+    render();
+  }
+}
+
+function setOpen(open) {
+  state.open = open;
+  elements.drawer.classList.toggle("open", open);
+}
+
+function render() {
+  elements.tabs.forEach((tab) => {
+    tab.classList.toggle("active", tab.dataset.tab === state.tab);
+  });
+
+  if (state.tab === "edit") {
+    elements.content.innerHTML = `<textarea aria-label="PRD Markdown"></textarea>`;
+    const textarea = elements.content.querySelector("textarea");
+    textarea.value = state.markdown;
+    textarea.addEventListener("input", () => {
+      state.markdown = textarea.value;
+      setStatus("Unsaved changes.");
+    });
+    return;
+  }
+
+  if (state.tab === "preview") {
+    elements.content.innerHTML = `<article class="preview">${renderMarkdown(state.markdown)}</article>`;
+    return;
+  }
+
+  elements.content.innerHTML = `
+    <p class="hint">AI generation only runs when you click the button. The request is sent from the local Vite dev server, not the browser.</p>
+    <label>Instruction
+      <input class="instruction" value="Generate or improve this PRD from the current draft.">
+    </label>
+    <label>Product notes
+      <textarea class="notes" style="min-height:120px" placeholder="Optional notes about this prototype"></textarea>
+    </label>
+    <button class="primary generate" type="button">Generate Markdown</button>
+  `;
+  elements.content.querySelector(".generate").addEventListener("click", generate);
+}
+
+async function saveDraft() {
+  try {
+    await request("/draft", {
+      method: "PUT",
+      body: { markdown: state.markdown }
+    });
+    setStatus("Draft saved locally.");
+  } catch (error) {
+    setStatus(error.message);
+  }
+}
+
+async function exportDocs() {
+  try {
+    const result = await request("/export", {
+      method: "POST",
+      body: { markdown: state.markdown, title: state.title }
+    });
+    setStatus(`Exported ${result.fileName}.`);
+  } catch (error) {
+    setStatus(error.message);
+  }
+}
+
+async function copyMarkdown() {
+  await navigator.clipboard.writeText(state.markdown);
+  setStatus("Markdown copied.");
+}
+
+async function generate() {
+  const instruction = elements.content.querySelector(".instruction").value;
+  const notes = elements.content.querySelector(".notes").value;
+
+  try {
+    setStatus("Generating with AI...");
+    const result = await request("/ai/generate", {
+      method: "POST",
+      body: {
+        markdown: state.markdown,
+        instruction,
+        notes,
+        pageUrl: window.location.href
+      }
+    });
+    state.markdown = result.markdown;
+    state.tab = "edit";
+    setStatus("AI generated Markdown. Review before saving.");
+    render();
+  } catch (error) {
+    setStatus(error.message);
+  }
+}
+
+async function request(path, options = {}) {
+  const response = await fetch(`${API}${path}`, {
+    method: options.method || "GET",
+    headers: options.body ? { "content-type": "application/json" } : undefined,
+    body: options.body ? JSON.stringify(options.body) : undefined
+  });
+  const payload = await response.json();
+
+  if (!response.ok) {
+    throw new Error(payload?.error?.message || "Prototype PRD request failed.");
+  }
+
+  return payload;
+}
+
+function setStatus(message) {
+  elements.status.textContent = message;
+}
+
+function renderMarkdown(markdown) {
+  return escapeHtml(markdown)
+    .replace(/^# (.*)$/gm, "<h1>$1</h1>")
+    .replace(/^## (.*)$/gm, "<h2>$1</h2>")
+    .replace(/^### (.*)$/gm, "<h3>$1</h3>")
+    .replace(/^\- (.*)$/gm, "<li>$1</li>")
+    .replace(/\n{2,}/g, "</p><p>")
+    .replace(/^(?!<h|<li|<\/p>)(.+)$/gm, "<p>$1</p>");
+}
+
+function escapeHtml(value) {
+  return String(value ?? "")
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}

package/examples/basic/index.html

@@ -0,0 +1,19 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Prototype PRD Example</title>
+  </head>
+  <body>
+    <main class="hero">
+      <p class="eyebrow">Prototype</p>
+      <h1>Checkout flow concept</h1>
+      <p>
+        A small Vite page used to test the local PRD workbench overlay.
+      </p>
+      <button>Start checkout</button>
+    </main>
+    <script type="module" src="/src/main.js"></script>
+  </body>
+</html>