@playcraft/cli 0.1.54 → 0.1.56-beta

package/project-template-v2/.claude/skills/playcraft-vfx-animation/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: playcraft-vfx-animation
+description: VFX 特效与动画精灵图选型决策树与核心命令速查。按游戏事件快速选定预设，详细预设目录见 refs/ta-vfx-preset-catalog.md。
+triggers: VFX,特效,动画,animate,animation,use-vfx,精灵动画,sprite animation,爆炸特效,闪光效果,vfx预设,animate预设,bounce,spin,pulse,shake,float,blink,swing,wobble,flip,confetti,sparkle,explosion,starburst,smoke,glow,impact
+---
+
+# PlayCraft VFX 特效与动画精灵图生成指南
+
+## 0. Overview
+
+VFX（视觉特效精灵图）和 animate（运动动画精灵图）是可玩广告视觉品质的关键层。它们属于 TA 工作流的 **Stage B**（精灵图处理阶段），在 Stage A 元素生成完成后执行。
+
+- **VFX**：预制粒子/爆炸/光效精灵表，用于游戏事件反馈（消除、得分、胜利等）
+- **animate**：将静态素材转为循环动画精灵表，用于 idle 状态、UI 引导、装饰运动
+
+**发现可用预设**：
+
+```bash
+playcraft image list-vfx            # 列出所有 VFX 预设（含帧数、体积）
+playcraft image animate --list-presets  # 列出所有 animate 预设
+```
+
+## 1. VFX 选型决策树
+
+按游戏事件选择预设：
+
+```
+需要为哪种游戏事件添加 VFX？
++-- 元素消除/击破 -> explosion_small (8帧, ~30KB)
+|   理由: 中心爆发+碎片扩散, 8帧在视觉冲击与体积间取得平衡
++-- 得分/收集奖励 -> sparkle (6帧, ~15KB)
+|   理由: 轻量粒子迸发, 15KB 可高频触发而不累积体积压力
++-- 关卡完成/大胜利 -> confetti (12帧, ~25KB)
+|   理由: 多彩纸片飘落, 12帧保证庆祝感的持续时长
++-- 连击触发/特殊技能 -> starburst (8帧, ~20KB)
+|   理由: 金色放射线条, 视觉冲击强且不遮挡游戏元素
++-- 元素消失/冲刺残影 -> smoke (8帧, ~20KB)
+|   理由: 烟雾自然消散, 柔和过渡不抢视觉焦点
++-- 元素高亮/选中状态 -> glow (6帧, ~10KB)
+|   理由: 最小体积, 适合持续循环播放(选中状态)
++-- 落地/点击反馈 -> impact_ring (6帧, ~15KB)
+|   理由: 快速扩散环, 6帧短促匹配瞬时反馈的时间尺度
++-- 金币/货币拾取 -> coin_collect (8帧, ~20KB)
+    理由: 专用金色闪光发散, 与通用 sparkle 区分货币语义
+```
+
+## 2. Animate 选型决策树
+
+按运动需求选择预设：
+
+```
+需要什么运动效果？
++-- 引起注意(CTA/重要按钮) -> pulse (缩放脉冲, 周期1.5-2s)
+|   理由: 缩放振荡是最有效的注意力引导, 不依赖位移空间
++-- 持续旋转(加载/转盘/金币) -> spin (X轴缩放模拟Y轴旋转)
+|   理由: 2D压缩模拟3D翻转, 适合圆形/对称元素
++-- 弹跳反馈(点击/收集/idle) -> bounce (Y轴正弦平移)
+|   理由: 最自然的"活着"感, 适用面最广
++-- 错误/警告/受击 -> shake (随机小幅XY偏移)
+|   理由: 随机位移制造紧张感, 强制引导注意力
++-- 悬浮装饰(idle/魔法道具) -> float (轻柔漂浮+微旋转)
+|   理由: 比bounce更轻柔, 加入+-3度旋转增添神秘感
++-- 闪烁提示(光标/倒计时) -> blink (不透明度振荡)
+|   理由: 最简单的"请注意我"动画, 最小视觉干扰
++-- 钟摆装饰(悬挂物/灯笼) -> swing (绕顶部中心摆动)
+|   理由: 物理感强, 专为"挂着"的元素设计
++-- 可爱/卡通idle(果冻/气泡) -> wobble (左右交替小幅旋转)
+|   理由: +-5-10度交替旋转产生弹性感, 适合软体元素
++-- 卡牌翻转/3D旋转 -> flip (需要正面+背面两张素材)
+    理由: 完整正面->过渡->背面翻转; 详见 ta-3d-flip-recipe.md
+```
+
+## 3. Core Commands
+
+### use-vfx 完整示例
+
+```bash
+playcraft image use-vfx \
+  --preset explosion_small \   # 预设名(必填), 从决策树选定
+  --tint "#FF6B35" \           # 颜色叠加(可选), hex格式, 按元素颜色调整
+  --scale 1.2 \                # 缩放(可选, 默认1.0), 范围0.5-3.0
+  --output assets/images/vfx/tile_break.png  # 输出路径(必填)
+```
+
+| 参数       | 类型   | 默认值     | 说明                 |
+| ---------- | ------ | ---------- | -------------------- |
+| `--preset` | string | 必填       | VFX 预设名           |
+| `--output` | string | 必填       | 输出精灵表路径(.png) |
+| `--tint`   | hex    | 预设默认色 | 颜色叠加 `#RRGGBB`   |
+| `--scale`  | number | 1.0        | 整体缩放(0.5-3.0)    |
+
+### animate 完整示例
+
+```bash
+playcraft image animate \
+  --input assets/images/ui/cta_button.png \  # 输入静态素材(必填)
+  --preset pulse \             # 动画预设(默认bounce)
+  --frames 8 \                 # 总帧数(2-64, 默认8)
+  --columns 4 \                # 精灵表列数(默认4)
+  --output assets/images/ui/cta_button_pulse.png  # 输出路径(必填)
+```
+
+| 参数        | 类型   | 默认值 | 说明                    |
+| ----------- | ------ | ------ | ----------------------- |
+| `--input`   | string | 必填   | 输入图片路径            |
+| `--output`  | string | 必填   | 输出精灵表路径(.png)    |
+| `--preset`  | string | bounce | 动画预设名              |
+| `--frames`  | number | 8      | 总帧数(2-64)            |
+| `--columns` | number | 4      | 精灵表列数              |
+| `--back`    | string | 无     | flip 专用: 背面图片路径 |
+
+## 4. Post-Generation Checklist
+
+| 检查项             | 方法                               | 不通过时                     |
+| ------------------ | ---------------------------------- | ---------------------------- |
+| 帧数与预设规格匹配 | 计算精灵表格子数 = 行x列           | 重新生成, 检查 --frames 参数 |
+| 精灵表尺寸合理     | 单帧 <= 256x256, 总图 <= 1024px 宽 | 降低 --scale 或减少帧数      |
+| 文件体积在预算内   | VFX 总计 <= 150KB                  | 减少预设数量或降帧           |
+| 记录到 ta-log.md   | grid 参数(帧数/列数/单帧尺寸)      | 补写, Developer 需要此信息   |
+
+## 5. Detailed Reference
+
+完整预设目录与组合配方见 `refs/ta-vfx-preset-catalog.md`，包含：
+
+- 每个 VFX 预设的完整详解（动画感描述、Tint 建议、Scale 建议、典型错误）
+- 每个 animate 预设的完整详解（参数建议、最佳用途、典型错误）
+- 按游戏类型的 VFX + 动画组合配方（Match-3 / 跑酷 / 卡牌 / 泡泡射击）
+- flip 工作流详情
+- 自定义帧数决策指南与非均匀帧时长技巧
+- 体积预算分配参考

package/project-template-v2/.claude/skills/playcraft-workspace-assets/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: playcraft-workspace-assets
+description: Use when finding or downloading shared library assets, or creating and managing durable image, audio, sprite, animation, model, or video generation tasks in a PlayCraft cloud workspace.
+compatibility: agent,opencode
+version: 1.0.0
+surfaces:
+  - sandbox-agent
+---
+
+# 工作区素材工作流
+
+使用 PlayCraft CLI (Command Line Interface, 命令行界面) 的 `library` 和 `assets` 命令。运行对应子命令的 `--help` 核对参数；当前命令行缺少这些入口时，先报告需要匹配的命令行与服务版本。凭据由工作区提供。
+
+## 查找并复用素材
+
+```bash
+playcraft library search "角色" --type texture --tags character --limit 20 --json
+playcraft library facets --json
+playcraft library get <assetId> --json
+playcraft library files <assetId> --json
+playcraft library download <assetId> --output ./assets/character
+```
+
+检索字段是名称、素材库路径和标签；还可按分类、子分类、团队和分页筛选。使用检索结果返回的素材库编号，与 `tools list-assets` 的项目资产编号分别处理。不要把下载预览图当作完整素材包。
+
+`--output` 对单文件表示文件路径，对素材包表示目录；`--output-dir` 始终表示目录。目标路径必须尚不存在。素材包包含清单、嵌套目录和模型贴图等依赖，下载后保留其相对路径。用户要求修改已有素材时，先下载到新路径并核对，再按用户要求替换。
+
+## 创建持久化生成任务
+
+从 `references/requests.json` 选取所需类型的示例，将**单个请求对象**写入工程内的请求文件，并改成完整的用户需求。六种类型分别为 `image`、`audio`、`sprite`、`animation`、`model`、`video`。请求使用 JSON (JavaScript Object Notation, 数据交换格式)；参考图需同时提供 `referenceImageBase64` 和对应 `referenceImageMimeType`。模型参数以可用配置和共享契约为准。
+
+```bash
+playcraft assets estimate --request .tmp/asset-request.json
+playcraft assets generate --request .tmp/asset-request.json --client-request-id <stable-request-id>
+playcraft assets get <taskId>
+playcraft assets wait <taskId> --timeout 1800
+playcraft assets download <taskId> --output ./assets/generated-result
+```
+
+同一次生成保持 `--client-request-id` 和请求内容不变。提交结果不确定时重用原请求；拿到 `taskId` 后用 `get` 或 `wait` 恢复，不能新建任务来代替查状态。新候选使用新请求编号。`--wait --output <path>` 可合并等待和下载。
+
+命令在当前工程推断工作区和工程目录；工程外须传 `--workspace <workspaceId> --directory <directoryName>`，范围应对应目标工程。`tasks` 列出该范围任务；`cancel <taskId>` 请求取消，上游已提交请求可能继续结算。等待超时返回退出状态 75，远端任务仍可查询。
+
+下载前任务应为 `awaiting_adoption` 或 `saved`。精灵图与动画输出为完整包目录，下载会校验各文件大小与内容摘要。`queued` 和 `running` 只表示任务尚未完成；`failed`、`cancelled`、`interrupted` 应根据真实状态汇报。
+
+## 结果保存和动画版本
+
+- 生成结果保存到共享素材库：先 `assets library-targets` 获取允许的目的地，再通过 `assets library-save <taskId> --request <save-request.json>` 保存。用 `library-saves <taskId>` 查看状态，失败时 `library-retry <taskId> --save-id <saveId>` 沿用原保存任务。请求字段以命令帮助和 `asset-library-save` 共享契约为准。
+- 动画编辑：`assets animation get <taskId>` 读取草稿及修订号，`draft`、`upload-frame`、`version` 使用请求文件更新草稿、替换帧和导出版本。草稿写入结果不确定时先重新读取草稿修订号。
+- 指定动画版本下载：`assets download <taskId> --version <versionId> --output <new-directory>`。
+- `assets saved` 和 `assets animation saved` 需要已有的平台写入回执，不能用普通本地下载路径声明已经采纳。
+
+工作素材写入工程的 `assets/`，请求与回执放在 `dist/` 外。最终交付使用工程根目录 `dist/`，包内依赖一起交付。单张图片的直接生成仍可用 `tools generate-image`；裁剪、分割、分层及九宫格分析使用 `image` 子命令，先查看各自帮助。

package/project-template-v2/.claude/skills/playcraft-workspace-assets/references/requests.json

@@ -0,0 +1,32 @@
+{
+  "image": { "kind": "image", "prompt": "A transparent game character", "removeBackground": true },
+  "audio": { "kind": "audio", "category": "sfx", "description": "A short bright reward chime" },
+  "sprite": {
+    "kind": "sprite",
+    "prompt": "A character walking sequence",
+    "frameCount": 8,
+    "frameWidth": 256,
+    "frameHeight": 256,
+    "columns": 4,
+    "fps": 12
+  },
+  "animation": {
+    "kind": "animation",
+    "prompt": "A character waving in a loop",
+    "frameCount": 8,
+    "frameWidth": 256,
+    "frameHeight": 256,
+    "columns": 4,
+    "fps": 12
+  },
+  "model": { "kind": "model", "mode": "text", "prompt": "A low polygon treasure chest" },
+  "video": {
+    "kind": "video",
+    "mode": "text",
+    "prompt": "A treasure chest opening",
+    "duration": 5,
+    "aspectRatio": "16:9",
+    "resolution": "720P",
+    "audio": false
+  }
+}

package/project-template-v2/.claude/skills/playwright-cli/SKILL.md

@@ -0,0 +1,390 @@
+---
+name: playwright-cli
+description: Automate browser interactions, test web pages and work with Playwright tests.
+allowed-tools: Bash(playwright-cli:*) Bash(npx:*) Bash(npm:*)
+---
+
+# Browser Automation with playwright-cli
+
+## Quick start
+
+```bash
+# open new browser
+playwright-cli open
+# navigate to a page
+playwright-cli goto https://playwright.dev
+# interact with the page using refs from the snapshot
+playwright-cli click e15
+playwright-cli type "page.click"
+playwright-cli press Enter
+# take a screenshot (rarely used, as snapshot is more common)
+playwright-cli screenshot
+# close the browser
+playwright-cli close
+```
+
+## Commands
+
+### Core
+
+```bash
+playwright-cli open
+# open and navigate right away
+playwright-cli open https://example.com/
+playwright-cli goto https://playwright.dev
+playwright-cli type "search query"
+playwright-cli click e3
+playwright-cli dblclick e7
+# --submit presses Enter after filling the element
+playwright-cli fill e5 "user@example.com"  --submit
+playwright-cli drag e2 e8
+# drop files or data onto an element (from outside the page)
+playwright-cli drop e4 --path=./image.png
+playwright-cli drop e4 --data="text/plain=hello world"
+playwright-cli hover e4
+playwright-cli select e9 "option-value"
+playwright-cli upload ./document.pdf
+playwright-cli check e12
+playwright-cli uncheck e12
+playwright-cli snapshot
+playwright-cli eval "document.title"
+playwright-cli eval "el => el.textContent" e5
+# get element id, class, or any attribute not visible in the snapshot
+playwright-cli eval "el => el.id" e5
+playwright-cli eval "el => el.getAttribute('data-testid')" e5
+playwright-cli dialog-accept
+playwright-cli dialog-accept "confirmation text"
+playwright-cli dialog-dismiss
+playwright-cli resize 1920 1080
+playwright-cli close
+```
+
+### Navigation
+
+```bash
+playwright-cli go-back
+playwright-cli go-forward
+playwright-cli reload
+```
+
+### Keyboard
+
+```bash
+playwright-cli press Enter
+playwright-cli press ArrowDown
+playwright-cli keydown Shift
+playwright-cli keyup Shift
+```
+
+### Mouse
+
+```bash
+playwright-cli mousemove 150 300
+playwright-cli mousedown
+playwright-cli mousedown right
+playwright-cli mouseup
+playwright-cli mouseup right
+playwright-cli mousewheel 0 100
+```
+
+### Save as
+
+```bash
+playwright-cli screenshot
+playwright-cli screenshot e5
+playwright-cli screenshot --filename=page.png
+playwright-cli pdf --filename=page.pdf
+```
+
+### Tabs
+
+```bash
+playwright-cli tab-list
+playwright-cli tab-new
+playwright-cli tab-new https://example.com/page
+playwright-cli tab-close
+playwright-cli tab-close 2
+playwright-cli tab-select 0
+```
+
+### Storage
+
+```bash
+playwright-cli state-save
+playwright-cli state-save auth.json
+playwright-cli state-load auth.json
+
+# Cookies
+playwright-cli cookie-list
+playwright-cli cookie-list --domain=example.com
+playwright-cli cookie-get session_id
+playwright-cli cookie-set session_id abc123
+playwright-cli cookie-set session_id abc123 --domain=example.com --httpOnly --secure
+playwright-cli cookie-delete session_id
+playwright-cli cookie-clear
+
+# LocalStorage
+playwright-cli localstorage-list
+playwright-cli localstorage-get theme
+playwright-cli localstorage-set theme dark
+playwright-cli localstorage-delete theme
+playwright-cli localstorage-clear
+
+# SessionStorage
+playwright-cli sessionstorage-list
+playwright-cli sessionstorage-get step
+playwright-cli sessionstorage-set step 3
+playwright-cli sessionstorage-delete step
+playwright-cli sessionstorage-clear
+```
+
+### Network
+
+```bash
+playwright-cli route "**/*.jpg" --status=404
+playwright-cli route "https://api.example.com/**" --body='{"mock": true}'
+playwright-cli route-list
+playwright-cli unroute "**/*.jpg"
+playwright-cli unroute
+```
+
+### DevTools
+
+```bash
+playwright-cli console
+playwright-cli console warning
+playwright-cli requests
+playwright-cli request 5
+playwright-cli run-code "async page => await page.context().grantPermissions(['geolocation'])"
+playwright-cli run-code --filename=script.js
+playwright-cli tracing-start
+playwright-cli tracing-stop
+playwright-cli video-start video.webm
+playwright-cli video-chapter "Chapter Title" --description="Details" --duration=2000
+playwright-cli video-stop
+
+# launch the dashboard for UI review / design feedback — user annotates the page, you receive the annotated screenshot, snapshot, and notes
+playwright-cli show --annotate
+
+# generate a Playwright locator for an element from its ref or selector
+playwright-cli generate-locator e5 --raw
+
+# show a persistent highlight overlay for an element, optionally with a custom style
+playwright-cli highlight e5
+playwright-cli highlight e5 --style="outline: 3px dashed red"
+# hide a single element highlight, or all page highlights when no target is given
+playwright-cli highlight e5 --hide
+playwright-cli highlight --hide
+```
+
+## Raw output
+
+The global `--raw` option strips page status, generated code, and snapshot sections from the output, returning only the result value. Use it to pipe command output into other tools. Commands that don't produce output return nothing.
+
+```bash
+playwright-cli --raw eval "JSON.stringify(performance.timing)" | jq '.loadEventEnd - .navigationStart'
+playwright-cli --raw eval "JSON.stringify([...document.querySelectorAll('a')].map(a => a.href))" > links.json
+playwright-cli --raw snapshot > before.yml
+playwright-cli click e5
+playwright-cli --raw snapshot > after.yml
+diff before.yml after.yml
+TOKEN=$(playwright-cli --raw cookie-get session_id)
+playwright-cli --raw localstorage-get theme
+```
+
+For structured output wrapping every reply as JSON, pass --json
+
+```bash
+playwright-cli list --json
+```
+
+## Open parameters
+
+```bash
+# Use specific browser when creating session
+playwright-cli open --browser=chrome
+playwright-cli open --browser=firefox
+playwright-cli open --browser=webkit
+playwright-cli open --browser=msedge
+
+# Use persistent profile (by default profile is in-memory)
+playwright-cli open --persistent
+# Use persistent profile with custom directory
+playwright-cli open --profile=/path/to/profile
+
+# Connect to browser via Playwright Extension
+playwright-cli attach --extension=chrome
+
+# Connect to a running Chrome or Edge by channel name
+playwright-cli attach --cdp=chrome
+playwright-cli attach --cdp=msedge
+
+# Connect to a running browser via CDP endpoint
+playwright-cli attach --cdp=http://localhost:9222
+
+# Start with config file
+playwright-cli open --config=my-config.json
+
+# Close the browser
+playwright-cli close
+# Detach from an attached browser (leaves the external browser running)
+playwright-cli -s=msedge detach
+# Delete user data for the default session
+playwright-cli delete-data
+```
+
+## Snapshots
+
+After each command, playwright-cli provides a snapshot of the current browser state.
+
+```bash
+> playwright-cli goto https://example.com
+### Page
+- Page URL: https://example.com/
+- Page Title: Example Domain
+### Snapshot
+[Snapshot](.playwright-cli/page-2026-02-14T19-22-42-679Z.yml)
+```
+
+You can also take a snapshot on demand using `playwright-cli snapshot` command. All the options below can be combined as needed.
+
+```bash
+# default - save to a file with timestamp-based name
+playwright-cli snapshot
+
+# save to file, use when snapshot is a part of the workflow result
+playwright-cli snapshot --filename=after-click.yaml
+
+# snapshot an element instead of the whole page
+playwright-cli snapshot "#main"
+
+# limit snapshot depth for efficiency, take a partial snapshot afterwards
+playwright-cli snapshot --depth=4
+playwright-cli snapshot e34
+
+# include each element's bounding box as [box=x,y,width,height]
+playwright-cli snapshot --boxes
+```
+
+## Targeting elements
+
+By default, use refs from the snapshot to interact with page elements.
+
+```bash
+# get snapshot with refs
+playwright-cli snapshot
+
+# interact using a ref
+playwright-cli click e15
+```
+
+You can also use css selectors or Playwright locators.
+
+```bash
+# css selector
+playwright-cli click "#main > button.submit"
+
+# role locator
+playwright-cli click "getByRole('button', { name: 'Submit' })"
+
+# test id
+playwright-cli click "getByTestId('submit-button')"
+```
+
+## Browser Sessions
+
+```bash
+# create new browser session named "mysession" with persistent profile
+playwright-cli -s=mysession open example.com --persistent
+# same with manually specified profile directory (use when requested explicitly)
+playwright-cli -s=mysession open example.com --profile=/path/to/profile
+playwright-cli -s=mysession click e6
+playwright-cli -s=mysession close  # stop a named browser
+playwright-cli -s=mysession delete-data  # delete user data for persistent session
+
+playwright-cli list
+# Close all browsers
+playwright-cli close-all
+# Forcefully kill all browser processes
+playwright-cli kill-all
+```
+
+## Installation
+
+If global `playwright-cli` command is not available, try a local version via `npx playwright-cli`:
+
+```bash
+npx --no-install playwright-cli --version
+```
+
+When local version is available, use `npx playwright-cli` in all commands. Otherwise, install `playwright-cli` as a global command:
+
+```bash
+npm install -g @playwright/cli@latest
+```
+
+## Example: Form submission
+
+```bash
+playwright-cli open https://example.com/form
+playwright-cli snapshot
+
+playwright-cli fill e1 "user@example.com"
+playwright-cli fill e2 "password123"
+playwright-cli click e3
+playwright-cli snapshot
+playwright-cli close
+```
+
+## Example: Multi-tab workflow
+
+```bash
+playwright-cli open https://example.com
+playwright-cli tab-new https://example.com/other
+playwright-cli tab-list
+playwright-cli tab-select 0
+playwright-cli snapshot
+playwright-cli close
+```
+
+## Example: Debugging with DevTools
+
+```bash
+playwright-cli open https://example.com
+playwright-cli click e4
+playwright-cli fill e7 "test"
+playwright-cli console
+playwright-cli requests
+playwright-cli close
+```
+
+```bash
+playwright-cli open https://example.com
+playwright-cli tracing-start
+playwright-cli click e4
+playwright-cli fill e7 "test"
+playwright-cli tracing-stop
+playwright-cli close
+```
+
+## Example: Interactive session
+
+Ask the user for UI review or design feedback. The user draws boxes on the live page and types comments; you receive the annotated screenshot, the snapshot of the marked region, and the user's notes. Use this whenever the user asks for "UI review", "design feedback", or to "ask the user what they think / want / mean":
+
+```bash
+playwright-cli open https://example.com
+playwright-cli show --annotate
+```
+
+## Specific tasks
+
+- **Running and Debugging Playwright tests** [references/playwright-tests.md](references/playwright-tests.md)
+- **Request mocking** [references/request-mocking.md](references/request-mocking.md)
+- **Running Playwright code** [references/running-code.md](references/running-code.md)
+- **Browser session management** [references/session-management.md](references/session-management.md)
+- **Spec-driven testing (plan / generate / heal)** [references/spec-driven-testing.md](references/spec-driven-testing.md)
+- **Storage state (cookies, localStorage)** [references/storage-state.md](references/storage-state.md)
+- **Test generation** [references/test-generation.md](references/test-generation.md)
+- **Tracing** [references/tracing.md](references/tracing.md)
+- **Video recording** [references/video-recording.md](references/video-recording.md)
+- **Inspecting element attributes** [references/element-attributes.md](references/element-attributes.md)

package/project-template-v2/.claude/skills/playwright-cli/references/element-attributes.md

@@ -0,0 +1,23 @@
+# Inspecting Element Attributes
+
+When the snapshot doesn't show an element's `id`, `class`, `data-*` attributes, or other DOM properties, use `eval` to inspect them.
+
+## Examples
+
+```bash
+playwright-cli snapshot
+# snapshot shows a button as e7 but doesn't reveal its id or data attributes
+
+# get the element's id
+playwright-cli eval "el => el.id" e7
+
+# get all CSS classes
+playwright-cli eval "el => el.className" e7
+
+# get a specific attribute
+playwright-cli eval "el => el.getAttribute('data-testid')" e7
+playwright-cli eval "el => el.getAttribute('aria-label')" e7
+
+# get a computed style property
+playwright-cli eval "el => getComputedStyle(el).display" e7
+```

package/project-template-v2/.claude/skills/playwright-cli/references/playwright-tests.md

@@ -0,0 +1,39 @@
+# Running Playwright Tests
+
+To run Playwright tests, use the `npx playwright test` command, or a package manager script. To avoid opening the interactive html report, use `PLAYWRIGHT_HTML_OPEN=never` environment variable.
+
+```bash
+# Run all tests
+PLAYWRIGHT_HTML_OPEN=never npx playwright test
+
+# Run all tests through a custom npm script
+PLAYWRIGHT_HTML_OPEN=never npm run special-test-command
+```
+
+# Debugging Playwright Tests
+
+To debug a failing Playwright test, run it with `--debug=cli` option. This command will pause the test at the start and print the debugging instructions.
+
+**IMPORTANT**: run the command in the background and check the output until "Debugging Instructions" is printed. Make sure to stop the command after you have finished.
+
+Once instructions containing a session name are printed, use `playwright-cli` to attach the session and explore the page.
+
+```bash
+# Run the test
+PLAYWRIGHT_HTML_OPEN=never npx playwright test --debug=cli
+# ...
+# ... debugging instructions for "tw-abcdef" session ...
+# ...
+
+# Attach to the test
+playwright-cli attach tw-abcdef
+```
+
+Keep the test running in the background while you explore and look for a fix.
+The test is paused at the start, so you should step over or pause at a particular location
+where the problem is most likely to be.
+
+Every action you perform with `playwright-cli` generates corresponding Playwright TypeScript code.
+This code appears in the output and can be copied directly into the test. Most of the time, a specific locator or an expectation should be updated, but it could also be a bug in the app. Use your judgement.
+
+After fixing the test, stop the background test run. Rerun to check that test passes.