@norarcasey/arkanora 0.1.0

package/README.md

@@ -0,0 +1,70 @@
+# Arkanora 🧱
+
+An embeddable React + TypeScript breakout game. Slide the paddle with your
+**mouse** (or the **arrow keys** / **A,D**), keep the ball alive, and smash
+every brick. Miss the ball and you lose a life.
+
+Built with **Vite** and tested with **Vitest** + **React Testing Library**.
+
+## Quick start
+
+```bash
+npm install
+npm run dev        # demo site at http://localhost:5173
+npm test           # run the test suite
+npm run build      # build the demo site for deployment
+npm run build:lib  # build the embeddable component library
+```
+
+## Embedding the component
+
+```tsx
+import { Arkanora } from '@norarcasey/arkanora'
+import '@norarcasey/arkanora/style.css'
+
+export function App() {
+  return <Arkanora />
+}
+```
+
+`react` / `react-dom` are peer dependencies you already have.
+
+### Props
+
+| Prop             | Type             | Default      | Description                                          |
+| ---------------- | ---------------- | ------------ | ---------------------------------------------------- |
+| `rows`           | `number`         | `5`          | Number of brick rows.                                |
+| `cols`           | `number`         | `9`          | Number of brick columns.                             |
+| `lives`          | `number`         | `3`          | Lives before the game is over.                       |
+| `speed`          | `number`         | `16`         | Milliseconds between physics ticks (lower = faster). |
+| `enableKeyboard` | `boolean`        | `true`       | Steer the paddle with the arrow keys / A,D.          |
+| `title`          | `string \| null` | `"Arkanora"` | Heading above the board; pass `null` to hide it.     |
+| `className`      | `string`         | —            | Extra class on the root element.                     |
+
+### Headless engine
+
+The game logic lives in a framework-free hook if you want to build your own UI:
+
+```tsx
+import { useArkanora } from '@norarcasey/arkanora'
+
+const game = useArkanora({ rows: 6, cols: 10 })
+// game.ball, game.bricks, game.paddleX, game.score, game.lives, game.status
+// game.start(), game.reset(), game.movePaddle(x), game.nudgePaddle(dx)
+```
+
+The playfield is a fixed 100×100 unit square; positions and sizes are in those
+units so the board scales to any pixel size.
+
+## Roadmap
+
+This is the MVP: paddle, ball, bricks, lives, win/lose. Planned flavor —
+multi-hit bricks, power-ups (multiball, wide paddle), and per-row scoring.
+
+Rendering is currently DOM-based, which is fine at this scale; a `<canvas>`
+renderer is the natural next step if we add particle effects or smooth trails
+(the engine is already decoupled from the view, so it'd be a Board-only swap).
+
+## License
+
+MIT © Nora Casey

package/dist/arkanora.js

@@ -0,0 +1,231 @@
+import { jsxs as k, jsx as y } from "react/jsx-runtime";
+import { useReducer as Y, useEffect as A, useCallback as b } from "react";
+const m = 100, S = 100, x = 18, R = 2.6, _ = 92, c = 1.6, P = 1.25, E = 0.35, H = 1.05, M = 6, I = 10, X = 4, $ = 1.4, D = 1.4, B = 3, g = { rows: 5, cols: 9, lives: 3, speed: 16 };
+function L(a, n, e) {
+  return Math.min(e, Math.max(n, a));
+}
+function O(a, n) {
+  const e = (m - 2 * B - D * (n - 1)) / n, i = [];
+  for (let l = 0; l < a; l++)
+    for (let s = 0; s < n; s++)
+      i.push({
+        x: B + s * (e + D),
+        y: I + l * (X + $),
+        w: e,
+        h: X,
+        alive: !0
+      });
+  return i;
+}
+function C(a) {
+  return {
+    x: a,
+    y: _ - c - 0.2,
+    vx: P * Math.sin(E),
+    vy: -P * Math.cos(E)
+  };
+}
+function w(a, n, e) {
+  return {
+    rows: a,
+    cols: n,
+    maxLives: e,
+    ball: C(m / 2),
+    paddleX: m / 2,
+    bricks: O(a, n),
+    status: "idle",
+    score: 0,
+    lives: e
+  };
+}
+function G(a, n) {
+  switch (n.type) {
+    case "configure":
+      return w(n.rows, n.cols, n.lives);
+    case "reset":
+      return w(a.rows, a.cols, a.maxLives);
+    case "start":
+      return { ...w(a.rows, a.cols, a.maxLives), status: "running" };
+    case "movePaddle":
+      return { ...a, paddleX: L(n.x, x / 2, m - x / 2) };
+    case "nudgePaddle":
+      return { ...a, paddleX: L(a.paddleX + n.dx, x / 2, m - x / 2) };
+    case "tick": {
+      if (a.status !== "running") return a;
+      const e = {
+        x: a.ball.x + a.ball.vx,
+        y: a.ball.y + a.ball.vy,
+        vx: a.ball.vx,
+        vy: a.ball.vy
+      };
+      e.x - c < 0 ? (e.x = c, e.vx = Math.abs(e.vx)) : e.x + c > m && (e.x = m - c, e.vx = -Math.abs(e.vx)), e.y - c < 0 && (e.y = c, e.vy = Math.abs(e.vy));
+      const i = x / 2;
+      if (e.vy > 0 && e.y + c >= _ && e.y - c <= _ + R && e.x >= a.paddleX - i && e.x <= a.paddleX + i) {
+        const r = L((e.x - a.paddleX) / i, -1, 1) * H;
+        e.vx = P * Math.sin(r), e.vy = -P * Math.cos(r), e.y = _ - c;
+      }
+      let l = a.bricks, s = a.score;
+      for (let t = 0; t < l.length; t++) {
+        const r = l[t];
+        if (!r.alive) continue;
+        const u = e.x + c > r.x && e.x - c < r.x + r.w, o = e.y + c > r.y && e.y - c < r.y + r.h;
+        if (!u || !o) continue;
+        const p = Math.min(e.x + c, r.x + r.w) - Math.max(e.x - c, r.x), h = Math.min(e.y + c, r.y + r.h) - Math.max(e.y - c, r.y);
+        p < h ? e.vx = -e.vx : e.vy = -e.vy, l = l.map((f, d) => d === t ? { ...f, alive: !1 } : f), s += 1;
+        break;
+      }
+      if (e.y - c > S) {
+        const t = a.lives - 1;
+        return t <= 0 ? { ...a, ball: e, bricks: l, score: s, lives: 0, status: "over" } : { ...a, bricks: l, score: s, lives: t, ball: C(a.paddleX) };
+      }
+      return l.every((t) => !t.alive) ? { ...a, ball: e, bricks: l, score: s, status: "won" } : { ...a, ball: e, bricks: l, score: s };
+    }
+  }
+}
+function T(a = {}) {
+  const n = a.rows ?? g.rows, e = a.cols ?? g.cols, i = a.lives ?? g.lives, l = a.speed ?? g.speed, [s, t] = Y(G, void 0, () => w(n, e, i));
+  A(() => {
+    t({ type: "configure", rows: n, cols: e, lives: i });
+  }, [n, e, i]);
+  const r = b(() => t({ type: "start" }), []), u = b(() => t({ type: "reset" }), []), o = b((h) => t({ type: "movePaddle", x: h }), []), p = b((h) => t({ type: "nudgePaddle", dx: h }), []);
+  return A(() => {
+    if (s.status !== "running") return;
+    const h = setInterval(() => t({ type: "tick" }), l);
+    return () => clearInterval(h);
+  }, [s.status, l]), {
+    width: m,
+    height: S,
+    ball: s.ball,
+    ballRadius: c,
+    paddleX: s.paddleX,
+    paddleWidth: x,
+    paddleHeight: R,
+    paddleY: _,
+    bricks: s.bricks,
+    status: s.status,
+    score: s.score,
+    lives: s.lives,
+    start: r,
+    reset: u,
+    movePaddle: o,
+    nudgePaddle: p
+  };
+}
+function j({
+  width: a,
+  height: n,
+  ball: e,
+  ballRadius: i,
+  paddleX: l,
+  paddleWidth: s,
+  paddleHeight: t,
+  paddleY: r,
+  bricks: u
+}) {
+  const o = (d, v) => `${d / v * 100}%`, p = { aspectRatio: `${a} / ${n}` }, h = {
+    left: o(e.x - i, a),
+    top: o(e.y - i, n),
+    width: o(i * 2, a),
+    height: o(i * 2, n)
+  }, f = {
+    left: o(l - s / 2, a),
+    top: o(r, n),
+    width: o(s, a),
+    height: o(t, n)
+  };
+  return /* @__PURE__ */ k("div", { className: "arkanora__board", style: p, "data-testid": "board", children: [
+    u.map(
+      (d, v) => d.alive ? /* @__PURE__ */ y(
+        "div",
+        {
+          className: "arkanora__brick",
+          style: {
+            left: o(d.x, a),
+            top: o(d.y, n),
+            width: o(d.w, a),
+            height: o(d.h, n),
+            // Color rows along a hue ramp for a retro rainbow wall.
+            backgroundColor: `hsl(${d.y * 7 % 360} 80% 58%)`
+          },
+          "aria-hidden": !0
+        },
+        v
+      ) : null
+    ),
+    /* @__PURE__ */ y("div", { className: "arkanora__paddle", style: f, "aria-hidden": !0 }),
+    /* @__PURE__ */ y("div", { className: "arkanora__ball", style: h, "aria-hidden": !0 })
+  ] });
+}
+function F({
+  rows: a,
+  cols: n,
+  lives: e,
+  speed: i,
+  enableKeyboard: l = !0,
+  title: s = "Arkanora",
+  className: t
+}) {
+  const r = T({ rows: a, cols: n, lives: e, speed: i }), { status: u, start: o, nudgePaddle: p } = r;
+  A(() => {
+    if (!l) return;
+    const d = (v) => {
+      const N = v.key === "ArrowLeft" || v.key === "a", W = v.key === "ArrowRight" || v.key === "d";
+      !N && !W || (v.preventDefault(), u !== "running" && o(), p(N ? -M : M));
+    };
+    return window.addEventListener("keydown", d), () => window.removeEventListener("keydown", d);
+  }, [l, u, o, p]);
+  const h = (d) => {
+    const v = d.currentTarget.getBoundingClientRect();
+    v.width !== 0 && r.movePaddle((d.clientX - v.left) / v.width * r.width);
+  }, f = u === "over" || u === "won";
+  return /* @__PURE__ */ k(
+    "section",
+    {
+      className: `arkanora${t ? ` ${t}` : ""}`,
+      "aria-label": s ?? "Breakout game",
+      children: [
+        /* @__PURE__ */ k("header", { className: "arkanora__header", children: [
+          s !== null && /* @__PURE__ */ y("h2", { className: "arkanora__title", children: s }),
+          /* @__PURE__ */ k("span", { className: "arkanora__stat", "aria-live": "polite", children: [
+            "Score: ",
+            r.score
+          ] }),
+          /* @__PURE__ */ k("span", { className: "arkanora__stat", "aria-live": "polite", children: [
+            "Lives: ",
+            r.lives
+          ] })
+        ] }),
+        /* @__PURE__ */ k("div", { className: "arkanora__stage", onPointerMove: h, children: [
+          /* @__PURE__ */ y(
+            j,
+            {
+              width: r.width,
+              height: r.height,
+              ball: r.ball,
+              ballRadius: r.ballRadius,
+              paddleX: r.paddleX,
+              paddleWidth: r.paddleWidth,
+              paddleHeight: r.paddleHeight,
+              paddleY: r.paddleY,
+              bricks: r.bricks
+            }
+          ),
+          u !== "running" && /* @__PURE__ */ k("div", { className: "arkanora__overlay", role: "status", children: [
+            u === "idle" && /* @__PURE__ */ y("p", { className: "arkanora__message", children: "Break some bricks!" }),
+            u === "over" && /* @__PURE__ */ k("p", { className: "arkanora__message", children: [
+              "Game over — score ",
+              r.score
+            ] }),
+            u === "won" && /* @__PURE__ */ y("p", { className: "arkanora__message", children: "You cleared the board! 🏆" }),
+            /* @__PURE__ */ y("button", { type: "button", className: "arkanora__button", onClick: o, children: f ? "Play again" : "Start" }),
+            /* @__PURE__ */ y("p", { className: "arkanora__hint", children: "Move with the mouse, or arrow keys / A,D" })
+          ] })
+        ] })
+      ]
+    }
+  );
+}
+export {
+  F as Arkanora,
+  T as useArkanora
+};

package/dist/index.d.ts

@@ -0,0 +1,88 @@
+import { JSX as JSX_2 } from 'react';
+
+export declare function Arkanora({ rows, cols, lives, speed, enableKeyboard, title, className, }: ArkanoraProps): JSX_2.Element;
+
+export declare interface ArkanoraApi {
+    /** Playfield width in units (always 100). */
+    width: number;
+    /** Playfield height in units (always 100). */
+    height: number;
+    ball: Ball;
+    ballRadius: number;
+    /** Center x of the paddle, in units. */
+    paddleX: number;
+    paddleWidth: number;
+    paddleHeight: number;
+    /** The paddle's top edge, in units. */
+    paddleY: number;
+    bricks: Brick[];
+    status: GameStatus;
+    score: number;
+    lives: number;
+    /** Reset the board and serve the ball. */
+    start: () => void;
+    /** Reset the board to `idle` without serving. */
+    reset: () => void;
+    /** Move the paddle so its center sits at unit-x `x` (clamped to the walls). */
+    movePaddle: (x: number) => void;
+    /** Nudge the paddle by `dx` units (clamped to the walls). */
+    nudgePaddle: (dx: number) => void;
+}
+
+export declare interface ArkanoraProps {
+    /** Number of brick rows. Default `5`. */
+    rows?: number;
+    /** Number of brick columns. Default `9`. */
+    cols?: number;
+    /** Lives before the game is over. Default `3`. */
+    lives?: number;
+    /** Milliseconds between physics ticks; lower is smoother/faster. Default `16`. */
+    speed?: number;
+    /** Steer the paddle with the arrow keys / A,D. Default `true`. */
+    enableKeyboard?: boolean;
+    /** Heading shown above the board. Pass `null` to hide it. */
+    title?: string | null;
+    /** Extra class on the root element. */
+    className?: string;
+}
+
+/** The ball: a position and a velocity (units per tick). */
+export declare interface Ball {
+    x: number;
+    y: number;
+    vx: number;
+    vy: number;
+}
+
+/** A single brick. Axis-aligned, top-left origin. */
+export declare interface Brick {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    alive: boolean;
+}
+
+/**
+ * Lifecycle of a single game:
+ *  - `idle`    — board is set up, ball resting on the paddle, waiting to start.
+ *  - `running` — the ball is in play.
+ *  - `over`    — the ball was missed with no lives left.
+ *  - `won`     — every brick has been cleared.
+ */
+export declare type GameStatus = 'idle' | 'running' | 'over' | 'won';
+
+export declare function useArkanora(options?: UseArkanoraOptions): ArkanoraApi;
+
+export declare interface UseArkanoraOptions {
+    /** Number of brick rows. Default `5`. */
+    rows?: number;
+    /** Number of brick columns. Default `9`. */
+    cols?: number;
+    /** Lives before the game is over. Default `3`. */
+    lives?: number;
+    /** Milliseconds between physics ticks; lower is smoother/faster. Default `16`. */
+    speed?: number;
+}
+
+export { }

package/dist/style.css

@@ -0,0 +1 @@
+.arkanora{--arkanora-bg: #0b1020;--arkanora-board: #0e1530;--arkanora-wall: #1b2550;--arkanora-ball: #ffffff;--arkanora-paddle: #38e1ff;--arkanora-accent: #38e1ff;--arkanora-text: #e7ecff;box-sizing:border-box;width:100%;max-width:560px;margin:0 auto;font-family:-apple-system,BlinkMacSystemFont,Segoe UI,Roboto,Oxygen,Ubuntu,Cantarell,Helvetica Neue,sans-serif;color:var(--arkanora-text)}.arkanora *,.arkanora *:before,.arkanora *:after{box-sizing:border-box}.arkanora__header{display:flex;align-items:baseline;gap:1rem;margin-bottom:.75rem}.arkanora__title{margin:0 auto 0 0;font-size:1.4rem;font-weight:700}.arkanora__stat{font-variant-numeric:tabular-nums;font-weight:600;color:var(--arkanora-accent)}.arkanora__stage{position:relative;touch-action:none}.arkanora__board{position:relative;width:100%;background:radial-gradient(120% 120% at 50% 0%,var(--arkanora-board),var(--arkanora-bg));border:2px solid var(--arkanora-wall);border-radius:8px;overflow:hidden;cursor:none}.arkanora__brick{position:absolute;border-radius:2px;box-shadow:inset 0 -2px #00000040}.arkanora__paddle{position:absolute;background:var(--arkanora-paddle);border-radius:3px;box-shadow:0 0 12px var(--arkanora-paddle)}.arkanora__ball{position:absolute;background:var(--arkanora-ball);border-radius:50%;box-shadow:0 0 10px var(--arkanora-ball)}.arkanora__overlay{position:absolute;top:0;right:0;bottom:0;left:0;display:flex;flex-direction:column;align-items:center;justify-content:center;gap:.75rem;background:#060a18cc;border-radius:8px;text-align:center}.arkanora__message{margin:0;font-size:1.25rem;font-weight:700}.arkanora__hint{margin:0;font-size:.85rem;color:var(--arkanora-accent)}.arkanora__button{-webkit-appearance:none;-moz-appearance:none;appearance:none;font:inherit;font-weight:600;cursor:pointer;padding:.55rem 1.4rem;color:#06122a;background:var(--arkanora-accent);border:none;border-radius:999px;transition:filter .12s ease}.arkanora__button:hover{filter:brightness(1.1)}.arkanora__button:active{filter:brightness(.95)}

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@norarcasey/arkanora",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "An embeddable React breakout game — bounce the ball with your paddle and smash every brick.",
+  "license": "MIT",
+  "author": "Nora Casey",
+  "homepage": "https://github.com/norarcasey/arkanora#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/norarcasey/arkanora.git"
+  },
+  "bugs": {
+    "url": "https://github.com/norarcasey/arkanora/issues"
+  },
+  "keywords": [
+    "breakout",
+    "arkanoid",
+    "game",
+    "retro",
+    "arcade",
+    "react",
+    "component",
+    "typescript"
+  ],
+  "main": "./dist/arkanora.js",
+  "module": "./dist/arkanora.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/arkanora.js"
+    },
+    "./style.css": "./dist/style.css"
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "build:lib": "tsc -p tsconfig.lib.json && vite build --mode lib",
+    "preview": "vite preview",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "prepublishOnly": "npm run lint && npm run typecheck && npm run test && npm run build:lib"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "@testing-library/jest-dom": "^6.4.8",
+    "@testing-library/react": "^16.0.1",
+    "@testing-library/user-event": "^14.5.2",
+    "@types/node": "^20.19.41",
+    "@types/react": "^18.3.5",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.3.1",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^9.1.2",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "eslint-plugin-react-refresh": "^0.4.26",
+    "globals": "^15.15.0",
+    "jsdom": "^25.0.0",
+    "prettier": "^3.8.3",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "^5.5.4",
+    "typescript-eslint": "^8.60.1",
+    "vite": "^5.4.2",
+    "vite-plugin-dts": "^4.0.3",
+    "vitest": "^2.0.5"
+  }
+}