@profullstack/leaderboard 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Profullstack, LLC
+
+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

@@ -0,0 +1,150 @@
+# @profullstack/leaderboard
+
+A public leaderboard that drops into any site. Score events in, ranked boards out: all time, week, month, streaks, badges, a commission ladder, RSS, a share card per player and a widget any page can embed with one script tag.
+
+Zero dependencies. The core is a Fetch API handler, so it runs in Node, Bun, Deno and at the edge. Adapters for Hono and Next.js. Stores: in-memory, or any SQL client with `execute({ sql, args })` (libsql/Turso, sqlite, Postgres).
+
+Built for marketplaces where people sell through properties and niches and earn a growing cut, but every board, badge and metric is yours to define.
+
+## Install
+
+```sh
+npm i @profullstack/leaderboard
+```
+
+## Sixty seconds
+
+```js
+import { createLeaderboard, sqlStore, commissionLadder } from '@profullstack/leaderboard';
+import { leaderboard } from '@profullstack/leaderboard/hono';
+
+const store = sqlStore({ execute: (q) => db.execute(q) });   // @libsql/client shape
+await store.migrate();
+
+const lb = createLeaderboard({
+  siteName: 'NicheDB',
+  siteUrl: 'https://nichedb.dev',
+  store,
+  boards: {
+    earnings: { label: 'Top earners', metric: 'cents', format: 'usd', unit: 'Earned' },
+    sales:    { label: 'Most sales',  metric: 'sales', tiebreak: 'cents' },
+    streaks:  { label: 'Longest streaks', metric: 'streak', min: 1 },
+  },
+  ladder: commissionLadder(),   // 20% -> 80%
+});
+
+app.use('*', leaderboard(lb));
+
+// When something happens:
+await lb.record({ player: user.id, name: user.name, metrics: { cents: 1900, sales: 1 } });
+await lb.set({ player: user.id, metrics: { properties: 3, niches: 5 } });
+```
+
+That gives the site, under `/leaderboard`:
+
+| Path | What |
+| --- | --- |
+| `/leaderboard` | A full leaderboard page (`?board=&period=&me=&theme=`) |
+| `/leaderboard.json` | Boards, periods, badges and the ladder |
+| `/leaderboard/earnings.json?period=week&limit=10&me=u_42` | Ranked rows, plus `me` (my standing, on the board or not) |
+| `/leaderboard/earnings.xml?period=week` | RSS of the board |
+| `/leaderboard/u/u_42` | A share card with Open Graph tags: ranks, streaks, badges, commission |
+| `/leaderboard/u/u_42.json` | The same as data |
+| `/leaderboard/embed?board=sales&sticky=bottom-right` | An iframe-able page |
+| `/leaderboard/embed.js` | The widget script |
+
+JSON answers carry `Access-Control-Allow-Origin: *`, so the widget works on any domain.
+
+## The widget
+
+On any page, yours or a partner's:
+
+```html
+<div data-leaderboard></div>
+<script src="https://nichedb.dev/leaderboard/embed.js"
+        data-board="earnings" data-period="week" data-limit="10" data-me="u_42"></script>
+```
+
+Period tabs, badges next to names, the commission rate, streak flames, a highlighted row for `data-me` (and a "you" row below the cut when they are not in the top N), a share link per row that copies the player's card URL, RSS and full-board links, and a refresh every 60 seconds while the tab is visible.
+
+Sticky mode is the retention feature. Add `data-sticky="bottom-right"` (or `bottom-left`, `top-right`, `top-left`) and the board becomes a corner pill reading "You are #4 this week" that opens the panel on click. It follows the reader around the site.
+
+| Attribute | Default | Meaning |
+| --- | --- | --- |
+| `data-board` | first board | Board id |
+| `data-period` | site default | `all`, `day`, `week`, `month` |
+| `data-limit` | `10` | Rows |
+| `data-me` | | Player id to highlight and report |
+| `data-sticky` | | Corner pill mode |
+| `data-theme` | `auto` | `light`, `dark`, `auto` |
+| `data-title` | board label | Heading |
+| `data-refresh` | `60` | Seconds between refreshes, `0` to disable |
+| `data-target` | | CSS selector of the container |
+| `data-base` | from `src` | The leaderboard path when the script is served elsewhere |
+
+The widget fires `leaderboard:render` on its container with the JSON as `detail`, for anything you want to do with the numbers.
+
+## Metrics
+
+Three kinds, one vocabulary:
+
+- **Counters** go in through `record()` and are summed. Boards on a counter honour the period.
+- **Gauges** go in through `set()` and are the current value (properties owned, niches promoted, followers). Boards on a gauge show the same number in every period.
+- **Derived**: `streak` (consecutive UTC days with any `record()`, still current through yesterday) and `bestStreak`.
+
+A board is `{ label, metric, format, unit, min, order, tiebreak }`. `format` is `number`, `integer`, `usd` (cents in) or `percent`. Players below `min` do not appear. Ties break on `tiebreak`, then on who got there first.
+
+`record()` and `set()` return the badges newly earned, for a toast.
+
+## Badges
+
+A badge is `{ id, emoji, label, describe, when(profile) }`. It is awarded the first time `when` is true and kept forever, so "top ten this week" stays earned after the week ends. The profile carries `totals`, `gauges`, `streak`, `bestStreak`, `ranks[board][period]` and `commission.rate`.
+
+The default set is for a marketplace: first sale, ten sales, hundred sales, seven and thirty day streaks, three properties, five niches, top ten this week, number one, and the 80% club. Pass `badges: [...]` for your own; `onBadge({ player, name, badge })` fires on every award.
+
+## The commission ladder
+
+```js
+const ladder = commissionLadder();          // base 20, cap 80, +5 per property (max 6), +5 per niche (max 6)
+ladder.rate({ properties: 2, niches: 4 });  // 50
+ladder.next({ properties: 2, niches: 4 });  // { add: 'property', rate: 55, from: 50, gain: 5, toCap: 30 }
+ladder.table();                             // every step, for a pricing page
+```
+
+Every number is an option (`base`, `cap`, `perProperty`, `perNiche`, `maxProperties`, `maxNiches`, `propertiesMetric`, `nichesMetric`). Pass `ladder: true` for the defaults. The rate appears in every row and on the share card, with the next step spelled out: "Add one niche to reach 55%".
+
+## Stores
+
+```js
+import { memoryStore, sqlStore } from '@profullstack/leaderboard';
+
+memoryStore();                                        // one process, tests
+sqlStore({ execute, prefix: 'lb_', dialect: 'sqlite' })  // or 'postgres'
+```
+
+`sqlStore` needs `execute({ sql, args }) -> { rows }`, which is `@libsql/client` as is. `store.schema` is the DDL for your own migration tool; `store.migrate()` runs it. Three tables: events, gauges, badges.
+
+Anything else implements six methods: `append`, `list({ since })`, `setGauge`, `gauges`, `awardBadge`, `badges`. The core reads all events and aggregates in memory, cached for `cacheMs` (15 s); that is fine into the hundreds of thousands of events. Call `lb.invalidate()` after writing to the store from elsewhere.
+
+## Next.js
+
+```js
+// app/leaderboard/[[...path]]/route.js
+import { leaderboardRoute } from '@profullstack/leaderboard/next';
+export const { GET } = leaderboardRoute(lb);
+export const dynamic = 'force-dynamic';
+```
+
+## Programmatic
+
+```js
+await lb.top({ board: 'earnings', period: 'month', limit: 25, offset: 0 });
+await lb.standing({ player: 'u_42', board: 'earnings', period: 'week' });
+await lb.profile('u_42');
+await lb.rss({ board: 'sales' });
+lb.index();
+```
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,109 @@
+export type Period = 'all' | 'day' | 'week' | 'month';
+export type Format = 'number' | 'integer' | 'usd' | 'percent';
+
+export interface Event { player: string; name?: string; metric: string; delta: number; at: number }
+
+export interface Store {
+  append(event: Event): Promise<void>;
+  list(opts?: { since?: number }): Promise<Event[]>;
+  setGauge(player: string, metric: string, value: number, name: string | undefined, at: number): Promise<void>;
+  gauges(): Promise<Record<string, { name?: string; at: number; values: Record<string, number> }>>;
+  awardBadge(player: string, badge: string, at: number): Promise<boolean>;
+  badges(): Promise<Record<string, Record<string, number>>>;
+}
+
+export interface MemoryStore extends Store { _dump(): unknown }
+export function memoryStore(): MemoryStore;
+
+export interface SqlStoreOptions {
+  execute: (q: { sql: string; args: unknown[] }) => Promise<{ rows: Record<string, unknown>[] }> | { rows: Record<string, unknown>[] };
+  prefix?: string;
+  dialect?: 'sqlite' | 'postgres';
+}
+export interface SqlStore extends Store { schema: string[]; tables: { events: string; gauges: string; badges: string }; migrate(): Promise<void> }
+export function sqlStore(options: SqlStoreOptions): SqlStore;
+
+export interface LadderOptions {
+  base?: number; cap?: number; perProperty?: number; perNiche?: number; maxProperties?: number; maxNiches?: number;
+  propertiesMetric?: string; nichesMetric?: string;
+}
+export interface LadderState { properties?: number; niches?: number; [metric: string]: number | undefined }
+export interface LadderStep { add: 'property' | 'niche'; rate: number; from: number; gain: number; toCap: number }
+export interface Ladder extends Required<LadderOptions> {
+  rate(state?: LadderState): number;
+  next(state?: LadderState): LadderStep | null;
+  table(): Array<{ properties: number; niches: number; rate: number }>;
+  describe(): string;
+}
+export function commissionLadder(options?: LadderOptions): Ladder;
+
+export interface Badge { id: string; emoji?: string; label?: string; describe?: string; when(profile: Profile): boolean }
+export interface EarnedBadge { id: string; emoji: string; label: string; describe: string; at: number }
+export function defaultBadges(names?: { sales?: string; properties?: string; niches?: string }): Badge[];
+
+export interface BoardOptions { label?: string; metric?: string; format?: Format; unit?: string; min?: number; order?: 'asc' | 'desc'; tiebreak?: string }
+export interface Board { id: string; label: string; metric: string; format: Format; unit: string }
+
+export interface Profile {
+  id: string; name: string;
+  totals: Record<string, number>;
+  gauges: Record<string, number>;
+  streak: number; bestStreak: number;
+  firstAt: number; lastAt: number;
+  ranks: Record<string, Partial<Record<Period, number>>>;
+  values: Record<string, Partial<Record<Period, number>>>;
+  badges: EarnedBadge[];
+  commission?: { rate: number; next: LadderStep | null };
+  url: string; shareUrl: string;
+}
+
+export interface Row {
+  rank: number | null; id: string; name: string; value: number; display: string;
+  streak: number; bestStreak: number; badges: Array<{ id: string; emoji: string; label: string }>;
+  commission?: number; url: string;
+}
+export interface Standing extends Row { qualified: boolean; min: number }
+export interface Top { board: Board; period: Period; periods: Period[]; generatedAt: string; total: number; rows: Row[]; me?: Standing | null }
+
+export interface LeaderboardOptions {
+  store?: Store;
+  basePath?: string;
+  siteName?: string;
+  siteUrl?: string;
+  boards?: Record<string, BoardOptions> | Array<BoardOptions & { id: string }>;
+  periods?: Period[];
+  defaultPeriod?: Period;
+  ladder?: Ladder | boolean;
+  badges?: Badge[];
+  cacheMs?: number;
+  limitMax?: number;
+  profileUrl?: (id: string) => string;
+  now?: () => number;
+  onBadge?: (x: { player: string; name: string; badge: EarnedBadge }) => void | Promise<void>;
+}
+
+export interface Leaderboard {
+  record(x: { player: string; name?: string; metrics: Record<string, number>; at?: number }): Promise<EarnedBadge[]>;
+  set(x: { player: string; name?: string; metrics: Record<string, number>; at?: number }): Promise<EarnedBadge[]>;
+  award(player: string): Promise<EarnedBadge[]>;
+  top(opts?: { board?: string; period?: Period; limit?: number; offset?: number }): Promise<Top>;
+  standing(opts: { player: string; board?: string; period?: Period }): Promise<Standing | null>;
+  profile(player: string): Promise<Profile | null>;
+  handle(request: Request): Promise<Response | null>;
+  rss(opts?: { board?: string; period?: Period; limit?: number }): Promise<string>;
+  index(): unknown;
+  widget(): string;
+  invalidate(): void;
+  boards: Board[]; periods: Period[]; basePath: string; ladder: Ladder | null; badges: Badge[];
+}
+export function createLeaderboard(options?: LeaderboardOptions): Leaderboard;
+
+export function streaks(days: Iterable<number>, now?: number): { current: number; best: number };
+export function format(value: number, kind?: Format, locale?: string): string;
+export function periodLabel(period: Period): string;
+
+/** Hono middleware. */
+export function leaderboard(lbOrOptions: Leaderboard | LeaderboardOptions): (c: any, next: () => Promise<void>) => Promise<Response | void>;
+/** Next.js Route Handler for `app/<basePath>/[[...path]]/route.js`. */
+export function leaderboardRoute(lbOrOptions: Leaderboard | LeaderboardOptions): { GET: (request: Request) => Promise<Response>; HEAD: (request: Request) => Promise<Response> };
+export function widgetSource(): string;

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@profullstack/leaderboard",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "A public leaderboard with badges, streaks and a commission ladder that drops into any site: score events in, ranked boards + RSS + a share card + an embeddable widget out. Zero dependencies, Fetch API core, Hono and Next adapters.",
+  "keywords": [
+    "leaderboard",
+    "gamification",
+    "badges",
+    "streaks",
+    "ranking",
+    "affiliate",
+    "commission",
+    "embed",
+    "widget",
+    "rss",
+    "hono",
+    "nextjs",
+    "libsql",
+    "turso"
+  ],
+  "repository": { "type": "git", "url": "git+https://github.com/profullstack/leaderboard.git" },
+  "homepage": "https://github.com/profullstack/leaderboard#readme",
+  "bugs": { "url": "https://github.com/profullstack/leaderboard/issues" },
+  "license": "MIT",
+  "author": "Profullstack, LLC",
+  "exports": {
+    ".": { "types": "./index.d.ts", "import": "./src/index.js" },
+    "./hono": { "types": "./index.d.ts", "import": "./src/hono.js" },
+    "./next": { "types": "./index.d.ts", "import": "./src/next.js" },
+    "./ladder": { "types": "./index.d.ts", "import": "./src/ladder.js" },
+    "./badges": { "types": "./index.d.ts", "import": "./src/badges.js" },
+    "./store/memory": { "types": "./index.d.ts", "import": "./src/store/memory.js" },
+    "./store/sql": { "types": "./index.d.ts", "import": "./src/store/sql.js" }
+  },
+  "types": "./index.d.ts",
+  "files": ["src", "index.d.ts", "README.md", "LICENSE"],
+  "engines": { "node": ">=20.11" },
+  "sideEffects": false,
+  "scripts": {
+    "test": "node --test"
+  }
+}

package/src/badges.js

@@ -0,0 +1,41 @@
+/**
+ * Badges are predicates over a player's profile. A badge is awarded once and
+ * kept forever, so `when` only has to be true at one moment: the week you were
+ * in the top ten counts even after you fall out.
+ *
+ * The profile handed to `when` carries: `totals` (summed counters, all time),
+ * `gauges` (absolute values you `set`), `streak`, `bestStreak`, `ranks`
+ * (`{ [boardId]: { [period]: rank } }`) and, when a ladder is configured,
+ * `commission.rate`.
+ *
+ * This is the default set for a marketplace with sellers, properties and
+ * niches. Pass your own array to `createLeaderboard({ badges })` for anything
+ * else; the shape is the whole contract.
+ */
+export function defaultBadges(names = {}) {
+  const sales = names.sales ?? 'sales';
+  const properties = names.properties ?? 'properties';
+  const niches = names.niches ?? 'niches';
+  const t = (p, k) => Number(p.totals?.[k] ?? 0);
+  const g = (p, k) => Number(p.gauges?.[k] ?? 0);
+  const bestRank = (p, period) => {
+    let best = Infinity;
+    for (const board of Object.values(p.ranks ?? {})) {
+      const r = board?.[period];
+      if (Number.isFinite(r) && r < best) best = r;
+    }
+    return best;
+  };
+  return [
+    { id: 'first-sale', emoji: '🎉', label: 'First sale', describe: 'Made a first sale', when: (p) => t(p, sales) >= 1 },
+    { id: 'ten-sales', emoji: '🔟', label: 'Ten sales', describe: 'Ten sales, all time', when: (p) => t(p, sales) >= 10 },
+    { id: 'hundred-sales', emoji: '💯', label: 'Hundred sales', describe: 'One hundred sales, all time', when: (p) => t(p, sales) >= 100 },
+    { id: 'streak-7', emoji: '🔥', label: 'Seven day streak', describe: 'Active seven days in a row', when: (p) => (p.bestStreak ?? 0) >= 7 },
+    { id: 'streak-30', emoji: '🌋', label: 'Thirty day streak', describe: 'Active thirty days in a row', when: (p) => (p.bestStreak ?? 0) >= 30 },
+    { id: 'three-properties', emoji: '🏠', label: 'Three properties', describe: 'Owns three properties', when: (p) => g(p, properties) >= 3 },
+    { id: 'five-niches', emoji: '🎯', label: 'Five niches', describe: 'Promotes to five niches', when: (p) => g(p, niches) >= 5 },
+    { id: 'top-ten-week', emoji: '🏅', label: 'Top ten this week', describe: 'Ranked in a weekly top ten', when: (p) => bestRank(p, 'week') <= 10 },
+    { id: 'number-one', emoji: '👑', label: 'Number one', describe: 'Held first place on any board', when: (p) => bestRank(p, 'all') === 1 || bestRank(p, 'week') === 1 || bestRank(p, 'month') === 1 },
+    { id: 'eighty-club', emoji: '💸', label: '80% club', describe: 'Reached the top commission rate', when: (p) => (p.commission?.rate ?? 0) >= 80 },
+  ];
+}

package/src/embed.js

@@ -0,0 +1,167 @@
+/**
+ * The embeddable widget, served by the leaderboard at `${basePath}/embed.js`.
+ * One script tag on any page, ours or a partner's:
+ *
+ *   <div data-leaderboard></div>
+ *   <script src="https://nichedb.dev/leaderboard/embed.js"
+ *           data-board="earnings" data-period="week" data-limit="10"
+ *           data-me="u_42" data-sticky="bottom-right" data-theme="dark"></script>
+ *
+ * Attributes: board, period, limit, me (highlight and show my standing),
+ * sticky (bottom-right | bottom-left | top-right | top-left: a corner pill
+ * that opens the board), theme (light | dark | auto), title, refresh (seconds,
+ * 0 to disable), target (a CSS selector for the container), base (the
+ * leaderboard path when the script is served from somewhere else).
+ *
+ * Kept as a string so the package has no build step and runs at the edge.
+ */
+export function widgetSource() {
+  return WIDGET;
+}
+
+const WIDGET = String.raw`(function () {
+  var script = document.currentScript;
+  if (!script) return;
+  var d = script.dataset;
+  var src = new URL(script.src, location.href);
+  var base = d.base || src.pathname.replace(/\/embed\.js$/, '');
+  var origin = src.origin;
+  var board = d.board || '';
+  var period = d.period || '';
+  var limit = d.limit || '10';
+  var me = d.me || '';
+  var sticky = d.sticky || '';
+  var theme = d.theme || 'auto';
+  var refresh = d.refresh === undefined ? 60 : Number(d.refresh) || 0;
+  var periods = null;
+
+  var CSS = '.pflb{--bg:#fff;--fg:#111827;--muted:#6b7280;--line:#e5e7eb;--accent:#2563eb;--gold:#b45309;--hi:#eff6ff;font:14px/1.4 system-ui,-apple-system,Segoe UI,Roboto,sans-serif;color:var(--fg);background:var(--bg);border:1px solid var(--line);border-radius:12px;overflow:hidden;box-sizing:border-box}' +
+    '.pflb.dark{--bg:#0f1219;--fg:#e8eaf0;--muted:#8b93a7;--line:#242a38;--accent:#7cc4ff;--gold:#fbbf24;--hi:#172033}' +
+    '@media (prefers-color-scheme:dark){.pflb.auto{--bg:#0f1219;--fg:#e8eaf0;--muted:#8b93a7;--line:#242a38;--accent:#7cc4ff;--gold:#fbbf24;--hi:#172033}}' +
+    '.pflb *{box-sizing:border-box}.pflb a{color:inherit;text-decoration:none}' +
+    '.pflb-head{display:flex;align-items:center;justify-content:space-between;gap:8px;padding:12px 14px;border-bottom:1px solid var(--line);flex-wrap:wrap}' +
+    '.pflb-title{font-weight:700;font-size:15px;margin:0}.pflb-tabs{display:flex;gap:4px;flex-wrap:wrap}' +
+    '.pflb-tabs button{font:inherit;font-size:12px;padding:4px 10px;border-radius:999px;border:1px solid var(--line);background:transparent;color:var(--muted);cursor:pointer}' +
+    '.pflb-tabs button.on{background:var(--accent);border-color:var(--accent);color:#fff}' +
+    '.pflb table{width:100%;border-collapse:collapse}.pflb td,.pflb th{padding:9px 14px;text-align:left;border-bottom:1px solid var(--line);white-space:nowrap}' +
+    '.pflb th{font-size:11px;text-transform:uppercase;letter-spacing:.1em;color:var(--muted);font-weight:600}' +
+    '.pflb tr.me td{background:var(--hi)}.pflb td.rank{font-weight:800;color:var(--muted);width:44px}.pflb td.rank.top{color:var(--gold)}' +
+    '.pflb td.name{font-weight:600;white-space:normal}.pflb td.val{font-weight:700;text-align:right}.pflb td.streak{color:var(--muted);text-align:right}' +
+    '.pflb .badges{margin-left:6px;font-size:13px;letter-spacing:1px}.pflb .share{margin-left:8px;font-size:11px;color:var(--muted);cursor:pointer;opacity:0;transition:opacity .15s}.pflb tr:hover .share{opacity:1}' +
+    '.pflb-foot{display:flex;justify-content:space-between;gap:12px;padding:10px 14px;font-size:12px;color:var(--muted);flex-wrap:wrap}.pflb-foot a{color:var(--accent)}' +
+    '.pflb-empty{padding:24px 14px;color:var(--muted);text-align:center}' +
+    '.pflb-pill{position:fixed;z-index:2147483000;font:13px/1 system-ui,-apple-system,Segoe UI,Roboto,sans-serif;background:#111827;color:#fff;border-radius:999px;padding:10px 14px;box-shadow:0 6px 24px rgba(0,0,0,.25);cursor:pointer;border:0;display:flex;align-items:center;gap:8px}' +
+    '.pflb-panel{position:fixed;z-index:2147483000;width:min(420px,calc(100vw - 24px));max-height:min(70vh,640px);overflow:auto;box-shadow:0 12px 40px rgba(0,0,0,.35)}' +
+    '.pflb-panel .pflb-close{font:inherit;background:transparent;border:0;color:var(--muted);cursor:pointer;font-size:18px;line-height:1}';
+
+  function ensureStyle() {
+    if (document.getElementById('pflb-style')) return;
+    var s = document.createElement('style');
+    s.id = 'pflb-style';
+    s.textContent = CSS;
+    document.head.appendChild(s);
+  }
+
+  function findTarget() {
+    if (d.target) { var t = document.querySelector(d.target); if (t) return t; }
+    var prev = script.previousElementSibling;
+    while (prev) { if (prev.hasAttribute('data-leaderboard')) return prev; prev = prev.previousElementSibling; }
+    var any = document.querySelector('[data-leaderboard]:empty');
+    if (any) return any;
+    var div = document.createElement('div');
+    script.parentNode.insertBefore(div, script);
+    return div;
+  }
+
+  function esc(s) { return String(s == null ? '' : s).replace(/[&<>"]/g, function (c) { return { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]; }); }
+  function label(p) { return { all: 'All time', day: 'Today', week: 'Week', month: 'Month' }[p] || p; }
+
+  function url(kind) {
+    var u = origin + base + '/' + board + '.' + kind + '?period=' + encodeURIComponent(period) + '&limit=' + encodeURIComponent(limit);
+    if (me && kind === 'json') u += '&me=' + encodeURIComponent(me);
+    return u;
+  }
+
+  function copy(text, el) {
+    var done = function () { var was = el.textContent; el.textContent = 'copied'; setTimeout(function () { el.textContent = was; }, 1200); };
+    if (navigator.clipboard && navigator.clipboard.writeText) navigator.clipboard.writeText(text).then(done, function () { prompt('Share link', text); });
+    else prompt('Share link', text);
+  }
+
+  function render(root, data) {
+    var rows = data.rows || [];
+    if (!board) board = data.board.id;
+    if (!periods) periods = data.periods || ['all'];
+    period = data.period;
+    var title = d.title || data.board.label;
+    var tabs = periods.map(function (p) { return '<button type="button" data-p="' + esc(p) + '" class="' + (p === period ? 'on' : '') + '">' + esc(label(p)) + '</button>'; }).join('');
+    var body = rows.length ? rows.map(function (r) {
+      var isMe = me && r.id === me;
+      var badges = (r.badges || []).map(function (b) { return '<span title="' + esc(b.label) + '">' + esc(b.emoji) + '</span>'; }).join('');
+      var share = origin + base + '/u/' + encodeURIComponent(r.id);
+      return '<tr class="' + (isMe ? 'me' : '') + '">' +
+        '<td class="rank ' + (r.rank <= 3 ? 'top' : '') + '">' + (r.rank < 10 ? '0' : '') + r.rank + '</td>' +
+        '<td class="name"><a href="' + esc(origin + r.url) + '">' + esc(r.name) + '</a>' + (badges ? '<span class="badges">' + badges + '</span>' : '') +
+          (r.commission != null ? ' <span style="color:var(--muted);font-weight:400;font-size:12px">' + r.commission + '%</span>' : '') +
+          '<span class="share" data-share="' + esc(share) + '">share</span></td>' +
+        '<td class="val">' + esc(r.display) + '</td>' +
+        '<td class="streak" title="streak">' + (r.streak ? '🔥' + r.streak : '') + '</td></tr>';
+    }).join('') : '';
+    var meRow = '';
+    if (data.me && !rows.some(function (r) { return r.id === me; })) {
+      var m = data.me;
+      meRow = '<tr class="me"><td class="rank">' + (m.rank ? (m.rank < 10 ? '0' : '') + m.rank : '–') + '</td><td class="name">' + esc(m.name) + ' <span style="color:var(--muted);font-weight:400">(you)</span></td><td class="val">' + esc(m.display) + '</td><td class="streak">' + (m.streak ? '🔥' + m.streak : '') + '</td></tr>';
+    }
+    root.innerHTML =
+      '<div class="pflb-head"><h3 class="pflb-title">' + esc(title) + '</h3><div class="pflb-tabs">' + tabs + '</div>' + (root.classList.contains('pflb-panel') ? '<button class="pflb-close" aria-label="Close">×</button>' : '') + '</div>' +
+      (rows.length || meRow
+        ? '<table><thead><tr><th>#</th><th>Name</th><th style="text-align:right">' + esc(data.board.unit || data.board.label) + '</th><th></th></tr></thead><tbody>' + body + meRow + '</tbody></table>'
+        : '<div class="pflb-empty">Nobody on the board yet. Be first.</div>') +
+      '<div class="pflb-foot"><span>' + esc(label(period)) + ' · ' + esc(String(data.total || rows.length)) + ' ranked</span><span><a href="' + esc(url('xml')) + '">RSS</a> · <a href="' + esc(origin + base + '?board=' + encodeURIComponent(board) + '&period=' + encodeURIComponent(period)) + '">Full board</a></span></div>';
+    root.querySelectorAll('.pflb-tabs button').forEach(function (b) { b.addEventListener('click', function () { period = b.dataset.p; load(root); }); });
+    root.querySelectorAll('.share').forEach(function (s) { s.addEventListener('click', function (e) { e.preventDefault(); copy(s.dataset.share, s); }); });
+    var close = root.querySelector('.pflb-close');
+    if (close) close.addEventListener('click', function () { root.hidden = true; });
+    root.dispatchEvent(new CustomEvent('leaderboard:render', { bubbles: true, detail: data }));
+    return data;
+  }
+
+  function load(root) {
+    if (!board) {
+      return fetch(origin + base + '.json').then(function (r) { return r.json(); }).then(function (idx) {
+        board = (idx.boards[0] || {}).id; periods = idx.periods; period = period || idx.defaultPeriod; return load(root);
+      });
+    }
+    return fetch(url('json')).then(function (r) { return r.json(); }).then(function (data) { return render(root, data); }).catch(function () {
+      root.innerHTML = '<div class="pflb-empty">Leaderboard unavailable.</div>';
+    });
+  }
+
+  ensureStyle();
+  var root;
+  if (sticky) {
+    var pos = sticky.split('-');
+    var v = pos[0] === 'top' ? 'top' : 'bottom', h = pos[1] === 'left' ? 'left' : 'right';
+    var pill = document.createElement('button');
+    pill.className = 'pflb-pill';
+    pill.style[v] = '16px'; pill.style[h] = '16px';
+    pill.innerHTML = '🏆 <span>Leaderboard</span>';
+    root = document.createElement('div');
+    root.className = 'pflb pflb-panel ' + theme;
+    root.hidden = true;
+    root.style[v] = '64px'; root.style[h] = '16px';
+    document.body.appendChild(pill); document.body.appendChild(root);
+    pill.addEventListener('click', function () { root.hidden = !root.hidden; if (!root.hidden) load(root); });
+    root.addEventListener('leaderboard:render', function (e) {
+      var data = e.detail; var m = data.me; var top = (data.rows || [])[0];
+      pill.querySelector('span').textContent = m && m.rank ? 'You are #' + m.rank + ' ' + label(data.period).toLowerCase() : top ? '#1 ' + top.name : 'Leaderboard';
+    });
+    load(root);
+  } else {
+    root = findTarget();
+    root.classList.add('pflb', theme);
+    load(root);
+  }
+  if (refresh > 0) setInterval(function () { if (!document.hidden && !root.hidden) load(root); }, refresh * 1000);
+})();
+`;

package/src/hono.js

@@ -0,0 +1,21 @@
+import { createLeaderboard } from './index.js';
+
+/**
+ * The leaderboard as Hono middleware: JSON, RSS, the share card, the embed
+ * page and the widget script, all under `basePath`.
+ *
+ *   import { leaderboard } from '@profullstack/leaderboard/hono';
+ *   const lb = createLeaderboard({ store, boards });
+ *   app.use('*', leaderboard(lb));
+ *
+ * Takes either options or a leaderboard already created, so an app can keep
+ * the instance around for `record()` and `set()`.
+ */
+export function leaderboard(lbOrOptions) {
+  const lb = lbOrOptions && typeof lbOrOptions.handle === 'function' ? lbOrOptions : createLeaderboard(lbOrOptions);
+  return async (c, next) => {
+    const answer = await lb.handle(c.req.raw);
+    if (answer) return answer;
+    await next();
+  };
+}

package/src/index.js

@@ -0,0 +1,432 @@
+import { memoryStore } from './store/memory.js';
+import { commissionLadder } from './ladder.js';
+import { defaultBadges } from './badges.js';
+import { widgetSource } from './embed.js';
+
+export { commissionLadder } from './ladder.js';
+export { defaultBadges } from './badges.js';
+export { memoryStore } from './store/memory.js';
+export { sqlStore } from './store/sql.js';
+
+const DAY = 86_400_000;
+const PERIODS = { all: 0, day: DAY, week: 7 * DAY, month: 30 * DAY };
+
+/**
+ * Build a leaderboard.
+ *
+ *   const lb = createLeaderboard({
+ *     siteName: 'NicheDB', siteUrl: 'https://nichedb.dev',
+ *     store: sqlStore({ execute }),
+ *     boards: {
+ *       earnings: { label: 'Top earners', metric: 'cents', format: 'usd' },
+ *       sales:    { label: 'Most sales',  metric: 'sales' },
+ *       streaks:  { label: 'Longest streaks', metric: 'streak' },
+ *     },
+ *     ladder: commissionLadder(),
+ *   });
+ *   await lb.record({ player: 'u_42', name: 'Dr. Okafor', metrics: { cents: 1900, sales: 1 } });
+ *   await lb.set({ player: 'u_42', metrics: { properties: 2, niches: 4 } });
+ *
+ * Counters go in through `record` and are summed per period; gauges go in
+ * through `set` and are the current value. `streak` and `bestStreak` are
+ * derived from the days a player recorded anything. Every board ranks one
+ * metric of any of those three kinds.
+ */
+export function createLeaderboard(options = {}) {
+  const store = options.store ?? memoryStore();
+  const basePath = trimSlash(options.basePath ?? '/leaderboard');
+  const siteName = options.siteName ?? 'Leaderboard';
+  const siteUrl = options.siteUrl ? trimSlash(options.siteUrl) : '';
+  const periods = (options.periods ?? ['all', 'week', 'month']).filter((p) => p in PERIODS);
+  const defaultPeriod = periods.includes(options.defaultPeriod) ? options.defaultPeriod : periods[0];
+  const boards = normaliseBoards(options.boards);
+  const defaultBoard = boards[0].id;
+  const ladder = options.ladder === undefined ? null : options.ladder === true ? commissionLadder() : options.ladder;
+  const badges = options.badges ?? (ladder ? defaultBadges({ properties: ladder.propertiesMetric, niches: ladder.nichesMetric }) : defaultBadges());
+  const cacheMs = Math.max(0, Number(options.cacheMs ?? 15_000));
+  const limitMax = Math.max(1, Number(options.limitMax ?? 100));
+  const profileUrl = options.profileUrl ?? ((id) => `${basePath}/u/${encodeURIComponent(id)}`);
+  const now = options.now ?? (() => Date.now());
+  const onBadge = options.onBadge ?? null;
+
+  let cache = null; // { at, all: Map<player, profile>, ordered }
+
+  async function record({ player, name, metrics, at } = {}) {
+    if (!player) throw new TypeError('record needs a player');
+    const when = at ?? now();
+    const entries = Object.entries(metrics ?? {}).filter(([, v]) => Number.isFinite(Number(v)));
+    if (!entries.length) throw new TypeError('record needs at least one numeric metric');
+    for (const [metric, delta] of entries) await store.append({ player: String(player), name, metric, delta: Number(delta), at: when });
+    cache = null;
+    return award(String(player));
+  }
+
+  async function set({ player, name, metrics, at } = {}) {
+    if (!player) throw new TypeError('set needs a player');
+    const when = at ?? now();
+    for (const [metric, value] of Object.entries(metrics ?? {})) await store.setGauge(String(player), metric, Number(value), name, when);
+    cache = null;
+    return award(String(player));
+  }
+
+  /** Re-check every badge for one player; returns the badges newly awarded. */
+  async function award(player) {
+    const profiles = await computeAll();
+    const p = profiles.get(player);
+    if (!p) return [];
+    const fresh = [];
+    for (const b of badges) {
+      if (p.badges.some((x) => x.id === b.id)) continue;
+      let hit = false;
+      try { hit = Boolean(b.when(p)); } catch { hit = false; }
+      if (!hit) continue;
+      const at = now();
+      if (await store.awardBadge(player, b.id, at)) {
+        const earned = { id: b.id, emoji: b.emoji ?? '', label: b.label ?? b.id, describe: b.describe ?? '', at };
+        p.badges.push(earned);
+        fresh.push(earned);
+        if (onBadge) { try { await onBadge({ player, name: p.name, badge: earned }); } catch {} }
+      }
+    }
+    return fresh;
+  }
+
+  /** Every player's all-time profile, cached for `cacheMs`. */
+  async function computeAll() {
+    if (cache && now() - cache.at < cacheMs) return cache.all;
+    const t = now();
+    const [events, gauges, awarded] = await Promise.all([store.list({ since: 0 }), store.gauges(), store.badges()]);
+    const all = new Map();
+    const profile = (id) => all.get(id) ?? (all.set(id, blank(id)), all.get(id));
+    for (const e of events) {
+      const p = profile(e.player);
+      p.totals[e.metric] = (p.totals[e.metric] ?? 0) + e.delta;
+      if (e.name && e.at >= p.nameAt) { p.name = e.name; p.nameAt = e.at; }
+      if (e.at > p.lastAt) p.lastAt = e.at;
+      if (e.at < p.firstAt) p.firstAt = e.at;
+      p.days.add(dayOf(e.at));
+    }
+    for (const [id, row] of Object.entries(gauges)) {
+      const p = profile(id);
+      p.gauges = { ...row.values };
+      if (row.name && row.at >= p.nameAt) { p.name = row.name; p.nameAt = row.at; }
+    }
+    for (const p of all.values()) {
+      const s = streaks(p.days, t);
+      p.streak = s.current;
+      p.bestStreak = s.best;
+      if (ladder) p.commission = { rate: ladder.rate(p.gauges), next: ladder.next(p.gauges) };
+      delete p.days;
+    }
+    // Windows and ranks: each board, each period.
+    const byPeriod = {};
+    for (const period of periods) byPeriod[period] = windowTotals(events, all, period, t);
+    for (const b of boards) {
+      for (const period of periods) {
+        const ranked = rank(b, all, byPeriod[period]);
+        ranked.forEach((r, i) => {
+          const p = all.get(r.id);
+          (p.ranks[b.id] ??= {})[period] = i + 1;
+          (p.values[b.id] ??= {})[period] = r.value;
+        });
+      }
+    }
+    for (const p of all.values()) {
+      const mine = awarded[p.id] ?? {};
+      p.badges = badges.filter((b) => mine[b.id]).map((b) => ({ id: b.id, emoji: b.emoji ?? '', label: b.label ?? b.id, describe: b.describe ?? '', at: mine[b.id] }));
+    }
+    cache = { at: t, all };
+    return all;
+  }
+
+  function windowTotals(events, all, period, t) {
+    if (period === 'all') return null;
+    const since = t - PERIODS[period];
+    const totals = new Map();
+    for (const e of events) {
+      if (e.at < since) continue;
+      const row = totals.get(e.player) ?? {};
+      row[e.metric] = (row[e.metric] ?? 0) + e.delta;
+      totals.set(e.player, row);
+    }
+    return totals;
+  }
+
+  function valueOf(board, p, window) {
+    const m = board.metric;
+    if (m === 'streak') return p.streak;
+    if (m === 'bestStreak') return p.bestStreak;
+    if (m in p.gauges) return p.gauges[m];
+    if (window) return window.get(p.id)?.[m] ?? 0;
+    return p.totals[m] ?? 0;
+  }
+
+  function rank(board, all, window) {
+    const rows = [];
+    for (const p of all.values()) {
+      const value = valueOf(board, p, window);
+      if (value < board.min) continue;
+      if (window && !window.has(p.id) && !(board.metric in p.gauges) && board.metric !== 'streak' && board.metric !== 'bestStreak') continue;
+      rows.push({ id: p.id, value, tie: board.tiebreak ? valueOf({ metric: board.tiebreak, min: -Infinity }, p, window) : 0, lastAt: p.lastAt, name: p.name });
+    }
+    const dir = board.order === 'asc' ? 1 : -1;
+    rows.sort((a, b) => (a.value - b.value) * dir || (b.tie - a.tie) || (a.lastAt - b.lastAt) || a.name.localeCompare(b.name));
+    return rows;
+  }
+
+  function boardOf(id) {
+    return boards.find((b) => b.id === id) ?? null;
+  }
+
+  function periodOf(p) {
+    return periods.includes(p) ? p : defaultPeriod;
+  }
+
+  async function top({ board = defaultBoard, period = defaultPeriod, limit = 25, offset = 0 } = {}) {
+    const b = boardOf(board);
+    if (!b) throw new RangeError(`unknown board: ${board}`);
+    period = periodOf(period);
+    const all = await computeAll();
+    const rows = [];
+    for (const p of all.values()) {
+      const r = p.ranks[b.id]?.[period];
+      if (r) rows.push(row(p, b, period, r));
+    }
+    rows.sort((a, c) => a.rank - c.rank);
+    const n = Math.min(limitMax, Math.max(1, Number(limit) || 25));
+    return { board: pub(b), period, periods, generatedAt: new Date(now()).toISOString(), total: rows.length, rows: rows.slice(Number(offset) || 0, (Number(offset) || 0) + n) };
+  }
+
+  async function standing({ player, board = defaultBoard, period = defaultPeriod } = {}) {
+    const b = boardOf(board);
+    if (!b || !player) return null;
+    period = periodOf(period);
+    const all = await computeAll();
+    const p = all.get(String(player));
+    if (!p) return null;
+    const r = p.ranks[b.id]?.[period] ?? null;
+    return { ...row(p, b, period, r), qualified: r !== null, min: b.min };
+  }
+
+  async function profile(player) {
+    const all = await computeAll();
+    const p = all.get(String(player));
+    if (!p) return null;
+    const { nameAt, ...rest } = p;
+    return { ...rest, url: profileUrl(p.id), shareUrl: `${siteUrl}${basePath}/u/${encodeURIComponent(p.id)}` };
+  }
+
+  function row(p, b, period, r) {
+    const value = p.values[b.id]?.[period] ?? 0;
+    return {
+      rank: r, id: p.id, name: p.name, value, display: format(value, b.format),
+      streak: p.streak, bestStreak: p.bestStreak,
+      badges: p.badges.map(({ id, emoji, label }) => ({ id, emoji, label })),
+      commission: p.commission ? p.commission.rate : undefined,
+      url: profileUrl(p.id),
+    };
+  }
+
+  function boardsIndex() {
+    return { site: siteName, siteUrl, basePath, periods, defaultPeriod, boards: boards.map(pub), ladder: ladder ? { base: ladder.base, cap: ladder.cap, describe: ladder.describe() } : null, badges: badges.map(({ id, emoji, label, describe }) => ({ id, emoji, label, describe })) };
+  }
+
+  /** Fetch-API handler: answers under basePath, null for anything else. */
+  async function handle(request) {
+    if (request.method !== 'GET' && request.method !== 'HEAD') return null;
+    const url = new URL(request.url);
+    const path = trimSlash(url.pathname);
+    if (path !== basePath && !path.startsWith(basePath + '/') && path !== basePath + '.json') return null;
+    const rest = path === basePath ? '' : path.slice(basePath.length);
+    const q = url.searchParams;
+    const period = periodOf(q.get('period'));
+    const limit = q.get('limit') ?? 25;
+
+    if (rest === '.json' || rest === '/index.json') return json(boardsIndex());
+    if (rest === '/embed.js') return new Response(widgetSource(), { headers: { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'public, max-age=3600' } });
+    if (rest === '' || rest === '/embed' || rest === '/index.html') {
+      const b = boardOf(q.get('board') ?? defaultBoard) ?? boards[0];
+      return html(embedPage({ board: b, period, limit, sticky: q.get('sticky'), theme: q.get('theme'), me: q.get('me'), full: rest !== '/embed' }));
+    }
+    let m;
+    if ((m = rest.match(/^\/u\/([^/]+)\.json$/))) {
+      const p = await profile(decodeURIComponent(m[1]));
+      return p ? json(p) : json({ error: 'unknown player' }, 404);
+    }
+    if ((m = rest.match(/^\/u\/([^/]+)$/))) {
+      const p = await profile(decodeURIComponent(m[1]));
+      return p ? html(sharePage(p)) : html(notFoundPage(), 404);
+    }
+    if ((m = rest.match(/^\/([a-z0-9_-]+)\.(json|xml|rss)$/i))) {
+      const b = boardOf(m[1]);
+      if (!b) return json({ error: 'unknown board' }, 404);
+      const result = await top({ board: b.id, period, limit, offset: q.get('offset') ?? 0 });
+      if (m[2] === 'json') {
+        const me = q.get('me');
+        if (me) result.me = await standing({ player: me, board: b.id, period });
+        return json(result);
+      }
+      return new Response(rss(result), { headers: { 'content-type': 'application/rss+xml; charset=utf-8', 'cache-control': 'public, max-age=300' } });
+    }
+    return null;
+  }
+
+  function rss(result) {
+    const title = `${siteName}: ${result.board.label} (${periodLabel(result.period)})`;
+    const link = `${siteUrl}${basePath}?board=${result.board.id}&period=${result.period}`;
+    const items = result.rows.map((r) => {
+      const badgeText = r.badges.map((b) => `${b.emoji} ${b.label}`).join(', ');
+      return `    <item>
+      <title>${esc(`#${r.rank} ${r.name}: ${r.display}`)}</title>
+      <link>${esc(absolute(r.url))}</link>
+      <guid isPermaLink="false">${esc(`${result.board.id}:${result.period}:${r.id}:${r.value}`)}</guid>
+      <description>${esc(`${r.name} is #${r.rank} on ${result.board.label} with ${r.display}. Streak ${r.streak} (best ${r.bestStreak}).${badgeText ? ' Badges: ' + badgeText + '.' : ''}`)}</description>
+    </item>`;
+    });
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0">
+  <channel>
+    <title>${esc(title)}</title>
+    <link>${esc(link)}</link>
+    <description>${esc(`Top ${result.rows.length} on ${result.board.label}, ${periodLabel(result.period)}.`)}</description>
+    <lastBuildDate>${new Date(result.generatedAt).toUTCString()}</lastBuildDate>
+${items.join('\n')}
+  </channel>
+</rss>
+`;
+  }
+
+  function embedPage({ board, period, limit, sticky, theme, me, full }) {
+    const attrs = [
+      `data-board="${esc(board.id)}"`, `data-period="${esc(period)}"`, `data-limit="${esc(String(limit))}"`,
+      sticky ? `data-sticky="${esc(sticky)}"` : '', theme ? `data-theme="${esc(theme)}"` : '', me ? `data-me="${esc(me)}"` : '',
+      `data-base="${esc(basePath)}"`,
+    ].filter(Boolean).join(' ');
+    const title = `${board.label}: ${siteName}`;
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${esc(title)}</title>
+<meta property="og:title" content="${esc(title)}"><meta property="og:description" content="${esc(`Live ${periodLabel(period)} ranking on ${siteName}.`)}">
+<link rel="alternate" type="application/rss+xml" title="${esc(title)}" href="${esc(`${basePath}/${board.id}.xml?period=${period}`)}">
+<style>body{margin:0;background:transparent;font-family:system-ui,-apple-system,Segoe UI,Roboto,sans-serif}${full ? 'main{max-width:760px;margin:0 auto;padding:24px 16px}' : 'main{padding:8px}'}</style>
+</head><body><main><div data-leaderboard></div>
+<script src="${esc(basePath)}/embed.js" ${attrs}></script>
+</main></body></html>`;
+  }
+
+  function sharePage(p) {
+    const lines = boards.map((b) => {
+      const r = p.ranks[b.id]?.[defaultPeriod];
+      const v = p.values[b.id]?.[defaultPeriod];
+      return r ? `<li><strong>#${r}</strong> on ${esc(b.label)} <span class="muted">(${esc(periodLabel(defaultPeriod))}, ${esc(format(v, b.format))})</span></li>` : '';
+    }).filter(Boolean).join('');
+    const bestRank = Math.min(...boards.map((b) => p.ranks[b.id]?.[defaultPeriod] ?? Infinity));
+    const headline = Number.isFinite(bestRank) ? `#${bestRank} on ${siteName}` : `${p.name} on ${siteName}`;
+    const desc = `${p.name}: streak ${p.streak} (best ${p.bestStreak}), ${p.badges.length} badge${p.badges.length === 1 ? '' : 's'}${p.commission ? `, ${p.commission.rate}% commission` : ''}.`;
+    const badgeHtml = p.badges.map((b) => `<li title="${esc(b.describe)}"><span class="e">${esc(b.emoji)}</span> ${esc(b.label)}</li>`).join('') || '<li class="muted">No badges yet.</li>';
+    const ladderHtml = p.commission ? `<section><h2>Commission</h2><p class="big">${p.commission.rate}%</p><p class="muted">${p.commission.next ? esc(`Add one ${p.commission.next.add} to reach ${p.commission.next.rate}%.`) : esc(`At the cap. ${ladder.describe()}`)}</p></section>` : '';
+    const boardUrl = `${siteUrl}${basePath}`;
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${esc(`${p.name}: ${headline}`)}</title>
+<meta property="og:type" content="profile"><meta property="og:title" content="${esc(`${p.name}: ${headline}`)}"><meta property="og:description" content="${esc(desc)}"><meta property="og:url" content="${esc(p.shareUrl)}">
+<meta name="twitter:card" content="summary"><meta name="twitter:title" content="${esc(`${p.name}: ${headline}`)}"><meta name="twitter:description" content="${esc(desc)}">
+<link rel="alternate" type="application/json" href="${esc(`${basePath}/u/${encodeURIComponent(p.id)}.json`)}">
+<style>
+:root{color-scheme:light dark}body{margin:0;font-family:system-ui,-apple-system,Segoe UI,Roboto,sans-serif;background:#0b0d12;color:#e8eaf0}
+main{max-width:640px;margin:0 auto;padding:40px 20px}h1{font-size:28px;margin:0 0 4px}h2{font-size:12px;text-transform:uppercase;letter-spacing:.12em;color:#8b93a7;margin:24px 0 8px}
+.big{font-size:40px;font-weight:800;margin:0}.muted{color:#8b93a7}ul{list-style:none;padding:0;margin:0}li{padding:8px 0;border-bottom:1px solid #1f2430}.e{font-size:20px;margin-right:6px}
+a{color:#7cc4ff}.stats{display:flex;gap:24px;flex-wrap:wrap}.stats div b{display:block;font-size:22px}
+</style></head><body><main>
+<p class="muted"><a href="${esc(boardUrl)}">${esc(siteName)} leaderboard</a></p>
+<h1>${esc(p.name)}</h1><p class="muted">${esc(headline)}</p>
+<div class="stats"><div><b>${p.streak}</b><span class="muted">day streak</span></div><div><b>${p.bestStreak}</b><span class="muted">best streak</span></div><div><b>${p.badges.length}</b><span class="muted">badges</span></div></div>
+<section><h2>Boards</h2><ul>${lines || '<li class="muted">Not on a board yet.</li>'}</ul></section>
+<section><h2>Badges</h2><ul>${badgeHtml}</ul></section>
+${ladderHtml}
+<p class="muted" style="margin-top:32px"><a href="${esc(p.shareUrl)}">Share this page</a></p>
+</main></body></html>`;
+  }
+
+  function notFoundPage() {
+    return `<!doctype html><meta charset="utf-8"><title>Not found</title><p>No such player.</p>`;
+  }
+
+  function absolute(u) {
+    return /^https?:/.test(u) ? u : `${siteUrl}${u}`;
+  }
+
+  return {
+    record, set, top, standing, profile, handle, award,
+    boards: boards.map(pub), periods, basePath, ladder, badges,
+    index: boardsIndex,
+    rss: async (opts) => rss(await top(opts)),
+    widget: widgetSource,
+    /** Drop the cache, e.g. after writing to the store from elsewhere. */
+    invalidate() { cache = null; },
+  };
+}
+
+function normaliseBoards(input) {
+  const src = input && Object.keys(input).length ? input : { top: { label: 'Top', metric: 'score' } };
+  const list = Array.isArray(src) ? src : Object.entries(src).map(([id, b]) => ({ id, ...b }));
+  return list.map((b) => {
+    if (!b.id || !/^[a-z0-9_-]+$/i.test(b.id)) throw new TypeError(`board id must be [a-z0-9_-]: ${b.id}`);
+    return { id: b.id, label: b.label ?? b.id, metric: b.metric ?? 'score', format: b.format ?? 'number', min: Number.isFinite(b.min) ? b.min : Number.MIN_VALUE, order: b.order === 'asc' ? 'asc' : 'desc', tiebreak: b.tiebreak ?? null, unit: b.unit ?? '' };
+  });
+}
+
+function pub(b) {
+  return { id: b.id, label: b.label, metric: b.metric, format: b.format, unit: b.unit };
+}
+
+function blank(id) {
+  return { id, name: id, nameAt: 0, totals: {}, gauges: {}, days: new Set(), streak: 0, bestStreak: 0, firstAt: Infinity, lastAt: 0, ranks: {}, values: {}, badges: [], commission: undefined };
+}
+
+function dayOf(at) {
+  return Math.floor(at / DAY);
+}
+
+/** Current = consecutive days ending today or yesterday; best = longest run ever. */
+export function streaks(days, now = Date.now()) {
+  const sorted = [...days].sort((a, b) => a - b);
+  let best = 0, run = 0, prev = null;
+  for (const d of sorted) {
+    run = prev !== null && d === prev + 1 ? run + 1 : 1;
+    if (run > best) best = run;
+    prev = d;
+  }
+  const today = dayOf(now);
+  const last = sorted[sorted.length - 1];
+  const current = last === today || last === today - 1 ? run : 0;
+  return { current, best };
+}
+
+export function format(value, kind = 'number', locale = 'en-US') {
+  const n = Number(value) || 0;
+  if (kind === 'usd') return (n / 100).toLocaleString(locale, { style: 'currency', currency: 'USD' });
+  if (kind === 'percent') return `${Math.round(n)}%`;
+  if (kind === 'integer') return Math.round(n).toLocaleString(locale);
+  return Number.isInteger(n) ? n.toLocaleString(locale) : n.toLocaleString(locale, { maximumFractionDigits: 2 });
+}
+
+export function periodLabel(p) {
+  return { all: 'all time', day: 'today', week: 'this week', month: 'this month' }[p] ?? p;
+}
+
+function trimSlash(s) {
+  return String(s).replace(/\/+$/, '') || '/';
+}
+
+function esc(s) {
+  return String(s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+}
+
+function json(body, status = 200) {
+  return new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'public, max-age=15', 'access-control-allow-origin': '*' } });
+}
+
+function html(body, status = 200) {
+  return new Response(body, { status, headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'public, max-age=60' } });
+}

package/src/ladder.js

@@ -0,0 +1,76 @@
+/**
+ * The commission ladder: a seller's cut climbs with the number of properties
+ * they own and the number of niches they can promote to. The defaults are the
+ * program as announced: start at 20%, top out at 80%, five points per property
+ * and five per niche, six of each to reach the cap.
+ *
+ *   const ladder = commissionLadder();
+ *   ladder.rate({ properties: 1, niches: 0 });   // 25
+ *   ladder.next({ properties: 1, niches: 0 });   // { add: 'property', rate: 30, ... }
+ *
+ * Every number is an option, so a program with a different shape passes its
+ * own. `rate()` returns whole percent as an integer.
+ */
+export function commissionLadder(options = {}) {
+  const base = num(options.base, 20);
+  const cap = num(options.cap, 80);
+  const perProperty = num(options.perProperty, 5);
+  const perNiche = num(options.perNiche, 5);
+  const maxProperties = num(options.maxProperties, 6);
+  const maxNiches = num(options.maxNiches, 6);
+  const propertiesMetric = options.propertiesMetric ?? 'properties';
+  const nichesMetric = options.nichesMetric ?? 'niches';
+
+  function counts(state = {}) {
+    const properties = Math.max(0, Math.floor(num(state[propertiesMetric] ?? state.properties, 0)));
+    const niches = Math.max(0, Math.floor(num(state[nichesMetric] ?? state.niches, 0)));
+    return { properties, niches };
+  }
+
+  function rate(state) {
+    const { properties, niches } = counts(state);
+    const raw = base + perProperty * Math.min(properties, maxProperties) + perNiche * Math.min(niches, maxNiches);
+    return Math.min(cap, Math.max(0, Math.round(raw)));
+  }
+
+  /** The single cheapest step up from here, or null at the cap. */
+  function next(state) {
+    const c = counts(state);
+    const here = rate(c);
+    if (here >= cap) return null;
+    const candidates = [];
+    if (c.properties < maxProperties) {
+      candidates.push({ add: 'property', rate: rate({ properties: c.properties + 1, niches: c.niches }) });
+    }
+    if (c.niches < maxNiches) {
+      candidates.push({ add: 'niche', rate: rate({ properties: c.properties, niches: c.niches + 1 }) });
+    }
+    const better = candidates.filter((x) => x.rate > here).sort((a, b) => b.rate - a.rate);
+    const pick = better[0];
+    if (!pick) return null;
+    return { ...pick, from: here, gain: pick.rate - here, toCap: cap - here };
+  }
+
+  /** Every step on the ladder, for a docs table or a pricing page. */
+  function table() {
+    const rows = [];
+    for (let p = 0; p <= maxProperties; p++) {
+      for (let n = 0; n <= maxNiches; n++) rows.push({ properties: p, niches: n, rate: rate({ properties: p, niches: n }) });
+    }
+    return rows;
+  }
+
+  function describe() {
+    return `Start at ${base}%. Each property adds ${perProperty} points (up to ${maxProperties}), each niche adds ${perNiche} (up to ${maxNiches}). Cap ${cap}%.`;
+  }
+
+  return {
+    base, cap, perProperty, perNiche, maxProperties, maxNiches, propertiesMetric, nichesMetric,
+    rate, next, table, describe,
+  };
+}
+
+function num(v, fallback) {
+  const n = Number(v);
+  return Number.isFinite(n) ? n : fallback;
+}

package/src/next.js

@@ -0,0 +1,18 @@
+import { createLeaderboard } from './index.js';
+
+/**
+ * A Route Handler for Next.js. Mount it on a catch-all under the base path:
+ *
+ *   // app/leaderboard/[[...path]]/route.js
+ *   import { leaderboardRoute } from '@profullstack/leaderboard/next';
+ *   export const { GET } = leaderboardRoute(lb);
+ *   export const dynamic = 'force-dynamic';
+ *
+ * Anything the leaderboard does not answer 404s, which is what a route under
+ * its own path should do.
+ */
+export function leaderboardRoute(lbOrOptions) {
+  const lb = lbOrOptions && typeof lbOrOptions.handle === 'function' ? lbOrOptions : createLeaderboard(lbOrOptions);
+  const GET = async (request) => (await lb.handle(request)) ?? new Response('Not found', { status: 404 });
+  return { GET, HEAD: GET };
+}

package/src/store/memory.js

@@ -0,0 +1,54 @@
+/**
+ * The in-memory store: the reference implementation of the store contract,
+ * and enough for a single process, tests, or a leaderboard that is rebuilt
+ * from somewhere else on boot.
+ *
+ * The contract every store meets:
+ *   append(event)            -> void          event: { player, name, metric, delta, at }
+ *   list({ since })          -> event[]       at >= since, any order
+ *   setGauge(player, metric, value, name, at) -> void
+ *   gauges()                 -> { [player]: { name, at, values: { [metric]: number } } }
+ *   awardBadge(player, badge, at) -> boolean  true when newly awarded
+ *   badges()                 -> { [player]: { [badge]: at } }
+ */
+export function memoryStore() {
+  const events = [];
+  const gauges = new Map();
+  const badges = new Map();
+  return {
+    async append(ev) {
+      events.push({ ...ev });
+    },
+    async list({ since = 0 } = {}) {
+      return since > 0 ? events.filter((e) => e.at >= since) : events.slice();
+    },
+    async setGauge(player, metric, value, name, at) {
+      const row = gauges.get(player) ?? { name, at, values: {} };
+      row.values[metric] = value;
+      if (name) row.name = name;
+      row.at = at;
+      gauges.set(player, row);
+    },
+    async gauges() {
+      const out = {};
+      for (const [player, row] of gauges) out[player] = { name: row.name, at: row.at, values: { ...row.values } };
+      return out;
+    },
+    async awardBadge(player, badge, at) {
+      const row = badges.get(player) ?? {};
+      if (row[badge]) return false;
+      row[badge] = at;
+      badges.set(player, row);
+      return true;
+    },
+    async badges() {
+      const out = {};
+      for (const [player, row] of badges) out[player] = { ...row };
+      return out;
+    },
+    /** Test helper: everything, for assertions. */
+    _dump() {
+      return { events: events.slice(), gauges: Object.fromEntries(gauges), badges: Object.fromEntries(badges) };
+    },
+  };
+}

package/src/store/sql.js

@@ -0,0 +1,88 @@
+/**
+ * A store over any SQL client with `execute({ sql, args }) -> { rows }`:
+ * @libsql/client (Turso), better-sqlite3 behind a shim, node-postgres behind
+ * a shim, Bun's SQL. Three tables, created by `migrate()` or by running
+ * `schema` in your own migration tool.
+ *
+ *   import { createClient } from '@libsql/client';
+ *   const store = sqlStore({ execute: (q) => createClient({ url }).execute(q) });
+ *   await store.migrate();
+ *
+ * `dialect: 'postgres'` swaps `?` placeholders for `$n` and picks Postgres
+ * types; the default is SQLite. Rows come back as objects keyed by column name
+ * in both clients.
+ */
+export function sqlStore({ execute, prefix = 'lb_', dialect = 'sqlite' } = {}) {
+  if (typeof execute !== 'function') throw new TypeError('sqlStore needs an execute({ sql, args }) function');
+  const T = { events: `${prefix}events`, gauges: `${prefix}gauges`, badges: `${prefix}badges` };
+  const pg = dialect === 'postgres';
+  const q = (sql) => {
+    if (!pg) return sql;
+    let i = 0;
+    return sql.replace(/\?/g, () => `$${++i}`);
+  };
+  const run = (sql, args = []) => execute({ sql: q(sql), args });
+  const rows = async (sql, args) => (await run(sql, args))?.rows ?? [];
+  const idType = pg ? 'BIGSERIAL PRIMARY KEY' : 'INTEGER PRIMARY KEY AUTOINCREMENT';
+  const schema = [
+    `CREATE TABLE IF NOT EXISTS ${T.events} (id ${idType}, player TEXT NOT NULL, name TEXT, metric TEXT NOT NULL, delta DOUBLE PRECISION NOT NULL, at BIGINT NOT NULL)`,
+    `CREATE INDEX IF NOT EXISTS ${T.events}_at ON ${T.events} (at)`,
+    `CREATE INDEX IF NOT EXISTS ${T.events}_player ON ${T.events} (player)`,
+    `CREATE TABLE IF NOT EXISTS ${T.gauges} (player TEXT NOT NULL, metric TEXT NOT NULL, value DOUBLE PRECISION NOT NULL, name TEXT, at BIGINT NOT NULL, PRIMARY KEY (player, metric))`,
+    `CREATE TABLE IF NOT EXISTS ${T.badges} (player TEXT NOT NULL, badge TEXT NOT NULL, at BIGINT NOT NULL, PRIMARY KEY (player, badge))`,
+  ];
+
+  return {
+    schema,
+    tables: T,
+    async migrate() {
+      for (const sql of schema) await run(sql);
+    },
+    async append(ev) {
+      await run(`INSERT INTO ${T.events} (player, name, metric, delta, at) VALUES (?, ?, ?, ?, ?)`, [
+        ev.player, ev.name ?? null, ev.metric, ev.delta, ev.at,
+      ]);
+    },
+    async list({ since = 0 } = {}) {
+      const r = since > 0
+        ? await rows(`SELECT player, name, metric, delta, at FROM ${T.events} WHERE at >= ?`, [since])
+        : await rows(`SELECT player, name, metric, delta, at FROM ${T.events}`);
+      return r.map((x) => ({ player: String(x.player), name: x.name ?? undefined, metric: String(x.metric), delta: Number(x.delta), at: Number(x.at) }));
+    },
+    async setGauge(player, metric, value, name, at) {
+      await run(
+        `INSERT INTO ${T.gauges} (player, metric, value, name, at) VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT (player, metric) DO UPDATE SET value = excluded.value, name = COALESCE(excluded.name, ${T.gauges}.name), at = excluded.at`,
+        [player, metric, value, name ?? null, at],
+      );
+    },
+    async gauges() {
+      const out = {};
+      for (const x of await rows(`SELECT player, metric, value, name, at FROM ${T.gauges}`)) {
+        const p = String(x.player);
+        const row = out[p] ?? (out[p] = { name: undefined, at: 0, values: {} });
+        row.values[String(x.metric)] = Number(x.value);
+        const at = Number(x.at);
+        if (at >= row.at) {
+          row.at = at;
+          if (x.name) row.name = String(x.name);
+        }
+      }
+      return out;
+    },
+    async awardBadge(player, badge, at) {
+      const before = await rows(`SELECT 1 AS one FROM ${T.badges} WHERE player = ? AND badge = ?`, [player, badge]);
+      if (before.length) return false;
+      await run(`INSERT INTO ${T.badges} (player, badge, at) VALUES (?, ?, ?) ON CONFLICT (player, badge) DO NOTHING`, [player, badge, at]);
+      return true;
+    },
+    async badges() {
+      const out = {};
+      for (const x of await rows(`SELECT player, badge, at FROM ${T.badges}`)) {
+        const p = String(x.player);
+        (out[p] ?? (out[p] = {}))[String(x.badge)] = Number(x.at);
+      }
+      return out;
+    },
+  };
+}