@photivra/engine 2.12.0 → 2.13.0

package/docs/api/exports.json

@@ -1,6 +1,6 @@
 {
-  "packageVersion": "2.12.0",
-  "engineApiVersion": "2.12.0",
+  "packageVersion": "2.13.0",
+  "engineApiVersion": "2.13.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",
@@ -2797,6 +2832,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",
@@ -3327,6 +3372,11 @@
       "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",
@@ -5917,6 +5967,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",
@@ -8137,6 +8192,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",

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-simulate-capture.md

@@ -21,8 +21,10 @@ export interface DisplayViewResult {
    */
   view: { width: number; height: number; frameWidth: number; frameHeight: number; scaleX: number; scaleY: number; samplesPerAxis: number;
     region?: { x: number; y: number; width: number; height: number } };
-  /** The resolved exposure of the capture this view shows; `standardExposureDeviationStops` as in {@link SimulateCaptureResult}. */
+  /** The resolved exposure of the capture this view shows; `standardExposureDeviationStops` and `standardExposureIlluminanceLux` as in {@link SimulateCaptureResult}. */
   exposure: { mode: SimulateCaptureExposureMode; settings: { fNumber: number; shutterSeconds: number; iso: number }; ev100: number; standardExposureDeviationStops: number | null;
+    /** As in the capture result. */
+    standardExposureIlluminanceLux: number | null;
     /** #516: as in the capture result. */
     isoControl: "manual" | "automatic"; autoIso?: SimulateCaptureAutoIsoReport };
   scene: SimulateCaptureResult["scene"];
@@ -186,23 +188,82 @@ resolver output stays in the capture's `exposure.resolution`.
 export interface SimulateCaptureAutoIsoReport {
   /** The ISO the meter target asked for at the resolved aperture and shutter, before the Auto ISO range and the ISO grid. */
   idealIsoBeforeConstraints: number;
-  /** The Auto ISO range the ISO was chosen in: the body's Auto ISO bounds, or its ISO range when it declares none (the tiers: ISO 100 to their maximum). */
+  /**
+   * The body's Auto ISO range: its Auto ISO bounds, or its ISO range when it declares none (the tiers: ISO 100 to their
+   * maximum). Without `limits` the ISO was chosen in this range.
+   */
   autoIsoMinimum: number;
   autoIsoMaximum: number;
+  /**
+   * #505: present only with `exposure.autoIso.limits`: the photographer's Auto ISO range the ISO was chosen in, inside the
+   * body's (`minimum` is the body's Auto ISO minimum when the option omits it).
+   */
+  limits?: { minimum: number; maximum: number };
   /** Whether the ISO was held at an end of the Auto ISO range. */
   clamped: false | "minimum" | "maximum";
   /**
    * The constraint that limited the resolved exposure: the resolver's `targetResidual.limitingConstraint`, for example
-   * `"iso-maximum"` (the exposure stays under target at the Auto ISO maximum), `"iso-grid-quantization"` (the nearest
-   * selectable ISO) or `"none"` (on target).
+   * `"iso-maximum"` (the exposure stays under target at the body's Auto ISO maximum), `"user-iso-maximum"` (#505: at the
+   * photographer's `limits.maximum`, below the body's), `"iso-grid-quantization"` (the nearest selectable ISO) or `"none"`
+   * (on target).
    */
   limitingConstraint: ExposureResolutionConstraint;
   /** The resolver's residual, log2(target / achieved exposure), in stops: positive when the exposure is under the meter target, negative when over it. */
   residualStops: number;
-  /** Aperture priority only: the policy and slowest preferred shutter used, and whether the slower-shutter fallback ran. */
+  /**
+   * Aperture priority, and program with a slowest preferred shutter (#504): the policy and slowest preferred shutter used,
+   * and whether the slower-shutter fallback ran.
+   */
   afterMaximumIso?: SimulateCaptureAutoIsoAfterMaximum;
   slowestPreferredShutterSeconds?: number;
   afterMaximumIsoFallbackUsed?: boolean;
+  /** #504, program only: whether the program line's shutter was longer than the slowest preferred shutter and was held. */
+  slowestPreferredShutterApplied?: boolean;
+  /** #504: present only with `slowestPreferredShutterSeconds: "auto"`: how the engine derived it (`estimateAutoIsoSlowestShutter`). */
+  automaticSlowestShutter?: SimulateCaptureAutomaticSlowestShutterReport;
+}
+```
+
+## SimulateCaptureAutomaticSlowestShutterOptions
+
+#504: the settings of `exposure.autoIso.slowestPreferredShutterSeconds: "auto"`. Every field is optional; the defaults are
+labelled generic values, recorded as `default` assumptions.
+
+```ts
+export interface SimulateCaptureAutomaticSlowestShutterOptions {
+  /** The bias in whole stops, as cameras' Auto minimum-shutter settings offer: +1 one stop faster, −1 one stop slower; −2 to +2. Default 0. */
+  fasterByStops?: number;
+  /** The shake blur allowed, in sensor pixels of `sensor.pixelPitchMicrometers`. Default 1 (a generic pixel-level budget). */
+  blurBudgetPixels?: number;
+  /**
+   * The hand's constant angular velocity, rad/s (signs as in `motion.angularVelocityRadPerSec`; only the magnitude matters).
+   * Default `GENERIC_HANDHELD_ANGULAR_VELOCITY_RAD_PER_SEC`: 4.39 °/s on yaw, a cited generic value for a 100 g phone held in
+   * two hands (Xiao et al., Proc. SPIE 7250, 2009), not a measurement of you or of this camera.
+   */
+  angularVelocityRadPerSec?: { yaw: number; pitch: number };
+  /** Stabilization in equivalent stops (≥ 0, at most 10), scaling the motion by 2^−stops. Default 0: the tiers declare no stabilization. */
+  stabilizationStopsEquivalent?: number;
+}
+```
+
+## SimulateCaptureAutomaticSlowestShutterReport
+
+#504: the automatic slowest preferred shutter in the Auto ISO report.
+
+```ts
+export interface SimulateCaptureAutomaticSlowestShutterReport {
+  /** The exposure time whose camera-shake blur equals the budget (`estimateCameraShakeBlur`), before the bias and the grid. */
+  derivedShutterSeconds: number;
+  fasterByStops: number;
+  /** derivedShutterSeconds · 2^−fasterByStops. */
+  biasedShutterSeconds: number;
+  /** The slowest preferred shutter used: the biased time within the body's shutter range. */
+  shutterSeconds: number;
+  blurBudgetPixels: number;
+  /** The shake blur at `shutterSeconds`, in pixels. */
+  blurAtShutterPixels: number;
+  angularVelocityRadPerSec: { yaw: number; pitch: number };
+  stabilizationStopsEquivalent: number;
 }
 ```
 
@@ -391,11 +452,24 @@ export interface SimulateCaptureOptions {
      */
     iso?: number | "auto";
     /**
-     * #516: aperture priority with `iso: "auto"` only (required there). The shutter gets as long as
-     * `slowestPreferredShutterSeconds` (seconds, within the body's shutter range) at the lowest Auto ISO; beyond it the ISO
-     * rises; at the Auto ISO maximum `afterMaximumIso` decides (default `"allow-slower-shutter"`).
+     * Auto ISO settings, with `iso: "auto"` only.
+     *
+     * - `slowestPreferredShutterSeconds` and `afterMaximumIso` (#516): aperture priority, where the slowest shutter is
+     *   required, and (#504) program, where it is optional. The shutter gets as long as `slowestPreferredShutterSeconds`
+     *   (seconds, within the body's shutter range) at the lowest Auto ISO; beyond it the ISO rises; at the Auto ISO maximum
+     *   `afterMaximumIso` decides (default `"allow-slower-shutter"`; in program the shutter then never gets longer than the
+     *   program line's own). Without it, program follows its line as before.
+     * - `slowestPreferredShutterSeconds: "auto"` (#504): the engine derives it from the focal length, the pixel pitch and a
+     *   hand-shake profile with `estimateAutoIsoSlowestShutter` (the camera-shake model, not the 1/focal-length rule of
+     *   thumb); `automaticSlowestShutter` sets the bias, the blur budget, the shake and the stabilization.
+     * - `limits` (#505): every mode. The photographer's Auto ISO range `{ maximum, minimum? }`, a choice kept apart from
+     *   the body's Auto ISO capability: both are selectable ISOs inside the body's Auto ISO range, `minimum` at most
+     *   `maximum` (default: the body's minimum). Outside the body's range or off its ISO grid the request fails; the
+     *   engine never clips a limit. When the ISO stops at a limit strictly inside the body's range, the report's
+     *   `limitingConstraint` is `"user-iso-maximum"` or `"user-iso-minimum"`.
      */
-    autoIso?: { slowestPreferredShutterSeconds: number; afterMaximumIso?: SimulateCaptureAutoIsoAfterMaximum };
+    autoIso?: { slowestPreferredShutterSeconds?: number | "auto"; afterMaximumIso?: SimulateCaptureAutoIsoAfterMaximum; limits?: AutoIsoLimits;
+      automaticSlowestShutter?: SimulateCaptureAutomaticSlowestShutterOptions };
     /** Shutter for manual and shutter-priority modes. Default 1/125 s. */
     shutterSeconds?: number;
     /** Exposure compensation applied to the meter target, in stops. Default 0. */
@@ -616,6 +690,13 @@ export interface SimulateCaptureResult {
      * the metered luminance is 0 (a black scene has no standard exposure).
      */
     standardExposureDeviationStops: number | null;
+    /**
+     * The illuminance, lux, at which the settings used give the standard exposure: E·L_ref(N, t, S)/L = E·2^Δ, with E the
+     * request's `illuminanceLux`. Exact for a reflective scene (a chart, a reflectance function or a material scene), whose
+     * metered luminance is proportional to E. Null for a black scene (L = 0) and for a radiance-function scene, whose
+     * radiance does not depend on the illuminance. It may exceed the 1e7 lux that `illuminanceLux` accepts.
+     */
+    standardExposureIlluminanceLux: number | null;
     /** Full output of the existing exposure-mode resolver. */
     resolution: unknown;
   };

package/docs/api/output-text-metadata.md

@@ -2,6 +2,40 @@
 
 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.
 
+## addJpegTextMetadata
+
+Returns a copy of a baseline JPEG with the text fields added: merged into its XMP APP1 packet (or a new packet
+after the last leading APPn segment when it has none), plus a COM segment for `comment`. Every other byte,
+including the entropy-coded data, is unchanged. Reads marker segments only up to SOS. The engine's own
+`output.metadata` path calls this function, so for the same JPEG and text the bytes are the same.
+
+Root export (#388). `metadata` is checked as `output.metadata` is (see the module notes); a JPEG without SOI,
+a malformed or truncated segment before SOS, an XMP APP1 segment after a non-APPn segment, an XMP packet that is
+not UTF-8 or has no `rdf:RDF`, or text that makes the packet larger than one APP1 segment fails with
+`InvalidConfigurationError`. The input is not changed.
+
+```ts
+export function addJpegTextMetadata(jpeg: Uint8Array, metadata: Readonly<OutputTextMetadata>): Uint8Array;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## addPngTextMetadata
+
+Returns a copy of a PNG with one text chunk per field inserted before the first IDAT chunk. Other chunks are
+unchanged. The engine's own `output.metadata` path calls this function, so for the same PNG and text the bytes
+are the same.
+
+Root export (#388). `metadata` is checked as `output.metadata` is (see the module notes); a file without the PNG
+signature, or without an IDAT chunk inside its bytes, fails with `InvalidConfigurationError`. Chunk CRCs before
+IDAT are not checked. The input is not changed.
+
+```ts
+export function addPngTextMetadata(png: Uint8Array, metadata: Readonly<OutputTextMetadata>): Uint8Array;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
 ## OutputTextMetadata
 
 Caller-supplied text written into JPEG, PNG and DNG outputs. Every field is optional; at least one must be set.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@photivra/engine",
-  "version": "2.12.0",
+  "version": "2.13.0",
   "private": false,
   "description": "Scientific TypeScript engine for camera optics, exposure, focus, motion, sensor sampling, diffraction, and digital imaging calculations.",
   "type": "module",