@pwfabric/embed 0.0.0-stage → 1.0.0-rc.1

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,504 @@
1
+ import * as React from 'react';
2
+ import { RenderableSurface, CapabilityProvider, EntityFacade, SurfaceConnectionsValue, DataServiceConfig, SurfaceDataCache, ImageAdapter, BlockComponentRegistry, SurfaceEvent, BlockComponentProps, EntityDefinition } from '@pwfabric/runtime';
3
+ import { DynamicBlockDescriptor, DynamicStarterDescriptor, BreakpointName, SurfaceRenderGrant } from '@pwfabric/contracts';
4
+
5
+ /**
6
+ * Shared mount core for the embed runtime.
7
+ *
8
+ * Wraps the REAL runtime renderer (`SurfaceRenderer` / `DataBoundSurfaceRenderer`,
9
+ * imported as-is from `@pwfabric/runtime`) inside a
10
+ * `DynamicArtifactProvider` and mounts it into a target DOM node with
11
+ * `ReactDOM.createRoot`.
12
+ *
13
+ * Nothing here talks to the network on its own — the caller supplies the
14
+ * already-resolved surface + dynamic block descriptors. Thin mode fetches
15
+ * them first (see `thin.ts`); fat mode passes inline descriptors (see
16
+ * `fat.ts`).
17
+ *
18
+ * @module @pwfabric/embed/render-core
19
+ */
20
+
21
+ /**
22
+ * Options accepted by the shared mount. A superset of what both thin and fat
23
+ * mode produce after they have resolved the surface + descriptors.
24
+ */
25
+ interface RenderCoreOptions {
26
+ /** Resolved surface to render (blocks + appearance + capabilities). */
27
+ readonly surface: RenderableSurface;
28
+ /** Dynamic (installed/CDN/inline) block descriptors. */
29
+ readonly dynamicBlocks?: readonly DynamicBlockDescriptor[];
30
+ /** Optional dynamic starter descriptors (rarely used in embed). */
31
+ readonly dynamicStarters?: readonly DynamicStarterDescriptor[];
32
+ /** App-level light/dark hint passed straight to the renderer. */
33
+ readonly theme?: 'light' | 'dark';
34
+ /** Explicit viewport breakpoint override (otherwise auto-detected). */
35
+ readonly viewport?: BreakpointName;
36
+ /** Capability providers (auth/data/navigation/...). */
37
+ readonly capabilities?: CapabilityProvider[];
38
+ /** Entity facade for the platform/entities capability (fat = in-memory). */
39
+ readonly entityFacade?: EntityFacade;
40
+ /**
41
+ * The surface CONNECTIONS CONTEXT — configured connections +
42
+ * the loaded connector/provider engine registry. When present the render
43
+ * routes `{kind:entity,connector}` data sources through the registry AND
44
+ * exposes the value to blocks via `SurfaceConnectionsContext` (the
45
+ * engine-bridge path, e.g. chat-panel). Absent = today's behavior.
46
+ */
47
+ readonly connections?: SurfaceConnectionsValue;
48
+ /**
49
+ * Configuration for the renderer's DataService — the host's own API origin
50
+ * (so the platform store can be called with its cookie and nobody else can)
51
+ * and the token resolver for `authProviderRef`.
52
+ */
53
+ readonly dataServiceConfig?: DataServiceConfig;
54
+ /** See DataBoundSurfaceRendererProps — 'gate' withholds the tree until the first fetch, 'immediate' paints at once. */
55
+ readonly loadingStrategy?: 'gate' | 'immediate';
56
+ /** See DataBoundSurfaceRendererProps — yesterday's rows while today's load. */
57
+ readonly dataCache?: SurfaceDataCache;
58
+ /** `live` (default) or `inert` (no auto-refresh, no dispatched actions). */
59
+ readonly interactionMode?: 'live' | 'inert';
60
+ /** Base path for links/routing. */
61
+ readonly basePath?: string;
62
+ /** Image adapter; defaults to plain <img> when omitted. */
63
+ readonly imageAdapter?: ImageAdapter;
64
+ /** Custom block component overrides (test/preview seams). */
65
+ readonly components?: Partial<BlockComponentRegistry>;
66
+ /** Surface event callback. */
67
+ readonly onEvent?: (event: SurfaceEvent) => void;
68
+ /** Grid gap (px) override. */
69
+ readonly gap?: number;
70
+ /** Surface inner padding (px) override. */
71
+ readonly padding?: number;
72
+ /**
73
+ * Draw a visible "rebuild needed" placeholder for every block type in the
74
+ * surface that has neither a dynamic descriptor nor a component.
75
+ *
76
+ * Off by default, and deliberately so: on a published page an unknown type
77
+ * renders only its children (see the renderer), because a visible
78
+ * placeholder reads as a broken page to a visitor. A live preview is the
79
+ * opposite case — the author has just added a block whose bundle is not in
80
+ * the shipped manifest yet, and an invisible block would look like the edit
81
+ * did nothing. The placeholder is a plain element: nothing is fetched or
82
+ * imported for the missing type.
83
+ */
84
+ readonly placeholderMissingBlocks?: boolean;
85
+ }
86
+ /**
87
+ * Handle returned by `mountSurface` so the host can later unmount or update.
88
+ */
89
+ interface SurfaceMountHandle {
90
+ /** Tear down the React root and free the DOM. */
91
+ unmount(): void;
92
+ /** The root DOM node the surface was mounted into. */
93
+ readonly container: HTMLElement;
94
+ /**
95
+ * Re-render new surface options into the SAME root — e.g. a client-side
96
+ * page transition. Reuses the root created by `mountSurface` instead of
97
+ * calling `createRoot`/`hydrateRoot` again (which would either throw or
98
+ * discard the existing tree).
99
+ */
100
+ render(opts: RenderCoreOptions): void;
101
+ }
102
+ interface MountSurfaceOptions {
103
+ /**
104
+ * Hydrate existing server-rendered markup already present in `target`
105
+ * (`ReactDOM.hydrateRoot`) instead of a fresh client-only mount
106
+ * (`ReactDOM.createRoot`, which discards whatever DOM was already there).
107
+ * The initial `opts` must produce a tree matching what was server-rendered
108
+ * or React will warn/re-render on mismatch.
109
+ */
110
+ readonly hydrate?: boolean;
111
+ }
112
+ /**
113
+ * Does this surface need the data-bound renderer? The RUNTIME answers —
114
+ * `surfaceNeedsDataBinding` is the same predicate the renderer's own
115
+ * passthrough uses: data sources, `initialState`, declared behaviors,
116
+ * formBindings, or a block `action`.
117
+ *
118
+ * This used to be a second, shorter list (sources + initialState). It had
119
+ * drifted from the renderer's in both directions: a page with only buttons
120
+ * carrying `action` props, or only formBindings, got the plain
121
+ * SurfaceRenderer here — no dispatcher, so the click did nothing and the
122
+ * submit went nowhere.
123
+ */
124
+ declare function needsDataBoundRenderer(surface: RenderableSurface): boolean;
125
+ /**
126
+ * Every block type in `surface` that nothing can render: no dynamic
127
+ * descriptor and no component. Walks `blocks` and `children` recursively.
128
+ */
129
+ declare function missingBlockTypes(surface: RenderableSurface, dynamicBlocks: readonly DynamicBlockDescriptor[] | undefined, components: Partial<BlockComponentRegistry> | undefined): string[];
130
+ /**
131
+ * The placeholder for a block type whose bundle this page does not have.
132
+ * Static markup only — it never asks for the type's code. Children still
133
+ * render inside it, so a missing container does not hide its subtree.
134
+ */
135
+ declare function RebuildNeededBlock({ block, children }: BlockComponentProps): React.ReactElement;
136
+ /**
137
+ * Build the React element tree for a surface — `DynamicArtifactProvider`
138
+ * wrapping the appropriate renderer. Exposed separately from `mountSurface`
139
+ * so it can be used in SSR / test contexts without a DOM root.
140
+ */
141
+ declare function createSurfaceElement(opts: RenderCoreOptions): React.ReactElement;
142
+ /**
143
+ * Resolve a target — an HTMLElement or a CSS selector string — to a node.
144
+ */
145
+ declare function resolveTarget(target: HTMLElement | string): HTMLElement;
146
+ /**
147
+ * Mount a surface into `target` and return a handle for later teardown or
148
+ * update. Pass `{ hydrate: true }` to attach to existing server-rendered
149
+ * markup instead of discarding it.
150
+ */
151
+ declare function mountSurface(target: HTMLElement | string, opts: RenderCoreOptions, mountOptions?: MountSurfaceOptions): SurfaceMountHandle;
152
+
153
+ /**
154
+ * Fat mode renderer — fully offline.
155
+ *
156
+ * Renders a surface with NO API and NO auth. The surface JSON, its block
157
+ * bundle descriptors, and its appearance are all provided inline by the
158
+ * caller. Capabilities default to the offline stubs (in-memory entity facade,
159
+ * inert navigation), so a surface that declares capabilities still renders.
160
+ *
161
+ * Offline block loading: `DynamicBlockDescriptor.moduleUrl` may be a `data:`
162
+ * URL (or any URL the host can `fetch`). The runtime's `BlockModuleLoader`
163
+ * fetches the bytes, SHA-256-verifies them against `descriptor.integrity`,
164
+ * and `import()`s the resulting Blob URL — all client-side, no server. As long
165
+ * as the descriptors carry inline `data:` module URLs + correct integrity
166
+ * hashes, the whole render is self-contained.
167
+ *
168
+ * @module @pwfabric/embed/fat
169
+ */
170
+
171
+ interface RenderFatOptions {
172
+ /** The surface to render (inline JSON). */
173
+ readonly surface: RenderableSurface;
174
+ /**
175
+ * Block bundle descriptors. `moduleUrl` is typically a `data:text/javascript`
176
+ * URL for full offline self-containment; integrity must match the bytes.
177
+ */
178
+ readonly blocks?: readonly DynamicBlockDescriptor[];
179
+ /**
180
+ * Capability providers. When omitted, offline stubs are auto-supplied for
181
+ * any capability the surface declares (entities → in-memory facade,
182
+ * navigation → inert provider).
183
+ */
184
+ readonly capabilities?: CapabilityProvider[];
185
+ /** Override the auto-created offline entity facade. */
186
+ readonly entityFacade?: EntityFacade;
187
+ /**
188
+ * Connector/provider engine registry + configured
189
+ * connections. The runner builds this from the export's shipped engine
190
+ * bundles + the PKCE auth token, so connector panels (chat-panel etc.) run
191
+ * against real engines. Threaded to the data-bound renderer, which exposes it
192
+ * via `SurfaceConnectionsContext`.
193
+ */
194
+ readonly connections?: SurfaceConnectionsValue;
195
+ /**
196
+ * How the data layer authenticates its requests.
197
+ *
198
+ * Carries the resolver a pwapp runner supplies for the VISITOR's own
199
+ * session: a source that names an `authProviderRef` gets an
200
+ * `Authorization: Bearer` header for it. Declared here because fat mode is
201
+ * how a published app renders, and a published app behind a sign-in has to
202
+ * fetch its own records as the person who signed in.
203
+ */
204
+ readonly dataServiceConfig?: DataServiceConfig;
205
+ readonly loadingStrategy?: 'gate' | 'immediate';
206
+ readonly dataCache?: SurfaceDataCache;
207
+ /** Inline appearance ref; overrides `surface.appearance` when given. */
208
+ readonly appearance?: RenderableSurface['appearance'];
209
+ /**
210
+ * Hydrate existing server-rendered markup in `target` instead of a fresh
211
+ * client-only mount. See `MountSurfaceOptions.hydrate`.
212
+ */
213
+ readonly hydrate?: boolean;
214
+ readonly theme?: RenderCoreOptions['theme'];
215
+ readonly viewport?: RenderCoreOptions['viewport'];
216
+ readonly interactionMode?: RenderCoreOptions['interactionMode'];
217
+ readonly basePath?: RenderCoreOptions['basePath'];
218
+ readonly imageAdapter?: RenderCoreOptions['imageAdapter'];
219
+ readonly components?: RenderCoreOptions['components'];
220
+ readonly onEvent?: RenderCoreOptions['onEvent'];
221
+ readonly gap?: RenderCoreOptions['gap'];
222
+ readonly padding?: RenderCoreOptions['padding'];
223
+ /** See `RenderCoreOptions.placeholderMissingBlocks` — preview hosts only. */
224
+ readonly placeholderMissingBlocks?: RenderCoreOptions['placeholderMissingBlocks'];
225
+ }
226
+ /**
227
+ * The handle fat mode returns. `update` re-renders new fat options into the
228
+ * SAME root, through the same option translation the first mount used — so a
229
+ * host holding fat options (blocks, appearance override, offline stubs) never
230
+ * has to rebuild the core options by hand.
231
+ */
232
+ interface FatMountHandle extends SurfaceMountHandle {
233
+ update(opts: RenderFatOptions): void;
234
+ }
235
+ /**
236
+ * Translate fat options into the shared core options: offline capability
237
+ * stubs, the appearance override folded into the surface, every passthrough.
238
+ */
239
+ declare function fatCoreOptions(opts: RenderFatOptions): RenderCoreOptions;
240
+ /**
241
+ * Render a surface fully offline into `target`.
242
+ */
243
+ declare function renderFat(target: HTMLElement | string, opts: RenderFatOptions): FatMountHandle;
244
+
245
+ /**
246
+ * Thin mode loader.
247
+ *
248
+ * Fetches a published surface + its render grants from a host API the same
249
+ * way a host application's public surface route does, then normalises the
250
+ * result into the shape `render-core` consumes.
251
+ *
252
+ * The host API serves `GET /api/surfaces/by-slug/:tenant/:slug` (and
253
+ * `GET /api/surfaces/:id/published`). Host API clients are not part of this
254
+ * engine, so this issues the HTTP call with `fetch` and applies the same
255
+ * post-processing a host applies:
256
+ * - `definition.rootBlock.children` (or `definition.blocks`) → runtime blocks,
257
+ * merging each block's stored `layout.span` with `DEFAULT_BLOCK_LAYOUT.span`.
258
+ * - `response.renderGrants[]` → `DynamicBlockDescriptor[]` (publisher
259
+ * 'workspace', unverified) — byte-identical to the host's `mappedDescriptors`.
260
+ * - `definition.theme` / `styleVariables` → an `appearance` ref.
261
+ * - `definition.capabilities` normalised with `required: false` default.
262
+ *
263
+ * @module @pwfabric/embed/thin
264
+ */
265
+
266
+ interface ThinAuth {
267
+ /** Bearer token; injected as `Authorization` on the surface fetch and on
268
+ * any REST data sources (matching the host's `ms_access_token` behaviour). */
269
+ readonly accessToken?: string;
270
+ /** Send credentials (cookies) with the request. */
271
+ readonly includeCredentials?: boolean;
272
+ }
273
+ interface LoadThinOptions {
274
+ /** API origin, e.g. `https://api.example.com`. */
275
+ readonly apiBaseUrl: string;
276
+ /** Optional auth. */
277
+ readonly auth?: ThinAuth;
278
+ /** Custom fetch (test injection / non-browser runtime). */
279
+ readonly fetchImpl?: typeof fetch;
280
+ }
281
+ /**
282
+ * A surface reference: either a `surfaceId` (by-id) or a tenant+surface slug
283
+ * pair (by-slug, the host's path).
284
+ */
285
+ type ThinSurfaceRef = {
286
+ readonly surfaceId: string;
287
+ } | {
288
+ readonly tenantSlug: string;
289
+ readonly surfaceSlug: string;
290
+ };
291
+ interface LoadThinResult {
292
+ readonly surface: RenderableSurface;
293
+ readonly dynamicBlocks: readonly DynamicBlockDescriptor[];
294
+ readonly surfaceId?: string;
295
+ readonly worldId?: string;
296
+ /** Surface-level layout hints from the API (maxWidth/gap/padding). */
297
+ readonly layout?: {
298
+ maxWidth?: number;
299
+ gap?: number;
300
+ padding?: number;
301
+ };
302
+ }
303
+ /**
304
+ * Map render grants → dynamic block descriptors. Byte-identical to the host's
305
+ * `mappedDescriptors` memo: publisher 'workspace', unverified, a minimal
306
+ * marketplace-category definition.
307
+ */
308
+ declare function grantsToDescriptors(grants: readonly SurfaceRenderGrant[]): DynamicBlockDescriptor[];
309
+ /**
310
+ * Fetch + normalise a published surface and its render grants.
311
+ */
312
+ declare function loadThin(ref: ThinSurfaceRef, options: LoadThinOptions): Promise<LoadThinResult>;
313
+
314
+ /**
315
+ * Self-contained fat HTML builder.
316
+ *
317
+ * Produces a single HTML string that renders a surface fully offline:
318
+ * - the surface JSON in a `<script type="application/pw-surface+json">` tag,
319
+ * - the block descriptors in `<script type="application/pw-blocks+json">`
320
+ * (with `moduleUrl` left as-is — callers should pass `data:` URLs for true
321
+ * offline self-containment + matching integrity hashes),
322
+ * - the appearance ref in `<script type="application/pw-appearance+json">`,
323
+ * - the bundled `embed.js` IIFE inlined verbatim in a `<script>` tag,
324
+ * - a bootstrap call:
325
+ * `PWFabric.render('#pw-root', { surface }, { mode:'fat', blocks, appearance })`.
326
+ *
327
+ * Pure function — no I/O. The local preview tool reads `dist/embed.js` off
328
+ * disk and passes its contents as `embedJs`; this module never touches the
329
+ * filesystem.
330
+ *
331
+ * @module @pwfabric/embed/build-fat-html
332
+ */
333
+
334
+ interface BuildFatHtmlOptions {
335
+ /** Surface JSON to inline + render. */
336
+ readonly surface: RenderableSurface;
337
+ /** Block descriptors (prefer `data:` moduleUrls for offline). */
338
+ readonly blocks?: readonly DynamicBlockDescriptor[];
339
+ /** Appearance ref (defaults to `surface.appearance`). */
340
+ readonly appearance?: RenderableSurface['appearance'];
341
+ /** The full contents of the built `dist/embed.js` IIFE. */
342
+ readonly embedJs: string;
343
+ /** `<title>` of the page. */
344
+ readonly title?: string;
345
+ /** Optional `lang` attribute. */
346
+ readonly lang?: string;
347
+ }
348
+ /**
349
+ * Build a fully self-contained HTML document string.
350
+ */
351
+ declare function buildFatHtml(options: BuildFatHtmlOptions): string;
352
+
353
+ /**
354
+ * Offline capability stubs for fat mode.
355
+ *
356
+ * Fat mode renders with no API and no auth, so any capability the surface
357
+ * declares (entities, navigation, persistence) must be satisfied locally.
358
+ * These factories provide in-memory / no-op implementations:
359
+ *
360
+ * - `createOfflineEntityFacade()` — a real `createEntityFacade()` backed by
361
+ * the in-memory `StaticConnector`, optionally seeded with entity defs +
362
+ * records. CRUD happens entirely in memory.
363
+ * - `createOfflineNavigationProvider()` — a `navigation` CapabilityProvider
364
+ * whose links resolve to in-page anchors (no router).
365
+ * - `staticDataSources()` — turns a record-map of inline data into
366
+ * `platform/persistence` static data sources for the DataBoundSurfaceRenderer.
367
+ *
368
+ * @module @pwfabric/embed/capabilities-stub
369
+ */
370
+
371
+ interface OfflineEntitySeed {
372
+ /** Entity definition to register. */
373
+ readonly definition: EntityDefinition;
374
+ /** Initial records to load into the static connector. */
375
+ readonly records?: readonly Record<string, unknown>[];
376
+ }
377
+ /**
378
+ * Build an entity facade wired to a single in-memory `StaticConnector`.
379
+ * All CRUD performed by the surface happens in memory and is lost on reload —
380
+ * exactly what an offline embed wants.
381
+ */
382
+ declare function createOfflineEntityFacade(seeds?: readonly OfflineEntitySeed[]): EntityFacade;
383
+ /**
384
+ * A `navigation` capability provider for offline rendering. There is no
385
+ * router, so navigation is reduced to in-page anchors / `window.location`.
386
+ * The provider exposes a `data` payload the navigation-aware blocks read.
387
+ */
388
+ declare function createOfflineNavigationProvider(options?: {
389
+ readonly basePath?: string;
390
+ }): CapabilityProvider;
391
+ /**
392
+ * Convert a map of `{ sourceId: data }` into the `platform/persistence`
393
+ * capability config shape (static data sources) that the
394
+ * DataBoundSurfaceRenderer consumes. Use this to inline mock/fixture data into
395
+ * a fat embed so REST-bound blocks render without a backend.
396
+ */
397
+ declare function staticPersistenceCapability(data: Readonly<Record<string, unknown>>, initialState?: Record<string, unknown>): CapabilityProvider & {
398
+ capability: string;
399
+ config: Record<string, unknown>;
400
+ };
401
+
402
+ /**
403
+ * @pwfabric/embed
404
+ *
405
+ * Portable embed runtime — renders a PWFabric CanonicalSurface anywhere, using
406
+ * the REAL `SurfaceRenderer` from `@pwfabric/runtime`.
407
+ *
408
+ * Consumed two ways:
409
+ * - as a built artifact — `assembleWebApp` takes the bundle as an `embedJs`
410
+ * string and ships it into every export's `assets/`;
411
+ * - as a dependency — a host API can resolve `dist/embed.js` out of
412
+ * `node_modules` rather than keeping a committed copy (a vendored copy
413
+ * goes stale silently; a package dependency is version-gated).
414
+ *
415
+ * Two modes:
416
+ * - **thin** — fetch surface + render grants from the API (like a hosted surface page).
417
+ * - **fat** — render an inline surface + block bundles + appearance fully
418
+ * offline, no backend.
419
+ *
420
+ * Public entry: `PWFabric.render(target, source, options?)`. A `data-pw-surface`
421
+ * DOM auto-loader is also wired on load.
422
+ *
423
+ * @module @pwfabric/embed
424
+ */
425
+
426
+ type EmbedMode = 'thin' | 'fat';
427
+ /**
428
+ * Source: either a reference to fetch (thin) or an inline surface (fat).
429
+ */
430
+ type EmbedSource = {
431
+ readonly surfaceId: string;
432
+ } | {
433
+ readonly tenantSlug: string;
434
+ readonly surfaceSlug: string;
435
+ } | {
436
+ readonly surface: RenderableSurface;
437
+ };
438
+ interface EmbedOptions {
439
+ /** `thin` (fetch) or `fat` (inline/offline). Auto-detected from source when omitted. */
440
+ readonly mode?: EmbedMode;
441
+ /** API origin for thin mode (e.g. https://api.example.com). */
442
+ readonly apiBaseUrl?: string;
443
+ /** Auth for thin mode. */
444
+ readonly auth?: ThinAuth;
445
+ /** Custom fetch implementation (test/non-browser). */
446
+ readonly fetchImpl?: typeof fetch;
447
+ /** Inline block bundle descriptors (fat). */
448
+ readonly blocks?: readonly DynamicBlockDescriptor[];
449
+ /** Inline appearance ref (fat); falls back to surface.appearance. */
450
+ readonly appearance?: RenderableSurface['appearance'];
451
+ /** Hydrate existing server-rendered markup instead of a fresh mount (fat). */
452
+ readonly hydrate?: boolean;
453
+ /** Capability providers (fat). */
454
+ readonly capabilities?: CapabilityProvider[];
455
+ /** Entity facade override (fat). */
456
+ readonly entityFacade?: EntityFacade;
457
+ /** Connector/provider engine registry + connections (fat embed). */
458
+ readonly connections?: SurfaceConnectionsValue;
459
+ /**
460
+ * Configuration for the renderer's DataService — the host's own API origin
461
+ * (so the platform store can be called with its cookie and nobody else can)
462
+ * and the token resolver for `authProviderRef`.
463
+ */
464
+ readonly dataServiceConfig?: DataServiceConfig;
465
+ readonly loadingStrategy?: 'gate' | 'immediate';
466
+ readonly dataCache?: SurfaceDataCache;
467
+ readonly theme?: 'light' | 'dark';
468
+ readonly viewport?: BreakpointName;
469
+ readonly basePath?: string;
470
+ readonly imageAdapter?: ImageAdapter;
471
+ readonly interactionMode?: 'live' | 'inert';
472
+ readonly onEvent?: (event: SurfaceEvent) => void;
473
+ readonly gap?: number;
474
+ readonly padding?: number;
475
+ /** Custom block component overrides (test/preview seams). */
476
+ readonly components?: Partial<BlockComponentRegistry>;
477
+ /** Visible placeholder for block types nothing can render (preview hosts). */
478
+ readonly placeholderMissingBlocks?: boolean;
479
+ readonly onReady?: (handle: SurfaceMountHandle) => void;
480
+ readonly onError?: (error: unknown) => void;
481
+ }
482
+ /**
483
+ * Render a surface into `target`.
484
+ *
485
+ * @param target An HTMLElement or CSS selector string.
486
+ * @param source `{ surfaceId }` / `{ tenantSlug, surfaceSlug }` (thin) or
487
+ * `{ surface }` (fat).
488
+ * @param options Mode + transport + render options.
489
+ * @returns A promise resolving to the mount handle.
490
+ */
491
+ declare function render(target: HTMLElement | string, source: EmbedSource, options?: EmbedOptions): Promise<SurfaceMountHandle>;
492
+ /**
493
+ * Scan + hydrate all `[data-pw-surface]` elements currently in the document.
494
+ * Idempotent: elements already hydrated (marked with `data-pw-hydrated`) skip.
495
+ */
496
+ declare function autoload(root?: ParentNode): void;
497
+ declare const PWFabric: {
498
+ render: typeof render;
499
+ renderFat: typeof renderFat;
500
+ loadThin: typeof loadThin;
501
+ autoload: typeof autoload;
502
+ };
503
+
504
+ export { type BuildFatHtmlOptions, type EmbedMode, type EmbedOptions, type EmbedSource, type FatMountHandle, type LoadThinOptions, type LoadThinResult, PWFabric, RebuildNeededBlock, type RenderCoreOptions, type RenderFatOptions, type SurfaceMountHandle, type ThinAuth, type ThinSurfaceRef, autoload, buildFatHtml, createOfflineEntityFacade, createOfflineNavigationProvider, createSurfaceElement, PWFabric as default, fatCoreOptions, grantsToDescriptors, loadThin, missingBlockTypes, mountSurface, needsDataBoundRenderer, render, renderFat, resolveTarget, staticPersistenceCapability };