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

package/dist/components/Image.astro

@@ -0,0 +1,18 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+import { resolveImage, type StorystickImageField, type ResolveImageOptions } from '@storystick/media';
+import { cleanPreviewAttributes } from '../text.js';
+interface Props extends Omit<HTMLAttributes<'img'>, 'src' | 'srcset' | 'sizes' | 'width' | 'height' | 'alt'> { image: StorystickImageField | null | undefined; options?: ResolveImageOptions; responsive?: boolean; alt?: string }
+const { image, options = {}, responsive = true, alt, ...attributes } = Astro.props;
+const resolved = resolveImage(alt !== undefined && image ? { ...image, alt } : image, { ...options,
+  ...(responsive && options.sizes === undefined ? { sizes: attributes.loading === 'eager' ? '100vw' : 'auto, 100vw' } : {}),
+  ...(!responsive ? { widths: [], sizes: undefined } : {}),
+});
+const props = resolved.status === 'ok' ? resolved.props : null;
+const { srcSet, style, ...native } = props ?? {};
+const position = style && 'objectPosition' in style ? style.objectPosition : undefined;
+const nativeStyle = typeof attributes.style === 'string' ? `${position ? `object-position:${position};` : ''}${attributes.style}` : position || attributes.style ? { ...(position ? { 'object-position': position } : {}), ...attributes.style } : undefined;
+const output = { ...cleanPreviewAttributes(attributes), ...native, srcset: srcSet, style: nativeStyle,
+  loading: attributes.loading ?? (responsive ? props?.loading : 'eager'), decoding: attributes.decoding ?? props?.decoding };
+---
+{props ? <img {...output} /> : <slot name="fallback" />}

package/dist/components/Link.astro

@@ -0,0 +1,14 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+import { resolveLink, resolveDocumentLink, type LinkDocument, type LinkValue, type LinkOptions } from '@storystick/types';
+import { previewText, cleanPreviewAttributes } from '../text.js';
+type Source = { link: (LinkValue & { text?: string; title?: string | null }) | null | undefined; document?: never; href?: never } | { document: LinkDocument | null | undefined; link?: never; href?: never } | { href: string | null | undefined; link?: never; document?: never };
+type Props = Omit<HTMLAttributes<'a'>, 'href' | 'target' | 'rel'> & Source & { options?: LinkOptions & { fallbackLabel?: string } };
+const { link, document, href, options, title, ...attributes } = Astro.props;
+const resolved = document ? resolveDocumentLink(document, options) : resolveLink(link ?? (href == null ? null : { href }), options);
+const text = previewText(link?.text ?? options?.fallbackLabel);
+const labelAttrs = resolved.props['data-ss-e'] ? {} : text.attributes;
+const diagnostic = ['ok', 'external', 'asset'].includes(resolved.status) ? undefined : resolved.status;
+const selectedTitle = Object.hasOwn(Astro.props, 'title') ? title : link?.title;
+---
+<a {...cleanPreviewAttributes(attributes)} {...resolved.props} title={previewText(selectedTitle).text || undefined} data-ss-link-status={diagnostic} {...labelAttrs}><slot>{text.text}</slot></a>

package/dist/components/PreviewHost.astro

@@ -0,0 +1,12 @@
+---
+import { ClientRouter } from 'astro:transitions';
+import { siteRuntime, type SiteHandle } from '../server.js';
+interface Props { site: SiteHandle; debug?: boolean }
+const { site, debug = false } = Astro.props;
+const bootstrap = await siteRuntime(site).bootstrap(Astro);
+---
+{bootstrap && <>
+  <ClientRouter />
+  <div data-storystick-astro-host data-storystick-debug={debug ? '' : undefined} transition:persist="storystick-astro-host"></div>
+  <script type="application/json" data-storystick-astro-render set:html={JSON.stringify(bootstrap).replaceAll('<', '\\u003c')} />
+</>}

package/dist/components/PublicDeliveryReceipt.astro

@@ -0,0 +1,6 @@
+---
+import { PUBLIC_RENDER_RECEIPT_ID, serializePublicRenderReceipt, type PublicRenderReceiptV1 } from '@storystick/client';
+interface Props { receipt: PublicRenderReceiptV1 | null }
+const { receipt } = Astro.props;
+---
+{receipt && <script is:inline id={PUBLIC_RENDER_RECEIPT_ID} type="application/json" set:html={serializePublicRenderReceipt(receipt)} />}

package/dist/components/PublicHost.astro

@@ -0,0 +1,3 @@
+---
+// A public build contributes no markup, scripts, CSS or request reads.
+---

package/dist/components/RichText.astro

@@ -0,0 +1,7 @@
+---
+import { richTextNodes, type RichTextOptions } from '../rich-text.js';
+import RichTextNode from './RichTextNode.astro';
+interface Props extends RichTextOptions {}
+const nodes = richTextNodes(Astro.props);
+---
+{nodes.length ? nodes.map(node => <RichTextNode node={node} />) : <slot name="fallback" />}

package/dist/components/RichTextInline.astro

@@ -0,0 +1,6 @@
+---
+import type { RichTextOptions } from '../rich-text.js';
+import RichText from './RichText.astro';
+interface Props extends Omit<RichTextOptions, 'inline'> {}
+---
+<RichText {...Astro.props} inline><slot name="fallback" slot="fallback" /></RichText>

package/dist/components/RichTextNode.astro

@@ -0,0 +1,7 @@
+---
+import type { RenderNode } from '../rich-text.js';
+interface Props { node: RenderNode }
+const { node } = Astro.props;
+const Tag = node.tag;
+---
+{node.text !== undefined ? node.text : Tag ? <Tag {...node.props}>{node.children?.map(child => <Astro.self node={child} />)}</Tag> : node.children?.map(child => <Astro.self node={child} />)}

package/dist/components/Slice.astro

@@ -0,0 +1,8 @@
+---
+import type { HTMLTag, HTMLAttributes } from 'astro/types';
+import { sliceAttributes, type SliceData } from '../slices.js';
+import { cleanPreviewAttributes } from '../text.js';
+interface Props extends HTMLAttributes<'section'> { slice: SliceData; siblings?: readonly unknown[]; as?: HTMLTag }
+const { slice, siblings, as: Tag = 'section', ...attributes } = Astro.props;
+---
+<Tag {...sliceAttributes(slice, siblings)} {...cleanPreviewAttributes(attributes)}><slot /></Tag>

package/dist/components/SliceZone.astro

@@ -0,0 +1,20 @@
+---
+import type { AstroComponentFactory } from 'astro/runtime/server/index.js';
+import { prepareContentSource, prepareSlice, readContentOrigin, buildSliceProvenance, type ContentSource, type SliceData } from '../slices.js';
+import type { SliceContractRegistry, SliceRenderFailure } from '@storystick/types';
+interface Props { slices?: readonly SliceData[] | null; components: Record<string, AstroComponentFactory>; source?: ContentSource; context?: unknown; contracts?: SliceContractRegistry; fallback?: AstroComponentFactory; onRenderFailure?: (failure: SliceRenderFailure) => void }
+const { slices: input, components, source, context, contracts, fallback: Fallback, onRenderFailure } = Astro.props;
+const slices = prepareContentSource(input, source) ?? [];
+const rendered = slices.map((value, index) => {
+  const prepared = prepareSlice(value, index, Object.keys(components), contracts);
+  if (prepared.failure) {
+    onRenderFailure?.(prepared.failure);
+    if (!Fallback) throw new TypeError(`Astro slice at index ${index} could not render (${prepared.failure.reason}).`);
+    return { Component: Fallback, props: { failure: prepared.failure } };
+  }
+  const slice = prepared.slice;
+  const content = readContentOrigin(slice);
+  return { Component: components[slice._type]!, props: { slice, siblings: slices, zones: content?.zones, bindings: slice._key ? buildSliceProvenance(content ?? source?.document, slice) : undefined, context } };
+});
+---
+{rendered.map(({ Component, props }) => <Component {...props} />)}

package/dist/components/Storystick.astro

@@ -0,0 +1,6 @@
+---
+import PreviewHost from 'virtual:storystick/preview';
+import type { SiteHandle } from '../server.js';
+interface Props { site: SiteHandle; debug?: boolean }
+---
+<PreviewHost {...Astro.props}/>

package/dist/components/Text.astro

@@ -0,0 +1,8 @@
+---
+import type { HTMLTag, HTMLAttributes } from 'astro/types';
+import { previewText, cleanPreviewAttributes } from '../text.js';
+interface Props extends Omit<HTMLAttributes<'span'>, 'children'> { value?: string | number | boolean | null; as?: HTMLTag }
+const { value, as: Tag = 'span', ...attributes } = Astro.props;
+const text = previewText(value);
+---
+<Tag {...cleanPreviewAttributes(attributes)} {...text.attributes}>{text.text}</Tag>

package/dist/components/Video.astro

@@ -0,0 +1,13 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+import { resolveVideo, type StorystickVideoField, type ResolveVideoOptions } from '@storystick/media/video';
+import { cleanPreviewAttributes } from '../text.js';
+interface Props extends Omit<HTMLAttributes<'video'>, 'src' | 'poster' | 'width' | 'height'> { video: StorystickVideoField | null | undefined; options?: ResolveVideoOptions }
+const { video, options, ...attributes } = Astro.props;
+const resolved = resolveVideo(video, options);
+const props = resolved.status === 'ok' ? resolved.props : null;
+const { crossOrigin, playsInline, ...native } = props ?? {};
+const output = { ...cleanPreviewAttributes(attributes), ...native, crossorigin: attributes.crossorigin ?? crossOrigin,
+  playsinline: attributes.playsinline ?? playsInline, controls: attributes.controls ?? props?.controls, preload: attributes.preload ?? props?.preload };
+---
+{resolved.status === 'ok' && props ? <video {...output}>{resolved.tracks.map(track => track.status === 'ok' && <track {...track.props}/>)}<slot /></video> : <slot name="fallback" />}

package/dist/components/Zone.astro

@@ -0,0 +1,11 @@
+---
+import { readContentOrigin } from '../slices.js';
+import type { AstroComponentFactory } from 'astro/runtime/server/index.js';
+import RichText from './RichText.astro';
+import SliceZone from './SliceZone.astro';
+interface Props { zone?: { value: unknown; path: string }; components: Record<string, AstroComponentFactory>; context?: unknown }
+const { zone, components, context } = Astro.props;
+const value = zone?.value;
+const rich = typeof value === 'string' || readContentOrigin(value)?.kind === 'richtext' || !!value && typeof value === 'object' && 'type' in value && value.type === 'doc';
+---
+{rich ? <RichText content={value} components={{ embeds: components }} context={context} /> : Array.isArray(value) ? <SliceZone slices={value} components={components} context={context} /> : <slot name="fallback" />}

package/dist/components/index.d.ts

@@ -0,0 +1,12 @@
+export { default as Storystick } from './Storystick.astro';
+export { default as Text } from './Text.astro';
+export { default as Image } from './Image.astro';
+export { default as File } from './File.astro';
+export { default as Video } from './Video.astro';
+export { default as Link } from './Link.astro';
+export { default as Slice } from './Slice.astro';
+export { default as SliceZone } from './SliceZone.astro';
+export { default as PublicDeliveryReceipt } from './PublicDeliveryReceipt.astro';
+export { default as RichText } from './RichText.astro';
+export { default as RichTextInline } from './RichTextInline.astro';
+export { default as Zone } from './Zone.astro';

package/dist/components/index.js

@@ -0,0 +1,12 @@
+export { default as Storystick } from './Storystick.astro';
+export { default as Text } from './Text.astro';
+export { default as Image } from './Image.astro';
+export { default as File } from './File.astro';
+export { default as Video } from './Video.astro';
+export { default as Link } from './Link.astro';
+export { default as Slice } from './Slice.astro';
+export { default as SliceZone } from './SliceZone.astro';
+export { default as PublicDeliveryReceipt } from './PublicDeliveryReceipt.astro';
+export { default as RichText } from './RichText.astro';
+export { default as RichTextInline } from './RichTextInline.astro';
+export { default as Zone } from './Zone.astro';

package/dist/control.d.ts

@@ -0,0 +1,3 @@
+import type { APIContext } from 'astro';
+import type { ServerConfiguration } from "./server.js";
+export declare function createControlHandler(configuration: () => Promise<ServerConfiguration>): (ctx: APIContext) => Promise<Response>;

package/dist/control.js

@@ -0,0 +1,123 @@
+import { previewControlErrorResponse, previewInitialRouteErrorResponse, previewErrorResponse } from '@storystick/preview/server/control-errors';
+import { previewControlClient } from '@storystick/preview/server/control-client';
+import { previewProvenanceRuntimeScript } from '@storystick/preview/provenance';
+import { createPreviewScope, writePreviewScopeToSearchParams } from '@storystick/preview/identity';
+import { activatePreviewGrantForServer, parsePreviewActivation, assertSafePreviewRedirect, isSafePreviewSessionId, exchangePreviewAuthoringAdmissionForServer, classifyPreviewGrantError, PreviewGrantExchangeError, PreviewActivationError, PreviewRedirectError } from '@storystick/preview/server/grant';
+import { resolvePreviewGrantAccess, readPreviewGrantCookie } from '@storystick/preview/server/extract-token';
+import { buildPreviewGrantCookieFromActivation, setPreviewGrantCookieOnResponse } from '@storystick/preview/server/route-session-cookie';
+import { readPreviewContextCommand, readBoundedPreviewJson } from '@storystick/preview/server/read-context-command';
+const reader = (ctx) => ({ getAll: () => (ctx.request.headers.get('cookie') ?? '').split(';')
+        .map(part => part.slice(0, part.indexOf('=')).trim()).filter(Boolean)
+        .map(name => ({ name, value: ctx.cookies.get(name)?.value ?? '' })) });
+const json = (body, status = 200) => Response.json(body, { status, headers: { 'Cache-Control': 'private, no-store' } });
+function control(token, config) { return previewControlClient(config.endpoint, token); }
+export function createControlHandler(configuration) {
+    return async function handleControl(ctx) {
+        const action = ctx.params.action;
+        const config = { ...await configuration(), requestOrigin: ctx.url.origin };
+        try {
+            const methods = { preview: ['GET'], 'preview/token': ['POST'], 'preview/context': ['GET', 'POST'], 'preview/disable': ['POST'], 'preview/authoring': ['POST'], 'provenance-runtime': ['GET'] };
+            if (!action || !methods[action])
+                return json({ code: 'PREVIEW_ROUTE_UNSUPPORTED' }, 404);
+            if (!methods[action].includes(ctx.request.method))
+                return new Response(null, { status: 405, headers: { Allow: methods[action].join(', '), 'Cache-Control': 'no-store' } });
+            if (ctx.request.method === 'POST' && ctx.request.headers.get('origin') !== ctx.url.origin)
+                return json({ code: 'PREVIEW_ORIGIN_MISMATCH' }, 403);
+            if (action === 'preview' && ctx.request.method === 'GET') {
+                const sessionId = ctx.url.searchParams.get('_ss_session');
+                if (!isSafePreviewSessionId(sessionId))
+                    return json({ code: 'PREVIEW_SESSION_MISSING' }, 400);
+                const activation = parsePreviewActivation(ctx.url.searchParams.get('_ss_activation'));
+                const target = assertSafePreviewRedirect(ctx.url.searchParams.get('redirect') || '/', '');
+                const previewScope = createPreviewScope({ variantId: ctx.url.searchParams.get('_ss_variant'), releaseId: ctx.url.searchParams.get('_ss_release') });
+                const result = await activatePreviewGrantForServer({ ...config, ...activation, sessionId });
+                if (result.projectId !== config.projectId || result.previewOrigin !== ctx.url.origin ||
+                    result.sessionId !== sessionId || result.grantId !== activation.grantId || result.grantExpiresAt <= Date.now())
+                    throw new Error('PREVIEW_GRANT_BINDING_MISMATCH');
+                await setPreviewGrantCookieOnResponse({ response: ctx, reader: reader(ctx), scope: config,
+                    requestUrl: ctx.url.href, basePath: '', sequence: result.admissionSequence,
+                    cookie: buildPreviewGrantCookieFromActivation(result, Date.now(), config.applicationBuildId) });
+                const destination = new URL(target, ctx.url.origin);
+                for (const key of [...destination.searchParams.keys()])
+                    if (key.startsWith('_ss_') && key !== '_ss_draft')
+                        destination.searchParams.delete(key);
+                destination.searchParams.set('_ss_session', sessionId);
+                writePreviewScopeToSearchParams(destination.searchParams, previewScope);
+                return new Response(null, { status: 302, headers: { Location: destination.href, 'Cache-Control': 'no-store', 'Referrer-Policy': 'no-referrer' } });
+            }
+            if (action === 'preview/disable' && ctx.request.method === 'POST') {
+                try {
+                    const fields = await resolvePreviewGrantAccess(reader(ctx), config);
+                    if (fields) {
+                        const command = await readPreviewContextCommand(ctx.request);
+                        if (command) {
+                            if (command.perspective !== null)
+                                return json({ code: 'PREVIEW_CONTEXT_INVALID' }, 400);
+                            const result = await control(fields.token, config).changeContext(command);
+                            if (result.status === 'conflict')
+                                return json({ code: 'PREVIEW_CONTEXT_CONFLICT' }, 409);
+                        }
+                    }
+                }
+                catch (error) {
+                    if (![401, 403].includes(error.status) && error.code !== 'storystick/CONTENT_SHAPE_RELOAD_REQUIRED')
+                        throw error;
+                }
+                // Exit uses the shared context command. The admission cookie remains valid for other views.
+                return json({ status: 'disabled' });
+            }
+            const fields = await resolvePreviewGrantAccess(reader(ctx), config);
+            if (!fields)
+                return json({ code: 'PREVIEW_GRANT_MISSING' }, 401);
+            const client = control(fields.token, config);
+            if (action === 'preview/token' && ctx.request.method === 'POST') {
+                const sessionId = ctx.url.searchParams.get('_ss_session');
+                if (!isSafePreviewSessionId(sessionId))
+                    return json({ code: 'PREVIEW_SESSION_MISSING' }, 400);
+                await client.context({ sessionId });
+                return json({ token: fields.token, expiresAt: fields.tokenExpiresAt,
+                    refreshAfter: Date.now() + Math.max(1000, (fields.tokenExpiresAt - Date.now()) * .8), sessionId, projectId: fields.projectId });
+            }
+            if (action === 'preview/context') {
+                if (ctx.request.method === 'GET')
+                    return json(await client.context({}));
+                const command = await readPreviewContextCommand(ctx.request);
+                if (!command)
+                    return json({ code: 'PREVIEW_CONTEXT_INVALID' }, 400);
+                const result = await client.changeContext(command);
+                return json(result, result.status === 'conflict' ? 409 : 200);
+            }
+            if (action === 'preview/authoring' && ctx.request.method === 'POST') {
+                const renewal = await readBoundedPreviewJson(ctx.request);
+                if (!renewal || Array.isArray(renewal) || typeof renewal !== 'object' ||
+                    Object.keys(renewal).some(key => !['admissionId', 'fileDelegationId'].includes(key)) ||
+                    Boolean(renewal.admissionId) !== Boolean(renewal.fileDelegationId) ||
+                    Object.values(renewal).some(v => typeof v !== 'string' || !v.length || v.length > 256))
+                    return json({ code: 'PREVIEW_AUTHORING_REQUEST_INVALID' }, 400);
+                const grant = await readPreviewGrantCookie(reader(ctx), config);
+                const result = await exchangePreviewAuthoringAdmissionForServer({ ...config,
+                    grantToken: grant.grantToken, contentShapeCapability: grant.contentShapeCapability, ...renewal });
+                if (result.projectShortId !== config.projectId)
+                    throw new Error('PREVIEW_PROJECT_MISMATCH');
+                return json(result);
+            }
+            if (action === 'provenance-runtime' && ctx.request.method === 'GET')
+                return new Response(previewProvenanceRuntimeScript, {
+                    headers: { 'Cache-Control': 'no-store', 'Content-Type': 'application/javascript', 'X-Content-Type-Options': 'nosniff' },
+                });
+            return json({ code: 'PREVIEW_ROUTE_UNSUPPORTED' }, 404);
+        }
+        catch (error) {
+            console.error('[storystick/astro control]', error.code ?? error.message);
+            if (error instanceof PreviewActivationError)
+                return previewErrorResponse(400, 'PREVIEW_ACTIVATION_INVALID', 'Preview activation is missing or malformed.', { category: 'validation', recoverable: true });
+            if (error instanceof PreviewRedirectError)
+                return previewErrorResponse(400, 'PREVIEW_REDIRECT_UNSAFE', 'Unsafe Preview redirect.', { category: 'validation', recoverable: true });
+            if (error instanceof PreviewGrantExchangeError) {
+                const failure = classifyPreviewGrantError(error, action === 'preview' ? 'activate' : action === 'preview/authoring' ? 'authoring' : 'exchange');
+                return action === 'preview' ? previewInitialRouteErrorResponse(ctx.request, failure) : previewErrorResponse(failure);
+            }
+            return previewControlErrorResponse(error);
+        }
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export { createSite, AstroPreviewError } from './server.js';
+export type { Site, SiteHandle, SiteOptions, RequestContext } from './server.js';
+export { resolveImage, resolveFile } from '@storystick/media';
+export { resolveVideo } from '@storystick/media/video';
+export { resolveLink } from '@storystick/client';
+export { sliceAttributes } from './slices.js';
+export { previewText } from './text.js';
+export { toText } from './rich-text.js';
+export type { RichTextOptions, RichTextRegistry } from './rich-text.js';
+export type { SliceData, SliceComponentProps } from './slices.js';
+export type { SliceContract, SliceContractRegistry, SliceRenderFailure, LinkDocument } from '@storystick/types';
+export { sitemapResponse, sitemapIndexResponse } from './sitemap.js';
+export { createPublicationHandler } from './publication.js';
+export type { PublicationBatch, PublicationHandlerOptions } from './publication.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+export { createSite, AstroPreviewError } from './server.js';
+export { resolveImage, resolveFile } from '@storystick/media';
+export { resolveVideo } from '@storystick/media/video';
+export { resolveLink } from '@storystick/client';
+export { sliceAttributes } from './slices.js';
+export { previewText } from './text.js';
+export { toText } from './rich-text.js';
+export { sitemapResponse, sitemapIndexResponse } from './sitemap.js';
+export { createPublicationHandler } from './publication.js';

package/dist/integration.d.ts

@@ -0,0 +1,10 @@
+import type { AstroIntegration } from 'astro';
+export interface StorystickIntegrationOptions {
+    /** Server module exporting `site = createSite(...)`. Relative to the Astro root. */
+    site: string;
+    /** A separate SSR Preview deployment. Public builds omit its routes and JavaScript. */
+    preview?: {
+        origin: string;
+    };
+}
+export default function storystick(options: StorystickIntegrationOptions): AstroIntegration;

package/dist/integration.js

@@ -0,0 +1,59 @@
+import { fileURLToPath } from 'node:url';
+export default function storystick(options) {
+    const previewOrigin = options.preview ? new URL(options.preview.origin) : null;
+    if (previewOrigin && (!['http:', 'https:'].includes(previewOrigin.protocol) || previewOrigin.href !== previewOrigin.origin + '/')) {
+        throw new TypeError('Storystick Preview requires an exact HTTP(S) origin.');
+    }
+    const ownRoute = fileURLToPath(new URL(previewOrigin ? './routes/control.js' : './routes/readback.js', import.meta.url));
+    const errorRoute = fileURLToPath(new URL('./routes/error.astro', import.meta.url));
+    let projectRoot;
+    let hasServerRoutes = false;
+    return {
+        name: '@storystick/astro',
+        hooks: {
+            'astro:config:setup'({ config, updateConfig, addMiddleware, injectRoute, injectScript }) {
+                projectRoot = config.root;
+                if (config.base !== '/')
+                    throw new TypeError('Storystick Astro currently requires base: "/".');
+                const sitePath = fileURLToPath(new URL(options.site, config.root));
+                updateConfig({
+                    ...(previewOrigin ? { security: { allowedDomains: [...config.security.allowedDomains, {
+                                    protocol: previewOrigin.protocol.slice(0, -1), hostname: previewOrigin.hostname,
+                                    port: previewOrigin.port || (previewOrigin.protocol === 'https:' ? '443' : '80'),
+                                }] } } : {}),
+                    vite: { resolve: { dedupe: ['react', 'react-dom'] }, plugins: [{
+                                name: 'storystick-site',
+                                resolveId(id) { if (id === 'virtual:storystick/site' || id === 'virtual:storystick/preview')
+                                    return '\0' + id; },
+                                load(id) { if (id === '\0virtual:storystick/preview')
+                                    return `export { default } from ${JSON.stringify(fileURLToPath(new URL(previewOrigin ? './components/PreviewHost.astro' : './components/PublicHost.astro', import.meta.url)))};`; if (id === '\0virtual:storystick/site')
+                                    return `export { site } from ${JSON.stringify(sitePath)}; export const previewOrigin = ${JSON.stringify(previewOrigin?.origin ?? null)};`; },
+                            }] },
+                });
+                hasServerRoutes = !!previewOrigin || config.output === 'server';
+                if (hasServerRoutes)
+                    injectRoute({ pattern: '/api/storystick/[...action]', entrypoint: ownRoute, prerender: false });
+                if (!previewOrigin)
+                    return;
+                addMiddleware({ entrypoint: '@storystick/astro/internal/middleware', order: 'pre' });
+                injectRoute({ pattern: '/storystick-preview-error', entrypoint: errorRoute, prerender: false });
+                injectScript('page', 'import { boot } from "@storystick/astro/browser"; boot();');
+            },
+            'astro:config:done'({ config }) {
+                if (previewOrigin && (!config.adapter || config.output !== 'server'))
+                    throw new TypeError('Storystick Preview requires output: "server" and an SSR adapter.');
+            },
+            'astro:routes:resolved'({ routes }) {
+                if (!hasServerRoutes)
+                    return;
+                for (const route of routes) {
+                    const entrypoint = fileURLToPath(new URL(route.entrypoint, projectRoot));
+                    if (entrypoint !== ownRoute && entrypoint !== errorRoute &&
+                        (route.pattern?.startsWith('/api/storystick/') || route.pathname === '/storystick-preview-error')) {
+                        throw new TypeError(`Route "${route.entrypoint}" (${route.origin}) collides with the reserved Storystick Preview route "${route.pattern}". Expected "${ownRoute}" or "${errorRoute}".`);
+                    }
+                }
+            },
+        },
+    };
+}

package/dist/middleware.d.ts

@@ -0,0 +1 @@
+export declare const onRequest: import("astro").MiddlewareHandler;

package/dist/middleware.js

@@ -0,0 +1,34 @@
+import { defineMiddleware } from 'astro:middleware';
+import { site, previewOrigin } from 'virtual:storystick/site';
+import { setPreviewOrigin, setRenderFailure, siteRuntime, AstroPreviewError } from './server.js';
+export const onRequest = defineMiddleware(async (ctx, next) => {
+    if (!previewOrigin)
+        return next();
+    if (ctx.url.origin !== previewOrigin)
+        return new Response('Preview origin mismatch', { status: 403, headers: { 'Cache-Control': 'no-store' } });
+    setPreviewOrigin(ctx, previewOrigin);
+    const control = ctx.url.pathname.startsWith('/api/storystick/');
+    let response;
+    try {
+        if (!control && ctx.url.pathname !== '/storystick-preview-error')
+            await siteRuntime(site).requestContext(ctx);
+        response = await next();
+        if (!control && ctx.request.method === 'GET' && response.headers.get('content-type')?.includes('text/html')) {
+            if (response.status >= 500 && ctx.url.pathname !== '/storystick-preview-error')
+                throw new Error('Preview render failed');
+            // A failed stream cannot carry a successful render receipt.
+            response = new Response(await response.text(), response);
+        }
+    }
+    catch (error) {
+        if (control || ctx.url.pathname === '/storystick-preview-error')
+            throw error;
+        console.error('[storystick/astro render]', error instanceof Error ? error.message : 'Unknown render failure');
+        setRenderFailure(ctx, error);
+        response = await ctx.rewrite('/storystick-preview-error');
+        response = new Response(await response.text(), { status: error instanceof AstroPreviewError ? error.status : 500, headers: response.headers });
+    }
+    response.headers.set('Cache-Control', 'private, no-store');
+    response.headers.set('X-Robots-Tag', 'noindex, nofollow');
+    return response;
+});

package/dist/navigation.d.ts

@@ -0,0 +1,7 @@
+/** Context admission can finish after another gesture. Only the latest intent
+ * may start a native navigation; Astro owns cancellation once it has started. */
+export declare function createAstroNavigation(transition: (destination: string, history: 'push' | 'replace', commandId?: string) => Promise<void>): {
+    navigate: (pathname: string, options?: import("@storystick/preview/nav-handler").NavigateHandlerOptions | undefined) => Promise<void>;
+    invalidate(): void;
+    dispose(): void;
+};

package/dist/navigation.js

@@ -0,0 +1,34 @@
+import { previewRuntime } from '@storystick/preview/runtime/store';
+import { writePreviewScopeToSearchParams } from '@storystick/preview/identity';
+/** Context admission can finish after another gesture. Only the latest intent
+ * may start a native navigation; Astro owns cancellation once it has started. */
+export function createAstroNavigation(transition) {
+    let revision = 0;
+    let disposed = false;
+    const navigate = async (...[path, options]) => {
+        if (disposed)
+            return;
+        const intent = ++revision;
+        let perspective = previewRuntime.getState().session?.readContext.perspective;
+        if (options?.contextCommand && options.commandId) {
+            const context = await previewRuntime.changePerspective({ ...options.contextCommand,
+                commandId: options.commandId, perspective: options.scope }, '/api/storystick/preview/context');
+            if (!context || disposed || intent !== revision)
+                return;
+            perspective = context.perspective;
+        }
+        const url = new URL(path, location.href);
+        // Template prototypes use admitted view routing; native links leave it.
+        const session = previewRuntime.getState().session;
+        if (session?.draftTarget?.kind === 'template')
+            url.searchParams.set('_ss_session', session.sessionId);
+        if (perspective)
+            writePreviewScopeToSearchParams(url.searchParams, perspective);
+        await transition(url.href, options?.history ?? 'replace', options?.commandId);
+    };
+    return {
+        navigate,
+        invalidate() { revision++; },
+        dispose() { disposed = true; revision++; },
+    };
+}

package/dist/publication.d.ts

@@ -0,0 +1,10 @@
+import { type PublicationEventV2 } from '@storystick/types/publication';
+export type PublicationBatch = PublicationEventV2;
+export interface PublicationHandlerOptions {
+    projectId: string;
+    secret: string | (() => string | undefined);
+    /** Enqueue returns accepted; completed means the invalidation/build activation
+     * finished. Neither certifies HTML: the publisher checks the renderer receipt. */
+    onPublish: (event: PublicationEventV2) => Promise<'accepted' | 'completed'>;
+}
+export declare function createPublicationHandler(options: PublicationHandlerOptions): (request: Request) => Promise<Response>;

package/dist/publication.js

@@ -0,0 +1,29 @@
+import { readSignedWebhook } from '@storystick/client/adapter';
+import { isPublicationEvent } from '@storystick/types/publication';
+export function createPublicationHandler(options) {
+    if (!options.projectId)
+        throw new TypeError('A publication handler requires projectId.');
+    return async (request) => {
+        const json = (value, status = 200) => Response.json(value, { status, headers: { 'Cache-Control': 'no-store' } });
+        if (request.method !== 'POST')
+            return new Response(null, { status: 405, headers: { Allow: 'POST', 'Cache-Control': 'no-store' } });
+        const secret = typeof options.secret === 'function' ? options.secret() : options.secret;
+        if (!secret)
+            return json({ error: 'webhook_secret_not_configured' }, 500);
+        const result = await readSignedWebhook(request, { secret });
+        if (!result.ok)
+            return json({ error: result.error }, result.status);
+        const event = result.payload;
+        if (!isPublicationEvent(event) || event.projectId !== options.projectId)
+            return json({ error: 'publication_invalid' }, 400);
+        try {
+            const effect = await options.onPublish(event);
+            if (effect !== 'accepted' && effect !== 'completed')
+                throw Error('Invalid effect acknowledgement');
+            return json({ version: 2, projectId: event.projectId, id: event.id, effect }, effect === 'accepted' ? 202 : 200);
+        }
+        catch {
+            return json({ error: 'publication_not_accepted' }, 503);
+        }
+    };
+}

package/dist/readback.d.ts

@@ -0,0 +1,14 @@
+import type { APIContext } from 'astro';
+export interface MigrationReadback {
+    projectId: string;
+    artifactId: string;
+    artifactDigest: string;
+    schemaVersion: string | null;
+    querySchemaFingerprint: string;
+    publication?: {
+        version: 2;
+        rendering: 'request' | 'static' | 'unqualified';
+        receipts: boolean;
+    };
+}
+export declare function createReadbackHandler(readback: () => Promise<MigrationReadback | null>): (ctx: Pick<APIContext, "params" | "request">) => Promise<Response>;

package/dist/readback.js

@@ -0,0 +1,18 @@
+export function createReadbackHandler(readback) {
+    return async (ctx) => {
+        const headers = { 'Cache-Control': 'no-store' };
+        if (!['health', 'migration-readback'].includes(ctx.params.action ?? ''))
+            return Response.json({ ok: false, error: 'not_found' }, { status: 404, headers });
+        if (ctx.request.method !== 'GET')
+            return new Response(null, { status: 405, headers: { ...headers, Allow: 'GET' } });
+        if (ctx.params.action === 'health')
+            return Response.json({ ok: true }, { headers });
+        try {
+            const migration = await readback();
+            return Response.json(migration ? { ok: true, migration } : { ok: false, error: 'migration_readback_not_configured' }, { status: migration ? 200 : 503, headers });
+        }
+        catch {
+            return Response.json({ ok: false, error: 'migration_readback_unavailable' }, { status: 503, headers });
+        }
+    };
+}

package/dist/render-gate.d.ts

@@ -0,0 +1,36 @@
+import { type PreviewReadContext } from '@storystick/types/preview-query-targeting';
+export interface AstroRenderReceipt {
+    readContext: PreviewReadContext;
+    renderId: string;
+    renderedUrl: string;
+    projectionCheckpoint?: unknown;
+}
+/** The view/session and refresh nonce select transport, not customer content. */
+export declare function renderLocation(value: string | URL): string;
+export declare function isAstroRenderReceipt(value: unknown): value is AstroRenderReceipt;
+type Swap<Document> = {
+    signal: AbortSignal;
+    from: URL;
+    to: URL;
+    newDocument: Document;
+    swap: () => void;
+    info?: unknown;
+};
+/** Astro owns navigation, cancellation and DOM replacement. This gate owns
+ * only the proof that its particular response was installed in this context.
+ * Checking inside swap matters: context can change during the old-page animation.
+ */
+export declare function createAstroRenderGate<Document>(options: {
+    readReceipt: (document?: Document) => unknown;
+    readContext: () => PreviewReadContext | null | undefined;
+    readUrl: () => string;
+    commit: (receipt: AstroRenderReceipt, info?: unknown) => void;
+    reject: (reason: 'context' | 'receipt' | 'destination', destination: URL) => void;
+}): {
+    prepare(signal: AbortSignal): void;
+    beforeSwap(event: Swap<Document>): void;
+    afterSwap(): boolean;
+    initial(): boolean;
+    dispose(): void;
+};
+export {};