bookcover-web 0.18.0 → 0.20.0

package/README.md

@@ -64,7 +64,7 @@ To self-host instead, serve the same layout under any prefix on your origin:
   for the renderer). Without a bundler, copy them from `node_modules` into your `public/` dir.
 - **`<assets_prefix>/frames/`** — `painted.png` and `torn.png`, copied from the repo's
   `assets/frames/`. (`backgrounds/` is only needed if your UI offers the suggested
-  background images.)
+  background images — see below.)
 - **`<fonts_prefix>/`** — the fonts tree (`manifest.json`, one dir per family, Noto fallbacks
   under `_noto/`). Generate it with the repo's font config:
 
@@ -74,12 +74,34 @@ To self-host instead, serve the same layout under any prefix on your origin:
   ```
 
 
+### Built-in backgrounds
+
+A built-in background's filename (e.g. `beach.jpg`) is its ID — the embed protocol sends a built-in
+as `bg_image_builtin` with no bytes. Join it onto any of these to fetch a copy:
+
+- `https://assets.paper.bible/backgrounds/<name>` — the original (2.8MB on average), for final
+  output
+- `https://assets.paper.bible/backgrounds/previews_2700/<name>` (`BG_PREVIEW_DIR`) — ~380KB,
+  enough for on-screen previews of a 6x9" cover
+- `https://assets.paper.bible/backgrounds/previews_800/<name>` — large thumbnails
+- `https://assets.paper.bible/backgrounds/thumbnails/<name>` — 160x120 picker tiles
+
+Pass the filename to `generate()` as `image_builtin` whichever copy you render, so the automatic
+text colors come from its baked color data and a preview matches the final output exactly.
+`get_builtin_bg_regions(name)` returns the same data, and `get_builtin_bg(name)` adds the
+original's pixel size (for resolution checks without downloading it).
+
+
 ## `CoverGenerator.generate(options): Promise<GenerateResult>`
 
 ```ts
 interface GenerateOptions {
     schema: unknown               // raw schema (see above)
     image?: Blob                  // background image
+    // Filename of the built-in background `image` is a copy of — colors come from its baked data
+    image_builtin?: string
+    // Shrink `image` to at most this many pixels per inch of cover before compiling (previews)
+    image_max_dpi?: number
     format?: 'pdf'|'svg'|'png'   // default: 'pdf'
     ppi?: number                  // PNG resolution, default: 144
     split?: boolean               // include split panels in result

package/dist/embed_types.d.ts

@@ -85,7 +85,8 @@ export type HostMessage = InitMessage | {
     id: string;
     bg_image: File | null;
 };
-/** Widget -> host. `bg_image` rides on every data/finished message (cloning a File is cheap);
+/** Widget -> host. `bg_image` and `bg_image_builtin` ride on every data/finished message
+ *  (cloning a File is cheap), at most one of them non-null;
  *  `custom_fonts` byte arrays are expensive to clone, so on 'data' messages the field is only
  *  present when the font set changed since the last message (absent = unchanged), while
  *  'finished' always carries the complete array.
@@ -98,17 +99,18 @@ export type HostMessage = InitMessage | {
  *  InitMessage.custom_fonts for the rule, and font_families_in_form in bookcover-core for the
  *  applied set).
  *
- *  `bg_image_builtin` is ADVISORY background identity, so a host doesn't have to recover it by
- *  hashing returned bytes: when the user picks one of the widget's built-in backgrounds it
- *  carries that image's published filename, and it is null for a user upload or no image at all.
- *  The filename IS the id — hosts join it onto their own assets path to get the bytes and slice
- *  its extension off for the MIME type, so it must stay a filename (see the contract on
- *  BACKGROUNDS in the widget's services/backgrounds.ts). It exists purely so the host can store a
- *  reference instead of a private copy of a shipped image. Treat it as untrusted input — map it
- *  to a built-in only after checking it against your own allowlist, and fall back to the upload
- *  path otherwise. Nothing in bookcover ever resolves bytes from this field.
+ *  `bg_image_builtin` IS the background when the user picked one of the widget's built-ins: it
+ *  carries that image's published filename and `bg_image` is null. It is null for an upload or
+ *  no image at all. The filename IS the id — hosts join it onto their own assets path to get the
+ *  bytes (`backgrounds/<name>` for the original, BG_PREVIEW_DIR for a preview-sized copy) and
+ *  slice its extension off for the MIME type, so it must stay a filename (see the contract on
+ *  BACKGROUNDS in the widget's services/backgrounds.ts). Pass it to generate() as image_builtin
+ *  so colors come from the baked table whichever copy is rendered. Treat it as untrusted input
+ *  — map it to a built-in only after checking it against your own allowlist. A name that fails
+ *  that check comes with no bytes to fall back on, so keep the cover's existing background
+ *  rather than treating the message as clearing it.
  *
- *  The `bg_image` File is the one the host supplied, byte-for-byte — see the round-trip
+ *  A non-null `bg_image` File is the one the host supplied, byte-for-byte — see the round-trip
  *  guarantee at the top of this file.
  *
  *  'bg_suggestion_selected' asks the host for the bytes behind one of the BgSuggestions it sent

package/dist/embed_types.js

@@ -8,7 +8,13 @@
 // Messages carry no derived schema: hosts call build_schema(form) from bookcover-core, so there
 // is exactly one place that form → schema conversion happens.
 //
-// BACKGROUND IMAGE BYTES ROUND-TRIP UNMODIFIED. Whatever File the host hands in comes back out
+// A BACKGROUND IMAGE IS AN ID OR BYTES, NEVER BOTH. A built-in background travels as its
+// filename in `bg_image_builtin` with `bg_image: null` — no bytes, in either direction, so
+// neither side has to download a multi-megabyte original just to open or report the editor. An
+// uploaded image (a user upload, or a host-supplied one) travels as `bg_image` bytes with
+// `bg_image_builtin: null`.
+//
+// UPLOADED IMAGE BYTES ROUND-TRIP UNMODIFIED. Whatever File the host hands in comes back out
 // byte-for-byte — never re-encoded, resized or stripped of metadata — so a host can hash the
 // bytes to recognise an image it already stores. See FormState.bg_image in bookcover-core.
 export {};

package/dist/index.d.ts

@@ -6,9 +6,9 @@ export { font_file_url } from 'typst-fonts/web';
 export { get_fonts, get_bundled_font } from 'typst-fonts';
 export { list_patterns, collect_fonts, collect_all_fonts, default_spine_title, list_vector_backgrounds, find_vector_background, list_builtin_icons, find_builtin_icon, icon_categories, suggested_icons, generate_palette, cover_schema } from 'bookcover-core';
 export type { IconCategory } from 'bookcover-core';
-export { tinted_contrast_text, pick_vivid_tint, synthesize_fill, blend_regions, region_hex, all_image_regions, analyze_pixel_regions, get_builtin_bg_regions, VECTOR_BG_AUTO_COLOR, resolve_colors, darken_hsl } from 'bookcover-core';
-export type { RegionStats, ImageRegions, ResolvedColors } from 'bookcover-core';
-export { make_blank_form_values, build_schema, curly_quotes, parse_font_family, find_pattern, derive_colors, hex_override_to_hsl, hex_to_hsl, is_dark_color } from 'bookcover-core';
+export { tinted_contrast_text, pick_vivid_tint, synthesize_fill, blend_regions, region_hex, all_image_regions, analyze_pixel_regions, get_builtin_bg, get_builtin_bg_regions, BG_PREVIEW_DIR, VECTOR_BG_AUTO_COLOR, resolve_colors, darken_hsl } from 'bookcover-core';
+export type { RegionStats, ImageRegions, ResolvedColors, BuiltinBg } from 'bookcover-core';
+export { make_blank_form_values, build_schema, curly_quotes, parse_font_family, find_pattern, derive_colors, hex_override_to_hsl, hex_to_hsl, is_dark_color, warn_unknown } from 'bookcover-core';
 export type { FormState, EmbedFormState, CustomFontStyle, DerivedColors } from 'bookcover-core';
 export { resolve_dimensions } from 'bookcover-core';
 export type { GetDimensionsResult, DimensionInputs } from 'bookcover-core';
@@ -22,6 +22,8 @@ export interface InitOptions {
 export interface GenerateOptions {
     schema: unknown;
     image?: Blob;
+    image_builtin?: string;
+    image_max_dpi?: number;
     format?: OutputFormat;
     ppi?: number;
     split?: boolean;
@@ -34,12 +36,11 @@ export interface GenerateResult {
 }
 /**
  * Sample a background image's dominant colors, under both interpretations at once — see
- * analyze_pixel_regions for what `dims` does. Skips decoding entirely when the image matches a
- * known builtin background by filename + byte size (see get_builtin_bg_regions) — that fast
- * path needs a File (or any Blob with a `name`); a plain nameless Blob always gets a live
- * decode via the Canvas API. Exported so hosts can sample ahead of generate() (e.g. the widget
- * caches this on a debounced watcher, independent of when generate() itself runs, then passes
- * the result back in via GenerateOptions.image_regions).
+ * analyze_pixel_regions for what `dims` does. Always decodes via the Canvas API — a builtin
+ * background's baked regions come from get_builtin_bg_regions() by its ID instead. Exported so
+ * hosts can sample ahead of generate() (e.g. the widget caches this on a debounced watcher,
+ * independent of when generate() itself runs, then passes the result back in via
+ * GenerateOptions.image_regions).
  */
 export declare function analyze_image_regions(image: Blob, dims: GetDimensionsResult | null): Promise<ImageRegions>;
 /** Stateful cover generator — each instance owns its own compiler and renderer */

package/dist/index.js

@@ -8,9 +8,9 @@ import { load_fonts_prefix, font_urls_for as build_font_urls, fetch_font_bytes,
 export { font_file_url } from 'typst-fonts/web';
 export { get_fonts, get_bundled_font } from 'typst-fonts';
 export { list_patterns, collect_fonts, collect_all_fonts, default_spine_title, list_vector_backgrounds, find_vector_background, list_builtin_icons, find_builtin_icon, icon_categories, suggested_icons, generate_palette, cover_schema } from 'bookcover-core';
-export { tinted_contrast_text, pick_vivid_tint, synthesize_fill, blend_regions, region_hex, all_image_regions, analyze_pixel_regions, get_builtin_bg_regions, VECTOR_BG_AUTO_COLOR, resolve_colors, darken_hsl } from 'bookcover-core';
+export { tinted_contrast_text, pick_vivid_tint, synthesize_fill, blend_regions, region_hex, all_image_regions, analyze_pixel_regions, get_builtin_bg, get_builtin_bg_regions, BG_PREVIEW_DIR, VECTOR_BG_AUTO_COLOR, resolve_colors, darken_hsl } from 'bookcover-core';
 // Form state + form->schema conversion, so hosts can derive the renderable schema themselves
-export { make_blank_form_values, build_schema, curly_quotes, parse_font_family, find_pattern, derive_colors, hex_override_to_hsl, hex_to_hsl, is_dark_color } from 'bookcover-core';
+export { make_blank_form_values, build_schema, curly_quotes, parse_font_family, find_pattern, derive_colors, hex_override_to_hsl, hex_to_hsl, is_dark_color, warn_unknown } from 'bookcover-core';
 // Dimension resolution, so hosts can locate cover panels (e.g. for background-image analysis)
 export { resolve_dimensions } from 'bookcover-core';
 const decoder = new TextDecoder();
@@ -31,13 +31,17 @@ function make_canvas(width, height) {
     canvas.height = height;
     return canvas;
 }
+/** Encode a canvas' contents as an image Blob of the given type (handles both canvas types) */
+async function canvas_blob(canvas, type, quality) {
+    if ('convertToBlob' in canvas)
+        return canvas.convertToBlob({ type, quality });
+    return new Promise((resolve) => {
+        canvas.toBlob((b) => resolve(b), type, quality);
+    });
+}
 /** Encode a canvas' contents as PNG bytes (handles both canvas types) */
 async function canvas_png_bytes(canvas) {
-    const blob = 'convertToBlob' in canvas
-        ? await canvas.convertToBlob({ type: 'image/png' })
-        : await new Promise((resolve) => {
-            canvas.toBlob((b) => resolve(b), 'image/png');
-        });
+    const blob = await canvas_blob(canvas, 'image/png');
     return new Uint8Array(await blob.arrayBuffer());
 }
 /** Crop a region from a PNG using the Canvas API — used as PngCropFn */
@@ -53,23 +57,78 @@ async function canvas_crop(data, x, y, w, h) {
 // Downscale target (longest edge, px) for a live pixel decode — plenty of resolution for a
 // dominant-color read while keeping the pixel scan cheap
 const IMAGE_REGIONS_MAX_DIM = 400;
+// Resizing is skipped when it would shrink the image by less than this fraction of its size —
+// a near-target image (e.g. a built-in's preview copy, sized for a 6x9 cover) gains nothing from
+// another decode and lossy re-encode
+const MIN_DOWNSCALE = 0.85;
+// The most recent downscaled copy (see downscale_image), so repeat previews of one image at one
+// size skip the decode + re-encode. Just one entry: the target size shifts with every page count
+// or trim edit, and older copies would otherwise pile up
+let downscaled = null;
+/** Identify an image across structured clones. A File posted to a worker arrives as a new object
+ *  on every message, so identity alone would never match; its name, size, type and modified time
+ *  together do. A plain Blob carries none of that beyond size/type, so it's matched by identity */
+function image_key(image) {
+    if (!(image instanceof File))
+        return null;
+    return `${image.name}:${image.size}:${image.type}:${image.lastModified}`;
+}
+/** Shrink an image to the smallest size that still covers target_w x target_h — the templates
+ *  place background images with fit "cover", so the LARGER of the two scale factors is the one
+ *  that keeps every covered pixel. Never enlarges, and returns the image itself when it's already
+ *  small enough or near enough (see MIN_DOWNSCALE). PNGs stay PNG so transparency survives;
+ *  anything else is re-encoded as JPEG */
+async function resize_to_cover(image, target_w, target_h) {
+    const bitmap = await createImageBitmap(image);
+    const scale = Math.max(target_w / bitmap.width, target_h / bitmap.height);
+    if (scale >= MIN_DOWNSCALE) {
+        bitmap.close();
+        return image;
+    }
+    const w = Math.max(1, Math.round(bitmap.width * scale));
+    const h = Math.max(1, Math.round(bitmap.height * scale));
+    const canvas = make_canvas(w, h);
+    const ctx = canvas.getContext('2d');
+    if (!ctx)
+        throw new Error('[generator-web] 2D canvas context unavailable');
+    ctx.drawImage(bitmap, 0, 0, w, h);
+    bitmap.close();
+    const type = image.type === 'image/png' ? 'image/png' : 'image/jpeg';
+    return canvas_blob(canvas, type, 0.85);
+}
+/** A copy of a background image with at most max_dpi pixels per inch across the full cover
+ *  spread (see GenerateOptions.image_max_dpi), reusing the last one when nothing changed */
+function downscale_image(image, dims, max_dpi) {
+    const target_w = Math.round(dims.cover_total_width.toNumber() / 25.4 * max_dpi);
+    const target_h = Math.round(dims.cover_total_height.toNumber() / 25.4 * max_dpi);
+    const size_key = `${target_w}x${target_h}`;
+    const key = image_key(image) ?? '';
+    const same_image = downscaled !== null
+        && (downscaled.source === image || (key !== '' && downscaled.image_key === key));
+    if (downscaled && same_image && downscaled.size_key === size_key)
+        return downscaled.blob;
+    // Cache the promise so concurrent calls share one resize, but drop it if the resize fails
+    const blob = resize_to_cover(image, target_w, target_h);
+    const entry = { image_key: key, source: image, size_key, blob };
+    downscaled = entry;
+    blob.catch(() => {
+        if (downscaled === entry)
+            downscaled = null;
+    });
+    return blob;
+}
 // How many generate() calls to allow between forced memory resets, as a fallback for whatever
 // slow growth an image-identity change alone wouldn't catch — see reset_memory_if_needed
 const MEMORY_RESET_INTERVAL = 25;
 /**
  * Sample a background image's dominant colors, under both interpretations at once — see
- * analyze_pixel_regions for what `dims` does. Skips decoding entirely when the image matches a
- * known builtin background by filename + byte size (see get_builtin_bg_regions) — that fast
- * path needs a File (or any Blob with a `name`); a plain nameless Blob always gets a live
- * decode via the Canvas API. Exported so hosts can sample ahead of generate() (e.g. the widget
- * caches this on a debounced watcher, independent of when generate() itself runs, then passes
- * the result back in via GenerateOptions.image_regions).
+ * analyze_pixel_regions for what `dims` does. Always decodes via the Canvas API — a builtin
+ * background's baked regions come from get_builtin_bg_regions() by its ID instead. Exported so
+ * hosts can sample ahead of generate() (e.g. the widget caches this on a debounced watcher,
+ * independent of when generate() itself runs, then passes the result back in via
+ * GenerateOptions.image_regions).
  */
 export async function analyze_image_regions(image, dims) {
-    const filename = 'name' in image ? image.name : undefined;
-    const builtin = filename ? get_builtin_bg_regions(filename, image.size) : null;
-    if (builtin)
-        return builtin;
     const bitmap = await createImageBitmap(image);
     const scale = Math.min(1, IMAGE_REGIONS_MAX_DIM / Math.max(bitmap.width, bitmap.height));
     const w = Math.max(1, Math.round(bitmap.width * scale));
@@ -314,10 +373,16 @@ export class CoverGenerator {
         }
         // Bound the compiler/renderer's WASM memory growth — see reset_memory_if_needed
         await this.reset_memory_if_needed(options.image);
+        // The image actually compiled — a downscaled copy for previews (see image_max_dpi), which
+        // only ever feeds build(); colors and the memory-reset check above use the original
+        const cover_dims = resolve_dimensions(parsed);
+        const render_image = options.image && options.image_max_dpi
+            ? await downscale_image(options.image, cover_dims, options.image_max_dpi)
+            : options.image;
         // Convert Blob to ImageInput (Uint8Array + extension) for the core builder
         let image_input;
-        if (options.image) {
-            const blob = options.image;
+        if (render_image) {
+            const blob = render_image;
             const ext = '.' + (blob.type.split('/')[1] ?? 'jpg').replace('jpeg', 'jpg');
             image_input = { data: new Uint8Array(await blob.arrayBuffer()), ext };
         }
@@ -329,16 +394,21 @@ export class CoverGenerator {
             frame_blob = await resp.blob();
         }
         // Colors sampled from the background image, for auto text/blurb/spine coloring. A
-        // caller-supplied value (e.g. the widget's own debounced cache) is used as-is; otherwise
-        // this samples `image` itself (see analyze_image_regions) — best-effort, since a decode
-        // failure here would otherwise take down an unrelated generate() call.
+        // caller-supplied value (e.g. the widget's own debounced cache) is used as-is, then a
+        // named builtin's baked regions; otherwise this samples the original `image` itself (see
+        // analyze_image_regions) — best-effort, since a decode failure here would otherwise take
+        // down an unrelated generate() call.
+        const builtin_regions = options.image_builtin
+            ? get_builtin_bg_regions(options.image_builtin) : null;
         let image_regions;
         if (options.image_regions !== undefined) {
             image_regions = options.image_regions;
         }
+        else if (options.image && builtin_regions) {
+            image_regions = builtin_regions;
+        }
         else if (options.image) {
-            image_regions = await analyze_image_regions(options.image, resolve_dimensions(parsed))
-                .catch(() => null);
+            image_regions = await analyze_image_regions(options.image, cover_dims).catch(() => null);
         }
         else {
             image_regions = null;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "bookcover-web",
-    "version": "0.18.0",
+    "version": "0.20.0",
     "license": "MIT-0",
     "repository": {
         "type": "git",
@@ -39,7 +39,7 @@
         "@myriaddreamin/typst-ts-renderer": "0.7.0",
         "@myriaddreamin/typst-ts-web-compiler": "0.7.0",
         "@myriaddreamin/typst.ts": "0.7.0",
-        "bookcover-core": "^0.18.0",
+        "bookcover-core": "^0.20.0",
         "typst-fonts": "^0.1.0"
     },
     "sideEffects": false