@quybt93/pcgf 0.0.1

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

@@ -0,0 +1,156 @@
+import * as Phaser from 'phaser';
+import { getSfxVolume } from '../../../templates/ui/audio-settings';
+import { bindButtonMotion } from '../../../templates/motion';
+
+const CLICK_URL = '/assets/sfx/ui_click.mp3';
+const CLOSE_URL = '/assets/sfx/ui_close.mp3';
+const CLICK_KEY = 'ui_click';
+const CLOSE_KEY = 'ui_close';
+
+let sharedGame: Phaser.Game | undefined;
+
+/** One unlocked element per SFX; clones play overlapping presses. */
+const htmlPlayers: { click?: HTMLAudioElement; close?: HTMLAudioElement } = {};
+
+export function setUiAudioGame(game: Phaser.Game): void {
+  sharedGame = game;
+}
+
+function ensureHtmlPlayer(kind: 'click' | 'close'): HTMLAudioElement {
+  const existing = htmlPlayers[kind];
+  if (existing) return existing;
+  const audio = new Audio(kind === 'click' ? CLICK_URL : CLOSE_URL);
+  audio.preload = 'auto';
+  htmlPlayers[kind] = audio;
+  return audio;
+}
+
+/** Warm HTML players; also queue Phaser cache when a scene loader is available. */
+export function preloadUiAudio(scene: Phaser.Scene): void {
+  ensureHtmlPlayer('click');
+  ensureHtmlPlayer('close');
+  try {
+    ensureHtmlPlayer('click').load();
+    ensureHtmlPlayer('close').load();
+  } catch {
+    /* ignore */
+  }
+  if (!scene.cache.audio.exists(CLICK_KEY)) {
+    scene.load.audio(CLICK_KEY, CLICK_URL);
+  }
+  if (!scene.cache.audio.exists(CLOSE_KEY)) {
+    scene.load.audio(CLOSE_KEY, CLOSE_URL);
+  }
+}
+
+function playHtml(kind: 'click' | 'close', baseVolume: number): void {
+  const volume = Math.max(0, Math.min(1, baseVolume * getSfxVolume()));
+  if (volume <= 0.001) return;
+  try {
+    const base = ensureHtmlPlayer(kind);
+    const node = base.cloneNode(true) as HTMLAudioElement;
+    node.volume = volume;
+    const run = node.play();
+    if (run && typeof run.catch === 'function') {
+      void run.catch(() => {
+        /* autoplay until gesture — ignore */
+      });
+    }
+  } catch {
+    /* ignore */
+  }
+}
+
+/** Shared click — HTMLAudio so DOM/Phaser never depend on Phaser loader cache. */
+export function playUiClick(_scene?: Phaser.Scene): void {
+  playHtml('click', 0.8);
+}
+
+/** Shared close — HTMLAudio primary. */
+export function playUiClose(_scene?: Phaser.Scene): void {
+  playHtml('close', 0.7);
+}
+
+/**
+ * @deprecated Use `bindButtonMotion` from `templates/motion` (see phaser-ui-motion skill).
+ */
+export function wirePhaserButtonHover(
+  scene: Phaser.Scene,
+  root: Phaser.GameObjects.Container,
+  hit: Phaser.GameObjects.GameObject,
+  onClick: () => void,
+): void {
+  const hitArea = hit as Phaser.GameObjects.Rectangle;
+  bindButtonMotion(scene, hitArea, hitArea, {
+    scaleTarget: root,
+    onClickSound: () => playUiClick(scene),
+    onAccepted: onClick,
+  });
+}
+
+function isCloseControl(el: HTMLElement): boolean {
+  if (el instanceof HTMLButtonElement || el.getAttribute('role') === 'button') {
+    return (
+      el.classList.contains('modal-close') ||
+      el.id === 'inventory-close' ||
+      el.id === 'settings-close' ||
+      el.hasAttribute('data-close-popup') ||
+      el.getAttribute('aria-label') === 'Close'
+    );
+  }
+  return false;
+}
+
+function findUiControl(target: EventTarget | null): HTMLElement | null {
+  const el = target as HTMLElement | null;
+  if (!el?.closest) return null;
+  const button = el.closest('button, [role="button"]');
+  return button instanceof HTMLElement ? button : null;
+}
+
+/**
+ * Demo-wide DOM SFX:
+ * - every `button` / `[role=button]` → click (or close if ×)
+ * - click on modal dim (target === backdrop) → close
+ */
+export function bindDomButtonJuice(): void {
+  // Prime decode on first gesture so later clones play instantly.
+  document.addEventListener(
+    'pointerdown',
+    () => {
+      const click = ensureHtmlPlayer('click');
+      const close = ensureHtmlPlayer('close');
+      click.load();
+      close.load();
+      sharedGame?.sound?.unlock?.();
+    },
+    { once: true, capture: true },
+  );
+
+  document.addEventListener(
+    'click',
+    (event) => {
+      const target = event.target as HTMLElement | null;
+      if (!target) return;
+
+      if (target.classList?.contains('modal-backdrop') || target.classList?.contains('settings-backdrop')) {
+        playUiClose();
+        return;
+      }
+
+      const control = findUiControl(target);
+      if (!control) return;
+      if (control instanceof HTMLButtonElement && control.disabled) return;
+      if (control.getAttribute('aria-disabled') === 'true') return;
+      // Settings Home is an action button (click), not close.
+      if (control.id === 'settings-home') {
+        playUiClick();
+        return;
+      }
+
+      if (isCloseControl(control)) playUiClose();
+      else playUiClick();
+    },
+    true,
+  );
+}

package/plugins/phaser-casual-game-factory/examples/factory-browser-demo/tests/browser-smoke.spec.ts

@@ -0,0 +1,170 @@
+import { test, expect } from '@playwright/test';
+
+async function dismissRewardIfOpen(page: import('@playwright/test').Page): Promise<void> {
+  const levelUp = page.locator('#levelup-modal.is-open');
+  if (await levelUp.count()) {
+    await page.locator('#levelup-ok').click();
+    await expect(page.locator('#levelup-modal')).not.toHaveClass(/is-open/);
+  }
+  const reward = page.locator('#reward-modal.is-open');
+  if (await reward.count()) {
+    await page.locator('#reward-modal').click({ position: { x: 8, y: 8 } });
+    await expect(page.locator('#reward-modal')).not.toHaveClass(/is-open/);
+  }
+}
+
+test.beforeEach(async ({ page }) => {
+  await page.addInitScript(() => {
+    localStorage.setItem('pcgf.demo.toolsEnabled', '1');
+  });
+  await page.goto('/?tools=1', { waitUntil: 'domcontentloaded' });
+  await expect(page.locator('[data-testid="loading-overlay"]')).toHaveClass(/is-hidden/, { timeout: 30_000 });
+  await expect(page.locator('body')).not.toHaveClass(/splash-fullscreen/, { timeout: 30_000 });
+});
+
+async function openDemoTools(page: import('@playwright/test').Page): Promise<void> {
+  const panel = page.locator('[data-testid="tool-panel"]');
+  if (await panel.isVisible().catch(() => false)) return;
+  await page.locator('[data-testid="tools-fab"]').click();
+  await expect(panel).toBeVisible();
+}
+
+test('boots through loading gate and completes Phaser scene lifecycle', async ({ page }) => {
+  await expect(page.locator('[data-testid="loading-overlay"]')).toHaveClass(/is-hidden/);
+  await expect(page.locator('[data-testid="phone-frame"]')).toBeVisible();
+  await expect(page.locator('body')).toHaveAttribute('data-scene-lifecycle', 'ready');
+  await expect(page.locator('#status')).toHaveText('Ready');
+});
+
+test('full sample flow commits economy and progression state', async ({ page }) => {
+  await openDemoTools(page);
+  await page.locator('[data-action="grant"]').click();
+  await dismissRewardIfOpen(page);
+  await expect(page.locator('#hud-gold')).toHaveText('100');
+  await page.locator('[data-action="add-xp"]').click();
+  await dismissRewardIfOpen(page);
+  await expect(page.locator('#player-level-text')).toHaveText('Lv 2');
+  await page.locator('[data-action="create-item"]').click();
+  await page.locator('[data-action="seed-materials"]').click();
+  await dismissRewardIfOpen(page);
+  await page.locator('#btn-bag').click();
+  await page.locator('.bag-tab[data-bag-tab="equipment"]').click();
+  await page.locator('[data-equipment-detail]').click();
+  await expect(page.locator('#inventory-detail')).toHaveClass(/is-open/);
+  await page.locator('#reroll-item').click();
+  await expect(page.locator('#reroll-preview')).toContainText('Cost: gem 5');
+  await page.locator('#apply-item').click();
+  await page.locator('#inventory-close').click({ force: true });
+  await expect(page.locator('#inventory-detail')).not.toHaveClass(/is-open/);
+  await page.locator('.bag-tab[data-bag-tab="material"]').click();
+  await page.locator('[data-inventory-detail="choiceTicket"]').click();
+  await expect(page.locator('#inventory-open')).toBeDisabled();
+  await page.locator('[data-choice-id="coin"]').click();
+  await expect(page.locator('#inventory-open')).toBeEnabled();
+  await page.locator('#inventory-open').click();
+  await dismissRewardIfOpen(page);
+  // grant 100 + character Lv2 reward 50 + choiceTicket coin 100
+  await expect(page.locator('#hud-gold')).toHaveText('250');
+  await page.reload({ waitUntil: 'domcontentloaded' });
+  await expect(page.locator('[data-testid="loading-overlay"]')).toHaveClass(/is-hidden/);
+  await expect(page.locator('#hud-gold')).toHaveText('250');
+  await expect(page.locator('#player-level-text')).toHaveText('Lv 2');
+});
+
+test('renders phone shell above tools on a mobile viewport', async ({ browser }) => {
+  const context = await browser.newContext({ viewport: { width: 390, height: 844 }, deviceScaleFactor: 2, isMobile: true });
+  const page = await context.newPage();
+  await page.goto('/?tools=1', { waitUntil: 'domcontentloaded' });
+  await expect(page.locator('[data-testid="loading-overlay"]')).toHaveClass(/is-hidden/);
+  await expect(page.locator('[data-testid="phone-frame"]')).toBeVisible();
+  await expect(page.locator('[data-testid="tools-fab"]')).toBeVisible();
+  const stageBox = await page.locator('.stage-screen').boundingBox();
+  const viewport = page.viewportSize();
+  expect(stageBox).toBeTruthy();
+  expect(viewport).toBeTruthy();
+  if (stageBox && viewport) {
+    const stageCenter = stageBox.x + stageBox.width / 2;
+    expect(Math.abs(stageCenter - viewport.width / 2)).toBeLessThan(24);
+  }
+  await context.close();
+});
+
+test('scene can reload without duplicate boot errors', async ({ page }) => {
+  const errors: string[] = [];
+  page.on('pageerror', (error) => errors.push(error.message));
+  await page.reload({ waitUntil: 'domcontentloaded' });
+  await expect(page.locator('[data-testid="loading-overlay"]')).toHaveClass(/is-hidden/);
+  await expect(page.locator('body')).toHaveAttribute('data-scene-lifecycle', 'ready');
+  expect(errors).toEqual([]);
+});
+
+test('Play enters Game scene and Back returns Home', async ({ page }) => {
+  await expect(page.locator('body')).toHaveAttribute('data-scene-lifecycle', 'ready');
+  await page.locator('#btn-play').click();
+  await expect(page.locator('body')).toHaveAttribute('data-scene-lifecycle', 'game', { timeout: 20_000 });
+  await expect(page.locator('.stage-screen')).toHaveClass(/is-game/);
+  await expect
+    .poll(async () => page.evaluate(() => (window as unknown as { __factoryDemo?: { getPlayLevel: () => number } }).__factoryDemo?.getPlayLevel() ?? 0), {
+      timeout: 5_000,
+    })
+    .toBe(1);
+  await page.evaluate(() => {
+    (window as unknown as { __factoryDemo?: { nextLevel: () => void } }).__factoryDemo?.nextLevel();
+  });
+  await expect
+    .poll(async () => page.evaluate(() => (window as unknown as { __factoryDemo?: { getPlayLevel: () => number } }).__factoryDemo?.getPlayLevel() ?? 0), {
+      timeout: 15_000,
+    })
+    .toBe(2);
+  const returnRequestedAt = Date.now();
+  await page.evaluate(() => {
+    (window as unknown as { __factoryDemo?: { returnHome: () => void } }).__factoryDemo?.returnHome();
+  });
+  await expect(page.locator('body')).toHaveAttribute('data-scene-lifecycle', 'ready', { timeout: 20_000 });
+  // Return was requested while Next Level was still closing. Its own
+  // open 0 / min 1s / close 1s transition must be queued, not skipped.
+  expect(Date.now() - returnRequestedAt).toBeGreaterThanOrEqual(2_800);
+  await expect(page.locator('.stage-screen')).toHaveClass(/is-home/);
+  await expect(page.locator('#view-main')).toBeVisible();
+});
+
+test('real Game Back button runs one visible loading transition', async ({ page }) => {
+  const enterStartedAt = Date.now();
+  await page.locator('#btn-play').click();
+  await expect(page.locator('body')).toHaveAttribute('data-scene-lifecycle', 'game', { timeout: 20_000 });
+  const enterElapsed = Date.now() - enterStartedAt;
+  expect(enterElapsed).toBeGreaterThanOrEqual(1_800);
+  expect(enterElapsed).toBeLessThan(3_500);
+
+  const canvas = page.locator('#game canvas');
+  const box = await canvas.boundingBox();
+  expect(box).toBeTruthy();
+  const returnStartedAt = Date.now();
+  if (box) {
+    await canvas.click({
+      position: {
+        x: box.width / 2,
+        y: (554 / 640) * box.height,
+      },
+    });
+  }
+  await page.waitForTimeout(300);
+  // HomeScene may already be created underneath, but its HTML view must not
+  // cover the Phaser LoadingView until the transition has completed.
+  await expect(page.locator('.stage-screen')).toHaveClass(/is-game.*is-revealing-home|is-revealing-home.*is-game/);
+  await expect(page.locator('#view-main')).toBeVisible();
+  await expect(page.locator('.stage-hud')).toBeVisible();
+  await expect(page.locator('.stage-nav')).toBeVisible();
+  const revealPanelBox = await page.locator('#view-main').boundingBox();
+  await expect(page.locator('body')).toHaveAttribute('data-scene-lifecycle', 'ready', { timeout: 20_000 });
+  const returnElapsed = Date.now() - returnStartedAt;
+  expect(returnElapsed).toBeGreaterThanOrEqual(1_800);
+  expect(returnElapsed).toBeLessThan(3_500);
+  const finalPanelBox = await page.locator('#view-main').boundingBox();
+  expect(revealPanelBox).toBeTruthy();
+  expect(finalPanelBox).toBeTruthy();
+  if (revealPanelBox && finalPanelBox) {
+    expect(Math.abs(revealPanelBox.y - finalPanelBox.y)).toBeLessThan(2);
+    expect(Math.abs(revealPanelBox.height - finalPanelBox.height)).toBeLessThan(2);
+  }
+});

package/plugins/phaser-casual-game-factory/examples/factory-browser-demo/vite.config.ts

@@ -0,0 +1,23 @@
+import { defineConfig } from 'vite';
+import { fileURLToPath, URL } from 'node:url';
+
+// Templates live above this example's node_modules. Pin Phaser so Vite can
+// bundle template imports exactly like a consuming game would.
+export default defineConfig({
+  resolve: {
+    alias: {
+      phaser: fileURLToPath(new URL('./node_modules/phaser/dist/phaser.esm.js', import.meta.url)),
+      rxjs: fileURLToPath(new URL('./node_modules/rxjs/dist/esm/index.js', import.meta.url)),
+    },
+  },
+  optimizeDeps: { exclude: ['phaser', 'rxjs'] },
+  // Avoid default 5173 — often taken by other local Vite apps.
+  server: {
+    port: 5180,
+    strictPort: false,
+  },
+  preview: {
+    port: 4180,
+    strictPort: false,
+  },
+});

package/plugins/phaser-casual-game-factory/examples/leveling-demo-config.ts

@@ -0,0 +1,107 @@
+import type { LevelingConfig } from '../templates/leveling';
+
+function heroTrack(id: string, shardResource: string): LevelingConfig['tracks'][string] {
+  const costs: Record<string, Array<{ resourceId: string; amount: number }>> = {};
+  for (let level = 2; level <= 10; level += 1) {
+    costs[String(level)] = [
+      { resourceId: 'coin', amount: 100 * (level - 1) },
+      { resourceId: shardResource, amount: (level - 1) * 2 },
+    ];
+  }
+  return {
+    id,
+    mode: 'resource',
+    startLevel: 1,
+    maxLevel: 10,
+    upgradeCosts: costs,
+    reset: { enabled: true, refundPercent: 100 },
+  };
+}
+
+export const levelingDemoConfig: LevelingConfig = {
+  tracks: {
+    character: {
+      id: 'character',
+      mode: 'experience',
+      startLevel: 1,
+      maxLevel: 4,
+      xpToNext: { '1': 100, '2': 150, '3': 3000 },
+      rewards: {
+        '2': [
+          { type: 'resource', resourceId: 'coin', amount: 50 },
+          { type: 'feature-unlocked', featureId: 'daily-quest' },
+        ],
+        '3': [{ type: 'feature-unlocked', featureId: 'hard-mode' }],
+      },
+      reset: { enabled: true, resetRewards: false },
+    },
+    hero: {
+      id: 'hero',
+      mode: 'resource',
+      startLevel: 0,
+      maxLevel: 10,
+      upgradeCosts: {
+        '1': [{ resourceId: 'coin', amount: 100 }],
+        '2': [
+          { resourceId: 'coin', amount: 200 },
+          { resourceId: 'shard', amount: 2 },
+        ],
+        '3': [{ resourceId: 'coin', amount: 300 }, { resourceId: 'shard', amount: 3 }],
+        '4': [{ resourceId: 'coin', amount: 400 }, { resourceId: 'shard', amount: 4 }],
+        '5': [{ resourceId: 'coin', amount: 500 }, { resourceId: 'shard', amount: 5 }],
+        '6': [{ resourceId: 'coin', amount: 600 }, { resourceId: 'shard', amount: 6 }],
+        '7': [{ resourceId: 'coin', amount: 700 }, { resourceId: 'shard', amount: 7 }],
+        '8': [{ resourceId: 'coin', amount: 800 }, { resourceId: 'shard', amount: 8 }],
+        '9': [{ resourceId: 'coin', amount: 900 }, { resourceId: 'shard', amount: 9 }],
+        '10': [{ resourceId: 'coin', amount: 1000 }, { resourceId: 'shard', amount: 10 }],
+      },
+      upgradeConditions: {
+        '2': [{ type: 'track-level-at-least', trackId: 'character', level: 2 }],
+      },
+      reset: { enabled: true, refundPercent: 50 },
+    },
+    heroRanger: heroTrack('heroRanger', 'shardRanger'),
+    heroGuardian: heroTrack('heroGuardian', 'shardGuardian'),
+    heroMage: heroTrack('heroMage', 'shardMage'),
+    heroKnight: heroTrack('heroKnight', 'shardKnight'),
+    battlePass: {
+      id: 'battlePass',
+      mode: 'experience',
+      startLevel: 0,
+      maxLevel: 30,
+      xpToNext: {
+        '0': 1000,
+        '1': 2200,
+        '2': 2200,
+        '3': 2200,
+        '4': 2200,
+        '5': 2200,
+        '6': 2200,
+        '7': 2200,
+        '8': 2200,
+        '9': 2200,
+        '10': 2200,
+        '11': 2200,
+        '12': 2200,
+        '13': 2200,
+        '14': 2200,
+        '15': 2200,
+        '16': 2200,
+        '17': 2200,
+        '18': 2200,
+        '19': 2200,
+        '20': 2200,
+        '21': 2200,
+        '22': 2200,
+        '23': 2200,
+        '24': 2200,
+        '25': 2200,
+        '26': 2200,
+        '27': 2200,
+        '28': 2200,
+        '29': 2200,
+      },
+      reset: { enabled: true, resetRewards: false },
+    },
+  },
+};

package/plugins/phaser-casual-game-factory/references/condition-service.md

@@ -0,0 +1,38 @@
+# ConditionService reference
+
+## Remote-safe configuration
+
+```ts
+const config: ConditionConfig = {
+  definitions: {
+    unlockHero: {
+      id: 'unlockHero',
+      title: 'Hero feature',
+      root: {
+        type: 'all',
+        conditions: [
+          { type: 'metric', metric: 'level', params: { trackId: 'character' }, operator: '>=', target: 10, description: 'Reach Player Lv {target}' },
+          { type: 'metric', metric: 'login-streak', operator: '>=', target: 3, description: 'Login {current}/{target} consecutive days' },
+        ],
+      },
+    },
+  },
+};
+conditions.replaceConfig(config);
+```
+
+Descriptions accept `{current}` and `{target}`. `progressFormat` may be `fraction`, `percent`, `both`, or `none`. Use `getViewModel()` instead of rebuilding the numerator/denominator in UI.
+
+## Metric providers
+
+The built-in metrics read persistent state: `level`, `login-days`, `login-streak`, and `resource`. Add new metrics without changing the evaluator:
+
+```ts
+const questProvider: ConditionMetricProvider = {
+  metric: 'quest-count',
+  getValue: () => questService.completedCount(),
+};
+const conditions = new DefaultConditionService(repository, config, [questProvider]);
+```
+
+Keep a provider read-only. If a condition unlocks or grants something, evaluate first and execute the grant with the owning atomic service. Remote config is client presentation/eligibility data unless the server independently validates the same rule.

package/plugins/phaser-casual-game-factory/references/core-contracts.md

@@ -0,0 +1,39 @@
+# Core contracts
+
+Core contracts are the stable boundary between reusable services, Phaser scenes, UI, and game-specific gameplay. Copy the templates from `templates/core/` into a game project and implement adapters around them.
+
+## Rules
+
+1. Keep contracts independent of Phaser whenever possible.
+2. Scenes coordinate; services own rules; UI renders state and emits intent.
+3. Prefer **MVVM + RxJS** when a feature needs reactive View state or multi-step async
+   presentation (LoadingView is the reference). Pure domain services stay RxJS-free when
+   no View is involved.
+4. Default scenes: **Boot → Home → Game**. `FactoryLoadingOverlay` is a technical Loading
+   View scene, not a gameplay destination.
+5. Route storage, time, loading, and layout through their contracts.
+6. Use typed events instead of arbitrary string payloads.
+7. Include a reason for economy, XP, and reward mutations.
+8. Keep gameplay-specific state in the game module, not shared services.
+9. Use fake storage and fake clocks in tests.
+10. Use `templates/loading-view/` for blocking loads; ViewModel owns timing/progress
+    and the platform View owns all presentation. Home↔Game / Next Level: pause BitmapMask
+    while fully covered; paint progress only on whole-percent steps (Δ ≥ 1%). Boot company
+    brand → skill `phaser-studio25-boot-brand`. See `references/loading-view.md`.
+
+## Recommended dependency direction
+
+```text
+Scene -> Gameplay module -> Shared services -> Core contracts
+UI -> ViewModel (RxJS state$) -> Shared services
+Adapters -> Browser/Phaser APIs
+```
+
+The core layer must not import Phaser or access `localStorage` directly.
+Blocking loading follows:
+
+```text
+Navigation -> LoadingViewModel -> LoadingView (Studio25 Boot | Phaser overlay) -> prepared destination
+```
+
+See `references/loading-view.md` for progress timing and hybrid HTML layering.

package/plugins/phaser-casual-game-factory/references/daily-login-service.md

@@ -0,0 +1,32 @@
+# DailyLoginService reference
+
+## Game entry
+
+```ts
+const dailyLogin = new DefaultDailyLoginService(repository, time, events);
+await dailyLogin.startAutoRegistration({ source: 'game' });
+```
+
+The first call registers today. Each later `time:new-day` registers the new configured-timezone day. `stopAutoRegistration()` removes only the new-day listener; it does not delete login history.
+
+## Portal or third-party login
+
+```ts
+await dailyLogin.registerLogin({
+  dayKey: portal.verifiedDayKey,
+  source: 'portal',
+  transactionId: `portal-login:${portal.callbackId}`,
+});
+```
+
+Only send verified historical/current day keys. The local implementation refuses future days. When server authority is enabled, validate the callback and date on the backend as well.
+
+## UI queries
+
+```ts
+const state = await dailyLogin.getState();
+const checkedToday = await dailyLogin.hasLoggedIn(time.todayKey());
+const streak = await dailyLogin.getConsecutiveLoginDays();
+```
+
+Use `state.days[dayKey]` to render individual calendar cells. Do not assume a `new-day` event means the player has already claimed any gift: registration and reward claim are deliberately separate flows.