@storystick/preview 0.2.0-rc.0 → 0.2.0-rc.1

package/PUBLIC-API.md

@@ -1,8 +1,8 @@
 # @storystick/preview API contract
 
-Install this candidate explicitly with `@storystick/preview@0.2.0-rc.0` after registry bootstrap and publication. This repository alone does not make the candidate or beta channel available on npm.
+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.0, cohort `sdk-0.2.0-rc.0`. ESM distribution; no CommonJS or universal Edge compatibility is promised.
+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.
 
@@ -35,6 +35,7 @@ This package supports the integration facades; installing it directly is an adva
 | `./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 |

package/dist/.source-hash

@@ -1 +1 @@
-d7ff593b5f2ade5e8f9370eb42602497bb6b37f2c82edb6b712289200e939956
+bd76a6ce0bc6a45860a5c7a43beca2a761804917b32721b33339d3cbe862a05d

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

@@ -1,7 +1,7 @@
 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: 9;
+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 {
@@ -45,9 +45,10 @@ export interface PreviewAuthoringRuntimeMountOptions {
     root: ShadowRoot;
     container: HTMLElement;
     target?: PreviewAuthoringTarget;
-    surface?: PreviewAuthoringSurface;
+    surface?: PreviewAuthoringSurface | null;
     header?: {
         leading: HTMLElement;
+        title: HTMLElement;
         trailing: HTMLElement;
     };
     assistantThreadId?: string | null;
@@ -85,5 +86,7 @@ export interface PreviewAuthoringRuntimeHandle {
 }
 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

@@ -1,4 +1,4 @@
-export const STORYSTICK_AUTHORING_RUNTIME_CONTRACT_VERSION = 9;
+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()) {

package/dist/page-presentation.d.ts

@@ -0,0 +1,24 @@
+/** Framework-independent presentation for Preview's opening and failure pages.
+ * The activation route can render the same surface before any React runtime. */
+export declare const STORYSTICK_MARK_VIEW_BOX = "0 0 12 11";
+export declare const STORYSTICK_MARK_RECTS: readonly [{
+    readonly x: 0;
+    readonly y: 4;
+    readonly width: 3;
+    readonly height: 7;
+    readonly rx: 1;
+}, {
+    readonly x: 4.5;
+    readonly y: 0;
+    readonly width: 3;
+    readonly height: 11;
+    readonly rx: 1;
+}, {
+    readonly x: 9;
+    readonly y: 6;
+    readonly width: 3;
+    readonly height: 5;
+    readonly rx: 1;
+}];
+export declare const PREVIEW_PAGE_BRAND_HTML: string;
+export declare const PREVIEW_PAGE_STYLES = "\n  [data-ss-preview-page] { box-sizing: border-box; display: flex; min-height: 100svh; width: 100%; padding: 32px 24px; background: var(--ss-surface-page, #fff); color: var(--ss-text-primary, oklch(.2 .007 258.364)); font: 400 14px/20px \"Storystick Inter\", \"Inter Variable\", ui-sans-serif, system-ui, sans-serif; -webkit-font-smoothing: antialiased; text-rendering: optimizeLegibility; color-scheme: light; }\n  [data-ss-preview-page-content] { width: 100%; max-width: 360px; margin: auto; text-align: center; overflow-wrap: anywhere; }\n  [data-ss-preview-page-brand] { display: flex; align-items: center; justify-content: center; gap: 9px; margin-bottom: 32px; font-size: 15px; font-weight: 500; letter-spacing: -.015em; }\n  [data-ss-preview-page-brand] svg { flex: none; width: 15px; height: 14px; transform: rotate(90deg); }\n  [data-ss-preview-page-heading] { display: flex; align-items: center; justify-content: center; gap: 10px; }\n  [data-ss-preview-page-title] { margin: 0; color: inherit; font: inherit; font-size: 20px; line-height: 28px; font-weight: 500; letter-spacing: -.025em; text-wrap: balance; }\n  [data-ss-preview-page-description] { margin: 12px 0 0; color: var(--ss-text-secondary, oklch(.471 .006 258.364)); font: inherit; text-wrap: pretty; }\n  [data-ss-preview-page-actions] { display: flex; flex-wrap: wrap; align-items: center; justify-content: center; gap: 8px; margin-top: 24px; }\n  [data-ss-preview-page-action] { box-sizing: border-box; display: inline-flex; align-items: center; justify-content: center; min-height: 36px; padding: 8px 16px; border: 0; border-radius: 999px; background: var(--ss-surface-card, #fff); color: inherit; box-shadow: var(--ss-shadow-control, 0 0 1px rgb(0 0 0 / .22), 0 2px 4px rgb(0 0 0 / .04)); font: inherit; line-height: 20px; text-decoration: none; cursor: pointer; transition: background-color 140ms ease; }\n  [data-ss-preview-page-action]:hover { background: var(--ss-surface-field, oklch(.958 .001 255)); }\n  [data-ss-preview-page-action='primary'] { background: var(--ss-text-primary, oklch(.2 .007 258.364)); color: #fff; box-shadow: none; }\n  [data-ss-preview-page-action='primary']:hover { background: #303034; }\n  [data-ss-preview-page-action]:focus-visible, [data-ss-preview-page] summary:focus-visible { outline: 2px solid var(--ss-focus-color, oklch(.614 .194 257)); outline-offset: 3px; }\n  [data-ss-preview-page] details { margin-top: 24px; color: var(--ss-text-secondary, oklch(.471 .006 258.364)); font-size: 12px; line-height: 18px; }\n  [data-ss-preview-page] summary { width: fit-content; margin-inline: auto; border-radius: 4px; cursor: pointer; }\n  [data-ss-preview-page] pre { box-sizing: border-box; max-height: 240px; margin: 12px 0 0; overflow: auto; padding: 12px; border-radius: 12px; background: var(--ss-surface-field, oklch(.958 .001 255)); font: 12px/18px ui-monospace, monospace; white-space: pre-wrap; text-align: left; }\n  [data-ss-preview-page-progress] { position: relative; display: inline-block; flex: none; width: 15px; height: 15px; color: var(--ss-text-tertiary, oklch(.515 .006 258.364)); animation: ss-preview-page-orbit 720ms linear infinite; }\n  [data-ss-preview-page-progress]::before { content: ''; position: absolute; inset: 0; box-sizing: border-box; border: 2px solid currentColor; border-radius: 50%; opacity: .2; }\n  [data-ss-preview-page-progress]::after { content: ''; position: absolute; top: 1px; left: calc(50% - 2px); width: 4px; height: 4px; border-radius: 50%; background: currentColor; }\n  @keyframes ss-preview-page-orbit { to { transform: rotate(360deg); } }\n  @media (prefers-reduced-motion: reduce) { [data-ss-preview-page-progress] { animation: none; } [data-ss-preview-page-action] { transition: none; } }\n";

package/dist/page-presentation.js

@@ -0,0 +1,32 @@
+/** Framework-independent presentation for Preview's opening and failure pages.
+ * The activation route can render the same surface before any React runtime. */
+export const STORYSTICK_MARK_VIEW_BOX = '0 0 12 11';
+export const STORYSTICK_MARK_RECTS = [
+    { x: 0, y: 4, width: 3, height: 7, rx: 1 },
+    { x: 4.5, y: 0, width: 3, height: 11, rx: 1 },
+    { x: 9, y: 6, width: 3, height: 5, rx: 1 },
+];
+export const PREVIEW_PAGE_BRAND_HTML = `<div data-ss-preview-page-brand><svg viewBox="${STORYSTICK_MARK_VIEW_BOX}" fill="currentColor" aria-hidden="true">${STORYSTICK_MARK_RECTS.map(rect => `<rect ${Object.entries(rect).map(([key, value]) => `${key}="${value}"`).join(' ')} />`).join('')}</svg><span>Storystick</span></div>`;
+export const PREVIEW_PAGE_STYLES = `
+  [data-ss-preview-page] { box-sizing: border-box; display: flex; min-height: 100svh; width: 100%; padding: 32px 24px; background: var(--ss-surface-page, #fff); color: var(--ss-text-primary, oklch(.2 .007 258.364)); font: 400 14px/20px "Storystick Inter", "Inter Variable", ui-sans-serif, system-ui, sans-serif; -webkit-font-smoothing: antialiased; text-rendering: optimizeLegibility; color-scheme: light; }
+  [data-ss-preview-page-content] { width: 100%; max-width: 360px; margin: auto; text-align: center; overflow-wrap: anywhere; }
+  [data-ss-preview-page-brand] { display: flex; align-items: center; justify-content: center; gap: 9px; margin-bottom: 32px; font-size: 15px; font-weight: 500; letter-spacing: -.015em; }
+  [data-ss-preview-page-brand] svg { flex: none; width: 15px; height: 14px; transform: rotate(90deg); }
+  [data-ss-preview-page-heading] { display: flex; align-items: center; justify-content: center; gap: 10px; }
+  [data-ss-preview-page-title] { margin: 0; color: inherit; font: inherit; font-size: 20px; line-height: 28px; font-weight: 500; letter-spacing: -.025em; text-wrap: balance; }
+  [data-ss-preview-page-description] { margin: 12px 0 0; color: var(--ss-text-secondary, oklch(.471 .006 258.364)); font: inherit; text-wrap: pretty; }
+  [data-ss-preview-page-actions] { display: flex; flex-wrap: wrap; align-items: center; justify-content: center; gap: 8px; margin-top: 24px; }
+  [data-ss-preview-page-action] { box-sizing: border-box; display: inline-flex; align-items: center; justify-content: center; min-height: 36px; padding: 8px 16px; border: 0; border-radius: 999px; background: var(--ss-surface-card, #fff); color: inherit; box-shadow: var(--ss-shadow-control, 0 0 1px rgb(0 0 0 / .22), 0 2px 4px rgb(0 0 0 / .04)); font: inherit; line-height: 20px; text-decoration: none; cursor: pointer; transition: background-color 140ms ease; }
+  [data-ss-preview-page-action]:hover { background: var(--ss-surface-field, oklch(.958 .001 255)); }
+  [data-ss-preview-page-action='primary'] { background: var(--ss-text-primary, oklch(.2 .007 258.364)); color: #fff; box-shadow: none; }
+  [data-ss-preview-page-action='primary']:hover { background: #303034; }
+  [data-ss-preview-page-action]:focus-visible, [data-ss-preview-page] summary:focus-visible { outline: 2px solid var(--ss-focus-color, oklch(.614 .194 257)); outline-offset: 3px; }
+  [data-ss-preview-page] details { margin-top: 24px; color: var(--ss-text-secondary, oklch(.471 .006 258.364)); font-size: 12px; line-height: 18px; }
+  [data-ss-preview-page] summary { width: fit-content; margin-inline: auto; border-radius: 4px; cursor: pointer; }
+  [data-ss-preview-page] pre { box-sizing: border-box; max-height: 240px; margin: 12px 0 0; overflow: auto; padding: 12px; border-radius: 12px; background: var(--ss-surface-field, oklch(.958 .001 255)); font: 12px/18px ui-monospace, monospace; white-space: pre-wrap; text-align: left; }
+  [data-ss-preview-page-progress] { position: relative; display: inline-block; flex: none; width: 15px; height: 15px; color: var(--ss-text-tertiary, oklch(.515 .006 258.364)); animation: ss-preview-page-orbit 720ms linear infinite; }
+  [data-ss-preview-page-progress]::before { content: ''; position: absolute; inset: 0; box-sizing: border-box; border: 2px solid currentColor; border-radius: 50%; opacity: .2; }
+  [data-ss-preview-page-progress]::after { content: ''; position: absolute; top: 1px; left: calc(50% - 2px); width: 4px; height: 4px; border-radius: 50%; background: currentColor; }
+  @keyframes ss-preview-page-orbit { to { transform: rotate(360deg); } }
+  @media (prefers-reduced-motion: reduce) { [data-ss-preview-page-progress] { animation: none; } [data-ss-preview-page-action] { transition: none; } }
+`;

package/dist/server/control-errors.js

@@ -1,7 +1,8 @@
+import { PREVIEW_PAGE_BRAND_HTML, PREVIEW_PAGE_STYLES } from "../page-presentation.js";
 import { StorystickError } from "@storystick/client";
 import { mapPreviewSessionError } from "@storystick/preview/session-subscriber";
 export function previewInitialRouteErrorResponse(request, error) {
-    if (error.recoverable && requestAcceptsHtml(request)) {
+    if (requestAcceptsHtml(request)) {
         return previewHtmlErrorResponse(error, new URL(request.url).searchParams.get("_ss_session"));
     }
     return previewErrorResponse(error);
@@ -63,7 +64,11 @@ function buildHtmlError(error, sessionId) {
         ? `<script>window.parent.postMessage(${JSON.stringify({ type: 'storystick.preview.activation-error', sessionId, code: error.code })}, '*');</script>`
         : '';
     const code = escapeHtml(error.code);
-    const message = escapeHtml(error.message);
+    const details = escapeHtml([
+        error.code, error.message,
+        ...('upstreamCode' in error && error.upstreamCode ? [`Upstream code: ${error.upstreamCode}`] : []),
+        ...('upstreamRef' in error && error.upstreamRef ? [`Reference: ${error.upstreamRef}`] : []),
+    ].join('\n'));
     const retryScript = error.retryable
         ? `<script>
     (() => {
@@ -88,6 +93,10 @@ function buildHtmlError(error, sessionId) {
         } catch (_) {}
         if (attempt >= maxAttempts) {
           document.body.dataset.previewRecovery = 'stopped';
+          document.title = 'Preview unavailable';
+          document.querySelector('[data-ss-preview-page-progress]')?.remove();
+          document.querySelector('[data-ss-preview-page-title]').textContent = 'Preview unavailable';
+          document.querySelector('[data-ss-preview-page-description]').textContent = 'The site could not reconnect. Try again, or reopen Preview from Studio.';
           return;
         }
         const delay = Math.min(5000, Math.round(500 * Math.pow(1.5, attempt - 1)));
@@ -97,29 +106,37 @@ function buildHtmlError(error, sessionId) {
     })();
   </script>`
         : "";
-    const title = error.retryable ? "Preview recovering" : "Preview unavailable";
-    const heading = error.retryable
-        ? "Preview reconnecting"
-        : error.code === "PREVIEW_PROJECT_MISMATCH" ? "Preview is connected to another project" : "Reopen this preview from Storystick Studio";
+    const title = error.retryable ? "Preview reconnecting" : "Preview unavailable";
+    const description = error.retryable
+        ? "We’re reconnecting to your site. Your preview will open here when it’s ready."
+        : error.code === "PREVIEW_PROJECT_MISMATCH"
+            ? "This site belongs to another project. Open Preview from the correct project in Studio."
+            : "Reopen this preview from Storystick Studio to continue.";
     return `<!doctype html>
 <html lang="en">
 <head>
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>${title}</title>
-  <style>
-    :root { color-scheme: light dark; font-family: system-ui, sans-serif; }
-    body { margin: 0; min-height: 100vh; display: grid; place-items: center; background: Canvas; color: CanvasText; }
-    main { max-width: 28rem; padding: 1.5rem; line-height: 1.5; }
-    h1 { font-size: 1rem; margin: 0 0 .5rem; }
-    p { margin: 0; color: color-mix(in srgb, CanvasText 70%, transparent); }
-    code { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: .8125rem; }
-  </style>
+  <style>body { margin: 0; } ${PREVIEW_PAGE_STYLES}</style>
 </head>
 <body>
-  <main aria-live="polite">
-    <h1>${heading}</h1>
-    <p data-preview-error="${code}">${message}</p>
+  <main data-ss-preview-page>
+    <div data-ss-preview-page-content>
+      ${PREVIEW_PAGE_BRAND_HTML}
+      <div role="${error.retryable ? 'status' : 'alert'}">
+        <div data-ss-preview-page-heading>
+          ${error.retryable ? '<span data-ss-preview-page-progress aria-hidden="true"></span>' : ''}
+          <h1 data-ss-preview-page-title>${title}</h1>
+        </div>
+        <p data-ss-preview-page-description>${description}</p>
+      </div>
+      ${error.retryable ? '<div data-ss-preview-page-actions><button type="button" data-ss-preview-page-action="primary" onclick="window.location.reload()">Try again</button></div>' : ''}
+      <details>
+        <summary>Technical details</summary>
+        <pre data-preview-error="${code}">${details}</pre>
+      </details>
+    </div>
   </main>
   ${diagnostic}
   ${retryScript}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storystick/preview",
-  "version": "0.2.0-rc.0",
+  "version": "0.2.0-rc.1",
   "license": "FSL-1.1-MIT",
   "type": "module",
   "main": "dist/index.js",
@@ -115,6 +115,10 @@
       "types": "./dist/authoring/runtime-contract.d.ts",
       "import": "./dist/authoring/runtime-contract.js"
     },
+    "./page-presentation": {
+      "types": "./dist/page-presentation.d.ts",
+      "import": "./dist/page-presentation.js"
+    },
     "./sdk-error-copy": {
       "types": "./dist/sdk-error-copy.d.ts",
       "import": "./dist/sdk-error-copy.js"
@@ -177,9 +181,9 @@
   },
   "dependencies": {
     "convex": "1.42.3",
-    "@storystick/client": "0.2.0-rc.0",
-    "@storystick/transport-allowlist": "0.1.0-rc.0",
-    "@storystick/types": "0.1.0-rc.0"
+    "@storystick/client": "0.2.0-rc.1",
+    "@storystick/transport-allowlist": "0.1.0-rc.1",
+    "@storystick/types": "0.1.0-rc.1"
   },
   "devDependencies": {
     "fake-indexeddb": "^6.2.5",