@supersuit/artifacts 0.58.1 → 0.58.2

package/CHANGELOG.md

@@ -3,6 +3,32 @@
 `@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.58.2 (2026-11-02)
+
+**A letter's greeting and sign-off keep their own lines.** Markdown joins a soft line break with a
+space, so a letter ending "Your friend in Christ," then the name on a plain newline drew as one
+line. `remarkLetterBreaks` (in `ArtifactMarkdown`'s plugin list) turns a paragraph that opens on a
+short line (40 characters or fewer) ending in a comma into real breaks after each short line in it.
+Hard-wrapped prose still joins.
+
+- DETECTOR: a page whose sign-off reads "Love, Gary" on one line.
+- REMEDY: update; nothing to change in the page.
+- Tests: `src/artifacts/letter-breaks.test.tsx`.
+
+**A host that cannot sign in to its own database says so, instead of a bare 500.** When a host's
+cloud credential is refused (a workload identity provider trusting another Vercel team's OIDC
+issuer, or a revoked service account key), every Firestore call threw and every route answered an
+empty 500. Publishers saw "500, no message", and the Supersuit comments client guessed "a missing
+index" (2026-10-28, after a hub's Vercel project moved teams). Every route handler in
+`createArtifactRoutes` now answers that one cause with `503 { error: "backend-auth", message }`. The
+cause itself is logged on the server and kept out of the body. Any other error is unchanged.
+
+- DETECTOR: the server log shows `invalid_grant`, `Getting metadata from plugin failed`,
+  `UNAUTHENTICATED` or `Could not load the default credentials`; clients now get a typed 503.
+- REMEDY: fix the host's credential. For Vercel workload identity, point the provider's issuer at
+  `https://oidc.vercel.com/<team>` and its audience at `https://vercel.com/<team>`.
+- Tests: `src/routes/backend-auth.test.tsx`.
+
 ## 0.58.1 (2026-10-27)
 
 **The no-link door on a per-reader page offers sign-in.** A signed-in owner or hub admin already got

package/lib/artifacts/letter-breaks.d.ts

@@ -0,0 +1,2 @@
+import type { Root } from 'mdast';
+export declare function remarkLetterBreaks(): (tree: Root) => void;

package/lib/artifacts/letter-breaks.js

@@ -0,0 +1,68 @@
+const SHORT = 40;
+const isParent = (n) => !!n && Array.isArray(n.children);
+/** The paragraph's text as the writer typed it, soft breaks included. */
+function plain(nodes) {
+    return nodes.map((n) => {
+        const x = n;
+        if (x.type === 'text' || x.type === 'inlineCode')
+            return x.value ?? '';
+        if (x.type === 'break')
+            return '\n';
+        return x.children ? plain(x.children) : '';
+    }).join('');
+}
+function breakLetter(p) {
+    const lines = plain(p.children).split('\n');
+    if (lines.length < 2)
+        return;
+    const short = (l) => l.trim().length <= SHORT;
+    if (!short(lines[0]) || !/,$/.test(lines[0].trim()))
+        return;
+    let line = 0;
+    const walk = (parent) => {
+        const out = [];
+        for (const child of parent.children) {
+            const c = child;
+            if (c.type === 'text') {
+                const parts = c.value.split('\n');
+                parts.forEach((part, k) => {
+                    if (k > 0) {
+                        const keep = short(lines[line]);
+                        line++;
+                        if (keep) {
+                            out.push({ type: 'break' });
+                            part = part.replace(/^\s+/, '');
+                        }
+                        else
+                            part = ' ' + part.replace(/^\s+/, '');
+                    }
+                    if (part)
+                        out.push({ type: 'text', value: part });
+                });
+                continue;
+            }
+            if (c.type === 'break')
+                line++;
+            else if (isParent(c))
+                walk(c);
+            out.push(c);
+        }
+        parent.children = out;
+    };
+    walk(p);
+}
+export function remarkLetterBreaks() {
+    return (tree) => {
+        const visit = (n) => {
+            if (!isParent(n))
+                return;
+            for (const c of n.children) {
+                if (c.type === 'paragraph')
+                    breakLetter(c);
+                else
+                    visit(c);
+            }
+        };
+        visit(tree);
+    };
+}

package/lib/artifacts/render.js

@@ -23,6 +23,7 @@ import { VideoAutoplay } from '../reader/video-autoplay.js';
 import { CodeCopy } from '../reader/code-copy.js';
 import { DefinitionLayer } from '../reader/definition-layer.js';
 import { remarkDefinitions } from './definitions.js';
+import { remarkLetterBreaks } from './letter-breaks.js';
 import { AUDIO_SRC, remarkVoiceNotes, TRANSCRIPT_LANG } from './voice-note.js';
 import { VoiceNote } from '../widgets/voice-note.js';
 // Every colour is a theme variable (brand/theme.ts), so a page follows its light, dark or system mode.
@@ -371,7 +372,7 @@ export function ArtifactMarkdown({ markdown, notes, checklist, definitions, Sect
     // Voice notes first, so a section groups the note node the pair became.
     const voiceNotes = [];
     const voiced = /^ {0,3}(`{3,}|~{3,})\s*transcript\b/m.test(markdown);
-    const plugins = [remarkGfm, ...(voiced ? [remarkVoiceNotes(voiceNotes)] : []), ...(defined ? [remarkDefinitions(defined)] : []), ...(outline.length ? [remarkSections(outline[0].depth)] : [])];
+    const plugins = [remarkGfm, remarkLetterBreaks, ...(voiced ? [remarkVoiceNotes(voiceNotes)] : []), ...(defined ? [remarkDefinitions(defined)] : []), ...(outline.length ? [remarkSections(outline[0].depth)] : [])];
     const lists = /^ {0,3}(`{3,}|~{3,})\s*checklist\b/m.test(markdown) ? checklistsOf(markdown) : null;
     const checklists = lists
         // `send` from the host means it keeps answers and the page declared the `checklist` slot; on a

package/lib/routes/artifacts.js

@@ -40,6 +40,7 @@ import { PageAnalytics } from '../reader/page-analytics.js';
 import { analyticsPlan } from '../reader/analytics-plan.js';
 import { createPersonalRoutes } from './personal-routes.js';
 import { createVoiceRoutes } from './voice-routes.js';
+import { guardRouteTable } from './backend-auth.js';
 /** Ids are 8 chars from the safe alphabet; anything else is not a page and never reaches the store. */
 export const ARTIFACT_ID = ARTIFACT_ID_RE;
 /** A version number as it appears in a URL: no zero, no leading zero, so each version has one address. */
@@ -1124,5 +1125,5 @@ export function createArtifactRoutes(config) {
             + `<p data-per-reader-shut style="max-width:36rem;padding:0 1.5rem;text-align:center;font-size:1.125rem;opacity:.8">${UNAVAILABLE}</p></body></html>`;
         return new Response(html, { status: 410, headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'x-robots-tag': 'noindex, nofollow' } });
     }
-    return { Page, generateMetadata, VersionPage, generateVersionMetadata, VERSIONS, POST, GET, DELETE, LIST, shutPageResponse, PUT_ASSET, UPLOAD, SHARE_IMAGE, ENTER, LEAVE, TRACK, ACK, ACCESS, SETTINGS, READS, sweepReaders, TRANSCRIBE: voiceRoutes.TRANSCRIBE, ...stateRoutes, ...personalRoutes, ...recipientsRoutes, dynamic: 'force-dynamic', maxDuration: 30 };
+    return guardRouteTable({ Page, generateMetadata, VersionPage, generateVersionMetadata, VERSIONS, POST, GET, DELETE, LIST, shutPageResponse, PUT_ASSET, UPLOAD, SHARE_IMAGE, ENTER, LEAVE, TRACK, ACK, ACCESS, SETTINGS, READS, sweepReaders, TRANSCRIBE: voiceRoutes.TRANSCRIBE, ...stateRoutes, ...personalRoutes, ...recipientsRoutes, dynamic: 'force-dynamic', maxDuration: 30 });
 }

package/lib/routes/backend-auth.d.ts

@@ -0,0 +1,9 @@
+import { NextResponse } from 'next/server';
+/** True when an error is the host failing to authenticate to its own backend. */
+export declare function isBackendAuthError(e: unknown): boolean;
+export declare const BACKEND_AUTH_MESSAGE = "This host could not sign in to its database, so nothing was read or saved. Its owner should check the host's cloud credentials (the workload identity provider's issuer and audience, or the service account key).";
+export declare function backendAuthResponse(): NextResponse;
+/** Wrap a route handler so a backend credential failure answers the typed 503. */
+export declare function guardBackendAuth<A extends unknown[], R>(handler: (...args: A) => R | Promise<R>): (...args: A) => Promise<R | NextResponse>;
+/** Every route handler in a route table (its UPPER_CASE functions) gets the guard. */
+export declare function guardRouteTable<T extends Record<string, unknown>>(table: T): T;

package/lib/routes/backend-auth.js

@@ -0,0 +1,42 @@
+// A host whose cloud credential is refused (a workload identity provider trusting another
+// issuer, a revoked or missing service account key) fails every Firestore call. Unhandled, each
+// route then answers a bare 500 that a publisher reads as "something broke" and a client hint
+// can only guess at (on 2026-10-28 it guessed "a missing index"). This turns that one cause into
+// a typed 503 the publisher can name, and leaves every other error exactly as it was.
+import { NextResponse } from 'next/server';
+const AUTH_MESSAGE = /invalid_grant|Getting metadata from plugin failed|Could not load the default credentials|UNAUTHENTICATED|Request had invalid authentication credentials/i;
+/** True when an error is the host failing to authenticate to its own backend. */
+export function isBackendAuthError(e) {
+    if (!(e instanceof Error))
+        return false;
+    if (e.code === 16)
+        return true; // gRPC UNAUTHENTICATED
+    return AUTH_MESSAGE.test(e.message);
+}
+export const BACKEND_AUTH_MESSAGE = "This host could not sign in to its database, so nothing was read or saved. Its owner should check the host's cloud credentials (the workload identity provider's issuer and audience, or the service account key).";
+export function backendAuthResponse() {
+    return NextResponse.json({ error: 'backend-auth', message: BACKEND_AUTH_MESSAGE }, { status: 503, headers: { 'cache-control': 'no-store' } });
+}
+/** Wrap a route handler so a backend credential failure answers the typed 503. */
+export function guardBackendAuth(handler) {
+    return async (...args) => {
+        try {
+            return await handler(...args);
+        }
+        catch (e) {
+            if (!isBackendAuthError(e))
+                throw e;
+            console.error('[artifacts] backend credential refused:', e);
+            return backendAuthResponse();
+        }
+    };
+}
+/** Every route handler in a route table (its UPPER_CASE functions) gets the guard. */
+export function guardRouteTable(table) {
+    const out = { ...table };
+    for (const [k, v] of Object.entries(table)) {
+        if (typeof v === 'function' && /^[A-Z][A-Z0-9_]*$/.test(k))
+            out[k] = guardBackendAuth(v);
+    }
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersuit/artifacts",
-  "version": "0.58.1",
+  "version": "0.58.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",