@geniee-inc/sfa-kit 1.16.0 → 1.18.0

package/src/lib/auth/useEmbedSession.js

@@ -21,12 +21,23 @@ const CODE_TIMEOUT_SECONDS = 15;
 /** Consecutive failed attempts to obtain a usable session before giving up. */
 const MAX_RECOVERY_ATTEMPTS = 4;
 /**
- * A 401 landing within this window of the previous one belongs to the same
- * recovery run. Without it, a token Keystone happily mints but the API keeps
- * rejecting loops forever, because every exchange succeeds and resets counters.
+ * A rejection landing within this window of the run's start belongs to the
+ * same recovery run. Without it, a token Keystone happily mints but the API
+ * keeps rejecting loops forever, because every exchange succeeds and resets
+ * the retry counters.
+ *
+ * NOTE: only rejections of the token currently held are counted — a reply
+ * about a token already replaced is dropped before it gets here. The window
+ * therefore bounds a genuine loop, and no longer trips on the stragglers of a
+ * session that is recovering perfectly well.
+ *
+ * NOTE: a backstop for a fast loop, not a precise detector. Separating a loop
+ * from an endpoint answering 401 where it means 403 needs to know whether any
+ * request *succeeded* with the replacement token, which nothing reports — the
+ * client only calls back on failure.
  */
 const AUTH_ERROR_WINDOW_SECONDS = 30;
-/** 401-triggered recovery cycles allowed inside AUTH_ERROR_WINDOW_SECONDS. */
+/** Rejections of the current token allowed inside AUTH_ERROR_WINDOW_SECONDS. */
 const MAX_AUTH_ERROR_CYCLES = 3;
 /** An exchange still unsettled after this long is treated as abandoned. */
 const STALE_EXCHANGE_SECONDS = 20;
@@ -84,6 +95,8 @@ export function useEmbedSession({ apiBase, trustedOrigin, }) {
     const [phase, setPhase] = useState({ step: 'waiting_for_code' });
     const refreshTimerRef = useRef(null);
     const retryTimerRef = useRef(null);
+    /** ホストから最初のコードが届くのを待つタイマー。届いた時点で止める。 */
+    const codeTimeoutRef = useRef(null);
     const exchangingRef = useRef(false);
     const exchangeStartedAtRef = useRef(0);
     /** 追い越された交換の結果で新しいセッションを上書きしないための世代番号。 */
@@ -99,15 +112,23 @@ export function useEmbedSession({ apiBase, trustedOrigin, }) {
     /** 連鎖の起点。最後の 1 件ではなく最初の 1 件から窓を測る。 */
     const authErrorRunStartedAtRef = useRef(0);
     /**
-     * 401 を受けてコードを要求済みかどうか。SfaClient は 401 を返した
-     * リクエストごとに onAuthError を呼ぶため、並行リクエストの分をまとめる。
+     * 直近に交換できたトークン。401 がどのトークンに対するものかの照合に使う。
+     * 拒否として受理した時点で null にする。SfaClient は 401 を返した
+     * リクエストごとに onAuthError を呼ぶので、同じトークンの並行分は以降
+     * 照合に失敗して落ちる。
      */
-    const isAuthErrorPendingRef = useRef(false);
+    const currentTokenRef = useRef(null);
     const hasEverAuthenticatedRef = useRef(false);
     /** 同じ復帰の試行でコンソールに書いたかどうか。交換成功で false に戻す。 */
     const hasLoggedExchangeFailureRef = useRef(false);
     /** 打ち切り済み。以降は再要求も画面遷移もしない。 */
     const isSettledRef = useRef(false);
+    /**
+     * 後片付け済み。SfaClient は解体後も生き続け、飛んでいたリクエストが 401 で
+     * 返ると onAuthError を呼ぶ。isSettledRef では代用できない（依存変更による
+     * 再実行でも立ってしまい、生きているセッションまで止まる）。
+     */
+    const isTornDownRef = useRef(false);
     const clearRefreshTimer = useCallback(() => {
         if (refreshTimerRef.current != null) {
             clearTimeout(refreshTimerRef.current);
@@ -120,6 +141,12 @@ export function useEmbedSession({ apiBase, trustedOrigin, }) {
             retryTimerRef.current = null;
         }
     }, []);
+    const clearCodeTimeout = useCallback(() => {
+        if (codeTimeoutRef.current != null) {
+            clearTimeout(codeTimeoutRef.current);
+            codeTimeoutRef.current = null;
+        }
+    }, []);
     const isTokenUsable = useCallback(() => {
         const session = sessionRef.current;
         return session != null && session.expiresAt > Date.now();
@@ -127,13 +154,17 @@ export function useEmbedSession({ apiBase, trustedOrigin, }) {
     /** 打ち切って画面を差し替える。手元に使えるものが何も残っていないとき。 */
     const settle = useCallback((next) => {
         isSettledRef.current = true;
+        // 待ち時間のタイマーを止める。終了画面が書き換わるのを防いでいるのは
+        // ハンドラ側の waiting_for_code 判定のほうで、ここは残り 15 秒を
+        // 空回りさせないための後片付け
+        clearCodeTimeout();
         // 進行中の交換を無効化する。これが無いと、打ち切った後に解決した交換が
         // authenticated を書き戻し、二度と操作できない画面が残る。
         exchangeGenerationRef.current += 1;
         clearRefreshTimer();
         clearRetryTimer();
         setPhase(next);
-    }, [clearRefreshTimer, clearRetryTimer]);
+    }, [clearCodeTimeout, clearRefreshTimer, clearRetryTimer]);
     /**
      * 状態画面は子ツリーがまだ描画されていないときだけ出す。認証済みの表示中は
      * phase を動かさず、ページの状態をそのまま残す。打ち切り後も動かさない。
@@ -154,9 +185,21 @@ export function useEmbedSession({ apiBase, trustedOrigin, }) {
             ? current
             : { step: 'exchanging' });
     }, []);
-    const sendCodeRequest = useCallback(() => {
-        sendToHost({ type: 'sfa-kit:code-request' }, trustedOrigin);
+    // NOTE: 宛先は ref から読む。trustedOrigin を直接閉じ込めると、張り済みの
+    // タイマーが差し替え前の宛先へ送り続ける。あわせて sendCodeRequest の同一性が
+    // 安定し、これを使うコールバック（armCodeRetry / requestCode / scheduleRefresh）
+    // も張り直しの対象から外れる。
+    //
+    // NOTE: 代入はレンダー中ではなく effect で行う。並行レンダリングでは破棄される
+    // レンダーがあり、その値が残ると、一度も有効になっていない宛先へ送ることになる。
+    // useRef の初期値があるので、最初の effect までの窓が空になることはない。
+    const trustedOriginRef = useRef(trustedOrigin);
+    useEffect(() => {
+        trustedOriginRef.current = trustedOrigin;
     }, [trustedOrigin]);
+    const sendCodeRequest = useCallback(() => {
+        sendToHost({ type: 'sfa-kit:code-request' }, trustedOriginRef.current);
+    }, []);
     /** 打ち切り後にトークンが切れた時点で next に落とすためのタイマー。 */
     const scheduleExpiryCutoff = useCallback((next) => {
         clearRefreshTimer();
@@ -243,6 +286,10 @@ export function useEmbedSession({ apiBase, trustedOrigin, }) {
         }, delaySeconds * 1000);
     }, [clearRefreshTimer, requestCode]);
     const handleCodeReceived = useCallback((code, context) => __awaiter(this, void 0, void 0, function* () {
+        // コードが届いた時点でホストは手順に対応している。取りこぼした 1 通でも
+        // それは変わらないので、打ち切り済みかどうかの判定より先に止める。
+        // settle() 側と同じく、表示を守っているのはハンドラ側の判定のほう。
+        clearCodeTimeout();
         if (isSettledRef.current)
             return;
         const startedAt = Date.now();
@@ -265,7 +312,7 @@ export function useEmbedSession({ apiBase, trustedOrigin, }) {
             if (exchangeGenerationRef.current !== generation)
                 return;
             recoveryAttemptsRef.current = 0;
-            isAuthErrorPendingRef.current = false;
+            currentTokenRef.current = session.accessToken;
             hasLoggedExchangeFailureRef.current = false;
             hasEverAuthenticatedRef.current = true;
             sessionRef.current = session;
@@ -317,6 +364,7 @@ export function useEmbedSession({ apiBase, trustedOrigin, }) {
         }
     }), [
         apiBase,
+        clearCodeTimeout,
         scheduleRefresh,
         armCodeRetry,
         clearRetryTimer,
@@ -325,12 +373,37 @@ export function useEmbedSession({ apiBase, trustedOrigin, }) {
         showStatusIfNotMounted,
         showExchangingIfNotMounted,
     ]);
-    const handleAuthError = useCallback(() => {
-        if (isSettledRef.current)
+    const handleAuthError = useCallback((rejectedToken) => {
+        // 解体後の 401 で復帰を始めない。もう無い画面のために使い捨てコードを
+        // ホストへ要求し続けることになる
+        if (isTornDownRef.current || isSettledRef.current)
             return;
-        if (isAuthErrorPendingRef.current)
+        // 認証なしで飛んだリクエストの 401。埋め込みでは SfaProvider に
+        // トークンが渡ってから子ツリーを描き、exchangeCode も空のトークンを
+        // 弾くので、この経路は発生しない。発生するようになったら落とすのでは
+        // なく本物の拒否として扱うこと — さもないと、全部のリクエストが 401 に
+        // なる画面が認証済みの見た目のまま残る。
+        //
+        // NOTE: 下の照合に任せず明示的に落とす。任せると「undefined は string と
+        // 一致しない」という偶然が唯一の根拠になり、currentTokenRef の型を
+        // string | undefined に揃えるリファクタが、型エラーを出さないまま
+        // この分岐を反転させる。
+        if (rejectedToken == null)
             return;
-        isAuthErrorPendingRef.current = true;
+        // 差し替え済みのトークンについての返事は捨てる。ホストへコードを
+        // 要求し直しても、そのリクエストはもう存在しないトークンのものなので
+        // 何も直らず、動いているセッションを巻き添えにするだけになる。
+        // 復帰中（currentTokenRef が null）の分もここで落ちる。
+        //
+        // 並行リクエストの重複もここで落ちる。最初の 1 件で currentTokenRef を
+        // null にするため、同じトークンの 2 件目以降は照合に失敗する。
+        //
+        // NOTE: 文字列の一致で見分けられるのは、Keystone が 1 回ごとに異なる
+        // トークンを出すから（jti に uuid4 が入る）。同じ値が再発行されると、
+        // 差し替え後に届いた遅れ分が新しいトークンの拒否と区別できなくなる。
+        if (rejectedToken !== currentTokenRef.current)
+            return;
+        currentTokenRef.current = null;
         const now = Date.now();
         // 窓は連鎖の起点から測る。直近の 1 件から測ると、正常に復帰している
         // 25 秒間隔の 401 でも窓が滑り続けて打ち切りに達してしまう。
@@ -340,13 +413,18 @@ export function useEmbedSession({ apiBase, trustedOrigin, }) {
             authErrorRunStartedAtRef.current = now;
         }
         authErrorCyclesRef.current += 1;
-        // ここに達した時点で交換自体は通り続けている。その 401 は差し替え前の
-        // トークンで投げられたリクエストの遅れ着信であることが多く、手元では
-        // 見分けられない（onAuthError は拒否されたトークンを渡さない）。
-        // 動いているセッションを巻き添えにしない側を採る。
+        // ここに達するのは、いま持っているトークンが実際に拒否された場合だけ。
+        // それでも上限を置くのは、Keystone が発行するそばから API に拒否される
+        // 状態を止めるため。交換自体は成功し続けるので、見張り側の試行回数は
+        // 毎回 0 に戻り、上限が無ければ永久に回り続ける。
         if (authErrorCyclesRef.current > MAX_AUTH_ERROR_CYCLES) {
-            // 手元のトークンが期限内なら表示は保ち、コードの取り直しだけをやめて、
-            // 失効した時点でセッション切れとして扱う。
+            // 表示は保ち、コードの取り直しだけをやめて、失効した時点でセッション
+            // 切れとして扱う。
+            //
+            // NOTE: ここまで来たトークンは期限内だが拒否されている（照合を通った
+            // ので、遅れ着信ではない）。つまり残す画面ではリクエストが通らない。
+            // それでも畳まないのは、入力中の内容を失わせないため。どちらを採るかは
+            // 挙動の選択なので、変えるなら SFAJAI-202 の判断ごと見直すこと。
             //
             // 据え置きにする必要がある。ホストは要求を受けてから非同期にコードを
             // 発行するので、打ち切った後に以前の要求への応答が届く。交換を続けて
@@ -367,6 +445,61 @@ export function useEmbedSession({ apiBase, trustedOrigin, }) {
         requestCode();
         showStatusIfNotMounted({ step: 'waiting_for_code' });
     }, [requestCode, clearRefreshTimer, stopRetrying, showStatusIfNotMounted]);
+    /** 直前に使っていた認証先。同一性の変化と、値の変化を見分けるために持つ。 */
+    const previousApiBaseRef = useRef(apiBase);
+    /**
+     * @description 認証先が変わっていれば、旧 API を前提にした状態をすべて捨てて
+     * やり直す。変わっていなければ何もしない。
+     *
+     * 判定を内側に持つのは、依存の同一性が変わっただけの張り直しで走らせない
+     * ため。やり直す理由は認証先が変わったことであって、effect が走り直した
+     * ことではない。
+     *
+     * 交換を始めた時点の apiBase が、その結果が通用する認証先を決める。返ってくる
+     * トークンは旧 API が発行したものなので採用できない。採用すると SfaProvider が
+     * 新しい API へ旧トークンを送り続けることになる。
+     *
+     * NOTE: 世代を進めるだけでは足りない。世代がずれると handleCodeReceived の
+     * finally が exchangingRef を戻さず、張り直されたメッセージ effect が送る ready
+     * への返事まで「交換中」と見なされて STALE_EXCHANGE_SECONDS の間無視される。
+     *
+     * NOTE: isSettledRef は戻さない。打ち切り済みの画面は認証先を変えても復帰しない。
+     * 復帰させるなら settle() が消したタイマー群も張り直す必要があり、終了画面を
+     * 出したまま裏で再試行が走る状態を招く。再読み込みを復帰手段とする。
+     */
+    const restartIfAuthTargetChanged = useCallback((nextApiBase) => {
+        if (previousApiBaseRef.current === nextApiBase)
+            return;
+        previousApiBaseRef.current = nextApiBase;
+        exchangeGenerationRef.current += 1;
+        exchangingRef.current = false;
+        // 旧 API のトークンは新しい認証先では通らない。保持判定から外す
+        sessionRef.current = null;
+        // NOTE: これ以降、旧トークンについての 401 は照合に失敗して捨てられる。
+        // 旧トークンで復帰を始めても新しい認証先では通らないので意味がない。
+        // 復帰はメッセージ effect が送り直す ready と、下で張る見張りが担う。
+        currentTokenRef.current = null;
+        // 認証先ごとに試行回数を数え直す。引き継ぐと上限の手前から始まることになり、
+        // armCodeRetry は上限判定を送信より先に行うため、新しい認証先へ
+        // code-request を 1 通も送らないまま打ち切られる。
+        //
+        // NOTE: 上限に達するには同じ認証先が 1 分ほど続く必要がある。それより短い
+        // 間隔で認証先が変わり続ける限り打ち切りには達しない。apiBase は
+        // resolveApiBase の純粋な結果で、ページの寿命の間は変わらない前提。
+        recoveryAttemptsRef.current = 0;
+        authErrorCyclesRef.current = 0;
+        authErrorRunStartedAtRef.current = 0;
+        // ready はメッセージ effect が送り直す。ここでは応答が無かったときの
+        // 見張りだけ張る
+        armCodeRetryRef.current();
+        // NOTE: 先回り更新のタイマーはここで消さない。refreshTimerRef は打ち切り後の
+        // 失効タイマー（scheduleExpiryCutoff）も兼ねており、消すと「セッション期限切れ」
+        // へ落ちなくなる。旧セッションの期限で残っても、交換が成功した時点で
+        // scheduleRefresh が張り替えるため実害はない。
+    }, []);
+    useEffect(() => {
+        restartIfAuthTargetChanged(apiBase);
+    }, [apiBase, restartIfAuthTargetChanged]);
     useEffect(() => {
         const handleMessage = (event) => {
             var _a;
@@ -382,7 +515,16 @@ export function useEmbedSession({ apiBase, trustedOrigin, }) {
         // If the host never sends a code (e.g. mintSfaKitExchangeCode is not
         // implemented or the host page doesn't support the embed protocol),
         // show an error instead of hanging on "Connecting..." forever.
-        const codeTimeout = setTimeout(() => {
+        //
+        // NOTE: settle では閉じない。ホストが遅いだけなら、期限を過ぎて届いた
+        // コードでそのまま復帰できる。打ち切ってしまうと、有効なコードが数秒後に
+        // 来ているのに再読み込みするまで死んだままになる。
+        //
+        // 待ち状態のときだけ出す。この判定が effect の張り直しも兼ねる — 既に
+        // 認証済み・交換中・別の理由で打ち切り済みなら、どれも
+        // waiting_for_code ではないので、より正確な表示を上書きしない。
+        codeTimeoutRef.current = setTimeout(() => {
+            codeTimeoutRef.current = null;
             setPhase(current => {
                 if (current.step !== 'waiting_for_code')
                     return current;
@@ -393,12 +535,40 @@ export function useEmbedSession({ apiBase, trustedOrigin, }) {
                 };
             });
         }, CODE_TIMEOUT_SECONDS * 1000);
+        // NOTE: 消すのはこの effect が張ったコード待ちタイマーだけ。更新・再試行の
+        // タイマーはこの effect の持ち物ではなく、フックが載っている間ずっと生きる。
+        // ここで消すと、認証済みのまま apiBase や trustedOrigin が変わっただけで
+        // 先回り更新が失われ、誰も張り直さないままトークンが期限切れになる。
         return () => {
             window.removeEventListener('message', handleMessage);
-            clearTimeout(codeTimeout);
-            clearRefreshTimer();
-            clearRetryTimer();
+            clearCodeTimeout();
         };
-    }, [trustedOrigin, handleCodeReceived, clearRefreshTimer, clearRetryTimer]);
+    }, [trustedOrigin, handleCodeReceived, clearCodeTimeout]);
+    // NOTE: 解体は依存を持たない effect に分ける。上のメッセージ effect の後片付けは
+    // 依存の同一性が変わるたびに走るので、そこで世代を進めると、認証先は同じままの
+    // 張り直しでも進行中の交換が捨てられる。認証先が変わった場合の破棄は専用の
+    // effect（authTargetRef）が担う。ここは本当にアンマウントするときだけ走る。
+    useEffect(() => {
+        // ref は再マウントを越えて残る。StrictMode や Fast Refresh は
+        // マウント → 解体 → 再マウントと走るので、ここで戻さないと
+        // handleAuthError が最初の行で return し続け、401 から復帰できなくなる。
+        isTornDownRef.current = false;
+        return () => {
+            isTornDownRef.current = true;
+            // 解体後に解決した交換で、この下で消すタイマーを張り直させない。
+            // 世代を進めると handleCodeReceived が結果を捨てる。進行中の交換は
+            // どれも現行世代のものではなくなるため、居座り判定も解除する。
+            exchangeGenerationRef.current += 1;
+            exchangingRef.current = false;
+            // NOTE: clearRefreshTimer / clearRetryTimer は経由せず直接消す。経由すると
+            // 依存配列が空でなくなり、「アンマウント時だけ」がそれらの同一性の安定に
+            // 依存する。両者は settle → armCodeRetry → scheduleRefresh →
+            // handleCodeReceived まで伝播しているため、影響範囲が広い。
+            if (refreshTimerRef.current != null)
+                clearTimeout(refreshTimerRef.current);
+            if (retryTimerRef.current != null)
+                clearTimeout(retryTimerRef.current);
+        };
+    }, []);
     return { phase, handleAuthError };
 }

package/src/lib/bundle/build-static-bundle.d.ts

@@ -0,0 +1,45 @@
+import type { BundleManifest } from '../signing/types.js';
+export interface BuildStaticBundleOptions {
+    /** Entry module that mounts the page, e.g. `entry.tsx`. */
+    readonly entry: string;
+    /** Directory the bundle is written to. Created if absent. */
+    readonly outDir: string;
+    /**
+     * The Studio build version this bundle targets — not the sfa-kit npm version.
+     *
+     * NOTE: required on purpose. The signature covers
+     * `"{studio_version}:{content_hash}"` and Keystone reads the field back
+     * separately, so a default would sign the wrong version perfectly well.
+     */
+    readonly studioVersion: string;
+    /** Keystone API base, e.g. `https://keystone-api-staging.chikyu.mobi`. */
+    readonly apiBase: string;
+    /** The same Bearer token the rest of the Keystone API is called with. */
+    readonly accessToken: string;
+    /** Title of the generated `index.html`. */
+    readonly title?: string;
+    /**
+     * Extra manifest fields, e.g. `name` or `displayName`. Keystone ignores
+     * everything but the three signed fields, which cannot be overridden here.
+     */
+    readonly manifestExtras?: Readonly<Record<string, unknown>>;
+}
+/**
+ * @description Builds the framework-free static bundle a page is uploaded as
+ * to become a custom tab, and signs it.
+ *
+ * Produces `index.html`, `assets/bundle.js` and a signed `manifest.json` in
+ * `outDir`. The caller zips that directory's contents — the files have to sit
+ * at the zip root. Zipping is left out because Node ships no zip writer, and a
+ * dependency for it would reach a package whose runtime needs only `tslib`.
+ *
+ * Signing is not optional, and a failure removes the output: an unsigned bundle
+ * uploads successfully while Keystone's verifier runs in `disabled` mode and
+ * only starts failing at `enforced`, so a half-built directory left behind is
+ * something a caller can still zip and upload by mistake.
+ *
+ * **Node.js only**, and needs `esbuild` installed alongside the kit.
+ *
+ * @returns The manifest that was written.
+ */
+export declare function buildStaticBundle({ entry, outDir, studioVersion, apiBase, accessToken, title, manifestExtras, }: BuildStaticBundleOptions): Promise<BundleManifest>;

package/src/lib/bundle/build-static-bundle.js

@@ -0,0 +1,263 @@
+import { __awaiter } from "tslib";
+import { mkdir, readFile, readdir, rm, stat, writeFile, } from 'node:fs/promises';
+import { join, posix, relative } from 'node:path';
+import { computeContentHash } from '../signing/compute-content-hash.js';
+import { readBundleFiles } from '../signing/read-bundle-files.js';
+import { loadEsbuild } from './esbuild-loader.js';
+import { requestSignature } from './request-signature.js';
+/** Where the bundled script lands inside the output directory. */
+const BUNDLE_PATH = 'assets/bundle.js';
+/** esbuild writes this beside the script when the entry imports any CSS. */
+const STYLES_PATH = 'assets/bundle.css';
+/**
+ * Every path this builder writes, relative to `outDir` with forward slashes.
+ *
+ * NOTE: full paths, not top-level names. Matching on names would accept any
+ * directory shaped like a static site — an `index.html` beside an `assets/`
+ * folder — and clear it.
+ */
+const OWN_OUTPUT = new Set([
+    'index.html',
+    'manifest.json',
+    BUNDLE_PATH,
+    STYLES_PATH,
+]);
+/** How many unexpected paths an error names before it stops listing them. */
+const UNEXPECTED_SHOWN = 5;
+/**
+ * Removed rather than refused. Opening the output directory in Finder to zip
+ * it — which GUIDE.md tells the reader to do — leaves a `.DS_Store` behind,
+ * and refusing it would wedge the build → zip → rebuild loop on a hidden file.
+ */
+const JUNK_FILES = new Set(['.DS_Store', 'Thumbs.db']);
+/**
+ * @description Builds the framework-free static bundle a page is uploaded as
+ * to become a custom tab, and signs it.
+ *
+ * Produces `index.html`, `assets/bundle.js` and a signed `manifest.json` in
+ * `outDir`. The caller zips that directory's contents — the files have to sit
+ * at the zip root. Zipping is left out because Node ships no zip writer, and a
+ * dependency for it would reach a package whose runtime needs only `tslib`.
+ *
+ * Signing is not optional, and a failure removes the output: an unsigned bundle
+ * uploads successfully while Keystone's verifier runs in `disabled` mode and
+ * only starts failing at `enforced`, so a half-built directory left behind is
+ * something a caller can still zip and upload by mistake.
+ *
+ * **Node.js only**, and needs `esbuild` installed alongside the kit.
+ *
+ * @returns The manifest that was written.
+ */
+export function buildStaticBundle(_a) {
+    return __awaiter(this, arguments, void 0, function* ({ entry, outDir, studioVersion, apiBase, accessToken, title = 'SFA/CRM', manifestExtras = {}, }) {
+        for (const [name, value] of [
+            ['entry', entry],
+            ['outDir', outDir],
+            ['studioVersion', studioVersion],
+            ['apiBase', apiBase],
+            ['accessToken', accessToken],
+        ]) {
+            // NOTE: checked before esbuild runs. An empty apiBase otherwise surfaces as
+            // "Failed to parse URL from /v1/pages/sign" after a full build.
+            // NOTE: `== null` as well as empty. The subpath is published, and a JS
+            // caller omitting a field would otherwise pay for a full build to reach
+            // `Authorization: Bearer undefined`.
+            if (value == null || value === '') {
+                throw new Error(`${name} is required and must not be empty`);
+            }
+        }
+        // Serialised now so a value that cannot be JSON — cyclic, a BigInt — fails
+        // before anything is written, rather than after Keystone has signed.
+        assertSerialisable(manifestExtras);
+        const esbuild = yield loadEsbuild();
+        yield prepareOutDir(outDir);
+        yield mkdir(join(outDir, 'assets'), { recursive: true });
+        try {
+            yield esbuild.build({
+                entryPoints: [entry],
+                outfile: join(outDir, BUNDLE_PATH),
+                bundle: true,
+                minify: true,
+                format: 'esm',
+                jsx: 'automatic',
+                target: 'es2020',
+            });
+            // entry が CSS を import していると esbuild が bundle.css も書き出す。
+            // index.html から参照しないと、署名も検証も通ったうえで無スタイルの画面が
+            // 出る — どこにも失敗が現れない
+            const hasStyles = yield stat(join(outDir, STYLES_PATH)).then(() => true, () => false);
+            yield writeFile(join(outDir, 'index.html'), renderIndexHtml(title, hasStyles), 'utf-8');
+            // manifest.json is written last: the hash covers every other file, so the
+            // directory has to be complete before it is computed.
+            const contentHash = computeContentHash(yield readBundleFiles(outDir));
+            const manifest = {
+                studio_version: studioVersion,
+                content_hash: contentHash,
+                signature: yield requestSignature({
+                    apiBase,
+                    accessToken,
+                    studioVersion,
+                    contentHash,
+                }),
+            };
+            yield writeFile(join(outDir, 'manifest.json'), 
+            // NOTE: the decorative fields go first so the three signed ones cannot be
+            // overwritten by a caller's extras.
+            `${JSON.stringify(Object.assign(Object.assign({}, manifestExtras), manifest), null, 2)}\n`, 'utf-8');
+            return manifest;
+        }
+        catch (thrown) {
+            // Whatever was written is a bundle in every respect but the manifest, and
+            // a caller can still zip and upload it.
+            yield removeOwnOutput(outDir).catch(() => {
+                throw new Error(`${thrown instanceof Error ? thrown.message : String(thrown)} ` +
+                    `Additionally, ${outDir} could not be cleaned up — delete it by ` +
+                    'hand rather than uploading it; it carries no signature.');
+            });
+            throw thrown;
+        }
+    });
+}
+/** Fails now on a value `JSON.stringify` would reject after the bundle is signed. */
+function assertSerialisable(extras) {
+    try {
+        JSON.stringify(extras);
+    }
+    catch (thrown) {
+        throw new Error('manifestExtras must be JSON-serialisable ' +
+            `(${thrown instanceof Error ? thrown.message : String(thrown)})`);
+    }
+}
+/**
+ * @description Empties the output directory of previous build output, and
+ * refuses to touch anything else.
+ *
+ * NOTE: `outDir` comes from a caller's flag, so nothing is deleted recursively
+ * — `--out src` would take the source tree with it. Only the exact files this
+ * builder writes are removed, and any other file at any depth stops the build:
+ * a leftover lands in `content_hash` and then has to be in the zip for the
+ * signature to match, which quietly makes it part of the bundle.
+ *
+ * NOTE: matching those names is not enough to claim the directory. `index.html`
+ * beside `assets/bundle.js` is also what a hand-written static site looks like,
+ * and deleting one would be unrecoverable. A `manifest.json` carrying the three
+ * signed fields is the proof, because only this builder writes one.
+ */
+function prepareOutDir(outDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        // NOTE: names only. Reading contents here — as readBundleFiles does — would
+        // pull the whole directory into memory to decide it is the wrong directory,
+        // so `--out .` in a repository would run out of memory instead of refusing.
+        const entries = yield readdir(outDir, {
+            recursive: true,
+            withFileTypes: true,
+        }).catch((thrown) => {
+            // Only "it is not there yet" means there is nothing to check. Swallowing
+            // every error would turn a permission problem into a silent build over
+            // whatever the directory held.
+            if (thrown.code === 'ENOENT')
+                return null;
+            throw thrown;
+        });
+        if (entries == null)
+            return;
+        const unexpected = [];
+        const junk = [];
+        const own = [];
+        for (const entry of entries) {
+            if (!entry.isFile())
+                continue;
+            const parent = (_a = entry.parentPath) !== null && _a !== void 0 ? _a : entry.path;
+            const path = relative(outDir, join(parent, entry.name))
+                .split(/[\\/]/)
+                .join(posix.sep);
+            if (OWN_OUTPUT.has(path)) {
+                own.push(path);
+                continue;
+            }
+            // NOTE: collected, not deleted yet. Removing junk from a directory the
+            // next few lines may refuse to touch would contradict the promise above.
+            if (JUNK_FILES.has(entry.name)) {
+                junk.push(join(parent, entry.name));
+                continue;
+            }
+            unexpected.push(path);
+            if (unexpected.length > UNEXPECTED_SHOWN)
+                break;
+        }
+        if (unexpected.length > 0) {
+            const shown = unexpected.slice(0, UNEXPECTED_SHOWN).sort().join(', ');
+            const more = unexpected.length > UNEXPECTED_SHOWN ? ', and more' : '';
+            throw new Error(`${outDir} holds files this build did not produce ` +
+                `(${shown}${more}). They would be hashed into the bundle. ` +
+                'Point --out at an empty directory, or clear it first.');
+        }
+        if (own.length > 0 && !(yield hasOwnManifest(outDir))) {
+            throw new Error(`${outDir} holds ${own.sort().join(', ')} but no manifest.json this ` +
+                'builder wrote, so it is not a previous build of this bundle and will ' +
+                'not be overwritten. Point --out at an empty directory, or clear it ' +
+                'first.');
+        }
+        for (const path of junk) {
+            yield rm(path, { force: true });
+        }
+        yield removeOwnOutput(outDir);
+    });
+}
+/** Whether the directory carries a manifest only this builder could have written. */
+function hasOwnManifest(outDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const raw = yield readFile(join(outDir, 'manifest.json'), 'utf-8').catch(() => null);
+        if (raw == null)
+            return false;
+        try {
+            const parsed = JSON.parse(raw);
+            return ['studio_version', 'content_hash', 'signature'].every(field => typeof parsed[field] === 'string' && parsed[field] !== '');
+        }
+        catch (_a) {
+            return false;
+        }
+    });
+}
+/**
+ * @description Deletes the files this builder writes, and nothing else.
+ *
+ * NOTE: separate from {@link prepareOutDir} because the failure path needs the
+ * removal without the validation. Reusing the checking function there would
+ * throw on any stray file and leave the unsigned bundle exactly where the
+ * contract promises it will not be.
+ */
+function removeOwnOutput(outDir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        for (const path of OWN_OUTPUT) {
+            yield rm(join(outDir, path), { force: true });
+        }
+    });
+}
+/** The host page for the bundle: the script, and the stylesheet if there is one. */
+function renderIndexHtml(title, hasStyles) {
+    const stylesheet = hasStyles
+        ? `\n    <link rel="stylesheet" href="./${STYLES_PATH}" />`
+        : '';
+    return `<!doctype html>
+<html lang="ja">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${escapeHtml(title)}</title>${stylesheet}
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./${BUNDLE_PATH}"></script>
+  </body>
+</html>
+`;
+}
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}