@freeappstore/quality 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FreeAppStore
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Quality reporter for FreeAppStore / FreeGameStore apps.
+ *
+ * When an app is loaded inside an iframe (i.e. by the platform Quality
+ * Dashboard at https://freeappstore.online/quality), this reporter posts
+ * viewport / overflow / clipping metrics back to the parent so the
+ * dashboard can audit layout fit at every reference viewport without
+ * needing same-origin DOM access.
+ *
+ * In production (top-level navigation) the reporter is a no-op — there's
+ * no parent to receive messages, so we don't waste CPU.
+ *
+ * Privacy note: posts contain ONLY viewport / DOM-shape numbers. No URLs
+ * (parent already knows), no localStorage, no user content, no identifiers.
+ * Apps remain fully privacy-first; this is structural metadata for QA only.
+ *
+ * Cooperation contract: the platform's audit treats apps that import this
+ * reporter (and respond to dashboard probes) as audit-cooperative. Apps
+ * that ship without it can still be listed but won't get a Quality Index
+ * badge — opt-out is allowed but visible.
+ */
+export interface ViewportReport {
+    type: 'fas:quality';
+    schema: 1;
+    /** ms since epoch when the snapshot was taken. */
+    capturedAt: number;
+    /** Top-level subdomain (e.g. "tetris" from tetris.freegamestore.online). */
+    appId: string;
+    /** Viewport size as the iframe sees it (parent sets this). */
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /** Document scroll vs viewport — if scrollWidth > clientWidth, the page scrolls horizontally. */
+    document: {
+        scrollWidth: number;
+        scrollHeight: number;
+        clientWidth: number;
+        clientHeight: number;
+        scrollsX: boolean;
+        scrollsY: boolean;
+    };
+    /** Inner-clipping: any element with overflow:hidden|clip whose content overflows its box. */
+    clipping: ClippingHit[];
+    /** Color scheme the app currently believes it's in (light | dark | unknown). */
+    colorScheme: 'light' | 'dark' | 'unknown';
+    /** Whether prefers-reduced-motion is set. */
+    reducedMotion: boolean;
+    /** SDK / reporter version that produced this. Lets the dashboard
+     *  detect / migrate when the schema changes. */
+    reporterVersion: string;
+}
+export interface ClippingHit {
+    /** CSS-ish selector best-effort: tag + first class or id. */
+    selector: string;
+    scrollWidth: number;
+    scrollHeight: number;
+    clientWidth: number;
+    clientHeight: number;
+    clipsX: boolean;
+    clipsY: boolean;
+}
+/**
+ * Synchronously snapshot the current layout state. Cheap (single DOM walk)
+ * but called frequently during resize, so we cap clipping hits.
+ */
+export declare function snapshot(): ViewportReport;
+interface ReporterHandle {
+    /** Stop reporting and detach all listeners. */
+    stop(): void;
+    /** Force a snapshot + post immediately (e.g. after a layout change). */
+    reportNow(): void;
+}
+/**
+ * Start the reporter. Idempotent — calling twice returns the existing
+ * handle. Designed for one-line use: `initQualityReporter()` from your
+ * app's main.tsx / entry. The reporter is a no-op when not iframed,
+ * so leaving it on in production has zero cost.
+ *
+ * Channels:
+ * - posts to `window.parent` with `type: 'fas:quality'`
+ * - listens on `window` for `type: 'fas:quality:request'` so the parent
+ *   can poll on demand (e.g. after resizing the iframe)
+ */
+export declare function initQualityReporter(): ReporterHandle;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,CAAC,CAAC;IACV,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,iGAAiG;IACjG,QAAQ,EAAE;QACR,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,QAAQ,EAAE,OAAO,CAAC;QAClB,QAAQ,EAAE,OAAO,CAAC;KACnB,CAAC;IACF,6FAA6F;IAC7F,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,gFAAgF;IAChF,WAAW,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;IAC1C,6CAA6C;IAC7C,aAAa,EAAE,OAAO,CAAC;IACvB;oDACgD;IAChD,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB;AAqBD;;;GAGG;AACH,wBAAgB,QAAQ,IAAI,cAAc,CA2FzC;AAED,UAAU,cAAc;IACtB,+CAA+C;IAC/C,IAAI,IAAI,IAAI,CAAC;IACb,wEAAwE;IACxE,SAAS,IAAI,IAAI,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,CAwDpD"}

package/dist/index.js

@@ -0,0 +1,199 @@
+/**
+ * Quality reporter for FreeAppStore / FreeGameStore apps.
+ *
+ * When an app is loaded inside an iframe (i.e. by the platform Quality
+ * Dashboard at https://freeappstore.online/quality), this reporter posts
+ * viewport / overflow / clipping metrics back to the parent so the
+ * dashboard can audit layout fit at every reference viewport without
+ * needing same-origin DOM access.
+ *
+ * In production (top-level navigation) the reporter is a no-op — there's
+ * no parent to receive messages, so we don't waste CPU.
+ *
+ * Privacy note: posts contain ONLY viewport / DOM-shape numbers. No URLs
+ * (parent already knows), no localStorage, no user content, no identifiers.
+ * Apps remain fully privacy-first; this is structural metadata for QA only.
+ *
+ * Cooperation contract: the platform's audit treats apps that import this
+ * reporter (and respond to dashboard probes) as audit-cooperative. Apps
+ * that ship without it can still be listed but won't get a Quality Index
+ * badge — opt-out is allowed but visible.
+ */
+const REPORTER_VERSION = '0.1.0';
+const TOLERANCE_PX = 1;
+const MAX_CLIPPING_HITS = 20;
+/**
+ * Whether the page should report. Returns false when:
+ * - There's no `window.parent` (Node / SSR)
+ * - The page is loaded top-level (no parent to talk to)
+ * - The user has set window.__FAS_QUALITY_DISABLE = true (for embeds where
+ *   the host is hostile — e.g. an iframe embed on a third-party site that
+ *   we don't want to leak metrics to).
+ */
+function shouldReport() {
+    if (typeof window === 'undefined')
+        return false;
+    if (window.parent === window)
+        return false;
+    if (window.__FAS_QUALITY_DISABLE)
+        return false;
+    return true;
+}
+/**
+ * Synchronously snapshot the current layout state. Cheap (single DOM walk)
+ * but called frequently during resize, so we cap clipping hits.
+ */
+export function snapshot() {
+    const root = typeof document !== 'undefined' ? document.documentElement : null;
+    const w = typeof window !== 'undefined' ? window : undefined;
+    const fallback = () => ({
+        type: 'fas:quality',
+        schema: 1,
+        capturedAt: Date.now(),
+        appId: '',
+        viewport: { width: 0, height: 0 },
+        document: {
+            scrollWidth: 0,
+            scrollHeight: 0,
+            clientWidth: 0,
+            clientHeight: 0,
+            scrollsX: false,
+            scrollsY: false,
+        },
+        clipping: [],
+        colorScheme: 'unknown',
+        reducedMotion: false,
+        reporterVersion: REPORTER_VERSION,
+    });
+    if (!root)
+        return fallback();
+    const clipping = [];
+    // Walk all elements once; flag those with overflow:hidden|clip whose
+    // content is larger than their box. This catches the common case where
+    // a fixed-pixel container clips its child content but the document
+    // itself doesn't scroll — invisible clipping that breaks UX without
+    // tripping a naive scrollWidth check.
+    const all = document.querySelectorAll('*');
+    for (let i = 0; i < all.length && clipping.length < MAX_CLIPPING_HITS; i++) {
+        const el = all[i];
+        const cs = getComputedStyle(el);
+        const ovx = cs.overflowX;
+        const ovy = cs.overflowY;
+        const xClipped = (ovx === 'hidden' || ovx === 'clip') && el.scrollWidth > el.clientWidth + TOLERANCE_PX;
+        const yClipped = (ovy === 'hidden' || ovy === 'clip') && el.scrollHeight > el.clientHeight + TOLERANCE_PX;
+        if (!xClipped && !yClipped)
+            continue;
+        const idPart = el.id ? `#${el.id}` : '';
+        const classPart = el.className && typeof el.className === 'string'
+            ? `.${el.className.split(/\s+/).filter(Boolean)[0] ?? ''}`
+            : '';
+        clipping.push({
+            selector: `${el.tagName.toLowerCase()}${idPart}${classPart}`,
+            scrollWidth: el.scrollWidth,
+            scrollHeight: el.scrollHeight,
+            clientWidth: el.clientWidth,
+            clientHeight: el.clientHeight,
+            clipsX: xClipped,
+            clipsY: yClipped,
+        });
+    }
+    const colorScheme = typeof matchMedia === 'function'
+        ? matchMedia('(prefers-color-scheme: dark)').matches
+            ? 'dark'
+            : 'light'
+        : 'unknown';
+    const reducedMotion = typeof matchMedia === 'function' ? matchMedia('(prefers-reduced-motion: reduce)').matches : false;
+    // App ID is the leftmost subdomain on a *.freeappstore.online or
+    // *.freegamestore.online host; bare domains (local dev, custom domains)
+    // get the empty string and the dashboard falls back to the iframe URL.
+    const host = w.location.hostname;
+    const m = /^([^.]+)\.(?:freeappstore|freegamestore)\.online$/.exec(host);
+    const appId = m?.[1] ?? '';
+    return {
+        type: 'fas:quality',
+        schema: 1,
+        capturedAt: Date.now(),
+        appId,
+        viewport: { width: w.innerWidth, height: w.innerHeight },
+        document: {
+            scrollWidth: root.scrollWidth,
+            scrollHeight: root.scrollHeight,
+            clientWidth: root.clientWidth,
+            clientHeight: root.clientHeight,
+            scrollsX: root.scrollWidth > root.clientWidth + TOLERANCE_PX,
+            scrollsY: root.scrollHeight > root.clientHeight + TOLERANCE_PX,
+        },
+        clipping,
+        colorScheme,
+        reducedMotion,
+        reporterVersion: REPORTER_VERSION,
+    };
+}
+/**
+ * Start the reporter. Idempotent — calling twice returns the existing
+ * handle. Designed for one-line use: `initQualityReporter()` from your
+ * app's main.tsx / entry. The reporter is a no-op when not iframed,
+ * so leaving it on in production has zero cost.
+ *
+ * Channels:
+ * - posts to `window.parent` with `type: 'fas:quality'`
+ * - listens on `window` for `type: 'fas:quality:request'` so the parent
+ *   can poll on demand (e.g. after resizing the iframe)
+ */
+export function initQualityReporter() {
+    // Idempotency guard: parent dashboards can probe + the SDK can also
+    // call this; we only want one reporter per page.
+    const w = typeof window !== 'undefined' ? window : null;
+    if (!w)
+        return { stop: () => undefined, reportNow: () => undefined };
+    const existing = w.__FAS_QUALITY_REPORTER__;
+    if (existing)
+        return existing;
+    if (!shouldReport()) {
+        // No-op handle — production page with no parent. Still install one
+        // marker so a later call doesn't try to install again.
+        const noop = { stop: () => undefined, reportNow: () => undefined };
+        w.__FAS_QUALITY_REPORTER__ = noop;
+        return noop;
+    }
+    const post = () => {
+        try {
+            w.parent.postMessage(snapshot(), '*');
+        }
+        catch {
+            // Parent may have closed or set restrictive CSP; nothing to do.
+        }
+    };
+    // Fire on initial layout, after fonts settle, and after any subsequent
+    // resize. The 250ms delay matches what fas screencheck waits for fonts.
+    const initialPost = () => {
+        post();
+        setTimeout(post, 250);
+        setTimeout(post, 1500); // catch late layout (web fonts, lazy images)
+    };
+    const onResize = () => post();
+    const onMessage = (e) => {
+        const data = e.data;
+        if (data && data.type === 'fas:quality:request')
+            post();
+    };
+    if (document.readyState === 'complete' || document.readyState === 'interactive') {
+        initialPost();
+    }
+    else {
+        document.addEventListener('DOMContentLoaded', initialPost, { once: true });
+    }
+    w.addEventListener('resize', onResize);
+    w.addEventListener('message', onMessage);
+    const handle = {
+        stop: () => {
+            w.removeEventListener('resize', onResize);
+            w.removeEventListener('message', onMessage);
+            delete w.__FAS_QUALITY_REPORTER__;
+        },
+        reportNow: post,
+    };
+    w.__FAS_QUALITY_REPORTER__ = handle;
+    return handle;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.test.d.ts.map

package/dist/index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":""}

package/dist/index.test.js

@@ -0,0 +1,116 @@
+// @vitest-environment jsdom
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { snapshot, initQualityReporter } from './index.js';
+describe('snapshot', () => {
+    it('returns the schema-1 shape with required keys', () => {
+        const s = snapshot();
+        expect(s.type).toBe('fas:quality');
+        expect(s.schema).toBe(1);
+        expect(typeof s.capturedAt).toBe('number');
+        expect(s.viewport).toBeDefined();
+        expect(s.document).toBeDefined();
+        expect(s.clipping).toBeInstanceOf(Array);
+        expect(['light', 'dark', 'unknown']).toContain(s.colorScheme);
+    });
+    it('extracts appId from *.freeappstore.online host', () => {
+        Object.defineProperty(window, 'location', {
+            value: { hostname: 'tetris.freegamestore.online' },
+            configurable: true,
+        });
+        expect(snapshot().appId).toBe('tetris');
+        Object.defineProperty(window, 'location', {
+            value: { hostname: 'todo.freeappstore.online' },
+            configurable: true,
+        });
+        expect(snapshot().appId).toBe('todo');
+    });
+    it('returns empty appId for local dev / custom domains', () => {
+        Object.defineProperty(window, 'location', {
+            value: { hostname: 'localhost' },
+            configurable: true,
+        });
+        expect(snapshot().appId).toBe('');
+        Object.defineProperty(window, 'location', {
+            value: { hostname: 'example.com' },
+            configurable: true,
+        });
+        expect(snapshot().appId).toBe('');
+    });
+    it('flags scrollsX/scrollsY when scrollWidth/Height exceed client', () => {
+        // jsdom's layout numbers are mostly zero; mock the getter chain.
+        const root = document.documentElement;
+        Object.defineProperty(root, 'scrollWidth', { get: () => 500, configurable: true });
+        Object.defineProperty(root, 'clientWidth', { get: () => 393, configurable: true });
+        Object.defineProperty(root, 'scrollHeight', { get: () => 800, configurable: true });
+        Object.defineProperty(root, 'clientHeight', { get: () => 800, configurable: true });
+        const s = snapshot();
+        expect(s.document.scrollsX).toBe(true);
+        expect(s.document.scrollsY).toBe(false);
+    });
+    it('detects inner clipping on overflow:hidden elements', () => {
+        document.body.innerHTML = '<div class="clipper"><div class="big"></div></div>';
+        const clipper = document.querySelector('.clipper');
+        // Mock getComputedStyle so the clipper reports overflow:hidden.
+        const origGet = window.getComputedStyle;
+        window.getComputedStyle = ((el) => {
+            if (el === clipper)
+                return { overflowX: 'hidden', overflowY: 'visible' };
+            return origGet(el);
+        });
+        Object.defineProperty(clipper, 'scrollWidth', { get: () => 500 });
+        Object.defineProperty(clipper, 'clientWidth', { get: () => 200 });
+        Object.defineProperty(clipper, 'scrollHeight', { get: () => 100 });
+        Object.defineProperty(clipper, 'clientHeight', { get: () => 100 });
+        const s = snapshot();
+        expect(s.clipping.length).toBeGreaterThan(0);
+        expect(s.clipping[0].clipsX).toBe(true);
+        expect(s.clipping[0].selector).toContain('div');
+        window.getComputedStyle = origGet;
+    });
+});
+describe('initQualityReporter', () => {
+    beforeEach(() => {
+        delete window.__FAS_QUALITY_REPORTER__;
+        delete window.__FAS_QUALITY_DISABLE;
+    });
+    afterEach(() => {
+        const h = window.__FAS_QUALITY_REPORTER__;
+        if (h?.stop)
+            h.stop();
+    });
+    it('is a no-op when there is no parent (top-level navigation)', () => {
+        // jsdom's window.parent === window by default — same as a real top-level page.
+        const handle = initQualityReporter();
+        expect(typeof handle.stop).toBe('function');
+        expect(typeof handle.reportNow).toBe('function');
+        // Calling reportNow shouldn't throw.
+        expect(() => handle.reportNow()).not.toThrow();
+    });
+    it('returns the existing handle on second call (idempotent)', () => {
+        const a = initQualityReporter();
+        const b = initQualityReporter();
+        expect(a).toBe(b);
+    });
+    it('skips reporting when window.__FAS_QUALITY_DISABLE is set', () => {
+        window.__FAS_QUALITY_DISABLE = true;
+        const handle = initQualityReporter();
+        expect(handle).toBeDefined();
+        // Internal marker should still be set so we don't re-attach.
+        expect(window.__FAS_QUALITY_REPORTER__).toBeDefined();
+    });
+    it('posts a snapshot when an iframe parent requests via fas:quality:request', () => {
+        // Simulate iframed: fake out window.parent so it's NOT === window.
+        const fakeParent = { postMessage: vi.fn() };
+        Object.defineProperty(window, 'parent', { value: fakeParent, configurable: true });
+        const handle = initQualityReporter();
+        // Trigger a manual snapshot post.
+        handle.reportNow();
+        expect(fakeParent.postMessage).toHaveBeenCalled();
+        const arg = fakeParent.postMessage.mock.calls[0]?.[0];
+        expect(arg.type).toBe('fas:quality');
+        expect(arg.schema).toBe(1);
+        // Restore parent.
+        Object.defineProperty(window, 'parent', { value: window, configurable: true });
+    });
+});
+//# sourceMappingURL=index.test.js.map

package/dist/index.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.js","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@freeappstore/quality",
+  "version": "0.1.0",
+  "description": "Quality reporter — apps post viewport metrics to a parent dashboard via postMessage so /quality can audit fit / scroll / clipping at every reference viewport without driving a headless browser per app.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "homepage": "https://github.com/freeappstore-online/sdk#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/freeappstore-online/sdk.git",
+    "directory": "packages/quality"
+  },
+  "bugs": {
+    "url": "https://github.com/freeappstore-online/sdk/issues"
+  },
+  "keywords": [
+    "freeappstore",
+    "freegamestore",
+    "quality",
+    "audit",
+    "viewport"
+  ],
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "devDependencies": {
+    "jsdom": "^25.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}