@gmitch215/tinyimg 1.1.1 → 1.2.0

package/README.md

@@ -172,9 +172,15 @@ half the time. Across twelve JPEGs, milliseconds per megapixel spread 7.1x while
 megabyte spread 1.95x at this scale. The practical rule for a 200 px thumbnail is roughly **480 KB of
 compressed source**, whatever its dimensions.
 
-The estimate `decide()` returns still prices against source samples and is wrong by up to 12.8x for
-that reason, so treat `budgetMs` as a coarse guard rather than a promise. Past the ceiling the
-artifact has to be computed once and cached; see [Caching](#caching).
+`decide().estimateMs` covers decode and resample and leaves the encoder out. On 878 held-out cells
+timed against the v1.1.1 model (one machine, sources with alpha excluded) it ran a median 2.0x under
+the clock, 38.6% of cells landed within 0.6x to 2.0x, and the worst was 10.97x under. Adding the
+encoder, which is what `budgetMs` compares against, moved the median to 1.3x under and 59.8% in
+band, with the worst at 9.04x under (a JPEG source) and 7.44x over (a PNG). AVIF sources were the
+worst group, 3.7% in band. The model in this release prices the compressed bytes as well as the
+samples and carries a calibrated upper bound, described under [Admission](#admission). Treat
+`budgetMs` as a coarse guard with no guarantee behind it. Past the ceiling the artifact has to be computed
+once and cached; see [Caching](#caching).
 
 A progressive JPEG is the exception worth knowing about. At an eighth scale the transform reads the
 DC term alone, so the scans that carry only high-frequency detail are stepped over rather than
@@ -190,13 +196,16 @@ the per-stage profile and the comparison against `@jsquash`.
 
 ### Gaps
 
-- **AVIF encode has no partition search.** Decode is complete and matches `dav1d` exactly. The
+- **AVIF encode has no partition search.** Decode reads AV1 intra. The
   encoder uses fixed 8x8 blocks and picks the luma mode from four candidates by absolute
   difference, so its files run 1.1x to 1.3x libaom's size at matched quality. A partition search is
   where most of AV1's compression lives.
 - **No 10 or 12 bit AVIF.** The reconstruction is 8 bits a sample end to end, so an HDR AVIF is
   refused rather than truncated. 4:2:2 is refused too, for a reason in the format: the
   specification's own subsampled-size table has no answer for a tall block on such a plane.
+- **Some AVIF files are refused rather than decoded wrong.** Film grain, superres, `grid` and
+  `iovl` images, a cropping `clap` aperture, PQ and HLG transfer, and an alpha plane the decoder
+  cannot read each return an unsupported-variant error.
 - **No animation.** Both decode a first frame; neither re-times or composes one.
 - **You own the caching.** Images caches derivatives at the edge as a product feature. tinyimg gives
   you the key and leaves the cache to you; see [Caching](#caching).
@@ -304,11 +313,11 @@ The options apply in a fixed order, exported as `TRANSFORM_ORDER`: crop, resize
 the color adjustments, blur, sharpen, trim. An option object has no order of its own, so two callers
 writing the same keys get the same image.
 
-A JPEG with an EXIF orientation is turned upright before anything else runs, so `width`, `height`,
+A JPEG with an EXIF orientation, or an AVIF with `irot` and `imir` properties, is turned upright before anything else runs, so `width`, `height`,
 `crop` and `fit` all read the image as displayed. A phone photo stored landscape and tagged 90
 degrees comes out portrait, and a request for 400 wide is a portrait 400 wide. `probe` reports the
 tag as `orientation`, and the chainable API applies it with `Image.autoOrient()`, which has to be
-the first operation. Only JPEG reports it; every other format reports 1.
+the first operation. Only JPEG and AVIF report it; every other format reports 1.
 
 ### Fit Modes
 
@@ -357,6 +366,11 @@ it, call `dispose()` in a `finally`. Encoding does not consume the plan.
 
 `pixels()` hands back the raw samples for a caller who wants them rather than a container.
 
+`edit(fn)` runs after the plan, like `trim` and `rotateFree`, and hands `fn` the materialized image as
+RGBA to change in place. It is for per-pixel arithmetic the library does not carry, such as another
+library's exact blend or a fixed convolution kernel. The extent and channel count cannot change, and
+the view is valid only inside the call.
+
 ## The Planner
 
 Nothing runs until the output is asked for. Operations append to a fixed-capacity list, and the plan
@@ -396,13 +410,19 @@ On that chain the planner is worth 3.63x against running the same operations one
 | ------ | ------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
 | PNG    | 8 and 16 bit, gray/palette/truecolor with and without alpha, Adam7              | hash-chain LZ77, static and dynamic Huffman, the five filters     |
 | JPEG   | baseline and progressive, 4:4:4 / 4:2:2 / 4:2:0, CMYK and YCCK, restart markers | quality-scaled tables, optimized Huffman, progressive scan script |
-| WebP   | VP8 lossy and VP8L lossless                                                     | both modes                                                        |
+| WebP   | VP8 lossy and VP8L lossless                                                     | both modes, alpha kept through an `ALPH` chunk when lossy         |
 | GIF    | LZW, local and global palettes, interlace, transparency                         | median-cut palette with Floyd-Steinberg dithering                 |
 | TIFF   | strips, uncompressed / PackBits / LZW / Deflate, both byte orders               | uncompressed and PackBits                                         |
 | BMP    | uncompressed and RLE8                                                           | uncompressed                                                      |
 | AVIF   | AV1 intra: every transform, all 13 intra modes, deblock and CDEF                | fixed 8x8 partitions, no rate-distortion search                   |
 | HEIF   | container only; `probe` answers and decode reports a specific error             | no                                                                |
 
+A lossy WebP with transparency is written as a `VP8X` header, an `ALPH` chunk holding the alpha plane
+as a lossless stream, and the lossy frame, so alpha is exact at any `quality`; an image whose alpha
+is all 255 gets the plain frame. The JPEG and AVIF encoders write no alpha, and GIF keeps one bit of
+it. When a `transform` output has transparency its format cannot carry, `degraded` contains
+`'alpha'`.
+
 JPEG carries true DCT-domain scaled decode at 1/2, 1/4 and 1/8, and region decode that Huffman-scans
 past blocks outside the box without transforming them. PNG, GIF, TIFF and BMP row-skip and
 column-skip.
@@ -732,9 +752,9 @@ const result = await transform(tinyimg, source, {
 result.format; // 'webp' if it fits inside 7 ms, otherwise 'jpeg'
 ```
 
-A format you name is never substituted, however far over budget it is. The estimate is accurate to
-about 20% on the machine its rates were measured on, so give a budget below the limit rather than at
-it, and use [`measure`](#work-counters) when you need what a request cost.
+A format you name is never substituted, however far over budget it is. On the machine its rates were
+measured on, the estimate's median decode error on images held out of the fit is within 10% for every
+format except TIFF (54% under), the encoder is priced separately, and single requests spread wider, so give a budget below the limit rather than at it, and use [`measure`](#work-counters) when you need what a request cost.
 
 **A budget the container change cannot meet degrades the plan, and the result says what it gave up.**
 Container first, because a cheaper encoder costs bytes and nothing else; then the planner's own
@@ -767,6 +787,108 @@ The output extent never changes. A budget decides how the pixels are made, not h
 is degraded when the estimate already fits. `degraded` is empty on a pass-through, which needs no
 lever at all.
 
+### Admission
+
+Naming `admission` beside `budgetMs` turns the budget into a decision on the calibrated upper bound
+instead of the point estimate. `'strict'` throws `TinyImgBudgetError`, carrying the numbers, when the
+bound plus the encoder is over budget, and gives nothing up. `'degrade'` takes the ladder above,
+judged on the bound, and runs the cheapest request that results. `'passthrough'` degrades the same
+way and returns the source bytes unchanged, with `'passthrough'` in `degraded`, when no rung fits;
+that needs the output format to be the source's own, or none asked for.
+
+```ts
+const result = await transform(tinyimg, source, {
+  width: 200,
+  budgetMs: 10,
+  admission: 'passthrough',
+  platformScale: 1.9
+});
+```
+
+An admitted request also stops itself. The module sums the work its decoders and encoders have
+counted into a work clock, a function of the counters and not of a timer, because a Worker's timers
+do not advance during CPU work. When the clock passes the budget, the operation returns
+`TINYIMG_ERR_BUDGET`, which `transform` throws as `TinyImgBudgetError`, or answers with the source
+under `'passthrough'`. `Image.admit(budgetMs, options)` returns the decision without running
+anything.
+
+The bound is a calibrated prediction under exchangeability, not a guarantee. It is relative to the
+machine the cost model was timed on, so `platformScale` carries your own factor; a Worker ran the same
+module 1.9x slower at the median and 2.4x to 4.7x slower on cheap requests, and the library applies
+none. Leaving `admission` unset keeps `budgetMs` exactly as described above.
+
+How it held on 423 requests the model never saw, at five budgets from 5 to 100 ms (2,115 request and
+budget pairs, timed on the Apple M2 Pro the model was calibrated on): the bound admitted 739 pairs
+and 67 of them, 9.07%, ran over budget. The v1.1.1 estimate admitted 1,174 and 451 of them, 38.42%,
+ran over, so the bound admits with 6.73x fewer overruns. It misses the 5% overrun rate set for it
+before the run, so use it as a filter and not as a limit. AVIF sources are the weak spot: 26 of the
+32 pairs admitted for them ran over. The other formats together ran over on about 6%. The bound also
+refuses requests that fit, 7.31% of the pairs that did (WebP sources 33.9%). The test left out
+sources with alpha, and lossy WebP with alpha and TIFF encode are priced less tightly (held-out
+coverage 0.82 and 0.89). The tables are in `bench/baselines/v1.2/admission-summary.md`.
+
+### Selection
+
+`Image.select(options)` searches the decode levers (scale, filter, effort), the output format and its
+quality together, drops each combination that breaks a limit, and returns the best of the rest. It
+reads no pixels and no clock. `Image.bytesFor(selection)` runs the choice and returns the encoded bytes.
+
+```ts
+using image = await Image.open(tinyimg, source);
+image.resize(400, 300);
+
+const selection = image.select({ budgetMs: 20, platformScale: 1.9, minDb: 35 });
+
+if (selection.feasible) {
+  const bytes = await image.bytesFor(selection);
+  // serve bytes as selection.choice.format
+} else {
+  // selection.reason names the check the nearest miss failed
+}
+```
+
+| Option            | Default                         | Meaning                                                           |
+| ----------------- | ------------------------------- | ----------------------------------------------------------------- |
+| `budgetMs`        | no limit                        | CPU the request may spend, judged on the calibrated upper bound   |
+| `platformScale`   | `1`                             | How much slower your machine is than the calibrated one           |
+| `peakBytes`       | the module's heap ceiling       | Largest heap bound a candidate may have                           |
+| `minDb`           | no floor                        | Predicted PSNR against the undegraded output, in dB               |
+| `formats`         | the source's own, JPEG and WebP | Output containers to consider                                     |
+| `objective`       | `'bytes'`                       | `'bytes'`, `'time'` or `'quality'`, among the candidates that fit |
+| `uncharacterized` | `'refuse'`                      | `'allow'` keeps a candidate whose quality is unknown              |
+| `assumeOpaque`    | `false`                         | Treat an RGBA source as opaque, so JPEG, AVIF and GIF qualify     |
+
+A `Selection` carries `feasible`, `reason`, `choice` (format, quality, whether it is lossless, the
+lattice position `bytesFor` runs, and the predicted upper-bound cost, peak heap, dB and bytes), the
+output `width` and `height`, whether the source counted as having `alpha`, the measured `coverage` of
+each table, and every candidate in `considered` with the check that removed it. An infeasible
+selection is a normal answer.
+
+On the held-out test images at 10, 20 and 50 ms, with and without a 35 dB floor, the joint search
+served 37.8% of 1,137 requests, the planner's own ladder 17.2% and format-and-quality chosen
+independently 33.8%. Against independent choice the gain is 4 points, interval 3.0 to 5.1, and all of
+it comes from requests without a quality floor. The tables are in
+`bench/baselines/v1.2/selector-summary.md`.
+
+The predictions come from tables measured on other images, so each one has a stated reach:
+
+- **`db` is a table percentile.** It composes the fifth percentile of the decode lever with the fifth
+  percentile of the encoder. On images held out of the fit the lever table's percentile held for
+  89.3% of cells (WebP sources 64.5%) and the encode table's for 94.8%, against a 95% target. Read it
+  as a likely floor, not a guarantee; `coverage` reports the figure for your source and format.
+- **`bytes` is a median over 99 opaque images.** On the images the table was fitted on, it ordered
+  two formats at the same quality tier correctly in 93.5% of pairs. It cannot say how large this
+  image will be: measured bytes over predicted ran from 0.32 to 0.58 at the fifth percentile and
+  1.27 to 1.84 at the 95th, by format, at quality 75.
+- **Alpha is priced pessimistically.** The tables come from opaque images, so `db` is low and `bytes`
+  leaves out the alpha plane. An RGBA source cannot go to JPEG, AVIF or GIF unless `assumeOpaque` is
+  set, and the planner cannot see whether the pixels are opaque.
+- **Lossless TIFF, BMP and WebP outputs have no quality class.** Their error is unmeasured, so
+  `'refuse'` drops them, and asking for `formats: ['tiff']` or `['bmp']` returns an infeasible
+  selection with reason `'uncharacterized'`. A TIFF or BMP source can still go to JPEG or WebP.
+  `uncharacterized: 'allow'` keeps the unclassified candidates with an unknown `db`, which cannot
+  satisfy a `minDb`.
+
 ## Caching
 
 A cache hit costs no CPU at all, which is how a request too expensive to serve synchronously still
@@ -799,6 +921,9 @@ const { work } = await tinyimg.measure(() => transform(tinyimg, source, { width:
 work.samplesPerTransform; // 1 at an eighth scale, 4 at a quarter, 64 at full
 work.decodedSamples / work.sourceSamples; // what the reduction was worth
 work.filtered; // macroblocks a region did not skip
+work.entropyBytes; // compressed bytes the decoder read, which a region or progressive 1/8 lowers
+work.encodeProbes; // match candidates a PNG encode compared, the cost `encoded` cannot see
+work.alphaDropped; // samples whose alpha a JPEG, AVIF or GIF encode wrote without it
 ```
 
 `samplesPerTransform` is the one to read for a scaled decode: a decode transforming whole blocks and

package/dist/image.d.ts

@@ -1,5 +1,44 @@
-import { type Color, type Fit, type FlipAxis, type Gravity, type ImageFormat, type PlanDecision, type RawImage, type ResampleFilter, type Source } from './types.js';
+import { type Admission, type Color, type Fit, type FlipAxis, type Gravity, type ImageFormat, type PlanDecision, type RawImage, type ResampleFilter, type Selection, type Source } from './types.js';
 import { TinyImgModule } from './wasm.js';
+/** What {@link Image.admit} takes beyond the budget. */
+export interface AdmitOptions {
+    /**
+     * `'degrade'` walks the budget ladder on the upper bound before it rejects; `'strict'` rejects
+     * a request that is over as it stands. Defaults to `'degrade'`.
+     */
+    mode?: 'strict' | 'degrade';
+    /** The container the result is written as, which prices the encoder. Defaults to the source's. */
+    format?: ImageFormat;
+    /** How much slower this machine is than the calibrated one. Defaults to 1. */
+    platformScale?: number;
+    /** The encoder's quality, which moves its price for JPEG, WebP and AVIF. */
+    quality?: number;
+    /** Whether WebP is written lossless, which is dearer to encode. */
+    lossless?: boolean;
+    /** The encoder's compression level for PNG and TIFF. Defaults to `'auto'`. */
+    compression?: EncodeOptions['compression'];
+    /** The encoder's effort. Defaults to `'fancy'`. */
+    effort?: 'fancy' | 'fast';
+}
+/** What {@link Image.select} takes. */
+export interface SelectOptions {
+    /** CPU the request may spend, in milliseconds on the machine it runs on. Omitted means no limit. */
+    budgetMs?: number;
+    /** How much slower this machine is than the calibrated one. Defaults to 1. */
+    platformScale?: number;
+    /** Largest heap bound a candidate may have, in bytes. Defaults to the module's heap ceiling. */
+    peakBytes?: number;
+    /** Quality floor as predicted PSNR in dB against the undegraded output. Omitted means no floor. */
+    minDb?: number;
+    /** Output containers to consider. Defaults to the source's own, JPEG and WebP. */
+    formats?: ImageFormat[];
+    /** What to minimize among the candidates that fit. Defaults to `'bytes'`. */
+    objective?: 'bytes' | 'time' | 'quality';
+    /** What to do with a candidate whose quality is unknown. Defaults to `'refuse'`. */
+    uncharacterized?: 'refuse' | 'allow';
+    /** Treat an RGBA source as opaque, so the search may pick JPEG, AVIF or GIF. */
+    assumeOpaque?: boolean;
+}
 /** What {@link Image.bytes} and its siblings take. */
 export interface EncodeOptions {
     /** Quality for a lossy format, 1 through 100. */
@@ -138,12 +177,13 @@ export declare class Image {
     /** Mirrors along one axis or both. */
     flip(axis?: FlipAxis): this;
     /**
-     * Turns the source upright by the orientation its EXIF names.
+     * Turns the source upright by the orientation its EXIF (JPEG) or its `irot` and `imir`
+     * properties (AVIF) name.
      *
      * The decoder returns pixels as stored and a plan's output carries no EXIF block, so an image
      * tagged as rotated would otherwise come out sideways. This appends the flip and turn that
      * orientation stands for, which fold into the output addressing like any other, so it costs no
-     * pass. A source with no tag, and every format but JPEG, appends nothing.
+     * pass. A source with no tag, and every format but JPEG and AVIF, appends nothing.
      *
      * Call it before any other operation: a crop or resize after it works in display coordinates,
      * and one before it would not.
@@ -170,6 +210,18 @@ export declare class Image {
      * @param tolerance How far a pixel may differ from the border color and still be trimmed.
      */
     trim(tolerance?: number): this;
+    /**
+     * Changes the materialized pixels in place, with a function of your own.
+     *
+     * **Runs after the plan rather than inside it.** The escape hatch for per-pixel arithmetic the
+     * library does not carry, such as another library's exact integer blend or a fixed convolution
+     * kernel. The image is widened to RGBA first, so `fn` always sees four channels, and it gets a
+     * live view into the module's memory: write to `pixels` and the encoder reads what you wrote.
+     * The extent and the channel count cannot change, and the view is only valid inside the call.
+     *
+     * @param fn Receives the extent and `width * height * 4` bytes, rows tightly packed.
+     */
+    edit(fn: (image: RawImage) => void): this;
     /** Scales every channel. 1 is unchanged. */
     brightness(factor: number): this;
     /** Scales every channel about mid gray. 1 is unchanged. */
@@ -266,8 +318,43 @@ export declare class Image {
      * {@link transform}, which does that for you.
      *
      * @param milliseconds The budget, or 0 to remove it.
+     * @param basis Which cost the ladder compares to the budget. `'point'`, the default, is the
+     * estimate; `'upper'` is the calibrated upper bound, so a rung that fits is one whose bound
+     * fits.
+     */
+    budget(milliseconds: number, basis?: 'point' | 'upper'): this;
+    /**
+     * Decides whether this request fits a CPU budget, on the calibrated upper bound.
+     *
+     * Prices the plan undegraded, adds the encoder for the format being written, and multiplies by
+     * `platformScale`. The request is admitted when that bound is within `budgetMs`. In the default
+     * `'degrade'` mode an over-budget request walks the planner's ladder on the bound and is
+     * `'degraded'` when a rung fits and `'reject'` when none does; `'strict'` rejects without
+     * trying. The plan's own {@link budget} is not read and not changed.
+     *
+     * The bound is a prediction under exchangeability, not a guarantee, and it is relative to the
+     * machine the cost model was calibrated on.
+     *
+     * @param budgetMs CPU the request may spend, in milliseconds on the machine it runs on.
+     * @param options The mode, the output format, the machine factor and the encoder's settings.
+     * @return The decision and the numbers behind it.
      */
-    budget(milliseconds: number): this;
+    admit(budgetMs: number, options?: AdmitOptions): Admission;
+    /**
+     * Searches the ways to run this request and picks the best one that fits the limits.
+     *
+     * Crosses the planner's decode levers (scale, filter, effort) with the output format and its
+     * quality, drops each combination that breaks a limit, and takes the best by `objective`. It
+     * reads no pixels and no clock, so it costs a few table lookups per candidate. Run the choice
+     * with {@link bytesFor}.
+     *
+     * The limits are the options', not the plan's own {@link budget}. A selection with `feasible`
+     * false is a normal answer: `reason` names the check the nearest miss failed.
+     *
+     * @param options The limits and the objective.
+     * @return The choice, the predicted figures behind it and every candidate looked at.
+     */
+    select(options?: SelectOptions): Selection;
     /**
      * Runs the plan and encodes the result.
      *
@@ -279,6 +366,19 @@ export declare class Image {
      * @return The encoded bytes.
      */
     bytes(format?: ImageFormat, options?: EncodeOptions): Promise<Uint8Array<ArrayBuffer>>;
+    /**
+     * Runs the plan the way a {@link select} chose and encodes it as that choice says.
+     *
+     * Decodes at the lattice point the selection names (its scale, filter and effort) and writes
+     * the format, quality and coding it names. `options` supplies the settings the selection does
+     * not carry: `progressive`, `stripMetadata`, `effort` and `compression`. The selection has to
+     * come from this image, with no operation added since.
+     *
+     * @param selection A feasible selection from {@link select}.
+     * @param options Encoder settings other than quality and lossless.
+     * @return The encoded bytes.
+     */
+    bytesFor(selection: Selection, options?: Omit<EncodeOptions, 'quality' | 'lossless'>): Promise<Uint8Array<ArrayBuffer>>;
     /**
      * Runs the plan and hands back the raw samples.
      *

package/dist/image.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../src/ts/image.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../src/ts/image.ts"],"names":[],"mappings":"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"}

package/dist/image.js

@@ -72,13 +72,69 @@ const Field = {
     passes: 14,
     kernels: 15,
     cost: 16,
-    degraded: 17
+    degraded: 17,
+    costUpper: 18
 };
 const DEGRADES = [
     [1 << 0, 'effort'],
     [1 << 1, 'filter'],
     [1 << 2, 'scale']
 ];
+const DECISIONS = ['admit', 'degraded', 'reject'];
+const AdmissionField = {
+    decision: 0,
+    degraded: 1,
+    cost: 2,
+    costUpper: 3,
+    encode: 4,
+    encodeUpper: 5,
+    margin: 6
+};
+const SELECT_REASONS = [
+    'none',
+    'format',
+    'alpha',
+    'uncharacterized',
+    'peak',
+    'quality',
+    'budget'
+];
+const OBJECTIVES = ['bytes', 'time', 'quality'];
+const SelectionField = {
+    feasible: 0,
+    reason: 1,
+    candidate: 2,
+    format: 3,
+    quality: 4,
+    lossless: 5,
+    costUpper: 6,
+    peak: 7,
+    dbMilli: 8,
+    dbMedianMilli: 9,
+    dbKnown: 10,
+    bytesPerPixelMicro: 12,
+    bytesKnown: 13,
+    predictedBytes: 14,
+    considered: 15,
+    width: 17,
+    height: 18,
+    alpha: 20,
+    leverCoverage: 21,
+    encodeCoverage: 23,
+    chosen: 24
+};
+const ConsideredField = {
+    format: 1,
+    quality: 2,
+    lossless: 3,
+    reason: 4,
+    dbMilli: 6,
+    dbKnown: 7,
+    bytesPerPixelMicro: 8,
+    bytesKnown: 9,
+    costUpper: 10,
+    peak: 11
+};
 export const COMPRESSION = ['auto', 'none', 'fast', 'default', 'best'];
 export class Image {
     #module;
@@ -186,6 +242,25 @@ export class Image {
         });
         return this;
     }
+    edit(fn) {
+        this.#alive();
+        this.#after.push((image) => {
+            const module = this.#module;
+            module.check(module.exports.tiny_image_convert_channels(image, 4), 'widen to RGBA');
+            const width = module.exports.tiny_image_getwidth(image);
+            const height = module.exports.tiny_image_getheight(image);
+            const data = module.exports.tiny_image_getdata(image);
+            fn({
+                width,
+                height,
+                channels: 4,
+                pixels: module
+                    .bytes()
+                    .subarray(data, data + width * height * 4)
+            });
+        });
+        return this;
+    }
     brightness(factor) {
         return this.#append(this.#module.exports.tiny_plan_brightness(this.#plan, factor), 'brightness');
     }
@@ -272,6 +347,7 @@ export class Image {
                 passes: field('passes'),
                 kernels: KERNELS.filter(([bit]) => (bits & bit) !== 0).map(([, name]) => name),
                 estimateMs: field('cost') / 1000,
+                costUpperMs: field('costUpper') / 1000,
                 degraded: DEGRADES.filter(([bit]) => (field('degraded') & bit) !== 0).map(([, name]) => name)
             };
         }
@@ -279,12 +355,126 @@ export class Image {
             module.free(resolution);
         }
     }
-    budget(milliseconds) {
+    budget(milliseconds, basis = 'point') {
         this.#alive();
         this.#module.check(this.#module.exports.tiny_plan_set_budget(this.#plan, Math.max(0, Math.round(milliseconds * 1000))), 'budget setting');
+        this.#module.check(this.#module.exports.tiny_plan_set_budget_basis(this.#plan, basis === 'upper' ? 1 : 0), 'budget basis setting');
         return this;
     }
+    admit(budgetMs, options = {}) {
+        this.#alive();
+        const module = this.#module;
+        const format = options.format ?? this.#format;
+        const opts = module.alloc(module.exports.tiny_admit_opts_sizeof());
+        const out = module.alloc(module.exports.tiny_admission_sizeof());
+        try {
+            const view = module.view();
+            const values = [
+                Math.min(0xffffffff, Math.max(0, Math.round(budgetMs * 1000))),
+                Math.min(0xffffffff, Math.max(1, Math.round((options.platformScale ?? 1) * 1000))),
+                options.mode === 'strict' ? 0 : 1,
+                format === 'unknown' ? 0 : module.formatId(format),
+                COMPRESSION.indexOf(options.compression ?? 'auto'),
+                options.quality ?? 0,
+                options.lossless ? 1 : 0,
+                options.effort === 'fast' ? 1 : 0
+            ];
+            values.forEach((value, index) => view.setUint32(opts + index * 4, value, true));
+            module.check(module.exports.tiny_plan_admit(this.#plan, opts, out), 'admit the plan');
+            const field = (name) => module.exports.tiny_admission_field(out, AdmissionField[name]);
+            return {
+                decision: DECISIONS[field('decision')] ?? 'reject',
+                costMs: field('cost') / 1000,
+                costUpperMs: field('costUpper') / 1000,
+                encodeMs: field('encode') / 1000,
+                encodeUpperMs: field('encodeUpper') / 1000,
+                marginMs: (field('margin') | 0) / 1000,
+                degraded: DEGRADES.filter(([bit]) => (field('degraded') & bit) !== 0).map(([, name]) => name)
+            };
+        }
+        finally {
+            module.free(out);
+            module.free(opts);
+        }
+    }
+    select(options = {}) {
+        this.#alive();
+        const module = this.#module;
+        const opts = module.alloc(module.exports.tiny_select_opts_sizeof());
+        const out = module.alloc(module.exports.tiny_selection_sizeof());
+        try {
+            const view = module.view();
+            const mask = (options.formats ?? []).reduce((bits, format) => bits | (1 << module.formatId(format)), 0);
+            const u32 = (value) => Math.min(0xffffffff, Math.max(0, Math.round(value)));
+            const objective = OBJECTIVES.indexOf(options.objective ?? 'bytes');
+            if (objective < 0)
+                throw new TypeError(`'${options.objective}' is not an objective`);
+            view.setUint32(opts, u32((options.budgetMs ?? 0) * 1000), true);
+            view.setUint32(opts + 4, u32(Math.max(1, (options.platformScale ?? 1) * 1000)), true);
+            view.setUint32(opts + 8, u32(options.peakBytes ?? 0), true);
+            view.setFloat32(opts + 12, options.minDb ?? 0, true);
+            view.setUint32(opts + 16, mask >>> 0, true);
+            view.setUint32(opts + 20, objective, true);
+            view.setUint32(opts + 24, options.uncharacterized === 'allow' ? 1 : 0, true);
+            view.setUint32(opts + 28, options.assumeOpaque ? 1 : 0, true);
+            module.check(module.exports.tiny_plan_select(this.#plan, opts, out), 'select');
+            const field = (name) => module.exports.tiny_selection_field(out, SelectionField[name]);
+            const width = field('width');
+            const height = field('height');
+            const read = (index) => {
+                const part = (name) => module.exports.tiny_selection_considered_field(out, index, ConsideredField[name]);
+                return {
+                    format: module.formatName(part('format')),
+                    quality: part('quality'),
+                    lossless: part('lossless') !== 0,
+                    reason: SELECT_REASONS[part('reason')] ?? 'none',
+                    costUpperMs: part('costUpper') / 1000,
+                    peakBytes: part('peak'),
+                    db: part('dbKnown') ? part('dbMilli') / 1000 : undefined,
+                    bytes: part('bytesKnown')
+                        ? Math.round((part('bytesPerPixelMicro') / 1e6) * width * height)
+                        : undefined
+                };
+            };
+            const considered = Array.from({ length: field('considered') }, (_, index) => read(index));
+            const feasible = field('feasible') !== 0;
+            return {
+                feasible,
+                reason: SELECT_REASONS[field('reason')] ?? 'none',
+                choice: feasible
+                    ? {
+                        ...considered[field('chosen')],
+                        candidate: field('candidate'),
+                        dbMedian: field('dbKnown') ? field('dbMedianMilli') / 1000 : undefined,
+                        ...(field('bytesKnown') ? { bytes: field('predictedBytes') } : {})
+                    }
+                    : undefined,
+                width,
+                height,
+                alpha: field('alpha') !== 0,
+                coverage: {
+                    lever: field('leverCoverage') / 1000,
+                    encode: field('encodeCoverage') / 1000
+                },
+                considered
+            };
+        }
+        finally {
+            module.free(out);
+            module.free(opts);
+        }
+    }
     async bytes(format, options = {}) {
+        return this.#encode(format, options);
+    }
+    async bytesFor(selection, options = {}) {
+        const choice = selection.choice;
+        if (!selection.feasible || !choice) {
+            throw new TypeError(`the selection is not feasible (${selection.reason}), so there is nothing to run`);
+        }
+        return this.#encode(choice.format, { ...options, quality: choice.quality, lossless: choice.lossless }, choice.candidate);
+    }
+    #encode(format, options, lattice) {
         this.#alive();
         const target = format ?? this.#format;
         if (target === 'unknown') {
@@ -303,11 +493,11 @@ export class Image {
         try {
             module.check(module.exports.tiny_writer_init(writer, 0), 'prepare the encoder');
             try {
-                if (this.#after.length === 0) {
+                if (this.#after.length === 0 && lattice === undefined) {
                     module.check(module.exports.tiny_plan_encode(this.#plan, module.formatId(target), opts, writer), 'run and encode');
                 }
                 else {
-                    this.#runWithAfter(target, opts, writer);
+                    this.#runWithAfter(target, opts, writer, lattice);
                 }
                 return module.copyOut(module.exports.tiny_writer_data(writer), module.exports.tiny_writer_size(writer));
             }
@@ -384,11 +574,13 @@ export class Image {
         this.#module.check(result, `append a ${what}`);
         return this;
     }
-    #runWithAfter(target, opts, writer) {
+    #runWithAfter(target, opts, writer, lattice) {
         const module = this.#module;
         const image = module.alloc(module.exports.tiny_image_sizeof());
         try {
-            module.check(module.exports.tiny_plan_run(this.#plan, image), 'run the plan');
+            module.check(lattice === undefined
+                ? module.exports.tiny_plan_run(this.#plan, image)
+                : module.exports.tiny_plan_run_lattice(this.#plan, lattice, image), 'run the plan');
             try {
                 for (const step of this.#after)
                     step(image);