@buley/hexgrid-3d 3.6.1 → 3.6.2

package/README.md

@@ -2,6 +2,10 @@
 
 A reusable 3D hexagonal grid visualization component for displaying content in an immersive spherical layout.
 
+## Documentation
+
+- [Territory README](./src/territory/README.md)
+
 ## Features
 
 - **3D Hexagonal Grid Layout** - Spherical projection with customizable curvature
@@ -9,7 +13,7 @@ A reusable 3D hexagonal grid visualization component for displaying content in a
 - **Image Texture Mapping** - Automatic texture loading and caching
 - **Real-time Statistics** - Live telemetry and performance metrics
 - **Narration System** - Play-by-play commentary overlay
-- **Territory Globe** - Deterministic wrapped globe topology for paid root claims, recursive subdivision, and delegated territory overlays
+- **Territory Globe** - Deterministic wrapped globe topology for paid seed claims, recursive subdivision, delegated territory overlays, and conquest-driven occupation
 - **Web Worker Rendering** - High-performance offloaded calculations
 - **Multi-Input Support** - Touch gestures, mouse, and keyboard controls
 - **Responsive Design** - Adapts to mobile and desktop viewports
@@ -155,7 +159,7 @@ Wrapped React Three Fiber surface for territory-aware hex cells on a sphere.
 | Prop | Type | Description |
 | ---- | ---- | ----------- |
 | `cells` | `HexTerritoryCell[]` | Deterministic canonical globe cells |
-| `claimedCellIds` | `Iterable<string>` | Claimed sovereign roots |
+| `claimedCellIds` | `Iterable<string>` | Occupied or currently held roots |
 | `lockedCellIds` | `Iterable<string>` | Visible but unclaimable roots |
 | `colorsByCellId` | `Record<string, string>` | Per-root color overrides |
 | `selectedCellId` | `string` | Active root highlight |
@@ -173,6 +177,9 @@ The package now exports territory-specific helpers:
 - `CanonicalHexGlobeConfig`
 - `HexTerritoryBoard`
 - `HexTerritoryCell`
+- `HexTerritoryAffiliation`
+- `HexTerritoryAllianceBinding`
+- `HexTerritoryRallyMarker`
 - `HexNodePath`
 - `HexwarEmbedRef`
 - `HexTerritoryTickState`

package/dist/components/GameSphere.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GameSphere.d.ts","sourceRoot":"","sources":["../../src/components/GameSphere.tsx"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAkD,MAAM,OAAO,CAAC;AAEvE,OAAO,KAAK,EACV,eAAe,EAKhB,MAAM,UAAU,CAAC;AAqOlB,eAAO,MAAM,UAAU,EAAE,KAAK,CAAC,EAAE,CAAC,eAAe,CAwjBhD,CAAC;AAGF,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"GameSphere.d.ts","sourceRoot":"","sources":["../../src/components/GameSphere.tsx"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAkD,MAAM,OAAO,CAAC;AAEvE,OAAO,KAAK,EACV,eAAe,EAKhB,MAAM,UAAU,CAAC;AA+OlB,eAAO,MAAM,UAAU,EAAE,KAAK,CAAC,EAAE,CAAC,eAAe,CAyjBhD,CAAC;AAGF,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/components/GameSphere.js

@@ -65,6 +65,15 @@ function getHighlightColor(highlight) {
         return '#000000';
     return HIGHLIGHT_COLORS[highlight] ?? highlight; // If it's a custom color string, use directly
 }
+function normalizeReactNode(node) {
+    if (typeof node === 'bigint') {
+        return node.toString();
+    }
+    if (Array.isArray(node)) {
+        return node.map(normalizeReactNode);
+    }
+    return node;
+}
 function createOrbitControls(camera, canvas, initialDistance) {
     const state = {
         theta: 0,
@@ -174,6 +183,7 @@ function getCellUnderMouse(event, canvas, camera, cellMeshes) {
 // GameSphere Component
 // ---------------------------------------------------------------------------
 export const GameSphere = ({ cellGameState, config: configProp, events, width = '100%', height = '100%', className, style, rendererRef, sceneRef, paused = false, children, }) => {
+    const overlayChildren = normalizeReactNode(children);
     const containerRef = useRef(null);
     const canvasRef = useRef(null);
     const rendererInternalRef = useRef(null);
@@ -609,14 +619,14 @@ export const GameSphere = ({ cellGameState, config: configProp, events, width =
                     height: '100%',
                     display: 'block',
                     touchAction: 'none', // Prevent browser gesture interference
-                } }), children && (_jsx("div", { style: {
+                } }), overlayChildren != null ? (_jsx("div", { style: {
                     position: 'absolute',
                     top: 0,
                     left: 0,
                     right: 0,
                     bottom: 0,
                     pointerEvents: 'none',
-                }, children: _jsx("div", { style: { pointerEvents: 'auto' }, children: children }) }))] }));
+                }, children: _jsx("div", { style: { pointerEvents: 'auto' }, children: overlayChildren }) })) : null] }));
 };
 // Re-export GeodesicHexGrid for game consumers
 export { GeodesicHexGrid } from '../math/HexCoordinates';

package/dist/components/HexGrid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HexGrid.d.ts","sourceRoot":"","sources":["../../src/components/HexGrid.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA4D,MAAM,OAAO,CAAA;AAYhF,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,UAAU,CAAA;AAI/C,YAAY,EAAE,KAAK,EAAE,CAAA;AAWrB,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,OAAO;IAEvC,KAAK,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAA;IACrB,MAAM,CAAC,EAAE,KAAK,EAAE,CAAA;IAGhB,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,IAAI,CAAA;IACzC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAA;IAEnC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAAA;IAC9C,mBAAmB,CAAC,EAAE,CAAC,WAAW,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,KAAK,IAAI,CAAA;IAC5G,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,0BAA0B,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACpD,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,KAAK,CAAA;IACZ,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC9B,aAAa,EAAE,MAAM,CAAA;IACrB,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IAC1C,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;CACf;AAoLD,eAAO,MAAM,OAAO,GAAI,CAAC,GAAG,OAAO,EAAE,iMAalC,YAAY,CAAC,CAAC,CAAC,4CA4xIjB,CAAA;AAk7DD,eAAe,OAAO,CAAC"}
+{"version":3,"file":"HexGrid.d.ts","sourceRoot":"","sources":["../../src/components/HexGrid.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA4D,MAAM,OAAO,CAAA;AAYhF,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,UAAU,CAAA;AAU/C,YAAY,EAAE,KAAK,EAAE,CAAA;AAWrB,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,OAAO;IAEvC,KAAK,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAA;IACrB,MAAM,CAAC,EAAE,KAAK,EAAE,CAAA;IAGhB,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,IAAI,CAAA;IACzC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAA;IAEnC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAAA;IAC9C,mBAAmB,CAAC,EAAE,CAAC,WAAW,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,KAAK,IAAI,CAAA;IAC5G,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,0BAA0B,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACpD,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,KAAK,CAAA;IACZ,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC9B,aAAa,EAAE,MAAM,CAAA;IACrB,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IAC1C,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;CACf;AAsLD,eAAO,MAAM,OAAO,GAAI,CAAC,GAAG,OAAO,EAAE,iMAalC,YAAY,CAAC,CAAC,CAAC,4CAkzIjB,CAAA;AAk2DD,eAAe,OAAO,CAAC"}

package/dist/components/HexGrid.js

@@ -10,6 +10,7 @@ import { setCustomAccentColor, clearCustomAccentColor, getCurrentAccentHex, getA
 import { decodeHTMLEntities } from '../lib/html-utils';
 import { getProxiedImageUrl } from '../utils/image-utils';
 import { gridItemToPhoto } from '../compat';
+import { generateScreenSpaceSphericalHexGrid, getNormalizedScreenSpaceSphericalCoordinates, } from '../workers/hexgrid-math';
 // Fallback no-op logger at module scope (unused - component-level dlog is used instead)
 // Kept for backward compatibility but renamed to avoid shadowing confusion
 const noopLog = (..._args) => { };
@@ -1118,7 +1119,7 @@ export const HexGrid = ({ items, photos: photosProp, onItemClick, onHexClick, sp
         if (hasSignificantCurvature) {
             // Use spherical hexagonal grid for compact 3D packing
             const densityMultiplier = workerDebug.sphericalDensity ?? 1.4;
-            const result = generateSphericalHexGrid(totalHexagons, screenWidth, screenHeight, curveUDeg, curveVDeg, densityMultiplier, effectiveHexRadius // Pass the actual hex radius so spacing matches drawing
+            const result = generateScreenSpaceSphericalHexGrid(totalHexagons, screenWidth, screenHeight, curveUDeg, curveVDeg, densityMultiplier, effectiveHexRadius // Pass the actual hex radius so spacing matches drawing
             );
             gridMetadataRef.current = result.metadata;
             return result.positions;
@@ -1304,8 +1305,15 @@ export const HexGrid = ({ items, photos: photosProp, onItemClick, onHexClick, sp
         const minY = gridBounds.minY;
         const w = gridBounds.width;
         const h = gridBounds.height;
-        const u = (x - minX) / Math.max(1e-6, w);
-        const v = (y - minY) / Math.max(1e-6, h);
+        const currentGridMetadata = gridMetadataRef.current;
+        const sphericalGridMetadata = currentGridMetadata.isSpherical
+            ? currentGridMetadata
+            : null;
+        const sphericalCoordinates = sphericalGridMetadata && typeof idx === 'number'
+            ? getNormalizedScreenSpaceSphericalCoordinates(idx, sphericalGridMetadata, curveUDeg)
+            : null;
+        const u = sphericalCoordinates?.u ?? (x - minX) / Math.max(1e-6, w);
+        const v = sphericalCoordinates?.v ?? (y - minY) / Math.max(1e-6, h);
         // Clear, explicit spherical mapping
         const deg2rad = Math.PI / 180;
         // longitude: center u=0.5 -> lon=0
@@ -1432,14 +1440,17 @@ export const HexGrid = ({ items, photos: photosProp, onItemClick, onHexClick, sp
             try {
                 if (typeof idx === 'number' && Array.isArray(hexPositions) && hexPositions.length > idx) {
                     // Find neighbor indices using grid geometry (pass isSpherical flag)
-                    const isSpherical = gridMetadataRef.current?.isSpherical ?? false;
+                    const isSpherical = sphericalGridMetadata !== null;
                     const neighborIndices = getNeighbors(idx, hexPositions, drawnHexRadius, isSpherical);
                     const projNeighbors = [];
                     for (const ni of neighborIndices) {
                         const np = hexPositions[ni];
                         // Map neighbor pixel to lon/lat using same gridBounds mapping
-                        const nu = (np[0] - minX) / Math.max(1e-6, w);
-                        const nv = (np[1] - minY) / Math.max(1e-6, h);
+                        const neighborCoordinates = sphericalGridMetadata
+                            ? getNormalizedScreenSpaceSphericalCoordinates(ni, sphericalGridMetadata, curveUDeg)
+                            : null;
+                        const nu = neighborCoordinates?.u ?? (np[0] - minX) / Math.max(1e-6, w);
+                        const nv = neighborCoordinates?.v ?? (np[1] - minY) / Math.max(1e-6, h);
                         const nlon = (nu - 0.5) * (curveUDeg * deg2rad);
                         const nlat = (nv - 0.5) * (curveVDeg * deg2rad);
                         const cosLatN = Math.cos(nlat);
@@ -2855,7 +2866,7 @@ export const HexGrid = ({ items, photos: photosProp, onItemClick, onHexClick, sp
             // Use the same projection helper as hit-tests so angles/positions match exactly.
             if (dbg?.renderBothSides) {
                 try {
-                    const anti = mapAndProject(hexPositions[index], true);
+                    const anti = mapAndProject(hexPositions[index], true, index);
                     const antiScale = anti.scale || 1;
                     const antiAngle = anti.angle || 0;
                     drawHexagon(ctx, [anti.x, anti.y, 0], drawnHexRadius * antiScale, infection, textures, index, blankCount, smoothed, sheenProgress, sheenIntensity, sheenEnabled, scratchEnabled, scratchCanvasRef.current, seamInset, pulseProgress, false, true, antiAngle);
@@ -3295,7 +3306,7 @@ export const HexGrid = ({ items, photos: photosProp, onItemClick, onHexClick, sp
             // If configured, also check the antipodal (inside) projection
             if (workerDebug.renderBothSides) {
                 try {
-                    const anti = mapAndProject(hexPositions[i], true);
+                    const anti = mapAndProject(hexPositions[i], true, i);
                     const antiScale = anti.scale || 1;
                     const antiRadius = drawnHexRadius * antiScale;
                     const antiAngle = anti.angle || 0;
@@ -3420,7 +3431,7 @@ export const HexGrid = ({ items, photos: photosProp, onItemClick, onHexClick, sp
                         }
                         if (workerDebug.renderBothSides) {
                             try {
-                                const anti = mapAndProject(hexPositions[i], true);
+                                const anti = mapAndProject(hexPositions[i], true, i);
                                 const antiRadius = drawnHexRadius * (anti.scale || 1);
                                 const antiAngle = anti.angle || 0;
                                 if (isPointInHexagon(x, y, [anti.x, anti.y, 0], antiRadius, antiAngle)) {
@@ -4359,62 +4370,6 @@ function generatePixelScreen(cols, rows, hexRadius) {
     // No centering needed for canvas - positions are already in canvas coordinates
     return positions;
 }
-// Generate hexagons directly in spherical space for compact 3D packing
-function generateSphericalHexGrid(targetCount, screenWidth, screenHeight, curveUDeg, curveVDeg, densityMultiplier = 1.4, hexRadius // The actual hex radius used for drawing
-) {
-    const positions = [];
-    const sqrt3 = Math.sqrt(3);
-    // Calculate grid dimensions based on hex radius and screen size
-    // Use the SAME spacing math as the flat grid for consistency
-    const baseHorizontalSpacing = sqrt3 * hexRadius;
-    const baseVerticalSpacing = 1.5 * hexRadius;
-    // Calculate how many hexes fit based on actual hex size
-    const baseCols = Math.ceil(screenWidth / baseHorizontalSpacing);
-    const baseRows = Math.ceil(screenHeight / baseVerticalSpacing);
-    // Apply density multiplier to get more/fewer hexes
-    const cols = Math.ceil(baseCols * Math.sqrt(densityMultiplier));
-    const rows = Math.ceil(baseRows * Math.sqrt(densityMultiplier));
-    const deg2rad = Math.PI / 180;
-    // Use the same spacing for generation (already calculated above)
-    const verticalSpacing = baseVerticalSpacing;
-    const horizontalSpacing = baseHorizontalSpacing;
-    // Generate positions directly in lat/lon space with proper hexagonal offsets
-    // Apply adaptive density based on latitude to naturally handle pole convergence
-    for (let row = 0; row < rows; row++) {
-        // Use vertical spacing for proper hex packing
-        const y = row * verticalSpacing;
-        // Calculate latitude for this row to determine if we're near a pole
-        const v = y / Math.max(1, screenHeight);
-        // Clamp v to [0, 1] range
-        if (v < 0 || v > 1)
-            continue;
-        const lat = (v - 0.5) * (curveVDeg * deg2rad);
-        // Natural pole density reduction: fewer hexes per row near poles
-        // This is more physically accurate for spherical surfaces
-        const latFactor = Math.max(0.3, Math.abs(Math.cos(lat)));
-        const effectiveColsForRow = Math.max(3, Math.round(cols * latFactor));
-        // CRITICAL: Calculate hex offset based on the base spacing (not per-row spacing)
-        // This ensures proper nesting at all latitudes
-        const hexOffsetX = horizontalSpacing * 0.5;
-        for (let col = 0; col < effectiveColsForRow; col++) {
-            // Start with evenly distributed positions in screen space
-            let x = col * horizontalSpacing;
-            // Apply hexagonal offset for odd rows in SCREEN SPACE
-            // This ensures hexagons nestle properly between rows below
-            if (row % 2 !== 0) {
-                x += hexOffsetX;
-            }
-            // Wrap/clamp x to screen bounds
-            // For full 360° wrap, hexes can exceed screen width and will wrap in projection
-            // For partial coverage, clamp to screen
-            if (Math.abs(curveUDeg) < 359) {
-                x = Math.max(0, Math.min(screenWidth, x));
-            }
-            positions.push([x, y, 0]);
-        }
-    }
-    return { positions, metadata: { cols, rows, isSpherical: true } };
-}
 function initializeInfectionSystem(positions, photos, hexRadius, initialClusterMax = 3, loggerParam = logger, isSpherical = false) {
     const logger = loggerParam;
     // GUARD: Validate inputs to prevent creating invalid infections

package/dist/territory/HexTerritoryGlobe.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { type HexTerritoryCell } from './globe';
+import { type HexTerritoryAffiliation, type HexTerritoryAllianceBinding, type HexTerritoryCell, type HexTerritoryRallyMarker } from './globe';
 export interface HexTerritoryGlobeProps {
     cells: HexTerritoryCell[];
     selectedCellId?: string | null;
@@ -7,9 +7,12 @@ export interface HexTerritoryGlobeProps {
     claimedCellIds?: Iterable<string>;
     lockedCellIds?: Iterable<string>;
     colorsByCellId?: Record<string, string>;
+    affiliationByCellId?: Record<string, HexTerritoryAffiliation>;
+    allianceBindings?: HexTerritoryAllianceBinding[];
+    rallyMarkers?: HexTerritoryRallyMarker[];
     tileRadius?: number;
     onSelectCell?: (cell: HexTerritoryCell) => void;
     onHoverCell?: (cell: HexTerritoryCell | null) => void;
 }
-export declare function HexTerritoryGlobe({ cells, selectedCellId, hoverCellId, claimedCellIds, lockedCellIds, colorsByCellId, tileRadius, onSelectCell, onHoverCell, }: HexTerritoryGlobeProps): React.JSX.Element;
+export declare function HexTerritoryGlobe({ cells, selectedCellId, hoverCellId, claimedCellIds, lockedCellIds, colorsByCellId, affiliationByCellId, allianceBindings, rallyMarkers, tileRadius, onSelectCell, onHoverCell, }: HexTerritoryGlobeProps): React.JSX.Element;
 //# sourceMappingURL=HexTerritoryGlobe.d.ts.map

package/dist/territory/HexTerritoryGlobe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HexTerritoryGlobe.d.ts","sourceRoot":"","sources":["../../src/territory/HexTerritoryGlobe.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAqC,MAAM,OAAO,CAAC;AAG1D,OAAO,EAAgC,KAAK,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAE9E,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,cAAc,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAClC,aAAa,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACjC,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAChD,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI,KAAK,IAAI,CAAC;CACvD;AAMD,wBAAgB,iBAAiB,CAAC,EAChC,KAAK,EACL,cAAqB,EACrB,WAAkB,EAClB,cAAc,EACd,aAAa,EACb,cAAc,EACd,UAAU,EACV,YAAY,EACZ,WAAW,GACZ,EAAE,sBAAsB,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CA6F5C"}
+{"version":3,"file":"HexTerritoryGlobe.d.ts","sourceRoot":"","sources":["../../src/territory/HexTerritoryGlobe.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAqC,MAAM,OAAO,CAAC;AAG1D,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,2BAA2B,EAChC,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC7B,MAAM,SAAS,CAAC;AAEjB,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,cAAc,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAClC,aAAa,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACjC,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC;IAC9D,gBAAgB,CAAC,EAAE,2BAA2B,EAAE,CAAC;IACjD,YAAY,CAAC,EAAE,uBAAuB,EAAE,CAAC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAChD,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI,KAAK,IAAI,CAAC;CACvD;AAMD,wBAAgB,iBAAiB,CAAC,EAChC,KAAK,EACL,cAAqB,EACrB,WAAkB,EAClB,cAAc,EACd,aAAa,EACb,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EAChB,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,WAAW,GACZ,EAAE,sBAAsB,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAyJ5C"}

package/dist/territory/HexTerritoryGlobe.js

@@ -1,16 +1,17 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useEffect, useMemo, useRef } from 'react';
 import { Color, CircleGeometry, Matrix4, Object3D } from 'three';
-import { calculateAutoTileRadiusByRow } from './globe';
+import { calculateAutoTileRadiusByRow, } from './globe';
 function asSet(values) {
     return values ? new Set(values) : new Set();
 }
-export function HexTerritoryGlobe({ cells, selectedCellId = null, hoverCellId = null, claimedCellIds, lockedCellIds, colorsByCellId, tileRadius, onSelectCell, onHoverCell, }) {
+export function HexTerritoryGlobe({ cells, selectedCellId = null, hoverCellId = null, claimedCellIds, lockedCellIds, colorsByCellId, affiliationByCellId, allianceBindings, rallyMarkers, tileRadius, onSelectCell, onHoverCell, }) {
     const meshRef = useRef(null);
     const geometry = useMemo(() => new CircleGeometry(1, 6), []);
     const workingObject = useMemo(() => new Object3D(), []);
     const claimed = useMemo(() => asSet(claimedCellIds), [claimedCellIds]);
     const locked = useMemo(() => asSet(lockedCellIds), [lockedCellIds]);
+    const cellById = useMemo(() => new Map(cells.map((cell) => [cell.cellId, cell])), [cells]);
     const autoTileRadiusByRow = useMemo(() => tileRadius === undefined ? calculateAutoTileRadiusByRow(cells) : undefined, [cells, tileRadius]);
     useEffect(() => {
         const mesh = meshRef.current;
@@ -27,6 +28,7 @@ export function HexTerritoryGlobe({ cells, selectedCellId = null, hoverCellId =
             workingObject.updateMatrix();
             matrix.copy(workingObject.matrix);
             mesh.setMatrixAt(index, matrix);
+            const affiliation = affiliationByCellId?.[cell.cellId] ?? 'neutral';
             const baseColor = locked.has(cell.cellId)
                 ? '#23345c'
                 : colorsByCellId?.[cell.cellId] ??
@@ -34,9 +36,15 @@ export function HexTerritoryGlobe({ cells, selectedCellId = null, hoverCellId =
                         ? '#7ee7ff'
                         : hoverCellId === cell.cellId
                             ? '#59d0ff'
-                            : claimed.has(cell.cellId)
-                                ? '#63f2c6'
-                                : '#1f2a4a');
+                            : affiliation === 'self'
+                                ? '#7ee7ff'
+                                : affiliation === 'ally'
+                                    ? '#63f2c6'
+                                    : affiliation === 'hostile'
+                                        ? '#ff9675'
+                                        : claimed.has(cell.cellId)
+                                            ? '#63f2c6'
+                                            : '#1f2a4a');
             mesh.setColorAt(index, new Color(baseColor));
         });
         mesh.instanceMatrix.needsUpdate = true;
@@ -47,6 +55,7 @@ export function HexTerritoryGlobe({ cells, selectedCellId = null, hoverCellId =
         cells,
         claimed,
         colorsByCellId,
+        affiliationByCellId,
         hoverCellId,
         locked,
         selectedCellId,
@@ -54,22 +63,44 @@ export function HexTerritoryGlobe({ cells, selectedCellId = null, hoverCellId =
         autoTileRadiusByRow,
         workingObject,
     ]);
-    return (_jsx("instancedMesh", { ref: meshRef, args: [geometry, undefined, cells.length], onClick: (event) => {
-            if (typeof event.instanceId !== 'number') {
-                return;
-            }
-            const cell = cells[event.instanceId];
-            if (cell) {
-                onSelectCell?.(cell);
-            }
-        }, onPointerMove: (event) => {
-            if (typeof event.instanceId !== 'number') {
-                onHoverCell?.(null);
-                return;
-            }
-            const cell = cells[event.instanceId];
-            onHoverCell?.(cell ?? null);
-        }, onPointerOut: () => {
-            onHoverCell?.(null);
-        }, children: _jsx("meshStandardMaterial", { transparent: true, opacity: 0.92, metalness: 0.14, roughness: 0.42 }) }));
+    return (_jsxs(_Fragment, { children: [_jsx("instancedMesh", { ref: meshRef, args: [geometry, undefined, cells.length], onClick: (event) => {
+                    if (typeof event.instanceId !== 'number') {
+                        return;
+                    }
+                    const cell = cells[event.instanceId];
+                    if (cell) {
+                        onSelectCell?.(cell);
+                    }
+                }, onPointerMove: (event) => {
+                    if (typeof event.instanceId !== 'number') {
+                        onHoverCell?.(null);
+                        return;
+                    }
+                    const cell = cells[event.instanceId];
+                    onHoverCell?.(cell ?? null);
+                }, onPointerOut: () => {
+                    onHoverCell?.(null);
+                }, children: _jsx("meshStandardMaterial", { transparent: true, opacity: 0.92, metalness: 0.14, roughness: 0.42 }) }), (rallyMarkers ?? []).map((marker) => {
+                const cell = cellById.get(marker.cellId);
+                if (!cell) {
+                    return null;
+                }
+                const intensity = Math.max(0.35, Math.min(marker.intensity ?? 1, 2));
+                const scale = 0.028 * intensity;
+                const point = cell.surfacePoint;
+                return (_jsxs("mesh", { position: [point.x * 1.015, point.y * 1.015, point.z * 1.015], children: [_jsx("sphereGeometry", { args: [scale, 10, 10] }), _jsx("meshBasicMaterial", { color: marker.directive === 'surge'
+                                ? '#ffc857'
+                                : marker.directive === 'fortify'
+                                    ? '#7ee7ff'
+                                    : marker.directive === 'support'
+                                        ? '#63f2c6'
+                                        : '#c9d4ff' })] }, `${marker.cellId}:${marker.directive}`));
+            }), (allianceBindings ?? []).flatMap((binding) => binding.rootCellIds.map((cellId) => {
+                const cell = cellById.get(cellId);
+                if (!cell) {
+                    return null;
+                }
+                const point = cell.surfacePoint;
+                return (_jsxs("mesh", { position: [point.x * 1.005, point.y * 1.005, point.z * 1.005], children: [_jsx("sphereGeometry", { args: [0.018, 8, 8] }), _jsx("meshBasicMaterial", { color: "#7ee7ff", transparent: true, opacity: 0.75 })] }, `${binding.phyleId}:${cellId}:halo`));
+            }))] }));
 }

package/dist/territory/globe.d.ts

@@ -28,6 +28,18 @@ export interface HexTerritoryTickState {
     cohesion: number;
     lastResolvedAt: number;
 }
+export type HexTerritoryAffiliation = 'self' | 'ally' | 'neutral' | 'hostile';
+export interface HexTerritoryAllianceBinding {
+    phyleId: string;
+    rootCellIds: string[];
+    displayName?: string;
+}
+export interface HexTerritoryRallyMarker {
+    cellId: string;
+    directive: 'fortify' | 'surge' | 'watch' | 'support';
+    phyleId?: string;
+    intensity?: number;
+}
 export interface HexTerritoryCellPoint {
     x: number;
     y: number;

package/dist/territory/globe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"globe.d.ts","sourceRoot":"","sources":["../../src/territory/globe.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,qBAAqB,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAC9D,MAAM,MAAM,WAAW,GAAG,qBAAqB,EAAE,CAAC;AAElD,MAAM,MAAM,mBAAmB,GAC3B,SAAS,GACT,GAAG,GACH,WAAW,GACX,SAAS,GACT,QAAQ,CAAC;AAEb,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,YAAY,GAAG,QAAQ,CAAC;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,qBAAqB,CAAC;IACpC,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,uBAAuB,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,gBAAgB,EAAE,CAAC;CAC3B;AA2HD,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,uBAAuB,GAC9B,iBAAiB,CAoDnB;AAED,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,SAAS,gBAAgB,EAAE,GACjC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAiErB"}
+{"version":3,"file":"globe.d.ts","sourceRoot":"","sources":["../../src/territory/globe.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,qBAAqB,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAC9D,MAAM,MAAM,WAAW,GAAG,qBAAqB,EAAE,CAAC;AAElD,MAAM,MAAM,mBAAmB,GAC3B,SAAS,GACT,GAAG,GACH,WAAW,GACX,SAAS,GACT,QAAQ,CAAC;AAEb,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,YAAY,GAAG,QAAQ,CAAC;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;AAE9E,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,qBAAqB,CAAC;IACpC,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,uBAAuB,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,gBAAgB,EAAE,CAAC;CAC3B;AA2HD,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,uBAAuB,GAC9B,iBAAiB,CAoDnB;AAED,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,SAAS,gBAAgB,EAAE,GACjC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAiErB"}

package/dist/territory/globe.js

@@ -93,7 +93,7 @@ export function generateCanonicalHexGlobe(config) {
     const sphereRadius = config.sphereRadius ?? 1;
     const rows = [];
     for (let rowIndex = 0; rowIndex < config.rowCount; rowIndex += 1) {
-        const latitudeProgress = config.rowCount <= 1 ? 0 : rowIndex / (config.rowCount - 1);
+        const latitudeProgress = config.rowCount <= 1 ? 0.5 : (rowIndex + 0.5) / config.rowCount;
         const lat = -90 + latitudeProgress * 180;
         const columnCount = columnCountForLatitude(lat, config);
         const lonStep = 360 / columnCount;

package/dist/territory/narration.d.ts

@@ -1,5 +1,5 @@
 import type { NarrationMessage } from '../lib/narration';
-export type HexwarNarrationEventType = 'claim' | 'embed_set' | 'delegation_issued' | 'delegation_revoked' | 'unlock' | 'tick_surged' | 'tick_entrenched' | 'leaderboard_flip';
+export type HexwarNarrationEventType = 'claim' | 'territory_captured' | 'embed_set' | 'delegation_issued' | 'delegation_revoked' | 'nexus_created' | 'nexus_connected' | 'alliance_root_bound' | 'rally_called' | 'allied_border_held' | 'alliance_surged' | 'unlock' | 'tick_surged' | 'tick_entrenched' | 'leaderboard_flip';
 export interface HexwarNarrationEvent {
     id: string;
     eventType: HexwarNarrationEventType;

package/dist/territory/narration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"narration.d.ts","sourceRoot":"","sources":["../../src/territory/narration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD,MAAM,MAAM,wBAAwB,GAChC,OAAO,GACP,WAAW,GACX,mBAAmB,GACnB,oBAAoB,GACpB,QAAQ,GACR,aAAa,GACb,iBAAiB,GACjB,kBAAkB,CAAC;AAEvB,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,wBAAwB,CAAC;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;CACxE;AAgDD,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,oBAAoB,EAAE,GAC7B,gBAAgB,EAAE,CAmDpB"}
+{"version":3,"file":"narration.d.ts","sourceRoot":"","sources":["../../src/territory/narration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD,MAAM,MAAM,wBAAwB,GAChC,OAAO,GACP,oBAAoB,GACpB,WAAW,GACX,mBAAmB,GACnB,oBAAoB,GACpB,eAAe,GACf,iBAAiB,GACjB,qBAAqB,GACrB,cAAc,GACd,oBAAoB,GACpB,iBAAiB,GACjB,QAAQ,GACR,aAAa,GACb,iBAAiB,GACjB,kBAAkB,CAAC;AAEvB,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,wBAAwB,CAAC;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;CACxE;AAyED,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,oBAAoB,EAAE,GAC7B,gBAAgB,EAAE,CAmDpB"}

package/dist/territory/narration.js

@@ -3,11 +3,22 @@ function priorityForEvent(eventType) {
         case 'leaderboard_flip':
         case 'unlock':
             return 9;
+        case 'nexus_created':
+        case 'nexus_connected':
+        case 'alliance_surged':
+            return 8;
+        case 'territory_captured':
+            return 8;
         case 'tick_surged':
         case 'tick_entrenched':
             return 8;
+        case 'rally_called':
+        case 'alliance_root_bound':
+            return 7;
         case 'claim':
             return 7;
+        case 'allied_border_held':
+            return 6;
         case 'delegation_issued':
         case 'delegation_revoked':
             return 6;
@@ -23,12 +34,26 @@ function formatSingleEvent(event) {
     switch (event.eventType) {
         case 'claim':
             return `${actor}claimed root${cell}.`.trim();
+        case 'territory_captured':
+            return `${actor}captured frontier territory${cell}.`.trim();
         case 'embed_set':
             return `${actor}repointed the frontier payload${cell}.`.trim();
         case 'delegation_issued':
             return `${actor}delegated subhex control${cell}.`.trim();
         case 'delegation_revoked':
             return `${actor}revoked delegated control${cell}.`.trim();
+        case 'nexus_created':
+            return `${actor}founded a nexus${cell}.`.trim();
+        case 'nexus_connected':
+            return `${actor}connected a sovereign root into an alliance${cell}.`.trim();
+        case 'alliance_root_bound':
+            return `A sovereign root joined an allied phyle${cell}.`.trim();
+        case 'rally_called':
+            return `A new rally directive lit up${cell}.`.trim();
+        case 'allied_border_held':
+            return `Allied borders held firm${cell}.`.trim();
+        case 'alliance_surged':
+            return `Allied pressure pushed${cell} into surge state.`.trim();
         case 'unlock':
             return `A new latitude band unlocked${cell}.`.trim();
         case 'tick_surged':

package/dist/workers/hexgrid-math.d.ts

@@ -3,6 +3,36 @@
  * These functions have NO side effects, NO logging, and NO mutable state access.
  * They are deterministic and testable in isolation.
  */
+export interface ScreenGridMetadata {
+    isSpherical: false;
+    cols: number;
+    rows: number;
+}
+export interface SphericalScreenGridMetadata {
+    isSpherical: true;
+    cols: number;
+    rows: number;
+    rowColumnCounts: number[];
+    indexToRow: number[];
+    indexToColumn: number[];
+}
+export interface SphericalScreenGridLayout {
+    positions: [number, number, number][];
+    metadata: SphericalScreenGridMetadata;
+}
+/**
+ * Generate a screen-space hex grid that preserves local neighbor spacing while
+ * carrying enough metadata to project each row across the full spherical span.
+ */
+export declare function generateScreenSpaceSphericalHexGrid(_targetCount: number, screenWidth: number, screenHeight: number, curveUDeg: number, curveVDeg: number, densityMultiplier: number | undefined, hexRadius: number): SphericalScreenGridLayout;
+/**
+ * Convert a spherical grid index into normalized [0,1] coordinates used for
+ * longitude/latitude mapping, independent of the row's raw screen-space width.
+ */
+export declare function getNormalizedScreenSpaceSphericalCoordinates(index: number, metadata: SphericalScreenGridMetadata, curveUDeg: number): {
+    u: number;
+    v: number;
+} | null;
 /**
  * Calculate the bounding box of a set of 2D/3D positions.
  * @pure - No side effects, deterministic

package/dist/workers/hexgrid-math.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hexgrid-math.d.ts","sourceRoot":"","sources":["../../src/workers/hexgrid-math.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE;;;;;;;EAmBlE;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAC3B,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAC3B,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EACzC,WAAW,EAAE,OAAO,GACnB,MAAM,CAeR;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iCAAiC,CAC/C,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAalC;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EAAE,EACjB,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,EACrC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,EAAE,GACxC,MAAM,CAgBR;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,EAAE,EACjB,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,EACrC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,EAAE,GACxC,MAAM,CAER;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EAAE,EACjB,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,EACrC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,EAAE,GACxC,MAAM,CAgBR"}
+{"version":3,"file":"hexgrid-math.d.ts","sourceRoot":"","sources":["../../src/workers/hexgrid-math.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,KAAK,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,2BAA2B;IAC1C,WAAW,EAAE,IAAI,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,yBAAyB;IACxC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;IACtC,QAAQ,EAAE,2BAA2B,CAAC;CACvC;AAED;;;GAGG;AACH,wBAAgB,mCAAmC,CACjD,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,iBAAiB,oBAAM,EACvB,SAAS,EAAE,MAAM,GAChB,yBAAyB,CAmE3B;AAED;;;GAGG;AACH,wBAAgB,4CAA4C,CAC1D,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,2BAA2B,EACrC,SAAS,EAAE,MAAM,GAChB;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAkCjC;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE;;;;;;;EAmBlE;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAC3B,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAC3B,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EACzC,WAAW,EAAE,OAAO,GACnB,MAAM,CAeR;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iCAAiC,CAC/C,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAalC;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EAAE,EACjB,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,EACrC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,EAAE,GACxC,MAAM,CAgBR;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,EAAE,EACjB,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,EACrC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,EAAE,GACxC,MAAM,CAER;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EAAE,EACjB,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,EACrC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,EAAE,GACxC,MAAM,CAgBR"}

package/dist/workers/hexgrid-math.js

@@ -3,6 +3,98 @@
  * These functions have NO side effects, NO logging, and NO mutable state access.
  * They are deterministic and testable in isolation.
  */
+/**
+ * Generate a screen-space hex grid that preserves local neighbor spacing while
+ * carrying enough metadata to project each row across the full spherical span.
+ */
+export function generateScreenSpaceSphericalHexGrid(_targetCount, screenWidth, screenHeight, curveUDeg, curveVDeg, densityMultiplier = 1.4, hexRadius) {
+    const positions = [];
+    const rowColumnCounts = [];
+    const indexToRow = [];
+    const indexToColumn = [];
+    if (!Number.isFinite(screenWidth) ||
+        !Number.isFinite(screenHeight) ||
+        !Number.isFinite(curveUDeg) ||
+        !Number.isFinite(curveVDeg) ||
+        !Number.isFinite(densityMultiplier) ||
+        !Number.isFinite(hexRadius) ||
+        screenWidth <= 0 ||
+        screenHeight <= 0 ||
+        hexRadius <= 0) {
+        return {
+            positions,
+            metadata: {
+                isSpherical: true,
+                cols: 0,
+                rows: 0,
+                rowColumnCounts,
+                indexToRow,
+                indexToColumn,
+            },
+        };
+    }
+    const sqrt3 = Math.sqrt(3);
+    const horizontalSpacing = sqrt3 * hexRadius;
+    const verticalSpacing = 1.5 * hexRadius;
+    const densityScale = Math.sqrt(Math.max(0.1, densityMultiplier));
+    const cols = Math.max(3, Math.ceil((screenWidth / horizontalSpacing) * densityScale));
+    const rows = Math.max(1, Math.ceil((screenHeight / verticalSpacing) * densityScale));
+    const deg2rad = Math.PI / 180;
+    for (let row = 0; row < rows; row += 1) {
+        const y = row * verticalSpacing;
+        const rowProgress = rows === 1 ? 0.5 : (row + 0.5) / rows;
+        const lat = (rowProgress - 0.5) * (curveVDeg * deg2rad);
+        const latFactor = Math.max(0.3, Math.abs(Math.cos(lat)));
+        const effectiveColsForRow = Math.max(3, Math.round(cols * latFactor));
+        const rowOffset = row % 2 === 0 ? 0 : 0.5;
+        rowColumnCounts.push(effectiveColsForRow);
+        for (let col = 0; col < effectiveColsForRow; col += 1) {
+            const x = (col + rowOffset) * horizontalSpacing;
+            positions.push([x, y, 0]);
+            indexToRow.push(row);
+            indexToColumn.push(col);
+        }
+    }
+    return {
+        positions,
+        metadata: {
+            isSpherical: true,
+            cols,
+            rows,
+            rowColumnCounts,
+            indexToRow,
+            indexToColumn,
+        },
+    };
+}
+/**
+ * Convert a spherical grid index into normalized [0,1] coordinates used for
+ * longitude/latitude mapping, independent of the row's raw screen-space width.
+ */
+export function getNormalizedScreenSpaceSphericalCoordinates(index, metadata, curveUDeg) {
+    if (index < 0 ||
+        index >= metadata.indexToRow.length ||
+        metadata.rows <= 0) {
+        return null;
+    }
+    const row = metadata.indexToRow[index];
+    const column = metadata.indexToColumn[index];
+    const rowColumnCount = metadata.rowColumnCounts[row];
+    if (row === undefined ||
+        column === undefined ||
+        rowColumnCount === undefined ||
+        rowColumnCount <= 0) {
+        return null;
+    }
+    const rowOffset = row % 2 === 0 ? 0 : 0.5;
+    const isWrapped = Math.abs(curveUDeg) >= 359;
+    const rawU = (column + 0.5 + rowOffset) / rowColumnCount;
+    const u = isWrapped
+        ? ((rawU % 1) + 1) % 1
+        : Math.min(1, Math.max(0, rawU / Math.max(1, 1 + rowOffset / rowColumnCount)));
+    const v = metadata.rows === 1 ? 0.5 : (row + 0.5) / metadata.rows;
+    return { u, v };
+}
 /**
  * Calculate the bounding box of a set of 2D/3D positions.
  * @pure - No side effects, deterministic

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buley/hexgrid-3d",
-  "version": "3.6.1",
+  "version": "3.6.2",
   "description": "3D hexagonal grid visualization component for React",
   "type": "module",
   "main": "./dist/index.js",