cursedbelt 5.0.1 → 5.2.0

package/dist/react/engagement/beacon.d.ts

@@ -0,0 +1,38 @@
+import { type ReportPlaceOptions } from "./beaconClient.js";
+/**
+ * Report `place` whenever it changes.
+ *
+ * `place` should be the app's own route-manifest id — the same string the
+ * server resolves against. Pass `null` while the route is unresolved (a lazy
+ * view still loading, a signed-out shell) rather than a placeholder: a
+ * placeholder becomes a real row in the console.
+ */
+export declare function useEngagementBeacon(place: string | null, options?: ReportPlaceOptions): void;
+/**
+ * Report wherever the browser IS, and keep reporting as it moves.
+ *
+ * This is the form every app should use, and it is why adoption is one line
+ * rather than a per-app mapping: the client sends its LOCATION and the server
+ * resolves it against that app's own route manifest (`policy.ts:resolvePlace`).
+ * A `route.view → place id` table written in twelve app shells would be twelve
+ * places for the names to drift, and a drifted name reads on the board as a
+ * page nobody opens — a wrong answer, not a gap.
+ *
+ * Listens to `hashchange` and `popstate`, which between them cover both kinds of
+ * router — hash-routed apps like this one, and a pushState app. `reportPlace`
+ * de-duplicates, so a re-render costs nothing.
+ */
+export declare function useLocationBeacon(options?: ReportPlaceOptions): void;
+/**
+ * The location beacon as an element, for a shell that mounts declaratively.
+ *
+ * Deliberately takes no `place` prop. Offering both would mean two callers of
+ * one module-level de-duplication memory, and an app that passed a place would
+ * silently suppress the location half or vice versa — use
+ * {@link useEngagementBeacon} directly when an app really does know its own
+ * place ids.
+ */
+export declare function EngagementBeacon(props: {
+    basePath?: string;
+}): null;
+//# sourceMappingURL=beacon.d.ts.map

package/dist/react/engagement/beacon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"beacon.d.ts","sourceRoot":"","sources":["../../../src/react/engagement/beacon.tsx"],"names":[],"mappings":"AAQA,OAAO,EAAE,KAAK,kBAAkB,EAAoC,MAAM,mBAAmB,CAAC;AAE9F;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,GAAE,kBAAuB,GAAG,IAAI,CAQhG;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,kBAAuB,GAAG,IAAI,CAMxE;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAGnE"}

package/dist/react/engagement/beacon.js

@@ -0,0 +1,62 @@
+/**
+ * The React adapter over `beaconClient.ts` — one hook, one component.
+ *
+ * Separate file from the plain-JS half so an app with no React (or a test with
+ * no DOM) can import `reportPlace` without pulling React in, and so the app's
+ * own router stays the thing that decides what "a place" is.
+ */
+import { useEffect } from "react";
+import { reportPlace, startLocationBeacon } from "./beaconClient.js";
+/**
+ * Report `place` whenever it changes.
+ *
+ * `place` should be the app's own route-manifest id — the same string the
+ * server resolves against. Pass `null` while the route is unresolved (a lazy
+ * view still loading, a signed-out shell) rather than a placeholder: a
+ * placeholder becomes a real row in the console.
+ */
+export function useEngagementBeacon(place, options = {}) {
+    const basePath = options.basePath;
+    useEffect(() => {
+        if (!place)
+            return;
+        // Fire and forget; `reportPlace` never rejects. Not awaited on purpose —
+        // a route change must not wait on telemetry.
+        void reportPlace(place, basePath ? { basePath } : {});
+    }, [place, basePath]);
+}
+/**
+ * Report wherever the browser IS, and keep reporting as it moves.
+ *
+ * This is the form every app should use, and it is why adoption is one line
+ * rather than a per-app mapping: the client sends its LOCATION and the server
+ * resolves it against that app's own route manifest (`policy.ts:resolvePlace`).
+ * A `route.view → place id` table written in twelve app shells would be twelve
+ * places for the names to drift, and a drifted name reads on the board as a
+ * page nobody opens — a wrong answer, not a gap.
+ *
+ * Listens to `hashchange` and `popstate`, which between them cover both kinds of
+ * router — hash-routed apps like this one, and a pushState app. `reportPlace`
+ * de-duplicates, so a re-render costs nothing.
+ */
+export function useLocationBeacon(options = {}) {
+    const basePath = options.basePath;
+    // Delegates to the plain-JS starter so there is ONE implementation of the
+    // listener set. Most apps call `startLocationBeacon()` from `main.tsx`
+    // instead; this exists for a shell that would rather own the lifetime.
+    useEffect(() => startLocationBeacon(basePath ? { basePath } : {}), [basePath]);
+}
+/**
+ * The location beacon as an element, for a shell that mounts declaratively.
+ *
+ * Deliberately takes no `place` prop. Offering both would mean two callers of
+ * one module-level de-duplication memory, and an app that passed a place would
+ * silently suppress the location half or vice versa — use
+ * {@link useEngagementBeacon} directly when an app really does know its own
+ * place ids.
+ */
+export function EngagementBeacon(props) {
+    useLocationBeacon(props.basePath ? { basePath: props.basePath } : {});
+    return null;
+}
+//# sourceMappingURL=beacon.js.map

package/dist/react/engagement/beacon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"beacon.js","sourceRoot":"","sources":["../../../src/react/engagement/beacon.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAClC,OAAO,EAA2B,WAAW,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE9F;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAoB,EAAE,UAA8B,EAAE;IACzF,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IAClC,SAAS,CAAC,GAAG,EAAE;QACd,IAAI,CAAC,KAAK;YAAE,OAAO;QACnB,yEAAyE;QACzE,6CAA6C;QAC7C,KAAK,WAAW,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACvD,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC;AACvB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAA8B,EAAE;IACjE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IAClC,0EAA0E;IAC1E,uEAAuE;IACvE,uEAAuE;IACvE,SAAS,CAAC,GAAG,EAAE,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;AAChF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAA4B;IAC5D,iBAAiB,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACtE,OAAO,IAAI,CAAC;AACb,CAAC"}

package/dist/react/engagement/beaconClient.d.ts

@@ -0,0 +1,119 @@
+/**
+ * `cursedbelt/react/engagement-beacon` — the engagement beacon's plain-JS half (no React). Lifted
+ * 2026-09-23 (cursedbelt 5.2.0, task 098-280's browser half) from `src/kit/engagement/beacon.client.ts`,
+ * identical in collections, family, music and roms (auth's differed only in a comment). The
+ * server half is `cursedbelt-server/engagement`.
+ *
+ * The browser half — report which PLACE the user is on, once per arrival.
+ *
+ * ── Why an explicit beacon and not the request log ──────────────────────────
+ * Most satellites are SPA-routed: moving from Notes' Files page to its Ask page
+ * fires zero navigations and, on a warm cache, zero HTTP requests. So the
+ * request metrics already in `metrics/` can tell you an app is used and cannot
+ * tell you which of its pages are — which is exactly the question the owner
+ * asked ("notes is used but its slideshow is not"). One small event, sent by
+ * the router, is the only thing that can answer it.
+ *
+ * ── It is ONE implementation, adopted; never per-app ────────────────────────
+ * Eleven hand-rolled beacons would be eleven different place vocabularies, and
+ * the console would be comparing strings that mean different things. Apps call
+ * `reportPlace` (or mount `useEngagementBeacon`) and send an id from their own
+ * route manifest; the server resolves it against that same manifest.
+ *
+ * ── What it does NOT send ───────────────────────────────────────────────────
+ * No path, no query, no title, no referrer, no identifiers of any kind — just
+ * `{ place }`. The account comes from the session cookie the request already
+ * carries, server-side. There is nothing in the payload that could carry a note
+ * id, a ROM title or a search string, which is the property that makes this
+ * safe to run inside private apps at all. See `policy.ts`.
+ *
+ * ── Failure is silence ──────────────────────────────────────────────────────
+ * Every call is fire-and-forget and swallows its error. Telemetry that can
+ * surface an error toast, block a route change, or reject an unhandled promise
+ * is telemetry that makes the app worse than having none.
+ *
+ * 🔴 …and "silence" includes the BROWSER's console, which is why the beacon
+ * asks whether there is a session before it reports (`SESSION_PATH` below).
+ * Swallowing the rejection in JS is not enough: a `fetch` that comes back 401
+ * leaves the browser's own *"Failed to load resource: the server responded with
+ * a status of 401"* in the console no matter what the caller does with the
+ * promise. Measured 2026-08-14 against live prod — `music` and `learn` both
+ * failed their signed-out route-health check on exactly this, with a correctly
+ * rendered sign-in card on screen and nothing else wrong. `apps/roms`' App.tsx
+ * already wrote the rule down for the feedback provider: *"an app that logs an
+ * error on its front door is an app nobody can tell apart from a broken one."*
+ * The recorder's 401 is deliberate and stays — `api.ts` mounts it AFTER the
+ * session gate on purpose, because the gate is what puts the user where
+ * `resolveUser` can read them — so the fix belongs on this side.
+ *
+ * It is also the semantically right answer, not merely a quieter one: the
+ * recorder attributes a view to an account, so a signed-out arrival could never
+ * have been recorded. Nothing that used to be counted stops being counted.
+ */
+/** Where the recorder is mounted. Apps that remount it pass `basePath`. */
+export declare const ENGAGEMENT_BASE_PATH = "/api/engagement";
+/**
+ * The public session probe every satellite serves
+ * (`ssoConsumer.server.ts` → `{ authenticated, user?, accountsUrl }`).
+ *
+ * Deliberately NOT session-gated on the server, which is what makes it usable
+ * here: asking it costs one small same-origin GET and can never itself produce
+ * the console line this exists to avoid.
+ */
+export declare const SESSION_PATH = "/api/auth/session";
+export interface ReportPlaceOptions {
+    basePath?: string;
+    /** Injected in tests; defaults to the global. */
+    fetchImpl?: typeof fetch;
+    /** Override the session probe. Apps that remount the consumer elsewhere. */
+    sessionPath?: string;
+    /**
+     * Skip the session probe and report unconditionally.
+     *
+     * For a caller that ALREADY knows there is a session — a React tree below the
+     * authenticated branch, say — where the probe would be a second answer to a
+     * question already asked. Never set it from `main.tsx`, which runs before
+     * anything knows.
+     */
+    assumeSignedIn?: boolean;
+}
+/**
+ * Where the browser is, as a string the server can resolve.
+ *
+ * The hash when there is one (every satellite but roms routes on it), else the
+ * pathname. Never the search string: `normalizePlaceId` strips one anyway, and
+ * not sending it in the first place means user text does not travel at all.
+ */
+export declare function currentLocationPlace(): string;
+/** Reset the de-duplication memory. Tests, and a sign-out. */
+export declare function resetEngagementBeacon(): void;
+/**
+ * Report an arrival at `place`. Returns whether anything was sent.
+ *
+ * Not awaited by callers in practice — the promise is returned so a test can
+ * settle it without a timer.
+ */
+export declare function reportPlace(place: string, options?: ReportPlaceOptions): Promise<boolean>;
+/** Detaches the listeners `startLocationBeacon` installed. */
+export type StopBeacon = () => void;
+/**
+ * Start reporting wherever the browser is, and keep reporting as it moves.
+ *
+ * The form every app adopts, called once from `main.tsx` beside
+ * `initColorScheme()` — one line, no React, and no per-app mapping from a
+ * router's internal view name to a place id. The server resolves the LOCATION
+ * against that app's own `routes.manifest.json` (`policy.ts:resolvePlace`),
+ * which is the list the app already maintains and already gates on.
+ *
+ * `hashchange` and `popstate` between them cover both kinds of router, which is
+ * why BOTH are listened for when `collections` — hash-routed — only needs the
+ * first. The census that settled it was the previous generation's twelve apps:
+ * eleven hash routers and one pushState app. Keeping the second listener costs
+ * a no-op call, and losing it would be silent.
+ *
+ * Idempotent — a second call replaces the first rather than doubling every
+ * view, which matters because React 18 StrictMode mounts twice in development
+ * and a doubled count is a wrong number rather than a visible fault.
+ */
+export declare function startLocationBeacon(options?: ReportPlaceOptions): StopBeacon;
+//# sourceMappingURL=beaconClient.d.ts.map

package/dist/react/engagement/beaconClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"beaconClient.d.ts","sourceRoot":"","sources":["../../../src/react/engagement/beaconClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,2EAA2E;AAC3E,eAAO,MAAM,oBAAoB,oBAAoB,CAAC;AAEtD;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,sBAAsB,CAAC;AAEhD,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CACzB;AAaD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAI7C;AAYD,8DAA8D;AAC9D,wBAAgB,qBAAqB,IAAI,IAAI,CAG5C;AAyBD;;;;;GAKG;AACH,wBAAsB,WAAW,CAChC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,kBAAuB,GAC9B,OAAO,CAAC,OAAO,CAAC,CA+BlB;AAED,8DAA8D;AAC9D,MAAM,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC;AAIpC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,kBAAuB,GAAG,UAAU,CAehF"}

package/dist/react/engagement/beaconClient.js

@@ -0,0 +1,203 @@
+/**
+ * `cursedbelt/react/engagement-beacon` — the engagement beacon's plain-JS half (no React). Lifted
+ * 2026-09-23 (cursedbelt 5.2.0, task 098-280's browser half) from `src/kit/engagement/beacon.client.ts`,
+ * identical in collections, family, music and roms (auth's differed only in a comment). The
+ * server half is `cursedbelt-server/engagement`.
+ *
+ * The browser half — report which PLACE the user is on, once per arrival.
+ *
+ * ── Why an explicit beacon and not the request log ──────────────────────────
+ * Most satellites are SPA-routed: moving from Notes' Files page to its Ask page
+ * fires zero navigations and, on a warm cache, zero HTTP requests. So the
+ * request metrics already in `metrics/` can tell you an app is used and cannot
+ * tell you which of its pages are — which is exactly the question the owner
+ * asked ("notes is used but its slideshow is not"). One small event, sent by
+ * the router, is the only thing that can answer it.
+ *
+ * ── It is ONE implementation, adopted; never per-app ────────────────────────
+ * Eleven hand-rolled beacons would be eleven different place vocabularies, and
+ * the console would be comparing strings that mean different things. Apps call
+ * `reportPlace` (or mount `useEngagementBeacon`) and send an id from their own
+ * route manifest; the server resolves it against that same manifest.
+ *
+ * ── What it does NOT send ───────────────────────────────────────────────────
+ * No path, no query, no title, no referrer, no identifiers of any kind — just
+ * `{ place }`. The account comes from the session cookie the request already
+ * carries, server-side. There is nothing in the payload that could carry a note
+ * id, a ROM title or a search string, which is the property that makes this
+ * safe to run inside private apps at all. See `policy.ts`.
+ *
+ * ── Failure is silence ──────────────────────────────────────────────────────
+ * Every call is fire-and-forget and swallows its error. Telemetry that can
+ * surface an error toast, block a route change, or reject an unhandled promise
+ * is telemetry that makes the app worse than having none.
+ *
+ * 🔴 …and "silence" includes the BROWSER's console, which is why the beacon
+ * asks whether there is a session before it reports (`SESSION_PATH` below).
+ * Swallowing the rejection in JS is not enough: a `fetch` that comes back 401
+ * leaves the browser's own *"Failed to load resource: the server responded with
+ * a status of 401"* in the console no matter what the caller does with the
+ * promise. Measured 2026-08-14 against live prod — `music` and `learn` both
+ * failed their signed-out route-health check on exactly this, with a correctly
+ * rendered sign-in card on screen and nothing else wrong. `apps/roms`' App.tsx
+ * already wrote the rule down for the feedback provider: *"an app that logs an
+ * error on its front door is an app nobody can tell apart from a broken one."*
+ * The recorder's 401 is deliberate and stays — `api.ts` mounts it AFTER the
+ * session gate on purpose, because the gate is what puts the user where
+ * `resolveUser` can read them — so the fix belongs on this side.
+ *
+ * It is also the semantically right answer, not merely a quieter one: the
+ * recorder attributes a view to an account, so a signed-out arrival could never
+ * have been recorded. Nothing that used to be counted stops being counted.
+ */
+/** Where the recorder is mounted. Apps that remount it pass `basePath`. */
+export const ENGAGEMENT_BASE_PATH = "/api/engagement";
+/**
+ * The public session probe every satellite serves
+ * (`ssoConsumer.server.ts` → `{ authenticated, user?, accountsUrl }`).
+ *
+ * Deliberately NOT session-gated on the server, which is what makes it usable
+ * here: asking it costs one small same-origin GET and can never itself produce
+ * the console line this exists to avoid.
+ */
+export const SESSION_PATH = "/api/auth/session";
+/**
+ * The last place reported, so a router that re-renders does not re-report.
+ *
+ * A React router re-runs its effects on every state change that touches the
+ * route object, and a beacon per keystroke in a search box would turn one visit
+ * into forty views — inflating exactly the number the console reads as
+ * "interest". De-duplicating on the place id is what keeps a view meaning "an
+ * arrival".
+ */
+let lastReported = null;
+/**
+ * Where the browser is, as a string the server can resolve.
+ *
+ * The hash when there is one (every satellite but roms routes on it), else the
+ * pathname. Never the search string: `normalizePlaceId` strips one anyway, and
+ * not sending it in the first place means user text does not travel at all.
+ */
+export function currentLocationPlace() {
+    const { hash, pathname } = window.location;
+    const raw = hash && hash !== "#" ? hash : pathname;
+    return raw.split("?")[0] ?? "/";
+}
+/**
+ * The answer to "is anyone signed in?", remembered for this page load.
+ *
+ * One probe per load, not one per navigation: the answer cannot change without
+ * a navigation that replaces the document (the SSO callback is a full page
+ * load), and re-asking on every hash change would trade one wasted request for
+ * dozens.
+ */
+let sessionAnswer = null;
+/** Reset the de-duplication memory. Tests, and a sign-out. */
+export function resetEngagementBeacon() {
+    lastReported = null;
+    sessionAnswer = null;
+}
+/**
+ * Is there a session? Silent, cached, and false on any doubt.
+ *
+ * Fails CLOSED — a probe that throws, answers non-2xx or returns a body this
+ * cannot read means "do not report". The cost of a false negative is one
+ * uncounted view; the cost of a false positive is the console line on the front
+ * door that this whole path exists to prevent.
+ */
+async function hasSession(options) {
+    const doFetch = options.fetchImpl ?? globalThis.fetch;
+    if (typeof doFetch !== "function")
+        return false;
+    try {
+        const res = await doFetch(options.sessionPath ?? SESSION_PATH, {
+            credentials: "same-origin",
+        });
+        if (!res.ok)
+            return false;
+        const body = (await res.json());
+        return body?.authenticated === true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Report an arrival at `place`. Returns whether anything was sent.
+ *
+ * Not awaited by callers in practice — the promise is returned so a test can
+ * settle it without a timer.
+ */
+export async function reportPlace(place, options = {}) {
+    if (!place || place === lastReported)
+        return false;
+    const doFetch = options.fetchImpl ?? globalThis.fetch;
+    if (typeof doFetch !== "function")
+        return false;
+    // 🔴 BEFORE the de-duplication is committed, not after. A signed-out arrival
+    // must leave no trace at all — recording it as `lastReported` would mean the
+    // view that happens once the visitor signs in and lands back on this same
+    // place is silently dropped as a duplicate.
+    if (options.assumeSignedIn !== true) {
+        sessionAnswer ??= hasSession(options);
+        if (!(await sessionAnswer))
+            return false;
+    }
+    if (place === lastReported)
+        return false;
+    lastReported = place;
+    try {
+        await doFetch(`${options.basePath ?? ENGAGEMENT_BASE_PATH}/view`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            // Same-origin credentials: the session cookie is the only identity
+            // this request carries, and it is the only one it may carry.
+            credentials: "same-origin",
+            body: JSON.stringify({ place }),
+            keepalive: true,
+        });
+        return true;
+    }
+    catch {
+        // See the header: telemetry never becomes the user's problem.
+        return false;
+    }
+}
+let running = null;
+/**
+ * Start reporting wherever the browser is, and keep reporting as it moves.
+ *
+ * The form every app adopts, called once from `main.tsx` beside
+ * `initColorScheme()` — one line, no React, and no per-app mapping from a
+ * router's internal view name to a place id. The server resolves the LOCATION
+ * against that app's own `routes.manifest.json` (`policy.ts:resolvePlace`),
+ * which is the list the app already maintains and already gates on.
+ *
+ * `hashchange` and `popstate` between them cover both kinds of router, which is
+ * why BOTH are listened for when `collections` — hash-routed — only needs the
+ * first. The census that settled it was the previous generation's twelve apps:
+ * eleven hash routers and one pushState app. Keeping the second listener costs
+ * a no-op call, and losing it would be silent.
+ *
+ * Idempotent — a second call replaces the first rather than doubling every
+ * view, which matters because React 18 StrictMode mounts twice in development
+ * and a doubled count is a wrong number rather than a visible fault.
+ */
+export function startLocationBeacon(options = {}) {
+    running?.();
+    const send = () => {
+        void reportPlace(currentLocationPlace(), options);
+    };
+    send();
+    window.addEventListener("hashchange", send);
+    window.addEventListener("popstate", send);
+    const stop = () => {
+        window.removeEventListener("hashchange", send);
+        window.removeEventListener("popstate", send);
+        if (running === stop)
+            running = null;
+    };
+    running = stop;
+    return stop;
+}
+//# sourceMappingURL=beaconClient.js.map

package/dist/react/engagement/beaconClient.js.map

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

package/dist/react/engagement/index.d.ts

@@ -0,0 +1,3 @@
+export { ENGAGEMENT_BASE_PATH, type ReportPlaceOptions, reportPlace, resetEngagementBeacon, SESSION_PATH, type StopBeacon, startLocationBeacon, currentLocationPlace, } from './beaconClient.js';
+export { EngagementBeacon, useEngagementBeacon, useLocationBeacon } from './beacon.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/react/engagement/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/react/engagement/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACN,oBAAoB,EACpB,KAAK,kBAAkB,EACvB,WAAW,EACX,qBAAqB,EACrB,YAAY,EACZ,KAAK,UAAU,EACf,mBAAmB,EACnB,oBAAoB,GACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC"}

package/dist/react/engagement/index.js

@@ -0,0 +1,5 @@
+// `cursedbelt/react/engagement-beacon` — the engagement beacon: `reportPlace` and
+// `startLocationBeacon` (plain JS, no React) and the React hooks over them.
+export { ENGAGEMENT_BASE_PATH, reportPlace, resetEngagementBeacon, SESSION_PATH, startLocationBeacon, currentLocationPlace, } from './beaconClient.js';
+export { EngagementBeacon, useEngagementBeacon, useLocationBeacon } from './beacon.js';
+//# sourceMappingURL=index.js.map

package/dist/react/engagement/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/react/engagement/index.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,4EAA4E;AAC5E,OAAO,EACN,oBAAoB,EAEpB,WAAW,EACX,qBAAqB,EACrB,YAAY,EAEZ,mBAAmB,EACnB,oBAAoB,GACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC"}

package/dist/react/lib/directUpload.d.ts

@@ -0,0 +1,130 @@
+/**
+ * `cursedbelt/react/upload-direct` — browser-side resumable upload, straight from the file input
+ * to binary-server.
+ *
+ * Lifted 2026-09-23 (cursedbelt 5.2.0, task 056-343's browser half) from `src/kit/directUpload.ts`,
+ * identical in collections and family. The server half — minting the session — is
+ * `cursedbelt-server/binary-store/upload-session`'s `createUploadSession`.
+ *
+ * 🔴 THIS FILE RUNS IN A BROWSER. It must never import `node:*`, `binaryStore.ts`, or
+ * anything that reaches a private key — see {@link UploadSession}. Keep it dependency-free.
+ *
+ * ## Why the bytes skip the app server
+ *
+ * Every satellite's upload route reads the whole body (`formData()` → `arrayBuffer()`) before
+ * handing it to binary-server, inside a unit capped at `MemoryMax=300M` on a shared t3.micro
+ * that also runs nginx and every other app. That is why the fleet's upload ceiling is 32 MB
+ * and why raising the number was never the fix: a 10 GB video does not fit in the process, in
+ * the nginx body limit, or in the Cloudflare Tunnel's ~100 MB request wall.
+ *
+ * So a large file does not go through the app server at all. The app server mints a session
+ * token naming exactly one destination key; the browser PUTs bounded parts directly to
+ * binary-server, which assembles them; the app server is told afterwards and records the
+ * metadata. No byte of video touches the EC2 box, which is the owner's standing rule for
+ * video (2026-08-12) and also the only shape that survives the memory limit.
+ *
+ * ## What makes it survive 10 GB
+ *
+ * - **Resume.** `GET /upload-chunk` reports which parts already landed, so an upload that
+ *   dies at 90% resumes instead of restarting. That answer comes from the parts on disk, so
+ *   it survives a binary-server restart too.
+ * - **Bounded concurrency.** A few parts in flight keeps a home upstream saturated without
+ *   putting the whole file in memory. Only one part's bytes are ever read at a time per slot.
+ * - **Per-part retry.** A dropped part costs one part, not the upload.
+ * - **Slicing, not reading.** `Blob.slice` is lazy — the 10 GB file is never materialized.
+ */
+/** Everything the browser needs to run an upload, minted server-side by `createUploadSession`
+ *  in `cursedbelt-server/binary-store/upload-session`. Contains a capability token scoped to ONE key, and no key
+ *  material — it is safe to hand to the page that will do the uploading. */
+export interface UploadSession {
+    /** binary-server's public base, e.g. `https://binary-server.cursedalchemy.com`. */
+    baseUrl: string;
+    /** App-prefixed destination key, e.g. `family/media/<uuid>`. */
+    path: string;
+    /** Signed token authorizing this session (carries `sid`, `tc` and the source length `sz`). */
+    token: string;
+    /** Chunk session id. */
+    sid: string;
+    /** Total parts the file was split into. */
+    totalChunks: number;
+    /** Bytes per part — must match what the token's `tc` was computed from. */
+    chunkBytes: number;
+}
+export interface DirectUploadOptions {
+    /** 0..1, called as parts complete. */
+    onProgress?: (fraction: number, bytesSent: number, totalBytes: number) => void;
+    /** Parts in flight at once. Default 3 — enough to saturate a home upstream, few enough
+     *  that a failure retries cheaply. */
+    concurrency?: number;
+    /** Attempts per part before giving up. Default 5, with backoff. */
+    retries?: number;
+    /**
+     * Called once, before any part is sent, when the store reports less free space than this
+     * upload is likely to need.
+     *
+     * 🔴 A WARNING and nothing else — it cannot stop the upload, and there is deliberately no
+     * way for it to. The owner's instruction (2026-08-13) is that space must never block them:
+     * *"Remove all blockers for space and only allow warning me. I'll manage space myself
+     * beyond that."* Returning `false` from here, or throwing, would quietly reinstate exactly
+     * the blocker that was removed.
+     */
+    onLowDisk?: (info: {
+        freeBytes: number;
+        needBytes: number;
+    }) => void;
+    /** Abort the whole upload (a cancel button, or unmount). */
+    signal?: AbortSignal;
+    /** Re-mint an expired session token mid-upload. A 10 GB upload can outlive any TTL short
+     *  enough to be safe, so the page supplies a way to ask its own server for a fresh one
+     *  for the SAME `sid`. Without it, a long upload simply fails on expiry. */
+    refreshToken?: () => Promise<string>;
+}
+/** What binary-server reports once the last part lands. */
+export interface DirectUploadResult {
+    key: string;
+    size: number;
+    checksum: string | null;
+}
+/** Split `[0, total)` into `chunkBytes`-sized part indices. */
+export declare const chunkCount: (totalBytes: number, chunkBytes: number) => number;
+/** Which parts binary-server already holds, plus whether the object is already complete.
+ *  A fresh session answers `{ received: [], complete: false }`, so callers need no special
+ *  case for "first attempt". */
+export declare function fetchSessionState(session: UploadSession, token?: string, signal?: AbortSignal): Promise<{
+    received: Set<number>;
+    complete: boolean;
+    size: number | null;
+    checksum: string | null;
+    /** Bytes binary-server still has room for, or null if it could not tell. */
+    freeBytes: number | null;
+}>;
+/** Thrown when binary-server has no room for the file. Distinct from a transport failure so a
+ *  UI can say "the server is full" — which is actionable — rather than "upload failed", which
+ *  invites the person to retry forever against a disk that will never have space. */
+export declare class InsufficientStorageError extends Error {
+    readonly needBytes: number;
+    readonly freeBytes: number | null;
+    /**
+     * 🔴 Vestigial since 2026-08-13 and kept only so an older deployed binary-server can
+     * still be understood: THIS service no longer refuses an upload for disk space at all,
+     * so nothing here should be producing an overridable refusal any more. If you see one,
+     * the origin is running a build from before that change.
+     */
+    readonly overridable: boolean;
+    constructor(needBytes: number, freeBytes: number | null, 
+    /**
+     * 🔴 Vestigial since 2026-08-13 and kept only so an older deployed binary-server can
+     * still be understood: THIS service no longer refuses an upload for disk space at all,
+     * so nothing here should be producing an overridable refusal any more. If you see one,
+     * the origin is running a build from before that change.
+     */
+    overridable?: boolean);
+}
+/**
+ * Upload `file` to binary-server in parts, resuming anything already delivered.
+ *
+ * Resolves once every part has landed and bs has assembled the object. The caller then tells
+ * its own app server to record the metadata — see each app's `/complete` route.
+ */
+export declare function uploadDirect(file: Blob, session: UploadSession, opts?: DirectUploadOptions): Promise<DirectUploadResult>;
+//# sourceMappingURL=directUpload.d.ts.map

package/dist/react/lib/directUpload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directUpload.d.ts","sourceRoot":"","sources":["../../../src/react/lib/directUpload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH;;4EAE4E;AAC5E,MAAM,WAAW,aAAa;IAC7B,mFAAmF;IACnF,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,8FAA8F;IAC9F,KAAK,EAAE,MAAM,CAAC;IACd,wBAAwB;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IACnC,sCAAsC;IACtC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/E;0CACsC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACrE,4DAA4D;IAC5D,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;gFAE4E;IAC5E,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CACrC;AAED,2DAA2D;AAC3D,MAAM,WAAW,kBAAkB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAID,+DAA+D;AAC/D,eAAO,MAAM,UAAU,GAAI,YAAY,MAAM,EAAE,YAAY,MAAM,KAAG,MACpB,CAAC;AAcjD;;gCAEgC;AAChC,wBAAsB,iBAAiB,CACtC,OAAO,EAAE,aAAa,EACtB,KAAK,SAAgB,EACrB,MAAM,CAAC,EAAE,WAAW,GAClB,OAAO,CAAC;IACV,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACtB,QAAQ,EAAE,OAAO,CAAC;IAClB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,4EAA4E;IAC5E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB,CAAC,CAwBD;AAED;;qFAEqF;AACrF,qBAAa,wBAAyB,SAAQ,KAAK;IAEjD,QAAQ,CAAC,SAAS,EAAE,MAAM;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,WAAW;gBARX,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAAG,IAAI;IACjC;;;;;OAKG;IACM,WAAW,UAAQ;CAS7B;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CACjC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,aAAa,EACtB,IAAI,GAAE,mBAAwB,GAC5B,OAAO,CAAC,kBAAkB,CAAC,CAyJ7B"}