cursedbelt 5.1.0 → 5.2.0

package/dist/react/lib/directUpload.js

@@ -0,0 +1,228 @@
+/**
+ * `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.
+ */
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Split `[0, total)` into `chunkBytes`-sized part indices. */
+export const chunkCount = (totalBytes, chunkBytes) => Math.max(1, Math.ceil(totalBytes / chunkBytes));
+const chunkUrl = (s, token, ci) => `${s.baseUrl}/upload-chunk/${s.path
+    .split("/")
+    .map(encodeURIComponent)
+    .join("/")}?token=${encodeURIComponent(token)}&ci=${ci}`;
+const statusUrl = (s, token) => `${s.baseUrl}/upload-chunk/${s.path
+    .split("/")
+    .map(encodeURIComponent)
+    .join("/")}?token=${encodeURIComponent(token)}`;
+/** 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 async function fetchSessionState(session, token = session.token, signal) {
+    const res = await fetch(statusUrl(session, token), { signal });
+    if (!res.ok)
+        return {
+            received: new Set(),
+            complete: false,
+            size: null,
+            checksum: null,
+            freeBytes: null,
+        };
+    const body = (await res.json());
+    return {
+        received: new Set(body.received ?? []),
+        complete: Boolean(body.complete),
+        size: body.size ?? null,
+        checksum: body.checksum ?? null,
+        freeBytes: body.freeBytes ?? 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 class InsufficientStorageError extends Error {
+    needBytes;
+    freeBytes;
+    overridable;
+    constructor(needBytes, freeBytes, 
+    /**
+     * 🔴 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 = false) {
+        super(freeBytes === null
+            ? "binary-server is out of space for this upload"
+            : `binary-server has ${(freeBytes / 1024 ** 3).toFixed(1)} GB free, which is not enough for a ${(needBytes / 1024 ** 3).toFixed(1)} GB upload`);
+        this.needBytes = needBytes;
+        this.freeBytes = freeBytes;
+        this.overridable = overridable;
+        this.name = "InsufficientStorageError";
+    }
+}
+/**
+ * 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 async function uploadDirect(file, session, opts = {}) {
+    const { onProgress, signal, refreshToken } = opts;
+    const concurrency = Math.max(1, opts.concurrency ?? 3);
+    const retries = Math.max(1, opts.retries ?? 5);
+    const { onLowDisk } = opts;
+    const total = session.totalChunks;
+    // A token can expire mid-upload on a slow line; `refreshToken` swaps in a new one and
+    // every subsequent request picks it up.
+    let token = session.token;
+    const prior = await fetchSessionState(session, token, signal);
+    if (prior.complete) {
+        return {
+            key: session.path,
+            size: prior.size ?? file.size,
+            checksum: prior.checksum,
+        };
+    }
+    // Bail before sending anything if the file plainly cannot land. bs keeps a reserve so a
+    // full disk never takes the Mac down, and it reports free space on the status call above —
+    // so an upload with nowhere to go costs one request instead of gigabytes of transfer.
+    const remainingBytes = file.size - prior.received.size * session.chunkBytes;
+    /*
+     * 🔴 NO PREFLIGHT REFUSAL. Owner instruction, 2026-08-13: *"Remove all blockers for space
+     * and only allow warning me. I'll manage space myself beyond that."*
+     *
+     * This used to throw when the remaining bytes exceeded the reported free space. It is gone
+     * rather than softened because a client-side estimate is the WORST place to make this
+     * call: `remainingBytes` counts every part not yet delivered, `freeBytes` was read before
+     * the transfer began, and neither accounts for what the run itself frees or the owner
+     * clears while it goes. binary-server no longer refuses either; the real limit is ENOSPC
+     * from the filesystem, which is about the actual write rather than a projection.
+     *
+     * `onLowDisk` is the replacement, and it only WARNS.
+     */
+    if (prior.freeBytes !== null && remainingBytes > prior.freeBytes) {
+        onLowDisk?.({ freeBytes: prior.freeBytes, needBytes: remainingBytes });
+    }
+    const pending = Array.from({ length: total }, (_, i) => i).filter((i) => !prior.received.has(i));
+    let done = total - pending.length;
+    let assembled = null;
+    const report = () => onProgress?.(total === 0 ? 1 : done / total, done * session.chunkBytes, file.size);
+    report();
+    const sendOne = async (ci) => {
+        const start = ci * session.chunkBytes;
+        // Lazy view onto the file — nothing is read until fetch streams it.
+        const part = file.slice(start, Math.min(start + session.chunkBytes, file.size));
+        let lastErr;
+        for (let attempt = 0; attempt < retries; attempt++) {
+            signal?.throwIfAborted();
+            try {
+                const res = await fetch(chunkUrl(session, token, ci), {
+                    method: "PUT",
+                    body: part,
+                    // bs stores the mime from the assembling request's content-type.
+                    // 🔴 `x-allow-low-disk` is what turns binary-server's disk RESERVE from a
+                    // wall into a warning. Owner instruction 2026-08-13, after a large upload
+                    // stopped dead: *"Do not let the server block me. It can warn me and I can
+                    // say do it anyway or cancel if I want."* The reserve is sized for the worst
+                    // case a chunked upload can transiently need, so it refused uploads that
+                    // would have fit. bs still refuses absolutely below its hard floor, where
+                    // the machine itself is what is at risk.
+                    headers: file.type ? { "content-type": file.type } : undefined,
+                    signal,
+                });
+                if (res.status === 403 && refreshToken) {
+                    // Almost always an expired session token on a long upload. Re-mint once per
+                    // attempt and let the loop retry with it.
+                    token = await refreshToken();
+                    throw new Error("token refreshed, retrying");
+                }
+                // Out of space is terminal — retrying cannot make room, and a 10 GB upload
+                // hammering a full disk five times over is the opposite of helpful.
+                if (res.status === 507) {
+                    const body = (await res.json().catch(() => ({})));
+                    // Terminal — retrying cannot make room, and a 10 GB upload hammering a full
+                    // disk five times over is the opposite of helpful. 🔴 A CURRENT
+                    // binary-server never sends this for its own reserve any more (see
+                    // `overridable`); reaching here means the volume is genuinely out of room
+                    // and the filesystem said so.
+                    throw new InsufficientStorageError(file.size, body.freeBytes ?? null, body.overridable === true);
+                }
+                if (!res.ok)
+                    throw new Error(`chunk ${ci}: HTTP ${res.status}`);
+                const body = (await res.json());
+                if (body.assembled) {
+                    assembled = {
+                        key: body.key ?? session.path,
+                        size: body.size ?? file.size,
+                        checksum: body.checksum ?? null,
+                    };
+                }
+                done++;
+                report();
+                return;
+            }
+            catch (err) {
+                if (signal?.aborted)
+                    throw err;
+                // Terminal: no amount of backoff creates disk space.
+                if (err instanceof InsufficientStorageError)
+                    throw err;
+                lastErr = err;
+                // Backoff, capped — a home connection that dropped needs seconds, not minutes.
+                await sleep(Math.min(1000 * 2 ** attempt, 15_000));
+            }
+        }
+        throw new Error(`chunk ${ci} failed after ${retries} attempts: ${lastErr instanceof Error ? lastErr.message : String(lastErr)}`);
+    };
+    // Bounded worker pool over the pending indices.
+    const queue = [...pending];
+    const workers = Array.from({ length: Math.min(concurrency, queue.length) }, async () => {
+        for (;;) {
+            const next = queue.shift();
+            if (next === undefined)
+                return;
+            await sendOne(next);
+        }
+    });
+    await Promise.all(workers);
+    if (assembled)
+        return assembled;
+    // Every part reported OK but no response carried the assemble result — possible if the
+    // final 201 was the one that got retried after its response was lost. Ask.
+    const after = await fetchSessionState(session, token, signal);
+    if (after.complete) {
+        return { key: session.path, size: after.size ?? file.size, checksum: after.checksum };
+    }
+    throw new Error(`upload finished but binary-server did not assemble ${session.path} (${after.received.size}/${total} parts)`);
+}
+//# sourceMappingURL=directUpload.js.map

package/dist/react/lib/directUpload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"directUpload.js","sourceRoot":"","sources":["../../../src/react/lib/directUpload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAsDH,MAAM,KAAK,GAAG,CAAC,EAAU,EAAiB,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;AAEnF,+DAA+D;AAC/D,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,UAAkB,EAAE,UAAkB,EAAU,EAAE,CAC5E,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC,CAAC,CAAC;AAEjD,MAAM,QAAQ,GAAG,CAAC,CAAgB,EAAE,KAAa,EAAE,EAAU,EAAU,EAAE,CACxE,GAAG,CAAC,CAAC,OAAO,iBAAiB,CAAC,CAAC,IAAI;KACjC,KAAK,CAAC,GAAG,CAAC;KACV,GAAG,CAAC,kBAAkB,CAAC;KACvB,IAAI,CAAC,GAAG,CAAC,UAAU,kBAAkB,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;AAE3D,MAAM,SAAS,GAAG,CAAC,CAAgB,EAAE,KAAa,EAAU,EAAE,CAC7D,GAAG,CAAC,CAAC,OAAO,iBAAiB,CAAC,CAAC,IAAI;KACjC,KAAK,CAAC,GAAG,CAAC;KACV,GAAG,CAAC,kBAAkB,CAAC;KACvB,IAAI,CAAC,GAAG,CAAC,UAAU,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC;AAElD;;gCAEgC;AAChC,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACtC,OAAsB,EACtB,KAAK,GAAG,OAAO,CAAC,KAAK,EACrB,MAAoB;IASpB,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,SAAS,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IAC/D,IAAI,CAAC,GAAG,CAAC,EAAE;QACV,OAAO;YACN,QAAQ,EAAE,IAAI,GAAG,EAAE;YACnB,QAAQ,EAAE,KAAK;YACf,IAAI,EAAE,IAAI;YACV,QAAQ,EAAE,IAAI;YACd,SAAS,EAAE,IAAI;SACf,CAAC;IACH,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAM7B,CAAC;IACF,OAAO;QACN,QAAQ,EAAE,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC;QACtC,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC;QAChC,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,IAAI;QACvB,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,IAAI;QAC/B,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,IAAI;KACjC,CAAC;AACH,CAAC;AAED;;qFAEqF;AACrF,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IAExC;IACA;IAOA;IATV,YACU,SAAiB,EACjB,SAAwB;IACjC;;;;;OAKG;IACM,cAAc,KAAK;QAE5B,KAAK,CACJ,SAAS,KAAK,IAAI;YACjB,CAAC,CAAC,+CAA+C;YACjD,CAAC,CAAC,qBAAqB,CAAC,SAAS,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,uCAAuC,CAAC,SAAS,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY,CAC/I,CAAC;QAdO,cAAS,GAAT,SAAS,CAAQ;QACjB,cAAS,GAAT,SAAS,CAAe;QAOxB,gBAAW,GAAX,WAAW,CAAQ;QAO5B,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACxC,CAAC;CACD;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CACjC,IAAU,EACV,OAAsB,EACtB,OAA4B,EAAE;IAE9B,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC;IAClD,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,WAAW,IAAI,CAAC,CAAC,CAAC;IACvD,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC;IAC/C,MAAM,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC;IAC3B,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,CAAC;IAElC,sFAAsF;IACtF,wCAAwC;IACxC,IAAI,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IAE1B,MAAM,KAAK,GAAG,MAAM,iBAAiB,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;IAC9D,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QACpB,OAAO;YACN,GAAG,EAAE,OAAO,CAAC,IAAI;YACjB,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI;YAC7B,QAAQ,EAAE,KAAK,CAAC,QAAQ;SACxB,CAAC;IACH,CAAC;IAED,wFAAwF;IACxF,2FAA2F;IAC3F,sFAAsF;IACtF,MAAM,cAAc,GAAG,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,QAAQ,CAAC,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC;IAC5E;;;;;;;;;;;;OAYG;IACH,IAAI,KAAK,CAAC,SAAS,KAAK,IAAI,IAAI,cAAc,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;QAClE,SAAS,EAAE,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,SAAS,EAAE,cAAc,EAAE,CAAC,CAAC;IACxE,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACjG,IAAI,IAAI,GAAG,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC;IAClC,IAAI,SAAS,GAA8B,IAAI,CAAC;IAEhD,MAAM,MAAM,GAAG,GAAS,EAAE,CACzB,UAAU,EAAE,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,KAAK,EAAE,IAAI,GAAG,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IACpF,MAAM,EAAE,CAAC;IAET,MAAM,OAAO,GAAG,KAAK,EAAE,EAAU,EAAiB,EAAE;QACnD,MAAM,KAAK,GAAG,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC;QACtC,oEAAoE;QACpE,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QAEhF,IAAI,OAAgB,CAAC;QACrB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC;YACpD,MAAM,EAAE,cAAc,EAAE,CAAC;YACzB,IAAI,CAAC;gBACJ,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,CAAC,EAAE;oBACrD,MAAM,EAAE,KAAK;oBACb,IAAI,EAAE,IAAI;oBACV,iEAAiE;oBACjE,0EAA0E;oBAC1E,0EAA0E;oBAC1E,2EAA2E;oBAC3E,6EAA6E;oBAC7E,yEAAyE;oBACzE,0EAA0E;oBAC1E,yCAAyC;oBACzC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS;oBAC9D,MAAM;iBACN,CAAC,CAAC;gBAEH,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,IAAI,YAAY,EAAE,CAAC;oBACxC,4EAA4E;oBAC5E,0CAA0C;oBAC1C,KAAK,GAAG,MAAM,YAAY,EAAE,CAAC;oBAC7B,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;gBAC9C,CAAC;gBACD,2EAA2E;gBAC3E,oEAAoE;gBACpE,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;oBACxB,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAG/C,CAAC;oBACF,4EAA4E;oBAC5E,gEAAgE;oBAChE,mEAAmE;oBACnE,0EAA0E;oBAC1E,8BAA8B;oBAC9B,MAAM,IAAI,wBAAwB,CACjC,IAAI,CAAC,IAAI,EACT,IAAI,CAAC,SAAS,IAAI,IAAI,EACtB,IAAI,CAAC,WAAW,KAAK,IAAI,CACzB,CAAC;gBACH,CAAC;gBACD,IAAI,CAAC,GAAG,CAAC,EAAE;oBAAE,MAAM,IAAI,KAAK,CAAC,SAAS,EAAE,UAAU,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;gBAEhE,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAK7B,CAAC;gBACF,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;oBACpB,SAAS,GAAG;wBACX,GAAG,EAAE,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,IAAI;wBAC7B,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI;wBAC5B,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,IAAI;qBAC/B,CAAC;gBACH,CAAC;gBACD,IAAI,EAAE,CAAC;gBACP,MAAM,EAAE,CAAC;gBACT,OAAO;YACR,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACd,IAAI,MAAM,EAAE,OAAO;oBAAE,MAAM,GAAG,CAAC;gBAC/B,qDAAqD;gBACrD,IAAI,GAAG,YAAY,wBAAwB;oBAAE,MAAM,GAAG,CAAC;gBACvD,OAAO,GAAG,GAAG,CAAC;gBACd,+EAA+E;gBAC/E,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,IAAI,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;YACpD,CAAC;QACF,CAAC;QACD,MAAM,IAAI,KAAK,CACd,SAAS,EAAE,iBAAiB,OAAO,cAClC,OAAO,YAAY,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAC5D,EAAE,CACF,CAAC;IACH,CAAC,CAAC;IAEF,gDAAgD;IAChD,MAAM,KAAK,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC;IAC3B,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,EAAE,KAAK,IAAI,EAAE;QACtF,SAAS,CAAC;YACT,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC;YAC3B,IAAI,IAAI,KAAK,SAAS;gBAAE,OAAO;YAC/B,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;QACrB,CAAC;IACF,CAAC,CAAC,CAAC;IACH,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAE3B,IAAI,SAAS;QAAE,OAAO,SAAS,CAAC;IAEhC,uFAAuF;IACvF,2EAA2E;IAC3E,MAAM,KAAK,GAAG,MAAM,iBAAiB,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;IAC9D,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QACpB,OAAO,EAAE,GAAG,EAAE,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC;IACvF,CAAC;IACD,MAAM,IAAI,KAAK,CACd,sDAAsD,OAAO,CAAC,IAAI,KAAK,KAAK,CAAC,QAAQ,CAAC,IAAI,IAAI,KAAK,SAAS,CAC5G,CAAC;AACH,CAAC"}

package/dist/styles-areas/auth.css

@@ -18,12 +18,12 @@
  * after an app's responsive variant (task 2124). An app that imports every area gets exactly
  * what `cursedbelt/styles-utilities.css` emits — proved rule by rule in
  * src/stylesAreas.spec.ts, which is also what fails when this file is stale.
- * 11 candidate(s).
+ * 10 candidate(s).
  *
  * Written by scripts/generateAreaStyles.ts (`bun run styles:areas`), which
  * `bun run build` runs. The map of what is in which area, and why the areas are
  * import closures rather than a hand-written list, is scripts/styleAreas.ts.
  */
-@source inline("caret-transparent com focus-within:border-field-ring focus-within:ring-2");
+@source inline("caret-transparent focus-within:border-field-ring focus-within:ring-2");
 @source inline("focus-within:ring-field-ring/30 h-12 has-[[aria-invalid=true]]:border-field-error min-h-dvh");
 @source inline("self-start self-stretch sm:w-11");

package/dist/styles-areas/core.css

@@ -15,7 +15,7 @@
  * after an app's responsive variant (task 2124). An app that imports every area gets exactly
  * what `cursedbelt/styles-utilities.css` emits — proved rule by rule in
  * src/stylesAreas.spec.ts, which is also what fails when this file is stale.
- * 705 candidate(s).
+ * 706 candidate(s).
  *
  * Written by scripts/generateAreaStyles.ts (`bun run styles:areas`), which
  * `bun run build` runs. The map of what is in which area, and why the areas are
@@ -52,7 +52,7 @@
 @source inline("border-collapse border-current border-destructive/30 border-destructive/40 border-destructive/50");
 @source inline("border-field-border border-success/30 border-success/40 border-success/50 border-t");
 @source inline("border-transparent border-warning/30 border-warning/40 border-warning/50 border-x-4");
-@source inline("border-x-transparent bot bottom bottom-0 break break-all c ca cap capitalize co contain");
+@source inline("border-x-transparent bot bottom bottom-0 break break-all c ca cap capitalize co com contain");
 @source inline("container content contents cursor cursor-col-resize cursor-default cursor-ew-resize");
 @source inline("cursor-pointer cursor-row-resize d dark dark:bg-card-overlay dark:bg-card-raised");
 @source inline("dark:bg-gray-800 data data-[disabled]:hover:bg-border data-[disabled]:opacity-50");

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt",
-	"version": "5.1.0",
+	"version": "5.2.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "The React design system of the cursedbelt split — components, styles, theme. cursedbelt-core below it; server tier in cursedbelt-server.",
@@ -203,6 +203,12 @@
 			"source": "./src/react/components/DropdownMenu.tsx",
 			"import": "./dist/react/components/DropdownMenu.js"
 		},
+		"./react/engagement-beacon": {
+			"types": "./dist/react/engagement/index.d.ts",
+			"bun": "./src/react/engagement/index.ts",
+			"source": "./src/react/engagement/index.ts",
+			"import": "./dist/react/engagement/index.js"
+		},
 		"./react/file-tree": {
 			"types": "./dist/react/file-tree/index.d.ts",
 			"bun": "./src/react/file-tree/index.ts",
@@ -395,6 +401,12 @@
 			"source": "./src/react/components/Switch.tsx",
 			"import": "./dist/react/components/Switch.js"
 		},
+		"./react/upload-direct": {
+			"types": "./dist/react/lib/directUpload.d.ts",
+			"bun": "./src/react/lib/directUpload.ts",
+			"source": "./src/react/lib/directUpload.ts",
+			"import": "./dist/react/lib/directUpload.js"
+		},
 		"./react/workbook-viewer": {
 			"types": "./dist/react/workbook-viewer/index.d.ts",
 			"bun": "./src/react/workbook-viewer/index.ts",

package/scripts/checkAreaStyles.spec.ts

@@ -8,6 +8,7 @@ import {
   classesInCss,
   hasVariantPrefix,
   inlineCandidatesIn,
+  onlyAsPropertyName,
   onlyInMergeTables,
   readBeltSheets,
   tokensInJs,
@@ -133,6 +134,28 @@ describe('🔴 tailwind-merge tables are not usage (task 2118)', () => {
   });
 });
 
+describe('🔴 a property NAME is not class usage (task 2131, station)', () => {
+  // Verbatim from station's build: d3's scale check, inside recharts.
+  const STATION = 'function RE(e){if(e!=null)return"invert"in e&&typeof e.invert=="function"?e.invert:null}';
+
+  test('an `in` test and an object key are excused', () => {
+    expect(onlyAsPropertyName('invert', STATION)).toBe(true);
+    expect(onlyAsPropertyName('invert', 'const o={"invert":1}')).toBe(true);
+  });
+
+  test('refused when the token is ALSO a class, or a lone string value (`cn("italic")` IS usage)', () => {
+    expect(onlyAsPropertyName('invert', `${STATION};x({className:"invert grayscale"})`)).toBe(false);
+    expect(onlyAsPropertyName('italic', 'x=cn("italic",y)')).toBe(false);
+    expect(onlyAsPropertyName('h-8', 'const v={size:{sm:"h-8"}}')).toBe(false);
+    expect(onlyAsPropertyName('invert', '')).toBe(false);
+  });
+
+  test('the station shape reports no `invert` miss', () => {
+    const { missing } = checkAreaStyles({ js: [STATION], css: [''] }, readBeltSheets());
+    expect(missing.map((m) => m.className)).not.toContain('invert');
+  });
+});
+
 describe('an area is `@source inline` candidates since 5.1.0 (task 2124)', () => {
   test('inlineCandidatesIn reads both quote kinds and skips markers', () => {
     const css = `/* banner */\n@source inline("flex sm:hidden peer");\n@source inline('before:content-[""]');\n`;

package/scripts/checkAreaStyles.ts

@@ -132,6 +132,25 @@ export function onlyInMergeTables(token: string, js: string): boolean {
   return seen > 0 && [...js.matchAll(bare)].length === seen;
 }
 
+/**
+ * Does `token` occur in the built JS only as a PROPERTY NAME — the left side of an `in` test
+ * (`"invert"in e`, d3's scale check inside recharts) or an object key (`{"invert":…}`)? A className
+ * is always a string VALUE, never either (task 2131, measured on station's build 2026-09-23: the
+ * only false reference left after the tailwind-merge filter, and it demanded the `media` area).
+ * Refused as soon as the token also appears in any class string.
+ */
+export function onlyAsPropertyName(token: string, js: string): boolean {
+  const quoted = new RegExp(`(["'])${escapeRe(token)}\\1`, 'g');
+  let seen = 0;
+  for (const m of js.matchAll(quoted)) {
+    seen++;
+    const after = js.slice((m.index ?? 0) + m[0].length, (m.index ?? 0) + m[0].length + 4);
+    if (!/^\s*(?::|in\b)/.test(after)) return false;
+  }
+  const bare = new RegExp(`(^|[\\s"'\`])${escapeRe(token)}(?=[\\s"'\`]|$)`, 'g');
+  return seen > 0 && [...js.matchAll(bare)].length === seen;
+}
+
 // ── the ORDER check (5.1.0, task 2124) ─────────────────────────────────────────────────
 
 export interface CascadeFault {
@@ -290,7 +309,7 @@ export function checkAreaStyles(
   const allJs = input.js.join('\n');
   const missing = [...referenced]
     .filter((name) => !emitted.has(name))
-    .filter((name) => !onlyInMergeTables(name, allJs))
+    .filter((name) => !onlyInMergeTables(name, allJs) && !onlyAsPropertyName(name, allJs))
     .sort()
     .map((className) => ({ className, area: areaOf.get(className) as string }));
   return { missing, referenced: referenced.size };

package/scripts/styleAreas.ts

@@ -130,6 +130,8 @@ export const AREAS: readonly Area[] = [
 			'colorScheme',
 			'constants',
 			'layout',
+			// The engagement beacon draws nothing; it is here because every app beacons (5.2.0).
+			'engagement',
 			'namespace',
 			'portal',
 			'slots',

package/src/react/engagement/beacon.tsx

@@ -0,0 +1,63 @@
+/**
+ * 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 { type ReportPlaceOptions, 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: string | null, options: ReportPlaceOptions = {}): void {
+	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: ReportPlaceOptions = {}): void {
+	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: { basePath?: string }): null {
+	useLocationBeacon(props.basePath ? { basePath: props.basePath } : {});
+	return null;
+}

package/src/react/engagement/beaconClient.spec.ts

@@ -0,0 +1,138 @@
+/**
+ * The beacon's SILENCE contract.
+ *
+ * `beacon.client.ts` says failure is silence, and on 2026-08-14 that turned out
+ * to be true only of the JavaScript. A `fetch` that comes back 401 leaves the
+ * browser's own *"Failed to load resource"* in the console however carefully the
+ * promise is handled — so a beacon fired from a sign-in card put an error on the
+ * front door of every private satellite, and `music`'s and `learn`'s signed-out
+ * route health failed on it against live prod with nothing else wrong.
+ *
+ * These tests are about the request that is NOT made. `window` is deliberately
+ * untouched: `reportPlace` is the whole mechanism and needs no DOM, which is why
+ * this file runs in the package's plain `bun test`.
+ */
+import { beforeEach, describe, expect, test } from "bun:test";
+import { reportPlace, resetEngagementBeacon, SESSION_PATH } from "./beaconClient.js";
+
+/** A `fetch` that records every call and answers from a script. */
+function recordingFetch(answers: Record<string, { status?: number; body?: unknown }>) {
+	const calls: string[] = [];
+	const impl = (async (input: string) => {
+		const url = String(input);
+		calls.push(url);
+		const answer = answers[url] ?? { status: 404 };
+		const status = answer.status ?? 200;
+		return {
+			ok: status >= 200 && status < 300,
+			status,
+			json: async () => answer.body ?? {},
+		};
+	}) as unknown as typeof fetch;
+	return { impl, calls };
+}
+
+const SIGNED_IN = { body: { authenticated: true } };
+const SIGNED_OUT = { body: { authenticated: false } };
+
+beforeEach(() => {
+	resetEngagementBeacon();
+});
+
+describe("signed out, the beacon makes no gated request at all", () => {
+	test("it asks the public session probe and then stays quiet", async () => {
+		const { impl, calls } = recordingFetch({ [SESSION_PATH]: SIGNED_OUT });
+
+		expect(await reportPlace("/#/hub", { fetchImpl: impl })).toBe(false);
+
+		// The probe, and nothing else. A POST to the gated recorder is exactly the
+		// request that produced the console line.
+		expect(calls).toEqual([SESSION_PATH]);
+	});
+
+	test("🔴 it does not consume the de-duplication slot", async () => {
+		// The bug this ordering prevents: a signed-out arrival at `/#/hub` marking
+		// `/#/hub` as already-reported, so the FIRST real view after signing in —
+		// which lands on that same place — is dropped forever as a duplicate.
+		const out = recordingFetch({ [SESSION_PATH]: SIGNED_OUT });
+		expect(await reportPlace("/#/hub", { fetchImpl: out.impl })).toBe(false);
+
+		resetEngagementBeacon(); // what a full page load (the SSO callback) does
+		const inn = recordingFetch({
+			[SESSION_PATH]: SIGNED_IN,
+			"/api/engagement/view": { status: 200 },
+		});
+		expect(await reportPlace("/#/hub", { fetchImpl: inn.impl })).toBe(true);
+		expect(inn.calls).toContain("/api/engagement/view");
+	});
+});
+
+describe("signed in, nothing that used to be counted stops being counted", () => {
+	test("the view is reported, after the probe", async () => {
+		const { impl, calls } = recordingFetch({
+			[SESSION_PATH]: SIGNED_IN,
+			"/api/engagement/view": { status: 200 },
+		});
+
+		expect(await reportPlace("/#/stats", { fetchImpl: impl })).toBe(true);
+		expect(calls).toEqual([SESSION_PATH, "/api/engagement/view"]);
+	});
+
+	test("the probe is asked ONCE per page load, not once per navigation", async () => {
+		const { impl, calls } = recordingFetch({
+			[SESSION_PATH]: SIGNED_IN,
+			"/api/engagement/view": { status: 200 },
+		});
+
+		await reportPlace("/#/hub", { fetchImpl: impl });
+		await reportPlace("/#/stats", { fetchImpl: impl });
+		await reportPlace("/#/archive", { fetchImpl: impl });
+
+		expect(calls.filter((url) => url === SESSION_PATH)).toHaveLength(1);
+		expect(calls.filter((url) => url === "/api/engagement/view")).toHaveLength(3);
+	});
+
+	test("a repeated place is still one view — the old rule is untouched", async () => {
+		const { impl, calls } = recordingFetch({
+			[SESSION_PATH]: SIGNED_IN,
+			"/api/engagement/view": { status: 200 },
+		});
+
+		await reportPlace("/#/hub", { fetchImpl: impl });
+		expect(await reportPlace("/#/hub", { fetchImpl: impl })).toBe(false);
+		expect(calls.filter((url) => url === "/api/engagement/view")).toHaveLength(1);
+	});
+});
+
+describe("the probe fails CLOSED", () => {
+	// One uncounted view is cheap. A false positive is the console line on the
+	// front door, which is the whole thing this path exists to prevent.
+	test.each([
+		["the probe itself errors", null],
+		["the probe answers non-2xx", { status: 500 }],
+		["the body carries no verdict", { body: {} }],
+		["the body says authenticated is a string", { body: { authenticated: "yes" } }],
+	])("%s → nothing is sent", async (_name, answer) => {
+		const impl = (async (input: string) => {
+			if (answer === null) throw new Error("network down");
+			const status = (answer as { status?: number }).status ?? 200;
+			return {
+				ok: status >= 200 && status < 300,
+				status,
+				json: async () => (answer as { body?: unknown }).body ?? {},
+				_url: input,
+			};
+		}) as unknown as typeof fetch;
+
+		expect(await reportPlace("/#/hub", { fetchImpl: impl })).toBe(false);
+	});
+});
+
+describe("a caller that already knows may skip the probe", () => {
+	test("assumeSignedIn reports with no second answer to the same question", async () => {
+		const { impl, calls } = recordingFetch({ "/api/engagement/view": { status: 200 } });
+
+		expect(await reportPlace("/#/hub", { fetchImpl: impl, assumeSignedIn: true })).toBe(true);
+		expect(calls).toEqual(["/api/engagement/view"]);
+	});
+});