@photivra/engine 0.1.0

package/docs/API_STYLE.md

@@ -0,0 +1,65 @@
+# Public API Style
+
+The open engine should feel like one coherent library.
+
+## Rules
+
+- Use descriptive `camelCase` function names, normally beginning with a verb such as `calculate`, `estimate`, `parse`, `validate`, or `simulate`.
+- For calculations with more than one meaningful input, accept a single typed/config object rather than positional arguments.
+- Include units in property names when a quantity is not represented by a dedicated unit type: `focalLengthMm`, `distanceM`, `shutterSeconds`.
+- Never accept unitless ambiguous physical quantities.
+- Use the same property name for the same physical concept across modules.
+- Return plain serializable data from core calculations.
+- Public calculation envelopes must not contain `NaN` or numeric infinities; non-finite computed results fail with `InvalidScientificResultError` rather than relying on JSON coercion.
+- Keep deterministic functions synchronous. Use async only for actual asynchronous work.
+- Throw typed/domain errors for invalid configurations; do not silently coerce scientifically invalid values.
+- Public calculation functions and meaningful public contracts require concise JSDoc covering purpose, units, assumptions, and return meaning.
+- Do not expose renderer, framework, or UI-specific types through calculation APIs.
+- Public configuration interfaces that are expected to cross JSON/untrusted boundaries should have corresponding runtime parsers; TypeScript types alone are not a validation boundary.
+- Preserve backward compatibility after 1.0 unless a documented major version changes the contract.
+
+## Preferred shape
+
+```ts
+calculateFieldOfView({
+  focalLengthMm,
+  sensorDimensionMm,
+  focusDistanceM
+});
+
+calculateDepthOfField({
+  focalLengthMm,
+  aperture,
+  focusDistanceM,
+  circleOfConfusionMm
+});
+```
+
+Avoid one-off positional signatures and inconsistent abbreviations.
+
+## Result metadata
+
+Primitive public scientific calculation functions return `CalculationResult<T>`, which carries model provenance and optional quality metadata.
+
+Not every public API returns a `CalculationResult<T>`. Parsers return validated configuration values, and the composed `simulatePocCamera()` response exposes component and aggregate provenance directly because it combines many calculation results.
+
+Optional `quality` metadata is used only when there is defensible accuracy/uncertainty information to report; deterministic analytical results should omit it rather than inventing error bars.
+
+Quality metadata supports:
+
+- absolute uncertainty with an explicit unit;
+- relative uncertainty as a fractional magnitude;
+- uncertainty source classification: measurement, model approximation, or calibration;
+- optional confidence/coverage level only when its basis can be stated;
+- documented model/calibration valid ranges;
+- concise quality notes.
+
+Uncertainty entries identify the affected result with a JSON-style `quantityPath` such as `value.distanceM`. Valid ranges identify the relevant parameter with a path such as `input.focusDistanceM`.
+
+Do **not** automatically sum, average, add in quadrature, or otherwise collapse multiple uncertainty components. Combination is permitted only when the implementing model documents the mathematical method plus independence/correlation assumptions. Aggregate simulations should preserve component uncertainty or explicitly state that no combined uncertainty has been calculated.
+
+## Versioning
+
+`ENGINE_API_VERSION` describes the composed engine API contract and is independent of the npm/package version.
+
+Before 1.0, public APIs may evolve with documented changes. After 1.0, breaking public-contract changes require an appropriate major-version transition.

package/docs/ARCHITECTURE.md

@@ -0,0 +1,51 @@
+# Architecture
+
+Photivra separates a reusable scientific core from optional composition and transport layers.
+
+## Current root package
+
+The browser-safe root package currently owns:
+
+- unit-explicit camera, sensor, lens, exposure, focus, scene, and motion contracts;
+- deterministic camera/optics/exposure/crop calculations;
+- the explicitly approximate stabilization-equivalent camera-shake model;
+- sensor signal/noise primitives;
+- schema/runtime validation;
+- provenance and optional uncertainty/quality contracts;
+- the composed `simulatePocCamera()` proof-of-concept calculation.
+
+The root package has no runtime npm dependencies. CI walks the root import graph and fails if Node-only modules or the `src/api` transport layer become reachable from it.
+
+Comparison, optimization, real-camera calibration databases, renderer effects, and full optical simulation are **not** current root-package capabilities.
+
+## Repository-local Node POC transport
+
+The repository contains a minimal Node-only HTTP transport under `src/api` for contributor integration testing.
+
+It wraps `simulatePocCamera()` with an unauthenticated localhost server. The HTTP layer adds structural request validation and transport behavior; it does not define new camera-science equations.
+
+This transport is intentionally **not** part of the public `@photivra/engine` package surface and is excluded from the npm tarball. The POC server is not the intended production architecture.
+
+## Optional/future capability modules
+
+Future capabilities should compose onto the scientific core rather than silently widening unrelated models. Examples include:
+
+- more complete camera-rotation and translation models;
+- panning and rolling/global shutter;
+- flash;
+- spectral/color modeling;
+- macro/high-magnification calibration;
+- non-circular diffraction PSFs;
+- computational capture;
+- lens calibration profiles;
+- advanced/calibrated sensor profiles;
+- comparison and optimization systems;
+- renderer-specific effects.
+
+Capabilities should remain discoverable and explicitly versioned rather than being assumed present for every scene or runtime.
+
+## Repository scope
+
+This repository contains the Apache-2.0 scientific/business-logic package together with its tests, documentation, schemas, validation, and contributor tooling.
+
+The published npm package intentionally exposes only the browser-safe scientific root surface; repository-local development tooling such as the Node POC transport remains outside the published package.

package/docs/MOTION_AND_SIGNAL.md

@@ -0,0 +1,53 @@
+# Motion and Signal Foundation
+
+## Projected subject motion
+
+Subject-motion blur is modeled from image-plane displacement rather than broad labels such as "fast sport" or "slow subject."
+
+`calculateProjectedMotionBlur()` projects one representative scene point at shutter open and shutter close after applying constant world-space linear velocity. The difference is the sensor-plane displacement.
+
+Projection has two explicit modes:
+
+- when `focusDistanceM` is omitted, nominal focal length is used as the backwards-compatible infinity-focus/pinhole projection distance;
+- when `focusDistanceM` is supplied, the ideal Gaussian thin-lens image distance for that focus plane is used.
+
+Projected displacement therefore depends on:
+
+- focal length;
+- optional focus-plane extension;
+- shutter duration;
+- starting object position/distance;
+- motion direction;
+- object velocity;
+- optional sensor pixel pitch for pixel-domain reporting.
+
+The model can represent a representative point moving laterally and/or along the optical axis. It does **not** yet model an extended object's changing apparent scale across the exposure, rotational subject motion, acceleration, deformation, or occlusion changes. A large object moving significantly in depth can therefore exhibit real scale blur that this point-displacement primitive does not describe.
+
+Camera motion is not folded into subject motion. Camera shake is modeled separately by `estimateCameraShakeBlur()`; panning detection/intent is not currently modeled.
+
+## Exposure relations
+
+`calculateExposureValue100()` implements EV100 from aperture and shutter duration.
+
+`calculateRelativeOpticalExposure()` compares the proportional image-plane exposure relation `t / N²`.
+
+These calculations do not imply a photon count because they do not include scene radiance, lens transmission/T-stop, vignetting, spectral response, or sensor calibration.
+
+`calculateEquivalentIso()` treats ISO as nominal gain/brightness compensation needed to preserve rendered exposure after an aperture/shutter change. It is not used as a shortcut for noise or photon creation.
+
+## Signal/noise primitives
+
+The root package also exports low-level deterministic sensor primitives:
+
+- `calculatePhotoelectrons()`: caller-supplied mean incident photons × caller-supplied quantum efficiency;
+- `calculateSignalToNoise()`: Poisson shot-noise standard deviation plus independent caller-supplied RMS read noise, reported as linear and dB SNR.
+
+These functions do **not** derive incident photon counts from scene imagery.
+
+They do not currently model dark current, fixed-pattern noise, PRNU/DSNU, ADC quantization, clipping/full-well behavior, CFA/demosaic, downstream denoising, or a particular commercial sensor.
+
+The composed POC intentionally does not expose photon/noise output until there is a defensible calibrated radiometric path including the necessary scene, spectral, optical-transmission, pixel-area, quantum-efficiency, and calibration assumptions.
+
+## Provenance
+
+The equations in this slice are independently implemented from established projective geometry, exposure relations, and elementary photon/statistical noise models. No third-party source code or calibration dataset is incorporated by these modules.

package/docs/PHYSICS_FOUNDATION.md

@@ -0,0 +1,92 @@
+# Physics Foundation
+
+Photivra starts with analytical models that can be independently tested and whose assumptions can be stated explicitly.
+
+## Implemented models
+
+### Rectilinear field of view
+
+The rectilinear relation is:
+
+`FOV = 2 atan(d / (2v))`
+
+where `d` is the relevant sensor dimension and `v` is the projection/image-plane distance.
+
+When no focus distance is supplied, `v = f` is the infinity-focus/pinhole compatibility approximation. When focus distance is supplied, `v` is the ideal Gaussian thin-lens image distance.
+
+### Pixel pitch and crop
+
+Pixel pitch is derived directly from active sensor width and horizontal active pixel count.
+
+Centered crop dimensions are derived from a linear crop factor while preserving the source aspect ratio, subject to integer pixel flooring.
+
+Subject-height framing crop computes the additional same-aspect crop needed to target a requested subject-height fraction. It assumes the crop can be positioned around the subject and does not check subject position against image edges.
+
+### Projection, focus extension, object size, and motion
+
+Field of view, projected fronto-parallel object size, projected representative-point subject motion, and camera-shake projection support two explicit projection modes:
+
+- **pinhole/infinity-focus compatibility mode** when no focus distance is supplied: nominal focal length is used as the projection distance;
+- **focus-aware thin-lens mode** when a focus distance is supplied: sensor-plane projection distance is calculated from the Gaussian thin-lens relation `1/f = 1/s + 1/v`.
+
+There is no hidden distance threshold or discontinuous transition between the modes. The caller chooses the model by supplying or omitting focus distance.
+
+At a focus distance of at least 100 focal lengths, the ideal thin-lens projection-distance scale differs from the infinity-focus approximation by no more than about 1.011%. For example, 200 mm focused at 22 m (110 focal lengths) changes projected scale by about 0.92%.
+
+The focus-aware model improves internal consistency with thin-lens DOF/defocus calculations, but it is still an ideal paraxial model. It does not model real-lens focus breathing, pupil magnification, principal-plane movement, distortion, aberrations, or lens-specific macro behavior.
+
+Projected subject motion is a representative-point displacement model with constant linear world velocity. It does not yet describe scale blur of an extended object whose magnification changes materially during the exposure.
+
+### Thin-lens focus and depth of field
+
+The geometric depth-of-field model uses the conventional hyperfocal/near/far equations with a caller-supplied acceptable circle of confusion.
+
+The circle-of-confusion criterion is a viewing/acceptability input, not a physical sensor threshold. The optional equivalent-viewing helper scales a caller-supplied reference criterion by sensor-diagonal ratio and is explicitly labeled an approximation.
+
+The model is not a macro calibration model and does not include diffraction, pupil magnification, aberrations, focus breathing, or lens-specific principal-plane behavior in its DOF criterion.
+
+### Defocus circle
+
+Defocus is calculated geometrically by comparing the selected sensor plane for the focus distance with the ideal image plane for the subject distance and projecting an ideal circular entrance-pupil cone to the sensor.
+
+### Diffraction
+
+For an ideal circular aperture, first-zero Airy diameter is:
+
+`d = 2.44 λ N`
+
+where `λ` is wavelength and `N` is f-number.
+
+This is a monochromatic, ideal-circular-pupil diagnostic.
+
+It is deliberately separate from regular-polygon aperture geometry used for bokeh/sunstar exploration. Supplying a polygon blade count does not convert the circular Airy result into a polygon-aperture diffraction PSF; a physically consistent non-circular diffraction model remains future work.
+
+### Ideal diaphragm geometry and sunstar symmetry
+
+For a regular straight-edged diaphragm, the engine calculates normalized polygon vertices and idealized sunstar direction symmetry perpendicular to blade edges.
+
+For even blade counts, opposite parallel edges produce overlapping opposite directions, yielding the same number of unique directions as blades.
+
+For odd blade counts, there are no parallel opposite-edge pairs, yielding twice as many directions as blades.
+
+This is a geometry/orientation model only. It does not calculate diffraction intensity, wavelength-dependent star length, blade curvature, coatings, internal reflections, lens aberrations, sensor blooming, or a complete point-spread function.
+
+### Controlled camera shake
+
+Yaw and pitch angular velocity are integrated over shutter duration. Their angular displacement is projected to the image plane using the selected projection distance.
+
+The current model returns one global image-plane vector. It does not compute the spatially varying optical flow that a real camera rotation produces away from the optical axis.
+
+Equivalent stabilization stops attenuate angular displacement by `2^-stops`; that attenuation is explicitly an educational approximation rather than a real IBIS/OIS or CIPA performance model.
+
+## Source provenance
+
+These implementations were written independently from established mathematical/physical relations. No third-party source code, calibration dataset, table, or model weight is incorporated by these scientific modules.
+
+Public technical references may be used to understand or validate concepts, but their code, protected prose, tables, figures, or restricted measurement data are not copied unless separately licensed for that use. See [Scientific and Source Provenance](PROVENANCE.md).
+
+## Scope
+
+These models produce numerical indicators, not a universal "sharpness score." Sampling, defocus, diffraction, subject motion, and camera shake describe different physical effects and should not be directly added together without a justified image-formation model.
+
+Rendering and analysis clients should consume validated numerical outputs rather than silently introducing conflicting camera science.

package/docs/POC_API.md

@@ -0,0 +1,210 @@
+# Local POC Simulation API
+
+Photivra includes a minimal Node HTTP transport for proof-of-concept development and integration testing.
+
+It is **not** the recommended production runtime. Browser applications can consume the root `@photivra/engine` scientific surface directly; the production Photivra architecture is intended to keep the simulation math client-side rather than expose this unauthenticated POC server to the public internet.
+
+## Repository and package boundary
+
+`@photivra/engine` publishes only the runtime-neutral scientific/calculation surface.
+
+The Node HTTP transport remains in this GitHub repository under `src/api` as contributor/development tooling. It is **not** exported by the package and `dist/api` is explicitly excluded from the npm tarball.
+
+The HTTP layer adds request parsing, CORS response headers, routing, and serialization. It does not add camera-science equations.
+
+## Build and run from a repository checkout
+
+```sh
+npm ci
+npm run build
+node dist/api/poc-api-cli.js
+```
+
+This command is a repository-development workflow. Installing `@photivra/engine` from npm does not install or expose the POC HTTP server.
+
+Defaults:
+
+- bind host: `localhost` (loopback only);
+- API URL: `http://localhost:8787`;
+- CORS allowed origin value: `http://localhost:5173`.
+
+Overrides:
+
+- `PHOTIVRA_API_HOST`;
+- `PHOTIVRA_API_PORT`;
+- `PHOTIVRA_ALLOWED_ORIGIN`.
+
+The server is unauthenticated and therefore binds only to loopback by default. Setting `PHOTIVRA_API_HOST` to a non-loopback address exposes it beyond the local machine and is outside the security model supplied by this repository.
+
+CORS is a browser policy, **not** authentication or authorization. Non-browser clients can call an exposed endpoint regardless of its CORS header.
+
+The server accepts request bodies up to 64 KiB. It does not provide production rate limiting, authentication, quotas, reverse-proxy hardening, or abuse controls.
+
+## Health
+
+`GET /health`
+
+Example:
+
+```json
+{
+  "ok": true,
+  "service": "photivra-engine",
+  "apiVersion": "0.17.0"
+}
+```
+
+## Simulate
+
+`POST /v1/poc/simulate`
+
+Requests must use `Content-Type: application/json`.
+
+All physical quantities use explicit units in their property names.
+
+API 0.17 composes projection using the selected focus plane. The response includes a `projection` block with ideal thin-lens image distance, scale relative to the infinity-focus approximation, and model provenance. Full-sensor field of view, crop field of view, object sampling, subject motion, and camera-shake projection use that same selected projection plane.
+
+### Required request groups
+
+The request includes:
+
+- sensor dimensions and resolution;
+- focal length and aperture;
+- shutter duration and ISO;
+- focus distance;
+- exactly one circle-of-confusion criterion:
+  - explicit target `circleOfConfusionMm`, or
+  - an equivalent-viewing reference sensor/CoC convention;
+- crop factor;
+- diffraction wavelength;
+- one representative object position and velocity.
+
+### Optional request groups
+
+The request may also include:
+
+- physical subject dimensions/distance for pixels-on-subject calculation;
+- named scene-plane distances for defocus sampling;
+- named physical objects for projected pixel sampling;
+- named object motion samples with explicit position/velocity vectors;
+- target subject-height fraction for framing crop;
+- controlled yaw/pitch camera-shake profile plus equivalent stabilization-stop attenuation;
+- ideal regular-polygon aperture blade count/orientation;
+- primary-subject diagnostics selecting a named motion sample.
+
+Named sample IDs must be non-empty and unique within their respective arrays.
+
+## Response semantics
+
+### Projection and field of view
+
+The top-level `fieldOfView` always describes the full sensor before digital cropping.
+
+`projection` reports:
+
+- selected focus distance;
+- ideal Gaussian thin-lens image distance;
+- scale relative to the infinity-focus `f` projection;
+- calculated model provenance.
+
+This remains ideal paraxial geometry, not a real-lens focus-breathing calibration.
+
+### Crop
+
+`crop` reports the requested fixed crop factor, retained pixel dimensions/area, megapixels, and its effective field of view.
+
+If `subjectCrop` is requested, subject framing is composed **after** the fixed crop. The response distinguishes:
+
+- `additionalCropFactor`: framing crop relative to the fixed crop;
+- `totalCropFactor`: total linear crop relative to the full sensor.
+
+`subjectHeightFraction` is not clamped to 1. A value above 1 with `subjectClipped: true` means the projected subject is taller than the output frame.
+
+The framing calculation assumes the crop can be positioned around the subject; it does not validate subject position against source-image edges.
+
+### Subject/object sampling
+
+When physical subject/object dimensions are supplied, projected dimensions are returned in sensor millimetres and pixels using the focus-aware projection plane.
+
+These values can drive pre-authored asset/detail selection without moving projection math into a renderer.
+
+### Defocus
+
+Named defocus samples return ideal geometric blur-circle diameters in sensor millimetres and pixels.
+
+### Subject motion
+
+Primary and named motion samples return representative-point sensor-plane displacement in millimetres and pixels, including signed x/y components.
+
+The model assumes constant world-space linear velocity. It can represent depth-direction motion of the representative point but does not model extended-object scale blur, rotation, acceleration, deformation, or occlusion changes.
+
+### Camera shake
+
+When supplied, camera shake returns unstabilized and stabilized global image-plane vectors.
+
+Yaw/pitch projection uses the selected focus-aware projection distance. Equivalent stabilization stops attenuate angular displacement by `2^-stops` and are explicitly labeled an approximation.
+
+The result is not a CIPA DC-011 measurement, real-camera stabilization rating, or spatially varying rotational optical-flow model.
+
+### Aperture and diffraction
+
+The optional aperture-shape response contains regular-polygon vertices plus idealized sunstar direction symmetry. Blade count is bounded to 1024.
+
+The separate diffraction result remains the ideal **circular-pupil** first-zero Airy diagnostic and reports `pupilModel: "ideal-circular"`.
+
+Polygon aperture geometry does not convert the circular Airy result into a polygon-aperture diffraction PSF.
+
+### Focus criterion
+
+For cross-format comparisons, the equivalent-viewing helper scales a caller-supplied reference CoC by sensor-diagonal ratio.
+
+That is explicitly an approximation based on equivalent final viewing assumptions; it is not a physical lens/sensor blur threshold.
+
+### Primary-subject diagnostics
+
+When requested with the needed subject inputs, diagnostics report sampling, defocus, circular-pupil diffraction, optional named subject-motion path, and optional stabilized camera-shake path side by side.
+
+They are intentionally **not** collapsed into one sharpness score because these quantities describe different physical effects.
+
+### Provenance
+
+Aggregate response provenance is:
+
+- `calculated` when all included components are calculated models;
+- `mixed` when an equivalent-viewing focus criterion and/or camera-shake approximation is present.
+
+Component provenance identifies which parts are calculated versus approximate.
+
+## Validation and errors
+
+Decoded HTTP JSON is structurally checked for required object/array/string/finite-number/vector shapes before simulation.
+
+That parser does not duplicate every scientific domain/range rule. Scientific modules remain responsible for constraints such as positive dimensions, physically valid distances, blade-count bounds, and crop limits.
+
+Current transport responses include:
+
+- `200`: successful simulation;
+- `204`: CORS preflight;
+- `400`: malformed JSON/shape or invalid scientific request;
+- `404`: unknown route;
+- `415`: simulation POST without `application/json`.
+
+Error messages are intended for local development diagnostics and should not be treated as a hardened public error contract.
+
+## Reusable repository module
+
+Within this repository, `src/api/server.ts` exports an unbound `createPocApiServer` constructor for tests and trusted development composition.
+
+It is repository-internal development tooling rather than a supported npm subpath. Importing the module in repository tests does not start a listener; the CLI entrypoint is responsible for binding the configured host/port.
+
+## Important limitations
+
+- Local POC transport only.
+- No authentication or authorization.
+- No rate limiting or public-service abuse protection.
+- No persistence.
+- No scene uploads.
+- No calibration database.
+- No real-camera/lens claims.
+- ISO is an exposure/gain setting, not a noise shortcut.
+- Photon/noise primitives exist in the root library, but calibrated photon/noise output is intentionally absent from the composed POC until the radiometric/spectral/optical/sensor prerequisites are defensible.

package/docs/PROVENANCE.md

@@ -0,0 +1,87 @@
+# Scientific and Source Provenance
+
+Every scientific or calculation module in this repository must have a traceable, legally clean origin.
+
+## Allowed foundations
+
+An implementation may be based on:
+
+1. Public-domain facts and mathematics.
+2. Established mathematical identities and physical laws.
+3. Scientific methods described in public technical literature, standards, patents, or papers, provided protected text/code/tables/figures are not copied unless separately licensed for that use and any applicable third-party patent rights are separately considered.
+4. Third-party code, datasets, model weights, or calibration material only when the applicable license explicitly permits the intended copying, modification, redistribution, and commercial use and is compatible with this project.
+
+"Available on the internet" is not sufficient permission.
+
+A paper, standard, or patent publication may explain a method without granting copyright permission to copy its expression and without granting a patent license. Independent implementation addresses source-code/prose provenance; it does not by itself resolve active third-party patent claims.
+
+## Independent implementation
+
+When a reference explains a method but does not license its implementation or text for reuse:
+
+- understand the mathematical/scientific method;
+- write a fresh implementation from the method, not from proprietary source structure;
+- do not translate, mechanically rewrite, or adapt proprietary source code;
+- do not copy protected tables, diagrams, explanatory prose, calibration datasets, waveform files, or model weights;
+- add tests based on independently derived analytical cases or clearly reusable data;
+- record material references and any known licensing/patent constraints.
+
+## AI-assisted work
+
+AI-assisted code, documentation, tests, or research notes are treated as untrusted draft material until substantively reviewed by a human contributor.
+
+A contributor using an AI system remains responsible for:
+
+- confirming that the submitted expression is appropriate to distribute under Apache-2.0;
+- checking for suspiciously copied/source-like output;
+- validating scientific and technical correctness;
+- ensuring no confidential or restricted third-party material was supplied to the tool;
+- making the DCO certification for the final submitted contribution.
+
+An AI system's assertion about originality, copyrightability, patents, or license compatibility is not accepted as provenance evidence.
+
+## Module record
+
+Meaningful scientific modules should document, in JSDoc or an adjacent reference document:
+
+- mathematical/physical basis;
+- assumptions and valid range;
+- units and coordinate conventions;
+- whether the implementation is independent;
+- public references used to understand or validate the method;
+- third-party code/data incorporated, if any;
+- the license for any incorporated third-party material;
+- uncertainty or approximation status where applicable.
+
+## Provenance labels
+
+Scientific calculation envelopes use these labels:
+
+- `calculated`: directly computed from the documented model.
+- `calibrated`: uses measurement/calibration data with documented reuse rights.
+- `estimated`: an input or result is inferred rather than known exactly.
+- `approximation`: a deliberately simplified model is used.
+
+The composed `simulatePocCamera()` response is not itself a `CalculationResult<T>`; it reports aggregate/component provenance separately and uses `mixed` when calculated components are combined with explicitly approximate components.
+
+## Uncertainty and quality metadata
+
+Provenance answers **how a result was produced**; uncertainty answers **what quantitative accuracy/variability is defensibly known**. They are related but must not be conflated.
+
+When available, `CalculationResult.quality` records uncertainty components by affected quantity and source:
+
+- `measurement`: variability/uncertainty originating in measured inputs or observations;
+- `calibration`: uncertainty originating in a calibration or calibrated reference;
+- `model-approximation`: quantified error attributed to a simplified/inexact model.
+
+An approximation label does not by itself justify a numeric model-error estimate. If no defensible bound exists, retain the approximation provenance and assumptions without fabricating quality metadata.
+
+Confidence/coverage levels are optional and must include a stated basis. They are not subjective confidence scores.
+
+Valid-range metadata describes where a model/calibration is considered applicable. It is not an uncertainty interval.
+
+When composing models, preserve uncertainty components separately unless a documented model provides a defensible combination rule. Do not imply statistical independence, add errors in quadrature, or publish a single aggregate confidence score without evidence.
+
+## Release gate
+
+Ambiguous licensing, unresolved material patent risk, uncertain provenance, unexplained copied material, fabricated uncertainty, undocumented uncertainty combination, or unsupported scientific claims block release until resolved.

package/docs/STABILIZATION.md

@@ -0,0 +1,78 @@
+# Camera Shake and Stabilization
+
+Photivra separates deterministic projection geometry from a deliberately simplified educational stabilization model.
+
+## Controlled camera shake
+
+`estimateCameraShakeBlur()` accepts constant camera angular velocity around two axes:
+
+- yaw, in radians per second;
+- pitch, in radians per second.
+
+For shutter-open duration `t`, each angular displacement is:
+
+`theta = angularVelocity * t`
+
+The image-plane component is projected as:
+
+`d = v * tan(theta)`
+
+where `v` is the projection distance in millimetres.
+
+Projection has two modes:
+
+- without `focusDistanceM`, `v` is nominal focal length (the infinity-focus compatibility approximation);
+- with `focusDistanceM`, `v` is the ideal Gaussian thin-lens image distance for the selected focus plane.
+
+When pixel pitch is supplied, the same displacement is also reported in sensor pixels.
+
+The supplied shake profile is synthetic input. The model is not an empirical statement about how much a particular photographer shakes.
+
+### Spatial limitation
+
+The current result is one global image-plane yaw/pitch vector. Real camera rotation produces position-dependent optical flow away from the optical axis; that spatial variation is not yet modeled. Roll and translational camera motion are also omitted.
+
+## Equivalent stabilization stops
+
+The model accepts `stabilizationStopsEquivalent`.
+
+For educational exploration, the supplied angular displacement is attenuated by:
+
+`residualMotionFactor = 2 ^ (-stops)`
+
+For example, 3 equivalent stops produces a residual factor of 1/8 for the controlled synthetic shake profile.
+
+This attenuation is an **approximation**. It is useful for demonstrating the effect of reducing camera motion, but it is not a model of a particular IBIS/OIS implementation and does not imply that a real stabilization system deterministically reduces every motion path by that factor.
+
+Because the returned result combines this attenuation assumption with the geometric projection, the calculation envelope uses `provenance.kind = "approximation"`.
+
+## CIPA reference
+
+CIPA publishes **DC-011-2024** for measurement and description of image-stabilization performance.
+
+Photivra is not affiliated with, sponsored by, endorsed by, certified by, or claimed to comply with CIPA. The current educational approximation does not implement the CIPA test method.
+
+Reference:
+
+- CIPA DC-011-2024 overview: https://www.cipa.jp/e/std/image-stabilization.html
+
+Only the public standard identifier and high-level terminology are referenced here; CIPA logos and protected standard content are not incorporated into this project.
+
+## Not yet modeled
+
+The current model intentionally omits:
+
+- roll;
+- translational camera shake;
+- spatially varying rotational optical flow;
+- frequency-dependent shake spectra;
+- photographer-to-photographer variation;
+- shutter-button impulse;
+- tripod/support interactions;
+- sensor/lens stabilization axis limits;
+- IBIS/OIS coordination;
+- focal-length-dependent stabilization effectiveness beyond projection geometry;
+- rolling shutter;
+- panning detection/modes.
+
+Those capabilities should be added as separate, documented models rather than being silently folded into the current approximation.