@expofp/renderer 3.28.0 → 3.28.2

package/dist/external/external-camera.d.ts

@@ -7,7 +7,8 @@ import { type Camera } from 'three';
  * (P′, V′) pairs multiply to the same M — but the *rigid* split is the one three's `Camera` class
  * assumes for `getWorldDirection`, frustum culling, raycasting and the lighting that reads the
  * camera's world matrix. Any extra scale or skew in M (mercator-unit conversion, say) ends up
- * absorbed into P, where it breaks none of those.
+ * absorbed into P, where it breaks none of those — a *reflection* being the exception, which is why
+ * the host's world is mirrored into three's before any of this runs.
  * @param camera - The external camera to publish onto; `matrixAutoUpdate` and
  *   `matrixWorldAutoUpdate` must be off, since everything here is written by hand.
  * @param mainMatrix - The combined matrix mapping world space directly to clip space, sixteen

package/dist/external/external-camera.js

@@ -1,4 +1,5 @@
 import { Matrix3, Matrix4, Vector3 } from 'three';
+import { HANDEDNESS_FLIP } from '../space/Space';
 /**
  * Decomposes the host's combined world-to-clip matrix into a rigid view matrix and a projection
  * matrix, publishing all four matrices (and their inverses) on the camera.
@@ -7,14 +8,19 @@ import { Matrix3, Matrix4, Vector3 } from 'three';
  * (P′, V′) pairs multiply to the same M — but the *rigid* split is the one three's `Camera` class
  * assumes for `getWorldDirection`, frustum culling, raycasting and the lighting that reads the
  * camera's world matrix. Any extra scale or skew in M (mercator-unit conversion, say) ends up
- * absorbed into P, where it breaks none of those.
+ * absorbed into P, where it breaks none of those — a *reflection* being the exception, which is why
+ * the host's world is mirrored into three's before any of this runs.
  * @param camera - The external camera to publish onto; `matrixAutoUpdate` and
  *   `matrixWorldAutoUpdate` must be off, since everything here is written by hand.
  * @param mainMatrix - The combined matrix mapping world space directly to clip space, sixteen
  *   elements column-major.
  */
 export function setExternalCameraProjection(camera, mainMatrix) {
-    const M = _main.fromArray(mainMatrix);
+    // The host's matrix reads the host's world; the space mirrors that world into three's, so undo
+    // the mirror here. The two cancel: the plan lands exactly where the host put it, and what is left
+    // is a plan → world matrix that reverses orientation, which is the whole point — see
+    // {@link HANDEDNESS_FLIP}.
+    const M = _main.fromArray(mainMatrix).multiply(HANDEDNESS_FLIP);
     const e = M.elements; // column-major storage: M[row, col] = e[row + 4 * col]
     // Step 1: camera world position c.
     //

package/dist/objects/Lighting.js

@@ -47,8 +47,8 @@ export function Lighting() {
             .setFromMatrixColumn(state.camera.matrixWorld, 2)
             .transformDirection(space.matrixInverse);
         // The plan's own up axis, as a point whose world position lands back on it — which is what three
-        // reads a hemisphere light's sky axis from. Under the viewbox fit that axis is world -z, the
-        // side the camera is on; under a caller's own transform it is wherever that transform puts it.
+        // reads a hemisphere light's sky axis from. It is world -z either way, the side the camera is
+        // on: every path into world space ends with handedness flip.
         //
         // Computed here rather than memoized against the space because the space is refitted in place
         // and so never changes identity — and it is four vector operations on a frame that was going to

package/dist/space/Space.d.ts

@@ -22,8 +22,8 @@ export type PlanPointLike = PointLike & {
     __space: 'plan';
 };
 /**
- * A point in **world space**: three's own space, the one the camera is placed in. World z grows *away*
- * from the viewer under the viewbox fit, which is why {@link Space} mirrors it.
+ * A point in **world space**: three's own space, the one the camera is placed in. Right-handed, so
+ * world z grows *away* from the viewer — which is why {@link Space} mirrors the plan's z.
  *
  * World and NDC points are three's vectors instead of `@expofp/geometry`: neither is part of the
  * public API, and both exist only to be multiplied by matrices and unprojected through cameras.
@@ -81,9 +81,9 @@ export interface SpaceOptions {
      */
     dpr: number;
     /**
-     * A caller-supplied plan → world matrix, 16 elements column-major. When present it *replaces* the
-     * viewbox fit rather than composing with it, and carries its own z convention — the maplibre
-     * transform scales z upward where the fit mirrors it.
+     * A caller-supplied plan → world matrix, 16 elements column-major, in the host's own coordinates.
+     * When present it *replaces* the viewbox fit rather than composing with it; the z mirror both
+     * paths end with is not the caller's to supply (see {@link HANDEDNESS_FLIP}).
      */
     staticTransform?: number[];
 }
@@ -97,13 +97,16 @@ export declare function useSpace(): Space;
  * conversions that ride on it.
  *
  * The mapping is one matrix. Without a `staticTransform` it is the **viewbox fit**: centre the
- * viewbox on the world origin and scale it uniformly to best fill the drawing buffer, mirroring z so a positive
- * elevation lands nearer the camera. That fit is what makes one world unit one device pixel when
- * the plan exactly fills the canvas, which in turn is what lets the camera's zoom math be written
- * without reference to the scene at all — see {@link Camera}.
+ * viewbox on the world origin and scale it uniformly to best fill the drawing buffer. That fit is
+ * what makes one world unit one device pixel when the plan exactly fills the canvas, which in turn
+ * is what lets the camera's zoom math be written without reference to the scene at all — see
+ * {@link Camera}.
  *
  * With a `staticTransform` the matrix is whatever the caller supplied, and the fit is not computed:
- * a host like maplibre places the plan itself, in its own space and with its own z convention.
+ * a host like maplibre places the plan itself, in its own space.
+ *
+ * Either way the matrix ends with {@link HANDEDNESS_FLIP}, which is what makes the space three's
+ * rather than the plan's or a host's — a positive elevation then lands nearer the camera.
  *
  * **Stable for the scene's lifetime.** A resize does not build a new space — {@link Scene} refits
  * this one in place — so every holder reads the current fit through the same object and none of
@@ -285,4 +288,23 @@ export declare const SpaceContext: import("react").Context<Space>;
  * @param camera - The camera to cast from.
  */
 export declare function castRay(raycaster: Raycaster, ndc: NDCPointLike, camera: Camera): void;
+/**
+ * The last step of both paths into world space: mirror z.
+ *
+ * Plan space is left-handed — x right, y **down**, z up — where three's world is right-handed, so
+ * one axis has to flip and z is it: the plan's up is world `-z`, the side the camera is on.
+ *
+ * The flip belongs in the plan → world matrix and nowhere else. three reads a face's winding from
+ * that matrix's determinant alone (`matrixWorld.determinantAffine() < 0`) and never from the
+ * projection, so a reflection anywhere else is invisible to it: every `DoubleSide` lit surface
+ * negates its normal and shades from behind.
+ *
+ * **Assumes a host's world shares the plan's handedness**, which mercator does — x east, y south,
+ * z up — resolving the clash inside its own projection instead (`MercatorTransform._calcMatrices`
+ * scales by `[1, -1, 1]`). So the same flip serves both paths, and external mode undoes it on the
+ * host's own matrix (`setExternalCameraProjection`). A host with a right-handed world would
+ * need it skipped on both — a `leftHandedWorld` flag on the external contract is where that choice
+ * would go.
+ */
+export declare const HANDEDNESS_FLIP: Matrix4;
 //# sourceMappingURL=Space.d.ts.map

package/dist/space/Space.js

@@ -17,13 +17,16 @@ export function useSpace() {
  * conversions that ride on it.
  *
  * The mapping is one matrix. Without a `staticTransform` it is the **viewbox fit**: centre the
- * viewbox on the world origin and scale it uniformly to best fill the drawing buffer, mirroring z so a positive
- * elevation lands nearer the camera. That fit is what makes one world unit one device pixel when
- * the plan exactly fills the canvas, which in turn is what lets the camera's zoom math be written
- * without reference to the scene at all — see {@link Camera}.
+ * viewbox on the world origin and scale it uniformly to best fill the drawing buffer. That fit is
+ * what makes one world unit one device pixel when the plan exactly fills the canvas, which in turn
+ * is what lets the camera's zoom math be written without reference to the scene at all — see
+ * {@link Camera}.
  *
  * With a `staticTransform` the matrix is whatever the caller supplied, and the fit is not computed:
- * a host like maplibre places the plan itself, in its own space and with its own z convention.
+ * a host like maplibre places the plan itself, in its own space.
+ *
+ * Either way the matrix ends with {@link HANDEDNESS_FLIP}, which is what makes the space three's
+ * rather than the plan's or a host's — a positive elevation then lands nearer the camera.
  *
  * **Stable for the scene's lifetime.** A resize does not build a new space — {@link Scene} refits
  * this one in place — so every holder reads the current fit through the same object and none of
@@ -91,8 +94,10 @@ export class Space {
             // product to come out as scale∘translate — the order the imperative renderer built it in.
             this.matrix
                 .makeTranslation(-centerX * fit, -centerY * fit, 0)
-                .scale(new Vector3(fit, fit, -fit));
+                .scale(new Vector3(fit, fit, fit));
         }
+        // Both paths land in a host's space or ours; this is what makes either one three's.
+        this.matrix.premultiply(HANDEDNESS_FLIP);
         this.matrixInverse.copy(this.matrix).invert();
         this._scale = Math.sqrt(axisLength(this.matrix, 0) * axisLength(this.matrix, 1));
     }
@@ -306,6 +311,25 @@ export function castRay(raycaster, ndc, camera) {
 function axisLength(matrix, axis) {
     return new Vector3().setFromMatrixColumn(matrix, axis).length();
 }
+/**
+ * The last step of both paths into world space: mirror z.
+ *
+ * Plan space is left-handed — x right, y **down**, z up — where three's world is right-handed, so
+ * one axis has to flip and z is it: the plan's up is world `-z`, the side the camera is on.
+ *
+ * The flip belongs in the plan → world matrix and nowhere else. three reads a face's winding from
+ * that matrix's determinant alone (`matrixWorld.determinantAffine() < 0`) and never from the
+ * projection, so a reflection anywhere else is invisible to it: every `DoubleSide` lit surface
+ * negates its normal and shades from behind.
+ *
+ * **Assumes a host's world shares the plan's handedness**, which mercator does — x east, y south,
+ * z up — resolving the clash inside its own projection instead (`MercatorTransform._calcMatrices`
+ * scales by `[1, -1, 1]`). So the same flip serves both paths, and external mode undoes it on the
+ * host's own matrix (`setExternalCameraProjection`). A host with a right-handed world would
+ * need it skipped on both — a `leftHandedWorld` flag on the external contract is where that choice
+ * would go.
+ */
+export const HANDEDNESS_FLIP = new Matrix4().makeScale(1, 1, -1);
 /** The plan's own plane in plan space, which every pointer position is reported on. */
 const PLAN_PLANE = new Plane(new Vector3(0, 0, 1), 0);
 /**

package/dist/types/defs.d.ts

@@ -12,7 +12,11 @@ export interface SceneDef {
     background?: ColorInput;
     /** SVG viewbox */
     viewbox: Box;
-    /** Static transform matrix */
+    /**
+     * Static transform matrix: plan → the host's world, in place of the viewbox fit and in the host's
+     * own coordinates. Assumed to share plan space's handedness — see `HANDEDNESS_FLIP` in Space.ts, which the
+     * renderer adds on top to reach three's.
+     */
     staticTransform?: number[];
 }
 /** Shared properties for all renderable defs */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expofp/renderer",
-  "version": "3.28.0",
+  "version": "3.28.2",
   "repository": {
     "type": "git",
     "url": "https://github.com/expofp/efp-app.git",
@@ -42,7 +42,7 @@
     "troika-three-text": "^0.52.5",
     "tslib": "^2.3.0",
     "webgl-memory": "^1.1.3",
-    "@expofp/geometry": "3.28.0"
+    "@expofp/geometry": "3.28.2"
   },
   "devDependencies": {
     "@react-three/test-renderer": "^9.1.0",