Siling UI Preview CLI

UI adapters

Since 0.0.3, check and start accept --ui-adapters FILE.json. Run siling-ui-preview help; capability ui-adapters-v1 confirms support. Project Skills download their pinned release automatically. Version 0.0.2 does not support this parameter.

Configuration maps direct runtime import specifiers in the selected src/tools/ui/ui.ts to explicit preview implementations. It does not replace imports made by other files, transitive dependencies, ui.ts itself or native globals. Replacement sources stay outside the framework, inside the configuration directory and --project-dir. Check/diagnostics expose uiAdapters including limitations. All replacement dependencies remain checked. See the Skill's references/ui-adapters.md for the configuration, synchronous resourceAvailable API and onDispose cleanup example.

Node.js 22 on Windows x64. Provide your own Siling v4-compatible source directory and classic Warcraft III MPQs. The package includes the resource codec, not the framework or game assets.

Install the published tool with npm install @scent/[email protected]. The command remains siling-ui-preview. Project Skills pin the exact release and SHA-256, download through npmmirror with official fallback, and install outside the project in the user's local tool cache.

Since 0.0.4 inspect.input exposes native mouseFocus, keyboardFocus, hovered, pressed buttons, capturedPointers and blocker. Ordinary FRAME/TEXT occlude; passive layers and actual FDF ignore-track flags pass through. Disabled occlusion is separate from event eligibility. act input reports INPUT_BLOCKED when its real click fails to focus the target. See docs/INPUT-COMPATIBILITY.md in the repository for exact rules, the shared game/browser fixture and pending user game acceptance. Generic native-button keyboard focus and game-world input are not simulated.

siling-ui-preview check --entry ./ui.tsx --siling-dir D:/framework --mpq-dir "E:/Game/Warcraft III Frozen Throne" --json
siling-ui-preview start --entry ./ui.tsx --siling-dir D:/framework --mpq-dir "E:/Game/Warcraft III Frozen Throne" --json
siling-ui-preview inspect --session SESSION
siling-ui-preview act --session SESSION --action click --target increment
siling-ui-preview screenshot --session SESSION --output preview.png
siling-ui-preview stop --session SESSION

TSX files default-export a function component. TS files export mount({root, signal}) and return a cleanup function. root is an exclusive SilingElement root. Imports use @siling/tools/ui/ui, @siling/tools/ui/tsx, or project-local UI modules. Add JSX id values for stable Agent interaction targets. Native handles are exposed as revision:handle; they expire after hot reload. Duplicate JSX IDs reject actions.

Use --resource-dir repeatedly for project assets, --toc for a different resource-relative TOC, --tsconfig and --project-dir for project-local aliases, --viewport WIDTHxHEIGHT for canvas size, and --mpq repeatedly for an explicit archive override order. Directory mode reads classic patch archives first, then other MPQs in sorted filename order. Relative paths resolve against the caller's working directory.

All commands emit JSON. check validates the complete runtime import graph and a tree-shaken browser bundle before execution. Unapproved npm/game dependencies, computed module paths, unknown globals and incompatible environment adapters are rejected with a dependency chain. Type-only imports are erased. Target project compiler plugins are never executed. This is a compatibility check for trusted development code, not a security sandbox.

For game-coupled UI, the Agent prepares an isolated preview entry with test data, action logging through print, and extracted UI-only helpers. The original source stays unchanged and the same strict check runs on the adapted entry. Preserve visual structure and required interactions; passing this preview does not validate game business. The Skill includes the detailed adaptation reference.

Framework UI/TSX/layout/animation/FDF files come from the supplied directory. Environment modules replaced by browser adapters are listed in the check report and pinned to reviewed source contracts; modified boundaries fail explicitly. Version strings and directory names are not compatibility signals. Source layout changes or new native APIs require an adapter update.

Since 0.0.2, player/math/message adapters validate supported exports and their same-module dependency closure, imports and top-level initialization instead of unrelated function bodies. New unrelated helpers do not break basic SilingElement imports; using an unadapted export still fails. The reviewed optional message duration extension preserves the existing default. Other environment modules remain fully pinned. isMpqResourceAvailable checks actual nonempty bytes through the resource service, in project/framework/MPQ order; missing/empty returns false, service errors throw. This synchronous compatibility query may block briefly during disk/MPQ reads. It neither validates decoding nor dynamically loads additional TOCs; configure the TOC to preload as before.

start launches a background localhost service and returns its session ID and URL. Source and asset changes trigger revalidation. Invalid changes disable the old preview until fixed. status reports the current revision, diagnostics returns errors, and stop closes the managed browser and codec.

On Windows, package installation applies a version-checked Playwright process cleanup patch; session startup verifies it again (including installations made with lifecycle scripts disabled). Browser cleanup uses a bundled, hidden Windows PowerShell helper with Toolhelp process snapshots and native process handles. It does not launch cmd.exe or taskkill, and requires no WMI service query. stop reports success only after the session records completed cleanup and its process exits; a cleanup timeout is an error. Dependency version or launcher structure changes require review instead of a blind patch.

inspect, screenshot and act share one persistent headless browser per session. Human browser tabs opened at the returned URL have independent state. A locally installed Chrome or Edge is used; Playwright Chromium is a fallback if installed. Actions: click, input, key --key ControlOrMeta+A, scroll --dy 120, drag --to TARGET, wait --target ID --text EXPECTED --timeout 5000. Screenshots wait for requested textures to settle.

Models remain placeholders; BLP2, CASC, game simulation and offline HTML export are not supported. FDF limitations and browser/game font differences remain as described in the project documentation.