@widgetic/embed-sdk 2.1.2 → 2.1.4

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.
Files changed (40) hide show
  1. package/README.md +2 -0
  2. package/dist/browser/chunks/ABTestManager.js +1 -1
  3. package/dist/browser/chunks/advanced.js +1 -1
  4. package/dist/browser/chunks/api.js +1 -1
  5. package/dist/browser/chunks/core.js +1 -1
  6. package/dist/browser/chunks/display.js +1 -1
  7. package/dist/browser/chunks/renderers.js +1 -1
  8. package/dist/browser/chunks/scanner.js +1 -1
  9. package/dist/browser/chunks/security.js +1 -1
  10. package/dist/browser/chunks/workflows.js +1 -1
  11. package/dist/browser/embed-bootstrap.js +1 -1
  12. package/dist/browser/embed-sdk.js +1 -1
  13. package/dist/esm/chunks/ABTestManager.js +1 -1
  14. package/dist/esm/chunks/advanced.js +1 -1
  15. package/dist/esm/chunks/api.js +1 -1
  16. package/dist/esm/chunks/core.js +1 -1
  17. package/dist/esm/chunks/display.js +1 -1
  18. package/dist/esm/chunks/renderers.js +1 -1
  19. package/dist/esm/chunks/scanner.js +1 -1
  20. package/dist/esm/chunks/security.js +1 -1
  21. package/dist/esm/chunks/workflows.js +1 -1
  22. package/dist/esm/embed-bootstrap.js +1 -1
  23. package/dist/esm/embed-sdk.js +1 -1
  24. package/dist/esm/types/core/auth-detector.d.ts +2 -0
  25. package/dist/esm/types/core/constants.d.ts +1 -1
  26. package/dist/esm/types/core/version.d.ts +1 -0
  27. package/dist/esm/types/utils/autoscale-request.d.ts +11 -0
  28. package/dist/esm/types/utils/editor-session-access.d.ts +15 -0
  29. package/dist/esm/types/utils/editor-session-response.d.ts +21 -0
  30. package/dist/esm/types/utils/embed-autoscale.d.ts +139 -0
  31. package/dist/esm/types/utils/gateway-request.d.ts +29 -0
  32. package/dist/esm/types/utils/hydrate-published-host.d.ts +8 -2
  33. package/dist/esm/types/utils/mount-direct-widget.d.ts +28 -0
  34. package/dist/esm/types/utils/public-embed-lookup.d.ts +8 -2
  35. package/dist/esm/types/utils/published-host-bridge.d.ts +26 -5
  36. package/dist/esm/types/utils/workflow-shared-contract.d.ts +7 -0
  37. package/dist/esm/types/workflows/workflow-stage.d.ts +1 -1
  38. package/dist/umd/embed-bootstrap.js +1 -1
  39. package/dist/umd/embed-sdk.js +1 -1
  40. package/package.json +5 -4
@@ -0,0 +1,139 @@
1
+ /**
2
+ * Autoscale of a plain embed: the `autoscale` attribute of a `<widgetic composition-id>` tag.
3
+ *
4
+ * A tag with `autoscale` is as tall as its widget needs, and follows when that changes (an entry is added to a
5
+ * guestbook, a list loads, the page gets narrower). Without it the embed keeps the size its tag gives, the way an
6
+ * iframe does. The height the tag asks for is the least the embed is tall (`autoscale-min-height` replaces it); the most
7
+ * is `autoscale-max-height` (2000 by default), and `autoscale-debounce`, `-threshold`, `-animate` and
8
+ * `-animation-duration` tune it, with the numbers a workflow embed and the legacy autoscale already use.
9
+ *
10
+ * Two kinds of embed can follow:
11
+ *
12
+ * - A widget mounted in the page (direct): the SDK looks into the widget and works out the height at which none of
13
+ * its scrolling regions has to scroll (`measureNaturalHeight`). The box of the widget keeps an explicit height all
14
+ * the time, so a widget that fills its frame (`height: 100%` all the way down) works as it does in an iframe, and a
15
+ * list that has more entries than fit makes the box taller, not the page longer.
16
+ * - A widget in an iframe: the frame is another document, so it is the widget that says how tall it is, with the
17
+ * `widgetic:resize` message every widget page may send (`detail.height`). The SDK follows what it hears. A widget
18
+ * that never says anything keeps the height of its tag.
19
+ *
20
+ * Not for a workflow's stages (the workflow code follows their height itself, workflows/workflow-stage.ts) and not for an
21
+ * overlay (the overlay decides its own size). A workflow tag has its own rules in src/workflows/workflow-autoscale.ts;
22
+ * the numbers here are the same (embed-autoscale-parity.test.ts holds the two together).
23
+ *
24
+ * The code-split build and the single-file build both put this file in the SDK's own code, not the workflow code, so it
25
+ * never imports from src/workflows/.
26
+ */
27
+ /** Non-secret runtime constants of an embed's autoscale. The same defaults as the legacy autoscale and a workflow embed. */
28
+ export declare const EMBED_AUTOSCALE_DEFAULTS: {
29
+ readonly MAX_HEIGHT_PIXELS: 2000;
30
+ readonly DEBOUNCE_MILLISECONDS: 150;
31
+ readonly THRESHOLD_PIXELS: 5;
32
+ readonly ANIMATE: true;
33
+ readonly ANIMATION_MILLISECONDS: 300;
34
+ };
35
+ export interface EmbedAutoscaleSettings {
36
+ /** The least the embed is tall, in pixels: the height its tag asks for, or `autoscale-min-height` when the tag names one. */
37
+ floorHeight: number;
38
+ /** The most the embed is tall, in pixels. Never below the floor. */
39
+ maxHeight: number;
40
+ /** The longest the embed waits before it looks at the widget again, in milliseconds. */
41
+ debounceDelay: number;
42
+ /** The smallest change in height worth following, in pixels. */
43
+ threshold: number;
44
+ /** Whether a change in height is animated. */
45
+ animate: boolean;
46
+ /** How long the animation lasts, in milliseconds. */
47
+ animationDuration: number;
48
+ }
49
+ /** Whether a host is a stage of a workflow: the workflow code, not this one, follows its height. */
50
+ export declare function isWorkflowStageHost(host: Element): boolean;
51
+ /**
52
+ * Whether a tag's embed follows its widget's height: it asked for it (`autoscale`) and nothing else decides its size.
53
+ */
54
+ export declare function shouldAutoscaleEmbed(host: Element): boolean;
55
+ /**
56
+ * The settings of an embed, read from its tag. `tagHeightPixels` is the height the tag's embed starts at (the floor,
57
+ * unless the tag names `autoscale-min-height`).
58
+ */
59
+ export declare function readEmbedAutoscaleSettings(host: Element, tagHeightPixels: number, prefersReducedMotion?: boolean): EmbedAutoscaleSettings;
60
+ /** A height held between the floor and the maximum, rounded up to a whole pixel (half a pixel less would cut the last line). */
61
+ export declare function clampEmbedHeight(rawHeight: number, settings: Pick<EmbedAutoscaleSettings, "floorHeight" | "maxHeight">): number;
62
+ /**
63
+ * The scroll regions that did not follow the box when it changed height: a list that is as tall as its own CSS says
64
+ * (`max-height: 24rem`, `height: 20rem`), which scrolls inside the widget whatever the widget's box is. Making the box
65
+ * taller for one only leaves empty space, and every look would ask for more, so a region found like this is not asked
66
+ * about again.
67
+ */
68
+ export type RigidRegions = WeakSet<HTMLElement>;
69
+ /**
70
+ * The height a widget needs: the one at which none of its scrolling regions has to scroll. `boxHeight` is the height of
71
+ * the box the widget is in now; the answer is that plus what the regions are short of (or minus the room they have to
72
+ * spare), so it comes out the same however far a change of height has got. It is null when the box has no size (hidden).
73
+ */
74
+ export declare function measureNaturalHeight(root: ParentNode, boxHeight: number, rigidRegions?: RigidRegions): number | null;
75
+ /**
76
+ * The height a widget needs, found as `measureNaturalHeight` finds it and then tried out: the box is given that height for
77
+ * a moment and each region says how much of the change it took. A region that took none (a list with a `max-height`, a
78
+ * fixed `height`) is left out from then on; a region that took part of it (a list that stopped growing at its
79
+ * `max-height`) counts for what it took. Without this a box asked to grow for a list that cannot grow would grow at every
80
+ * look, up to its maximum, and leave the widget in a box of empty space.
81
+ */
82
+ export declare function measureProvenHeight(root: ParentNode, box: HTMLElement, boxHeight: number, settings: Pick<EmbedAutoscaleSettings, "floorHeight" | "maxHeight" | "threshold">, rigidRegions: RigidRegions): number | null;
83
+ export interface HeightFollowerOptions {
84
+ /** The `<widgetic>` tag: the page's `widgetic:autoscale` listeners hear changes here. */
85
+ host: HTMLElement;
86
+ /** The element that has the height: the widget's box, or the iframe. */
87
+ box: HTMLElement;
88
+ compositionId: string;
89
+ settings: EmbedAutoscaleSettings;
90
+ /** The height the box has before autoscale, in pixels: the height its tag asked for. */
91
+ startHeight: number;
92
+ /** What `style.height` of the box was before autoscale, put back when the box is as tall as the tag asked for (in the unit it asked in). */
93
+ originalHeightCss: string;
94
+ }
95
+ export interface HeightFollower {
96
+ /** The height the box has now, in pixels (the height of its tag until it is given another). */
97
+ currentHeight(): number;
98
+ /** Gives the box the height that fits `naturalHeight` when that is worth a change. Returns whether the box changed. */
99
+ follow(naturalHeight: number): boolean;
100
+ /** Starts at the height this composition had the last time it was shown, when that was taller than the floor. */
101
+ startAtStoredHeight(): boolean;
102
+ /** Whether the box is still on its way to the height it was last given (it is not tried out or measured until it is there). */
103
+ isAnimating(): boolean;
104
+ }
105
+ /** Whether a new height is different enough from the one shown to be worth following. */
106
+ export declare function isChangeWorthFollowing(currentHeight: number, nextHeight: number, threshold: number): boolean;
107
+ export declare function createHeightFollower(options: HeightFollowerOptions): HeightFollower;
108
+ export interface DirectAutoscaleOptions {
109
+ /** The `<widgetic>` tag. */
110
+ host: HTMLElement;
111
+ /** The box the SDK made for the widget (`div[data-widgetic-direct]`), already in the page. */
112
+ box: HTMLElement;
113
+ /** The shadow root of the box, where the widget is. */
114
+ shadowRoot: ShadowRoot;
115
+ compositionId: string;
116
+ /** The height of the tag in pixels when the browser cannot say how tall the box is (the tag is not shown yet). */
117
+ fallbackHeightPixels: number;
118
+ }
119
+ export interface AutoscaleHandle {
120
+ /** Looks at the widget again, soon (changes close together are followed once). */
121
+ refresh(): void;
122
+ /** Stops following. The box keeps the height it has. */
123
+ stop(): void;
124
+ }
125
+ export declare function startDirectAutoscale(options: DirectAutoscaleOptions): AutoscaleHandle;
126
+ /** Stops following the iframe of this tag, if it is being followed. */
127
+ export declare function stopFramedAutoscale(host: HTMLElement): void;
128
+ export interface FramedAutoscaleOptions {
129
+ host: HTMLElement;
130
+ iframe: HTMLIFrameElement;
131
+ compositionId: string;
132
+ /** The height of the tag in pixels when the browser cannot say how tall the iframe is (the tag is not shown yet). */
133
+ fallbackHeightPixels: number;
134
+ }
135
+ /**
136
+ * The iframe of this tag is as tall as its widget says it is. The widget says it with `widgetic:resize` (`detail.height`
137
+ * in pixels), which reaches the tag as an event. A widget that does not say keeps the height of its tag.
138
+ */
139
+ export declare function startFramedAutoscale(options: FramedAutoscaleOptions): AutoscaleHandle;
@@ -0,0 +1,29 @@
1
+ /**
2
+ * Small helpers for the calls the SDK makes to the gateway's authenticated routes through the generated API client.
3
+ */
4
+ /**
5
+ * A new `Idempotency-Key` for one call.
6
+ *
7
+ * The gateway refuses a POST or a PUT on the content routes that carries none (400 `VALIDATION_FIELD_REQUIRED`,
8
+ * "Idempotency-Key header is required"), including the check that saves nothing, and it accepts 8 to 50 letters, digits,
9
+ * dashes and underscores. A UUID fits. `crypto.randomUUID` is missing in older browsers and outside secure contexts, so
10
+ * the fallback builds a version 4 shaped key from `Math.random`: the gateway only compares keys, it does not need them
11
+ * to be unguessable, and a key is never reused for a second call (a reused key would replay the first answer).
12
+ */
13
+ export declare function createIdempotencyKey(): string;
14
+ /**
15
+ * The part of a gateway answer that holds the result.
16
+ *
17
+ * The gateway wraps an answer as `{ success, data }`. This returns `data` when the answer has one and the answer itself
18
+ * when it does not (an operation the gateway answers unwrapped), so a caller reads the same fields either way.
19
+ */
20
+ export declare function unwrapGatewayAnswer(answer: Record<string, unknown>): Record<string, unknown>;
21
+ /**
22
+ * The result of a call made through the generated client's `...Raw` method, as the gateway sent it.
23
+ *
24
+ * The client's typed value is not used for these operations: it keeps only the fields its model names at the top of the
25
+ * body, and for `validateCompositionContent` and `setDynamicContent` the model describes what is inside `data` while
26
+ * the gateway sends it wrapped (`{ success, data }`), so `valid` and `validationResult` came back missing and every
27
+ * check read as invalid. An answer that is not a JSON object is read as empty.
28
+ */
29
+ export declare function readGatewayAnswer(rawResponse: Response): Promise<Record<string, unknown>>;
@@ -1,11 +1,17 @@
1
1
  /**
2
2
  * Hydrate customer `<widgetic composition-id>` in place.
3
- * Customer tag is one word: `<widgetic>`. No `<widgetic-widget>`, no render-mode.
3
+ * Customer tag is one word: `<widgetic>`. No `<widgetic-widget>`.
4
4
  *
5
5
  * Copy iframe = raw `<iframe src>` without SDK.
6
6
  * Copy web component = SDK + `<widgetic composition-id>`. When the published
7
7
  * version has a direct module, the SDK mounts it in a shadow root. A version
8
- * with only widget.html asks for a republish and does not insert an iframe.
8
+ * with only widget.html asks for a republish and does not insert an iframe
9
+ * (`render-mode="iframe"` on the tag asks for the iframe).
10
+ *
11
+ * The box of either is as big as the tag says. A tag that also says `autoscale`
12
+ * gets a box that follows the height of the widget (embed-autoscale.ts): the
13
+ * list the widget measures for a mount in the page, the widget's own
14
+ * `widgetic:resize` for an iframe.
9
15
  */
10
16
  import { REFUSED_HOST_ATTRIBUTE } from "./host-bridge-markers.js";
11
17
  export { REFUSED_HOST_ATTRIBUTE };
@@ -45,6 +45,34 @@ export declare function updateDirectMount(host: HTMLElement, nextOverlay: {
45
45
  contentItems?: unknown[];
46
46
  }): boolean;
47
47
  export declare function destroyDirectMount(host: HTMLElement): void;
48
+ /**
49
+ * The size the iframe of the same tag gets when the embed code names none (`mountIframeInto` in
50
+ * hydrate-published-host.ts passes "400" and "300"). A widget mounted in the page has the box it would have had in the
51
+ * frame, whichever way the tag is rendered, so removing `render-mode="iframe"` does not change how big the widget is.
52
+ */
53
+ export declare const DIRECT_BOX_DEFAULTS: {
54
+ readonly WIDTH_PIXELS: 400;
55
+ readonly HEIGHT_PIXELS: 300;
56
+ };
57
+ /**
58
+ * The CSS length for a `width` or `height` of an embed code. An iframe reads `height="405"` as 405px and `width="100%"`
59
+ * as a percentage; the `div` that is the box of a widget mounted in the page reads neither, so the box says it in CSS.
60
+ * A value that is not a number or a number with a unit gives the fallback, in pixels.
61
+ */
62
+ export declare function cssLengthOfEmbedAttribute(value: string | null | undefined, fallbackPixels: number): string;
63
+ /**
64
+ * The number of pixels a `width` or `height` of an embed code stands for when it is a plain number or a number of
65
+ * pixels (`405`, `405px`), or the fallback for anything else (a percentage has no size until the box is in the page).
66
+ */
67
+ export declare function pixelsOfEmbedAttribute(value: string | null | undefined, fallbackPixels: number): number;
68
+ /**
69
+ * The rules, in the shadow root and ahead of the module's own, that make the mount target what `#app.widgetic-root-el`
70
+ * is in the widget's frame page: it fills the box, and so does the first thing the module puts in it (the widget's root;
71
+ * a second node, such as a portal container, keeps its own size). A rule of the module's own with the same weight,
72
+ * written after these, wins. A module built before this has none of these rules of its own, which is why the SDK has
73
+ * them and not only newer builds.
74
+ */
75
+ export declare const DIRECT_BOX_STYLES = ".widgetic-direct-target { width: 100%; height: 100%; }\n.widgetic-direct-target > :first-child { width: 100%; height: 100%; min-width: 0; min-height: 0; }\n";
48
76
  /**
49
77
  * Loads the module and mounts it. Returns false when the module is missing,
50
78
  * the contract is not 2, the load fails, or the host changed while loading.
@@ -4,8 +4,14 @@
4
4
  *
5
5
  * Order:
6
6
  * 1. <script data-api-url> / window.WIDGETIC_EMBED_API (explicit override: local runs, tests)
7
- * 2. CDN lookup script (no CORS — works on CodePen)
8
- * 3. getApiUrl() / api.widgetic.com (new platform API)
7
+ * 2. getApiUrl() / api.widgetic.com (new platform API): its answer carries the embed's address, its entries and its
8
+ * adapters, and is read as soon as it comes
9
+ * 3. The CDN copy of the address (a lookup script, no CORS: it works on CodePen), for a gateway that gave no answer. A
10
+ * copy the page already holds (the script's global is set) is known before step 2 and costs nothing; one that is not
11
+ * there is requested only after step 2. Asked first, it is a round trip made before the gateway's own, and where the
12
+ * CDN holds no copy it answers 404 with an HTML page (checked on 27 October 2026 for two widgets, a quarter of a
13
+ * second each) that the browser refuses as a script (`net::ERR_BLOCKED_BY_ORB`): the wait comes before every embed,
14
+ * and the failed request shows in the console of the customer's page.
9
15
  *
10
16
  * api.widgetic.com is the new API host. Legacy REST is widgetic.com/api/v2.
11
17
  * The development gateways (the Render service, localhost:3000) are no longer
@@ -12,6 +12,12 @@ export interface AbGoalAssignment {
12
12
  }
13
13
  /** The capability a widget lists in `widgetic:ready` when it reports which element of a goal was used. */
14
14
  export declare const GOAL_REPORTER_CAPABILITY = "goal-reporter";
15
+ /** What the page changes in a running widget (`widgetic:update`): its design, its content, its list of items. */
16
+ interface WidgetUpdate {
17
+ design?: Record<string, string>;
18
+ content?: Record<string, unknown>;
19
+ contentItems?: unknown[];
20
+ }
15
21
  declare class PublishedHostBridge {
16
22
  private readonly host;
17
23
  private readonly iframe;
@@ -19,6 +25,7 @@ declare class PublishedHostBridge {
19
25
  private readonly compositionId;
20
26
  private readonly services?;
21
27
  private readyDispatched;
28
+ private pendingWidgetUpdate;
22
29
  private latestAbGoal;
23
30
  private latestWorkflowWatch;
24
31
  private attributeFlushScheduled;
@@ -42,15 +49,29 @@ declare class PublishedHostBridge {
42
49
  */
43
50
  sendWorkflowWatch(watch: WorkflowWatch): void;
44
51
  private postWorkflowWatch;
45
- sendWidgetUpdate(payload: {
46
- design?: Record<string, string>;
47
- content?: Record<string, unknown>;
48
- contentItems?: unknown[];
49
- }): void;
52
+ sendWidgetUpdate(payload: WidgetUpdate): void;
53
+ /** Sends the update the page asked for while the frame was blank, if there is one and the frame can take it now. */
54
+ private flushPendingWidgetUpdate;
55
+ /**
56
+ * Whether the frame can be written to. A frame that holds only its blank first document is on the page's own origin,
57
+ * so it refuses every message addressed to the gateway, with a warning in the customer's console (see
58
+ * `iframeStillBlank`).
59
+ */
60
+ private frameCanReceive;
50
61
  private handleWrapperMessage;
51
62
  private dispatchHostEvent;
52
63
  destroy(): void;
53
64
  }
65
+ /**
66
+ * True while the iframe still holds its initial blank document. A message addressed to the gateway has nowhere to go
67
+ * then: that window's origin is the page's own, not the gateway's, so the browser refuses it with a warning in the
68
+ * customer's console. Every default embed code met it (the page's own change of the host, such as the SDK marking it
69
+ * mounted, sent a widget update a moment after the frame was added). The bridge holds its snapshot, goal, watch and
70
+ * updates back while this is true; the `load` listener and `widgetic:ready` send them once the frame page is there. A frame
71
+ * that has gone on to the gateway is cross-origin and refuses to say where it is, and so does anything else that cannot be
72
+ * read: those are treated as loaded, which is what the bridge did before.
73
+ */
74
+ export declare function iframeStillBlank(iframe: HTMLIFrameElement): boolean;
54
75
  /**
55
76
  * Attaches the host bridge for a published iframe mount.
56
77
  *
@@ -33,3 +33,10 @@ export declare const WORKFLOW_SHARED_CONTRACT_VERSION = 1;
33
33
  export declare const WORKFLOW_SHARED_SERVICES_GLOBAL = "__widgeticEmbedSharedServices";
34
34
  /** Where the workflow code leaves what it offers to the SDK. */
35
35
  export declare const WORKFLOW_EXPORTS_GLOBAL = "__widgeticEmbedWorkflows";
36
+ /**
37
+ * Marks a stage: a composition the workflow code built for a workflow. The workflow code writes it on the `<widgetic>`
38
+ * element it makes (src/workflows/workflow-stage.ts), and the SDK reads it when it mounts the widget in that element:
39
+ * a stage is as tall as its widget, and the viewport follows that, so the SDK must not give it a box of a fixed size.
40
+ * It lives here because both files need the same name and this is the one module they share.
41
+ */
42
+ export declare const WORKFLOW_STAGE_ATTRIBUTE = "data-widgetic-workflow-stage";
@@ -18,7 +18,7 @@
18
18
  */
19
19
  /** Marks the viewport the SDK puts on a tag. */
20
20
  export declare const VIEWPORT_ATTRIBUTE = "data-widgetic-workflow-viewport";
21
- /** Marks a stage: a composition built for a workflow. */
21
+ /** Marks a stage: a composition built for a workflow (the name is shared with the SDK, see workflow-shared-contract.ts). */
22
22
  export declare const STAGE_ATTRIBUTE = "data-widgetic-workflow-stage";
23
23
  /** Tells the viewport a stage has this height now. */
24
24
  export type HeightReport = (entries: Array<{