star-canvas 0.1.8 → 0.1.9

package/PROMPT.md

@@ -124,6 +124,7 @@ A safe manager for your HTML overlay, stacked on top of the canvas.
   - `ui.render(html: string)`: **Use this** to set your UI. It's safe and won't destroy the canvas.
     - Automatically skips updates if HTML is unchanged (safe to call in loop for static content)
     - For best performance with dynamic content (score), only call when values actually change
+    - **Positioning:** The UI overlay covers the full viewport, not just the letterboxed game area. Use percentage-based positioning (e.g., `top: 50%; left: 50%; transform: translate(-50%, -50%)`) to stay centered within the visible area. Fixed offsets like `bottom: 18px` may land in the letterbox bars on some screen sizes.
   - `ui.el(selector)`: Scoped `querySelector` for the UI root.
   - `ui.all(selector)`: Scoped `querySelectorAll` for the UI root.
 
@@ -180,6 +181,15 @@ g.loop((dt) => {
 });
 ```
 
+**Hover effects for canvas buttons:**
+```ts
+g.loop((dt) => {
+  const hoverLb = state === 'gameover' && inRect(g.pointer, lbBtn);
+  drawButton('VIEW LEADERBOARD', lbBtn, hoverLb ? '#9061f9' : '#7c3aed');
+  g.canvas.style.cursor = hoverLb ? 'pointer' : 'default';
+});
+```
+
 Taps on interactive UI elements (from `on()` or native `<button>`) are automatically suppressed from `g.tap`.
 
 ### Cursor Management
@@ -202,39 +212,34 @@ if (state === 'menu' || state === 'gameover') canvas.style.cursor = 'auto';  //
 
 **Decision:** Does player click on game objects? → `'pointer'` | Aim precisely? → `'crosshair'` | WASD/touch only? → `'none'` during play, `'auto'` for menus
 
-### `toStagePoint(event)`
-
-Converts `MouseEvent` or `PointerEvent` client coordinates to the stage's logical coordinates.
+### Drag and Drop (Polling Pattern)
 
-  - **USE THIS** for all canvas pointer input.
-
-### `createDrag()`
-
-Creates a drag state helper that handles coordinate conversion and offset tracking automatically.
+Use `g.tap`, `g.pointer`, and `g.released` for drag-and-drop — coordinates are automatic.
 
 ```ts
-const drag = createDrag();
+let dragging = null;
+let offsetX = 0, offsetY = 0;
 
-canvas.addEventListener('pointerdown', (e) => {
-  canvas.setPointerCapture(e.pointerId);  // IMPORTANT: Capture for reliable drags
-  const { x, y } = drag.point(e);         // Convert coordinates
-  const hit = pieces.find(p => /* hit test */);
-  if (hit) drag.grab(e, hit);             // Start drag with offset
-});
-
-canvas.addEventListener('pointermove', (e) => drag.move(e));  // Updates position
-canvas.addEventListener('pointerup', () => {
-  const dropped = drag.release();  // Returns dropped object (or null)
+g.loop((dt) => {
+  if (g.tap) {
+    const hit = pieces.find(p => inRect(g.tap, p));
+    if (hit) {
+      dragging = hit;
+      offsetX = hit.x - g.tap.x;  // Offset so piece doesn't jump to cursor
+      offsetY = hit.y - g.tap.y;
+    }
+  }
+  if (dragging && g.pointer.down) {
+    dragging.x = g.pointer.x + offsetX;
+    dragging.y = g.pointer.y + offsetY;
+  }
+  if (g.released && dragging) {
+    handleDrop(dragging);
+    dragging = null;
+  }
 });
 ```
 
-**API:**
-- `point(e)` - Pure coordinate conversion, no side effects
-- `grab(e, obj)` - Start dragging an object, computing offset from cursor
-- `move(e)` - Update dragged object's position
-- `release()` - End drag, returns dropped object or null
-- `dragging` - The currently dragged object (or null)
-
 ### `GameOptions` (optional)
 
 Pass an options object as the second argument to `game()`:
@@ -508,15 +513,15 @@ game(({ ctx, scoped, loop }) => {
 
 **Why use `scoped()`:** Prevents transform stack corruption from early returns, exceptions, or forgetting `ctx.restore()`. The context is always restored, even if the function exits early.
 
-### Recipe 7: Drag and Drop with createDrag() (RECOMMENDED)
+### Recipe 7: Drag and Drop
 
-Use the `createDrag()` helper - it handles coordinate conversion and offset tracking automatically.
+Use `g.tap`, `g.pointer`, and `g.released` for drag-and-drop. Coordinates are canvas-space automatically.
 
 ```ts
 import { game } from 'star-canvas';
 
-game(({ ctx, width, height, loop, canvas, createDrag }) => {
-  // Size relative to height for consistency
+game((g) => {
+  const { ctx, width, height } = g;
   const pieceSize = height * 0.15;
 
   const pieces = [
@@ -525,77 +530,8 @@ game(({ ctx, width, height, loop, canvas, createDrag }) => {
     { x: width * 0.6, y: height * 0.3, color: '#3b82f6' },
   ];
 
-  // Create drag helper - handles coordinate conversion automatically
-  const drag = createDrag();
-
-  function hitTest(x, y) {
-    for (let i = pieces.length - 1; i >= 0; i--) {
-      const p = pieces[i];
-      if (x >= p.x && x < p.x + pieceSize && y >= p.y && y < p.y + pieceSize) {
-        return p;
-      }
-    }
-    return null;
-  }
-
-  canvas.addEventListener('pointerdown', (e) => {
-    canvas.setPointerCapture(e.pointerId); // IMPORTANT: Ensures drag works outside canvas
-    const { x, y } = drag.point(e);        // Convert coordinates
-    const hit = hitTest(x, y);
-    if (hit) {
-      drag.grab(e, hit);                   // Start drag with offset from cursor
-      canvas.style.cursor = 'grabbing';
-    }
-  });
-
-  canvas.addEventListener('pointermove', (e) => {
-    drag.move(e);                          // Updates grabbed object position
-    if (!drag.dragging) {
-      const { x, y } = drag.point(e);
-      canvas.style.cursor = hitTest(x, y) ? 'grab' : 'default';
-    }
-  });
-
-  canvas.addEventListener('pointerup', () => {
-    const dropped = drag.release();        // Returns dropped object (or null)
-    if (dropped) {
-      console.log('Dropped:', dropped);
-    }
-    canvas.style.cursor = 'default';
-  });
-
-  loop(() => {
-    ctx.fillStyle = '#1f2937';
-    ctx.fillRect(0, 0, width, height);
-
-    for (const p of pieces) {
-      ctx.fillStyle = drag.dragging === p ? '#f59e0b' : p.color;
-      ctx.fillRect(p.x, p.y, pieceSize, pieceSize);
-    }
-  });
-});
-```
-
-**CRITICAL: Always use `setPointerCapture()`** - This ensures drags work even when the pointer moves outside the canvas. Without it, fast drags can leave objects stuck mid-drag.
-
-### Recipe 8: Drag and Drop (Manual Pattern)
-
-If you need more control, here's the manual approach with `toStagePoint()`.
-
-```ts
-import { game } from 'star-canvas';
-
-game(({ ctx, width, height, loop, canvas, toStagePoint }) => {
-  const pieceSize = height * 0.15;
-  const pieces = [
-    { x: width * 0.2, y: height * 0.3, color: '#ef4444' },
-    { x: width * 0.4, y: height * 0.4, color: '#10b981' },
-  ];
-
-  // Manual drag state
   let dragging = null;
-  let dragOffsetX = 0;
-  let dragOffsetY = 0;
+  let offsetX = 0, offsetY = 0;
 
   function hitTest(px, py) {
     for (let i = pieces.length - 1; i >= 0; i--) {
@@ -607,34 +543,28 @@ game(({ ctx, width, height, loop, canvas, toStagePoint }) => {
     return null;
   }
 
-  canvas.addEventListener('pointerdown', (e) => {
-    canvas.setPointerCapture(e.pointerId);  // Ensures drag works outside canvas
-    const { x, y } = toStagePoint(e);       // CRITICAL: Convert coordinates!
-    const hit = hitTest(x, y);
-    if (hit) {
-      dragging = hit;
-      dragOffsetX = x - hit.x;              // Store offset
-      dragOffsetY = y - hit.y;
-      canvas.style.cursor = 'grabbing';
+  g.loop(() => {
+    // Grab
+    if (g.tap) {
+      const hit = hitTest(g.tap.x, g.tap.y);
+      if (hit) {
+        dragging = hit;
+        offsetX = hit.x - g.tap.x;  // Offset so piece doesn't jump to cursor
+        offsetY = hit.y - g.tap.y;
+      }
     }
-  });
-
-  canvas.addEventListener('pointermove', (e) => {
-    const { x, y } = toStagePoint(e);  // CRITICAL: Convert here too!
-    if (dragging) {
-      dragging.x = x - dragOffsetX;
-      dragging.y = y - dragOffsetY;
-    } else {
-      canvas.style.cursor = hitTest(x, y) ? 'grab' : 'default';
+    // Move
+    if (dragging && g.pointer.down) {
+      dragging.x = g.pointer.x + offsetX;
+      dragging.y = g.pointer.y + offsetY;
+    }
+    // Drop
+    if (g.released && dragging) {
+      console.log('Dropped:', dragging);
+      dragging = null;
     }
-  });
-
-  canvas.addEventListener('pointerup', () => {
-    dragging = null;
-    canvas.style.cursor = 'default';
-  });
 
-  loop(() => {
+    // Draw
     ctx.fillStyle = '#1f2937';
     ctx.fillRect(0, 0, width, height);
 
@@ -646,16 +576,6 @@ game(({ ctx, width, height, loop, canvas, toStagePoint }) => {
 });
 ```
 
-**Common Drag-Drop Mistakes:**
-
-1. ❌ Forgetting `toStagePoint()` in pointermove → `createDrag()` fixes this
-2. ❌ No drag offset (piece "jumps" to cursor) → `createDrag()` fixes this
-3. ❌ Using `e.clientX/clientY` directly → `createDrag()` fixes this
-4. ❌ Not clearing state on pointerup → `createDrag()` fixes this
-5. ❌ Missing `setPointerCapture()` (drags break outside canvas) → **You must add this!**
-
-**Recommendation:** Use `createDrag()` + `setPointerCapture()` for bulletproof drag-and-drop.
-
 ### Recipe 9: Image Backgrounds
 
 Two patterns for backgrounds: **full-canvas** (unique scenes) or **tileable patterns** (repeating textures).

package/dist/index.d.cts

@@ -72,7 +72,7 @@ interface GameContext {
         x: number;
         y: number;
     };
-    /** Creates a drag state helper for pointer-based dragging. Handles coordinate conversion and offset. */
+    /** @deprecated Use g.tap/g.pointer/g.released polling instead. */
     createDrag: <T extends {
         x: number;
         y: number;
@@ -192,7 +192,7 @@ interface DragState<T extends {
     /** The currently grabbed object (or null) */
     readonly dragging: T | null;
 }
-/** Creates a drag state helper that handles coordinate conversion and offset tracking */
+/** @deprecated Use g.tap/g.pointer/g.released polling for drag-and-drop instead. */
 declare function createDragState<T extends {
     x: number;
     y: number;

package/dist/index.d.ts

@@ -72,7 +72,7 @@ interface GameContext {
         x: number;
         y: number;
     };
-    /** Creates a drag state helper for pointer-based dragging. Handles coordinate conversion and offset. */
+    /** @deprecated Use g.tap/g.pointer/g.released polling instead. */
     createDrag: <T extends {
         x: number;
         y: number;
@@ -192,7 +192,7 @@ interface DragState<T extends {
     /** The currently grabbed object (or null) */
     readonly dragging: T | null;
 }
-/** Creates a drag state helper that handles coordinate conversion and offset tracking */
+/** @deprecated Use g.tap/g.pointer/g.released polling for drag-and-drop instead. */
 declare function createDragState<T extends {
     x: number;
     y: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "star-canvas",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "private": false,
   "description": "Canvas game utilities for reliable game initialization - part of Star SDK.",
   "type": "module",