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

package/LICENSE

@@ -0,0 +1,112 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 Tanguy Freycon
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+This Agreement shall be governed by the laws of France.

package/PUBLIC-API.md

@@ -0,0 +1,56 @@
+# @storystick/preview API contract
+
+Install this candidate explicitly with `@storystick/preview@0.2.0-rc.1` after registry bootstrap and publication. This repository alone does not make the candidate or beta channel available on npm.
+
+Version 0.2.0-rc.1, cohort `sdk-0.2.0-rc.1`. ESM distribution; no CommonJS or universal Edge compatibility is promised.
+
+This package supports the integration facades; installing it directly is an advanced use. Reserved contracts are required between SDK packages and must be upgraded with the same cohort. Their public export paths do not promise independent stability.
+
+| Entry | Status |
+| --- | --- |
+| `.` | Reserved SDK contract |
+| `./runtime/store` | Reserved SDK contract |
+| `./runtime/request-id` | Reserved SDK contract |
+| `./runtime/authority` | Reserved SDK contract |
+| `./overlay-label` | Reserved SDK contract |
+| `./select-cursor` | Reserved SDK contract |
+| `./runtime/boot` | Reserved SDK contract |
+| `./runtime/perf-metrics` | Reserved SDK contract |
+| `./runtime/live-query-overlay` | Reserved SDK contract |
+| `./refresh-policy` | Reserved SDK contract |
+| `./runtime/emit-runtime-error` | Reserved SDK contract |
+| `./runtime/workspace-shortcuts` | Reserved SDK contract |
+| `./runtime/momentary-navigate` | Reserved SDK contract |
+| `./runtime/content-refresh` | Reserved SDK contract |
+| `./runtime/standalone-overlays` | Reserved SDK contract |
+| `./runtime/invalidation` | Reserved SDK contract |
+| `./dev/suspicious-codeword-detector` | Reserved SDK contract |
+| `./channel-taxonomy` | Reserved SDK contract |
+| `./session-projections` | Reserved SDK contract |
+| `./nav-handler` | Reserved SDK contract |
+| `./router-subscriber` | Reserved SDK contract |
+| `./identity/preview-cookie` | Reserved SDK contract |
+| `./identity/browser-context` | Reserved SDK contract |
+| `./identity` | Reserved SDK contract |
+| `./provenance` | Reserved SDK contract |
+| `./provenance/richtext-slice-embed-address` | Reserved SDK contract |
+| `./authoring/runtime-contract` | Reserved SDK contract |
+| `./page-presentation` | Reserved SDK contract |
+| `./sdk-error-copy` | Reserved SDK contract |
+| `./session-subscriber` | Reserved SDK contract |
+| `./provenance/source-registry` | Reserved SDK contract |
+| `./runtime/preview-transition-state` | Reserved SDK contract |
+| `./runtime/preview-perspective-intent-state` | Reserved SDK contract |
+| `./runtime/preview-perspective-alignment` | Reserved SDK contract |
+| `./reveal-target` | Reserved SDK contract |
+| `./framework/*` | Reserved SDK contract |
+| `./routes` | Reserved SDK contract |
+| `./server/*` | Reserved SDK contract |
+| `./provenance/render-context` | Reserved SDK contract |
+| `./provenance/slice-model` | Reserved SDK contract |
+
+The qualified toolchain is Node 24.19.0 and pnpm 9.15.9. Next uses App Router 15.5.28, Sharp 0.35.5 and React/React DOM 19.2.8; Astro uses 7.4.4 with the Node adapter 11.1.9. Browser delivery is verified by bundling; hosted Preview activation and cross-browser behavior require the staging manual check. Source/CLI are Node tools, server entries belong on the server, and browser entries must never receive a server API key.
+
+This is a support/tooling contract. It does not independently grant project access or permission to perform effects.
+
+The repository is private. Public package availability does not make the monorepo public, and npm provenance from that repository is unavailable. Product and pilot support: [Storystick](https://storystick.app).

package/README.md

@@ -1,3 +1,43 @@
-# Temporary Holding Version
+# @storystick/preview
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Low-level Preview runtime used by the Storystick React and Next.js SDKs.
+
+Application code normally installs this package alongside the public SDK
+surface rather than importing it directly:
+
+```bash
+pnpm add @storystick/client @storystick/media @storystick/next @storystick/preview @storystick/react
+```
+
+Its documented subpaths are runtime contracts consumed by the SDK packages.
+They are published so an application installed exclusively from registry
+tarballs has the same Preview behavior as the Storystick monorepo.
+
+
+## Workspace shortcuts in an embedded Preview
+
+The Preview integration reserves Studio workspace shortcuts while attached to
+an authorized Studio session, in both Edit and Navigate modes, including inside
+site inputs. The Studio supplies the platform bindings from its command catalog:
+navigation, Preview, Details and Assistant panels, the command palette, and
+F6/Shift+F6 region navigation. These chords take priority over site handlers.
+Ordinary typing, clipboard operations, local Undo/Redo, Find and Escape remain
+with the site. Outside an attached session nothing is reserved. Nested third-party
+frames and pages without the Preview runtime do not participate.
+
+`runtime/workspace-shortcuts` implements this opt-in SDK contract without reading
+customer DOM state or sending input content. The `storystick.preview.shortcuts`
+UI channel exchanges `ready`, `probe`, `configure` and `invoke` messages. It is
+bound to the active iframe window, exact origins, project/session and a fresh
+realm identifier. Each Studio connection has its own configuration identity, so
+reconnecting to a surviving iframe cannot inherit stale revisions. Configuration
+revisions and invocation sequence numbers reject
+stale/duplicate commands. The Studio rechecks current action and modal ownership
+before dispatch. The shared installer covers framework boot, adapters and the
+early provenance script, and suspends its bindings across pagehide/session changes.
+
+## Candidate distribution contract
+
+See [PUBLIC-API.md](./PUBLIC-API.md) for supported entries, reserved SDK contracts,
+the qualified runtime matrix and the candidate cohort. Upgrade Storystick
+packages together.

package/dist/.source-hash

@@ -0,0 +1 @@
+bd76a6ce0bc6a45860a5c7a43beca2a761804917b32721b33339d3cbe862a05d

package/dist/authoring/runtime-contract.d.ts

@@ -0,0 +1,92 @@
+import type { PreviewPerspective, PreviewReadContext } from '@storystick/types/preview-query-targeting';
+import type { PreviewV2RevealSourceRequest, PreviewV2RevealSliceRequest } from '../provenance/reveal-contract.js';
+import type { ImperativeEditorNavigationTarget } from '@storystick/types/editor-destination';
+export declare const STORYSTICK_AUTHORING_RUNTIME_CONTRACT_VERSION: 11;
+export declare const STORYSTICK_AUTHORING_RUNTIME_GLOBAL: "StorystickAuthoringRuntime";
+export declare const STORYSTICK_AUTHORING_RUNTIME_PATH: "/authoring-runtime/authoring-runtime.js";
+export interface PreviewAuthoringAdmission {
+    connection: {
+        id: string;
+        expiresAt: number;
+    };
+    projectId: string;
+    projectShortId: string;
+    contentShapeCapability: string;
+    token: string;
+    /** Project/admission-bound Convex RPC authority; never use the public SDK token. */
+    rpcToken: string;
+    expiresAt: number;
+    files: {
+        id: string;
+        token: string;
+        expiresAt: number;
+        userId: string;
+        sessionId: string;
+    };
+}
+export interface PreviewAuthoringTarget {
+    documentId: string;
+    locale: string;
+    variantId?: string;
+    releaseId?: string;
+    published?: boolean;
+    position?: ImperativeEditorNavigationTarget;
+}
+export interface PreviewAuthoringPresentation {
+    /** Absent for a public route; present for a routable document without a pathname. */
+    draftDocumentId?: string;
+    documentId: string;
+    locale: string;
+    pathname: string;
+    perspective: PreviewPerspective;
+}
+export type PreviewAuthoringSurface = 'editor' | 'assistant';
+export interface PreviewAuthoringRuntimeMountOptions {
+    root: ShadowRoot;
+    container: HTMLElement;
+    target?: PreviewAuthoringTarget;
+    surface?: PreviewAuthoringSurface | null;
+    header?: {
+        leading: HTMLElement;
+        title: HTMLElement;
+        trailing: HTMLElement;
+    };
+    assistantThreadId?: string | null;
+    onSurface?(surface: PreviewAuthoringSurface): void;
+    onAssistantThread?(threadId: string | null): void;
+    /** A project control can be mounted before there is an edited document. */
+    context?: {
+        container: HTMLElement;
+        getSnapshot(): PreviewReadContext | null;
+        subscribe(listener: () => void): () => void;
+        change(perspective: PreviewPerspective): Promise<PreviewReadContext>;
+    };
+    studioUrl?: string;
+    getPresentation?(): PreviewAuthoringPresentation | null;
+    /** Resolves after context acceptance and navigation dispatch. Site rendering
+     * is observed separately and must not hold the editor's target transition. */
+    present?(destination: PreviewAuthoringPresentation, 
+    /** The edited owner can differ from the page being presented. */
+    editorTarget?: PreviewAuthoringTarget): Promise<PreviewReadContext>;
+    admission: PreviewAuthoringAdmission;
+    refreshAdmission(force?: boolean): Promise<PreviewAuthoringAdmission>;
+    closeAdmission(): void;
+    revealSource?(request: PreviewV2RevealSourceRequest): boolean;
+    revealSlice?(request: PreviewV2RevealSliceRequest): boolean;
+    onTarget?(target: PreviewAuthoringTarget): void;
+    onStatus?(status: PreviewAuthoringRuntimeStatus): void;
+}
+export declare function isPreviewAuthoringAdmission(value: unknown, now?: number): value is PreviewAuthoringAdmission;
+export type PreviewAuthoringRuntimeStatus = 'connecting' | 'ready' | 'unauthorized' | 'disposed';
+export interface PreviewAuthoringRuntimeHandle {
+    setSurface(surface: PreviewAuthoringSurface | null): void;
+    /** A host observation may become obsolete while the current draft is saved. */
+    open(target: PreviewAuthoringTarget, isCurrent?: () => boolean): Promise<void>;
+    dispose(): Promise<void>;
+}
+export interface PreviewAuthoringRuntimeModule {
+    readonly contractVersion: typeof STORYSTICK_AUTHORING_RUNTIME_CONTRACT_VERSION;
+    /** Fetch code only. Admission, queries and mounting still require an explicit open. */
+    preload(surface: PreviewAuthoringSurface): Promise<void>;
+    mount(options: PreviewAuthoringRuntimeMountOptions): PreviewAuthoringRuntimeHandle;
+}

package/dist/authoring/runtime-contract.js

@@ -0,0 +1,28 @@
+export const STORYSTICK_AUTHORING_RUNTIME_CONTRACT_VERSION = 11;
+export const STORYSTICK_AUTHORING_RUNTIME_GLOBAL = 'StorystickAuthoringRuntime';
+export const STORYSTICK_AUTHORING_RUNTIME_PATH = '/authoring-runtime/authoring-runtime.js';
+export function isPreviewAuthoringAdmission(value, now = Date.now()) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const entry = value;
+    const connection = entry.connection;
+    if (!connection ||
+        typeof connection.id !== 'string' ||
+        connection.id.length === 0 ||
+        !Number.isFinite(connection.expiresAt) ||
+        connection.expiresAt <= now)
+        return false;
+    const files = entry.files;
+    if (!files ||
+        !['id', 'token', 'userId', 'sessionId'].every((key) => typeof files[key] ===
+            'string' &&
+            files[key] !== '') ||
+        !files.token.startsWith('stf_') ||
+        !Number.isFinite(files.expiresAt) ||
+        files.expiresAt <= now)
+        return false;
+    return (['projectId', 'projectShortId', 'contentShapeCapability', 'token', 'rpcToken'].every((key) => typeof entry[key] === 'string' && entry[key] !== '') &&
+        typeof entry.expiresAt === 'number' &&
+        Number.isFinite(entry.expiresAt) &&
+        entry.expiresAt > now);
+}

package/dist/channel-taxonomy.d.ts

@@ -0,0 +1,17 @@
+import type { PreviewMessageType } from '@storystick/transport-allowlist';
+import type { IframeToStudio, StudioToIframe } from './types.js';
+export type PreviewPostMessageFamily = 'session' | 'navigation' | 'location' | 'render-ack' | 'runtime-status' | 'overlay' | 'selection' | 'live-query';
+export type PreviewUiSignalFamily = 'ui-signal';
+export type PreviewContentSignalFamily = 'content-refresh';
+export type PreviewChannelFamily = PreviewPostMessageFamily | PreviewUiSignalFamily | PreviewContentSignalFamily;
+export declare const PREVIEW_CONTENT_REFRESH_CHANNEL: "preview-session-content-revision";
+/**
+ * Taxonomy for the secure preview envelope protocol. This classifies the
+ * existing wire types only; it does not change or version the envelopes.
+ */
+export declare function classifyPreviewEnvelopeType(type: PreviewMessageType): PreviewPostMessageFamily;
+/**
+ * Legacy/non-envelope Studio UI signals. These are postMessage UI commands and
+ * diagnostics, not content freshness signals.
+ */
+export declare function classifyPreviewUiSignalType(type: StudioToIframe['type'] | IframeToStudio['type']): PreviewUiSignalFamily;

package/dist/channel-taxonomy.js

@@ -0,0 +1,46 @@
+export const PREVIEW_CONTENT_REFRESH_CHANNEL = 'preview-session-content-revision';
+/**
+ * Taxonomy for the secure preview envelope protocol. This classifies the
+ * existing wire types only; it does not change or version the envelopes.
+ */
+export function classifyPreviewEnvelopeType(type) {
+    switch (type) {
+        case 'storystick.preview.session-broadcast':
+        case 'storystick.preview.session-request':
+            return 'session';
+        case 'storystick.preview.navigate':
+        case 'storystick.preview.reload':
+        case 'storystick.preview.interaction-mode':
+            return 'navigation';
+        case 'storystick.preview.navigation-start':
+        case 'storystick.preview.location':
+            return 'location';
+        case 'storystick.preview.route-rendered':
+            return 'render-ack';
+        case 'storystick.preview.runtime-error':
+        case 'storystick.preview.runtime-recovered':
+        case 'storystick.preview.lifecycle':
+            return 'runtime-status';
+        case 'storystick.preview.overlay-map':
+        case 'storystick.preview.overlay-clear':
+        case 'storystick.preview.overlay-ready':
+        case 'storystick.preview.overlay-click':
+        case 'storystick.preview.iframe-interaction':
+            return 'overlay';
+        case 'storystick.preview.v2.reveal-source':
+        case 'storystick.preview.v2.reveal-result':
+            return 'selection';
+        case 'storystick.preview.live-query.register':
+        case 'storystick.preview.live-query.unregister':
+        case 'storystick.preview.live-query.projection':
+            return 'live-query';
+    }
+}
+/**
+ * Legacy/non-envelope Studio UI signals. These are postMessage UI commands and
+ * diagnostics, not content freshness signals.
+ */
+export function classifyPreviewUiSignalType(type) {
+    void type;
+    return 'ui-signal';
+}

package/dist/context-command.d.ts

@@ -0,0 +1,18 @@
+import { type PreviewPerspective, type PreviewReadContext } from '@storystick/types/preview-query-targeting';
+export interface PreviewPerspectiveCommand {
+    commandId: string;
+    expectedContextId: string;
+    expectedRevision: number;
+    perspective: PreviewPerspective | null;
+}
+export type PreviewPerspectiveCommandResult = {
+    context: PreviewReadContext;
+    ended: boolean;
+} & ({
+    status: 'applied';
+    appliedRevision: number;
+} | {
+    status: 'conflict';
+});
+/** A network-uncertain mutation is retried only with its original identity. */
+export declare function sendPreviewPerspectiveCommand(route: string, command: PreviewPerspectiveCommand, fetchFn?: typeof fetch): Promise<PreviewPerspectiveCommandResult>;

package/dist/context-command.js

@@ -0,0 +1,38 @@
+import { isPreviewReadContext, } from '@storystick/types/preview-query-targeting';
+/** A network-uncertain mutation is retried only with its original identity. */
+export async function sendPreviewPerspectiveCommand(route, command, fetchFn = fetch) {
+    const body = JSON.stringify(command);
+    const send = () => fetchFn(route, {
+        method: 'POST', credentials: 'same-origin', cache: 'no-store',
+        headers: { 'Content-Type': 'application/json', Accept: 'application/json' }, body,
+    });
+    let response;
+    try {
+        response = await send();
+    }
+    catch {
+        // Read back before retrying. A concurrent context change never changes
+        // the original command's fence or turns it into a new intent.
+        const read = await fetchFn(route, { credentials: 'same-origin', cache: 'no-store' });
+        if (!read.ok)
+            throw new Error('Preview context readback is unavailable.');
+        const snapshot = await read.json();
+        if (!isRecord(snapshot) || !isPreviewReadContext(snapshot.context) ||
+            snapshot.context.contextId !== command.expectedContextId) {
+            throw new Error('Invalid Preview context readback.');
+        }
+        response = await send();
+    }
+    const result = await response.json();
+    if ((response.status !== 200 && response.status !== 409) || !isRecord(result) ||
+        (result.status !== 'applied' && result.status !== 'conflict') ||
+        !isPreviewReadContext(result.context) || typeof result.ended !== 'boolean' ||
+        (result.status === 'applied' && (!Number.isSafeInteger(result.appliedRevision) ||
+            result.appliedRevision < 1 || result.appliedRevision > result.context.revision))) {
+        throw new Error('Preview perspective change is unavailable.');
+    }
+    return result;
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/dev/suspicious-codeword-detector.d.ts

@@ -0,0 +1,15 @@
+export type SuspiciousPreviewCodewordKind = 'attribute' | 'head' | 'script' | 'style' | 'form-value' | 'url';
+export interface SuspiciousPreviewCodewordReport {
+    readonly kind: SuspiciousPreviewCodewordKind;
+    readonly element?: Element;
+    readonly attribute?: string;
+    readonly value: string;
+    readonly cleaned: string;
+    readonly markerIds: readonly string[];
+}
+/**
+ * Dev-only audit for coded text in sinks where the invisible payload is
+ * intrinsically dangerous. Rendered text is deliberately ignored: coded text
+ * is expected there, and treating it as suspicious would create false positives.
+ */
+export declare function observeSuspiciousPreviewCodewords(doc: Document, onReports: (reports: readonly SuspiciousPreviewCodewordReport[]) => void): () => void;