@freeappstore/compliance 0.2.0 → 0.3.0

package/dist/checks/no-scroll.d.ts

@@ -0,0 +1,24 @@
+import type { CheckResult } from '../types.js';
+/**
+ * Games on FreeGameStore must fit the viewport — no horizontal or
+ * vertical scroll at the document level. Static analysis catches the
+ * common CSS / inline-style anti-patterns:
+ *
+ *   - `overflow: scroll` or `overflow: auto` on `html` or `body`.
+ *   - `min-height: 100vh` on `html` / `body` (creates page that's at
+ *     least viewport-tall, but content + topbar = > 100vh = scroll).
+ *   - Missing the `100svh` / `100vh` height constraint on the layout
+ *     wrapper (loose check — "at least one root element should hard-cap
+ *     to viewport height").
+ *
+ * Runtime guarantees (real DOM measurement) live in the e2e Playwright
+ * suite; this check exists as a fast pre-publish gate so creators
+ * don't ship trivially-scrolling games.
+ *
+ * Apps (FreeAppStore) are not subject to this check — the apps Shell
+ * wraps them in a sidebar+main layout that legitimately scrolls. We
+ * detect "is this a game project" by looking for the @freeappstore/games
+ * dep, the canonical signal that the app uses GameShell.
+ */
+export declare function checkNoScroll(repoDir: string): Promise<CheckResult>;
+//# sourceMappingURL=no-scroll.d.ts.map

package/dist/checks/no-scroll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-scroll.d.ts","sourceRoot":"","sources":["../../src/checks/no-scroll.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG/C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA6EzE"}

package/dist/checks/no-scroll.js

@@ -0,0 +1,143 @@
+import { readFile } from 'node:fs/promises';
+import { extname, relative } from 'node:path';
+import { walk } from '../lib/walk.js';
+/**
+ * Games on FreeGameStore must fit the viewport — no horizontal or
+ * vertical scroll at the document level. Static analysis catches the
+ * common CSS / inline-style anti-patterns:
+ *
+ *   - `overflow: scroll` or `overflow: auto` on `html` or `body`.
+ *   - `min-height: 100vh` on `html` / `body` (creates page that's at
+ *     least viewport-tall, but content + topbar = > 100vh = scroll).
+ *   - Missing the `100svh` / `100vh` height constraint on the layout
+ *     wrapper (loose check — "at least one root element should hard-cap
+ *     to viewport height").
+ *
+ * Runtime guarantees (real DOM measurement) live in the e2e Playwright
+ * suite; this check exists as a fast pre-publish gate so creators
+ * don't ship trivially-scrolling games.
+ *
+ * Apps (FreeAppStore) are not subject to this check — the apps Shell
+ * wraps them in a sidebar+main layout that legitimately scrolls. We
+ * detect "is this a game project" by looking for the @freeappstore/games
+ * dep, the canonical signal that the app uses GameShell.
+ */
+export async function checkNoScroll(repoDir) {
+    // Skip apps — only games are subject to no-scroll.
+    if (!(await isGame(repoDir))) {
+        return {
+            name: 'No scroll (games only)',
+            status: 'pass',
+            detail: 'not a game project — check skipped',
+        };
+    }
+    const issues = [];
+    let sawViewportLock = false;
+    for await (const file of walk(repoDir)) {
+        const ext = extname(file).toLowerCase();
+        if (!SCAN_EXTS.has(ext))
+            continue;
+        const content = await readFile(file, 'utf8').catch(() => '');
+        if (!content)
+            continue;
+        const rel = relative(repoDir, file);
+        // 1. Forbidden overflow declarations on root elements.
+        for (const re of FORBIDDEN_OVERFLOW) {
+            const m = re.exec(content);
+            if (m) {
+                const line = lineNumberAt(content, m.index);
+                issues.push(`${rel}:${line} ${m[0]} — root scrolling not allowed in games`);
+            }
+        }
+        // 2. min-height on root elements (creates pages taller than viewport).
+        for (const re of FORBIDDEN_MIN_HEIGHT) {
+            const m = re.exec(content);
+            if (m) {
+                const line = lineNumberAt(content, m.index);
+                issues.push(`${rel}:${line} ${m[0]} — use exact viewport height (100svh) instead`);
+            }
+        }
+        // 3. Look for at least one viewport-lock pattern. GameShell sets
+        // `height: 100svh` on a fixed wrapper; we accept any 100svh / 100vh
+        // declaration as evidence the game considered viewport sizing.
+        if (VIEWPORT_LOCK.test(content))
+            sawViewportLock = true;
+        if (issues.length >= 8)
+            break;
+    }
+    if (issues.length > 0) {
+        return {
+            name: 'No scroll (games only)',
+            status: 'fail',
+            detail: `${issues.length} scroll-enabling pattern${issues.length === 1 ? '' : 's'}`,
+            suggestions: [
+                ...issues.slice(0, 5),
+                ...(issues.length > 5 ? [`...and ${issues.length - 5} more`] : []),
+                'Use <GameShell> from @freeappstore/games — it locks layout to 100svh.',
+                'Inside the play area, use overflow: hidden instead of overflow: auto.',
+            ],
+        };
+    }
+    if (!sawViewportLock) {
+        return {
+            name: 'No scroll (games only)',
+            status: 'warn',
+            detail: 'no 100svh/100vh viewport lock detected — game may scroll on small viewports',
+            suggestions: [
+                'Wrap your game in <GameShell> from @freeappstore/games, or',
+                'Add `height: 100svh` to your root container.',
+            ],
+        };
+    }
+    return {
+        name: 'No scroll (games only)',
+        status: 'pass',
+        detail: 'viewport-locked layout detected',
+    };
+}
+const SCAN_EXTS = new Set(['.css', '.scss', '.tsx', '.ts', '.jsx', '.js', '.html']);
+// Match `overflow: scroll` and `overflow: auto` on html/body selectors,
+// or as bare global rules in CSS. Conservative: only flags when paired
+// with html/body — avoids false positives for component-scoped overflow.
+//
+// IMPORTANT: no `g` flag. Module-scoped regexes with `g` share lastIndex
+// across parallel test runs and produce flaky matches; we only need
+// first-match-per-file anyway.
+const FORBIDDEN_OVERFLOW = [
+    /(?:^|[\s,{])(?:html|body)\s*\{[^}]*overflow\s*:\s*(?:scroll|auto)/im,
+    /(?:^|[\s,{])(?:html|body)\s*\{[^}]*overflow-(?:x|y)\s*:\s*(?:scroll|auto)/im,
+];
+const FORBIDDEN_MIN_HEIGHT = [
+    /(?:^|[\s,{])(?:html|body)\s*\{[^}]*min-height\s*:\s*100vh/im,
+];
+const VIEWPORT_LOCK = /(?:height|max-height)\s*:\s*100(?:s?vh)|GameShell|@freeappstore\/games/i;
+async function isGame(repoDir) {
+    // Fast path: look for the explicit games-sdk dep in any package.json.
+    // Falls back to scanning JSX for GameShell import — catches cases
+    // where the dep is hoisted to a workspace root.
+    for await (const file of walk(repoDir)) {
+        const base = file.split('/').pop() ?? '';
+        if (base !== 'package.json')
+            continue;
+        const content = await readFile(file, 'utf8').catch(() => '');
+        if (/@freeappstore\/games/.test(content))
+            return true;
+    }
+    for await (const file of walk(repoDir)) {
+        const ext = extname(file).toLowerCase();
+        if (ext !== '.tsx' && ext !== '.ts')
+            continue;
+        const content = await readFile(file, 'utf8').catch(() => '');
+        if (/from\s+['"]@freeappstore\/games['"]/.test(content))
+            return true;
+    }
+    return false;
+}
+function lineNumberAt(content, index) {
+    let n = 1;
+    for (let i = 0; i < index; i++)
+        if (content.charCodeAt(i) === 10)
+            n++;
+    return n;
+}
+//# sourceMappingURL=no-scroll.js.map

package/dist/checks/no-scroll.js.map

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

package/dist/checks/no-scroll.test.d.ts

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

package/dist/checks/no-scroll.test.d.ts.map

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

package/dist/checks/no-scroll.test.js

@@ -0,0 +1,105 @@
+import { describe, it, expect } from 'vitest';
+import { mkdtemp, mkdir, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { checkNoScroll } from './no-scroll.js';
+async function fixture(files) {
+    const dir = await mkdtemp(join(tmpdir(), 'fas-noscroll-'));
+    for (const [path, content] of Object.entries(files)) {
+        const full = join(dir, path);
+        await mkdir(join(full, '..'), { recursive: true });
+        await writeFile(full, content);
+    }
+    return dir;
+}
+const GAME_DEPS = JSON.stringify({
+    name: 'my-game',
+    dependencies: { '@freeappstore/games': '^0.1.0' },
+});
+describe('checkNoScroll', () => {
+    it('passes (skipped) when the project is not a game', async () => {
+        const dir = await fixture({
+            'package.json': JSON.stringify({ name: 'my-app' }),
+            'web/src/index.css': 'body { overflow: scroll; }',
+        });
+        const r = await checkNoScroll(dir);
+        expect(r.status).toBe('pass');
+        expect(r.detail).toMatch(/not a game/);
+    });
+    it('detects @freeappstore/games dep as the game signal', async () => {
+        const dir = await fixture({
+            'package.json': GAME_DEPS,
+            'web/src/index.css': 'body { height: 100svh; }',
+            'web/src/App.tsx': 'import { GameShell } from "@freeappstore/games";',
+        });
+        const r = await checkNoScroll(dir);
+        // Should at least run the check, not skip.
+        expect(r.detail).not.toMatch(/not a game/);
+    });
+    it('fails when html/body declares overflow: scroll', async () => {
+        const dir = await fixture({
+            'package.json': GAME_DEPS,
+            'web/src/index.css': 'html { overflow: scroll; }',
+        });
+        const r = await checkNoScroll(dir);
+        expect(r.status).toBe('fail');
+        expect(r.suggestions?.join(' ')).toMatch(/GameShell/);
+    });
+    it('fails when html/body declares overflow: auto', async () => {
+        const dir = await fixture({
+            'package.json': GAME_DEPS,
+            'web/src/index.css': 'body { overflow: auto; }',
+        });
+        const r = await checkNoScroll(dir);
+        expect(r.status).toBe('fail');
+    });
+    it('fails on overflow-y: scroll on body', async () => {
+        const dir = await fixture({
+            'package.json': GAME_DEPS,
+            'web/src/index.css': 'body { overflow-y: scroll; padding: 0; }',
+        });
+        const r = await checkNoScroll(dir);
+        expect(r.status).toBe('fail');
+    });
+    it('fails on min-height: 100vh on body (creates page taller than viewport)', async () => {
+        const dir = await fixture({
+            'package.json': GAME_DEPS,
+            'web/src/index.css': 'body { min-height: 100vh; }',
+        });
+        const r = await checkNoScroll(dir);
+        expect(r.status).toBe('fail');
+        expect(r.suggestions?.join(' ')).toMatch(/100svh/);
+    });
+    it('warns when there is no viewport-lock evidence', async () => {
+        const dir = await fixture({
+            'package.json': GAME_DEPS,
+            'web/src/index.css': 'body { padding: 0; }',
+            'web/src/App.tsx': 'export default function App() { return <div>game</div>; }',
+        });
+        const r = await checkNoScroll(dir);
+        expect(r.status).toBe('warn');
+        expect(r.detail).toMatch(/viewport lock/);
+    });
+    it('passes when GameShell is imported (the canonical viewport lock)', async () => {
+        const dir = await fixture({
+            'package.json': GAME_DEPS,
+            'web/src/App.tsx': `
+        import { GameShell, GameTopbar } from "@freeappstore/games";
+        export default function App() {
+          return <GameShell topbar={<GameTopbar score={0} />}>game</GameShell>;
+        }
+      `,
+        });
+        const r = await checkNoScroll(dir);
+        expect(r.status).toBe('pass');
+    });
+    it('passes when CSS has explicit 100svh height lock', async () => {
+        const dir = await fixture({
+            'package.json': GAME_DEPS,
+            'web/src/index.css': '.game-root { height: 100svh; overflow: hidden; }',
+        });
+        const r = await checkNoScroll(dir);
+        expect(r.status).toBe('pass');
+    });
+});
+//# sourceMappingURL=no-scroll.test.js.map

package/dist/checks/no-scroll.test.js.map

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

package/dist/checks/unsafe-vh.d.ts

@@ -0,0 +1,24 @@
+import type { CheckResult } from '../types.js';
+/**
+ * Flag `100vh` (and Tailwind shortcuts that compile to it) in source.
+ *
+ * Why: on iOS Safari with the URL bar visible, `100vh` resolves to the
+ * *layout* viewport (e.g. 852px on iPhone 15) but the actual visible
+ * area is the *visual* viewport (~750px). An element sized at `100vh`
+ * is then ~100px taller than the screen, forcing the page to scroll on
+ * first load. This is invisible to headless Playwright (no dynamic URL
+ * bar) and to the static audit Worker (no rendering), so this fast
+ * static rule is the cheapest place to catch it.
+ *
+ * Fix: use `100svh` (small viewport height — accounts for visible
+ * browser UI) for "as tall as the screen" intent, or `100dvh` (dynamic
+ * viewport height — recomputes as the URL bar shows/hides) for full-
+ * height containers that should grow when chrome retracts.
+ *
+ * Scope: warn-by-default, not fail. There ARE legitimate uses of
+ * `100vh` (intentionally taking layout-viewport height for hero
+ * sections that should stay constant as URL bar moves). Creators can
+ * acknowledge by leaving an `// allow-100vh` comment on the same line.
+ */
+export declare function checkUnsafeVh(repoDir: string): Promise<CheckResult>;
+//# sourceMappingURL=unsafe-vh.d.ts.map

package/dist/checks/unsafe-vh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unsafe-vh.d.ts","sourceRoot":"","sources":["../../src/checks/unsafe-vh.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG/C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA2CzE"}

package/dist/checks/unsafe-vh.js

@@ -0,0 +1,110 @@
+import { readFile } from 'node:fs/promises';
+import { extname, relative } from 'node:path';
+import { walk } from '../lib/walk.js';
+/**
+ * Flag `100vh` (and Tailwind shortcuts that compile to it) in source.
+ *
+ * Why: on iOS Safari with the URL bar visible, `100vh` resolves to the
+ * *layout* viewport (e.g. 852px on iPhone 15) but the actual visible
+ * area is the *visual* viewport (~750px). An element sized at `100vh`
+ * is then ~100px taller than the screen, forcing the page to scroll on
+ * first load. This is invisible to headless Playwright (no dynamic URL
+ * bar) and to the static audit Worker (no rendering), so this fast
+ * static rule is the cheapest place to catch it.
+ *
+ * Fix: use `100svh` (small viewport height — accounts for visible
+ * browser UI) for "as tall as the screen" intent, or `100dvh` (dynamic
+ * viewport height — recomputes as the URL bar shows/hides) for full-
+ * height containers that should grow when chrome retracts.
+ *
+ * Scope: warn-by-default, not fail. There ARE legitimate uses of
+ * `100vh` (intentionally taking layout-viewport height for hero
+ * sections that should stay constant as URL bar moves). Creators can
+ * acknowledge by leaving an `// allow-100vh` comment on the same line.
+ */
+export async function checkUnsafeVh(repoDir) {
+    const issues = [];
+    for await (const file of walk(repoDir)) {
+        const ext = extname(file).toLowerCase();
+        if (!SCAN_EXTS.has(ext))
+            continue;
+        const content = await readFile(file, 'utf8').catch(() => '');
+        if (!content)
+            continue;
+        const rel = relative(repoDir, file);
+        for (const { re, label } of PATTERNS) {
+            // Reset lastIndex defensively; we use `g` to find all matches.
+            re.lastIndex = 0;
+            let m;
+            while ((m = re.exec(content)) !== null) {
+                const line = lineNumberAt(content, m.index);
+                // Allow opt-out via an inline `allow-100vh` comment on the same line.
+                if (lineHasAllowComment(content, m.index))
+                    continue;
+                issues.push(`${rel}:${line} ${label} — use 100svh or 100dvh`);
+            }
+        }
+    }
+    if (issues.length === 0) {
+        return {
+            name: 'No unsafe 100vh',
+            status: 'pass',
+            detail: 'no 100vh / h-screen patterns found',
+        };
+    }
+    const head = issues.slice(0, MAX_REPORTED);
+    const tail = issues.length > MAX_REPORTED ? [`...and ${issues.length - MAX_REPORTED} more`] : [];
+    return {
+        name: 'No unsafe 100vh',
+        status: 'warn',
+        detail: `${issues.length} occurrence${issues.length === 1 ? '' : 's'} of 100vh / h-screen — breaks on iOS Safari with URL bar visible`,
+        suggestions: [
+            ...head,
+            ...tail,
+            'Replace with 100svh (preferred) or 100dvh. Add `// allow-100vh` on the line if intentional.',
+        ],
+    };
+}
+const SCAN_EXTS = new Set(['.css', '.scss', '.tsx', '.ts', '.jsx', '.js', '.html']);
+const MAX_REPORTED = 5;
+/**
+ * Patterns to flag. Each is global (`g`) so we find every occurrence.
+ *
+ * Boundary handling:
+ * - `100vh` uses `\b` since CSS values are tokenised normally.
+ * - Tailwind classes use a custom hyphen-aware boundary
+ *   `(?<![\w-])foo(?![\w-])` so `h-screen` doesn't match inside
+ *   `min-h-screen` (and we don't double-count `min-h-screen` as both
+ *   itself and its `h-screen` substring).
+ */
+const PATTERNS = [
+    { re: /\b100vh\b/g, label: '100vh' },
+    // Tailwind: h-screen → height: 100vh; same for min-/max-.
+    { re: /(?<![\w-])h-screen(?![\w-])/g, label: 'h-screen (Tailwind: → 100vh)' },
+    { re: /(?<![\w-])min-h-screen(?![\w-])/g, label: 'min-h-screen (Tailwind: → min-height: 100vh)' },
+    { re: /(?<![\w-])max-h-screen(?![\w-])/g, label: 'max-h-screen (Tailwind: → max-height: 100vh)' },
+];
+function lineNumberAt(content, index) {
+    let n = 1;
+    for (let i = 0; i < index; i++)
+        if (content.charCodeAt(i) === 10)
+            n++;
+    return n;
+}
+/**
+ * True if the rest of the line containing `index` includes the literal
+ * string "allow-100vh" (typically inside a comment). Cheap and cheerful
+ * — doesn't validate comment syntax, just trusts the marker.
+ */
+function lineHasAllowComment(content, index) {
+    // Find end of the current line.
+    let end = content.indexOf('\n', index);
+    if (end === -1)
+        end = content.length;
+    // Walk back to the start of the line for full context.
+    let start = content.lastIndexOf('\n', index);
+    if (start === -1)
+        start = 0;
+    return content.slice(start, end).includes('allow-100vh');
+}
+//# sourceMappingURL=unsafe-vh.js.map

package/dist/checks/unsafe-vh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unsafe-vh.js","sourceRoot":"","sources":["../../src/checks/unsafe-vh.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE9C,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAAe;IACjD,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACvC,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;QACxC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,SAAS;QAClC,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;QAC7D,IAAI,CAAC,OAAO;YAAE,SAAS;QACvB,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAEpC,KAAK,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,QAAQ,EAAE,CAAC;YACrC,+DAA+D;YAC/D,EAAE,CAAC,SAAS,GAAG,CAAC,CAAC;YACjB,IAAI,CAAyB,CAAC;YAC9B,OAAO,CAAC,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;gBACvC,MAAM,IAAI,GAAG,YAAY,CAAC,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;gBAC5C,sEAAsE;gBACtE,IAAI,mBAAmB,CAAC,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC;oBAAE,SAAS;gBACpD,MAAM,CAAC,IAAI,CAAC,GAAG,GAAG,IAAI,IAAI,IAAI,KAAK,yBAAyB,CAAC,CAAC;YAChE,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO;YACL,IAAI,EAAE,iBAAiB;YACvB,MAAM,EAAE,MAAM;YACd,MAAM,EAAE,oCAAoC;SAC7C,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC;IAC3C,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC,UAAU,MAAM,CAAC,MAAM,GAAG,YAAY,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACjG,OAAO;QACL,IAAI,EAAE,iBAAiB;QACvB,MAAM,EAAE,MAAM;QACd,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,cAAc,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,kEAAkE;QACtI,WAAW,EAAE;YACX,GAAG,IAAI;YACP,GAAG,IAAI;YACP,6FAA6F;SAC9F;KACF,CAAC;AACJ,CAAC;AAED,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;AACpF,MAAM,YAAY,GAAG,CAAC,CAAC;AAEvB;;;;;;;;;GASG;AACH,MAAM,QAAQ,GAAyC;IACrD,EAAE,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE;IACpC,0DAA0D;IAC1D,EAAE,EAAE,EAAE,8BAA8B,EAAE,KAAK,EAAE,8BAA8B,EAAE;IAC7E,EAAE,EAAE,EAAE,kCAAkC,EAAE,KAAK,EAAE,8CAA8C,EAAE;IACjG,EAAE,EAAE,EAAE,kCAAkC,EAAE,KAAK,EAAE,8CAA8C,EAAE;CAClG,CAAC;AAEF,SAAS,YAAY,CAAC,OAAe,EAAE,KAAa;IAClD,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE;QAAE,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,EAAE;YAAE,CAAC,EAAE,CAAC;IACtE,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;GAIG;AACH,SAAS,mBAAmB,CAAC,OAAe,EAAE,KAAa;IACzD,gCAAgC;IAChC,IAAI,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACvC,IAAI,GAAG,KAAK,CAAC,CAAC;QAAE,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC;IACrC,uDAAuD;IACvD,IAAI,KAAK,GAAG,OAAO,CAAC,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC7C,IAAI,KAAK,KAAK,CAAC,CAAC;QAAE,KAAK,GAAG,CAAC,CAAC;IAC5B,OAAO,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;AAC3D,CAAC"}

package/dist/checks/unsafe-vh.test.d.ts

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

package/dist/checks/unsafe-vh.test.d.ts.map

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

package/dist/checks/unsafe-vh.test.js

@@ -0,0 +1,115 @@
+import { describe, it, expect } from 'vitest';
+import { mkdtemp, mkdir, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { checkUnsafeVh } from './unsafe-vh.js';
+async function fixture(files) {
+    const dir = await mkdtemp(join(tmpdir(), 'fas-unsafe-vh-'));
+    for (const [path, content] of Object.entries(files)) {
+        const full = join(dir, path);
+        await mkdir(join(full, '..'), { recursive: true });
+        await writeFile(full, content);
+    }
+    return dir;
+}
+describe('checkUnsafeVh', () => {
+    it('passes when no 100vh appears anywhere', async () => {
+        const dir = await fixture({
+            'web/src/index.css': 'body { height: 100svh; }',
+            'web/src/App.tsx': 'export default () => <div className="h-screen-not-really" />;',
+        });
+        const r = await checkUnsafeVh(dir);
+        expect(r.status).toBe('pass');
+        expect(r.detail).toMatch(/no 100vh/);
+    });
+    it('warns on a literal 100vh in CSS', async () => {
+        const dir = await fixture({
+            'web/src/index.css': '.full { height: 100vh; }',
+        });
+        const r = await checkUnsafeVh(dir);
+        expect(r.status).toBe('warn');
+        expect(r.detail).toMatch(/1 occurrence/);
+        expect(r.suggestions?.join('\n')).toMatch(/web\/src\/index\.css:1.*100vh/);
+        expect(r.suggestions?.join('\n')).toMatch(/100svh.*100dvh/);
+    });
+    it('warns on Tailwind h-screen / min-h-screen / max-h-screen', async () => {
+        const dir = await fixture({
+            'web/src/App.tsx': `
+        export default () => (
+          <div className="h-screen">
+            <header className="min-h-screen" />
+            <main className="max-h-screen" />
+          </div>
+        );
+      `,
+        });
+        const r = await checkUnsafeVh(dir);
+        expect(r.status).toBe('warn');
+        expect(r.detail).toMatch(/3 occurrences/);
+        const suggestionText = r.suggestions?.join('\n') ?? '';
+        expect(suggestionText).toMatch(/h-screen/);
+        expect(suggestionText).toMatch(/min-h-screen/);
+        expect(suggestionText).toMatch(/max-h-screen/);
+    });
+    it('respects the `allow-100vh` opt-out comment on the same line', async () => {
+        const dir = await fixture({
+            'web/src/index.css': `
+        .hero { height: 100vh; /* allow-100vh — intentional, hero stays constant under URL bar */ }
+      `,
+        });
+        const r = await checkUnsafeVh(dir);
+        expect(r.status).toBe('pass');
+    });
+    it('still flags a different line even when one line has the opt-out', async () => {
+        const dir = await fixture({
+            'web/src/index.css': `.a { height: 100vh; /* allow-100vh */ }
+.b { height: 100vh; }
+`,
+        });
+        const r = await checkUnsafeVh(dir);
+        expect(r.status).toBe('warn');
+        expect(r.detail).toMatch(/1 occurrence/); // only the un-opt-out line
+    });
+    it('does not flag the strings "100svh" / "100dvh" (the recommended fixes)', async () => {
+        const dir = await fixture({
+            'web/src/index.css': `
+        .a { height: 100svh; }
+        .b { height: 100dvh; }
+      `,
+        });
+        const r = await checkUnsafeVh(dir);
+        expect(r.status).toBe('pass');
+    });
+    it('does not match identifiers that contain "100vh" as a substring', async () => {
+        const dir = await fixture({
+            // `var100vh` and `--my100vhvar` aren't actual unit usage; word
+            // boundaries must keep us from flagging them.
+            'web/src/foo.ts': 'const var100vh = 1; const x = "--my100vhvar";',
+        });
+        const r = await checkUnsafeVh(dir);
+        expect(r.status).toBe('pass');
+    });
+    it('caps reported issues at 5 and notes the rest', async () => {
+        const lines = Array.from({ length: 8 }, (_, i) => `.x${i} { height: 100vh; }`).join('\n');
+        const dir = await fixture({ 'web/src/index.css': lines });
+        const r = await checkUnsafeVh(dir);
+        expect(r.status).toBe('warn');
+        expect(r.detail).toMatch(/8 occurrences/);
+        // 5 file:line entries + 1 "...and N more" + 1 final "Replace with..." advice = 7
+        expect(r.suggestions?.length).toBe(7);
+        expect(r.suggestions?.[5]).toMatch(/and 3 more/);
+    });
+    it('scans CSS, JS, TS, JSX, TSX, HTML — but skips other extensions', async () => {
+        const dir = await fixture({
+            'web/src/index.css': '.a { height: 100vh; }',
+            'web/src/App.jsx': 'const x = "h-screen";', // string with the class — still flagged (we can't know intent)
+            'docs/notes.md': 'Use 100vh somewhere', // Markdown — should NOT be scanned
+            'web/src/foo.scss': '$h: 100vh;',
+        });
+        const r = await checkUnsafeVh(dir);
+        expect(r.status).toBe('warn');
+        // 3 hits: index.css, App.jsx, foo.scss. notes.md ignored.
+        expect(r.detail).toMatch(/3 occurrences/);
+    });
+});
+//# sourceMappingURL=unsafe-vh.test.js.map

package/dist/checks/unsafe-vh.test.js.map

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

package/dist/checks/viewport-support.d.ts

@@ -0,0 +1,23 @@
+import type { CheckResult } from '../types.js';
+/**
+ * Apps and games must declare which screens and orientations they
+ * support, so the storefront can render a coverage badge ("works on
+ * 92% of devices · portrait + landscape") and visitors know what to
+ * expect before they tap.
+ *
+ * Two declarations are required, both in `web/public/manifest.json`:
+ *
+ *   "orientation":           "any" | "portrait" | "landscape" |
+ *                            "portrait-primary" | "landscape-primary"
+ *   "min_viewport_width":     320 | 360 | 414 | 600 | 768 | 1024
+ *
+ * `orientation` is a standard PWA manifest field. `min_viewport_width`
+ * is a custom platform field — the smallest screen width (in CSS px)
+ * the app renders correctly at. The storefront maps that to a global
+ * device-share percentile to render coverage.
+ *
+ * If you genuinely don't care about orientation, set `"any"`. Don't
+ * leave it off — that's the only value that returns a fail.
+ */
+export declare function checkViewportSupport(repoDir: string): Promise<CheckResult>;
+//# sourceMappingURL=viewport-support.d.ts.map

package/dist/checks/viewport-support.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewport-support.d.ts","sourceRoot":"","sources":["../../src/checks/viewport-support.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA+DhF"}