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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,23 @@
1
+ import { type PreviewCopyKey } from './preview-copy.js';
2
+ export type PreviewFeedbackTone = 'neutral' | 'attention' | 'error';
3
+ export type PreviewFeedbackScope = 'configuration' | 'connection' | 'page' | 'visual-editing' | 'minimap' | 'environment';
4
+ export type PreviewFeedbackAction = 'configure' | 'reconnect' | 'retry' | 'retry-page' | 'retry-start' | 'resume' | 'current-site' | 'studio' | 'open-preview' | 'exit' | 'editor' | 'choose-version';
5
+ export interface PreviewFeedback {
6
+ readonly title: string;
7
+ readonly body: string;
8
+ readonly key: PreviewCopyKey;
9
+ readonly tone: PreviewFeedbackTone;
10
+ readonly scope: PreviewFeedbackScope;
11
+ readonly action: PreviewFeedbackAction | null;
12
+ readonly actionLabel: string | null;
13
+ readonly diagnostic: boolean;
14
+ /** Retaining a page must never outlive its admission or version boundary. */
15
+ readonly invalidatesPresentation: boolean;
16
+ readonly audience: 'editor' | 'developer';
17
+ }
18
+ /** Domain codes select product meaning; transport severity never selects presentation. */
19
+ export declare const PREVIEW_FEEDBACK: Readonly<Record<string, PreviewFeedback>>;
20
+ export declare function normalizePreviewCode(code: string): string;
21
+ export declare function lookupPreviewFeedback(code: string | null | undefined): PreviewFeedback;
22
+ /** A capability failure is local only after the current authorized page was accepted. */
23
+ export declare function isPreviewCapabilityFeedback(code: string): boolean;
@@ -0,0 +1,131 @@
1
+ import { PREVIEW_COPY } from './preview-copy.js';
2
+ const ACTION_LABELS = {
3
+ configure: 'Configure preview', reconnect: 'Reconnect preview', retry: 'Try again',
4
+ 'retry-page': 'Retry this page', 'retry-start': 'Retry start', resume: 'Resume working preview',
5
+ 'current-site': 'Use current site', studio: 'Return to Studio', 'open-preview': 'Open Preview',
6
+ exit: 'Retry exit', editor: 'Open editor', 'choose-version': 'Choose a version',
7
+ };
8
+ function feedback(key, scope, action, tone = 'error', options = {}) {
9
+ return { ...PREVIEW_COPY[key], key, scope, action, actionLabel: action === null ? null : ACTION_LABELS[action],
10
+ tone, diagnostic: true, invalidatesPresentation: scope === 'connection' || scope === 'configuration', audience: 'editor', ...options };
11
+ }
12
+ const setup = feedback('setup', 'configuration', 'configure', 'neutral', { diagnostic: false });
13
+ const origins = feedback('origins-missing', 'configuration', 'configure', 'neutral', { diagnostic: false });
14
+ const reconnect = feedback('reconnect', 'connection', 'reconnect', 'attention');
15
+ const access = feedback('access-unavailable', 'connection', 'studio', 'attention');
16
+ const binding = feedback('connection-mismatch', 'connection', 'reconnect');
17
+ const missing = feedback('open-from-studio', 'connection', 'studio', 'neutral', { diagnostic: false });
18
+ const visualLimited = feedback('visual-limited', 'visual-editing', 'editor', 'attention');
19
+ const workspaceSetup = feedback('workspace-configuration', 'environment', 'current-site', 'attention');
20
+ const workspaceUnconfirmed = feedback('workspace-unconfirmed', 'environment', 'current-site', 'attention');
21
+ const workspaceFailed = feedback('workspace-start-failed', 'environment', 'retry-start');
22
+ /** Domain codes select product meaning; transport severity never selects presentation. */
23
+ export const PREVIEW_FEEDBACK = {
24
+ preview_url_not_configured: setup,
25
+ preview_url_invalid: feedback('invalid-url', 'configuration', 'configure', 'attention'),
26
+ origin_not_configured: origins,
27
+ origin_not_allowed: feedback('origin-forbidden', 'configuration', 'configure', 'attention'),
28
+ PREVIEW_ORIGIN_FORBIDDEN: feedback('origin-forbidden', 'configuration', 'configure', 'attention'),
29
+ preview_project_mismatch: feedback('project-mismatch', 'configuration', 'configure', 'attention'),
30
+ PREVIEW_PROJECT_MISMATCH: feedback('project-mismatch', 'configuration', 'configure', 'attention'),
31
+ preview_activation_invalid: reconnect,
32
+ PREVIEW_ACTIVATION_INVALID: reconnect,
33
+ PREVIEW_CONTEXT_UNAVAILABLE: feedback('unavailable', 'connection', 'retry'),
34
+ session_expired: reconnect,
35
+ session_not_found: reconnect,
36
+ 'runtime.SESSION_EXPIRED': reconnect,
37
+ PREVIEW_GRANT_MALFORMED: reconnect,
38
+ PREVIEW_GRANT_INVALID: reconnect,
39
+ PREVIEW_GRANT_EXPIRED: reconnect,
40
+ PREVIEW_VIEW_UNAVAILABLE: reconnect,
41
+ CONTENT_SHAPE_RELOAD_REQUIRED: feedback('deployment-changed', 'connection', 'reconnect', 'attention'),
42
+ PREVIEW_GRANT_MISSING: missing,
43
+ PREVIEW_GRANT_REQUIRED: missing,
44
+ PREVIEW_REQUIRED: missing,
45
+ SESSION_SUBSCRIPTION_UNAVAILABLE: feedback('connection-interrupted', 'connection', 'reconnect'),
46
+ identity_carrier_timeout: feedback('connection-interrupted', 'connection', 'reconnect'),
47
+ identity_recovery_exhausted: feedback('connection-interrupted', 'connection', 'reconnect'),
48
+ preview_lifecycle_blocked: access,
49
+ PREVIEW_GRANT_REVOKED: access,
50
+ PREVIEW_ACCESS_REVOKED: access,
51
+ PREVIEW_GRANT_FORBIDDEN: access,
52
+ INVALID_IDENTITY_CLAIM: access,
53
+ PREVIEW_CONTEXT_INVALID: feedback('view-unavailable', 'connection', 'choose-version', 'attention'),
54
+ PREVIEW_CONTEXT_ENDED: feedback('ended', 'connection', 'studio', 'neutral', { diagnostic: false }),
55
+ PREVIEW_CONTEXT_EXIT_UNAVAILABLE: feedback('exit-incomplete', 'connection', 'exit', 'attention'),
56
+ PREVIEW_ADMISSION_SUPERSEDED: feedback('admission-superseded', 'connection', 'reconnect', 'attention'),
57
+ protocol_invalid: binding,
58
+ session_mismatch: binding,
59
+ PREVIEW_GRANT_BINDING_MISMATCH: binding,
60
+ PREVIEW_ORIGIN_MISMATCH: binding,
61
+ PREVIEW_TOKEN_PROTOCOL_INVALID: feedback('integration-update', 'connection', 'studio', 'attention'),
62
+ 'runtime.preview_read_unavailable': feedback('content-unavailable', 'page', 'retry-page'),
63
+ 'runtime.customer_render_failed': feedback('render-failed', 'page', 'retry-page'),
64
+ PREVIEW_CONVERGENCE_STOPPED: feedback('update-failed', 'page', 'retry-page'),
65
+ 'runtime.PREVIEW_SCOPE_MISMATCH': feedback('scope-mismatch', 'page', 'retry-page', 'attention', { invalidatesPresentation: true }),
66
+ 'runtime.PREVIEW_RELEASE_SCOPE_MISMATCH': feedback('scope-mismatch', 'page', 'retry-page', 'attention', { invalidatesPresentation: true }),
67
+ 'runtime.preview_context_superseded': feedback('selection-superseded', 'page', 'choose-version', 'attention', { invalidatesPresentation: true }),
68
+ 'runtime.schema_sync_delayed': feedback('visual-connecting', 'visual-editing', null, 'neutral'),
69
+ 'runtime.cache_unavailable': visualLimited,
70
+ 'runtime.schema_delivery_failed': visualLimited,
71
+ 'runtime.schema_upgrade_required': feedback('visual-update', 'visual-editing', 'editor', 'attention'),
72
+ 'runtime.suspicious_codeword_sink': feedback('marker-diagnostic', 'visual-editing', null, 'attention', { audience: 'developer' }),
73
+ PREVIEW_MINIMAP_TIMEOUT: feedback('minimap-unavailable', 'minimap', 'open-preview', 'neutral'),
74
+ workspace_preview_unavailable: feedback('workspace-unavailable', 'environment', 'retry-start', 'attention'),
75
+ workspace_preview_stopped: feedback('workspace-stopped', 'environment', 'resume', 'neutral', { diagnostic: false }),
76
+ workspace_preview_start_failed: workspaceFailed,
77
+ PROJECT_WORKSPACE_NOT_ENABLED: workspaceSetup,
78
+ PROJECT_WORKSPACE_EXECUTION_DISABLED: workspaceSetup,
79
+ PROJECT_WORKSPACE_PROVIDER_NOT_CONFIGURED: workspaceSetup,
80
+ PROJECT_WORKSPACE_PROVIDER_NAMESPACE_UNKNOWN: workspaceSetup,
81
+ PROJECT_WORKSPACE_PROVIDER_NAMESPACE_CHANGED: workspaceSetup,
82
+ PROJECT_WORKSPACE_RECIPE_CHANGED: workspaceSetup,
83
+ PROJECT_WORKSPACE_SOURCE_PREPARATION_MISMATCH: workspaceSetup,
84
+ PROJECT_WORKSPACE_BUDGET_UNAVAILABLE: workspaceSetup,
85
+ PROJECT_WORKSPACE_BUDGET_ALLOCATION_INVALID: workspaceSetup,
86
+ PROJECT_WORKSPACE_BUDGET_CHANGED: workspaceSetup,
87
+ PROJECT_WORKSPACE_ALLOCATION_OUTCOME_UNKNOWN: workspaceUnconfirmed,
88
+ PROJECT_WORKSPACE_OUTCOME_UNKNOWN: workspaceUnconfirmed,
89
+ PROJECT_WORKSPACE_SUSPEND_UNCONFIRMED: workspaceUnconfirmed,
90
+ PROJECT_WORKSPACE_RUNTIME_NOT_STOPPED: workspaceUnconfirmed,
91
+ PROJECT_WORKSPACE_RELEASE_NOT_EDITABLE: feedback('release-readonly', 'environment', 'choose-version', 'attention', { diagnostic: false }),
92
+ PROJECT_WORKSPACE_RELEASE_REQUIRED: feedback('workspace-selection-failed', 'environment', 'choose-version', 'attention'),
93
+ PROJECT_WORKSPACE_BINDING_MISMATCH: feedback('workspace-unavailable', 'environment', 'current-site', 'attention', { invalidatesPresentation: true }),
94
+ PROJECT_WORKSPACE_BUSY: feedback('busy', 'environment', 'retry-start', 'attention'),
95
+ PROJECT_WORKSPACE_NOT_PREPARED: feedback('workspace-not-prepared', 'environment', 'current-site', 'neutral', { diagnostic: false }),
96
+ PROJECT_WORKSPACE_FORBIDDEN: feedback('workspace-forbidden', 'environment', 'current-site', 'attention', { diagnostic: false }),
97
+ PROJECT_WORKSPACE_BUDGET_EXHAUSTED: feedback('workspace-limit', 'environment', 'current-site', 'attention', { diagnostic: false }),
98
+ PROJECT_WORKSPACE_SOURCE_RECOVERY_REQUIRED: feedback('workspace-recovery', 'environment', 'current-site', 'attention'),
99
+ workspace_switch_failed: feedback('workspace-switch-failed', 'environment', 'retry'),
100
+ workspace_stop_failed: feedback('workspace-stop-failed', 'environment', 'retry'),
101
+ workspace_stopped_recovery: feedback('workspace-stopped-recovery', 'environment', 'current-site', 'attention'),
102
+ workspace_selection_failed: feedback('workspace-selection-failed', 'environment', 'choose-version'),
103
+ PREVIEW_SESSION_MISSING: feedback('opening-invalid', 'connection', 'studio', 'neutral', { diagnostic: false }),
104
+ PREVIEW_REDIRECT_UNSAFE: feedback('opening-invalid', 'connection', 'studio', 'neutral', { diagnostic: false }),
105
+ PREVIEW_SCOPE_CONFLICT: feedback('opening-invalid', 'connection', 'studio', 'neutral', { diagnostic: false }),
106
+ preview_session_creation_failed: feedback('opening-failed', 'connection', 'reconnect'),
107
+ UNKNOWN: feedback('unavailable', 'page', 'retry'),
108
+ };
109
+ export function normalizePreviewCode(code) {
110
+ return code.startsWith('storystick/') ? code.slice('storystick/'.length) : code;
111
+ }
112
+ export function lookupPreviewFeedback(code) {
113
+ const key = normalizePreviewCode(code ?? '');
114
+ if (Object.hasOwn(PREVIEW_FEEDBACK, key))
115
+ return PREVIEW_FEEDBACK[key];
116
+ if (/^PROJECT_WORKSPACE_[A-Z_]{1,80}$/.test(key))
117
+ return workspaceFailed;
118
+ if (/^PREVIEW_(?:GRANT_ACTIVATION|GRANT_ACCESS|AUTHORING_ADMISSION)_[A-Z_]{1,40}$/.test(key)) {
119
+ if (key.endsWith('_RATE_LIMITED'))
120
+ return feedback('busy', 'connection', 'retry', 'attention');
121
+ if (key.endsWith('_AUTH_FAILED'))
122
+ return access;
123
+ return feedback('unavailable', 'connection', 'retry');
124
+ }
125
+ return PREVIEW_FEEDBACK.UNKNOWN;
126
+ }
127
+ /** A capability failure is local only after the current authorized page was accepted. */
128
+ export function isPreviewCapabilityFeedback(code) {
129
+ const scope = lookupPreviewFeedback(code).scope;
130
+ return scope === 'visual-editing';
131
+ }
@@ -1,4 +1,6 @@
1
1
  /** Public bootstrap hint only. The same-origin token route still authorizes it. */
2
2
  export declare function readStandalonePreviewSessionId(expectedProjectId?: string): string | null;
3
+ /** Explicit intent is a display hint only; it grants no Preview access. */
4
+ export declare function hasExplicitPreviewBrowserContext(expectedProjectId?: string): boolean;
3
5
  /** Small, framework-independent gate; never loads the authenticated runtime. */
4
6
  export declare function isPreviewBrowserContext(expectedProjectId?: string): boolean;
@@ -14,9 +14,14 @@ export function readStandalonePreviewSessionId(expectedProjectId) {
14
14
  return null;
15
15
  return /^[A-Za-z0-9_-]{1,180}$/.test(stored.sessionId) ? stored.sessionId : null;
16
16
  }
17
+ /** Explicit intent is a display hint only; it grants no Preview access. */
18
+ export function hasExplicitPreviewBrowserContext(expectedProjectId) {
19
+ return typeof window !== 'undefined' && (new URLSearchParams(window.location.search).has(PREVIEW_SESSION_QUERY_PARAM) ||
20
+ readStandalonePreviewSessionId(expectedProjectId) !== null);
21
+ }
17
22
  /** Small, framework-independent gate; never loads the authenticated runtime. */
18
23
  export function isPreviewBrowserContext(expectedProjectId) {
19
24
  if (typeof window === 'undefined')
20
25
  return false;
21
- return window.parent !== window || readStandalonePreviewSessionId(expectedProjectId) !== null;
26
+ return window.parent !== window || hasExplicitPreviewBrowserContext(expectedProjectId);
22
27
  }
@@ -10,4 +10,4 @@ export declare function rememberStandaloneView(view: {
10
10
  /** Persistent interaction choice for this view only; access is authorized separately. */
11
11
  export declare function readStandaloneInteractionMode(projectId: string | null, sessionId: string | null): 'edit' | 'browse';
12
12
  export { rememberStandaloneInteractionMode } from './carriers/storage.js';
13
- export { readStandalonePreviewSessionId, isPreviewBrowserContext } from './browser-context-gate.js';
13
+ export { readStandalonePreviewSessionId, isPreviewBrowserContext, hasExplicitPreviewBrowserContext } from './browser-context-gate.js';
@@ -19,4 +19,4 @@ export function readStandaloneInteractionMode(projectId, sessionId) {
19
19
  : 'edit';
20
20
  }
21
21
  export { rememberStandaloneInteractionMode } from './carriers/storage.js';
22
- export { readStandalonePreviewSessionId, isPreviewBrowserContext } from './browser-context-gate.js';
22
+ export { readStandalonePreviewSessionId, isPreviewBrowserContext, hasExplicitPreviewBrowserContext } from './browser-context-gate.js';
@@ -0,0 +1,24 @@
1
+ /** Framework-independent presentation for Preview's opening and failure pages.
2
+ * The activation route can render the same surface before any React runtime. */
3
+ export declare const STORYSTICK_MARK_VIEW_BOX = "0 0 12 11";
4
+ export declare const STORYSTICK_MARK_RECTS: readonly [{
5
+ readonly x: 0;
6
+ readonly y: 4;
7
+ readonly width: 3;
8
+ readonly height: 7;
9
+ readonly rx: 1;
10
+ }, {
11
+ readonly x: 4.5;
12
+ readonly y: 0;
13
+ readonly width: 3;
14
+ readonly height: 11;
15
+ readonly rx: 1;
16
+ }, {
17
+ readonly x: 9;
18
+ readonly y: 6;
19
+ readonly width: 3;
20
+ readonly height: 5;
21
+ readonly rx: 1;
22
+ }];
23
+ export declare const PREVIEW_PAGE_BRAND_HTML: string;
24
+ 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";
@@ -0,0 +1,32 @@
1
+ /** Framework-independent presentation for Preview's opening and failure pages.
2
+ * The activation route can render the same surface before any React runtime. */
3
+ export const STORYSTICK_MARK_VIEW_BOX = '0 0 12 11';
4
+ export const STORYSTICK_MARK_RECTS = [
5
+ { x: 0, y: 4, width: 3, height: 7, rx: 1 },
6
+ { x: 4.5, y: 0, width: 3, height: 11, rx: 1 },
7
+ { x: 9, y: 6, width: 3, height: 5, rx: 1 },
8
+ ];
9
+ 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>`;
10
+ export const PREVIEW_PAGE_STYLES = `
11
+ [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; }
12
+ [data-ss-preview-page-content] { width: 100%; max-width: 360px; margin: auto; text-align: center; overflow-wrap: anywhere; }
13
+ [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; }
14
+ [data-ss-preview-page-brand] svg { flex: none; width: 15px; height: 14px; transform: rotate(90deg); }
15
+ [data-ss-preview-page-heading] { display: flex; align-items: center; justify-content: center; gap: 10px; }
16
+ [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; }
17
+ [data-ss-preview-page-description] { margin: 12px 0 0; color: var(--ss-text-secondary, oklch(.471 .006 258.364)); font: inherit; text-wrap: pretty; }
18
+ [data-ss-preview-page-actions] { display: flex; flex-wrap: wrap; align-items: center; justify-content: center; gap: 8px; margin-top: 24px; }
19
+ [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; }
20
+ [data-ss-preview-page-action]:hover { background: var(--ss-surface-field, oklch(.958 .001 255)); }
21
+ [data-ss-preview-page-action='primary'] { background: var(--ss-text-primary, oklch(.2 .007 258.364)); color: #fff; box-shadow: none; }
22
+ [data-ss-preview-page-action='primary']:hover { background: #303034; }
23
+ [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; }
24
+ [data-ss-preview-page] details { margin-top: 24px; color: var(--ss-text-secondary, oklch(.471 .006 258.364)); font-size: 12px; line-height: 18px; }
25
+ [data-ss-preview-page] summary { width: fit-content; margin-inline: auto; border-radius: 4px; cursor: pointer; }
26
+ [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; }
27
+ [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; }
28
+ [data-ss-preview-page-progress]::before { content: ''; position: absolute; inset: 0; box-sizing: border-box; border: 2px solid currentColor; border-radius: 50%; opacity: .2; }
29
+ [data-ss-preview-page-progress]::after { content: ''; position: absolute; top: 1px; left: calc(50% - 2px); width: 4px; height: 4px; border-radius: 50%; background: currentColor; }
30
+ @keyframes ss-preview-page-orbit { to { transform: rotate(360deg); } }
31
+ @media (prefers-reduced-motion: reduce) { [data-ss-preview-page-progress] { animation: none; } [data-ss-preview-page-action] { transition: none; } }
32
+ `;
@@ -1,48 +1,6 @@
1
- /**
2
- * ADR-134 §9.T2 — SDK-side copy table for the `<Storystick />` terminal
3
- * panel in `@storystick/next`. Mirror of `apps/studio/src/lib/preview-
4
- * error-copy.ts`, scoped to the SUBSET of codes the customer-side panel
5
- * actually renders. A contract test at `apps/studio/tests/sdk-error-
6
- * copy-contract.test.ts` pins overlap rows verbatim against Studio's
7
- * copy so the two tables can't drift on shared codes.
8
- *
9
- * Why a separate table : Studio product copy doesn't ship in customer-
10
- * runtime bundle (different audience, different vocabulary, different
11
- * bundle size budget). The SDK surface renders inside the customer's
12
- * page, so it speaks to the DEVELOPER hosting the customer site rather
13
- * than to a Studio editor. Phrasing can legitimately diverge on Studio-
14
- * specific codes ; the contract test ensures shared codes don't.
15
- *
16
- * Codes covered :
17
- * - `runtime.cache_unavailable` (D6 — Layer1 cache failed to open)
18
- * - `runtime.schema_sync_delayed` (D6 — attempt 1 of schema retry)
19
- * - `runtime.schema_delivery_failed` (D6 — attempt 5 of schema retry)
20
- * - `identity_carrier_timeout` when Studio identity cannot be established.
21
- * - PreviewGrant/context boundary codes emitted by the same-origin token
22
- * route or Convex subscriptions.
23
- *
24
- * Unknown codes fall back to a generic entry. The fallback's body is
25
- * intentionally honest : the SDK doesn't claim to know what happened.
26
- */
27
- export interface SdkErrorCopyEntry {
28
- title: string;
29
- body: string;
30
- /**
31
- * Non-exhaustive list of likely causes. The SDK panel renders these
32
- * as a bullet list inside the red surface. Empty array → list is
33
- * suppressed.
34
- */
35
- commonCauses: ReadonlyArray<string>;
1
+ import { type PreviewFeedback } from './framework/preview-feedback.js';
2
+ export interface SdkErrorCopyEntry extends PreviewFeedback {
3
+ readonly commonCauses: ReadonlyArray<string>;
36
4
  }
37
- /**
38
- * Canonical map. Codes here MUST match `apps/studio/src/lib/preview-
39
- * error-copy.ts` on overlap rows (contract-tested). Title + body
40
- * fields share verbatim, commonCauses share as a set (order can
41
- * differ).
42
- */
43
5
  export declare const SDK_ERROR_COPY: Readonly<Record<string, SdkErrorCopyEntry>>;
44
- /**
45
- * Look up the structured SDK copy for a code. Always returns an entry
46
- * (never null) so the panel can render unconditionally.
47
- */
48
6
  export declare function lookupSdkCopy(code: string | null | undefined): SdkErrorCopyEntry;
@@ -1,182 +1,5 @@
1
- /**
2
- * ADR-134 §9.T2 — SDK-side copy table for the `<Storystick />` terminal
3
- * panel in `@storystick/next`. Mirror of `apps/studio/src/lib/preview-
4
- * error-copy.ts`, scoped to the SUBSET of codes the customer-side panel
5
- * actually renders. A contract test at `apps/studio/tests/sdk-error-
6
- * copy-contract.test.ts` pins overlap rows verbatim against Studio's
7
- * copy so the two tables can't drift on shared codes.
8
- *
9
- * Why a separate table : Studio product copy doesn't ship in customer-
10
- * runtime bundle (different audience, different vocabulary, different
11
- * bundle size budget). The SDK surface renders inside the customer's
12
- * page, so it speaks to the DEVELOPER hosting the customer site rather
13
- * than to a Studio editor. Phrasing can legitimately diverge on Studio-
14
- * specific codes ; the contract test ensures shared codes don't.
15
- *
16
- * Codes covered :
17
- * - `runtime.cache_unavailable` (D6 — Layer1 cache failed to open)
18
- * - `runtime.schema_sync_delayed` (D6 — attempt 1 of schema retry)
19
- * - `runtime.schema_delivery_failed` (D6 — attempt 5 of schema retry)
20
- * - `identity_carrier_timeout` when Studio identity cannot be established.
21
- * - PreviewGrant/context boundary codes emitted by the same-origin token
22
- * route or Convex subscriptions.
23
- *
24
- * Unknown codes fall back to a generic entry. The fallback's body is
25
- * intentionally honest : the SDK doesn't claim to know what happened.
26
- */
27
- const PREVIEW_ACCESS_ENDED = {
28
- title: 'Preview access ended',
29
- body: 'This preview is no longer active. Return to Storystick Studio to open a new preview.',
30
- commonCauses: [],
31
- };
32
- const PREVIEW_ADMISSION_MISSING = {
33
- title: 'Preview access is missing',
34
- body: 'The site did not receive the Preview admission cookie. Open a fresh Preview from Studio. If this continues, check the site’s HTTPS and cookie configuration.',
35
- commonCauses: [
36
- 'The browser did not accept or send the Preview cookie in this context.',
37
- 'The Preview admission expired or was cleared.',
38
- ],
39
- };
40
- const PREVIEW_RENDER_ADMISSION_MISSING = {
41
- title: 'Preview needs a fresh activation',
42
- body: 'The site could not confirm Preview for its current deployment. Reopen Preview from Studio.',
43
- commonCauses: [
44
- 'The site was redeployed after Preview was opened.',
45
- 'The browser did not return the site’s Draft Mode cookie.',
46
- ],
47
- };
48
- const PREVIEW_BINDING_MISMATCH = {
49
- title: 'Preview binding mismatch',
50
- body: 'This preview does not match the active project, origin, or session. Reopen the document from the correct Storystick Studio project.',
51
- commonCauses: [],
52
- };
53
- const PREVIEW_VIEW_UNAVAILABLE = {
54
- title: 'This preview has expired',
55
- body: 'Open a new preview from Studio to continue.',
56
- commonCauses: [],
57
- };
58
- const PREVIEW_ADMISSION_SUPERSEDED = {
59
- title: 'Preview changed in another view',
60
- body: 'This page could not reconnect to the current preview. Reopen it from Studio.',
61
- commonCauses: [],
62
- };
63
- const PREVIEW_PROTOCOL_INVALID = {
64
- title: 'Preview adapter mismatch',
65
- body: 'The customer preview route returned an incompatible response. Update the Storystick packages together, then reopen the document.',
66
- commonCauses: [],
67
- };
68
- /**
69
- * Canonical map. Codes here MUST match `apps/studio/src/lib/preview-
70
- * error-copy.ts` on overlap rows (contract-tested). Title + body
71
- * fields share verbatim, commonCauses share as a set (order can
72
- * differ).
73
- */
74
- export const SDK_ERROR_COPY = {
75
- 'runtime.preview_read_unavailable': {
76
- title: 'Preview content temporarily unavailable',
77
- body: 'The content service could not answer this page’s request. Retry when the connection is restored.',
78
- commonCauses: [],
79
- },
80
- 'runtime.customer_render_failed': {
81
- title: 'This page could not render',
82
- body: 'The customer site reported a rendering error. You can open another document. Retry this page after its rendering error has been corrected.',
83
- commonCauses: [],
84
- },
85
- // ─── D-category runtime warnings/errors (emitted by SDK boot/schema) ──
86
- 'runtime.cache_unavailable': {
87
- title: 'Preview cache unavailable',
88
- body: 'The preview cache could not be opened, so observed overlays are disabled. Authenticated preview still works; the editor will fall back to explicit rendering.',
89
- commonCauses: [
90
- 'IndexedDB is disabled (private browsing on older Firefox / Safari).',
91
- 'A browser extension is blocking storage access.',
92
- ],
93
- },
94
- 'runtime.schema_sync_delayed': {
95
- title: 'Loading schema is taking longer than usual',
96
- body: 'Studio is still fetching the project schema. Field-level overlays will be limited until the schema arrives.',
97
- commonCauses: [
98
- 'Slow network between the iframe and the Storystick gateway.',
99
- 'The gateway returned a transient error and the SDK is retrying.',
100
- ],
101
- },
102
- 'runtime.schema_delivery_failed': {
103
- title: 'Schema delivery failed',
104
- body: 'The preview schema could not be fetched after 5 attempts. Field-level overlays are unavailable for this session.',
105
- commonCauses: [
106
- 'The Storystick gateway is unreachable from the iframe.',
107
- 'Network conditions prevented the schema HTTP request from completing.',
108
- 'Reload the iframe to retry from a fresh attempt cycle.',
109
- ],
110
- },
111
- // ─── Grant / origin / session codes ────────────────────────────
112
- identity_carrier_timeout: {
113
- title: 'Preview identity could not be established',
114
- body: 'Studio did not deliver a preview identity to this iframe in time. Reopen the document in Storystick Studio to retry.',
115
- commonCauses: [],
116
- },
117
- PREVIEW_GRANT_MISSING: PREVIEW_ADMISSION_MISSING,
118
- 'storystick/PREVIEW_GRANT_MISSING': PREVIEW_ADMISSION_MISSING,
119
- CONTENT_SHAPE_RELOAD_REQUIRED: PREVIEW_RENDER_ADMISSION_MISSING,
120
- 'storystick/CONTENT_SHAPE_RELOAD_REQUIRED': PREVIEW_RENDER_ADMISSION_MISSING,
121
- PREVIEW_GRANT_MALFORMED: PREVIEW_ACCESS_ENDED,
122
- 'storystick/PREVIEW_GRANT_MALFORMED': PREVIEW_ACCESS_ENDED,
123
- PREVIEW_GRANT_INVALID: PREVIEW_ACCESS_ENDED,
124
- 'storystick/PREVIEW_GRANT_INVALID': PREVIEW_ACCESS_ENDED,
125
- PREVIEW_GRANT_REVOKED: PREVIEW_ACCESS_ENDED,
126
- 'storystick/PREVIEW_GRANT_REVOKED': PREVIEW_ACCESS_ENDED,
127
- PREVIEW_GRANT_EXPIRED: PREVIEW_ACCESS_ENDED,
128
- 'storystick/PREVIEW_GRANT_EXPIRED': PREVIEW_ACCESS_ENDED,
129
- PREVIEW_ACCESS_REVOKED: PREVIEW_ACCESS_ENDED,
130
- 'storystick/PREVIEW_ACCESS_REVOKED': PREVIEW_ACCESS_ENDED,
131
- PREVIEW_VIEW_UNAVAILABLE,
132
- 'storystick/PREVIEW_VIEW_UNAVAILABLE': PREVIEW_VIEW_UNAVAILABLE,
133
- PREVIEW_ADMISSION_SUPERSEDED,
134
- 'storystick/PREVIEW_ADMISSION_SUPERSEDED': PREVIEW_ADMISSION_SUPERSEDED,
135
- PREVIEW_CONTEXT_INVALID: PREVIEW_ACCESS_ENDED,
136
- 'storystick/PREVIEW_CONTEXT_INVALID': PREVIEW_ACCESS_ENDED,
137
- PREVIEW_CONTEXT_ENDED: PREVIEW_ACCESS_ENDED,
138
- PREVIEW_CONTEXT_EXIT_UNAVAILABLE: {
139
- title: 'Preview exit could not finish',
140
- body: 'The shared preview ended, but this page could not clear its local preview access. Retry Exit Preview.',
141
- commonCauses: [],
142
- },
143
- PREVIEW_GRANT_REQUIRED: PREVIEW_BINDING_MISMATCH,
144
- PREVIEW_GRANT_FORBIDDEN: PREVIEW_BINDING_MISMATCH,
145
- 'storystick/PREVIEW_GRANT_FORBIDDEN': PREVIEW_BINDING_MISMATCH,
146
- PREVIEW_GRANT_BINDING_MISMATCH: PREVIEW_BINDING_MISMATCH,
147
- 'storystick/PREVIEW_GRANT_BINDING_MISMATCH': PREVIEW_BINDING_MISMATCH,
148
- PREVIEW_ORIGIN_MISMATCH: PREVIEW_BINDING_MISMATCH,
149
- 'storystick/PREVIEW_ORIGIN_MISMATCH': PREVIEW_BINDING_MISMATCH,
150
- PREVIEW_PROJECT_MISMATCH: PREVIEW_BINDING_MISMATCH,
151
- 'storystick/PREVIEW_PROJECT_MISMATCH': PREVIEW_BINDING_MISMATCH,
152
- PREVIEW_TOKEN_PROTOCOL_INVALID: PREVIEW_PROTOCOL_INVALID,
153
- PREVIEW_REQUIRED: {
154
- title: 'Preview mode required',
155
- body: 'This route can only be rendered inside an active Storystick preview session. Open it from Studio to view.',
156
- commonCauses: [],
157
- },
158
- UNKNOWN: {
159
- title: 'Unknown preview error',
160
- body: 'The Storystick SDK received an unrecognised error code. Reload the iframe ; if the issue persists, check the Studio logs.',
161
- commonCauses: [],
162
- },
163
- };
164
- /**
165
- * Fallback entry. Returned by `lookupSdkCopy` for codes not in the map.
166
- * Honest body — the SDK doesn't pretend to know.
167
- */
168
- const FALLBACK_SDK_ENTRY = {
169
- title: 'Storystick preview error',
170
- body: 'Preview connection lost. Reopen the document in Storystick Studio to resume.',
171
- commonCauses: [],
172
- };
173
- /**
174
- * Look up the structured SDK copy for a code. Always returns an entry
175
- * (never null) so the panel can render unconditionally.
176
- */
1
+ import { PREVIEW_FEEDBACK, lookupPreviewFeedback } from './framework/preview-feedback.js';
2
+ export const SDK_ERROR_COPY = Object.fromEntries(Object.entries(PREVIEW_FEEDBACK).map(([code, entry]) => [code, { ...entry, commonCauses: [] }]));
177
3
  export function lookupSdkCopy(code) {
178
- if (typeof code !== 'string' || code.length === 0) {
179
- return FALLBACK_SDK_ENTRY;
180
- }
181
- return SDK_ERROR_COPY[code] ?? FALLBACK_SDK_ENTRY;
4
+ return { ...lookupPreviewFeedback(code), commonCauses: [] };
182
5
  }
@@ -1,7 +1,11 @@
1
+ import { lookupPreviewFeedback } from '../framework/preview-feedback.js';
2
+ import { PREVIEW_COPY } from '../framework/preview-copy.js';
3
+ import { previewDiagnostic, safePreviewCode } from '../framework/preview-diagnostic.js';
4
+ import { PREVIEW_PAGE_BRAND_HTML, PREVIEW_PAGE_STYLES } from "../page-presentation.js";
1
5
  import { StorystickError } from "@storystick/client";
2
6
  import { mapPreviewSessionError } from "@storystick/preview/session-subscriber";
3
7
  export function previewInitialRouteErrorResponse(request, error) {
4
- if (error.recoverable && requestAcceptsHtml(request)) {
8
+ if (requestAcceptsHtml(request)) {
5
9
  return previewHtmlErrorResponse(error, new URL(request.url).searchParams.get("_ss_session"));
6
10
  }
7
11
  return previewErrorResponse(error);
@@ -62,8 +66,9 @@ function buildHtmlError(error, sessionId) {
62
66
  const diagnostic = sessionId && /^[A-Za-z0-9_-]{1,128}$/.test(sessionId) && diagnosticCodes.includes(error.code)
63
67
  ? `<script>window.parent.postMessage(${JSON.stringify({ type: 'storystick.preview.activation-error', sessionId, code: error.code })}, '*');</script>`
64
68
  : '';
65
- const code = escapeHtml(error.code);
66
- const message = escapeHtml(error.message);
69
+ const code = escapeHtml(safePreviewCode(error.code));
70
+ const feedback = lookupPreviewFeedback(error.code);
71
+ const details = escapeHtml(previewDiagnostic({ code: error.code, reference: 'upstreamRef' in error ? error.upstreamRef : undefined }));
67
72
  const retryScript = error.retryable
68
73
  ? `<script>
69
74
  (() => {
@@ -88,6 +93,10 @@ function buildHtmlError(error, sessionId) {
88
93
  } catch (_) {}
89
94
  if (attempt >= maxAttempts) {
90
95
  document.body.dataset.previewRecovery = 'stopped';
96
+ document.title = ${JSON.stringify(PREVIEW_COPY['connection-interrupted'].title)};
97
+ document.querySelector('[data-ss-preview-page-progress]')?.remove();
98
+ document.querySelector('[data-ss-preview-page-title]').textContent = ${JSON.stringify(PREVIEW_COPY['connection-interrupted'].title)};
99
+ document.querySelector('[data-ss-preview-page-description]').textContent = ${JSON.stringify(PREVIEW_COPY['connection-interrupted'].body)};
91
100
  return;
92
101
  }
93
102
  const delay = Math.min(5000, Math.round(500 * Math.pow(1.5, attempt - 1)));
@@ -97,29 +106,33 @@ function buildHtmlError(error, sessionId) {
97
106
  })();
98
107
  </script>`
99
108
  : "";
100
- const title = error.retryable ? "Preview recovering" : "Preview unavailable";
101
- const heading = error.retryable
102
- ? "Preview reconnecting"
103
- : error.code === "PREVIEW_PROJECT_MISMATCH" ? "Preview is connected to another project" : "Reopen this preview from Storystick Studio";
109
+ const title = escapeHtml(error.retryable ? PREVIEW_COPY.reconnecting.title : feedback.title);
110
+ const description = escapeHtml(error.retryable ? PREVIEW_COPY.reconnecting.body : feedback.action === 'reconnect' ? `${feedback.body} ${PREVIEW_COPY['open-from-studio'].body}` : feedback.body);
104
111
  return `<!doctype html>
105
112
  <html lang="en">
106
113
  <head>
107
114
  <meta charset="utf-8">
108
115
  <meta name="viewport" content="width=device-width, initial-scale=1">
109
116
  <title>${title}</title>
110
- <style>
111
- :root { color-scheme: light dark; font-family: system-ui, sans-serif; }
112
- body { margin: 0; min-height: 100vh; display: grid; place-items: center; background: Canvas; color: CanvasText; }
113
- main { max-width: 28rem; padding: 1.5rem; line-height: 1.5; }
114
- h1 { font-size: 1rem; margin: 0 0 .5rem; }
115
- p { margin: 0; color: color-mix(in srgb, CanvasText 70%, transparent); }
116
- code { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: .8125rem; }
117
- </style>
117
+ <style>body { margin: 0; } ${PREVIEW_PAGE_STYLES}</style>
118
118
  </head>
119
119
  <body>
120
- <main aria-live="polite">
121
- <h1>${heading}</h1>
122
- <p data-preview-error="${code}">${message}</p>
120
+ <main data-ss-preview-page data-preview-code="${code}">
121
+ <div data-ss-preview-page-content>
122
+ ${PREVIEW_PAGE_BRAND_HTML}
123
+ <div role="status">
124
+ <div data-ss-preview-page-heading>
125
+ ${error.retryable ? '<span data-ss-preview-page-progress aria-hidden="true"></span>' : ''}
126
+ <h1 data-ss-preview-page-title>${title}</h1>
127
+ </div>
128
+ <p data-ss-preview-page-description>${description}</p>
129
+ </div>
130
+ ${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>' : ''}
131
+ ${feedback.diagnostic ? `<details>
132
+ <summary>Diagnostic</summary>
133
+ <pre data-preview-error="${code}">${details}</pre>
134
+ </details>` : ''}
135
+ </div>
123
136
  </main>
124
137
  ${diagnostic}
125
138
  ${retryScript}
@@ -1,3 +1,4 @@
1
+ import { collectRouteDocumentSliceTypes } from '@storystick/types/public-delivery';
1
2
  import { collectPreviewReadObservations } from '@storystick/client/internal';
2
3
  import { appliedPreviewVariantIdFromQueryResult, previewReadScopeEchoFromQueryResult, requestedPreviewVariantIdFromQueryResult, collectPreviewProvenanceSourceMappedQueryResults, collectPreviewFrameDependencies, createPreviewProvenanceEditableManifestMatcher, formatPreviewProvenanceCanonicalPath, materializePreviewProvenanceSourceMap, planPreviewProvenanceEditableTextLeaves, previewProvenanceEditableTextPathPatternMatches, previewProvenanceRichTextTextNodes, previewProvenanceSourceIdentityFromQueryResult, } from '@storystick/preview/provenance';
3
4
  import { normalizePreviewVariantId } from '@storystick/preview/identity';
@@ -515,18 +516,7 @@ function collectSlicePlanningScopes(document) {
515
516
  return scopes;
516
517
  }
517
518
  export function unstable_collectPreviewRouteDocumentSliceTypes(document) {
518
- const out = new Set();
519
- for (const scope of collectSlicePlanningScopes(document)) {
520
- for (const slice of scope.slices) {
521
- if (!isRecord(slice))
522
- continue;
523
- const sliceType = slice._type;
524
- if (typeof sliceType === 'string' && sliceType.length > 0) {
525
- out.add(sliceType);
526
- }
527
- }
528
- }
529
- return out;
519
+ return collectRouteDocumentSliceTypes(document);
530
520
  }
531
521
  function zoneMappingsSidecar(document) {
532
522
  const mappings = document._zoneMappings;