@photivra/engine 2.11.1 → 2.13.0

package/docs/USAGE.md

@@ -5089,10 +5089,72 @@ The limiting constraint is reported as one of:
 - `none`;
 - `iso-minimum`;
 - `iso-maximum`;
+- `user-iso-minimum` and `user-iso-maximum` (#505, [photographer-set limits](#photographer-set-auto-iso-limits-505));
 - `iso-grid-quantization`.
 
 If Auto ISO capability is `unsupported` or `unknown`, the resolver returns a blocked result. Unknown is not treated as supported.
 
+### Photographer-set Auto ISO limits (#505)
+
+Cameras let the photographer cap Auto ISO, and some also raise its floor: the Nikon D850 has a maximum sensitivity
+([Auto ISO control](https://imaging.nikon.com/support/digitutor/d850/functions/autoisocontrol.html)), Fujifilm a default and a
+maximum sensitivity per preset ([ISO Auto setting](https://fujifilm-dsc.com/en/manual/x-pro2/menu_shooting/iso_auto_setting/index.html)),
+and Panasonic separate upper and lower Auto ISO limits
+([GH5 II manual](https://eww.pavc.panasonic.co.jp/dscoi/DC-GH5M2/html/DC-GH5M2_DVQP2464_eng/0062.html)). That is the
+photographer's choice, so the engine keeps it apart from what the body allows (`capabilities.iso.autoIsoMinimum` and
+`autoIsoMaximum`, or the ISO range when the body declares none).
+
+Every Auto ISO entry point takes an optional `autoIsoLimits: { maximum, minimum? }` (`AutoIsoLimits`):
+
+| Resolver | Where |
+| --- | --- |
+| `resolveManualExposureMode` | `isoControl.autoIsoLimits` (automatic ISO) |
+| `resolveAperturePriorityAutoIsoExposureMode` | `policy.autoIsoLimits` |
+| `resolveShutterPriorityExposureMode` | `isoControl.policy.autoIsoLimits` (automatic ISO) |
+| `resolveProgramAutoExposureMode` | `isoControl.autoIsoLimits` (automatic ISO) |
+| `resolveFullAutoExposureMode` | `policy.autoIsoLimits` |
+
+Composition fragment: requires previously validated bindings `capabilities`, `target`. This is an integration sketch, not a standalone runnable program.
+
+```ts
+import {
+  resolveManualExposureMode
+} from "@photivra/engine";
+
+const capped =
+  resolveManualExposureMode({
+    target,
+    capabilities,
+    referenceExposure: {
+      aperture: 4,
+      shutterSeconds: 1 / 125,
+      iso: 100
+    },
+    manualAperture: 4,
+    manualShutterSeconds: 1 / 125,
+    isoControl: {
+      kind: "automatic",
+      quantizationPolicy:
+        "nearest-log2-lower-on-tie",
+      autoIsoLimits: { maximum: 6400 }
+    }
+  });
+```
+
+The rules:
+
+- Both limits 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`. `minimum` defaults to the body's Auto ISO minimum. A limit outside the body's range or off
+  the grid fails with `InvalidScientificInputError`, and a malformed record (not an object, an unknown field) with
+  `InvalidConfigurationError`. The engine never clips a limit silently.
+- The ISO is chosen in the narrowed range, and the baseline of the priority, program and Full Auto policies (the lowest
+  selectable ISO) is the first selectable ISO at or above `minimum`.
+- When the ISO is held at a limit strictly inside the body's range, the limiting constraint is `user-iso-maximum` or
+  `user-iso-minimum`, with the residual to the target as usual. A limit equal to the body's bound adds nothing; the body's
+  `iso-maximum` or `iso-minimum` is reported.
+- Without `autoIsoLimits` every result is unchanged.
+- A separate, lower cap for flash is not part of this: it belongs with flash-aware exposure.
+
 A `no-signal` meter target also blocks Auto ISO, instead of selecting maximum ISO or infinity.
 
 ### Manual ISO
@@ -5258,6 +5320,12 @@ The policy is explicit:
    - `allow-slower-shutter`; or
    - `hold-preferred-shutter` and return residual underexposure.
 
+With `policy.autoIsoLimits` ([photographer-set limits](#photographer-set-auto-iso-limits-505), #505) the maximum in step 4
+is the photographer's `maximum`, and both choices behave there exactly as at the body's maximum: the same settings and
+residual, with `user-iso-maximum` in place of `iso-maximum` when the policy holds the shutter. Shutter Priority
+(`isoControl.policy.autoIsoLimits`), Program Auto (`isoControl.autoIsoLimits`) and Full Auto (`policy.autoIsoLimits`) take
+the same limits.
+
 For discrete shutter grids, the shutter chosen before ISO is raised is never longer than the requested or preferred duration. Otherwise rounding to the grid could overexpose, and undoing that would need an ISO below the supported minimum.
 
 ### Shutter Priority + manual ISO
@@ -5320,6 +5388,107 @@ This policy:
 
 That direction is deliberate. Choosing an aperture wider than the ideal at minimum ISO could overexpose, with no lower ISO left to compensate.
 
+### Automatic slowest shutter (#504)
+
+Cameras let the photographer set the slowest shutter before Auto ISO raises the ISO to "Auto", chosen from the focal
+length, with a bias in 1-stop steps (Sony's ISO AUTO Min. SS: Faster, Fast, Standard, Slow and Slower, 1 EV apart:
+[help guide](https://helpguide.sony.net/ilc/2020/v1/en/contents/TP1000139958.html); Nikon and Fujifilm: see the manuals
+cited above). Those cameras base it on the old reciprocal rule, about 1/focal length. That is a rule of thumb, not physics,
+and the engine does not use it. `estimateAutoIsoSlowestShutter()` derives the threshold from the engine's own camera-shake
+model, `estimateCameraShakeBlur()` ([camera shake](https://github.com/Photivra/photivra/blob/main/docs/STABILIZATION.md#controlled-camera-shake)), the same physics the preview
+shows.
+
+The camera turns at a constant angular velocity ω = (ω_yaw, ω_pitch), reduced by stabilization to r·ω with r = 2^−stops. A
+still point on the optical axis then moves
+
+```text
+b(t) = v · hypot(tan(r·ω_yaw·t), tan(r·ω_pitch·t))
+```
+
+on the sensor, where v is the focal length (or, with `focusDistanceM`, the thin-lens image distance). The derived shutter is
+the time t at which b(t) equals the blur budget. On one axis that is `t = atan(budget / v) / (r·|ω|)` exactly; on two axes
+the engine bisects, which works because b grows strictly with t. Then:
+
+1. the bias: `biased = derived · 2^−fasterByStops`, with `fasterByStops` a whole number from −2 to +2 (+1 is one stop faster);
+2. the grid, optional: with `shutterCapability`, the biased time snaps to the body's shutter grid, never longer, held at its
+   ends.
+
+Composition fragment: requires previously validated bindings `capabilities`. This is an integration sketch, not a standalone runnable program.
+
+```ts
+import {
+  estimateAutoIsoSlowestShutter,
+  GENERIC_HANDHELD_ANGULAR_VELOCITY_RAD_PER_SEC
+} from "@photivra/engine";
+
+const slowest =
+  estimateAutoIsoSlowestShutter({
+    focalLengthMm: 50,
+    angularVelocityRadPerSec:
+      GENERIC_HANDHELD_ANGULAR_VELOCITY_RAD_PER_SEC,
+    stabilizationStopsEquivalent: 0,
+    blurBudget: {
+      kind: "pixels",
+      pixels: 1,
+      pixelPitchMicrometers: 6
+    },
+    fasterByStops: 0,
+    shutterCapability:
+      capabilities.shutter
+  });
+// slowest.value.shutterSeconds: about 1/640 s for 50 mm, 6 µm pixels and the generic hand.
+```
+
+The result reports `derivedShutterSeconds`, `biasedShutterSeconds`, `shutterSeconds` (after the grid), the blur budget and
+the shake model's blur at the derived and the final shutter, the projection distance and the residual-motion factor, as an
+`approximation` with its assumptions. The blur budget is `{ kind: "pixels", pixels, pixelPitchMicrometers }` or
+`{ kind: "image-diagonal-fraction", fraction, imageWidthMm, imageHeightMm }`.
+
+What the tests check: longer focal lengths give faster thresholds; each stabilization stop doubles the time exactly; the
+bias moves it by exact whole stops; the shake model's blur at the derived time equals the budget; nothing is NaN or
+infinite; invalid input fails with a domain error (no shake, a fractional or out-of-range bias, a non-positive budget, a
+quarter turn of motion).
+
+**The hand-shake profile is an input.** No free source gives one angular velocity for every photographer and camera.
+`GENERIC_HANDHELD_ANGULAR_VELOCITY_RAD_PER_SEC` is a **labelled generic default**: 4.39 °/s (≈ 0.0766 rad/s), on yaw. It is the
+linear camera-motion rate F. Xiao, J. Farrell, P. Catrysse and B. Wandell use for an average user holding a typical 100 g
+mobile handset with two hands ("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
+take it from their earlier gyroscope measurements, F. Xiao et al., "Camera-motion and mobile imaging", Proc. SPIE 6502
+(2007), which report that the motion is close to linear for exposures under about 100 ms. It is one magnitude, so the
+engine puts it on yaw; for small angles the blur length does not depend on the direction. A heavier camera, another grip
+or another photographer moves differently, so pass your own profile when you have one.
+
+**Approximations.** Constant angular velocity, blur on the optical axis only, stabilization as 2^−stops (the educational
+model of `estimateCameraShakeBlur()`, not a CIPA DC-011 rating), no roll, translation or subject motion. The blur budget is
+your choice of sharpness, not a measured threshold.
+
+#### Through `simulateCapture`
+
+`exposure.autoIso.slowestPreferredShutterSeconds: "auto"` (aperture priority; optional in program) calls
+`estimateAutoIsoSlowestShutter()` with the request's focal length, focus distance, pixel pitch and the body's shutter range.
+`exposure.autoIso.automaticSlowestShutter` sets `fasterByStops` (default 0), `blurBudgetPixels` (default 1, a generic
+pixel-level budget), `angularVelocityRadPerSec` (default the generic hand above) and `stabilizationStopsEquivalent` (default 0:
+the tiers declare none). Each default is recorded as a `default` assumption. The report's `exposure.autoIso.automaticSlowestShutter`
+gives the derived, biased and used times and the blur at the used time in pixels.
+
+### Program Auto with Auto ISO: a slowest preferred shutter (#504)
+
+`resolveProgramAutoExposureMode()` optionally takes
+`isoControl.slowestPreferredShutter: { slowestPreferredShutterSeconds, afterMaximumIso }`
+(`ProgramSlowestPreferredShutterPolicy`), the same two-axis policy as Aperture Priority + Auto ISO:
+
+1. Follow the program line at the lowest selectable ISO.
+2. If the line's shutter is longer than `slowestPreferredShutterSeconds`, hold the shutter there (snapped, never longer),
+   keep the line's aperture, and raise the ISO.
+3. At the Auto ISO maximum (the body's or the photographer's `autoIsoLimits`), `"allow-slower-shutter"` lengthens the shutter
+   toward the target, but never past the line's own shutter. `"hold-preferred-shutter"` keeps the shutter there and reports
+   the residual.
+
+The result adds `slowestPreferredShutter: { ..., applied, afterMaximumIsoFallbackUsed }`; `programLineSelection` stays the
+line's own selection. Without the option the resolver behaves as before and reports no such field. Full Auto exposure does
+not take the option.
+
 ### Shared boundaries
 
 These are control policies over the same relative exposure equation. They create no new optics or sensor physics.
@@ -6882,6 +7051,31 @@ try { parseDngRawImage({ bytes: png }); } catch { rejected = true; }
 if (!rejected) throw new Error('A PNG must not parse as a DNG');
 ```
 
+## Text metadata on a file you encoded
+
+`addJpegTextMetadata(jpeg, metadata)` and `addPngTextMetadata(png, metadata)` (#388) add the caller's text to a JPEG
+or PNG that was encoded without `output.metadata`: for example a full-size file joined from `output.region` parts
+and encoded with `composePrintJpegStrips` or `serializePngImage`. They are the functions that `output.metadata`
+calls, so for the same file and text the bytes are the same as a whole-frame `simulateCapture` with
+`output.metadata`. The text is checked as `output.metadata` is (see
+[Text metadata](https://github.com/Photivra/photivra/blob/main/docs/QUICK_START.md#text-metadata-24)); invalid text or a
+malformed file fails with `InvalidConfigurationError`. The input array is not changed.
+
+```ts
+import { addJpegTextMetadata, addPngTextMetadata, serializePngImage, simulateCapture } from '@photivra/engine';
+
+const text = { description: 'Siemens star at f/8', software: 'My Viewer 1.0', comment: 'Test run 3' };
+// A PNG the caller encoded (here one sRGB pixel) gets the PNG text chunks.
+const png = addPngTextMetadata(serializePngImage({ width: 1, height: 1, bitDepth: 8, samples: Uint8Array.of(255, 128, 0),
+  colourEncoding: { kind: 'srgb', renderingIntent: 'perceptual' } }), text);
+// A JPEG written without output.metadata and tagged afterwards has the bytes of one written with it.
+const plain = await simulateCapture({ scene: { preset: 'siemens-star' }, output: { width: 8, height: 8, format: 'jpeg' } });
+const direct = await simulateCapture({ scene: { preset: 'siemens-star' }, output: { width: 8, height: 8, format: 'jpeg', metadata: text } });
+const tagged = addJpegTextMetadata(plain.image.jpeg!, text);
+const same = tagged.length === direct.image.jpeg!.length && tagged.every((byte, i) => byte === direct.image.jpeg![i]);
+console.log(png.length, same);
+```
+
 ## Native-only Print planning
 
 - [Registered linear statistics](https://github.com/Photivra/photivra/blob/main/docs/PRINT_REGION_STATISTICS.md) tell apart changes caused by processing the same capture from variation between repeated captures at each site.
@@ -7497,13 +7691,46 @@ const star = await simulateCapture({
   output: { width: 12, height: 8, toneCurve: "positive-reinhard-per-channel", whiteBalance: { kelvin: 5000 } }
 });
 
-console.log(star.exposure.settings.shutterSeconds, star.exposure.ev100);
+console.log(star.exposure.settings.shutterSeconds, star.exposure.ev100, star.exposure.standardExposureDeviationStops);
 console.log(star.assumptions.filter((a) => a.kind === "default").map((a) => a.id));
 console.log(star.request.siteInput(0).environment.optics.nominalFNumber);
 ```
 
 In `aperture-priority` mode, the shutter comes from the meter (CIPA DC-004 relations S = 10/H and H = 0.65·L·t/N²) through
 `resolveAperturePriorityExposureMode()`.
+`exposure.standardExposureDeviationStops` is the exposure used minus the standard exposure for the metered luminance L, in stops,
+log₂(N²/t) − log₂(0.65·L·S/10) from the same relations: positive is darker (under), negative brighter (over). In an automatic
+mode it is minus the compensation plus any limit the resolver hit; it is `null` only for a scene with no metered luminance.
+`exposure.standardExposureIlluminanceLux` is the illuminance at which those settings give the standard exposure, E·2^Δ for the
+request's illuminance E (a reflective scene's metered luminance is proportional to E); `null` for a black scene or a
+`radiance-function` scene. The display view's `exposure` carries the same values.
+
+With `exposure.iso: "auto"` (#516) the ISO is chosen too, in every mode, by the resolvers' Auto ISO branches
+([Priority modes with Auto ISO](#priority-modes-with-auto-iso)). Aperture priority then needs the slowest shutter
+before the ISO rises, and takes the policy at the maximum ISO; the result reports the ISO, that it was automatic and
+what limited it. `exposure.autoIso.limits: { maximum, minimum? }` (#505) sets the photographer's Auto ISO range in any
+mode ([photographer-set limits](#photographer-set-auto-iso-limits-505)). `slowestPreferredShutterSeconds: "auto"` (#504)
+derives the slowest shutter from the camera-shake model, in aperture priority and, optionally, program
+([automatic slowest shutter](#automatic-slowest-shutter-504)). See [Auto ISO](QUICK_START.md#auto-iso-516).
+
+```ts
+import { prepareDisplayView, simulateCapture, type SimulateCaptureOptions } from "@photivra/engine";
+
+const request: SimulateCaptureOptions = {
+  exposure: { mode: "aperture-priority", iso: "auto", autoIso: { slowestPreferredShutterSeconds: 1 / 125 } },
+  lens: { fNumber: 4 },
+  scene: { preset: "siemens-star" },
+  illuminanceLux: 50,
+  output: { width: 16, height: 12 }
+};
+const capture = await simulateCapture(request);
+const { settings, isoControl, autoIso } = capture.exposure;
+// For example "ISO 3200 · Auto", and why: "iso-grid-quantization", or "iso-maximum" with the shutter held.
+console.log(`ISO ${settings.iso} · ${isoControl === "automatic" ? "Auto" : ""}`, autoIso?.limitingConstraint, autoIso?.afterMaximumIsoFallbackUsed);
+// The display view of the same request resolves the same exposure.
+const view = await (await prepareDisplayView(request)).render({ width: 8, height: 6 });
+console.log(view.exposure.settings.iso === settings.iso);
+```
 
 The chart presets are also available on their own:
 
@@ -7547,6 +7774,12 @@ console.log(ran.backend, ran.fallbackReason, ran.assurance, ran.errorBound, ran.
 prepared.dispose(); // releases a device the view acquired; a shared accelerator's device stays its owner's
 ```
 
+The GPU code (the session, the renderers and their WGSL, about 52 kB gzip) is imported only when `gpu` is `"auto"` or
+`"require"`, so a bundler that splits dynamic imports leaves it out of a page's first load. A build that cannot split inlines
+it: Vite builds workers as `iife` by default, so a worker that calls `prepareDisplayView` carries it; build workers as ES
+modules (`worker: { format: "es" }`, with `new Worker(url, { type: "module" })`) to keep it out. Measured sizes:
+[Bundle size](https://github.com/Photivra/photivra/blob/main/docs/DISPLAY_VIEW.md#bundle-size).
+
 #### Sharing AHD correction states between workers
 
 With `output.demosaic: "ahd"`, low-signal display pixels read correction states that each realm (a page, a Web Worker)

package/docs/api/core-version.md

@@ -11,5 +11,5 @@ version they were made with. Proof-of-concept (POC), schema and model contracts
 own versions. Release checks confirm it matches package.json and the packed package.
 
 ```ts
-ENGINE_API_VERSION = "2.11.1" as const
+ENGINE_API_VERSION = "2.13.0" as const
 ```

package/docs/api/exports.json

@@ -1,6 +1,6 @@
 {
-  "packageVersion": "2.11.1",
-  "engineApiVersion": "2.11.1",
+  "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",
@@ -8127,6 +8182,26 @@
       "source": "src/facade/simulate-capture.ts",
       "kind": "type"
     },
+    {
+      "name": "SimulateCaptureAutoIsoAfterMaximum",
+      "source": "src/facade/simulate-capture.ts",
+      "kind": "type"
+    },
+    {
+      "name": "SimulateCaptureAutoIsoReport",
+      "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 })
+```