@qaiddev/thumbs-embed 1.1.1 → 1.2.1

package/dist/quest-launcher.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Lazy loader + launcher for `@qaiddev/quests-embed`.
+ *
+ * `thumbs-embed` links a button to a quest but owns no questionnaire code
+ * and takes no build-time dependency on the quests package. Instead the
+ * quests widget is imported from a CDN the first time a quest is triggered,
+ * so the shipped bundle stays zero-dependency and small.
+ *
+ * Only the tiny slice of the quests public API that we actually use is
+ * modelled here structurally, so a version bump of the quests package that
+ * keeps this surface stable needs no change in thumbs-embed.
+ */
+/** Default ES-module URL, pinned to a compatible major on unpkg. */
+export declare const DEFAULT_QUESTS_MODULE_URL = "https://unpkg.com/@qaiddev/quests-embed@1/dist/qaid-quests.js";
+/** The bit of a QaidQuests instance we hold onto. */
+export interface QuestInstance {
+    destroy(): void;
+}
+/** The bit of QaidQuests config we pass. Mirrors QuestsConfig loosely. */
+export interface LaunchedQuestConfig {
+    endpoint: string;
+    configUrl: string;
+    apiKey?: string;
+    metadata?: Record<string, unknown>;
+    onComplete?: (answers: Record<string, unknown>) => void;
+    onClose?: () => void;
+}
+type QuestsConstructor = new (config: LaunchedQuestConfig) => QuestInstance;
+/** Shape of the quests module's default/entry exports. */
+export interface QuestsModule {
+    QaidQuests: QuestsConstructor;
+}
+type Importer = (url: string) => Promise<unknown>;
+/**
+ * @internal Test seam: swap the dynamic importer and clear the cache.
+ * Pass `null` to restore the real dynamic `import()`. Not re-exported
+ * from the package entry, so it isn't public API.
+ */
+export declare function _setQuestsImporter(fn: Importer | null): void;
+/**
+ * Import the quests module, caching the promise per URL. A failed load
+ * clears the cache so a later trigger can retry (e.g. after a transient
+ * network error) rather than being stuck with a rejected promise.
+ */
+export declare function loadQuestsModule(moduleUrl: string): Promise<QuestsModule>;
+export interface LaunchQuestOptions {
+    /** Quest id to launch (the `[id]` in `{base}/{id}/definition`). */
+    questId: string;
+    /** Quest-service base URL, e.g. "https://qaid.dev/api/quests". */
+    base: string;
+    /** API key for the quest service (optional). */
+    apiKey?: string;
+    /** ES-module URL to load the quests widget from. */
+    moduleUrl: string;
+    /** Feedback record id to correlate the response with (optional). */
+    feedbackId?: string | number | null;
+    /** Called when the quest embed is torn down. */
+    onClose?: () => void;
+}
+/**
+ * Load the quests widget (if not already loaded) and open the given quest
+ * as its own centered modal. Rejects if the module can't be loaded — the
+ * caller should fall back to its normal UI.
+ */
+export declare function launchQuest(opts: LaunchQuestOptions): Promise<QuestInstance>;
+export {};

package/dist/types.d.ts

@@ -99,6 +99,43 @@ export interface FeedbackConfig {
         /** Max height of the screenshot. Default: 800 */
         maxHeight?: number;
     };
+    /**
+     * Link buttons to quests. When a button has a quest id here, clicking it
+     * launches that quest (via `@qaiddev/quests-embed`, lazy-loaded at runtime)
+     * in place of the optional message box. Leave `base` unset to keep the
+     * classic message-box behaviour for every button.
+     */
+    quests?: QuestsLaunchConfig;
+}
+/**
+ * Per-button quest links plus how to reach the quest service.
+ *
+ * The quests widget is loaded on demand from a CDN the first time a quest
+ * is triggered, so this stays a thin link — `thumbs-embed` gains no
+ * questionnaire code and no build-time dependency on the quests package.
+ */
+export interface QuestsLaunchConfig {
+    /**
+     * Base URL of the quest service. **Required to enable quest launching.**
+     * For QAid.dev this is e.g. `"https://qaid.dev/api/quests"`. The embed
+     * derives the quest definition URL (`{base}/{questId}/definition`) and the
+     * response endpoint (`{base}/responses`) from it.
+     */
+    base?: string;
+    /** Quest id launched after a thumbs-up (in place of the message box). */
+    up?: string;
+    /** Quest id launched after a thumbs-down. */
+    down?: string;
+    /** Quest id launched after a video recording is sent. */
+    video?: string;
+    /** API key for the quest service. Defaults to the top-level `apiKey`. */
+    apiKey?: string;
+    /**
+     * ES-module URL to lazy-load `@qaiddev/quests-embed` from at runtime.
+     * Default: the unpkg build pinned to a compatible major. Override to
+     * self-host or to point at a local build during development.
+     */
+    moduleUrl?: string;
 }
 /**
  * Network error captured during the session
@@ -249,4 +286,16 @@ export interface ResolvedFeedbackConfig {
         maxDuration: number;
     };
     recordIcon: string;
+    quests: {
+        /** Quest-service base URL. Empty string when quest launching is disabled. */
+        base: string;
+        /** Quest ids per button. Empty string means "no quest for this button". */
+        up: string;
+        down: string;
+        video: string;
+        /** Resolved quest API key (falls back to the top-level apiKey). */
+        apiKey: string;
+        /** Resolved ES-module URL for lazy-loading the quests widget. */
+        moduleUrl: string;
+    };
 }

package/dist/video-orientation.d.ts

@@ -0,0 +1,48 @@
+/**
+ * iOS/iPadOS screen-recording orientation fix.
+ *
+ * On iOS/iPadOS, `getDisplayMedia` + `MediaRecorder` writes a device-orientation
+ * rotation into the recorded file (even for screen captures). Players disagree
+ * on whether to honour it — the widget's own preview `<video>` renders it
+ * sideways, and so does the dashboard. Re-encoding the *live* decoded frames
+ * (which carry no container rotation) through a canvas produces a file whose
+ * pixels are already upright with no rotation metadata, so it renders the same
+ * everywhere.
+ *
+ * If the live frames themselves come back with swapped dimensions (portrait
+ * frame while the viewport is landscape, or vice versa), we additionally rotate
+ * the canvas 90° to match the viewport. That branch only triggers on a clear
+ * orientation mismatch, so a correctly-oriented recording is never rotated.
+ */
+export interface OrientationTransform {
+    /** Output canvas width in px. */
+    width: number;
+    /** Output canvas height in px. */
+    height: number;
+    /** Clockwise rotation to apply while drawing: 0, 90, or -90. */
+    rotate: 0 | 90 | -90;
+}
+export interface OrientationCorrectedStream {
+    /** Canvas-sourced stream to hand to MediaRecorder. */
+    stream: MediaStream;
+    /** Stop drawing and release the canvas stream + source video. */
+    stop: () => void;
+}
+/** True on iPhone/iPad/iPod, including iPadOS 13+ which reports as desktop Mac. */
+export declare function isIOSDevice(): boolean;
+/**
+ * Decide the output canvas size and rotation needed to render a `frameW×frameH`
+ * capture upright for a `viewportW×viewportH` viewport. When the frame and
+ * viewport share an orientation, no rotation is applied (a straight re-encode,
+ * which still strips the bad container rotation). Otherwise rotate 90°, its
+ * direction chosen from the screen orientation angle.
+ */
+export declare function computeOrientationTransform(frameW: number, frameH: number, viewportW: number, viewportH: number, screenAngle: number): OrientationTransform;
+/** Draw one video frame onto the canvas context, applying the transform. */
+export declare function drawRotatedFrame(ctx: CanvasRenderingContext2D, source: CanvasImageSource, t: OrientationTransform): void;
+/**
+ * Build a canvas-backed, orientation-normalised copy of a display-capture
+ * stream. Returns null when the browser can't support the canvas pipeline, in
+ * which case the caller should record the original stream directly.
+ */
+export declare function buildOrientationCorrectedStream(displayStream: MediaStream, frameRate?: number): Promise<OrientationCorrectedStream | null>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qaiddev/thumbs-embed",
-  "version": "1.1.1",
+  "version": "1.2.1",
   "description": "Precision User Feedback",
   "type": "module",
   "main": "./dist/qaid.umd.cjs",