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

package/dist/provenance/transformed-output-gate.d.ts

@@ -0,0 +1,161 @@
+import type { PreviewProvenanceCarrierPlan, ProvenanceId } from './types.js';
+export type PreviewTransformedOutputStatus = 'guaranteed' | 'derived-single' | 'derived-composite' | 'attribute-carrier-needed' | 'compiler-needed' | 'intervention-needed' | 'unsupported/absent';
+export type PreviewExpressionCaptureModality = 'text' | 'attr' | 'scope';
+export type PreviewExpressionSourceSetKind = 'single' | 'derived-single' | 'derived-composite' | 'unknown';
+export type PreviewExpressionTransformKind = 'identity' | 'uppercase' | 'concat' | 'truncate' | 'date-format' | 'number-format' | 'url-or-slug' | 'custom' | 'precomputed';
+export interface PreviewExpressionSourceRead extends ProvenanceId {
+    readonly readKey: string;
+}
+export interface PreviewExpressionCaptureRecord {
+    readonly contractVersion: 1;
+    readonly sourceReads: readonly PreviewExpressionSourceRead[];
+    readonly renderedPrimitive: string | number | boolean | null;
+    readonly modality: PreviewExpressionCaptureModality;
+    readonly sourceSetKind: PreviewExpressionSourceSetKind;
+    readonly transformKind: PreviewExpressionTransformKind;
+    readonly debugReason?: string;
+    readonly carrierPlan: PreviewProvenanceCarrierPlan | null;
+}
+export interface PreviewTransformedOutputCase {
+    readonly id: 'direct-text' | 'uppercase' | 'concat' | 'truncate' | 'date-formatting' | 'number-formatting' | 'url-slug' | 'href' | 'alt' | 'rich-text-split-across-marks' | 'duplicate-strings' | 'precomputed-view-model';
+    readonly status: PreviewTransformedOutputStatus;
+    readonly modality: PreviewExpressionCaptureModality;
+    readonly sourceSetKind: PreviewExpressionSourceSetKind;
+    readonly sourceProof: 'direct' | 'captured' | 'not-captured';
+    readonly carrierPlan: PreviewProvenanceCarrierPlan | null;
+    readonly reason: string;
+}
+export declare const PREVIEW_TRANSFORMED_OUTPUT_GATE_MATRIX: readonly [{
+    readonly id: "direct-text";
+    readonly status: "guaranteed";
+    readonly modality: "text";
+    readonly sourceSetKind: "single";
+    readonly sourceProof: "direct";
+    readonly carrierPlan: PreviewProvenanceCarrierPlan;
+    readonly reason: "Direct editorial text can use data-ss-p or coded text as a carrier after owner-map validation.";
+}, {
+    readonly id: "uppercase";
+    readonly status: "derived-single";
+    readonly modality: "text";
+    readonly sourceSetKind: "derived-single";
+    readonly sourceProof: "captured";
+    readonly carrierPlan: PreviewProvenanceCarrierPlan;
+    readonly reason: "A single-source transform is safe only when Expression Capture proves the source read.";
+}, {
+    readonly id: "concat";
+    readonly status: "derived-composite";
+    readonly modality: "scope";
+    readonly sourceSetKind: "derived-composite";
+    readonly sourceProof: "captured";
+    readonly carrierPlan: {
+        readonly kind: "future-scope";
+        readonly carrier: "scope-carrier";
+        readonly modality: "scope";
+        readonly anchorKind: "scope";
+        readonly status: "planned";
+        readonly previewOnly: true;
+        readonly markerPayload: "opaque-marker-id";
+        readonly reason: "Composite or structural outputs need group/scope ownership.";
+    };
+    readonly reason: "Multiple source reads must become composite/group/scope ownership, never a fake single-field overlay.";
+}, {
+    readonly id: "truncate";
+    readonly status: "compiler-needed";
+    readonly modality: "text";
+    readonly sourceSetKind: "unknown";
+    readonly sourceProof: "not-captured";
+    readonly carrierPlan: null;
+    readonly reason: "Destructive transforms can cut or move hidden markers and need captured expression causality.";
+}, {
+    readonly id: "date-formatting";
+    readonly status: "compiler-needed";
+    readonly modality: "text";
+    readonly sourceSetKind: "unknown";
+    readonly sourceProof: "not-captured";
+    readonly carrierPlan: null;
+    readonly reason: "Formatted dates are derived view output; coded text must not be written into date values.";
+}, {
+    readonly id: "number-formatting";
+    readonly status: "compiler-needed";
+    readonly modality: "text";
+    readonly sourceSetKind: "unknown";
+    readonly sourceProof: "not-captured";
+    readonly carrierPlan: null;
+    readonly reason: "Formatted numbers are derived view output and are not proven by marker survival.";
+}, {
+    readonly id: "url-slug";
+    readonly status: "unsupported/absent";
+    readonly modality: "attr";
+    readonly sourceSetKind: "unknown";
+    readonly sourceProof: "not-captured";
+    readonly carrierPlan: null;
+    readonly reason: "URLs, slugs, and pathnames must never receive coded text carriers.";
+}, {
+    readonly id: "href";
+    readonly status: "attribute-carrier-needed";
+    readonly modality: "attr";
+    readonly sourceSetKind: "derived-single";
+    readonly sourceProof: "captured";
+    readonly carrierPlan: {
+        readonly kind: "future-attribute";
+        readonly carrier: "attribute-output-carrier";
+        readonly modality: "attr:href";
+        readonly anchorKind: "attribute";
+        readonly status: "planned";
+        readonly previewOnly: true;
+        readonly markerPayload: "opaque-marker-id";
+        readonly reason: "URL and technical attributes need explicit attribute capture, not coded text.";
+    };
+    readonly reason: "href needs explicit attribute capture/carrier; Unicode text in the URL is forbidden.";
+}, {
+    readonly id: "alt";
+    readonly status: "attribute-carrier-needed";
+    readonly modality: "attr";
+    readonly sourceSetKind: "single";
+    readonly sourceProof: "captured";
+    readonly carrierPlan: PreviewProvenanceCarrierPlan;
+    readonly reason: "alt can be editorial, but it is still an attribute surface and needs an attribute carrier.";
+}, {
+    readonly id: "rich-text-split-across-marks";
+    readonly status: "guaranteed";
+    readonly modality: "text";
+    readonly sourceSetKind: "single";
+    readonly sourceProof: "direct";
+    readonly carrierPlan: PreviewProvenanceCarrierPlan;
+    readonly reason: "Rich text is supported at individual text-node granularity, not as a wrapper around the full JSON field.";
+}, {
+    readonly id: "duplicate-strings";
+    readonly status: "intervention-needed";
+    readonly modality: "scope";
+    readonly sourceSetKind: "unknown";
+    readonly sourceProof: "not-captured";
+    readonly carrierPlan: {
+        readonly kind: "future-scope";
+        readonly carrier: "scope-carrier";
+        readonly modality: "scope";
+        readonly anchorKind: "scope";
+        readonly status: "planned";
+        readonly previewOnly: true;
+        readonly markerPayload: "opaque-marker-id";
+        readonly reason: "Composite or structural outputs need group/scope ownership.";
+    };
+    readonly reason: "Equal rendered strings cannot be routed by value matching; they need explicit source identity or scope grouping.";
+}, {
+    readonly id: "precomputed-view-model";
+    readonly status: "unsupported/absent";
+    readonly modality: "text";
+    readonly sourceSetKind: "unknown";
+    readonly sourceProof: "not-captured";
+    readonly carrierPlan: null;
+    readonly reason: "A precomputed primitive without captured reads has no reliable source truth at render time.";
+}];
+export declare function transformedOutputCanProduceSingleFieldOverlay(output: Pick<PreviewTransformedOutputCase, 'status' | 'sourceSetKind' | 'sourceProof'>): boolean;
+export declare function classifyPreviewExpressionCapture(input: {
+    readonly sourceReads: readonly PreviewExpressionSourceRead[];
+    readonly renderedPrimitive: PreviewExpressionCaptureRecord['renderedPrimitive'];
+    readonly modality: PreviewExpressionCaptureModality;
+    readonly transformKind: PreviewExpressionTransformKind;
+    readonly carrierPlan?: PreviewProvenanceCarrierPlan | null;
+    readonly debugReason?: string;
+}): PreviewExpressionCaptureRecord;
+export declare function statusForExpressionCapture(capture: PreviewExpressionCaptureRecord): PreviewTransformedOutputStatus;

package/dist/provenance/transformed-output-gate.js

@@ -0,0 +1,171 @@
+/**
+ * Conserved deliberately: this matrix is the executable specification for
+ * the annotation seam (guaranteed vs carrier/compiler/intervention needed),
+ * not residue from DOM inference.
+ */
+import { createPreviewProvenanceAttributeCarrierPlan, createPreviewProvenanceCodedTextCarrierPlan, previewProvenanceFutureCarrierPlans, } from './carrier-plan.js';
+const directTextCarrierPlan = createPreviewProvenanceCodedTextCarrierPlan({
+    surface: 'direct-editorial-text',
+});
+const richTextCarrierPlan = createPreviewProvenanceCodedTextCarrierPlan({
+    surface: 'rich-text-text-node',
+});
+const altCarrierPlan = createPreviewProvenanceAttributeCarrierPlan({
+    modality: 'attr:alt',
+    anchorKind: 'attribute',
+});
+const hrefFutureCarrierPlan = previewProvenanceFutureCarrierPlans.find((plan) => plan.kind === 'future-attribute');
+const scopeFutureCarrierPlan = previewProvenanceFutureCarrierPlans.find((plan) => plan.kind === 'future-scope');
+export const PREVIEW_TRANSFORMED_OUTPUT_GATE_MATRIX = [
+    {
+        id: 'direct-text',
+        status: 'guaranteed',
+        modality: 'text',
+        sourceSetKind: 'single',
+        sourceProof: 'direct',
+        carrierPlan: directTextCarrierPlan,
+        reason: 'Direct editorial text can use data-ss-p or coded text as a carrier after owner-map validation.',
+    },
+    {
+        id: 'uppercase',
+        status: 'derived-single',
+        modality: 'text',
+        sourceSetKind: 'derived-single',
+        sourceProof: 'captured',
+        carrierPlan: directTextCarrierPlan,
+        reason: 'A single-source transform is safe only when Expression Capture proves the source read.',
+    },
+    {
+        id: 'concat',
+        status: 'derived-composite',
+        modality: 'scope',
+        sourceSetKind: 'derived-composite',
+        sourceProof: 'captured',
+        carrierPlan: scopeFutureCarrierPlan,
+        reason: 'Multiple source reads must become composite/group/scope ownership, never a fake single-field overlay.',
+    },
+    {
+        id: 'truncate',
+        status: 'compiler-needed',
+        modality: 'text',
+        sourceSetKind: 'unknown',
+        sourceProof: 'not-captured',
+        carrierPlan: null,
+        reason: 'Destructive transforms can cut or move hidden markers and need captured expression causality.',
+    },
+    {
+        id: 'date-formatting',
+        status: 'compiler-needed',
+        modality: 'text',
+        sourceSetKind: 'unknown',
+        sourceProof: 'not-captured',
+        carrierPlan: null,
+        reason: 'Formatted dates are derived view output; coded text must not be written into date values.',
+    },
+    {
+        id: 'number-formatting',
+        status: 'compiler-needed',
+        modality: 'text',
+        sourceSetKind: 'unknown',
+        sourceProof: 'not-captured',
+        carrierPlan: null,
+        reason: 'Formatted numbers are derived view output and are not proven by marker survival.',
+    },
+    {
+        id: 'url-slug',
+        status: 'unsupported/absent',
+        modality: 'attr',
+        sourceSetKind: 'unknown',
+        sourceProof: 'not-captured',
+        carrierPlan: null,
+        reason: 'URLs, slugs, and pathnames must never receive coded text carriers.',
+    },
+    {
+        id: 'href',
+        status: 'attribute-carrier-needed',
+        modality: 'attr',
+        sourceSetKind: 'derived-single',
+        sourceProof: 'captured',
+        carrierPlan: hrefFutureCarrierPlan,
+        reason: 'href needs explicit attribute capture/carrier; Unicode text in the URL is forbidden.',
+    },
+    {
+        id: 'alt',
+        status: 'attribute-carrier-needed',
+        modality: 'attr',
+        sourceSetKind: 'single',
+        sourceProof: 'captured',
+        carrierPlan: altCarrierPlan,
+        reason: 'alt can be editorial, but it is still an attribute surface and needs an attribute carrier.',
+    },
+    {
+        id: 'rich-text-split-across-marks',
+        status: 'guaranteed',
+        modality: 'text',
+        sourceSetKind: 'single',
+        sourceProof: 'direct',
+        carrierPlan: richTextCarrierPlan,
+        reason: 'Rich text is supported at individual text-node granularity, not as a wrapper around the full JSON field.',
+    },
+    {
+        id: 'duplicate-strings',
+        status: 'intervention-needed',
+        modality: 'scope',
+        sourceSetKind: 'unknown',
+        sourceProof: 'not-captured',
+        carrierPlan: scopeFutureCarrierPlan,
+        reason: 'Equal rendered strings cannot be routed by value matching; they need explicit source identity or scope grouping.',
+    },
+    {
+        id: 'precomputed-view-model',
+        status: 'unsupported/absent',
+        modality: 'text',
+        sourceSetKind: 'unknown',
+        sourceProof: 'not-captured',
+        carrierPlan: null,
+        reason: 'A precomputed primitive without captured reads has no reliable source truth at render time.',
+    },
+];
+export function transformedOutputCanProduceSingleFieldOverlay(output) {
+    if (output.sourceProof === 'not-captured')
+        return false;
+    return (output.status === 'guaranteed' ||
+        output.status === 'derived-single') && (output.sourceSetKind === 'single' ||
+        output.sourceSetKind === 'derived-single');
+}
+export function classifyPreviewExpressionCapture(input) {
+    const sourceSetKind = classifyExpressionSourceSetKind(input);
+    return {
+        contractVersion: 1,
+        sourceReads: input.sourceReads,
+        renderedPrimitive: input.renderedPrimitive,
+        modality: input.modality,
+        sourceSetKind,
+        transformKind: input.transformKind,
+        ...(input.debugReason ? { debugReason: input.debugReason } : {}),
+        carrierPlan: input.carrierPlan ?? null,
+    };
+}
+export function statusForExpressionCapture(capture) {
+    if (capture.sourceSetKind === 'unknown') {
+        return capture.transformKind === 'precomputed'
+            ? 'unsupported/absent'
+            : 'compiler-needed';
+    }
+    if (capture.modality === 'attr' &&
+        (capture.carrierPlan === null || capture.carrierPlan.status !== 'emitted')) {
+        return 'attribute-carrier-needed';
+    }
+    if (capture.sourceSetKind === 'single')
+        return 'guaranteed';
+    if (capture.sourceSetKind === 'derived-single')
+        return 'derived-single';
+    return 'derived-composite';
+}
+function classifyExpressionSourceSetKind(input) {
+    if (input.sourceReads.length === 0)
+        return 'unknown';
+    if (input.sourceReads.length > 1)
+        return 'derived-composite';
+    return input.transformKind === 'identity' ? 'single' : 'derived-single';
+}

package/dist/provenance/types.d.ts

@@ -0,0 +1,102 @@
+import { type PreviewReadScopeEcho } from '@storystick/client/internal';
+import type { PreviewReadContext } from '@storystick/types/preview-query-targeting';
+export interface PathAnchor {
+    readonly path: string;
+    readonly key: string;
+}
+export interface ProvenanceId {
+    readonly documentId: string;
+    readonly variantId?: string;
+    readonly canonicalPath: string;
+    readonly pathAnchors: readonly PathAnchor[];
+    readonly navigationPath?: string;
+    readonly navigationAnchors?: readonly PathAnchor[];
+    /** Scope of the concrete read that produced this source, when attested. */
+    readonly readScope?: PreviewReadScopeEcho;
+    /**
+     * Private rich-text leaf metadata. Present only for richtext source ids
+     * emitted per rendered text node inside one editable rich text field.
+     */
+    readonly textNodeIndex?: number;
+    readonly sourceKind: 'stored' | 'binding' | 'model' | 'computed' | 'richtext' | 'embed' | 'emptyFallback' | 'unknown';
+}
+export interface SourceSet {
+    readonly id: string;
+    readonly kind: 'single' | 'composite' | 'derived' | 'unknown';
+    readonly sources: readonly ProvenanceId[];
+    readonly primary?: ProvenanceId;
+    readonly derivation?: 'identity' | 'binding' | 'model' | 'concat' | 'truncate' | 'format' | 'richtext-flatten' | 'custom';
+    readonly editable: 'single-field' | 'multi-field' | 'not-editable';
+}
+export type ProvenanceMarkerModality = 'text' | 'attr:href' | 'attr:src' | 'attr:alt' | 'attr:title' | 'attr:aria-label';
+export type ProvenanceAnchorKind = 'element' | 'attribute' | 'text-range' | 'scope';
+export type PreviewProvenanceCarrierPlan = {
+    readonly kind: 'attribute';
+    readonly carrier: 'data-ss-p' | 'data-ss-e';
+    readonly modality: ProvenanceMarkerModality;
+    readonly anchorKind: ProvenanceAnchorKind;
+    readonly status: 'emitted';
+    readonly previewOnly: true;
+    readonly markerPayload: 'opaque-marker-id';
+} | {
+    readonly kind: 'text';
+    readonly carrier: 'coded-text-unicode-tags';
+    readonly modality: 'text';
+    readonly anchorKind: 'element';
+    readonly status: 'emitted';
+    readonly previewOnly: true;
+    readonly markerPayload: 'opaque-marker-id';
+    readonly surface: 'direct-editorial-text' | 'rich-text-text-node' | 'fallback-text-carrier';
+} | {
+    readonly kind: 'text-range';
+    readonly carrier: 'coded-text-unicode-tags';
+    readonly modality: 'text';
+    readonly anchorKind: 'text-range';
+    readonly status: 'emitted';
+    readonly previewOnly: true;
+    readonly markerPayload: 'opaque-marker-id';
+    readonly surface: 'non-promoted-text-range';
+} | {
+    readonly kind: 'future-attribute' | 'future-media' | 'future-scope';
+    readonly carrier: 'attribute-output-carrier' | 'media-carrier' | 'scope-carrier';
+    readonly modality: ProvenanceMarkerModality | 'media' | 'scope';
+    readonly anchorKind: ProvenanceAnchorKind;
+    readonly status: 'planned';
+    readonly previewOnly: true;
+    readonly markerPayload: 'opaque-marker-id';
+    readonly reason: string;
+};
+export interface MarkerRecord {
+    readonly markerId: string;
+    readonly sourceSetId: string;
+    readonly modality: ProvenanceMarkerModality;
+    readonly anchorKind: ProvenanceAnchorKind;
+    readonly carrierPlans?: readonly PreviewProvenanceCarrierPlan[];
+    readonly anchorMultiplicity?: 'single' | 'multi';
+    /** `expected` is a non-fatal public diagnostic state for missing anchors. */
+    readonly presence?: 'required' | 'optional' | 'expected';
+    readonly renderedTextFingerprint?: string;
+}
+export interface ProvenanceFrame {
+    readonly type: 'storystick.preview.provenance-frame';
+    readonly version: 1;
+    readonly sessionId?: string;
+    readonly readContext?: PreviewReadContext;
+    readonly routeHash: string;
+    readonly codeVersion: string;
+    readonly variantId?: string;
+    /** Gateway requested-vs-applied scope observed by this render. */
+    readonly previewScope?: PreviewReadScopeEcho;
+    readonly renderId: string;
+    readonly generation: number;
+    readonly renderNonce?: string;
+    readonly emissionRevision?: number;
+    readonly sourceSets: readonly SourceSet[];
+    readonly markers: readonly MarkerRecord[];
+}
+export interface AuthoritativeSet {
+    readonly documentIds: ReadonlySet<string>;
+    readonly routeHash: string;
+    readonly codeVersion: string;
+    readonly variantId?: string | null;
+}

package/dist/provenance/types.js

@@ -0,0 +1 @@
+export {};

package/dist/refresh-policy.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared timing constants retained for adapter scheduling. Preview browser
+ * grants themselves are coordinated by `grant-coordinator.ts`; this module has
+ * no postMessage or parent-window dependency.
+ */
+export declare const REFRESH_OFFSET_MS = 240000;
+export declare const REFRESH_JITTER_MS = 5000;
+export declare const REFRESH_TIMEOUT_MS = 5000;
+export declare const REFRESH_RETRY_COUNT = 2;
+export declare const REFRESH_BACKOFF_MS: readonly number[];
+export declare function computeRefreshAt(issuedAt: number, random?: () => number): number;

package/dist/refresh-policy.js

@@ -0,0 +1,14 @@
+/**
+ * Shared timing constants retained for adapter scheduling. Preview browser
+ * grants themselves are coordinated by `grant-coordinator.ts`; this module has
+ * no postMessage or parent-window dependency.
+ */
+export const REFRESH_OFFSET_MS = 240_000;
+export const REFRESH_JITTER_MS = 5_000;
+export const REFRESH_TIMEOUT_MS = 5_000;
+export const REFRESH_RETRY_COUNT = 2;
+export const REFRESH_BACKOFF_MS = [1_000, 3_000];
+export function computeRefreshAt(issuedAt, random = Math.random) {
+    const jitter = (random() * 2 - 1) * REFRESH_JITTER_MS;
+    return issuedAt + REFRESH_OFFSET_MS + jitter;
+}

package/dist/reveal-target.d.ts

@@ -0,0 +1,8 @@
+/** Geometry of an explicitly resolved preview target, independent of its
+ * provenance, transport and overlay renderer. Hidden content is not opened. */
+export declare function isPreviewTargetRendered(element: Element): boolean;
+/** Native nearest alignment handles nested scroll owners without taking focus.
+ * The optional completion callback lets reveal paint outlive a long smooth
+ * scroll. It observes only the explicit target, including nested scroll motion;
+ * cleanup cancels the observation, not a newer browser scroll. */
+export declare function scrollPreviewTargetIntoView(element: Element, onSettled?: () => void): () => void;

package/dist/reveal-target.js

@@ -0,0 +1,47 @@
+/** Geometry of an explicitly resolved preview target, independent of its
+ * provenance, transport and overlay renderer. Hidden content is not opened. */
+export function isPreviewTargetRendered(element) {
+    const win = element.ownerDocument.defaultView;
+    if (!win)
+        return false;
+    const style = win.getComputedStyle(element);
+    if (style.display === "none" || style.visibility === "hidden")
+        return false;
+    return Array.from(element.getClientRects()).some((rect) => rect.width > 0 && rect.height > 0);
+}
+/** Native nearest alignment handles nested scroll owners without taking focus.
+ * The optional completion callback lets reveal paint outlive a long smooth
+ * scroll. It observes only the explicit target, including nested scroll motion;
+ * cleanup cancels the observation, not a newer browser scroll. */
+export function scrollPreviewTargetIntoView(element, onSettled) {
+    const win = element.ownerDocument.defaultView;
+    const reducedMotion = win?.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
+    element.scrollIntoView({
+        block: "nearest",
+        inline: "nearest",
+        behavior: reducedMotion ? "instant" : "smooth",
+    });
+    if (!onSettled || !win || reducedMotion) {
+        onSettled?.();
+        return () => { };
+    }
+    let previous = element.getBoundingClientRect();
+    let stableFrames = 0;
+    const startedAt = win.performance.now();
+    let frame = win.requestAnimationFrame(observe);
+    function observe(now) {
+        const current = element.getBoundingClientRect();
+        stableFrames = current.top === previous.top && current.left === previous.left
+            ? stableFrames + 1
+            : 0;
+        previous = current;
+        // Three still frames also cover an already-visible target (no scrollend
+        // event). Bound observation if the target itself continuously animates.
+        if (!element.isConnected || stableFrames >= 3 || now - startedAt >= 5_000) {
+            onSettled();
+            return;
+        }
+        frame = win.requestAnimationFrame(observe);
+    }
+    return () => win.cancelAnimationFrame(frame);
+}

package/dist/route-paths.d.ts

@@ -0,0 +1,11 @@
+export declare const STORYSTICK_ROUTE_BASE_PATH = "/api/storystick";
+export declare const STORYSTICK_PREVIEW_ROUTE_PATH = "/api/storystick/preview";
+export declare const STORYSTICK_PREVIEW_TOKEN_ROUTE_PATH = "/api/storystick/preview/token";
+export declare const STORYSTICK_PREVIEW_CONTEXT_ROUTE_PATH = "/api/storystick/preview/context";
+export declare const STORYSTICK_PREVIEW_DISABLE_ROUTE_PATH = "/api/storystick/preview/disable";
+export declare const STORYSTICK_PREVIEW_AUTHORING_ROUTE_PATH = "/api/storystick/preview/authoring";
+export declare const STORYSTICK_HEALTH_ROUTE_PATH = "/api/storystick/health";
+export declare const STORYSTICK_MIGRATION_READBACK_ROUTE_PATH = "/api/storystick/migration-readback";
+export declare const STORYSTICK_REVALIDATE_ROUTE_PATH = "/api/storystick/revalidate";
+export declare const STORYSTICK_PREVIEW_PROVENANCE_RUNTIME_ROUTE_PATH = "/api/storystick/provenance-runtime";
+export declare function storystickRouteForBasePath(basePath: string, routePath: string): string;

package/dist/route-paths.js

@@ -0,0 +1,14 @@
+export const STORYSTICK_ROUTE_BASE_PATH = '/api/storystick';
+export const STORYSTICK_PREVIEW_ROUTE_PATH = `${STORYSTICK_ROUTE_BASE_PATH}/preview`;
+export const STORYSTICK_PREVIEW_TOKEN_ROUTE_PATH = `${STORYSTICK_PREVIEW_ROUTE_PATH}/token`;
+export const STORYSTICK_PREVIEW_CONTEXT_ROUTE_PATH = `${STORYSTICK_PREVIEW_ROUTE_PATH}/context`;
+export const STORYSTICK_PREVIEW_DISABLE_ROUTE_PATH = `${STORYSTICK_PREVIEW_ROUTE_PATH}/disable`;
+export const STORYSTICK_PREVIEW_AUTHORING_ROUTE_PATH = `${STORYSTICK_PREVIEW_ROUTE_PATH}/authoring`;
+export const STORYSTICK_HEALTH_ROUTE_PATH = `${STORYSTICK_ROUTE_BASE_PATH}/health`;
+export const STORYSTICK_MIGRATION_READBACK_ROUTE_PATH = `${STORYSTICK_ROUTE_BASE_PATH}/migration-readback`;
+export const STORYSTICK_REVALIDATE_ROUTE_PATH = `${STORYSTICK_ROUTE_BASE_PATH}/revalidate`;
+export const STORYSTICK_PREVIEW_PROVENANCE_RUNTIME_ROUTE_PATH = `${STORYSTICK_ROUTE_BASE_PATH}/provenance-runtime`;
+export function storystickRouteForBasePath(basePath, routePath) {
+    const normalized = basePath.trim().replace(/^\/+|\/+$/g, '');
+    return normalized.length === 0 ? routePath : `/${normalized}${routePath}`;
+}

package/dist/router-subscriber.d.ts

@@ -0,0 +1,92 @@
+import type { PreviewRoutePresentation } from '@storystick/transport-allowlist';
+export type { PreviewServerRenderReceipt, PreviewRoutePresentation } from '@storystick/transport-allowlist';
+/**
+ * Iframe→Studio router-transition subscriber (ADR-108 D6).
+ *
+ * Framework-agnostic contract used by adapters (`@storystick/next/
+ * preview-nav` for Next, future Astro/Vue/Svelte adapters) to report
+ * router transitions to the preview orchestrator inside `activate()`.
+ * The orchestrator then emits a `storystick.preview.location` envelope
+ * to the parent Studio.
+ *
+ * Mirror of `nav-handler.ts` (default no-op + register/get/clear), but
+ * direction-inverted:
+ *
+ *   - `setRouterSubscriber(handler)` — adapter registers a callback the
+ *     SDK invokes when the customer's router transitions. The adapter
+ *     is responsible for the framework-specific wiring (Next App: rAF-
+ *     coalesced `usePathname` + `useSearchParams`; Next Pages:
+ *     `router.events.on('routeChangeComplete')`; etc.) — this module
+ *     stays free of framework imports.
+ *
+ *   - `getRouterSubscriber()` — internal getter used by `activate()`'s
+ *     router-transition handler (it stores the function so consumers
+ *     can call into it as transitions happen). Returns `null` before
+ *     any adapter has registered. **Currently unused by `activate()`
+ *     directly** — the activate orchestrator stores the handler it
+ *     wants to invoke and ignores the registered subscriber; the
+ *     getter exists for tests + future plug-points (overlay click
+ *     handler, navigateToField wiring) that want to read the
+ *     subscriber from outside the orchestrator's closure.
+ *
+ * The "subscriber" wording emphasises that the SDK consumes the
+ * adapter's signal (one-way callback); the adapter is the producer of
+ * the transition events.
+ *
+ * Cleanup discipline (StrictMode safety): adapters MUST call
+ * `setRouterSubscriber(null)` on unmount. Without it a StrictMode
+ * double-mount would leave a stale subscriber registered after the
+ * first mount unmounts. The cleanup also lets a fresh adapter mount
+ * (overlay react remount on route change) register cleanly.
+ */
+/**
+ * Adapter-reported router transition tuple. Browser form throughout —
+ * pathname starts with `/`, search has no leading `?`, hash includes
+ * the `#`. Empty strings for `search` / `hash` mean "no query" / "no
+ * fragment" respectively.
+ */
+export interface RouterTransition {
+    /** Explicit adapter confirmation after a commanded render, including same-URL refresh. */
+    commandId?: string;
+    presentation?: PreviewRoutePresentation;
+    /** Browser pathname for this commit, before the adapter removes its basePath. */
+    browserPathname?: string;
+    pathname: string;
+    search: string;
+    hash: string;
+}
+/**
+ * Subscriber callback shape. The adapter invokes the registered
+ * handler with the post-transition tuple (after the customer's
+ * router has updated its internal state and the browser URL has
+ * already settled at the new value).
+ */
+export type RouterSubscriber = (transition: RouterTransition) => void;
+interface PreviewRouterSubscriberCell {
+    subscriber: RouterSubscriber | null;
+}
+declare global {
+    var __storystick_preview_router_subscriber__: PreviewRouterSubscriberCell | undefined;
+}
+/**
+ * Register the router subscriber. Replaces any previously registered
+ * subscriber. Pass `null` to reset to the default no-op.
+ */
+export declare function setRouterSubscriber(fn: RouterSubscriber | null): void;
+/**
+ * Read the currently-registered subscriber. Returns `null` before any
+ * adapter has called `setRouterSubscriber`. Consumers gate their
+ * invocation on the non-null return.
+ */
+export declare function getRouterSubscriber(): RouterSubscriber | null;
+/**
+ * Convenience for `activate()`'s router-transition path: invoke the
+ * currently-registered subscriber if any, no-op otherwise. Centralises
+ * the null-check so callers don't repeat it.
+ */
+export declare function notifyRouterTransition(transition: RouterTransition): void;
+/**
+ * Test-only reset. Vitest isolates modules per file but multiple
+ * cases inside one file would otherwise share state.
+ */
+export declare function _resetRouterSubscriberForTests(): void;