tempo-sdk 0.0.19 → 0.0.20

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/README.md CHANGED
@@ -189,8 +189,38 @@ export default defineConfig({
189
189
 
190
190
  Same `TEMPO` env-var gating, same `data-tempo-*` output as the Next.js plugin.
191
191
  The Vite plugin additionally exposes an `/__tempo/errors` SSE endpoint for
192
- streaming compile errors to the design surface — see `SPEC.md` for the full
193
- design.
192
+ streaming concrete compile errors to the design surface. It does not publish a
193
+ source-update stream or supervise source-to-visible HMR transactions; normal
194
+ updates belong to Vite and the official React plugin.
195
+
196
+ ### Canvas runtime surface
197
+
198
+ `tempo-sdk/canvas` exposes the bundler-agnostic runtime used by the generated
199
+ Canvas host:
200
+
201
+ - `CanvasHost` accepts either legacy `children` or literal `canvasModules`
202
+ loaders. Passing both throws `CanvasHostContractError` instead of silently
203
+ rendering an ambiguous host.
204
+ - `CanvasImportBoundary` owns lazy import, Suspense, canvas-scoped error
205
+ reporting, and current-owner mount success. It does not replay accepted
206
+ modules or inspect Vite transactions.
207
+ - `getCanvasHostRecoveryFeed()` returns the document-local
208
+ `host-recovery-feed`. It carries exactly one product fact
209
+ (`module-load-failure`: a canvas import rejection or an HMR
210
+ module-evaluation failure) to the generated recovery adapter; no hot
211
+ context, cycle number, owner success, or reload command crosses the SDK
212
+ boundary.
213
+ - `canvasHostCapability` declares protocol version 1 with
214
+ `supportsModules: true`. It is defense-in-depth, not the primary
215
+ compatibility gate.
216
+
217
+ Before generating `.tempo/tempo-host.tsx`, `tempo-devserver` runs the primary
218
+ installed-package check. An incompatible SDK fails before browser evaluation
219
+ with `canvas_host_sdk_incompatible` and an actionable install command. Tempo's
220
+ managed sidecar rollout first runs `ensureTempoSdkLatestSpec`; whether that
221
+ upgrade was attempted is included in the typed compatibility error. The rollout
222
+ contract is publish the compatible SDK first, verify the packed artifact, then
223
+ ship the devserver that requires it.
194
224
 
195
225
  ---
196
226
 
@@ -1,6 +1,6 @@
1
1
  import {
2
2
  parseCanvasFile
3
- } from "../chunk-P277UVZE.js";
3
+ } from "../chunk-GBKYTBEE.js";
4
4
 
5
5
  // canvas/editor.ts
6
6
  import { parseSync } from "oxc-parser";
@@ -3,7 +3,7 @@ import { ReactNode, ComponentType } from 'react';
3
3
  import { d as TempoStoryboard } from '../page-xi1aI5a7.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,30 @@ 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
+ type CanvasHostModule = {
31
+ canvasPath: string;
32
+ load: () => Promise<CanvasModule>;
33
+ };
34
+ declare class CanvasHostContractError extends Error {
35
+ name: string;
36
+ }
37
+ declare function CanvasHost({ children, canvasModules, activeStoryboardIds, isStoryboardActive, }: {
23
38
  children?: ReactNode;
39
+ canvasModules?: readonly CanvasHostModule[];
24
40
  activeStoryboardIds?: ReadonlySet<string> | readonly string[];
25
41
  isStoryboardActive?: (storyboardId: string) => boolean;
26
42
  }): react_jsx_runtime.JSX.Element;
@@ -33,11 +49,15 @@ type CanvasHostCaptureResult = {
33
49
  };
34
50
  timing?: Record<string, number>;
35
51
  };
52
+ type CanvasHostWatchResumeOptions = {
53
+ flush?: "always" | "if-dirty" | "never";
54
+ triggers?: readonly "viewport-capture"[];
55
+ };
36
56
  type CanvasHostWatch = {
37
57
  stop(): void | Promise<void>;
38
58
  pause?(): void;
39
- resume?(): void;
40
- setPaused?(paused: boolean): void;
59
+ resume?(options?: CanvasHostWatchResumeOptions): void;
60
+ setPaused?(paused: boolean, options?: CanvasHostWatchResumeOptions): void;
41
61
  };
42
62
  type CanvasHostRuntime = {
43
63
  captureSelector(selector: string, options?: {
@@ -100,21 +120,11 @@ declare function captureStoryboardImage(renderId: string, options?: Parameters<C
100
120
  declare function captureStoryboardHtml(renderId: string, options?: {
101
121
  timeout?: number;
102
122
  }): Promise<unknown | null>;
103
- declare function captureStoryboardStaticHtml(renderId: string, options?: {
104
- timeout?: number;
105
- }): Promise<unknown | null>;
106
123
  declare function captureStoryboardCombined(renderId: string, options?: {
107
124
  fiberSelector?: string;
108
125
  fiberTags?: unknown[];
109
126
  timeout?: number;
110
127
  }): 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
128
  declare function watchStoryboardCombined(renderId: string, options: {
119
129
  onUpdate(capture: unknown): void;
120
130
  onError?(error: Error): void;
@@ -126,6 +136,79 @@ declare function watchStoryboardCombined(renderId: string, options: {
126
136
  knownSourceVersion?: unknown;
127
137
  }): Promise<CanvasHostWatch>;
128
138
 
139
+ /**
140
+ * The CanvasHost protocol capability this SDK build implements.
141
+ *
142
+ * The authoritative compatibility gate is devserver-side: tempo-devserver
143
+ * resolves the installed tempo-sdk package version BEFORE generating a host
144
+ * document and refuses generation with a typed, actionable error when the
145
+ * installed SDK predates the generated contract. That check cannot be an
146
+ * in-host import assertion, because an SDK old enough to matter does not
147
+ * export this constant — the named import itself would throw before any
148
+ * assertion ran.
149
+ *
150
+ * This constant exists as defense-in-depth for FUTURE protocol bumps, once
151
+ * every supported SDK version is known to export it.
152
+ */
153
+ declare const canvasHostCapability: {
154
+ readonly protocolVersion: 1;
155
+ readonly supportsModules: true;
156
+ };
157
+
158
+ /**
159
+ * In-document recovery feed shared between the SDK runtime and the
160
+ * devserver-generated CanvasHost recovery adapter.
161
+ *
162
+ * The generated host document contains two cooperating parties that must not
163
+ * import each other:
164
+ *
165
+ * - the SDK (problem tracking), which observes the product fact "a module
166
+ * evaluation failed in this document"; and
167
+ * - the devserver-generated Vite recovery adapter, which owns
168
+ * `import.meta.hot` and decides when a failed host document may reload.
169
+ *
170
+ * The feed is a tiny window-global event bus with create-if-absent semantics
171
+ * on both sides, so evaluation order between the SDK and the generated
172
+ * adapter never matters. It carries product facts about failed module loads —
173
+ * never Vite contexts, cycle numbers, owner success, or reload commands.
174
+ * Which canvases show which problems is the SDK problem tracker's job; the
175
+ * adapter's repair (a document reload) is document-scoped and needs no owner
176
+ * identity.
177
+ */
178
+ type CanvasHostRecoveryEvent = {
179
+ /** "module-load-failure": a module load or evaluation failed in a way Vite
180
+ * cannot converge in place (evaluation threw and cleared the Fast Refresh
181
+ * accepts, or a canvas's cold-start import rejected) — the adapter reloads
182
+ * on the first later HMR cycle. "module-update-dropped": Vite dropped a
183
+ * hot update whose module fetch failed — the adapter reloads only if a
184
+ * later cycle does not retry the path (a retry lets Vite own the outcome). */
185
+ type: "module-load-failure" | "module-update-dropped";
186
+ /** Failed module path. Diagnostic for load failures; for dropped updates it
187
+ * must be the exact accepted-module path Vite reported so the adapter can
188
+ * match it against later update payloads. */
189
+ path: string;
190
+ message?: string;
191
+ };
192
+ type CanvasHostRecoveryFeed = {
193
+ publish(event: CanvasHostRecoveryEvent): void;
194
+ subscribe(listener: (event: CanvasHostRecoveryEvent) => void): () => void;
195
+ };
196
+ /**
197
+ * Returns the document's shared recovery feed, creating it when this is the
198
+ * first party to ask. The generated adapter bootstraps an identically-shaped
199
+ * feed, so whichever side evaluates first wins and the other reuses it.
200
+ */
201
+ declare function getCanvasHostRecoveryFeed(): CanvasHostRecoveryFeed;
202
+
203
+ /** Stable browsing-context marker for Tempo-owned live interact previews. */
204
+ declare const TEMPO_INTERACT_FRAME_NAME = "tempo-interact-preview";
205
+ declare function isTempoInteractFrameName(value: string): boolean;
206
+ declare global {
207
+ interface Window {
208
+ __tempoInteractProjectionOwner?: "vite" | "electron";
209
+ }
210
+ }
211
+
129
212
  declare function useActiveState(storyboardId: string): boolean;
130
213
 
131
214
  interface StoryboardLayout {
@@ -171,4 +254,4 @@ declare function StoryboardSlot({ children, id, kind, layout, name, route, filep
171
254
  src?: string;
172
255
  }): react_jsx_runtime.JSX.Element | null;
173
256
 
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 };
257
+ export { 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 };