@buley/hexgrid-3d 3.6.0 → 3.6.2

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/components/index.d.ts

@@ -1,4 +1,9 @@
 export { HexGrid, default } from './HexGrid';
 export type { Photo } from './HexGrid';
 export type { HexGridProps } from '../types';
+export { GameSphere } from './GameSphere';
+export { buildPieceMesh, placePieceOnSphere, animatePiece, buildCellMesh, buildCellBorder, buildHighlightRing, buildFogOverlay, buildAttackTrail, buildOrbitalStrike, disposePieceGroup, applyCellState, } from './GamePieceRenderer';
+export type { AttackAnimationConfig, OrbitalStrikeConfig } from './GamePieceRenderer';
+export type { GamePiece, PieceShape, PieceAnimation, PieceAnimationConfig, CellGameState, CellHighlight, CellBorder, FogLevel, GameSphereProps, GameSphereConfig, GameSphereEvents, } from '../types';
+export { HexTerritoryGlobe } from '../territory/HexTerritoryGlobe';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,YAAY,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AACvC,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,YAAY,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AACvC,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAG7C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,YAAY,EACZ,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,GACf,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAGtF,YAAY,EACV,SAAS,EACT,UAAU,EACV,cAAc,EACd,oBAAoB,EACpB,aAAa,EACb,aAAa,EACb,UAAU,EACV,QAAQ,EACR,eAAe,EACf,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC"}

package/dist/components/index.js

@@ -1 +1,5 @@
 export { HexGrid, default } from './HexGrid';
+// Game piece rendering system
+export { GameSphere } from './GameSphere';
+export { buildPieceMesh, placePieceOnSphere, animatePiece, buildCellMesh, buildCellBorder, buildHighlightRing, buildFogOverlay, buildAttackTrail, buildOrbitalStrike, disposePieceGroup, applyCellState, } from './GamePieceRenderer';
+export { HexTerritoryGlobe } from '../territory/HexTerritoryGlobe';

package/dist/index.d.ts

@@ -9,4 +9,6 @@ export * from './algorithms';
 export * from './HexGridEnhanced';
 export * from './wasm';
 export * from './Snapshot';
+export * from './territory';
+export type { NarrationMessage } from './lib/narration';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAG3B,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AAGpC,YAAY,EAAE,WAAW,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAG5D,cAAc,QAAQ,CAAC;AAGvB,cAAc,cAAc,CAAC;AAG7B,cAAc,mBAAmB,CAAC;AAGlC,cAAc,QAAQ,CAAC;AAGvB,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAG3B,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AAGpC,YAAY,EAAE,WAAW,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAG5D,cAAc,QAAQ,CAAC;AAGvB,cAAc,cAAc,CAAC;AAG7B,cAAc,mBAAmB,CAAC;AAGlC,cAAc,QAAQ,CAAC;AAGvB,cAAc,YAAY,CAAC;AAG3B,cAAc,aAAa,CAAC;AAC5B,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -15,3 +15,5 @@ export * from './HexGridEnhanced';
 export * from './wasm';
 // Unified Snapshot API
 export * from './Snapshot';
+// Territory globe exports
+export * from './territory';

package/dist/territory/HexTerritoryGlobe.d.ts

@@ -0,0 +1,18 @@
+import React from 'react';
+import { type HexTerritoryAffiliation, type HexTerritoryAllianceBinding, type HexTerritoryCell, type HexTerritoryRallyMarker } from './globe';
+export interface HexTerritoryGlobeProps {
+    cells: HexTerritoryCell[];
+    selectedCellId?: string | null;
+    hoverCellId?: string | null;
+    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, affiliationByCellId, allianceBindings, rallyMarkers, tileRadius, onSelectCell, onHoverCell, }: HexTerritoryGlobeProps): React.JSX.Element;
+//# sourceMappingURL=HexTerritoryGlobe.d.ts.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,106 @@
+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';
+function asSet(values) {
+    return values ? new Set(values) : new Set();
+}
+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;
+        if (!mesh) {
+            return;
+        }
+        const matrix = new Matrix4();
+        cells.forEach((cell, index) => {
+            const point = cell.surfacePoint;
+            const effectiveTileRadius = tileRadius ?? autoTileRadiusByRow?.get(cell.rowIndex) ?? 0;
+            workingObject.position.set(point.x, point.y, point.z);
+            workingObject.lookAt(point.x * 2, point.y * 2, point.z * 2);
+            workingObject.scale.setScalar(effectiveTileRadius);
+            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] ??
+                    (selectedCellId === cell.cellId
+                        ? '#7ee7ff'
+                        : hoverCellId === cell.cellId
+                            ? '#59d0ff'
+                            : 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;
+        if (mesh.instanceColor) {
+            mesh.instanceColor.needsUpdate = true;
+        }
+    }, [
+        cells,
+        claimed,
+        colorsByCellId,
+        affiliationByCellId,
+        hoverCellId,
+        locked,
+        selectedCellId,
+        tileRadius,
+        autoTileRadiusByRow,
+        workingObject,
+    ]);
+    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

@@ -0,0 +1,66 @@
+export interface CanonicalHexGlobeConfig {
+    boardId: string;
+    curveUDeg: number;
+    curveVDeg: number;
+    rowCount: number;
+    equatorColumns: number;
+    minimumColumnsPerRow: number;
+    poleMinScale: number;
+    sphereRadius?: number;
+}
+export type HexSubdivisionSegment = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+export type HexNodePath = HexSubdivisionSegment[];
+export type HexwarEmbedProvider = 'youtube' | 'x' | 'instagram' | 'threads' | 'tiktok';
+export interface HexwarEmbedRef {
+    provider: HexwarEmbedProvider;
+    submittedUrl: string;
+    canonicalUrl: string;
+    kind: 'video' | 'post' | 'thread' | 'short' | 'reel';
+    title?: string;
+    authorName?: string;
+    thumbnailUrl?: string;
+    embedAllowed: boolean;
+}
+export interface HexTerritoryTickState {
+    stage: 'dormant' | 'active' | 'surging' | 'entrenched' | 'fading';
+    energy: number;
+    pressure: number;
+    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;
+    z: number;
+}
+export interface HexTerritoryCell {
+    cellId: string;
+    rowIndex: number;
+    columnIndex: number;
+    columnCount: number;
+    lat: number;
+    lon: number;
+    surfacePoint: HexTerritoryCellPoint;
+    neighborCellIds: string[];
+}
+export interface HexTerritoryBoard {
+    boardId: string;
+    config: CanonicalHexGlobeConfig;
+    configHash: string;
+    cells: HexTerritoryCell[];
+}
+export declare function generateCanonicalHexGlobe(config: CanonicalHexGlobeConfig): HexTerritoryBoard;
+export declare function calculateAutoTileRadiusByRow(cells: readonly HexTerritoryCell[]): Map<number, number>;
+//# sourceMappingURL=globe.d.ts.map

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

@@ -0,0 +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,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

@@ -0,0 +1,180 @@
+const boardCache = new Map();
+const HEX_HORIZONTAL_RADIUS_RATIO = Math.sqrt(3);
+const HEX_VERTICAL_RADIUS_RATIO = 1.5;
+const TERRITORY_TILE_RADIUS_SAFETY_MARGIN = 0.96;
+function toRadians(value) {
+    return (value * Math.PI) / 180;
+}
+function normalizeLongitude(value) {
+    let next = value;
+    while (next < -180) {
+        next += 360;
+    }
+    while (next >= 180) {
+        next -= 360;
+    }
+    return next;
+}
+function buildConfigHash(config) {
+    return [
+        config.boardId,
+        config.curveUDeg,
+        config.curveVDeg,
+        config.rowCount,
+        config.equatorColumns,
+        config.minimumColumnsPerRow,
+        config.poleMinScale,
+        config.sphereRadius ?? 1,
+    ].join(':');
+}
+function toSurfacePoint(lat, lon, sphereRadius) {
+    const latRadians = toRadians(lat);
+    const lonRadians = toRadians(lon);
+    const cosLat = Math.cos(latRadians);
+    return {
+        x: sphereRadius * cosLat * Math.cos(lonRadians),
+        y: sphereRadius * Math.sin(latRadians),
+        z: sphereRadius * cosLat * Math.sin(lonRadians),
+    };
+}
+function shortestWrappedDistance(a, b) {
+    const delta = Math.abs(a - b);
+    return Math.min(delta, 360 - delta);
+}
+function pointDistance(left, right) {
+    const dx = left.x - right.x;
+    const dy = left.y - right.y;
+    const dz = left.z - right.z;
+    return Math.sqrt(dx * dx + dy * dy + dz * dz);
+}
+function columnCountForLatitude(latitude, config) {
+    const cosScale = Math.abs(Math.cos(toRadians(latitude)));
+    const scaled = Math.max(config.poleMinScale, cosScale);
+    return Math.max(config.minimumColumnsPerRow, Math.round(config.equatorColumns * scaled));
+}
+function findClosestColumns(rowCells, lon) {
+    const ranked = rowCells
+        .map((cell) => ({
+        cell,
+        distance: shortestWrappedDistance(cell.lon, lon),
+    }))
+        .sort((left, right) => left.distance - right.distance);
+    return ranked.slice(0, Math.min(3, ranked.length)).map((item) => item.cell);
+}
+function buildNeighbors(cell, rows) {
+    const currentRow = rows[cell.rowIndex] ?? [];
+    const neighborIds = new Set();
+    const sameRowCount = currentRow.length;
+    if (sameRowCount > 1) {
+        const left = currentRow[(cell.columnIndex - 1 + sameRowCount) % sameRowCount] ?? null;
+        const right = currentRow[(cell.columnIndex + 1) % sameRowCount] ?? null;
+        if (left) {
+            neighborIds.add(left.cellId);
+        }
+        if (right) {
+            neighborIds.add(right.cellId);
+        }
+    }
+    const adjacentRows = [cell.rowIndex - 1, cell.rowIndex + 1];
+    for (const rowIndex of adjacentRows) {
+        const row = rows[rowIndex] ?? [];
+        for (const adjacent of findClosestColumns(row, cell.lon)) {
+            neighborIds.add(adjacent.cellId);
+        }
+    }
+    return Array.from(neighborIds);
+}
+export function generateCanonicalHexGlobe(config) {
+    const configHash = buildConfigHash(config);
+    const cached = boardCache.get(configHash);
+    if (cached) {
+        return cached;
+    }
+    const sphereRadius = config.sphereRadius ?? 1;
+    const rows = [];
+    for (let rowIndex = 0; rowIndex < config.rowCount; rowIndex += 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;
+        const lonOffset = rowIndex % 2 === 0 ? 0 : lonStep / 2;
+        const rowCells = [];
+        for (let columnIndex = 0; columnIndex < columnCount; columnIndex += 1) {
+            const lon = normalizeLongitude(-180 + lonOffset + columnIndex * lonStep + lonStep / 2);
+            rowCells.push({
+                cellId: `${config.boardId}:r${rowIndex}:c${columnIndex}`,
+                rowIndex,
+                columnIndex,
+                columnCount,
+                lat,
+                lon,
+                surfacePoint: toSurfacePoint(lat, lon, sphereRadius),
+                neighborCellIds: [],
+            });
+        }
+        rows.push(rowCells);
+    }
+    for (const row of rows) {
+        for (const cell of row) {
+            cell.neighborCellIds = buildNeighbors(cell, rows);
+        }
+    }
+    const board = {
+        boardId: config.boardId,
+        config,
+        configHash,
+        cells: rows.flat(),
+    };
+    boardCache.set(configHash, board);
+    return board;
+}
+export function calculateAutoTileRadiusByRow(cells) {
+    const rowMap = new Map();
+    const cellById = new Map();
+    for (const cell of cells) {
+        const row = rowMap.get(cell.rowIndex);
+        if (row) {
+            row.push(cell);
+        }
+        else {
+            rowMap.set(cell.rowIndex, [cell]);
+        }
+        cellById.set(cell.cellId, cell);
+    }
+    const radiusByRow = new Map();
+    for (const [rowIndex, unsortedRow] of rowMap.entries()) {
+        const row = [...unsortedRow].sort((left, right) => left.columnIndex - right.columnIndex);
+        let minimumSameRowDistance = Number.POSITIVE_INFINITY;
+        let minimumAdjacentRowDistance = Number.POSITIVE_INFINITY;
+        if (row.length > 1) {
+            for (let columnIndex = 0; columnIndex < row.length; columnIndex += 1) {
+                const current = row[columnIndex];
+                const next = row[(columnIndex + 1) % row.length];
+                if (current && next) {
+                    minimumSameRowDistance = Math.min(minimumSameRowDistance, pointDistance(current.surfacePoint, next.surfacePoint));
+                }
+            }
+        }
+        for (const cell of row) {
+            for (const neighborId of cell.neighborCellIds) {
+                const neighbor = cellById.get(neighborId);
+                if (!neighbor || Math.abs(neighbor.rowIndex - rowIndex) !== 1) {
+                    continue;
+                }
+                minimumAdjacentRowDistance = Math.min(minimumAdjacentRowDistance, pointDistance(cell.surfacePoint, neighbor.surfacePoint));
+            }
+        }
+        const horizontalRadius = Number.isFinite(minimumSameRowDistance)
+            ? minimumSameRowDistance / HEX_HORIZONTAL_RADIUS_RATIO
+            : Number.POSITIVE_INFINITY;
+        const verticalRadius = Number.isFinite(minimumAdjacentRowDistance)
+            ? minimumAdjacentRowDistance / HEX_VERTICAL_RADIUS_RATIO
+            : Number.POSITIVE_INFINITY;
+        const unconstrainedRadius = Math.min(horizontalRadius, verticalRadius);
+        const safeRadius = Number.isFinite(unconstrainedRadius) && unconstrainedRadius > 0
+            ? unconstrainedRadius * TERRITORY_TILE_RADIUS_SAFETY_MARGIN
+            : 0;
+        radiusByRow.set(rowIndex, safeRadius);
+    }
+    return radiusByRow;
+}

package/dist/territory/index.d.ts

@@ -0,0 +1,4 @@
+export * from './globe';
+export * from './narration';
+export * from './HexTerritoryGlobe';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/territory/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC"}

package/dist/territory/index.js

@@ -0,0 +1,3 @@
+export * from './globe';
+export * from './narration';
+export * from './HexTerritoryGlobe';

package/dist/territory/narration.d.ts

@@ -0,0 +1,12 @@
+import type { NarrationMessage } from '../lib/narration';
+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;
+    occurredAtMs: number;
+    actorName?: string;
+    cellId?: string;
+    details?: Record<string, string | number | boolean | null | undefined>;
+}
+export declare function createHexwarNarrationAdapter(events: HexwarNarrationEvent[]): NarrationMessage[];
+//# sourceMappingURL=narration.d.ts.map

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

@@ -0,0 +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,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"}