@photivra/engine 0.1.0 → 0.4.0

package/docs/PHYSICS_FOUNDATION.md

@@ -14,14 +14,71 @@ where `d` is the relevant sensor dimension and `v` is the projection/image-plane
 
 When no focus distance is supplied, `v = f` is the infinity-focus/pinhole compatibility approximation. When focus distance is supplied, `v` is the ideal Gaussian thin-lens image distance.
 
-### Pixel pitch and crop
+For a centered sensor interval, the usual symmetric form is sufficient. For an off-center sensor interval, Photivra uses signed sensor-plane bounds relative to the optical axis:
 
-Pixel pitch is derived directly from active sensor width and horizontal active pixel count.
+`FOV = atan(x_max / v) - atan(x_min / v)`
 
-Centered crop dimensions are derived from a linear crop factor while preserving the source aspect ratio, subject to integer pixel flooring.
+This preserves asymmetric left/right or top/bottom angular limits instead of pretending every active crop is centered.
+
+### Sensor geometry, sampling, capture, and crop
+
+Photivra separates physical image-formation geometry from digital sampling.
+
+`SensorImagingArea` represents the physical photosensitive area used for image formation. It is not a sensor package/die dimension.
+
+`NativeImageRaster` represents the effective native image-sampling grid. It does not imply that one output/image sample corresponds one-to-one with one physical photodiode. Generic active/output rasters use `RasterDimensions`.
+
+Geometric sample pitch is derived independently on each axis:
+
+- `pitchX = imagingWidth / nativePixelWidth`;
+- `pitchY = imagingHeight / nativePixelHeight`.
+
+These pitches are geometric sample spacing only. They are not fill factor, effective collection area, or photon-collection area.
+
+The capture pipeline is staged:
+
+```text
+physical imaging area + native raster
+              ↓
+native active-capture rectangle
+              ↓
+physical camera orientation
+              ↓
+oriented active capture
+              ↓
+digital/output crop
+              ↓
+output raster
+```
+
+Native raster coordinates use a top-left origin with +X right and +Y down. Integer rectangles are half-open. Physical camera rotation does not redefine the native coordinate system; Photivra transforms points, vectors, and rectangles explicitly between native and oriented coordinates.
+
+For the generic sensor model, active physical dimensions and optical-axis offset are derived by assuming the native sampling grid uniformly spans the declared physical imaging area. This assumption is recorded because a future calibrated camera profile may need explicit physical active-area data instead.
+
+An off-center active rectangle changes both retained physical extent and angular position relative to the optical axis. It must therefore use asymmetric angular bounds rather than a centered FOV formula.
+
+For an off-center rectangular active area, the two opposite-corner diagonal angular spans need not be equal. `calculateActiveCaptureFieldOfView()` reports both and uses the larger span for its compatibility `diagonalDegrees` summary.
+
+Output crop/resampling is digital geometry. It does not mutate physical sensor identity or active-capture geometry. Output raster aspect ratio must remain consistent with the selected output crop; implicit geometric stretching is rejected.
+
+Centered crop dimensions are derived from a linear crop factor while preserving source aspect ratio, subject to integer pixel flooring.
 
 Subject-height framing crop computes the additional same-aspect crop needed to target a requested subject-height fraction. It assumes the crop can be positioned around the subject and does not check subject position against image edges.
 
+### Crop factor and 35 mm-equivalent focal length
+
+Physical crop factor is diagonal-based relative to a 36 × 24 mm reference frame:
+
+`cropFactor = diagonal_35mm / activeCaptureDiagonal`
+
+Conventional 35 mm-equivalent focal length is:
+
+`equivalentFocalLength = actualFocalLength × cropFactor`
+
+The actual focal length remains the optical focal length. Equivalent focal length is a derived framing convention; it does not replace physical focal length in projection or depth-of-field calculations.
+
+Photivra bases equivalence on the active physical capture area, not later digital/output crop. Physical orientation leaves the active diagonal unchanged and therefore does not change diagonal-based equivalent focal length. Different aspect ratios can still produce different horizontal/vertical FOV even when the single diagonal-equivalent number is the same.
+
 ### Projection, focus extension, object size, and motion
 
 Field of view, projected fronto-parallel object size, projected representative-point subject motion, and camera-shake projection support two explicit projection modes:
@@ -37,18 +94,110 @@ The focus-aware model improves internal consistency with thin-lens DOF/defocus c
 
 Projected subject motion is a representative-point displacement model with constant linear world velocity. It does not yet describe scale blur of an extended object whose magnification changes materially during the exposure.
 
+### Generic illumination vignetting
+
+The engine exposes a generic rotationally symmetric **relative linear illumination** model:
+
+```text
+T(rho) = 1 + r2*rho² + r4*rho⁴ + r6*rho⁶
+```
+
+where `rho` is ideal image-plane field radius divided by the caller-declared physical normalization radius.
+
+The optical axis is normalized to `T(0) = 1`.
+
+The declared `maximumNormalizedRadius` is a scientific operating envelope. Photivra evaluates the polynomial endpoints and all real internal extrema over the full interval and rejects profiles that:
+
+- produce zero/negative throughput; or
+- exceed the center-normalized throughput of 1.
+
+The result is a linear-light multiplicative attenuation plus equivalent positive stop loss.
+
+This slice is **not mechanical/pupil vignetting**. It does not clip the pupil or change bokeh/PSF shape. It also does not claim calibrated radiometry or named-lens behavior.
+
+### Generic lateral chromatic aberration
+
+The standalone lateral-CA foundation uses the green channel as the reference field mapping.
+
+A shared base radial-distortion profile defines the common geometric lens mapping. Red and blue coefficient offsets are added to that base before each channel is mapped:
+
+```text
+green coefficients = base
+red coefficients   = base + red offset
+blue coefficients  = base + blue offset
+```
+
+This keeps ordinary geometric distortion and lateral chromatic separation distinct while allowing one renderer pass to consume the combined per-channel mapping.
+
+The model deliberately does **not** represent CA as finished-image RGB blur. Forward mapping reports per-channel field coordinates and vector separation; inverse mapping reports the per-channel ideal source coordinate required for one distorted destination.
+
+All combined channel profiles share one physical normalization radius and operating envelope and must remain individually invertible.
+
+The RGB labels are representative renderer channels only. The model does not define wavelengths, sensor CFA responses, longitudinal chromatic aberration, wavelength-dependent PSFs, or calibrated real-lens color behavior.
+
+### Generic radial distortion
+
+The engine includes a standalone rotationally symmetric radial field-mapping approximation:
+
+```text
+p_distorted = p_ideal × (1 + k1 r² + k2 r⁴ + k3 r⁶)
+```
+
+where `r` is image-plane radius divided by a caller-declared physical normalization radius.
+
+The declared `maximumNormalizedRadius` is part of the scientific contract. Photivra checks the derivative of the radial mapping over that interval and rejects profiles that are not strictly one-to-one. This makes deterministic inverse destination-to-source sampling well-defined.
+
+The model is centered on the optical axis and does not yet include tangential/decentering terms. Coefficients are generic inputs, not real-lens calibration data.
+
+### Declared-scale focus breathing
+
+The root engine exposes a generic focus-breathing projection approximation.
+
+For one selected focus state:
+
+```text
+effective projection distance
+  = ideal thin-lens image distance × caller-declared breathing projection scale
+```
+
+Scale `1` exactly preserves the existing thin-lens projection.
+
+The model intentionally does not infer a focus-breathing curve. It represents focus-dependent framing/magnification only when the caller supplies the scale for that state. Physical focal length remains unchanged.
+
+This simplified scale does not model principal-plane movement, pupil magnification, distortion, aberrations, or a named commercial lens. Those require separate models and, for calibrated profiles, defensible provenance.
+
 ### Thin-lens focus and depth of field
 
 The geometric depth-of-field model uses the conventional hyperfocal/near/far equations with a caller-supplied acceptable circle of confusion.
 
 The circle-of-confusion criterion is a viewing/acceptability input, not a physical sensor threshold. The optional equivalent-viewing helper scales a caller-supplied reference criterion by sensor-diagonal ratio and is explicitly labeled an approximation.
 
+In composed POC capture mode, the equivalent-viewing helper uses the final retained physical image region that will be enlarged to the assumed final viewing size. Active capture, digital output crop, and centered subject framing can therefore change the viewing criterion; output pixel resolution alone cannot. This changes only the viewing/acceptability convention, not the physical optical blur. An explicit caller-supplied `circleOfConfusionMm` is never rescaled.
+
 The model is not a macro calibration model and does not include diffraction, pupil magnification, aberrations, focus breathing, or lens-specific principal-plane behavior in its DOF criterion.
 
 ### Defocus circle
 
 Defocus is calculated geometrically by comparing the selected sensor plane for the focus distance with the ideal image plane for the subject distance and projecting an ideal circular entrance-pupil cone to the sensor.
 
+### PSF/pupil foundation
+
+The engine now exposes a PSF/pupil foundation that evaluates existing geometric defocus and circular diffraction diagnostics in one explicit context while keeping the numerical contributions separate.
+
+The context declares:
+
+- physical image-plane field position;
+- a comparison-only field normalization radius;
+- focus and subject depth;
+- monochromatic wavelength basis;
+- ideal circular f-number-derived pupil size.
+
+The current foundation does **not** calculate a combined point-spread function or MTF. Defocus-circle diameter and Airy first-zero diameter are not added together or collapsed into one sharpness value.
+
+Reserved future contributions include non-circular diffraction, mechanical pupil clipping, field curvature, field-dependent aberration structure, and field-dependent bokeh.
+
+Illumination vignetting remains outside the PSF contribution list because it is currently modeled as throughput-only.
+
 ### Diffraction
 
 For an ideal circular aperture, first-zero Airy diameter is:
@@ -79,6 +228,44 @@ The current model returns one global image-plane vector. It does not compute the
 
 Equivalent stabilization stops attenuate angular displacement by `2^-stops`; that attenuation is explicitly an educational approximation rather than a real IBIS/OIS or CIPA performance model.
 
+### Radiometry readiness boundary
+
+Absolute scene luminance or relative exposure alone is not enough to derive a defensible photon count.
+
+Before any future composed photon simulation, Photivra requires an explicit prerequisite package covering:
+
+- scene spectral radiance or a documented spectral approximation;
+- optical transmission;
+- pupil/vignetting behavior;
+- photosite collection-area semantics;
+- exposure integration;
+- sensor spectral response / quantum efficiency;
+- evidence and uncertainty/limitation metadata for each component.
+
+`assessRadiometryReadiness()` can classify a declared package as `not-ready`, `approximate-only`, or `calibrated-ready`. This classification validates the declared model/evidence structure; it does not prove that the calibration is scientifically correct and does not itself calculate photons.
+
+Geometric sample pitch is intentionally insufficient as a collection-area model. A profile must provide either an effective collection area or geometric cell area plus explicit fill factor.
+
+Approximate inputs remain approximate even when every prerequisite category is present. A calibrated-ready declaration requires calibrated components with quantified uncertainty.
+
+The composed POC continues to emit no photon/photoelectron/SNR output from scene settings. Low-level `calculatePhotoelectrons()` remains a separate primitive for callers that already possess a defensible incident-photon count and QE.
+
+## Image-formation domain boundary
+
+Future optical and sensor models must follow `getImageFormationContract()`.
+
+The contract intentionally avoids describing all image formation as independent serial post-processing. Some quantities are coupled:
+
+- focus-dependent projection and lens mapping;
+- wavelength-dependent field mapping and PSF basis;
+- pupil clipping, throughput, and bokeh/PSF shape;
+- time-varying scene/camera mapping and sensor readout schedule;
+- native sensor sampling and reconstruction.
+
+Current analytical primitives remain valid and separately named. Adding a broader stage must not silently reinterpret existing focal length, defocus, diffraction, motion, crop, or sensor-sampling outputs.
+
+Reserved sensor stages in the contract are ordering placeholders only; they do not establish OLPF, CFA, photon, ADC, or reconstruction capabilities.
+
 ## Source provenance
 
 These implementations were written independently from established mathematical/physical relations. No third-party source code, calibration dataset, table, or model weight is incorporated by these scientific modules.

package/docs/POC_API.md

@@ -50,7 +50,7 @@ Example:
 {
   "ok": true,
   "service": "photivra-engine",
-  "apiVersion": "0.17.0"
+  "apiVersion": "0.20.0"
 }
 ```
 
@@ -62,13 +62,48 @@ Requests must use `Content-Type: application/json`.
 
 All physical quantities use explicit units in their property names.
 
-API 0.17 composes projection using the selected focus plane. The response includes a `projection` block with ideal thin-lens image distance, scale relative to the infinity-focus approximation, and model provenance. Full-sensor field of view, crop field of view, object sampling, subject motion, and camera-shake projection use that same selected projection plane.
+The POC transport reports the composed simulation contract version, not the root library `ENGINE_API_VERSION`. The current composed contract is exposed as `POC_SIMULATION_API_VERSION`.
+
+POC simulation API 0.20 composes projection using the selected focus plane. The response includes a `projection` block with ideal thin-lens image distance, scale relative to the infinity-focus approximation, and model provenance. Full-sensor field of view, crop field of view, object sampling, subject motion, and camera-shake projection use that same selected projection plane.
+
+### Sensor/capture composition in POC API 0.20
+
+POC simulation API 0.20 begins composing the standalone sensor/capture foundation **additively**.
+
+The existing request remains valid. New callers may opt into staged capture geometry with a `capture` object containing:
+
+- physical `orientation`;
+- optional native `activeCaptureRect`;
+- optional oriented `outputCropRect`;
+- optional final `outputRaster`.
+
+Compatibility rules are intentionally strict:
+
+- legacy `crop.factor` remains available for existing callers;
+- when `capture` is supplied, legacy `crop.factor` must be `1` so two crop models are not silently stacked;
+- legacy top-level `subjectCrop` response semantics remain unchanged when staged capture is absent;
+- with staged capture, subject framing is reported under `capture.subjectFraming` and is applied after declared output crop/resampling;
+- equivalent-viewing CoC in staged capture is based on the final retained physical image region used for viewing, including subject framing when present; output pixel count alone does not change it.
+
+The response keeps existing full-sensor/native-vector fields intact and adds an optional `capture` block with:
+
+- resolved native/active/oriented/output geometry, including final retained physical bounds;
+- active-capture and final-output FOV, including asymmetric bounds for off-center capture/output crop;
+- physical actual focal length plus active-capture diagonal-based 35 mm equivalence;
+- explicit oriented-capture→output pixel scaling;
+- optional capture-specific subject framing with final retained physical area and effective FOV;
+- explicit native-raster, oriented-capture, and final-output motion-vector diagnostics;
+- corresponding native-raster/oriented/output camera-shake vectors when camera shake is requested.
+
+Final digital/output crop does not redefine physical focal length or active-capture 35 mm equivalence. Physical `lens.focalLengthMm` remains the optical input.
+
+Sensor architecture metadata and radiometry-readiness profiles remain standalone foundations and are not yet composed into the POC.
 
 ### Required request groups
 
 The request includes:
 
-- sensor dimensions and resolution;
+- sensor physical imaging dimensions and native effective raster;
 - focal length and aperture;
 - shutter duration and ISO;
 - focus distance;
@@ -109,9 +144,33 @@ The top-level `fieldOfView` always describes the full sensor before digital crop
 
 This remains ideal paraxial geometry, not a real-lens focus-breathing calibration.
 
-### Crop
+### Sensor and staged capture geometry
 
-`crop` reports the requested fixed crop factor, retained pixel dimensions/area, megapixels, and its effective field of view.
+The `sensor` response now includes the shared `SensorGeometryMetrics` result in addition to the backwards-compatible representative pitch fields. This exposes physical imaging-area crop factor, exact native-raster megapixels, and independent X/Y geometric sample pitch without treating sample pitch as photosite collection area.
+
+When the opt-in `capture` request is present, the response additionally exposes the staged geometry pipeline:
+
+```text
+native physical imaging area + native raster
+                ↓
+native active-capture rectangle
+                ↓
+physical camera orientation
+                ↓
+oriented active capture
+                ↓
+digital/output crop
+                ↓
+final output raster
+```
+
+Native sensor coordinates remain invariant under orientation. Active-capture FOV is calculated from the physical retained area, including off-center asymmetric angular bounds.
+
+Legacy projected-motion/camera-shake X/Y values use the existing image-plane basis (+X right, +Y up). Capture raster coordinates use +X right, +Y down. The capture diagnostics therefore expose the explicit conversion to `nativeRasterDeltaPixels` before rotating to `orientedCaptureDeltaPixels` and scaling to `outputDeltaPixels`; legacy fields remain unchanged.
+
+### Legacy crop
+
+`crop` reports the requested legacy centered crop factor, retained pixel dimensions/area, megapixels, and its effective field of view.
 
 If `subjectCrop` is requested, subject framing is composed **after** the fixed crop. The response distinguishes:
 
@@ -122,8 +181,13 @@ If `subjectCrop` is requested, subject framing is composed **after** the fixed c
 
 The framing calculation assumes the crop can be positioned around the subject; it does not validate subject position against source-image edges.
 
+### Sensor sampling
+
+The response exposes horizontal and vertical geometric sampling pitch plus their relative difference. The composed POC still uses the backwards-compatible horizontal pitch as its representative scalar for blur/sampling calculations and therefore rejects sensor geometry whose X/Y pitch differs by more than 1%. This prevents silent directional error until the composed POC becomes fully axis-aware.
+
 ### Subject/object sampling
 
+
 When physical subject/object dimensions are supplied, projected dimensions are returned in sensor millimetres and pixels using the focus-aware projection plane.
 
 These values can drive pre-authored asset/detail selection without moving projection math into a renderer.
@@ -156,9 +220,11 @@ Polygon aperture geometry does not convert the circular Airy result into a polyg
 
 ### Focus criterion
 
-For cross-format comparisons, the equivalent-viewing helper scales a caller-supplied reference CoC by sensor-diagonal ratio.
+For cross-format comparisons, the equivalent-viewing helper scales a caller-supplied reference CoC by the diagonal of the physical image region assumed to be enlarged to the final viewing size.
+
+Legacy requests continue to use the full physical sensor. In staged capture mode the target is the final physical region retained by active capture + output crop and, when requested, centered subject framing. Changing only the encoded output raster does not change this viewing criterion.
 
-That is explicitly an approximation based on equivalent final viewing assumptions; it is not a physical lens/sensor blur threshold.
+This remains explicitly a viewing approximation, not a physical lens/sensor blur threshold. An explicit caller-supplied `circleOfConfusionMm` is never changed by crop or output geometry.
 
 ### Primary-subject diagnostics
 

package/docs/PROVENANCE.md

@@ -15,6 +15,20 @@ An implementation may be based on:
 
 A paper, standard, or patent publication may explain a method without granting copyright permission to copy its expression and without granting a patent license. Independent implementation addresses source-code/prose provenance; it does not by itself resolve active third-party patent claims.
 
+## Source evidence and reuse rights
+
+Factual/source evidence keeps **origin** separate from **reuse rights**.
+
+- `sourceOrigin` identifies who originated the referenced fact or data: manufacturer, third party, or Photivra.
+- `reuseStatus` identifies how Photivra may use it: factual-reference-only, reusable-data, or Photivra-owned.
+- Reusable data requires an explicit license.
+- Photivra-owned material must originate from Photivra.
+- Manufacturer or third-party sources may be either factual-reference-only or explicitly reusable when licensing supports that use.
+
+One evidence record must not silently support unrelated facts. Scalar metadata may cite multiple evidence records, and multi-valued capabilities should carry evidence per value.
+
+Evidence provenance is not a confidence score and does not establish scientific effect by itself. Descriptive hardware facts only affect calculations when a separate documented model explicitly consumes them.
+
 ## Independent implementation
 
 When a reference explains a method but does not license its implementation or text for reuse:
@@ -82,6 +96,16 @@ Valid-range metadata describes where a model/calibration is considered applicabl
 
 When composing models, preserve uncertainty components separately unless a documented model provides a defensible combination rule. Do not imply statistical independence, add errors in quadrature, or publish a single aggregate confidence score without evidence.
 
+## Radiometry readiness evidence
+
+Radiometry readiness is a declaration/validation gate, not proof that a calibration is correct.
+
+A component labeled `calibrated` must identify its model/version, supporting evidence, and quantified uncertainty. If uncertainty cannot yet be quantified, the component may still be represented, but the overall assessment cannot become `calibrated-ready`.
+
+Data-bearing calibration artifacts are referenced by stable identifier plus SHA-256 checksum. Publicly viewable curves/tables without reuse rights must not be copied into those artifacts. Manufacturer-published factual specifications may support independently authored models, while copied calibration datasets require explicit reusable licensing or Photivra ownership.
+
+An `approximation` remains explicitly approximate even when all prerequisite categories are present. Readiness must never be used to upgrade approximation provenance into calibration provenance.
+
 ## Release gate
 
 Ambiguous licensing, unresolved material patent risk, uncertain provenance, unexplained copied material, fabricated uncertainty, undocumented uncertainty combination, or unsupported scientific claims block release until resolved.

package/docs/PSF_FOUNDATION.md

@@ -0,0 +1,133 @@
+# PSF and Pupil Foundation
+
+Photivra's PSF/pupil foundation keeps optical blur contributions **separate and explicitly contextualized** until a defensible composition model exists.
+
+Use:
+
+```ts
+import {
+  calculatePsfFoundationComponents,
+  getPsfFoundationContract
+} from "@photivra/engine";
+
+const contract = getPsfFoundationContract();
+
+const components = calculatePsfFoundationComponents({
+  focalLengthMm: 85,
+  aperture: 2.8,
+  focusDistanceM: 10,
+  subjectDistanceM: 20,
+  fieldPointMm: { x: 12, y: 8 },
+  fieldNormalizationRadiusMm: 21.6,
+  spectralBasis: {
+    kind: "monochromatic",
+    wavelengthNm: 550
+  }
+});
+```
+
+## What is implemented
+
+The current foundation evaluates two existing diagnostics in one explicit context:
+
+- **geometric defocus circle** — the existing thin-lens defocus-circle diameter;
+- **circular diffraction first-zero diameter** — the existing ideal circular-pupil Airy diagnostic.
+
+Each contribution retains the provenance of its underlying primitive.
+
+The foundation records:
+
+- physical image-plane field position;
+- normalized field radius for comparison;
+- focus and subject depth;
+- monochromatic wavelength basis;
+- ideal circular f-number-derived pupil diameter.
+
+## What is deliberately not calculated
+
+The foundation does **not** currently calculate:
+
+- a combined PSF;
+- a convolution kernel;
+- MTF;
+- one combined blur diameter;
+- a lens-sharpness score.
+
+Defocus and diffraction are independent diagnostics. A future combined PSF must document the mathematical composition method and assumptions rather than adding their diameters or scores ad hoc.
+
+## Reserved contributions
+
+The public contract reserves ownership for:
+
+- non-circular diffraction;
+- mechanical/pupil clipping;
+- field curvature;
+- field-dependent aberration/PSF structure;
+- field-dependent bokeh.
+
+A reserved contribution is not an implemented capability.
+
+## Field position
+
+Field position uses physical image-plane coordinates:
+
+- optical axis at the origin;
+- +X right;
+- +Y up;
+- millimetres.
+
+`fieldNormalizationRadiusMm` exists only to make center/mid/edge/corner comparisons reproducible. It is not a real-lens calibration or model-validity limit by itself.
+
+The current defocus and circular Airy diagnostics are field invariant. Recording field position now gives future field-dependent contributions a stable context without changing those existing calculations.
+
+## Spectral basis
+
+The current foundation accepts an explicit monochromatic wavelength because the circular Airy diagnostic is wavelength dependent.
+
+This does not create:
+
+- a spectral lens model;
+- longitudinal chromatic aberration;
+- sensor spectral response;
+- CFA/color calibration.
+
+Future wavelength-dependent PSFs must declare their basis explicitly.
+
+## Pupil boundary
+
+The current context records an ideal circular, f-number-derived pupil diameter because the existing defocus/Airy diagnostics use circular-pupil assumptions.
+
+Polygon aperture geometry is not automatically a non-circular diffraction PSF.
+
+Mechanical/pupil vignetting is also separate from illumination vignetting:
+
+- illumination vignetting changes throughput only;
+- pupil clipping can change throughput **and** PSF/bokeh shape.
+
+## Preview and reference fidelity
+
+Browser preview and higher-fidelity reference implementations may use different numerical approximations or sampling budgets.
+
+They must preserve the same:
+
+- contribution identities;
+- field/depth/spectral context;
+- pupil semantics;
+- engine-owned parameters;
+- scientific limitations.
+
+A preview approximation must not redefine the science merely because it is cheaper to render.
+
+## Test Fixture relationship
+
+Test Fixture v0.3 provides deterministic center/mid/edge/corner detail and point-highlight targets for integration regression.
+
+It does not establish:
+
+- calibrated MTF;
+- a measured real-lens PSF;
+- spectral lens behavior;
+- calibrated mechanical vignetting;
+- named-lens performance.
+
+Engine analytical/reference tests remain the scientific source of truth.

package/docs/STABILIZATION.md

@@ -26,11 +26,24 @@ Projection has two modes:
 
 When pixel pitch is supplied, the same displacement is also reported in sensor pixels.
 
+The returned X/Y shake components are expressed in the primitive's sensor/image-plane axes. `estimateCameraShakeBlur()` does not accept `CaptureOrientation` and does not rotate its vector into portrait/oriented output coordinates. A caller combining this primitive with the capture-orientation layer must explicitly transform the vector with the orientation helpers.
+
 The supplied shake profile is synthetic input. The model is not an empirical statement about how much a particular photographer shakes.
 
-### Spatial limitation
+### Spatial limitation and the separate rotation primitive
+
+`estimateCameraShakeBlur()` intentionally remains one global image-plane yaw/pitch vector for backwards compatibility with the existing stabilization-equivalent teaching model.
+
+The root engine now separately exposes `calculateCameraRotationImageMapping()`, which models field-position-dependent **pure camera rotation** for yaw/pitch/roll at arbitrary physical time from exposure start.
+
+The two APIs do not share sign semantics:
+
+- the legacy shake estimator preserves its historical direct image-plane displacement convention;
+- the spatial rotation primitive represents physical camera rotation using right-hand pitch/yaw/roll, then maps a stationary world ray through the inverse camera rotation.
+
+Do not substitute one result for the other without an explicit migration.
 
-The current result is one global image-plane yaw/pitch vector. Real camera rotation produces position-dependent optical flow away from the optical axis; that spatial variation is not yet modeled. Roll and translational camera motion are also omitted.
+The spatial primitive does not apply stabilization stops. Real IBIS/OIS behavior and translation/parallax remain separate future models.
 
 ## Equivalent stabilization stops
 
@@ -60,11 +73,11 @@ Only the public standard identifier and high-level terminology are referenced he
 
 ## Not yet modeled
 
-The current model intentionally omits:
+The legacy stabilization-equivalent model intentionally omits:
 
 - roll;
 - translational camera shake;
-- spatially varying rotational optical flow;
+- spatially varying rotational optical flow inside this compatibility API;
 - frequency-dependent shake spectra;
 - photographer-to-photographer variation;
 - shutter-button impulse;