@photivra/engine 0.6.0 → 1.0.1

package/docs/api/exposure-exposure.md

@@ -0,0 +1,150 @@
+# exposure/exposure.ts public contracts
+
+Package **1.0.1**, root API **1.0.1**. [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.
+
+## calculateEquivalentIso
+
+Calculates the ISO/gain setting that preserves nominal rendered exposure
+after changing aperture and/or shutter, assuming all other factors remain
+constant.
+
+This is an exposure-compensation relation, not a sensor-noise model.
+
+```ts
+export function calculateEquivalentIso(
+  input: CalculateEquivalentIsoInput
+): CalculationResult<number>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateEquivalentIsoInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateEquivalentIsoInput {
+  baseIso: number;
+  baseAperture: number;
+  baseShutterSeconds: number;
+  aperture: number;
+  shutterSeconds: number;
+}
+```
+
+## calculateExposureValue100
+
+Calculates EV100 from aperture and shutter duration.
+
+```ts
+export function calculateExposureValue100(
+  input: CalculateExposureValue100Input
+): CalculationResult<number>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateExposureValue100Input
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateExposureValue100Input {
+  /** F-number. */
+  aperture: number;
+  /** Shutter duration in seconds. */
+  shutterSeconds: number;
+}
+```
+
+## calculateRelativeOpticalExposure
+
+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.
+
+```ts
+export function calculateRelativeOpticalExposure(
+  input: CalculateRelativeOpticalExposureInput
+): CalculationResult<RelativeOpticalExposure>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateRelativeOpticalExposureInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateRelativeOpticalExposureInput {
+  aperture: number;
+  shutterSeconds: number;
+  referenceAperture: number;
+  referenceShutterSeconds: number;
+}
+```
+
+## calculateRelativeRenderedExposure
+
+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.
+
+```ts
+export function calculateRelativeRenderedExposure(
+  input: CalculateRelativeRenderedExposureInput
+): CalculationResult<RelativeRenderedExposure>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateRelativeRenderedExposureInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateRelativeRenderedExposureInput {
+  aperture: number;
+  shutterSeconds: number;
+  iso: number;
+  referenceAperture: number;
+  referenceShutterSeconds: number;
+  referenceIso: number;
+}
+```
+
+## RelativeOpticalExposure
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface RelativeOpticalExposure {
+  /** Relative light exposure at the image plane; 1 equals the reference. */
+  factor: number;
+  /** Difference from the reference in stops. Positive means more light exposure. */
+  stops: number;
+}
+```
+
+## RelativeRenderedExposure
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface RelativeRenderedExposure {
+  /** Nominal linear rendering multiplier; 1 equals the reference settings. */
+  factor: number;
+  /** Difference from the reference in stops. Positive means a brighter rendering. */
+  stops: number;
+  /** Image-plane optical exposure ratio before nominal ISO gain. */
+  opticalFactor: number;
+  /** Nominal ISO gain ratio relative to the reference ISO. */
+  isoGainFactor: number;
+}
+```

package/docs/api/exposure-flash.md

@@ -0,0 +1,327 @@
+# exposure/flash.ts public contracts
+
+Package **1.0.1**, root API **1.0.1**. [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.
+
+## createManualFlashIlluminationOverlay
+
+Construct an owned registered temporal illumination overlay from the resolved manual pulse while
+preserving base ambient source identity.
+
+Manual flash is a registered relative pulse/source overlay on the capture opening-reference clock.
+Ordinary front/rear sync requires a real whole-frame opening interval. HSS/TTL and flash metering
+are unsupported here; source magnitude, optical transport and sensor integration retain their own
+contracts.
+
+```ts
+export function createManualFlashIlluminationOverlay(
+  input:
+    CreateManualFlashIlluminationOverlayInput
+): ManualFlashIlluminationOverlay;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CreateManualFlashIlluminationOverlayInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CreateManualFlashIlluminationOverlayInput {
+  baseIlluminationProfile:
+    SceneIlluminationProfile;
+  baseTemporalProfile?:
+    SceneIlluminationTemporalProfile;
+  flashProfile:
+    ManualFlashProfile;
+  resolvedSync:
+    ResolvedManualFlashSync;
+  illuminationProfileId: string;
+  temporalProfileId: string;
+}
+```
+
+## FLASH_SYNC_CAPABILITY_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+FLASH_SYNC_CAPABILITY_SCHEMA_VERSION =
+  "0.1.0" as const
+```
+
+## FlashSyncCapabilityProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface FlashSyncCapabilityProfile {
+  schemaVersion:
+    typeof FLASH_SYNC_CAPABILITY_SCHEMA_VERSION;
+  profileId: string;
+  profileVersion: string;
+  captureModeId: string;
+  timingProfileId: string;
+  supportedOrdinarySyncModes:
+    readonly ManualFlashSyncMode[];
+  highSpeedSyncSupported: false;
+  ordinarySyncRequiresWholeActiveFrameSimultaneouslyExposed:
+    true;
+  evidence: readonly EvidenceProvenance[];
+  limitations: readonly string[];
+}
+```
+
+## MANUAL_FLASH_PROFILE_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+MANUAL_FLASH_PROFILE_SCHEMA_VERSION =
+  "0.1.0" as const
+```
+
+## ManualFlashIlluminationOverlay
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ManualFlashIlluminationOverlay {
+  flashApplied: boolean;
+  illuminationProfile:
+    SceneIlluminationProfile;
+  temporalProfile:
+    SceneIlluminationTemporalProfile | null;
+  sourceId: string;
+  waveformId: string;
+  timeReference:
+    "first-opening-boundary-phase";
+  sourceMagnitudeAppliedBySceneTransport:
+    true;
+  materialTransportOwnedBySceneRadiance:
+    true;
+  visibilityOwnedBySceneRadiance:
+    true;
+  indirectTransportOwnedBySceneRadiance:
+    true;
+  postRenderBrightnessMultiplierUsed:
+    false;
+  whiteBalanceModified: false;
+  ambientMeteringModified: false;
+  ttlMeteringIncluded: false;
+  ambientTemporalBehaviorPreserved:
+    true;
+}
+```
+
+## ManualFlashProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ManualFlashProfile {
+  schemaVersion:
+    typeof MANUAL_FLASH_PROFILE_SCHEMA_VERSION;
+  profileId: string;
+  profileVersion: string;
+  sourceTemplate:
+    Omit<
+      SceneIlluminationSource,
+      "enabled" |
+      "temporalBehavior"
+    >;
+  pulse:
+    ManualFlashPulseProfile;
+  outputControl: {
+    kind:
+      "relative-linear-source-scale";
+    scale: number;
+    flashExposureCompensationStops:
+      0;
+  };
+  ttlModeled: false;
+  highSpeedSyncModeled: false;
+  recycleBehaviorModeled: false;
+  redEyePreflashModeled: false;
+  modelingLightModeled: false;
+  afAssistModeled: false;
+  evidence: readonly EvidenceProvenance[];
+  limitations: readonly string[];
+}
+```
+
+## ManualFlashPulseProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ManualFlashPulseProfile {
+  waveformId: string;
+  scientificStatus: "approximation";
+  supportDurationSeconds: number;
+  interpolation: "piecewise-linear";
+  samples:
+    readonly SceneIlluminationTemporalWaveformSample[];
+  normalization:
+    "relative-peak-one";
+  evidence:
+    readonly EvidenceProvenance[];
+  limitations: readonly string[];
+}
+```
+
+## ManualFlashSyncMode
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ManualFlashSyncMode =
+  | "front-curtain"
+  | "rear-curtain";
+```
+
+## parseFlashSyncCapabilityProfile
+
+Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
+missing required fields and incompatible scientific data fail at this boundary.
+
+Manual flash is a registered relative pulse/source overlay on the capture opening-reference clock.
+Ordinary front/rear sync requires a real whole-frame opening interval. HSS/TTL and flash metering
+are unsupported here; source magnitude, optical transport and sensor integration retain their own
+contracts.
+
+```ts
+export function parseFlashSyncCapabilityProfile(
+  value: unknown
+): FlashSyncCapabilityProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## parseManualFlashProfile
+
+Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
+missing required fields and incompatible scientific data fail at this boundary.
+
+Manual flash is a registered relative pulse/source overlay on the capture opening-reference clock.
+Ordinary front/rear sync requires a real whole-frame opening interval. HSS/TTL and flash metering
+are unsupported here; source magnitude, optical transport and sensor integration retain their own
+contracts.
+
+```ts
+export function parseManualFlashProfile(
+  value: unknown
+): ManualFlashProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## RequestedFlashSyncMode
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type RequestedFlashSyncMode =
+  | ManualFlashSyncMode
+  | "high-speed-sync";
+```
+
+## ResolvedManualFlashSync
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolvedManualFlashSync {
+  flashEnabled: boolean;
+  flashProfileId: string;
+  flashProfileVersion: string;
+  sourceId: string;
+  captureModeId: string;
+  timingProfileId: string;
+  syncCapabilityProfileId:
+    string;
+  syncMode:
+    RequestedFlashSyncMode;
+  syncStatus:
+    | "disabled"
+    | "ordinary-sync-resolved";
+  timeReference:
+    "first-opening-boundary-phase";
+  wholeActiveFrameOpenInterval:
+    {
+      startSecondsFromCaptureReference:
+        number;
+      endSecondsFromCaptureReference:
+        number;
+      durationSeconds: number;
+    };
+  pulseSupportDurationSeconds:
+    number;
+  pulseStartSecondsFromCaptureReference:
+    number | null;
+  pulseEndSecondsFromCaptureReference:
+    number | null;
+  waveformTimeZeroSecondsFromCaptureReference:
+    number | null;
+  releaseFrameBinding:
+    | {
+        sequenceId: string;
+        releaseFrameId: string;
+        frameIndex: number;
+        sceneTimeSecondsFromSequenceStartAtPulseStart:
+          number;
+        sceneTimeSecondsFromSequenceStartAtPulseEnd:
+          number;
+      }
+    | null;
+  hssModeled: false;
+  ttlModeled: false;
+  sensorReadoutTimingUsedAsExposureTiming:
+    false;
+  whiteBalanceModified: false;
+  focusModified: false;
+  exposureSettingsModified: false;
+  driveModeModified: false;
+  supportStateModified: false;
+  evidence: readonly EvidenceProvenance[];
+  limitations: readonly string[];
+}
+```
+
+## resolveManualFlashSync
+
+Place a declared ordinary flash pulse into the actual whole-frame exposure opening interval for
+front or rear sync, or return structured incompatibility.
+
+Manual flash is a registered relative pulse/source overlay on the capture opening-reference clock.
+Ordinary front/rear sync requires a real whole-frame opening interval. HSS/TTL and flash metering
+are unsupported here; source magnitude, optical transport and sensor integration retain their own
+contracts.
+
+```ts
+export function resolveManualFlashSync(
+  input:
+    ResolveManualFlashSyncInput
+): ResolvedManualFlashSync;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolveManualFlashSyncInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolveManualFlashSyncInput {
+  flashEnabled: boolean;
+  flashProfile:
+    ManualFlashProfile;
+  syncCapabilities:
+    FlashSyncCapabilityProfile;
+  timing:
+    ResolvedCaptureModeTiming;
+  syncMode:
+    RequestedFlashSyncMode;
+  releaseFrame?:
+    ResolvedReleaseFrame;
+}
+```

package/docs/api/exposure-metering-scene-radiance.md

@@ -0,0 +1,154 @@
+# exposure/metering-scene-radiance.ts public contracts
+
+Package **1.0.1**, root API **1.0.1**. [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.
+
+## createSceneRadianceDerivedExposureMeteringSampleSet
+
+Creates a relative pre-exposure meter sample set bound to one validated #85
+provider context.
+
+The caller/renderer still supplies the scalar relative samples. This bridge
+validates identity and timing semantics only; it does not convert spectral
+radiance into luminance or define a calibrated meter spectral response.
+
+```ts
+export function createSceneRadianceDerivedExposureMeteringSampleSet(
+  input:
+    CreateSceneRadianceDerivedExposureMeteringSampleSetInput
+): SceneRadianceDerivedExposureMeteringSampleSet;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CreateSceneRadianceDerivedExposureMeteringSampleSetInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CreateSceneRadianceDerivedExposureMeteringSampleSetInput {
+  measurementId: string;
+  sceneStateId: string;
+  providerProfile:
+    SceneRadianceProviderProfile;
+  illuminationProfile:
+    SceneIlluminationProfile;
+  materialResponseProfile:
+    SceneMaterialResponseProfile;
+  illuminationTemporalProfile?:
+    SceneIlluminationTemporalProfile;
+  captureTimeSecondsFromReference?: number;
+  captureGeometry:
+    ResolvedCaptureGeometry;
+  derivationProfile:
+    SceneRadianceMeteringDerivationProfile;
+  samples:
+    readonly ExposureMeteringZoneSample[];
+}
+```
+
+## parseSceneRadianceMeteringDerivationProfile
+
+Parses the declared approximation used to reduce renderer/provider scene
+information into the scalar relative-linear domain consumed by metering.
+
+This profile explicitly does not authorize a calibrated luminance or
+spectral-to-photometric conversion claim.
+
+```ts
+export function parseSceneRadianceMeteringDerivationProfile(
+  value: unknown
+): SceneRadianceMeteringDerivationProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## SCENE_RADIANCE_METERING_DERIVATION_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+SCENE_RADIANCE_METERING_DERIVATION_SCHEMA_VERSION =
+  "0.1.0" as const
+```
+
+## SceneRadianceDerivedExposureMeteringSampleSet
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SceneRadianceDerivedExposureMeteringSampleSet
+  extends ExposureMeteringSampleSet {
+  sourceContext:
+    SceneRadianceMeteringSourceContext;
+}
+```
+
+## SceneRadianceMeteringDerivationProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SceneRadianceMeteringDerivationProfile {
+  schemaVersion:
+    typeof SCENE_RADIANCE_METERING_DERIVATION_SCHEMA_VERSION;
+  derivationId: string;
+  scientificStatus: "approximation";
+  method:
+    "renderer-provided-pre-exposure-relative-reduction";
+  spectralWeighting:
+    "not-calibrated";
+  evidence: readonly EvidenceProvenance[];
+  limitation: string;
+}
+```
+
+## SceneRadianceMeteringSourceContext
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SceneRadianceMeteringSourceContext {
+  kind:
+    "scene-radiance-provider-derived-relative";
+  sceneId: string;
+  sceneStateId: string;
+  providerProfileId: string;
+  illuminationProfileId: string;
+  materialResponseProfileId: string;
+  derivationProfileId: string;
+  providerScientificStatus:
+    SceneRadianceProviderProfile["scientificStatus"];
+  materialResponseFidelity:
+    ReturnType<
+      typeof assessSceneMaterialResponseFidelity
+    >;
+  temporal:
+    SceneRadianceMeteringTemporalContext;
+  spectralReductionCalibrated: false;
+  calibratedLuminanceClaimAuthorized:
+    false;
+  calibratedSceneRadianceClaimAuthorized:
+    false;
+}
+```
+
+## SceneRadianceMeteringTemporalContext
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SceneRadianceMeteringTemporalContext =
+  | {
+      kind: "time-invariant";
+    }
+  | {
+      kind:
+        "registered-time-varying";
+      illuminationTemporalProfileId:
+        string;
+      timeReference:
+        "first-opening-boundary-phase";
+      captureTimeSecondsFromReference:
+        number;
+    };
+```