@m2farhood-2/qapture 0.2.0

package/dist/index.cjs

@@ -0,0 +1,20 @@
+'use strict';
+
+var chunkCJQHPDT7_cjs = require('./chunk-CJQHPDT7.cjs');
+
+
+
+Object.defineProperty(exports, "QaStudio", {
+  enumerable: true,
+  get: function () { return chunkCJQHPDT7_cjs.Qapture; }
+});
+Object.defineProperty(exports, "Qapture", {
+  enumerable: true,
+  get: function () { return chunkCJQHPDT7_cjs.Qapture; }
+});
+Object.defineProperty(exports, "initQaStudio", {
+  enumerable: true,
+  get: function () { return chunkCJQHPDT7_cjs.initQaStudio; }
+});
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.d.cts

@@ -0,0 +1,179 @@
+/**
+ * schema.ts — all public config types + a runtime validator for qapture.
+ *
+ * validateConfig() deep-merges user input over the built-in defaults, coerces
+ * or skips invalid entries, and NEVER throws. Returns a fully-resolved config
+ * plus human-readable warnings.
+ *
+ * Also exports DEFAULT_THEME so that defaults.ts can import it without
+ * creating a circular dependency (defaults.ts → schema.ts, not the reverse).
+ */
+/** A bilingual string: either a plain string (language-neutral) or { en, ar? }. */
+type QaBilingual = string | {
+    en: string;
+    ar?: string;
+};
+/** Brand colour palette for the QA panel. All fields optional on input. */
+type QaTheme = {
+    primary: string;
+    primaryDark: string;
+    accent: string;
+    accentDark: string;
+    sage: string;
+    cream: string;
+    mauve: string;
+    surface: string;
+    ink: string;
+};
+/** A single test credential row. */
+type QaCredential = {
+    role: string;
+    roleAr?: string;
+    login: string;
+    password: string;
+    seeded?: boolean;
+    hint?: {
+        en: string;
+        ar?: string;
+    };
+};
+/** Risk level for a journey step. */
+type QaRisk = 'red' | 'amber' | 'green';
+/** One step inside a journey lane. */
+type QaJourneyStep = {
+    path: string;
+    what: QaBilingual;
+    risk?: QaRisk;
+    riskWhy?: string;
+};
+/** A role-grouped journey lane. */
+type QaJourneyLane = {
+    id: string;
+    color?: string;
+    role: QaBilingual;
+    steps: QaJourneyStep[];
+};
+/**
+ * Freeform preamble block consumed by AI agents in Phase 2.
+ * All fields optional; additional keys allowed via index signature.
+ *
+ * conventions, invariants, verifySteps, and runCommands all accept either a
+ * single string (plain text / newline-separated) or an explicit string[].
+ * The export layer normalises both forms before rendering.
+ */
+type QaPreamble = {
+    projectName?: string;
+    oneLiner?: string;
+    stack?: string;
+    runCommands?: string | string[];
+    /** Numbered conventions list — plain string or explicit array. */
+    conventions?: string | string[];
+    /** Do-not-break invariants — plain string or explicit array. */
+    invariants?: string | string[];
+    /** Steps to verify a fix — plain string or explicit array. */
+    verifySteps?: string | string[];
+    additionalContext?: string;
+    [key: string]: unknown;
+};
+type QaConfig = {
+    /** Storage + DB namespace. Defaults to 'qapture'. */
+    namespace?: string;
+    /** Override any subset of the colour palette. */
+    theme?: Partial<QaTheme>;
+    /** Panel brand label. */
+    brand?: {
+        label?: string;
+    };
+    /** Display label for the login/username field. */
+    loginField?: {
+        en: string;
+        ar?: string;
+    };
+    /** Test credentials list. */
+    credentials?: QaCredential[];
+    /** Role-grouped testing journey. */
+    journey?: QaJourneyLane[];
+    /** AI agent preamble block. */
+    preamble?: QaPreamble;
+    /** If true, default language initializes to 'ar' (RTL). */
+    rtl?: boolean;
+    /**
+     * Whether the panel is visible.
+     * - true / false: always show / always hide
+     * - undefined (default): ShadowMount treats as "dev-only" (show only when
+     *   process.env.NODE_ENV !== 'production' or equivalent)
+     */
+    visible?: boolean;
+    /** Always visible, even in production. Overrides `visible`. */
+    alwaysVisible?: boolean;
+    /** Keyboard shortcut to toggle the panel. Default: 'shift+alt+q'. */
+    hotkey?: string;
+};
+type ResolvedConfig = {
+    namespace: string;
+    theme: QaTheme;
+    brand: {
+        label: string;
+    };
+    loginField: {
+        en: string;
+        ar?: string;
+    };
+    credentials: QaCredential[];
+    journey: QaJourneyLane[];
+    preamble: QaPreamble | null;
+    rtl: boolean;
+    /**
+     * Visibility sentinel.
+     * - true: always show
+     * - false: always hide
+     * - undefined: dev-only (ShadowMount interprets at mount time)
+     *
+     * The key is always present in ResolvedConfig; only the value may be undefined.
+     */
+    visible: boolean | undefined;
+    alwaysVisible: boolean;
+    hotkey: string;
+};
+
+/**
+ * qapture — public API.
+ *
+ * Ships ZERO AI: this is a keyless, secretless, 100% client-side capture
+ * widget. The <Qapture/> component and initQaStudio() imperative function
+ * both mount an isolated Shadow-DOM host on the client and render nothing on
+ * the server (SSR-safe).
+ */
+
+/**
+ * Mount qapture imperatively.
+ *
+ * Validates and resolves the supplied config, then mounts the widget into an
+ * isolated Shadow-DOM host attached to document.body. Returns a handle with a
+ * destroy() method that unmounts and cleans up.
+ *
+ * SSR-safe: returns a no-op destroy() when called outside a browser.
+ */
+declare function initQaStudio(config?: QaConfig): {
+    destroy(): void;
+};
+/**
+ * Drop-in React component that mounts qapture on the client.
+ *
+ * Renders `null` (SSR-safe). On mount it calls initQaStudio() and returns its
+ * destroy() for useEffect cleanup. Config changes after mount are ignored
+ * (destroy + remount if needed).
+ *
+ * Usage (Next.js App Router):
+ *   import { Qapture } from 'qapture/next';  // adds 'use client' banner
+ *   <Qapture config={qaConfig} />
+ *
+ * Usage (any React app):
+ *   import { Qapture } from 'qapture';
+ *   <Qapture config={qaConfig} />
+ */
+declare function Qapture({ config }: {
+    config?: QaConfig;
+}): null;
+
+export { type QaBilingual, type QaConfig, type QaCredential, type QaJourneyLane, type QaJourneyStep, type QaPreamble, type QaRisk, Qapture as QaStudio, type QaTheme, Qapture, type ResolvedConfig, initQaStudio };

package/dist/index.d.ts

@@ -0,0 +1,179 @@
+/**
+ * schema.ts — all public config types + a runtime validator for qapture.
+ *
+ * validateConfig() deep-merges user input over the built-in defaults, coerces
+ * or skips invalid entries, and NEVER throws. Returns a fully-resolved config
+ * plus human-readable warnings.
+ *
+ * Also exports DEFAULT_THEME so that defaults.ts can import it without
+ * creating a circular dependency (defaults.ts → schema.ts, not the reverse).
+ */
+/** A bilingual string: either a plain string (language-neutral) or { en, ar? }. */
+type QaBilingual = string | {
+    en: string;
+    ar?: string;
+};
+/** Brand colour palette for the QA panel. All fields optional on input. */
+type QaTheme = {
+    primary: string;
+    primaryDark: string;
+    accent: string;
+    accentDark: string;
+    sage: string;
+    cream: string;
+    mauve: string;
+    surface: string;
+    ink: string;
+};
+/** A single test credential row. */
+type QaCredential = {
+    role: string;
+    roleAr?: string;
+    login: string;
+    password: string;
+    seeded?: boolean;
+    hint?: {
+        en: string;
+        ar?: string;
+    };
+};
+/** Risk level for a journey step. */
+type QaRisk = 'red' | 'amber' | 'green';
+/** One step inside a journey lane. */
+type QaJourneyStep = {
+    path: string;
+    what: QaBilingual;
+    risk?: QaRisk;
+    riskWhy?: string;
+};
+/** A role-grouped journey lane. */
+type QaJourneyLane = {
+    id: string;
+    color?: string;
+    role: QaBilingual;
+    steps: QaJourneyStep[];
+};
+/**
+ * Freeform preamble block consumed by AI agents in Phase 2.
+ * All fields optional; additional keys allowed via index signature.
+ *
+ * conventions, invariants, verifySteps, and runCommands all accept either a
+ * single string (plain text / newline-separated) or an explicit string[].
+ * The export layer normalises both forms before rendering.
+ */
+type QaPreamble = {
+    projectName?: string;
+    oneLiner?: string;
+    stack?: string;
+    runCommands?: string | string[];
+    /** Numbered conventions list — plain string or explicit array. */
+    conventions?: string | string[];
+    /** Do-not-break invariants — plain string or explicit array. */
+    invariants?: string | string[];
+    /** Steps to verify a fix — plain string or explicit array. */
+    verifySteps?: string | string[];
+    additionalContext?: string;
+    [key: string]: unknown;
+};
+type QaConfig = {
+    /** Storage + DB namespace. Defaults to 'qapture'. */
+    namespace?: string;
+    /** Override any subset of the colour palette. */
+    theme?: Partial<QaTheme>;
+    /** Panel brand label. */
+    brand?: {
+        label?: string;
+    };
+    /** Display label for the login/username field. */
+    loginField?: {
+        en: string;
+        ar?: string;
+    };
+    /** Test credentials list. */
+    credentials?: QaCredential[];
+    /** Role-grouped testing journey. */
+    journey?: QaJourneyLane[];
+    /** AI agent preamble block. */
+    preamble?: QaPreamble;
+    /** If true, default language initializes to 'ar' (RTL). */
+    rtl?: boolean;
+    /**
+     * Whether the panel is visible.
+     * - true / false: always show / always hide
+     * - undefined (default): ShadowMount treats as "dev-only" (show only when
+     *   process.env.NODE_ENV !== 'production' or equivalent)
+     */
+    visible?: boolean;
+    /** Always visible, even in production. Overrides `visible`. */
+    alwaysVisible?: boolean;
+    /** Keyboard shortcut to toggle the panel. Default: 'shift+alt+q'. */
+    hotkey?: string;
+};
+type ResolvedConfig = {
+    namespace: string;
+    theme: QaTheme;
+    brand: {
+        label: string;
+    };
+    loginField: {
+        en: string;
+        ar?: string;
+    };
+    credentials: QaCredential[];
+    journey: QaJourneyLane[];
+    preamble: QaPreamble | null;
+    rtl: boolean;
+    /**
+     * Visibility sentinel.
+     * - true: always show
+     * - false: always hide
+     * - undefined: dev-only (ShadowMount interprets at mount time)
+     *
+     * The key is always present in ResolvedConfig; only the value may be undefined.
+     */
+    visible: boolean | undefined;
+    alwaysVisible: boolean;
+    hotkey: string;
+};
+
+/**
+ * qapture — public API.
+ *
+ * Ships ZERO AI: this is a keyless, secretless, 100% client-side capture
+ * widget. The <Qapture/> component and initQaStudio() imperative function
+ * both mount an isolated Shadow-DOM host on the client and render nothing on
+ * the server (SSR-safe).
+ */
+
+/**
+ * Mount qapture imperatively.
+ *
+ * Validates and resolves the supplied config, then mounts the widget into an
+ * isolated Shadow-DOM host attached to document.body. Returns a handle with a
+ * destroy() method that unmounts and cleans up.
+ *
+ * SSR-safe: returns a no-op destroy() when called outside a browser.
+ */
+declare function initQaStudio(config?: QaConfig): {
+    destroy(): void;
+};
+/**
+ * Drop-in React component that mounts qapture on the client.
+ *
+ * Renders `null` (SSR-safe). On mount it calls initQaStudio() and returns its
+ * destroy() for useEffect cleanup. Config changes after mount are ignored
+ * (destroy + remount if needed).
+ *
+ * Usage (Next.js App Router):
+ *   import { Qapture } from 'qapture/next';  // adds 'use client' banner
+ *   <Qapture config={qaConfig} />
+ *
+ * Usage (any React app):
+ *   import { Qapture } from 'qapture';
+ *   <Qapture config={qaConfig} />
+ */
+declare function Qapture({ config }: {
+    config?: QaConfig;
+}): null;
+
+export { type QaBilingual, type QaConfig, type QaCredential, type QaJourneyLane, type QaJourneyStep, type QaPreamble, type QaRisk, Qapture as QaStudio, type QaTheme, Qapture, type ResolvedConfig, initQaStudio };

package/dist/index.js

@@ -0,0 +1,3 @@
+export { Qapture as QaStudio, Qapture, initQaStudio } from './chunk-OPZF4IVW.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/next.cjs

@@ -0,0 +1,21 @@
+"use client";
+'use strict';
+
+var chunkCJQHPDT7_cjs = require('./chunk-CJQHPDT7.cjs');
+
+
+
+Object.defineProperty(exports, "QaStudio", {
+  enumerable: true,
+  get: function () { return chunkCJQHPDT7_cjs.Qapture; }
+});
+Object.defineProperty(exports, "Qapture", {
+  enumerable: true,
+  get: function () { return chunkCJQHPDT7_cjs.Qapture; }
+});
+Object.defineProperty(exports, "initQaStudio", {
+  enumerable: true,
+  get: function () { return chunkCJQHPDT7_cjs.initQaStudio; }
+});
+//# sourceMappingURL=next.cjs.map
+//# sourceMappingURL=next.cjs.map

package/dist/next.d.cts

@@ -0,0 +1 @@
+export { QaConfig, QaStudio, QaStudio as Qapture, initQaStudio } from './index.cjs';

package/dist/next.d.ts

@@ -0,0 +1 @@
+export { QaConfig, QaStudio, QaStudio as Qapture, initQaStudio } from './index.js';

package/dist/next.js

@@ -0,0 +1,4 @@
+"use client";
+export { Qapture as QaStudio, Qapture, initQaStudio } from './chunk-OPZF4IVW.js';
+//# sourceMappingURL=next.js.map
+//# sourceMappingURL=next.js.map

package/dist/standalone.cjs

@@ -0,0 +1,39 @@
+'use strict';
+
+var chunkCJQHPDT7_cjs = require('./chunk-CJQHPDT7.cjs');
+
+// src/standalone.ts
+if (typeof window !== "undefined" && typeof customElements !== "undefined" && !customElements.get("qapture-widget")) {
+  import('./index.cjs').then(({ initQaStudio: init }) => {
+    customElements.define(
+      "qapture-widget",
+      class QaStudioWidget extends HTMLElement {
+        connectedCallback() {
+          let cfg = {};
+          try {
+            const attr = this.getAttribute("config");
+            if (attr) cfg = JSON.parse(attr);
+          } catch {
+          }
+          const propCfg = this["config"];
+          if (propCfg && typeof propCfg === "object" && !Array.isArray(propCfg)) {
+            cfg = propCfg;
+          }
+          const instance = init(cfg);
+          this._destroy = instance.destroy;
+        }
+        disconnectedCallback() {
+          this._destroy?.();
+        }
+      }
+    );
+  }).catch(() => {
+  });
+}
+
+Object.defineProperty(exports, "initQaStudio", {
+  enumerable: true,
+  get: function () { return chunkCJQHPDT7_cjs.initQaStudio; }
+});
+//# sourceMappingURL=standalone.cjs.map
+//# sourceMappingURL=standalone.cjs.map

package/dist/standalone.d.cts

@@ -0,0 +1 @@
+export { QaConfig, initQaStudio } from './index.cjs';

package/dist/standalone.d.ts

@@ -0,0 +1 @@
+export { QaConfig, initQaStudio } from './index.js';

package/dist/standalone.js

@@ -0,0 +1,32 @@
+export { initQaStudio } from './chunk-OPZF4IVW.js';
+
+// src/standalone.ts
+if (typeof window !== "undefined" && typeof customElements !== "undefined" && !customElements.get("qapture-widget")) {
+  import('./index.js').then(({ initQaStudio: init }) => {
+    customElements.define(
+      "qapture-widget",
+      class QaStudioWidget extends HTMLElement {
+        connectedCallback() {
+          let cfg = {};
+          try {
+            const attr = this.getAttribute("config");
+            if (attr) cfg = JSON.parse(attr);
+          } catch {
+          }
+          const propCfg = this["config"];
+          if (propCfg && typeof propCfg === "object" && !Array.isArray(propCfg)) {
+            cfg = propCfg;
+          }
+          const instance = init(cfg);
+          this._destroy = instance.destroy;
+        }
+        disconnectedCallback() {
+          this._destroy?.();
+        }
+      }
+    );
+  }).catch(() => {
+  });
+}
+//# sourceMappingURL=standalone.js.map
+//# sourceMappingURL=standalone.js.map

package/package.json

@@ -0,0 +1,116 @@
+{
+  "name": "@m2farhood-2/qapture",
+  "version": "0.2.0",
+  "description": "Drop-in, AI-aware in-browser QA capture widget. A tester annotates the live app (element/region + auto-screenshot + note), tracks a graded testing journey, and exports a ZIP your own coding agent reads. Ships zero AI.",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "qa",
+    "testing",
+    "annotation",
+    "screenshot",
+    "ai",
+    "agents",
+    "claude-code",
+    "widget",
+    "shadow-dom"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./next": {
+      "import": {
+        "types": "./dist/next.d.ts",
+        "default": "./dist/next.js"
+      },
+      "require": {
+        "types": "./dist/next.d.cts",
+        "default": "./dist/next.cjs"
+      }
+    },
+    "./standalone": {
+      "import": {
+        "types": "./dist/standalone.d.ts",
+        "default": "./dist/standalone.js"
+      },
+      "require": {
+        "types": "./dist/standalone.d.cts",
+        "default": "./dist/standalone.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "qapture": "./dist/bin/init.cjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mohammed-farhood/qapture.git"
+  },
+  "homepage": "https://github.com/mohammed-farhood/qapture#readme",
+  "bugs": {
+    "url": "https://github.com/mohammed-farhood/qapture/issues"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "!dist/_export-test.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup && node scripts/postbuild.mjs",
+    "prepublishOnly": "npm run build",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "smoke": "node scripts/smoke.mjs",
+    "export-smoke": "esbuild src/lib/exportZip.ts --bundle --format=esm --platform=node --outfile=dist/_export-test.mjs --log-level=error && node scripts/export-smoke.mjs dist/_export-test.mjs",
+    "browser-test": "node scripts/browser-test.mjs",
+    "verify": "npm run typecheck && npm run build && npm run smoke && npm run export-smoke",
+    "play": "npm --prefix playground run dev"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": false
+    },
+    "react-dom": {
+      "optional": false
+    }
+  },
+  "dependencies": {
+    "html2canvas": "^1.4.1",
+    "jszip": "^3.10.1"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "jsdom": "^29.1.1",
+    "puppeteer-core": "^25.2.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3"
+  }
+}