game-harness 1.0.0

package/docs/sourcey.config.ts

@@ -0,0 +1,79 @@
+import { defineConfig, markdown } from 'sourcey';
+
+export default defineConfig({
+  name: 'Game Harness',
+  siteUrl: 'https://jonbogaty.com',
+  baseUrl: '/game-harness',
+  theme: {
+    preset: 'default',
+    colors: {
+      primary: '#0f766e',
+      light: '#2dd4bf',
+      dark: '#115e59',
+    },
+    fonts: {
+      sans: 'Inter, system-ui, sans-serif',
+      mono: 'JetBrains Mono, ui-monospace, monospace',
+    },
+    layout: {
+      content: '48rem',
+    },
+  },
+  prettyUrls: 'slash',
+  favicon: './assets/game-harness-hero.webp',
+  ogImage: './assets/game-harness-hero.webp',
+  repo: 'https://github.com/jbcom/game-harness',
+  editBranch: 'main',
+  editBasePath: 'docs',
+  navbar: {
+    links: [
+      { type: 'github', href: 'https://github.com/jbcom/game-harness' },
+      {
+        type: 'link',
+        label: 'npm',
+        href: 'https://www.npmjs.com/package/game-harness',
+      },
+    ],
+  },
+  footer: {
+    links: [
+      { type: 'github', href: 'https://github.com/jbcom/game-harness' },
+      { type: 'link', label: 'Security', href: 'https://jonbogaty.com/game-harness/security/' },
+    ],
+  },
+  navigation: {
+    tabs: [
+      {
+        tab: 'Documentation',
+        slug: '',
+        source: markdown({
+          groups: [
+            {
+              group: 'Getting Started',
+              pages: ['introduction', 'getting-started', 'quick-start', 'entry-points'],
+            },
+            {
+              group: 'Guides',
+              pages: [
+                'guides/playwright',
+                'guides/vitest',
+                'guides/chromium-and-silent-qa',
+                'guides/production-runtime',
+                'guides/visual-battery',
+                'guides/lighthouse-and-release-ladder',
+              ],
+            },
+            {
+              group: 'Reference',
+              pages: ['architecture', 'reference/troubleshooting'],
+            },
+            {
+              group: 'Project',
+              pages: ['contributing', 'security', 'changelog', 'agent-guide'],
+            },
+          ],
+        }),
+      },
+    ],
+  },
+});

package/llms.txt

@@ -0,0 +1,32 @@
+# Game Harness
+
+> Release-grade browser QA primitives for TypeScript games: silent Playwright/Vitest sessions, deterministic screenshots, production-runtime proof, and Lighthouse gates.
+
+Game Harness is a focused library, not a test framework. It supplies a
+reusable, fail-closed safety and orchestration layer around Playwright and
+Vitest Browser Mode; a consuming game keeps its own journeys, assertions,
+art direction, and audio engine. Install from npm as
+`game-harness`, Node 22 or newer. Import only the subpath
+entry point a game needs — the package root stays peer-free and never loads
+Playwright or Vitest. See AGENTS.md at the repository root for an
+agent-oriented quick reference before writing code against this package.
+
+## Docs
+
+- [Getting started](https://jonbogaty.com/game-harness/getting-started/): Installation and the current release/conformance matrix.
+- [Quick start](https://jonbogaty.com/game-harness/quick-start/): Wire up the silent runtime marker and a first Playwright config.
+- [Entry points](https://jonbogaty.com/game-harness/entry-points/): The full subpath-export map and required peers.
+- [Playwright guide](https://jonbogaty.com/game-harness/guides/playwright/): Deterministic ports, strict-port preview servers, device tiers.
+- [Vitest Browser Mode guide](https://jonbogaty.com/game-harness/guides/vitest/): Headed real-Chromium Vitest projects.
+- [Chromium launch profile & Silent QA guide](https://jonbogaty.com/game-harness/guides/chromium-and-silent-qa/): The peer-free primitives behind every silent browser launch.
+- [Production runtime verification guide](https://jonbogaty.com/game-harness/guides/production-runtime/): Turning a build into fail-closed runtime evidence.
+- [Visual battery guide](https://jonbogaty.com/game-harness/guides/visual-battery/): Deterministic screenshot baseline orchestration.
+- [Lighthouse presets & release ladder guide](https://jonbogaty.com/game-harness/guides/lighthouse-and-release-ladder/): CI Lighthouse assertions and the release-step orchestrator.
+- [Architecture reference](https://jonbogaty.com/game-harness/reference/architecture/): Module boundaries, runtime evidence flow, build/distribution guarantees.
+- [Troubleshooting reference](https://jonbogaty.com/game-harness/reference/troubleshooting/): Common failure modes and releases/support.
+
+## Optional
+
+- [Repository](https://github.com/jbcom/game-harness): Source, issues, and pull requests.
+- [AGENTS.md](https://github.com/jbcom/game-harness/blob/main/AGENTS.md): Agent-facing quick reference for using this package correctly.
+- [CHANGELOG](https://github.com/jbcom/game-harness/blob/main/CHANGELOG.md): Release history, managed by release-please.

package/maestro/smoke.template.yaml

@@ -0,0 +1,11 @@
+# Maestro smoke-test template — copy to <repo>/.maestro/smoke.yaml and fill
+# in the placeholders below. This is the minimal "does the app boot and
+# render its first screen" flow; add game-specific flows alongside it as
+# separate .maestro/*.yaml files (they're app-specific user journeys, not
+# shareable config — see game-harness's package notes).
+appId: __APP_ID__ # e.g. com.jbcom.kuroga — must match capacitor.config.ts's appId
+---
+- launchApp
+- assertVisible:
+    id: __ROOT_ELEMENT_ID__ # e.g. the canvas mount root or title-screen testID
+- takeScreenshot: smoke-boot

package/package.json

@@ -0,0 +1,196 @@
+{
+  "name": "game-harness",
+  "version": "1.0.0",
+  "description": "Release-grade browser QA primitives for TypeScript games: silent Playwright/Vitest sessions, deterministic screenshots, runtime proof, and Lighthouse gates.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jbcom/game-harness.git"
+  },
+  "files": [
+    "AGENTS.md",
+    "bin",
+    "CHANGELOG.md",
+    "dist",
+    "docs",
+    "llms.txt",
+    "maestro",
+    "LICENSE",
+    "README.md"
+  ],
+  "bin": {
+    "game-harness-visual-battery": "bin/test-harness-visual-battery.mjs",
+    "test-harness-visual-battery": "bin/test-harness-visual-battery.mjs"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/types/index.d.cts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./vitest": {
+      "import": {
+        "types": "./dist/types/browser-config.d.ts",
+        "default": "./dist/esm/browser-config.js"
+      },
+      "require": {
+        "types": "./dist/types/browser-config.d.cts",
+        "default": "./dist/cjs/browser-config.js"
+      }
+    },
+    "./playwright": {
+      "import": {
+        "types": "./dist/types/playwright-config.d.ts",
+        "default": "./dist/esm/playwright-config.js"
+      },
+      "require": {
+        "types": "./dist/types/playwright-config.d.cts",
+        "default": "./dist/cjs/playwright-config.js"
+      }
+    },
+    "./silent-qa": {
+      "import": {
+        "types": "./dist/types/silent-qa.d.ts",
+        "default": "./dist/esm/silent-qa.js"
+      },
+      "require": {
+        "types": "./dist/types/silent-qa.d.cts",
+        "default": "./dist/cjs/silent-qa.js"
+      }
+    },
+    "./production-runtime": {
+      "import": {
+        "types": "./dist/types/production-runtime.d.ts",
+        "default": "./dist/esm/production-runtime.js"
+      },
+      "require": {
+        "types": "./dist/types/production-runtime.d.cts",
+        "default": "./dist/cjs/production-runtime.js"
+      }
+    },
+    "./chromium": {
+      "import": {
+        "types": "./dist/types/chromium-launch.d.ts",
+        "default": "./dist/esm/chromium-launch.js"
+      },
+      "require": {
+        "types": "./dist/types/chromium-launch.d.cts",
+        "default": "./dist/cjs/chromium-launch.js"
+      }
+    },
+    "./lighthouse": {
+      "import": {
+        "types": "./dist/types/lighthouse.d.ts",
+        "default": "./dist/esm/lighthouse.js"
+      },
+      "require": {
+        "types": "./dist/types/lighthouse.d.cts",
+        "default": "./dist/cjs/lighthouse.js"
+      }
+    },
+    "./release-ladder": {
+      "import": {
+        "types": "./dist/types/release-ladder.d.ts",
+        "default": "./dist/esm/release-ladder.js"
+      },
+      "require": {
+        "types": "./dist/types/release-ladder.d.cts",
+        "default": "./dist/cjs/release-ladder.js"
+      }
+    },
+    "./visual-battery": {
+      "import": {
+        "types": "./dist/types/visual-battery.d.ts",
+        "default": "./dist/esm/visual-battery.js"
+      },
+      "require": {
+        "types": "./dist/types/visual-battery.d.cts",
+        "default": "./dist/cjs/visual-battery.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "dependencies": {
+    "cross-spawn": "7.0.6",
+    "get-port": "7.2.0"
+  },
+  "peerDependencies": {
+    "@playwright/test": ">=1.62.1 <2",
+    "@vitest/browser-playwright": ">=4.1.10 <5",
+    "vitest": ">=4.1.10 <5"
+  },
+  "peerDependenciesMeta": {
+    "@playwright/test": {
+      "optional": true
+    },
+    "@vitest/browser-playwright": {
+      "optional": true
+    },
+    "vitest": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "0.18.5",
+    "@playwright/test": "1.62.1",
+    "@types/cross-spawn": "6.0.6",
+    "@types/node": "24.13.3",
+    "@vitest/browser-playwright": "4.1.10",
+    "@vitest/coverage-v8": "4.1.10",
+    "oxlint": "1.79.0",
+    "prettier": "3.9.6",
+    "publint": "0.3.24",
+    "rimraf": "6.1.3",
+    "typescript": "7.0.2",
+    "vitest": "4.1.10"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "bugs": {
+    "url": "https://github.com/jbcom/game-harness/issues"
+  },
+  "homepage": "https://github.com/jbcom/game-harness#readme",
+  "sideEffects": false,
+  "author": "Jon Bogaty <jon@jonbogaty.com>",
+  "keywords": [
+    "vitest",
+    "playwright",
+    "testing",
+    "browser-testing",
+    "visual-regression",
+    "lighthouse",
+    "ci",
+    "game-dev"
+  ],
+  "scripts": {
+    "build": "pnpm run clean && pnpm run build:esm && pnpm run build:cjs && pnpm run build:types && pnpm run build:fixup",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:types": "tsc -p tsconfig.types.json",
+    "build:fixup": "node scripts/fixup-cjs-package-json.mjs",
+    "clean": "rimraf dist",
+    "coverage": "vitest run --coverage",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "oxlint --deny-warnings src tests scripts",
+    "package:check": "publint && attw --pack . --profile node16",
+    "test": "vitest run",
+    "test:package": "node scripts/verify-package-boundaries.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "verify": "pnpm run format:check && pnpm run lint && pnpm run typecheck && pnpm run coverage && pnpm run build && pnpm run package:check && pnpm run test:package"
+  }
+}