From 8fa94cbdb79a4b8c881fcbc79c985ad096416942 Mon Sep 17 00:00:00 2001
From: tqdat410 <danhlagi01472@gmail.com>
Date: Wed, 1 Apr 2026 11:05:54 +0700
Subject: [PATCH 01/12] feat: add text and shape styling API

Add textStyle and shapeStyle inputs, keep legacy aliases, and cover the new SVG styling behavior in unit and Playwright tests.

Co-authored-by: Codex <noreply@openai.com>
---
 e2e/fixtures/index.html                       |  60 +++++-
 e2e/fixtures/shape-text-e2e-app.js            |  87 +++++++-
 e2e/shape-text-local-e2e.spec.ts              |  58 +++++-
 src/index.ts                                  |   7 +
 src/layout/layout-text-in-compiled-shape.ts   |  10 +-
 src/layout/layout-text-in-shape.test.ts       |  27 +++
 src/layout/layout-text-in-shape.ts            |  15 +-
 src/render/normalize-shape-decoration.ts      |  59 ++++++
 src/render/render-layout-to-svg.test.ts       | 185 +++++++++++++++++-
 src/render/render-layout-to-svg.ts            | 109 +++++++++--
 src/render/render-svg-shadow-filter.ts        |  32 +++
 src/text/normalize-text-style-to-font.test.ts |  41 ++++
 src/text/normalize-text-style-to-font.ts      |  41 ++++
 src/types.ts                                  |  71 ++++++-
 14 files changed, 767 insertions(+), 35 deletions(-)
 create mode 100644 src/render/normalize-shape-decoration.ts
 create mode 100644 src/render/render-svg-shadow-filter.ts
 create mode 100644 src/text/normalize-text-style-to-font.test.ts
 create mode 100644 src/text/normalize-text-style-to-font.ts

diff --git a/e2e/fixtures/index.html b/e2e/fixtures/index.html
index ba6344e..a5de73d 100644
--- a/e2e/fixtures/index.html
+++ b/e2e/fixtures/index.html
@@ -117,6 +117,13 @@
         margin-top: 14px;
       }
 
+      .controls-grid {
+        display: grid;
+        grid-template-columns: repeat(2, minmax(0, 1fr));
+        gap: 12px;
+        margin-top: 14px;
+      }
+
       label {
         display: grid;
         gap: 6px;
@@ -138,6 +145,10 @@
         .panel-grid {
           grid-template-columns: 1fr;
         }
+
+        .controls-grid {
+          grid-template-columns: 1fr;
+        }
       }
     </style>
   </head>
@@ -146,14 +157,57 @@
       <section class="hero">
         <div class="card">
           <h1>shape-text demo</h1>
-          <p>Preview the current library in a real browser UI. Switch between polygon flow and glyph-mask flow, edit text, tweak line height, then render again.</p>
+          <p>Preview the current library in a real browser UI. Switch between polygon flow and glyph-mask flow, edit text, tweak text style and shape decoration, then render again.</p>
           <textarea id="text-input"></textarea>
-          <div class="control-row">
+          <div class="controls-grid">
             <label>
               Line height
               <input id="line-height-input" type="range" min="18" max="34" step="1" value="22" />
             </label>
-            <span>Current: <span id="line-height-value" class="metric">22</span>px</span>
+            <label>
+              Text size
+              <input id="text-size-input" type="range" min="14" max="34" step="1" value="18" />
+            </label>
+            <label>
+              Weight
+              <select id="text-weight-select">
+                <option value="400">Regular</option>
+                <option value="700" selected>Bold</option>
+              </select>
+            </label>
+            <label>
+              Text color
+              <input id="text-color-input" type="color" value="#111827" />
+            </label>
+            <label>
+              Shape fill
+              <input id="shape-fill-input" type="color" value="#dbeafe" />
+            </label>
+            <label>
+              Border color
+              <input id="shape-border-color-input" type="color" value="#94a3b8" />
+            </label>
+            <label>
+              Border width
+              <input id="shape-border-width-input" type="range" min="0" max="12" step="1" value="2" />
+            </label>
+          </div>
+          <div class="control-row">
+            <span>Line: <span id="line-height-value" class="metric">22</span>px</span>
+            <span>Text: <span id="text-size-value" class="metric">18</span>px</span>
+            <span>Border: <span id="shape-border-width-value" class="metric">2</span>px</span>
+            <label>
+              <input id="text-italic-input" type="checkbox" />
+              Italic
+            </label>
+            <label>
+              <input id="show-shape-input" type="checkbox" checked />
+              Show shape
+            </label>
+            <label>
+              <input id="shape-shadow-input" type="checkbox" checked />
+              Shadow
+            </label>
             <button id="render-button" class="primary-button" type="button">Render</button>
           </div>
         </div>
diff --git a/e2e/fixtures/shape-text-e2e-app.js b/e2e/fixtures/shape-text-e2e-app.js
index d4edf95..70b346b 100644
--- a/e2e/fixtures/shape-text-e2e-app.js
+++ b/e2e/fixtures/shape-text-e2e-app.js
@@ -10,6 +10,17 @@ const summary = document.querySelector('#summary')
 const textInput = document.querySelector('#text-input')
 const lineHeightInput = document.querySelector('#line-height-input')
 const lineHeightValue = document.querySelector('#line-height-value')
+const textSizeInput = document.querySelector('#text-size-input')
+const textSizeValue = document.querySelector('#text-size-value')
+const textWeightSelect = document.querySelector('#text-weight-select')
+const textItalicInput = document.querySelector('#text-italic-input')
+const textColorInput = document.querySelector('#text-color-input')
+const shapeFillInput = document.querySelector('#shape-fill-input')
+const shapeBorderWidthInput = document.querySelector('#shape-border-width-input')
+const shapeBorderWidthValue = document.querySelector('#shape-border-width-value')
+const shapeBorderColorInput = document.querySelector('#shape-border-color-input')
+const shapeShadowInput = document.querySelector('#shape-shadow-input')
+const showShapeInput = document.querySelector('#show-shape-input')
 const renderButton = document.querySelector('#render-button')
 const measurer = createCanvasTextMeasurer()
 
@@ -57,7 +68,6 @@ const scenarios = {
     },
     autoFill: true,
     text: 'ONE',
-    showShape: false,
   },
   'digit-two-wide': {
     shape: { kind: 'polygon', points: createDigitTwoPolygon(340, 460) },
@@ -99,6 +109,41 @@ const state = {
   svg: '',
   text: 'ONE',
   lineHeight: 22,
+  textSize: 18,
+  textWeight: 700,
+  textItalic: false,
+  textColor: '#111827',
+  showShape: true,
+  shapeFill: '#dbeafe',
+  shapeBorderWidth: 2,
+  shapeBorderColor: '#94a3b8',
+  shapeShadow: true,
+}
+
+function getTextStyle() {
+  return {
+    family: '"Helvetica Neue", Arial, sans-serif',
+    size: state.textSize,
+    weight: state.textWeight,
+    style: state.textItalic ? 'italic' : 'normal',
+    color: state.textColor,
+  }
+}
+
+function getShapeStyle() {
+  return {
+    backgroundColor: state.shapeFill,
+    borderColor: state.shapeBorderColor,
+    borderWidth: state.shapeBorderWidth,
+    shadow: state.shapeShadow
+      ? {
+          color: 'rgba(15, 23, 42, 0.22)',
+          blur: 6,
+          offsetX: 0,
+          offsetY: 6,
+        }
+      : undefined,
+  }
 }
 
 function renderScenario(name) {
@@ -109,7 +154,7 @@ function renderScenario(name) {
 
   const layout = layoutTextInShape({
     text: state.text,
-    font: '16px "Helvetica Neue", Arial, sans-serif',
+    textStyle: getTextStyle(),
     lineHeight: state.lineHeight,
     shape: scenario.shape,
     measurer,
@@ -119,10 +164,8 @@ function renderScenario(name) {
 
   const svg = renderLayoutToSvg(layout, {
     background: '#fffdf7',
-    textFill: '#111827',
-    shapeStroke: '#94a3b8',
-    shapeFill: 'rgba(191, 219, 254, 0.18)',
-    showShape: scenario.showShape ?? true,
+    shapeStyle: getShapeStyle(),
+    showShape: state.showShape,
     padding: 12,
   })
 
@@ -137,6 +180,8 @@ function renderScenario(name) {
       shapeKind: scenario.shape.kind,
       autoFill: Boolean(scenario.autoFill),
       lineHeight: state.lineHeight,
+      textStyle: getTextStyle(),
+      shapeStyle: getShapeStyle(),
       lineCount: layout.lines.length,
       exhausted: layout.exhausted,
       firstLine: layout.lines[0]?.text ?? null,
@@ -200,12 +245,34 @@ function syncControls() {
   textInput.value = state.text
   lineHeightInput.value = String(state.lineHeight)
   lineHeightValue.textContent = String(state.lineHeight)
+  textSizeInput.value = String(state.textSize)
+  textSizeValue.textContent = String(state.textSize)
+  textWeightSelect.value = String(state.textWeight)
+  textItalicInput.checked = state.textItalic
+  textColorInput.value = state.textColor
+  showShapeInput.checked = state.showShape
+  shapeFillInput.value = state.shapeFill
+  shapeBorderWidthInput.value = String(state.shapeBorderWidth)
+  shapeBorderWidthValue.textContent = String(state.shapeBorderWidth)
+  shapeBorderColorInput.value = state.shapeBorderColor
+  shapeShadowInput.checked = state.shapeShadow
 }
 
 renderButton.addEventListener('click', () => {
   state.text = textInput.value
   state.lineHeight = Number(lineHeightInput.value)
+  state.textSize = Number(textSizeInput.value)
+  state.textWeight = Number(textWeightSelect.value)
+  state.textItalic = textItalicInput.checked
+  state.textColor = textColorInput.value
+  state.showShape = showShapeInput.checked
+  state.shapeFill = shapeFillInput.value
+  state.shapeBorderWidth = Number(shapeBorderWidthInput.value)
+  state.shapeBorderColor = shapeBorderColorInput.value
+  state.shapeShadow = shapeShadowInput.checked
   lineHeightValue.textContent = String(state.lineHeight)
+  textSizeValue.textContent = String(state.textSize)
+  shapeBorderWidthValue.textContent = String(state.shapeBorderWidth)
   renderScenario(state.scenario || 'digit-two-wide')
 })
 
@@ -213,6 +280,14 @@ lineHeightInput.addEventListener('input', () => {
   lineHeightValue.textContent = lineHeightInput.value
 })
 
+textSizeInput.addEventListener('input', () => {
+  textSizeValue.textContent = textSizeInput.value
+})
+
+shapeBorderWidthInput.addEventListener('input', () => {
+  shapeBorderWidthValue.textContent = shapeBorderWidthInput.value
+})
+
 document.querySelectorAll('[data-scenario]').forEach(button => {
   button.addEventListener('click', () => {
     renderScenario(button.getAttribute('data-scenario'))
diff --git a/e2e/shape-text-local-e2e.spec.ts b/e2e/shape-text-local-e2e.spec.ts
index 5a6831d..d82443b 100644
--- a/e2e/shape-text-local-e2e.spec.ts
+++ b/e2e/shape-text-local-e2e.spec.ts
@@ -24,6 +24,15 @@ declare global {
           }>
         }
         text: string
+        textSize: number
+        textWeight: number
+        textItalic: boolean
+        textColor: string
+        showShape: boolean
+        shapeFill: string
+        shapeBorderWidth: number
+        shapeBorderColor: string
+        shapeShadow: boolean
         svg: string
       }
     }
@@ -34,6 +43,22 @@ async function getState(page: import('@playwright/test').Page) {
   return page.evaluate(() => window.shapeTextTestApi.getState())
 }
 
+async function setRangeValue(
+  page: import('@playwright/test').Page,
+  selector: string,
+  value: string,
+) {
+  await page.locator(selector).evaluate((element, nextValue) => {
+    if (!(element instanceof HTMLInputElement)) {
+      throw new Error('Expected an input element')
+    }
+
+    element.value = nextValue
+    element.dispatchEvent(new Event('input', { bubbles: true }))
+    element.dispatchEvent(new Event('change', { bubbles: true }))
+  }, value)
+}
+
 test('renders the glyph text-mask fixture into SVG', async ({ page }) => {
   await page.goto('/')
   await expect(page.locator('#stage svg')).toBeVisible()
@@ -46,7 +71,12 @@ test('renders the glyph text-mask fixture into SVG', async ({ page }) => {
   expect(state.layout.autoFill).toBe(true)
   expect(state.layout.exhausted).toBe(false)
   expect(state.layout.lines[0]?.text).toContain('ONE')
-  await expect(page.locator('#stage text')).toHaveCount(state.layout.lines.length)
+  expect(state.textSize).toBe(18)
+  const expectedTextNodeCount =
+    state.showShape && state.scenario === 'glyph-two-repeat'
+      ? state.layout.lines.length + 1
+      : state.layout.lines.length
+  await expect(page.locator('#stage text')).toHaveCount(expectedTextNodeCount)
 })
 
 test('reuses the cached compiled glyph shape for repeated text-mask requests', async ({
@@ -72,6 +102,32 @@ test('rejects invalid text-mask alpha thresholds with a clear error', async ({ p
   expect(errorMessage).toContain('alphaThreshold')
 })
 
+test('applies text and shape style controls to the rendered SVG', async ({ page }) => {
+  await page.goto('/')
+
+  await setRangeValue(page, '#text-size-input', '28')
+  await page.locator('#text-weight-select').selectOption('700')
+  await page.locator('#text-italic-input').check()
+  await page.locator('#text-color-input').fill('#ef4444')
+  await page.locator('#shape-fill-input').fill('#fde68a')
+  await setRangeValue(page, '#shape-border-width-input', '6')
+  await page.locator('#shape-border-color-input').fill('#f59e0b')
+  await page.locator('#shape-shadow-input').check()
+  await page.locator('#render-button').click()
+
+  const state = await getState(page)
+
+  expect(state.textSize).toBe(28)
+  expect(state.textItalic).toBe(true)
+  expect(state.shapeBorderWidth).toBe(6)
+  expect(state.svg).toContain('font:italic 700 28px')
+  expect(state.svg).toContain('fill="#ef4444"')
+  expect(state.svg).toContain('stroke="#f59e0b"')
+  expect(state.svg).toContain('stroke-width="6"')
+  expect(state.svg).toContain('fill="#fde68a"')
+  expect(state.svg).toContain('shape-text-shape-shadow')
+})
+
 test('reflows into more lines in the narrow rectangle scenario', async ({ page }) => {
   await page.goto('/')
 
diff --git a/src/index.ts b/src/index.ts
index becfd5c..d467df8 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -11,16 +11,23 @@ export type {
   PreparedLayoutText,
   PreparedLayoutToken,
   RenderLayoutToSvgOptions,
+  ResolvedShapeShadow,
+  ResolvedShapeStyle,
+  ResolvedTextStyle,
   ShapeInput,
   ShapeBounds,
+  ShapeShadowInput,
+  ShapeStyleInput,
   ShapeTextLayout,
   ShapeTextLine,
   ShapeTextPoint,
   TextMaskShape,
+  TextStyleInput,
   TextMeasurer,
 } from './types.js'
 
 export { createCanvasTextMeasurer } from './text/create-canvas-text-measurer.js'
+export { normalizeTextStyleToFont, resolveLayoutTextStyle } from './text/normalize-text-style-to-font.js'
 export { prepareTextForLayout } from './text/prepare-text-for-layout.js'
 export { layoutNextLineFromPreparedText } from './text/layout-next-line-from-prepared-text.js'
 export { layoutNextLineFromRepeatedText } from './text/layout-next-line-from-repeated-text.js'
diff --git a/src/layout/layout-text-in-compiled-shape.ts b/src/layout/layout-text-in-compiled-shape.ts
index 1110b6d..9003368 100644
--- a/src/layout/layout-text-in-compiled-shape.ts
+++ b/src/layout/layout-text-in-compiled-shape.ts
@@ -7,6 +7,7 @@ import type {
 } from '../types.js'
 import { layoutNextLineFromPreparedText } from '../text/layout-next-line-from-prepared-text.js'
 import { layoutNextLineFromRepeatedText } from '../text/layout-next-line-from-repeated-text.js'
+import { resolveLayoutTextStyle } from '../text/normalize-text-style-to-font.js'
 import { prepareTextForLayout } from '../text/prepare-text-for-layout.js'
 
 function pickWidestInterval(intervals: Interval[]): Interval {
@@ -25,7 +26,11 @@ function pickWidestInterval(intervals: Interval[]): Interval {
 export function layoutTextInCompiledShape(
   options: LayoutTextInCompiledShapeOptions,
 ): ShapeTextLayout {
-  const prepared = prepareTextForLayout(options.text, options.font, options.measurer)
+  const resolvedTextStyle = resolveLayoutTextStyle({
+    font: options.font,
+    textStyle: options.textStyle,
+  })
+  const prepared = prepareTextForLayout(options.text, resolvedTextStyle.font, options.measurer)
   const autoFill = options.autoFill ?? false
   const align = options.align ?? 'left'
   const baselineRatio = options.baselineRatio ?? 0.8
@@ -64,7 +69,8 @@ export function layoutTextInCompiledShape(
   }
 
   return {
-    font: options.font,
+    font: resolvedTextStyle.font,
+    textStyle: resolvedTextStyle,
     lineHeight: options.compiledShape.bandHeight,
     shape: options.compiledShape.source,
     compiledShape: options.compiledShape,
diff --git a/src/layout/layout-text-in-shape.test.ts b/src/layout/layout-text-in-shape.test.ts
index c501baf..f5a6797 100644
--- a/src/layout/layout-text-in-shape.test.ts
+++ b/src/layout/layout-text-in-shape.test.ts
@@ -103,4 +103,31 @@ describe('layoutTextInShape', () => {
     expect(layout.autoFill).toBe(true)
     expect(layout.exhausted).toBe(false)
   })
+
+  it('normalizes textStyle into the resolved layout font and color', () => {
+    const layout = layoutTextInShape({
+      text: 'xin chao',
+      textStyle: {
+        family: 'Test Sans',
+        size: 18,
+        weight: 700,
+        style: 'italic',
+        color: '#2563eb',
+      },
+      lineHeight: 20,
+      shape: {
+        kind: 'polygon',
+        points: [
+          { x: 0, y: 0 },
+          { x: 120, y: 0 },
+          { x: 120, y: 40 },
+          { x: 0, y: 40 },
+        ],
+      },
+      measurer: createFixedWidthTextMeasurer(),
+    })
+
+    expect(layout.font).toBe('italic 700 18px Test Sans')
+    expect(layout.textStyle?.color).toBe('#2563eb')
+  })
 })
diff --git a/src/layout/layout-text-in-shape.ts b/src/layout/layout-text-in-shape.ts
index 245859b..529204f 100644
--- a/src/layout/layout-text-in-shape.ts
+++ b/src/layout/layout-text-in-shape.ts
@@ -9,9 +9,22 @@ export function layoutTextInShape(options: LayoutTextInShapeOptions): ShapeTextL
     minSlotWidth: options.minSlotWidth,
   })
 
+  if (options.textStyle !== undefined) {
+    return layoutTextInCompiledShape({
+      text: options.text,
+      font: options.font,
+      textStyle: options.textStyle,
+      compiledShape,
+      measurer: options.measurer,
+      align: options.align,
+      baselineRatio: options.baselineRatio,
+      autoFill: options.autoFill,
+    })
+  }
+
   return layoutTextInCompiledShape({
     text: options.text,
-    font: options.font,
+    font: options.font!,
     compiledShape,
     measurer: options.measurer,
     align: options.align,
diff --git a/src/render/normalize-shape-decoration.ts b/src/render/normalize-shape-decoration.ts
new file mode 100644
index 0000000..cb3f1ab
--- /dev/null
+++ b/src/render/normalize-shape-decoration.ts
@@ -0,0 +1,59 @@
+import type {
+  RenderLayoutToSvgOptions,
+  ResolvedShapeStyle,
+  ShapeShadowInput,
+} from '../types.js'
+
+function assertFiniteNonNegative(value: number, message: string): void {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new Error(message)
+  }
+}
+
+function normalizeShadow(shadow: ShapeShadowInput | undefined): ResolvedShapeStyle['shadow'] {
+  if (shadow === undefined) {
+    return undefined
+  }
+
+  assertFiniteNonNegative(shadow.blur, 'shapeStyle.shadow.blur must be a finite non-negative number')
+
+  const offsetX = shadow.offsetX ?? 0
+  const offsetY = shadow.offsetY ?? 0
+  if (!Number.isFinite(offsetX) || !Number.isFinite(offsetY)) {
+    throw new Error('shapeStyle.shadow offsets must be finite numbers')
+  }
+
+  return {
+    color: shadow.color ?? 'rgba(15, 23, 42, 0.24)',
+    blur: shadow.blur,
+    offsetX,
+    offsetY,
+  }
+}
+
+export function normalizeShapeDecoration(
+  options: RenderLayoutToSvgOptions,
+): ResolvedShapeStyle {
+  const explicitBorderWidth = options.shapeStyle?.borderWidth
+  if (explicitBorderWidth !== undefined) {
+    assertFiniteNonNegative(
+      explicitBorderWidth,
+      'shapeStyle.borderWidth must be a finite non-negative number',
+    )
+  }
+
+  const borderWidth =
+    explicitBorderWidth ??
+    (options.shapeStyle?.borderColor !== undefined
+      ? 1
+      : options.shapeStyle === undefined && (options.shapeStroke !== undefined || options.showShape === true)
+        ? 1
+        : 0)
+
+  return {
+    backgroundColor: options.shapeStyle?.backgroundColor ?? options.shapeFill,
+    borderColor: options.shapeStyle?.borderColor ?? options.shapeStroke ?? '#d1d5db',
+    borderWidth,
+    shadow: normalizeShadow(options.shapeStyle?.shadow),
+  }
+}
diff --git a/src/render/render-layout-to-svg.test.ts b/src/render/render-layout-to-svg.test.ts
index 54e5a9c..1a37e3b 100644
--- a/src/render/render-layout-to-svg.test.ts
+++ b/src/render/render-layout-to-svg.test.ts
@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest'
 
 import { layoutTextInShape } from '../layout/layout-text-in-shape.js'
 import { renderLayoutToSvg } from './render-layout-to-svg.js'
-import type { TextMeasurer } from '../types.js'
+import type { ShapeTextLayout, TextMeasurer } from '../types.js'
 
 const measurer: TextMeasurer = {
   measureText(text) {
@@ -35,4 +35,187 @@ describe('renderLayoutToSvg', () => {
     expect(svg).toContain('<polygon')
     expect(svg).toContain('<text')
   })
+
+  it('uses textStyle color by default and shapeStyle decoration when requested', () => {
+    const layout = layoutTextInShape({
+      text: 'shape text',
+      textStyle: {
+        family: 'Test Sans',
+        size: 20,
+        weight: 700,
+        style: 'italic',
+        color: '#dc2626',
+      },
+      lineHeight: 20,
+      shape: {
+        kind: 'polygon',
+        points: [
+          { x: 0, y: 0 },
+          { x: 200, y: 0 },
+          { x: 200, y: 40 },
+          { x: 0, y: 40 },
+        ],
+      },
+      measurer,
+    })
+
+    const svg = renderLayoutToSvg(layout, {
+      shapeStyle: {
+        backgroundColor: '#fef3c7',
+        borderColor: '#f59e0b',
+        borderWidth: 4,
+        shadow: {
+          color: 'rgba(15, 23, 42, 0.25)',
+          blur: 6,
+          offsetX: 2,
+          offsetY: 3,
+        },
+      },
+    })
+
+    expect(svg).toContain('fill="#dc2626"')
+    expect(svg).toContain('stroke="#f59e0b"')
+    expect(svg).toContain('stroke-width="4"')
+    expect(svg).toContain('fill="#fef3c7"')
+    expect(svg).toContain('<filter id="shape-text-shape-shadow-')
+    expect(svg).toContain('filterUnits="userSpaceOnUse"')
+    expect(svg).toContain('style="font:italic 700 20px Test Sans;"')
+  })
+
+  it('lets render options override text fill color for the same layout', () => {
+    const layout = layoutTextInShape({
+      text: 'override',
+      textStyle: {
+        family: 'Test Sans',
+        size: 16,
+        color: '#2563eb',
+      },
+      lineHeight: 20,
+      shape: {
+        kind: 'polygon',
+        points: [
+          { x: 0, y: 0 },
+          { x: 200, y: 0 },
+          { x: 200, y: 40 },
+          { x: 0, y: 40 },
+        ],
+      },
+      measurer,
+    })
+
+    const svg = renderLayoutToSvg(layout, {
+      textFill: '#16a34a',
+    })
+
+    expect(svg).toContain('fill="#16a34a"')
+    expect(svg).not.toContain('fill="#2563eb"')
+  })
+
+  it('does not inject a border when shapeStyle only sets background color', () => {
+    const layout = layoutTextInShape({
+      text: 'fill only',
+      font: '16px Test Sans',
+      lineHeight: 20,
+      shape: {
+        kind: 'polygon',
+        points: [
+          { x: 0, y: 0 },
+          { x: 200, y: 0 },
+          { x: 200, y: 40 },
+          { x: 0, y: 40 },
+        ],
+      },
+      measurer,
+    })
+
+    const svg = renderLayoutToSvg(layout, {
+      shapeStyle: {
+        backgroundColor: '#fef3c7',
+      },
+    })
+
+    expect(svg).toContain('stroke-width="0"')
+    expect(svg).toContain('fill="#fef3c7"')
+  })
+
+  it('expands the viewport for borders and shadows without manual padding', () => {
+    const layout = layoutTextInShape({
+      text: 'shadow',
+      font: '16px Test Sans',
+      lineHeight: 20,
+      shape: {
+        kind: 'polygon',
+        points: [
+          { x: 0, y: 0 },
+          { x: 200, y: 0 },
+          { x: 200, y: 40 },
+          { x: 0, y: 40 },
+        ],
+      },
+      measurer,
+    })
+
+    const svg = renderLayoutToSvg(layout, {
+      padding: 0,
+      shapeStyle: {
+        borderColor: '#0f172a',
+        borderWidth: 8,
+        shadow: {
+          blur: 10,
+          offsetX: 6,
+          offsetY: 4,
+        },
+      },
+    })
+
+    expect(svg).toContain('viewBox="-34 -34 274 112"')
+  })
+
+  it('renders a legacy layout object without textStyle metadata', () => {
+    const svg = renderLayoutToSvg({
+      font: '16px Test Sans',
+      lineHeight: 20,
+      shape: {
+        kind: 'polygon',
+        points: [
+          { x: 0, y: 0 },
+          { x: 200, y: 0 },
+          { x: 200, y: 40 },
+          { x: 0, y: 40 },
+        ],
+      },
+      compiledShape: {
+        kind: 'polygon',
+        source: {
+          kind: 'polygon',
+          points: [
+            { x: 0, y: 0 },
+            { x: 200, y: 0 },
+            { x: 200, y: 40 },
+            { x: 0, y: 40 },
+          ],
+        },
+        bounds: { left: 0, top: 0, right: 200, bottom: 40 },
+        bandHeight: 20,
+        minSlotWidth: 16,
+        bands: [],
+        debugView: {
+          kind: 'polygon',
+          points: [
+            { x: 0, y: 0 },
+            { x: 200, y: 0 },
+            { x: 200, y: 40 },
+            { x: 0, y: 40 },
+          ],
+        },
+      },
+      bounds: { left: 0, top: 0, right: 200, bottom: 40 },
+      lines: [],
+      exhausted: true,
+      autoFill: false,
+    } satisfies ShapeTextLayout)
+
+    expect(svg).toContain('<svg')
+    expect(svg).not.toContain('undefined')
+  })
 })
diff --git a/src/render/render-layout-to-svg.ts b/src/render/render-layout-to-svg.ts
index b182ed6..d4e3e27 100644
--- a/src/render/render-layout-to-svg.ts
+++ b/src/render/render-layout-to-svg.ts
@@ -4,55 +4,130 @@ import type {
   ShapeTextLayout,
   ShapeTextPoint,
 } from '../types.js'
+import { createSvgShadowFilter } from './render-svg-shadow-filter.js'
+import { normalizeShapeDecoration } from './normalize-shape-decoration.js'
 import { escapeXmlText } from './escape-xml-text.js'
 
 function renderPoints(points: ShapeTextPoint[]): string {
   return points.map(point => `${point.x},${point.y}`).join(' ')
 }
 
-function renderDebugShape(
+function getEffectPadding(options: {
+  strokeWidth: number
+  shadow?: {
+    blur: number
+    offsetX: number
+    offsetY: number
+  }
+}) {
+  const strokePadding = options.strokeWidth / 2
+  const shadowBlurPadding = options.shadow === undefined ? 0 : options.shadow.blur * 3
+
+  return {
+    left:
+      strokePadding +
+      (options.shadow === undefined ? 0 : shadowBlurPadding + Math.max(0, -options.shadow.offsetX)),
+    right:
+      strokePadding +
+      (options.shadow === undefined ? 0 : shadowBlurPadding + Math.max(0, options.shadow.offsetX)),
+    top:
+      strokePadding +
+      (options.shadow === undefined ? 0 : shadowBlurPadding + Math.max(0, -options.shadow.offsetY)),
+    bottom:
+      strokePadding +
+      (options.shadow === undefined ? 0 : shadowBlurPadding + Math.max(0, options.shadow.offsetY)),
+  }
+}
+
+function renderShapeAttributes(
   debugView: CompiledShapeDebugView,
-  shapeFill: string,
-  shapeStroke: string,
+  options: {
+    fill: string
+    stroke: string
+    strokeWidth: number
+    filterUrl?: string
+  },
 ): string {
+  const filter = options.filterUrl === undefined ? '' : ` filter="${options.filterUrl}"`
+  const fill = escapeXmlText(options.fill)
+  const stroke = escapeXmlText(options.stroke)
+
   if (debugView.kind === 'polygon') {
-    return `<polygon points="${renderPoints(debugView.points)}" fill="${shapeFill}" stroke="${shapeStroke}" stroke-width="1" />`
+    return `<polygon points="${renderPoints(debugView.points)}" fill="${fill}" stroke="${stroke}" stroke-width="${options.strokeWidth}"${filter} />`
   }
 
-  return `<text x="${debugView.x}" y="${debugView.baseline}" fill="${shapeFill}" stroke="${shapeStroke}" stroke-width="1" style="font:${escapeXmlText(debugView.font)};">${escapeXmlText(debugView.text)}</text>`
+  return `<text x="${debugView.x}" y="${debugView.baseline}" fill="${fill}" stroke="${stroke}" stroke-width="${options.strokeWidth}"${filter} style="font:${escapeXmlText(debugView.font)};">${escapeXmlText(debugView.text)}</text>`
 }
 
 export function renderLayoutToSvg(
   layout: ShapeTextLayout,
   options: RenderLayoutToSvgOptions = {},
 ): string {
-  const padding = options.padding ?? 0
-  const width = layout.bounds.right - layout.bounds.left + padding * 2
-  const height = layout.bounds.bottom - layout.bounds.top + padding * 2
-  const viewBoxLeft = layout.bounds.left - padding
-  const viewBoxTop = layout.bounds.top - padding
-  const textFill = options.textFill ?? '#111827'
-  const shapeStroke = options.shapeStroke ?? '#d1d5db'
-  const shapeFill = options.shapeFill ?? 'none'
+  const userPadding = options.padding ?? 0
+  const textFill = options.textFill ?? layout.textStyle?.color ?? '#111827'
+  const shapeStyle = normalizeShapeDecoration(options)
   const background = options.background
-  const showShape = options.showShape ?? false
+  const hasVisibleCanonicalShapeDecoration =
+    options.shapeStyle !== undefined &&
+    (shapeStyle.backgroundColor !== undefined ||
+      shapeStyle.borderWidth > 0 ||
+      shapeStyle.shadow !== undefined)
+  const showShape = options.showShape ?? hasVisibleCanonicalShapeDecoration
+  const effectPadding = showShape
+    ? getEffectPadding({
+        strokeWidth: shapeStyle.borderWidth,
+        shadow: shapeStyle.shadow,
+      })
+    : { left: 0, right: 0, top: 0, bottom: 0 }
+  const totalPadding = {
+    left: userPadding + effectPadding.left,
+    right: userPadding + effectPadding.right,
+    top: userPadding + effectPadding.top,
+    bottom: userPadding + effectPadding.bottom,
+  }
+  const width = layout.bounds.right - layout.bounds.left + totalPadding.left + totalPadding.right
+  const height = layout.bounds.bottom - layout.bounds.top + totalPadding.top + totalPadding.bottom
+  const viewBoxLeft = layout.bounds.left - totalPadding.left
+  const viewBoxTop = layout.bounds.top - totalPadding.top
+  const shadowFilter =
+    showShape && shapeStyle.shadow !== undefined
+      ? createSvgShadowFilter(shapeStyle.shadow, {
+          x: viewBoxLeft,
+          y: viewBoxTop,
+          width,
+          height,
+        })
+      : undefined
 
   const pieces = [
     `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${viewBoxLeft} ${viewBoxTop} ${width} ${height}" width="${width}" height="${height}">`,
   ]
 
+  if (shadowFilter !== undefined) {
+    pieces.push(shadowFilter.markup)
+  }
+
   if (background !== undefined) {
-    pieces.push(`<rect x="${viewBoxLeft}" y="${viewBoxTop}" width="${width}" height="${height}" fill="${background}" />`)
+    pieces.push(
+      `<rect x="${viewBoxLeft}" y="${viewBoxTop}" width="${width}" height="${height}" fill="${escapeXmlText(background)}" />`,
+    )
   }
 
   if (showShape) {
-    pieces.push(renderDebugShape(layout.compiledShape.debugView, shapeFill, shapeStroke))
+    pieces.push(
+      renderShapeAttributes(layout.compiledShape.debugView, {
+        fill: shapeStyle.backgroundColor ?? 'none',
+        stroke: shapeStyle.borderColor,
+        strokeWidth: shapeStyle.borderWidth,
+        filterUrl: shadowFilter === undefined ? undefined : `url(#${shadowFilter.filterId})`,
+      }),
+    )
   }
 
   for (let index = 0; index < layout.lines.length; index++) {
     const line = layout.lines[index]!
     pieces.push(
-      `<text x="${line.x}" y="${line.baseline}" fill="${textFill}" style="font:${escapeXmlText(layout.font)};">${escapeXmlText(line.text)}</text>`,
+      `<text x="${line.x}" y="${line.baseline}" fill="${escapeXmlText(textFill)}" style="font:${escapeXmlText(layout.font)};">${escapeXmlText(line.text)}</text>`,
     )
   }
 
diff --git a/src/render/render-svg-shadow-filter.ts b/src/render/render-svg-shadow-filter.ts
new file mode 100644
index 0000000..bfb26ec
--- /dev/null
+++ b/src/render/render-svg-shadow-filter.ts
@@ -0,0 +1,32 @@
+import type { ResolvedShapeShadow } from '../types.js'
+import { escapeXmlText } from './escape-xml-text.js'
+
+function hashString(value: string): string {
+  let hash = 0
+
+  for (let index = 0; index < value.length; index++) {
+    hash = (hash * 31 + value.charCodeAt(index)) >>> 0
+  }
+
+  return hash.toString(36)
+}
+
+export function createSvgShadowFilter(
+  shadow: ResolvedShapeShadow,
+  filterRegion: {
+    x: number
+    y: number
+    width: number
+    height: number
+  },
+): {
+  filterId: string
+  markup: string
+} {
+  const filterId = `shape-text-shape-shadow-${hashString(JSON.stringify(shadow))}`
+
+  return {
+    filterId,
+    markup: `<defs><filter id="${filterId}" filterUnits="userSpaceOnUse" x="${filterRegion.x}" y="${filterRegion.y}" width="${filterRegion.width}" height="${filterRegion.height}"><feDropShadow dx="${shadow.offsetX}" dy="${shadow.offsetY}" stdDeviation="${shadow.blur}" flood-color="${escapeXmlText(shadow.color)}" /></filter></defs>`,
+  }
+}
diff --git a/src/text/normalize-text-style-to-font.test.ts b/src/text/normalize-text-style-to-font.test.ts
new file mode 100644
index 0000000..3b508c3
--- /dev/null
+++ b/src/text/normalize-text-style-to-font.test.ts
@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest'
+
+import { normalizeTextStyleToFont, resolveLayoutTextStyle } from './normalize-text-style-to-font.js'
+
+describe('normalizeTextStyleToFont', () => {
+  it('builds a canonical CSS font string from text style input', () => {
+    expect(
+      normalizeTextStyleToFont({
+        family: '"Helvetica Neue", Arial, sans-serif',
+        size: 18,
+        weight: 700,
+        style: 'italic',
+        color: '#0f172a',
+      }),
+    ).toEqual({
+      family: '"Helvetica Neue", Arial, sans-serif',
+      size: 18,
+      weight: 700,
+      style: 'italic',
+      color: '#0f172a',
+      font: 'italic 700 18px "Helvetica Neue", Arial, sans-serif',
+    })
+  })
+
+  it('uses the new textStyle API over the legacy font string', () => {
+    const resolved = resolveLayoutTextStyle({
+      font: '16px Old Font',
+      textStyle: {
+        family: 'Test Sans',
+        size: 24,
+        style: 'oblique',
+      },
+    })
+
+    expect(resolved.font).toBe('oblique 400 24px Test Sans')
+  })
+
+  it('rejects missing font inputs', () => {
+    expect(() => resolveLayoutTextStyle({})).toThrow('font or textStyle')
+  })
+})
diff --git a/src/text/normalize-text-style-to-font.ts b/src/text/normalize-text-style-to-font.ts
new file mode 100644
index 0000000..63563b8
--- /dev/null
+++ b/src/text/normalize-text-style-to-font.ts
@@ -0,0 +1,41 @@
+import type { ResolvedTextStyle, TextStyleInput } from '../types.js'
+
+function assertFinitePositiveSize(size: number): void {
+  if (!Number.isFinite(size) || size <= 0) {
+    throw new Error('textStyle.size must be a finite positive number')
+  }
+}
+
+export function normalizeTextStyleToFont(textStyle: TextStyleInput): ResolvedTextStyle {
+  if (textStyle.family.trim().length === 0) {
+    throw new Error('textStyle.family must be a non-empty string')
+  }
+
+  assertFinitePositiveSize(textStyle.size)
+
+  return {
+    family: textStyle.family,
+    size: textStyle.size,
+    weight: textStyle.weight ?? 400,
+    style: textStyle.style ?? 'normal',
+    color: textStyle.color,
+    font: `${textStyle.style ?? 'normal'} ${String(textStyle.weight ?? 400)} ${textStyle.size}px ${textStyle.family}`,
+  }
+}
+
+export function resolveLayoutTextStyle(options: {
+  font?: string
+  textStyle?: TextStyleInput
+}): ResolvedTextStyle {
+  if (options.textStyle !== undefined) {
+    return normalizeTextStyleToFont(options.textStyle)
+  }
+
+  if (options.font !== undefined && options.font.trim().length > 0) {
+    return {
+      font: options.font,
+    }
+  }
+
+  throw new Error('layout text requires either font or textStyle')
+}
diff --git a/src/types.ts b/src/types.ts
index 0fccc0e..0e6fca7 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -30,6 +30,51 @@ export type TextMeasurer = {
   measureText(text: string, font: string): number
 }
 
+export type TextStyleInput = {
+  family: string
+  size: number
+  weight?: number | string
+  style?: 'normal' | 'italic' | 'oblique'
+  color?: string
+}
+
+export type ResolvedTextStyle = {
+  font: string
+  family?: string
+  size?: number
+  weight?: number | string
+  style?: 'normal' | 'italic' | 'oblique'
+  color?: string
+}
+
+export type ShapeShadowInput = {
+  color?: string
+  blur: number
+  offsetX?: number
+  offsetY?: number
+}
+
+export type ResolvedShapeShadow = {
+  color: string
+  blur: number
+  offsetX: number
+  offsetY: number
+}
+
+export type ShapeStyleInput = {
+  backgroundColor?: string
+  borderColor?: string
+  borderWidth?: number
+  shadow?: ShapeShadowInput
+}
+
+export type ResolvedShapeStyle = {
+  backgroundColor?: string
+  borderColor: string
+  borderWidth: number
+  shadow?: ResolvedShapeShadow
+}
+
 export type PreparedLayoutToken = {
   kind: 'word' | 'newline'
   text: string
@@ -101,6 +146,7 @@ export type CompiledShapeBands = {
 
 export type ShapeTextLayout = {
   font: string
+  textStyle?: ResolvedTextStyle
   lineHeight: number
   shape: ShapeInput
   compiledShape: CompiledShapeBands
@@ -118,17 +164,24 @@ export type CompileShapeForLayoutOptions = {
 
 export type LayoutTextInCompiledShapeOptions = {
   text: string
-  font: string
   compiledShape: CompiledShapeBands
   measurer: TextMeasurer
   align?: 'left' | 'center'
   baselineRatio?: number
   autoFill?: boolean
-}
+} & (
+  | {
+      font: string
+      textStyle?: TextStyleInput
+    }
+  | {
+      font?: string
+      textStyle: TextStyleInput
+    }
+)
 
 export type LayoutTextInShapeOptions = {
   text: string
-  font: string
   lineHeight: number
   shape: ShapeInput
   measurer: TextMeasurer
@@ -136,7 +189,16 @@ export type LayoutTextInShapeOptions = {
   minSlotWidth?: number
   baselineRatio?: number
   autoFill?: boolean
-}
+} & (
+  | {
+      font: string
+      textStyle?: TextStyleInput
+    }
+  | {
+      font?: string
+      textStyle: TextStyleInput
+    }
+)
 
 export type RenderLayoutToSvgOptions = {
   padding?: number
@@ -144,5 +206,6 @@ export type RenderLayoutToSvgOptions = {
   textFill?: string
   shapeStroke?: string
   shapeFill?: string
+  shapeStyle?: ShapeStyleInput
   showShape?: boolean
 }

From 095528a6691315f7108f0d200d5f92bbc923f74d Mon Sep 17 00:00:00 2001
From: tqdat410 <danhlagi01472@gmail.com>
Date: Wed, 1 Apr 2026 11:06:10 +0700
Subject: [PATCH 02/12] docs: document style and decoration API

Document textStyle and shapeStyle usage, architecture notes, and changelog updates for the new rendering options.

Co-authored-by: Codex <noreply@openai.com>
---
 README.md                    | 30 +++++++++++++++++++++++++-----
 docs/code-standards.md       |  2 ++
 docs/project-changelog.md    |  7 +++++++
 docs/project-overview-pdr.md |  6 ++++--
 docs/system-architecture.md  |  4 +++-
 5 files changed, 41 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index a20586f..ecfa224 100644
--- a/README.md
+++ b/README.md
@@ -31,7 +31,13 @@ const measurer = createCanvasTextMeasurer()
 
 const layout = layoutTextInShape({
   text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
-  font: '16px "Helvetica Neue", Arial, sans-serif',
+  textStyle: {
+    family: '"Helvetica Neue", Arial, sans-serif',
+    size: 16,
+    weight: 700,
+    style: 'italic',
+    color: '#111827',
+  },
   lineHeight: 22,
   shape: {
     kind: 'polygon',
@@ -47,9 +53,15 @@ const layout = layoutTextInShape({
 
 const svg = renderLayoutToSvg(layout, {
   background: '#fffdf7',
-  textFill: '#111827',
-  shapeStroke: '#d1d5db',
-  showShape: true,
+  shapeStyle: {
+    backgroundColor: '#dbeafe',
+    borderColor: '#94a3b8',
+    borderWidth: 2,
+    shadow: {
+      blur: 6,
+      offsetY: 6,
+    },
+  },
 })
 ```
 
@@ -58,7 +70,12 @@ const svg = renderLayoutToSvg(layout, {
 ```ts
 const layout = layoutTextInShape({
   text: 'ONE',
-  font: '16px Arial',
+  textStyle: {
+    family: 'Arial, sans-serif',
+    size: 16,
+    weight: 700,
+    color: '#0f172a',
+  },
   lineHeight: 20,
   autoFill: true,
   shape: {
@@ -77,6 +94,7 @@ const layout = layoutTextInShape({
 
 - `createCanvasTextMeasurer()`
 - `compileShapeForLayout()`
+- `normalizeTextStyleToFont()`
 - `prepareTextForLayout()`
 - `layoutNextLineFromPreparedText()`
 - `layoutNextLineFromRepeatedText()`
@@ -91,6 +109,8 @@ const layout = layoutTextInShape({
 - The project takes inspiration from `pretext` for the `prepare -> layout` split and streaming line iteration, but owns its geometry, slot policy, and public API.
 - `text-mask` shapes are raster-compiled into reusable line bands. This is the default path for browser fonts such as `Arial`, and it is designed so callers can precompile `0-9` and `:` for clock-like UIs.
 - `autoFill: true` repeats the source text until the available shape bands are full.
+- `textStyle` is the new data-driven API for size, weight, italic/oblique, family, and default text color. Legacy `font` string input still works.
+- `shapeStyle` lives in `renderLayoutToSvg()` because fill, border, and shadow do not affect line breaking or shape compilation.
 - For late-loading web fonts, compile after the font is ready if you want immediate cache reuse. The compiler skips cache writes until `document.fonts.check()` reports the font as ready.
 
 ## Local E2E
diff --git a/docs/code-standards.md b/docs/code-standards.md
index 10da2fc..904c658 100644
--- a/docs/code-standards.md
+++ b/docs/code-standards.md
@@ -14,6 +14,8 @@
 - V1 is browser-first
 - Advanced i18n fidelity can be added later without breaking the public shape-first API
 - Keep shape compilation separate from content flow so hot paths can reuse cached bands
+- Keep text formatting data-driven; do not pass framework components into the core API
+- Keep shape decoration renderer-only unless it changes geometry
 
 ## Testing Rules
 
diff --git a/docs/project-changelog.md b/docs/project-changelog.md
index d7a0af5..40cff79 100644
--- a/docs/project-changelog.md
+++ b/docs/project-changelog.md
@@ -14,3 +14,10 @@
 - Added compiler guards for invalid alpha thresholds and oversized raster requests
 - Added cache safety for late-loading fonts and frozen compiled shapes
 - Added Vitest coverage support and direct text-mask compiler tests
+
+## 2026-04-01
+
+- Added structured `textStyle` API for text size, family, weight, style, and default color
+- Added renderer-side `shapeStyle` API for shape fill, border, and shadow
+- Kept legacy `font`, `textFill`, `shapeFill`, and `shapeStroke` compatibility paths
+- Extended local demo and Playwright coverage for style and decoration controls
diff --git a/docs/project-overview-pdr.md b/docs/project-overview-pdr.md
index 9a10d4b..e5d0701 100644
--- a/docs/project-overview-pdr.md
+++ b/docs/project-overview-pdr.md
@@ -14,6 +14,8 @@ Web CSS can wrap text around floated shapes, but it does not provide a solid, po
 - Accept text-mask input from glyph text and font
 - Measure and stream paragraph lines through shape bands
 - Support repeat-fill mode for dense glyph fills
+- Support structured text formatting params for size, family, weight, style, and color
+- Support renderer-only shape decoration for fill, border, and shadow
 - Return deterministic line geometry
 - Render to SVG
 - Support Latin/Vietnamese first
@@ -28,9 +30,9 @@ Web CSS can wrap text around floated shapes, but it does not provide a solid, po
 
 ## Acceptance Criteria
 
-- A caller can pass text, font, line height, shape input, and measurer
+- A caller can pass text, text formatting, line height, shape input, and measurer
 - The library can compile reusable shape bands for polygon and text-mask shapes
 - The library can repeat source text until the target shape bands are full
 - The library returns line positions inside the target shape
-- The library renders those lines to SVG
+- The library renders those lines to SVG with optional shape decoration
 - Build and tests pass
diff --git a/docs/system-architecture.md b/docs/system-architecture.md
index 7eec384..a90202a 100644
--- a/docs/system-architecture.md
+++ b/docs/system-architecture.md
@@ -10,7 +10,7 @@
 
 ## Data Flow
 
-1. Normalize and prepare text
+1. Normalize text formatting into a canonical font string
 2. Compile the input shape into reusable line bands
 3. Compute allowed intervals for each band
 4. Pick the widest interval
@@ -21,6 +21,8 @@
 ## Boundary Decisions
 
 - Text measurement stays replaceable through `TextMeasurer`
+- Layout-affecting text style stays in the layout API
 - Shape compilation stays separate from content flow so glyph shapes can be cached
 - Geometry stays shape-specific, not DOM-specific
+- Renderer-only decoration stays out of compile/layout caching
 - Renderer consumes compiled layout output only

From 9be89c6a2540df9adca0b04ce21774a62aaa6676 Mon Sep 17 00:00:00 2001
From: tqdat410 <danhlagi01472@gmail.com>
Date: Wed, 1 Apr 2026 11:29:29 +0700
Subject: [PATCH 03/12] fix(demo): preserve editable autofill text state

Keep glyph autofill text editable across rerenders and scenario switches, and add Playwright coverage for the demo state regressions.

Co-authored-by: Codex <noreply@openai.com>
---
 e2e/fixtures/index.html            |  2 +-
 e2e/fixtures/shape-text-e2e-app.js | 18 ++++++++-
 e2e/shape-text-local-e2e.spec.ts   | 62 ++++++++++++++++++++++++++++++
 3 files changed, 79 insertions(+), 3 deletions(-)

diff --git a/e2e/fixtures/index.html b/e2e/fixtures/index.html
index a5de73d..fe10740 100644
--- a/e2e/fixtures/index.html
+++ b/e2e/fixtures/index.html
@@ -220,7 +220,7 @@ <h1>shape-text demo</h1>
             <button data-scenario="rectangle-wide">Rectangle Wide</button>
             <button data-scenario="rectangle-narrow">Rectangle Narrow</button>
           </div>
-          <p>Use the shape buttons to compare flow behavior. The glyph scenario uses a real text mask and repeats ONE until the shape is full.</p>
+          <p>Use the shape buttons to compare flow behavior. The glyph scenario uses a real text mask and repeats whatever text is currently in the editor until the shape is full.</p>
         </div>
       </section>
       <div class="panel-grid">
diff --git a/e2e/fixtures/shape-text-e2e-app.js b/e2e/fixtures/shape-text-e2e-app.js
index 70b346b..c649833 100644
--- a/e2e/fixtures/shape-text-e2e-app.js
+++ b/e2e/fixtures/shape-text-e2e-app.js
@@ -119,6 +119,7 @@ const state = {
   shapeBorderColor: '#94a3b8',
   shapeShadow: true,
 }
+let hasUserEditedText = false
 
 function getTextStyle() {
   return {
@@ -146,11 +147,19 @@ function getShapeStyle() {
   }
 }
 
-function renderScenario(name) {
+function resolveScenarioText(name) {
   const scenario = scenarios[name]
   if (!scenario) throw new Error(`Unknown scenario: ${name}`)
 
-  state.text = scenario.text ?? state.text
+  if (!hasUserEditedText && scenario.text !== undefined) {
+    state.text = scenario.text
+  }
+
+  return scenario
+}
+
+function renderScenario(name) {
+  const scenario = resolveScenarioText(name)
 
   const layout = layoutTextInShape({
     text: state.text,
@@ -276,6 +285,11 @@ renderButton.addEventListener('click', () => {
   renderScenario(state.scenario || 'digit-two-wide')
 })
 
+textInput.addEventListener('input', () => {
+  state.text = textInput.value
+  hasUserEditedText = true
+})
+
 lineHeightInput.addEventListener('input', () => {
   lineHeightValue.textContent = lineHeightInput.value
 })
diff --git a/e2e/shape-text-local-e2e.spec.ts b/e2e/shape-text-local-e2e.spec.ts
index d82443b..bff3a6f 100644
--- a/e2e/shape-text-local-e2e.spec.ts
+++ b/e2e/shape-text-local-e2e.spec.ts
@@ -128,6 +128,68 @@ test('applies text and shape style controls to the rendered SVG', async ({ page
   expect(state.svg).toContain('shape-text-shape-shadow')
 })
 
+test('preserves edited glyph autofill text without forcing uppercase', async ({ page }) => {
+  await page.goto('/')
+
+  await page.locator('#text-input').fill('one')
+  await page.locator('#render-button').click()
+
+  const state = await getState(page)
+
+  await expect(page.locator('#text-input')).toHaveValue('one')
+  expect(state.text).toBe('one')
+  expect(state.layout.lines[0]?.text).toContain('one')
+  expect(state.layout.lines[0]?.text).not.toContain('ONE')
+  expect(state.svg).toContain('>one<')
+})
+
+test('keeps edited text when switching away from and back to the glyph scenario', async ({
+  page,
+}) => {
+  await page.goto('/')
+
+  await page.locator('#text-input').fill('one')
+  await page.locator('#render-button').click()
+  await page.evaluate(() => window.shapeTextTestApi.renderScenario('rectangle-wide'))
+  await page.evaluate(() => window.shapeTextTestApi.renderScenario('glyph-two-repeat'))
+
+  const state = await getState(page)
+
+  await expect(page.locator('#text-input')).toHaveValue('one')
+  expect(state.scenario).toBe('glyph-two-repeat')
+  expect(state.text).toBe('one')
+  expect(state.layout.lines[0]?.text).toContain('one')
+  expect(state.layout.lines[0]?.text).not.toContain('ONE')
+})
+
+test('keeps unsaved textarea edits when switching scenarios', async ({ page }) => {
+  await page.goto('/')
+
+  await page.locator('#text-input').fill('draft')
+  await page.evaluate(() => window.shapeTextTestApi.renderScenario('rectangle-wide'))
+
+  const state = await getState(page)
+
+  await expect(page.locator('#text-input')).toHaveValue('draft')
+  expect(state.scenario).toBe('rectangle-wide')
+  expect(state.text).toBe('draft')
+  expect(state.layout.lines[0]?.text).toContain('draft')
+})
+
+test('keeps scenario defaults when rerender changes only style controls', async ({ page }) => {
+  await page.goto('/')
+
+  await setRangeValue(page, '#text-size-input', '24')
+  await page.locator('#render-button').click()
+  await page.evaluate(() => window.shapeTextTestApi.renderScenario('rectangle-wide'))
+
+  const state = await getState(page)
+
+  expect(state.scenario).toBe('rectangle-wide')
+  expect(state.text).toContain('Shape text lets a paragraph travel inside a silhouette')
+  expect(state.layout.lines[0]?.text).toContain('Shape text')
+})
+
 test('reflows into more lines in the narrow rectangle scenario', async ({ page }) => {
   await page.goto('/')
 

From 12616b3a66dcf667f56b56f79857ebb77d6d2746 Mon Sep 17 00:00:00 2001
From: tqdat410 <danhlagi01472@gmail.com>
Date: Wed, 1 Apr 2026 12:57:10 +0700
Subject: [PATCH 04/12] feat(layout): add max-fill stream strategy

Co-authored-by: Codex <noreply@openai.com>
---
 e2e/fixtures/index.html                       |  10 +-
 e2e/fixtures/shape-text-e2e-app.js            |  26 +++-
 e2e/shape-text-local-e2e.spec.ts              |  46 ++++++
 src/index.ts                                  |   2 +
 src/layout/layout-dense-fill-pass.ts          | 106 +++++++++++++
 src/layout/layout-text-in-compiled-shape.ts   |  81 +---------
 src/layout/layout-text-in-shape.test.ts       | 144 ++++++++++++++++++
 src/layout/layout-text-in-shape.ts            |  18 ++-
 src/layout/resolve-flow-layout.ts             | 122 +++++++++++++++
 src/layout/resolve-max-fill-layout.ts         |  68 +++++++++
 src/render/render-layout-to-svg.test.ts       |  76 +++++++++
 src/render/render-layout-to-svg.ts            |   2 +-
 ...yout-next-line-from-dense-repeated-text.ts |  85 +++++++++++
 src/text/prepare-dense-repeat-fill-pattern.ts |  21 +++
 .../prepare-stream-repeat-fill-pattern.ts     |  25 +++
 src/types.ts                                  |  11 ++
 16 files changed, 766 insertions(+), 77 deletions(-)
 create mode 100644 src/layout/layout-dense-fill-pass.ts
 create mode 100644 src/layout/resolve-flow-layout.ts
 create mode 100644 src/layout/resolve-max-fill-layout.ts
 create mode 100644 src/text/layout-next-line-from-dense-repeated-text.ts
 create mode 100644 src/text/prepare-dense-repeat-fill-pattern.ts
 create mode 100644 src/text/prepare-stream-repeat-fill-pattern.ts

diff --git a/e2e/fixtures/index.html b/e2e/fixtures/index.html
index fe10740..7a2457a 100644
--- a/e2e/fixtures/index.html
+++ b/e2e/fixtures/index.html
@@ -179,6 +179,14 @@ <h1>shape-text demo</h1>
               Text color
               <input id="text-color-input" type="color" value="#111827" />
             </label>
+            <label>
+              Fill mode
+              <select id="auto-fill-mode-select">
+                <option value="words" selected>Word repeat</option>
+                <option value="dense">Dense repeat</option>
+                <option value="max">Max fill</option>
+              </select>
+            </label>
             <label>
               Shape fill
               <input id="shape-fill-input" type="color" value="#dbeafe" />
@@ -220,7 +228,7 @@ <h1>shape-text demo</h1>
             <button data-scenario="rectangle-wide">Rectangle Wide</button>
             <button data-scenario="rectangle-narrow">Rectangle Narrow</button>
           </div>
-          <p>Use the shape buttons to compare flow behavior. The glyph scenario uses a real text mask and repeats whatever text is currently in the editor until the shape is full.</p>
+          <p>Use the shape buttons to compare flow behavior. The glyph scenario uses a real text mask and can repeat by words, dense grapheme flow, or max fill with extra slot coverage while still keeping spaces in the text stream.</p>
         </div>
       </section>
       <div class="panel-grid">
diff --git a/e2e/fixtures/shape-text-e2e-app.js b/e2e/fixtures/shape-text-e2e-app.js
index c649833..4473dac 100644
--- a/e2e/fixtures/shape-text-e2e-app.js
+++ b/e2e/fixtures/shape-text-e2e-app.js
@@ -15,6 +15,7 @@ const textSizeValue = document.querySelector('#text-size-value')
 const textWeightSelect = document.querySelector('#text-weight-select')
 const textItalicInput = document.querySelector('#text-italic-input')
 const textColorInput = document.querySelector('#text-color-input')
+const autoFillModeSelect = document.querySelector('#auto-fill-mode-select')
 const shapeFillInput = document.querySelector('#shape-fill-input')
 const shapeBorderWidthInput = document.querySelector('#shape-border-width-input')
 const shapeBorderWidthValue = document.querySelector('#shape-border-width-value')
@@ -113,6 +114,8 @@ const state = {
   textWeight: 700,
   textItalic: false,
   textColor: '#111827',
+  autoFillMode: 'words',
+  fillStrategy: 'flow',
   showShape: true,
   shapeFill: '#dbeafe',
   shapeBorderWidth: 2,
@@ -121,6 +124,21 @@ const state = {
 }
 let hasUserEditedText = false
 
+function getFillSelectValue() {
+  return state.fillStrategy === 'max' ? 'max' : state.autoFillMode
+}
+
+function applyFillSelection(value) {
+  if (value === 'max') {
+    state.autoFillMode = 'stream'
+    state.fillStrategy = 'max'
+    return
+  }
+
+  state.autoFillMode = value
+  state.fillStrategy = 'flow'
+}
+
 function getTextStyle() {
   return {
     family: '"Helvetica Neue", Arial, sans-serif',
@@ -167,8 +185,10 @@ function renderScenario(name) {
     lineHeight: state.lineHeight,
     shape: scenario.shape,
     measurer,
-    minSlotWidth: 24,
+    minSlotWidth: state.fillStrategy === 'max' ? 8 : 24,
     autoFill: scenario.autoFill,
+    autoFillMode: state.autoFillMode,
+    fillStrategy: state.fillStrategy,
   })
 
   const svg = renderLayoutToSvg(layout, {
@@ -188,6 +208,8 @@ function renderScenario(name) {
       scenario: name,
       shapeKind: scenario.shape.kind,
       autoFill: Boolean(scenario.autoFill),
+      autoFillMode: layout.autoFillMode,
+      fillStrategy: layout.fillStrategy,
       lineHeight: state.lineHeight,
       textStyle: getTextStyle(),
       shapeStyle: getShapeStyle(),
@@ -259,6 +281,7 @@ function syncControls() {
   textWeightSelect.value = String(state.textWeight)
   textItalicInput.checked = state.textItalic
   textColorInput.value = state.textColor
+  autoFillModeSelect.value = getFillSelectValue()
   showShapeInput.checked = state.showShape
   shapeFillInput.value = state.shapeFill
   shapeBorderWidthInput.value = String(state.shapeBorderWidth)
@@ -274,6 +297,7 @@ renderButton.addEventListener('click', () => {
   state.textWeight = Number(textWeightSelect.value)
   state.textItalic = textItalicInput.checked
   state.textColor = textColorInput.value
+  applyFillSelection(autoFillModeSelect.value)
   state.showShape = showShapeInput.checked
   state.shapeFill = shapeFillInput.value
   state.shapeBorderWidth = Number(shapeBorderWidthInput.value)
diff --git a/e2e/shape-text-local-e2e.spec.ts b/e2e/shape-text-local-e2e.spec.ts
index bff3a6f..38747a4 100644
--- a/e2e/shape-text-local-e2e.spec.ts
+++ b/e2e/shape-text-local-e2e.spec.ts
@@ -15,12 +15,16 @@ declare global {
         scenario: string
         layout: {
           autoFill: boolean
+          autoFillMode: 'words' | 'dense' | 'stream'
+          fillStrategy: 'flow' | 'max'
           exhausted: boolean
           lines: Array<{
             text: string
             x: number
+            top: number
             width: number
             slot: { left: number; right: number }
+            fillPass?: 1 | 2
           }>
         }
         text: string
@@ -28,6 +32,8 @@ declare global {
         textWeight: number
         textItalic: boolean
         textColor: string
+        autoFillMode: 'words' | 'dense' | 'stream'
+        fillStrategy: 'flow' | 'max'
         showShape: boolean
         shapeFill: string
         shapeBorderWidth: number
@@ -69,6 +75,8 @@ test('renders the glyph text-mask fixture into SVG', async ({ page }) => {
   expect(state.text).toBe('ONE')
   expect(state.layout.lines.length).toBeGreaterThan(4)
   expect(state.layout.autoFill).toBe(true)
+  expect(state.layout.autoFillMode).toBe('words')
+  expect(state.layout.fillStrategy).toBe('flow')
   expect(state.layout.exhausted).toBe(false)
   expect(state.layout.lines[0]?.text).toContain('ONE')
   expect(state.textSize).toBe(18)
@@ -128,6 +136,44 @@ test('applies text and shape style controls to the rendered SVG', async ({ page
   expect(state.svg).toContain('shape-text-shape-shadow')
 })
 
+test('packs glyph autofill more tightly in dense mode', async ({ page }) => {
+  await page.goto('/')
+
+  const wordsState = await getState(page)
+
+  await page.locator('#auto-fill-mode-select').selectOption('dense')
+  await page.locator('#render-button').click()
+
+  const denseState = await getState(page)
+
+  expect(wordsState.layout.autoFillMode).toBe('words')
+  expect(denseState.layout.autoFillMode).toBe('dense')
+  expect(denseState.autoFillMode).toBe('dense')
+  expect(denseState.layout.lines[0]?.text).not.toContain(' ')
+  expect(denseState.layout.lines[0]?.width).toBeGreaterThan(wordsState.layout.lines[0]?.width ?? 0)
+})
+
+test('keeps spaces and fills multiple slots in max mode without mini-font fallback', async ({ page }) => {
+  await page.goto('/')
+
+  await page.locator('#text-input').fill('ONE ONE')
+  await page.locator('#auto-fill-mode-select').selectOption('dense')
+  await page.locator('#render-button').click()
+  const denseState = await getState(page)
+
+  await page.locator('#auto-fill-mode-select').selectOption('max')
+  await page.locator('#render-button').click()
+  const maxState = await getState(page)
+
+  expect(maxState.fillStrategy).toBe('max')
+  expect(maxState.layout.fillStrategy).toBe('max')
+  expect(maxState.layout.autoFillMode).toBe('stream')
+  expect(maxState.layout.lines.some(line => line.text.includes(' '))).toBe(true)
+  expect(maxState.layout.lines.some((line, index, lines) => lines.some(other => other !== line && other.top === line.top))).toBe(true)
+  expect(maxState.layout.lines.length).toBeGreaterThanOrEqual(denseState.layout.lines.length)
+  expect(maxState.svg).not.toMatch(/font:[^"]*12\./)
+})
+
 test('preserves edited glyph autofill text without forcing uppercase', async ({ page }) => {
   await page.goto('/')
 
diff --git a/src/index.ts b/src/index.ts
index d467df8..ed87596 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,7 +1,9 @@
 export type {
+  AutoFillMode,
   CompiledShapeBand,
   CompiledShapeBands,
   CompileShapeForLayoutOptions,
+  FillStrategy,
   Interval,
   LayoutCursor,
   LayoutLineRange,
diff --git a/src/layout/layout-dense-fill-pass.ts b/src/layout/layout-dense-fill-pass.ts
new file mode 100644
index 0000000..94eab90
--- /dev/null
+++ b/src/layout/layout-dense-fill-pass.ts
@@ -0,0 +1,106 @@
+import type { CompiledShapeBands, Interval, PreparedLayoutToken, ShapeTextLine } from '../types.js'
+import { layoutNextLineFromDenseRepeatedText } from '../text/layout-next-line-from-dense-repeated-text.js'
+
+export type DenseFillOccupiedRect = {
+  left: number
+  right: number
+  top: number
+  bottom: number
+}
+
+type LayoutDenseFillPassOptions = {
+  compiledShape: CompiledShapeBands
+  densePattern: PreparedLayoutToken
+  startOffset: number
+  align: 'left' | 'center'
+  baselineRatio: number
+  allSlots: boolean
+  font?: string
+  fillPass?: 1 | 2
+}
+
+function pickWidestInterval(intervals: Interval[]): Interval {
+  let best = intervals[0]!
+
+  for (let index = 1; index < intervals.length; index++) {
+    const candidate = intervals[index]!
+    if (candidate.right - candidate.left > best.right - best.left) {
+      best = candidate
+    }
+  }
+
+  return best
+}
+
+function getOrderedSlots(intervals: Interval[], allSlots: boolean): Interval[] {
+  if (intervals.length === 0) {
+    return []
+  }
+
+  if (!allSlots) {
+    return [pickWidestInterval(intervals)]
+  }
+
+  return [...intervals].sort((left, right) => left.left - right.left)
+}
+
+export function layoutDenseFillPass(options: LayoutDenseFillPassOptions): {
+  lines: ShapeTextLine[]
+  endOffset: number
+  occupiedRects: DenseFillOccupiedRect[]
+} {
+  const lines: ShapeTextLine[] = []
+  const occupiedRects: DenseFillOccupiedRect[] = []
+  let offset = options.startOffset
+
+  for (let bandIndex = 0; bandIndex < options.compiledShape.bands.length; bandIndex++) {
+    const band = options.compiledShape.bands[bandIndex]!
+    const slots = getOrderedSlots(band.intervals, options.allSlots)
+
+    for (let slotIndex = 0; slotIndex < slots.length; slotIndex++) {
+      const slot = slots[slotIndex]!
+      const line = layoutNextLineFromDenseRepeatedText(
+        options.densePattern,
+        offset,
+        slot.right - slot.left,
+      )
+
+      if (line === null) {
+        continue
+      }
+
+      const x =
+        options.align === 'center'
+          ? slot.left + Math.max(0, (slot.right - slot.left - line.width) / 2)
+          : slot.left
+      const occupiedRight = Math.min(slot.right, x + Math.max(0, line.width))
+
+      lines.push({
+        ...line,
+        x,
+        top: band.top,
+        baseline: band.top + options.compiledShape.bandHeight * options.baselineRatio,
+        slot,
+        font: options.font,
+        fillPass: options.fillPass,
+      })
+
+      if (occupiedRight > x) {
+        occupiedRects.push({
+          left: x,
+          right: occupiedRight,
+          top: band.top,
+          bottom: band.bottom,
+        })
+      }
+
+      offset = line.end.tokenIndex
+    }
+  }
+
+  return {
+    lines,
+    endOffset: offset,
+    occupiedRects,
+  }
+}
diff --git a/src/layout/layout-text-in-compiled-shape.ts b/src/layout/layout-text-in-compiled-shape.ts
index 9003368..20ac17f 100644
--- a/src/layout/layout-text-in-compiled-shape.ts
+++ b/src/layout/layout-text-in-compiled-shape.ts
@@ -1,82 +1,17 @@
-import type {
-  Interval,
-  LayoutCursor,
-  LayoutTextInCompiledShapeOptions,
-  ShapeTextLayout,
-  ShapeTextLine,
-} from '../types.js'
-import { layoutNextLineFromPreparedText } from '../text/layout-next-line-from-prepared-text.js'
-import { layoutNextLineFromRepeatedText } from '../text/layout-next-line-from-repeated-text.js'
-import { resolveLayoutTextStyle } from '../text/normalize-text-style-to-font.js'
-import { prepareTextForLayout } from '../text/prepare-text-for-layout.js'
-
-function pickWidestInterval(intervals: Interval[]): Interval {
-  let best = intervals[0]!
-
-  for (let index = 1; index < intervals.length; index++) {
-    const candidate = intervals[index]!
-    if (candidate.right - candidate.left > best.right - best.left) {
-      best = candidate
-    }
-  }
-
-  return best
-}
+import type { AutoFillMode, FillStrategy, LayoutTextInCompiledShapeOptions, ShapeTextLayout } from '../types.js'
+import { resolveFlowLayout } from './resolve-flow-layout.js'
+import { resolveMaxFillLayout } from './resolve-max-fill-layout.js'
 
 export function layoutTextInCompiledShape(
   options: LayoutTextInCompiledShapeOptions,
 ): ShapeTextLayout {
-  const resolvedTextStyle = resolveLayoutTextStyle({
-    font: options.font,
-    textStyle: options.textStyle,
-  })
-  const prepared = prepareTextForLayout(options.text, resolvedTextStyle.font, options.measurer)
   const autoFill = options.autoFill ?? false
-  const align = options.align ?? 'left'
-  const baselineRatio = options.baselineRatio ?? 0.8
-  const lines: ShapeTextLine[] = []
-  let cursor: LayoutCursor = { tokenIndex: 0, graphemeIndex: 0 }
-
-  for (let index = 0; index < options.compiledShape.bands.length; index++) {
-    const band = options.compiledShape.bands[index]!
-    if (band.intervals.length === 0) {
-      continue
-    }
+  const autoFillMode: AutoFillMode = autoFill ? (options.autoFillMode ?? 'words') : 'words'
+  const fillStrategy: FillStrategy = autoFill ? (options.fillStrategy ?? 'flow') : 'flow'
 
-    const slot = pickWidestInterval(band.intervals)
-    const line = autoFill
-      ? layoutNextLineFromRepeatedText(prepared, cursor, slot.right - slot.left)
-      : layoutNextLineFromPreparedText(prepared, cursor, slot.right - slot.left)
-
-    if (line === null) {
-      break
-    }
-
-    const x =
-      align === 'center'
-        ? slot.left + Math.max(0, (slot.right - slot.left - line.width) / 2)
-        : slot.left
-
-    lines.push({
-      ...line,
-      x,
-      top: band.top,
-      baseline: band.top + options.compiledShape.bandHeight * baselineRatio,
-      slot,
-    })
-
-    cursor = line.end
+  if (fillStrategy === 'max') {
+    return resolveMaxFillLayout(options)
   }
 
-  return {
-    font: resolvedTextStyle.font,
-    textStyle: resolvedTextStyle,
-    lineHeight: options.compiledShape.bandHeight,
-    shape: options.compiledShape.source,
-    compiledShape: options.compiledShape,
-    bounds: options.compiledShape.bounds,
-    lines,
-    exhausted: autoFill ? prepared.tokens.length === 0 : cursor.tokenIndex >= prepared.tokens.length,
-    autoFill,
-  }
+  return resolveFlowLayout(options, autoFillMode)
 }
diff --git a/src/layout/layout-text-in-shape.test.ts b/src/layout/layout-text-in-shape.test.ts
index f5a6797..b0cb0a0 100644
--- a/src/layout/layout-text-in-shape.test.ts
+++ b/src/layout/layout-text-in-shape.test.ts
@@ -101,9 +101,153 @@ describe('layoutTextInShape', () => {
 
     expect(layout.lines.map(line => line.text)).toEqual(['ONE ONE', 'ONE ONE', 'ONE ONE'])
     expect(layout.autoFill).toBe(true)
+    expect(layout.autoFillMode).toBe('words')
     expect(layout.exhausted).toBe(false)
   })
 
+  it('supports dense auto-fill by ignoring spaces and word boundaries', () => {
+    const layout = layoutTextInShape({
+      text: 'ONE',
+      font: '16px Test Sans',
+      lineHeight: 20,
+      autoFill: true,
+      autoFillMode: 'dense',
+      shape: {
+        kind: 'polygon',
+        points: [
+          { x: 0, y: 0 },
+          { x: 100, y: 0 },
+          { x: 100, y: 60 },
+          { x: 0, y: 60 },
+        ],
+      },
+      measurer: createFixedWidthTextMeasurer(),
+    })
+
+    expect(layout.autoFillMode).toBe('dense')
+    expect(layout.lines[0]?.text).toBe('ONEONEONEO')
+    expect(layout.lines[0]?.width).toBe(100)
+    expect(layout.lines[0]?.text).not.toContain(' ')
+  })
+
+  it('supports max fill by sweeping every slot in a band', () => {
+    const layout = layoutTextInCompiledShape({
+      text: 'A B',
+      font: '16px Test Sans',
+      autoFill: true,
+      fillStrategy: 'max',
+      compiledShape: {
+        kind: 'polygon',
+        source: {
+          kind: 'polygon',
+          points: [
+            { x: 0, y: 0 },
+            { x: 100, y: 0 },
+            { x: 100, y: 8 },
+            { x: 0, y: 8 },
+          ],
+        },
+        bounds: { left: 0, top: 0, right: 100, bottom: 8 },
+        bandHeight: 8,
+        minSlotWidth: 1,
+        bands: [
+          {
+            top: 0,
+            bottom: 8,
+            intervals: [
+              { left: 0, right: 30 },
+              { left: 70, right: 100 },
+            ],
+          },
+        ],
+        debugView: {
+          kind: 'polygon',
+          points: [
+            { x: 0, y: 0 },
+            { x: 100, y: 0 },
+            { x: 100, y: 8 },
+            { x: 0, y: 8 },
+          ],
+        },
+      },
+      measurer: createFixedWidthTextMeasurer(),
+    })
+
+    expect(layout.fillStrategy).toBe('max')
+    expect(layout.autoFillMode).toBe('stream')
+    expect(layout.lines.map(line => [line.text, line.x, line.fillPass])).toEqual([
+      ['A B', 0, 1],
+      ['A B', 70, 1],
+    ])
+  })
+
+  it('strips whitespace and continues dense fill across line boundaries', () => {
+    const layout = layoutTextInShape({
+      text: 'A B',
+      font: '16px Test Sans',
+      lineHeight: 20,
+      autoFill: true,
+      autoFillMode: 'dense',
+      shape: {
+        kind: 'polygon',
+        points: [
+          { x: 0, y: 0 },
+          { x: 50, y: 0 },
+          { x: 50, y: 40 },
+          { x: 0, y: 40 },
+        ],
+      },
+      measurer: createFixedWidthTextMeasurer(),
+    })
+
+    expect(layout.lines.map(line => line.text)).toEqual(['ABABA', 'BABAB'])
+  })
+
+  it('rejects dense auto-fill when the source becomes whitespace-only', () => {
+    expect(() =>
+      layoutTextInShape({
+        text: ' \n\t ',
+        font: '16px Test Sans',
+        lineHeight: 20,
+        autoFill: true,
+        autoFillMode: 'dense',
+        shape: {
+          kind: 'polygon',
+          points: [
+            { x: 0, y: 0 },
+            { x: 100, y: 0 },
+            { x: 100, y: 60 },
+            { x: 0, y: 60 },
+          ],
+        },
+        measurer: createFixedWidthTextMeasurer(),
+      }),
+    ).toThrow('dense autoFill requires at least one non-whitespace grapheme')
+  })
+
+  it('keeps empty word auto-fill exhausted state unchanged', () => {
+    const layout = layoutTextInShape({
+      text: '',
+      font: '16px Test Sans',
+      lineHeight: 20,
+      autoFill: true,
+      shape: {
+        kind: 'polygon',
+        points: [
+          { x: 0, y: 0 },
+          { x: 100, y: 0 },
+          { x: 100, y: 60 },
+          { x: 0, y: 60 },
+        ],
+      },
+      measurer: createFixedWidthTextMeasurer(),
+    })
+
+    expect(layout.lines).toHaveLength(0)
+    expect(layout.exhausted).toBe(true)
+    expect(layout.autoFillMode).toBe('words')
+  })
+
   it('normalizes textStyle into the resolved layout font and color', () => {
     const layout = layoutTextInShape({
       text: 'xin chao',
diff --git a/src/layout/layout-text-in-shape.ts b/src/layout/layout-text-in-shape.ts
index 529204f..3007f89 100644
--- a/src/layout/layout-text-in-shape.ts
+++ b/src/layout/layout-text-in-shape.ts
@@ -2,11 +2,23 @@ import type { LayoutTextInShapeOptions, ShapeTextLayout } from '../types.js'
 import { compileShapeForLayout } from '../shape/compile-shape-for-layout.js'
 import { layoutTextInCompiledShape } from './layout-text-in-compiled-shape.js'
 
+function resolveCompileMinSlotWidth(options: LayoutTextInShapeOptions): number | undefined {
+  if (options.fillStrategy !== 'max' || options.autoFill !== true) {
+    return options.minSlotWidth
+  }
+
+  if (options.minSlotWidth !== undefined) {
+    return options.minSlotWidth
+  }
+
+  return Math.max(6, Math.round(options.lineHeight * 0.45))
+}
+
 export function layoutTextInShape(options: LayoutTextInShapeOptions): ShapeTextLayout {
   const compiledShape = compileShapeForLayout({
     shape: options.shape,
     lineHeight: options.lineHeight,
-    minSlotWidth: options.minSlotWidth,
+    minSlotWidth: resolveCompileMinSlotWidth(options),
   })
 
   if (options.textStyle !== undefined) {
@@ -19,6 +31,8 @@ export function layoutTextInShape(options: LayoutTextInShapeOptions): ShapeTextL
       align: options.align,
       baselineRatio: options.baselineRatio,
       autoFill: options.autoFill,
+      autoFillMode: options.autoFillMode,
+      fillStrategy: options.fillStrategy,
     })
   }
 
@@ -30,5 +44,7 @@ export function layoutTextInShape(options: LayoutTextInShapeOptions): ShapeTextL
     align: options.align,
     baselineRatio: options.baselineRatio,
     autoFill: options.autoFill,
+    autoFillMode: options.autoFillMode,
+    fillStrategy: options.fillStrategy,
   })
 }
diff --git a/src/layout/resolve-flow-layout.ts b/src/layout/resolve-flow-layout.ts
new file mode 100644
index 0000000..5438d6c
--- /dev/null
+++ b/src/layout/resolve-flow-layout.ts
@@ -0,0 +1,122 @@
+import type {
+  AutoFillMode,
+  Interval,
+  LayoutCursor,
+  LayoutTextInCompiledShapeOptions,
+  ShapeTextLayout,
+  ShapeTextLine,
+} from '../types.js'
+import { layoutNextLineFromPreparedText } from '../text/layout-next-line-from-prepared-text.js'
+import { layoutNextLineFromRepeatedText } from '../text/layout-next-line-from-repeated-text.js'
+import { resolveLayoutTextStyle } from '../text/normalize-text-style-to-font.js'
+import { prepareDenseRepeatFillPattern } from '../text/prepare-dense-repeat-fill-pattern.js'
+import { prepareTextForLayout } from '../text/prepare-text-for-layout.js'
+import { layoutDenseFillPass } from './layout-dense-fill-pass.js'
+
+function pickWidestInterval(intervals: Interval[]): Interval {
+  let best = intervals[0]!
+
+  for (let index = 1; index < intervals.length; index++) {
+    const candidate = intervals[index]!
+    if (candidate.right - candidate.left > best.right - best.left) {
+      best = candidate
+    }
+  }
+
+  return best
+}
+
+export function resolveFlowLayout(
+  options: LayoutTextInCompiledShapeOptions,
+  autoFillMode: AutoFillMode,
+): ShapeTextLayout {
+  const resolvedTextStyle = resolveLayoutTextStyle({
+    font: options.font,
+    textStyle: options.textStyle,
+  })
+  const align = options.align ?? 'left'
+  const baselineRatio = options.baselineRatio ?? 0.8
+  const autoFill = options.autoFill ?? false
+  const prepared =
+    autoFillMode === 'dense'
+      ? undefined
+      : prepareTextForLayout(options.text, resolvedTextStyle.font, options.measurer)
+  const densePattern =
+    autoFillMode === 'dense'
+      ? prepareDenseRepeatFillPattern(options.text, resolvedTextStyle.font, options.measurer)
+      : undefined
+  const lines: ShapeTextLine[] = []
+  let cursor: LayoutCursor = { tokenIndex: 0, graphemeIndex: 0 }
+
+  for (let index = 0; index < options.compiledShape.bands.length; index++) {
+    const band = options.compiledShape.bands[index]!
+    if (band.intervals.length === 0) {
+      continue
+    }
+
+    const slot = pickWidestInterval(band.intervals)
+    if (autoFill && autoFillMode === 'dense') {
+      const denseLine =
+        layoutDenseFillPass({
+          compiledShape: {
+            ...options.compiledShape,
+            bands: [{ ...band, intervals: [slot] }],
+          },
+          densePattern: densePattern!,
+          startOffset: cursor.tokenIndex,
+          align,
+          baselineRatio,
+          allSlots: false,
+        }).lines[0] ?? null
+
+      if (denseLine === null) {
+        break
+      }
+
+      lines.push(denseLine)
+      cursor = denseLine.end
+      continue
+    }
+
+    const line = autoFill
+      ? layoutNextLineFromRepeatedText(prepared!, cursor, slot.right - slot.left)
+      : layoutNextLineFromPreparedText(prepared!, cursor, slot.right - slot.left)
+
+    if (line === null) {
+      break
+    }
+
+    const x =
+      align === 'center'
+        ? slot.left + Math.max(0, (slot.right - slot.left - line.width) / 2)
+        : slot.left
+
+    lines.push({
+      ...line,
+      x,
+      top: band.top,
+      baseline: band.top + options.compiledShape.bandHeight * baselineRatio,
+      slot,
+    })
+
+    cursor = line.end
+  }
+
+  return {
+    font: resolvedTextStyle.font,
+    textStyle: resolvedTextStyle,
+    lineHeight: options.compiledShape.bandHeight,
+    shape: options.compiledShape.source,
+    compiledShape: options.compiledShape,
+    bounds: options.compiledShape.bounds,
+    lines,
+    exhausted: autoFill
+      ? autoFillMode === 'dense'
+        ? false
+        : prepared!.tokens.length === 0
+      : cursor.tokenIndex >= prepared!.tokens.length,
+    autoFill,
+    autoFillMode,
+    fillStrategy: 'flow',
+  }
+}
diff --git a/src/layout/resolve-max-fill-layout.ts b/src/layout/resolve-max-fill-layout.ts
new file mode 100644
index 0000000..fa108b8
--- /dev/null
+++ b/src/layout/resolve-max-fill-layout.ts
@@ -0,0 +1,68 @@
+import type { LayoutTextInCompiledShapeOptions, ShapeTextLayout } from '../types.js'
+import { compileShapeForLayout } from '../shape/compile-shape-for-layout.js'
+import { resolveLayoutTextStyle } from '../text/normalize-text-style-to-font.js'
+import { prepareStreamRepeatFillPattern } from '../text/prepare-stream-repeat-fill-pattern.js'
+import { layoutDenseFillPass } from './layout-dense-fill-pass.js'
+
+const MAX_FILL_BASE_MIN_SLOT_WIDTH_FACTOR = 0.45
+const MIN_MAX_FILL_SLOT_WIDTH = 6
+
+function resolveMaxFillMinSlotWidth(lineHeight: number, factor: number): number {
+  return Math.max(MIN_MAX_FILL_SLOT_WIDTH, Math.round(lineHeight * factor))
+}
+
+function ensureMaxFillCompiledShape(options: LayoutTextInCompiledShapeOptions) {
+  const recommendedMinSlotWidth = resolveMaxFillMinSlotWidth(
+    options.compiledShape.bandHeight,
+    MAX_FILL_BASE_MIN_SLOT_WIDTH_FACTOR,
+  )
+  if (options.compiledShape.minSlotWidth <= recommendedMinSlotWidth) {
+    return options.compiledShape
+  }
+
+  return compileShapeForLayout({
+    shape: options.compiledShape.source,
+    lineHeight: options.compiledShape.bandHeight,
+    minSlotWidth: recommendedMinSlotWidth,
+  })
+}
+
+export function resolveMaxFillLayout(
+  options: LayoutTextInCompiledShapeOptions,
+): ShapeTextLayout {
+  const resolvedTextStyle = resolveLayoutTextStyle({
+    font: options.font,
+    textStyle: options.textStyle,
+  })
+  const baselineRatio = options.baselineRatio ?? 0.8
+  const maxCompiledShape = ensureMaxFillCompiledShape(options)
+  const streamPattern = prepareStreamRepeatFillPattern(
+    options.text,
+    resolvedTextStyle.font,
+    options.measurer,
+  )
+
+  const pass = layoutDenseFillPass({
+    compiledShape: maxCompiledShape,
+    densePattern: streamPattern,
+    startOffset: 0,
+    align: 'left',
+    baselineRatio,
+    allSlots: true,
+    fillPass: 1,
+  })
+
+  return {
+    font: resolvedTextStyle.font,
+    textStyle: resolvedTextStyle,
+    lineHeight: maxCompiledShape.bandHeight,
+    shape: maxCompiledShape.source,
+    compiledShape: maxCompiledShape,
+    bounds: maxCompiledShape.bounds,
+    lines: pass.lines,
+    exhausted: false,
+    autoFill: true,
+    autoFillMode: 'stream',
+    fillStrategy: 'max',
+  }
+}
diff --git a/src/render/render-layout-to-svg.test.ts b/src/render/render-layout-to-svg.test.ts
index 1a37e3b..f38a61e 100644
--- a/src/render/render-layout-to-svg.test.ts
+++ b/src/render/render-layout-to-svg.test.ts
@@ -111,6 +111,80 @@ describe('renderLayoutToSvg', () => {
     expect(svg).not.toContain('fill="#2563eb"')
   })
 
+  it('renders line-level font overrides for residual max-fill passes', () => {
+    const svg = renderLayoutToSvg({
+      font: '16px Test Sans',
+      lineHeight: 20,
+      shape: {
+        kind: 'polygon',
+        points: [
+          { x: 0, y: 0 },
+          { x: 120, y: 0 },
+          { x: 120, y: 40 },
+          { x: 0, y: 40 },
+        ],
+      },
+      compiledShape: {
+        kind: 'polygon',
+        source: {
+          kind: 'polygon',
+          points: [
+            { x: 0, y: 0 },
+            { x: 120, y: 0 },
+            { x: 120, y: 40 },
+            { x: 0, y: 40 },
+          ],
+        },
+        bounds: { left: 0, top: 0, right: 120, bottom: 40 },
+        bandHeight: 20,
+        minSlotWidth: 16,
+        bands: [],
+        debugView: {
+          kind: 'polygon',
+          points: [
+            { x: 0, y: 0 },
+            { x: 120, y: 0 },
+            { x: 120, y: 40 },
+            { x: 0, y: 40 },
+          ],
+        },
+      },
+      bounds: { left: 0, top: 0, right: 120, bottom: 40 },
+      lines: [
+        {
+          text: 'BASE',
+          width: 40,
+          start: { tokenIndex: 0, graphemeIndex: 0 },
+          end: { tokenIndex: 4, graphemeIndex: 0 },
+          x: 0,
+          top: 0,
+          baseline: 16,
+          slot: { left: 0, right: 60 },
+          fillPass: 1,
+        },
+        {
+          text: 'mini',
+          width: 24,
+          start: { tokenIndex: 4, graphemeIndex: 0 },
+          end: { tokenIndex: 8, graphemeIndex: 0 },
+          x: 60,
+          top: 12,
+          baseline: 24,
+          slot: { left: 60, right: 96 },
+          font: '11.52px Test Sans',
+          fillPass: 2,
+        },
+      ],
+      exhausted: false,
+      autoFill: true,
+      autoFillMode: 'dense',
+      fillStrategy: 'max',
+    } satisfies ShapeTextLayout)
+
+    expect(svg).toContain('style="font:16px Test Sans;"')
+    expect(svg).toContain('style="font:11.52px Test Sans;"')
+  })
+
   it('does not inject a border when shapeStyle only sets background color', () => {
     const layout = layoutTextInShape({
       text: 'fill only',
@@ -213,6 +287,8 @@ describe('renderLayoutToSvg', () => {
       lines: [],
       exhausted: true,
       autoFill: false,
+      autoFillMode: 'words',
+      fillStrategy: 'flow',
     } satisfies ShapeTextLayout)
 
     expect(svg).toContain('<svg')
diff --git a/src/render/render-layout-to-svg.ts b/src/render/render-layout-to-svg.ts
index d4e3e27..bbb8458 100644
--- a/src/render/render-layout-to-svg.ts
+++ b/src/render/render-layout-to-svg.ts
@@ -127,7 +127,7 @@ export function renderLayoutToSvg(
   for (let index = 0; index < layout.lines.length; index++) {
     const line = layout.lines[index]!
     pieces.push(
-      `<text x="${line.x}" y="${line.baseline}" fill="${escapeXmlText(textFill)}" style="font:${escapeXmlText(layout.font)};">${escapeXmlText(line.text)}</text>`,
+      `<text x="${line.x}" y="${line.baseline}" fill="${escapeXmlText(textFill)}" style="font:${escapeXmlText(line.font ?? layout.font)};">${escapeXmlText(line.text)}</text>`,
     )
   }
 
diff --git a/src/text/layout-next-line-from-dense-repeated-text.ts b/src/text/layout-next-line-from-dense-repeated-text.ts
new file mode 100644
index 0000000..f37718e
--- /dev/null
+++ b/src/text/layout-next-line-from-dense-repeated-text.ts
@@ -0,0 +1,85 @@
+import type { LayoutLineRange, PreparedLayoutToken } from '../types.js'
+import { getWordSliceText, getWordSliceWidth } from './layout-text-line-helpers.js'
+
+function findMaxSliceEnd(
+  pattern: PreparedLayoutToken,
+  start: number,
+  maxWidth: number,
+): number {
+  let low = start
+  let high = pattern.graphemes.length
+
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2)
+    const width = getWordSliceWidth(pattern, start, mid)
+
+    if (width <= maxWidth) {
+      low = mid
+      continue
+    }
+
+    high = mid - 1
+  }
+
+  return low
+}
+
+export function layoutNextLineFromDenseRepeatedText(
+  pattern: PreparedLayoutToken,
+  startOffset: number,
+  maxWidth: number,
+): LayoutLineRange | null {
+  if (pattern.graphemes.length === 0) {
+    return null
+  }
+
+  const availableWidth = Math.max(0, maxWidth)
+  const start = { tokenIndex: startOffset, graphemeIndex: 0 }
+  const textParts: string[] = []
+  let width = 0
+  let consumed = 0
+
+  const appendSlice = (sliceStart: number, sliceEnd: number) => {
+    if (sliceEnd <= sliceStart) {
+      return
+    }
+
+    textParts.push(getWordSliceText(pattern, sliceStart, sliceEnd))
+    width += getWordSliceWidth(pattern, sliceStart, sliceEnd)
+    consumed += sliceEnd - sliceStart
+  }
+
+  const tailEnd = findMaxSliceEnd(pattern, startOffset, availableWidth)
+  appendSlice(startOffset, tailEnd)
+
+  if (tailEnd === pattern.graphemes.length) {
+    const remainingAfterTail = availableWidth - width
+    if (remainingAfterTail >= pattern.width) {
+      const fullCycles = Math.floor(remainingAfterTail / pattern.width)
+      if (fullCycles > 0) {
+        textParts.push(pattern.text.repeat(fullCycles))
+        width += pattern.width * fullCycles
+        consumed += pattern.graphemes.length * fullCycles
+      }
+    }
+
+    const remainingAfterCycles = availableWidth - width
+    const prefixEnd = findMaxSliceEnd(pattern, 0, remainingAfterCycles)
+    appendSlice(0, prefixEnd)
+  }
+
+  if (consumed === 0) {
+    const forcedEnd = Math.min(startOffset + 1, pattern.graphemes.length)
+    appendSlice(startOffset, forcedEnd)
+  }
+
+  return {
+    text: textParts.join(''),
+    width,
+    start,
+    end: {
+      tokenIndex: (startOffset + consumed) % pattern.graphemes.length,
+      graphemeIndex: 0,
+    },
+  }
+}
diff --git a/src/text/prepare-dense-repeat-fill-pattern.ts b/src/text/prepare-dense-repeat-fill-pattern.ts
new file mode 100644
index 0000000..e8a6126
--- /dev/null
+++ b/src/text/prepare-dense-repeat-fill-pattern.ts
@@ -0,0 +1,21 @@
+import type { PreparedLayoutToken, TextMeasurer } from '../types.js'
+import { createMeasuredWordToken } from './segment-text-for-layout.js'
+
+export function prepareDenseRepeatFillPattern(
+  text: string,
+  font: string,
+  measurer: TextMeasurer,
+): PreparedLayoutToken {
+  const normalized = text.replace(/\s+/gu, '')
+
+  if (normalized.length === 0) {
+    throw new Error('dense autoFill requires at least one non-whitespace grapheme')
+  }
+
+  const pattern = createMeasuredWordToken(normalized, value => measurer.measureText(value, font))
+  if (pattern.width <= 0) {
+    throw new Error('dense autoFill requires measurable graphemes')
+  }
+
+  return pattern
+}
diff --git a/src/text/prepare-stream-repeat-fill-pattern.ts b/src/text/prepare-stream-repeat-fill-pattern.ts
new file mode 100644
index 0000000..ce02d58
--- /dev/null
+++ b/src/text/prepare-stream-repeat-fill-pattern.ts
@@ -0,0 +1,25 @@
+import type { PreparedLayoutToken, TextMeasurer } from '../types.js'
+import { createMeasuredWordToken } from './segment-text-for-layout.js'
+
+function normalizeRepeatStreamText(text: string): string {
+  return text.replace(/\r\n?/gu, '\n').replace(/[\n\t\f\v]+/gu, ' ')
+}
+
+export function prepareStreamRepeatFillPattern(
+  text: string,
+  font: string,
+  measurer: TextMeasurer,
+): PreparedLayoutToken {
+  const normalized = normalizeRepeatStreamText(text)
+
+  if (normalized.length === 0) {
+    throw new Error('stream autoFill requires at least one grapheme')
+  }
+
+  const pattern = createMeasuredWordToken(normalized, value => measurer.measureText(value, font))
+  if (pattern.width <= 0) {
+    throw new Error('stream autoFill requires measurable graphemes')
+  }
+
+  return pattern
+}
diff --git a/src/types.ts b/src/types.ts
index 0e6fca7..c5a920f 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -68,6 +68,9 @@ export type ShapeStyleInput = {
   shadow?: ShapeShadowInput
 }
 
+export type AutoFillMode = 'words' | 'dense' | 'stream'
+export type FillStrategy = 'flow' | 'max'
+
 export type ResolvedShapeStyle = {
   backgroundColor?: string
   borderColor: string
@@ -106,6 +109,8 @@ export type ShapeTextLine = LayoutLineRange & {
   top: number
   baseline: number
   slot: Interval
+  font?: string
+  fillPass?: 1 | 2
 }
 
 export type ShapeBounds = {
@@ -154,6 +159,8 @@ export type ShapeTextLayout = {
   lines: ShapeTextLine[]
   exhausted: boolean
   autoFill: boolean
+  autoFillMode?: AutoFillMode
+  fillStrategy?: FillStrategy
 }
 
 export type CompileShapeForLayoutOptions = {
@@ -169,6 +176,8 @@ export type LayoutTextInCompiledShapeOptions = {
   align?: 'left' | 'center'
   baselineRatio?: number
   autoFill?: boolean
+  autoFillMode?: AutoFillMode
+  fillStrategy?: FillStrategy
 } & (
   | {
       font: string
@@ -189,6 +198,8 @@ export type LayoutTextInShapeOptions = {
   minSlotWidth?: number
   baselineRatio?: number
   autoFill?: boolean
+  autoFillMode?: AutoFillMode
+  fillStrategy?: FillStrategy
 } & (
   | {
       font: string

From 64a9d374d4a371899eb80d7bc4202b370f2703d1 Mon Sep 17 00:00:00 2001
From: tqdat410 <danhlagi01472@gmail.com>
Date: Wed, 1 Apr 2026 12:57:30 +0700
Subject: [PATCH 05/12] docs: update max-fill stream notes

Co-authored-by: Codex <noreply@openai.com>
---
 README.md                 | 3 +++
 docs/project-changelog.md | 2 ++
 2 files changed, 5 insertions(+)

diff --git a/README.md b/README.md
index ecfa224..bbba2b8 100644
--- a/README.md
+++ b/README.md
@@ -78,6 +78,7 @@ const layout = layoutTextInShape({
   },
   lineHeight: 20,
   autoFill: true,
+  fillStrategy: 'max',
   shape: {
     kind: 'text-mask',
     text: '2',
@@ -109,6 +110,8 @@ const layout = layoutTextInShape({
 - The project takes inspiration from `pretext` for the `prepare -> layout` split and streaming line iteration, but owns its geometry, slot policy, and public API.
 - `text-mask` shapes are raster-compiled into reusable line bands. This is the default path for browser fonts such as `Arial`, and it is designed so callers can precompile `0-9` and `:` for clock-like UIs.
 - `autoFill: true` repeats the source text until the available shape bands are full.
+- `autoFillMode: 'words'` is the default readable repeat behavior. `autoFillMode: 'dense'` strips whitespace and breaks at grapheme boundaries to pack shapes harder for decorative fills.
+- `fillStrategy: 'max'` switches to an all-slots pass that fills every usable interval in reading order. It keeps spaces as normal graphemes instead of stripping them, and it does not fall back to smaller text for leftover pockets.
 - `textStyle` is the new data-driven API for size, weight, italic/oblique, family, and default text color. Legacy `font` string input still works.
 - `shapeStyle` lives in `renderLayoutToSvg()` because fill, border, and shadow do not affect line breaking or shape compilation.
 - For late-loading web fonts, compile after the font is ready if you want immediate cache reuse. The compiler skips cache writes until `document.fonts.check()` reports the font as ready.
diff --git a/docs/project-changelog.md b/docs/project-changelog.md
index 40cff79..97141a7 100644
--- a/docs/project-changelog.md
+++ b/docs/project-changelog.md
@@ -19,5 +19,7 @@
 
 - Added structured `textStyle` API for text size, family, weight, style, and default color
 - Added renderer-side `shapeStyle` API for shape fill, border, and shadow
+- Added `autoFillMode: 'dense'` for whitespace-stripped grapheme repeat fill inside compiled shape bands
+- Added `fillStrategy: 'max'` for all-slot glyph coverage without mini-font fallback, while preserving spaces in the repeat stream
 - Kept legacy `font`, `textFill`, `shapeFill`, and `shapeStroke` compatibility paths
 - Extended local demo and Playwright coverage for style and decoration controls

From 104f4ec4dac0efeecbaab063a2e7b67517867b0c Mon Sep 17 00:00:00 2001
From: tqdat410 <danhlagi01472@gmail.com>
Date: Thu, 2 Apr 2026 18:26:04 +0700
Subject: [PATCH 06/12] fix(dev): run demo and playwright directly on windows

Co-authored-by: Codex <noreply@openai.com>
---
 package.json              | 16 ++++++++--------
 playwright.config.ts      |  2 +-
 scripts/run-e2e-serve.mjs | 36 ++++++++++++++++++++++++++++++++++++
 vitest.config.ts          |  2 +-
 4 files changed, 46 insertions(+), 10 deletions(-)
 create mode 100644 scripts/run-e2e-serve.mjs

diff --git a/package.json b/package.json
index da1ba6c..3b63e85 100644
--- a/package.json
+++ b/package.json
@@ -22,14 +22,14 @@
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "check": "npm run typecheck && npm run test",
-    "e2e": "playwright test",
-    "e2e:ui": "playwright test --ui",
-    "e2e:headed": "playwright test --headed",
-    "e2e:debug": "playwright test --debug",
-    "e2e:serve": "npm run build && node ./scripts/serve-static-e2e.mjs",
-    "e2e:serve:dev": "node ./scripts/serve-static-e2e.mjs",
-    "demo": "npm run e2e:serve",
-    "demo:dev": "npm run e2e:serve:dev"
+    "e2e": "node ./node_modules/@playwright/test/cli.js test",
+    "e2e:ui": "node ./node_modules/@playwright/test/cli.js test --ui",
+    "e2e:headed": "node ./node_modules/@playwright/test/cli.js test --headed",
+    "e2e:debug": "node ./node_modules/@playwright/test/cli.js test --debug",
+    "e2e:serve": "node ./scripts/run-e2e-serve.mjs",
+    "e2e:serve:dev": "node ./scripts/run-e2e-serve.mjs --skip-build",
+    "demo": "node ./scripts/run-e2e-serve.mjs",
+    "demo:dev": "node ./scripts/run-e2e-serve.mjs --skip-build"
   },
   "keywords": [
     "svg",
diff --git a/playwright.config.ts b/playwright.config.ts
index 65560fe..f382c44 100644
--- a/playwright.config.ts
+++ b/playwright.config.ts
@@ -13,7 +13,7 @@ export default defineConfig({
     trace: 'on-first-retry',
   },
   webServer: {
-    command: 'npm run e2e:serve',
+    command: 'node ./scripts/run-e2e-serve.mjs',
     url: `${baseURL}/`,
     reuseExistingServer: !process.env.CI,
     timeout: 120_000,
diff --git a/scripts/run-e2e-serve.mjs b/scripts/run-e2e-serve.mjs
new file mode 100644
index 0000000..bcafb69
--- /dev/null
+++ b/scripts/run-e2e-serve.mjs
@@ -0,0 +1,36 @@
+import { spawn } from 'node:child_process'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url))
+const rootDir = path.resolve(scriptDir, '..')
+const skipBuild = process.argv.includes('--skip-build')
+
+function runBuild() {
+  return new Promise((resolve, reject) => {
+    const child = spawn(
+      process.execPath,
+      ['./node_modules/typescript/lib/tsc.js', '-p', 'tsconfig.build.json'],
+      {
+        cwd: rootDir,
+        stdio: 'inherit',
+      },
+    )
+
+    child.once('error', reject)
+    child.once('exit', (code) => {
+      if (code === 0) {
+        resolve()
+        return
+      }
+
+      reject(new Error(`Build failed with exit code ${code ?? 'unknown'}`))
+    })
+  })
+}
+
+if (!skipBuild) {
+  await runBuild()
+}
+
+await import('./serve-static-e2e.mjs')
diff --git a/vitest.config.ts b/vitest.config.ts
index ef3f442..065f4ac 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -3,7 +3,7 @@ import { defineConfig } from 'vitest/config'
 export default defineConfig({
   test: {
     environment: 'node',
-    exclude: ['e2e/**', 'node_modules/**', 'dist/**'],
+    exclude: ['e2e/**', 'node_modules/**', 'dist/**', '.claude/**'],
     coverage: {
       provider: 'v8',
       include: ['src/**/*.ts'],

From f484c62c1cdb497a819a687e757cf352a5cc41db Mon Sep 17 00:00:00 2001
From: tqdat410 <danhlagi01472@gmail.com>
Date: Thu, 2 Apr 2026 18:26:34 +0700
Subject: [PATCH 07/12] feat(text-mask): add fit-content sizing and demo
 controls

Co-authored-by: Codex <noreply@openai.com>
---
 e2e/fixtures/demo-fill-presets.js             |  52 +++
 e2e/fixtures/demo-payload-helpers.js          | 268 ++++++++++++
 e2e/fixtures/demo-scenarios.js                |  80 ++++
 e2e/fixtures/demo-svg-viewport-controller.js  | 138 ++++++
 e2e/fixtures/demo-ui-controller.js            | 277 ++++++++++++
 e2e/fixtures/index.html                       | 110 ++++-
 e2e/fixtures/shape-text-e2e-app.js            | 401 ++++++------------
 e2e/shape-text-local-e2e.spec.ts              | 307 ++++++++++++++
 src/index.ts                                  |   6 +
 .../layout-flow-lines-in-compiled-shape.ts    | 104 +++++
 src/layout/layout-text-in-compiled-shape.ts   |   8 +
 src/layout/layout-text-in-shape.test.ts       | 112 +++++
 src/layout/resolve-flow-layout.ts             |  94 +---
 src/layout/resolve-max-fill-helpers.ts        |  22 +
 src/layout/resolve-max-fill-layout.ts         |  27 +-
 .../resolve-sequential-shape-regions.ts       | 144 +++++++
 src/shape/build-text-mask-bands-from-alpha.ts | 106 +++++
 ...compile-text-mask-shape-for-layout.test.ts | 139 +++++-
 .../compile-text-mask-shape-for-layout.ts     | 295 ++++++-------
 src/shape/render-text-mask-raster.ts          |  54 +++
 src/shape/resolve-text-mask-shape-size.ts     | 112 +++++
 src/shape/segment-text-mask-graphemes.ts      |  33 ++
 src/types.ts                                  |  31 +-
 23 files changed, 2344 insertions(+), 576 deletions(-)
 create mode 100644 e2e/fixtures/demo-fill-presets.js
 create mode 100644 e2e/fixtures/demo-payload-helpers.js
 create mode 100644 e2e/fixtures/demo-scenarios.js
 create mode 100644 e2e/fixtures/demo-svg-viewport-controller.js
 create mode 100644 e2e/fixtures/demo-ui-controller.js
 create mode 100644 src/layout/layout-flow-lines-in-compiled-shape.ts
 create mode 100644 src/layout/resolve-max-fill-helpers.ts
 create mode 100644 src/layout/resolve-sequential-shape-regions.ts
 create mode 100644 src/shape/build-text-mask-bands-from-alpha.ts
 create mode 100644 src/shape/render-text-mask-raster.ts
 create mode 100644 src/shape/resolve-text-mask-shape-size.ts
 create mode 100644 src/shape/segment-text-mask-graphemes.ts

diff --git a/e2e/fixtures/demo-fill-presets.js b/e2e/fixtures/demo-fill-presets.js
new file mode 100644
index 0000000..cd29369
--- /dev/null
+++ b/e2e/fixtures/demo-fill-presets.js
@@ -0,0 +1,52 @@
+function createSeededRandom(seed) {
+  let value = seed >>> 0
+  return () => {
+    value = (value * 1664525 + 1013904223) >>> 0
+    return value / 0x100000000
+  }
+}
+
+function createRandomText(alphabet, length, seed) {
+  const random = createSeededRandom(seed)
+  let text = ''
+
+  for (let index = 0; index < length; index++) {
+    const nextIndex = Math.floor(random() * alphabet.length)
+    text += alphabet[nextIndex]
+  }
+
+  return text
+}
+
+export const fillTextPresets = [
+  { id: 'custom', label: 'Custom' },
+  { id: 'ascii-random', label: 'ASCII', alphabet: 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789!@#$%^&*()[]{}<>?/|+-=', length: 96, seed: 0x41534349 },
+  { id: 'binary-random', label: 'BINARY', alphabet: '01', length: 128, seed: 0x42494e41 },
+  { id: 'hex-random', label: 'HEX', alphabet: '0123456789ABCDEF', length: 112, seed: 0x48455821 },
+  { id: 'octal-random', label: 'OCTAL', alphabet: '01234567', length: 120, seed: 0x4f435441 },
+  { id: 'symbol-random', label: 'SYMBOL', alphabet: '<>[]{}()/\\|+-=_*#@~', length: 96, seed: 0x53594d42 },
+]
+
+export function findFillTextPresetById(id) {
+  return fillTextPresets.find(preset => preset.id === id) ?? fillTextPresets[0]
+}
+
+export function identifyFillTextPresetId(text) {
+  for (let index = 0; index < fillTextPresets.length; index++) {
+    const preset = fillTextPresets[index]
+    if (preset.id !== 'custom' && resolveFillTextPresetText(preset.id) === text) {
+      return preset.id
+    }
+  }
+
+  return 'custom'
+}
+
+export function resolveFillTextPresetText(id) {
+  const preset = findFillTextPresetById(id)
+  if (preset.id === 'custom') {
+    return null
+  }
+
+  return createRandomText(preset.alphabet, preset.length, preset.seed)
+}
diff --git a/e2e/fixtures/demo-payload-helpers.js b/e2e/fixtures/demo-payload-helpers.js
new file mode 100644
index 0000000..92ac7bb
--- /dev/null
+++ b/e2e/fixtures/demo-payload-helpers.js
@@ -0,0 +1,268 @@
+function clonePoints(points) {
+  return points.map(point => ({ x: point.x, y: point.y }))
+}
+
+function cloneDemoState(state) {
+  return {
+    ...state,
+    polygonPoints: clonePoints(state.polygonPoints),
+  }
+}
+
+function assertFiniteNumber(value, label) {
+  if (!Number.isFinite(value)) {
+    throw new Error(`${label} must be a finite number`)
+  }
+
+  return value
+}
+
+function assertPositiveFiniteNumber(value, label) {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`${label} must be a finite positive number`)
+  }
+
+  return value
+}
+
+function hasOwnProperty(value, key) {
+  return Object.prototype.hasOwnProperty.call(value, key)
+}
+
+function normalizeTextMaskSize(size) {
+  if (size === undefined) {
+    return { mode: 'fit-content' }
+  }
+
+  if (size === null || typeof size !== 'object' || Array.isArray(size)) {
+    throw new Error('layout.shape.size must be an object')
+  }
+
+  const mode = size.mode ?? 'fit-content'
+  if (mode !== 'fit-content' && mode !== 'fixed') {
+    throw new Error('layout.shape.size.mode must be fit-content or fixed')
+  }
+
+  const padding =
+    size.padding === undefined
+      ? undefined
+      : assertFiniteNumber(Number(size.padding), 'layout.shape.size.padding')
+
+  if (padding !== undefined && padding < 0) {
+    throw new Error('layout.shape.size.padding must be a finite non-negative number')
+  }
+
+  if (mode === 'fixed') {
+    return {
+      mode,
+      width: assertPositiveFiniteNumber(Number(size.width), 'layout.shape.size.width'),
+      height: assertPositiveFiniteNumber(Number(size.height), 'layout.shape.size.height'),
+      padding,
+    }
+  }
+
+  return {
+    mode,
+    padding,
+  }
+}
+
+function normalizeShape(shape) {
+  if (shape.kind === 'text-mask') {
+    if (hasOwnProperty(shape, 'width') || hasOwnProperty(shape, 'height') || hasOwnProperty(shape, 'padding')) {
+      throw new Error('layout.shape.width, height, and padding moved to layout.shape.size')
+    }
+
+    const shapeTextMode = shape.shapeTextMode ?? 'whole-text'
+    if (shapeTextMode !== 'whole-text' && shapeTextMode !== 'per-character') {
+      throw new Error('layout.shape.shapeTextMode must be whole-text or per-character')
+    }
+
+    return {
+      kind: 'text-mask',
+      text: String(shape.text),
+      font: String(shape.font),
+      size: normalizeTextMaskSize(shape.size),
+      shapeTextMode,
+      maskScale:
+        shape.maskScale === undefined
+          ? undefined
+          : assertFiniteNumber(Number(shape.maskScale), 'layout.shape.maskScale'),
+      alphaThreshold:
+        shape.alphaThreshold === undefined
+          ? undefined
+          : assertFiniteNumber(Number(shape.alphaThreshold), 'layout.shape.alphaThreshold'),
+    }
+  }
+
+  if (!Array.isArray(shape.points) || shape.points.length < 3) {
+    throw new Error('layout.shape.points must contain at least 3 points')
+  }
+
+  return {
+    kind: 'polygon',
+    points: shape.points.map((point, index) => ({
+      x: assertFiniteNumber(Number(point.x), `layout.shape.points[${index}].x`),
+      y: assertFiniteNumber(Number(point.y), `layout.shape.points[${index}].y`),
+    })),
+  }
+}
+
+function buildTextMaskSize(state) {
+  if (state.shapeSizeMode === 'fixed') {
+    return {
+      mode: 'fixed',
+      width: state.shapeWidth,
+      height: state.shapeHeight,
+      padding: state.shapePadding,
+    }
+  }
+
+  return {
+    mode: 'fit-content',
+    padding: state.shapePadding,
+  }
+}
+
+export function buildDemoPayload(state) {
+  const shape =
+    state.shapeKind === 'text-mask'
+      ? {
+          kind: 'text-mask',
+          text: state.shapeText,
+          font: state.shapeFont,
+          size: buildTextMaskSize(state),
+          shapeTextMode: state.shapeTextMode,
+          maskScale: state.shapeMaskScale,
+          alphaThreshold: state.shapeAlphaThreshold,
+        }
+      : {
+          kind: 'polygon',
+          points: clonePoints(state.polygonPoints),
+        }
+
+  return {
+    layout: {
+      text: state.text,
+      textStyle: {
+        family: '"Helvetica Neue", Arial, sans-serif',
+        size: state.textSize,
+        weight: state.textWeight,
+        style: state.textItalic ? 'italic' : 'normal',
+        color: state.textColor,
+      },
+      lineHeight: state.lineHeight,
+      shape,
+      minSlotWidth: state.minSlotWidth ?? (state.fillStrategy === 'max' ? 8 : 24),
+      autoFill: state.autoFill,
+      autoFillMode: state.autoFillMode,
+      fillStrategy: state.fillStrategy,
+    },
+    render: {
+      background: state.background,
+      shapeStyle: {
+        backgroundColor: state.shapeFill,
+        borderColor: state.shapeBorderColor,
+        borderWidth: state.shapeBorderWidth,
+        shadow: state.shapeShadow
+          ? {
+              color: 'rgba(15, 23, 42, 0.22)',
+              blur: 6,
+              offsetX: 0,
+              offsetY: 6,
+            }
+          : undefined,
+      },
+      showShape: state.showShape,
+      padding: state.renderPadding,
+    },
+  }
+}
+
+export function serializeDemoPayload(state) {
+  return JSON.stringify(buildDemoPayload(state), null, 2)
+}
+
+export function applyDemoPayloadToState(state, payload) {
+  if (payload === null || typeof payload !== 'object') {
+    throw new Error('payload must be an object')
+  }
+
+  const layout = payload.layout
+  const render = payload.render
+  if (layout === null || typeof layout !== 'object') {
+    throw new Error('payload.layout must be an object')
+  }
+  if (render === null || typeof render !== 'object') {
+    throw new Error('payload.render must be an object')
+  }
+
+  const nextState = cloneDemoState(state)
+
+  nextState.text = String(layout.text ?? nextState.text)
+  nextState.lineHeight = assertFiniteNumber(Number(layout.lineHeight ?? nextState.lineHeight), 'layout.lineHeight')
+  nextState.minSlotWidth =
+    layout.minSlotWidth === undefined
+      ? nextState.minSlotWidth
+      : assertFiniteNumber(Number(layout.minSlotWidth), 'layout.minSlotWidth')
+  nextState.autoFill = Boolean(layout.autoFill ?? nextState.autoFill)
+  nextState.fillStrategy =
+    layout.fillStrategy === undefined ? nextState.fillStrategy : layout.fillStrategy === 'max' ? 'max' : 'flow'
+  nextState.autoFillMode =
+    layout.autoFillMode === undefined
+      ? nextState.autoFillMode
+      : layout.autoFillMode === 'dense' || layout.autoFillMode === 'stream'
+        ? layout.autoFillMode
+        : 'words'
+
+  if (layout.textStyle !== null && typeof layout.textStyle === 'object') {
+    nextState.textSize = assertFiniteNumber(
+      Number(layout.textStyle.size ?? nextState.textSize),
+      'layout.textStyle.size',
+    )
+    nextState.textWeight = Number(layout.textStyle.weight ?? nextState.textWeight)
+    nextState.textItalic =
+      layout.textStyle.style === undefined
+        ? nextState.textItalic
+        : String(layout.textStyle.style) !== 'normal'
+    nextState.textColor = String(layout.textStyle.color ?? nextState.textColor)
+  }
+
+  const shape = normalizeShape(layout.shape)
+  nextState.shapeKind = shape.kind
+  if (shape.kind === 'text-mask') {
+    nextState.shapeText = shape.text
+    nextState.shapeFont = shape.font
+    nextState.shapeSizeMode = shape.size.mode === 'fixed' ? 'fixed' : 'fit-content'
+    if (shape.size.mode === 'fixed') {
+      nextState.shapeWidth = shape.size.width
+      nextState.shapeHeight = shape.size.height
+    }
+    nextState.shapeTextMode = shape.shapeTextMode
+    nextState.shapePadding = shape.size.padding ?? 0
+    nextState.shapeMaskScale = shape.maskScale ?? 2
+    nextState.shapeAlphaThreshold = shape.alphaThreshold
+  } else {
+    nextState.polygonPoints = shape.points
+  }
+
+  nextState.background = String(render.background ?? nextState.background)
+  nextState.showShape = Boolean(render.showShape ?? nextState.showShape)
+  nextState.renderPadding = assertFiniteNumber(
+    Number(render.padding ?? nextState.renderPadding),
+    'render.padding',
+  )
+
+  if (render.shapeStyle !== null && typeof render.shapeStyle === 'object') {
+    nextState.shapeFill = String(render.shapeStyle.backgroundColor ?? nextState.shapeFill)
+    nextState.shapeBorderColor = String(render.shapeStyle.borderColor ?? nextState.shapeBorderColor)
+    nextState.shapeBorderWidth = assertFiniteNumber(
+      Number(render.shapeStyle.borderWidth ?? nextState.shapeBorderWidth),
+      'render.shapeStyle.borderWidth',
+    )
+    nextState.shapeShadow = render.shapeStyle.shadow !== undefined
+  }
+
+  Object.assign(state, nextState)
+  state.polygonPoints = nextState.polygonPoints
+}
diff --git a/e2e/fixtures/demo-scenarios.js b/e2e/fixtures/demo-scenarios.js
new file mode 100644
index 0000000..516ff98
--- /dev/null
+++ b/e2e/fixtures/demo-scenarios.js
@@ -0,0 +1,80 @@
+const defaultParagraph = [
+  'Shape text lets a paragraph travel inside a silhouette thay vi chi wrap quanh float.',
+  'Ban co the dung no de render layout hinh so 2, badge, logo block, hoac poster typography.',
+  'E2E local o day uu tien deterministic browser path: build dist, import module, render SVG, assert lai state.',
+].join(' ')
+
+function createDigitTwoPolygon(width, height) {
+  return [
+    { x: width * 0.12, y: height * 0.1 },
+    { x: width * 0.34, y: 0 },
+    { x: width * 0.72, y: height * 0.02 },
+    { x: width * 0.9, y: height * 0.16 },
+    { x: width * 0.88, y: height * 0.32 },
+    { x: width * 0.74, y: height * 0.44 },
+    { x: width * 0.5, y: height * 0.57 },
+    { x: width * 0.26, y: height * 0.72 },
+    { x: width * 0.14, y: height * 0.86 },
+    { x: width * 0.88, y: height * 0.86 },
+    { x: width * 0.86, y: height },
+    { x: 0, y: height },
+    { x: 0, y: height * 0.78 },
+    { x: width * 0.12, y: height * 0.64 },
+    { x: width * 0.35, y: height * 0.5 },
+    { x: width * 0.62, y: height * 0.35 },
+    { x: width * 0.74, y: height * 0.26 },
+    { x: width * 0.72, y: height * 0.14 },
+    { x: width * 0.58, y: height * 0.08 },
+    { x: width * 0.34, y: height * 0.08 },
+  ]
+}
+
+export const demoScenarios = {
+  'glyph-two-repeat': {
+    shape: {
+      kind: 'text-mask',
+      text: '23',
+      font: '700 420px Arial',
+      size: {
+        mode: 'fit-content',
+        padding: 10,
+      },
+      shapeTextMode: 'whole-text',
+      maskScale: 2,
+    },
+    autoFill: true,
+    text: 'ONE',
+  },
+  'digit-two-wide': {
+    shape: { kind: 'polygon', points: createDigitTwoPolygon(340, 460) },
+    text: defaultParagraph,
+  },
+  'digit-two-narrow': {
+    shape: { kind: 'polygon', points: createDigitTwoPolygon(240, 460) },
+    text: defaultParagraph,
+  },
+  'rectangle-wide': {
+    shape: {
+      kind: 'polygon',
+      points: [
+        { x: 0, y: 0 },
+        { x: 340, y: 0 },
+        { x: 340, y: 360 },
+        { x: 0, y: 360 },
+      ],
+    },
+    text: defaultParagraph,
+  },
+  'rectangle-narrow': {
+    shape: {
+      kind: 'polygon',
+      points: [
+        { x: 0, y: 0 },
+        { x: 220, y: 0 },
+        { x: 220, y: 360 },
+        { x: 0, y: 360 },
+      ],
+    },
+    text: defaultParagraph,
+  },
+}
diff --git a/e2e/fixtures/demo-svg-viewport-controller.js b/e2e/fixtures/demo-svg-viewport-controller.js
new file mode 100644
index 0000000..faf021d
--- /dev/null
+++ b/e2e/fixtures/demo-svg-viewport-controller.js
@@ -0,0 +1,138 @@
+const MIN_ZOOM = 0.25
+const MAX_ZOOM = 4
+const ZOOM_STEP = 1.25
+
+function clampZoom(value) {
+  return Math.max(MIN_ZOOM, Math.min(MAX_ZOOM, value))
+}
+
+function parseSvgDimension(svg, attribute) {
+  const attributeValue = Number(svg.getAttribute(attribute))
+  if (Number.isFinite(attributeValue) && attributeValue > 0) {
+    return attributeValue
+  }
+
+  const viewBox = svg.getAttribute('viewBox')
+  if (!viewBox) {
+    return 0
+  }
+
+  const parts = viewBox.split(/\s+/).map(Number)
+  return Number.isFinite(parts[attribute === 'width' ? 2 : 3]) ? parts[attribute === 'width' ? 2 : 3] : 0
+}
+
+function getContentBounds(svg) {
+  const width = parseSvgDimension(svg, 'width')
+  const height = parseSvgDimension(svg, 'height')
+  let left = 0
+  let top = 0
+  let right = width
+  let bottom = height
+
+  try {
+    const box = svg.getBBox()
+    if (Number.isFinite(box.x) && Number.isFinite(box.width)) {
+      left = Math.min(left, box.x)
+      right = Math.max(right, box.x + box.width)
+    }
+    if (Number.isFinite(box.y) && Number.isFinite(box.height)) {
+      top = Math.min(top, box.y)
+      bottom = Math.max(bottom, box.y + box.height)
+    }
+  } catch {
+    // Ignore SVG bbox failures and fall back to declared dimensions.
+  }
+
+  return {
+    left,
+    top,
+    width: right - left,
+    height: bottom - top,
+  }
+}
+
+export function createDemoSvgViewportController({ state, elements }) {
+  let intrinsicSvgWidth = 0
+  let intrinsicSvgHeight = 0
+  let contentOffsetX = 0
+  let contentOffsetY = 0
+
+  function syncZoomLabel() {
+    elements.zoomValue.textContent = `${Math.round(state.stageZoom * 100)}%`
+  }
+
+  function applyZoom() {
+    const svg = elements.stage.querySelector('svg')
+    if (svg instanceof SVGSVGElement) {
+      svg.style.width = `${intrinsicSvgWidth * state.stageZoom}px`
+      svg.style.height = `${intrinsicSvgHeight * state.stageZoom}px`
+      svg.style.marginLeft = `${contentOffsetX * state.stageZoom}px`
+      svg.style.marginTop = `${contentOffsetY * state.stageZoom}px`
+      svg.style.transform = 'none'
+    }
+
+    elements.stage.style.width = `${state.stageSvgWidth * state.stageZoom}px`
+    elements.stage.style.height = `${state.stageSvgHeight * state.stageZoom}px`
+    syncZoomLabel()
+  }
+
+  function syncStageMetrics() {
+    const svg = elements.stage.querySelector('svg')
+    if (!(svg instanceof SVGSVGElement)) {
+      intrinsicSvgWidth = 0
+      intrinsicSvgHeight = 0
+      contentOffsetX = 0
+      contentOffsetY = 0
+      state.stageSvgWidth = 0
+      state.stageSvgHeight = 0
+      elements.stage.style.width = '0px'
+      elements.stage.style.height = '0px'
+      return
+    }
+
+    const bounds = getContentBounds(svg)
+    intrinsicSvgWidth = parseSvgDimension(svg, 'width')
+    intrinsicSvgHeight = parseSvgDimension(svg, 'height')
+    contentOffsetX = Math.max(0, -bounds.left)
+    contentOffsetY = Math.max(0, -bounds.top)
+    state.stageSvgWidth = bounds.width
+    state.stageSvgHeight = bounds.height
+    svg.style.display = 'block'
+    svg.style.transformOrigin = 'top left'
+  }
+
+  return {
+    renderSvg(svgMarkup) {
+      elements.stage.innerHTML = svgMarkup
+      syncStageMetrics()
+      applyZoom()
+    },
+    zoomIn() {
+      state.stageZoom = clampZoom(state.stageZoom * ZOOM_STEP)
+      applyZoom()
+    },
+    zoomOut() {
+      state.stageZoom = clampZoom(state.stageZoom / ZOOM_STEP)
+      applyZoom()
+    },
+    resetZoom() {
+      state.stageZoom = 1
+      applyZoom()
+    },
+    fitZoom() {
+      const width = state.stageSvgWidth
+      const height = state.stageSvgHeight
+      if (width <= 0 || height <= 0) {
+        return
+      }
+
+      const viewportWidth = Math.max(1, elements.stageViewport.clientWidth - 24)
+      const viewportHeight = Math.max(1, elements.stageViewport.clientHeight - 24)
+      state.stageZoom = clampZoom(Math.min(viewportWidth / width, viewportHeight / height))
+      elements.stageViewport.scrollLeft = 0
+      elements.stageViewport.scrollTop = 0
+      applyZoom()
+    },
+    syncZoomLabel,
+  }
+}
diff --git a/e2e/fixtures/demo-ui-controller.js b/e2e/fixtures/demo-ui-controller.js
new file mode 100644
index 0000000..3c67085
--- /dev/null
+++ b/e2e/fixtures/demo-ui-controller.js
@@ -0,0 +1,277 @@
+import { layoutTextInShape, renderLayoutToSvg } from '/dist/index.js'
+import {
+  applyDemoPayloadToState,
+  buildDemoPayload,
+  serializeDemoPayload,
+} from './demo-payload-helpers.js'
+import {
+  fillTextPresets,
+  findFillTextPresetById,
+  identifyFillTextPresetId,
+  resolveFillTextPresetText,
+} from './demo-fill-presets.js'
+import { demoScenarios } from './demo-scenarios.js'
+
+export function createDemoUiController({ state, elements, measurer, viewport }) {
+  let hasUserEditedText = false
+  let hasUserEditedShapeText = false
+  let hasPayloadDraftChanges = false
+  let lastCommittedState = cloneStateSnapshot(state)
+  let lastRenderedState = null
+
+  function setPayloadError(message = '') {
+    state.payloadError = message
+    elements.payloadError.textContent = message
+    elements.payloadError.hidden = message.length === 0
+  }
+
+  function syncPresetSelection() {
+    state.fillPresetId = identifyFillTextPresetId(state.text)
+  }
+
+  function cloneStateSnapshot(source) {
+    return {
+      ...source,
+      polygonPoints: source.polygonPoints.map(point => ({ ...point })),
+    }
+  }
+
+  function updateSummary() {
+    const resolvedShapeWidth =
+      state.layout === null ? null : state.layout.compiledShape.bounds.right - state.layout.compiledShape.bounds.left
+    const resolvedShapeHeight =
+      state.layout === null ? null : state.layout.compiledShape.bounds.bottom - state.layout.compiledShape.bounds.top
+
+    elements.summary.textContent = JSON.stringify(
+      {
+        scenario: state.scenario,
+        shapeKind: state.shapeKind,
+        shapeText: state.shapeText,
+        shapeTextMode: state.shapeTextMode,
+        shapeSizeMode: state.shapeSizeMode,
+        resolvedShapeWidth,
+        resolvedShapeHeight,
+        fillPresetId: state.fillPresetId,
+        autoFill: state.layout?.autoFill ?? false,
+        autoFillMode: state.layout?.autoFillMode ?? null,
+        fillStrategy: state.layout?.fillStrategy ?? null,
+        lineCount: state.layout?.lines.length ?? 0,
+        exhausted: state.layout?.exhausted ?? null,
+        stageZoom: state.stageZoom,
+        stageSvgWidth: state.stageSvgWidth,
+        stageSvgHeight: state.stageSvgHeight,
+        payloadError: state.payloadError,
+        firstLine: state.layout?.lines[0]?.text ?? null,
+        lastLine: state.layout?.lines.at(-1)?.text ?? null,
+      },
+      null,
+      2,
+    )
+  }
+
+  function renderStateSnapshot(snapshot) {
+    const payload = buildDemoPayload(snapshot)
+    const layout = layoutTextInShape({ ...payload.layout, measurer })
+    const svg = renderLayoutToSvg(layout, payload.render)
+
+    return { layout, svg }
+  }
+
+  function commitRenderedState(nextState, rendered) {
+    const nextPolygonPoints = nextState.polygonPoints.map(point => ({ ...point }))
+
+    Object.assign(state, nextState)
+    state.polygonPoints = nextPolygonPoints
+    state.layout = rendered.layout
+    state.svg = rendered.svg
+    syncPresetSelection()
+    syncControls()
+    syncPayloadInput()
+    setPayloadError('')
+    viewport.renderSvg(rendered.svg)
+    updateSummary()
+    lastCommittedState = cloneStateSnapshot(state)
+    lastRenderedState = rendered
+  }
+
+  function restoreCommittedState(message) {
+    if (lastRenderedState === null) {
+      throw new Error(message)
+    }
+
+    const restoredState = cloneStateSnapshot(lastCommittedState)
+    const restoredPolygonPoints = restoredState.polygonPoints.map(point => ({ ...point }))
+
+    Object.assign(state, restoredState)
+    state.polygonPoints = restoredPolygonPoints
+    state.layout = lastRenderedState.layout
+    state.svg = lastRenderedState.svg
+    syncPresetSelection()
+    syncControls()
+    syncPayloadInput()
+    setPayloadError(message)
+    viewport.renderSvg(state.svg)
+    updateSummary()
+  }
+
+  function syncPayloadInput(force = false) {
+    const nextDraft = serializeDemoPayload(state)
+    if (force || !hasPayloadDraftChanges) {
+      state.payloadDraft = nextDraft
+      elements.payloadInput.value = nextDraft
+      return
+    }
+
+    state.payloadDraft = elements.payloadInput.value
+  }
+
+  function syncControls() {
+    const isTextMask = state.shapeKind === 'text-mask'
+    const showFixedSizeFields = isTextMask && state.shapeSizeMode === 'fixed'
+
+    elements.textInput.value = state.text
+    elements.shapeTextInput.value = state.shapeText
+    elements.shapeTextInput.disabled = !isTextMask
+    elements.shapeTextModeSelect.value = state.shapeTextMode
+    elements.shapeTextModeSelect.disabled = !isTextMask
+    elements.shapeSizeModeSelect.value = state.shapeSizeMode
+    elements.shapeSizeModeSelect.disabled = !isTextMask
+    elements.shapeFixedWidthField.hidden = !showFixedSizeFields
+    elements.shapeFixedHeightField.hidden = !showFixedSizeFields
+    elements.shapeFixedWidthInput.disabled = !showFixedSizeFields
+    elements.shapeFixedHeightInput.disabled = !showFixedSizeFields
+    elements.shapeFixedWidthInput.value = String(state.shapeWidth)
+    elements.shapeFixedHeightInput.value = String(state.shapeHeight)
+    elements.fillPresetSelect.value = state.fillPresetId
+    elements.lineHeightInput.value = String(state.lineHeight)
+    elements.lineHeightValue.textContent = String(state.lineHeight)
+    elements.textSizeInput.value = String(state.textSize)
+    elements.textSizeValue.textContent = String(state.textSize)
+    elements.textWeightSelect.value = String(state.textWeight)
+    elements.textItalicInput.checked = state.textItalic
+    elements.textColorInput.value = state.textColor
+    elements.autoFillModeSelect.value = state.fillStrategy === 'max' ? 'max' : state.autoFillMode
+    elements.showShapeInput.checked = state.showShape
+    elements.shapeFillInput.value = state.shapeFill
+    elements.shapeBorderWidthInput.value = String(state.shapeBorderWidth)
+    elements.shapeBorderWidthValue.textContent = String(state.shapeBorderWidth)
+    elements.shapeBorderColorInput.value = state.shapeBorderColor
+    elements.shapeShadowInput.checked = state.shapeShadow
+  }
+
+  function applyScenario(name) {
+    const scenario = demoScenarios[name]
+    if (!scenario) throw new Error(`Unknown scenario: ${name}`)
+
+    state.scenario = name
+    state.shapeKind = scenario.shape.kind
+    state.autoFill = Boolean(scenario.autoFill)
+    if (!hasUserEditedText && scenario.text !== undefined) {
+      state.text = scenario.text
+    }
+
+    if (scenario.shape.kind === 'text-mask') {
+      const size = scenario.shape.size ?? {}
+      if (!hasUserEditedShapeText) {
+        state.shapeText = scenario.shape.text
+      }
+      state.shapeFont = scenario.shape.font
+      state.shapeSizeMode = size.mode === 'fixed' ? 'fixed' : 'fit-content'
+      if (size.mode === 'fixed') {
+        state.shapeWidth = size.width
+        state.shapeHeight = size.height
+      }
+      state.shapeTextMode = scenario.shape.shapeTextMode ?? 'whole-text'
+      state.shapePadding = size.padding ?? 0
+      state.shapeMaskScale = scenario.shape.maskScale ?? 2
+      state.shapeAlphaThreshold = scenario.shape.alphaThreshold
+      return
+    }
+
+    state.polygonPoints = scenario.shape.points.map(point => ({ ...point }))
+  }
+
+  function renderCurrentState() {
+    const nextState = cloneStateSnapshot(state)
+
+    try {
+      commitRenderedState(nextState, renderStateSnapshot(nextState))
+    } catch (error) {
+      restoreCommittedState(error instanceof Error ? error.message : String(error))
+    }
+  }
+
+  return {
+    populateFillPresetOptions() {
+      fillTextPresets.forEach(preset => {
+        const option = document.createElement('option')
+        option.value = preset.id
+        option.textContent = preset.label
+        elements.fillPresetSelect.append(option)
+      })
+    },
+    applyScenario,
+    renderCurrentState,
+    syncControls,
+    syncPayloadInput,
+    applyFillSelection(value) {
+      if (value === 'max') {
+        state.autoFillMode = 'stream'
+        state.fillStrategy = 'max'
+        return
+      }
+
+      state.autoFillMode = value
+      state.fillStrategy = 'flow'
+    },
+    handleTextEdited(value) {
+      state.text = value
+      hasUserEditedText = true
+      state.fillPresetId = 'custom'
+      syncPayloadInput()
+    },
+    handleShapeTextEdited(value) {
+      state.shapeText = value
+      hasUserEditedShapeText = true
+      syncPayloadInput()
+    },
+    handleShapeTextModeSelected(value) {
+      state.shapeTextMode = value === 'per-character' ? 'per-character' : 'whole-text'
+      syncPayloadInput()
+    },
+    handleShapeSizeModeSelected(value) {
+      state.shapeSizeMode = value === 'fixed' ? 'fixed' : 'fit-content'
+      syncControls()
+      syncPayloadInput()
+    },
+    handlePresetSelected(id) {
+      const preset = findFillTextPresetById(id)
+      const nextText = resolveFillTextPresetText(preset.id)
+      if (nextText === null) return
+      state.text = nextText
+      state.fillPresetId = preset.id
+      hasUserEditedText = true
+      syncControls()
+      syncPayloadInput()
+    },
+    handlePayloadDraftEdited(value) {
+      state.payloadDraft = value
+      hasPayloadDraftChanges = true
+    },
+    applyPayloadText() {
+      const nextState = cloneStateSnapshot(state)
+      applyDemoPayloadToState(nextState, JSON.parse(elements.payloadInput.value))
+      const rendered = renderStateSnapshot(nextState)
+      hasPayloadDraftChanges = false
+      hasUserEditedText = true
+      hasUserEditedShapeText = true
+      commitRenderedState(nextState, rendered)
+    },
+    resetPayloadDraft() {
+      hasPayloadDraftChanges = false
+      syncPayloadInput(true)
+      setPayloadError('')
+    },
+    setPayloadError,
+  }
+}
diff --git a/e2e/fixtures/index.html b/e2e/fixtures/index.html
index 7a2457a..c003aee 100644
--- a/e2e/fixtures/index.html
+++ b/e2e/fixtures/index.html
@@ -70,6 +70,11 @@
         background: #ffffff;
       }
 
+      .payload-textarea {
+        min-height: 220px;
+        font: 12px/1.6 ui-monospace, SFMono-Regular, Consolas, monospace;
+      }
+
       button {
         border: 1px solid #cbd5e1;
         background: white;
@@ -90,12 +95,36 @@
         gap: 16px;
       }
 
-      #stage {
+      .stage-card {
+        display: grid;
+        gap: 12px;
+      }
+
+      .stage-toolbar {
+        display: flex;
+        gap: 10px;
+        align-items: center;
+        flex-wrap: wrap;
+      }
+
+      #stage-viewport {
         min-height: 520px;
+        max-height: 72vh;
         border-radius: 24px;
         background: rgba(255, 255, 255, 0.8);
         border: 1px solid rgba(148, 163, 184, 0.35);
         padding: 16px;
+        overflow: auto;
+      }
+
+      #stage {
+        width: max-content;
+        height: max-content;
+        transform-origin: top left;
+      }
+
+      #stage svg {
+        display: block;
       }
 
       #summary {
@@ -131,6 +160,10 @@
         color: #334155;
       }
 
+      [hidden] {
+        display: none !important;
+      }
+
       input[type="range"] {
         width: 220px;
       }
@@ -140,6 +173,24 @@
         color: #0f172a;
       }
 
+      .muted {
+        font-size: 12px;
+        color: #64748b;
+      }
+
+      .error-box {
+        margin-top: 10px;
+        border-radius: 16px;
+        background: #fef2f2;
+        color: #b91c1c;
+        padding: 12px;
+        white-space: pre-wrap;
+      }
+
+      details {
+        margin-top: 16px;
+      }
+
       @media (max-width: 960px) {
         .hero,
         .panel-grid {
@@ -160,6 +211,36 @@ <h1>shape-text demo</h1>
           <p>Preview the current library in a real browser UI. Switch between polygon flow and glyph-mask flow, edit text, tweak text style and shape decoration, then render again.</p>
           <textarea id="text-input"></textarea>
           <div class="controls-grid">
+            <label>
+              Shape text
+              <input id="shape-text-input" type="text" value="23" />
+            </label>
+            <label>
+              Shape text mode
+              <select id="shape-text-mode-select">
+                <option value="whole-text" selected>Whole text shape</option>
+                <option value="per-character">Per-character regions</option>
+              </select>
+            </label>
+            <label>
+              Shape size mode
+              <select id="shape-size-mode-select">
+                <option value="fit-content" selected>Fit content</option>
+                <option value="fixed">Fixed box</option>
+              </select>
+            </label>
+            <label id="shape-fixed-width-field" hidden>
+              Fixed width
+              <input id="shape-fixed-width-input" type="number" min="1" step="1" value="340" />
+            </label>
+            <label id="shape-fixed-height-field" hidden>
+              Fixed height
+              <input id="shape-fixed-height-input" type="number" min="1" step="1" value="460" />
+            </label>
+            <label>
+              Fill preset
+              <select id="fill-preset-select"></select>
+            </label>
             <label>
               Line height
               <input id="line-height-input" type="range" min="18" max="34" step="1" value="22" />
@@ -218,21 +299,42 @@ <h1>shape-text demo</h1>
             </label>
             <button id="render-button" class="primary-button" type="button">Render</button>
           </div>
+          <details open>
+            <summary>Payload editor</summary>
+            <p class="muted">Edit the live demo payload directly. Use Apply to re-parse and render. Invalid JSON should keep the previous SVG.</p>
+            <textarea id="payload-input" class="payload-textarea"></textarea>
+            <div class="control-row">
+              <button id="apply-payload-button" class="primary-button" type="button">Apply payload</button>
+              <button id="reset-payload-button" type="button">Reset draft</button>
+            </div>
+            <pre id="payload-error" class="error-box" hidden></pre>
+          </details>
         </div>
         <div class="card">
           <p>Scenarios</p>
           <div class="toolbar">
-            <button data-scenario="glyph-two-repeat">Glyph 2 Repeat</button>
+            <button data-scenario="glyph-two-repeat">Glyph 23 Repeat</button>
             <button data-scenario="digit-two-wide">Digit 2 Wide</button>
             <button data-scenario="digit-two-narrow">Digit 2 Narrow</button>
             <button data-scenario="rectangle-wide">Rectangle Wide</button>
             <button data-scenario="rectangle-narrow">Rectangle Narrow</button>
           </div>
-          <p>Use the shape buttons to compare flow behavior. The glyph scenario uses a real text mask and can repeat by words, dense grapheme flow, or max fill with extra slot coverage while still keeping spaces in the text stream.</p>
+          <p>Use the shape buttons to compare flow behavior. The glyph scenario now defaults to fit-content sizing so multi-character text masks such as 23 render fully before repeat-fill kicks in.</p>
         </div>
       </section>
       <div class="panel-grid">
-        <section id="stage"></section>
+        <section class="card stage-card">
+          <div class="stage-toolbar">
+            <button id="zoom-out-button" type="button">Zoom out</button>
+            <button id="zoom-in-button" type="button">Zoom in</button>
+            <button id="zoom-reset-button" type="button">100%</button>
+            <button id="zoom-fit-button" type="button">Fit</button>
+            <span>Zoom: <span id="zoom-value" class="metric">100%</span></span>
+          </div>
+          <div id="stage-viewport">
+            <div id="stage"></div>
+          </div>
+        </section>
         <pre id="summary"></pre>
       </div>
     </main>
diff --git a/e2e/fixtures/shape-text-e2e-app.js b/e2e/fixtures/shape-text-e2e-app.js
index 4473dac..7fc4f45 100644
--- a/e2e/fixtures/shape-text-e2e-app.js
+++ b/e2e/fixtures/shape-text-e2e-app.js
@@ -1,245 +1,97 @@
-import {
-  compileShapeForLayout,
-  createCanvasTextMeasurer,
-  layoutTextInShape,
-  renderLayoutToSvg,
-} from '/dist/index.js'
-
-const stage = document.querySelector('#stage')
-const summary = document.querySelector('#summary')
-const textInput = document.querySelector('#text-input')
-const lineHeightInput = document.querySelector('#line-height-input')
-const lineHeightValue = document.querySelector('#line-height-value')
-const textSizeInput = document.querySelector('#text-size-input')
-const textSizeValue = document.querySelector('#text-size-value')
-const textWeightSelect = document.querySelector('#text-weight-select')
-const textItalicInput = document.querySelector('#text-italic-input')
-const textColorInput = document.querySelector('#text-color-input')
-const autoFillModeSelect = document.querySelector('#auto-fill-mode-select')
-const shapeFillInput = document.querySelector('#shape-fill-input')
-const shapeBorderWidthInput = document.querySelector('#shape-border-width-input')
-const shapeBorderWidthValue = document.querySelector('#shape-border-width-value')
-const shapeBorderColorInput = document.querySelector('#shape-border-color-input')
-const shapeShadowInput = document.querySelector('#shape-shadow-input')
-const showShapeInput = document.querySelector('#show-shape-input')
-const renderButton = document.querySelector('#render-button')
-const measurer = createCanvasTextMeasurer()
-
-const defaultParagraph = [
-  'Shape text lets a paragraph travel inside a silhouette thay vi chi wrap quanh float.',
-  'Ban co the dung no de render layout hinh so 2, badge, logo block, hoac poster typography.',
-  'E2E local o day uu tien deterministic browser path: build dist, import module, render SVG, assert lai state.',
-].join(' ')
-
-function createDigitTwoPolygon(width, height) {
-  return [
-    { x: width * 0.12, y: height * 0.1 },
-    { x: width * 0.34, y: 0 },
-    { x: width * 0.72, y: height * 0.02 },
-    { x: width * 0.9, y: height * 0.16 },
-    { x: width * 0.88, y: height * 0.32 },
-    { x: width * 0.74, y: height * 0.44 },
-    { x: width * 0.5, y: height * 0.57 },
-    { x: width * 0.26, y: height * 0.72 },
-    { x: width * 0.14, y: height * 0.86 },
-    { x: width * 0.88, y: height * 0.86 },
-    { x: width * 0.86, y: height },
-    { x: 0, y: height },
-    { x: 0, y: height * 0.78 },
-    { x: width * 0.12, y: height * 0.64 },
-    { x: width * 0.35, y: height * 0.5 },
-    { x: width * 0.62, y: height * 0.35 },
-    { x: width * 0.74, y: height * 0.26 },
-    { x: width * 0.72, y: height * 0.14 },
-    { x: width * 0.58, y: height * 0.08 },
-    { x: width * 0.34, y: height * 0.08 },
-  ]
-}
-
-const scenarios = {
-  'glyph-two-repeat': {
-    shape: {
-      kind: 'text-mask',
-      text: '2',
-      font: '700 420px Arial',
-      width: 340,
-      height: 460,
-      padding: 10,
-      maskScale: 2,
-    },
-    autoFill: true,
-    text: 'ONE',
-  },
-  'digit-two-wide': {
-    shape: { kind: 'polygon', points: createDigitTwoPolygon(340, 460) },
-    text: defaultParagraph,
-  },
-  'digit-two-narrow': {
-    shape: { kind: 'polygon', points: createDigitTwoPolygon(240, 460) },
-    text: defaultParagraph,
-  },
-  'rectangle-wide': {
-    shape: {
-      kind: 'polygon',
-      points: [
-        { x: 0, y: 0 },
-        { x: 340, y: 0 },
-        { x: 340, y: 360 },
-        { x: 0, y: 360 },
-      ],
-    },
-    text: defaultParagraph,
-  },
-  'rectangle-narrow': {
-    shape: {
-      kind: 'polygon',
-      points: [
-        { x: 0, y: 0 },
-        { x: 220, y: 0 },
-        { x: 220, y: 360 },
-        { x: 0, y: 360 },
-      ],
-    },
-    text: defaultParagraph,
-  },
+import { compileShapeForLayout, createCanvasTextMeasurer } from '/dist/index.js'
+import { createDemoSvgViewportController } from './demo-svg-viewport-controller.js'
+import { createDemoUiController } from './demo-ui-controller.js'
+import { demoScenarios } from './demo-scenarios.js'
+
+const $ = selector => document.querySelector(selector)
+const elements = {
+  stage: $('#stage'),
+  summary: $('#summary'),
+  stageViewport: $('#stage-viewport'),
+  textInput: $('#text-input'),
+  shapeTextInput: $('#shape-text-input'),
+  shapeTextModeSelect: $('#shape-text-mode-select'),
+  shapeSizeModeSelect: $('#shape-size-mode-select'),
+  shapeFixedWidthField: $('#shape-fixed-width-field'),
+  shapeFixedWidthInput: $('#shape-fixed-width-input'),
+  shapeFixedHeightField: $('#shape-fixed-height-field'),
+  shapeFixedHeightInput: $('#shape-fixed-height-input'),
+  fillPresetSelect: $('#fill-preset-select'),
+  payloadInput: $('#payload-input'),
+  payloadError: $('#payload-error'),
+  lineHeightInput: $('#line-height-input'),
+  lineHeightValue: $('#line-height-value'),
+  textSizeInput: $('#text-size-input'),
+  textSizeValue: $('#text-size-value'),
+  textWeightSelect: $('#text-weight-select'),
+  textItalicInput: $('#text-italic-input'),
+  textColorInput: $('#text-color-input'),
+  autoFillModeSelect: $('#auto-fill-mode-select'),
+  shapeFillInput: $('#shape-fill-input'),
+  shapeBorderWidthInput: $('#shape-border-width-input'),
+  shapeBorderWidthValue: $('#shape-border-width-value'),
+  shapeBorderColorInput: $('#shape-border-color-input'),
+  shapeShadowInput: $('#shape-shadow-input'),
+  showShapeInput: $('#show-shape-input'),
+  zoomOutButton: $('#zoom-out-button'),
+  zoomInButton: $('#zoom-in-button'),
+  zoomResetButton: $('#zoom-reset-button'),
+  zoomFitButton: $('#zoom-fit-button'),
+  zoomValue: $('#zoom-value'),
 }
-
 const state = {
-  scenario: '',
+  scenario: 'glyph-two-repeat',
   layout: null,
   svg: '',
+  payloadDraft: '',
+  payloadError: '',
   text: 'ONE',
+  fillPresetId: 'custom',
   lineHeight: 22,
   textSize: 18,
   textWeight: 700,
   textItalic: false,
   textColor: '#111827',
+  autoFill: true,
   autoFillMode: 'words',
   fillStrategy: 'flow',
+  minSlotWidth: undefined,
+  background: '#fffdf7',
+  renderPadding: 12,
   showShape: true,
   shapeFill: '#dbeafe',
   shapeBorderWidth: 2,
   shapeBorderColor: '#94a3b8',
   shapeShadow: true,
+  shapeKind: 'text-mask',
+  shapeText: '23',
+  shapeTextMode: 'whole-text',
+  shapeSizeMode: 'fit-content',
+  shapeFont: '700 420px Arial',
+  shapeWidth: 340,
+  shapeHeight: 460,
+  shapePadding: 10,
+  shapeMaskScale: 2,
+  shapeAlphaThreshold: undefined,
+  polygonPoints: [],
+  stageZoom: 1,
+  stageSvgWidth: 0,
+  stageSvgHeight: 0,
 }
-let hasUserEditedText = false
-
-function getFillSelectValue() {
-  return state.fillStrategy === 'max' ? 'max' : state.autoFillMode
-}
-
-function applyFillSelection(value) {
-  if (value === 'max') {
-    state.autoFillMode = 'stream'
-    state.fillStrategy = 'max'
-    return
-  }
-
-  state.autoFillMode = value
-  state.fillStrategy = 'flow'
-}
-
-function getTextStyle() {
-  return {
-    family: '"Helvetica Neue", Arial, sans-serif',
-    size: state.textSize,
-    weight: state.textWeight,
-    style: state.textItalic ? 'italic' : 'normal',
-    color: state.textColor,
-  }
-}
-
-function getShapeStyle() {
-  return {
-    backgroundColor: state.shapeFill,
-    borderColor: state.shapeBorderColor,
-    borderWidth: state.shapeBorderWidth,
-    shadow: state.shapeShadow
-      ? {
-          color: 'rgba(15, 23, 42, 0.22)',
-          blur: 6,
-          offsetX: 0,
-          offsetY: 6,
-        }
-      : undefined,
-  }
-}
-
-function resolveScenarioText(name) {
-  const scenario = scenarios[name]
-  if (!scenario) throw new Error(`Unknown scenario: ${name}`)
-
-  if (!hasUserEditedText && scenario.text !== undefined) {
-    state.text = scenario.text
-  }
-
-  return scenario
-}
-
-function renderScenario(name) {
-  const scenario = resolveScenarioText(name)
-
-  const layout = layoutTextInShape({
-    text: state.text,
-    textStyle: getTextStyle(),
-    lineHeight: state.lineHeight,
-    shape: scenario.shape,
-    measurer,
-    minSlotWidth: state.fillStrategy === 'max' ? 8 : 24,
-    autoFill: scenario.autoFill,
-    autoFillMode: state.autoFillMode,
-    fillStrategy: state.fillStrategy,
-  })
-
-  const svg = renderLayoutToSvg(layout, {
-    background: '#fffdf7',
-    shapeStyle: getShapeStyle(),
-    showShape: state.showShape,
-    padding: 12,
-  })
-
-  state.scenario = name
-  state.layout = layout
-  state.svg = svg
-  textInput.value = state.text
-  stage.innerHTML = svg
-  summary.textContent = JSON.stringify(
-    {
-      scenario: name,
-      shapeKind: scenario.shape.kind,
-      autoFill: Boolean(scenario.autoFill),
-      autoFillMode: layout.autoFillMode,
-      fillStrategy: layout.fillStrategy,
-      lineHeight: state.lineHeight,
-      textStyle: getTextStyle(),
-      shapeStyle: getShapeStyle(),
-      lineCount: layout.lines.length,
-      exhausted: layout.exhausted,
-      firstLine: layout.lines[0]?.text ?? null,
-      lastLine: layout.lines.at(-1)?.text ?? null,
-    },
-    null,
-    2,
-  )
-}
+const measurer = createCanvasTextMeasurer()
+const viewport = createDemoSvgViewportController({ state, elements })
+const controller = createDemoUiController({ state, elements, measurer, viewport })
 
 window.shapeTextTestApi = {
-  renderScenario,
+  renderScenario(name) {
+    controller.applyScenario(name)
+    controller.renderCurrentState()
+  },
   compileScenarioTwice(name) {
-    const scenario = scenarios[name]
+    const scenario = demoScenarios[name]
     if (!scenario) throw new Error(`Unknown scenario: ${name}`)
-
-    const first = compileShapeForLayout({
-      shape: scenario.shape,
-      lineHeight: state.lineHeight,
-      minSlotWidth: 24,
-    })
-    const second = compileShapeForLayout({
-      shape: scenario.shape,
-      lineHeight: state.lineHeight,
-      minSlotWidth: 24,
-    })
-
+    const first = compileShapeForLayout({ shape: scenario.shape, lineHeight: state.lineHeight, minSlotWidth: 24 })
+    const second = compileShapeForLayout({ shape: scenario.shape, lineHeight: state.lineHeight, minSlotWidth: 24 })
     return {
       sameReference: first === second,
       isFrozen: Object.isFrozen(first) && Object.isFrozen(first.bands),
@@ -252,16 +104,18 @@ window.shapeTextTestApi = {
       compileShapeForLayout({
         shape: {
           kind: 'text-mask',
-          text: '2',
+          text: '23',
           font: '700 420px Arial',
-          width: 340,
-          height: 460,
+          size: {
+            mode: 'fixed',
+            width: 340,
+            height: 460,
+          },
           alphaThreshold: 999,
         },
         lineHeight: state.lineHeight,
         minSlotWidth: 24,
       })
-
       return null
     } catch (error) {
       return error instanceof Error ? error.message : String(error)
@@ -272,65 +126,52 @@ window.shapeTextTestApi = {
   },
 }
 
-function syncControls() {
-  textInput.value = state.text
-  lineHeightInput.value = String(state.lineHeight)
-  lineHeightValue.textContent = String(state.lineHeight)
-  textSizeInput.value = String(state.textSize)
-  textSizeValue.textContent = String(state.textSize)
-  textWeightSelect.value = String(state.textWeight)
-  textItalicInput.checked = state.textItalic
-  textColorInput.value = state.textColor
-  autoFillModeSelect.value = getFillSelectValue()
-  showShapeInput.checked = state.showShape
-  shapeFillInput.value = state.shapeFill
-  shapeBorderWidthInput.value = String(state.shapeBorderWidth)
-  shapeBorderWidthValue.textContent = String(state.shapeBorderWidth)
-  shapeBorderColorInput.value = state.shapeBorderColor
-  shapeShadowInput.checked = state.shapeShadow
-}
-
-renderButton.addEventListener('click', () => {
-  state.text = textInput.value
-  state.lineHeight = Number(lineHeightInput.value)
-  state.textSize = Number(textSizeInput.value)
-  state.textWeight = Number(textWeightSelect.value)
-  state.textItalic = textItalicInput.checked
-  state.textColor = textColorInput.value
-  applyFillSelection(autoFillModeSelect.value)
-  state.showShape = showShapeInput.checked
-  state.shapeFill = shapeFillInput.value
-  state.shapeBorderWidth = Number(shapeBorderWidthInput.value)
-  state.shapeBorderColor = shapeBorderColorInput.value
-  state.shapeShadow = shapeShadowInput.checked
-  lineHeightValue.textContent = String(state.lineHeight)
-  textSizeValue.textContent = String(state.textSize)
-  shapeBorderWidthValue.textContent = String(state.shapeBorderWidth)
-  renderScenario(state.scenario || 'digit-two-wide')
-})
-
-textInput.addEventListener('input', () => {
-  state.text = textInput.value
-  hasUserEditedText = true
-})
-
-lineHeightInput.addEventListener('input', () => {
-  lineHeightValue.textContent = lineHeightInput.value
-})
-
-textSizeInput.addEventListener('input', () => {
-  textSizeValue.textContent = textSizeInput.value
-})
-
-shapeBorderWidthInput.addEventListener('input', () => {
-  shapeBorderWidthValue.textContent = shapeBorderWidthInput.value
+controller.populateFillPresetOptions()
+elements.textInput.addEventListener('input', () => controller.handleTextEdited(elements.textInput.value))
+elements.shapeTextInput.addEventListener('input', () => controller.handleShapeTextEdited(elements.shapeTextInput.value))
+elements.shapeTextModeSelect.addEventListener('change', () =>
+  controller.handleShapeTextModeSelected(elements.shapeTextModeSelect.value),
+)
+elements.shapeSizeModeSelect.addEventListener('change', () =>
+  controller.handleShapeSizeModeSelected(elements.shapeSizeModeSelect.value),
+)
+elements.fillPresetSelect.addEventListener('change', () => controller.handlePresetSelected(elements.fillPresetSelect.value))
+elements.payloadInput.addEventListener('input', () => controller.handlePayloadDraftEdited(elements.payloadInput.value))
+elements.lineHeightInput.addEventListener('input', () => { state.lineHeight = Number(elements.lineHeightInput.value); controller.syncControls(); controller.syncPayloadInput() })
+elements.textSizeInput.addEventListener('input', () => { state.textSize = Number(elements.textSizeInput.value); controller.syncControls(); controller.syncPayloadInput() })
+elements.textWeightSelect.addEventListener('change', () => { state.textWeight = Number(elements.textWeightSelect.value); controller.syncPayloadInput() })
+elements.textItalicInput.addEventListener('change', () => { state.textItalic = elements.textItalicInput.checked; controller.syncPayloadInput() })
+elements.textColorInput.addEventListener('input', () => { state.textColor = elements.textColorInput.value; controller.syncPayloadInput() })
+elements.autoFillModeSelect.addEventListener('change', () => { controller.applyFillSelection(elements.autoFillModeSelect.value); controller.syncPayloadInput() })
+elements.shapeFillInput.addEventListener('input', () => { state.shapeFill = elements.shapeFillInput.value; controller.syncPayloadInput() })
+elements.shapeBorderWidthInput.addEventListener('input', () => { state.shapeBorderWidth = Number(elements.shapeBorderWidthInput.value); controller.syncControls(); controller.syncPayloadInput() })
+elements.shapeBorderColorInput.addEventListener('input', () => { state.shapeBorderColor = elements.shapeBorderColorInput.value; controller.syncPayloadInput() })
+elements.shapeShadowInput.addEventListener('change', () => { state.shapeShadow = elements.shapeShadowInput.checked; controller.syncPayloadInput() })
+elements.showShapeInput.addEventListener('change', () => { state.showShape = elements.showShapeInput.checked; controller.syncPayloadInput() })
+elements.shapeFixedWidthInput.addEventListener('input', () => { state.shapeWidth = Number(elements.shapeFixedWidthInput.value); controller.syncPayloadInput() })
+elements.shapeFixedHeightInput.addEventListener('input', () => { state.shapeHeight = Number(elements.shapeFixedHeightInput.value); controller.syncPayloadInput() })
+elements.zoomOutButton.addEventListener('click', () => viewport.zoomOut())
+elements.zoomInButton.addEventListener('click', () => viewport.zoomIn())
+elements.zoomResetButton.addEventListener('click', () => viewport.resetZoom())
+elements.zoomFitButton.addEventListener('click', () => viewport.fitZoom())
+$('#render-button').addEventListener('click', () => controller.renderCurrentState())
+$('#apply-payload-button').addEventListener('click', () => {
+  try {
+    controller.applyPayloadText()
+  } catch (error) {
+    controller.setPayloadError(error instanceof Error ? error.message : String(error))
+  }
 })
-
+$('#reset-payload-button').addEventListener('click', () => controller.resetPayloadDraft())
 document.querySelectorAll('[data-scenario]').forEach(button => {
   button.addEventListener('click', () => {
-    renderScenario(button.getAttribute('data-scenario'))
+    controller.applyScenario(button.getAttribute('data-scenario'))
+    controller.renderCurrentState()
   })
 })
 
-syncControls()
-renderScenario('glyph-two-repeat')
+controller.applyScenario('glyph-two-repeat')
+controller.syncControls()
+controller.syncPayloadInput(true)
+viewport.syncZoomLabel()
+controller.renderCurrentState()
diff --git a/e2e/shape-text-local-e2e.spec.ts b/e2e/shape-text-local-e2e.spec.ts
index 38747a4..f4ef701 100644
--- a/e2e/shape-text-local-e2e.spec.ts
+++ b/e2e/shape-text-local-e2e.spec.ts
@@ -18,6 +18,15 @@ declare global {
           autoFillMode: 'words' | 'dense' | 'stream'
           fillStrategy: 'flow' | 'max'
           exhausted: boolean
+          compiledShape?: {
+            bounds: {
+              left: number
+              top: number
+              right: number
+              bottom: number
+            }
+            regions?: Array<{ grapheme: string }>
+          }
           lines: Array<{
             text: string
             x: number
@@ -28,17 +37,27 @@ declare global {
           }>
         }
         text: string
+        fillPresetId: string
         textSize: number
         textWeight: number
         textItalic: boolean
         textColor: string
         autoFillMode: 'words' | 'dense' | 'stream'
         fillStrategy: 'flow' | 'max'
+        shapeKind: 'polygon' | 'text-mask'
+        shapeText: string
+        shapeTextMode: 'whole-text' | 'per-character'
+        shapeSizeMode: 'fit-content' | 'fixed'
         showShape: boolean
         shapeFill: string
         shapeBorderWidth: number
         shapeBorderColor: string
         shapeShadow: boolean
+        stageZoom: number
+        stageSvgWidth: number
+        stageSvgHeight: number
+        payloadDraft: string
+        payloadError: string
         svg: string
       }
     }
@@ -79,6 +98,8 @@ test('renders the glyph text-mask fixture into SVG', async ({ page }) => {
   expect(state.layout.fillStrategy).toBe('flow')
   expect(state.layout.exhausted).toBe(false)
   expect(state.layout.lines[0]?.text).toContain('ONE')
+  expect(state.shapeText).toBe('23')
+  expect(state.shapeSizeMode).toBe('fit-content')
   expect(state.textSize).toBe(18)
   const expectedTextNodeCount =
     state.showShape && state.scenario === 'glyph-two-repeat'
@@ -136,6 +157,292 @@ test('applies text and shape style controls to the rendered SVG', async ({ page
   expect(state.svg).toContain('shape-text-shape-shadow')
 })
 
+test('lets the demo edit glyph shape text directly', async ({ page }) => {
+  await page.goto('/')
+
+  await page.locator('#shape-text-input').fill('8')
+  await page.locator('#render-button').click()
+
+  const state = await getState(page)
+
+  await expect(page.locator('#shape-text-input')).toHaveValue('8')
+  expect(state.shapeKind).toBe('text-mask')
+  expect(state.shapeText).toBe('8')
+  expect(state.svg).toContain('>8<')
+})
+
+test('restores the last good state when direct render controls produce an invalid shape', async ({
+  page,
+}) => {
+  await page.goto('/')
+
+  const before = await getState(page)
+  await page.locator('#shape-text-input').fill('')
+  await page.locator('#render-button').click()
+
+  const after = await getState(page)
+
+  await expect(page.locator('#shape-text-input')).toHaveValue(before.shapeText)
+  expect(after.shapeText).toBe(before.shapeText)
+  expect(after.svg).toBe(before.svg)
+  expect(after.payloadError.length).toBeGreaterThan(0)
+})
+
+test('keeps wide output inspectable inside the zoomable stage viewport', async ({ page }) => {
+  await page.goto('/')
+
+  const initialState = await getState(page)
+  const initialWidth =
+    (initialState.layout.compiledShape?.bounds.right ?? 0) -
+    (initialState.layout.compiledShape?.bounds.left ?? 0)
+  const payload = JSON.parse(await page.locator('#payload-input').inputValue())
+  payload.layout.shape.text = '20252025'
+  payload.layout.shape.shapeTextMode = 'whole-text'
+
+  await page.locator('#payload-input').fill(JSON.stringify(payload, null, 2))
+  await page.locator('#apply-payload-button').click()
+
+  const beforeZoom = await getState(page)
+  const widenedShapeWidth =
+    (beforeZoom.layout.compiledShape?.bounds.right ?? 0) -
+    (beforeZoom.layout.compiledShape?.bounds.left ?? 0)
+  const viewportMetrics = await page.locator('#stage-viewport').evaluate(element => ({
+    clientWidth: element.clientWidth,
+    scrollWidth: element.scrollWidth,
+  }))
+
+  await page.locator('#zoom-in-button').click()
+  const zoomedIn = await getState(page)
+  await page.locator('#zoom-out-button').click()
+  const zoomedOut = await getState(page)
+  await page.locator('#zoom-fit-button').click()
+  const fitState = await getState(page)
+  const fitViewportMetrics = await page.locator('#stage-viewport').evaluate(element => ({
+    clientWidth: element.clientWidth,
+    scrollWidth: element.scrollWidth,
+  }))
+  await page.locator('#zoom-reset-button').click()
+  const resetState = await getState(page)
+
+  expect(widenedShapeWidth).toBeGreaterThan(initialWidth)
+  expect(viewportMetrics.scrollWidth).toBeGreaterThan(viewportMetrics.clientWidth)
+  expect(zoomedIn.stageZoom).toBeGreaterThan(beforeZoom.stageZoom)
+  expect(zoomedOut.stageZoom).toBeLessThan(zoomedIn.stageZoom)
+  expect(fitState.stageZoom).toBeGreaterThan(0)
+  expect(fitViewportMetrics.scrollWidth).toBeLessThanOrEqual(fitViewportMetrics.clientWidth + 12)
+  expect(resetState.stageZoom).toBe(1)
+  await expect(page.locator('#stage svg')).toBeVisible()
+})
+
+test('applies payload editor changes to the live demo state', async ({ page }) => {
+  await page.goto('/')
+
+  const payload = JSON.parse(await page.locator('#payload-input').inputValue())
+  payload.layout.text = 'DATA'
+  payload.layout.textStyle.size = 30
+  payload.layout.shape.text = '8'
+
+  await page.locator('#payload-input').fill(JSON.stringify(payload, null, 2))
+  await page.locator('#apply-payload-button').click()
+
+  const state = await getState(page)
+
+  expect(state.text).toBe('DATA')
+  expect(state.textSize).toBe(30)
+  expect(state.shapeText).toBe('8')
+  expect(state.payloadError).toBe('')
+  expect(state.svg).toContain('font:normal 700 30px')
+  expect(state.svg).toContain('>8<')
+})
+
+test('switches text-mask sizing between fit-content and fixed', async ({ page }) => {
+  await page.goto('/')
+
+  await expect(page.locator('#shape-fixed-width-field')).toBeHidden()
+  await expect(page.locator('#shape-fixed-height-field')).toBeHidden()
+
+  await page.locator('#shape-size-mode-select').selectOption('fixed')
+  await expect(page.locator('#shape-fixed-width-field')).toBeVisible()
+  await expect(page.locator('#shape-fixed-height-field')).toBeVisible()
+
+  await page.locator('#shape-fixed-width-input').fill('520')
+  await page.locator('#shape-fixed-height-input').fill('260')
+  await page.locator('#render-button').click()
+
+  const fixedState = await getState(page)
+  const fixedWidth =
+    (fixedState.layout.compiledShape?.bounds.right ?? 0) -
+    (fixedState.layout.compiledShape?.bounds.left ?? 0)
+
+  expect(fixedState.shapeSizeMode).toBe('fixed')
+  expect(fixedWidth).toBe(520)
+  expect(fixedState.payloadDraft).toContain('"mode": "fixed"')
+
+  await page.locator('#shape-size-mode-select').selectOption('fit-content')
+  await page.locator('#render-button').click()
+  await expect(page.locator('#shape-fixed-width-field')).toBeHidden()
+  await expect(page.locator('#shape-fixed-height-field')).toBeHidden()
+
+  const fitState = await getState(page)
+  const fitWidth =
+    (fitState.layout.compiledShape?.bounds.right ?? 0) -
+    (fitState.layout.compiledShape?.bounds.left ?? 0)
+
+  expect(fitState.shapeSizeMode).toBe('fit-content')
+  expect(fitState.payloadDraft).toContain('"mode": "fit-content"')
+  expect(fitWidth).toBeLessThan(fixedWidth)
+})
+
+test('switches text-mask rendering between whole-text and per-character regions', async ({
+  page,
+}) => {
+  await page.goto('/')
+
+  const payload = JSON.parse(await page.locator('#payload-input').inputValue())
+  payload.layout.autoFill = false
+  payload.layout.text = 'ABCDEFGHIJ'
+  payload.layout.lineHeight = 18
+  payload.layout.minSlotWidth = 1
+  payload.layout.textStyle.size = 14
+  payload.layout.shape.text = 'AB'
+  payload.layout.shape.font = '700 260px Arial'
+  payload.layout.shape.size = {
+    mode: 'fixed',
+    width: 520,
+    height: 260,
+  }
+  payload.layout.shape.shapeTextMode = 'whole-text'
+
+  await page.locator('#payload-input').fill(JSON.stringify(payload, null, 2))
+  await page.locator('#apply-payload-button').click()
+  const wholeTextState = await getState(page)
+
+  await page.locator('#shape-text-mode-select').selectOption('per-character')
+  await page.locator('#render-button').click()
+  const perCharacterState = await getState(page)
+
+  expect(wholeTextState.shapeTextMode).toBe('whole-text')
+  expect(perCharacterState.shapeTextMode).toBe('per-character')
+  expect(perCharacterState.payloadDraft).toContain('"shapeTextMode": "per-character"')
+  expect(wholeTextState.layout.compiledShape?.regions ?? []).toHaveLength(0)
+  expect(perCharacterState.layout.compiledShape?.regions?.map(region => region.grapheme)).toEqual(['A', 'B'])
+  expect(perCharacterState.layout.lines.length).toBeGreaterThan(0)
+})
+
+test('keeps the last successful SVG when payload parsing fails', async ({ page }) => {
+  await page.goto('/')
+
+  const before = await getState(page)
+  await page.locator('#payload-input').fill('{"layout":')
+  await page.locator('#apply-payload-button').click()
+
+  const after = await getState(page)
+
+  expect(after.payloadError.length).toBeGreaterThan(0)
+  expect(after.svg).toBe(before.svg)
+  expect(after.text).toBe(before.text)
+  expect(after.shapeText).toBe(before.shapeText)
+  await expect(page.locator('#payload-error')).toBeVisible()
+})
+
+test('keeps state unchanged when payload validation fails mid-apply', async ({ page }) => {
+  await page.goto('/')
+
+  const before = await getState(page)
+  const payload = JSON.parse(await page.locator('#payload-input').inputValue())
+  payload.layout.text = 'BROKEN'
+  payload.layout.shape.text = '8'
+  payload.render.padding = 'oops'
+
+  await page.locator('#payload-input').fill(JSON.stringify(payload, null, 2))
+  await page.locator('#apply-payload-button').click()
+
+  const after = await getState(page)
+
+  expect(after.payloadError).toContain('render.padding')
+  expect(after.text).toBe(before.text)
+  expect(after.shapeText).toBe(before.shapeText)
+  expect(after.svg).toBe(before.svg)
+})
+
+test('keeps state unchanged when payload render fails after JSON parsing succeeds', async ({
+  page,
+}) => {
+  await page.goto('/')
+
+  const before = await getState(page)
+  const payload = JSON.parse(await page.locator('#payload-input').inputValue())
+  payload.layout.text = 'BROKEN-BUT-VALID'
+  payload.layout.shape.text = ''
+
+  await page.locator('#payload-input').fill(JSON.stringify(payload, null, 2))
+  await page.locator('#apply-payload-button').click()
+
+  const after = await getState(page)
+
+  expect(after.payloadError.length).toBeGreaterThan(0)
+  expect(after.text).toBe(before.text)
+  expect(after.shapeText).toBe(before.shapeText)
+  expect(after.svg).toBe(before.svg)
+})
+
+test('preserves omitted payload fields instead of resetting styling and fill mode', async ({
+  page,
+}) => {
+  await page.goto('/')
+
+  await page.locator('#text-italic-input').check()
+  await page.locator('#auto-fill-mode-select').selectOption('max')
+  await page.locator('#render-button').click()
+
+  const payload = JSON.parse(await page.locator('#payload-input').inputValue())
+  delete payload.layout.fillStrategy
+  delete payload.layout.autoFillMode
+  payload.layout.textStyle = { size: 22 }
+
+  await page.locator('#payload-input').fill(JSON.stringify(payload, null, 2))
+  await page.locator('#apply-payload-button').click()
+
+  const state = await getState(page)
+
+  expect(state.textSize).toBe(22)
+  expect(state.textItalic).toBe(true)
+  expect(state.fillStrategy).toBe('max')
+  expect(state.autoFillMode).toBe('stream')
+})
+
+test('keeps payloadDraft aligned with the visible textarea while draft edits are dirty', async ({
+  page,
+}) => {
+  await page.goto('/')
+
+  const payload = JSON.parse(await page.locator('#payload-input').inputValue())
+  payload.layout.text = 'DIRTY'
+  const dirtyDraft = JSON.stringify(payload, null, 2)
+
+  await page.locator('#payload-input').fill(dirtyDraft)
+  await setRangeValue(page, '#text-size-input', '24')
+
+  const state = await getState(page)
+
+  expect(state.payloadDraft).toBe(await page.locator('#payload-input').inputValue())
+  expect(state.payloadDraft).toBe(dirtyDraft)
+})
+
+test('syncs predefined fill presets into text input and payload draft', async ({ page }) => {
+  await page.goto('/')
+
+  await page.locator('#fill-preset-select').selectOption('binary-random')
+
+  const state = await getState(page)
+
+  await expect(page.locator('#text-input')).toHaveValue(state.text)
+  expect(state.fillPresetId).toBe('binary-random')
+  expect(state.text).toMatch(/^[01]+$/)
+  expect(state.text.length).toBeGreaterThan(100)
+  expect(state.payloadDraft).toContain(`"text": "${state.text}"`)
+})
+
 test('packs glyph autofill more tightly in dense mode', async ({ page }) => {
   await page.goto('/')
 
diff --git a/src/index.ts b/src/index.ts
index ed87596..e6d7007 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -2,6 +2,7 @@ export type {
   AutoFillMode,
   CompiledShapeBand,
   CompiledShapeBands,
+  CompiledShapeRegion,
   CompileShapeForLayoutOptions,
   FillStrategy,
   Interval,
@@ -24,6 +25,11 @@ export type {
   ShapeTextLine,
   ShapeTextPoint,
   TextMaskShape,
+  TextMaskShapeFixedSize,
+  TextMaskShapeFitContentSize,
+  TextMaskShapeSize,
+  TextMaskShapeSizeMode,
+  TextMaskShapeTextMode,
   TextStyleInput,
   TextMeasurer,
 } from './types.js'
diff --git a/src/layout/layout-flow-lines-in-compiled-shape.ts b/src/layout/layout-flow-lines-in-compiled-shape.ts
new file mode 100644
index 0000000..d19680b
--- /dev/null
+++ b/src/layout/layout-flow-lines-in-compiled-shape.ts
@@ -0,0 +1,104 @@
+import type {
+  AutoFillMode,
+  CompiledShapeBands,
+  LayoutCursor,
+  PreparedLayoutText,
+  PreparedLayoutToken,
+  ShapeTextLine,
+} from '../types.js'
+import { layoutNextLineFromPreparedText } from '../text/layout-next-line-from-prepared-text.js'
+import { layoutNextLineFromRepeatedText } from '../text/layout-next-line-from-repeated-text.js'
+import { layoutDenseFillPass } from './layout-dense-fill-pass.js'
+
+function pickWidestInterval(intervals: CompiledShapeBands['bands'][number]['intervals']) {
+  let best = intervals[0]!
+
+  for (let index = 1; index < intervals.length; index++) {
+    const candidate = intervals[index]!
+    if (candidate.right - candidate.left > best.right - best.left) {
+      best = candidate
+    }
+  }
+
+  return best
+}
+
+type LayoutFlowLinesInCompiledShapeOptions = {
+  compiledShape: CompiledShapeBands
+  prepared?: PreparedLayoutText
+  densePattern?: PreparedLayoutToken
+  autoFill: boolean
+  autoFillMode: AutoFillMode
+  align: 'left' | 'center'
+  baselineRatio: number
+  startCursor: LayoutCursor
+}
+
+export function layoutFlowLinesInCompiledShape(
+  options: LayoutFlowLinesInCompiledShapeOptions,
+): {
+  lines: ShapeTextLine[]
+  endCursor: LayoutCursor
+} {
+  const lines: ShapeTextLine[] = []
+  let cursor: LayoutCursor = options.startCursor
+
+  for (let index = 0; index < options.compiledShape.bands.length; index++) {
+    const band = options.compiledShape.bands[index]!
+    if (band.intervals.length === 0) {
+      continue
+    }
+
+    const slot = pickWidestInterval(band.intervals)
+    if (options.autoFill && options.autoFillMode === 'dense') {
+      const denseLine =
+        layoutDenseFillPass({
+          compiledShape: {
+            ...options.compiledShape,
+            bands: [{ ...band, intervals: [slot] }],
+          },
+          densePattern: options.densePattern!,
+          startOffset: cursor.tokenIndex,
+          align: options.align,
+          baselineRatio: options.baselineRatio,
+          allSlots: false,
+        }).lines[0] ?? null
+
+      if (denseLine === null) {
+        break
+      }
+
+      lines.push(denseLine)
+      cursor = denseLine.end
+      continue
+    }
+
+    const line = options.autoFill
+      ? layoutNextLineFromRepeatedText(options.prepared!, cursor, slot.right - slot.left)
+      : layoutNextLineFromPreparedText(options.prepared!, cursor, slot.right - slot.left)
+
+    if (line === null) {
+      break
+    }
+
+    const x =
+      options.align === 'center'
+        ? slot.left + Math.max(0, (slot.right - slot.left - line.width) / 2)
+        : slot.left
+
+    lines.push({
+      ...line,
+      x,
+      top: band.top,
+      baseline: band.top + options.compiledShape.bandHeight * options.baselineRatio,
+      slot,
+    })
+
+    cursor = line.end
+  }
+
+  return {
+    lines,
+    endCursor: cursor,
+  }
+}
diff --git a/src/layout/layout-text-in-compiled-shape.ts b/src/layout/layout-text-in-compiled-shape.ts
index 20ac17f..047bb37 100644
--- a/src/layout/layout-text-in-compiled-shape.ts
+++ b/src/layout/layout-text-in-compiled-shape.ts
@@ -1,6 +1,10 @@
 import type { AutoFillMode, FillStrategy, LayoutTextInCompiledShapeOptions, ShapeTextLayout } from '../types.js'
 import { resolveFlowLayout } from './resolve-flow-layout.js'
 import { resolveMaxFillLayout } from './resolve-max-fill-layout.js'
+import {
+  hasSequentialShapeRegions,
+  resolveSequentialShapeRegions,
+} from './resolve-sequential-shape-regions.js'
 
 export function layoutTextInCompiledShape(
   options: LayoutTextInCompiledShapeOptions,
@@ -9,6 +13,10 @@ export function layoutTextInCompiledShape(
   const autoFillMode: AutoFillMode = autoFill ? (options.autoFillMode ?? 'words') : 'words'
   const fillStrategy: FillStrategy = autoFill ? (options.fillStrategy ?? 'flow') : 'flow'
 
+  if (hasSequentialShapeRegions(options.compiledShape)) {
+    return resolveSequentialShapeRegions(options)
+  }
+
   if (fillStrategy === 'max') {
     return resolveMaxFillLayout(options)
   }
diff --git a/src/layout/layout-text-in-shape.test.ts b/src/layout/layout-text-in-shape.test.ts
index b0cb0a0..d7767cc 100644
--- a/src/layout/layout-text-in-shape.test.ts
+++ b/src/layout/layout-text-in-shape.test.ts
@@ -181,6 +181,118 @@ describe('layoutTextInShape', () => {
     ])
   })
 
+  it('fills per-character text-mask regions sequentially while preserving region order', () => {
+    const layout = layoutTextInCompiledShape({
+      text: 'ABCD',
+      font: '16px Test Sans',
+      compiledShape: {
+        kind: 'text-mask',
+        source: {
+          kind: 'text-mask',
+          text: 'A B',
+          font: '700 160px Test Sans',
+          size: {
+            mode: 'fixed',
+            width: 80,
+            height: 20,
+          },
+          shapeTextMode: 'per-character',
+        },
+        bounds: { left: 0, top: 0, right: 80, bottom: 20 },
+        bandHeight: 20,
+        minSlotWidth: 1,
+        bands: [
+          {
+            top: 0,
+            bottom: 20,
+            intervals: [
+              { left: 0, right: 20 },
+              { left: 40, right: 60 },
+            ],
+          },
+        ],
+        regions: [
+          {
+            index: 0,
+            grapheme: 'A',
+            bounds: { left: 0, top: 0, right: 80, bottom: 20 },
+            bands: [{ top: 0, bottom: 20, intervals: [{ left: 0, right: 20 }] }],
+            debugView: {
+              kind: 'text',
+              text: 'A',
+              font: '700 160px Test Sans',
+              x: 0,
+              baseline: 16,
+            },
+          },
+          {
+            index: 1,
+            grapheme: 'B',
+            bounds: { left: 0, top: 0, right: 80, bottom: 20 },
+            bands: [{ top: 0, bottom: 20, intervals: [{ left: 40, right: 60 }] }],
+            debugView: {
+              kind: 'text',
+              text: 'B',
+              font: '700 160px Test Sans',
+              x: 40,
+              baseline: 16,
+            },
+          },
+        ],
+        debugView: {
+          kind: 'text',
+          text: 'A B',
+          font: '700 160px Test Sans',
+          x: 0,
+          baseline: 16,
+        },
+      },
+      measurer: createFixedWidthTextMeasurer(),
+    })
+
+    expect(layout.lines.map(line => [line.text, line.x])).toEqual([
+      ['AB', 0],
+      ['CD', 40],
+    ])
+  })
+
+  it('falls back to whole-shape flow when per-character regions are empty', () => {
+    const layout = layoutTextInCompiledShape({
+      text: 'ABCD',
+      font: '16px Test Sans',
+      compiledShape: {
+        kind: 'text-mask',
+        source: {
+          kind: 'text-mask',
+          text: 'III',
+          font: '700 160px Test Sans',
+          size: {
+            mode: 'fixed',
+            width: 60,
+            height: 20,
+          },
+          shapeTextMode: 'per-character',
+        },
+        bounds: { left: 0, top: 0, right: 60, bottom: 20 },
+        bandHeight: 20,
+        minSlotWidth: 50,
+        bands: [{ top: 0, bottom: 20, intervals: [{ left: 0, right: 60 }] }],
+        regions: [],
+        debugView: {
+          kind: 'text',
+          text: 'III',
+          font: '700 160px Test Sans',
+          x: 0,
+          baseline: 16,
+        },
+      },
+      measurer: createFixedWidthTextMeasurer(),
+    })
+
+    expect(layout.lines.map(line => line.text)).toEqual(['ABCD'])
+    expect(layout.fillStrategy).toBe('flow')
+  })
+
   it('strips whitespace and continues dense fill across line boundaries', () => {
     const layout = layoutTextInShape({
       text: 'A B',
diff --git a/src/layout/resolve-flow-layout.ts b/src/layout/resolve-flow-layout.ts
index 5438d6c..12dd1bb 100644
--- a/src/layout/resolve-flow-layout.ts
+++ b/src/layout/resolve-flow-layout.ts
@@ -1,30 +1,8 @@
-import type {
-  AutoFillMode,
-  Interval,
-  LayoutCursor,
-  LayoutTextInCompiledShapeOptions,
-  ShapeTextLayout,
-  ShapeTextLine,
-} from '../types.js'
-import { layoutNextLineFromPreparedText } from '../text/layout-next-line-from-prepared-text.js'
-import { layoutNextLineFromRepeatedText } from '../text/layout-next-line-from-repeated-text.js'
+import type { AutoFillMode, LayoutTextInCompiledShapeOptions, ShapeTextLayout } from '../types.js'
 import { resolveLayoutTextStyle } from '../text/normalize-text-style-to-font.js'
 import { prepareDenseRepeatFillPattern } from '../text/prepare-dense-repeat-fill-pattern.js'
 import { prepareTextForLayout } from '../text/prepare-text-for-layout.js'
-import { layoutDenseFillPass } from './layout-dense-fill-pass.js'
-
-function pickWidestInterval(intervals: Interval[]): Interval {
-  let best = intervals[0]!
-
-  for (let index = 1; index < intervals.length; index++) {
-    const candidate = intervals[index]!
-    if (candidate.right - candidate.left > best.right - best.left) {
-      best = candidate
-    }
-  }
-
-  return best
-}
+import { layoutFlowLinesInCompiledShape } from './layout-flow-lines-in-compiled-shape.js'
 
 export function resolveFlowLayout(
   options: LayoutTextInCompiledShapeOptions,
@@ -45,62 +23,16 @@ export function resolveFlowLayout(
     autoFillMode === 'dense'
       ? prepareDenseRepeatFillPattern(options.text, resolvedTextStyle.font, options.measurer)
       : undefined
-  const lines: ShapeTextLine[] = []
-  let cursor: LayoutCursor = { tokenIndex: 0, graphemeIndex: 0 }
-
-  for (let index = 0; index < options.compiledShape.bands.length; index++) {
-    const band = options.compiledShape.bands[index]!
-    if (band.intervals.length === 0) {
-      continue
-    }
-
-    const slot = pickWidestInterval(band.intervals)
-    if (autoFill && autoFillMode === 'dense') {
-      const denseLine =
-        layoutDenseFillPass({
-          compiledShape: {
-            ...options.compiledShape,
-            bands: [{ ...band, intervals: [slot] }],
-          },
-          densePattern: densePattern!,
-          startOffset: cursor.tokenIndex,
-          align,
-          baselineRatio,
-          allSlots: false,
-        }).lines[0] ?? null
-
-      if (denseLine === null) {
-        break
-      }
-
-      lines.push(denseLine)
-      cursor = denseLine.end
-      continue
-    }
-
-    const line = autoFill
-      ? layoutNextLineFromRepeatedText(prepared!, cursor, slot.right - slot.left)
-      : layoutNextLineFromPreparedText(prepared!, cursor, slot.right - slot.left)
-
-    if (line === null) {
-      break
-    }
-
-    const x =
-      align === 'center'
-        ? slot.left + Math.max(0, (slot.right - slot.left - line.width) / 2)
-        : slot.left
-
-    lines.push({
-      ...line,
-      x,
-      top: band.top,
-      baseline: band.top + options.compiledShape.bandHeight * baselineRatio,
-      slot,
-    })
-
-    cursor = line.end
-  }
+  const { lines, endCursor } = layoutFlowLinesInCompiledShape({
+    compiledShape: options.compiledShape,
+    prepared,
+    densePattern,
+    autoFill,
+    autoFillMode,
+    align,
+    baselineRatio,
+    startCursor: { tokenIndex: 0, graphemeIndex: 0 },
+  })
 
   return {
     font: resolvedTextStyle.font,
@@ -114,7 +46,7 @@ export function resolveFlowLayout(
       ? autoFillMode === 'dense'
         ? false
         : prepared!.tokens.length === 0
-      : cursor.tokenIndex >= prepared!.tokens.length,
+      : endCursor.tokenIndex >= prepared!.tokens.length,
     autoFill,
     autoFillMode,
     fillStrategy: 'flow',
diff --git a/src/layout/resolve-max-fill-helpers.ts b/src/layout/resolve-max-fill-helpers.ts
new file mode 100644
index 0000000..91212f9
--- /dev/null
+++ b/src/layout/resolve-max-fill-helpers.ts
@@ -0,0 +1,22 @@
+import type { CompiledShapeBands } from '../types.js'
+import { compileShapeForLayout } from '../shape/compile-shape-for-layout.js'
+
+const MAX_FILL_BASE_MIN_SLOT_WIDTH_FACTOR = 0.45
+const MIN_MAX_FILL_SLOT_WIDTH = 6
+
+export function resolveMaxFillMinSlotWidth(lineHeight: number): number {
+  return Math.max(MIN_MAX_FILL_SLOT_WIDTH, Math.round(lineHeight * MAX_FILL_BASE_MIN_SLOT_WIDTH_FACTOR))
+}
+
+export function ensureMaxFillCompiledShape(compiledShape: CompiledShapeBands): CompiledShapeBands {
+  const recommendedMinSlotWidth = resolveMaxFillMinSlotWidth(compiledShape.bandHeight)
+  if (compiledShape.minSlotWidth <= recommendedMinSlotWidth) {
+    return compiledShape
+  }
+
+  return compileShapeForLayout({
+    shape: compiledShape.source,
+    lineHeight: compiledShape.bandHeight,
+    minSlotWidth: recommendedMinSlotWidth,
+  })
+}
diff --git a/src/layout/resolve-max-fill-layout.ts b/src/layout/resolve-max-fill-layout.ts
index fa108b8..b406d40 100644
--- a/src/layout/resolve-max-fill-layout.ts
+++ b/src/layout/resolve-max-fill-layout.ts
@@ -1,31 +1,8 @@
 import type { LayoutTextInCompiledShapeOptions, ShapeTextLayout } from '../types.js'
-import { compileShapeForLayout } from '../shape/compile-shape-for-layout.js'
 import { resolveLayoutTextStyle } from '../text/normalize-text-style-to-font.js'
 import { prepareStreamRepeatFillPattern } from '../text/prepare-stream-repeat-fill-pattern.js'
 import { layoutDenseFillPass } from './layout-dense-fill-pass.js'
-
-const MAX_FILL_BASE_MIN_SLOT_WIDTH_FACTOR = 0.45
-const MIN_MAX_FILL_SLOT_WIDTH = 6
-
-function resolveMaxFillMinSlotWidth(lineHeight: number, factor: number): number {
-  return Math.max(MIN_MAX_FILL_SLOT_WIDTH, Math.round(lineHeight * factor))
-}
-
-function ensureMaxFillCompiledShape(options: LayoutTextInCompiledShapeOptions) {
-  const recommendedMinSlotWidth = resolveMaxFillMinSlotWidth(
-    options.compiledShape.bandHeight,
-    MAX_FILL_BASE_MIN_SLOT_WIDTH_FACTOR,
-  )
-  if (options.compiledShape.minSlotWidth <= recommendedMinSlotWidth) {
-    return options.compiledShape
-  }
-
-  return compileShapeForLayout({
-    shape: options.compiledShape.source,
-    lineHeight: options.compiledShape.bandHeight,
-    minSlotWidth: recommendedMinSlotWidth,
-  })
-}
+import { ensureMaxFillCompiledShape } from './resolve-max-fill-helpers.js'
 
 export function resolveMaxFillLayout(
   options: LayoutTextInCompiledShapeOptions,
@@ -35,7 +12,7 @@ export function resolveMaxFillLayout(
     textStyle: options.textStyle,
   })
   const baselineRatio = options.baselineRatio ?? 0.8
-  const maxCompiledShape = ensureMaxFillCompiledShape(options)
+  const maxCompiledShape = ensureMaxFillCompiledShape(options.compiledShape)
   const streamPattern = prepareStreamRepeatFillPattern(
     options.text,
     resolvedTextStyle.font,
diff --git a/src/layout/resolve-sequential-shape-regions.ts b/src/layout/resolve-sequential-shape-regions.ts
new file mode 100644
index 0000000..e6252d1
--- /dev/null
+++ b/src/layout/resolve-sequential-shape-regions.ts
@@ -0,0 +1,144 @@
+import type {
+  AutoFillMode,
+  CompiledShapeBands,
+  CompiledShapeRegion,
+  FillStrategy,
+  LayoutCursor,
+  LayoutTextInCompiledShapeOptions,
+  ShapeTextLayout,
+} from '../types.js'
+import { resolveLayoutTextStyle } from '../text/normalize-text-style-to-font.js'
+import { prepareDenseRepeatFillPattern } from '../text/prepare-dense-repeat-fill-pattern.js'
+import { prepareStreamRepeatFillPattern } from '../text/prepare-stream-repeat-fill-pattern.js'
+import { prepareTextForLayout } from '../text/prepare-text-for-layout.js'
+import { layoutDenseFillPass } from './layout-dense-fill-pass.js'
+import { layoutFlowLinesInCompiledShape } from './layout-flow-lines-in-compiled-shape.js'
+import { ensureMaxFillCompiledShape } from './resolve-max-fill-helpers.js'
+
+function createCompiledShapeFromRegion(
+  compiledShape: CompiledShapeBands,
+  region: CompiledShapeRegion,
+): CompiledShapeBands {
+  return {
+    kind: compiledShape.kind,
+    source: compiledShape.source,
+    bounds: region.bounds,
+    bandHeight: compiledShape.bandHeight,
+    minSlotWidth: compiledShape.minSlotWidth,
+    bands: region.bands,
+    debugView: region.debugView,
+  }
+}
+
+export function hasSequentialShapeRegions(compiledShape: CompiledShapeBands): boolean {
+  return (
+    compiledShape.source.kind === 'text-mask' &&
+    (compiledShape.source.shapeTextMode ?? 'whole-text') === 'per-character' &&
+    (compiledShape.regions?.some(region =>
+      region.bands.some(band => band.intervals.length > 0),
+    ) ?? false)
+  )
+}
+
+export function resolveSequentialShapeRegions(
+  options: LayoutTextInCompiledShapeOptions,
+): ShapeTextLayout {
+  const autoFill = options.autoFill ?? false
+  const autoFillMode: AutoFillMode = autoFill ? (options.autoFillMode ?? 'words') : 'words'
+  const fillStrategy: FillStrategy = autoFill ? (options.fillStrategy ?? 'flow') : 'flow'
+  const resolvedTextStyle = resolveLayoutTextStyle({
+    font: options.font,
+    textStyle: options.textStyle,
+  })
+  const align = options.align ?? 'left'
+  const baselineRatio = options.baselineRatio ?? 0.8
+  const compiledShape =
+    fillStrategy === 'max' ? ensureMaxFillCompiledShape(options.compiledShape) : options.compiledShape
+  const regions = compiledShape.regions ?? []
+
+  if (fillStrategy === 'max') {
+    const streamPattern = prepareStreamRepeatFillPattern(
+      options.text,
+      resolvedTextStyle.font,
+      options.measurer,
+    )
+    const lines = []
+    let offset = 0
+
+    for (let index = 0; index < regions.length; index++) {
+      const regionShape = createCompiledShapeFromRegion(compiledShape, regions[index]!)
+      const pass = layoutDenseFillPass({
+        compiledShape: regionShape,
+        densePattern: streamPattern,
+        startOffset: offset,
+        align: 'left',
+        baselineRatio,
+        allSlots: true,
+        fillPass: 1,
+      })
+
+      lines.push(...pass.lines)
+      offset = pass.endOffset
+    }
+
+    return {
+      font: resolvedTextStyle.font,
+      textStyle: resolvedTextStyle,
+      lineHeight: compiledShape.bandHeight,
+      shape: compiledShape.source,
+      compiledShape,
+      bounds: compiledShape.bounds,
+      lines,
+      exhausted: false,
+      autoFill: true,
+      autoFillMode: 'stream',
+      fillStrategy: 'max',
+    }
+  }
+
+  const prepared =
+    autoFillMode === 'dense'
+      ? undefined
+      : prepareTextForLayout(options.text, resolvedTextStyle.font, options.measurer)
+  const densePattern =
+    autoFillMode === 'dense'
+      ? prepareDenseRepeatFillPattern(options.text, resolvedTextStyle.font, options.measurer)
+      : undefined
+  const lines = []
+  let cursor: LayoutCursor = { tokenIndex: 0, graphemeIndex: 0 }
+
+  for (let index = 0; index < regions.length; index++) {
+    const regionShape = createCompiledShapeFromRegion(compiledShape, regions[index]!)
+    const result = layoutFlowLinesInCompiledShape({
+      compiledShape: regionShape,
+      prepared,
+      densePattern,
+      autoFill,
+      autoFillMode,
+      align,
+      baselineRatio,
+      startCursor: cursor,
+    })
+
+    lines.push(...result.lines)
+    cursor = result.endCursor
+
+    if (!autoFill && prepared !== undefined && cursor.tokenIndex >= prepared.tokens.length) {
+      break
+    }
+  }
+
+  return {
+    font: resolvedTextStyle.font,
+    textStyle: resolvedTextStyle,
+    lineHeight: compiledShape.bandHeight,
+    shape: compiledShape.source,
+    compiledShape,
+    bounds: compiledShape.bounds,
+    lines,
+    exhausted: autoFill ? autoFillMode === 'dense' ? false : prepared!.tokens.length === 0 : cursor.tokenIndex >= prepared!.tokens.length,
+    autoFill,
+    autoFillMode,
+    fillStrategy: 'flow',
+  }
+}
diff --git a/src/shape/build-text-mask-bands-from-alpha.ts b/src/shape/build-text-mask-bands-from-alpha.ts
new file mode 100644
index 0000000..503cf7c
--- /dev/null
+++ b/src/shape/build-text-mask-bands-from-alpha.ts
@@ -0,0 +1,106 @@
+import type { CompiledShapeBand, Interval } from '../types.js'
+
+export type TextMaskAlphaBandsOptions = {
+  width: number
+  height: number
+  maskScale: number
+  alphaThreshold: number
+}
+
+function intersectIntervalSets(leftSet: Interval[], rightSet: Interval[]): Interval[] {
+  const intersections: Interval[] = []
+  let leftIndex = 0
+  let rightIndex = 0
+
+  while (leftIndex < leftSet.length && rightIndex < rightSet.length) {
+    const left = leftSet[leftIndex]!
+    const right = rightSet[rightIndex]!
+    const overlapLeft = Math.max(left.left, right.left)
+    const overlapRight = Math.min(left.right, right.right)
+
+    if (overlapRight > overlapLeft) {
+      intersections.push({ left: overlapLeft, right: overlapRight })
+    }
+
+    if (left.right < right.right) {
+      leftIndex += 1
+    } else {
+      rightIndex += 1
+    }
+  }
+
+  return intersections
+}
+
+function getRowIntervals(
+  alpha: Uint8ClampedArray,
+  row: number,
+  width: number,
+  alphaThreshold: number,
+): Interval[] {
+  const intervals: Interval[] = []
+  let start = -1
+  const rowOffset = row * width * 4
+
+  for (let x = 0; x < width; x++) {
+    const isSolid = alpha[rowOffset + x * 4 + 3] >= alphaThreshold
+
+    if (isSolid && start < 0) {
+      start = x
+      continue
+    }
+
+    if (!isSolid && start >= 0) {
+      intervals.push({ left: start, right: x })
+      start = -1
+    }
+  }
+
+  if (start >= 0) {
+    intervals.push({ left: start, right: width })
+  }
+
+  return intervals
+}
+
+export function buildTextMaskBandsFromAlpha(
+  options: TextMaskAlphaBandsOptions,
+  alpha: Uint8ClampedArray,
+  lineHeight: number,
+  minSlotWidth: number,
+): CompiledShapeBand[] {
+  const pixelWidth = Math.max(1, Math.ceil(options.width * options.maskScale))
+  const bands: CompiledShapeBand[] = []
+
+  for (let bandTop = 0; bandTop + lineHeight <= options.height; bandTop += lineHeight) {
+    const startRow = Math.floor(bandTop * options.maskScale)
+    const endRow = Math.max(startRow, Math.ceil((bandTop + lineHeight) * options.maskScale) - 1)
+    let intervals: Interval[] | null = null
+
+    for (let row = startRow; row <= endRow; row++) {
+      const rowIntervals = getRowIntervals(alpha, row, pixelWidth, options.alphaThreshold)
+      if (rowIntervals.length === 0) {
+        intervals = []
+        break
+      }
+
+      intervals = intervals === null ? rowIntervals : intersectIntervalSets(intervals, rowIntervals)
+      if (intervals.length === 0) {
+        break
+      }
+    }
+
+    bands.push({
+      top: bandTop,
+      bottom: bandTop + lineHeight,
+      intervals: (intervals ?? [])
+        .map(interval => ({
+          left: interval.left / options.maskScale,
+          right: interval.right / options.maskScale,
+        }))
+        .filter(interval => interval.right - interval.left >= minSlotWidth),
+    })
+  }
+
+  return bands
+}
diff --git a/src/shape/compile-text-mask-shape-for-layout.test.ts b/src/shape/compile-text-mask-shape-for-layout.test.ts
index 1646193..41e6de7 100644
--- a/src/shape/compile-text-mask-shape-for-layout.test.ts
+++ b/src/shape/compile-text-mask-shape-for-layout.test.ts
@@ -2,11 +2,11 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
 
 import { compileShapeForLayout } from './compile-shape-for-layout.js'
 
-function createMaskData(width: number, height: number): Uint8ClampedArray {
+function createMaskData(width: number, height: number, left: number, right: number): Uint8ClampedArray {
   const data = new Uint8ClampedArray(width * height * 4)
 
   for (let y = 0; y < height; y++) {
-    for (let x = 10; x < width - 10; x++) {
+    for (let x = left; x < right; x++) {
       const alphaOffset = (y * width + x) * 4 + 3
       data[alphaOffset] = 255
     }
@@ -19,6 +19,8 @@ class FakeCanvasContext {
   font = ''
   fillStyle = '#000000'
   textBaseline: CanvasTextBaseline = 'alphabetic'
+  private lastDrawX = 0
+  private lastText = ''
 
   constructor(
     private readonly width: number,
@@ -27,10 +29,15 @@ class FakeCanvasContext {
 
   clearRect(): void {}
 
-  fillText(): void {}
+  fillText(text: string, x: number): void {
+    this.lastText = text
+    this.lastDrawX = x
+  }
 
   getImageData(): ImageData {
-    return { data: createMaskData(this.width, this.height) } as ImageData
+    const left = Math.max(0, Math.floor(this.lastDrawX))
+    const right = Math.min(this.width, Math.ceil(this.lastDrawX + this.lastText.length * 40))
+    return { data: createMaskData(this.width, this.height, left, right) } as ImageData
   }
 
   measureText(text: string): TextMetrics {
@@ -61,12 +68,22 @@ class FakeOffscreenCanvas {
   }
 }
 
-const baseShape = {
+const fitContentShape = {
+  kind: 'text-mask' as const,
+  text: '23',
+  font: '700 160px Test Sans',
+  maskScale: 1,
+}
+
+const fixedShape = {
   kind: 'text-mask' as const,
   text: '2',
   font: '700 160px Test Sans',
-  width: 120,
-  height: 160,
+  size: {
+    mode: 'fixed' as const,
+    width: 120,
+    height: 160,
+  },
   maskScale: 1,
 }
 
@@ -75,7 +92,7 @@ afterEach(() => {
 })
 
 describe('compileTextMaskShapeForLayout', () => {
-  it('compiles a text mask into reusable frozen bands', () => {
+  it('compiles a fixed text mask into reusable frozen bands', () => {
     vi.stubGlobal('OffscreenCanvas', FakeOffscreenCanvas)
     vi.stubGlobal('document', {
       fonts: {
@@ -84,24 +101,90 @@ describe('compileTextMaskShapeForLayout', () => {
     })
 
     const first = compileShapeForLayout({
-      shape: baseShape,
+      shape: fixedShape,
       lineHeight: 20,
       minSlotWidth: 12,
     })
     const second = compileShapeForLayout({
-      shape: baseShape,
+      shape: fixedShape,
       lineHeight: 20,
       minSlotWidth: 12,
     })
 
     expect(first.kind).toBe('text-mask')
     expect(first.bands).toHaveLength(8)
-    expect(first.bands[0]?.intervals[0]).toEqual({ left: 10, right: 110 })
+    expect(first.bands[0]?.intervals[0]).toEqual({ left: 40, right: 80 })
+    expect(first.regions).toEqual([])
     expect(first).toBe(second)
     expect(Object.isFrozen(first)).toBe(true)
     expect(Object.isFrozen(first.bands)).toBe(true)
   })
 
+  it('resolves fit-content bounds from the measured glyph text', () => {
+    vi.stubGlobal('OffscreenCanvas', FakeOffscreenCanvas)
+    vi.stubGlobal('document', {
+      fonts: {
+        check: () => true,
+      },
+    })
+
+    const compiled = compileShapeForLayout({
+      shape: fitContentShape,
+      lineHeight: 20,
+      minSlotWidth: 12,
+    })
+
+    expect(compiled.bounds).toEqual({ left: 0, top: 0, right: 80, bottom: 40 })
+    expect(compiled.bands).toHaveLength(2)
+    expect(compiled.bands[0]?.intervals[0]).toEqual({ left: 0, right: 80 })
+  })
+
+  it('compiles per-character text-mask regions and skips spaces', () => {
+    vi.stubGlobal('OffscreenCanvas', FakeOffscreenCanvas)
+    vi.stubGlobal('document', {
+      fonts: {
+        check: () => true,
+      },
+    })
+
+    const compiled = compileShapeForLayout({
+      shape: {
+        ...fitContentShape,
+        text: 'A B',
+        shapeTextMode: 'per-character',
+      },
+      lineHeight: 20,
+      minSlotWidth: 12,
+    })
+
+    expect(compiled.regions).toHaveLength(2)
+    expect(compiled.regions?.map(region => region.grapheme)).toEqual(['A', 'B'])
+    expect(compiled.regions?.[0]?.bands[0]?.intervals[0]).toEqual({ left: 0, right: 40 })
+    expect(compiled.regions?.[1]?.bands[0]?.intervals[0]).toEqual({ left: 80, right: 120 })
+  })
+
+  it('drops per-character regions that become empty after minSlotWidth filtering', () => {
+    vi.stubGlobal('OffscreenCanvas', FakeOffscreenCanvas)
+    vi.stubGlobal('document', {
+      fonts: {
+        check: () => true,
+      },
+    })
+
+    const compiled = compileShapeForLayout({
+      shape: {
+        ...fitContentShape,
+        text: 'III',
+        shapeTextMode: 'per-character',
+      },
+      lineHeight: 20,
+      minSlotWidth: 50,
+    })
+
+    expect(compiled.bands[0]?.intervals[0]).toEqual({ left: 0, right: 120 })
+    expect(compiled.regions).toHaveLength(0)
+  })
+
   it('rejects invalid alpha thresholds early', () => {
     vi.stubGlobal('OffscreenCanvas', FakeOffscreenCanvas)
     vi.stubGlobal('document', {
@@ -113,7 +196,7 @@ describe('compileTextMaskShapeForLayout', () => {
     expect(() =>
       compileShapeForLayout({
         shape: {
-          ...baseShape,
+          ...fixedShape,
           alphaThreshold: -1,
         },
         lineHeight: 20,
@@ -122,6 +205,30 @@ describe('compileTextMaskShapeForLayout', () => {
     ).toThrow('alphaThreshold')
   })
 
+  it('rejects invalid fixed sizes early', () => {
+    vi.stubGlobal('OffscreenCanvas', FakeOffscreenCanvas)
+    vi.stubGlobal('document', {
+      fonts: {
+        check: () => true,
+      },
+    })
+
+    expect(() =>
+      compileShapeForLayout({
+        shape: {
+          ...fitContentShape,
+          size: {
+            mode: 'fixed',
+            width: 0,
+            height: 160,
+          },
+        },
+        lineHeight: 20,
+        minSlotWidth: 12,
+      }),
+    ).toThrow('fixed width')
+  })
+
   it('skips cache writes until the font is ready', () => {
     vi.stubGlobal('OffscreenCanvas', FakeOffscreenCanvas)
     const check = vi.fn(() => false)
@@ -132,12 +239,12 @@ describe('compileTextMaskShapeForLayout', () => {
     })
 
     const beforeReadyA = compileShapeForLayout({
-      shape: baseShape,
+      shape: fixedShape,
       lineHeight: 20,
       minSlotWidth: 12,
     })
     const beforeReadyB = compileShapeForLayout({
-      shape: baseShape,
+      shape: fixedShape,
       lineHeight: 20,
       minSlotWidth: 12,
     })
@@ -147,12 +254,12 @@ describe('compileTextMaskShapeForLayout', () => {
     check.mockReturnValue(true)
 
     const afterReadyA = compileShapeForLayout({
-      shape: baseShape,
+      shape: fixedShape,
       lineHeight: 20,
       minSlotWidth: 12,
     })
     const afterReadyB = compileShapeForLayout({
-      shape: baseShape,
+      shape: fixedShape,
       lineHeight: 20,
       minSlotWidth: 12,
     })
diff --git a/src/shape/compile-text-mask-shape-for-layout.ts b/src/shape/compile-text-mask-shape-for-layout.ts
index 5b81325..e5e3450 100644
--- a/src/shape/compile-text-mask-shape-for-layout.ts
+++ b/src/shape/compile-text-mask-shape-for-layout.ts
@@ -1,25 +1,30 @@
-import type { CompiledShapeBand, CompiledShapeBands, Interval, TextMaskShape } from '../types.js'
+import type { CompiledShapeBands, CompiledShapeRegion, TextMaskShape } from '../types.js'
 import { createBrowserCanvas2DContext } from '../text/create-browser-canvas-2d-context.js'
-
-type TextMaskPlacement = {
-  x: number
-  baseline: number
-}
+import { buildTextMaskBandsFromAlpha } from './build-text-mask-bands-from-alpha.js'
+import {
+  getTextMaskPlacement,
+  renderTextMaskRaster,
+  type TextMaskCanvas,
+  type TextMaskPlacement,
+} from './render-text-mask-raster.js'
+import {
+  measureTextMaskContent,
+  resolveTextMaskShapeSize,
+  type ResolvedTextMaskSize,
+} from './resolve-text-mask-shape-size.js'
+import { segmentTextMaskGraphemes } from './segment-text-mask-graphemes.js'
 
 const MAX_MASK_PIXELS = 4_000_000
 const compiledShapeCache = new Map<string, CompiledShapeBands>()
 
-function validateTextMaskShape(shape: TextMaskShape): void {
+function validateTextMaskShape(shape: TextMaskShape, size: ResolvedTextMaskSize): void {
   if (shape.text.length === 0) {
     throw new Error('text-mask shape needs a non-empty text value')
   }
 
-  if (!Number.isFinite(shape.width) || shape.width <= 0) {
-    throw new Error('text-mask width must be a finite positive number')
-  }
-
-  if (!Number.isFinite(shape.height) || shape.height <= 0) {
-    throw new Error('text-mask height must be a finite positive number')
+  const shapeTextMode = shape.shapeTextMode ?? 'whole-text'
+  if (shapeTextMode !== 'whole-text' && shapeTextMode !== 'per-character') {
+    throw new Error('text-mask shapeTextMode must be whole-text or per-character')
   }
 
   const maskScale = shape.maskScale ?? 2
@@ -27,8 +32,8 @@ function validateTextMaskShape(shape: TextMaskShape): void {
     throw new Error('text-mask maskScale must be a finite positive number')
   }
 
-  const pixelWidth = Math.max(1, Math.ceil(shape.width * maskScale))
-  const pixelHeight = Math.max(1, Math.ceil(shape.height * maskScale))
+  const pixelWidth = Math.max(1, Math.ceil(size.width * maskScale))
+  const pixelHeight = Math.max(1, Math.ceil(size.height * maskScale))
   if (pixelWidth * pixelHeight > MAX_MASK_PIXELS) {
     throw new Error('text-mask raster request is too large')
   }
@@ -41,6 +46,7 @@ function validateTextMaskShape(shape: TextMaskShape): void {
 
 function buildCacheKey(
   shape: TextMaskShape,
+  size: ResolvedTextMaskSize,
   lineHeight: number,
   minSlotWidth: number,
 ): string {
@@ -48,9 +54,11 @@ function buildCacheKey(
     kind: shape.kind,
     text: shape.text,
     font: shape.font,
-    width: shape.width,
-    height: shape.height,
-    padding: shape.padding ?? 0,
+    sizeMode: size.mode,
+    width: size.width,
+    height: size.height,
+    shapeTextMode: shape.shapeTextMode ?? 'whole-text',
+    padding: size.padding,
     maskScale: shape.maskScale ?? 2,
     alphaThreshold: shape.alphaThreshold ?? 16,
     lineHeight,
@@ -58,86 +66,6 @@ function buildCacheKey(
   })
 }
 
-function intersectIntervalSets(leftSet: Interval[], rightSet: Interval[]): Interval[] {
-  const intersections: Interval[] = []
-  let leftIndex = 0
-  let rightIndex = 0
-
-  while (leftIndex < leftSet.length && rightIndex < rightSet.length) {
-    const left = leftSet[leftIndex]!
-    const right = rightSet[rightIndex]!
-    const overlapLeft = Math.max(left.left, right.left)
-    const overlapRight = Math.min(left.right, right.right)
-
-    if (overlapRight > overlapLeft) {
-      intersections.push({ left: overlapLeft, right: overlapRight })
-    }
-
-    if (left.right < right.right) {
-      leftIndex += 1
-    } else {
-      rightIndex += 1
-    }
-  }
-
-  return intersections
-}
-
-function getRowIntervals(
-  alpha: Uint8ClampedArray,
-  row: number,
-  width: number,
-  alphaThreshold: number,
-): Interval[] {
-  const intervals: Interval[] = []
-  let start = -1
-  const rowOffset = row * width * 4
-
-  for (let x = 0; x < width; x++) {
-    const isSolid = alpha[rowOffset + x * 4 + 3] >= alphaThreshold
-
-    if (isSolid && start < 0) {
-      start = x
-      continue
-    }
-
-    if (!isSolid && start >= 0) {
-      intervals.push({ left: start, right: x })
-      start = -1
-    }
-  }
-
-  if (start >= 0) {
-    intervals.push({ left: start, right: width })
-  }
-
-  return intervals
-}
-
-function getTextMaskPlacement(shape: TextMaskShape, context: CanvasText['context']): TextMaskPlacement {
-  const padding = shape.padding ?? 0
-  context.font = shape.font
-  const metrics = context.measureText(shape.text)
-  const contentWidth =
-    (metrics.actualBoundingBoxLeft ?? 0) + (metrics.actualBoundingBoxRight ?? metrics.width)
-  const contentHeight =
-    (metrics.actualBoundingBoxAscent ?? 0) + (metrics.actualBoundingBoxDescent ?? 0)
-  const innerWidth = Math.max(0, shape.width - padding * 2)
-  const innerHeight = Math.max(0, shape.height - padding * 2)
-  const left = padding + Math.max(0, (innerWidth - contentWidth) / 2)
-  const top = padding + Math.max(0, (innerHeight - contentHeight) / 2)
-
-  return {
-    x: left + (metrics.actualBoundingBoxLeft ?? 0),
-    baseline: top + (metrics.actualBoundingBoxAscent ?? 0),
-  }
-}
-
-type CanvasText = {
-  context: ReturnType<typeof createBrowserCanvas2DContext>
-  imageData: ImageData
-}
-
 function isFontReadyForShape(shape: TextMaskShape): boolean {
   if (typeof document === 'undefined' || document.fonts === undefined) {
     return true
@@ -151,87 +79,106 @@ function isFontReadyForShape(shape: TextMaskShape): boolean {
 }
 
 function freezeCompiledShape(compiledShape: CompiledShapeBands): CompiledShapeBands {
-  for (let bandIndex = 0; bandIndex < compiledShape.bands.length; bandIndex++) {
-    const band = compiledShape.bands[bandIndex]!
-    for (let intervalIndex = 0; intervalIndex < band.intervals.length; intervalIndex++) {
-      Object.freeze(band.intervals[intervalIndex]!)
-    }
-
-    Object.freeze(band.intervals)
-    Object.freeze(band)
-  }
+  freezeBands(compiledShape.bands)
+  freezeRegions(compiledShape.regions ?? [])
 
   Object.freeze(compiledShape.bounds)
   Object.freeze(compiledShape.source)
   Object.freeze(compiledShape.debugView)
   Object.freeze(compiledShape.bands)
+  if (compiledShape.regions !== undefined) {
+    Object.freeze(compiledShape.regions)
+  }
   return Object.freeze(compiledShape)
 }
 
-function renderTextMask(shape: TextMaskShape): CanvasText {
-  const maskScale = shape.maskScale ?? 2
-  const pixelWidth = Math.max(1, Math.ceil(shape.width * maskScale))
-  const pixelHeight = Math.max(1, Math.ceil(shape.height * maskScale))
-  const context = createBrowserCanvas2DContext(pixelWidth, pixelHeight)
-
-  context.setTransform(1, 0, 0, 1, 0, 0)
-  context.clearRect(0, 0, pixelWidth, pixelHeight)
-  context.setTransform(maskScale, 0, 0, maskScale, 0, 0)
-  context.font = shape.font
-  context.fillStyle = '#000000'
-  context.textBaseline = 'alphabetic'
+function freezeBands(bands: CompiledShapeBands['bands']): void {
+  for (let bandIndex = 0; bandIndex < bands.length; bandIndex++) {
+    const band = bands[bandIndex]!
+    for (let intervalIndex = 0; intervalIndex < band.intervals.length; intervalIndex++) {
+      Object.freeze(band.intervals[intervalIndex]!)
+    }
 
-  const placement = getTextMaskPlacement(shape, context)
-  context.fillText(shape.text, placement.x, placement.baseline)
+    Object.freeze(band.intervals)
+    Object.freeze(band)
+  }
+}
 
-  return {
-    context,
-    imageData: context.getImageData(0, 0, pixelWidth, pixelHeight),
+function freezeRegions(regions: CompiledShapeRegion[]): void {
+  for (let index = 0; index < regions.length; index++) {
+    const region = regions[index]!
+    freezeBands(region.bands)
+    Object.freeze(region.bounds)
+    Object.freeze(region.debugView)
+    Object.freeze(region.bands)
+    Object.freeze(region)
   }
 }
 
-function buildBands(
+function buildRegion(
   shape: TextMaskShape,
-  alpha: Uint8ClampedArray,
+  size: ResolvedTextMaskSize,
   lineHeight: number,
   minSlotWidth: number,
-): CompiledShapeBand[] {
-  const maskScale = shape.maskScale ?? 2
-  const alphaThreshold = shape.alphaThreshold ?? 16
-  const pixelWidth = Math.max(1, Math.ceil(shape.width * maskScale))
-  const bands: CompiledShapeBand[] = []
-
-  for (let bandTop = 0; bandTop + lineHeight <= shape.height; bandTop += lineHeight) {
-    const startRow = Math.floor(bandTop * maskScale)
-    const endRow = Math.max(startRow, Math.ceil((bandTop + lineHeight) * maskScale) - 1)
-    let intervals: Interval[] | null = null
-
-    for (let row = startRow; row <= endRow; row++) {
-      const rowIntervals = getRowIntervals(alpha, row, pixelWidth, alphaThreshold)
-      if (rowIntervals.length === 0) {
-        intervals = []
-        break
-      }
-
-      intervals = intervals === null ? rowIntervals : intersectIntervalSets(intervals, rowIntervals)
-      if (intervals.length === 0) {
-        break
-      }
-    }
+  index: number,
+  grapheme: string,
+  drawX: number,
+  baseline: number,
+): CompiledShapeRegion {
+  const { imageData } = renderTextMaskRaster(shape, size, grapheme, drawX, baseline)
 
-    bands.push({
-      top: bandTop,
-      bottom: bandTop + lineHeight,
-      intervals: (intervals ?? [])
-        .map(interval => ({
-          left: interval.left / maskScale,
-          right: interval.right / maskScale,
-        }))
-        .filter(interval => interval.right - interval.left >= minSlotWidth),
-    })
+  return {
+    index,
+    grapheme,
+    bounds: { left: 0, top: 0, right: size.width, bottom: size.height },
+    bands: buildTextMaskBandsFromAlpha(
+      {
+        width: size.width,
+        height: size.height,
+        maskScale: shape.maskScale ?? 2,
+        alphaThreshold: shape.alphaThreshold ?? 16,
+      },
+      imageData.data,
+      lineHeight,
+      minSlotWidth,
+    ),
+    debugView: {
+      kind: 'text',
+      text: grapheme,
+      font: shape.font,
+      x: drawX,
+      baseline,
+    },
   }
+}
 
-  return bands
+function buildRegions(
+  shape: TextMaskShape,
+  size: ResolvedTextMaskSize,
+  context: TextMaskCanvas['context'],
+  placement: TextMaskPlacement,
+  lineHeight: number,
+  minSlotWidth: number,
+): CompiledShapeRegion[] {
+  if ((shape.shapeTextMode ?? 'whole-text') !== 'per-character') {
+    return []
+  }
+
+  return segmentTextMaskGraphemes(shape.text, placement.x, value => context.measureText(value).width)
+    .filter(placementEntry => !placementEntry.isWhitespace)
+    .map((placementEntry, index) =>
+      buildRegion(
+        shape,
+        size,
+        lineHeight,
+        minSlotWidth,
+        index,
+        placementEntry.grapheme,
+        placementEntry.drawX,
+        placement.baseline,
+      ),
+    )
+    .filter(region => region.bands.some(band => band.intervals.length > 0))
 }
 
 export function compileTextMaskShapeForLayout(
@@ -239,24 +186,38 @@ export function compileTextMaskShapeForLayout(
   lineHeight: number,
   minSlotWidth: number,
 ): CompiledShapeBands {
-  validateTextMaskShape(shape)
-  const fontReadyForCache = isFontReadyForShape(shape)
+  const context = createBrowserCanvas2DContext(1, 1)
+  const contentMetrics = measureTextMaskContent(context, shape)
+  const size = resolveTextMaskShapeSize(shape, contentMetrics)
+  validateTextMaskShape(shape, size)
 
-  const cacheKey = buildCacheKey(shape, lineHeight, minSlotWidth)
+  const fontReadyForCache = isFontReadyForShape(shape)
+  const cacheKey = buildCacheKey(shape, size, lineHeight, minSlotWidth)
   const cachedShape = fontReadyForCache ? compiledShapeCache.get(cacheKey) : undefined
   if (cachedShape !== undefined) {
     return cachedShape
   }
 
-  const { context, imageData } = renderTextMask(shape)
-  const placement = getTextMaskPlacement(shape, context)
+  const placement = getTextMaskPlacement(size, contentMetrics)
+  const { imageData } = renderTextMaskRaster(shape, size, shape.text, placement.x, placement.baseline)
   const compiledShape: CompiledShapeBands = {
     kind: shape.kind,
     source: shape,
-    bounds: { left: 0, top: 0, right: shape.width, bottom: shape.height },
+    bounds: { left: 0, top: 0, right: size.width, bottom: size.height },
     bandHeight: lineHeight,
     minSlotWidth,
-    bands: buildBands(shape, imageData.data, lineHeight, minSlotWidth),
+    bands: buildTextMaskBandsFromAlpha(
+      {
+        width: size.width,
+        height: size.height,
+        maskScale: shape.maskScale ?? 2,
+        alphaThreshold: shape.alphaThreshold ?? 16,
+      },
+      imageData.data,
+      lineHeight,
+      minSlotWidth,
+    ),
+    regions: buildRegions(shape, size, context, placement, lineHeight, minSlotWidth),
     debugView: {
       kind: 'text',
       text: shape.text,
diff --git a/src/shape/render-text-mask-raster.ts b/src/shape/render-text-mask-raster.ts
new file mode 100644
index 0000000..fd6d9d5
--- /dev/null
+++ b/src/shape/render-text-mask-raster.ts
@@ -0,0 +1,54 @@
+import type { TextMaskShape } from '../types.js'
+import { createBrowserCanvas2DContext } from '../text/create-browser-canvas-2d-context.js'
+import type { ResolvedTextMaskSize, TextMaskContentMetrics } from './resolve-text-mask-shape-size.js'
+
+export type TextMaskPlacement = {
+  x: number
+  baseline: number
+}
+
+export type TextMaskCanvas = {
+  context: ReturnType<typeof createBrowserCanvas2DContext>
+  imageData: ImageData
+}
+
+export function getTextMaskPlacement(
+  size: ResolvedTextMaskSize,
+  metrics: TextMaskContentMetrics,
+): TextMaskPlacement {
+  const innerWidth = Math.max(0, size.width - size.padding * 2)
+  const innerHeight = Math.max(0, size.height - size.padding * 2)
+  const left = size.padding + Math.max(0, (innerWidth - metrics.width) / 2)
+  const top = size.padding + Math.max(0, (innerHeight - metrics.height) / 2)
+
+  return {
+    x: left + metrics.left,
+    baseline: top + metrics.ascent,
+  }
+}
+
+export function renderTextMaskRaster(
+  shape: TextMaskShape,
+  size: ResolvedTextMaskSize,
+  text = shape.text,
+  drawX?: number,
+  baseline?: number,
+): TextMaskCanvas {
+  const maskScale = shape.maskScale ?? 2
+  const pixelWidth = Math.max(1, Math.ceil(size.width * maskScale))
+  const pixelHeight = Math.max(1, Math.ceil(size.height * maskScale))
+  const context = createBrowserCanvas2DContext(pixelWidth, pixelHeight)
+
+  context.setTransform(1, 0, 0, 1, 0, 0)
+  context.clearRect(0, 0, pixelWidth, pixelHeight)
+  context.setTransform(maskScale, 0, 0, maskScale, 0, 0)
+  context.font = shape.font
+  context.fillStyle = '#000000'
+  context.textBaseline = 'alphabetic'
+  context.fillText(text, drawX ?? 0, baseline ?? 0)
+
+  return {
+    context,
+    imageData: context.getImageData(0, 0, pixelWidth, pixelHeight),
+  }
+}
diff --git a/src/shape/resolve-text-mask-shape-size.ts b/src/shape/resolve-text-mask-shape-size.ts
new file mode 100644
index 0000000..8b5b586
--- /dev/null
+++ b/src/shape/resolve-text-mask-shape-size.ts
@@ -0,0 +1,112 @@
+import type { BrowserCanvas2DContext } from '../text/create-browser-canvas-2d-context.js'
+import type { TextMaskShape, TextMaskShapeSizeMode } from '../types.js'
+
+type TextMaskShapeWithLegacySizeFields = TextMaskShape & {
+  width?: unknown
+  height?: unknown
+  padding?: unknown
+}
+
+export type TextMaskContentMetrics = {
+  left: number
+  right: number
+  ascent: number
+  descent: number
+  width: number
+  height: number
+}
+
+export type ResolvedTextMaskSize = {
+  mode: TextMaskShapeSizeMode
+  width: number
+  height: number
+  padding: number
+}
+
+function assertFiniteNumber(value: number, label: string): number {
+  if (!Number.isFinite(value)) {
+    throw new Error(`${label} must be a finite number`)
+  }
+
+  return value
+}
+
+function assertPositiveFiniteNumber(value: number, label: string): number {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`${label} must be a finite positive number`)
+  }
+
+  return value
+}
+
+function assertNoLegacySizeFields(shape: TextMaskShapeWithLegacySizeFields): void {
+  if ('width' in shape || 'height' in shape || 'padding' in shape) {
+    throw new Error('text-mask width, height, and padding moved to shape.size')
+  }
+}
+
+function resolveMetric(value: number | undefined, fallback = 0): number {
+  return value !== undefined && Number.isFinite(value) ? value : fallback
+}
+
+export function measureTextMaskContent(
+  context: BrowserCanvas2DContext,
+  shape: TextMaskShape,
+  text = shape.text,
+): TextMaskContentMetrics {
+  context.font = shape.font
+  const metrics = context.measureText(text)
+  const left = resolveMetric(metrics.actualBoundingBoxLeft, 0)
+  const right = resolveMetric(metrics.actualBoundingBoxRight, metrics.width)
+  const ascent = resolveMetric(metrics.actualBoundingBoxAscent, 0)
+  const descent = resolveMetric(metrics.actualBoundingBoxDescent, 0)
+
+  return {
+    left,
+    right,
+    ascent,
+    descent,
+    width: left + right,
+    height: ascent + descent,
+  }
+}
+
+export function resolveTextMaskShapeSize(
+  shape: TextMaskShape,
+  contentMetrics: TextMaskContentMetrics,
+): ResolvedTextMaskSize {
+  assertNoLegacySizeFields(shape as TextMaskShapeWithLegacySizeFields)
+
+  if (shape.size !== undefined && (shape.size === null || typeof shape.size !== 'object')) {
+    throw new Error('text-mask size must be an object')
+  }
+
+  const size = shape.size ?? {}
+  const mode = size.mode ?? 'fit-content'
+  if (mode !== 'fit-content' && mode !== 'fixed') {
+    throw new Error('text-mask size.mode must be fit-content or fixed')
+  }
+
+  const padding = size.padding === undefined ? 0 : assertFiniteNumber(size.padding, 'text-mask padding')
+  if (padding < 0) {
+    throw new Error('text-mask padding must be a finite non-negative number')
+  }
+
+  if (mode === 'fixed') {
+    const fixedSize = size as { width: number; height: number }
+
+    return {
+      mode,
+      width: assertPositiveFiniteNumber(fixedSize.width, 'text-mask fixed width'),
+      height: assertPositiveFiniteNumber(fixedSize.height, 'text-mask fixed height'),
+      padding,
+    }
+  }
+
+  return {
+    mode,
+    width: Math.max(1, contentMetrics.width + padding * 2),
+    height: Math.max(1, contentMetrics.height + padding * 2),
+    padding,
+  }
+}
diff --git a/src/shape/segment-text-mask-graphemes.ts b/src/shape/segment-text-mask-graphemes.ts
new file mode 100644
index 0000000..39527cd
--- /dev/null
+++ b/src/shape/segment-text-mask-graphemes.ts
@@ -0,0 +1,33 @@
+const graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' })
+
+export type TextMaskGraphemePlacement = {
+  grapheme: string
+  drawX: number
+  isWhitespace: boolean
+}
+
+function isWhitespaceGrapheme(grapheme: string): boolean {
+  return grapheme.trim().length === 0
+}
+
+export function segmentTextMaskGraphemes(
+  text: string,
+  originX: number,
+  measureAdvance: (value: string) => number,
+): TextMaskGraphemePlacement[] {
+  const segments = Array.from(graphemeSegmenter.segment(text), segment => segment.segment)
+  const placements: TextMaskGraphemePlacement[] = []
+  let prefix = ''
+
+  for (let index = 0; index < segments.length; index++) {
+    const grapheme = segments[index]!
+    placements.push({
+      grapheme,
+      drawX: originX + measureAdvance(prefix),
+      isWhitespace: isWhitespaceGrapheme(grapheme),
+    })
+    prefix += grapheme
+  }
+
+  return placements
+}
diff --git a/src/types.ts b/src/types.ts
index c5a920f..4f0b391 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -8,6 +8,23 @@ export type Interval = {
   right: number
 }
 
+export type TextMaskShapeTextMode = 'whole-text' | 'per-character'
+export type TextMaskShapeSizeMode = 'fit-content' | 'fixed'
+
+export type TextMaskShapeFitContentSize = {
+  mode?: 'fit-content'
+  padding?: number
+}
+
+export type TextMaskShapeFixedSize = {
+  mode: 'fixed'
+  width: number
+  height: number
+  padding?: number
+}
+
+export type TextMaskShapeSize = TextMaskShapeFitContentSize | TextMaskShapeFixedSize
+
 export type PolygonShape = {
   kind: 'polygon'
   points: ShapeTextPoint[]
@@ -17,9 +34,8 @@ export type TextMaskShape = {
   kind: 'text-mask'
   text: string
   font: string
-  width: number
-  height: number
-  padding?: number
+  size?: TextMaskShapeSize
+  shapeTextMode?: TextMaskShapeTextMode
   maskScale?: number
   alphaThreshold?: number
 }
@@ -139,6 +155,14 @@ export type CompiledShapeDebugView =
       baseline: number
     }
 
+export type CompiledShapeRegion = {
+  index: number
+  grapheme: string
+  bounds: ShapeBounds
+  bands: CompiledShapeBand[]
+  debugView: CompiledShapeDebugView
+}
+
 export type CompiledShapeBands = {
   kind: ShapeInput['kind']
   source: ShapeInput
@@ -146,6 +170,7 @@ export type CompiledShapeBands = {
   bandHeight: number
   minSlotWidth: number
   bands: CompiledShapeBand[]
+  regions?: CompiledShapeRegion[]
   debugView: CompiledShapeDebugView
 }
 

From 8e1cd47f6ea0058395d952b2aacaed53d2f55a3d Mon Sep 17 00:00:00 2001
From: tqdat410 <danhlagi01472@gmail.com>
Date: Thu, 2 Apr 2026 18:26:55 +0700
Subject: [PATCH 08/12] docs: update text-mask sizing and demo usage

Co-authored-by: Codex <noreply@openai.com>
---
 README.md                   | 48 ++++++++++++++++++++++++++++++++++---
 docs/project-changelog.md   |  4 ++++
 docs/system-architecture.md | 21 +++++++++-------
 3 files changed, 61 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index bbba2b8..dde49de 100644
--- a/README.md
+++ b/README.md
@@ -83,14 +83,45 @@ const layout = layoutTextInShape({
     kind: 'text-mask',
     text: '2',
     font: '700 420px Arial',
-    width: 340,
-    height: 460,
-    padding: 10,
+    size: {
+      mode: 'fit-content',
+      padding: 10,
+    },
+  },
+  measurer,
+})
+```
+
+## Sequential text-mask regions
+
+```ts
+const layout = layoutTextInShape({
+  text: 'ABCDEFGHIJ',
+  textStyle: {
+    family: 'Arial, sans-serif',
+    size: 14,
+    weight: 700,
+  },
+  lineHeight: 18,
+  shape: {
+    kind: 'text-mask',
+    text: 'AB',
+    font: '700 160px Arial',
+    size: {
+      mode: 'fixed',
+      width: 260,
+      height: 180,
+    },
+    shapeTextMode: 'per-character',
   },
   measurer,
 })
 ```
 
+`shape.size` defaults to `{ mode: 'fit-content', padding: 0 }`. Use `mode: 'fixed'` only when you need to force the glyph mask into an explicit raster box.
+
+`shape.shapeTextMode` defaults to `'whole-text'`. Set it to `'per-character'` to compile one ordered region per non-space grapheme and flow layout through those regions in shape-text order.
+
 ## Public API
 
 - `createCanvasTextMeasurer()`
@@ -112,6 +143,8 @@ const layout = layoutTextInShape({
 - `autoFill: true` repeats the source text until the available shape bands are full.
 - `autoFillMode: 'words'` is the default readable repeat behavior. `autoFillMode: 'dense'` strips whitespace and breaks at grapheme boundaries to pack shapes harder for decorative fills.
 - `fillStrategy: 'max'` switches to an all-slots pass that fills every usable interval in reading order. It keeps spaces as normal graphemes instead of stripping them, and it does not fall back to smaller text for leftover pockets.
+- `text-mask` sizing now lives under `shape.size`. The default `fit-content` mode measures the text mask first and grows the raster box to avoid clipping multi-character shapes such as `23`.
+- `shape.shapeTextMode: 'per-character'` keeps the full text-mask debug view, but also compiles ordered per-character regions for sequential fill across multi-character shape text.
 - `textStyle` is the new data-driven API for size, weight, italic/oblique, family, and default text color. Legacy `font` string input still works.
 - `shapeStyle` lives in `renderLayoutToSvg()` because fill, border, and shadow do not affect line breaking or shape compilation.
 - For late-loading web fonts, compile after the font is ready if you want immediate cache reuse. The compiler skips cache writes until `document.fonts.check()` reports the font as ready.
@@ -166,3 +199,12 @@ For a fast local loop without rebuilding first:
 npm run build
 npm run demo:dev
 ```
+
+The demo now includes:
+
+- direct `shape.text` editing for text-mask scenarios
+- `shape.size.mode` switching between `fit-content` and `fixed`
+- `shapeTextMode` switching between `whole-text` and sequential `per-character` text-mask regions
+- a payload JSON editor for the live `layout` + `render` request
+- a scrollable full-output SVG viewport with `Zoom out`, `Zoom in`, `100%`, and `Fit` controls
+- predefined random character-pattern fill presets for quick repeat-fill experiments
diff --git a/docs/project-changelog.md b/docs/project-changelog.md
index 97141a7..0a88440 100644
--- a/docs/project-changelog.md
+++ b/docs/project-changelog.md
@@ -21,5 +21,9 @@
 - Added renderer-side `shapeStyle` API for shape fill, border, and shadow
 - Added `autoFillMode: 'dense'` for whitespace-stripped grapheme repeat fill inside compiled shape bands
 - Added `fillStrategy: 'max'` for all-slot glyph coverage without mini-font fallback, while preserving spaces in the repeat stream
+- Added `shape.shapeTextMode: 'per-character'` for ordered non-space text-mask regions and sequential per-region layout flow
+- Replaced top-level text-mask `width` / `height` / `padding` with `shape.size`, defaulting text-mask sizing to `fit-content`
+- Added demo payload editing, freeform glyph-shape text input, and predefined random character-pattern fill presets
+- Added a scrollable demo full-output SVG viewport with zoom in/out, reset, and fit controls for wide or tall renders
 - Kept legacy `font`, `textFill`, `shapeFill`, and `shapeStroke` compatibility paths
 - Extended local demo and Playwright coverage for style and decoration controls
diff --git a/docs/system-architecture.md b/docs/system-architecture.md
index a90202a..6cf4eca 100644
--- a/docs/system-architecture.md
+++ b/docs/system-architecture.md
@@ -4,25 +4,28 @@
 
 - `text/*`: text preparation and streamed line breaking
 - `geometry/*`: polygon band sampling and interval extraction
-- `shape/*`: shape compilation and cacheable band generation
-- `layout/*`: shape-aware line placement and repeat-fill policies
+- `shape/*`: shape compilation, text-mask size resolution, cacheable band generation, and optional per-character text-mask region extraction
+- `layout/*`: shape-aware line placement, repeat-fill policies, and sequential region flow for per-character text masks
 - `render/*`: SVG serialization
+- `e2e/fixtures/*`: browser demo UI, payload editor, and SVG viewport zoom controller
 
 ## Data Flow
 
 1. Normalize text formatting into a canonical font string
-2. Compile the input shape into reusable line bands
-3. Compute allowed intervals for each band
-4. Pick the widest interval
-5. Stream the next line into that width
-6. Optionally repeat the source text until bands are full
+2. Resolve text-mask sizing into either `fit-content` or fixed bounds, then compile the input shape into reusable line bands
+3. For `text-mask` shapes with `shapeTextMode: 'per-character'`, also compile ordered non-space grapheme regions from the same mask source
+4. Compute allowed intervals for each band or per-character region
+5. Route layout through sequential regions when they exist; otherwise use the normal whole-shape flow or max-fill path
+6. Optionally repeat the source text until the active shape bands are full
 7. Project positioned lines into SVG
+8. In the demo, mount the SVG into a scrollable viewport and apply bounded zoom or fit-to-viewport scaling
 
 ## Boundary Decisions
 
-- Text measurement stays replaceable through `TextMeasurer`
+- Text measurement stays replaceable through the layout measurer interface
 - Layout-affecting text style stays in the layout API
-- Shape compilation stays separate from content flow so glyph shapes can be cached
+- Shape compilation stays separate from content flow so resolved text-mask bounds, glyph shapes, and per-character regions can be cached
 - Geometry stays shape-specific, not DOM-specific
 - Renderer-only decoration stays out of compile/layout caching
 - Renderer consumes compiled layout output only
+- Demo zoom is a presentation concern only; it never changes compile or layout results

From f83f26af65bd0f24a30c8e6c2656e5fb48f1a236 Mon Sep 17 00:00:00 2001
From: tqdat410 <danhlagi01472@gmail.com>
Date: Thu, 2 Apr 2026 20:52:12 +0700
Subject: [PATCH 09/12] feat(shape-paragraph): add react workbench and
 ship-ready runtime

Co-authored-by: Codex <noreply@openai.com>
---
 .gitignore                                    |   1 +
 LICENSE                                       |  21 +
 demo/index.html                               |  12 +
 demo/src/app.tsx                              |  90 +++
 demo/src/base.css                             |  64 ++
 demo/src/components/payload-editor-panel.tsx  |  73 +++
 demo/src/components/render-summary-panel.tsx  |  39 ++
 demo/src/components/shape-controls-panel.tsx  | 154 +++++
 demo/src/components/svg-output-viewport.tsx   |  86 +++
 demo/src/components/text-controls-panel.tsx   | 138 ++++
 demo/src/demo-model.ts                        | 116 ++++
 demo/src/demo-payload-primitives.ts           |  20 +
 demo/src/demo-payload.test.ts                 |  71 ++
 demo/src/demo-payload.ts                      |  22 +
 demo/src/demo-presets.test.ts                 |  43 ++
 demo/src/demo-presets.ts                      | 125 ++++
 demo/src/main.tsx                             |  18 +
 demo/src/merge-demo-layout-payload.ts         | 147 +++++
 demo/src/merge-demo-render-payload.ts         |  59 ++
 demo/src/use-rendered-demo-request.ts         |  49 ++
 demo/src/use-shape-paragraph-workbench.ts     | 193 ++++++
 demo/src/workbench.css                        | 167 +++++
 demo/vite.config.ts                           |  32 +
 e2e/fixtures/demo-fill-presets.js             |  52 --
 e2e/fixtures/demo-payload-helpers.js          | 268 --------
 e2e/fixtures/demo-scenarios.js                |  80 ---
 e2e/fixtures/demo-svg-viewport-controller.js  | 138 ----
 e2e/fixtures/demo-ui-controller.js            | 277 --------
 e2e/fixtures/index.html                       | 343 ----------
 e2e/fixtures/shape-text-e2e-app.js            | 177 -----
 e2e/shape-paragraph-demo.spec.ts              |  77 +++
 e2e/shape-paragraph-workbench.spec.ts         | 175 +++++
 e2e/shape-text-local-e2e.spec.ts              | 571 ----------------
 package-lock.json                             | 617 ++++++++++++++++++
 package.json                                  |  58 +-
 playwright.config.ts                          |   9 +-
 scripts/run-demo-app.mjs                      |  71 ++
 scripts/run-e2e-serve.mjs                     |  36 -
 scripts/run-library-build.mjs                 |  33 +
 scripts/run-library-ship-check.mjs            | 167 +++++
 scripts/run-node-script-from-package-root.cjs |  35 +
 scripts/run-project-check.mjs                 |  31 +
 scripts/serve-static-e2e.mjs                  |  57 --
 src/index.ts                                  |   2 -
 .../layout-flow-lines-in-compiled-shape.ts    |  40 +-
 src/layout/layout-text-in-compiled-shape.ts   |  10 +-
 src/layout/layout-text-in-shape.test.ts       |  51 +-
 src/layout/layout-text-in-shape.ts            |   6 +-
 src/layout/resolve-flow-layout.ts             |  31 +-
 src/layout/resolve-max-fill-layout.ts         |   2 -
 .../resolve-sequential-shape-regions.ts       |  36 +-
 src/render/render-layout-to-svg.test.ts       |   6 +-
 src/types.ts                                  |   9 -
 tsconfig.build.json                           |   4 +-
 tsconfig.json                                 |  16 +-
 vitest.config.ts                              |   6 +-
 56 files changed, 3054 insertions(+), 2177 deletions(-)
 create mode 100644 LICENSE
 create mode 100644 demo/index.html
 create mode 100644 demo/src/app.tsx
 create mode 100644 demo/src/base.css
 create mode 100644 demo/src/components/payload-editor-panel.tsx
 create mode 100644 demo/src/components/render-summary-panel.tsx
 create mode 100644 demo/src/components/shape-controls-panel.tsx
 create mode 100644 demo/src/components/svg-output-viewport.tsx
 create mode 100644 demo/src/components/text-controls-panel.tsx
 create mode 100644 demo/src/demo-model.ts
 create mode 100644 demo/src/demo-payload-primitives.ts
 create mode 100644 demo/src/demo-payload.test.ts
 create mode 100644 demo/src/demo-payload.ts
 create mode 100644 demo/src/demo-presets.test.ts
 create mode 100644 demo/src/demo-presets.ts
 create mode 100644 demo/src/main.tsx
 create mode 100644 demo/src/merge-demo-layout-payload.ts
 create mode 100644 demo/src/merge-demo-render-payload.ts
 create mode 100644 demo/src/use-rendered-demo-request.ts
 create mode 100644 demo/src/use-shape-paragraph-workbench.ts
 create mode 100644 demo/src/workbench.css
 create mode 100644 demo/vite.config.ts
 delete mode 100644 e2e/fixtures/demo-fill-presets.js
 delete mode 100644 e2e/fixtures/demo-payload-helpers.js
 delete mode 100644 e2e/fixtures/demo-scenarios.js
 delete mode 100644 e2e/fixtures/demo-svg-viewport-controller.js
 delete mode 100644 e2e/fixtures/demo-ui-controller.js
 delete mode 100644 e2e/fixtures/index.html
 delete mode 100644 e2e/fixtures/shape-text-e2e-app.js
 create mode 100644 e2e/shape-paragraph-demo.spec.ts
 create mode 100644 e2e/shape-paragraph-workbench.spec.ts
 delete mode 100644 e2e/shape-text-local-e2e.spec.ts
 create mode 100644 scripts/run-demo-app.mjs
 delete mode 100644 scripts/run-e2e-serve.mjs
 create mode 100644 scripts/run-library-build.mjs
 create mode 100644 scripts/run-library-ship-check.mjs
 create mode 100644 scripts/run-node-script-from-package-root.cjs
 create mode 100644 scripts/run-project-check.mjs
 delete mode 100644 scripts/serve-static-e2e.mjs

diff --git a/.gitignore b/.gitignore
index c9310e7..206f449 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,6 @@
 node_modules/
 dist/
+demo/dist/
 coverage/
 playwright-report/
 test-results/
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..b62b2f8
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Admin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/demo/index.html b/demo/index.html
new file mode 100644
index 0000000..de0d944
--- /dev/null
+++ b/demo/index.html
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>shape-text shape paragraph demo</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./src/main.tsx"></script>
+  </body>
+  </html>
diff --git a/demo/src/app.tsx b/demo/src/app.tsx
new file mode 100644
index 0000000..de8dbc4
--- /dev/null
+++ b/demo/src/app.tsx
@@ -0,0 +1,90 @@
+import { PayloadEditorPanel } from './components/payload-editor-panel'
+import { RenderSummaryPanel } from './components/render-summary-panel'
+import { ShapeControlsPanel } from './components/shape-controls-panel'
+import { SvgOutputViewport } from './components/svg-output-viewport'
+import { TextControlsPanel } from './components/text-controls-panel'
+import { useRenderedDemoRequest } from './use-rendered-demo-request'
+import { useShapeParagraphWorkbench } from './use-shape-paragraph-workbench'
+
+export function App() {
+  const workbench = useShapeParagraphWorkbench()
+  const rendered = useRenderedDemoRequest(workbench.request)
+  const isTextMask = workbench.request.layout.shape.kind === 'text-mask'
+  const textWeight = String(workbench.request.layout.textStyle.weight ?? '700')
+  const textItalic = (workbench.request.layout.textStyle.style ?? 'normal') !== 'normal'
+  const textColor = workbench.request.layout.textStyle.color ?? '#0f172a'
+  const shapeFill = workbench.request.render.shapeStyle?.backgroundColor ?? '#dbeafe'
+
+  return (
+    <main className="app-shell">
+      <section className="hero panel">
+        <p className="eyebrow">shape paragraph</p>
+        <h1>Shape paragraph workbench</h1>
+        <p className="hero-copy">
+          One library, two shape sources: explicit geometry input or value-derived input. The demo is now the real browser workbench and the future E2E target.
+        </p>
+      </section>
+
+      <section className="layout-grid">
+        <div className="sidebar">
+          <TextControlsPanel
+            text={workbench.request.layout.text}
+            fillPresetId={workbench.fillPresetId}
+            autoFill={workbench.request.layout.autoFill}
+            textSize={workbench.request.layout.textStyle.size}
+            lineHeight={workbench.request.layout.lineHeight}
+            textWeight={textWeight}
+            textItalic={textItalic}
+            textColor={textColor}
+            onTextChange={workbench.setText}
+            onFillPresetChange={workbench.setFillPreset}
+            onFillPresetReroll={workbench.rerollFillPreset}
+            onAutoFillChange={workbench.setAutoFill}
+            onTextSizeChange={workbench.setTextSize}
+            onLineHeightChange={workbench.setLineHeight}
+            onTextWeightChange={workbench.setTextWeight}
+            onTextItalicChange={workbench.setTextItalic}
+            onTextColorChange={workbench.setTextColor}
+          />
+
+          <ShapeControlsPanel
+            shapeSource={workbench.shapeSource}
+            geometryPresetId={workbench.geometryPresetId}
+            shape={workbench.request.layout.shape}
+            showShape={workbench.request.render.showShape ?? true}
+            shapeFill={shapeFill}
+            onShapeSourceChange={workbench.setShapeSource}
+            onGeometryPresetChange={workbench.setGeometryPreset}
+            onShapeTextChange={workbench.setShapeText}
+            onShapeTextModeChange={workbench.setShapeTextMode}
+            onShapeSizeModeChange={workbench.setShapeSizeMode}
+            onShapeFixedDimensionChange={workbench.setShapeFixedDimension}
+            onShowShapeChange={workbench.setShowShape}
+            onShapeFillChange={workbench.setShapeFill}
+          />
+
+          <PayloadEditorPanel request={workbench.request} onApply={workbench.applyRequest} />
+        </div>
+
+        <div className="main-panel">
+          <SvgOutputViewport svg={rendered.svg} />
+          <RenderSummaryPanel
+            layout={rendered.layout}
+            shapeSource={workbench.shapeSource}
+            error={rendered.error}
+          />
+
+          {isTextMask ? (
+            <p className="mode-note">
+              Value-derived mode keeps `text-mask` as the low-level API term, but frames it in the UI as a shape source, not a one-off feature.
+            </p>
+          ) : (
+            <p className="mode-note">
+              Geometry mode uses the same layout engine, only the compiled shape source changes.
+            </p>
+          )}
+        </div>
+      </section>
+    </main>
+  )
+}
diff --git a/demo/src/base.css b/demo/src/base.css
new file mode 100644
index 0000000..1c455d0
--- /dev/null
+++ b/demo/src/base.css
@@ -0,0 +1,64 @@
+:root {
+  color-scheme: light;
+  font-family: "Instrument Sans", "Segoe UI", sans-serif;
+  background: #eff3f6;
+  color: #10243c;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  min-width: 320px;
+  background:
+    radial-gradient(circle at top left, rgba(174, 239, 220, 0.38), transparent 32%),
+    linear-gradient(180deg, #f7f5ee 0%, #e8eef4 100%);
+}
+
+button,
+input,
+select,
+textarea {
+  font: inherit;
+}
+
+h1,
+h2,
+p {
+  margin: 0;
+}
+
+textarea,
+input[type="text"],
+input[type="number"],
+select {
+  width: 100%;
+  padding: 12px 14px;
+  border-radius: 18px;
+  border: 1px solid #cad5e0;
+  background: rgba(255, 255, 255, 0.92);
+}
+
+textarea {
+  min-height: 160px;
+  resize: vertical;
+}
+
+input[type="range"] {
+  width: 100%;
+}
+
+button {
+  border: 1px solid #c1cfda;
+  border-radius: 999px;
+  background: white;
+  padding: 8px 14px;
+  cursor: pointer;
+}
+
+details summary {
+  cursor: pointer;
+  font-weight: 700;
+}
diff --git a/demo/src/components/payload-editor-panel.tsx b/demo/src/components/payload-editor-panel.tsx
new file mode 100644
index 0000000..4491f16
--- /dev/null
+++ b/demo/src/components/payload-editor-panel.tsx
@@ -0,0 +1,73 @@
+import { useEffect, useState } from 'react'
+
+import type { DemoRequest } from '../demo-model'
+import { parseDemoRequest, serializeDemoRequest } from '../demo-payload'
+
+type PayloadEditorPanelProps = {
+  request: DemoRequest
+  onApply: (value: DemoRequest) => void
+}
+
+export function PayloadEditorPanel(props: PayloadEditorPanelProps) {
+  const [draft, setDraft] = useState(() => serializeDemoRequest(props.request))
+  const [isDirty, setIsDirty] = useState(false)
+  const [error, setError] = useState('')
+
+  useEffect(() => {
+    if (!isDirty) {
+      setDraft(serializeDemoRequest(props.request))
+    }
+  }, [isDirty, props.request])
+
+  function handleApply() {
+    try {
+      props.onApply(parseDemoRequest(draft, props.request))
+      setError('')
+      setIsDirty(false)
+    } catch (nextError) {
+      setError(nextError instanceof Error ? nextError.message : String(nextError))
+    }
+  }
+
+  function handleReset() {
+    setDraft(serializeDemoRequest(props.request))
+    setError('')
+    setIsDirty(false)
+  }
+
+  return (
+    <details className="panel">
+      <summary>Advanced payload editor</summary>
+
+      <p className="panel-copy">Edit the raw `layoutTextInShape()` and `renderLayoutToSvg()` request only when you need full control.</p>
+
+      <label className="field">
+        <span>Payload JSON</span>
+        <textarea
+          aria-label="Payload JSON"
+          className="payload-textarea"
+          value={draft}
+          onChange={event => {
+            setDraft(event.target.value)
+            setIsDirty(true)
+          }}
+        />
+      </label>
+
+      <div className="button-row">
+        <button type="button" onClick={handleApply}>
+          Apply JSON
+        </button>
+        <button type="button" onClick={handleReset}>
+          Reset JSON
+        </button>
+      </div>
+
+      {error.length > 0 ? (
+        <p aria-live="polite" className="error-box" data-testid="payload-error">
+          {error}
+        </p>
+      ) : null}
+    </details>
+  )
+}
diff --git a/demo/src/components/render-summary-panel.tsx b/demo/src/components/render-summary-panel.tsx
new file mode 100644
index 0000000..abfa270
--- /dev/null
+++ b/demo/src/components/render-summary-panel.tsx
@@ -0,0 +1,39 @@
+import type { ShapeTextLayout } from 'shape-text'
+
+import type { ShapeSource } from '../demo-model'
+
+type RenderSummaryPanelProps = {
+  layout: ShapeTextLayout | null
+  shapeSource: ShapeSource
+  error: string
+}
+
+export function RenderSummaryPanel(props: RenderSummaryPanelProps) {
+  const width = props.layout === null ? 0 : props.layout.compiledShape.bounds.right - props.layout.compiledShape.bounds.left
+  const height = props.layout === null ? 0 : props.layout.compiledShape.bounds.bottom - props.layout.compiledShape.bounds.top
+  const regionCount = props.layout?.compiledShape.regions?.length ?? 0
+
+  return (
+    <section className="panel summary-panel">
+      <div className="panel-heading">
+        <h2>Summary</h2>
+        <p>Visible app state only. Tests should read this, not private controller internals.</p>
+      </div>
+
+      <dl className="summary-grid">
+        <div><dt>Shape source</dt><dd data-testid="summary-shape-source">{props.shapeSource}</dd></div>
+        <div><dt>Resolved size</dt><dd data-testid="summary-shape-size">{width} × {height}</dd></div>
+        <div><dt>Line count</dt><dd data-testid="summary-line-count">{props.layout?.lines.length ?? 0}</dd></div>
+        <div><dt>Region count</dt><dd data-testid="summary-region-count">{regionCount}</dd></div>
+        <div><dt>Exhausted</dt><dd data-testid="summary-exhausted">{String(props.layout?.exhausted ?? false)}</dd></div>
+        <div><dt>Auto fill</dt><dd data-testid="summary-auto-fill">{String(props.layout?.autoFill ?? false)}</dd></div>
+      </dl>
+
+      {props.error.length > 0 ? (
+        <p aria-live="polite" className="error-box" data-testid="render-error">
+          {props.error}
+        </p>
+      ) : null}
+    </section>
+  )
+}
diff --git a/demo/src/components/shape-controls-panel.tsx b/demo/src/components/shape-controls-panel.tsx
new file mode 100644
index 0000000..ed7540e
--- /dev/null
+++ b/demo/src/components/shape-controls-panel.tsx
@@ -0,0 +1,154 @@
+import type { ShapeInput } from 'shape-text'
+
+import { geometryPresets, type GeometryPresetId } from '../demo-presets'
+import type { ShapeSource } from '../demo-model'
+
+type ShapeControlsPanelProps = {
+  shapeSource: ShapeSource
+  geometryPresetId: GeometryPresetId
+  shape: ShapeInput
+  showShape: boolean
+  shapeFill: string
+  onShapeSourceChange: (value: ShapeSource) => void
+  onGeometryPresetChange: (value: GeometryPresetId) => void
+  onShapeTextChange: (value: string) => void
+  onShapeTextModeChange: (value: 'whole-text' | 'per-character') => void
+  onShapeSizeModeChange: (value: 'fit-content' | 'fixed') => void
+  onShapeFixedDimensionChange: (dimension: 'width' | 'height', value: number) => void
+  onShowShapeChange: (value: boolean) => void
+  onShapeFillChange: (value: string) => void
+}
+
+export function ShapeControlsPanel(props: ShapeControlsPanelProps) {
+  const textMaskShape = props.shape.kind === 'text-mask' ? props.shape : null
+  const fixedTextMaskSize = textMaskShape?.size?.mode === 'fixed' ? textMaskShape.size : null
+
+  return (
+    <section className="panel">
+      <div className="panel-heading">
+        <h2>Shape Source</h2>
+        <p>Choose whether the paragraph flows through explicit geometry or a value-derived text mask.</p>
+      </div>
+
+      <div className="field-grid">
+        <label className="field">
+          <span>Shape source</span>
+          <select
+            aria-label="Shape source"
+            value={props.shapeSource}
+            onChange={event => props.onShapeSourceChange(event.target.value as ShapeSource)}
+          >
+            <option value="value-derived">Value-derived input</option>
+            <option value="geometry">Geometry input</option>
+          </select>
+        </label>
+
+        {textMaskShape === null ? (
+          <label className="field">
+            <span>Geometry preset</span>
+            <select
+              aria-label="Geometry preset"
+              value={props.geometryPresetId}
+              onChange={event => props.onGeometryPresetChange(event.target.value as GeometryPresetId)}
+            >
+              {props.geometryPresetId === 'custom' ? <option value="custom">Custom geometry</option> : null}
+              {geometryPresets.map(preset => (
+                <option key={preset.id} value={preset.id}>
+                  {preset.label}
+                </option>
+              ))}
+            </select>
+          </label>
+        ) : null}
+
+        <label className="field checkbox-field">
+          <span>Show shape</span>
+          <input
+            aria-label="Show shape"
+            type="checkbox"
+            checked={props.showShape}
+            onChange={event => props.onShowShapeChange(event.target.checked)}
+          />
+        </label>
+
+        <label className="field">
+          <span>Shape fill</span>
+          <input
+            aria-label="Shape fill"
+            type="color"
+            value={props.shapeFill}
+            onChange={event => props.onShapeFillChange(event.target.value)}
+          />
+        </label>
+      </div>
+
+      {textMaskShape !== null ? (
+        <div className="field-grid">
+          <label className="field">
+            <span>Shape value</span>
+            <input
+              aria-label="Shape value"
+              type="text"
+              value={textMaskShape.text}
+              onChange={event => props.onShapeTextChange(event.target.value)}
+            />
+          </label>
+
+          <label className="field">
+            <span>Shape text mode</span>
+            <select
+              aria-label="Shape text mode"
+              value={textMaskShape.shapeTextMode ?? 'whole-text'}
+              onChange={event =>
+                props.onShapeTextModeChange(event.target.value as 'whole-text' | 'per-character')
+              }
+            >
+              <option value="whole-text">Whole text shape</option>
+              <option value="per-character">Per-character regions</option>
+            </select>
+          </label>
+
+          <label className="field">
+            <span>Shape size mode</span>
+            <select
+              aria-label="Shape size mode"
+              value={textMaskShape.size?.mode === 'fixed' ? 'fixed' : 'fit-content'}
+              onChange={event => props.onShapeSizeModeChange(event.target.value as 'fit-content' | 'fixed')}
+            >
+              <option value="fit-content">Fit content</option>
+              <option value="fixed">Fixed box</option>
+            </select>
+          </label>
+
+          {fixedTextMaskSize !== null ? (
+            <>
+              <label className="field">
+                <span>Fixed width</span>
+                <input
+                  aria-label="Fixed width"
+                  type="number"
+                  min="1"
+                  step="1"
+                   value={fixedTextMaskSize.width}
+                   onChange={event => props.onShapeFixedDimensionChange('width', Number(event.target.value))}
+                 />
+              </label>
+
+              <label className="field">
+                <span>Fixed height</span>
+                <input
+                  aria-label="Fixed height"
+                  type="number"
+                  min="1"
+                  step="1"
+                   value={fixedTextMaskSize.height}
+                   onChange={event => props.onShapeFixedDimensionChange('height', Number(event.target.value))}
+                 />
+              </label>
+            </>
+          ) : null}
+        </div>
+      ) : null}
+    </section>
+  )
+}
diff --git a/demo/src/components/svg-output-viewport.tsx b/demo/src/components/svg-output-viewport.tsx
new file mode 100644
index 0000000..01bd0fa
--- /dev/null
+++ b/demo/src/components/svg-output-viewport.tsx
@@ -0,0 +1,86 @@
+import { useEffect, useRef, useState } from 'react'
+
+type SvgOutputViewportProps = {
+  svg: string
+}
+
+function readSvgSize(svg: SVGSVGElement | null) {
+  if (svg === null) {
+    return { width: 0, height: 0 }
+  }
+
+  const viewBox = svg.viewBox.baseVal
+  if (viewBox.width > 0 && viewBox.height > 0) {
+    return { width: viewBox.width, height: viewBox.height }
+  }
+
+  return {
+    width: Number(svg.getAttribute('width') ?? 0),
+    height: Number(svg.getAttribute('height') ?? 0),
+  }
+}
+
+export function SvgOutputViewport(props: SvgOutputViewportProps) {
+  const viewportRef = useRef<HTMLDivElement | null>(null)
+  const stageRef = useRef<HTMLDivElement | null>(null)
+  const [zoom, setZoom] = useState(1)
+  const [contentSize, setContentSize] = useState({ width: 0, height: 0 })
+
+  function fitZoom() {
+    const viewport = viewportRef.current
+    const { width, height } = contentSize
+    if (viewport === null || width <= 0 || height <= 0) {
+      return
+    }
+
+    setZoom(
+      Math.min(1, (viewport.clientWidth - 24) / width, (viewport.clientHeight - 24) / height),
+    )
+  }
+
+  useEffect(() => {
+    const nextSize = readSvgSize(stageRef.current?.querySelector('svg') ?? null)
+    setContentSize(nextSize)
+    const frame = window.requestAnimationFrame(() => fitZoom())
+    return () => window.cancelAnimationFrame(frame)
+  }, [props.svg])
+
+  return (
+    <section className="panel stage-panel">
+      <div className="panel-heading">
+        <h2>SVG output</h2>
+        <p>Inspect the full rendered output, zoom in, zoom out, or fit the current shape paragraph.</p>
+      </div>
+
+      <div className="button-row">
+        <button type="button" onClick={() => setZoom(current => Math.max(0.2, Number((current - 0.1).toFixed(2))))}>
+          Zoom out
+        </button>
+        <button type="button" onClick={() => setZoom(current => Number((current + 0.1).toFixed(2)))}>
+          Zoom in
+        </button>
+        <button type="button" onClick={() => setZoom(1)}>100%</button>
+        <button type="button" onClick={fitZoom}>Fit</button>
+        <span className="zoom-label" data-testid="stage-zoom">{Math.round(zoom * 100)}%</span>
+      </div>
+
+      <div ref={viewportRef} className="stage-viewport" data-testid="stage-viewport">
+        <div
+          className="stage-scale-box"
+          style={{
+            width: contentSize.width * zoom,
+            height: contentSize.height * zoom,
+          }}
+        >
+          <div
+            ref={stageRef}
+            className="stage"
+            data-testid="stage"
+            style={{ transform: `scale(${zoom})` }}
+            dangerouslySetInnerHTML={{ __html: props.svg }}
+          />
+        </div>
+      </div>
+    </section>
+  )
+}
diff --git a/demo/src/components/text-controls-panel.tsx b/demo/src/components/text-controls-panel.tsx
new file mode 100644
index 0000000..2ba8157
--- /dev/null
+++ b/demo/src/components/text-controls-panel.tsx
@@ -0,0 +1,138 @@
+import { fillTextPresets, type FillPresetId } from '../demo-presets'
+
+type TextControlsPanelProps = {
+  text: string
+  fillPresetId: FillPresetId
+  autoFill: boolean
+  textSize: number
+  lineHeight: number
+  textWeight: string
+  textItalic: boolean
+  textColor: string
+  onTextChange: (value: string) => void
+  onFillPresetChange: (value: FillPresetId) => void
+  onFillPresetReroll: () => void
+  onAutoFillChange: (value: boolean) => void
+  onTextSizeChange: (value: number) => void
+  onLineHeightChange: (value: number) => void
+  onTextWeightChange: (value: string) => void
+  onTextItalicChange: (value: boolean) => void
+  onTextColorChange: (value: string) => void
+}
+
+export function TextControlsPanel(props: TextControlsPanelProps) {
+  return (
+    <section className="panel">
+      <div className="panel-heading">
+        <h2>Paragraph</h2>
+        <p>Choose the paragraph, max-fill source text, and readable text styling.</p>
+      </div>
+
+      <label className="field">
+        <span>Text</span>
+        <textarea
+          aria-label="Paragraph text"
+          value={props.text}
+          onChange={event => props.onTextChange(event.target.value)}
+        />
+      </label>
+
+      <div className="field-grid">
+        <label className="field">
+          <span>Fill preset</span>
+          <div className="button-row">
+            <select
+              aria-label="Fill preset"
+              value={props.fillPresetId}
+              onChange={event => props.onFillPresetChange(event.target.value as FillPresetId)}
+            >
+              {fillTextPresets.map(preset => (
+                <option key={preset.id} value={preset.id}>
+                  {preset.label}
+                </option>
+              ))}
+            </select>
+
+            <button
+              type="button"
+              onClick={props.onFillPresetReroll}
+              disabled={props.fillPresetId === 'custom'}
+            >
+              Reroll
+            </button>
+          </div>
+        </label>
+
+        <label className="field checkbox-field">
+          <span>Auto fill</span>
+          <input
+            aria-label="Auto fill"
+            type="checkbox"
+            checked={props.autoFill}
+            onChange={event => props.onAutoFillChange(event.target.checked)}
+          />
+        </label>
+
+        <label className="field">
+          <span>Weight</span>
+          <select
+            aria-label="Text weight"
+            value={props.textWeight}
+            onChange={event => props.onTextWeightChange(event.target.value)}
+          >
+            <option value="400">Regular</option>
+            <option value="700">Bold</option>
+          </select>
+        </label>
+
+        <label className="field checkbox-field">
+          <span>Italic</span>
+          <input
+            aria-label="Italic"
+            type="checkbox"
+            checked={props.textItalic}
+            onChange={event => props.onTextItalicChange(event.target.checked)}
+          />
+        </label>
+
+        <label className="field">
+          <span>Text color</span>
+          <input
+            aria-label="Text color"
+            type="color"
+            value={props.textColor}
+            onChange={event => props.onTextColorChange(event.target.value)}
+          />
+        </label>
+      </div>
+
+      <div className="field-grid">
+        <label className="field">
+          <span>Text size: {props.textSize}px</span>
+          <input
+            aria-label="Text size"
+            type="range"
+            min="14"
+            max="34"
+            step="1"
+            value={props.textSize}
+            onChange={event => props.onTextSizeChange(Number(event.target.value))}
+          />
+        </label>
+
+        <label className="field">
+          <span>Line height: {props.lineHeight}px</span>
+          <input
+            aria-label="Line height"
+            type="range"
+            min="18"
+            max="40"
+            step="1"
+            value={props.lineHeight}
+            onChange={event => props.onLineHeightChange(Number(event.target.value))}
+          />
+        </label>
+      </div>
+    </section>
+  )
+}
diff --git a/demo/src/demo-model.ts b/demo/src/demo-model.ts
new file mode 100644
index 0000000..923ad73
--- /dev/null
+++ b/demo/src/demo-model.ts
@@ -0,0 +1,116 @@
+import type {
+  PolygonShape,
+  RenderLayoutToSvgOptions,
+  ShapeInput,
+  TextMaskShape,
+  TextStyleInput,
+} from 'shape-text'
+
+import { createGeometryShapeFromPreset, defaultParagraphText, type GeometryPresetId } from './demo-presets'
+
+export type ShapeSource = 'geometry' | 'value-derived'
+
+export type DemoRequest = {
+  layout: {
+    text: string
+    textStyle: TextStyleInput
+    lineHeight: number
+    shape: ShapeInput
+    minSlotWidth?: number
+    autoFill: boolean
+  }
+  render: RenderLayoutToSvgOptions
+}
+
+export function createDefaultTextMaskShape(): TextMaskShape {
+  return {
+    kind: 'text-mask',
+    text: '23',
+    font: '700 420px Arial',
+    size: {
+      mode: 'fit-content',
+      padding: 10,
+    },
+    shapeTextMode: 'whole-text',
+    maskScale: 2,
+  }
+}
+
+export function createDefaultDemoRequest(): DemoRequest {
+  return {
+    layout: {
+      text: defaultParagraphText,
+      textStyle: {
+        family: '"Helvetica Neue", Arial, sans-serif',
+        size: 18,
+        weight: 700,
+        style: 'normal',
+        color: '#0f172a',
+      },
+      lineHeight: 24,
+      shape: createDefaultTextMaskShape(),
+      autoFill: true,
+    },
+    render: {
+      background: '#f8fafc',
+      padding: 16,
+      showShape: true,
+      shapeStyle: {
+        backgroundColor: '#dbeafe',
+        borderColor: '#94a3b8',
+        borderWidth: 2,
+        shadow: {
+          color: 'rgba(15, 23, 42, 0.22)',
+          blur: 8,
+          offsetX: 0,
+          offsetY: 8,
+        },
+      },
+    },
+  }
+}
+
+export function cloneDemoRequest(request: DemoRequest): DemoRequest {
+  return {
+    layout: {
+      ...request.layout,
+      textStyle: { ...request.layout.textStyle },
+      shape: cloneShape(request.layout.shape),
+    },
+    render: {
+      ...request.render,
+      shapeStyle:
+        request.render.shapeStyle === undefined
+          ? undefined
+          : {
+              ...request.render.shapeStyle,
+              shadow:
+                request.render.shapeStyle.shadow === undefined
+                  ? undefined
+                  : { ...request.render.shapeStyle.shadow },
+            },
+    },
+  }
+}
+
+export function cloneShape(shape: ShapeInput): ShapeInput {
+  if (shape.kind === 'polygon') {
+    return {
+      kind: 'polygon',
+      points: shape.points.map(point => ({ ...point })),
+    }
+  }
+
+  return {
+    ...shape,
+    size: shape.size === undefined ? undefined : { ...shape.size },
+  }
+}
+
+export function deriveShapeSource(shape: ShapeInput): ShapeSource {
+  return shape.kind === 'polygon' ? 'geometry' : 'value-derived'
+}
+
+export function createDefaultGeometryShape(geometryPresetId: GeometryPresetId): PolygonShape {
+  return createGeometryShapeFromPreset(geometryPresetId)
+}
diff --git a/demo/src/demo-payload-primitives.ts b/demo/src/demo-payload-primitives.ts
new file mode 100644
index 0000000..316b8e0
--- /dev/null
+++ b/demo/src/demo-payload-primitives.ts
@@ -0,0 +1,20 @@
+export function assertObject(value: unknown, label: string): Record<string, unknown> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`)
+  }
+
+  return value as Record<string, unknown>
+}
+
+export function readFiniteNumber(value: unknown, label: string, allowZero = false) {
+  const number = Number(value)
+  if (!Number.isFinite(number) || (!allowZero && number <= 0)) {
+    throw new Error(`${label} must be a finite ${allowZero ? 'number' : 'positive number'}`)
+  }
+
+  return number
+}
+
+export function hasOwnProperty(value: Record<string, unknown>, key: string) {
+  return Object.prototype.hasOwnProperty.call(value, key)
+}
diff --git a/demo/src/demo-payload.test.ts b/demo/src/demo-payload.test.ts
new file mode 100644
index 0000000..98bcd15
--- /dev/null
+++ b/demo/src/demo-payload.test.ts
@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'vitest'
+
+import { createDefaultDemoRequest } from './demo-model'
+import { parseDemoRequest } from './demo-payload'
+import { identifyGeometryPresetId } from './demo-presets'
+
+describe('parseDemoRequest', () => {
+  it('preserves omitted nested fields during partial payload merges', () => {
+    const fallback = createDefaultDemoRequest()
+    fallback.layout.autoFill = true
+    fallback.layout.textStyle.style = 'italic'
+
+    const nextRequest = parseDemoRequest(
+      JSON.stringify({
+        layout: {
+          textStyle: {
+            size: 30,
+          },
+        },
+        render: {},
+      }),
+      fallback,
+    )
+
+    expect(nextRequest.layout.textStyle.size).toBe(30)
+    expect(nextRequest.layout.textStyle.style).toBe('italic')
+    expect(nextRequest.layout.autoFill).toBe(true)
+  })
+
+  it('marks non-matching polygon shapes as custom geometry', () => {
+    const nextRequest = parseDemoRequest(
+      JSON.stringify({
+        layout: {
+          shape: {
+            kind: 'polygon',
+            points: [
+              { x: 0, y: 0 },
+              { x: 200, y: 0 },
+              { x: 120, y: 220 },
+            ],
+          },
+        },
+        render: {},
+      }),
+      createDefaultDemoRequest(),
+    )
+
+    expect(nextRequest.layout.shape.kind).toBe('polygon')
+    if (nextRequest.layout.shape.kind !== 'polygon') {
+      throw new Error('Expected polygon shape')
+    }
+
+    expect(identifyGeometryPresetId(nextRequest.layout.shape)).toBe('custom')
+  })
+
+  it('keeps textStyle weight 500 when the payload provides it directly', () => {
+    const nextRequest = parseDemoRequest(
+      JSON.stringify({
+        layout: {
+          textStyle: {
+            weight: 500,
+          },
+        },
+        render: {},
+      }),
+      createDefaultDemoRequest(),
+    )
+
+    expect(nextRequest.layout.textStyle.weight).toBe(500)
+  })
+})
diff --git a/demo/src/demo-payload.ts b/demo/src/demo-payload.ts
new file mode 100644
index 0000000..c56c6bb
--- /dev/null
+++ b/demo/src/demo-payload.ts
@@ -0,0 +1,22 @@
+import type { DemoRequest } from './demo-model'
+
+import { cloneDemoRequest } from './demo-model'
+import { assertObject } from './demo-payload-primitives'
+import { mergeDemoLayoutPayload } from './merge-demo-layout-payload'
+import { mergeDemoRenderPayload } from './merge-demo-render-payload'
+
+export function serializeDemoRequest(request: DemoRequest) {
+  return JSON.stringify(request, null, 2)
+}
+
+export function parseDemoRequest(jsonText: string, fallback: DemoRequest): DemoRequest {
+  const root = assertObject(JSON.parse(jsonText), 'payload')
+  const layout = assertObject(root.layout, 'payload.layout')
+  const render = assertObject(root.render, 'payload.render')
+  const nextRequest = cloneDemoRequest(fallback)
+
+  mergeDemoLayoutPayload(nextRequest, layout)
+  mergeDemoRenderPayload(nextRequest, render)
+
+  return nextRequest
+}
diff --git a/demo/src/demo-presets.test.ts b/demo/src/demo-presets.test.ts
new file mode 100644
index 0000000..80f8cfc
--- /dev/null
+++ b/demo/src/demo-presets.test.ts
@@ -0,0 +1,43 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { createFillTextPresetText, fillTextPresets } from './demo-presets'
+
+describe('createFillTextPresetText', () => {
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('returns null for the custom preset', () => {
+    expect(createFillTextPresetText('custom')).toBeNull()
+  })
+
+  it('creates fresh random text from the preset alphabet', () => {
+    let callCount = 0
+    vi.spyOn(globalThis.crypto, 'getRandomValues').mockImplementation(values => {
+      const uint32Values = values as Uint32Array
+
+      for (let index = 0; index < uint32Values.length; index++) {
+        uint32Values[index] = callCount + index
+      }
+
+      callCount += 1
+      return values
+    })
+
+    const preset = fillTextPresets.find(candidate => candidate.id === 'hex-random')
+    if (preset?.id !== 'hex-random') {
+      throw new Error('Expected hex-random preset')
+    }
+
+    const firstText = createFillTextPresetText('hex-random')
+    const secondText = createFillTextPresetText('hex-random')
+
+    expect(firstText).not.toBeNull()
+    expect(secondText).not.toBeNull()
+    expect(firstText).toHaveLength(preset.length)
+    expect(secondText).toHaveLength(preset.length)
+    expect(firstText).not.toBe(secondText)
+    expect([...firstText!].every(character => preset.alphabet.includes(character))).toBe(true)
+    expect([...secondText!].every(character => preset.alphabet.includes(character))).toBe(true)
+  })
+})
diff --git a/demo/src/demo-presets.ts b/demo/src/demo-presets.ts
new file mode 100644
index 0000000..866b0ea
--- /dev/null
+++ b/demo/src/demo-presets.ts
@@ -0,0 +1,125 @@
+import type { PolygonShape } from 'shape-text'
+
+export type GeometryPresetId = 'custom' | 'digit-two' | 'rectangle-wide'
+export type FillPresetId =
+  | 'custom'
+  | 'ascii-random'
+  | 'binary-random'
+  | 'hex-random'
+  | 'octal-random'
+  | 'symbol-random'
+
+export const defaultParagraphText = [
+  'Shape paragraph lets a paragraph travel inside a silhouette instead of wrapping around a float.',
+  'Use geometry input when the shape already exists, or value-derived input when the shape should come from text like 23.',
+  'The same layout engine then turns that source into SVG lines or max-fill decorative coverage.',
+].join(' ')
+
+function createDigitTwoPolygon(width: number, height: number) {
+  return [
+    { x: width * 0.12, y: height * 0.1 },
+    { x: width * 0.34, y: 0 },
+    { x: width * 0.72, y: height * 0.02 },
+    { x: width * 0.9, y: height * 0.16 },
+    { x: width * 0.88, y: height * 0.32 },
+    { x: width * 0.74, y: height * 0.44 },
+    { x: width * 0.5, y: height * 0.57 },
+    { x: width * 0.26, y: height * 0.72 },
+    { x: width * 0.14, y: height * 0.86 },
+    { x: width * 0.88, y: height * 0.86 },
+    { x: width * 0.86, y: height },
+    { x: 0, y: height },
+    { x: 0, y: height * 0.78 },
+    { x: width * 0.12, y: height * 0.64 },
+    { x: width * 0.35, y: height * 0.5 },
+    { x: width * 0.62, y: height * 0.35 },
+    { x: width * 0.74, y: height * 0.26 },
+    { x: width * 0.72, y: height * 0.14 },
+    { x: width * 0.58, y: height * 0.08 },
+    { x: width * 0.34, y: height * 0.08 },
+  ]
+}
+
+function getRandomUint32Values(length: number) {
+  if (typeof globalThis.crypto?.getRandomValues === 'function') {
+    return globalThis.crypto.getRandomValues(new Uint32Array(length))
+  }
+
+  const values = new Uint32Array(length)
+  for (let index = 0; index < length; index++) {
+    values[index] = Math.floor(Math.random() * 0x100000000)
+  }
+
+  return values
+}
+
+export const geometryPresets = [
+  {
+    id: 'digit-two',
+    label: 'Digit two polygon',
+    createShape: (): PolygonShape => ({
+      kind: 'polygon',
+      points: createDigitTwoPolygon(340, 460),
+    }),
+  },
+  {
+    id: 'rectangle-wide',
+    label: 'Wide rectangle',
+    createShape: (): PolygonShape => ({
+      kind: 'polygon',
+      points: [
+        { x: 0, y: 0 },
+        { x: 360, y: 0 },
+        { x: 360, y: 320 },
+        { x: 0, y: 320 },
+      ],
+    }),
+  },
+] as const satisfies ReadonlyArray<{
+  id: GeometryPresetId
+  label: string
+  createShape: () => PolygonShape
+}>
+
+export const fillTextPresets = [
+  { id: 'custom', label: 'Custom' },
+  {
+    id: 'ascii-random',
+    label: 'ASCII',
+    alphabet: 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789!@#$%^&*()[]{}<>?/|+-=',
+    length: 96,
+  },
+  { id: 'binary-random', label: 'BINARY', alphabet: '01', length: 128 },
+  { id: 'hex-random', label: 'HEX', alphabet: '0123456789ABCDEF', length: 112 },
+  { id: 'octal-random', label: 'OCTAL', alphabet: '01234567', length: 120 },
+  { id: 'symbol-random', label: 'SYMBOL', alphabet: '<>[]{}()/\\|+-=_*#@~', length: 96 },
+] as const
+
+function serializePoints(points: PolygonShape['points']) {
+  return points.map(point => `${point.x},${point.y}`).join(';')
+}
+
+export function createGeometryShapeFromPreset(id: GeometryPresetId): PolygonShape {
+  return (geometryPresets.find(preset => preset.id === id) ?? geometryPresets[0]).createShape()
+}
+
+export function identifyGeometryPresetId(shape: PolygonShape): GeometryPresetId {
+  const serializedPoints = serializePoints(shape.points)
+  return geometryPresets.find(preset => serializePoints(preset.createShape().points) === serializedPoints)?.id ?? 'custom'
+}
+
+export function createFillTextPresetText(id: FillPresetId): string | null {
+  const preset = fillTextPresets.find(candidate => candidate.id === id) ?? fillTextPresets[0]
+  if (preset.id === 'custom') {
+    return null
+  }
+
+  const values = getRandomUint32Values(preset.length)
+  let text = ''
+
+  for (let index = 0; index < preset.length; index++) {
+    text += preset.alphabet[values[index]! % preset.alphabet.length]!
+  }
+
+  return text
+}
diff --git a/demo/src/main.tsx b/demo/src/main.tsx
new file mode 100644
index 0000000..ed569c0
--- /dev/null
+++ b/demo/src/main.tsx
@@ -0,0 +1,18 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+
+import { App } from './app'
+import './base.css'
+import './workbench.css'
+
+const rootElement = document.getElementById('root')
+
+if (rootElement === null) {
+  throw new Error('Missing #root element')
+}
+
+createRoot(rootElement).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+)
diff --git a/demo/src/merge-demo-layout-payload.ts b/demo/src/merge-demo-layout-payload.ts
new file mode 100644
index 0000000..289cb66
--- /dev/null
+++ b/demo/src/merge-demo-layout-payload.ts
@@ -0,0 +1,147 @@
+import type { DemoRequest } from './demo-model'
+
+import { createDefaultGeometryShape, createDefaultTextMaskShape } from './demo-model'
+import { assertObject, hasOwnProperty, readFiniteNumber } from './demo-payload-primitives'
+
+export function mergeDemoLayoutPayload(target: DemoRequest, layout: Record<string, unknown>) {
+  if (hasOwnProperty(layout, 'text')) {
+    target.layout.text = String(layout.text)
+  }
+
+  if (hasOwnProperty(layout, 'lineHeight')) {
+    target.layout.lineHeight = readFiniteNumber(layout.lineHeight, 'payload.layout.lineHeight')
+  }
+
+  if (hasOwnProperty(layout, 'autoFill')) {
+    target.layout.autoFill = Boolean(layout.autoFill)
+  }
+
+  if (hasOwnProperty(layout, 'minSlotWidth')) {
+    target.layout.minSlotWidth =
+      layout.minSlotWidth === undefined
+        ? undefined
+        : readFiniteNumber(layout.minSlotWidth, 'payload.layout.minSlotWidth')
+  }
+
+  if (hasOwnProperty(layout, 'textStyle')) {
+    const textStyle = assertObject(layout.textStyle, 'payload.layout.textStyle')
+    target.layout.textStyle = {
+      family: hasOwnProperty(textStyle, 'family')
+        ? String(textStyle.family)
+        : target.layout.textStyle.family,
+      size: hasOwnProperty(textStyle, 'size')
+        ? readFiniteNumber(textStyle.size, 'payload.layout.textStyle.size')
+        : target.layout.textStyle.size,
+      weight:
+        typeof textStyle.weight === 'string' || typeof textStyle.weight === 'number'
+          ? textStyle.weight
+          : target.layout.textStyle.weight,
+      style: hasOwnProperty(textStyle, 'style')
+        ? textStyle.style === 'italic' || textStyle.style === 'oblique'
+          ? textStyle.style
+          : 'normal'
+        : target.layout.textStyle.style,
+      color: hasOwnProperty(textStyle, 'color')
+        ? String(textStyle.color)
+        : target.layout.textStyle.color,
+    }
+  }
+
+  if (!hasOwnProperty(layout, 'shape')) {
+    return
+  }
+
+  const shape = assertObject(layout.shape, 'payload.layout.shape')
+  const shapeKind =
+    shape.kind === 'text-mask' || shape.kind === 'polygon' ? shape.kind : target.layout.shape.kind
+
+  if (shapeKind === 'text-mask') {
+    const baseShape =
+      target.layout.shape.kind === 'text-mask' ? target.layout.shape : createDefaultTextMaskShape()
+    const size =
+      hasOwnProperty(shape, 'size') && shape.size !== undefined
+        ? assertObject(shape.size, 'payload.layout.shape.size')
+        : {}
+    const nextSizeMode = hasOwnProperty(size, 'mode')
+      ? size.mode === 'fixed'
+        ? 'fixed'
+        : 'fit-content'
+      : baseShape.size?.mode === 'fixed'
+        ? 'fixed'
+        : 'fit-content'
+    const nextPadding = hasOwnProperty(size, 'padding')
+      ? size.padding === undefined
+        ? undefined
+        : readFiniteNumber(size.padding, 'payload.layout.shape.size.padding', true)
+      : baseShape.size?.padding
+
+    target.layout.shape = {
+      kind: 'text-mask',
+      text: hasOwnProperty(shape, 'text') ? String(shape.text) : baseShape.text,
+      font: hasOwnProperty(shape, 'font') ? String(shape.font) : baseShape.font,
+      size:
+        nextSizeMode === 'fixed'
+          ? {
+              mode: 'fixed',
+              width: hasOwnProperty(size, 'width')
+                ? readFiniteNumber(size.width, 'payload.layout.shape.size.width')
+                : baseShape.size?.mode === 'fixed'
+                  ? baseShape.size.width
+                  : 520,
+              height: hasOwnProperty(size, 'height')
+                ? readFiniteNumber(size.height, 'payload.layout.shape.size.height')
+                : baseShape.size?.mode === 'fixed'
+                  ? baseShape.size.height
+                  : 260,
+              padding: nextPadding,
+            }
+          : {
+              mode: 'fit-content',
+              padding: nextPadding,
+            },
+      shapeTextMode: hasOwnProperty(shape, 'shapeTextMode')
+        ? shape.shapeTextMode === 'per-character'
+          ? 'per-character'
+          : 'whole-text'
+        : baseShape.shapeTextMode,
+      maskScale: hasOwnProperty(shape, 'maskScale')
+        ? shape.maskScale === undefined
+          ? undefined
+          : readFiniteNumber(shape.maskScale, 'payload.layout.shape.maskScale')
+        : baseShape.maskScale,
+      alphaThreshold: hasOwnProperty(shape, 'alphaThreshold')
+        ? shape.alphaThreshold === undefined
+          ? undefined
+          : readFiniteNumber(shape.alphaThreshold, 'payload.layout.shape.alphaThreshold', true)
+        : baseShape.alphaThreshold,
+    }
+
+    return
+  }
+
+  const baseShape =
+    target.layout.shape.kind === 'polygon'
+      ? target.layout.shape
+      : createDefaultGeometryShape('digit-two')
+
+  if (!hasOwnProperty(shape, 'points')) {
+    target.layout.shape = baseShape
+    return
+  }
+
+  const points = Array.isArray(shape.points) ? shape.points : null
+  if (points === null || points.length < 3) {
+    throw new Error('payload.layout.shape.points must contain at least 3 points')
+  }
+
+  target.layout.shape = {
+    kind: 'polygon',
+    points: points.map((point, index) => {
+      const value = assertObject(point, `payload.layout.shape.points[${index}]`)
+      return {
+        x: readFiniteNumber(value.x, `payload.layout.shape.points[${index}].x`, true),
+        y: readFiniteNumber(value.y, `payload.layout.shape.points[${index}].y`, true),
+      }
+    }),
+  }
+}
diff --git a/demo/src/merge-demo-render-payload.ts b/demo/src/merge-demo-render-payload.ts
new file mode 100644
index 0000000..9c1cdf0
--- /dev/null
+++ b/demo/src/merge-demo-render-payload.ts
@@ -0,0 +1,59 @@
+import type { DemoRequest } from './demo-model'
+
+import { assertObject, hasOwnProperty, readFiniteNumber } from './demo-payload-primitives'
+
+export function mergeDemoRenderPayload(target: DemoRequest, render: Record<string, unknown>) {
+  if (hasOwnProperty(render, 'background')) {
+    target.render.background = render.background === undefined ? undefined : String(render.background)
+  }
+
+  if (hasOwnProperty(render, 'padding')) {
+    target.render.padding = readFiniteNumber(render.padding, 'payload.render.padding', true)
+  }
+
+  if (hasOwnProperty(render, 'showShape')) {
+    target.render.showShape = Boolean(render.showShape)
+  }
+
+  if (!hasOwnProperty(render, 'shapeStyle')) {
+    return
+  }
+
+  const shapeStyle =
+    render.shapeStyle === undefined ? {} : assertObject(render.shapeStyle, 'payload.render.shapeStyle')
+  const shadow =
+    shapeStyle.shadow === undefined || shapeStyle.shadow === null
+      ? null
+      : assertObject(shapeStyle.shadow, 'payload.render.shapeStyle.shadow')
+
+  target.render.shapeStyle = {
+    backgroundColor: hasOwnProperty(shapeStyle, 'backgroundColor')
+      ? String(shapeStyle.backgroundColor)
+      : target.render.shapeStyle?.backgroundColor,
+    borderColor: hasOwnProperty(shapeStyle, 'borderColor')
+      ? String(shapeStyle.borderColor)
+      : target.render.shapeStyle?.borderColor,
+    borderWidth: hasOwnProperty(shapeStyle, 'borderWidth')
+      ? readFiniteNumber(shapeStyle.borderWidth, 'payload.render.shapeStyle.borderWidth', true)
+      : target.render.shapeStyle?.borderWidth,
+    shadow:
+      hasOwnProperty(shapeStyle, 'shadow')
+        ? shadow === null
+          ? undefined
+          : {
+              color: hasOwnProperty(shadow, 'color')
+                ? String(shadow.color)
+                : target.render.shapeStyle?.shadow?.color ?? 'rgba(15, 23, 42, 0.22)',
+              blur: hasOwnProperty(shadow, 'blur')
+                ? readFiniteNumber(shadow.blur, 'payload.render.shapeStyle.shadow.blur', true)
+                : target.render.shapeStyle?.shadow?.blur ?? 8,
+              offsetX: hasOwnProperty(shadow, 'offsetX')
+                ? readFiniteNumber(shadow.offsetX, 'payload.render.shapeStyle.shadow.offsetX', true)
+                : target.render.shapeStyle?.shadow?.offsetX ?? 0,
+              offsetY: hasOwnProperty(shadow, 'offsetY')
+                ? readFiniteNumber(shadow.offsetY, 'payload.render.shapeStyle.shadow.offsetY', true)
+                : target.render.shapeStyle?.shadow?.offsetY ?? 8,
+            }
+        : target.render.shapeStyle?.shadow,
+  }
+}
diff --git a/demo/src/use-rendered-demo-request.ts b/demo/src/use-rendered-demo-request.ts
new file mode 100644
index 0000000..49c1da2
--- /dev/null
+++ b/demo/src/use-rendered-demo-request.ts
@@ -0,0 +1,49 @@
+import { useEffect, useState } from 'react'
+
+import { createCanvasTextMeasurer, layoutTextInShape, renderLayoutToSvg, type ShapeTextLayout } from 'shape-text'
+
+import type { DemoRequest } from './demo-model'
+
+const measurer = createCanvasTextMeasurer()
+
+type RenderedDemoRequest = {
+  layout: ShapeTextLayout | null
+  svg: string
+  error: string
+}
+
+function renderDemoRequest(request: DemoRequest): RenderedDemoRequest {
+  try {
+    const layout = layoutTextInShape({
+      ...request.layout,
+      measurer,
+    })
+
+    return {
+      layout,
+      svg: renderLayoutToSvg(layout, request.render),
+      error: '',
+    }
+  } catch (error) {
+    return {
+      layout: null,
+      svg: '',
+      error: error instanceof Error ? error.message : String(error),
+    }
+  }
+}
+
+export function useRenderedDemoRequest(request: DemoRequest) {
+  const [rendered, setRendered] = useState<RenderedDemoRequest>(() => renderDemoRequest(request))
+
+  useEffect(() => {
+    const nextRendered = renderDemoRequest(request)
+    setRendered(current =>
+      nextRendered.error.length === 0 || current.svg.length === 0
+        ? nextRendered
+        : { ...current, error: nextRendered.error },
+    )
+  }, [request])
+
+  return rendered
+}
diff --git a/demo/src/use-shape-paragraph-workbench.ts b/demo/src/use-shape-paragraph-workbench.ts
new file mode 100644
index 0000000..606349c
--- /dev/null
+++ b/demo/src/use-shape-paragraph-workbench.ts
@@ -0,0 +1,193 @@
+import { useRef, useState } from 'react'
+
+import {
+  cloneDemoRequest,
+  createDefaultDemoRequest,
+  createDefaultGeometryShape,
+  createDefaultTextMaskShape,
+  deriveShapeSource,
+  type DemoRequest,
+  type ShapeSource,
+} from './demo-model'
+import {
+  identifyGeometryPresetId,
+  createFillTextPresetText,
+  type FillPresetId,
+  type GeometryPresetId,
+} from './demo-presets'
+
+export function useShapeParagraphWorkbench() {
+  const [request, setRequest] = useState(createDefaultDemoRequest)
+  const [fillPresetId, setFillPresetId] = useState<FillPresetId>('custom')
+  const [geometryPresetId, setGeometryPresetId] = useState<GeometryPresetId>('digit-two')
+  const polygonShapeRef = useRef(createDefaultGeometryShape('digit-two'))
+  const textMaskShapeRef = useRef(createDefaultTextMaskShape())
+
+  function syncWorkbenchState(
+    nextRequest: DemoRequest,
+    nextFillPresetId: FillPresetId = fillPresetId,
+  ) {
+    setRequest(nextRequest)
+    setFillPresetId(nextFillPresetId)
+    if (nextRequest.layout.shape.kind === 'polygon') {
+      polygonShapeRef.current = nextRequest.layout.shape
+      setGeometryPresetId(identifyGeometryPresetId(nextRequest.layout.shape))
+      return
+    }
+
+    textMaskShapeRef.current = nextRequest.layout.shape
+  }
+
+  function applyRequest(nextRequest: DemoRequest) {
+    syncWorkbenchState(nextRequest, 'custom')
+  }
+
+  function updateRequest(
+    update: (current: DemoRequest) => DemoRequest,
+    nextFillPresetId: FillPresetId = fillPresetId,
+  ) {
+    syncWorkbenchState(update(cloneDemoRequest(request)), nextFillPresetId)
+  }
+
+  return {
+    request,
+    fillPresetId,
+    geometryPresetId,
+    shapeSource: deriveShapeSource(request.layout.shape) as ShapeSource,
+    applyRequest,
+    setText(text: string) {
+      updateRequest(current => ({ ...current, layout: { ...current.layout, text } }), 'custom')
+    },
+    setFillPreset(id: FillPresetId) {
+      const nextText = createFillTextPresetText(id)
+      if (nextText === null) {
+        setFillPresetId('custom')
+        return
+      }
+
+      updateRequest(current => ({ ...current, layout: { ...current.layout, text: nextText } }), id)
+    },
+    rerollFillPreset() {
+      if (fillPresetId === 'custom') {
+        return
+      }
+
+      const nextText = createFillTextPresetText(fillPresetId)
+      if (nextText === null) {
+        return
+      }
+
+      updateRequest(current => ({ ...current, layout: { ...current.layout, text: nextText } }), fillPresetId)
+    },
+    setShapeSource(source: ShapeSource) {
+      updateRequest(current => ({
+        ...current,
+        layout: {
+          ...current.layout,
+          shape: source === 'geometry' ? polygonShapeRef.current : textMaskShapeRef.current,
+        },
+      }))
+    },
+    setGeometryPreset(id: GeometryPresetId) {
+      if (id === 'custom') {
+        setGeometryPresetId('custom')
+        return
+      }
+
+      const nextShape = createDefaultGeometryShape(id)
+      polygonShapeRef.current = nextShape
+      setGeometryPresetId(id)
+      if (request.layout.shape.kind === 'polygon') {
+        updateRequest(current => ({ ...current, layout: { ...current.layout, shape: nextShape } }))
+      }
+    },
+    setTextSize(size: number) {
+      updateRequest(current => ({ ...current, layout: { ...current.layout, textStyle: { ...current.layout.textStyle, size } } }))
+    },
+    setLineHeight(lineHeight: number) {
+      updateRequest(current => ({ ...current, layout: { ...current.layout, lineHeight } }))
+    },
+    setTextWeight(weight: string) {
+      updateRequest(current => ({ ...current, layout: { ...current.layout, textStyle: { ...current.layout.textStyle, weight } } }))
+    },
+    setTextItalic(textItalic: boolean) {
+      updateRequest(current => ({
+        ...current,
+        layout: { ...current.layout, textStyle: { ...current.layout.textStyle, style: textItalic ? 'italic' : 'normal' } },
+      }))
+    },
+    setTextColor(color: string) {
+      updateRequest(current => ({ ...current, layout: { ...current.layout, textStyle: { ...current.layout.textStyle, color } } }))
+    },
+    setAutoFill(autoFill: boolean) {
+      updateRequest(current => ({ ...current, layout: { ...current.layout, autoFill } }))
+    },
+    setShapeText(text: string) {
+      if (request.layout.shape.kind !== 'text-mask') {
+        return
+      }
+
+      updateRequest(current => ({
+        ...current,
+        layout: { ...current.layout, shape: { ...current.layout.shape, text } },
+      }))
+    },
+    setShapeTextMode(mode: 'whole-text' | 'per-character') {
+      if (request.layout.shape.kind !== 'text-mask') {
+        return
+      }
+
+      updateRequest(current => ({
+        ...current,
+        layout: { ...current.layout, shape: { ...current.layout.shape, shapeTextMode: mode } },
+      }))
+    },
+    setShapeSizeMode(mode: 'fit-content' | 'fixed') {
+      if (request.layout.shape.kind !== 'text-mask') {
+        return
+      }
+
+      updateRequest(current => ({
+        ...current,
+        layout: {
+          ...current.layout,
+          shape:
+            mode === 'fixed'
+              ? { ...current.layout.shape, size: { mode: 'fixed', width: 520, height: 260, padding: 10 } }
+              : { ...current.layout.shape, size: { mode: 'fit-content', padding: 10 } },
+        },
+      }))
+    },
+    setShapeFixedDimension(dimension: 'width' | 'height', value: number) {
+      if (request.layout.shape.kind !== 'text-mask' || request.layout.shape.size?.mode !== 'fixed') {
+        return
+      }
+
+      updateRequest(current => {
+        if (current.layout.shape.kind !== 'text-mask' || current.layout.shape.size?.mode !== 'fixed') {
+          return current
+        }
+
+        return {
+          ...current,
+          layout: {
+            ...current.layout,
+            shape: { ...current.layout.shape, size: { ...current.layout.shape.size, [dimension]: value } },
+          },
+        }
+      })
+    },
+    setShowShape(showShape: boolean) {
+      updateRequest(current => ({ ...current, render: { ...current.render, showShape } }))
+    },
+    setShapeFill(backgroundColor: string) {
+      updateRequest(current => ({
+        ...current,
+        render: {
+          ...current.render,
+          shapeStyle: { ...current.render.shapeStyle, backgroundColor },
+        },
+      }))
+    },
+  }
+}
diff --git a/demo/src/workbench.css b/demo/src/workbench.css
new file mode 100644
index 0000000..f18a1bd
--- /dev/null
+++ b/demo/src/workbench.css
@@ -0,0 +1,167 @@
+.app-shell {
+  width: min(1440px, calc(100vw - 32px));
+  margin: 0 auto;
+  padding: 24px 0 40px;
+}
+
+.layout-grid {
+  display: grid;
+  grid-template-columns: minmax(320px, 420px) minmax(0, 1fr);
+  gap: 18px;
+}
+
+.sidebar,
+.main-panel {
+  display: grid;
+  gap: 18px;
+  align-content: start;
+}
+
+.panel {
+  border: 1px solid rgba(132, 151, 168, 0.26);
+  border-radius: 28px;
+  background: rgba(255, 255, 255, 0.82);
+  box-shadow: 0 20px 60px rgba(16, 36, 60, 0.08);
+  padding: 18px;
+}
+
+.hero {
+  margin-bottom: 18px;
+  background: linear-gradient(135deg, rgba(255, 255, 255, 0.9), rgba(233, 242, 249, 0.88));
+}
+
+.eyebrow {
+  margin: 0 0 8px;
+  letter-spacing: 0.14em;
+  text-transform: uppercase;
+  color: #5b728d;
+  font-size: 12px;
+}
+
+h1 {
+  font-size: clamp(32px, 4vw, 48px);
+  line-height: 0.95;
+}
+
+h2 {
+  font-size: 20px;
+}
+
+.hero-copy,
+.panel-heading p,
+.panel-copy,
+.mode-note {
+  color: #53667d;
+  line-height: 1.6;
+}
+
+.panel-heading {
+  display: grid;
+  gap: 6px;
+  margin-bottom: 14px;
+}
+
+.field,
+.checkbox-field {
+  display: grid;
+  gap: 6px;
+  color: #31465d;
+}
+
+.field span {
+  font-size: 13px;
+}
+
+.field-grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 12px;
+  margin-top: 14px;
+}
+
+.checkbox-field {
+  align-content: end;
+}
+
+.payload-textarea {
+  min-height: 240px;
+  font: 12px/1.6 ui-monospace, "Cascadia Code", monospace;
+}
+
+.button-row {
+  display: flex;
+  gap: 10px;
+  align-items: center;
+  flex-wrap: wrap;
+  margin-top: 14px;
+}
+
+.stage-panel {
+  min-height: 0;
+}
+
+.stage-viewport {
+  min-height: 540px;
+  max-height: 74vh;
+  margin-top: 14px;
+  padding: 16px;
+  overflow: auto;
+  border-radius: 24px;
+  background: rgba(247, 245, 238, 0.86);
+  border: 1px solid rgba(173, 183, 191, 0.6);
+}
+
+.stage-scale-box {
+  position: relative;
+}
+
+.stage {
+  width: max-content;
+  transform-origin: top left;
+}
+
+.stage svg {
+  display: block;
+}
+
+.zoom-label {
+  font-weight: 700;
+}
+
+.summary-panel dt {
+  font-size: 12px;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: #66788f;
+}
+
+.summary-panel dd {
+  margin: 4px 0 0;
+  font-weight: 700;
+}
+
+.summary-grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 14px;
+}
+
+.error-box {
+  margin-top: 14px;
+  padding: 12px 14px;
+  border-radius: 16px;
+  background: #fff1f2;
+  color: #b42318;
+  white-space: pre-wrap;
+}
+
+@media (max-width: 1080px) {
+  .layout-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .field-grid,
+  .summary-grid {
+    grid-template-columns: 1fr;
+  }
+}
diff --git a/demo/vite.config.ts b/demo/vite.config.ts
new file mode 100644
index 0000000..8b663b2
--- /dev/null
+++ b/demo/vite.config.ts
@@ -0,0 +1,32 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import react from '@vitejs/plugin-react'
+import { defineConfig } from 'vite'
+
+const configDir = path.dirname(fileURLToPath(import.meta.url))
+const rootDir = path.resolve(configDir, '..')
+const port = Number(process.env.PORT ?? 4173)
+
+export default defineConfig({
+  root: configDir,
+  cacheDir: path.resolve(rootDir, 'node_modules/.vite-demo'),
+  plugins: [react()],
+  resolve: {
+    alias: {
+      'shape-text': path.resolve(rootDir, 'src/index.ts'),
+    },
+  },
+  server: {
+    host: '127.0.0.1',
+    port,
+  },
+  preview: {
+    host: '127.0.0.1',
+    port,
+  },
+  build: {
+    outDir: path.resolve(configDir, 'dist'),
+    emptyOutDir: true,
+  },
+})
diff --git a/e2e/fixtures/demo-fill-presets.js b/e2e/fixtures/demo-fill-presets.js
deleted file mode 100644
index cd29369..0000000
--- a/e2e/fixtures/demo-fill-presets.js
+++ /dev/null
@@ -1,52 +0,0 @@
-function createSeededRandom(seed) {
-  let value = seed >>> 0
-  return () => {
-    value = (value * 1664525 + 1013904223) >>> 0
-    return value / 0x100000000
-  }
-}
-
-function createRandomText(alphabet, length, seed) {
-  const random = createSeededRandom(seed)
-  let text = ''
-
-  for (let index = 0; index < length; index++) {
-    const nextIndex = Math.floor(random() * alphabet.length)
-    text += alphabet[nextIndex]
-  }
-
-  return text
-}
-
-export const fillTextPresets = [
-  { id: 'custom', label: 'Custom' },
-  { id: 'ascii-random', label: 'ASCII', alphabet: 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789!@#$%^&*()[]{}<>?/|+-=', length: 96, seed: 0x41534349 },
-  { id: 'binary-random', label: 'BINARY', alphabet: '01', length: 128, seed: 0x42494e41 },
-  { id: 'hex-random', label: 'HEX', alphabet: '0123456789ABCDEF', length: 112, seed: 0x48455821 },
-  { id: 'octal-random', label: 'OCTAL', alphabet: '01234567', length: 120, seed: 0x4f435441 },
-  { id: 'symbol-random', label: 'SYMBOL', alphabet: '<>[]{}()/\\|+-=_*#@~', length: 96, seed: 0x53594d42 },
-]
-
-export function findFillTextPresetById(id) {
-  return fillTextPresets.find(preset => preset.id === id) ?? fillTextPresets[0]
-}
-
-export function identifyFillTextPresetId(text) {
-  for (let index = 0; index < fillTextPresets.length; index++) {
-    const preset = fillTextPresets[index]
-    if (preset.id !== 'custom' && resolveFillTextPresetText(preset.id) === text) {
-      return preset.id
-    }
-  }
-
-  return 'custom'
-}
-
-export function resolveFillTextPresetText(id) {
-  const preset = findFillTextPresetById(id)
-  if (preset.id === 'custom') {
-    return null
-  }
-
-  return createRandomText(preset.alphabet, preset.length, preset.seed)
-}
diff --git a/e2e/fixtures/demo-payload-helpers.js b/e2e/fixtures/demo-payload-helpers.js
deleted file mode 100644
index 92ac7bb..0000000
--- a/e2e/fixtures/demo-payload-helpers.js
+++ /dev/null
@@ -1,268 +0,0 @@
-function clonePoints(points) {
-  return points.map(point => ({ x: point.x, y: point.y }))
-}
-
-function cloneDemoState(state) {
-  return {
-    ...state,
-    polygonPoints: clonePoints(state.polygonPoints),
-  }
-}
-
-function assertFiniteNumber(value, label) {
-  if (!Number.isFinite(value)) {
-    throw new Error(`${label} must be a finite number`)
-  }
-
-  return value
-}
-
-function assertPositiveFiniteNumber(value, label) {
-  if (!Number.isFinite(value) || value <= 0) {
-    throw new Error(`${label} must be a finite positive number`)
-  }
-
-  return value
-}
-
-function hasOwnProperty(value, key) {
-  return Object.prototype.hasOwnProperty.call(value, key)
-}
-
-function normalizeTextMaskSize(size) {
-  if (size === undefined) {
-    return { mode: 'fit-content' }
-  }
-
-  if (size === null || typeof size !== 'object' || Array.isArray(size)) {
-    throw new Error('layout.shape.size must be an object')
-  }
-
-  const mode = size.mode ?? 'fit-content'
-  if (mode !== 'fit-content' && mode !== 'fixed') {
-    throw new Error('layout.shape.size.mode must be fit-content or fixed')
-  }
-
-  const padding =
-    size.padding === undefined
-      ? undefined
-      : assertFiniteNumber(Number(size.padding), 'layout.shape.size.padding')
-
-  if (padding !== undefined && padding < 0) {
-    throw new Error('layout.shape.size.padding must be a finite non-negative number')
-  }
-
-  if (mode === 'fixed') {
-    return {
-      mode,
-      width: assertPositiveFiniteNumber(Number(size.width), 'layout.shape.size.width'),
-      height: assertPositiveFiniteNumber(Number(size.height), 'layout.shape.size.height'),
-      padding,
-    }
-  }
-
-  return {
-    mode,
-    padding,
-  }
-}
-
-function normalizeShape(shape) {
-  if (shape.kind === 'text-mask') {
-    if (hasOwnProperty(shape, 'width') || hasOwnProperty(shape, 'height') || hasOwnProperty(shape, 'padding')) {
-      throw new Error('layout.shape.width, height, and padding moved to layout.shape.size')
-    }
-
-    const shapeTextMode = shape.shapeTextMode ?? 'whole-text'
-    if (shapeTextMode !== 'whole-text' && shapeTextMode !== 'per-character') {
-      throw new Error('layout.shape.shapeTextMode must be whole-text or per-character')
-    }
-
-    return {
-      kind: 'text-mask',
-      text: String(shape.text),
-      font: String(shape.font),
-      size: normalizeTextMaskSize(shape.size),
-      shapeTextMode,
-      maskScale:
-        shape.maskScale === undefined
-          ? undefined
-          : assertFiniteNumber(Number(shape.maskScale), 'layout.shape.maskScale'),
-      alphaThreshold:
-        shape.alphaThreshold === undefined
-          ? undefined
-          : assertFiniteNumber(Number(shape.alphaThreshold), 'layout.shape.alphaThreshold'),
-    }
-  }
-
-  if (!Array.isArray(shape.points) || shape.points.length < 3) {
-    throw new Error('layout.shape.points must contain at least 3 points')
-  }
-
-  return {
-    kind: 'polygon',
-    points: shape.points.map((point, index) => ({
-      x: assertFiniteNumber(Number(point.x), `layout.shape.points[${index}].x`),
-      y: assertFiniteNumber(Number(point.y), `layout.shape.points[${index}].y`),
-    })),
-  }
-}
-
-function buildTextMaskSize(state) {
-  if (state.shapeSizeMode === 'fixed') {
-    return {
-      mode: 'fixed',
-      width: state.shapeWidth,
-      height: state.shapeHeight,
-      padding: state.shapePadding,
-    }
-  }
-
-  return {
-    mode: 'fit-content',
-    padding: state.shapePadding,
-  }
-}
-
-export function buildDemoPayload(state) {
-  const shape =
-    state.shapeKind === 'text-mask'
-      ? {
-          kind: 'text-mask',
-          text: state.shapeText,
-          font: state.shapeFont,
-          size: buildTextMaskSize(state),
-          shapeTextMode: state.shapeTextMode,
-          maskScale: state.shapeMaskScale,
-          alphaThreshold: state.shapeAlphaThreshold,
-        }
-      : {
-          kind: 'polygon',
-          points: clonePoints(state.polygonPoints),
-        }
-
-  return {
-    layout: {
-      text: state.text,
-      textStyle: {
-        family: '"Helvetica Neue", Arial, sans-serif',
-        size: state.textSize,
-        weight: state.textWeight,
-        style: state.textItalic ? 'italic' : 'normal',
-        color: state.textColor,
-      },
-      lineHeight: state.lineHeight,
-      shape,
-      minSlotWidth: state.minSlotWidth ?? (state.fillStrategy === 'max' ? 8 : 24),
-      autoFill: state.autoFill,
-      autoFillMode: state.autoFillMode,
-      fillStrategy: state.fillStrategy,
-    },
-    render: {
-      background: state.background,
-      shapeStyle: {
-        backgroundColor: state.shapeFill,
-        borderColor: state.shapeBorderColor,
-        borderWidth: state.shapeBorderWidth,
-        shadow: state.shapeShadow
-          ? {
-              color: 'rgba(15, 23, 42, 0.22)',
-              blur: 6,
-              offsetX: 0,
-              offsetY: 6,
-            }
-          : undefined,
-      },
-      showShape: state.showShape,
-      padding: state.renderPadding,
-    },
-  }
-}
-
-export function serializeDemoPayload(state) {
-  return JSON.stringify(buildDemoPayload(state), null, 2)
-}
-
-export function applyDemoPayloadToState(state, payload) {
-  if (payload === null || typeof payload !== 'object') {
-    throw new Error('payload must be an object')
-  }
-
-  const layout = payload.layout
-  const render = payload.render
-  if (layout === null || typeof layout !== 'object') {
-    throw new Error('payload.layout must be an object')
-  }
-  if (render === null || typeof render !== 'object') {
-    throw new Error('payload.render must be an object')
-  }
-
-  const nextState = cloneDemoState(state)
-
-  nextState.text = String(layout.text ?? nextState.text)
-  nextState.lineHeight = assertFiniteNumber(Number(layout.lineHeight ?? nextState.lineHeight), 'layout.lineHeight')
-  nextState.minSlotWidth =
-    layout.minSlotWidth === undefined
-      ? nextState.minSlotWidth
-      : assertFiniteNumber(Number(layout.minSlotWidth), 'layout.minSlotWidth')
-  nextState.autoFill = Boolean(layout.autoFill ?? nextState.autoFill)
-  nextState.fillStrategy =
-    layout.fillStrategy === undefined ? nextState.fillStrategy : layout.fillStrategy === 'max' ? 'max' : 'flow'
-  nextState.autoFillMode =
-    layout.autoFillMode === undefined
-      ? nextState.autoFillMode
-      : layout.autoFillMode === 'dense' || layout.autoFillMode === 'stream'
-        ? layout.autoFillMode
-        : 'words'
-
-  if (layout.textStyle !== null && typeof layout.textStyle === 'object') {
-    nextState.textSize = assertFiniteNumber(
-      Number(layout.textStyle.size ?? nextState.textSize),
-      'layout.textStyle.size',
-    )
-    nextState.textWeight = Number(layout.textStyle.weight ?? nextState.textWeight)
-    nextState.textItalic =
-      layout.textStyle.style === undefined
-        ? nextState.textItalic
-        : String(layout.textStyle.style) !== 'normal'
-    nextState.textColor = String(layout.textStyle.color ?? nextState.textColor)
-  }
-
-  const shape = normalizeShape(layout.shape)
-  nextState.shapeKind = shape.kind
-  if (shape.kind === 'text-mask') {
-    nextState.shapeText = shape.text
-    nextState.shapeFont = shape.font
-    nextState.shapeSizeMode = shape.size.mode === 'fixed' ? 'fixed' : 'fit-content'
-    if (shape.size.mode === 'fixed') {
-      nextState.shapeWidth = shape.size.width
-      nextState.shapeHeight = shape.size.height
-    }
-    nextState.shapeTextMode = shape.shapeTextMode
-    nextState.shapePadding = shape.size.padding ?? 0
-    nextState.shapeMaskScale = shape.maskScale ?? 2
-    nextState.shapeAlphaThreshold = shape.alphaThreshold
-  } else {
-    nextState.polygonPoints = shape.points
-  }
-
-  nextState.background = String(render.background ?? nextState.background)
-  nextState.showShape = Boolean(render.showShape ?? nextState.showShape)
-  nextState.renderPadding = assertFiniteNumber(
-    Number(render.padding ?? nextState.renderPadding),
-    'render.padding',
-  )
-
-  if (render.shapeStyle !== null && typeof render.shapeStyle === 'object') {
-    nextState.shapeFill = String(render.shapeStyle.backgroundColor ?? nextState.shapeFill)
-    nextState.shapeBorderColor = String(render.shapeStyle.borderColor ?? nextState.shapeBorderColor)
-    nextState.shapeBorderWidth = assertFiniteNumber(
-      Number(render.shapeStyle.borderWidth ?? nextState.shapeBorderWidth),
-      'render.shapeStyle.borderWidth',
-    )
-    nextState.shapeShadow = render.shapeStyle.shadow !== undefined
-  }
-
-  Object.assign(state, nextState)
-  state.polygonPoints = nextState.polygonPoints
-}
diff --git a/e2e/fixtures/demo-scenarios.js b/e2e/fixtures/demo-scenarios.js
deleted file mode 100644
index 516ff98..0000000
--- a/e2e/fixtures/demo-scenarios.js
+++ /dev/null
@@ -1,80 +0,0 @@
-const defaultParagraph = [
-  'Shape text lets a paragraph travel inside a silhouette thay vi chi wrap quanh float.',
-  'Ban co the dung no de render layout hinh so 2, badge, logo block, hoac poster typography.',
-  'E2E local o day uu tien deterministic browser path: build dist, import module, render SVG, assert lai state.',
-].join(' ')
-
-function createDigitTwoPolygon(width, height) {
-  return [
-    { x: width * 0.12, y: height * 0.1 },
-    { x: width * 0.34, y: 0 },
-    { x: width * 0.72, y: height * 0.02 },
-    { x: width * 0.9, y: height * 0.16 },
-    { x: width * 0.88, y: height * 0.32 },
-    { x: width * 0.74, y: height * 0.44 },
-    { x: width * 0.5, y: height * 0.57 },
-    { x: width * 0.26, y: height * 0.72 },
-    { x: width * 0.14, y: height * 0.86 },
-    { x: width * 0.88, y: height * 0.86 },
-    { x: width * 0.86, y: height },
-    { x: 0, y: height },
-    { x: 0, y: height * 0.78 },
-    { x: width * 0.12, y: height * 0.64 },
-    { x: width * 0.35, y: height * 0.5 },
-    { x: width * 0.62, y: height * 0.35 },
-    { x: width * 0.74, y: height * 0.26 },
-    { x: width * 0.72, y: height * 0.14 },
-    { x: width * 0.58, y: height * 0.08 },
-    { x: width * 0.34, y: height * 0.08 },
-  ]
-}
-
-export const demoScenarios = {
-  'glyph-two-repeat': {
-    shape: {
-      kind: 'text-mask',
-      text: '23',
-      font: '700 420px Arial',
-      size: {
-        mode: 'fit-content',
-        padding: 10,
-      },
-      shapeTextMode: 'whole-text',
-      maskScale: 2,
-    },
-    autoFill: true,
-    text: 'ONE',
-  },
-  'digit-two-wide': {
-    shape: { kind: 'polygon', points: createDigitTwoPolygon(340, 460) },
-    text: defaultParagraph,
-  },
-  'digit-two-narrow': {
-    shape: { kind: 'polygon', points: createDigitTwoPolygon(240, 460) },
-    text: defaultParagraph,
-  },
-  'rectangle-wide': {
-    shape: {
-      kind: 'polygon',
-      points: [
-        { x: 0, y: 0 },
-        { x: 340, y: 0 },
-        { x: 340, y: 360 },
-        { x: 0, y: 360 },
-      ],
-    },
-    text: defaultParagraph,
-  },
-  'rectangle-narrow': {
-    shape: {
-      kind: 'polygon',
-      points: [
-        { x: 0, y: 0 },
-        { x: 220, y: 0 },
-        { x: 220, y: 360 },
-        { x: 0, y: 360 },
-      ],
-    },
-    text: defaultParagraph,
-  },
-}
diff --git a/e2e/fixtures/demo-svg-viewport-controller.js b/e2e/fixtures/demo-svg-viewport-controller.js
deleted file mode 100644
index faf021d..0000000
--- a/e2e/fixtures/demo-svg-viewport-controller.js
+++ /dev/null
@@ -1,138 +0,0 @@
-const MIN_ZOOM = 0.25
-const MAX_ZOOM = 4
-const ZOOM_STEP = 1.25
-
-function clampZoom(value) {
-  return Math.max(MIN_ZOOM, Math.min(MAX_ZOOM, value))
-}
-
-function parseSvgDimension(svg, attribute) {
-  const attributeValue = Number(svg.getAttribute(attribute))
-  if (Number.isFinite(attributeValue) && attributeValue > 0) {
-    return attributeValue
-  }
-
-  const viewBox = svg.getAttribute('viewBox')
-  if (!viewBox) {
-    return 0
-  }
-
-  const parts = viewBox.split(/\s+/).map(Number)
-  return Number.isFinite(parts[attribute === 'width' ? 2 : 3]) ? parts[attribute === 'width' ? 2 : 3] : 0
-}
-
-function getContentBounds(svg) {
-  const width = parseSvgDimension(svg, 'width')
-  const height = parseSvgDimension(svg, 'height')
-  let left = 0
-  let top = 0
-  let right = width
-  let bottom = height
-
-  try {
-    const box = svg.getBBox()
-    if (Number.isFinite(box.x) && Number.isFinite(box.width)) {
-      left = Math.min(left, box.x)
-      right = Math.max(right, box.x + box.width)
-    }
-    if (Number.isFinite(box.y) && Number.isFinite(box.height)) {
-      top = Math.min(top, box.y)
-      bottom = Math.max(bottom, box.y + box.height)
-    }
-  } catch {
-    // Ignore SVG bbox failures and fall back to declared dimensions.
-  }
-
-  return {
-    left,
-    top,
-    width: right - left,
-    height: bottom - top,
-  }
-}
-
-export function createDemoSvgViewportController({ state, elements }) {
-  let intrinsicSvgWidth = 0
-  let intrinsicSvgHeight = 0
-  let contentOffsetX = 0
-  let contentOffsetY = 0
-
-  function syncZoomLabel() {
-    elements.zoomValue.textContent = `${Math.round(state.stageZoom * 100)}%`
-  }
-
-  function applyZoom() {
-    const svg = elements.stage.querySelector('svg')
-    if (svg instanceof SVGSVGElement) {
-      svg.style.width = `${intrinsicSvgWidth * state.stageZoom}px`
-      svg.style.height = `${intrinsicSvgHeight * state.stageZoom}px`
-      svg.style.marginLeft = `${contentOffsetX * state.stageZoom}px`
-      svg.style.marginTop = `${contentOffsetY * state.stageZoom}px`
-      svg.style.transform = 'none'
-    }
-
-    elements.stage.style.width = `${state.stageSvgWidth * state.stageZoom}px`
-    elements.stage.style.height = `${state.stageSvgHeight * state.stageZoom}px`
-    syncZoomLabel()
-  }
-
-  function syncStageMetrics() {
-    const svg = elements.stage.querySelector('svg')
-    if (!(svg instanceof SVGSVGElement)) {
-      intrinsicSvgWidth = 0
-      intrinsicSvgHeight = 0
-      contentOffsetX = 0
-      contentOffsetY = 0
-      state.stageSvgWidth = 0
-      state.stageSvgHeight = 0
-      elements.stage.style.width = '0px'
-      elements.stage.style.height = '0px'
-      return
-    }
-
-    const bounds = getContentBounds(svg)
-    intrinsicSvgWidth = parseSvgDimension(svg, 'width')
-    intrinsicSvgHeight = parseSvgDimension(svg, 'height')
-    contentOffsetX = Math.max(0, -bounds.left)
-    contentOffsetY = Math.max(0, -bounds.top)
-    state.stageSvgWidth = bounds.width
-    state.stageSvgHeight = bounds.height
-    svg.style.display = 'block'
-    svg.style.transformOrigin = 'top left'
-  }
-
-  return {
-    renderSvg(svgMarkup) {
-      elements.stage.innerHTML = svgMarkup
-      syncStageMetrics()
-      applyZoom()
-    },
-    zoomIn() {
-      state.stageZoom = clampZoom(state.stageZoom * ZOOM_STEP)
-      applyZoom()
-    },
-    zoomOut() {
-      state.stageZoom = clampZoom(state.stageZoom / ZOOM_STEP)
-      applyZoom()
-    },
-    resetZoom() {
-      state.stageZoom = 1
-      applyZoom()
-    },
-    fitZoom() {
-      const width = state.stageSvgWidth
-      const height = state.stageSvgHeight
-      if (width <= 0 || height <= 0) {
-        return
-      }
-
-      const viewportWidth = Math.max(1, elements.stageViewport.clientWidth - 24)
-      const viewportHeight = Math.max(1, elements.stageViewport.clientHeight - 24)
-      state.stageZoom = clampZoom(Math.min(viewportWidth / width, viewportHeight / height))
-      elements.stageViewport.scrollLeft = 0
-      elements.stageViewport.scrollTop = 0
-      applyZoom()
-    },
-    syncZoomLabel,
-  }
-}
diff --git a/e2e/fixtures/demo-ui-controller.js b/e2e/fixtures/demo-ui-controller.js
deleted file mode 100644
index 3c67085..0000000
--- a/e2e/fixtures/demo-ui-controller.js
+++ /dev/null
@@ -1,277 +0,0 @@
-import { layoutTextInShape, renderLayoutToSvg } from '/dist/index.js'
-import {
-  applyDemoPayloadToState,
-  buildDemoPayload,
-  serializeDemoPayload,
-} from './demo-payload-helpers.js'
-import {
-  fillTextPresets,
-  findFillTextPresetById,
-  identifyFillTextPresetId,
-  resolveFillTextPresetText,
-} from './demo-fill-presets.js'
-import { demoScenarios } from './demo-scenarios.js'
-
-export function createDemoUiController({ state, elements, measurer, viewport }) {
-  let hasUserEditedText = false
-  let hasUserEditedShapeText = false
-  let hasPayloadDraftChanges = false
-  let lastCommittedState = cloneStateSnapshot(state)
-  let lastRenderedState = null
-
-  function setPayloadError(message = '') {
-    state.payloadError = message
-    elements.payloadError.textContent = message
-    elements.payloadError.hidden = message.length === 0
-  }
-
-  function syncPresetSelection() {
-    state.fillPresetId = identifyFillTextPresetId(state.text)
-  }
-
-  function cloneStateSnapshot(source) {
-    return {
-      ...source,
-      polygonPoints: source.polygonPoints.map(point => ({ ...point })),
-    }
-  }
-
-  function updateSummary() {
-    const resolvedShapeWidth =
-      state.layout === null ? null : state.layout.compiledShape.bounds.right - state.layout.compiledShape.bounds.left
-    const resolvedShapeHeight =
-      state.layout === null ? null : state.layout.compiledShape.bounds.bottom - state.layout.compiledShape.bounds.top
-
-    elements.summary.textContent = JSON.stringify(
-      {
-        scenario: state.scenario,
-        shapeKind: state.shapeKind,
-        shapeText: state.shapeText,
-        shapeTextMode: state.shapeTextMode,
-        shapeSizeMode: state.shapeSizeMode,
-        resolvedShapeWidth,
-        resolvedShapeHeight,
-        fillPresetId: state.fillPresetId,
-        autoFill: state.layout?.autoFill ?? false,
-        autoFillMode: state.layout?.autoFillMode ?? null,
-        fillStrategy: state.layout?.fillStrategy ?? null,
-        lineCount: state.layout?.lines.length ?? 0,
-        exhausted: state.layout?.exhausted ?? null,
-        stageZoom: state.stageZoom,
-        stageSvgWidth: state.stageSvgWidth,
-        stageSvgHeight: state.stageSvgHeight,
-        payloadError: state.payloadError,
-        firstLine: state.layout?.lines[0]?.text ?? null,
-        lastLine: state.layout?.lines.at(-1)?.text ?? null,
-      },
-      null,
-      2,
-    )
-  }
-
-  function renderStateSnapshot(snapshot) {
-    const payload = buildDemoPayload(snapshot)
-    const layout = layoutTextInShape({ ...payload.layout, measurer })
-    const svg = renderLayoutToSvg(layout, payload.render)
-
-    return { layout, svg }
-  }
-
-  function commitRenderedState(nextState, rendered) {
-    const nextPolygonPoints = nextState.polygonPoints.map(point => ({ ...point }))
-
-    Object.assign(state, nextState)
-    state.polygonPoints = nextPolygonPoints
-    state.layout = rendered.layout
-    state.svg = rendered.svg
-    syncPresetSelection()
-    syncControls()
-    syncPayloadInput()
-    setPayloadError('')
-    viewport.renderSvg(rendered.svg)
-    updateSummary()
-    lastCommittedState = cloneStateSnapshot(state)
-    lastRenderedState = rendered
-  }
-
-  function restoreCommittedState(message) {
-    if (lastRenderedState === null) {
-      throw new Error(message)
-    }
-
-    const restoredState = cloneStateSnapshot(lastCommittedState)
-    const restoredPolygonPoints = restoredState.polygonPoints.map(point => ({ ...point }))
-
-    Object.assign(state, restoredState)
-    state.polygonPoints = restoredPolygonPoints
-    state.layout = lastRenderedState.layout
-    state.svg = lastRenderedState.svg
-    syncPresetSelection()
-    syncControls()
-    syncPayloadInput()
-    setPayloadError(message)
-    viewport.renderSvg(state.svg)
-    updateSummary()
-  }
-
-  function syncPayloadInput(force = false) {
-    const nextDraft = serializeDemoPayload(state)
-    if (force || !hasPayloadDraftChanges) {
-      state.payloadDraft = nextDraft
-      elements.payloadInput.value = nextDraft
-      return
-    }
-
-    state.payloadDraft = elements.payloadInput.value
-  }
-
-  function syncControls() {
-    const isTextMask = state.shapeKind === 'text-mask'
-    const showFixedSizeFields = isTextMask && state.shapeSizeMode === 'fixed'
-
-    elements.textInput.value = state.text
-    elements.shapeTextInput.value = state.shapeText
-    elements.shapeTextInput.disabled = !isTextMask
-    elements.shapeTextModeSelect.value = state.shapeTextMode
-    elements.shapeTextModeSelect.disabled = !isTextMask
-    elements.shapeSizeModeSelect.value = state.shapeSizeMode
-    elements.shapeSizeModeSelect.disabled = !isTextMask
-    elements.shapeFixedWidthField.hidden = !showFixedSizeFields
-    elements.shapeFixedHeightField.hidden = !showFixedSizeFields
-    elements.shapeFixedWidthInput.disabled = !showFixedSizeFields
-    elements.shapeFixedHeightInput.disabled = !showFixedSizeFields
-    elements.shapeFixedWidthInput.value = String(state.shapeWidth)
-    elements.shapeFixedHeightInput.value = String(state.shapeHeight)
-    elements.fillPresetSelect.value = state.fillPresetId
-    elements.lineHeightInput.value = String(state.lineHeight)
-    elements.lineHeightValue.textContent = String(state.lineHeight)
-    elements.textSizeInput.value = String(state.textSize)
-    elements.textSizeValue.textContent = String(state.textSize)
-    elements.textWeightSelect.value = String(state.textWeight)
-    elements.textItalicInput.checked = state.textItalic
-    elements.textColorInput.value = state.textColor
-    elements.autoFillModeSelect.value = state.fillStrategy === 'max' ? 'max' : state.autoFillMode
-    elements.showShapeInput.checked = state.showShape
-    elements.shapeFillInput.value = state.shapeFill
-    elements.shapeBorderWidthInput.value = String(state.shapeBorderWidth)
-    elements.shapeBorderWidthValue.textContent = String(state.shapeBorderWidth)
-    elements.shapeBorderColorInput.value = state.shapeBorderColor
-    elements.shapeShadowInput.checked = state.shapeShadow
-  }
-
-  function applyScenario(name) {
-    const scenario = demoScenarios[name]
-    if (!scenario) throw new Error(`Unknown scenario: ${name}`)
-
-    state.scenario = name
-    state.shapeKind = scenario.shape.kind
-    state.autoFill = Boolean(scenario.autoFill)
-    if (!hasUserEditedText && scenario.text !== undefined) {
-      state.text = scenario.text
-    }
-
-    if (scenario.shape.kind === 'text-mask') {
-      const size = scenario.shape.size ?? {}
-      if (!hasUserEditedShapeText) {
-        state.shapeText = scenario.shape.text
-      }
-      state.shapeFont = scenario.shape.font
-      state.shapeSizeMode = size.mode === 'fixed' ? 'fixed' : 'fit-content'
-      if (size.mode === 'fixed') {
-        state.shapeWidth = size.width
-        state.shapeHeight = size.height
-      }
-      state.shapeTextMode = scenario.shape.shapeTextMode ?? 'whole-text'
-      state.shapePadding = size.padding ?? 0
-      state.shapeMaskScale = scenario.shape.maskScale ?? 2
-      state.shapeAlphaThreshold = scenario.shape.alphaThreshold
-      return
-    }
-
-    state.polygonPoints = scenario.shape.points.map(point => ({ ...point }))
-  }
-
-  function renderCurrentState() {
-    const nextState = cloneStateSnapshot(state)
-
-    try {
-      commitRenderedState(nextState, renderStateSnapshot(nextState))
-    } catch (error) {
-      restoreCommittedState(error instanceof Error ? error.message : String(error))
-    }
-  }
-
-  return {
-    populateFillPresetOptions() {
-      fillTextPresets.forEach(preset => {
-        const option = document.createElement('option')
-        option.value = preset.id
-        option.textContent = preset.label
-        elements.fillPresetSelect.append(option)
-      })
-    },
-    applyScenario,
-    renderCurrentState,
-    syncControls,
-    syncPayloadInput,
-    applyFillSelection(value) {
-      if (value === 'max') {
-        state.autoFillMode = 'stream'
-        state.fillStrategy = 'max'
-        return
-      }
-
-      state.autoFillMode = value
-      state.fillStrategy = 'flow'
-    },
-    handleTextEdited(value) {
-      state.text = value
-      hasUserEditedText = true
-      state.fillPresetId = 'custom'
-      syncPayloadInput()
-    },
-    handleShapeTextEdited(value) {
-      state.shapeText = value
-      hasUserEditedShapeText = true
-      syncPayloadInput()
-    },
-    handleShapeTextModeSelected(value) {
-      state.shapeTextMode = value === 'per-character' ? 'per-character' : 'whole-text'
-      syncPayloadInput()
-    },
-    handleShapeSizeModeSelected(value) {
-      state.shapeSizeMode = value === 'fixed' ? 'fixed' : 'fit-content'
-      syncControls()
-      syncPayloadInput()
-    },
-    handlePresetSelected(id) {
-      const preset = findFillTextPresetById(id)
-      const nextText = resolveFillTextPresetText(preset.id)
-      if (nextText === null) return
-      state.text = nextText
-      state.fillPresetId = preset.id
-      hasUserEditedText = true
-      syncControls()
-      syncPayloadInput()
-    },
-    handlePayloadDraftEdited(value) {
-      state.payloadDraft = value
-      hasPayloadDraftChanges = true
-    },
-    applyPayloadText() {
-      const nextState = cloneStateSnapshot(state)
-      applyDemoPayloadToState(nextState, JSON.parse(elements.payloadInput.value))
-      const rendered = renderStateSnapshot(nextState)
-      hasPayloadDraftChanges = false
-      hasUserEditedText = true
-      hasUserEditedShapeText = true
-      commitRenderedState(nextState, rendered)
-    },
-    resetPayloadDraft() {
-      hasPayloadDraftChanges = false
-      syncPayloadInput(true)
-      setPayloadError('')
-    },
-    setPayloadError,
-  }
-}
diff --git a/e2e/fixtures/index.html b/e2e/fixtures/index.html
deleted file mode 100644
index c003aee..0000000
--- a/e2e/fixtures/index.html
+++ /dev/null
@@ -1,343 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>shape-text Demo</title>
-    <style>
-      :root {
-        color-scheme: light;
-        font-family: "Segoe UI", system-ui, sans-serif;
-      }
-
-      body {
-        margin: 0;
-        padding: 24px;
-        background: linear-gradient(180deg, #f8fafc 0%, #eef2ff 100%);
-        color: #0f172a;
-      }
-
-      main {
-        max-width: 1200px;
-        margin: 0 auto;
-      }
-
-      .toolbar {
-        display: flex;
-        gap: 12px;
-        align-items: center;
-        flex-wrap: wrap;
-        margin-bottom: 16px;
-      }
-
-      .hero {
-        display: grid;
-        grid-template-columns: minmax(0, 1.2fr) minmax(320px, 0.8fr);
-        gap: 20px;
-        align-items: start;
-        margin-bottom: 18px;
-      }
-
-      .card {
-        border-radius: 24px;
-        background: rgba(255, 255, 255, 0.84);
-        border: 1px solid rgba(148, 163, 184, 0.35);
-        padding: 18px;
-        box-shadow: 0 20px 50px rgba(15, 23, 42, 0.06);
-      }
-
-      h1 {
-        margin: 0 0 8px;
-        font-size: 34px;
-        line-height: 1.05;
-      }
-
-      p {
-        margin: 0;
-        line-height: 1.5;
-      }
-
-      textarea {
-        width: 100%;
-        min-height: 140px;
-        resize: vertical;
-        margin-top: 14px;
-        border-radius: 18px;
-        border: 1px solid #cbd5e1;
-        padding: 14px;
-        font: 14px/1.5 "Segoe UI", system-ui, sans-serif;
-        box-sizing: border-box;
-        background: #ffffff;
-      }
-
-      .payload-textarea {
-        min-height: 220px;
-        font: 12px/1.6 ui-monospace, SFMono-Regular, Consolas, monospace;
-      }
-
-      button {
-        border: 1px solid #cbd5e1;
-        background: white;
-        border-radius: 999px;
-        padding: 8px 14px;
-        cursor: pointer;
-      }
-
-      .primary-button {
-        border-color: #0f172a;
-        background: #0f172a;
-        color: #f8fafc;
-      }
-
-      .panel-grid {
-        display: grid;
-        grid-template-columns: minmax(0, 1fr) 320px;
-        gap: 16px;
-      }
-
-      .stage-card {
-        display: grid;
-        gap: 12px;
-      }
-
-      .stage-toolbar {
-        display: flex;
-        gap: 10px;
-        align-items: center;
-        flex-wrap: wrap;
-      }
-
-      #stage-viewport {
-        min-height: 520px;
-        max-height: 72vh;
-        border-radius: 24px;
-        background: rgba(255, 255, 255, 0.8);
-        border: 1px solid rgba(148, 163, 184, 0.35);
-        padding: 16px;
-        overflow: auto;
-      }
-
-      #stage {
-        width: max-content;
-        height: max-content;
-        transform-origin: top left;
-      }
-
-      #stage svg {
-        display: block;
-      }
-
-      #summary {
-        white-space: pre-wrap;
-        margin: 0;
-        border-radius: 24px;
-        background: #0f172a;
-        color: #e2e8f0;
-        padding: 16px;
-        min-height: 160px;
-        font: 13px/1.5 ui-monospace, SFMono-Regular, Consolas, monospace;
-      }
-
-      .control-row {
-        display: flex;
-        gap: 12px;
-        align-items: center;
-        flex-wrap: wrap;
-        margin-top: 14px;
-      }
-
-      .controls-grid {
-        display: grid;
-        grid-template-columns: repeat(2, minmax(0, 1fr));
-        gap: 12px;
-        margin-top: 14px;
-      }
-
-      label {
-        display: grid;
-        gap: 6px;
-        font-size: 13px;
-        color: #334155;
-      }
-
-      [hidden] {
-        display: none !important;
-      }
-
-      input[type="range"] {
-        width: 220px;
-      }
-
-      .metric {
-        font-weight: 700;
-        color: #0f172a;
-      }
-
-      .muted {
-        font-size: 12px;
-        color: #64748b;
-      }
-
-      .error-box {
-        margin-top: 10px;
-        border-radius: 16px;
-        background: #fef2f2;
-        color: #b91c1c;
-        padding: 12px;
-        white-space: pre-wrap;
-      }
-
-      details {
-        margin-top: 16px;
-      }
-
-      @media (max-width: 960px) {
-        .hero,
-        .panel-grid {
-          grid-template-columns: 1fr;
-        }
-
-        .controls-grid {
-          grid-template-columns: 1fr;
-        }
-      }
-    </style>
-  </head>
-  <body>
-    <main>
-      <section class="hero">
-        <div class="card">
-          <h1>shape-text demo</h1>
-          <p>Preview the current library in a real browser UI. Switch between polygon flow and glyph-mask flow, edit text, tweak text style and shape decoration, then render again.</p>
-          <textarea id="text-input"></textarea>
-          <div class="controls-grid">
-            <label>
-              Shape text
-              <input id="shape-text-input" type="text" value="23" />
-            </label>
-            <label>
-              Shape text mode
-              <select id="shape-text-mode-select">
-                <option value="whole-text" selected>Whole text shape</option>
-                <option value="per-character">Per-character regions</option>
-              </select>
-            </label>
-            <label>
-              Shape size mode
-              <select id="shape-size-mode-select">
-                <option value="fit-content" selected>Fit content</option>
-                <option value="fixed">Fixed box</option>
-              </select>
-            </label>
-            <label id="shape-fixed-width-field" hidden>
-              Fixed width
-              <input id="shape-fixed-width-input" type="number" min="1" step="1" value="340" />
-            </label>
-            <label id="shape-fixed-height-field" hidden>
-              Fixed height
-              <input id="shape-fixed-height-input" type="number" min="1" step="1" value="460" />
-            </label>
-            <label>
-              Fill preset
-              <select id="fill-preset-select"></select>
-            </label>
-            <label>
-              Line height
-              <input id="line-height-input" type="range" min="18" max="34" step="1" value="22" />
-            </label>
-            <label>
-              Text size
-              <input id="text-size-input" type="range" min="14" max="34" step="1" value="18" />
-            </label>
-            <label>
-              Weight
-              <select id="text-weight-select">
-                <option value="400">Regular</option>
-                <option value="700" selected>Bold</option>
-              </select>
-            </label>
-            <label>
-              Text color
-              <input id="text-color-input" type="color" value="#111827" />
-            </label>
-            <label>
-              Fill mode
-              <select id="auto-fill-mode-select">
-                <option value="words" selected>Word repeat</option>
-                <option value="dense">Dense repeat</option>
-                <option value="max">Max fill</option>
-              </select>
-            </label>
-            <label>
-              Shape fill
-              <input id="shape-fill-input" type="color" value="#dbeafe" />
-            </label>
-            <label>
-              Border color
-              <input id="shape-border-color-input" type="color" value="#94a3b8" />
-            </label>
-            <label>
-              Border width
-              <input id="shape-border-width-input" type="range" min="0" max="12" step="1" value="2" />
-            </label>
-          </div>
-          <div class="control-row">
-            <span>Line: <span id="line-height-value" class="metric">22</span>px</span>
-            <span>Text: <span id="text-size-value" class="metric">18</span>px</span>
-            <span>Border: <span id="shape-border-width-value" class="metric">2</span>px</span>
-            <label>
-              <input id="text-italic-input" type="checkbox" />
-              Italic
-            </label>
-            <label>
-              <input id="show-shape-input" type="checkbox" checked />
-              Show shape
-            </label>
-            <label>
-              <input id="shape-shadow-input" type="checkbox" checked />
-              Shadow
-            </label>
-            <button id="render-button" class="primary-button" type="button">Render</button>
-          </div>
-          <details open>
-            <summary>Payload editor</summary>
-            <p class="muted">Edit the live demo payload directly. Use Apply to re-parse and render. Invalid JSON should keep the previous SVG.</p>
-            <textarea id="payload-input" class="payload-textarea"></textarea>
-            <div class="control-row">
-              <button id="apply-payload-button" class="primary-button" type="button">Apply payload</button>
-              <button id="reset-payload-button" type="button">Reset draft</button>
-            </div>
-            <pre id="payload-error" class="error-box" hidden></pre>
-          </details>
-        </div>
-        <div class="card">
-          <p>Scenarios</p>
-          <div class="toolbar">
-            <button data-scenario="glyph-two-repeat">Glyph 23 Repeat</button>
-            <button data-scenario="digit-two-wide">Digit 2 Wide</button>
-            <button data-scenario="digit-two-narrow">Digit 2 Narrow</button>
-            <button data-scenario="rectangle-wide">Rectangle Wide</button>
-            <button data-scenario="rectangle-narrow">Rectangle Narrow</button>
-          </div>
-          <p>Use the shape buttons to compare flow behavior. The glyph scenario now defaults to fit-content sizing so multi-character text masks such as 23 render fully before repeat-fill kicks in.</p>
-        </div>
-      </section>
-      <div class="panel-grid">
-        <section class="card stage-card">
-          <div class="stage-toolbar">
-            <button id="zoom-out-button" type="button">Zoom out</button>
-            <button id="zoom-in-button" type="button">Zoom in</button>
-            <button id="zoom-reset-button" type="button">100%</button>
-            <button id="zoom-fit-button" type="button">Fit</button>
-            <span>Zoom: <span id="zoom-value" class="metric">100%</span></span>
-          </div>
-          <div id="stage-viewport">
-            <div id="stage"></div>
-          </div>
-        </section>
-        <pre id="summary"></pre>
-      </div>
-    </main>
-    <script type="module" src="/e2e/fixtures/shape-text-e2e-app.js"></script>
-  </body>
-</html>
diff --git a/e2e/fixtures/shape-text-e2e-app.js b/e2e/fixtures/shape-text-e2e-app.js
deleted file mode 100644
index 7fc4f45..0000000
--- a/e2e/fixtures/shape-text-e2e-app.js
+++ /dev/null
@@ -1,177 +0,0 @@
-import { compileShapeForLayout, createCanvasTextMeasurer } from '/dist/index.js'
-import { createDemoSvgViewportController } from './demo-svg-viewport-controller.js'
-import { createDemoUiController } from './demo-ui-controller.js'
-import { demoScenarios } from './demo-scenarios.js'
-
-const $ = selector => document.querySelector(selector)
-const elements = {
-  stage: $('#stage'),
-  summary: $('#summary'),
-  stageViewport: $('#stage-viewport'),
-  textInput: $('#text-input'),
-  shapeTextInput: $('#shape-text-input'),
-  shapeTextModeSelect: $('#shape-text-mode-select'),
-  shapeSizeModeSelect: $('#shape-size-mode-select'),
-  shapeFixedWidthField: $('#shape-fixed-width-field'),
-  shapeFixedWidthInput: $('#shape-fixed-width-input'),
-  shapeFixedHeightField: $('#shape-fixed-height-field'),
-  shapeFixedHeightInput: $('#shape-fixed-height-input'),
-  fillPresetSelect: $('#fill-preset-select'),
-  payloadInput: $('#payload-input'),
-  payloadError: $('#payload-error'),
-  lineHeightInput: $('#line-height-input'),
-  lineHeightValue: $('#line-height-value'),
-  textSizeInput: $('#text-size-input'),
-  textSizeValue: $('#text-size-value'),
-  textWeightSelect: $('#text-weight-select'),
-  textItalicInput: $('#text-italic-input'),
-  textColorInput: $('#text-color-input'),
-  autoFillModeSelect: $('#auto-fill-mode-select'),
-  shapeFillInput: $('#shape-fill-input'),
-  shapeBorderWidthInput: $('#shape-border-width-input'),
-  shapeBorderWidthValue: $('#shape-border-width-value'),
-  shapeBorderColorInput: $('#shape-border-color-input'),
-  shapeShadowInput: $('#shape-shadow-input'),
-  showShapeInput: $('#show-shape-input'),
-  zoomOutButton: $('#zoom-out-button'),
-  zoomInButton: $('#zoom-in-button'),
-  zoomResetButton: $('#zoom-reset-button'),
-  zoomFitButton: $('#zoom-fit-button'),
-  zoomValue: $('#zoom-value'),
-}
-const state = {
-  scenario: 'glyph-two-repeat',
-  layout: null,
-  svg: '',
-  payloadDraft: '',
-  payloadError: '',
-  text: 'ONE',
-  fillPresetId: 'custom',
-  lineHeight: 22,
-  textSize: 18,
-  textWeight: 700,
-  textItalic: false,
-  textColor: '#111827',
-  autoFill: true,
-  autoFillMode: 'words',
-  fillStrategy: 'flow',
-  minSlotWidth: undefined,
-  background: '#fffdf7',
-  renderPadding: 12,
-  showShape: true,
-  shapeFill: '#dbeafe',
-  shapeBorderWidth: 2,
-  shapeBorderColor: '#94a3b8',
-  shapeShadow: true,
-  shapeKind: 'text-mask',
-  shapeText: '23',
-  shapeTextMode: 'whole-text',
-  shapeSizeMode: 'fit-content',
-  shapeFont: '700 420px Arial',
-  shapeWidth: 340,
-  shapeHeight: 460,
-  shapePadding: 10,
-  shapeMaskScale: 2,
-  shapeAlphaThreshold: undefined,
-  polygonPoints: [],
-  stageZoom: 1,
-  stageSvgWidth: 0,
-  stageSvgHeight: 0,
-}
-const measurer = createCanvasTextMeasurer()
-const viewport = createDemoSvgViewportController({ state, elements })
-const controller = createDemoUiController({ state, elements, measurer, viewport })
-
-window.shapeTextTestApi = {
-  renderScenario(name) {
-    controller.applyScenario(name)
-    controller.renderCurrentState()
-  },
-  compileScenarioTwice(name) {
-    const scenario = demoScenarios[name]
-    if (!scenario) throw new Error(`Unknown scenario: ${name}`)
-    const first = compileShapeForLayout({ shape: scenario.shape, lineHeight: state.lineHeight, minSlotWidth: 24 })
-    const second = compileShapeForLayout({ shape: scenario.shape, lineHeight: state.lineHeight, minSlotWidth: 24 })
-    return {
-      sameReference: first === second,
-      isFrozen: Object.isFrozen(first) && Object.isFrozen(first.bands),
-      bandCount: first.bands.length,
-      shapeKind: first.kind,
-    }
-  },
-  compileInvalidTextMaskShape() {
-    try {
-      compileShapeForLayout({
-        shape: {
-          kind: 'text-mask',
-          text: '23',
-          font: '700 420px Arial',
-          size: {
-            mode: 'fixed',
-            width: 340,
-            height: 460,
-          },
-          alphaThreshold: 999,
-        },
-        lineHeight: state.lineHeight,
-        minSlotWidth: 24,
-      })
-      return null
-    } catch (error) {
-      return error instanceof Error ? error.message : String(error)
-    }
-  },
-  getState() {
-    return state
-  },
-}
-
-controller.populateFillPresetOptions()
-elements.textInput.addEventListener('input', () => controller.handleTextEdited(elements.textInput.value))
-elements.shapeTextInput.addEventListener('input', () => controller.handleShapeTextEdited(elements.shapeTextInput.value))
-elements.shapeTextModeSelect.addEventListener('change', () =>
-  controller.handleShapeTextModeSelected(elements.shapeTextModeSelect.value),
-)
-elements.shapeSizeModeSelect.addEventListener('change', () =>
-  controller.handleShapeSizeModeSelected(elements.shapeSizeModeSelect.value),
-)
-elements.fillPresetSelect.addEventListener('change', () => controller.handlePresetSelected(elements.fillPresetSelect.value))
-elements.payloadInput.addEventListener('input', () => controller.handlePayloadDraftEdited(elements.payloadInput.value))
-elements.lineHeightInput.addEventListener('input', () => { state.lineHeight = Number(elements.lineHeightInput.value); controller.syncControls(); controller.syncPayloadInput() })
-elements.textSizeInput.addEventListener('input', () => { state.textSize = Number(elements.textSizeInput.value); controller.syncControls(); controller.syncPayloadInput() })
-elements.textWeightSelect.addEventListener('change', () => { state.textWeight = Number(elements.textWeightSelect.value); controller.syncPayloadInput() })
-elements.textItalicInput.addEventListener('change', () => { state.textItalic = elements.textItalicInput.checked; controller.syncPayloadInput() })
-elements.textColorInput.addEventListener('input', () => { state.textColor = elements.textColorInput.value; controller.syncPayloadInput() })
-elements.autoFillModeSelect.addEventListener('change', () => { controller.applyFillSelection(elements.autoFillModeSelect.value); controller.syncPayloadInput() })
-elements.shapeFillInput.addEventListener('input', () => { state.shapeFill = elements.shapeFillInput.value; controller.syncPayloadInput() })
-elements.shapeBorderWidthInput.addEventListener('input', () => { state.shapeBorderWidth = Number(elements.shapeBorderWidthInput.value); controller.syncControls(); controller.syncPayloadInput() })
-elements.shapeBorderColorInput.addEventListener('input', () => { state.shapeBorderColor = elements.shapeBorderColorInput.value; controller.syncPayloadInput() })
-elements.shapeShadowInput.addEventListener('change', () => { state.shapeShadow = elements.shapeShadowInput.checked; controller.syncPayloadInput() })
-elements.showShapeInput.addEventListener('change', () => { state.showShape = elements.showShapeInput.checked; controller.syncPayloadInput() })
-elements.shapeFixedWidthInput.addEventListener('input', () => { state.shapeWidth = Number(elements.shapeFixedWidthInput.value); controller.syncPayloadInput() })
-elements.shapeFixedHeightInput.addEventListener('input', () => { state.shapeHeight = Number(elements.shapeFixedHeightInput.value); controller.syncPayloadInput() })
-elements.zoomOutButton.addEventListener('click', () => viewport.zoomOut())
-elements.zoomInButton.addEventListener('click', () => viewport.zoomIn())
-elements.zoomResetButton.addEventListener('click', () => viewport.resetZoom())
-elements.zoomFitButton.addEventListener('click', () => viewport.fitZoom())
-$('#render-button').addEventListener('click', () => controller.renderCurrentState())
-$('#apply-payload-button').addEventListener('click', () => {
-  try {
-    controller.applyPayloadText()
-  } catch (error) {
-    controller.setPayloadError(error instanceof Error ? error.message : String(error))
-  }
-})
-$('#reset-payload-button').addEventListener('click', () => controller.resetPayloadDraft())
-document.querySelectorAll('[data-scenario]').forEach(button => {
-  button.addEventListener('click', () => {
-    controller.applyScenario(button.getAttribute('data-scenario'))
-    controller.renderCurrentState()
-  })
-})
-
-controller.applyScenario('glyph-two-repeat')
-controller.syncControls()
-controller.syncPayloadInput(true)
-viewport.syncZoomLabel()
-controller.renderCurrentState()
diff --git a/e2e/shape-paragraph-demo.spec.ts b/e2e/shape-paragraph-demo.spec.ts
new file mode 100644
index 0000000..f5d2fb2
--- /dev/null
+++ b/e2e/shape-paragraph-demo.spec.ts
@@ -0,0 +1,77 @@
+import { expect, test } from '@playwright/test'
+
+function readNumber(value: string) {
+  return Number(value.trim())
+}
+
+test('renders the value-derived shape paragraph by default', async ({ page }) => {
+  await page.goto('/')
+
+  await expect(page.getByRole('heading', { name: 'Shape paragraph workbench' })).toBeVisible()
+  await expect(page.getByTestId('stage').locator('svg')).toBeVisible()
+  await expect(page.getByLabel('Shape source')).toHaveValue('value-derived')
+  await expect(page.getByLabel('Shape value')).toHaveValue('23')
+  await expect(page.getByTestId('summary-shape-source')).toHaveText('value-derived')
+  await expect(page.getByLabel('Fill mode')).toHaveCount(0)
+  await expect(page.locator('option[value="500"]')).toHaveCount(0)
+
+  expect(readNumber(await page.getByTestId('summary-line-count').innerText())).toBeGreaterThan(0)
+})
+
+test('switches between value-derived and geometry shape sources', async ({ page }) => {
+  await page.goto('/')
+
+  await page.getByLabel('Shape source').selectOption('geometry')
+  await expect(page.getByLabel('Geometry preset')).toHaveValue('digit-two')
+  await expect(page.getByTestId('summary-shape-source')).toHaveText('geometry')
+  await expect(page.getByLabel('Shape value')).toHaveCount(0)
+
+  await page.getByLabel('Geometry preset').selectOption('rectangle-wide')
+  await expect(page.getByTestId('stage').locator('svg')).toBeVisible()
+
+  await page.getByLabel('Shape source').selectOption('value-derived')
+  await expect(page.getByLabel('Shape value')).toHaveValue('23')
+  await expect(page.getByTestId('summary-shape-source')).toHaveText('value-derived')
+})
+
+test('switches text-mask sizing between fit-content and fixed', async ({ page }) => {
+  await page.goto('/')
+
+  await page.getByLabel('Shape size mode').selectOption('fixed')
+  await page.getByLabel('Fixed width').fill('520')
+  await page.getByLabel('Fixed height').fill('260')
+  await expect(page.getByTestId('summary-shape-size')).toHaveText('520 × 260')
+
+  await page.getByLabel('Shape size mode').selectOption('fit-content')
+  await expect(page.getByTestId('summary-shape-size')).not.toHaveText('520 × 260')
+})
+
+test('switches value-derived rendering between whole-text and per-character regions', async ({ page }) => {
+  await page.goto('/')
+
+  await page.getByLabel('Paragraph text').fill('ABCDEFGHIJ')
+  await page.getByLabel('Shape value').fill('AB')
+  await page.getByLabel('Shape size mode').selectOption('fixed')
+  await page.getByLabel('Fixed width').fill('520')
+  await page.getByLabel('Fixed height').fill('260')
+  await expect(page.getByTestId('summary-region-count')).toHaveText('0')
+
+  await page.getByLabel('Shape text mode').selectOption('per-character')
+  await expect(page.getByTestId('summary-region-count')).toHaveText('2')
+  expect(readNumber(await page.getByTestId('summary-line-count').innerText())).toBeGreaterThan(0)
+})
+
+test('rerolls true-random preset text while keeping the same preset family selected', async ({ page }) => {
+  await page.goto('/')
+
+  await page.getByLabel('Fill preset').selectOption('ascii-random')
+  const firstText = await page.getByLabel('Paragraph text').inputValue()
+
+  await expect(page.getByLabel('Fill preset')).toHaveValue('ascii-random')
+  await page.getByRole('button', { name: 'Reroll' }).click()
+  const secondText = await page.getByLabel('Paragraph text').inputValue()
+
+  expect(firstText).not.toBe(secondText)
+  expect(firstText).toMatch(/^[A-Za-z0-9!@#$%^&*()[\]{}<>?/|+\-=]+$/)
+  expect(secondText).toMatch(/^[A-Za-z0-9!@#$%^&*()[\]{}<>?/|+\-=]+$/)
+})
diff --git a/e2e/shape-paragraph-workbench.spec.ts b/e2e/shape-paragraph-workbench.spec.ts
new file mode 100644
index 0000000..c0f7a81
--- /dev/null
+++ b/e2e/shape-paragraph-workbench.spec.ts
@@ -0,0 +1,175 @@
+import { expect, test } from '@playwright/test'
+
+test('applies payload JSON and keeps the last successful SVG when JSON is invalid', async ({ page }) => {
+  await page.goto('/')
+
+  await page.getByText('Advanced payload editor').click()
+  await page.getByLabel('Payload JSON').fill(
+    JSON.stringify(
+      {
+        layout: {
+          text: 'DATA FLOW',
+          textStyle: {
+            family: '"Helvetica Neue", Arial, sans-serif',
+            size: 22,
+            weight: 700,
+            style: 'normal',
+            color: '#0f172a',
+          },
+          lineHeight: 28,
+          shape: {
+            kind: 'text-mask',
+            text: '8',
+            font: '700 420px Arial',
+            size: { mode: 'fit-content', padding: 10 },
+            shapeTextMode: 'whole-text',
+            maskScale: 2,
+          },
+          autoFill: true,
+        },
+        render: {
+          background: '#f8fafc',
+          padding: 16,
+          showShape: true,
+          shapeStyle: {
+            backgroundColor: '#dbeafe',
+            borderColor: '#94a3b8',
+            borderWidth: 2,
+          },
+        },
+      },
+      null,
+      2,
+    ),
+  )
+  await page.getByRole('button', { name: 'Apply JSON' }).click()
+
+  await expect(page.getByLabel('Paragraph text')).toHaveValue('DATA FLOW')
+  await expect(page.getByLabel('Shape value')).toHaveValue('8')
+  await expect(page.getByTestId('stage').locator('svg')).toBeVisible()
+
+  const beforeMarkup = await page.getByTestId('stage').innerHTML()
+  await page.getByLabel('Payload JSON').fill('{"layout":')
+  await page.getByRole('button', { name: 'Apply JSON' }).click()
+
+  await expect(page.getByTestId('payload-error')).toBeVisible()
+  await expect(page.getByTestId('stage').locator('svg')).toBeVisible()
+  expect(await page.getByTestId('stage').innerHTML()).toBe(beforeMarkup)
+})
+
+test('merges partial payload JSON without resetting omitted state', async ({ page }) => {
+  await page.goto('/')
+
+  await page.getByLabel('Italic').check()
+  await page.getByText('Advanced payload editor').click()
+  await page.getByLabel('Payload JSON').fill(
+    JSON.stringify(
+      {
+        layout: {
+          textStyle: {
+            size: 30,
+          },
+        },
+        render: {},
+      },
+      null,
+      2,
+    ),
+  )
+  await page.getByRole('button', { name: 'Apply JSON' }).click()
+
+  await expect(page.getByLabel('Text size')).toHaveValue('30')
+  await expect(page.getByLabel('Italic')).toBeChecked()
+  await expect(page.getByLabel('Auto fill')).toBeChecked()
+})
+
+test('keeps custom geometry payloads labeled as custom instead of overwriting them with a preset', async ({ page }) => {
+  await page.goto('/')
+
+  await page.getByText('Advanced payload editor').click()
+  await page.getByLabel('Payload JSON').fill(
+    JSON.stringify(
+      {
+        layout: {
+          shape: {
+            kind: 'polygon',
+            points: [
+              { x: 0, y: 0 },
+              { x: 200, y: 0 },
+              { x: 120, y: 220 },
+            ],
+          },
+        },
+        render: {},
+      },
+      null,
+      2,
+    ),
+  )
+  await page.getByRole('button', { name: 'Apply JSON' }).click()
+
+  await expect(page.getByLabel('Shape source')).toHaveValue('geometry')
+  await expect(page.getByLabel('Geometry preset')).toHaveValue('custom')
+})
+
+test('keeps wide output inspectable with zoom controls', async ({ page }) => {
+  await page.goto('/')
+
+  await page.getByLabel('Shape value').fill('202520252025202520252025')
+  await expect(page.getByTestId('stage').locator('svg')).toBeVisible()
+
+  await page.getByRole('button', { name: '100%' }).click()
+  const viewportBefore = await page.getByTestId('stage-viewport').evaluate(element => ({
+    clientWidth: element.clientWidth,
+    scrollWidth: element.scrollWidth,
+  }))
+
+  await expect(page.getByTestId('stage-zoom')).toHaveText('100%')
+  await page.getByRole('button', { name: 'Zoom in' }).click()
+  await expect(page.getByTestId('stage-zoom')).not.toHaveText('100%')
+  await page.getByRole('button', { name: 'Fit' }).click()
+
+  const viewportAfter = await page.getByTestId('stage-viewport').evaluate(element => ({
+    clientWidth: element.clientWidth,
+    scrollWidth: element.scrollWidth,
+  }))
+
+  expect(viewportBefore.scrollWidth).toBeGreaterThanOrEqual(viewportBefore.clientWidth)
+  expect(viewportAfter.scrollWidth).toBeLessThanOrEqual(viewportAfter.clientWidth + 12)
+})
+
+test('fits tall output by viewport height as well as width', async ({ page }) => {
+  await page.goto('/')
+
+  await page.getByText('Advanced payload editor').click()
+  await page.getByLabel('Payload JSON').fill(
+    JSON.stringify(
+      {
+        layout: {
+          shape: {
+            kind: 'polygon',
+            points: [
+              { x: 0, y: 0 },
+              { x: 220, y: 0 },
+              { x: 220, y: 1500 },
+              { x: 0, y: 1500 },
+            ],
+          },
+        },
+        render: {},
+      },
+      null,
+      2,
+    ),
+  )
+  await page.getByRole('button', { name: 'Apply JSON' }).click()
+  await page.getByRole('button', { name: 'Fit' }).click()
+
+  const viewportAfter = await page.getByTestId('stage-viewport').evaluate(element => ({
+    clientHeight: element.clientHeight,
+    scrollHeight: element.scrollHeight,
+  }))
+
+  await expect(page.getByTestId('stage-zoom')).not.toHaveText('100%')
+  expect(viewportAfter.scrollHeight).toBeLessThanOrEqual(viewportAfter.clientHeight + 12)
+})
diff --git a/e2e/shape-text-local-e2e.spec.ts b/e2e/shape-text-local-e2e.spec.ts
deleted file mode 100644
index f4ef701..0000000
--- a/e2e/shape-text-local-e2e.spec.ts
+++ /dev/null
@@ -1,571 +0,0 @@
-import { expect, test } from '@playwright/test'
-
-declare global {
-  interface Window {
-    shapeTextTestApi: {
-      renderScenario(name: string): void
-      compileScenarioTwice(name: string): {
-        sameReference: boolean
-        isFrozen: boolean
-        bandCount: number
-        shapeKind: string
-      }
-      compileInvalidTextMaskShape(): string | null
-      getState(): {
-        scenario: string
-        layout: {
-          autoFill: boolean
-          autoFillMode: 'words' | 'dense' | 'stream'
-          fillStrategy: 'flow' | 'max'
-          exhausted: boolean
-          compiledShape?: {
-            bounds: {
-              left: number
-              top: number
-              right: number
-              bottom: number
-            }
-            regions?: Array<{ grapheme: string }>
-          }
-          lines: Array<{
-            text: string
-            x: number
-            top: number
-            width: number
-            slot: { left: number; right: number }
-            fillPass?: 1 | 2
-          }>
-        }
-        text: string
-        fillPresetId: string
-        textSize: number
-        textWeight: number
-        textItalic: boolean
-        textColor: string
-        autoFillMode: 'words' | 'dense' | 'stream'
-        fillStrategy: 'flow' | 'max'
-        shapeKind: 'polygon' | 'text-mask'
-        shapeText: string
-        shapeTextMode: 'whole-text' | 'per-character'
-        shapeSizeMode: 'fit-content' | 'fixed'
-        showShape: boolean
-        shapeFill: string
-        shapeBorderWidth: number
-        shapeBorderColor: string
-        shapeShadow: boolean
-        stageZoom: number
-        stageSvgWidth: number
-        stageSvgHeight: number
-        payloadDraft: string
-        payloadError: string
-        svg: string
-      }
-    }
-  }
-}
-
-async function getState(page: import('@playwright/test').Page) {
-  return page.evaluate(() => window.shapeTextTestApi.getState())
-}
-
-async function setRangeValue(
-  page: import('@playwright/test').Page,
-  selector: string,
-  value: string,
-) {
-  await page.locator(selector).evaluate((element, nextValue) => {
-    if (!(element instanceof HTMLInputElement)) {
-      throw new Error('Expected an input element')
-    }
-
-    element.value = nextValue
-    element.dispatchEvent(new Event('input', { bubbles: true }))
-    element.dispatchEvent(new Event('change', { bubbles: true }))
-  }, value)
-}
-
-test('renders the glyph text-mask fixture into SVG', async ({ page }) => {
-  await page.goto('/')
-  await expect(page.locator('#stage svg')).toBeVisible()
-
-  const state = await getState(page)
-
-  expect(state.scenario).toBe('glyph-two-repeat')
-  expect(state.text).toBe('ONE')
-  expect(state.layout.lines.length).toBeGreaterThan(4)
-  expect(state.layout.autoFill).toBe(true)
-  expect(state.layout.autoFillMode).toBe('words')
-  expect(state.layout.fillStrategy).toBe('flow')
-  expect(state.layout.exhausted).toBe(false)
-  expect(state.layout.lines[0]?.text).toContain('ONE')
-  expect(state.shapeText).toBe('23')
-  expect(state.shapeSizeMode).toBe('fit-content')
-  expect(state.textSize).toBe(18)
-  const expectedTextNodeCount =
-    state.showShape && state.scenario === 'glyph-two-repeat'
-      ? state.layout.lines.length + 1
-      : state.layout.lines.length
-  await expect(page.locator('#stage text')).toHaveCount(expectedTextNodeCount)
-})
-
-test('reuses the cached compiled glyph shape for repeated text-mask requests', async ({
-  page,
-}) => {
-  await page.goto('/')
-
-  const result = await page.evaluate(() =>
-    window.shapeTextTestApi.compileScenarioTwice('glyph-two-repeat'),
-  )
-
-  expect(result.shapeKind).toBe('text-mask')
-  expect(result.bandCount).toBeGreaterThan(4)
-  expect(result.sameReference).toBe(true)
-  expect(result.isFrozen).toBe(true)
-})
-
-test('rejects invalid text-mask alpha thresholds with a clear error', async ({ page }) => {
-  await page.goto('/')
-
-  const errorMessage = await page.evaluate(() => window.shapeTextTestApi.compileInvalidTextMaskShape())
-
-  expect(errorMessage).toContain('alphaThreshold')
-})
-
-test('applies text and shape style controls to the rendered SVG', async ({ page }) => {
-  await page.goto('/')
-
-  await setRangeValue(page, '#text-size-input', '28')
-  await page.locator('#text-weight-select').selectOption('700')
-  await page.locator('#text-italic-input').check()
-  await page.locator('#text-color-input').fill('#ef4444')
-  await page.locator('#shape-fill-input').fill('#fde68a')
-  await setRangeValue(page, '#shape-border-width-input', '6')
-  await page.locator('#shape-border-color-input').fill('#f59e0b')
-  await page.locator('#shape-shadow-input').check()
-  await page.locator('#render-button').click()
-
-  const state = await getState(page)
-
-  expect(state.textSize).toBe(28)
-  expect(state.textItalic).toBe(true)
-  expect(state.shapeBorderWidth).toBe(6)
-  expect(state.svg).toContain('font:italic 700 28px')
-  expect(state.svg).toContain('fill="#ef4444"')
-  expect(state.svg).toContain('stroke="#f59e0b"')
-  expect(state.svg).toContain('stroke-width="6"')
-  expect(state.svg).toContain('fill="#fde68a"')
-  expect(state.svg).toContain('shape-text-shape-shadow')
-})
-
-test('lets the demo edit glyph shape text directly', async ({ page }) => {
-  await page.goto('/')
-
-  await page.locator('#shape-text-input').fill('8')
-  await page.locator('#render-button').click()
-
-  const state = await getState(page)
-
-  await expect(page.locator('#shape-text-input')).toHaveValue('8')
-  expect(state.shapeKind).toBe('text-mask')
-  expect(state.shapeText).toBe('8')
-  expect(state.svg).toContain('>8<')
-})
-
-test('restores the last good state when direct render controls produce an invalid shape', async ({
-  page,
-}) => {
-  await page.goto('/')
-
-  const before = await getState(page)
-  await page.locator('#shape-text-input').fill('')
-  await page.locator('#render-button').click()
-
-  const after = await getState(page)
-
-  await expect(page.locator('#shape-text-input')).toHaveValue(before.shapeText)
-  expect(after.shapeText).toBe(before.shapeText)
-  expect(after.svg).toBe(before.svg)
-  expect(after.payloadError.length).toBeGreaterThan(0)
-})
-
-test('keeps wide output inspectable inside the zoomable stage viewport', async ({ page }) => {
-  await page.goto('/')
-
-  const initialState = await getState(page)
-  const initialWidth =
-    (initialState.layout.compiledShape?.bounds.right ?? 0) -
-    (initialState.layout.compiledShape?.bounds.left ?? 0)
-  const payload = JSON.parse(await page.locator('#payload-input').inputValue())
-  payload.layout.shape.text = '20252025'
-  payload.layout.shape.shapeTextMode = 'whole-text'
-
-  await page.locator('#payload-input').fill(JSON.stringify(payload, null, 2))
-  await page.locator('#apply-payload-button').click()
-
-  const beforeZoom = await getState(page)
-  const widenedShapeWidth =
-    (beforeZoom.layout.compiledShape?.bounds.right ?? 0) -
-    (beforeZoom.layout.compiledShape?.bounds.left ?? 0)
-  const viewportMetrics = await page.locator('#stage-viewport').evaluate(element => ({
-    clientWidth: element.clientWidth,
-    scrollWidth: element.scrollWidth,
-  }))
-
-  await page.locator('#zoom-in-button').click()
-  const zoomedIn = await getState(page)
-  await page.locator('#zoom-out-button').click()
-  const zoomedOut = await getState(page)
-  await page.locator('#zoom-fit-button').click()
-  const fitState = await getState(page)
-  const fitViewportMetrics = await page.locator('#stage-viewport').evaluate(element => ({
-    clientWidth: element.clientWidth,
-    scrollWidth: element.scrollWidth,
-  }))
-  await page.locator('#zoom-reset-button').click()
-  const resetState = await getState(page)
-
-  expect(widenedShapeWidth).toBeGreaterThan(initialWidth)
-  expect(viewportMetrics.scrollWidth).toBeGreaterThan(viewportMetrics.clientWidth)
-  expect(zoomedIn.stageZoom).toBeGreaterThan(beforeZoom.stageZoom)
-  expect(zoomedOut.stageZoom).toBeLessThan(zoomedIn.stageZoom)
-  expect(fitState.stageZoom).toBeGreaterThan(0)
-  expect(fitViewportMetrics.scrollWidth).toBeLessThanOrEqual(fitViewportMetrics.clientWidth + 12)
-  expect(resetState.stageZoom).toBe(1)
-  await expect(page.locator('#stage svg')).toBeVisible()
-})
-
-test('applies payload editor changes to the live demo state', async ({ page }) => {
-  await page.goto('/')
-
-  const payload = JSON.parse(await page.locator('#payload-input').inputValue())
-  payload.layout.text = 'DATA'
-  payload.layout.textStyle.size = 30
-  payload.layout.shape.text = '8'
-
-  await page.locator('#payload-input').fill(JSON.stringify(payload, null, 2))
-  await page.locator('#apply-payload-button').click()
-
-  const state = await getState(page)
-
-  expect(state.text).toBe('DATA')
-  expect(state.textSize).toBe(30)
-  expect(state.shapeText).toBe('8')
-  expect(state.payloadError).toBe('')
-  expect(state.svg).toContain('font:normal 700 30px')
-  expect(state.svg).toContain('>8<')
-})
-
-test('switches text-mask sizing between fit-content and fixed', async ({ page }) => {
-  await page.goto('/')
-
-  await expect(page.locator('#shape-fixed-width-field')).toBeHidden()
-  await expect(page.locator('#shape-fixed-height-field')).toBeHidden()
-
-  await page.locator('#shape-size-mode-select').selectOption('fixed')
-  await expect(page.locator('#shape-fixed-width-field')).toBeVisible()
-  await expect(page.locator('#shape-fixed-height-field')).toBeVisible()
-
-  await page.locator('#shape-fixed-width-input').fill('520')
-  await page.locator('#shape-fixed-height-input').fill('260')
-  await page.locator('#render-button').click()
-
-  const fixedState = await getState(page)
-  const fixedWidth =
-    (fixedState.layout.compiledShape?.bounds.right ?? 0) -
-    (fixedState.layout.compiledShape?.bounds.left ?? 0)
-
-  expect(fixedState.shapeSizeMode).toBe('fixed')
-  expect(fixedWidth).toBe(520)
-  expect(fixedState.payloadDraft).toContain('"mode": "fixed"')
-
-  await page.locator('#shape-size-mode-select').selectOption('fit-content')
-  await page.locator('#render-button').click()
-  await expect(page.locator('#shape-fixed-width-field')).toBeHidden()
-  await expect(page.locator('#shape-fixed-height-field')).toBeHidden()
-
-  const fitState = await getState(page)
-  const fitWidth =
-    (fitState.layout.compiledShape?.bounds.right ?? 0) -
-    (fitState.layout.compiledShape?.bounds.left ?? 0)
-
-  expect(fitState.shapeSizeMode).toBe('fit-content')
-  expect(fitState.payloadDraft).toContain('"mode": "fit-content"')
-  expect(fitWidth).toBeLessThan(fixedWidth)
-})
-
-test('switches text-mask rendering between whole-text and per-character regions', async ({
-  page,
-}) => {
-  await page.goto('/')
-
-  const payload = JSON.parse(await page.locator('#payload-input').inputValue())
-  payload.layout.autoFill = false
-  payload.layout.text = 'ABCDEFGHIJ'
-  payload.layout.lineHeight = 18
-  payload.layout.minSlotWidth = 1
-  payload.layout.textStyle.size = 14
-  payload.layout.shape.text = 'AB'
-  payload.layout.shape.font = '700 260px Arial'
-  payload.layout.shape.size = {
-    mode: 'fixed',
-    width: 520,
-    height: 260,
-  }
-  payload.layout.shape.shapeTextMode = 'whole-text'
-
-  await page.locator('#payload-input').fill(JSON.stringify(payload, null, 2))
-  await page.locator('#apply-payload-button').click()
-  const wholeTextState = await getState(page)
-
-  await page.locator('#shape-text-mode-select').selectOption('per-character')
-  await page.locator('#render-button').click()
-  const perCharacterState = await getState(page)
-
-  expect(wholeTextState.shapeTextMode).toBe('whole-text')
-  expect(perCharacterState.shapeTextMode).toBe('per-character')
-  expect(perCharacterState.payloadDraft).toContain('"shapeTextMode": "per-character"')
-  expect(wholeTextState.layout.compiledShape?.regions ?? []).toHaveLength(0)
-  expect(perCharacterState.layout.compiledShape?.regions?.map(region => region.grapheme)).toEqual(['A', 'B'])
-  expect(perCharacterState.layout.lines.length).toBeGreaterThan(0)
-})
-
-test('keeps the last successful SVG when payload parsing fails', async ({ page }) => {
-  await page.goto('/')
-
-  const before = await getState(page)
-  await page.locator('#payload-input').fill('{"layout":')
-  await page.locator('#apply-payload-button').click()
-
-  const after = await getState(page)
-
-  expect(after.payloadError.length).toBeGreaterThan(0)
-  expect(after.svg).toBe(before.svg)
-  expect(after.text).toBe(before.text)
-  expect(after.shapeText).toBe(before.shapeText)
-  await expect(page.locator('#payload-error')).toBeVisible()
-})
-
-test('keeps state unchanged when payload validation fails mid-apply', async ({ page }) => {
-  await page.goto('/')
-
-  const before = await getState(page)
-  const payload = JSON.parse(await page.locator('#payload-input').inputValue())
-  payload.layout.text = 'BROKEN'
-  payload.layout.shape.text = '8'
-  payload.render.padding = 'oops'
-
-  await page.locator('#payload-input').fill(JSON.stringify(payload, null, 2))
-  await page.locator('#apply-payload-button').click()
-
-  const after = await getState(page)
-
-  expect(after.payloadError).toContain('render.padding')
-  expect(after.text).toBe(before.text)
-  expect(after.shapeText).toBe(before.shapeText)
-  expect(after.svg).toBe(before.svg)
-})
-
-test('keeps state unchanged when payload render fails after JSON parsing succeeds', async ({
-  page,
-}) => {
-  await page.goto('/')
-
-  const before = await getState(page)
-  const payload = JSON.parse(await page.locator('#payload-input').inputValue())
-  payload.layout.text = 'BROKEN-BUT-VALID'
-  payload.layout.shape.text = ''
-
-  await page.locator('#payload-input').fill(JSON.stringify(payload, null, 2))
-  await page.locator('#apply-payload-button').click()
-
-  const after = await getState(page)
-
-  expect(after.payloadError.length).toBeGreaterThan(0)
-  expect(after.text).toBe(before.text)
-  expect(after.shapeText).toBe(before.shapeText)
-  expect(after.svg).toBe(before.svg)
-})
-
-test('preserves omitted payload fields instead of resetting styling and fill mode', async ({
-  page,
-}) => {
-  await page.goto('/')
-
-  await page.locator('#text-italic-input').check()
-  await page.locator('#auto-fill-mode-select').selectOption('max')
-  await page.locator('#render-button').click()
-
-  const payload = JSON.parse(await page.locator('#payload-input').inputValue())
-  delete payload.layout.fillStrategy
-  delete payload.layout.autoFillMode
-  payload.layout.textStyle = { size: 22 }
-
-  await page.locator('#payload-input').fill(JSON.stringify(payload, null, 2))
-  await page.locator('#apply-payload-button').click()
-
-  const state = await getState(page)
-
-  expect(state.textSize).toBe(22)
-  expect(state.textItalic).toBe(true)
-  expect(state.fillStrategy).toBe('max')
-  expect(state.autoFillMode).toBe('stream')
-})
-
-test('keeps payloadDraft aligned with the visible textarea while draft edits are dirty', async ({
-  page,
-}) => {
-  await page.goto('/')
-
-  const payload = JSON.parse(await page.locator('#payload-input').inputValue())
-  payload.layout.text = 'DIRTY'
-  const dirtyDraft = JSON.stringify(payload, null, 2)
-
-  await page.locator('#payload-input').fill(dirtyDraft)
-  await setRangeValue(page, '#text-size-input', '24')
-
-  const state = await getState(page)
-
-  expect(state.payloadDraft).toBe(await page.locator('#payload-input').inputValue())
-  expect(state.payloadDraft).toBe(dirtyDraft)
-})
-
-test('syncs predefined fill presets into text input and payload draft', async ({ page }) => {
-  await page.goto('/')
-
-  await page.locator('#fill-preset-select').selectOption('binary-random')
-
-  const state = await getState(page)
-
-  await expect(page.locator('#text-input')).toHaveValue(state.text)
-  expect(state.fillPresetId).toBe('binary-random')
-  expect(state.text).toMatch(/^[01]+$/)
-  expect(state.text.length).toBeGreaterThan(100)
-  expect(state.payloadDraft).toContain(`"text": "${state.text}"`)
-})
-
-test('packs glyph autofill more tightly in dense mode', async ({ page }) => {
-  await page.goto('/')
-
-  const wordsState = await getState(page)
-
-  await page.locator('#auto-fill-mode-select').selectOption('dense')
-  await page.locator('#render-button').click()
-
-  const denseState = await getState(page)
-
-  expect(wordsState.layout.autoFillMode).toBe('words')
-  expect(denseState.layout.autoFillMode).toBe('dense')
-  expect(denseState.autoFillMode).toBe('dense')
-  expect(denseState.layout.lines[0]?.text).not.toContain(' ')
-  expect(denseState.layout.lines[0]?.width).toBeGreaterThan(wordsState.layout.lines[0]?.width ?? 0)
-})
-
-test('keeps spaces and fills multiple slots in max mode without mini-font fallback', async ({ page }) => {
-  await page.goto('/')
-
-  await page.locator('#text-input').fill('ONE ONE')
-  await page.locator('#auto-fill-mode-select').selectOption('dense')
-  await page.locator('#render-button').click()
-  const denseState = await getState(page)
-
-  await page.locator('#auto-fill-mode-select').selectOption('max')
-  await page.locator('#render-button').click()
-  const maxState = await getState(page)
-
-  expect(maxState.fillStrategy).toBe('max')
-  expect(maxState.layout.fillStrategy).toBe('max')
-  expect(maxState.layout.autoFillMode).toBe('stream')
-  expect(maxState.layout.lines.some(line => line.text.includes(' '))).toBe(true)
-  expect(maxState.layout.lines.some((line, index, lines) => lines.some(other => other !== line && other.top === line.top))).toBe(true)
-  expect(maxState.layout.lines.length).toBeGreaterThanOrEqual(denseState.layout.lines.length)
-  expect(maxState.svg).not.toMatch(/font:[^"]*12\./)
-})
-
-test('preserves edited glyph autofill text without forcing uppercase', async ({ page }) => {
-  await page.goto('/')
-
-  await page.locator('#text-input').fill('one')
-  await page.locator('#render-button').click()
-
-  const state = await getState(page)
-
-  await expect(page.locator('#text-input')).toHaveValue('one')
-  expect(state.text).toBe('one')
-  expect(state.layout.lines[0]?.text).toContain('one')
-  expect(state.layout.lines[0]?.text).not.toContain('ONE')
-  expect(state.svg).toContain('>one<')
-})
-
-test('keeps edited text when switching away from and back to the glyph scenario', async ({
-  page,
-}) => {
-  await page.goto('/')
-
-  await page.locator('#text-input').fill('one')
-  await page.locator('#render-button').click()
-  await page.evaluate(() => window.shapeTextTestApi.renderScenario('rectangle-wide'))
-  await page.evaluate(() => window.shapeTextTestApi.renderScenario('glyph-two-repeat'))
-
-  const state = await getState(page)
-
-  await expect(page.locator('#text-input')).toHaveValue('one')
-  expect(state.scenario).toBe('glyph-two-repeat')
-  expect(state.text).toBe('one')
-  expect(state.layout.lines[0]?.text).toContain('one')
-  expect(state.layout.lines[0]?.text).not.toContain('ONE')
-})
-
-test('keeps unsaved textarea edits when switching scenarios', async ({ page }) => {
-  await page.goto('/')
-
-  await page.locator('#text-input').fill('draft')
-  await page.evaluate(() => window.shapeTextTestApi.renderScenario('rectangle-wide'))
-
-  const state = await getState(page)
-
-  await expect(page.locator('#text-input')).toHaveValue('draft')
-  expect(state.scenario).toBe('rectangle-wide')
-  expect(state.text).toBe('draft')
-  expect(state.layout.lines[0]?.text).toContain('draft')
-})
-
-test('keeps scenario defaults when rerender changes only style controls', async ({ page }) => {
-  await page.goto('/')
-
-  await setRangeValue(page, '#text-size-input', '24')
-  await page.locator('#render-button').click()
-  await page.evaluate(() => window.shapeTextTestApi.renderScenario('rectangle-wide'))
-
-  const state = await getState(page)
-
-  expect(state.scenario).toBe('rectangle-wide')
-  expect(state.text).toContain('Shape text lets a paragraph travel inside a silhouette')
-  expect(state.layout.lines[0]?.text).toContain('Shape text')
-})
-
-test('reflows into more lines in the narrow rectangle scenario', async ({ page }) => {
-  await page.goto('/')
-
-  await page.evaluate(() => window.shapeTextTestApi.renderScenario('rectangle-wide'))
-  const wideState = await getState(page)
-  await page.evaluate(() => window.shapeTextTestApi.renderScenario('rectangle-narrow'))
-  const narrowState = await getState(page)
-
-  expect(narrowState.layout.lines.length).toBeGreaterThan(wideState.layout.lines.length)
-  expect(narrowState.layout.lines[0]?.text).not.toBe('')
-})
-
-test('keeps each rendered line inside its chosen slot', async ({ page }) => {
-  await page.goto('/')
-  await page.evaluate(() => window.shapeTextTestApi.renderScenario('rectangle-wide'))
-
-  const state = await getState(page)
-
-  for (const line of state.layout.lines) {
-    expect(line.x).toBeGreaterThanOrEqual(line.slot.left)
-    expect(line.x + line.width).toBeLessThanOrEqual(line.slot.right + 0.5)
-  }
-
-  expect(state.svg).toContain('<svg')
-  expect(state.svg).toContain('<text')
-})
diff --git a/package-lock.json b/package-lock.json
index de2f524..0dac1bd 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -10,8 +10,15 @@
       "license": "MIT",
       "devDependencies": {
         "@playwright/test": "^1.58.2",
+        "@types/node": "^25.5.0",
+        "@types/react": "^19.2.2",
+        "@types/react-dom": "^19.2.2",
+        "@vitejs/plugin-react": "^5.1.0",
         "@vitest/coverage-v8": "^3.2.4",
+        "react": "^19.2.0",
+        "react-dom": "^19.2.0",
         "typescript": "^5.9.3",
+        "vite": "^7.1.12",
         "vitest": "^3.2.4"
       }
     },
@@ -29,6 +36,185 @@
         "node": ">=6.0.0"
       }
     },
+    "node_modules/@babel/code-frame": {
+      "version": "7.29.0",
+      "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.29.0.tgz",
+      "integrity": "sha512-9NhCeYjq9+3uxgdtp20LSiJXJvN0FeCtNGpJxuMFZ1Kv3cWUNb6DOhJwUvcVCzKGR66cw4njwM6hrJLqgOwbcw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/helper-validator-identifier": "^7.28.5",
+        "js-tokens": "^4.0.0",
+        "picocolors": "^1.1.1"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/code-frame/node_modules/js-tokens": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz",
+      "integrity": "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@babel/compat-data": {
+      "version": "7.29.0",
+      "resolved": "https://registry.npmjs.org/@babel/compat-data/-/compat-data-7.29.0.tgz",
+      "integrity": "sha512-T1NCJqT/j9+cn8fvkt7jtwbLBfLC/1y1c7NtCeXFRgzGTsafi68MRv8yzkYSapBnFA6L3U2VSc02ciDzoAJhJg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/core": {
+      "version": "7.29.0",
+      "resolved": "https://registry.npmjs.org/@babel/core/-/core-7.29.0.tgz",
+      "integrity": "sha512-CGOfOJqWjg2qW/Mb6zNsDm+u5vFQ8DxXfbM09z69p5Z6+mE1ikP2jUXw+j42Pf1XTYED2Rni5f95npYeuwMDQA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/code-frame": "^7.29.0",
+        "@babel/generator": "^7.29.0",
+        "@babel/helper-compilation-targets": "^7.28.6",
+        "@babel/helper-module-transforms": "^7.28.6",
+        "@babel/helpers": "^7.28.6",
+        "@babel/parser": "^7.29.0",
+        "@babel/template": "^7.28.6",
+        "@babel/traverse": "^7.29.0",
+        "@babel/types": "^7.29.0",
+        "@jridgewell/remapping": "^2.3.5",
+        "convert-source-map": "^2.0.0",
+        "debug": "^4.1.0",
+        "gensync": "^1.0.0-beta.2",
+        "json5": "^2.2.3",
+        "semver": "^6.3.1"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/babel"
+      }
+    },
+    "node_modules/@babel/core/node_modules/semver": {
+      "version": "6.3.1",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz",
+      "integrity": "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==",
+      "dev": true,
+      "license": "ISC",
+      "bin": {
+        "semver": "bin/semver.js"
+      }
+    },
+    "node_modules/@babel/generator": {
+      "version": "7.29.1",
+      "resolved": "https://registry.npmjs.org/@babel/generator/-/generator-7.29.1.tgz",
+      "integrity": "sha512-qsaF+9Qcm2Qv8SRIMMscAvG4O3lJ0F1GuMo5HR/Bp02LopNgnZBC/EkbevHFeGs4ls/oPz9v+Bsmzbkbe+0dUw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/parser": "^7.29.0",
+        "@babel/types": "^7.29.0",
+        "@jridgewell/gen-mapping": "^0.3.12",
+        "@jridgewell/trace-mapping": "^0.3.28",
+        "jsesc": "^3.0.2"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/helper-compilation-targets": {
+      "version": "7.28.6",
+      "resolved": "https://registry.npmjs.org/@babel/helper-compilation-targets/-/helper-compilation-targets-7.28.6.tgz",
+      "integrity": "sha512-JYtls3hqi15fcx5GaSNL7SCTJ2MNmjrkHXg4FSpOA/grxK8KwyZ5bubHsCq8FXCkua6xhuaaBit+3b7+VZRfcA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/compat-data": "^7.28.6",
+        "@babel/helper-validator-option": "^7.27.1",
+        "browserslist": "^4.24.0",
+        "lru-cache": "^5.1.1",
+        "semver": "^6.3.1"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/helper-compilation-targets/node_modules/lru-cache": {
+      "version": "5.1.1",
+      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-5.1.1.tgz",
+      "integrity": "sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "yallist": "^3.0.2"
+      }
+    },
+    "node_modules/@babel/helper-compilation-targets/node_modules/semver": {
+      "version": "6.3.1",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-6.3.1.tgz",
+      "integrity": "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==",
+      "dev": true,
+      "license": "ISC",
+      "bin": {
+        "semver": "bin/semver.js"
+      }
+    },
+    "node_modules/@babel/helper-globals": {
+      "version": "7.28.0",
+      "resolved": "https://registry.npmjs.org/@babel/helper-globals/-/helper-globals-7.28.0.tgz",
+      "integrity": "sha512-+W6cISkXFa1jXsDEdYA8HeevQT/FULhxzR99pxphltZcVaugps53THCeiWA8SguxxpSp3gKPiuYfSWopkLQ4hw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/helper-module-imports": {
+      "version": "7.28.6",
+      "resolved": "https://registry.npmjs.org/@babel/helper-module-imports/-/helper-module-imports-7.28.6.tgz",
+      "integrity": "sha512-l5XkZK7r7wa9LucGw9LwZyyCUscb4x37JWTPz7swwFE/0FMQAGpiWUZn8u9DzkSBWEcK25jmvubfpw2dnAMdbw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/traverse": "^7.28.6",
+        "@babel/types": "^7.28.6"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/helper-module-transforms": {
+      "version": "7.28.6",
+      "resolved": "https://registry.npmjs.org/@babel/helper-module-transforms/-/helper-module-transforms-7.28.6.tgz",
+      "integrity": "sha512-67oXFAYr2cDLDVGLXTEABjdBJZ6drElUSI7WKp70NrpyISso3plG9SAGEF6y7zbha/wOzUByWWTJvEDVNIUGcA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/helper-module-imports": "^7.28.6",
+        "@babel/helper-validator-identifier": "^7.28.5",
+        "@babel/traverse": "^7.28.6"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      },
+      "peerDependencies": {
+        "@babel/core": "^7.0.0"
+      }
+    },
+    "node_modules/@babel/helper-plugin-utils": {
+      "version": "7.28.6",
+      "resolved": "https://registry.npmjs.org/@babel/helper-plugin-utils/-/helper-plugin-utils-7.28.6.tgz",
+      "integrity": "sha512-S9gzZ/bz83GRysI7gAD4wPT/AI3uCnY+9xn+Mx/KPs2JwHJIz1W8PZkg2cqyt3RNOBM8ejcXhV6y8Og7ly/Dug==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
     "node_modules/@babel/helper-string-parser": {
       "version": "7.27.1",
       "resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-7.27.1.tgz",
@@ -49,6 +235,30 @@
         "node": ">=6.9.0"
       }
     },
+    "node_modules/@babel/helper-validator-option": {
+      "version": "7.27.1",
+      "resolved": "https://registry.npmjs.org/@babel/helper-validator-option/-/helper-validator-option-7.27.1.tgz",
+      "integrity": "sha512-YvjJow9FxbhFFKDSuFnVCe2WxXk1zWc22fFePVNEaWJEu8IrZVlda6N0uHwzZrUM1il7NC9Mlp4MaJYbYd9JSg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/helpers": {
+      "version": "7.29.2",
+      "resolved": "https://registry.npmjs.org/@babel/helpers/-/helpers-7.29.2.tgz",
+      "integrity": "sha512-HoGuUs4sCZNezVEKdVcwqmZN8GoHirLUcLaYVNBK2J0DadGtdcqgr3BCbvH8+XUo4NGjNl3VOtSjEKNzqfFgKw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/template": "^7.28.6",
+        "@babel/types": "^7.29.0"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
     "node_modules/@babel/parser": {
       "version": "7.29.2",
       "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.29.2.tgz",
@@ -65,6 +275,72 @@
         "node": ">=6.0.0"
       }
     },
+    "node_modules/@babel/plugin-transform-react-jsx-self": {
+      "version": "7.27.1",
+      "resolved": "https://registry.npmjs.org/@babel/plugin-transform-react-jsx-self/-/plugin-transform-react-jsx-self-7.27.1.tgz",
+      "integrity": "sha512-6UzkCs+ejGdZ5mFFC/OCUrv028ab2fp1znZmCZjAOBKiBK2jXD1O+BPSfX8X2qjJ75fZBMSnQn3Rq2mrBJK2mw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/helper-plugin-utils": "^7.27.1"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      },
+      "peerDependencies": {
+        "@babel/core": "^7.0.0-0"
+      }
+    },
+    "node_modules/@babel/plugin-transform-react-jsx-source": {
+      "version": "7.27.1",
+      "resolved": "https://registry.npmjs.org/@babel/plugin-transform-react-jsx-source/-/plugin-transform-react-jsx-source-7.27.1.tgz",
+      "integrity": "sha512-zbwoTsBruTeKB9hSq73ha66iFeJHuaFkUbwvqElnygoNbj/jHRsSeokowZFN3CZ64IvEqcmmkVe89OPXc7ldAw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/helper-plugin-utils": "^7.27.1"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      },
+      "peerDependencies": {
+        "@babel/core": "^7.0.0-0"
+      }
+    },
+    "node_modules/@babel/template": {
+      "version": "7.28.6",
+      "resolved": "https://registry.npmjs.org/@babel/template/-/template-7.28.6.tgz",
+      "integrity": "sha512-YA6Ma2KsCdGb+WC6UpBVFJGXL58MDA6oyONbjyF/+5sBgxY/dwkhLogbMT2GXXyU84/IhRw/2D1Os1B/giz+BQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/code-frame": "^7.28.6",
+        "@babel/parser": "^7.28.6",
+        "@babel/types": "^7.28.6"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/traverse": {
+      "version": "7.29.0",
+      "resolved": "https://registry.npmjs.org/@babel/traverse/-/traverse-7.29.0.tgz",
+      "integrity": "sha512-4HPiQr0X7+waHfyXPZpWPfWL/J7dcN1mx9gL6WdQVMbPnF3+ZhSMs8tCxN7oHddJE9fhNE7+lxdnlyemKfJRuA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/code-frame": "^7.29.0",
+        "@babel/generator": "^7.29.0",
+        "@babel/helper-globals": "^7.28.0",
+        "@babel/parser": "^7.29.0",
+        "@babel/template": "^7.28.6",
+        "@babel/types": "^7.29.0",
+        "debug": "^4.3.1"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
     "node_modules/@babel/types": {
       "version": "7.29.0",
       "resolved": "https://registry.npmjs.org/@babel/types/-/types-7.29.0.tgz",
@@ -570,6 +846,17 @@
         "@jridgewell/trace-mapping": "^0.3.24"
       }
     },
+    "node_modules/@jridgewell/remapping": {
+      "version": "2.3.5",
+      "resolved": "https://registry.npmjs.org/@jridgewell/remapping/-/remapping-2.3.5.tgz",
+      "integrity": "sha512-LI9u/+laYG4Ds1TDKSJW2YPrIlcVYOwi2fUC6xB43lueCjgxV4lffOCZCtYFiH6TNOX+tQKXx97T4IKHbhyHEQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/gen-mapping": "^0.3.5",
+        "@jridgewell/trace-mapping": "^0.3.24"
+      }
+    },
     "node_modules/@jridgewell/resolve-uri": {
       "version": "3.1.2",
       "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz",
@@ -625,6 +912,13 @@
         "node": ">=18"
       }
     },
+    "node_modules/@rolldown/pluginutils": {
+      "version": "1.0.0-rc.3",
+      "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.0-rc.3.tgz",
+      "integrity": "sha512-eybk3TjzzzV97Dlj5c+XrBFW57eTNhzod66y9HrBlzJ6NsCrWCp/2kaPS3K9wJmurBC0Tdw4yPjXKZqlznim3Q==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@rollup/rollup-android-arm-eabi": {
       "version": "4.60.1",
       "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.60.1.tgz",
@@ -1014,6 +1308,51 @@
         "win32"
       ]
     },
+    "node_modules/@types/babel__core": {
+      "version": "7.20.5",
+      "resolved": "https://registry.npmjs.org/@types/babel__core/-/babel__core-7.20.5.tgz",
+      "integrity": "sha512-qoQprZvz5wQFJwMDqeseRXWv3rqMvhgpbXFfVyWhbx9X47POIA6i/+dXefEmZKoAgOaTdaIgNSMqMIU61yRyzA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/parser": "^7.20.7",
+        "@babel/types": "^7.20.7",
+        "@types/babel__generator": "*",
+        "@types/babel__template": "*",
+        "@types/babel__traverse": "*"
+      }
+    },
+    "node_modules/@types/babel__generator": {
+      "version": "7.27.0",
+      "resolved": "https://registry.npmjs.org/@types/babel__generator/-/babel__generator-7.27.0.tgz",
+      "integrity": "sha512-ufFd2Xi92OAVPYsy+P4n7/U7e68fex0+Ee8gSG9KX7eo084CWiQ4sdxktvdl0bOPupXtVJPY19zk6EwWqUQ8lg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/types": "^7.0.0"
+      }
+    },
+    "node_modules/@types/babel__template": {
+      "version": "7.4.4",
+      "resolved": "https://registry.npmjs.org/@types/babel__template/-/babel__template-7.4.4.tgz",
+      "integrity": "sha512-h/NUaSyG5EyxBIp8YRxo4RMe2/qQgvyowRwVMzhYhBCONbW8PUsg4lkFMrhgZhUe5z3L3MiLDuvyJ/CaPa2A8A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/parser": "^7.1.0",
+        "@babel/types": "^7.0.0"
+      }
+    },
+    "node_modules/@types/babel__traverse": {
+      "version": "7.28.0",
+      "resolved": "https://registry.npmjs.org/@types/babel__traverse/-/babel__traverse-7.28.0.tgz",
+      "integrity": "sha512-8PvcXf70gTDZBgt9ptxJ8elBeBjcLOAcOtoO/mPJjtji1+CdGbHgm77om1GrsPxsiE+uXIpNSK64UYaIwQXd4Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/types": "^7.28.2"
+      }
+    },
     "node_modules/@types/chai": {
       "version": "5.2.3",
       "resolved": "https://registry.npmjs.org/@types/chai/-/chai-5.2.3.tgz",
@@ -1039,6 +1378,57 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@types/node": {
+      "version": "25.5.0",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-25.5.0.tgz",
+      "integrity": "sha512-jp2P3tQMSxWugkCUKLRPVUpGaL5MVFwF8RDuSRztfwgN1wmqJeMSbKlnEtQqU8UrhTmzEmZdu2I6v2dpp7XIxw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~7.18.0"
+      }
+    },
+    "node_modules/@types/react": {
+      "version": "19.2.14",
+      "resolved": "https://registry.npmjs.org/@types/react/-/react-19.2.14.tgz",
+      "integrity": "sha512-ilcTH/UniCkMdtexkoCN0bI7pMcJDvmQFPvuPvmEaYA/NSfFTAgdUSLAoVjaRJm7+6PvcM+q1zYOwS4wTYMF9w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "csstype": "^3.2.2"
+      }
+    },
+    "node_modules/@types/react-dom": {
+      "version": "19.2.3",
+      "resolved": "https://registry.npmjs.org/@types/react-dom/-/react-dom-19.2.3.tgz",
+      "integrity": "sha512-jp2L/eY6fn+KgVVQAOqYItbF0VY/YApe5Mz2F0aykSO8gx31bYCZyvSeYxCHKvzHG5eZjc+zyaS5BrBWya2+kQ==",
+      "dev": true,
+      "license": "MIT",
+      "peerDependencies": {
+        "@types/react": "^19.2.0"
+      }
+    },
+    "node_modules/@vitejs/plugin-react": {
+      "version": "5.2.0",
+      "resolved": "https://registry.npmjs.org/@vitejs/plugin-react/-/plugin-react-5.2.0.tgz",
+      "integrity": "sha512-YmKkfhOAi3wsB1PhJq5Scj3GXMn3WvtQ/JC0xoopuHoXSdmtdStOpFrYaT1kie2YgFBcIe64ROzMYRjCrYOdYw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/core": "^7.29.0",
+        "@babel/plugin-transform-react-jsx-self": "^7.27.1",
+        "@babel/plugin-transform-react-jsx-source": "^7.27.1",
+        "@rolldown/pluginutils": "1.0.0-rc.3",
+        "@types/babel__core": "^7.20.5",
+        "react-refresh": "^0.18.0"
+      },
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      },
+      "peerDependencies": {
+        "vite": "^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0"
+      }
+    },
     "node_modules/@vitest/coverage-v8": {
       "version": "3.2.4",
       "resolved": "https://registry.npmjs.org/@vitest/coverage-v8/-/coverage-v8-3.2.4.tgz",
@@ -1253,6 +1643,19 @@
         "node": "18 || 20 || >=22"
       }
     },
+    "node_modules/baseline-browser-mapping": {
+      "version": "2.10.13",
+      "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.10.13.tgz",
+      "integrity": "sha512-BL2sTuHOdy0YT1lYieUxTw/QMtPBC3pmlJC6xk8BBYVv6vcw3SGdKemQ+Xsx9ik2F/lYDO9tqsFQH1r9PFuHKw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "baseline-browser-mapping": "dist/cli.cjs"
+      },
+      "engines": {
+        "node": ">=6.0.0"
+      }
+    },
     "node_modules/brace-expansion": {
       "version": "5.0.5",
       "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.5.tgz",
@@ -1266,6 +1669,40 @@
         "node": "18 || 20 || >=22"
       }
     },
+    "node_modules/browserslist": {
+      "version": "4.28.2",
+      "resolved": "https://registry.npmjs.org/browserslist/-/browserslist-4.28.2.tgz",
+      "integrity": "sha512-48xSriZYYg+8qXna9kwqjIVzuQxi+KYWp2+5nCYnYKPTr0LvD89Jqk2Or5ogxz0NUMfIjhh2lIUX/LyX9B4oIg==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/browserslist"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/funding/github/npm/browserslist"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "baseline-browser-mapping": "^2.10.12",
+        "caniuse-lite": "^1.0.30001782",
+        "electron-to-chromium": "^1.5.328",
+        "node-releases": "^2.0.36",
+        "update-browserslist-db": "^1.2.3"
+      },
+      "bin": {
+        "browserslist": "cli.js"
+      },
+      "engines": {
+        "node": "^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7"
+      }
+    },
     "node_modules/cac": {
       "version": "6.7.14",
       "resolved": "https://registry.npmjs.org/cac/-/cac-6.7.14.tgz",
@@ -1276,6 +1713,27 @@
         "node": ">=8"
       }
     },
+    "node_modules/caniuse-lite": {
+      "version": "1.0.30001784",
+      "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001784.tgz",
+      "integrity": "sha512-WU346nBTklUV9YfUl60fqRbU5ZqyXlqvo1SgigE1OAXK5bFL8LL9q1K7aap3N739l4BvNqnkm3YrGHiY9sfUQw==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/browserslist"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/funding/github/npm/caniuse-lite"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "CC-BY-4.0"
+    },
     "node_modules/chai": {
       "version": "5.3.3",
       "resolved": "https://registry.npmjs.org/chai/-/chai-5.3.3.tgz",
@@ -1323,6 +1781,13 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/convert-source-map": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/convert-source-map/-/convert-source-map-2.0.0.tgz",
+      "integrity": "sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/cross-spawn": {
       "version": "7.0.6",
       "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz",
@@ -1338,6 +1803,13 @@
         "node": ">= 8"
       }
     },
+    "node_modules/csstype": {
+      "version": "3.2.3",
+      "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.2.3.tgz",
+      "integrity": "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/debug": {
       "version": "4.4.3",
       "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
@@ -1373,6 +1845,13 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/electron-to-chromium": {
+      "version": "1.5.331",
+      "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.331.tgz",
+      "integrity": "sha512-IbxXrsTlD3hRodkLnbxAPP4OuJYdWCeM3IOdT+CpcMoIwIoDfCmRpEtSPfwBXxVkg9xmBeY7Lz2Eo2TDn/HC3Q==",
+      "dev": true,
+      "license": "ISC"
+    },
     "node_modules/emoji-regex": {
       "version": "9.2.2",
       "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-9.2.2.tgz",
@@ -1429,6 +1908,16 @@
         "@esbuild/win32-x64": "0.27.4"
       }
     },
+    "node_modules/escalade": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz",
+      "integrity": "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/estree-walker": {
       "version": "3.0.3",
       "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-3.0.3.tgz",
@@ -1499,6 +1988,16 @@
         "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
       }
     },
+    "node_modules/gensync": {
+      "version": "1.0.0-beta.2",
+      "resolved": "https://registry.npmjs.org/gensync/-/gensync-1.0.0-beta.2.tgz",
+      "integrity": "sha512-3hN7NaskYvMDLQY55gnW3NQ+mesEAepTqlg+VEbj7zzqEMBVNhzcGYYeqFo/TlYz6eQiFcp1HcsCZO+nGgS8zg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
     "node_modules/glob": {
       "version": "10.5.0",
       "resolved": "https://registry.npmjs.org/glob/-/glob-10.5.0.tgz",
@@ -1665,6 +2164,32 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/jsesc": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/jsesc/-/jsesc-3.1.0.tgz",
+      "integrity": "sha512-/sM3dO2FOzXjKQhJuo0Q173wf2KOo8t4I8vHy6lF9poUp7bKT0/NHE8fPX23PwfhnykfqnC2xRxOnVw5XuGIaA==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "jsesc": "bin/jsesc"
+      },
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/json5": {
+      "version": "2.2.3",
+      "resolved": "https://registry.npmjs.org/json5/-/json5-2.2.3.tgz",
+      "integrity": "sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "json5": "lib/cli.js"
+      },
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/loupe": {
       "version": "3.2.1",
       "resolved": "https://registry.npmjs.org/loupe/-/loupe-3.2.1.tgz",
@@ -1769,6 +2294,13 @@
         "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"
       }
     },
+    "node_modules/node-releases": {
+      "version": "2.0.37",
+      "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.37.tgz",
+      "integrity": "sha512-1h5gKZCF+pO/o3Iqt5Jp7wc9rH3eJJ0+nh/CIoiRwjRxde/hAHyLPXYN4V3CqKAbiZPSeJFSWHmJsbkicta0Eg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/package-json-from-dist": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/package-json-from-dist/-/package-json-from-dist-1.0.1.tgz",
@@ -1916,6 +2448,39 @@
         "node": "^10 || ^12 || >=14"
       }
     },
+    "node_modules/react": {
+      "version": "19.2.4",
+      "resolved": "https://registry.npmjs.org/react/-/react-19.2.4.tgz",
+      "integrity": "sha512-9nfp2hYpCwOjAN+8TZFGhtWEwgvWHXqESH8qT89AT/lWklpLON22Lc8pEtnpsZz7VmawabSU0gCjnj8aC0euHQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/react-dom": {
+      "version": "19.2.4",
+      "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.2.4.tgz",
+      "integrity": "sha512-AXJdLo8kgMbimY95O2aKQqsz2iWi9jMgKJhRBAxECE4IFxfcazB2LmzloIoibJI3C12IlY20+KFaLv+71bUJeQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "scheduler": "^0.27.0"
+      },
+      "peerDependencies": {
+        "react": "^19.2.4"
+      }
+    },
+    "node_modules/react-refresh": {
+      "version": "0.18.0",
+      "resolved": "https://registry.npmjs.org/react-refresh/-/react-refresh-0.18.0.tgz",
+      "integrity": "sha512-QgT5//D3jfjJb6Gsjxv0Slpj23ip+HtOpnNgnb2S5zU3CB26G/IDPGoy4RJB42wzFE46DRsstbW6tKHoKbhAxw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/rollup": {
       "version": "4.60.1",
       "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.60.1.tgz",
@@ -1961,6 +2526,13 @@
         "fsevents": "~2.3.2"
       }
     },
+    "node_modules/scheduler": {
+      "version": "0.27.0",
+      "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.27.0.tgz",
+      "integrity": "sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/semver": {
       "version": "7.7.4",
       "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.4.tgz",
@@ -2261,6 +2833,44 @@
         "node": ">=14.17"
       }
     },
+    "node_modules/undici-types": {
+      "version": "7.18.2",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.18.2.tgz",
+      "integrity": "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/update-browserslist-db": {
+      "version": "1.2.3",
+      "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.2.3.tgz",
+      "integrity": "sha512-Js0m9cx+qOgDxo0eMiFGEueWztz+d4+M3rGlmKPT+T4IS/jP4ylw3Nwpu6cpTTP8R1MAC1kF4VbdLt3ARf209w==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/browserslist"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/funding/github/npm/browserslist"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "escalade": "^3.2.0",
+        "picocolors": "^1.1.1"
+      },
+      "bin": {
+        "update-browserslist-db": "cli.js"
+      },
+      "peerDependencies": {
+        "browserslist": ">= 4.21.0"
+      }
+    },
     "node_modules/vite": {
       "version": "7.3.1",
       "resolved": "https://registry.npmjs.org/vite/-/vite-7.3.1.tgz",
@@ -2562,6 +3172,13 @@
       "engines": {
         "node": ">=8"
       }
+    },
+    "node_modules/yallist": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/yallist/-/yallist-3.1.1.tgz",
+      "integrity": "sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==",
+      "dev": true,
+      "license": "ISC"
     }
   }
 }
diff --git a/package.json b/package.json
index 3b63e85..5fb75f1 100644
--- a/package.json
+++ b/package.json
@@ -1,10 +1,12 @@
 {
   "name": "shape-text",
   "version": "0.1.0",
-  "description": "Browser-first TypeScript library for laying out text inside polygon shapes and rendering to SVG.",
+  "description": "Browser-first TypeScript library for shape-paragraph layout inside geometry and value-derived shapes, rendered to SVG.",
   "type": "module",
   "main": "./dist/index.js",
+  "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -12,29 +14,48 @@
       "default": "./dist/index.js"
     }
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tqdat410/shape-text.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tqdat410/shape-text/issues"
+  },
+  "homepage": "https://github.com/tqdat410/shape-text#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18",
+    "bun": ">=1.0.0"
+  },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage",
-    "check": "npm run typecheck && npm run test",
-    "e2e": "node ./node_modules/@playwright/test/cli.js test",
-    "e2e:ui": "node ./node_modules/@playwright/test/cli.js test --ui",
-    "e2e:headed": "node ./node_modules/@playwright/test/cli.js test --headed",
-    "e2e:debug": "node ./node_modules/@playwright/test/cli.js test --debug",
-    "e2e:serve": "node ./scripts/run-e2e-serve.mjs",
-    "e2e:serve:dev": "node ./scripts/run-e2e-serve.mjs --skip-build",
-    "demo": "node ./scripts/run-e2e-serve.mjs",
-    "demo:dev": "node ./scripts/run-e2e-serve.mjs --skip-build"
+    "build": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('scripts/run-library-build.mjs')\"",
+    "typecheck": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('node_modules/typescript/bin/tsc',['-p','tsconfig.json','--noEmit'])\"",
+    "test": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('node_modules/vitest/vitest.mjs',['run'])\"",
+    "test:coverage": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('node_modules/vitest/vitest.mjs',['run','--coverage'])\"",
+    "check": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('scripts/run-project-check.mjs')\"",
+    "e2e": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('node_modules/@playwright/test/cli.js',['test'])\"",
+    "e2e:ui": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('node_modules/@playwright/test/cli.js',['test','--ui'])\"",
+    "e2e:headed": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('node_modules/@playwright/test/cli.js',['test','--headed'])\"",
+    "e2e:debug": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('node_modules/@playwright/test/cli.js',['test','--debug'])\"",
+    "demo": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('scripts/run-demo-app.mjs')\"",
+    "demo:dev": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('scripts/run-demo-app.mjs')\"",
+    "demo:build": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('scripts/run-demo-app.mjs',['--build'])\"",
+    "demo:preview": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('scripts/run-demo-app.mjs',['--preview'])\"",
+    "prepack": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('scripts/run-library-build.mjs')\"",
+    "ship:check": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('scripts/run-library-ship-check.mjs')\""
   },
   "keywords": [
     "svg",
     "text-layout",
     "shape-text",
+    "shape-paragraph",
     "polygon",
     "typography"
   ],
@@ -42,8 +63,15 @@
   "license": "MIT",
   "devDependencies": {
     "@playwright/test": "^1.58.2",
+    "@types/node": "^25.5.0",
+    "@types/react": "^19.2.2",
+    "@types/react-dom": "^19.2.2",
+    "@vitejs/plugin-react": "^5.1.0",
     "@vitest/coverage-v8": "^3.2.4",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
     "typescript": "^5.9.3",
+    "vite": "^7.1.12",
     "vitest": "^3.2.4"
   }
 }
diff --git a/playwright.config.ts b/playwright.config.ts
index f382c44..a07a963 100644
--- a/playwright.config.ts
+++ b/playwright.config.ts
@@ -1,6 +1,11 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
 import { defineConfig } from '@playwright/test'
 
-const port = Number(process.env.PLAYWRIGHT_PORT ?? 4173)
+const rootDir = path.dirname(fileURLToPath(import.meta.url))
+const demoScript = path.resolve(rootDir, 'scripts/run-demo-app.mjs')
+const port = Number(process.env.PLAYWRIGHT_PORT ?? 4174)
 const baseURL = `http://127.0.0.1:${port}`
 
 export default defineConfig({
@@ -13,7 +18,7 @@ export default defineConfig({
     trace: 'on-first-retry',
   },
   webServer: {
-    command: 'node ./scripts/run-e2e-serve.mjs',
+    command: `"${process.execPath}" "${demoScript}" --preview`,
     url: `${baseURL}/`,
     reuseExistingServer: !process.env.CI,
     timeout: 120_000,
diff --git a/scripts/run-demo-app.mjs b/scripts/run-demo-app.mjs
new file mode 100644
index 0000000..9284575
--- /dev/null
+++ b/scripts/run-demo-app.mjs
@@ -0,0 +1,71 @@
+import { spawn } from 'node:child_process'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url))
+const rootDir = path.resolve(scriptDir, '..')
+const viteCli = path.resolve(rootDir, 'node_modules/vite/bin/vite.js')
+const viteConfig = path.resolve(rootDir, 'demo/vite.config.ts')
+const port = String(Number(process.env.PORT ?? 4173))
+const isPreview = process.argv.includes('--preview')
+const isBuildOnly = process.argv.includes('--build')
+
+function spawnVite(args) {
+  return spawn(process.execPath, [viteCli, ...args], {
+    cwd: rootDir,
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      PORT: port,
+    },
+  })
+}
+
+function runVite(args) {
+  return new Promise((resolve, reject) => {
+    const child = spawnVite(args)
+
+    child.once('error', reject)
+    child.once('exit', code => {
+      if (code && code !== 0) {
+        reject(new Error(`vite exited with code ${code}`))
+        return
+      }
+
+      resolve()
+    })
+  })
+}
+
+if (isBuildOnly || isPreview) {
+  await runVite(['build', '--config', viteConfig])
+}
+
+if (isBuildOnly) {
+  process.exit(0)
+}
+
+const serveArgs = [
+  ...(isPreview ? ['preview'] : []),
+  '--config',
+  viteConfig,
+  '--host',
+  '127.0.0.1',
+  '--port',
+  port,
+]
+
+if (process.env.CI) {
+  serveArgs.push('--strictPort')
+}
+
+const child = spawnVite(serveArgs)
+
+child.once('error', error => {
+  console.error(error)
+  process.exit(1)
+})
+
+child.once('exit', code => {
+  process.exit(code ?? 0)
+})
diff --git a/scripts/run-e2e-serve.mjs b/scripts/run-e2e-serve.mjs
deleted file mode 100644
index bcafb69..0000000
--- a/scripts/run-e2e-serve.mjs
+++ /dev/null
@@ -1,36 +0,0 @@
-import { spawn } from 'node:child_process'
-import path from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-const scriptDir = path.dirname(fileURLToPath(import.meta.url))
-const rootDir = path.resolve(scriptDir, '..')
-const skipBuild = process.argv.includes('--skip-build')
-
-function runBuild() {
-  return new Promise((resolve, reject) => {
-    const child = spawn(
-      process.execPath,
-      ['./node_modules/typescript/lib/tsc.js', '-p', 'tsconfig.build.json'],
-      {
-        cwd: rootDir,
-        stdio: 'inherit',
-      },
-    )
-
-    child.once('error', reject)
-    child.once('exit', (code) => {
-      if (code === 0) {
-        resolve()
-        return
-      }
-
-      reject(new Error(`Build failed with exit code ${code ?? 'unknown'}`))
-    })
-  })
-}
-
-if (!skipBuild) {
-  await runBuild()
-}
-
-await import('./serve-static-e2e.mjs')
diff --git a/scripts/run-library-build.mjs b/scripts/run-library-build.mjs
new file mode 100644
index 0000000..bd9c937
--- /dev/null
+++ b/scripts/run-library-build.mjs
@@ -0,0 +1,33 @@
+import { rm } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { spawn } from 'node:child_process'
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url))
+const rootDir = path.resolve(scriptDir, '..')
+const distDir = path.resolve(rootDir, 'dist')
+const typeScriptCli = path.resolve(rootDir, 'node_modules/typescript/bin/tsc')
+
+function runNode(entryPath, args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [entryPath, ...args], {
+      cwd: rootDir,
+      stdio: 'inherit',
+      env: process.env,
+    })
+
+    child.once('error', reject)
+    child.once('exit', code => {
+      if (code && code !== 0) {
+        reject(new Error(`${path.basename(entryPath)} exited with code ${code}`))
+        return
+      }
+
+      resolve()
+    })
+  })
+}
+
+await rm(distDir, { recursive: true, force: true })
+await runNode(typeScriptCli, ['-p', 'tsconfig.build.json'])
diff --git a/scripts/run-library-ship-check.mjs b/scripts/run-library-ship-check.mjs
new file mode 100644
index 0000000..848be8f
--- /dev/null
+++ b/scripts/run-library-ship-check.mjs
@@ -0,0 +1,167 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { spawn } from 'node:child_process'
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url))
+const rootDir = path.resolve(scriptDir, '..')
+const buildScript = path.resolve(rootDir, 'scripts/run-library-build.mjs')
+const skipBuild = process.argv.includes('--skip-build')
+
+function resolveCommand(command) {
+  if (process.platform === 'win32' && command === 'npm') {
+    return 'npm.cmd'
+  }
+
+  return command
+}
+
+function quoteShellArg(value) {
+  if (value === '') {
+    return '""'
+  }
+
+  if (!/[ \t"]/u.test(value)) {
+    return value
+  }
+
+  return `"${value.replace(/"/g, '\\"')}"`
+}
+
+function run(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const resolvedCommand = resolveCommand(command)
+    const useShell = process.platform === 'win32' && !path.isAbsolute(resolvedCommand)
+    const child = spawn(
+      useShell
+        ? [command, ...args].map(quoteShellArg).join(' ')
+        : resolvedCommand,
+      useShell ? [] : args,
+      {
+      cwd: options.cwd ?? rootDir,
+      env: options.env ?? process.env,
+      stdio: options.capture ? 'pipe' : 'inherit',
+      shell: useShell,
+    })
+
+    let stdout = ''
+    let stderr = ''
+
+    if (options.capture) {
+      child.stdout?.on('data', chunk => {
+        stdout += String(chunk)
+      })
+      child.stderr?.on('data', chunk => {
+        stderr += String(chunk)
+      })
+    }
+
+    child.once('error', reject)
+    child.once('exit', code => {
+      if (code && code !== 0) {
+        reject(
+          new Error(
+            `${command} ${args.join(' ')} exited with code ${code}${
+              stderr ? `\n${stderr.trim()}` : ''
+            }`,
+          ),
+        )
+        return
+      }
+
+      resolve(stdout.trim())
+    })
+  })
+}
+
+async function createConsumerWorkspace(prefix, runner) {
+  const consumerDir = await mkdtemp(path.join(os.tmpdir(), `${prefix}-`))
+  const packageJson = {
+    name: prefix,
+    private: true,
+    type: 'module',
+  }
+const smokeScript = `import { normalizeTextStyleToFont, prepareTextForLayout } from 'shape-text'
+
+const style = normalizeTextStyleToFont({
+  family: 'Arial, sans-serif',
+  size: 16,
+  weight: 700,
+})
+
+if (!style.font.includes('16px')) {
+  throw new Error('Expected normalized font to include 16px')
+}
+
+const prepared = prepareTextForLayout('A B', style.font, {
+  measureText(text) {
+    return text.length * 10
+  },
+})
+
+if (prepared.tokens.length !== 2) {
+  throw new Error('Expected two measured tokens for A B')
+}
+`
+
+  await writeFile(path.join(consumerDir, 'package.json'), JSON.stringify(packageJson, null, 2))
+  await writeFile(path.join(consumerDir, 'smoke.mjs'), smokeScript)
+
+  return {
+    consumerDir,
+    install(tarballPath) {
+      return run(runner, runner === 'bun' ? ['add', tarballPath] : ['install', tarballPath], {
+        cwd: consumerDir,
+      })
+    },
+    execute() {
+      return run(runner === 'bun' ? 'bun' : 'node', ['smoke.mjs'], {
+        cwd: consumerDir,
+      })
+    },
+  }
+}
+
+async function createTarball(packDir) {
+  const npmPackOutput = await run(
+    'npm',
+    ['pack', '--ignore-scripts', '--json', '--pack-destination', packDir],
+    { capture: true },
+  )
+  const parsed = JSON.parse(npmPackOutput)
+  const tarballName = parsed[0]?.filename
+  if (typeof tarballName !== 'string') {
+    throw new Error('npm pack did not return a tarball filename')
+  }
+
+  return path.resolve(packDir, tarballName)
+}
+
+if (!skipBuild) {
+  await run(process.execPath, [buildScript])
+}
+
+const packDir = await mkdtemp(path.join(os.tmpdir(), 'shape-text-pack-'))
+
+try {
+  const tarballPath = await createTarball(packDir)
+
+  await run('bun', ['pm', 'pack', '--ignore-scripts', '--dry-run'])
+
+  const npmConsumer = await createConsumerWorkspace('shape-text-npm-smoke', 'npm')
+  const bunConsumer = await createConsumerWorkspace('shape-text-bun-smoke', 'bun')
+
+  try {
+    await npmConsumer.install(tarballPath)
+    await npmConsumer.execute()
+    await bunConsumer.install(tarballPath)
+    await bunConsumer.execute()
+  } finally {
+    await rm(npmConsumer.consumerDir, { recursive: true, force: true })
+    await rm(bunConsumer.consumerDir, { recursive: true, force: true })
+  }
+} finally {
+  await rm(packDir, { recursive: true, force: true })
+}
diff --git a/scripts/run-node-script-from-package-root.cjs b/scripts/run-node-script-from-package-root.cjs
new file mode 100644
index 0000000..9aed16e
--- /dev/null
+++ b/scripts/run-node-script-from-package-root.cjs
@@ -0,0 +1,35 @@
+const { spawn } = require('node:child_process')
+const path = require('node:path')
+
+function getPackageRoot() {
+  const packageJsonPath = String(process.env.npm_package_json ?? '').replace(/^\\\\\?\\/, '')
+
+  if (!packageJsonPath) {
+    throw new Error('npm_package_json is missing; cannot resolve package root')
+  }
+
+  return path.dirname(packageJsonPath)
+}
+
+function run(relativeEntryPath, args = []) {
+  const rootDir = getPackageRoot()
+  const entryPath = path.resolve(rootDir, relativeEntryPath)
+  const child = spawn(process.execPath, [entryPath, ...args], {
+    cwd: rootDir,
+    stdio: 'inherit',
+    env: process.env,
+  })
+
+  child.once('error', error => {
+    console.error(error)
+    process.exit(1)
+  })
+
+  child.once('exit', code => {
+    process.exit(code ?? 0)
+  })
+}
+
+module.exports = {
+  run,
+}
diff --git a/scripts/run-project-check.mjs b/scripts/run-project-check.mjs
new file mode 100644
index 0000000..ee27c6c
--- /dev/null
+++ b/scripts/run-project-check.mjs
@@ -0,0 +1,31 @@
+import { spawn } from 'node:child_process'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url))
+const rootDir = path.resolve(scriptDir, '..')
+const typeScriptCli = path.resolve(rootDir, 'node_modules/typescript/bin/tsc')
+const vitestCli = path.resolve(rootDir, 'node_modules/vitest/vitest.mjs')
+
+function runNode(entryPath, args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [entryPath, ...args], {
+      cwd: rootDir,
+      stdio: 'inherit',
+      env: process.env,
+    })
+
+    child.once('error', reject)
+    child.once('exit', code => {
+      if (code && code !== 0) {
+        reject(new Error(`${path.basename(entryPath)} exited with code ${code}`))
+        return
+      }
+
+      resolve()
+    })
+  })
+}
+
+await runNode(typeScriptCli, ['-p', 'tsconfig.json', '--noEmit'])
+await runNode(vitestCli, ['run'])
diff --git a/scripts/serve-static-e2e.mjs b/scripts/serve-static-e2e.mjs
deleted file mode 100644
index b0d69a7..0000000
--- a/scripts/serve-static-e2e.mjs
+++ /dev/null
@@ -1,57 +0,0 @@
-import { createServer } from 'node:http'
-import { readFile } from 'node:fs/promises'
-import path from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-const port = Number(process.env.PORT ?? 4173)
-const scriptDir = path.dirname(fileURLToPath(import.meta.url))
-const rootDir = path.resolve(scriptDir, '..')
-
-const contentTypes = new Map([
-  ['.css', 'text/css; charset=utf-8'],
-  ['.html', 'text/html; charset=utf-8'],
-  ['.js', 'text/javascript; charset=utf-8'],
-  ['.json', 'application/json; charset=utf-8'],
-  ['.mjs', 'text/javascript; charset=utf-8'],
-  ['.svg', 'image/svg+xml'],
-])
-
-function resolveRequestPath(urlPath) {
-  const normalizedPath = urlPath === '/' ? '/e2e/fixtures/index.html' : urlPath
-  const diskPath = path.resolve(rootDir, `.${normalizedPath}`)
-
-  if (!diskPath.startsWith(rootDir)) {
-    return null
-  }
-
-  return diskPath
-}
-
-const server = createServer(async (request, response) => {
-  const requestPath = request.url ? new URL(request.url, `http://127.0.0.1:${port}`).pathname : '/'
-  const diskPath = resolveRequestPath(requestPath)
-
-  if (diskPath === null) {
-    response.writeHead(403)
-    response.end('Forbidden')
-    return
-  }
-
-  try {
-    const file = await readFile(diskPath)
-    const ext = path.extname(diskPath)
-    response.writeHead(200, {
-      'cache-control': 'no-store',
-      'content-type': contentTypes.get(ext) ?? 'application/octet-stream',
-    })
-    response.end(file)
-  } catch {
-    response.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' })
-    response.end(`Not found: ${requestPath}`)
-  }
-})
-
-server.listen(port, '127.0.0.1', () => {
-  process.stdout.write(`shape-text e2e server listening on http://127.0.0.1:${port}\n`)
-})
-
diff --git a/src/index.ts b/src/index.ts
index e6d7007..41418e5 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,10 +1,8 @@
 export type {
-  AutoFillMode,
   CompiledShapeBand,
   CompiledShapeBands,
   CompiledShapeRegion,
   CompileShapeForLayoutOptions,
-  FillStrategy,
   Interval,
   LayoutCursor,
   LayoutLineRange,
diff --git a/src/layout/layout-flow-lines-in-compiled-shape.ts b/src/layout/layout-flow-lines-in-compiled-shape.ts
index d19680b..044e8c0 100644
--- a/src/layout/layout-flow-lines-in-compiled-shape.ts
+++ b/src/layout/layout-flow-lines-in-compiled-shape.ts
@@ -1,14 +1,10 @@
 import type {
-  AutoFillMode,
   CompiledShapeBands,
   LayoutCursor,
   PreparedLayoutText,
-  PreparedLayoutToken,
   ShapeTextLine,
 } from '../types.js'
 import { layoutNextLineFromPreparedText } from '../text/layout-next-line-from-prepared-text.js'
-import { layoutNextLineFromRepeatedText } from '../text/layout-next-line-from-repeated-text.js'
-import { layoutDenseFillPass } from './layout-dense-fill-pass.js'
 
 function pickWidestInterval(intervals: CompiledShapeBands['bands'][number]['intervals']) {
   let best = intervals[0]!
@@ -25,10 +21,7 @@ function pickWidestInterval(intervals: CompiledShapeBands['bands'][number]['inte
 
 type LayoutFlowLinesInCompiledShapeOptions = {
   compiledShape: CompiledShapeBands
-  prepared?: PreparedLayoutText
-  densePattern?: PreparedLayoutToken
-  autoFill: boolean
-  autoFillMode: AutoFillMode
+  prepared: PreparedLayoutText
   align: 'left' | 'center'
   baselineRatio: number
   startCursor: LayoutCursor
@@ -50,32 +43,11 @@ export function layoutFlowLinesInCompiledShape(
     }
 
     const slot = pickWidestInterval(band.intervals)
-    if (options.autoFill && options.autoFillMode === 'dense') {
-      const denseLine =
-        layoutDenseFillPass({
-          compiledShape: {
-            ...options.compiledShape,
-            bands: [{ ...band, intervals: [slot] }],
-          },
-          densePattern: options.densePattern!,
-          startOffset: cursor.tokenIndex,
-          align: options.align,
-          baselineRatio: options.baselineRatio,
-          allSlots: false,
-        }).lines[0] ?? null
-
-      if (denseLine === null) {
-        break
-      }
-
-      lines.push(denseLine)
-      cursor = denseLine.end
-      continue
-    }
-
-    const line = options.autoFill
-      ? layoutNextLineFromRepeatedText(options.prepared!, cursor, slot.right - slot.left)
-      : layoutNextLineFromPreparedText(options.prepared!, cursor, slot.right - slot.left)
+    const line = layoutNextLineFromPreparedText(
+      options.prepared,
+      cursor,
+      slot.right - slot.left,
+    )
 
     if (line === null) {
       break
diff --git a/src/layout/layout-text-in-compiled-shape.ts b/src/layout/layout-text-in-compiled-shape.ts
index 047bb37..b0db463 100644
--- a/src/layout/layout-text-in-compiled-shape.ts
+++ b/src/layout/layout-text-in-compiled-shape.ts
@@ -1,4 +1,4 @@
-import type { AutoFillMode, FillStrategy, LayoutTextInCompiledShapeOptions, ShapeTextLayout } from '../types.js'
+import type { LayoutTextInCompiledShapeOptions, ShapeTextLayout } from '../types.js'
 import { resolveFlowLayout } from './resolve-flow-layout.js'
 import { resolveMaxFillLayout } from './resolve-max-fill-layout.js'
 import {
@@ -9,17 +9,13 @@ import {
 export function layoutTextInCompiledShape(
   options: LayoutTextInCompiledShapeOptions,
 ): ShapeTextLayout {
-  const autoFill = options.autoFill ?? false
-  const autoFillMode: AutoFillMode = autoFill ? (options.autoFillMode ?? 'words') : 'words'
-  const fillStrategy: FillStrategy = autoFill ? (options.fillStrategy ?? 'flow') : 'flow'
-
   if (hasSequentialShapeRegions(options.compiledShape)) {
     return resolveSequentialShapeRegions(options)
   }
 
-  if (fillStrategy === 'max') {
+  if (options.autoFill === true) {
     return resolveMaxFillLayout(options)
   }
 
-  return resolveFlowLayout(options, autoFillMode)
+  return resolveFlowLayout(options)
 }
diff --git a/src/layout/layout-text-in-shape.test.ts b/src/layout/layout-text-in-shape.test.ts
index d7767cc..5414ce9 100644
--- a/src/layout/layout-text-in-shape.test.ts
+++ b/src/layout/layout-text-in-shape.test.ts
@@ -99,19 +99,17 @@ describe('layoutTextInShape', () => {
       measurer: createFixedWidthTextMeasurer(),
     })
 
-    expect(layout.lines.map(line => line.text)).toEqual(['ONE ONE', 'ONE ONE', 'ONE ONE'])
+    expect(layout.lines.map(line => line.text)).toEqual(['ONEONEONEO', 'NEONEONEON', 'EONEONEONE'])
     expect(layout.autoFill).toBe(true)
-    expect(layout.autoFillMode).toBe('words')
     expect(layout.exhausted).toBe(false)
   })
 
-  it('supports dense auto-fill by ignoring spaces and word boundaries', () => {
+  it('keeps spaces in the repeat stream while filling max coverage', () => {
     const layout = layoutTextInShape({
-      text: 'ONE',
+      text: 'A B',
       font: '16px Test Sans',
       lineHeight: 20,
       autoFill: true,
-      autoFillMode: 'dense',
       shape: {
         kind: 'polygon',
         points: [
@@ -124,10 +122,8 @@ describe('layoutTextInShape', () => {
       measurer: createFixedWidthTextMeasurer(),
     })
 
-    expect(layout.autoFillMode).toBe('dense')
-    expect(layout.lines[0]?.text).toBe('ONEONEONEO')
-    expect(layout.lines[0]?.width).toBe(100)
-    expect(layout.lines[0]?.text).not.toContain(' ')
+    expect(layout.lines.map(line => line.text)).toEqual(['A BA BA BA', ' BA BA BA ', 'BA BA BA B'])
+    expect(layout.lines.some(line => line.text.includes(' '))).toBe(true)
   })
 
   it('supports max fill by sweeping every slot in a band', () => {
@@ -135,7 +131,6 @@ describe('layoutTextInShape', () => {
       text: 'A B',
       font: '16px Test Sans',
       autoFill: true,
-      fillStrategy: 'max',
       compiledShape: {
         kind: 'polygon',
         source: {
@@ -173,8 +168,6 @@ describe('layoutTextInShape', () => {
       measurer: createFixedWidthTextMeasurer(),
     })
 
-    expect(layout.fillStrategy).toBe('max')
-    expect(layout.autoFillMode).toBe('stream')
     expect(layout.lines.map(line => [line.text, line.x, line.fillPass])).toEqual([
       ['A B', 0, 1],
       ['A B', 70, 1],
@@ -290,39 +283,15 @@ describe('layoutTextInShape', () => {
     })
 
     expect(layout.lines.map(line => line.text)).toEqual(['ABCD'])
-    expect(layout.fillStrategy).toBe('flow')
-  })
-
-  it('strips whitespace and continues dense fill across line boundaries', () => {
-    const layout = layoutTextInShape({
-      text: 'A B',
-      font: '16px Test Sans',
-      lineHeight: 20,
-      autoFill: true,
-      autoFillMode: 'dense',
-      shape: {
-        kind: 'polygon',
-        points: [
-          { x: 0, y: 0 },
-          { x: 50, y: 0 },
-          { x: 50, y: 40 },
-          { x: 0, y: 40 },
-        ],
-      },
-      measurer: createFixedWidthTextMeasurer(),
-    })
-
-    expect(layout.lines.map(line => line.text)).toEqual(['ABABA', 'BABAB'])
   })
 
-  it('rejects dense auto-fill when the source becomes whitespace-only', () => {
+  it('rejects empty max-fill input', () => {
     expect(() =>
       layoutTextInShape({
-        text: ' \n\t ',
+        text: '',
         font: '16px Test Sans',
         lineHeight: 20,
         autoFill: true,
-        autoFillMode: 'dense',
         shape: {
           kind: 'polygon',
           points: [
@@ -334,15 +303,14 @@ describe('layoutTextInShape', () => {
         },
         measurer: createFixedWidthTextMeasurer(),
       }),
-    ).toThrow('dense autoFill requires at least one non-whitespace grapheme')
+    ).toThrow('stream autoFill requires at least one grapheme')
   })
 
-  it('keeps empty word auto-fill exhausted state unchanged', () => {
+  it('keeps non-auto-fill empty text layout unchanged', () => {
     const layout = layoutTextInShape({
       text: '',
       font: '16px Test Sans',
       lineHeight: 20,
-      autoFill: true,
       shape: {
         kind: 'polygon',
         points: [
@@ -357,7 +325,6 @@ describe('layoutTextInShape', () => {
 
     expect(layout.lines).toHaveLength(0)
     expect(layout.exhausted).toBe(true)
-    expect(layout.autoFillMode).toBe('words')
   })
 
   it('normalizes textStyle into the resolved layout font and color', () => {
diff --git a/src/layout/layout-text-in-shape.ts b/src/layout/layout-text-in-shape.ts
index 3007f89..246a89d 100644
--- a/src/layout/layout-text-in-shape.ts
+++ b/src/layout/layout-text-in-shape.ts
@@ -3,7 +3,7 @@ import { compileShapeForLayout } from '../shape/compile-shape-for-layout.js'
 import { layoutTextInCompiledShape } from './layout-text-in-compiled-shape.js'
 
 function resolveCompileMinSlotWidth(options: LayoutTextInShapeOptions): number | undefined {
-  if (options.fillStrategy !== 'max' || options.autoFill !== true) {
+  if (options.autoFill !== true) {
     return options.minSlotWidth
   }
 
@@ -31,8 +31,6 @@ export function layoutTextInShape(options: LayoutTextInShapeOptions): ShapeTextL
       align: options.align,
       baselineRatio: options.baselineRatio,
       autoFill: options.autoFill,
-      autoFillMode: options.autoFillMode,
-      fillStrategy: options.fillStrategy,
     })
   }
 
@@ -44,7 +42,5 @@ export function layoutTextInShape(options: LayoutTextInShapeOptions): ShapeTextL
     align: options.align,
     baselineRatio: options.baselineRatio,
     autoFill: options.autoFill,
-    autoFillMode: options.autoFillMode,
-    fillStrategy: options.fillStrategy,
   })
 }
diff --git a/src/layout/resolve-flow-layout.ts b/src/layout/resolve-flow-layout.ts
index 12dd1bb..0f3260f 100644
--- a/src/layout/resolve-flow-layout.ts
+++ b/src/layout/resolve-flow-layout.ts
@@ -1,12 +1,10 @@
-import type { AutoFillMode, LayoutTextInCompiledShapeOptions, ShapeTextLayout } from '../types.js'
+import type { LayoutTextInCompiledShapeOptions, ShapeTextLayout } from '../types.js'
 import { resolveLayoutTextStyle } from '../text/normalize-text-style-to-font.js'
-import { prepareDenseRepeatFillPattern } from '../text/prepare-dense-repeat-fill-pattern.js'
 import { prepareTextForLayout } from '../text/prepare-text-for-layout.js'
 import { layoutFlowLinesInCompiledShape } from './layout-flow-lines-in-compiled-shape.js'
 
 export function resolveFlowLayout(
   options: LayoutTextInCompiledShapeOptions,
-  autoFillMode: AutoFillMode,
 ): ShapeTextLayout {
   const resolvedTextStyle = resolveLayoutTextStyle({
     font: options.font,
@@ -14,21 +12,14 @@ export function resolveFlowLayout(
   })
   const align = options.align ?? 'left'
   const baselineRatio = options.baselineRatio ?? 0.8
-  const autoFill = options.autoFill ?? false
-  const prepared =
-    autoFillMode === 'dense'
-      ? undefined
-      : prepareTextForLayout(options.text, resolvedTextStyle.font, options.measurer)
-  const densePattern =
-    autoFillMode === 'dense'
-      ? prepareDenseRepeatFillPattern(options.text, resolvedTextStyle.font, options.measurer)
-      : undefined
+  const prepared = prepareTextForLayout(
+    options.text,
+    resolvedTextStyle.font,
+    options.measurer,
+  )
   const { lines, endCursor } = layoutFlowLinesInCompiledShape({
     compiledShape: options.compiledShape,
     prepared,
-    densePattern,
-    autoFill,
-    autoFillMode,
     align,
     baselineRatio,
     startCursor: { tokenIndex: 0, graphemeIndex: 0 },
@@ -42,13 +33,7 @@ export function resolveFlowLayout(
     compiledShape: options.compiledShape,
     bounds: options.compiledShape.bounds,
     lines,
-    exhausted: autoFill
-      ? autoFillMode === 'dense'
-        ? false
-        : prepared!.tokens.length === 0
-      : endCursor.tokenIndex >= prepared!.tokens.length,
-    autoFill,
-    autoFillMode,
-    fillStrategy: 'flow',
+    exhausted: endCursor.tokenIndex >= prepared.tokens.length,
+    autoFill: false,
   }
 }
diff --git a/src/layout/resolve-max-fill-layout.ts b/src/layout/resolve-max-fill-layout.ts
index b406d40..e99c5d1 100644
--- a/src/layout/resolve-max-fill-layout.ts
+++ b/src/layout/resolve-max-fill-layout.ts
@@ -39,7 +39,5 @@ export function resolveMaxFillLayout(
     lines: pass.lines,
     exhausted: false,
     autoFill: true,
-    autoFillMode: 'stream',
-    fillStrategy: 'max',
   }
 }
diff --git a/src/layout/resolve-sequential-shape-regions.ts b/src/layout/resolve-sequential-shape-regions.ts
index e6252d1..00a1151 100644
--- a/src/layout/resolve-sequential-shape-regions.ts
+++ b/src/layout/resolve-sequential-shape-regions.ts
@@ -1,14 +1,11 @@
 import type {
-  AutoFillMode,
   CompiledShapeBands,
   CompiledShapeRegion,
-  FillStrategy,
   LayoutCursor,
   LayoutTextInCompiledShapeOptions,
   ShapeTextLayout,
 } from '../types.js'
 import { resolveLayoutTextStyle } from '../text/normalize-text-style-to-font.js'
-import { prepareDenseRepeatFillPattern } from '../text/prepare-dense-repeat-fill-pattern.js'
 import { prepareStreamRepeatFillPattern } from '../text/prepare-stream-repeat-fill-pattern.js'
 import { prepareTextForLayout } from '../text/prepare-text-for-layout.js'
 import { layoutDenseFillPass } from './layout-dense-fill-pass.js'
@@ -44,19 +41,18 @@ export function resolveSequentialShapeRegions(
   options: LayoutTextInCompiledShapeOptions,
 ): ShapeTextLayout {
   const autoFill = options.autoFill ?? false
-  const autoFillMode: AutoFillMode = autoFill ? (options.autoFillMode ?? 'words') : 'words'
-  const fillStrategy: FillStrategy = autoFill ? (options.fillStrategy ?? 'flow') : 'flow'
   const resolvedTextStyle = resolveLayoutTextStyle({
     font: options.font,
     textStyle: options.textStyle,
   })
   const align = options.align ?? 'left'
   const baselineRatio = options.baselineRatio ?? 0.8
-  const compiledShape =
-    fillStrategy === 'max' ? ensureMaxFillCompiledShape(options.compiledShape) : options.compiledShape
+  const compiledShape = autoFill
+    ? ensureMaxFillCompiledShape(options.compiledShape)
+    : options.compiledShape
   const regions = compiledShape.regions ?? []
 
-  if (fillStrategy === 'max') {
+  if (autoFill) {
     const streamPattern = prepareStreamRepeatFillPattern(
       options.text,
       resolvedTextStyle.font,
@@ -91,19 +87,14 @@ export function resolveSequentialShapeRegions(
       lines,
       exhausted: false,
       autoFill: true,
-      autoFillMode: 'stream',
-      fillStrategy: 'max',
     }
   }
 
-  const prepared =
-    autoFillMode === 'dense'
-      ? undefined
-      : prepareTextForLayout(options.text, resolvedTextStyle.font, options.measurer)
-  const densePattern =
-    autoFillMode === 'dense'
-      ? prepareDenseRepeatFillPattern(options.text, resolvedTextStyle.font, options.measurer)
-      : undefined
+  const prepared = prepareTextForLayout(
+    options.text,
+    resolvedTextStyle.font,
+    options.measurer,
+  )
   const lines = []
   let cursor: LayoutCursor = { tokenIndex: 0, graphemeIndex: 0 }
 
@@ -112,9 +103,6 @@ export function resolveSequentialShapeRegions(
     const result = layoutFlowLinesInCompiledShape({
       compiledShape: regionShape,
       prepared,
-      densePattern,
-      autoFill,
-      autoFillMode,
       align,
       baselineRatio,
       startCursor: cursor,
@@ -136,9 +124,7 @@ export function resolveSequentialShapeRegions(
     compiledShape,
     bounds: compiledShape.bounds,
     lines,
-    exhausted: autoFill ? autoFillMode === 'dense' ? false : prepared!.tokens.length === 0 : cursor.tokenIndex >= prepared!.tokens.length,
-    autoFill,
-    autoFillMode,
-    fillStrategy: 'flow',
+    exhausted: cursor.tokenIndex >= prepared.tokens.length,
+    autoFill: false,
   }
 }
diff --git a/src/render/render-layout-to-svg.test.ts b/src/render/render-layout-to-svg.test.ts
index f38a61e..c131982 100644
--- a/src/render/render-layout-to-svg.test.ts
+++ b/src/render/render-layout-to-svg.test.ts
@@ -111,7 +111,7 @@ describe('renderLayoutToSvg', () => {
     expect(svg).not.toContain('fill="#2563eb"')
   })
 
-  it('renders line-level font overrides for residual max-fill passes', () => {
+  it('renders line-level font overrides when a line provides its own font', () => {
     const svg = renderLayoutToSvg({
       font: '16px Test Sans',
       lineHeight: 20,
@@ -177,8 +177,6 @@ describe('renderLayoutToSvg', () => {
       ],
       exhausted: false,
       autoFill: true,
-      autoFillMode: 'dense',
-      fillStrategy: 'max',
     } satisfies ShapeTextLayout)
 
     expect(svg).toContain('style="font:16px Test Sans;"')
@@ -287,8 +285,6 @@ describe('renderLayoutToSvg', () => {
       lines: [],
       exhausted: true,
       autoFill: false,
-      autoFillMode: 'words',
-      fillStrategy: 'flow',
     } satisfies ShapeTextLayout)
 
     expect(svg).toContain('<svg')
diff --git a/src/types.ts b/src/types.ts
index 4f0b391..7922e00 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -84,9 +84,6 @@ export type ShapeStyleInput = {
   shadow?: ShapeShadowInput
 }
 
-export type AutoFillMode = 'words' | 'dense' | 'stream'
-export type FillStrategy = 'flow' | 'max'
-
 export type ResolvedShapeStyle = {
   backgroundColor?: string
   borderColor: string
@@ -184,8 +181,6 @@ export type ShapeTextLayout = {
   lines: ShapeTextLine[]
   exhausted: boolean
   autoFill: boolean
-  autoFillMode?: AutoFillMode
-  fillStrategy?: FillStrategy
 }
 
 export type CompileShapeForLayoutOptions = {
@@ -201,8 +196,6 @@ export type LayoutTextInCompiledShapeOptions = {
   align?: 'left' | 'center'
   baselineRatio?: number
   autoFill?: boolean
-  autoFillMode?: AutoFillMode
-  fillStrategy?: FillStrategy
 } & (
   | {
       font: string
@@ -223,8 +216,6 @@ export type LayoutTextInShapeOptions = {
   minSlotWidth?: number
   baselineRatio?: number
   autoFill?: boolean
-  autoFillMode?: AutoFillMode
-  fillStrategy?: FillStrategy
 } & (
   | {
       font: string
diff --git a/tsconfig.build.json b/tsconfig.build.json
index 9a433e9..4b137a7 100644
--- a/tsconfig.build.json
+++ b/tsconfig.build.json
@@ -4,6 +4,6 @@
     "rootDir": "./src",
     "outDir": "./dist"
   },
-  "include": ["src"]
+  "include": ["src"],
+  "exclude": ["src/**/*.test.ts", "src/**/*.test.tsx"]
 }
-
diff --git a/tsconfig.json b/tsconfig.json
index 214a1fc..ab97470 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -5,13 +5,25 @@
     "moduleResolution": "Bundler",
     "lib": ["ES2022", "DOM"],
     "strict": true,
+    "jsx": "react-jsx",
     "declaration": true,
     "sourceMap": true,
     "rootDir": ".",
+    "baseUrl": ".",
+    "paths": {
+      "shape-text": ["./src/index.ts"]
+    },
     "esModuleInterop": true,
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true
   },
-  "include": ["src", "vitest.config.ts"]
+  "include": [
+    "src",
+    "demo/**/*.ts",
+    "demo/**/*.tsx",
+    "demo/vite.config.ts",
+    "e2e/**/*.ts",
+    "playwright.config.ts",
+    "vitest.config.ts"
+  ]
 }
-
diff --git a/vitest.config.ts b/vitest.config.ts
index 065f4ac..d064951 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -3,11 +3,11 @@ import { defineConfig } from 'vitest/config'
 export default defineConfig({
   test: {
     environment: 'node',
-    exclude: ['e2e/**', 'node_modules/**', 'dist/**', '.claude/**'],
+    exclude: ['e2e/**', 'node_modules/**', 'dist/**', 'demo/dist/**', '.claude/**'],
     coverage: {
       provider: 'v8',
-      include: ['src/**/*.ts'],
-      exclude: ['src/**/*.test.ts', 'src/index.ts', 'src/types.ts'],
+      include: ['src/**/*.ts', 'demo/src/**/*.ts'],
+      exclude: ['src/**/*.test.ts', 'src/index.ts', 'src/types.ts', 'demo/src/**/*.test.ts', 'demo/src/main.tsx'],
     },
   },
 })

From 8d1ed280367ad92f056d3c622f516740acd2145c Mon Sep 17 00:00:00 2001
From: tqdat410 <danhlagi01472@gmail.com>
Date: Thu, 2 Apr 2026 20:52:37 +0700
Subject: [PATCH 10/12] docs(shape-paragraph): refresh workbench and release
 guidance

Co-authored-by: Codex <noreply@openai.com>
---
 README.md                    | 91 +++++++++++++++++++++++++++---------
 docs/code-standards.md       |  4 +-
 docs/development-roadmap.md  |  9 +++-
 docs/project-changelog.md    | 17 +++++++
 docs/project-overview-pdr.md | 14 +++---
 docs/system-architecture.md  | 12 +++--
 6 files changed, 112 insertions(+), 35 deletions(-)

diff --git a/README.md b/README.md
index dde49de..eb00449 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,12 @@
 # shape-text
 
-Browser-first TypeScript library for laying out text inside shapes and rendering the result to SVG.
+Browser-first TypeScript library for shape-paragraph layout and SVG rendering.
 
 ## V1 scope
 
 - SVG renderer
-- Polygon input
-- Text-mask input from glyph text
+- Geometry input
+- Value-derived input from text masks
 - Latin/Vietnamese first
 - Single closed shape, no holes
 - Shape-first API, not a thin wrapper over `pretext`
@@ -16,8 +16,37 @@ Browser-first TypeScript library for laying out text inside shapes and rendering
 
 ```bash
 npm install shape-text
+bun add shape-text
 ```
 
+## Local demo and browser E2E
+
+```bash
+npx playwright install chromium
+npm run demo
+npm run e2e:ui
+```
+
+- `npm run demo` starts the React workbench on `http://127.0.0.1:4173/`
+- `npm run demo:preview` serves the built demo
+- `npm run e2e` and `npm run e2e:ui` run Playwright against the built preview app on port `4174`, which is closer to production than hitting the dev server
+- The npm scripts resolve their own package root so they still work even if Windows launches `cmd.exe` with a broken fallback cwd
+
+## Ship readiness
+
+Library packaging is validated for both `npm` and `bun`.
+
+```bash
+npm run ship:check
+```
+
+That flow currently checks:
+
+- clean library build output
+- `npm pack` tarball contents
+- `bun pm pack` compatibility
+- smoke install + ESM import via both `npm` and `bun`
+
 ## Quick start
 
 ```ts
@@ -65,11 +94,20 @@ const svg = renderLayoutToSvg(layout, {
 })
 ```
 
-## Text-mask autofill
+## Shape sources
+
+`shape-text` currently ships two first-class ways to provide the shape paragraph surface:
+
+- Geometry input: pass explicit polygon points
+- Value-derived input: pass a `text-mask` shape derived from text and font
+
+The low-level API term stays `text-mask`, but the product framing is `value-derived shape`.
+
+## Value-derived example
 
 ```ts
 const layout = layoutTextInShape({
-  text: 'ONE',
+  text: 'Shape paragraph can fill a value-derived silhouette too.',
   textStyle: {
     family: 'Arial, sans-serif',
     size: 16,
@@ -78,10 +116,9 @@ const layout = layoutTextInShape({
   },
   lineHeight: 20,
   autoFill: true,
-  fillStrategy: 'max',
   shape: {
     kind: 'text-mask',
-    text: '2',
+    text: '23',
     font: '700 420px Arial',
     size: {
       mode: 'fit-content',
@@ -92,7 +129,7 @@ const layout = layoutTextInShape({
 })
 ```
 
-## Sequential text-mask regions
+## Sequential value-derived regions
 
 ```ts
 const layout = layoutTextInShape({
@@ -139,10 +176,10 @@ const layout = layoutTextInShape({
 
 - V1 keeps the text engine simple on purpose. It uses `Intl.Segmenter` for grapheme-safe word breaking, but it does not promise full browser-parity for every writing system.
 - The project takes inspiration from `pretext` for the `prepare -> layout` split and streaming line iteration, but owns its geometry, slot policy, and public API.
-- `text-mask` shapes are raster-compiled into reusable line bands. This is the default path for browser fonts such as `Arial`, and it is designed so callers can precompile `0-9` and `:` for clock-like UIs.
-- `autoFill: true` repeats the source text until the available shape bands are full.
-- `autoFillMode: 'words'` is the default readable repeat behavior. `autoFillMode: 'dense'` strips whitespace and breaks at grapheme boundaries to pack shapes harder for decorative fills.
-- `fillStrategy: 'max'` switches to an all-slots pass that fills every usable interval in reading order. It keeps spaces as normal graphemes instead of stripping them, and it does not fall back to smaller text for leftover pockets.
+- Geometry and value-derived shapes both compile into reusable line bands before layout.
+- `text-mask` shapes are raster-compiled into reusable line bands. This is the default value-derived path for browser fonts such as `Arial`, and it is designed so callers can precompile `0-9` and `:` for clock-like UIs.
+- `autoFill: true` now means one thing: max-fill stream layout that sweeps every usable interval in reading order.
+- Max fill keeps spaces as normal graphemes instead of stripping them, and it does not fall back to smaller text for leftover pockets.
 - `text-mask` sizing now lives under `shape.size`. The default `fit-content` mode measures the text mask first and grows the raster box to avoid clipping multi-character shapes such as `23`.
 - `shape.shapeTextMode: 'per-character'` keeps the full text-mask debug view, but also compiles ordered per-character regions for sequential fill across multi-character shape text.
 - `textStyle` is the new data-driven API for size, weight, italic/oblique, family, and default text color. Legacy `font` string input still works.
@@ -177,11 +214,17 @@ npm run e2e:headed
 npm run e2e:debug
 ```
 
-The E2E fixture is a static page served from `/e2e/fixtures/index.html`. It imports the built library from `/dist/index.js`, so the browser test path stays very close to real package usage.
+Playwright now targets the React workbench in `demo/`, so browser coverage runs against the same app used for manual exploration.
+
+## Publish notes
+
+- Published package surface is limited to `dist/`, `README.md`, and `LICENSE`
+- `npm pack` / `npm publish` trigger a clean library rebuild through `prepack`
+- Build output excludes test files so the tarball stays library-only
 
 ## Local Demo UI
 
-If you just want to open a real browser UI and click around:
+Open the React workbench:
 
 ```bash
 npm run demo
@@ -193,18 +236,24 @@ Then open:
 http://127.0.0.1:4173/
 ```
 
-For a fast local loop without rebuilding first:
+Build the workbench explicitly:
+
+```bash
+npm run demo:build
+```
+
+Preview the built app:
 
 ```bash
-npm run build
-npm run demo:dev
+npm run demo:preview
 ```
 
-The demo now includes:
+The workbench includes:
 
-- direct `shape.text` editing for text-mask scenarios
+- geometry vs value-derived shape source switching
+- direct `shape.text` editing for value-derived shapes
 - `shape.size.mode` switching between `fit-content` and `fixed`
-- `shapeTextMode` switching between `whole-text` and sequential `per-character` text-mask regions
+- `shapeTextMode` switching between `whole-text` and sequential `per-character` value-derived regions
+- random character-pattern fill presets
 - a payload JSON editor for the live `layout` + `render` request
 - a scrollable full-output SVG viewport with `Zoom out`, `Zoom in`, `100%`, and `Fit` controls
-- predefined random character-pattern fill presets for quick repeat-fill experiments
diff --git a/docs/code-standards.md b/docs/code-standards.md
index 904c658..e3f9d13 100644
--- a/docs/code-standards.md
+++ b/docs/code-standards.md
@@ -11,6 +11,7 @@
 ## Scope Rules
 
 - V1 supports polygon and text-mask shapes
+- Product framing should describe those as geometry input and value-derived input when talking about the user-facing feature set
 - V1 is browser-first
 - Advanced i18n fidelity can be added later without breaking the public shape-first API
 - Keep shape compilation separate from content flow so hot paths can reuse cached bands
@@ -21,5 +22,6 @@
 
 - Test layout logic with a deterministic measurer
 - Test SVG output with string assertions
-- Test browser-only glyph masking through Playwright, not Node mocks
+- Test browser-only glyph masking and workbench wiring through Playwright, not Node mocks
 - Keep tests focused on behavior, not implementation details
+- Do not expose private browser globals just to make E2E easier
diff --git a/docs/development-roadmap.md b/docs/development-roadmap.md
index b864eb8..8c7ffd1 100644
--- a/docs/development-roadmap.md
+++ b/docs/development-roadmap.md
@@ -9,9 +9,14 @@
 
 ## Phase 2
 
-- Add center alignment polish
 - Add alpha-mask adapter
-- Add playground/demo page
+- Completed on 2026-04-02:
+  - Add React playground/demo page
+  - Replace fixture-driven browser tests with workbench-driven browser tests
+- Simplify repeat fill to max-fill-only product behavior
+- Harden npm/bun release readiness for shipping the library as a clean consumable package
+- Remaining:
+  - Add alpha-mask adapter
 
 ## Phase 3
 
diff --git a/docs/project-changelog.md b/docs/project-changelog.md
index 0a88440..a374360 100644
--- a/docs/project-changelog.md
+++ b/docs/project-changelog.md
@@ -27,3 +27,20 @@
 - Added a scrollable demo full-output SVG viewport with zoom in/out, reset, and fit controls for wide or tall renders
 - Kept legacy `font`, `textFill`, `shapeFill`, and `shapeStroke` compatibility paths
 - Extended local demo and Playwright coverage for style and decoration controls
+
+## 2026-04-02
+
+- Reframed the product language around `shape paragraph`
+- Standardized the two primary shape-source directions as geometry input and value-derived input
+- Replaced the static fixture browser demo with a small React workbench under `demo/`
+- Rewrote Playwright coverage against visible React app behavior instead of a private `window` test API
+- Moved the local browser workflow to Vite + React and removed the legacy static fixture server scripts
+- Kept payload JSON editing as an advanced workbench panel instead of a parallel demo-only state architecture
+- Fixed Windows `npm run demo` / `npm run e2e:*` execution under `\\?\C:\...` cwd by resolving package-root script entrypoints explicitly instead of relying on relative cwd paths
+- Simplified browser E2E to run against the built preview app on a dedicated Playwright port, so local tests are closer to the shipped browser path
+- Simplified repeat fill to one product path: `autoFill: true` now always routes to max fill
+- Removed the workbench fill-mode selector and the medium weight option
+- Changed workbench fill presets from seeded deterministic strings to true-random generation with reroll support
+- Tightened package metadata for library shipping, including `sideEffects`, publish metadata, and LICENSE packaging
+- Cleaned the library build so `dist/` no longer ships compiled test files
+- Added `npm` + `bun` ship-readiness smoke checks for tarball generation and consumer import validation
diff --git a/docs/project-overview-pdr.md b/docs/project-overview-pdr.md
index e5d0701..02ebb42 100644
--- a/docs/project-overview-pdr.md
+++ b/docs/project-overview-pdr.md
@@ -2,20 +2,21 @@
 
 ## Product
 
-`shape-text` is a browser-first TypeScript library that places text inside polygon or glyph-derived shapes and renders the result to SVG.
+`shape-text` is a browser-first TypeScript library for shape-paragraph layout. It places text inside either explicit geometry or value-derived shapes and renders the result to SVG.
 
 ## Problem
 
-Web CSS can wrap text around floated shapes, but it does not provide a solid, portable way to fill text inside arbitrary shapes. We need a small library that solves that exact gap and supports dynamic glyph-shaped layouts such as numeric clocks.
+Web CSS can wrap text around floated shapes, but it does not provide a solid, portable way to fill text inside arbitrary shapes. We need a small library that solves that exact gap, supports dynamic value-derived layouts such as numeric clocks, and has a real browser workbench for manual verification.
 
 ## V1 Requirements
 
-- Accept polygon input
-- Accept text-mask input from glyph text and font
+- Accept geometry input
+- Accept value-derived input from glyph text and font
 - Measure and stream paragraph lines through shape bands
-- Support repeat-fill mode for dense glyph fills
+- Support max-fill repeat coverage for decorative glyph fills
 - Support structured text formatting params for size, family, weight, style, and color
 - Support renderer-only shape decoration for fill, border, and shadow
+- Ship a React browser workbench that exercises the library directly
 - Return deterministic line geometry
 - Render to SVG
 - Support Latin/Vietnamese first
@@ -31,8 +32,9 @@ Web CSS can wrap text around floated shapes, but it does not provide a solid, po
 ## Acceptance Criteria
 
 - A caller can pass text, text formatting, line height, shape input, and measurer
-- The library can compile reusable shape bands for polygon and text-mask shapes
+- The library can compile reusable shape bands for geometry and value-derived shapes
 - The library can repeat source text until the target shape bands are full
 - The library returns line positions inside the target shape
 - The library renders those lines to SVG with optional shape decoration
+- The React workbench covers both shape-source directions and the advanced payload editor path
 - Build and tests pass
diff --git a/docs/system-architecture.md b/docs/system-architecture.md
index 6cf4eca..3600b7c 100644
--- a/docs/system-architecture.md
+++ b/docs/system-architecture.md
@@ -5,9 +5,10 @@
 - `text/*`: text preparation and streamed line breaking
 - `geometry/*`: polygon band sampling and interval extraction
 - `shape/*`: shape compilation, text-mask size resolution, cacheable band generation, and optional per-character text-mask region extraction
-- `layout/*`: shape-aware line placement, repeat-fill policies, and sequential region flow for per-character text masks
+- `layout/*`: shape-aware line placement, max-fill repeat coverage, and sequential region flow for per-character text masks
 - `render/*`: SVG serialization
-- `e2e/fixtures/*`: browser demo UI, payload editor, and SVG viewport zoom controller
+- `demo/src/*`: React workbench UI, request editing, and SVG viewport presentation
+- `e2e/*`: Playwright browser coverage against the React workbench
 
 ## Data Flow
 
@@ -15,10 +16,10 @@
 2. Resolve text-mask sizing into either `fit-content` or fixed bounds, then compile the input shape into reusable line bands
 3. For `text-mask` shapes with `shapeTextMode: 'per-character'`, also compile ordered non-space grapheme regions from the same mask source
 4. Compute allowed intervals for each band or per-character region
-5. Route layout through sequential regions when they exist; otherwise use the normal whole-shape flow or max-fill path
+5. Route layout through sequential regions when they exist; otherwise use the normal whole-shape flow or the max-fill path
 6. Optionally repeat the source text until the active shape bands are full
 7. Project positioned lines into SVG
-8. In the demo, mount the SVG into a scrollable viewport and apply bounded zoom or fit-to-viewport scaling
+8. In the React workbench, mount the SVG into a scrollable viewport and apply bounded zoom or fit-to-viewport scaling
 
 ## Boundary Decisions
 
@@ -28,4 +29,5 @@
 - Geometry stays shape-specific, not DOM-specific
 - Renderer-only decoration stays out of compile/layout caching
 - Renderer consumes compiled layout output only
-- Demo zoom is a presentation concern only; it never changes compile or layout results
+- Workbench zoom is a presentation concern only; it never changes compile or layout results
+- Playwright should assert visible browser behavior, not private controller state

From e4b79ce75ee5d1f4ee26b5b7819698c4f32873af Mon Sep 17 00:00:00 2001
From: tqdat410 <danhlagi01472@gmail.com>
Date: Thu, 2 Apr 2026 21:16:11 +0700
Subject: [PATCH 11/12] ci(release): add npm publish pipeline

Co-authored-by: Codex <noreply@openai.com>
---
 .github/workflows/ci.yml         |  72 +++++++++++++++++++++
 .github/workflows/release.yml    |  82 ++++++++++++++++++++++++
 README.md                        |   4 ++
 docs/code-standards.md           |   3 +
 docs/deployment-guide.md         | 105 +++++++++++++++++++++++++++++++
 docs/development-roadmap.md      |   1 +
 docs/project-changelog.md        |   3 +
 docs/project-overview-pdr.md     |   2 +
 docs/system-architecture.md      |   4 ++
 package.json                     |   3 +-
 scripts/validate-release-tag.mjs |  29 +++++++++
 11 files changed, 307 insertions(+), 1 deletion(-)
 create mode 100644 .github/workflows/ci.yml
 create mode 100644 .github/workflows/release.yml
 create mode 100644 docs/deployment-guide.md
 create mode 100644 scripts/validate-release-tag.mjs

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..3d29fbe
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,72 @@
+name: CI
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+      - codex/**
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  library:
+    name: Library Validation
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: npm
+          registry-url: https://registry.npmjs.org
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.5
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run project checks
+        run: npm run check
+
+      - name: Run library ship smoke checks
+        run: npm run ship:check
+
+  browser:
+    name: Browser Integration
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright Chromium
+        run: npx playwright install --with-deps chromium
+
+      - name: Run browser E2E
+        run: npm run e2e
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 0000000..06fa8a2
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,82 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - v*.*.*
+
+permissions:
+  contents: write
+  id-token: write
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    name: Publish Package
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    environment:
+      name: npm-release
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: npm
+          registry-url: https://registry.npmjs.org
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.5
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Validate release tag against package version
+        run: node ./scripts/validate-release-tag.mjs "${{ github.ref_name }}"
+
+      - name: Run project checks
+        run: npm run check
+
+      - name: Run ship smoke checks
+        run: npm run ship:check
+
+      - name: Install Playwright Chromium
+        run: npx playwright install --with-deps chromium
+
+      - name: Run browser E2E
+        run: npm run e2e
+
+      - name: Publish to npm
+        run: |
+          if [ -n "${NODE_AUTH_TOKEN}" ]; then
+            echo "Publishing with npm token fallback"
+          else
+            echo "Publishing with npm trusted publisher / OIDC"
+          fi
+
+          npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create GitHub release
+        run: |
+          tag="${{ github.ref_name }}"
+
+          if gh release view "$tag" >/dev/null 2>&1; then
+            echo "GitHub release already exists for $tag"
+          else
+            gh release create "$tag" --verify-tag --generate-notes --latest
+          fi
+        env:
+          GH_TOKEN: ${{ github.token }}
diff --git a/README.md b/README.md
index eb00449..e268230 100644
--- a/README.md
+++ b/README.md
@@ -221,6 +221,10 @@ Playwright now targets the React workbench in `demo/`, so browser coverage runs
 - Published package surface is limited to `dist/`, `README.md`, and `LICENSE`
 - `npm pack` / `npm publish` trigger a clean library rebuild through `prepack`
 - Build output excludes test files so the tarball stays library-only
+- PR validation now runs through `.github/workflows/ci.yml`
+- Tag releases now run through `.github/workflows/release.yml`
+- Preferred publish path is npm Trusted Publisher via GitHub Actions OIDC, with `NPM_TOKEN` as fallback only
+- Maintainer release steps and repository settings live in [docs/deployment-guide.md](./docs/deployment-guide.md)
 
 ## Local Demo UI
 
diff --git a/docs/code-standards.md b/docs/code-standards.md
index e3f9d13..9d43d9d 100644
--- a/docs/code-standards.md
+++ b/docs/code-standards.md
@@ -25,3 +25,6 @@
 - Test browser-only glyph masking and workbench wiring through Playwright, not Node mocks
 - Keep tests focused on behavior, not implementation details
 - Do not expose private browser globals just to make E2E easier
+- Keep `npm run ship:check` green before any release tag
+- Release tags must match `package.json.version`
+- CI must be required on `main` before merge
diff --git a/docs/deployment-guide.md b/docs/deployment-guide.md
new file mode 100644
index 0000000..ce31d5c
--- /dev/null
+++ b/docs/deployment-guide.md
@@ -0,0 +1,105 @@
+# Deployment Guide
+
+## Release Model
+
+- Canonical registry: npm
+- Bun support: validated consumer/runtime path, not a second registry target
+- CI workflow: `.github/workflows/ci.yml`
+- Release workflow: `.github/workflows/release.yml`
+
+## Required Repository Settings
+
+### Branch Protection
+
+Protect `main` with these minimum rules:
+
+- require pull requests before merge
+- require status checks to pass before merge
+- require `Library Validation`
+- require `Browser Integration`
+- block force pushes
+
+### Release Environment
+
+Create a GitHub environment named `npm-release`.
+
+Recommended:
+
+- add at least one required reviewer before production publishes
+- scope fallback publish secrets to this environment only
+
+## npm Trusted Publishing
+
+Trusted publishing is the preferred setup.
+
+1. In npm package settings, add this GitHub repository and the `release.yml` workflow as a trusted publisher.
+2. Keep `id-token: write` permission enabled in the release workflow.
+3. Release by pushing a tag that matches `package.json.version`, for example:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+With trusted publishing enabled, `npm publish --provenance --access public` can authenticate through GitHub OIDC without a long-lived npm token.
+
+References:
+
+- [npm trusted publishers](https://docs.npmjs.com/trusted-publishers/)
+- [npm provenance statements](https://docs.npmjs.com/generating-provenance-statements)
+
+## Fallback Token Publishing
+
+Use this only if trusted publishing cannot be enabled yet.
+
+1. Create an npm automation token with publish rights for `shape-text`.
+2. Store it in GitHub as `NPM_TOKEN`.
+3. Prefer storing the secret on the `npm-release` environment instead of repository-wide secrets.
+
+Do not commit `.npmrc` tokens to the repo.
+
+## Maintainer Release Flow
+
+1. Make sure the release PR is merged to `main`.
+2. Pull the latest `main`.
+3. Bump `package.json.version`.
+4. Update changelog if the release needs curated notes beyond generated release notes.
+5. Run:
+
+```bash
+npm run check
+npm run ship:check
+npm run e2e
+```
+
+6. Commit the version bump.
+7. Push the commit to `main`.
+8. Create and push the matching tag:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+9. Watch the `Release` workflow.
+10. Verify:
+  - npm package published
+  - GitHub release created
+  - `bun add shape-text` still works through the smoke path
+
+## Failure Modes
+
+### Tag/Version Mismatch
+
+The release workflow runs `scripts/validate-release-tag.mjs` and fails if:
+
+- tag is not semver-like
+- tag does not exactly match `package.json.version`
+
+### Trusted Publishing Not Configured
+
+If trusted publishing is not configured and `NPM_TOKEN` is absent, the publish step fails. Fix settings first; do not retry blindly.
+
+### Browser Regression On Release
+
+The release workflow reruns Playwright before publish. If browser E2E fails, the package is not published.
diff --git a/docs/development-roadmap.md b/docs/development-roadmap.md
index 8c7ffd1..d506775 100644
--- a/docs/development-roadmap.md
+++ b/docs/development-roadmap.md
@@ -15,6 +15,7 @@
   - Replace fixture-driven browser tests with workbench-driven browser tests
 - Simplify repeat fill to max-fill-only product behavior
 - Harden npm/bun release readiness for shipping the library as a clean consumable package
+- Add GitHub Actions CI and tag-driven npm release automation with Bun compatibility checks
 - Remaining:
   - Add alpha-mask adapter
 
diff --git a/docs/project-changelog.md b/docs/project-changelog.md
index a374360..129e678 100644
--- a/docs/project-changelog.md
+++ b/docs/project-changelog.md
@@ -44,3 +44,6 @@
 - Tightened package metadata for library shipping, including `sideEffects`, publish metadata, and LICENSE packaging
 - Cleaned the library build so `dist/` no longer ships compiled test files
 - Added `npm` + `bun` ship-readiness smoke checks for tarball generation and consumer import validation
+- Added GitHub Actions CI for library validation and browser integration
+- Added a tag-driven release workflow with semver tag guarding and npm-first publish automation
+- Added a maintainer deployment guide covering trusted publishing, token fallback, and branch protection
diff --git a/docs/project-overview-pdr.md b/docs/project-overview-pdr.md
index 02ebb42..924853c 100644
--- a/docs/project-overview-pdr.md
+++ b/docs/project-overview-pdr.md
@@ -17,6 +17,7 @@ Web CSS can wrap text around floated shapes, but it does not provide a solid, po
 - Support structured text formatting params for size, family, weight, style, and color
 - Support renderer-only shape decoration for fill, border, and shadow
 - Ship a React browser workbench that exercises the library directly
+- Ship with merge-blocking CI and a documented npm release path
 - Return deterministic line geometry
 - Render to SVG
 - Support Latin/Vietnamese first
@@ -37,4 +38,5 @@ Web CSS can wrap text around floated shapes, but it does not provide a solid, po
 - The library returns line positions inside the target shape
 - The library renders those lines to SVG with optional shape decoration
 - The React workbench covers both shape-source directions and the advanced payload editor path
+- The repository can validate, package, and publish the library through GitHub Actions without undocumented maintainer steps
 - Build and tests pass
diff --git a/docs/system-architecture.md b/docs/system-architecture.md
index 3600b7c..5636fca 100644
--- a/docs/system-architecture.md
+++ b/docs/system-architecture.md
@@ -9,6 +9,7 @@
 - `render/*`: SVG serialization
 - `demo/src/*`: React workbench UI, request editing, and SVG viewport presentation
 - `e2e/*`: Playwright browser coverage against the React workbench
+- `.github/workflows/*`: CI enforcement and tag-driven npm release automation
 
 ## Data Flow
 
@@ -20,6 +21,8 @@
 6. Optionally repeat the source text until the active shape bands are full
 7. Project positioned lines into SVG
 8. In the React workbench, mount the SVG into a scrollable viewport and apply bounded zoom or fit-to-viewport scaling
+9. CI reruns project validation, package smoke checks, and browser coverage before merge
+10. Release tags rerun validation, verify the semver tag, and publish once to npm with Bun compatibility already covered by smoke checks
 
 ## Boundary Decisions
 
@@ -31,3 +34,4 @@
 - Renderer consumes compiled layout output only
 - Workbench zoom is a presentation concern only; it never changes compile or layout results
 - Playwright should assert visible browser behavior, not private controller state
+- Release automation should publish to npm once and treat Bun as a verified consumer path rather than a second registry target
diff --git a/package.json b/package.json
index 5fb75f1..ce85d0a 100644
--- a/package.json
+++ b/package.json
@@ -49,7 +49,8 @@
     "demo:build": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('scripts/run-demo-app.mjs',['--build'])\"",
     "demo:preview": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('scripts/run-demo-app.mjs',['--preview'])\"",
     "prepack": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('scripts/run-library-build.mjs')\"",
-    "ship:check": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('scripts/run-library-ship-check.mjs')\""
+    "ship:check": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('scripts/run-library-ship-check.mjs')\"",
+    "release:check-tag": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('scripts/validate-release-tag.mjs', process.argv.slice(1))\""
   },
   "keywords": [
     "svg",
diff --git a/scripts/validate-release-tag.mjs b/scripts/validate-release-tag.mjs
new file mode 100644
index 0000000..822de0e
--- /dev/null
+++ b/scripts/validate-release-tag.mjs
@@ -0,0 +1,29 @@
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url))
+const rootDir = path.resolve(scriptDir, '..')
+const packageJsonPath = path.resolve(rootDir, 'package.json')
+
+const tag = process.argv[2]
+if (typeof tag !== 'string' || tag.length === 0) {
+  throw new Error('release tag is required')
+}
+
+if (!/^v\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/u.test(tag)) {
+  throw new Error(`release tag "${tag}" must match v<semver>`)
+}
+
+const packageJson = JSON.parse(await readFile(packageJsonPath, 'utf8'))
+const version = packageJson.version
+
+if (typeof version !== 'string' || version.length === 0) {
+  throw new Error('package.json version is missing')
+}
+
+if (`v${version}` !== tag) {
+  throw new Error(
+    `release tag "${tag}" does not match package.json version "v${version}"`,
+  )
+}

From 80450d24efac4b65beb055afa6c8ece2e238b5ca Mon Sep 17 00:00:00 2001
From: tqdat410 <danhlagi01472@gmail.com>
Date: Thu, 2 Apr 2026 21:21:24 +0700
Subject: [PATCH 12/12] fix(ci): stabilize package-root script runner

Co-authored-by: Codex <noreply@openai.com>
---
 package.json                                  | 32 +++++++++----------
 scripts/run-node-script-from-package-root.cjs | 11 ++++++-
 2 files changed, 26 insertions(+), 17 deletions(-)

diff --git a/package.json b/package.json
index ce85d0a..5154ca7 100644
--- a/package.json
+++ b/package.json
@@ -35,22 +35,22 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('scripts/run-library-build.mjs')\"",
-    "typecheck": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('node_modules/typescript/bin/tsc',['-p','tsconfig.json','--noEmit'])\"",
-    "test": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('node_modules/vitest/vitest.mjs',['run'])\"",
-    "test:coverage": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('node_modules/vitest/vitest.mjs',['run','--coverage'])\"",
-    "check": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('scripts/run-project-check.mjs')\"",
-    "e2e": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('node_modules/@playwright/test/cli.js',['test'])\"",
-    "e2e:ui": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('node_modules/@playwright/test/cli.js',['test','--ui'])\"",
-    "e2e:headed": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('node_modules/@playwright/test/cli.js',['test','--headed'])\"",
-    "e2e:debug": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('node_modules/@playwright/test/cli.js',['test','--debug'])\"",
-    "demo": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('scripts/run-demo-app.mjs')\"",
-    "demo:dev": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('scripts/run-demo-app.mjs')\"",
-    "demo:build": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('scripts/run-demo-app.mjs',['--build'])\"",
-    "demo:preview": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('scripts/run-demo-app.mjs',['--preview'])\"",
-    "prepack": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('scripts/run-library-build.mjs')\"",
-    "ship:check": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('scripts/run-library-ship-check.mjs')\"",
-    "release:check-tag": "node -e \"const path=require('node:path');const pkg=(process.env.npm_package_json||'').replace(/^\\\\\\\\\\?\\\\/,'');require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('scripts/validate-release-tag.mjs', process.argv.slice(1))\""
+    "build": "node -e \"const path=require('node:path');let pkg=process.env.npm_package_json||'';if(pkg.charCodeAt(0)===92&&pkg.charCodeAt(1)===92&&pkg.charCodeAt(2)===63&&pkg.charCodeAt(3)===92) pkg=pkg.slice(4);require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('scripts/run-library-build.mjs')\"",
+    "typecheck": "node -e \"const path=require('node:path');let pkg=process.env.npm_package_json||'';if(pkg.charCodeAt(0)===92&&pkg.charCodeAt(1)===92&&pkg.charCodeAt(2)===63&&pkg.charCodeAt(3)===92) pkg=pkg.slice(4);require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('node_modules/typescript/bin/tsc',['-p','tsconfig.json','--noEmit'])\"",
+    "test": "node -e \"const path=require('node:path');let pkg=process.env.npm_package_json||'';if(pkg.charCodeAt(0)===92&&pkg.charCodeAt(1)===92&&pkg.charCodeAt(2)===63&&pkg.charCodeAt(3)===92) pkg=pkg.slice(4);require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('node_modules/vitest/vitest.mjs',['run'])\"",
+    "test:coverage": "node -e \"const path=require('node:path');let pkg=process.env.npm_package_json||'';if(pkg.charCodeAt(0)===92&&pkg.charCodeAt(1)===92&&pkg.charCodeAt(2)===63&&pkg.charCodeAt(3)===92) pkg=pkg.slice(4);require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('node_modules/vitest/vitest.mjs',['run','--coverage'])\"",
+    "check": "node -e \"const path=require('node:path');let pkg=process.env.npm_package_json||'';if(pkg.charCodeAt(0)===92&&pkg.charCodeAt(1)===92&&pkg.charCodeAt(2)===63&&pkg.charCodeAt(3)===92) pkg=pkg.slice(4);require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('scripts/run-project-check.mjs')\"",
+    "e2e": "node -e \"const path=require('node:path');let pkg=process.env.npm_package_json||'';if(pkg.charCodeAt(0)===92&&pkg.charCodeAt(1)===92&&pkg.charCodeAt(2)===63&&pkg.charCodeAt(3)===92) pkg=pkg.slice(4);require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('node_modules/@playwright/test/cli.js',['test'])\"",
+    "e2e:ui": "node -e \"const path=require('node:path');let pkg=process.env.npm_package_json||'';if(pkg.charCodeAt(0)===92&&pkg.charCodeAt(1)===92&&pkg.charCodeAt(2)===63&&pkg.charCodeAt(3)===92) pkg=pkg.slice(4);require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('node_modules/@playwright/test/cli.js',['test','--ui'])\"",
+    "e2e:headed": "node -e \"const path=require('node:path');let pkg=process.env.npm_package_json||'';if(pkg.charCodeAt(0)===92&&pkg.charCodeAt(1)===92&&pkg.charCodeAt(2)===63&&pkg.charCodeAt(3)===92) pkg=pkg.slice(4);require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('node_modules/@playwright/test/cli.js',['test','--headed'])\"",
+    "e2e:debug": "node -e \"const path=require('node:path');let pkg=process.env.npm_package_json||'';if(pkg.charCodeAt(0)===92&&pkg.charCodeAt(1)===92&&pkg.charCodeAt(2)===63&&pkg.charCodeAt(3)===92) pkg=pkg.slice(4);require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('node_modules/@playwright/test/cli.js',['test','--debug'])\"",
+    "demo": "node -e \"const path=require('node:path');let pkg=process.env.npm_package_json||'';if(pkg.charCodeAt(0)===92&&pkg.charCodeAt(1)===92&&pkg.charCodeAt(2)===63&&pkg.charCodeAt(3)===92) pkg=pkg.slice(4);require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('scripts/run-demo-app.mjs')\"",
+    "demo:dev": "node -e \"const path=require('node:path');let pkg=process.env.npm_package_json||'';if(pkg.charCodeAt(0)===92&&pkg.charCodeAt(1)===92&&pkg.charCodeAt(2)===63&&pkg.charCodeAt(3)===92) pkg=pkg.slice(4);require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('scripts/run-demo-app.mjs')\"",
+    "demo:build": "node -e \"const path=require('node:path');let pkg=process.env.npm_package_json||'';if(pkg.charCodeAt(0)===92&&pkg.charCodeAt(1)===92&&pkg.charCodeAt(2)===63&&pkg.charCodeAt(3)===92) pkg=pkg.slice(4);require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('scripts/run-demo-app.mjs',['--build'])\"",
+    "demo:preview": "node -e \"const path=require('node:path');let pkg=process.env.npm_package_json||'';if(pkg.charCodeAt(0)===92&&pkg.charCodeAt(1)===92&&pkg.charCodeAt(2)===63&&pkg.charCodeAt(3)===92) pkg=pkg.slice(4);require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('scripts/run-demo-app.mjs',['--preview'])\"",
+    "prepack": "node -e \"const path=require('node:path');let pkg=process.env.npm_package_json||'';if(pkg.charCodeAt(0)===92&&pkg.charCodeAt(1)===92&&pkg.charCodeAt(2)===63&&pkg.charCodeAt(3)===92) pkg=pkg.slice(4);require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('scripts/run-library-build.mjs')\"",
+    "ship:check": "node -e \"const path=require('node:path');let pkg=process.env.npm_package_json||'';if(pkg.charCodeAt(0)===92&&pkg.charCodeAt(1)===92&&pkg.charCodeAt(2)===63&&pkg.charCodeAt(3)===92) pkg=pkg.slice(4);require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('scripts/run-library-ship-check.mjs')\"",
+    "release:check-tag": "node -e \"const path=require('node:path');let pkg=process.env.npm_package_json||'';if(pkg.charCodeAt(0)===92&&pkg.charCodeAt(1)===92&&pkg.charCodeAt(2)===63&&pkg.charCodeAt(3)===92) pkg=pkg.slice(4);require(path.join(path.dirname(pkg),'scripts','run-node-script-from-package-root.cjs')).run('scripts/validate-release-tag.mjs', process.argv.slice(1))\""
   },
   "keywords": [
     "svg",
diff --git a/scripts/run-node-script-from-package-root.cjs b/scripts/run-node-script-from-package-root.cjs
index 9aed16e..bf51bb3 100644
--- a/scripts/run-node-script-from-package-root.cjs
+++ b/scripts/run-node-script-from-package-root.cjs
@@ -2,7 +2,16 @@ const { spawn } = require('node:child_process')
 const path = require('node:path')
 
 function getPackageRoot() {
-  const packageJsonPath = String(process.env.npm_package_json ?? '').replace(/^\\\\\?\\/, '')
+  let packageJsonPath = String(process.env.npm_package_json ?? '')
+
+  if (
+    packageJsonPath.charCodeAt(0) === 92 &&
+    packageJsonPath.charCodeAt(1) === 92 &&
+    packageJsonPath.charCodeAt(2) === 63 &&
+    packageJsonPath.charCodeAt(3) === 92
+  ) {
+    packageJsonPath = packageJsonPath.slice(4)
+  }
 
   if (!packageJsonPath) {
     throw new Error('npm_package_json is missing; cannot resolve package root')