@dloizides/poster-render 0.2.4 → 0.2.5

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.2.5
+
+- Own-key checks: the schema validator and the asset lookup use `Object.hasOwn`, so a `__proto__` key is rejected and an imageId such as `constructor` is reported missing.
+- `placeContain(image, region, { anchor, alignX, scale })` takes an options object (was 5 positional parameters).
+- Named size and gap constants; ESLint now lints tests and `src/testing`.
+- README: install, usage, canvas injection, fonts, type floor, schema version policy.
+
 ## 0.2.4
 
 - Type floor: every text run is at least 30px at a 1080 short edge (scaled per format by short edge). When a layout cannot fit its text at the floor, the picture yields space to the body (and a header stacked above it) in 2.5% steps.

package/README.md

@@ -7,7 +7,46 @@ One JSON document (`FlierDoc`) in, one poster out. Used by Flier Studio (FLIER-1
 - `render(doc, assets, canvas)`: validates first (throws `FlierDocError` before touching the canvas), resizes the canvas to the format, draws, returns a `RenderReport` (picture rect, text and card boxes).
 - `exportPng(canvas)`: PNG `Blob` of the canvas size.
 - Formats: story 1080x1920, post 1080x1350, square 1080x1080, phone 1170x2532, desktop 2560x1440.
-- Layouts: `picture-right` (E-A), `picture-left` (E-B), `arch` (E-C), `picture-bottom`, `list`, `phone-clock-safe` (P-A, top kept clear for the lock-screen clock), `phone-arch` (P-B), `desktop-safe` (D-A, text clear of desktop icons and the taskbar), `desktop-arch` (D-B). `LAYOUT_CATALOGUE` lists id, design id, label, description and designed formats (for the app picker and the LLM prompt); `defaultLayoutFor(format)` gives E-A / P-A / D-A.
+- Layouts: `picture-right` (E-A "Picture right"), `picture-left` (E-B "Picture left"), `arch` (E-C "Arch"), `picture-bottom`, `list`, `phone-clock-safe` (P-A "Phone, clock clear": top kept clear for the lock-screen clock), `phone-arch` (P-B "Phone arch"), `desktop-safe` (D-A "Desktop, icons clear": text clear of desktop icons and the taskbar), `desktop-arch` (D-B "Desktop arch"). `LAYOUT_CATALOGUE` lists id, design id, label, description and designed formats (for the app picker and the LLM prompt); `defaultLayoutFor(format)` gives E-A "Picture right" / P-A "Phone, clock clear" / D-A "Desktop, icons clear" (D4 "Layouts: keep all").
 - Arch layouts paint a soft arch (palette `arch`, about 4% off the ground) behind the picture only, inside the picture region; prices sit large on either side. The includes block is set at one size for every line. Palettes: `sand`, `night`, `sea`, `rose`. Font sets: `classic`, `modern`, `elegant` (the app loads the web fonts).
 - The picture is placed contain + anchor in its own region: never cropped, never faded, drawn last, and no text or card is laid out in its region. Text shrinks to fit, never overflows.
 - Example: `kizombaWorkshopDocs` (3 workshops + list flier), `kizombaWorkshop` (the list flier).
+
+## Install
+
+```bash
+npm install @dloizides/poster-render
+```
+
+## Usage
+
+```ts
+import { exportPng, kizombaWorkshop, render, validateFlierDoc } from '@dloizides/poster-render';
+
+const checked = validateFlierDoc(kizombaWorkshop);
+if (!checked.ok) {
+  throw new Error(checked.errors.join('\n'));
+}
+const canvas = document.createElement('canvas');
+const report = render(checked.doc, { dancers: pictureImage, logo: logoImage }, canvas);
+const png = await exportPng(canvas);
+```
+
+## Canvas injection
+
+`render` takes any canvas with a 2d context; the package has no canvas dependency.
+
+- Browser: an `HTMLCanvasElement` (or `OffscreenCanvas`); assets are loaded `HTMLImageElement` / `ImageBitmap`.
+- Node: `@napi-rs/canvas` (`createCanvas(1, 1)`, `loadImage(path)`); `render` resizes the canvas to the format.
+
+## Fonts
+
+The font sets name CSS families (`FONT_SETS`). The host loads them before `render`: in a browser with `document.fonts.load(...)` / `@font-face`, in Node with `GlobalFonts.registerFromPath` from `@napi-rs/canvas`. A missing font falls back to the default family and the text still fits.
+
+## Type floor
+
+Every text run is at least 30px at a 1080 short edge (40px on desktop 2560x1440). When a layout cannot fit its text at the floor, the picture gives space to the text.
+
+## Schema version policy
+
+`FlierDoc.version` is `1`. A field added as optional keeps version 1; a removed, renamed or retyped field raises the version and `validateFlierDoc` rejects the other version with `version: must be 1 (got N)`. A package major release goes with a new doc version.

package/dist/index.d.mts

@@ -217,7 +217,7 @@ interface LayoutCatalogueEntry {
     formats: readonly FormatId[];
 }
 declare const LAYOUT_CATALOGUE: readonly LayoutCatalogueEntry[];
-/** The default layout for a format (D4: E-A for posters, P-A for phone, D-A for desktop). */
+/** The default layout for a format (D4 "Layouts: keep all"): E-A "Picture right" for posters, P-A "Phone, clock clear", D-A "Desktop, icons clear". */
 declare function defaultLayoutFor(format: FormatId): LayoutId;
 
 declare const kizombaWorkshop: FlierDoc;

package/dist/index.d.ts

@@ -217,7 +217,7 @@ interface LayoutCatalogueEntry {
     formats: readonly FormatId[];
 }
 declare const LAYOUT_CATALOGUE: readonly LayoutCatalogueEntry[];
-/** The default layout for a format (D4: E-A for posters, P-A for phone, D-A for desktop). */
+/** The default layout for a format (D4 "Layouts: keep all"): E-A "Picture right" for posters, P-A "Phone, clock clear", D-A "Desktop, icons clear". */
 declare function defaultLayoutFor(format: FormatId): LayoutId;
 
 declare const kizombaWorkshop: FlierDoc;

package/dist/index.js

@@ -226,7 +226,7 @@ function checkObject(schema, value, path, errors) {
     }
   }
   for (const [key, child] of Object.entries(value)) {
-    const childSchema = props[key];
+    const childSchema = Object.hasOwn(props, key) ? props[key] : void 0;
     if (childSchema === void 0) {
       if (schema.additionalProperties === false) {
         errors.push(`${join(path, key)}: is not allowed`);
@@ -284,10 +284,10 @@ function validateFlierDoc(input) {
 }
 function missingAssets(doc, assets) {
   const errors = [];
-  if (doc.picture && assets[doc.picture.imageId] === void 0) {
+  if (doc.picture && !Object.hasOwn(assets, doc.picture.imageId)) {
     errors.push(`picture.imageId: no asset named "${doc.picture.imageId}"`);
   }
-  if (doc.logo && assets[doc.logo.imageId] === void 0) {
+  if (doc.logo && !Object.hasOwn(assets, doc.logo.imageId)) {
     errors.push(`logo.imageId: no asset named "${doc.logo.imageId}"`);
   }
   return errors;
@@ -347,9 +347,10 @@ var BOTTOM_MIN_TOP = 0.25;
 var BOTTOM_HEADER_SHARE = 0.3;
 var BOTTOM_GAP = 40 / 1080;
 var BOTTOM_ASPECT = 0.57;
+var DEFAULT_SIDE = [0.6, 0.42];
 var PICTURE_SIDE = {
-  ["picture-right" /* PictureRight */]: [0.6, 0.42],
-  ["picture-left" /* PictureLeft */]: [0.6, 0.42],
+  ["picture-right" /* PictureRight */]: DEFAULT_SIDE,
+  ["picture-left" /* PictureLeft */]: DEFAULT_SIDE,
   ["list" /* List */]: [0.5, 0.36]
 };
 var ANCHOR_Y = { ["top" /* Top */]: 0, ["center" /* Center */]: 0.5, ["bottom" /* Bottom */]: 1 };
@@ -409,13 +410,14 @@ function geometry(layout, w, h, give = 0) {
   if (layout === "picture-bottom" /* PictureBottom */) {
     return bottom(w, h, BOTTOM_PICTURE_W - give);
   }
-  const g = side(w, h, PICTURE_SIDE[layout] ?? [0.6, 0.42]);
+  const g = side(w, h, PICTURE_SIDE[layout] ?? DEFAULT_SIDE);
   if (layout !== "picture-left" /* PictureLeft */) {
     return g;
   }
   return { header: mirror(g.header, w), body: mirror(g.body, w), picture: mirror(g.picture, w), alignX: 1 - g.alignX };
 }
-function placeContain(image, region, anchor, alignX, scale) {
+function placeContain(image, region, fit) {
+  const { anchor, alignX, scale } = fit;
   const s = Math.min(region.w / image.width, region.h / image.height) * scale;
   const w = Math.floor(image.width * s);
   const h = Math.floor(image.height * s);
@@ -432,6 +434,29 @@ var BOLD = 700;
 var SEMI = 600;
 var MEDIUM = 500;
 var SCRIPT = 400;
+var SIZE = {
+  title: 250,
+  headerScript: 120,
+  itemDate: 67,
+  itemRow: 42,
+  scheduleLabel: 66,
+  scheduleTime: 60,
+  priceAmount: 66,
+  priceLabel: 52,
+  listPrice: 58,
+  flankAmount: 110,
+  flankLabel: 48,
+  venue: 58,
+  listVenue: 48,
+  small: 38
+};
+var GAP = {
+  item: 48,
+  row: 30,
+  venue: 40,
+  includes: 24,
+  rule: 8
+};
 var makers = (p, u) => ({
   display: (text2, size) => ({ text: text2, role: "display", weight: BOLD, size: size * u, color: p.title }),
   venue: (text2, size) => ({ text: text2, role: "display", weight: MEDIUM, size: size * u, color: p.ink }),
@@ -444,36 +469,36 @@ var makers = (p, u) => ({
 function headerGroups(doc, p, u) {
   const l = makers(p, u);
   const b = doc.blocks;
-  const lines = [l.display?.(b.title, 250), b.script ? l.script?.(b.script, 120) : void 0, b.titleBottom ? l.display?.(b.titleBottom, 250) : void 0];
+  const lines = [l.display(b.title, SIZE.title), b.script ? l.script(b.script, SIZE.headerScript) : void 0, b.titleBottom ? l.display(b.titleBottom, SIZE.title) : void 0];
   return [{ lines: lines.filter((x) => x !== void 0), gapAfter: 0 }];
 }
 function itemGroup(item, l, u) {
-  const lines = [l.script?.(item.date, 67)];
-  item.schedule.forEach((row) => lines.push(l.strong?.(`${row.label}  ${row.time}`, 42)));
+  const lines = [l.script(item.date, SIZE.itemDate)];
+  item.schedule.forEach((row) => lines.push(l.strong(`${row.label}  ${row.time}`, SIZE.itemRow)));
   if (item.price) {
-    lines.push(l.accent?.(item.price, 42));
+    lines.push(l.accent(item.price, SIZE.itemRow));
   }
-  return { lines, gapAfter: 48 * u };
+  return { lines, gapAfter: GAP.item * u };
 }
 function eventGroups(doc, l, u, withPrices) {
   const b = doc.blocks;
   const groups = [];
-  b.schedule?.forEach((row) => groups.push({ lines: [l.strong?.(row.label, 66), l.accent?.(row.time, 60)], gapAfter: 30 * u }));
+  b.schedule?.forEach((row) => groups.push({ lines: [l.strong(row.label, SIZE.scheduleLabel), l.accent(row.time, SIZE.scheduleTime)], gapAfter: GAP.row * u }));
   const prices = (withPrices ? b.prices : void 0) ?? [];
-  prices.forEach((row, i) => groups.push({ lines: [l.strong?.(row.amount, 66), l.accent?.(row.label, 52)], gapAfter: 30 * u, keepWithNext: i < prices.length - 1 }));
+  prices.forEach((row, i) => groups.push({ lines: [l.strong(row.amount, SIZE.priceAmount), l.accent(row.label, SIZE.priceLabel)], gapAfter: GAP.row * u, keepWithNext: i < prices.length - 1 }));
   return groups;
 }
 function listGroups(doc, l, u) {
   const groups = (doc.items ?? []).map((item) => itemGroup(item, l, u));
-  const prices = doc.blocks.prices?.map((row) => l.strong?.(`${row.amount} ${row.label}`, 58)) ?? [];
+  const prices = doc.blocks.prices?.map((row) => l.strong(`${row.amount} ${row.label}`, SIZE.listPrice)) ?? [];
   if (prices.length > 0) {
-    groups.push({ lines: prices, gapAfter: 30 * u });
+    groups.push({ lines: prices, gapAfter: GAP.row * u });
   }
   return groups;
 }
 function flankPriceGroups(doc, p, u) {
   const l = makers(p, u);
-  return (doc.blocks.prices ?? []).map((row) => ({ lines: [l.strong?.(row.amount, 110), l.accent?.(row.label, 48)], gapAfter: 30 * u }));
+  return (doc.blocks.prices ?? []).map((row) => ({ lines: [l.strong(row.amount, SIZE.flankAmount), l.accent(row.label, SIZE.flankLabel)], gapAfter: GAP.row * u }));
 }
 function bodyGroups(doc, p, u, withPrices = true) {
   const l = makers(p, u);
@@ -481,15 +506,16 @@ function bodyGroups(doc, p, u, withPrices = true) {
   const groups = [];
   const isList = doc.layout === "list" /* List */;
   if (b.venue) {
-    groups.push({ lines: b.venue.map((v) => l.venue?.(v, isList ? 48 : 58)), gapAfter: 40 * u, rule: { color: p.accent, height: 8 * u }, ruleBelow: true, icon: { color: p.accent, glyph: p.background } });
+    const size = isList ? SIZE.listVenue : SIZE.venue;
+    groups.push({ lines: b.venue.map((v) => l.venue(v, size)), gapAfter: GAP.venue * u, rule: { color: p.accent, height: GAP.rule * u }, ruleBelow: true, icon: { color: p.accent, glyph: p.background } });
   }
   groups.push(...isList ? listGroups(doc, l, u) : eventGroups(doc, l, u, withPrices));
   if (b.includes) {
-    const lines = [l.accent?.(b.includes.heading, 38), ...b.includes.items.map((i) => l.item?.(i, 38))];
-    groups.push({ lines, gapAfter: 24 * u, uniform: true });
+    const lines = [l.accent(b.includes.heading, SIZE.small), ...b.includes.items.map((i) => l.item(i, SIZE.small))];
+    groups.push({ lines, gapAfter: GAP.includes * u, uniform: true });
   }
   if (b.footer) {
-    groups.push({ lines: [l.soft?.(b.footer, 38)], gapAfter: 0 });
+    groups.push({ lines: [l.soft(b.footer, SIZE.small)], gapAfter: 0 });
   }
   return groups;
 }
@@ -501,6 +527,7 @@ var BULLET_RADIUS = 0.2;
 var RULE_GAP = 2.5;
 var RULE_WIDTH = 0.9;
 var WIDE = 1.6;
+var COLUMN_GAP = 0.04;
 var TWO_COLUMN_MIN = 0.75;
 var TWO_COLUMN_GAIN = 1.15;
 var MIN_K = 0.02;
@@ -523,15 +550,17 @@ function groupRatio(m, k, avail) {
   }
   return Math.min(...m.group.lines.map((line, i) => lineSize(line, m.widths[i] ?? 1, k, avail) / line.size));
 }
-function placeIcon(group, d, x, textTop, textBottom, out) {
+function placeIcon(group, box, out) {
+  const { d, x, top, bottom: bottom2 } = box;
   if (!group.icon || d <= 0) {
-    return textBottom;
+    return bottom2;
   }
-  const textH = textBottom - textTop;
-  out?.icons.push({ rect: { x, y: textTop + Math.max(0, (textH - d) / 2), w: d, h: d }, color: group.icon.color, glyph: group.icon.glyph });
-  return textTop + Math.max(textH, d);
+  const textH = bottom2 - top;
+  out?.icons.push({ rect: { x, y: top + Math.max(0, (textH - d) / 2), w: d, h: d }, color: group.icon.color, glyph: group.icon.glyph });
+  return top + Math.max(textH, d);
 }
-function placeGroup(m, k, col, y0, out) {
+function placeGroup(m, at, out) {
+  const { k, col, y0 } = at;
   const { group } = m;
   let y = y0;
   if (group.rule) {
@@ -556,7 +585,7 @@ function placeGroup(m, k, col, y0, out) {
     }
     y += size * LINE_HEIGHT;
   });
-  y = placeIcon(group, d, col.x + pad, top + pad, y, out);
+  y = placeIcon(group, { d, x: col.x + pad, top: top + pad, bottom: y }, out);
   y += pad;
   if (group.rule && group.ruleBelow) {
     y += group.rule.height * k * (RULE_GAP - 1);
@@ -568,10 +597,11 @@ function placeGroup(m, k, col, y0, out) {
   }
   return y + group.gapAfter * k - y0;
 }
-function placeColumn(groups, k, col, out, spread = 0) {
+function placeColumn(groups, at, out) {
+  const { k, col, spread = 0 } = at;
   let h = 0;
   for (const g of groups) {
-    h += placeGroup(g, k, col, col.y + h, out) + spread;
+    h += placeGroup(g, { k, col, y0: col.y + h }, out) + spread;
   }
   return h - spread;
 }
@@ -598,9 +628,9 @@ function keepTogether(groups, heights, cut) {
   return candidates.reduce((best, c) => tallest(heights, c) < tallest(heights, best) ? c : best);
 }
 function splitColumns(groups, zone) {
-  const gap = Math.round(zone.w * 0.04);
+  const gap = Math.round(zone.w * COLUMN_GAP);
   const w = (zone.w - gap) / 2;
-  const heights = groups.map((g) => placeGroup(g, 1, { ...zone, w }, 0, null));
+  const heights = groups.map((g) => placeGroup(g, { k: 1, col: { ...zone, w }, y0: 0 }, null));
   const total = columnSum(heights, 0, heights.length);
   let cut = 1;
   for (let c = 2; c < groups.length; c++) {
@@ -615,7 +645,7 @@ function splitColumns(groups, zone) {
   ];
 }
 function largestK(columns, zoneH) {
-  const fits = (k) => columns.every((c) => placeColumn(c.groups, k, c.col, null) <= zoneH);
+  const fits = (k) => columns.every((c) => placeColumn(c.groups, { k, col: c.col }, null) <= zoneH);
   let lo = MIN_K;
   let hi = 1;
   if (fits(1)) {
@@ -652,9 +682,9 @@ function flow(ctx, groups, zone, fonts) {
   }));
   const { columns, k: lo } = bestColumns(measured, zone);
   const out = emptyFlow();
-  const heights = columns.map((c) => placeColumn(c.groups, lo, c.col, null));
+  const heights = columns.map((c) => placeColumn(c.groups, { k: lo, col: c.col }, null));
   const end = Math.max(...heights);
-  columns.forEach((c, i) => placeColumn(c.groups, lo, c.col, out, c.groups.length > 1 && columns.length > 1 ? (end - (heights[i] ?? end)) / (c.groups.length - 1) : 0));
+  columns.forEach((c, i) => placeColumn(c.groups, { k: lo, col: c.col, spread: c.groups.length > 1 && columns.length > 1 ? (end - (heights[i] ?? end)) / (c.groups.length - 1) : 0 }, out));
   const lines = groups.flatMap((g) => g.lines);
   out.texts.forEach((t, i) => {
     const line = lines[i];
@@ -691,11 +721,11 @@ function measuredEnd(f, fallback) {
   const bottoms = [...f.texts.map((t) => t.box), ...f.rules.map((r3) => r3.rect), ...f.icons.map((i) => i.rect)].map((r3) => r3.y + r3.h);
   return bottoms.length > 0 ? Math.max(...bottoms) : fallback;
 }
-function pictureRegion(layout, geo, body, u, frame) {
+function pictureRegion(layout, geo, body, frame) {
   if (layout !== "picture-bottom" /* PictureBottom */) {
     return geo.picture;
   }
-  const y = Math.min(geo.picture.y, Math.ceil(measuredEnd(body, geo.body.y) + BODY_GAP * u));
+  const y = Math.min(geo.picture.y, Math.ceil(measuredEnd(body, geo.body.y) + BODY_GAP * frame.u));
   return { x: geo.picture.x, y, w: geo.picture.w, h: frame.height - y };
 }
 
@@ -882,7 +912,7 @@ function render(input, assets, canvas) {
   const radius = Math.min(width, height) * CARD_RADIUS;
   [head, body, ...sides].forEach((f) => drawFlow(ctx, f, radius));
   const logoImage = doc.logo ? assets[doc.logo.imageId] : void 0;
-  const logo = logoImage ? placeContain(logoImage, geo.logo ? zones.logo : capAligned(zones.logo, head), "top" /* Top */, 1, 1) : null;
+  const logo = logoImage ? placeContain(logoImage, geo.logo ? zones.logo : capAligned(zones.logo, head), { anchor: "top" /* Top */, alignX: 1, scale: 1 }) : null;
   if (logoImage && logo) {
     ctx.drawImage(logoImage, logo.x, logo.y, logo.w, logo.h);
   }
@@ -891,8 +921,8 @@ function render(input, assets, canvas) {
   if (backdrop) {
     drawArch(ctx, backdrop, palette.arch);
   }
-  const region = pictureRegion(doc.layout, geo, body, u, { height });
-  const picture = image && doc.picture ? placeContain(image, region, doc.picture.anchor, geo.alignX, doc.picture.scale) : null;
+  const region = pictureRegion(doc.layout, geo, body, { height, u });
+  const picture = image && doc.picture ? placeContain(image, region, { anchor: doc.picture.anchor, alignX: geo.alignX, scale: doc.picture.scale }) : null;
   if (image && picture) {
     ctx.drawImage(image, picture.x, picture.y, picture.w, picture.h);
   }