# lightdrift-libraw 1.0.0-rc.1

`1.0.0-rc.1` is the first release candidate for the stable LightDrift LibRaw
SDK. It replaces the beta root contract with a typed, asynchronous API while
keeping the frozen beta behavior available at `lightdrift-libraw/legacy`.

The candidate is published to the npm `next` dist-tag only after every release
workflow gate succeeds. It must not replace `latest`.

## Highlights

- Vendored LibRaw 0.22.2 and zlib 1.3.2; no system LibRaw dependency.
- Node.js 22 and 24 support through Node-API 8.
- ESM, CommonJS, and TypeScript declarations.
- One FIFO worker queue per instance with cancellation and typed events.
- Complete safe LibRaw mirror: 65 supported manifest entries and six explicit
  exclusions.
- Unified Sharp workflow for JPEG, PNG, TIFF, WebP, AVIF, and 8/16-bit PPM.
- Prebuild targets for Linux glibc x64/arm64, macOS x64/arm64, and Windows x64.
- Frozen beta compatibility entry point throughout v1.
- Sharp 0.35.3 with current libvips security fixes.

## Install

After the release workflow publishes the candidate:

```bash
npm install lightdrift-libraw@next
```

Do not install the public `beta` dist-tag expecting the stable root API; it
contains the older beta contract.

## Breaking changes from beta

- The package root now exports the stable asynchronous `LibRaw` class.
- Stable encoded results use `{ data, format, width, height, channels, size,
  processingTimeMs, source }`.
- Stable failures are `LibRawError` instances with `code`, `operation`,
  `librawCode`, `state`, and `cause`.
- `openFile()` opens only; `loadFile()` performs recycle → open → unpack.
- `close()` permanently closes an instance. Use `recycle()` for reuse.
- Canonical mirror names use camelCase.

See the [migration guide](../migration-v1.md) for the complete compatibility
contract.

## Supported platforms

| Platform | Architecture | Delivery |
| --- | --- | --- |
| Linux glibc | x64, arm64 | Prebuilt + source fallback |
| macOS | x64, arm64 | Prebuilt + source fallback |
| Windows | x64 | Prebuilt + source fallback |

Node.js 20, Alpine/musl, browsers, WASM, and system LibRaw are outside v1.

## Known limitations

- Inputs and outputs are complete files or buffers; incremental streaming is
  not implemented.
- Callback events are ordered records emitted after a native operation, not
  live progress-bar updates.
- Sharp codecs normalize 16-bit LibRaw samples to 8-bit before encoding. Use
  `dcrawMakeMemImage()` or `createPPMBuffer()` to retain 16-bit samples.
- Direct LibRaw writer/profile paths on Windows remain limited to the active
  Windows code page. Sharp-based convenience writers accept Unicode paths.
- `/legacy` is deprecated and will be removed in v2.

## Promotion gates

The RC may be promoted to the version-only `1.0.0` release after all of these
gates pass from the same commit:

- [ ] Node.js 22 and 24 stable suites.
- [ ] Linux glibc x64 and arm64 prebuild/runtime jobs.
- [ ] macOS x64 and arm64 prebuild/runtime jobs.
- [ ] Windows x64 prebuild/runtime job.
- [ ] Linux forced source-only tarball installation.
- [ ] Full Linux stable suite and malformed-input child under ASan/UBSan.
- [ ] Production dependency audit with no high-severity findings.
- [ ] Npm tarball assembled with all five prebuilds and required licenses/docs.
- [ ] CJS, ESM, and TypeScript consumers on Node.js 22 and 24 without install
  scripts or a compiler.
- [ ] CycloneDX 1.6 SBOM validation.
- [ ] Trusted npm publication with provenance to `next`.

Promotion changes only the package version and release notes. It does not add
features or change the API contract.

## Related

- [Documentation index](../README.md) - Complete SDK documentation.
- [Migration guide](../migration-v1.md) - Move from beta to stable v1.
- [Platform support](../platform-support.md) - Detailed target matrix.
- [Implementation audit](../superpowers/2026-08-15-lightdrift-libraw-stable-v1-audit.md) - Local evidence and external gates.
- [Project README](../../README.md) - Installation and overview.