@supersuit/artifacts 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+`@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.1.0 (2026-09-24)
+
+**The site shell behind Freedom's `artifacts.<name>` pages, published as a package.** It was a
+private workspace package (`@freedom/site-shell`) inside the one deployment that serves every
+operator's pages; it now ships from its own public repository so a fix is one release that every
+host picks up, and anyone can file one.
+
+- Everything the host had: the Firestore artifact store with version history, the route factory
+  (`createArtifactRoutes`), the read-along reader, brand packs with `freedomDefault`, password
+  pages, confidential pages (`access: freedom | invite`) with the readers store, the agreement,
+  the watermark and the read record, and the share card.
+- **Compiled ESM with declarations** (`lib/`), so a host no longer needs `transpilePackages`.
+  Relative imports carry `.js`; `next/*` imports deliberately do NOT. `next/navigation.js` skips
+  the alias Next applies per layer, and every route handler then fails to build on a missing
+  app-router context module. Plain Node ESM cannot resolve the extensionless form, so a host's
+  Vitest inlines the package (README).
+- **No sign-in service is assumed.** `signInOrigin` used to default to one company's sign-in
+  host. It now has no default, and a confidential page on a host that sets none shows its door
+  with no way through: it fails closed rather than sending readers somewhere the host never named.
+- **The share-card font ships in the tarball** at `fonts/Newsreader-600.ttf` and is found from a
+  host's `node_modules`, where it used to be read from the host's own source tree. Next's tracer
+  does not follow it there, so a host names it in `outputFileTracingIncludes` under a key that is
+  a glob (`'/*/share.png'`; `'/[id]/share.png'` is a character class and matches nothing).
+- **DETECTOR:** a host importing `@freedom/site-shell` is on the pre-package copy.
+- **REMEDY:** depend on `@supersuit/artifacts`, rename the imports, drop the package from
+  `transpilePackages`, point Tailwind `content` and any `outputFileTracingIncludes` for the font
+  at `node_modules/@supersuit/artifacts/`, inline the package in Vitest, and pass `signInOrigin`
+  explicitly if the host serves confidential pages.
+- 92 tests, including one for the fail-closed door, plus `npm run test:packed`, which packs the
+  tarball into a small Next.js app (`test/fixture`), builds it, checks the share route's trace
+  carries the font, then serves it and fetches a page, a share card and the publish route. It was
+  verified to fail on a `next/navigation.js` import and on a tarball without `fonts/`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Supersuit Up
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,206 @@
+# @supersuit/artifacts
+
+Publish a markdown file, get a branded page at a short link. `@supersuit/artifacts` is the whole
+site shell behind that: the store, the route handlers, the read-along reader, brand packs,
+password pages, confidential pages with a signed-in reader list, and the share card a link
+unfurls as. You mount it in a Next.js App Router app with a handful of one-line route files.
+
+It is the shell that serves every Freedom operator's `artifacts.<theirname>` page, published
+openly because none of it is secret and all of it is better with more eyes on it.
+
+```bash
+npm install @supersuit/artifacts
+```
+
+Peers: `next >= 16`, `react >= 19`, `react-dom >= 19`, `firebase-admin >= 13` (the store is
+Firestore), and optionally `@google-cloud/storage >= 7` for uploaded files.
+
+## What you get
+
+| Export | What it is |
+|---|---|
+| `createArtifactRoutes(config)` | Every route handler: the page, its metadata, the publish API, the share card, the reader sign-in exchange, access control |
+| `createArtifactStore(db, path)` | Firestore store for pages and their version history, under any collection path |
+| `createReadersStore(db, path)` | The record for confidential pages: allowlist, agreements, reading sessions, flags |
+| `createArtifactAssets(bucket, prefix)` | Uploaded images for a page, in a Cloud Storage bucket |
+| `freedomDefault`, `BrandPack` | The default look and the type any other look implements |
+| `BrandGround`, `BrandMark` | The pack's page backdrop and mark, for your own pages (a home, a 404) |
+| `parseArtifactSource` | The front-matter contract, as a parser you can call before publishing |
+| `mintPass`, `verifyPass` | The reader pass, for the sign-in side (see below) |
+| `ARTIFACT_PUBLIC_PREFIXES` (`/gate`) | Paths to leave open if you mount artifacts inside a gated site |
+
+Subpath imports: `@supersuit/artifacts/artifacts`, `/routes`, `/brand`, `/reader`, `/gate`.
+The package ships compiled ESM with type declarations; no `transpilePackages` needed.
+
+## Mount it in a Next.js app
+
+One module builds the routes; every route file is a one-line delegation.
+
+```ts
+// src/lib/artifacts.ts
+import { createArtifactRoutes, createArtifactStore, createArtifactAssets, createReadersStore, freedomDefault } from '@supersuit/artifacts'
+import { getFirestore } from 'firebase-admin/firestore'
+import { getStorage } from 'firebase-admin/storage'
+
+export const artifacts = createArtifactRoutes({
+  store: createArtifactStore(getFirestore(), 'artifacts'),
+  assets: createArtifactAssets(getStorage().bucket(), 'artifacts'),   // optional
+  brand: { ...freedomDefault, kicker: 'A page from Sam Rivera' },
+  siteUrl: 'https://artifacts.example.com',
+  publishKey: () => process.env.ARTIFACTS_PUBLISH_KEY,
+  // Only for confidential pages (access:). Leave all three out and such a page stays shut.
+  readers: createReadersStore(getFirestore(), 'artifact'),
+  readerSecret: () => process.env.ARTIFACT_PASS_SECRET,
+  signInOrigin: 'https://accounts.example.com',
+})
+```
+
+```tsx
+// app/[id]/page.tsx
+import { artifacts } from '@/lib/artifacts'
+export const dynamic = 'force-dynamic'
+export const generateMetadata = artifacts.generateMetadata
+export default artifacts.Page
+```
+
+The rest, each exporting the named handler(s) from `artifacts`:
+
+| File | Handlers |
+|---|---|
+| `app/[id]/share.png/route.tsx` | `GET` = `SHARE_IMAGE` |
+| `app/api/artifacts/route.ts` | `POST` (publish) |
+| `app/api/artifacts/[id]/route.ts` | `GET`, `DELETE` |
+| `app/api/artifacts/[id]/assets/[name]/route.ts` | `PUT` = `PUT_ASSET` |
+| `app/api/artifacts/[id]/access/route.ts` | `GET`, `POST` = `ACCESS` |
+| `app/api/artifacts/[id]/reads/route.ts` | `GET` = `READS` |
+| `app/api/reader/enter/route.ts` | `GET` = `ENTER` |
+| `app/api/reader/leave/route.ts` | `GET` = `LEAVE` |
+| `app/api/reader/ack/route.ts` | `POST` = `ACK` |
+| `app/api/reader/track/route.ts` | `POST` = `TRACK` |
+
+Pages live at `/<id>` by default. Mounting inside a larger site, pass `pagePrefix: '/a/'` and put
+the page at `app/a/[id]/`. One deployment can serve many sites: build one set of routes per
+hostname and pick by the `host` header.
+
+### Three things your build config must know
+
+- **Tailwind**: the shell's markup uses Tailwind classes, so add the package to `content`:
+  `'./node_modules/@supersuit/artifacts/lib/**/*.js'`.
+- **The share-card font** ships at `node_modules/@supersuit/artifacts/fonts/` and is read from
+  `process.cwd()` at request time. Next's file tracer does not follow that path into
+  `node_modules`, so tell it, or the default pack's share card has no font in production:
+
+  ```ts
+  // next.config.ts
+  outputFileTracingIncludes: { '/*/share.png': ['./node_modules/@supersuit/artifacts/fonts/**'] },
+  ```
+
+  The key is a glob. `'/[id]/share.png'` reads as a character class and matches nothing, silently.
+- **Vitest** (or anything running the shell under plain Node ESM): the shell imports
+  `next/navigation`, `next/server` and friends without a file extension, because that is the
+  form Next's bundler aliases per layer (with `.js` every route handler fails to build). Plain
+  Node cannot resolve that form, so let Vite resolve the package instead:
+  `test: { server: { deps: { inline: ['@supersuit/artifacts'] } } }`.
+
+## Publishing a page
+
+`POST /api/artifacts` with `Authorization: Bearer <publish key>` and the markdown file as the
+body. The response carries the page's id and URL. Posting a file whose front matter carries
+that `id:` republishes it in place, keeping every earlier version.
+
+## Front matter
+
+```markdown
+---
+title: The Plan for Q4
+subtitle: What we are doing and why
+summary: Three bets, what each costs, and what we stop doing to afford them.
+---
+```
+
+| Key | Meaning |
+|---|---|
+| `title` (required) | The large line, and the unfurl title |
+| `summary` (required) | The italic teaser under it, and the unfurl description |
+| `subtitle` | A line between the two. A republish without it removes it |
+| `id` | Republish in place instead of minting a new page |
+| `cover` | An image URL (absolute or site-relative) used as the unfurl image instead of the share card |
+| `audience` | Free text stored with the page |
+| `voice`, `narration`, `timings`, `narrationHash` | Read-aloud: the audio and word timings a publisher generated. Absent, no player |
+| `password` | Shuts the body behind a door (below) |
+| `access` | `freedom`, `invite` or `public`: a confidential page (below) |
+| `template` | `document`, the only one so far |
+
+An unknown key is refused, so a typo fails loudly instead of being ignored.
+
+## A page with a password
+
+`password: <string>` shuts the body behind a door. The title, summary and unfurl stay, so the
+link still reads as itself in a thread. It opens on `?key=<password>` in the URL, or on the
+cookie that first open sets, which holds a hash bound to the page id: it names no password and
+opens no other page. Republishing without the line takes the door down.
+
+## A confidential page (`access:`)
+
+`access: freedom` opens the page only to a signed-in reader with an active Freedom account or
+on the page's list; `access: invite` opens it only to the list. Everyone else gets the title,
+the summary and a sign-in door; the body never reaches them.
+
+**The level is host-side state.** A republish that omits `access:` leaves it as it was; only
+`access: public` (or `POST /api/artifacts/<id>/access` with `{"access":"public"}`) opens the page
+again, so a publisher that strips keys can never reopen a confidential page by accident.
+
+The list lives in the readers store, never in the file, so addresses stay out of content and
+changing it needs no republish: `POST /api/artifacts/<id>/access` with
+`{"add":[{"email":"...","name":"...","reason":"..."}],"remove":["..."]}` and the publish key.
+`GET /api/artifacts/<id>/reads` returns who read it, for how long, and what they tried.
+
+An allowed reader agrees to a short confidentiality statement before the body renders, once per
+page; the wording is stored with their address and the time. The page then greets them by first
+name, says why they can read it, tiles their address as a faint watermark, and records reading
+time, scroll depth, and attempts to print, copy at length, or save. Refused sign-ins are
+recorded too, which is how a forwarded link shows up.
+
+### The reader pass (the contract with your sign-in side)
+
+This package does not sign anyone in. It sends readers to your sign-in authority and trusts a
+signed pass coming back:
+
+1. A signed-out reader is sent to `<signInOrigin>/artifact/sign-in?to=<page URL>`.
+2. Your side authenticates them and redirects to `<page origin>/api/reader/enter?pass=<pass>&to=/<id>`.
+3. `ENTER` verifies the pass, sets a week-long HttpOnly grant cookie, and lands them on the page.
+
+The pass is `a1.<payload>.<sig>`: `payload` is the base64url of
+`{"u": uid, "e": email, "n": name|null, "m": isMember, "x": expiry-unix-seconds}`, and `sig` is
+the first 32 hex characters of `HMAC-SHA256(ARTIFACT_PASS_SECRET, "artifact-pass:a1.<payload>")`.
+`mintPass(secret, reader, exp)` builds one, so a Node sign-in side can import it rather than
+reimplement it. Keep passes short-lived (five minutes is what the tests assume).
+
+Without `signInOrigin`, a confidential page shows its door with no way through. It fails
+closed, never open.
+
+## Brand packs
+
+A `BrandPack` is data plus at most two components: colours, type, the kicker line above a title,
+the narrator label, an optional full-page `Wrapper` and `Mark`, and an optional `share` block
+(a font loader and a backdrop) that draws the unfurl card. `freedomDefault` is the default look.
+Keep a pack carrying your own trademark in your own app, not in a pull request here.
+
+## Environment
+
+| Variable | Used for |
+|---|---|
+| your publish key (named by you, read in `publishKey`) | Authorises publish, delete and access changes |
+| `ARTIFACT_PASS_SECRET` (named by you, read in `readerSecret`) | Verifies reader passes and signs grants; shared with your sign-in side |
+| Firebase Admin credentials | The store and readers store |
+
+## Contributing
+
+Fixes and improvements are welcome: open an issue or a pull request at
+[SupersuitUp/artifacts](https://github.com/SupersuitUp/artifacts). `npm test` runs the suite,
+`npm run build` compiles, and `npm run test:packed` builds and serves a small Next.js app from
+the packed tarball. A behaviour change comes with its test in the same pull request.
+
+## License
+
+MIT

package/lib/artifacts/assets.d.ts

@@ -0,0 +1,27 @@
+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>;
+}
+/** Names are one path segment: letters, digits, dot, dash, underscore. */
+export declare const ASSET_NAME: RegExp;
+export declare const ASSET_TYPES: Record<string, string>;
+export declare function contentTypeFor(name: string): string | undefined;
+/**
+ * The stored name carries a hash of the bytes: `21-the-fork.9f3c1a22.png`.
+ *
+ * WITHOUT THIS, `immutable` IS A LIE AND THE READER PAYS FOR IT. Assets are served
+ * `public, max-age=31536000, immutable`, which instructs every browser and cache never to
+ * revalidate for a year, and republishing an artifact overwrote the object under the SAME
+ * filename. So a reader who opened a page once kept the first version they ever loaded,
+ * permanently, while the publisher's own `curl` fetched fresh bytes and reported everything fine.
+ * Measured 2026-09-23: an operator kept seeing a retired diagram on his phone after four
+ * republishes, and every check from this machine said the host was correct. It was. His copy was
+ * the one nobody could see.
+ *
+ * Hashing the bytes into the name is what `immutable` is designed for: changed bytes get a new
+ * URL, so nothing has to be invalidated and nothing can go stale. Unchanged bytes keep the same
+ * URL and stay cached, which is the whole benefit.
+ */
+export declare function hashedName(name: string, bytes: Buffer): string;
+export declare function createArtifactAssets(bucket: Bucket, prefix: string): ArtifactAssets;

package/lib/artifacts/assets.js

@@ -0,0 +1,63 @@
+// Where an artifact's files live (cover, images, narration audio and timings). The shell
+// only knows the interface; the instance hands in a bucket. Before this existed the
+// 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';
+/** 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 = {
+    webp: 'image/webp',
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    mp3: 'audio/mpeg',
+    json: 'application/json',
+};
+export function contentTypeFor(name) {
+    const ext = name.split('.').pop()?.toLowerCase() ?? '';
+    return ASSET_TYPES[ext];
+}
+/**
+ * The stored name carries a hash of the bytes: `21-the-fork.9f3c1a22.png`.
+ *
+ * WITHOUT THIS, `immutable` IS A LIE AND THE READER PAYS FOR IT. Assets are served
+ * `public, max-age=31536000, immutable`, which instructs every browser and cache never to
+ * revalidate for a year, and republishing an artifact overwrote the object under the SAME
+ * filename. So a reader who opened a page once kept the first version they ever loaded,
+ * permanently, while the publisher's own `curl` fetched fresh bytes and reported everything fine.
+ * Measured 2026-09-23: an operator kept seeing a retired diagram on his phone after four
+ * republishes, and every check from this machine said the host was correct. It was. His copy was
+ * the one nobody could see.
+ *
+ * Hashing the bytes into the name is what `immutable` is designed for: changed bytes get a new
+ * URL, so nothing has to be invalidated and nothing can go stale. Unchanged bytes keep the same
+ * 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);
+    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)}`;
+}
+export function createArtifactAssets(bucket, prefix) {
+    const clean = prefix.replace(/^\/+|\/+$/g, '');
+    return {
+        async put(id, name, bytes, contentType) {
+            const key = `${clean}/${id}/${hashedName(name, bytes)}`;
+            const file = bucket.file(key);
+            await file.save(bytes, {
+                contentType,
+                resumable: false,
+                metadata: { cacheControl: 'public, max-age=31536000, immutable' },
+            });
+            try {
+                await file.makePublic();
+            }
+            catch {
+                // A bucket with uniform public access has nothing to make public; the URL below still serves.
+            }
+            return `https://storage.googleapis.com/${bucket.name}/${key}`;
+        },
+    };
+}

package/lib/artifacts/auth.d.ts

@@ -0,0 +1 @@
+export declare function isPublishAuthed(request: Request, key: string | undefined): boolean;

package/lib/artifacts/auth.js

@@ -0,0 +1,8 @@
+// One publish key per instance. The site gate lets the artifacts API through precisely
+// because this header is the whole authorization.
+export function isPublishAuthed(request, key) {
+    if (!key)
+        return false;
+    const h = request.headers.get('authorization') ?? '';
+    return h === `Bearer ${key}`;
+}

package/lib/artifacts/confidential.d.ts

@@ -0,0 +1,47 @@
+import type { BrandPack } from '../brand/pack.js';
+import type { Reader } from './reader.js';
+export declare function bannerLines({ name, email, reason, owner }: {
+    name: string | null;
+    email: string;
+    reason: string;
+    owner: string;
+}): {
+    lead: string;
+    why: string;
+    rule: string;
+    record: string;
+};
+export declare function ConfidentialBanner(props: {
+    name: string | null;
+    email: string;
+    reason: string;
+    owner: string;
+    brand: BrandPack;
+    signOutUrl: string;
+}): import("react").JSX.Element;
+/** A tiled, rotated, near-invisible line of the reader's address over the whole page. */
+export declare function Watermark({ email }: {
+    email: string;
+}): import("react").JSX.Element;
+/** Printing shows this and nothing else, whichever way the print dialog was reached. */
+export declare const NO_PRINT_CSS = "@media print { body * { visibility: hidden !important; } body::after { content: \"This page is confidential and cannot be printed.\"; visibility: visible; position: fixed; top: 40%; left: 0; right: 0; text-align: center; font: 16px sans-serif; color: #000; } }";
+export declare function SignInDoor({ brand, href }: {
+    brand: BrandPack;
+    href?: string;
+}): import("react").JSX.Element;
+export declare function NotAllowedDoor({ brand, reader, signOutUrl }: {
+    brand: BrandPack;
+    reader: Reader;
+    signOutUrl: string;
+}): import("react").JSX.Element;
+/** The agreement a reader makes before a confidential page opens. The exact string is stored
+ *  with their acknowledgement, so the record says what they agreed to, not what it says today. */
+export declare function ackText(owner: string): string;
+export declare function AckDoor({ brand, name, email, owner, pageId, signOutUrl }: {
+    brand: BrandPack;
+    name: string | null;
+    email: string;
+    owner: string;
+    pageId: string;
+    signOutUrl: string;
+}): import("react").JSX.Element;

package/lib/artifacts/confidential.js

@@ -0,0 +1,39 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export function bannerLines({ name, email, reason, owner }) {
+    return {
+        lead: `${name ? `${name}, this` : 'This'} is confidential.`,
+        why: `You are reading it because ${reason}.`,
+        rule: `It is for you alone. Do not share, forward, copy, screenshot, print, or download it, or discuss its contents with anyone ${owner} has not given access.`,
+        record: `Your reading is recorded under ${email}.`,
+    };
+}
+export function ConfidentialBanner(props) {
+    const l = bannerLines(props);
+    return (_jsxs("aside", { "data-nospeak": true, className: "mx-auto max-w-2xl rounded-xl border px-5 py-4 text-sm leading-relaxed", style: { borderColor: props.brand.accent, color: props.brand.ink }, children: [_jsx("p", { className: "font-semibold", style: { color: props.brand.accent }, children: l.lead }), _jsxs("p", { className: "mt-1", children: [l.why, " ", l.rule] }), _jsxs("p", { className: "mt-2 text-xs opacity-60", children: [l.record, " Not you? ", _jsx("a", { href: props.signOutUrl, className: "underline", children: "Sign out" }), "."] })] }));
+}
+/** A tiled, rotated, near-invisible line of the reader's address over the whole page. */
+export function Watermark({ email }) {
+    const text = `${email} · confidential`.replace(/[<>&"']/g, '');
+    const svg = `<svg xmlns='http://www.w3.org/2000/svg' width='420' height='220'><text x='10' y='120' transform='rotate(-24 210 110)' font-family='sans-serif' font-size='14' fill='rgba(128,128,128,0.10)'>${text}</text></svg>`;
+    return (_jsx("div", { "aria-hidden": true, "data-nospeak": true, className: "pointer-events-none fixed inset-0 z-40", style: { backgroundImage: `url("data:image/svg+xml;utf8,${encodeURIComponent(svg)}")` } }));
+}
+/** Printing shows this and nothing else, whichever way the print dialog was reached. */
+export const NO_PRINT_CSS = `@media print { body * { visibility: hidden !important; } body::after { content: "This page is confidential and cannot be printed."; visibility: visible; position: fixed; top: 40%; left: 0; right: 0; text-align: center; font: 16px sans-serif; color: #000; } }`;
+export function SignInDoor({ brand, href }) {
+    // No href means the host configured no sign-in authority: the door stays, with no way through.
+    if (!href) {
+        return (_jsx("div", { "data-nospeak": true, className: "mx-auto max-w-sm px-6 pb-24 text-center", children: _jsx("p", { className: "text-sm opacity-70", children: "This page is confidential, and this site cannot sign readers in yet." }) }));
+    }
+    return (_jsxs("div", { "data-nospeak": true, className: "mx-auto max-w-sm px-6 pb-24 text-center", children: [_jsx("p", { className: "text-sm opacity-70", children: "This page is confidential. Sign in with the Google account your Freedom account uses, or the address it was shared with." }), _jsx("a", { href: href, className: "mt-5 inline-block rounded-lg px-5 py-2 text-sm font-medium", style: { background: brand.accent, color: brand.ground }, children: "Sign in to read" })] }));
+}
+export function NotAllowedDoor({ brand, reader, signOutUrl }) {
+    return (_jsxs("div", { "data-nospeak": true, className: "mx-auto max-w-sm px-6 pb-24 text-center text-sm", children: [_jsxs("p", { className: "opacity-80", children: ["You are signed in as ", reader.email, ", and this page has not been shared with that address. If it was sent to a different address of yours, sign out and use that one."] }), _jsx("p", { className: "mt-3 opacity-60", children: "This attempt was recorded." }), _jsx("a", { href: signOutUrl, className: "mt-5 inline-block underline", style: { color: brand.accent }, children: "Sign out" })] }));
+}
+/** The agreement a reader makes before a confidential page opens. The exact string is stored
+ *  with their acknowledgement, so the record says what they agreed to, not what it says today. */
+export function ackText(owner) {
+    return `I understand this document is confidential. I will not share, forward, copy, screenshot, print, or download it, or discuss its contents with anyone ${owner} has not given access. I understand that my reading is recorded.`;
+}
+export function AckDoor({ brand, name, email, owner, pageId, signOutUrl }) {
+    return (_jsxs("form", { method: "post", action: "/api/reader/ack", "data-nospeak": true, className: "mx-auto max-w-md px-6 pb-24 text-left text-sm", children: [_jsx("input", { type: "hidden", name: "id", value: pageId }), _jsxs("div", { className: "rounded-xl border px-5 py-5", style: { borderColor: brand.accent }, children: [_jsx("p", { className: "font-semibold", style: { color: brand.accent }, children: name ? `${name}, before you read` : 'Before you read' }), _jsx("p", { className: "mt-3 leading-relaxed", children: ackText(owner) }), _jsxs("label", { className: "mt-4 flex items-start gap-3", children: [_jsx("input", { type: "checkbox", name: "agree", value: "yes", required: true, className: "mt-1" }), _jsx("span", { children: "I agree to keep it confidential." })] }), _jsx("button", { type: "submit", className: "mt-5 w-full rounded-lg px-5 py-2 text-sm font-medium", style: { background: brand.accent, color: brand.ground }, children: "Agree and open" }), _jsxs("p", { className: "mt-3 text-xs opacity-60", children: ["Signed in as ", email, ". Your agreement is recorded with the time. Not you? ", _jsx("a", { href: signOutUrl, className: "underline", children: "Sign out" }), "."] })] })] }));
+}

package/lib/artifacts/door.d.ts

@@ -0,0 +1,5 @@
+import type { BrandPack } from '../brand/pack.js';
+export declare function ArtifactDoor({ brand, wrongKey }: {
+    brand: BrandPack;
+    wrongKey: boolean;
+}): import("react").JSX.Element;

package/lib/artifacts/door.js

@@ -0,0 +1,4 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export function ArtifactDoor({ brand, wrongKey }) {
+    return (_jsxs("form", { method: "get", "data-nospeak": true, className: "mx-auto max-w-sm px-6 pb-24 text-center", children: [_jsx("label", { htmlFor: "artifact-key", className: "block text-sm opacity-70", children: "This page is for the people it was written for. Enter the key you were given." }), _jsx("input", { id: "artifact-key", name: "key", type: "password", autoComplete: "off", autoFocus: true, className: "mt-4 w-full rounded-lg border px-4 py-3 text-center text-base outline-none", style: { borderColor: brand.accent, background: 'transparent', color: brand.ink } }), wrongKey ? (_jsx("p", { className: "mt-3 text-sm", style: { color: brand.accent }, children: "That key did not open it." })) : null, _jsx("button", { type: "submit", className: "mt-4 rounded-lg px-5 py-2 text-sm font-medium", style: { background: brand.accent, color: brand.ground }, children: "Open" })] }));
+}

package/lib/artifacts/front-matter.d.ts

@@ -0,0 +1,34 @@
+import { type Access } from './reader.js';
+export type ArtifactMeta = {
+    title: string;
+    summary: string;
+    template: 'document';
+    /** A line under the title. Title, subtitle and summary are three separate fields; the summary
+     *  is the teaser, and the unfurl carries the title and the summary. */
+    subtitle?: string;
+    audience?: string;
+    cover?: string;
+    id?: string;
+    /** Narrator to generate with (a voice id the host's publisher knows). The publisher acts on it; the API stores it. */
+    voice?: string;
+    /** Bucket URLs written by the publisher after narration; absent means no player. */
+    narration?: string;
+    timings?: string;
+    /** Hash of the narrated text, so a changed body is re-narrated and an unchanged one is not. */
+    narrationHash?: string;
+    /** Shut the page behind this until `?key=<password>` or the cookie it sets. Never rendered. */
+    password?: string;
+    /** Who may read it, checked against a signed-in reader: `invite` is the host-side allowlist
+     *  only; `freedom` is any active Freedom account plus that list; `public` opens it again.
+     *  ABSENT CHANGES NOTHING: the level is host-side state, so a republish that omits the line
+     *  (or a publisher that strips unknown keys) can never reopen a confidential page. */
+    access?: Access | 'public';
+};
+export declare function parseArtifactSource(text: string): {
+    ok: true;
+    meta: ArtifactMeta;
+    body: string;
+} | {
+    ok: false;
+    error: string;
+};

package/lib/artifacts/front-matter.js

@@ -0,0 +1,37 @@
+// The artifact contract: markdown plus a small front matter.
+// Documented in README, "Front matter".
+import matter from 'gray-matter';
+import { ACCESS_LEVELS } from './reader.js';
+const KNOWN = new Set(['title', 'summary', 'subtitle', 'template', 'audience', 'cover', 'id', 'voice', 'narration', 'timings', 'narrationHash', 'password', 'access']);
+export function parseArtifactSource(text) {
+    const { data, content } = matter(text);
+    const d = data;
+    for (const k of Object.keys(d)) {
+        if (!KNOWN.has(k))
+            return { ok: false, error: `front matter has an unknown key: ${k}` };
+    }
+    for (const k of ['title', 'summary']) {
+        const v = d[k];
+        if (typeof v !== 'string' || !v.trim())
+            return { ok: false, error: `front matter is missing ${k}` };
+    }
+    const template = d.template ?? 'document';
+    if (template !== 'document')
+        return { ok: false, error: 'template must be document' };
+    const meta = {
+        title: String(d.title).trim(),
+        summary: String(d.summary).trim(),
+        template: 'document',
+    };
+    for (const k of ['subtitle', 'audience', 'cover', 'id', 'voice', 'narration', 'timings', 'narrationHash', 'password']) {
+        const v = d[k];
+        if (typeof v === 'string' && v)
+            meta[k] = v;
+    }
+    if (d.access !== undefined) {
+        if (d.access !== 'public' && !ACCESS_LEVELS.includes(d.access))
+            return { ok: false, error: `access must be one of: public, ${ACCESS_LEVELS.join(', ')}` };
+        meta.access = d.access;
+    }
+    return { ok: true, meta, body: content };
+}

package/lib/artifacts/index.d.ts

@@ -0,0 +1,9 @@
+export { parseArtifactSource, type ArtifactMeta } from './front-matter.js';
+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 { 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

@@ -0,0 +1,9 @@
+export { parseArtifactSource } from './front-matter.js';
+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 { 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/artifacts/narration.d.ts

@@ -0,0 +1,8 @@
+export declare function narrationTextFromMarkdown(markdown: string): string;
+export declare function narrationText(input: {
+    title: string;
+    summary: string;
+    markdown: string;
+}): string;
+/** Tokens the highlighter and the timings agree on: whitespace-split, lowercased, letters and digits only. */
+export declare function normalizeWord(w: string): string;