referenceupdated v8growing

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/ にしかない、マーカー付き bundleadopt.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.png

2.1 ファイル名

数字プレフィックスで実行順序を制御する:

10-utils.ts
20-model.ts
30-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 構文制約

#制約
1import は 1 行に収める
2複数行 import { a,\n b } は禁止
3トップレベル await は禁止
4import.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(...) { ... }

違反した場合

違反bundleverifyauditdev 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 個別変換

Terminal window
node scripts/html-build/to-js.mjs --project <name>

src/tools/<name>/dist-js/ に各 .ts を JS 化して出力する。ソースや bundle は上書きしない(予約ディレクトリへの書き込みは安全ガードで拒否される)。バンドルではなく素の JS ファイル群が必要な場合(Vite への受け渡し等)に使う。

7.7 型チェック

Terminal window
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 トップレベル識別子の重複

00-utils.js
function lum(hex) { ... }
// 10-palette.js
function 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プロジェクト名(ディレクトリ名と一致が望ましい)
templatedev テンプレートのパス(src/ 相対)
stylesCSS の glob(文字列 or 配列、src/ 相対)
scriptsJS/TS の glob(文字列 or 配列、src/ 相対)
entryentry の JS/TS(src/ 相対、実ファイルを指すこと)
outputbundle の出力先(public/ 相対。既定 "index.html")
recoveredsplit の既定出力先(src/ 相対)
tmpverify の一時ディレクトリ(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 本。

Terminal window
# 順方向(デフォルト): 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-fixaudit を検出のみにする
--no-verifyverify をスキップ(素早く bundle だけ見たいとき)
--serveビルド後に serve.mjs を起動(Ctrl+C で停止)
--reversesplit → 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 不要)

Terminal window
node scripts/html-build/bundle.mjs --list
node scripts/html-build/audit-imports.mjs --project my-project
node scripts/html-build/bundle.mjs --project my-project
node scripts/html-build/verify.mjs --project my-project
node scripts/html-build/smoke.mjs --project my-project
npm run typecheck

10.4 逆方向の手動実行(split 単体)

Terminal window
# 既定: 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 開発サーバ

Terminal window
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 server
responded with a MIME type of "text/plain". Strict MIME type checking is enforced for
module 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: 出力先
--fixaudit: 自動修復(既定で有効)
--no-fixaudit: 検出のみ
--no-verifybuild: verify をスキップ
--servebuild: ビルド後 serve を起動
--reversebuild: split → audit → verify
--keep-templatesplit: dev テンプレートを書き換えない
--drymigrate / adopt / clean: 変更せず予告のみ
--entireclean: プロジェクト丸ごと削除
--allsmoke / adopt / migrate: 対象全件

11. ツール動作

11.1 build(統合)

順方向(デフォルト):

  1. audit-imports.mjs を実行(--no-fix 指定時以外は --fix 付き)
  2. bundle.mjs を実行 → public/tools/<name>/index.html
  3. verify.mjs を実行(--no-verify 指定時以外)
  4. すべて exit 0 なら完了。--serve 指定時は dev サーバを起動

逆方向(--reverse):

  1. split.mjs を実行(--in → --out。既定は public/tools/<name>/index.html → src/tools/<name>/)
  2. audit-imports.mjs を実行(--fix 既定)
  3. verify.mjs を実行(内部で bundle を tmp に生成し、往復比較)
  4. bundle.mjs は 直接は走らせない(verify が内部で実行する)。public/tools/<name>/index.html は入力のまま更新しない
  5. 公開 bundle も新 src から作り直すには、続けて順方向 build.mjs を実行する

途中でどれかが失敗すれば即中断。CI でもローカルでも 1 本で回せる。

11.2 bundle(分割 → 単一)

  1. src/tools/<name>/ の CSS をファイル名順に読む。@file マーカーを検証
  2. JS/TS を読む。.ts / .tsx は esbuild で型剥がし(マーカー行は退避 → transform → 復元)
  3. @import: directive から依存グラフを構築しトポロジカルソート
  4. 循環依存があれば警告(続行)
  5. 相対 import 行と export キーワードを除去
  6. 外部 import を先頭に hoist
  7. src/tools/<name>/index.html(dev テンプレート)の <link> / <style> と <script> を inline 展開
  8. </script> を <\/script> にエスケープ
  9. public/tools/<name>/index.html に書き出し

11.3 split(単一 → 分割)

  1. <style> を抽出し /* === @file: === */ で分割
  2. inline <script type="module"> を抽出し // === @file: === で分割
  3. @import: / @export: directive を読む
  4. import 行を directive から再構築
  5. export キーワードを @export: に従って付与
  6. outDir に書き出し
  7. --keep-template が無ければ dev テンプレートを生成

安全弁(2026-10):

  • outDir が src/tools/<name> と一致する場合は削除せず上書き
  • 抽出結果が 0 css かつ 0 js の場合、dev テンプレートを 書き換えない(マーカーの無い HTML を渡された場合の防御)

11.4 verify(往復検証)

  1. src を bundle → src/tools/<name>/tmp/bundled.html
  2. tmp/bundled.html を split → src/tools/<name>/tmp/recovered/
  3. src と tmp/recovered/ を比較
    • .js: byte-exact
    • .ts / .tsx: directive 行のみの構造比較
  4. 全一致で 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.html
  • manifest.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();

ビルド:

Terminal window
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() 呼び出しが末尾に残る。

動作確認:

Terminal window
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.mjs 1 本で 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. 関連ドキュメント