@buley/hexgrid-3d 3.6.0 → 3.6.2

package/dist/territory/narration.js

@@ -0,0 +1,109 @@
+function priorityForEvent(eventType) {
+    switch (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;
+        case 'embed_set':
+            return 5;
+        default:
+            return 4;
+    }
+}
+function formatSingleEvent(event) {
+    const actor = event.actorName ? `${event.actorName} ` : '';
+    const cell = event.cellId ? ` ${event.cellId}` : '';
+    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':
+            return `Hourly pressure pushed${cell} into surge state.`.trim();
+        case 'tick_entrenched':
+            return `${cell.trim()} entrenched after the latest tick.`.trim();
+        case 'leaderboard_flip':
+            return `The leaderboard flipped after the latest tick.`.trim();
+        default:
+            return 'Frontier activity updated.';
+    }
+}
+export function createHexwarNarrationAdapter(events) {
+    if (events.length === 0) {
+        return [];
+    }
+    const sorted = [...events].sort((left, right) => left.occurredAtMs - right.occurredAtMs);
+    const messages = [];
+    let currentBurst = [];
+    for (const event of sorted) {
+        const previous = currentBurst[currentBurst.length - 1];
+        const isBurstContinuation = previous &&
+            previous.eventType === event.eventType &&
+            event.occurredAtMs - previous.occurredAtMs <= 30000;
+        if (!isBurstContinuation && currentBurst.length > 0) {
+            const first = currentBurst[0];
+            messages.push({
+                generation: 0,
+                timestamp: new Date(first.occurredAtMs).toISOString(),
+                priority: priorityForEvent(first.eventType),
+                text: currentBurst.length === 1
+                    ? formatSingleEvent(first)
+                    : `${currentBurst.length} ${first.eventType.replace(/_/g, ' ')} events rippled across the frontier.`,
+                eventType: first.eventType,
+            });
+            currentBurst = [];
+        }
+        currentBurst.push(event);
+    }
+    if (currentBurst.length > 0) {
+        const first = currentBurst[0];
+        messages.push({
+            generation: 0,
+            timestamp: new Date(first.occurredAtMs).toISOString(),
+            priority: priorityForEvent(first.eventType),
+            text: currentBurst.length === 1
+                ? formatSingleEvent(first)
+                : `${currentBurst.length} ${first.eventType.replace(/_/g, ' ')} events rippled across the frontier.`,
+            eventType: first.eventType,
+        });
+    }
+    return messages;
+}

package/dist/types.d.ts

@@ -123,4 +123,169 @@ export interface WorkerDebug {
     batchPerFrame: number;
     [key: string]: any;
 }
+/** Built-in 3D primitive shapes for game pieces */
+export type PieceShape = 'sphere' | 'cube' | 'cone' | 'cylinder' | 'pyramid' | 'torus' | 'ring' | 'flag' | 'star' | 'diamond' | 'capsule' | 'octahedron' | 'dodecahedron' | 'icosahedron';
+/** Animation presets that can be applied to game pieces */
+export type PieceAnimation = 'none' | 'spin' | 'bob' | 'pulse' | 'wobble' | 'orbit' | 'glow';
+/** Animation configuration */
+export interface PieceAnimationConfig {
+    type: PieceAnimation;
+    speed?: number;
+    amplitude?: number;
+    axis?: [number, number, number];
+    phase?: number;
+}
+/**
+ * A game piece placed on a hex cell.
+ *
+ * Supports three rendering modes:
+ * 1. **Primitive shape** — set `shape` to a PieceShape string.
+ * 2. **Custom Three.js Object3D** — set `object3D` to any Object3D instance.
+ *    The renderer will clone it and place it on the hex surface.
+ * 3. **GLTF/GLB model URL** — set `modelUrl` to a URL pointing to a .glb/.gltf.
+ *    The renderer loads it asynchronously and caches the geometry.
+ */
+export interface GamePiece {
+    id: string;
+    shape?: PieceShape;
+    /** Arbitrary Three.js Object3D (mesh, group, sprite, etc.) */
+    object3D?: unknown;
+    /** URL to a .glb / .gltf model */
+    modelUrl?: string;
+    color?: string;
+    emissive?: string;
+    emissiveIntensity?: number;
+    opacity?: number;
+    metalness?: number;
+    roughness?: number;
+    wireframe?: boolean;
+    scale?: number | [number, number, number];
+    offsetY?: number;
+    rotationY?: number;
+    animation?: PieceAnimation | PieceAnimationConfig;
+    label?: string;
+    labelColor?: string;
+    tooltip?: string;
+    count?: number;
+    stackStyle?: 'badge' | 'stack' | 'ring';
+    interactive?: boolean;
+    draggable?: boolean;
+    layer?: number;
+    group?: string;
+}
+/** Fog of war visibility levels */
+export type FogLevel = 'visible' | 'explored' | 'dim' | 'hidden';
+/** Cell highlight modes */
+export type CellHighlight = 'none' | 'selected' | 'hover' | 'attack-target' | 'move-target' | 'great-circle' | 'path' | 'danger' | 'friendly' | 'contested' | string;
+/** Border style for cell outlines */
+export interface CellBorder {
+    color: string;
+    width?: number;
+    style?: 'solid' | 'dashed' | 'glow' | 'pulse';
+    emissive?: boolean;
+}
+/**
+ * Complete game state for a single cell on the sphere.
+ * Pass a `Map<number, CellGameState>` to GameSphere to overlay game state on the geodesic grid.
+ */
+export interface CellGameState {
+    ownerId?: string;
+    ownerColor?: string;
+    ownerColorIntensity?: number;
+    pieces?: GamePiece[];
+    fogLevel?: FogLevel;
+    highlight?: CellHighlight;
+    highlightColor?: string;
+    highlightIntensity?: number;
+    border?: CellBorder;
+    terrainType?: string;
+    terrainColor?: string;
+    cellLabel?: string;
+    cellLabelColor?: string;
+    cellLabelSize?: number;
+    elevation?: number;
+    isPentagon?: boolean;
+    data?: Record<string, unknown>;
+}
+/**
+ * Configuration for the GameSphere's visual appearance.
+ */
+export interface GameSphereConfig {
+    subdivisions?: number;
+    sphereRadius?: number;
+    cameraDistance?: number;
+    cameraFov?: number;
+    enableOrbitControls?: boolean;
+    autoRotate?: boolean;
+    autoRotateSpeed?: number;
+    ambientLightIntensity?: number;
+    directionalLightIntensity?: number;
+    directionalLightPosition?: [number, number, number];
+    hexBaseColor?: string;
+    hexBorderColor?: string;
+    hexBorderWidth?: number;
+    pentagonBaseColor?: string;
+    pentagonBorderColor?: string;
+    fogDimColor?: string;
+    fogHiddenColor?: string;
+    fogExploredColor?: string;
+    defaultPieceScale?: number;
+    defaultPieceColor?: string;
+    enableRaycasting?: boolean;
+    enableDragDrop?: boolean;
+    hoverHighlightColor?: string;
+    enableBloom?: boolean;
+    enableShadows?: boolean;
+    enableAntialias?: boolean;
+    enableInstancing?: boolean;
+    maxVisiblePieces?: number;
+    pixelRatio?: number;
+}
+/**
+ * Events emitted by the GameSphere component.
+ */
+export interface GameSphereEvents {
+    /** Cell was clicked */
+    onCellClick?: (cellIndex: number, event: {
+        shiftKey: boolean;
+        ctrlKey: boolean;
+    }) => void;
+    /** Cell hover entered */
+    onCellHover?: (cellIndex: number | null) => void;
+    /** A piece was clicked */
+    onPieceClick?: (cellIndex: number, piece: GamePiece) => void;
+    /** A piece was dragged from one cell to another */
+    onPieceDrop?: (fromCell: number, toCell: number, piece: GamePiece) => void;
+    /** Camera moved (for syncing external UI) */
+    onCameraChange?: (position: [number, number, number], target: [number, number, number]) => void;
+    /** Render frame callback (for custom overlays) */
+    onFrame?: (deltaTime: number) => void;
+}
+/**
+ * Props for the GameSphere component — the 3D board game renderer.
+ */
+export interface GameSphereProps {
+    /** Game state per cell. Key = cell index from GeodesicHexGrid. */
+    cellGameState?: Map<number, CellGameState>;
+    /** Visual and behavior configuration */
+    config?: GameSphereConfig;
+    /** Event callbacks */
+    events?: GameSphereEvents;
+    /** Width of the canvas (default '100%') */
+    width?: number | string;
+    /** Height of the canvas (default '100%') */
+    height?: number | string;
+    /** CSS class for the container */
+    className?: string;
+    /** Inline styles for the container */
+    style?: React.CSSProperties;
+    /** Optional ref to the Three.js renderer for external access */
+    rendererRef?: RefObject<unknown>;
+    /** Optional ref to the Three.js scene for injecting custom objects */
+    sceneRef?: RefObject<unknown>;
+    /** Pauses rendering when true (e.g. modal open) */
+    paused?: boolean;
+    /** Children rendered as React overlay on top of the canvas */
+    children?: React.ReactNode;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

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.0",
+  "version": "3.6.2",
   "description": "3D hexagonal grid visualization component for React",
   "type": "module",
   "main": "./dist/index.js",
@@ -65,6 +65,7 @@
     "three"
   ],
   "peerDependencies": {
+    "@react-three/fiber": "^9.4.2",
     "next": "^14.0.0",
     "react": "^18.0.0",
     "react-dom": "^18.0.0",
@@ -80,6 +81,7 @@
     "@types/react": "^18.3.27",
     "@types/three": "^0.183.1",
     "@types/react-dom": "^18.3.7",
+    "@react-three/fiber": "^9.4.2",
     "happy-dom": "^20.3.3",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",