◼BLACK MIRROR BOARD — USAGE

§1Welcome to Black Mirror Board

• 図形を描けば、ターミナルがそれに応えて言葉を返す。Draw a shape — the terminal answers in words.
• 打鍵ではなく描画で、世界を構築していく。Build the world by gesture, not just by keystroke.
• 個人の小さな呪文（コマンド）を SNS で共有し合い、他人の魔法を自分の道具にできる。Share tiny spells on SNS — someone else's magic becomes your tool.

コードを書かない美学と、コマンドを打つ快感が交わる場所。それが Black Mirror です。

It's where the aesthetic of "I don't write code" meets the thrill of "I speak to the machine."

§2Basic Controls / 基本操作

Drawing / 描画

Zoom / ズーム   ·   Pan / パン

Move · Rotate · Resize / 移動・回転・リサイズ

S  →  Select tool
   · Click an object (or within 8px of its outline) to grab it.
   · Drag to move.
   · Drag the ○ handle above the bbox to rotate.
   · Drag any of the 8 □ anchors to resize.

Modifier keys while resizing:
   Shift         Lock aspect ratio (corner handles).
   Alt / Option  Anchor to the center (symmetric scale).
   Shift + Alt   Both at once.

Images are aspect-locked on corners by DEFAULT —
Shift releases the lock, so photos never warp accidentally.

Marquee Selection / 範囲選択

Drag on empty canvas  →  dashed selection rectangle.
Any object that the marquee grazes (AABB intersection) → selected.
Then drag any selected object to move the whole group.
The group rotates + resizes like a single object.
Del / Backspace  → delete all selected.
Esc              → deselect all.

§3The Terminal Interface / ターミナル

History & Recall / 履歴の呼び出し

履歴は最大 80 件まで localStorage に保存 — リロードしても残る。History persists (up to 80 entries) in localStorage — survives reload.

Built-in Commands / 組込みコマンド

── navigation ──
help / ?                →  in-terminal cheat sheet
usage / man / docs      →  summon the USAGE overlay
clear / flush           →  wipe terminal output
objects                 →  dump every object on the board (debug)

── theme ──
light / dark / gray     →  switch canvas theme

── project (IndexedDB) ──
save <name>             →  snapshot canvas to local DB
ls                      →  list saved snapshots
load <name>             →  restore snapshot

── spell management ──
list                    →  list every registered command (preset / user flagged)
register <n> <js>       →  create a new spell
alias <new>=<old>       →  duplicate a spell under a new name
share <name>            →  copy spell JSON to clipboard
forget <name>           →  remove a user spell (presets protected)

── preset spells ──
$ scatter               →  scatter selected objects randomly
$ grid-3x3              →  place a 3×3 grid at view center
$ biwako-blue           →  retint all strokes to #0044CC
$ fetch-img <kw> <n>    →  summon n images (Lorem Flickr, no key)
$ monoclo               →  grayscale the selected image(s)
$ svg                   →  selection → editable vector SVG

── camera & sharing (v1.2) ──
Black Mirror            →  selfie camera wipe, top-right PIP
Black Mirror off        →  dismiss the camera wipe
share                   →  canvas → shareable URL (modal, no args)

── export ──
export                  →  selection as transparent PNG
export magic            →  spell picker modal
export data             →  bundle export modal (canvas / spells)
export-all              →  one-shot: project + all spells
export-spells [names]   →  one-shot: spells as a package

── easter egg ──
youtube                 →  (try it)

§4Custom Commands / カスタムコマンドの魔法

4.1 Importing a spell / 魔法を拾う

{
  "command": "scatter",
  "action": "const sel = BM.getSelected(); for (const o of sel) BM.translate(o, BM.rand(-400,400), BM.rand(-300,300)); BM.log('scattered ' + sel.length);"
}

paste > [JSON payload intercepted]
→ schema check... { command, action } ✓
→ binding $scatter → sandboxed function...
→ persisting to local storage...
[OK] spell acquired — run: $scatter

4.2 Exporting a spell / 魔法を放つ

share <name>

[CLIPBOARD] Copied to clipboard. Paste this on SNS!
───────────────────────────────────────────
{
  "command": "scatter",
  "action": "..."
}
───────────────────────────────────────────

4.3 Writing your own / 自作する

register <name> <javascript action>

Inside the action, the BM global is your interface:

重要： BM.create('rect', ...) は使えません。四角は 'square' を使ってください。対応タイプは circle / square / triangle / arrow / text の5種のみです。Important: BM.create('rect', ...) is not supported. Use 'square' instead. The five valid types are circle / square / triangle / arrow / text.

4.4 Aliasing / 別名

alias ripple = scatter

4.5 Import collision behavior / 取り込み時の衝突回避

§4.5Images / 画像の召喚とモノクロ化

Screenshot → paste / drop — クリップボードから直接

// Pipeline
clipboard image  →  paste handler  →  placeImageOnCanvas('paste')
file drop        →  drop handler   →  placeImageOnCanvas('drop')
file picker (I)  →  change handler →  placeImageOnCanvas('upload')

// All three routes share the same scaling, centering, undo, and terminal log.

$ fetch-img — keyword-based image summoning

// Technical spec
endpoint : https://loremflickr.com/<w>/<h>/<keyword>?lock=<seed>
size     : 240 × 180 per tile
gap      : 20px
max      : 25 images per invocation
output   : color (use $ monoclo to grayscale after)
grid     : cols = ceil(√n)  ·  rows = ceil(n / cols)
cors     : falls back to URL ref if dataURL conversion fails

$ monoclo — grayscale selected images

// Filter applied
grayscale(100%) contrast(110%) brightness(95%)

// Behavior
· selection required · multi-select supported
· updates obj.data.src to a new dataURL → persisted
· Cmd+Z reverts to the original color image

⚠ Image Persistence — 画像の保存について

§5AI-Assisted Spells / AI に魔法を作らせる

完全な機械可読仕様: spell-spec.md · LLM index: llms.txtFull machine-readable spec: spell-spec.md · LLM index: llms.txt

5.1 Prompt template / プロンプト雛形

以下のブロックを AI に貼って、最後の「リクエスト」部分だけ書き換えてください。Paste the block below into your AI chat and fill in the request at the bottom.

You are a Black Mirror Board spell author.
Return exactly one JSON object in this shape — nothing else:

{
  "command": "name-of-spell (a-z 0-9 _ -, max 30 chars)",
  "action": "javascript source as a string"
}

── BM API (the only functions available inside action) ──
BM.getSelected() / BM.all() / BM.clear()
BM.create(type, props)   // type ∈ {circle, square, triangle, arrow, text, sticky}
BM.update(idOrObj, patch) / BM.translate(obj, dx, dy)
BM.setStroke(obj, color) / BM.setFill(obj, color)
BM.remove(obj)
BM.viewCenter()  // {x, y}
BM.rand(min, max)
BM.redraw()      // call after any mutation
BM.save()        // commits to undo history
BM.log(msg, cls?) // cls ∈ {t-ok, t-err, t-dim}
args             // string passed at invocation: "$name foo bar" → args === "foo bar"

── Object types and props ──
circle:   {cx, cy, rx, ry, rotation, fill, strokeOff}
square:   {x, y, w, h, rotation, fill, strokeOff}
triangle: {x, y, w, h, rotation, fill, strokeOff}
arrow:    {x1, y1, x2, y2, rotation}
text:     {x, y, text, fontSize, rotation}
sticky:   {x, y, w, h, text, color, rotation}  // default color '#FFE873'

── Hard rules ──
1. Rect does not exist. Use 'square', not 'rect'.
2. No async/await at the top level — action runs synchronously.
   Use .then() chains if you need Promises.
3. No import / require / external libraries.
4. Always call BM.redraw() after mutations.
5. For meaningful changes, call BM.save() so Cmd+Z works.
6. If the spell requires a selection, guard it:
     if (!sel.length) { BM.log('select first', 't-err'); return; }

── FORBIDDEN — these are NOT BMBoard ──
internalName, displayName, description, icon, category, cost, mp, cooldown,
PROJECTILE, particle, onHit, effect, magic create, /bmboard, /reload,
plugins/, skills/, give, server-side, mod, plugin, manifest.
If you reach for any of these, you are off-spec — start over.

── Request ──
(write what you want in one or two sentences)

5.2 Short form / 超短縮版

上のテンプレが長すぎる場合に。When the full template is overkill:

Make a Black Mirror Board spell. Output 1 line of JSON, no Markdown:
{"command":"NAME","action":"JS"}

BM API (only): getSelected(), all(), clear(), create(type, props),
update(o,patch), translate(o,dx,dy), setStroke/setFill(o,c), remove(o),
viewCenter(), rand(min,max), log(msg,cls), redraw(), save(). args = string.

Types: circle | square | triangle | arrow | text | sticky  (NO rect).
NEVER: internalName, displayName, cooldown, magic create, /bmboard,
plugins/, skills/. Those are not BMBoard.
No async/await. End with BM.redraw().

Request: (what you want)

5.3 Example round-trip / 応答例

Request: 選択中の図形を画面中央に集めて、選択が無ければエラーにする

{
  "command": "center-all",
  "action": "const sel=BM.getSelected();if(!sel.length){BM.log('select first','t-err');return}const vc=BM.viewCenter();for(const o of sel){if(o.data.cx!==undefined){o.data.cx=vc.x;o.data.cy=vc.y}else if(o.data.x!==undefined){o.data.x=vc.x-(o.data.w||0)/2;o.data.y=vc.y-(o.data.h||0)/2}}BM.redraw();BM.save();BM.log('centered '+sel.length+' object(s)')"
}

5.4 Common AI pitfalls / よくある失敗と対処

5.5 Growing a spell incrementally / 段階的に育てる

1. 最初は最小の魔法を頼む（動作1つ）Start with the smallest version that works.
2. 取り込んで実行確認Register it and verify it runs.
3. 「次は選択が無いときの分岐を追加して」Then ask: "add a guard for empty selection."
4. 「次はランダム色を追加して」Then: "add random color."
5. 動く状態を保ちながら機能追加。一気に複雑化しないのがコツ。Keep it working at every step — avoid big-bang complexity.

§6Tutorial — Your First Command / 最初の一手

biwako-blue

scatter

grid-3x3

fetch-img ocean 4

monoclo

これで、あなたは5つの呪文を既に使ったことになります。You've just cast five spells. Now make your own.

Next Steps / 次の一歩

• Type $ usage to summon the overlay manual from within the app.
• Type $ help for a terminal-native cheat sheet.
• Write your own: register <name> <js> → share <name> → paste to SNS.
• Try export magic to bundle several spells as a shareable .json.

§7Keyboard Reference / キーボード完全版

TOOLS                               THEMES
────────────────────────────────    ────────────────────────────────
S   Select                          dark   Void theme
P   Pen                             light  Surface theme
N   Path (anchor-by-click)          gray   Studio theme (cobalt)
E   Eraser
C   Circle                          COMMANDS
G   Triangle                        ────────────────────────────────
Q   Square                          help      terminal cheat sheet
A   Arrow                           usage     overlay manual
T   Text                            list      list registered spells
I   Upload image                    register  create a new spell
X   Export transparent PNG          share     copy spell JSON
                                    alias     duplicate as new name
WIDTH                               forget    remove a user spell
────────────────────────────────    clear     flush terminal
1   Thin                            ↑ / ↓     command history
2   Medium
3   Thick                           RESIZE MODIFIERS
                                    ────────────────────────────────
GLOBAL                              Shift     lock aspect ratio
────────────────────────────────    Alt/Opt   scale from center
Space     Hold to pan               Shift+Alt both at once
Ctrl+Z    Undo
Ctrl+Y    Redo
Del       Delete selected
Esc       Dismiss / deselect

§8Export & Import / 書き出しと取り込み

8.1 Export — 書き出し

8.1c URL share — share でキャンバス丸ごと送る

// Typical size
  10 shapes   → ~1 KB
  50 shapes   → ~3 KB
 200 shapes   → ~8 KB   (warning threshold)
 500+ shapes  → 10 KB+  (may break SNS link previews)

// Stripped to keep URL short
· image objects (dataURLs too heavy) → use export data for full fidelity

// Browser requirement
CompressionStream API — Chrome 80+ · Safari 16.4+ · Firefox 113+

// Receiver behavior
open URL → board loads with #s=... → decodes → replaces canvas
         terminal logs "[SYSTEM] shared-state detected"
         URL hash is cleared after load (reload is idempotent)

8.1b SVG export — ベクター書き出しの詳細

// Mapping
circle    → <ellipse>                rotation → <g transform="rotate(...)">
square    → <rect>                   color    → obj.data.stroke / resolveFill(theme)
triangle  → <polygon>                fill     → fill attribute (or none)
arrow     → <line> + <polygon head>  stroke   → stroke attribute + stroke-width
text      → <text dominant-baseline="hanging">
pen       → <path d="M ... Q ...">   (closed strokes carry a final Z + fill)
image     → <image href="dataURL">   (URL-only images: linked, may not load offline)

// Filename
BM_CANVAS_YYYYMMDD_HHMM.svg

// Background note
· Colors come from the current theme. Exporting from DARK mode
  produces light strokes — view on a dark background, or switch
  to LIGHT / GRAY mode first for print-friendly output.

8.2 Import — 取り込み

1. single spell
{"command":"grain", "action":"..."}

2. array of spells
[{"command":"a", "action":"..."}, {"command":"b", "action":"..."}]

3. spells package
{"format":"blackmirror.spells", "version":"1.2", "commands":[...]}

4. full bundle (canvas + spells)
{"format":"blackmirror.bundle", "version":"1.2", "project":{...}, "commands":[...]}

8.3 Drop zone

8.4 Bundle confirmation dialog

◼ BUNDLE DETECTED
incoming: 12 object(s), 3 spell(s)
current canvas: 5 object(s)

[O] OVERWRITE — replace current canvas with the bundle
[A] ADD       — merge bundle into current canvas (re-IDs incoming)
[C] CANCEL    — do nothing

完全バンドル（キャンバス込み）を取り込む時だけ、3択の確認ダイアログが出ます。

The confirmation dialog appears only for full bundles that include canvas objects.

8.5 Collision-safe rename / 衝突時の自動リネーム

§9Capabilities & Limits / できること・できないこと

9.1 BM.create types (the only 5 valid)

rect / ellipse / polygon / path / line は未対応。square・circle（rx≠ry で楕円）・arrow 等で代用してください。

rect / ellipse / polygon / path / line are not valid. Use square / circle (with different rx/ry) / arrow etc.

9.2 JS features available in actions

9.3 Canvas limits

~500 objects    comfortable
~1000           still smooth
~10000+         likely to stall the browser

Tip: call BM.redraw() once after a bulk loop, not on every iteration.

9.4 External APIs via CORS

9.5 Persistence layout

• Spells (preset + user) → IndexedDB blackmirror/commands + localStorage shadow
• Named projects (save / load) → IndexedDB blackmirror/projects
• Terminal history → localStorage key bm.termHistory.v1
• Everything is local-only. Nothing is uploaded.

リロードしてもタブを閉じても残ります。ブラウザのデータを消すと消えるので、重要なワークは export data でファイル書き出し推奨。Survives reloads and tab-close. Lost if you clear browser data — use export data for hard backups.

9.6 Object data properties / オブジェクト型ごとのプロパティ

BM.all() で返ってくる各オブジェクトの obj.data で読み書きできる属性。Attributes available on each object's obj.data, returned by BM.all().

circle    { cx, cy, rx, ry, rotation, fill, stroke, strokeOff }
square    { x, y, w, h, rotation, fill, stroke, strokeOff }
triangle  { x, y, w, h, rotation, fill, stroke, strokeOff }
arrow     { x1, y1, x2, y2, rotation }
text      { x, y, text, fontSize, rotation, fill, stroke }
stroke    { pts: [{x,y}, ...], lw, closed, fill, stroke, strokeOff }  // pen drawing — read-only to BM.create
image     { x, y, w, h, src (dataURL or URL) }                        // via fetch-img or I key

9.7 Use-case feasibility / ユースケース別の可否

§10FAQ / トラブルシューティング

10.1 Drawing / 描画

10.2 Terminal / ターミナル

10.3 Spells / 魔法

10.4 Export / Import

10.5 Performance / パフォーマンス

10.5b Camera wipe / カメラワイプ

10.5c Share URL

10.6 Mobile / モバイル

10.7 Still stuck? / それでも解決しない

1. DevTools (F12) の Console でエラーログを取得Open DevTools (F12) → Console to capture the real error.
2. 再現手順を添えて SNS (#blackmirror) または GitHub Issues に報告Report to SNS (#blackmirror) or GitHub Issues with the steps.
3. 「こういう魔法が作れない」系は §9 をまず確認For "spell X won't work" questions, check §9 first.