ooxml-ui 0.30.0 → 0.31.0

package/dist/pptx/render/visual-3d-extrusion.d.ts

@@ -0,0 +1,66 @@
+/**
+ * CSS 3D extrusion side-panel data (framework-agnostic).
+ *
+ * Generates the geometry/CSS for rendering real depth on an extruded shape by
+ * positioning panel `<div>`s along its sides in 3D space, plus a `translateZ`
+ * for the front face and a camera-aware material overlay gradient. Moved here
+ * from React's `shape-visual-3d.ts` (`build3DExtrusionData`) so every binding
+ * shares the math; the style objects use a framework-neutral CSS map
+ * ({@link Extrusion3dCss}) instead of `React.CSSProperties`, which each binding
+ * casts to its own style type.
+ *
+ * @module render/visual-3d-extrusion
+ */
+import type { Scene3dParams } from './visual-3d-camera.js';
+/** Shape 3D extrusion/material parameters consumed by the panel builder. */
+export interface Shape3dExtrusionParams {
+    extrusionHeight?: number;
+    extrusionColor?: string;
+    presetMaterial?: string;
+}
+/**
+ * Framework-neutral CSS style object  -  a plain string/number map. Bindings cast
+ * it to their own style type (`React.CSSProperties`, Vue `CSSProperties`, …).
+ */
+export type Extrusion3dCss = Record<string, string | number>;
+/**
+ * Describes one side face (panel) of a CSS 3D extrusion.
+ * Each panel is a div positioned using CSS 3D transforms to form
+ * the sides of the extruded shape.
+ */
+export interface ExtrusionPanel {
+    /** Which side of the shape this panel represents. */
+    side: 'top' | 'bottom' | 'left' | 'right';
+    /** CSS styles for the panel (transform, width, height, background, etc.). */
+    style: Extrusion3dCss;
+}
+/** Complete data for rendering a CSS 3D extrusion effect. */
+export interface Extrusion3DData {
+    /** Whether extrusion should be rendered (has depth and is valid). */
+    hasExtrusion: boolean;
+    /** Styles to apply to the outer wrapper that establishes the 3D context. */
+    wrapperStyle: Extrusion3dCss;
+    /** Styles to apply to the front face (the original shape content). */
+    frontFaceStyle: Extrusion3dCss;
+    /** Side panels that form the extrusion depth. */
+    panels: ExtrusionPanel[];
+    /** Material gradient overlay for front face (CSS backgroundImage). */
+    materialOverlay?: string;
+}
+/**
+ * Build complete 3D extrusion data for rendering side face panels.
+ *
+ * This generates CSS 3D transform data that creates real depth by positioning
+ * div elements along the sides of the shape in 3D space. The front face is
+ * translated forward by half the extrusion depth, and side panels connect
+ * the front face to the back face.
+ *
+ * @param shape3d - Shape 3D extrusion/bevel properties.
+ * @param scene3d - Scene camera/lighting properties.
+ * @param fillColor - The resolved fill colour of the shape (hex string).
+ * @param elementWidth - Width of the shape element in pixels.
+ * @param elementHeight - Height of the shape element in pixels.
+ * @returns Extrusion data including wrapper styles, front face styles, and panels.
+ */
+export declare function build3DExtrusionData(shape3d: Shape3dExtrusionParams | undefined, scene3d: Scene3dParams | undefined, fillColor: string | undefined, elementWidth: number, elementHeight: number): Extrusion3DData;
+//# sourceMappingURL=visual-3d-extrusion.d.ts.map

package/dist/pptx/render/visual-3d-extrusion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visual-3d-extrusion.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/visual-3d-extrusion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAaxD,4EAA4E;AAC5E,MAAM,WAAW,sBAAsB;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;AAE7D;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B,qDAAqD;IACrD,IAAI,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;IAC1C,6EAA6E;IAC7E,KAAK,EAAE,cAAc,CAAC;CACtB;AAED,6DAA6D;AAC7D,MAAM,WAAW,eAAe;IAC/B,qEAAqE;IACrE,YAAY,EAAE,OAAO,CAAC;IACtB,4EAA4E;IAC5E,YAAY,EAAE,cAAc,CAAC;IAC7B,sEAAsE;IACtE,cAAc,EAAE,cAAc,CAAC;IAC/B,iDAAiD;IACjD,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,sEAAsE;IACtE,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CACnC,OAAO,EAAE,sBAAsB,GAAG,SAAS,EAC3C,OAAO,EAAE,aAAa,GAAG,SAAS,EAClC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,GACnB,eAAe,CAiJjB"}

package/dist/pptx/render/visual-3d-materials.d.ts

@@ -0,0 +1,55 @@
+/**
+ * CSS approximation of OOXML 3D material presets (framework-agnostic).
+ *
+ * Since a DOM-based renderer cannot use Three.js, material properties
+ * (roughness, metalness, transparency) are approximated with CSS filters,
+ * box-shadow variations, opacity and gradient overlays. Moved here verbatim
+ * from React's `material-presets.ts` so every binding shares one source of
+ * truth; the React/Vue/Angular layers re-export these.
+ *
+ * Each material maps to:
+ * - `filter`: brightness, contrast, saturate, sepia adjustments
+ * - `boxShadow`: inset specular highlight simulation
+ * - `opacity`: transparency for translucent materials
+ * - `backgroundImage`: gradient overlay for specular/environment reflections
+ * - `mixBlendMode`: optional blend mode token for the fill overlay
+ *
+ * @module render/visual-3d-materials
+ */
+import type { MaterialPresetType } from 'ooxml-core/pptx';
+/** CSS overrides that approximate an OOXML 3D material preset. */
+export interface MaterialCssOverrides {
+    /** Extra CSS filter chain to append (e.g. "brightness(1.1) saturate(1.2)"). */
+    filter?: string;
+    /** Opacity override (0–1). */
+    opacity?: number;
+    /** Extra box-shadow to layer for specular highlight simulation. */
+    boxShadow?: string;
+    /**
+     * Blend mode for fill overlay. Framework-neutral string token (e.g.
+     * "normal", "multiply"); bindings cast it to their own CSS type.
+     */
+    mixBlendMode?: string;
+    /** Gradient overlay for specular/environment simulation. */
+    backgroundImage?: string;
+}
+/**
+ * Returns CSS overrides that approximate the given OOXML 3D material preset.
+ * Returns an empty object for `undefined` or unrecognised values.
+ */
+export declare function getMaterialCssOverrides(material: MaterialPresetType | undefined): MaterialCssOverrides;
+/**
+ * Compute the lighting angle in CSS degrees based on camera rotation.
+ * When the camera rotates right (rotateY < 0), the specular highlight
+ * should shift left to remain consistent with the viewer's perspective.
+ * Returns a gradient angle in CSS degrees (0 = upward, 90 = rightward).
+ */
+export declare function getLightAngleFromCamera(rotateX: number, rotateY: number): number;
+/**
+ * Map camera rotation to a gradient overlay for material simulation on the
+ * front face of an extruded shape. The gradient direction adapts to the camera
+ * rotation so the specular highlight appears to track the light source relative
+ * to the viewer. Returns `undefined` for materials without a directional overlay.
+ */
+export declare function getMaterialGradientOverlay(material: string | undefined, rotateX: number, rotateY: number): string | undefined;
+//# sourceMappingURL=visual-3d-materials.d.ts.map

package/dist/pptx/render/visual-3d-materials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visual-3d-materials.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/visual-3d-materials.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE1D,kEAAkE;AAClE,MAAM,WAAW,oBAAoB;IACpC,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB;AAoGD;;;GAGG;AACH,wBAAgB,uBAAuB,CACtC,QAAQ,EAAE,kBAAkB,GAAG,SAAS,GACtC,oBAAoB,CAKtB;AAID;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAShF;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACzC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACb,MAAM,GAAG,SAAS,CAkCpB"}

package/dist/pptx/render/visual-3d-panel-depth-skew-map.d.ts

@@ -0,0 +1,107 @@
+/**
+ * COM-measured extrusion panel depth-skew data, split out of
+ * `visual-3d-panel-quad` to keep that file under the repo's LOC guideline.
+ * See that module's doc comment for how the measurement itself works
+ * (edge-band ink fit against a `Slide.Export` render); this file only holds
+ * the resulting table and its lookup.
+ *
+ * @module render/visual-3d-panel-depth-skew-map
+ */
+/**
+ * A panel's measured "depth direction": the screen-space vector (in
+ * fractions of a px, per px of rendered extrusion depth) that the BACK edge
+ * of a panel is offset from the front edge it shares with the front face.
+ * Multiply both components by the actual rendered depth (px) to get the
+ * real per-corner screen offset.
+ */
+export interface PanelDepthSkew {
+    dx: number;
+    dy: number;
+}
+/**
+ * A `PANEL_DEPTH_SKEW_MAP` entry: a default vector (used when the caller
+ * doesn't ask for a specific side, or when the requested side has no
+ * dedicated measurement) plus optional per-side overrides. Single-panel
+ * presets carry only the default; two-panel presets (the `oblique*` family
+ * and a handful of `isometric*`/`perspective*` siblings) carry a `top`/
+ * `bottom`/`left`/`right` override for each side that was independently
+ * measured, because the two panels of one preset are not always skewed by
+ * the same vector (see the module doc comment).
+ */
+export interface PanelDepthSkewEntry extends PanelDepthSkew {
+    top?: PanelDepthSkew;
+    bottom?: PanelDepthSkew;
+    left?: PanelDepthSkew;
+    right?: PanelDepthSkew;
+}
+/**
+ * COM-measured panel depth-skew vectors, keyed by camera preset. Only
+ * presets with real ground truth are listed; see `visual-3d-panel-quad`'s
+ * module doc comment for the measurement method. Extend this table (rather
+ * than guessing a formula) when a new preset is COM-verified, matching
+ * `CAMERA_HOMOGRAPHY_MAP`'s own "measured, not derived" convention.
+ *
+ * Extended 2026-09 from an initial 8-preset pass to full coverage of every
+ * preset with visible extrusion ink (37 of the 44 camera configurations
+ * tested: the 35 `CAMERA_HOMOGRAPHY_MAP` keys plus the 9 `oblique*`
+ * compass-direction representatives standing in for `oblique*`/
+ * `legacyOblique*`/`legacyPerspective*` alike). Measurement moved from a
+ * global convex-hull fit of the whole green blob (which produces a garbage
+ * quadrilateral whenever two adjacent panels merge into one non-convex
+ * connected component at a shared corner, e.g. `obliqueTopLeft`'s top and
+ * left panels touch pixel-wise at the shape's own top-left corner) to an
+ * EDGE-BAND fit: green ink is isolated by its position along each candidate
+ * side's OWN front edge (keeping only the middle 30% of the edge, far enough
+ * from both corners that an adjacent side's panel - which only ever touches
+ * this edge's line near a corner - cannot reach in), then the farthest ink
+ * from that edge's line (no radius cap) gives an exact per-side skew sample
+ * with no risk of grabbing the wrong side's geometry. Three sub-bands are
+ * cross-checked per side; every entry below measured under 1px disagreement
+ * between them unless the preset also shows a second side (see below).
+ *
+ * Two presets have no entry despite showing ink at this depth:
+ * `perspectiveHeroicExtremeLeftFacing`/`obliqueRight`/`obliqueLeft`/
+ * `perspectiveLeft`/`perspectiveRight`/`perspectiveFront`/`orthographicFront`
+ * measured ZERO visible ink (no panel to correct); every OTHER tested preset
+ * that showed ink has an entry.
+ *
+ * A preset with 2 simultaneously-visible panels (e.g. `obliqueTopLeft`'s
+ * top+left, `isometricRightUp`'s top+left) was measured with each side's OWN
+ * independent skew. Each such entry's `top`/`bottom`/`left`/`right` fields
+ * carry that per-side vector; `getMeasuredPanelDepthSkew` returns the
+ * side-specific vector when one exists, falling back to the entry's default
+ * `dx`/`dy` (the average of the sides that WERE measured, for a shape that
+ * somehow shows a side the ground truth never observed). This matters most
+ * for the `oblique*` family, whose two panels turned out to be
+ * independently, axis-aligned skewed: `obliqueTopLeft`'s own top-panel ink
+ * measured a purely VERTICAL offset and its left-panel ink a purely
+ * HORIZONTAL one, not one shared diagonal vector, so a single averaged
+ * vector put both panels' back edges tens of screen px off at a typical
+ * extrusion depth (see `visual-3d-panel-quad.test.ts`'s residual-error
+ * assertions). For the `isometric*`/`perspective*` families (real, if
+ * orthographic, 3D rotations) a single shared vector is also the physically
+ * correct model, and the two sides' independent measurements typically
+ * agreed closely (e.g. `isometricBottomDown`'s left-panel reading matched
+ * its `isometricBottomUp` sibling's independently-measured left-panel skew
+ * to within 0.1%); those entries still carry the per-side overrides for
+ * exactness, they just barely move the result.
+ *
+ * `isometricTopUp` previously had no entry: COM measurement found its real
+ * extrusion ink matches the box's `right` (local u=1) edge corners, not the
+ * `bottom` edge the SHIPPED `MEASURED_ISOMETRIC_PANEL_SIDES.isometricTopUp`
+ * used to resolve it to (a coarser "count green pixels in the band below/
+ * right of the front bbox" classifier mislabelled this steeply-rotated
+ * diagonal panel). That visibility table has been corrected alongside this
+ * one (now resolves `isometricTopUp` to `right`), so its measured skew is
+ * listed here too.
+ */
+export declare const PANEL_DEPTH_SKEW_MAP: Record<string, PanelDepthSkewEntry>;
+/**
+ * Look up the measured depth skew for a preset, or `undefined` when
+ * unmeasured. Pass `side` to get that side's own measured vector when the
+ * preset has one (see `PanelDepthSkewEntry`); omitted, or when the requested
+ * side has no dedicated measurement, falls back to the entry's default
+ * `dx`/`dy`.
+ */
+export declare function getMeasuredPanelDepthSkew(preset: string | undefined, side?: 'top' | 'bottom' | 'left' | 'right'): PanelDepthSkew | undefined;
+//# sourceMappingURL=visual-3d-panel-depth-skew-map.d.ts.map

package/dist/pptx/render/visual-3d-panel-depth-skew-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visual-3d-panel-depth-skew-map.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/visual-3d-panel-depth-skew-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;CACX;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAoB,SAAQ,cAAc;IAC1D,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,KAAK,CAAC,EAAE,cAAc,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CA8EpE,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACxC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,IAAI,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GACxC,cAAc,GAAG,SAAS,CAU5B"}

package/dist/pptx/render/visual-3d-panel-quad.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Extruded-box side-panel QUADRILATERAL for a homography-resolved camera
+ * (framework-agnostic).
+ *
+ * `visual-3d-extrusion`'s panels used to share the front face's own
+ * `matrix3d` and fold themselves into position with a local `rotateX`/
+ * `rotateY(+/-90deg)` plus `translateZ`. That composition is exact for a real
+ * CSS 3D `perspective` camera (see `visual-3d-camera`'s non-homography
+ * branch), but is DEGENERATE for a homography-resolved camera: a COM-measured
+ * unit-square homography (`visual-3d-camera-homography`) is a flat 2D
+ * projective map whose CSS `matrix3d` embedding has an IDENTITY z-row (see
+ * that module's doc comment), so it never feeds a point's z-coordinate into
+ * the projective divide. A rigid local rotation moves the panel's "front" and
+ * "back" edges apart only in z (their x/y stay identical before the
+ * homography is applied), so both edges land on the exact SAME screen line
+ * after the homography runs: the panel collapses to a zero-width sliver.
+ * Verified 2026-09 by rendering the actual `build3DExtrusionData` output in a
+ * real browser (Playwright, corner-marker `getBoundingClientRect`) for every
+ * `isometric*`/`perspective*`/`oblique*` preset tested: the panel's front-edge
+ * and back-edge markers landed on IDENTICAL pixels every time.
+ *
+ * This module replaces that composition with an EXPLICIT quadrilateral: the
+ * front edge is the exact image of the shape's own unit-square edge under the
+ * SAME homography the front face already uses (so it is pixel-identical to
+ * the front face's boundary by construction, never "close"), and the back
+ * edge is that same edge offset by a COM-measured 2D screen-space direction
+ * vector, scaled by the actual rendered extrusion depth. The panel is then a
+ * flat, untransformed `clip-path: polygon(...)` cut from a div sized to the
+ * quad's own bounding box: exact, and framework-agnostic (every binding
+ * already passes `ExtrusionPanel.style` through generically, so a new
+ * `clipPath`/`left`/`top` reaches all five with no per-binding change).
+ *
+ * Ground-truthed 2026-09 (COM `Slide.Export`, 300dpi, a 2in square extruded
+ * 36pt, front face red / `extrusionClr` green, convex-hull corner fit of the
+ * green ink): the measured back-edge offset, expressed as a fraction of the
+ * rendered extrusion depth (dimensionless: screen px moved per px of depth,
+ * so the same ratio applies at any element size or DPI), for the families
+ * this module covers. Presets with no ground truth here fall back to the
+ * pre-existing (degenerate) composition in `visual-3d-extrusion` rather than
+ * guessing an unmeasured skew: see that module's call site.
+ *
+ * @module render/visual-3d-panel-quad
+ */
+import type { Homography3 } from './visual-3d-camera-homography.js';
+import type { PanelDepthSkew } from './visual-3d-panel-depth-skew-map.js';
+export { PANEL_DEPTH_SKEW_MAP, getMeasuredPanelDepthSkew, type PanelDepthSkewEntry, type PanelDepthSkew, } from './visual-3d-panel-depth-skew-map.js';
+/** A single 2D point, in element-local CSS px (0,0 = the shape's own un-rotated top-left). */
+export interface Point2D {
+    x: number;
+    y: number;
+}
+/**
+ * Apply a unit-square homography to a single point `(u, v)` (both typically
+ * in `[0, 1]`, the shape's own local fraction), returning its projected
+ * position in the element's actual `width x height` CSS-px box. Pure
+ * evaluation (no CSS string involved), so it can be reused for both the
+ * front-face corners AND, offset by a depth skew, the back-face corners.
+ */
+export declare function projectHomographyPoint(h: Homography3, u: number, v: number, width: number, height: number): Point2D;
+/** An explicit, flat quadrilateral for one extrusion side panel. */
+export interface PanelQuadGeometry {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+    /** CSS `clip-path` polygon, in px relative to `(left, top)`. */
+    clipPath: string;
+}
+/**
+ * Compute a homography-resolved panel's exact projected quadrilateral: the
+ * front edge (the image of the shape's own shared edge under `h`, identical
+ * to the front face's own boundary) joined to that same edge offset by
+ * `skew * depthPx` (see the module doc comment). Returns a flat bounding box
+ * + `clip-path` polygon; the caller applies NO further transform.
+ */
+export declare function computeHomographyPanelQuad(h: Homography3, side: 'top' | 'bottom' | 'left' | 'right', width: number, height: number, depthPx: number, skew: PanelDepthSkew): PanelQuadGeometry;
+//# sourceMappingURL=visual-3d-panel-quad.d.ts.map

package/dist/pptx/render/visual-3d-panel-quad.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visual-3d-panel-quad.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/visual-3d-panel-quad.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAKvE,OAAO,EACN,oBAAoB,EACpB,yBAAyB,EACzB,KAAK,mBAAmB,EACxB,KAAK,cAAc,GACnB,MAAM,kCAAkC,CAAC;AAE1C,8FAA8F;AAC9F,MAAM,WAAW,OAAO;IACvB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACV;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACrC,CAAC,EAAE,WAAW,EACd,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACZ,OAAO,CAOT;AAyBD,oEAAoE;AACpE,MAAM,WAAW,iBAAiB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACzC,CAAC,EAAE,WAAW,EACd,IAAI,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,EACzC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,cAAc,GAClB,iBAAiB,CAqBnB"}

package/dist/pptx/render/visual-3d-panel-sides-perspective.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Extruded-box panel-side visibility for the `perspective*` camera family,
+ * split out of `visual-3d-panel-sides.ts` to keep that file under the repo's
+ * LOC guideline.
+ *
+ * @module render/visual-3d-panel-sides-perspective
+ */
+import type { Homography3 } from './visual-3d-camera-homography.js';
+import type { PanelVisibility } from './visual-3d-panel-sides.js';
+/**
+ * Homography-derived GUESS at extruded-box panel visibility for the
+ * `perspective*` family: the visible panel is assumed to be the side whose
+ * outward normal faces the camera, read off the homography's own
+ * perspective/skew terms. `h31`/`h32` (the homography's perspective terms)
+ * are the PRIMARY signal; `h21`/`h12` (the skew terms) are a SECONDARY
+ * tie-break for near-zero `h31`/`h32` cases.
+ *
+ * SUPERSEDED for every currently-known `perspective*` preset by
+ * {@link MEASURED_PERSPECTIVE_PANEL_SIDES}: a full COM re-measurement
+ * (2026-09, all 15 presets, edge-band ink analysis; see that table's doc
+ * comment) found this formula wrong for 7 of the 15 - it reliably OVER-
+ * predicts an extra side for every `*LeftFacing` preset and both plain
+ * single-axis `perspectiveLeft`/`perspectiveRight` (predicts a horizontal
+ * panel that never renders, matching neither `perspectiveAbove` nor
+ * `perspectiveBelow`'s own vertical analogue, which DO render). This
+ * function is kept only as the last-resort fallback in
+ * `resolvePanelSides` for a hypothetical future `perspective*` preset with no
+ * measured entry yet; every preset that exists today is measured.
+ *
+ * Convention: a positive `h31`/`xTerm` means the LEFT edge is the one
+ * foreshortening less (nearer the camera) so the box's left panel is
+ * revealed; positive `h32`/`yTerm` reveals the TOP panel. Both axes share
+ * the same sign convention (matches `perspectiveAbove`/`perspectiveBelow`
+ * being the exact transpose of `perspectiveLeft`/`perspectiveRight`).
+ */
+export declare function panelSidesFromHomography(h: Homography3): PanelVisibility;
+/**
+ * COM-measured panel sides for the WHOLE `perspective*` family (15 presets),
+ * replacing {@link panelSidesFromHomography}'s formula for every preset that
+ * exists today (that function is kept only as a fallback for a hypothetical
+ * future preset with no entry here yet). Ground-truthed 2026-09 (COM
+ * `Slide.Export`, a 2in square extruded 36pt, front/extrusion faces in
+ * distinct colours, edge-band ink analysis, all 15 presets in one pass; see
+ * `visual-3d-panel-sides.ts`'s `MEASURED_ISOMETRIC_PANEL_SIDES` doc comment
+ * for the method).
+ *
+ * This table replaces an earlier 2-entry `PERSPECTIVE_MEASURED_EXCEPTIONS`
+ * hack (`HeroicExtremeLeftFacing`/`RightFacing` only): re-measurement found
+ * {@link panelSidesFromHomography} wrong for 5 MORE presets beyond those 2,
+ * so "measure the family that mostly works, except 2 hand-found exceptions"
+ * was no longer an honest description of the data. 7 of the 15 disagree with
+ * the formula:
+ *
+ * - `perspectiveLeft` and `perspectiveRight` (the plain single-axis pair)
+ *   both measure NO visible panel at all, unlike their vertical analogues
+ *   `perspectiveAbove`/`perspectiveBelow`, which DO show one: the formula's
+ *   `h31`/`xTerm` sign predicts a horizontal panel for both from a small but
+ *   nonzero perspective term, but real PowerPoint renders neither. This is
+ *   the discrepancy `visual-3d-panel-quad.ts` previously flagged for
+ *   `perspectiveLeft` alone as unresolved; `perspectiveRight` turns out to
+ *   have the exact same problem, so both are fixed together here.
+ * - Every `*LeftFacing` preset the formula predicts a SECOND side for
+ *   (`perspectiveAboveLeftFacing`, `ContrastingLeftFacing`,
+ *   `HeroicLeftFacing`) in fact shows only its primary side: the formula's
+ *   small-magnitude secondary-axis term is a real but sub-visible signal at
+ *   this depth, not an actually-rendered panel. Their `*RightFacing`
+ *   mirrors, and the vertical-only `Above`/`Below`/`Relaxed*`/
+ *   `HeroicRightFacing` presets, already matched the formula and are
+ *   unchanged.
+ */
+export declare const MEASURED_PERSPECTIVE_PANEL_SIDES: Record<string, PanelVisibility>;
+//# sourceMappingURL=visual-3d-panel-sides-perspective.d.ts.map

package/dist/pptx/render/visual-3d-panel-sides-perspective.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visual-3d-panel-sides-perspective.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/visual-3d-panel-sides-perspective.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAS/D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,WAAW,GAAG,eAAe,CAYxE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,gCAAgC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAwD5E,CAAC"}

package/dist/pptx/render/visual-3d-panel-sides.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Extruded-box panel-side visibility for a camera preset (framework-agnostic).
+ *
+ * Split out of `visual-3d-camera-homography.ts` to keep that file under the
+ * repo's LOC guideline; consumed by `visual-3d-camera`'s `getCameraTransform`
+ * and, transitively, `visual-3d-extrusion`'s `build3DExtrusionData`.
+ *
+ * @module render/visual-3d-panel-sides
+ */
+import type { Homography3 } from './visual-3d-camera-homography.js';
+import { MEASURED_PERSPECTIVE_PANEL_SIDES, panelSidesFromHomography } from './visual-3d-panel-sides-perspective.js';
+/** Which sides of an extruded box's side panels are visible on screen. */
+export interface PanelVisibility {
+    showTop: boolean;
+    showBottom: boolean;
+    showLeft: boolean;
+    showRight: boolean;
+}
+export { panelSidesFromHomography, MEASURED_PERSPECTIVE_PANEL_SIDES };
+/**
+ * COM-measured extruded-box panel sides for the `isometric*` family (20
+ * presets), which {@link panelSidesFromHomography} structurally CANNOT
+ * derive: every preset in this family shares an IDENTICAL front-face
+ * homography with at least one sibling (e.g. `isometricLeftUp` and
+ * `isometricRightUp` resolve to the exact same matrix; `isometricTopUp`,
+ * `isometricTopDown`, `isometricBottomUp` and `isometricBottomDown` all
+ * share one), because a flat, unextruded front face genuinely renders
+ * pixel-identical under both (only the box's unseen back/side geometry
+ * differs). No function of the homography alone can recover which of two
+ * siblings a name refers to, so this table is measured directly per preset
+ * name instead.
+ *
+ * Re-ground-truthed 2026-09 (COM `Slide.Export`, a 2in square extruded 36pt,
+ * front/extrusion faces in distinct colours, all 20 `isometric*` presets in
+ * one pass, edge-band ink analysis: each side's visible ink is isolated by
+ * position along its OWN front edge rather than a coarse "count green pixels
+ * in the band below/right of the front bbox" classifier, which the ORIGINAL
+ * 2026-09 pass used and which mislabelled several presets - see
+ * `PANEL_DEPTH_SKEW_MAP`'s doc comment for the corner-fit method this reuses).
+ * Two corrections the coarse classifier could not have caught:
+ *
+ * - `isometricTopUp` (and by extension every OTHER pure single-axis preset
+ *   this table lists as a *single* side) shows a genuinely diagonal panel
+ *   whose ink falls mostly in the "below front bbox" band even though it
+ *   structurally hangs off the box's `right` edge, not `bottom`: the
+ *   corner-fit method (which identifies a side by matching the panel's own
+ *   shared edge with the front face, not by counting pixels in a directional
+ *   band) reclassifies it to `right`. This was a previously-flagged, then
+ *   unresolved discrepancy (see `PANEL_DEPTH_SKEW_MAP`'s prior doc comment);
+ *   it is now fixed by construction, and `PANEL_DEPTH_SKEW_MAP.isometricTopUp`
+ *   carries the matching measured skew for the `right` edge it now resolves
+ *   to (a skew for `bottom` would have been actively wrong here).
+ * - Roughly half of this table's ORIGINAL single-`Left`/`Right`-paired-with-
+ *   `Top`/`Bottom` entries (`isometricLeftDown`, `RightUp`'s sibling
+ *   `LeftUp`, `RightDown`, and every plain `OffAxis{1,2,3,4}Left`/`Right`)
+ *   actually show only ONE panel, not two: the coarse band classifier's
+ *   "count pixels in the band beyond the front bbox" over-counted a second,
+ *   fainter panel that is not actually there (or belongs to the other
+ *   preset in a shared-homography pair). The edge-fit method confirms each
+ *   side independently against its own analytic front-edge corners, so a
+ *   phantom second side no longer survives.
+ */
+export declare const MEASURED_ISOMETRIC_PANEL_SIDES: Record<string, PanelVisibility>;
+/**
+ * COM-measured extruded-box panel sides for the `oblique*`/`legacyOblique*`/
+ * `legacyPerspective*`/`orthographicFront` family, keyed by the compass
+ * suffix shared across all 3 legacy families (`getObliqueDirectionSuffix`
+ * extracts it from the actual preset name). This family's front-face
+ * homography is the trivial IDENTITY for every member (see
+ * `IDENTITY_HOMOGRAPHY_PRESETS`), carrying no per-preset signal at all, so -
+ * exactly like the isometric family above - panel visibility must be
+ * measured rather than derived. Ground-truthed 2026-09 (COM `Slide.Export`,
+ * `oblique<Direction>` extruded 36pt, all 8 compass directions plus
+ * `orthographicFront`); `legacyOblique*`/`legacyPerspective*` are not
+ * independently re-measured but share `oblique*`'s exact `rotateX`/
+ * `rotateY` sign per direction word (only magnitude/`perspectiveRefPx`
+ * differs), so the same table is reused for all 3 families by direction
+ * name.
+ *
+ * Two directions (`Left`, `Right`) measured NO visible panel at all: a
+ * purely horizontal extrusion-direction camera in this legacy family, like
+ * the modern `perspectiveLeft`/`Right`, reveals no side panel PowerPoint
+ * considers worth rendering.
+ */
+export declare const OBLIQUE_DIRECTION_PANEL_SIDES: Record<string, PanelVisibility>;
+/**
+ * Resolve extruded-box panel visibility for a camera preset: the measured
+ * per-preset lookup for every family (isometric, perspective, oblique/legacy),
+ * otherwise the general homography-derived formula (kept only for a
+ * hypothetical future preset with no measured entry), otherwise `undefined`
+ * (an unrecognised preset, or an explicit `a:camera/a:rot` override in play:
+ * the caller falls back to its own rotateX/rotateY threshold heuristic in
+ * that case, unchanged).
+ */
+export declare function resolvePanelSides(preset: string | undefined, homography: Homography3 | undefined): PanelVisibility | undefined;
+/**
+ * Resolve which extrusion side panels a caller (`build3DExtrusionData`)
+ * should actually render, combining {@link resolvePanelSides}'s
+ * preset-specific ground truth with two fallbacks: the legacy rotateX/
+ * rotateY threshold heuristic when there is no preset-specific ground truth
+ * at all (no scene3d, an explicit `a:camera/a:rot` override, or an
+ * unrecognised preset), and a deliberate "show all four" depth-perception
+ * default for a genuinely face-on view (no preset, or one COM-measured to
+ * reveal no panel at all, e.g. `perspectiveFront`/`orthographicFront`) -
+ * an extrusion with literally no visible side reads as broken, not
+ * flat-on, in the UI.
+ */
+export declare function resolveExtrusionPanelVisibility(panelSides: PanelVisibility | undefined, rotateX: number, rotateY: number): PanelVisibility;
+//# sourceMappingURL=visual-3d-panel-sides.d.ts.map

package/dist/pptx/render/visual-3d-panel-sides.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visual-3d-panel-sides.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/visual-3d-panel-sides.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EACN,gCAAgC,EAChC,wBAAwB,EACxB,MAAM,qCAAqC,CAAC;AAE7C,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;CACnB;AASD,OAAO,EAAE,wBAAwB,EAAE,gCAAgC,EAAE,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,eAAO,MAAM,8BAA8B,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAqB1E,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,6BAA6B,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAUzE,CAAC;AAoBF;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAChC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,UAAU,EAAE,WAAW,GAAG,SAAS,GACjC,eAAe,GAAG,SAAS,CAoB7B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,+BAA+B,CAC9C,UAAU,EAAE,eAAe,GAAG,SAAS,EACvC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACb,eAAe,CAejB"}