@gongbaodd/qr-renderer 0.1.0

package/dist/types/core/artifacts.d.ts

@@ -0,0 +1,2 @@
+import type { RegionMask } from './types';
+export declare function renderRegionMask(mask: RegionMask): Promise<Uint8Array>;

package/dist/types/core/assemble.d.ts

@@ -0,0 +1,36 @@
+import type { PixelStyle } from './pattern';
+import type { QrPalette } from './palette';
+import type { AssembleReport, BoundingBox, ResolvedLayout } from './types';
+/**
+ * Assembles the finished poster offline in whole modules. Upright placements take the golden
+ * 0° path, where the generator's marker-free matrix is sampled against the painted region on
+ * the placed QR's own lattice. A rotated placement instead validates and paints in the QR's
+ * upright frame: the region mask is inverse-rotated into that frame, the same whole-module
+ * pipeline generates the fill and plate there, and the finished overlay rides the placement
+ * transform back onto the poster (doc/plan/rotated-mask-fill.md).
+ */
+export declare function assembleResolved(layout: ResolvedLayout, options: {
+    seed?: number;
+    qrMargin?: 1;
+    radius?: number;
+    rimModules?: number;
+    rimRounded?: boolean;
+    regionMargin?: boolean;
+    pixelStyle?: PixelStyle;
+    transparentBlank?: boolean;
+    palette?: QrPalette;
+}): Promise<{
+    report: AssembleReport;
+    artifacts: Record<string, Uint8Array<ArrayBufferLike>>;
+}>;
+/**
+ * Geometry of the marker-only light band, in poster pixels: beside each 7x7 finder marker, the two
+ * arms that run along its outer edges plus the diagonal corner block, all whole cells on the module
+ * lattice. The arms span the finder footprint exactly — the separator inside the code grid already
+ * carries its own light row and column — so the band is three small Ls rather than a quiet zone
+ * around the code.
+ */
+export declare function markerBandRects(codeGrid: BoundingBox, qrModules: number, pitch: number, marginModules: 1): {
+    arms: BoundingBox[];
+    cornerBlocks: BoundingBox[];
+};

package/dist/types/core/errors.d.ts

@@ -0,0 +1,6 @@
+export type ErrorCode = 'QWEN_API_FAILED' | 'INVALID_INPUT' | 'MASK_AMBIGUOUS' | 'MASK_INVALID' | 'QR_INVALID' | 'QR_TEXT_MISMATCH' | 'QR_LAYOUT_INVALID' | 'COLOR_INVALID' | 'OUTPUT_EXISTS' | 'IMAGE_PROCESSING_FAILED' | 'VERIFICATION_FAILED';
+export declare class QrPosterError extends Error {
+    readonly code: ErrorCode;
+    readonly exitCode: 2 | 3 | 4;
+    constructor(code: ErrorCode, message: string, exitCode?: 2 | 3 | 4, options?: ErrorOptions);
+}

package/dist/types/core/export-sizes.d.ts

@@ -0,0 +1,21 @@
+import type { RawImage } from './imaging/types';
+import type { RegionMask } from './types';
+export declare const RASTER_EXPORT_TARGETS: readonly [320, 640, 1280];
+export interface RasterExportChoice {
+    key: string;
+    targetPitch: number;
+    width: number;
+    height: number;
+}
+export declare function dimensionsAtPitch(width: number, height: number, originalPitch: number, targetPitch: number): {
+    width: number;
+    height: number;
+};
+/** Build distinct smaller choices while keeping every export on an integer QR-module pitch. */
+export declare function rasterExportChoices(width: number, height: number, originalPitch: number): RasterExportChoice[];
+/** Area-weighted RGBA shrink in premultiplied-alpha space. */
+export declare function resizeAreaPremultiplied(source: RawImage, width: number, height: number): Uint8Array;
+/** A target mask pixel is selected only when every source pixel in its footprint is selected. */
+export declare function resizeRegionMaskConservative(source: RegionMask, width: number, height: number): RegionMask;
+/** A self-contained full-poster SVG backed by the exact verified assembled PNG. */
+export declare function buildPosterSvg(png: Uint8Array, width: number, height: number): string;

package/dist/types/core/image.d.ts

@@ -0,0 +1,14 @@
+export interface LoadedPng {
+    path: string;
+    file: Uint8Array;
+    data: Uint8Array;
+    width: number;
+    height: number;
+    sha256: string;
+}
+export declare function loadPng(path: string, label: string): Promise<LoadedPng>;
+/** Decodes an in-memory PNG into the same shape {@link loadPng} returns. */
+export declare function decodePng(file: Uint8Array, path: string, label: string): Promise<LoadedPng>;
+export declare function rgbaToPng(data: Uint8Array, width: number, height: number): Promise<Uint8Array>;
+export declare function grayscaleToPng(data: Uint8Array, width: number, height: number): Promise<Uint8Array>;
+export declare function luma(r: number, g: number, b: number): number;

package/dist/types/core/imaging/browser.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The browser imaging backend: @jsquash/png for the lossless PNG codec and
+ * @resvg/resvg-wasm as the SVG rasterizer. Pixel work (composite, flatten,
+ * nearest resize) shares the pure-TS helpers in pixels.ts so both environments
+ * implement the same document semantics.
+ *
+ * The WASM binaries are initialized lazily on the first operation. In a browser
+ * bundle both codecs auto-resolve their `.wasm` assets relative to their own
+ * module URL; in Node (parity harness) pass the raw wasm bytes via
+ * {@link installBrowserImaging}.
+ */
+import type { InitInput as PngWasmInput } from '@jsquash/png/codec/pkg/squoosh_png.js';
+import type { InitInput as ResvgWasmInput } from '@resvg/resvg-wasm';
+import type { Imaging } from './types';
+export interface BrowserImagingOptions {
+    /** resvg wasm source; defaults to the codec's bundled URL in browser builds. */
+    resvgWasm?: ResvgWasmInput;
+    /** jSquash png wasm source; defaults to the codec's bundled URL in browser builds. */
+    pngWasm?: PngWasmInput;
+}
+/** Pre-initializes the codec WASMs; call once per worker/entry point. */
+export declare function installBrowserImaging(options?: BrowserImagingOptions): Promise<void>;
+export declare const browserImaging: Imaging;

package/dist/types/core/imaging/cloudflare.d.ts

@@ -0,0 +1,2 @@
+/** Installs the same codec backend used in the browser worker using bundled Worker WASM modules. */
+export declare const cloudflareImagingReady: Promise<void>;

package/dist/types/core/imaging/index.d.ts

@@ -0,0 +1,5 @@
+import type { Imaging } from './types';
+/** Installs one backend. Entry points only (test setup, scripts, route handlers, the worker). */
+export declare function setImaging(backend: Imaging): void;
+/** The installed backend. Core modules call this instead of importing sharp directly. */
+export declare function imaging(): Imaging;

package/dist/types/core/imaging/node.d.ts

@@ -0,0 +1,4 @@
+/** The Node imaging backend. Every operation mirrors the exact sharp pipeline the call
+ * site used before the seam, so Node-side output bytes stay bit-identical after extraction. */
+import type { Imaging } from './types';
+export declare const nodeImaging: Imaging;

package/dist/types/core/imaging/pixels.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Pure-TS pixel operations shared by pixel-writing backends. The sharp backend keeps its
+ * own native compositing for existing opaque paths so their bytes stay bit-identical. Shared
+ * pixel helpers cover operations that need identical semantics in both environments, including
+ * source-over into the transparent blank poster.
+ */
+import type { RawImage } from './types';
+/** Source-over composites one unpremultiplied RGBA pixel into another in place. */
+export declare function compositePixelOver(source: Uint8Array, sourceOffset: number, destination: Uint8Array, destinationOffset: number, sourceAlphaOverride?: number): void;
+/** Flattens alpha over an opaque white background: `out = c*a/255 + 255*(1 - a/255)`, truncated. */
+export declare function flattenOverWhite(data: Uint8Array): Uint8Array;
+/**
+ * Standard source-over blend of full-size unpremultiplied RGBA overlay rasters over an
+ * opaque base. Alpha compositing uses the same blend libvips performs; differences stay
+ * limited to SVG antialiasing, which the renderers already treat as free.
+ */
+export declare function compositeOver(base: RawImage, overlays: RawImage[]): Uint8Array;
+/**
+ * Integer nearest-neighbor resample, matching the probed libvips(nearest) mapping rules:
+ * expansion anchors left (`floor(x * in / out)`), shrink centers the sample
+ * (`floor((x + 0.5) * in / out)`). Residual tie cases (exact-integer or half-integer
+ * sample positions) may pick one pixel lower in libvips' internal two-stage shrink —
+ * a documented deviation absorbed by the parity tolerance, never affecting intra-run
+ * verification.
+ */
+export declare function resizeNearest(raw: RawImage, width: number, height: number): Uint8Array;
+/** Copies a subrectangle without resampling. */
+export declare function cropRgba(raw: RawImage, x: number, y: number, width: number, height: number): Uint8Array;

package/dist/types/core/imaging/types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Environment-agnostic imaging seam. Core modules call these operations instead of
+ * using sharp (or any other rasterizer) directly, so a Node (sharp) and a browser
+ * backend can be swapped without touching pipeline logic.
+ *
+ * Semantics each backend must honor:
+ * - `decodePng` is strict and exact: RGBA pixels, failing loudly on undecodable input.
+ * - `rasterizeSvg` returns unpremultiplied RGBA; antialiased edges may differ between
+ *   rasterizers (librsvg here, the browser rasterizer later), which the poster has always
+ *   treated as renderer freedom.
+ */
+/** A decoded raster of unpremultiplied RGBA pixels. */
+export interface RawImage {
+    data: Uint8Array;
+    width: number;
+    height: number;
+}
+/** Result of rasterizing an SVG straight to PNG bytes. */
+export interface RenderedSvgPng {
+    png: Uint8Array;
+    width: number;
+    height: number;
+}
+export interface SvgRenderOptions {
+    /** Composites the raster over opaque white before encoding (plain alpha otherwise). */
+    flatten?: boolean;
+}
+export interface Imaging {
+    /** Strict PNG decode into exact RGBA. */
+    decodePng(file: Uint8Array): Promise<RawImage>;
+    /** Encodes RGBA pixels into PNG bytes. */
+    encodePngRgba(data: Uint8Array, width: number, height: number): Promise<Uint8Array>;
+    /** Encodes a one-byte-per-pixel grayscale raster into PNG bytes. */
+    encodePngGrayscale(data: Uint8Array, width: number, height: number): Promise<Uint8Array>;
+    /** Rasterizes an SVG at the exact size into RGBA pixels. */
+    rasterizeSvg(svg: string, width: number, height: number): Promise<RawImage>;
+    /** Rasterizes an SVG into PNG bytes, optionally flattened over opaque white. */
+    renderSvgToPng(svg: string, options: SvgRenderOptions): Promise<RenderedSvgPng>;
+    /** Composites SVG overlays (rasterized at the base size) over a base PNG into PNG bytes. */
+    composeQrPng(basePng: Uint8Array, overlaySvgs: string[]): Promise<Uint8Array>;
+    /** Flattens alpha over white, nearest-resamples to a square target size, returns PNG bytes. */
+    normalizeQrPng(file: Uint8Array, targetSize: number): Promise<Uint8Array>;
+    /** SHA-256 hex of bytes or a UTF-8 string. Async so the browser's crypto.subtle fits. */
+    sha256Hex(input: string | Uint8Array): Promise<string>;
+}

package/dist/types/core/mask.d.ts

@@ -0,0 +1,11 @@
+import type { LoadedPng } from './image';
+import type { BoundingBox, Point, RegionMask } from './types';
+/** Shared pixel rule for manual masks: opaque white selects the region. */
+export declare function isSelectedMaskPixel(r: number, g: number, b: number, alpha: number): boolean;
+export declare function buildManualRegionMask(mask: LoadedPng, width: number, height: number): RegionMask;
+export declare function detectRegionMask(image: LoadedPng): RegionMask;
+export declare function calculateMaskStats(data: Uint8Array, width: number, height: number): {
+    area: number;
+    bounds: BoundingBox;
+    centroid: Point;
+};

package/dist/types/core/module-cut.d.ts

@@ -0,0 +1,107 @@
+import type { BoundingBox } from './types';
+/**
+ * The poster-space module lattice the assembled cut is built on. Cell (column, row) covers one
+ * `modulePixels`-sized pixel block, and the origin is the placed QR's own lattice, so every drawn
+ * module is a whole QR cell of the texture rather than a slice of one.
+ */
+export interface ModuleLattice {
+    /** Poster-space x of the lattice origin; `0 <= x < modulePixels`. */
+    x: number;
+    /** Poster-space y of the lattice origin; `0 <= y < modulePixels`. */
+    y: number;
+    modulePixels: number;
+    columns: number;
+    rows: number;
+    width: number;
+    height: number;
+}
+/** Plate window in poster pixels; its box must sit on the lattice or the hole would slice a module. */
+export interface ModuleWindow {
+    x: number;
+    y: number;
+    size: number;
+}
+export interface SafeArea {
+    /** Row-major grid: 1 when the module's whole pixel block is inside the painted region. */
+    safe: Uint8Array;
+    safeModules: number;
+    /** Modules the region covers only in part; they keep the original artwork. */
+    partialModules: number;
+    /** Region pixels inside those partial modules, which the cut therefore never paints. */
+    droppedPartialPixels: number;
+    /** Canvas-pixel bounds of the safe modules. */
+    bounds: BoundingBox;
+}
+export interface PlateModules {
+    /** Row-major grid: 1 for every module the cut drops for the QR plate, corners already handed back. */
+    cells: Uint8Array;
+    /** Row-major grid: 1 for the modules handed back to the texture. */
+    corners: Uint8Array;
+    /** Modules the hole covers after the corners are handed back. */
+    holeModules: number;
+    /** Modules the texture keeps, 0 when the hand-back rectangles are empty. */
+    cornerModules: number;
+    /** Canvas-pixel bounds of the plate cells, the hand-backs already removed. */
+    bounds: BoundingBox;
+}
+/** Row-major safe cells in the QR's source quiet zone for a tight rectangular mask. */
+export interface TightBlockQuietZone {
+    cells: Uint8Array;
+    modules: number;
+}
+/**
+ * Builds the module lattice covering the canvas. The origin is reduced to a phase inside one
+ * module, so a caller can pass the placement box directly and get the same lattice the QR uses.
+ */
+export declare function buildModuleLattice(width: number, height: number, modulePixels: number, origin: {
+    x: number;
+    y: number;
+}): ModuleLattice;
+/** Poster-space block of one lattice cell. */
+export declare function moduleBlock(lattice: ModuleLattice, column: number, row: number): ModuleWindow;
+/** Index of the cell containing a poster pixel, or -1 when the pixel is off the lattice. */
+export declare function moduleCellIndex(lattice: ModuleLattice, x: number, y: number): number;
+/**
+ * Marks the modules the cut may draw: a module is safe only when its whole pixel block is on the
+ * canvas and every one of those pixels is inside the painted region. A module the region covers
+ * only in part is dropped, so the drawn area stays a union of whole modules and the original
+ * artwork survives along the silhouette.
+ */
+export declare function computeSafeArea(selection: Uint8Array, width: number, height: number, lattice: ModuleLattice): SafeArea;
+/**
+ * Keeps the normalized QR's two-module light margin quiet when a solid rectangular mask nearly
+ * touches the placed QR on all four sides. The region and placement use exclusive right/bottom
+ * bounds; partially covered cells stay out because only safe cells can be returned.
+ */
+export declare function computeTightBlockQuietZone(selection: Uint8Array, width: number, height: number, safe: Uint8Array, plate: Uint8Array, lattice: ModuleLattice, placement: ModuleWindow, enabled: boolean): TightBlockQuietZone;
+/**
+ * Marks the plate on the module lattice. The hole is every module whose whole block sits inside one
+ * of the plate rectangles — the code grid plus the light arms beside the finder markers — so the cut
+ * never relies on artwork showing through the plate and no drawn edge crosses a module. The
+ * hand-back rectangles (the corner blocks `--cut-radius` carves out of the arms) leave the hole
+ * again and keep the texture, so the plate's corners stay texture instead of the QR's own light
+ * band. Rectangles may share edges and may reach past the canvas; only lattice cells are marked.
+ */
+export declare function computePlateModules(lattice: ModuleLattice, plateRects: BoundingBox[], handbackRects?: BoundingBox[]): PlateModules;
+/**
+ * Marks the outer rings of drawn modules with a Chebyshev distance of at most `rimModules` from the
+ * nearest module the region does not fully cover. Those modules are forced dark, so the rim is a
+ * band of whole modules that closes on the silhouette. The plate is never a seed: the rim follows
+ * the painted region, not the QR window.
+ */
+export declare function computeRimModules(safe: Uint8Array, lattice: ModuleLattice, rimModules: number): Uint8Array;
+/** Outer light margin, followed by the optional dark rim, both restricted to safe whole modules. */
+export declare function computeRegionBands(safe: Uint8Array, lattice: ModuleLattice, rimModules: number, regionMargin: boolean): {
+    margin: Uint8Array;
+    rim: Uint8Array;
+};
+/** Union of whole module rectangles as an SVG path; every edge lands on an integer pixel. */
+export declare function buildModulePath(cells: Uint8Array, lattice: ModuleLattice): string;
+/** Rounded outer silhouette of whole-module union: outer corners filleted to `radius` with antialiasing. */
+export declare function buildRoundedModulePath(cells: Uint8Array, lattice: ModuleLattice, radius: number): string;
+/**
+ * Rasterizes the module path and returns its coverage. By default module edges land on integer
+ * pixel boundaries, so the raster is binary; when `allowAntialias` is true partial alpha is kept
+ * for rounded, antialiased edges.
+ */
+export declare function renderModuleCoverage(pathData: string, width: number, height: number, allowAntialias?: boolean): Promise<Uint8Array>;

package/dist/types/core/palette.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The pattern palette: pixel (ink), marker (finder/alignment ink), and background
+ * (light) colors, plus the OKLCH machinery that derives suggestions from the pixel
+ * color and guards decoding contrast. Pure and dependency-free: UI, worker, and
+ * Node tests share the exact same numbers.
+ */
+export interface QrPalette {
+    /** Ink of every dark module: texture cells, data modules, the rim, marker-refill bits. */
+    pixel: string;
+    /** Ink of the three finder markers and the circular alignment marker. */
+    marker: string;
+    /** Light modules: quiet zone, marker rings, the plate's light band, the region margin. */
+    background: string;
+}
+export declare const DEFAULT_PALETTE: QrPalette;
+/**
+ * The mahu-QR mascot's own palette: near-black pixel ink, vermilion marker ink,
+ * white background. A brand suggestion the UI offers in one tap — never an
+ * engine default, so `DEFAULT_PALETTE` and every golden output stay untouched.
+ */
+export declare const TIGER_PRESET: QrPalette;
+export interface Oklch {
+    /** Perceptual lightness [0, 1]. */
+    l: number;
+    /** Chroma, roughly [0, 0.37] inside sRGB. */
+    c: number;
+    /** Hue in degrees [0, 360). */
+    h: number;
+}
+/** Guard limits. Luma thresholds mirror qr.ts: the quiet-zone rule needs 200 and ink detection is 128. */
+export declare const GUARD: {
+    /** Rec.601 luma a selectable background must stay above (quiet-zone rule needs 200; kept headroom). */
+    readonly lightLumaMin: 205;
+    /** Rec.601 luma every ink must stay at or below (INK_LUMA_THRESHOLD is 128; kept headroom). */
+    readonly inkLumaMax: 120;
+    /** OKLCH lightness distance each ink must keep from the background. */
+    readonly minLightnessDistance: 0.3;
+};
+export declare const HEX_PATTERN: RegExp;
+export type Rgb = [number, number, number];
+/** Parses `#rgb`/`#rrggbb` (any case); null for anything else. */
+export declare function parseHex(hex: string): Rgb | null;
+/** Lowercase six-digit form; null when the input is not a parseable hex color. */
+export declare function normalizeHex(hex: string): string | null;
+/** Rec.601 luma — the same grayscale weights the QR pipeline's ink and quiet-zone rules use. */
+export declare function luma([r, g, b]: Rgb): number;
+/** Convenience for renderers turning a stored hex into 0-255 channels. */
+export declare function hexToRgb(hex: string): Rgb;
+export declare function rgbToOklch(rgb: Rgb): Oklch;
+/**
+ * OKLCH → sRGB, always in gamut: chroma is reduced in fixed `CHROMA_STEP` decrements
+ * until every channel lands in [0, 255], so the same OKLCH maps to the same hex.
+ */
+export declare function oklchToHex({ l, c, h }: Oklch, step?: number): string;
+export declare function hexToOklch(hex: string): Oklch | null;
+/**
+ * Suggests marker and background colors for a picked pixel color, derived in OKLCH:
+ * the background is a faint tint of the same hue near white, the marker is a tonal
+ * step of the pixel's own tone (same hue and chroma, stepped down the lightness axis)
+ * that stays decode-dark. Both always pass the palette guard.
+ */
+export declare function suggestPalette(pixel: string): {
+    marker: string;
+    background: string;
+};
+export interface PaletteIssue {
+    color: keyof QrPalette;
+    message: string;
+}
+/**
+ * Decoding-safety guard for a user-edited palette: the background must stay light
+ * (the engine's quiet-zone rule counts brightness ≥ 200 as light), every ink must
+ * stay dark, and each ink must separate from the background in OKLCH lightness.
+ * The generated QR's decode round-trip remains the authoritative gate; this reports
+ * early, before a prepare request is spent.
+ */
+export declare function paletteGuard(palette: QrPalette): {
+    ok: boolean;
+    issues: PaletteIssue[];
+};

package/dist/types/core/pattern-cut.d.ts

@@ -0,0 +1,96 @@
+import type { LoadedPng } from './image';
+import type { BoundingBox, Point } from './types';
+/** Default corner fillet radius in poster pixels; matches the placed module pitch. */
+export declare const CUT_RADIUS = 5;
+/** Default Douglas-Peucker tolerance in pixels for the traced outline. */
+export declare const CUT_SMOOTH_TOLERANCE = 3;
+/** Solid black band retained inside the letter outline. */
+export declare const CUT_BORDER_WIDTH = 20;
+/** A mask pixel selects the cut shape when it is transparent or dark. */
+export declare const CUT_KEEP_RULE: 'transparent-or-dark';
+/** Loops below the fillet area are dropped as specks; shared by the cut and assembly reports. */
+export declare function cutMinLoopArea(radius: number): number;
+export interface CutPathStats {
+    loopsTraced: number;
+    loopsKept: number;
+    specksDropped: number;
+    verticesTraced: number;
+    verticesSimplified: number;
+    holes: number;
+    /** Area of the simplified cut polygon before corner rounding. */
+    area: number;
+    /** True when the fillet had to shrink below the requested radius on a narrow feature. */
+    radiusClamped: boolean;
+    bounds: BoundingBox;
+}
+export interface CutPath {
+    d: string;
+    stats: CutPathStats;
+}
+export interface CutPathOptions {
+    /** Corner fillet radius in pixels; defaults to {@link CUT_RADIUS}. */
+    radius?: number;
+    /** Douglas-Peucker tolerance in pixels; defaults to {@link CUT_SMOOTH_TOLERANCE}. */
+    smoothTolerance?: number;
+}
+interface FilletResult {
+    commands: string[];
+    clamped: boolean;
+}
+/**
+ * A mask pixel selects the cut shape when it is transparent or dark, which covers both artifact
+ * conventions: `edit-mask.png` (opaque white outside, transparent inside) and `region-mask.png`
+ * (white inside on black).
+ */
+export declare function buildShapeSelection(mask: LoadedPng): Uint8Array;
+/**
+ * Disc morphology that turns a raw selection into a cuttable outline: a closing (dilate, erode)
+ * fills pinholes and concave nicks, an opening (erode, dilate) drops specks and convex jags. Both
+ * run at the same radius, so a pixel staircase becomes one continuous edge the fillet can round.
+ */
+export declare function cleanMaskSelection(selection: Uint8Array, width: number, height: number, radius: number): Uint8Array;
+/**
+ * Traces the boundary of a binary selection as closed loops along pixel borders. The traversal keeps
+ * the selected pixels on its right, so outer boundaries come out with negative shoelace area and
+ * holes with positive area.
+ */
+export declare function traceMaskContours(selected: Uint8Array, width: number, height: number): Point[][];
+/** Drops the intermediate points of straight runs, leaving only genuine corners. */
+export declare function collapseCollinearPoints(loop: Point[]): Point[];
+/**
+ * Splits a closed loop at its farthest vertex before simplifying, so an open-run simplifier cannot
+ * collapse the whole ring onto its duplicated start and end point.
+ */
+export declare function simplifyClosedLoop(loop: Point[], tolerance: number): Point[];
+export declare function polygonArea(loop: Point[]): number;
+/**
+ * Rounds every corner with a fillet. The tangent distance is capped at half of each neighbouring
+ * edge and the arc radius is recomputed from the capped tangent, so arcs on small features stay
+ * inside the polygon instead of overlapping each other.
+ */
+export declare function filletLoop(loop: Point[], radius: number): FilletResult;
+/** Turns a binary selection into a rounded SVG path plus the statistics the report records. */
+export declare function buildCutPath(selected: Uint8Array, width: number, height: number, options?: CutPathOptions): CutPath;
+export interface CutSvgOptions {
+    /** Black band drawn inside the cut edge, in pixels; zero leaves the edge bare. */
+    borderWidth?: number;
+}
+/** Self-contained SVG: the pattern rides along as a data URI and the cut edge stays vector. */
+export declare function buildCutSvg(pathData: string, width: number, height: number, pattern: Uint8Array, options?: CutSvgOptions): string;
+/**
+ * Rasterizes only the cut path and returns its antialiased coverage: 0 outside the cut shape, 255
+ * inside, and the partial values along the edge that make the fillet smooth.
+ */
+export declare function renderCutCoverage(pathData: string, width: number, height: number): Promise<Uint8Array>;
+/**
+ * Rasterizes the band hugging the inside of the cut edge: a stroke of twice `width` centered on the
+ * path and clipped to the shape, so coverage is 0 outside, roughly half on the boundary itself, and
+ * 255 one border width inside.
+ */
+export declare function renderCutBorderCoverage(pathData: string, width: number, height: number, borderWidth: number): Promise<Uint8Array>;
+/**
+ * Applies the cut coverage without resampling the source. An optional black band is composited
+ * inside the outline; pixels beyond it stay bit-exact and everything outside is transparent.
+ */
+export declare function renderCutPng(pattern: LoadedPng, pathData: string, borderWidth?: number): Promise<Uint8Array>;
+export {};

package/dist/types/core/pattern.d.ts

@@ -0,0 +1,119 @@
+import type { QrCodeGenerateResult } from 'uqr';
+/** Project defaults: ecc 'M', 2-module margin, dot pixel style, auto mask. */
+export declare const PATTERN_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
+export declare const PATTERN_ECC: 'M';
+export declare const PATTERN_PIXEL_STYLE: 'dot';
+export declare const PATTERN_PIXEL_STYLES: readonly ['square', 'rounded', 'dot'];
+export type PixelStyle = (typeof PATTERN_PIXEL_STYLES)[number];
+export declare const PATTERN_MARKER_REFILL: 'seeded-random';
+/** Render ink and light colors; the palette overrides parse as hex. */
+export declare const PATTERN_INK: '#000000';
+export declare const PATTERN_LIGHT: '#ffffff';
+/** Light modules the toolkit draws around the code; the texture's own quiet zone. */
+export declare const PATTERN_QUIET_ZONE_MODULES: 2;
+export interface PatternRenderWindow {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+export interface PatternRenderOptions {
+    /** Background behind rendered modules. Transparent is reserved for ink-only poster overlays. */
+    background?: 'white' | 'transparent';
+    /** Light modules drawn around the matrix; matches the toolkit's default margin of 2. */
+    marginModules?: number;
+    /** Visible sub-rectangle of the full code canvas, in code pixels. */
+    window?: PatternRenderWindow;
+    /**
+     * Draws only the modules this predicate accepts, addressed in code-module coordinates
+     * (`0 .. totalModules - 1`, margin included). A rejected module renders nothing and counts as
+     * light when wedge neighbours are resolved, so the drawn area stays a union of whole modules and
+     * its edge closes on the silhouette. Without it every module is drawn on one white canvas,
+     * exactly as `--pattern-preview` renders.
+     */
+    include?: (moduleX: number, moduleY: number) => boolean;
+    /** Suppresses black geometry for selected cells while retaining the white canvas beneath them. */
+    skipInk?: (moduleX: number, moduleY: number) => boolean;
+    /** Ink color of the dark geometry, replacing the default #000000. */
+    ink?: string;
+    /** Light color for the canvas and light modules, replacing the default #ffffff. */
+    light?: string;
+}
+export interface PosterPatternOptions {
+    /** Poster canvas width in pixels. */
+    width: number;
+    /** Poster canvas height in pixels. */
+    height: number;
+    /** Module pitch in poster pixels. */
+    modulePixels: number;
+    /** Seed for the random text line and the marker refill; defaults to a fresh random seed per run. */
+    seed?: number;
+    /**
+     * Poster-space origin of a module lattice to phase-lock the window to, typically the placed QR box.
+     * The texture's module boundaries then land on the same lattice as the QR's, so the field
+     * continues the code's rhythm. Without it the window stays centered as before.
+     */
+    alignTo?: {
+        x: number;
+        y: number;
+    };
+    /** Pixel shape: square is full cell, rounded blends neighbours, dot is a circle. */
+    pixelStyle?: PixelStyle;
+}
+export interface PosterPattern {
+    png: Uint8Array;
+    seed: number;
+    version: number;
+    text: string;
+    /** Marker-free module matrix, marker cells refilled with seeded random bits. */
+    matrix: boolean[][];
+    qrModules: number;
+    totalModules: number;
+    codeSize: number;
+    marginModules: number;
+    crop: {
+        left: number;
+        top: number;
+    };
+    refilledModules: number;
+}
+/** The generated texture's lattice, its matrix, and how the window sits on it. */
+export type PosterPatternLattice = Omit<PosterPattern, 'png'>;
+/**
+ * Smallest QR version whose modules plus quiet zone cover the canvas at this pitch. A caller that
+ * needs to phase-lock the window (see `alignTo`) asks for one module of headroom, so the code is
+ * wider than the canvas and the window can still be shifted onto the requested lattice.
+ */
+export declare function selectPatternVersion(modulePixels: number, width: number, height: number, headroomPixels?: number): number;
+/** Random text long enough to fill the version's data capacity, so no repeating pad codewords appear. */
+export declare function createPatternText(version: number, seed: number): string;
+/**
+ * Finder patterns and alignment patterns are dropped, then refilled with seeded random bits. Leaving
+ * those cells light would punch a 9x9 (finder) or 5x5 (alignment) white hole into the texture; the
+ * refill keeps the field even. The refill stream is derived from the run seed, so a seed reproduces
+ * the whole pattern.
+ */
+export declare function stripMarkerModules(matrix: QrCodeGenerateResult, seed: number): boolean[][];
+/** Cells the marker refill replaces: the three 9x9 finder areas plus every 5x5 alignment block. */
+export declare function countMarkerModules(matrix: QrCodeGenerateResult): number;
+/**
+ * Renders a pixel style — square is full cells, dot is circles, rounded blends neighbours.
+ * Square and dot use the standard full-cell and circular module styles; rounded uses one
+ * inscribed circle per dark module plus corner wedges that
+ * bridge dark neighbours (and fill inner corners of light modules).
+ */
+export declare function renderPattern(matrix: boolean[][], modulePixels: number, pixelStyle?: PixelStyle, options?: PatternRenderOptions): Promise<Uint8Array>;
+/**
+ * Renders the legacy rounded pixel style: one inscribed circle per dark module plus
+ * corner wedges that bridge dark neighbours (and fill inner corners of light modules).
+ * @deprecated Use renderPattern with explicit pixelStyle instead.
+ */
+export declare function renderRoundedPattern(matrix: boolean[][], modulePixels: number, options?: PatternRenderOptions): Promise<Uint8Array>;
+/**
+ * Renders the poster-sized marker-free texture at a fixed module pitch. The version is the smallest
+ * whose modules plus margin cover the canvas, the code is center-cropped at whole-module offsets,
+ * and the same seed reproduces the same bytes.
+ */
+export declare function buildPosterPattern(options: PosterPatternOptions): Promise<PosterPatternLattice>;
+/** Renders the poster pattern, or just its lattice, in one call. */
+export declare function renderPosterPattern(options: PosterPatternOptions): Promise<PosterPattern>;

package/dist/types/core/placement.d.ts

@@ -0,0 +1,9 @@
+import type { QrBoxInput, QrPlacement, RegionMask } from './types';
+export declare const MINIMUM_MODULE_PIXELS = 4;
+export declare const REGION_TOO_SMALL_MESSAGE = "The painted region cannot fit the QR code at the minimum 4px module size. Supply a larger region or QR position.";
+export declare function placeQr(mask: RegionMask, totalModules: number, requested?: QrBoxInput): QrPlacement;
+export declare function boxIsInsideMask(mask: RegionMask, x: number, y: number, size: number, rotation?: number): boolean;
+export declare function findClosestSquare(mask: RegionMask, size: number): {
+    x: number;
+    y: number;
+};