user app publishing system — build, serve, and use personal apps in workspace panels

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-27 17:23:24 +00:00
parent 4d30672adb
commit fd4d77a389
17 changed files with 873 additions and 48 deletions
@@ -0,0 +1,65 @@
+# AGENTS.md — Simple App Template
+
+## Project Structure
+
+```
+src/
+├── index.ts          # Bun server entry (routes, HMR)
+├── index.html        # HTML entry point
+├── frontend.tsx      # React root mount
+├── index.css         # Tailwind + global styles
+├── App.tsx           # Main React component
+└── components/       # UI components
+build.ts              # Build script (bun run build → dist/)
+.officerdev/
+└── meta.json         # Project metadata
+```
+
+## Tech Stack
+
+- **Runtime**: Bun
+- **Language**: TypeScript (strict)
+- **Framework**: React 19
+- **Styling**: Tailwind CSS v4
+- **UI**: shadcn/ui components (Radix UI primitives)
+- **Icons**: lucide-react
+
+## Build System
+
+- `bun dev` — starts dev server with HMR
+- `bun run build` — produces `dist/` via `build.ts`
+- Build uses `bun-plugin-tailwind` for CSS processing
+- Output: minified JS/CSS bundles + HTML in `dist/`
+
+## Publishing
+
+This project can be published as a standalone app in officer.dev.
+
+**Version**: Set in `package.json` → `version` field. Bump before republishing.
+
+**Icon**: When publishing, choose from these available lucide icon names:
+Activity, Airplay, Archive, BarChart3, Bell, Blocks, BookOpen, Box, BrainCircuit,
+Calendar, Camera, ChartPie, CircleDot, Cloud, Code, Compass, CreditCard, Database,
+FileText, Folder, Gamepad2, Globe, Heart, Home, Image, Inbox, Layers, Layout,
+LineChart, Link, List, Mail, Map, MessageCircle, Monitor, Music, Palette, PenTool,
+Play, Puzzle, Radio, Rocket, Search, Settings, ShoppingCart, Star, Sun, Table,
+Terminal, Timer, Users, Wand2, Zap
+
+## Iframe Constraints
+
+Published apps run inside an iframe in officer.dev workspace panels:
+
+- **Auth token injection**: The iframe URL includes a `?token=` param. A script is injected into the HTML `<head>` that automatically adds `Authorization: Bearer <token>` to all fetch/XHR requests.
+- **Path rewriting**: All absolute paths (`/api/...`, `/assets/...`) are rewritten to go through the serve proxy at `/api/app-serve/{slug}/`. Relative paths work as-is.
+- **No direct DOM access**: The app cannot access the parent frame.
+- **API access**: Use `fetch('/api/...')` — the injected script rewrites paths and adds auth headers automatically.
+
+## Coding Conventions
+
+- Functional components, arrow functions
+- No default exports — use named exports
+- Strict TypeScript, no `any`
+- Semicolons, single quotes (JS), double quotes (JSX)
+- 2-space indentation
+- Prefer composition over inheritance
+- Keep components small and focused
@@ -0,0 +1,46 @@
+// Injected into proxied HTML to intercept fetch/XHR/WebSocket so absolute paths
+// go through the proxy instead of hitting the host server directly.
+// Also injects JWT auth headers from localStorage for authenticated requests.
+export const proxyOverrideScript = (base: string) =>
+  `<script>(function(){` +
+  `var b=${JSON.stringify(base)},o=location.origin;` +
+  `function gt(){try{return localStorage.getItem("BEARER_TOKEN")||localStorage.getItem("PERTENTO_EDITOR_AUTH_TOKEN")}catch(e){return null}}` +
+  `function rw(u){` +
+  `if(typeof u==="string"){` +
+  `if(u.startsWith("/")&&!u.startsWith("//")&&!u.startsWith(b))return b+u;` +
+  `if(u.startsWith(o+"/")&&!u.startsWith(o+b))return o+b+u.slice(o.length);` +
+  `return u}` +
+  `if(u instanceof URL&&u.origin===o&&!u.pathname.startsWith(b))` +
+  `return new URL(o+b+u.pathname+u.search+u.hash);` +
+  `if(u instanceof Request){var p=new URL(u.url);` +
+  `if(p.origin===o&&!p.pathname.startsWith(b))` +
+  `return new Request(o+b+p.pathname+p.search+p.hash,u)}` +
+  `return u}` +
+  `var F=window.fetch;window.fetch=function(i,n){` +
+  `var t=gt();if(t){n=n||{};var h=new Headers(n.headers||{});` +
+  `if(!h.has("Authorization"))h.set("Authorization","Bearer "+t);n.headers=h}` +
+  `return F.call(this,rw(i),n)};` +
+  `var XO=XMLHttpRequest.prototype.open,XS=XMLHttpRequest.prototype.send;` +
+  `XMLHttpRequest.prototype.open=function(){arguments[1]=rw(arguments[1]);this._authSet=false;return XO.apply(this,arguments)};` +
+  `XMLHttpRequest.prototype.send=function(d){` +
+  `if(!this._authSet){var t=gt();if(t)try{this.setRequestHeader("Authorization","Bearer "+t)}catch(e){}}` +
+  `return XS.call(this,d)};` +
+  `var NWS=window.WebSocket;window.WebSocket=function(u,p){` +
+  `if(typeof u==="string"&&(u.startsWith("ws://"+location.host)||u.startsWith("wss://"+location.host)||u.startsWith("/"))){` +
+  `var t=gt();if(t){var sep=u.indexOf("?")>-1?"&":"?";u=u+sep+"token="+encodeURIComponent(t)}}` +
+  `return p!==undefined?new NWS(u,p):new NWS(u)};` +
+  `window.WebSocket.prototype=NWS.prototype;window.WebSocket.CONNECTING=NWS.CONNECTING;` +
+  `window.WebSocket.OPEN=NWS.OPEN;window.WebSocket.CLOSING=NWS.CLOSING;window.WebSocket.CLOSED=NWS.CLOSED;` +
+  `})()</script>`;
+
+// HTML: rewrite src/href/action attributes with absolute paths + inject fetch/XHR override
+export const rewriteHtml = (html: string, base: string) =>
+  html
+    .replace(/<head([^>]*)>/i, `<head$1>${proxyOverrideScript(base)}`)
+    .replace(/(href|src|action)="\/(?!\/)/g, `$1="${base}/`)
+    .replace(/(href|src|action)='\/(?!\/)/g, `$1='${base}/`)
+    .replace(/url\(\//g, `url(${base}/`);
+
+// JS/CSS: only rewrite /_bun/ asset paths (Bun dev server specific)
+export const rewriteAssetPaths = (text: string, base: string) =>
+  text.replace(/\/_bun\//g, `${base}/_bun/`);
@@ -0,0 +1,2 @@
+export { appsRouter, appServeRouter } from './router';
+export type { AppManifest } from './router';
@@ -0,0 +1,298 @@
+import type { Context } from 'hono';
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { readdir, cp, rm, mkdir } from 'node:fs/promises';
+import { createRouter } from '@@/create-router';
+import type { HonoVariables } from '@@/create-router';
+import { getUserAppsDir, getUserProjectsDir } from '@@/data-path';
+import * as errors from '@@/custom-errors';
+import { verify } from '@@/jwt';
+import { isTokenBlacklisted } from 'officerdb';
+import { rewriteHtml, rewriteAssetPaths } from '../_shared/html-rewrite';
+
+export type AppManifest = {
+  slug: string;
+  name: string;
+  version: string;
+  icon: string;
+  description: string;
+  sourceProject: string;
+  commitHash: string;
+  publishedAt: string;
+  buildDir: string;
+};
+
+// ── Protected routes (inside protectedRouter) ──
+
+export const appsRouter = createRouter();
+
+appsRouter.get('/', async (ctx) => {
+  const user = ctx.get('user');
+  const appsDir = getUserAppsDir(user.email);
+
+  if (!existsSync(appsDir)) return ctx.json({ apps: [] });
+
+  const entries = await readdir(appsDir, { withFileTypes: true });
+  const apps: AppManifest[] = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const manifestPath = join(appsDir, entry.name, 'manifest.json');
+    if (!existsSync(manifestPath)) continue;
+    try {
+      const manifest = JSON.parse(await Bun.file(manifestPath).text()) as AppManifest;
+      apps.push(manifest);
+    } catch {
+      // skip malformed manifests
+    }
+  }
+
+  return ctx.json({ apps });
+});
+
+appsRouter.post('/publish', async (ctx) => {
+  const user = ctx.get('user');
+  const body = ctx.get('body') as { projectSlug: string; name?: string; icon?: string; description?: string };
+  const { projectSlug, name, icon, description } = body;
+
+  if (!projectSlug) throw errors.BAD_REQUEST('Missing projectSlug');
+
+  const projectDir = join(getUserProjectsDir(user.email), projectSlug);
+  if (!existsSync(projectDir)) throw errors.BAD_REQUEST(`Project not found: ${projectSlug}`);
+
+  const pkgPath = join(projectDir, 'package.json');
+  if (!existsSync(pkgPath)) throw errors.BAD_REQUEST('No package.json found in project');
+
+  let pkgJson: { name?: string; version?: string; scripts?: Record<string, string> };
+  try {
+    pkgJson = JSON.parse(await Bun.file(pkgPath).text());
+  } catch {
+    throw errors.BAD_REQUEST('Failed to read package.json');
+  }
+
+  if (!pkgJson.scripts?.build) throw errors.BAD_REQUEST('No "build" script in package.json');
+
+  const version = pkgJson.version ?? '0.1.0';
+  const appSlug = projectSlug;
+  const appName = name ?? pkgJson.name ?? projectSlug;
+
+  // Read .officerdev/meta.json for fallback description
+  let metaDescription = '';
+  const metaPath = join(projectDir, '.officerdev', 'meta.json');
+  if (existsSync(metaPath)) {
+    try {
+      const meta = JSON.parse(await Bun.file(metaPath).text());
+      metaDescription = meta.description ?? '';
+    } catch {
+      // ignore
+    }
+  }
+
+  // Get git commit hash
+  let commitHash = 'unknown';
+  try {
+    const proc = Bun.spawn(['git', 'rev-parse', '--short', 'HEAD'], { cwd: projectDir, stdout: 'pipe', stderr: 'pipe' });
+    await proc.exited;
+    if (proc.exitCode === 0) {
+      commitHash = (await new Response(proc.stdout).text()).trim();
+    }
+  } catch {
+    // no git — that's fine
+  }
+
+  // Run build
+  const buildProc = Bun.spawn(['bun', 'run', 'build'], {
+    cwd: projectDir,
+    stdout: 'pipe',
+    stderr: 'pipe',
+    env: { ...process.env, NODE_ENV: 'production' },
+  });
+
+  const buildTimeout = setTimeout(() => buildProc.kill(), 60_000);
+  const exitCode = await buildProc.exited;
+  clearTimeout(buildTimeout);
+
+  if (exitCode !== 0) {
+    const stderr = await new Response(buildProc.stderr).text();
+    throw errors.BAD_REQUEST(`Build failed (exit ${exitCode}):\n${stderr.slice(-500)}`);
+  }
+
+  // Verify dist output
+  const distDir = join(projectDir, 'dist');
+  if (!existsSync(distDir)) throw errors.BAD_REQUEST('Build did not produce a dist/ directory');
+
+  const distFiles = await readdir(distDir);
+  const hasHtml = distFiles.some((f) => f.endsWith('.html'));
+  if (!hasHtml) throw errors.BAD_REQUEST('Build output has no HTML files');
+
+  // Copy to versioned directory
+  const appsDir = getUserAppsDir(user.email);
+  const appDir = join(appsDir, appSlug);
+  const versionDir = join(appDir, 'v', version);
+
+  await mkdir(versionDir, { recursive: true });
+  await cp(distDir, versionDir, { recursive: true });
+
+  // Write manifest
+  const manifest: AppManifest = {
+    slug: appSlug,
+    name: appName,
+    version,
+    icon: icon ?? 'Box',
+    description: description ?? metaDescription,
+    sourceProject: projectSlug,
+    commitHash,
+    publishedAt: new Date().toISOString(),
+    buildDir: `v/${version}`,
+  };
+
+  await Bun.write(join(appDir, 'manifest.json'), JSON.stringify(manifest, null, 2));
+
+  return ctx.json(manifest);
+});
+
+appsRouter.delete('/:slug', async (ctx) => {
+  const user = ctx.get('user');
+  const slug = ctx.req.param('slug');
+  if (!slug) throw errors.BAD_REQUEST('Missing slug');
+
+  const appDir = join(getUserAppsDir(user.email), slug);
+  if (!existsSync(appDir)) throw errors.NOT_FOUND('App not found');
+
+  await rm(appDir, { recursive: true, force: true });
+  return ctx.json({ ok: true });
+});
+
+// ── Static serving (outside protectedRouter) ──
+
+export const appServeRouter = createRouter();
+
+const MIME_TYPES: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'application/javascript; charset=utf-8',
+  '.mjs': 'application/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.ico': 'image/x-icon',
+  '.webp': 'image/webp',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.eot': 'application/vnd.ms-fontobject',
+  '.map': 'application/json',
+};
+
+const getMimeType = (filePath: string): string => {
+  const ext = filePath.slice(filePath.lastIndexOf('.'));
+  return MIME_TYPES[ext] ?? 'application/octet-stream';
+};
+
+type ValidateResult = { email: string } | null;
+
+async function validateToken(req: Request): Promise<ValidateResult> {
+  const authHeader = req.headers.get('authorization');
+  const token = authHeader?.startsWith('Bearer ') ? authHeader.slice(7) : new URL(req.url).searchParams.get('token');
+  if (!token) return null;
+  try {
+    const payload = await verify(token);
+    if (!payload?.email) return null;
+    if (payload.jti && (await isTokenBlacklisted(payload.jti))) return null;
+    return { email: payload.email };
+  } catch {
+    return null;
+  }
+}
+
+appServeRouter.all('/:slug/*', async (ctx) => {
+  const slug = ctx.req.param('slug');
+  if (!slug) return ctx.text('Not found', 404);
+
+  // Validate auth — HTML requests require token, assets check referer
+  const pathname = new URL(ctx.req.url).pathname;
+  const isHtml =
+    ctx.req.header('accept')?.includes('text/html') ||
+    pathname.endsWith('.html') ||
+    !pathname.slice(pathname.lastIndexOf('/') + 1).includes('.');
+
+  const validated = await validateToken(ctx.req.raw);
+
+  if (!validated) {
+    // For non-HTML assets, try referer-based resolution
+    if (!isHtml) {
+      const referer = ctx.req.header('referer');
+      if (referer) {
+        const match = referer.match(/\/api\/app-serve\/([^/?]+)/);
+        if (match) {
+          // Extract token from referer URL if present
+          try {
+            const refUrl = new URL(referer);
+            const refToken = refUrl.searchParams.get('token');
+            if (refToken) {
+              const payload = await verify(refToken);
+              if (payload?.email) {
+                if (!payload.jti || !(await isTokenBlacklisted(payload.jti))) {
+                  return serveFile(ctx, payload.email, slug);
+                }
+              }
+            }
+          } catch {
+            // fall through
+          }
+        }
+      }
+    }
+    return ctx.text('Unauthorized', 401);
+  }
+
+  return serveFile(ctx, validated.email, slug);
+});
+
+async function serveFile(ctx: Context<{ Variables: HonoVariables }>, email: string, slug: string) {
+  const appDir = join(getUserAppsDir(email), slug);
+  const manifestPath = join(appDir, 'manifest.json');
+
+  if (!existsSync(manifestPath)) return ctx.text('App not found', 404);
+
+  let manifest: AppManifest;
+  try {
+    manifest = JSON.parse(await Bun.file(manifestPath).text());
+  } catch {
+    return ctx.text('Invalid manifest', 500);
+  }
+
+  const buildDir = join(appDir, manifest.buildDir);
+  const prefix = `/api/app-serve/${slug}`;
+
+  const url = new URL(ctx.req.url);
+  let filePath = url.pathname.replace(prefix, '') || '/';
+  if (filePath === '/') filePath = '/index.html';
+
+  const fullPath = join(buildDir, filePath);
+
+  // Security: prevent directory traversal
+  if (!fullPath.startsWith(buildDir)) return ctx.text('Forbidden', 403);
+
+  // If file doesn't exist, serve index.html for SPA routing
+  const targetPath = existsSync(fullPath) ? fullPath : join(buildDir, 'index.html');
+  if (!existsSync(targetPath)) return ctx.text('Not found', 404);
+
+  const file = Bun.file(targetPath);
+  const mimeType = getMimeType(targetPath);
+  const needsRewrite =
+    mimeType.includes('text/html') || mimeType.includes('javascript') || mimeType.includes('text/css');
+
+  if (needsRewrite) {
+    const content = await file.text();
+    const rewritten = mimeType.includes('text/html')
+      ? rewriteHtml(content, prefix)
+      : rewriteAssetPaths(content, prefix);
+    return new Response(rewritten, { headers: { 'content-type': mimeType } });
+  }
+
+  return new Response(file, { headers: { 'content-type': mimeType } });
+}
@@ -8,6 +8,7 @@ import { CustomError } from '@@/custom-errors';
 import * as errors from '@@/custom-errors';
 import { verify } from '@@/jwt';
 import { isTokenBlacklisted } from 'officerdb';
+import { rewriteHtml, rewriteAssetPaths } from '../_shared/html-rewrite';

 export const devServerRouter = createRouter();
 export const devServerProxyRouter = createRouter();
@@ -311,49 +312,3 @@ devServerProxyRouter.all('/:proxyId/*', async (ctx) => {
  return ctx.text('No dev server running', 404);
 });

-// Injected into proxied HTML to intercept fetch/XHR/WebSocket so absolute paths
-// go through the proxy instead of hitting the host server directly.
-// Also injects JWT auth headers from localStorage for authenticated requests.
-const proxyOverrideScript = (base: string) =>
-  `<script>(function(){` +
-  `var b=${JSON.stringify(base)},o=location.origin;` +
-  `function gt(){try{return localStorage.getItem("BEARER_TOKEN")||localStorage.getItem("PERTENTO_EDITOR_AUTH_TOKEN")}catch(e){return null}}` +
-  `function rw(u){` +
-  `if(typeof u==="string"){` +
-  `if(u.startsWith("/")&&!u.startsWith("//")&&!u.startsWith(b))return b+u;` +
-  `if(u.startsWith(o+"/")&&!u.startsWith(o+b))return o+b+u.slice(o.length);` +
-  `return u}` +
-  `if(u instanceof URL&&u.origin===o&&!u.pathname.startsWith(b))` +
-  `return new URL(o+b+u.pathname+u.search+u.hash);` +
-  `if(u instanceof Request){var p=new URL(u.url);` +
-  `if(p.origin===o&&!p.pathname.startsWith(b))` +
-  `return new Request(o+b+p.pathname+p.search+p.hash,u)}` +
-  `return u}` +
-  `var F=window.fetch;window.fetch=function(i,n){` +
-  `var t=gt();if(t){n=n||{};var h=new Headers(n.headers||{});` +
-  `if(!h.has("Authorization"))h.set("Authorization","Bearer "+t);n.headers=h}` +
-  `return F.call(this,rw(i),n)};` +
-  `var XO=XMLHttpRequest.prototype.open,XS=XMLHttpRequest.prototype.send;` +
-  `XMLHttpRequest.prototype.open=function(){arguments[1]=rw(arguments[1]);this._authSet=false;return XO.apply(this,arguments)};` +
-  `XMLHttpRequest.prototype.send=function(d){` +
-  `if(!this._authSet){var t=gt();if(t)try{this.setRequestHeader("Authorization","Bearer "+t)}catch(e){}}` +
-  `return XS.call(this,d)};` +
-  `var NWS=window.WebSocket;window.WebSocket=function(u,p){` +
-  `if(typeof u==="string"&&(u.startsWith("ws://"+location.host)||u.startsWith("wss://"+location.host)||u.startsWith("/"))){` +
-  `var t=gt();if(t){var sep=u.indexOf("?")>-1?"&":"?";u=u+sep+"token="+encodeURIComponent(t)}}` +
-  `return p!==undefined?new NWS(u,p):new NWS(u)};` +
-  `window.WebSocket.prototype=NWS.prototype;window.WebSocket.CONNECTING=NWS.CONNECTING;` +
-  `window.WebSocket.OPEN=NWS.OPEN;window.WebSocket.CLOSING=NWS.CLOSING;window.WebSocket.CLOSED=NWS.CLOSED;` +
-  `})()</script>`;
-
-// HTML: rewrite src/href/action attributes with absolute paths + inject fetch/XHR override
-const rewriteHtml = (html: string, base: string) =>
-  html
-    .replace(/<head([^>]*)>/i, `<head$1>${proxyOverrideScript(base)}`)
-    .replace(/(href|src|action)="\/(?!\/)/g, `$1="${base}/`)
-    .replace(/(href|src|action)='\/(?!\/)/g, `$1='${base}/`)
-    .replace(/url\(\//g, `url(${base}/`);
-
-// JS/CSS: only rewrite /_bun/ asset paths (Bun dev server specific)
-const rewriteAssetPaths = (text: string, base: string) =>
-  text.replace(/\/_bun\//g, `${base}/_bun/`);
@@ -92,3 +92,5 @@ export const getAttachmentsDir = (email: string, provider: 'claude' | 'opencode'


 export const getUserEmailDir = (email: string) => join(DATA_PATH, email, 'Gmail', 'emails');
+
+export const getUserAppsDir = (email: string) => join(DATA_PATH, email, 'apps');
@@ -26,6 +26,7 @@ import { queueRouter } from './api/queue/queue';
 import { emailRouter } from './api/email/email';
 import { channelsRouter } from './channels/routes';
 import { browserRouter } from './api/browser/router';
+import { appsRouter, appServeRouter } from './api/apps';
 import { CustomError } from './custom-errors';
 import { userMiddleware, bodyParser, isOriginAllowed, superAdminMiddleware } from './_middlewares';

@@ -51,6 +52,7 @@ honoServer.route('/api/auth', authRouter);
 honoServer.route('/api/landing-page-data', landingPageDataRouter);
 honoServer.route('/api/waitlist', waitlistRouter);
 honoServer.route('/api/dev-server-proxy', devServerProxyRouter);
+honoServer.route('/api/app-serve', appServeRouter);
 honoServer.get('/api/integrations/google/callback', googleCallbackHandler);
 honoServer.get('/api/server-settings/onboarding-complete', async (ctx) => {
  const { readServerSettings } = await import('officerdb');
@@ -83,6 +85,7 @@ protectedRouter.route('/queue', queueRouter);
 protectedRouter.route('/email', emailRouter);
 protectedRouter.route('/channels', channelsRouter);
 protectedRouter.route('/browser', browserRouter);
+protectedRouter.route('/apps', appsRouter);
 protectedRouter.route('/', piRestRouter);

 honoServer.route('/api', protectedRouter);
@@ -1,3 +1,4 @@
+import { useEffect, useRef } from 'react';
 import { appRegistryMetas as fileBrowserMetas } from '../apps/FileBrowser';
 import { appRegistryMetas as terminalMetas } from '../apps/Terminal';
 import { appRegistryMetas as codeEditorMetas } from '../apps/CodeEditor';
@@ -9,10 +10,34 @@ import { appRegistryMetas as chatHistoryMetas } from '../apps/ChatHistory';
 import { appRegistryMetas as previewMetas } from '../apps/Preview';
 import { appRegistryMetas as widgetMetas } from '../apps/Widgets';
 import { useAppRegistry } from './useAppRegistry';
+import { useUserApps } from 'state/useUserApps';
+import { createUserAppPanel } from '../apps/UserApp/UserAppPanel';
+import { createUserAppHeader } from '../apps/UserApp/UserAppHeader';
+import { resolveIcon } from '../utils/resolve-icon';

 const apps = [...fileBrowserMetas, ...terminalMetas, ...codeEditorMetas, ...chatMetas, ...fileViewerMetas, ...workspaceMetas, ...projectMetas, ...chatHistoryMetas, ...previewMetas, ...widgetMetas];

 export const AppRegistry = () => {
-  useAppRegistry(apps);
+  const { registerApp } = useAppRegistry(apps);
+  const { apps: userApps, email } = useUserApps();
+  const registeredRef = useRef(new Set<string>());
+
+  useEffect(() => {
+    if (!email || userApps.length === 0) return;
+
+    for (const app of userApps) {
+      const key = `${email}/${app.slug}`;
+      if (registeredRef.current.has(key)) continue;
+      registeredRef.current.add(key);
+
+      registerApp(key, {
+        name: app.name,
+        icon: resolveIcon(app.icon),
+        component: createUserAppPanel(app.slug),
+        header: createUserAppHeader(app.name, resolveIcon(app.icon)),
+      });
+    }
+  }, [userApps, email, registerApp]);
+
  return null;
 };
@@ -1,12 +1,13 @@
 import { useState } from 'react';
 import { Link, useLocation, useNavigate } from 'react-router';
-import { FolderKanban, Plus, Pencil, Trash2, Search } from 'lucide-react';
+import { FolderKanban, Plus, Pencil, Trash2, Search, Rocket } from 'lucide-react';
 import { useQueryClient } from '@tanstack/react-query';
 import { useGlobal } from 'hooks/useGlobal';
 import { useClient } from 'hooks/useClient';
 import { generateSlug } from 'helpers/slug';
 import { useWorkspacesState } from 'state/useWorkspacesState';
 import type { ProjectDefinition, ProjectType } from '../../components/Workspace';
+import { PublishDialog } from './PublishDialog';
 import {
  AlertDialog,
  AlertDialogAction,
@@ -53,6 +54,7 @@ export const ProjectListApp = () => {

  const [search, setSearch] = useState('');
  const [deleting, setDeleting] = useState<ProjectDefinition | null>(null);
+  const [publishing, setPublishing] = useState<ProjectDefinition | null>(null);
  const isProjectsPage = location.pathname === '/projects';
  const filtered = search
    ? projects.filter((p) => {
@@ -81,6 +83,11 @@ export const ProjectListApp = () => {
    setDeleting(p);
  };

+  const handlePublish = (ev: React.MouseEvent, p: ProjectDefinition) => {
+    ev.stopPropagation();
+    setPublishing(p);
+  };
+
  const confirmDelete = () => {
    if (!deleting) return;
    // Optimistic: remove from cache immediately
@@ -166,6 +173,14 @@ export const ProjectListApp = () => {
            <span className="text-[10px] text-duck-dark/30 shrink-0">{PROJECT_TYPE_LABELS[p.projectType]}</span>
            {isProjectsPage && (
              <>
+                <button
+                  type="button"
+                  onClick={(ev) => handlePublish(ev, p)}
+                  className="shrink-0 p-1 rounded text-duck-dark/20 md:opacity-0 md:group-hover:opacity-100 hover:text-blue-400 transition-opacity cursor-pointer"
+                  title="Publish"
+                >
+                  <Rocket className="h-3.5 w-3.5" />
+                </button>
                <button
                  type="button"
                  onClick={(ev) => handleEdit(ev, p)}
@@ -207,6 +222,15 @@ export const ProjectListApp = () => {
          </AlertDialogFooter>
        </AlertDialogContent>
      </AlertDialog>
+
+      {publishing && (
+        <PublishDialog
+          open={true}
+          onOpenChange={(open) => { if (!open) setPublishing(null); }}
+          projectSlug={publishing.id}
+          projectName={publishing.name}
+        />
+      )}
    </div>
  );
 };
@@ -0,0 +1,177 @@
+import { useState } from 'react';
+import { Loader2, Rocket } from 'lucide-react';
+import { toast } from 'sonner';
+import { useClient } from 'hooks/useClient';
+import { useUserApps } from 'state/useUserApps';
+import {
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogDescription,
+} from '@/components/ui/dialog';
+import { resolveIcon, availableIconNames } from '../../utils/resolve-icon';
+
+type PublishDialogProps = {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  projectSlug: string;
+  projectName: string;
+};
+
+export const PublishDialog = ({ open, onOpenChange, projectSlug, projectName }: PublishDialogProps) => {
+  const client = useClient();
+  const { refetch } = useUserApps();
+
+  const [name, setName] = useState(projectName);
+  const [icon, setIcon] = useState('Globe');
+  const [description, setDescription] = useState('');
+  const [publishing, setPublishing] = useState(false);
+  const [version, setVersion] = useState<string | null>(null);
+  const [iconPickerOpen, setIconPickerOpen] = useState(false);
+
+  // Fetch version from package.json when dialog opens
+  const fetchVersion = async () => {
+    try {
+      const res = await client.get<{ content: string }>(`/file-browser/read?path=/Projects/${projectSlug}/package.json`);
+      const pkg = JSON.parse(res.content);
+      setVersion(pkg.version ?? '0.1.0');
+    } catch {
+      setVersion('0.1.0');
+    }
+  };
+
+  const handleOpenChange = (nextOpen: boolean) => {
+    if (nextOpen) {
+      setName(projectName);
+      setIcon('Globe');
+      setDescription('');
+      setPublishing(false);
+      fetchVersion();
+    }
+    onOpenChange(nextOpen);
+  };
+
+  const handlePublish = async () => {
+    setPublishing(true);
+    try {
+      await client.post('/apps/publish', {
+        projectSlug,
+        name,
+        icon,
+        description,
+      });
+      refetch();
+      toast.success(`Published ${name} successfully`);
+      onOpenChange(false);
+    } catch (err: unknown) {
+      const msg = err && typeof err === 'object' && 'message' in err ? String(err.message) : 'Publish failed';
+      toast.error(msg);
+    } finally {
+      setPublishing(false);
+    }
+  };
+
+  const SelectedIcon = resolveIcon(icon);
+
+  return (
+    <Dialog open={open} onOpenChange={handleOpenChange}>
+      <DialogContent className="max-w-md">
+        <DialogHeader>
+          <DialogTitle className="flex items-center gap-2">
+            <Rocket className="h-4 w-4" />
+            Publish App
+          </DialogTitle>
+          <DialogDescription>
+            Build and publish <strong>{projectSlug}</strong> as a standalone app.
+          </DialogDescription>
+        </DialogHeader>
+
+        <div className="flex flex-col gap-3">
+          <label className="flex flex-col gap-1">
+            <span className="text-xs text-muted-foreground">App Name</span>
+            <input
+              type="text"
+              value={name}
+              onChange={(ev) => setName(ev.target.value)}
+              className="rounded-md border border-duck-dark/15 bg-transparent px-3 py-1.5 text-sm focus:outline-none focus:ring-1 focus:ring-emerald-500/30"
+            />
+          </label>
+
+          <label className="flex flex-col gap-1">
+            <span className="text-xs text-muted-foreground">Icon</span>
+            <div className="relative">
+              <button
+                type="button"
+                onClick={() => setIconPickerOpen(!iconPickerOpen)}
+                className="flex items-center gap-2 rounded-md border border-duck-dark/15 bg-transparent px-3 py-1.5 text-sm cursor-pointer hover:bg-duck-dark/5 w-full"
+              >
+                <SelectedIcon className="h-4 w-4" />
+                <span>{icon}</span>
+              </button>
+              {iconPickerOpen && (
+                <div className="absolute top-full left-0 mt-1 z-50 bg-background border border-duck-dark/15 rounded-md shadow-lg p-2 grid grid-cols-8 gap-1 max-h-48 overflow-y-auto w-full">
+                  {availableIconNames.map((iconName) => {
+                    const IconComp = resolveIcon(iconName);
+                    return (
+                      <button
+                        key={iconName}
+                        type="button"
+                        onClick={() => {
+                          setIcon(iconName);
+                          setIconPickerOpen(false);
+                        }}
+                        className={`p-1.5 rounded cursor-pointer transition-colors ${
+                          icon === iconName ? 'bg-emerald-500/20 text-emerald-400' : 'hover:bg-duck-dark/10'
+                        }`}
+                        title={iconName}
+                      >
+                        <IconComp className="h-4 w-4" />
+                      </button>
+                    );
+                  })}
+                </div>
+              )}
+            </div>
+          </label>
+
+          <label className="flex flex-col gap-1">
+            <span className="text-xs text-muted-foreground">Description</span>
+            <textarea
+              value={description}
+              onChange={(ev) => setDescription(ev.target.value)}
+              rows={2}
+              className="rounded-md border border-duck-dark/15 bg-transparent px-3 py-1.5 text-sm focus:outline-none focus:ring-1 focus:ring-emerald-500/30 resize-none"
+            />
+          </label>
+
+          {version && (
+            <div className="flex items-center gap-2 text-xs text-muted-foreground">
+              <span>Version:</span>
+              <span className="font-mono">{version}</span>
+            </div>
+          )}
+
+          <button
+            type="button"
+            disabled={publishing || !name.trim()}
+            onClick={handlePublish}
+            className="flex items-center justify-center gap-2 rounded-md bg-emerald-500 hover:bg-emerald-500/90 text-white py-2 px-4 text-sm font-medium transition-colors disabled:opacity-50 disabled:cursor-not-allowed cursor-pointer"
+          >
+            {publishing ? (
+              <>
+                <Loader2 className="h-4 w-4 animate-spin" />
+                Publishing...
+              </>
+            ) : (
+              <>
+                <Rocket className="h-4 w-4" />
+                Publish
+              </>
+            )}
+          </button>
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+};
@@ -0,0 +1,31 @@
+import type { ComponentType } from 'react';
+import type { LucideIcon } from 'lucide-react';
+import { RefreshCw } from 'lucide-react';
+import { useGlobal } from 'hooks/useGlobal';
+
+type UserAppHeaderProps = { panelId: string };
+
+export const createUserAppHeader = (name: string, Icon: LucideIcon): ComponentType<UserAppHeaderProps> => {
+  const UserAppHeader = ({ panelId }: UserAppHeaderProps) => {
+    const iframeRefreshKey = `USER_APP_REFRESH_${panelId}`;
+    const [, setRefresh] = useGlobal<number>(iframeRefreshKey, 0);
+
+    return (
+      <>
+        <Icon className="h-3.5 w-3.5 text-duck-teal shrink-0" />
+        <span className="text-xs font-medium shrink-0">{name}</span>
+        <button
+          type="button"
+          onClick={() => setRefresh((k) => k + 1)}
+          className="p-0.5 rounded hover:bg-black/10 transition-colors cursor-pointer shrink-0"
+          title="Refresh"
+        >
+          <RefreshCw className="h-3 w-3" />
+        </button>
+      </>
+    );
+  };
+
+  UserAppHeader.displayName = `UserAppHeader(${name})`;
+  return UserAppHeader;
+};
@@ -0,0 +1,41 @@
+import type { ComponentType } from 'react';
+import { useState, useCallback } from 'react';
+import { Loader2 } from 'lucide-react';
+import { useClient } from 'hooks/useClient';
+
+type UserAppPanelProps = { panelId: string };
+
+export const createUserAppPanel = (slug: string): ComponentType<UserAppPanelProps> => {
+  const UserAppPanel = ({ panelId }: UserAppPanelProps) => {
+    const client = useClient();
+    const [iframeKey, setIframeKey] = useState(0);
+    const [loading, setLoading] = useState(true);
+
+    const token = client.token;
+    const src = token
+      ? `/api/app-serve/${slug}/?token=${encodeURIComponent(token)}`
+      : `/api/app-serve/${slug}/`;
+
+    const handleLoad = useCallback(() => setLoading(false), []);
+
+    return (
+      <div className="relative h-full w-full">
+        {loading && (
+          <div className="absolute inset-0 flex items-center justify-center text-duck-dark/50">
+            <Loader2 className="h-5 w-5 animate-spin" />
+          </div>
+        )}
+        <iframe
+          key={iframeKey}
+          src={src}
+          className="h-full w-full border-none"
+          title={slug}
+          onLoad={handleLoad}
+        />
+      </div>
+    );
+  };
+
+  UserAppPanel.displayName = `UserAppPanel(${slug})`;
+  return UserAppPanel;
+};
@@ -0,0 +1,2 @@
+export { createUserAppPanel } from './UserAppPanel';
+export { createUserAppHeader } from './UserAppHeader';
@@ -17,6 +17,8 @@ export { TerminalView } from './apps/Terminal';
 export type { TerminalViewProps } from './apps/Terminal';
 export { WorkspaceListApp, WorkspacePreview, SELECTED_WORKSPACE_KEY, CREATING_WORKSPACE_KEY, EDITING_WORKSPACE_KEY, NEW_WS_NAME_KEY, NEW_WS_DESC_KEY, NEW_WS_TEMPLATE_KEY } from './apps/Workspaces';
 export { ProjectListApp, ProjectPreview, SELECTED_PROJECT, CREATING_PROJECT, EDITING_PROJECT, NEW_PROJ_NAME, NEW_PROJ_DESC, NEW_PROJ_TEMPLATE, NEW_PROJ_TYPE, NEW_PROJ_HAS_BACKEND, NEW_PROJ_HAS_AUTH, NEW_PROJ_PREVIEW_LAYOUT } from './apps/Projects';
+export { createUserAppPanel, createUserAppHeader } from './apps/UserApp';
+export { resolveIcon, availableIconNames } from './utils/resolve-icon';

 // Workspace
 export { WorkspaceView, WorkspaceLayout, WorkspaceProvider, useWorkspace } from './components/Workspace';
@@ -0,0 +1,116 @@
+import type { LucideIcon } from 'lucide-react';
+import {
+  Activity,
+  Airplay,
+  Archive,
+  BarChart3,
+  Bell,
+  Blocks,
+  BookOpen,
+  Box,
+  BrainCircuit,
+  Calendar,
+  Camera,
+  ChartPie,
+  CircleDot,
+  Cloud,
+  Code,
+  Compass,
+  CreditCard,
+  Database,
+  FileText,
+  Folder,
+  Gamepad2,
+  Globe,
+  Heart,
+  Home,
+  Image,
+  Inbox,
+  Layers,
+  Layout,
+  LineChart,
+  Link,
+  List,
+  Mail,
+  Map,
+  MessageCircle,
+  Monitor,
+  Music,
+  Palette,
+  PenTool,
+  Play,
+  Puzzle,
+  Radio,
+  Rocket,
+  Search,
+  Settings,
+  ShoppingCart,
+  Star,
+  Sun,
+  Table,
+  Terminal,
+  Timer,
+  Users,
+  Wand2,
+  Zap,
+} from 'lucide-react';
+
+const ICON_MAP: Record<string, LucideIcon> = {
+  Activity,
+  Airplay,
+  Archive,
+  BarChart3,
+  Bell,
+  Blocks,
+  BookOpen,
+  Box,
+  BrainCircuit,
+  Calendar,
+  Camera,
+  ChartPie,
+  CircleDot,
+  Cloud,
+  Code,
+  Compass,
+  CreditCard,
+  Database,
+  FileText,
+  Folder,
+  Gamepad2,
+  Globe,
+  Heart,
+  Home,
+  Image,
+  Inbox,
+  Layers,
+  Layout,
+  LineChart,
+  Link,
+  List,
+  Mail,
+  Map,
+  MessageCircle,
+  Monitor,
+  Music,
+  Palette,
+  PenTool,
+  Play,
+  Puzzle,
+  Radio,
+  Rocket,
+  Search,
+  Settings,
+  ShoppingCart,
+  Star,
+  Sun,
+  Table,
+  Terminal,
+  Timer,
+  Users,
+  Wand2,
+  Zap,
+};
+
+export const resolveIcon = (name: string): LucideIcon => ICON_MAP[name] ?? Box;
+
+export const availableIconNames = Object.keys(ICON_MAP);
@@ -14,3 +14,5 @@ export type { ResourceSummary, ResourceDetail, PingResult } from './useResources
 export { useChatSessions } from './useChatSessions';
 export type { UseChatSessionsType } from './useChatSessions';
 export { useChatGroups } from './useChatGroups';
+export { useUserApps } from './useUserApps';
+export type { AppManifest } from './useUserApps';
@@ -0,0 +1,34 @@
+import { useAuth } from 'hooks/useAuth';
+import { useClient } from 'hooks/useClient';
+import { useQuery, useQueryClient } from '@tanstack/react-query';
+
+export type AppManifest = {
+  slug: string;
+  name: string;
+  version: string;
+  icon: string;
+  description: string;
+  sourceProject: string;
+  commitHash: string;
+  publishedAt: string;
+  buildDir: string;
+};
+
+const QUERY_KEY = ['USER_APPS'] as const;
+
+export function useUserApps() {
+  const client = useClient();
+  const queryClient = useQueryClient();
+  const { user, isAuthenticated } = useAuth();
+
+  const { data: apps = [], isLoading } = useQuery<AppManifest[]>({
+    queryKey: QUERY_KEY,
+    enabled: isAuthenticated,
+    queryFn: () => client.get<{ apps: AppManifest[] }>('/apps').then((r) => r.apps),
+    staleTime: 30_000,
+  });
+
+  const refetch = () => queryClient.invalidateQueries({ queryKey: QUERY_KEY });
+
+  return { apps, isLoading, refetch, email: user?.email ?? '' };
+}