docs(renderer): record wrapped label rollout

2026-10-20 02:18:23 +00:00 · 2026-07-15 12:21:25 +07:00
1 parent d57009e63b
commit 2e1c3be0a4
@@ -0,0 +1,35 @@
+---
+date: 2026-07-15
+session: bold-wrapped-wheel-labels
+---
+
+# Journal: 2026-07-15 — Bold Wrapped Wheel Labels
+
+## Context
+
+Wheel labels needed bold typography and automatic line wrapping so long entries remained readable without changing the GIF API or wheel geometry.
+
+## What Happened
+
+- Added bold, Unicode-safe multiline label layout with balanced word-boundary wrapping and bounded line height.
+- Independent review exposed a 384px regression: short labels such as `alpha` wrapped because the first implementation wrapped before trying the supported one-line font-size range.
+- Corrected the layout order to preserve one-line text whenever it fits at 8px or larger, then wrap only when necessary.
+- Measured fit against content width after excluding horizontal padding, preventing padding from being counted twice.
+- Validation passed: lint, typecheck, 29 tests, render smoke and visual inspection, a 135-case layout probe, and independent review scored 9.7/10.
+
+## Reflection
+
+The initial wrapping feature handled long content but optimized the wrong constraint first. Minimum-size rendering needed explicit regression coverage at the smallest supported wheel size. Separating content width from padding and defining the 8px one-line threshold made the behavior deterministic across short, long, and unbroken labels.
+
+## Decisions Made
+
+| Decision | Rationale | Impact |
+|----------|-----------|--------|
+| Attempt one-line fit before wrapping | Short names should remain intact at supported sizes | Prevents unnecessary wrapping at 384px |
+| Use 8px as the one-line fit threshold | Preserves readability while allowing modest shrinking | Long labels wrap only after the readable one-line range is exhausted |
+| Exclude horizontal padding from content width | Layout measurements must represent the actual text box | Avoids double-counting padding and false overflow |
+| Keep the public API unchanged | The change is internal presentation behavior | Existing clients, routes, and winner metadata remain compatible |
+
+## Next Steps
+
+- No follow-up required; retain the minimum-size and multiline cases as regression coverage.
@@ -0,0 +1,57 @@
+---
+phase: 1
+title: Implementation
+status: completed
+priority: P1
+dependencies: []
+effort: small
+---
+
+# Phase 1: Implementation
+
+## Overview
+
+Add deterministic wrapped-label metadata to the pure layout helper and consume it in the Remotion composition. Keep the change local to wheel label presentation.
+
+## Requirements
+
+- Functional: split long labels into balanced lines, retain one line for short labels, size against the longest output line, render at bold weight, and clip overflow.
+- Non-functional: deterministic output across frames; JavaScript + JSDoc; no public API, theme, or wheel geometry changes.
+
+## Architecture
+
+`getRadialLabelLayout()` remains the composition-facing boundary. Extend its return value with the rendered line list and a bounded text-block height. A pure wrapping helper should normalize whitespace, prefer word boundaries, and choose the most balanced split whose longest estimated line best fits the radial track. Preserve text for unbroken long tokens with a deterministic fallback rather than relying on browser-dependent wrapping. Pass the longest returned line to `getLabelFontSize()` so wrapping reduces shrinkage without removing the existing minimum-size safeguard.
+
+`WheelComposition.jsx` renders the precomputed lines in a centered block using `fontWeight: 700`, compact line height, and explicit width/height plus `overflow: hidden`. Do not use ellipsis or `nowrap`, because the helper owns the line breaks.
+
+## Related Code Files
+
+- Modify: `C:/Users/miti99/Workspaces/tiennm99/wheelofnames/src/remotion/wheel-label-layout.js` — wrapping, longest-line sizing, returned layout metadata/JSDoc.
+- Modify: `C:/Users/miti99/Workspaces/tiennm99/wheelofnames/src/remotion/WheelComposition.jsx` — bold multi-line rendering and clipping.
+- Create: none.
+- Delete: none.
+
+## Implementation Steps
+
+1. Add a small exported pure helper for label-line selection. Return `[text]` when the base-size estimate fits; otherwise evaluate sensible word-boundary splits and select balanced lines by minimizing the longest estimated line, with deterministic handling for whitespace and single long tokens.
+2. Update `getRadialLabelLayout()` and its JSDoc shape to return `lines` and a bounded label-block height while computing `fontSize` from the longest returned line.
+3. Update the label element in `WheelComposition.jsx` to render the prepared lines at weight `700`, center them with compact multi-line spacing, and clip to the returned width/height.
+4. Preserve radial coordinates, rotation, slice rendering, color contrast, and all component props.
+
+## Success Criteria
+
+- [x] Short text yields one line and keeps the normal base size when space permits.
+- [x] Long phrase yields balanced multiple lines and a larger readable size than whole-label fitting would allow.
+- [x] Font size is calculated from the longest returned line.
+- [x] Rendered labels are bold, centered, and clipped inside their label box.
+- [x] No API/schema, theme, or wheel geometry file changes.
+
+## Risk Assessment
+
+- Dense wheels can have limited cross-track height. Mitigate with a bounded line count/height and clipping derived from existing label geometry.
+- Width estimates are approximate and bold glyphs are wider. Keep conservative padding and verify the rendered smoke GIF.
+- Unbroken or non-Latin text may not have word boundaries. Use deterministic grapheme-safe fallback behavior and cover it with a focused unit case if the helper supports splitting it.
+
+## Security Considerations
+
+No new input surface or HTML injection path. React continues to escape label text; preserve request validation and do not use raw HTML.
@@ -0,0 +1,56 @@
+---
+phase: 2
+title: Verification
+status: completed
+priority: P1
+dependencies:
+  - 1
+effort: small
+---
+
+# Phase 2: Verification
+
+## Overview
+
+Lock the layout contract with focused unit tests, then verify static quality gates and actual Remotion output.
+
+## Requirements
+
+- Functional: tests witness one-line, balanced multi-line, and longest-line sizing behavior.
+- Non-functional: all required repository gates pass; rendered smoke output completes without label-layout regressions.
+
+## Architecture
+
+Unit tests exercise the pure helpers so line-selection and sizing regressions fail cheaply. `render:smoke` is the visual/runtime witness for React styles, clipping, Chromium font layout, and GIF generation.
+
+## Related Code Files
+
+- Modify: `C:/Users/miti99/Workspaces/tiennm99/wheelofnames/test/wheel-label-layout.test.js` — focused wrapping and sizing assertions.
+- Witness: `C:/Users/miti99/Workspaces/tiennm99/wheelofnames/scripts/render-fixtures.js` via `pnpm render:smoke` — no planned script change.
+- Create: none.
+- Delete: none.
+
+## Implementation Steps
+
+1. Replace the old whole-label shrink expectation with assertions that a short label remains one line and a long phrase wraps into balanced lines.
+2. Assert the returned font size matches sizing based on the longest rendered line and is not based on the unsplit full label.
+3. Add edge coverage for whitespace normalization and/or a long unbroken label according to the implemented helper contract.
+4. Run `pnpm lint`, `pnpm typecheck`, and `pnpm test`.
+5. Run `pnpm render:smoke`; inspect command success and confirm the generated smoke frame/GIF does not overflow or truncate labels unexpectedly. Do not commit generated GIFs or temporary render artifacts.
+
+## Success Criteria
+
+- [x] `pnpm lint` passes.
+- [x] `pnpm typecheck` passes.
+- [x] `pnpm test` passes with focused wrapping witnesses.
+- [x] `pnpm render:smoke` passes and visually witnesses bold, readable labels without clipping.
+- [x] `git diff` contains only the planned source, test, and plan changes; no generated GIFs or secrets.
+
+## Risk Assessment
+
+- A smoke fixture may not contain a sufficiently long label. If its existing input cannot witness wrapping, make the smallest fixture-input adjustment without changing production API behavior; never commit the generated GIF.
+- Font rendering varies by host. Treat pure-helper tests as the deterministic contract and smoke rendering as integration evidence.
+
+## Security Considerations
+
+No security behavior changes. Ensure test fixtures contain only synthetic labels and no private data.
@@ -0,0 +1,51 @@
+---
+title: Bold Wrapped Wheel Labels
+description: >-
+  Render wheel option labels in bold and wrap long text into balanced lines
+  without changing the API or wheel geometry.
+status: completed
+priority: P2
+branch: main
+tags:
+  - feature
+  - frontend
+blockedBy: []
+blocks: []
+created: '2026-07-15T03:47:02.124Z'
+createdBy: 'ck:plan'
+source: skill
+---
+
+# Bold Wrapped Wheel Labels
+
+## Overview
+
+Replace whole-label shrink-to-fit behavior with deterministic multi-line layout. Short labels remain one line; long labels are split at sensible boundaries, balanced across the available radial track, and sized from the longest rendered line. The Remotion composition renders the returned lines at bold weight and clips the text block to its label area.
+
+## Scope
+
+- Modify label layout and rendering only.
+- Preserve `/api` request/response schemas, themes, and wheel geometry.
+- Use JavaScript + JSDoc and existing Remotion/CSS patterns; add no custom font or SVG work.
+
+## Phases
+
+| Phase | Name | Status |
+|-------|------|--------|
+| 1 | [Implementation](./phase-01-implementation.md) | Completed |
+| 2 | [Verification](./phase-02-verification.md) | Completed |
+
+## Dependencies
+
+- Cross-plan: none.
+- Runtime: existing React, Remotion, and CSS rendering stack.
+- Quality gates: Node.js 24, `pnpm lint`, `pnpm typecheck`, `pnpm test`, and `pnpm render:smoke`.
+
+## Acceptance Criteria
+
+- Labels render with a bold font weight.
+- Long labels become balanced multiple lines within the radial label track.
+- Font sizing uses the longest rendered line, not the original full label.
+- Short labels remain one line.
+- Multi-line content remains clipped within the computed label area.
+- API/schema, themes, and wheel geometry remain unchanged.
@@ -0,0 +1,27 @@
+{
+  "skill": "ck:code-review",
+  "mode": "review",
+  "task": "Independent re-review of the short-label wrapping fix",
+  "acceptanceCriteria": [
+    "labels use bold font weight",
+    "long labels wrap deterministically into balanced lines",
+    "font sizing uses the longest rendered line",
+    "short labels remain one line at every supported output size",
+    "multi-line content is clipped within a bounded label area",
+    "API schemas, routes, themes, slices, and radial geometry remain unchanged"
+  ],
+  "touchpoints": [
+    "src/remotion/wheel-label-layout.js",
+    "src/remotion/WheelComposition.jsx",
+    "test/wheel-label-layout.test.js"
+  ],
+  "publicContracts": [
+    "POST /api/gif request and response contract remains unchanged",
+    "getRadialLabelLayout supplies deterministic presentation metadata to the Remotion composition"
+  ],
+  "blastRadius": [
+    "wheel label line breaking, font sizing, padding, and clipping",
+    "Remotion label rendering at 384px, 480px, and 512px with 2-32 options"
+  ],
+  "scoutSummary": "The fix addresses the layout decision itself: it first computes a fitted one-line size and wraps only when that size reaches the existing 8px floor and slice height permits multiple lines. The padded content width is used for measurement while the unchanged track width remains the border-box width. No character-specific patch, API change, theme change, slice change, or radial-position change was found."
+}
@@ -0,0 +1,33 @@
+{
+  "decision": "PASS",
+  "score": 9.7,
+  "criticalCount": 0,
+  "warningCount": 0,
+  "suggestionCount": 0,
+  "criticals": [],
+  "warnings": [],
+  "suggestions": [],
+  "acceptanceCoverage": [
+    "fontWeight 700 is applied by the Remotion composition",
+    "short labels are fitted as one line before wrapping is considered",
+    "the original 384px alpha/beta/gamma/delta blocker is covered by an exact regression test and fresh direct probe",
+    "long labels wrap deterministically at word boundaries or Unicode grapheme boundaries and size from the longest rendered line",
+    "content width subtracts horizontal padding while the outer width remains the unchanged radial track width",
+    "height remains bounded by per-slice arc length and dense 32-option layouts stay to one line",
+    "API, schema, route, render flow, themes, slice geometry, contrast behavior, and radial coordinates are unchanged"
+  ],
+  "regressionProof": [
+    "lint and JSDoc typecheck pass",
+    "all 29 tests pass",
+    "the exact 384px probe keeps alpha, beta, gamma, and delta on one line",
+    "a 135-case supported-size, density, maximum-length, and Unicode matrix reports no failures",
+    "render smoke completes with a 407905-byte GIF in 3163ms"
+  ],
+  "contractStatus": "OK",
+  "blockingReasons": [],
+  "sideEffects": [
+    "the intended bold font changes text metrics",
+    "very long labels wrap only when one-line fitting would reach the 8px floor and slice height permits it",
+    "padding now consumes space inside the existing label width, preventing CSS border-box overflow"
+  ]
+}
@@ -0,0 +1,16 @@
+{
+  "highRisk": false,
+  "reasons": [
+    "presentation-only Remotion label layout change",
+    "the change retains the existing 8px font floor, three-line cap, track coordinates, slice geometry, contrast helper, and API contracts",
+    "candidate generation is bounded by the configured 40-character option limit and at most three lines"
+  ],
+  "autoStopRequired": false,
+  "humanApproved": true,
+  "largeDiff": false,
+  "sideEffects": [
+    "labels that cannot fit above the 8px floor may now wrap when slice height permits",
+    "label padding is now included inside the existing radial-track border box instead of increasing its rendered width",
+    "dense 32-option layouts remain one clipped line because their available slice height cannot support wrapping"
+  ]
+}
@@ -0,0 +1,50 @@
+{
+  "commands": [
+    {
+      "command": "pnpm lint",
+      "status": "pass",
+      "exitCode": 0,
+      "timestamp": "2026-07-15T11:21:43.4859125+07:00",
+      "summary": "ESLint completed without errors."
+    },
+    {
+      "command": "pnpm typecheck",
+      "status": "pass",
+      "exitCode": 0,
+      "timestamp": "2026-07-15T11:21:43.4859125+07:00",
+      "summary": "TypeScript JSDoc checking completed without errors."
+    },
+    {
+      "command": "pnpm test",
+      "status": "pass",
+      "exitCode": 0,
+      "timestamp": "2026-07-15T11:21:43.4859125+07:00",
+      "summary": "All 5 test files and 29 tests passed."
+    },
+    {
+      "command": "node --input-type=module -e <supported-size and Unicode layout matrix>",
+      "status": "pass",
+      "exitCode": 0,
+      "timestamp": "2026-07-15T11:21:43.4859125+07:00",
+      "summary": "All 135 cases passed across 384/480/512px, 2/4/8/16/32 options, 40-character text, emoji, ZWJ graphemes, and combining marks. The exact 384px four-option probe returned alpha=[alpha] at 21px, beta=[beta] at 22px, gamma=[gamma] at 20px, and delta=[delta] at 21px."
+    },
+    {
+      "command": "pnpm render:smoke",
+      "status": "pass",
+      "exitCode": 0,
+      "timestamp": "2026-07-15T11:21:43.4859125+07:00",
+      "summary": "Rendered a 407905-byte GIF in 3163ms; the generated fixture was removed after verification."
+    },
+    {
+      "command": "git diff --check",
+      "status": "pass",
+      "exitCode": 0,
+      "timestamp": "2026-07-15T11:21:43.4859125+07:00",
+      "summary": "No whitespace errors were reported."
+    }
+  ],
+  "beforeAfter": {
+    "before": "The first wrapping implementation broke common short labels at 384px because it wrapped at base size before attempting a modest one-line shrink, and CSS padding was not subtracted from the measured width.",
+    "after": "The layout first fits a single line against padded content width, wraps only at the 8px floor when height allows, and preserves the radial track as the outer border-box width."
+  }
+}