@syntrologie/adapt-product 2.28.0 → 2.29.0

package/dist/widgets/renderHealthReporter.d.ts

@@ -0,0 +1,66 @@
+/**
+ * renderHealthReporter — the shared, reusable half of runtime render-health
+ * self-detection.
+ *
+ * `renderHealth.ts` MEASURES a rendered element (pure DOM read: undeclared clips
+ * + blank paint). This module is the counterpart that REPORTS the measurement:
+ * it emits `app:<category>:blank` / `app:<category>:clipped` through the ONE
+ * consent-gated door to PostHog (`window.SynOS.runtime.events.emit`), and packages
+ * the once-per-visual-state scheduling as a Lit ReactiveController so every tile
+ * widget adopts the same self-detection with ~5 lines and no copy-paste.
+ *
+ * COE-051 lesson: `publish()` only notifies in-process canvas subscribers — it
+ * NEVER reaches PostHog. `emit()` is the sanctioned capture path: the EventBus
+ * forwards emit()'d events to its posthogCapture sink (bootstrap-runtime wires it
+ * to the consent-gated `telemetry.track`). We never call posthog directly. The
+ * event name MUST satisfy validateEventName (`app:{category}:{action}`, colon
+ * segments, no `app:` prefix stripped) or the EventBus silently drops it — the
+ * exact silent failure this telemetry exists to surface.
+ *
+ * NON-PII discipline: only element tag/class PATHS and pixel numbers ever leave a
+ * widget — never text content, never customer copy.
+ */
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+import { type RenderHealth } from './renderHealth';
+export interface RenderHealthReportOptions {
+    /** Event category segment: emits `app:<category>:blank` / `:clipped`. Must be a
+     *  valid segment (`^[a-z][a-z0-9_]*$`), e.g. `product_comparison`. */
+    category: string;
+    /** `widget_kind` tag included in every payload, e.g. `adaptive-product:comparison`. */
+    widgetKind: string;
+    /** Extra NON-PII context merged into every payload (density, velvet, …). */
+    context?: Record<string, unknown>;
+}
+/**
+ * Measure `root` and, if it clips or paints blank, emit the corresponding
+ * self-detection event via the consent-gated emit() path. Returns the measured
+ * health (so callers/tests can inspect it). Never throws — a measurement or
+ * telemetry failure must never crash the widget or the host page.
+ */
+export declare function reportRenderHealth(root: Element, opts: RenderHealthReportOptions): RenderHealth;
+/** What a widget's probe returns for one measurement pass. */
+export interface RenderHealthProbe extends RenderHealthReportOptions {
+    /** The element to measure, or `null` to SKIP this pass. A widget returns null
+     *  for any UNSETTLED state (loading, error, empty, wrong face) so a transient
+     *  no-content frame is never mis-reported as a blank tile. */
+    root: Element | null;
+    /** Stable key for the current visual state; a state reports AT MOST ONCE
+     *  (prevents event spam across re-renders of the same visual state). */
+    stateKey: string;
+}
+/**
+ * Lit ReactiveController that runs a widget's render-health probe after each
+ * paint settles (rAF then a 0ms timeout, so lazy images / web fonts land first),
+ * at most once per visual state. Attach in a widget's field initializer:
+ *
+ *   #health = new RenderHealthController(this, () => this.#healthProbe());
+ *
+ * The controller's `hostUpdated` fires automatically after every host update.
+ */
+export declare class RenderHealthController implements ReactiveController {
+    #private;
+    constructor(host: ReactiveControllerHost, probe: () => RenderHealthProbe | null);
+    hostUpdated(): void;
+    hostDisconnected(): void;
+}
+//# sourceMappingURL=renderHealthReporter.d.ts.map

package/dist/widgets/renderHealthReporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderHealthReporter.d.ts","sourceRoot":"","sources":["../../src/widgets/renderHealthReporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,KAAK,CAAC;AACtE,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAwBxE,MAAM,WAAW,yBAAyB;IACxC;0EACsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IACjB,uFAAuF;IACvF,UAAU,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAID;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,yBAAyB,GAAG,YAAY,CA2B/F;AAED,8DAA8D;AAC9D,MAAM,WAAW,iBAAkB,SAAQ,yBAAyB;IAClE;;kEAE8D;IAC9D,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IACrB;4EACwE;IACxE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,qBAAa,sBAAuB,YAAW,kBAAkB;;gBAKnD,IAAI,EAAE,sBAAsB,EAAE,KAAK,EAAE,MAAM,iBAAiB,GAAG,IAAI;IAK/E,WAAW,IAAI,IAAI;IAInB,gBAAgB,IAAI,IAAI;CA6CzB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syntrologie/adapt-product",
-  "version": "2.28.0",
+  "version": "2.29.0",
   "description": "Adaptive Product — product cards, comparison, hero, and grid tile widgets with optional price/image binding to host-page sources.",
   "license": "Proprietary",
   "private": false,
@@ -46,6 +46,9 @@
     "lit": "^3.0.0",
     "zod": "^3.0.0"
   },
+  "dependencies": {
+    "@syntrologie/runtime-contracts": "*"
+  },
   "devDependencies": {
     "@open-wc/testing-helpers": "3.0.1",
     "@syntrologie/sdk-contracts": "*",