レンダラが 🐢 を自分で描けるようにしたい（Canvas の外にタートルを置く）

[temoki]

背景

TortoiseBlocks の visionOS 版（temoki/TortoiseBlocks#53）で、机の上に置いた紙の上を 3D モデルの 🐢 が歩くようにしたい。線は今まで通り TortoiseCanvas が ViewAttachmentComponent の中で描き、タートルだけを RealityKit のエンティティに差し替える。

つまり「描画はライブラリ、カーソルは呼び出し側」という構成で、これは visionOS 固有の話ではない。SwiftUI のオーバーレイ、別のゲームエンジンのスプライト、SpriteKit — どれも同じものを必要とする。

いま、これができない。3 つ足りない。

足りないもの

1. スプライトを描かない指定がない

TortoiseSprite は .triangle と .image だけ。自前のカーソルを描くと、canvas が描く三角形／画像と二重に出る。

hideTortoise() は別のもので、代わりにはならない。あれはコマンドなので、シリアライズされて SVG にも PNG にもサムネイルにも保存ファイルにも付いて回る。ここで欲しいのは「この view では描かない」という表示側の指定。

2. タートルの現在位置が取れない

TortoisePlayer が公開しているのは currentCommandIndex と isFinished だけ。これはコマンド単位、つまり毎秒 10 回程度しか動かない。

一方 canvas は animationProgress でコマンド間を補間してスプライトを描いている（CanvasModel は internal）。だから currentCommandIndex からカーソルを動かすと、線はなめらかに伸びていくのにタートルだけがワープする。「タートルが線を引きながら歩く」がこのライブラリの売りなので、これが取れないと自前描画は成立しない。

3. 座標のマッピングが取れない

ViewportMode.transform(...) と TortoiseSprite.halfExtent が internal。.autoFit は描画のバウンディングボックスに合わせて拡大・中央寄せするので、呼び出し側は同じ写像を自分で書き直すしかない。書いた日は一致していて、あとから黙ってずれる種類のコードになる。

提案

• TortoiseSprite.hidden — canvas はアニメーションはそのまま、スプライトだけ描かない。halfExtent は 0（描かないものに余白を取る理由がない）ので .autoFit の inset も 0 になる。余白が要るなら呼び出し側で .padding()
• TortoisePlayer.currentTortoiseState: TortoiseState? — いま canvas がスプライトを描いている、まさにその状態。canvas に attach されるまでは nil
• ViewportMode.transform(canvasSize:viewSize:drawingBounds:spriteHalfExtent:) と TortoiseSprite.halfExtent を public に

補間そのものは TortoiseState.interpolated(toward:progress:) として Core に置き、CanvasRenderer と currentTortoiseState の両方がそこを通るようにする。そうすれば自前カーソルが組み込みスプライトから 1 コマンドの端数ぶんずれることが原理的に起きない。位置と向きだけを補間する（ペンはコマンドの瞬間に下りるもので、途中まで下りた状態は存在しない）。

受け入れ条件

• .hidden で線は今まで通り描かれ、スプライトだけ消える
• currentTortoiseState がコマンド間で補間されている（コミット済みの状態ではない）
• currentTortoiseState が canvas の描画位置と一致する
• 既存の golden が変わらない

[temoki]

#47 で4つとも満たしました。根拠を残しておきます。

.hidden で線は今まで通り描かれ、スプライトだけ消える — 新規ゴールデン hiddenSprite.1.png を、同じ描画・同じビューポートで撮っている imageSprite.1.png と画素比較したところ、差があるのは 82×82px の1領域だけでした（+559+159＝スプライトの位置、40×40pt @2x にアンチエイリアスぶん）。線の画素は完全一致で、.hidden が触るのはカーソルだけです。

コマンド間で補間されている — 速度5（0.1秒/コマンド）で 0.05秒ぶん tick すると、currentCommandIndex はまだ -1（何もコミットされていない）のに位置は y=50。コミット済みの状態を返しているなら 0 になります。

canvas の描画位置と一致する — テストが押さえているのは currentTortoiseState == model.liveTortoiseState、つまり canvas がレンダラに渡す値との一致です。ピクセルでの突き合わせはしていませんが、補間を CanvasModel.liveTortoiseState 1箇所に寄せた結果、CanvasRenderer.drawTortoise の引数からは progress も next も消えました。別の補間をする材料が無いので、ズレが表現できません。

既存の golden が変わらない — コミットが触ったゴールデンは新規1枚のみ。既存の SVG・PNG は全件そのまま通過しています（142テスト・16スイート）。