@photivra/engine 2.12.0 → 2.14.0

package/docs/api/exports.json

@@ -1,6 +1,6 @@
 {
-  "packageVersion": "2.12.0",
-  "engineApiVersion": "2.12.0",
+  "packageVersion": "2.14.0",
+  "engineApiVersion": "2.14.0",
   "exports": [
     {
       "name": "AbsoluteUncertaintyEstimate",
@@ -27,6 +27,16 @@
       "source": "src/output/capture-geometry.ts",
       "kind": "type"
     },
+    {
+      "name": "addJpegTextMetadata",
+      "source": "src/output/text-metadata.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "addPngTextMetadata",
+      "source": "src/output/text-metadata.ts",
+      "kind": "runtime"
+    },
     {
       "name": "AffineGeometricTransform",
       "source": "src/output/geometric-transforms.ts",
@@ -192,11 +202,36 @@
       "source": "src/optics/atmospheric-haze.ts",
       "kind": "type"
     },
+    {
+      "name": "AUTO_ISO_SLOWEST_SHUTTER_MAXIMUM_BIAS_STOPS",
+      "source": "src/exposure/auto-iso-slowest-shutter.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "AUTO_ISO_SLOWEST_SHUTTER_MODEL_VERSION",
+      "source": "src/exposure/auto-iso-slowest-shutter.ts",
+      "kind": "runtime"
+    },
     {
       "name": "AutoIsoBaselinePolicy",
       "source": "src/exposure/exposure-mode-resolver.ts",
       "kind": "type"
     },
+    {
+      "name": "AutoIsoLimits",
+      "source": "src/exposure/exposure-mode-resolver.ts",
+      "kind": "type"
+    },
+    {
+      "name": "AutoIsoSlowestShutterBlurBudget",
+      "source": "src/exposure/auto-iso-slowest-shutter.ts",
+      "kind": "type"
+    },
+    {
+      "name": "AutoIsoSlowestShutterEstimate",
+      "source": "src/exposure/auto-iso-slowest-shutter.ts",
+      "kind": "type"
+    },
     {
       "name": "AxisSamplingPitchMicrometers",
       "source": "src/motion/camera-rotation.ts",
@@ -2042,6 +2077,26 @@
       "source": "src/color/colorimetry-math.ts",
       "kind": "type"
     },
+    {
+      "name": "COLOR_PATCH_IDS",
+      "source": "src/facade/color-patches.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "COLOR_PATCH_SET_ID",
+      "source": "src/facade/color-patches.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "COLOR_PATCH_SET_VERSION",
+      "source": "src/facade/color-patches.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "COLOR_PATCH_WAVELENGTH_RANGE_NANOMETERS",
+      "source": "src/facade/color-patches.ts",
+      "kind": "runtime"
+    },
     {
       "name": "COLOR_TEMPERATURE_WHITE_BALANCE_INTENT_VERSION",
       "source": "src/color/white-balance.ts",
@@ -2087,6 +2142,41 @@
       "source": "src/color/colorimetry-math.ts",
       "kind": "type"
     },
+    {
+      "name": "ColorPatch",
+      "source": "src/facade/color-patches.ts",
+      "kind": "type"
+    },
+    {
+      "name": "ColorPatchesChartScene",
+      "source": "src/facade/chart-scenes.ts",
+      "kind": "type"
+    },
+    {
+      "name": "ColorPatchGroup",
+      "source": "src/facade/color-patches.ts",
+      "kind": "type"
+    },
+    {
+      "name": "ColorPatchId",
+      "source": "src/facade/color-patches.ts",
+      "kind": "type"
+    },
+    {
+      "name": "ColorPatchReflectance",
+      "source": "src/facade/chart-scenes.ts",
+      "kind": "type"
+    },
+    {
+      "name": "ColorPatchSet",
+      "source": "src/facade/color-patches.ts",
+      "kind": "type"
+    },
+    {
+      "name": "ColorPatchSpectralTerm",
+      "source": "src/facade/color-patches.ts",
+      "kind": "type"
+    },
     {
       "name": "ColorSamplingChannelComposition",
       "source": "src/sensor/capture-color-sampling-binding.ts",
@@ -2797,6 +2887,16 @@
       "source": "src/optics/circle-of-confusion.ts",
       "kind": "type"
     },
+    {
+      "name": "estimateAutoIsoSlowestShutter",
+      "source": "src/exposure/auto-iso-slowest-shutter.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "EstimateAutoIsoSlowestShutterInput",
+      "source": "src/exposure/auto-iso-slowest-shutter.ts",
+      "kind": "type"
+    },
     {
       "name": "estimateAutoWhiteBalance",
       "source": "src/color/white-balance.ts",
@@ -2877,6 +2977,16 @@
       "source": "src/color/rgb-color-spaces.ts",
       "kind": "runtime"
     },
+    {
+      "name": "evaluateColorPatchReflectance",
+      "source": "src/facade/color-patches.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "EvaluateColorPatchReflectanceInput",
+      "source": "src/facade/color-patches.ts",
+      "kind": "type"
+    },
     {
       "name": "evaluateSceneIlluminationTemporalMultiplier",
       "source": "src/schema/illumination-temporal.ts",
@@ -3322,11 +3432,21 @@
       "source": "src/equipment/generic-tier-presets.ts",
       "kind": "runtime"
     },
+    {
+      "name": "GENERIC_EQUIPMENT_TIER_PRESET_VERSIONS",
+      "source": "src/equipment/generic-tier-presets.ts",
+      "kind": "runtime"
+    },
     {
       "name": "GENERIC_EQUIPMENT_TIERS",
       "source": "src/equipment/generic-tier-presets.ts",
       "kind": "runtime"
     },
+    {
+      "name": "GENERIC_HANDHELD_ANGULAR_VELOCITY_RAD_PER_SEC",
+      "source": "src/exposure/auto-iso-slowest-shutter.ts",
+      "kind": "runtime"
+    },
     {
       "name": "GENERIC_ISO_SIGNAL_CHAIN_PRESET_CATALOG_SCHEMA_VERSION",
       "source": "src/sensor/iso-signal-chain.ts",
@@ -3357,6 +3477,21 @@
       "source": "src/equipment/release-capabilities.ts",
       "kind": "runtime"
     },
+    {
+      "name": "GENERIC_THIRD_STOP_ISO_SETTINGS",
+      "source": "src/equipment/generic-tier-assets.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "GENERIC_THIRD_STOP_SHUTTER_SECONDS",
+      "source": "src/equipment/generic-tier-assets.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "GENERIC_WHOLE_STOP_ISO_SETTINGS",
+      "source": "src/equipment/generic-tier-assets.ts",
+      "kind": "runtime"
+    },
     {
       "name": "GenericBodyExposureCapabilityProfile",
       "source": "src/equipment/exposure-capabilities.ts",
@@ -3477,6 +3612,11 @@
       "source": "src/equipment/generic-tier-assets.ts",
       "kind": "type"
     },
+    {
+      "name": "GenericTierPresetVersion",
+      "source": "src/equipment/generic-tier-assets.ts",
+      "kind": "type"
+    },
     {
       "name": "GenericVersionedAsset",
       "source": "src/equipment/generic-tier-assets.ts",
@@ -3532,6 +3672,11 @@
       "source": "src/output/geometric-transforms.ts",
       "kind": "type"
     },
+    {
+      "name": "getColorPatchSet",
+      "source": "src/facade/color-patches.ts",
+      "kind": "runtime"
+    },
     {
       "name": "getImageFormationContract",
       "source": "src/core/image-formation.ts",
@@ -5917,6 +6062,11 @@
       "source": "src/exposure/exposure-mode-resolver.ts",
       "kind": "type"
     },
+    {
+      "name": "ProgramSlowestPreferredShutterPolicy",
+      "source": "src/exposure/exposure-mode-resolver.ts",
+      "kind": "type"
+    },
     {
       "name": "ProjectedMotionBlur",
       "source": "src/motion/projected-motion.ts",
@@ -8112,6 +8262,11 @@
       "source": "src/facade/simulate-capture.ts",
       "kind": "runtime"
     },
+    {
+      "name": "SIMULATE_CAPTURE_METERING_MODES",
+      "source": "src/facade/simulate-capture.ts",
+      "kind": "runtime"
+    },
     {
       "name": "SIMULATE_DISPLAY_VIEW_DEFAULT_SAMPLES_PER_AXIS",
       "source": "src/facade/simulate-capture.ts",
@@ -8137,6 +8292,16 @@
       "source": "src/facade/simulate-capture.ts",
       "kind": "type"
     },
+    {
+      "name": "SimulateCaptureAutomaticSlowestShutterOptions",
+      "source": "src/facade/simulate-capture.ts",
+      "kind": "type"
+    },
+    {
+      "name": "SimulateCaptureAutomaticSlowestShutterReport",
+      "source": "src/facade/simulate-capture.ts",
+      "kind": "type"
+    },
     {
       "name": "SimulateCaptureBorderHandling",
       "source": "src/facade/simulate-capture.ts",
@@ -8187,6 +8352,11 @@
       "source": "src/facade/simulate-capture.ts",
       "kind": "type"
     },
+    {
+      "name": "SimulateCaptureMetering",
+      "source": "src/facade/simulate-capture.ts",
+      "kind": "type"
+    },
     {
       "name": "SimulateCaptureMotion",
       "source": "src/facade/simulate-capture.ts",

package/docs/api/exposure-auto-iso-slowest-shutter.md

@@ -0,0 +1,139 @@
+# exposure/auto-iso-slowest-shutter.ts public contracts
+
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## AUTO_ISO_SLOWEST_SHUTTER_MAXIMUM_BIAS_STOPS
+
+The largest whole-stop bias accepted, either way (makers offer up to 2 stops faster or slower).
+
+```ts
+AUTO_ISO_SLOWEST_SHUTTER_MAXIMUM_BIAS_STOPS = 2 as const
+```
+
+## AUTO_ISO_SLOWEST_SHUTTER_MODEL_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+AUTO_ISO_SLOWEST_SHUTTER_MODEL_VERSION = "1.0.0" as const
+```
+
+## AutoIsoSlowestShutterBlurBudget
+
+The blur allowed during the exposure, on the sensor.
+
+```ts
+export type AutoIsoSlowestShutterBlurBudget =
+  | {
+      /** The blur trace length in pixels of the given pitch. */
+      kind: "pixels";
+      pixels: number;
+      pixelPitchMicrometers: number;
+    }
+  | {
+      /** The blur trace length as a fraction of the image diagonal (width × height in millimetres). */
+      kind: "image-diagonal-fraction";
+      fraction: number;
+      imageWidthMm: number;
+      imageHeightMm: number;
+    };
+```
+
+## AutoIsoSlowestShutterEstimate
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface AutoIsoSlowestShutterEstimate {
+  /** The exposure time whose shake blur equals the budget, before the bias and the grid. */
+  derivedShutterSeconds: number;
+  fasterByStops: number;
+  /** derivedShutterSeconds · 2^−fasterByStops. */
+  biasedShutterSeconds: number;
+  /** The slowest preferred shutter: the biased value, snapped to `shutterCapability` when given. */
+  shutterSeconds: number;
+  shutterResolution: {
+    kind: "unconstrained" | "continuous" | "discrete";
+    selectionPolicy: "not-longer-than-target";
+    quantized: boolean;
+    clamped: false | "minimum" | "maximum";
+  };
+  blurBudgetMm: number;
+  /** `estimateCameraShakeBlur()`'s stabilized blur at the derived shutter (equal to the budget within rounding). */
+  blurAtDerivedShutterMm: number;
+  /** `estimateCameraShakeBlur()`'s stabilized blur at `shutterSeconds`. */
+  blurAtShutterMm: number;
+  /** The same blur lengths in pixels, for a pixel budget. */
+  blurBudgetPixels?: number;
+  blurAtShutterPixels?: number;
+  projectionDistanceMm: number;
+  residualMotionFactor: number;
+  angularVelocityRadPerSec: { yaw: number; pitch: number };
+  stabilizationStopsEquivalent: number;
+}
+```
+
+## estimateAutoIsoSlowestShutter
+
+Estimates the slowest preferred shutter for Auto ISO from the lens, the sensor and the hand's
+shake: the exposure time at which `estimateCameraShakeBlur()`'s stabilized blur equals the blur
+budget, then shifted by a whole-stop bias and optionally snapped to the body's shutter grid (never
+longer than the biased value). Longer focal lengths give faster shutters; each stabilization stop
+doubles the time; each bias stop halves (+1) or doubles (−1) it.
+
+An approximation: constant angular velocity (a caller profile, or the labelled generic default
+`GENERIC_HANDHELD_ANGULAR_VELOCITY_RAD_PER_SEC`), stabilization as 2^−stops, blur on the optical axis
+only. The 1/focal-length "reciprocal rule" is a rule of thumb and is not used.
+
+```ts
+export function estimateAutoIsoSlowestShutter(
+  input: EstimateAutoIsoSlowestShutterInput
+): CalculationResult<AutoIsoSlowestShutterEstimate>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## EstimateAutoIsoSlowestShutterInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface EstimateAutoIsoSlowestShutterInput {
+  focalLengthMm: number;
+  /** Optional focus distance in metres: the thin-lens image distance becomes the projection distance, as in `estimateCameraShakeBlur()`. */
+  focusDistanceM?: number;
+  /**
+   * The hand's constant angular velocity in radians per second, the explicit shake profile (signs as in
+   * `estimateCameraShakeBlur()`; only the magnitude matters here). At least one axis must be non-zero.
+   * `GENERIC_HANDHELD_ANGULAR_VELOCITY_RAD_PER_SEC` is a cited generic default, not a measurement of you.
+   */
+  angularVelocityRadPerSec: { yaw: number; pitch: number };
+  /** Stabilization in equivalent stops (≥ 0); the motion is scaled by 2^−stops. Default 0. */
+  stabilizationStopsEquivalent?: number;
+  blurBudget: AutoIsoSlowestShutterBlurBudget;
+  /**
+   * The bias in whole stops, applied after the derivation: +1 is one stop faster (half the time), −1 one
+   * stop slower (twice the time). An integer from −2 to +2. Default 0.
+   */
+  fasterByStops?: number;
+  /** Optional: the body's resolved shutter capability. The biased shutter then snaps to it, never longer than the biased value, and is held at its ends. */
+  shutterCapability?: ResolvedGenericEquipmentExposureCapabilities["shutter"];
+}
+```
+
+## GENERIC_HANDHELD_ANGULAR_VELOCITY_RAD_PER_SEC
+
+A generic handheld angular velocity, labelled as a default and not a measurement of any camera or
+photographer: 4.39 °/s (≈ 0.0766 rad/s), the linear camera-motion rate Xiao, Farrell, Catrysse and
+Wandell use for "an average user" holding "a typical 100g mobile handset with two hands", from their
+earlier gyroscope measurements (F. Xiao, J. Farrell, P. Catrysse, B. Wandell, "Mobile imaging: the
+big challenge of the small pixel", Proc. SPIE 7250, Digital Photography V, 2009, §2; author copy:
+https://web.stanford.edu/~wandell/data/papers/2009-CameraShake-Xiao.pdf; they cite F. Xiao et al.,
+"Camera-motion and mobile imaging", Proc. SPIE 6502, 2007). The value is one rate magnitude; it is
+placed on the yaw axis (for small angles the blur length does not depend on the direction). A
+heavier camera, another grip or another photographer moves differently: pass your own profile.
+
+```ts
+GENERIC_HANDHELD_ANGULAR_VELOCITY_RAD_PER_SEC: Readonly<{ yaw: number; pitch: number }> =
+  Object.freeze({ yaw: (4.39 * Math.PI) / 180, pitch: 0 })
+```

package/docs/api/exposure-exposure-mode-resolver.md

@@ -198,6 +198,32 @@ export interface AutoIsoBaselinePolicy {
   isoBaseline: "minimum-selectable";
   isoQuantizationPolicy:
     "nearest-log2-lower-on-tie";
+  /** #505: optional photographer-set Auto ISO limits inside the body's Auto ISO range. */
+  autoIsoLimits?: AutoIsoLimits;
+}
+```
+
+## AutoIsoLimits
+
+#505: the photographer's Auto ISO limits, a policy choice kept separate from what the body allows
+(`capabilities.iso.autoIsoMinimum`/`autoIsoMaximum`, else the ISO range). Cameras let the
+photographer cap Auto ISO, and some also raise its floor (for example the Nikon D850's "maximum
+sensitivity", Fujifilm's per-preset default and maximum sensitivity, and Panasonic's separate upper
+and lower Auto ISO limits; makers' manuals, see docs/USAGE.md).
+
+Both values are ISO settings: inside the body's Auto ISO range and, on a discrete ISO grid, one of
+its values, with `minimum` at most `maximum`. Anything else fails with
+`InvalidScientificInputError`; the engine never clips a limit silently. When a limit is strictly
+inside the body's range and the ISO is held there, the limiting constraint is `user-iso-maximum` or
+`user-iso-minimum`; a limit equal to the body's bound adds nothing, and the body's `iso-maximum` or
+`iso-minimum` is reported.
+
+```ts
+export interface AutoIsoLimits {
+  /** The highest ISO Auto ISO may choose. */
+  maximum: number;
+  /** The lowest ISO Auto ISO may choose, and so its baseline. Default: the body's Auto ISO minimum. */
+  minimum?: number;
 }
 ```
 
@@ -219,6 +245,8 @@ export type ExposureResolutionConstraint =
   | "none"
   | "iso-minimum"
   | "iso-maximum"
+  | "user-iso-minimum"
+  | "user-iso-maximum"
   | "iso-grid-quantization"
   | "shutter-minimum"
   | "shutter-maximum"
@@ -366,6 +394,8 @@ export interface FullAutoExposurePolicy {
     "minimum-selectable";
   isoQuantizationPolicy:
     "nearest-log2-lower-on-tie";
+  /** #505: optional photographer-set Auto ISO limits inside the body's Auto ISO range. */
+  autoIsoLimits?: AutoIsoLimits;
 }
 ```
 
@@ -467,6 +497,8 @@ export type ManualIsoControl =
       kind: "automatic";
       quantizationPolicy:
         "nearest-log2-lower-on-tie";
+      /** #505: optional photographer-set Auto ISO limits inside the body's Auto ISO range. */
+      autoIsoLimits?: AutoIsoLimits;
     };
 ```
 
@@ -521,6 +553,16 @@ export type ProgramAutoExposureModeResolution =
           ExposureTargetResidual,
           { status: "resolved" }
         >;
+      /**
+       * #504: present only with `isoControl.slowestPreferredShutter`. `applied` is true when the line's
+       * shutter was longer than the slowest preferred shutter and was held; `afterMaximumIsoFallbackUsed`
+       * when the slower-shutter fallback ran at the Auto ISO maximum. `programLineSelection` stays the
+       * line's own selection.
+       */
+      slowestPreferredShutter?: ProgramSlowestPreferredShutterPolicy & {
+        applied: boolean;
+        afterMaximumIsoFallbackUsed: boolean;
+      };
     })
   | {
       resolverVersion:
@@ -573,6 +615,14 @@ export type ProgramAutoIsoControl =
         "minimum-selectable";
       isoQuantizationPolicy:
         "nearest-log2-lower-on-tie";
+      /** #505: optional photographer-set Auto ISO limits inside the body's Auto ISO range. */
+      autoIsoLimits?: AutoIsoLimits;
+      /**
+       * #504: optionally hold the program line's shutter at or faster than a slowest preferred shutter
+       * before the ISO rises (for example from `estimateAutoIsoSlowestShutter()`). Absent, the program line
+       * is followed as before.
+       */
+      slowestPreferredShutter?: ProgramSlowestPreferredShutterPolicy;
     };
 ```
 
@@ -611,6 +661,24 @@ export interface ProgramLineSelectionDiagnostics {
 }
 ```
 
+## ProgramSlowestPreferredShutterPolicy
+
+#504: Program + Auto ISO's slowest preferred shutter, the two-axis policy of Aperture Priority + Auto
+ISO applied to the program line. When the line asks for a longer shutter than
+`slowestPreferredShutterSeconds`, the shutter is held there (snapped, never longer) with the line's
+aperture, and Auto ISO makes up the rest. At the Auto ISO maximum, `afterMaximumIso` decides:
+`"allow-slower-shutter"` lengthens the shutter toward the target, but never past the program line's
+own shutter; `"hold-preferred-shutter"` keeps it and leaves the exposure under target.
+
+```ts
+export interface ProgramSlowestPreferredShutterPolicy {
+  slowestPreferredShutterSeconds: number;
+  afterMaximumIso:
+    | "allow-slower-shutter"
+    | "hold-preferred-shutter";
+}
+```
+
 ## RelativeExposureControlAnchor
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.

package/docs/api/facade-chart-scenes.md

@@ -97,6 +97,7 @@ CHART_SCENE_DEFAULTS = Object.freeze({
   "slanted-squares": Object.freeze({ columns: 3, rows: 2, sizeFraction: 0.5, angleDegrees: 5, darkReflectance: 0.15, lightReflectance: 0.6 }),
   "line-grid": Object.freeze({ spacing: 1 / 3, lineWidth: 0.01, lineReflectance: 0.42, backgroundReflectance: 0.6 }),
   fiducial: Object.freeze({ radiusFraction: 0.8, ringFraction: 0.18, inverted: false, darkReflectance: 0.05, lightReflectance: 0.8, backgroundReflectance: 0.18 }),
+  "color-patches": Object.freeze({ patchIds: COLOR_PATCH_IDS, gapFraction: 0.1, backgroundReflectance: 0.18 }),
   composite: Object.freeze({ background: Object.freeze({ preset: "uniform" as const, reflectance: 0.18 }) })
 })
 ```
@@ -108,7 +109,7 @@ The exact contract is declared below; use the domain guide for assumptions and s
 ```ts
 CHART_SCENE_PRESETS: readonly ChartScenePresetId[] = Object.freeze(["uniform", "slanted-edge", "siemens-star",
   "step-wedge", "grey-ramp", "checkerboard", "point-grid", "patches", "dead-leaves", "bar-groups", "hyperbolic-wedge", "zone-plate",
-  "slanted-squares", "line-grid", "fiducial", "composite"] as const)
+  "slanted-squares", "line-grid", "fiducial", "color-patches", "composite"] as const)
 ```
 
 ## CHART_SPECTRAL_RANGE_NANOMETERS
@@ -144,7 +145,7 @@ Any chart preset except `composite`: a composite's background or element.
 
 ```ts
 export type ChartElementScene = UniformChartScene | SlantedEdgeChartScene | SiemensStarChartScene | StepWedgeChartScene | GreyRampChartScene |
-  CheckerboardChartScene | PointGridChartScene | PatchChartScene | DeadLeavesChartScene | BarGroupsChartScene | HyperbolicWedgeChartScene |
+  CheckerboardChartScene | PointGridChartScene | PatchChartScene | ColorPatchesChartScene | DeadLeavesChartScene | BarGroupsChartScene | HyperbolicWedgeChartScene |
   ZonePlateChartScene | SlantedSquaresChartScene | LineGridChartScene | FiducialChartScene;
 ```
 
@@ -158,10 +159,11 @@ export interface ChartRectangle { u0: number; v0: number; u1: number; v1: number
 
 ## ChartReflectance
 
-A neutral (spectrally flat) reflectance in [0, 1], or a caller reflectance spectrum (values in [0, 1]).
+A neutral (spectrally flat) reflectance in [0, 1], a caller reflectance spectrum (values in [0, 1]) or, from 2.14, a
+built-in color patch `{ kind: "color-patch", patchId }`.
 
 ```ts
-export type ChartReflectance = number | ColorimetricSpectrum;
+export type ChartReflectance = number | ColorimetricSpectrum | ColorPatchReflectance;
 ```
 
 ## ChartScene
@@ -213,6 +215,35 @@ export interface CheckerboardChartScene {
 }
 ```
 
+## ColorPatchesChartScene
+
+2.14: the built-in Photivra color patches (`getColorPatchSet()`) in a grid, drawn like `patches`: row-major, each
+patch centred in an equal cell with a neutral gap around it. The spectra are the engine's own analytic designs; no
+third-party chart data, names, order or layout are used.
+
+```ts
+export interface ColorPatchesChartScene {
+  preset: "color-patches";
+  /** Patches to draw, row-major, distinct. Default: the whole set in `COLOR_PATCH_IDS` order (30 patches, six per row). */
+  patchIds?: readonly ColorPatchId[];
+  /** Patches per row, 1 to the patch count. Default min(6, patch count). */
+  columns?: number;
+  /** Gap between patches as a fraction of the cell size, [0, 0.5). Default 0.1. */
+  gapFraction?: number;
+  /** Neutral reflectance of the gaps and empty cells. Default 0.18. */
+  backgroundReflectance?: number;
+}
+```
+
+## ColorPatchReflectance
+
+2.14: one of the engine's built-in color patches (see `getColorPatchSet()`): its reflectance spectrum, Photivra's own
+analytic design, rendered through the same spectral path as a caller spectrum.
+
+```ts
+export interface ColorPatchReflectance { kind: "color-patch"; patchId: ColorPatchId }
+```
+
 ## CompositeChartElement
 
 One element of a composite chart: a preset drawn inside its placement rectangle (frame units of the
@@ -346,7 +377,7 @@ The exact contract is declared below; use the domain guide for assumptions and s
 ```ts
 export interface PatchChartScene {
   preset: "patches";
-  /** Caller reflectance per patch, row-major; the facade bundles no colour-chart data. 1..1024 patches. */
+  /** Caller reflectance per patch, row-major; the facade bundles no color-chart data. 1..1024 patches. */
   patches: readonly { patchId: string; reflectance: ChartReflectance }[];
   /** Patches per row. Default ceil(sqrt(patch count)). */
   columns?: number;