Magic Envelope

✉ Magic Envelope

免费邀请函和信件：生日、婚礼、派对、晚宴、信件…… 选择现成模板，或用输入式模块自行制作。发送链接后，宾客打开密封信封即可查看。

这不是编辑器。所有内容都以输入式模块构成。

运行

pnpm install
pnpm dev          # http://localhost:3000

本地运行时无需任何密钥，已发布的卡片和上传的图片会保存在 .data/ 下。只有 AI 图片需要密钥。

面向 Agent

无需浏览器即可使用应用的所有功能：

• MCP — https://magic-envelope.com/api/mcp（工具：get_catalog、create_letter、get_letter、update_letter）
• REST — POST /api/v1/letters、GET|PATCH /api/v1/letters/:id（Authorization: Bearer <editKey>）、GET /api/v1/catalog
• 规范 — /api/v1/openapi.json、/api/v1/schema、/llms.txt，文档位于 /developers

REST 和 MCP 适配器共用一个服务层（src/lib/api.server.ts），并使用与编辑器相同的 Zod 模式进行验证。

原生应用（Capacitor 8）

iOS/Android 应用是托管 Web 应用的轻量外壳（应用需要 API 路由，因此不支持静态导出）。 capacitor.config.ts 将 WebView 指向 CAP_SERVER_URL（默认值为 https://magic-envelope.com）；native-shell/ 仅用于离线页面。

pnpm dev:lan                                   # dev server reachable from your phone
CAP_SERVER_URL=http://192.168.1.20:3000 pnpm cap:android   # or cap:ios (opens Android Studio / Xcode)

src/lib/native.ts 是唯一的桥接层：应用中的每个函数都使用 Capacitor 插件，浏览器中的每个函数都使用 Web API。

函数	原生应用	浏览器
share()	系统分享面板	Web Share；不可用时回退为复制链接
haptic()	Taptic/振动	navigator.vibrate
copy()	原生剪贴板	Clipboard API
pickPhoto()	相机/照片图库	文件输入（在移动设备上，capture 会打开相机）
saveFile()	写入缓存，然后分享（文件、日历……）	下载
onBack()	Android 返回按钮可关闭面板/向导步骤	–
深层链接	appUrlOpen 会在应用内打开 /c/…	–

环境变量

变量	用途
AI_GATEWAY_API_KEY	通过 Vercel AI Gateway 生成 AI 图片（在 Vercel 上，OIDC 无需此变量即可运行）
BLOB_READ_WRITE_TOKEN	用于已发布卡片（私有）和图片（公开）的 Vercel Blob 存储
NEXT_PUBLIC_SITE_URL	规范 URL，例如 https://magic-envelope.com（二维码、OG 图片）
IMAGE_MODEL	可选覆盖项，默认值为 bfl/flux-2-klein-4b（便宜且快速）

架构

src/lib/model.ts        Zod schemas: Card, 15 Block types, kinds, themes, languages
src/lib/blocks.ts       block registry (icons, palette, factories) + 24 templates (8 kinds × 3)
src/lib/ui.ts           app UI copy (always English)
src/lib/styles.ts       letter styles = design-system tokens (fonts, colors, background, frame, control shape, envelope) + per-letter overrides
src/lib/i18n.ts         letter languages es · en · fr · pt · it · de (guest-facing copy + presets)
src/lib/fields.ts       field kinds (phone, email, url, date…): one validator for editor + renderer
src/lib/craft.ts        seal shapes/marks & envelope geometry/palettes (shared by app and OG image)
src/lib/color.ts        opaque shading helpers
src/lib/themes.ts       6 themes (parchment, midnight, rose, forest, sky, ink)
src/lib/actions.ts      calendar (.ics / Google), maps, RSVP deep links, music embeds
src/lib/drafts.ts       drafts in localStorage (no account needed)
src/lib/store.server.ts Vercel Blob storage, or .data/ in local dev

src/components/sketch.tsx         Excalidraw-style rough.js frames and buttons
src/components/card/blocks.tsx    renderer per block type
src/components/craft.tsx          wax seal, envelope art, envelope opener
src/components/editor/            tap-a-block editor, "+" palette, theme, share sheet
src/components/wizard.tsx         language → kind → template

/                 home (drafts)
/new              wizard (?kind=wedding jumps to templates)
/edit/[id]        editor (local draft)
/c/[id]           public envelope (+ OG image for WhatsApp/iMessage previews)
/e/[id]#key       "edit on another device": imports the card into local drafts
/api/publish      save/overwrite a card (id + secret edit key)
/api/upload       image upload (resized client-side)
/api/imagine      AI image → stored → URL
/api/card/[id]    card JSON for holders of the edit key

src/lib/personalize.ts            {name} token: resolution and fallbacks
src/lib/mail.ts                   envelope slots (fixed block types), stamps, per-style envelope defaults
src/components/editor/envelope-editor.tsx  envelope canvas + slot/seal editors
src/components/export-stage.tsx   flat PNG/ZIP rendering (fonts embedded per style)
src/components/editor/guests-panel.tsx, send-panel.tsx

添加块类型

1. 在 lib/model.ts 中添加模式，并将其加入 Block 联合类型（如果修改现有结构，也要在此添加迁移）。
2. 在 lib/blocks.ts 中添加图标、调色板项和工厂函数，并在 lib/ui.ts 中添加其标签。
3. 在 components/card/blocks.tsx 中添加渲染器分支和 isEmpty 规则。
4. 在 components/editor/block-editor.tsx 中添加编辑器分支，并使用字段类型正确的 Field。
5. 在 lib/i18n.ts 中添加面向宾客的所有文案。

TypeScript 的穷尽式 switch 会标出你遗漏的每一步。

功能

• 向导：选择信件语言 → 选择风格（15 种风格：Classic、Elegant、Modern、Playful、Retro）→ 空白信件（默认）或场合预设
• 编辑器中的风格面板：切换风格，自定义点缀色、纸张色和文字色，以及标题和正文的字体；选择印章（符号、姓名首字母或无）；设置写在信封上的文字（支持宾客姓名）
• 预览页面与编辑器中的链接／图片选项及“预览身份”宾客保持一致，并可直接发送
• 应用界面为英文；每封信都有自己的语言（可在风格面板中更改）
• 15 种区块：标题、正文、图片、日期、地点 + 地图、倒计时、RSVP（WhatsApp／SMS／电子邮件）、QR 码、链接、日程、着装风格情绪板（颜色、表情符号、文字、图片）、礼物（复制 IBAN／礼物清单）、音乐（Spotify／YouTube／SoundCloud）、署名、分隔线
• 提供 4 种风格的 AI 图片（storybook、medieval、sketch、photo），并支持上传照片
• 六种主题、自定义火漆印章字形，以及写有“To: …”的信封
• 宾客名单：添加宾客、粘贴名单（“姓名，电话／电子邮件”），或从联系人中选择；任意文本中的 {name} 都会替换为对应宾客的姓名
  • 每位宾客都有专属链接（/c/<id>?g=<guest>）——只会将该宾客的姓名发送到其浏览器
  • 通过每位宾客的渠道（WhatsApp／电子邮件／分享面板）单独发送，追踪已发送对象，复制所有链接，导出 CSV
  • RSVP 回复会附上宾客姓名；信封也会写上宾客姓名
• 信封（链接信件）：包含固定位置的真实区块——标题（收件人）、正文（寄件人，在印章下方留言）和邮票（邮资，14 种带齿孔的邮票）；使用与信件相同的编辑器、占位符和规则进行编辑；印章有 4 种形状（波浪边、圆形、花形、八边形），并可搭配矢量图案（12 种图标、1–3 个姓名首字母、类似“A ♥ J”的组合、纯色或无图案），在任何蜡色上都清晰易读。每种风格都自带信封（饰边 + 邮票）。宾客会先收到正面，轻点即可翻面，再轻点即可拆开信封；真实信件会从中滑出。
• 预览会准确展示宾客收到的内容：链接信件会显示信封（可重新播放），图片信件会显示实际导出的 PNG
• 一封信件，两种输出：交互式链接，或平面图片（每位宾客一张 PNG、所有图片打包为 ZIP、打印／PDF） 带操作功能的区块会自动以平面形式呈现在图片中；每个区块也可关闭链接中的按钮。
• 分享方式：链接、系统分享面板、WhatsApp、下载 QR 码、打印／PDF
• 宾客可“添加到日历”、查看路线、查看实时倒计时并一键 RSVP
• 可安装的 PWA（iOS／Android 主屏幕）、深色模式浏览器界面、支持减少动态效果
• 已发布的链接带有 noindex；每张卡片都可在创建它的设备上重新发布