@storystick/astro 0.0.0-stage → 0.2.0-rc.1

package/LICENSE

@@ -0,0 +1,112 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 Tanguy Freycon
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+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.
+
+This Agreement shall be governed by the laws of France.

package/PUBLIC-API.md

@@ -0,0 +1,23 @@
+# @storystick/astro API contract
+
+Install this candidate explicitly with `@storystick/astro@0.2.0-rc.1` after registry bootstrap and publication. This repository alone does not make the candidate or beta channel available on npm.
+
+Version 0.2.0-rc.1, cohort `sdk-0.2.0-rc.1`. ESM distribution; no CommonJS or universal Edge compatibility is promised.
+
+This package is a product integration facade. Reserved contracts are required between SDK packages and must be upgraded with the same cohort. Their public export paths do not promise independent stability.
+
+| Entry | Status |
+| --- | --- |
+| `.` | Supported beta entry |
+| `./integration` | Supported beta entry |
+| `./components` | Supported beta entry |
+| `./browser` | Reserved SDK contract |
+| `./internal/*` | Reserved SDK contract |
+| `./components/*` | Supported beta entry |
+| `./routes/*` | Reserved SDK contract |
+
+The qualified toolchain is Node 24.19.0 and pnpm 9.15.9. Next uses App Router 15.5.28, Sharp 0.35.5 and React/React DOM 19.2.8; Astro uses 7.4.4 with the Node adapter 11.1.9. Browser delivery is verified by bundling; hosted Preview activation and cross-browser behavior require the staging manual check. Source/CLI are Node tools, server entries belong on the server, and browser entries must never receive a server API key.
+
+Use a generated Query V2 definition. A missing document/singleton returns null, an empty collection returns an empty array, and fetch throws on blocked/degraded execution. Execute exposes the complete result envelope. RSC metadata must remain plain JSON data; request authority must not be stored in shared module state.
+
+The repository is private. Public package availability does not make the monorepo public, and npm provenance from that repository is unavailable. Product and pilot support: [Storystick](https://storystick.app).

package/README.md

@@ -1,3 +1,164 @@
-# Temporary Holding Version
+# @storystick/astro
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Native Astro rendering with the shared Storystick query, media and Preview contracts. The initial candidate is exercised on Astro 7.4.4, Node 24.3 and `@astrojs/node` 11.1.9. The connected pilot uses the compiled package. Main, Published, release, variant, pathless documents, templates, independent reads, detached editing and React islands have been exercised with a real dedicated Studio project. The native starter is also qualified from installed tarballs outside the workspace. This does not qualify other deployment adapters or browsers; see the lifecycle limits below.
+
+## Configure once
+
+Generate your content definition with the Storystick CLI, then export your site from a server module:
+
+```ts
+// src/storystick.ts
+import { getSecret } from 'astro:env/server';
+import { createSite } from '@storystick/astro';
+import * as definition from '../generated/storystick/query';
+
+export const site = createSite({
+  definition,
+  projectId: getSecret('STORYSTICK_PROJECT_ID')!,
+  apiKey: () => getSecret('STORYSTICK_API_KEY')!,
+  publishableKey: () => getSecret('STORYSTICK_PUBLISHABLE_KEY')!,
+  applicationBuildId: getSecret('STORYSTICK_APP_BUILD_ID'),
+  siteUrl: 'https://example.com',
+});
+```
+
+The API key stays on the server. Preview requires the publishable key and the registered application build identity. Gateway infrastructure resolves from the project ID; `infrastructure` is an override for isolated development or self-hosting.
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import storystick from '@storystick/astro/integration';
+export default defineConfig({
+  integrations: [storystick({ site: './src/storystick.ts' })],
+});
+```
+
+The public build can be static or SSR. Its Storystick mount emits no markup, CSS or JavaScript. For a separate Preview deployment, use `output: 'server'`, your SSR adapter, and `preview: { origin: 'https://preview.example.com' }` in the integration. The integration owns `/api/storystick/*`, `/storystick-preview-error`, the exact allowed origin and a composable middleware. Preview responses are private/no-store and noindex. A base path other than `/` is currently rejected explicitly.
+
+## Read and route
+
+```astro
+---
+import { Text, SliceZone, Storystick } from '@storystick/astro/components';
+import { site } from '../storystick';
+import Hero from '../components/Hero.astro';
+const route = await site.resolvePage(Astro);
+if (route.type === 'redirect') return Astro.redirect(route.redirectTo, route.permanent ? 308 : 302);
+if (route.type === 'notFound') Astro.response.status = 404;
+---
+{route.type === 'document' ? <>
+  <Text as="h1" value={route.document.fields.title}/>
+  <SliceZone slices={route.document.fields.sections} components={{ hero: Hero }}/>
+</> : <h1>Page not found</h1>}
+<Storystick site={site}/>
+```
+
+Resolve redirects and response statuses in the page frontmatter, before rendering child components: Astro cannot redirect after a child has started streaming. Use a native `src/pages/[...pathname].astro` catch-all for CMS routing. For static generation, export `getStaticPaths = () => site.params()`; Preview uses on-demand rendering. The route result discriminates documents by the generated story type. Redirects, publication inventory, canonical URLs and language alternates use the same logic as the Next adapter.
+
+Independent layouts/components call `await site.client(Astro)`, then the generated Query V2 API. Pass the same Astro request context: admission and read context are shared within that request, never across visitors. Build-time `site.client()` has no Preview authority. `site.metadata(route)` returns canonical/language URLs and indexing posture; `site.sitemap()` returns published sitemap entries. `sitemapResponse(await site.sitemap())` returns XML for a native `sitemap.xml.ts` endpoint. Large sites use `site.sitemapIds()`, per-shard `site.sitemap({ id })` and `sitemapIndexResponse(urls)`; the application owns those endpoint paths. `publicOrigins` and `domainLocale` support language domains.
+
+An explicit `_ss_draft` destination resolves a routable document without a pathname through `site.resolvePage(Astro)`. When its pathname is assigned, the resolver returns a canonical redirect. A native homepage uses `await site.resolvePreviewDraft(Astro)` and keeps its own content when the result is `null`. This also accepts a template prototype bound to the admitted view. The prototype must match that view’s route and target; ordinary customer navigation leaves it. As the pilot demonstrates, Storystick does not replace arbitrary customer content.
+
+## Native components
+
+- `Text`: clean text and field provenance; `previewText(value)` returns `{ text, attributes }` for your own element.
+- `Image`, `File`, `Video`: existing asset resolvers with native HTML, a named `fallback` slot and optional resolver `options`. Storystick owns image transforms; no second Astro image transform is applied.
+- `Link`: the shared safe link resolver (`link`, `document` or `href`), native navigation and locale-aware document references carried by content values.
+- `RichText`, `RichTextInline`: native HTML, block/mark/list/embed component overrides, safe links and field provenance. Unknown blocks preserve text and report a diagnostic.
+- `SliceZone`: dispatches generated slices to native Astro components. The component receives `slice`, `siblings`, `bindings`, `zones` and `context`. Optional generated `contracts` validate variations and project the exact field surface. A `fallback` Astro component receives `failure`; otherwise unresolved slices fail visibly. Rich text embeds use the same contracts and fallback.
+- `Slice`: an explicit visual root, e.g. `<Slice as="section" slice={slice} siblings={siblings}>`. `sliceAttributes()` is the wrapper-free alternative.
+- `Zone`: renders a named `zones.name` descriptor as rich text or a nested slice zone.
+
+Autonomous query values carry model bindings, zones, references and asset metadata. Raw values can supply an explicit `{ document, path }` source. A missing slice renderer or unresolved model fails visibly instead of silently dropping a section.
+
+## Preview lifecycle
+
+Put one `Storystick` mount in the shared layout. Astro's native ClientRouter owns navigation and body replacement; the SDK host persists. Customer islands follow native Astro lifecycle rules. A response is acknowledged only after its receipt, destination and read context match the actual installed render. Invalid or stale HTTP responses preserve the last accepted page and offer recovery. The existing React authoring host is used for detached editing; customer markup can stay native Astro without a React integration.
+
+Customer React islands can opt into `transition:persist` and the ordinary Astro React integration. The pilot verified `client:load`, `client:idle` and `client:visible`: persisted state survives refresh/navigation while new props arrive; ordinary islands remount; visible islands hydrate on visibility and retain field provenance. Menus, forms and media follow these native lifetimes, rather than an SDK promise to preserve arbitrary DOM state.
+
+A complete transport failure is different from an invalid HTTP response: Astro 7.4.4 falls back to full browser navigation when its page fetch fails. In the offline pilot this lost local island state; restoring the network and reloading Studio recovered editing. Seamless offline navigation, long real BFCache suspension and browser-specific third-party cookie behavior remain outside the qualified matrix. The SDK does not replace Astro's loader to hide those limits.
+
+The browser reads explicit Storystick markers only. `debug` on the mount enables identity/checkpoint traces on its own host; credentials are never recorded. Public and Preview must have distinct cache/origin policies. The qualified deployment target is Astro 7.4.4 with the official Node adapter 11.1.9 on Node 24.3. Other deployment adapters, base paths and server islands require their own qualification. Template rendering, image delivery, live edits, field selection and navigation back to a CMS document have been exercised in the connected pilot. The current native image component has responsive candidates and contextual alt; automatic LQIP loading effects are not part of its initial HTML-only contract.
+
+## Development
+
+`pnpm --filter @storystick/astro build`, `pnpm --filter @storystick/astro test`, and `pnpm --filter @storystick/astro exec astro-check --tsconfig tsconfig.check.json` cover TypeScript, native components and low-level contracts. The public fixture builds with `pnpm --filter @storystick/astro exec astro build --root tests/fixtures/public`. Manual connected qualification uses `services/spikes/astro-preview-pilot`; no Preview browser E2E harness is introduced.
+
+## Deployment and publication
+
+`site.locale(Astro)` uses the resolved route locale, or the configured/project
+locale for an independent layout. `SliceComponentProps<GeneratedSliceData>` types
+a native slice without requiring an index signature on generated data.
+
+Node SSR builds expose read-only `/api/storystick/health` and
+`/api/storystick/migration-readback` endpoints through the integration. Readback
+requires `applicationBuildId` and `applicationBuildDigest`, the deployed
+application's lowercase SHA-256. It reports the build-paired schema and generated
+query fingerprint for the CLI's existing migration attestation flow. It does not
+activate a migration. Static output has no such request endpoints. Public SSR
+rejects private Preview actions.
+
+Public SSR has no SDK page cache. A deployment that adds a CDN cache owns its
+invalidation. Static publication requires a new build and atomic deployment of
+the resulting route inventory and sitemap. A missed hosting job must remain
+recoverable by replaying or manually triggering that build.
+
+For a server endpoint accepting Storystick publication deliveries:
+
+```ts
+import type { APIRoute } from 'astro';
+import { getSecret } from 'astro:env/server';
+import { createPublicationHandler } from '@storystick/astro';
+import { enqueueBuild } from '../your-build-queue';
+const handle = createPublicationHandler({
+  projectId: getSecret('STORYSTICK_PROJECT_ID')!,
+  secret: () => getSecret('STORYSTICK_WEBHOOK_SECRET'),
+  onPublish: async event => { await enqueueBuild(event.projectId); return 'accepted'; },
+});
+export const prerender = false;
+export const POST: APIRoute = ({ request }) => handle(request);
+```
+
+Mount this outside the integration's reserved `/api/storystick/*` paths, for
+example `/api/publication`, and configure that URL in Studio. A static-only
+hosting target needs a separate server receiver. The SDK verifies the signature,
+bounds actual body bytes to 1 MiB and checks the project and batch. It acknowledges
+the callback's explicit `accepted` (durably enqueued) or `completed` (invalidation
+performed) result; callback failure returns 503. Neither result certifies rendered
+pages. The dispatcher retains a separate rendered proof obligation for instrumented
+sites and retries until it is satisfied. Callbacks must tolerate repeated deliveries. Coalesce
+builds while work is pending; do not keep a permanent content-hash deduplication
+set, since an identical payload can represent a later legitimate publication.
+
+## Hosting and browser policy
+
+Keep API keys and webhook secrets server-side. Configure the exact Preview origin
+and Studio's allowed origins; do not reuse public CDN caching rules for Preview.
+Production Preview requires HTTPS. Admission cookies are scoped by the shared
+project/origin contract and remain HTTP-only; detached windows obtain their own
+admission through Studio. Browser restrictions on third-party iframe cookies still
+apply. Use the same site domain where appropriate, or the detached top-level
+Preview flow when the browser blocks the embedding arrangement.
+
+A custom CSP must permit Studio as a frame ancestor, the SDK's scripts and
+styles, the configured content/asset origins, and the Preview/authoring HTTP and
+WebSocket endpoints. Keep those policies specific to the chosen deployment;
+there is no blanket wildcard policy supplied by the SDK.
+
+The starter is available as `minimal-astro`. Its pinned artifact and the full
+package dependency closure are qualified outside the workspace by
+`pnpm starter:qualify:astro`: generation, Astro types, Node SSR, static localized
+HTML, sitemap and unauthenticated Preview rejection. No browser test harness is
+required for this distribution check.
+
+The `deliveryEndpoint`, `deploymentId` and `publicRendering` site options connect
+public reads and explicit rendering proof. See the repository's
+[publication contract](../../services/public-content-gateway/PUBLICATION.md) for
+receipt components, route manifests, v2 callbacks and qualified hosting modes.
+
+## Candidate distribution contract
+
+See [PUBLIC-API.md](./PUBLIC-API.md) for supported entries, reserved SDK contracts,
+the qualified runtime matrix and the candidate cohort. Upgrade Storystick
+packages together.

package/dist/.source-hash

@@ -0,0 +1 @@
+5f6f45338c96bd1cce60a00414498f8a9c138c04f19a80cf4bcc6d988b517a46

package/dist/browser.d.ts

@@ -0,0 +1 @@
+export declare function boot(): Promise<void>;

package/dist/browser.js

@@ -0,0 +1,327 @@
+import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { navigate } from 'astro:transitions/client';
+import { useSyncExternalStore } from 'react';
+import { createRoot } from 'react-dom/client';
+import { createInternalClient } from '@storystick/client/internal';
+import { previewRuntime } from '@storystick/preview/runtime/store';
+import { bootIframeRuntime } from '@storystick/preview/runtime/boot';
+import { createPreviewRequestId } from '@storystick/preview/runtime/request-id';
+import { isPreviewBrowserContext } from '@storystick/preview/identity/browser-context';
+import { getNavigateHandler, getReloadHandler, setNavigateHandler, setReloadHandler } from '@storystick/preview/nav-handler';
+import { notifyRouterTransition } from '@storystick/preview/router-subscriber';
+import { setStandaloneOverlaySuspended } from '@storystick/preview/runtime/standalone-overlays';
+import { PreviewStandaloneControls } from '@storystick/react/internal/preview-host';
+import { canRefreshPresentedPreviewContext, createPreviewRuntimeAdapterStore, PREVIEW_RUNTIME_SERVER_SNAPSHOT } from '@storystick/preview/framework/runtime-adapter-store';
+import { createPreviewProjectionGenerationWatch } from '@storystick/preview/framework/projection-generation-watch';
+import { createPreviewGenerationRefresh } from '@storystick/preview/framework/generation-refresh';
+import { isPreviewProjectionGenerationSignal } from '@storystick/preview/framework/generation-signal';
+import { commitPreviewRenderReceipt } from '@storystick/preview/framework/render-receipt';
+import { emitRuntimeError, emitRuntimeRecovered } from '@storystick/preview/runtime/emit-runtime-error';
+import { createAstroRenderGate, isAstroRenderReceipt, renderLocation } from './render-gate.js';
+import { createAstroNavigation } from './navigation.js';
+const trace = [];
+const record = (event, detail = {}) => {
+    if (!document.querySelector('[data-storystick-astro-host][data-storystick-debug]'))
+        return;
+    trace.push({ event, at: performance.now(), ...detail });
+    if (trace.length > 300)
+        trace.shift();
+    document.querySelector('[data-storystick-astro-host]')?.setAttribute('data-storystick-trace', JSON.stringify(trace));
+};
+let booted = false;
+let disposeBoot;
+if (import.meta.hot)
+    import.meta.hot.dispose(() => disposeBoot?.());
+export async function boot() {
+    if (booted)
+        return;
+    const readRender = (doc = document) => {
+        try {
+            return JSON.parse(doc.querySelector('[data-storystick-astro-render]')?.textContent ?? 'null');
+        }
+        catch {
+            return null;
+        }
+    };
+    const initial = readRender();
+    if (!initial || !isPreviewBrowserContext(initial.config.projectId))
+        return;
+    booted = true;
+    const config = initial.config;
+    const lifetime = new AbortController();
+    let disposed = false;
+    window.__STORYSTICK_CODE_VERSION__ = config.codeVersion;
+    let watchCount = 0;
+    let driver = null;
+    let stopWatch;
+    let currentWatchKey = '';
+    let currentClientKey = '';
+    let currentReceipt = null;
+    let clearReceipt;
+    let renderError = initial.error ? 'The preview could not render this page.' : null;
+    let recoverAdmission = initial.recovery === 'admission';
+    let initialRecoveryLaunched = false;
+    let retryUrl = location.href;
+    let latestDestination = location.href;
+    let reportedLocation = null;
+    const retries = new Set();
+    const commands = new WeakMap();
+    const adapter = createPreviewRuntimeAdapterStore(previewRuntime);
+    const host = document.querySelector('[data-storystick-astro-host]');
+    const root = createRoot(host);
+    function Controls() {
+        const state = useSyncExternalStore(adapter.subscribe, adapter.getSnapshot, () => PREVIEW_RUNTIME_SERVER_SNAPSHOT);
+        if (window.parent !== window)
+            return null;
+        return _jsxs(_Fragment, { children: [renderError && _jsxs("aside", { role: "alert", "data-storystick-astro-error": true, style: { position: 'fixed', bottom: 16, left: 16, zIndex: 2147483646, padding: 16, background: '#fff', color: '#172b2a', border: '1px solid #aaa', borderRadius: 12 }, children: [_jsxs("p", { children: [renderError, " The last successful page is retained when available."] }), _jsx("button", { type: "button", onClick: () => void transition(retryUrl), children: "Retry preview" })] }), state.state !== 'idle' && _jsx(PreviewStandaloneControls, { projectId: config.projectId, state: state, pathname: location.pathname })] });
+    }
+    root.render(_jsx(Controls, {}));
+    record('boot');
+    const aligned = (receipt) => {
+        const context = previewRuntime.getState().session?.readContext;
+        return isAstroRenderReceipt(receipt) && context && receipt.readContext.contextId === context.contextId && receipt.readContext.revision === context.revision;
+    };
+    function fail(message, destination = latestDestination) {
+        if (disposed)
+            return;
+        renderError = message;
+        retryUrl = destination;
+        driver?.observeTransition(false);
+        emitRuntimeError({ code: 'runtime.customer_render_failed', message, severity: 'error', retryable: true });
+        root.render(_jsx(Controls, {}));
+    }
+    function commit(receipt, info) {
+        currentReceipt = receipt;
+        latestDestination = location.href;
+        clearReceipt?.();
+        clearReceipt = commitPreviewRenderReceipt(receipt);
+        renderError = null;
+        retries.clear();
+        emitRuntimeRecovered('runtime.customer_render_failed');
+        window.dispatchEvent(new CustomEvent('storystick.preview.rendered-context', { detail: {
+                sessionId: previewRuntime.getState().sessionId, source: 'framework', readContext: receipt.readContext,
+            } }));
+        reportLocation(receipt, info);
+        setStandaloneOverlaySuspended(false);
+        if (isPreviewProjectionGenerationSignal(receipt.projectionCheckpoint))
+            driver?.observeRenderedCheckpoint(receipt.projectionCheckpoint);
+        driver?.observeTransition(false);
+        record('render-accepted', { renderId: receipt.renderId, revision: receipt.readContext.revision, pathname: location.pathname, sameHost: host === document.querySelector('[data-storystick-astro-host]') });
+        root.render(_jsx(Controls, {}));
+    }
+    function reportLocation(receipt, info) {
+        reportedLocation = location.href;
+        const params = new URLSearchParams(location.search);
+        for (const key of [...params.keys()])
+            if (key.startsWith('_ss_'))
+                params.delete(key);
+        const presentation = { readContext: receipt.readContext, renderId: receipt.renderId, pathname: location.pathname };
+        notifyRouterTransition({ pathname: location.pathname, browserPathname: location.pathname,
+            search: params.toString(), hash: location.hash,
+            commandId: info && typeof info === 'object' ? commands.get(info) : undefined, presentation });
+    }
+    const gate = createAstroRenderGate({
+        readReceipt: (doc = document) => {
+            const rendered = readRender(doc);
+            return rendered?.config.projectId === config.projectId ? rendered.receipt : null;
+        },
+        readContext: () => previewRuntime.getState().session?.readContext,
+        readUrl: () => location.href,
+        commit,
+        reject(reason, destination) {
+            record('swap-rejected', { reason, pathname: destination.pathname });
+            driver?.observeTransition(false);
+            const context = previewRuntime.getState().session?.readContext;
+            const key = `${context?.contextId}:${context?.revision}:${renderLocation(destination)}`;
+            if (reason === 'context' && context && !retries.has(key)) {
+                retries.add(key);
+                // The native router aborts its prior navigation. The microtask runs
+                // after the rejected swap and cannot acknowledge that retained body.
+                queueMicrotask(() => { if (!disposed)
+                    void transition(destination.href); });
+            }
+            else
+                fail('The preview could not render the requested page.', destination.href);
+        },
+    });
+    async function transition(destination, history = 'replace', commandId) {
+        if (disposed)
+            return;
+        try {
+            const url = new URL(destination, location.href);
+            if (url.origin !== location.origin)
+                throw new Error('STORYSTICK_NAVIGATION_ORIGIN');
+            // Astro otherwise skips the fetch for a same-page destination with a hash.
+            url.searchParams.set('_ss_refresh', createPreviewRequestId());
+            const info = {};
+            commands.set(info, commandId);
+            record('navigation-requested', { pathname: url.pathname, commandId });
+            await navigate(url.pathname + url.search + url.hash, { history, info });
+        }
+        catch (error) {
+            record('navigation-error', { message: String(error) });
+            fail('The preview request failed.', destination);
+        }
+    }
+    const navigation = createAstroNavigation(transition);
+    document.addEventListener('astro:before-preparation', ((event) => {
+        if (!commands.has(event.info))
+            navigation.invalidate();
+        latestDestination = event.to.href;
+        gate.prepare(event.signal);
+        driver?.observeTransition(true);
+        setStandaloneOverlaySuspended(true);
+        record('before-preparation', { pathname: event.to.pathname });
+    }), { signal: lifetime.signal });
+    document.addEventListener('astro:before-swap', ((event) => gate.beforeSwap(event)), { signal: lifetime.signal });
+    document.addEventListener('astro:after-swap', () => gate.afterSwap(), { signal: lifetime.signal });
+    const reportSameDocumentLocation = () => {
+        navigation.invalidate();
+        // Native hash/history navigation may not perform an Astro swap. Reuse only
+        // the already installed receipt, never manufacture another server render.
+        if (!renderError && currentReceipt && aligned(currentReceipt) && location.href !== reportedLocation &&
+            renderLocation(currentReceipt.renderedUrl) === renderLocation(location.href)) {
+            latestDestination = location.href;
+            reportLocation(currentReceipt);
+            record('same-document-location', { hash: location.hash });
+        }
+    };
+    window.addEventListener('hashchange', reportSameDocumentLocation, { signal: lifetime.signal });
+    window.addEventListener('popstate', reportSameDocumentLocation, { signal: lifetime.signal });
+    const navigateHandler = navigation.navigate;
+    const reloadHandler = (mode, options) => { navigation.invalidate(); if (mode === 'hard')
+        location.reload();
+    else
+        void transition(renderError ? retryUrl : location.href, 'replace', options.commandId); };
+    setNavigateHandler(navigateHandler);
+    setReloadHandler(reloadHandler);
+    let runtimeHandle;
+    let lastState = '';
+    const update = () => {
+        const state = previewRuntime.getState();
+        const context = state.session?.readContext;
+        const stateKey = `${state.state}:${state.error?.code}:${context?.revision}`;
+        if (lastState !== stateKey) {
+            lastState = stateKey;
+            record('runtime-state', { state: state.state, errorCode: state.error?.code, revision: context?.revision });
+        }
+        if (disposed)
+            return;
+        if (state.state !== 'authenticated' || !state.previewToken || !context) {
+            stopWatch?.();
+            stopWatch = undefined;
+            driver?.dispose();
+            driver = null;
+            watchCount = 0;
+            currentWatchKey = '';
+            currentClientKey = '';
+            return;
+        }
+        const key = `${state.sessionId}:${context.contextId}:${context.revision}`;
+        const clientKey = `${key}:${state.previewToken}`;
+        if (currentClientKey !== clientKey) {
+            currentClientKey = clientKey;
+            previewRuntime.setHttpClient(createInternalClient({
+                schema: { contractVersion: 2, fingerprint: 'query-schema.v2.preview-control-only', stories: {} },
+                projectId: config.projectId, publishableKey: config.publishableKey, endpoint: config.endpoint,
+                requestContext: { previewToken: state.previewToken, previewReadContext: context,
+                    previewSessionId: state.sessionId, previewQueryConsumer: 'client-cache', previewObservationId: state.sessionId,
+                    variantId: state.variantId, releaseId: state.releaseId },
+            }));
+        }
+        if (currentWatchKey !== key) {
+            currentWatchKey = key;
+            stopWatch?.();
+            driver?.dispose();
+            watchCount = 0;
+            const watch = createPreviewProjectionGenerationWatch(state.client, state.sessionId);
+            const receipt = readRender()?.receipt;
+            driver = createPreviewGenerationRefresh({ delayMs: 50,
+                initialCheckpoint: aligned(receipt) && isPreviewProjectionGenerationSignal(receipt.projectionCheckpoint) ? receipt.projectionCheckpoint : null,
+                refresh: () => driver?.dispatch(() => {
+                    if (canRefreshPresentedPreviewContext(adapter.getSnapshot(), window.parent !== window))
+                        void transition(renderError ? retryUrl : latestDestination);
+                    else
+                        driver?.observeTransition(false);
+                }),
+                setTimer: (callback, ms) => window.setTimeout(callback, ms), clearTimer: window.clearTimeout,
+            });
+            if (watch) {
+                watchCount = 1;
+                record('watch-started', { count: watchCount, revision: context.revision });
+                stopWatch = watch.subscribe(value => {
+                    if (isPreviewProjectionGenerationSignal(value)) {
+                        record('projection', { generation: value.generation, status: value.status, projectedThroughSeq: value.projectedThroughSeq });
+                        driver?.observe(value);
+                    }
+                }, () => driver?.resynchronize());
+            }
+            gate.initial();
+            if (recoverAdmission) {
+                recoverAdmission = false;
+                initialRecoveryLaunched = true;
+                record('admission-recovery');
+                void transition(location.href);
+            }
+        }
+    };
+    const unsubscribe = previewRuntime.subscribe(update);
+    if (!window.__ssPreviewProvenanceRuntimeInstalled) {
+        const reporter = document.createElement('script');
+        reporter.src = '/api/storystick/provenance-runtime';
+        reporter.dataset.storystickPreviewProvenanceRuntime = '';
+        document.head.append(reporter);
+    }
+    disposeBoot = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        lifetime.abort();
+        navigation.dispose();
+        gate.dispose();
+        unsubscribe();
+        stopWatch?.();
+        driver?.dispose();
+        runtimeHandle?.teardown();
+        clearReceipt?.();
+        if (getNavigateHandler() === navigateHandler)
+            setNavigateHandler(null);
+        if (getReloadHandler() === reloadHandler)
+            setReloadHandler(null);
+        root.unmount();
+        previewRuntime.dispose();
+        watchCount = 0;
+        booted = false;
+        record('disposed');
+    };
+    window.addEventListener('pagehide', event => {
+        if (event.persisted) {
+            stopWatch?.();
+            stopWatch = undefined;
+            driver?.dispose();
+            driver = null;
+            watchCount = 0;
+            currentWatchKey = '';
+            record('suspended');
+        }
+        else
+            disposeBoot?.();
+    }, { signal: lifetime.signal });
+    window.addEventListener('pageshow', event => {
+        if (event.persisted) {
+            update();
+            driver?.resynchronize();
+            record('resumed');
+        }
+    }, { signal: lifetime.signal });
+    const initialized = previewRuntime.init({ projectId: config.projectId, gatewaySyncUrl: config.gatewaySyncUrl, tokenRoute: '/api/storystick/preview/token' });
+    runtimeHandle = await bootIframeRuntime();
+    await initialized;
+    if (disposed) {
+        runtimeHandle?.teardown();
+        return;
+    }
+    update();
+    if (renderError && !initialRecoveryLaunched)
+        fail(renderError);
+}

package/dist/components/File.astro

@@ -0,0 +1,9 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+import { resolveFile, type StorystickFileField, type ResolveFileOptions } from '@storystick/media';
+import { cleanPreviewAttributes } from '../text.js';
+interface Props extends Omit<HTMLAttributes<'a'>, 'href' | 'download' | 'type'> { file: StorystickFileField | null | undefined; options?: ResolveFileOptions }
+const { file, options, ...attributes } = Astro.props;
+const resolved = resolveFile(file, options);
+---
+{resolved.status === 'ok' ? <a {...cleanPreviewAttributes(attributes)} {...resolved.props}><slot>{resolved.filename}</slot></a> : <slot name="fallback" />}