@photivra/engine 1.4.0 → 2.0.0

package/docs/api/exposure-exposure-duration-control.md

@@ -1,13 +1,13 @@
 # exposure/exposure-duration-control.ts public contracts
 
-Package **1.4.0**, root API **1.4.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../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.
+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.
 
 ## bindResolvedExposureDurationToCaptureExposureInput
 
-Binds a resolved duration into the authoritative #12 exposure-window input.
+Puts a resolved duration into the capture exposure-window input.
 
-The existing shutter mechanism/opening/closing schedules remain untouched.
-Only the seconds-valued nominal duration is supplied here.
+The existing shutter mechanism and opening/closing schedules are left as
+they are. Only the nominal duration, in seconds, is supplied.
 
 ```ts
 export function bindResolvedExposureDurationToCaptureExposureInput(
@@ -99,12 +99,12 @@ export type ExposureDurationControlResolution =
 
 ## resolveExposureDurationControl
 
-Resolves shutter-duration control semantics to a concrete positive elapsed
-duration before physical exposure integration.
+Turns a shutter-duration control setting into a concrete, positive elapsed
+duration, before the physical exposure is integrated.
 
-Bulb and Time are control behaviors only. Neither implies a shutter
-mechanism, exposure-boundary topology, tripod, stabilization state, long
-exposure NR, or temperature model.
+Bulb and Time are only control behaviours. Neither implies a shutter
+mechanism, an exposure-boundary layout, a tripod, a stabilization state,
+long-exposure noise reduction (NR) or a temperature model.
 
 ```ts
 export function resolveExposureDurationControl(

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

@@ -1,6 +1,6 @@
 # exposure/exposure-mode-resolver.ts public contracts
 
-Package **1.4.0**, root API **1.4.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../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.
+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.
 
 ## AperturePriorityAutoIsoExposureModeResolution
 
@@ -625,13 +625,14 @@ export interface RelativeExposureControlAnchor {
 
 ## resolveAperturePriorityAutoIsoExposureMode
 
-Hold aperture fixed, follow the declared minimum-shutter policy and use bounded Auto ISO to absorb
-remaining target residual.
+Aperture Priority with Auto ISO. Keeps the aperture fixed, follows the declared minimum-shutter
+policy, and uses Auto ISO (within its limits) to make up the rest of the exposure.
 
-Exposure modes apply control policy to one shared relative exposure equation and an explicit
-reference anchor. Compensation is already included in the immutable meter target. Manual axes remain
-unchanged; automatic axes use declared setting grids and expose signed residual stops and limit
-diagnostics. A zero-signal target cannot authorize an invented exposure.
+Every exposure mode applies its control policy to one shared relative exposure equation, with an
+explicit reference anchor. Exposure compensation is already part of the frozen meter target. Manual
+settings are never changed. Automatic settings snap to the declared setting grids, and the result
+reports the signed leftover (residual) stops and any limits hit. A target with zero signal cannot
+be used to make up an exposure.
 
 ```ts
 export function resolveAperturePriorityAutoIsoExposureMode(
@@ -662,9 +663,9 @@ export interface ResolveAperturePriorityAutoIsoExposureModeInput {
 
 Resolves Aperture Priority with manual ISO.
 
-Aperture and ISO remain caller-owned. Shutter is the only automatic axis.
-The target/reference relationship is the same relative exposure model used
-by Manual + Auto ISO; no new mode-specific exposure equation is introduced.
+The caller sets aperture and ISO. Only the shutter is automatic. The target
+and reference use the same relative exposure model as Manual + Auto ISO; no
+new exposure equation is added for this mode.
 
 ```ts
 export function resolveAperturePriorityExposureMode(
@@ -695,13 +696,14 @@ export interface ResolveAperturePriorityExposureModeInput {
 
 ## resolveFullAutoExposureMode
 
-Resolve aperture, shutter and ISO under an explicit generic Full Auto exposure policy. Autofocus,
-WB, flash, drive and scene recognition remain unresolved.
+Full Auto. Chooses aperture, shutter and ISO under an explicit generic Full Auto exposure policy.
+Autofocus, white balance (WB), flash, drive mode and scene recognition are not resolved.
 
-Exposure modes apply control policy to one shared relative exposure equation and an explicit
-reference anchor. Compensation is already included in the immutable meter target. Manual axes remain
-unchanged; automatic axes use declared setting grids and expose signed residual stops and limit
-diagnostics. A zero-signal target cannot authorize an invented exposure.
+Every exposure mode applies its control policy to one shared relative exposure equation, with an
+explicit reference anchor. Exposure compensation is already part of the frozen meter target. Manual
+settings are never changed. Automatic settings snap to the declared setting grids, and the result
+reports the signed leftover (residual) stops and any limits hit. A target with zero signal cannot
+be used to make up an exposure.
 
 ```ts
 export function resolveFullAutoExposureMode(
@@ -732,9 +734,9 @@ export interface ResolveFullAutoExposureModeInput {
 
 Resolves Manual exposure with either manual ISO or Auto ISO.
 
-Aperture and shutter are always caller-owned and are never changed.
-The relative meter target is normalized by an explicit reference exposure
-anchor; no ISO-100 or other hidden absolute calibration is assumed.
+The caller sets aperture and shutter; they are never changed. The relative
+meter target is normalized by an explicit reference exposure anchor. No
+ISO 100 or other hidden absolute calibration is assumed.
 
 ```ts
 export function resolveManualExposureMode(
@@ -764,13 +766,14 @@ export interface ResolveManualExposureModeInput {
 
 ## resolveProgramAutoExposureMode
 
-Evaluate the declared generic program line in log2 exposure space, quantize aperture/shutter and
-optionally use Auto ISO for residual exposure.
+Program auto exposure. Follows the declared generic program line in log2 exposure space, snaps
+aperture and shutter to their grids, and can use Auto ISO for any exposure left over.
 
-Exposure modes apply control policy to one shared relative exposure equation and an explicit
-reference anchor. Compensation is already included in the immutable meter target. Manual axes remain
-unchanged; automatic axes use declared setting grids and expose signed residual stops and limit
-diagnostics. A zero-signal target cannot authorize an invented exposure.
+Every exposure mode applies its control policy to one shared relative exposure equation, with an
+explicit reference anchor. Exposure compensation is already part of the frozen meter target. Manual
+settings are never changed. Automatic settings snap to the declared setting grids, and the result
+reports the signed leftover (residual) stops and any limits hit. A target with zero signal cannot
+be used to make up an exposure.
 
 ```ts
 export function resolveProgramAutoExposureMode(
@@ -801,13 +804,14 @@ export interface ResolveProgramAutoExposureModeInput {
 
 ## resolveShutterPriorityExposureMode
 
-Hold shutter fixed and resolve aperture plus optional Auto ISO against the exact capability
-envelope.
+Shutter Priority. Keeps the shutter fixed and chooses the aperture, plus optional Auto ISO, within
+exactly what the equipment can do.
 
-Exposure modes apply control policy to one shared relative exposure equation and an explicit
-reference anchor. Compensation is already included in the immutable meter target. Manual axes remain
-unchanged; automatic axes use declared setting grids and expose signed residual stops and limit
-diagnostics. A zero-signal target cannot authorize an invented exposure.
+Every exposure mode applies its control policy to one shared relative exposure equation, with an
+explicit reference anchor. Exposure compensation is already part of the frozen meter target. Manual
+settings are never changed. Automatic settings snap to the declared setting grids, and the result
+reports the signed leftover (residual) stops and any limits hit. A target with zero signal cannot
+be used to make up an exposure.
 
 ```ts
 export function resolveShutterPriorityExposureMode(

package/docs/api/exposure-exposure.md

@@ -1,12 +1,12 @@
 # exposure/exposure.ts public contracts
 
-Package **1.4.0**, root API **1.4.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../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.
+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.
 
 ## calculateEquivalentIso
 
-Calculates the ISO/gain setting that preserves nominal rendered exposure
-after changing aperture and/or shutter, assuming all other factors remain
-constant.
+Calculates the ISO (gain) setting that keeps the nominal rendered exposure
+the same after aperture, shutter or both change. Assumes nothing else
+changes.
 
 This is an exposure-compensation relation, not a sensor-noise model.
 
@@ -62,8 +62,8 @@ export interface CalculateExposureValue100Input {
 Compares image-plane optical exposure using the proportional relation
 shutterSeconds / aperture^2.
 
-This does not include scene light, lens transmission, vignetting, or sensor
-response and therefore must not be interpreted as a photon-count result.
+This does not include scene light, lens transmission, vignetting or sensor
+response. Do not read it as a photon count.
 
 ```ts
 export function calculateRelativeOpticalExposure(
@@ -91,10 +91,10 @@ export interface CalculateRelativeOpticalExposureInput {
 Calculates a relative linear rendering exposure from aperture, shutter, and
 nominal ISO gain.
 
-This relation is intended for deterministic educational rendering relative to
-a declared reference exposure. ISO is treated as a brightness/gain control;
-it does not create photons and this function does not model sensor noise,
-clipping, tone mapping, lens transmission, or absolute scene luminance.
+This relation is for deterministic educational rendering, relative to a
+declared reference exposure. ISO is treated as a brightness (gain) control;
+it does not create photons. This function does not model sensor noise,
+clipping, tone mapping, lens transmission or absolute scene luminance.
 
 ```ts
 export function calculateRelativeRenderedExposure(

package/docs/api/exposure-flash-ttl.md

@@ -0,0 +1,182 @@
+# exposure/flash-ttl.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.
+
+## calculateFlashGuideNumber
+
+Effective guide number GN = GN_full · √p · √(ISO/100).
+
+The guide number relation GN = d·N follows from the inverse-square law. Light on the subject from a
+point-like flash falls as 1/d², and sensor exposure falls as 1/N². So exposure stays correct while
+d·N is constant (camera equation H = 0.65·L·t/N² and reference exposure H = 10/S, CIPA DC-004-2020,
+free). Exposure grows linearly with emitted energy (power fraction p), and the exposure needed falls
+inversely with ISO speed. So GN ∝ √p·√ISO. The engine does not model how a guide number is measured;
+the caller supplies it.
+
+```ts
+export function calculateFlashGuideNumber(input: FlashGuideNumberInput): number;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## calculateFlashPowerForDistance
+
+Manual guide-number exposure: the power fraction that exposes a subject at distance d correctly.
+
+```ts
+export function calculateFlashPowerForDistance(input: FlashPowerForDistanceInput): FlashPowerForDistance;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## createTtlScaledFlashProfile
+
+Returns a copy of a manual flash profile with its relative output scaled by a resolved TTL power
+fraction, ready for resolveManualFlashSync (front/rear curtain). For high-speed sync, instead pass
+the unscaled profile, and pass `ttl.powerFraction` as resolveHighSpeedFlashSync's powerFraction.
+That way power is applied only once.
+
+```ts
+export function createTtlScaledFlashProfile(flashProfile: ManualFlashProfile, ttl: TtlFlashExposure): ManualFlashProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## FlashGuideNumberInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface FlashGuideNumberInput {
+  /** Guide number at full power for ISO 100, in metres (GN = distance · f-number). */
+  fullPowerGuideNumberMetersIso100: number;
+  /** Output as a fraction of full power, (0, 1]. */
+  powerFraction: number;
+  iso: number;
+}
+```
+
+## FlashPowerForDistance
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface FlashPowerForDistance {
+  /** p = (d·N / (GN_full·√(ISO/100)))², before clamping. */
+  requiredPowerFraction: number;
+  powerFraction: number;
+  status: "within-range" | "clamped-at-minimum-power" | "clamped-at-full-power";
+  /** log2(delivered / required) flash exposure; positive is overexposure. */
+  flashExposureErrorStops: number;
+  /** GN_full·√(ISO/100)/N: the farthest correctly exposed distance at full power. */
+  maximumDistanceM: number;
+}
+```
+
+## FlashPowerForDistanceInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface FlashPowerForDistanceInput {
+  fullPowerGuideNumberMetersIso100: number;
+  subjectDistanceM: number;
+  apertureFNumber: number;
+  iso: number;
+  /** Lowest available power fraction, (0, 1]. */
+  minimumPowerFraction: number;
+}
+```
+
+## resolveTtlFlashExposure
+
+Solves the main-flash power from a pre-flash measurement (manufacturer-independent TTL).
+
+The meter is linear for the policies allowed here: M(a + b) = M(a) + M(b).
+- The pre-flash at power p_pre adds a flash-only signal f_i = pre_i − ambient_i in each zone.
+- Flash signal is proportional to emitted energy, so at main power p it adds (p/p_pre)·M(f).
+- With ambient scaled to the main exposure by k, the metered total is k·A + p·F, where
+  F = M(f)/p_pre.
+- Setting this equal to the target T' = T·2^FEC gives p = (T' − k·A)/(F·s). Here s is the sync
+  energy factor (1 for ordinary sync, η·t_e/D for high-speed sync).
+- p is clamped to [p_min, 1], the guide-number range.
+Highlight policies are rejected: their weights depend on the signal, so the total is no longer
+linear in p.
+
+```ts
+export function resolveTtlFlashExposure(input: ResolveTtlFlashExposureInput): CalculationResult<TtlFlashExposure>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolveTtlFlashExposureInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolveTtlFlashExposureInput {
+  /** Spatially linear metering profile (multi-zone-uniform, center-weighted-radial or spot). */
+  meteringProfile: ExposureMeteringProfile;
+  /** Measurement-window samples with the flash off. */
+  ambientSampleSet: ExposureMeteringSampleSet;
+  /** The same zones and settings with the pre-flash fired. */
+  preFlashSampleSet: ExposureMeteringSampleSet;
+  /** Pre-flash output as a fraction of full power, (0, 1]. */
+  preFlashPowerFraction: number;
+  /**
+   * Ratio of ambient light collected in the main exposure to that in the measurement window, at the
+   * same aperture and ISO (for example t_main/t_measure). Must be ≥ 0. The flash pulse falls inside
+   * both windows, so it is not scaled.
+   */
+  ambientScaleToMainExposure: number;
+  /** Flash exposure compensation applied to the TTL target, in stops. */
+  flashExposureCompensationStops: number;
+  /** Lowest available main-flash power fraction, (0, 1]. */
+  minimumPowerFraction: number;
+  /**
+   * Flash energy each line receives, relative to an ordinary pulse at the same power fraction. 1 for
+   * front/rear-curtain sync; η·t_e/D for high-speed sync (see resolveHighSpeedFlashSync). Defaults to 1.
+   */
+  syncEnergyFactor?: number;
+  /** Optional guide-number reporting. */
+  guideNumber?: { fullPowerGuideNumberMetersIso100: number; iso: number; apertureFNumber: number };
+}
+```
+
+## TTL_FLASH_MODEL
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+TTL_FLASH_MODEL = Object.freeze({ id: "preflash-linear-ttl", version: "1.0.0" } as const)
+```
+
+## TtlFlashExposure
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface TtlFlashExposure {
+  modelId: typeof TTL_FLASH_MODEL.id;
+  modelVersion: typeof TTL_FLASH_MODEL.version;
+  status: "resolved" | "clamped-at-minimum-power" | "clamped-at-full-power" | "no-flash-return";
+  /** Metered ambient signal in the main exposure: k·M(ambient). */
+  ambientMainExposureMeteredSignal: number;
+  /** Metered flash-only signal per unit full power: M(preflash − ambient)/p_pre. */
+  flashMeteredSignalPerFullPower: number;
+  /** T·2^FEC. */
+  targetRelativeSignal: number;
+  /** Unclamped solution (T' − k·A)/(F·syncEnergyFactor); null with no flash return. */
+  requiredPowerFraction: number | null;
+  /** Commanded main-flash power fraction (clamped); null with no flash return. */
+  powerFraction: number | null;
+  ambientAloneReachesTarget: boolean;
+  predictedMeteredSignal: number;
+  /** log2(predicted / target); 0 when the solution is within range; null when nothing is predicted. */
+  predictedExposureErrorStops: number | null;
+  effectiveGuideNumberMetersAtIso: number | null;
+  flashRangeAtApertureM: number | null;
+  preFlashInsideMainExposure: false;
+  ambientMeteringModified: false;
+}
+```