@memberjunction/ng-realtime-channels 0.0.0 → 6.2.0-edge.4

package/dist/lib/dom-frame-capture.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @fileoverview The default, opt-in DOM rasterizer for realtime channels: turns a rendered
+ * component's DOM subtree into a JPEG so a video-capable model can SEE it (used by the Interactive Component channel and by
+ * channels built with the Angular adapter).
+ *
+ * It is built on `html-to-image` (MIT; already a dependency of MJ Explorer for pin thumbnails). That library draws the
+ * subtree through an SVG `foreignObject`, so the browser's own CSS engine renders it, which matters because MJ's design
+ * tokens use `color-mix()` and similar that canvas-based rasterizers cannot parse. It runs in the main thread and clones
+ * the subtree synchronously, so this module bounds the work (node cap, timeout, one capture at a time, a size ceiling).
+ *
+ * Nothing here is on by default. A host that wants the agent to see components calls
+ * {@link EnableChannelFrameCapture} once, before a realtime session is minted (Explorer does; an embeddable
+ * element exposes it as a flag). The base channel's visual pump decides WHEN to capture (change-driven, paced to the
+ * negotiated rate, deduplicated, only while exposure is `pixels` and a video track is up) and tags each frame with the change id
+ * of the state it shows; this module only decides what a frame looks like and fails soft.
+ *
+ * **Failure is soft and loud once.** Cross-origin images, tainted canvases and fonts that cannot be read make a rasterizer
+ * throw or hang. The first such failure is logged ONCE with its reason; a failure that cannot succeed on retry (a security
+ * error) disables capture for the rest of the session, and repeated transient failures (timeouts) do the same. The channel
+ * then simply stays at state-only: the model keeps getting state notes, never an error.
+ *
+ * @module @memberjunction/ng-realtime-channels
+ */
+import { type ElementFrameCapturer } from './channel-frame-capture';
+/** Renders an element to a JPEG data URL; the shape of `html-to-image`'s `toJpeg`, so a test can supply a fake. */
+export type DomRasterizer = (element: HTMLElement, options: DomRasterizerOptions) => Promise<string>;
+/** The options this module passes to a {@link DomRasterizer} (a subset of `html-to-image`'s own). */
+export interface DomRasterizerOptions {
+    /** JPEG quality, 0 to 1. */
+    quality: number;
+    /** Scale applied to the element's own size, so the longest edge is at most {@link DomFrameCaptureOptions.MaxEdgePx}. */
+    pixelRatio: number;
+    /** The color behind transparent areas (JPEG has no alpha). */
+    backgroundColor: string;
+    /** Skip embedding web fonts: they add seconds and cross-origin failures, and the model does not need the typeface. */
+    skipFonts: boolean;
+}
+/** Options for {@link CreateDomFrameCapturer}. */
+export interface DomFrameCaptureOptions {
+    /** JPEG quality, 0 to 1. Default 0.6 (a frame of a dashboard is roughly 40 to 120 KB). */
+    Quality?: number;
+    /** The longest edge of the frame, in pixels; larger elements are scaled down. Default 1024. */
+    MaxEdgePx?: number;
+    /** Elements with more descendants than this are not rasterized (the synchronous clone would freeze the page). Default 3000. */
+    MaxNodes?: number;
+    /** How long to wait for one capture before giving up on it. Default 4000 ms. */
+    TimeoutMs?: number;
+    /** Consecutive transient failures (timeouts, unknown errors) after which capture is disabled for the session. Default 3. */
+    MaxConsecutiveFailures?: number;
+    /** The rasterizer. Default: `html-to-image`'s `toJpeg`. */
+    Rasterize?: DomRasterizer;
+    /** Called once, with the reason, the first time capture is degraded. Default: `console.warn`. */
+    OnDegraded?: (reason: string) => void;
+}
+/**
+ * Builds a {@link ElementFrameCapturer} that rasterizes an element to a base64 JPEG (no data-URL prefix).
+ *
+ * The returned function never throws. It returns `null` (so the pump sends no frame) when the element has no size, is too
+ * large, a capture is already in flight, a capture times out or fails, or capture has been disabled after repeated or
+ * permanent failure; in the last two cases the reason is reported once through `OnDegraded`.
+ *
+ * @param options Tuning and test seams.
+ */
+export declare function CreateDomFrameCapturer(options?: DomFrameCaptureOptions): ElementFrameCapturer;
+/**
+ * Turns on picture capture of channel surfaces for this host: registers the default rasterizer. Call it once at startup, BEFORE a realtime session is minted (whether the channel can source a video track is
+ * decided at mint). Hosts opt in: MJ Explorer calls it; an embeddable element calls it only when its flag is set.
+ *
+ * @param options Tuning and test seams.
+ * @returns A function that removes the registration.
+ */
+export declare function EnableChannelFrameCapture(options?: DomFrameCaptureOptions): () => void;
+//# sourceMappingURL=dom-frame-capture.d.ts.map

package/dist/lib/dom-frame-capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom-frame-capture.d.ts","sourceRoot":"","sources":["../../src/lib/dom-frame-capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EAAuB,KAAK,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAEzF,mHAAmH;AACnH,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,oBAAoB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAErG,qGAAqG;AACrG,MAAM,WAAW,oBAAoB;IACjC,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,wHAAwH;IACxH,UAAU,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,eAAe,EAAE,MAAM,CAAC;IACxB,sHAAsH;IACtH,SAAS,EAAE,OAAO,CAAC;CACtB;AAED,kDAAkD;AAClD,MAAM,WAAW,sBAAsB;IACnC,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+FAA+F;IAC/F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+HAA+H;IAC/H,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4HAA4H;IAC5H,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,2DAA2D;IAC3D,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,iGAAiG;IACjG,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAkDD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,sBAA2B,GAAG,oBAAoB,CAqDjG;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,GAAE,sBAA2B,GAAG,MAAM,IAAI,CAG1F"}

package/dist/lib/dom-frame-capture.js

@@ -0,0 +1,135 @@
+/**
+ * @fileoverview The default, opt-in DOM rasterizer for realtime channels: turns a rendered
+ * component's DOM subtree into a JPEG so a video-capable model can SEE it (used by the Interactive Component channel and by
+ * channels built with the Angular adapter).
+ *
+ * It is built on `html-to-image` (MIT; already a dependency of MJ Explorer for pin thumbnails). That library draws the
+ * subtree through an SVG `foreignObject`, so the browser's own CSS engine renders it, which matters because MJ's design
+ * tokens use `color-mix()` and similar that canvas-based rasterizers cannot parse. It runs in the main thread and clones
+ * the subtree synchronously, so this module bounds the work (node cap, timeout, one capture at a time, a size ceiling).
+ *
+ * Nothing here is on by default. A host that wants the agent to see components calls
+ * {@link EnableChannelFrameCapture} once, before a realtime session is minted (Explorer does; an embeddable
+ * element exposes it as a flag). The base channel's visual pump decides WHEN to capture (change-driven, paced to the
+ * negotiated rate, deduplicated, only while exposure is `pixels` and a video track is up) and tags each frame with the change id
+ * of the state it shows; this module only decides what a frame looks like and fails soft.
+ *
+ * **Failure is soft and loud once.** Cross-origin images, tainted canvases and fonts that cannot be read make a rasterizer
+ * throw or hang. The first such failure is logged ONCE with its reason; a failure that cannot succeed on retry (a security
+ * error) disables capture for the rest of the session, and repeated transient failures (timeouts) do the same. The channel
+ * then simply stays at state-only: the model keeps getting state notes, never an error.
+ *
+ * @module @memberjunction/ng-realtime-channels
+ */
+import { toJpeg } from 'html-to-image';
+import { ChannelFrameCapture } from './channel-frame-capture';
+const DEFAULTS = { Quality: 0.6, MaxEdgePx: 1024, MaxNodes: 3000, TimeoutMs: 4000, MaxConsecutiveFailures: 3 };
+/** The data-URL prefix a JPEG from the rasterizer starts with. */
+const JPEG_DATA_URL_PREFIX = 'data:image/jpeg;base64,';
+/** A background color to put behind transparent areas: the nearest ancestor that paints one, else white. */
+function resolveBackground(element) {
+    for (let node = element; node; node = node.parentElement) {
+        const color = getComputedStyle(node).backgroundColor;
+        if (color && color !== 'transparent' && !/^rgba\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*,\s*0\s*\)$/.test(color)) {
+            return color;
+        }
+    }
+    return '#ffffff';
+}
+/** Whether an error is one that cannot succeed on retry in this page (a tainted canvas or blocked cross-origin read). */
+function isPermanentFailure(error) {
+    const name = error instanceof Error ? error.name : '';
+    const message = error instanceof Error ? error.message : String(error);
+    return name === 'SecurityError' || /tainted|cross-origin|insecure|not allowed to load/i.test(message);
+}
+/** A readable reason for a failure. */
+function describeFailure(error) {
+    if (isPermanentFailure(error)) {
+        return `the page's content cannot be read for a picture (cross-origin images or a tainted canvas): ${error instanceof Error ? error.message : String(error)}`;
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+/** Resolves to `undefined` if the promise has not settled within `ms`; the work itself is not cancelled. */
+function withTimeout(promise, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => resolve(undefined), ms);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
+/**
+ * Builds a {@link ElementFrameCapturer} that rasterizes an element to a base64 JPEG (no data-URL prefix).
+ *
+ * The returned function never throws. It returns `null` (so the pump sends no frame) when the element has no size, is too
+ * large, a capture is already in flight, a capture times out or fails, or capture has been disabled after repeated or
+ * permanent failure; in the last two cases the reason is reported once through `OnDegraded`.
+ *
+ * @param options Tuning and test seams.
+ */
+export function CreateDomFrameCapturer(options = {}) {
+    const quality = options.Quality ?? DEFAULTS.Quality;
+    const maxEdge = options.MaxEdgePx ?? DEFAULTS.MaxEdgePx;
+    const maxNodes = options.MaxNodes ?? DEFAULTS.MaxNodes;
+    const timeoutMs = options.TimeoutMs ?? DEFAULTS.TimeoutMs;
+    const maxFailures = options.MaxConsecutiveFailures ?? DEFAULTS.MaxConsecutiveFailures;
+    const rasterize = options.Rasterize ?? ((element, rasterOptions) => toJpeg(element, rasterOptions));
+    const report = options.OnDegraded ?? ((reason) => console.warn(`[RealtimeChannels] ${reason}`));
+    let disabled = false;
+    let inFlight = false;
+    let failures = 0;
+    const disable = (reason) => {
+        if (!disabled) {
+            disabled = true;
+            report(`Picture capture of components is off for this session; the agent keeps receiving state only. Reason: ${reason}`);
+        }
+    };
+    return async (element) => {
+        if (disabled || inFlight || element.clientWidth === 0 || element.clientHeight === 0) {
+            return null;
+        }
+        if (element.getElementsByTagName('*').length > maxNodes) {
+            return null;
+        }
+        inFlight = true;
+        try {
+            const ratio = Math.min(1, maxEdge / Math.max(element.clientWidth, element.clientHeight));
+            const dataUrl = await withTimeout(rasterize(element, { quality, pixelRatio: ratio, backgroundColor: resolveBackground(element), skipFonts: true }), timeoutMs);
+            if (dataUrl === undefined) {
+                failures++;
+                if (failures >= maxFailures) {
+                    disable(`capturing took longer than ${timeoutMs} ms, ${failures} times in a row`);
+                }
+                return null;
+            }
+            failures = 0;
+            return dataUrl.startsWith(JPEG_DATA_URL_PREFIX) ? dataUrl.slice(JPEG_DATA_URL_PREFIX.length) : null;
+        }
+        catch (error) {
+            failures++;
+            if (isPermanentFailure(error) || failures >= maxFailures) {
+                disable(describeFailure(error));
+            }
+            return null;
+        }
+        finally {
+            inFlight = false;
+        }
+    };
+}
+/**
+ * Turns on picture capture of channel surfaces for this host: registers the default rasterizer. Call it once at startup, BEFORE a realtime session is minted (whether the channel can source a video track is
+ * decided at mint). Hosts opt in: MJ Explorer calls it; an embeddable element calls it only when its flag is set.
+ *
+ * @param options Tuning and test seams.
+ * @returns A function that removes the registration.
+ */
+export function EnableChannelFrameCapture(options = {}) {
+    ChannelFrameCapture.Instance.Register(CreateDomFrameCapturer(options));
+    return () => ChannelFrameCapture.Instance.Register(null);
+}
+//# sourceMappingURL=dom-frame-capture.js.map

package/dist/lib/dom-frame-capture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom-frame-capture.js","sourceRoot":"","sources":["../../src/lib/dom-frame-capture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,OAAO,EAAE,mBAAmB,EAA6B,MAAM,yBAAyB,CAAC;AAmCzF,MAAM,QAAQ,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,sBAAsB,EAAE,CAAC,EAAW,CAAC;AAExH,kEAAkE;AAClE,MAAM,oBAAoB,GAAG,yBAAyB,CAAC;AAEvD,4GAA4G;AAC5G,SAAS,iBAAiB,CAAC,OAAoB;IAC3C,KAAK,IAAI,IAAI,GAAuB,OAAO,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;QAC3E,MAAM,KAAK,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC,eAAe,CAAC;QACrD,IAAI,KAAK,IAAI,KAAK,KAAK,aAAa,IAAI,CAAC,iDAAiD,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACrG,OAAO,KAAK,CAAC;QACjB,CAAC;IACL,CAAC;IACD,OAAO,SAAS,CAAC;AACrB,CAAC;AAED,yHAAyH;AACzH,SAAS,kBAAkB,CAAC,KAAc;IACtC,MAAM,IAAI,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IACtD,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,OAAO,IAAI,KAAK,eAAe,IAAI,oDAAoD,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AAC1G,CAAC;AAED,uCAAuC;AACvC,SAAS,eAAe,CAAC,KAAc;IACnC,IAAI,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,8FAA8F,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;IAClK,CAAC;IACD,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAClE,CAAC;AAED,4GAA4G;AAC5G,SAAS,WAAW,CAAI,OAAmB,EAAE,EAAU;IACnD,OAAO,IAAI,OAAO,CAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAClD,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC,CAAC;QACvD,OAAO,CAAC,IAAI,CACR,CAAC,KAAK,EAAE,EAAE;YACN,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,OAAO,CAAC,KAAK,CAAC,CAAC;QACnB,CAAC,EACD,CAAC,KAAc,EAAE,EAAE;YACf,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,MAAM,CAAC,KAAK,CAAC,CAAC;QAClB,CAAC,CACJ,CAAC;IACN,CAAC,CAAC,CAAC;AACP,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CAAC,UAAkC,EAAE;IACvE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,QAAQ,CAAC,OAAO,CAAC;IACpD,MAAM,OAAO,GAAG,OAAO,CAAC,SAAS,IAAI,QAAQ,CAAC,SAAS,CAAC;IACxD,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,QAAQ,CAAC,QAAQ,CAAC;IACvD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,QAAQ,CAAC,SAAS,CAAC;IAC1D,MAAM,WAAW,GAAG,OAAO,CAAC,sBAAsB,IAAI,QAAQ,CAAC,sBAAsB,CAAC;IACtF,MAAM,SAAS,GAAkB,OAAO,CAAC,SAAS,IAAI,CAAC,CAAC,OAAO,EAAE,aAAa,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC;IACnH,MAAM,MAAM,GAAG,OAAO,CAAC,UAAU,IAAI,CAAC,CAAC,MAAc,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,sBAAsB,MAAM,EAAE,CAAC,CAAC,CAAC;IAExG,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,IAAI,QAAQ,GAAG,CAAC,CAAC;IAEjB,MAAM,OAAO,GAAG,CAAC,MAAc,EAAQ,EAAE;QACrC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACZ,QAAQ,GAAG,IAAI,CAAC;YAChB,MAAM,CAAC,wGAAwG,MAAM,EAAE,CAAC,CAAC;QAC7H,CAAC;IACL,CAAC,CAAC;IAEF,OAAO,KAAK,EAAE,OAAoB,EAA0B,EAAE;QAC1D,IAAI,QAAQ,IAAI,QAAQ,IAAI,OAAO,CAAC,WAAW,KAAK,CAAC,IAAI,OAAO,CAAC,YAAY,KAAK,CAAC,EAAE,CAAC;YAClF,OAAO,IAAI,CAAC;QAChB,CAAC;QACD,IAAI,OAAO,CAAC,oBAAoB,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,QAAQ,EAAE,CAAC;YACtD,OAAO,IAAI,CAAC;QAChB,CAAC;QACD,QAAQ,GAAG,IAAI,CAAC;QAChB,IAAI,CAAC;YACD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC;YACzF,MAAM,OAAO,GAAG,MAAM,WAAW,CAC7B,SAAS,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,eAAe,EAAE,iBAAiB,CAAC,OAAO,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,EAChH,SAAS,CACZ,CAAC;YACF,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBACxB,QAAQ,EAAE,CAAC;gBACX,IAAI,QAAQ,IAAI,WAAW,EAAE,CAAC;oBAC1B,OAAO,CAAC,8BAA8B,SAAS,QAAQ,QAAQ,iBAAiB,CAAC,CAAC;gBACtF,CAAC;gBACD,OAAO,IAAI,CAAC;YAChB,CAAC;YACD,QAAQ,GAAG,CAAC,CAAC;YACb,OAAO,OAAO,CAAC,UAAU,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACxG,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,QAAQ,EAAE,CAAC;YACX,IAAI,kBAAkB,CAAC,KAAK,CAAC,IAAI,QAAQ,IAAI,WAAW,EAAE,CAAC;gBACvD,OAAO,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC;YACpC,CAAC;YACD,OAAO,IAAI,CAAC;QAChB,CAAC;gBAAS,CAAC;YACP,QAAQ,GAAG,KAAK,CAAC;QACrB,CAAC;IACL,CAAC,CAAC;AACN,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB,CAAC,UAAkC,EAAE;IAC1E,mBAAmB,CAAC,QAAQ,CAAC,QAAQ,CAAC,sBAAsB,CAAC,OAAO,CAAC,CAAC,CAAC;IACvE,OAAO,GAAG,EAAE,CAAC,mBAAmB,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAC7D,CAAC","sourcesContent":["/**\n * @fileoverview The default, opt-in DOM rasterizer for realtime channels: turns a rendered\n * component's DOM subtree into a JPEG so a video-capable model can SEE it (used by the Interactive Component channel and by\n * channels built with the Angular adapter).\n *\n * It is built on `html-to-image` (MIT; already a dependency of MJ Explorer for pin thumbnails). That library draws the\n * subtree through an SVG `foreignObject`, so the browser's own CSS engine renders it, which matters because MJ's design\n * tokens use `color-mix()` and similar that canvas-based rasterizers cannot parse. It runs in the main thread and clones\n * the subtree synchronously, so this module bounds the work (node cap, timeout, one capture at a time, a size ceiling).\n *\n * Nothing here is on by default. A host that wants the agent to see components calls\n * {@link EnableChannelFrameCapture} once, before a realtime session is minted (Explorer does; an embeddable\n * element exposes it as a flag). The base channel's visual pump decides WHEN to capture (change-driven, paced to the\n * negotiated rate, deduplicated, only while exposure is `pixels` and a video track is up) and tags each frame with the change id\n * of the state it shows; this module only decides what a frame looks like and fails soft.\n *\n * **Failure is soft and loud once.** Cross-origin images, tainted canvases and fonts that cannot be read make a rasterizer\n * throw or hang. The first such failure is logged ONCE with its reason; a failure that cannot succeed on retry (a security\n * error) disables capture for the rest of the session, and repeated transient failures (timeouts) do the same. The channel\n * then simply stays at state-only: the model keeps getting state notes, never an error.\n *\n * @module @memberjunction/ng-realtime-channels\n */\n\nimport { toJpeg } from 'html-to-image';\nimport { ChannelFrameCapture, type ElementFrameCapturer } from './channel-frame-capture';\n\n/** Renders an element to a JPEG data URL; the shape of `html-to-image`'s `toJpeg`, so a test can supply a fake. */\nexport type DomRasterizer = (element: HTMLElement, options: DomRasterizerOptions) => Promise<string>;\n\n/** The options this module passes to a {@link DomRasterizer} (a subset of `html-to-image`'s own). */\nexport interface DomRasterizerOptions {\n    /** JPEG quality, 0 to 1. */\n    quality: number;\n    /** Scale applied to the element's own size, so the longest edge is at most {@link DomFrameCaptureOptions.MaxEdgePx}. */\n    pixelRatio: number;\n    /** The color behind transparent areas (JPEG has no alpha). */\n    backgroundColor: string;\n    /** Skip embedding web fonts: they add seconds and cross-origin failures, and the model does not need the typeface. */\n    skipFonts: boolean;\n}\n\n/** Options for {@link CreateDomFrameCapturer}. */\nexport interface DomFrameCaptureOptions {\n    /** JPEG quality, 0 to 1. Default 0.6 (a frame of a dashboard is roughly 40 to 120 KB). */\n    Quality?: number;\n    /** The longest edge of the frame, in pixels; larger elements are scaled down. Default 1024. */\n    MaxEdgePx?: number;\n    /** Elements with more descendants than this are not rasterized (the synchronous clone would freeze the page). Default 3000. */\n    MaxNodes?: number;\n    /** How long to wait for one capture before giving up on it. Default 4000 ms. */\n    TimeoutMs?: number;\n    /** Consecutive transient failures (timeouts, unknown errors) after which capture is disabled for the session. Default 3. */\n    MaxConsecutiveFailures?: number;\n    /** The rasterizer. Default: `html-to-image`'s `toJpeg`. */\n    Rasterize?: DomRasterizer;\n    /** Called once, with the reason, the first time capture is degraded. Default: `console.warn`. */\n    OnDegraded?: (reason: string) => void;\n}\n\nconst DEFAULTS = { Quality: 0.6, MaxEdgePx: 1024, MaxNodes: 3000, TimeoutMs: 4000, MaxConsecutiveFailures: 3 } as const;\n\n/** The data-URL prefix a JPEG from the rasterizer starts with. */\nconst JPEG_DATA_URL_PREFIX = 'data:image/jpeg;base64,';\n\n/** A background color to put behind transparent areas: the nearest ancestor that paints one, else white. */\nfunction resolveBackground(element: HTMLElement): string {\n    for (let node: HTMLElement | null = element; node; node = node.parentElement) {\n        const color = getComputedStyle(node).backgroundColor;\n        if (color && color !== 'transparent' && !/^rgba\\(\\s*\\d+\\s*,\\s*\\d+\\s*,\\s*\\d+\\s*,\\s*0\\s*\\)$/.test(color)) {\n            return color;\n        }\n    }\n    return '#ffffff';\n}\n\n/** Whether an error is one that cannot succeed on retry in this page (a tainted canvas or blocked cross-origin read). */\nfunction isPermanentFailure(error: unknown): boolean {\n    const name = error instanceof Error ? error.name : '';\n    const message = error instanceof Error ? error.message : String(error);\n    return name === 'SecurityError' || /tainted|cross-origin|insecure|not allowed to load/i.test(message);\n}\n\n/** A readable reason for a failure. */\nfunction describeFailure(error: unknown): string {\n    if (isPermanentFailure(error)) {\n        return `the page's content cannot be read for a picture (cross-origin images or a tainted canvas): ${error instanceof Error ? error.message : String(error)}`;\n    }\n    return error instanceof Error ? error.message : String(error);\n}\n\n/** Resolves to `undefined` if the promise has not settled within `ms`; the work itself is not cancelled. */\nfunction withTimeout<T>(promise: Promise<T>, ms: number): Promise<T | undefined> {\n    return new Promise<T | undefined>((resolve, reject) => {\n        const timer = setTimeout(() => resolve(undefined), ms);\n        promise.then(\n            (value) => {\n                clearTimeout(timer);\n                resolve(value);\n            },\n            (error: unknown) => {\n                clearTimeout(timer);\n                reject(error);\n            }\n        );\n    });\n}\n\n/**\n * Builds a {@link ElementFrameCapturer} that rasterizes an element to a base64 JPEG (no data-URL prefix).\n *\n * The returned function never throws. It returns `null` (so the pump sends no frame) when the element has no size, is too\n * large, a capture is already in flight, a capture times out or fails, or capture has been disabled after repeated or\n * permanent failure; in the last two cases the reason is reported once through `OnDegraded`.\n *\n * @param options Tuning and test seams.\n */\nexport function CreateDomFrameCapturer(options: DomFrameCaptureOptions = {}): ElementFrameCapturer {\n    const quality = options.Quality ?? DEFAULTS.Quality;\n    const maxEdge = options.MaxEdgePx ?? DEFAULTS.MaxEdgePx;\n    const maxNodes = options.MaxNodes ?? DEFAULTS.MaxNodes;\n    const timeoutMs = options.TimeoutMs ?? DEFAULTS.TimeoutMs;\n    const maxFailures = options.MaxConsecutiveFailures ?? DEFAULTS.MaxConsecutiveFailures;\n    const rasterize: DomRasterizer = options.Rasterize ?? ((element, rasterOptions) => toJpeg(element, rasterOptions));\n    const report = options.OnDegraded ?? ((reason: string) => console.warn(`[RealtimeChannels] ${reason}`));\n\n    let disabled = false;\n    let inFlight = false;\n    let failures = 0;\n\n    const disable = (reason: string): void => {\n        if (!disabled) {\n            disabled = true;\n            report(`Picture capture of components is off for this session; the agent keeps receiving state only. Reason: ${reason}`);\n        }\n    };\n\n    return async (element: HTMLElement): Promise<string | null> => {\n        if (disabled || inFlight || element.clientWidth === 0 || element.clientHeight === 0) {\n            return null;\n        }\n        if (element.getElementsByTagName('*').length > maxNodes) {\n            return null;\n        }\n        inFlight = true;\n        try {\n            const ratio = Math.min(1, maxEdge / Math.max(element.clientWidth, element.clientHeight));\n            const dataUrl = await withTimeout(\n                rasterize(element, { quality, pixelRatio: ratio, backgroundColor: resolveBackground(element), skipFonts: true }),\n                timeoutMs\n            );\n            if (dataUrl === undefined) {\n                failures++;\n                if (failures >= maxFailures) {\n                    disable(`capturing took longer than ${timeoutMs} ms, ${failures} times in a row`);\n                }\n                return null;\n            }\n            failures = 0;\n            return dataUrl.startsWith(JPEG_DATA_URL_PREFIX) ? dataUrl.slice(JPEG_DATA_URL_PREFIX.length) : null;\n        } catch (error) {\n            failures++;\n            if (isPermanentFailure(error) || failures >= maxFailures) {\n                disable(describeFailure(error));\n            }\n            return null;\n        } finally {\n            inFlight = false;\n        }\n    };\n}\n\n/**\n * Turns on picture capture of channel surfaces for this host: registers the default rasterizer. Call it once at startup, BEFORE a realtime session is minted (whether the channel can source a video track is\n * decided at mint). Hosts opt in: MJ Explorer calls it; an embeddable element calls it only when its flag is set.\n *\n * @param options Tuning and test seams.\n * @returns A function that removes the registration.\n */\nexport function EnableChannelFrameCapture(options: DomFrameCaptureOptions = {}): () => void {\n    ChannelFrameCapture.Instance.Register(CreateDomFrameCapturer(options));\n    return () => ChannelFrameCapture.Instance.Register(null);\n}\n"]}

package/dist/public-api.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @packageDocumentation
+ *
+ * # @memberjunction/ng-realtime-channels
+ *
+ * Build realtime-agent channels in Angular without the call overlay.
+ *
+ * - {@link AngularComponentChannel}: wrap an EXISTING Angular component as a channel surface: a descriptor plus a few
+ *   binding functions.
+ * - {@link EnableChannelFrameCapture} / {@link ChannelFrameCapture}: the opt-in DOM rasterizer that lets a channel show
+ *   the model what a surface looks like.
+ *
+ * See `guides/REALTIME_CHANNELS_GUIDE.md`.
+ */
+export * from './lib/angular-component-channel';
+export * from './lib/channel-frame-capture';
+export * from './lib/dom-frame-capture';
+//# sourceMappingURL=public-api.d.ts.map

package/dist/public-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-api.d.ts","sourceRoot":"","sources":["../src/public-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,cAAc,iCAAiC,CAAC;AAChD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC"}

package/dist/public-api.js

@@ -0,0 +1,18 @@
+/**
+ * @packageDocumentation
+ *
+ * # @memberjunction/ng-realtime-channels
+ *
+ * Build realtime-agent channels in Angular without the call overlay.
+ *
+ * - {@link AngularComponentChannel}: wrap an EXISTING Angular component as a channel surface: a descriptor plus a few
+ *   binding functions.
+ * - {@link EnableChannelFrameCapture} / {@link ChannelFrameCapture}: the opt-in DOM rasterizer that lets a channel show
+ *   the model what a surface looks like.
+ *
+ * See `guides/REALTIME_CHANNELS_GUIDE.md`.
+ */
+export * from './lib/angular-component-channel';
+export * from './lib/channel-frame-capture';
+export * from './lib/dom-frame-capture';
+//# sourceMappingURL=public-api.js.map

package/dist/public-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-api.js","sourceRoot":"","sources":["../src/public-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,cAAc,iCAAiC,CAAC;AAChD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC","sourcesContent":["/**\n * @packageDocumentation\n *\n * # @memberjunction/ng-realtime-channels\n *\n * Build realtime-agent channels in Angular without the call overlay.\n *\n * - {@link AngularComponentChannel}: wrap an EXISTING Angular component as a channel surface: a descriptor plus a few\n *   binding functions.\n * - {@link EnableChannelFrameCapture} / {@link ChannelFrameCapture}: the opt-in DOM rasterizer that lets a channel show\n *   the model what a surface looks like.\n *\n * See `guides/REALTIME_CHANNELS_GUIDE.md`.\n */\n\nexport * from './lib/angular-component-channel';\nexport * from './lib/channel-frame-capture';\nexport * from './lib/dom-frame-capture';\n"]}

package/package.json

@@ -1,10 +1,51 @@
 {
   "name": "@memberjunction/ng-realtime-channels",
-  "version": "0.0.0",
-  "description": "OIDC trusted publishing setup package for @memberjunction/ng-realtime-channels",
+  "version": "6.2.0-edge.4",
+  "description": "MemberJunction: build realtime-agent channels in Angular. Wrap an EXISTING Angular component as a channel surface with AngularComponentChannel (a descriptor plus a few binding functions), and let channels show the model pictures of DOM surfaces through an opt-in rasterizer. No overlay, no Explorer, no router.",
+  "main": "./dist/public-api.js",
+  "typings": "./dist/public-api.d.ts",
+  "files": [
+    "/dist"
+  ],
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
-}
+    "angular",
+    "realtime",
+    "channel",
+    "ai-agent",
+    "memberjunction"
+  ],
+  "author": "MemberJunction",
+  "license": "BUSL-1.1",
+  "devDependencies": {
+    "@angular/compiler": "21.2.22",
+    "@angular/compiler-cli": "21.2.22",
+    "@memberjunction/ng-test-utils": "6.2.0-edge.4",
+    "vitest": "^4.0.18"
+  },
+  "peerDependencies": {
+    "@angular/common": "^21.2.22",
+    "@angular/core": "^21.2.22"
+  },
+  "dependencies": {
+    "@memberjunction/ai": "6.2.0-edge.4",
+    "@memberjunction/ai-core-plus": "6.2.0-edge.4",
+    "@memberjunction/core": "6.2.0-edge.4",
+    "@memberjunction/global": "6.2.0-edge.4",
+    "@memberjunction/realtime-runtime": "6.2.0-edge.4",
+    "html-to-image": "^1.11.11",
+    "rxjs": "^7.8.2",
+    "tslib": "^2.8.1"
+  },
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MemberJunction/MJ"
+  },
+  "mjUILayer": "widgets",
+  "scripts": {
+    "test": "vitest run",
+    "test:types": "tsc --noEmit -p tsconfig.spec.json",
+    "build": "ngc",
+    "test:watch": "vitest"
+  }
+}