ooxml-ui 0.30.1 → 0.31.0

package/dist/pptx/render/model3d-scene-apply.d.ts

@@ -0,0 +1,33 @@
+/**
+ * three.js applier for a {@link Model3DSceneDescriptor}.
+ *
+ * Builds the camera, lights and (optional) model wrapper for
+ * `mountModel3D` from the pure descriptor. `three` is passed in by the caller
+ * (it is an optional, dynamically imported peer), so this file only carries
+ * type-only imports.
+ */
+import type * as THREE from 'three';
+import type { Model3DSceneDescriptor } from './model3d-scene-descriptor.js';
+type ThreeModule = typeof THREE;
+/**
+ * Scene units per metre. The model is auto-fitted to a 2-unit cube, so one
+ * metre spans `2 / (maxModelDim * meterPerModelUnit)` units. Without an
+ * authored `meterPerModelUnit` the authored camera distance is normalised to
+ * the default distance so the model still fills the view sensibly.
+ */
+export declare function computeMetresToSceneScale(desc: Model3DSceneDescriptor, maxModelDim: number): number;
+/** The objects `mountModel3D` needs, built from a descriptor. */
+export interface Model3DRig {
+    camera: THREE.PerspectiveCamera | THREE.OrthographicCamera;
+    lights: THREE.Object3D[];
+    /** Camera-to-target distance in scene units (for orbit limits). */
+    distance: number;
+    /** Wrap the fitted model with the authored scale/rotation/offset, if any. */
+    placeModel: (model: THREE.Object3D) => THREE.Object3D;
+    /** Re-fit the camera after a viewport aspect change. */
+    setAspect: (aspect: number) => void;
+}
+/** Build camera, lights and model placement for a descriptor. */
+export declare function buildModel3DRig(three: ThreeModule, desc: Model3DSceneDescriptor, aspect: number, maxModelDim: number): Model3DRig;
+export {};
+//# sourceMappingURL=model3d-scene-apply.d.ts.map

package/dist/pptx/render/model3d-scene-apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model3d-scene-apply.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/model3d-scene-apply.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAGpC,OAAO,KAAK,EAEX,sBAAsB,EAEtB,MAAM,4BAA4B,CAAC;AAEpC,KAAK,WAAW,GAAG,OAAO,KAAK,CAAC;AAMhC;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACxC,IAAI,EAAE,sBAAsB,EAC5B,WAAW,EAAE,MAAM,GACjB,MAAM,CAYR;AAID,iEAAiE;AACjE,MAAM,WAAW,UAAU;IAC1B,MAAM,EAAE,KAAK,CAAC,iBAAiB,GAAG,KAAK,CAAC,kBAAkB,CAAC;IAC3D,MAAM,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC;IACzB,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,UAAU,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,KAAK,KAAK,CAAC,QAAQ,CAAC;IACtD,wDAAwD;IACxD,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CACpC;AAuCD,iEAAiE;AACjE,wBAAgB,eAAe,CAC9B,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,sBAAsB,EAC5B,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GACjB,UAAU,CA2DZ"}

package/dist/pptx/render/model3d-scene-descriptor.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Pure decision function: authored PowerPoint 3D scene data -> a
+ * framework-neutral three.js scene descriptor.
+ *
+ * `resolveModel3DSceneDescriptor` reads the camera, model transform and lights
+ * parsed by core (`Model3DSceneData`) and returns plain numbers/strings. All
+ * lengths in the descriptor are METRES (EMU / 914400); the three.js applier
+ * ({@link ./model3d-scene-apply}) converts metres into fitted scene units once
+ * the model's size is known. When nothing is authored the descriptor reproduces
+ * the viewer's long-standing default framing and lights.
+ *
+ * NOTE: not yet verified against PowerPoint renders (axis handedness of
+ * `am3d:rot`, ordering of `preTrans`, and orthographic scale are unconfirmed).
+ */
+import type { Model3DSceneData } from 'ooxml-core/pptx';
+/** Default vertical field of view (degrees) used when none is authored. */
+export declare const DEFAULT_MODEL3D_FOV_DEG = 50;
+/** Plain 3-tuple. */
+export type Vec3Tuple = readonly [number, number, number];
+/** Camera part of the descriptor. */
+export interface Model3DCameraDescriptor {
+    /** `authored` = derived from `am3d:camera`; `default` = built-in framing. */
+    framing: 'authored' | 'default';
+    kind: 'perspective' | 'orthographic';
+    fovDeg: number;
+    /** Metres in model space (`authored`) or fitted scene units (`default`). */
+    position: Vec3Tuple;
+    up: Vec3Tuple;
+    /** Look-at target, same space as `position`. */
+    target: Vec3Tuple;
+}
+/** Model placement part of the descriptor. */
+export interface Model3DTransformDescriptor {
+    /** Metres per model unit; `undefined` means "unknown, keep the fitted size". */
+    meterPerModelUnit?: number;
+    scale: Vec3Tuple;
+    /** Euler XYZ rotation in degrees. */
+    rotationDeg: Vec3Tuple;
+    /** Offset applied after scale/rotation, metres. */
+    postTranslate: Vec3Tuple;
+}
+/** One three.js light. */
+export interface Model3DLightDescriptor {
+    kind: 'ambient' | 'point' | 'spot' | 'directional';
+    /** `#rrggbb`. */
+    color: string;
+    intensity: number;
+    /** Metres (authored) or scene units (default lights). */
+    position?: Vec3Tuple;
+    /** Direction the light travels; directional/spot only. */
+    direction?: Vec3Tuple;
+    /** Spot cone half-angle in degrees. */
+    spotAngleDeg?: number;
+}
+/** Framework-neutral scene descriptor consumed by the three.js applier. */
+export interface Model3DSceneDescriptor {
+    /** `true` when any of camera/transform/lights came from the file. */
+    authored: boolean;
+    camera: Model3DCameraDescriptor;
+    /** `true` when `lights` came from the file (positions are then metres). */
+    lightsAuthored: boolean;
+    /** `undefined` when no `am3d:trans` was authored. */
+    transform?: Model3DTransformDescriptor;
+    lights: Model3DLightDescriptor[];
+}
+/** The built-in camera (unchanged pre-existing framing). */
+export declare const DEFAULT_MODEL3D_CAMERA: Model3DCameraDescriptor;
+/** The built-in lights (unchanged pre-existing rig). */
+export declare const DEFAULT_MODEL3D_LIGHTS: readonly Model3DLightDescriptor[];
+/**
+ * Turn parsed 3D scene data into a three.js scene descriptor. With no data
+ * (or no authored camera / lights) the matching part falls back to the default
+ * framing / lights, so `resolveModel3DSceneDescriptor(undefined)` equals the
+ * previous hard-coded setup.
+ */
+export declare function resolveModel3DSceneDescriptor(scene: Model3DSceneData | undefined): Model3DSceneDescriptor;
+//# sourceMappingURL=model3d-scene-descriptor.d.ts.map

package/dist/pptx/render/model3d-scene-descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model3d-scene-descriptor.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/model3d-scene-descriptor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAoB,gBAAgB,EAAe,MAAM,iBAAiB,CAAC;AAIvF,2EAA2E;AAC3E,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C,qBAAqB;AACrB,MAAM,MAAM,SAAS,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAE1D,qCAAqC;AACrC,MAAM,WAAW,uBAAuB;IACvC,6EAA6E;IAC7E,OAAO,EAAE,UAAU,GAAG,SAAS,CAAC;IAChC,IAAI,EAAE,aAAa,GAAG,cAAc,CAAC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,QAAQ,EAAE,SAAS,CAAC;IACpB,EAAE,EAAE,SAAS,CAAC;IACd,gDAAgD;IAChD,MAAM,EAAE,SAAS,CAAC;CAClB;AAED,8CAA8C;AAC9C,MAAM,WAAW,0BAA0B;IAC1C,gFAAgF;IAChF,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,KAAK,EAAE,SAAS,CAAC;IACjB,qCAAqC;IACrC,WAAW,EAAE,SAAS,CAAC;IACvB,mDAAmD;IACnD,aAAa,EAAE,SAAS,CAAC;CACzB;AAED,0BAA0B;AAC1B,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,aAAa,CAAC;IACnD,iBAAiB;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,uCAAuC;IACvC,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,2EAA2E;AAC3E,MAAM,WAAW,sBAAsB;IACtC,qEAAqE;IACrE,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,uBAAuB,CAAC;IAChC,2EAA2E;IAC3E,cAAc,EAAE,OAAO,CAAC;IACxB,qDAAqD;IACrD,SAAS,CAAC,EAAE,0BAA0B,CAAC;IACvC,MAAM,EAAE,sBAAsB,EAAE,CAAC;CACjC;AAED,4DAA4D;AAC5D,eAAO,MAAM,sBAAsB,EAAE,uBAOpC,CAAC;AAEF,wDAAwD;AACxD,eAAO,MAAM,sBAAsB,EAAE,SAAS,sBAAsB,EAInE,CAAC;AAmEF;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC5C,KAAK,EAAE,gBAAgB,GAAG,SAAS,GACjC,sBAAsB,CAoBxB"}

package/dist/pptx/render/model3d-scene.cjs

@@ -0,0 +1,22 @@
+'use strict';
+
+var chunk2JEQHIAL_cjs = require('../chunk-2JEQHIAL.cjs');
+
+
+
+Object.defineProperty(exports, "DEFAULT_MODEL_MIME", {
+  enumerable: true,
+  get: function () { return chunk2JEQHIAL_cjs.DEFAULT_MODEL_MIME; }
+});
+Object.defineProperty(exports, "THREE_UNAVAILABLE", {
+  enumerable: true,
+  get: function () { return chunk2JEQHIAL_cjs.THREE_UNAVAILABLE; }
+});
+Object.defineProperty(exports, "modelDataToBlobUrl", {
+  enumerable: true,
+  get: function () { return chunk2JEQHIAL_cjs.modelDataToBlobUrl; }
+});
+Object.defineProperty(exports, "mountModel3D", {
+  enumerable: true,
+  get: function () { return chunk2JEQHIAL_cjs.mountModel3D; }
+});

package/dist/pptx/render/model3d-scene.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Vanilla three.js GLTF/GLB model scene controller (framework-agnostic).
+ *
+ * Mounts an interactive 3D model into a caller-provided container element:
+ * dynamically imports `three` plus its `GLTFLoader` and `OrbitControls` addons,
+ * builds a scene (perspective camera, lights), auto-centres and fits the model
+ * to the view via a `Box3`, renders with a RAF loop, and exposes `resize()` /
+ * `dispose()` for deterministic teardown of GPU resources.
+ *
+ * `three` is an OPTIONAL peer dependency: every import is dynamic and guarded.
+ * When `three` is not installed, {@link mountModel3D} resolves to a sentinel
+ * handle ({@link THREE_UNAVAILABLE}) so the caller can fall back to a poster.
+ * No framework imports - the React, Vue, and Angular bindings can all mount it.
+ */
+import type { Model3DSceneData } from 'ooxml-core/pptx';
+/** Default MIME for GLB binaries when the element omits `modelMimeType`. */
+export declare const DEFAULT_MODEL_MIME = "model/gltf-binary";
+/**
+ * Convert a base64 `modelData` data URL to a blob (object) URL the GLTF
+ * loader can fetch. Returns `undefined` for missing / non-base64 data URLs.
+ *
+ * Vue's `useModel3dScene` (`modelDataToBlobUrl`), Svelte's `render/
+ * model3d-view.ts`, and Vanilla's `render/elements/model3d.ts` each carried a
+ * byte-identical copy of this, built on core's `parseDataUrlToBytes`; this is
+ * the one copy. (React's own `Model3DRenderer.tsx` hand-decodes base64 itself
+ * rather than calling core's `parseDataUrlToBytes` and infers its MIME from
+ * the data URL instead of accepting a `mimeType` parameter - a behavioural
+ * difference for the binding wave to reconcile when repointing.)
+ */
+export declare function modelDataToBlobUrl(dataUrl: string | undefined, mimeType: string | undefined): string | undefined;
+/** Options for {@link mountModel3D}. */
+export interface Model3DSceneOptions {
+    /** Initial CSS-pixel width of the view. */
+    width: number;
+    /** Initial CSS-pixel height of the view. */
+    height: number;
+    /** Enable OrbitControls (rotate + zoom, no pan). Default `true`. */
+    interactive?: boolean;
+    /** Solid background colour `#rrggbb`; omit for a transparent canvas. */
+    background?: string;
+    /** Device pixel-ratio cap. Default `2`. */
+    maxPixelRatio?: number;
+    /** Authored camera/transform/lights; omit for the default framing. */
+    scene?: Model3DSceneData;
+}
+/** Imperative handle to a mounted 3D model view. */
+export interface Model3DHandle {
+    /** Whether the model mounted (false = `three` missing / load failed). */
+    readonly ok: boolean;
+    /** Resize the renderer + camera to new CSS-pixel dimensions. */
+    resize: (width: number, height: number) => void;
+    /** Toggle interactive orbit controls at runtime. */
+    setInteractive: (on: boolean) => void;
+    /** Tear down the renderer, controls, loaded model, and GPU resources. */
+    dispose: () => void;
+}
+/**
+ * Sentinel handle returned when `three` is unavailable or the model fails to
+ * load. All methods are no-ops; `ok` is `false` so callers can show a poster.
+ */
+export declare const THREE_UNAVAILABLE: Model3DHandle;
+/**
+ * Mount an interactive GLTF/GLB model into `container` and start rendering.
+ *
+ * Resolves to {@link THREE_UNAVAILABLE} (a no-op handle with `ok === false`)
+ * when `three` or its addons cannot be loaded, or when the model fails to parse.
+ */
+export declare function mountModel3D(container: HTMLElement, modelUrl: string, options: Model3DSceneOptions): Promise<Model3DHandle>;
+//# sourceMappingURL=model3d-scene.d.ts.map

package/dist/pptx/render/model3d-scene.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model3d-scene.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/model3d-scene.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAWxD,4EAA4E;AAC5E,eAAO,MAAM,kBAAkB,sBAAsB,CAAC;AAEtD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CACjC,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC1B,MAAM,GAAG,SAAS,CAcpB;AAED,wCAAwC;AACxC,MAAM,WAAW,mBAAmB;IACnC,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sEAAsE;IACtE,KAAK,CAAC,EAAE,gBAAgB,CAAC;CACzB;AAED,oDAAoD;AACpD,MAAM,WAAW,aAAa;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,gEAAgE;IAChE,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD,oDAAoD;IACpD,cAAc,EAAE,CAAC,EAAE,EAAE,OAAO,KAAK,IAAI,CAAC;IACtC,yEAAyE;IACzE,OAAO,EAAE,MAAM,IAAI,CAAC;CACpB;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,aAK/B,CAAC;AA6DF;;;;;GAKG;AACH,wBAAsB,YAAY,CACjC,SAAS,EAAE,WAAW,EACtB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,mBAAmB,GAC1B,OAAO,CAAC,aAAa,CAAC,CAyHxB"}

package/dist/pptx/render/model3d-scene.mjs

@@ -0,0 +1 @@
+export { DEFAULT_MODEL_MIME, THREE_UNAVAILABLE, modelDataToBlobUrl, mountModel3D } from '../chunk-DMWNOP4E.mjs';

package/dist/pptx/render/modify-password-check.d.ts

@@ -0,0 +1,39 @@
+import type { PptxModifyVerifier } from 'ooxml-core/pptx';
+export type ModifyPasswordCheckResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: 'wrong-password' | 'unsupported-algorithm';
+};
+/**
+ * Check a candidate password against `verifier`.
+ *
+ * The algorithm check goes through `resolveModifyVerifierAlgorithmName`
+ * (`ooxml-core/pptx`), not a bare `verifier.algorithmName` read: PowerPoint's
+ * own "Set Password to Modify" writes ONLY `cryptAlgorithmSid` (no
+ * `algorithmName` attribute at all), so a bare read here would report every
+ * real PowerPoint-authored modify password as unsupported, exactly the same
+ * mistake `ReadOnlyRecommendation.requiresPassword` would make without the
+ * same resolver, which is the whole reason this function exists to check the
+ * password `requiresPassword` promised was checkable.
+ *
+ * Returns `{ ok: false, reason: 'unsupported-algorithm' }` both when the
+ * verifier is missing the pieces needed to run the check at all (mirrors
+ * `requiresPassword`, but this function stays defensive against being called
+ * directly) and when core's verifier throws trying to compute the digest
+ * (an algorithm this viewer's Web Crypto binding does not support).
+ *
+ * A missing `saltData` is NOT one of those pieces: `p:modifyVerifier`'s
+ * `saltData` attribute is optional (ECMA-376 19.2.1.22), and core's
+ * `verifyModifyPassword` treats an absent salt as a zero-length one and runs
+ * the same hash derivation, so a salt-less verifier is checkable here too.
+ * See `verifyModifyPassword`'s module doc comment ("Salt-less verifiers") in
+ * `ooxml-core/pptx` for the ECMA-376/[MS-OFFCRYPTO] citation; that comment
+ * also documents a COM-confirmed surprise worth knowing before assuming this
+ * mirrors PowerPoint: real PowerPoint's own "Set Password to Modify" check
+ * rejects EVERY password (including the mathematically correct one) for a
+ * salt-less verifier, so this function is deliberately MORE permissive than
+ * PowerPoint's own implementation, not a reproduction of it.
+ */
+export declare function checkModifyPassword(verifier: PptxModifyVerifier | undefined, password: string): Promise<ModifyPasswordCheckResult>;
+//# sourceMappingURL=modify-password-check.d.ts.map

package/dist/pptx/render/modify-password-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"modify-password-check.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/modify-password-check.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE1D,MAAM,MAAM,yBAAyB,GAClC;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;CAAE,GACrB;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,uBAAuB,CAAA;CAAE,CAAC;AAEvF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,mBAAmB,CACxC,QAAQ,EAAE,kBAAkB,GAAG,SAAS,EACxC,QAAQ,EAAE,MAAM,GACd,OAAO,CAAC,yBAAyB,CAAC,CAUpC"}

package/dist/pptx/render/morph-animation.d.ts

@@ -0,0 +1,264 @@
+/**
+ * CSS keyframe generation for morph transitions.
+ *
+ * Generates per-element CSS keyframe animation data for matched and
+ * unmatched elements, including fill colour interpolation, stroke
+ * interpolation, and text morph animations.
+ *
+ * Pure: produces CSS keyframe strings only. DOM injection of the generated
+ * keyframes (creating/removing `<style>` elements) is a binding concern and
+ * stays in the consuming framework.
+ *
+ * @module render/morph-animation
+ */
+import type { PptxElement, PptxSlide } from 'ooxml-core/pptx';
+import type { MorphAnimationStyle, MorphMode, MorphPair } from './morph-types.js';
+import type { ZOrderJourney } from './morph-z-order.js';
+/**
+ * Generate CSS keyframe properties for fill colour interpolation between two elements.
+ * Returns an object with `from` and `to` background-color declarations, or null
+ * if both elements lack fill or are identical.
+ *
+ * @param fromElement - The outgoing element.
+ * @param toElement - The incoming element.
+ * @returns Fill colour keyframe properties, or null if no interpolation is needed.
+ */
+export declare function buildColorInterpolationProps(fromElement: PptxElement, toElement: PptxElement): {
+    fromBg: string;
+    toBg: string;
+} | null;
+/**
+ * Generate CSS keyframe properties for stroke interpolation between two elements.
+ *
+ * @param fromElement - The outgoing element.
+ * @param toElement - The incoming element.
+ * @returns Stroke colour and width keyframe properties, or null if no interpolation is needed.
+ */
+export declare function buildStrokeInterpolationProps(fromElement: PptxElement, toElement: PptxElement): {
+    fromStroke: string;
+    toStroke: string;
+    fromWidth: number;
+    toWidth: number;
+} | null;
+/**
+ * Whether a matched pair needs a crossfade rather than a plain glide.
+ *
+ * PowerPoint's Morph dissolves a shape's appearance into its counterpart's
+ * while it travels. Without this, a deck whose slides are near-duplicates (the
+ * usual Morph authoring pattern: duplicate the slide, then restyle one shape)
+ * appeared to have no transition at all, because every persisting shape was
+ * painted in its FINAL state on frame 1 and only the handful of genuinely new
+ * or departing shapes faded (issue #131).
+ */
+export declare function morphPairNeedsCrossfade(fromElement: PptxElement, toElement: PptxElement): boolean;
+/**
+ * Whether a matched pair is INERT: identical appearance, and neither moved,
+ * resized, rotated nor flipped. Its ghost in the overlay is therefore a
+ * pixel-perfect stand-in for the live element underneath.
+ *
+ * Most of a Morph deck is inert - the authoring pattern is to duplicate a slide
+ * and restyle one thing, so 26 of 32 pairs on this deck's transitions are
+ * untouched - which makes what we do with them the dominant visual effect.
+ *
+ * A picture's SOURCE CROP counts here even though it moves no box: PowerPoint's
+ * "Scale Height"/"Scale Width" is an `a:srcRect` crop inside an unchanged frame,
+ * so a picture rescaled between two slides compares equal on every other axis
+ * and would otherwise be skipped entirely (issue #148).
+ */
+export declare function isInertMorphPair(fromElement: PptxElement, toElement: PptxElement): boolean;
+/**
+ * The outgoing shapes the transition overlay actually has to paint.
+ *
+ * The overlay is one flat layer ABOVE the live stage, so everything it paints
+ * hides whatever the incoming slide is doing underneath - including the shapes
+ * that only exist on the incoming slide and are dissolving IN. A ghost is
+ * therefore only worth that cost when it shows something the live stage cannot:
+ *
+ * - a shape with **no counterpart** has nowhere else to be drawn;
+ * - a pair whose **appearance changed** has to dissolve its old look away, and
+ *   the live element underneath is already wearing the new one;
+ * - a pair that merely moved (or did not move at all) is drawn identically by
+ *   its live counterpart, which travels the very same path - the ghost is a
+ *   duplicate, and an opaque one.
+ *
+ * The last kind is kept in exactly one case: when something painted BELOW it is
+ * itself dissolving, whatever is left out of the overlay would be seen through
+ * that dissolve instead of over it. That is the issue #131 case (a full-slide
+ * backdrop crossfading between two photos, with the wheel drawn over it) and it
+ * still gets a full set of ghosts. When the backdrop is UNCHANGED, as it is on
+ * every jump into this deck's detail slides, nothing needs protecting and the
+ * backdrop ghost is dropped - which is what stopped the incoming callouts from
+ * appearing at all until the overlay was torn down (issue #144).
+ *
+ * @param outgoingElements - The outgoing slide, flattened, in document order.
+ * @param pairs - The matched pairs; anything not in here has no counterpart.
+ * @returns The ids of the outgoing elements to paint, in the same order.
+ */
+export declare function resolveMorphGhostIds(outgoingElements: PptxElement[], pairs: MorphPair[]): Set<string>;
+/**
+ * Whether a crossfading pair's INCOMING half may fade in over its ghost.
+ *
+ * Fading both halves of a dissolve leaves the middle of the transition
+ * part-transparent, so a solid object goes see-through and the background shows
+ * through it - the reason the incoming half is otherwise pinned at its final
+ * opacity. That only matters when the element actually paints a body: a text
+ * box over `noFill` has nothing to hollow out, and pinning it means the new
+ * wording is at full strength from frame 1 while the old dissolves off it,
+ * which reads as the new text simply appearing rather than cross-dissolving.
+ *
+ * A GROUP owns no fill of its own, so the question has to be asked of its
+ * children: the wheel deck's centre panel is a group around an opaque disc, and
+ * fading it in while its ghost faded out turned the disc translucent for the
+ * middle of every hub-to-topic morph.
+ */
+/**
+ * Whether a matched pair's INCOMING half dissolves in rather than being painted
+ * at full strength from the first frame.
+ *
+ * Exported because the overlay has to know: a half that dissolves in can be
+ * lifted above a ghost that would otherwise hide it, and a half that is pinned
+ * cannot (lifting that one turns its dissolve into a cut). See
+ * `resolveMorphOverlayArrivals`.
+ *
+ * @param fromElement - The outgoing half of the pair.
+ * @param toElement - The incoming half.
+ * @param ghosted - Whether the overlay paints this pair's ghost at all.
+ */
+export declare function morphPairIncomingFadesIn(fromElement: PptxElement, toElement: PptxElement, ghosted?: boolean): boolean;
+/**
+ * Generate morph animation keyframes for matched element pairs.
+ *
+ * Produces CSS `@keyframes` blocks that animate position, size, rotation,
+ * opacity, fill colour, and stroke between matched element states.
+ *
+ * @param pairs - Matched element pairs from the morph matching pass.
+ * @param durationMs - Animation duration in milliseconds.
+ * @param _mode - Morph granularity mode (reserved for future use in this function).
+ * @param ghostIds - Outgoing ids the overlay will paint (see
+ *   {@link resolveMorphGhostIds}). A pair whose ghost is NOT painted has no
+ *   stand-in above it, so this half must stay visible. Defaults to "all", the
+ *   behaviour before the ghost set existed.
+ * @param zSwaps - Incoming id -> z-index journey for stacking-order swaps (see
+ *   {@link computeZOrderSwaps}). The track rides the same shorthand.
+ * @returns An array of animation style descriptors for each pair.
+ */
+export declare function generateMorphAnimations(pairs: MorphPair[], durationMs: number, _mode?: MorphMode, ghostIds?: ReadonlySet<string>, zSwaps?: ReadonlyMap<string, ZOrderJourney>): MorphAnimationStyle[];
+/**
+ * Generate the OUTGOING half of every matched pair.
+ *
+ * The returned animations target the outgoing element, which a binding paints
+ * in its transition overlay above the live stage. Each ghost travels the same
+ * path as its incoming counterpart - from its own geometry to the pair's final
+ * geometry - so the overlay stays a faithful, moving copy of the outgoing
+ * slide for the whole transition.
+ *
+ * A pair whose APPEARANCE changed fades to nothing on the way, dissolving into
+ * the counterpart rendered underneath. A pair that only moved keeps its opacity
+ * and simply lands on the incoming geometry, where the two are pixel-identical
+ * and the overlay can be torn down without a visible seam. Emitting the second
+ * kind matters because the overlay is a flat layer above the stage: a
+ * full-slide background that IS crossfading would otherwise hide every
+ * unchanged shape until it had faded, making them pop in mid-transition.
+ *
+ * Like every other morph animation, the frames are ELEMENT-LOCAL: they target
+ * the node that carries the element's static transform, restate that transform
+ * (see `generateMorphAnimations`), pivot on the element's own centre, and move
+ * by centre deltas. A binding must therefore attach these to the outgoing
+ * element's positioned container itself, never to a slide-sized wrapper.
+ *
+ * @param pairs - Matched pairs.
+ * @param durationMs - Animation duration in milliseconds.
+ * @param startIndex - Index offset for unique keyframe naming.
+ * @param ghostIds - Outgoing ids the overlay will paint (see
+ *   {@link resolveMorphGhostIds}); pairs outside it get no ghost. Defaults to
+ *   "all", the behaviour before the ghost set existed.
+ * @returns Ghost animation descriptors keyed by the OUTGOING element id.
+ */
+export declare function generateMorphGhostAnimations(pairs: MorphPair[], durationMs: number, startIndex: number, ghostIds?: ReadonlySet<string>): MorphAnimationStyle[];
+/**
+ * The target angle to animate TO so the element turns the short way round.
+ *
+ * CSS interpolates `rotate(a)` -> `rotate(b)` numerically, so a pair authored
+ * at 315deg and 0deg spins -315deg (almost a full turn anti-clockwise) when
+ * the shapes are only 45deg apart. PowerPoint always takes the shorter arc.
+ * Returns `fromDeg` plus the delta wrapped into (-180, 180], which is the same
+ * final orientation modulo 360 but the rotation a viewer expects: the issue
+ * #131 deck's wheel points its arrow at the selected wedge by rotating a ring
+ * in 45deg steps, so clicking the neighbouring wedge sent the arrow the long
+ * way around the dial.
+ *
+ * An exact half turn has no shorter arc, and PowerPoint's choice there is not
+ * a fixed sign: it turns CLOCKWISE when the shape starts anywhere in
+ * [90, 270) and ANTI-clockwise otherwise. Measured on PowerPoint 16 by
+ * sampling the rendered frames of a half-turn morph, both on the issue #131
+ * wheel (0->180 anti, 45->225 anti, 90->270 clock, 135->315 clock, 180->360
+ * clock, 270->90 anti) and on a synthetic two-slide deck built for the purpose
+ * (0->180 anti, 45->225 anti, 90->270 clock, 270->90 anti), which agrees on
+ * every case. Always taking +180 sent the wheel's arrow round the wrong side
+ * for the wedge diametrically opposite the one on screen, so one click in
+ * seven looked nothing like the others.
+ */
+export declare function shortestRotationTarget(fromDeg: number, toDeg: number): number;
+/**
+ * Generate fade-out animations for elements that only exist on the outgoing slide.
+ *
+ * The shape dissolves in the FIRST quarter of the morph rather than across the
+ * whole of it, and holds at zero from there (see
+ * {@link MORPH_FADE_OUT_END_PERCENT} for the frames that were measured). Fading
+ * it over the full duration left it half-visible at the midpoint, on top of an
+ * incoming replacement that was itself half-visible, so the middle of every
+ * morph read as a double exposure where PowerPoint shows a clean gap.
+ *
+ * Nothing scales: PowerPoint's dissolve keeps the box exactly where it is.
+ *
+ * @param elements - Unmatched elements from the outgoing slide.
+ * @param durationMs - Animation duration in milliseconds.
+ * @param startIndex - Index offset for unique keyframe naming.
+ * @returns An array of fade-out animation style descriptors.
+ */
+export declare function generateUnmatchedFadeOutAnimations(elements: PptxElement[], durationMs: number, startIndex: number): MorphAnimationStyle[];
+/**
+ * Generate fade-in animations for elements that only exist on the incoming slide.
+ *
+ * The shape stays completely invisible until the morph is
+ * {@link MORPH_FADE_IN_START_PERCENT}% through, then dissolves in on a
+ * decelerating curve. See that constant for the frames that were measured.
+ *
+ * Nothing scales: PowerPoint's dissolve keeps the box exactly where it is.
+ *
+ * @param elements - Unmatched elements from the incoming slide.
+ * @param durationMs - Animation duration in milliseconds.
+ * @param startIndex - Index offset for unique keyframe naming.
+ * @returns An array of fade-in animation style descriptors.
+ */
+export declare function generateUnmatchedFadeInAnimations(elements: PptxElement[], durationMs: number, startIndex: number): MorphAnimationStyle[];
+/**
+ * Generate text morph animations for a matched element pair with text content.
+ *
+ * Produces per-token (word or character) CSS keyframes that animate
+ * position, font size, color, and opacity of individual text units.
+ *
+ * @param pair - The matched element pair containing text.
+ * @param durationMs - Animation duration in milliseconds.
+ * @param mode - Whether to animate by "word" or "character".
+ * @param pairIndex - Index of this pair for unique keyframe naming.
+ * @returns An array of per-token animation style descriptors.
+ */
+export declare function generateTextMorphAnimations(pair: MorphPair, durationMs: number, mode: 'word' | 'character', pairIndex: number): MorphAnimationStyle[];
+/**
+ * Generate a complete morph transition animation set, including:
+ * - Matched element morphs (position, size, rotation, opacity, color, stroke)
+ * - Unmatched element fade-out / fade-in
+ * - Optional text morph (word or character level)
+ *
+ * @param fromSlide - The outgoing slide.
+ * @param toSlide - The incoming slide.
+ * @param durationMs - Animation duration in milliseconds.
+ * @param mode - Morph granularity: "object", "word", or "character".
+ * @param zIndexBase - The z-index the live stage gives the incoming slide's
+ *   first top-level element (see {@link computeZOrderSwaps}); a binding that
+ *   paints master/layout shapes beneath the slide passes their count.
+ * @returns A complete array of animation style descriptors for the transition.
+ */
+export declare function generateFullMorphTransition(fromSlide: PptxSlide, toSlide: PptxSlide, durationMs: number, mode?: MorphMode, zIndexBase?: number): MorphAnimationStyle[];
+//# sourceMappingURL=morph-animation.d.ts.map

package/dist/pptx/render/morph-animation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"morph-animation.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/morph-animation.ts"],"names":[],"mappings":"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"}

package/dist/pptx/render/morph-color.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Colour parsing and interpolation utilities for morph transitions.
+ *
+ * Provides functions to parse hex colour strings into RGBA components,
+ * linearly interpolate between two colours, and convert RGBA back to hex.
+ *
+ * @module render/morph-color
+ */
+import type { RgbaColor } from './morph-types.js';
+/**
+ * Parse a hex colour string (3, 4, 6, or 8 digits) into RGBA components.
+ * Returns null for invalid or missing inputs.
+ *
+ * @param hex - A CSS hex colour string, optionally prefixed with `#`.
+ * @returns Parsed RGBA components or null if the input is invalid.
+ */
+export declare function parseHexColor(hex: string | undefined): RgbaColor | null;
+/**
+ * Linearly interpolate between two RGBA colours at parameter t (0-1).
+ * Returns a CSS rgba() string.
+ *
+ * @param from - The starting colour.
+ * @param to - The ending colour.
+ * @param t - Interpolation parameter, clamped to [0, 1].
+ * @returns A CSS `rgba(r, g, b, a)` string.
+ */
+export declare function lerpColor(from: RgbaColor, to: RgbaColor, t: number): string;
+/**
+ * Convert an RgbaColor back to a hex string (6-digit or 8-digit if alpha < 1).
+ *
+ * @param c - The RGBA colour to convert.
+ * @returns A hex colour string prefixed with `#`.
+ */
+export declare function rgbaToHex(c: RgbaColor): string;
+//# sourceMappingURL=morph-color.d.ts.map

package/dist/pptx/render/morph-color.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"morph-color.d.ts","sourceRoot":"","sources":["../../../src/pptx/render/morph-color.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAM/C;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,IAAI,CAmCvE;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAO3E;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,SAAS,GAAG,MAAM,CAW9C"}