@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.
package/PUBLIC-API.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # @storystick/preview API contract
2
2
 
3
- 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.
3
+ Install this candidate explicitly with `@storystick/preview@0.2.0-rc.2` after registry bootstrap and publication. This repository alone does not make the candidate or beta channel available on npm.
4
4
 
5
- Version 0.2.0-rc.0, cohort `sdk-0.2.0-rc.0`. ESM distribution; no CommonJS or universal Edge compatibility is promised.
5
+ Version 0.2.0-rc.2, cohort `sdk-0.2.0-rc.2`. ESM distribution; no CommonJS or universal Edge compatibility is promised.
6
6
 
7
7
  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.
8
8
 
@@ -35,6 +35,7 @@ This package supports the integration facades; installing it directly is an adva
35
35
  | `./provenance` | Reserved SDK contract |
36
36
  | `./provenance/richtext-slice-embed-address` | Reserved SDK contract |
37
37
  | `./authoring/runtime-contract` | Reserved SDK contract |
38
+ | `./page-presentation` | Reserved SDK contract |
38
39
  | `./sdk-error-copy` | Reserved SDK contract |
39
40
  | `./session-subscriber` | Reserved SDK contract |
40
41
  | `./provenance/source-registry` | Reserved SDK contract |
package/dist/.source-hash CHANGED
@@ -1 +1 @@
1
- d7ff593b5f2ade5e8f9370eb42602497bb6b37f2c82edb6b712289200e939956
1
+ a5f163aae4bf2733892f4674626e581304e6173491f17c8ccdfea4886b0fa0a9
@@ -1,7 +1,8 @@
1
+ import { type StudioContentShapeDescriptor } from '@storystick/types';
1
2
  import type { PreviewPerspective, PreviewReadContext } from '@storystick/types/preview-query-targeting';
2
3
  import type { PreviewV2RevealSourceRequest, PreviewV2RevealSliceRequest } from '../provenance/reveal-contract.js';
3
4
  import type { ImperativeEditorNavigationTarget } from '@storystick/types/editor-destination';
4
- export declare const STORYSTICK_AUTHORING_RUNTIME_CONTRACT_VERSION: 9;
5
+ export declare const STORYSTICK_AUTHORING_RUNTIME_CONTRACT_VERSION: 12;
5
6
  export declare const STORYSTICK_AUTHORING_RUNTIME_GLOBAL: "StorystickAuthoringRuntime";
6
7
  export declare const STORYSTICK_AUTHORING_RUNTIME_PATH: "/authoring-runtime/authoring-runtime.js";
7
8
  export interface PreviewAuthoringAdmission {
@@ -12,6 +13,7 @@ export interface PreviewAuthoringAdmission {
12
13
  projectId: string;
13
14
  projectShortId: string;
14
15
  contentShapeCapability: string;
16
+ contentShapeDescriptor: StudioContentShapeDescriptor;
15
17
  token: string;
16
18
  /** Project/admission-bound Convex RPC authority; never use the public SDK token. */
17
19
  rpcToken: string;
@@ -45,9 +47,10 @@ export interface PreviewAuthoringRuntimeMountOptions {
45
47
  root: ShadowRoot;
46
48
  container: HTMLElement;
47
49
  target?: PreviewAuthoringTarget;
48
- surface?: PreviewAuthoringSurface;
50
+ surface?: PreviewAuthoringSurface | null;
49
51
  header?: {
50
52
  leading: HTMLElement;
53
+ title: HTMLElement;
51
54
  trailing: HTMLElement;
52
55
  };
53
56
  assistantThreadId?: string | null;
@@ -85,5 +88,7 @@ export interface PreviewAuthoringRuntimeHandle {
85
88
  }
86
89
  export interface PreviewAuthoringRuntimeModule {
87
90
  readonly contractVersion: typeof STORYSTICK_AUTHORING_RUNTIME_CONTRACT_VERSION;
91
+ /** Fetch code only. Admission, queries and mounting still require an explicit open. */
92
+ preload(surface: PreviewAuthoringSurface): Promise<void>;
88
93
  mount(options: PreviewAuthoringRuntimeMountOptions): PreviewAuthoringRuntimeHandle;
89
94
  }
@@ -1,4 +1,5 @@
1
- export const STORYSTICK_AUTHORING_RUNTIME_CONTRACT_VERSION = 9;
1
+ import { isStudioContentShapeDescriptor } from '@storystick/types';
2
+ export const STORYSTICK_AUTHORING_RUNTIME_CONTRACT_VERSION = 12;
2
3
  export const STORYSTICK_AUTHORING_RUNTIME_GLOBAL = 'StorystickAuthoringRuntime';
3
4
  export const STORYSTICK_AUTHORING_RUNTIME_PATH = '/authoring-runtime/authoring-runtime.js';
4
5
  export function isPreviewAuthoringAdmission(value, now = Date.now()) {
@@ -21,7 +22,8 @@ export function isPreviewAuthoringAdmission(value, now = Date.now()) {
21
22
  !Number.isFinite(files.expiresAt) ||
22
23
  files.expiresAt <= now)
23
24
  return false;
24
- return (['projectId', 'projectShortId', 'contentShapeCapability', 'token', 'rpcToken'].every((key) => typeof entry[key] === 'string' && entry[key] !== '') &&
25
+ return (isStudioContentShapeDescriptor(entry.contentShapeDescriptor) &&
26
+ ['projectId', 'projectShortId', 'contentShapeCapability', 'token', 'rpcToken'].every((key) => typeof entry[key] === 'string' && entry[key] !== '') &&
25
27
  typeof entry.expiresAt === 'number' &&
26
28
  Number.isFinite(entry.expiresAt) &&
27
29
  entry.expiresAt > now);
@@ -1,2 +1,2 @@
1
1
  /** Initial browser gate; no storage writers, transport or authenticated runtime. */
2
- export { isPreviewBrowserContext } from '../identity/browser-context-gate.js';
2
+ export { isPreviewBrowserContext, hasExplicitPreviewBrowserContext, readStandalonePreviewSessionId } from '../identity/browser-context-gate.js';
@@ -1,2 +1,2 @@
1
1
  /** Initial browser gate; no storage writers, transport or authenticated runtime. */
2
- export { isPreviewBrowserContext } from '../identity/browser-context-gate.js';
2
+ export { isPreviewBrowserContext, hasExplicitPreviewBrowserContext, readStandalonePreviewSessionId } from '../identity/browser-context-gate.js';
@@ -0,0 +1,362 @@
1
+ /** Product copy shared by Studio, embedded Preview and standalone views. */
2
+ export interface PreviewCopy {
3
+ readonly title: string;
4
+ readonly body: string;
5
+ }
6
+ export declare const PREVIEW_COPY: {
7
+ readonly setup: {
8
+ readonly title: "Set up your preview";
9
+ readonly body: "Add your site’s address to see it here while you edit.";
10
+ };
11
+ readonly "invalid-url": {
12
+ readonly title: "Check the preview address";
13
+ readonly body: "The configured address isn’t valid. Add an HTTP or HTTPS site address in Preview and origins.";
14
+ };
15
+ readonly "origins-missing": {
16
+ readonly title: "Finish preview setup";
17
+ readonly body: "Allow your site to connect to Storystick in Preview and origins.";
18
+ };
19
+ readonly "origin-forbidden": {
20
+ readonly title: "This site isn’t allowed";
21
+ readonly body: "This site isn’t included in the project’s allowed preview origins.";
22
+ };
23
+ readonly "project-mismatch": {
24
+ readonly title: "This site uses another project";
25
+ readonly body: "Check the preview address and the Storystick project connected to this site.";
26
+ };
27
+ readonly "document-empty": {
28
+ readonly title: "Open a document";
29
+ readonly body: "Its preview will appear here.";
30
+ };
31
+ readonly "document-context": {
32
+ readonly title: "Preview this content on a page";
33
+ readonly body: "This document has no preview of its own. Open it from a page that uses it.";
34
+ };
35
+ readonly "route-unmapped": {
36
+ readonly title: "Page without a document";
37
+ readonly body: "This page isn’t linked to a Storystick document. The editor is still on {document}.";
38
+ };
39
+ readonly "another-page": {
40
+ readonly title: "Preview shows another page";
41
+ readonly body: "You’re editing {document}. The preview shows {page}.";
42
+ };
43
+ readonly preparing: {
44
+ readonly title: "Preparing preview";
45
+ readonly body: "Your site will appear here when it’s ready.";
46
+ };
47
+ readonly "page-loading": {
48
+ readonly title: "Loading your site";
49
+ readonly body: "Waiting for the page to respond.";
50
+ };
51
+ readonly connecting: {
52
+ readonly title: "Connecting preview";
53
+ readonly body: "Connecting this site to Studio.";
54
+ };
55
+ readonly "workspace-creating": {
56
+ readonly title: "Starting working preview";
57
+ readonly body: "Preparing the environment for this working version.";
58
+ };
59
+ readonly "workspace-restoring": {
60
+ readonly title: "Resuming working preview";
61
+ readonly body: "Restoring the environment and its saved changes.";
62
+ };
63
+ readonly "workspace-installing": {
64
+ readonly title: "Preparing the project";
65
+ readonly body: "Installing the project’s dependencies. The first start can take longer.";
66
+ };
67
+ readonly "workspace-checking": {
68
+ readonly title: "Checking the project";
69
+ readonly body: "Checking this version before starting the site.";
70
+ };
71
+ readonly "workspace-launching": {
72
+ readonly title: "Starting the site";
73
+ readonly body: "Starting the working preview server.";
74
+ };
75
+ readonly "retained-loading": {
76
+ readonly title: "Loading {page}";
77
+ readonly body: "The previous page is still shown.";
78
+ };
79
+ readonly updating: {
80
+ readonly title: "Updating preview";
81
+ readonly body: "Waiting for the updated page.";
82
+ };
83
+ readonly "taking-longer": {
84
+ readonly title: "Preview is taking longer";
85
+ readonly body: "We’re still waiting for the requested page.";
86
+ };
87
+ readonly reconnect: {
88
+ readonly title: "Reconnect your preview";
89
+ readonly body: "This preview connection is no longer valid. Reconnect to continue.";
90
+ };
91
+ readonly "deployment-changed": {
92
+ readonly title: "The site has changed";
93
+ readonly body: "Reconnect preview to use the current site deployment.";
94
+ };
95
+ readonly "open-from-studio": {
96
+ readonly title: "Open preview from Studio";
97
+ readonly body: "Start a new preview from Studio to connect this page.";
98
+ };
99
+ readonly "connection-interrupted": {
100
+ readonly title: "Preview connection interrupted";
101
+ readonly body: "The connection couldn’t be restored. Reconnect preview to continue.";
102
+ };
103
+ readonly "access-unavailable": {
104
+ readonly title: "Preview access unavailable";
105
+ readonly body: "This preview is no longer available with your current access. Return to Studio to open an available view.";
106
+ };
107
+ readonly "view-unavailable": {
108
+ readonly title: "This view is no longer available";
109
+ readonly body: "Choose an available version in Studio, then open preview again.";
110
+ };
111
+ readonly ended: {
112
+ readonly title: "Preview ended";
113
+ readonly body: "This preview was closed. Return to Studio to start another.";
114
+ };
115
+ readonly "exit-incomplete": {
116
+ readonly title: "Preview hasn’t fully closed";
117
+ readonly body: "The shared preview ended, but this tab couldn’t leave preview mode.";
118
+ };
119
+ readonly "admission-superseded": {
120
+ readonly title: "Preview changed in another view";
121
+ readonly body: "Reconnect to follow the current preview.";
122
+ };
123
+ readonly "connection-mismatch": {
124
+ readonly title: "Preview couldn’t connect";
125
+ readonly body: "The site and Studio couldn’t establish the same preview session.";
126
+ };
127
+ readonly "integration-update": {
128
+ readonly title: "Preview integration needs an update";
129
+ readonly body: "A developer needs to update the site’s preview integration before Studio can connect.";
130
+ };
131
+ readonly "content-unavailable": {
132
+ readonly title: "Preview content unavailable";
133
+ readonly body: "The content service couldn’t answer this page’s request.";
134
+ };
135
+ readonly "render-failed": {
136
+ readonly title: "This page couldn’t load";
137
+ readonly body: "The site couldn’t render this page. You can keep editing or open another page.";
138
+ };
139
+ readonly "update-failed": {
140
+ readonly title: "Preview couldn’t update";
141
+ readonly body: "The requested page wasn’t confirmed. Try opening it again.";
142
+ };
143
+ readonly "scope-mismatch": {
144
+ readonly title: "Preview shows another version";
145
+ readonly body: "The site hasn’t confirmed the version selected in Studio.";
146
+ };
147
+ readonly "selection-superseded": {
148
+ readonly title: "The version changed";
149
+ readonly body: "Your selection was replaced before the preview finished updating.";
150
+ };
151
+ readonly "version-unavailable": {
152
+ readonly title: "This version couldn’t open";
153
+ readonly body: "Choose the version again, or return to another available version.";
154
+ };
155
+ readonly "route-lookup-failed": {
156
+ readonly title: "Page connection unavailable";
157
+ readonly body: "Studio couldn’t identify the document for this page.";
158
+ };
159
+ readonly "sync-failed": {
160
+ readonly title: "This page couldn’t be shown";
161
+ readonly body: "Preview didn’t confirm the document you requested.";
162
+ };
163
+ readonly unavailable: {
164
+ readonly title: "Preview is unavailable";
165
+ readonly body: "Studio couldn’t prepare this preview. Try again, or share the diagnostic with your project administrator.";
166
+ };
167
+ readonly busy: {
168
+ readonly title: "Preview is temporarily busy";
169
+ readonly body: "The service couldn’t accept this request yet.";
170
+ };
171
+ readonly "visual-connecting": {
172
+ readonly title: "Connecting visual editing";
173
+ readonly body: "";
174
+ };
175
+ readonly "visual-limited": {
176
+ readonly title: "Visual editing is limited";
177
+ readonly body: "Some elements can’t be selected on this page. You can still edit their content in Studio.";
178
+ };
179
+ readonly "visual-update": {
180
+ readonly title: "Visual editing needs an update";
181
+ readonly body: "The page is available, but a developer needs to update its editing integration.";
182
+ };
183
+ readonly "visual-partial": {
184
+ readonly title: "Some elements aren’t selectable";
185
+ readonly body: "";
186
+ };
187
+ readonly "visual-empty": {
188
+ readonly title: "No editable elements on this page";
189
+ readonly body: "";
190
+ };
191
+ readonly "visual-unavailable": {
192
+ readonly title: "Page selection unavailable";
193
+ readonly body: "The page’s editing controls couldn’t be confirmed. You can continue editing in Studio.";
194
+ };
195
+ readonly "minimap-unavailable": {
196
+ readonly title: "Minimap unavailable for this page";
197
+ readonly body: "Open Preview to view this page without the minimap.";
198
+ };
199
+ readonly "marker-diagnostic": {
200
+ readonly title: "Editing markers need attention";
201
+ readonly body: "";
202
+ };
203
+ readonly "workspace-unavailable": {
204
+ readonly title: "Working preview unavailable";
205
+ readonly body: "This working version isn’t available right now. Open it again, or use the current site.";
206
+ };
207
+ readonly "workspace-configuration": {
208
+ readonly title: "Working preview needs setup";
209
+ readonly body: "A project administrator needs to complete this environment’s setup before it can start.";
210
+ };
211
+ readonly "workspace-unconfirmed": {
212
+ readonly title: "Working preview status is unconfirmed";
213
+ readonly body: "The environment hasn’t confirmed the last operation. A project administrator can check its status before another attempt.";
214
+ };
215
+ readonly "workspace-stopped": {
216
+ readonly title: "Working preview is stopped";
217
+ readonly body: "Resume this working version, or use the current site.";
218
+ };
219
+ readonly "workspace-start-failed": {
220
+ readonly title: "Working preview couldn’t start";
221
+ readonly body: "The environment couldn’t start. Try again, or use the current site.";
222
+ };
223
+ readonly "workspace-not-prepared": {
224
+ readonly title: "Working preview isn’t set up";
225
+ readonly body: "A project administrator needs to prepare this working version before it can start.";
226
+ };
227
+ readonly "workspace-forbidden": {
228
+ readonly title: "Working preview needs project access";
229
+ readonly body: "A project administrator needs to start this working version.";
230
+ };
231
+ readonly "workspace-limit": {
232
+ readonly title: "Working preview limit reached";
233
+ readonly body: "This working preview has reached its usage limit. A project administrator can review it.";
234
+ };
235
+ readonly "workspace-near-limit": {
236
+ readonly title: "Working preview is nearing its limit";
237
+ readonly body: "";
238
+ };
239
+ readonly "workspace-recovery": {
240
+ readonly title: "Working files need recovery";
241
+ readonly body: "Some file changes need to be recovered before this environment can restart.";
242
+ };
243
+ readonly "workspace-switch-failed": {
244
+ readonly title: "Environment couldn’t change";
245
+ readonly body: "The requested environment couldn’t be selected.";
246
+ };
247
+ readonly "workspace-stop-failed": {
248
+ readonly title: "Working preview couldn’t stop";
249
+ readonly body: "The environment didn’t confirm that it stopped.";
250
+ };
251
+ readonly "workspace-stopped-recovery": {
252
+ readonly title: "Preview stopped, files need recovery";
253
+ readonly body: "Some file changes still need to be recovered before this environment is used again.";
254
+ };
255
+ readonly "workspace-release": {
256
+ readonly title: "Select this working version’s content";
257
+ readonly body: "This environment belongs to {release}. Select it to preview its content.";
258
+ };
259
+ readonly "workspace-selection-failed": {
260
+ readonly title: "Working version couldn’t be selected";
261
+ readonly body: "The requested content version couldn’t be applied.";
262
+ };
263
+ readonly "field-hidden": {
264
+ readonly title: "This field isn’t visible here";
265
+ readonly body: "It’s on this page, but isn’t currently visible.";
266
+ };
267
+ readonly "field-absent": {
268
+ readonly title: "This field isn’t on this page";
269
+ readonly body: "Its content is available in the editor.";
270
+ };
271
+ readonly "field-pending": {
272
+ readonly title: "The page isn’t ready to locate this field";
273
+ readonly body: "";
274
+ };
275
+ readonly "field-missing": {
276
+ readonly title: "This content couldn’t be located";
277
+ readonly body: "It may have changed in this version. Open its document to continue.";
278
+ };
279
+ readonly "field-ambiguous": {
280
+ readonly title: "Choose an editing version";
281
+ readonly body: "This content appears in more than one version.";
282
+ };
283
+ readonly "field-closest": {
284
+ readonly title: "Showing the containing section";
285
+ readonly body: "The exact field couldn’t be located.";
286
+ };
287
+ readonly "field-opening": {
288
+ readonly title: "Opening the selected content";
289
+ readonly body: "It will open when the editor is ready.";
290
+ };
291
+ readonly "field-open-failed": {
292
+ readonly title: "This content couldn’t open";
293
+ readonly body: "Try opening its document again.";
294
+ };
295
+ readonly "field-multiple": {
296
+ readonly title: "Multiple preview targets";
297
+ readonly body: "";
298
+ };
299
+ readonly "release-nonmember": {
300
+ readonly title: "This page uses Main";
301
+ readonly body: "It isn’t included in {release}.";
302
+ };
303
+ readonly "release-follows-main": {
304
+ readonly title: "Preview now follows Main";
305
+ readonly body: "{release} was published.";
306
+ };
307
+ readonly "release-archived": {
308
+ readonly title: "Preview now follows Main";
309
+ readonly body: "{release} was archived.";
310
+ };
311
+ readonly "release-unavailable": {
312
+ readonly title: "This release view is unavailable";
313
+ readonly body: "Preview is showing Main for this page.";
314
+ };
315
+ readonly "release-readonly": {
316
+ readonly title: "This version can’t be edited";
317
+ readonly body: "Choose an editable version to continue.";
318
+ };
319
+ readonly "opening-invalid": {
320
+ readonly title: "This preview link is unavailable";
321
+ readonly body: "Open a new preview from Studio.";
322
+ };
323
+ readonly "opening-failed": {
324
+ readonly title: "Preview couldn’t open";
325
+ readonly body: "The connection couldn’t be prepared. Try again, or return to Studio.";
326
+ };
327
+ readonly "editor-unavailable": {
328
+ readonly title: "Editor unavailable";
329
+ readonly body: "The editor couldn’t connect. Try again, or open this content in Studio.";
330
+ };
331
+ readonly "editing-forbidden": {
332
+ readonly title: "Editing isn’t available with your access";
333
+ readonly body: "";
334
+ };
335
+ readonly "element-empty": {
336
+ readonly title: "Select an element on the page";
337
+ readonly body: "Its content will open here.";
338
+ };
339
+ readonly "runtime-unavailable": {
340
+ readonly title: "Preview controls couldn’t load";
341
+ readonly body: "Reload this preview to try connecting again.";
342
+ };
343
+ readonly "diagnostic-copied": {
344
+ readonly title: "Diagnostic copied";
345
+ readonly body: "";
346
+ };
347
+ readonly "diagnostic-failed": {
348
+ readonly title: "Diagnostic couldn’t be copied";
349
+ readonly body: "Retry, or select the diagnostic text.";
350
+ };
351
+ readonly reconnecting: {
352
+ readonly title: "Reconnecting preview";
353
+ readonly body: "We’re trying to restore the connection.";
354
+ };
355
+ readonly "setup-readonly": {
356
+ readonly title: "Preview isn’t set up yet";
357
+ readonly body: "A project administrator can add the site address. You can continue working in Studio.";
358
+ };
359
+ };
360
+ export type PreviewCopyKey = keyof typeof PREVIEW_COPY;
361
+ /** Names and labels come from the already admitted presentation context. */
362
+ export declare function previewCopy(key: PreviewCopyKey, params?: Readonly<Record<string, string>>): PreviewCopy;
@@ -0,0 +1,96 @@
1
+ export const PREVIEW_COPY = {
2
+ "setup": { "title": "Set up your preview", "body": "Add your site’s address to see it here while you edit." },
3
+ "invalid-url": { "title": "Check the preview address", "body": "The configured address isn’t valid. Add an HTTP or HTTPS site address in Preview and origins." },
4
+ "origins-missing": { "title": "Finish preview setup", "body": "Allow your site to connect to Storystick in Preview and origins." },
5
+ "origin-forbidden": { "title": "This site isn’t allowed", "body": "This site isn’t included in the project’s allowed preview origins." },
6
+ "project-mismatch": { "title": "This site uses another project", "body": "Check the preview address and the Storystick project connected to this site." },
7
+ "document-empty": { "title": "Open a document", "body": "Its preview will appear here." },
8
+ "document-context": { "title": "Preview this content on a page", "body": "This document has no preview of its own. Open it from a page that uses it." },
9
+ "route-unmapped": { "title": "Page without a document", "body": "This page isn’t linked to a Storystick document. The editor is still on {document}." },
10
+ "another-page": { "title": "Preview shows another page", "body": "You’re editing {document}. The preview shows {page}." },
11
+ "preparing": { "title": "Preparing preview", "body": "Your site will appear here when it’s ready." },
12
+ "page-loading": { "title": "Loading your site", "body": "Waiting for the page to respond." },
13
+ "connecting": { "title": "Connecting preview", "body": "Connecting this site to Studio." },
14
+ "workspace-creating": { "title": "Starting working preview", "body": "Preparing the environment for this working version." },
15
+ "workspace-restoring": { "title": "Resuming working preview", "body": "Restoring the environment and its saved changes." },
16
+ "workspace-installing": { "title": "Preparing the project", "body": "Installing the project’s dependencies. The first start can take longer." },
17
+ "workspace-checking": { "title": "Checking the project", "body": "Checking this version before starting the site." },
18
+ "workspace-launching": { "title": "Starting the site", "body": "Starting the working preview server." },
19
+ "retained-loading": { "title": "Loading {page}", "body": "The previous page is still shown." },
20
+ "updating": { "title": "Updating preview", "body": "Waiting for the updated page." },
21
+ "taking-longer": { "title": "Preview is taking longer", "body": "We’re still waiting for the requested page." },
22
+ "reconnect": { "title": "Reconnect your preview", "body": "This preview connection is no longer valid. Reconnect to continue." },
23
+ "deployment-changed": { "title": "The site has changed", "body": "Reconnect preview to use the current site deployment." },
24
+ "open-from-studio": { "title": "Open preview from Studio", "body": "Start a new preview from Studio to connect this page." },
25
+ "connection-interrupted": { "title": "Preview connection interrupted", "body": "The connection couldn’t be restored. Reconnect preview to continue." },
26
+ "access-unavailable": { "title": "Preview access unavailable", "body": "This preview is no longer available with your current access. Return to Studio to open an available view." },
27
+ "view-unavailable": { "title": "This view is no longer available", "body": "Choose an available version in Studio, then open preview again." },
28
+ "ended": { "title": "Preview ended", "body": "This preview was closed. Return to Studio to start another." },
29
+ "exit-incomplete": { "title": "Preview hasn’t fully closed", "body": "The shared preview ended, but this tab couldn’t leave preview mode." },
30
+ "admission-superseded": { "title": "Preview changed in another view", "body": "Reconnect to follow the current preview." },
31
+ "connection-mismatch": { "title": "Preview couldn’t connect", "body": "The site and Studio couldn’t establish the same preview session." },
32
+ "integration-update": { "title": "Preview integration needs an update", "body": "A developer needs to update the site’s preview integration before Studio can connect." },
33
+ "content-unavailable": { "title": "Preview content unavailable", "body": "The content service couldn’t answer this page’s request." },
34
+ "render-failed": { "title": "This page couldn’t load", "body": "The site couldn’t render this page. You can keep editing or open another page." },
35
+ "update-failed": { "title": "Preview couldn’t update", "body": "The requested page wasn’t confirmed. Try opening it again." },
36
+ "scope-mismatch": { "title": "Preview shows another version", "body": "The site hasn’t confirmed the version selected in Studio." },
37
+ "selection-superseded": { "title": "The version changed", "body": "Your selection was replaced before the preview finished updating." },
38
+ "version-unavailable": { "title": "This version couldn’t open", "body": "Choose the version again, or return to another available version." },
39
+ "route-lookup-failed": { "title": "Page connection unavailable", "body": "Studio couldn’t identify the document for this page." },
40
+ "sync-failed": { "title": "This page couldn’t be shown", "body": "Preview didn’t confirm the document you requested." },
41
+ "unavailable": { "title": "Preview is unavailable", "body": "Studio couldn’t prepare this preview. Try again, or share the diagnostic with your project administrator." },
42
+ "busy": { "title": "Preview is temporarily busy", "body": "The service couldn’t accept this request yet." },
43
+ "visual-connecting": { "title": "Connecting visual editing", "body": "" },
44
+ "visual-limited": { "title": "Visual editing is limited", "body": "Some elements can’t be selected on this page. You can still edit their content in Studio." },
45
+ "visual-update": { "title": "Visual editing needs an update", "body": "The page is available, but a developer needs to update its editing integration." },
46
+ "visual-partial": { "title": "Some elements aren’t selectable", "body": "" },
47
+ "visual-empty": { "title": "No editable elements on this page", "body": "" },
48
+ "visual-unavailable": { "title": "Page selection unavailable", "body": "The page’s editing controls couldn’t be confirmed. You can continue editing in Studio." },
49
+ "minimap-unavailable": { "title": "Minimap unavailable for this page", "body": "Open Preview to view this page without the minimap." },
50
+ "marker-diagnostic": { "title": "Editing markers need attention", "body": "" },
51
+ "workspace-unavailable": { "title": "Working preview unavailable", "body": "This working version isn’t available right now. Open it again, or use the current site." },
52
+ "workspace-configuration": { "title": "Working preview needs setup", "body": "A project administrator needs to complete this environment’s setup before it can start." },
53
+ "workspace-unconfirmed": { "title": "Working preview status is unconfirmed", "body": "The environment hasn’t confirmed the last operation. A project administrator can check its status before another attempt." },
54
+ "workspace-stopped": { "title": "Working preview is stopped", "body": "Resume this working version, or use the current site." },
55
+ "workspace-start-failed": { "title": "Working preview couldn’t start", "body": "The environment couldn’t start. Try again, or use the current site." },
56
+ "workspace-not-prepared": { "title": "Working preview isn’t set up", "body": "A project administrator needs to prepare this working version before it can start." },
57
+ "workspace-forbidden": { "title": "Working preview needs project access", "body": "A project administrator needs to start this working version." },
58
+ "workspace-limit": { "title": "Working preview limit reached", "body": "This working preview has reached its usage limit. A project administrator can review it." },
59
+ "workspace-near-limit": { "title": "Working preview is nearing its limit", "body": "" },
60
+ "workspace-recovery": { "title": "Working files need recovery", "body": "Some file changes need to be recovered before this environment can restart." },
61
+ "workspace-switch-failed": { "title": "Environment couldn’t change", "body": "The requested environment couldn’t be selected." },
62
+ "workspace-stop-failed": { "title": "Working preview couldn’t stop", "body": "The environment didn’t confirm that it stopped." },
63
+ "workspace-stopped-recovery": { "title": "Preview stopped, files need recovery", "body": "Some file changes still need to be recovered before this environment is used again." },
64
+ "workspace-release": { "title": "Select this working version’s content", "body": "This environment belongs to {release}. Select it to preview its content." },
65
+ "workspace-selection-failed": { "title": "Working version couldn’t be selected", "body": "The requested content version couldn’t be applied." },
66
+ "field-hidden": { "title": "This field isn’t visible here", "body": "It’s on this page, but isn’t currently visible." },
67
+ "field-absent": { "title": "This field isn’t on this page", "body": "Its content is available in the editor." },
68
+ "field-pending": { "title": "The page isn’t ready to locate this field", "body": "" },
69
+ "field-missing": { "title": "This content couldn’t be located", "body": "It may have changed in this version. Open its document to continue." },
70
+ "field-ambiguous": { "title": "Choose an editing version", "body": "This content appears in more than one version." },
71
+ "field-closest": { "title": "Showing the containing section", "body": "The exact field couldn’t be located." },
72
+ "field-opening": { "title": "Opening the selected content", "body": "It will open when the editor is ready." },
73
+ "field-open-failed": { "title": "This content couldn’t open", "body": "Try opening its document again." },
74
+ "field-multiple": { "title": "Multiple preview targets", "body": "" },
75
+ "release-nonmember": { "title": "This page uses Main", "body": "It isn’t included in {release}." },
76
+ "release-follows-main": { "title": "Preview now follows Main", "body": "{release} was published." },
77
+ "release-archived": { "title": "Preview now follows Main", "body": "{release} was archived." },
78
+ "release-unavailable": { "title": "This release view is unavailable", "body": "Preview is showing Main for this page." },
79
+ "release-readonly": { "title": "This version can’t be edited", "body": "Choose an editable version to continue." },
80
+ "opening-invalid": { "title": "This preview link is unavailable", "body": "Open a new preview from Studio." },
81
+ "opening-failed": { "title": "Preview couldn’t open", "body": "The connection couldn’t be prepared. Try again, or return to Studio." },
82
+ "editor-unavailable": { "title": "Editor unavailable", "body": "The editor couldn’t connect. Try again, or open this content in Studio." },
83
+ "editing-forbidden": { "title": "Editing isn’t available with your access", "body": "" },
84
+ "element-empty": { "title": "Select an element on the page", "body": "Its content will open here." },
85
+ "runtime-unavailable": { "title": "Preview controls couldn’t load", "body": "Reload this preview to try connecting again." },
86
+ "diagnostic-copied": { "title": "Diagnostic copied", "body": "" },
87
+ "diagnostic-failed": { "title": "Diagnostic couldn’t be copied", "body": "Retry, or select the diagnostic text." },
88
+ "reconnecting": { "title": "Reconnecting preview", "body": "We’re trying to restore the connection." },
89
+ "setup-readonly": { "title": "Preview isn’t set up yet", "body": "A project administrator can add the site address. You can continue working in Studio." },
90
+ };
91
+ /** Names and labels come from the already admitted presentation context. */
92
+ export function previewCopy(key, params = {}) {
93
+ const copy = PREVIEW_COPY[key];
94
+ const format = (text) => text.replace(/\{(\w+)\}/g, (match, name) => params[name] ?? match);
95
+ return { title: format(copy.title), body: format(copy.body) };
96
+ }
@@ -0,0 +1,6 @@
1
+ /** Diagnostics intentionally exclude exception messages, arbitrary payloads and credentials. */
2
+ export declare function safePreviewCode(value: unknown): string;
3
+ export declare function safePreviewOrigin(value: unknown): string | null;
4
+ export declare function previewDiagnostic(input: unknown): string;
5
+ /** Re-sanitize at the rendering/copy boundary even when a caller supplies its own report. */
6
+ export declare function sanitizePreviewDiagnostic(payload: string): string;
@@ -0,0 +1,64 @@
1
+ import { PREVIEW_FEEDBACK, normalizePreviewCode } from './preview-feedback.js';
2
+ /** Diagnostics intentionally exclude exception messages, arbitrary payloads and credentials. */
3
+ export function safePreviewCode(value) {
4
+ if (typeof value !== 'string')
5
+ return 'UNKNOWN';
6
+ const code = normalizePreviewCode(value);
7
+ if (Object.hasOwn(PREVIEW_FEEDBACK, code))
8
+ return code;
9
+ if (/^(?:PROJECT_WORKSPACE_[A-Z_]{1,80}|PREVIEW_(?:GRANT_ACTIVATION|GRANT_ACCESS|AUTHORING_ADMISSION)_[A-Z_]{1,40})$/.test(code))
10
+ return code;
11
+ return 'UNKNOWN';
12
+ }
13
+ export function safePreviewOrigin(value) {
14
+ if (typeof value !== 'string')
15
+ return null;
16
+ try {
17
+ const url = new URL(value);
18
+ return url.protocol === 'https:' || url.protocol === 'http:' ? url.origin : null;
19
+ }
20
+ catch {
21
+ return null;
22
+ }
23
+ }
24
+ const STATES = new Set(['idle', 'loading', 'ready', 'error', 'empty', 'dormant', 'authenticated', 'pending', 'unauthenticated', 'device', 'navigation', 'visible', 'hidden', 'unavailable', 'iframe', 'loaded']);
25
+ const OPERATIONS = new Set(['connect', 'reconnect', 'navigate', 'reload', 'start', 'resume', 'stop', 'select-version', 'exit', 'activate', 'authoring']);
26
+ const PHASES = new Set(['dormant', 'preflight', 'booting', 'auth', 'loading', 'connecting', 'render', 'proof', 'paint', 'ack', 'ready', 'failed', 'authenticating', 'transitioning', 'unconfirmed', 'blocked', 'error']);
27
+ const STATE_KEYS = new Set(['stageState', 'authStatus', 'mode', 'frame', 'stage', 'status', 'iframeLoadStatus']);
28
+ const TIMING_KEYS = new Set(['iframe_load_ms', 'auth_request_ms', 'auth_response_ms', 'iframe_visible_ms']);
29
+ const COUNT_KEYS = new Set(['attempt', 'generation', 'desiredGeneration', 'presentedGeneration', 'reloadCount']);
30
+ export function previewDiagnostic(input) {
31
+ const report = { format: 'storystick-preview-v1' };
32
+ if (typeof input !== 'object' || input === null || Array.isArray(input))
33
+ return JSON.stringify(report, null, 2);
34
+ for (const [key, value] of Object.entries(input)) {
35
+ if (key === 'code' || key === 'internalCause')
36
+ report[key] = value === null ? null : safePreviewCode(value);
37
+ else if (key === 'reference' && typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,95}$/.test(value))
38
+ report[key] = value;
39
+ else if (key === 'operation' && typeof value === 'string' && OPERATIONS.has(value))
40
+ report[key] = value;
41
+ else if (key === 'phase' && typeof value === 'string' && PHASES.has(value))
42
+ report[key] = value;
43
+ else if (key === 'runtimeError' && value !== null && typeof value === 'object')
44
+ report.code = safePreviewCode(value.code);
45
+ else if (key === 'origin' || key === 'previewUrl')
46
+ report[key] = safePreviewOrigin(value);
47
+ else if (STATE_KEYS.has(key) && typeof value === 'string' && STATES.has(value))
48
+ report[key] = value;
49
+ else if (TIMING_KEYS.has(key) && (value === null || typeof value === 'number' && Number.isFinite(value) && value >= 0))
50
+ report[key] = value;
51
+ else if (COUNT_KEYS.has(key) && typeof value === 'number' && Number.isSafeInteger(value) && value >= 0)
52
+ report[key] = value;
53
+ }
54
+ return JSON.stringify(report, null, 2);
55
+ }
56
+ /** Re-sanitize at the rendering/copy boundary even when a caller supplies its own report. */
57
+ export function sanitizePreviewDiagnostic(payload) {
58
+ try {
59
+ return previewDiagnostic(JSON.parse(payload));
60
+ }
61
+ catch {
62
+ return previewDiagnostic(null);
63
+ }
64
+ }