@photivra/engine 2.5.0 → 2.7.0

package/docs/api/facade-scene-radiance.md

@@ -2,6 +2,31 @@
 
 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.
 
+## CALLER_MATERIAL_SCENE_MAX_MATERIALS
+
+Most materials a {@link CallerMaterialScene} may list.
+
+```ts
+CALLER_MATERIAL_SCENE_MAX_MATERIALS = 65_536
+```
+
+## CallerMaterialScene
+
+2.7 (#386): a piecewise-constant caller scene, lit by the facade illuminant like a reflectance function. `materials` are
+reflectances as a chart's patches take them (a neutral number in [0, 1] or a reflectance spectrum covering 380–780 nm, at
+most {@link CALLER_MATERIAL_SCENE_MAX_MATERIALS}); `materialAt` returns the index of the material at a plane point (an
+integer from 0 to materials.length − 1). The radiance at a point is that material's, exactly as for a reflectance function
+returning its reflectance, but renderers can tabulate each material once: the display view then takes the chart path.
+
+```ts
+export interface CallerMaterialScene {
+  kind: "material-function";
+  sceneId: string;
+  materials: readonly ChartReflectance[];
+  materialAt(point: Readonly<SceneMaterialPoint>): number;
+}
+```
+
 ## CallerRadianceScene
 
 Caller absolute spectral radiance in W·m⁻²·sr⁻¹·nm⁻¹; the facade illuminant is not used.
@@ -65,7 +90,7 @@ provider `providerProfileId`.
 
 ```ts
 export function createPlanarSceneRadianceProvider(input: {
-  scene: ChartScene | CallerReflectanceScene | CallerRadianceScene;
+  scene: ChartScene | CallerReflectanceScene | CallerRadianceScene | CallerMaterialScene;
   illuminant: CaptureIlluminant;
   illuminanceLux: number;
   distanceM: number;
@@ -140,6 +165,14 @@ export interface ResolvedCaptureIlluminant {
 }
 ```
 
+## SceneMaterialPoint
+
+2.7: a scene-plane point without a wavelength, passed to a material scene's `materialAt`.
+
+```ts
+export type SceneMaterialPoint = Omit<ScenePlanePoint, "wavelengthNanometers">;
+```
+
 ## ScenePlanePoint
 
 A point of the scene plane passed to caller scene functions.

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
@@ -220,7 +264,7 @@ export interface SimulateCaptureOptions {
     compensationStops?: number;
   };
   /** Required: an engine chart (for example `{ preset: "uniform" }`, an 18 % grey card) or a caller reflectance/radiance function. */
-  scene: ChartScene | CallerReflectanceScene | CallerRadianceScene;
+  scene: ChartScene | CallerReflectanceScene | CallerRadianceScene | CallerMaterialScene;
   /** Distance from the camera to the scene plane in metres. Default 5. */
   subjectDistanceM?: number;
   /**
@@ -285,7 +329,9 @@ 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 };
   };
@@ -503,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,57 @@
+# 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.
+
+## PreparedDisplayView
+
+2.7: a display-view request resolved once (`prepareDisplayView`). `render(view)` gives the same result as
+`simulateDisplayView(options, view)` for the prepared options, byte for byte (samples, view, exposure, scene, diagnostics
+and assumptions; only `diagnostics.timingsMs` differ, and they cover the render only), without repeating the request's
+setup: use it to render one view in many regions, for example on each worker of a progressive display.
+
+```ts
+export interface PreparedDisplayView {
+  /** Renders a view of the prepared request. Renders may run concurrently; they share no state except read-only setup. */
+  render(view: SimulateDisplayViewOptions, renderOptions?: PreparedDisplayViewRenderOptions): Promise<DisplayViewResult>;
+}
+```
+
+## PreparedDisplayViewRenderOptions
+
+Options of one {@link PreparedDisplayView} render.
+
+```ts
+export interface PreparedDisplayViewRenderOptions {
+  /** Aborting cancels this render only; the promise rejects with a domain error. The request's own `signal` applies to preparing only. */
+  signal?: AbortSignal;
+}
+```
+
+## prepareDisplayView
+
+2.7 (#387): resolves a {@link simulateDisplayView} request once, without a view, and returns a handle whose `render(view)`
+renders its views. The setup it does once (request validation, the camera, lens, scene, chart and illuminant, the channel
+responses through the environment chain, the diffraction kernels, readout moments, demosaic tables and colour matrix) costs
+about 0.3–1.3 s per call on a 24 MP request; a region costs only its own pixels. Errors in the request are raised here;
+errors in the view by `render`.
+
+```ts
+export async function prepareDisplayView(options: SimulateCaptureOptions): Promise<PreparedDisplayView>;
+```
+
+This call is asynchronous; byte hashing uses the caller runtime's Web Crypto.
+
+## 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

@@ -86,6 +86,14 @@ export interface ChartFraming {
   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). */
@@ -119,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/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.5.0",
+  "version": "2.7.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",