fundus 0.22.1 → 0.23.0

package/README.md

@@ -85,6 +85,52 @@ pixel ratio) plus a ready-made CSS `aspect-ratio` value. For the 3-slice modes
 the sliced-off cross axis must be laid out at exactly that size so the end caps
 keep their authored aspect ratio.
 
+For an existing canvas, preload the manifest and use the synchronous drawing
+helpers. Both accept a canvas element or its 2D context:
+
+```ts
+import { drawImage, drawSlice } from 'fundus';
+import { main } from '$lib/fundus/main.generated';
+
+await main.preload();
+
+// Set up the backing store once; resizing a canvas clears its contents.
+const width = 640;
+const height = 360;
+const dpr = window.devicePixelRatio || 1;
+canvas.width = Math.round(width * dpr);
+canvas.height = Math.round(height * dpr);
+canvas.style.width = `${width}px`;
+canvas.style.height = `${height}px`;
+const ctx = canvas.getContext('2d')!;
+ctx.setTransform(canvas.width / width, 0, 0, canvas.height / height, 0, 0);
+
+drawSlice(ctx, main.dialogFrame, 20, 30, 300, 180);
+drawImage(ctx, main.logo, 40, 50, 120, 60);
+
+// Release when finished with the assets, after the last draw or animation frame.
+main.release();
+```
+
+`x`, `y`, `width`, and `height` use the context's current coordinate system;
+with the setup above they are CSS pixels, and `(x, y)` is the top-left corner.
+Fundus never applies an extra canvas DPR multiplier. A slice's asset
+`pixelRatio` determines its fixed logical borders (a 20-source-pixel border
+at @2x becomes 10 logical pixels), without changing the requested box size.
+Images have no asset pixel-ratio metadata and stretch to the explicit target size.
+Slice coordinates describe the element core; baked-in overdraw paints outside it.
+
+The helpers preserve existing canvas contents and context state, including
+transforms, clipping, alpha, compositing, and image smoothing. Slice painting
+shares the component's geometry and drawing routine; the caller controls the
+backing store and transforms, so fractional pixel placement can antialias cell
+edges. Use integer backing-pixel boundaries when crisp slice edges matter.
+Non-positive sizes are no-ops; non-finite coordinates throw. For non-empty draws,
+missing decoded sources throw with a preload hint, including during preload,
+after the last manifest releases them, or when decoding was disabled. Keep a
+preloaded manifest held for render loops. Image preloading retains its
+decoded element until release. The `<Slice>` component still loads automatically.
+
 For changes made outside the editor:
 
 ```bash
@@ -100,8 +146,8 @@ modules. With the default config, those live in `fundus.config.ts`, `assets/`,
 
 | Type             | Processing                                       | Runtime                                 |
 | ---------------- | ------------------------------------------------ | --------------------------------------- |
-| Image            | WebP, PNG, AVIF, or JPEG; optional width         | `<Image>`                               |
-| Slice            | 1-, 3-, or 9-slice; optional stretch compression | `<Slice>`                               |
+| Image            | WebP, PNG, AVIF, or JPEG; optional width         | `<Image>`, `drawImage()`                |
+| Slice            | 1-, 3-, or 9-slice; optional stretch compression | `<Slice>`, `drawSlice()`                |
 | Video            | H.264 MP4; optional width cap                    | `<Video>`                               |
 | Chroma-key video | H.264 MP4 with WebGL2 keying, mask, and fallback | `<ChromaKeyVideo>`                      |
 | Audio            | Opus/WebM or AAC/M4A                             | Your audio engine via `audioSourceOf()` |