cursedbelt 0.0.0

package/README.md

@@ -0,0 +1,80 @@
+# cursedbelt
+
+A tight, standardized Bun + React web framework. Apps consume it so they can focus on business logic while cursedbelt owns the core: the UI kit, the app shell, state/data/real-time plumbing, and the server-agnostic cores.
+
+> 📐 **Engineering standards live in [`STANDARDS.md`](./STANDARDS.md)** — the one canonical source of truth, reuse-not-duplicate, the layering + Biome rules, the ctgr/getOnly server invariants, and the integration-flow worktree workflow. **Read it before adding code, and build on the shared primitives instead of recreating them.**
+
+## Why
+Apps kept re-fixing the same cross-cutting bug on page after page (keyboard occlusion, floating-element placement, modal behavior). cursedbelt makes those primitives **impossible to build wrong** — most notably the keyboard-safe `ScrollArea`, the one shell `AppShell`, and a token-driven theme.
+
+## Foundation choices
+- UI: shadcn/ui (vendored Radix) + Tailwind v4, themed off **one accent token**.
+- Floating: `@floating-ui/react`. Forms: react-hook-form + zod. Tables: TanStack Table.
+- Server: **Hono on Bun** (one framework). ctgr GET-tunnel kept as a primitive. Auth: jose. DB: SQLite (bun:sqlite) + a migration runner + Kysely-typed plumbing.
+- Bespoke (no library exists): the keyboard-safe `ScrollArea`, the `AppShell`, and the field/layout engines.
+
+## Consuming (live local DX)
+
+cursedbelt is consumed as **source** in dev (the `source` export condition → `./src`,
+never a built `dist`), so a one-line change here shows up in apps with no rebuild.
+
+**One-time machine setup** — register the global link once, in this repo:
+```bash
+cd cursedbelt && bun link        # global cursedbelt link → this repo dir
+```
+
+Then each app declares the link dep + dedupe + the `source` condition:
+```jsonc
+// ca/ru package.json (root)
+"cursedbelt": "link:cursedbelt"   // bun's link: protocol resolves the global link by
+                                   // NAME — `link:../cursedbelt` / `link:..` do NOT work
+```
+```ts
+// ui/vite.config.ts — resolve cursedbelt source + force single dep copies
+resolve: {
+  conditions: ['source', 'import', 'module', 'browser', 'default'],
+  dedupe: ['react', 'react-dom', 'react/jsx-runtime', '@tanstack/react-query', 'zustand', 'lucide-react'],
+}
+```
+```jsonc
+// ui/tsconfig.json — make tsc honor the same `source` condition (no per-subpath paths)
+"compilerOptions": { "customConditions": ["source"] }
+```
+Import it:
+```ts
+import { AppShell, ScrollArea, Button } from 'cursedbelt/react';
+```
+```css
+@import 'tailwindcss';
+@import 'cwip/styles.css';
+@import 'cursedbelt/styles.css';
+@import 'cursedbelt/theme.css';
+:root { --accent: #059669; --accent-hover: #047857; } /* ca = emerald; ru = violet */
+```
+
+`react`/`react-dom`/`@tanstack/react-query` are **peerDependencies** here (never bundled),
+so the app's single copy wins — required, or two Reacts white-screen the app.
+
+## Developing cursedbelt
+
+```bash
+bun run demo        # kitchen-sink app (the visual contract) at http://localhost:4318
+bun run done        # gate: typecheck + lint + unit tests
+bun run e2e         # Playwright smoke against the demo (chromium)
+bun run build       # emit dist/ (.js + .d.ts) — only for `bun publish`; apps never use it
+```
+
+- **Tests** are Bun `*.spec.ts` files colocated in `src/` (`bun test src`).
+- **The demo** (`demo/`) is standalone + dev-only — it consumes cursedbelt exactly like
+  the apps (`link:cursedbelt`), renders every primitive in every state, light + dark, and
+  doubles as the Playwright fixture. Each new primitive task adds a `demo/sections/*` file.
+
+## Vendoring shadcn/Radix components
+
+The Radix primitives ship as runtime `dependencies`; component source is **vendored** into
+`src/react/components/` (we own it). To add one: `npx shadcn@latest add <component>` (or copy
+the source), then — because consumers bundle our **source** — rewrite shadcn's `@/` aliases to
+**relative** imports (`@/lib/utils` → `../lib/cn`, the `cn()` helper). No `@/` alias exists here
+on purpose: a `@/` import would resolve against the *consuming app's* `src`, not ours.
+
+> Status: P0 (foundation) — DX + demo + harness landed; primitives rebuilt task-by-task.

package/dist/client/convertRequest.d.ts

@@ -0,0 +1,15 @@
+/** One converted request ready for `fetch`: the GET-twin path + the GET init. */
+export interface CtgrFetchRequest {
+    /** `/ctgr<XX><path>?<params>` — a path; the caller prepends any API prefix. */
+    url: string;
+    init: RequestInit;
+}
+/**
+ * Convert one request for ctgr transport. Returns the chunked GET requests to send in
+ * order (usually one); when ctgr mode is off, or it is already a body-less GET, the
+ * original request passes through unchanged as a single entry.
+ */
+export declare function convertIfOnlyGETRequests(url: string, init?: RequestInit, formData?: FormData): Promise<{
+    requests: CtgrFetchRequest[];
+}>;
+//# sourceMappingURL=convertRequest.d.ts.map

package/dist/client/convertRequest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convertRequest.d.ts","sourceRoot":"","sources":["../../src/client/convertRequest.ts"],"names":[],"mappings":"AAiBA,iFAAiF;AACjF,MAAM,WAAW,gBAAgB;IAC/B,+EAA+E;IAC/E,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,WAAW,CAAC;CACnB;AASD;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,WAA+B,EACrC,QAAQ,CAAC,EAAE,QAAQ,GAClB,OAAO,CAAC;IAAE,QAAQ,EAAE,gBAAgB,EAAE,CAAA;CAAE,CAAC,CAgB3C"}

package/dist/client/convertRequest.js

@@ -0,0 +1,94 @@
+/*
+ * v1 client request converter — the browser half of the ctgr GET-tunnel. When ctgr
+ * mode is on, a mutating request is rewritten into one or more `/ctgr<XX>` GET twins
+ * via the isomorphic codec (gzip + single base64url + integrity); a plain GET passes
+ * through untouched. FormData uploads are serialized into the JSON body's `__files`
+ * shape (the server reconstructs `req.files` from it) — identical to the legacy shape,
+ * just fed through the optimized codec.
+ */
+import { encodeRequest, METHOD_TO_ABBREV, toBase64, } from '../ctgr';
+import { isCtgrModeOn } from './ctgrConfig';
+// 10 MB per-file cap for ctgr (GET-only) mode. base64 + URL transport inflates each
+// file and needs many sequential GETs per MB; beyond this the upload hangs/OOMs on
+// mobile. Large files require a real (non-`/f`) login.
+const CTGR_MAX_FILE_BYTES = 10 * 1024 * 1024;
+const SAFE_METHODS = new Set(['GET', 'HEAD']);
+/**
+ * Convert one request for ctgr transport. Returns the chunked GET requests to send in
+ * order (usually one); when ctgr mode is off, or it is already a body-less GET, the
+ * original request passes through unchanged as a single entry.
+ */
+export async function convertIfOnlyGETRequests(url, init = { method: 'GET' }, formData) {
+    const method = (init.method ?? (formData ? 'POST' : 'GET')).toUpperCase();
+    if (!isCtgrModeOn() || (SAFE_METHODS.has(method) && !formData)) {
+        return { requests: [{ url, init }] };
+    }
+    const upper = method;
+    if (!METHOD_TO_ABBREV[upper]) {
+        throw new Error(`ctgr: "${method}" is not a tunnelable method`);
+    }
+    const body = formData ? await formDataToBody(formData) : bodyFromInit(init.body);
+    const getInit = toGetInit(init);
+    const { chunks } = await encodeRequest(upper, url, body);
+    return { requests: chunks.map((chunk) => ({ url: chunk.url, init: getInit })) };
+}
+/** Turn a FormData upload into the `__files` JSON body shape the GET path carries. */
+async function formDataToBody(formData) {
+    const files = [];
+    const fields = {};
+    for (const [key, value] of formData.entries()) {
+        if (typeof value === 'object' && value !== null && 'arrayBuffer' in value) {
+            const file = value;
+            if (file.size > CTGR_MAX_FILE_BYTES) {
+                throw new Error(`"${file.name}" (${Math.round(file.size / 1024 / 1024)} MB) is too large to upload in ` +
+                    `GET-only mode — log in via /login (not /f) to upload large files`);
+            }
+            files.push({
+                field: key,
+                name: file.name,
+                type: file.type,
+                dataBase64: toBase64(new Uint8Array(await file.arrayBuffer())),
+            });
+        }
+        else {
+            fields[key] = String(value);
+        }
+    }
+    return { __files: files, ...fields };
+}
+/** The request body as a JS value: a JSON string is parsed; anything else passes through. */
+function bodyFromInit(body) {
+    if (typeof body !== 'string')
+        return body ?? undefined;
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return body;
+    }
+}
+/** A GET copy of the init: no body, and the now-meaningless content-type dropped. */
+function toGetInit(init) {
+    const next = { ...init, method: 'GET', headers: stripContentType(init.headers) };
+    delete next.body;
+    return next;
+}
+function stripContentType(headers) {
+    if (!headers)
+        return headers;
+    if (headers instanceof Headers) {
+        const next = new Headers(headers);
+        next.delete('content-type');
+        return next;
+    }
+    if (Array.isArray(headers)) {
+        return headers.filter(([key]) => key.toLowerCase() !== 'content-type');
+    }
+    const next = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() !== 'content-type')
+            next[key] = value;
+    }
+    return next;
+}
+//# sourceMappingURL=convertRequest.js.map

package/dist/client/convertRequest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"convertRequest.js","sourceRoot":"","sources":["../../src/client/convertRequest.ts"],"names":[],"mappings":"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"}

package/dist/client/ctgrConfig.d.ts

@@ -0,0 +1,3 @@
+export declare const isCtgrModeOn: () => boolean;
+export declare const setCtgrMode: (on: boolean) => void;
+//# sourceMappingURL=ctgrConfig.d.ts.map

package/dist/client/ctgrConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ctgrConfig.d.ts","sourceRoot":"","sources":["../../src/client/ctgrConfig.ts"],"names":[],"mappings":"AAaA,eAAO,MAAM,YAAY,QAAO,OAM/B,CAAC;AAEF,eAAO,MAAM,WAAW,GAAI,IAAI,OAAO,KAAG,IAOzC,CAAC"}

package/dist/client/ctgrConfig.js

@@ -0,0 +1,32 @@
+/*
+ * Single source of truth for "GET-conversion (ctgr) mode". When on, every server
+ * request is rewritten to a GET (see `convertIfOnlyGETRequests`) so the app works
+ * where non-GET methods are blocked. Both the converter and the safety guard read
+ * this, so they can never disagree.
+ *
+ * The mode is per-login-method, persisted in localStorage so it survives reloads:
+ *   • the obfuscated `/f` login forces it ON (that environment is GET-only).
+ *   • the standard `/login` keeps it OFF, so normal POST/PUT/PATCH/DELETE are used.
+ * Default is OFF.
+ */
+const CTGR_KEY = 'ctgr';
+export const isCtgrModeOn = () => {
+    try {
+        return localStorage.getItem(CTGR_KEY) === 'on';
+    }
+    catch {
+        return false;
+    }
+};
+export const setCtgrMode = (on) => {
+    try {
+        if (on)
+            localStorage.setItem(CTGR_KEY, 'on');
+        else
+            localStorage.removeItem(CTGR_KEY);
+    }
+    catch {
+        // localStorage unavailable (private mode / SSR) — nothing to persist.
+    }
+};
+//# sourceMappingURL=ctgrConfig.js.map

package/dist/client/ctgrConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ctgrConfig.js","sourceRoot":"","sources":["../../src/client/ctgrConfig.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,QAAQ,GAAG,MAAM,CAAC;AAExB,MAAM,CAAC,MAAM,YAAY,GAAG,GAAY,EAAE;IACxC,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,EAAW,EAAQ,EAAE;IAC/C,IAAI,CAAC;QACH,IAAI,EAAE;YAAE,YAAY,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;;YACxC,YAAY,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,sEAAsE;IACxE,CAAC;AACH,CAAC,CAAC"}

package/dist/client/ctgrGuard.d.ts

@@ -0,0 +1,2 @@
+export declare const installCtgrGuard: () => void;
+//# sourceMappingURL=ctgrGuard.d.ts.map

package/dist/client/ctgrGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ctgrGuard.d.ts","sourceRoot":"","sources":["../../src/client/ctgrGuard.ts"],"names":[],"mappings":"AA2CA,eAAO,MAAM,gBAAgB,QAAO,IA+BnC,CAAC"}

package/dist/client/ctgrGuard.js

@@ -0,0 +1,71 @@
+/*
+ * Safety net for GET-conversion mode. Even though every server request is supposed to
+ * be rewritten to a GET (`convertIfOnlyGETRequests`), this guard sits at the actual
+ * network boundary and HARD-BLOCKS any non-GET request to our own origin when the
+ * mode is on — so a code path that forgot to run through the converter can never
+ * sneak a real POST/PUT/DELETE/PATCH onto the wire. Catches both `fetch` and
+ * `XMLHttpRequest`. This is a protection guarantee: it must never weaken.
+ */
+import { isCtgrModeOn } from './ctgrConfig';
+// Methods that never mutate and are always safe to allow.
+const SAFE_METHODS = new Set(['GET', 'HEAD']);
+const urlOf = (input) => {
+    if (typeof input === 'string')
+        return input;
+    if (input instanceof URL)
+        return input.href;
+    if (input instanceof Request)
+        return input.url;
+    return String(input);
+};
+// Only guard requests to our own server (relative paths or same-origin absolute
+// URLs); leave genuinely cross-origin requests alone.
+const isSameOrigin = (rawUrl) => {
+    if (rawUrl.startsWith('/'))
+        return true;
+    try {
+        return new URL(rawUrl, window.location.href).origin === window.location.origin;
+    }
+    catch {
+        return false;
+    }
+};
+const block = (method, url, via) => {
+    const message = `[ctgr guard] Blocked ${method} ${url} (${via}). GET-conversion mode is on, so every ` +
+        `server request must be a GET. This request bypassed convertIfOnlyGETRequests — fix the ` +
+        `call site (use authRequest/fetchAndParse) instead of issuing a raw ${method}.`;
+    // Loud, with a stack so the offending call site is easy to find.
+    console.error(message, new Error('ctgr-guard origin'));
+    return new Error(message);
+};
+let installed = false;
+export const installCtgrGuard = () => {
+    if (installed || typeof window === 'undefined')
+        return;
+    installed = true;
+    // ── fetch ──────────────────────────────────────────────────────────────────
+    if (typeof window.fetch === 'function') {
+        const originalFetch = window.fetch.bind(window);
+        const guardedFetch = (input, init) => {
+            const method = (init?.method ?? (input instanceof Request ? input.method : 'GET')).toUpperCase();
+            const url = urlOf(input);
+            if (isCtgrModeOn() && !SAFE_METHODS.has(method) && isSameOrigin(url)) {
+                return Promise.reject(block(method, url, 'fetch'));
+            }
+            return originalFetch(input, init);
+        };
+        window.fetch = guardedFetch;
+    }
+    // ── XMLHttpRequest ───────────────────────────────────────────────────────────
+    if (typeof XMLHttpRequest !== 'undefined') {
+        const originalOpen = XMLHttpRequest.prototype.open;
+        XMLHttpRequest.prototype.open = function open(method, url, ...rest) {
+            const upper = String(method).toUpperCase();
+            if (isCtgrModeOn() && !SAFE_METHODS.has(upper) && isSameOrigin(String(url))) {
+                throw block(upper, String(url), 'XMLHttpRequest');
+            }
+            return originalOpen.call(this, method, url, ...rest);
+        };
+    }
+};
+//# sourceMappingURL=ctgrGuard.js.map

package/dist/client/ctgrGuard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ctgrGuard.js","sourceRoot":"","sources":["../../src/client/ctgrGuard.ts"],"names":[],"mappings":"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"}

package/dist/client/index.d.ts

@@ -0,0 +1,5 @@
+export { type CtgrFetchRequest, convertIfOnlyGETRequests } from './convertRequest';
+export { isCtgrModeOn, setCtgrMode } from './ctgrConfig';
+export { installCtgrGuard } from './ctgrGuard';
+export { buildChannelSocketUrl, type CreateChannelSocketOptions, createChannelSocket, parseWsMessage, type ReconnectingWebSocket, sendWsMessage, type WsLocation, type WsMessage, } from './ws';
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,KAAK,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AACnF,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EACL,qBAAqB,EACrB,KAAK,0BAA0B,EAC/B,mBAAmB,EACnB,cAAc,EACd,KAAK,qBAAqB,EAC1B,aAAa,EACb,KAAK,UAAU,EACf,KAAK,SAAS,GACf,MAAM,MAAM,CAAC"}

package/dist/client/index.js

@@ -0,0 +1,12 @@
+/*
+ * cursedbelt/client — the browser half of the cursedbelt server toolkit:
+ *  • the ctgr GET-tunnel (localStorage mode flag, v1 request converter, hard-block guard),
+ *    pairing with `cursedbelt/server` (`unGETify`) + `cursedbelt/ctgr` (the codec);
+ *  • the WS hub's auto-reconnecting channel socket (partysocket), pairing with
+ *    `cursedbelt/server`'s `createWsHub`.
+ */
+export { convertIfOnlyGETRequests } from './convertRequest';
+export { isCtgrModeOn, setCtgrMode } from './ctgrConfig';
+export { installCtgrGuard } from './ctgrGuard';
+export { buildChannelSocketUrl, createChannelSocket, parseWsMessage, sendWsMessage, } from './ws';
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAyB,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AACnF,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EACL,qBAAqB,EAErB,mBAAmB,EACnB,cAAc,EAEd,aAAa,GAGd,MAAM,MAAM,CAAC"}

package/dist/client/ws.d.ts

@@ -0,0 +1,37 @@
+import ReconnectingWebSocket, { type Options as ReconnectingOptions } from 'partysocket/ws';
+/** The minimal shape of `window.location` {@link buildChannelSocketUrl} needs. Injectable
+ * so the URL builder is pure + testable (no `window` at module scope). */
+export interface WsLocation {
+    protocol: string;
+    host: string;
+}
+/** The hub's wire envelope, mirroring `cursedbelt/server`'s `WsMessage`. Re-declared here
+ * (not imported) because the server module is Bun-typed and must not leak into the browser
+ * surface. */
+export interface WsMessage<T = unknown> {
+    event: string;
+    data: T;
+}
+export interface CreateChannelSocketOptions {
+    /** Override the page location (tests / SSR). Defaults to `window.location`. */
+    location?: WsLocation;
+    /** Passed through to partysocket's `ReconnectingWebSocket` (backoff tuning, `startClosed`, …). */
+    socketOptions?: ReconnectingOptions;
+}
+/** Build the `ws(s)://host/ws/<channel>[?room=<roomId>]` URL the hub upgrades. `wss` is
+ * chosen iff the page is `https`. Pure — pass `loc` in tests. */
+export declare function buildChannelSocketUrl(channel: string, roomId: string | undefined, loc: WsLocation): string;
+/**
+ * Open an auto-reconnecting socket to the hub's `channel` (optionally scoped to `roomId`).
+ * The returned socket is a standard `WebSocket`-shaped object (`send`/`close`/`addEventListener`)
+ * that reconnects on drop with exponential backoff. Pair sends with {@link sendWsMessage} and
+ * reads with {@link parseWsMessage}.
+ */
+export declare function createChannelSocket(channel: string, roomId?: string, opts?: CreateChannelSocketOptions): ReconnectingWebSocket;
+/** Send a `{ event, data }` frame the hub understands. */
+export declare function sendWsMessage(socket: Pick<ReconnectingWebSocket, 'send'>, event: string, data: unknown): void;
+/** Parse an inbound frame into a `{ event, data }` envelope, or `null` if it isn't valid
+ * JSON of that shape (so a stray non-envelope frame can't throw in a message handler). */
+export declare function parseWsMessage<T = unknown>(raw: unknown): WsMessage<T> | null;
+export type { ReconnectingWebSocket };
+//# sourceMappingURL=ws.d.ts.map

package/dist/client/ws.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws.d.ts","sourceRoot":"","sources":["../../src/client/ws.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,EAAE,EAAE,KAAK,OAAO,IAAI,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAe5F;0EAC0E;AAC1E,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;cAEc;AACd,MAAM,WAAW,SAAS,CAAC,CAAC,GAAG,OAAO;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,CAAC,CAAC;CACT;AAED,MAAM,WAAW,0BAA0B;IACzC,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB,kGAAkG;IAClG,aAAa,CAAC,EAAE,mBAAmB,CAAC;CACrC;AAED;iEACiE;AACjE,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,GAAG,EAAE,UAAU,GACd,MAAM,CAIR;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,EACf,IAAI,GAAE,0BAA+B,GACpC,qBAAqB,CAOvB;AAED,0DAA0D;AAC1D,wBAAgB,aAAa,CAC3B,MAAM,EAAE,IAAI,CAAC,qBAAqB,EAAE,MAAM,CAAC,EAC3C,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,OAAO,GACZ,IAAI,CAEN;AAED;0FAC0F;AAC1F,wBAAgB,cAAc,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,OAAO,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,CAiB7E;AAED,YAAY,EAAE,qBAAqB,EAAE,CAAC"}

package/dist/client/ws.js

@@ -0,0 +1,43 @@
+import ReconnectingWebSocket, {} from 'partysocket/ws';
+/** Build the `ws(s)://host/ws/<channel>[?room=<roomId>]` URL the hub upgrades. `wss` is
+ * chosen iff the page is `https`. Pure — pass `loc` in tests. */
+export function buildChannelSocketUrl(channel, roomId, loc) {
+    const scheme = loc.protocol === 'https:' ? 'wss' : 'ws';
+    const base = `${scheme}://${loc.host}/ws/${encodeURIComponent(channel)}`;
+    return roomId ? `${base}?room=${encodeURIComponent(roomId)}` : base;
+}
+/**
+ * Open an auto-reconnecting socket to the hub's `channel` (optionally scoped to `roomId`).
+ * The returned socket is a standard `WebSocket`-shaped object (`send`/`close`/`addEventListener`)
+ * that reconnects on drop with exponential backoff. Pair sends with {@link sendWsMessage} and
+ * reads with {@link parseWsMessage}.
+ */
+export function createChannelSocket(channel, roomId, opts = {}) {
+    const loc = opts.location ?? window.location;
+    return new ReconnectingWebSocket(buildChannelSocketUrl(channel, roomId, loc), undefined, opts.socketOptions);
+}
+/** Send a `{ event, data }` frame the hub understands. */
+export function sendWsMessage(socket, event, data) {
+    socket.send(JSON.stringify({ event, data }));
+}
+/** Parse an inbound frame into a `{ event, data }` envelope, or `null` if it isn't valid
+ * JSON of that shape (so a stray non-envelope frame can't throw in a message handler). */
+export function parseWsMessage(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (parsed &&
+        typeof parsed === 'object' &&
+        'event' in parsed &&
+        typeof parsed.event === 'string') {
+        return parsed;
+    }
+    return null;
+}
+//# sourceMappingURL=ws.js.map

package/dist/client/ws.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws.js","sourceRoot":"","sources":["../../src/client/ws.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,EAAE,EAAuC,MAAM,gBAAgB,CAAC;AAqC5F;iEACiE;AACjE,MAAM,UAAU,qBAAqB,CACnC,OAAe,EACf,MAA0B,EAC1B,GAAe;IAEf,MAAM,MAAM,GAAG,GAAG,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;IACxD,MAAM,IAAI,GAAG,GAAG,MAAM,MAAM,GAAG,CAAC,IAAI,OAAO,kBAAkB,CAAC,OAAO,CAAC,EAAE,CAAC;IACzE,OAAO,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,SAAS,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACtE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAAe,EACf,MAAe,EACf,OAAmC,EAAE;IAErC,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC;IAC7C,OAAO,IAAI,qBAAqB,CAC9B,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAC3C,SAAS,EACT,IAAI,CAAC,aAAa,CACnB,CAAC;AACJ,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,aAAa,CAC3B,MAA2C,EAC3C,KAAa,EACb,IAAa;IAEb,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED;0FAC0F;AAC1F,MAAM,UAAU,cAAc,CAAc,GAAY;IACtD,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACzC,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IACE,MAAM;QACN,OAAO,MAAM,KAAK,QAAQ;QAC1B,OAAO,IAAI,MAAM;QACjB,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,EAChC,CAAC;QACD,OAAO,MAAsB,CAAC;IAChC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/core/color.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Pick the readable foreground keyword (`'black'` or `'white'`) for text on a solid
+ * hex background, using the WCAG relative-luminance formula (sRGB gamma-expanded).
+ *
+ * Returns CSS color keywords (not hex) so a call site can drop the result straight
+ * into a `color:` style. Accepts 3- or 6-digit hex, with or without a leading `#`;
+ * an unparseable input falls back to `'white'` (legible on most accent colors).
+ *
+ * This is the canonical contrast primitive. The nav toolkit's `readableTextOn`
+ * (`react/nav/colors.ts`) and the spreadsheet theme's `contrastOn` deliberately
+ * return tuned near-black/near-white *hex* with their own thresholds for those
+ * surfaces; this returns pure keywords on the standard WCAG threshold.
+ */
+export declare function contrastText(hex: string): 'black' | 'white';
+//# sourceMappingURL=color.d.ts.map

package/dist/core/color.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"color.d.ts","sourceRoot":"","sources":["../../src/core/color.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,CAkB3D"}

package/dist/core/color.js

@@ -0,0 +1,33 @@
+// Framework-agnostic color helpers. Pure functions over hex strings — no React,
+// no DOM — so they're usable in the apps, on the server, and in tests.
+/**
+ * Pick the readable foreground keyword (`'black'` or `'white'`) for text on a solid
+ * hex background, using the WCAG relative-luminance formula (sRGB gamma-expanded).
+ *
+ * Returns CSS color keywords (not hex) so a call site can drop the result straight
+ * into a `color:` style. Accepts 3- or 6-digit hex, with or without a leading `#`;
+ * an unparseable input falls back to `'white'` (legible on most accent colors).
+ *
+ * This is the canonical contrast primitive. The nav toolkit's `readableTextOn`
+ * (`react/nav/colors.ts`) and the spreadsheet theme's `contrastOn` deliberately
+ * return tuned near-black/near-white *hex* with their own thresholds for those
+ * surfaces; this returns pure keywords on the standard WCAG threshold.
+ */
+export function contrastText(hex) {
+    const c = hex.replace('#', '').trim();
+    const full = c.length === 3
+        ? c
+            .split('')
+            .map((ch) => ch + ch)
+            .join('')
+        : c;
+    if (!/^[0-9a-f]{6}$/i.test(full))
+        return 'white';
+    const r = Number.parseInt(full.slice(0, 2), 16) / 255;
+    const g = Number.parseInt(full.slice(2, 4), 16) / 255;
+    const b = Number.parseInt(full.slice(4, 6), 16) / 255;
+    const [rs, gs, bs] = [r, g, b].map((v) => v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4);
+    const luminance = 0.2126 * rs + 0.7152 * gs + 0.0722 * bs;
+    return luminance > 0.179 ? 'black' : 'white';
+}
+//# sourceMappingURL=color.js.map

package/dist/core/color.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"color.js","sourceRoot":"","sources":["../../src/core/color.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,uEAAuE;AAEvE;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,MAAM,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACtC,MAAM,IAAI,GACR,CAAC,CAAC,MAAM,KAAK,CAAC;QACZ,CAAC,CAAC,CAAC;aACE,KAAK,CAAC,EAAE,CAAC;aACT,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC;aACpB,IAAI,CAAC,EAAE,CAAC;QACb,CAAC,CAAC,CAAC,CAAC;IACR,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,OAAO,CAAC;IACjD,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC;IACtD,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC;IACtD,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC;IACtD,MAAM,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CACvC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,KAAK,CAAC,IAAI,GAAG,CACxD,CAAC;IACF,MAAM,SAAS,GAAG,MAAM,GAAG,EAAE,GAAG,MAAM,GAAG,EAAE,GAAG,MAAM,GAAG,EAAE,CAAC;IAC1D,OAAO,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;AAC/C,CAAC"}

package/dist/core/csv.d.ts

@@ -0,0 +1,65 @@
+/**
+ * CSV core — a thin, typed wrapper over PapaParse (the canonical CSV engine:
+ * quoted fields, BOM, streaming, RFC-4180). This is the single CSV parse/serialize
+ * surface for both apps, replacing the hand-rolled per-site parsers. Framework- and
+ * DOM-agnostic for the string path (so it's trivially testable under Bun); the
+ * `File`/streaming paths use browser APIs and degrade gracefully off the browser.
+ *
+ * (Distinct from `data/json`'s `csvToJson`, which is the Format-Lab CSV⇆JSON
+ * *converter* — a different concern. This module is the general parse/serialize API.)
+ */
+import Papa from 'papaparse';
+export interface CsvParseResult<T> {
+    /** Parsed rows — objects when `header: true`, else string arrays cast to `T`. */
+    data: T[];
+    /** Recoverable parse problems (malformed quotes, ragged rows, …). */
+    errors: Papa.ParseError[];
+    /** Delimiter detected, line breaks, truncation, the header row, etc. */
+    meta: Papa.ParseMeta;
+}
+export interface CsvParseOptions {
+    /** Treat the first row as field names → rows become objects keyed by them. */
+    header?: boolean;
+    /** Coerce numeric/boolean-looking cells to real numbers/booleans (default off). */
+    dynamicTyping?: boolean;
+    /** Drop blank lines. `true` skips fully-empty lines; `'greedy'` also skips
+     *  whitespace-only ones. Defaults to `true` (the overwhelmingly common intent). */
+    skipEmptyLines?: boolean | 'greedy';
+    /** Per-cell transform applied before typing (e.g. trim, redact). */
+    transform?: (value: string, field: string | number) => unknown;
+}
+/**
+ * Parse CSV text (synchronous) or a `File` (async). The synchronous string path is
+ * the common case — quoted commas, embedded newlines, and BOM are all handled by
+ * PapaParse. A `File` returns a Promise (browser-only; uses `FileReader`).
+ *
+ *   parseCsv('name,age\n"Smith, Jr.",30', { header: true })
+ *   // → { data: [{ name: 'Smith, Jr.', age: '30' }], errors: [], meta: {…} }
+ */
+export declare function parseCsv<T = Record<string, string>>(input: string, opts?: CsvParseOptions): CsvParseResult<T>;
+export declare function parseCsv<T = Record<string, string>>(input: File, opts?: CsvParseOptions): Promise<CsvParseResult<T>>;
+export interface StreamCsvOptions<T> extends CsvParseOptions {
+    /** Bytes per chunk (default 10 MB). Tunes memory vs. callback frequency. */
+    chunkSize?: number;
+    /** Called once per parsed chunk with that chunk's rows — never accumulates the
+     *  whole file in memory, so multi-GB CSVs stream without blowing the heap. */
+    onChunk: (rows: T[]) => void;
+    onComplete: (meta: Papa.ParseMeta) => void;
+    onError?: (error: Papa.ParseError | Error) => void;
+}
+/**
+ * Stream-parse a large `File` chunk-by-chunk so the UI thread never blocks and the
+ * full dataset never lives in memory at once. Uses a Web Worker when available
+ * (`worker: true`), falling back to main-thread chunking off the browser. Browser-
+ * only (needs `File`); a no-op-with-error elsewhere.
+ */
+export declare function streamCsv<T = Record<string, string>>(input: File, opts: StreamCsvOptions<T>): void;
+export interface ToCsvOptions {
+    /** Emit a header row from the object keys (default true). */
+    header?: boolean;
+    /** Column order / subset (defaults to the union of keys across rows). */
+    columns?: string[];
+}
+/** Serialize rows back to a CSV string (quotes/escapes handled by PapaParse). */
+export declare function toCsv(rows: Record<string, unknown>[], opts?: ToCsvOptions): string;
+//# sourceMappingURL=csv.d.ts.map

package/dist/core/csv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csv.d.ts","sourceRoot":"","sources":["../../src/core/csv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,iFAAiF;IACjF,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,qEAAqE;IACrE,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC;IAC1B,wEAAwE;IACxE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,mFAAmF;IACnF,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;uFACmF;IACnF,cAAc,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IACpC,oEAAoE;IACpE,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,KAAK,OAAO,CAAC;CAChE;AASD;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACjD,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,eAAe,GACrB,cAAc,CAAC,CAAC,CAAC,CAAC;AACrB,wBAAgB,QAAQ,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACjD,KAAK,EAAE,IAAI,EACX,IAAI,CAAC,EAAE,eAAe,GACrB,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;AAkB9B,MAAM,WAAW,gBAAgB,CAAC,CAAC,CAAE,SAAQ,eAAe;IAC1D,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;kFAC8E;IAC9E,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,IAAI,CAAC;IAC7B,UAAU,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,KAAK,IAAI,CAAC;IAC3C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,UAAU,GAAG,KAAK,KAAK,IAAI,CAAC;CACpD;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAClD,KAAK,EAAE,IAAI,EACX,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC,GACxB,IAAI,CAUN;AAED,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,iFAAiF;AACjF,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAAE,IAAI,GAAE,YAAiB,GAAG,MAAM,CAKtF"}