ooxml-ui 0.30.1 → 1.0.0

package/dist/pptx/render/visual-3d-camera-presets.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Legacy camera-preset -> rotateX/rotateY/rotateZ + perspective-distance
+ * table (framework-agnostic).
+ *
+ * Split out of `visual-3d-camera.ts` to keep that file under the repo's LOC
+ * guideline. As of the 2026-09 off-axis-camera homography wave (see
+ * `visual-3d-camera-homography`'s module doc comment), this table's angles
+ * are ONLY the actual rendered transform for a preset with no COM-measured
+ * homography, or when an explicit `a:camera/a:rot`/`@fov`/`@zoom` override is
+ * present; for every other preset it now serves solely as an extrusion
+ * panel-visibility/shading DIRECTION HINT (`visual-3d-camera`'s
+ * `cameraFlatFace` doc comment explains why a pure front-face measurement
+ * cannot always recover this, e.g. `isometricTopUp` vs `isometricBottomUp`).
+ *
+ * @module render/visual-3d-camera-presets
+ */
+/**
+ * Camera preset configuration: reference perspective distance (px, at
+ * `visual-3d-camera-fov`'s `REFERENCE_SIZE_PX`) and base rotation angles (in degrees). These
+ * approximate the OOXML camera preset positions.
+ */
+export interface CameraPresetConfig {
+    /** Reference CSS perspective distance in px at `visual-3d-camera-fov`'s `REFERENCE_SIZE_PX`, or `undefined` for a parallel (non-perspective) projection. */
+    perspectiveRefPx?: number;
+    rotateX: number;
+    rotateY: number;
+    rotateZ: number;
+    /** COM-calibrated `perspective-origin` (% of the element's box); only used on the explicit-override/no-homography fallback path. */
+    perspectiveOriginXPct?: number;
+    perspectiveOriginYPct?: number;
+}
+/**
+ * Reference perspective distance (px, at `visual-3d-camera-fov`'s `REFERENCE_SIZE_PX`) used for
+ * an explicit rotation with no camera preset at all. Matches the pre-existing
+ * flat `800px` fallback.
+ */
+export declare const DEFAULT_CUSTOM_REF_PX = 800;
+export declare const CAMERA_PRESET_MAP: Record<string, CameraPresetConfig>;
+//# sourceMappingURL=visual-3d-camera-presets.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"visual-3d-camera-presets.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/visual-3d-camera-presets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IAClC,4JAA4J;IAC5J,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,oIAAoI;IACpI,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAEzC,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAiGhE,CAAC"}

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

@@ -0,0 +1,154 @@
+/**
+ * Camera-preset → CSS perspective/rotation mapping (framework-agnostic).
+ *
+ * Resolves OOXML camera presets and explicit rotation angles into CSS
+ * `perspective` + `rotateX/Y/Z`. Shared by every binding's 3D layer.
+ *
+ * The perspective DISTANCE is derived geometrically from a camera field of
+ * view rather than an arbitrary pixel constant: for a FOV `f` projected onto
+ * an element of on-screen `size` pixels, the CSS `perspective` distance that
+ * reproduces that FOV is `d = (size / 2) / tan(f / 2)` (see
+ * {@link fovToPerspectivePx}). Each preset in
+ * {@link CAMERA_PRESET_MAP} instead stores the EQUIVALENT reference distance
+ * at `visual-3d-camera-fov`'s `REFERENCE_SIZE_PX` (the pre-existing hand-tuned pixel constants,
+ * kept as-is so behaviour at that reference size is unchanged); a per-preset
+ * FOV is derived from it once and then re-projected onto the actual element
+ * size, so a large shape gets proportionally less foreshortening than a small
+ * one for the "same" camera, matching how a real lens behaves. An explicit
+ * `a:camera/@fov` overrides the derived default outright, and `@zoom` narrows
+ * the effective FOV the way a telephoto lens flattens perspective when
+ * zooming in from a fixed position (see `visual-3d-camera-fov`'s
+ * `applyZoomToFov`). The FOV <-> perspective-distance math itself lives in
+ * that sibling module, split out to keep this file under the repo's LOC
+ * guideline.
+ *
+ * Ground-truthed against real PowerPoint (COM `Slide.Export` at 192dpi,
+ * 2026-09): a flat, unextruded square under `isometricLeftDown` /
+ * `isometricTopUp` renders as a true parallelogram, with opposite edges equal
+ * in length to within measurement noise (~0.7%): PARALLEL projection,
+ * no perspective divide at all. `orthographicFront` is unrotated and
+ * trivially parallel too. Only the `perspective*`/`oblique*`/`legacy*`
+ * families showed real keystoning (near/far edge length differing by several
+ * percent). {@link CAMERA_PRESET_MAP} reflects that: isometric/orthographic
+ * presets carry no `perspectiveRefPx`, so {@link getCameraTransform} never
+ * emits a `perspective` for them, regardless of element size or explicit fov.
+ *
+ * A second COM measurement (2026-09, a 4in/144dpi square, `SetPresetCamera` +
+ * `Depth = 0`, pixel-scanned bounding box + centroid) found every rotated
+ * `perspective*` preset projected OPPOSITE the direction the old
+ * `rotateX`/`rotateY` signs + a centred `perspective` predicted
+ * (`perspectiveLeft` measured screen-RIGHT). Negating both for the whole
+ * family (below) brings the single-axis presets within ~0.5% of measured
+ * (effectively exact) and roughly halves the error for the two-axis presets.
+ * A centred `perspective` alone cannot fully reproduce the two-axis presets'
+ * off-axis camera even with corrected signs (a `rotateX`/`rotateY`/distance
+ * grid search could not zero the residual for `perspectiveHeroicLeftFacing`
+ * or `perspectiveContrastingLeftFacing`: a genuine off-axis vanishing point,
+ * not a wrong angle). A COM-calibrated `perspective-origin`
+ * (`perspectiveOriginXPct`/`YPct` below) closes most of that gap for the
+ * `Contrasting*` and `HeroicExtreme*` presets; `Heroic(Left/Right)Facing`,
+ * `AboveLeftFacing`/`RightFacing` and `Relaxed*` found no stable
+ * non-boundary-hugging origin fit and keep the default centred origin.
+ *
+ * @module render/visual-3d-camera
+ */
+import type { ElementSizePx } from './visual-3d-camera-fov.js';
+import type { PanelVisibility } from './visual-3d-panel-sides.js';
+export type { ElementSizePx } from './visual-3d-camera-fov.js';
+export { getCameraHomography, homographyToMatrix3d, isIdentityHomography, IDENTITY_HOMOGRAPHY_PRESETS, CAMERA_HOMOGRAPHY_MAP, } from './visual-3d-camera-homography.js';
+export type { Homography3 } from './visual-3d-camera-homography.js';
+export { panelSidesFromHomography, resolvePanelSides, resolveExtrusionPanelVisibility, MEASURED_ISOMETRIC_PANEL_SIDES, OBLIQUE_DIRECTION_PANEL_SIDES, } from './visual-3d-panel-sides.js';
+export type { PanelVisibility } from './visual-3d-panel-sides.js';
+export { computeParametricCameraHomography, sixtyThousandthsDegToRad, } from './visual-3d-camera-parametric.js';
+export type { ParametricCameraParams } from './visual-3d-camera-parametric.js';
+/**
+ * Structural subset of `Pptx3DScene` consumed by the camera mapping. Declared
+ * locally (rather than importing `Pptx3DScene`) so the named React-compatible
+ * helpers accept the same shape; `Pptx3DScene` structurally satisfies it.
+ */
+export interface Scene3dParams {
+    cameraPreset?: string;
+    cameraRotX?: number;
+    cameraRotY?: number;
+    cameraRotZ?: number;
+    /** `a:camera/@fov`, in 1/60000 degrees. Overrides the preset's default FOV. */
+    cameraFieldOfView?: number;
+    /** `a:camera/@zoom`, a fraction where 1 = 100%. Narrows the effective FOV. */
+    cameraZoom?: number;
+    lightRigType?: string;
+    lightRigDirection?: string;
+    hasBackdrop?: boolean;
+    /** Backdrop plane normal vector (`a:backdrop/a:norm`), default (0, 1, 0): a flat floor. */
+    backdropNormalX?: number;
+    backdropNormalY?: number;
+    backdropNormalZ?: number;
+}
+/** Resolved camera transform produced by {@link getCameraTransform}. */
+export interface CameraTransform {
+    perspective?: string;
+    /** CSS `perspective-origin` (e.g. `"93% 0%"`); `undefined` means the default centred `50% 50%`. */
+    perspectiveOrigin?: string;
+    /**
+     * A COM-measured exact `matrix3d(...)` CSS transform (see
+     * `visual-3d-camera-homography`), when the preset has ground truth and no
+     * explicit `a:camera/a:rot` override is present. When set, this REPLACES
+     * `perspective`/`perspectiveOrigin`/`rotateX`/`rotateY`/`rotateZ` for the
+     * actual rendered transform (both are always 0 in that case) and MUST be
+     * paired with `transformOrigin: '0 0'`. `rotateX`/`rotateY` are still
+     * populated (from the legacy preset table) for callers that only need
+     * "which side is the camera on" (extrusion panel visibility/shading), not
+     * the exact transform; see {@link cameraFlatFace}.
+     */
+    matrix3d?: string;
+    /** `'0 0'` when {@link matrix3d} is set; `undefined` (default `50% 50%`) otherwise. */
+    transformOrigin?: string;
+    /**
+     * `true` when a COM-measured homography resolved the preset to an
+     * IDENTITY transform (the front face is flat; see
+     * `visual-3d-camera-homography`'s module doc comment for the
+     * `oblique*`/`legacyOblique*`/`legacyPerspective*`/`orthographicFront`
+     * families). `rotateX`/`rotateY` are still populated from the legacy
+     * hand-tuned table in this case, but ONLY as an extrusion
+     * panel-visibility/shading direction hint (which side of the box the
+     * camera implies you'd see) -- callers building the actual CSS transform
+     * MUST skip `rotateX`/`rotateY`/`rotateZ`/`perspective` entirely when this
+     * is `true`, the same way they already skip them when {@link matrix3d} is
+     * set.
+     */
+    cameraFlatFace?: boolean;
+    rotateX: number;
+    rotateY: number;
+    rotateZ: number;
+    /**
+     * COM-measured extruded-box panel visibility for this camera preset (see
+     * `visual-3d-panel-sides`), when one could be resolved. `undefined` means
+     * "no preset-specific ground truth" (an explicit `a:camera/a:rot`
+     * override, or an unrecognised preset): callers fall back to their own
+     * `rotateX`/`rotateY` threshold heuristic in that case, unchanged.
+     */
+    panelSides?: PanelVisibility;
+}
+/**
+ * The generic (no camera preset, no explicit rotation) default perspective
+ * distance, re-projected onto `elementSize` instead of the flat `800px`
+ * constant this used to be everywhere it appeared (`visual-3d-extrusion`'s
+ * wrapper style in particular, which falls back to it independently of
+ * {@link getCameraTransform} whenever `scene3d` itself is absent rather than
+ * merely lacking a preset). Exported so every such call site derives the same
+ * size-aware default instead of hand-rolling its own `'800px'` literal.
+ */
+export declare function getDefaultPerspectivePx(elementSize?: ElementSizePx): number;
+/**
+ * Resolve a camera preset name + explicit rotation overrides into final CSS
+ * perspective and rotation (degrees). Explicit `cameraRot*` (1/60000 deg)
+ * override preset defaults; the X axis is negated to match CSS conventions.
+ *
+ * `elementSize`, when provided, re-projects the preset's (or an explicit
+ * `@fov`'s) field of view onto the element's actual rendered size rather than
+ * the `visual-3d-camera-fov`'s `REFERENCE_SIZE_PX` the preset table was tuned at, so a large
+ * shape is not warped as aggressively, in absolute terms, as a small one
+ * under the "same" camera. Omitting it (every call site that predates this
+ * parameter) reproduces the exact legacy `perspectiveRefPx` strings.
+ */
+export declare function getCameraTransform(scene3d: Scene3dParams | undefined, elementSize?: ElementSizePx): CameraTransform;
+//# sourceMappingURL=visual-3d-camera.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"visual-3d-camera.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/visual-3d-camera.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AASH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAS5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE/D,YAAY,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EACN,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,2BAA2B,EAC3B,qBAAqB,GACrB,MAAM,+BAA+B,CAAC;AACvC,YAAY,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EACN,wBAAwB,EACxB,iBAAiB,EACjB,+BAA+B,EAC/B,8BAA8B,EAC9B,6BAA6B,GAC7B,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EACN,iCAAiC,EACjC,wBAAwB,GACxB,MAAM,+BAA+B,CAAC;AACvC,YAAY,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAE5E;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+EAA+E;IAC/E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,2FAA2F;IAC3F,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mGAAmG;IACnG,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uFAAuF;IACvF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;;;;;;OAYG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,eAAe,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,CAAC,EAAE,aAAa,GAAG,MAAM,CAE3E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CACjC,OAAO,EAAE,aAAa,GAAG,SAAS,EAClC,WAAW,CAAC,EAAE,aAAa,GACzB,eAAe,CAyHjB"}

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

@@ -0,0 +1,12 @@
+/**
+ * Colour helpers for the CSS-based 3D approximation (framework-agnostic).
+ *
+ * @module render/visual-3d-color
+ */
+/**
+ * Darken a hex colour by a factor (0 = black, 1 = unchanged).
+ * Used for the deepest extrusion layers and side faces to create a depth
+ * gradient.
+ */
+export declare function darkenColor(hex: string, factor: number): string;
+//# sourceMappingURL=visual-3d-color.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"visual-3d-color.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/visual-3d-color.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAM/D"}

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

@@ -0,0 +1,17 @@
+/**
+ * Shared constants for the CSS-based 3D approximation (framework-agnostic).
+ *
+ * @module render/visual-3d-constants
+ */
+/**
+ * EMU per CSS pixel. PowerPoint stores 3D dimensions in English Metric Units;
+ * the React layer uses the same constant (9525). Defined locally to keep the
+ * 3D modules self-contained.
+ */
+export declare const EMU_PER_PX = 9525;
+/**
+ * Maximum stacked shadow layers for extrusion (performance guard). Matches the
+ * React engine  -  each layer is a single box-shadow, so 40 is still performant.
+ */
+export declare const MAX_EXTRUSION_LAYERS = 40;
+//# sourceMappingURL=visual-3d-constants.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"visual-3d-constants.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/visual-3d-constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;GAIG;AACH,eAAO,MAAM,UAAU,OAAO,CAAC;AAE/B;;;GAGG;AACH,eAAO,MAAM,oBAAoB,KAAK,CAAC"}

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

@@ -0,0 +1,41 @@
+/**
+ * Extrusion side-panel array construction, split out of `visual-3d-extrusion`
+ * to keep that file under the repo's LOC guideline.
+ *
+ * Panels share the front face's transform (`matrix3d` when a homography
+ * camera is active) so they don't visibly separate from its projected edges.
+ * That composition is exact for the legacy `rotateX`/`rotateY` + CSS
+ * `perspective` camera, but is DEGENERATE for a homography-resolved camera
+ * (see `visual-3d-panel-quad`'s module doc comment: a homography's
+ * `matrix3d` never feeds z into the projective divide, so a purely local
+ * rotate + `translateZ` fold collapses the front and back edges onto the
+ * same screen line). When a preset has COM-measured ground truth (see
+ * `PANEL_DEPTH_SKEW_MAP`), `computeHomographyPanelQuad` replaces the whole
+ * rotate/translateZ/transform composition with an explicit projected
+ * quadrilateral instead; presets without ground truth keep the legacy
+ * (still-approximate) composition rather than guessing an unmeasured skew.
+ *
+ * @module render/visual-3d-extrusion-panels
+ */
+import type { ExtrusionPanel } from './visual-3d-extrusion.js';
+import type { PanelVisibility } from './visual-3d-panel-sides.js';
+/** Inputs needed to build the extrusion side-panel array. */
+export interface BuildExtrusionPanelsParams {
+    panelVisibility: PanelVisibility;
+    elementWidth: number;
+    elementHeight: number;
+    clampedDepth: number;
+    halfDepth: number;
+    rotateX: number;
+    rotateY: number;
+    rotateZ: number;
+    matrix3d: string | undefined;
+    homographyResolved: boolean;
+    cameraPreset: string | undefined;
+    sideColorLit: string;
+    sideColor: string;
+    sideColorDeep: string;
+}
+/** Build the extrusion side-panel array (bottom/top/right/left, whichever are visible). */
+export declare function buildExtrusionPanels(params: BuildExtrusionPanelsParams): ExtrusionPanel[];
+//# sourceMappingURL=visual-3d-extrusion-panels.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"visual-3d-extrusion-panels.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/visual-3d-extrusion-panels.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,KAAK,EAAkB,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAG5E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE/D,6DAA6D;AAC7D,MAAM,WAAW,0BAA0B;IAC1C,eAAe,EAAE,eAAe,CAAC;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,kBAAkB,EAAE,OAAO,CAAC;IAC5B,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;CACtB;AAYD,2FAA2F;AAC3F,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,0BAA0B,GAAG,cAAc,EAAE,CAiLzF"}

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"}