@quybt93/pcgf 0.0.1

package/plugins/phaser-casual-game-factory/examples/factory-browser-demo/src/main.ts

@@ -0,0 +1,1358 @@
+import * as Phaser from 'phaser';
+import {
+  demoConfig,
+  demoHeroes,
+  inventoryDemoConfig,
+  itemMeta,
+  shopChests,
+  shopGoldPacks,
+  type ItemKind,
+} from '../../economy-demo-config';
+import { BrowserStorageAdapter } from '../../../templates/phaser/browser-storage-adapter';
+import { levelingDemoConfig } from '../../leveling-demo-config';
+import {
+  DefaultEconomyService,
+  DefaultItemService,
+  DefaultInventoryService,
+  LocalEconomyRepository,
+  applyDelta,
+  cloneEconomyState,
+  createDefaultEconomyRegistry,
+  type RandomSource,
+  type RewardSummary,
+  type TransactionReceipt,
+} from '../../../templates/economy';
+import { DefaultLevelingService } from '../../../templates/leveling';
+import { FactoryLoadingOverlayScene } from '../../../templates/phaser/loading-overlay-scene';
+import { designGameCanvasSize, lockGameDpr } from '../../../templates/phaser/design-size';
+import { LOADING_TIMING_PRESETS, LoadingViewModel, type LoadingViewTask } from '../../../templates/loading-view';
+import { demoScenes, sceneHooks } from './demo-scenes';
+import { bindDomButtonJuice, playUiClick, playUiClose, setUiAudioGame } from './ui-audio';
+import { bindDomSettingsPopup } from '../../../templates/ui/settings-popup-dom';
+import { initDemoTools, DEMO_TOOLS_DEFAULT, DEMO_TOOLS_FORCE } from './demo-tools';
+import { initDemoQaTools } from '../../../templates/demo-tools/init-demo-qa-tools';
+import type { DeviceTierSession } from '../../../templates/adaptive-loading';
+import { unlockAudioSettings } from '../../../templates/ui/audio-settings';
+
+lockGameDpr();
+const gameCanvas = designGameCanvasSize();
+
+class DemoRandom implements RandomSource {
+  private index = 0;
+  private readonly values = [0.1, 0.8, 0.2, 0.6, 0.4];
+  next(): number {
+    const value = this.values[this.index % this.values.length];
+    this.index += 1;
+    return value;
+  }
+}
+
+type RewardRow = { icon: string; label: string; amount: number };
+
+document.body.dataset.sceneLifecycle = 'booting';
+const STORAGE_KEY = 'phaser-casual-factory-demo';
+const repository = new LocalEconomyRepository(new BrowserStorageAdapter(), STORAGE_KEY);
+const economy = new DefaultEconomyService(repository, demoConfig, createDefaultEconomyRegistry(), new DemoRandom());
+const items = new DefaultItemService(repository, demoConfig, new DemoRandom(), () => 1700000000000);
+const leveling = new DefaultLevelingService(repository, demoConfig, levelingDemoConfig);
+const inventory = new DefaultInventoryService(repository, demoConfig, inventoryDemoConfig, new DemoRandom());
+
+let transactionCount = 0;
+const sessionId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+let proposalId: string | undefined;
+let selectedInventoryItemId: string | undefined;
+let selectedEquipmentId: string | undefined;
+let detailMode: 'stack' | 'equipment' | 'heroShard' = 'stack';
+const selectedInventoryRewards = new Set<string>();
+let busy = false;
+let bagTab: 'material' | 'equipment' | 'heroShard' = 'material';
+let selectedHeroId: (typeof demoHeroes)[number]['id'] | undefined;
+let selectedShardHeroId: (typeof demoHeroes)[number]['id'] | undefined;
+let inGameplay = false;
+let enteringGame = false;
+let xpHudLevel = 1;
+
+const RESOURCE_ICONS: Record<string, string> = {
+  coin: '🪙',
+  gem: '💎',
+  shard: '🔷',
+  shardRanger: '🏹',
+  shardGuardian: '🛡️',
+  shardMage: '🔮',
+  shardKnight: '⚔️',
+  heroRanger: '🏹',
+  heroGuardian: '🛡️',
+  heroMage: '🔮',
+  heroKnight: '⚔️',
+};
+
+const KIND_LABEL: Record<ItemKind, string> = {
+  material: 'MATERIAL',
+  chest: 'CHEST',
+  heroShard: 'HERO SHARD',
+  equipment: 'EQUIPMENT',
+};
+
+const $ = <T extends HTMLElement>(selector: string): T => {
+  const element = document.querySelector<T>(selector);
+  if (!element) throw new Error(`Missing element: ${selector}`);
+  return element;
+};
+
+const logElement = $('#log');
+const statusElement = document.querySelector<HTMLElement>('#status');
+
+function writeLog(label: string, payload: unknown): void {
+  const line = `${new Date().toLocaleTimeString()}  ${label}\n${JSON.stringify(payload, null, 2)}`;
+  logElement.textContent = `${line}\n\n${logElement.textContent}`.slice(0, 7000);
+}
+
+function setStatus(text: string, type: 'ready' | 'busy' | 'error' = 'ready'): void {
+  if (!statusElement) return;
+  statusElement.textContent = text;
+  statusElement.className = `status status-${type}`;
+}
+
+function unwrap<T>(result: { ok: true; value: T } | { ok: false; error: Error }): T {
+  if (!result.ok) throw result.error;
+  return result.value;
+}
+
+function tx(label: string): string {
+  return `browser-${label}-${sessionId}-${transactionCount + 1}`;
+}
+
+function formatStacks(stacks: Array<{ resourceId: string; amount: number }>): string {
+  return stacks.length ? stacks.map((stack) => `${stack.resourceId} ${stack.amount}`).join(', ') : 'No cost';
+}
+
+async function hasResources(stacks: Array<{ resourceId: string; amount: number }>): Promise<boolean> {
+  const balances = await Promise.all(stacks.map(async (stack) => (await economy.getBalance(stack.resourceId)) >= stack.amount));
+  return balances.every(Boolean);
+}
+
+function syncModalScrollLock(): void {
+  const open = document.querySelector('.modal-backdrop.is-open');
+  document.body.classList.toggle('modal-open', Boolean(open));
+}
+
+function showRewardPopup(rows: RewardRow[], title = 'Nhận thưởng'): void {
+  if (!rows.length) return;
+  $('#reward-modal').querySelector('h2')!.textContent = title;
+  $('#reward-list').innerHTML = rows
+    .map(
+      (row) => `<div class="reward-row"><span class="reward-ico">${row.icon}</span><span>${row.label}</span><strong>×${row.amount}</strong></div>`,
+    )
+    .join('');
+  $('#reward-modal').classList.add('is-open');
+  syncModalScrollLock();
+}
+
+function closeRewardPopup(): void {
+  $('#reward-modal').classList.remove('is-open');
+  syncModalScrollLock();
+}
+
+function closeLevelUpPopup(): void {
+  $('#levelup-modal').classList.remove('is-open');
+  syncModalScrollLock();
+}
+
+async function showLevelUpPopup(level: number, rewardRows: RewardRow[]): Promise<void> {
+  const required = unwrap(await leveling.getXpToNextLevel('character'));
+  const character = unwrap(await leveling.getState('character'));
+  const maxLevel = levelingDemoConfig.tracks.character.maxLevel ?? 99;
+  const atMax = character.level >= maxLevel;
+  const ratio = atMax || !required ? 1 : Math.min(1, character.exp / required);
+  const percent = Math.round(ratio * 100);
+
+  $('#levelup-level').textContent = `Lv ${level}`;
+  $('#levelup-text').textContent = `Chúc mừng! Player lên cấp ${level}.`;
+  $('#levelup-xp-label').textContent = atMax ? `${character.exp} XP · Max` : `${character.exp} / ${required} XP`;
+  $('#levelup-reward-list').innerHTML = rewardRows.length
+    ? rewardRows
+        .map(
+          (row) => `<div class="reward-row"><span class="reward-ico">${row.icon}</span><span>${row.label}</span><strong>×${row.amount}</strong></div>`,
+        )
+        .join('')
+    : '<div class="reward-row"><span class="reward-ico">✨</span><span>Không có thưởng thêm</span><strong>—</strong></div>';
+
+  $('#levelup-modal').classList.add('is-open');
+  syncModalScrollLock();
+
+  const fill = $('#levelup-xp-fill');
+  fill.style.transition = 'none';
+  fill.style.width = '0%';
+  void fill.offsetWidth;
+  fill.style.transition = '';
+  void setXpFillElement(fill, percent, true, true);
+}
+
+function setXpFillElement(fill: HTMLElement, percent: number, animate: boolean, leveledUp: boolean): Promise<void> {
+  if (!animate) {
+    fill.style.transition = 'none';
+    fill.style.width = `${percent}%`;
+    void fill.offsetWidth;
+    fill.style.transition = '';
+    return Promise.resolve();
+  }
+  if (leveledUp) {
+    return (async () => {
+      fill.style.width = '100%';
+      await waitMs(450);
+      fill.style.transition = 'none';
+      fill.style.width = '0%';
+      void fill.offsetWidth;
+      fill.style.transition = '';
+      fill.style.width = `${percent}%`;
+      await waitMs(450);
+    })();
+  }
+  fill.style.width = `${percent}%`;
+  return waitMs(450);
+}
+
+function extractLevelUps(result: unknown): Array<{ trackId: string; level: number }> {
+  const receipt =
+    result && typeof result === 'object' && 'rewards' in result
+      ? (result as TransactionReceipt)
+      : result && typeof result === 'object' && 'ok' in result && (result as { ok: boolean; value?: TransactionReceipt }).ok
+        ? (result as { value: TransactionReceipt }).value
+        : undefined;
+  return (receipt?.rewards ?? []).filter(
+    (reward): reward is Extract<RewardSummary, { type: 'level-up' }> => reward.type === 'level-up',
+  );
+}
+
+function rewardRowsFromReceipt(receipt: TransactionReceipt | undefined, options?: { excludeLevelUpMeta?: boolean }): RewardRow[] {
+  if (!receipt) return [];
+  const rows: RewardRow[] = [];
+  const push = (icon: string, label: string, amount: number) => {
+    if (amount <= 0) return;
+    const existing = rows.find((row) => row.label === label);
+    if (existing) existing.amount += amount;
+    else rows.push({ icon, label, amount });
+  };
+
+  for (const reward of receipt.rewards ?? []) {
+    if (reward.type === 'resource') {
+      push(RESOURCE_ICONS[reward.resourceId] ?? '✨', reward.resourceId, reward.amount);
+    } else if (reward.type === 'item') {
+      const meta = itemMeta[reward.itemId];
+      const name = inventoryDemoConfig.items[reward.itemId]?.name ?? reward.itemId;
+      push(meta?.icon ?? '📦', name, reward.amount ?? 1);
+    } else if (reward.type === 'feature-unlocked') {
+      push('🔓', reward.featureId, 1);
+    } else if (reward.type === 'level-up') {
+      if (!options?.excludeLevelUpMeta) push('⬆️', `${reward.trackId} Lv ${reward.level}`, 1);
+    }
+  }
+
+  if (!rows.length && !options?.excludeLevelUpMeta) {
+    for (const change of receipt.changes ?? []) {
+      if (change.delta > 0) push(RESOURCE_ICONS[change.resourceId] ?? '✨', change.resourceId, change.delta);
+    }
+  }
+  return rows;
+}
+
+function collectRewardRows(result: unknown): RewardRow[] {
+  if (!result) return [];
+  if (Array.isArray(result)) {
+    return result.flatMap((entry) => collectRewardRows(entry));
+  }
+  if (typeof result === 'object' && result !== null && 'ok' in result) {
+    const boxed = result as { ok: boolean; value?: unknown };
+    return boxed.ok ? collectRewardRows(boxed.value) : [];
+  }
+  if (typeof result === 'object' && result !== null && 'rewards' in result) {
+    return rewardRowsFromReceipt(result as TransactionReceipt);
+  }
+  if (typeof result === 'object' && result !== null && 'receipt' in result) {
+    return rewardRowsFromReceipt((result as { receipt: TransactionReceipt }).receipt);
+  }
+  return [];
+}
+
+function setPhoneMode(mode: 'boot' | 'home' | 'game'): void {
+  inGameplay = mode === 'game';
+  const screen = document.querySelector('.stage-screen');
+  screen?.classList.remove('is-boot', 'is-game', 'is-home', 'is-revealing-home');
+  screen?.classList.add(`is-${mode}`);
+  if (mode === 'home') setNav('main');
+}
+
+function prepareHomeReveal(): void {
+  document.querySelector('.stage-screen')?.classList.add('is-revealing-home');
+  document.querySelectorAll<HTMLElement>('.stage-view').forEach((panel) => {
+    const isMain = panel.dataset.view === 'main';
+    panel.classList.toggle('is-active', isMain);
+    panel.hidden = !isMain;
+  });
+  // Re-pin Boot splash / Phaser FIT to the phone stage before iris measures frog.
+  window.dispatchEvent(new Event('resize'));
+}
+
+/** Seed Home tabs under splash without flipping to HUD chrome (sculpin-stable canvas). */
+function prepareHomeUnderSplash(): void {
+  document.querySelectorAll<HTMLElement>('.stage-view').forEach((panel) => {
+    const isMain = panel.dataset.view === 'main';
+    panel.classList.toggle('is-active', isMain);
+    panel.hidden = !isMain;
+  });
+}
+
+function setNav(view: 'shop' | 'main' | 'heroes'): void {
+  if (inGameplay) return;
+  document.querySelectorAll('.nav-tab').forEach((tab) => tab.classList.toggle('is-active', (tab as HTMLElement).dataset.nav === view));
+  document.querySelectorAll<HTMLElement>('.stage-view').forEach((panel) => {
+    const active = panel.dataset.view === view;
+    panel.classList.toggle('is-active', active);
+    panel.hidden = !active;
+  });
+}
+
+async function refresh(options?: { animateXp?: boolean }): Promise<void> {
+  const gold = await economy.getBalance('coin');
+  const gem = await economy.getBalance('gem');
+  $('#hud-gold').textContent = String(gold);
+  $('#hud-gem').textContent = String(gem);
+
+  const toolIds = ['coin', 'gem', 'shardRanger', 'shardGuardian', 'shardMage', 'shardKnight', 'heroRanger', 'heroGuardian', 'heroMage', 'heroKnight'];
+  const balances = await Promise.all(toolIds.map(async (id) => [id, await economy.getBalance(id)] as const));
+  $('#balances').innerHTML = balances
+    .map(([id, amount]) => `<div class="balance"><span>${id}</span><strong>${amount}</strong></div>`)
+    .join('');
+
+  const character = unwrap(await leveling.getState('character'));
+  const required = unwrap(await leveling.getXpToNextLevel('character'));
+  const maxLevel = levelingDemoConfig.tracks.character.maxLevel ?? 99;
+  const atMax = character.level >= maxLevel;
+  const ratio = atMax || !required ? 1 : Math.min(1, character.exp / required);
+  const percent = Math.round(ratio * 100);
+  const leveledUp = character.level > xpHudLevel;
+  $('#player-level-text').textContent = `Lv ${character.level}`;
+  $('#player-xp-label').textContent = atMax ? `${character.exp} XP · Max` : `${character.exp} / ${required} XP`;
+  // Fire-and-forget tween so tool clicks are not blocked by animation.
+  if (options?.animateXp) void setXpFill(percent, true, leveledUp);
+  else void setXpFill(percent, false, false);
+  xpHudLevel = character.level;
+
+  $('#transaction-count').textContent = `${transactionCount} tx`;
+  renderShop();
+  await renderHeroes();
+  await renderBag();
+  await refreshOpenPopups();
+}
+
+function waitMs(ms: number): Promise<void> {
+  return new Promise((resolve) => window.setTimeout(resolve, ms));
+}
+
+async function setXpFill(percent: number, animate: boolean, leveledUp: boolean): Promise<void> {
+  await setXpFillElement($('#player-xp-fill'), percent, animate, leveledUp);
+}
+
+function renderShop(): void {
+  $('#shop-gold-grid').innerHTML = shopGoldPacks
+    .map(
+      (pack) => `
+      <button type="button" class="shop-gold-card" data-buy-gold="${pack.id}">
+        <span class="shop-gold-amount">🪙 ${pack.gold.toLocaleString()}</span>
+        <strong>💎 ${pack.gem}</strong>
+      </button>`,
+    )
+    .join('');
+
+  $('#shop-chest-list').innerHTML = shopChests
+    .map((chest) => {
+      const def = inventoryDemoConfig.items[chest.itemId];
+      return `<button type="button" class="shop-chest-card" data-buy-chest="${chest.itemId}" data-gem="${chest.gem}">
+        <div style="display:flex;align-items:center;gap:8px">
+          <span class="chest-icon">${chest.icon}</span>
+          <div><strong>${def.name}</strong><span>${chest.blurb}</span></div>
+        </div>
+        <strong class="gem-cost">💎 ${chest.gem}</strong>
+      </button>`;
+    })
+    .join('');
+}
+
+async function renderHeroes(): Promise<void> {
+  const rows = await Promise.all(
+    demoHeroes.map(async (hero) => {
+      const owned = (await economy.getBalance(hero.ownedResource)) > 0;
+      const shards = await economy.getBalance(hero.shardResource);
+      const state = unwrap(await leveling.getState(hero.trackId));
+      const meta = owned ? `Lv ${state.level} · 🧩 ${shards}` : `Chưa sở hữu · 🧩 ${shards}`;
+      return `<button type="button" class="hero-card ${owned ? '' : 'locked'}" data-hero="${hero.id}">
+        <span class="hero-icon" style="background:${hero.accent}22">${hero.icon}</span>
+        <div><strong>${hero.name}</strong><span>${meta}</span></div>
+      </button>`;
+    }),
+  );
+  $('#hero-list').innerHTML = rows.join('');
+}
+
+async function renderBag(): Promise<void> {
+  if (bagTab === 'equipment') {
+    const state = await repository.getSnapshot();
+    const equipment = Object.values(state.items);
+    $('#bag-list').innerHTML = equipment.length
+      ? equipment
+          .map(
+            (item) => `<button type="button" class="inventory-card" data-equipment-detail="${item.instanceId}">
+          <span class="item-mini-icon">🗡️</span>
+          <span class="item-mini-body"><strong>Iron Sword</strong><span>R${item.revision}</span></span>
+        </button>`,
+          )
+          .join('')
+      : '<div class="empty-inventory">Chưa có trang bị. Dùng tool Create sword.</div>';
+    return;
+  }
+
+  if (bagTab === 'heroShard') {
+    const shards = await Promise.all(
+      demoHeroes.map(async (hero) => {
+        const amount = await economy.getBalance(hero.shardResource);
+        const owned = (await economy.getBalance(hero.ownedResource)) > 0;
+        return { hero, amount, owned };
+      }),
+    );
+    $('#bag-list').innerHTML = shards.some((entry) => entry.amount > 0)
+      ? shards
+          .filter((entry) => entry.amount > 0)
+          .map((entry) => {
+            const canActivate = !entry.owned && entry.amount >= HERO_UNLOCK_SHARDS;
+            return `<div class="shard-card">
+              <button type="button" class="shard-card-main" data-shard-detail="${entry.hero.id}">
+                <span class="item-mini-icon">${entry.hero.icon}</span>
+                <span class="item-mini-body"><strong>${entry.hero.name} shard</strong><span>x${entry.amount}</span></span>
+              </button>
+              ${
+                canActivate
+                  ? `<button type="button" class="shard-activate" data-activate-hero="${entry.hero.id}">Active · ${HERO_UNLOCK_SHARDS}</button>`
+                  : ''
+              }
+            </div>`;
+          })
+          .join('')
+      : '<div class="empty-inventory">Chưa có mảnh hero.</div>';
+    return;
+  }
+
+  const list = await inventory.list();
+  const filtered = list.filter((entry) => entry.amount > 0 && itemMeta[entry.itemId]?.bagTab === 'material');
+  $('#bag-list').innerHTML = filtered.length
+    ? filtered
+        .map((entry) => {
+          const meta = itemMeta[entry.itemId];
+          return `<button type="button" class="inventory-card" data-inventory-detail="${entry.itemId}">
+            <span class="item-mini-icon">${meta?.icon ?? '📦'}</span>
+            <span class="item-mini-body"><strong>${entry.definition.name}</strong><span>x${entry.amount}</span></span>
+          </button>`;
+        })
+        .join('')
+    : '<div class="empty-inventory">Trống trong tab này.</div>';
+}
+
+async function run(label: string, action: () => Promise<unknown>, options?: { showRewards?: boolean }): Promise<void> {
+  if (busy) return;
+  busy = true;
+  setStatus('Processing…', 'busy');
+  try {
+    const result = await action();
+    transactionCount += 1;
+    writeLog(label, result);
+    setStatus('Success');
+    await refresh({ animateXp: label === 'add-xp' });
+    if (options?.showRewards !== false) {
+      const levelUps = extractLevelUps(result).filter((entry) => entry.trackId === 'character');
+      if (levelUps.length) {
+        const receipt =
+          result && typeof result === 'object' && 'rewards' in result
+            ? (result as TransactionReceipt)
+            : result && typeof result === 'object' && 'ok' in result && (result as { ok: boolean; value?: TransactionReceipt }).ok
+              ? (result as { value: TransactionReceipt }).value
+              : undefined;
+        const levelRewards = rewardRowsFromReceipt(receipt, { excludeLevelUpMeta: true });
+        const topLevel = Math.max(...levelUps.map((entry) => entry.level));
+        void showLevelUpPopup(topLevel, levelRewards);
+      } else {
+        const rows = collectRewardRows(result);
+        if (rows.length) showRewardPopup(rows);
+      }
+    }
+  } catch (error) {
+    writeLog(`${label} failed`, error instanceof Error ? error.message : error);
+    setStatus('Failed', 'error');
+  } finally {
+    busy = false;
+  }
+}
+
+const HERO_UNLOCK_SHARDS = 50;
+
+const HERO_RESOURCE_TO_SHARD: Record<string, string> = {
+  heroRanger: 'shardRanger',
+  heroGuardian: 'shardGuardian',
+  heroMage: 'shardMage',
+  heroKnight: 'shardKnight',
+};
+
+/** If a hero reward lands on an already-owned hero, convert duplicates into 50 shards each. */
+async function convertDuplicateHeroRewards(receipt: TransactionReceipt): Promise<TransactionReceipt> {
+  const heroGains = (receipt.rewards ?? []).filter(
+    (reward): reward is Extract<RewardSummary, { type: 'resource' }> =>
+      reward.type === 'resource' && Boolean(HERO_RESOURCE_TO_SHARD[reward.resourceId]),
+  );
+  if (!heroGains.length) return receipt;
+
+  const transactionId = tx('hero-dup-convert');
+  const converted: RewardSummary[] = [];
+  const result = await repository.runAtomic(transactionId, async (state) => {
+    const next = cloneEconomyState(state);
+    const changes: Array<{ resourceId: string; delta: number; balance: number }> = [];
+    const nextRewards: RewardSummary[] = [];
+
+    for (const reward of receipt.rewards ?? []) {
+      if (reward.type !== 'resource' || !HERO_RESOURCE_TO_SHARD[reward.resourceId]) {
+        nextRewards.push(reward);
+        continue;
+      }
+      const shardId = HERO_RESOURCE_TO_SHARD[reward.resourceId];
+      // After open/grant, balance already includes this reward.
+      const ownedAfter = next.balances[reward.resourceId] ?? 0;
+      const ownedBefore = Math.max(0, ownedAfter - reward.amount);
+      const keep = ownedBefore >= 1 ? 0 : Math.min(1, reward.amount);
+      const dupes = reward.amount - keep;
+      if (dupes > 0) {
+        applyDelta(next, demoConfig, reward.resourceId, -dupes, 'grantable', changes);
+        applyDelta(next, demoConfig, shardId, HERO_UNLOCK_SHARDS * dupes, 'grantable', changes);
+        converted.push({ type: 'resource', resourceId: shardId, amount: HERO_UNLOCK_SHARDS * dupes });
+        if (keep > 0) nextRewards.push({ type: 'resource', resourceId: reward.resourceId, amount: keep });
+        nextRewards.push({ type: 'resource', resourceId: shardId, amount: HERO_UNLOCK_SHARDS * dupes });
+      } else {
+        nextRewards.push(reward);
+      }
+    }
+
+    return {
+      state: next,
+      receipt: {
+        transactionId,
+        operationType: 'inventory-grant',
+        applied: true,
+        changes,
+        rewards: nextRewards,
+      },
+      value: nextRewards,
+    };
+  });
+
+  if (!converted.length) return receipt;
+  return {
+    ...receipt,
+    rewards: result.value,
+    changes: [...(receipt.changes ?? []), ...result.receipt.changes],
+  };
+}
+
+async function buyChest(itemId: string, gemCost: number): Promise<TransactionReceipt> {
+  const transactionId = tx(`buy-${itemId}`);
+  const result = await repository.runAtomic(transactionId, async (state) => {
+    const next = cloneEconomyState(state);
+    const changes: Array<{ resourceId: string; delta: number; balance: number }> = [];
+    applyDelta(next, demoConfig, 'gem', -gemCost, 'spendable', changes);
+    next.inventory[itemId] = (next.inventory[itemId] ?? 0) + 1;
+    return {
+      state: next,
+      receipt: {
+        transactionId,
+        operationType: 'inventory-grant',
+        applied: true,
+        changes,
+        rewards: [{ type: 'item', itemId, amount: 1 } satisfies RewardSummary],
+      },
+    };
+  });
+  return result.receipt;
+}
+
+async function activateHeroFromShards(heroId: (typeof demoHeroes)[number]['id']): Promise<TransactionReceipt> {
+  const hero = demoHeroes.find((entry) => entry.id === heroId);
+  if (!hero) throw new Error(`Unknown hero: ${heroId}`);
+  const transactionId = tx(`activate-${hero.id}`);
+  const result = await repository.runAtomic(transactionId, async (state) => {
+    const next = cloneEconomyState(state);
+    const owned = next.balances[hero.ownedResource] ?? 0;
+    const shards = next.balances[hero.shardResource] ?? 0;
+    if (owned > 0) throw new Error(`${hero.name} already owned`);
+    if (shards < HERO_UNLOCK_SHARDS) throw new Error(`Need ${HERO_UNLOCK_SHARDS} shards to unlock ${hero.name}`);
+    const changes: Array<{ resourceId: string; delta: number; balance: number }> = [];
+    applyDelta(next, demoConfig, hero.shardResource, -HERO_UNLOCK_SHARDS, 'spendable', changes);
+    applyDelta(next, demoConfig, hero.ownedResource, 1, 'grantable', changes);
+    return {
+      state: next,
+      receipt: {
+        transactionId,
+        operationType: 'inventory-grant',
+        applied: true,
+        changes,
+        rewards: [{ type: 'resource', resourceId: hero.ownedResource, amount: 1 } satisfies RewardSummary],
+      },
+    };
+  });
+  return result.receipt;
+}
+
+const actions: Record<string, () => Promise<unknown>> = {
+  grant: () => economy.execute({ type: 'grant', configId: 'starter', transactionId: tx('starter') }),
+  'add-gold': () => economy.execute({ type: 'grant', configId: 'toolGold', transactionId: tx('tool-gold') }),
+  'add-gem': () => economy.execute({ type: 'grant', configId: 'toolGem', transactionId: tx('tool-gem') }),
+  'add-shards': () => economy.execute({ type: 'grant', configId: 'toolShards', transactionId: tx('tool-shards') }),
+  'add-xp': () => leveling.addExp('character', 100, tx('character-xp')),
+  'reset-character': () => leveling.resetToDefault('character', tx('character-reset')),
+  'create-item': async () => {
+    const item = unwrap(await items.createItem('sword-1', 'ironSword', tx('create-item')));
+    proposalId = undefined;
+    return item;
+  },
+  'seed-materials': async () => {
+    const receipts = [];
+    for (const itemId of ['fixedChest', 'selectHeroChest', 'randomShardChest', 'spinTicket', 'choiceTicket']) {
+      receipts.push(unwrap(await inventory.grant(itemId, 2, tx(`seed-${itemId}`))));
+    }
+    return receipts;
+  },
+  'reroll-item': async () => {
+    const id = selectedEquipmentId ?? 'sword-1';
+    const proposal = unwrap(await items.rollChange(id, 'swordReroll', `proposal-${sessionId}-${transactionCount + 1}`, tx('reroll-item')));
+    proposalId = proposal.proposalId;
+    return proposal;
+  },
+  'apply-item': async () => {
+    if (!proposalId) throw new Error('Preview an item change first');
+    const id = selectedEquipmentId ?? 'sword-1';
+    const result = unwrap(await items.applyChange(id, proposalId, tx('apply-item')));
+    proposalId = undefined;
+    return result;
+  },
+  'revert-item': async () => {
+    if (!proposalId) throw new Error('Apply an item change first');
+    const id = selectedEquipmentId ?? 'sword-1';
+    const result = unwrap(await items.revertChange(id, proposalId, tx('revert-item')));
+    proposalId = undefined;
+    return result;
+  },
+};
+
+function renderCurrentDiff(current: number, next?: number): string {
+  if (next === undefined || next === current) return String(current);
+  const direction = next > current ? 'up' : 'down';
+  return `${current} <span class="inline-diff diff-${direction}">→ ${next}</span>`;
+}
+
+function renderSkillDiff(current: Record<string, number>, next?: Record<string, number>): string {
+  const currentText = Object.keys(current).join(', ') || 'None';
+  if (!next) return currentText;
+  const changes = Object.keys({ ...current, ...next }).filter((key) => (current[key] ?? 0) !== (next[key] ?? 0));
+  if (!changes.length) return currentText;
+  return `${currentText} <span class="inline-diff diff-${changes.some((key) => (next[key] ?? 0) > (current[key] ?? 0)) ? 'up' : 'down'}">→ ${changes.map((key) => `${key} ${current[key] ?? 0}→${next[key] ?? 0}`).join(', ')}</span>`;
+}
+
+function formatRewardEntry(entry: { type: string; resourceId?: string; itemId?: string; amount: number }): string {
+  if (entry.type === 'item') {
+    const name = inventoryDemoConfig.items[entry.itemId ?? '']?.name ?? entry.itemId;
+    return `${itemMeta[entry.itemId ?? '']?.icon ?? '📦'} ${name} +${entry.amount}`;
+  }
+  const id = entry.resourceId ?? '';
+  return `${RESOURCE_ICONS[id] ?? '✨'} ${id} +${entry.amount}`;
+}
+
+async function openInventoryDetail(itemId: string): Promise<void> {
+  const entry = (await inventory.list()).find((candidate) => candidate.itemId === itemId);
+  if (!entry) return;
+  const meta = itemMeta[itemId];
+  const kind = meta?.kind ?? 'material';
+  detailMode = 'stack';
+  selectedInventoryItemId = itemId;
+  selectedEquipmentId = undefined;
+  selectedInventoryRewards.clear();
+  $('#inventory-detail').classList.add('is-open');
+  syncModalScrollLock();
+  $('#detail-icon').textContent = meta?.icon ?? '📦';
+  $('#detail-kind').textContent = KIND_LABEL[kind];
+  $('#inventory-name').textContent = entry.definition.name;
+  $('#inventory-description').textContent = entry.definition.description;
+  $('#inventory-owned').textContent = `Owned: ${entry.amount}`;
+  $('#equipment-stats').hidden = true;
+  $('#equipment-actions').hidden = true;
+  $('#inventory-detail').querySelector('.inventory-modal')?.classList.remove('is-compact');
+
+  const canUse = Boolean(entry.definition.open);
+  const canSell = Boolean(entry.definition.sell);
+  const isSelect = entry.definition.open?.mode === 'select';
+
+  $('#stack-actions').hidden = !(canUse || canSell);
+  $('#amount-block').hidden = !(canUse || canSell);
+  $('#inventory-open').hidden = !canUse;
+  $('#inventory-sell').hidden = !canSell;
+
+  const amountInput = $('#inventory-amount') as HTMLInputElement;
+  amountInput.max = String(entry.amount);
+  amountInput.value = '1';
+
+  // Reward preview for Use items (non-select shows list; select uses choice list)
+  const open = entry.definition.open;
+  if (canUse && open && !isSelect) {
+    $('#reward-preview').hidden = false;
+    $('#reward-preview-list').innerHTML = open.entries
+      .map((reward) => `<div class="reward-preview-row"><span>${formatRewardEntry(reward)}</span></div>`)
+      .join('');
+  } else {
+    $('#reward-preview').hidden = true;
+    $('#reward-preview-list').innerHTML = '';
+  }
+
+  $('#inventory-choice-list').innerHTML =
+    isSelect && open
+      ? open.entries
+          .map((reward) => {
+            const id = reward.type === 'item' ? reward.itemId : reward.resourceId;
+            return `<button type="button" class="choice-button" data-choice-id="${id}">${formatRewardEntry(reward)}</button>`;
+          })
+          .join('')
+      : '';
+
+  updateInventoryOpenButton(open?.mode);
+  $('#inventory-sell').toggleAttribute('disabled', !canSell);
+}
+
+async function openShardDetail(heroId: (typeof demoHeroes)[number]['id']): Promise<void> {
+  const hero = demoHeroes.find((entry) => entry.id === heroId);
+  if (!hero) return;
+  detailMode = 'heroShard';
+  selectedShardHeroId = heroId;
+  selectedInventoryItemId = undefined;
+  selectedEquipmentId = undefined;
+  const amount = await economy.getBalance(hero.shardResource);
+  $('#inventory-detail').classList.add('is-open');
+  syncModalScrollLock();
+  $('#detail-icon').textContent = hero.icon;
+  $('#detail-kind').textContent = KIND_LABEL.heroShard;
+  $('#inventory-name').textContent = `${hero.name} Shard`;
+  $('#inventory-description').textContent = `Mảnh nâng cấp ${hero.name}. Không Use/Sell.`;
+  $('#inventory-owned').textContent = `Owned: ${amount}`;
+  $('#equipment-stats').hidden = true;
+  $('#equipment-actions').hidden = true;
+  $('#stack-actions').hidden = true;
+  $('#amount-block').hidden = true;
+  $('#inventory-open').hidden = true;
+  $('#inventory-sell').hidden = true;
+  $('#reward-preview').hidden = true;
+  $('#inventory-choice-list').innerHTML = '';
+  $('#inventory-detail').querySelector('.inventory-modal')?.classList.add('is-compact');
+}
+
+async function openEquipmentDetail(instanceId: string): Promise<void> {
+  const state = await repository.getSnapshot();
+  const item = state.items[instanceId];
+  if (!item) return;
+  detailMode = 'equipment';
+  selectedEquipmentId = instanceId;
+  selectedInventoryItemId = undefined;
+  $('#inventory-detail').classList.add('is-open');
+  syncModalScrollLock();
+  $('#detail-icon').textContent = '🗡️';
+  $('#detail-kind').textContent = KIND_LABEL.equipment;
+  $('#inventory-name').textContent = 'Iron Sword';
+  $('#inventory-description').textContent = 'Trang bị unique — không stack. Reroll/Apply/Revert only.';
+  $('#inventory-owned').textContent = `Revision ${item.revision}`;
+  $('#amount-block').hidden = true;
+  $('#stack-actions').hidden = true;
+  $('#inventory-open').hidden = true;
+  $('#inventory-sell').hidden = true;
+  $('#reward-preview').hidden = true;
+  $('#equipment-actions').hidden = false;
+  $('#inventory-choice-list').innerHTML = '';
+  $('#inventory-detail').querySelector('.inventory-modal')?.classList.add('is-compact');
+  const activeProposal = proposalId ? state.itemProposals[proposalId] : undefined;
+  const pending = activeProposal?.status === 'pending' ? activeProposal : undefined;
+  $('#equipment-stats').hidden = false;
+  $('#equipment-stats').innerHTML = `
+    <div class="stat-row"><span>Attack</span><strong>${renderCurrentDiff(item.stats.attack, pending?.after.stats.attack)}</strong></div>
+    <div class="stat-row"><span>Defense</span><strong>${renderCurrentDiff(item.stats.defense, pending?.after.stats.defense)}</strong></div>
+    <div class="skill-row"><span>Skills</span><strong>${renderSkillDiff(item.skills, pending?.after.skills)}</strong></div>
+    <div id="reroll-preview" class="reroll-preview"><div class="reroll-title">Reroll preview</div><div class="reroll-cost">Cost: ${formatStacks(demoConfig.itemChanges.swordReroll.cost)}</div></div>
+  `;
+  const rerollCost = demoConfig.itemChanges.swordReroll.cost;
+  $('#reroll-item').toggleAttribute('disabled', !(await hasResources(rerollCost)) || pending?.status === 'pending');
+  $('#apply-item').toggleAttribute('disabled', pending?.status !== 'pending');
+  $('#revert-item').toggleAttribute('disabled', pending?.status !== 'pending');
+}
+
+async function refreshOpenPopups(): Promise<void> {
+  if ($('#inventory-detail').classList.contains('is-open')) {
+    if (detailMode === 'equipment' && selectedEquipmentId) await openEquipmentDetail(selectedEquipmentId);
+    else if (detailMode === 'stack' && selectedInventoryItemId) await openInventoryDetail(selectedInventoryItemId);
+    else if (detailMode === 'heroShard' && selectedShardHeroId) await openShardDetail(selectedShardHeroId);
+  }
+  if (selectedHeroId && $('#hero-upgrade-modal').classList.contains('is-open')) await openHeroUpgrade(selectedHeroId);
+}
+
+function updateInventoryOpenButton(mode?: string): void {
+  $('#inventory-open').toggleAttribute('disabled', !mode || (mode === 'select' && selectedInventoryRewards.size === 0));
+}
+
+function closeInventoryDetail(): void {
+  $('#inventory-detail').classList.remove('is-open');
+  selectedInventoryItemId = undefined;
+  selectedEquipmentId = undefined;
+  syncModalScrollLock();
+}
+
+function getInventoryAmount(): number {
+  const input = $('#inventory-amount') as HTMLInputElement;
+  const max = Number(input.max);
+  const amount = Math.floor(Number(input.value) || 1);
+  return Math.max(1, Math.min(max, amount));
+}
+
+async function openHeroUpgrade(heroId: (typeof demoHeroes)[number]['id']): Promise<void> {
+  const hero = demoHeroes.find((entry) => entry.id === heroId);
+  if (!hero) return;
+  selectedHeroId = heroId;
+  const owned = (await economy.getBalance(hero.ownedResource)) > 0;
+  const shards = await economy.getBalance(hero.shardResource);
+  const state = unwrap(await leveling.getState(hero.trackId));
+  const preview = unwrap(await leveling.getUpgradePreview(hero.trackId));
+  const maxLevel = levelingDemoConfig.tracks[hero.trackId].maxLevel ?? 10;
+  const startLevel = levelingDemoConfig.tracks[hero.trackId].startLevel ?? 1;
+
+  $('#hero-upgrade-modal').classList.add('is-open');
+  syncModalScrollLock();
+  const icon = $('#hero-upgrade-icon');
+  icon.textContent = hero.icon;
+  icon.style.background = `${hero.accent}33`;
+  $('#hero-upgrade-name').textContent = hero.name;
+  $('#hero-upgrade-level').textContent = owned ? `Lv ${state.level} / Max ${maxLevel}` : 'Chưa sở hữu';
+  $('#hero-upgrade-shards').textContent = `Mảnh: ${shards}`;
+
+  if (!owned) {
+    $('#hero-upgrade-costs').innerHTML = '<div class="cost-row">Mở hero từ Select Hero Chest để nâng cấp.</div>';
+    $('#hero-upgrade-btn').hidden = true;
+    $('#hero-reset-btn').hidden = true;
+    return;
+  }
+
+  $('#hero-upgrade-btn').hidden = false;
+  $('#hero-reset-btn').hidden = false;
+  const costRows = await Promise.all(
+    (preview.isMaxLevel ? [] : preview.costs).map(async (stack) => {
+      const have = await economy.getBalance(stack.resourceId);
+      const ok = have >= stack.amount;
+      const icon = RESOURCE_ICONS[stack.resourceId] ?? '✨';
+      return `<div class="cost-row ${ok ? 'ok' : 'short'}"><span>${icon} ${stack.resourceId}</span><strong>${have} / ${stack.amount}</strong></div>`;
+    }),
+  );
+  $('#hero-upgrade-costs').innerHTML = preview.isMaxLevel
+    ? '<div class="cost-row">Max level reached</div>'
+    : costRows.join('') || '<div class="cost-row">No cost</div>';
+  $('#hero-upgrade-btn').toggleAttribute('disabled', preview.isMaxLevel);
+  $('#hero-reset-btn').toggleAttribute('disabled', state.level <= startLevel);
+}
+
+document.querySelectorAll<HTMLButtonElement>('[data-action]').forEach((button) => {
+  button.addEventListener('click', () => {
+    const action = button.dataset.action;
+    if (action && actions[action]) {
+      const silent = action === 'reroll-item' || action === 'create-item' || action === 'revert-item';
+      void run(action, actions[action], { showRewards: !silent });
+    }
+  });
+});
+
+/** QA overlay only — skill `tool-demo-qa`. Wired after Phaser.Game below. */
+let demoTools: ReturnType<typeof initDemoTools>;
+let deviceTierSession: DeviceTierSession;
+let adaptiveLoading: NonNullable<ReturnType<typeof initDemoQaTools>['adaptiveLoading']> | null =
+  null;
+
+document.querySelectorAll<HTMLElement>('[data-close-popup]').forEach((button) => {
+  button.addEventListener('click', () => {
+    const id = button.dataset.closePopup;
+    if (id) $(`#${id}`).classList.remove('is-open');
+    syncModalScrollLock();
+  });
+});
+
+document.querySelectorAll<HTMLButtonElement>('.nav-tab').forEach((button) => {
+  button.addEventListener('click', () => setNav(button.dataset.nav as 'shop' | 'main' | 'heroes'));
+});
+
+document.querySelectorAll<HTMLButtonElement>('.bag-tab').forEach((button) => {
+  button.addEventListener('click', () => {
+    bagTab = button.dataset.bagTab as typeof bagTab;
+    document.querySelectorAll('.bag-tab').forEach((tab) => tab.classList.toggle('is-active', tab === button));
+    void renderBag();
+  });
+});
+
+document.addEventListener('click', (event) => {
+  const target = event.target as HTMLElement;
+  const goldId = target.closest<HTMLElement>('[data-buy-gold]')?.dataset.buyGold;
+  if (goldId) {
+    const pack = shopGoldPacks.find((entry) => entry.id === goldId);
+    void run(`buy-${goldId}`, async () => {
+      const receipt = unwrap(await economy.execute({ type: 'convert', configId: goldId, transactionId: tx(goldId) }));
+      return {
+        ...receipt,
+        rewards: [{ type: 'resource', resourceId: 'coin', amount: pack?.gold ?? 0 }],
+      };
+    });
+  }
+
+  const chest = target.closest<HTMLElement>('[data-buy-chest]');
+  if (chest?.dataset.buyChest) {
+    const gemCost = Number(chest.dataset.gem);
+    void run(`buy-${chest.dataset.buyChest}`, () => buyChest(chest.dataset.buyChest!, gemCost));
+  }
+
+  const heroId = target.closest<HTMLElement>('[data-hero]')?.dataset.hero as (typeof demoHeroes)[number]['id'] | undefined;
+  if (heroId) void openHeroUpgrade(heroId);
+
+  const detailId = target.closest<HTMLElement>('[data-inventory-detail]')?.dataset.inventoryDetail;
+  if (detailId) void openInventoryDetail(detailId);
+
+  const shardId = target.closest<HTMLElement>('[data-shard-detail]')?.dataset.shardDetail as (typeof demoHeroes)[number]['id'] | undefined;
+  if (shardId) void openShardDetail(shardId);
+
+  const activateId = target.closest<HTMLElement>('[data-activate-hero]')?.dataset.activateHero as
+    | (typeof demoHeroes)[number]['id']
+    | undefined;
+  if (activateId) {
+    event.preventDefault();
+    void run(`activate-${activateId}`, () => activateHeroFromShards(activateId));
+  }
+
+  const equipmentId = target.closest<HTMLElement>('[data-equipment-detail]')?.dataset.equipmentDetail;
+  if (equipmentId) void openEquipmentDetail(equipmentId);
+
+  const choiceId = target.closest<HTMLElement>('[data-choice-id]')?.dataset.choiceId;
+  if (choiceId) {
+    selectedInventoryRewards.clear();
+    selectedInventoryRewards.add(choiceId);
+    document.querySelectorAll('[data-choice-id]').forEach((element) => element.classList.toggle('is-selected', (element as HTMLElement).dataset.choiceId === choiceId));
+    updateInventoryOpenButton('select');
+  }
+});
+
+$('#inventory-close').addEventListener('click', closeInventoryDetail);
+$('#reward-modal').addEventListener('click', (event) => {
+  if (event.target === $('#reward-modal')) closeRewardPopup();
+});
+$('.reward-modal').addEventListener('click', (event) => {
+  event.stopPropagation();
+});
+$('#levelup-ok').addEventListener('click', closeLevelUpPopup);
+$('#inventory-minus').addEventListener('click', () => {
+  const input = $('#inventory-amount') as HTMLInputElement;
+  input.value = String(Math.max(1, getInventoryAmount() - 1));
+});
+$('#inventory-plus').addEventListener('click', () => {
+  const input = $('#inventory-amount') as HTMLInputElement;
+  input.value = String(Math.min(Number(input.max), getInventoryAmount() + 1));
+});
+$('#inventory-max').addEventListener('click', () => {
+  const input = $('#inventory-amount') as HTMLInputElement;
+  input.value = input.max;
+});
+$('#inventory-open').addEventListener('click', () => {
+  if (!selectedInventoryItemId) return;
+  void run('inventory-open', async () => {
+    const receipt = unwrap(
+      await inventory.open(selectedInventoryItemId!, getInventoryAmount(), tx('inventory-open'), [...selectedInventoryRewards]),
+    );
+    return convertDuplicateHeroRewards(receipt);
+  });
+  closeInventoryDetail();
+});
+$('#inventory-sell').addEventListener('click', () => {
+  if (!selectedInventoryItemId) return;
+  void run('inventory-sell', async () => unwrap(await inventory.sell(selectedInventoryItemId!, getInventoryAmount(), tx('inventory-sell'))));
+  closeInventoryDetail();
+});
+
+$('#hero-upgrade-btn').addEventListener('click', () => {
+  if (!selectedHeroId) return;
+  const hero = demoHeroes.find((entry) => entry.id === selectedHeroId);
+  if (!hero) return;
+  void run(`upgrade-${hero.id}`, () => leveling.upgrade(hero.trackId, tx(`upgrade-${hero.id}`)), { showRewards: false });
+});
+$('#hero-reset-btn').addEventListener('click', () => {
+  if (!selectedHeroId) return;
+  const hero = demoHeroes.find((entry) => entry.id === selectedHeroId);
+  if (!hero) return;
+  void run(`reset-${hero.id}`, () => leveling.resetToDefault(hero.trackId, tx(`reset-${hero.id}`)));
+});
+
+$('#btn-bag').addEventListener('click', () => {
+  $('#bag-modal').classList.add('is-open');
+  syncModalScrollLock();
+  void renderBag();
+});
+
+sceneHooks.onBootLoad = async () => {
+  renderShop();
+  await refresh();
+};
+
+sceneHooks.onBootPrepareHome = (closeStyle) => {
+  // slide-up: idle Home under DOM splash that slides away.
+  // iris: keep sculpin full-viewport canvas — only seed Home content; reveal later.
+  if (closeStyle === 'slide-up') {
+    setPhoneMode('home');
+    return;
+  }
+  prepareHomeUnderSplash();
+};
+
+sceneHooks.onRequestHome = () => {
+  void returnHome();
+};
+
+sceneHooks.onRequestPlay = () => {
+  void enterGame();
+};
+
+sceneHooks.onRequestNextLevel = () => {
+  void loadNextLevel();
+};
+
+$('#btn-play').addEventListener('click', () => {
+  void enterGame();
+});
+
+const game = new Phaser.Game({
+  type: Phaser.WEBGL,
+  parent: 'game',
+  // Design 390×720 × devicePixelRatio so FIT CSS stays phone-sized while the
+  // WebGL buffer matches Retina (fixes nhòe / răng cưa on text + Graphics).
+  width: gameCanvas.width,
+  height: gameCanvas.height,
+  transparent: true,
+  // Alpha 0 so idle/reveal frames do not clear to opaque #0b1220 over HTML Home.
+  backgroundColor: 'rgba(11, 18, 32, 0)',
+  roundPixels: false,
+  render: {
+    antialias: true,
+    antialiasGL: true,
+    roundPixels: false,
+    powerPreference: 'high-performance',
+  },
+  scale: {
+    mode: Phaser.Scale.FIT,
+    autoCenter: Phaser.Scale.CENTER_BOTH,
+    // Sub-pixel CSS rounding from autoRound softens FIT output on HiDPI.
+    autoRound: false,
+  },
+  scene: demoScenes,
+});
+
+/** QA Test tools — Perf HUD + potato/low/mid/high (ensures shell even if HTML is partial). */
+const demoQa = initDemoQaTools({
+  defaultEnabled: DEMO_TOOLS_DEFAULT,
+  ...(DEMO_TOOLS_FORCE == null ? {} : { enabled: DEMO_TOOLS_FORCE }),
+  getLoop: () => game.loop,
+});
+demoTools = demoQa.tools;
+deviceTierSession = demoQa.deviceTierSession;
+adaptiveLoading = demoQa.adaptiveLoading;
+
+const resizeToDesignCanvas = (): void => {
+  game.scale.resize(gameCanvas.width, gameCanvas.height);
+  game.scale.refresh();
+};
+
+sceneHooks.onBootRevealHome = () => {
+  prepareHomeReveal();
+  game.scale.refresh();
+};
+setUiAudioGame(game);
+bindDomButtonJuice();
+bindDomSettingsPopup(document, {
+  onCloseSound: () => playUiClose(),
+  onClickSound: () => playUiClick(),
+  onHome: () => sceneHooks.onRequestHome?.(),
+});
+document.addEventListener(
+  'pointerdown',
+  () => {
+    unlockAudioSettings();
+  },
+  { once: true },
+);
+
+async function getOverlay(): Promise<FactoryLoadingOverlayScene> {
+  const overlay = game.scene.getScene(FactoryLoadingOverlayScene.KEY) as FactoryLoadingOverlayScene;
+  if (!game.scene.isActive(FactoryLoadingOverlayScene.KEY)) {
+    game.scene.run(FactoryLoadingOverlayScene.KEY);
+    await Promise.race([
+      new Promise<void>((resolve) => overlay.events.once(Phaser.Scenes.Events.CREATE, () => resolve())),
+      new Promise<void>((resolve) => window.setTimeout(resolve, 400)),
+    ]);
+  }
+  game.scene.bringToTop(FactoryLoadingOverlayScene.KEY);
+  return overlay;
+}
+
+async function waitLayout(): Promise<void> {
+  await new Promise<void>((resolve) => requestAnimationFrame(() => requestAnimationFrame(() => resolve())));
+  // Keep HiDPI canvas matched to design×DPR. Resizing to a mismatched buffer
+  // (e.g. 640 inside a 720 host) stretches and softens Game/Loading text.
+  resizeToDesignCanvas();
+}
+
+window.addEventListener('resize', () => {
+  game.scale.refresh();
+});
+
+function switchToGameScene(): void {
+  if (game.scene.isActive('Home') || game.scene.isSleeping('Home')) game.scene.stop('Home');
+  if (game.scene.isActive('Boot')) game.scene.stop('Boot');
+  if (game.scene.isActive('Game')) game.scene.stop('Game');
+  game.scene.start('Game');
+  game.scene.bringToTop('Game');
+  if (game.scene.isActive(FactoryLoadingOverlayScene.KEY)) {
+    game.scene.bringToTop(FactoryLoadingOverlayScene.KEY);
+  }
+}
+
+function switchToHomeScene(): void {
+  if (game.scene.isActive('Game') || game.scene.isSleeping('Game')) game.scene.stop('Game');
+  if (game.scene.isActive('Home')) game.scene.stop('Home');
+  game.scene.start('Home');
+  game.scene.bringToTop('Home');
+  if (game.scene.isActive(FactoryLoadingOverlayScene.KEY)) {
+    game.scene.bringToTop(FactoryLoadingOverlayScene.KEY);
+  }
+}
+
+async function enterGame(): Promise<void> {
+  if (inGameplay || enteringGame) return;
+  enteringGame = true;
+  try {
+    const overlay = await getOverlay();
+    game.registry.set('playLevel', 1);
+    const tasks: LoadingViewTask[] = [
+      {
+        id: 'player-data',
+        weight: 1,
+        run: async ({ reportProgress }) => {
+          reportProgress(0.1);
+          await refresh();
+          reportProgress(1);
+        },
+      },
+      {
+        id: 'game-scene',
+        weight: 2,
+        afterOpen: true,
+        run: async ({ reportProgress }) => {
+          reportProgress(0.15);
+          // Visual swap waits for open — source scene may still show under the View.
+          setPhoneMode('game');
+          await waitLayout();
+          switchToGameScene();
+          await waitLayout();
+          reportProgress(1);
+        },
+      },
+    ];
+    await overlay.play(new LoadingViewModel({
+      ...LOADING_TIMING_PRESETS.menuToGame,
+      description: 'Loading Game…',
+    }, tasks), 'scene-transition');
+  } catch (error) {
+    console.error('enterGame transition failed', error);
+    switchToGameScene();
+  }
+  if (!game.scene.isActive('Game')) switchToGameScene();
+  await waitLayout();
+  document.body.dataset.sceneLifecycle = 'game';
+  enteringGame = false;
+}
+
+async function returnHome(): Promise<void> {
+  if (!inGameplay && document.body.dataset.sceneLifecycle !== 'game') return;
+  try {
+    const overlay = await getOverlay();
+    const tasks: LoadingViewTask[] = [
+      {
+        id: 'home-scene',
+        weight: 2,
+        afterOpen: true,
+        run: async ({ reportProgress }) => {
+          reportProgress(0.15);
+          // `.is-game.is-revealing-home` keeps canvas above HTML so the LoadingView
+          // bitmap mask can reveal the real Home View (not BG_lobby).
+          prepareHomeReveal();
+          switchToHomeScene();
+          await waitLayout();
+          reportProgress(1);
+        },
+      },
+      {
+        id: 'home-data',
+        weight: 1,
+        run: async ({ reportProgress }) => {
+          reportProgress(0.1);
+          await refresh();
+          reportProgress(1);
+        },
+      },
+    ];
+    await overlay.play(new LoadingViewModel({
+      ...LOADING_TIMING_PRESETS.gameToMenu,
+      description: 'Returning Home…',
+    }, tasks), 'scene-transition');
+  } catch (error) {
+    console.error('returnHome transition failed', error);
+    switchToHomeScene();
+  }
+  if (!game.scene.isActive('Home')) switchToHomeScene();
+  setPhoneMode('home');
+  await waitLayout();
+  document.body.dataset.sceneLifecycle = 'ready';
+}
+
+async function simulateNextLevelData(level: number, reportProgress: (progress: number) => void): Promise<void> {
+  // Smooth mock load so the bar eases under minimumVisibleMs instead of stair-steps.
+  const steps = [
+    [0.12, 120],
+    [0.28, 120],
+    [0.44, 120],
+    [0.58, 120],
+    [0.72, 120],
+    [0.86, 120],
+  ] as const;
+  for (const [progress, delayMs] of steps) {
+    reportProgress(progress);
+    await new Promise<void>((resolve) => window.setTimeout(resolve, delayMs));
+  }
+  game.registry.set('playLevel', level);
+  game.registry.set('playLevelSeed', Date.now());
+  reportProgress(0.94);
+}
+
+async function loadNextLevel(): Promise<void> {
+  if (!game.scene.isActive('Game') && document.body.dataset.sceneLifecycle !== 'game') return;
+  try {
+    const overlay = await getOverlay();
+    const next = Number(game.registry.get('playLevel') ?? 1) + 1;
+    const tasks: LoadingViewTask[] = [
+      {
+        id: 'next-level-data',
+        weight: 2,
+        run: async ({ reportProgress }) => {
+          await simulateNextLevelData(next, reportProgress);
+          reportProgress(1);
+        },
+      },
+      {
+        id: 'next-level-scene',
+        weight: 1,
+        afterOpen: true,
+        run: async ({ reportProgress }) => {
+          reportProgress(0.2);
+          if (game.scene.isActive('Game')) game.scene.stop('Game');
+          game.scene.start('Game');
+          game.scene.bringToTop('Game');
+          game.scene.bringToTop(FactoryLoadingOverlayScene.KEY);
+          await waitLayout();
+          reportProgress(1);
+        },
+      },
+    ];
+    await overlay.play(new LoadingViewModel({
+      ...LOADING_TIMING_PRESETS.nextLevel,
+      description: `Loading Level ${next}…`,
+    }, tasks), 'next-level');
+  } catch (error) {
+    console.error('next level transition failed', error);
+  }
+}
+
+$('#btn-reset-data').addEventListener('click', () => {
+  if (!window.confirm('Reset toàn bộ save data về ban đầu?')) return;
+  localStorage.removeItem(STORAGE_KEY);
+  location.reload();
+});
+
+(window as unknown as {
+  __factoryDemo?: {
+    returnHome: () => void;
+    enterGame: () => void;
+    nextLevel: () => void;
+    getPlayLevel: () => number;
+    refresh: () => Promise<void>;
+    /** QA Test tools overlay — skill `tool-demo-qa`. */
+    setToolsEnabled: (enabled: boolean) => void;
+    toolsEnabled: () => boolean;
+    getDeviceTier: () => ReturnType<DeviceTierSession['getState']>;
+    setDeviceTier: (override: 'auto' | 'potato' | 'low' | 'mid' | 'high') => void;
+  };
+}).__factoryDemo = {
+  enterGame: () => {
+    void enterGame();
+  },
+  returnHome: () => {
+    void returnHome();
+  },
+  nextLevel: () => {
+    void loadNextLevel();
+  },
+  getPlayLevel: () => Number(game.registry.get('playLevel') ?? 1),
+  refresh: () => refresh(),
+  setToolsEnabled: (enabled: boolean) => {
+    demoTools.setEnabled(enabled);
+  },
+  toolsEnabled: () => demoTools.enabled,
+  getDeviceTier: () => deviceTierSession.getState(),
+  setDeviceTier: (override) => {
+    deviceTierSession.setOverride(override);
+  },
+};
+
+game.events.on('demo-mode', (mode: 'boot' | 'home' | 'game') => {
+  setPhoneMode(mode);
+  if (mode === 'boot') $('#loading-overlay').classList.add('is-hidden');
+  resizeToDesignCanvas();
+  window.dispatchEvent(new Event('resize'));
+});
+
+setPhoneMode('boot');
+document.body.dataset.sceneLifecycle = 'booting';
+
+void (async () => {
+  const waitHome = new Promise<void>((resolve) => {
+    const handler = (mode: string) => {
+      if (mode === 'home') {
+        game.events.off('demo-mode', handler);
+        resolve();
+      }
+    };
+    game.events.on('demo-mode', handler);
+  });
+  try {
+    await waitHome;
+    await refresh();
+    $('#loading-overlay').classList.add('is-hidden');
+    document.body.dataset.sceneLifecycle = 'ready';
+    setStatus('Ready');
+  } catch (error) {
+    setStatus('Load failed', 'error');
+    $('#loading-overlay').textContent = error instanceof Error ? error.message : 'Load failed';
+  }
+})();