@beyondwork/docx-react-component 1.0.56 → 1.0.58

package/src/ui-tailwind/editor-surface/pm-schema.ts

@@ -5,6 +5,17 @@ import {
   tableCellNodeSpec,
   tableHeaderCellNodeSpec,
 } from "../../runtime/table-schema.ts";
+import {
+  isSupportedShapeGeometry,
+  renderShapeSvg,
+  type ShapeFill,
+  type ShapeLine,
+} from "./shape-renderer.ts";
+import {
+  EMU_PER_PX,
+  ROTATION_UNITS_PER_DEGREE,
+  SRCRECT_UNITS_PER_PERCENT,
+} from "../../runtime/units.ts";
 
 const HEX_COLOR_RE = /^[0-9A-Fa-f]{3,8}$/;
 const SAFE_FONT_RE = /^[A-Za-z0-9 ,\-'"]+$/;
@@ -442,6 +453,22 @@ export const editorSchema = new Schema({
         src: { default: null },
         widthEmu: { default: null },
         heightEmu: { default: null },
+        // Lane 6d N11 — picture effects from `SurfacePictureEffects`.
+        // Defaults are no-effect (null/false) so legacy callers stay
+        // visually identical.  OOXML units: rotation = 60000ths of a
+        // degree; srcRect = 1/1000 of a percent.
+        rotation: { default: null },
+        flipH: { default: false },
+        flipV: { default: false },
+        srcRect: { default: null },
+        // Lane 6d N9 — float-wrap fields surfaced from `SurfaceDrawingAnchor`.
+        wrapMode: { default: null },
+        distMargins: { default: null },
+        positionH: { default: null },
+        // Lane 6d N11.b — CSS filter effects (soft-edge, outer shadow, glow).
+        softEdgeRadius: { default: null },
+        outerShadow: { default: null },
+        glow: { default: null },
       },
       toDOM(node) {
         const isMissing = node.attrs.state === "missing";
@@ -450,22 +477,94 @@ export const editorSchema = new Schema({
         const widthEmu = node.attrs.widthEmu as number | null;
         const heightEmu = node.attrs.heightEmu as number | null;
         if (!isMissing && src) {
-          const widthPx = widthEmu ? Math.max(24, Math.round(widthEmu / 9525)) : undefined;
-          const heightPx = heightEmu ? Math.max(24, Math.round(heightEmu / 9525)) : undefined;
+          const widthPx = widthEmu ? Math.max(24, Math.round(widthEmu / EMU_PER_PX)) : undefined;
+          const heightPx = heightEmu ? Math.max(24, Math.round(heightEmu / EMU_PER_PX)) : undefined;
+          // N11 picture effects → CSS transform + clip-path.
+          const rotation = node.attrs.rotation as number | null;
+          const flipH = Boolean(node.attrs.flipH);
+          const flipV = Boolean(node.attrs.flipV);
+          const srcRect = node.attrs.srcRect as
+            | { top: number; bottom: number; left: number; right: number }
+            | null;
+          const transformParts: string[] = [];
+          if (rotation && rotation !== 0) {
+            transformParts.push(`rotate(${(rotation / ROTATION_UNITS_PER_DEGREE).toFixed(3)}deg)`);
+          }
+          if (flipH) transformParts.push("scaleX(-1)");
+          if (flipV) transformParts.push("scaleY(-1)");
+          // OOXML srcRect uses 1/1000 of a percent (e.g. 5000 = 5%).
+          // CSS clip-path inset() uses literal percent.
+          const clipParts: string[] = [];
+          if (srcRect) {
+            clipParts.push(
+              `inset(${(srcRect.top / SRCRECT_UNITS_PER_PERCENT).toFixed(3)}% ${(srcRect.right / SRCRECT_UNITS_PER_PERCENT).toFixed(3)}% ${(srcRect.bottom / SRCRECT_UNITS_PER_PERCENT).toFixed(3)}% ${(srcRect.left / SRCRECT_UNITS_PER_PERCENT).toFixed(3)}%)`,
+            );
+          }
+          // N11.b filter effects → CSS filter on the img element.
+          const softEdgeRadius = node.attrs.softEdgeRadius as number | null;
+          const outerShadow = node.attrs.outerShadow as {
+            blurRad: number; dist: number; dir: number; color: string;
+          } | null;
+          const glow = node.attrs.glow as { radius: number; color: string } | null;
+          const filterParts: string[] = [];
+          if (softEdgeRadius) {
+            filterParts.push(`blur(${(softEdgeRadius / EMU_PER_PX).toFixed(2)}px)`);
+          }
+          if (glow) {
+            filterParts.push(`drop-shadow(0 0 ${(glow.radius / EMU_PER_PX).toFixed(2)}px #${glow.color})`);
+          }
+          if (outerShadow) {
+            const blurPx = (outerShadow.blurRad / EMU_PER_PX).toFixed(2);
+            const distPx = outerShadow.dist / EMU_PER_PX;
+            const dirRad = (outerShadow.dir / ROTATION_UNITS_PER_DEGREE) * (Math.PI / 180);
+            const dx = (distPx * Math.cos(dirRad)).toFixed(2);
+            const dy = (distPx * Math.sin(dirRad)).toFixed(2);
+            filterParts.push(`drop-shadow(${dx}px ${dy}px ${blurPx}px #${outerShadow.color})`);
+          }
+          // N9 float-wrap → CSS float + shape-outside on the wrapper span.
+          const wrapMode = node.attrs.wrapMode as string | null;
+          const positionH = node.attrs.positionH as { align?: string } | null;
+          const distMargins = node.attrs.distMargins as
+            | { top?: number; bottom?: number; left?: number; right?: number }
+            | null;
+          const wrapperStyleParts: string[] = [];
+          if (isFloating && wrapMode === "square") {
+            const floatSide = positionH?.align === "right" ? "right" : "left";
+            wrapperStyleParts.push(
+              `float:${floatSide}`,
+              "shape-outside:margin-box",
+            );
+          } else if (isFloating && wrapMode === "topAndBottom") {
+            wrapperStyleParts.push("clear:both", "display:block");
+          }
+          // distMargins from EMU → px on the wrapper.
+          if (isFloating && distMargins) {
+            const m = (v?: number) => (v ? Math.round(v / EMU_PER_PX) : 0);
+            wrapperStyleParts.push(
+              `margin:${m(distMargins.top)}px ${m(distMargins.right)}px ${m(distMargins.bottom)}px ${m(distMargins.left)}px`,
+            );
+          }
           const style = [
             "display:inline-block",
             "vertical-align:middle",
-            "margin:0 4px",
+            wrapperStyleParts.length === 0 ? "margin:0 4px" : "",
             widthPx ? `width:${widthPx}px` : "",
             heightPx ? `height:${heightPx}px` : "",
+            transformParts.length > 0 ? `transform:${transformParts.join(" ")}` : "",
+            clipParts.length > 0 ? `clip-path:${clipParts[0]}` : "",
+            filterParts.length > 0 ? `filter:${filterParts.join(" ")}` : "",
           ].filter(Boolean).join(";");
+          const wrapperStyle = wrapperStyleParts.join(";");
+          const wrapperAttrs: Record<string, string> = {
+            class: "inline-flex items-center rounded",
+            "data-node-type": "image",
+            title: (node.attrs.detail as string) ?? (node.attrs.altText as string) ?? "Image",
+          };
+          if (wrapMode) wrapperAttrs["data-wrap-mode"] = wrapMode;
+          if (wrapperStyle) wrapperAttrs.style = wrapperStyle;
           return [
             "span",
-            {
-              class: "inline-flex items-center rounded",
-              "data-node-type": "image",
-              title: (node.attrs.detail as string) ?? (node.attrs.altText as string) ?? "Image",
-            },
+            wrapperAttrs,
             [
               "img",
               {
@@ -774,19 +873,123 @@ export const editorSchema = new Schema({
         text: { default: null },
         geometry: { default: null },
         detail: { default: null },
+        // V2c.5 additions — populated when the segment originates from a
+        // canonical `DrawingFrameNode` with `content.type === "shape"`.
+        // Legacy debug-mode opaque-preview consumers leave these at their
+        // defaults so the original toDOM output is unchanged.
+        label: { default: null },
+        fill: { default: null },
+        line: { default: null },
+        isTextBox: { default: false },
+        txbxText: { default: null },
+        wrapMode: { default: "none" },
+        display: { default: "inline" },
+        widthEmu: { default: null },
+        heightEmu: { default: null },
       },
       toDOM(node) {
+        // V2c.5: when the rich attrs are present (DrawingFrame source),
+        // render either an SVG (N10 supported geometries) or a chip
+        // fallback with shape-aware data attributes.  Otherwise fall back
+        // to the legacy opaque-preview chip so existing harness debug
+        // previews stay visually identical.
+        const isV2c5 = node.attrs.label !== null || node.attrs.isTextBox === true;
+        if (isV2c5) {
+          const geometry = node.attrs.geometry as string | null;
+          const fill = node.attrs.fill as
+            | ShapeFill
+            | {
+                kind: "gradient";
+                stops: Array<{ pos: number; color: string; colorType: "srgbClr" | "schemeClr" }>;
+                direction:
+                  | { kind: "linear"; angle: number; scaled?: boolean }
+                  | { kind: "path"; path: "circle" | "rect" | "shape" };
+                rotWithShape?: boolean;
+              }
+            | {
+                kind: "pattern";
+                preset: string;
+                fg?: { color: string; colorType: "srgbClr" | "schemeClr" };
+                bg?: { color: string; colorType: "srgbClr" | "schemeClr" };
+              }
+            | null;
+          const widthEmu = node.attrs.widthEmu as number | null;
+          const heightEmu = node.attrs.heightEmu as number | null;
+          const widthPx = widthEmu ? Math.max(8, Math.round(widthEmu / EMU_PER_PX)) : null;
+          const heightPx = heightEmu ? Math.max(8, Math.round(heightEmu / EMU_PER_PX)) : null;
+          const svgFill =
+            fill === undefined || fill === null
+              ? undefined
+              : fill.kind === "solid" || fill.kind === "none"
+                ? fill
+                : undefined;
+          // N10 — try SVG render path for supported geometries with extent.
+          if (
+            geometry &&
+            isSupportedShapeGeometry(geometry) &&
+            widthPx &&
+            heightPx &&
+            svgFill !== undefined
+          ) {
+            const svgSpec = renderShapeSvg(
+              {
+                geometry,
+                fill: svgFill,
+                line: node.attrs.line as ShapeLine | undefined,
+              },
+              widthPx,
+              heightPx,
+            );
+            if (svgSpec) {
+              return [
+                "span",
+                {
+                  class: "inline-block align-middle mx-0.5",
+                  style: `display:inline-block;width:${widthPx}px;height:${heightPx}px;vertical-align:middle`,
+                  "data-node-type": "shape",
+                  "data-shape-geometry": geometry,
+                  "data-shape-wrap": (node.attrs.wrapMode as string) ?? "none",
+                  contenteditable: "false",
+                  title: (node.attrs.detail as string) || (node.attrs.label as string) || "Shape",
+                },
+                svgSpec as unknown as readonly [string, Record<string, string>],
+              ];
+            }
+          }
+          // Chip fallback for unsupported geometry / missing extent.
+          const isTextBox = Boolean(node.attrs.isTextBox);
+          const txbxText = node.attrs.txbxText as string | null;
+          const display =
+            isTextBox && txbxText
+              ? `\u25A1 ${txbxText}`
+              : isTextBox
+                ? "\u25A1 Text box"
+                : "\u25C7 Shape";
+          return [
+            "span",
+            {
+              class:
+                "inline-flex items-center gap-1 mx-0.5 px-1.5 py-0.5 rounded text-xs border-none text-secondary bg-surface",
+              "data-node-type": "shape",
+              "data-shape-geometry": (node.attrs.geometry as string) ?? "",
+              "data-shape-wrap": (node.attrs.wrapMode as string) ?? "none",
+              contenteditable: "false",
+              title: (node.attrs.detail as string) || (node.attrs.label as string) || "Shape",
+            },
+            display,
+          ];
+        }
         const text = node.attrs.text as string | null;
-        const label = text ? `Shape: ${text}` : "Shape";
+        const legacyLabel = text ? `Shape: ${text}` : "Shape";
         return [
           "span",
           {
             class: "inline-flex items-center gap-1 mx-0.5 rounded border border-success/25 bg-success-soft px-1.5 py-0.5 text-xs text-success",
             "data-node-type": "shape_atom",
             contenteditable: "false",
-            title: (node.attrs.detail as string) ?? label,
+            title: (node.attrs.detail as string) ?? legacyLabel,
           },
-          "\u25A1 " + label,
+          "\u25A1 " + legacyLabel,
         ];
       },
     },

package/src/ui-tailwind/editor-surface/pm-state-from-snapshot.ts

@@ -453,8 +453,21 @@ function buildInlineContent(
           display: segment.display ?? "inline",
           detail: segment.detail ?? null,
           src: preview?.src ?? null,
-          widthEmu: preview?.widthEmu ?? null,
-          heightEmu: preview?.heightEmu ?? null,
+          widthEmu: preview?.widthEmu ?? preview?.widthEmu ?? segment.anchor?.extent.widthEmu ?? null,
+          heightEmu: preview?.heightEmu ?? segment.anchor?.extent.heightEmu ?? null,
+          // Lane 6d N11 — picture effects.
+          rotation: segment.pictureEffects?.rotation ?? null,
+          flipH: segment.pictureEffects?.flipH ?? false,
+          flipV: segment.pictureEffects?.flipV ?? false,
+          srcRect: segment.pictureEffects?.srcRect ?? null,
+          // Lane 6d N9 — float-wrap.
+          wrapMode: segment.anchor?.wrapMode ?? null,
+          distMargins: segment.anchor?.distMargins ?? null,
+          positionH: segment.anchor?.positionH ?? null,
+          // Lane 6d N11.b — filter effects.
+          softEdgeRadius: segment.pictureEffects?.softEdgeRadius ?? null,
+          outerShadow: segment.pictureEffects?.outerShadow ?? null,
+          glow: segment.pictureEffects?.glow ?? null,
         }),
       ];
       }
@@ -462,6 +475,23 @@ function buildInlineContent(
     case "opaque_inline":
       return [buildOpaqueInlineOrComplexAtom(segment, mediaPreviews, showUnsupportedObjectPreviews)];
 
+    case "shape":
+      return [
+        editorSchema.nodes.shape_atom.create({
+          label: segment.label,
+          detail: segment.detail,
+          geometry: segment.geometry ?? null,
+          fill: segment.fill ?? null,
+          line: segment.line ?? null,
+          isTextBox: segment.isTextBox ?? false,
+          txbxText: segment.txbxText ?? null,
+          wrapMode: segment.anchor?.wrapMode ?? "none",
+          display: segment.anchor?.display ?? "inline",
+          widthEmu: segment.anchor?.extent.widthEmu ?? null,
+          heightEmu: segment.anchor?.extent.heightEmu ?? null,
+        }),
+      ];
+
     case "note_ref": {
       const text = editorSchema.text(
         segment.label,

package/src/ui-tailwind/editor-surface/shape-renderer.ts

@@ -0,0 +1,206 @@
+/**
+ * Lane 6d — Slice N10 (P12.1 + P12.2): pure SVG shape renderer.
+ *
+ * Maps the V2c.5 `kind: "shape"` surface segment onto inline SVG markup
+ * for the most common geometries (rect / ellipse / roundRect).  Pure —
+ * no DOM access, no React; returns a plain markup string the toDOM can
+ * embed via attrs.  Returns `null` for unsupported geometries so the
+ * caller falls back to the existing chip render.
+ *
+ * v1 fill coverage: solid (srgbClr) → `#${hex}`; solid (schemeClr) →
+ * `currentColor` placeholder until Lane 6a theme resolver wires through;
+ * none → `none`.  Gradient + pattern fills are dropped at the surface
+ * boundary (V2c.5 surface only carries solid/none) — they remain on the
+ * canonical model for a future renderer extension.
+ *
+ * v1 line coverage: width = `widthEmu / 9525` px; color same handling as
+ * fill; `noLine: true` → `stroke: "none"`.
+ */
+
+import { EMU_PER_PX } from "../../runtime/units";
+
+const SUPPORTED_GEOMETRIES = new Set(["rect", "ellipse", "roundRect"]);
+
+export type ShapeFill =
+  | { kind: "solid"; color: string; colorType: "srgbClr" | "schemeClr" }
+  | { kind: "none" };
+
+export type ShapeLine = {
+  color?: string;
+  widthEmu?: number;
+  noLine?: boolean;
+};
+
+export interface ResolvedFillCss {
+  fill: string;
+  /** True when caller should warn about unresolved scheme color. */
+  isSchemePlaceholder: boolean;
+}
+
+export interface ResolvedLineCss {
+  stroke: string;
+  strokeWidth: number;
+}
+
+/**
+ * Resolve a shape fill into a CSS color string.  schemeClr falls back
+ * to `currentColor` until Lane 6a's theme resolver is wired here —
+ * `isSchemePlaceholder` flags the placeholder so callers (or follow-up
+ * slices) can later substitute the resolved theme color.
+ */
+export function resolveFillCss(fill: ShapeFill | undefined): ResolvedFillCss {
+  if (!fill || fill.kind === "none") {
+    return { fill: "none", isSchemePlaceholder: false };
+  }
+  if (fill.colorType === "schemeClr") {
+    return { fill: "currentColor", isSchemePlaceholder: true };
+  }
+  // srgbClr — color is uppercase hex without leading `#`.
+  return { fill: `#${fill.color}`, isSchemePlaceholder: false };
+}
+
+/**
+ * Resolve a shape line into stroke + stroke-width values.  `noLine: true`
+ * collapses to `stroke: "none"` per OOXML semantics.  Default stroke
+ * width is 1 px when widthEmu is absent or zero.
+ */
+export function resolveLineCss(line: ShapeLine | undefined): ResolvedLineCss {
+  if (!line || line.noLine) {
+    return { stroke: "none", strokeWidth: 0 };
+  }
+  // Default stroke (no widthEmu) matches the floor used when widthEmu
+  // is set — otherwise a `widthEmu: 0` shape would get a fatter stroke
+  // (1 px) than a `widthEmu: 1` shape (0.5 px from the Math.max floor).
+  const strokeWidth = line.widthEmu && line.widthEmu > 0
+    ? Math.max(0.5, line.widthEmu / EMU_PER_PX)
+    : 0.5;
+  // line.color uses OOXML hex without `#`; "auto" → currentColor.
+  const stroke = !line.color || line.color === "auto"
+    ? "currentColor"
+    : `#${line.color}`;
+  return { stroke, strokeWidth };
+}
+
+export interface ShapeSegmentLike {
+  geometry?: string;
+  fill?: ShapeFill;
+  line?: ShapeLine;
+}
+
+/**
+ * PM `DOMOutputSpec`-style array tree for an SVG element.  Each inner
+ * tuple is `[tag, attrs, ...children]`.  Used by ProseMirror's
+ * `toDOM` to construct DOM nodes without string parsing.
+ */
+export type SvgSpec = readonly [string, Record<string, string>, ...SvgSpec[]];
+
+/**
+ * Render a supported geometry into a PM-compatible DOMOutputSpec tree
+ * for an inline `<svg>`.  Returns `null` when the geometry is unsupported
+ * or the caller did not supply pixel dimensions (a chip-fallback signal).
+ *
+ * The SVG is sized 1:1 to its container; the wrapper span owns the
+ * outer `width:Xpx; height:Ypx`.
+ */
+export function renderShapeSvg(
+  segment: ShapeSegmentLike,
+  widthPx: number,
+  heightPx: number,
+): SvgSpec | null {
+  if (!widthPx || !heightPx) return null;
+  if (!segment.geometry || !SUPPORTED_GEOMETRIES.has(segment.geometry)) {
+    return null;
+  }
+  const fillCss = resolveFillCss(segment.fill);
+  const lineCss = resolveLineCss(segment.line);
+  const sw = lineCss.strokeWidth;
+  // Inset the geometry by half the stroke so the stroke paints inside
+  // the bounding box (browsers default to centered stroke).
+  const insetX = sw / 2;
+  const insetY = sw / 2;
+  const innerW = Math.max(0, widthPx - sw);
+  const innerH = Math.max(0, heightPx - sw);
+
+  let geometryEl: SvgSpec;
+  switch (segment.geometry) {
+    case "rect":
+      geometryEl = [
+        "rect",
+        {
+          x: String(insetX),
+          y: String(insetY),
+          width: String(innerW),
+          height: String(innerH),
+          fill: fillCss.fill,
+          stroke: lineCss.stroke,
+          "stroke-width": String(sw),
+        },
+      ];
+      break;
+    case "roundRect": {
+      // Default OOXML preset uses ~10% of the shorter side for corner radius.
+      const r = Math.min(innerW, innerH) * 0.1;
+      geometryEl = [
+        "rect",
+        {
+          x: String(insetX),
+          y: String(insetY),
+          width: String(innerW),
+          height: String(innerH),
+          rx: String(r),
+          ry: String(r),
+          fill: fillCss.fill,
+          stroke: lineCss.stroke,
+          "stroke-width": String(sw),
+        },
+      ];
+      break;
+    }
+    case "ellipse": {
+      const cx = widthPx / 2;
+      const cy = heightPx / 2;
+      const rx = Math.max(0, (widthPx - sw) / 2);
+      const ry = Math.max(0, (heightPx - sw) / 2);
+      geometryEl = [
+        "ellipse",
+        {
+          cx: String(cx),
+          cy: String(cy),
+          rx: String(rx),
+          ry: String(ry),
+          fill: fillCss.fill,
+          stroke: lineCss.stroke,
+          "stroke-width": String(sw),
+        },
+      ];
+      break;
+    }
+    default:
+      return null;
+  }
+
+  // PM's DOMSerializer parses the tag string for an SVG namespace prefix:
+  // "http://www.w3.org/2000/svg svg" → createElementNS().  Setting an
+  // `xmlns` *attribute* after createElement() is meaningless — the
+  // resulting node is HTMLUnknownElement and won't paint as SVG.
+  // Children inherit the namespace, so the geometry tag stays bare.
+  return [
+    "http://www.w3.org/2000/svg svg",
+    {
+      viewBox: `0 0 ${widthPx} ${heightPx}`,
+      width: String(widthPx),
+      height: String(heightPx),
+      preserveAspectRatio: "none",
+      "aria-hidden": "true",
+    },
+    geometryEl,
+  ];
+}
+
+/**
+ * Whether N10 v1 supports rendering this geometry as SVG.  Useful for
+ * caller-side branching when the chip fallback should fire.
+ */
+export function isSupportedShapeGeometry(geometry: string | undefined): boolean {
+  return geometry !== undefined && SUPPORTED_GEOMETRIES.has(geometry);
+}

package/src/ui-tailwind/editor-surface/surface-layer.ts

@@ -0,0 +1,66 @@
+/**
+ * R.4 SurfaceLayer — named shell for the outermost input surface layer.
+ * See `docs/plans/lane-1-editing-foundation.md` §R.4.
+ *
+ * Analogous to LibreOffice `SwWrtShell`. Owns: keyboard resolution, paste/drop
+ * routing decisions, composition state. Does NOT own: PM view construction,
+ * DOM manipulation, visible selection chrome — those stay in
+ * `pm-command-bridge.ts` as a thin plugin factory that forwards events here.
+ *
+ * The R.4 scope shipped in this first extraction is the TYPED RESULT SHAPE +
+ * a testable dispatch seam for the keyboard path. Tests can now exercise
+ * "Ctrl+F without React render" by calling `surfaceLayer.resolveKeyDown`
+ * directly — no PM boot, no DOM.
+ *
+ * Follow-up work (not in this slice): migrate `pm-command-bridge.ts`
+ * `handleKeyDown` / `handlePaste` / `handleDrop` to call into
+ * `surfaceLayer.dispatchPaste` / `surfaceLayer.dispatchDrop` so the bridge
+ * becomes a plugin factory with zero dispatch logic.
+ */
+
+import {
+  resolveSurfaceShortcut,
+  resolveShellShortcut,
+  type ShellShortcutContext,
+  type ShellShortcutResolution,
+  type ShortcutKeyInput,
+  type SurfaceShortcutContext,
+  type SurfaceShortcutResolution,
+} from "../../ui/runtime-shortcut-dispatch";
+
+export type SurfaceResult =
+  | { kind: "dispatched"; surface: SurfaceShortcutResolution }
+  | { kind: "shell"; shell: ShellShortcutResolution }
+  | { kind: "pass-through" };
+
+export interface SurfaceLayer {
+  /**
+   * Resolve a keydown event. Consults the shell-level dispatcher first
+   * (Ctrl+F / Ctrl+Shift+E / F5 etc.) and falls back to the surface-level
+   * dispatcher (typing, arrows, Tab). Returns a typed `SurfaceResult` so
+   * callers can switch on the kind without reaching into either
+   * dispatcher's specific resolution types.
+   */
+  resolveKeyDown(
+    input: ShortcutKeyInput,
+    shell: ShellShortcutContext,
+    surface: SurfaceShortcutContext,
+  ): SurfaceResult;
+}
+
+/**
+ * Default stateless SurfaceLayer instance. Safe to share across runtimes.
+ */
+export const surfaceLayer: SurfaceLayer = {
+  resolveKeyDown(input, shell, surface) {
+    const shellResolution = resolveShellShortcut(input, shell);
+    if (shellResolution.kind !== "none") {
+      return { kind: "shell", shell: shellResolution };
+    }
+    const surfaceResolution = resolveSurfaceShortcut(input, surface);
+    if (surfaceResolution.kind !== "none") {
+      return { kind: "dispatched", surface: surfaceResolution };
+    }
+    return { kind: "pass-through" };
+  },
+};

package/src/ui-tailwind/editor-surface/tw-inline-token.tsx

@@ -93,6 +93,35 @@ export function TwInlineToken(props: TwInlineTokenProps) {
     );
   }
 
+  // V2c.5 — shape segment (rect/ellipse/text-box/etc).  Lane 6d N10 will
+  // upgrade this to proper SVG/HTML shape rendering; for now we render a
+  // selectable chip so reviewers can see the shape exists in the doc.
+  if (segment.kind === "shape") {
+    const isTextBox = Boolean(segment.isTextBox);
+    const label = isTextBox && segment.txbxText ? segment.txbxText : segment.label;
+    return (
+      <button
+        type="button"
+        tabIndex={-1}
+        onMouseDown={(e) => {
+          e.preventDefault();
+          props.onSelectionChange?.(createSelectionSnapshot(segment.from, segment.to));
+        }}
+        className={`inline-flex items-center gap-1 mx-0.5 px-1.5 py-0.5 rounded text-xs border-none cursor-pointer ${commentClass} text-secondary bg-surface ${
+          selected ? "ring-1 ring-accent/30" : ""
+        } ${focusRingClass}`}
+        title={segment.detail || segment.label}
+        data-segment-kind="shape"
+        data-shape-geometry={segment.geometry ?? ""}
+      >
+        {renderTwCaret(selection, segment.from)}
+        <span>{isTextBox ? "□" : "◇"}</span>
+        {label}
+        {renderTwCaret(selection, segment.to)}
+      </button>
+    );
+  }
+
   // opaque_inline
   if (segment.kind === "opaque_inline") {
     if (segment.presentation === "quiet-marker") {

package/src/ui-tailwind/editor-surface/tw-segment-view.tsx

@@ -23,7 +23,13 @@ export function TwSegmentView(props: TwSegmentViewProps) {
   const { segment, selection, markupDisplay } = props;
 
   // Non-text segments delegate to TwInlineToken
-  if (segment.kind === "tab" || segment.kind === "hard_break" || segment.kind === "image" || segment.kind === "opaque_inline") {
+  if (
+    segment.kind === "tab" ||
+    segment.kind === "hard_break" ||
+    segment.kind === "image" ||
+    segment.kind === "opaque_inline" ||
+    segment.kind === "shape"
+  ) {
     return (
       <TwInlineToken
         segment={segment}