@quybt93/pcgf 0.0.1

package/plugins/phaser-casual-game-factory/skills/theme-cream-casual/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: theme-cream-casual
+description: >-
+  Apply Phaser Casual Game Factory default cream-casual UI (factory-browser-demo):
+  cream #fff6ea page, white hard-shadow cards, green #22c55e primary, gold costs,
+  hot pink close (rest rotate 8deg; hover/press upright), button press MUST use
+  box-shadow:none + translateY(3px), bindFactoryDomPress with window pointerup so
+  release outside Phaser canvas/letterbox does not stick press. Triggers: UI, CSS,
+  button, modal, theme, cream, hard shadow, box-shadow none, press stuck, thả ngoài
+  canvas, letterbox. Search: theme cream. For Phaser off-canvas stuck scale also
+  read phaser-ui-motion/fix-off-canvas-press.md.
+---
+
+# Theme: Cream Casual (default)
+
+**Canonical CSS:** `templates/ui/factory-cream-casual.css` (scaffold → `src/factory/ui/`).  
+**DOM press helper:** `templates/ui/bind-factory-dom-press.ts` → `bindFactoryDomPress()`.  
+**Golden reference:** `examples/factory-browser-demo`.
+
+Until game art arrives, **this theme is mandatory** — not optional.
+
+For a full **UI reskin** (theme + bitmap pack + feeling + SFX), start at navigator **`pcgf-ui-reskin`** — do not treat cream CSS alone as the reskin workflow.
+
+## When this skill applies (auto)
+
+Follow **before** writing/changing DOM/CSS if the request mentions UI, CSS, style, theme, button, modal, close ×, Home, Settings, cream, hard shadow, press feeling, or “giống demo”.
+
+**MUST NOT** invent purple-on-navy. That is **`theme-dark-casual` only** when explicitly requested.
+
+## NEVER / ALWAYS
+
+| ALWAYS | NEVER |
+|--------|--------|
+| `@import` `factory-cream-casual.css` **first** | Hand-roll competing `:root` / button colors |
+| `body.factory-page` or `.factory-ui` on chrome root | Bare buttons with no theme root/classes |
+| Press CSS includes **`box-shadow: none`** (see verbatim block) | Leave hard shadow while pressed; omit `box-shadow: none` |
+| Call **`bindFactoryDomPress()`** once after DOM ready | Hand-roll `pointerout` → clear press / scale tween |
+| Clear press only on **pointerup / cancel / lostcapture** (incl. **window** — release outside canvas) | Reset press on `pointerout` / `mouseleave` (breaks drag-off) |
+| Phaser buttons → **`phaser-ui-motion`** `bindButtonMotion` | Ad-hoc Phaser hover/press tweens |
+
+## CRITICAL — press must kill shadow (do not omit)
+
+Agents keep shipping buttons that keep the bottom ledge while pressed. **Every** cream press rule **MUST** include `box-shadow: none` (theme CSS uses `!important`).
+
+**Verbatim press contract (copy — do not “simplify” away the none):**
+
+```css
+/* REQUIRED on :active AND .is-pressed */
+transform: scale(0.96) translateY(3px);
+box-shadow: none !important;
+filter: none;
+```
+
+If you add custom button CSS, you **MUST** repeat `box-shadow: none !important` on `:active` / `.is-pressed`. Resting hard shadow alone is incomplete.
+
+## CRITICAL — drag-off / release outside canvas must not stick press
+
+**Symptom:** Press → kéo xa → **thả ngoài canvas (letterbox)** → scale/shadow kẹt.
+
+**Do this playbook (do not improvise):**
+
+1. Open skill sibling playbook: `skills/phaser-ui-motion/fix-off-canvas-press.md` and follow **section A (DOM)** and/or **B (Phaser)**.
+2. DOM checklist:
+   - `body.factory-page`
+   - `@import` `factory-cream-casual.css`
+   - `bindFactoryDomPress()` called once
+   - Grep `bind-factory-dom-press.ts` for `window.addEventListener('pointerup'` — if missing, **replace file** from plugin `templates/ui/bind-factory-dom-press.ts`
+   - Delete any `pointerout` / `mouseleave` that clears press
+3. Phaser checklist:
+   - Every button uses `bindButtonMotion` only
+   - Grep `phaser-ui-motion.ts` for `finishFromWindow` — if missing, **replace file** from plugin `templates/motion/phaser-ui-motion.ts`
+4. Verify manually: release in the letterbox outside the game canvas → button returns to idle.
+
+```ts
+import { bindFactoryDomPress } from './factory/ui';
+bindFactoryDomPress();
+```
+
+Press CSS must still include (do not omit):
+
+```css
+box-shadow: none !important;
+```
+on `:active` and `.is-pressed`.
+
+## Visual contract (match demo)
+
+1. Cream page `#fff6ea` + white cards, hard shadow `#e4dccf`
+2. Brand green `#22c55e` / `#15803d`
+3. Hot close `#ff4d6d`
+4. Gold costs `#ffb703`
+5. Be Vietnam Pro via `var(--factory-font)`
+6. Radii: card 22 / tile 16 / pill 14 / button ~18
+
+## Press / close motion table
+
+| State | Product button | Close (`.factory-close` / `.modal-close`) |
+|-------|----------------|-------------------------------------------|
+| Rest | hard `box-shadow: 0 5px 0 …` | `rotate(8deg)` + hot hard shadow |
+| Hover | `scale(1.08)` | `scale(1.08)` only (no rotate) |
+| Press (`:active` **or** `.is-pressed`) | `scale(0.96) translateY(3px)` + **`box-shadow: none !important`** | upright sink + **`box-shadow: none !important`** |
+
+## Wire-up (copy exactly)
+
+```css
+@import "./factory/ui/factory-cream-casual.css";
+@import "./factory/demo-tools/demo-tools.css"; /* if QA tools on — after cream */
+```
+
+```html
+<body class="factory-page">
+  <button type="button" class="factory-button">Play</button>
+  <button type="button" class="modal-close" aria-label="Close">×</button>
+</body>
+```
+
+```ts
+import { bindFactoryDomPress } from './factory/ui';
+bindFactoryDomPress();
+```
+
+## Scaffold
+
+`pcgf install --scaffold` copies cream CSS + `bind-factory-dom-press.ts`.  
+Existing games: `--no-scaffold`, then import CSS + `factory-page` + **`bindFactoryDomPress()`**.
+
+## Verification (fail = wrong)
+
+- [ ] Import `factory-cream-casual.css`
+- [ ] `body.factory-page` (or `.factory-ui`)
+- [ ] **`bindFactoryDomPress()`** called
+- [ ] Press: shadow **gone** (`box-shadow: none`), face sinks ~3px
+- [ ] Press → drag **outside canvas** → release: button returns to idle (no stuck scale/shadow)
+- [ ] Close ×: rest tilt 8°; hover/press upright
+- [ ] No `pointerout` press-clear; no purple-on-navy default chrome
+- [ ] Tools panel stays navy (demo-tools after cream)

package/plugins/phaser-casual-game-factory/skills/theme-dark-casual/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: theme-dark-casual
+description: "Optional alternate dark-casual UI theme (navy panels, purple primary). Not the factory default — prefer theme-cream-casual (demo-matched cream casual) unless a game explicitly asks for dark preview. Search: theme dark."
+---
+
+# Theme: Dark Casual (optional)
+
+Use `templates/ui/factory-dark-casual.css` only when a project **explicitly** wants a dark CSS preview. It is **not** the factory default and does **not** match `factory-browser-demo`.
+
+**Default UI theme:** skill **`theme-cream-casual`** → `templates/ui/factory-cream-casual.css` (cream page, green primary, gold costs, hot close).
+
+## When to use this skill
+
+- Temporary dark A/B chrome, or a game that already ships dark navy/purple art direction.
+- Otherwise use cream casual.
+
+## Rules (dark preview only)
+
+- Preserve hierarchy: dark page, separated navy cards, large purple primary actions, yellow costs, muted disabled actions.
+- Use semantic classes (`factory-card`, `factory-button`, `factory-progress`) — same names as cream so you can swap the stylesheet.
+- Modal close × may still use hot tile language so close affordance stays familiar.
+- Pair with **`phaser-ui-motion`** for press/popup/slider feeling.
+- When art/assets arrive, replace the renderer; do not treat this as final art.

package/plugins/phaser-casual-game-factory/skills/tool-demo-qa/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: tool-demo-qa
+description: >-
+  Create, add, wire, or strip Phaser Casual Game Factory QA/demo Test tools:
+  Tools FAB, collapsible +/− sections, appendToolSection, parameter groups
+  (label-above select/range+value like Volute MOVE — BÀN CHƠI), grant/cheat
+  buttons, Perf HUD FPS/ms/tier, device-tier force potato/low/mid/high. Use
+  whenever the user asks to tạo tool, add tool, debug tools, cheat menu, QA
+  panel, Test tools, tune params, tween/slider tools, grant gold/XP, FPS overlay,
+  tier force, or demo tools FAB — default path for any new debug/cheat/param
+  control in a PCGF game. Not for production player HUD or LoadingView.
+  Search: tool demo qa.
+---
+
+# Tool: Demo QA (Test tools)
+
+**Default** path for any new debug / cheat / QA control in a factory game. Do **not** invent a parallel tools panel, floating debug menu, or ad-hoc FPS HUD — extend this overlay instead.
+
+Dev/QA chrome must stay **outside** the product scene lifecycle (`Boot → Home → Game` + LoadingView). Turning tools off must not change boot, iris, Home, or Game behavior — and must **not** leave any FPS sampling or HUD DOM running.
+
+## When this skill applies (auto)
+
+Read and follow this skill **before coding** if the request matches any of:
+
+- tạo tool / add tool / debug tool / cheat / QA / Test tools / Tools FAB
+- grant gold/gem/XP, seed inventory, reset save, win level, god mode
+- tune params / tween / stagger / slider / select trong Tools (layout kiểu Volute)
+- FPS / ms / Perf HUD / potato|low|mid|high tier force
+- collapsible tool sections / `appendToolSection` / `mountToolParamGroups`
+
+## Rules
+
+1. Tools are **opt-in chrome**, not a scene and not part of LoadingView.
+2. One enable flag controls mount/visibility — flip without editing BootScene / Home / Game.
+3. FAB + popup live in HTML **outside** `.stage-screen` (fixed overlay). While enabled they stay **always on top** (high z-index), including Boot splash and Game→Home reveal.
+4. Action handlers (`grant`, `add-xp`, …) stay in the app; this skill owns **shell + enable API + Perf HUD + tier force UI + collapsible sections**.
+5. Do **not** hide tools during scene transitions (`splash-fullscreen`, `is-revealing-home`). Only hide when tools are **fully disabled** for an official player build.
+6. When tools are fully off: tear down FAB/panel **and** Perf HUD (FPS / ms / tier). Stop all `requestAnimationFrame` sampling so official builds pay **zero** tools cost.
+7. **MUST** include Device tier force controls: `auto` / `potato` / `low` / `mid` / `high`. A Tools panel without `[data-tier]` buttons is incomplete — call `ensureDemoToolsShell()` or `initDemoQaTools()`.
+8. **MUST** use collapsible sections (`.tool-section` / `toolSectionHtml` / `appendToolSection`). Large noisy blocks (balances, transaction log, seed dumps) default **collapsed**; click the section header / **+**/**−** to expand.
+9. Collapse affordance is **`+` when closed, `−` when open** (CSS on `.tool-section-chevron` in `demo-tools.css`). Do **not** use up/down chevron arrows.
+10. **MUST NOT** create a second debug overlay, custom FAB, or one-off FPS DOM outside `templates/demo-tools/` (or the game’s copied `src/factory/demo-tools/`).
+
+## Canonical files
+
+| Piece | Path |
+|-------|------|
+| One-shot wire (preferred) | `templates/demo-tools/init-demo-qa-tools.ts` (`initDemoQaTools`) |
+| Shell + inject missing tier/perf | `templates/demo-tools/tool-shell.ts` / `tool-shell.html` |
+| Collapsible sections + add tool | `templates/demo-tools/tool-sections.ts` |
+| Parameter groups (select / range+value) | `templates/demo-tools/tool-param-fields.ts` |
+| Enable + FAB bind | `templates/demo-tools/demo-tools.ts` |
+| FPS / ms / tier HUD | `templates/demo-tools/demo-perf.ts` |
+| Device tier force UI | `templates/demo-tools/demo-device-tier.ts` |
+| Tier session | `templates/adaptive-loading/device-tier-session.ts` |
+| CSS | `templates/demo-tools/demo-tools.css` |
+| Demo HTML example | `examples/factory-browser-demo/index.html` |
+| Scaffold copy | `scripts/new-phaser-casual-game.ps1` → `src/factory/demo-tools/` + `src/factory/adaptive-loading/` |
+
+## Scaffold / new game (required)
+
+`pcgf install --scaffold` / `new-phaser-casual-game.ps1` copies demo-tools + adaptive-loading into `src/factory/`.
+
+In the game bootstrap (after `new Phaser.Game`):
+
+```ts
+import { initDemoQaTools } from './factory/demo-tools';
+import './factory/demo-tools/demo-tools.css';
+
+const qa = initDemoQaTools({
+  getLoop: () => game.loop,
+  // Official build:
+  // enabled: false,
+});
+// qa.deviceTierSession / qa.adaptiveLoading / qa.perfHud / qa.tools
+```
+
+`initDemoQaTools` calls `ensureDemoToolsShell()` first — so even if `index.html` only has an old FAB, it **injects** Performance + Device tier (`potato`/`low`/`mid`/`high`), **wraps flat headings into collapsible sections**, and binds collapse prefs.
+
+Paste `templates/demo-tools/tool-shell.html` into `index.html` (outside `.stage-screen`) when you want static HTML; still call `initDemoQaTools` to bind behavior.
+
+## Create a new tool (game-specific)
+
+Handlers / config stay in app code. Shell only renders UI.
+
+Pick the control type:
+
+| Need | Pattern |
+|------|---------|
+| One-shot cheat / seed | `.button-grid` + `data-action` (below) |
+| Tunable params (tween, ms, stagger, …) | **Parameter groups** — see next section (Volute layout) |
+
+### Action buttons
+
+1. Prefer a **new collapsible section** (do not dump buttons into an already huge open section).
+2. Use `appendToolSection` (or paste the same markup) into `#demo-tools-extra`:
+
+```ts
+import { appendToolSection } from './factory/demo-tools';
+
+appendToolSection({
+  id: 'cheat-combat',
+  title: 'Combat cheats',
+  defaultOpen: false,
+  bodyHtml: `
+    <div class="button-grid">
+      <button type="button" data-action="win-level">Win level</button>
+      <button type="button" data-action="god-mode">God mode</button>
+    </div>`,
+});
+```
+
+3. Wire clicks in the app:
+
+```ts
+document.querySelectorAll<HTMLButtonElement>('[data-action]').forEach((button) => {
+  button.addEventListener('click', () => {
+    const action = button.dataset.action;
+    // call economy / inventory / scene APIs — never Boot/Home lifecycle
+  });
+});
+```
+
+4. After dynamic inject, call `bindDemoToolSections()` again (or rely on `ensureDemoToolsShell`).
+
+## Parameter groups (Volute layout — required for sliders/selects)
+
+Reference: solitaire/volute Tools → groups like **MOVE — BÀN CHƠI** / **ADD COLUMN — THU NHỎ**.
+
+**Do not** put ranges/selects in a bare `.button-grid`. Use nested param groups inside the Tools panel (usually under one outer `tool-section` or `#demo-tools-extra`).
+
+### Layout contract
+
+```
+.anim-group[.is-collapsed]          /* padded card; title uppercase green */
+  .anim-group-head
+    .anim-group-title               /* e.g. "Move — bàn chơi" → CSS uppercase */
+    button.anim-group-toggle        /* text "+" | "−" only */
+  .anim-group-body
+    .anim-field                     /* one param */
+      label                         /* ALWAYS above control */
+      select[data-key]              /* OR */
+      .anim-row
+        input[type=range][data-key]
+        span.val[data-val]          /* right, tabular-nums, accent green */
+```
+
+| Rule | Detail |
+|------|--------|
+| Label | **Above** control (`label { display:block }`) — never beside the slider |
+| Select | Full width under label (tween ease, mode, …) |
+| Range | Flex row: slider `flex:1` + `.val` right (live number) |
+| Group title | Uppercase via CSS; accent `#9fe7b5` |
+| Collapse | Inner `+`/`−` button; class `.is-collapsed` hides body; persist `localStorage.pcgf.demo.toolParamGroups` |
+| Two layers | Outer `<details class="tool-section">` (PCGF) **and** inner `.anim-group` (param packs). Do not flatten everything into one open list |
+
+### API (preferred)
+
+```ts
+import { mountToolParamGroups, type ToolParamGroup } from './factory/demo-tools';
+
+const groups: ToolParamGroup[] = [
+  {
+    title: 'Move — bàn chơi',
+    fields: [
+      { type: 'select', key: 'moveEase', label: 'Tween', options: EASES, labels: EASE_LABELS },
+      { type: 'range', key: 'moveMs', label: 'Thời gian di chuyển (ms)', min: 40, max: 1200, step: 10 },
+      { type: 'range', key: 'moveStaggerMs', label: 'Stagger (ms)', min: 0, max: 200, step: 5 },
+    ],
+  },
+  {
+    title: 'Add Column — thu nhỏ',
+    defaultCollapsed: true,
+    fields: [
+      { type: 'range', key: 'maxExtraColumns', label: 'Số cột thêm tối đa', min: 0, max: 3, step: 1 },
+    ],
+  },
+];
+
+const host = document.querySelector('#card-anim-fields'); // or appendToolSection body
+if (host) {
+  mountToolParamGroups({
+    host,
+    groups,
+    getValues: () => getCardAnim(),       // app config store
+    onChange: (patch) => setCardAnim(patch),
+  });
+}
+```
+
+CSS for these classes lives in `demo-tools.css` (no game-local inject required). Optional Copy/Reset row: `.btn-row` + `.copy-hint`.
+
+### Markup-only (same structure)
+
+```html
+<div class="anim-group">
+  <div class="anim-group-head">
+    <div class="anim-group-title">Move — bàn chơi</div>
+    <button type="button" class="anim-group-toggle" aria-expanded="true">−</button>
+  </div>
+  <div class="anim-group-body">
+    <div class="anim-field">
+      <label>Tween</label>
+      <select data-key="moveEase">…</select>
+    </div>
+    <div class="anim-field">
+      <label>Thời gian di chuyển (ms)</label>
+      <div class="anim-row">
+        <input type="range" min="40" max="1200" step="10" data-key="moveMs" value="560" />
+        <span class="val" data-val="moveMs">560</span>
+      </div>
+    </div>
+  </div>
+</div>
+```
+
+### Collapse rules (outer `tool-section`)
+
+| Case | Behavior |
+|------|----------|
+| Section header + **+**/**−** | Toggle open/closed (`<details>`); **closed = `+`**, **open = `−`** (never ↑↓ arrows) |
+| Icon CSS | `.tool-section-chevron::before` → `'+'` / `[open]` → `'−'` in `demo-tools.css` |
+| Persist | `localStorage.pcgf.demo.toolsSections` = `{ [id]: boolean }` |
+| Default collapsed ids | `balances`, `transaction-log`, `equipment-seed`, `save-data` (+ any you pass `defaultOpen: false`) |
+| Legacy flat `.section-heading` | `wrapFlatToolSections` / `ensureDemoToolsShell` upgrades automatically |
+| Inner param groups | `.anim-group-toggle` text `+`/`−`; persist `pcgf.demo.toolParamGroups` by **group title** |
+
+## Enable / disable (official vs demo)
+
+Priority (first wins):
+
+1. Code: `enabled: false` / `DEMO_TOOLS_FORCE = false` / `tools.setEnabled(false)` — **official player build**
+2. URL: `?tools=0` / `?tools=off` → off; `?tools=1` / `?tools=on` → on
+3. `localStorage.pcgf.demo.toolsEnabled` = `'0'` | `'1'`
+4. Default (`defaultEnabled`, demo = `true`)
+
+Also: `body.demo-tools-off` when disabled. Prefer `setToolsAllowed(false)` on Perf HUD so sampling stops — CSS alone is not enough.
+
+## Device tier (display + force) — mandatory in Tools
+
+Tiers: **`potato` | `low` | `mid` | `high`** (see `phaser-adaptive-loading`).
+
+| Control | Behavior |
+|---------|----------|
+| `#device-tier-status` | `Tier: {effective} · auto\|force … · detect {detected}` |
+| `[data-tier=auto\|potato\|low\|mid\|high]` | Force override via `bindDemoDeviceTier` |
+| Persist | `localStorage.pcgf.demo.deviceTier` |
+| URL | `?tier=potato` (etc.) |
+| Apply | `setOverride` → `AdaptiveLoadingManager.setProfile` + Perf HUD tier row |
+
+## Perf HUD
+
+Rows: **FPS** → **ms** → **tier**. Gated by tools master switch (`toolsAllowed` / `setToolsAllowed`).
+
+## Verification
+
+- New scaffold game: Tools panel shows **auto / potato / low / mid / high** (not missing).
+- Partial HTML without `[data-tier]`: after `initDemoQaTools`, buttons appear.
+- Sections show **+** (collapsed) / **−** (open), not up/down arrows; large sections start collapsed; toggle persists across reload.
+- New tool via `appendToolSection` lands under `#demo-tools-extra` and collapses correctly.
+- Param tools: label above control; range shows value on the right; groups use `+/−` (Volute MOVE layout); `mountToolParamGroups` persists collapse by title.
+- `?tools=0` / `enabled: false` → no FAB, no `#demo-perf-hud`, no FPS rAF.
+- Force tier updates status + Perf HUD tier row.
+- Do not hide tools under splash / `is-revealing-home`.

package/plugins/phaser-casual-game-factory/templates/adaptive-loading/adaptive-loading-manager.ts

@@ -0,0 +1,103 @@
+import type { ActivitySource, AdaptiveLoadingConfig, AdaptiveLoadTask, DeviceProfile } from './types';
+
+const defaults: Required<{
+  concurrency: Record<NonNullable<DeviceProfile['tier']>, number>;
+  idleDelayMs: Record<DeviceProfile['tier'], number>;
+  idleCheckMs: number;
+  blockRemainingCurrentOnActivity: Record<DeviceProfile['tier'], boolean>;
+  nextLevelRequiredPercent: Record<DeviceProfile['tier'], number>;
+}> = {
+  concurrency: { potato: 1, low: 1, mid: 2, high: 4 },
+  idleDelayMs: { potato: 2200, low: 1400, mid: 800, high: 400 },
+  idleCheckMs: 100,
+  blockRemainingCurrentOnActivity: { potato: true, low: true, mid: true, high: false },
+  nextLevelRequiredPercent: { potato: 100, low: 100, mid: 60, high: 25 },
+};
+
+export class AdaptiveLoadingManager {
+  private readonly config: typeof defaults;
+  private controller = new AbortController();
+  private lastBusyAt = Date.now();
+
+  constructor(
+    private profile: DeviceProfile,
+    config: AdaptiveLoadingConfig = {},
+  ) {
+    this.config = {
+      concurrency: { ...defaults.concurrency, ...config.concurrency },
+      idleDelayMs: { ...defaults.idleDelayMs, ...config.idleDelayMs },
+      idleCheckMs: config.idleCheckMs ?? defaults.idleCheckMs,
+      blockRemainingCurrentOnActivity: {
+        ...defaults.blockRemainingCurrentOnActivity,
+        ...config.blockRemainingCurrentOnActivity,
+      },
+      nextLevelRequiredPercent: {
+        ...defaults.nextLevelRequiredPercent,
+        ...config.nextLevelRequiredPercent,
+      },
+    };
+  }
+
+  /** QA / runtime: swap effective profile without rebuilding queues mid-flight. */
+  setProfile(profile: DeviceProfile): void {
+    this.profile = profile;
+  }
+
+  getProfile(): DeviceProfile {
+    return this.profile;
+  }
+
+  async loadCritical(tasks: AdaptiveLoadTask[]): Promise<void> {
+    await this.run(tasks, this.config.concurrency[this.profile.tier]);
+  }
+
+  scheduleNextLevel(tasks: AdaptiveLoadTask[], activity: ActivitySource): () => void {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const poll = () => {
+      if (activity.isInputActive() || activity.isAnimationActive()) this.lastBusyAt = Date.now();
+      if (Date.now() - this.lastBusyAt >= this.config.idleDelayMs[this.profile.tier]) {
+        void this.run(tasks, 1);
+        return;
+      }
+      timer = setTimeout(poll, this.config.idleCheckMs);
+    };
+    timer = setTimeout(poll, this.config.idleCheckMs);
+    return () => {
+      if (timer) clearTimeout(timer);
+      this.controller.abort();
+      this.controller = new AbortController();
+    };
+  }
+
+  /** Current-level leftovers always run before next-level work. `requiredNow` bypasses idle gates. */
+  scheduleRemainingCurrentLevel(
+    tasks: AdaptiveLoadTask[],
+    activity: ActivitySource,
+    requiredNow = false,
+  ): () => void {
+    if (requiredNow || !this.config.blockRemainingCurrentOnActivity[this.profile.tier]) {
+      void this.run(tasks, 1);
+      return () => this.controller.abort();
+    }
+    return this.scheduleNextLevel(tasks, activity);
+  }
+
+  /** Memory pressure wins: never trade a smooth decode for an OOM. */
+  nextLevelRequiredPercent(): number {
+    if (this.profile.memoryPressure === 'high') return 35;
+    if (this.profile.decodePressure === 'high') return 85;
+    return this.config.nextLevelRequiredPercent[this.profile.tier];
+  }
+
+  private async run(tasks: AdaptiveLoadTask[], concurrency: number): Promise<void> {
+    const queue = [...tasks];
+    await Promise.all(
+      Array.from({ length: Math.min(concurrency, queue.length) }, async () => {
+        while (queue.length) {
+          const task = queue.shift();
+          if (task) await task.run(this.controller.signal);
+        }
+      }),
+    );
+  }
+}

package/plugins/phaser-casual-game-factory/templates/adaptive-loading/device-profile.ts

@@ -0,0 +1,76 @@
+import type { DevicePressure, DeviceProfile, DeviceTier } from './types';
+
+function readNavigatorHints(): {
+  cores?: number;
+  memoryGb?: number;
+  saveData: boolean;
+  effectiveType?: string;
+} {
+  const nav = navigator as Navigator & {
+    deviceMemory?: number;
+    connection?: { saveData?: boolean; effectiveType?: string };
+  };
+  return {
+    cores: nav.hardwareConcurrency,
+    memoryGb: nav.deviceMemory,
+    saveData: nav.connection?.saveData ?? false,
+    effectiveType: nav.connection?.effectiveType,
+  };
+}
+
+export function classifyDeviceProfile(input: {
+  cores?: number;
+  memoryGb?: number;
+  saveData?: boolean;
+  effectiveType?: string;
+  benchmarkMs?: number;
+}): DeviceProfile {
+  const cores = input.cores;
+  const memoryGb = input.memoryGb;
+  const saveData = input.saveData ?? false;
+  const effectiveType = input.effectiveType;
+  const benchmarkMs = input.benchmarkMs;
+
+  const memoryPressure: DevicePressure =
+    saveData || (memoryGb !== undefined && memoryGb <= 2)
+      ? 'high'
+      : memoryGb !== undefined && memoryGb <= 4
+        ? 'medium'
+        : 'low';
+
+  const decodePressure: DevicePressure =
+    (cores !== undefined && cores <= 2) || (benchmarkMs !== undefined && benchmarkMs > 80)
+      ? 'high'
+      : (cores !== undefined && cores <= 4) || (benchmarkMs !== undefined && benchmarkMs > 35)
+        ? 'medium'
+        : 'low';
+
+  const potato =
+    (memoryPressure === 'high' && decodePressure === 'high') ||
+    (memoryGb !== undefined && memoryGb <= 1) ||
+    (cores !== undefined && cores <= 1) ||
+    (benchmarkMs !== undefined && benchmarkMs > 120);
+
+  const tier: DeviceTier = potato
+    ? 'potato'
+    : memoryPressure === 'high' || decodePressure === 'high'
+      ? 'low'
+      : memoryPressure === 'low' && decodePressure === 'low'
+        ? 'high'
+        : 'mid';
+
+  return { tier, memoryPressure, decodePressure, cores, memoryGb, saveData, effectiveType, benchmarkMs };
+}
+
+/** Sync detect from navigator hints (optional sync benchmark ms). */
+export function detectDeviceProfile(benchmarkMs?: number): DeviceProfile {
+  return classifyDeviceProfile({ ...readNavigatorHints(), benchmarkMs });
+}
+
+/** Async path when a real micro-benchmark is supplied. */
+export async function detectDeviceProfileAsync(
+  benchmark?: () => Promise<number>,
+): Promise<DeviceProfile> {
+  const benchmarkMs = benchmark ? await benchmark() : undefined;
+  return classifyDeviceProfile({ ...readNavigatorHints(), benchmarkMs });
+}