@photivra/engine 1.4.0 → 2.0.0

package/docs/api/output-capture-geometry.md

@@ -1,6 +1,6 @@
 # output/capture-geometry.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.
 
 ## ActiveCaptureFieldOfView
 
@@ -12,8 +12,8 @@ export interface ActiveCaptureFieldOfView {
   horizontalDegrees: number;
   verticalDegrees: number;
   /**
-   * Larger of the two opposite-corner diagonal angular spans. For centered
-   * crops both diagonal spans are equal.
+   * The larger of the two corner-to-corner diagonal angles. For a centred
+   * crop the two diagonals are equal.
    */
   diagonalDegrees: number;
   horizontalBoundsDegrees: {
@@ -39,10 +39,11 @@ export interface ActiveCaptureFieldOfView {
 
 ## calculateActiveCaptureFieldOfView
 
-Calculates asymmetric horizontal/vertical FOV plus opposite-corner diagonal
-spans for the active physical capture area after physical camera orientation.
+Calculates the field of view (FOV) of the active physical capture area after
+camera orientation. Horizontal and vertical FOV can be asymmetric about the
+optical axis; both corner-to-corner diagonals are reported.
 
-Final digital/output crop is intentionally excluded.
+The final digital (output) crop is deliberately not included.
 
 ```ts
 export function calculateActiveCaptureFieldOfView(
@@ -69,9 +70,8 @@ export interface CalculateActiveCaptureFieldOfViewInput {
 
 ## calculateOutputFieldOfView
 
-Calculates final visible field of view after physical active capture,
-orientation, and digital/output crop. Output raster resolution does not
-affect this optical/framing result.
+Calculates the final visible field of view after the active capture area,
+orientation and digital (output) crop. Output resolution does not affect it.
 
 ```ts
 export function calculateOutputFieldOfView(
@@ -111,9 +111,9 @@ export type CaptureOrientation =
 
 ## ImagePlaneMetricPointMm
 
-Pre-orientation optical image-plane coordinate in millimetres.
+A point on the optical image plane, in millimetres, before camera orientation is applied.
 
-Origin is the optical axis; +X points right and +Y points up.
+The origin is the optical axis. +X points right and +Y points up.
 
 ```ts
 export interface ImagePlaneMetricPointMm {
@@ -124,13 +124,12 @@ export interface ImagePlaneMetricPointMm {
 
 ## mapImagePlanePointToOrientedPhysicalUv
 
-Maps a pre-orientation optical image-plane point into normalized coordinates
-of an oriented physical raster region.
+Maps an optical image-plane point (before camera orientation) to normalized
+coordinates in an oriented physical image region.
 
-This is the exact coordinate inverse of
-mapOrientedPhysicalUvToImagePlanePoint(). Points outside the supplied region
-fail closed; a tiny tolerance only absorbs floating-point round-trip noise at
-an edge.
+This is the exact inverse of mapOrientedPhysicalUvToImagePlanePoint(). A point
+outside the region is rejected. A tiny tolerance only absorbs floating-point
+round-trip error at an edge.
 
 ```ts
 export function mapImagePlanePointToOrientedPhysicalUv(
@@ -174,13 +173,13 @@ export interface MapOrientedPhysicalUvToImagePlaneInput {
 
 ## mapOrientedPhysicalUvToImagePlanePoint
 
-Maps normalized coordinates in an oriented physical raster region into the
-pre-orientation optical image plane used by lens-field and camera-mapping
-APIs.
+Maps normalized (0–1) coordinates in an oriented physical image region to the
+optical image plane used by the lens-field and camera-mapping APIs, before
+camera orientation.
 
-The supplied physical bounds use the capture contract's +Y-down basis after
-physical camera orientation. The returned image-plane point uses optical-axis
-origin, +X right and +Y up. No lens or projection equation is applied.
+The input bounds are after camera orientation and use +Y down. The returned
+point has its origin on the optical axis, with +X right and +Y up. No lens or
+projection equation is applied.
 
 ```ts
 export function mapOrientedPhysicalUvToImagePlanePoint(
@@ -287,8 +286,8 @@ export interface RasterVector {
 
 ## resolveCaptureGeometry
 
-Resolves native sensor geometry, active capture, physical camera orientation,
-and final digital/output geometry without conflating their identities.
+Resolves native sensor geometry, active capture area, physical camera orientation
+and final digital (output) geometry, keeping each one distinct.
 
 ```ts
 export function resolveCaptureGeometry(
@@ -314,16 +313,16 @@ export interface ResolveCaptureGeometryInput {
    */
   activeCaptureRect?: RasterRect;
   /**
-   * Final digital/output crop in oriented active-capture raster coordinates.
+   * Final digital (output) crop, in oriented active-capture pixel coordinates.
    *
    * Defaults to the full oriented active capture.
    */
   outputCropRect?: RasterRect;
   /**
-   * Final output raster after optional digital crop/resampling.
+   * Final output image size after the optional digital crop and resampling.
    *
-   * Defaults to the output-crop dimensions. The output raster must preserve
-   * the crop aspect ratio within a small integer-rounding tolerance.
+   * Defaults to the output-crop size. The output must keep the crop's aspect
+   * ratio, allowing only a small tolerance for integer rounding.
    */
   outputRaster?: RasterDimensions;
 }
@@ -354,7 +353,7 @@ export interface ResolvedCaptureGeometry {
     /** Native physical bounds relative to the optical axis. */
     physicalBoundsFromOpticalAxisMm: PhysicalBoundsFromOpticalAxisMm;
     /**
-     * Current generic model assumes native image samples uniformly span the
+     * The current generic model assumes the native pixels evenly cover the
      * declared physical imaging area.
      */
     imagingAreaDerivation: "uniform-native-raster";
@@ -369,9 +368,9 @@ export interface ResolvedCaptureGeometry {
   };
   output: {
     /**
-     * Digital/output crop expressed in oriented active-capture coordinates.
+     * Digital (output) crop, in oriented active-capture coordinates.
      *
-     * This crop does not mutate physical sensor identity or active-capture
+     * This crop does not change the physical sensor or the active-capture
      * geometry.
      */
     cropRect: RasterRect;
@@ -381,7 +380,7 @@ export interface ResolvedCaptureGeometry {
     physicalBoundsFromOpticalAxisMm: PhysicalBoundsFromOpticalAxisMm;
     centerOffsetFromOpticalAxisMm: RasterVector;
     sourceRetainedAreaFraction: number;
-    /** Pixel-domain resampling from oriented active capture into output. */
+    /** Pixel resampling from the oriented active capture to the output image. */
     orientedCaptureToOutputScale: {
       x: number;
       y: number;
@@ -393,8 +392,8 @@ export interface ResolvedCaptureGeometry {
 
 ## transformNativeRasterPointToOriented
 
-Transforms a continuous native raster edge-coordinate point into oriented
-capture coordinates. Pixel centers can be represented with +0.5 offsets.
+Converts a point in native pixel coordinates to oriented capture coordinates.
+Coordinates are continuous and measured from pixel edges, so a pixel centre is at +0.5.
 
 ```ts
 export function transformNativeRasterPointToOriented(
@@ -430,7 +429,7 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## transformOrientedRasterPointToNative
 
-Transforms an oriented raster edge-coordinate point back to native coordinates.
+Converts a point in oriented pixel coordinates (measured from pixel edges) back to native coordinates.
 
 ```ts
 export function transformOrientedRasterPointToNative(

package/docs/api/output-capture-sdr.md

@@ -1,6 +1,6 @@
 # output/capture-sdr.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.
 
 ## calculateCaptureSdr
 
@@ -22,7 +22,7 @@ CAPTURE_SDR_SCHEMA_VERSION = "0.1.0" as const
 
 ## CaptureSdrInput
 
-Select an existing RGB state or explicitly derive one; never estimate WB here.
+Either select an existing RGB image state or derive one explicitly. White balance is never estimated here.
 
 ```ts
 export interface CaptureSdrInput {
@@ -40,7 +40,7 @@ export interface CaptureSdrInput {
 
 ## CaptureSdrResult
 
-Keeps source capture history, optional color derivation and SDR diagnostics distinct.
+Result. The source capture history, the optional colour derivation and the SDR diagnostics are kept separate.
 
 ```ts
 export interface CaptureSdrResult {
@@ -60,7 +60,7 @@ export interface CaptureSdrResult {
 
 ## parseCaptureSdrInput
 
-Validates the capture and explicit color/render choices at an untrusted boundary.
+Validates untrusted input: the capture and the explicit colour and rendering choices.
 
 ```ts
 export function parseCaptureSdrInput(value: unknown): CaptureSdrInput;

package/docs/api/output-crop.md

@@ -1,10 +1,10 @@
 # output/crop.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.
 
 ## calculateCenteredCrop
 
-Calculates dimensions remaining after a centered, same-aspect-ratio crop.
+Calculates the dimensions left after a centred crop that keeps the aspect ratio.
 
 ```ts
 export function calculateCenteredCrop(
@@ -25,8 +25,11 @@ export interface CalculateCenteredCropInput {
   /** Original image height in pixels. */
   pixelHeight: number;
   /**
-   * Linear crop factor. 1 means no crop; 1.5 retains 1 / 1.5 of each
-   * dimension while preserving aspect ratio.
+   * Linear crop factor. 1 means no crop; 1.5 keeps at most 1 / 1.5 of each
+   * dimension. The shorter axis is floor(dimension / cropFactor). The longer
+   * axis is the integer that best matches the source aspect ratio, capped at
+   * floor(dimension / cropFactor). This keeps the aspect ratio as close as
+   * whole pixels allow.
    */
   cropFactor: number;
 }

package/docs/api/output-geometric-transforms.md

@@ -1,10 +1,10 @@
 # output/geometric-transforms.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.
 
 ## AffineGeometricTransform
 
-Explicit destination-to-source affine map, including rotation/shear/offset.
+Explicit destination-to-source affine map, which can include rotation, shear and offset.
 
 ```ts
 export interface AffineGeometricTransform extends TransformIdentity {
@@ -14,9 +14,20 @@ export interface AffineGeometricTransform extends TransformIdentity {
 }
 ```
 
+## BrownConradyGeometricTransform
+
+Schema 0.2.0: Brown-Conrady distortion. A correction reads the distorted data at the position mapped from each ideal destination point.
+
+```ts
+export interface BrownConradyGeometricTransform extends TransformIdentity {
+  kind: "brown-conrady";
+  profile: BrownConradyDistortionProfile;
+}
+```
+
 ## calculateComposedGeometricMapping
 
-Authoritative display-to-capture map and full local directional derivatives.
+Maps a display point to the capture, with the full local derivatives in each direction.
 
 ```ts
 export function calculateComposedGeometricMapping(input: {
@@ -28,7 +39,7 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## calculateForwardGeometricMapping
 
-Capture-to-display bridge for focus, metering and overlays; reverses the same maps.
+Maps a capture point to the display, for focus, metering and overlays. It inverts the same maps.
 
 ```ts
 export function calculateForwardGeometricMapping(input: {
@@ -40,7 +51,7 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## calculateGeometricResampling
 
-Samples an already-formed scalar image once; null output marks missing source support.
+Resamples an already-formed single-channel image once. A null output sample marks missing source data.
 
 ```ts
 export function calculateGeometricResampling(input: {
@@ -52,12 +63,17 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## calculateGeometricSamplingPlan
 
-Resolves one joint validity/crop/AA plan after composing compatible inverse maps.
+Composes compatible inverse maps, then resolves one shared plan for validity, crop and anti-aliasing (AA).
 
 ```ts
 export function calculateGeometricSamplingPlan(input: {
   mapping: PreparedGeometricMapping; sourceRaster: GeometricRaster; destinationRaster: GeometricRaster;
   resampler: GeometricResampler; physicalProjectionDistanceMm: number;
+  /**
+   * Ideal projection of the captured (source) image, used for the reported angles. Omitted or
+   * "rectilinear" keeps the existing atan(mm / projection distance) angles exactly.
+   */
+  sourceProjectionModel?: LensProjectionModel;
 }): CalculationResult<GeometricSamplingPlan>;
 ```
 
@@ -68,12 +84,16 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
 
 ```ts
-export type DigitalGeometricTransform = AffineGeometricTransform | RadialGeometricTransform;
+export type DigitalGeometricTransform =
+  | AffineGeometricTransform
+  | RadialGeometricTransform
+  | BrownConradyGeometricTransform
+  | ProjectionRemapGeometricTransform;
 ```
 
 ## GeometricImageDomain
 
-Domains are barriers: only contiguous equal-domain maps share a resample.
+A domain change separates maps: only adjacent maps in the same domain share one resampling pass.
 
 ```ts
 export type GeometricImageDomain = "raw-channel" | "reconstructed-linear" | "processed-output";
@@ -81,7 +101,7 @@ export type GeometricImageDomain = "raw-channel" | "reconstructed-linear" | "pro
 
 ## GeometricJacobian
 
-Row-major derivative d(source mm)/d(destination mm).
+Jacobian (derivative) d(source mm)/d(destination mm), in row-major order.
 
 ```ts
 export type GeometricJacobian = readonly [number, number, number, number];
@@ -102,9 +122,20 @@ export interface GeometricMappingPoint {
 }
 ```
 
+## GeometricProjectionDeclaration
+
+One ideal projection and its mapping scale (focal length, or mm per radian for equirectangular).
+
+```ts
+export interface GeometricProjectionDeclaration {
+  projectionModel: LensProjectionModel;
+  focalLengthMm: number;
+}
+```
+
 ## GeometricRaster
 
-Regular pixel centers on the optical plane: +X right, +Y up; row order down.
+A regular grid of pixel centres on the optical plane: +X right, +Y up; rows run top to bottom.
 
 ```ts
 export interface GeometricRaster {
@@ -117,7 +148,7 @@ export interface GeometricRaster {
 
 ## GeometricResampler
 
-Resampler identity is independent of mapping. Prefiltering is a caller obligation.
+The resampling filter, chosen independently of the mapping. Any prefiltering (anti-aliasing) is the caller's job.
 
 ```ts
 export interface GeometricResampler {
@@ -139,21 +170,21 @@ export interface GeometricSamplingPlan {
   destinationRaster: GeometricRaster;
   resampler: GeometricResampler;
   points: readonly GeometricMappingPoint[];
-  /** Includes exact center-domain support for the selected filter; no edge extension. */
+  /** True where the selected filter has full source support around the pixel centre. Edges are not extended. */
   validSourceMask: readonly boolean[];
-  /** Largest all-valid axis-aligned pixel rectangle, half-open. Null if empty. */
+  /** Largest axis-aligned rectangle of valid pixels (half-open). Null if there is none. */
   jointCrop: { x: number; y: number; width: number; height: number } | null;
   requiresPrefilter: boolean;
   canResample: boolean;
   physicalCapturedFovDegrees: { horizontal: number; vertical: number };
-  /** Envelope of mapped pixel-center rays retained by the joint crop, not edge FOV. */
+  /** Angular extent of the mapped pixel-centre rays kept by the joint crop. It is not the edge-to-edge FOV. */
   retainedSampleRayEnvelopeDegrees: { minX: number; maxX: number; minY: number; maxY: number } | null;
 }
 ```
 
 ## parseDigitalGeometricTransform
 
-Parses strict transform data, rejecting unknown semantics and noninvertible profiles.
+Strictly parses transform data. Unknown kinds or fields and profiles that cannot be inverted are rejected.
 
 ```ts
 export function parseDigitalGeometricTransform(value: unknown): DigitalGeometricTransform;
@@ -163,11 +194,12 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## PreparedGeometricMapping
 
-Serializable prepared state. Maps are applied in listed destination-to-source order.
+Serializable prepared mapping. Maps are applied in the listed order, from destination towards source.
 
 ```ts
 export interface PreparedGeometricMapping {
-  schemaVersion: "0.1.0";
+  /** 0.1.0 when only affine and radial kinds are used; 0.2.0 when a kind added in 2.0 is present. */
+  schemaVersion: "0.1.0" | "0.2.0";
   frameTimeSeconds: number;
   transforms: readonly DigitalGeometricTransform[];
   semanticKey: string;
@@ -177,7 +209,7 @@ export interface PreparedGeometricMapping {
 
 ## prepareGeometricMapping
 
-Prepares deterministic still/frame geometry; time changes require another preparation.
+Prepares a deterministic mapping for one still or frame. A change in time needs a new preparation.
 
 ```ts
 export function prepareGeometricMapping(input: {
@@ -187,9 +219,23 @@ export function prepareGeometricMapping(input: {
 
 This call is synchronous; any supplied provider must follow its explicit synchronous contract.
 
+## ProjectionRemapGeometricTransform
+
+Schema 0.2.0: change of projection. Each destination point becomes a scene direction (using
+the destination projection), then a source point (using the source projection). Purpose must
+be "projection".
+
+```ts
+export interface ProjectionRemapGeometricTransform extends TransformIdentity {
+  kind: "projection-remap";
+  destinationProjection: GeometricProjectionDeclaration;
+  sourceProjection: GeometricProjectionDeclaration;
+}
+```
+
 ## RadialGeometricTransform
 
-Correction samples physical distorted data at the mapped ideal destination.
+Radial distortion. A correction reads the physically distorted data at the position mapped from each ideal (undistorted) destination point.
 
 ```ts
 export interface RadialGeometricTransform extends TransformIdentity {

package/docs/api/output-lens-corrections.md

@@ -1,12 +1,12 @@
 # output/lens-corrections.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.
 
 ## calculateLensCorrectedCapture
 
-Executes bounded reconstructed-linear corrections on already sampled RGB channels.
-Compatible common geometry plus channel CA is sampled once per channel.
-A gain between geometry components or incompatible domains requires an external staged consumer.
+Applies bounded corrections to RGB channels that are already sampled and linear.
+Compatible shared geometry and per-channel CA are combined, so each channel is resampled once.
+A gain between geometry components, or incompatible domains, needs a separate staged caller.
 
 ```ts
 export function calculateLensCorrectedCapture(input: {
@@ -18,10 +18,10 @@ export function calculateLensCorrectedCapture(input: {
   application: ResolvedLensCorrectionPlan["application"];
   channels: Readonly<Record<LensCorrectionChannel, readonly (number | null)[]>>;
   samplingPlans: Partial<Record<LensCorrectionChannel, GeometricSamplingPlan>>;
-  /** Intersection across all channel footprints, before crop; no missing colors fabricated. */
+  /** Area valid in every channel, before cropping. Missing colours are never made up. */
   validSourceMask: readonly boolean[];
   jointCrop: GeometricSamplingPlan["jointCrop"];
-  /** Gain-stage clipping events before joint support/crop; repeated stages count separately. */
+  /** Clipping events in gain stages, before the shared valid-area crop. Each stage is counted separately. */
   illuminationClippingEventCount: number;
 }>;
 ```
@@ -30,7 +30,8 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## calculatePeripheralIlluminationCorrection
 
-Applies scalar post-capture gain and reports pre-clip variance; no photon/SNR history rewrite.
+Applies a gain after capture and reports the variance before clipping. It does not rewrite
+the photon or SNR (signal-to-noise ratio) history of the capture.
 
 ```ts
 export function calculatePeripheralIlluminationCorrection(input: {
@@ -43,7 +44,7 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## GenericLensCorrectionProfile
 
-Exact generic system binding, with components in authoritative application order.
+A correction profile for one exact lens-and-camera system. Components are listed in the order they are applied.
 
 ```ts
 export interface GenericLensCorrectionProfile {
@@ -58,7 +59,7 @@ export interface GenericLensCorrectionProfile {
 
 ## GeometricLensCorrection
 
-A separately declared correction map may deliberately retain physical distortion.
+A distortion correction map, declared separately. It may deliberately leave some physical distortion in place.
 
 ```ts
 export interface GeometricLensCorrection extends CorrectionComponentIdentity {
@@ -69,7 +70,7 @@ export interface GeometricLensCorrection extends CorrectionComponentIdentity {
 
 ## IlluminationLensCorrection
 
-Post-capture scalar gain; strength 0..1 leaves explicit residual falloff.
+Vignetting correction as a gain applied after capture. A strength below 1 deliberately leaves some falloff. Range 0..1.
 
 ```ts
 export interface IlluminationLensCorrection extends CorrectionComponentIdentity {
@@ -81,7 +82,7 @@ export interface IlluminationLensCorrection extends CorrectionComponentIdentity
 
 ## LateralCaLensCorrection
 
-Channel registration only, not longitudinal CA or color shading.
+Lateral CA: shifts colour channels into register. It does not correct longitudinal CA or colour shading.
 
 ```ts
 export interface LateralCaLensCorrection extends CorrectionComponentIdentity {
@@ -92,7 +93,7 @@ export interface LateralCaLensCorrection extends CorrectionComponentIdentity {
 
 ## LensCorrectionCapture
 
-Immutable capture identity accompanies downstream channels for meaningful On/Off comparisons.
+The fixed capture identity travels with the output channels, so On/Off comparisons use the same capture.
 
 ```ts
 export interface LensCorrectionCapture {
@@ -123,7 +124,7 @@ export type LensCorrectionComponent = GeometricLensCorrection | LateralCaLensCor
 
 ## parseGenericLensCorrectionProfile
 
-Strict parser for generic system corrections; no extrapolation or restoration claim.
+Strictly parses a generic correction profile. It does not extrapolate and makes no claim to restore lost detail.
 
 ```ts
 export function parseGenericLensCorrectionProfile(value: unknown): GenericLensCorrectionProfile;
@@ -142,14 +143,15 @@ export interface ResolvedLensCorrectionPlan {
   selectionKind: "camera-selectable" | "reference-bypass";
   components: readonly { component: LensCorrectionComponent; enabled: boolean;
     reason: "selected" | "default" | "mandatory" | "stabilization-dependency" | "component-dependency" | "reference-bypass" }[];
-  /** RAW-like intent remains metadata only in this first foundation. */
+  /** For now, a RAW-like intent is recorded as metadata only. */
   application: "metadata-only" | "bake-downstream";
 }
 ```
 
 ## resolveLensCorrectionPlan
 
-Resolves independent camera states, explicit dependencies, RAW intent and educational bypass.
+Decides which corrections apply for a camera state. It accounts for per-component settings,
+explicit dependencies between components, RAW intent and the educational "corrections off" bypass.
 
 ```ts
 export function resolveLensCorrectionPlan(input: {