@photivra/engine 1.4.0 → 2.0.0

package/dist/exposure/flash.js

@@ -1,35 +1,47 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Module boundary and integration notes.
- * 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.
- * 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.
- * @see docs/USAGE.md for equations, coordinate/unit conventions, blockers and support limits.
+ * Manual flash and flash sync.
+ *
+ * The parsers validate untrusted input and return the normalized typed contract. Unknown enum values,
+ * missing required fields and incompatible scientific data are rejected.
+ *
+ * Manual flash is a relative light pulse added on top of the scene light, timed on the capture's
+ * opening-reference clock.
+ * - Ordinary front- or rear-curtain sync needs a real interval when the whole frame is open at once.
+ * - High-speed sync (HSS; schema 0.2.0 sync profiles) is separate: a near-continuous burst that
+ *   covers the travelling shutter slit (resolveHighSpeedFlashSync).
+ * - TTL pre-flash power and guide-number relations are in flash-ttl.ts.
+ * Source brightness, optical transport and sensor integration have their own contracts.
+ * @see docs/USAGE.md for the equations, units, coordinate conventions, known blockers and support
+ * limits.
  */
 import { InvalidConfigurationError } from "../core/configuration-error.js";
 import { parseEvidenceList } from "../core/evidence-provenance.js";
 import { InvalidScientificInputError } from "../core/validation.js";
 import { parseSceneIlluminationProfile } from "../schema/illumination.js";
 import { parseSceneIlluminationTemporalProfile } from "../schema/illumination-temporal.js";
+import { requireInputObject, requireInputKeys, rejectUnknownFields } from "../core/record-validation.js";
 export const MANUAL_FLASH_PROFILE_SCHEMA_VERSION = "0.1.0";
 export const FLASH_SYNC_CAPABILITY_SCHEMA_VERSION = "0.1.0";
+/** Sync-capability schema that may declare high-speed sync (a fast pulse train that acts as continuous light). */
+export const FLASH_SYNC_CAPABILITY_HSS_SCHEMA_VERSION = "0.2.0";
+/** Model identity of the pulsed quasi-continuous high-speed-sync burst. */
+export const HIGH_SPEED_SYNC_MODEL = Object.freeze({
+    id: "flash-hss-quasi-continuous-burst",
+    version: "1.0.0"
+});
 const ORDINARY_SYNC_MODES = new Set([
     "front-curtain",
     "rear-curtain"
 ]);
-function requireRecord(value, path) {
+function requireRecord(value, path, allowedKeys) {
     if (typeof value !== "object" ||
         value === null ||
         Array.isArray(value)) {
         throw new InvalidConfigurationError(path + " must be an object.");
     }
+    if (allowedKeys !== null)
+        rejectUnknownFields(value, allowedKeys, path);
     return value;
 }
 function requireNonEmptyString(value, path) {
@@ -81,7 +93,7 @@ function parsePulseSamples(value, supportDurationSeconds, path) {
             "[" +
             index +
             "]";
-        const record = requireRecord(entry, samplePath);
+        const record = requireRecord(entry, samplePath, ["timeSecondsFromWaveformReference", "relativeMagnitudeMultiplier"]);
         const time = requireFinite(record
             .timeSecondsFromWaveformReference, samplePath +
             ".timeSecondsFromWaveformReference");
@@ -131,6 +143,7 @@ function parsePulseSamples(value, supportDurationSeconds, path) {
     return samples;
 }
 function validateSourceTemplate(sourceTemplate) {
+    requireInputObject(sourceTemplate, "manualFlashProfile.sourceTemplate");
     const probe = parseSceneIlluminationProfile({
         schemaVersion: "0.1.0",
         profileId: "manual-flash-source-validation",
@@ -171,20 +184,20 @@ function validateSourceTemplate(sourceTemplate) {
     };
 }
 /**
- * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
- * missing required fields and incompatible scientific data fail at this boundary.
+ * Validates an untrusted declaration and returns the normalized typed contract. Unknown enum values,
+ * missing required fields and incompatible scientific data are rejected here.
  *
- * 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.
- * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
- * @returns ManualFlashProfile. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * Manual flash is a relative light pulse added on top of the scene light, timed on the capture's
+ * opening-reference clock. Ordinary front- or rear-curtain sync needs a real interval when the whole
+ * frame is open at once. High-speed sync (HSS), TTL and flash metering are not handled here. Source
+ * brightness, optical transport and sensor integration have their own contracts.
+ * @param value - unknown. Untrusted input; TypeScript types alone are not validation.
+ * @returns ManualFlashProfile. The result states its shape and scientific status; a successful call does not imply calibration.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export function parseManualFlashProfile(value) {
-    const record = requireRecord(value, "manualFlashProfile");
+    const record = requireRecord(value, "manualFlashProfile", ["schemaVersion", "pulse", "outputControl", "profileId", "profileVersion", "sourceTemplate", "evidence", "limitations", "ttlModeled", "highSpeedSyncModeled", "recycleBehaviorModeled", "redEyePreflashModeled", "modelingLightModeled", "afAssistModeled"]);
     if (record.schemaVersion !==
         MANUAL_FLASH_PROFILE_SCHEMA_VERSION) {
         throw new InvalidConfigurationError('manualFlashProfile.schemaVersion must be "' +
@@ -205,7 +218,7 @@ export function parseManualFlashProfile(value) {
                 " must be false in schema 0.1.0.");
         }
     }
-    const pulse = requireRecord(record.pulse, "manualFlashProfile.pulse");
+    const pulse = requireRecord(record.pulse, "manualFlashProfile.pulse", ["supportDurationSeconds", "scientificStatus", "interpolation", "normalization", "waveformId", "samples", "evidence", "limitations"]);
     const supportDurationSeconds = requirePositiveFinite(pulse.supportDurationSeconds, "manualFlashProfile.pulse.supportDurationSeconds");
     if (pulse.scientificStatus !==
         "approximation" ||
@@ -215,7 +228,7 @@ export function parseManualFlashProfile(value) {
             "relative-peak-one") {
         throw new InvalidConfigurationError("manualFlashProfile.pulse scientificStatus/interpolation/normalization is invalid.");
     }
-    const output = requireRecord(record.outputControl, "manualFlashProfile.outputControl");
+    const output = requireRecord(record.outputControl, "manualFlashProfile.outputControl", ["kind", "flashExposureCompensationStops", "scale"]);
     if (output.kind !==
         "relative-linear-source-scale" ||
         output
@@ -254,33 +267,58 @@ export function parseManualFlashProfile(value) {
     };
 }
 /**
- * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
- * missing required fields and incompatible scientific data fail at this boundary.
+ * Validates an untrusted declaration and returns the normalized typed contract. Unknown enum values,
+ * missing required fields and incompatible scientific data are rejected here.
  *
- * 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.
- * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
- * @returns FlashSyncCapabilityProfile. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * Manual flash is a relative light pulse added on top of the scene light, timed on the capture's
+ * opening-reference clock. Ordinary front- or rear-curtain sync needs a real interval when the whole
+ * frame is open at once. High-speed sync (HSS), TTL and flash metering are not handled here. Source
+ * brightness, optical transport and sensor integration have their own contracts.
+ * @param value - unknown. Untrusted input; TypeScript types alone are not validation.
+ * @returns FlashSyncCapabilityProfile. The result states its shape and scientific status; a successful call does not imply calibration.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export function parseFlashSyncCapabilityProfile(value) {
-    const record = requireRecord(value, "flashSyncCapabilityProfile");
+    const record = requireRecord(value, "flashSyncCapabilityProfile", ["schemaVersion", "highSpeedSyncSupported", "ordinarySyncRequiresWholeActiveFrameSimultaneouslyExposed", "highSpeedSync", "supportedOrdinarySyncModes", "profileId", "profileVersion", "captureModeId", "timingProfileId", "evidence", "limitations"]);
     if (record.schemaVersion !==
-        FLASH_SYNC_CAPABILITY_SCHEMA_VERSION) {
+        FLASH_SYNC_CAPABILITY_SCHEMA_VERSION &&
+        record.schemaVersion !==
+            FLASH_SYNC_CAPABILITY_HSS_SCHEMA_VERSION) {
         throw new InvalidConfigurationError('flashSyncCapabilityProfile.schemaVersion must be "' +
             FLASH_SYNC_CAPABILITY_SCHEMA_VERSION +
+            '" or "' +
+            FLASH_SYNC_CAPABILITY_HSS_SCHEMA_VERSION +
             '".');
     }
-    if (record.highSpeedSyncSupported !==
-        false ||
+    const hssSchema = record.schemaVersion ===
+        FLASH_SYNC_CAPABILITY_HSS_SCHEMA_VERSION;
+    if ((hssSchema
+        ? typeof record.highSpeedSyncSupported !==
+            "boolean"
+        : record.highSpeedSyncSupported !==
+            false) ||
         record
             .ordinarySyncRequiresWholeActiveFrameSimultaneouslyExposed !==
             true) {
         throw new InvalidConfigurationError("flashSyncCapabilityProfile schema 0.1.0 supports ordinary whole-frame sync only and must not claim HSS.");
     }
+    let highSpeedSync;
+    if (record.highSpeedSyncSupported === true) {
+        const hss = requireRecord(record.highSpeedSync, "flashSyncCapabilityProfile.highSpeedSync", ["burstEnergyFractionOfFullPulse", "evidence"]);
+        const fraction = requirePositiveFinite(hss.burstEnergyFractionOfFullPulse, "flashSyncCapabilityProfile.highSpeedSync.burstEnergyFractionOfFullPulse");
+        if (fraction > 1) {
+            throw new InvalidConfigurationError("flashSyncCapabilityProfile.highSpeedSync.burstEnergyFractionOfFullPulse must be at most 1.");
+        }
+        highSpeedSync = {
+            burstEnergyFractionOfFullPulse: fraction,
+            evidence: parseEvidenceList(hss.evidence, "flashSyncCapabilityProfile.highSpeedSync.evidence")
+        };
+    }
+    else if (record.highSpeedSync !==
+        undefined) {
+        throw new InvalidConfigurationError("flashSyncCapabilityProfile.highSpeedSync must be omitted when HSS is unsupported.");
+    }
     if (!Array.isArray(record.supportedOrdinarySyncModes) ||
         record
             .supportedOrdinarySyncModes
@@ -304,18 +342,46 @@ export function parseFlashSyncCapabilityProfile(value) {
         throw new InvalidConfigurationError("flashSyncCapabilityProfile.supportedOrdinarySyncModes must not contain duplicates.");
     }
     return {
-        schemaVersion: FLASH_SYNC_CAPABILITY_SCHEMA_VERSION,
+        schemaVersion: hssSchema
+            ? FLASH_SYNC_CAPABILITY_HSS_SCHEMA_VERSION
+            : FLASH_SYNC_CAPABILITY_SCHEMA_VERSION,
         profileId: requireNonEmptyString(record.profileId, "flashSyncCapabilityProfile.profileId"),
         profileVersion: requireNonEmptyString(record.profileVersion, "flashSyncCapabilityProfile.profileVersion"),
         captureModeId: requireNonEmptyString(record.captureModeId, "flashSyncCapabilityProfile.captureModeId"),
         timingProfileId: requireNonEmptyString(record.timingProfileId, "flashSyncCapabilityProfile.timingProfileId"),
         supportedOrdinarySyncModes: modes,
-        highSpeedSyncSupported: false,
+        highSpeedSyncSupported: highSpeedSync !== undefined,
+        ...(highSpeedSync === undefined
+            ? {}
+            : { highSpeedSync }),
         ordinarySyncRequiresWholeActiveFrameSimultaneouslyExposed: true,
         evidence: parseEvidenceList(record.evidence, "flashSyncCapabilityProfile.evidence"),
         limitations: parseLimitations(record.limitations, "flashSyncCapabilityProfile.limitations")
     };
 }
+/**
+ * Shape guard for the resolved capture-mode timing record read by the flash sync functions: every
+ * nested object read below must be an object, so a malformed record fails with
+ * InvalidConfigurationError instead of a raw TypeError. Values are checked where they are used.
+ */
+function requireTimingRecordShape(timing, path) {
+    requireInputObject(timing, path);
+    const record = timing;
+    if (!Array.isArray(record.evidence))
+        throw new InvalidConfigurationError(path + ".evidence must be an array.");
+    requireInputObject(record.exposureWindows, path + ".exposureWindows");
+    const windows = record.exposureWindows;
+    requireInputObject(windows.nominalExposureDurationSeconds, path + ".exposureWindows.nominalExposureDurationSeconds");
+    requireInputObject(windows.localExposureDurationRangeSeconds, path + ".exposureWindows.localExposureDurationRangeSeconds");
+    for (const boundary of ["opening", "closing"]) {
+        requireInputObject(windows[boundary], path + ".exposureWindows." + boundary);
+        const schedule = windows[boundary].schedule;
+        requireInputObject(schedule, path + ".exposureWindows." + boundary + ".schedule");
+        if (schedule.kind !== "simultaneous") {
+            requireInputObject(schedule.traversalDurationSeconds, path + ".exposureWindows." + boundary + ".schedule.traversalDurationSeconds");
+        }
+    }
+}
 function wholeFrameOpenInterval(timing) {
     const opening = timing.exposureWindows.opening
         .schedule;
@@ -337,6 +403,8 @@ function wholeFrameOpenInterval(timing) {
     };
 }
 function validateReleaseBinding(release, timing) {
+    requireInputObject(release, "releaseFrame");
+    requireInputObject(release.exposure, "releaseFrame.exposure");
     const nominal = timing.exposureWindows
         .nominalExposureDurationSeconds
         .value;
@@ -348,23 +416,25 @@ function validateReleaseBinding(release, timing) {
         Number.EPSILON *
             16 *
             scale) {
-        throw new InvalidScientificInputError("releaseFrame shutter duration must match the #12 capture-mode timing exposure duration.");
+        throw new InvalidScientificInputError("releaseFrame shutter duration must match the exposure duration of the capture-mode exposure-window timing.");
     }
 }
 /**
- * Place a declared ordinary flash pulse into the actual whole-frame exposure opening interval for
- * front or rear sync, or return structured incompatibility.
+ * Places a declared ordinary flash pulse inside the actual interval when the whole frame is open, for
+ * front- or rear-curtain sync. Otherwise returns a 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.
- * @param input - ResolveManualFlashSyncInput. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns ResolvedManualFlashSync. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * Manual flash is a relative light pulse added on top of the scene light, timed on the capture's
+ * opening-reference clock. Ordinary front- or rear-curtain sync needs a real interval when the whole
+ * frame is open at once. High-speed sync (HSS), TTL and flash metering are not handled here. Source
+ * brightness, optical transport and sensor integration have their own contracts.
+ * @param input - ResolveManualFlashSyncInput. See that type for coordinates, units and profile binding.
+ * @returns ResolvedManualFlashSync. The result states its shape and scientific status; a successful call does not imply calibration.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export function resolveManualFlashSync(input) {
+    requireInputKeys(input, "resolveManualFlashSync", ["flashEnabled", "flashProfile", "syncCapabilities", "timing", "syncMode", "releaseFrame"]);
+    requireTimingRecordShape(input.timing, "resolveManualFlashSync timing");
     const flash = parseManualFlashProfile(input.flashProfile);
     const capabilities = parseFlashSyncCapabilityProfile(input.syncCapabilities);
     if (capabilities.captureModeId !==
@@ -423,7 +493,7 @@ export function resolveManualFlashSync(input) {
     }
     if (input.syncMode ===
         "high-speed-sync") {
-        throw new InvalidScientificInputError("High-speed sync is not modeled in manual flash schema 0.1.0; ordinary single-pulse flash cannot be used as an HSS substitute.");
+        throw new InvalidScientificInputError("High-speed sync is not an ordinary sync mode; ordinary single-pulse flash cannot be used as an HSS substitute. Use resolveHighSpeedFlashSync with an HSS-capable sync profile.");
     }
     if (!capabilities
         .supportedOrdinarySyncModes
@@ -432,7 +502,7 @@ export function resolveManualFlashSync(input) {
     }
     if (openInterval.durationSeconds <=
         0) {
-        throw new InvalidScientificInputError("Ordinary one-pulse flash cannot uniformly expose the active frame because the #12 timing has no whole-frame-open interval.");
+        throw new InvalidScientificInputError("Ordinary one-pulse flash cannot uniformly expose the active frame because the exposure-window timing has no whole-frame-open interval.");
     }
     if (flash.pulse
         .supportDurationSeconds >
@@ -498,19 +568,20 @@ function scaledFlashSource(flash) {
     };
 }
 /**
- * Construct an owned registered temporal illumination overlay from the resolved manual pulse while
- * preserving base ambient source identity.
+ * Builds a temporal illumination overlay from the resolved manual pulse. The identity of the base
+ * ambient light source is kept.
  *
- * 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.
- * @param input - CreateManualFlashIlluminationOverlayInput. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns ManualFlashIlluminationOverlay. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * Manual flash is a relative light pulse added on top of the scene light, timed on the capture's
+ * opening-reference clock. Ordinary front- or rear-curtain sync needs a real interval when the whole
+ * frame is open at once. High-speed sync (HSS), TTL and flash metering are not handled here. Source
+ * brightness, optical transport and sensor integration have their own contracts.
+ * @param input - CreateManualFlashIlluminationOverlayInput. See that type for coordinates, units and profile binding.
+ * @returns ManualFlashIlluminationOverlay. The result states its shape and scientific status; a successful call does not imply calibration.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export function createManualFlashIlluminationOverlay(input) {
+    requireInputKeys(input, "createManualFlashIlluminationOverlay", ["baseIlluminationProfile", "baseTemporalProfile", "flashProfile", "resolvedSync", "illuminationProfileId", "temporalProfileId"]);
     const base = parseSceneIlluminationProfile(input
         .baseIlluminationProfile);
     const baseTemporal = input.baseTemporalProfile ===
@@ -527,6 +598,9 @@ export function createManualFlashIlluminationOverlay(input) {
     }
     const flash = parseManualFlashProfile(input.flashProfile);
     const sync = input.resolvedSync;
+    requireInputObject(sync, "createManualFlashIlluminationOverlay resolvedSync");
+    if (!Array.isArray(sync.evidence))
+        throw new InvalidConfigurationError("createManualFlashIlluminationOverlay resolvedSync.evidence must be an array.");
     if (sync.flashProfileId !==
         flash.profileId ||
         sync.flashProfileVersion !==
@@ -614,7 +688,7 @@ export function createManualFlashIlluminationOverlay(input) {
                 scientificStatus: "approximation",
                 timingUncertainty: {
                     kind: "not-quantified",
-                    limitation: "Schema 0.1.0 uses ideal deterministic flash trigger registration within the declared #12 exposure-window schedule."
+                    limitation: "Schema 0.1.0 uses ideal deterministic flash trigger registration within the declared exposure-window schedule."
                 },
                 evidence: sync.evidence
             }
@@ -641,4 +715,130 @@ export function createManualFlashIlluminationOverlay(input) {
         ttlMeteringIncluded: false
     };
 }
+function integratePulse(samples) {
+    let area = 0;
+    for (let index = 1; index < samples.length; index += 1) {
+        const a = samples[index - 1], b = samples[index];
+        area += (b.timeSecondsFromWaveformReference - a.timeSecondsFromWaveformReference) *
+            (a.relativeMagnitudeMultiplier + b.relativeMagnitudeMultiplier) / 2;
+    }
+    return area;
+}
+/**
+ * Resolves high-speed (focal-plane) sync (HSS): a fast pulse train that acts as continuous light and
+ * covers the whole travelling-slit exposure.
+ *
+ * At shutter speeds faster than the ordinary sync limit, the shutter's opening and closing edges
+ * cross the frame as a slit, and the whole frame is never open at once. A single short pulse would
+ * light only a band.
+ *
+ * HSS instead fires a rapid pulse train. It behaves like constant output P over the burst D, from
+ * the first line opening to the last line closing. Each line collects P·t_e over its slit time t_e.
+ * - The burst energy is E_burst = η·p·E_pulse. η comes from the sync profile, p is the power
+ *   fraction and E_pulse is the energy of an ordinary full-power pulse.
+ * - So P = E_burst/D, and each line receives η·p·E_pulse·t_e/D.
+ * - Exposure ∝ GN² (inverse-square law, GN = d·N). So, relative to an ordinary pulse at the same
+ *   power, the effective guide number is GN_HSS/GN = √(η·t_e/D).
+ * Shortening t_e by one stop therefore costs half a stop of guide number.
+ *
+ * Approximations: the pulse train is treated as continuous (pulse period ≪ t_e). Recycle and thermal
+ * limits are folded into η. Front/rear-curtain placement does not apply, because the burst covers
+ * the whole exposure.
+ * @see docs/SCENE_SENSOR_TEMPORAL_EXPOSURE.md#high-speed-sync
+ */
+export function resolveHighSpeedFlashSync(input) {
+    requireInputKeys(input, "resolveHighSpeedFlashSync", ["flashEnabled", "flashProfile", "syncCapabilities", "timing", "powerFraction", "releaseFrame"]);
+    requireTimingRecordShape(input.timing, "resolveHighSpeedFlashSync timing");
+    const flash = parseManualFlashProfile(input.flashProfile);
+    const capabilities = parseFlashSyncCapabilityProfile(input.syncCapabilities);
+    if (capabilities.captureModeId !== input.timing.captureModeId || capabilities.timingProfileId !== input.timing.timingProfileId) {
+        throw new InvalidScientificInputError("Flash sync capability profile must exactly match the resolved capture-mode and timing-profile identities.");
+    }
+    if (!capabilities.highSpeedSyncSupported || capabilities.highSpeedSync === undefined) {
+        throw new InvalidScientificInputError("The flash sync capability profile does not declare high-speed sync.");
+    }
+    const power = input.powerFraction;
+    if (typeof power !== "number" || !Number.isFinite(power) || power <= 0 || power > 1) {
+        throw new InvalidScientificInputError("HSS powerFraction must lie in (0, 1].");
+    }
+    if (input.releaseFrame !== undefined)
+        validateReleaseBinding(input.releaseFrame, input.timing);
+    const windows = input.timing.exposureWindows;
+    const closing = windows.closing.schedule;
+    const burstEnd = windows.nominalExposureDurationSeconds.value +
+        (closing.kind === "simultaneous" ? 0 : closing.traversalDurationSeconds.value);
+    const eta = capabilities.highSpeedSync.burstEnergyFractionOfFullPulse;
+    const local = windows.localExposureDurationRangeSeconds;
+    const fraction = { minimum: eta * local.minimum / burstEnd, maximum: eta * local.maximum / burstEnd };
+    const pulseEnergy = integratePulse(flash.pulse.samples);
+    const burstFlashProfile = {
+        ...flash,
+        pulse: {
+            ...flash.pulse,
+            waveformId: flash.pulse.waveformId + "-hss-burst",
+            supportDurationSeconds: burstEnd,
+            samples: [
+                { timeSecondsFromWaveformReference: 0, relativeMagnitudeMultiplier: 1 },
+                { timeSecondsFromWaveformReference: burstEnd, relativeMagnitudeMultiplier: 1 }
+            ],
+            limitations: [...flash.pulse.limitations,
+                "Quasi-continuous HSS burst: the pulse train is approximated by constant output over the burst support."]
+        },
+        outputControl: { ...flash.outputControl, scale: flash.outputControl.scale * power * eta * pulseEnergy / burstEnd }
+    };
+    const enabled = input.flashEnabled;
+    return {
+        modelId: HIGH_SPEED_SYNC_MODEL.id,
+        modelVersion: HIGH_SPEED_SYNC_MODEL.version,
+        flashEnabled: enabled,
+        flashProfileId: flash.profileId,
+        flashProfileVersion: flash.profileVersion,
+        sourceId: flash.sourceTemplate.sourceId,
+        syncMode: "high-speed-sync",
+        syncStatus: enabled ? "high-speed-sync-resolved" : "disabled",
+        captureModeId: input.timing.captureModeId,
+        timingProfileId: input.timing.timingProfileId,
+        syncCapabilityProfileId: capabilities.profileId,
+        timeReference: "first-opening-boundary-phase",
+        powerFraction: power,
+        burstEnergyFractionOfFullPulse: eta,
+        singlePulseIntegratedRelativeSeconds: pulseEnergy,
+        burstStartSecondsFromCaptureReference: 0,
+        burstEndSecondsFromCaptureReference: burstEnd,
+        burstDurationSeconds: burstEnd,
+        localExposureDurationRangeSeconds: { minimum: local.minimum, maximum: local.maximum },
+        energyFractionOfSinglePulseRange: fraction,
+        guideNumberFactorRange: { minimum: Math.sqrt(fraction.minimum), maximum: Math.sqrt(fraction.maximum) },
+        uniformAcrossActiveFrame: local.minimum === local.maximum,
+        burstFlashProfile: enabled ? burstFlashProfile : null,
+        waveformTimeZeroSecondsFromCaptureReference: enabled ? 0 : null,
+        releaseFrameBinding: !enabled || input.releaseFrame === undefined ? null : {
+            sequenceId: input.releaseFrame.sequenceId,
+            releaseFrameId: input.releaseFrame.releaseFrameId,
+            frameIndex: input.releaseFrame.frameIndex,
+            sceneTimeSecondsFromSequenceStartAtBurstStart: input.releaseFrame.sceneTimeSecondsFromSequenceStart,
+            sceneTimeSecondsFromSequenceStartAtBurstEnd: input.releaseFrame.sceneTimeSecondsFromSequenceStart + burstEnd
+        },
+        hssModeled: true,
+        ttlModeled: false,
+        sensorReadoutTimingUsedAsExposureTiming: false,
+        evidence: [...flash.evidence, ...capabilities.evidence, ...capabilities.highSpeedSync.evidence, ...input.timing.evidence],
+        limitations: [
+            ...flash.limitations,
+            ...capabilities.limitations,
+            "HSS burst is registered to exposure-boundary timing (first line opening to last line closing), never sensor data-readout timing.",
+            "Pulse-train ripple, recycle/thermal limits beyond the declared burst energy fraction and branded flash protocols are not modeled."
+        ]
+    };
+}
+/**
+ * Registers a resolved high-speed-sync burst as a temporal illumination overlay: a rectangular
+ * waveform over [0, D]. Each line then collects the burst over its own local exposure window.
+ */
+export function createHighSpeedSyncIlluminationOverlay(input) {
+    requireInputKeys(input, "createHighSpeedSyncIlluminationOverlay", ["baseIlluminationProfile", "baseTemporalProfile", "flashProfile", "illuminationProfileId", "temporalProfileId", "resolvedSync"]);
+    requireInputObject(input.resolvedSync, "createHighSpeedSyncIlluminationOverlay resolvedSync");
+    return createManualFlashIlluminationOverlay({ ...input,
+        flashProfile: input.resolvedSync.burstFlashProfile ?? input.flashProfile });
+}
 //# sourceMappingURL=flash.js.map