egatari 0.0.0-stage → 0.6.4

package/kit/core/components-lock.mjs

@@ -0,0 +1,169 @@
+// 部品庫の部品（egatari/components のリリース）の写しと、その版の固定（components.lock.json）
+//   写し：vendor/components/sha256/<hash>/{index.js, README.md, demo.html …}（版ごとの content 表で引く）
+//   固定：components.lock.json（npm run components:update -- vX.Y.Z が書く。手で直さない）
+//     { "source": "https://github.com/egatari/components", "tag": "v1.0.0", "tarballSha256": "…",
+//       "releases": { "v1.0.0": { "tarballSha256": "…" } },
+//       "yanked": { "1.0.0": { "replacement": "1.0.2", "reason": "…", "date": "2026-10-20" } },
+//       "components": { "<名前>": { "default": "1.0.0", "versions": ["1.0.0"], "sha256": { "1.0.0": "<index.js の同一性の sha256>" },
+//                                   "crlfSha256": { "1.0.0": "<改行を CRLF にした index.js の sha256>" },
+//                                   "content": { "1.0.0": "<フォルダ全体の sha256>" } } } }
+//     yanked は部品庫が取り下げた版（format spec §6：版は手に入るまま、manifest.json の yanked が取り下げと置き換え先の版を示す）。取り込むたびに manifest の
+//     yanked を足す（消さない）。編集アプリは、取り下げた版を記録した教材に組み直しを勧めるが、黙って置き換えない
+//     sha256 は改行をそろえた同一性の hash（format spec §6、kit/core/identity-hash.mjs）。crlfSha256 は、改行をそろえる前に Windows の checkout で
+//     書き出した文書（CRLF のまま hash した）を同じ版に結ぶためだけに使う
+// 組み立て（build-core）・持ち運べる 1 ファイル（portable）・編集アプリが共有する。node: の読み込み・fs・process を使わない（読み書きは env を通す）。
+// 文書が記録した部品（format spec §6：{name, version, sha256}。sha256 は index.js だけ）は、sha256 の合う版に結ぶ（versionForSha）。
+export const LOCK_FILE = 'components.lock.json';
+export const VENDOR_COMPONENTS = ['vendor', 'components'];
+// 部品の名前（format spec §6 の registry の名前）と版（パスの 1 つの部分になるので、字を限る）
+export const NAME_RE = /^[a-z][a-z0-9-]{0,63}$/;
+export const VERSION_RE = /^\d{1,6}\.\d{1,6}\.\d{1,6}(?:-[0-9a-z][0-9a-z.-]{0,31})?$/;
+const SHA_RE = /^[0-9a-f]{64}$/;
+const isObj = (x) => x !== null && typeof x === 'object' && !Array.isArray(x);
+const own = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+
+// catalogue: "2" の項目は 2.0 だけのパーツ（1.x の目録には出さず、1.x リリース単位の yanked も当てない）。
+// 固定のファイルの中身を確かめる。返すもの：問題の配列（空なら正しい）
+export function lockProblems(lock) {
+  const e = [];
+  if (!isObj(lock)) return ['not an object'];
+  if (!isObj(lock.components)) return ['components: not an object'];
+  if (own(lock, 'yanked')) e.push(...yankedProblems(lock.yanked));
+  if (isObj(lock.yanked)) for (const [name, c] of Object.entries(lock.components)) if (isObj(c) && c.catalogue !== '2' && typeof c.default === 'string' && own(lock.yanked, c.default)) e.push(`components.${name}.default: "${c.default}" is yanked`);
+  for (const [name, c] of Object.entries(lock.components)) {
+    const w = `components.${name}`;
+    if (!NAME_RE.test(name)) e.push(`${w}: not a registry name`);
+    if (!isObj(c)) { e.push(`${w}: not an object`); continue; }
+    if (!Array.isArray(c.versions) || !c.versions.length) { e.push(`${w}.versions: not a non-empty array`); continue; }
+    for (const v of c.versions) if (typeof v !== 'string' || !VERSION_RE.test(v)) e.push(`${w}.versions: "${v}" is not a version`);
+    if (new Set(c.versions).size !== c.versions.length) e.push(`${w}.versions: duplicates`);
+    if (!c.versions.includes(c.default)) e.push(`${w}.default: "${c.default}" is not in versions`);
+    if (!isObj(c.sha256)) { e.push(`${w}.sha256: not an object`); continue; }
+    for (const v of c.versions) if (!(own(c.sha256, v) && SHA_RE.test(c.sha256[v]))) e.push(`${w}.sha256.${v}: not a sha256`);
+    for (const v of Object.keys(c.sha256)) if (!c.versions.includes(v)) e.push(`${w}.sha256.${v}: not in versions`);
+    if (own(c, 'crlfSha256')) {
+      if (!isObj(c.crlfSha256)) e.push(`${w}.crlfSha256: not an object`);
+      else for (const [v, h] of Object.entries(c.crlfSha256)) if (!c.versions.includes(v) || !SHA_RE.test(h)) e.push(`${w}.crlfSha256.${v}: not a version with a sha256`);
+    }
+    if (own(c, 'content')) {
+      if (!isObj(c.content)) e.push(`${w}.content: not an object`);
+      else {
+        for (const v of c.versions) if (!own(c.content, v) || typeof c.content[v] !== 'string' || !SHA_RE.test(c.content[v])) e.push(`${w}.content.${v}: not a sha256`);
+        for (const v of Object.keys(c.content)) if (!c.versions.includes(v)) e.push(`${w}.content.${v}: not in versions`);
+      }
+    }
+  }
+  return e;
+}
+
+// yanked（{版: {replacement, reason, date}}）の形：置き換え先は、より新しい、取り下げていない版
+export function yankedProblems(y) {
+  if (!isObj(y)) return ['yanked: not an object'];
+  const e = [];
+  for (const [v, x] of Object.entries(y)) {
+    const w = `yanked.${v}`;
+    if (!VERSION_RE.test(v) || v.includes('-')) { e.push(`${w}: not a version`); continue; }
+    if (!isObj(x)) { e.push(`${w}: not an object`); continue; }
+    if (typeof x.replacement !== 'string' || !VERSION_RE.test(x.replacement) || x.replacement.includes('-') || cmpPlain(x.replacement, v) <= 0) e.push(`${w}.replacement: not a later version`);
+    else if (own(y, x.replacement)) e.push(`${w}.replacement: "${x.replacement}" is itself yanked`);
+    if (typeof x.reason !== 'string' || !x.reason || x.reason.length > 500) e.push(`${w}.reason: not a short text`);
+    if (typeof x.date !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(x.date)) e.push(`${w}.date: not YYYY-MM-DD`);
+  }
+  return e;
+}
+const cmpPlain = (a, b) => { const x = a.split('.').map(Number), y = b.split('.').map(Number); for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] - y[i]; return 0; };
+
+// その版が取り下げられていれば {replacement, reason, date}、なければ null
+export function yankedInfo(lock, version) {
+  return lock && isObj(lock.yanked) && own(lock.yanked, version) && isObj(lock.yanked[version]) ? lock.yanked[version] : null;
+}
+
+// 取り下げた版（版を記録した教材が使うもの）に、置き換えの版で組み直したときの変わり方：部品ごとに {name, from, to, sha256Changes}
+// （sha256Changes：index.js の同一性の hash が変わるか。同じなら、組み直しても部品のコードは同じ）
+export function replacementPlan(lock, used) {
+  const out = [];
+  for (const u of used) {
+    const y = yankedInfo(lock, u.version);
+    const c = lock && isObj(lock.components) && own(lock.components, u.name) ? lock.components[u.name] : null;
+    if (!y || !c) continue;
+    const to = c.versions.includes(y.replacement) ? y.replacement : null;
+    out.push({ name: u.name, from: u.version, to, reason: y.reason, date: y.date, sha256Changes: to ? c.sha256[u.version] !== c.sha256[to] : null });
+  }
+  return out;
+}
+
+export function parseLock(text) {
+  let lock;
+  try { lock = JSON.parse(text); } catch (err) { throw new Error(`${LOCK_FILE}: ${err.message}`); }
+  const e = lockProblems(lock);
+  if (e.length) throw new Error(`${LOCK_FILE}: ${e.join('; ')}`);
+  return lock;
+}
+
+// env（build-core の env）から読む。なければ null（部品庫の部品は使えない）
+export function readLock(env, root) {
+  const f = env.path.join(root, LOCK_FILE);
+  if (!env.exists(f)) return null;
+  return parseLock(env.readText(f));
+}
+
+// 部品の写しのフォルダ（<root>/vendor/components）
+export const vendorDir = (P, root) => P.join(root, ...VENDOR_COMPONENTS);
+
+// 唯一の写しの場所の解決口。content はフォルダ全体のバイトの hash（index.js の同一性の hash とは別）。
+// content のない古い固定も読めるので、移行前の写し・道具の試験でも同じ口を使う。
+export function resolveComponent(P, root, lock, name, version) {
+  if (!NAME_RE.test(name) || !VERSION_RE.test(version) || !lock || !isObj(lock.components) || !own(lock.components, name)) return null;
+  const c = lock.components[name];
+  if (!c.versions.includes(version)) return null;
+  if (own(c, 'content')) {
+    const hash = c.content && c.content[version];
+    return typeof hash === 'string' && SHA_RE.test(hash) ? P.join(vendorDir(P, root), 'sha256', hash) : null;
+  }
+  return P.join(vendorDir(P, root), name, version);
+}
+
+// 使う版を決める：want（固定。opts.componentVersions や作業フォルダの設定のファイルの components）が手元にあればそれ、なければ既定の版。
+// 返すもの：{version, note}（note は知らせ。固定した版が手元にないときなど）。部品が固定のファイルにないときは version: null
+export function pickVersion(lock, name, want) {
+  const c = lock && isObj(lock.components) && own(lock.components, name) ? lock.components[name] : null;
+  if (!c) return { version: null, note: null };
+  if (want === undefined || want === null) return { version: c.default, note: null };
+  if (typeof want === 'string' && c.versions.includes(want)) return { version: want, note: null };
+  return { version: c.default, note: `component m-${name}: version "${String(want).slice(0, 40)}" is not in ${LOCK_FILE}; using ${c.default}` };
+}
+
+// 文書が記録した index.js の sha256 に合う版（なければ null）。同じ中身の版が複数あれば、既定の版、次に新しく取り込んだ版。
+// 同一性の hash（sha256）に合わなければ、改行をそろえる前に CRLF のまま hash した記録（crlfSha256）とも比べる
+// prefer：文書が記録した版。手元にあって hash が合えば、それを選ぶ（同じ中身の新しい版に黙って移らない。format spec §3.3）
+export function versionForSha(lock, name, sha, prefer) {
+  const c = lock && isObj(lock.components) && own(lock.components, name) ? lock.components[name] : null;
+  if (!c || typeof sha !== 'string') return null;
+  for (const key of ['sha256', 'crlfSha256']) {
+    const m = isObj(c[key]) ? c[key] : {};
+    if (typeof prefer === 'string' && c.versions.includes(prefer) && m[prefer] === sha) return prefer;
+    if (m[c.default] === sha) return c.default;
+    for (const v of [...c.versions].reverse()) if (m[v] === sha) return v;
+  }
+  return null;
+}
+
+// 文書の索引の部品（index.components）から、組み直しで使う版の固定を作る：{名前: 版}。既定の版と同じものも入れる。
+// 合う版がない部品は missing に（段 B・C の編集はできない。format spec §6）
+export function pinsForIndex(lock, components) {
+  const pins = {}, missing = [];
+  for (const c of Array.isArray(components) ? components : []) {
+    if (!isObj(c) || c.source !== 'registry' || typeof c.name !== 'string' || !NAME_RE.test(c.name)) continue;
+    const v = versionForSha(lock, c.name, c.sha256, c.version);
+    if (v) pins[c.name] = v; else missing.push(c);
+  }
+  return { pins, missing };
+}
+
+// 作業フォルダの設定のファイル（FORMAT.CONFIG_FILE）の components：{名前: 版}。形が違うものは捨てる
+export function configPins(conf) {
+  if (!isObj(conf) || !isObj(conf.components)) return {};
+  const out = {};
+  for (const [k, v] of Object.entries(conf.components)) if (NAME_RE.test(k) && typeof v === 'string' && VERSION_RE.test(v)) out[k] = v;
+  return out;
+}

package/kit/core/config-file.mjs

@@ -0,0 +1,140 @@
+// 設定のファイル（FORMAT.CONFIG_FILE = egatari.json）を書き換える、ただ 1 つの道（format spec §3.3）。
+// 仕様：ほかの作り手（producer）は自分の状態を自分の名前の項目 1 つに置いてよく、ほかの作り手と編集器はその項目を変えずに残し、意味を与えない。
+// Studio が書くのは自分の項目（docId・metadata・attachments・components・themes・extensions）だけで、ほかの項目は読み直して書き直さない：
+// 元の文字列のうち、変える項目の値だけを差し替える（ほかの項目はバイトのまま。項目の順も、空白も、数の書き方も変わらない。
+// JSON.parse → JSON.stringify では大きな整数や 1e400 が変わり、"10" のような名前の項目が先頭に移る）。
+//   updateConfig(oldText, patch)  新しい文字列。oldText：今のファイルの文字列（ないときは null・undefined）。
+//                                 patch：{名前: 値}。値が undefined なら項目を消す。merge({…}) なら今の object の中を同じ規則で書き換える
+//                                 （ないか object でなければ、その object にする）。ほかの値は置き換える（同じ値なら元のバイトのまま）。
+//                                 今のファイルが JSON の object として読めなければ code 'bad-config' で断る（読めないものを上書きして消さない）
+//   merge(obj)                    patch の値：object の中の項目だけを変える
+//   configObject(text)            JSON の object として読む（読めなければ code 'bad-config'）。ないときは {}
+// node: の読み込み・fs を使わない（編集アプリ・Worker・Node で同じもの）
+
+class Merge { constructor(o) { this.o = o; } }
+export const merge = (o) => new Merge(o);
+
+const badConfig = (msg) => Object.assign(new Error(`egatari.json: ${msg}`), { code: 'bad-config' });
+const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+export function configObject(text) {
+  if (text === null || text === undefined || text === '') return {};
+  let v;
+  try { v = JSON.parse(text); } catch (e) { throw badConfig(`not JSON (${e.message})`); }
+  if (!isObj(v)) throw badConfig('not a JSON object');
+  return v;
+}
+
+// merge を外した値（新しく書くとき）。undefined の項目は書かない
+function plain(v) {
+  if (v instanceof Merge) v = v.o;
+  if (!isObj(v)) return v;
+  const out = {};
+  for (const [k, x] of Object.entries(v)) if (x !== undefined) out[k] = plain(x);
+  return out;
+}
+
+// 元の文字列の構造：object の項目の場所（名前の始まり・値の始まりと終わり）。値の中身は JSON.parse で確かめた後なので、ここでは区切りだけ見る
+function scanner(text) {
+  let i = 0;
+  const ws = () => { while (i < text.length && ' \t\n\r'.includes(text[i])) i++; };
+  const str = () => { i++; while (text[i] !== '"') i += text[i] === '\\' ? 2 : 1; i++; };
+  function value() {
+    ws();
+    const start = i, c = text[i];
+    if (c === '{') return object();
+    if (c === '[') {
+      i++; ws();
+      if (text[i] === ']') { i++; return { kind: 'array', start, end: i }; }
+      for (;;) { value(); ws(); if (text[i] === ',') { i++; continue; } i++; return { kind: 'array', start, end: i }; }
+    }
+    if (c === '"') { str(); return { kind: 'string', start, end: i }; }
+    while (i < text.length && !',]} \t\n\r'.includes(text[i])) i++;
+    return { kind: 'scalar', start, end: i };
+  }
+  function object() {
+    const start = i, members = [];
+    i++; ws();
+    if (text[i] === '}') { i++; return { kind: 'object', start, end: i, members }; }
+    for (;;) {
+      ws();
+      const keyStart = i; str();
+      const key = JSON.parse(text.slice(keyStart, i));
+      ws(); i++;   // :
+      const v = value();
+      members.push({ key, keyStart, value: v });
+      ws();
+      if (text[i] === ',') { i++; continue; }
+      i++;
+      return { kind: 'object', start, end: i, members };
+    }
+  }
+  return value;
+}
+
+// pos のある行の頭の空白
+function lineIndent(text, pos) {
+  const ls = text.lastIndexOf('\n', pos - 1) + 1;
+  const m = /^[ \t]*/.exec(text.slice(ls, pos));
+  return m ? m[0] : '';
+}
+
+// 新しい値の文字列。pretty なら 2 字下げで、続く行を ind だけ下げる。そうでなければ 1 行
+const render = (v, ind) => (ind === null ? JSON.stringify(plain(v)) : JSON.stringify(plain(v), null, 2).replace(/\n/g, '\n' + ind));
+
+// object（node）に patch を当てる編集 [{start, end, text}] を edits に足す
+function patchObject(text, node, patch, edits) {
+  const ms = node.members;
+  const first = ms[0];
+  const pretty = !first || /\n[ \t]*$/.test(text.slice(node.start + 1, first.keyStart));
+  const objInd = lineIndent(text, node.start);
+  const memInd = first && pretty ? lineIndent(text, first.keyStart) : objInd + '  ';
+  const valInd = pretty ? memInd : null;
+  const byKey = new Map(ms.map((m, i) => [m.key, i]));
+  const del = new Set(), adds = [];
+  for (const [k, v] of Object.entries(patch)) {
+    const i = byKey.has(k) ? byKey.get(k) : -1;
+    if (v === undefined) { if (i >= 0) del.add(i); continue; }
+    if (i < 0) { if (!(v instanceof Merge && v.o === undefined)) adds.push(`${JSON.stringify(k)}: ${render(v, valInd)}`); continue; }
+    const m = ms[i], raw = text.slice(m.value.start, m.value.end);
+    if (v instanceof Merge && m.value.kind === 'object') { patchObject(text, m.value, v.o, edits); continue; }
+    if (!(v instanceof Merge) && JSON.stringify(JSON.parse(raw)) === JSON.stringify(v)) continue;   // 同じ値：元のバイトのまま
+    edits.push({ start: m.value.start, end: m.value.end, text: render(v, valInd) });
+  }
+  if (!del.size && !adds.length) return;
+  const keep = ms.map((_, i) => i).filter((i) => !del.has(i));
+  if (!keep.length) {
+    // 項目が 1 つも残らない：object を作り直す（中の値の編集はない：消す項目の中は触らない）
+    for (let e = edits.length - 1; e >= 0; e--) if (edits[e].start >= node.start && edits[e].end <= node.end) edits.splice(e, 1);
+    edits.push({ start: node.start, end: node.end, text: adds.length ? (pretty ? `{\n${adds.map((a) => memInd + a).join(',\n')}\n${objInd}}` : `{${adds.join(', ')}}`) : '{}' });
+    return;
+  }
+  // 消す：後ろに項目が残るものは次の項目の名前の前まで、最後から続けて消すものは残る最後の項目の値の後ろから
+  const lastKeep = keep[keep.length - 1];
+  for (const i of del) {
+    if (i < lastKeep) edits.push({ start: ms[i].keyStart, end: ms[i + 1].keyStart, text: '' });
+  }
+  if (lastKeep < ms.length - 1) edits.push({ start: ms[lastKeep].value.end, end: ms[ms.length - 1].value.end, text: '' });
+  // 足す：残る最後の項目の後ろに、同じ書き方で
+  if (adds.length) edits.push({ start: ms[lastKeep].value.end, end: ms[lastKeep].value.end, text: adds.map((a) => (pretty ? `,\n${memInd}${a}` : `, ${a}`)).join('') });
+}
+
+export function updateConfig(oldText, patch) {
+  if (oldText === null || oldText === undefined || oldText === '') return JSON.stringify(plain(patch), null, 2) + '\n';
+  configObject(oldText);   // 読めないものは断る
+  const root = scanner(oldText)();
+  const edits = [];
+  patchObject(oldText, root, patch, edits);
+  if (!edits.length) return oldText;
+  // 同じ場所では、足す（長さ 0）を先に
+  edits.sort((a, b) => a.start - b.start || (a.end - a.start) - (b.end - b.start));
+  let out = '', at = 0;
+  for (const e of edits) { out += oldText.slice(at, e.start) + e.text; at = Math.max(at, e.end); }
+  return out + oldText.slice(at);
+}
+
+// 新しい教材のカタログ（設定のファイルの componentsCatalogue。"2" は components2.lock.json の既定の 2.x のカタログ。kit/core/parts2.mjs の pickCatalogue）。
+// 新規作成（編集アプリの「新規作成…」・npx egatari new・make スキルの作業フォルダ）は、AI への指示（既定の 2.x のカタログの manifest から作る）と同じ 2.x で組む。
+// componentsCatalogue のない今までの教材は 1.x のまま（黙って変えない）
+export const NEW_LESSON_CATALOGUE = '2';
+export const withNewLessonCatalogue = (configText) => updateConfig(configText || null, { componentsCatalogue: NEW_LESSON_CATALOGUE });

package/kit/core/error-text.mjs

@@ -0,0 +1,26 @@
+// コンソールのエラー・例外の言葉を、品質チェックの知らせと AI への修正依頼に載せる形にする。Node にもブラウザにも依存しない（純粋な ESM）
+//   cleanErrorText(text) → 1 行の言葉：スタックの行（"    at …"）を除き、ファイルの場所（file://…、一時フォルダ、手元のサーバーの
+//     http(s)://localhost:… など）をファイルの名前だけにし、行と桁（:2582:20）を除く。中身の言葉は残す
+//   componentError(text) → {tag, msg} | null：実行系の古い形の部品の例外（"M-CURVES TypeError: S.map is not a function"）
+const STACK = /^\s*at\s|^\s*\(eval at |^\s*@|^\s*[\w$.<>]*@(?:file|https?|blob):/;
+const LOCAL = /\bhttps?:\/\/(?:localhost|127\.\d+\.\d+\.\d+|\[::1\]|0\.0\.0\.0)(?::\d+)?/gi;
+const FILE_URL = /\bfile:\/\/\/?[^\s)'"]*/gi;
+const TEMP = /(?:\/private)?\/(?:var\/folders|tmp|temp)\/[^\s)'"]*|[A-Za-z]:\\[^\s)'"]*\\(?:Temp|tmp)\\[^\s)'"]*/gi;
+const base = (p) => String(p).replace(/[?#].*$/, '').replace(/:\d+(?::\d+)?$/, '').split(/[\\/]/).filter(Boolean).pop() || '';
+
+export function cleanErrorText(text) {
+  const lines = String(text ?? '').replace(/\r\n?/g, '\n').split('\n');
+  const keep = lines.filter((ln) => ln.trim() && !STACK.test(ln));
+  let s = (keep.length ? keep : lines.slice(0, 1)).join(' ').replace(/\s+/g, ' ').trim();
+  s = s.replace(FILE_URL, (u) => base(u.replace(/^file:\/+/, '/')))
+    .replace(TEMP, (p) => base(p))
+    .replace(new RegExp(LOCAL.source + '(/[^\\s)\'"]*)?', 'gi'), (_, p) => (p ? base(p) : ''))
+    .replace(/\b([\w.-]+\.(?:html|js|mjs))(?::\d+){1,2}\b/g, '$1')
+    .replace(/\(\s*\)/g, '').replace(/\s+/g, ' ').trim();
+  return s;
+}
+
+export function componentError(text) {
+  const m = cleanErrorText(text).match(/^(?:\[[^\]]*\]\s*)?(M-[A-Z0-9-]+)\s+((?:Type|Range|Reference|Syntax)?Error:?\s.*)$/);
+  return m ? { tag: m[1].toLowerCase(), msg: m[2] } : null;
+}

package/kit/core/export-name.mjs

@@ -0,0 +1,44 @@
+// 書き出すファイルの既定の名前：教材の題名から（同じ deck.ega.html がたまって取り違えないように）。Node にもブラウザにも依存しない
+//   titleOf(html)                  <title> の文字（タグを除き、文字参照を戻す）。なければ ''
+//   exportName(title, fallback, ext) → 題名から作った名前 + ext。題名が使えなければ fallback（デッキの名前。拡張子なし）+ ext
+// どの OS でも使える名前にする：Windows の使えない字（\ / : * ? " < > |）と制御文字を除き、空白をまとめ、
+// 頭の点（隠しファイル）と終わりの点・空白（Windows が落とす）を除き、予約の名前（CON・NUL・COM1 など）は避け、
+// 拡張子を入れて 255 バイト（多くのファイルシステムの上限）に収まるよう、字の途中で切らずに短くする（字は NFC にそろえる）
+const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ' };
+function decode(s) {
+  return s.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (m, e) => {
+    if (e[0] === '#') {
+      const n = e[1] === 'x' || e[1] === 'X' ? parseInt(e.slice(2), 16) : parseInt(e.slice(1), 10);
+      return n > 0 && n <= 0x10FFFF && !(n >= 0xD800 && n <= 0xDFFF) ? String.fromCodePoint(n) : ' ';
+    }
+    return ENTITIES[e.toLowerCase()] ?? ' ';
+  });
+}
+export function titleOf(html) {
+  const t = String(html || '').match(/<title[^>]*>([\s\S]*?)<\/title>/i)?.[1] || '';
+  return decode(t.replace(/<[^>]*>/g, '')).replace(/\s+/g, ' ').trim();
+}
+const RESERVED = /^(con|prn|aux|nul|com[0-9¹²³]|lpt[0-9¹²³])(\..*)?$/i;
+const MAX_CHARS = 80, MAX_BYTES = 255;
+const utf8Bytes = (s) => new TextEncoder().encode(s).length;
+function clean(s) {
+  let x = String(s || '').normalize('NFC')
+    .replace(/[\\/:*?"<>|\u0000-\u001f\u007f-\u009f\u200b-\u200f\u2028-\u202e\u2060-\u2064\ufeff]/g, ' ')
+    .replace(/\s+/g, ' ').trim()
+    .replace(/^[.\s]+/, '');
+  return x;
+}
+function fit(name, ext) {
+  let cps = [...name].slice(0, MAX_CHARS);
+  while (cps.length && utf8Bytes(cps.join('') + ext) > MAX_BYTES) cps.pop();
+  return cps.join('').replace(/[.\s]+$/, '');
+}
+export function exportName(title, fallback, ext) {
+  const e = String(ext || '');
+  for (const cand of [title, fallback, 'lesson']) {
+    const n = fit(clean(cand), e);
+    if (n && !RESERVED.test(n)) return n + e;
+    if (n) return n + '_' + e;          // CON → CON_.ega.html
+  }
+  return 'lesson' + e;
+}

package/kit/core/favicon.mjs

@@ -0,0 +1,33 @@
+// 組んだデッキのタブのアイコン（backlog #59）。assets/logo/egatari-32-{light,dark}.svg（32 px 用の見た目を整えた版。MIT の対象外：NOTICE）の
+// 形と色をそのまま 1 つの SVG にし、暗い画面の色は SVG の中の prefers-color-scheme で替える。data: URI の <link rel="icon"> として <head> に入れる
+// （ファイルが 1 つで足り、CSP の img-src data: で通る）。形・色が assets/logo と同じことは tools/test-favicon.mjs が確かめる
+// 同じ 1 つの SVG にした理由：<link media="(prefers-color-scheme: dark)"> を 2 つ並べる方式は、media を見ないブラウザ（Safari など）が
+// 先の 1 つ（明るい版）だけを使い、暗いタブで読めないことがあるため。SVG の中の問い合わせなら、SVG のアイコンを使うブラウザは暗い画面の色まで見る
+export const FAVICON = Object.freeze({
+  bracket: 'M10 5H5V18.5 M22 27H27V13.5',
+  e: 'M10 13.5Q15.125 13 19.875 11.875Q21.125 11.625 20.25 12.875L9.75 23.25L13.75 19Q16 16.625 16.875 19.875L17.375 22Q18.25 24.5 20.75 23Q22.625 21.875 22 20.25',
+  sun: { cx: 14, cy: 8.25, r: 1.75 },
+  light: { ink: '#4A488E', sun: '#D3381C' },
+  dark: { ink: '#A9ABFA', sun: '#F2573B' },
+});
+
+export function faviconSvg() {
+  const F = FAVICON;
+  return '<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 32 32">'
+    + `<style>.i{stroke:${F.light.ink}}.s{fill:${F.light.sun}}@media (prefers-color-scheme:dark){.i{stroke:${F.dark.ink}}.s{fill:${F.dark.sun}}}</style>`
+    + `<path class="i" d="${F.bracket}" fill="none" stroke-width="2" stroke-linecap="square" stroke-linejoin="miter"/>`
+    + `<circle class="s" cx="${F.sun.cx}" cy="${F.sun.cy}" r="${F.sun.r}"/>`
+    + `<path class="i" d="${F.e}" fill="none" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/></svg>`;
+}
+
+// <link rel="icon"> 1 本（SVG は % 符号化。base64 にしない：HTML の中で読め、数百バイトで済む）
+export function faviconLink() {
+  const uri = 'data:image/svg+xml,' + encodeURIComponent(faviconSvg()).replace(/'/g, '%27');
+  return `<link rel="icon" type="image/svg+xml" href="${uri}" data-egatari-favicon>`;
+}
+
+// 入れるか：<html data-favicon="off"|false|no|0> なら入れない（data-feedback と同じ書き方）。原稿が自分の <link rel="icon">（shortcut icon も）を持てばそちらを使う
+export function wantsFavicon(htmlAttr, hasOwnIcon) {
+  if (/^(off|false|no|0)$/i.test((htmlAttr || '').trim())) return false;
+  return !hasOwnIcon;
+}

package/kit/core/file-policy.mjs

@@ -0,0 +1,165 @@
+// ファイルの決まり（format spec §4.2 の file policy）：1 ファイル（.ega.html）が持つ Content-Security-Policy の <meta>。
+// Node にもブラウザにも依存しない（node: の読み込みなし）。書き出し（kit/core/portable.mjs）・授業の部屋の派生（kit/core/live.mjs）・読み手の検査が使う
+//
+//   BASELINE                        基準の決まり（ディレクティブ → 源の配列）。外へは繋がらない（connect-src 'none'）
+//   policyText(extra)               extra {connect: [源…], frame: [源…]}（宣言した拡張が足す行き先）を基準に足した文字列
+//   policyMeta(text)                <meta http-equiv="Content-Security-Policy" content="…">
+//   extensionSources(extensions)    deck-extensions（実行系が宣言する拡張。いくつあってもよく、それぞれ自分のディレクティブだけに足す）から、決まりに足す行き先 {connect, frame}：
+//                                   live は endpoint の両方の形（https:/wss:）を connect-src に、embed は一覧の行き先（§3 の許す一覧にあるもの）を frame-src に
+//   parsePolicy(text)               → {directives: Map(名前 → 源の配列), duplicates: [名前]}（名前は小文字、源は比べる形にそろえる）
+//   policyDiff(actual, expected)    解析したディレクティブと源の集まりで比べる（順と空白は問わない）→ 違いの文字列の配列（[] なら同じ）
+//   findPolicies(html)              文書の中の決まりの <meta>（http-equiv が Content-Security-Policy のもの）：[{content, start, end}]
+//   placementProblems(html)         §4.2 の置き場所：ちょうど 1 つ。前に来てよいのは doctype・<html>・<head>・<meta charset> だけ（どれも on* なし）。
+//                                   どの <script>・<style>・<link>・URL の属性（src href srcset poster data）・on* の属性よりも前
+//   checkFilePolicy(html, extensions?) 置き場所と中身（基準と宣言した拡張だけ）→ 問題の文字列の配列（[] なら合う）。extensions を渡さなければ、
+//                                   文書の実行系が宣言するもの（<script type="application/json" id="deck-extensions">。再生器が読むもの）
+import { parse } from 'parse5';
+import { LivePolicy } from './live-policy.mjs';
+import { SCRIPTING } from './code-scan.mjs';
+
+// 行き先を求めるだけ（つながるかは再生器が決める）：開発用のループバックの http: の部屋も、その endpoint だけを足したものとして比べる
+const LP = LivePolicy({ allowLoopback: true });
+const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+export const BASELINE = Object.freeze([
+  ['default-src', ["'none'"]], ['script-src', ["'unsafe-inline'"]], ['style-src', ["'unsafe-inline'"]], ['img-src', ['data:', 'blob:']],
+  ['font-src', ['data:']], ['media-src', ['data:', 'blob:']], ['connect-src', ["'none'"]], ['frame-src', ["'self'", 'file:']],
+  ['worker-src', ["'none'"]], ['object-src', ["'none'"]], ['manifest-src', ["'none'"]], ['base-uri', ["'none'"]], ['form-action', ["'none'"]],
+]);
+// 拡張 embed（format spec の extensions/embed.md §3）の許す行き先（v1）。frame-src にはこの形のまま足す
+export const EMBED_DESTINATIONS = Object.freeze(['https://www.youtube-nocookie.com', 'https://player.vimeo.com', 'https://www.google.com/maps/embed', 'https://www.openstreetmap.org/export/embed.html']);
+
+const uniq = (a) => [...new Set(a)];
+export function policyText(extra = {}) {
+  const connect = uniq(extra.connect || []), frame = uniq(extra.frame || []);
+  return BASELINE.map(([d, src]) => {
+    let s = src;
+    if (d === 'connect-src' && connect.length) s = connect;            // 'none' は源があれば外す（'none' と源は並べられない）
+    if (d === 'frame-src' && frame.length) s = [...src, ...frame];
+    return `${d} ${s.join(' ')}`;
+  }).join('; ');
+}
+const escAttr = (s) => String(s).replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
+export const policyMeta = (text) => `<meta http-equiv="Content-Security-Policy" content="${escAttr(text)}">`;
+
+// embed の項目の src が許す行き先か（origin が同じで、パスの前置があればそれで始まる）→ 足す行き先（一覧の形）か null
+function embedDestination(src) {
+  let u;
+  try { u = new URL(String(src)); } catch { return null; }
+  if (u.protocol !== 'https:' || u.username || u.password) return null;
+  for (const d of EMBED_DESTINATIONS) {
+    const x = new URL(d);
+    if (u.origin !== x.origin) continue;
+    if (x.pathname === '/' || u.pathname === x.pathname || u.pathname.startsWith(x.pathname.replace(/\/?$/, '/')) || u.pathname.startsWith(x.pathname + '?')) return d;
+  }
+  return null;
+}
+export function extensionSources(extensions) {
+  const out = { connect: [], frame: [] };
+  if (!isObj(extensions)) return out;
+  const live = extensions.live;
+  if (isObj(live) && live.v === 1 && typeof live.endpoint === 'string') {
+    const cs = LP.connectSrc(live.endpoint);
+    if (cs) out.connect.push(...cs.split(' '));
+  }
+  const embed = extensions.embed;
+  if (isObj(embed) && embed.v === 1 && isObj(embed.items)) {
+    for (const k of Object.keys(embed.items).sort()) {
+      const it = embed.items[k], d = isObj(it) ? embedDestination(it.src) : null;
+      if (d) out.frame.push(d);
+    }
+  }
+  out.connect = uniq(out.connect); out.frame = uniq(out.frame).sort();
+  return out;
+}
+
+// 源をそろえる：キーワード（'none' など）・scheme（data:）・ホストは小文字、パスはそのまま
+function normSource(s) {
+  if (s.startsWith("'")) return s.toLowerCase();
+  if (/^[a-z][a-z0-9+.-]*:$/i.test(s)) return s.toLowerCase();
+  const m = /^([a-z][a-z0-9+.-]*:\/\/)?([^/]*)(.*)$/i.exec(s);
+  return m ? (m[1] || '').toLowerCase() + m[2].toLowerCase() + m[3] : s;
+}
+export function parsePolicy(text) {
+  const directives = new Map(), duplicates = [];
+  for (const part of String(text).split(';')) {
+    const toks = part.trim().split(/[\t\n\f\r ]+/).filter(Boolean);
+    if (!toks.length) continue;
+    const name = toks[0].toLowerCase();
+    // 同じ名前の 2 つ目以降はブラウザが無視する（CSP3 §2.2.1）：違いとして知らせる
+    if (directives.has(name)) { duplicates.push(name); continue; }
+    directives.set(name, uniq(toks.slice(1).map(normSource)).sort());
+  }
+  return { directives, duplicates };
+}
+export function policyDiff(actual, expected) {
+  const a = parsePolicy(actual), e = parsePolicy(expected), out = [];
+  for (const d of a.duplicates) out.push(`directive "${d}" appears more than once`);
+  for (const [d, src] of e.directives) {
+    if (!a.directives.has(d)) { out.push(`missing directive "${d}"`); continue; }
+    const have = new Set(a.directives.get(d)), want = new Set(src);
+    for (const s of have) if (!want.has(s)) out.push(`${d}: extra source ${s}`);
+    for (const s of want) if (!have.has(s)) out.push(`${d}: missing source ${s}`);
+  }
+  for (const d of a.directives.keys()) if (!e.directives.has(d)) out.push(`extra directive "${d}"`);
+  return out;
+}
+
+const URL_ATTRS = new Set(['src', 'href', 'srcset', 'poster', 'data']);
+const isPolicyMeta = (n) => n.tagName === 'meta' && (n.attrs || []).some((a) => a.name === 'http-equiv' && a.value.trim().toLowerCase() === 'content-security-policy');
+function walk(n, fn) {
+  fn(n);
+  for (const c of n.childNodes || []) walk(c, fn);
+  if (n.content) walk(n.content, fn);
+}
+function parsed(html) { return parse(String(html), { sourceCodeLocationInfo: true, scriptingEnabled: SCRIPTING }); }
+export function findPolicies(html, doc = parsed(html)) {
+  const out = [];
+  walk(doc, (n) => {
+    if (!n.tagName || !isPolicyMeta(n)) return;
+    const c = (n.attrs || []).find((a) => a.name === 'content');
+    out.push({ content: c ? c.value : '', start: n.sourceCodeLocation ? n.sourceCodeLocation.startOffset : -1, end: n.sourceCodeLocation ? n.sourceCodeLocation.endOffset : -1, inHead: n.parentNode && n.parentNode.tagName === 'head' });
+  });
+  return out;
+}
+export function placementProblems(html, doc = parsed(html)) {
+  const pol = findPolicies(html, doc);
+  if (!pol.length) return ['no Content-Security-Policy <meta> (the file policy, §4.2)'];
+  const out = [];
+  if (pol.length > 1) out.push(`${pol.length} Content-Security-Policy <meta> elements (the file carries exactly one, §4.2)`);
+  const at = pol[0].start;
+  if (!pol[0].inHead) out.push('the Content-Security-Policy <meta> is not in <head>');
+  walk(doc, (n) => {
+    if (!n.tagName || !n.sourceCodeLocation) return;
+    const start = n.sourceCodeLocation.startOffset;
+    const attrs = n.attrs || [];
+    const onAttr = attrs.find((a) => /^on/i.test(a.name));
+    if (start >= at) {
+      // 前に来る要素（<html>・<head>）の開始タグに付いた on* も前にある
+      return;
+    }
+    const charsetMeta = n.tagName === 'meta' && attrs.some((a) => a.name === 'charset') && !isPolicyMeta(n);
+    if (!['html', 'head'].includes(n.tagName) && !charsetMeta) out.push(`<${n.tagName}> comes before the Content-Security-Policy <meta>`);
+    if (onAttr) out.push(`<${n.tagName} ${onAttr.name}> (an event handler) comes before the Content-Security-Policy <meta>`);
+    const u = attrs.find((a) => URL_ATTRS.has(a.name));
+    if (u) out.push(`<${n.tagName} ${u.name}> (a URL attribute) comes before the Content-Security-Policy <meta>`);
+  });
+  return out;
+}
+function deckExtensions(doc) {
+  let out = null;
+  walk(doc, (n) => {
+    if (out !== null || n.tagName !== 'script' || !(n.attrs || []).some((a) => a.name === 'id' && a.value === 'deck-extensions')) return;
+    const t = (n.childNodes || []).filter((c) => c.nodeName === '#text').map((c) => c.value).join('');
+    try { out = JSON.parse(t); } catch { out = {}; }
+  });
+  return isObj(out) ? out : {};
+}
+export function checkFilePolicy(html, extensions) {
+  const doc = parsed(html);
+  if (extensions === undefined) extensions = deckExtensions(doc);
+  const out = placementProblems(html, doc);
+  const pol = findPolicies(html, doc);
+  if (pol.length) for (const d of policyDiff(pol[0].content, policyText(extensionSources(extensions)))) out.push(`file policy differs from the baseline and the declared extensions: ${d}`);
+  return out;
+}

package/kit/core/format.mjs

@@ -0,0 +1,38 @@
+// 持ち運べるデッキの形式（format spec：FORMAT.SPEC_URL）の名前と、名前から作る識別子のすべて。
+// 形式の名前が変わったら、このファイルだけを直し、仕様の写しを同期し直す（node tools/sync-spec.mjs <仕様の clone>）。
+// ほかのファイルには形式の名前を書かない（ここから読み込む。kit/deck.js には build が DECK.FORMAT として埋め込む）
+const NAME = 'egatari';
+
+export const FORMAT = Object.freeze({
+  NAME,
+  DISPLAY_NAME: 'Egatari',                            // 人に見せる名前
+  FORMAT_ID: NAME,                                    // index.format と deck-meta.format
+  INDEX_ID: `${NAME}-index`,                          // 索引の <script id>
+  BLOB_PREFIX: `${NAME}-b-`,                          // 塊の <script id> の前置（<prefix><blobId>-<n>）
+  READABLE_ID: `${NAME}-readable`,                    // スクリプトなしで読める層の id
+  SIGNATURES_ID: `${NAME}-signatures`,                // 署名のブロック（予約。まだ作らない）
+  FONT_SUPPLEMENT_PREFIX: `${NAME}-font-supplement-`, // 段 A の編集で足す字の <style id>（<prefix><n>。kit/core/tier-a.mjs）
+  MESSAGE_KEY: NAME,                                  // 埋め込みの postMessage の鍵（{<key>: "seek", …}。後の段階）
+  MIME: `application/vnd.${NAME}+json`,               // 索引の type
+  URI_SCHEME: `${NAME}:`,                             // deck-audio の src（<scheme><blobId>）
+  FILE_EXT: '.ega.html',                              // 書き出すファイルの拡張子
+  PLAY_EXT: '.play.ega.html',                         // 再生専用の派生の拡張子
+  CONFIG_FILE: `${NAME}.json`,                        // 作業フォルダに残す docId と metadata（と添付の一覧 ATTACH_KEY）
+  // 添付（§3.8）：読み手のためのファイル（元の原稿・PDF・コード・データ・補足）。組み立てには使わず、再生器はダウンロードだけ（実行しない）
+  ATTACH_DIR: 'attachments',                          // 置き場所（archive path は 'attachments/…'）
+  ATTACH_KEY: 'attachments',                          // index.attachments（[{path, role, title?}]）。作業フォルダでは CONFIG_FILE の同じ名前の項目
+  ATTACH_ROLES: Object.freeze(['source', 'pdf', 'code', 'data', 'supplement']),
+  SCHEMA_PREFIX: `${NAME}-`,                          // 仕様の Schema のファイル名の前置（<prefix>index.schema.json など）
+  SCHEMA_BASE: 'https://egatari.org/schema/',         // Schema の $id の前置（試験は写しを $id で引く。ネットワークは使わない）
+  SPEC_URL: 'https://github.com/egatari/egatari-spec',
+  VENDOR_DIR: `vendor/${NAME}-spec`,                  // 仕様の Schema と試験用の入力の写し（リポジトリの根から）
+  // 授業の部屋（拡張 live。仕様の extensions/live.md）：既定の部屋のサービス・通信の約束（egatari/live の protocol/）の写し・再生器の記憶の鍵の前置
+  LIVE_ENDPOINT: `https://live.${NAME}.org`,
+  LIVE_REPO: `https://github.com/${NAME}/live`,
+  LIVE_VENDOR_DIR: `vendor/${NAME}-live-protocol`,
+  LIVE_SETUP_PREFIX: `${NAME}-live-setup-v1:`,        // エディタからの一方向の設定の文字列の前置（egatari/live の PROTOCOL.md §2.1）
+  LIVE_STORE_PREFIX: `${NAME}-live-`,                 // 再生器の localStorage（pid）と sessionStorage（参加した）の鍵の前置（<prefix>pid:<room> など）
+});
+// 実行系（kit/deck.js）に渡す分（build-core が DECK.FORMAT として埋め込む）
+export const RUNTIME_FORMAT = Object.freeze({ id: FORMAT.FORMAT_ID, displayName: FORMAT.DISPLAY_NAME, blobPrefix: FORMAT.BLOB_PREFIX, uriScheme: FORMAT.URI_SCHEME, readableId: FORMAT.READABLE_ID,
+  indexId: FORMAT.INDEX_ID, attachKey: FORMAT.ATTACH_KEY, attachDir: FORMAT.ATTACH_DIR, attachRoles: FORMAT.ATTACH_ROLES });