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

package/dist/cache-tags.js

@@ -0,0 +1,12 @@
+import { createHash } from 'node:crypto';
+import { normalizePathname } from '@storystick/client/normalize-pathname';
+/** Internal tags share one bounded representation at read and invalidation. */
+export function storystickCacheTag(tag) {
+    const prefix = 'storystick:pathname:';
+    const canonical = tag.startsWith(prefix)
+        ? prefix + normalizePathname(tag.slice(prefix.length))
+        : tag;
+    return canonical.length <= 256
+        ? canonical
+        : `storystick:sha256:${createHash('sha256').update(canonical).digest('hex')}`;
+}

package/dist/clean.d.ts

@@ -0,0 +1 @@
+export { stripPreviewProvenance } from '@storystick/types/preview-provenance';

package/dist/clean.js

@@ -0,0 +1 @@
+export { stripPreviewProvenance } from '@storystick/types/preview-provenance';

package/dist/code-version.d.ts

@@ -0,0 +1,29 @@
+type EnvLike = Record<string, string | undefined>;
+export declare const STORYSTICK_UNKNOWN_CODE_VERSION = "dev-unknown";
+/** Opt-in, deployment-specific identity used by schema-generation pairing. */
+export declare function resolveStorystickApplicationBuildId(input?: {
+    readonly env?: EnvLike;
+}): string | undefined;
+/** Build-system supplied SHA-256 of the deployed application artifact. */
+export declare function resolveStorystickApplicationBuildDigest(input?: {
+    readonly env?: EnvLike;
+}): string | undefined;
+/**
+ * Browser-visible deploy signature. This is the fallback path for apps
+ * that mount the client component directly.
+ */
+export declare function resolveStorystickBrowserCodeVersion(input?: {
+    readonly codeVersion?: string;
+    readonly env?: EnvLike;
+}): string;
+/**
+ * Server-visible deploy signature. The root Next export uses this from
+ * Server Components and passes the resolved value into the client runtime,
+ * keeping Preview snapshots and RSC sidecars on one codeVersion without
+ * requiring user-written props.
+ */
+export declare function resolveStorystickServerCodeVersion(input?: {
+    readonly codeVersion?: string;
+    readonly env?: EnvLike;
+}): string;
+export {};

package/dist/code-version.js

@@ -0,0 +1,48 @@
+import { isContentShapeBuildId } from '@storystick/types';
+export const STORYSTICK_UNKNOWN_CODE_VERSION = 'dev-unknown';
+/** Opt-in, deployment-specific identity used by schema-generation pairing. */
+export function resolveStorystickApplicationBuildId(input = {}) {
+    const value = present((input.env ?? process.env).STORYSTICK_APP_BUILD_ID);
+    if (value !== undefined && !isContentShapeBuildId(value)) {
+        throw new TypeError('STORYSTICK_APP_BUILD_ID must be an app:-prefixed URL-safe identifier of at most 255 characters.');
+    }
+    return value;
+}
+/** Build-system supplied SHA-256 of the deployed application artifact. */
+export function resolveStorystickApplicationBuildDigest(input = {}) {
+    const value = present((input.env ?? process.env).STORYSTICK_APP_BUILD_DIGEST);
+    if (value !== undefined && !/^[a-f0-9]{64}$/.test(value)) {
+        throw new TypeError('STORYSTICK_APP_BUILD_DIGEST must be a lowercase SHA-256 hex digest.');
+    }
+    return value;
+}
+function present(value) {
+    return value && value.length > 0 ? value : undefined;
+}
+/**
+ * Browser-visible deploy signature. This is the fallback path for apps
+ * that mount the client component directly.
+ */
+export function resolveStorystickBrowserCodeVersion(input = {}) {
+    const env = input.env ?? process.env;
+    return (present(input.codeVersion) ??
+        present(env.NEXT_PUBLIC_STORYSTICK_CODE_VERSION) ??
+        present(env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA) ??
+        STORYSTICK_UNKNOWN_CODE_VERSION);
+}
+/**
+ * Server-visible deploy signature. The root Next export uses this from
+ * Server Components and passes the resolved value into the client runtime,
+ * keeping Preview snapshots and RSC sidecars on one codeVersion without
+ * requiring user-written props.
+ */
+export function resolveStorystickServerCodeVersion(input = {}) {
+    const env = input.env ?? process.env;
+    return (present(input.codeVersion) ??
+        present(env.STORYSTICK_CODE_VERSION) ??
+        present(env.NEXT_BUILD_ID) ??
+        present(env.VERCEL_GIT_COMMIT_SHA) ??
+        present(env.NEXT_PUBLIC_STORYSTICK_CODE_VERSION) ??
+        present(env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA) ??
+        STORYSTICK_UNKNOWN_CODE_VERSION);
+}

package/dist/file.d.ts

@@ -0,0 +1 @@
+export { StorystickFile, resolveFile, type FileStatus, type ResolveFileOptions, type ResolvedStorystickFile, type StorystickFileComponentProps, type StorystickFileFailure, type StorystickFileFallback, type StorystickFileField, type StorystickFileProps, } from '@storystick/react/file';

package/dist/file.js

@@ -0,0 +1 @@
+export { StorystickFile, resolveFile, } from '@storystick/react/file';

package/dist/i18n-seo.d.ts

@@ -0,0 +1 @@
+export * from '@storystick/client/seo';

package/dist/i18n-seo.js

@@ -0,0 +1 @@
+export * from '@storystick/client/seo';

package/dist/image.d.ts

@@ -0,0 +1,11 @@
+import { resolveImage } from '@storystick/react/image';
+import type { ResolveImageOptions, StorystickImageField, StorystickImageProps } from '@storystick/media';
+import type { ImageProps as NextImageProps } from 'next/image';
+export { resolveImage };
+/** The native renderer is framework-neutral; Next adds only Next Image props. */
+export { StorystickImage, type StorystickImageComponentProps, type StorystickImageFailure, type StorystickImageFallback, } from '@storystick/react/image';
+export type GetNextImagePropsOptions = ResolveImageOptions & {
+    unoptimized?: boolean;
+};
+export declare function getNextImageProps(image: StorystickImageField | null | undefined, options?: GetNextImagePropsOptions): (Pick<NextImageProps, 'src' | 'alt' | 'width' | 'height' | 'sizes' | 'unoptimized' | 'blurDataURL' | 'placeholder'> & Pick<StorystickImageProps, 'data-ss-e'>) | null;
+export type { ResolvedStorystickImage, StorystickAsset, StorystickAssetSidecar, StorystickImageField, } from '@storystick/media';

package/dist/image.js

@@ -0,0 +1,22 @@
+import { resolveImage } from '@storystick/react/image';
+export { resolveImage };
+/** The native renderer is framework-neutral; Next adds only Next Image props. */
+export { StorystickImage, } from '@storystick/react/image';
+export function getNextImageProps(image, options = {}) {
+    const resolved = resolveImage(image, options);
+    if (resolved.status !== 'ok')
+        return null;
+    const props = resolved.props;
+    return {
+        src: props.src,
+        alt: props.alt,
+        width: props.width,
+        height: props.height,
+        ...(props.sizes ? { sizes: props.sizes } : {}),
+        ...(resolved.blurDataURL
+            ? { blurDataURL: resolved.blurDataURL, placeholder: 'blur' }
+            : {}),
+        ...('data-ss-e' in props ? { 'data-ss-e': props['data-ss-e'] } : {}),
+        unoptimized: options.unoptimized ?? true,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './rendering.js';
+export { useQuery } from './query.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+// The server entry shares these primitives without re-exporting the client hook.
+export * from './rendering.js';
+export { useQuery } from './query.js';

package/dist/index.react-server.d.ts

@@ -0,0 +1,3 @@
+export * from './rendering.js';
+import type { StorystickProps } from './storystick.js';
+export declare function Storystick(props?: StorystickProps): Promise<import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>>;

package/dist/index.react-server.js

@@ -0,0 +1,12 @@
+// Server-only assembly of the existing mount. Client imports keep the same
+// entry and never pull next/headers or credentials into their bundle.
+export * from './rendering.js';
+import { renderStorystick } from './storystick.js';
+import { readPreviewServerRenderReceipt } from './server-runtime.js';
+export async function Storystick(props = {}) {
+    const { projectId, endpoint, gatewaySyncUrl, publishableKey, basePath, codeVersion } = props;
+    return renderStorystick({
+        projectId, endpoint, gatewaySyncUrl, publishableKey, basePath, codeVersion,
+        previewServerRenderReceipt: await readPreviewServerRenderReceipt(projectId),
+    });
+}

package/dist/link.d.ts

@@ -0,0 +1,10 @@
+import * as React from 'react';
+import NextLink from 'next/link';
+import type { StorystickLinkProps as ReactStorystickLinkProps } from '@storystick/react/link';
+export type StorystickLinkProps = ReactStorystickLinkProps & {
+    readonly prefetch?: React.ComponentProps<typeof NextLink>['prefetch'];
+};
+/** Next router adapter for the framework-neutral Storystick link. */
+export declare function StorystickLink({ prefetch, ...props }: StorystickLinkProps): React.ReactElement;
+export { resolveLink } from '@storystick/react/link';
+export type { StorystickLinkDocument, StorystickLinkOptions, StorystickLinkValue, } from '@storystick/react/link';

package/dist/link.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import NextLink from 'next/link';
+import { StorystickLinkAdapter, } from '@storystick/react/internal/link-adapter';
+/** Next router adapter for the framework-neutral Storystick link. */
+export function StorystickLink({ prefetch, ...props }) {
+    return (_jsx(StorystickLinkAdapter, { ...props, internalComponent: NextLink, internalComponentProps: { prefetch } }));
+}
+export { resolveLink } from '@storystick/react/link';

package/dist/preview/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `@storystick/next/preview` — server-only PreviewGrant route adapters.
+ *
+ * Mounted by customers in their App Router as one catch-all route:
+ *
+ *   // app/api/storystick/[...action]/route.ts
+ *   import { createRouteHandler } from '@storystick/next/preview'
+ *   const storystick = createRouteHandler()
+ *   export const GET = storystick.GET
+ *   export const POST = storystick.POST
+ *
+ * Server-only by design: the root `@storystick/next` entry MUST NOT re-export
+ * from here. These handlers import `next/headers::cookies` + `draftMode` and
+ * server-side grant exchange machinery; pulling them into the root entry would drag
+ * server-only code into Server Components that import `createServerClient` /
+ * `fetchDocument` / `fetchQuery`.
+ */
+import 'server-only';
+export { createRouteHandler } from './route-handler.js';
+export { createStorystickPreviewHandler } from './route-initial.js';
+export { createStorystickPreviewTokenHandler } from './route-token.js';
+export { createStorystickPreviewDisableHandler } from './route-disable.js';
+export { createStorystickPreviewAuthoringHandler } from './route-authoring.js';
+export { createStorystickPreviewProvenanceRuntimeHandler } from './route-provenance-runtime.js';
+export type { RouteHandlerOptions, RouteHandlers, } from './route-handler.js';
+export type { PreviewHandlerOptions } from './route-initial.js';
+export type { PreviewTokenHandlerOptions } from './route-token.js';
+export type { PreviewDisableHandlerOptions } from './route-disable.js';
+export type { PreviewProvenanceRuntimeHandlerOptions } from './route-provenance-runtime.js';

package/dist/preview/index.js

@@ -0,0 +1,24 @@
+/**
+ * `@storystick/next/preview` — server-only PreviewGrant route adapters.
+ *
+ * Mounted by customers in their App Router as one catch-all route:
+ *
+ *   // app/api/storystick/[...action]/route.ts
+ *   import { createRouteHandler } from '@storystick/next/preview'
+ *   const storystick = createRouteHandler()
+ *   export const GET = storystick.GET
+ *   export const POST = storystick.POST
+ *
+ * Server-only by design: the root `@storystick/next` entry MUST NOT re-export
+ * from here. These handlers import `next/headers::cookies` + `draftMode` and
+ * server-side grant exchange machinery; pulling them into the root entry would drag
+ * server-only code into Server Components that import `createServerClient` /
+ * `fetchDocument` / `fetchQuery`.
+ */
+import 'server-only';
+export { createRouteHandler } from './route-handler.js';
+export { createStorystickPreviewHandler } from './route-initial.js';
+export { createStorystickPreviewTokenHandler } from './route-token.js';
+export { createStorystickPreviewDisableHandler } from './route-disable.js';
+export { createStorystickPreviewAuthoringHandler } from './route-authoring.js';
+export { createStorystickPreviewProvenanceRuntimeHandler } from './route-provenance-runtime.js';

package/dist/preview/internal.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Internal helpers shared by the Preview activation and token routes.
+ *
+ * Server-only. Not re-exported from `@storystick/next/preview`.
+ *
+ * ADR-131 C9 — endpoint resolution flows through `resolveInfra()` which
+ * shares its `resolveProject` cache with `server.ts` (same per-process
+ * Map in `@storystick/client/resolve.ts`). The `STORYSTICK_ENDPOINT` env
+ * escape hatch is preserved as an undocumented self-host override.
+ */
+import type { NextRequest } from 'next/server';
+export type PreviewTransport = {
+    endpoint: string;
+    projectId: string;
+    apiKey: string;
+};
+export declare function createPreviewControlClient(token: string): Promise<{
+    context: <T = unknown>(input?: {
+        sessionId?: string;
+        includeProjectionCheckpoint?: boolean;
+        includeRouting?: boolean;
+    }) => Promise<T>;
+    session: (input: {
+        sessionId: string;
+        mode?: "routing-only";
+    }) => Promise<unknown>;
+    draft: (input: {
+        sessionId: string;
+        draftDocumentId?: string;
+        locale?: string;
+        contextId: string;
+        revision: number;
+        fallbackPolicy?: "none" | "explicit";
+    }) => Promise<unknown>;
+    changeContext: (input: {
+        commandId: string;
+        expectedContextId: string;
+        expectedRevision: number;
+        perspective: import("@storystick/types/preview-query-targeting").PreviewPerspective | null;
+    }) => Promise<{
+        status: "applied" | "conflict";
+    }>;
+}>;
+export declare function getPreviewTransport(): Promise<PreviewTransport>;
+/**
+ * Resolve the browser-visible origin for customer preview requests.
+ *
+ * Next's `nextUrl.origin` is not always browser-visible: under
+ * `next start --hostname 0.0.0.0`, it can become `http://0.0.0.0:*`
+ * even though the iframe requested `http://localhost:*`. Prefer Host,
+ * falling back to Next's origin only if Host is absent or malformed.
+ */
+export declare function resolvePreviewRequestOrigin(request: NextRequest): string;
+/** Reset the transport singleton (testing only). */
+export declare function _resetPreviewTransport(): void;
+/**
+ * Allow tests to inject a transport without going through env vars or
+ * `resolveProject`. The override is consumed by `getPreviewTransport`
+ * on next call. Returns a dispose function that restores prior state.
+ */
+export declare function _setPreviewTransport(t: PreviewTransport | null): void;

package/dist/preview/internal.js

@@ -0,0 +1,97 @@
+/**
+ * Internal helpers shared by the Preview activation and token routes.
+ *
+ * Server-only. Not re-exported from `@storystick/next/preview`.
+ *
+ * ADR-131 C9 — endpoint resolution flows through `resolveInfra()` which
+ * shares its `resolveProject` cache with `server.ts` (same per-process
+ * Map in `@storystick/client/resolve.ts`). The `STORYSTICK_ENDPOINT` env
+ * escape hatch is preserved as an undocumented self-host override.
+ */
+import { resolveInfra } from '@storystick/client/adapter';
+import { previewControlClient } from '@storystick/preview/server/control-client';
+let _previewTransport = null;
+export async function createPreviewControlClient(token) {
+    const transport = await getPreviewTransport();
+    return previewControlClient(transport.endpoint, token);
+}
+export async function getPreviewTransport() {
+    if (_previewTransport)
+        return _previewTransport;
+    const apiKey = process.env.STORYSTICK_API_KEY;
+    if (!apiKey) {
+        throw new Error('StorystickError: No STORYSTICK_API_KEY found.\n' +
+            'Add it to your .env.local (ss_sk_live_* for server-side reads):\n\n' +
+            '  STORYSTICK_API_KEY=ss_sk_live_...\n');
+    }
+    const projectId = process.env.STORYSTICK_PROJECT_ID;
+    if (!projectId) {
+        throw new Error('StorystickError: No STORYSTICK_PROJECT_ID found.\n' +
+            'Add it to your .env.local — it is the 8-char shortId visible in your\n' +
+            'Hub project URL at /p/<label>-<shortId>:\n\n' +
+            '  STORYSTICK_PROJECT_ID=a3k9m2x7\n' +
+            '  STORYSTICK_API_KEY=ss_sk_live_...\n');
+    }
+    const directEndpoint = process.env.STORYSTICK_ENDPOINT;
+    const infra = await resolveInfra(projectId, {
+        endpoint: directEndpoint || undefined,
+    });
+    _previewTransport = {
+        endpoint: infra.endpoint,
+        projectId,
+        apiKey,
+    };
+    return _previewTransport;
+}
+function firstHeaderValue(value) {
+    if (value === null)
+        return null;
+    const first = value.split(',')[0]?.trim();
+    return first && first.length > 0 ? first : null;
+}
+function safeHostHeaderOrigin(protocol, host) {
+    // Host is allowed to carry a port and bracketed IPv6 literal, but not URL
+    // delimiters/userinfo/control characters. If it is malformed, fail closed
+    // to Next's own origin instead of reflecting an arbitrary header string.
+    if (/[\u0000-\u001F\u007F\s/@\\]/.test(host))
+        return null;
+    try {
+        const url = new URL(`${protocol}://${host}`);
+        if (url.hostname.length === 0)
+            return null;
+        return url.origin;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve the browser-visible origin for customer preview requests.
+ *
+ * Next's `nextUrl.origin` is not always browser-visible: under
+ * `next start --hostname 0.0.0.0`, it can become `http://0.0.0.0:*`
+ * even though the iframe requested `http://localhost:*`. Prefer Host,
+ * falling back to Next's origin only if Host is absent or malformed.
+ */
+export function resolvePreviewRequestOrigin(request) {
+    const protocol = request.nextUrl.protocol === 'https:' ? 'https' : 'http';
+    const host = firstHeaderValue(request.headers.get('host'));
+    if (host !== null) {
+        const origin = safeHostHeaderOrigin(protocol, host);
+        if (origin !== null)
+            return origin;
+    }
+    return request.nextUrl.origin;
+}
+/** Reset the transport singleton (testing only). */
+export function _resetPreviewTransport() {
+    _previewTransport = null;
+}
+/**
+ * Allow tests to inject a transport without going through env vars or
+ * `resolveProject`. The override is consumed by `getPreviewTransport`
+ * on next call. Returns a dispose function that restores prior state.
+ */
+export function _setPreviewTransport(t) {
+    _previewTransport = t;
+}

package/dist/preview/preview-request-identity.d.ts

@@ -0,0 +1,4 @@
+import type { ReadPreviewProvenanceSessionOptions, ResolvePreviewProvenanceRouteIdentityOptions, PreviewProvenanceRouteIdentity } from '@storystick/preview/server/provenance-runtime';
+export type { ReadPreviewProvenanceSessionOptions, ResolvePreviewProvenanceRouteIdentityOptions, PreviewProvenanceRouteIdentity } from '@storystick/preview/server/provenance-runtime';
+export declare function readPreviewProvenanceSessionId(options?: ReadPreviewProvenanceSessionOptions): Promise<string | null>;
+export declare function resolvePreviewProvenanceRouteIdentity(options: ResolvePreviewProvenanceRouteIdentityOptions): Promise<PreviewProvenanceRouteIdentity>;

package/dist/preview/preview-request-identity.js

@@ -0,0 +1,63 @@
+import { getPreviewTransport } from "./internal.js";
+import { cookies, headers } from 'next/headers';
+import { readPreviewGrantCookie, } from '@storystick/preview/server/extract-token';
+export async function readPreviewProvenanceSessionId(options = {}) {
+    try {
+        const sessionId = options.sessionId ?? null;
+        const requestHeaders = await headers();
+        const host = requestHeaders.get('x-forwarded-host') ?? requestHeaders.get('host');
+        if (!host)
+            return null;
+        const requestOrigin = `${requestHeaders.get('x-forwarded-proto') ?? inferProtocol(host)}://${host}`;
+        const grant = await readPreviewGrantCookie((await cookies()), { ...await getPreviewTransport(), requestOrigin });
+        return grant ? sessionId : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function resolvePreviewProvenanceRouteIdentity(options) {
+    const routeUrl = await derivePreviewProvenanceRouteUrl(options);
+    return {
+        routeUrl,
+        routeHash: await sha256Hex(routeUrl),
+        variantId: null,
+    };
+}
+async function derivePreviewProvenanceRouteUrl(options) {
+    try {
+        const requestHeaders = await headers();
+        const host = requestHeaders.get('x-forwarded-host') ?? requestHeaders.get('host');
+        const proto = requestHeaders.get('x-forwarded-proto') ?? inferProtocol(host);
+        const origin = host ? `${proto}://${host}` : '';
+        const path = options.fallbackPathname ?? '/';
+        return withPreviewSessionQuery(`${origin}${path || '/'}`, options.sessionId);
+    }
+    catch {
+        return withPreviewSessionQuery(options.fallbackPathname ?? '/', options.sessionId);
+    }
+}
+function inferProtocol(host) {
+    if (host === null)
+        return 'https';
+    const normalized = host.toLowerCase();
+    return normalized.startsWith('localhost') ||
+        normalized.startsWith('127.0.0.1') ||
+        normalized.startsWith('[::1]') ||
+        normalized.startsWith('::1')
+        ? 'http'
+        : 'https';
+}
+function withPreviewSessionQuery(routeUrl, sessionId) {
+    if (routeUrl.includes('_ss_session='))
+        return routeUrl;
+    const separator = routeUrl.includes('?') ? '&' : '?';
+    return `${routeUrl}${separator}_ss_session=${encodeURIComponent(sessionId)}`;
+}
+async function sha256Hex(input) {
+    const bytes = new TextEncoder().encode(input);
+    const digest = await crypto.subtle.digest('SHA-256', bytes);
+    return Array.from(new Uint8Array(digest))
+        .map((byte) => byte.toString(16).padStart(2, '0'))
+        .join('');
+}

package/dist/preview/provenance-config.d.ts

@@ -0,0 +1,42 @@
+import type { StorystickPreviewProvenanceConfig } from '@storystick/preview/server/provenance-runtime';
+export type { StorystickPreviewProvenanceConfig } from '@storystick/preview/server/provenance-runtime';
+import { type ReactElement } from 'react';
+import type { PreviewProvenanceEditableTextPathManifest } from '@storystick/preview/provenance';
+type EnvLike = Record<string, string | undefined>;
+export interface ResolveStorystickPreviewProvenanceConfigOptions {
+    readonly env?: EnvLike;
+    readonly sessionId?: string;
+}
+export interface ResolveStorystickPreviewProvenanceManifestOptions {
+    readonly importer: () => Promise<unknown>;
+    /** The module the importer stands for. Reported verbatim in diagnostics. */
+    readonly specifier?: string;
+    /** Overrides the console reporter. */
+    readonly onDiagnostic?: (diagnostic: PreviewProvenanceManifestDiagnostic) => void;
+}
+export type PreviewProvenanceManifestFailure = 
+/** The module did not resolve at all — missing file, or missing alias. */
+'module-unresolved'
+/** The module resolved but carries no usable manifest export. */
+ | 'module-malformed';
+export interface PreviewProvenanceManifestDiagnostic {
+    readonly reason: PreviewProvenanceManifestFailure;
+    readonly specifier: string;
+    readonly cause?: string;
+}
+export declare function unstable_resolveStorystickPreviewProvenanceConfig(options?: ResolveStorystickPreviewProvenanceConfigOptions): StorystickPreviewProvenanceConfig;
+export declare function unstable_renderStorystickPreviewNoIndex(config?: Pick<StorystickPreviewProvenanceConfig, 'enabled'>): ReactElement | null;
+/**
+ * Loads the generated provenance manifest.
+ *
+ * The manifest is what makes rendered text editable. When it fails to load,
+ * every text-level binding silently disappears and the preview reads as "this
+ * page has nothing editable" rather than "the manifest did not load" — the two
+ * are indistinguishable from the outside, which is why the failure is reported
+ * here instead of being swallowed.
+ *
+ * Resolution still fails closed to an empty manifest: a manifest that will not
+ * load must never take a production render down with it.
+ */
+export declare function unstable_resolveStorystickPreviewProvenanceManifest(options: ResolveStorystickPreviewProvenanceManifestOptions): Promise<PreviewProvenanceEditableTextPathManifest>;
+export declare function formatPreviewProvenanceManifestFailure(diagnostic: PreviewProvenanceManifestDiagnostic): string;

package/dist/preview/provenance-config.js

@@ -0,0 +1,132 @@
+import { createElement } from 'react';
+import { resolveStorystickServerCodeVersion } from '../code-version.js';
+const DEFAULT_PREVIEW_PROVENANCE_SESSION_ID = 'storystick_preview_provenance';
+const PREVIEW_PROVENANCE_SESSION_ID_ENV = 'STORYSTICK_PREVIEW_PROVENANCE_SESSION_ID';
+function present(value) {
+    return value && value.length > 0 ? value : undefined;
+}
+export function unstable_resolveStorystickPreviewProvenanceConfig(options = {}) {
+    const env = options.env ?? process.env;
+    const enabled = env.STORYSTICK_PREVIEW_PROVENANCE === '1';
+    const fixtureEnabled = enabled && env.STORYSTICK_PREVIEW_PROVENANCE_FIXTURE === '1';
+    const sessionId = options.sessionId ??
+        present(env[PREVIEW_PROVENANCE_SESSION_ID_ENV]) ??
+        DEFAULT_PREVIEW_PROVENANCE_SESSION_ID;
+    return {
+        enabled,
+        fixtureEnabled,
+        sessionId,
+        codeVersion: resolveStorystickServerCodeVersion({ env }),
+        fixture: fixtureEnabled
+            ? {
+                enabled: true,
+                sessionId,
+            }
+            : null,
+    };
+}
+export function unstable_renderStorystickPreviewNoIndex(config = unstable_resolveStorystickPreviewProvenanceConfig()) {
+    return config.enabled
+        ? createElement('meta', {
+            name: 'robots',
+            content: 'noindex,nofollow,noarchive',
+        })
+        : null;
+}
+/**
+ * Loads the generated provenance manifest.
+ *
+ * The manifest is what makes rendered text editable. When it fails to load,
+ * every text-level binding silently disappears and the preview reads as "this
+ * page has nothing editable" rather than "the manifest did not load" — the two
+ * are indistinguishable from the outside, which is why the failure is reported
+ * here instead of being swallowed.
+ *
+ * Resolution still fails closed to an empty manifest: a manifest that will not
+ * load must never take a production render down with it.
+ */
+export async function unstable_resolveStorystickPreviewProvenanceManifest(options) {
+    const importer = options.importer;
+    const specifier = options.specifier ?? 'Storystick site definition';
+    const report = options.onDiagnostic ?? reportPreviewProvenanceManifestFailure;
+    let module;
+    try {
+        module = await importer();
+    }
+    catch (error) {
+        report({
+            reason: 'module-unresolved',
+            specifier,
+            cause: describeError(error),
+        });
+        return EMPTY_PREVIEW_PROVENANCE_MANIFEST;
+    }
+    const manifest = isRecord(module)
+        ? module.previewProvenanceEditableTextPathManifest
+        : undefined;
+    if (!isRecord(manifest)) {
+        report({
+            reason: 'module-malformed',
+            specifier,
+            cause: `expected an exported \`previewProvenanceEditableTextPathManifest\` object, found ${describeShape(manifest)}`,
+        });
+        return EMPTY_PREVIEW_PROVENANCE_MANIFEST;
+    }
+    return manifest;
+}
+const EMPTY_PREVIEW_PROVENANCE_MANIFEST = {};
+/**
+ * Reported once per reason in production — the same broken deploy re-renders
+ * thousands of routes and one legible line per cause is enough. In development
+ * every attempt reports, so the message comes back after each reload until the
+ * manifest actually loads.
+ */
+const reportedPreviewProvenanceManifestFailures = new Set();
+function reportPreviewProvenanceManifestFailure(diagnostic) {
+    if (process.env.NODE_ENV === 'production') {
+        if (reportedPreviewProvenanceManifestFailures.has(diagnostic.reason))
+            return;
+        reportedPreviewProvenanceManifestFailures.add(diagnostic.reason);
+    }
+    console.error(formatPreviewProvenanceManifestFailure(diagnostic));
+}
+export function formatPreviewProvenanceManifestFailure(diagnostic) {
+    const code = diagnostic.reason === 'module-unresolved'
+        ? 'PREVIEW_PROVENANCE_MANIFEST_UNRESOLVED'
+        : 'PREVIEW_PROVENANCE_MANIFEST_MALFORMED';
+    const headline = diagnostic.reason === 'module-unresolved'
+        ? `could not load "${diagnostic.specifier}".`
+        : `loaded "${diagnostic.specifier}", but it exports no usable manifest.`;
+    const fix = diagnostic.reason === 'module-unresolved'
+        ? [
+            '  1. Generate it — `storystick sync` writes generated/storystick/preview-provenance.ts.',
+            '  2. Pass the generated definition to createSite once, in your Storystick configuration.',
+        ]
+        : [
+            '  1. Regenerate it — `storystick sync` rewrites generated/storystick/preview-provenance.ts.',
+            '  2. Do not hand-edit the generated file; a partial or stale copy loads without exporting the manifest.',
+        ];
+    return [
+        `StorystickError: ${code} — ${headline}`,
+        'Preview provenance is enabled (STORYSTICK_PREVIEW_PROVENANCE=1), so this is not a no-op: every text-level binding is dropped. The page still renders, and nothing on it is editable.',
+        ...(diagnostic.cause ? [`Cause: ${diagnostic.cause}`] : []),
+        'Fix:',
+        ...fix,
+    ].join('\n');
+}
+function describeError(error) {
+    if (error instanceof Error) {
+        return error.message.length > 0 ? error.message : error.name;
+    }
+    return String(error);
+}
+function describeShape(value) {
+    if (value === undefined)
+        return 'no such export';
+    if (value === null)
+        return 'null';
+    return Array.isArray(value) ? 'an array' : typeof value;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}