@supersuit/artifacts 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -3,6 +3,29 @@
 `@supersuit/artifacts`. One entry per version, newest first. Each entry says what changed, how a
 host can tell whether it is affected (DETECTOR), what a host does about it (REMEDY), and the tests.
 
+## 0.4.1 (2026-09-26)
+
+**Big files upload straight to the bucket.**
+
+- A route handler on Vercel refuses a body over 4.5 MB (`FUNCTION_PAYLOAD_TOO_LARGE`), about five
+  minutes of narration, so a long page's audio could never publish; `PUT_ASSET`'s own 16 MiB cap
+  was never reached. New route `UPLOAD` (`POST /api/artifacts/<id>/uploads/<name>`, publish key,
+  JSON `{ digest }`) returns a v4 signed URL and the headers to send; the publisher PUTs the bytes
+  there, then calls again with `{ digest, done: true }`, which makes the object readable and
+  returns its URL (409 if nothing arrived). The key is the same hashed name `put()` writes, with
+  the same `immutable` cache header. `ArtifactAssets` gains optional `signUpload` and
+  `finishUpload`; `createArtifactAssets` implements both. `storedName`, `hashedName` and
+  `ASSET_DIGEST` are exported.
+- **DETECTOR:** publishing a page whose narration is longer than about five minutes fails with
+  `narration upload failed 413: ... FUNCTION_PAYLOAD_TOO_LARGE`.
+- **REMEDY:** add `app/api/artifacts/[id]/uploads/[name]/route.ts` exporting `POST` that calls
+  the routes' `UPLOAD`, the same shape as the assets route. The bucket's service account needs no
+  new permission when the host signs with a service-account key. Until the route exists the
+  publisher gets a 404 and falls back to `PUT_ASSET`.
+- **Tests:** signing targets put()'s key with its cache header; finishing refuses a missing
+  object; the route's refusals match `PUT_ASSET`'s, a bad digest is 400, and a host whose assets
+  cannot sign answers 501.
+
 ## 0.4.0 (2026-09-26)
 
 **Light and dark modes, a table of contents, and an animated ground.**

package/lib/artifacts/assets.d.ts

@@ -2,7 +2,21 @@ import type { Bucket } from '@google-cloud/storage';
 export interface ArtifactAssets {
     /** Store `bytes` for artifact `id` under `name`; return the public URL. */
     put(id: string, name: string, bytes: Buffer, contentType: string): Promise<string>;
+    /**
+     * A signed URL the publisher PUTs a big file to directly, skipping the route handler.
+     * `digest` is the first 8 hex of the bytes' sha256, so the key is the one put() would use.
+     * Optional: a host without it answers 501 and the publisher falls back to put().
+     */
+    signUpload?(id: string, name: string, digest: string, contentType: string): Promise<{
+        uploadUrl: string;
+        headers: Record<string, string>;
+        url: string;
+    }>;
+    /** After a signed upload: make it readable and return its URL, or null if nothing arrived. */
+    finishUpload?(id: string, name: string, digest: string): Promise<string | null>;
 }
+/** The digest half of a stored name: the first 8 hex of the bytes' sha256. */
+export declare const ASSET_DIGEST: RegExp;
 /** Names are one path segment: letters, digits, dot, dash, underscore. */
 export declare const ASSET_NAME: RegExp;
 export declare const ASSET_TYPES: Record<string, string>;
@@ -24,4 +38,6 @@ export declare function contentTypeFor(name: string): string | undefined;
  * URL and stay cached, which is the whole benefit.
  */
 export declare function hashedName(name: string, bytes: Buffer): string;
+/** `name` with `digest` spliced in before the extension, the way hashedName stores it. */
+export declare function storedName(name: string, digest: string): string;
 export declare function createArtifactAssets(bucket: Bucket, prefix: string): ArtifactAssets;

package/lib/artifacts/assets.js

@@ -3,6 +3,9 @@
 // publisher shelled out to gsutil against the maintainer's bucket, which no other operator
 // could do, so every operator gets the same door: PUT bytes with their key, get a URL back.
 import { createHash } from 'node:crypto';
+/** The digest half of a stored name: the first 8 hex of the bytes' sha256. */
+export const ASSET_DIGEST = /^[0-9a-f]{8}$/;
+const CACHE_CONTROL = 'public, max-age=31536000, immutable';
 /** Names are one path segment: letters, digits, dot, dash, underscore. */
 export const ASSET_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,120}$/;
 export const ASSET_TYPES = {
@@ -35,7 +38,10 @@ export function contentTypeFor(name) {
  * URL and stay cached, which is the whole benefit.
  */
 export function hashedName(name, bytes) {
-    const digest = createHash('sha256').update(bytes).digest('hex').slice(0, 8);
+    return storedName(name, createHash('sha256').update(bytes).digest('hex').slice(0, 8));
+}
+/** `name` with `digest` spliced in before the extension, the way hashedName stores it. */
+export function storedName(name, digest) {
     const dot = name.lastIndexOf('.');
     // A name with no extension is legal here, so append rather than assume there is a dot.
     return dot <= 0 ? `${name}.${digest}` : `${name.slice(0, dot)}.${digest}${name.slice(dot)}`;
@@ -49,7 +55,7 @@ export function createArtifactAssets(bucket, prefix) {
             await file.save(bytes, {
                 contentType,
                 resumable: false,
-                metadata: { cacheControl: 'public, max-age=31536000, immutable' },
+                metadata: { cacheControl: CACHE_CONTROL },
             });
             try {
                 await file.makePublic();
@@ -59,5 +65,35 @@ export function createArtifactAssets(bucket, prefix) {
             }
             return `https://storage.googleapis.com/${bucket.name}/${key}`;
         },
+        // A route handler on Vercel refuses a body over 4.5 MB (FUNCTION_PAYLOAD_TOO_LARGE), which is
+        // about five minutes of narration. An hour-long paper's audio (~55 MB) could never publish.
+        // So a big file goes to the bucket directly, on a URL signed with the host's own service
+        // account, to the same hashed key and with the same cache header put() writes.
+        async signUpload(id, name, digest, contentType) {
+            const key = `${clean}/${id}/${storedName(name, digest)}`;
+            const headers = { 'content-type': contentType, 'cache-control': CACHE_CONTROL };
+            const [uploadUrl] = await bucket.file(key).getSignedUrl({
+                version: 'v4',
+                action: 'write',
+                expires: Date.now() + 15 * 60 * 1000,
+                contentType,
+                extensionHeaders: { 'cache-control': CACHE_CONTROL },
+            });
+            return { uploadUrl, headers, url: `https://storage.googleapis.com/${bucket.name}/${key}` };
+        },
+        async finishUpload(id, name, digest) {
+            const key = `${clean}/${id}/${storedName(name, digest)}`;
+            const file = bucket.file(key);
+            const [there] = await file.exists();
+            if (!there)
+                return null;
+            try {
+                await file.makePublic();
+            }
+            catch {
+                // uniform bucket access: already public
+            }
+            return `https://storage.googleapis.com/${bucket.name}/${key}`;
+        },
     };
 }

package/lib/artifacts/index.d.ts

@@ -3,7 +3,7 @@ export { ArtifactMarkdown } from './render.js';
 export { narrationText, narrationTextFromMarkdown, normalizeWord } from './narration.js';
 export { createArtifactStore, newArtifactId, type ArtifactStore, type ArtifactRecord, type SaveResult } from './store.js';
 export { isPublishAuthed } from './auth.js';
-export { createArtifactAssets, contentTypeFor, ASSET_NAME, type ArtifactAssets } from './assets.js';
+export { createArtifactAssets, contentTypeFor, storedName, hashedName, ASSET_NAME, ASSET_DIGEST, type ArtifactAssets } from './assets.js';
 export { isUnlocked, keyHash, unlockCookieName, unlockedUrl } from './unlock.js';
 export { verifyPass, mintPass, verifyGrant, mintGrant, decide, firstName, signInUrl, safeReturnPath, GRANT_COOKIE, ACCESS_LEVELS, type Access, type Reader, type AllowEntry, type Decision } from './reader.js';
 export { createReadersStore, summarize, FLAG_KINDS, type ReadersStore, type FlagKind, type SessionDoc, type FlagDoc } from './readers-store.js';

package/lib/artifacts/index.js

@@ -3,7 +3,7 @@ export { ArtifactMarkdown } from './render.js';
 export { narrationText, narrationTextFromMarkdown, normalizeWord } from './narration.js';
 export { createArtifactStore, newArtifactId } from './store.js';
 export { isPublishAuthed } from './auth.js';
-export { createArtifactAssets, contentTypeFor, ASSET_NAME } from './assets.js';
+export { createArtifactAssets, contentTypeFor, storedName, hashedName, ASSET_NAME, ASSET_DIGEST } from './assets.js';
 export { isUnlocked, keyHash, unlockCookieName, unlockedUrl } from './unlock.js';
 export { verifyPass, mintPass, verifyGrant, mintGrant, decide, firstName, signInUrl, safeReturnPath, GRANT_COOKIE, ACCESS_LEVELS } from './reader.js';
 export { createReadersStore, summarize, FLAG_KINDS } from './readers-store.js';

package/lib/reader/artifact-reader.d.ts

@@ -3,6 +3,9 @@ export type WordTiming = {
     s: number;
     e: number;
 };
+/** The word to light at `now`, or -1. Nothing lights until narration has started: the first
+ *  word begins at 0, so an untouched page would otherwise sit with its first word highlighted. */
+export declare function litWordIndex(words: WordTiming[], now: number, started: boolean): number;
 export declare function ArtifactReader({ src, words, rootId, label, accent, ground, }: {
     src: string;
     words: WordTiming[];

package/lib/reader/artifact-reader.js

@@ -70,6 +70,25 @@ function align(spans, words) {
     }
     return out;
 }
+/** The word to light at `now`, or -1. Nothing lights until narration has started: the first
+ *  word begins at 0, so an untouched page would otherwise sit with its first word highlighted. */
+export function litWordIndex(words, now, started) {
+    if (!started)
+        return -1;
+    let lo = 0;
+    let hi = words.length - 1;
+    let idx = -1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        if (words[mid].s <= now) {
+            idx = mid;
+            lo = mid + 1;
+        }
+        else
+            hi = mid - 1;
+    }
+    return idx >= 0 && now <= words[idx].e + 0.25 ? idx : -1;
+}
 function fmt(t) {
     const m = Math.floor(t / 60);
     const s = Math.floor(t % 60);
@@ -80,6 +99,8 @@ export function ArtifactReader({ src, words, rootId, label, accent, ground, }) {
     const audioRef = useRef(null);
     const mapRef = useRef([]);
     const litRef = useRef(null);
+    // Set on the first play or seek; the highlight stays off until then.
+    const startedRef = useRef(false);
     const [playing, setPlaying] = useState(false);
     const [t, setT] = useState(0);
     const [dur, setDur] = useState(0);
@@ -111,20 +132,8 @@ export function ArtifactReader({ src, words, rootId, label, accent, ground, }) {
         const tick = () => {
             const now = a.currentTime;
             setT(now);
-            // Binary search the word at `now`.
-            let lo = 0;
-            let hi = words.length - 1;
-            let idx = -1;
-            while (lo <= hi) {
-                const mid = (lo + hi) >> 1;
-                if (words[mid].s <= now) {
-                    idx = mid;
-                    lo = mid + 1;
-                }
-                else
-                    hi = mid - 1;
-            }
-            const el = idx >= 0 && now <= words[idx].e + 0.25 ? mapRef.current[idx] : null;
+            const idx = litWordIndex(words, now, startedRef.current);
+            const el = idx >= 0 ? mapRef.current[idx] : null;
             if (el !== litRef.current) {
                 litRef.current?.classList.remove('artifact-word-lit');
                 el?.classList.add('artifact-word-lit');
@@ -154,7 +163,12 @@ export function ArtifactReader({ src, words, rootId, label, accent, ground, }) {
         .artifact-word { border-radius: 3px; transition: background-color 120ms; }
         .artifact-word:hover { background: var(--a-surface-strong, rgba(255,255,255,0.08)); cursor: pointer; }
         .artifact-word-lit { background: color-mix(in srgb, ${accent} 35%, transparent); color: var(--a-strong, #fff); }
-      ` }), _jsx("audio", { ref: audioRef, src: src, preload: "metadata", onPlay: () => setPlaying(true), onPause: () => setPlaying(false), onLoadedMetadata: (e) => setDur(e.target.duration), onRateChange: (e) => setRate(e.target.playbackRate) }), _jsx("div", { className: "fixed inset-x-0 bottom-0 z-40 border-t border-[color:var(--a-line)] backdrop-blur", style: { background: `color-mix(in srgb, ${ground} 90%, transparent)` }, children: _jsxs("div", { className: "mx-auto flex max-w-2xl items-center gap-4 px-6 py-3", children: [_jsx("button", { type: "button", onClick: toggle, "aria-label": playing ? 'Pause narration' : 'Play narration', className: "flex h-11 w-11 shrink-0 items-center justify-center rounded-full", style: { background: accent, color: ground }, children: playing ? (_jsxs("svg", { width: "18", height: "18", viewBox: "0 0 24 24", fill: "currentColor", children: [_jsx("rect", { x: "6", y: "5", width: "4", height: "14" }), _jsx("rect", { x: "14", y: "5", width: "4", height: "14" })] })) : (_jsx("svg", { width: "18", height: "18", viewBox: "0 0 24 24", fill: "currentColor", children: _jsx("path", { d: "M8 5v14l11-7z" }) })) }), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("div", { className: "text-[11px] uppercase tracking-[0.2em]", style: { color: accent }, children: narrator }), _jsx("input", { type: "range", min: 0, max: dur || 0, step: 0.1, value: Math.min(t, dur || 0), onChange: (e) => {
+      ` }), _jsx("audio", { ref: audioRef, src: src, preload: "metadata", onPlay: () => {
+                    startedRef.current = true;
+                    setPlaying(true);
+                }, onSeeking: () => {
+                    startedRef.current = true;
+                }, onPause: () => setPlaying(false), onLoadedMetadata: (e) => setDur(e.target.duration), onRateChange: (e) => setRate(e.target.playbackRate) }), _jsx("div", { className: "fixed inset-x-0 bottom-0 z-40 border-t border-[color:var(--a-line)] backdrop-blur", style: { background: `color-mix(in srgb, ${ground} 90%, transparent)` }, children: _jsxs("div", { className: "mx-auto flex max-w-2xl items-center gap-4 px-6 py-3", children: [_jsx("button", { type: "button", onClick: toggle, "aria-label": playing ? 'Pause narration' : 'Play narration', className: "flex h-11 w-11 shrink-0 items-center justify-center rounded-full", style: { background: accent, color: ground }, children: playing ? (_jsxs("svg", { width: "18", height: "18", viewBox: "0 0 24 24", fill: "currentColor", children: [_jsx("rect", { x: "6", y: "5", width: "4", height: "14" }), _jsx("rect", { x: "14", y: "5", width: "4", height: "14" })] })) : (_jsx("svg", { width: "18", height: "18", viewBox: "0 0 24 24", fill: "currentColor", children: _jsx("path", { d: "M8 5v14l11-7z" }) })) }), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("div", { className: "text-[11px] uppercase tracking-[0.2em]", style: { color: accent }, children: narrator }), _jsx("input", { type: "range", min: 0, max: dur || 0, step: 0.1, value: Math.min(t, dur || 0), onChange: (e) => {
                                         if (audioRef.current)
                                             audioRef.current.currentTime = Number(e.target.value);
                                     }, "aria-label": "Seek", className: "mt-1 w-full", style: { accentColor: accent } })] }), _jsxs("div", { className: "w-16 shrink-0 text-right text-xs tabular-nums text-[color:var(--a-muted)]", children: [fmt(t), " / ", fmt(dur)] }), _jsxs("button", { type: "button", onClick: () => {

package/lib/routes/artifacts.d.ts

@@ -102,6 +102,18 @@ export declare function createArtifactRoutes(config: ArtifactRoutesConfig): {
         name: string;
         url: string;
     }>>;
+    UPLOAD: (request: NextRequest, { params }: {
+        params: Promise<{
+            id: string;
+            name: string;
+        }>;
+    }) => Promise<NextResponse<{
+        error: string;
+    }> | NextResponse<{
+        id: string;
+        name: string;
+        url: string;
+    }>>;
     SHARE_IMAGE: (_request: NextRequest, { params }: Params) => Promise<Response>;
     ENTER: (request: NextRequest) => Promise<NextResponse<unknown>>;
     LEAVE: (request: NextRequest) => Promise<NextResponse<unknown>>;

package/lib/routes/artifacts.js

@@ -9,7 +9,7 @@ import { ArtifactMarkdown } from '../artifacts/render.js';
 import { ArtifactDoor } from '../artifacts/door.js';
 import { isUnlocked, keyHash, unlockCookieName } from '../artifacts/unlock.js';
 import { shapeChanges } from '../artifacts/state.js';
-import { ASSET_NAME, contentTypeFor } from '../artifacts/assets.js';
+import { ASSET_DIGEST, ASSET_NAME, contentTypeFor } from '../artifacts/assets.js';
 import { BrandGround } from '../brand/wrapper.js';
 import { themedPack } from '../brand/theme.js';
 import { showToc, tocOf, TocInline, TocRail } from '../artifacts/toc.js';
@@ -358,6 +358,40 @@ export function createArtifactRoutes(config) {
         const url = await config.assets.put(id, name, bytes, type);
         return NextResponse.json({ id, name, url }, { status: 201 });
     }
+    /**
+     * POST /api/artifacts/<id>/uploads/<name> with `{ digest }`: a signed URL to PUT a big file to
+     * directly, because a route handler cannot take one (Vercel caps a body at 4.5 MB). Then the
+     * same call with `{ digest, done: true }` makes it readable and returns its URL; 409 when the
+     * bytes never arrived. 501 on a host whose assets cannot sign, so the publisher falls back.
+     */
+    async function UPLOAD(request, { params }) {
+        if (!isPublishAuthed(request, config.publishKey()))
+            return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+        const assets = config.assets;
+        if (!assets?.signUpload || !assets.finishUpload)
+            return NextResponse.json({ error: 'this host does not take direct uploads' }, { status: 501 });
+        const { id, name } = await params;
+        if (!ARTIFACT_ID.test(id))
+            return NextResponse.json({ error: `no artifact with id ${id}` }, { status: 404 });
+        if (!(await store.get(id)))
+            return NextResponse.json({ error: `no artifact with id ${id}` }, { status: 404 });
+        if (!ASSET_NAME.test(name))
+            return NextResponse.json({ error: 'asset name must be one path segment: letters, digits, dot, dash, underscore' }, { status: 400 });
+        const type = contentTypeFor(name);
+        if (!type)
+            return NextResponse.json({ error: 'asset type not allowed; use webp, png, jpg, gif, mp3 or json' }, { status: 415 });
+        const body = (await request.json().catch(() => ({})));
+        const digest = typeof body.digest === 'string' ? body.digest : '';
+        if (!ASSET_DIGEST.test(digest))
+            return NextResponse.json({ error: 'digest must be the first 8 hex of the sha256 of the bytes' }, { status: 400 });
+        if (body.done === true) {
+            const url = await assets.finishUpload(id, name, digest);
+            if (!url)
+                return NextResponse.json({ error: 'nothing was uploaded to that url' }, { status: 409 });
+            return NextResponse.json({ id, name, url }, { status: 201 });
+        }
+        return NextResponse.json({ id, name, ...(await assets.signUpload(id, name, digest, type)) }, { status: 201 });
+    }
     /** GET /<id>/share.png: the page's title card. 404 when the pack draws none, so a
      *  tenant on the static default never serves a half-styled card. */
     async function SHARE_IMAGE(_request, { params }) {
@@ -379,5 +413,5 @@ export function createArtifactRoutes(config) {
         revalidatePath(pagePath(id));
         return NextResponse.json({ deleted: true });
     }
-    return { Page, generateMetadata, POST, GET, DELETE, PUT_ASSET, SHARE_IMAGE, ENTER, LEAVE, TRACK, ACK, ACCESS, READS, ...stateRoutes, dynamic: 'force-dynamic', maxDuration: 30 };
+    return { Page, generateMetadata, POST, GET, DELETE, PUT_ASSET, UPLOAD, SHARE_IMAGE, ENTER, LEAVE, TRACK, ACK, ACCESS, READS, ...stateRoutes, dynamic: 'force-dynamic', maxDuration: 30 };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersuit/artifacts",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Publish markdown as branded, read-aloud pages from a Next.js app: the artifacts store, the route factory, the read-along reader, brand packs, password and confidential pages, and share cards.",
   "license": "MIT",
   "type": "module",