Xprite のしくみ

Xprite は Aseprite のエディターをブラウザに持ち込みました。インストールもアカウント作成も不要で、作品を保存するサーバーもありません。この記事では、ブラウザで .aseprite を読み書きする方法、Canvas でくっきりしたピクセルを描く方法、作品の保存場所、オフラインでエディターを開くしくみ、そしてマウス向けに作られたデスクトップの画面を指やペン、スマホの画面にどう合わせているかを、技術的な側面から説明します。

全体像

エディターの処理はすべてブラウザ内で行われます。重い処理は Web Worker で動き、保存にはブラウザ標準の IndexedDB と OPFS を使います。ネットワークを使うのは、ページの読み込み、匿名のアクセス解析の送信、フィードバックの送信だけです。

ブラウザで .aseprite を読み書きする

ファイル形式

.aseprite はリトルエンディアンのバイナリ形式で、128 バイトのヘッダーの後に、複数のチャンクからなるフレームが続きます。ヘッダーのマジックナンバーは 0xA5E0、各フレームのものは 0xF1FA です。デコーダーは次のチャンクを扱います。

古い 0x0004 と 0x000B のパレットチャンクも読み込み、非推奨のマスク（0x2016）とパス（0x2017）のチャンクも認識します。

先に検査し、それからデコード

ブラウザで開くファイルはどこから来たものかわからないので、デコードは 2 段階で行います。1 回目はファイル全体を走査し、すべてのチャンクの長さ、オフセット、個数がファイル内に収まっているかを確認します。実際のデコードはその後で始まります。壊れたファイルや上限を超えるファイルは、途中で失敗するのではなく走査の段階で見つかります。現在の上限は次のとおりです。

Worker でデコード

数十フレームを展開するには時間がかかり、メインスレッドで行うと画面が固まってしまいます。ファイルを開くと専用のデコード用 Worker に渡し、デコードしたピクセルバッファーは Transferable オブジェクトとしてコピーせずにメインスレッドへ戻します。ブラウザが Worker に対応していない場合や Worker が失敗した場合は、メインスレッドでのデコードにフォールバックします。

ピクセルデータは zlib で圧縮されています。ブラウザ標準の DecompressionStream("deflate") を優先し、展開爆弾を防ぐため出力をチャンクヘッダーで宣言されたサイズまでに制限します。対応していない場合は fflate を使います。もう一方の展開経路では、宣言されたサイズちょうどの出力バッファーを確保し、Adler-32 チェックサムを検証します。

必要なピクセルだけ展開する

ファイルを開いたとき、RGB のセルは検証されますが、すべてが展開されるわけではありません。元の圧縮バイトはメモリに残し、各フレームは必要になったときに展開します。大きなプロジェクトでも、一度にすべてをメモリに展開する必要はありません。

変更していない部分はそのまま書き戻す

.aseprite に保存するとき、エンコーダーは手を加えていない内容をそのまま残します。

• 変更していないセルは、開いたときから保持している圧縮バイトから再圧縮せずに書き戻します。
• 未知のチャンクはそのまま書き戻すので、新しいバージョンの Aseprite で作ったファイルを Xprite で保存してもデータは失われません。
• 再圧縮したセルは、圧縮版が生データより小さい場合にだけ圧縮版を使います。
• 圧縮にはブラウザ標準の CompressionStream を使います。対応していない場合は非圧縮で保存されます。サイズは大きくなりますが、Aseprite で開けます。

Canvas 2D だけでキャンバスを描画する

Xprite は WebGL を使いません。ドット絵のキャンバスはたいてい小さく、難しいのはすべてのピクセルをくっきり保つことです。どのズーム倍率でも、どの画面密度でも、ピクセルはブラウザがぼかしたものではなく、縁のはっきりした正方形として表示されなければなりません。

レイヤーから画面まで

描画中、エディターは各ストロークで変わった矩形を記録し、描画処理では毎回画像全体を送り直すのではなく、その範囲だけを画像キャンバスに書き込みます。できあがったビュー（ピクセル、市松模様、グリッド）はベースキャンバスにキャッシュします。キャッシュキーにはピクセルのバージョン、ビューの位置、表示設定などが含まれます。カーソルを動かしてもキーは変わらないので、ベースキャンバスを再利用し、ブラシカーソルのプレビューだけを描き直します。

整数倍と小数倍

最後の段階でビューを画面に描画します。ビューが画面にちょうど整数倍で対応する場合は、画像のスムージングをオフにしてブラウザの drawImage に任せます。

if (Number.isInteger(scaleX) && Number.isInteger(scaleY) /* and no offset */) {
  presentation.imageSmoothingEnabled = false;
  presentation.drawImage(sourceCanvas, 0, 0, sourceWidth, sourceHeight,
                         0, 0, canvas.width, canvas.height);
  return;
}
presentation.putImageData(renderer.render(context.getImageData(...)), 0, 0);

画面密度 1.5 やブラウザのズーム 110% のような小数倍では、ブラウザごとに drawImage のサンプリングが異なります。ピクセルの列の幅が不揃いになったり、画像全体が半ピクセルずれたりします。その場合はニアレストネイバーのサンプリングを自前で行います。描画先のサイズに対して、各列・各行がどの元ピクセルに対応するかを事前に計算し、2 つの Int32Array ルックアップテーブルに保存します。サンプリングでは各ピクセルを 1 つの Uint32 としてコピーし、同じ行が続く部分は copyWithin でまとめてコピーします。

インターフェースも同じ考え方で、すべてのコントロールを論理ピクセルあたり 2 サンプルで描画します。ブラウザのウィンドウサイズを変えても変わるのはワークスペースの大きさだけで、ボタンやメニューの大きさは変わりません。

画像の読み込みとエクスポート

PNG、JPEG、WebP などの画像のエンコードとデコードはブラウザが行います。

• デコードは createImageBitmap を優先し、<img> 要素をフォールバックに使います。
• エンコードは OffscreenCanvas.convertToBlob を優先し、<canvas> の toBlob をフォールバックに使います。
• ブラウザが形式に対応していないとき、toBlob はエラーを出さずに黙って PNG を返します。そのため、エンコード後に結果の実際の種類を確認し、エクスポートの前に 1×1 のテスト画像をエンコードして、ブラウザがどの形式をエクスポートできるかを調べます。

作品の保存場所

プロジェクトの保存先は 2 つあり、名前を付けて保存... の 保存先 で選びます。

ブラウザ内のプロジェクトはこの端末のこのブラウザにだけ存在し、同期されません。サイトのデータを消去すると削除されます。ユーザーガイドをご覧ください。

ファイルマネージャー：元のファイルに直接書き戻す

File System Access API に対応したブラウザ（デスクトップ版の Chrome、Edge など）では、開く と 保存 でシステムのファイルダイアログが表示されます。得られるのはファイルのコピーではなく、ファイルハンドルです。

• ファイルハンドルは IndexedDB に保存されるので、次の 保存 では保存先を尋ねずに同じファイルに書き戻します。
• 書き込む前に読み書きの権限を求め、createWritable() で書き込みます。
• ブラウザはファイルダイアログをユーザーのクリックから直接開くことを求めるので、クリック直後に他の非同期処理を挟まず showSaveFilePicker() を呼び出します。
• ページが他のサイトの iframe（ゲームポータルなど）に埋め込まれている場合、ブラウザはファイルダイアログを許可しません。その場合 Xprite は、非対応のブラウザと同じようにファイルをダウンロードします。

ブラウザ：IndexedDB のカタログと OPFS のデータ

ブラウザに保存したプロジェクトのカタログ（名前、サイズ、更新日時、現在のバージョン）は常に IndexedDB にあります。プロジェクトのデータは、できる限り OPFS（オリジンプライベートファイルシステム。ブラウザが各サイトに与える非公開のディスク領域）に保存します。OPFS を使うのは、ブラウザが Worker、navigator.storage.getDirectory()、Web Locks、書き込み可能なファイルハンドルに対応している場合だけです。保存方式はプロジェクトの作成時に決まり、その後は変わらないので、ブラウザの対応状況が変わっても古いプロジェクトが消えることはありません。

OPFS の読み書きは専用の Worker で行い、同期アクセスハンドル（createSyncAccessHandle）で書き込み、切り詰め、フラッシュを行います。保存のたびに次の手順をたどります。

データの破損を防ぐためのルールがいくつかあります。

• 書き込んだデータは追記のみです。各キーは一度しか書き込めず、途中で失敗したファイルは削除されます。
• 現在のバージョンを切り替えるのは最後のカタログのトランザクションだけで、それも他のタブが先に現在のバージョンを変えていない場合に限ります（コンペア・アンド・スワップ）。
• Xprite が複数のタブで開かれているときは、Web Locks で書き込みを排他制御します。
• .aseprite のチャンク境界で分割するので、変更していないフレームやレイヤーは同じセグメントに残ります。1 フレームを編集しても、変わったセグメントだけが書き込まれます。

自動復元

自動復元はブラウザへの保存と同じ保存経路を使います。編集中、Xprite は初期設定で 2 分ごとに復元データを保存し、7 日間保持します。間隔と日数は 編集 → 環境設定 → ファイル で変更できます。ブラウザが突然閉じた場合は、ホームで ファイルを復元... を選ぶと作業を取り戻せます。

共有リンク：スプライトは # の後ろにある

ファイル → 共有... は何もアップロードしません。スプライトは圧縮されて、リンクの #share= 以降の部分（URL フラグメント）に書き込まれます。ブラウザは # 以降をサーバーに送らないので、共有でサーバーに触れることはありません。

• まとめる処理、圧縮、デコードはすべて Worker で行います。Zstd は WebAssembly として動き、まずレベル 19 で圧縮し、1 MiB 未満の結果はさらに高いレベルで圧縮し直します。WebAssembly の読み込みに失敗した場合は DEFLATE だけを使い、リンクは問題なく開けます。
• QR コードの英数字モードは 1 文字あたり 5.5 ビットしか使わず、バイトモードよりコンパクトなので、QR コードにはこのモードの文字だけでできた Base43 エンコードを使います。
• リンクを開くと、エディターは #share= 以降のデータを読み取り、すぐに history.replaceState でアドレスバーから取り除いてから、Worker に渡してデコードします。
• 1,800 文字を超えるリンクには、チャットアプリによっては途中で切れることがあるという警告が表示されます。8,192 文字を超えるリンクは作成されません。

リンクには編集可能なプロジェクトがまるごと含まれます。リンク全体を持つ人は誰でも開けて、有効期限はなく、取り消すこともできません。リンクや QR コードをチャットアプリで送ると、そのアプリにも作品のデータが渡ります。

オフライン利用：一度に 1 つの完全なバージョン

Xprite をデスクトップやホーム画面に追加すると、Service Worker がエディターをキャッシュし、ネットワークがなくても開けるようになります（キャッシュには、先に一度オンラインでエディターを開く必要があります。手順はユーザーガイドをご覧ください）。キャッシュの方針は、バージョンの一貫性を保つことを軸にしています。

• ビルドごとに、そのバージョンのリソースマニフェストを生成し、すべてのファイルに SRI ハッシュを付けます。インストール時に cache.addAll でマニフェスト全体を一度にキャッシュします。1 つでもダウンロードに失敗したりハッシュが一致しなかったりすると、そのバージョンは有効にならないので、新旧のファイルが混ざることはありません。
• すべてキャッシュし終えると「準備完了」のマーカーを書き込み、オフライン起動ではこのマーカーがあるバージョンだけを使います。
• 新しいバージョンはインストールされるとすぐに切り替わりますが、すでに開いているページは古いコードで動き続けます。ハッシュ付きのファイル名を持つ古いアセットは残しておくので、それらのページも読み込めます。
• キャッシュするのはビルド成果物だけです。アクセス解析、フィードバックの送信先、サイトのページはキャッシュを通りません。
• 古いバージョンのキャッシュは、すべてのエディターウィンドウが閉じた後でだけ削除します。

対応しているブラウザでは永続ストレージ（navigator.storage.persist()）も要求し、容量が足りなくなったときにブラウザが作品を消去する可能性を下げています。

タッチスクリーンとペン

マウスのポインターは 1 つですが、タッチスクリーンにはペンと複数の指が同時に触れることがあります。入力レイヤーは次のルールで処理します。

ドラッグのしきい値もポインターの種類で変わります。指は 8 CSS ピクセルを超えて動かないとドラッグとみなされませんが、マウスやペンは 1 ピクセルで十分です。

より細かいストローク

ブラウザは処理を減らすため、1 フレーム内の複数の pointermove イベントを 1 つにまとめます。ペンで描くときは、getCoalescedEvents() からまとめられたサンプルをすべて取り出し、それぞれの筆圧の値も使います。ブラウザは予測サンプルも提供しますが、Xprite は使いません。予測した点は実際のストロークと一致しないことがあり、操作履歴に入ってはならないからです。

/** Real samples only: predicted input must never reach document history. */
const coalesced = event.getCoalescedEvents?.() ?? [];
const actual = coalesced.filter(
  (point) => point.pointerId === event.pointerId && point.pointerType === "pen",
);

iPad の Apple Pencil

iPad の Safari では、Apple Pencil で触れると初期設定でテキスト選択やスクリブルなどのシステムの動作が起きます。React のタッチリスナーはパッシブで既定の動作を止められないため、キャンバスとドラッグ可能なコントロールに非パッシブのネイティブ touchstart リスナーを直接登録し、touchType が stylus のときだけ preventDefault() を呼び出します。テキスト欄などの編集可能な領域には影響しないので、そこではスクリブルで書き込めます。

レイアウト：デスクトップのウィンドウから縦向きのスマホまで

Xprite のインターフェースは Aseprite 1.3 を再現しています。ダイアログのサイズやコントロールの位置は Aseprite 1.3.18 を計測したもので、テストで一致を保っています。テーマの画像は Aseprite のドット絵スタイルに倣い、中国語・日本語・韓国語のインターフェースには Fusion Pixel フォントを使っています。

ワイドな画面では、上にメニューバー、左にパレット、右にツール、下にタイムラインという、おなじみのデスクトップレイアウトになります。

このレイアウトは縦向きのスマホには収まりません。ワークスペースのレイアウト が 自動（初期設定）のときは、使える領域に合わせてレイアウトを選びます。ワイドレイアウト か コンパクトレイアウト に固定することもできます。ユーザーガイドをご覧ください。ルールは次のとおりです。

コンパクトレイアウトでは、メニューバーは左上の ☰ ボタンにまとめられ、インターフェースはノッチや角丸などのセーフエリアを避けて配置されます。

レイアウトと操作モードは別々に決まります。横向きの iPad はワイドレイアウトとタッチ操作を同時に使います。デスクトップのブラウザのウィンドウを狭めるとコンパクトレイアウトに切り替わりますが、マウス操作のままです。

Xprite が送信するデータ

編集、保存、共有ではネットワークを使いません。送信されるデータは 2 種類だけです。

利用状況の解析は PostHog Cloud（米国）に送られます。

• 訪問者 ID はブラウザの localStorage に保存されます。
• 元の IP アドレスは、おおよその位置を付けた後に破棄されます。
• セッション録画とクリックの自動取得はどちらもオフです。
• ブラウザでトラッキング拒否（Do Not Track）をオンにして Xprite を開き直すと、それ以降は利用データが送信されません。

詳しくはプライバシーについてをご覧ください。

オープンソース

ここで説明したすべてのソースコードは GitHub で公開しています。エディターのコードは GPL-2.0-only ライセンスです。