tempo-sdk 0.0.19 → 0.0.22

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.
@@ -1,9 +1,9 @@
1
1
  import * as react_jsx_runtime from 'react/jsx-runtime';
2
2
  import { ReactNode, ComponentType } from 'react';
3
- import { d as TempoStoryboard } from '../page-xi1aI5a7.js';
3
+ import { d as TempoStoryboard } from '../page-BUbHO0BI.js';
4
4
 
5
5
  declare function getCanvasStoryboardRenderId(canvasPath: string, storyboardId: string): string;
6
- declare function Canvas({ children, name, path, backgroundColor, defaultViewport, }: {
6
+ declare function Canvas({ children, name, path, backgroundColor, defaultViewport, ...sourceAnnotations }: {
7
7
  children?: ReactNode;
8
8
  name: string;
9
9
  path?: string;
@@ -13,14 +13,38 @@ declare function Canvas({ children, name, path, backgroundColor, defaultViewport
13
13
  y: number;
14
14
  zoom: number;
15
15
  };
16
- }): react_jsx_runtime.JSX.Element;
16
+ } & Record<`data-tempo-${string}`, unknown>): react_jsx_runtime.JSX.Element;
17
17
  declare function CanvasContext({ children, path, }: {
18
18
  children?: ReactNode;
19
19
  path: string;
20
20
  }): react_jsx_runtime.JSX.Element;
21
21
 
22
- declare function CanvasHost({ children, activeStoryboardIds, isStoryboardActive, }: {
22
+ type CanvasModule = {
23
+ default: ComponentType;
24
+ };
25
+ declare function CanvasImportBoundary({ canvasPath, load, }: {
26
+ canvasPath: string;
27
+ load: () => Promise<CanvasModule>;
28
+ }): react_jsx_runtime.JSX.Element;
29
+
30
+ /**
31
+ * Live document title of every component-host page. AI agents connected over
32
+ * CDP identify Tempo-internal frames by the leading "INTERNAL" marker and
33
+ * leave them alone. Only the runtime title changes: the static
34
+ * `<title>tempo-host</title>` in the harness HTML must stay untouched because
35
+ * tempo-devserver's HTTP host detector matches on that exact body text.
36
+ */
37
+ declare const CANVAS_HOST_DOCUMENT_TITLE = "INTERNAL tempo-host \u2014 Tempo component host, do not interact";
38
+ type CanvasHostModule = {
39
+ canvasPath: string;
40
+ load: () => Promise<CanvasModule>;
41
+ };
42
+ declare class CanvasHostContractError extends Error {
43
+ name: string;
44
+ }
45
+ declare function CanvasHost({ children, canvasModules, activeStoryboardIds, isStoryboardActive, }: {
23
46
  children?: ReactNode;
47
+ canvasModules?: readonly CanvasHostModule[];
24
48
  activeStoryboardIds?: ReadonlySet<string> | readonly string[];
25
49
  isStoryboardActive?: (storyboardId: string) => boolean;
26
50
  }): react_jsx_runtime.JSX.Element;
@@ -33,11 +57,15 @@ type CanvasHostCaptureResult = {
33
57
  };
34
58
  timing?: Record<string, number>;
35
59
  };
60
+ type CanvasHostWatchResumeOptions = {
61
+ flush?: "always" | "if-dirty" | "never";
62
+ triggers?: readonly "viewport-capture"[];
63
+ };
36
64
  type CanvasHostWatch = {
37
65
  stop(): void | Promise<void>;
38
66
  pause?(): void;
39
- resume?(): void;
40
- setPaused?(paused: boolean): void;
67
+ resume?(options?: CanvasHostWatchResumeOptions): void;
68
+ setPaused?(paused: boolean, options?: CanvasHostWatchResumeOptions): void;
41
69
  };
42
70
  type CanvasHostRuntime = {
43
71
  captureSelector(selector: string, options?: {
@@ -96,25 +124,20 @@ declare const buildRenderContentSelector: (renderId: string) => string;
96
124
  declare const buildRenderContentFiberSelector: (renderId: string) => string;
97
125
  declare function stripRenderContentWrapperAttributes<T>(capture: T, renderId: string): T;
98
126
  declare function stripRenderContentWrapperFromCombinedCapture<T>(capture: T, renderId: string): T;
99
- declare function captureStoryboardImage(renderId: string, options?: Parameters<CanvasHostRuntime["captureSelector"]>[1]): Promise<CanvasHostCaptureResult | null>;
127
+ declare function captureStoryboardImage(renderId: string, options?: Parameters<CanvasHostRuntime["captureSelector"]>[1] & {
128
+ /** Capture a single descendant of the storyboard's render root instead of
129
+ * the root — composed as `<renderRoot> <childSelector>`, so it can only
130
+ * ever match inside this storyboard's slot. */
131
+ childSelector?: string;
132
+ }): Promise<CanvasHostCaptureResult | null>;
100
133
  declare function captureStoryboardHtml(renderId: string, options?: {
101
134
  timeout?: number;
102
135
  }): Promise<unknown | null>;
103
- declare function captureStoryboardStaticHtml(renderId: string, options?: {
104
- timeout?: number;
105
- }): Promise<unknown | null>;
106
136
  declare function captureStoryboardCombined(renderId: string, options?: {
107
137
  fiberSelector?: string;
108
138
  fiberTags?: unknown[];
109
139
  timeout?: number;
110
140
  }): Promise<unknown | null>;
111
- declare function watchStoryboardHtml(renderId: string, options: {
112
- onUpdate(capture: unknown): void;
113
- onError?(error: Error): void;
114
- debounceDelay?: number;
115
- maxWait?: number;
116
- timeout?: number;
117
- }): Promise<CanvasHostWatch>;
118
141
  declare function watchStoryboardCombined(renderId: string, options: {
119
142
  onUpdate(capture: unknown): void;
120
143
  onError?(error: Error): void;
@@ -126,6 +149,79 @@ declare function watchStoryboardCombined(renderId: string, options: {
126
149
  knownSourceVersion?: unknown;
127
150
  }): Promise<CanvasHostWatch>;
128
151
 
152
+ /**
153
+ * The CanvasHost protocol capability this SDK build implements.
154
+ *
155
+ * The authoritative compatibility gate is devserver-side: tempo-devserver
156
+ * resolves the installed tempo-sdk package version BEFORE generating a host
157
+ * document and refuses generation with a typed, actionable error when the
158
+ * installed SDK predates the generated contract. That check cannot be an
159
+ * in-host import assertion, because an SDK old enough to matter does not
160
+ * export this constant — the named import itself would throw before any
161
+ * assertion ran.
162
+ *
163
+ * This constant exists as defense-in-depth for FUTURE protocol bumps, once
164
+ * every supported SDK version is known to export it.
165
+ */
166
+ declare const canvasHostCapability: {
167
+ readonly protocolVersion: 1;
168
+ readonly supportsModules: true;
169
+ };
170
+
171
+ /**
172
+ * In-document recovery feed shared between the SDK runtime and the
173
+ * devserver-generated CanvasHost recovery adapter.
174
+ *
175
+ * The generated host document contains two cooperating parties that must not
176
+ * import each other:
177
+ *
178
+ * - the SDK (problem tracking), which observes the product fact "a module
179
+ * evaluation failed in this document"; and
180
+ * - the devserver-generated Vite recovery adapter, which owns
181
+ * `import.meta.hot` and decides when a failed host document may reload.
182
+ *
183
+ * The feed is a tiny window-global event bus with create-if-absent semantics
184
+ * on both sides, so evaluation order between the SDK and the generated
185
+ * adapter never matters. It carries product facts about failed module loads —
186
+ * never Vite contexts, cycle numbers, owner success, or reload commands.
187
+ * Which canvases show which problems is the SDK problem tracker's job; the
188
+ * adapter's repair (a document reload) is document-scoped and needs no owner
189
+ * identity.
190
+ */
191
+ type CanvasHostRecoveryEvent = {
192
+ /** "module-load-failure": a module load or evaluation failed in a way Vite
193
+ * cannot converge in place (evaluation threw and cleared the Fast Refresh
194
+ * accepts, or a canvas's cold-start import rejected) — the adapter reloads
195
+ * on the first later HMR cycle. "module-update-dropped": Vite dropped a
196
+ * hot update whose module fetch failed — the adapter reloads only if a
197
+ * later cycle does not retry the path (a retry lets Vite own the outcome). */
198
+ type: "module-load-failure" | "module-update-dropped";
199
+ /** Failed module path. Diagnostic for load failures; for dropped updates it
200
+ * must be the exact accepted-module path Vite reported so the adapter can
201
+ * match it against later update payloads. */
202
+ path: string;
203
+ message?: string;
204
+ };
205
+ type CanvasHostRecoveryFeed = {
206
+ publish(event: CanvasHostRecoveryEvent): void;
207
+ subscribe(listener: (event: CanvasHostRecoveryEvent) => void): () => void;
208
+ };
209
+ /**
210
+ * Returns the document's shared recovery feed, creating it when this is the
211
+ * first party to ask. The generated adapter bootstraps an identically-shaped
212
+ * feed, so whichever side evaluates first wins and the other reuses it.
213
+ */
214
+ declare function getCanvasHostRecoveryFeed(): CanvasHostRecoveryFeed;
215
+
216
+ /** Stable browsing-context marker for Tempo-owned live interact previews. */
217
+ declare const TEMPO_INTERACT_FRAME_NAME = "tempo-interact-preview";
218
+ declare function isTempoInteractFrameName(value: string): boolean;
219
+ declare global {
220
+ interface Window {
221
+ __tempoInteractProjectionOwner?: "vite" | "electron";
222
+ }
223
+ }
224
+
129
225
  declare function useActiveState(storyboardId: string): boolean;
130
226
 
131
227
  interface StoryboardLayout {
@@ -153,6 +249,7 @@ declare function RouteStoryboard({ id, name, route, layout, }: {
153
249
  layout: StoryboardLayout;
154
250
  name?: string;
155
251
  }): react_jsx_runtime.JSX.Element;
252
+ /** @deprecated Legacy HTML storyboards are render-only. */
156
253
  declare function HtmlStoryboard({ id, name, filepath, src, layout, }: {
157
254
  id: string;
158
255
  layout: StoryboardLayout;
@@ -171,4 +268,4 @@ declare function StoryboardSlot({ children, id, kind, layout, name, route, filep
171
268
  src?: string;
172
269
  }): react_jsx_runtime.JSX.Element | null;
173
270
 
174
- export { Canvas, CanvasContext, CanvasHost, type CanvasHostCaptureResult, type CanvasHostRuntime, type CanvasHostWatch, HtmlStoryboard, LegacyStoryboardV1, RouteStoryboard, Storyboard, type StoryboardLayout, StoryboardSlot, buildRenderContentFiberSelector, buildRenderContentSelector, buildRenderSelector, captureStoryboardCombined, captureStoryboardHtml, captureStoryboardImage, captureStoryboardStaticHtml, getCanvasHostRuntime, getCanvasStoryboardRenderId, getOptionalCanvasHostRuntime, stripRenderContentWrapperAttributes, stripRenderContentWrapperFromCombinedCapture, useActiveState, watchStoryboardCombined, watchStoryboardHtml };
271
+ export { CANVAS_HOST_DOCUMENT_TITLE, Canvas, CanvasContext, CanvasHost, type CanvasHostCaptureResult, CanvasHostContractError, type CanvasHostModule, type CanvasHostRecoveryEvent, type CanvasHostRecoveryFeed, type CanvasHostRuntime, type CanvasHostWatch, CanvasImportBoundary, HtmlStoryboard, LegacyStoryboardV1, RouteStoryboard, Storyboard, type StoryboardLayout, StoryboardSlot, TEMPO_INTERACT_FRAME_NAME, buildRenderContentFiberSelector, buildRenderContentSelector, buildRenderSelector, canvasHostCapability, captureStoryboardCombined, captureStoryboardHtml, captureStoryboardImage, getCanvasHostRecoveryFeed, getCanvasHostRuntime, getCanvasStoryboardRenderId, getOptionalCanvasHostRuntime, isTempoInteractFrameName, stripRenderContentWrapperAttributes, stripRenderContentWrapperFromCombinedCapture, useActiveState, watchStoryboardCombined };