@quybt93/pcgf 0.0.1

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

@@ -0,0 +1,107 @@
+---
+name: phaser-studio25-boot-brand
+description: Owns the company Studio25 Boot→Home LoadingView brand (logo-frog.png, 25 STUDIO wordmark, tips, tagline, footer) and Boot close styles iris (default) / slide-up. Use when implementing or rebranding Boot splash/logo, Studio25 boot art, or company identity on first load — not for Home↔Game overlay chrome or gameplay art.
+---
+
+# Studio25 Boot Brand
+
+Single source of truth for **company** Boot → Home presentation. Loading timing/tasks stay in `phaser-loading-view`; this skill owns identity (image, wordmark, tips, copy) and **Boot close styles**.
+
+## Rule
+
+`logo-frog.png` + **25 STUDIO** (+ tips) is the company default — do not replace with a game splash unless the product explicitly rebrands the studio.
+
+When rebranding: **update this skill + brand templates/assets only**. Do not fork BootScene structure or invent a second boot loader.
+
+## Boot close styles (switchable)
+
+| Style id | Constant | Behavior | When |
+|----------|----------|----------|------|
+| **`iris`** | `BOOT_CLOSE_STYLE.iris` | Frog bitmap mask scale **0 → full** at logo origin (`createBootIrisClose` → `playIconMaskReveal`) | **Default** when product does not request another close |
+| **`slide-up`** | `BOOT_CLOSE_STYLE.slideUp` | Whole `#studio25-splash` slides up — `done` → `translateY(-102%)`, `.65s` `cubic-bezier(.7,0,.3,1)` (associatio-match) | Opt-in when a game asks for DOM slide close |
+
+```ts
+import {
+  BOOT_CLOSE_STYLE,
+  createBootIrisClose,
+  playBootLoadingView,
+} from '../factory/boot';
+
+await playBootLoadingView(viewModel, {
+  closeStyle: BOOT_CLOSE_STYLE.iris, // default — omit for same effect
+  splashAnchor: document.querySelector('#game canvas') ?? document.getElementById('game'),
+  runIrisClose: createBootIrisClose({
+    game,
+    maskKey, // same art as DOM frogSrc / logo-frog.png
+    ensureOverlay,
+    prepareCameras, // cameras only
+    afterCoverReady, // hybrid Home chrome under veil
+  }),
+});
+
+// Switch later:
+// closeStyle: BOOT_CLOSE_STYLE.slideUp  // no runIrisClose needed
+```
+
+- Files: `templates/boot/close-styles.ts`, `iris-close.ts`, `play-boot-loading-view.ts`.
+- Home↔Game / Next Level **bitmap hole** (full→0 / 0→full) is **not** these styles — see `phaser-loading-view`.
+
+## Splash pin + iris origin (required)
+
+1. `#studio25-splash` is `position:fixed` and sized by `syncSplashToGameView` to the **Phaser canvas** client box (fallback: `#game` / viewport if canvas is 0×0). Prefer `align-items:center; justify-content:center` so frog + wordmark center in that box (sculpin layout).
+2. Hybrid shell: Boot stage box **equals** idle Home stage (same phone frame). Do not run Boot as full-viewport then jump to a smaller Home.
+3. Iris close order (`createBootIrisClose`):
+   - Re-sync splash → measure frog with float/drop animations paused → `mapDomRectToPhaserGame`.
+   - Mask at that origin with **`scale: 0`**, then tween to full (`playIconMaskReveal`).
+   - `prepareCameras`: transparency / hide Boot camera only — **no** stage resize / HUD flip.
+   - `onCoverReady`: `dismissDomSplash`, then `afterCoverReady` (e.g. `.is-boot.is-revealing-home`).
+4. Same `logo-frog.png` (or brand path) for DOM frog and iris/`maskKey` so the hole matches the logo art.
+
+## Canonical files
+
+| Piece | Path |
+|-------|------|
+| Close style ids | `templates/boot/close-styles.ts` |
+| Iris runner helper | `templates/boot/iris-close.ts` (`prepareCameras` / `afterCoverReady`) |
+| Brand tokens (edit first) | `templates/boot/brand/brand-defaults.js` |
+| DOM LoadingView | `templates/boot/brand/BootLoadingScreen.js` |
+| Fullscreen splash sync | `templates/boot/brand/SplashFullscreenBg.js` |
+| Wire into LoadingViewModel | `templates/boot/play-boot-loading-view.ts` |
+| Public logo | `public/logo-frog.png` (demo: `examples/factory-browser-demo/public/logo-frog.png`) |
+
+## Default tokens
+
+```js
+// templates/boot/brand/brand-defaults.js
+frogSrc: '/logo-frog.png'          // DOM frog (+ iris / overlay may reuse URL)
+wordmark: { n: '25', s: 'STUDIO' }
+tagline: 'Building Instant Games for the World'
+footer: 'A Skylink Group Company'
+tips: [ /* rotating progress tips */ ]
+```
+
+## Rebrand checklist (only this skill)
+
+1. Edit `templates/boot/brand/brand-defaults.js` (paths, wordmark, tips, tagline, footer).
+2. Replace `public/logo-frog.png` (or new path referenced in defaults).
+3. Update this `SKILL.md` so agents match the new identity.
+4. Keep `playBootLoadingView` + `LOADING_TIMING_PRESETS.bootToHome` — do not change LoadingViewModel task contract.
+5. Do **not** put game-title splash art here; game art belongs on Home / overlay BG.
+6. Keep default `closeStyle: 'iris'` unless the product explicitly asks for `slide-up`.
+7. Keep splash pin → canvas and iris **0 → full** at logo origin; do not start iris from a mismatched rect.
+
+## Out of scope
+
+- Home ↔ Game / Next Level timing and overlay layout → `phaser-loading-view`
+- Economy, leveling, adaptive prefetch → their own skills
+- Gameplay HUD art
+
+## Verification
+
+- Boot shows company frog + 25 STUDIO + tips; progress from ViewModel only.
+- Boot DOM progress fill / tip / `aria-valuenow`: update only when whole percent changes (**Δ ≥ 1%**).
+- Splash box matches Home stage/canvas size; frog and wordmark are centered in the splash.
+- Default close is **`iris`**; mask starts at **scale 0** on the live logo point; `slide-up` only when `closeStyle` is set explicitly.
+- Switching styles is a one-line `closeStyle` change (+ `runIrisClose` only for iris).
+- No parallel `#loading-overlay` / fake ticker during boot.
+- Changing brand does not require rewriting BootScene task list.

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

@@ -0,0 +1,26 @@
+---
+name: phaser-time-service
+description: Add a reusable timezone-aware TimeService to a Phaser casual game, including local-first/server-sync clocks, reset-boundary events, and minute interval subscriptions. Use for daily/weekly/monthly resets, countdowns, and server-time migration; not for a one-off scene timer.
+---
+
+# Phaser Time Service
+
+Use `templates/time/` for domain time. It is Phaser-independent and starts with `LocalTimeSource`; replace only the source with `ServerTimeSource` when an authoritative backend clock is available. Read `references/time-service.md` before wiring reset-dependent features.
+
+## Integration rules
+
+- Configure an IANA `timeZone` explicitly for any shared/global reset. Do not use a player's browser zone unless that is the game design.
+- Use `weekStartsOn: 1` by default. Set another value only when the game design specifies it.
+- Call `time.tick()` from one central game lifecycle point, especially after app resume. `startPolling()` is available for non-Phaser/browser pages; never start multiple pollers.
+- Subscribe to `new-day`, `new-week`, `new-month`, or `onEveryMinutes(n)` for reset work. Subscribe before calling the first tick if the current session must observe a crossing.
+- Boundary events report the previous and current calendar keys. They indicate that a boundary was crossed, not that every missed reward should be granted. Persistent services must calculate eligibility from saved state and use idempotent transaction IDs.
+- Use `ServerTimeSource.sync()` at boot and resume once a server is available. Keep gameplay API on `TimeService`; do not scatter `Date.now()` through Daily Login, shops, cooldowns, or UI.
+
+## Events
+
+`DefaultTimeService` can optionally forward typed global events through `GameEventMap`:
+
+- `time:new-minute`, `time:new-hour`, `time:new-day`, `time:new-week`, `time:new-month`
+- `time:interval` for each configured custom minute interval
+
+Dispose the service, or stop polling, when the app lifetime ends. Do not let individual Phaser scenes own the service; scenes only subscribe and unsubscribe during their own lifecycle.

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

@@ -0,0 +1,161 @@
+---
+name: phaser-ui-motion
+description: >-
+  Factory Phaser UI feeling/motion for buttons, toggles, popups, sliders (default
+  feeling for pcgf-ui-reskin). MUST keep press until release (even after drag-off);
+  MUST finish press on window pointerup when release is outside the Phaser
+  canvas/letterbox (stuck scale bug). Never reset on pointerout. Use
+  bindButtonMotion + setPointerCapture + scene POINTER_UP + window pointerup.
+  UI click/close sounds → phaser-ui-sfx (call only). Full UI reskin → pcgf-ui-reskin.
+  Triggers: button press stuck, thả ngoài canvas, letterbox, scale kẹt,
+  Settings/Next Level press, slider drag off-track. Read fix-off-canvas-press.md
+  when fixing off-canvas release.
+---
+
+# Phaser UI Motion
+
+Use `templates/motion` (scaffold → `src/factory/motion/`) and `templates/ui/` (scaffold → `src/factory/ui/`). Preserve semantic UI state outside the tween; motion only presents it.
+
+## STOP — stuck press after release outside canvas
+
+If the user reports: press → drag far → **thả ngoài canvas / letterbox** → button tween/scale kẹt:
+
+1. **Read and follow** [fix-off-canvas-press.md](fix-off-canvas-press.md) **before writing code**.
+2. Do **not** invent a new press helper.
+3. Grep the game’s `phaser-ui-motion.ts` for `finishFromWindow`. If missing → **replace the whole file** from plugin `templates/motion/phaser-ui-motion.ts`.
+4. Grep for hand-rolled `pointerout` + `setScale` / clear press → **delete** those handlers; use `bindButtonMotion` only.
+5. DOM cream buttons: call `bindFactoryDomPress()`; its file **must** use `window.addEventListener('pointerup'`.
+
+## NEVER / ALWAYS — press scale (anti-regression)
+
+Game Settings / Next Level regressed twice. Do **not** “fix” this again with the wrong model.
+
+| ALWAYS | NEVER |
+| --- | --- |
+| Call `bindButtonMotion` from `templates/motion/phaser-ui-motion.ts` | Hand-roll `pointerover` / `pointerdown` / `pointerup` scale tweens |
+| Keep **press scale** while the pointer is held, including after drag **outside** the hit | Reset / tween to `1` on `pointerout` while still held |
+| Clear press on hit up / scene `POINTER_UP` / **`window` `pointerup`** (off-canvas) | Assume scene up alone covers letterbox release |
+| File contains **`finishFromWindow`** + `window.addEventListener('pointerup', finishFromWindow, true)` | Ship an old motion.ts without the window safety net |
+| `canvas.setPointerCapture` on down; release capture on finish | Clear press to “match CSS `:active` ending on leave” |
+| DOM cream: **`bindFactoryDomPress`** (`theme-cream-casual`) | Hand-roll DOM `pointerout` → clear press |
+| Accept click only if release is inside **unscaled** hit bounds | Accept on `pointerdown` or on leave |
+| Remove scene + **window** listeners in `destroy` | Leave press scale stuck after scene teardown |
+
+**Golden reference:** DOM Settings **close** + canonical `bindButtonMotion` (includes `finishFromWindow`).
+
+**Wrong “fix”:** clearing press on `pointerout` “like CSS `:active`”, or only listening to Phaser `POINTER_UP` (misses off-canvas release).
+
+## Hard rule — never invent parallel motion helpers
+
+**Root cause of missing button feeling:** call sites used ad-hoc hover (`wirePhaserButtonHover` / raw `pointerup` scale) or no motion, instead of `bindButtonMotion`.
+
+**Root cause of stuck scale after release outside canvas:** Phaser never gets `POINTER_UP` off-canvas; local `phaser-ui-motion.ts` missing `finishFromWindow` / window listener; or hand-rolled press without window up.
+
+| Reference that is correct | Why |
+| --- | --- |
+| Canonical `bindButtonMotion` + `finishFromWindow` | Window `pointerup` clears press when release is in the letterbox |
+| Settings popup **close** (DOM) + `bindFactoryDomPress` | Capture + window up for HTML chrome |
+
+**Required Phaser UX:**
+
+1. `pointerdown` → press scale + canvas `setPointerCapture`.
+2. Drag outside hit while held → **keep** press scale (no clear on `pointerout`).
+3. `pointerup` anywhere (hit / scene / **window**) → scale to `1`.
+4. Accept click only if release is over **unscaled** hit when still meaningful; off-canvas release → **reset only**, never `onAccepted`.
+
+Before shipping any Phaser UI control:
+
+| Control | Must use | Must not |
+| --- | --- | --- |
+| Button / icon / pill / close × | `bindButtonMotion` (file with `finishFromWindow`) | `pointerout` clear while held; motion.ts without window up |
+| Popup / modal panel | `tweenPopup` + dim-only dismiss + panel sink | Dismiss on panel chrome taps |
+| Volume / settings slider | `createSlider` + capture + scene move/up + **window up** | Track-only `pointermove` |
+| Loading / XP bar | XP helper or `createSlider` (`interactive: false`); paint Δ ≥ 1% | Per-frame clear; tween across level caps |
+
+Graphics chrome: pass hit `Rectangle` as `background`, `scaleTarget: buttonContainer`.
+
+## NEVER / ALWAYS — slider drag (anti-regression)
+
+| ALWAYS | NEVER |
+| --- | --- |
+| `createSlider` from `templates/motion` | Hand-roll track `pointermove` only |
+| `setPointerCapture` on down | Assume thin track keeps move after leave |
+| Scene `POINTER_MOVE` + `POINTER_UP` + **window `pointerup`** | Only GameObject up events |
+| Clamp progress 0–1 | Negative / overflow fill width |
+| `destroy()` removes scene **and window** listeners | Leak listeners after popup close |
+
+### Manual check — slider
+
+1. Press track → click SFX; small move → drag (instant fill).
+2. Drag outside track while held → fill keeps updating.
+3. Release outside canvas → drag ends cleanly; no stuck capture.
+4. Tap without drag → tween seek.
+
+## Button press / release contract (required)
+
+`bindButtonMotion` in `templates/motion/phaser-ui-motion.ts`:
+
+1. `pointerdown` → `activePointerId`, scale `pressScale`, canvas `setPointerCapture`.
+2. `pointerout` while held → **no** scale change.
+3. `pointerout` while idle → idle scale `1`.
+4. Finish on hit `pointerup` / `pointerupoutside`, scene `POINTER_UP`, and **`finishFromWindow`** (`window` `pointerup` / `pointercancel`).
+5. `destroy` removes scene + window listeners, releases capture, `killTweens`, `setScale(1)`.
+
+Do **not** reimplement Settings / Next Level with raw `pointerup`.
+
+### Manual check — Phaser button
+
+1. Press → scale shrinks.
+2. Drag outside button, still inside canvas, held → stays pressed.
+3. Release outside button → scale `1`, no click.
+4. Press + release inside → click + SFX once.
+5. Press → drag into **letterbox outside canvas** → release → scale `1` (not stuck).
+6. Repeat quickly — never stuck at `0.9`.
+
+## Shared UI sounds (call only — do not author here)
+
+UI click/close files, creation, and playback helpers live in skill **`phaser-ui-sfx`**
+(`templates/ui/ui-sfx.ts`, plugin `assets/sfx/`).
+
+This feeling skill **only wires** `onClickSound` / `onCloseSound` to `playUiClick` /
+`playUiClose`. Full interaction → sound table and replace-sound workflow → **`phaser-ui-sfx`**.
+Full reskin (theme + pack + feeling + SFX) → navigator **`pcgf-ui-reskin`**.
+
+## Settings popup (Home + Game = one modal)
+
+- Source: `templates/ui/settings-popup-dom.ts` + `audio-settings.ts`.
+- Wire `bindDomSettingsPopup`; Game opens via `getDomSettingsPopup()?.open({ showHome: true })`.
+- Dim-only dismiss; panel open `Back.out`, close `Expo.out`.
+- SFX hooks → **`phaser-ui-sfx`**.
+
+## Popup dismiss contract
+
+- Dismiss only on close ×, dismiss CTA, or dim outside panel.
+- Phaser: `panelSink` under children; DOM: `event.target === backdrop`.
+
+## Motion contracts
+
+- `bindButtonMotion`: must include `finishFromWindow`.
+- `tweenPopup` — open `Back.out`, close `Expo.out`.
+- `createSlider`: window up for off-canvas end.
+- Cream DOM: skill **`theme-cream-casual`** + `bindFactoryDomPress`.
+
+```ts
+import { bindButtonMotion, createSlider } from '../factory/motion';
+import { playUiClick } from '../factory/ui/ui-sfx';
+
+bindButtonMotion(scene, hit, hit, {
+  scaleTarget: buttonRoot,
+  onClickSound: () => playUiClick(),
+  onAccepted: () => { /* … */ },
+});
+```
+
+## Additional resources
+
+- **Off-canvas stuck press playbook (read first when fixing):** [fix-off-canvas-press.md](fix-off-canvas-press.md)
+- Cream DOM + `box-shadow: none`: skill **`theme-cream-casual`**
+- UI SFX contract / files: skill **`phaser-ui-sfx`**
+- Full UI reskin navigator: skill **`pcgf-ui-reskin`**
+
+For cover/reveal transitions → `phaser-loading-view`.

package/plugins/phaser-casual-game-factory/skills/phaser-ui-motion/fix-off-canvas-press.md

@@ -0,0 +1,198 @@
+# Fix: press tween stuck when release is outside the canvas
+
+**Symptom (user):** Press a button → drag far → release **outside the Phaser canvas** (letterbox / black bars / beside the phone frame) → button scale/shadow **stays pressed** or tween looks broken.
+
+**Also triggers this skill when user says:** thả ngoài canvas, stuck press, scale kẹt, letterbox release, drag off canvas.
+
+Do **not** invent a new helper. Follow this playbook exactly.
+
+---
+
+## Step 0 — Pick the stack (30 seconds)
+
+| UI lives in… | Fix path |
+|--------------|----------|
+| HTML buttons (Home / Settings / cream) | **A — DOM** below |
+| Phaser GameObjects (Game Settings, Next Level, pills) | **B — Phaser** below |
+| Both | Do **A and B** |
+
+---
+
+## A — DOM cream buttons
+
+### A1. Audit (run these searches in the game repo)
+
+```text
+pointerout
+mouseleave
+is-pressed
+bindFactoryDomPress
+factory-cream-casual.css
+```
+
+**Fail if any of these are true:**
+
+- Custom `pointerout` / `mouseleave` clears scale, shadow, or a press class
+- No `bindFactoryDomPress` import/call in bootstrap / main / home entry
+- `factory-cream-casual.css` missing `box-shadow: none` on `:active` / `.is-pressed`
+- Local `bind-factory-dom-press.ts` has **no** `window.addEventListener('pointerup'`
+
+### A2. Patch (required)
+
+1. Refresh plugin templates if needed:
+
+```bash
+npx --yes --package=git+ssh://git@git.skylinkmedia.asia:h5-game/unityhn/plugin-casual-game-factory.git pcgf install --yes --no-scaffold
+```
+
+2. Ensure these files exist (scaffold paths):
+
+- `src/factory/ui/factory-cream-casual.css`
+- `src/factory/ui/bind-factory-dom-press.ts`
+
+3. Main CSS (order matters):
+
+```css
+@import "./factory/ui/factory-cream-casual.css";
+```
+
+4. HTML root:
+
+```html
+<body class="factory-page">
+```
+
+5. Bootstrap **once** after DOM ready (same file that starts the game / Home):
+
+```ts
+import { bindFactoryDomPress } from './factory/ui/bind-factory-dom-press';
+// or: from './factory/ui'
+
+bindFactoryDomPress();
+```
+
+6. **Delete** any hand-rolled DOM press code that does:
+
+```ts
+// FORBIDDEN — causes stuck / wrong press when leaving the button
+el.addEventListener('pointerout', () => { el.style.transform = ''; /* or remove class */ });
+el.addEventListener('mouseleave', () => { /* clear press */ });
+```
+
+### A3. Required lines inside `bind-factory-dom-press.ts`
+
+The file **MUST** contain (grep must find):
+
+```ts
+window.addEventListener('pointerup', onPointerUp, true);
+window.addEventListener('pointercancel', onPointerUp, true);
+```
+
+If the local copy only listens on `document` / root and **not** `window`, **replace the whole file** from the plugin template `templates/ui/bind-factory-dom-press.ts`.
+
+### A4. Verify
+
+1. Press HTML button → hard shadow **off**, face sinks.
+2. Drag into letterbox / outside canvas → release → idle restored (no stuck `.is-pressed`).
+3. DevTools: while held, element has class `is-pressed`; after off-canvas release, class is gone.
+
+---
+
+## B — Phaser buttons (`bindButtonMotion`)
+
+### B1. Audit
+
+```text
+bindButtonMotion
+pointerout
+setScale
+POINTER_UP
+finishFromWindow
+wirePhaserButtonHover
+```
+
+**Fail if:**
+
+- Scene wires `pointerover` / `pointerdown` / `pointerup` scale **without** `bindButtonMotion`
+- `pointerout` resets scale while a press may still be held
+- `src/factory/motion/phaser-ui-motion.ts` has **no** `finishFromWindow` and **no** `window.addEventListener('pointerup'`
+- Call site uses deprecated `wirePhaserButtonHover` only (ok only if it delegates to `bindButtonMotion`)
+
+### B2. Patch (required)
+
+1. Same `pcgf install --yes --no-scaffold` as above.
+
+2. **Replace** local motion file from plugin if stale:
+
+- Plugin: `templates/motion/phaser-ui-motion.ts`
+- Game: `src/factory/motion/phaser-ui-motion.ts`
+
+Grep the game file — **must** find:
+
+```ts
+finishFromWindow
+window.addEventListener('pointerup', finishFromWindow, true);
+window.addEventListener('pointercancel', finishFromWindow, true);
+```
+
+If missing → copy the plugin file over the local one. Do **not** “patch by memory”.
+
+3. Every interactive Phaser control:
+
+```ts
+import { bindButtonMotion } from '../factory/motion'; // or templates/motion
+
+bindButtonMotion(scene, hitRect, hitRect, {
+  scaleTarget: buttonContainer, // when chrome is Container / Graphics
+  onClickSound: () => playUiClick(scene),
+  onAccepted: () => { /* action */ },
+});
+```
+
+4. **Remove** parallel helpers, e.g.:
+
+```ts
+// FORBIDDEN
+hit.on('pointerout', () => scaleTo(1));
+hit.on('pointerdown', () => scaleTo(0.9));
+hit.on('pointerup', () => scaleTo(1));
+```
+
+### B3. Why window listener is mandatory
+
+| Release location | What fires |
+|------------------|------------|
+| Inside canvas, on button | hit `pointerup` / scene `POINTER_UP` |
+| Inside canvas, off button | `pointerupoutside` / scene `POINTER_UP` |
+| **Outside canvas (letterbox)** | **Often nothing in Phaser** → need **`window` `pointerup`** |
+
+`setPointerCapture` on the canvas helps but is **not enough alone** on all browsers / letterbox layouts. Canonical `bindButtonMotion` ends the gesture in `finishFromWindow`.
+
+### B4. Verify
+
+1. Game Settings / Next Level / any pill: press → scale down.
+2. Drag to **black letterbox outside the game canvas** → release → scale back to `1` within ~150ms.
+3. No click/SFX when release was outside the unscaled hit.
+4. Repeat 5 times quickly — never stuck at `0.9`.
+
+---
+
+## C — Sliders (same off-canvas class of bugs)
+
+`createSlider` in the same `phaser-ui-motion.ts` **must** also have:
+
+```ts
+window.addEventListener('pointerup', endFromWindow, true);
+```
+
+If drag dies or capture sticks after release outside canvas, replace the motion file from the plugin (same as B2).
+
+---
+
+## Do not ship until
+
+- [ ] DOM: `bindFactoryDomPress()` called; file has `window` `pointerup`
+- [ ] Phaser: all buttons use `bindButtonMotion`; file has `finishFromWindow`
+- [ ] No `pointerout` → clear press while held
+- [ ] Manual test: release **outside canvas** restores idle
+- [ ] Cream press CSS still has `box-shadow: none !important` on `:active` / `.is-pressed`

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

@@ -0,0 +1,83 @@
+---
+name: phaser-ui-sfx
+description: >-
+  Own Phaser Casual Game Factory shared UI sounds: one click + one close API,
+  default MP3s in assets/sfx, HTMLAudio clone playback scaled by audio-settings
+  SFX volume. Use when adding/replacing UI click/close sounds, silent buttons, or
+  splitting audio from phaser-ui-motion. Triggers: UI SFX, ui_click, ui_close,
+  âm thanh nút, click sound, close sound. Create/replace sound files here — feeling
+  skills only call the play APIs. Default pack for pcgf-ui-reskin SFX lane.
+---
+
+# Phaser UI SFX
+
+Canonical UI audio for Factory games. **Feeling** (`phaser-ui-motion`) calls these
+APIs; it does **not** own sound files or generation.
+
+**Default files (plugin):** `assets/sfx/ui_click.mp3`, `assets/sfx/ui_close.mp3`  
+**Game public paths:** `/assets/sfx/ui_click.mp3`, `/assets/sfx/ui_close.mp3`  
+**Template module:** `templates/ui/ui-sfx.ts` (scaffold → prefer `src/factory/ui/ui-sfx.ts`)  
+**Volume:** `templates/ui/audio-settings.ts` → `getSfxVolume()`
+
+## Contract (mandatory)
+
+Route all Factory UI audio through **one click** and **one close** API, scaled by persisted SFX volume.
+
+| Interaction | Sound |
+| --- | --- |
+| Action button (Play, Next Level, Home, tabs, shop cards, …) | **click** |
+| Close × / `data-close-popup` / modal dim (backdrop) dismiss | **close** |
+| Settings slider pointer-down (click or start of drag) | **click** |
+| Opening a popup | none (or game-specific); do not use close |
+| Action that also dismisses (e.g. Home inside settings) | **click** only — then close the panel **silently** |
+
+**Playback:** prefer HTMLAudio `cloneNode` (`playUiClick` / `playUiClose`). Do not assume Phaser `cache.audio` alone in hybrid DOM/Phaser demos.
+
+```ts
+import { playUiClick, playUiClose, preloadUiAudio } from '../factory/ui/ui-sfx';
+
+preloadUiAudio(scene);
+bindButtonMotion(scene, hit, hit, {
+  onClickSound: () => playUiClick(),
+  onAccepted: () => { /* … */ },
+});
+```
+
+## Install / refresh defaults
+
+1. Copy plugin `assets/sfx/ui_click.mp3` + `ui_close.mp3` → game `public/assets/sfx/`.
+2. Copy or scaffold `templates/ui/ui-sfx.ts` (+ keep using `audio-settings.ts`).
+3. Wire `onClickSound` / `onCloseSound` from motion + settings popup to these helpers.
+4. Respect mute / SFX slider; unlock / warm players after first user gesture.
+
+## Create or replace sounds
+
+When the user wants **new** UI SFX (not the default MP3s):
+
+1. Stay in this skill (or a future registered SFX skill under `pcgf-ui-reskin`).
+2. Keep the same filenames **or** update both files + all callers together.
+3. Put candidates next to a small compare note / audio links in the reskin `compare.html` when doing a full UI reskin.
+4. Do **not** invent a second click/close pair beside `playUiClick` / `playUiClose`.
+
+Future SFX generators register in `pcgf-ui-reskin` → SFX registry; this skill remains the default consumer contract.
+
+## Settings volume UI
+
+- Source: `templates/ui/settings-popup-dom.ts` + `audio-settings.ts`.
+- Slider pointer-down → `playUiClick()`; × / dim → `playUiClose()`.
+- Motion/feeling owns slider **tweens**; this skill owns **what** plays.
+
+## NEVER / ALWAYS
+
+| ALWAYS | NEVER |
+| --- | --- |
+| One click + one close API | Parallel `playButton` / ad-hoc Audio elements per control |
+| Scale by `getSfxVolume()` | Ignore mute / SFX slider |
+| Ship files under `/assets/sfx/` | Rely only on Phaser cache in hybrid UI |
+| Own file creation/replacement here | Bury new SFX authorship inside `phaser-ui-motion` |
+
+## Related
+
+- Feeling callers: **`phaser-ui-motion`**
+- Reskin navigator: **`pcgf-ui-reskin`**
+- Cream DOM press (no audio): **`theme-cream-casual`**