ooxml-ui 0.30.0 → 0.31.0

package/dist/pptx/render/visual-3d-bevel-lighting-profile.d.ts

@@ -0,0 +1,141 @@
+/**
+ * `a:bevelT/@prst` profile -> SVG height-map shape.
+ *
+ * Split out of `visual-3d-bevel-lighting-tables.ts` to keep both files under
+ * the repo's ~300 LOC guideline; see that module's doc comment for the other
+ * two axes (light rig elevation, material response) and the highlight
+ * DIRECTION, which is resolved separately in `visual-3d-bevel-light.ts`.
+ *
+ * @module render/visual-3d-bevel-lighting-profile
+ */
+/** How wide/sharp a bevel profile's SVG height-map ramp is, and how strongly it carries a directional signal. */
+export interface BevelProfileHeightMap {
+    /** `feGaussianBlur` `stdDeviation` factor, multiplied by the bevel's own (width+height)/2 in px. */
+    blurFactor: number;
+    /** `feMorphology` `radius` factor (erode), or `undefined` for a pure-blur (smooth, curved) profile. */
+    morphologyFactor?: number;
+    /** Relief height (`surfaceScale`) factor: 1 = full, less for a shallow/steep-walled profile. */
+    surfaceScaleFactor: number;
+    /**
+     * `true` for the two profiles (`slope`, `hardEdge`) COM-measured (see
+     * `visual-3d-bevel-light`) to show NO clean directional brightness signal
+     * at any sampled depth, only a crisp, near-uniform self-shadowed seam. This
+     * is about which CARDINAL EDGE lights up (or doesn't), independent of the
+     * cross-section ramp SHAPE the factors below now target - see this
+     * module's doc comment. Kept as a flag so callers/tests can assert on it
+     * rather than re-deriving it from the two factors above.
+     */
+    measuredUniform: boolean;
+    /**
+     * Non-monotonic height REMAP for the three profiles (`relaxedInset`,
+     * `slope`, `hardEdge`) whose COM cross-section is a genuine
+     * bright-bump-then-dark-trough double transition (see this module's doc
+     * comment), which the `blurFactor`/`morphologyFactor`/`surfaceScaleFactor`
+     * ramp above cannot reproduce on its own: that ramp only ever builds a
+     * single monotonic height field (alpha blurred, optionally eroded), so its
+     * diffuse/specular response can rise-then-settle but never
+     * rise-then-undershoot-then-settle.
+     *
+     * When present, `visual-3d-bevel-lighting.ts` feeds the monotonic ramp
+     * through an SVG `feComponentTransfer`/`feFuncA type="table"` BEFORE
+     * lighting it: `feFuncA` linearly interpolates between these stops across
+     * the input domain `[0, 1]`, so a table that rises then falls then rises
+     * again reshapes the height field's spatial derivative (and therefore its
+     * surface normal, and therefore its diffuse/specular brightness) into a
+     * genuine two-lobe profile, even though the INPUT ramp it remaps is still
+     * monotonic. This is the "genuinely non-monotonic (two-lobe) height-map"
+     * the pre-2026-09-16 doc comment below flagged as out of scope; it is
+     * cheap to build this way because `feComponentTransfer` remaps a value
+     * pointwise, so it needs no new geometry primitive, just a reshaping stage
+     * between the existing blur/erode step and `feDiffuseLighting`.
+     *
+     * Each profile's table is the profile's own pinned 24pt COM cross-section
+     * curve (`visual-3d-bevel-lighting-tables.test.ts`'s
+     * `MEASURED_24PT_CURVES`, 10 points from the top edge inward), normalised
+     * to `[0, 1]` via `(brightness - min) / (max - min)`. This is a deliberate
+     * choice, not a claim of a rigorously inverted lighting model: for a
+     * gently-curved, primarily-diffuse height field the rendered brightness
+     * tracks the local height fairly directly, so reusing the MEASURED
+     * brightness curve's own shape as the height-remap curve reproduces the
+     * measured peak/trough/recovery POSITIONS closely without solving the
+     * (non-invertible in closed form) diffuse/specular equations backwards.
+     * Verified structurally (`visual-3d-bevel-lighting.test.ts`): each table
+     * is non-monotonic (has an interior local max followed by an interior
+     * local min before recovering), and the generated filter markup carries
+     * the `feComponentTransfer` stage only for these three profiles. NOT
+     * independently re-verified against a fresh COM render (no new
+     * `Slide.Export` measurement was taken for this change; the existing 2026-
+     * 09 pins above are the ground truth reused here), so treat the exact
+     * on-screen brightness as an analytical/geometric fit against already-
+     * measured data, not a newly pixel-verified match.
+     */
+    heightTransferTable?: readonly number[];
+}
+/**
+ * `a:bevelT/@prst` (and `bevelB`, which shares the same profile vocabulary)
+ * -> height-map shape. ECMA-376 20.1.10.9 describes each profile's silhouette
+ * (a "circular", "flat sloped", "crossed", "art-deco stepped" etc.
+ * cross-section); these factors were ORIGINALLY grouped into 3
+ * physically-motivated buckets by that description (curved / faceted /
+ * steep-narrow) rather than 12 independent hand-tuned entries, reasoned from
+ * ECMA-376 alone.
+ *
+ * COM-MEASURED 2026-09 (real PowerPoint `Slide.Export`, mid-grey `matte`
+ * square, `threePt` rig / `dir="t"`, `orthographicFront` camera, both a 6pt
+ * and a 24pt `a:bevelT`, a line of 40 brightness samples from the top edge
+ * inward for all 12 profiles): fitting these SAME 3 factors (grid search,
+ * minimum RMSE against the measured curve, both depths jointly) against real
+ * cross-section data overturned the bucket story for 3 profiles.
+ * `circle`/`convex`/`softRound`/`divot` (curved) and `angle`/`cross`/
+ * `coolSlant`/`riblet`/`artDeco` (faceted) fit closely (RMSE 1-7 brightness
+ * units) with factors in the same rough range as the original reasoning, so
+ * their bucket membership held up. `relaxedInset`, `slope` and `hardEdge`
+ * did NOT: all three measured a genuine BRIGHT-BUMP-THEN-DARK-TROUGH double
+ * transition partway through the ramp (e.g. `hardEdge` at 24pt: baseline 133
+ * -> peaks ~139 -> drops to 67 -> recovers), which this filter's single
+ * monotonic blur(+erode) height map (one bell-shaped slope lobe) cannot
+ * reproduce on its own - the original 3-parameter fit pushed
+ * `surfaceScaleFactor` to the largest tested value trying to reach the
+ * trough depth, landing the LARGEST relief factor of any profile, the
+ * opposite of the pre-2026-09 "slope/hardEdge are low-relief" assumption
+ * (`slope`/`hardEdge` were previously reasoned as "steep/narrow" with
+ * REDUCED relief; `relaxedInset` was previously grouped as "curved" with
+ * full relief and no erode at all), but still only reached RMSE 12-19
+ * against the measured curve (versus 1-7 for the other 9).
+ *
+ * **2026-09-16: closed via a height-remap stage.** These three profiles now
+ * also carry a `heightTransferTable` (see that field's own doc comment
+ * above): an `feComponentTransfer`/`feFuncA type="table"` reshaping stage,
+ * inserted between the existing blur(+erode) ramp and the lighting
+ * primitives, remaps the monotonic ramp through each profile's own measured
+ * bright-bump-then-dark-trough curve shape. The three factors below (blur/
+ * morphology/surfaceScale) are UNCHANGED and still control the underlying
+ * ramp's width and crispness; the new field supplies the genuinely
+ * non-monotonic (two-lobe) height response this doc comment previously
+ * flagged as needing a new primitive chain, without actually needing one.
+ * This was NOT re-verified against a fresh COM render (see
+ * `heightTransferTable`'s doc comment); it is an analytical/geometric fit
+ * against the SAME measured curves pinned below, not a new measurement - see
+ * `docs/guide/limitations.md` and `docs/guide/visual-effects.md` for the
+ * current framing.
+ *
+ * The direction-independence these three still show (`measuredUniform`) is
+ * unaffected: it is a separate, already-COM-confirmed finding (see
+ * `visual-3d-bevel-light.ts`'s module doc comment) about which CARDINAL EDGE
+ * lights up, not about the cross-section ramp shape this campaign measures.
+ * Scripts (scratch, not committed, same convention as `com-acceptance.mjs`):
+ * `scripts/make-bevel-profile-fixture.mjs` (fixture, all 12
+ * profiles x 2 depths), `scripts/measure-bevel-profile-com.ps1`
+ * (COM export + 40-point sampler), `scripts/fit-bevel-profile-com.mjs`
+ * (grid-search fit; a closed-form Gaussian-CDF reimplementation of the
+ * primitive chain, not a headless-browser render - Playwright's Chromium
+ * launch hangs indefinitely via a plain script in this environment, though
+ * `bunx playwright test` itself works fine, used to independently verify the
+ * metal/circle routing conclusion in `visual-3d-bevel-lighting-routing.ts`).
+ * The raw 10-point-per-profile table (24pt depth) is pinned in
+ * `visual-3d-bevel-lighting-tables.test.ts`; the full 40-point x 2-depth
+ * table is in the task report.
+ */
+export declare const BEVEL_PROFILE_HEIGHT_MAP: Record<string, BevelProfileHeightMap>;
+export declare function getBevelProfileHeightMap(bevelType: string): BevelProfileHeightMap;
+//# sourceMappingURL=visual-3d-bevel-lighting-profile.d.ts.map

package/dist/pptx/render/visual-3d-bevel-lighting-profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visual-3d-bevel-lighting-profile.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/visual-3d-bevel-lighting-profile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,iHAAiH;AACjH,MAAM,WAAW,qBAAqB;IACrC,oGAAoG;IACpG,UAAU,EAAE,MAAM,CAAC;IACnB,uGAAuG;IACvG,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gGAAgG;IAChG,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;;;;;;;OAQG;IACH,eAAe,EAAE,OAAO,CAAC;IACzB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0CG;IACH,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,eAAO,MAAM,wBAAwB,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAsF1E,CAAC;AAQF,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,qBAAqB,CAEjF"}

package/dist/pptx/render/visual-3d-bevel-lighting-routing.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Legacy `box-shadow` routing for a `material`/profile combination the SVG
+ * lighting filter cannot beat.
+ *
+ * Split out of `visual-3d-bevel-lighting.ts` to keep that file under the
+ * repo's ~300 LOC guideline.
+ *
+ * @module render/visual-3d-bevel-lighting-routing
+ */
+/**
+ * Whether a `material`/`profile` combination is routed to the legacy
+ * `box-shadow` bevel model instead of the SVG lighting filter.
+ */
+export declare function isRoutedToLegacyBevelShadow(material: string | undefined, profile: string): boolean;
+//# sourceMappingURL=visual-3d-bevel-lighting-routing.d.ts.map

package/dist/pptx/render/visual-3d-bevel-lighting-routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visual-3d-bevel-lighting-routing.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/visual-3d-bevel-lighting-routing.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA2CH;;;GAGG;AACH,wBAAgB,2BAA2B,CAC1C,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,OAAO,EAAE,MAAM,GACb,OAAO,CAET"}

package/dist/pptx/render/visual-3d-bevel-lighting-tables.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Data tables for the real SVG lighting bevel filter (framework-agnostic).
+ *
+ * Split out of `visual-3d-bevel-lighting.ts` to keep that module under the
+ * repo's ~300 LOC guideline. Three independent axes feed the filter this
+ * module's data drives: bevel PROFILE shape (`a:bevelT/@prst`, ECMA-376
+ * 20.1.10.9 `ST_BevelPresetType`, re-exported here but defined in
+ * `visual-3d-bevel-lighting-profile.ts`, itself split out for the same LOC
+ * reason), light rig ELEVATION/specular character (`a:lightRig/@rig`,
+ * ECMA-376 20.1.10.36 `ST_LightRigType`, defined below), and MATERIAL
+ * response (`a:sp3d/@prstMaterial`, ECMA-376 20.1.10.50 `ST_PresetMaterialType`,
+ * re-exported from `visual-3d-bevel-lighting-material.ts`).
+ * The highlight/shadow DIRECTION (azimuth) itself is mostly resolved
+ * elsewhere: `visual-3d-bevel-light`'s already COM-measured cardinal-snap
+ * vector supplies the base azimuth from `a:lightRig/@dir`, and this module's
+ * `LIGHT_RIG_LIGHTING.invertedDirection` (COM-measured, see that export's own
+ * doc comment) supplies the one further correction that vector doesn't
+ * cover: 10 of the 27 rigs flip which cardinal edge lights up.
+ *
+ * An early COM check (2026-09, PowerPoint `Slide.Export`, mid-grey 1.4in
+ * square, `circle`/matte, `dir="t"`, sampled 0.15in from the top and bottom
+ * edges) did NOT confirm the then-assumed "harsh has higher contrast than
+ * threePt" ordering at that sample distance: measured contrast (highlight
+ * brightness minus shadow brightness, 0-255) was `threePt` 47, `soft` 38,
+ * `flat` 0 (exactly, matching `flat`'s intentional no-op design), and `harsh`
+ * only -4. A full 27-rig, two-direction (`dir="t"` and the perpendicular
+ * `dir="r"`) follow-up campaign (see `LIGHT_RIG_LIGHTING`'s doc comment)
+ * resolved this: `harsh`'s -4 was not noise or a narrower falloff band, it
+ * was `harsh` being one of the 10 `invertedDirection` rigs (highlight on the
+ * edge OPPOSITE `dir`, so its small measured value is a near-flat rig with
+ * the "wrong" sign, not a sharp rig sampled past its falloff). See
+ * `visual-3d-bevel-lighting.ts`'s module doc for the (separately real)
+ * profile x material x direction COM comparison table.
+ *
+ * @module render/visual-3d-bevel-lighting-tables
+ */
+export { BEVEL_PROFILE_HEIGHT_MAP, getBevelProfileHeightMap, } from './visual-3d-bevel-lighting-profile.js';
+export type { BevelProfileHeightMap } from './visual-3d-bevel-lighting-profile.js';
+/** Light elevation (degrees, 0 = grazing, 90 = straight-on) and specular sharpness bucket for a light rig. */
+export interface LightRigLighting {
+    elevationDeg: number;
+    /** `feSpecularLighting`'s `specularExponent` multiplier (1 = neutral). */
+    specularSharpness: number;
+    /**
+     * `true` when this rig's measured highlight sits on the edge OPPOSITE
+     * `a:lightRig/@dir` rather than the edge `dir` points at (see this
+     * module's doc comment). Combines with (multiplies) the bevel-profile
+     * inversion `isBevelProfileInverted` already applies, the same way that
+     * flag and the top/bottom-bevel inversion already combine.
+     */
+    invertedDirection?: boolean;
+}
+/**
+ * `a:lightRig/@rig` -> elevation/sharpness/direction. COM-CALIBRATED
+ * (2026-09, real PowerPoint `Slide.Export`, mid-grey #808080 1.4in square,
+ * `matte`/`circle`, 24pt bevel, `orthographicFront`, all 27 `ST_LightRigType`
+ * tokens, sampled 0.15in from edge, Rec.709 luminance): a `dir="t"` campaign
+ * (sampling the top/bottom edges) and an independent `dir="r"` campaign
+ * (sampling left/right) were run for every rig; the two agreed on both sign
+ * and magnitude for all 27 rigs (mean absolute difference under 1 brightness
+ * unit), confirming `a:lightRig/@dir` genuinely rotates each rig's effective
+ * azimuth (not a fixed, `dir`-independent offset) and that the per-rig
+ * finding below is repeatable, not sampling noise. Scripts (scratch, not
+ * committed, same convention as `com-acceptance.mjs`):
+ * `scripts/_scratch-make-lightrig-fixture.mjs` (dir="t" fixture, all 27
+ * rigs), `scripts/_scratch-make-lightrig-fixture-dirR.mjs` (dir="r"
+ * counterpart), `scripts/_scratch-measure-sample.ps1` (generic COM
+ * `Slide.Export` + pixel sampler). Raw per-rig table (brightness 0-255,
+ * `contrast` = highlight edge minus opposite edge, averaged between the two
+ * campaigns):
+ *
+ * ```
+ * rig             contrast  elevationDeg  invertedDirection
+ * legacyHarsh2      49.0        73        false
+ * threePt           47.5        74        false
+ * legacyNormal2      43.0        75        false
+ * soft               38.5        77        false
+ * legacyFlat2        37.0        77        false
+ * flood              15.5        85        false
+ * legacyHarsh1        0.0        90        false
+ * legacyFlat1        -0.5        90        false
+ * legacyFlat3         0.0        90        false
+ * legacyNormal1       0.0        90        false
+ * legacyNormal3       0.0        90        false
+ * legacyHarsh3        0.0        90        false
+ * contrasting         0.0        90        false
+ * flat                0.0        90        false
+ * glow                0.0        90        false
+ * brightRoom          0.0        90        false
+ * harsh               -4.0       89        true
+ * balanced            -6.0       88        true
+ * twoPt              -30.5       79        true
+ * legacyFlat4        -37.0       77        true
+ * legacyNormal4      -43.0       75        true
+ * legacyHarsh4       -49.0       73        true
+ * sunset             -74.0       64        true
+ * freezing           -79.1       62        true
+ * chilly             -80.2       62        true
+ * sunrise            -88.6       59        true
+ * morning           -101.1       54        true
+ * ```
+ *
+ * `elevationDeg` was fit (not guessed) by rendering the ACTUAL production SVG
+ * filter primitive chain (`visual-3d-bevel-lighting.ts`'s
+ * `resolveLayer`/`renderLayerPrimitives`, reusing the SAME `getBevelProfile
+ * HeightMap('circle')`/`getMaterialLighting('matte')` table lookups this
+ * module already exports) for `elevationDeg` swept 5..90 in 5deg steps at the
+ * identical geometry, taking a pure-SVG (no `foreignObject`, so the canvas
+ * read-back isn't tainted) screenshot-equivalent raster via a headless
+ * Chromium `<canvas>` draw, and sampling the SAME 0.15in-from-edge points.
+ * That render-side sweep is monotonically decreasing in contrast across
+ * `elevationDeg` 45..90 (117 down to 0 brightness units), which covers every
+ * measured `|contrast|` above (max 101.1); each rig's `elevationDeg` is the
+ * piecewise-linear inverse of its measured `|contrast|` against that curve
+ * (`scripts/_scratch-lightrig-calibration-gen.mjs` + a canvas sampler
+ * embedded in `scripts/_scratch-sample-host.html`, both scratch/uncommitted).
+ * `specularSharpness` was NOT part of this campaign (only `elevationDeg`/
+ * `invertedDirection` were COM-fit) and keeps its pre-existing REASONED
+ * per-family value.
+ *
+ * The most consequential finding is `invertedDirection`: 10 of the 27 rigs
+ * (`harsh`, `balanced`, `twoPt`, the `*4` legacy variant of each `legacy{Flat,
+ * Normal,Harsh}` family, and all 5 weather rigs `morning`/`sunrise`/`sunset`/
+ * `chilly`/`freezing`) measure their highlight on the edge OPPOSITE
+ * `a:lightRig/@dir`, not the edge `dir` points at - the previous reasoned
+ * table had no way to represent this (a single `elevationDeg` cannot flip
+ * azimuth) and silently got the highlight side backwards for all 10.
+ * `legacyFlat2`/`legacyNormal2`/`legacyHarsh2` and their `*4` mirror twins
+ * are NOT interchangeable within a "legacy family" the way the old table
+ * assumed (both grouped to one shared value): `*1`/`*3` measure a clean
+ * `elevationDeg=90` (no directional signal at that sample offset) while `*2`
+ * is normal-direction and `*4` is its exact `invertedDirection` mirror
+ * (matching magnitude, opposite sign) - each of the 4 numbered variants in a
+ * legacy family is now its own table entry rather than 4 copies of one value.
+ */
+export declare const LIGHT_RIG_LIGHTING: Record<string, LightRigLighting>;
+export declare function getLightRigLighting(rigType: string | undefined): LightRigLighting;
+export { getMaterialLighting, MATERIAL_LIGHTING } from './visual-3d-bevel-lighting-material.js';
+export type { MaterialLighting } from './visual-3d-bevel-lighting-material.js';
+//# sourceMappingURL=visual-3d-bevel-lighting-tables.d.ts.map

package/dist/pptx/render/visual-3d-bevel-lighting-tables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visual-3d-bevel-lighting-tables.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/visual-3d-bevel-lighting-tables.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EACN,wBAAwB,EACxB,wBAAwB,GACxB,MAAM,oCAAoC,CAAC;AAC5C,YAAY,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAEhF,8GAA8G;AAC9G,MAAM,WAAW,gBAAgB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,iBAAiB,EAAE,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkFG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CA4B/D,CAAC;AAIF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,gBAAgB,CAKjF;AAED,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AAC7F,YAAY,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAC"}

package/dist/pptx/render/visual-3d-bevel-lighting.d.ts

@@ -0,0 +1,207 @@
+/**
+ * Real SVG lighting for `a:sp3d` bevels (framework-agnostic).
+ *
+ * Closes the first of the three open "3-D shapes and scenes" limitations
+ * (`docs/guide/limitations.md`): bevels used to be CSS `box-shadow` layers
+ * (`visual-3d.ts`'s `getBevelStyle`/`get3DBevelShadow`), a fixed set of inset
+ * shadows per profile with no real lighting model, and material presets a
+ * fully independent, non-interacting CSS `filter` (`visual-3d-materials.ts`).
+ * This module replaces both with ONE physically-grounded SVG filter chain:
+ *
+ * 1. A height map is built from the shape's own alpha silhouette
+ *    (`feGaussianBlur`/`feMorphology` sized by the bevel's `w`/`h`, shaped
+ *    per `a:bevelT/@prst` via `visual-3d-bevel-lighting-tables`'s profile
+ *    buckets - ECMA-376 20.1.10.9).
+ * 2. `feDiffuseLighting` + `feSpecularLighting` light that height map with a
+ *    `feDistantLight` whose azimuth reuses `visual-3d-bevel-light`'s already
+ *    COM-measured cardinal-snap direction (not re-derived here) and whose
+ *    elevation/sharpness comes from the `a:lightRig/@rig` table.
+ * 3. Material (`a:sp3d/@prstMaterial`) sets the SAME light's response
+ *    (`diffuseConstant`/`specularConstant`/`specularExponent`/`lighting-
+ *    color`) instead of a disconnected `filter`, so a metal bevel's specular
+ *    band is now driven by the SAME light as its diffuse shading.
+ * 4. The lit diffuse/specular layers are clipped to `SourceAlpha` and blended
+ *    back over `SourceGraphic` (multiply for diffuse, screen for specular),
+ *    so interior fill/text is untouched and only the edge band relights.
+ *
+ * ## COM comparison (2026-09, real PowerPoint `Slide.Export`, 192px/in)
+ *
+ * Profiles `circle`/`angle`/`hardEdge`/`softRound` x directions `t`/`r`/`b`/`l`
+ * x materials `matte`/`metal` (32 conditions), a 1.4in mid-grey square, a 24pt
+ * `a:bevelT`, `Depth = 0`, `orthographicFront` camera (flat, axis-aligned, so
+ * the same pixel offset samples every condition without a per-shape corner
+ * fit). Ground truth: COM `Slide.Export` PNG, sampled 0.15in from each edge
+ * (the same offset `visual-3d-bevel-light.ts`'s own campaign used) at the
+ * `a:lightRig/@dir`-designated highlight edge and its opposite (shadow) edge.
+ * "Before"/"after" renders: the ACTUAL `getBevelStyle` (box-shadow) and
+ * `getBevelLightingFilterMarkup` (this module) output for the same 32
+ * conditions, painted onto same-scale `<div>`s and sampled at the identical
+ * offsets via a headless Chromium screenshot. Mean absolute error (0-255
+ * brightness, both edges averaged per condition, then averaged per material
+ * across all 4 profiles x 4 directions = 16 samples):
+ *
+ * ```
+ *                         matte   metal   (mean abs error, lower is better)
+ * box-shadow (before)     56.3    61.2
+ * SVG lighting (after)    34.8    59.7
+ * ```
+ *
+ * `matte` improves clearly with the ORIGINAL (uncalibrated) constants. `metal`
+ * as originally tuned was roughly a WASH (61.2 -> 59.7) and hid a real
+ * regression on `metal`/`circle` specifically (54.9 -> 80.1): the
+ * shadow-side sample, which COM measures at a moderate ~178/255, rendered as
+ * near-black (~22/255) because `feDiffuseLighting`'s `N.L<=0` clamp-to-black
+ * is structural to this primitive chain, independent of `diffuseConstant`'s
+ * magnitude (which only scales the LIT side). `metal` was subsequently
+ * RE-CALIBRATED (`visual-3d-bevel-lighting-material.ts`'s `metal` entry,
+ * verified with the same pipeline across all 4 directions): `angle`,
+ * `hardEdge` and `softRound` now land at or below the box-shadow baseline in
+ * every direction, but no combination of `diffuseConstant`/
+ * `specularConstant`/`specularExponent`/`surfaceScaleMultiplier` could bring
+ * `metal`/`circle` below its baseline in any direction (the two targets pull
+ * in opposite directions as `surfaceScale` changes - see
+ * `visual-3d-bevel-lighting-routing.ts`'s `isRoutedToLegacyBevelShadow` doc
+ * comment), so `metal`/`circle` ROUTED to the legacy `box-shadow` model at
+ * the time (SUPERSEDED 2026-09 below; it no longer routes). The "before"
+ * numbers are large because this campaign scores absolute brightness match,
+ * not just highlight/shadow SIGN agreement (all `getBevelShadow`'s
+ * box-shadow output was previously verified against). Scripts: scratch
+ * tooling, same convention as `com-acceptance.mjs`.
+ *
+ * ## Re-run against the CURRENT `threePt` elevationDeg (2026-09, post-lightRig-recalibration)
+ *
+ * The 32-condition table above predates `LIGHT_RIG_LIGHTING`'s COM
+ * recalibration (`threePt` moved from an assumed 45deg to a measured 74deg);
+ * re-running the SAME 32 conditions (fresh COM ground truth, which matched
+ * the historical per-condition numbers above exactly, confirming both
+ * campaigns sample the same real PowerPoint behaviour) against the CURRENT
+ * elevationDeg found the change is a genuine regression for BOTH materials,
+ * not just `metal`: `matte`'s mean absolute error rose from the 34.8 above to
+ * ~47.4 (`hardEdge` alone: ~90, COM 133/133 vs a render of ~73/14), even
+ * though `matte`'s `specularConstant` is negligible (0.02) - this is a
+ * DIFFUSE-side regression, `elevationDeg` itself reshaping the diffuse
+ * contrast band at 74deg differently than it did at 45deg, independent of
+ * the specular-saturation issue below.
+ *
+ * A SEPARATE COM campaign (mid-grey `#808080` square, `circle` bevel,
+ * sampled at the shape's exact CENTER, i.e. the flat, non-bevelled interior,
+ * not the edge band) measured `metal`/`matte`/`plastic` PIXEL-IDENTICAL at
+ * every rig tested (`flat`/`contrasting`/`threePt`/`legacyHarsh1-4`/`harsh`/
+ * `balanced`/`soft`/`twoPt`/`sunrise`/`morning`/`flood`/`glow`/`brightRoom`,
+ * elevations 54-90deg): e.g. `flat` reads `rgb(127,127,127)` (the raw fill,
+ * unlit) for all three materials, `morning` reads `rgb(112,108,98)` for all
+ * three. Real PowerPoint's material response is therefore zero on a flat
+ * normal at every elevation, not just small - confirming the "whole shape
+ * washes out under `threePt`" defect this module's material doc comment
+ * describes is real and elevation-independent in its WRONGNESS, even though
+ * this filter's own flat-region specular term is highly elevation-dependent
+ * (0 at low elevation, the full `specularConstant` at 90).
+ *
+ * An attempted fix (2026-09) gave `feSpecularLighting` its OWN
+ * `<feDistantLight>` elevation, decoupled from the rig's diffuse elevation
+ * and fixed low enough that the flat-region term is negligible by
+ * closed-form calculation (verified: at 20deg, under 2/255 brightness units
+ * for `metal`'s worst-case `specularConstant`/`specularExponent`). Render-vs-
+ * COM re-measurement of the SAME 32 band conditions at this decoupled
+ * elevation found the fix is NOT clean: it is not simply "lower is safer" -
+ * `hardEdge` (already low-relief, steep-eroded) improved or stayed flat, but
+ * `angle` and `softRound` got MUCH worse at both 20deg (`metal`/`angle` hi
+ * COM 141 vs rendered 154-214, `metal`/`softRound` sh COM 141 vs rendered
+ * 155) and 45deg (`metal`/`angle` hi rendered 225-234, `metal`/`softRound` sh
+ * rendered 234, i.e. saturating). The likely cause: for a profile whose
+ * height-map gradient is steep (the `erode`-heavy faceted family), a LOWER
+ * light elevation can align the half-vector `H` more closely with a TILTED
+ * band normal than a high elevation does with the FLAT normal, so
+ * suppressing the flat-region term this way can amplify the band's own
+ * specular peak instead, in a profile-specific, non-monotonic way. This
+ * decoupling attempt was NOT landed (reverted after measurement). A working
+ * fix likely needs the specular layer's contribution MASKED to the actual
+ * curved band (e.g. the difference between the original and eroded/blurred
+ * alpha, rather than the whole `SourceAlpha`) so a flat interior gets zero
+ * specular by construction regardless of elevation, or a full joint
+ * numerical re-fit of `elevationDeg`/`specularElevationDeg`/
+ * `specularConstant`/`specularExponent`/`surfaceScaleMultiplier` per
+ * material against this same COM ground truth. Neither was completed in
+ * this pass; see `docs/guide/limitations.md`.
+ *
+ * ## 2026-09 bevel-profile cross-section + specular-masking follow-up
+ *
+ * Kept in the files they most directly touch (LOC budget): the 12
+ * `a:bevelT/@prst` height-map SHAPES were fit against real COM cross-section
+ * curves for the first time (`visual-3d-bevel-lighting-tables.ts`'s doc +
+ * pinned table in its `.test.ts`), changing `circle`'s `surfaceScaleFactor`
+ * enough that `metal`/`circle` now beats baseline unrouted; a follow-up
+ * specular-band-masking attempt at the saturation defect above was measured
+ * and made things WORSE (`visual-3d-bevel-lighting-routing.ts`'s doc).
+ *
+ * ## 2026-09-16: non-monotonic height-remap for relaxedInset/slope/hardEdge
+ *
+ * `renderLayerPrimitives` below now inserts an `feComponentTransfer`/
+ * `feFuncA type="table"` stage between the blur(+erode) height ramp and the
+ * lighting primitives whenever the resolved layer carries a
+ * `heightTransferTable` (`visual-3d-bevel-lighting-profile.ts`'s
+ * `BEVEL_PROFILE_HEIGHT_MAP` entries for `relaxedInset`/`slope`/`hardEdge`
+ * only). This closes the bevel-profile-shape gap the cross-section campaign
+ * above left open: the monotonic ramp is reshaped through each profile's own
+ * measured bright-bump-then-dark-trough curve, giving a genuine two-lobe
+ * height response instead of forcing the OLD 3-parameter (blur/erode/
+ * surfaceScale) chain to approximate one. This is an analytical fit against
+ * the ALREADY-pinned COM cross-section curves above, not a fresh COM
+ * re-measurement; see `BevelProfileHeightMap.heightTransferTable`'s doc
+ * comment for exactly what was and was not re-verified. The SEPARATE
+ * specular/diffuse coupling defect (metal oversaturating under a
+ * high-elevation rig) was UNCHANGED by this pass; see the next section for
+ * its resolution.
+ *
+ * ## 2026-09-24: metal specular/diffuse elevation decoupling (RESOLVED)
+ *
+ * `BevelFilterLayer.specularElevationDeg` gives the specular `<feDistantLight>`
+ * its own elevation, `Math.min(rigElevation, cap)` capped independently of
+ * diffuse via `MaterialLighting.specularElevationCapDeg` (mechanism + full
+ * numbers in that field's doc comment, `visual-3d-bevel-lighting-material
+ * .ts`): mean absolute error 75.0 -> 36.4 on a 134-condition, full-cross-
+ * section COM set, jointly re-fit with `metal`'s `specularConstant`/
+ * `specularExponent`, unlike the fixed-elevation attempt above.
+ * `surfaceScaleMultiplier` was deliberately left untouched (lowering it
+ * flattens the diffuse band too, a different concern). Only `metal` carries
+ * a cap, so every other material's filter markup is unchanged.
+ *
+ * @module render/visual-3d-bevel-lighting
+ */
+import type { PptxElement } from 'ooxml-core/pptx';
+import type { SvgFilterDefinition } from './visual-effects.js';
+/** Structural subset of the bevel-relevant `Pptx3DShape` fields. */
+export interface BevelLightingShapeParams {
+    bevelTopType?: string;
+    bevelTopWidth?: number;
+    bevelTopHeight?: number;
+    bevelBottomType?: string;
+    bevelBottomWidth?: number;
+    bevelBottomHeight?: number;
+    presetMaterial?: string;
+}
+/** Structural subset of the bevel-relevant `Pptx3DScene` fields. */
+export interface BevelLightingSceneParams {
+    lightRigType?: string;
+    lightRigDirection?: string;
+}
+/** Stable SVG filter id for a bevel lighting filter on a given element. */
+export declare function getBevelLightingFilterId(elementId: string): string;
+/**
+ * Build the bevel lighting `<filter>` for a shape's `a:sp3d` bevel(s).
+ * Returns `undefined` when the shape has no top/bottom bevel, OR when the
+ * shape's material/profile combination is routed to the legacy `box-shadow`
+ * model (see `visual-3d-bevel-lighting-routing.ts`'s `isRoutedToLegacyBevel
+ * Shadow` doc comment) - the caller (`visual-3d.ts`) already falls back to
+ * `getBevelStyle`/`get3DBevelShadow` whenever this returns `undefined`, so
+ * routing is a no-op change to that call site: it reuses the SAME fallback
+ * path a bevel-less shape takes.
+ */
+export declare function getBevelLightingFilterMarkup(elementId: string, shape3d: BevelLightingShapeParams | undefined, scene3d: BevelLightingSceneParams | undefined): SvgFilterDefinition | undefined;
+/**
+ * Convenience wrapper: resolve a bevel lighting filter straight from a
+ * `PptxElement`, mirroring `getSoftEdgeSvgFilter`'s call shape. Returns
+ * `undefined` for a non-shape element or one with no bevel.
+ */
+export declare function getBevelLightingSvgFilter(el: PptxElement): SvgFilterDefinition | undefined;
+//# sourceMappingURL=visual-3d-bevel-lighting.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"visual-3d-bevel-lighting.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/visual-3d-bevel-lighting.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyKG;AAEH,OAAO,KAAK,EAA4B,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAM7E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAG5D,oEAAoE;AACpE,MAAM,WAAW,wBAAwB;IACxC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,oEAAoE;AACpE,MAAM,WAAW,wBAAwB;IACxC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC3B;AA2DD,2EAA2E;AAC3E,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAElE;AAED;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAC3C,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,wBAAwB,GAAG,SAAS,EAC7C,OAAO,EAAE,wBAAwB,GAAG,SAAS,GAC3C,mBAAmB,GAAG,SAAS,CA+DjC;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,WAAW,GAAG,mBAAmB,GAAG,SAAS,CAQ1F"}

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

@@ -0,0 +1,44 @@
+/**
+ * Field-of-view <-> CSS perspective-distance math for the camera-preset
+ * mapping (framework-agnostic).
+ *
+ * Split out of `visual-3d-camera.ts` to keep that file under the repo's
+ * ~300 LOC guideline once the preset table grew a geometric FOV model on top
+ * of its rotation angles; see that module's doc comment for the overall
+ * design (reference size, per-preset reference distance, zoom).
+ *
+ * @module render/visual-3d-camera-fov
+ */
+/** The on-screen size (px) of the element the camera is projected onto. */
+export interface ElementSizePx {
+    width: number;
+    height: number;
+}
+/**
+ * The pixel size the camera preset table's reference distances were
+ * hand-tuned at. Callers that omit an `ElementSizePx` get back the exact
+ * legacy distance for a preset; callers that pass the element's actual
+ * rendered size get a proportionally re-projected one.
+ */
+export declare const REFERENCE_SIZE_PX = 300;
+/**
+ * Derive the FOV (radians) a reference perspective distance implies at
+ * {@link REFERENCE_SIZE_PX}, by inverting `d = (size / 2) / tan(f / 2)`.
+ */
+export declare function fovFromRefPx(refPx: number): number;
+/**
+ * Narrow (or widen) an FOV by a camera zoom factor, the way a real lens
+ * flattens perspective when zooming in from a fixed position: increasing
+ * `zoom` decreases `tan(f/2)` proportionally, which decreases the resulting
+ * FOV (a longer effective focal length) and so increases the projected
+ * perspective distance. `zoom <= 0` is treated as unset (100%).
+ */
+export declare function applyZoomToFov(fovRad: number, zoom: number | undefined): number;
+/**
+ * Project an FOV (radians) onto an on-screen size (px) into a CSS
+ * `perspective` distance (px): `d = (size / 2) / tan(f / 2)`.
+ */
+export declare function fovToPerspectivePx(fovRad: number, sizePx: number): number;
+/** The larger of an `ElementSizePx`'s two dimensions, or the reference size when omitted. */
+export declare function resolveSizePx(elementSize: ElementSizePx | undefined): number;
+//# sourceMappingURL=visual-3d-camera-fov.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"visual-3d-camera-fov.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/visual-3d-camera-fov.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,2EAA2E;AAC3E,MAAM,WAAW,aAAa;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAK/E;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEzE;AAED,6FAA6F;AAC7F,wBAAgB,aAAa,CAAC,WAAW,EAAE,aAAa,GAAG,SAAS,GAAG,MAAM,CAE5E"}

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

@@ -0,0 +1,36 @@
+/**
+ * Generic "unit square -> quadrilateral" projective homography solver
+ * (framework-agnostic, no OOXML-specific knowledge).
+ *
+ * Split out of `visual-3d-camera-parametric.ts` so that module's own math
+ * (the actual camera model) is not tangled with this general-purpose closed
+ * form, and so it can be unit-tested in isolation against hand-computed
+ * cases. This is the standard "map a square to an arbitrary convex
+ * quadrilateral" projective transform (P. Heckbert, "Fundamentals of Texture
+ * Mapping and Image Warping", UC Berkeley MS thesis, 1989, §3): given the
+ * four destination points the unit square's corners `(0,0) (1,0) (0,1)
+ * (1,1)` map to, it returns the unique 3x3 homography (`h33` normalised to
+ * 1) reproducing exactly those four correspondences - the same
+ * {@link Homography3} shape `visual-3d-camera-homography`'s COM-measured
+ * preset table already uses, so its `homographyToMatrix3d` embedding is
+ * reused unchanged for a homography built by this module too.
+ *
+ * @module render/visual-3d-camera-homography-math
+ */
+import type { Homography3 } from './visual-3d-camera-homography.js';
+/** A 2D point. */
+export interface Point2 {
+    x: number;
+    y: number;
+}
+/**
+ * Solve the projective homography mapping the unit square's corners
+ * `(0,0)->d00`, `(1,0)->d10`, `(0,1)->d01`, `(1,1)->d11`. Degenerates
+ * gracefully to the identity when all four destinations equal their source
+ * (avoids a division by zero the affine special case would otherwise need to
+ * guard separately).
+ */
+export declare function unitSquareToQuadHomography(d00: Point2, d10: Point2, d01: Point2, d11: Point2): Homography3;
+/** Apply a {@link Homography3} to a single point (for tests / sanity checks). */
+export declare function applyHomography(h: Homography3, p: Point2): Point2;
+//# sourceMappingURL=visual-3d-camera-homography-math.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"visual-3d-camera-homography-math.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/visual-3d-camera-homography-math.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAEjE,kBAAkB;AAClB,MAAM,WAAW,MAAM;IACtB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACV;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACzC,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,GACT,WAAW,CA0Bb;AAED,iFAAiF;AACjF,wBAAgB,eAAe,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAIjE"}