@rashidee/co2 1.3.10 → 1.3.11

package/dist/index.js

@@ -6809,7 +6809,7 @@ var {
 // package.json
 var package_default = {
   name: "@rashidee/co2",
-  version: "1.3.10",
+  version: "1.3.11",
   description: "Compound Context Studio \u2014 self-hosted team context authoring for CO2 projects",
   type: "module",
   license: "MIT",
@@ -19151,6 +19151,14 @@ var gitResolveRequestSchema = external_exports.object({
   message: "Manual resolution requires the merged content",
   path: ["content"]
 });
+var gitPullResponseSchema = external_exports.object({
+  status: external_exports.enum(["up_to_date", "merged", "conflicts"]),
+  branch: external_exports.string(),
+  /** New short HEAD hash — present only for `merged`. */
+  commitHash: external_exports.string().optional(),
+  /** Git's own summary (e.g. the conflict list) — display verbatim. */
+  message: external_exports.string().optional()
+});
 
 // ../core/src/schemas/import.ts
 var importCandidateSchema = external_exports.object({
@@ -19905,6 +19913,64 @@ async function startMockupHub(db, workspacePath, projectId, requestHost, port) {
   }
   return toStatus({ location, running: false, activePort: targetPort }, requestHost, projectId);
 }
+var STRIP_HEADERS = /* @__PURE__ */ new Set([
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+  "host",
+  "content-length",
+  "content-encoding",
+  "accept-encoding"
+]);
+async function proxyHubRequest(db, workspacePath, projectId, prefix, subPath, req) {
+  const location = resolveHub(db, workspacePath, projectId);
+  if (!location.present) throw svcError("MOCKUP_HUB_MISSING", 404);
+  if (!location.configPort) throw svcError("MOCKUP_HUB_DOWN", 502);
+  const url = new URL(req.url);
+  const target = `http://127.0.0.1:${location.configPort}${subPath}${url.search}`;
+  const headers = new Headers();
+  req.headers.forEach((value, name) => {
+    if (!STRIP_HEADERS.has(name.toLowerCase())) headers.set(name, value);
+  });
+  headers.set("x-forwarded-prefix", prefix);
+  headers.set("x-forwarded-host", url.host);
+  headers.set("x-forwarded-proto", url.protocol.replace(/:$/, ""));
+  const hasBody = req.method !== "GET" && req.method !== "HEAD";
+  let upstream;
+  try {
+    upstream = await fetch(target, {
+      method: req.method,
+      headers,
+      body: hasBody ? await req.arrayBuffer() : void 0,
+      redirect: "manual"
+    });
+  } catch {
+    throw svcError("MOCKUP_HUB_DOWN", 502);
+  }
+  const responseHeaders = new Headers();
+  upstream.headers.forEach((value, name) => {
+    if (!STRIP_HEADERS.has(name.toLowerCase())) responseHeaders.set(name, value);
+  });
+  const redirectTo = responseHeaders.get("location");
+  if (redirectTo?.startsWith("/") && redirectTo !== prefix && !redirectTo.startsWith(`${prefix}/`)) {
+    responseHeaders.set("location", `${prefix}${redirectTo}`);
+  }
+  const prefixAware = upstream.headers.get("x-hub-prefix") !== null;
+  responseHeaders.delete("x-hub-prefix");
+  if (!prefixAware && responseHeaders.get("content-type")?.includes("text/html")) {
+    const html = (await upstream.text()).replace(
+      /(href|src|action|hx-get|hx-post|hx-put|hx-patch|hx-delete)="(\/[^"]*)"/g,
+      (match2, attr, url2) => url2 === prefix || url2.startsWith(`${prefix}/`) ? match2 : `${attr}="${prefix}${url2}"`
+    );
+    return new Response(html, { status: upstream.status, headers: responseHeaders });
+  }
+  return new Response(upstream.body, { status: upstream.status, headers: responseHeaders });
+}
 function stopMockupHub(projectId) {
   const child = spawnedHubs.get(projectId);
   if (!child) return false;
@@ -20201,6 +20267,24 @@ function artifactRoutes(db, workspacePath) {
       return errorResponse(c, e);
     }
   });
+  app.all(
+    "/mockup-proxy/:projectId",
+    (c) => (
+      // Normalize to the trailing-slash form so the prefix always maps to the hub root.
+      c.redirect(`${c.req.path}/`, 301)
+    )
+  );
+  app.all("/mockup-proxy/:projectId/*", async (c) => {
+    const projectId = Number(c.req.param("projectId"));
+    if (!Number.isInteger(projectId) || projectId <= 0) return c.json({ code: "INVALID_ID" }, 400);
+    const prefix = `/api/artifacts/mockup-proxy/${projectId}`;
+    const subPath = c.req.path.slice(prefix.length) || "/";
+    try {
+      return await proxyHubRequest(db, workspacePath, projectId, prefix, subPath, c.req.raw);
+    } catch (e) {
+      return errorResponse(c, e);
+    }
+  });
   app.get("/:id/content", (c) => {
     const id = Number(c.req.param("id"));
     if (Number.isNaN(id)) return c.json({ code: "INVALID_ID" }, 400);
@@ -24404,6 +24488,67 @@ function resolveConflict(db, workspacePath, projectId, input) {
     throw new GitServiceError("GIT_RESOLVE_FAILED", 409, detail(e));
   }
 }
+function pullChanges(db, workspacePath, projectId, userId) {
+  const dir = projectDir(db, workspacePath, projectId);
+  if (!existsSync18(dir) || !isGitRepo(dir)) {
+    throw new GitServiceError("NO_GIT_REPO", 404, "No git repository for this project");
+  }
+  const status = getGitStatus(db, workspacePath, projectId);
+  if (!status.clean) {
+    throw new GitServiceError(
+      "UNCOMMITTED_CHANGES",
+      409,
+      "Commit or discard your local changes before pulling"
+    );
+  }
+  const branch = safe(() => git3(dir, ["branch", "--show-current"])) ?? "";
+  if (branch === "") {
+    throw new GitServiceError(
+      "DETACHED_HEAD",
+      409,
+      "The repository is in detached HEAD state \u2014 check out a branch before pulling"
+    );
+  }
+  const ctx = resolveGitPushContext(db, projectId, userId);
+  if (ctx.remoteUrl) ensureOrigin(dir, ctx.remoteUrl);
+  const remotes = safe(() => git3(dir, ["remote"])) ?? "";
+  if (!remotes.split("\n").includes("origin")) {
+    throw new GitServiceError("NO_REMOTE", 400, "No git remote configured for this project");
+  }
+  const headBefore = safe(() => git3(dir, ["rev-parse", "--short", "HEAD"])) ?? "";
+  const authB64 = ctx.auth ? Buffer.from(`${ctx.auth.username}:${ctx.auth.token}`).toString("base64") : null;
+  try {
+    execFileSync3(
+      "git",
+      [
+        ...buildPushAuthArgs(ctx.auth),
+        ...identityArgs(db, userId),
+        "pull",
+        "--no-rebase",
+        "--no-edit",
+        "origin",
+        branch
+      ],
+      {
+        cwd: dir,
+        stdio: "pipe",
+        timeout: 12e4,
+        maxBuffer: 64 * 1024 * 1024,
+        env: { ...process.env, GIT_TERMINAL_PROMPT: "0" }
+      }
+    );
+  } catch (e) {
+    if (authB64) redactAuthHeaderFromError(e, authB64);
+    const after = getGitStatus(db, workspacePath, projectId);
+    if (after.hasConflicts) {
+      return { status: "conflicts", branch, message: gitErrorDetail(e) };
+    }
+    throw new GitServiceError("GIT_PULL_FAILED", 409, withIdentityHint(gitErrorDetail(e)));
+  }
+  const headAfter = safe(() => git3(dir, ["rev-parse", "--short", "HEAD"])) ?? "";
+  if (headAfter === headBefore) return { status: "up_to_date", branch };
+  return { status: "merged", branch, commitHash: headAfter };
+}
 function detail(e) {
   const stderr = e.stderr?.toString().trim();
   return stderr || e.message || String(e);
@@ -24475,6 +24620,15 @@ function gitRoutes(db, workspacePath) {
       return errorResponse7(c, e);
     }
   });
+  app.post("/pull/:projectId", (c) => {
+    const projectId = Number(c.req.param("projectId"));
+    if (Number.isNaN(projectId)) return c.json({ code: "INVALID_ID" }, 400);
+    try {
+      return c.json(pullChanges(db, workspacePath, projectId, c.get("user")?.id));
+    } catch (e) {
+      return errorResponse7(c, e);
+    }
+  });
   return app;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rashidee/co2",
-  "version": "1.3.10",
+  "version": "1.3.11",
   "description": "Compound Context Studio — self-hosted team context authoring for CO2 projects",
   "type": "module",
   "license": "MIT",

package/plugin/skills/mockgen-shadcn/SKILL.md

@@ -36,7 +36,8 @@ designer review. Layout uses React components (header, sidebar, footer) composed
 layout route. Pages are React Router routes rendered inside the layout. All navigation is
 client-side via React Router `<Link>` and `useNavigate`.
 
-The mockup is generated with `base`/`basename` set to `/{app_slug}/`, **built** with
+The mockup is generated with Vite `base` set to `/{app_slug}/` (router basename derived
+from the current URL so it also works behind the studio's proxy prefix), **built** with
 `npm run build`, and served from its `dist/` folder by the **shared Mockup Hub** — a single
 zero-dependency Node.js server at `<root>/mockup/` that serves ALL applications' mockups
 (see [references/mockup-hub-template.md](references/mockup-hub-template.md)). The hub renders
@@ -90,8 +91,8 @@ The application name is matched against root-level application folders:
 
 **App slug** (used as the URL base path): the application folder name with the leading
 `<number>_` prefix stripped (e.g., `1_hub_middleware` → `hub_middleware`). Record it during
-input resolution — it is baked into `vite.config.ts` (`base`), `main.tsx`
-(`BrowserRouter basename`), and all MOCKUP.html links.
+input resolution — it is baked into `vite.config.ts` (`base`), `main.tsx` (the runtime
+basename derivation always ends in `/{app_slug}`), and all MOCKUP.html links.
 
 ### Example Invocations
 
@@ -528,8 +529,10 @@ Key project setup:
 - `postcss.config.js` — PostCSS with Tailwind and autoprefixer
 - `components.json` — shadcn/ui configuration (New York style, zinc base)
 - `index.html` — Vite entry HTML with Google Fonts
-- `src/main.tsx` — React root render with `<BrowserRouter basename="/{app_slug}">`
-  (REQUIRED to match the Vite `base`)
+- `src/main.tsx` — React root render with a `<BrowserRouter basename={...}>` derived at
+  runtime from the current URL — it always ends in `/{app_slug}` (matching the Vite
+  `base`) and preserves any proxy prefix (Compound Context Studio embeds the hub through
+  its same-origin proxy); see the main.tsx template
 - `src/App.tsx` — React Router configuration with all role/page routes
 - `src/index.css` — Tailwind directives + shadcn/ui CSS variables (light and dark)
 - `src/lib/utils.ts` — `cn()` utility (clsx + tailwind-merge)
@@ -1009,8 +1012,9 @@ After all mockup files are successfully generated, append an entry to `CHANGELOG
   v1.0.2` means "generate Employer module pages as they exist at v1.0.2". Version filtering
   and module filtering each apply independently; a story must satisfy BOTH to be included.
 - **Base path is mandatory**: `vite.config.ts` MUST set `base: "/{app_slug}/"` and
-  `main.tsx` MUST set `<BrowserRouter basename="/{app_slug}">` — without them the built
-  app cannot be served by the hub at `/{app_slug}`.
+  `main.tsx` MUST derive the router basename from the current URL per the main.tsx
+  template (it always ends in `/{app_slug}`) — without them the built app cannot be
+  served by the hub at `/{app_slug}`, directly or behind the studio's proxy prefix.
 - **No per-app server for viewing**: reviewers use ONLY the shared hub at `<root>/mockup/`
   (ensure it per Step 4d). The Vite dev server is for design iteration only.
 - **Manifest is mandatory**: every run writes/updates `mockup-manifest.json` — without it

package/plugin/skills/mockgen-shadcn/references/admin-layout-template.md

@@ -461,9 +461,19 @@ import { ThemeProvider } from "next-themes";
 import App from "./App";
 import "./index.css";
 
+// The app is served at /{{APP_SLUG}} by the Mockup Hub — either directly, or behind a
+// prefix-forwarding proxy (Compound Context Studio embeds the hub at
+// /api/artifacts/mockup-proxy/<id>/). Derive the basename from the current URL so
+// client-side routing works in both cases.
+const APP_BASE = "/{{APP_SLUG}}";
+const path = window.location.pathname;
+const cut = path.indexOf(APP_BASE + "/");
+const basename =
+  cut >= 0 ? path.slice(0, cut) + APP_BASE : path.endsWith(APP_BASE) ? path : APP_BASE;
+
 createRoot(document.getElementById("root")!).render(
   <StrictMode>
-    <BrowserRouter basename="/{{APP_SLUG}}">
+    <BrowserRouter basename={basename}>
       <ThemeProvider attribute="class" defaultTheme="light" enableSystem>
         <App />
       </ThemeProvider>
@@ -472,8 +482,9 @@ createRoot(document.getElementById("root")!).render(
 );
 ```
 
-> The `basename` MUST match the Vite `base` — all internal `<Link to="/{role}/...">`
-> paths stay unchanged; React Router resolves them under `/{{APP_SLUG}}` automatically.
+> The basename always ends in `/{{APP_SLUG}}` (matching the Vite `base`) — all internal
+> `<Link to="/{role}/...">` paths stay unchanged; React Router resolves them under it
+> automatically, with any proxy prefix preserved.
 
 ---
 

package/plugin/skills/mockgen-shadcn/references/mockup-hub-template.md

@@ -19,6 +19,13 @@ they contain NO server of their own.
   `mockup.config.json` and re-listens on the new port. Compound Context Studio's Mockup
   page reads its own topbar port input and passes it via the `PORT` env when its
   **Start Hub** button spawns this server.
+- **Reverse-proxy aware** (v3): Compound Context Studio embeds the hub through its own
+  same-origin proxy (`/api/artifacts/mockup-proxy/<projectId>/`), which sends the mount
+  path in an `X-Forwarded-Prefix` header. The hub prefixes every redirect and rewrites
+  root-absolute URL attributes (`href`/`src`/`action`/`hx-*`) in the HTML it serves —
+  including per-app assets generated before v3 — so mockups work behind the studio (or
+  any prefix-forwarding reverse proxy) without exposing the hub's port separately.
+  Requests without the header behave exactly as before.
 
 The hub has **zero npm dependencies** — `npm start` (or `node server.js`) works with no
 `npm install`.
@@ -97,12 +104,15 @@ Example:
 #!/usr/bin/env node
 /*
  * CO2 Mockup Hub — one server for ALL application mockups.
- * HUB_VERSION: 2   (marker used by mockgen-* skills to decide upgrades — do not remove)
+ * HUB_VERSION: 3   (marker used by mockgen-* skills to decide upgrades — do not remove)
  *
  * Discovers every root-level application folder containing context/PRD.md.
  * Apps with a context/mockup/mockup-manifest.json are routable:
  *   - stack "tailwind": pages assembled from partials + content fragments
  *   - stack "shadcn":  served from the built dist/ folder (SPA fallback)
+ * Reverse proxy: when a request carries X-Forwarded-Prefix (Compound Context Studio's
+ *   same-origin proxy sends it), redirects are prefixed and root-absolute URL
+ *   attributes in served HTML are rewritten under the prefix.
  * Port: PORT env var > mockup.config.json "port" > first unused port from 4000.
  *   - A PORT env value is exact (Compound Context Studio's Start Hub passes it) — a busy
  *     port fails fast so the caller sees the error.
@@ -118,10 +128,11 @@ const net = require('net');
 const fs = require('fs');
 const path = require('path');
 
-const HUB_VERSION = 2;
+const HUB_VERSION = 3;
 const HUB_DIR = __dirname;
 const ROOT_DIR = path.resolve(HUB_DIR, '..');
 const SAFE_SEG = /^[A-Za-z0-9._-]+$/;
+const SAFE_PREFIX = /^\/[A-Za-z0-9/_-]*$/; // root-relative, no dots/query/fragment
 const PORT_SCAN_START = 4000; // default: first unused port starting here
 const PORT_SCAN_LIMIT = 100;
 
@@ -229,11 +240,39 @@ function findApp(slug) {
 
 // ── Response helpers ─────────────────────────────────────────────────────────
 
+/** The sanitized X-Forwarded-Prefix ('' when absent/unsafe), without trailing slash. */
+function requestPrefix(req) {
+  var raw = String(req.headers['x-forwarded-prefix'] || '');
+  if (raw.endsWith('/')) raw = raw.slice(0, -1);
+  return SAFE_PREFIX.test(raw) ? raw : '';
+}
+
+/**
+ * Rewrite root-absolute URL attributes so they stay under the proxy prefix. Covers hub
+ * pages AND per-app assets (tailwind partials/content with hx-* attributes, shadcn dist
+ * index.html, MOCKUP.html, reports) — including assets generated before hub v3.
+ */
+function applyPrefix(html, prefix) {
+  if (!prefix) return html;
+  return html.replace(
+    /(href|src|action|hx-get|hx-post|hx-put|hx-patch|hx-delete)="\//g,
+    '$1="' + prefix + '/'
+  );
+}
+
 function send(res, code, body, type) {
   res.writeHead(code, { 'Content-Type': type || 'text/html; charset=utf-8' });
   res.end(body);
 }
 
+/** All HTML goes out through this so root-absolute links are prefix-rewritten. The
+ *  X-Hub-Prefix header tells the studio proxy the hub already rewrote its HTML, so the
+ *  proxy skips its own legacy-hub rewrite pass (no double-prefixing). */
+function sendHtml(res, code, html, prefix) {
+  if (prefix) res.setHeader('X-Hub-Prefix', prefix);
+  send(res, code, applyPrefix(html, prefix), 'text/html; charset=utf-8');
+}
+
 function redirect(res, location) {
   res.writeHead(302, { Location: location });
   res.end();
@@ -252,12 +291,18 @@ function safeJoin(baseDir, segments) {
   return target;
 }
 
-function serveFile(res, filePath) {
+function serveFile(res, filePath, prefix) {
   if (!filePath) return false;
   let stat;
   try { stat = fs.statSync(filePath); } catch (err) { return false; }
   if (!stat.isFile()) return false;
-  const type = MIME[path.extname(filePath).toLowerCase()] || 'application/octet-stream';
+  const ext = path.extname(filePath).toLowerCase();
+  const type = MIME[ext] || 'application/octet-stream';
+  // HTML files (MOCKUP.html, shadcn dist index.html, reports) get prefix-rewritten.
+  if (ext === '.html' && prefix) {
+    sendHtml(res, 200, fs.readFileSync(filePath, 'utf8'), prefix);
+    return true;
+  }
   send(res, 200, fs.readFileSync(filePath), type);
   return true;
 }
@@ -340,7 +385,9 @@ function renderAppCard(app) {
 
 // Port input (default: the current port — auto-picked as the first unused port from 4000
 // when nothing was configured). Apply persists to mockup.config.json via POST /api/port
-// and the hub re-listens on the new port; the page then follows it.
+// and the hub re-listens on the new port; the page then follows it. Behind a proxy
+// (HUB_PREFIX set) the page reloads the prefix root instead — the studio proxy reads
+// the new port from mockup.config.json, so the same URL keeps working.
 const PORT_SCRIPT = `
   function applyPort() {
     var msg = document.getElementById('port-msg');
@@ -349,25 +396,28 @@ const PORT_SCRIPT = `
       msg.style.color = '#dc2626'; msg.textContent = 'Port must be 1024-65535'; return;
     }
     msg.style.color = '#64748b'; msg.textContent = 'Applying\\u2026';
-    fetch('/api/port', { method: 'POST', headers: { 'Content-Type': 'application/json' },
+    fetch(HUB_PREFIX + '/api/port', { method: 'POST', headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({ port: port }) })
       .then(function (r) { return r.json(); })
       .then(function (res) {
         if (!res.ok) { msg.style.color = '#dc2626'; msg.textContent = res.error || 'Failed'; return; }
         msg.textContent = 'Restarting on port ' + res.port + '\\u2026';
         setTimeout(function () {
-          location.href = location.protocol + '//' + location.hostname + ':' + res.port + '/';
+          location.href = HUB_PREFIX
+            ? HUB_PREFIX + '/'
+            : location.protocol + '//' + location.hostname + ':' + res.port + '/';
         }, 700);
       })
       .catch(function () { msg.style.color = '#dc2626'; msg.textContent = 'Request failed'; });
   }
 `;
 
-function renderLanding(apps, currentPort) {
+function renderLanding(apps, currentPort, prefix) {
   return '<!DOCTYPE html>\n<html lang="en">\n<head>\n<meta charset="UTF-8">\n'
     + '<meta name="viewport" content="width=device-width, initial-scale=1.0">\n'
     + '<title>Mockup Hub</title>\n<style>' + LANDING_CSS + '</style>\n'
-    + '<script>' + PORT_SCRIPT + '</script>\n</head>\n<body>\n'
+    // prefix is SAFE_PREFIX-sanitized, so it embeds safely in the inline script.
+    + '<script>var HUB_PREFIX = "' + (prefix || '') + '";' + PORT_SCRIPT + '</script>\n</head>\n<body>\n'
     + '<div class="wrap">\n<h1>Mockup Hub</h1>\n'
     + '<p class="sub">All application mockups, served from one place. '
     + apps.length + ' application(s) discovered. Click a role to open its dashboard.</p>\n'
@@ -378,8 +428,8 @@ function renderLanding(apps, currentPort) {
     + '<span id="port-msg"></span></span></p>\n</div>\n</body>\n</html>';
 }
 
-function notReadyPage(app) {
-  return renderLanding([app], CURRENT_PORT);
+function notReadyPage(app, prefix) {
+  return renderLanding([app], CURRENT_PORT, prefix);
 }
 
 function notFoundPage(what) {
@@ -410,45 +460,46 @@ function assemblePage(app, role, page) {
 
 // ── Routing ──────────────────────────────────────────────────────────────────
 
-function routeTailwind(app, segs, res) {
+function routeTailwind(app, segs, res, prefix) {
   if (segs.length === 1) {
-    if (serveFile(res, path.join(app.mockupDir, 'MOCKUP.html'))) return;
+    if (serveFile(res, path.join(app.mockupDir, 'MOCKUP.html'), prefix)) return;
     const first = app.roles.find((r) => r.slug);
-    if (first) return redirect(res, '/' + app.slug + '/' + first.slug + '/home');
-    return send(res, 404, notFoundPage(app.slug));
+    if (first) return redirect(res, prefix + '/' + app.slug + '/' + first.slug + '/home');
+    return sendHtml(res, 404, notFoundPage(app.slug), prefix);
   }
   if (segs[1] === 'static' || segs[1] === 'reports') {
     const file = safeJoin(path.join(app.mockupDir, segs[1]), segs.slice(2));
-    if (serveFile(res, file)) return;
-    return send(res, 404, notFoundPage());
+    if (serveFile(res, file, prefix)) return;
+    return sendHtml(res, 404, notFoundPage(), prefix);
   }
-  if (!SAFE_SEG.test(segs[1])) return send(res, 400, notFoundPage());
-  if (segs.length === 2) return redirect(res, '/' + app.slug + '/' + segs[1] + '/home');
+  if (!SAFE_SEG.test(segs[1])) return sendHtml(res, 400, notFoundPage(), prefix);
+  if (segs.length === 2) return redirect(res, prefix + '/' + app.slug + '/' + segs[1] + '/home');
   if (segs.length === 3 && SAFE_SEG.test(segs[2])) {
     const html = assemblePage(app, segs[1], segs[2]);
     if (html === null) {
       return send(res, 500, '<h1>Missing partials. Re-run the mockup generator.</h1>');
     }
-    return send(res, 200, html);
+    return sendHtml(res, 200, html, prefix);
   }
-  return send(res, 404, notFoundPage());
+  return sendHtml(res, 404, notFoundPage(), prefix);
 }
 
-function routeShadcn(app, segs, res) {
-  if (segs.length === 1 && serveFile(res, path.join(app.mockupDir, 'MOCKUP.html'))) return;
+function routeShadcn(app, segs, res, prefix) {
+  if (segs.length === 1 && serveFile(res, path.join(app.mockupDir, 'MOCKUP.html'), prefix)) return;
   if (segs[1] === 'reports') {
     const file = safeJoin(path.join(app.mockupDir, 'public', 'reports'), segs.slice(2));
-    if (serveFile(res, file)) return;
-    return send(res, 404, notFoundPage());
+    if (serveFile(res, file, prefix)) return;
+    return sendHtml(res, 404, notFoundPage(), prefix);
   }
   const distDir = path.join(app.mockupDir, 'dist');
   if (segs.length > 1) {
     const file = safeJoin(distDir, segs.slice(1));
-    if (serveFile(res, file)) return;
+    if (serveFile(res, file, prefix)) return;
   }
-  // SPA fallback — React Router (basename /{app_slug}) handles the path client-side
-  if (serveFile(res, path.join(distDir, 'index.html'))) return;
-  return send(res, 404, notFoundPage(app.slug));
+  // SPA fallback — React Router handles the path client-side (the app derives its
+  // basename from the current URL, so it also works under a proxy prefix)
+  if (serveFile(res, path.join(distDir, 'index.html'), prefix)) return;
+  return sendHtml(res, 404, notFoundPage(app.slug), prefix);
 }
 
 // POST /api/port — persist a new port (from the landing page's port input) and re-listen.
@@ -473,8 +524,11 @@ function handlePortUpdate(req, res) {
 function route(req, res) {
   const urlPath = decodeURIComponent((req.url || '/').split('?')[0]);
   const segs = urlPath.split('/').filter(Boolean);
+  const prefix = requestPrefix(req); // '' unless behind a prefix-forwarding proxy
 
-  if (segs.length === 0) return send(res, 200, renderLanding(discoverApps(), CURRENT_PORT));
+  if (segs.length === 0) {
+    return sendHtml(res, 200, renderLanding(discoverApps(), CURRENT_PORT, prefix), prefix);
+  }
   if (urlPath === '/favicon.ico') { res.writeHead(204); return res.end(); }
 
   if (segs[0] === 'api' && segs[1] === 'port' && segs.length === 2 && req.method === 'POST') {
@@ -483,26 +537,28 @@ function route(req, res) {
 
   // HTMX fragment endpoint (tailwind): /api/content/:app/:role/:page
   if (segs[0] === 'api' && segs[1] === 'content') {
-    if (segs.length !== 5) return send(res, 404, notFoundPage());
+    if (segs.length !== 5) return sendHtml(res, 404, notFoundPage(), prefix);
     const app = findApp(segs[2]);
     if (!app || app.status !== 'ready' || app.stack !== 'tailwind') {
-      return send(res, 404, notFoundPage(segs[2]));
+      return sendHtml(res, 404, notFoundPage(segs[2]), prefix);
+    }
+    if (!SAFE_SEG.test(segs[3]) || !SAFE_SEG.test(segs[4])) {
+      return sendHtml(res, 400, notFoundPage(), prefix);
     }
-    if (!SAFE_SEG.test(segs[3]) || !SAFE_SEG.test(segs[4])) return send(res, 400, notFoundPage());
     const content = readText(path.join(app.mockupDir, segs[3], 'content', segs[4] + '.html'));
     if (content === null) {
       return send(res, 404, '<div class="p-6 text-red-500">Content not found.</div>');
     }
-    return send(res, 200, content);
+    return sendHtml(res, 200, content, prefix);
   }
 
-  if (!SAFE_SEG.test(segs[0])) return send(res, 400, notFoundPage());
+  if (!SAFE_SEG.test(segs[0])) return sendHtml(res, 400, notFoundPage(), prefix);
   const app = findApp(segs[0]);
-  if (!app) return send(res, 404, notFoundPage(segs[0]));
-  if (app.status !== 'ready') return send(res, 200, notReadyPage(app));
+  if (!app) return sendHtml(res, 404, notFoundPage(segs[0]), prefix);
+  if (app.status !== 'ready') return sendHtml(res, 200, notReadyPage(app, prefix), prefix);
 
-  if (app.stack === 'shadcn') return routeShadcn(app, segs, res);
-  return routeTailwind(app, segs, res);
+  if (app.stack === 'shadcn') return routeShadcn(app, segs, res, prefix);
+  return routeTailwind(app, segs, res, prefix);
 }
 
 // ── Start ────────────────────────────────────────────────────────────────────
@@ -627,5 +683,7 @@ Mockup Hub
 3. Open http://localhost:4000 in your browser
    (the hub picks the first unused port from 4000; the exact URL is printed on start.
     Change port: the landing page's Port input, PORT=4100 npm start, or edit
-    mockup.config.json — or use Compound Context Studio's Mockup page Start/Stop Hub.)
+    mockup.config.json — or use Compound Context Studio's Mockup page Start/Stop Hub.
+    Inside the studio the hub is embedded through its same-origin proxy — no need to
+    expose this port when the studio itself is reachable.)
 ```