Magic Envelope

✉ Magic Envelope

無料の招待状や手紙を作成できます。誕生日、結婚式、パーティー、ディナー、手紙などに対応しています… 用意されたテンプレートを選ぶか、入力式のブロックを組み合わせて作成できます。リンクを送ると、ゲストが封筒を開きます。

これはエディターではありません。すべて入力式で、モジュール化されています。

実行

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

キーなしでローカル実行できます。公開したカードとアップロードした画像は .data/ に保存されます。キーが必要なのはAI画像だけです。

エージェント向け

アプリの機能はすべて、ブラウザーを使わずに利用できます。

• 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 アプリは、ホストされたウェブアプリを囲む薄いシェルです（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 プラグインを、ブラウザーではウェブ API を使用します。

関数	ネイティブ	ブラウザー
share()	システムの共有シート	Web Share。利用できない場合はリンクをコピー
haptic()	Taptic／バイブレーション	navigator.vibrate
copy()	ネイティブのクリップボード	Clipboard API
pickPhoto()	カメラ／フォトライブラリ	ファイル入力（capture を指定すると、モバイルではカメラが開きます）
saveFile()	キャッシュに書き込んでから共有（Files、Calendar など）	ダウンロード
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（QR コード、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. Field に適切なフィールド種別を指定して、components/editor/block-editor.tsx にエディターのケースを追加します。
5. ゲストに表示する文言を lib/i18n.ts に追加します。

TypeScript の網羅性チェックにより、対応漏れのある手順がすべて検出されます。

機能

• ウィザード：手紙の言語 → スタイル（15種類：クラシック、エレガント、モダン、遊び心のある、レトロ） → 空白の手紙（デフォルト）またはイベント用プリセット
• エディターのスタイルパネル：スタイルの切り替え、アクセント・紙・文字の色とタイトル・本文のフォント、封蝋（シンボル、イニシャル、またはなし）、封筒に書くテキスト（ゲストの名前に対応）をカスタマイズ
• プレビューページには、エディターのリンク／画像の選択と「次のゲストとしてプレビュー」が反映され、そこから直接送信できます
• アプリのUIは英語です。各手紙にはそれぞれ言語があり（スタイルパネルから変更可能）
• 15種類のブロック：タイトル、テキスト、画像、日付、場所＋地図、カウントダウン、出欠確認（WhatsApp／SMS／メール）、QR、リンク、スケジュール、ドレスコードのムードボード（色、絵文字、単語、写真）、ギフト（IBANのコピー／ギフト登録リスト）、音楽（Spotify／YouTube／SoundCloud）、署名、区切り線
• 4種類のスタイル（絵本風、中世風、スケッチ、写真風）のAI画像と写真のアップロード
• 6種類のテーマ、カスタムの封蝋用グリフ、「宛先：…」と記された封筒
• ゲストリスト：ゲストを追加、リストを貼り付け（「名前、電話番号／メール」）、または連絡先から選択。テキスト内の {name} は各ゲストの名前に置き換わります
  • すべてのゲストに個別のリンク（/c/<id>?g=<guest>）が割り当てられます。各ゲスト自身の名前だけが、そのゲストのブラウザーに送信されます
  • 各ゲストの連絡手段（WhatsApp／メール／共有シート）で個別に送信し、送信済みの相手を追跡できます。すべてのリンクのコピーやCSV出力も可能です
  • 出欠確認の返信にはゲストの名前が含まれ、封筒の宛名もゲストに合わせて表示されます
• 封筒（リンク形式の手紙）：実際のブロックを配置する固定スロット——タイトル（宛先）、テキスト（差出人、封蝋の下に添えるメモ）、スタンプ（郵便料金、ミシン目入りのスタンプ14種類）。手紙と同じエディター、プレースホルダー、ルールで編集できます。封蝋は4種類の形（スカラップ、丸形、花形、八角形）から選べ、ベクターマーク（12種類のアイコン、1〜3文字のイニシャル、「A ♥ J」のようなカップル名、文字のみ、またはなし）を入れられます。どの色の封蝋でも常に読みやすく表示されます。各スタイルには専用の封筒（縁取り＋スタンプ）が付属します。ゲストには封筒の表面が届き、タップして裏返し、もう一度タップして開くと、実際の手紙が滑り出てきます。
• プレビューにはゲストが受け取る内容がそのまま表示されます。リンクの場合は再生できる封筒、画像の場合は実際にエクスポートされるPNGです。
• 1通の手紙から2種類の形式を出力できます：インタラクティブなリンク、または静止画像（ゲストごとのPNG、全員分のZIP、印刷／PDF）。 操作機能を持つブロックは画像では自動的に静止表示になり、リンクでも各ブロックのボタンをオフにできます。
• 共有：リンク、ネイティブの共有シート、WhatsApp、ダウンロード可能なQR、印刷／PDF
• ゲストは「カレンダーに追加」、経路案内、リアルタイムのカウントダウン、ワンタップでの出欠回答を利用できます
• インストール可能なPWA（iOS／Androidのホーム画面）、ダークモードのブラウザーUI、動きを抑える設定に対応
• 公開されたリンクには noindex が設定されます。各カードは、作成したデバイスから再公開できます