@photivra/engine 2.15.0 → 2.17.0

package/docs/api/exports.json

@@ -1,6 +1,6 @@
 {
-  "packageVersion": "2.15.0",
-  "engineApiVersion": "2.15.0",
+  "packageVersion": "2.17.0",
+  "engineApiVersion": "2.17.0",
   "exports": [
     {
       "name": "AbsoluteUncertaintyEstimate",
@@ -562,6 +562,16 @@
       "source": "src/color/illuminants.ts",
       "kind": "runtime"
     },
+    {
+      "name": "calculateDefocusBokehKernel",
+      "source": "src/optics/defocus-bokeh-kernel.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "CalculateDefocusBokehKernelInput",
+      "source": "src/optics/defocus-bokeh-kernel.ts",
+      "kind": "type"
+    },
     {
       "name": "calculateDefocusCircle",
       "source": "src/optics/depth-of-field.ts",
@@ -2432,6 +2442,16 @@
       "source": "src/equipment/generic-tier-presets.ts",
       "kind": "runtime"
     },
+    {
+      "name": "createGenericLensCorrectionProfile",
+      "source": "src/output/generic-lens-corrections.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "CreateGenericLensCorrectionProfileInput",
+      "source": "src/output/generic-lens-corrections.ts",
+      "kind": "type"
+    },
     {
       "name": "createHdrBracketMergeTask",
       "source": "src/processing/hdr.ts",
@@ -2702,11 +2722,46 @@
       "source": "src/sensor/capture-mode.ts",
       "kind": "type"
     },
+    {
+      "name": "DEFOCUS_BOKEH_MAXIMUM_BLADES",
+      "source": "src/optics/defocus-bokeh-kernel.ts",
+      "kind": "runtime"
+    },
     {
       "name": "DEFOCUS_DISC_KERNEL_MAXIMUM_RADIUS_SITES",
       "source": "src/optics/defocus-disc-kernel.ts",
       "kind": "runtime"
     },
+    {
+      "name": "DefocusBokehBlades",
+      "source": "src/optics/defocus-bokeh-kernel.ts",
+      "kind": "type"
+    },
+    {
+      "name": "DefocusBokehCatsEye",
+      "source": "src/optics/defocus-bokeh-kernel.ts",
+      "kind": "type"
+    },
+    {
+      "name": "DefocusBokehClippingAperture",
+      "source": "src/optics/defocus-bokeh-kernel.ts",
+      "kind": "type"
+    },
+    {
+      "name": "DefocusBokehKernel",
+      "source": "src/optics/defocus-bokeh-kernel.ts",
+      "kind": "type"
+    },
+    {
+      "name": "DefocusBokehOptions",
+      "source": "src/optics/defocus-bokeh-kernel.ts",
+      "kind": "type"
+    },
+    {
+      "name": "DefocusBokehSphericalAberration",
+      "source": "src/optics/defocus-bokeh-kernel.ts",
+      "kind": "type"
+    },
     {
       "name": "DefocusCircle",
       "source": "src/optics/depth-of-field.ts",
@@ -2802,6 +2857,11 @@
       "source": "src/facade/display-view-gpu.ts",
       "kind": "type"
     },
+    {
+      "name": "DisplayViewHighlightDiagnostics",
+      "source": "src/facade/simulate-capture.ts",
+      "kind": "type"
+    },
     {
       "name": "DisplayViewResult",
       "source": "src/facade/simulate-capture.ts",
@@ -3477,6 +3537,26 @@
       "source": "src/sensor/iso-signal-chain.ts",
       "kind": "runtime"
     },
+    {
+      "name": "GENERIC_LENS_CATALOGUE",
+      "source": "src/equipment/generic-lens-catalogue.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "GENERIC_LENS_CORRECTION_CHANNEL_WAVELENGTHS_NM",
+      "source": "src/output/generic-lens-corrections.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "GENERIC_LENS_IDS",
+      "source": "src/equipment/generic-lens-catalogue.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "GENERIC_LENS_SET_BASELINES",
+      "source": "src/equipment/generic-lens-catalogue.ts",
+      "kind": "runtime"
+    },
     {
       "name": "GENERIC_PRIME_EQUIVALENT_FOCAL_LENGTHS_MM",
       "source": "src/equipment/generic-prime-lenses.ts",
@@ -3582,6 +3662,26 @@
       "source": "src/sensor/iso-signal-chain.ts",
       "kind": "type"
     },
+    {
+      "name": "GenericLensAdjustments",
+      "source": "src/equipment/generic-lens-catalogue.ts",
+      "kind": "type"
+    },
+    {
+      "name": "GenericLensCatalogueEntry",
+      "source": "src/equipment/generic-lens-catalogue.ts",
+      "kind": "type"
+    },
+    {
+      "name": "GenericLensCharacter",
+      "source": "src/equipment/generic-lens-catalogue.ts",
+      "kind": "type"
+    },
+    {
+      "name": "GenericLensCharacterValues",
+      "source": "src/equipment/generic-lens-catalogue.ts",
+      "kind": "type"
+    },
     {
       "name": "GenericLensCorrectionProfile",
       "source": "src/output/lens-corrections.ts",
@@ -3592,6 +3692,21 @@
       "source": "src/equipment/exposure-capabilities.ts",
       "kind": "type"
     },
+    {
+      "name": "GenericLensFocusError",
+      "source": "src/equipment/generic-lens-catalogue.ts",
+      "kind": "type"
+    },
+    {
+      "name": "GenericLensKind",
+      "source": "src/equipment/generic-lens-catalogue.ts",
+      "kind": "type"
+    },
+    {
+      "name": "GenericLensSet",
+      "source": "src/equipment/generic-lens-catalogue.ts",
+      "kind": "type"
+    },
     {
       "name": "GenericOpticalEvidence",
       "source": "src/optics/profile-contract.ts",
@@ -4577,6 +4692,11 @@
       "source": "src/capture/native-environment-optical-stage.ts",
       "kind": "runtime"
     },
+    {
+      "name": "NATIVE_RAW_DEVELOPMENT_EXPOSURE_RANGE_STOPS",
+      "source": "src/capture/native-raw-development.ts",
+      "kind": "runtime"
+    },
     {
       "name": "NATIVE_RAW_DNG_SCHEMA_VERSION",
       "source": "src/capture/native-raw-dng.ts",
@@ -6612,6 +6732,11 @@
       "source": "src/sensor/iso-signal-chain.ts",
       "kind": "type"
     },
+    {
+      "name": "ResolvedGenericLens",
+      "source": "src/equipment/generic-lens-catalogue.ts",
+      "kind": "type"
+    },
     {
       "name": "ResolvedGenericTierLensProfiles",
       "source": "src/equipment/generic-tier-presets.ts",
@@ -6772,6 +6897,16 @@
       "source": "src/sensor/iso-signal-chain.ts",
       "kind": "runtime"
     },
+    {
+      "name": "resolveGenericLens",
+      "source": "src/equipment/generic-lens-catalogue.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "ResolveGenericLensInput",
+      "source": "src/equipment/generic-lens-catalogue.ts",
+      "kind": "type"
+    },
     {
       "name": "resolveGenericPrimeLens",
       "source": "src/equipment/generic-prime-lenses.ts",
@@ -8347,6 +8482,16 @@
       "source": "src/facade/simulate-capture.ts",
       "kind": "type"
     },
+    {
+      "name": "SimulateCaptureDetailDiagnostics",
+      "source": "src/facade/simulate-capture.ts",
+      "kind": "type"
+    },
+    {
+      "name": "SimulateCaptureDiffractionCorrection",
+      "source": "src/facade/simulate-capture.ts",
+      "kind": "type"
+    },
     {
       "name": "SimulateCaptureDngPart",
       "source": "src/facade/simulate-capture.ts",
@@ -8412,6 +8557,11 @@
       "source": "src/facade/simulate-capture.ts",
       "kind": "type"
     },
+    {
+      "name": "SimulateCaptureSharpening",
+      "source": "src/facade/simulate-capture.ts",
+      "kind": "type"
+    },
     {
       "name": "SimulateCaptureWhiteBalance",
       "source": "src/facade/simulate-capture.ts",
@@ -8452,6 +8602,16 @@
       "source": "src/capture/environment-raw-producer.ts",
       "kind": "type"
     },
+    {
+      "name": "simulateGenericLensFocusError",
+      "source": "src/equipment/generic-lens-catalogue.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "SimulateGenericLensFocusErrorInput",
+      "source": "src/equipment/generic-lens-catalogue.ts",
+      "kind": "type"
+    },
     {
       "name": "simulateIdealReference",
       "source": "src/facade/simulate-capture.ts",

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

@@ -2,6 +2,37 @@
 
 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.
 
+## DisplayViewHighlightDiagnostics
+
+#533: the display view's highlight count. `simulateCapture` reports `diagnostics.highlight.saturatedPixelCount`, the
+output pixels with at least one clipped contributing RAW site (a site flagged saturated or at the white level) counted on its
+one noise sample (`sensor.noiseSeed`). The display view renders no RAW, so it reports that count's expected value over the
+noise: Σ_j w_j·P_j over the real output pixels j of the rendered region, w_j the part of pixel j inside the region (1 inside,
+a fraction at a region edge that cuts a real pixel) and P_j the probability, under the view's own site model (each site's
+normalized value normal with its exact expected electrons, shot, dark, read and ADC noise, as the expected value uses), that at
+least one site pixel j's demosaic reads is at or above the white level, the sites' noises independent. It is estimated as the
+view's expected value is (`view.estimation`: exact over every real pixel, or the stratified samples), so it is not an integer.
+
+- Where every contributing site is far from white (more than 8.5 noise standard deviations either side) P_j is exactly 0 or 1,
+  and the expected count equals the capture's count of the same pixels exactly (they then have no noise to differ by).
+- Regions are additive: the counts of regions that tile the view sum to the whole view's count (up to floating-point summation
+  order), each display pixel's share being the same in every region that renders it.
+- With the bilinear demosaic the sites are the capture's own contributing sites. With AHD the capture counts every site within
+  3 sites of the pixel (its interpolation reach, clipped to the raster); the view counts the 25–29 of those 49 that its AHD
+  candidates read, so its count can be lower where a clipped area ends in a corner or a speck 2–3 sites away diagonally
+  (an approximation; along a straight clipped edge the two agree).
+- It never changes a sample of the view. On the GPU (`prepareDisplayView` with `gpu`) it is the CPU reference's value: the
+  kernel decides P_j only where it is certainly 0 or 1 and the host computes every other pixel's share with the reference.
+
+```ts
+export interface DisplayViewHighlightDiagnostics {
+  /** Expected number of saturated real output pixels in the rendered region (a non-negative real number; see above). */
+  saturatedPixelCount: number;
+  /** The statistic: always "expected-value" (the capture's own count is one noise sample of it). */
+  statistic: "expected-value";
+}
+```
+
 ## DisplayViewResult
 
 Result of {@link simulateDisplayView }: the full-resolution capture resized for display, estimated; not a capture.
@@ -43,7 +74,9 @@ export interface DisplayViewResult {
   diagnostics: { sampleCount: number; siteEvaluations: number; sceneLookups: number; detailPixelCount: number; uniformPixelCount: number; ahdCorrectedPixelCount: number;
     timingsMs: { view: number; total: number };
     /** #395: exact or fast, as requested and as run; 2.11 (#481): plus `execution`, where the render ran (see {@link DisplayViewFastReport}). */
-    fast: DisplayViewFastReport };
+    fast: DisplayViewFastReport;
+    /** #533: the saturated (clipped highlight) pixels of the real capture in the rendered region, as an expected value (see {@link DisplayViewHighlightDiagnostics}). */
+    highlight: DisplayViewHighlightDiagnostics };
   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`. */
@@ -109,9 +142,9 @@ a capture does. `motion.rotation` is a non-zero angular velocity; `sensor.tempor
 
 ```ts
 SIMULATE_CAPTURE_COST_OPTIONS = Object.freeze(["lens.pupilSampling", "lens.projection", "lens.distortion", "lens.vignetting", "lens.psf",
-  "lens.diffraction", "lens.defocus", "sensor.antiAliasing", "sensor.pixelAperture.box", "sensor.temporalSampleCount", "motion.rotation", "motion.shutter.rolling", "output.borderHandling.mirror", "output.region",
+  "lens.diffraction", "lens.defocus", "lens.catalogue", "sensor.antiAliasing", "sensor.pixelAperture.box", "sensor.temporalSampleCount", "motion.rotation", "motion.shutter.rolling", "output.borderHandling.mirror", "output.region",
   "output.whiteBalance.auto", "output.demosaic.ahd", "output.highlightMode.reconstruct", "output.colorEncoding.wide-gamut", "output.gamutMapping.perceptual",
-  "output.format.jpeg", "output.format.png", "output.format.dng"] as const)
+  "output.diffractionCorrection", "output.sharpening", "output.format.jpeg", "output.format.png", "output.format.dng"] as const)
 ```
 
 ## SIMULATE_CAPTURE_DEFAULT_ILLUMINANCE_LUX
@@ -334,6 +367,56 @@ export type SimulateCaptureDemosaic = "bilinear" | "ahd";
 export interface SimulateCaptureDemosaicRecord { kind: SimulateCaptureDemosaic; fast?: boolean }
 ```
 
+## SimulateCaptureDetailDiagnostics
+
+`diagnostics.detail` (#552): what the development detail stages did. Present only when one ran.
+
+```ts
+export interface SimulateCaptureDetailDiagnostics {
+  diffractionCorrection?: {
+    /** Corrected linear samples below 0 (ringing below black; clipped later by gamut handling) and above the RAW white level 1. */
+    negativeSampleCount: number;
+    aboveWhiteSampleCount: number;
+    /** The diffraction cut-off p/(λ·N_w) in cycles per pixel (Nyquist is 0.5); nothing beyond it is recovered. */
+    cutoffCyclesPerPixel: number;
+    /** Measured largest |response| of the filter, and largest |response| beyond the cut-off (null when the Nyquist square is inside it). */
+    responsePeakGain: number;
+    responseMaximumBeyondCutoff: number | null;
+  };
+  sharpening?: {
+    /** Half-width ⌈3σ⌉ of the Gaussian in pixels. */
+    kernelRadiusPixels: number;
+    /** Samples changed by the mask, and samples left alone because their detail was under the threshold. */
+    sharpenedSampleCount: number;
+    thresholdHeldSampleCount: number;
+    /** Sharpened samples clipped at 0 or 1. */
+    clippedLowSampleCount: number;
+    clippedHighSampleCount: number;
+    /** Largest increase and decrease amount·detail before clipping, in encoded units: the halo strength. */
+    maximumIncrease: number;
+    maximumDecrease: number;
+  };
+}
+```
+
+## SimulateCaptureDiffractionCorrection
+
+`output.diffractionCorrection` (#552): the Wiener–Tikhonov gain G(s) = min(maximumGain, H(s)(1 + α)/(H(s)² + α)) on the circular-pupil
+OTF H at s = f/f_c, f_c = 1/(λ·N_w), as a (2R + 1)² FIR per channel. Every field is optional.
+
+```ts
+export interface SimulateCaptureDiffractionCorrection {
+  /** Design wavelength in nm, 380–780, used for all three channels. Default 550. */
+  wavelengthNm?: number;
+  /** α, an assumed noise-to-signal power ratio, 1e-4–1. Larger is safer and restores less. Default 0.01. */
+  regularization?: number;
+  /** Upper bound on the gain at any frequency, 1–10 (it bounds the noise amplification). Default 4. */
+  maximumGain?: number;
+  /** FIR radius R in pixels, 1–16. Default: the Airy pattern's third dark ring at the design wavelength, within 1–16. */
+  kernelRadiusPixels?: number;
+}
+```
+
 ## SimulateCaptureDngPart
 
 One part of a whole-frame DNG (#391): a region render's packed RAW and where its native sites lie (`result.raw`, `result.region`).
@@ -431,6 +514,22 @@ export interface SimulateCaptureOptions {
      * focus distance below its minimum focus distance, is rejected. Not combinable with `focalLengthMm`.
      */
     prime?: number;
+    /**
+     * Opt-in (#549): a lens of the generic lens catalogue by id (`GENERIC_LENS_IDS`, for example "pv-50-1.2-pro" or "pv-50-1.8";
+     * docs/LENS_CATALOGUE.md). Like `prime`, its focal length is the full-frame equivalent ÷ the simulated frame's diagonal crop
+     * factor and it replaces the tier lens's focal length and f-number range (the transmission is kept). The capture renders the
+     * lens's character, all labelled approximations: its PSF (diffraction with the lens's Seidel aberrations, axial and lateral
+     * colour, at the resolved f-number and focus) through the environment PSF quadrature, its radial distortion, its vignetting
+     * and, for the fisheyes, the equisolid projection. Flare, focus breathing and bokeh shape are not rendered. Not combinable
+     * with `prime`, `focalLengthMm`, `projection`, `distortion`, `vignetting`, `psf`, `diffraction` or `pupilSampling` (the
+     * lens sets them); `defocus` convolves the disc into the lens's PSF. Not offered by the display view. Default off.
+     */
+    catalogue?: string;
+    /**
+     * Opt-in (#549), with `catalogue` only: a seeded autofocus error (`simulateGenericLensFocusError`). The focus distance becomes
+     * the sampled one for (seed, shotIndex), reported in the `lens.focusScatter` assumption; it is visible with `defocus`. Default off.
+     */
+    focusScatter?: { seed: number; shotIndex?: number };
     /** Aperture for manual and aperture-priority modes. Default 8. */
     fNumber?: number;
     /** Focus distance in metres. Default: the subject distance. */
@@ -464,8 +563,13 @@ export interface SimulateCaptureOptions {
      * kernel is convolved with the disc (a further approximation). In focus the result is that of the same request
      * without the option, plus the assumption.
      * Not combinable with `pupilSampling` or `psf`. Default off.
+     *
+     * Bokeh character (#553), each part off by default (without them the disc is unchanged, byte for byte): `blades` (a
+     * polygonal or rounded-blade opening), `sphericalAberration` (primary W040: soft-edged blur on one side of the focus
+     * plane, bright-rimmed on the other) and `catsEye` (mechanical vignetting clipping the pupil by field position; the
+     * capture only, not with `diffraction`). See `calculateDefocusBokehKernel` and docs/QUICK_START.md, "Bokeh character".
      */
-    defocus?: { model: "geometric-disc" };
+    defocus?: { model: "geometric-disc" } & DefocusBokehOptions;
   };
   exposure?: {
     /** Default "manual". */
@@ -544,6 +648,16 @@ export interface SimulateCaptureOptions {
     toneCurveParameters?: SdrToneCurveParameters;
     /** Default "clip". */
     highlightMode?: RawHighlightMode;
+    /**
+     * Opt-in (#556) development exposure push in stops, −2 to +5 (`NATIVE_RAW_DEVELOPMENT_EXPOSURE_RANGE_STOPS`); default 0.
+     * A linear gain 2^stops on the RAW after black subtraction and white normalization, before demosaic, white balance,
+     * the highlight mode, colour, the tone curve and encoding, like a raw editor's exposure slider ("brighten in development").
+     * A site pushed to or past white clips there and counts as saturated (`highlightMode: "reconstruct"` rolls it off);
+     * raised shadows keep their real noise and ADC quantization. The RAW codes, `result.raw` and a DNG are not changed;
+     * the developed samples (`image.samples`, also with format "dng"), JPEG, PNG, the ideal reference and the display view
+     * honour it. Reported in the assumption `output.exposureCompensationStops`. 0 or omitted: byte-identical to before.
+     */
+    exposureCompensationStops?: number;
     /** Default "scene-illuminant". */
     whiteBalance?: SimulateCaptureWhiteBalance;
     /** JPEG constant quantization step 1-255 (not a manufacturer 'quality'). Default 2. */
@@ -587,6 +701,20 @@ export interface SimulateCaptureOptions {
      * as a capture of the region's size.
      */
     region?: { x: number; y: number; width: number; height: number };
+    /**
+     * Opt-in (#552) diffraction correction: a bounded, regularized deconvolution of the developed linear colour with the
+     * diffraction OTF of the ideal circular pupil at the capture's working f-number (see {@link SimulateCaptureDiffractionCorrection}).
+     * It runs after demosaic, colour and white balance and before the tone curve. Frequencies beyond the diffraction cut-off
+     * 1/(λ·N_w) never reached the sensor and stay lost: the correction's design gain there is 0. Needs `lens.diffraction`.
+     * Not combinable with `region`. The DNG's RAW codes are not changed. Default off.
+     */
+    diffractionCorrection?: SimulateCaptureDiffractionCorrection;
+    /**
+     * Opt-in (#552) unsharp mask (see {@link SimulateCaptureSharpening}) on the sRGB-encoded values after the tone curve and gamut
+     * handling, before quantization. It raises edge contrast and creates halos; it adds no optical detail. sRGB output only
+     * (not the wide-gamut or perceptual PNG paths); not combinable with `region`. The DNG's RAW codes are not changed. Default off.
+     */
+    sharpening?: SimulateCaptureSharpening;
   };
   /** Camera motion and shutter type. Default: still camera, global electronic shutter. */
   motion?: SimulateCaptureMotion;
@@ -708,7 +836,7 @@ export interface SimulateCaptureResult {
      * scene provider gives the same expected signal (to float rounding) through the per-tap environment quadrature.
      */
     diffraction?: { profile: DiffractionLimitedPsfProfile; psf: Extract<CalculateEnvironmentSensorPhotoSignalInput["psf"], { kind: "sampled-local" }>;
-      execution: "object-space-convolution" | "environment-psf-quadrature" };
+      execution: "object-space-convolution" | "environment-psf-quadrature" | "image-space-convolution" };
   };
   exposure: {
     mode: SimulateCaptureExposureMode;
@@ -781,6 +909,8 @@ export interface SimulateCaptureResult {
     rendering: SdrRenderingResult["diagnostics"];
     /** Present with output.gamutMapping "perceptual": pixels whose chroma or lightness the mapping changed. */
     gamutMapping?: { method: "cielab-hue-preserving-chroma-compression"; kneeFraction: number; adjustedPixelCount: number; lightnessClippedPixelCount: number };
+    /** #552: present with output.diffractionCorrection or output.sharpening. */
+    detail?: SimulateCaptureDetailDiagnostics;
     /**
      * Wall-clock milliseconds per stage. `raw`, `whiteBalance` (the second RAW pass of auto white balance), `development`
      * (includes DNG writing), `jpeg` and `total` are whole milliseconds (`Date.now()`). Since 2.1, where a stage ran:
@@ -831,6 +961,22 @@ export type SimulateCaptureSensorAntiAliasing =
   | { kind: "point-splitting"; components: readonly AntiAliasingPointSplitComponent[]; fast?: boolean };
 ```
 
+## SimulateCaptureSharpening
+
+`output.sharpening` (#552): unsharp mask y = x + amount·(x − G_σ∗x) where |x − G_σ∗x| ≥ threshold (GIMP and ImageMagick
+unsharp mask), per channel on sRGB-encoded values in [0, 1], then clipped to [0, 1]. Every field is optional.
+
+```ts
+export interface SimulateCaptureSharpening {
+  /** Gaussian standard deviation σ in output pixels, (0, 8]; the kernel reaches ⌈3σ⌉. Default 1. */
+  radiusPixels?: number;
+  /** Gain on the detail signal, (0, 5]. Default 0.5. */
+  amount?: number;
+  /** Detail smaller than this (encoded units, [0, 1]) is left unchanged. Default 0 (every difference is sharpened). */
+  threshold?: number;
+}
+```
+
 ## SimulateCaptureWhiteBalance
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.

package/docs/api/optics-defocus-bokeh-kernel.md

@@ -0,0 +1,145 @@
+# optics/defocus-bokeh-kernel.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.
+
+## calculateDefocusBokehKernel
+
+The defocus kernel of `lens.defocus` with bokeh options (#553), on the site lattice, for one field point: the same kernel
+`simulateCapture` and the display view apply (on the field zone's centre with a cat's eye). Pure; for tests, previews and
+lens catalogues. Fails with `InvalidScientificInputError` past {@link DEFOCUS_DISC_KERNEL_MAXIMUM_RADIUS_SITES} (spherical
+aberration can widen the blur beyond the disc) or when the cat's eye closes the pupil, `InvalidConfigurationError` for
+unknown fields. A geometric approximation: see the module comment of `defocus-bokeh-kernel.ts` and docs/QUICK_START.md,
+"Bokeh character".
+
+```ts
+export function calculateDefocusBokehKernel(input: CalculateDefocusBokehKernelInput): CalculationResult<DefocusBokehKernel>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateDefocusBokehKernelInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateDefocusBokehKernelInput {
+  /** Lens focal length, mm. */
+  focalLengthMm: number;
+  /** Working f-number. */
+  aperture: number;
+  /** Focus-plane distance, m. */
+  focusDistanceM: number;
+  /** Scene-plane distance, m. */
+  subjectDistanceM: number;
+  /** Sensor site pitch, µm: the lattice the kernel is sampled on. */
+  pixelPitchMicrometers: number;
+  /** The bokeh options, as `lens.defocus` takes them (blades, sphericalAberration, catsEye). */
+  bokeh: DefocusBokehOptions;
+  /** Field tangent tan θ·(cos φ, sin φ) in output-image axes (+X right, +Y up); only the cat's eye reads it. Default on axis. */
+  fieldTangent?: { x: number; y: number };
+}
+```
+
+## DEFOCUS_BOKEH_MAXIMUM_BLADES
+
+Largest blade count of `lens.defocus.blades` (and of {@link DefocusBokehBlades}).
+
+```ts
+DEFOCUS_BOKEH_MAXIMUM_BLADES = 32
+```
+
+## DefocusBokehBlades
+
+Aperture blades: a regular polygon, optionally with rounded blades and open at wide f-numbers.
+
+```ts
+export interface DefocusBokehBlades {
+  /** Number of diaphragm blades, 3 to {@link DEFOCUS_BOKEH_MAXIMUM_BLADES}. */
+  count: number;
+  /** Rotation of the first blade edge, degrees counter-clockwise (`calculateIdealApertureGeometry`'s convention). Default 0. */
+  firstBladeEdgeAngleDegrees?: number;
+  /** Blade roundness κ in [0, 1]: each edge is an arc of radius 1/κ circumradii (0: straight blades, 1: a circle). Default 0. */
+  curvature?: number;
+  /** At or below this f-number the blades are open and the opening is circular (the lens's widest aperture). Default: never. */
+  circularAtOrBelowFNumber?: number;
+}
+```
+
+## DefocusBokehCatsEye
+
+Mechanical vignetting (cat's eye): the open pupil clipped by each aperture at the field point.
+
+```ts
+export interface DefocusBokehCatsEye {
+  /** One through eight clipping apertures. */
+  apertures: readonly DefocusBokehClippingAperture[];
+  /**
+   * `lens.defocus` only: zones across the frame's long side (1 to {@link DEFOCUS_BOKEH_MAXIMUM_FIELD_ZONES}, default
+   * {@link DEFOCUS_BOKEH_DEFAULT_FIELD_ZONES}); square zones, each with the kernel of its centre's field point.
+   */
+  fieldZonesAcrossLongSide?: number;
+}
+```
+
+## DefocusBokehClippingAperture
+
+One clipping aperture of the cat's eye, as `MechanicalVignettingAperture` of `calculateMechanicalVignetting`.
+
+```ts
+export interface DefocusBokehClippingAperture {
+  /** Aperture radius referred to the entrance-pupil plane, mm. */
+  radiusMm: number;
+  /** Shift of its projected centre per unit tan(field angle), mm, toward the field point when positive. */
+  shiftPerTanFieldMm: number;
+}
+```
+
+## DefocusBokehKernel
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface DefocusBokehKernel {
+  /** "behind-focus" (subject farther than focus), "in-front-of-focus", or "in-focus" (no kernel). */
+  side: "behind-focus" | "in-front-of-focus" | "in-focus";
+  /** Thin-lens blur diameter c, µm and sites (`calculateDefocusCircle`, thin-lens model 1.1.0). */
+  diameterMicrometers: number;
+  diameterSites: number;
+  /** Kernel radius R and window side 2R + 1 (0 and 1 in focus). */
+  kernelRadiusSites: number;
+  width: number;
+  /** Row-major weights, index (j + R)·width + (i + R) for site offset (i right, j down) from the chief ray; null in focus. */
+  weights: Float64Array | null;
+  /** Open pupil area / unclipped opening area at the field point (the cat's eye's open fraction; 1 without one). */
+  openAreaRatio: number;
+  method: "exact-polygon-cell-area" | "pupil-ray-binning" | "none";
+  /** Transverse spherical aberration of the marginal ray at the working f-number, sites (8·N·W040(N)/pitch). */
+  sphericalAberrationSites: number;
+  raySamples: number;
+}
+```
+
+## DefocusBokehOptions
+
+The bokeh options of `lens.defocus` (#553), each off when omitted; a lens catalogue entry can carry them as they are.
+
+```ts
+export interface DefocusBokehOptions {
+  blades?: DefocusBokehBlades;
+  sphericalAberration?: DefocusBokehSphericalAberration;
+  catsEye?: DefocusBokehCatsEye;
+}
+```
+
+## DefocusBokehSphericalAberration
+
+Primary (Seidel) spherical aberration W = W040·ρ⁴, given at a reference f-number.
+
+```ts
+export interface DefocusBokehSphericalAberration {
+  /** W040 in µm of optical path at the pupil edge of `atFNumber`; positive = undercorrected (marginal rays focus short). */
+  w040Micrometers: number;
+  /** The f-number at which `w040Micrometers` is given; the working value is W040·(atFNumber/N)⁴. */
+  atFNumber: number;
+}
+```