@strifeapp/astro 1.4.1 → 1.5.1

package/README.md

@@ -11,6 +11,7 @@ Official [Strife](https://strife.app) integration for [Astro](https://astro.buil
 - [Usage](#usage)
   - [Reading content](#reading-content)
   - [Telemetry: `<Insights />`](#telemetry-insights)
+  - [Snapshots](#snapshots)
   - [TypeScript: typing `strife:store`](#typescript-typing-strifestore)
   - [Direct Vite plugin](#direct-vite-plugin)
 - [Configuration](#configuration)
@@ -100,6 +101,70 @@ On every page load it reports Core Web Vitals (LCP, INP, CLS, FCP, TTFB) and, wh
 
 > The API only stores a beacon when its `Origin` is one of the team's registered domains. For local development, run the API in `Development` and add `localhost` to your team's `Domains`.
 
+> **Content Security Policy:** if your site sends a CSP header, allow the insights endpoint in `connect-src` (e.g. `connect-src 'self' https://api.strife.app`) — otherwise the browser blocks the beacon (a CSP violation is logged to the console; no request is sent and nothing is stored). Use your custom `endpoint`'s origin if you overrode it.
+
+Inside the Strife live preview (`Astro.locals.editMode`) only the accessibility audit runs; on a [snapshot](#snapshots) (`Astro.locals.snapshot`) the component renders nothing and sends no beacon at all.
+
+### Snapshots
+
+An editor can hand a reviewer a link to a frozen, unpublished version of a document: `{origin}{locale root prefix}/snapshot/{token}` — for example `https://example.com/snapshot/0123…cdef` or `https://example.com/sv/snapshot/0123…cdef`. The integration registers a `pre` middleware (`@strifeapp/astro/snapshot-middleware`) that resolves such a request to its snapshot in the `Content/ByUrl` index — for the locale Astro resolved (`context.currentLocale`) — and either sets `Astro.locals.snapshot` or answers with **your 404 page** (unknown, expired or revoked links look like content that does not exist). Both responses carry `X-Robots-Tag: noindex, nofollow`, `Cache-Control: private, no-store` and `Referrer-Policy: no-referrer`; edit mode is forced off on snapshot routes, so `<LivePreview />` never activates there.
+
+You author the page — it renders in your own layout. Copy [`templates/snapshot-page.astro`](https://github.com/wieldyapp/wieldy/blob/master/src/sdk/js/src/packages/astro/templates/snapshot-page.astro) to `src/pages/snapshot/[token].astro`:
+
+```astro
+---
+export const prerender = false;              // rendered on demand — never prebuilt
+import Layout from '../../layouts/Layout.astro';
+
+const { name, expiresAt, locale, content } = Astro.locals.snapshot!;
+---
+<Layout title={content.displayName ?? 'Preview'}>
+  <aside role="status">{name ? `Preview “${name}”` : 'Preview'} — expires {expiresAt.toISOString()}</aside>
+  <h1>{content.heading}</h1>
+</Layout>
+```
+
+`Astro.locals.snapshot` is `{ docId, name, expiresAt: Date, locale, content }`. `content` is the index row for that locale: `docId`, `locale`, `collection`, `displayName`, `url` (the snapshot path itself — a snapshot row's `url` is `{root slug}/snapshot/{token}` for its locale, never the canonical page's path), `snapshotName`, `expiresAt`, plus every field you list in `snapshot.fields`, so one lookup both decides the 404 and feeds the render:
+
+```typescript
+strife({
+  snapshot: {
+    fields: ['heading', 'body'],   // your template fields, projected onto Astro.locals.snapshot.content
+  },
+});
+```
+
+Without `snapshot.fields`, `content` carries the row fields only and the page queries its own fields by `docId` + `locale` (`whereEquals('docId', content.docId)`, `whereEquals('status', 'snapshot')`).
+
+| Option | Where | Description |
+| --- | --- | --- |
+| `snapshot.fields` | integration | Extra `Content/ByUrl` fields to project onto `content`. |
+| `snapshot.middleware: false` | integration | Skip the automatic registration; compose the middleware yourself (below). |
+| `resolveLocale(context)` | `createSnapshotMiddleware` | Resolve the request's locale when your site does not use Astro i18n routing. Defaults to `context.currentLocale`. |
+
+When the resolved locale has no row in the snapshot (a cookie- or Accept-Language-driven locale the draft never had, a link pasted under another prefix), the middleware serves the snapshot's own `snapshotLocale` row instead of the 404 — the same fallback as the .NET SDK. If your site resolves its locale in its own middleware (a cookie, a header, its own path scheme), Astro's `currentLocale` is not enough — opt out of the automatic registration and compose the middleware where your locale is known:
+
+```typescript
+// src/middleware.ts
+import { sequence } from 'astro:middleware';
+import { createSnapshotMiddleware } from '@strifeapp/astro/snapshot-middleware';
+
+export const onRequest = sequence(
+  myLocaleMiddleware,
+  createSnapshotMiddleware({ resolveLocale: (context) => context.locals.locale }),
+);
+```
+
+Keep these in mind:
+
+- The snapshot token is the link's secret. Render `name` as text only (never `set:html`), emit no Open Graph tags on the page, keep `/snapshot/*` out of CDN caching rules and analytics, and keep access-log retention short — a bearer URL is inherently logged by proxies. The middleware logs nothing on a hit and never logs the token.
+- `/snapshot/{token}` and `/{one segment}/snapshot/{token}` are reserved by the convention; the prefix segment is opaque (the locale comes from your resolution, not the path). Only a tail of 8 lowercase letters or digits is a snapshot request — a snapshot-shaped path with any other tail (`/help/snapshot/link`) is not claimed by the middleware and reaches your own routes, as in the .NET SDK.
+- A miss is rendered through Astro's rewrite to `/404`. Astro forbids rewriting from an on-demand route to a **prerendered** page, so if your `src/pages/404.astro` is static the middleware answers a bare `404` (headers included) and your adapter or host serves the static 404 page; add `export const prerender = false` to `404.astro` to render it through the rewrite instead.
+- Snapshots need a `Content/ByUrl` index built from a `@strifeapp/strife` release that includes snapshots, deployed with `strife push` (the developer docs state the exact versions); until then Strife refuses to create snapshots for the team, and the route answers your 404 page.
+- The middleware is optional: because a snapshot row's `url` is the snapshot path, a site can serve snapshots through its ordinary exact-URL lookup instead — the raw contract (the one predicate clause, the load-bearing locale clause, per-request resolution, and the hygiene you then own) is documented in the Strife developer reference under Snapshots.
+
+`resolveSnapshot(token, locale)` from `@strifeapp/astro/snapshot` is the same lookup as a function, returning the snapshot context or `null`.
+
 ### TypeScript: typing `strife:store`
 
 Typed ambient declarations for the `strife:store` virtual module are not bundled in this release. Until a typed surface is published, add your own declaration (e.g. in `src/env.d.ts`):

package/dist/Insights.astro

@@ -24,6 +24,7 @@
 // consumer's runtime/build (see the integration's env schema).
 import { getSecret } from 'astro:env/server';
 import { decodeSecrets } from '@strifeapp/strife/secrets';
+import { insightsMode } from './insights-mode.js';
 
 export interface Props {
   /** Override the collection endpoint. Defaults to the hosted Strife API. */
@@ -62,29 +63,31 @@ function resolveSiteId(): string | null {
 
 const site = resolveSiteId();
 
-// `editMode` is true inside the Strife live preview (set by the edit-mode
-// middleware). We split the work by audience: Web Vitals run only for REAL visitors
-// (they need real-user device/network/interaction variance), while the heavy
-// axe-core accessibility audit runs only in the editor's live preview — a11y is
-// deterministic per content version, so the editor is the right place for it, and it
-// keeps axe-core off every real visitor entirely. Without the middleware, editMode
-// defaults to false, so plain sites get Web Vitals exactly as before.
-const editMode = Astro.locals.editMode ?? false;
+// The middleware-set locals decide the audience. We split the work: Web Vitals run
+// only for REAL visitors (they need real-user device/network/interaction variance),
+// while the heavy axe-core accessibility audit runs only in the editor's live
+// preview (`editMode`) — a11y is deterministic per content version, so the editor is
+// the right place for it, and it keeps axe-core off every real visitor entirely. A
+// snapshot (`snapshot`, STR-2165) is neither: it sends nothing at all — it is not
+// audience traffic, and a beacon would carry the snapshot path, i.e. the token. Without
+// the middleware, plain sites get Web Vitals exactly as before.
+const mode = insightsMode(Astro.locals);
 ---
 
-{site && (
+{site && mode !== 'off' && (
   <Fragment>
-    <script is:inline define:vars={{ site, endpoint, accessibility, editMode }}>
-      window.__strifeInsights = { site, endpoint, accessibility, editMode };
+    <script is:inline define:vars={{ site, endpoint, accessibility, mode }}>
+      window.__strifeInsights = { site, endpoint, accessibility, mode };
     </script>
     <script>
       import { onLCP, onINP, onCLS, onFCP, onTTFB } from 'web-vitals';
+      import type { InsightsMode } from './insights-mode.js';
 
       const cfg = (window as any).__strifeInsights || {};
       const ENDPOINT: string = cfg.endpoint;
       const SITE: string = cfg.site;
       const RUN_A11Y: boolean = cfg.accessibility !== false;
-      const EDIT_MODE: boolean = cfg.editMode === true;
+      const MODE: InsightsMode = cfg.mode;
 
       /** Beacon a payload to the collection endpoint (fire-and-forget). */
       function send(payload: Record<string, unknown>) {
@@ -231,17 +234,18 @@ const editMode = Astro.locals.editMode ?? false;
         scheduleAccessibilityAudit();
       }
 
-      if (EDIT_MODE) {
+      if (MODE === 'audit') {
         // In the Strife live preview: only the accessibility audit runs. The editor is
         // the right place for the heavy axe-core scan (a11y is deterministic per content
         // version), and it keeps axe-core off every real visitor.
         auditOnce();
         // Astro View Transitions: re-audit the newly loaded page.
         document.addEventListener('astro:page-load', auditOnce);
-      } else {
+      } else if (MODE === 'vitals') {
         // A real visitor: Web Vitals only, batched on pagehide. No axe-core download/run.
         initWebVitals();
       }
+      // 'off' (a snapshot) never reaches this script: the component renders nothing.
     </script>
   </Fragment>
 )}

package/dist/index.d.ts

@@ -1,11 +1,31 @@
 import { AstroIntegration } from 'astro';
 import { IAuthOptions } from 'ravendb';
+import { SnapshotContext } from './snapshot';
+export type { SnapshotContent, SnapshotContext } from './snapshot';
 export interface IntegrationOptions extends IAuthOptions {
     certificate?: string;
     password?: string;
     urls?: string[];
     database?: string;
     collections?: Collection[];
+    /** Snapshots (`/snapshot/{token}`); see `@strifeapp/astro/snapshot-middleware`. */
+    snapshot?: SnapshotOptions;
+}
+export interface SnapshotOptions {
+    /**
+     * Index fields to project onto `Astro.locals.snapshot.content` beside the row fields
+     * (your template fields, e.g. `['heading', 'body']`), so the middleware's one
+     * lookup also feeds the render. Without it, `content` carries the row fields only
+     * and the snapshot page queries its own fields by `docId` + `locale`.
+     */
+    fields?: string[];
+    /**
+     * `false` skips the automatic `pre` registration of the snapshot middleware. Do this
+     * when your site resolves its locale in its own middleware: compose
+     * `createSnapshotMiddleware({ resolveLocale })` from `@strifeapp/astro/snapshot-middleware`
+     * in `src/middleware.ts` instead.
+     */
+    middleware?: boolean;
 }
 export interface Collection {
     name: string;
@@ -21,6 +41,14 @@ declare global {
              * e.g. render draft vs published content.
              */
             editMode?: boolean;
+            /**
+             * Set by the snapshot middleware on a `/snapshot/{token}` request that resolved to a
+             * live snapshot: the snapshot's id, its editor-given name (text only —
+             * never `set:html`), when the link expires, the resolved locale, and the
+             * `Content/ByUrl` projection to render. Absent on every other request, and
+             * on every snapshot miss (the middleware answers those with the site's 404 page).
+             */
+            snapshot?: SnapshotContext;
         }
     }
 }

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,OAAO,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAI5C,MAAM,WAAW,kBAAmB,SAAQ,YAAY;IACtD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,GAAG,CAAC;QACZ,UAAU,MAAM;YACd;;;;;eAKG;YACH,QAAQ,CAAC,EAAE,OAAO,CAAC;SACpB;KACF;CACF;AAMD,MAAM,CAAC,OAAO,UAAU,iBAAiB,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,gBAAgB,CAwDxF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,OAAO,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAG5C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEnE,MAAM,WAAW,kBAAmB,SAAQ,YAAY;IACtD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;IAC3B,mFAAmF;IACnF,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B;AAED,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,GAAG,CAAC;QACZ,UAAU,MAAM;YACd;;;;;eAKG;YACH,QAAQ,CAAC,EAAE,OAAO,CAAC;YACnB;;;;;;eAMG;YACH,QAAQ,CAAC,EAAE,eAAe,CAAC;SAC5B;KACF;CACF;AAMD,MAAM,CAAC,OAAO,UAAU,iBAAiB,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,gBAAgB,CAoExF"}

package/dist/index.js

@@ -1,20 +1,20 @@
 import { envField as e } from "astro/config";
-import { v as c } from "./vite-plugin-strife-store-B-B_HXbA.js";
-const i = {
+import { v as i } from "./vite-plugin-strife-store-B5tSnH_D.js";
+const c = {
   type: "pfx"
 };
-function p(t) {
+function l(t) {
   return {
     name: "@strife/astro",
     hooks: {
-      "astro:config:setup": ({ updateConfig: r, addMiddleware: s }) => {
-        const n = {
-          ...i,
+      "astro:config:setup": ({ updateConfig: o, addMiddleware: r }) => {
+        const s = {
+          ...c,
           ...t ? Object.fromEntries(
-            Object.entries(t).filter(([, o]) => o != null)
+            Object.entries(t).filter(([, n]) => n != null)
           ) : {}
         };
-        r({
+        o({
           env: {
             schema: {
               // Consolidated single-var secret (packs urls/database/certificate/password,
@@ -32,16 +32,19 @@ function p(t) {
             }
           },
           vite: {
-            plugins: [c(n)]
+            plugins: [i(s)]
           }
-        }), s({
+        }), r({
           entrypoint: "@strifeapp/astro/edit-mode-middleware",
           order: "pre"
+        }), s.snapshot?.middleware !== !1 && r({
+          entrypoint: "@strifeapp/astro/snapshot-middleware",
+          order: "pre"
         });
       }
     }
   };
 }
 export {
-  p as default
+  l as default
 };

package/dist/insights-mode.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Which telemetry `<Insights />` runs for a request, from the middleware-set locals:
+ *   - `vitals`: a real visitor — Core Web Vitals only;
+ *   - `audit`: the Strife live preview (edit mode) — the axe-core accessibility audit only;
+ *   - `off`: a snapshot (R14) — nothing at all. A snapshot is not audience traffic, and a
+ *     beacon would carry the snapshot path, i.e. the token.
+ * Pure, so the gate is unit-tested; Insights.astro only forwards the result.
+ */
+export type InsightsMode = 'vitals' | 'audit' | 'off';
+export declare function insightsMode(locals: {
+    editMode?: boolean;
+    snapshot?: unknown;
+}): InsightsMode;
+//# sourceMappingURL=insights-mode.d.ts.map

package/dist/insights-mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"insights-mode.d.ts","sourceRoot":"","sources":["../src/insights-mode.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,OAAO,GAAG,KAAK,CAAC;AAEtD,wBAAgB,YAAY,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,YAAY,CAI7F"}

package/dist/insights-mode.js

@@ -0,0 +1,6 @@
+function e(t) {
+  return t.snapshot != null ? "off" : t.editMode === !0 ? "audit" : "vitals";
+}
+export {
+  e as insightsMode
+};

package/dist/snapshot-middleware.d.ts

@@ -0,0 +1,36 @@
+import { APIContext, MiddlewareHandler } from 'astro';
+import { ResolveSnapshotOptions } from './snapshot';
+/**
+ * Snapshot-link middleware (STR-2165). Registered `pre` by the integration (see
+ * src/index.ts) unless `snapshot.middleware` is `false`; also exported as
+ * `createSnapshotMiddleware` so a site that resolves its locale in its own middleware
+ * can compose it there with `resolveLocale`.
+ *
+ * For a snapshot path (`/snapshot/{token}` after an optional locale root prefix, where the
+ * tail is a valid token — 8 lowercase letters or digits) it looks the snapshot up for
+ * the site's resolved locale and:
+ *   - on a hit sets `Astro.locals.snapshot = { docId, name, expiresAt, locale, content }`
+ *     and lets the site's `src/pages/snapshot/[token].astro` render it;
+ *   - on any miss renders the site's 404 page through Astro's rewrite, re-wrapped so
+ *     the status is 404 (Astro answers a rewrite with 200).
+ * Both carry `X-Robots-Tag: noindex, nofollow`, `Cache-Control: private, no-store`
+ * and `Referrer-Policy: no-referrer`. Edit mode is forced off on snapshot routes, so
+ * `<LivePreview />` never activates there. Nothing is logged on a hit, and the token
+ * is never logged. Every other path passes through untouched — including a
+ * snapshot-shaped path whose tail is not a token (`/help/snapshot/link`): as in the .NET
+ * resolver, that is not a snapshot request but an ordinary site route.
+ */
+export interface SnapshotMiddlewareOptions extends ResolveSnapshotOptions {
+    /**
+     * Resolve the locale of the current request. Defaults to Astro's
+     * `context.currentLocale` (i18n routing). A site that resolves its locale itself
+     * — from a cookie, a header, its own path scheme — must pass this, or a
+     * multi-locale snapshot resolves the wrong (or no) row.
+     */
+    resolveLocale?: (context: APIContext) => string | undefined | Promise<string | undefined>;
+}
+export declare const SNAPSHOT_RESPONSE_HEADERS: Readonly<Record<string, string>>;
+export declare function createSnapshotMiddleware(options?: SnapshotMiddlewareOptions): MiddlewareHandler;
+/** The default instance the integration registers via `addMiddleware`. */
+export declare const onRequest: MiddlewareHandler;
+//# sourceMappingURL=snapshot-middleware.d.ts.map

package/dist/snapshot-middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-middleware.d.ts","sourceRoot":"","sources":["../src/snapshot-middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,OAAO,CAAC;AAC3D,OAAO,EAAsD,KAAK,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAE7G;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,WAAW,yBAA0B,SAAQ,sBAAsB;IACvE;;;;;OAKG;IACH,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CAC3F;AAED,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAIrE,CAAC;AAEH,wBAAgB,wBAAwB,CAAC,OAAO,GAAE,yBAA8B,GAAG,iBAAiB,CA0BnG;AAED,0EAA0E;AAC1E,eAAO,MAAM,SAAS,EAAE,iBAA8C,CAAC"}

package/dist/snapshot-middleware.js

@@ -0,0 +1,49 @@
+import { matchSnapshotPath as u, isSnapshotToken as i, lookupSnapshot as h } from "./snapshot.js";
+const f = Object.freeze({
+  "X-Robots-Tag": "noindex, nofollow",
+  "Cache-Control": "private, no-store",
+  "Referrer-Policy": "no-referrer"
+});
+function p(r = {}) {
+  return async (e, o) => {
+    const t = u(e.url.pathname);
+    if (t === null || !i(t)) return o();
+    e.locals.editMode = !1;
+    const a = r.resolveLocale ? await r.resolveLocale(e) : e.currentLocale, n = await h(t, a, r);
+    return n.snapshot === null ? (n.reason === "query_error" && console.warn("[strife] snapshot lookup failed (reason=query_error); answering 404"), d(o)) : (e.locals.snapshot = n.snapshot, l(await o()));
+  };
+}
+const y = p();
+async function d(r) {
+  let e;
+  try {
+    e = await r("/404");
+  } catch {
+    e = new Response(null, { status: 404 });
+  }
+  return l(e, 404);
+}
+function l(r, e) {
+  const o = e !== void 0 && r.status !== e ? s(r, e) : r, t = (a) => {
+    for (const [n, c] of Object.entries(f))
+      a.set(n, c);
+  };
+  try {
+    return t(o.headers), o;
+  } catch {
+    const a = s(o, o.status);
+    return t(a.headers), a;
+  }
+}
+function s(r, e) {
+  return new Response(r.body, {
+    status: e,
+    statusText: r.statusText,
+    headers: new Headers(r.headers)
+  });
+}
+export {
+  f as SNAPSHOT_RESPONSE_HEADERS,
+  p as createSnapshotMiddleware,
+  y as onRequest
+};

package/dist/snapshot.d.ts

@@ -0,0 +1,129 @@
+import { IDocumentStore } from 'ravendb';
+/**
+ * Snapshots (STR-2165): resolve a `/snapshot/{token}` request to the one live snapshot
+ * snapshot its token names, reading the `Content/ByUrl` projection for the resolved
+ * locale. Locale handling mirrors the .NET SDK's `DefaultRouteResolver` exactly:
+ *   - with a resolved locale the query carries a locale clause; when it yields no row
+ *     (a cookie- or Accept-Language-driven locale the draft never had, a link pasted
+ *     under another prefix) the token is re-queried without the clause (bounded to
+ *     `MAX_SNAPSHOT_LOCALE_ROWS`) and only the snapshot's own row — `locale` equal to
+ *     its `snapshotLocale` — is kept, so the preview is served rather than hidden;
+ *   - without a resolved locale the token-only query pages every row of the snapshot
+ *     (again bounded to `MAX_SNAPSHOT_LOCALE_ROWS`, never just the first two), and more
+ *     than one candidate row is decided by the same rule: the `snapshotLocale` row wins,
+ *     and anything other than exactly one such row is an `ambiguous_locale` miss.
+ * Pure with respect to Astro — the store is injectable, so the lookup is
+ * unit-testable without RavenDB; `resolveSnapshot` without a store reads the
+ * integration's `strife:store` virtual module.
+ *
+ * The token is the bearer secret of the link: nothing in this module logs it, and
+ * a thrown query (an index build that predates snapshots, an unreachable store)
+ * is a miss, never an exception that could surface it on an error page.
+ */
+/** The content index the integration queries; deployed by `strife push`. */
+export declare const SNAPSHOT_INDEX_NAME = "Content/ByUrl";
+/** A snapshot token is exactly 8 lowercase letters or digits — nothing looser. */
+export declare const SNAPSHOT_TOKEN_PATTERN: RegExp;
+/**
+ * Upper bound on locales one snapshot can carry rows for; a token-only query (no
+ * resolved locale, or the locale fallback) never scans further. Same constant as the
+ * .NET resolver's `MaxSnapshotLocaleRows`.
+ */
+export declare const MAX_SNAPSHOT_LOCALE_ROWS = 64;
+/**
+ * Row fields every snapshot lookup projects from the index: the snapshot metadata plus
+ * what a page needs to pick a layout (`collection`, `displayName`, `url`). The row's
+ * `url` is the snapshot path itself — `{root slug}/snapshot/{token}` for the row's locale,
+ * the exact-URL lookup key a raw site queries — never the canonical page's path. `deleted`
+ * is not stored in the index; RavenDB's default projection behaviour reads it from
+ * the document, which is exactly the soft-delete check we want. Site-specific
+ * template fields come from the `fields` option.
+ */
+export declare const SNAPSHOT_ROW_FIELDS: readonly ["docId", "locale", "collection", "displayName", "url", "status", "snapshotToken", "snapshotName", "expiresAt", "snapshotLocale", "createdAt", "changedAt", "publishedAt", "origin", "labels", "deleted"];
+/**
+ * The `Content/ByUrl` row for the snapshot in the resolved locale — the same
+ * projected, locale-translated object a page gets when it queries the index, plus
+ * any site fields passed through `fields`.
+ */
+export interface SnapshotContent {
+    docId: string;
+    locale: string;
+    status: 'snapshot';
+    snapshotToken: string;
+    snapshotName?: string | null;
+    expiresAt: string;
+    /** The locale the editor was viewing when sharing — the one the link targets. */
+    snapshotLocale?: string | null;
+    collection?: string | null;
+    displayName?: string | null;
+    /** The snapshot path for this locale (`{root slug}/snapshot/{token}`) — not the canonical page's path. */
+    url?: string | null;
+    [field: string]: unknown;
+}
+/** What a snapshot page sees on `Astro.locals.snapshot`. */
+export interface SnapshotContext {
+    /** The snapshot's document id (`{canonicalId}/snapshot/{token}`). Never log it. */
+    docId: string;
+    /** The editor-given name, or `null`. Render as text only — never `set:html`. */
+    name: string | null;
+    /** UTC instant after which the link stops resolving. */
+    expiresAt: Date;
+    /** The locale the row was resolved for. */
+    locale: string;
+    /** The index projection for that locale; render this. */
+    content: SnapshotContent;
+}
+export type SnapshotMissReason = 'malformed_token' | 'not_found' | 'ambiguous_locale' | 'deleted' | 'no_expiry' | 'expired' | 'query_error';
+export type SnapshotLookup = {
+    snapshot: SnapshotContext;
+    reason: null;
+} | {
+    snapshot: null;
+    reason: SnapshotMissReason;
+};
+export interface ResolveSnapshotOptions {
+    /** The document store to query. Defaults to the integration's `strife:store`. */
+    store?: IDocumentStore;
+    /**
+     * Extra index fields to project onto `content` (your template fields, e.g.
+     * `['heading', 'body']`), so one lookup both decides the 404 and feeds the render.
+     * Defaults to the integration's `snapshot.fields` option.
+     */
+    fields?: readonly string[];
+    /** Clock, for tests. */
+    now?: () => Date;
+}
+export declare function isSnapshotToken(value: unknown): value is string;
+/**
+ * Matches the snapshot convention `/snapshot/{token}` after an optional single locale root
+ * prefix segment (`/sv/snapshot/{token}`, `/svenska/snapshot/{token}`), with or without a
+ * trailing slash. Returns the raw token segment — validate it with `isSnapshotToken` — or
+ * `null` when the path is not snapshot-shaped. The prefix is opaque: the locale comes
+ * from the site's own resolution, never from the path.
+ */
+export declare function matchSnapshotPath(pathname: string): string | null;
+/**
+ * Picks the single live snapshot row or names the miss. Mirrors the .NET SDK's
+ * `DefaultRouteResolver.ClassifySnapshotRows` so both site SDKs agree on "live": with
+ * more than one row (several locales of one snapshot and no locale resolver to pick
+ * between them) the snapshot's own locale wins — the row whose `locale` equals its
+ * `snapshotLocale` — and anything other than exactly one such row is `ambiguous_locale`.
+ */
+export declare function classifySnapshotRows(rows: readonly Record<string, unknown>[], now: Date): SnapshotLookup;
+/**
+ * Looks a snapshot up and reports the outcome with its miss reason. A malformed token
+ * never reaches the store. `locale` is the site's resolved locale: the query carries
+ * it as a clause, and when that yields no row the token is re-queried without the
+ * clause and only the snapshot's own `snapshotLocale` row is kept (the .NET resolver's
+ * locale fallback). When `locale` is `undefined` (a single-locale site without Astro
+ * i18n) the clause is omitted from the start and the query pages every row of the
+ * snapshot; more than one row then resolves to the `snapshotLocale` row, or is an
+ * `ambiguous_locale` miss (see `classifySnapshotRows`).
+ */
+export declare function lookupSnapshot(token: string, locale: string | undefined, options?: ResolveSnapshotOptions): Promise<SnapshotLookup>;
+/**
+ * Resolves `token` in `locale` to the snapshot context, or `null` on any miss
+ * (unknown, malformed, deleted, expired, missing expiry, query failure).
+ */
+export declare function resolveSnapshot(token: string, locale: string | undefined, options?: ResolveSnapshotOptions): Promise<SnapshotContext | null>;
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../src/snapshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,4EAA4E;AAC5E,eAAO,MAAM,mBAAmB,kBAAkB,CAAC;AAEnD,kFAAkF;AAClF,eAAO,MAAM,sBAAsB,QAAkB,CAAC;AAEtD;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAE3C;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,oNAiBtB,CAAC;AAEX;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,UAAU,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,0GAA0G;IAC1G,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED,4DAA4D;AAC5D,MAAM,WAAW,eAAe;IAC9B,mFAAmF;IACnF,KAAK,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,wDAAwD;IACxD,SAAS,EAAE,IAAI,CAAC;IAChB,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,OAAO,EAAE,eAAe,CAAC;CAC1B;AAED,MAAM,MAAM,kBAAkB,GAC1B,iBAAiB,GACjB,WAAW,GACX,kBAAkB,GAClB,SAAS,GACT,WAAW,GACX,SAAS,GACT,aAAa,CAAC;AAElB,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,IAAI,CAAA;CAAE,GAC3C;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,CAAC;AAEnD,MAAM,WAAW,sBAAsB;IACrC,iFAAiF;IACjF,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB;;;;OAIG;IACH,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,wBAAwB;IACxB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE/D;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGjE;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAAE,GAAG,EAAE,IAAI,GAAG,cAAc,CA2BxG;AAcD;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,cAAc,CAAC,CAezB;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAEjC"}

package/dist/snapshot.js

@@ -0,0 +1,104 @@
+const i = "Content/ByUrl", c = /^[a-z0-9]{8}$/, _ = 64, p = [
+  "docId",
+  "locale",
+  "collection",
+  "displayName",
+  "url",
+  "status",
+  "snapshotToken",
+  "snapshotName",
+  "expiresAt",
+  "snapshotLocale",
+  "createdAt",
+  "changedAt",
+  "publishedAt",
+  "origin",
+  "labels",
+  "deleted"
+];
+function h(e) {
+  return typeof e == "string" && c.test(e);
+}
+function w(e) {
+  const n = /^\/(?:[^/]+\/)?snapshot\/([^/]+)\/?$/.exec(e);
+  return n ? n[1] : null;
+}
+function f(e, n) {
+  if (e.length === 0) return { snapshot: null, reason: "not_found" };
+  let t = e[0];
+  if (e.length > 1) {
+    const r = e.filter(u);
+    if (r.length !== 1) return { snapshot: null, reason: "ambiguous_locale" };
+    t = r[0];
+  }
+  if (t.deleted === !0) return { snapshot: null, reason: "deleted" };
+  const o = d(t.expiresAt);
+  if (o === null) return { snapshot: null, reason: "no_expiry" };
+  if (o.getTime() <= n.getTime()) return { snapshot: null, reason: "expired" };
+  const s = t;
+  return {
+    snapshot: {
+      docId: String(s.docId),
+      name: typeof s.snapshotName == "string" ? s.snapshotName : null,
+      expiresAt: o,
+      locale: String(s.locale),
+      content: s
+    },
+    reason: null
+  };
+}
+function u(e) {
+  return e.snapshotLocale != null && e.locale === e.snapshotLocale;
+}
+function d(e) {
+  if (e instanceof Date) return Number.isNaN(e.getTime()) ? null : e;
+  if (typeof e != "string" || e === "") return null;
+  const n = new Date(e);
+  return Number.isNaN(n.getTime()) ? null : n;
+}
+async function S(e, n, t = {}) {
+  if (!h(e)) return { snapshot: null, reason: "malformed_token" };
+  const o = t.now ?? (() => /* @__PURE__ */ new Date());
+  let s;
+  try {
+    const { store: r, fields: a } = await y(t);
+    s = await N(r, e, n, a);
+  } catch {
+    return { snapshot: null, reason: "query_error" };
+  }
+  return f(s, o());
+}
+async function T(e, n, t = {}) {
+  return (await S(e, n, t)).snapshot;
+}
+async function N(e, n, t, o) {
+  const s = e.openSession();
+  try {
+    const r = m(o);
+    let a = s.query({ indexName: i }).whereEquals("snapshotToken", n).whereEquals("status", "snapshot");
+    t && (a = a.whereEquals("locale", t));
+    const l = await a.selectFields(r).take(t ? 2 : 64).all();
+    return l.length > 0 || !t ? l : (await s.query({ indexName: i }).whereEquals("snapshotToken", n).whereEquals("status", "snapshot").selectFields(r).take(64).all()).filter(u);
+  } finally {
+    s.dispose();
+  }
+}
+function m(e) {
+  return [.../* @__PURE__ */ new Set([...p, ...e ?? []])];
+}
+async function y(e) {
+  if (e.store) return { store: e.store, fields: e.fields };
+  const n = await import("strife:store");
+  return { store: n.store, fields: e.fields ?? n.snapshotOptions?.fields };
+}
+export {
+  _ as MAX_SNAPSHOT_LOCALE_ROWS,
+  i as SNAPSHOT_INDEX_NAME,
+  p as SNAPSHOT_ROW_FIELDS,
+  c as SNAPSHOT_TOKEN_PATTERN,
+  f as classifySnapshotRows,
+  h as isSnapshotToken,
+  S as lookupSnapshot,
+  w as matchSnapshotPath,
+  T as resolveSnapshot
+};

package/dist/{vite-plugin-strife-store-B-B_HXbA.js → vite-plugin-strife-store-B5tSnH_D.js}

@@ -96,6 +96,10 @@ function n(o) {
           // operator-controlled path). The store only connects and reads — Astro no
           // longer deploys the index or seeds templates.
           export { store };
+
+          // Non-secret snapshot-link options (@strifeapp/astro/snapshot reads the projection
+          // fields from here when the auto-registered middleware resolves a snapshot).
+          export const snapshotOptions = defaultConfig.snapshot || {};
         `;
     }
   };

package/dist/vite-plugin-strife-store-entry.js

@@ -1,4 +1,4 @@
-import { v as t } from "./vite-plugin-strife-store-B-B_HXbA.js";
+import { v as t } from "./vite-plugin-strife-store-B5tSnH_D.js";
 export {
   t as vitePluginStrifeStore
 };

package/dist/vite-plugin-strife-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vite-plugin-strife-store.d.ts","sourceRoot":"","sources":["../src/vite-plugin-strife-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,MAAM,CAAC;AAEzC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAKlD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,kBAAkB,GAAG,YAAY,CA6G9E"}
+{"version":3,"file":"vite-plugin-strife-store.d.ts","sourceRoot":"","sources":["../src/vite-plugin-strife-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,MAAM,CAAC;AAEzC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAKlD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,kBAAkB,GAAG,YAAY,CAiH9E"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strifeapp/astro",
-  "version": "1.4.1",
+  "version": "1.5.1",
   "description": "Official Strife integration for Astro — connect your Astro site to a RavenDB-backed Strife content store via a strife:store virtual module.",
   "keywords": [
     "astro-integration",
@@ -39,6 +39,14 @@
       "types": "./dist/edit-mode-middleware.d.ts",
       "import": "./dist/edit-mode-middleware.js"
     },
+    "./snapshot": {
+      "types": "./dist/snapshot.d.ts",
+      "import": "./dist/snapshot.js"
+    },
+    "./snapshot-middleware": {
+      "types": "./dist/snapshot-middleware.d.ts",
+      "import": "./dist/snapshot-middleware.js"
+    },
     "./LivePreview.astro": "./dist/LivePreview.astro",
     "./Insights.astro": "./dist/Insights.astro",
     "./vite-plugin-strife-store": "./dist/vite-plugin-strife-store-entry.js"
@@ -63,17 +71,17 @@
     "@strifeapp/strife": "^1.1.0",
     "axe-core": "^4.11.0",
     "dotenv": "^17.2.3",
-    "jose": "^5.9.6",
+    "jose": "^6.2.9",
     "ravendb": "^7.1.4",
     "serialize-javascript": "^7.0.5",
-    "web-vitals": "^5.1.0"
+    "web-vitals": "^6.1.1"
   },
   "devDependencies": {
     "@types/serialize-javascript": "^5.0.4",
-    "astro": "^6.3.6",
+    "astro": "^6.4.8",
     "rimraf": "^6.0.1",
     "typescript": "^5.7.3",
-    "vite": "^7.0.0",
+    "vite": "^7.3.6",
     "vite-plugin-dts": "^4.5.3",
     "vitest": "^4.1.7"
   },