feat: power reference site with in-process WIP WASM
Add the public-document Worldspace, Rust Client/Host bridge, and WIP-backed tree and document rendering while preserving static fallback and navigation. Pin the Rust source and build tools, verify resource and trap boundaries, and cover dev and preview loading including same-origin generated module URLs.
This commit is contained in:
@@ -1,91 +1,107 @@
|
||||
# WIP Reference
|
||||
|
||||
Worldspace Interface Protocolの仕様文書と、その文書を読むための静的サイトです。
|
||||
Worldspace Interface Protocolの仕様文書と、その文書を実際のWIPで読むサイトです。
|
||||
|
||||
## 構成
|
||||
|
||||
- [`contents/`](contents/) — 仕様の正本。番号付きMarkdownを章順に読みます。
|
||||
- [`contents/draft/`](contents/draft/) — API設計・投影方針などの草案。正本とは区別します。
|
||||
- [`site/`](site/) — AstroによるトップページとBook。文書のコピーは持たず、`contents/**/*.md`をビルド時に読み込みます。
|
||||
- [`contents/draft/`](contents/draft/) — 検討中の草案。公開サイトとWIPの生成データには含めません。
|
||||
- [`site/`](site/) — Astroの静的サイトと、ブラウザ内で動くRust Client / Host。
|
||||
|
||||
[第1章：コンセプト](contents/1-concept.md) / [Core Model](contents/2-core-model.md) / [Protocol](contents/3-protocol.md) / [Client](contents/4-client.md) / [WIP over HTTP](contents/5.1-wip-over-http.md)
|
||||
|
||||
以前の直下Markdownと`draft/`は`contents/`へ移動しました。文書の内容・ファイル名・相互の相対リンクは維持しています。外部からraw Markdownを参照する場合はパスへ`contents/`を追加してください。
|
||||
## ブラウザ内のWIP
|
||||
|
||||
```text
|
||||
ツリー・本文UI (TypeScript)
|
||||
→ BrowserSession (WASM公開API)
|
||||
→ wip-client::direct::Client
|
||||
→ 型付き要求・応答の直接呼び出し
|
||||
→ サイト用Worldspace / wip-host
|
||||
```
|
||||
|
||||
ClientとHostは同じWASM内にあります。三つのinteraction（observe、fetch_interface、call_operation）にHTTP binding、JSON wire envelope、socketは使いません。WASMと`worldspace.json`の取得、Astroによる静的ページ遷移は通常のasset/page配信です。
|
||||
|
||||
公開文書と既存のhome/indexコンポーネントから`worldspace.json`をビルド時に生成します。本文の別コピーを編集する必要はありません。Rust ProviderはそれをimmutableなWorldspaceとして公開し、本文はroot scopeの`document.read()`で取得します。章Objectは本文と子の節を同時に持ちます。
|
||||
|
||||
Worldspace path、表示用の既存識別子、Web URLは別です。たとえば：
|
||||
|
||||
- Worldspace: `/book/1-concept.md/1.1-interaction-abstraction.md`
|
||||
- 表示識別子: `/1.1-interaction-abstraction.md`
|
||||
- Web URL: `/book/1.1-interaction-abstraction/`
|
||||
|
||||
ツリーはClientの観測とOperation結果を使い、URL・履歴・折りたたみ・読書位置はUIが管理します。WASM sessionはAstroのページ切替をまたいで存続します。JavaScriptなし、WASM未対応、asset読み込み失敗時も、静的HTMLと通常リンクで閲覧できます。`data-wip-state="ready"`だけが実WIP経由の反映成功を表し、失敗時は`fallback`です。
|
||||
|
||||
主なファイル：
|
||||
|
||||
- `site/worldspace/` — サイト専用Rust Provider、入力検証、再帰observe、document Interface。
|
||||
- `site/browser/` — Rust ClientとHostを所有するWASM session。
|
||||
- `site/src/pages/worldspace.json.ts` — 公開文書・home/indexのデータ生成。
|
||||
- `site/src/scripts/browser-wip.ts` — WASM初期化、session寿命、結果検証と本文反映。
|
||||
- `site/src/scripts/landing.ts` — 共通ツリー、導入演出、ページ切替と読書位置。
|
||||
|
||||
### 実行上の境界
|
||||
|
||||
このサイトの操作は同期・メモリ内・読み取り専用です。入力JSONは16MiB、Object数4096、階層32を上限とし、Clientにもstate/history上限を設けています。JS APIにdeadlineや並行実行中のcancellation設定はなく、HostにはdeadlineなしのExecutionContextを渡します。ブラウザ非対応の`std::time::Instant::now()`を呼ぶdeadline経路は利用しません。将来deadlineを公開する場合はブラウザ対応時計と実行テストが必要です。
|
||||
|
||||
release WASMは`panic=abort`です。Rustのpanic/trapは`catch_unwind`でProtocol failureへ回復できるとは扱いません。通常の入力・ProtocolエラーはJS例外として返り、サイトは静的表示へfallbackします。trapしたinstanceは以後呼び出し・解放せず、そのブラウザdocumentの残りの寿命は静的表示へfallbackします。ページ切替でOperationを再実行せず、復帰には再読み込みによる新instanceを使います。
|
||||
|
||||
JS境界のJSONはサイト専用のtree/document DTOであり、汎用WIP wire形式ではありません。本文はビルド時に既存Markdown rendererが生成した公開HTMLです。任意の外部Hostが返すHTMLを無条件に挿入する汎用クライアントではありません。
|
||||
|
||||
## 開発・検証
|
||||
|
||||
Node.js 22.12以上（CIは24）、npmを使用します。
|
||||
Node.js 22.12以上（CIは24）、npm、Rust 1.97.1、`wasm32-unknown-unknown`標準ライブラリ、`wasm-bindgen-cli` 0.2.121を使います。Rust sourceはこのrepoの隣の`wip-rs/`に置き、`site/rust-source.json`で指定するrevisionをcheckoutします。
|
||||
|
||||
```sh
|
||||
# このrepositoryのrootで実行
|
||||
# 既存の隣接checkoutがある場合はcloneせず、その作業を保全してください。
|
||||
git clone https://gitea.hareworks.net/Hare/wip-rs ../wip-rs
|
||||
git -C ../wip-rs checkout "$(node -p 'require("./site/rust-source.json").revision')"
|
||||
rustup toolchain install 1.97.1 --component rustfmt --component clippy --target wasm32-unknown-unknown
|
||||
cargo +1.97.1 install wasm-bindgen-cli --version 0.2.121 --locked
|
||||
cd site
|
||||
npm ci
|
||||
npm run dev
|
||||
```
|
||||
|
||||
開発サーバーは通常 `http://localhost:4321/` です。
|
||||
`npm run dev`と`npm run build`は先にWASMをsourceから生成します。Rustとwasm-bindgenがPATHにないNix環境では、隣接`wip-rs/flake.lock`を使って開発環境・LLD・wasm-bindgenを起動します。Cargo.lockとwasm-bindgenのバージョンは固定し、rustup環境では`site/rust-toolchain.toml`を使います。通常のWASMビルドはRust sourceのrevisionとclean状態を確認します。Rust側を同時編集するローカル開発に限り`WIP_ALLOW_DIRTY_SOURCE=1`で明示的に解除できますが、release検証では解除しません。生成物`site/public/wip-wasm/`と`site/target/`はGit管理しません。
|
||||
|
||||
```sh
|
||||
npm run verify # unit tests → Astro/TypeScript check → production build → link checks
|
||||
npm run verify # unit tests → Astro check → WASM/build → link checks
|
||||
WIP_TEST_GENERATED=1 node --test tests/worldspace-data.test.mjs
|
||||
cargo test --workspace --locked -- --include-ignored # build後の実文書テストも実施
|
||||
cargo clippy --workspace --all-targets --locked -- -D warnings
|
||||
npx playwright install chromium
|
||||
npm run test:browser
|
||||
npm run test:dev # dev serverでも実WASMの読み込み・本文反映を確認
|
||||
# インストール済みChromeを使う場合：CHROME_PATH=/path/to/chrome npm run test:browser
|
||||
npm run preview
|
||||
```
|
||||
|
||||
`/`がトップページ、`/book/`が目次です。各章は`/book/3-protocol/`のように元のファイル名を保持します。草案は`/book/draft/rust-api-model/`などに分離し、草案である旨を表示します。サイドバー、章内目次、前後の章へのリンクはsourceから生成します。
|
||||
Nixでnativeテストを行う場合は`nix develop ../../wip-rs --command cargo test --workspace --locked -- --include-ignored`のように実行します。テスト用previewは`127.0.0.1:4322`、`test:dev`は別のdev serverを4323で起動し、通常のdev server（4321）を再利用・停止しません。`SITE_BASE=/reference npm run test:dev`でサブパスのWASM読み込みも確認できます。
|
||||
|
||||
ブラウザーでデスクトップ／モバイルの表示とナビゲーションを検証する場合（事前にbuildが必要）：
|
||||
`npm run test:browser`は先に`test-probes` feature付きの別WASMを`site/test-assets/`へ生成します。`wasm-limits.spec.ts`は実WASMの入力上限と意図的なRust panicを検証し、trapがProtocol failureへ誤変換されず、サイトがsessionを再利用しないことを確認します。このprobeはテストrouteでのみ配信され、通常の`public/`・`dist/`には入りません。
|
||||
|
||||
```sh
|
||||
npx playwright install chromium
|
||||
npm run test:browser
|
||||
# インストール済みChromeを使う場合：CHROME_PATH=/path/to/chrome npm run test:browser
|
||||
```
|
||||
ブラウザテストはPC/mobile、no-JS、実WASMの独立session・三つのinteraction、WIP結果によるUI更新、失敗fallback、履歴、初回演出、ライト／ダークを検証します。`wasm.spec.ts`は静的asset取得後にfetchを禁止して直接呼び出しを確認し、`wip.spec.ts`は壊した初期HTMLを実WIP結果が修復することまで確認します。
|
||||
|
||||
Bookの閲覧テストはJavaScript無効、ランディングのテストは有効にして実行します。スクリーンショットは`site/test-results/`に保存され、ランディングは動きが重なる途中フレームをデスクトップ／モバイルで記録し、移動・縮小・幹伸長の同時進行と、移動中のSVG／罫線の接続位置を検証します。サブパスbuildの検証時は同じ`SITE_BASE`を設定してください。テスト用previewは`127.0.0.1:4322`を使用し、4321のdev serverとは別に起動します。
|
||||
## 表示と文書編集
|
||||
|
||||
### ランディング
|
||||
`/`が独立したホーム、`/book/`が目次です。各章の既存Web URLを維持し、共通ツリーでは章の下に節を表示します。初回ホームの導入演出は入力で開始し、EscapeやSkipで完了できます。`prefers-reduced-motion`では演出を省略します。配色はOSの`prefers-color-scheme`へ追従し、JavaScriptなしでも有効です。
|
||||
|
||||
トップはSVGのルートマークから始まります。コンテの2はホバー専用の「Tap」表現で、ポインタを離すと消え、待っていても本編には進みません。クリック・ホイール／タッチスクロール・キー入力のいずれか一回で、全体を約3.9秒で最後まで再生します。ホバーは再生の前提ではなく、追加入力で段階を進めたり、再生を重ねたりもしません。Escapeまたは画面右下のスキップで直ちにデモへ移れます。ブラウザの修飾キー付きショートカットは妨げません。
|
||||
|
||||
ホバーの「Tap」はルートと同じSVG座標系に置き、スラッシュの上辺・下辺（`y=4`〜`60`）に一致するマスクで切り抜きます。左右の文字列は斜辺と平行に逆方向へ流れ、上下端は水平に揃います。
|
||||
|
||||
ルートは中間位置で停止せず、一つの弧状の軌道でツリーへ移動します。円周文字の上端接線への流出、ルートの縮小、直下への幹伸長を重ね、着地を待たずに右向きの枝とパネルのglitchを始めます。円の半径・曲率は変えません。移動中の枝もルートと同じ座標変換に乗せ、縦幹全体を`├`・`│`・`└`へずれなく引き継ぎます。主幹は連続したまま保ち、枝先とラベルにglitchを適用します。ページのヘッダーや周辺要素も末尾の収束に重ねて現れます。
|
||||
|
||||
ツリーとパネルはASCII glitchから確定した文字・罫線へ収束します。ノイズは局所的なセル置換を10Hzで更新し、全画面の点滅は使いません。空白・改行・日本語は保持し、完了／スキップ時には元の文字列を完全に復元します。
|
||||
|
||||
- `src/components/Landing.astro` — SVGと、最終的に操作するツリー／パネルの静的HTML。
|
||||
- `src/components/BoxFrame.astro` — `┌─┐`・`│`・`└─┘`によるText View／Call resultの枠。CSS borderやSVGで枠を代用せず、幅・高さに合わせて罫線素片をクリップします。JavaScript無効時も表示されます。
|
||||
- `src/lib/landing-ascii.mjs` — セル幅を保つ決定的なglitch文字置換。
|
||||
- `src/scripts/landing.ts` — 単一の`requestAnimationFrame`時計、役割別の速度曲線、固定円周＋上端接線の文字経路、幹の伸長から罫線への接続、ツリー操作。
|
||||
- `src/lib/landing-demo.ts` — ブラウザ内だけで使うサンプル。外部Hostへの接続、変更操作、通信はありません。Object signatureとInterface signatureを分け、本文は明示的なCallで表示します。
|
||||
- `src/styles/landing.css` — トップ全体を14pxのmonoフォント・24pxの行高で構成。フレーム幅を4ch単位に揃え、列・ガター・パディングもセルと行の整数倍にします。ツリーはSVGの線ではなく`├──`・`└──`・`│`などの罫線素片を使い、JavaScript無効時も同じ構造を表示します。モバイルはツリーとパネルを縦に配置します。
|
||||
|
||||
`prefers-reduced-motion: reduce`では演出を省略し、操作可能なデモを表示します。JavaScript無効時は静的なサンプルと説明・Bookリンクを表示し、モジュール取得失敗時も導入画面に閉じ込めません。再確認はページのリロードで行えます。
|
||||
|
||||
## 文書の編集
|
||||
|
||||
文書は`contents/`だけを編集します。各文書の先頭の`#`見出しをタイトルに使用するため、frontmatterは不要です。番号付き文書は番号順、草案は別グループで表示します。
|
||||
|
||||
Markdown上の相対`.md`リンクはリポジトリ上でもそのまま読めます。サイト生成時にremark pluginがBookのURLへ変換し、queryとfragmentを維持します。コードブロックや外部URLは変換しません。`npm run check:links`は生成ページ、文書の欠落、重複ID、内部リンク・画像・CSS/JSと見出しanchorを検証します。
|
||||
文書は`contents/`だけを編集します。先頭の`#`見出しをタイトルに使うためfrontmatterは不要です。Markdownの相対`.md`リンクはビルド時にBook URLへ変換し、query/fragmentを維持します。draftへのリンクは公開リンクにしません。`npm run check:links`で生成ページ・内部リンク・見出しanchorを検証します。
|
||||
|
||||
## サイト公開
|
||||
|
||||
静的出力の`site/dist/`を公開します。SSR、常駐Nodeサーバー、データベースは不要です。ホスティング先や公開ドメインはまだ固定していません。**このリポジトリへのpushだけでインターネット上へ自動デプロイされる設定ではありません。**
|
||||
静的出力の`site/dist/`を公開します。常駐WIPサーバー、Nodeサーバー、データベースは不要です。このrepositoryへのpushだけでインターネットへ自動デプロイする設定ではありません。
|
||||
|
||||
```sh
|
||||
cd site
|
||||
npm ci
|
||||
SITE_URL=https://your-domain.example npm run verify
|
||||
```
|
||||
|
||||
サブパスへ公開する場合：
|
||||
|
||||
```sh
|
||||
# サブパス配信の検証
|
||||
SITE_URL=https://your-domain.example SITE_BASE=/wip-reference npm run verify
|
||||
SITE_URL=https://your-domain.example SITE_BASE=/wip-reference npm run test:browser
|
||||
```
|
||||
|
||||
- `SITE_URL`：公開サイトのorigin（例：`https://your-domain.example`）。path prefixは`SITE_BASE`へ分離します。設定時にcanonical URLを生成し、未指定時に仮ドメインは埋め込みません。
|
||||
- `SITE_BASE`：公開path prefix。既定は`/`。サブパスの場合は、そのprefixへ`dist/`の内容を配置します。
|
||||
- 本番ビルドはリポジトリ全体をcheckoutし、作業directoryを`site/`、build commandを`npm ci && npm run verify`、output directoryを`site/dist/`（作業directory基準では`dist/`）にします。
|
||||
- Static hostではディレクトリの`index.html`を配信し、未知のURLへ`404.html`を返す設定を使用します。SPA fallbackは不要です。
|
||||
- 文書は静的HTML、コードの色付けはビルド時のShiki、モバイルの目次はHTMLの`details`です。閲覧にクライアント側JavaScriptを必要としません。
|
||||
|
||||
Gitea Actionsの`.gitea/workflows/site.yml`で、通常ビルドとサブパスビルドを検証し、公開用の`wip-reference-site` artifactを作成します。GiteaのActionsと対応runnerが必要です。Repository variablesの`SITE_URL`／`SITE_BASE`を設定すると成果物へ反映します。ホスティングへのアップロードは、その公開先を決めてから別途接続してください。
|
||||
- `SITE_URL`はorigin、`SITE_BASE`はpath prefixです。既定のbaseは`/`です。
|
||||
- Static hostはディレクトリの`index.html`を配信し、未知URLに`404.html`を返します。SPA fallbackは不要です。
|
||||
- `.wasm`は`application/wasm`で配信してください。モジュール、WASM、manifest、HTMLを同じbuildの成果物として公開します。
|
||||
- Gitea Actionsは固定revisionのRust sourceとサイトを組み合わせ、通常／サブパスの検証後に`wip-reference-site` artifactを作ります。Rust revisionの更新時は両repositoryのテストを実施し、参照commitを取得可能にしてからCIを動かしてください。
|
||||
|
||||
Reference in New Issue
Block a user