@unmade/text-renderer 0.1.12 → 0.2.1

package/README.md

@@ -0,0 +1,115 @@
+# @unmade/text-renderer
+
+Pure function SVG text renderer. No side effects, all dependencies injected explicitly. Web worker compatible.
+
+## Public API
+
+```typescript
+import { getRenderedText } from '@unmade/text-renderer';
+
+const svg = await getRenderedText({
+  text: 'HELLO',
+  fontUrl: 'https://example.com/font.ttf',
+  physicalSize: [40, 'mm'],
+  boxDimensions: {
+    width: 500,
+    height: 200,
+    physicalWidth: 100,
+    physicalHeight: 40,
+    physicalUnits: 'mm',
+  },
+  spacing: { outlineWidth: 0, letterSpacing: 0, letterSpacingOutline: 0 },
+  baseline: 'flat', // or 'curved', or { type: 'custom', path: '...' }
+  horizontalAlignment: 'centre', // 'left' | 'centre' | 'right' | 'distributed'
+  verticalAlignment: 'centre',   // 'top' | 'centre' | 'bottom'
+  fillColour: { hex: '#000000' },
+});
+```
+
+### Import paths
+
+```typescript
+import { getRenderedText } from '@unmade/text-renderer';        // Browser
+import { getRenderedText } from '@unmade/text-renderer/node';   // Node.js
+import { getRenderedText } from '@unmade/text-renderer/worker'; // Web Worker
+```
+
+## Configuration Engine adapter
+
+The `ce-adapter` sub-package bridges CE (Configuration Engine) editor state to renderer options:
+
+```typescript
+import { extractTextPlacements, mapStateToRendererOptions } from '@unmade/text-renderer/ce-adapter';
+
+const placements = extractTextPlacements(editor);            // LoadedTextPlacement[]
+const options    = mapStateToRendererOptions(placements[0]); // GetRenderedTextOptions
+const svg        = await getRenderedText(options);
+```
+
+`extractTextPlacements` reads an editor instance and returns one `LoadedTextPlacement` per text placement, resolving fonts, colours, and position data from the CE state.
+
+`mapStateToRendererOptions` converts a `LoadedTextPlacement` into the `GetRenderedTextOptions` shape that `getRenderedText` accepts — including alignment normalisation (CE uses American English, TR uses British English).
+
+## Comparison system
+
+The `packages/tr-comparison` package provides a pipeline for validating TR output against the CE's own rendering for real production designs.
+
+### How it works
+
+1. A design URL is POSTed to the comparison Lambda
+2. The Lambda loads the design via the CE factory, extracts all text placements, and renders each one with both CE and TR
+3. Both outputs are rasterised to PNG and diffed pixel-by-pixel with pixelmatch
+4. Results (match score, images, state) are stored in S3 and indexed in DynamoDB
+5. A browser comparison is also run via Puppeteer against the deployed demo app
+6. The comparison dashboard at `packages/tr-comparison/src` displays all results
+
+### Stored S3 artefacts
+
+For each placement comparison:
+
+```
+comparisons/{designUrlHash}/{timestamp}/{placementId}/
+  ce.png                # Config Engine render
+  tr.png                # Text Renderer render
+  diff.png              # Pixel difference heatmap
+  state.json            # LoadedTextPlacement (CE state passed to the adapter)
+  renderer-options.json # GetRenderedTextOptions (mapped TR input)
+```
+
+## Regression tests
+
+Regression tests live in `__tests__/regression.test.ts` and use fixture pairs in `__tests__/fixtures/regression/`:
+
+| File | Contents |
+|------|----------|
+| `{name}.json` | Fixture metadata + `LoadedTextPlacement` |
+| `{name}.png`  | Reference PNG (expected TR render) |
+
+The test pipeline for each fixture:
+
+```
+LoadedTextPlacement
+  → mapStateToRendererOptions()
+  → getRenderedText()
+  → SVG → PNG (resvg-js)
+  → pixelmatch diff against {name}.png
+  → fail if diff > 1%
+```
+
+### Adding a fixture
+
+1. Run a comparison in the dashboard against a design URL
+2. Select the record and click **Save as fixture** in the detail panel
+3. Enter a descriptive name (e.g. `curved-jersey-40mm`) — two files download
+4. Place both files in `__tests__/fixtures/regression/`
+5. Run `npm test` to confirm the fixture passes, then commit
+
+### Updating fixtures after an intentional change
+
+```bash
+UPDATE_FIXTURES=true npm test
+```
+
+This re-renders all fixtures and overwrites the stored PNGs. Review the diffs, then commit.
+
+> Regression tests require network access to fetch fonts from their CDN URLs.

package/dist/ce-adapter/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});function C(t){return t.type==="text"}function P(t){const i=t.getState().garment;return t.settings.garments.find(s=>s.slug===i)}function w(t,o){if(t.embellishment_positions)return t.embellishment_positions.find(i=>i.placement===o)}function A(t,o){const i=t.fonts.find(s=>s.id===o);if(i)return{id:i.id,fontUrl:i.font_url,fontFamily:i.font_family,letterSpacing:i.letter_spacing??0,letterSpacingOutline:i.letter_spacing_outline??0,outlineWidth:i.outline_width??0,fixedColours:i.fixed_colours}}function v(t,o,i,s,c){const{library:u}=c,a=[];for(const[l,h]of Object.entries(s)){if(h.type!=="text")continue;const f=h,{meta:n}=f;if(!n?.text)continue;const{libraryItemID:d}=f,g=u[d];if(!g||!C(g))continue;const y=n.font;if(y===void 0)continue;const m=A(g,y);if(!m)continue;const r=w(o,l);if(!r)continue;let x=null,b=null;if(n.colours&&g.palette!=null)try{const e=t.palettes.getUsedColours(g.palette,n.colours);x=e[0]??null,b=e[1]??null}catch(e){console.warn(`[extractTextPlacements] Colour resolution failed for ${l}:`,e)}const S=c.byId?.[l],p={vertical:"top",horizontal:"left"};if(S){const e=S;e.vertical_alignment&&(p.vertical=e.vertical_alignment),e.horizontal_alignment&&(p.horizontal=e.horizontal_alignment)}a.push({placementId:l,displayName:l,source:i,text:n.text,font:m,isCurved:n.isCurved??!1,isDistributed:n.isDistributed??!1,verticalAlignment:n.verticalAlignment??p.vertical,horizontalAlignment:n.horizontalAlignment??p.horizontal,rotation:n.rotation??0,spacing:n.spacing??null,fillColour:x,outlineColour:b,position:{width:r.width,height:r.height,physicalWidth:r.physical_width_decimal,physicalHeight:r.physical_height_decimal,physicalUnits:r.physical_size_units,baselinePath:r.baseline_path,rotation:r.rotation},userSetPhysicalSize:n.retainedPhysicalSize??null,fontMetrics:(()=>{const e=n.fontMetrics??{size:0,height:0,baseline:0,width:0},z=e.physicalFontSize||(e.physicalHeight!=null&&e.physicalHeight>0&&e.physicalUnits!=null?[e.physicalHeight,e.physicalUnits]:void 0);return{...e,physicalFontSize:z}})(),manufacturingMethod:n.manufacturing_method??""})}return a}function U(t){const o=t.getState(),i=P(t);if(!i)return console.warn("[extractTextPlacements] No matching garment found"),[];const s=[],c=o.vals?.placements,u=t.settings.placements;c&&u&&s.push(...v(t,i,"placements",c,u));const a=o.vals?.embellishments,l=t.settings.embellishments;return a&&l&&s.push(...v(t,i,"embellishments",a,l)),s.length===0&&console.warn("[extractTextPlacements] No text entries found in either placements or embellishments"),s}function _(t){return t==="center"?"centre":t}function O(t){let o=_(t.horizontalAlignment);t.isDistributed&&(o="distributed");let i;t.position.baselinePath?i={type:"custom",path:t.position.baselinePath}:t.isCurved?i="curved":i="flat";const s=t.userSetPhysicalSize?[t.userSetPhysicalSize[0],t.userSetPhysicalSize[1]]:t.fontMetrics.physicalFontSize!=null?t.fontMetrics.physicalFontSize:[t.position.physicalHeight,t.position.physicalUnits],u={outlineWidth:t.outlineColour!=null?t.font.outlineWidth:0,letterSpacing:t.spacing?.letter_spacing??0,letterSpacingOutline:t.spacing?.letter_spacing_outline??0},a=t.fillColour?{hex:t.fillColour.hex,reference:t.fillColour.reference??void 0}:void 0,l=t.outlineColour?{hex:t.outlineColour.hex,reference:t.outlineColour.reference??void 0}:void 0;let h;if(t.font.fixedColours){const f={};for(const[n,d]of Object.entries(t.font.fixedColours))f[n]={hex:d.hex,reference:d.reference};h=f}return{text:t.text,fontUrl:t.font.fontUrl,physicalSize:s,fontSizeFallback:t.fontMetrics.size,boxDimensions:{width:t.position.width,height:t.position.height,physicalWidth:t.position.physicalWidth,physicalHeight:t.position.physicalHeight,physicalUnits:t.position.physicalUnits},spacing:u,verticalAlignment:_(t.verticalAlignment),horizontalAlignment:o,baseline:i,fillColour:a,strokeColour:l,colourMap:h}}exports.extractTextPlacements=U;exports.mapStateToRendererOptions=O;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});function P(t){return t.type==="text"}function w(t){const i=t.getState().garment;return t.settings.garments.find(s=>s.slug===i)}function A(t,l,i){if(!t.embellishment_positions)return;const s=t.embellishment_positions.filter(o=>o.placement!==l?!1:!i||!o.variant?!0:o.variant===i||o.variant.toLowerCase()==="common");if(i&&s.length>1){const o=s.find(a=>a.variant===i);if(o)return o}return s[0]}function U(t,l){const i=t.fonts.find(s=>s.id===l);if(i)return{id:i.id,fontUrl:i.font_url,fontFamily:i.font_family,letterSpacing:i.letter_spacing??0,letterSpacingOutline:i.letter_spacing_outline??0,outlineWidth:i.outline_width??0,fixedColours:i.fixed_colours}}function v(t,l,i,s,o,a){const{library:h}=o,u=[];for(const[r,f]of Object.entries(s)){if(f.type!=="text")continue;const d=f,{meta:e}=d;if(!e?.text)continue;const{libraryItemID:z}=d,g=h[z];if(!g||!P(g))continue;const y=e.font;if(y===void 0)continue;const m=U(g,y);if(!m)continue;const c=A(l,r,a);if(!c)continue;let x=null,b=null;if(e.colours&&g.palette!=null)try{const n=t.palettes.getUsedColours(g.palette,e.colours);x=n[0]??null,b=n[1]??null}catch(n){console.warn(`[extractTextPlacements] Colour resolution failed for ${r}:`,n)}const S=o.byId?.[r],p={vertical:"top",horizontal:"left"};if(S){const n=S;n.vertical_alignment&&(p.vertical=n.vertical_alignment),n.horizontal_alignment&&(p.horizontal=n.horizontal_alignment)}u.push({placementId:r,displayName:r,source:i,text:e.text,font:m,isCurved:e.isCurved??!1,isDistributed:e.isDistributed??!1,verticalAlignment:e.verticalAlignment??p.vertical,horizontalAlignment:e.horizontalAlignment??p.horizontal,rotation:e.rotation??0,spacing:e.spacing??null,fillColour:x,outlineColour:b,position:{width:c.width,height:c.height,physicalWidth:c.physical_width_decimal,physicalHeight:c.physical_height_decimal,physicalUnits:c.physical_size_units,baselinePath:c.baseline_path,rotation:c.rotation},userSetPhysicalSize:e.retainedPhysicalSize??null,fontMetrics:(()=>{const n=e.fontMetrics??{size:0,height:0,baseline:0,width:0},C=n.physicalFontSize||(n.physicalHeight!=null&&n.physicalHeight>0&&n.physicalUnits!=null?[n.physicalHeight,n.physicalUnits]:void 0);return{...n,physicalFontSize:C}})(),manufacturingMethod:e.manufacturing_method??""})}return u}function O(t){const l=t.getState(),i=w(t);if(!i)return console.warn("[extractTextPlacements] No matching garment found"),[];const s=typeof t.getCurrentVariant=="function"?t.getCurrentVariant():void 0,o=[],a=l.vals?.placements,h=t.settings.placements;a&&h&&o.push(...v(t,i,"placements",a,h,s));const u=l.vals?.embellishments,r=t.settings.embellishments;return u&&r&&o.push(...v(t,i,"embellishments",u,r,s)),o.length===0&&console.warn("[extractTextPlacements] No text entries found in either placements or embellishments"),o}function _(t){return t==="center"?"centre":t}function T(t){let l=_(t.horizontalAlignment);t.isDistributed&&(l="distributed");let i;t.position.baselinePath?i={type:"custom",path:t.position.baselinePath}:t.isCurved?i="curved":i="flat";const s=t.userSetPhysicalSize?[t.userSetPhysicalSize[0],t.userSetPhysicalSize[1]]:t.fontMetrics.physicalFontSize!=null?t.fontMetrics.physicalFontSize:[t.position.physicalHeight,t.position.physicalUnits],a={outlineWidth:t.outlineColour!=null?t.font.outlineWidth:0,letterSpacing:t.spacing?.letter_spacing??0,letterSpacingOutline:t.spacing?.letter_spacing_outline??0},h=t.fillColour?{hex:t.fillColour.hex,reference:t.fillColour.reference??void 0}:void 0,u=t.outlineColour?{hex:t.outlineColour.hex,reference:t.outlineColour.reference??void 0}:void 0;let r;if(t.font.fixedColours){const f={};for(const[d,e]of Object.entries(t.font.fixedColours))f[d]={hex:e.hex,reference:e.reference};r=f}return{text:t.text,fontUrl:t.font.fontUrl,physicalSize:s,fontSizeFallback:t.fontMetrics.size,boxDimensions:{width:t.position.width,height:t.position.height,physicalWidth:t.position.physicalWidth,physicalHeight:t.position.physicalHeight,physicalUnits:t.position.physicalUnits},spacing:a,verticalAlignment:_(t.verticalAlignment),horizontalAlignment:l,baseline:i,fillColour:h,strokeColour:u,colourMap:r}}exports.extractTextPlacements=O;exports.mapStateToRendererOptions=T;

package/dist/ce-adapter/index.js

@@ -1,18 +1,21 @@
-function C(t) {
+function w(t) {
   return t.type === "text";
 }
 function P(t) {
   const i = t.getState().garment;
   return t.settings.garments.find((s) => s.slug === i);
 }
-function w(t, o) {
-  if (t.embellishment_positions)
-    return t.embellishment_positions.find(
-      (i) => i.placement === o
-    );
+function A(t, l, i) {
+  if (!t.embellishment_positions) return;
+  const s = t.embellishment_positions.filter((o) => o.placement !== l ? !1 : !i || !o.variant ? !0 : o.variant === i || o.variant.toLowerCase() === "common");
+  if (i && s.length > 1) {
+    const o = s.find((a) => a.variant === i);
+    if (o) return o;
+  }
+  return s[0];
 }
-function A(t, o) {
-  const i = t.fonts.find((s) => s.id === o);
+function U(t, l) {
+  const i = t.fonts.find((s) => s.id === l);
   if (i)
     return {
       id: i.id,
@@ -24,109 +27,109 @@ function A(t, o) {
       fixedColours: i.fixed_colours
     };
 }
-function v(t, o, i, s, c) {
-  const { library: u } = c, a = [];
-  for (const [l, h] of Object.entries(s)) {
-    if (h.type !== "text") continue;
-    const f = h, { meta: n } = f;
-    if (!n?.text) continue;
-    const { libraryItemID: d } = f, g = u[d];
-    if (!g || !C(g)) continue;
-    const y = n.font;
+function S(t, l, i, s, o, a) {
+  const { library: h } = o, u = [];
+  for (const [r, f] of Object.entries(s)) {
+    if (f.type !== "text") continue;
+    const d = f, { meta: e } = d;
+    if (!e?.text) continue;
+    const { libraryItemID: z } = d, g = h[z];
+    if (!g || !w(g)) continue;
+    const y = e.font;
     if (y === void 0) continue;
-    const m = A(g, y);
+    const m = U(g, y);
     if (!m) continue;
-    const r = w(o, l);
-    if (!r) continue;
+    const c = A(l, r, a);
+    if (!c) continue;
     let x = null, b = null;
-    if (n.colours && g.palette != null)
+    if (e.colours && g.palette != null)
       try {
-        const e = t.palettes.getUsedColours(
+        const n = t.palettes.getUsedColours(
           g.palette,
-          n.colours
+          e.colours
         );
-        x = e[0] ?? null, b = e[1] ?? null;
-      } catch (e) {
-        console.warn(`[extractTextPlacements] Colour resolution failed for ${l}:`, e);
+        x = n[0] ?? null, b = n[1] ?? null;
+      } catch (n) {
+        console.warn(`[extractTextPlacements] Colour resolution failed for ${r}:`, n);
       }
-    const S = c.byId?.[l], p = {
+    const v = o.byId?.[r], p = {
       vertical: "top",
       horizontal: "left"
     };
-    if (S) {
-      const e = S;
-      e.vertical_alignment && (p.vertical = e.vertical_alignment), e.horizontal_alignment && (p.horizontal = e.horizontal_alignment);
+    if (v) {
+      const n = v;
+      n.vertical_alignment && (p.vertical = n.vertical_alignment), n.horizontal_alignment && (p.horizontal = n.horizontal_alignment);
     }
-    a.push({
-      placementId: l,
-      displayName: l,
+    u.push({
+      placementId: r,
+      displayName: r,
       source: i,
-      text: n.text,
+      text: e.text,
       font: m,
-      isCurved: n.isCurved ?? !1,
-      isDistributed: n.isDistributed ?? !1,
-      verticalAlignment: n.verticalAlignment ?? p.vertical,
-      horizontalAlignment: n.horizontalAlignment ?? p.horizontal,
-      rotation: n.rotation ?? 0,
-      spacing: n.spacing ?? null,
+      isCurved: e.isCurved ?? !1,
+      isDistributed: e.isDistributed ?? !1,
+      verticalAlignment: e.verticalAlignment ?? p.vertical,
+      horizontalAlignment: e.horizontalAlignment ?? p.horizontal,
+      rotation: e.rotation ?? 0,
+      spacing: e.spacing ?? null,
       fillColour: x,
       outlineColour: b,
       position: {
-        width: r.width,
-        height: r.height,
-        physicalWidth: r.physical_width_decimal,
-        physicalHeight: r.physical_height_decimal,
-        physicalUnits: r.physical_size_units,
-        baselinePath: r.baseline_path,
-        rotation: r.rotation
+        width: c.width,
+        height: c.height,
+        physicalWidth: c.physical_width_decimal,
+        physicalHeight: c.physical_height_decimal,
+        physicalUnits: c.physical_size_units,
+        baselinePath: c.baseline_path,
+        rotation: c.rotation
       },
-      userSetPhysicalSize: n.retainedPhysicalSize ?? null,
+      userSetPhysicalSize: e.retainedPhysicalSize ?? null,
       fontMetrics: (() => {
-        const e = n.fontMetrics ?? { size: 0, height: 0, baseline: 0, width: 0 }, z = e.physicalFontSize || (e.physicalHeight != null && e.physicalHeight > 0 && e.physicalUnits != null ? [e.physicalHeight, e.physicalUnits] : void 0);
-        return { ...e, physicalFontSize: z };
+        const n = e.fontMetrics ?? { size: 0, height: 0, baseline: 0, width: 0 }, C = n.physicalFontSize || (n.physicalHeight != null && n.physicalHeight > 0 && n.physicalUnits != null ? [n.physicalHeight, n.physicalUnits] : void 0);
+        return { ...n, physicalFontSize: C };
       })(),
-      manufacturingMethod: n.manufacturing_method ?? ""
+      manufacturingMethod: e.manufacturing_method ?? ""
     });
   }
-  return a;
+  return u;
 }
-function U(t) {
-  const o = t.getState(), i = P(t);
+function F(t) {
+  const l = t.getState(), i = P(t);
   if (!i)
     return console.warn("[extractTextPlacements] No matching garment found"), [];
-  const s = [], c = o.vals?.placements, u = t.settings.placements;
-  c && u && s.push(...v(t, i, "placements", c, u));
-  const a = o.vals?.embellishments, l = t.settings.embellishments;
-  return a && l && s.push(...v(t, i, "embellishments", a, l)), s.length === 0 && console.warn("[extractTextPlacements] No text entries found in either placements or embellishments"), s;
+  const s = typeof t.getCurrentVariant == "function" ? t.getCurrentVariant() : void 0, o = [], a = l.vals?.placements, h = t.settings.placements;
+  a && h && o.push(...S(t, i, "placements", a, h, s));
+  const u = l.vals?.embellishments, r = t.settings.embellishments;
+  return u && r && o.push(...S(t, i, "embellishments", u, r, s)), o.length === 0 && console.warn("[extractTextPlacements] No text entries found in either placements or embellishments"), o;
 }
 function _(t) {
   return t === "center" ? "centre" : t;
 }
-function F(t) {
-  let o = _(t.horizontalAlignment);
-  t.isDistributed && (o = "distributed");
+function H(t) {
+  let l = _(t.horizontalAlignment);
+  t.isDistributed && (l = "distributed");
   let i;
   t.position.baselinePath ? i = { type: "custom", path: t.position.baselinePath } : t.isCurved ? i = "curved" : i = "flat";
   const s = t.userSetPhysicalSize ? [
     t.userSetPhysicalSize[0],
     t.userSetPhysicalSize[1]
-  ] : t.fontMetrics.physicalFontSize != null ? t.fontMetrics.physicalFontSize : [t.position.physicalHeight, t.position.physicalUnits], u = {
+  ] : t.fontMetrics.physicalFontSize != null ? t.fontMetrics.physicalFontSize : [t.position.physicalHeight, t.position.physicalUnits], a = {
     outlineWidth: t.outlineColour != null ? t.font.outlineWidth : 0,
     letterSpacing: t.spacing?.letter_spacing ?? 0,
     letterSpacingOutline: t.spacing?.letter_spacing_outline ?? 0
-  }, a = t.fillColour ? {
+  }, h = t.fillColour ? {
     hex: t.fillColour.hex,
     reference: t.fillColour.reference ?? void 0
-  } : void 0, l = t.outlineColour ? {
+  } : void 0, u = t.outlineColour ? {
     hex: t.outlineColour.hex,
     reference: t.outlineColour.reference ?? void 0
   } : void 0;
-  let h;
+  let r;
   if (t.font.fixedColours) {
     const f = {};
-    for (const [n, d] of Object.entries(t.font.fixedColours))
-      f[n] = { hex: d.hex, reference: d.reference };
-    h = f;
+    for (const [d, e] of Object.entries(t.font.fixedColours))
+      f[d] = { hex: e.hex, reference: e.reference };
+    r = f;
   }
   return {
     text: t.text,
@@ -140,18 +143,18 @@ function F(t) {
       physicalHeight: t.position.physicalHeight,
       physicalUnits: t.position.physicalUnits
     },
-    spacing: u,
+    spacing: a,
     verticalAlignment: _(
       t.verticalAlignment
     ),
-    horizontalAlignment: o,
+    horizontalAlignment: l,
     baseline: i,
-    fillColour: a,
-    strokeColour: l,
-    colourMap: h
+    fillColour: h,
+    strokeColour: u,
+    colourMap: r
   };
 }
 export {
-  U as extractTextPlacements,
-  F as mapStateToRendererOptions
+  F as extractTextPlacements,
+  H as mapStateToRendererOptions
 };