@geniee-inc/sfa-kit 1.18.0 → 1.19.0

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).
@@ -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.0",
   "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/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.
  *

package/src/lib/bundle/request-signature.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Whether `value` has the shape Keystone gives `content_hash` and `signature`.
+ *
+ * NOTE: shared with the builder's previous-build check, so the shape the
+ * signer accepts and the shape a rebuild recognises cannot drift apart.
+ */
+export declare function isHexDigest(value: unknown): value is string;
 /**
  * @description Asks Keystone to sign a bundle, returning the signature.
  *
@@ -6,6 +13,11 @@
  * per project while the key must be identical across all of them (SFAJAI-186).
  * The caller computes `contentHash` locally and Keystone signs it.
  *
+ * Without `studioVersion`, Keystone signs `contentHash` alone. With it, Keystone
+ * returns the legacy signature over `"{studio_version}:{content_hash}"`, and the
+ * caller must write the same `studio_version` into the manifest for it to
+ * verify.
+ *
  * NOTE: every failure throws. An unsigned bundle uploads successfully while
  * Keystone's verifier runs in `disabled` mode, so returning "no signature" here
  * would produce an artifact that looks fine and starts being rejected the day
@@ -17,6 +29,6 @@
 export declare function requestSignature({ apiBase, accessToken, studioVersion, contentHash, }: {
     readonly apiBase: string;
     readonly accessToken: string;
-    readonly studioVersion: string;
+    readonly studioVersion?: string;
     readonly contentHash: string;
 }): Promise<string>;

package/src/lib/bundle/request-signature.js

@@ -6,6 +6,15 @@ import { __awaiter } from "tslib";
 const HEX_DIGEST_PATTERN = /^[0-9a-f]{64}$/;
 /** Matches the timeout the documented Python flow uses for the same call. */
 const SIGN_TIMEOUT_MS = 30000;
+/**
+ * Whether `value` has the shape Keystone gives `content_hash` and `signature`.
+ *
+ * NOTE: shared with the builder's previous-build check, so the shape the
+ * signer accepts and the shape a rebuild recognises cannot drift apart.
+ */
+export function isHexDigest(value) {
+    return typeof value === 'string' && HEX_DIGEST_PATTERN.test(value);
+}
 /**
  * @description Asks Keystone to sign a bundle, returning the signature.
  *
@@ -14,6 +23,11 @@ const SIGN_TIMEOUT_MS = 30000;
  * per project while the key must be identical across all of them (SFAJAI-186).
  * The caller computes `contentHash` locally and Keystone signs it.
  *
+ * Without `studioVersion`, Keystone signs `contentHash` alone. With it, Keystone
+ * returns the legacy signature over `"{studio_version}:{content_hash}"`, and the
+ * caller must write the same `studio_version` into the manifest for it to
+ * verify.
+ *
  * NOTE: every failure throws. An unsigned bundle uploads successfully while
  * Keystone's verifier runs in `disabled` mode, so returning "no signature" here
  * would produce an artifact that looks fine and starts being rejected the day
@@ -24,7 +38,7 @@ const SIGN_TIMEOUT_MS = 30000;
  */
 export function requestSignature(_a) {
     return __awaiter(this, arguments, void 0, function* ({ apiBase, accessToken, studioVersion, contentHash, }) {
-        if (!HEX_DIGEST_PATTERN.test(contentHash)) {
+        if (!isHexDigest(contentHash)) {
             throw new Error(`content_hash must be a 64-character hex digest, got ${JSON.stringify(contentHash)}`);
         }
         // 末尾のスラッシュを落とす。付いたままだと //v1/pages/sign になり、多くの
@@ -44,10 +58,11 @@ export function requestSignature(_a) {
                 'Content-Type': 'application/json',
                 Authorization: `Bearer ${accessToken}`,
             },
-            body: JSON.stringify({
-                studio_version: studioVersion,
-                content_hash: contentHash,
-            }),
+            // NOTE: the field is left out, not sent empty. Keystone picks the format
+            // by whether studio_version is present, as it does for the manifest.
+            body: JSON.stringify(studioVersion == null
+                ? { content_hash: contentHash }
+                : { studio_version: studioVersion, content_hash: contentHash }),
         })
             .catch((thrown) => {
             throw new Error(`POST ${url} could not be reached ` +
@@ -72,7 +87,7 @@ export function requestSignature(_a) {
         // error page echoed into this field would otherwise be written into
         // manifest.json, upload fine while the verifier is `disabled`, and fail only
         // once it is switched to `enforced`.
-        if (!HEX_DIGEST_PATTERN.test(payload.signature)) {
+        if (!isHexDigest(payload.signature)) {
             throw new Error(`POST ${url} returned ${JSON.stringify(payload.signature)}, which is ` +
                 'not an HMAC-SHA-256 hex digest. The bundle was not signed.');
         }

package/src/lib/components/FieldRenderer.d.ts

@@ -5,7 +5,8 @@ interface FieldRendererProps {
 }
 /**
  * @description Renders a single field value based on its normalized kind.
- * Uses `label` for display (pre-formatted by the API), falls back to `value`.
+ * Uses `label` for display (pre-formatted by the API), falls back to a plain
+ * readable `value` — never a code or an id.
  */
 export declare function FieldRenderer({ fieldValue, fieldName }: FieldRendererProps): JSX.Element;
 export {};

package/src/lib/components/FieldRenderer.js

@@ -1,36 +1,28 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { toFieldDisplayText } from './fieldDisplayText';
 /**
  * @description Renders a single field value based on its normalized kind.
- * Uses `label` for display (pre-formatted by the API), falls back to `value`.
+ * Uses `label` for display (pre-formatted by the API), falls back to a plain
+ * readable `value` — never a code or an id.
  */
 export function FieldRenderer({ fieldValue, fieldName }) {
-    var _a;
-    const display = (_a = fieldValue.label) !== null && _a !== void 0 ? _a : formatFallback(fieldValue);
+    const display = toFieldDisplayText(fieldValue);
+    // NOTE: every branch carries `data-field`, so a page can find a field by name
+    // whatever its value looks like — empty, multi-line or a link
     if (display == null || display === '') {
-        return _jsx("span", { style: styles.empty, children: "\u2014" });
+        return (_jsx("span", { "data-field": fieldName, style: styles.empty, children: "\u2014" }));
     }
     if (fieldValue.kind === 'text' && typeof fieldValue.value === 'string') {
         if (isMultiline(fieldValue.value)) {
-            return _jsx("span", { style: styles.preWrap, children: display });
+            return (_jsx("span", { "data-field": fieldName, style: styles.preWrap, children: display }));
         }
         const link = detectLink(fieldValue.value);
         if (link) {
-            return (_jsx("a", { href: link.href, style: styles.link, target: "_blank", rel: "noopener noreferrer", children: display }));
+            return (_jsx("a", { "data-field": fieldName, href: link.href, style: styles.link, target: "_blank", rel: "noopener noreferrer", children: display }));
         }
     }
     return _jsx("span", { "data-field": fieldName, children: display });
 }
-function formatFallback(field) {
-    if (field.value == null)
-        return null;
-    if (typeof field.value === 'number')
-        return field.value.toLocaleString('ja-JP');
-    if (typeof field.value === 'string')
-        return field.value;
-    if (Array.isArray(field.value))
-        return field.value.join(', ');
-    return String(field.value);
-}
 function isMultiline(value) {
     return value.includes('\n');
 }
@@ -39,10 +31,31 @@ function detectLink(value) {
         return { href: value };
     if (/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value))
         return { href: `mailto:${value}` };
-    if (/^[\d+][\d\-().+\s]{7,}$/.test(value))
-        return { href: `tel:${value.replace(/[\s()-]/g, '')}` };
+    const phoneNumber = toPhoneNumber(value);
+    if (phoneNumber)
+        return { href: `tel:${phoneNumber}` };
     return null;
 }
+/**
+ * The number to dial when `value` reads as a phone number, or null.
+ *
+ * NOTE: digits and dashes alone also make up postal codes (100-0001) and dates
+ * (2026-09-28). A Japanese number starts with a single 0 and has 10 or 11
+ * digits; an international one starts with + and has 8 to 15 (E.164 caps it at
+ * 15). A leading 00 is a zero-padded code, not a number to dial
+ */
+function toPhoneNumber(value) {
+    if (!/^(?:\+|\(?0)[\d\s().-]+$/.test(value))
+        return null;
+    const digits = value.replace(/\D/g, '');
+    if (value.startsWith('+')) {
+        return digits.length >= 8 && digits.length <= 15 ? `+${digits}` : null;
+    }
+    // NOTE: checked on the digits, so separators cannot hide the second 0
+    if (digits.startsWith('00'))
+        return null;
+    return digits.length === 10 || digits.length === 11 ? digits : null;
+}
 const styles = {
     empty: {
         color: '#94a3b8',

package/src/lib/components/RecordList.js

@@ -3,6 +3,7 @@ import { useEffect, useMemo, useRef } from 'react';
 import { useRecordList } from '../hooks/useRecordList';
 import { color, font, radius, space, baseContainerStyle, baseButtonStyle, } from '../theme';
 import { SFA_KIT_VERSION } from '../version';
+import { EmptyState } from './EmptyState';
 import { FetchErrorState } from './FetchErrorState';
 import { FieldRenderer } from './FieldRenderer';
 const MAX_AUTO_COLUMNS = 8;
@@ -26,6 +27,15 @@ export function RecordList({ collection, columns, params, pageSize = 20, showPag
     if (status === 'error') {
         return (_jsxs("div", { style: styles.container, children: [_jsx(FetchErrorState, { message: errorMessage, onRetry: refetch }), _jsxs("div", { style: styles.versionFooter, children: ["@geniee-inc/sfa-kit v", SFA_KIT_VERSION] })] }));
     }
+    // NOTE: on 'idle' nothing was asked — this component never disables the hook,
+    // so it only happens while `collection` is empty. "0 records" and "No records
+    // found" would state something the server never answered, and an empty table
+    // would look broken. Say what is missing instead — the input, not the data —
+    // as RecordView does for a missing record. From here on the status is
+    // 'loading' or 'success', so `!isLoading` means the items came from the server
+    if (status === 'idle') {
+        return (_jsxs("div", { style: styles.container, children: [_jsx(EmptyState, { message: "\u30AA\u30D6\u30B8\u30A7\u30AF\u30C8\u304C\u6307\u5B9A\u3055\u308C\u3066\u3044\u307E\u305B\u3093" }), _jsxs("div", { style: styles.versionFooter, children: ["@geniee-inc/sfa-kit v", SFA_KIT_VERSION] })] }));
+    }
     const resolvedColumns = columns !== null && columns !== void 0 ? columns : autoDetectColumns(items);
     const totalPages = Math.max(1, Math.ceil(totalCount / pageSize));
     const rangeStart = pageIndex * pageSize + 1;

package/src/lib/components/RecordView.js

@@ -3,7 +3,9 @@ import { useEffect, useRef } from 'react';
 import { useRecord } from '../hooks/useRecord';
 import { color, font, radius, space, baseContainerStyle } from '../theme';
 import { SFA_KIT_VERSION } from '../version';
+import { EmptyState } from './EmptyState';
 import { FetchErrorState } from './FetchErrorState';
+import { toFieldDisplayText } from './fieldDisplayText';
 import { FieldRenderer } from './FieldRenderer';
 /**
  * @description Fetches and displays a single SFA/CRM record in a label-value grid.
@@ -11,26 +13,41 @@ import { FieldRenderer } from './FieldRenderer';
 export function RecordView({ collection, recordId, title, fields, fieldGroups, onError, errorMessage, }) {
     var _a;
     const { record, isLoading, error, refetch } = useRecord(collection, recordId);
+    // NOTE: useRecord reports an empty record id as an error so a page using the
+    // hook alone can say so, but to this component it is "no record specified",
+    // not a failed fetch: nothing was sent, and a retry would only repeat it.
+    // The screen and onError both read this, so a page never toasts a failure
+    // next to the "not specified" state
+    const fetchError = recordId === '' ? null : error;
     // Use a ref so inline onError callbacks don't re-fire the effect on
     // every parent render when error is present.
     const onErrorRef = useRef(onError);
     onErrorRef.current = onError;
     useEffect(() => {
         var _a;
-        if (error)
-            (_a = onErrorRef.current) === null || _a === void 0 ? void 0 : _a.call(onErrorRef, error);
-    }, [error]);
-    if (error) {
+        if (fetchError)
+            (_a = onErrorRef.current) === null || _a === void 0 ? void 0 : _a.call(onErrorRef, fetchError);
+    }, [fetchError]);
+    if (fetchError) {
         // NOTE: `title` is the label the page already shows as the heading, so it
         // names the record without exposing `collection` — the object key the API
         // is addressed with. The derived heading is unavailable here: it reads the
         // record, and on a failure there is none.
         return (_jsxs("div", { style: styles.container, children: [_jsx(FetchErrorState, { message: errorMessage !== null && errorMessage !== void 0 ? errorMessage : (title ? `${title}の取得に失敗` : undefined), onRetry: refetch }), _jsxs("div", { style: styles.versionFooter, children: ["@geniee-inc/sfa-kit v", SFA_KIT_VERSION] })] }));
     }
-    if (isLoading || !record) {
+    if (isLoading) {
         return (_jsxs("div", { style: styles.container, children: [_jsx("div", { style: styles.loading, children: "Loading..." }), _jsxs("div", { style: styles.versionFooter, children: ["@geniee-inc/sfa-kit v", SFA_KIT_VERSION] })] }));
     }
-    const displayTitle = (_a = title !== null && title !== void 0 ? title : record.title) !== null && _a !== void 0 ? _a : buildTitle(record.fields, record.titleFields);
+    // NOTE: nothing is loading and no fetch failed, yet there is no record. A
+    // fetch that finds none throws, so this means no record was specified — no
+    // collection or no record id yet. "Loading..." would never go away
+    if (!record) {
+        return (_jsxs("div", { style: styles.container, children: [_jsx(EmptyState, { message: "\u30EC\u30B3\u30FC\u30C9\u304C\u6307\u5B9A\u3055\u308C\u3066\u3044\u307E\u305B\u3093" }), _jsxs("div", { style: styles.versionFooter, children: ["@geniee-inc/sfa-kit v", SFA_KIT_VERSION] })] }));
+    }
+    // NOTE: an empty title from the API names nothing, so build one from
+    // `titleFields` as if it were missing
+    const recordTitle = record.title === '' ? null : record.title;
+    const displayTitle = (_a = title !== null && title !== void 0 ? title : recordTitle) !== null && _a !== void 0 ? _a : buildTitle(record.fields, record.titleFields);
     const hasGroups = fieldGroups && fieldGroups.length > 0;
     return (_jsxs("div", { style: styles.container, children: [displayTitle && _jsx("h2", { style: styles.title, children: displayTitle }), _jsxs("div", { style: styles.meta, children: [collection, " / ", record.record_id] }), hasGroups
                 ? renderFieldGroups(record.fields, fieldGroups)
@@ -65,7 +82,10 @@ function renderFieldGroups(mapping, groups) {
 }
 function buildTitle(mapping, titleFields) {
     return titleFields
-        .map(name => { var _a; return (_a = mapping[name]) === null || _a === void 0 ? void 0 : _a.label; })
+        .map(name => {
+        const field = mapping[name];
+        return field ? toFieldDisplayText(field) : null;
+    })
         .filter(Boolean)
         .join(' ');
 }

package/src/lib/components/fieldDisplayText.d.ts

@@ -0,0 +1,11 @@
+import type { SfaFieldValue } from '../provider/types';
+/**
+ * @description The text a field shows to a reader — its label, or a plain
+ * readable value when the label is empty or missing — or null.
+ *
+ * NOTE: never a code or an id. FieldRenderer and the heading RecordView builds
+ * from `titleFields` both use this, so a field shows the same thing in its row
+ * and in the heading, and a reference whose label is missing puts its raw id
+ * in neither
+ */
+export declare function toFieldDisplayText(field: SfaFieldValue): string | null;

package/src/lib/components/fieldDisplayText.js

@@ -0,0 +1,51 @@
+/**
+ * Kinds whose `value` reads as it is. The others hold a code or an id, and
+ * only `label` names it
+ */
+const READABLE_VALUE_KINDS = new Set([
+    'text',
+    'number',
+    'date',
+    'datetime',
+    'computed',
+]);
+/**
+ * Whether `value` can be shown to a reader as it is: a number, a boolean, or a
+ * string that is not markup
+ *
+ * NOTE: Chikyu also sends kinds it has no mapping for as 'text' — an image
+ * field holds HTML, others may hold an object — so the kind alone does not
+ * promise readable text
+ */
+function isPlainValue(value) {
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return true;
+    return typeof value === 'string' && !/<[a-z!/][^>]*>/i.test(value);
+}
+/**
+ * @description The text a field shows to a reader — its label, or a plain
+ * readable value when the label is empty or missing — or null.
+ *
+ * NOTE: never a code or an id. FieldRenderer and the heading RecordView builds
+ * from `titleFields` both use this, so a field shows the same thing in its row
+ * and in the heading, and a reference whose label is missing puts its raw id
+ * in neither
+ */
+export function toFieldDisplayText(field) {
+    if (field.label != null && field.label !== '')
+        return field.label;
+    // NOTE: an empty or missing label carries no formatting, so a plain readable
+    // value shows instead. Anything else stays empty: a choice or a reference
+    // holds a code or an id (Chikyu leaves the caption out of fields it does not
+    // display, and a master-backed select holds an id), and markup or an object
+    // means nothing to a reader
+    return READABLE_VALUE_KINDS.has(field.kind) && isPlainValue(field.value)
+        ? formatPlainValue(field.value)
+        : null;
+}
+/** A plain value as text: a number formatted for ja-JP, the rest as it is */
+function formatPlainValue(value) {
+    return typeof value === 'number'
+        ? value.toLocaleString('ja-JP')
+        : String(value);
+}

package/src/lib/hooks/useFieldTypes.d.ts

@@ -10,6 +10,11 @@ interface UseFieldTypesResult {
 }
 /**
  * @description Fetches the static field-type catalog from Keystone.
+ *
+ * NOTE: a failed refetch keeps the field types already shown and sets `error`
+ * beside them. The catalog almost never changes, so a transient failure must
+ * not empty the pickers built from it. useRecord drops its record instead: a
+ * record does change, and a stale one would pass for the current one.
  */
 export declare function useFieldTypes(options?: UseFieldTypesOptions): UseFieldTypesResult;
 export {};

package/src/lib/hooks/useFieldTypes.js

@@ -2,6 +2,11 @@ import { useCallback, useEffect, useRef, useState } from 'react';
 import { useSfaClient } from '../provider/useSfaClient';
 /**
  * @description Fetches the static field-type catalog from Keystone.
+ *
+ * NOTE: a failed refetch keeps the field types already shown and sets `error`
+ * beside them. The catalog almost never changes, so a transient failure must
+ * not empty the pickers built from it. useRecord drops its record instead: a
+ * record does change, and a stale one would pass for the current one.
  */
 export function useFieldTypes(options) {
     var _a;

package/src/lib/hooks/useObjectCatalog.d.ts

@@ -10,6 +10,12 @@ interface UseObjectCatalogResult {
 }
 /**
  * @description Fetches the list of all objects available in the org.
+ *
+ * NOTE: a failed refetch keeps the objects already shown and sets `error`
+ * beside them. The catalog almost never changes, so a transient failure must
+ * not empty the object picker built from it. useRecord drops its record
+ * instead: a record does change, and a stale one would pass for the current
+ * one.
  */
 export declare function useObjectCatalog(options?: UseObjectCatalogOptions): UseObjectCatalogResult;
 export {};

package/src/lib/hooks/useObjectCatalog.js

@@ -2,6 +2,12 @@ import { useCallback, useEffect, useRef, useState } from 'react';
 import { useSfaClient } from '../provider/useSfaClient';
 /**
  * @description Fetches the list of all objects available in the org.
+ *
+ * NOTE: a failed refetch keeps the objects already shown and sets `error`
+ * beside them. The catalog almost never changes, so a transient failure must
+ * not empty the object picker built from it. useRecord drops its record
+ * instead: a record does change, and a stale one would pass for the current
+ * one.
  */
 export function useObjectCatalog(options) {
     var _a;

package/src/lib/hooks/useRecord.d.ts

@@ -10,6 +10,26 @@ interface UseRecordResult {
 }
 /**
  * @description Fetches a single record from the SFA/CRM API.
+ *
+ * NOTE: a failed refetch drops the record already shown. A record changes, so
+ * an earlier copy next to the error would pass for the current one and could
+ * be edited from. The catalog hooks keep their data on a failure instead,
+ * because what they hold almost never changes.
+ *
+ * NOTE: an empty `collection` means there is nothing to ask yet — the embed
+ * context has not arrived, say — and is treated like `enabled: false`: no
+ * request and no error. An error would flash on every page that is still
+ * waiting, and useRecordList and useDescribe stay idle the same way. An empty
+ * `recordId` with a collection given is different, and does set `error`: the
+ * object is known but no record is picked, which the message asks the reader to
+ * fix, and an empty id that reached the API was answered with a 503.
+ *
+ * NOTE: the result always describes the `collection` / `recordId` / client
+ * passed right now. When they change, the state still answers the old ones
+ * until the fetch for the new ones starts, so it reports no record and no
+ * error — with `isLoading` when a fetch is due — instead of the old answer,
+ * the way useRecordList reports 'loading' before its fetch settles. Disabling
+ * without changing them keeps the record already fetched.
  */
 export declare function useRecord(collection: string, recordId: string, options?: UseRecordOptions): UseRecordResult;
 export {};

package/src/lib/hooks/useRecord.js

@@ -4,6 +4,26 @@ import { ERR_EMPTY_RECORD_ID } from '../errors';
 import { useSfaClient } from '../provider/useSfaClient';
 /**
  * @description Fetches a single record from the SFA/CRM API.
+ *
+ * NOTE: a failed refetch drops the record already shown. A record changes, so
+ * an earlier copy next to the error would pass for the current one and could
+ * be edited from. The catalog hooks keep their data on a failure instead,
+ * because what they hold almost never changes.
+ *
+ * NOTE: an empty `collection` means there is nothing to ask yet — the embed
+ * context has not arrived, say — and is treated like `enabled: false`: no
+ * request and no error. An error would flash on every page that is still
+ * waiting, and useRecordList and useDescribe stay idle the same way. An empty
+ * `recordId` with a collection given is different, and does set `error`: the
+ * object is known but no record is picked, which the message asks the reader to
+ * fix, and an empty id that reached the API was answered with a 503.
+ *
+ * NOTE: the result always describes the `collection` / `recordId` / client
+ * passed right now. When they change, the state still answers the old ones
+ * until the fetch for the new ones starts, so it reports no record and no
+ * error — with `isLoading` when a fetch is due — instead of the old answer,
+ * the way useRecordList reports 'loading' before its fetch settles. Disabling
+ * without changing them keeps the record already fetched.
  */
 export function useRecord(collection, recordId, options) {
     var _a;
@@ -13,9 +33,19 @@ export function useRecord(collection, recordId, options) {
     const [isLoading, setIsLoading] = useState(enabled && !!collection && !!recordId);
     const [error, setError] = useState(null);
     const fetchId = useRef(0);
+    // NOTE: which inputs the state above answers. Set whenever doFetch starts
+    // answering a new question, so a render can tell the state is about inputs
+    // that are no longer passed
+    const answeredRef = useRef(null);
     const doFetch = useCallback(() => __awaiter(this, void 0, void 0, function* () {
         if (!enabled || !collection)
             return;
+        const answered = answeredRef.current;
+        const isNewQuestion = answered == null ||
+            answered.client !== client ||
+            answered.collection !== collection ||
+            answered.recordId !== recordId;
+        answeredRef.current = { client, collection, recordId };
         if (!recordId) {
             fetchId.current += 1;
             setRecord(null);
@@ -25,6 +55,10 @@ export function useRecord(collection, recordId, options) {
         }
         fetchId.current += 1;
         const currentFetchId = fetchId.current;
+        // NOTE: a refetch of the same record keeps it on screen while it loads; a
+        // record answering other inputs must not stand in for the new one
+        if (isNewQuestion)
+            setRecord(null);
         setIsLoading(true);
         setError(null);
         try {
@@ -45,5 +79,24 @@ export function useRecord(collection, recordId, options) {
     useEffect(() => {
         doFetch();
     }, [doFetch]);
+    const answered = answeredRef.current;
+    const answersCurrentInputs = answered != null &&
+        answered.client === client &&
+        answered.collection === collection &&
+        answered.recordId === recordId;
+    // NOTE: the state answers other inputs — the fetch for these has not started
+    // yet, or nothing will be asked (no collection, or disabled after the inputs
+    // changed). Either way the old record and error answer something else. It
+    // is loading only when a fetch is due; an empty record id gets its error from
+    // the effect. Disabling without changing the inputs keeps what was fetched,
+    // as useRecordList does
+    if (!answersCurrentInputs) {
+        return {
+            record: null,
+            isLoading: enabled && !!collection && !!recordId,
+            error: null,
+            refetch: doFetch,
+        };
+    }
     return { record, isLoading, error, refetch: doFetch };
 }

package/src/lib/signing/compute-signature.d.ts

@@ -2,7 +2,9 @@
  * Computes the HMAC-SHA-256 bundle signature matching Keystone's
  * BundleSignatureVerifier.
  *
- * Signs the message `"{studioVersion}:{contentHash}"` with the given key.
+ * Signs the message `"{studioVersion}:{contentHash}"` with the given key. This
+ * is the legacy format; a manifest without `studio_version` is checked
+ * against `contentHash` alone (see `ContentHashManifest`).
  *
  * **The signing key lives only in Keystone (`KEYSTONE_STUDIO__SIGNING_KEY`),
  * so a page build cannot call this.** Deploying the key to Studio as well was
@@ -13,7 +15,7 @@
  * ```ts
  * const files = await readBundleFiles('dist');
  * const contentHash = computeContentHash(files);
- * // POST /v1/pages/sign { studio_version, content_hash } -> { signature }
+ * // POST /v1/pages/sign { content_hash } -> { signature }
  * ```
  *
  * Reach for this only from a service that legitimately holds the key. Signing

package/src/lib/signing/compute-signature.js

@@ -3,7 +3,9 @@ import { createHmac } from 'node:crypto';
  * Computes the HMAC-SHA-256 bundle signature matching Keystone's
  * BundleSignatureVerifier.
  *
- * Signs the message `"{studioVersion}:{contentHash}"` with the given key.
+ * Signs the message `"{studioVersion}:{contentHash}"` with the given key. This
+ * is the legacy format; a manifest without `studio_version` is checked
+ * against `contentHash` alone (see `ContentHashManifest`).
  *
  * **The signing key lives only in Keystone (`KEYSTONE_STUDIO__SIGNING_KEY`),
  * so a page build cannot call this.** Deploying the key to Studio as well was
@@ -14,7 +16,7 @@ import { createHmac } from 'node:crypto';
  * ```ts
  * const files = await readBundleFiles('dist');
  * const contentHash = computeContentHash(files);
- * // POST /v1/pages/sign { studio_version, content_hash } -> { signature }
+ * // POST /v1/pages/sign { content_hash } -> { signature }
  * ```
  *
  * Reach for this only from a service that legitimately holds the key. Signing

package/src/lib/signing/create-manifest.d.ts

@@ -2,15 +2,17 @@ import type { BundleManifest, FileEntry } from './types.js';
 /**
  * Creates a signed {@link BundleManifest} from a list of bundle files.
  *
- * Returns the three fields Keystone's BundleSignatureVerifier requires.
- * Callers can spread decorative fields (e.g. `sfaKitVersion` for the npm
- * package version, `name`, `displayName`) on top before writing to disk.
+ * Returns the three fields of the legacy format, signed over
+ * `"{studio_version}:{content_hash}"`. Callers can spread decorative fields
+ * (e.g. `name`, `displayName`) on top before writing to disk.
  *
  * **Requires the shared signing key, which page builds do not have** — see
  * {@link computeSignature}. A page build computes `content_hash` with
- * {@link computeContentHash} and gets the signature from Keystone's
- * `POST /v1/pages/sign`, then writes the three fields as a
- * {@link BundleManifest} literal.
+ * {@link computeContentHash}, posts it alone to Keystone's
+ * `POST /v1/pages/sign`, and writes the current format, a
+ * `ContentHashManifest` (see GUIDE.md). It does not write `studio_version`:
+ * Keystone checks a manifest carrying one in this legacy format, so a signature
+ * over `content_hash` alone would not verify.
  *
  * @param studioVersion - Studio version stored as page metadata.
  * @param files - All files in the bundle (manifest.json is automatically excluded).

package/src/lib/signing/create-manifest.js

@@ -3,15 +3,17 @@ import { computeSignature } from './compute-signature.js';
 /**
  * Creates a signed {@link BundleManifest} from a list of bundle files.
  *
- * Returns the three fields Keystone's BundleSignatureVerifier requires.
- * Callers can spread decorative fields (e.g. `sfaKitVersion` for the npm
- * package version, `name`, `displayName`) on top before writing to disk.
+ * Returns the three fields of the legacy format, signed over
+ * `"{studio_version}:{content_hash}"`. Callers can spread decorative fields
+ * (e.g. `name`, `displayName`) on top before writing to disk.
  *
  * **Requires the shared signing key, which page builds do not have** — see
  * {@link computeSignature}. A page build computes `content_hash` with
- * {@link computeContentHash} and gets the signature from Keystone's
- * `POST /v1/pages/sign`, then writes the three fields as a
- * {@link BundleManifest} literal.
+ * {@link computeContentHash}, posts it alone to Keystone's
+ * `POST /v1/pages/sign`, and writes the current format, a
+ * `ContentHashManifest` (see GUIDE.md). It does not write `studio_version`:
+ * Keystone checks a manifest carrying one in this legacy format, so a signature
+ * over `content_hash` alone would not verify.
  *
  * @param studioVersion - Studio version stored as page metadata.
  * @param files - All files in the bundle (manifest.json is automatically excluded).

package/src/lib/signing/index.d.ts

@@ -1,4 +1,4 @@
-export type { BundleManifest, FileEntry } from './types.js';
+export type { BundleManifest, FileEntry, ContentHashManifest, } from './types.js';
 export { computeContentHash } from './compute-content-hash.js';
 export { readBundleFiles } from './read-bundle-files.js';
 export { computeSignature } from './compute-signature.js';

package/src/lib/signing/types.d.ts

@@ -1,8 +1,9 @@
 /**
- * The three fields Keystone's BundleSignatureVerifier reads from
- * manifest.json. Callers can spread decorative fields on top before
- * writing to disk (e.g. `sfaKitVersion` for the npm package version,
- * `name`, `displayName`, `entry`).
+ * The legacy manifest format: the signature covers
+ * `"{studio_version}:{content_hash}"`. Keystone still accepts it, and
+ * {@link createManifest} and `buildStaticBundle` given a `studioVersion` still
+ * produce it. Callers can spread decorative fields on top before writing to
+ * disk (e.g. `name`, `displayName`, `entry`).
  */
 export interface BundleManifest {
     /** Studio version string (the build version, not the sfa-kit npm version). */
@@ -12,6 +13,34 @@ export interface BundleManifest {
     /** HMAC-SHA-256 hex of `"{studio_version}:{content_hash}"`. */
     signature: string;
 }
+/**
+ * The manifest `buildStaticBundle` writes when no `studioVersion` is given.
+ *
+ * Keystone reads a manifest without `studio_version` as this format and checks
+ * the signature against `content_hash` alone. `content_hash` covers every
+ * other file in the bundle, so that is what makes an edited bundle fail.
+ */
+export interface ContentHashManifest {
+    /**
+     * The sfa-kit version that ran the build. Not signed: Keystone stores it for
+     * troubleshooting only.
+     *
+     * NOTE: this is the copy of sfa-kit that ran the bundler. esbuild bundles
+     * whichever copy the entry module imports, which is normally the same one,
+     * but a project with two installed copies can bundle the other.
+     */
+    sfa_kit_version: string;
+    /** SHA-256 hex digest of all non-manifest file contents. */
+    content_hash: string;
+    /** HMAC-SHA-256 hex of `content_hash`. */
+    signature: string;
+    /**
+     * Never present in this format. Keystone picks the format by whether the
+     * manifest carries `studio_version`, so one that does is a legacy
+     * {@link BundleManifest}, not this.
+     */
+    studio_version?: never;
+}
 /** A single file in the bundle, used for content hash computation. */
 export interface FileEntry {
     /** Relative path using forward slashes (e.g. "index.html", "assets/bundle.js"). */

package/src/lib/version.d.ts

@@ -1 +1 @@
-export declare const SFA_KIT_VERSION = "1.18.0";
+export declare const SFA_KIT_VERSION = "1.19.0";

package/src/lib/version.js

@@ -1,3 +1,3 @@
 // このファイルは libs/sfa-kit/scripts/sync-version.cjs が生成する。
 // 手で編集しないこと。バージョンを上げるときは libs/sfa-kit/package.json を変更する。
-export const SFA_KIT_VERSION = '1.18.0';
+export const SFA_KIT_VERSION = '1.19.0';

package/src/signing.d.ts

@@ -14,10 +14,10 @@
  * import { readBundleFiles, computeContentHash } from '@geniee-inc/sfa-kit/signing';
  *
  * const contentHash = computeContentHash(await readBundleFiles('./dist'));
- * // POST /v1/pages/sign { studio_version, content_hash } -> { signature }
+ * // POST /v1/pages/sign { content_hash } -> { signature }
  * ```
  *
  * @packageDocumentation
  */
-export type { BundleManifest, FileEntry } from './lib/signing/index.js';
+export type { BundleManifest, FileEntry, ContentHashManifest, } from './lib/signing/index.js';
 export { computeContentHash, readBundleFiles, computeSignature, createManifest, createManifestFromDirectory, } from './lib/signing/index.js';