@quybt93/pcgf 0.0.1

package/plugins/phaser-casual-game-factory/skills/phaser-casual-game-factory/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: phaser-casual-game-factory
+description: >-
+  Build, refactor, and review Phaser casual games using a reusable scene lifecycle,
+  responsive layout, game-state architecture, UI system (MUST default
+  theme-cream-casual, feeling phaser-ui-motion, SFX phaser-ui-sfx; bitmap pack
+  super-casual when art is needed), input/audio/persistence services, safe loading
+  transitions, and QA Test tools (tool-demo-qa). Use for new Phaser casual games,
+  shared foundation work, DOM/CSS/button/modal UI, or debug/cheat/QA tools.
+  For reskinning an existing game's theme/assets/feeling/SFX, use pcgf-ui-reskin
+  instead — do not run the compare.html reskin flow on greenfield creates.
+---
+
+# Phaser Casual Game Factory
+
+Use this skill whenever the task creates or changes a Phaser casual game. Treat the current repository as the source of truth: preserve its framework and conventions, and add only the smallest reusable layer that solves the task.
+
+The plugin's reusable contracts are documented in `references/core-contracts.md` and templated in `templates/core/`. Read those files before introducing a new shared service, event, storage adapter, time helper, loading flow, layout system, or gameplay module. For blocking loading/scene transitions, also read `references/loading-view.md` and use `templates/loading-view/`, `templates/boot/play-boot-loading-view.ts`, plus `templates/phaser/loading-overlay-scene.ts`. For company Boot logo/wordmark/tips, read skill **`phaser-studio25-boot-brand`**. For reset boundaries, timezones, or local/server clock work, also read `references/time-service.md` and use `templates/time/`. For attendance/streak tracking, use `templates/daily-login/` and read `references/daily-login-service.md`. For feature gates and requirement UI, use `templates/condition/` and read `references/condition-service.md`.
+
+## First pass
+
+Before editing:
+
+1. Identify Phaser version, build tool, language, entry point, and existing scene structure.
+2. Find the game configuration, asset loading, scaling mode, input handling, and state ownership.
+3. Check whether the repository already has shared UI, audio, persistence, transition, or event utilities. Extend them instead of creating parallel systems.
+4. Run the existing checks once when practical so failures can be separated from the change.
+
+If the project is new, establish this minimum structure:
+
+```text
+src/
+  app/          # bootstrap, scene registration, global services
+  core/         # game state, events, constants, contracts
+  scenes/       # Boot, Home, Game (required)
+  systems/      # input, audio, save, level, timer, score
+  ui/           # reusable Phaser UI components and layout helpers
+  config/       # typed tuning values and environment configuration
+```
+
+## Default lifecycle
+
+Required scenes (register at game start; only Boot auto-starts):
+
+`Boot -> Home -> Game` (+ `FactoryLoadingOverlay` last as a technical Loading View, not a destination)
+
+- Follow `skills/phaser-loading-view` for every blocking transition.
+- Boot → Home brand (logo / 25 STUDIO / tips) → skill **`phaser-studio25-boot-brand`**
+  only. Rebrand there — do not swap in game splash art inside BootScene.
+- Boot wires `playBootLoadingView` + `bootToHome` (0/2000/700); brand close style defaults to **`iris`** (`BOOT_CLOSE_STYLE.iris`); opt-in **`slide-up`** when requested.
+- Home ↔ Game / Next Level: `FactoryLoadingOverlay` (`scene-transition` / `next-level`); mask hole **full → 0** on cover, **0 → full** on reveal (do not start cover from 0). While fully covered, **pause** BitmapMask for the HUD dwell; resume before reveal. Progress bar paints only on **whole-percent** changes (Δ ≥ 1%) — see `phaser-loading-view`.
+- `Home` owns navigation and **settings** (shared HTML modal for Home + Game — see `phaser-ui-motion` + `phaser-ui-sfx`).
+- `Game` coordinates a session and delegates rules to systems/domain objects; Game settings opens the **same** Home modal (`getDomSettingsPopup().open({ showHome: true })`), not a forked Phaser panel.
+- **New game / greenfield UI:** apply defaults below directly. Do **not** open **`pcgf-ui-reskin`** or build compare.html — there is no Before state.
+- **Reskin / skin / đổi UI on an existing game** → navigator **`pcgf-ui-reskin`** (audit → choose → compare.html → replace on approval). Do **not** treat `phaser-ui-motion` alone as the reskin entry point.
+- Default feeling (button/popup/slider tweens) → skill **`phaser-ui-motion`** + `templates/motion`.
+- Default UI SFX (click/close) → skill **`phaser-ui-sfx`** + `templates/ui/ui-sfx.ts` + plugin `assets/sfx/`.
+- Default DOM/CSS theme → skill **`theme-cream-casual`** (`templates/ui/factory-cream-casual.css`, matches browser demo). **MUST** import it + put `factory-page` on `body` for bare-button press language. Dark navy/purple is optional via **`theme-dark-casual`** only when explicitly requested.
+- Default bitmap UI pack when wiring art on a new game → `assets/ui-packs/super-casual/`. Create-new art → skill **`game-art`**.
+
+Keep scene transitions explicit. Do not hide navigation inside unrelated UI components.
+Do not use a parallel boot splash with a fake progress ticker.
+
+## Architecture rules
+
+- **Prefer MVVM + RxJS** when a feature needs reactive UI state, async progress, or
+  multi-step presentation (LoadingView is the reference). ViewModels own state/`state$`;
+  Views only mirror. Plain services remain fine for pure domain work with no View.
+- Keep authoritative state in a typed model or session object, not in display objects.
+- Let scenes coordinate; let systems implement rules; let UI render state and emit intent.
+- Use domain events or narrow callbacks for cross-system communication. Avoid global mutable variables.
+- Make randomization injectable or seedable when level generation or scoring needs reproducibility.
+- Put balancing values in typed config/data, not magic numbers spread through scene code.
+- Dispose timers, listeners, tweens, and input handlers when a scene/session ends.
+- Prefer data-driven levels and content so adding a level does not require duplicating scene code.
+- Keep shared contracts independent of Phaser whenever possible. Phaser/browser APIs belong in adapters.
+- Route persistence through `StorageService`, time through `TimeService`, async work through `LoadingManager`, and viewport calculations through `LayoutService`.
+- Use typed event maps and include a reason for economy, XP, and reward mutations.
+- Keep game-specific state behind `GameplayModule<TState>`; do not add game rules to shared services.
+
+## Blocking loading and scene transitions
+
+- Follow `references/loading-view.md` / `skills/phaser-loading-view` exactly.
+- MVVM + RxJS: **every** async step (cleanup/load scene, config, user data, assets) is a ViewModel task; View is optional and only mirrors `state$`.
+- Timing: open (source may still show) + showing (≥ min) runs tasks; close is View-only. Progress ≤ 99% until all tasks settle, then 100%.
+- Visual scene work uses `afterOpen: true` or `waitForOpen()` — never swap scenes during open.
+- Boot → Home: `playBootLoadingView` + `bootToHome`; brand from `phaser-studio25-boot-brand`; close style **`iris`** by default, **`slide-up`** when requested.
+- Boot LoadingView **stage box size matches idle Home** (same phone frame / canvas client box). Pin splash to `#game canvas`; iris mask **scale 0 → full** at frog logo origin (`createBootIrisClose`: measure before chrome flip; `afterCoverReady` for hybrid `.is-revealing-home`).
+- Home↔Game / Next Level overlay mask: cover **full → 0**, reveal **0 → full**. Follow `phaser-loading-view`.
+- Queue navigation; prepare destination before close; HTML Home idle stacks above canvas (mask reveal mode keeps canvas on top only while masking).
+- After reveal settles, clear `is-revealing-home` and keep bottom nav (Shop/Main/Heroes) above the canvas (`z-index`); do not leave canvas covering HUD/nav on idle Home.
+- Verify both directions with real controls.
+
+## Demo Test tools (MUST for debug / cheat / QA)
+
+When the user asks to **tạo tool**, add debug/cheat/QA controls, grant gold/XP, FPS HUD, or a Tools FAB — **MUST** follow skill **`tool-demo-qa`** (`templates/demo-tools/`). Do **not** invent a parallel debug panel.
+
+- Prefer **`initDemoQaTools({ getLoop })`** (scaffold → `src/factory/demo-tools/`). It ensures FAB + Perf HUD + **potato/low/mid/high** force buttons (`ensureDemoToolsShell`) + **collapsible sections**.
+- Add game tools with **`appendToolSection`** / `data-action`, or tunable params with **`mountToolParamGroups`** (label-above select/range+value — Volute MOVE layout). Large sections collapse by default (**+** / **−**, not ↑↓).
+- Stay **visible above** splash and Game→Home (do not hide on `is-revealing-home`).
+- Official player build: `enabled: false` / `DEMO_TOOLS_FORCE = false` — tears down FAB/panel **and** Perf HUD (no rAF). Also `?tools=0`.
+- A Tools panel without `[data-tier]` is incomplete — call `ensureDemoToolsShell` / `initDemoQaTools`.
+
+## UI theme, feeling, and SFX (new games)
+
+On **new / greenfield** work, wire defaults directly — no reskin navigator, no compare.html:
+
+| Lane | Default skill / pack |
+|------|----------------------|
+| Theme | **`theme-cream-casual`** |
+| Feeling | **`phaser-ui-motion`** |
+| SFX | **`phaser-ui-sfx`** |
+| Bitmap pack (when needed) | **`super-casual`** (`assets/ui-packs/super-casual/`) |
+| Create-new art | **`game-art`** |
+
+## UI reskin (existing games only)
+
+When the user asks to **reskin**, restyle product UI, swap UI packs, or upgrade theme/assets/feeling/SFX on a game that **already has** chrome — follow navigator **`pcgf-ui-reskin`** (audit → choose defaults/options → apply → **compare.html** → replace on approval). Never run that compare/replace flow for a brand-new project.
+
+Follow **`theme-cream-casual`** for **all** default DOM chrome (cream page, green primary, gold costs, hot close) unless the game supplies art or explicitly opts into **`theme-dark-casual`**.
+
+- **MUST** `@import` `factory-cream-casual.css`, set `body.factory-page`, and call **`bindFactoryDomPress()`** so press uses `box-shadow: none` and survives drag-off (no stuck tween).
+- **MUST NOT** invent purple-on-navy / flat buttons / keep shadow while pressed / clear press on `pointerout`.
+- Details → skill **`theme-cream-casual`**.
+
+Follow **`phaser-ui-motion`** for every interactive control's **feeling**:
+
+- Buttons → `bindButtonMotion` only (motion file **must** include `finishFromWindow` / window `pointerup` for release outside canvas). **Press held until release**; never clear on `pointerout`. Stuck after thả ngoài canvas → follow `phaser-ui-motion/fix-off-canvas-press.md`.
+- Settings volume UI chrome/tweens: one modal (`templates/ui/settings-popup-dom.ts` + `audio-settings.ts`) for Home and Game; Game only toggles the Home CTA.
+- Popups dismiss only on dim / × / explicit dismiss — never on panel chrome taps.
+
+Follow **`phaser-ui-sfx`** for shared click/close sounds (not inside motion authorship):
+
+- Prefer HTMLAudio clones (`playUiClick` / `playUiClose` from `templates/ui/ui-sfx.ts`); files `/assets/sfx/ui_*.mp3` (plugin defaults in `assets/sfx/`).
+- Do not assume Phaser `cache.audio` alone in hybrid demos.
+- Create/replace UI sounds via **`phaser-ui-sfx`** (or a future SFX skill registered in `pcgf-ui-reskin`).
+
+## Responsive layout
+
+Use one layout policy for the whole game:
+
+- Define a logical design size and let Phaser scale the canvas to the viewport.
+- Keep gameplay coordinates in world space and HUD coordinates in screen/UI space.
+- Recalculate layout on resize/orientation changes through a single layout service or scene method.
+- Anchor controls by semantic regions (`topBar`, `playArea`, `bottomActions`) rather than fixed pixels.
+- Preserve touch target sizes and readable text on narrow screens.
+- Test at at least one narrow portrait and one wide landscape viewport.
+
+## Casual-game UX baseline
+
+Every playable flow should provide:
+
+- An immediate visual response to tap/click (**`bindButtonMotion`** / DOM twin — `phaser-ui-motion`).
+- Clear idle, success, failure, and disabled states.
+- A pause/restart path where the platform permits it.
+- Short feedback loops: score, progress, combo, timer, or goal status is visible.
+- Audio that respects a persisted mute/SFX setting (`audio-settings`) and starts only after browser interaction when required; UI click/close via **`phaser-ui-sfx`** must be audible on **every** press, not only the first gesture.
+- A result state that explains what happened and offers a single obvious next action.
+
+## Turning a description into a game
+
+1. Convert the request into a scene/transition matrix before implementation: source,
+   destination, blocking tasks, open/minimum/close timing, and presentation variant.
+2. Inspect supplied screenshots/assets and derive palette, shape, spacing and typography.
+   Never use a screenshot with baked cards/buttons as a generic scene background.
+3. Build ViewModels and service boundaries first, then Views and game-specific art.
+4. If gameplay is not implemented yet, reserve the final play-area footprint with a
+   genre-appropriate placeholder (board/grid/lane), without putting rules in the scene.
+5. Keep HTML and Phaser layout ownership explicit. A transition must reveal the final
+   destination layout, not a temporary background or differently sized shell.
+
+## Implementation workflow
+
+1. Read the relevant core contracts and inspect existing adapters.
+2. Write the smallest gameplay contract: start condition, actions, success/failure, and end condition.
+3. Add or update typed state and events before wiring visual effects.
+4. Implement the happy path with placeholder visuals.
+5. Add responsive UI and interaction feedback.
+6. Add audio, persistence, transitions, and polish as separate changes.
+7. Verify desktop and touch input, resize behavior, restart behavior, and scene cleanup.
+8. Report changed files, checks run, and any remaining asset/content assumptions.
+
+## Review checklist
+
+Flag these issues during review:
+
+- Gameplay state stored only in sprites/text objects.
+- Scene `create()` or `update()` growing into a monolith.
+- Resize logic duplicated across components.
+- Input listeners or timers surviving scene shutdown.
+- Restart causing duplicate listeners, duplicated sprites, or stale state.
+- Audio starting without a user gesture or ignoring mute/SFX volume.
+- Silent buttons / missing press feeling (skipped `bindButtonMotion` or missing **`phaser-ui-sfx`** / empty `/assets/sfx/`).
+- Existing-game UI reskin done only through `phaser-ui-motion` without **`pcgf-ui-reskin`** audit / compare.html (greenfield creates do not need compare.html).
+- Stuck / wrong button press after drag-off (must **keep** press until release like Settings close; finish on scene `POINTER_UP` + pointer capture — never clear press on `pointerout`; see `phaser-ui-motion`).
+- Forked Settings UI between Home and Game with divergent slider/tween behavior.
+- Popup closing when tapping inside the panel (missing dim-only dismiss / panel sink).
+- Hard-coded viewport coordinates that break on mobile.
+- New assets loaded from gameplay scenes without a loading/error path.
+- A feature that cannot be tested without clicking through the entire game.
+
+## Refresh plugin on an existing game
+
+If `_pcgf/` already exists, update skills/templates with `--no-scaffold` so `src/` is not overwritten:
+
+```bash
+npx @quybt93/pcgf install --yes --no-scaffold
+```
+
+If install looks stale (old skill names, bad scaffold), wipe then reinstall:
+
+```bash
+npx @quybt93/pcgf clean --yes
+npx @quybt93/pcgf install --yes --scaffold
+```
+
+Use `pcgf clean --yes --with-scaffold` to also delete `src/factory/`. From Git: append the same flags to the `npx --yes --package=git+ssh://... pcgf …` command.
+
+## Shipping to Git
+
+When the user asks to commit, push, or land on `main`, follow **`pcgf-git-merge-request`**: side branch → rebase `origin/main` → push branch → GitLab Merge Request. Do not push straight to `main`.
+
+## Completion standard
+
+A task is complete when the game behavior works, the reusable boundary is clear, the narrowest relevant checks pass, and the handoff mentions any unverified browser/device behavior. Do not introduce a framework migration or a large abstraction unless the task explicitly calls for it.

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

@@ -0,0 +1,21 @@
+---
+name: phaser-condition-service
+description: "Build remote-config-ready gameplay conditions for Phaser casual games, including player levels, login totals and streaks, resources, comparison operators, AND/OR/NOT groups, descriptions, and UI progress. Use for feature gates, unlocks, and requirements; not for mutating rewards."
+---
+
+# Phaser Condition Service
+
+Use `templates/condition/` with the shared Economy repository. Read `references/condition-service.md` before adding a configurable game requirement.
+
+## Config and evaluation
+
+- Store definitions as JSON-safe `ConditionConfig`; call `replaceConfig()` after local or remote config validation/loading. Definition key and `id` must match.
+- Use metric `level` with `params.trackId`, `login-days`, `login-streak`, or `resource` with `params.resourceId`. Supported operators are `>=`, `>`, `=`, `!=`, `<`, and `<=`.
+- Combine nodes with `all`, `any`, and `not`. Do not hard-code condition checks in Phaser scenes.
+- Call `getViewModel(id)` for UI. It returns `met`, description, `current`, `target`, percent, and a format-ready `x/y`, percent, or combined label.
+
+## Extensibility
+
+- Register a `ConditionMetricProvider` for every future metric, such as quest count, hero star, battle-pass tier, package ownership, or server flag. Providers only read state.
+- If a Leveling track starts above zero before it has been persisted, pass `createLevelMetricProvider({ character: 1 })` (or defaults generated from Leveling config) to preserve correct initial progress.
+- Condition evaluation has no side effect. The caller performs a later Economy/Leveling transaction after a condition is met; server-authoritative features must revalidate on the backend.

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

@@ -0,0 +1,20 @@
+---
+name: phaser-daily-login-service
+description: "Add persistent daily-login tracking to a Phaser casual game: date lookup, consecutive login streaks, local/portal login sources, idempotent registration, and automatic new-day registration. Use for login calendars and streak UI; reward-claim calendars need an additional reward config layer."
+---
+
+# Phaser Daily Login Service
+
+Use `templates/daily-login/` with the shared Economy repository and `ManagedTimeService`. Read `references/daily-login-service.md` before adding a login calendar, portal callback, or streak UI.
+
+## Invariants
+
+- Configure TimeService timezone before creating Daily Login. A login day is its `YYYY-MM-DD` key, never the device's unconfigured Date string.
+- Call `startAutoRegistration()` once in the application/session coordinator. It registers the current day immediately and subscribes to TimeService `new-day`; dispose it at application teardown.
+- For a portal or third-party callback, call `registerLogin({ dayKey, source, transactionId })`. The external callback ID must be stable on retry.
+- `registerLogin` is idempotent. A repeated date or duplicate transaction never increases the streak. Use `hasLoggedIn(dayKey)` and `getConsecutiveLoginDays()` for UI rather than recalculating dates in a scene.
+- This service records attendance only. A future reward-claim feature must evaluate its own eligibility and grant through Economy atomically; do not put rewards in the time event callback.
+
+## State semantics
+
+`currentStreak` is the contiguous sequence ending on the most recent recorded login date. `longestStreak` is the highest contiguous sequence ever recorded. Registering historical days is supported for verified portal migration and recomputes both safely.

package/plugins/phaser-casual-game-factory/skills/phaser-economy-service/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: phaser-economy-service
+description: Implement extensible, config-driven Phaser game economy operations with atomic local transactions, idempotency keys, resource capabilities, and a repository boundary ready for server synchronization.
+---
+
+# Phaser Economy Service
+
+Use `templates/economy/` for economy work. Read `references/core-contracts.md` first when connecting the economy to a new game.
+
+## Design rules
+
+- Model resources as data with explicit capabilities: `grantable`, `spendable`, `sellable`, `convertible`, and `mergeable`.
+- Keep each operation in its own handler. Register new operations; do not edit existing handlers to add unrelated behavior.
+- Put quantities, weights, recipes, rewards, and package entitlements in config.
+- Require a unique `transactionId` for every mutation, including free rewards and daily login claims.
+- Execute mutations through `EconomyRepository.runAtomic`. Never mutate UI state or storage directly from a scene.
+- Validate all inputs and outputs before committing. A failed operation must leave balances, packages, and transaction records unchanged.
+- Return a receipt containing the transaction ID, operation type, and balance changes.
+
+## Supported operations
+
+- `grant`: all configured rewards, weighted random selection, or user-selected rewards; each reward can use a fixed or random quantity.
+- `sell`: consume one or more sellable resources and grant one or more configured rewards.
+- `convert`: consume convertible resources and grant another resource set.
+- `merge`: consume mergeable fragments/items and grant the configured result.
+- `activate-package`: record package entitlements and optional rewards exactly once.
+
+## Items and equipment
+
+Use `DefaultItemService` for item instances that have generated stats or skills. Keep the item template immutable and store the rolled effects on the instance.
+
+- Creation can use fixed effects, weighted random effects, or random stat ranges.
+- A change creates a proposal containing `before`, `after`, `baseRevision`, and resource cost.
+- Preview/roll validates and charges the configured resources atomically, then stores the proposal while leaving the item unchanged.
+- Apply validates the base revision and commits the already-paid proposal; it never charges resources again.
+- If the user does not apply the proposal, the rolled cost remains spent but the item remains unchanged.
+- Revert restores the proposal's `before` snapshot after apply, or discards a pending proposal without changing the item; it never charges/refunds resources.
+- Reject stale proposals when the item revision changed after reroll.
+
+Do not mutate an item's stats in the UI. The UI should display a proposal and call apply or revert with a new transaction ID.
+
+Use `buildItemRerollViewModel()` to render current-to-proposed stat/skill diffs, up/down direction, cost label, and `canReroll`. Use `buildInventoryDetailViewModel()` for owned amount clamping, open/sell availability, and select-open state. These view models keep UI rules reusable across Phaser and HTML/CSS screens.
+
+## Inventory items
+
+Use `DefaultInventoryService` for stackable consumables that are separate from generated equipment. Define each item in `InventoryConfig` with optional `open` and `sell` capabilities.
+
+- `open.mode: 'all'` grants every configured entry.
+- `open.mode: 'weighted-random'` selects by configured weights.
+- `open.mode: 'select'` requires the UI to pass selected reward IDs.
+- Opening and selling consume the requested stack amount atomically and return item/resource reward summaries.
+- Use `list()` and `getAmount()` to build inventory UI; do not mutate stack counts directly from Phaser scenes.
+- Detail UI should clamp amount to `1..owned`, expose minus/plus/max/input controls, and use a confirmation/action button for open or sell.
+- Use a stable transaction ID for seed, open, and sell operations so repeated clicks cannot duplicate rewards.
+
+## Transaction behavior
+
+The local repository serializes concurrent calls, checks `transactionId` before executing, commits a cloned state only after the handler succeeds, and persists the receipt with the state. A repeated ID returns the original receipt and cannot grant resources again.
+
+For server integration, implement the same repository contract with a database transaction or server-side idempotency store. Do not move atomicity into the Phaser scene.
+
+## Adding a new operation
+
+1. Add a new discriminated request type.
+2. Add its config shape and validation rules.
+3. Implement one `EconomyOperationHandler`.
+4. Register it in the operation registry.
+5. Add tests for success, insufficient balance, invalid config, duplicate transaction, and concurrent calls.
+
+For item changes also test fixed versus random rolls, skill unlocks, stale proposal rejection, apply/revert, and duplicate apply.
+
+Do not change the repository or existing handlers unless the transaction contract itself changes.

package/plugins/phaser-casual-game-factory/skills/phaser-foundation/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: phaser-foundation
+description: Build or adapt the reusable Phaser runtime foundation for casual games, including typed event buses, storage and time adapters, scene context, lifecycle cleanup, and scene registration. Use before adding game-specific gameplay or shared services.
+---
+
+# Phaser Foundation
+
+Use the templates in `templates/phaser/` together with the contracts in `templates/core/`. The foundation connects framework/browser APIs to framework-independent contracts.
+
+## Boundaries
+
+- Keep domain services independent of Phaser.
+- Put Phaser, browser storage, and browser clock access in adapters.
+- Pass a `GameContext` into scenes; do not construct global services inside individual scenes.
+- Register cleanup for every listener, timer, tween, and subscription created by a scene.
+- Default scene set: **Boot → Home → Game**. Register `FactoryLoadingOverlay` last as a
+  technical Loading View (not a gameplay destination).
+- Prefer **MVVM + RxJS** for features that need reactive View state (see LoadingView);
+  keep pure domain services Phaser/RxJS-free when no View is involved.
+- Boot → Home uses `playBootLoadingView` + `bootToHome`; company logo/wordmark/tips + close styles
+  (`iris` default / `slide-up`) live in skill **`phaser-studio25-boot-brand`** (`templates/boot/`).
+  Rebrand only that skill. Default close is **`iris`** unless the product asks for `slide-up`.
+  Hybrid: Boot splash box size matches Home stage; iris **0 → full** at logo (`afterCoverReady` for chrome).
+  Details → `phaser-loading-view` + `phaser-studio25-boot-brand`.
+- Home↔Game / Next Level use `FactoryLoadingOverlay` (queue requests; never merge intents).
+  Overlay hole: cover **full → 0**, reveal **0 → full**. Pause BitmapMask while fully covered
+  (HUD dwell); resume before reveal. Progress HUD paint only on **Δ ≥ 1%** whole-percent steps
+  (see `phaser-loading-view`). Do not reuse Home↔Game hole contracts for Boot `slide-up`.
+- For hybrid HTML Home, use a transparent renderer and coordinator-owned DOM mode;
+  scene `create()` must not move HTML above the loading canvas.
+- Copy `templates/motion/` and `templates/ui/` (audio settings + shared settings popup +
+  **`factory-cream-casual.css`** default style) with the foundation; wire UI SFX via HTMLAudio
+  (or equivalent) so click/close work without Phaser cache.
+  Default look → skill **`theme-cream-casual`**: import `factory-cream-casual.css` + `body.factory-page` + `bindFactoryDomPress()`.
+  Optional dark preview → **`theme-dark-casual`** only when requested. Do not invent parallel DOM themes.
+  Follow skill **`phaser-ui-motion`** for buttons, popups, sliders, and Home/Game settings
+  (press held until release — never clear press on `pointerout`; see that skill’s NEVER/ALWAYS).
+- Debug / cheat / QA Test tools → skill **`tool-demo-qa`** (`templates/demo-tools/`, `initDemoQaTools`,
+  `appendToolSection`). Do not invent a parallel tools panel.
+
+## Implementation order
+
+1. Copy the core contracts and the relevant Phaser adapters into the game project.
+2. Create one application context that owns the event bus, storage, time, and service implementations.
+3. Pass the context into the first scene through scene data or a project-level bootstrap.
+4. Extend `FoundationScene` for scenes that need automatic subscription cleanup.
+5. Register Boot, Home, Game (+ overlay) in one place; only Boot auto-starts.
+6. Add framework-specific adapters only when a contract requires them.
+7. Copy `templates/loading-view/`, `templates/boot/` (incl. brand skill assets), Phaser overlay,
+   `templates/motion/`, `templates/ui/`, and hybrid CSS.
+
+## Verification
+
+- Reloading a scene does not duplicate event listeners.
+- Restarting a game creates a fresh session state.
+- Storage failures do not crash boot; the adapter has a safe fallback or explicit error policy.
+- Time-dependent systems can receive a fake clock in tests.
+- Scene transitions do not leak timers, tweens, or subscriptions.
+- The final destination layout is already beneath LoadingView before close begins.
+- Core services can be tested without creating a Phaser game instance.

package/plugins/phaser-casual-game-factory/skills/phaser-leveling-service/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: phaser-leveling-service
+description: Implement reusable character, hero, battle-pass, and progression level tracks with XP, resource upgrades, conditions, max-level overflow, automatic rewards, reset/refund policies, typed events, and atomic transaction behavior.
+---
+
+# Phaser Leveling Service
+
+Use `templates/leveling/` with the shared economy repository and economy config. A level track is data, not a separate service class: character level, hero level, battle pass, and future progression types use the same API.
+
+Call `validateLevelingConfig(config, economyConfig)` before loading a game. `DefaultLevelingService` validates automatically and rejects experience tracks with a finite `maxLevel` when any curve entry from `startLevel` through `maxLevel - 1` is missing. This catches a rollback-causing missing Battle Pass curve before gameplay.
+
+## Track modes
+
+- `experience`: add XP, level up automatically, preserve XP overflow at max level, and keep total XP.
+- `resource`: upgrade one level at a time by configured resource cost and conditions; store the exact cost spent at each level for reset/refund.
+
+Every track has a configurable start level. Default it to `1`, but allow `0` or another value.
+
+## Atomic rules
+
+- Add XP, level-up rewards, feature unlock summaries, and persistence commit as one repository transaction.
+- Resource upgrade cost, level change, and level-up rewards commit together.
+- Reset/refund and state reset commit together.
+- If any resource check, condition, reward grant, or persistence step fails, do not save XP, level, spent cost, or claimed rewards.
+- Use a unique transaction ID for XP grants, upgrades, and resets. A duplicate ID returns the original receipt and does not repeat rewards.
+
+## Rewards and events
+
+Level-up rewards are automatic. The returned receipt contains an aggregated `rewards` list for UI presentation after an animation or flow completes. Feature unlocks are notification summaries unless a dedicated feature service is connected.
+
+Emit events only after the repository transaction succeeds. UI may subscribe to level-track changes, level-up events, rewards, and reset/refund results.
+
+## Conditions and reset
+
+Use configured conditions for upgrades. The default evaluator supports other track levels, resource balances, AND, and OR. Keep the evaluator injectable so a future ConditionService can handle quests, stars, unlocks, and compound conditions.
+
+Reset behavior is configured per track. A reset can return to the configured default level, clear XP, optionally clear claimed rewards, and refund a configured percentage of recorded resource costs. XP overflow is not silently discarded at max level; it remains in the track state.
+
+Use `buildLevelTrackViewModel()` for UI. It exposes level/max labels, `XP current/required` (or current XP at max), next-level costs, condition labels, and `canUpgrade`. Keep this view model separate from Phaser scene objects so HTML, Phaser UI, and tests render the same state.

package/plugins/phaser-casual-game-factory/skills/phaser-loading-view/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: phaser-loading-view
+description: Implements or fixes Phaser blocking LoadingView transitions with MVVM, RxJS task progress, independent open/minimum/close timing, queued scene requests, bitmap masks, progress paint dirty-checks, mask pause while fully covered, and safe Phaser/HTML layering. Use for Boot→Home wiring, Home↔Game transitions, mandatory level entry, Next Level loading, progress bars, transition flashes, duplicated loading, loading jank, or destination layout reveal bugs. For company Boot logo/wordmark/tips, use phaser-studio25-boot-brand.
+---
+
+# Phaser LoadingView
+
+Read `references/loading-view.md`, then use the canonical templates:
+
+- `templates/loading-view/`
+- `templates/boot/play-boot-loading-view.ts` — Boot → Home wire into ViewModel
+- Company Boot brand (logo, 25 STUDIO, tips) → skill **`phaser-studio25-boot-brand`**
+  (`templates/boot/brand/`)
+- `templates/phaser/loading-overlay-scene.ts` — Home↔Game / Next Level View (technical scene)
+- `templates/phaser/hybrid-loading-layer.css`
+
+## Required architecture
+
+Always follow this contract — do not invent a parallel loader.
+
+1. One `LoadingViewModel` per user operation.
+2. **Every** async step registers as a weighted task: cleanup scene, load scene, config, user data, mandatory assets, layout prepare, …
+3. Timing lives on the ViewModel:
+   - `openDurationMs` — open/cover; source may still be visible
+   - `minimumVisibleMs` — minimum `showing` after open
+   - `closeDurationMs` — View close/reveal **only** (no async work)
+4. Task window = open + showing (`showing ≥ minimumVisibleMs`).
+5. `actualProgress` ≤ **0.99** until all tasks settle, then **1**.
+6. Visual scene work waits for open: `afterOpen: true` or `await waitForOpen()`.
+7. View is **optional** and only mirrors `state$` — never owns load work.
+8. Queue requests; never merge two navigation intents.
+9. Destination fully prepared beneath LoadingView before `closing`.
+
+```ts
+new LoadingViewModel(
+  {
+    ...LOADING_TIMING_PRESETS.menuToGame,
+    description: 'Loading Game…',
+  },
+  [
+    { id: 'player-data', weight: 1, run: loadData },
+    { id: 'game-scene', weight: 2, afterOpen: true, run: swapScene },
+  ],
+);
+```
+
+## Boot → Home (structure stays here; brand is a separate skill)
+
+Default scenes: Boot, Home, Game. Boot always calls `playBootLoadingView` + `bootToHome`.
+
+```ts
+await playBootLoadingView(
+  new LoadingViewModel(
+    {
+      ...LOADING_TIMING_PRESETS.bootToHome, // open 0 / min 2000 / close 700 (iris)
+      description: 'Loading…',
+    },
+    [bootAssetsTask, bootDataTask, { ...homeSceneTask, afterOpen: true }],
+  ),
+  {
+    // Default closeStyle is iris — omit closeStyle or set BOOT_CLOSE_STYLE.iris.
+    // For associatio-match DOM slide: closeStyle: BOOT_CLOSE_STYLE.slideUp
+    splashAnchor: document.querySelector('#game canvas') ?? document.getElementById('game'),
+    runIrisClose: createBootIrisClose({
+      game,
+      maskKey,
+      ensureOverlay,
+      prepareCameras, // cameras / transparency only — do NOT flip Home chrome here
+      afterCoverReady, // hybrid: `.is-revealing-home` phone Home under veil
+    }),
+  },
+);
+```
+
+- **One** ViewModel; **one** Boot View (`playBootLoadingView`).
+- Brand art/copy/tips + Boot close styles (`iris` default / `slide-up`) → **`phaser-studio25-boot-brand`**.
+- `#loading-overlay` stays hidden for the whole boot.
+- Home↔Game / Next Level: `FactoryLoadingOverlayScene` (technical scene, not a destination).
+- Prepare Home **scene/data** under LoadingView before close; emit home mode after close finishes.
+- Hybrid demos: Boot splash **overall box size must match idle Home stage** (same phone frame, e.g. 390×720 FIT). Do **not** use a full-viewport Boot host that jumps to a smaller Home.
+
+## Mask scale (Home↔Game / Next Level + Boot `iris`)
+
+Bitmap mask = opaque frog PNG as an `invertAlpha` **hole**. Do not invent a stamp-from-0 cover for Home↔Game.
+
+| Flow | Open / cover | Close / reveal |
+|------|----------------|----------------|
+| Home ↔ Game (`scene-transition`) | hole **full → 0** | hole **0 → full** |
+| Next Level (`next-level`) | hole **full → 0** | hole **0 → full** |
+| Boot → Home `iris` (default) | n/a (open 0) | hole **0 → full** at mapped frog origin |
+| Boot → Home `slide-up` | n/a (open 0) | **DOM** `#studio25-splash.done` → `translateY(-102%)` |
+
+### Boot `iris` origin (required)
+
+1. Pin `#studio25-splash` to **`#game canvas`** (`syncSplashToGameView`) — same client box iris maps against.
+2. Sample frog with animations paused (`getFrogLogoRect` / equivalent) **while Boot splash layout is still stable**.
+3. Map with `mapDomRectToPhaserGame` → `originX/Y`; mask **`setScale(0)`** then tween to full.
+4. `prepareCameras`: Boot/Home camera transparency only — **do not** resize stage / flip HUD here (that drifts the logo→mask map).
+5. `onCoverReady` / `afterCoverReady`: dismiss DOM splash, then flip hybrid Home chrome (`.is-revealing-home`) **under** the night veil.
+6. Do not copy Boot iris 0-start onto Home↔Game cover. Boot `slide-up`: `beginClose()` only — no overlay iris.
+
+### Home↔Game / Next Level mask while HUD shows (required)
+
+When the cover hole is fully closed (`frog.scale ≈ 0`), the solid cream veil already occludes — keep running `BitmapMask` only wastes GPU.
+
+1. After cover completes (and again when HUD/`showing` starts): `cover.clearMask(false)` via `pauseCoverMaskWhileFullyCovered()` — do **not** destroy the mask object.
+2. Solid cover rectangles stay visible; HUD slider/text are siblings (not under the mask).
+3. Before reveal tween: `resumeCoverMaskForReveal()` — re-`setMask`, frog at **scale 0**, then hole **0 → full**.
+4. Do not leave the mask attached for the whole `minimumVisibleMs` dwell.
+
+## Timing formulas
+
+```text
+displayed = min(actualProgress, elapsedVisible / minimumVisibleMs)
+actual     ≤ 0.99 until all tasks done, else 1
+visible    = max(work after open, minimumVisibleMs)
+total      = open + visible + close
+```
+
+Zero is valid for every timing. With min `0`, work finished by end of open skips
+description/slider and goes directly to close.
+
+## View progress paint (required — jank root cause)
+
+Lag during the loading bar is almost always **View redraw**, not the progress formulas.
+
+| Rule | Contract |
+|------|----------|
+| Dirty-check | Paint slider / `%` only when `Math.round(displayedProgress * 100)` changes (**Δ ≥ 1%**). Lerp may run every frame; **Graphics / setText must not**. |
+| Player XP slider | Home↔Game / Next Level use Player `.xp-track` look (`createHomeStyleSlider` in overlay). Prefer track chrome once + cheap fill updates; if using `Graphics.clear` + rounded fill, still gate on the 1% dirty-check. |
+| Plain `rectangle` / `scaleX` fill | Leading fill edge is **square** unless clipped (GeometryMask / overflow). Keep rounded fill via Graphics-on-1%-step or a clipped fill — do not redraw every frame “for smoothness”. |
+| Boot DOM bar | Same 1% gate when setting fill width / tip / `aria-valuenow` (skip identical whole percent). |
+| Fake ticker | Never. Progress comes from ViewModel `displayedProgress` only. |
+
+Canonical overlay helpers: `progressDrawnPercent` in `FactoryLoadingOverlayScene.update`, and `drawnPercent` inside `createHomeStyleSlider`.
+
+## Hybrid HTML destinations
+
+- Transparent renderer + transparent Phaser HomeScene.
+- Design size + CSS stage share one phone box for Boot **and** Home (demo: 390×720). Boot `.is-boot` keeps that box (night BG, HUD/nav hidden); do not expand Boot to full viewport.
+- Splash CSS: `#studio25-splash` uses `align-items:center; justify-content:center` (sculpin) so frog + wordmark center in the stage box.
+- Prepare final Home HTML during the loading task (after open when open > 0); keep chrome flip for iris until `afterCoverReady`.
+- LoadingView above HTML through close; idle Home HTML above canvas (see demo CSS).
+- Boot/Game → Home: Boot `iris` uses `.is-boot.is-revealing-home` **after** night cover; Boot `slide-up` prefers idle Home under splash; Game → Home uses `.is-game.is-revealing-home`.
+- While `is-revealing-home` (mask), `.game-host` is absolute over the **full** `.stage-screen` (`overflow: visible` on body) so HUD/nav stay under the veil; canvas `z-index` above HTML.
+- After settle: clear `is-revealing-home`, set `is-home`, keep **HUD + bottom nav** above canvas (`z-index` + `pointer-events: none` on idle `.game-host`).
+  Regression: nav “missing” was often canvas coverage, not a removed DOM node.
+
+## Art
+
+- Boot company identity → `phaser-studio25-boot-brand` (`brand-defaults.js` + `logo-frog.png`).
+- Home↔Game / Next Level LoadingView share **Home cream** (`#fff6ea`), **Home font** (`Be Vietnam Pro`), and **Home XP-track slider** by default.
+
+## Verification
+
+- Boot uses `playBootLoadingView` + brand skill defaults; `#loading-overlay` hidden;
+- Boot LoadingView client box ≈ Home `.stage-screen` / canvas box (same phone size);
+- Boot close defaults to **`iris`**; frog mask starts at **scale 0** on logo point; `slide-up` only when requested;
+- Home↔Game / Next Level keep full→0 / 0→full;
+- Home↔Game / Next Level **pause BitmapMask** while fully covered / HUD dwell; restore before reveal;
+- Progress HUD paints only on **whole-percent** changes (Δ ≥ 1%);
+- Home↔Game / Next Level use `FactoryLoadingOverlay` (technical scene);
+- All async work is ViewModel tasks; scene cleanup/start uses `afterOpen`;
+- Progress stays at 99% until complete; close has no tasks;
+- View optional / state$-driven;
+- production build + browser tests;
+- idle Home shows HUD + bottom nav above canvas (not covered by leftover `is-revealing-home`).