@geniee-inc/sfa-kit 1.18.0 → 1.19.2

package/GUIDE.md

@@ -25,16 +25,27 @@ Three additional subpaths are available: `@geniee-inc/sfa-kit/signing` exposes b
 
 ### Static bundle manifest (custom-tab uploads)
 
-A page uploaded through GENIEE's SFA/CRM settings UI as a custom tab is a framework-free static bundle — `index.html` + `manifest.json` + `assets/` — not a Next.js app. Its `manifest.json` carries the three fields Keystone's `BundleSignatureVerifier` reads: `studio_version`, `content_hash`, `signature`.
+A page uploaded through GENIEE's SFA/CRM settings UI as a custom tab is a framework-free static bundle — `index.html` + `manifest.json` + `assets/` — not a Next.js app. Its `manifest.json` carries three fields:
+
+| Field             | Signed | Meaning                                                                                      |
+| ----------------- | ------ | -------------------------------------------------------------------------------------------- |
+| `content_hash`    | Yes    | SHA-256 over every other file in the bundle (see `computeContentHash`)                       |
+| `signature`       | -      | HMAC-SHA-256 of `content_hash`, computed by Keystone                                         |
+| `sfa_kit_version` | No     | The sfa-kit version that ran the build. Keystone stores it with the page for troubleshooting |
+
+Editing any file after signing changes `content_hash`, and a new `content_hash` needs a new signature that only Keystone can compute, so an edited bundle fails verification.
+
+A manifest that also carries `studio_version` is the legacy format: its signature covers `"{studio_version}:{content_hash}"`. Keystone accepts both and tells them apart by whether `studio_version` is present.
 
 **The signing key lives only in Keystone, so a page build never computes the signature itself.** It hashes the bundle locally and asks Keystone to sign:
 
 ```ts
+import pkg from '@geniee-inc/sfa-kit/package.json';
 import {
   readBundleFiles,
   computeContentHash,
 } from '@geniee-inc/sfa-kit/signing';
-import type { BundleManifest } from '@geniee-inc/sfa-kit/signing';
+import type { ContentHashManifest } from '@geniee-inc/sfa-kit/signing';
 
 const files = await readBundleFiles('dist');
 const contentHash = computeContentHash(files);
@@ -47,16 +58,13 @@ const response = await fetch(`${apiBase}/v1/pages/sign`, {
     'Content-Type': 'application/json',
     Authorization: `Bearer ${accessToken}`,
   },
-  body: JSON.stringify({
-    studio_version: studioVersion,
-    content_hash: contentHash,
-  }),
+  body: JSON.stringify({ content_hash: contentHash }),
 });
 if (!response.ok) throw new Error(`Signing failed: ${response.status}`);
 const { signature } = (await response.json()) as { signature: string };
 
-const manifest: BundleManifest = {
-  studio_version: studioVersion, // the Studio build version, NOT the sfa-kit npm version
+const manifest: ContentHashManifest = {
+  sfa_kit_version: pkg.version,
   content_hash: contentHash,
   signature,
 };
@@ -72,7 +80,6 @@ import { buildStaticBundle } from '@geniee-inc/sfa-kit/bundle';
 await buildStaticBundle({
   entry: 'entry.tsx', // renders <SfaLoginGate>…</SfaLoginGate> into #root
   outDir: 'dist',
-  studioVersion: '0.5.0', // the Studio build version, NOT the sfa-kit npm version
   apiBase: 'https://keystone-api-staging.chikyu.mobi',
   accessToken: token,
 });
@@ -84,7 +91,6 @@ Or from the command line, which is the shorter path when a build script drives i
 SFA_KIT_ACCESS_TOKEN=<token> npx sfa-kit-bundle \
   --entry entry.tsx \
   --out dist \
-  --studio-version 0.5.0 \
   --api-base https://keystone-api-staging.chikyu.mobi
 ```
 
@@ -95,7 +101,9 @@ Then zip the **contents** of `dist/` — the bundle's files have to sit at the z
 `esbuild` is an optional peer dependency; install it alongside the kit. Its options are fixed: JS, JSX, TS and CSS bundle, but there is no loader for images or fonts, so a page importing a `.png`, `.svg` or a font — including through `url()` in CSS — fails to build. Inline such assets as data URIs, or reference them by absolute URL.
 Nothing is written when signing fails, so a failed build never leaves an unsigned bundle behind to be uploaded by mistake.
 
-`studioVersion` has no default on purpose. The signature covers `"{studio_version}:{content_hash}"` and Keystone reads the field back separately, so a guessed value produces a valid signature over the wrong version.
+`sfa_kit_version` is filled in automatically with the version of the sfa-kit that ran the build. esbuild bundles whichever copy of sfa-kit the entry module imports, which is normally the same one, but a project with two installed copies can record one version and ship the other.
+
+`studioVersion` (`--studio-version`) is deprecated. When given, the bundle is signed in the legacy format and the manifest carries `studio_version`. Omit it.
 
 ### Signing exports
 
@@ -109,7 +117,7 @@ The lower-level pieces `buildStaticBundle` uses, for a caller that builds its ow
 | `createManifest`              | **Yes**               |
 | `createManifestFromDirectory` | **Yes**               |
 
-The three key-taking exports exist for the service that holds the key. Calling them from a page build means inventing a key, which Keystone will not accept — and the mistake is invisible at first, because bundle verification ships in `disabled` mode: the upload succeeds, and only starts failing once the mode is switched to `enforced`.
+The three key-taking exports produce the legacy format, signed over `"{studio_version}:{content_hash}"`. They exist for the service that holds the key. Calling them from a page build means inventing a key, which Keystone will not accept — and the mistake is invisible at first, because bundle verification ships in `disabled` mode: the upload succeeds, and only starts failing once the mode is switched to `enforced`.
 
 `content_hash` must come from `computeContentHash`, never from hashing files back to back. The algorithm length-prefixes each path and each file's contents before feeding them into one running SHA-256; without those prefixes `"ab" + "c"` and `"a" + "bc"` hash identically, and the result never matches Keystone's own computation.
 
@@ -222,6 +230,8 @@ const { record, isLoading, error, refetch } = useRecord('companies', 'abc123');
 
 Returns `{ record: SfaRecord | null, isLoading, error, refetch }`.
 
+The result always describes the `collection` and `recordId` passed right now: from the first render after either changes it reports no record and no error — with `isLoading` while the new fetch runs — so the previous record or error never shows as the answer to the new one. An empty `recordId` with a collection given sets `error` instead of fetching. Disabling the hook (`enabled: false`) without changing them keeps the record already fetched.
+
 ### useRecordList
 
 Fetches a paginated list of records. Supports cursor-based pagination (Keystone API).
@@ -277,7 +287,7 @@ const result = useRecordList('companies', {
 
 Disabling the hook, or clearing `collection`, discards any request still in flight: a response that lands after the caller stopped asking never becomes the result, and the `'loading'` a discarded refetch set does not outlive it — the hook goes back to how the query last ended.
 
-Returns `{ items, totalCount, hasMore, pageIndex, status, isLoading, error, refetch, goToPage }`.
+Returns `{ items, totalCount, hasMore, pageIndex, status, isLoading, error, refetch, goToPage }`. `totalCount` is `null` when it is not known: the backend does not report it — Keystone pages with cursors and returns no total — or no fetch has succeeded since the query last changed (an earlier answer to the same query does not count). Read it together with `status`, and use `hasMore` to tell whether another page exists.
 
 For cross-object queries (fetching child records of a parent), prefer `useRelatedRecords` which builds the filter automatically from describe metadata.
 
@@ -351,7 +361,7 @@ const { items, isLoading, error } = useRelatedRecords(
 
 Check `status` for **every** hook on the page, not just the first one. Each related-records hook fails independently: with several fetches firing on mount, one can hit a rate limit or a timeout while the others succeed, and the failed one renders as an empty section unless its own status is read.
 
-Returns `{ items, totalCount, hasMore, pageIndex, status, goToPage, isLoading, error, refetch, relationship }`.
+Returns `{ items, totalCount, hasMore, pageIndex, status, goToPage, isLoading, error, refetch, relationship }`. As in `useRecordList`, `totalCount` is `null` when it is not known.
 
 ### Bulk writes
 
@@ -715,7 +725,7 @@ The state for `status === 'error'`. Renders `⚠ 取得失敗` and, when given `
 
 Props: `{ onRetry?: () => void, message?: string, retryLabel?: string }`. Without `onRetry` no link is rendered — a dead control is worse than none.
 
-The server's error text is deliberately not shown: it is wording the reader cannot act on. Pages that need it still have `error` from the hook, and `RecordList` / `RecordView` report it through their `onError` prop.
+The server's error text is deliberately not shown: it is wording the reader cannot act on. Pages that need it still have `error` from the hook, and `RecordList` / `RecordView` report it through their `onError` prop (`RecordView` does not for an empty record id — see [RecordView](#recordview)).
 
 `refetch` retries whichever step failed. On `useRelatedRecords` that includes a failed describe: retrying only the list would do nothing, because without relationship metadata the list never ran.
 
@@ -814,6 +824,10 @@ Props:
 
 Each group: `title?` (heading), `layout?` (`"1-col"` | `"2-col"` | `"3-col"`), `fields` (field names).
 
+**States.** While the record is fetched it shows "Loading...". A failed fetch shows `FetchErrorState` and calls `onError`. When no record is specified — `collection` or `recordId` is empty — it shows `EmptyState` with "レコードが指定されていません" and does **not** call `onError`: nothing was fetched, so there is no failure to report. `useRecord` on its own still sets `error` for an empty record id (a collection given, no record picked), so a page built on the hook can word that case itself.
+
+**Heading.** `title` if given, else the record's own title, else the values of its title fields joined by spaces. Only values a reader understands go into the heading — a reference or choice field without a label is left out rather than showing its id or code.
+
 ### RecordList
 
 Displays a paginated table of records.
@@ -834,6 +848,8 @@ Props:
 
 `RecordView` takes the same prop and, without it, names its `title` — the label it already shows as the heading — so a page that passed `title="会社"` gets `⚠ 会社の取得に失敗` for free.
 
+**States.** While the list is fetched it shows "Loading...". A failed fetch shows `FetchErrorState` and calls `onError`. Without a `collection` nothing is asked, so instead of "0 records" it shows `EmptyState` with "オブジェクトが指定されていません".
+
 ### FieldRenderer
 
 Renders a single field value based on its kind. Used internally by RecordView and RecordList. Use directly when building custom layouts.
@@ -842,6 +858,10 @@ Renders a single field value based on its kind. Used internally by RecordView an
 <FieldRenderer fieldValue={someField} fieldName="company_name" />
 ```
 
+It shows `label` (formatted by the API). When `label` is empty or `null`, it falls back to `value` only for `text` / `number` / `date` / `datetime` / `computed` fields whose value is a number, a boolean or a string that is not markup; a choice or reference field, whose value is a code or an id, shows `—` instead. The RecordView heading follows the same rule.
+
+A single-line `text` value becomes a link when it is a URL, an email address, or a phone number — a Japanese number starting with 0 with 10 or 11 digits (`03-1234-5678`), or an international one starting with `+` with 8 to 15 digits. Postal codes (`100-0001`) and dates (`2026-09-28`) stay plain text.
+
 ## Design tokens
 
 All kit components use CSS custom properties with `--sfa-*` prefixes. Use these in your generated UI for visual consistency with SFA/CRM:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geniee-inc/sfa-kit",
-  "version": "1.18.0",
+  "version": "1.19.2",
   "description": "React hooks and components for building pages that connect to GENIEE SFA/CRM data.",
   "type": "module",
   "main": "./src/index.js",

package/src/bin/sfa-kit-bundle.js

@@ -11,16 +11,15 @@ Usage:
   ${TOKEN_ENV}=<token> npx sfa-kit-bundle \\
     --entry entry.tsx \\
     --out dist \\
-    --studio-version 0.5.0 \\
     --api-base https://keystone-api-staging.chikyu.mobi
 
 Options:
   --entry           Entry module that mounts the page into #root. Required.
   --out             Output directory. Required.
-  --studio-version  The Studio build version this bundle targets, not the
-                    sfa-kit npm version. Required.
   --api-base        Keystone API base, without a trailing slash. Required.
   --title           <title> of the generated index.html. Default: SFA/CRM.
+  --studio-version  Deprecated; omit it. When given, the bundle is signed in
+                    the legacy format, over "{studio_version}:{content_hash}".
   --help            Show this message.
 
 Environment:
@@ -28,7 +27,8 @@ Environment:
   API is called with. Required, and read from the environment rather than an
   argument so it does not land in shell history or in the process list.
 
-Writes index.html, assets/bundle.js and a signed manifest.json. Zip the
+Writes index.html, assets/bundle.js and a signed manifest.json, which records
+this sfa-kit version as sfa_kit_version. Zip the
 contents of the output directory — the files have to sit at the zip root.
 Needs esbuild installed alongside the kit.`;
 const OPTIONS = {
@@ -70,7 +70,7 @@ function parseCliOptions(argv) {
  */
 export function runBundleCli(argv, env, out) {
     return __awaiter(this, void 0, void 0, function* () {
-        var _a, _b, _c, _d, _e, _f;
+        var _a, _b, _c, _d, _e;
         const parsed = parseCliOptions(argv);
         if (parsed.error != null) {
             out.error(`${parsed.error}\n\n${USAGE}`);
@@ -81,7 +81,7 @@ export function runBundleCli(argv, env, out) {
             out.log(USAGE);
             return 0;
         }
-        const missing = ['entry', 'out', 'studio-version', 'api-base']
+        const missing = ['entry', 'out', 'api-base']
             .filter(name => { var _a; return ((_a = values[name]) !== null && _a !== void 0 ? _a : '') === ''; })
             .map(name => `--${name}`);
         const accessToken = (_a = env[TOKEN_ENV]) !== null && _a !== void 0 ? _a : '';
@@ -91,10 +91,18 @@ export function runBundleCli(argv, env, out) {
             out.error(`Missing required: ${missing.join(', ')}\n\n${USAGE}`);
             return 1;
         }
+        // NOTE: an empty value is refused, not read as "omitted". Omitting the flag
+        // switches the signing format, and a script whose variable came out empty
+        // should hear about it rather than quietly get the other format.
+        const studioVersion = values['studio-version'];
+        if (studioVersion != null && studioVersion.trim() === '') {
+            out.error(`--studio-version must not be empty. Omit it to sign content_hash alone.\n\n${USAGE}`);
+            return 1;
+        }
         try {
-            const manifest = yield buildStaticBundle(Object.assign({ entry: (_b = values.entry) !== null && _b !== void 0 ? _b : '', outDir: (_c = values.out) !== null && _c !== void 0 ? _c : '', studioVersion: (_d = values['studio-version']) !== null && _d !== void 0 ? _d : '', apiBase: (_e = values['api-base']) !== null && _e !== void 0 ? _e : '', accessToken }, (((_f = values.title) !== null && _f !== void 0 ? _f : '') === '' ? {} : { title: values.title })));
+            const manifest = yield buildStaticBundle(Object.assign(Object.assign({ entry: (_b = values.entry) !== null && _b !== void 0 ? _b : '', outDir: (_c = values.out) !== null && _c !== void 0 ? _c : '', apiBase: (_d = values['api-base']) !== null && _d !== void 0 ? _d : '', accessToken }, (((_e = values.title) !== null && _e !== void 0 ? _e : '') === '' ? {} : { title: values.title })), (studioVersion == null ? {} : { studioVersion })));
             out.log(`Built and signed ${values.out} ` +
-                `(studio_version ${manifest.studio_version}, ` +
+                `(sfa_kit_version ${manifest.sfa_kit_version}, ` +
                 `content_hash ${manifest.content_hash}).`);
             return 0;
         }

package/src/bundle.d.ts

@@ -13,7 +13,6 @@
  * await buildStaticBundle({
  *   entry: 'entry.tsx',
  *   outDir: 'dist',
- *   studioVersion: '0.5.0',
  *   apiBase: 'https://keystone-api-staging.chikyu.mobi',
  *   accessToken: token,
  * });
@@ -21,6 +20,6 @@
  *
  * @packageDocumentation
  */
-export type { BundleManifest } from './lib/signing/index.js';
+export type { BundleManifest, ContentHashManifest, } from './lib/signing/index.js';
 export type { BuildStaticBundleOptions } from './lib/bundle/index.js';
 export { buildStaticBundle } from './lib/bundle/index.js';

package/src/lib/auth/DevToolbar.js

@@ -63,16 +63,13 @@ export function DevToolbar({ organizationId, preview, level, objectKey, onLogout
         };
     }, [client, hasObjectKey]);
     const [localRecordId, setLocalRecordId] = useState((_b = (_a = preview.state) === null || _a === void 0 ? void 0 : _a.record_id) !== null && _b !== void 0 ? _b : '');
-    // NOTE: フォームは record レベル かつ objectKey があるときだけ描くため、
-    // ここに来る時点で objectKey はある。型を絞るためのガードとして残す
+    // NOTE: フォームは record レベル かつ objectKey があるときだけ描く。対象の
+    // オブジェクトは StandaloneFlow が objectKey から決めるので、ここではレコード ID だけを渡す
     const handleSubmit = useCallback((e) => {
         e.preventDefault();
-        if (!hasObjectKey || objectKey == null)
-            return;
-        preview.setObjectKey(objectKey);
         preview.setRecordId(localRecordId);
         preview.triggerFetch();
-    }, [hasObjectKey, objectKey, localRecordId, preview]);
+    }, [localRecordId, preview]);
     // NOTE: カタログ取得前は key をそのまま表示名に使う。objectKey が無いページは
     // undefined のままにして、表示側で出し分ける
     const objectLabel = hasObjectKey

package/src/lib/auth/SfaLoginGate.js

@@ -166,22 +166,31 @@ function StandaloneFlow({ apiBase, defaultOrganizationId, objectKey, level, chil
     // NOTE: level を渡さない既存ページのために、objectKey の有無から補う。
     // 以前は objectKey があること自体が「record レベル」を意味していた
     const resolvedLevel = level !== null && level !== void 0 ? level : (objectKey != null && objectKey !== '' ? 'record' : 'object');
-    // Preview context state managed by DevToolbar.
-    // When objectKey is provided, pre-populate it.
-    const [previewObjectKey, setPreviewObjectKey] = useState(objectKey !== null && objectKey !== void 0 ? objectKey : '');
+    // Preview context state managed by DevToolbar. The object comes straight
+    // from the objectKey prop: nothing in the toolbar changes it.
     const [previewRecordId, setPreviewRecordId] = useState('');
+    // NOTE: a record id belongs to the object it was submitted for. objectKey can
+    // change without remounting this flow, so forget the id whenever it does —
+    // also when it changes back, or the old id would come back with it. This is
+    // React's "adjust state when a prop changes" pattern: it runs during render,
+    // so no frame pairs the new object with the old id
+    const [recordIdObjectKey, setRecordIdObjectKey] = useState(objectKey);
+    if (recordIdObjectKey !== objectKey) {
+        setRecordIdObjectKey(objectKey);
+        setPreviewRecordId('');
+    }
     const [fetchGeneration, setFetchGeneration] = useState(0);
     const triggerFetch = useCallback(() => {
         setFetchGeneration(prev => prev + 1);
     }, []);
     const previewControls = useMemo(() => ({
-        state: previewObjectKey !== ''
-            ? Object.assign({ object_key: previewObjectKey }, (previewRecordId !== '' ? { record_id: previewRecordId } : {})) : null,
-        setObjectKey: setPreviewObjectKey,
+        state: objectKey == null || objectKey === ''
+            ? null
+            : Object.assign({ object_key: objectKey }, (previewRecordId === '' ? {} : { record_id: previewRecordId })),
         setRecordId: setPreviewRecordId,
         triggerFetch,
         fetchGeneration,
-    }), [previewObjectKey, previewRecordId, triggerFetch, fetchGeneration]);
+    }), [objectKey, previewRecordId, triggerFetch, fetchGeneration]);
     const completeLogin = useCallback((newSession, normalizedBase) => {
         const sessionWithBase = Object.assign(Object.assign({}, newSession), { apiBase: normalizedBase });
         saveSession(sessionWithBase);
@@ -242,7 +251,7 @@ function StandaloneFlow({ apiBase, defaultOrganizationId, objectKey, level, chil
     if (!session || !auth) {
         return (_jsx(LoginForm, { defaultApiBase: apiBase, defaultOrganizationId: defaultOrganizationId, onSubmit: handleLogin, status: status, error: error }));
     }
-    return (_jsx(SfaProvider, { apiBase: activeBase, auth: auth, mode: "direct", organizationId: session.organizationId, onAuthError: handleLogout, children: _jsxs(StandalonePreviewCtx.Provider, { value: previewControls, children: [_jsx(DevToolbar, { organizationId: session.organizationId, preview: previewControls, objectKey: objectKey, level: resolvedLevel, onLogout: handleLogout }), objectKey ? (_jsx(ObjectKeyGuard, { objectKey: objectKey, children: children })) : (children)] }) }));
+    return (_jsx(SfaProvider, { apiBase: activeBase, auth: auth, mode: "direct", organizationId: session.organizationId, onAuthError: handleLogout, children: _jsxs(StandalonePreviewCtx.Provider, { value: previewControls, children: [_jsx(DevToolbar, { organizationId: session.organizationId, preview: previewControls, objectKey: objectKey, level: resolvedLevel, onLogout: handleLogout }, objectKey), objectKey ? (_jsx(ObjectKeyGuard, { objectKey: objectKey, children: children })) : (children)] }) }));
 }
 // ---------------------------------------------------------------------------
 // GENIEE SFA/CRM-branded login form

package/src/lib/auth/StandalonePreviewContext.d.ts

@@ -1,5 +1,6 @@
 /**
- * @description State managed by the DevToolbar in standalone (non-embedded) mode.
+ * @description Preview state in standalone (non-embedded) mode. `object_key`
+ * is SfaLoginGate's `objectKey`; `record_id` is what the DevToolbar submits.
  * Mirrors the shape of EmbedContext so useEmbedContext() can fall back to it.
  */
 export interface StandalonePreviewState {
@@ -9,7 +10,6 @@ export interface StandalonePreviewState {
 }
 export interface StandalonePreviewControls {
     readonly state: StandalonePreviewState | null;
-    readonly setObjectKey: (key: string) => void;
     readonly setRecordId: (id: string) => void;
     readonly triggerFetch: () => void;
     /** Increments on each triggerFetch call so consumers can react. */
@@ -17,7 +17,7 @@ export interface StandalonePreviewControls {
 }
 /**
  * @description React context carrying standalone preview state.
- * Populated only in standalone mode by StandaloneFlow's DevToolbar.
+ * Populated only in standalone mode by StandaloneFlow, for its DevToolbar.
  * useEmbedContext() checks this as a fallback when EmbedContext is null.
  */
 export declare const StandalonePreviewCtx: import("react").Context<StandalonePreviewControls | null>;

package/src/lib/auth/StandalonePreviewContext.js

@@ -1,7 +1,7 @@
 import { createContext, useContext } from 'react';
 /**
  * @description React context carrying standalone preview state.
- * Populated only in standalone mode by StandaloneFlow's DevToolbar.
+ * Populated only in standalone mode by StandaloneFlow, for its DevToolbar.
  * useEmbedContext() checks this as a fallback when EmbedContext is null.
  */
 export const StandalonePreviewCtx = createContext(null);

package/src/lib/auth/useEmbedContext.d.ts

@@ -10,7 +10,9 @@ export declare const EmbedContextValue: import("react").Context<EmbedContext | n
  * active runtime environment. Checks two sources in priority order:
  *
  * 1. Embed context (iframe postMessage flow) - set by the SFA/CRM host.
- * 2. Standalone preview context (DevToolbar) - set by the user in preview mode.
+ * 2. Standalone preview context - set by StandaloneFlow: `object_key` is
+ *    SfaLoginGate's `objectKey`, `record_id` is what the user submits in the
+ *    DevToolbar. It is null when no `objectKey` is passed.
  *
  * Returns null only when neither context is available.
  *

package/src/lib/auth/useEmbedContext.js

@@ -11,7 +11,9 @@ export const EmbedContextValue = createContext(null);
  * active runtime environment. Checks two sources in priority order:
  *
  * 1. Embed context (iframe postMessage flow) - set by the SFA/CRM host.
- * 2. Standalone preview context (DevToolbar) - set by the user in preview mode.
+ * 2. Standalone preview context - set by StandaloneFlow: `object_key` is
+ *    SfaLoginGate's `objectKey`, `record_id` is what the user submits in the
+ *    DevToolbar. It is null when no `objectKey` is passed.
  *
  * Returns null only when neither context is available.
  *

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

@@ -1,17 +1,18 @@
-import type { BundleManifest } from '../signing/types.js';
+import type { BundleManifest, ContentHashManifest } 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.
+     * @deprecated Omit it. The bundle is then signed over `content_hash` alone.
      *
-     * 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.
+     * When given, the bundle is signed in the legacy format, over
+     * `"{studio_version}:{content_hash}"`, and the value is written to the
+     * manifest. Kept so that builds which still pass it keep producing a manifest
+     * with `studio_version`. Keystone accepts both formats.
      */
-    readonly studioVersion: string;
+    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. */
@@ -19,17 +20,32 @@ export interface BuildStaticBundleOptions {
     /** 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.
+     * Extra manifest fields, e.g. `name` or `displayName`. Keystone ignores them.
+     * The fields this builder writes (`content_hash`, `signature`,
+     * `sfa_kit_version` and `studio_version`) cannot be set here.
      */
     readonly manifestExtras?: Readonly<Record<string, unknown>>;
 }
+/**
+ * @deprecated Omit `studioVersion`. Given one, the bundle is signed in the
+ * legacy format, over `"{studio_version}:{content_hash}"`, and the manifest
+ * carries `studio_version` beside `sfa_kit_version`. See the next overload for
+ * everything else this function does.
+ *
+ * NOTE: the order of the three overloads matters, since a call resolves to the
+ * first that matches: a `studioVersion` string here, none next, and one known
+ * only at run time (`string | undefined`) last.
+ */
+export declare function buildStaticBundle(options: BuildStaticBundleOptions & {
+    readonly studioVersion: string;
+}): Promise<BundleManifest & Pick<ContentHashManifest, 'sfa_kit_version'>>;
 /**
  * @description Builds the framework-free static bundle a page is uploaded as
- * to become a custom tab, and signs it.
+ * to become a custom tab, and signs it over `content_hash` alone.
  *
  * 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
+ * `outDir`. The manifest records this package's version as `sfa_kit_version`.
+ * 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`.
  *
@@ -42,4 +58,14 @@ export interface BuildStaticBundleOptions {
  *
  * @returns The manifest that was written.
  */
-export declare function buildStaticBundle({ entry, outDir, studioVersion, apiBase, accessToken, title, manifestExtras, }: BuildStaticBundleOptions): Promise<BundleManifest>;
+export declare function buildStaticBundle(options: BuildStaticBundleOptions & {
+    readonly studioVersion?: undefined;
+}): Promise<ContentHashManifest>;
+/**
+ * For a `studioVersion` known only at run time (`string | undefined`), such as
+ * a forwarded command-line flag. The result is the legacy manifest when one is
+ * given and the current format otherwise, so `studio_version` reads as
+ * `string | undefined`. See the previous overload for everything else this
+ * function does.
+ */
+export declare function buildStaticBundle(options: BuildStaticBundleOptions): Promise<ContentHashManifest | (BundleManifest & Pick<ContentHashManifest, 'sfa_kit_version'>)>;

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

@@ -3,8 +3,9 @@ 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 { SFA_KIT_VERSION } from '../version.js';
 import { loadEsbuild } from './esbuild-loader.js';
-import { requestSignature } from './request-signature.js';
+import { isHexDigest, 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. */
@@ -31,29 +32,23 @@ const UNEXPECTED_SHOWN = 5;
  */
 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.
+ * Manifest keys this builder writes. A caller's `manifestExtras` never set them.
  *
- * 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.
+ * NOTE: `studio_version` is listed even for builds that leave it out. Keystone
+ * checks a manifest carrying one in the legacy format, so an extra holding it
+ * would turn a correctly signed bundle into a 422.
  */
+const OWN_MANIFEST_KEYS = new Set([
+    'studio_version',
+    'sfa_kit_version',
+    'content_hash',
+    'signature',
+]);
 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],
         ]) {
@@ -66,6 +61,11 @@ export function buildStaticBundle(_a) {
                 throw new Error(`${name} is required and must not be empty`);
             }
         }
+        // NOTE: refused rather than read as "omitted". The overloads promise a
+        // manifest carrying studio_version whenever a studioVersion is passed.
+        if (studioVersion != null && studioVersion.trim() === '') {
+            throw new Error('studioVersion must not be empty. Omit it to sign content_hash alone.');
+        }
         // 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);
@@ -90,20 +90,27 @@ export function buildStaticBundle(_a) {
             // 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');
+            const signature = yield requestSignature({
+                apiBase,
+                accessToken,
+                studioVersion,
+                contentHash,
+            });
+            // NOTE: one object per format, not a conditional spread. The current
+            // format must not carry `studio_version` at all (see ContentHashManifest).
+            const manifest = studioVersion == null
+                ? {
+                    sfa_kit_version: SFA_KIT_VERSION,
+                    content_hash: contentHash,
+                    signature,
+                }
+                : {
+                    studio_version: studioVersion,
+                    sfa_kit_version: SFA_KIT_VERSION,
+                    content_hash: contentHash,
+                    signature,
+                };
+            yield writeFile(join(outDir, 'manifest.json'), `${JSON.stringify(Object.assign(Object.assign({}, withoutOwnKeys(manifestExtras)), manifest), null, 2)}\n`, 'utf-8');
             return manifest;
         }
         catch (thrown) {
@@ -118,6 +125,16 @@ export function buildStaticBundle(_a) {
         }
     });
 }
+/**
+ * Drops the keys this builder writes from a caller's extras.
+ *
+ * NOTE: spreading the extras first is not enough. A build without a
+ * studioVersion writes no `studio_version`, so one in the extras would survive
+ * the spread; {@link OWN_MANIFEST_KEYS} says why it must not reach the manifest.
+ */
+function withoutOwnKeys(extras) {
+    return Object.fromEntries(Object.entries(extras).filter(([key]) => !OWN_MANIFEST_KEYS.has(key)));
+}
 /** Fails now on a value `JSON.stringify` would reject after the bundle is signed. */
 function assertSerialisable(extras) {
     try {
@@ -140,8 +157,8 @@ function assertSerialisable(extras) {
  *
  * 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.
+ * and deleting one would be unrecoverable. The manifest is the proof; see
+ * {@link hasOwnManifest} for what counts.
  */
 function prepareOutDir(outDir) {
     return __awaiter(this, void 0, void 0, function* () {
@@ -205,7 +222,24 @@ function prepareOutDir(outDir) {
         yield removeOwnOutput(outDir);
     });
 }
-/** Whether the directory carries a manifest only this builder could have written. */
+/**
+ * @description Whether the directory holds a previous build this builder may
+ * overwrite.
+ *
+ * NOTE: `content_hash` and `signature` alone are not proof. Any signed bundle
+ * carries them, and accepting one would let a rebuild delete another bundle's
+ * files. Each format also needs its version field: `sfa_kit_version` in the
+ * current format, `studio_version` in the legacy one (the condition earlier
+ * releases used).
+ *
+ * Neither field proves this builder wrote the manifest. GUIDE.md's hand-built
+ * flow writes `sfa_kit_version` too, and `createManifest` or a hand-run
+ * equivalent writes `studio_version`. Both identify a bundle built through
+ * sfa-kit, not this builder alone. Nothing in a manifest narrows it further,
+ * and refusing those would block rebuilding over existing output directories.
+ * What is lost is bounded: only the paths in `OWN_OUTPUT` are removed, and any
+ * other file stops the build first.
+ */
 function hasOwnManifest(outDir) {
     return __awaiter(this, void 0, void 0, function* () {
         const raw = yield readFile(join(outDir, 'manifest.json'), 'utf-8').catch(() => null);
@@ -213,13 +247,19 @@ function hasOwnManifest(outDir) {
             return false;
         try {
             const parsed = JSON.parse(raw);
-            return ['studio_version', 'content_hash', 'signature'].every(field => typeof parsed[field] === 'string' && parsed[field] !== '');
+            const hasHexDigests = isHexDigest(parsed['content_hash']) && isHexDigest(parsed['signature']);
+            const hasVersionField = isNonEmptyString(parsed['sfa_kit_version']) ||
+                isNonEmptyString(parsed['studio_version']);
+            return hasHexDigests && hasVersionField;
         }
         catch (_a) {
             return false;
         }
     });
 }
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value !== '';
+}
 /**
  * @description Deletes the files this builder writes, and nothing else.
  *