@hjmds/design-contracts 1.13.0 → 1.14.0

package/dist/text-annotation.js

@@ -0,0 +1,137 @@
+/**
+ * Experimental drawing geometry, not a public TextFormat variant. A renderer
+ * supplies measured visual line rectangles; estimating widths from character
+ * counts would break proportional fonts, Korean wrapping, and bidirectional text.
+ * See docs/text-annotation.md for the unfinished renderer boundary.
+ */
+export const textAnnotationActions = [
+    'highlight', 'underline', 'box', 'circle', 'strike-through', 'crossed-off', 'bracket',
+];
+function finite(value, name) {
+    if (!Number.isFinite(value))
+        throw new RangeError(`${name} must be finite`);
+}
+/** Merge adjacent font/bidi runs only within their measured visual line. A gap
+ * in a partial selection stays unpainted even when both runs share a line.
+ * Hosts supply line identity from the same layout engine that paints the text.
+ */
+export function mergeTextAnnotationFragments(fragments) {
+    for (const fragment of fragments) {
+        for (const name of ['x', 'y', 'width', 'height'])
+            finite(fragment[name], name);
+        if (fragment.width < 0 || fragment.height < 0 || !Number.isSafeInteger(fragment.lineIndex) || fragment.lineIndex < 0)
+            throw new RangeError('Invalid text annotation fragment');
+        finite(fragment.x + fragment.width, 'Fragment right');
+        finite(fragment.y + fragment.height, 'Fragment bottom');
+    }
+    const ordered = fragments.filter(fragment => fragment.width > 0 && fragment.height > 0).map(fragment => ({ ...fragment })).sort((a, b) => a.lineIndex - b.lineIndex || a.x - b.x);
+    const merged = [];
+    for (const fragment of ordered) {
+        const previous = merged[merged.length - 1];
+        // Skia exposes Float32 edges: measured adjacent runs differed by ~0.00001px.
+        // 0.01 logical px absorbs this rounding, not a visible inter-word/selection gap.
+        if (previous && previous.lineIndex === fragment.lineIndex && fragment.x <= previous.x + previous.width + 0.01) {
+            const y = Math.min(previous.y, fragment.y);
+            merged[merged.length - 1] = { lineIndex: previous.lineIndex, x: previous.x, y, width: Math.max(previous.x + previous.width, fragment.x + fragment.width) - previous.x, height: Math.max(previous.y + previous.height, fragment.y + fragment.height) - y };
+        }
+        else
+            merged.push(fragment);
+    }
+    return merged.map(({ x, y, width, height }) => {
+        finite(width, 'Merged width');
+        finite(height, 'Merged height');
+        return { x, y, width, height };
+    });
+}
+/**
+ * Small deterministic offsets give the two passes a hand-drawn character.
+ * Random-per-render geometry was rejected: unrelated state updates must not
+ * make the annotation jump or create server/client output differences.
+ */
+export function resolveTextAnnotationGeometry(lines, action, options = {}) {
+    if (!textAnnotationActions.includes(action))
+        throw new TypeError('Unknown text annotation action');
+    // These are drawing parameters, not layout spacing. 1.5px keeps a doubled
+    // outline lighter than a focus ring; the 2px gap avoids touching glyph edges.
+    const strokeWidth = options.strokeWidth ?? 1.5;
+    const padding = options.padding ?? 2;
+    finite(strokeWidth, 'strokeWidth');
+    finite(padding, 'padding');
+    if (strokeWidth <= 0)
+        throw new RangeError('strokeWidth must be positive');
+    if (padding < 0)
+        throw new RangeError('padding must not be negative');
+    const paths = [];
+    let bounds = null;
+    for (const [lineIndex, line] of lines.entries()) {
+        for (const name of ['x', 'y', 'width', 'height'])
+            finite(line[name], name);
+        if (line.width < 0 || line.height < 0)
+            throw new RangeError('Line dimensions must not be negative');
+        // Empty lines and a not-yet-laid-out host do not produce stray marker dots.
+        if (line.width === 0 || line.height === 0)
+            continue;
+        // Scale the wobble down for tiny fragments; it must not swallow punctuation.
+        const wobble = Math.min(1, line.width / 8, line.height / 8);
+        // The surrounding loop must clear the actual text even if callers choose
+        // zero padding or a thick pen. Strike-through/crossed-off intentionally do not.
+        const gap = action === 'circle' ? Math.max(padding, strokeWidth / 2 + wobble) : padding;
+        const l = line.x - gap, r = line.x + line.width + gap;
+        const t = line.y - gap, b = line.y + line.height + gap;
+        const cx = l + (r - l) / 2, cy = t + (b - t) / 2;
+        // A modest outward bow keeps a loop distinct from the box without extending
+        // an ellipse by 40% of a long line's width into neighboring text or the screen edge.
+        const bow = action === 'circle' ? Math.min(line.width, line.height) * 0.12 : 0;
+        const add = (d, paint) => paths.push({ d, paint, strokeWidth, lineIndex });
+        if (action === 'highlight') {
+            add(`M ${l} ${t + wobble} Q ${cx} ${t - wobble} ${r} ${t} L ${r - wobble} ${b} Q ${cx} ${b + wobble} ${l} ${b - wobble} Z`, 'fill');
+        }
+        else {
+            for (const offset of [-wobble / 2, wobble / 2]) {
+                const x1 = l + offset, x2 = r + offset, y1 = t + offset, y2 = b + offset;
+                switch (action) {
+                    case 'underline':
+                        add(`M ${x1} ${y2} Q ${cx} ${y2 + wobble} ${x2} ${y2 - wobble / 2}`, 'stroke');
+                        break;
+                    case 'strike-through':
+                        add(`M ${x1} ${cy + offset} Q ${cx} ${cy - wobble} ${x2} ${cy + offset}`, 'stroke');
+                        break;
+                    case 'crossed-off':
+                        add(`M ${x1} ${y1} Q ${cx} ${cy - wobble} ${x2} ${y2} M ${x2} ${y1} Q ${cx} ${cy + wobble} ${x1} ${y2}`, 'stroke');
+                        break;
+                    case 'box':
+                        add(`M ${x1} ${y1} Q ${cx} ${y1 - wobble} ${x2} ${y1} L ${x2} ${y2} Q ${cx} ${y2 + wobble} ${x1} ${y2} Z`, 'stroke');
+                        break;
+                    case 'circle':
+                        // The original inscribed ellipse cut through end glyphs at 32px.
+                        // Bow each edge outward through the padded corners instead: every
+                        // segment stays outside the text rectangle while retaining a loose loop.
+                        add(`M ${x1} ${cy} Q ${x1 - bow} ${y1} ${x1} ${y1} Q ${cx} ${y1 - bow} ${x2} ${y1} Q ${x2 + bow} ${cy} ${x2} ${y2} Q ${cx} ${y2 + bow} ${x1} ${y2} Q ${x1 - bow} ${cy} ${x1} ${cy} Z`, 'stroke');
+                        break;
+                    case 'bracket': {
+                        const arm = Math.min(line.height / 3, line.width / 4);
+                        add(`M ${x1 + arm} ${y1} L ${x1} ${y1} L ${x1} ${y2} L ${x1 + arm} ${y2} M ${x2 - arm} ${y1} L ${x2} ${y1} L ${x2} ${y2} L ${x2 - arm} ${y2}`, 'stroke');
+                        break;
+                    }
+                }
+            }
+        }
+        // Include control points, both sketch passes and stroke caps so the SVG
+        // viewBox cannot clip an underline or a bracket at large text sizes.
+        const outset = Math.max(2 * wobble, bow + wobble / 2) + strokeWidth / 2;
+        const left = l - outset, top = t - outset, right = r + outset, bottom = b + outset;
+        if (!bounds)
+            bounds = { x: left, y: top, width: right - left, height: bottom - top };
+        else {
+            const x = Math.min(bounds.x, left), y = Math.min(bounds.y, top);
+            bounds = { x, y, width: Math.max(bounds.x + bounds.width, right) - x, height: Math.max(bounds.y + bounds.height, bottom) - y };
+        }
+    }
+    // Overflow can occur even with finite inputs. Reject it here instead of
+    // handing NaN/Infinity geometry to a native SVG implementation.
+    if (bounds)
+        for (const value of Object.values(bounds))
+            finite(value, 'Annotation bounds');
+    return { paths, bounds };
+}
+//# sourceMappingURL=text-annotation.js.map

package/dist/text-annotation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-annotation.js","sourceRoot":"","sources":["../src/text-annotation.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Experimental drawing geometry, not a public TextFormat variant. A renderer\n * supplies measured visual line rectangles; estimating widths from character\n * counts would break proportional fonts, Korean wrapping, and bidirectional text.\n * See docs/text-annotation.md for the unfinished renderer boundary.\n */\nexport const textAnnotationActions = [\n  'highlight', 'underline', 'box', 'circle', 'strike-through', 'crossed-off', 'bracket',\n] as const;\nexport type TextAnnotationAction = typeof textAnnotationActions[number];\nexport type TextAnnotationRect = Readonly<{ x: number; y: number; width: number; height: number }>;\nexport type TextAnnotationFragment = TextAnnotationRect & Readonly<{ lineIndex: number }>;\nexport type TextAnnotationPath = Readonly<{\n  d: string;\n  /** Filled marker strokes belong behind the text; outlines are unfilled. */\n  paint: 'fill' | 'stroke';\n  strokeWidth: number;\n  lineIndex: number;\n}>;\nexport type TextAnnotationGeometry = Readonly<{\n  paths: readonly TextAnnotationPath[];\n  bounds: TextAnnotationRect | null;\n}>;\n\nfunction finite(value: number, name: string): void {\n  if (!Number.isFinite(value)) throw new RangeError(`${name} must be finite`);\n}\n\n/** Merge adjacent font/bidi runs only within their measured visual line. A gap\n * in a partial selection stays unpainted even when both runs share a line.\n * Hosts supply line identity from the same layout engine that paints the text.\n */\nexport function mergeTextAnnotationFragments(fragments: readonly TextAnnotationFragment[]): TextAnnotationRect[] {\n  for (const fragment of fragments) {\n    for (const name of ['x', 'y', 'width', 'height'] as const) finite(fragment[name], name);\n    if (fragment.width < 0 || fragment.height < 0 || !Number.isSafeInteger(fragment.lineIndex) || fragment.lineIndex < 0) throw new RangeError('Invalid text annotation fragment');\n    finite(fragment.x + fragment.width, 'Fragment right'); finite(fragment.y + fragment.height, 'Fragment bottom');\n  }\n  const ordered = fragments.filter(fragment => fragment.width > 0 && fragment.height > 0).map(fragment => ({ ...fragment })).sort((a, b) => a.lineIndex - b.lineIndex || a.x - b.x);\n  const merged: TextAnnotationFragment[] = [];\n  for (const fragment of ordered) {\n    const previous = merged[merged.length - 1];\n    // Skia exposes Float32 edges: measured adjacent runs differed by ~0.00001px.\n    // 0.01 logical px absorbs this rounding, not a visible inter-word/selection gap.\n    if (previous && previous.lineIndex === fragment.lineIndex && fragment.x <= previous.x + previous.width + 0.01) {\n      const y = Math.min(previous.y, fragment.y);\n      merged[merged.length - 1] = { lineIndex: previous.lineIndex, x: previous.x, y, width: Math.max(previous.x + previous.width, fragment.x + fragment.width) - previous.x, height: Math.max(previous.y + previous.height, fragment.y + fragment.height) - y };\n    } else merged.push(fragment);\n  }\n  return merged.map(({ x, y, width, height }) => {\n    finite(width, 'Merged width'); finite(height, 'Merged height');\n    return { x, y, width, height };\n  });\n}\n\n/**\n * Small deterministic offsets give the two passes a hand-drawn character.\n * Random-per-render geometry was rejected: unrelated state updates must not\n * make the annotation jump or create server/client output differences.\n */\nexport function resolveTextAnnotationGeometry(\n  lines: readonly TextAnnotationRect[],\n  action: TextAnnotationAction,\n  options: Readonly<{ strokeWidth?: number; padding?: number }> = {},\n): TextAnnotationGeometry {\n  if (!(textAnnotationActions as readonly string[]).includes(action)) throw new TypeError('Unknown text annotation action');\n  // These are drawing parameters, not layout spacing. 1.5px keeps a doubled\n  // outline lighter than a focus ring; the 2px gap avoids touching glyph edges.\n  const strokeWidth = options.strokeWidth ?? 1.5;\n  const padding = options.padding ?? 2;\n  finite(strokeWidth, 'strokeWidth'); finite(padding, 'padding');\n  if (strokeWidth <= 0) throw new RangeError('strokeWidth must be positive');\n  if (padding < 0) throw new RangeError('padding must not be negative');\n  const paths: TextAnnotationPath[] = [];\n  let bounds: TextAnnotationRect | null = null;\n  for (const [lineIndex, line] of lines.entries()) {\n    for (const name of ['x', 'y', 'width', 'height'] as const) finite(line[name], name);\n    if (line.width < 0 || line.height < 0) throw new RangeError('Line dimensions must not be negative');\n    // Empty lines and a not-yet-laid-out host do not produce stray marker dots.\n    if (line.width === 0 || line.height === 0) continue;\n    // Scale the wobble down for tiny fragments; it must not swallow punctuation.\n    const wobble = Math.min(1, line.width / 8, line.height / 8);\n    // The surrounding loop must clear the actual text even if callers choose\n    // zero padding or a thick pen. Strike-through/crossed-off intentionally do not.\n    const gap = action === 'circle' ? Math.max(padding, strokeWidth / 2 + wobble) : padding;\n    const l = line.x - gap, r = line.x + line.width + gap;\n    const t = line.y - gap, b = line.y + line.height + gap;\n    const cx = l + (r - l) / 2, cy = t + (b - t) / 2;\n    // A modest outward bow keeps a loop distinct from the box without extending\n    // an ellipse by 40% of a long line's width into neighboring text or the screen edge.\n    const bow = action === 'circle' ? Math.min(line.width, line.height) * 0.12 : 0;\n    const add = (d: string, paint: 'fill' | 'stroke') => paths.push({ d, paint, strokeWidth, lineIndex });\n    if (action === 'highlight') {\n      add(`M ${l} ${t + wobble} Q ${cx} ${t - wobble} ${r} ${t} L ${r - wobble} ${b} Q ${cx} ${b + wobble} ${l} ${b - wobble} Z`, 'fill');\n    } else {\n      for (const offset of [-wobble / 2, wobble / 2]) {\n        const x1 = l + offset, x2 = r + offset, y1 = t + offset, y2 = b + offset;\n        switch (action) {\n          case 'underline':\n            add(`M ${x1} ${y2} Q ${cx} ${y2 + wobble} ${x2} ${y2 - wobble / 2}`, 'stroke'); break;\n          case 'strike-through':\n            add(`M ${x1} ${cy + offset} Q ${cx} ${cy - wobble} ${x2} ${cy + offset}`, 'stroke'); break;\n          case 'crossed-off':\n            add(`M ${x1} ${y1} Q ${cx} ${cy - wobble} ${x2} ${y2} M ${x2} ${y1} Q ${cx} ${cy + wobble} ${x1} ${y2}`, 'stroke'); break;\n          case 'box':\n            add(`M ${x1} ${y1} Q ${cx} ${y1 - wobble} ${x2} ${y1} L ${x2} ${y2} Q ${cx} ${y2 + wobble} ${x1} ${y2} Z`, 'stroke'); break;\n          case 'circle':\n            // The original inscribed ellipse cut through end glyphs at 32px.\n            // Bow each edge outward through the padded corners instead: every\n            // segment stays outside the text rectangle while retaining a loose loop.\n            add(`M ${x1} ${cy} Q ${x1 - bow} ${y1} ${x1} ${y1} Q ${cx} ${y1 - bow} ${x2} ${y1} Q ${x2 + bow} ${cy} ${x2} ${y2} Q ${cx} ${y2 + bow} ${x1} ${y2} Q ${x1 - bow} ${cy} ${x1} ${cy} Z`, 'stroke'); break;\n          case 'bracket': {\n            const arm = Math.min(line.height / 3, line.width / 4);\n            add(`M ${x1 + arm} ${y1} L ${x1} ${y1} L ${x1} ${y2} L ${x1 + arm} ${y2} M ${x2 - arm} ${y1} L ${x2} ${y1} L ${x2} ${y2} L ${x2 - arm} ${y2}`, 'stroke'); break;\n          }\n        }\n      }\n    }\n    // Include control points, both sketch passes and stroke caps so the SVG\n    // viewBox cannot clip an underline or a bracket at large text sizes.\n    const outset = Math.max(2 * wobble, bow + wobble / 2) + strokeWidth / 2;\n    const left = l - outset, top = t - outset, right = r + outset, bottom = b + outset;\n    if (!bounds) bounds = { x: left, y: top, width: right - left, height: bottom - top };\n    else {\n      const x = Math.min(bounds.x, left), y = Math.min(bounds.y, top);\n      bounds = { x, y, width: Math.max(bounds.x + bounds.width, right) - x, height: Math.max(bounds.y + bounds.height, bottom) - y };\n    }\n  }\n  // Overflow can occur even with finite inputs. Reject it here instead of\n  // handing NaN/Infinity geometry to a native SVG implementation.\n  if (bounds) for (const value of Object.values(bounds)) finite(value, 'Annotation bounds');\n  return { paths, bounds };\n}\n"]}

package/dist/version.d.ts

@@ -1,3 +1,3 @@
 /** Package release shown by documentation surfaces. Kept in sync by a test. */
-export declare const designSystemVersion: "1.13.0";
+export declare const designSystemVersion: "1.14.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,3 +1,3 @@
 /** Package release shown by documentation surfaces. Kept in sync by a test. */
-export const designSystemVersion = "1.13.0";
+export const designSystemVersion = "1.14.0";
 //# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,MAAM,CAAC,MAAM,mBAAmB,GAAG,QAAiB,CAAC","sourcesContent":["/** Package release shown by documentation surfaces. Kept in sync by a test. */\nexport const designSystemVersion = \"1.13.0\" as const;\n"]}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,MAAM,CAAC,MAAM,mBAAmB,GAAG,QAAiB,CAAC","sourcesContent":["/** Package release shown by documentation surfaces. Kept in sync by a test. */\nexport const designSystemVersion = \"1.14.0\" as const;\n"]}

package/docs/agreement.md

@@ -1,5 +1,7 @@
 # Agreement contract
 
+검토일: 2026-10-07.
+
 **문제.** 가입·결제 앞에 서는 약관 동의 묶음이다. 전체 동의 한 줄과 개별 항목들,
 필수/선택 구분, 각 항목의 전문 보기가 한 덩어리로 움직인다.
 
@@ -36,3 +38,15 @@ accessibility state와 `openDetail` action이다. 두 표면 모두 전체 동
 이전에는 토글에서만 불려 `defaultCheckedIds`·`checkedIds`가 처음부터 필수를 채운 경우 첫 `satisfied: true`가 오지 않아,
 이 콜백에 연결한 제출 버튼이 꺼진 채 남았다. 파생 상태가 바뀔 때마다 부르는 대안은 호출 수가 렌더 횟수에 묶여 버렸다.
 호출 수를 세던 소비자는 마운트 1회가 늘어난다(Changeset `recipe-parity-followups`).
+
+**제출 중 묶음 잠금(2026-10-07).** Utilverse 가입 화면은 서버 요청 동안 필수 약관의
+체크 값을 고정한다. 개별 `required + disabled`를 허용하면 필수/선택 분모 의미가 바뀌므로
+`descriptor.disabled`를 별도로 제공한다. 기본 false이며 전체/개별 toggle은 잠겼을 때
+동일 selection을 반환하고 renderer는 변경 callback을 발생시키지 않는다. `all`, `satisfied`,
+`missingRequiredIds`와 전문 읽기는 그대로다. onStateChange의 마운트/사용자 토글 계약도
+그대로이며 제어 값·약관 버전 변경 후 판정은 제품이 resolver로 다시 계산한다. UI 잠금은
+서버의 동의 버전 검증·중복 요청 보호를 대신하지 않는다.
+
+## 큰 글자 배치 보완 (2026-10-07)
+
+긴 전문 버튼이 제목 폭을 빼앗아 한국어가 세로로 끊기는 문제를 확인했다. 제목 기준 폭을 70%로 두고 전문 버튼은 줄바꿈한다. Native는 flexBasis만으로 축소를 막지 못하므로 같은 최소 폭을 적용한다. 체크/혼합 표시도 글꼴 문자가 아닌 고정 크기 도형으로 그려 2배 글자에서 원 밖으로 나가지 않는다. 검증 범위는 [약관 QA](../../../docs/qa/2026-10-07-agreement-lock.md)에 기록한다.

package/docs/dialog.md

@@ -1,7 +1,7 @@
 # Dialog
 
 Dialog provides a modal boundary for a task that needs the user's attention. This
-Reviewed: 2026-10-05. The original
+Reviewed: 2026-10-07. The original
 contract was recorded during the 2026-09-29 promotion audit because Web and Native
 already had different title APIs and dismissal sources, while there was no single
 component guide describing their shared behavior.
@@ -45,3 +45,18 @@ screen-reader behavior remains a separate consumer validation concern.
 Native accessibility follow-up (2026-10-01): at 200% text scale, the close glyph was clipped inside the fixed IconButton frame. Dialog and Sheet now render that decorative glyph at a fixed icon size, matching Toast; title/body text still scales and the named close action and touch target are preserved. `sheet-viewport.test.tsx` checks both renderers and close callbacks.
 
 Native viewport candidate (BT-QA-027, 2026-10-05): BurnTok local QA exposed a long confirmation extending beyond the visible screen. Dialog and AlertDialog now constrain the content surface and provide a shrinking scroll body, with actions outside that body and provider safe-area padding. Host tests cover those structural contracts and cancellation; they cannot prove Yoga geometry. Ordinary-size iOS confirmation and cancellation were checked. Enlarged-text device verification remains pending: the user stopped that QA scope before the candidate was confirmed, so this is not a completed device fix. Font caps and clipped copy were rejected because they remove readable content.
+
+## Optional measured origin motion (unpublished experiment)
+
+`motionOrigin` supplies a trigger rectangle measured immediately before opening in the same physical
+viewport/window coordinate system as the destination. The existing content-transition resolver supplies
+the inverse transform. Source investigation found lost trigger focus and discarded drafts in the external
+Morphing Dialog/Popover demos, so this presentation reuses canonical Dialog state rather than replacing
+the modal engine. It does not implement shared image/text identities or a new Popover engine.
+
+Web retains one subtree through exit and suppresses stale animation completion when reopened.
+Native uses the actual modal measurement and bounds its optional measurement wait by the existing
+enter duration, falling back to ordinary presentation if the host fails to reply. Reduced motion skips
+spatial interpolation. Device geometry, resizing/keyboard behavior, themes and performance remain
+experimental until the QA report verifies them. See the usage guide and
+[origin transition QA](../../../docs/qa/2026-10-07-overlay-origin-transition.md).

package/docs/effect-surface.md

@@ -1,10 +1,10 @@
 # Composable decorative surfaces
 
-2026-10-01. Optional Web/Native presentation, independent implementation inspired
+2026-10-07. Optional Web/Native presentation, independent implementation inspired
 by layered shader composition. No Shaders.com engine, presets or source is shipped.
 
 Import `EffectSurface` from the renderer `/effect-surface` entry. The shared
-`/effect-surface` contract accepts unique `layers` (`mesh`, `glow`, `grain`), a
+`/effect-surface` contract accepts unique `layers` (`mesh`, `glow`, `grain`, `noise`), a
 stable `seed`, `intensity` from 0 to 1, a cycle `period` from 2 to 120 seconds,
 `active` (false by default), and three semantic color references. Web uses local
 SVG/WAAPI; Native requires the existing optional SVG peer and core Animated.
@@ -24,7 +24,7 @@ The static seeded geometry and the base theme background stay visible when motio
 stops. Effects never duplicate content, take focus, intercept touches or add an
 accessible name. The content itself stays in normal layout.
 
-Noise uses a seeded repeating small-dot tile rather than large spots. Geometry
+The existing grain uses a seeded repeating small-dot tile rather than large spots. Geometry
 is shared, while host rasterization and transform details can differ. This is
 atmospheric parity, not a pixel-identical renderer promise. Motion is opt-in and
 slow by default to avoid adding continuous work to ordinary content screens.
@@ -48,3 +48,19 @@ A failed Native foreground animation start keeps the static decoration and stops
 retrying for that effect lifecycle. Descriptor validation stays outside this
 fallback so invalid caller input is still reported. This implements integration
 plan §5's requirement that decorative failures must not remove product content.
+
+
+## Static noise comparison (unpublished after 1.13.1)
+
+The opt-in `noise` layer uses an original 64×64 periodic six-octave value-noise
+alpha tile, generated by `scripts/generate-effect-noise.py`. Both renderers tint
+it with the current theme text color via an SVG mask. Its 64×64 tile repeats in physical host units outside
+the existing geometric 100×100 viewBox; seed shifts the phase. It is not pixel-identical to
+SVG feTurbulence/Perlin noise and grain remains unchanged.
+
+Reason: the installed react-native-svg15.15.5 FeTurbulence.render warns and returns
+null. A shared static mask keeps both hosts visible without a new native/GPU
+peer or per-frame noise generation. Magic UI's reference motivated the comparison,
+but no source or asset from that component is included. Check actual readability
+and rasterization cost before using it over product text. The comparison is at
+`실험/구성/정보 표시/질감 비교`; it is not a promotion of the new layer.

package/docs/generated/component-maturity.md

@@ -1,6 +1,6 @@
 # Component maturity and evidence manifest
 
-> Generated from `@hjmds/design-contracts` 1.13.0. Do not edit this file directly; run `pnpm contracts:sync`.
+> Generated from `@hjmds/design-contracts` 1.14.0. Do not edit this file directly; run `pnpm contracts:sync`.
 
 This document is the human-readable projection of the same catalog and Showcase manifest consumed by product CI.
 

package/docs/generated/renderer-evidence.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
-  "designSystemVersion": "1.13.0",
+  "designSystemVersion": "1.14.0",
   "source": "packages/design-contracts/docs/generated/showcase-manifest.json",
   "surfaces": {
     "web": {
       "packageName": "@hjmds/react",
-      "packageVersion": "1.13.0",
+      "packageVersion": "1.14.0",
       "activeComponents": 103,
       "claimedComponents": 103,
       "completeScenarioComponents": 103,
@@ -5642,7 +5642,7 @@
     },
     "native": {
       "packageName": "@hjmds/react-native",
-      "packageVersion": "1.13.0",
+      "packageVersion": "1.14.0",
       "activeComponents": 83,
       "claimedComponents": 83,
       "completeScenarioComponents": 83,

package/docs/generated/renderer-evidence.md

@@ -1,6 +1,6 @@
 # Renderer evidence coverage
 
-> Generated for HJM 1.13.0. Do not edit directly; run `pnpm evidence:sync`.
+> Generated for HJM 1.14.0. Do not edit directly; run `pnpm evidence:sync`.
 
 This projection joins the canonical surface maturity manifest with first-party renderer claims. Missing scenarios are explicit beta promotion debt; stable surfaces are blocked by CI until none remain.
 

package/docs/generated/showcase-manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 2,
-  "designSystemVersion": "1.13.0",
+  "designSystemVersion": "1.14.0",
   "packageName": "@hjmds/design-contracts",
   "components": [
     {

package/docs/image.md

@@ -1,5 +1,22 @@
 # Image contract
 
+## 정확한 결과 크기 검사 — 2026-10-07, 미게시
+
+Utilverse ADR-0020의 사진 결과 확인은 fit·2배·출력 크기를 구분한다. 기존 Image의 cover/contain/fill은
+요소 안에서 이미지를 맞추는 방법이며, 확대 검사 viewport/이동 경계와 다르다. 새 이미지 primitive를
+만들지 않고 기존 `components/image` subpath에 `resolveImageInspectionGeometry(image, viewport, mode)`를 추가한다.
+
+- `mode`: `fit`은 남은 viewport에 전체 이미지를 맞추며 작은 이미지는 확대한다. `double`은 그 2배다.
+- `pixels`: 출력 이미지의 width/height와 같은 layout 단위. 기기의 물리 pixel과 1:1이라는 뜻이 아니다.
+- 반환은 scale/width/height와 중앙 기준 양·음 이동 한계 panBounds.x/y다. 모자라는 축의 이동 한계는 0이다.
+- image/viewport 크기는 양수·유한값이어야 한다. 미측정 0이나 계산 overflow는 RangeError로 거절한다.
+  알려지지 않은 mode는 TypeError다. renderer는 실제 viewport 측정 후 호출해야 한다.
+
+600×600 사진, 402×454 viewport의 2배는 804×804, 이동 한계는 x ±201/y ±175다. iOS의
+zoom-toolkit Gallery는 scale=1 상태의 세로 pan을 pull로 처리해 손을 떼면 0으로 돌려보냈다.
+같은 peer의 ResumableZoom에서는 위 한계를 실측했다. Gallery private scale을 바꾸거나 원본 크기를
+속이지 않는다. 이 순수 geometry는 아직 ImageViewer의 공개 배율 UI에 연결되지 않았다.
+
 **문제.** 이 시스템에 이미지가 하나도 없었습니다. 사진 콘텐츠(선수 프로필 사진, FA 등급
 차트 이미지)를 레이아웃 밀림 없이, 로드 실패에도 의미를 잃지 않게 보여 주는 첫 계약입니다.
 

package/docs/optional-adapters.md

@@ -1,5 +1,30 @@
 # Optional presentation adapters
 
+## Image host extension — 2026-10-07 (unpublished)
+
+Native ImageViewer accepts `renderImage` with the item, measured viewport width/height and
+`onReady`/`onError`. This lets a product retain Expo display events and cache policy without
+adding Expo to the adapter. `onImageStatusChange` reports loading/ready/error for every mounted
+item, including offscreen pages. It is not current-page visibility or user review approval.
+Default RN Image still uses onLoad; an Expo consumer can use onDisplay instead. Retry remounts
+the image host, and callbacks from retired attempts or closed/replaced sessions are ignored.
+Failure stays terminal until retry. Closing sends no final status event; the product owns
+review invalidation on close, replacement and view-mode changes. This closes the host gap
+identified in Utilverse ADR-0020. The optional controlled `inspection` config adds fit/2x/output-size
+review using positive intrinsic item width/height, the shared image geometry resolver and ResumableZoom.
+It fixes the image scale and provides clamped pan plus non-drag directional/center controls; the
+ordinary Gallery keeps its pinch/paging behavior when inspection is absent. Inspection pages use
+previous/next buttons, not swipe paging. Mode, viewport, item and retry changes remount the host,
+retire callbacks and reset readiness/position. Output-size means layout units, not physical device pixels.
+Host width/height are the computed image dimensions in inspection mode (possibly larger than the viewport).
+The [image usage guide](usage/components/image.md) defines labels, placement and review invalidation.
+This is unpublished and is not proof of Expo onDisplay validation or Utilverse adoption.
+The Native Modal accepts supportedOrientations in fullScreen presentation. Optional left/right
+safe-area insets protect controls and feedback in landscape while the gallery remains full width.
+Products must supply updated insets and permit rotation in their manifests; OS rotation lock still applies.
+The additive Native-only props keep this optional subpath and its existing peers; the base Image
+renderers retain their own host APIs. There is no Web ImageViewer counterpart.
+
 ## Current evidence — 2026-09-30
 
 The six opt-in entries are implemented. The earlier checkout verification below is a historical

package/docs/popover.md

@@ -154,3 +154,18 @@ Dialog 안의 Popover는 첫 Escape를 소유한다. 내부 Menu가 Escape를
 재시도, dismiss 정책, 중첩 modal/menu, 선택형 hover 지연과 touch/keyboard press 경로,
 320px·2배 글자·RTL·충돌 배치, exit 격리를 다룬다.
 제품 채택·실제 보조기기 검증은 남아 있다.
+
+
+## 선택적 출발 위치 전환 (미게시, 2026-10-07)
+
+Motion Primitives의 Add Note 예제에서 닫기 후 초안과 트리거 초점이 사라지는 것을 확인했다.
+별도 MorphingPopover 상태 엔진을 도입하는 대신 기존 Popover에 `motionOrigin?: TransitionRect`를
+추가한다. viewport 좌표를 받고, 충돌 회피 위치가 확정된 후 Dialog와 공유하는 WAAPI 표현 helper를 쓴다.
+시간·easing은 Popover recipe가 소유한다. 움직이는 크기를 충돌 계산에 다시 넣으면 스크롤 중 위치가
+흔들리므로 측정에는 layout 크기를 쓴다. 기존 호출은 기존 측정·opacity 전환을 유지한다.
+
+이 옵션은 비모달 의미를 바꾸지 않는다. Escape/닫기는 기존 시점에 트리거로 초점을 돌리고,
+바깥 클릭/Tab은 이동한 대상의 초점을 유지한다. 닫는 동안 inert/aria-hidden이며 빠른 재열기는
+이전 animation 완료를 무시한다. 초안과 서버 저장은 제품 소유이며 portal 밖에서 보존한다.
+잘못된 좌표·모션 감소·WAAPI 미지원은 공간 전환 없이 기존 경로를 사용한다.
+Native Popover는 여전히 제공하지 않는다. 모바일의 같은 편집 목적에는 Dialog/Sheet를 사용한다.

package/docs/rating.md

@@ -1,4 +1,9 @@
-# Rating — 계약을 만들지 않는다
+# Rating — 과거 판단과 현재 계약
+
+> 2026-10-07 현재 상태 정정: 2026-10-06 사용자 레퍼런스 적용 요청으로 정수 선택·미평가·소수 평균을
+> 구분하는 supplemental Rating을 추가했다. 현재 계약은 [reference-controls](reference-controls.md),
+> import와 배치는 [사용 지침](usage/components/rating.md)을 따른다. 아래 “만들지 않는다”는 과거 판단이며
+> 현재 API 부재를 뜻하지 않는다. Slider 기반 반점 입력 예제는 별도 용도로 유지한다.
 
 > 2026-09-30 정리: 구현된 조합을 미구현으로 집계하지 않도록 독립 Planned 행과 catalog ID를 제거했다.
 > 기존 조합 예제와 공개 helper는 유지하며, 참조표는 실제 구성 컴포넌트로 연결한다.

package/docs/reference-controls.md

@@ -0,0 +1,40 @@
+# 이미지 비교와 별점 계약
+
+검토일: 2026-10-07 · 상태: 실험 · 변경 계기: 11개 UI 레퍼런스 조사에서 HJM의 전용 대응이 없는 두 기능을 확인했고 사용자가 적용을 요청했다.
+
+`reference-controls`는 기존 Image와 Slider가 제공하지 않는 **동일 좌표 이미지 비교**의 조합과,
+일반 RadioGroup이 구분하지 않는 **미평가·정수 입력·소수 평균**을 정의한다. canonical catalog는
+늘리지 않으며 두 renderer의 `/image-comparison`, `/rating`에서만 제공한다. root export와 새 peer는 없다.
+
+## Rating
+
+- `label`, `value`, `getValueLabel`을 제품이 전달한다. `value`는 controlled이며 자동 저장하지 않는다.
+- `null`은 미평가. 입력은 1~max의 정수, `readOnly` 평균은 0~max의 소수를 허용한다.
+- `max` 기본 5, 범위 1~10. 무한한 별 행은 점수 척도가 아니라 목록이 되므로 거부한다.
+- 입력형은 `onValueChange` 필수. `clearLabel`이 있으면 명시적으로 null로 지운다.
+  Web은 초기화 버튼이 비활성화되기 전에 첫 radio로 초점을 옮긴다. 2026-10-07 실제 키보드 검증에서
+  초기화 후 body로 초점이 빠져 재선택 위치를 잃는 문제를 확인했기 때문이다.
+- Web은 실제 radio와 name으로 키보드/폼 제출을 사용한다. Native는 radio role과 checked/disabled
+  상태를 제공한다. 읽기 전용은 하나의 이름 있는 이미지이며 입력처럼 초점을 받지 않는다.
+- 별은 값의 장식이고 현지화된 값 텍스트가 의미를 전달한다. 외부 SVG·폰트·아이콘 패키지를 추가하지 않았다.
+- Web은 기존 styles.css가 필요하다. 큰 글자에서는 별 행을 감아 배치한다.
+
+## ImageComparison
+
+- `before`, `after`는 `{src,width,height,label}`이고 같은 aspect ratio가 필요하다. 자동 crop·늘이기는
+  비교 좌표를 바꾸므로 거부한다. 기본 Image가 로딩 오류의 이름과 fallback을 소유한다.
+- controlled `value`는 0~100이며 **왼쪽에 보이는 before의 비율**이다. 0이면 after 전체, 100이면 before 전체.
+  이미지와 전후 라벨의 위치는 RTL에서도 물리 좌표를 유지하고 각 문구의 쓰기 방향은 제품 언어를 따른다.
+  2026-10-07 실제 RTL 화면에서 라벨만 반전되어 이미지와 불일치한 문제를 수정했다.
+- `label`, `getValueText`, `onValueChange`를 전달한다. Native에는 `decrementLabel`·`incrementLabel`도 필수다.
+- 구분선은 장식이며 드래그 핸들이 아니다. 아래의 기존 Slider로 드래그·키보드·Native adjustable
+  action을 제공한다. 독자 PanResponder를 만들지 않아 세로 스크롤 판정을 Slider와 공유한다.
+- Native는 프레임 폭을 측정하고 두 이미지 모두 전체 폭으로 렌더링한 후 before를 잘라 표시한다.
+- 서버 업로드·이미지 처리·원본 저장·기록 권한은 제품 소유다. 서로 다른 시점/대상을 비교한다고
+  자동으로 변화율이나 품질 점수를 계산하지 않는다.
+
+## 참조와 검증 경계
+
+[조사](../../../docs/plans/ui-reference-full-audit-2026-10-06.md)의 Motion Image Comparison과
+Component Gallery Rating에서 사용자 문제를 확인했다. 원본 코드를 복사하지 않고 HJM Image/Slider,
+semantic token, 플랫폼 입력 의미로 구현했다. Native 호스트 검사는 iOS/Android 실기기 증거가 아니다.

package/docs/screen-patterns.md

@@ -307,6 +307,8 @@ SearchScreen accepts a queryField slot for an existing accessible SearchField wi
 | 정렬은 결과 머리 끝 Menu(single). 바꾸면 본문을 맨 위로 | Menu 지침이 정렬을 용도로 명시. 시트 안 정렬은 정렬 하나에 시트 왕복이 필요 | 필터 시트 안 정렬 |
 | `queryLabelVisibility="hidden"`: 보이는 label을 빼고 `queryLabel`을 접근성 이름(Web `aria-label`, Native `accessibilityLabel`)과 placeholder로 쓴다 | 참고 서비스 공통 모양. 1배 약 22, 2배 약 40만큼 고정 영역을 아낀다(2026-10-06 실측). placeholder가 검색 대상을 알린다(Apple HIG) | placeholder 없이 숨김(보이는 이름이 없는 입력) |
 | `searching`+`searchingLabel`: Web `loading`, Native `busy`+`busyLabel`을 한 이름으로. 둘 다 주거나 둘 다 생략(타입) | 2026-10-06 utilverse 적용 조사: 진행 표시 하나 때문에 제품이 입력을 `queryField`로 통째로 바꿨다 | 플랫폼별 이름 그대로 노출 |
+| 확정하면 키보드를 닫는다(1.13.1). Native는 모든 확정에서 `Keyboard.dismiss()`(one-step 포함). Web은 고른 제안·최근·추천이면 그 행이 사라지기 전에 결과 영역(`.hjm-search-screen__results`, `tabIndex=-1`)으로 포커스를 옮기고, Enter 확정은 입력에 포커스를 남긴다 | utilverse 1.13.0 적용: 검색 키만 키보드를 닫아 추천 검색어를 고르면 키보드가 결과를 가렸다(제품이 `onSubmit`에서 dismiss). Web은 고른 행이 사라지며 포커스가 `<body>`로 떨어졌다. 결과 영역은 단계가 바뀌어도 남는 자리이고, 입력을 떠나 모바일 브라우저 키보드도 닫힌다. Enter는 입력이 그대로 보이고 바로 고쳐 다시 찾는 흐름이라 남긴다 | Web `blur()`만(포커스가 `<body>`로 가 낭독 위치를 잃음), 항상 입력으로 이동(모바일에서 키보드가 다시 열림), Native 포커스 이동(낭독 커서가 화면을 다시 읽음) |
+| `hostGutter`(`ContainerGutter`, 기본 `none`, 1.13.1): `filtersOverflow="scroll"` 줄을 화면 여백(`contentInset="none"`이면 0)에 host 여백을 더한 만큼 넓힌다 | utilverse 1.13.0 적용: route(Container `regular`)와 Sheet가 여백을 주는 화면에서 `contentInset="none"`이면 줄이 host 여백에서 잘렸다. SearchScreen은 host 여백을 볼 수 없다. 숫자가 아니라 Container gutter 이름이라 제품 코드에 임의 간격이 들어가지 않는다 | 창 기준 위치 측정(첫 프레임 점프, 가운데 정렬된 최대 폭 host에서 틀림), `contentInset="none"`이면 항상 16 가정(host 여백 20·24와 어긋남) |
 
 2026-10-06 릴리스 전 정리에서 Native `SearchField`도 `busy`인 동안 입력을 받게 했다(Web `loading`과 같다). 그 전에는 입력 변경을 무시해,
 `searching`을 입력 중 제안 조회에 켜면 그동안 친 글자가 사라졌고 지침이 "확정 결과 요청에만"으로 제한했다. 진행 표시가 입력을

package/docs/sheet.md

@@ -75,3 +75,12 @@ Diairy QA W16 reproduced Chrome default backdrop blur undoing Dialog focus retur
 - Web 여백은 Native와 같은 recipe 값이다: 위아래 `content.paddingTop/Bottom`(sm 12), 좌우 `paddingHorizontal`(lg 20),
   머리·본문·footer 사이 `body.gap`(md 16), footer 위 `footer.paddingTop`(sm 12). Web은 Dialog 여백(20)을 쓰고 있었다.
   본문 스크롤 상자는 자식 포커스 링이 잘리지 않도록 4px 안쪽 여백과 같은 크기의 음수 margin을 둔다(보이는 간격은 recipe 값).
+
+## 고정 높이 본문 채우기 (1.13.1, 2026-10-06)
+
+고정 높이 Native Sheet(`size` `medium`·`large`·`full`, 옆 시트)의 본문은 머리·footer를 뺀 남은 높이를 차지한다(`flexGrow: 1`, `minHeight: 0`).
+`scrollable`이면 ScrollView가 늘고 그 내용 컨테이너는 늘지 않는다. Web `.hjm-sheet__body`는 이미 `flex: 1 1 auto`였다.
+계기: utilverse가 1.13.0을 적용하며 `size="large"` Sheet 안에 SearchScreen을 넣었는데, 본문이 내용 높이 View라 ScreenLayout의 `flex: 1` 루트가
+0pt가 되고 검색 입력만 그려졌다(iPhone 17 Pro · iOS 26.5, 이전 코드로도 재현). 제품은 창 높이 `flexBasis`로 우회했다.
+`auto`는 내용 높이 그대로다(늘 남는 공간이 없다). 바뀌는 모습: 고정 높이 시트의 `footer`가 본문 바로 아래가 아니라 시트 아래에 붙는다(Web과 같다).
+버린 대안: 새 `bodyLayout` prop(기본값을 그대로 두면 Web과 다른 동작이 남고 제품마다 켜야 한다).

package/docs/task-list.md

@@ -1,6 +1,6 @@
 # Task list
 
-Reviewed: 2026-10-01. Web and Native expose TaskList through `/task-list`.
+Reviewed: 2026-10-07. Web and Native expose TaskList through `/task-list`.
 TaskList composes existing List and Checkbox rather than creating another selection
 or gesture engine. Each controlled item has unique `id`, localized `label`, boolean
 `completed`, optional `description` and `disabled`. Invalid identity/completion data
@@ -30,3 +30,17 @@ found that 200% text scaling enlarged Checkbox's decorative mark beyond its fixe
 Native Checkbox now keeps the checked/mixed artwork at the recipe typography size
 while its label and description continue scaling. TaskList inherits this correction
 through Checkbox; it does not provide a second selection indicator.
+
+## Independent item actions
+
+`renderItemAction({item, disabled})` optionally supplies a product-localized control below
+that item's checkbox. `disabled` combines the list and item disabled flags; pass it to
+the control. The slot does not save, remove, or confirm anything itself. Keep asynchronous
+storage and rollback in the product. The action is a sibling of Checkbox, never inside its
+label, so it has its own press/focus target. It follows the checkbox with spacing.sm (12)
+and remains part of renderItem when renderCollection supplies sorting.
+
+The separate line preserves the full label width at large text sizes. Utilverse checklist
+rows need deletion alongside completion (2026-10-07 consumer audit), which the previous
+completion-only API could not express without rebuilding row layout. Both showcases now
+include independent delete actions; device drag/focus/large-text action QA remains pending.

package/docs/text-annotation.md

@@ -0,0 +1,85 @@
+# 문장 주석 — 구현 중
+
+검토일: 2026-10-07. Web 내부 renderer는 구현했고 공개 renderer·Storybook 실험은 아직 없다.
+
+사용자가 제공한 Magic UI Highlighter를 조사한 결과 기존 TextFormat은 Web의
+단축키·코드·인용 요소를 위한 계약이라 손그림 주석을 직접 대체하지 못했다.
+조사 근거는 [원본 검토](../../../docs/qa/2026-10-07-highlighter-reference.md)다.
+
+## 공통 구현
+
+`src/text-annotation.ts`는 renderer가 측정한 시각적 줄 조각의 x/y/width/height에서
+SVG 경로를 만든다. `@hjmds/design-contracts/text-annotation` subpath로 공개하며 root에는
+추가하지 않는다. renderer에서 같은 경로 계산을 사용하면서 기본 소비 번들에는 들어가지
+않도록 한 선택이다. 이 export 추가가 renderer 사용 가능 또는 npm 게시를 뜻하지 않는다.
+
+- highlight는 뒤쪽 채움, underline/box/circle/strike-through/crossed-off/bracket은
+  두 번 그린 외곽 경로다. 무작위 값 대신 결정적인 작은 오프셋을 쓴다.
+- 줄 사이 빈 영역을 한 덩어리로 칠하지 않는다. 동일 줄의 bidi 조각도 호스트가 측정한
+  물리 좌표 그대로 받으며 문자열 길이로 위치를 추측하거나 RTL을 한 번 더 뒤집지 않는다.
+- 기본 strokeWidth=1.5, padding=2는 장식 경로 단위다. 문장 레이아웃이나 전역 토큰을
+  바꾸지 않는다. 작은 구두점에는 흔들림을 줄이고 빈 줄에는 경로를 만들지 않는다.
+- 반환 bounds는 경로 제어점·두 번 그린 선·선 굵기를 포함한다. 호스트는 이를 SVG
+  영역에 반영해야 하며 원래 Text의 크기나 줄바꿈 폭을 늘려서는 안 된다.
+- circle의 초기 내접 타원이 32px 글자의 양 끝을 가로질러 바깥으로 휜 루프로 수정했다.
+  여백 0이나 굵은 펜에서도 해당 줄의 글자 영역 밖에 선을 두도록 최소 간격을 계산한다.
+  현재 모양은 타원보다 둥근 테두리에 가깝다. 원본과의 시각적 차이, 조밀한 줄 간격에서
+  이웃 줄과의 충돌 및 팔레트 검증은 남아 있으며 원본 동등 표현으로 주장하지 않는다.
+- 음수 크기, 비유한 좌표와 계산 overflow는 렌더링 전 거부한다. 스크롤·상대 위치 때문에
+  음수 x/y는 유효하며 소수 단위 측정도 유지한다.
+- `mergeTextAnnotationFragments`는 같은 실제 줄(lineIndex)의 맞닿은 글꼴 조각을 합친다.
+  Native Skia가 한글·공백 fallback을 23개 조각으로 반환해 marker padding이 겹친 실측을
+  반영한 기능이다. Float32 경계 오차만 흡수하도록 0.01px 허용 오차를 사용하며 선택하지
+  않은 gap이나 다른 줄은 합치지 않는다. 이 함수가 줄 번호를 문자열에서 추측하지 않는다.
+
+## Web 내부 renderer와 Native의 남은 계약
+
+`packages/react/src/text-annotation.tsx`는 inline span의 실제 Range 사각형을 측정한다.
+문장 조각을 inline-block으로 바꾸지 않는다. 절대 위치 기준점과 SVG를 접근성·hit-test에서
+제외하고, 문구·앞 문장·조상 크기 및 스타일·글꼴 로드 변화에 재측정한다. 새 문구가 이전
+문구 경로를 받지 않도록 측정 세대를 나눈다. 동일 geometry에는 state 갱신을 보내지 않는다.
+진입 모션은 motion.slow=320ms, 모션 감소 또는 숨겨진 문서에서는 즉시 표시하며,
+리사이즈에는 다시 재생하지 않는다. highlight의 20% brand wash는 실험값이다. HJM 기본·Utilverse·BurnTok의
+light/dark × bg/surface × body/muted 24조합에서는 합성 뒤 4.5:1을 통과했으며,
+다른 표면·제품 색·이미지 배경의 대비를 보장하지 않는다. renderer는 아직 package exports에 넣지 않았다.
+
+Native 0.86.2/Expo Go 57.0.9/iOS 26.5에서 진단 fixture를 실행했다. 부모의 onTextLayout은
+폭 280→184에서 2→3줄을 보고했으나 중첩 Text의 onTextLayout/onLayout은 관찰되지 않았고
+measure는 0×0이었다. 이 경로를 실제 줄별 측정으로 사용할 수 없다. 진단 소스는
+`showcase/native/src/devtools/TextAnnotationMeasurementProbe.tsx`에 보존했다.
+
+후속 `TextAnnotationSkiaProbe.tsx`는 Skia 2.6.2의 Paragraph로 측정하고 **같은 Paragraph**를
+그린다. getRectsForRange와 실제 line metrics를 이용해 한글 23→3, emoji 9→2, 혼합 RTL
+21→3개의 표시 영역을 얻었다. RTL 폭 280→184에서 5줄로 다시 배치했다. 이 좌표를 다른
+Native Text 위에 올리는 것은 금지한다. 비교 fixture에서 두 엔진의 줄바꿈이 달랐다.
+이는 Native renderer 후보의 측정 증거이며 일반 Text 대체가 아니다. Canvas의 읽기 이름만으로
+Native Text 선택·복사 기능이 생기지 않는다. 폰트·스케일·외곽 잘림·선택·접근성·Android를
+해결하고 공개 API/실험으로 연결하는 일이 남았다.
+
+Web은 inline 문장과 Range.getClientRects의 줄 조각, Native는 실제 텍스트 레이아웃에서
+문장 일부의 줄별 위치를 얻어야 한다. 전체 문단을 주석으로 바꾸는 것으로 이 요구를
+대체하지 않는다. 글꼴 로드·문구 교체·글자 크기·폭 변경마다 최신 geometry를 공급한다.
+
+본문은 처음부터 읽고 선택할 수 있어야 한다. 주석은 접근성 트리와 pointer hit-testing에서
+제외하며 highlight는 글자 뒤에 둔다. 색은 제품 팔레트의 의미 색으로 공급하고 대비를
+검증한다. 취소선이 데이터의 삭제 상태를 대신 전달하지 않도록 제품 문구를 유지한다.
+모션 감소에서는 즉시 완성된 주석을 보인다. 비활성 화면·unmount 시 animation과 관찰자를
+정리한다. 리사이즈로 geometry만 바뀔 때 진입 모션을 반복하지 않는다.
+
+## 검증 범위
+
+현재 계약 테스트 15개는 줄 조각 분리/병합, RTL 물리 좌표 유지, 7가지 경로의 결정성, 소수·음수
+좌표, 빈 상태, 재측정, 비정상 입력을 확인한다. 실제 글자 측정, 글자 대비, 모션, 성능,
+스크린리더 또는 소비 앱 채택의 증거는 아니다. 별도 Web 브라우저 테스트 7개는 실제
+DOM 측정·줄바꿈·선택·RTL·폭 변경·문구 교체·모션 감소를 검증했다. 전체 스타일·기기·성능
+검증을 마쳤다는 뜻은 아니다. 추가된 큰 글자 회귀는 선 경로를 0.5px 간격으로 샘플링해
+선 두께까지 해당 줄의 글자 사각형 바깥에 있는지 검사한다. 이는 이웃 줄까지 포함한
+모든 배치 조합의 가독성 검증은 아니다.
+
+공개 export·양 renderer·사용 지침·실험 스토리·UI 및 행동 증거가 연결된 다음에 실험 수에
+포함한다. 안정화·npm 게시·Utilverse 적용은 사용자 요청의 후속 단계로 남아 있다.
+
+Web의 같은 top/height 수직 대역에서 맞닿은 bidi run은 기존 fragment 병합 계약으로
+한 주석을 그린다. 390px 아랍어/영어 혼합 문장에서 내부 세로선이 생긴 실측에 따른
+수정이다. 수직 대역이 다르거나 실제 수평 gap이 있으면 합치지 않는다. 추가된 회귀·
+제품 대비·진입 모션 재생 검사까지 Web 브라우저 테스트는 10개다.