@lfgf/cube-helper-web 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +123 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# cube-helper-web
|
|
2
|
+
|
|
3
|
+
This library was created as part of a personal experiment with smart cubes and Web Bluetooth.
|
|
4
|
+
|
|
5
|
+
A small, focused helper library that connects a **GAN smart cube** via **Web Bluetooth**
|
|
6
|
+
and exposes cube movements as simple, semantic events.
|
|
7
|
+
|
|
8
|
+
This library intentionally abstracts away Bluetooth, encryption and device-specific
|
|
9
|
+
protocols, allowing applications to consume cube moves (`R`, `U'`, `F2`, etc.)
|
|
10
|
+
with a minimal and stable API.
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## ✨ Motivation
|
|
15
|
+
|
|
16
|
+
Working directly with smart cubes in the browser is harder than it should be.
|
|
17
|
+
|
|
18
|
+
Even with existing low-level libraries, applications still need to deal with:
|
|
19
|
+
- Web Bluetooth APIs
|
|
20
|
+
- RxJS event streams
|
|
21
|
+
- Device-specific event formats
|
|
22
|
+
- Noise and connection lifecycle
|
|
23
|
+
|
|
24
|
+
This project exists to **separate concerns**:
|
|
25
|
+
|
|
26
|
+
> Device & protocol complexity → **library**
|
|
27
|
+
> Application logic → **consumer**
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## 🧩 What this library does
|
|
32
|
+
|
|
33
|
+
- Connects to a **GAN smart cube** using Web Bluetooth
|
|
34
|
+
- Listens to cube movement events
|
|
35
|
+
- Emits **normalized cube moves** (`R`, `U'`, `F2`)
|
|
36
|
+
- Exposes a **small, framework-agnostic API**
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## ❌ What this library does NOT do
|
|
41
|
+
|
|
42
|
+
- No UI
|
|
43
|
+
- No DOM access
|
|
44
|
+
- No game logic
|
|
45
|
+
- No cube state solving
|
|
46
|
+
- No Bluetooth abstractions for non-GAN devices
|
|
47
|
+
|
|
48
|
+
This is a **thin, intentional adapter**, not a full cube SDK.
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## 🚀 Installation
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
npm install @lfgf/cube-helper-web
|
|
56
|
+
```
|
|
57
|
+
Requires a browser with Web Bluetooth support (Chrome / Edge, HTTPS or localhost).
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
🛠️ Usage
|
|
62
|
+
|
|
63
|
+
```ts
|
|
64
|
+
import { connectGanCubeMoves } from "@lfgf/cube-helper-web";
|
|
65
|
+
|
|
66
|
+
const cube = await connectGanCubeMoves();
|
|
67
|
+
|
|
68
|
+
const unsubscribe = cube.onMove(({ move }) => {
|
|
69
|
+
console.log("Cube move:", move);
|
|
70
|
+
});
|
|
71
|
+
|
|
72
|
+
// later
|
|
73
|
+
await cube.disconnect();
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
---
|
|
77
|
+
|
|
78
|
+
🧠 API
|
|
79
|
+
connectGanCubeMoves(): Promise<CubeConnection>
|
|
80
|
+
|
|
81
|
+
Returns a connection object with:
|
|
82
|
+
|
|
83
|
+
```ts
|
|
84
|
+
type CubeConnection = {
|
|
85
|
+
onMove(cb: (m: { move: string; ts: number }) => void): () => void;
|
|
86
|
+
disconnect(): Promise<void>;
|
|
87
|
+
};
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
---
|
|
91
|
+
|
|
92
|
+
⚠️ Browser requirements
|
|
93
|
+
|
|
94
|
+
- Chrome or Edge (Chromium)
|
|
95
|
+
- User must explicitly allow Bluetooth access
|
|
96
|
+
- Device selection is user-driven (browser security model)
|
|
97
|
+
|
|
98
|
+
---
|
|
99
|
+
|
|
100
|
+
🔧 Internals
|
|
101
|
+
|
|
102
|
+
Internally, this library wraps gan-web-bluetooth, translating
|
|
103
|
+
low-level BLE/RxJS events into a stable, callback-based API.
|
|
104
|
+
|
|
105
|
+
This design allows applications to remain decoupled from:
|
|
106
|
+
- Bluetooth APIs
|
|
107
|
+
- RxJS
|
|
108
|
+
- Device-specific event shapes
|
|
109
|
+
|
|
110
|
+
---
|
|
111
|
+
|
|
112
|
+
📦 Use cases
|
|
113
|
+
|
|
114
|
+
- Cube training or analytics tools
|
|
115
|
+
- Creative or experimental browser-based projects
|
|
116
|
+
- Rapid prototyping with physical input devices
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
📄 License
|
|
121
|
+
|
|
122
|
+
MIT
|
|
123
|
+
|