cube-helper-web

This library was created as part of a personal experiment with smart cubes and Web Bluetooth.

A small, focused helper library that connects a GAN smart cube via Web Bluetooth
and exposes cube movements as simple, semantic events.

This library intentionally abstracts away Bluetooth, encryption and device-specific
protocols, allowing applications to consume cube moves (R, U', F2, etc.)
with a minimal and stable API.

---

✨ Motivation

Working directly with smart cubes in the browser is harder than it should be.

Even with existing low-level libraries, applications still need to deal with:
- Web Bluetooth APIs
- RxJS event streams
- Device-specific event formats
- Noise and connection lifecycle

This project exists to separate concerns:

> Device & protocol complexity → library
> Application logic → consumer

---

🧩 What this library does

- Connects to a GAN smart cube using Web Bluetooth
- Listens to cube movement events
- Emits normalized cube moves (R, U', F2)
- Exposes a small, framework-agnostic API

---

❌ What this library does NOT do

- No UI
- No DOM access
- No game logic
- No cube state solving
- No Bluetooth abstractions for non-GAN devices

This is a thin, intentional adapter, not a full cube SDK.

---

🚀 Installation

``bash
npm install @lfgf/cube-helper-web
`
Requires a browser with Web Bluetooth support (Chrome / Edge, HTTPS or localhost).

---

🛠️ Usage

`ts
import { connectGanCubeMoves } from "@lfgf/cube-helper-web";

const cube = await connectGanCubeMoves();

const unsubscribe = cube.onMove(({ move }) => {
console.log("Cube move:", move);
});

// later
await cube.disconnect();
`

---

🧠 API
connectGanCubeMoves(): Promise

Returns a connection object with:

`ts
type CubeConnection = {
onMove(cb: (m: { move: string; ts: number }) => void): () => void;
disconnect(): Promise;
};
``

---

⚠️ Browser requirements

- Chrome or Edge (Chromium)
- User must explicitly allow Bluetooth access
- Device selection is user-driven (browser security model)

---

🔧 Internals

Internally, this library wraps gan-web-bluetooth, translating
low-level BLE/RxJS events into a stable, callback-based API.

This design allows applications to remain decoupled from:
- Bluetooth APIs
- RxJS
- Device-specific event shapes

---

📦 Use cases

- Cube training or analytics tools
- Creative or experimental browser-based projects
- Rapid prototyping with physical input devices

---

📄 License

MIT