Magic Envelope

✉ Magic Envelope

Free invitations and letters: birthdays, weddings, parties, dinners, letters… Pick a ready-made template or build one from typed blocks. Send a link and the guest opens a sealed envelope.

Not an editor. Everything is typed and modular.

Run

pnpm install

pnpm dev # http://localhost:3000

Locally, without any keys, published cards and uploaded images are saved under .data/. Only AI images need a key.

For agents

Everything the app does is available without a browser:

• MCP — https://magic-envelope.com/api/mcp (tools: get_catalog, create_letter, get_letter, update_letter)
• REST — POST /api/v1/letters, GET|PATCH /api/v1/letters/:id (Authorization: Bearer ), GET /api/v1/catalog
• Specs — /api/v1/openapi.json, /api/v1/schema, /llms.txt, docs at /developers

The REST and MCP adapters share one service layer (src/lib/api.server.ts) and validate with the same Zod schemas as the editor.

Native apps (Capacitor 8)

The iOS/Android apps are thin shells around the hosted web app (it needs API routes, so no static export). capacitor.config.ts points the WebView at CAP_SERVER_URL (default https://magic-envelope.com); native-shell/ is only the offline page.

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 is the single bridge: each function uses the Capacitor plugin in the app and the web API in the browser.

Environment

Architecture

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

Adding a block type

1. Add a schema in lib/model.ts and include it in the Block union (add a migration there if you change an existing shape).
2. Add an icon, a palette entry and a factory in lib/blocks.ts, and its label in lib/ui.ts.
3. Add a renderer case and an isEmpty rule in components/card/blocks.tsx.
4. Add an editor case in components/editor/block-editor.tsx, using Field with the right field kind.
5. Add any guest-facing words to lib/i18n.ts.

TypeScript's exhaustive switches flag every step you missed.

Features

• Wizard: letter language → style (15 styles: Classic, Elegant, Modern, Playful, Retro) → blank letter (default) or an occasion preset
• Style panel in the editor: switch style, customize accent/paper/text colors and title/text fonts, seal (symbol, initials or none), text written on the envelope (supports the guest name)
• Preview page mirrors the editor's Link/Image choice and "preview as" guest, and can send directly
• App UI is English; each letter has its own language (changeable from the Style panel)
• 15 blocks: title, text, image, date, place + map, countdown, RSVP (WhatsApp/SMS/email), QR, link, schedule, dress code moodboard (colors, emojis, words, pictures), gifts (IBAN copy / registry), music (Spotify/YouTube/SoundCloud), signature, divider
• AI images in 4 styles (storybook, medieval, sketch, photo) and photo upload
• Six themes, custom wax-seal glyph, an envelope addressed "To: …"
• Guest list: add, paste a list ("Name, phone/email") or pick from contacts; {name} in any text addresses each guest
• every guest gets their own link (/c/ ?g= ) — only *their* name is ever sent to their browser
• send per guest via their channel (WhatsApp / email / share sheet), track who was sent, copy all links, CSV
• RSVP replies carry the guest's name; the envelope is addressed to them
• Envelope (link letters): fixed slots holding real blocks — Title (recipient), Text (sender, note, under the seal) and Stamp (postage, 14 perforated stamps) — edited with the same editor, placeholders and rules as the letter; seal in 4 shapes (scalloped, round, flower, octagon) with a vector mark (12 icons, 1–3 initials, a couple "A ♥ J", plain or none), always legible on any wax colour. Styles ship their own envelope (trim + stamp). Guests receive the front, turn it over with a tap, open it with a second; the real letter slides out.
• Preview shows exactly what a guest receives: the envelope (replayable) for links, the actual exported PNG for images.
• Two outputs from one letter: the interactive link, or flat images (PNG per guest, ZIP for all, print/PDF). Blocks with actions render flat automatically in images, and each can turn its buttons off for the link too.
• Share: link, native share sheet, WhatsApp, downloadable QR, print/PDF
• Guests get "add to calendar", directions, a live countdown and one-tap RSVP
• Installable PWA (iOS/Android home screen), dark-mode chrome, reduced-motion support
• Published links are noindex; each card can be re-published from the device that created it