@unmade/text-renderer 0.1.12 → 0.2.0

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.