Geometry Authority Audit

Background = Mask = PDF = Manifest = Replay

All 23 active templates · 4 audit phases · Complete dimension traceability

Geometry Parity Summary

Goal: Background Dims = Mask Dims = PDF Canvas = Frontend Geo = Manifest Geo = Replay Geo

Template Group	BG Dims	Mask Dims	PDF Canvas	Frontend Geo	Manifest Geo	Replay Geo	Match	Notes
Angel (Default)	1620×1200	pending upload	800×593	800×534	800×593	800×593	✗	frontendGeo uses legacy 534
Soldier Letter	2250×1667	—	800×593	800×593	800×593	800×593	✓	✓ Fully aligned
Starship Bridge	1620×1200	—	800×593	800×593	800×593	800×593	✓	✓ pdfLayout correct; registry dims stale (declares 1920×1440)
Navy Ship	1536×2304	—	683×1024	800×593	683×1024	683×1024	✗	CRITICAL: portrait misrouted as landscape in templateGeometry.js
1920×1440 group (×9)	1920×1440	—	800×600	800×1120	800×600	800×600	✗	STD_H=1120 phantom — all zone bottomY values are offset
1024×683 group (×3)	1620×1200*	—	800×593	800×1120	800×593	800×593	✗	*Registry says 1024×683 but you produced at 1620×1200
Floral group (×5)	2250×4000	—	800×1422	800×1120	800×1422	800×1422	✗	STD_H=1120 — actual canvas is 302px TALLER than assumed

Remediation Plan — Required Before Phase 3

Fix 1 — lib/templateGeometry.js: Change angH = 534 → 593 in default case, angelMarginAtY(), and getContinuousAngelCSS(). Adds 59px of correct canvas height to Angel.

Fix 2 — lib/templateGeometry.js: Change STD_H = 1120 → derive pdfH per-template from actual asset dimensions. All portrait templates currently use a phantom height.

Fix 3 — lib/templateGeometry.js: Navy Ship is a portrait asset (1536×2304). Its canvas is 683×1024, not 800×593. Remove it from the LAND_H=593 group. Recalculate all zone coordinates.

Fix 4 — lib/backgroundTemplates.js: Update stale imageWidth/imageHeight metadata for Angel, tropical_beach_01, birthday_celebration_01, and starship_01 to reflect actual CDN dimensions.

Long-term — Upload mask assets for all templates. Once TemplateGeometry records are populated for all templates, templateGeometry.js hardcoded values become the fallback of last resort only.

URL Inventory Verification

Verify every active template CDN URL resolves to a valid asset (HTTP HEAD)

Asset Dimension Measurement

Load each background PNG and measure actual pixel dimensions. Compare against registry and frontend geometry.

Legacy Dimension Authority Search

All hardcoded dimension values found in the codebase, their source files, and their status.

Renderer Chain Verification

Trace every rendering surface to confirm geometry source. Identify any surface still reading legacy constants.

PDF Rendererfunctions/initiateLetterDelivery

AUTHORITATIVE

Embeds CDN asset via pdf-lib, computes scale = min(1, 800/asset.width), pageH = round(asset.height × scale). Runtime. Always correct.

Manifest Recorderfunctions/getCompositionManifest

DERIVED — correct

Mirrors PDF renderer logic exactly. Derives pdfW/pdfH from embedded asset. Uses same mask_bands lookup from TemplateGeometry entity.

Mask Geometry (DB)entities/TemplateGeometry + hooks/useTemplateGeometry.js

CORRECT when record exists

processMask() reads actual PNG W×H at upload time, stores mask_bands as normalized pct fractions. pdf_w and pdf_h stored on the record. Frontend uses these via useTemplateGeometry hook.

Frontend Geometry (fallback)lib/templateGeometry.js → getCanvasGeometry()

BROKEN — legacy constants

Used when no active TemplateGeometry record exists. Contains STD_H=1120 (phantom), angH=534 (wrong for Angel), LAND_H=593 (wrong for Navy Ship). These are the legacy constants flagged in Phase 3.

Composition Enginelib/compositionEngine.js → getLayoutForTemplate()

CORRECT with mask / BROKEN without

Thin wrapper. When maskOverride is passed (from useTemplateGeometry), mask wins and geometry is correct. When no mask record, falls back to templateGeometry.js hardcoded values.

Preview Surfacecomponents/letters/LetterPreviewCanvas

CORRECT with mask / BROKEN without

Calls useTemplateGeometry() → if record exists, uses mask geometry. Otherwise uses getLayoutForTemplate() with templateGeometry.js fallback.

Writer Surfacecomponents/editor/MultiPageEditorComposer

CORRECT with mask / BROKEN without

Same pattern as Preview. Mask record → correct. No record → falls back to STD_H=1120 etc.

Replay System(Phase 3 — not yet implemented)

PENDING — must not read templateGeometry.js

Will consume CompositionManifest. Manifest coordinates derive from PDF renderer runtime canvas. Replay must use manifest pdfW/pdfH — not templateGeometry.js constants.

Active TemplateGeometry Records (DB)

Click "Load DB Records" to inspect active TemplateGeometry records.