@quybt93/pcgf 0.0.1

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

@@ -0,0 +1,305 @@
+/**
+ * Optional demo / QA Test tools shell — not part of Boot→Home→Game product flow.
+ * Enable/disable without touching scene lifecycle.
+ *
+ * @see skills/tool-demo-qa/SKILL.md
+ */
+
+export const DEMO_TOOLS_STORAGE_KEY = 'pcgf.demo.toolsEnabled';
+export const DEMO_TOOLS_FAB_POS_KEY = 'pcgf.demo.toolsFab';
+export const DEMO_TOOLS_QUERY = 'tools';
+
+export type ResolveDemoToolsEnabledOptions = {
+  /** Hard override (wins over URL / storage). */
+  enabled?: boolean;
+  /** Used when URL and storage are unset. Demo default: true. */
+  defaultEnabled?: boolean;
+  search?: string;
+  storage?: Pick<Storage, 'getItem' | 'setItem'> | null;
+};
+
+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;
+}
+
+/**
+ * Resolve whether Test tools UI should mount.
+ * Priority: explicit `enabled` → `?tools=` → localStorage → `defaultEnabled`.
+ */
+export function resolveDemoToolsEnabled(options: ResolveDemoToolsEnabledOptions = {}): boolean {
+  if (typeof options.enabled === 'boolean') return options.enabled;
+
+  const search =
+    options.search ??
+    (typeof window !== 'undefined' ? window.location.search : '');
+  const params = new URLSearchParams(search.startsWith('?') ? search : `?${search}`);
+  const fromQuery = parseBoolFlag(params.get(DEMO_TOOLS_QUERY));
+  if (fromQuery != null) return fromQuery;
+
+  const storage =
+    options.storage === undefined
+      ? typeof localStorage !== 'undefined'
+        ? localStorage
+        : null
+      : options.storage;
+  if (storage) {
+    try {
+      const fromStore = parseBoolFlag(storage.getItem(DEMO_TOOLS_STORAGE_KEY));
+      if (fromStore != null) return fromStore;
+    } catch {
+      /* ignore */
+    }
+  }
+
+  return options.defaultEnabled ?? true;
+}
+
+/** Persist preference (does not remount UI — call `applyDemoToolsEnabled` after). */
+export function persistDemoToolsEnabled(
+  enabled: boolean,
+  storage: Pick<Storage, 'setItem'> | null = typeof localStorage !== 'undefined' ? localStorage : null,
+): void {
+  if (!storage) return;
+  try {
+    storage.setItem(DEMO_TOOLS_STORAGE_KEY, enabled ? '1' : '0');
+  } catch {
+    /* ignore */
+  }
+}
+
+/**
+ * Toggle body flag + hide/show FAB/panel. Safe when nodes are missing.
+ * Does not bind drag/open — call `bindDemoToolsFab` when enabling.
+ */
+export function applyDemoToolsEnabled(enabled: boolean, doc: Document = document): void {
+  const root = doc.body;
+  root.classList.toggle('demo-tools-off', !enabled);
+  root.dataset.demoTools = enabled ? 'on' : 'off';
+
+  const fab = doc.querySelector<HTMLElement>('#tools-fab');
+  const panel = doc.querySelector<HTMLElement>('#tool-panel');
+  if (!enabled) {
+    fab?.setAttribute('hidden', '');
+    panel?.setAttribute('hidden', '');
+    fab?.classList.remove('is-open');
+    fab?.setAttribute('aria-expanded', 'false');
+  } else {
+    fab?.removeAttribute('hidden');
+    // Panel stays closed until the user opens it.
+    panel?.setAttribute('hidden', '');
+  }
+}
+
+export type BindDemoToolsFabOptions = {
+  fab?: HTMLButtonElement | null;
+  panel?: HTMLElement | null;
+  closeButton?: HTMLButtonElement | null;
+  positionStorageKey?: string;
+  dragThresholdPx?: number;
+};
+
+export type MountDemoToolsOptions = ResolveDemoToolsEnabledOptions &
+  BindDemoToolsFabOptions & {
+    /** Called whenever tools fully enable/disable (official build off, URL, runtime). */
+    onEnabledChange?: (enabled: boolean) => void;
+  };
+
+export type DemoToolsFabHandle = {
+  setOpen: (open: boolean) => void;
+  isOpen: () => boolean;
+  dispose: () => void;
+};
+
+/**
+ * Draggable FAB + popup shell. No-op when fab/panel missing (tools off / stripped HTML).
+ */
+export function bindDemoToolsFab(options: BindDemoToolsFabOptions = {}): DemoToolsFabHandle | null {
+  const doc = typeof document !== 'undefined' ? document : null;
+  if (!doc) return null;
+
+  const fab = options.fab ?? doc.querySelector<HTMLButtonElement>('#tools-fab');
+  const panel = options.panel ?? doc.querySelector<HTMLElement>('#tool-panel');
+  const closeBtn =
+    options.closeButton ?? doc.querySelector<HTMLButtonElement>('#tools-close');
+  if (!fab || !panel) return null;
+
+  const STORAGE_KEY = options.positionStorageKey ?? DEMO_TOOLS_FAB_POS_KEY;
+  const DRAG_THRESHOLD = options.dragThresholdPx ?? 6;
+
+  const clamp = (n: number, min: number, max: number) => Math.min(max, Math.max(min, n));
+
+  const placeFab = (left: number, top: number): void => {
+    const maxL = Math.max(8, window.innerWidth - fab.offsetWidth - 8);
+    const maxT = Math.max(8, window.innerHeight - fab.offsetHeight - 8);
+    const x = clamp(left, 8, maxL);
+    const y = clamp(top, 8, maxT);
+    fab.style.left = `${x}px`;
+    fab.style.top = `${y}px`;
+    fab.style.right = 'auto';
+    fab.style.bottom = 'auto';
+    try {
+      localStorage.setItem(STORAGE_KEY, JSON.stringify({ left: x, top: y }));
+    } catch {
+      /* ignore */
+    }
+  };
+
+  const placePanelNearFab = (): void => {
+    const fr = fab.getBoundingClientRect();
+    const pw = panel.offsetWidth || 280;
+    const ph = panel.offsetHeight || 360;
+    let left = fr.left + fr.width - pw;
+    let top = fr.top - ph - 12;
+    if (top < 8) top = fr.bottom + 12;
+    left = clamp(left, 8, Math.max(8, window.innerWidth - pw - 8));
+    top = clamp(top, 8, Math.max(8, window.innerHeight - ph - 8));
+    panel.style.left = `${left}px`;
+    panel.style.top = `${top}px`;
+    panel.style.right = 'auto';
+    panel.style.bottom = 'auto';
+  };
+
+  const setOpen = (open: boolean): void => {
+    if (fab.hasAttribute('hidden')) return;
+    panel.hidden = !open;
+    fab.classList.toggle('is-open', open);
+    fab.setAttribute('aria-expanded', open ? 'true' : 'false');
+    if (open) placePanelNearFab();
+  };
+
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    if (raw) {
+      const saved = JSON.parse(raw) as { left?: number; top?: number };
+      if (typeof saved.left === 'number' && typeof saved.top === 'number') {
+        placeFab(saved.left, saved.top);
+      }
+    }
+  } catch {
+    /* ignore */
+  }
+
+  let dragging = false;
+  let moved = false;
+  let startX = 0;
+  let startY = 0;
+  let originL = 0;
+  let originT = 0;
+  let pointerId = -1;
+
+  const onPointerDown = (event: PointerEvent): void => {
+    if (event.button !== 0) return;
+    dragging = true;
+    moved = false;
+    pointerId = event.pointerId;
+    fab.setPointerCapture(pointerId);
+    const rect = fab.getBoundingClientRect();
+    startX = event.clientX;
+    startY = event.clientY;
+    originL = rect.left;
+    originT = rect.top;
+    fab.classList.add('is-dragging');
+  };
+
+  const onPointerMove = (event: PointerEvent): void => {
+    if (!dragging || event.pointerId !== pointerId) return;
+    const dx = event.clientX - startX;
+    const dy = event.clientY - startY;
+    if (!moved && Math.hypot(dx, dy) < DRAG_THRESHOLD) return;
+    moved = true;
+    placeFab(originL + dx, originT + dy);
+    if (!panel.hidden) placePanelNearFab();
+  };
+
+  const endDrag = (event: PointerEvent): void => {
+    if (!dragging || event.pointerId !== pointerId) return;
+    dragging = false;
+    fab.classList.remove('is-dragging');
+    try {
+      fab.releasePointerCapture(pointerId);
+    } catch {
+      /* ignore */
+    }
+    pointerId = -1;
+    if (!moved) setOpen(panel.hidden);
+  };
+
+  const onKeyDown = (event: KeyboardEvent): void => {
+    if (event.key === 'Escape' && !panel.hidden) setOpen(false);
+  };
+
+  const onResize = (): void => {
+    const rect = fab.getBoundingClientRect();
+    placeFab(rect.left, rect.top);
+    if (!panel.hidden) placePanelNearFab();
+  };
+
+  const onCloseClick = (): void => setOpen(false);
+
+  fab.addEventListener('pointerdown', onPointerDown);
+  fab.addEventListener('pointermove', onPointerMove);
+  fab.addEventListener('pointerup', endDrag);
+  fab.addEventListener('pointercancel', endDrag);
+  closeBtn?.addEventListener('click', onCloseClick);
+  doc.addEventListener('keydown', onKeyDown);
+  window.addEventListener('resize', onResize);
+
+  return {
+    setOpen,
+    isOpen: () => !panel.hidden,
+    dispose: () => {
+      fab.removeEventListener('pointerdown', onPointerDown);
+      fab.removeEventListener('pointermove', onPointerMove);
+      fab.removeEventListener('pointerup', endDrag);
+      fab.removeEventListener('pointercancel', endDrag);
+      closeBtn?.removeEventListener('click', onCloseClick);
+      doc.removeEventListener('keydown', onKeyDown);
+      window.removeEventListener('resize', onResize);
+      setOpen(false);
+    },
+  };
+}
+
+/**
+ * One-shot: resolve flag → apply body class → bind FAB when on.
+ */
+export function mountDemoTools(options: MountDemoToolsOptions = {}): {
+  enabled: boolean;
+  fab: DemoToolsFabHandle | null;
+  setEnabled: (enabled: boolean) => void;
+} {
+  let fabHandle: DemoToolsFabHandle | null = null;
+  let enabled = resolveDemoToolsEnabled(options);
+
+  const setEnabled = (next: boolean): void => {
+    enabled = next;
+    persistDemoToolsEnabled(next);
+    applyDemoToolsEnabled(next);
+    if (!next) {
+      fabHandle?.dispose();
+      fabHandle = null;
+      options.onEnabledChange?.(false);
+      return;
+    }
+    if (!fabHandle) fabHandle = bindDemoToolsFab(options);
+    options.onEnabledChange?.(true);
+  };
+
+  applyDemoToolsEnabled(enabled);
+  if (enabled) fabHandle = bindDemoToolsFab(options);
+  options.onEnabledChange?.(enabled);
+
+  return {
+    get enabled() {
+      return enabled;
+    },
+    get fab() {
+      return fabHandle;
+    },
+    setEnabled,
+  };
+}

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

@@ -0,0 +1,7 @@
+export * from './demo-tools';
+export * from './demo-perf';
+export * from './demo-device-tier';
+export * from './tool-sections';
+export * from './tool-param-fields';
+export * from './tool-shell';
+export * from './init-demo-qa-tools';

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

@@ -0,0 +1,101 @@
+/**
+ * One-shot QA Test tools: shell (incl. potato/low/mid/high) + FAB + Perf HUD + tier session.
+ *
+ * @see skills/tool-demo-qa/SKILL.md
+ */
+
+import {
+  AdaptiveLoadingManager,
+  DeviceTierSession,
+  type DeviceTierState,
+} from '../adaptive-loading';
+import { bindDemoDeviceTier } from './demo-device-tier';
+import {
+  mountDemoPerfHud,
+  syncDemoPerfToggleButton,
+  type DemoPerfHudHandle,
+  type PhaserLoopLike,
+} from './demo-perf';
+import { mountDemoTools, type MountDemoToolsOptions } from './demo-tools';
+import { ensureDemoToolsShell } from './tool-shell';
+
+export type InitDemoQaToolsOptions = MountDemoToolsOptions & {
+  /** Phaser game loop accessor for FPS / ms. */
+  getLoop?: () => PhaserLoopLike | null | undefined;
+  /** Called when effective device tier changes (auto or forced). */
+  onTierChange?: (state: DeviceTierState) => void;
+  /** When true (default), create AdaptiveLoadingManager bound to effective profile. */
+  createAdaptiveLoading?: boolean;
+};
+
+export type DemoQaToolsHandle = {
+  tools: ReturnType<typeof mountDemoTools>;
+  perfHud: DemoPerfHudHandle;
+  deviceTierSession: DeviceTierSession;
+  adaptiveLoading: AdaptiveLoadingManager | null;
+  dispose: () => void;
+};
+
+/**
+ * Mounts Test tools with required Device tier force buttons and Perf HUD gate.
+ * Call after `document.body` exists (and after Phaser.Game if `getLoop` is used).
+ */
+export function initDemoQaTools(options: InitDemoQaToolsOptions = {}): DemoQaToolsHandle {
+  ensureDemoToolsShell();
+
+  const deviceTierSession = DeviceTierSession.create();
+  const createAdaptive = options.createAdaptiveLoading !== false;
+  const adaptiveLoading = createAdaptive
+    ? new AdaptiveLoadingManager(deviceTierSession.getEffectiveProfile())
+    : null;
+
+  let perfHud!: DemoPerfHudHandle;
+
+  const tools = mountDemoTools({
+    ...options,
+    onEnabledChange: (enabled) => {
+      options.onEnabledChange?.(enabled);
+      perfHud?.setToolsAllowed(enabled);
+    },
+  });
+
+  perfHud = mountDemoPerfHud({
+    getLoop: options.getLoop,
+    getTierLabel: () => deviceTierSession.getEffectiveProfile().tier,
+    toolsAllowed: tools.enabled,
+  });
+  perfHud.setToolsAllowed(tools.enabled);
+  perfHud.setTierLabel(deviceTierSession.getEffectiveProfile().tier);
+
+  const perfHudBtn = document.querySelector<HTMLButtonElement>('#btn-perf-hud');
+  syncDemoPerfToggleButton(perfHudBtn, perfHud.isEnabled());
+  const onPerfClick = (): void => {
+    if (!tools.enabled) return;
+    const next = !perfHud.isEnabled();
+    perfHud.setEnabled(next);
+    syncDemoPerfToggleButton(perfHudBtn, next);
+  };
+  perfHudBtn?.addEventListener('click', onPerfClick);
+
+  const tierBind = bindDemoDeviceTier({
+    session: deviceTierSession,
+    onChange: (state) => {
+      adaptiveLoading?.setProfile(state.effective);
+      perfHud.setTierLabel(state.effective.tier);
+      options.onTierChange?.(state);
+    },
+  });
+
+  return {
+    tools,
+    perfHud,
+    deviceTierSession,
+    adaptiveLoading,
+    dispose: () => {
+      perfHudBtn?.removeEventListener('click', onPerfClick);
+      tierBind.dispose();
+      perfHud.dispose();
+      tools.setEnabled(false);
+    },
+  };
+}

package/plugins/phaser-casual-game-factory/templates/demo-tools/tool-param-fields.ts

@@ -0,0 +1,214 @@
+/**
+ * Parameter groups inside Test tools — label-above + select / range+value.
+ * Reference layout: solitaire/volute card-anim tools (MOVE — BÀN CHƠI, …).
+ *
+ * @see skills/tool-demo-qa/SKILL.md
+ */
+
+export const DEMO_TOOLS_PARAM_GROUPS_KEY = 'pcgf.demo.toolParamGroups';
+
+export type ToolSelectField = {
+  type: 'select';
+  key: string;
+  label: string;
+  options: string[];
+  /** Display labels for option values (fallback = value). */
+  labels?: Record<string, string>;
+};
+
+export type ToolRangeField = {
+  type: 'range';
+  key: string;
+  label: string;
+  min: number;
+  max: number;
+  step: number;
+};
+
+export type ToolParamField = ToolSelectField | ToolRangeField;
+
+export type ToolParamGroup = {
+  title: string;
+  fields: ToolParamField[];
+  /** When true (or omitted and title is “large”), start collapsed if storage unset. */
+  defaultCollapsed?: boolean;
+};
+
+export type MountToolParamGroupsOptions = {
+  host: HTMLElement;
+  groups: ToolParamGroup[];
+  /** Current config map keyed by field.key. */
+  getValues: () => Record<string, string | number>;
+  /** Called when a field changes. */
+  onChange: (patch: Record<string, string | number>) => void;
+  /** Persist collapsed groups (default localStorage key DEMO_TOOLS_PARAM_GROUPS_KEY). */
+  storageKey?: string;
+  storage?: Pick<Storage, 'getItem' | 'setItem'> | null;
+  /** Clear host and rebuild (default false = no-op if host already has children). */
+  rebuild?: boolean;
+};
+
+function readCollapsed(
+  storage: Pick<Storage, 'getItem'> | null,
+  key: string,
+): Record<string, boolean> {
+  if (!storage) return {};
+  try {
+    const raw = storage.getItem(key);
+    if (!raw) return {};
+    const parsed = JSON.parse(raw) as unknown;
+    if (!parsed || typeof parsed !== 'object') return {};
+    const out: Record<string, boolean> = {};
+    for (const [k, v] of Object.entries(parsed as Record<string, unknown>)) {
+      if (typeof v === 'boolean') out[k] = v;
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+function writeCollapsed(
+  map: Record<string, boolean>,
+  storage: Pick<Storage, 'setItem'> | null,
+  key: string,
+): void {
+  if (!storage) return;
+  try {
+    storage.setItem(key, JSON.stringify(map));
+  } catch {
+    /* ignore */
+  }
+}
+
+function formatRangeValue(value: number, step: number): string {
+  return step < 1 ? Number(value).toFixed(2) : String(value);
+}
+
+/** Build one label-above field (select full-width, or range + right value). */
+export function appendToolParamField(
+  host: HTMLElement,
+  field: ToolParamField,
+  values: Record<string, string | number>,
+  onChange: (patch: Record<string, string | number>) => void,
+): HTMLElement {
+  const wrap = host.ownerDocument.createElement('div');
+  wrap.className = 'anim-field tool-param-field';
+
+  if (field.type === 'select') {
+    const current = String(values[field.key] ?? '');
+    const opts = field.options
+      .map((v) => {
+        const label = field.labels?.[v] ?? v;
+        const sel = current === v ? ' selected' : '';
+        return `<option value="${v}"${sel}>${label}</option>`;
+      })
+      .join('');
+    wrap.innerHTML = `<label>${field.label}</label><select data-key="${field.key}">${opts}</select>`;
+    host.appendChild(wrap);
+    const select = wrap.querySelector('select');
+    select?.addEventListener('change', () => {
+      if (!select) return;
+      onChange({ [field.key]: select.value });
+    });
+    return wrap;
+  }
+
+  const current = Number(values[field.key] ?? field.min);
+  wrap.innerHTML = `
+    <label>${field.label}</label>
+    <div class="anim-row tool-param-row">
+      <input type="range" min="${field.min}" max="${field.max}" step="${field.step}" data-key="${field.key}" value="${current}" />
+      <span class="val" data-val="${field.key}">${formatRangeValue(current, field.step)}</span>
+    </div>`;
+  host.appendChild(wrap);
+  const input = wrap.querySelector('input');
+  const val = wrap.querySelector<HTMLElement>('[data-val]');
+  input?.addEventListener('input', () => {
+    if (!input) return;
+    const next = Number(input.value);
+    onChange({ [field.key]: next });
+    if (val) val.textContent = formatRangeValue(next, field.step);
+  });
+  return wrap;
+}
+
+/**
+ * Mount collapsible parameter groups (Volute card-anim layout).
+ * Classes: `.anim-group` / `.anim-field` / `.anim-row` (+ aliases `.tool-param-*`).
+ */
+export function mountToolParamGroups(options: MountToolParamGroupsOptions): {
+  rebuild: () => void;
+} {
+  const storage =
+    options.storage === undefined
+      ? typeof localStorage !== 'undefined'
+        ? localStorage
+        : null
+      : options.storage;
+  const storageKey = options.storageKey ?? DEMO_TOOLS_PARAM_GROUPS_KEY;
+
+  const render = (): void => {
+    const { host, groups, getValues, onChange } = options;
+    if (options.rebuild) host.replaceChildren();
+    else if (host.childElementCount > 0) return;
+
+    const values = getValues();
+    const collapsed = readCollapsed(storage, storageKey);
+
+    for (const group of groups) {
+      const box = host.ownerDocument.createElement('div');
+      box.className = 'anim-group tool-param-group';
+      const isCollapsed =
+        Object.prototype.hasOwnProperty.call(collapsed, group.title)
+          ? !!collapsed[group.title]
+          : Boolean(group.defaultCollapsed);
+      if (isCollapsed) box.classList.add('is-collapsed');
+
+      const head = host.ownerDocument.createElement('div');
+      head.className = 'anim-group-head tool-param-group-head';
+
+      const title = host.ownerDocument.createElement('div');
+      title.className = 'anim-group-title tool-param-group-title';
+      title.textContent = group.title;
+
+      const toggle = host.ownerDocument.createElement('button');
+      toggle.type = 'button';
+      toggle.className = 'anim-group-toggle tool-param-group-toggle';
+      toggle.setAttribute('aria-expanded', isCollapsed ? 'false' : 'true');
+      toggle.setAttribute('aria-label', isCollapsed ? `Expand ${group.title}` : `Collapse ${group.title}`);
+      toggle.textContent = isCollapsed ? '+' : '−';
+
+      head.append(title, toggle);
+
+      const body = host.ownerDocument.createElement('div');
+      body.className = 'anim-group-body tool-param-group-body';
+      for (const field of group.fields) {
+        appendToolParamField(body, field, values, onChange);
+      }
+
+      toggle.addEventListener('click', () => {
+        const next = !box.classList.contains('is-collapsed');
+        box.classList.toggle('is-collapsed', next);
+        collapsed[group.title] = next;
+        writeCollapsed(collapsed, storage, storageKey);
+        toggle.textContent = next ? '+' : '−';
+        toggle.setAttribute('aria-expanded', next ? 'false' : 'true');
+        toggle.setAttribute('aria-label', next ? `Expand ${group.title}` : `Collapse ${group.title}`);
+      });
+
+      box.append(head, body);
+      host.appendChild(box);
+    }
+  };
+
+  render();
+
+  return {
+    rebuild: () => {
+      options.rebuild = true;
+      render();
+      options.rebuild = false;
+    },
+  };
+}