@quybt93/pcgf 0.0.1

package/plugins/phaser-casual-game-factory/templates/demo-tools/demo-device-tier.ts

@@ -0,0 +1,73 @@
+/**
+ * Wire DeviceTierSession into the Test tools panel (display + force buttons).
+ * @see skills/tool-demo-qa/SKILL.md
+ */
+
+import {
+  DEVICE_TIERS,
+  type DeviceTierOverride,
+  type DeviceTierSession,
+  type DeviceTierState,
+} from '../adaptive-loading/device-tier-session';
+
+export type BindDemoDeviceTierOptions = {
+  session: DeviceTierSession;
+  statusEl?: HTMLElement | null;
+  buttonsRoot?: ParentNode | Document | null;
+  onChange?: (state: DeviceTierState) => void;
+};
+
+export type DemoDeviceTierHandle = {
+  dispose: () => void;
+};
+
+function formatStatus(state: DeviceTierState): string {
+  const forced = state.override !== 'auto';
+  const mode = forced ? `force ${state.override}` : 'auto';
+  return `Tier: ${state.effective.tier}  ·  ${mode}  ·  detect ${state.detected.tier}`;
+}
+
+/**
+ * Updates `#device-tier-status` and `[data-tier]` buttons inside the tools panel.
+ */
+export function bindDemoDeviceTier(options: BindDemoDeviceTierOptions): DemoDeviceTierHandle {
+  const doc = typeof document !== 'undefined' ? document : null;
+  const statusEl =
+    options.statusEl ?? doc?.querySelector<HTMLElement>('#device-tier-status') ?? null;
+  const root = options.buttonsRoot ?? doc;
+  const buttons = root
+    ? Array.from(root.querySelectorAll<HTMLButtonElement>('[data-tier]'))
+    : [];
+
+  const paint = (state: DeviceTierState): void => {
+    if (statusEl) statusEl.textContent = formatStatus(state);
+    for (const btn of buttons) {
+      const value = (btn.dataset.tier ?? '') as DeviceTierOverride;
+      const active = value === state.override;
+      btn.classList.toggle('is-active', active);
+      btn.setAttribute('aria-pressed', active ? 'true' : 'false');
+    }
+    options.onChange?.(state);
+  };
+
+  const onClick = (event: Event): void => {
+    const btn = (event.target as HTMLElement | null)?.closest?.('[data-tier]') as
+      | HTMLButtonElement
+      | null;
+    if (!btn) return;
+    const raw = (btn.dataset.tier ?? 'auto') as DeviceTierOverride;
+    const next: DeviceTierOverride =
+      raw === 'auto' || (DEVICE_TIERS as readonly string[]).includes(raw) ? raw : 'auto';
+    paint(options.session.setOverride(next));
+  };
+
+  for (const btn of buttons) btn.addEventListener('click', onClick);
+  const unsub = options.session.subscribe(paint);
+
+  return {
+    dispose: () => {
+      unsub();
+      for (const btn of buttons) btn.removeEventListener('click', onClick);
+    },
+  };
+}

package/plugins/phaser-casual-game-factory/templates/demo-tools/demo-perf.ts

@@ -0,0 +1,232 @@
+/**
+ * Optional QA FPS / frame-time HUD for factory demos.
+ * Opt-in overlay — not part of Boot→Home→Game product flow.
+ * When Test tools are fully off, sampling must stop (no rAF / no DOM).
+ *
+ * @see skills/tool-demo-qa/SKILL.md
+ */
+
+export const DEMO_PERF_HUD_STORAGE_KEY = 'pcgf.demo.perfHud';
+
+export type PhaserLoopLike = {
+  actualFps?: number;
+  delta?: number;
+};
+
+export type MountDemoPerfHudOptions = {
+  /** Prefer Phaser loop when available; otherwise rAF sampling. */
+  getLoop?: () => PhaserLoopLike | null | undefined;
+  /** Optional live device tier label (potato/low/mid/high). */
+  getTierLabel?: () => string | null | undefined;
+  /**
+   * Master gate from Test tools. When false, HUD is removed and sampling stops
+   * even if the user previously toggled Perf HUD on.
+   */
+  toolsAllowed?: boolean;
+  doc?: Document;
+  storage?: Pick<Storage, 'getItem' | 'setItem'> | null;
+  /** Default when storage unset. */
+  defaultEnabled?: boolean;
+  /** Smooth window size for rAF fallback (frames). */
+  sampleWindow?: number;
+};
+
+export type DemoPerfHudHandle = {
+  /** User toggle (persisted). No-op for sampling while tools are off. */
+  setEnabled: (enabled: boolean) => void;
+  /** User preference only (ignores tools gate). */
+  isEnabled: () => boolean;
+  /** True only when tools allow + user enabled — sampling is live. */
+  isLive: () => boolean;
+  /**
+   * Gate from `mountDemoTools` / production disable.
+   * Does not clear the user's Perf HUD preference.
+   */
+  setToolsAllowed: (allowed: boolean) => void;
+  /** Update the tier row under ms (e.g. after QA force). */
+  setTierLabel: (label: string | null | undefined) => void;
+  dispose: () => void;
+};
+
+function parseBoolFlag(raw: string | null | undefined): boolean | null {
+  if (raw == null || raw === '') return null;
+  const v = raw.trim().toLowerCase();
+  if (v === '0' || v === 'false' || v === 'off' || v === 'no') return false;
+  if (v === '1' || v === 'true' || v === 'on' || v === 'yes') return true;
+  return null;
+}
+
+/**
+ * Mount a fixed FPS / ms / tier HUD. Sampling runs only while tools allow + user on.
+ */
+export function mountDemoPerfHud(options: MountDemoPerfHudOptions = {}): DemoPerfHudHandle {
+  const doc = options.doc ?? (typeof document !== 'undefined' ? document : null);
+  const storage =
+    options.storage === undefined
+      ? typeof localStorage !== 'undefined'
+        ? localStorage
+        : null
+      : options.storage;
+  const sampleWindow = Math.max(8, options.sampleWindow ?? 30);
+
+  let userEnabled = options.defaultEnabled ?? false;
+  if (storage) {
+    try {
+      const stored = parseBoolFlag(storage.getItem(DEMO_PERF_HUD_STORAGE_KEY));
+      if (stored != null) userEnabled = stored;
+    } catch {
+      /* ignore */
+    }
+  }
+
+  let toolsAllowed = options.toolsAllowed ?? true;
+  let hud: HTMLElement | null = null;
+  let fpsEl: HTMLElement | null = null;
+  let msEl: HTMLElement | null = null;
+  let tierEl: HTMLElement | null = null;
+  let tierLabel = options.getTierLabel?.()?.trim() || '--';
+  let rafId = 0;
+  let lastTs = 0;
+  const deltas: number[] = [];
+
+  const isLive = (): boolean => toolsAllowed && userEnabled;
+
+  const tearDownHud = (): void => {
+    hud?.remove();
+    hud = null;
+    fpsEl = null;
+    msEl = null;
+    tierEl = null;
+  };
+
+  const ensureHud = (): void => {
+    if (!doc || hud) return;
+    hud = doc.createElement('div');
+    hud.id = 'demo-perf-hud';
+    hud.className = 'demo-perf-hud';
+    hud.dataset.testid = 'demo-perf-hud';
+    hud.setAttribute('aria-live', 'polite');
+    hud.innerHTML = `
+      <div class="demo-perf-row"><span>FPS</span><strong data-perf="fps">--</strong></div>
+      <div class="demo-perf-row"><span>ms</span><strong data-perf="ms">--</strong></div>
+      <div class="demo-perf-row"><span>tier</span><strong data-perf="tier">--</strong></div>
+    `;
+    doc.body.appendChild(hud);
+    fpsEl = hud.querySelector('[data-perf="fps"]');
+    msEl = hud.querySelector('[data-perf="ms"]');
+    tierEl = hud.querySelector('[data-perf="tier"]');
+    if (tierEl) tierEl.textContent = tierLabel;
+  };
+
+  const persist = (next: boolean): void => {
+    if (!storage) return;
+    try {
+      storage.setItem(DEMO_PERF_HUD_STORAGE_KEY, next ? '1' : '0');
+    } catch {
+      /* ignore */
+    }
+  };
+
+  const paintTier = (): void => {
+    const next = options.getTierLabel?.()?.trim();
+    if (next) tierLabel = next;
+    if (tierEl) tierEl.textContent = tierLabel || '--';
+  };
+
+  const paint = (fps: number, frameMs: number): void => {
+    if (fpsEl) fpsEl.textContent = Number.isFinite(fps) ? String(Math.round(fps)) : '--';
+    if (msEl) msEl.textContent = Number.isFinite(frameMs) ? frameMs.toFixed(1) : '--';
+    paintTier();
+  };
+
+  const stopSample = (): void => {
+    if (rafId) {
+      cancelAnimationFrame(rafId);
+      rafId = 0;
+    }
+    lastTs = 0;
+    deltas.length = 0;
+  };
+
+  const tick = (ts: number): void => {
+    if (!isLive()) {
+      stopSample();
+      return;
+    }
+
+    const loop = options.getLoop?.() ?? null;
+    const loopFps = loop?.actualFps;
+    const loopDelta = loop?.delta;
+
+    if (typeof loopFps === 'number' && loopFps > 0) {
+      const frameMs =
+        typeof loopDelta === 'number' && loopDelta > 0 ? loopDelta : 1000 / loopFps;
+      paint(loopFps, frameMs);
+    } else if (lastTs > 0) {
+      const dt = ts - lastTs;
+      if (dt > 0 && dt < 1000) {
+        deltas.push(dt);
+        if (deltas.length > sampleWindow) deltas.shift();
+        const avg = deltas.reduce((a, b) => a + b, 0) / deltas.length;
+        paint(1000 / avg, avg);
+      }
+    }
+
+    lastTs = ts;
+    rafId = requestAnimationFrame(tick);
+  };
+
+  const startSample = (): void => {
+    stopSample();
+    if (typeof requestAnimationFrame !== 'function') return;
+    rafId = requestAnimationFrame(tick);
+  };
+
+  const applyVisible = (): void => {
+    if (!isLive()) {
+      stopSample();
+      tearDownHud();
+      return;
+    }
+    ensureHud();
+    if (hud) hud.hidden = false;
+    startSample();
+  };
+
+  applyVisible();
+
+  return {
+    setEnabled: (next: boolean) => {
+      userEnabled = next;
+      persist(next);
+      applyVisible();
+    },
+    isEnabled: () => userEnabled,
+    isLive,
+    setToolsAllowed: (allowed: boolean) => {
+      toolsAllowed = allowed;
+      applyVisible();
+    },
+    setTierLabel: (label: string | null | undefined) => {
+      tierLabel = label?.trim() || '--';
+      if (tierEl) tierEl.textContent = tierLabel;
+    },
+    dispose: () => {
+      stopSample();
+      tearDownHud();
+      toolsAllowed = false;
+      userEnabled = false;
+    },
+  };
+}
+
+/** Sync a toggle button label / aria-pressed with HUD state. */
+export function syncDemoPerfToggleButton(
+  button: HTMLButtonElement | null | undefined,
+  enabled: boolean,
+): void {
+  if (!button) return;
+  button.setAttribute('aria-pressed', enabled ? 'true' : 'false');
+  button.textContent = enabled ? 'Perf HUD: On' : 'Perf HUD: Off';
+  button.classList.toggle('is-active', enabled);
+}

package/plugins/phaser-casual-game-factory/templates/demo-tools/demo-tools.css

@@ -0,0 +1,355 @@
+/* Optional Test tools FAB + popup — skill tool-demo-qa.
+   Keep out of product Boot→Home→Game chrome. Toggle via body.demo-tools-off. */
+
+body.demo-tools-off .tools-fab,
+body.demo-tools-off .tool-panel,
+body.demo-tools-off .demo-perf-hud {
+  display: none !important;
+  pointer-events: none !important;
+}
+
+.tools-fab {
+  position: fixed;
+  right: 16px;
+  bottom: 24px;
+  /* Above stage canvas, LoadingView, and product modals while tools are on. */
+  z-index: 200;
+  width: 56px;
+  height: 56px;
+  padding: 0;
+  border-radius: 18px;
+  background: #152038;
+  color: #9fe7b5;
+  box-shadow: 0 4px 0 #070b14;
+  font-size: 11px;
+  font-weight: 900;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  touch-action: none;
+  user-select: none;
+  cursor: grab;
+}
+.tools-fab:hover:not(:disabled) {
+  transform: scale(1.06);
+  filter: brightness(1.06);
+}
+.tools-fab:active:not(:disabled),
+.tools-fab.is-dragging {
+  cursor: grabbing;
+  transform: scale(0.98);
+  box-shadow: 0 2px 0 #070b14;
+}
+.tools-fab.is-open {
+  color: #fff;
+  background: var(--brand, #22c55e);
+  box-shadow: 0 4px 0 var(--brand-d, #15803d);
+}
+.tools-fab[hidden] {
+  display: none !important;
+}
+
+.tool-panel.tool-popup {
+  position: fixed;
+  right: 16px;
+  bottom: 92px;
+  width: min(280px, calc(100vw - 24px));
+  max-height: min(70vh, 560px);
+  overflow: auto;
+  z-index: 201;
+  padding: 14px;
+  border-radius: var(--r-card, 22px);
+  background: #152038;
+  color: #e8eefc;
+  box-shadow: 0 8px 28px #00000088, 0 4px 0 #070b14;
+}
+.tool-panel.tool-popup[hidden] {
+  display: none !important;
+}
+.tool-panel .panel-heading {
+  display: grid;
+  grid-template-columns: 1fr auto auto;
+  align-items: center;
+  gap: 8px;
+}
+.tool-panel .panel-heading h2 {
+  color: #fff;
+  font-size: 16px;
+}
+.tool-panel .counter,
+.tool-panel .section-heading {
+  color: #8b9bb8;
+}
+.tool-panel .balance {
+  background: #1c2b4a;
+  box-shadow: 0 3px 0 #070b14;
+  color: #e8eefc;
+}
+.tool-panel .balance span {
+  color: #8b9bb8;
+}
+.tool-panel .log {
+  background: #0b1220;
+  height: 140px;
+}
+.tools-close {
+  width: 36px;
+  height: 36px;
+  padding: 0;
+  border-radius: 12px;
+  background: var(--hot, #ff4d6d);
+  box-shadow: 0 3px 0 var(--hot-d, #b8304b);
+  font-size: 20px;
+  line-height: 1;
+}
+
+.tool-panel button.is-active {
+  color: #0b1220;
+  background: #9fe7b5;
+  box-shadow: 0 3px 0 #3d8f5a;
+}
+
+/* Live FPS / ms overlay — QA only, created by mountDemoPerfHud. */
+.demo-perf-hud {
+  position: fixed;
+  top: 10px;
+  left: 10px;
+  z-index: 202;
+  min-width: 88px;
+  padding: 8px 10px;
+  border-radius: 12px;
+  background: #0b1220cc;
+  color: #9fe7b5;
+  box-shadow: 0 4px 0 #070b14;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  font-size: 12px;
+  line-height: 1.35;
+  pointer-events: none;
+  user-select: none;
+}
+.demo-perf-hud[hidden] {
+  display: none !important;
+}
+.demo-perf-hud .demo-perf-row {
+  display: flex;
+  justify-content: space-between;
+  gap: 12px;
+}
+.demo-perf-hud .demo-perf-row span {
+  color: #8b9bb8;
+}
+.demo-perf-hud .demo-perf-row strong {
+  color: #9fe7b5;
+  font-variant-numeric: tabular-nums;
+}
+
+.tool-panel .tier-status {
+  margin: 0 0 8px;
+  padding: 8px 10px;
+  border-radius: 12px;
+  background: #0b1220;
+  color: #9fe7b5;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  font-size: 12px;
+  line-height: 1.4;
+}
+.tool-panel .tier-status span {
+  color: #8b9bb8;
+}
+.tool-panel .tier-grid {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 8px;
+}
+.tool-panel .tier-grid button {
+  font-size: 11px;
+  text-transform: lowercase;
+}
+
+/* Collapsible sections — click summary / chevron to collapse large tool groups. */
+.tool-panel .tool-section {
+  margin: 0 0 10px;
+  border: 0;
+}
+.tool-panel .tool-section-toggle {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  list-style: none;
+  cursor: pointer;
+  user-select: none;
+  padding: 4px 0;
+}
+.tool-panel .tool-section-toggle::-webkit-details-marker {
+  display: none;
+}
+.tool-panel .tool-section-toggle .section-heading {
+  margin: 0;
+  flex: 1;
+  font-size: 12px;
+  font-weight: 800;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+}
+.tool-panel .tool-section-chevron {
+  flex: 0 0 auto;
+  width: 22px;
+  height: 22px;
+  border-radius: 8px;
+  background: #1c2b4a;
+  box-shadow: 0 2px 0 #070b14;
+  position: relative;
+  color: #9fe7b5;
+  font-size: 16px;
+  font-weight: 900;
+  line-height: 22px;
+  text-align: center;
+}
+.tool-panel .tool-section-chevron::before {
+  content: '+';
+}
+.tool-panel .tool-section[open] > .tool-section-toggle .tool-section-chevron::before {
+  content: '−';
+}
+.tool-panel .tool-section-body {
+  padding-top: 6px;
+}
+.tool-panel .demo-tools-extra {
+  display: flex;
+  flex-direction: column;
+  gap: 0;
+}
+
+/* Override cream `.factory-page button` so QA chrome stays navy (not brand green). */
+.tool-panel button {
+  width: 100%;
+  min-height: 40px;
+  margin-top: 8px;
+  border: 0;
+  border-radius: 12px;
+  background: #1c2b4a;
+  color: #e8eefc;
+  font-weight: 700;
+  box-shadow: 0 3px 0 #070b14;
+}
+.tool-panel .tools-close,
+.tool-panel .anim-group-toggle,
+.tool-panel .tool-param-group-toggle {
+  width: auto;
+  min-height: 0;
+  margin-top: 0;
+}
+.tool-panel .tier-grid button,
+.tool-panel .button-grid button {
+  margin-top: 0;
+}
+
+/* Parameter groups — Volute card-anim layout (label above, range + value, select).
+   Classes: .anim-group / .anim-field / .anim-row (aliases .tool-param-*). */
+.tool-panel .anim-group,
+.tool-panel .tool-param-group {
+  margin: 10px 0 4px;
+  padding: 8px 10px 6px;
+  border-radius: 12px;
+  background: rgba(11, 18, 32, 0.55);
+}
+.tool-panel .anim-group-head,
+.tool-panel .tool-param-group-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  margin: 0 0 6px;
+}
+.tool-panel .anim-group-title,
+.tool-panel .tool-param-group-title {
+  margin: 0;
+  font-size: 11px;
+  font-weight: 700;
+  letter-spacing: 0.05em;
+  text-transform: uppercase;
+  color: #9fe7b5;
+}
+.tool-panel .anim-group-toggle,
+.tool-panel .tool-param-group-toggle {
+  width: 28px;
+  min-width: 28px;
+  min-height: 28px;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  border-radius: 8px;
+  background: #152238;
+  color: #9fe7b5;
+  font-size: 14px;
+  font-weight: 700;
+  line-height: 1;
+  cursor: pointer;
+  box-shadow: none;
+}
+.tool-panel .anim-group-toggle:hover,
+.tool-panel .tool-param-group-toggle:hover {
+  background: #1c2b4a;
+}
+.tool-panel .anim-group.is-collapsed .anim-group-body,
+.tool-panel .tool-param-group.is-collapsed .tool-param-group-body,
+.tool-panel .tool-param-group.is-collapsed .anim-group-body {
+  display: none;
+}
+.tool-panel .anim-group-body,
+.tool-panel .tool-param-group-body {
+  margin: 0;
+}
+.tool-panel .anim-field,
+.tool-panel .tool-param-field {
+  margin: 8px 0;
+}
+.tool-panel .anim-field label,
+.tool-panel .tool-param-field label {
+  display: block;
+  color: #8b9bb8;
+  font-size: 11px;
+  margin-bottom: 2px;
+}
+.tool-panel .anim-row,
+.tool-panel .tool-param-row {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+}
+.tool-panel .anim-row input[type='range'],
+.tool-panel .tool-param-row input[type='range'] {
+  flex: 1;
+  min-width: 0;
+}
+.tool-panel .anim-row .val,
+.tool-panel .tool-param-row .val {
+  min-width: 36px;
+  text-align: right;
+  font-variant-numeric: tabular-nums;
+  color: #9fe7b5;
+}
+.tool-panel select {
+  width: 100%;
+  min-height: 36px;
+  border: 0;
+  border-radius: 10px;
+  background: #0b1220;
+  color: #e8eefc;
+  padding: 0 8px;
+}
+.tool-panel .btn-row {
+  display: flex;
+  gap: 8px;
+  margin-top: 8px;
+}
+.tool-panel .btn-row button {
+  flex: 1;
+  margin-top: 0;
+}
+.tool-panel .copy-hint {
+  margin: 6px 0 0;
+  font-size: 11px;
+  color: #8b9bb8;
+  min-height: 16px;
+}