HTML Split/Bundle 規約
単一 HTML と分割ソースを双方向変換するための規約。src/ を SSOT、public/ を配信専用とする 2 層レイアウト・マーカー文法・directive と実 import の 1:1 対応・TypeScript 拡張・7 スクリプト + 統合ビルド(順方向 / 逆方向)の動作を規定する。
HTML Split/Bundle 規約
0. この文書の目的
単一 HTML として配布したいが、開発時は複数ファイルに分割したいという要求を満たす、言語非依存・実装非依存の共通ルール。ゲーム、ツール、可視化、LP などに適用できる。
- 分割ソース(複数の
.css/.js/.ts+ テンプレート HTML)→ 単一 HTML(bundle) - 逆方向の変換(split)も可能
- 前後で整合を検証できる(verify / audit / smoke)
- TypeScript を一次市民とする(esbuild を transformer として使う)
src/を SSOT、public/を配信専用とする 2 層レイアウト
想定読者: 生成 AI エージェント、または人間の開発者。本稿だけで任意の HTML プロジェクトを分割ソース化できる。
1. 基本思想
1.1 なぜ単一 HTML か
配布が簡単。file:// で開ける。CDN 不要。サーバ設定不要。
1.2 なぜ分割ソースか
1 ファイル 5,000 行は人間にも LLM にも扱いにくい。機能単位で編集・差分レビューしたい。
1.3 なぜ src/ と public/ を分けるか
src/= 編集する場所。SSOT。配信しない。manifest.json/index.html(dev テンプレート)/styles//js/を置く。public/= 配信する場所。index.html(bundle 1 枚)だけを置く。- 編集対象と成果物を物理的に分離することで、「public を直接いじって壊す」「bundle を編集して split と食い違う」事故を防ぐ。
- Vite / Next.js / webpack 等の業界標準パターン。
1.4 開始点と方向
| 開始点 | 手順 | コマンド |
|---|---|---|
| A. ソースから始める | src/tools/{name}/ に js/ styles/ index.html manifest.json を書く | build.mjs --project {name}(順方向) |
| B. 単一 HTML から始める | bundle 形式 HTML を src/tools/{name}/index.html に配置 | split.mjs → 以降は A と同じ |
| C. bundle を真として src を再構成する | 既存の public/tools/{name}/index.html が真 | build.mjs --project {name} --reverse |
| D. bundle-only プロジェクトを取り込む | public/ にしかない、マーカー付き bundle | adopt.mjs --project {name} → build.mjs |
| E. 旧レイアウトから移行する | public/tools/{name}/ 直下に split ソースがある | migrate.mjs |
シナリオ B の運用: ユーザ(人間)が先に「単一 HTML で作る」と指示して LLM に bundle を書かせ、それが動いたら 別の指示で split.mjs にかけて分割ソース化する、という 2 段階を想定する。1 回の指示で両方をやらせると、split のマーカー文法を守りながら HTML を書く認知的負荷が高く、ミスが出やすい。
シナリオ C の用途: src/ が古くなってしまい、配信中の public/tools/{name}/index.html が最新という状況(または外部から bundle を貼り付けた場合)。--reverse は split → audit → verify を走らせ、src を bundle から再構成する。public は元のまま(verify の内部 bundle は tmp に書かれる)。公開 bundle も新 src から作り直したい場合は、続けて順方向 build.mjs を実行する。
1.5 用語
| 用語 | 意味 |
|---|---|
| ソース | src/tools/{name}/js/*.{js,ts,tsx} styles/*.css。directive + 実 import + 実 export を持つ |
| テンプレート | src/tools/{name}/index.html。dev 形式(<link> + <script src>)または bundle 形式(<style> + inline script) |
| bundle 出力 | public/tools/{name}/index.html。全コードが inline 展開される |
| directive | // @import: // @export: コメント行。split の唯一の情報源 |
| marker | === @file: ... === のファイル境界 |
1.6 非目標
ミニファイ / Tree shaking / ソースマップ / 循環依存の解決(禁止)。
2. ディレクトリ構造
<repo>/├── scripts/html-build/ 共通ツール(1 セットだけ)│ ├── _shared.mjs CLI 解決・パス算出│ ├── build.mjs audit→bundle→verify(順)/ split→audit→verify(逆)│ ├── bundle.mjs 分割 → 単一│ ├── split.mjs 単一 → 分割│ ├── verify.mjs 往復検証│ ├── audit-imports.mjs directive / import 整合(既定 --fix)│ ├── smoke.mjs ブラウザ実行確認│ ├── to-js.mjs TS → JS(個別ファイル)│ ├── migrate.mjs 旧レイアウト → 新レイアウト│ ├── adopt.mjs bundle-only → src 取り込み│ ├── clean.mjs スクラッチ掃除 / プロジェクト完全削除│ ├── serve.mjs 開発サーバ(リポジトリルート配信)│ └── smoke/<name>.json プロジェクト別の確認手順│├── src/tools/ SSOT(非公開・編集する場所)│ └── <name>/│ ├── manifest.json│ ├── index.html dev テンプレート│ ├── styles/*.css│ ├── js/*.{js,ts,tsx}│ ├── tmp/ verify の一時領域(gitignore)│ ├── src-recovered/ split の既定出力(gitignore)│ └── dist-js/ to-js の出力(gitignore)│├── public/tools/ 配信専用(公開)│ └── <name>/│ └── index.html bundle 出力のみ│└── .cache/html-smoke/ smoke のスクラッチ(gitignore) └── <name>/ ├── bundle.html ├── smoke-split.png └── smoke-bundle.png2.1 ファイル名
数字プレフィックスで実行順序を制御する:
10-utils.ts20-model.ts30-ui.ts...90-boot.ts ← entry(最後)- 依存される側は小さい数字
- entry は最も大きい数字。
manifest.entryに指定 - CSS も同様
2.2 禁止事項
- ファイル名にスペース・日本語・大文字を含めない
- 数字は辞書順ソートされる(
10-a<10-b) public/tools/<name>/にjs/styles/を置かない(それはsrc/側)src/tools/<name>/index.htmlを bundle 形式で上書きしない(dev 形式を保つ)
3. マーカー文法
3.1 ファイル境界マーカー
各ソースファイルの先頭 1 行にパスを宣言する。bundle / split の唯一の手がかり。
/* === @file: styles/20-components.css === */// === @file: js/70-compose.ts ===- 1 行目厳守(先頭に改行・空白・BOM 不可)
===を 前後両方に書く- パスは相対(
./なし、src/tools/<name>/からの相対)
3.2 間違いやすいポイント
| ❌ | ✅ | 症状 |
|---|---|---|
// @file: js/x.js | // === @file: js/x.js === | missing @file marker |
| 先頭に空行 → 2 行目にマーカー | 1 行目 | 同上 |
| UTF-8 BOM 付き | BOM なし | 同上 |
// === @file: ./js/x.js === | // === @file: js/x.js === | mismatch |
BOM の診断: xxd js/x.ts | head -1(先頭が efbb bf なら BOM)。
3.3 ディレクティブ(JS/TS のみ)
@file の直後に並べる。
// @import: { app } from './60-model.ts';// @import: { countString } from './20-count.ts';// @export: truncate30, computeName, expandTpl- 1 行 1 import。複数行 import は禁止
- 相対パス(
./)は分割ソース内の依存。非相対パスは外部依存(bundle 時に hoist) (none)を明示すると意図が明確になる- directive に書いた import は必ず実
import行を伴う(6.4 節)。逆も同じ
3.4 完全な例
以下は 1 ファイルの例示であり、60-model.ts は別ファイルで定義されている前提。
// === @file: js/70-compose.ts ===// @import: { app } from './60-model.ts';// @export: truncate30
import { app } from './60-model.ts';
export function truncate30(s: string): string { const cps = Array.from(s || ''); return cps.length <= 30 ? s : cps.slice(0, 30).join('');}注意: 上は最小の完全形。実プロジェクトでは複数の import を持つが、その場合も directive と実 import の 1:1 対応 を崩さないこと。
最重要: directive と実コードは 1:1 で対応させる。
4. テンプレート src/tools/<name>/index.html
4.1 dev 形式
<link rel="stylesheet" href="./styles/10-base.css"><script type="module" src="./js/90-boot.js"></script>JS プロジェクトでは serve.mjs 経由で /src/tools/<name>/ を開けば動く。
TS プロジェクトではブラウザが .ts を実行できないため、dev 形式は動作しない(bundle 経由を使う)。詳細は 7.4 節と 10.5 節。
4.2 bundle 形式
<style>/* === @file: styles/10-base.css === */...</style><script type="module">// === @file: js/10-utils.js ===...</script>そのまま動き、split の入力にもなる。src/tools/<name>/index.html が bundle 形式の場合、split.mjs が dev 形式に書き換える(--keep-template で抑止可能)。
4.3 規約
<link>と<style>を 同時に書かない<script type="module">は inline かsrcの一方- entry は 1 つだけ
- 外部 CDN の
<script src>は bundle 対象外として残る - 非 module の inline
<script>(診断用など)はそのまま残る(bundle / split の対象外)
5. 依存関係のルール
5.1 相対 import
// @import: { chooseEnd } from './40-candidates.js';- パスは現在ファイルからの相対。拡張子を必ず付ける
- TS プロジェクトでは
import './foo.js'(拡張子.js、実体.ts)と書くのが esbuild の慣行 - ディレクトリは
js/配下で統一
5.2 外部 import
非相対パスは外部依存。bundle 時に <script type="module"> の先頭へ hoist される。同じモジュールからの import は名前単位でマージ。
5.3 実行順序
依存グラフをトポロジカルソートして連結。循環依存は禁止(bundle は警告を出すが dev ESM では TDZ で壊れる)。
5.4 グローバル汚染
bundle 後は単一スコープになるため、すべてのトップレベル名はプロジェクト全体で一意。audit は [missing] で未 import 参照を検出するが、トップレベル名の重複は検出しないので注意(bundle 実行時の Identifier 'x' has already been declared で初めて分かる)。
5.5 export の扱い
- ソース: 実コードに
exportを書く(dev ESM のため) - bundle:
import行を除去し、exportキーワードも除去(単一スコープでは不要) - split:
@export:directive を読み、ソース生成時にexportを再付与
非対称設計。bundle 出力に export を残す意味はない。
6. コーディング規約
6.1 構文制約
| # | 制約 |
|---|---|
| 1 | import は 1 行に収める |
| 2 | 複数行 import { a,\n b } は禁止 |
| 3 | トップレベル await は禁止 |
| 4 | import.meta は禁止 |
| 5 | 副作用コードは boot() に集約 |
| 6 | 変数名は全体で一意 |
| 7 | ミニファイしない |
| 8 | テンプレートリテラル内に @file / @import を書かない |
| 9 | </script> を文字列で含む場合は <\/script> と書く |
6.2 ファイル末尾
改行は LF、末尾は 1 改行のみ。
6.3 @export と実 export の同期
directive と実コードを一致させる。ずれは audit-imports.mjs の [missing] で報告(--fix 対象外・手で直す)。
6.4 @import と実 import の同期 — 最重要
// === @file: js/110-ui.ts ===// @import: { $, $$, uid } from './10-utils.ts';// @import: { Store } from './50-storage.ts';// @export: toast, setUnsaved
import { $, $$, uid } from './10-utils.ts';import { Store } from './50-storage.ts';
export function toast(...) { ... }違反した場合
| 違反 | bundle | verify | audit | dev ESM |
|---|---|---|---|---|
| directive だけ・実 import なし | 通る | 落ちる | [directive-only] | ReferenceError |
| 実 import だけ・directive なし | 通る | 落ちる | [import-only] | 動く |
bundle は single-scope に結合するため実 import が無くても識別子が解決する。dev ESM では ReferenceError。この非対称性が最大の罠。
検出と修復
✗ js/110-ui.ts — 2 issue(s) [directive-only] // @import: { Store } from './50-storage.ts'; → add: import { Store } from './50-storage.ts'; (fixable with --fix) [import-only] import { foo } from './20-count.ts'; → add: // @import: { foo } from './20-count.ts'; (fixable with --fix)audit-imports.mjs は既定で --fix。--no-fix で検出のみ。[missing] だけは手動。
6.5 3 形式の対応
| 形式 | directive | 実 import | 実 export |
|---|---|---|---|
| ソース | あり | あり | あり |
| bundle 出力 | あり | なし | なし |
| split 出力 | あり | あり(directive から再生成) | あり(directive から再付与) |
7. TypeScript 拡張
7.1 変換
.ts / .tsx は bundle.mjs が esbuild を transformer として使って JS に変換し、その後マーカー駆動の連結パイプラインに流す。esbuild は bundler としては使わない。
7.2 マーカー・directive
すべて JS と同じ。ファイル拡張子だけが異なる。@file のパスも .ts を書く。
7.3 型 import の扱い
import type { X } from './y.ts'は directive 不要(esbuild が型を消す)import { type X, Y } from './y.ts'は 値 import の Y のみ directive 必須- audit は値 import のみを directive と突合する
7.4 split の扱い(TS)
split は TS 非依存。@file: マーカー駆動なので、.ts / .tsx を宣言するブロックもそのまま復元できる。ただし:
- esbuild が型を消した後の JS が復元される(byte-exact ではない)
- そのため verify は directive 行のみの構造比較に切り替える(後述 7.5)
- ブラウザは
.tsを実行できないため、dev ESM としての動作確認はできない smoke.mjsはjs/に.ts/.tsxが 1 つでもあれば split の実行テストを自動スキップし、bundle のみ検証する
「split は動くが dev ESM として動かない」が正確な理解。初めてのツールは .js で書き、必要になったら .ts に移行するのが挫折しにくい。
7.5 verify
.ts は型消去のため byte-exact 比較が不可能。verify は directive 行のみの構造比較に切り替える。型レベルの検証は tsc --noEmit が担う。
7.6 TS → JS 個別変換
node scripts/html-build/to-js.mjs --project <name>src/tools/<name>/dist-js/ に各 .ts を JS 化して出力する。ソースや bundle は上書きしない(予約ディレクトリへの書き込みは安全ガードで拒否される)。バンドルではなく素の JS ファイル群が必要な場合(Vite への受け渡し等)に使う。
7.7 型チェック
npm run typecheck # tsc --noEmitルートの tsconfig.json の include / exclude で検査対象を src/tools/**/*.ts に限定する。public/tools/** は bundle 出力なので除外。
8. アンチパターン
8.1 循環依存
// a.ts → b.ts → a.ts別ファイルへ移す・依存を引数化する。bundle は警告を出して続行するが、dev ESM では const の TDZ で壊れる。
8.2 複数行 import
// ❌import { foo, bar,} from './lib.js';
// ✅import { foo, bar } from './lib.js';8.3 トップレベル副作用
// ❌document.addEventListener('click', handler);
// ✅function boot() { document.addEventListener('click', handler); }boot();8.4 directive だけ書いて実 import を省略
LLM が最も頻繁に踏む罠。
// ❌ bundle は通るが verify / audit / dev ESM が落ちる// @import: { Store } from './50-storage.ts';export function toast(msg) { Store.get(...); }
// ✅// @import: { Store } from './50-storage.ts';import { Store } from './50-storage.ts';export function toast(msg) { Store.get(...); }8.5 トップレベル識別子の重複
function lum(hex) { ... }
// 10-palette.jsfunction lum(hex) { ... } // ❌ bundle で "Identifier 'lum' has already been declared"dev ESM では別スコープなので動くが、bundle では 1 スコープなので衝突する。同一プロジェクト内で全トップレベル名を一意にする。検出は現状 smoke の pageerror に頼る(audit の自動検出は範囲外)。
8.6 split をソースに直接かける
split の入力は bundle 形式の HTML(inline <style> / <script>、実 import なし)。ソース HTML(dev 形式)に直接かけると <style> も inline <script type="module"> も無いので失敗する。
正しい: ソース → bundle → public/index.html → split → src-recovered/
8.7 public 側を直接編集
public/tools/<name>/index.html は bundle 出力。ここを直接編集しても次回の build.mjs で上書きされる。編集は必ず src/ 側で。
9. manifest.json
配置: src/tools/<name>/manifest.json(旧 public/tools/<name>/manifest.json から移動)。
{ "name": "project-name", "template": "index.html", "styles": ["styles/*.css"], "scripts": ["js/*.ts"], "entry": "js/90-boot.ts", "output": "index.html", "recovered": "src-recovered", "tmp": "tmp", "marker": { "file": "=== @file:" }}| キー | 意味 |
|---|---|
name | プロジェクト名(ディレクトリ名と一致が望ましい) |
template | dev テンプレートのパス(src/ 相対) |
styles | CSS の glob(文字列 or 配列、src/ 相対) |
scripts | JS/TS の glob(文字列 or 配列、src/ 相対) |
entry | entry の JS/TS(src/ 相対、実ファイルを指すこと) |
output | bundle の出力先(public/ 相対。既定 "index.html") |
recovered | split の既定出力先(src/ 相対) |
tmp | verify の一時ディレクトリ(src/ 相対) |
marker | マーカー文法(変更禁止) |
entry の注意: manifest.entry は実ファイルのパスでなければならない。"entry": "index.html" のような誤設定は、split が dev テンプレートの <script src> に自己参照を書き込む地雷になる(archive-below で実際に発生)。
10. ツール実行
10.1 配置
すべてのツールは <repo>/scripts/html-build/ に 1 セット。_shared.mjs が __dirname/../.. から <repo> を自動算出する。
10.2 一括ビルド(推奨)
通常はこれ 1 本。
# 順方向(デフォルト): audit(--fix) → bundle → verify# src/tools/<name>/ → public/tools/<name>/index.html# サーバは起動しない。ビルドだけ。node scripts/html-build/build.mjs --project <name>
# ビルド後に dev サーバも起動(Ctrl+C で停止)node scripts/html-build/build.mjs --project <name> --serve
# 逆方向: split → audit(--fix) → verify# public/tools/<name>/index.html → src/tools/<name>/# public は入力のまま(更新しない)。公開 bundle を更新したい場合は# 続けて順方向 build.mjs を実行する。node scripts/html-build/build.mjs --project <name> --reverse
# 逆方向で入力 HTML を明示node scripts/html-build/build.mjs --project <name> --reverse --in /tmp/some.html--serve の有無:
- 指定なし: ビルドのみ。サーバは起動しない。最後に「
npm run serveでサーバを起動できます」というメッセージが表示される - 指定あり: ビルド成功後に
serve.mjsをspawnし、Ctrl+C まで常駐する
「build.mjs を実行したらサーバが立ち上がる」と誤解しやすいので、出力メッセージを明確に分けている。
オプション:
| オプション | 効果 |
|---|---|
--no-fix | audit を検出のみにする |
--no-verify | verify をスキップ(素早く bundle だけ見たいとき) |
--serve | ビルド後に serve.mjs を起動(Ctrl+C で停止) |
--reverse | split → audit → verify(bundle は走らせない) |
--in <path> | 逆方向時の入力 HTML(既定: public/tools/<name>/index.html) |
--out <path> | 逆方向時の出力先(既定: src/tools/<name>/) |
逆方向の注意:
- split の出力先が
src/tools/<name>と一致する場合、split は ディレクトリを消さず上書きする(manifest.json/index.htmlを保護するため) - 新しい bundle に含まれない古い
.js/.cssが src に残っていると、そのまま維持される(手でrmするか、build.mjsでEntry不一致エラーを確認) - 逆方向では
public/tools/<name>/index.htmlは元のまま(更新しない)。公開 bundle も新 src から作り直すには、続けて順方向build.mjsを実行する
10.3 個別実行(cd 不要)
node scripts/html-build/bundle.mjs --listnode scripts/html-build/audit-imports.mjs --project my-projectnode scripts/html-build/bundle.mjs --project my-projectnode scripts/html-build/verify.mjs --project my-projectnode scripts/html-build/smoke.mjs --project my-projectnpm run typecheck10.4 逆方向の手動実行(split 単体)
# 既定: public/tools/<name>/index.html → src/tools/<name>/src-recovered/node scripts/html-build/split.mjs --project <name>
# src を直接上書き(bootstrap / 旧レイアウトからの移行 / bundle を真とする)node scripts/html-build/split.mjs --project <name> --out src/tools/<name>
# 入力・出力を明示node scripts/html-build/split.mjs --project <name> \ --in public/tools/<name>/index.html \ --out /tmp/recovered--out が src/tools/<name> と一致する場合、split は ディレクトリを消さず上書きする(manifest.json を保護するため)。--keep-template を付けると dev テンプレートを書き換えない。
10.5 開発サーバ
node scripts/html-build/serve.mjs# index: http://localhost:8000/# dev ESM: http://localhost:8000/src/tools/<name>/# bundle: http://localhost:8000/public/tools/<name>/リポジトリルートを配信するので、src 側と public 側が 同一オリジン で叩ける。
TS プロジェクトでの注意: /src/tools/<name>/ を開くと、ブラウザの console に
Failed to load module script: Expected a JavaScript-or-Wasm module script but the serverresponded with a MIME type of "text/plain". Strict MIME type checking is enforced formodule scripts per HTML spec.が出る。これは .ts をブラウザが実行できないことによる 想定内の挙動。TS プロジェクトでは /public/tools/<name>/(bundle)を開くこと。.js プロジェクトなら /src/... がそのまま動く(hello の例を .js で実装した場合も同様)。
10.6 CLI オプション
| 短縮 | 長い版 | 意味 |
|---|---|---|
-p | --project <name|path> | プロジェクト名またはパス |
--root <path> | プロジェクトルートを直接指定(レガシー互換) | |
--src <path> | src ルートを明示 | |
--pub <path> | public ルートを明示 | |
--projects-dir <path> | 探索先(既定: <repo>/src/tools) | |
-l | --list | プロジェクト列挙 |
-i | --in <path> | split / build —reverse: 入力 HTML |
-o | --out <path> | bundle / split / to-js / build —reverse: 出力先 |
--fix | audit: 自動修復(既定で有効) | |
--no-fix | audit: 検出のみ | |
--no-verify | build: verify をスキップ | |
--serve | build: ビルド後 serve を起動 | |
--reverse | build: split → audit → verify | |
--keep-template | split: dev テンプレートを書き換えない | |
--dry | migrate / adopt / clean: 変更せず予告のみ | |
--entire | clean: プロジェクト丸ごと削除 | |
--all | smoke / adopt / migrate: 対象全件 |
11. ツール動作
11.1 build(統合)
順方向(デフォルト):
audit-imports.mjsを実行(--no-fix指定時以外は--fix付き)bundle.mjsを実行 →public/tools/<name>/index.htmlverify.mjsを実行(--no-verify指定時以外)- すべて exit 0 なら完了。
--serve指定時は dev サーバを起動
逆方向(--reverse):
split.mjsを実行(--in→--out。既定はpublic/tools/<name>/index.html→src/tools/<name>/)audit-imports.mjsを実行(--fix既定)verify.mjsを実行(内部で bundle を tmp に生成し、往復比較)bundle.mjsは 直接は走らせない(verify が内部で実行する)。public/tools/<name>/index.htmlは入力のまま更新しない- 公開 bundle も新 src から作り直すには、続けて順方向
build.mjsを実行する
途中でどれかが失敗すれば即中断。CI でもローカルでも 1 本で回せる。
11.2 bundle(分割 → 単一)
src/tools/<name>/の CSS をファイル名順に読む。@fileマーカーを検証- JS/TS を読む。
.ts/.tsxは esbuild で型剥がし(マーカー行は退避 → transform → 復元) @import:directive から依存グラフを構築しトポロジカルソート- 循環依存があれば警告(続行)
- 相対 import 行と
exportキーワードを除去 - 外部 import を先頭に hoist
src/tools/<name>/index.html(dev テンプレート)の<link>/<style>と<script>を inline 展開</script>を<\/script>にエスケープpublic/tools/<name>/index.htmlに書き出し
11.3 split(単一 → 分割)
<style>を抽出し/* === @file: === */で分割- inline
<script type="module">を抽出し// === @file: ===で分割 @import:/@export:directive を読むimport行を directive から再構築exportキーワードを@export:に従って付与outDirに書き出し--keep-templateが無ければ dev テンプレートを生成
安全弁(2026-10):
outDirがsrc/tools/<name>と一致する場合は削除せず上書き- 抽出結果が 0 css かつ 0 js の場合、dev テンプレートを 書き換えない(マーカーの無い HTML を渡された場合の防御)
11.4 verify(往復検証)
- src を bundle →
src/tools/<name>/tmp/bundled.html tmp/bundled.htmlを split →src/tools/<name>/tmp/recovered/- src と
tmp/recovered/を比較.js: byte-exact.ts/.tsx: directive 行のみの構造比較
- 全一致で exit 0
11.5 audit-imports(静的監査・既定 —fix)
検出項目:
[missing]: 未 import 参照(heuristic・--fix対象外)[directive-only]:@import:はあるが実 import 行が無い[import-only]: 実 import 行はあるが@import:が無い[bom][crlf][marker][import-format][trailing-newline]
既定で 2〜8 を自動修復。--no-fix で検出のみ。
11.6 smoke(ブラウザ実行確認)
public/tools/<name>/index.htmlがsrc/から作り直した結果と一致するか(bundle し忘れ検出)src/tools/<name>/(dev ESM)とpublic/tools/<name>/(bundle)を Chromium で動かし、smoke/<name>.jsonの手順を通す- TS プロジェクトでは split 実行を自動スキップ
- スクラッチとスクショは
.cache/html-smoke/<name>/(gitignore) - 自前の静的サーバを起動し、リポジトリルートを配信するので
/src/...と/public/...を同一オリジンで叩ける
11.7 to-js(TS → JS 個別変換)
src/tools/<name>/js/*.tsを 1 ファイルずつ esbuild で変換しdist-js/に書き出す- ソース / bundle は変更しない
--outで出力先を変えられる。予約ディレクトリ(js/styles/tmp/src-recovered/)への書き込みは拒否される
11.8 migrate(旧 → 新レイアウト)
旧 public/tools/<name>/{manifest.json,index.html,styles/,js/,bundle/index.html} を:
manifest.json/index.html/styles//js/→src/tools/<name>/bundle/index.html→public/tools/<name>/index.htmlmanifest.outputを"index.html"に正規化
に移す。--dry で予告のみ。bundle-only(split ソースが無い)プロジェクトは既定でスキップし、--force で bundle だけ移す。
11.9 adopt(bundle-only → src)
public/tools/<name>/index.html に @file: マーカー付きの <style> と inline <script type="module"> が 両方 あるときだけ、src/ に取り込む。無い場合は ineligible としてスキップする(半端な src を作らない)。
取り込み後は build.mjs で bundle を再生成して確認する。
11.10 clean(スクラッチ掃除)
tmp/out/dist-js/src-recoveredをsrc/tools/*/とpublic/tools/*/から削除--entire --project <name>で src と public の両方を丸ごと削除--dryで予告のみ
12. サンプル(最小プロジェクト・JS 版)
初心者向け: まずは .js で書くこと。.js なら dev ESM(/src/tools/hello/)がそのまま動く。.ts にしたくなったら 7.4 節の注意を読んでから拡張子を変える。
src/tools/hello/├── manifest.json├── index.html├── styles/10-base.css└── js/ ├── 10-utils.js ├── 20-state.js └── 90-boot.js
public/tools/hello/└── index.html ← bundle.mjs の出力src/tools/hello/index.html(dev 形式):
<!DOCTYPE html><html lang="en"><head><meta charset="UTF-8"><title>Hello</title><link rel="stylesheet" href="./styles/10-base.css"></head><body><div id="app"></div><script type="module" src="./js/90-boot.js"></script></body></html>src/tools/hello/manifest.json:
{ "name": "hello", "template": "index.html", "styles": ["styles/*.css"], "scripts": ["js/*.js"], "entry": "js/90-boot.js", "output": "index.html", "recovered": "src-recovered", "tmp": "tmp", "marker": { "file": "=== @file:" }}js/10-utils.js:
// === @file: js/10-utils.js ===// @import: (none)// @export: $, randInt, clamp
export const $ = (s, r = document) => r.querySelector(s);export const randInt = (n) => Math.floor(Math.random() * n);export const clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));js/20-state.js:
// === @file: js/20-state.js ===// @import: { randInt } from './10-utils.js';// @export: state, resetState, stepState
import { randInt } from './10-utils.js';
export const state = { count: 0 };export function resetState() { state.count = 0; }export function stepState() { state.count += randInt(3); }js/90-boot.js:
// === @file: js/90-boot.js ===// @import: { $ } from './10-utils.js';// @import: { state, resetState, stepState } from './20-state.js';// @export: boot
import { $ } from './10-utils.js';import { state, resetState, stepState } from './20-state.js';
export function boot() { resetState(); const app = $('#app'); function loop() { stepState(); if (app) app.textContent = 'count: ' + state.count; requestAnimationFrame(loop); } loop();}
boot();ビルド:
node scripts/html-build/build.mjs --project hello→ public/tools/hello/index.html が生成され、<script> は:
<script type="module">// === @file: js/10-utils.js ===// @import: (none)// @export: $, randInt, clamp
const $ = (s, r = document) => r.querySelector(s);const randInt = (n) => Math.floor(Math.random() * n);const clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
// === @file: js/20-state.js ===// @import: { randInt } from './10-utils.js';// @export: state, resetState, stepState
const state = { count: 0 };function resetState() { state.count = 0; }function stepState() { state.count += randInt(3); }
// === @file: js/90-boot.js ===// @import: { $ } from './10-utils.js';// @import: { state, resetState, stepState } from './20-state.js';// @export: boot
function boot() { ... }
boot();</script>import 行と export キーワードは除去される。entry の boot() 呼び出しが末尾に残る。
動作確認:
node scripts/html-build/build.mjs --project hello --serve# → http://localhost:8000/src/tools/hello/ (dev ESM, JS なので動く)# → http://localhost:8000/public/tools/hello/ (bundle)TS 化する場合: 拡張子を .ts に、コードに型を書く。manifest.scripts と entry も js/*.ts / js/90-boot.ts に更新。ただし /src/ は MIME エラーで動かなくなる(10.5 節)。動作確認は /public/ のみ。
13. チェックリスト
13.1 新規プロジェクト(ソースから)
-
src/tools/{name}/作成 -
index.htmlを dev 形式で作成 -
manifest.json作成(entryは実ファイルを指す) -
styles/js/を数字プレフィックスで作成 - 各ファイルの 1 行目に
=== @file: ... ===(BOM なし・===両側) - JS/TS の 2 行目以降に
@import:/@export:directive - directive と実 import / export を 1:1 で対応
- トップレベル名がプロジェクト全体で一意
-
importは 1 行ずつ、exportは実コードに書く - トップレベル副作用なし、
boot()に集約、entry 末尾でboot();を呼ぶ -
node scripts/html-build/build.mjs --project {name}→ exit 0 -
node scripts/html-build/smoke.mjs --project {name}→ split / bundle 両方 ✓(TS は bundle のみ) -
npm run typecheck→ exit 0(TS プロジェクト)
13.2 既存単一 HTML から
シナリオ B(ユーザが先に単一 HTML を作る場合): エージェントに「まず単一 HTML を作れ」と指示し、動作確認後に別途「split して src に取り込め」と指示する。
- モノリシック HTML を
src/tools/{name}/index.htmlに配置(bundle 形式) -
manifest.json作成 -
node scripts/html-build/split.mjs --project {name} --out src/tools/{name} -
js/styles/の中身を確認 - 以降は 13.1 と同じ
13.3 bundle-only から(シナリオ D)
-
public/tools/{name}/index.htmlに@file:マーカーが入っているか確認 -
node scripts/html-build/adopt.mjs --project {name} -
node scripts/html-build/build.mjs --project {name} -
node scripts/html-build/smoke.mjs --project {name}
13.4 bundle を真として src を再構成する(シナリオ C)
- 新しい bundle HTML を
public/tools/{name}/index.htmlに配置 - 古い
src/tools/{name}/js/styles/を必要に応じて削除(残っていると古いファイルが維持される) -
node scripts/html-build/build.mjs --project {name} --reverse - 必要に応じて公開 bundle も更新:
node scripts/html-build/build.mjs --project {name} -
node scripts/html-build/smoke.mjs --project {name}
14. エージェントへの指示テンプレート
用途別に 2 種類。シナリオ B では「単一 HTML を作る指示」と「split する指示」を別ターンに分けること(1 ターンで両方やらせると、マーカー文法を守りながら HTML を書く負荷でミスが出やすい)。
14.1 シナリオ A: ソースから作る
HTML プロジェクトを「分割ソース + ビルド」方式で実装する。共通ツールは配置済み、触らない: <repo>/scripts/html-build/{build,bundle,split,verify,audit-imports,smoke,to-js}.mjs
■ レイアウト- src/tools/{name}/ ← 編集する場所(SSOT・非公開) manifest.json index.html dev 形式テンプレート styles/*.css js/*.{js,ts,tsx}- public/tools/{name}/ ← 配信する場所(bundle のみ) index.html build.mjs の出力(手で編集しない)
■ マーカー(1 行目厳守・BOM なし・先頭に空行なし)- CSS: `/* === @file: styles/NN-name.css === */`- JS: `// === @file: js/NN-name.js ===`- TS: `// === @file: js/NN-name.ts ===`- 2 行目以降に directive: // @import: { name } from './NN-other.ts'; // @export: name1, name2
■ 最重要ルールdirective (`// @import:` / `// @export:`) と実コード (`import` / `export`) を1:1 で対応させる。片方だけ書いてはいけない。
❌ // @import: { Store } from './50-storage.ts'; export function foo() { Store.get(...); } // 実 import なし
✅ // @import: { Store } from './50-storage.ts'; import { Store } from './50-storage.ts'; export function foo() { Store.get(...); }
■ コーディング- import は 1 行ずつ(複数行禁止)- export は実コードに書く(bundle で除去される)- トップレベル副作用禁止。boot() に集約し entry 末尾で boot() を呼ぶ- トップレベル名はプロジェクト全体で一意(bundle で 1 スコープになるため)- ファイル末尾は LF で 1 改行- テンプレートリテラル内に @file / @import を書かない- 循環依存禁止- ミニファイしない
■ index.html (src/tools/{name}/index.html)- dev 形式: <link rel="stylesheet" href="./styles/NN-name.css"> と <script type="module" src="./js/NN-boot.js"></script>- 最初は .js で書く(.js なら /src/ がブラウザで動く)。 必要になったら .ts に移行(dev ESM は動かなくなる。7.4 節参照)。
■ manifest.json (src/tools/{name}/manifest.json){ "name":"{name}", "template":"index.html", "styles":["styles/*.css"], "scripts":["js/*.js"], "entry":"js/90-boot.js", "output":"index.html", "recovered":"src-recovered", "tmp":"tmp", "marker":{"file":"=== @file:"} }
■ 自己検証(すべて exit 0 が前提) node scripts/html-build/build.mjs --project {name} node scripts/html-build/smoke.mjs --project {name} npm run typecheck # TS のみ
■ 出力各ファイルをコードブロックで出力。直前にパスを明記。
■ 要件(ここに個別要件を書く)14.2 シナリオ B: HTML 単体から始める(2 ターン運用)
ターン 1(ユーザ → エージェント):
単一の HTML ファイルとして動くツールを作る。- 出力は 1 枚の index.html のみ。inline <style> と inline <script type="module"> を含む。- まだ split はしない。まず動作する単一 HTML を作り、動作確認したい。- 依存ライブラリは CDN から読む(<script src="https://...">)。- 以下は後続ターンで split するので、今は気にしなくてよい: - @file: / @import: / @export: マーカー - src/tools/<name>/ のレイアウト
■ 要件(ここに個別要件を書く)ターン 2(ユーザ → エージェント、ターン 1 で単一 HTML が動いた後):
上で作った単一 HTML を分割ソースに移行する。
■ 入力- 単一 HTML: <path/to/index.html>- プロジェクト名: {name}
■ 手順1. `mkdir -p src/tools/{name}`2. 単一 HTML を `src/tools/{name}/index.html` に配置3. `node scripts/html-build/split.mjs --project {name} --out src/tools/{name}`4. 生成された `js/`, `styles/`, `index.html`, `manifest.json` を確認5. `node scripts/html-build/build.mjs --project {name}`6. `node scripts/html-build/smoke.mjs --project {name}`
■ split が失敗したとき- 元の HTML に `@file:` マーカーが入っていない場合は失敗する。 その場合は、元 HTML を「bundle 形式に書き換える」ところから やり直す必要がある(inline <style> / inline <script type="module"> に `/* === @file: ... === */` / `// === @file: ... ===` を埋め込む)。- split の安全弁(0 件抽出時は dev テンプレートを書き換えない)により、 不完全な入力では index.html が保護される。ログを確認せよ。
■ 出力手順 4-6 の結果を報告。エラーがあれば原因と修正を提示。15. まとめ
- 3 つのマーカー(
@file/@import/@export)がすべて ===を両側に、1 行目厳守、BOM なし- directive と実
import/exportは 1:1 対応(bundle は通っても verify / audit / dev ESM が落ちる) src/tools/<name>/が SSOT、public/tools/<name>/index.htmlは配信専用(直接編集しない)manifest.jsonはsrc/側build.mjs1 本で audit(—fix) → bundle → verify が回る(--serveで dev サーバ同時起動)build.mjs --reverseで split → audit → verify(bundle から src を再構成するとき)- シナリオ B(単一 HTML から)は 2 ターン運用: まず単一 HTML を作り、動いたら別指示で split
- 最初は
.jsで書く。.jsなら/src/がブラウザで動く。.tsにしたくなったら 7.4 節を読む importは 1 行ずつ、exportは実コードに書く(bundle で除去される)- トップレベル副作用禁止、
boot()に集約、entry 末尾で呼ぶ - 循環依存禁止、トップレベル名は全体で一意
- TypeScript は esbuild を transformer として併用(bundler としては使わない)
- split は TS 非依存(.ts も構造的に復元可能)。dev ESM としての実行は TS 不可で、smoke が split 実行を自動スキップ
to-js.mjsで TS → JS の個別変換が可能(src/tools/<name>/dist-js/)- 開発サーバ は
serve.mjs(リポジトリルート配信、/src/tools/と/public/tools/が同一オリジン) - 移行ツール:
migrate.mjs(旧 → 新)、adopt.mjs(bundle-only → src)、clean.mjs(掃除・削除)
16. 関連ドキュメント
- HTML ツールカタログ: public/tools/ に置ける HTML アプリ・ゲームのカタログ
- Text Chunker 仕様書: 2026-09-27-text-chunker-spec
- Text Chunker 引き継ぎ: Text Chunker 引き継ぎレポート — 分割ソース化・BASELINE-3 到達と Batch 4 修正計画
- boardface / manual-gen 配置方針: boardface と manual-gen の配置方針決定 - 非対称配置と src/public 分離