API.md

API.md

AlphaForge Public API

This document is the canonical registry of the AlphaForge public API.

The public API boundary is the package root entry point (src/index.ts / dist/index.js). Any export that is not re-exported from the package root is considered Internal and may change without notice.

Only APIs documented in this file are Public. Public APIs are covered by the stability contract; Internal APIs are not.

Status Legend

Status	Meaning
Public	Part of the supported public API. Changes follow semantic versioning.
Internal	Not part of the public API. May change or be removed without notice.
Deprecated	Public API that is planned for removal.

Public API

IO

Name	Status	Source file	Re-export location	Description
VERSION	Public	src/index.ts	src/index.ts	Library version string.
loadImage	Public	src/io/image-loader.ts	src/io/index.ts → src/index.ts	Load and decode an image file into the AlphaForge RGBA8 representation.
ImageData	Public	src/io/image-types.ts	src/io/index.ts → src/index.ts	Immutable decoded RGBA8 image container.
LoadImageOptions	Public	src/io/image-types.ts	src/io/index.ts → src/index.ts	Options for loadImage.
ImageLoadError	Public	src/io/image-types.ts	src/io/index.ts → src/index.ts	Error thrown when image loading or decoding fails.

Validation

Name	Status	Source file	Re-export location	Description
validateImages	Public	src/validation/validate-images.ts	src/validation/index.ts → src/index.ts	Validate a pair of images for metadata and dimension compatibility.
assertImagesValid	Public	src/validation/validate-images.ts	src/validation/index.ts → src/index.ts	Assert that a pair of images is valid, throwing typed errors on failure.
validateImageMetadata	Public	src/validation/metadata-validator.ts	src/validation/index.ts → src/index.ts	Validate the metadata of a single image.
validateImageDimensions	Public	src/validation/dimension-validator.ts	src/validation/index.ts → src/index.ts	Validate that two images have matching dimensions.
ValidationError	Public	src/validation/validation-errors.ts	src/validation/index.ts → src/index.ts	Base error for all validation failures.
MetadataValidationError	Public	src/validation/validation-errors.ts	src/validation/index.ts → src/index.ts	Error thrown when image metadata is invalid.
DimensionValidationError	Public	src/validation/validation-errors.ts	src/validation/index.ts → src/index.ts	Error thrown when image dimensions are incompatible.
ValidationIssue	Public	src/validation/validation-types.ts	src/validation/index.ts → src/index.ts	A single validation issue discovered by a validator.
ValidationResult	Public	src/validation/validation-types.ts	src/validation/index.ts → src/index.ts	Structured result of validating an image pair.
measureBackgroundColor	Public	src/validation/background-validation.ts	src/validation/index.ts → src/index.ts	Measure the mean linear RGB color of an image border.
validateBackgroundColors	Public	src/validation/background-validation.ts	src/validation/index.ts → src/index.ts	Compare declared background colors against measured border colors.
assertBackgroundColorsValid	Public	src/validation/background-validation.ts	src/validation/index.ts → src/index.ts	Assert that declared background colors match measured border colors.
BackgroundMismatchError	Public	src/validation/background-errors.ts	src/validation/index.ts → src/index.ts	Error thrown when a background mismatch is detected.
DEFAULT_BACKGROUND_BORDER_WIDTH	Public	src/validation/background-validation.ts	src/validation/index.ts → src/index.ts	Default border width for background sampling.
DEFAULT_BACKGROUND_MISMATCH_THRESHOLD	Public	src/validation/background-validation.ts	src/validation/index.ts → src/index.ts	Default linear RGB mismatch threshold.
MeasuredBackgroundColor	Public	src/validation/background-validation.ts	src/validation/index.ts → src/index.ts	Metadata from a measured border color.
BackgroundValidationOptions	Public	src/validation/background-validation.ts	src/validation/index.ts → src/index.ts	Options for background validation.
BackgroundValidationResult	Public	src/validation/background-validation.ts	src/validation/index.ts → src/index.ts	Result of comparing declared and measured background colors.
BackgroundMismatchContext	Public	src/validation/background-errors.ts	src/validation/index.ts → src/index.ts	Context attached to a BackgroundMismatchError.

Color

Name	Status	Source file	Re-export location	Description
srgbToLinear	Public	src/color/color-converter.ts	src/color/index.ts → src/index.ts	Convert an RGBA8 image to linear RGB color space.
linearToSrgb	Public	src/color/color-converter.ts	src/color/index.ts → src/index.ts	Convert a linear RGB image back to RGBA8 sRGB color space.
LinearImageData	Public	src/color/color-types.ts	src/color/index.ts → src/index.ts	Immutable decoded image data in linear RGB color space.

Both color conversion functions throw Error when the input format or buffer dimensions are invalid. The exact error subclass is an internal implementation detail.

Reconstruction

Name	Status	Source file	Re-export location	Description
reconstructAlpha	Public	src/reconstruction/alpha-reconstruction.ts	src/reconstruction/index.ts → src/index.ts	Reconstruct a scalar alpha channel from two linear RGB observations.
AlphaReconstructionError	Public	src/reconstruction/alpha-errors.ts	src/reconstruction/index.ts → src/index.ts	Error thrown when alpha reconstruction fails.
ReconstructionInput	Public	src/reconstruction/reconstruction-types.ts	src/reconstruction/index.ts → src/index.ts	A linear observation and its known background.
ReconstructAlphaOptions	Public	src/reconstruction/alpha-types.ts	src/reconstruction/index.ts → src/index.ts	Options for reconstructAlpha.
AlphaChannelData	Public	src/reconstruction/alpha-types.ts	src/reconstruction/index.ts → src/index.ts	Single-channel alpha image in [0, 1].
reconstructForeground	Public	src/reconstruction/foreground-reconstruction.ts	src/reconstruction/index.ts → src/index.ts	Reconstruct the original foreground color from two linear RGB observations and a reconstructed alpha channel.
ForegroundReconstructionError	Public	src/reconstruction/foreground-errors.ts	src/reconstruction/index.ts → src/index.ts	Error thrown when foreground reconstruction fails.
ReconstructForegroundOptions	Public	src/reconstruction/foreground-types.ts	src/reconstruction/index.ts → src/index.ts	Options for reconstructForeground.
ForegroundImageData	Public	src/reconstruction/foreground-types.ts	src/reconstruction/index.ts → src/index.ts	Three-channel linear RGB foreground image in [0, 1].

Cleanup

Name	Status	Source file	Re-export location	Description
cleanup	Public	src/cleanup/cleanup.ts	src/cleanup/index.ts → src/index.ts	Deterministic cleanup pipeline for alpha and optional foreground.
CleanupError	Public	src/cleanup/cleanup-errors.ts	src/cleanup/index.ts → src/index.ts	Error thrown when cleanup fails or receives invalid input.
CleanupOptions	Public	src/cleanup/cleanup-types.ts	src/cleanup/index.ts → src/index.ts	Options for cleanup.
CleanupResult	Public	src/cleanup/cleanup-types.ts	src/cleanup/index.ts → src/index.ts	Result of cleanup.
AlphaThresholdOptions	Public	src/cleanup/cleanup-types.ts	src/cleanup/index.ts → src/index.ts	Configuration for alpha thresholding.
NoiseRemovalOptions	Public	src/cleanup/cleanup-types.ts	src/cleanup/index.ts → src/index.ts	Configuration for noise removal.
MorphologyOptions	Public	src/cleanup/cleanup-types.ts	src/cleanup/index.ts → src/index.ts	Configuration for morphological cleanup.
StructuringElementOptions	Public	src/cleanup/cleanup-types.ts	src/cleanup/index.ts → src/index.ts	Configuration for a structuring element.
StructuringElementShape	Public	src/cleanup/cleanup-types.ts	src/cleanup/index.ts → src/index.ts	Structuring element shape: square, disk, or cross.
Connectivity	Public	src/cleanup/cleanup-types.ts	src/cleanup/index.ts → src/index.ts	Connectivity for noise removal: 4 or 8.

Export

Name	Status	Source file	Re-export location	Description
exportPng	Public	src/export/export-png.ts	src/export/index.ts → src/index.ts	Export reconstructed image data to a PNG file.
ExportPngOptions	Public	src/export/export-types.ts	src/export/index.ts → src/index.ts	Options for exportPng.
ExportResult	Public	src/export/export-types.ts	src/export/index.ts → src/index.ts	Result of a PNG export.
ExportError	Public	src/export/export-errors.ts	src/export/index.ts → src/index.ts	Error thrown when PNG export fails.

Pipeline

Name	Status	Source file	Re-export location	Description
reconstructPipeline	Public	src/pipeline/reconstruct-pipeline.ts	src/pipeline/index.ts → src/index.ts	Orchestrate the full reconstruction pipeline.
PipelineError	Public	src/pipeline/pipeline-errors.ts	src/pipeline/index.ts → src/index.ts	Error thrown when the reconstruction pipeline fails.
ReconstructPipelineOptions	Public	src/pipeline/pipeline-types.ts	src/pipeline/index.ts → src/index.ts	Options for reconstructPipeline.
ReconstructPipelineResult	Public	src/pipeline/pipeline-types.ts	src/pipeline/index.ts → src/index.ts	Result of reconstructPipeline.
ReconstructPipelineCleanupOptions	Public	src/pipeline/pipeline-types.ts	src/pipeline/index.ts → src/index.ts	Configuration for optional cleanup stages inside the pipeline.

Anything not listed above is Internal. Internal helpers such as PixelFormat, Severity, srgbToLinearChannel, linearToSrgbChannel, and aggregateAlphaEstimates are intentionally omitted because they are not re-exported from the package root.

Error Contract

All public error classes extend Error and set name to the class name. Errors are explicit and must never be silently ignored by the library.

Every public error may carry a cause?: unknown property that preserves the original underlying error or value. Callers can inspect cause to produce actionable diagnostics.

Some errors carry additional structured context:

Error	cause	Extra properties
ImageLoadError	yes	context?: { path: string }
ValidationError	yes	issues: readonly ValidationIssue[]
MetadataValidationError	yes	inherits ValidationError
DimensionValidationError	yes	inherits ValidationError
BackgroundMismatchError	yes	context?: BackgroundMismatchContext
AlphaReconstructionError	yes	none
ForegroundReconstructionError	yes	none
CleanupError	yes	none
ExportError	yes	context?: { path: string }
PipelineError	yes	none

PipelineError.cause always contains the error raised by the failing stage, which may be any of the errors above.

The exact error message strings are not part of the public stability contract. Only the error type, the presence of cause, and the documented context properties are guaranteed.

Stability Contract

Only exports listed in this document are Public. Public function signatures, return types, and the error contract are covered by the stability contract.

Internal helpers, module file paths, and error message strings may change without notice. Consumers should rely exclusively on the Public API.