@beyondwork/docx-react-component 1.0.56 → 1.0.57

package/src/runtime/surface-projection.ts

@@ -3,7 +3,9 @@ import type {
   EditorSurfaceSnapshot,
   SecondaryStorySurface,
   SurfaceBlockSnapshot,
+  SurfaceDrawingAnchor,
   SurfaceInlineSegment,
+  SurfacePictureEffects,
   SurfaceTableCellSnapshot,
   SurfaceTableRowSnapshot,
   SurfaceTextMark,
@@ -30,6 +32,9 @@ import type {
   TableCellBorders,
   TableNode,
   TextMark,
+  DrawingFrameNode,
+  PictureContent,
+  ShapeContent,
   VmlShapeNode,
   WordArtNode,
 } from "../model/canonical-document.ts";
@@ -57,7 +62,7 @@ import {
   resolveNumberingMarkerRunFormatting,
 } from "./paragraph-style-resolver.ts";
 import { resolveHyperlinkRunFormatting } from "./hyperlink-color-resolver.ts";
-import { concretizeThemeColors } from "./theme-color-resolver.ts";
+import { concretizeThemeColors, ThemeColorResolver } from "./theme-color-resolver.ts";
 import type { CanonicalParagraphFormatting, CanonicalRunFormatting } from "../model/canonical-document.ts";
 
 interface ParagraphAccumulator {
@@ -93,6 +98,13 @@ export function createEditorSurfaceSnapshot(
   const blocks: SurfaceBlockSnapshot[] = [];
   const lockedFragmentIds: string[] = [];
   const numberingPrefixResolver = createNumberingPrefixResolver(document.numbering);
+  // Open a chartModelStore build pass tagged with the document envelope.
+  // Every `chart_preview` node populated during the pass records its id
+  // in the pass's seen-set; `endBuildPass()` below evicts store entries
+  // from previous documents (different owner) and stale entries from
+  // earlier builds (same owner, not seen this pass). Previously the
+  // store grew unbounded across document loads — documented v1 gap.
+  chartModelStore.beginBuildPass(document);
   let cursor = 0;
   const counters = {
     paragraph: 0,
@@ -157,6 +169,12 @@ export function createEditorSurfaceSnapshot(
 
   const secondaryStories = createSecondaryStorySurfaces(document, numberingPrefixResolver);
 
+  // Close the chartModelStore build pass. Evicts entries from previous
+  // documents + stale entries whose ids no longer appear in the current
+  // document. Must happen AFTER secondary stories (they may also contain
+  // chart_preview nodes).
+  chartModelStore.endBuildPass();
+
   return {
     storySize: cursor,
     plainText: createPlainText(blocks),
@@ -712,6 +730,12 @@ function createParagraphBlock(
   const lockedFragmentIds: string[] = [];
   let cursor = start;
   const children = Array.isArray(paragraph.children) ? paragraph.children : [];
+  // Build once per paragraph block — ThemeColorResolver is a thin wrapper
+  // around CanonicalTheme that applies clrMap remapping. Constructed here so
+  // it is not recreated on every text segment (inner hot loop).
+  const themeResolver = document.subParts?.canonicalTheme
+    ? new ThemeColorResolver(document.subParts.canonicalTheme)
+    : undefined;
 
   for (const child of children) {
     const result = appendInlineSegments(
@@ -722,6 +746,7 @@ function createParagraphBlock(
       promoteSecondaryStoryTextBoxes,
       undefined,
       cullBuild,
+      themeResolver,
     );
     cursor = result.nextCursor;
     lockedFragmentIds.push(...result.lockedFragmentIds);
@@ -885,6 +910,7 @@ function appendInlineSegments(
   promoteSecondaryStoryTextBoxes: boolean,
   hyperlinkHref?: string,
   cullBuild: boolean = false,
+  themeResolver?: ThemeColorResolver,
 ): { nextCursor: number; lockedFragmentIds: string[] } {
   switch (node.type) {
     case "text": {
@@ -919,11 +945,11 @@ function appendInlineSegments(
           ? resolveHyperlinkRunFormatting(
               runResolveInput,
               document.styles,
-              document.subParts?.resolvedTheme,
+              themeResolver,
             )
           : concretizeThemeColors(
               resolveEffectiveRunFormatting(runResolveInput, document.styles),
-              document.subParts?.resolvedTheme,
+              themeResolver,
             );
       paragraph.segments.push({
         segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
@@ -967,6 +993,7 @@ function appendInlineSegments(
           promoteSecondaryStoryTextBoxes,
           node.href,
           cullBuild,
+          themeResolver,
         );
         cursor = result.nextCursor;
       }
@@ -1020,15 +1047,18 @@ function appendInlineSegments(
       let parsedChartId: string | undefined;
       if (node.parsedData) {
         parsedChartId = stableChartId(node.rawXml);
-        if (!chartModelStore.has(parsedChartId)) {
-          const { widthPx, heightPx } = extractChartDimensions(node.rawXml);
-          chartModelStore.set(parsedChartId, {
-            model: node.parsedData,
-            widthPx,
-            heightPx,
-            theme: undefined,
-          });
-        }
+        // Always call `set` (even when the entry exists) so the active
+        // `chartModelStore` build pass records the id in its seen-set —
+        // the pass uses the seen-set to evict stale entries from earlier
+        // builds. The entry object is a tiny reference so the set cost
+        // is negligible.
+        const { widthPx, heightPx } = extractChartDimensions(node.rawXml);
+        chartModelStore.set(parsedChartId, {
+          model: node.parsedData,
+          widthPx,
+          heightPx,
+          theme: undefined,
+        });
       }
       return appendComplexPreviewSegment(paragraph, node, start, "Embedded chart", createChartDetail(node), {
         previewMediaId: node.previewMediaId,
@@ -1064,6 +1094,58 @@ function appendInlineSegments(
         );
       }
       return appendComplexPreviewSegment(paragraph, node, start, "Legacy VML drawing", createVmlDetail(node));
+    case "drawing_frame": {
+      const c = node.content;
+      if (c.type === "picture") {
+        const mediaId = c.mediaId ?? `drawing-frame-${start}`;
+        const state: "editable" | "missing" = c.mediaId ? "editable" : "missing";
+        const anchor = surfaceAnchorFromGeometry(node.anchor);
+        const pictureEffects = surfacePictureEffectsFromContent(c);
+        paragraph.segments.push({
+          segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
+          kind: "image",
+          from: start,
+          to: start + 1,
+          mediaId,
+          state,
+          display: node.anchor.display,
+          detail: `Drawing frame image (${node.anchor.extent.widthEmu}\u00d7${node.anchor.extent.heightEmu} EMU).`,
+          ...(anchor ? { anchor } : {}),
+          ...(pictureEffects ? { pictureEffects } : {}),
+        });
+        return { nextCursor: start + 1, lockedFragmentIds: [] };
+      }
+      if (c.type === "shape") {
+        const label = c.isTextBox ? "Text box" : "Drawing shape";
+        const detail = `DrawingFrame shape (${node.anchor.wrapMode}).`;
+        const anchor = surfaceAnchorFromGeometry(node.anchor);
+        const txbxText = c.isTextBox ? extractTxbxFirstText(c.txbxBlocks) : undefined;
+        const surfaceFill = c.fill;
+        paragraph.segments.push({
+          segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
+          kind: "shape",
+          from: start,
+          to: start + 1,
+          label,
+          detail,
+          ...(anchor ? { anchor } : {}),
+          ...(c.geometry !== undefined ? { geometry: c.geometry } : {}),
+          ...(surfaceFill ? { fill: surfaceFill } : {}),
+          ...(c.line ? { line: c.line } : {}),
+          ...(c.isTextBox ? { isTextBox: true } : {}),
+          ...(txbxText ? { txbxText } : {}),
+        });
+        return { nextCursor: start + 1, lockedFragmentIds: [] };
+      }
+      const rawXml = "rawXml" in c ? c.rawXml : "";
+      const label =
+        c.type === "chart_preview"
+          ? "Embedded chart"
+          : c.type === "smartart_preview"
+            ? "SmartArt diagram"
+            : "Drawing frame";
+      return appendComplexPreviewSegment(paragraph, { rawXml } as DrawingFrameNode["content"] & { rawXml: string }, start, label, `DrawingFrame ${c.type} (${node.anchor.wrapMode}).`);
+    }
     case "symbol":
       paragraph.segments.push({
         segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
@@ -1126,6 +1208,7 @@ function appendInlineSegments(
             promoteSecondaryStoryTextBoxes,
             refHyperlinkHref ?? hyperlinkHref,
             cullBuild,
+            themeResolver,
           );
           cursor = result.nextCursor;
           lockedIds.push(...result.lockedFragmentIds);
@@ -1181,6 +1264,95 @@ function appendInlineSegments(
   }
 }
 
+/**
+ * V2c.4 — Map a canonical `AnchorGeometry` onto the surface anchor type.
+ * Returns `undefined` when the anchor carries only the trivial inline
+ * defaults (no positioning / wrap / dist data) so the emitted segment
+ * stays minimal for the common inline-image case.
+ */
+function surfaceAnchorFromGeometry(
+  anchor: DrawingFrameNode["anchor"],
+): SurfaceDrawingAnchor | undefined {
+  // Cheap inline-default short-circuit: inline pictures with no extra
+  // metadata (no positionH/V, no distMargins, no docPr, no behindDoc/etc.)
+  // don't need the anchor bag — N9 float-wrap consumers only care about
+  // floating drawings or anchors with custom positioning.
+  const trivialInline =
+    anchor.display === "inline" &&
+    anchor.wrapMode === "none" &&
+    !anchor.positionH &&
+    !anchor.positionV &&
+    !anchor.distMargins &&
+    anchor.relativeHeight === undefined &&
+    anchor.behindDoc === undefined &&
+    anchor.layoutInCell === undefined &&
+    anchor.allowOverlap === undefined &&
+    anchor.simplePos === undefined &&
+    !anchor.docPr;
+  if (trivialInline) return undefined;
+  return {
+    display: anchor.display,
+    wrapMode: anchor.wrapMode,
+    extent: { ...anchor.extent },
+    ...(anchor.positionH ? { positionH: { ...anchor.positionH } } : {}),
+    ...(anchor.positionV ? { positionV: { ...anchor.positionV } } : {}),
+    ...(anchor.distMargins ? { distMargins: { ...anchor.distMargins } } : {}),
+    ...(anchor.relativeHeight !== undefined ? { relativeHeight: anchor.relativeHeight } : {}),
+    ...(anchor.behindDoc !== undefined ? { behindDoc: anchor.behindDoc } : {}),
+    ...(anchor.layoutInCell !== undefined ? { layoutInCell: anchor.layoutInCell } : {}),
+    ...(anchor.allowOverlap !== undefined ? { allowOverlap: anchor.allowOverlap } : {}),
+    ...(anchor.simplePos !== undefined ? { simplePos: anchor.simplePos } : {}),
+    ...(anchor.docPr ? { docPr: { ...anchor.docPr } } : {}),
+  };
+}
+
+/**
+ * V2c.4 — Project picture-effect fields from `PictureContent`.  Returns
+ * `undefined` when none of the effect fields are set so consumers can
+ * fast-path image rendering.
+ */
+function surfacePictureEffectsFromContent(
+  content: PictureContent,
+): SurfacePictureEffects | undefined {
+  const has =
+    content.srcRect !== undefined ||
+    content.rotation !== undefined ||
+    content.flipH !== undefined ||
+    content.flipV !== undefined ||
+    content.presetGeom !== undefined ||
+    content.stretch !== undefined;
+  if (!has) return undefined;
+  return {
+    ...(content.srcRect ? { srcRect: { ...content.srcRect } } : {}),
+    ...(content.rotation !== undefined ? { rotation: content.rotation } : {}),
+    ...(content.flipH !== undefined ? { flipH: content.flipH } : {}),
+    ...(content.flipV !== undefined ? { flipV: content.flipV } : {}),
+    ...(content.presetGeom !== undefined ? { presetGeom: content.presetGeom } : {}),
+    ...(content.stretch !== undefined ? { stretch: content.stretch } : {}),
+  };
+}
+
+/**
+ * V2c.5 — Extract the first paragraph's plain text from a parsed
+ * `txbxBlocks` tree for the `txbxText` segment preview.  The recursion
+ * is shallow — we only walk paragraph-shaped blocks at the top level
+ * and read the immediate run content.  Returns `undefined` when no text
+ * is present.
+ */
+function extractTxbxFirstText(
+  blocks: ShapeContent["txbxBlocks"],
+): string | undefined {
+  if (!blocks || blocks.length === 0) return undefined;
+  for (const block of blocks) {
+    if (block.type !== "paragraph") continue;
+    const runs = (block as { runs?: ReadonlyArray<{ text?: string }> }).runs;
+    if (!runs) continue;
+    const text = runs.map((r) => r.text ?? "").join("").trim();
+    if (text) return text;
+  }
+  return undefined;
+}
+
 function appendComplexPreviewSegment(
   paragraph: ParagraphAccumulator,
   node: { rawXml: string },
@@ -1616,6 +1788,8 @@ function summarizePreviewInline(node: InlineNode): string {
       return node.text ? `[WordArt: ${node.text}]` : "[WordArt]";
     case "vml_shape":
       return node.text ? `[VML: ${node.text}]` : "[Legacy VML drawing]";
+    case "drawing_frame":
+      return node.content.type === "picture" ? "[Image]" : "[Drawing]";
   }
 }
 

package/src/runtime/theme-color-resolver.ts

@@ -1,44 +1,112 @@
 /**
- * Resolve a (`<w:color>`-shaped) theme-color reference to a concrete hex
- * string, applying the `w:themeTint` / `w:themeShade` HSL-luminance
- * modulation per ECMA-376 §17.18.85 / §17.18.83.
+ * Unified runtime color resolver for every OOXML theme reference.
  *
- * Usage:
- *   - The IO layer (`parse-run-formatting.ts`) captures
- *     `colorThemeSlot` / `colorThemeTint` / `colorThemeShade` on
- *     `CanonicalRunFormatting` as raw strings (preserved for
- *     byte-stable round-trip).
- *   - The render/cascade layer calls `resolveThemeColorHex(rPr, theme)`
- *     to collapse the reference to the actual hex colour the browser
- *     should paint. The original fields stay intact so export still
- *     round-trips the theme reference (not the computed hex).
+ * Covers:
+ *   - `<w:color>` §17.18.85/§17.18.83 byte-form `w:themeTint`/`w:themeShade`
+ *     (HSL luminance modulation).
+ *   - `<a:schemeClr>` §20.1.2.3.x DrawingML modifier chain
+ *     `lumMod → lumOff → satMod → hueMod → tint → shade` (per-100,000 units).
+ *   - `<w:clrSchemeMapping>` §17.15.1.17 style-slot → scheme-slot remap
+ *     (including the implicit identity default when settings.xml omits it).
+ *   - `<w:color w:val="auto"/>` → the `t1` style slot via the clrMap.
  *
- * Lane 3 L2.c. Mirrors LibreOffice's `Color::ApplyTintOrShade` at
- * `vendor/libreoffice/include/tools/color.hxx:200-240` (shape only; no
- * code copied — our implementation is pure TypeScript against the
- * ECMA-376 formulae).
+ * Cascade layer entry points:
+ *   - `ThemeColorResolver` class — build once per `CanonicalTheme` snapshot,
+ *     key the cache on `(themeHash, clrMapHash)` per CLAUDE.md §3.
+ *   - `concretizeThemeColors(cascade, resolver)` — run-formatting post-pass.
  *
- * **Scope boundary:** this resolver handles the standard tint/shade
- * pair. Theme-color-mapping (clrSchemeMapping — how "accent1" maps to a
- * different `<w:clrScheme>` slot in older Word versions) is NOT applied
- * here — `resolveThemeColor` from `src/io/ooxml/parse-theme.ts` is the
- * authoritative slot→hex lookup and future work will layer scheme
- * mapping into it.
+ * LibreOffice parity: port of `vendor/libreoffice/oox/source/drawingml/color.cxx`
+ * (shape only; no code copied). Modifier order + HSL/sRGB color-space split
+ * match LO; modifiers are applied in declaration order — do NOT sort.
+ *
+ * The original `colorThemeSlot` / `Tint` / `Shade` fields are preserved on
+ * returned cascades so the export path can re-emit the original theme
+ * reference byte-for-byte.
  */
 
-import type { CanonicalRunFormatting, ResolvedTheme } from "../model/canonical-document.ts";
+import type { CanonicalRunFormatting, CanonicalTheme, ClrSchemeMappingSlot, ResolvedTheme } from "../model/canonical-document.ts";
 import { resolveThemeColor } from "../io/ooxml/parse-theme.ts";
 
+/**
+ * DrawingML color modifier (ECMA-376 §20.1.2.3.x).
+ * Values are in per-100,000 units (e.g. 65_000 = 65%).
+ * Apply in declaration order — do NOT sort or reorder.
+ *
+ * Distinct from w:themeTint / w:themeShade (ECMA-376 §17) which use
+ * hex-byte 0x00–0xFF encoding.
+ */
+export interface DrawingMlColorMod {
+  kind: "lumMod" | "lumOff" | "satMod" | "hueMod" | "shade" | "tint" | "alpha";
+  value: number;
+}
+
+const DML_UNIT = 100_000;
+
+/**
+ * Unified runtime theme color resolver.
+ * Construct once per CanonicalTheme (keyed on themeHash + clrMapHash).
+ * All resolution methods apply clrMap remapping before any slot lookup.
+ */
+export class ThemeColorResolver {
+  private readonly theme: CanonicalTheme;
+
+  constructor(theme: CanonicalTheme) {
+    this.theme = theme;
+  }
+
+  /** Look up a scheme slot with clrMap remapping applied. Returns #RRGGBB or undefined. */
+  resolveSchemeSlot(slot: string): string | undefined {
+    const mapped = this.theme.clrMap[slot as ClrSchemeMappingSlot] ?? slot;
+    const hex = this.theme.clrScheme.colors[mapped];
+    return hex ?? undefined;
+  }
+
+  /** Resolve w:color val="auto" → "text 1" style slot (t1) via clrMap. */
+  resolveAuto(): string | undefined {
+    // "auto" = windowText = "text 1" style slot (t1).
+    // Pass "t1" so clrMap remapping is honoured (e.g. <w:clrSchemeMapping w:t1="dk2"/>).
+    return this.resolveSchemeSlot("t1");
+  }
+
+  /**
+   * Resolve a w:themeColor + w:themeTint/w:themeShade (§17 byte form, 0x00–0xFF).
+   * Delegates to the existing applyThemeTintShade for the HSL transform.
+   */
+  resolveWordThemeColor(
+    colorThemeSlot: string,
+    colorThemeTint: string | undefined,
+    colorThemeShade: string | undefined,
+  ): string | undefined {
+    const baseHex = this.resolveSchemeSlot(colorThemeSlot);
+    if (!baseHex) return undefined;
+    return applyThemeTintShade(baseHex, colorThemeTint, colorThemeShade);
+  }
+
+  /**
+   * Resolve an a:schemeClr reference with DrawingML modifiers (§20).
+   * Modifiers are applied in declaration order. Alpha mods are ignored.
+   * Returns undefined when the slot is absent.
+   */
+  resolveWithModifiers(
+    slot: string,
+    mods: readonly DrawingMlColorMod[],
+  ): string | undefined {
+    const baseHex = this.resolveSchemeSlot(slot);
+    if (!baseHex) return undefined;
+    if (mods.length === 0) return baseHex;
+    return applyDmlMods(baseHex.startsWith("#") ? baseHex : `#${baseHex}`, mods);
+  }
+}
+
 /**
  * Collapse `<w:color>`-style theme-slot + tint + shade references into a
- * single resolved hex colour. Returns:
- *   - the raw `colorHex` as-is when it's a direct hex (the theme fields
- *     are ignored because direct colour wins per ECMA-376 cascade).
- *   - `"auto"` when the source declared `w:color w:val="auto"` (sentinel
- *     kept verbatim per our long-standing A.9 round-trip rule).
- *   - the theme slot's hex — tint/shade applied — when the source
- *     declared `w:themeColor="accent1"` etc. and the theme is available.
- *   - `undefined` otherwise (no colour declared, or theme slot absent).
+ * single resolved hex colour. §17-only byte-form path; does NOT apply
+ * `w:clrSchemeMapping` remap.
+ *
+ * @deprecated Use `ThemeColorResolver.resolveWordThemeColor` instead —
+ * it honours clrSchemeMapping. This free function is retained only for
+ * its targeted unit tests (`test/io/theme-color-tint-shade.test.ts`) and
+ * will be removed once those migrate to the class.
  */
 export function resolveThemeColorHex(
   rPr: Pick<
@@ -81,23 +149,22 @@ export function resolveThemeColorHex(
  */
 export function concretizeThemeColors(
   cascade: CanonicalRunFormatting,
-  theme: ResolvedTheme | undefined,
+  resolver: ThemeColorResolver | undefined,
 ): CanonicalRunFormatting {
   if (!cascade.colorThemeSlot) return cascade;
   if (cascade.colorHex && cascade.colorHex !== "auto") return cascade;
-  // When colorHex is "auto" we intentionally bypass it during theme
-  // resolution: Word's cascade treats `<w:color w:val="auto"
-  // w:themeColor="accent1"/>` as "paint with the theme slot; auto is
-  // the fallback if theme is missing." Pass a stripped input to the
-  // resolver so `colorHex === "auto"` doesn't short-circuit.
-  const resolved = resolveThemeColorHex(
-    {
-      colorThemeSlot: cascade.colorThemeSlot,
-      colorThemeTint: cascade.colorThemeTint,
-      colorThemeShade: cascade.colorThemeShade,
-    },
-    theme,
+  if (!resolver) return cascade;
+
+  // `colorHex === "auto"` with a themeColor slot means "paint via the theme
+  // slot; auto is only the fallback when theme is missing" — so we always
+  // resolve via the slot here. clrSchemeMapping remap is applied inside
+  // `resolver.resolveWordThemeColor`.
+  const resolved = resolver.resolveWordThemeColor(
+    cascade.colorThemeSlot,
+    cascade.colorThemeTint,
+    cascade.colorThemeShade,
   );
+
   if (!resolved || resolved === "auto") return cascade;
   if (resolved === cascade.colorHex) return cascade;
   return { ...cascade, colorHex: resolved };
@@ -174,6 +241,84 @@ function formatHexColor(rgb: { r: number; g: number; b: number }): string {
   return `${to2(rgb.r)}${to2(rgb.g)}${to2(rgb.b)}`;
 }
 
+// ---------------------------------------------------------------------------
+// DrawingML modifier pipeline (§20 forms — per-100,000 units)
+// ---------------------------------------------------------------------------
+
+function applyDmlMods(
+  hex: string,
+  mods: readonly DrawingMlColorMod[],
+): string {
+  let rgb = parseHexToRgbDml(hex);
+  for (const mod of mods) {
+    const frac = mod.value / DML_UNIT;
+    switch (mod.kind) {
+      case "lumMod": {
+        const hsl = rgbToHsl(rgb);
+        rgb = hslToRgb({ ...hsl, l: clamp01(hsl.l * frac) });
+        break;
+      }
+      case "lumOff": {
+        const hsl = rgbToHsl(rgb);
+        rgb = hslToRgb({ ...hsl, l: clamp01(hsl.l + frac) });
+        break;
+      }
+      case "satMod": {
+        const hsl = rgbToHsl(rgb);
+        rgb = hslToRgb({ ...hsl, s: clamp01(hsl.s * frac) });
+        break;
+      }
+      case "hueMod": {
+        const hsl = rgbToHsl(rgb);
+        // Multiplicative scale per LO color.cxx, not additive rotation
+        rgb = hslToRgb({ ...hsl, h: ((hsl.h * frac) % 360 + 360) % 360 });
+        break;
+      }
+      case "shade": {
+        // §20.1.2.3.31: sRGB space (NOT HSL) — multiply channels toward black
+        rgb = {
+          r: clamp255(rgb.r * frac),
+          g: clamp255(rgb.g * frac),
+          b: clamp255(rgb.b * frac),
+        };
+        break;
+      }
+      case "tint": {
+        // §20.1.2.3.34: sRGB space — C' = C * frac + 255 * (1 - frac)
+        const inv = 1 - frac;
+        rgb = {
+          r: clamp255(rgb.r * frac + 255 * inv),
+          g: clamp255(rgb.g * frac + 255 * inv),
+          b: clamp255(rgb.b * frac + 255 * inv),
+        };
+        break;
+      }
+      case "alpha":
+        break; // opacity not reflected in sRGB output
+    }
+  }
+  return formatDmlHex(rgb);
+}
+
+function parseHexToRgbDml(hex: string): { r: number; g: number; b: number } {
+  const n = Number.parseInt(hex.slice(1), 16);
+  return { r: (n >>> 16) & 0xff, g: (n >>> 8) & 0xff, b: n & 0xff };
+}
+
+function formatDmlHex(rgb: { r: number; g: number; b: number }): string {
+  const h2 = (n: number): string =>
+    Math.round(clamp255(n)).toString(16).padStart(2, "0").toUpperCase();
+  return `#${h2(rgb.r)}${h2(rgb.g)}${h2(rgb.b)}`;
+}
+
+function clamp01(x: number): number {
+  return x < 0 ? 0 : x > 1 ? 1 : x;
+}
+
+function clamp255(x: number): number {
+  return x < 0 ? 0 : x > 255 ? 255 : x;
+}
+
 function rgbToHsl(rgb: { r: number; g: number; b: number }): {
   h: number;
   s: number;

package/src/runtime/units.ts

@@ -0,0 +1,46 @@
+/**
+ * OOXML unit conversions used across the runtime + UI.
+ *
+ * Hoisted from per-file constants to deduplicate the magic numbers that
+ * appear in `pm-schema.ts`, `chart-model-store.ts`, `float-wrap-resolver.ts`,
+ * `shape-renderer.ts`, and several other call sites.  Renaming an alias
+ * here propagates everywhere; renaming a literal would not.
+ *
+ * Conventions:
+ *   - All EMU helpers assume 96 dpi (the default OOXML rendering DPI).
+ *   - Twip helpers assume 1440 twips per inch (OOXML standard).
+ *   - Rotation values use OOXML's 60 000ths of a degree (`a:xfrm a:rot`).
+ *   - Picture crop (`a:srcRect`) values use 1/1000 of a percent per edge.
+ */
+
+/** EMU (English Metric Units) per CSS pixel at 96 dpi. */
+export const EMU_PER_PX = 9525;
+
+/** OOXML rotation units per degree (`a:xfrm a:rot` = 60 000ths°). */
+export const ROTATION_UNITS_PER_DEGREE = 60000;
+
+/** OOXML picture-crop units per percent (`a:srcRect` uses 1/1000 of a percent). */
+export const SRCRECT_UNITS_PER_PERCENT = 1000;
+
+/** Twips per CSS pixel at 96 dpi (1440 twips/inch ÷ 96 px/inch = 15). */
+export const TWIPS_PER_PX = 15;
+
+/** Convert EMU → CSS pixels at 96 dpi. */
+export function emuToPx(emu: number): number {
+  return emu / EMU_PER_PX;
+}
+
+/** Convert OOXML rotation units → CSS degrees. */
+export function rotationToDeg(units: number): number {
+  return units / ROTATION_UNITS_PER_DEGREE;
+}
+
+/** Convert an `a:srcRect` edge value → CSS percent. */
+export function srcRectToPercent(units: number): number {
+  return units / SRCRECT_UNITS_PER_PERCENT;
+}
+
+/** Convert twips → CSS pixels at 96 dpi. */
+export function twipsToPx(twips: number): number {
+  return twips / TWIPS_PER_PX;
+}

package/src/runtime/view-state.ts

@@ -403,6 +403,14 @@ function deriveActiveObjectFrame(
     };
   }
 
+  if (segment.kind === "shape") {
+    return {
+      kind: "shape",
+      anchorPos: segment.from,
+      display: segment.anchor?.display === "floating" ? "floating" : "inline",
+    };
+  }
+
   const objectKind = inferOpaqueObjectKind(segment);
   if (!objectKind) {
     return null;
@@ -491,7 +499,7 @@ function normalizeZoomLevel(
 function findObjectSegmentAtPosition(
   segments: readonly SurfaceInlineSegment[],
   position: number,
-): Extract<SurfaceInlineSegment, { kind: "image" | "opaque_inline" }> | null {
+): Extract<SurfaceInlineSegment, { kind: "image" | "opaque_inline" | "shape" }> | null {
   for (const segment of segments) {
     if (!isObjectLikeSegment(segment)) {
       continue;
@@ -505,10 +513,13 @@ function findObjectSegmentAtPosition(
 
 function isObjectLikeSegment(
   segment: SurfaceInlineSegment,
-): segment is Extract<SurfaceInlineSegment, { kind: "image" | "opaque_inline" }> {
+): segment is Extract<SurfaceInlineSegment, { kind: "image" | "opaque_inline" | "shape" }> {
   if (segment.kind === "image") {
     return true;
   }
+  if (segment.kind === "shape") {
+    return true;
+  }
   if (segment.kind !== "opaque_inline") {
     return false;
   }