@quybt93/pcgf 0.0.1

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

@@ -0,0 +1,238 @@
+/**
+ * Collapsible Test-tools sections + helpers for adding game-specific tools.
+ *
+ * @see skills/tool-demo-qa/SKILL.md
+ */
+
+export const DEMO_TOOLS_SECTION_STORAGE_KEY = 'pcgf.demo.toolsSections';
+
+/** Sections that default collapsed when storage has no preference (large / noisy). */
+export const DEMO_TOOLS_LARGE_SECTION_IDS = new Set([
+  'balances',
+  'transaction-log',
+  'equipment-seed',
+  'save-data',
+]);
+
+export type ToolSectionHtmlOptions = {
+  id: string;
+  title: string;
+  bodyHtml: string;
+  /** When unset: open unless id is in DEMO_TOOLS_LARGE_SECTION_IDS. */
+  defaultOpen?: boolean;
+};
+
+function slugifySectionId(raw: string): string {
+  return raw
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '') || 'section';
+}
+
+function readSectionPrefs(
+  storage: Pick<Storage, 'getItem'> | null,
+): Record<string, boolean> {
+  if (!storage) return {};
+  try {
+    const raw = storage.getItem(DEMO_TOOLS_SECTION_STORAGE_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 writeSectionPrefs(
+  prefs: Record<string, boolean>,
+  storage: Pick<Storage, 'setItem'> | null,
+): void {
+  if (!storage) return;
+  try {
+    storage.setItem(DEMO_TOOLS_SECTION_STORAGE_KEY, JSON.stringify(prefs));
+  } catch {
+    /* ignore */
+  }
+}
+
+function resolveDefaultOpen(id: string, defaultOpen?: boolean): boolean {
+  if (typeof defaultOpen === 'boolean') return defaultOpen;
+  return !DEMO_TOOLS_LARGE_SECTION_IDS.has(id);
+}
+
+/** Build one collapsible section (details/summary). */
+export function toolSectionHtml(options: ToolSectionHtmlOptions): string {
+  const id = slugifySectionId(options.id);
+  const open = resolveDefaultOpen(id, options.defaultOpen);
+  return `
+<details class="tool-section" data-tool-section="${id}"${open ? ' open' : ''}>
+  <summary class="tool-section-toggle">
+    <span class="section-heading">${options.title}</span>
+    <span class="tool-section-chevron" aria-hidden="true"></span>
+  </summary>
+  <div class="tool-section-body">
+    ${options.bodyHtml}
+  </div>
+</details>
+`.trim();
+}
+
+export type AppendToolSectionOptions = ToolSectionHtmlOptions & {
+  /** Defaults to `#demo-tools-extra`, then `#tool-panel`. */
+  parent?: HTMLElement | null;
+  doc?: Document;
+};
+
+/**
+ * Append a game-specific tool section (buttons live in bodyHtml; wire handlers in app code).
+ */
+export function appendToolSection(options: AppendToolSectionOptions): HTMLElement | null {
+  const doc = options.doc ?? (typeof document !== 'undefined' ? document : null);
+  if (!doc) return null;
+
+  const parent =
+    options.parent ??
+    doc.querySelector<HTMLElement>('#demo-tools-extra') ??
+    doc.querySelector<HTMLElement>('#tool-panel');
+  if (!parent) return null;
+
+  parent.insertAdjacentHTML('beforeend', toolSectionHtml(options));
+  const id = slugifySectionId(options.id);
+  return parent.querySelector<HTMLElement>(`[data-tool-section="${id}"]`);
+}
+
+/**
+ * Upgrade flat `.section-heading` + siblings into collapsible `.tool-section` blocks.
+ * Idempotent — skips headings already inside a `.tool-section`.
+ */
+export function wrapFlatToolSections(panel: HTMLElement): void {
+  const headings = Array.from(panel.querySelectorAll<HTMLElement>('.section-heading'));
+  for (const heading of headings) {
+    if (heading.closest('.tool-section')) continue;
+
+    const title = (heading.textContent ?? '').trim() || 'Section';
+    const id = slugifySectionId(title);
+    const nodes: Node[] = [];
+    let sibling = heading.nextSibling;
+    while (sibling) {
+      const next = sibling.nextSibling;
+      if (sibling instanceof HTMLElement) {
+        if (
+          sibling.classList.contains('section-heading') ||
+          sibling.classList.contains('tool-section') ||
+          sibling.classList.contains('panel-heading')
+        ) {
+          break;
+        }
+      }
+      nodes.push(sibling);
+      sibling = next;
+    }
+
+    const details = panel.ownerDocument.createElement('details');
+    details.className = 'tool-section';
+    details.dataset.toolSection = id;
+    if (resolveDefaultOpen(id)) details.open = true;
+
+    const summary = panel.ownerDocument.createElement('summary');
+    summary.className = 'tool-section-toggle';
+    const titleEl = panel.ownerDocument.createElement('span');
+    titleEl.className = 'section-heading';
+    titleEl.textContent = title;
+    const chevron = panel.ownerDocument.createElement('span');
+    chevron.className = 'tool-section-chevron';
+    chevron.setAttribute('aria-hidden', 'true');
+    summary.append(titleEl, chevron);
+
+    const body = panel.ownerDocument.createElement('div');
+    body.className = 'tool-section-body';
+    for (const node of nodes) body.appendChild(node);
+
+    details.append(summary, body);
+    heading.replaceWith(details);
+  }
+}
+
+export type BindDemoToolSectionsOptions = {
+  panel?: HTMLElement | null;
+  storage?: Pick<Storage, 'getItem' | 'setItem'> | null;
+  /** Wrap legacy flat headings first (default true). */
+  wrapFlat?: boolean;
+};
+
+const BOUND_FLAG = 'demoToolSectionsBound';
+
+type PanelToggleListener = (event: Event) => void;
+const panelToggleListeners = new WeakMap<HTMLElement, PanelToggleListener>();
+
+/**
+ * Apply persisted open/closed prefs and listen for toggle. Call after shell is ready.
+ * Idempotent — re-wraps new flat headings but does not double-bind listeners.
+ */
+export function bindDemoToolSections(
+  options: BindDemoToolSectionsOptions = {},
+): { dispose: () => void } | null {
+  const doc = typeof document !== 'undefined' ? document : null;
+  if (!doc) return null;
+
+  const panel = options.panel ?? doc.querySelector<HTMLElement>('#tool-panel');
+  if (!panel) return null;
+
+  if (options.wrapFlat !== false) wrapFlatToolSections(panel);
+
+  const storage =
+    options.storage === undefined
+      ? typeof localStorage !== 'undefined'
+        ? localStorage
+        : null
+      : options.storage;
+
+  const prefs = readSectionPrefs(storage);
+  const sections = Array.from(
+    panel.querySelectorAll<HTMLDetailsElement>('details.tool-section[data-tool-section]'),
+  );
+
+  for (const section of sections) {
+    const id = section.dataset.toolSection;
+    if (!id) continue;
+    if (Object.prototype.hasOwnProperty.call(prefs, id)) {
+      section.open = prefs[id]!;
+    }
+  }
+
+  const dispose = (): void => {
+    const existing = panelToggleListeners.get(panel);
+    if (existing) {
+      panel.removeEventListener('toggle', existing, true);
+      panelToggleListeners.delete(panel);
+    }
+    panel.dataset[BOUND_FLAG] = '0';
+  };
+
+  if (panel.dataset[BOUND_FLAG] === '1' && panelToggleListeners.has(panel)) {
+    return { dispose };
+  }
+
+  const onToggle: PanelToggleListener = (event: Event): void => {
+    const target = event.target;
+    if (!(target instanceof HTMLDetailsElement)) return;
+    if (!target.classList.contains('tool-section')) return;
+    const id = target.dataset.toolSection;
+    if (!id) return;
+    const next = readSectionPrefs(storage);
+    next[id] = target.open;
+    writeSectionPrefs(next, storage);
+  };
+
+  panel.addEventListener('toggle', onToggle, true);
+  panelToggleListeners.set(panel, onToggle);
+  panel.dataset[BOUND_FLAG] = '1';
+
+  return { dispose };
+}

package/plugins/phaser-casual-game-factory/templates/demo-tools/tool-shell.html

@@ -0,0 +1,57 @@
+<!--
+  Canonical Test tools shell (skill tool-demo-qa).
+  Prefer `ensureDemoToolsShell()` / `initDemoQaTools()` from tool-shell.ts — they inject this
+  and guarantee Device tier force buttons (auto/potato/low/mid/high) + collapsible sections.
+  Paste into index.html outside .stage-screen if you wire HTML by hand.
+-->
+<button
+  type="button"
+  id="tools-fab"
+  class="tools-fab"
+  data-testid="tools-fab"
+  aria-expanded="false"
+  aria-controls="tool-panel"
+  title="Test tools (drag to move)"
+>
+  Tools
+</button>
+
+<aside id="tool-panel" class="tool-panel tool-popup" data-testid="tool-panel" hidden>
+  <div class="panel-heading">
+    <h2>Test tools</h2>
+    <button type="button" id="tools-close" class="tools-close" aria-label="Close tools">×</button>
+  </div>
+
+  <details class="tool-section" data-tool-section="performance" open>
+    <summary class="tool-section-toggle">
+      <span class="section-heading">Performance</span>
+      <span class="tool-section-chevron" aria-hidden="true"></span>
+    </summary>
+    <div class="tool-section-body">
+      <div class="button-grid">
+        <button type="button" id="btn-perf-hud" aria-pressed="false" data-testid="btn-perf-hud">
+          Perf HUD: Off
+        </button>
+      </div>
+    </div>
+  </details>
+
+  <details class="tool-section" data-tool-section="device-tier" open>
+    <summary class="tool-section-toggle">
+      <span class="section-heading">Device tier</span>
+      <span class="tool-section-chevron" aria-hidden="true"></span>
+    </summary>
+    <div class="tool-section-body">
+      <p id="device-tier-status" class="tier-status" data-testid="device-tier-status">Tier: …</p>
+      <div class="tier-grid" data-testid="device-tier-grid">
+        <button type="button" data-tier="auto" aria-pressed="true">auto</button>
+        <button type="button" data-tier="potato" aria-pressed="false">potato</button>
+        <button type="button" data-tier="low" aria-pressed="false">low</button>
+        <button type="button" data-tier="mid" aria-pressed="false">mid</button>
+        <button type="button" data-tier="high" aria-pressed="false">high</button>
+      </div>
+    </div>
+  </details>
+
+  <div id="demo-tools-extra" class="demo-tools-extra"></div>
+</aside>

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

@@ -0,0 +1,141 @@
+/**
+ * Canonical Test tools HTML shell — FAB + panel with Perf HUD + Device tier force.
+ * Scaffold / agents MUST paste this (or call `ensureDemoToolsShell`) so potato/low/mid/high exist.
+ *
+ * @see skills/tool-demo-qa/SKILL.md
+ */
+
+import { bindDemoToolSections, toolSectionHtml } from './tool-sections';
+
+export const DEMO_TOOLS_SHELL_HTML = `
+<button
+  type="button"
+  id="tools-fab"
+  class="tools-fab"
+  data-testid="tools-fab"
+  aria-expanded="false"
+  aria-controls="tool-panel"
+  title="Test tools (drag to move)"
+>
+  Tools
+</button>
+
+<aside id="tool-panel" class="tool-panel tool-popup" data-testid="tool-panel" hidden>
+  <div class="panel-heading">
+    <h2>Test tools</h2>
+    <span id="transaction-count" class="counter" hidden>0 tx</span>
+    <button type="button" id="tools-close" class="tools-close" aria-label="Close tools">×</button>
+  </div>
+
+  ${toolSectionHtml({
+    id: 'performance',
+    title: 'Performance',
+    bodyHtml: `
+    <div class="button-grid">
+      <button type="button" id="btn-perf-hud" aria-pressed="false" data-testid="btn-perf-hud">
+        Perf HUD: Off
+      </button>
+    </div>`,
+  })}
+
+  ${toolSectionHtml({
+    id: 'device-tier',
+    title: 'Device tier',
+    bodyHtml: `
+    <p id="device-tier-status" class="tier-status" data-testid="device-tier-status">Tier: …</p>
+    <div class="tier-grid" data-testid="device-tier-grid">
+      <button type="button" data-tier="auto" aria-pressed="true">auto</button>
+      <button type="button" data-tier="potato" aria-pressed="false">potato</button>
+      <button type="button" data-tier="low" aria-pressed="false">low</button>
+      <button type="button" data-tier="mid" aria-pressed="false">mid</button>
+      <button type="button" data-tier="high" aria-pressed="false">high</button>
+    </div>`,
+  })}
+
+  <!-- Optional game-specific seed actions (grant / XP / …) go below. -->
+  <div id="demo-tools-extra" class="demo-tools-extra"></div>
+</aside>
+`.trim();
+
+const DEVICE_TIER_SECTION_HTML = toolSectionHtml({
+  id: 'device-tier',
+  title: 'Device tier',
+  bodyHtml: `
+  <p id="device-tier-status" class="tier-status" data-testid="device-tier-status">Tier: …</p>
+  <div class="tier-grid" data-testid="device-tier-grid">
+    <button type="button" data-tier="auto" aria-pressed="true">auto</button>
+    <button type="button" data-tier="potato" aria-pressed="false">potato</button>
+    <button type="button" data-tier="low" aria-pressed="false">low</button>
+    <button type="button" data-tier="mid" aria-pressed="false">mid</button>
+    <button type="button" data-tier="high" aria-pressed="false">high</button>
+  </div>`,
+});
+
+const PERF_SECTION_HTML = toolSectionHtml({
+  id: 'performance',
+  title: 'Performance',
+  bodyHtml: `
+  <div class="button-grid">
+    <button type="button" id="btn-perf-hud" aria-pressed="false" data-testid="btn-perf-hud">
+      Perf HUD: Off
+    </button>
+  </div>`,
+});
+
+/**
+ * Ensure FAB + panel exist, and that Perf HUD + Device tier force controls are present.
+ * Safe to call on an older partial tools panel (injects missing sections).
+ * Also upgrades flat headings into collapsible sections and binds collapse prefs.
+ */
+export function ensureDemoToolsShell(doc: Document = document): {
+  fab: HTMLButtonElement | null;
+  panel: HTMLElement | null;
+} {
+  let fab = doc.querySelector<HTMLButtonElement>('#tools-fab');
+  let panel = doc.querySelector<HTMLElement>('#tool-panel');
+
+  if (!fab || !panel) {
+    doc.body.insertAdjacentHTML('beforeend', DEMO_TOOLS_SHELL_HTML);
+    fab = doc.querySelector<HTMLButtonElement>('#tools-fab');
+    panel = doc.querySelector<HTMLElement>('#tool-panel');
+  } else {
+    if (!panel.querySelector('#btn-perf-hud')) {
+      const heading = panel.querySelector('.panel-heading');
+      if (heading) {
+        heading.insertAdjacentHTML('afterend', PERF_SECTION_HTML);
+      } else {
+        panel.insertAdjacentHTML('afterbegin', PERF_SECTION_HTML);
+      }
+    }
+
+    if (!panel.querySelector('[data-tier]')) {
+      const perfSection =
+        panel.querySelector('[data-tool-section="performance"]') ??
+        panel.querySelector('#btn-perf-hud')?.closest('.tool-section, .button-grid');
+      if (perfSection) {
+        perfSection.insertAdjacentHTML('afterend', DEVICE_TIER_SECTION_HTML);
+      } else {
+        panel.insertAdjacentHTML('beforeend', DEVICE_TIER_SECTION_HTML);
+      }
+    } else if (!panel.querySelector('#device-tier-status')) {
+      const grid = panel.querySelector('[data-testid="device-tier-grid"], .tier-grid');
+      grid?.insertAdjacentHTML(
+        'beforebegin',
+        '<p id="device-tier-status" class="tier-status" data-testid="device-tier-status">Tier: …</p>',
+      );
+    }
+
+    if (!panel.querySelector('#demo-tools-extra')) {
+      panel.insertAdjacentHTML(
+        'beforeend',
+        '<div id="demo-tools-extra" class="demo-tools-extra"></div>',
+      );
+    }
+  }
+
+  if (panel) {
+    bindDemoToolSections({ panel, wrapFlat: true });
+  }
+
+  return { fab, panel };
+}

package/plugins/phaser-casual-game-factory/templates/economy/default-registry.ts

@@ -0,0 +1,14 @@
+import { OperationRegistry } from './operation-handler';
+import { ActivatePackageHandler } from './package-handler';
+import { ConvertOperationHandler, SellOperationHandler } from './exchange-handlers';
+import { GrantOperationHandler } from './grant-handler';
+import { MergeOperationHandler } from './merge-handler';
+
+export function createDefaultEconomyRegistry(): OperationRegistry {
+  return new OperationRegistry()
+    .register(new GrantOperationHandler())
+    .register(new SellOperationHandler())
+    .register(new ConvertOperationHandler())
+    .register(new MergeOperationHandler())
+    .register(new ActivatePackageHandler());
+}

package/plugins/phaser-casual-game-factory/templates/economy/economy-service.ts

@@ -0,0 +1,65 @@
+import type { Result } from '../core/types';
+import { MathRandomSource, type RandomSource } from './random';
+import { OperationRegistry } from './operation-handler';
+import type { EconomyRepository } from './repository';
+import type {
+  EconomyConfig,
+  EconomyOperationRequest,
+  EconomyService,
+  TransactionReceipt,
+} from './types';
+import { resourceRewardsFromChanges } from './state-utils';
+
+export class DefaultEconomyService implements EconomyService {
+  constructor(
+    private readonly repository: EconomyRepository,
+    private readonly config: EconomyConfig,
+    private readonly registry: OperationRegistry,
+    private readonly random: RandomSource = new MathRandomSource(),
+    private readonly now: () => number = () => Date.now(),
+  ) {}
+
+  async getBalance(resourceId: string): Promise<number> {
+    const state = await this.repository.getSnapshot();
+    return state.balances[resourceId] ?? 0;
+  }
+
+  async execute(
+    request: EconomyOperationRequest,
+  ): Promise<Result<TransactionReceipt>> {
+    if (!request.transactionId.trim()) {
+      return { ok: false, error: new Error('transactionId is required') };
+    }
+
+    try {
+      const result = await this.repository.runAtomic(
+        request.transactionId,
+        async (state) => {
+          const handler = this.registry.get(request.type);
+          const execution = handler.execute(request as any, {
+            state,
+            config: this.config,
+            random: this.random,
+            now: this.now(),
+          });
+          return {
+            state: execution.state,
+            receipt: {
+              ...execution.receipt,
+              transactionId: request.transactionId,
+              operationType: request.type,
+              metadata: request.metadata,
+              rewards: execution.receipt.rewards ?? resourceRewardsFromChanges(execution.receipt.changes),
+            },
+          };
+        },
+      );
+      return { ok: true, value: result.receipt };
+    } catch (error) {
+      return {
+        ok: false,
+        error: error instanceof Error ? error : new Error(String(error)),
+      };
+    }
+  }
+}

package/plugins/phaser-casual-game-factory/templates/economy/exchange-handlers.ts

@@ -0,0 +1,58 @@
+import type { EconomyOperationContext, EconomyOperationHandler } from './operation-handler';
+import type { EconomyOperationRequest, ExchangeConfig, TransactionChange } from './types';
+import { cloneEconomyState, applyInput, applyRewards, multiplyStacks, resolveQuantity } from './state-utils';
+
+type ExchangeRequest = Extract<
+  EconomyOperationRequest,
+  { type: 'sell' | 'convert' }
+>;
+type SellRequest = Extract<EconomyOperationRequest, { type: 'sell' }>;
+type ConvertRequest = Extract<EconomyOperationRequest, { type: 'convert' }>;
+
+function executeExchange(
+  request: ExchangeRequest,
+  context: EconomyOperationContext,
+  config: ExchangeConfig,
+  inputCapability: 'sellable' | 'convertible',
+) {
+  const quantity = request.quantity ?? 1;
+  const state = cloneEconomyState(context.state);
+  const changes: TransactionChange[] = [];
+  applyInput(
+    state,
+    context.config,
+    multiplyStacks(config.input, quantity),
+    inputCapability,
+    changes,
+  );
+  const rewards = config.output.map((reward) => ({
+    resourceId: reward.resourceId,
+    amount: resolveQuantity(reward.quantity, context.random) * quantity,
+  }));
+  applyRewards(state, context.config, rewards, changes);
+  return { state, receipt: { applied: true, changes } };
+}
+
+export class SellOperationHandler
+  implements EconomyOperationHandler<Extract<EconomyOperationRequest, { type: 'sell' }>>
+{
+  readonly type = 'sell' as const;
+
+  execute(request: SellRequest, context: EconomyOperationContext) {
+    const config = context.config.sales[request.configId];
+    if (!config) throw new Error(`Unknown sale config: ${request.configId}`);
+    return executeExchange(request, context, config, 'sellable');
+  }
+}
+
+export class ConvertOperationHandler
+  implements EconomyOperationHandler<Extract<EconomyOperationRequest, { type: 'convert' }>>
+{
+  readonly type = 'convert' as const;
+
+  execute(request: ConvertRequest, context: EconomyOperationContext) {
+    const config = context.config.conversions[request.configId];
+    if (!config) throw new Error(`Unknown conversion config: ${request.configId}`);
+    return executeExchange(request, context, config, 'convertible');
+  }
+}

package/plugins/phaser-casual-game-factory/templates/economy/grant-handler.ts

@@ -0,0 +1,58 @@
+import type { EconomyOperationContext, EconomyOperationHandler } from './operation-handler';
+import type { GrantEntry, EconomyOperationRequest, TransactionChange } from './types';
+import { weightedIndex } from './random';
+import {
+  applyRewards,
+  cloneEconomyState,
+  resolveQuantity,
+} from './state-utils';
+
+type GrantRequest = Extract<EconomyOperationRequest, { type: 'grant' }>;
+
+export class GrantOperationHandler
+  implements EconomyOperationHandler<GrantRequest>
+{
+  readonly type = 'grant' as const;
+
+  execute(request: GrantRequest, context: EconomyOperationContext) {
+    const config = context.config.grants[request.configId];
+    if (!config) throw new Error(`Unknown grant config: ${request.configId}`);
+
+    let entries: GrantEntry[];
+    if (config.mode === 'all') {
+      entries = [...config.entries];
+    } else if (config.mode === 'select') {
+      const selected = new Set(request.selectedResourceIds ?? []);
+      if (selected.size === 0) throw new Error('Select grant requires selected resources');
+      entries = config.entries.filter((entry) => selected.has(entry.resourceId));
+      if (entries.length !== selected.size) throw new Error('Selected resource is not in grant config');
+    } else {
+      const count = config.pickCount ?? 1;
+      const pool = [...config.entries];
+      entries = [];
+      for (let index = 0; index < count; index += 1) {
+        if (pool.length === 0) break;
+        const selectedIndex = weightedIndex(
+          context.random,
+          pool.map((entry) => entry.weight ?? 0),
+        );
+        entries.push(pool[selectedIndex]);
+        if (!config.allowDuplicatePicks) pool.splice(selectedIndex, 1);
+      }
+      if (entries.length !== count) throw new Error('Grant config cannot satisfy pickCount');
+    }
+
+    const rewards = entries.map((entry) => ({
+      resourceId: entry.resourceId,
+      amount: resolveQuantity(entry.quantity, context.random),
+    }));
+    const state = cloneEconomyState(context.state);
+    const changes: TransactionChange[] = [];
+    applyRewards(state, context.config, rewards, changes);
+
+    return {
+      state,
+      receipt: { applied: true, changes },
+    };
+  }
+}

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

@@ -0,0 +1,15 @@
+export * from './types';
+export * from './random';
+export * from './operation-handler';
+export * from './state-utils';
+export * from './repository';
+export * from './economy-service';
+export * from './default-registry';
+export * from './grant-handler';
+export * from './exchange-handlers';
+export * from './merge-handler';
+export * from './package-handler';
+export * from './item-utils';
+export * from './item-service';
+export * from './inventory-service';
+export * from './ui-view-models';