@photivra/engine 2.5.0 → 2.7.0

package/dist/sensor/stochastic-seed.js

@@ -16,6 +16,7 @@
  * correlation tests, not this hash alone, show that the resulting noise is statistically acceptable.
  */
 import { InvalidScientificInputError } from "../core/validation.js";
+import { portableCosTwoPi, portableLog, portableSinTwoPi } from "../core/portable-math.js";
 /** Stream IDs. Changing them changes every simulated RAW code. */
 export const NATIVE_SITE_CHARGE_STREAM_ID = 0;
 export const NATIVE_SITE_READ_NOISE_STREAM_ID = 1;
@@ -69,17 +70,21 @@ export function deriveNativeSiteStreamSeedUint32(captureSeedUint32, nativeSiteIn
  * Changing any of this changes simulated RAW output and needs a model and replay review.
  */
 export function createDeterministicUniformStream(seedUint32) {
-    let state = fmix32((seedUint32 ^ 0x9e3779b9) >>> 0);
-    if (state === 0) {
-        state = 0x6d2b79f5;
+    // The state lives in a Uint32Array: storing the int32 result there is the same `>>> 0` reduction, and a uint32 above
+    // 2^30 kept in a closure variable would be boxed on every step (half the speed). The draws are unchanged.
+    const state = new Uint32Array(1);
+    state[0] = fmix32((seedUint32 ^ 0x9e3779b9) >>> 0);
+    if (state[0] === 0) {
+        state[0] = 0x6d2b79f5;
     }
     return {
         next() {
-            state ^= state << 13;
-            state ^= state >>> 17;
-            state ^= state << 5;
-            state >>>= 0;
-            return (state + 0.5) / 0x1_0000_0000;
+            let x = state[0];
+            x ^= x << 13;
+            x ^= x >>> 17;
+            x ^= x << 5;
+            state[0] = x;
+            return (state[0] + 0.5) / 0x1_0000_0000;
         }
     };
 }
@@ -93,6 +98,35 @@ export function sampleDeterministicStandardNormal(random) {
     const u2 = random.next();
     return Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
 }
+/**
+ * The same Box–Muller draw (same two uniforms, same order) with the engine's portable logarithm and cosine
+ * (`portableLog`, `portableCosTwoPi`), so the sample has the same bits in every JavaScript engine. Used by the
+ * display view; the native noise keeps `sampleDeterministicStandardNormal`.
+ */
+export function samplePortableStandardNormal(random) {
+    const u1 = random.next();
+    const u2 = random.next();
+    return Math.sqrt(-2 * portableLog(u1)) * portableCosTwoPi(u2);
+}
+/**
+ * Standard normal samples from one stream, two per pair of uniforms: both Box–Muller outputs, r·cos(2πu₂) and then
+ * r·sin(2πu₂) with r = √(−2 ln u₁) (Box & Muller 1958; the two are independent standard normals), with the portable
+ * functions. Each call returns the next sample; the stream advances by two uniforms on every other call. Used by the
+ * display view's AHD correction states, which draw many normals from one stream.
+ */
+export function createPortableStandardNormalPairs(random) {
+    let spare = 0, hasSpare = false;
+    return () => {
+        if (hasSpare) {
+            hasSpare = false;
+            return spare;
+        }
+        const u1 = random.next(), u2 = random.next(), r = Math.sqrt(-2 * portableLog(u1));
+        spare = r * portableSinTwoPi(u2);
+        hasSpare = true;
+        return r * portableCosTwoPi(u2);
+    };
+}
 /**
  * Fixed-pattern stream IDs. They seed spatial patterns that belong to one physical sensor, never
  * per-capture noise, and are hashed with the sensor-instance seed instead of the capture seed.

package/dist/sensor/stochastic-seed.js.map

@@ -1 +1 @@
-{"version":3,"file":"stochastic-seed.js","sourceRoot":"","sources":["../../src/sensor/stochastic-seed.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Seeds for the random-number streams behind simulated sensor noise. The same inputs always give\n * the same noise.\n *\n * Each per-site stream seed is a strong 32-bit hash of the capture seed, the absolute native\n * row-major site index and a fixed stream ID. The hash is MurmurHash3_x86_32 (Austin Appleby,\n * placed in the public domain) of the 12-byte little-endian message `[captureSeed, siteIndex,\n * streamId]` with hash seed 0. Its avalanche finalizer (`fmix32`) makes a one-bit input change flip\n * each output bit with probability close to 1/2. So neighbouring sites, the two streams of one site\n * and captures with nearby seeds get unrelated seeds. A linear schedule such as `seed + 2*index` fed\n * into a linear generator (xorshift) lacks this property, and produced correlated noise with too\n * little variance (issue #270).\n *\n * This is deterministic and not cryptographic; it does not claim unpredictability. The moment and\n * correlation tests, not this hash alone, show that the resulting noise is statistically acceptable.\n */\n\nimport { InvalidScientificInputError } from \"../core/validation.js\";\n\n/** Stream IDs. Changing them changes every simulated RAW code. */\nexport const NATIVE_SITE_CHARGE_STREAM_ID = 0 as const;\nexport const NATIVE_SITE_READ_NOISE_STREAM_ID = 1 as const;\n\nconst MURMUR3_C1 = 0xcc9e2d51;\nconst MURMUR3_C2 = 0x1b873593;\n\n/** MurmurHash3 32-bit avalanche finalizer; a bijection on uint32 with fmix32(0) = 0. */\nexport function fmix32(value: number): number {\n  let h = value >>> 0;\n  h ^= h >>> 16;\n  h = Math.imul(h, 0x85ebca6b);\n  h ^= h >>> 13;\n  h = Math.imul(h, 0xc2b2ae35);\n  h ^= h >>> 16;\n  return h >>> 0;\n}\n\nfunction mixBlock(hash: number, block: number): number {\n  let k = Math.imul(block >>> 0, MURMUR3_C1);\n  k = (k << 15) | (k >>> 17);\n  k = Math.imul(k, MURMUR3_C2);\n  let h = (hash ^ k) >>> 0;\n  h = (h << 13) | (h >>> 19);\n  return (Math.imul(h, 5) + 0xe6546b64) >>> 0;\n}\n\nfunction isUint32(value: number): boolean {\n  return Number.isInteger(value) && value >= 0 && value <= 0xffffffff;\n}\n\n/**\n * Returns the uint32 seed of one random stream for one absolute native site.\n * All inputs must be uint32 integers. The site index is the full-frame native row-major\n * index, never relative to a tile or chunk, so how the work is split cannot change it.\n */\nexport function deriveNativeSiteStreamSeedUint32(\n  captureSeedUint32: number,\n  nativeSiteIndex: number,\n  streamId: number\n): number {\n  if (!isUint32(captureSeedUint32) || !isUint32(nativeSiteIndex) || !isUint32(streamId)) {\n    throw new InvalidScientificInputError(\"Stochastic stream seed inputs must be uint32 integers.\");\n  }\n  let h = 0;\n  h = mixBlock(h, captureSeedUint32);\n  h = mixBlock(h, nativeSiteIndex);\n  h = mixBlock(h, streamId);\n  return fmix32(h ^ 12);\n}\n\n/** One deterministic stream of uniforms strictly inside (0,1). */\nexport interface DeterministicUniformStream {\n  next(): number;\n}\n\n/**\n * Creates the deterministic, non-cryptographic xorshift32 random stream for one charge, read-noise\n * or fixed-pattern identity.\n *\n * The seed is first scrambled by the MurmurHash3 `fmix32` avalanche finalizer. xorshift32 is linear\n * over GF(2), so an unscrambled seed would give nearby seeds almost identical first draws, and noise\n * that is correlated across the sensor with too little variance (issue #270). The nonzero fallback\n * avoids the zero state, which xorshift can never leave. Adding 0.5 before dividing gives values\n * strictly inside (0,1), so the logarithms in the Poisson and normal transforms never see 0 or 1.\n * Changing any of this changes simulated RAW output and needs a model and replay review.\n */\nexport function createDeterministicUniformStream(seedUint32: number): DeterministicUniformStream {\n  let state = fmix32((seedUint32 ^ 0x9e3779b9) >>> 0);\n  if (state === 0) {\n    state = 0x6d2b79f5;\n  }\n  return {\n    next(): number {\n      state ^= state << 13;\n      state ^= state >>> 17;\n      state ^= state << 5;\n      state >>>= 0;\n      return (state + 0.5) / 0x1_0000_0000;\n    }\n  };\n}\n\n/**\n * Box–Muller transform of two uniform values in (0,1) (Box & Muller 1958). Each call uses two values\n * and returns one standard normal sample. The second possible sample is not cached, so the order of\n * draws from the stream never shifts.\n */\nexport function sampleDeterministicStandardNormal(random: DeterministicUniformStream): number {\n  const u1 = random.next();\n  const u2 = random.next();\n  return Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);\n}\n\n/**\n * Fixed-pattern stream IDs. They seed spatial patterns that belong to one physical sensor, never\n * per-capture noise, and are hashed with the sensor-instance seed instead of the capture seed.\n */\nexport const SENSOR_FIXED_PATTERN_PRNU_STREAM_ID = 16 as const;\nexport const SENSOR_FIXED_PATTERN_DSNU_STREAM_ID = 17 as const;\nexport const SENSOR_FIXED_PATTERN_HOT_PIXEL_STREAM_ID = 18 as const;\nexport const SENSOR_FIXED_PATTERN_ROW_STREAM_ID = 19 as const;\nexport const SENSOR_FIXED_PATTERN_COLUMN_STREAM_ID = 20 as const;\n\n/**\n * Returns the uint32 seed of one fixed-pattern stream for one physical colour-sampling site: the\n * MurmurHash3_x86_32 hash (hash seed 0) of the 16-byte little-endian message\n * `[sensorInstanceSeed, siteX, siteY, streamId]`. Site coordinates are absolute indices in the\n * colour-sampling grid, so the pattern belongs to the physical sensor and does not change with crop,\n * tiling or the per-capture seed. Deterministic and not cryptographic.\n */\nexport function deriveSensorFixedPatternSeedUint32(\n  sensorInstanceSeedUint32: number,\n  siteX: number,\n  siteY: number,\n  streamId: number\n): number {\n  if (!isUint32(sensorInstanceSeedUint32) || !isUint32(siteX) || !isUint32(siteY) || !isUint32(streamId)) {\n    throw new InvalidScientificInputError(\"Fixed-pattern seed inputs must be uint32 integers.\");\n  }\n  let h = 0;\n  h = mixBlock(h, sensorInstanceSeedUint32);\n  h = mixBlock(h, siteX);\n  h = mixBlock(h, siteY);\n  h = mixBlock(h, streamId);\n  return fmix32(h ^ 16);\n}\n"]}
+{"version":3,"file":"stochastic-seed.js","sourceRoot":"","sources":["../../src/sensor/stochastic-seed.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Seeds for the random-number streams behind simulated sensor noise. The same inputs always give\n * the same noise.\n *\n * Each per-site stream seed is a strong 32-bit hash of the capture seed, the absolute native\n * row-major site index and a fixed stream ID. The hash is MurmurHash3_x86_32 (Austin Appleby,\n * placed in the public domain) of the 12-byte little-endian message `[captureSeed, siteIndex,\n * streamId]` with hash seed 0. Its avalanche finalizer (`fmix32`) makes a one-bit input change flip\n * each output bit with probability close to 1/2. So neighbouring sites, the two streams of one site\n * and captures with nearby seeds get unrelated seeds. A linear schedule such as `seed + 2*index` fed\n * into a linear generator (xorshift) lacks this property, and produced correlated noise with too\n * little variance (issue #270).\n *\n * This is deterministic and not cryptographic; it does not claim unpredictability. The moment and\n * correlation tests, not this hash alone, show that the resulting noise is statistically acceptable.\n */\n\nimport { InvalidScientificInputError } from \"../core/validation.js\";\nimport { portableCosTwoPi, portableLog, portableSinTwoPi } from \"../core/portable-math.js\";\n\n/** Stream IDs. Changing them changes every simulated RAW code. */\nexport const NATIVE_SITE_CHARGE_STREAM_ID = 0 as const;\nexport const NATIVE_SITE_READ_NOISE_STREAM_ID = 1 as const;\n\nconst MURMUR3_C1 = 0xcc9e2d51;\nconst MURMUR3_C2 = 0x1b873593;\n\n/** MurmurHash3 32-bit avalanche finalizer; a bijection on uint32 with fmix32(0) = 0. */\nexport function fmix32(value: number): number {\n  let h = value >>> 0;\n  h ^= h >>> 16;\n  h = Math.imul(h, 0x85ebca6b);\n  h ^= h >>> 13;\n  h = Math.imul(h, 0xc2b2ae35);\n  h ^= h >>> 16;\n  return h >>> 0;\n}\n\nfunction mixBlock(hash: number, block: number): number {\n  let k = Math.imul(block >>> 0, MURMUR3_C1);\n  k = (k << 15) | (k >>> 17);\n  k = Math.imul(k, MURMUR3_C2);\n  let h = (hash ^ k) >>> 0;\n  h = (h << 13) | (h >>> 19);\n  return (Math.imul(h, 5) + 0xe6546b64) >>> 0;\n}\n\nfunction isUint32(value: number): boolean {\n  return Number.isInteger(value) && value >= 0 && value <= 0xffffffff;\n}\n\n/**\n * Returns the uint32 seed of one random stream for one absolute native site.\n * All inputs must be uint32 integers. The site index is the full-frame native row-major\n * index, never relative to a tile or chunk, so how the work is split cannot change it.\n */\nexport function deriveNativeSiteStreamSeedUint32(\n  captureSeedUint32: number,\n  nativeSiteIndex: number,\n  streamId: number\n): number {\n  if (!isUint32(captureSeedUint32) || !isUint32(nativeSiteIndex) || !isUint32(streamId)) {\n    throw new InvalidScientificInputError(\"Stochastic stream seed inputs must be uint32 integers.\");\n  }\n  let h = 0;\n  h = mixBlock(h, captureSeedUint32);\n  h = mixBlock(h, nativeSiteIndex);\n  h = mixBlock(h, streamId);\n  return fmix32(h ^ 12);\n}\n\n/** One deterministic stream of uniforms strictly inside (0,1). */\nexport interface DeterministicUniformStream {\n  next(): number;\n}\n\n/**\n * Creates the deterministic, non-cryptographic xorshift32 random stream for one charge, read-noise\n * or fixed-pattern identity.\n *\n * The seed is first scrambled by the MurmurHash3 `fmix32` avalanche finalizer. xorshift32 is linear\n * over GF(2), so an unscrambled seed would give nearby seeds almost identical first draws, and noise\n * that is correlated across the sensor with too little variance (issue #270). The nonzero fallback\n * avoids the zero state, which xorshift can never leave. Adding 0.5 before dividing gives values\n * strictly inside (0,1), so the logarithms in the Poisson and normal transforms never see 0 or 1.\n * Changing any of this changes simulated RAW output and needs a model and replay review.\n */\nexport function createDeterministicUniformStream(seedUint32: number): DeterministicUniformStream {\n  // The state lives in a Uint32Array: storing the int32 result there is the same `>>> 0` reduction, and a uint32 above\n  // 2^30 kept in a closure variable would be boxed on every step (half the speed). The draws are unchanged.\n  const state = new Uint32Array(1);\n  state[0] = fmix32((seedUint32 ^ 0x9e3779b9) >>> 0);\n  if (state[0] === 0) {\n    state[0] = 0x6d2b79f5;\n  }\n  return {\n    next(): number {\n      let x = state[0]!;\n      x ^= x << 13;\n      x ^= x >>> 17;\n      x ^= x << 5;\n      state[0] = x;\n      return (state[0] + 0.5) / 0x1_0000_0000;\n    }\n  };\n}\n\n/**\n * Box–Muller transform of two uniform values in (0,1) (Box & Muller 1958). Each call uses two values\n * and returns one standard normal sample. The second possible sample is not cached, so the order of\n * draws from the stream never shifts.\n */\nexport function sampleDeterministicStandardNormal(random: DeterministicUniformStream): number {\n  const u1 = random.next();\n  const u2 = random.next();\n  return Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);\n}\n\n/**\n * The same Box–Muller draw (same two uniforms, same order) with the engine's portable logarithm and cosine\n * (`portableLog`, `portableCosTwoPi`), so the sample has the same bits in every JavaScript engine. Used by the\n * display view; the native noise keeps `sampleDeterministicStandardNormal`.\n */\nexport function samplePortableStandardNormal(random: DeterministicUniformStream): number {\n  const u1 = random.next();\n  const u2 = random.next();\n  return Math.sqrt(-2 * portableLog(u1)) * portableCosTwoPi(u2);\n}\n\n/**\n * Standard normal samples from one stream, two per pair of uniforms: both Box–Muller outputs, r·cos(2πu₂) and then\n * r·sin(2πu₂) with r = √(−2 ln u₁) (Box & Muller 1958; the two are independent standard normals), with the portable\n * functions. Each call returns the next sample; the stream advances by two uniforms on every other call. Used by the\n * display view's AHD correction states, which draw many normals from one stream.\n */\nexport function createPortableStandardNormalPairs(random: DeterministicUniformStream): () => number {\n  let spare = 0, hasSpare = false;\n  return () => {\n    if (hasSpare) { hasSpare = false; return spare; }\n    const u1 = random.next(), u2 = random.next(), r = Math.sqrt(-2 * portableLog(u1));\n    spare = r * portableSinTwoPi(u2); hasSpare = true;\n    return r * portableCosTwoPi(u2);\n  };\n}\n\n/**\n * Fixed-pattern stream IDs. They seed spatial patterns that belong to one physical sensor, never\n * per-capture noise, and are hashed with the sensor-instance seed instead of the capture seed.\n */\nexport const SENSOR_FIXED_PATTERN_PRNU_STREAM_ID = 16 as const;\nexport const SENSOR_FIXED_PATTERN_DSNU_STREAM_ID = 17 as const;\nexport const SENSOR_FIXED_PATTERN_HOT_PIXEL_STREAM_ID = 18 as const;\nexport const SENSOR_FIXED_PATTERN_ROW_STREAM_ID = 19 as const;\nexport const SENSOR_FIXED_PATTERN_COLUMN_STREAM_ID = 20 as const;\n\n/**\n * Returns the uint32 seed of one fixed-pattern stream for one physical colour-sampling site: the\n * MurmurHash3_x86_32 hash (hash seed 0) of the 16-byte little-endian message\n * `[sensorInstanceSeed, siteX, siteY, streamId]`. Site coordinates are absolute indices in the\n * colour-sampling grid, so the pattern belongs to the physical sensor and does not change with crop,\n * tiling or the per-capture seed. Deterministic and not cryptographic.\n */\nexport function deriveSensorFixedPatternSeedUint32(\n  sensorInstanceSeedUint32: number,\n  siteX: number,\n  siteY: number,\n  streamId: number\n): number {\n  if (!isUint32(sensorInstanceSeedUint32) || !isUint32(siteX) || !isUint32(siteY) || !isUint32(streamId)) {\n    throw new InvalidScientificInputError(\"Fixed-pattern seed inputs must be uint32 integers.\");\n  }\n  let h = 0;\n  h = mixBlock(h, sensorInstanceSeedUint32);\n  h = mixBlock(h, siteX);\n  h = mixBlock(h, siteY);\n  h = mixBlock(h, streamId);\n  return fmix32(h ^ 16);\n}\n"]}

package/docs/AGENT_GUIDE.md

@@ -20,6 +20,7 @@ one-call capture, see the [Quick Start](QUICK_START.md). For every export, see t
 | Task | Call | Notes |
 | --- | --- | --- |
 | Simulate a full photo | [`simulateCapture`](api/facade-simulate-capture.md#simulatecapture) | Async. Returns an image, the RAW data, `assumptions` and `provenance`. |
+| Preview a whole frame as the real capture resized for display | [`simulateDisplayView`](api/facade-simulate-display-view.md#simulatedisplayview) | Async. Takes the capture's request plus a display size; costs follow the display pixels. Labelled `kind: "display-view"`: a preview, never a capture. |
 | Exposure value (EV) of a setting | [`calculateExposureValue100`](api/exposure-exposure.md#calculateexposurevalue100) | EV at ISO 100 = log2(N²/t). |
 | Keep brightness after changing aperture or shutter | [`calculateEquivalentIso`](api/exposure-exposure.md#calculateequivalentiso) | Returns the compensating ISO. Not a noise model. |
 | Compare two exposures in stops | [`calculateRelativeRenderedExposure`](api/exposure-exposure.md#calculaterelativerenderedexposure) | Includes ISO as gain. |

package/docs/API_REFERENCE.md

@@ -1,6 +1,6 @@
 # Public API reference
 
-Generated from the exact root exports for **@photivra/engine 2.5.0 / root contract 2.5.0** by `node scripts/generate-api-reference.mjs`. No module deep import is supported.
+Generated from the exact root exports for **@photivra/engine 2.7.0 / root contract 2.7.0** by `node scripts/generate-api-reference.mjs`. No module deep import is supported.
 
 Use [the developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md) for executable paths and scientific boundaries. Types are contracts, not runtime validation: parse untrusted data, preserve units/reference frames, read assessment blockers, and retain evidence/limitations. Optional properties do not imply a universal default. Model/schema IDs remain independent of the distribution.
 
@@ -11,6 +11,7 @@ Start here to find a function by task. [Using Photivra from an agent](AGENT_GUID
 | Task | Functions |
 | --- | --- |
 | Simulate a full photo (async) | [`simulateCapture`](api/facade-simulate-capture.md#simulatecapture) |
+| Preview a whole frame as the real capture resized (async) | [`simulateDisplayView`](api/facade-simulate-display-view.md#simulatedisplayview) |
 | Exposure value and equivalent settings | [`calculateExposureValue100`](api/exposure-exposure.md#calculateexposurevalue100), [`calculateEquivalentIso`](api/exposure-exposure.md#calculateequivalentiso), [`calculateRelativeRenderedExposure`](api/exposure-exposure.md#calculaterelativerenderedexposure) |
 | Depth of field, hyperfocal distance and defocus blur | [`calculateDepthOfField`](api/optics-depth-of-field.md#calculatedepthoffield), [`calculateDefocusCircle`](api/optics-depth-of-field.md#calculatedefocuscircle) |
 | Field of view | [`calculateFieldOfView`](api/camera-field-of-view.md#calculatefieldofview) |
@@ -1161,6 +1162,8 @@ Start here to find a function by task. [Using Photivra from an agent](AGENT_GUID
 
 | Export | Kind |
 | --- | --- |
+| [`CALLER_MATERIAL_SCENE_MAX_MATERIALS`](api/facade-scene-radiance.md#caller_material_scene_max_materials) | Runtime |
+| [`CallerMaterialScene`](api/facade-scene-radiance.md#callermaterialscene) | Type |
 | [`CallerRadianceScene`](api/facade-scene-radiance.md#callerradiancescene) | Type |
 | [`CallerReflectanceScene`](api/facade-scene-radiance.md#callerreflectancescene) | Type |
 | [`CaptureIlluminant`](api/facade-scene-radiance.md#captureilluminant) | Type |
@@ -1171,6 +1174,7 @@ Start here to find a function by task. [Using Photivra from an agent](AGENT_GUID
 | [`PlanarSceneRadianceProvider`](api/facade-scene-radiance.md#planarsceneradianceprovider) | Type |
 | [`resolveCaptureIlluminant`](api/facade-scene-radiance.md#resolvecaptureilluminant) | Runtime |
 | [`ResolvedCaptureIlluminant`](api/facade-scene-radiance.md#resolvedcaptureilluminant) | Type |
+| [`SceneMaterialPoint`](api/facade-scene-radiance.md#scenematerialpoint) | Type |
 | [`ScenePlanePoint`](api/facade-scene-radiance.md#sceneplanepoint) | Type |
 
 ## facade/simulate-capture.ts
@@ -1179,11 +1183,13 @@ Start here to find a function by task. [Using Photivra from an agent](AGENT_GUID
 
 | Export | Kind |
 | --- | --- |
+| [`DisplayViewResult`](api/facade-simulate-capture.md#displayviewresult) | Type |
 | [`IdealReferenceResult`](api/facade-simulate-capture.md#idealreferenceresult) | Type |
 | [`SIMULATE_CAPTURE_BOX_APERTURE_DEFAULT_SAMPLES`](api/facade-simulate-capture.md#simulate_capture_box_aperture_default_samples) | Runtime |
 | [`SIMULATE_CAPTURE_COST_OPTIONS`](api/facade-simulate-capture.md#simulate_capture_cost_options) | Runtime |
 | [`SIMULATE_CAPTURE_DEFAULT_ILLUMINANCE_LUX`](api/facade-simulate-capture.md#simulate_capture_default_illuminance_lux) | Runtime |
 | [`SIMULATE_CAPTURE_FACADE_VERSION`](api/facade-simulate-capture.md#simulate_capture_facade_version) | Runtime |
+| [`SIMULATE_DISPLAY_VIEW_DEFAULT_SAMPLES_PER_AXIS`](api/facade-simulate-capture.md#simulate_display_view_default_samples_per_axis) | Runtime |
 | [`simulateCapture`](api/facade-simulate-capture.md#simulatecapture) | Runtime |
 | [`SimulateCaptureAssumption`](api/facade-simulate-capture.md#simulatecaptureassumption) | Type |
 | [`SimulateCaptureBorderHandling`](api/facade-simulate-capture.md#simulatecaptureborderhandling) | Type |
@@ -1200,8 +1206,20 @@ Start here to find a function by task. [Using Photivra from an agent](AGENT_GUID
 | [`SimulateCaptureResult`](api/facade-simulate-capture.md#simulatecaptureresult) | Type |
 | [`SimulateCaptureSensorAntiAliasing`](api/facade-simulate-capture.md#simulatecapturesensorantialiasing) | Type |
 | [`SimulateCaptureWhiteBalance`](api/facade-simulate-capture.md#simulatecapturewhitebalance) | Type |
+| [`SimulateDisplayViewOptions`](api/facade-simulate-capture.md#simulatedisplayviewoptions) | Type |
 | [`simulateIdealReference`](api/facade-simulate-capture.md#simulateidealreference) | Runtime |
 
+## facade/simulate-display-view.ts
+
+[Detailed contracts](api/facade-simulate-display-view.md) · [Source](https://github.com/Photivra/photivra/blob/main/src/facade/simulate-display-view.ts)
+
+| Export | Kind |
+| --- | --- |
+| [`PreparedDisplayView`](api/facade-simulate-display-view.md#prepareddisplayview) | Type |
+| [`PreparedDisplayViewRenderOptions`](api/facade-simulate-display-view.md#prepareddisplayviewrenderoptions) | Type |
+| [`prepareDisplayView`](api/facade-simulate-display-view.md#preparedisplayview) | Runtime |
+| [`simulateDisplayView`](api/facade-simulate-display-view.md#simulatedisplayview) | Runtime |
+
 ## facade/subject-framing.ts
 
 [Detailed contracts](api/facade-subject-framing.md) · [Source](https://github.com/Photivra/photivra/blob/main/src/facade/subject-framing.ts)

package/docs/QUICK_START.md

@@ -233,6 +233,16 @@ const coverage = calculateChartFraming({ sensor: { widthMm: 36, heightMm: 24 },
 console.log(coverage.coverage.frameWidthFraction, coverage.magnification, coverage.belowMinimumFocus);
 ```
 
+**Close-up light (2.6).** Focused close, the lens delivers less light: the working f-number is N·(1 + m) with m = v/s at
+the focus distance (ideal symmetric thin lens, unity pupil magnification), so the image-plane irradiance falls by
+1/(1 + m)² compared with the same f-number at infinity focus. `calculateChartFraming` and
+`calculateSubjectDistanceForFraming` report it as `closeUpTransmission` (1/(1 + m)²) and `closeUpLossStops` (2·log₂(1 + m),
+how many stops darker). Both come from the same function as the factor `simulateCapture` applies in the scene-to-sensor
+irradiance, so they cannot drift apart; a test checks the RAW signal ratio of a uniform chart at 0.35 m and 50 m against
+them within 0.5 %. With the 50 mm prime: 0.81 (0.30 stop darker) at 0.5 m, 0.90 (0.15 stop) at 1 m, 0.95 (0.07 stop) at
+2 m and 0.98 (0.03 stop) at 5 m. Show it to users as "about N stops darker at this distance"; it is the thin-lens
+model, not a measured lens (real lenses with non-unity pupil magnification differ).
+
 Tests check that at `calculateSubjectDistanceForFraming`'s distance the coverage is 1 on the fitted side (every fit,
 three sensor shapes, four primes), and that at any distance it equals `result.scene.chart` from `simulateCapture` with
 `chartSize` (magnification, both coverage fractions, the chart's image size and the framed size, within 1e-12
@@ -292,6 +302,10 @@ What changes and what does not:
 
 Requests at 0.5–100 µm are byte-identical to 2.4.1.
 
+A whole-frame view simulates a camera with giant pixels. For a preview that looks like the real camera's photo
+shrunk to the frame size (the real pixel pitch for the optics, the real mosaic and the noise of the averaged real
+pixels), use [Display view](#display-view) instead.
+
 ### ISO and pixel size
 
 The tier's ISO signal chain (conversion gain, saturation signal and read noise per ISO setting) is
@@ -440,6 +454,34 @@ const vignette = await simulateCapture({
 console.log(vignette.request.whiteBalanceState?.source);
 ```
 
+**Piecewise-constant scenes (2.7).** A scene made of a few uniform reflectances, such as a chart with a printed label,
+can be passed as `{ kind: "material-function", sceneId, materials, materialAt }`. `materials` lists reflectances as a
+chart's patches take them: a neutral number in [0, 1], or a reflectance spectrum covering 380–780 nm. `materialAt`
+receives the plane point without a wavelength and returns the index of its material.
+
+The radiance at each point is the same as a reflectance function returning that material's reflectance. Captures and
+ideal references are therefore byte-identical to the reflectance-function form. The display view, though, tabulates
+each material once and takes the chart presets' path.
+
+```ts
+import { resolveChartScene, simulateDisplayView } from "@photivra/engine";
+
+const chart = resolveChartScene({ scene: { preset: "siemens-star" }, aspect: 2 / 3 });
+const label = chart.materials.length;   // one extra material: a printed label in the lower left
+const view = await simulateDisplayView({
+  scene: { kind: "material-function", sceneId: "star-with-label",
+    materials: [...chart.materials.map((m) => (m.kind === "neutral" ? m.reflectance : 0.5)), 0.05],
+    materialAt: (p) => (p.u < -0.6 && p.v < -0.5 ? label : chart.materialAt(p.u, p.v)) },
+  output: { width: 600, height: 400 }
+}, { width: 300, height: 200 });
+console.log(view.diagnostics.sceneLookups);
+```
+
+The display view's expected values match the reflectance-function form to rounding, because they are the same
+quantities summed in another order. Measured on the app's chart with a maker label (a 24 MP frame, the 2028 × 1352 view's
+centre strip, one thread), the material form took 1.15 s instead of 3.2 s with the defaults, and 3.0 s instead of 111 s
+with diffraction, the four-spot filter and AHD.
+
 ## White balance
 
 | Value | Meaning |
@@ -686,6 +728,14 @@ The optics options feed only what the environment site contract accepts:
     lit circular pupil (scalar Fraunhofer diffraction), aberration-free and in focus, with pupil diameter
     f/N and the thin-lens image distance (working f-number N·v/f). Each kernel holds the PSF energy of
     site-sized cells, one kernel per spectral node.
+  - Sources: the Airy pattern is the textbook Fraunhofer diffraction pattern of a circular aperture
+    (Born & Wolf, *Principles of Optics*, 7th ed., §8.5.2; Goodman, *Introduction to Fourier Optics*,
+    4th ed., §4.4). The kernels come from the pupil's incoherent optical transfer function (Goodman,
+    4th ed., §7.3; MIT OpenCourseWare 2.71, lectures 21–22, free). The first dark ring is at
+    1.22·λ·N_w (j₁,₁/π with j₁,₁ = 3.8317, the first zero of J₁), so the Airy disk diameter is
+    2.44·λ·N_w, and the energy inside radius r is 1 − J₀(x)² − J₁(x)², x = π·r/(λ·N_w) (Wyant &
+    Creath 1992, §II, eqs. 1–4, free). The Bessel-function relations and expansions come from the
+    NIST DLMF (free). Full references are under [Sources](#sources).
   - The kernel window reaches the third dark ring at the longest node by default (2, 4 and 7 sites at
     f/4, f/8 and f/16 with 6 µm pixels); set `kernelRadiusSamples` (0–32) to change it. The Airy tail
     outside the window (2–6 % of the energy with the default) is listed per wavelength in the
@@ -927,6 +977,8 @@ Ratios below about 1.1× are within the run-to-run spread (the three default run
 (anti-aliasing spots, pupil rays, PSF taps, temporal samples) multiply the run time by about the same
 factor, and output-side options cost almost nothing.
 
+The cost of `simulateDisplayView` is in [Display view](#display-view).
+
 ### Measuring cost on the user's device
 
 From 2.1 every result says what ran and how long each stage took, so an application can decide on the
@@ -1045,10 +1097,16 @@ How it stays identical:
   own edges the region raster ends exactly where the whole frame's does, so `borderHandling: "mirror"`
   mirrors at the same place. AHD reads at most 5 sites away, so its edge-directed choices see the same
   neighbourhood.
-- **Diffraction:** the object-space convolution is computed in whole-width bands of 32 native rows
-  around the region's rows, as in the whole render (the same bands, kernels and summation order). A
-  frame split into k tile columns therefore repeats that convolution k times; tile by rows (full-width
-  strips) to avoid it.
+- **Diffraction (2.6: region-limited):** the object-space convolution covers only the scene lattice the
+  region's native sites query: the native rectangle plus the anti-aliasing and box-aperture offsets on
+  each side, in bands of at most 32 native rows, with the kernel radius of real scene radiance around it.
+  Each kept value is the same gather as in the whole render (the same kernel, the same taps in the same
+  order, and every tap inside the grid), so the values are bit-identical while the work follows the
+  region plus its halo instead of the frame width. In 2.3–2.5 the bands spanned the whole frame width, so
+  a small crop of a wide frame paid for the full width and k tile columns repeated it k times. The noise
+  needs no frame-wide state: each site's stream is seeded by a hash of the capture seed and its absolute
+  native index (`seedSchedule: "murmur3-capture-seed-native-index-stream-v2"`), so it is counter-based,
+  not a position in one frame-wide stream; the demosaic and the filters read only the margin above.
 
 Measured on one core (Node 24, 4-vCPU Intel Xeon 2.80 GHz, built `dist`, one run each): a 256 × 256
 slanted edge took 8.45 s whole, 9.03 s as four 256 × 64 strips and 8.44 s as four 128 × 128 tiles run
@@ -1056,6 +1114,25 @@ one after another; with `lens.diffraction` 10.2 s whole and 12.9 s as four tiles
 convolution bands). A 64 × 64 crop of a 4000 × 3000 frame took 0.63 s, the same as a plain 64 × 64
 capture. Tiles in parallel workers divide the wall time by the number of cores.
 
+**A 100 % crop with the slow options (2.6).** A 192 × 128 region at the centre of a 6000 × 4000 frame at 6 µm,
+Siemens star, f/16, `output.maximumPixels: NATIVE_RAW_LIMITS.ceilingPixels` (one fresh Node 24.21.0 process per
+row, 4-vCPU Intel Xeon 2.80 GHz, built `dist`, one run each; `diagnostics.timingsMs`):
+
+| Options | 2.5.0 total (convolution) | 2.6 total (convolution) | Peak resident memory, 2.5.0 → 2.6 |
+| --- | --- | --- | --- |
+| defaults | 3.6 s (—) | 3.6 s (—) | 320 → 304 MB |
+| diffraction, four-spot filter, AHD | 60.8 s (50.2 s) | 11.8 s (1.7 s) | 556 → 379 MB |
+| diffraction, four-spot filter, AHD, box 2 × 2 | 228.7 s (195.8 s) | 39.6 s (6.5 s) | 1 285 → 545 MB |
+
+On a GitHub-hosted `ubuntu-latest` runner (4 vCPU AMD EPYC 7763, Node 24, one run each) the same rows took 2.7 → 2.6 s,
+44.1 → 8.3 s and 170.9 → 27.7 s; from 2.6 the box row takes 19.4 s, because the engine no longer re-parses the fixed parts of its own chart scenes' results (caller scenes keep the full validation). The samples are byte-identical between the two versions. What remains is the per-site work, which grows with the
+scene queries per site (20 spectral nodes × the filter spots × the box nodes: 80 per site with the filter, 320
+with the filter and the 2 × 2 box) and with the region's sites, not with the frame.
+
+`output.maximumPixels` is still needed for a region of a frame wider or taller than 4094 pixels: the request,
+plan and noise seeds are those of the whole frame, and the whole frame's native raster is checked against the
+limit. The allocations follow the region, so the opt-in costs no memory for the rest of the frame.
+
 `result.image` holds the region, `result.raw` and `result.plan` describe the region's native sites (the
 plan's active area is the region; `result.region.nativeRect` gives them in the whole frame), and
 `result.region` reports the rectangle and the frame. `diagnostics.options` lists `output.region`.
@@ -1117,6 +1194,101 @@ const [capture, reference] = await Promise.all([simulateCapture(request), simula
 console.log(reference.kind, reference.label, capture.image.samples.length === reference.image.samples.length);
 ```
 
+## Display view
+
+`simulateDisplayView(options, view)` returns what the real full-resolution capture of `options` would look like
+resized to `view.width` × `view.height`, at a cost that follows the display pixels. Pass the same request you use
+for the export, with the real sensor's pixel count and pitch:
+
+```ts
+import { NATIVE_RAW_LIMITS, simulateCapture, simulateDisplayView, type SimulateCaptureOptions } from "@photivra/engine";
+
+const request: SimulateCaptureOptions = { scene: { preset: "dead-leaves" }, lens: { prime: 35, fNumber: 2.8 }, subjectDistanceM: 3,
+  sensor: { pixelPitchMicrometers: 6 }, output: { width: 6000, height: 4000, maximumPixels: NATIVE_RAW_LIMITS.ceilingPixels } };
+const preview = await simulateDisplayView(request, { width: 384, height: 256 });   // on screen
+console.log(preview.kind, preview.label, preview.diagnostics.timingsMs.view);
+// The export stays a real capture: simulateCapture(request), or tiles of it with output.region.
+const crop = await simulateCapture({ ...request, output: { ...request.output, region: { x: 2968, y: 1968, width: 64, height: 64 } } });
+console.log(crop.image.width);
+```
+
+**What each display pixel is.** The area-weighted mean, in linear light, of the real output pixels its rectangle covers
+(6000 ÷ 384 = 15.625 real pixels per axis here), sRGB-encoded and rounded: area (box) resampling, the standard
+reduction filter. Lens diffraction, the anti-aliasing filter and the pixel aperture act at the real 6 µm 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, tone curve and framing are the capture's (the same code
+resolves them).
+
+**How it is computed** (details and error analysis in [DISPLAY_VIEW.md](https://github.com/Photivra/photivra/blob/main/docs/DISPLAY_VIEW.md)):
+
+- The expected value of each display pixel is a stratified Monte Carlo average over K × K real pixels of its rectangle
+  (`view.samplesPerAxis`, default 16), seeded and unbiased. For each sampled pixel the expected electrons of the real
+  sites its demosaic reads are exact, and the clips and tone curve act on the pixel's own noise distribution. A pilot
+  grid gives uniform areas K/4 samples per axis; their error is zero anyway.
+- The noise is one correlated normal draw per display pixel with the covariance of the area mean of the real pixels'
+  independent site noises (shot, dark, read, ADC), including the demosaic's correlation.
+- AHD is represented by its two linear candidates; where the noise is large enough for its homogeneity choice to shift
+  the colour, a control-variate correction runs the engine's AHD steps on drawn noisy neighbourhoods.
+
+Validated against real full-resolution captures resized in linear light: three sensors (12 MP phone, 24 MP full frame,
+100 MP medium format), five charts, f/2.8–f/16, ISO 100–6400, 96–800 display pixels wide, Speed and Quality options (see
+[Validation results](https://github.com/Photivra/photivra/blob/main/docs/DISPLAY_VIEW.md#validation-results)).
+
+**Cost.** It follows the detailed display pixels × `samplesPerAxis`², not the real pixel count. Measured against the
+whole-frame view of the same request (Siemens star, f/8, ISO 100, one run, Node 24.21.0 on a 4-vCPU 2.80 GHz Xeon;
+every row, and the times before the exact speed-ups, in [DISPLAY_VIEW.md](https://github.com/Photivra/photivra/blob/main/docs/DISPLAY_VIEW.md#cost)):
+
+| Sensor | Options | 96 wide | 384 wide | 800 wide |
+| --- | --- | --- | --- | --- |
+| 24 MP full frame, 6 µm | Speed (defaults) | 2.4 s (2.3×) | 10.6 s (0.92×) | 26.6 s (0.65×) |
+| 12 MP phone, 1.4 µm | Speed | 2.2 s (2.4×) | 11.7 s (0.92×) | 32.1 s (0.59×) |
+| 100 MP medium format, 3.76 µm | Speed | 2.7 s (2.3×) | 15.8 s (1.2×) | 32.6 s (0.66×) |
+| 24 MP full frame | Quality (diffraction, four-spot filter, AHD) | 5.2 s (1.6×) | 30.9 s (1.3×) | 84.3 s (0.76×) |
+| 12 MP phone | Quality | 49.7 s (20×) | 106 s (3.8×) | 272 s (2.2×) |
+| 100 MP medium format | Quality | 18.2 s (3.7×) | 49.7 s (1.8×) | 126 s (1.0×) |
+
+Quality costs more on small pixels. The diffraction kernel spans several real sites, and at 1.4 µm even ISO 100 is
+noisy enough for the AHD correction to run on every sampled pixel; its correction states are kept for later views of
+the same sensor, exposure and development in the same JavaScript realm (a second 384-wide phone view of the same
+request took 73 s instead of 103 s). The results are byte-identical to those of the display view as first merged,
+which took 222 s, 450 s and 837 s on the phone.
+
+**Options.** `view.width` and `view.height` (1 to the capture's output size), `view.samplesPerAxis` (1–32),
+`view.format` (`"srgb-8"` default or `"srgb-16"`) and `view.region` (a rectangle in display pixels, byte-identical to
+the same pixels of the whole view, for tiling across workers). The capture's file-format options (`format`,
+`colorEncoding`, `bitDepth`, `gamutMapping`, `jpegQuantizationStep`, `dng`, `metadata`) do not apply. The request must
+be one `simulateCapture` accepts (a frame wider or taller than 4094 pixels needs `output.maximumPixels`, although the
+view allocates nothing at full resolution).
+
+**Many regions of one view (2.7).** Each `simulateDisplayView` call repeats the request's setup: the camera, lens,
+scene and illuminant, the channel responses, the diffraction kernels and the colour tables. That is about 0.25 s with
+the engine defaults and 0.7 s with the Quality options on a 24 MP request. To render one view in many regions, prepare
+the request once and render each region from it; each region then costs only its own pixels:
+
+```ts
+import { prepareDisplayView, type SimulateCaptureOptions } from "@photivra/engine";
+
+const request: SimulateCaptureOptions = { scene: { preset: "siemens-star" }, output: { width: 600, height: 400 } };
+const prepared = await prepareDisplayView(request);   // request errors are raised here
+const tile = await prepared.render({ width: 300, height: 200, region: { x: 120, y: 80, width: 32, height: 32 } },
+  { signal: AbortSignal.timeout(60_000) });            // cancels this render only
+console.log(tile.image.width, tile.diagnostics.timingsMs.view);
+```
+
+`render(view)` returns what `simulateDisplayView(request, view)` returns, byte for byte (only `diagnostics.timingsMs`
+differ, and they cover the render only). Renders may run concurrently and share only read-only setup. The request's own
+`signal` applies to preparing; give each render its own. Keep one prepared view per request in each worker: measured on
+a 24 MP request, an 8 × 8 region took 6–40 ms through a prepared view instead of 0.24–0.41 s as its own call (Speed).
+
+**Not supported** (refused with an `InvalidConfigurationError`): `lens.pupilSampling`, `lens.projection`,
+`lens.distortion`, `lens.vignetting`, `lens.psf`, camera rotation, `output.whiteBalance: "auto"`, the luminance tone
+curves, `output.highlightMode: "reconstruct"` and `output.region` (use `view.region`). `onProgress` is not called;
+`signal` cancels.
+
+The result is labelled `kind: "display-view"` with a `label` for the user interface; it has no RAW, plan or file, and
+the `view.*` assumptions state the definition, the estimator, the noise model, the demosaic treatment and which capture
+options were ignored. The whole-frame views of [Whole-frame views](#whole-frame-views-25) are unchanged.
+
 ## Not available
 
 The facade offers no atmospheric haze or polarizer (see [Optics](#optics)), flash, video, HDR brackets
@@ -1125,6 +1297,33 @@ provided, for rights reasons.
 
 ## Sources
 
+- Diffraction (`lens.diffraction`, `createDiffractionLimitedPsfProfile`): M. Born, E. Wolf,
+  *Principles of Optics*, 7th (expanded) ed., Cambridge University Press, 1999,
+  doi:10.1017/CBO9781139644181, §8.5.2 "The circular aperture" (Fraunhofer diffraction at a circular
+  aperture: the Airy pattern and its dark rings); J. W. Goodman, *Introduction to Fourier Optics*,
+  4th ed., W. H. Freeman, 2017, §4.4 (examples of Fraunhofer diffraction patterns, including the
+  circular aperture) and §7.3 (frequency response for diffraction-limited incoherent imaging: the
+  optical transfer function as the normalized pupil autocorrelation); J. C. Wyant, K. Creath, "Basic
+  Wavefront Aberration Theory for Optical Metrology", *Applied Optics and Optical Engineering* XI,
+  ch. 1, Academic Press, 1992, §II "Aberration-Free Image", eqs. 1–4, free author copy at
+  <https://wp.optics.arizona.edu/jcwyant/wp-content/uploads/sites/13/2016/08/03-BasicAberrations_and_Optical_Testing.pdf>
+  (the Airy irradiance at the effective f-number, the 2.44·λ·N Airy disk diameter and the encircled
+  energy 1 − J₀² − J₁²); MIT OpenCourseWare 2.71 Optics (Spring 2009), lectures 21–22, free at
+  <https://ocw.mit.edu/courses/2-71-optics-spring-2009/resources/mit2_71s09_lec22/> (the intensity PSF as the transform of the
+  pupil autocorrelation and the circular-pupil MTF); F. W. J. Olver et al. (eds.), *NIST Digital
+  Library of Mathematical Functions*, release 1.2.8 (2026-09-15), free at <https://dlmf.nist.gov/>,
+  §10.6(i) (eqs. 10.6.2 and 10.6.3: J₀′ = −J₁ and J₁′ = J₀ − J₁/x, from which the encircled energy
+  follows), eq. 10.17.3 and §10.17(iii) (Hankel's large-argument expansion of J₀ and J₁ and its error
+  bound, used for cells much larger than the pattern) and eq. 10.9.2 (Bessel's integral, used as an
+  independent test). The original analysis is G. B. Airy, "On the Diffraction of an Object-glass with
+  Circular Aperture", *Transactions of the Cambridge Philosophical Society* 5, 1835, pp. 283–291. The
+  engine's implementation and its tests are its own (see [PSF foundation](https://github.com/Photivra/photivra/blob/main/docs/PSF_FOUNDATION.md#diffraction-limited-sampled-profile-21)).
+- Print planning (`calculatePrintPlan`, `calculatePrintSizeLimit`): Z. Alomar, K. D. Bojikian, "Visual Acuity
+  Testing in Adults", EyeWiki, American Academy of Ophthalmology, last edited June 16, 2026, free to read at
+  <https://eyewiki.aao.org/Visual_Acuity_Testing_in_Adults> (the minimum angle of resolution of an ideal eye under optimal
+  conditions is about 1 minute of arc; 20/20 letters are built from 1-arcmin elements). One arcminute per pixel is normal
+  (20/20) acuity under optimal conditions and an approximate rule of thumb: some viewers resolve finer detail and many
+  coarser. The planner uses the criterion the caller declares.
 - R. Palum, "Anti-Aliasing Filter Analysis for Digital Cameras", Proc. IS&T International Congress of
   Imaging Science (ICIS '06), 2006, free at
   <https://www.imaging.org/common/uploaded%20files/pdfs/Papers/2006/ICIS-0-736/33683.pdf>

package/docs/USAGE.md

@@ -7501,6 +7501,21 @@ The chart presets are also available on their own:
 - `createPlanarSceneRadianceProvider()` turns a chart into an `evaluateRadiance` callback for the native
   environment RAW contract.
 
+### Display view of a capture
+
+`simulateDisplayView(options, view)` takes a capture request and a display size and returns the real
+full-resolution capture resized to that size (area average in linear light), estimated at a cost that follows the
+display pixels. It is a preview (`kind: "display-view"`), never a capture; see [Display view](QUICK_START.md#display-view)
+and the design and validation in [DISPLAY_VIEW.md](https://github.com/Photivra/photivra/blob/main/docs/DISPLAY_VIEW.md).
+
+```ts
+import { simulateDisplayView } from "@photivra/engine";
+
+const view = await simulateDisplayView({ scene: { preset: "slanted-edge" }, sensor: { pixelPitchMicrometers: 3 }, output: { width: 600, height: 400 } },
+  { width: 60, height: 40 });
+console.log(view.kind, view.view.scaleX, view.assumptions.find((a) => a.id === "view.definition")?.value);
+```
+
 ### Facade 2.0 options: output, demosaic, optics and motion
 
 Each 2.0 option is opt-in and uses an existing public contract. Without them, the facade's output is

package/docs/api/core-version.md

@@ -11,5 +11,5 @@ version they were made with. Proof-of-concept (POC), schema and model contracts
 own versions. Release checks confirm it matches package.json and the packed package.
 
 ```ts
-ENGINE_API_VERSION = "2.5.0" as const
+ENGINE_API_VERSION = "2.7.0" as const
 ```

package/docs/api/exports.json

@@ -1,6 +1,6 @@
 {
-  "packageVersion": "2.5.0",
-  "engineApiVersion": "2.5.0",
+  "packageVersion": "2.7.0",
+  "engineApiVersion": "2.7.0",
   "exports": [
     {
       "name": "AbsoluteUncertaintyEstimate",
@@ -1417,6 +1417,16 @@
       "source": "src/sensor/radiometry-readiness.ts",
       "kind": "type"
     },
+    {
+      "name": "CALLER_MATERIAL_SCENE_MAX_MATERIALS",
+      "source": "src/facade/scene-radiance.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "CallerMaterialScene",
+      "source": "src/facade/scene-radiance.ts",
+      "kind": "type"
+    },
     {
       "name": "CallerRadianceScene",
       "source": "src/facade/scene-radiance.ts",
@@ -2582,6 +2592,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",
@@ -5367,6 +5382,16 @@
       "source": "src/color/color-matching-functions.ts",
       "kind": "type"
     },
+    {
+      "name": "PreparedDisplayView",
+      "source": "src/facade/simulate-display-view.ts",
+      "kind": "type"
+    },
+    {
+      "name": "PreparedDisplayViewRenderOptions",
+      "source": "src/facade/simulate-display-view.ts",
+      "kind": "type"
+    },
     {
       "name": "PreparedGeometricMapping",
       "source": "src/output/geometric-transforms.ts",
@@ -5377,6 +5402,11 @@
       "source": "src/composition/image-formation-plan.ts",
       "kind": "type"
     },
+    {
+      "name": "prepareDisplayView",
+      "source": "src/facade/simulate-display-view.ts",
+      "kind": "runtime"
+    },
     {
       "name": "PreparedRgbGamutMapping",
       "source": "src/color/gamut-mapping.ts",
@@ -6802,6 +6832,11 @@
       "source": "src/schema/illumination.ts",
       "kind": "type"
     },
+    {
+      "name": "SceneMaterialPoint",
+      "source": "src/facade/scene-radiance.ts",
+      "kind": "type"
+    },
     {
       "name": "SceneMaterialResponseDefinition",
       "source": "src/schema/scene-radiance.ts",
@@ -7907,6 +7942,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",
@@ -8002,6 +8042,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",