@scrymore/scry-deployer 0.10.0-next.20260929163821 → 0.10.0

package/bin/cli.js

@@ -7,7 +7,7 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const { zipDirectory } = require('../lib/archive.js');
-const { getApiClient, uploadBuild } = require('../lib/apiClient.js');
+const { getApiClient, uploadBuild, sanitizeServerText } = require('../lib/apiClient.js');
 const { createLogger } = require('../lib/logger.js');
 const { ApiError } = require('../lib/errors.js');
 const { loadConfig } = require('../lib/config.js');
@@ -610,30 +610,43 @@ function reportIndexingOutcome({ argv, analysis, uploadResult, emptyArchive, sbc
     return reportNoMetadataProduced(sbcovFailure, logger);
 }
 
+/** The parsed argv of the running command (set by middleware); handleError reads --verbose from it. */
+let currentArgv = {};
+
+/**
+ * The one place every CLI failure ends. Prints a one-line human message, the
+ * `Ref: <id>` of the failing response (when it had one) and a suggestion;
+ * reports to Sentry (tagged with the request id) and flushes before exiting
+ * non-zero. The stack is printed only with --verbose.
+ */
 async function handleError(error, argv) {
     const logger = createLogger(argv || {});
-    logger.error(`\n❌ Error: ${error.message}`);
-
-    // Report with an allowlisted subset of argv. Sending argv wholesale shipped
-    // the customer's --api-key to Sentry on every error.
-    captureCliError(error, argv);
-
-    // Ensure the event is sent before the process exits
-    await flushTelemetry(2000);
-
-    if (error instanceof ApiError) {
-        if (error.requestId) logger.error(`Ref: ${error.requestId}`);
-        if (error.statusCode === 401) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    // Strip server-provided control sequences, and never echo the API key.
+    let message = sanitizeServerText(err.message || 'Unknown error', 400);
+    const key = argv && (argv.apiKey || argv['api-key']);
+    if (typeof key === 'string' && key.length >= 4) message = message.split(key).join('<redacted>');
+    logger.error(`\n\u274c Error: ${message}`);
+
+    if (err instanceof ApiError) {
+        if (err.requestId) logger.error(`Ref: ${sanitizeServerText(err.requestId, 64)}`);
+        if (err.statusCode === 401) {
             logger.error('Suggestion: Check that your API key is correct and has not expired.');
-        } else if (error.statusCode >= 500) {
+        } else if (err.statusCode >= 500) {
             logger.error('Suggestion: This seems to be a server-side issue. Please try again later or contact support.');
         }
     }
 
-    if (argv && argv.verbose && error.stack) {
-        logger.debug(error.stack);
+    if (argv && argv.verbose && err.stack) {
+        logger.debug(err.stack);
     }
 
+    // Report with an allowlisted subset of argv. Sending argv wholesale shipped
+    // the customer's --api-key to Sentry on every error.
+    captureCliError(err, argv);
+    // Ensure the event is sent before the process exits
+    try { await flushTelemetry(2000); } catch { /* telemetry must never mask the real error */ }
+
     process.exit(1);
 }
 
@@ -646,6 +659,17 @@ async function main() {
         // The command handlers registered below do all the work; the parsed argv itself
         // (yargs' .parse() resolution) is never needed here.
         await yargs(hideBin(process.argv))
+            // Every failure surfaces as a rejection of parseAsync (below), handled by handleError;
+            // yargs must not print usage + a raw error and exit on its own. Usage errors (no Error
+            // object, e.g. a bad option) keep yargs' help output.
+            .exitProcess(false)
+            .fail((msg, err, y) => {
+                if (err) throw err;
+                y.showHelp('error');
+                console.error(`\n${msg}`);
+                process.exit(1);
+            })
+            .middleware((a) => { currentArgv = a; })
             .command('$0', 'Deploy Storybook static build', (yargs) => {
                 return yargs
                     .option('dir', {
@@ -1100,10 +1124,10 @@ async function main() {
             .help()
             .alias('help', 'h')
             .version(false)  // Disable built-in version since we use -v for deploy-version
-            .parse();
+            .parseAsync();
 
     } catch (error) {
-        await handleError(error, error.config || {});
+        await handleError(error, currentArgv);
     }
 }
 

package/lib/vendor/scf/VERSION

@@ -1 +1 @@
-290890e25589fb329a3052e32215ef3096683035
+ff1be9eada71eb4343cf5ead2c53317671f1b413

package/lib/vendor/scf/cli.js

@@ -8,9 +8,15 @@ function printHuman(target, result) {
     else {
         console.log(`FAIL  ${target}`);
     }
+    const issueLocation = (i) => {
+        if (i.id)
+            return ` [${i.id}]`;
+        if (i.path)
+            return ` [${i.path}]`;
+        return '';
+    };
     const printIssue = (prefix) => (i) => {
-        const loc = i.id ? ` [${i.id}]` : i.path ? ` [${i.path}]` : '';
-        console.log(`  ${prefix} ${i.code}${loc}: ${i.message}`);
+        console.log(`  ${prefix} ${i.code}${issueLocation(i)}: ${i.message}`);
     };
     result.errors.forEach(printIssue('error'));
     result.warnings.forEach(printIssue('warn '));
@@ -47,3 +53,4 @@ main()
     console.error(err instanceof Error ? err.message : String(err));
     process.exitCode = 1;
 });
+//# sourceMappingURL=cli.js.map

package/lib/vendor/scf/from-sbcov.d.ts

@@ -1,9 +1,4 @@
 import type { ScfManifest } from './types.js';
-/** Mirrors Storybook's `toId(kind, name)` closely enough to reproduce the same identity that the
- *  dashboard's suggest feature already derives from `storyTitle` + `testName` when no `storyId`
- *  field is present in metadata.json (the normal case — see search-api-client.ts:208-228). This id
- *  is for capture identity only; the legacy storage key stays `basename(screenshotPath)` (contract §3,
- *  guarantee G1), so byte-identical web rows do not depend on this function. */
 export declare function toStorybookId(title: string, name: string): string;
 /**
  * Converts a legacy sbcov `metadata.json` (+ optional `sbcov-manifest.json`) into an SCF 1.0

package/lib/vendor/scf/from-sbcov.js

@@ -8,12 +8,23 @@ const ID_SANITIZE_RE = /[ ,'’()!@#$%^&*+=<>{}[\]|\\;:/?.]+/g;
  *  field is present in metadata.json (the normal case — see search-api-client.ts:208-228). This id
  *  is for capture identity only; the legacy storage key stays `basename(screenshotPath)` (contract §3,
  *  guarantee G1), so byte-identical web rows do not depend on this function. */
+/** Trims leading/trailing `-` without a regex anchored on `$`, which sonarjs flags as
+ *  super-linear: an unanchored quantifier run ending in a literal that never matches the
+ *  string's actual end backtracks once per run position (O(n^2) on adversarial input). */
+function trimDashes(value) {
+    let start = 0;
+    let end = value.length;
+    while (start < end && value[start] === '-')
+        start++;
+    while (end > start && value[end - 1] === '-')
+        end--;
+    return value.slice(start, end);
+}
 export function toStorybookId(title, name) {
-    const sanitize = (value) => value
+    const sanitize = (value) => trimDashes(value
         .toLowerCase()
         .replace(ID_SANITIZE_RE, '-')
-        .replace(/-+/g, '-')
-        .replace(/^-+|-+$/g, '');
+        .replace(/-+/g, '-'));
     const kind = sanitize(title || 'unknown');
     const leaf = name ? sanitize(name) : '';
     return leaf ? `${kind}--${leaf}` : kind;
@@ -114,3 +125,4 @@ export function fromSbcov(metadataJson, manifestJson) {
     }
     return result;
 }
+//# sourceMappingURL=from-sbcov.js.map

package/lib/vendor/scf/from-sidecars.js

@@ -19,3 +19,4 @@ export function fromSidecars(files, sourceKind = 'upload') {
         captures,
     };
 }
+//# sourceMappingURL=from-sidecars.js.map

package/lib/vendor/scf/image-dimensions.d.ts

@@ -1,3 +1,4 @@
+import type { BundleFileMeasured } from './types.js';
 /**
  * Reads pixel width/height straight from an image's header — never decodes pixels — so the
  * validator can enforce the spec's "at most 16384 px on the longest side" without pulling in an
@@ -16,4 +17,61 @@ export interface ImageDimensions {
 }
 /** Best-effort header-only dimension read for the three formats SCF allows. */
 export declare function readImageDimensions(bytes: Uint8Array, family: 'png' | 'jpeg' | 'webp'): ImageDimensions | null;
+export type ImageFamily = 'png' | 'jpeg' | 'webp';
+/** Sniffs the magic bytes to tell which of the three SCF-allowed image formats `bytes` is, so a
+ *  `.png` with the wrong content (or vice versa) is still caught. Moved here (from `validate.ts`)
+ *  so `measureImage` below can use it without a circular import; re-exported from `validate.ts` for
+ *  callers that only need family detection (e.g. a `{head, size}` image entry's magic-byte check). */
+export declare function detectImageFamily(bytes: Uint8Array): ImageFamily | null;
+export interface MeasuredImage extends ImageDimensions {
+    family: ImageFamily;
+}
+/**
+ * The recommended cap on how large a `prefixBytes` a streaming caller should ever accumulate before
+ * giving up on `measureImage` and treating the image as unmeasurable (ledger F69). PNG's IHDR is
+ * always in the first 24 bytes and WebP's header in the first ~30, so this bound is really about
+ * JPEG: a real photo's SOF0/SOF2 marker is essentially always within a few KiB, but a JPEG can
+ * legally carry a large APPn/EXIF segment (an embedded thumbnail, ICC profile, XMP block) before its
+ * first SOF marker. 64 KiB comfortably covers realistic EXIF payloads while keeping the *transient*
+ * per-image buffer a streaming caller holds — never the persisted record — small and bounded.
+ */
+export declare const MEASURE_IMAGE_MAX_PREFIX_BYTES: number;
+/**
+ * Combines magic-byte family detection with a header-only dimension read into the one call a
+ * memory-bounded streaming reader needs (ledger F69: F32/F60's fixes still left the IMAGE member
+ * category exposed to the same "keep it all in memory" problem — an 8,000-entry bundle of honest,
+ * individually-tiny images could still retain ~500 MB via the old `{head, size}` shape, since a
+ * `{head, size}` entry whose real size is under the head cap retains the WHOLE image). A caller
+ * streaming a large bundle should feed this whatever *prefix* of an image's real decompressed bytes
+ * it has accumulated so far (never the whole file) — this function is a pure, stateless read of
+ * whatever prefix you hand it, so calling it again as more bytes arrive (up to
+ * `MEASURE_IMAGE_MAX_PREFIX_BYTES`, or once the entry finishes if it's smaller than that) is always
+ * safe and cheap; there is no separate "streaming" API to construct or tear down.
+ *
+ * Once this returns a non-null result (or the caller has accumulated `MEASURE_IMAGE_MAX_PREFIX_BYTES`
+ * and it's still null), the caller should discard the prefix buffer entirely and retain only the
+ * small `{family, width, height}` record plus the image's real total size — never the bytes
+ * themselves. That's the whole point: peak memory per image, beyond that small fixed record, is
+ * bounded by this function's own bounded input, not by how many images (or how large any one of
+ * them) the bundle contains.
+ *
+ * Returns null when the family can't be identified from the bytes present, OR when the family is
+ * known but the dimensions can't be read from this prefix (truncated/corrupt content, a WebP variant
+ * this parser doesn't cover, or — for JPEG — a real SOF marker that never showed up within the
+ * prefix a caller was willing to buffer). Both failure modes collapse to the same `null` on purpose:
+ * a caller holding only a bounded prefix has no bytes left over to tell "not a valid image" apart
+ * from "couldn't read far enough into a valid one" once that prefix is discarded, and a `{measured}`
+ * record built from a `null` result is rejected the same way either way (see `validate.ts`'s
+ * `IMAGE_FORMAT_INVALID` handling for a `{measured}` entry).
+ */
+export declare function measureImage(prefixBytes: Uint8Array): MeasuredImage | null;
+/**
+ * Ledger F126 (G7): builds the `{measured: true, ...}` record a streaming caller hands `validateBundle`
+ * from a bounded prefix. Unlike `measureImage` (which collapses "wrong format" and "right format,
+ * header unreadable" into `null`), this KEEPS the detected family when the dimensions cannot be read
+ * (`width`/`height` 0), so `validateBundle` reports IMAGE_HEADER_UNREADABLE for a truncated header,
+ * exactly like the directory/CLI path, instead of IMAGE_FORMAT_INVALID. Use this, not `measureImage`,
+ * in any streaming reader (upload route, build processing).
+ */
+export declare function measureImageRecord(prefixBytes: Uint8Array, size: number): BundleFileMeasured;
 //# sourceMappingURL=image-dimensions.d.ts.map

package/lib/vendor/scf/image-dimensions.js

@@ -1,15 +1,3 @@
-/**
- * Reads pixel width/height straight from an image's header — never decodes pixels — so the
- * validator can enforce the spec's "at most 16384 px on the longest side" without pulling in an
- * image-decoding dependency (which would also break "zero runtime deps"). A tiny file can still
- * declare an enormous canvas (PNG/JPEG/WebP all compress a large solid-colour image well under the
- * 20 MB byte cap), which is a resource-exhaustion risk for whatever decodes it later (thumbnailing,
- * pixel diff) — see ledger F25.
- *
- * Returns null when the format can't be determined (truncated/corrupt file, or a WebP variant this
- * parser doesn't recognise) rather than guessing; callers should not error on null, only on a
- * confirmed over-limit size.
- */
 function pngDimensions(bytes) {
     // Signature (8) + chunk length (4) + "IHDR" (4) + width (4) + height (4) = 24 bytes minimum.
     if (bytes.length < 24)
@@ -92,3 +80,88 @@ export function readImageDimensions(bytes, family) {
         return jpegDimensions(bytes);
     return webpDimensions(bytes);
 }
+/** Sniffs the magic bytes to tell which of the three SCF-allowed image formats `bytes` is, so a
+ *  `.png` with the wrong content (or vice versa) is still caught. Moved here (from `validate.ts`)
+ *  so `measureImage` below can use it without a circular import; re-exported from `validate.ts` for
+ *  callers that only need family detection (e.g. a `{head, size}` image entry's magic-byte check). */
+export function detectImageFamily(bytes) {
+    if (bytes.length >= 4 && bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47) {
+        return 'png';
+    }
+    if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) {
+        return 'jpeg';
+    }
+    if (bytes.length >= 12 &&
+        bytes[0] === 0x52 &&
+        bytes[1] === 0x49 &&
+        bytes[2] === 0x46 &&
+        bytes[3] === 0x46 &&
+        bytes[8] === 0x57 &&
+        bytes[9] === 0x45 &&
+        bytes[10] === 0x42 &&
+        bytes[11] === 0x50) {
+        return 'webp';
+    }
+    return null;
+}
+/**
+ * The recommended cap on how large a `prefixBytes` a streaming caller should ever accumulate before
+ * giving up on `measureImage` and treating the image as unmeasurable (ledger F69). PNG's IHDR is
+ * always in the first 24 bytes and WebP's header in the first ~30, so this bound is really about
+ * JPEG: a real photo's SOF0/SOF2 marker is essentially always within a few KiB, but a JPEG can
+ * legally carry a large APPn/EXIF segment (an embedded thumbnail, ICC profile, XMP block) before its
+ * first SOF marker. 64 KiB comfortably covers realistic EXIF payloads while keeping the *transient*
+ * per-image buffer a streaming caller holds — never the persisted record — small and bounded.
+ */
+export const MEASURE_IMAGE_MAX_PREFIX_BYTES = 64 * 1024;
+/**
+ * Combines magic-byte family detection with a header-only dimension read into the one call a
+ * memory-bounded streaming reader needs (ledger F69: F32/F60's fixes still left the IMAGE member
+ * category exposed to the same "keep it all in memory" problem — an 8,000-entry bundle of honest,
+ * individually-tiny images could still retain ~500 MB via the old `{head, size}` shape, since a
+ * `{head, size}` entry whose real size is under the head cap retains the WHOLE image). A caller
+ * streaming a large bundle should feed this whatever *prefix* of an image's real decompressed bytes
+ * it has accumulated so far (never the whole file) — this function is a pure, stateless read of
+ * whatever prefix you hand it, so calling it again as more bytes arrive (up to
+ * `MEASURE_IMAGE_MAX_PREFIX_BYTES`, or once the entry finishes if it's smaller than that) is always
+ * safe and cheap; there is no separate "streaming" API to construct or tear down.
+ *
+ * Once this returns a non-null result (or the caller has accumulated `MEASURE_IMAGE_MAX_PREFIX_BYTES`
+ * and it's still null), the caller should discard the prefix buffer entirely and retain only the
+ * small `{family, width, height}` record plus the image's real total size — never the bytes
+ * themselves. That's the whole point: peak memory per image, beyond that small fixed record, is
+ * bounded by this function's own bounded input, not by how many images (or how large any one of
+ * them) the bundle contains.
+ *
+ * Returns null when the family can't be identified from the bytes present, OR when the family is
+ * known but the dimensions can't be read from this prefix (truncated/corrupt content, a WebP variant
+ * this parser doesn't cover, or — for JPEG — a real SOF marker that never showed up within the
+ * prefix a caller was willing to buffer). Both failure modes collapse to the same `null` on purpose:
+ * a caller holding only a bounded prefix has no bytes left over to tell "not a valid image" apart
+ * from "couldn't read far enough into a valid one" once that prefix is discarded, and a `{measured}`
+ * record built from a `null` result is rejected the same way either way (see `validate.ts`'s
+ * `IMAGE_FORMAT_INVALID` handling for a `{measured}` entry).
+ */
+export function measureImage(prefixBytes) {
+    const family = detectImageFamily(prefixBytes);
+    if (!family)
+        return null;
+    const dims = readImageDimensions(prefixBytes, family);
+    if (!dims)
+        return null;
+    return { family, width: dims.width, height: dims.height };
+}
+/**
+ * Ledger F126 (G7): builds the `{measured: true, ...}` record a streaming caller hands `validateBundle`
+ * from a bounded prefix. Unlike `measureImage` (which collapses "wrong format" and "right format,
+ * header unreadable" into `null`), this KEEPS the detected family when the dimensions cannot be read
+ * (`width`/`height` 0), so `validateBundle` reports IMAGE_HEADER_UNREADABLE for a truncated header,
+ * exactly like the directory/CLI path, instead of IMAGE_FORMAT_INVALID. Use this, not `measureImage`,
+ * in any streaming reader (upload route, build processing).
+ */
+export function measureImageRecord(prefixBytes, size) {
+    const family = detectImageFamily(prefixBytes);
+    const dims = family ? readImageDimensions(prefixBytes, family) : null;
+    return { measured: true, family, width: dims?.width ?? 0, height: dims?.height ?? 0, size };
+}
+//# sourceMappingURL=image-dimensions.js.map

package/lib/vendor/scf/index.d.ts

@@ -2,10 +2,13 @@
  * @scrymore/scf — the Scry Capture Format 1.0 validator and converters.
  * Zero runtime dependencies; safe to vendor into a Worker or a Node service (see repo README).
  */
-export { validateBundle } from './validate.js';
+export { validateBundle, checkStructureMember, checkSourceTextMember } from './validate.js';
 export { fromSbcov, toStorybookId } from './from-sbcov.js';
 export { fromSidecars } from './from-sidecars.js';
 export { storageKey, companionKey, sourceKeyOf } from './storage-key.js';
 export { sha256Hex } from './sha256.js';
-export type { BundleFiles, CaptureBlock, CaptureCode, CaptureCrop, CaptureFlow, CaptureKind, CaptureLinks, CaptureMethod, CaptureSourceText, CaptureStructure, CaptureVariant, DeviceRef, ScfCapture, ScfCounts, ScfManifest, ScfRepository, ScfSource, ScfTree, ScfTreeNode, Severity, SkipReason, StructureOrigin, ValidationIssue, ValidationResult, } from './types.js';
+export { bundleFileFull, bundleFileHead, bundleFileSize, isCheckedBundleFile, isMeasuredBundleFile } from './types.js';
+export { detectImageFamily, measureImage, measureImageRecord, readImageDimensions, MEASURE_IMAGE_MAX_PREFIX_BYTES } from './image-dimensions.js';
+export type { ImageFamily, MeasuredImage } from './image-dimensions.js';
+export type { BundleFileBytes, BundleFileChecked, BundleFileHeadAndSize, BundleFileMeasured, BundleFiles, CaptureBlock, CaptureCode, CaptureCrop, CaptureFlow, CaptureKind, CaptureLinks, CaptureMethod, CaptureSourceText, CaptureStructure, CaptureVariant, DeviceRef, ScfCapture, ScfCounts, ScfManifest, ScfRepository, ScfSource, ScfTree, ScfTreeNode, Severity, SkipReason, StructureOrigin, ValidationIssue, ValidationResult, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/lib/vendor/scf/index.js

@@ -2,8 +2,11 @@
  * @scrymore/scf — the Scry Capture Format 1.0 validator and converters.
  * Zero runtime dependencies; safe to vendor into a Worker or a Node service (see repo README).
  */
-export { validateBundle } from './validate.js';
+export { validateBundle, checkStructureMember, checkSourceTextMember } from './validate.js';
 export { fromSbcov, toStorybookId } from './from-sbcov.js';
 export { fromSidecars } from './from-sidecars.js';
 export { storageKey, companionKey, sourceKeyOf } from './storage-key.js';
 export { sha256Hex } from './sha256.js';
+export { bundleFileFull, bundleFileHead, bundleFileSize, isCheckedBundleFile, isMeasuredBundleFile } from './types.js';
+export { detectImageFamily, measureImage, measureImageRecord, readImageDimensions, MEASURE_IMAGE_MAX_PREFIX_BYTES } from './image-dimensions.js';
+//# sourceMappingURL=index.js.map

package/lib/vendor/scf/sha256.js

@@ -96,3 +96,4 @@ export function sha256Hex(data) {
         hex += HEX[b];
     return hex;
 }
+//# sourceMappingURL=sha256.js.map

package/lib/vendor/scf/sidecars-internal.js

@@ -1,3 +1,4 @@
+import { bundleFileFull } from './types.js';
 /**
  * Builds capture objects for "sidecar mode": one entry per image path, with an optional
  * `<stem>.json` sidecar merged in. Shared by the native `"captures": "sidecars"` expansion in
@@ -8,7 +9,7 @@ export function sidecarCapturesFromImages(files, imagePaths) {
     for (const imagePath of [...imagePaths].sort()) {
         const dot = imagePath.lastIndexOf('.');
         const stem = dot === -1 ? imagePath : imagePath.slice(0, dot);
-        const sidecarBytes = files.get(`${stem}.json`);
+        const sidecarBytes = bundleFileFull(files.get(`${stem}.json`));
         let sidecar = {};
         if (sidecarBytes) {
             try {
@@ -27,3 +28,4 @@ export function sidecarCapturesFromImages(files, imagePaths) {
     }
     return captures;
 }
+//# sourceMappingURL=sidecars-internal.js.map

package/lib/vendor/scf/storage-key.js

@@ -25,3 +25,4 @@ export function sourceKeyOf(manifest) {
     const platform = manifest.source.platform ?? 'web';
     return `${manifest.source.kind}:${platform}`;
 }
+//# sourceMappingURL=storage-key.js.map

package/lib/vendor/scf/types.d.ts

@@ -140,8 +140,76 @@ export interface ScfManifest {
     warnings?: ValidationIssue[];
     [key: string]: unknown;
 }
-/** A bundle as an in-memory map of bundle-relative POSIX path -> file bytes. */
-export type BundleFiles = Map<string, Uint8Array>;
+/**
+ * Full bytes, or — for an image entry only — a memory-bounded stand-in: the first bytes of the
+ * file (enough for magic-byte family detection and a header-only dimension read, see
+ * `image-dimensions.ts`) plus its real total size. A caller that streams a large bundle instead of
+ * buffering it whole (ledger F31/F32: a Worker-safe bundle-upload route must never hold a full
+ * decompressed image, let alone a whole decompressed bundle, in memory) can supply this instead of
+ * the full decoded image. Every other bundle member (`scf.json`, `structure.file`/`sourceText.file`,
+ * sidecar JSON) MUST still be supplied in full — `validateBundle` only treats the `{head, size}`
+ * shape as an image, via the `image` field of a capture (security review F50).
+ */
+export type BundleFileHeadAndSize = {
+    head: Uint8Array;
+    size: number;
+};
+/**
+ * A stand-in for a `structure/*.json` or `source/*` member whose full inflated bytes were already
+ * run through `checkStructureMember`/`checkSourceTextMember` (this package) by a streaming caller,
+ * which recorded whatever issues that produced and then discarded the bytes to stay within a
+ * bounded memory budget (security review F60: a Worker-safe bundle-upload route must not retain
+ * every non-image member in full up to its own per-entry cap — structure trees especially can run
+ * 100s of MB across a large Storybook). `size` is the member's real total byte length. Accepted by
+ * `validateBundle` ONLY for those two path prefixes; any other member given this shape is refused
+ * with `MEMBER_BYTES_REQUIRED`, same as an ordinary `{head, size}` entry would be.
+ */
+export type BundleFileChecked = {
+    checked: true;
+    size: number;
+};
+/**
+ * A stand-in for an image entry that a streaming caller has already run through `measureImage`
+ * (`image-dimensions.ts`) against a bounded prefix of its real decompressed bytes, and then
+ * discarded the bytes entirely (ledger F69: even the `{head, size}` shape below still retains up to
+ * `imageHeadBytes` — the WHOLE image, for anything at or under that size — which an 8,000-image
+ * bundle of honest, individually-tiny images could turn into ~500 MB of live memory). `family` is
+ * `null` when `measureImage` couldn't identify or measure the image at all from the prefix the
+ * caller was willing to buffer (collapsed on purpose — see `measureImage`'s own doc comment); `size`
+ * is always the image's real total byte length, exactly as in `BundleFileHeadAndSize`. Accepted by
+ * `validateBundle` ONLY for image-extension paths, same restriction as `{head, size}` (F50) — any
+ * other member given this shape is refused with `MEMBER_BYTES_REQUIRED`.
+ */
+export type BundleFileMeasured = {
+    measured: true;
+    family: 'png' | 'jpeg' | 'webp' | null;
+    width: number;
+    height: number;
+    size: number;
+};
+export type BundleFileBytes = Uint8Array | BundleFileHeadAndSize | BundleFileChecked | BundleFileMeasured;
+/** A bundle as an in-memory map of bundle-relative POSIX path -> file bytes (see `BundleFileBytes`). */
+export type BundleFiles = Map<string, BundleFileBytes>;
+/** True for a `{checked: true, size}` entry (ledger F60) — never for a plain `Uint8Array`, a
+ *  `{head, size}` image entry, or a `{measured, ...}` image entry. */
+export declare function isCheckedBundleFile(entry: BundleFileBytes | undefined): entry is BundleFileChecked;
+/** True for a `{measured: true, family, width, height, size}` entry (ledger F69) — never for a
+ *  plain `Uint8Array`, a `{head, size}` image entry, or a `{checked, size}` entry. */
+export declare function isMeasuredBundleFile(entry: BundleFileBytes | undefined): entry is BundleFileMeasured;
+/** Normalizes a `BundleFiles` entry to bytes usable for magic-byte/header inspection: the full
+ *  bytes for a plain entry, or just the head for a `{head, size}` image entry. `undefined` for a
+ *  `{checked, size}` or `{measured, ...}` entry (no bytes were ever retained for either) — never the
+ *  image's real full content when given a partial entry; use `bundleFileSize` for the true byte
+ *  length. */
+export declare function bundleFileHead(entry: BundleFileBytes | undefined): Uint8Array | undefined;
+/** The entry's full bytes, or `undefined` for a `{head, size}`, `{checked, size}` or `{measured,
+ *  ...}` entry. Every non-image member (JSON, structure trees, source text) is read through this, so
+ *  a partial entry can never be validated from its head alone (security review F50). */
+export declare function bundleFileFull(entry: BundleFileBytes | undefined): Uint8Array | undefined;
+/** The entry's real total byte size: `byteLength` for a full entry, or the caller-reported `size`
+ *  for a `{head, size}`, `{checked, size}` or `{measured, ...}` entry (its true size, never a
+ *  head/partial length). */
+export declare function bundleFileSize(entry: BundleFileBytes | undefined): number | undefined;
 /** scf-tree/1, see ../../../spec/scf-1.0.md. */
 export interface ScfTreeNode {
     type: string;

package/lib/vendor/scf/types.js

@@ -1,2 +1,38 @@
 /** Types for the Scry Capture Format (SCF) 1.0. See ../../../spec/scf-1.0.md. */
-export {};
+/** True for a `{checked: true, size}` entry (ledger F60) — never for a plain `Uint8Array`, a
+ *  `{head, size}` image entry, or a `{measured, ...}` image entry. */
+export function isCheckedBundleFile(entry) {
+    return entry !== undefined && !(entry instanceof Uint8Array) && 'checked' in entry && entry.checked === true;
+}
+/** True for a `{measured: true, family, width, height, size}` entry (ledger F69) — never for a
+ *  plain `Uint8Array`, a `{head, size}` image entry, or a `{checked, size}` entry. */
+export function isMeasuredBundleFile(entry) {
+    return entry !== undefined && !(entry instanceof Uint8Array) && 'measured' in entry && entry.measured === true;
+}
+/** Normalizes a `BundleFiles` entry to bytes usable for magic-byte/header inspection: the full
+ *  bytes for a plain entry, or just the head for a `{head, size}` image entry. `undefined` for a
+ *  `{checked, size}` or `{measured, ...}` entry (no bytes were ever retained for either) — never the
+ *  image's real full content when given a partial entry; use `bundleFileSize` for the true byte
+ *  length. */
+export function bundleFileHead(entry) {
+    if (entry === undefined)
+        return undefined;
+    if (entry instanceof Uint8Array)
+        return entry;
+    return 'head' in entry ? entry.head : undefined;
+}
+/** The entry's full bytes, or `undefined` for a `{head, size}`, `{checked, size}` or `{measured,
+ *  ...}` entry. Every non-image member (JSON, structure trees, source text) is read through this, so
+ *  a partial entry can never be validated from its head alone (security review F50). */
+export function bundleFileFull(entry) {
+    return entry instanceof Uint8Array ? entry : undefined;
+}
+/** The entry's real total byte size: `byteLength` for a full entry, or the caller-reported `size`
+ *  for a `{head, size}`, `{checked, size}` or `{measured, ...}` entry (its true size, never a
+ *  head/partial length). */
+export function bundleFileSize(entry) {
+    if (entry === undefined)
+        return undefined;
+    return entry instanceof Uint8Array ? entry.byteLength : entry.size;
+}
+//# sourceMappingURL=types.js.map

package/lib/vendor/scf/validate.d.ts

@@ -1,4 +1,4 @@
-import type { BundleFiles, ValidationResult } from './types.js';
+import type { BundleFiles, ValidationIssue, ValidationResult } from './types.js';
 /** Reads a directory recursively into a BundleFiles map. Node only — never imported by a Worker
  *  build, since callers only reach this path when `input` is a string (a filesystem path). */
 /**
@@ -8,10 +8,42 @@ import type { BundleFiles, ValidationResult } from './types.js';
  * the shared G6/G7 gate, so it refuses them outright instead of relying on every consumer.
  */
 export declare function isSafeRelPath(path: string): boolean;
+interface MemberCheckResult {
+    errors: ValidationIssue[];
+    warnings: ValidationIssue[];
+}
+/**
+ * The content checks `validateBundle` applies to a `structure.file` member — a hard 10 MB size cap,
+ * a 2 MB soft (warning) threshold, and a shape check (parses as JSON and looks like a scf-tree/1
+ * document). Extracted (ledger F60) so a caller that streams a large bundle member-by-member rather
+ * than buffering the whole thing (e.g. a Worker-safe bundle-upload route, or `scry-build-processing-
+ * service`'s own streaming read) can run exactly these checks the moment a `structure/*.json` member
+ * is fully inflated, record the result, and then discard the bytes — passing `{checked: true, size}`
+ * for that member to `validateBundle` afterwards instead of its full content (see `BundleFileChecked`).
+ * `path` is only used in issue messages/paths, never re-derived from it; the caller decides which
+ * member this is. Returns no `id` — the caller (`validateBundle`, or a streaming caller once it has
+ * matched this path back to a capture) attaches that itself.
+ */
+export declare function checkStructureMember(path: string, bytes: Uint8Array): MemberCheckResult;
+/**
+ * The content checks `validateBundle` applies to a `sourceText.file` member — a 1 MB size cap and a
+ * plausible-UTF-8-text check (`looksLikeBinary`/`isValidUtf8`, ledger F24). Extracted (ledger F60)
+ * for the same streaming reason as `checkStructureMember` above — see its doc comment.
+ *
+ * `optedIn` is a fast-path only: when a caller already knows, at check time, that the manifest does
+ * NOT set `optIn.sourceText: true` (e.g. it read `scf.json` earlier in the same stream), passing
+ * `false` raises `SOURCE_TEXT_NOT_OPT_IN` immediately for this member instead of spending time on the
+ * size/binary/UTF-8 scan. It is never required for correctness: `validateBundle`'s own aggregate
+ * `SOURCE_TEXT_NOT_OPT_IN` check (across every capture, once the whole manifest is known) is always
+ * the source of truth and runs regardless, which is why `validateBundle` itself always calls this
+ * with `optedIn: true` — it would otherwise duplicate its own aggregate error.
+ */
+export declare function checkSourceTextMember(path: string, bytes: Uint8Array, optedIn: boolean): MemberCheckResult;
 /**
  * Validates an SCF bundle (or a legacy sbcov bundle, converted first) against spec/scf-1.0.md.
  * `input` is either an in-memory bundle (a Map of bundle-relative POSIX path -> bytes — the shape
  * a Worker or the upload service already has after reading a ZIP) or a directory path (Node only).
  */
 export declare function validateBundle(input: BundleFiles | string): Promise<ValidationResult>;
+export {};
 //# sourceMappingURL=validate.d.ts.map

package/lib/vendor/scf/validate.js

@@ -1,6 +1,7 @@
 import { fromSbcov } from './from-sbcov.js';
-import { readImageDimensions } from './image-dimensions.js';
+import { detectImageFamily, readImageDimensions } from './image-dimensions.js';
 import { sidecarCapturesFromImages } from './sidecars-internal.js';
+import { bundleFileFull, bundleFileHead, bundleFileSize, isCheckedBundleFile, isMeasuredBundleFile } from './types.js';
 const SUPPORTED_SCF_VERSIONS = new Set(['1.0']);
 const ALLOWED_IMAGE_EXT = new Set(['png', 'jpg', 'jpeg', 'webp']);
 const MAX_IMAGE_BYTES = 20 * 1024 * 1024;
@@ -9,36 +10,109 @@ const MAX_STRUCTURE_BYTES = 2 * 1024 * 1024; // soft (warning) threshold, spec's
 const MAX_STRUCTURE_HARD_BYTES = 10 * 1024 * 1024; // hard (error) threshold
 const MAX_SOURCE_TEXT_BYTES = 1 * 1024 * 1024;
 const MAX_LINK_URL_LENGTH = 2048;
+/** Spec MUSTs (bundle-wide, not per-entry): a bundle-wide entry-count cap that bounds validation
+ *  cost regardless of how many members a bundle has, independent of any per-image/per-entry memory
+ *  bound (ledger F69's own root cause, one root cause up: `readBoundedZip`'s own `maxEntries` already
+ *  enforces this number before inflating a single byte; `validateBundle` enforces it too since it's
+ *  the shared gate for any caller — CLI, a plain directory, a future non-ZIP source — not just a
+ *  streaming ZIP reader). See spec/scf-1.0.md's "Bundle layout" section. */
+const MAX_BUNDLE_MEMBERS = 20_000;
+/** Spec MUST: a bundle-wide cap on `captures.length` (or the sidecar-derived equivalent), independent
+ *  of the member-count cap above — a bundle could stay under `MAX_BUNDLE_MEMBERS` while still
+ *  declaring an enormous `captures` array that shares images/duplicates ids, or (in sidecar mode)
+ *  every capture is itself is a member so the two caps are related but not redundant. */
+const MAX_BUNDLE_CAPTURES = 10_000;
 const decoder = new TextDecoder();
 function extOf(path) {
     const m = /\.([a-zA-Z0-9]+)$/.exec(path);
     return m ? m[1].toLowerCase() : '';
 }
-const EXT_FAMILY = { png: 'png', jpg: 'jpeg', jpeg: 'jpeg', webp: 'webp' };
-/** Sniffs the magic bytes so a `.png` with the wrong content (or vice versa) is still caught. */
-function detectImageFamily(bytes) {
-    if (bytes.length >= 4 && bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47) {
-        return 'png';
-    }
-    if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) {
-        return 'jpeg';
-    }
-    if (bytes.length >= 12 &&
-        bytes[0] === 0x52 &&
-        bytes[1] === 0x49 &&
-        bytes[2] === 0x46 &&
-        bytes[3] === 0x46 &&
-        bytes[8] === 0x57 &&
-        bytes[9] === 0x45 &&
-        bytes[10] === 0x42 &&
-        bytes[11] === 0x50) {
-        return 'webp';
-    }
-    return null;
+/**
+ * The only two member prefixes a `{checked: true, size}` entry (ledger F60) is ever accepted for —
+ * a streaming caller may only skip retaining full bytes for these, since `checkStructureMember`/
+ * `checkSourceTextMember` are the only two extracted per-member checks this package exposes for
+ * that purpose. Anything else (scf.json, sidecar JSON, an image) must still be supplied in full or
+ * as the images-only `{head, size}` shape (F50).
+ */
+function isCheckableStructureOrSourcePath(path) {
+    return (path.startsWith('structure/') && extOf(path) === 'json') || path.startsWith('source/');
 }
+// ImageFamily/detectImageFamily live in image-dimensions.ts (shared with measureImage, ledger F69).
+const EXT_FAMILY = { png: 'png', jpg: 'jpeg', jpeg: 'jpeg', webp: 'webp' };
 function issue(code, message, extra) {
     return { code, message, ...extra };
 }
+/** Ledger F125: every enum/const the published schema/scf-1.0.json enforces. The validator MUST
+ *  reject exactly what the schema rejects (G7: schema, CLI and server agree). Keep in lockstep with
+ *  the schema; test/schema-parity.test.ts runs every fixture through both and asserts they agree. */
+const SOURCE_KINDS = new Set([
+    'storybook', 'storybook-rn', 'compose-preview', 'swiftui-preview', 'uikit', 'widgetbook', 'flutter-golden',
+    'playwright', 'cypress', 'maestro', 'xcuitest', 'crawler', 'figma', 'argos', 'percy', 'docs', 'upload',
+]);
+const SOURCE_PLATFORMS = new Set(['web', 'ios', 'android', 'macos', 'windows', 'email', 'other']);
+const CAPTURE_METHODS = new Set([
+    'browser', 'simulator', 'emulator', 'device', 'jvm-render', 'headless-render', 'design-export', 'manual',
+]);
+const CAPTURE_CROPS = new Set(['root', 'viewport', 'fullpage', 'element', 'none']);
+const CAPTURE_KINDS = new Set(['component', 'screen', 'page', 'flow-step', 'region', 'doc-image']);
+const STRUCTURE_ORIGINS = new Set([
+    'dom', 'rn-fiber', 'compose-semantics', 'uiautomator', 'xcui-accessibility', 'flutter-widgets',
+]);
+const SKIP_REASONS = new Set(['error', 'timeout', 'filtered', 'unsupported', 'empty']);
+function enumIssue(field, value, allowed, id) {
+    return issue('ENUM_VALUE_INVALID', `${field} must be one of ${[...allowed].join(', ')}: ${JSON.stringify(value)}`, { id });
+}
+/** Pushes ENUM_VALUE_INVALID when `value` is present (not undefined) and not in `allowed`. `null` is
+ *  present and off-enum, matching JSON Schema. */
+function checkEnum(errors, field, value, allowed, id) {
+    if (value === undefined)
+        return;
+    if (typeof value !== 'string' || !allowed.has(value))
+        errors.push(enumIssue(field, value, allowed, id));
+}
+function checkCaptureBlockEnums(errors, prefix, block, id) {
+    if (block === null || typeof block !== 'object' || Array.isArray(block))
+        return;
+    const b = block;
+    checkEnum(errors, `${prefix}.method`, b.method, CAPTURE_METHODS, id);
+    checkEnum(errors, `${prefix}.crop`, b.crop, CAPTURE_CROPS, id);
+}
+function checkManifestEnums(errors, manifest) {
+    const source = manifest.source;
+    if (source !== null && typeof source === 'object' && !Array.isArray(source)) {
+        const src = source;
+        const kind = src.kind;
+        if (kind !== undefined && (typeof kind !== 'string' || !(SOURCE_KINDS.has(kind) || /^x-./.test(kind)))) {
+            errors.push(issue('ENUM_VALUE_INVALID', `source.kind must be one of ${[...SOURCE_KINDS].join(', ')} or an x-<name> value: ${JSON.stringify(kind)}`));
+        }
+        checkEnum(errors, 'source.platform', src.platform, SOURCE_PLATFORMS);
+    }
+    const defaults = manifest.defaults;
+    if (defaults !== null && typeof defaults === 'object' && !Array.isArray(defaults)) {
+        checkCaptureBlockEnums(errors, 'defaults.capture', defaults.capture);
+    }
+    const skipped = manifest.counts?.skipped;
+    if (Array.isArray(skipped)) {
+        for (const item of skipped) {
+            if (item !== null && typeof item === 'object' && !Array.isArray(item)) {
+                checkEnum(errors, 'counts.skipped[].reason', item.reason, SKIP_REASONS);
+            }
+        }
+    }
+}
+function checkCaptureEnums(errors, capture, id) {
+    if (capture === null || typeof capture !== 'object')
+        return;
+    const c = capture;
+    checkEnum(errors, 'kind', c.kind, CAPTURE_KINDS, id);
+    checkCaptureBlockEnums(errors, 'capture', c.capture, id);
+    const structure = c.structure;
+    if (structure !== null && typeof structure === 'object' && !Array.isArray(structure)) {
+        const st = structure;
+        checkEnum(errors, 'structure.origin', st.origin, STRUCTURE_ORIGINS, id);
+        checkEnum(errors, 'structure.format', st.format, new Set(['scf-tree/1']), id);
+    }
+}
 /** Reads a directory recursively into a BundleFiles map. Node only — never imported by a Worker
  *  build, since callers only reach this path when `input` is a string (a filesystem path). */
 /**
@@ -76,7 +150,10 @@ async function readDir(dir) {
     return files;
 }
 function parseJson(files, path) {
-    return JSON.parse(decoder.decode(files.get(path)));
+    const bytes = bundleFileFull(files.get(path));
+    if (bytes === undefined)
+        throw new Error(`${path} must be supplied in full, not as a {head, size} entry`);
+    return JSON.parse(decoder.decode(bytes));
 }
 /**
  * `links.live` is auto-embedded as an iframe wherever Storybook is embedded today (contract §8);
@@ -156,15 +233,92 @@ function looksLikeScfTree(parsed) {
         return false;
     return typeof tree.root.type === 'string';
 }
+/**
+ * The content checks `validateBundle` applies to a `structure.file` member — a hard 10 MB size cap,
+ * a 2 MB soft (warning) threshold, and a shape check (parses as JSON and looks like a scf-tree/1
+ * document). Extracted (ledger F60) so a caller that streams a large bundle member-by-member rather
+ * than buffering the whole thing (e.g. a Worker-safe bundle-upload route, or `scry-build-processing-
+ * service`'s own streaming read) can run exactly these checks the moment a `structure/*.json` member
+ * is fully inflated, record the result, and then discard the bytes — passing `{checked: true, size}`
+ * for that member to `validateBundle` afterwards instead of its full content (see `BundleFileChecked`).
+ * `path` is only used in issue messages/paths, never re-derived from it; the caller decides which
+ * member this is. Returns no `id` — the caller (`validateBundle`, or a streaming caller once it has
+ * matched this path back to a capture) attaches that itself.
+ */
+export function checkStructureMember(path, bytes) {
+    const errors = [];
+    const warnings = [];
+    if (bytes.byteLength > MAX_STRUCTURE_HARD_BYTES) {
+        errors.push(issue('STRUCTURE_TREE_TOO_LARGE', `structure file is over 10 MB: ${path}`, { path }));
+        return { errors, warnings };
+    }
+    if (bytes.byteLength > MAX_STRUCTURE_BYTES) {
+        warnings.push(issue('STRUCTURE_TREE_LARGE', `structure file is over 2 MB: ${path}`, { path }));
+    }
+    let parsedTree;
+    try {
+        parsedTree = JSON.parse(decoder.decode(bytes));
+    }
+    catch {
+        parsedTree = undefined;
+    }
+    if (!looksLikeScfTree(parsedTree)) {
+        errors.push(issue('STRUCTURE_FORMAT_INVALID', `structure.file does not parse as a scf-tree/1 document: ${path}`, { path }));
+    }
+    return { errors, warnings };
+}
+/**
+ * The content checks `validateBundle` applies to a `sourceText.file` member — a 1 MB size cap and a
+ * plausible-UTF-8-text check (`looksLikeBinary`/`isValidUtf8`, ledger F24). Extracted (ledger F60)
+ * for the same streaming reason as `checkStructureMember` above — see its doc comment.
+ *
+ * `optedIn` is a fast-path only: when a caller already knows, at check time, that the manifest does
+ * NOT set `optIn.sourceText: true` (e.g. it read `scf.json` earlier in the same stream), passing
+ * `false` raises `SOURCE_TEXT_NOT_OPT_IN` immediately for this member instead of spending time on the
+ * size/binary/UTF-8 scan. It is never required for correctness: `validateBundle`'s own aggregate
+ * `SOURCE_TEXT_NOT_OPT_IN` check (across every capture, once the whole manifest is known) is always
+ * the source of truth and runs regardless, which is why `validateBundle` itself always calls this
+ * with `optedIn: true` — it would otherwise duplicate its own aggregate error.
+ */
+export function checkSourceTextMember(path, bytes, optedIn) {
+    const errors = [];
+    const warnings = [];
+    if (bytes.byteLength > MAX_SOURCE_TEXT_BYTES) {
+        errors.push(issue('SOURCE_TEXT_TOO_LARGE', `sourceText.file is over 1 MB: ${path}`, { path }));
+    }
+    else if (looksLikeBinary(bytes) || !isValidUtf8(bytes)) {
+        errors.push(issue('SOURCE_TEXT_NOT_TEXT', `sourceText.file is not valid UTF-8 text: ${path}`, { path }));
+    }
+    if (optedIn === false) {
+        errors.push(issue('SOURCE_TEXT_NOT_OPT_IN', `sourceText.file present but the manifest does not set optIn.sourceText: true: ${path}`, { path }));
+    }
+    return { errors, warnings };
+}
 /**
  * Validates an SCF bundle (or a legacy sbcov bundle, converted first) against spec/scf-1.0.md.
  * `input` is either an in-memory bundle (a Map of bundle-relative POSIX path -> bytes — the shape
  * a Worker or the upload service already has after reading a ZIP) or a directory path (Node only).
  */
+// This is the package's single security-sensitive "shared gate" (contract guarantee G7; security-review
+// ledger F18/F24/F25/F27/F50/F60/F69 all depend on its exact error set/order); decomposing it to reach the
+// 15-point cognitive-complexity limit is a genuine behavior-risk rewrite, not an economical fix — tracked
+// as pre-existing debt (F13 Sonar-lint pass) rather than attempted here.
+// eslint-disable-next-line sonarjs/cognitive-complexity -- 187 vs 15; full decomposition deferred, see above
 export async function validateBundle(input) {
     const files = typeof input === 'string' ? await readDir(input) : input;
     const errors = [];
     const warnings = [];
+    // Spec MUST, bundle-wide entry-count cap (ledger F69): checked first, before anything else about
+    // this bundle is even looked at, so a bundle with an absurd member count is rejected in O(1) (a
+    // single Map.size read) rather than after however much per-member work the checks below would
+    // otherwise do. This is deliberately independent of any streaming reader's own `maxEntries` (e.g.
+    // scry-storybook-upload-service's `readBoundedZip`, which enforces the same number before inflating
+    // a single byte) — validateBundle is the shared gate (contract's guarantee G7) for every caller,
+    // including a plain directory or an in-memory map nobody streamed through a ZIP at all.
+    if (files.size > MAX_BUNDLE_MEMBERS) {
+        errors.push(issue('BUNDLE_TOO_MANY_MEMBERS', `Bundle has ${files.size} members, over the ${MAX_BUNDLE_MEMBERS} limit.`));
+        return { ok: false, errors, warnings, manifest: null };
+    }
     const unsafeMembers = [...files.keys()].filter((p) => !isSafeRelPath(p));
     if (unsafeMembers.length > 0) {
         for (const p of unsafeMembers) {
@@ -172,6 +326,29 @@ export async function validateBundle(input) {
         }
         return { ok: false, errors, warnings, manifest: null };
     }
+    // Ledger F50: the {head, size} shape is for images only. Ledger F60: a NEW, distinct shape,
+    // {checked: true, size}, is additionally accepted for structure/*.json and source/* members only —
+    // it means a streaming caller already ran checkStructureMember/checkSourceTextMember against this
+    // member's full inflated bytes, recorded whatever issues that produced, and discarded the bytes to
+    // stay within a bounded memory budget. Any other member given either partial shape (including a
+    // {checked, size} entry outside those two prefixes, or a {head, size} entry that isn't an image) is
+    // refused outright, so scf.json, sidecars and anything not explicitly exempted are always validated
+    // from their full bytes.
+    const partialNonImages = [...files.entries()]
+        .filter(([p, entry]) => {
+        if (entry instanceof Uint8Array)
+            return false;
+        if (isCheckedBundleFile(entry))
+            return !isCheckableStructureOrSourcePath(p);
+        return !ALLOWED_IMAGE_EXT.has(extOf(p));
+    })
+        .map(([p]) => p);
+    if (partialNonImages.length > 0) {
+        for (const p of partialNonImages) {
+            errors.push(issue('MEMBER_BYTES_REQUIRED', `Only images may be supplied as {head, size}; ${p} must be supplied in full.`, { path: p }));
+        }
+        return { ok: false, errors, warnings, manifest: null };
+    }
     let manifest;
     let isLegacy = false;
     if (files.has('scf.json')) {
@@ -213,6 +390,7 @@ export async function validateBundle(input) {
     if (typeof manifest.scf !== 'string' || !SUPPORTED_SCF_VERSIONS.has(manifest.scf)) {
         errors.push(issue('SCF_VERSION_UNSUPPORTED', `Unsupported scf version: ${JSON.stringify(manifest.scf)}.`));
     }
+    checkManifestEnums(errors, manifest);
     const rawCaptures = manifest.captures;
     const isSidecarMode = rawCaptures === 'sidecars';
     let captures;
@@ -227,12 +405,21 @@ export async function validateBundle(input) {
         errors.push(issue('CAPTURES_MISSING', 'captures is missing, and not "sidecars" either.'));
         captures = [];
     }
+    // Spec MUST, bundle-wide capture-count cap (ledger F69) — independent of MAX_BUNDLE_MEMBERS above:
+    // a bundle could stay under the member cap while still declaring (or, in sidecar mode, deriving) an
+    // enormous captures list. Checked before the per-capture loop below so a bundle over this limit
+    // doesn't also pay for however much per-capture validation work the loop would otherwise do.
+    if (captures.length > MAX_BUNDLE_CAPTURES) {
+        errors.push(issue('BUNDLE_TOO_MANY_CAPTURES', `Bundle has ${captures.length} captures, over the ${MAX_BUNDLE_CAPTURES} limit.`));
+        return { ok: false, errors, warnings, manifest };
+    }
     const seenIds = new Map();
     const seenImages = new Map();
     const referencedPaths = new Set(['scf.json']);
     const sourceTextCaptureIds = [];
     for (const capture of captures) {
         const id = typeof capture?.id === 'string' ? capture.id : undefined;
+        checkCaptureEnums(errors, capture, id);
         if (!id || id.length > 512) {
             errors.push(issue('CAPTURE_ID_INVALID', 'Capture id is missing, empty, or over 512 characters.', { id }));
         }
@@ -253,27 +440,61 @@ export async function validateBundle(input) {
             }
             else {
                 const ext = extOf(image);
-                const bytes = files.get(image);
-                const family = bytes ? detectImageFamily(bytes) : null;
-                if (!ALLOWED_IMAGE_EXT.has(ext) || !family || EXT_FAMILY[ext] !== family) {
-                    errors.push(issue('IMAGE_FORMAT_INVALID', `Image is not PNG/JPEG/WebP: ${image}`, { id, path: image }));
-                }
-                if ((bytes?.byteLength ?? 0) > MAX_IMAGE_BYTES) {
-                    errors.push(issue('IMAGE_TOO_LARGE', `Image is over 20 MB: ${image}`, { id, path: image }));
-                }
-                if (bytes && family) {
-                    // Header-only read (no decode): a tiny file can still declare an enormous canvas, which
-                    // is a resource-exhaustion risk for whatever decodes it later (ledger F25). An unreadable
-                    // header (truncated file, or a WebP shape this parser doesn't cover) fails closed.
-                    const dims = readImageDimensions(bytes, family);
-                    if (!dims) {
+                const imageEntry = files.get(image);
+                const size = bundleFileSize(imageEntry) ?? 0;
+                if (isMeasuredBundleFile(imageEntry)) {
+                    // Ledger F69: a streaming caller already ran `measureImage` against a bounded prefix of
+                    // this image's real bytes and discarded them — there is nothing left here to re-sniff or
+                    // re-read a header from, only the small `{family, width, height, size}` record it kept.
+                    // `family: null` is `measureImage`'s own collapsed "couldn't identify or measure it at
+                    // all" result (see its doc comment) — treated the same as a format mismatch, since neither
+                    // this validator nor the caller that discarded the bytes has any way left to tell "wrong
+                    // format" apart from "header unreadable" once the prefix is gone.
+                    const { family, width, height } = imageEntry;
+                    if (!ALLOWED_IMAGE_EXT.has(ext) || !family || EXT_FAMILY[ext] !== family) {
+                        errors.push(issue('IMAGE_FORMAT_INVALID', `Image is not PNG/JPEG/WebP: ${image}`, { id, path: image }));
+                    }
+                    if (size > MAX_IMAGE_BYTES) {
+                        errors.push(issue('IMAGE_TOO_LARGE', `Image is over 20 MB: ${image}`, { id, path: image }));
+                    }
+                    if (family && EXT_FAMILY[ext] === family && (width < 1 || height < 1)) {
+                        // Ledger F126 (G7): family identified but no dimensions recorded (see `measureImageRecord`):
+                        // the same IMAGE_HEADER_UNREADABLE the full-bytes path reports for a truncated header.
                         errors.push(issue('IMAGE_HEADER_UNREADABLE', `Could not read image dimensions from the header: ${image}`, {
                             id,
                             path: image,
                         }));
                     }
-                    else if (dims.width > MAX_IMAGE_DIMENSION || dims.height > MAX_IMAGE_DIMENSION) {
-                        errors.push(issue('IMAGE_DIMENSION_TOO_LARGE', `Image is ${dims.width}x${dims.height}px, over the ${MAX_IMAGE_DIMENSION}px limit: ${image}`, { id, path: image }));
+                    else if (family && (width > MAX_IMAGE_DIMENSION || height > MAX_IMAGE_DIMENSION)) {
+                        errors.push(issue('IMAGE_DIMENSION_TOO_LARGE', `Image is ${width}x${height}px, over the ${MAX_IMAGE_DIMENSION}px limit: ${image}`, { id, path: image }));
+                    }
+                }
+                else {
+                    // `head` is the whole file for a plain entry, or just its first bytes for a `{head, size}`
+                    // partial image entry (ledger F31/F32) — either is enough for magic-byte + header-only
+                    // dimension checks. `size` is always the image's real total byte length.
+                    const head = bundleFileHead(imageEntry);
+                    const family = head ? detectImageFamily(head) : null;
+                    if (!ALLOWED_IMAGE_EXT.has(ext) || !family || EXT_FAMILY[ext] !== family) {
+                        errors.push(issue('IMAGE_FORMAT_INVALID', `Image is not PNG/JPEG/WebP: ${image}`, { id, path: image }));
+                    }
+                    if (size > MAX_IMAGE_BYTES) {
+                        errors.push(issue('IMAGE_TOO_LARGE', `Image is over 20 MB: ${image}`, { id, path: image }));
+                    }
+                    if (head && family) {
+                        // Header-only read (no decode): a tiny file can still declare an enormous canvas, which
+                        // is a resource-exhaustion risk for whatever decodes it later (ledger F25). An unreadable
+                        // header (truncated file, or a WebP shape this parser doesn't cover) fails closed.
+                        const dims = readImageDimensions(head, family);
+                        if (!dims) {
+                            errors.push(issue('IMAGE_HEADER_UNREADABLE', `Could not read image dimensions from the header: ${image}`, {
+                                id,
+                                path: image,
+                            }));
+                        }
+                        else if (dims.width > MAX_IMAGE_DIMENSION || dims.height > MAX_IMAGE_DIMENSION) {
+                            errors.push(issue('IMAGE_DIMENSION_TOO_LARGE', `Image is ${dims.width}x${dims.height}px, over the ${MAX_IMAGE_DIMENSION}px limit: ${image}`, { id, path: image }));
+                        }
                     }
                 }
             }
@@ -298,26 +519,25 @@ export async function validateBundle(input) {
             }
             else {
                 referencedPaths.add(structPath);
-                const structBytes = files.get(structPath);
-                if (!structBytes) {
-                    errors.push(issue('STRUCTURE_FILE_MISSING', `structure.file not found in bundle: ${structPath}`, { id, path: structPath }));
-                }
-                else if (structBytes.byteLength > MAX_STRUCTURE_HARD_BYTES) {
-                    errors.push(issue('STRUCTURE_TREE_TOO_LARGE', `structure file is over 10 MB: ${structPath}`, { id, path: structPath }));
+                const entry = files.get(structPath);
+                if (isCheckedBundleFile(entry)) {
+                    // Ledger F60: this member was already content-checked (checkStructureMember) and its bytes
+                    // discarded by a streaming caller before validateBundle ever saw them. The cross-checks
+                    // above (referenced-by-a-capture) and existence (an entry is present at all) are all that's
+                    // left to do here — there is nothing left to re-check content-wise, and no bytes to do it
+                    // with even if there were.
                 }
                 else {
-                    if (structBytes.byteLength > MAX_STRUCTURE_BYTES) {
-                        warnings.push(issue('STRUCTURE_TREE_LARGE', `structure file is over 2 MB: ${structPath}`, { id, path: structPath }));
-                    }
-                    let parsedTree;
-                    try {
-                        parsedTree = JSON.parse(decoder.decode(structBytes));
+                    const structBytes = bundleFileFull(entry);
+                    if (!structBytes) {
+                        errors.push(issue('STRUCTURE_FILE_MISSING', `structure.file not found in bundle: ${structPath}`, { id, path: structPath }));
                     }
-                    catch {
-                        parsedTree = undefined;
-                    }
-                    if (!looksLikeScfTree(parsedTree)) {
-                        errors.push(issue('STRUCTURE_FORMAT_INVALID', `structure.file does not parse as a scf-tree/1 document: ${structPath}`, { id, path: structPath }));
+                    else {
+                        const result = checkStructureMember(structPath, structBytes);
+                        for (const e of result.errors)
+                            errors.push({ ...e, id });
+                        for (const w of result.warnings)
+                            warnings.push({ ...w, id });
                     }
                 }
             }
@@ -338,21 +558,29 @@ export async function validateBundle(input) {
             }
             else {
                 referencedPaths.add(sourcePath);
-                const sourceBytes = files.get(sourcePath);
-                if (!sourceBytes) {
-                    errors.push(issue('SOURCE_TEXT_FILE_MISSING', `sourceText.file not found in bundle: ${sourcePath}`, {
-                        id,
-                        path: sourcePath,
-                    }));
-                }
-                else if (sourceBytes.byteLength > MAX_SOURCE_TEXT_BYTES) {
-                    errors.push(issue('SOURCE_TEXT_TOO_LARGE', `sourceText.file is over 1 MB: ${sourcePath}`, { id, path: sourcePath }));
+                const entry = files.get(sourcePath);
+                if (isCheckedBundleFile(entry)) {
+                    // Ledger F60: already content-checked (checkSourceTextMember) upstream; see the structure.file
+                    // branch above for the full reasoning — same shape, same trust boundary.
                 }
-                else if (looksLikeBinary(sourceBytes) || !isValidUtf8(sourceBytes)) {
-                    errors.push(issue('SOURCE_TEXT_NOT_TEXT', `sourceText.file is not valid UTF-8 text: ${sourcePath}`, {
-                        id,
-                        path: sourcePath,
-                    }));
+                else {
+                    const sourceBytes = bundleFileFull(entry);
+                    if (!sourceBytes) {
+                        errors.push(issue('SOURCE_TEXT_FILE_MISSING', `sourceText.file not found in bundle: ${sourcePath}`, {
+                            id,
+                            path: sourcePath,
+                        }));
+                    }
+                    else {
+                        // optedIn: true — the aggregate SOURCE_TEXT_NOT_OPT_IN check below (sourceTextCaptureIds vs.
+                        // manifest.optIn.sourceText) is this function's sole authority on opt-in; see
+                        // checkSourceTextMember's own doc comment for why validateBundle always passes true here.
+                        const result = checkSourceTextMember(sourcePath, sourceBytes, true);
+                        for (const e of result.errors)
+                            errors.push({ ...e, id });
+                        for (const w of result.warnings)
+                            warnings.push({ ...w, id });
+                    }
                 }
             }
         }
@@ -407,3 +635,4 @@ export async function validateBundle(input) {
     }
     return { ok: errors.length === 0, errors, warnings, manifest };
 }
+//# sourceMappingURL=validate.js.map

package/lib/vendor/scf/zip.js

@@ -58,3 +58,4 @@ function readLocalEntry(buf, localHeaderOffset, compressionMethod, compressedSiz
         return new Uint8Array(inflateRawSync(compressed));
     throw new Error(`Unsupported ZIP compression method: ${compressionMethod}`);
 }
+//# sourceMappingURL=zip.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scrymore/scry-deployer",
-  "version": "0.10.0-next.20260929163821",
+  "version": "0.10.0",
   "description": "A CLI to automate the deployment of Storybook static builds.",
   "main": "index.js",
   "bin": {