@autono/open-pages 0.8.0 → 0.9.0

package/skills/create-theme/SKILL.md

@@ -1,21 +1,22 @@
 ---
 name: create-theme
-description: Use this skill when the user wants to create, draft, author, or extract a theme in this open-pages repo. Triggers on phrases like "create a theme", "make a theme called X", "extract a theme from <page>", "match our brand", "build a design system from these screenshots", "apply this shadcn preset". Produces a three-file bundle under `themes/` — `<id>.md` (direction, fonts, component notes, token table), `<id>.css` (the shadcn token overrides), and `<id>.demo.tsx` (a demo page composed from `ui/` components that the workspace's Themes panel previews live). Do NOT use for editing real pages — only for authoring the theme bundle.
+description: Use this skill when the user wants to create, draft, author, or extract a theme in this open-pages repo. Triggers on phrases like "create a theme", "make a theme called X", "extract a theme from <page>", "match our brand", "build a design system from these screenshots", "apply this shadcn preset", "email theme for X". Produces a bundle under `themes/` — `<id>.md` (direction, fonts, component notes, token table), `<id>.css` (the shadcn token overrides), and `<id>.demo.tsx` (a demo page composed from `ui/` components that the workspace's Themes panel previews live) — plus `components/email/theme-<id>.ts`, the same palette as an emailcn EmailTheme so emails match. Do NOT use for editing real pages — only for authoring the theme bundle.
 ---
 
 # Create a theme
 
 A theme is a **token set**. Every workspace ships the full shadcn/ui set under `ui/`, and every component reads its colors, radius, and fonts from the CSS variables in `styles/globals.css` (`--background`, `--primary`, `--radius`, …). A theme overrides those variables; every component and every token-styled page restyles at once. Nothing is copied into pages.
 
-The bundle is three files sharing one stem under `themes/`:
+The bundle is three files sharing one stem under `themes/`, plus one under `components/email/`:
 
 1. `themes/<id>.md` — agent-facing direction: aesthetic, fonts, how to use the components in this theme, and a table of token → value. This is what `create-page` reads when an author picks the theme.
 2. `themes/<id>.css` — **only** `:root { … }` and `.dark { … }` blocks overriding the shadcn tokens (plus an optional Google Fonts `@import url(…)` at the very top). No `@theme` block, no Tailwind import, no selectors beyond those two.
 3. `themes/<id>.demo.tsx` — a runnable page module (same shape as `pages/<id>/index.tsx`, **one default-exported component**) composed from `@/ui/*` components so the tokens are shown on real parts. The Themes panel renders it with `<id>.css` injected automatically; the demo does not set `meta.theme`.
+4. `components/email/theme-<id>.ts` — the same palette as an emailcn `EmailTheme` object (hex colors, px sizes, font stacks), generated from the CSS by a script (Step 6b). Mail clients cannot read CSS variables or `oklch()`, so this is how emails under `emails/` pick the theme up; the `create-email` skill consumes it.
 
-A page opts in with `meta.theme: '<id>'`; the runtime injects `themes/<id>.css` into that page's preview frame and into its export.
+A page opts in with `meta.theme: '<id>'`; the runtime injects `themes/<id>.css` into that page's preview frame and into its export. An email opts in by passing the exported theme object to `createEmailTailwindConfig` (or to a section's `theme` prop).
 
-You only write the three theme files. Never modify pages, `ui/`, `styles/globals.css`, or configuration. The token names and how pages consume them live in the **`page-authoring`** skill (`references/typography-and-color.md`) — read it first. Component props and variants: the **`shadcn`** skill.
+You only write these four files. Never modify pages, emails, `ui/`, `styles/globals.css`, or configuration. The token names and how pages consume them live in the **`page-authoring`** skill (`references/typography-and-color.md`) — read it first. Component props and variants: the **`shadcn`** skill.
 
 ## Step 1 — Identify the input source
 
@@ -150,6 +151,11 @@ Notes on how to use the `ui/` set so pages feel like this theme — which varian
 - Feedback: `<Alert>`, `sonner` toasts.
 - Avoid: gradients | shadows | more than one accent | … (whatever the theme forbids).
 
+## Email
+
+- `components/email/theme-<id>.ts` exports `<id>Theme`, generated from this CSS. Emails pass it to `createEmailTailwindConfig` or to a section's `theme` prop.
+- Any email-specific notes: which emailcn sections suit the brand, whether headings keep the serif via `<Font>`, what the footer must carry.
+
 ## Aesthetic
 
 One paragraph. What it feels like, the references it draws on, what to avoid. Commit to a single direction.
@@ -179,6 +185,21 @@ Contract:
 - Root element: `min-h-screen bg-background text-foreground` (with `dark` if the theme is dark by default). Everything token-styled — the demo is the proof that pages need no raw colors.
 - Realistic content, not lorem ipsum. Must look right at Mobile (390px) as well as Desktop. Self-contained: no page-local assets.
 
+## Step 6b — Generate `components/email/theme-<id>.ts`
+
+Emails are rendered by react-email with emailcn's `createEmailTailwindConfig(theme)`, which takes a plain `EmailTheme` object, not CSS variables. Derive it from the finished CSS with the script that ships with this skill:
+
+```bash
+# once per workspace, if components/email/email-theme.ts does not exist yet
+npx shadcn@latest add @emailcn/react-email/theme-default
+
+node .agents/skills/create-theme/references/email-theme-from-css.mjs themes/<id>.css <id> > components/email/theme-<id>.ts
+```
+
+The script reads the `:root` block (emails are light documents; the `.dark` block is not used), converts every color to hex, and maps roles by `references/email-theme.md`: `--background` → `colorBackground`, `--foreground` → `colorText`, `--muted` / `--muted-foreground` → `colorBackgroundMuted` / `colorTextMuted`, `--secondary` → `colorBackgroundSubtle`, `--primary` / `--primary-foreground` → `colorPrimary` / `colorPrimaryForeground` and the primary button, `--border` → `colorBorder` and the secondary button's border, `--destructive` → `colorDanger`, `--radius` → `borderRadius` in px, `--font-sans` / `--font-mono` → `fontFamily` / `fontFamilyMono` with `var()` entries dropped. Success, warning, the type scale, and spacing keep emailcn's defaults because the CSS has no opinion on them.
+
+Open the generated file and review it: a web font in `fontFamily` needs a web-safe fallback after it (the script keeps whatever fallbacks the CSS listed), and `colorPrimaryHover` / `colorTextSubtle` are shifted from their base tokens, so glance that they still read well. Do not restyle it by hand beyond that; re-run the script after changing the CSS so the two never drift.
+
 ## Step 7 — Self-review
 
 - [ ] `themes/<id>.css` overrides every shadcn token in both `:root` and `.dark`, in OKLCH, with only those two selectors (plus an optional font `@import`).
@@ -187,15 +208,17 @@ Contract:
 - [ ] Typography names only fonts the CSS loads (or the system stack).
 - [ ] "Components in this theme" gives variant guidance for buttons, cards, nav, data, feedback.
 - [ ] Demo `.tsx` default-exports one component, imports only `@/ui/*`, uses semantic tokens only, shows both modes, nothing overflows on mobile.
-- [ ] All three files written with the same stem. No page changes, no `ui/` changes, no `styles/globals.css` changes.
+- [ ] `components/email/theme-<id>.ts` generated from the CSS, exports `<id>Theme` typed as `EmailTheme`, hex colors only, and its font stacks end in a web-safe family.
+- [ ] All four files written with the same stem. No page or email changes, no `ui/` changes, no `styles/globals.css` changes.
 
 ## Step 8 — Hand off
 
 Tell the user:
 
-- The theme id and the three file paths.
+- The theme id and the four file paths.
 - That the Themes panel in the workspace (`http://localhost:5173/themes`) previews the demo live, and `/create-page` will list the theme as a picker option on its next run.
 - That any existing page can adopt it by setting `meta.theme: '<id>'` — no other change.
+- That emails adopt it by importing `<id>Theme` from `@/components/email/theme-<id>` and passing it to `createEmailTailwindConfig` (or to an emailcn section's `theme` prop); `/create-email` offers it whenever the file exists.
 - A one-line summary of the look (accent, mode, radius, fonts).
 
 Do not run the dev server. Do not modify real pages — the demo `.tsx` is the demonstration.
@@ -205,7 +228,8 @@ Do not run the dev server. Do not modify real pages — the demo `.tsx` is the d
 - ❌ Pasting token values into pages, or theme markdown full of `bg-[#hex]` snippets. Tokens live in the CSS; pages stay semantic.
 - ❌ `@theme inline`, `@import "tailwindcss"`, `@source`, or selectors other than `:root`/`.dark` in `themes/<id>.css`.
 - ❌ Editing `styles/globals.css` or running `npx shadcn apply` against the workspace — that silently rethemes every page.
-- ❌ Producing one or two of the three files. A theme is the **bundle** — `.md`, `.css`, `.demo.tsx`, every time.
+- ❌ Producing a subset of the files. A theme is the **bundle** — `.md`, `.css`, `.demo.tsx`, and `components/email/theme-<id>.ts`, every time.
+- ❌ Hand-typing hex values into the email theme. Generate it from the CSS with the script so the page and email palettes cannot disagree.
 - ❌ A demo with raw colors or hand-rolled buttons — it must prove the tokens carry the look through `ui/`.
 - ❌ Naming font families the CSS never loads.
 - ❌ Inventing values when the user supplied a preset, images, or an existing page. Extract, don't fabricate.

package/skills/create-theme/references/email-theme-from-css.mjs

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+// Derives an emailcn EmailTheme module from a workspace theme's CSS.
+//
+//   node <this file> themes/<id>.css <id> > components/email/theme-<id>.ts
+//
+// Reads the :root block (emails are light-mode documents), converts each
+// OKLCH token to hex, and maps the shadcn roles onto EmailTheme fields.
+// Fields the CSS cannot decide (success, warning, type scale, spacing) take
+// emailcn's defaults so the file stays a drop-in for createEmailTailwindConfig.
+
+import { readFileSync } from 'node:fs';
+
+const [, , cssPath, rawId] = process.argv;
+if (!cssPath || !rawId) {
+  process.stderr.write('usage: email-theme-from-css.mjs themes/<id>.css <id>\n');
+  process.exit(1);
+}
+
+const css = readFileSync(cssPath, 'utf8');
+const rootBlock = css.match(/:root\s*\{([\s\S]*?)\}/)?.[1] ?? '';
+const tokens = {};
+for (const m of rootBlock.matchAll(/--([a-z0-9-]+)\s*:\s*([^;]+);/g)) tokens[m[1]] = m[2].trim();
+
+const missing = ['background', 'foreground', 'primary', 'primary-foreground', 'border'].filter(
+  (t) => !tokens[t],
+);
+if (missing.length) {
+  process.stderr.write(`${cssPath} :root is missing ${missing.map((t) => `--${t}`).join(', ')}\n`);
+  process.exit(1);
+}
+
+function clamp01(x) {
+  return Math.min(1, Math.max(0, x));
+}
+function linToSrgb(c) {
+  const v = clamp01(c);
+  return v <= 0.0031308 ? 12.92 * v : 1.055 * v ** (1 / 2.4) - 0.055;
+}
+function oklchToRgb(L, C, H) {
+  const h = (H * Math.PI) / 180;
+  const a = C * Math.cos(h);
+  const b = C * Math.sin(h);
+  const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
+  const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
+  const s_ = L - 0.0894841775 * a - 1.291485548 * b;
+  const l = l_ ** 3;
+  const m = m_ ** 3;
+  const s = s_ ** 3;
+  return [
+    4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+    -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+    -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+  ].map(linToSrgb);
+}
+function toHex([r, g, b]) {
+  return `#${[r, g, b]
+    .map((v) =>
+      Math.round(v * 255)
+        .toString(16)
+        .padStart(2, '0'),
+    )
+    .join('')}`;
+}
+function parseOklch(value) {
+  const m = value.match(/oklch\(\s*([\d.]+)%?\s+([\d.]+)\s+([\d.]+)/);
+  if (!m) return null;
+  let L = Number(m[1]);
+  if (value.includes('%')) L /= 100;
+  return { L, C: Number(m[2]), H: Number(m[3]) };
+}
+function hex(value) {
+  if (!value) return null;
+  if (/^#[0-9a-f]{6}$/i.test(value)) return value.toLowerCase();
+  const m = value.match(/rgb\(\s*(\d+)[\s,]+(\d+)[\s,]+(\d+)/);
+  if (m) return toHex([m[1], m[2], m[3]].map((n) => Number(n) / 255));
+  const o = parseOklch(value);
+  if (!o) return null;
+  return toHex(oklchToRgb(o.L, o.C, o.H));
+}
+function shifted(value, dL) {
+  const o = parseOklch(value);
+  if (!o) return hex(value);
+  return toHex(oklchToRgb(clamp01(o.L + dL), o.C, o.H));
+}
+function px(value, fallback) {
+  if (!value) return fallback;
+  const m = value.match(/([\d.]+)\s*(rem|px)/);
+  if (!m) return fallback;
+  const n = Number(m[1]);
+  return `${Math.round(m[2] === 'rem' ? n * 16 : n)}px`;
+}
+function fontStack(value, fallback) {
+  if (!value) return fallback;
+  return value
+    .split(',')
+    .map((f) => f.trim())
+    .filter((f) => !f.startsWith('var('))
+    .map((f) => f.replace(/^'(.*)'$/, '"$1"'))
+    .join(', ');
+}
+
+const color = (name, fallback) => hex(tokens[name]) ?? fallback;
+const background = color('background', '#ffffff');
+const foreground = color('foreground', '#111827');
+const primary = color('primary', '#111827');
+const primaryForeground = color('primary-foreground', '#ffffff');
+const border = color('border', '#e5e7eb');
+const muted = color('muted', '#f9fafb');
+const mutedForeground = color('muted-foreground', '#6b7280');
+const secondary = color('secondary', '#f3f4f6');
+const radius = px(tokens.radius, '6px');
+const radiusPx = Number.parseInt(radius, 10);
+
+const theme = {
+  borderRadius: radius,
+  borderRadiusLg: `${radiusPx * 2}px`,
+  button: {
+    primary: {
+      backgroundColor: primary,
+      borderRadius: radius,
+      color: primaryForeground,
+      fontSize: '14px',
+      fontWeight: '500',
+      paddingX: '24px',
+      paddingY: '12px',
+    },
+    secondary: {
+      backgroundColor: 'transparent',
+      border: `1px solid ${border}`,
+      borderRadius: radius,
+      color: foreground,
+      fontSize: '14px',
+      fontWeight: '500',
+      paddingX: '24px',
+      paddingY: '12px',
+    },
+  },
+  colorBackground: background,
+  colorBackgroundMuted: muted,
+  colorBackgroundSubtle: secondary,
+  colorBorder: border,
+  colorBorderSubtle: tokens.input ? color('input', border) : muted,
+  colorDanger: color('destructive', '#ef4444'),
+  colorPrimary: primary,
+  colorPrimaryForeground: primaryForeground,
+  colorPrimaryHover: tokens.primary ? shifted(tokens.primary, -0.08) : '#374151',
+  colorSuccess: '#10b981',
+  colorText: foreground,
+  colorTextMuted: mutedForeground,
+  colorTextSubtle: tokens['muted-foreground']
+    ? shifted(tokens['muted-foreground'], 0.14)
+    : '#9ca3af',
+  colorWarning: '#f59e0b',
+  containerWidth: '600px',
+  fontFamily: fontStack(
+    tokens['font-sans'],
+    '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+  ),
+  fontFamilyMono: fontStack(tokens['font-mono'], '"Menlo", "Monaco", "Courier New", monospace'),
+  fontSizeBase: '14px',
+  fontSizeHeading: '28px',
+  fontSizeLg: '16px',
+  fontSizeSm: '12px',
+  fontSizeXl: '20px',
+  fontWeightBold: '600',
+  fontWeightMedium: '500',
+  fontWeightNormal: '400',
+  lineHeightBase: '1.6',
+  spacingBase: '24px',
+  spacingLg: '32px',
+  spacingXl: '48px',
+};
+
+const id = rawId.replace(/\.css$/, '');
+const exportName = `${id.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase())}Theme`;
+// Unquoted keys, single-quoted strings unless the string itself holds one.
+const body = JSON.stringify(theme, null, 2)
+  .replace(/"([a-zA-Z]+)":/g, '$1:')
+  .replace(/"((?:[^"\\]|\\.)*)"/g, (_, str) =>
+    str.includes("'") ? `"${str}"` : `'${str.replace(/\\"/g, '"')}'`,
+  );
+
+process.stdout.write(
+  `import type { EmailTheme } from '@/components/email/email-theme';\n\n// Derived from themes/${id}.css by the create-theme skill. Re-run the script\n// after changing the CSS rather than editing colors here by hand.\nexport const ${exportName}: EmailTheme = ${body};\n`,
+);

package/skills/create-theme/references/email-theme.md

@@ -0,0 +1,48 @@
+# Email theme mapping
+
+`components/email/theme-<id>.ts` is the workspace theme expressed as an emailcn `EmailTheme`: hex colors, pixel sizes, plain font stacks. `email-theme-from-css.mjs` in this folder generates it from `themes/<id>.css`; this file records what it does so the output can be reviewed.
+
+```bash
+node .agents/skills/create-theme/references/email-theme-from-css.mjs themes/<id>.css <id> > components/email/theme-<id>.ts
+```
+
+Only the `:root` block is read. Emails are light-mode documents; mail clients that force dark mode recolor on their own and cannot be steered by a `.dark` block.
+
+## Token → field
+
+| CSS token (`:root`) | EmailTheme field | Notes |
+| --- | --- | --- |
+| `--background` | `colorBackground` | body and container fill |
+| `--foreground` | `colorText` | body copy, and the secondary button's text |
+| `--muted` | `colorBackgroundMuted` | bands, table stripes |
+| `--secondary` | `colorBackgroundSubtle` | quieter fills |
+| `--muted-foreground` | `colorTextMuted` | supporting copy |
+| `--muted-foreground` lightened (+0.14 L) | `colorTextSubtle` | captions, legal lines |
+| `--primary` | `colorPrimary`, `button.primary.backgroundColor` | the accent and the CTA fill |
+| `--primary` darkened (−0.08 L) | `colorPrimaryHover` | link hover where clients honor it |
+| `--primary-foreground` | `colorPrimaryForeground`, `button.primary.color` | text on the accent |
+| `--border` | `colorBorder`, `button.secondary.border` | hairlines, outline buttons |
+| `--input` (else `--muted`) | `colorBorderSubtle` | softer rules |
+| `--destructive` | `colorDanger` | errors |
+| `--radius` (rem × 16) | `borderRadius`, both buttons' `borderRadius`; ×2 → `borderRadiusLg` | |
+| `--font-sans` | `fontFamily` | `var()` entries dropped; keep a web-safe family at the end |
+| `--font-mono` | `fontFamilyMono` | same |
+
+Fixed at emailcn's defaults because the CSS has no equivalent: `colorSuccess` `#10b981`, `colorWarning` `#f59e0b`, `containerWidth` `600px`, the `fontSize*`, `fontWeight*`, `lineHeightBase`, and `spacing*` fields, and the button padding.
+
+## Review after generating
+
+- Web fonts: Gmail ignores them. The stack must end in `Arial, sans-serif` or a similar system family; the script keeps whatever the CSS listed, so add one if the CSS relied on `system-ui` alone.
+- Contrast: `colorTextMuted` on `colorBackground` and `colorPrimaryForeground` on `colorPrimary` are the pairs to check; they inherit the CSS values, so they pass when the CSS did.
+- Serif headings: `EmailTheme` has one `fontFamily`. If the page theme uses a serif `--font-heading`, emails set it per heading with `<Font>` plus a `font-serif` class or an explicit `style`, and the theme's `.md` should say so under "Email".
+
+## Using the theme in an email
+
+```tsx
+import { createEmailTailwindConfig } from '@/components/email/email-theme';
+import { midnightSaasTheme } from '@/components/email/theme-midnight-saas';
+
+<Tailwind config={createEmailTailwindConfig(midnightSaasTheme)}>…</Tailwind>
+```
+
+emailcn sections take a `theme` prop; blocks pin their theme inside the file and need a copy under `emails/<id>/components/` to swap it. The `create-email` skill covers both.

package/skills/current-page/SKILL.md

@@ -43,10 +43,10 @@ Path is relative to the project root (the user's `cwd`, the directory that conta
 }
 ```
 
-- `pageId` — folder name under `pages/`. Use as-is for any `/__pages/<id>/...` API or as the URL segment (`/p/<id>`).
+- `pageId` — folder name under `pages/` (or under `emails/` when `view` is `"emails"`). Use as-is for any `/__pages/<id>/...` API or as the URL segment (`/p/<id>`, `/e/<id>` for an email).
 - `pageTitle` — the page's `meta.title` (or `<title>` for an HTML page), falling back to the id.
-- `pagePath` — page entry path **relative to the project root**: `pages/<id>/index.tsx`, or `pages/<id>/index.html` for a plain HTML page. Prefix it with the project root before handing it to `Read` / `Edit`. Note the selection may point into a file under `pages/<id>/components/` if the page is split — match the line against the file whose JSX contains that tag and text.
-- `view` — `"pages"` when the user is viewing the page, `"assets"` when they are browsing that page's files in the asset manager rather than the page itself.
+- `pagePath` — entry path **relative to the project root**: `pages/<id>/index.tsx`, `pages/<id>/index.html` for a plain HTML page, or `emails/<id>/index.tsx` for an email. Prefix it with the project root before handing it to `Read` / `Edit`. Note the selection may point into a file under `pages/<id>/components/` (or `emails/<id>/components/`) if the entry is split — match the line against the file whose JSX contains that tag and text.
+- `view` — `"pages"` when the user is viewing a page, `"assets"` when they are browsing that page's files in the asset manager, `"emails"` when they are viewing an email template. An email means the `create-email` skill's rules apply (react-email components, no `ui/`), not `page-authoring`.
 - `selection` — `null` if nothing is selected. Otherwise, the JSX element the user picked in the inspector:
   - `line` (1-indexed) and `column` (0-indexed) point to the JSX opening tag in the page source. This is the canonical handle — match against the source line.
   - `tagName` is the rendered HTML tag, lowercased (`"h1"`, `"div"`, `"button"`). The source line it points at may be a shadcn component rather than that tag — a `"button"` selection usually lands on a `<Button>` line in the page, because `ui/` components spread the inspector tag onto their root. Edit the page line; never follow it into `ui/*.tsx`.

package/src/app/app.tsx

@@ -4,6 +4,8 @@ import { Toaster } from './components/ui/sonner';
 import { TooltipProvider } from './components/ui/tooltip';
 import { useLocale } from './lib/use-locale';
 import { AssetsPage } from './routes/assets';
+import { EmailView } from './routes/email';
+import { EmailsGalleryPage } from './routes/emails';
 import { Home } from './routes/home';
 import { HomeShell } from './routes/home-shell';
 import { PageView } from './routes/page';
@@ -22,11 +24,13 @@ export function App() {
               <Route path="/themes" element={<ThemesGalleryPage />} />
               <Route path="/themes/:themeId" element={<ThemeDetailPage />} />
               <Route path="/assets" element={<AssetsPage />} />
+              <Route path="/emails" element={<EmailsGalleryPage />} />
             </Route>
           ) : (
             <Route path="/" element={<NotFound />} />
           )}
           <Route path="/p/:pageId" element={<PageView />} />
+          <Route path="/e/:emailId" element={<EmailView />} />
           <Route path="*" element={<NotFound />} />
         </Routes>
       </TooltipProvider>

package/src/app/components/command/home-command-menu.tsx

@@ -1,12 +1,13 @@
-import { Presentation } from 'lucide-react';
+import { Mail, Presentation } from 'lucide-react';
 import { useMemo } from 'react';
 import { useNavigate } from 'react-router-dom';
 import { useLocale } from '~/lib/use-locale';
 import { usePageTitles } from '~/lib/use-page-titles';
+import { emailIds, emailMeta } from '../../lib/emails';
 import { pageIds } from '../../lib/pages';
 import type { Folder } from '../../lib/sdk';
 import { FolderIconChip, SystemViewIcon } from '../sidebar/folder-item';
-import { ALL_DOCS_ID, ASSETS_ID, DRAFT_ID, THEMES_ID } from '../sidebar/sidebar';
+import { ALL_DOCS_ID, ASSETS_ID, DRAFT_ID, EMAILS_ID, THEMES_ID } from '../sidebar/sidebar';
 import { type CommandGroupSpec, CommandMenu, type CommandSpec } from './command-menu';
 
 export function HomeCommandMenu({
@@ -35,6 +36,14 @@ export function HomeCommandMenu({
       run: () => navigate(`/p/${id}`),
     }));
 
+    const emails: CommandSpec[] = emailIds.map((id) => ({
+      id: `email-${id}`,
+      label: emailMeta[id]?.title ?? id,
+      icon: <Mail />,
+      keywords: [id, 'email', emailMeta[id]?.subject ?? ''],
+      run: () => navigate(`/e/${id}`),
+    }));
+
     const folderItems: CommandSpec[] = [
       {
         id: `view-${ALL_DOCS_ID}`,
@@ -67,6 +76,13 @@ export function HomeCommandMenu({
         keywords: ['themes', 'design'],
         run: () => onSelectView(THEMES_ID),
       },
+      {
+        id: `view-${EMAILS_ID}`,
+        label: t.home.emails,
+        icon: <SystemViewIcon kind="emails" />,
+        keywords: ['emails', 'mail', 'templates'],
+        run: () => onSelectView(EMAILS_ID),
+      },
     ];
     if (import.meta.env.DEV) {
       navigation.push({
@@ -80,6 +96,7 @@ export function HomeCommandMenu({
 
     return [
       { id: 'pages', heading: t.commandMenu.groupDocs, items: pages },
+      { id: 'emails', heading: t.commandMenu.groupEmails, items: emails },
       { id: 'folders', heading: t.commandMenu.groupFolders, items: folderItems },
       { id: 'navigation', heading: t.commandMenu.groupNavigation, items: navigation },
     ];

package/src/app/components/selection-note.tsx

@@ -0,0 +1,71 @@
+import { Loader2, MessageSquarePlus, X } from 'lucide-react';
+import { Button } from '~/components/ui/button';
+
+export type Selection = { loc: string; tag: string; text: string };
+
+/**
+ * The floating note box that follows an inspector pick: shows the picked
+ * element and lets the user leave a comment for their agent.
+ */
+export function SelectionNote({
+  selection,
+  note,
+  saving,
+  onNoteChange,
+  onSubmit,
+  onClear,
+}: {
+  selection: Selection;
+  note: string;
+  saving: boolean;
+  onNoteChange: (note: string) => void;
+  onSubmit: () => void;
+  onClear: () => void;
+}) {
+  return (
+    <div className="fixed bottom-6 right-6 z-20 w-[340px] rounded-lg border bg-background p-3 shadow-xl">
+      <div className="flex items-center gap-2">
+        <span className="rounded bg-muted px-1.5 py-0.5 font-mono text-[11px]">
+          {selection.tag}
+        </span>
+        <span className="font-mono text-[11px] text-muted-foreground">
+          line {selection.loc.replace(':', ', col ')}
+        </span>
+        <Button
+          variant="ghost"
+          size="icon"
+          className="ml-auto size-6"
+          aria-label="Clear selection"
+          onClick={onClear}
+        >
+          <X className="size-3.5" />
+        </Button>
+      </div>
+      {selection.text && (
+        <p className="mt-1.5 line-clamp-2 text-xs text-muted-foreground">“{selection.text}”</p>
+      )}
+      <textarea
+        value={note}
+        onChange={(e) => onNoteChange(e.target.value)}
+        placeholder="Leave a note for your agent — e.g. “make this bold”"
+        rows={2}
+        className="mt-2 w-full resize-none rounded-md border bg-transparent px-2 py-1.5 text-sm outline-none focus:ring-1 focus:ring-ring"
+      />
+      <div className="mt-2 flex justify-end gap-2">
+        <Button
+          size="sm"
+          onClick={onSubmit}
+          disabled={!note.trim() || saving}
+          aria-label="Save comment"
+        >
+          {saving ? (
+            <Loader2 className="size-3.5 animate-spin" />
+          ) : (
+            <MessageSquarePlus className="size-3.5" />
+          )}
+          Comment
+        </Button>
+      </div>
+    </div>
+  );
+}

package/src/app/components/sidebar/folder-item.tsx

@@ -2,6 +2,7 @@ import {
   FolderOpen,
   LayoutGrid,
   type LucideIcon,
+  Mail,
   MoreHorizontal,
   Palette,
   Pencil,
@@ -42,13 +43,14 @@ function useDocDragActive() {
   return active;
 }
 
-export type SystemViewKind = 'all' | 'draft' | 'themes' | 'assets';
+export type SystemViewKind = 'all' | 'draft' | 'themes' | 'assets' | 'emails';
 
 const SYSTEM_VIEW_ICONS: Record<SystemViewKind, LucideIcon> = {
   all: LayoutGrid,
   draft: PenLine,
   themes: Palette,
   assets: FolderOpen,
+  emails: Mail,
 };
 
 export function SystemViewIcon({ kind, className }: { kind: SystemViewKind; className?: string }) {
@@ -103,6 +105,9 @@ type Row =
     }
   | {
       kind: 'assets';
+    }
+  | {
+      kind: 'emails';
     };
 
 export function FolderItem({
@@ -168,7 +173,9 @@ export function FolderItem({
           ? t.home.themes
           : row.kind === 'assets'
             ? t.home.assets
-            : row.folder.name;
+            : row.kind === 'emails'
+              ? t.home.emails
+              : row.folder.name;
 
   const commitRename = () => {
     if (row.kind !== 'folder') return;

package/src/app/components/sidebar/sidebar.tsx

@@ -15,6 +15,7 @@ export const ALL_DOCS_ID = '__all__';
 export const DRAFT_ID = 'draft';
 export const THEMES_ID = '__themes__';
 export const ASSETS_ID = '__assets__';
+export const EMAILS_ID = '__emails__';
 
 export const FOLDER_DND_MIME = 'application/x-folder-id';
 
@@ -24,6 +25,7 @@ export function Sidebar({
   allCount,
   themesCount,
   assetsCount,
+  emailsCount,
   selectedId,
   onSelect,
   onCreate,
@@ -40,6 +42,7 @@ export function Sidebar({
   allCount: number;
   themesCount: number;
   assetsCount: number;
+  emailsCount: number;
   selectedId: string;
   onSelect: (id: string) => void;
   onCreate: (name: string, icon: FolderIcon) => Promise<Folder> | undefined;
@@ -178,6 +181,13 @@ export function Sidebar({
           onSelect={() => onSelect(THEMES_ID)}
           onDropDoc={() => {}}
         />
+        <FolderItem
+          row={{ kind: 'emails' }}
+          count={emailsCount}
+          selected={selectedId === EMAILS_ID}
+          onSelect={() => onSelect(EMAILS_ID)}
+          onDropDoc={() => {}}
+        />
         {import.meta.env.DEV && (
           <FolderItem
             row={{ kind: 'assets' }}

package/src/app/frame/email-inspect.ts

@@ -0,0 +1,17 @@
+// Attached to a rendered email when the workspace embeds it: the inspector
+// alone, since the document is static HTML and needs no React mount.
+import type { FrameMessage, WorkspaceMessage } from '../lib/frame';
+import { installInspector } from './inspect';
+
+if (window.parent !== window) {
+  const post = (msg: FrameMessage) => window.parent.postMessage(msg, '*');
+  const inspector = installInspector(post);
+  window.addEventListener('message', (event: MessageEvent<WorkspaceMessage>) => {
+    if (event.source !== window.parent) return;
+    const msg = event.data;
+    if (!msg || typeof msg !== 'object') return;
+    if (msg.type === 'op:inspect') inspector.setInspecting(msg.on);
+    else if (msg.type === 'op:select') inspector.setSelected(msg.loc);
+  });
+  post({ type: 'op:ready', title: document.title });
+}

package/src/app/lib/emails.ts

@@ -0,0 +1,17 @@
+import {
+  emailCreatedAt as createdAt,
+  emailIds as ids,
+  emailMeta as meta,
+} from 'virtual:open-pages/emails';
+
+export type EmailInfo = { title: string; subject: string | null; description: string | null };
+
+export const emailIds: string[] = ids;
+export const emailMeta: Record<string, EmailInfo> = meta;
+export const emailCreatedAt: Record<string, number> = createdAt;
+
+export function emailChangeIncludes(data: unknown, emailId: string): boolean {
+  if (!data || typeof data !== 'object') return false;
+  const payload = data as { emailIds?: unknown };
+  return Array.isArray(payload.emailIds) && payload.emailIds.includes(emailId);
+}

package/src/app/lib/frame.ts

@@ -12,22 +12,33 @@ export type WorkspaceMessage =
   | { type: 'op:inspect'; on: boolean }
   | { type: 'op:select'; loc: string | null };
 
-export type FrameSource = { pageId: string; kind?: PageKind } | { themeId: string };
+export type FrameSource =
+  | { pageId: string; kind?: PageKind }
+  | { themeId: string }
+  | { emailId: string };
 
 const BASE = import.meta.env.BASE_URL;
 
 /**
- * URL the workspace loads into an iframe for a page or a theme demo. React
- * pages mount through `frame.html`; `index.html` pages are served verbatim
- * (dev middleware, or the per-page build under `__page/` in a static build).
+ * URL the workspace loads into an iframe for a page, a theme demo, or an
+ * email. React pages mount through `frame.html`; `index.html` pages are served
+ * verbatim (dev middleware, or the per-page build under `__page/` in a static
+ * build); emails are rendered on the server under `__email/`.
  */
 export function frameUrl(source: FrameSource): string {
   if ('themeId' in source) return `${BASE}frame.html?theme=${encodeURIComponent(source.themeId)}`;
+  if ('emailId' in source) return emailUrl(source.emailId, 'html');
   if (source.kind === 'html')
     return `${BASE}__page/${encodeURIComponent(source.pageId)}/index.html`;
   return `${BASE}frame.html?page=${encodeURIComponent(source.pageId)}`;
 }
 
+/** The rendered email document, its plain-text alternative, or its render report. */
+export function emailUrl(emailId: string, format: 'html' | 'text' | 'json'): string {
+  const ext = format === 'text' ? 'txt' : format;
+  return `${BASE}__email/${encodeURIComponent(emailId)}/index.${ext}`;
+}
+
 export function isFrameMessage(data: unknown): data is FrameMessage {
   return (
     !!data &&