star-canvas 0.1.0

package/README.md

@@ -0,0 +1,206 @@
+# Star Canvas
+
+Essential DOM utilities for reliable game initialization.
+
+`star-canvas` solves common bugs in web games: event listeners on null elements, canvas sizing issues, and frame-rate dependent speed. It provides a tiny (~1KB), zero-dependency toolkit with a mobile-first design.
+
+This package is part of the **Star SDK**.
+
+## Features
+
+- **Safe Initialization:** Never crash from timing issues with `onReady()`
+- **Delegated Events:** Survive `innerHTML` re-renders with `on()`
+- **Responsive Canvas:** Auto-sizing with DPR handling via `canvas()`
+- **Frame-Rate Independence:** Delta time for consistent speed via `loop()`
+- **Zero Dependencies:** Pure vanilla JavaScript, SSR-safe
+- **Tiny:** <1KB gzipped
+
+## Install
+
+```bash
+yarn add star-canvas
+# or
+npm install star-canvas
+```
+
+## Quick Start
+
+### UI Click Game
+
+```javascript
+import { onReady, mount, on } from 'star-canvas';
+
+onReady(() => {
+  const root = mount('#game-root');
+  let score = 0;
+
+  function render() {
+    root.innerHTML = `
+      <div class="h-screen grid place-items-center bg-purple-900 text-white">
+        <div class="text-center space-y-4">
+          <h1 class="text-4xl font-bold">Score: ${score}</h1>
+          <button id="clickBtn" class="px-8 py-4 rounded-xl bg-cyan-400 text-slate-900 font-bold">
+            Click Me!
+          </button>
+        </div>
+      </div>`;
+  }
+
+  // Delegated event - survives re-renders
+  on(root, 'click', '#clickBtn', () => {
+    score++;
+    render();
+  });
+
+  render();
+});
+```
+
+### Canvas Game
+
+```javascript
+import { onReady, mount, canvas, loop } from 'star-canvas';
+
+onReady(() => {
+  const root = mount('#game-root');
+
+  root.innerHTML = `
+    <div class="h-screen w-screen bg-slate-900">
+      <!-- canvas auto-created here -->
+    </div>`;
+
+  const container = root.firstElementChild;
+  const { ctx, canvas: c } = canvas(container, { pixelRatio: 'device' });
+
+  const player = { x: 50, y: 50, vx: 200 }; // 200 px/sec
+
+  loop((dt) => {
+    // Delta time → same speed on all devices
+    player.x += player.vx * dt;
+
+    // Wrap around
+    if (player.x > c.width) player.x = 0;
+
+    // Render
+    ctx.fillStyle = '#1e293b';
+    ctx.fillRect(0, 0, c.width, c.height);
+
+    ctx.fillStyle = '#22d3ee';
+    ctx.fillRect(player.x, player.y, 32, 32);
+  });
+});
+```
+
+## API
+
+### `onReady(fn: () => void)`
+
+Run callback when DOM is ready. Works with all script loading patterns.
+
+```javascript
+onReady(() => {
+  // Safe to access DOM here
+});
+```
+
+### `mount(selector?: string | Element): HTMLElement`
+
+Ensure a root element exists. Creates `#game-root` if missing.
+
+```javascript
+const root = mount('#game-root'); // guaranteed non-null
+```
+
+### `on(root, type, selector, handler, options?)`
+
+Delegated event listener that survives re-renders.
+
+```javascript
+on(root, 'click', '#button', () => {
+  console.log('Clicked!');
+});
+
+// Later, safe to do:
+root.innerHTML = '<button id="button">Click</button>';
+// Event still works!
+```
+
+### `canvas(root, opts?): { canvas, ctx, resize }`
+
+Auto-sizing canvas with DPR handling.
+
+```javascript
+const { canvas: c, ctx } = canvas(container, { pixelRatio: 'device' });
+// Auto-resizes when container changes
+// Handles retina displays automatically
+```
+
+### `loop(tick): { start, stop }`
+
+RAF loop with delta time for frame-rate independence.
+
+```javascript
+const { stop } = loop((dt) => {
+  player.x += speed * dt; // Same speed on 60Hz and 120Hz
+});
+
+// Later:
+stop();
+```
+
+## Why Star DOM?
+
+### Problem: Event Listeners on Null
+
+```javascript
+// ❌ Breaks if script runs before DOM ready
+const btn = document.getElementById('start');
+btn.addEventListener('click', () => { /* ... */ }); // TypeError!
+```
+
+```javascript
+// ✅ Always works
+import { onReady, mount, on } from 'star-canvas';
+
+onReady(() => {
+  const root = mount();
+  on(root, 'click', '#start', () => { /* ... */ });
+});
+```
+
+### Problem: Canvas Doesn't Resize
+
+```javascript
+// ❌ Fixed size, doesn't adapt
+const canvas = document.createElement('canvas');
+canvas.width = 800;
+canvas.height = 600;
+```
+
+```javascript
+// ✅ Auto-sizes to container
+const { canvas: c } = canvas(container);
+// Resizes when sidebar appears/disappears
+// Handles DPR for crisp rendering
+```
+
+### Problem: Game Speed Varies by Device
+
+```javascript
+// ❌ 2x faster on 120Hz displays
+function gameLoop() {
+  player.x += 5; // 300px/sec on 60Hz, 600px/sec on 120Hz
+  requestAnimationFrame(gameLoop);
+}
+```
+
+```javascript
+// ✅ Same speed everywhere
+loop((dt) => {
+  player.x += 300 * dt; // 300px/sec on ALL devices
+});
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,19 @@
+"use strict";var _=Object.defineProperty;var Y=Object.getOwnPropertyDescriptor;var F=Object.getOwnPropertyNames;var W=Object.prototype.hasOwnProperty;var $=(r,n)=>{for(var o in n)_(r,o,{get:n[o],enumerable:!0})},B=(r,n,o,e)=>{if(n&&typeof n=="object"||typeof n=="function")for(let i of F(n))!W.call(r,i)&&i!==o&&_(r,i,{get:()=>n[i],enumerable:!(e=Y(n,i))||e.enumerable});return r};var P=r=>B(_({},"__esModule",{value:!0}),r);var V={};$(V,{createDragState:()=>X,game:()=>U,version:()=>I});module.exports=P(V);var I="0.7.0",z={landscape:{width:640,height:360},portrait:{width:360,height:640},responsive:{}};function X(r){let n=null,o=0,e=0;return{point(i){return r(i)},grab(i,f){let{x,y:M}=r(i);n=f,o=x-f.x,e=M-f.y},move(i){if(n){let{x:f,y:x}=r(i);n.x=f-o,n.y=x-e}},release(){let i=n;return n=null,i},get dragging(){return n}}}function k(){return typeof window<"u"&&typeof document<"u"}function N(){if(!k()||document.getElementById("star-dom-base"))return;let r=document.createElement("style");r.id="star-dom-base",r.textContent=`
+    html, body { height: 100%; }
+    body {
+      margin: 0; min-height: 100dvh; overflow: hidden; background: #000;
+      -webkit-user-select: none; user-select: none; -webkit-touch-callout: none;
+    }
+    /* Canvas is at z-index 0 */
+    .star-canvas { 
+      position: absolute; inset: 0; width: 100%; height: 100%; 
+      overflow: hidden; touch-action: none; 
+      z-index: 0;
+      display: block;
+    }
+    /* UI overlay - interactive and scrollable by default (standard CSS behavior) */
+    .star-ui {
+      position: absolute; inset: 0; width: 100%; height: 100%;
+      overflow-y: auto; z-index: 10;
+    }
+  `,document.head.appendChild(r)}function U(r,n={}){k()&&(document.readyState==="loading"?document.addEventListener("DOMContentLoaded",()=>H(r,n),{once:!0}):queueMicrotask(()=>H(r,n)))}function H(r,n){if(N(),window.__STAR_DOM__?.destroy)try{window.__STAR_DOM__.destroy()}catch{}document.querySelectorAll(".star-ui, .star-canvas").forEach(t=>t.remove());let o=document.createElement("div");o.className="star-ui",document.body.appendChild(o);let e=document.createElement("canvas");e.className="star-canvas",document.body.appendChild(e);let i=e.getContext("2d",n.contextAttributes??{alpha:!0});if(!i)throw new Error("[star-dom] Failed to get 2D context");if(n.preventContextMenu!==!1){let t=a=>a.preventDefault();e.addEventListener("contextmenu",t)}let f=e.addEventListener.bind(e);e.addEventListener=function(t,a,s){return/^(pointer|mouse|touch)/.test(t)&&(o.style.pointerEvents="none"),f(t,a,s)};let x=n.preset??"landscape",M=z[x]??z.landscape,w=n.width??M.width,E=n.height??M.height,A=n.maxPixelRatio??2,D=n.pixelRatio??"device",C=n.fit??"contain",g=1,c=w??1,u=E??1,R=new Set,T=null,b=[];function q(){return Math.min(typeof D=="number"?Math.max(1,D):Math.max(1,window.devicePixelRatio||1),A)}function p(){g=q();let t=document.body.getBoundingClientRect(),a=Math.max(1,Math.floor(t.width||window.innerWidth||800)),s=Math.max(1,Math.floor(t.height||window.innerHeight||600));if(w&&E){c=w,u=E;let d=c/u,h=a/s,v=1;if(C==="contain"?v=h>d?s/u:a/c:C==="cover"&&(v=h>d?a/c:s/u),C==="stretch")e.style.width="100%",e.style.height="100%";else{let y=Math.floor(c*v),O=Math.floor(u*v);e.style.width=`${y}px`,e.style.height=`${O}px`,e.style.position="absolute",e.style.left=`${Math.floor((a-y)/2)}px`,e.style.top=`${Math.floor((s-O)/2)}px`}}else if(E){u=E;let d=a/s;c=Math.floor(u*d),e.style.width="100%",e.style.height="100%",e.style.position="absolute",e.style.left="0",e.style.top="0"}else if(w){c=w;let d=a/s;u=Math.floor(c/d),e.style.width="100%",e.style.height="100%",e.style.position="absolute",e.style.left="0",e.style.top="0"}else c=a,u=s,e.style.width=`${c}px`,e.style.height=`${u}px`,e.style.position="absolute",e.style.left="0",e.style.top="0";let l=Math.max(1,Math.floor(c*g)),m=Math.max(1,Math.floor(u*g));e.width!==l&&(e.width=l),e.height!==m&&(e.height=m),i.setTransform(g,0,0,g,0,0),R.forEach(d=>d())}let G=new ResizeObserver(p);G.observe(document.body),b.push(()=>G.disconnect()),window.addEventListener("resize",p),b.push(()=>window.removeEventListener("resize",p));let L=window.visualViewport;L&&(L.addEventListener("resize",p),b.push(()=>L.removeEventListener("resize",p)));let S={stage:document.body,canvas:e,ctx:i,get width(){return c},get height(){return u},get dpr(){return g},resize:p,toStagePoint:t=>{let a=e.getBoundingClientRect(),s=(t.clientX-a.left)*(c/a.width),l=(t.clientY-a.top)*(u/a.height);return{x:s,y:l}},createDrag:()=>X(S.toStagePoint),on:(t,a,s,l)=>{let m=h=>{let y=h.target?.closest?.(a);y&&s.call(y,h)};document.addEventListener(t,m,l);let d=()=>document.removeEventListener(t,m,l);return b.push(d),d},loop:t=>{let s=0,l=!1,m=0,d=h=>{if(!l)return;let v=m?Math.min((h-m)/1e3,.1):0;m=h;try{t(v,h)}catch(y){console.error("[star-dom] Game loop error:",y)}s=requestAnimationFrame(d)};return T={get running(){return l},start(){l||(l=!0,m=performance.now(),s=requestAnimationFrame(d))},stop(){l&&(l=!1,cancelAnimationFrame(s))}},T.start(),T},ui:{root:o,render:t=>{o.innerHTML!==t&&(o.innerHTML=t)},el:t=>o.querySelector(t),all:t=>o.querySelectorAll(t)},destroy:()=>{T?.stop(),b.forEach(t=>t()),b=[],R.clear(),e.parentElement&&e.parentElement.removeChild(e),o.parentElement&&o.parentElement.removeChild(o)},scoped:t=>{i.save();try{t()}finally{i.restore()}}};window.__STAR_DOM__={destroy:S.destroy},requestAnimationFrame(()=>requestAnimationFrame(()=>{p();try{r(S)}catch(t){console.error("[star-dom] Game initialization failed:",t)}}))}0&&(module.exports={createDragState,game,version});

package/dist/index.d.cts

@@ -0,0 +1,166 @@
+/**
+ * Star DOM SDK v0.6.7
+ * MIT License
+ * https://buildwithstar.com
+ *
+ * A tiny, reliable DOM & Canvas SDK for browser games.
+ * Solves common LLM bugs: DOM timing, null listeners,
+ * canvas sizing/DPR, and canvas-vs-UI conflicts.
+ *
+ * Designed for LLMs and humans: owns the iframe <body>,
+ * provides a scrollable UI overlay, stable loop with dt,
+ * DPR-correct canvas sizing, and safe delegated events.
+ *
+ * ~1.5KB min+gz, zero deps, SSR-safe, iframe-first.
+ */
+declare const version = "0.7.0";
+declare global {
+    interface Window {
+        __STAR_DOM__?: {
+            destroy: () => void;
+        };
+    }
+}
+type GameTick = (dt: number, now: number) => void;
+interface GameLoop {
+    start: () => void;
+    stop: () => void;
+    readonly running: boolean;
+}
+interface GameUI {
+    /** The root <div> element for UI, stacked on top of the canvas. */
+    readonly root: HTMLElement;
+    /** Safely replaces the content of the UI overlay. */
+    render: (html: string) => void;
+    /** Scoped querySelector for the UI root. */
+    el: <T extends Element = HTMLElement>(selector: string) => T | null;
+    /** Scoped querySelectorAll for the UI root. */
+    all: <T extends Element = HTMLElement>(selector: string) => NodeListOf<T>;
+}
+interface GameContext {
+    /** The root <div> element for the canvas. */
+    readonly stage: HTMLElement;
+    /** The canvas element. */
+    readonly canvas: HTMLCanvasElement;
+    /** The 2D rendering context. */
+    readonly ctx: CanvasRenderingContext2D;
+    /** Logical width (CSS px). Use this for game logic. Default: 640 (landscape) or 360 (portrait). */
+    readonly width: number;
+    /** Logical height (CSS px). Use this for game logic. Default: 360 (landscape) or 640 (portrait). */
+    readonly height: number;
+    /** Effective device pixel ratio. */
+    readonly dpr: number;
+    /** Safely attaches delegated event listeners to the document. */
+    on: (type: string, selector: string, handler: (this: Element, ev: Event) => void, options?: AddEventListenerOptions) => () => void;
+    /** Starts a stable, auto-starting game loop. */
+    loop: (tick: GameTick) => GameLoop;
+    /** The dedicated UI overlay manager. */
+    readonly ui: GameUI;
+    /** Converts DOM event coords to logical stage coords (CSS px). */
+    toStagePoint: (e: {
+        clientX: number;
+        clientY: number;
+    }) => {
+        x: number;
+        y: number;
+    };
+    /** Creates a drag state helper for pointer-based dragging. Handles coordinate conversion and offset. */
+    createDrag: <T extends {
+        x: number;
+        y: number;
+    }>() => DragState<T>;
+    /** Re-calculates stage size (rarely needed). */
+    resize: () => void;
+    /** Cleans up all listeners and observers. */
+    destroy: () => void;
+    /** Runs a function with ctx.save/restore automatically managed. */
+    scoped: (fn: () => void) => void;
+}
+interface GameOptions {
+    /**
+     * Preset for common game orientations (all use 16:9 aspect ratio with letterboxing).
+     * - 'landscape' (default): 640x360, works identically on all devices
+     * - 'portrait': 360x640, for mobile-style games
+     * - 'responsive': No fixed dimensions, fills container (legacy behavior, gameplay varies by device)
+     */
+    preset?: 'landscape' | 'portrait' | 'responsive';
+    /**
+     * Logical width for fixed-size stages (e.g., 800).
+     * Default: 640 (landscape preset).
+     */
+    width?: number;
+    /**
+     * Logical height for fixed-size stages (e.g., 600).
+     * Default: 360 (landscape preset).
+     */
+    height?: number;
+    /**
+     * How a fixed-size stage fits its container.
+     * - 'contain' (default): Letterbox/pillarbox to fit.
+     * - 'cover': Fill container and crop.
+     * - 'stretch': Distort to fill container.
+     */
+    fit?: 'contain' | 'cover' | 'stretch';
+    /**
+     * Backing store DPR. 'device' (default) or a number.
+     */
+    pixelRatio?: 'device' | number;
+    /**
+     * Max cap for 'device' DPR. Default: 2.
+     */
+    maxPixelRatio?: number;
+    /**
+     * 2D context attributes (e.g., { alpha: false }).
+     */
+    contextAttributes?: CanvasRenderingContext2DSettings;
+    /**
+     * Prevent context menu on canvas. Default: true.
+     */
+    preventContextMenu?: boolean;
+}
+/** Drag state helper - handles coordinate conversion and offset tracking */
+interface DragState<T extends {
+    x: number;
+    y: number;
+}> {
+    /** Convert event to stage coordinates (pure function, no side effects) */
+    point: (e: {
+        clientX: number;
+        clientY: number;
+    }) => {
+        x: number;
+        y: number;
+    };
+    /** Start dragging an object - computes offset from cursor to object origin */
+    grab: (e: {
+        clientX: number;
+        clientY: number;
+    }, obj: T) => void;
+    /** Update the grabbed object's position based on pointer movement */
+    move: (e: {
+        clientX: number;
+        clientY: number;
+    }) => void;
+    /** Release the grabbed object and return it (or null if nothing was grabbed) */
+    release: () => T | null;
+    /** The currently grabbed object (or null) */
+    readonly dragging: T | null;
+}
+/** Creates a drag state helper that handles coordinate conversion and offset tracking */
+declare function createDragState<T extends {
+    x: number;
+    y: number;
+}>(toStagePoint: (e: {
+    clientX: number;
+    clientY: number;
+}) => {
+    x: number;
+    y: number;
+}): DragState<T>;
+/**
+ * The main entry point. Runs setup when the DOM is ready,
+ * providing a safe context for building a game.
+ */
+declare function game(setup: (g: GameContext) => void, options?: GameOptions): void;
+
+export { type DragState, type GameContext, type GameLoop, type GameOptions, type GameTick, type GameUI, createDragState, game, version };

package/dist/index.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Star DOM SDK v0.6.7
+ * MIT License
+ * https://buildwithstar.com
+ *
+ * A tiny, reliable DOM & Canvas SDK for browser games.
+ * Solves common LLM bugs: DOM timing, null listeners,
+ * canvas sizing/DPR, and canvas-vs-UI conflicts.
+ *
+ * Designed for LLMs and humans: owns the iframe <body>,
+ * provides a scrollable UI overlay, stable loop with dt,
+ * DPR-correct canvas sizing, and safe delegated events.
+ *
+ * ~1.5KB min+gz, zero deps, SSR-safe, iframe-first.
+ */
+declare const version = "0.7.0";
+declare global {
+    interface Window {
+        __STAR_DOM__?: {
+            destroy: () => void;
+        };
+    }
+}
+type GameTick = (dt: number, now: number) => void;
+interface GameLoop {
+    start: () => void;
+    stop: () => void;
+    readonly running: boolean;
+}
+interface GameUI {
+    /** The root <div> element for UI, stacked on top of the canvas. */
+    readonly root: HTMLElement;
+    /** Safely replaces the content of the UI overlay. */
+    render: (html: string) => void;
+    /** Scoped querySelector for the UI root. */
+    el: <T extends Element = HTMLElement>(selector: string) => T | null;
+    /** Scoped querySelectorAll for the UI root. */
+    all: <T extends Element = HTMLElement>(selector: string) => NodeListOf<T>;
+}
+interface GameContext {
+    /** The root <div> element for the canvas. */
+    readonly stage: HTMLElement;
+    /** The canvas element. */
+    readonly canvas: HTMLCanvasElement;
+    /** The 2D rendering context. */
+    readonly ctx: CanvasRenderingContext2D;
+    /** Logical width (CSS px). Use this for game logic. Default: 640 (landscape) or 360 (portrait). */
+    readonly width: number;
+    /** Logical height (CSS px). Use this for game logic. Default: 360 (landscape) or 640 (portrait). */
+    readonly height: number;
+    /** Effective device pixel ratio. */
+    readonly dpr: number;
+    /** Safely attaches delegated event listeners to the document. */
+    on: (type: string, selector: string, handler: (this: Element, ev: Event) => void, options?: AddEventListenerOptions) => () => void;
+    /** Starts a stable, auto-starting game loop. */
+    loop: (tick: GameTick) => GameLoop;
+    /** The dedicated UI overlay manager. */
+    readonly ui: GameUI;
+    /** Converts DOM event coords to logical stage coords (CSS px). */
+    toStagePoint: (e: {
+        clientX: number;
+        clientY: number;
+    }) => {
+        x: number;
+        y: number;
+    };
+    /** Creates a drag state helper for pointer-based dragging. Handles coordinate conversion and offset. */
+    createDrag: <T extends {
+        x: number;
+        y: number;
+    }>() => DragState<T>;
+    /** Re-calculates stage size (rarely needed). */
+    resize: () => void;
+    /** Cleans up all listeners and observers. */
+    destroy: () => void;
+    /** Runs a function with ctx.save/restore automatically managed. */
+    scoped: (fn: () => void) => void;
+}
+interface GameOptions {
+    /**
+     * Preset for common game orientations (all use 16:9 aspect ratio with letterboxing).
+     * - 'landscape' (default): 640x360, works identically on all devices
+     * - 'portrait': 360x640, for mobile-style games
+     * - 'responsive': No fixed dimensions, fills container (legacy behavior, gameplay varies by device)
+     */
+    preset?: 'landscape' | 'portrait' | 'responsive';
+    /**
+     * Logical width for fixed-size stages (e.g., 800).
+     * Default: 640 (landscape preset).
+     */
+    width?: number;
+    /**
+     * Logical height for fixed-size stages (e.g., 600).
+     * Default: 360 (landscape preset).
+     */
+    height?: number;
+    /**
+     * How a fixed-size stage fits its container.
+     * - 'contain' (default): Letterbox/pillarbox to fit.
+     * - 'cover': Fill container and crop.
+     * - 'stretch': Distort to fill container.
+     */
+    fit?: 'contain' | 'cover' | 'stretch';
+    /**
+     * Backing store DPR. 'device' (default) or a number.
+     */
+    pixelRatio?: 'device' | number;
+    /**
+     * Max cap for 'device' DPR. Default: 2.
+     */
+    maxPixelRatio?: number;
+    /**
+     * 2D context attributes (e.g., { alpha: false }).
+     */
+    contextAttributes?: CanvasRenderingContext2DSettings;
+    /**
+     * Prevent context menu on canvas. Default: true.
+     */
+    preventContextMenu?: boolean;
+}
+/** Drag state helper - handles coordinate conversion and offset tracking */
+interface DragState<T extends {
+    x: number;
+    y: number;
+}> {
+    /** Convert event to stage coordinates (pure function, no side effects) */
+    point: (e: {
+        clientX: number;
+        clientY: number;
+    }) => {
+        x: number;
+        y: number;
+    };
+    /** Start dragging an object - computes offset from cursor to object origin */
+    grab: (e: {
+        clientX: number;
+        clientY: number;
+    }, obj: T) => void;
+    /** Update the grabbed object's position based on pointer movement */
+    move: (e: {
+        clientX: number;
+        clientY: number;
+    }) => void;
+    /** Release the grabbed object and return it (or null if nothing was grabbed) */
+    release: () => T | null;
+    /** The currently grabbed object (or null) */
+    readonly dragging: T | null;
+}
+/** Creates a drag state helper that handles coordinate conversion and offset tracking */
+declare function createDragState<T extends {
+    x: number;
+    y: number;
+}>(toStagePoint: (e: {
+    clientX: number;
+    clientY: number;
+}) => {
+    x: number;
+    y: number;
+}): DragState<T>;
+/**
+ * The main entry point. Runs setup when the DOM is ready,
+ * providing a safe context for building a game.
+ */
+declare function game(setup: (g: GameContext) => void, options?: GameOptions): void;
+
+export { type DragState, type GameContext, type GameLoop, type GameOptions, type GameTick, type GameUI, createDragState, game, version };

package/dist/index.mjs

@@ -0,0 +1,19 @@
+var Y="0.7.0",O={landscape:{width:640,height:360},portrait:{width:360,height:640},responsive:{}};function k(u){let n=null,i=0,e=0;return{point(l){return u(l)},grab(l,f){let{x,y:M}=u(l);n=f,i=x-f.x,e=M-f.y},move(l){if(n){let{x:f,y:x}=u(l);n.x=f-i,n.y=x-e}},release(){let l=n;return n=null,l},get dragging(){return n}}}function H(){return typeof window<"u"&&typeof document<"u"}function q(){if(!H()||document.getElementById("star-dom-base"))return;let u=document.createElement("style");u.id="star-dom-base",u.textContent=`
+    html, body { height: 100%; }
+    body {
+      margin: 0; min-height: 100dvh; overflow: hidden; background: #000;
+      -webkit-user-select: none; user-select: none; -webkit-touch-callout: none;
+    }
+    /* Canvas is at z-index 0 */
+    .star-canvas { 
+      position: absolute; inset: 0; width: 100%; height: 100%; 
+      overflow: hidden; touch-action: none; 
+      z-index: 0;
+      display: block;
+    }
+    /* UI overlay - interactive and scrollable by default (standard CSS behavior) */
+    .star-ui {
+      position: absolute; inset: 0; width: 100%; height: 100%;
+      overflow-y: auto; z-index: 10;
+    }
+  `,document.head.appendChild(u)}function F(u,n={}){H()&&(document.readyState==="loading"?document.addEventListener("DOMContentLoaded",()=>z(u,n),{once:!0}):queueMicrotask(()=>z(u,n)))}function z(u,n){if(q(),window.__STAR_DOM__?.destroy)try{window.__STAR_DOM__.destroy()}catch{}document.querySelectorAll(".star-ui, .star-canvas").forEach(t=>t.remove());let i=document.createElement("div");i.className="star-ui",document.body.appendChild(i);let e=document.createElement("canvas");e.className="star-canvas",document.body.appendChild(e);let l=e.getContext("2d",n.contextAttributes??{alpha:!0});if(!l)throw new Error("[star-dom] Failed to get 2D context");if(n.preventContextMenu!==!1){let t=r=>r.preventDefault();e.addEventListener("contextmenu",t)}let f=e.addEventListener.bind(e);e.addEventListener=function(t,r,o){return/^(pointer|mouse|touch)/.test(t)&&(i.style.pointerEvents="none"),f(t,r,o)};let x=n.preset??"landscape",M=O[x]??O.landscape,w=n.width??M.width,E=n.height??M.height,_=n.maxPixelRatio??2,A=n.pixelRatio??"device",C=n.fit??"contain",g=1,d=w??1,c=E??1,D=new Set,T=null,b=[];function X(){return Math.min(typeof A=="number"?Math.max(1,A):Math.max(1,window.devicePixelRatio||1),_)}function p(){g=X();let t=document.body.getBoundingClientRect(),r=Math.max(1,Math.floor(t.width||window.innerWidth||800)),o=Math.max(1,Math.floor(t.height||window.innerHeight||600));if(w&&E){d=w,c=E;let s=d/c,h=r/o,v=1;if(C==="contain"?v=h>s?o/c:r/d:C==="cover"&&(v=h>s?r/d:o/c),C==="stretch")e.style.width="100%",e.style.height="100%";else{let y=Math.floor(d*v),G=Math.floor(c*v);e.style.width=`${y}px`,e.style.height=`${G}px`,e.style.position="absolute",e.style.left=`${Math.floor((r-y)/2)}px`,e.style.top=`${Math.floor((o-G)/2)}px`}}else if(E){c=E;let s=r/o;d=Math.floor(c*s),e.style.width="100%",e.style.height="100%",e.style.position="absolute",e.style.left="0",e.style.top="0"}else if(w){d=w;let s=r/o;c=Math.floor(d/s),e.style.width="100%",e.style.height="100%",e.style.position="absolute",e.style.left="0",e.style.top="0"}else d=r,c=o,e.style.width=`${d}px`,e.style.height=`${c}px`,e.style.position="absolute",e.style.left="0",e.style.top="0";let a=Math.max(1,Math.floor(d*g)),m=Math.max(1,Math.floor(c*g));e.width!==a&&(e.width=a),e.height!==m&&(e.height=m),l.setTransform(g,0,0,g,0,0),D.forEach(s=>s())}let R=new ResizeObserver(p);R.observe(document.body),b.push(()=>R.disconnect()),window.addEventListener("resize",p),b.push(()=>window.removeEventListener("resize",p));let L=window.visualViewport;L&&(L.addEventListener("resize",p),b.push(()=>L.removeEventListener("resize",p)));let S={stage:document.body,canvas:e,ctx:l,get width(){return d},get height(){return c},get dpr(){return g},resize:p,toStagePoint:t=>{let r=e.getBoundingClientRect(),o=(t.clientX-r.left)*(d/r.width),a=(t.clientY-r.top)*(c/r.height);return{x:o,y:a}},createDrag:()=>k(S.toStagePoint),on:(t,r,o,a)=>{let m=h=>{let y=h.target?.closest?.(r);y&&o.call(y,h)};document.addEventListener(t,m,a);let s=()=>document.removeEventListener(t,m,a);return b.push(s),s},loop:t=>{let o=0,a=!1,m=0,s=h=>{if(!a)return;let v=m?Math.min((h-m)/1e3,.1):0;m=h;try{t(v,h)}catch(y){console.error("[star-dom] Game loop error:",y)}o=requestAnimationFrame(s)};return T={get running(){return a},start(){a||(a=!0,m=performance.now(),o=requestAnimationFrame(s))},stop(){a&&(a=!1,cancelAnimationFrame(o))}},T.start(),T},ui:{root:i,render:t=>{i.innerHTML!==t&&(i.innerHTML=t)},el:t=>i.querySelector(t),all:t=>i.querySelectorAll(t)},destroy:()=>{T?.stop(),b.forEach(t=>t()),b=[],D.clear(),e.parentElement&&e.parentElement.removeChild(e),i.parentElement&&i.parentElement.removeChild(i)},scoped:t=>{l.save();try{t()}finally{l.restore()}}};window.__STAR_DOM__={destroy:S.destroy},requestAnimationFrame(()=>requestAnimationFrame(()=>{p();try{u(S)}catch(t){console.error("[star-dom] Game initialization failed:",t)}}))}export{k as createDragState,F as game,Y as version};

package/dist/legacy.cjs

@@ -0,0 +1,19 @@
+"use strict";var S=Object.defineProperty;var W=Object.getOwnPropertyDescriptor;var $=Object.getOwnPropertyNames;var B=Object.prototype.hasOwnProperty;var I=(o,t)=>{for(var r in t)S(o,r,{get:t[r],enumerable:!0})},P=(o,t,r,e)=>{if(t&&typeof t=="object"||typeof t=="function")for(let i of $(t))!B.call(o,i)&&i!==r&&S(o,i,{get:()=>t[i],enumerable:!(e=W(t,i))||e.enumerable});return o};var U=o=>P(S({},"__esModule",{value:!0}),o);var j={};I(j,{createDragState:()=>_,game:()=>V,version:()=>X});module.exports=U(j);var X="0.7.0",H={landscape:{width:640,height:360},portrait:{width:360,height:640},responsive:{}};function _(o){let t=null,r=0,e=0;return{point(i){return o(i)},grab(i,p){let{x,y:M}=o(i);t=p,r=x-p.x,e=M-p.y},move(i){if(t){let{x:p,y:x}=o(i);t.x=p-r,t.y=x-e}},release(){let i=t;return t=null,i},get dragging(){return t}}}function q(){return typeof window<"u"&&typeof document<"u"}function N(){if(!q()||document.getElementById("star-dom-base"))return;let o=document.createElement("style");o.id="star-dom-base",o.textContent=`
+    html, body { height: 100%; }
+    body {
+      margin: 0; min-height: 100dvh; overflow: hidden; background: #000;
+      -webkit-user-select: none; user-select: none; -webkit-touch-callout: none;
+    }
+    /* Canvas is at z-index 0 */
+    .star-canvas { 
+      position: absolute; inset: 0; width: 100%; height: 100%; 
+      overflow: hidden; touch-action: none; 
+      z-index: 0;
+      display: block;
+    }
+    /* UI overlay - interactive and scrollable by default (standard CSS behavior) */
+    .star-ui {
+      position: absolute; inset: 0; width: 100%; height: 100%;
+      overflow-y: auto; z-index: 10;
+    }
+  `,document.head.appendChild(o)}function Y(o,t={}){q()&&(document.readyState==="loading"?document.addEventListener("DOMContentLoaded",()=>k(o,t),{once:!0}):queueMicrotask(()=>k(o,t)))}function k(o,t){if(N(),window.__STAR_DOM__?.destroy)try{window.__STAR_DOM__.destroy()}catch{}document.querySelectorAll(".star-ui, .star-canvas").forEach(n=>n.remove());let r=document.createElement("div");r.className="star-ui",document.body.appendChild(r);let e=document.createElement("canvas");e.className="star-canvas",document.body.appendChild(e);let i=e.getContext("2d",t.contextAttributes??{alpha:!0});if(!i)throw new Error("[star-dom] Failed to get 2D context");if(t.preventContextMenu!==!1){let n=a=>a.preventDefault();e.addEventListener("contextmenu",n)}let p=e.addEventListener.bind(e);e.addEventListener=function(n,a,s){return/^(pointer|mouse|touch)/.test(n)&&(r.style.pointerEvents="none"),p(n,a,s)};let x=t.preset??"landscape",M=H[x]??H.landscape,w=t.width??M.width,E=t.height??M.height,A=t.maxPixelRatio??2,D=t.pixelRatio??"device",C=t.fit??"contain",g=1,c=w??1,u=E??1,O=new Set,T=null,b=[];function F(){return Math.min(typeof D=="number"?Math.max(1,D):Math.max(1,window.devicePixelRatio||1),A)}function f(){g=F();let n=document.body.getBoundingClientRect(),a=Math.max(1,Math.floor(n.width||window.innerWidth||800)),s=Math.max(1,Math.floor(n.height||window.innerHeight||600));if(w&&E){c=w,u=E;let d=c/u,h=a/s,v=1;if(C==="contain"?v=h>d?s/u:a/c:C==="cover"&&(v=h>d?a/c:s/u),C==="stretch")e.style.width="100%",e.style.height="100%";else{let y=Math.floor(c*v),z=Math.floor(u*v);e.style.width=`${y}px`,e.style.height=`${z}px`,e.style.position="absolute",e.style.left=`${Math.floor((a-y)/2)}px`,e.style.top=`${Math.floor((s-z)/2)}px`}}else if(E){u=E;let d=a/s;c=Math.floor(u*d),e.style.width="100%",e.style.height="100%",e.style.position="absolute",e.style.left="0",e.style.top="0"}else if(w){c=w;let d=a/s;u=Math.floor(c/d),e.style.width="100%",e.style.height="100%",e.style.position="absolute",e.style.left="0",e.style.top="0"}else c=a,u=s,e.style.width=`${c}px`,e.style.height=`${u}px`,e.style.position="absolute",e.style.left="0",e.style.top="0";let l=Math.max(1,Math.floor(c*g)),m=Math.max(1,Math.floor(u*g));e.width!==l&&(e.width=l),e.height!==m&&(e.height=m),i.setTransform(g,0,0,g,0,0),O.forEach(d=>d())}let R=new ResizeObserver(f);R.observe(document.body),b.push(()=>R.disconnect()),window.addEventListener("resize",f),b.push(()=>window.removeEventListener("resize",f));let L=window.visualViewport;L&&(L.addEventListener("resize",f),b.push(()=>L.removeEventListener("resize",f)));let G={stage:document.body,canvas:e,ctx:i,get width(){return c},get height(){return u},get dpr(){return g},resize:f,toStagePoint:n=>{let a=e.getBoundingClientRect(),s=(n.clientX-a.left)*(c/a.width),l=(n.clientY-a.top)*(u/a.height);return{x:s,y:l}},createDrag:()=>_(G.toStagePoint),on:(n,a,s,l)=>{let m=h=>{let y=h.target?.closest?.(a);y&&s.call(y,h)};document.addEventListener(n,m,l);let d=()=>document.removeEventListener(n,m,l);return b.push(d),d},loop:n=>{let s=0,l=!1,m=0,d=h=>{if(!l)return;let v=m?Math.min((h-m)/1e3,.1):0;m=h;try{n(v,h)}catch(y){console.error("[star-dom] Game loop error:",y)}s=requestAnimationFrame(d)};return T={get running(){return l},start(){l||(l=!0,m=performance.now(),s=requestAnimationFrame(d))},stop(){l&&(l=!1,cancelAnimationFrame(s))}},T.start(),T},ui:{root:r,render:n=>{r.innerHTML!==n&&(r.innerHTML=n)},el:n=>r.querySelector(n),all:n=>r.querySelectorAll(n)},destroy:()=>{T?.stop(),b.forEach(n=>n()),b=[],O.clear(),e.parentElement&&e.parentElement.removeChild(e),r.parentElement&&r.parentElement.removeChild(r)},scoped:n=>{i.save();try{n()}finally{i.restore()}}};window.__STAR_DOM__={destroy:G.destroy},requestAnimationFrame(()=>requestAnimationFrame(()=>{f();try{o(G)}catch(n){console.error("[star-dom] Game initialization failed:",n)}}))}function V(o,t={}){let r={preset:"responsive",...t};return Y(o,r)}0&&(module.exports={createDragState,game,version});

package/dist/legacy.d.cts

@@ -0,0 +1,19 @@
+import { GameContext, GameOptions } from './index.cjs';
+export { DragState, GameLoop, GameTick, GameUI, createDragState, version } from './index.cjs';
+
+/**
+ * Star DOM SDK - Legacy Entry Point
+ *
+ * This entry point preserves backward compatibility with games created before v0.7.
+ * It defaults to 'responsive' mode (no fixed dimensions).
+ *
+ * New games should use the main entry point which defaults to 'landscape' preset.
+ */
+
+/**
+ * Legacy game entry point - defaults to responsive mode for backward compatibility.
+ * New games should use '/star-sdk/dom-v1.js' which defaults to fixed-height mode.
+ */
+declare function game(setup: (g: GameContext) => void, options?: GameOptions): void;
+
+export { GameContext, GameOptions, game };

package/dist/legacy.d.ts

@@ -0,0 +1,19 @@
+import { GameContext, GameOptions } from './index.js';
+export { DragState, GameLoop, GameTick, GameUI, createDragState, version } from './index.js';
+
+/**
+ * Star DOM SDK - Legacy Entry Point
+ *
+ * This entry point preserves backward compatibility with games created before v0.7.
+ * It defaults to 'responsive' mode (no fixed dimensions).
+ *
+ * New games should use the main entry point which defaults to 'landscape' preset.
+ */
+
+/**
+ * Legacy game entry point - defaults to responsive mode for backward compatibility.
+ * New games should use '/star-sdk/dom-v1.js' which defaults to fixed-height mode.
+ */
+declare function game(setup: (g: GameContext) => void, options?: GameOptions): void;
+
+export { GameContext, GameOptions, game };

package/dist/legacy.mjs

@@ -0,0 +1,19 @@
+var Y="0.7.0",R={landscape:{width:640,height:360},portrait:{width:360,height:640},responsive:{}};function H(a){let n=null,i=0,e=0;return{point(d){return a(d)},grab(d,p){let{x,y:M}=a(d);n=p,i=x-p.x,e=M-p.y},move(d){if(n){let{x:p,y:x}=a(d);n.x=p-i,n.y=x-e}},release(){let d=n;return n=null,d},get dragging(){return n}}}function k(){return typeof window<"u"&&typeof document<"u"}function F(){if(!k()||document.getElementById("star-dom-base"))return;let a=document.createElement("style");a.id="star-dom-base",a.textContent=`
+    html, body { height: 100%; }
+    body {
+      margin: 0; min-height: 100dvh; overflow: hidden; background: #000;
+      -webkit-user-select: none; user-select: none; -webkit-touch-callout: none;
+    }
+    /* Canvas is at z-index 0 */
+    .star-canvas { 
+      position: absolute; inset: 0; width: 100%; height: 100%; 
+      overflow: hidden; touch-action: none; 
+      z-index: 0;
+      display: block;
+    }
+    /* UI overlay - interactive and scrollable by default (standard CSS behavior) */
+    .star-ui {
+      position: absolute; inset: 0; width: 100%; height: 100%;
+      overflow-y: auto; z-index: 10;
+    }
+  `,document.head.appendChild(a)}function X(a,n={}){k()&&(document.readyState==="loading"?document.addEventListener("DOMContentLoaded",()=>z(a,n),{once:!0}):queueMicrotask(()=>z(a,n)))}function z(a,n){if(F(),window.__STAR_DOM__?.destroy)try{window.__STAR_DOM__.destroy()}catch{}document.querySelectorAll(".star-ui, .star-canvas").forEach(t=>t.remove());let i=document.createElement("div");i.className="star-ui",document.body.appendChild(i);let e=document.createElement("canvas");e.className="star-canvas",document.body.appendChild(e);let d=e.getContext("2d",n.contextAttributes??{alpha:!0});if(!d)throw new Error("[star-dom] Failed to get 2D context");if(n.preventContextMenu!==!1){let t=o=>o.preventDefault();e.addEventListener("contextmenu",t)}let p=e.addEventListener.bind(e);e.addEventListener=function(t,o,r){return/^(pointer|mouse|touch)/.test(t)&&(i.style.pointerEvents="none"),p(t,o,r)};let x=n.preset??"landscape",M=R[x]??R.landscape,w=n.width??M.width,E=n.height??M.height,S=n.maxPixelRatio??2,_=n.pixelRatio??"device",C=n.fit??"contain",g=1,c=w??1,u=E??1,A=new Set,T=null,b=[];function q(){return Math.min(typeof _=="number"?Math.max(1,_):Math.max(1,window.devicePixelRatio||1),S)}function f(){g=q();let t=document.body.getBoundingClientRect(),o=Math.max(1,Math.floor(t.width||window.innerWidth||800)),r=Math.max(1,Math.floor(t.height||window.innerHeight||600));if(w&&E){c=w,u=E;let l=c/u,h=o/r,v=1;if(C==="contain"?v=h>l?r/u:o/c:C==="cover"&&(v=h>l?o/c:r/u),C==="stretch")e.style.width="100%",e.style.height="100%";else{let y=Math.floor(c*v),O=Math.floor(u*v);e.style.width=`${y}px`,e.style.height=`${O}px`,e.style.position="absolute",e.style.left=`${Math.floor((o-y)/2)}px`,e.style.top=`${Math.floor((r-O)/2)}px`}}else if(E){u=E;let l=o/r;c=Math.floor(u*l),e.style.width="100%",e.style.height="100%",e.style.position="absolute",e.style.left="0",e.style.top="0"}else if(w){c=w;let l=o/r;u=Math.floor(c/l),e.style.width="100%",e.style.height="100%",e.style.position="absolute",e.style.left="0",e.style.top="0"}else c=o,u=r,e.style.width=`${c}px`,e.style.height=`${u}px`,e.style.position="absolute",e.style.left="0",e.style.top="0";let s=Math.max(1,Math.floor(c*g)),m=Math.max(1,Math.floor(u*g));e.width!==s&&(e.width=s),e.height!==m&&(e.height=m),d.setTransform(g,0,0,g,0,0),A.forEach(l=>l())}let D=new ResizeObserver(f);D.observe(document.body),b.push(()=>D.disconnect()),window.addEventListener("resize",f),b.push(()=>window.removeEventListener("resize",f));let L=window.visualViewport;L&&(L.addEventListener("resize",f),b.push(()=>L.removeEventListener("resize",f)));let G={stage:document.body,canvas:e,ctx:d,get width(){return c},get height(){return u},get dpr(){return g},resize:f,toStagePoint:t=>{let o=e.getBoundingClientRect(),r=(t.clientX-o.left)*(c/o.width),s=(t.clientY-o.top)*(u/o.height);return{x:r,y:s}},createDrag:()=>H(G.toStagePoint),on:(t,o,r,s)=>{let m=h=>{let y=h.target?.closest?.(o);y&&r.call(y,h)};document.addEventListener(t,m,s);let l=()=>document.removeEventListener(t,m,s);return b.push(l),l},loop:t=>{let r=0,s=!1,m=0,l=h=>{if(!s)return;let v=m?Math.min((h-m)/1e3,.1):0;m=h;try{t(v,h)}catch(y){console.error("[star-dom] Game loop error:",y)}r=requestAnimationFrame(l)};return T={get running(){return s},start(){s||(s=!0,m=performance.now(),r=requestAnimationFrame(l))},stop(){s&&(s=!1,cancelAnimationFrame(r))}},T.start(),T},ui:{root:i,render:t=>{i.innerHTML!==t&&(i.innerHTML=t)},el:t=>i.querySelector(t),all:t=>i.querySelectorAll(t)},destroy:()=>{T?.stop(),b.forEach(t=>t()),b=[],A.clear(),e.parentElement&&e.parentElement.removeChild(e),i.parentElement&&i.parentElement.removeChild(i)},scoped:t=>{d.save();try{t()}finally{d.restore()}}};window.__STAR_DOM__={destroy:G.destroy},requestAnimationFrame(()=>requestAnimationFrame(()=>{f();try{a(G)}catch(t){console.error("[star-dom] Game initialization failed:",t)}}))}function B(a,n={}){let i={preset:"responsive",...n};return X(a,i)}export{H as createDragState,B as game,Y as version};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "star-canvas",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Canvas game utilities for reliable game initialization - part of Star SDK.",
+  "type": "module",
+  "sideEffects": false,
+  "starSdk": {
+    "internalImport": "import { game } from '/star-sdk/v1/dom.js';",
+    "publicImport": "import { game } from 'star-canvas';",
+    "publicPath": "dist/index.mjs",
+    "outputs": [
+      { "src": "dist/legacy.mjs", "dest": "dom.js" },
+      { "src": "dist/index.mjs", "dest": "v1/dom.js" }
+    ],
+    "skill": {
+      "name": "star-dom-sdk",
+      "description": "Star DOM SDK for canvas games and UI. Use when working with canvas rendering, game loops, sprites, input handling, UI overlays, or the game() initialization function."
+    }
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.mjs",
+      "require": "./dist/*.cjs"
+    }
+  },
+  "module": "./dist/index.mjs",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "node ../../apps/web/scripts/process-sdks.js --package star-canvas --public-only && yarn build"
+  },
+  "keywords": [
+    "dom",
+    "canvas",
+    "game-loop",
+    "mobile",
+    "responsive",
+    "dpr",
+    "retina",
+    "games",
+    "web",
+    "nextjs",
+    "vite",
+    "typescript"
+  ],
+  "dependencies": {},
+  "devDependencies": {
+    "tsup": "^8.0.2",
+    "typescript": "^5.4.5"
+  }
+}