@spotlab/hand-matrix 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 James DiGioia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,110 @@
-# Temporary Holding Version
+# @spotlab/hand-matrix
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A 13x13 poker hand-matrix React component. Peer-deps `react`, `react-dom`,
+and [`@spotlab/range`](../range) — no Tailwind, no bundler-plugin
+requirement.
+
+```tsx
+import { RangeGrid } from "@spotlab/hand-matrix";
+import "@spotlab/hand-matrix/style.css";
+import { initRange } from "@spotlab/range";
+
+await initRange(); // once, at startup
+
+<RangeGrid range="AKs:0.5,QQ" />;
+```
+
+## Exports
+
+- `HandMatrix` — the bare 13x13 grid primitive. Takes no range data; styling
+  is entirely the caller's job via `comboStyle`, keyed by combo string (e.g.
+  `"AKs"`).
+- `RangeGrid` — a read-only display component. Accepts the expanded
+  `HandFrequency[]` form or a range string directly (parsed via
+  `@spotlab/range`), and fills each cell to its combo's mean weight.
+- `cellFillGradient` / `CELL_FILL_DIRECTION` — the canonical left-to-right
+  gradient helper used to render a cell's fill.
+
+`RangeGrid`'s combo collapse (`toComboWeights`) is a wasm call, so
+`initRange()` must have resolved before rendering it — see
+[`@spotlab/range`](../range)'s own README for why that call is explicit
+rather than automatic.
+
+## Theming
+
+The package ships `hand-matrix.css` (`@spotlab/hand-matrix/style.css`),
+scoped entirely under a `.spotlab-hm-root` wrapper that every top-level
+component renders for itself, merged with any `className` passed in. Every
+custom property has a default declared on `.spotlab-hm-root`, so the
+component renders correctly with zero theming.
+
+Because the `className` you pass to a component lands on that same root, a
+class that sets variables works there too (`<RangeGrid className="my-theme" />`
+with `.my-theme { --spotlab-hm-border: … }`), in addition to the
+`.spotlab-hm-root` selector form below.
+
+**To override a variable, target `.spotlab-hm-root` itself** — not `:root`
+and not any other ancestor. Because the package's own default is declared
+directly on `.spotlab-hm-root`, a value set only on an ancestor loses to it
+regardless of specificity (an element's own declared value always beats an
+inherited one). This is the single most likely integration mistake:
+
+```css
+/* This does NOT win: */
+:root {
+  --spotlab-hm-fill: #f59e0b;
+}
+
+/* This does: */
+.spotlab-hm-root {
+  --spotlab-hm-fill: #f59e0b;
+}
+```
+
+**The package's defaults live in a named CSS cascade layer** (`@layer
+spotlab-hand-matrix`), not unlayered — this is what makes the above override
+reliable. Per the CSS cascade, unlayered styles always beat every `@layer`
+regardless of specificity or source order, so if the package's defaults were
+unlayered, a plain override would only win when it happened to load _after_
+the package's stylesheet; load it first, or wrap it in your own `@layer`,
+and the override would silently lose instead. Putting the defaults in a
+named layer makes any unlayered override — the common case for a plain CSS
+file or style tag, which is exactly what most consumers write — win
+automatically, regardless of import order.
+
+The one case this doesn't cover for free: if **your own styles are also
+inside a named layer** (for example, a Tailwind v4 app that wraps its design
+tokens in `@layer base`), layer priority is decided by each layer name's
+_first appearance_ in the stylesheet, not by where the override rule itself
+sits. A layer named for the first time later in the cascade outranks one
+named earlier, so you must import `@spotlab/hand-matrix/style.css` **before**
+whatever first establishes your own layer order (e.g. before `@import
+"tailwindcss"`, which emits `@layer theme, base, components, utilities;` as
+its first statement) — otherwise `spotlab-hand-matrix` gets appended last and
+outranks your override instead:
+
+```css
+/* Correct: registers `spotlab-hand-matrix` before Tailwind's layers, so
+   `@layer base` (where your override lives) outranks it. */
+@import "@spotlab/hand-matrix/style.css";
+@import "tailwindcss";
+```
+
+If you don't use cascade layers yourself (e.g. a plain CSS file, or an
+Obsidian plugin with no bundler-level layer system), none of this applies —
+your override is unlayered and wins unconditionally, in any import order.
+
+Available variables: `--spotlab-hm-border`, `--spotlab-hm-border-width`,
+`--spotlab-hm-cell-bg`, `--spotlab-hm-cell-fg`, `--spotlab-hm-fill`,
+`--spotlab-hm-font-family`, `--spotlab-hm-font-size`,
+`--spotlab-hm-font-weight`, `--spotlab-hm-radius`, `--spotlab-hm-surface-bg`,
+`--spotlab-hm-muted-bg`, `--spotlab-hm-muted-fg`, `--spotlab-hm-track-bg`,
+`--spotlab-hm-row-passive-bg`, `--spotlab-hm-dead-hatch`.
+
+Action/fill colors (`RangeGrid`'s `fill` prop) are **not** theme variables —
+they are data, passed as props. `--spotlab-hm-fill` is only the default used
+when `fill` is omitted.
+
+## License
+
+MIT — see `LICENSE`.

package/dist/editor/action-sliders.d.ts

@@ -0,0 +1,35 @@
+import { ChangeEvent, ComponentType, FC, ReactNode } from 'react';
+import { EditorActionSpec } from './weights';
+export type WeightInputProps = {
+    value: number;
+    "aria-label": string;
+    onChange: (event: ChangeEvent<HTMLInputElement>) => void;
+};
+export type ActionWeightSlidersProps = {
+    actions: EditorActionSpec[];
+    /** Indices into `actions`/`weights`, in the order rows should render. */
+    order: number[];
+    /** Index-aligned with `actions`. */
+    weights: number[];
+    passive: number;
+    onWeightsChange: (weights: number[]) => void;
+    /**
+     * Leading content for a row's header, replacing the default label — the
+     * slot for a control that takes the label's own position (e.g. a
+     * raise-size input) rather than trailing it. Defaults to the action's
+     * label (plus a "· remainder" suffix on the passive row).
+     */
+    renderActionLabel?: (action: EditorActionSpec, index: number, isPassive: boolean) => ReactNode;
+    /** Extra content rendered after an action's label — the slot for consumer-specific controls (a remove button). */
+    renderActionExtra?: (action: EditorActionSpec, index: number) => ReactNode;
+    components?: {
+        WeightInput?: ComponentType<WeightInputProps>;
+    };
+    className?: string;
+};
+/**
+ * One pointer-driven weight slider per action, each paired with a numeric
+ * input for keyboard entry. Adjusting one action rebalances the others
+ * proportionally so the row's weights keep summing to 100.
+ */
+export declare const ActionWeightSliders: FC<ActionWeightSlidersProps>;

package/dist/editor/cells.d.ts

@@ -0,0 +1,26 @@
+export declare const COMBO_INDEX: Map<string, number>;
+/**
+ * One matrix cell's painted state: `avail` is the combo's cap (its weight in the
+ * parent range the editor is splitting), `weights` are each action's conditional
+ * share of that cap, summing to 100 across the node's actions.
+ */
+export type EditorCell = {
+    avail: number;
+    weights: number[];
+};
+/**
+ * Seed the 169-cell grid from a parent range's per-combo availability and each
+ * action's own per-combo range, both expressed as absolute weights (a share of
+ * the whole deck, as `toComboWeights` from `@spotlab/range` produces). `avail`
+ * of `null` means the combo is unconstrained (available at 1). `passive` must be
+ * a valid index into `actionWeights` naming the remainder action.
+ */
+export declare function seedCells(avail: Map<string, number> | null, actionWeights: (Map<string, number> | null)[], passive: number): EditorCell[];
+/** Collapse one action's conditional weights back to absolute per-combo weights. */
+export declare function cellsToComboWeights(cells: EditorCell[], actionIndex: number): Map<string, number>;
+/**
+ * Re-derive conditional cell weights from absolute per-action ranges — the
+ * inverse of `cellsToComboWeights`. `passive` must be a valid index into
+ * `actionWeights` naming the remainder action.
+ */
+export declare function comboWeightsToCells(cells: EditorCell[], actionWeights: (Map<string, number> | null)[], passive: number): EditorCell[];

package/dist/editor/matrix-editor.d.ts

@@ -0,0 +1,24 @@
+import { FC } from 'react';
+import { PaintTool } from './use-range-painting';
+import { EditorCell } from './cells';
+import { EditorActionSpec } from './weights';
+export type RangeMatrixEditorProps = {
+    /** The 169-cell grid, in `@spotlab/range`'s `COMBOS` order. */
+    cells: EditorCell[];
+    /** Index-aligned with each cell's `weights` array. */
+    actions: EditorActionSpec[];
+    /** Indices into `actions`/`weights`, in the order bands should stack — a display concern the consumer owns (e.g. biggest raise first). */
+    order: number[];
+    brush: number[];
+    tool: PaintTool;
+    onCellsChange: (cells: EditorCell[]) => void;
+    onBrushChange: (brush: number[]) => void;
+    onToolChange: (tool: PaintTool) => void;
+    className?: string;
+};
+/**
+ * The paintable 13x13 range grid: per-cell action bands, the dead-cell hatch,
+ * the capped-cell cap marker, and the brush/eyedropper painting wired onto
+ * `HandMatrix`. Fully controlled; `useRangePainting` drives the state changes.
+ */
+export declare const RangeMatrixEditor: FC<RangeMatrixEditorProps>;

package/dist/editor/use-range-painting.d.ts

@@ -0,0 +1,19 @@
+import { EditorCell } from './cells';
+export type PaintTool = "brush" | "eyedropper";
+/**
+ * The brush/eyedropper state machine behind `RangeMatrixEditor`: drag-painting
+ * (tracked across `pointerdown`/mouse-enter without a React re-render per
+ * cell) and eyedropping a cell's weights back onto the brush. Fully
+ * controlled — all state changes go out through the `on*Change` callbacks.
+ */
+export declare function useRangePainting(opts: {
+    cells: EditorCell[];
+    brush: number[];
+    tool: PaintTool;
+    onCellsChange: (cells: EditorCell[]) => void;
+    onBrushChange: (brush: number[]) => void;
+    onToolChange: (tool: PaintTool) => void;
+}): {
+    onCellDown: (combo: string) => void;
+    onCellEnter: (combo: string) => void;
+};

package/dist/editor/weights.d.ts

@@ -0,0 +1,13 @@
+export declare const fixRound: (weights: number[], keep: number) => number[];
+/**
+ * `passive` names the remainder action — the one whose weight absorbs whatever
+ * the others leave behind. It must be a valid index into `weights`; the caller
+ * decides which action that is and guarantees one exists.
+ */
+export declare const rebalance: (weights: number[], index: number, value: number, passive: number) => number[];
+export declare const sumActive: (weights: number[], passive: number) => number;
+export type EditorActionSpec = {
+    id: string;
+    label: string;
+    color: string;
+};

package/dist/hand-matrix.css

@@ -0,0 +1,147 @@
+/*
+ * Defaults live in a named layer, not unlayered: unlayered CSS always beats
+ * every `@layer`, even one a consumer wrote specifically to override these
+ * variables. A named layer lets a consumer's plain (unlayered) override CSS
+ * win regardless of import order, and lets a consumer who uses cascade
+ * layers themselves (e.g. Tailwind) place their own override layer after
+ * this one. See the "Theming" section of README.md for how to register this
+ * layer's priority relative to a bundler-level layer system.
+ */
+@layer spotlab-hand-matrix {
+  .spotlab-hm-root {
+    --spotlab-hm-border: #d4d4d8;
+    --spotlab-hm-border-width: 1px;
+    --spotlab-hm-cell-bg: transparent;
+    --spotlab-hm-cell-fg: #18181b;
+    --spotlab-hm-muted-bg: #f4f4f5;
+    --spotlab-hm-muted-fg: #71717a;
+    --spotlab-hm-fill: #10b981;
+    --spotlab-hm-font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+    --spotlab-hm-font-size: 0.75rem;
+    --spotlab-hm-font-weight: 600;
+    --spotlab-hm-dead-hatch: repeating-linear-gradient(
+      45deg,
+      rgba(15, 23, 42, 0.22) 0 3px,
+      rgba(255, 255, 255, 0.18) 3px 6px
+    );
+    --spotlab-hm-radius: 0.5rem;
+    --spotlab-hm-surface-bg: #ffffff;
+    --spotlab-hm-track-bg: #e4e4e7;
+    --spotlab-hm-row-passive-bg: rgba(244, 244, 245, 0.4);
+  }
+}
+
+.spotlab-hm-row {
+  display: flex;
+  flex-flow: row nowrap;
+}
+
+.spotlab-hm-cell {
+  aspect-ratio: 1 / 1;
+  width: calc(100% / 13);
+  overflow: hidden;
+  background-color: var(--spotlab-hm-cell-bg);
+  border: var(--spotlab-hm-border-width) solid var(--spotlab-hm-border);
+  font-family: var(--spotlab-hm-font-family);
+  font-size: var(--spotlab-hm-font-size);
+  font-weight: var(--spotlab-hm-font-weight);
+  color: var(--spotlab-hm-cell-fg);
+}
+
+.spotlab-hm-cell-inner {
+  display: flex;
+  height: 100%;
+  width: 100%;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+}
+
+.spotlab-hm-sliders {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.spotlab-hm-slider-row {
+  display: flex;
+  flex-direction: column;
+  border-radius: var(--spotlab-hm-radius);
+  border: var(--spotlab-hm-border-width) solid var(--spotlab-hm-border);
+  padding: 10px 12px;
+  background: var(--spotlab-hm-surface-bg);
+}
+
+.spotlab-hm-slider-row[data-passive="true"] {
+  background: var(--spotlab-hm-row-passive-bg);
+}
+
+.spotlab-hm-slider-header {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin-bottom: 8px;
+}
+
+.spotlab-hm-slider-swatch {
+  flex: none;
+  height: 14px;
+  width: 14px;
+  border-radius: 3px;
+  border: var(--spotlab-hm-border-width) solid var(--spotlab-hm-border);
+}
+
+.spotlab-hm-slider-label {
+  flex: 1;
+  font-size: 13px;
+  font-weight: 600;
+  font-family: var(--spotlab-hm-font-family);
+  color: var(--spotlab-hm-cell-fg);
+}
+
+.spotlab-hm-slider-remainder {
+  font-size: 12px;
+  font-weight: 400;
+  color: var(--spotlab-hm-muted-fg);
+}
+
+.spotlab-hm-slider-track-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+.spotlab-hm-slider-track {
+  position: relative;
+  flex: 1;
+  height: 8px;
+  cursor: pointer;
+  border-radius: 5px;
+  border: var(--spotlab-hm-border-width) solid var(--spotlab-hm-border);
+  touch-action: none;
+}
+
+.spotlab-hm-slider-thumb {
+  position: absolute;
+  top: 50%;
+  height: 16px;
+  width: 16px;
+  transform: translate(-50%, -50%);
+  border-radius: 50%;
+  background: var(--spotlab-hm-surface-bg);
+  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.25);
+}
+
+.spotlab-hm-weight-input {
+  height: 32px;
+  width: 58px;
+  flex: none;
+  padding: 0 6px;
+  text-align: center;
+  font-size: 13px;
+  font-family: var(--spotlab-hm-font-family);
+  color: var(--spotlab-hm-cell-fg);
+  background: transparent;
+  border-radius: calc(var(--spotlab-hm-radius) * 0.5);
+  border: var(--spotlab-hm-border-width) solid var(--spotlab-hm-border);
+}

package/dist/hand-matrix.d.ts

@@ -0,0 +1,13 @@
+import { CSSProperties, FC } from 'react';
+export declare const CELL_FILL_DIRECTION = "to right";
+export declare const cellFillGradient: (stops: string[]) => string;
+type ComboHandlers = {
+    onClick?: (combo: string) => void;
+    onMouseDown?: (combo: string) => void;
+    onMouseEnter?: (combo: string) => void;
+    comboStyle?: (combo: string) => CSSProperties;
+};
+export declare const HandMatrix: FC<{
+    className?: string;
+} & ComboHandlers>;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { HandMatrix, cellFillGradient, CELL_FILL_DIRECTION, } from './hand-matrix';
+export { RangeGrid } from './range-grid';
+export { RangeMatrixEditor } from './editor/matrix-editor';
+export type { RangeMatrixEditorProps } from './editor/matrix-editor';
+export { ActionWeightSliders } from './editor/action-sliders';
+export type { ActionWeightSlidersProps, WeightInputProps, } from './editor/action-sliders';
+export { useRangePainting } from './editor/use-range-painting';
+export type { PaintTool } from './editor/use-range-painting';
+export { seedCells, cellsToComboWeights, comboWeightsToCells, } from './editor/cells';
+export type { EditorCell } from './editor/cells';
+export { rebalance } from './editor/weights';
+export type { EditorActionSpec } from './editor/weights';

package/dist/index.js

@@ -0,0 +1,307 @@
+import { COMBOS as g, parseRange as R, toComboWeights as x } from "@spotlab/range";
+import { jsx as p, jsxs as b } from "react/jsx-runtime";
+import { useCallback as v, useEffect as k, useMemo as L, useRef as w } from "react";
+var I = (e, t) => Array.from({ length: Math.ceil(e.length / t) }, (n, r) => e.slice(r * t, r * t + t)), D = "to right", $ = (e) => e.length === 0 ? "transparent" : `linear-gradient(${D}, ${e.join(", ")})`, B = ({ combo: e, onClick: t, onMouseDown: n, onMouseEnter: r, comboStyle: a }) => /* @__PURE__ */ p("div", {
+  className: "spotlab-hm-cell",
+  style: a?.(e),
+  onClick: () => t?.(e),
+  onMouseDown: () => n?.(e),
+  onMouseEnter: () => r?.(e),
+  children: /* @__PURE__ */ p("div", {
+    className: "spotlab-hm-cell-inner",
+    children: /* @__PURE__ */ p("div", {
+      "data-combo": e,
+      children: e
+    })
+  })
+}), O = ({ row: e, ...t }) => /* @__PURE__ */ p("div", {
+  className: "spotlab-hm-row",
+  children: e.map((n, r) => /* @__PURE__ */ p(B, {
+    combo: n,
+    ...t
+  }, r))
+}), N = ({ className: e, ...t }) => /* @__PURE__ */ p("div", {
+  className: ["spotlab-hm-root", e].filter(Boolean).join(" "),
+  children: I(g, 13).map((n, r) => /* @__PURE__ */ p(O, {
+    row: n,
+    ...t
+  }, r))
+}), S = (e, t) => ({ background: $([`${e} 0 ${t * 100}%`, `transparent ${t * 100}% 100%`]) }), H = ({ range: e, fill: t = "var(--spotlab-hm-fill)", className: n }) => {
+  const r = L(() => {
+    const a = typeof e == "string" ? R(e) : e;
+    return x(a);
+  }, [e]);
+  return /* @__PURE__ */ p(N, {
+    className: n,
+    comboStyle: (a) => {
+      const o = r.get(a);
+      return o ? S(t, o) : {};
+    }
+  });
+}, W = (e) => Math.max(0, Math.min(100, Math.round(e))), F = (e, t) => {
+  const n = e.map(Math.round);
+  let r = 100 - n.reduce((a, o) => a + o, 0);
+  if (r !== 0) {
+    for (let a = 0; a < n.length; a++) if (a !== t && n[a] + r >= 0) {
+      n[a] += r, r = 0;
+      break;
+    }
+    if (r !== 0) {
+      for (let a = 0; a < n.length; a++) if (a !== t && n[a] > 0) {
+        const o = Math.min(n[a], -r);
+        if (n[a] -= o, r += o, r === 0) break;
+      }
+      n[t] = Math.max(0, n[t] + r);
+    }
+  }
+  return n;
+}, j = (e, t, n, r) => {
+  const a = W(n), o = e.slice();
+  o[t] = a;
+  const i = 100 - a, l = [];
+  for (let s = 0; s < e.length; s++) s !== t && l.push(s);
+  const c = l.reduce((s, u) => s + e[u], 0);
+  if (c <= 0) {
+    l.forEach((u) => o[u] = 0);
+    const s = t === r ? l[0] : r;
+    s != null && (o[s] = i);
+  } else l.forEach((s) => o[s] = Math.round(e[s] / c * i));
+  return F(o, t);
+}, M = (e, t) => e.reduce((n, r, a) => a === t ? n : n + r, 0), C = new Map(g.map((e, t) => [e, t])), y = (e, t) => {
+  const n = e.slice();
+  let r = M(n, t);
+  if (r > 100) {
+    const a = 100 / r;
+    for (let o = 0; o < n.length; o++) o !== t && (n[o] = Math.round(n[o] * a));
+    r = M(n, t);
+  }
+  return n[t] = Math.max(0, 100 - r), n;
+};
+function Q(e, t, n) {
+  return g.map((r) => {
+    const a = e ? e.get(r) ?? 0 : 1, o = t.map(() => 0);
+    return a <= 0 ? (o[n] = 100, {
+      avail: 0,
+      weights: o
+    }) : (t.forEach((i, l) => {
+      const c = i?.get(r) ?? 0;
+      o[l] = Math.round(c / a * 100);
+    }), {
+      avail: a,
+      weights: y(o, n)
+    });
+  });
+}
+var T = 8;
+function Y(e, t) {
+  const n = /* @__PURE__ */ new Map();
+  return e.forEach((r, a) => {
+    if (r.avail <= 0) return;
+    const o = r.weights.reduce((l, c) => l + c, 0);
+    if (!o) return;
+    const i = Number((r.weights[t] / o * r.avail).toFixed(T));
+    i && n.set(g[a], i);
+  }), n;
+}
+function J(e, t, n) {
+  return e.map((r, a) => {
+    const o = t.map(() => 0);
+    if (r.avail <= 0)
+      return o[n] = 100, {
+        avail: r.avail,
+        weights: o
+      };
+    const i = g[a];
+    return t.forEach((l, c) => {
+      const s = l?.get(i) ?? 0;
+      o[c] = Math.round(s / r.avail * 100);
+    }), {
+      avail: r.avail,
+      weights: y(o, n)
+    };
+  });
+}
+function _(e) {
+  const { cells: t, brush: n, tool: r, onCellsChange: a, onBrushChange: o, onToolChange: i } = e, l = w(!1);
+  k(() => {
+    const u = () => l.current = !1;
+    return window.addEventListener("pointerup", u), () => window.removeEventListener("pointerup", u);
+  }, []);
+  const c = v((u) => {
+    const d = C.get(u);
+    if (t[d].avail <= 0) return;
+    const h = t.slice();
+    h[d] = {
+      avail: t[d].avail,
+      weights: [...n]
+    }, a(h);
+  }, [
+    t,
+    n,
+    a
+  ]), s = v((u) => {
+    const d = C.get(u);
+    t[d].avail <= 0 || (o([...t[d].weights]), i("brush"));
+  }, [
+    t,
+    o,
+    i
+  ]);
+  return {
+    onCellDown: v((u) => {
+      if (r === "eyedropper") {
+        s(u);
+        return;
+      }
+      l.current = !0, c(u);
+    }, [
+      r,
+      s,
+      c
+    ]),
+    onCellEnter: v((u) => {
+      l.current && r === "brush" && c(u);
+    }, [r, c])
+  };
+}
+var E = (e, t, n) => {
+  const r = [];
+  let a = 0;
+  return n.forEach((o) => {
+    const i = (e.weights[o] || 0) / 100 * e.avail;
+    if (i <= 0) return;
+    const l = t[o].color;
+    r.push(`${l} ${a * 100}%`), r.push(`${l} ${(a + i) * 100}%`), a += i;
+  }), $(r);
+}, K = ({ cells: e, actions: t, order: n, brush: r, tool: a, onCellsChange: o, onBrushChange: i, onToolChange: l, className: c }) => {
+  const { onCellDown: s, onCellEnter: u } = _({
+    cells: e,
+    brush: r,
+    tool: a,
+    onCellsChange: o,
+    onBrushChange: i,
+    onToolChange: l
+  });
+  return /* @__PURE__ */ p(N, {
+    className: c,
+    comboStyle: (d) => {
+      const h = e[C.get(d)];
+      if (h.avail <= 0) return {
+        background: "var(--spotlab-hm-dead-hatch)",
+        backgroundColor: "var(--spotlab-hm-muted-bg)",
+        cursor: "not-allowed",
+        color: "var(--spotlab-hm-muted-fg)"
+      };
+      const m = a === "eyedropper" ? "copy" : "pointer";
+      if (h.avail < 1) {
+        const f = `${h.avail * 100}%`;
+        return {
+          background: `repeating-linear-gradient(180deg, var(--spotlab-hm-muted-fg) 0 4px, transparent 4px 8px), var(--spotlab-hm-dead-hatch), ${E(h, t, n)}`,
+          backgroundSize: `1px 100%, ${(1 - h.avail) * 100}% 100%, ${h.avail * 100}% 100%`,
+          backgroundPosition: `${f} center, right center, left center`,
+          backgroundRepeat: "no-repeat, no-repeat, no-repeat",
+          cursor: m
+        };
+      }
+      return {
+        background: E(h, t, n),
+        cursor: m
+      };
+    },
+    onMouseDown: s,
+    onMouseEnter: u
+  });
+}, A = (e) => /* @__PURE__ */ p("input", {
+  type: "number",
+  className: "spotlab-hm-weight-input",
+  ...e
+}), P = ({ value: e, color: t, passive: n, onChange: r }) => {
+  const a = w(null), o = w(!1), i = v((l) => {
+    const c = a.current;
+    if (!c) return;
+    const s = c.getBoundingClientRect();
+    r((l - s.left) / s.width * 100);
+  }, [r]);
+  return k(() => {
+    const l = (s) => {
+      o.current && i(s.clientX);
+    }, c = () => o.current = !1;
+    return window.addEventListener("pointermove", l), window.addEventListener("pointerup", c), () => {
+      window.removeEventListener("pointermove", l), window.removeEventListener("pointerup", c);
+    };
+  }, [i]), /* @__PURE__ */ p("div", {
+    ref: a,
+    role: "slider",
+    "aria-valuenow": e,
+    "aria-valuemin": 0,
+    "aria-valuemax": 100,
+    className: "spotlab-hm-slider-track",
+    style: { background: `linear-gradient(to right, ${t} 0 ${e}%, var(--spotlab-hm-track-bg) ${e}% 100%)` },
+    onPointerDown: (l) => {
+      o.current = !0, i(l.clientX);
+    },
+    children: /* @__PURE__ */ p("div", {
+      className: "spotlab-hm-slider-thumb",
+      style: {
+        left: `${e}%`,
+        border: `2px solid ${n ? "var(--spotlab-hm-muted-fg)" : t}`
+      }
+    })
+  });
+}, X = (e, t) => /* @__PURE__ */ b("span", {
+  className: "spotlab-hm-slider-label",
+  children: [e.label, t && /* @__PURE__ */ p("span", {
+    className: "spotlab-hm-slider-remainder",
+    children: " · remainder"
+  })]
+}), V = ({ actions: e, order: t, weights: n, passive: r, onWeightsChange: a, renderActionLabel: o, renderActionExtra: i, components: l, className: c }) => {
+  const s = l?.WeightInput ?? A, u = (d, h) => {
+    a(j(n, d, h, r));
+  };
+  return /* @__PURE__ */ p("div", {
+    className: ["spotlab-hm-root spotlab-hm-sliders", c].filter(Boolean).join(" "),
+    children: t.map((d) => {
+      const h = e[d], m = d === r;
+      return /* @__PURE__ */ b("div", {
+        className: "spotlab-hm-slider-row",
+        "data-passive": m,
+        children: [/* @__PURE__ */ b("div", {
+          className: "spotlab-hm-slider-header",
+          children: [
+            /* @__PURE__ */ p("span", {
+              className: "spotlab-hm-slider-swatch",
+              style: { background: h.color }
+            }),
+            o?.(h, d, m) ?? X(h, m),
+            i?.(h, d)
+          ]
+        }), /* @__PURE__ */ b("div", {
+          className: "spotlab-hm-slider-track-row",
+          children: [/* @__PURE__ */ p(P, {
+            value: n[d],
+            color: h.color,
+            passive: m,
+            onChange: (f) => u(d, f)
+          }), /* @__PURE__ */ p(s, {
+            value: n[d],
+            "aria-label": `${h.label} weight`,
+            onChange: (f) => u(d, parseInt(f.target.value || "0", 10))
+          })]
+        })]
+      }, h.id);
+    })
+  });
+};
+export {
+  V as ActionWeightSliders,
+  D as CELL_FILL_DIRECTION,
+  N as HandMatrix,
+  H as RangeGrid,
+  K as RangeMatrixEditor,
+  $ as cellFillGradient,
+  Y as cellsToComboWeights,
+  J as comboWeightsToCells,
+  j as rebalance,
+  Q as seedCells,
+  _ as useRangePainting
+};

package/dist/range-grid.d.ts

@@ -0,0 +1,13 @@
+import { FC } from 'react';
+import { HandFrequency } from '@spotlab/range';
+/**
+ * A read-only 13x13 range grid: each cell fills to its combo's mean weight.
+ * Accepts the expanded hand-keyed form or a range string directly — a range
+ * string is parsed via `@spotlab/range`, so the caller never needs to touch
+ * the parser itself to render one.
+ */
+export declare const RangeGrid: FC<{
+    range: HandFrequency[] | string;
+    fill?: string;
+    className?: string;
+}>;

package/package.json

@@ -1,6 +1,78 @@
 {
   "name": "@spotlab/hand-matrix",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "A 13x13 poker hand-matrix React component: the read-only grid primitive and a range-string-aware display component, themed through CSS custom properties.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mAAdhaTTah/spotlab",
+    "directory": "packages/hand-matrix"
+  },
+  "homepage": "https://github.com/mAAdhaTTah/spotlab/tree/main/packages/hand-matrix#readme",
+  "bugs": {
+    "url": "https://github.com/mAAdhaTTah/spotlab/issues"
+  },
+  "author": "James DiGioia",
+  "keywords": [
+    "poker",
+    "range",
+    "hand-matrix",
+    "react",
+    "component",
+    "texas-holdem"
+  ],
+  "sideEffects": [
+    "*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./style.css": "./dist/hand-matrix.css"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@spotlab/range": "^0.1.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@spotlab/range": "0.1.0",
+    "@storybook/addon-vitest": "^10.5.5",
+    "@storybook/react-vite": "^10.5.5",
+    "@types/react": "^19.2.16",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.0",
+    "@vitest/browser": "^4.1.4",
+    "@vitest/browser-playwright": "4.1.11",
+    "playwright": "^1.49.1",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "storybook": "^10.5.5",
+    "typescript": "^6.0.0",
+    "vite": "^8.3.1",
+    "vite-plugin-dts": "^5.1.2",
+    "vitest": "^4.1.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json",
+    "build:vite": "vite build",
+    "build:css": "node scripts/copy-css.mjs",
+    "build": "pnpm typecheck && pnpm build:vite && pnpm build:css",
+    "test": "vitest run --project unit",
+    "storybook": "storybook dev -p 6007",
+    "build-storybook": "storybook build",
+    "test-storybook": "vitest run --project storybook"
+  }
 }