@photivra/engine 2.4.1 → 2.6.0

package/docs/api/exports.json

@@ -1,6 +1,6 @@
 {
-  "packageVersion": "2.4.1",
-  "engineApiVersion": "2.4.1",
+  "packageVersion": "2.6.0",
+  "engineApiVersion": "2.6.0",
   "exports": [
     {
       "name": "AbsoluteUncertaintyEstimate",
@@ -437,6 +437,16 @@
       "source": "src/output/crop.ts",
       "kind": "type"
     },
+    {
+      "name": "calculateChartFraming",
+      "source": "src/facade/subject-framing.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "CalculateChartFramingInput",
+      "source": "src/facade/subject-framing.ts",
+      "kind": "type"
+    },
     {
       "name": "calculateChartRadianceBatch",
       "source": "src/facade/chart-radiance-batch.ts",
@@ -1842,6 +1852,11 @@
       "source": "src/facade/chart-scenes.ts",
       "kind": "type"
     },
+    {
+      "name": "ChartFraming",
+      "source": "src/facade/subject-framing.ts",
+      "kind": "type"
+    },
     {
       "name": "ChartRadianceBatchInput",
       "source": "src/facade/chart-radiance-batch.ts",
@@ -2567,6 +2582,11 @@
       "source": "src/core/spectral-composition.ts",
       "kind": "type"
     },
+    {
+      "name": "DisplayViewResult",
+      "source": "src/facade/simulate-capture.ts",
+      "kind": "type"
+    },
     {
       "name": "DistributeIntegratedQuantityAcrossDiscreteLinesInput",
       "source": "src/core/spectral-composition.ts",
@@ -7892,6 +7912,11 @@
       "source": "src/facade/simulate-capture.ts",
       "kind": "runtime"
     },
+    {
+      "name": "SIMULATE_DISPLAY_VIEW_DEFAULT_SAMPLES_PER_AXIS",
+      "source": "src/facade/simulate-capture.ts",
+      "kind": "runtime"
+    },
     {
       "name": "simulateCapture",
       "source": "src/facade/simulate-capture.ts",
@@ -7987,6 +8012,16 @@
       "source": "src/capture/simulated-capture.ts",
       "kind": "type"
     },
+    {
+      "name": "simulateDisplayView",
+      "source": "src/facade/simulate-display-view.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "SimulateDisplayViewOptions",
+      "source": "src/facade/simulate-capture.ts",
+      "kind": "type"
+    },
     {
       "name": "simulateEnvironmentSensorRawFrame",
       "source": "src/capture/environment-raw-producer.ts",

package/docs/api/facade-simulate-capture.md

@@ -2,6 +2,42 @@
 
 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.
 
+## DisplayViewResult
+
+Result of {@link simulateDisplayView }: the full-resolution capture resized for display, estimated; not a capture.
+
+```ts
+export interface DisplayViewResult {
+  kind: "display-view";
+  /** Human-readable label for a user interface. */
+  label: string;
+  facadeVersion: typeof SIMULATE_CAPTURE_FACADE_VERSION;
+  engineApiVersion: string;
+  /** The display view (or its region): interleaved sRGB samples, row by row from the top-left. */
+  image: { width: number; height: number; format: "srgb-8" | "srgb-16"; samples: Uint8Array | Uint16Array };
+  /**
+   * The view: display size, the capture frame it shows (output pixels), real pixels per display pixel along each axis,
+   * the samples per axis and, with `view.region`, the rendered rectangle.
+   */
+  view: { width: number; height: number; frameWidth: number; frameHeight: number; scaleX: number; scaleY: number; samplesPerAxis: number;
+    region?: { x: number; y: number; width: number; height: number } };
+  /** The resolved exposure of the capture this view shows. */
+  exposure: { mode: SimulateCaptureExposureMode; settings: { fNumber: number; shutterSeconds: number; iso: number }; ev100: number };
+  scene: SimulateCaptureResult["scene"];
+  /**
+   * Work done: real pixels sampled, real-site expectations evaluated, scene queries, display pixels sampled in full (detail) or with
+   * a quarter of the samples per axis (uniform), display pixels whose value includes the AHD low-signal correction, and wall-clock
+   * milliseconds (diagnostic only; never affects the samples).
+   */
+  diagnostics: { sampleCount: number; siteEvaluations: number; sceneLookups: number; detailPixelCount: number; uniformPixelCount: number; ahdCorrectedPixelCount: number;
+    timingsMs: { view: number; total: number } };
+  provenance: { scientificStatus: "approximation"; cameraPresetId: string; cameraPresetVersion: string; evidence: readonly EvidenceProvenance[];
+    composedContracts: readonly string[]; limitations: readonly string[] };
+  /** The capture request's assumptions, then `view.definition`, `view.estimation`, `view.noise`, `view.demosaic` and `view.source`. */
+  assumptions: readonly SimulateCaptureAssumption[];
+}
+```
+
 ## IdealReferenceResult
 
 Result of {@link simulateIdealReference}: an ideal reference image, not a capture (no RAW, plan or request).
@@ -65,6 +101,14 @@ Version of how the facade builds requests. It changes whenever the same input wo
 SIMULATE_CAPTURE_FACADE_VERSION = "1.0.0" as const
 ```
 
+## SIMULATE_DISPLAY_VIEW_DEFAULT_SAMPLES_PER_AXIS
+
+Default stratified samples per axis of a display view (`view.samplesPerAxis`): 16 × 16 sampled real pixels per display pixel with detail, 4 × 4 where it is uniform.
+
+```ts
+SIMULATE_DISPLAY_VIEW_DEFAULT_SAMPLES_PER_AXIS = 16
+```
+
 ## simulateCapture
 
 Simulates one still capture of a planar scene and returns the developed image, the packed RAW, the full
@@ -285,14 +329,20 @@ export interface SimulateCaptureOptions {
      * the whole render: framing, metering, exposure, noise seeds (absolute native site indices), rolling-shutter row
      * timing, diffraction and demosaic all use the whole frame. Use it to tile a large frame across workers or to
      * render a 100 % crop. `result.image` is the region; `result.region` reports it. Not combinable with
-     * `whiteBalance: "auto"`, whose statistics would come from the region only.
+     * `whiteBalance: "auto"`, whose statistics would come from the region only. From 2.6 the diffraction convolution
+     * covers only the region plus the kernel and filter reach, so a small region of a large frame costs about as much
+     * as a capture of the region's size.
      */
     region?: { x: number; y: number; width: number; height: number };
   };
   /** Camera motion and shutter type. Default: still camera, global electronic shutter. */
   motion?: SimulateCaptureMotion;
   sensor?: {
-    /** Pixel pitch in micrometres. Default 6. */
+    /**
+     * Pixel pitch in micrometres, 0.5–1000. Default 6. The simulated sensor is output width × pitch wide. 2.5: above 100 µm the
+     * capture is a downsized view of a whole frame (for example 36 mm / 48 pixels = 750 µm), recorded in the assumption
+     * `sensor.wholeFrameView`: brightness is unchanged and the noise is that of a binned view, not of the real sensor's pixels.
+     */
     pixelPitchMicrometers?: number;
     /** Maximum spectral quadrature subinterval in nm. Default 20. */
     spectralStepNanometers?: number;
@@ -499,6 +549,24 @@ export type SimulateCaptureWhiteBalance =
   | { channelGains: { red: number; green: number; blue: number } };
 ```
 
+## SimulateDisplayViewOptions
+
+The display size and sampling of {@link simulateDisplayView }.
+
+```ts
+export interface SimulateDisplayViewOptions {
+  /** Display pixels, 1 to the capture's output width and height. */
+  width: number;
+  height: number;
+  /** Stratified Monte Carlo samples per axis for each display pixel's expected value (1–32, default 8: 64 real pixels). */
+  samplesPerAxis?: number;
+  /** "srgb-8" (default) or "srgb-16". */
+  format?: "srgb-8" | "srgb-16";
+  /** Render only this rectangle of the display view, in display pixels; byte-identical to the same pixels of the whole view. */
+  region?: { x: number; y: number; width: number; height: number };
+}
+```
+
 ## simulateIdealReference
 
 The ideal reference of a capture request (2.3): the same scene, framing, chart size, output size, region and pixel

package/docs/api/facade-simulate-display-view.md

@@ -0,0 +1,18 @@
+# facade/simulate-display-view.ts public contracts
+
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## simulateDisplayView
+
+The display view of a capture request: the image the real full-resolution capture (`simulateCapture(options)`) would
+give after it is resized to `view.width` × `view.height` by area averaging in linear light, estimated at a cost that
+follows the display pixels, not the capture's. Optics (lens diffraction, the anti-aliasing filter, the pixel aperture)
+act at the real pixel pitch; the colour mosaic, demosaic and development are those of the real pixels; the noise is
+that of the average of the real pixels, demosaic correlation included; exposure, white balance and tone are the
+capture's. The result is labelled `kind: "display-view"`; it is not a capture.
+
+```ts
+export async function simulateDisplayView(options: SimulateCaptureOptions, view: SimulateDisplayViewOptions): Promise<DisplayViewResult>;
+```
+
+This call is asynchronous; byte hashing uses the caller runtime's Web Crypto.

package/docs/api/facade-subject-framing.md

@@ -2,6 +2,39 @@
 
 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.
 
+## calculateChartFraming
+
+How much of the frame a chart of a given physical size covers at any subject distance (2.5): magnification, framed plane size,
+coverage fractions (above 1 when cropped), the chart's image size and the minimum-focus check. The same thin-lens framing as
+`simulateCapture` (`scene.framing`, `result.scene.chart`) and `calculateSubjectDistanceForFraming`.
+
+```ts
+export function calculateChartFraming(input: CalculateChartFramingInput): ChartFraming;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateChartFramingInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateChartFramingInput {
+  /** Active sensor (or simulated frame) size, mm: for `simulateCapture`, output width × height × pixel pitch. */
+  sensor: { widthMm: number; heightMm: number };
+  /** Physical focal length, mm. Give exactly one of this and `equivalentFocalLengthMm`. */
+  focalLengthMm?: number;
+  /** Full-frame-equivalent focal length (diagonal crop factor); a generic prime's value also reports that lens (as `lens.prime`). */
+  equivalentFocalLengthMm?: number;
+  /** Chart size as for `simulateCapture` `chartSize`: heightM defaults to widthM × the sensor aspect (height / width). */
+  chart: { widthM: number; heightM?: number };
+  /** Distance from the lens to the chart plane, metres; more than the focal length. */
+  subjectDistanceM: number;
+  /** Focus distance, metres (as `lens.focusDistanceM`); default the subject distance. More than the focal length. */
+  focusDistanceM?: number;
+}
+```
+
 ## calculateSubjectDistanceForFraming
 
 The subject distance that fits a chart of a given physical size to the frame, with magnification, coverage and the minimum-focus check (2.3).
@@ -30,6 +63,48 @@ export interface CalculateSubjectDistanceForFramingInput {
 }
 ```
 
+## ChartFraming
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ChartFraming {
+  subjectDistanceM: number;
+  focusDistanceM: number;
+  /** Thin-lens image distance at the focus distance, f·s/(s − f), mm. */
+  imageDistanceMm: number;
+  /** Image size ÷ object size on the chart plane, v/d: f/(d − f) when focused on the chart. */
+  magnification: number;
+  focalLengthMm: number;
+  equivalentFocalLengthMm: number;
+  cropFactor35Mm: number;
+  chart: { widthM: number; heightM: number };
+  /** Plane area the frame covers at the subject distance, metres: sensor side ÷ magnification. */
+  framedWidthM: number;
+  framedHeightM: number;
+  /** Fraction of the frame width and height the chart covers; above 1 means the chart is larger than the frame and cropped. */
+  coverage: { frameWidthFraction: number; frameHeightFraction: number };
+  /** The chart's image on the sensor, mm. */
+  chartImageMm: { width: number; height: number };
+  /**
+   * 2.6: the thin-lens close-up light factor at the focus distance, 1/(1 + m)² with m = v/s: the image-plane irradiance
+   * relative to the same lens and f-number focused at infinity (working f-number N·(1 + m)). It is the factor
+   * `simulateCapture` applies through the scene-to-sensor irradiance (same function, same value).
+   */
+  closeUpTransmission: number;
+  /** 2.6: the same factor in stops, 2·log₂(1 + m): how much darker the image is than at infinity focus. */
+  closeUpLossStops: number;
+  /** The generic prime of this equivalent focal length, when there is one. */
+  prime: GenericPrimeLens | null;
+  /** The generic prime rule max(0.10 m, f·(1 + 1/0.15)) at this focal length (the prime's own value when there is one). */
+  minimumFocusDistanceM: number;
+  /** True when the subject or focus distance is closer than the minimum focus distance (`simulateCapture` with `lens.prime` rejects it). */
+  belowMinimumFocus: boolean;
+  scientificStatus: "approximation";
+  assumptions: readonly SimulateCaptureAssumption[];
+}
+```
+
 ## SubjectFraming
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -52,6 +127,14 @@ export interface SubjectFraming {
   framedHeightM: number;
   /** Fraction of the frame width and height the chart covers (1 on the fitted side; above 1 means cropped). */
   coverage: { frameWidthFraction: number; frameHeightFraction: number };
+  /**
+   * 2.6: the thin-lens close-up light factor at the focus distance, 1/(1 + m)² with m = v/s: the image-plane irradiance
+   * relative to the same lens and f-number focused at infinity (working f-number N·(1 + m)). It is the factor
+   * `simulateCapture` applies through the scene-to-sensor irradiance (same function, same value).
+   */
+  closeUpTransmission: number;
+  /** 2.6: the same factor in stops, 2·log₂(1 + m): how much darker the image is than at infinity focus. */
+  closeUpLossStops: number;
   /** The generic prime of this equivalent focal length, when there is one. */
   prime: GenericPrimeLens | null;
   /** The generic prime rule max(0.10 m, f·(1 + 1/0.15)) at this focal length (the prime's own value when there is one). */

package/docs/api/optics-diffraction-psf-profile.md

@@ -71,7 +71,14 @@ export interface DiffractionLimitedPsfProfile {
   wavelengths: readonly DiffractionLimitedPsfWavelength[];
   /** Largest truncated energy over the wavelengths. */
   maximumTruncatedEnergyFraction: number;
-  quadrature: { method: "polar-frequency-domain-trapezoid-gauss-legendre"; maximumRadialNodes: number; maximumAngularNodes: number };
+  /**
+   * How the cells were integrated. 2.5: wavelengths with β = p·f_c ≥ 192 (cells far larger than the pattern) use the real-space
+   * encircled-energy method; `realSpaceWavelengthsNm` lists them, and `method` is `"frequency-domain-and-real-space"` when both ran.
+   * `maximumRadialNodes` counts frequency-domain radial nodes (0 when only the real-space method ran); `maximumAngularNodes` the
+   * angular nodes of either method (for the real-space method, all θ nodes of one wavelength).
+   */
+  quadrature: { method: "polar-frequency-domain-trapezoid-gauss-legendre" | "real-space-encircled-energy-gauss-legendre" | "frequency-domain-and-real-space";
+    maximumRadialNodes: number; maximumAngularNodes: number; realSpaceWavelengthsNm?: readonly number[] };
 }
 ```
 

package/docs/api/output-print-plan.md

@@ -5,7 +5,11 @@ The package and root API versions are recorded once in [Navigation](../API_REFER
 ## calculatePrintPlan
 
 Finds the smallest file, at the exact native aspect ratio, that meets the declared sampling and lab constraints.
-The angular guidance is an approximate rule of thumb; the geometry itself is calculated exactly.
+The angular guidance is an approximate rule of thumb; the geometry itself is calculated exactly. A common criterion,
+one arcminute per pixel, is normal (20/20) visual acuity under optimal conditions: the minimum angle of resolution of an
+ideal eye is about 1 minute of arc, and 20/20 letters are built from elements that each subtend 1 arcmin (Z. Alomar, K. D. Bojikian, "Visual Acuity Testing in Adults", EyeWiki, American Academy of Ophthalmology,
+https://eyewiki.aao.org/Visual_Acuity_Testing_in_Adults, last edited June 16, 2026).
+Some viewers resolve finer detail and many resolve coarser, so it stays a rule of thumb, and the criterion is the caller's.
 It does not assess source detail, perceived quality, file writing or available resources.
 
 ```ts
@@ -18,6 +22,9 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 Calculates the largest print size under the stated conditions. Lab constraints need individual plans,
 so this size query reports them as unsupported rather than ignoring them.
+As in `calculatePrintPlan`, an angular criterion is an approximate rule of thumb: one arcminute per pixel is normal
+(20/20) acuity under optimal conditions, which some viewers exceed and many do not (Z. Alomar, K. D. Bojikian, "Visual Acuity Testing in Adults", EyeWiki, American Academy of Ophthalmology,
+https://eyewiki.aao.org/Visual_Acuity_Testing_in_Adults, last edited June 16, 2026).
 
 ```ts
 export function calculatePrintSizeLimit(value: PrintSizeLimitInput): CalculationResult<PrintSizeLimit>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@photivra/engine",
-  "version": "2.4.1",
+  "version": "2.6.0",
   "private": false,
   "description": "Scientific TypeScript engine for camera optics, exposure, focus, motion, sensor sampling, diffraction, and digital imaging calculations.",
   "type": "module",
@@ -108,7 +108,8 @@
     "typescript-eslint": "8.70.0",
     "vitest": "5.0.1",
     "@types/node": "24.13.6",
-    "@vitest/coverage-v8": "5.0.1"
+    "@vitest/coverage-v8": "5.0.1",
+    "rolldown": "1.2.9"
   },
   "keywords": [
     "photography",