ui-design-workbench-cli 0.6.7__tar.gz → 0.6.10__tar.gz

ui_design_workbench_cli-0.6.10/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: ui-design-workbench-cli
+Version: 0.6.10
+Summary: Repository UI indexing, graph, preview, and deterministic review CLI
+Author: Elgreed
+Project-URL: Homepage, https://github.com/Elgreed/ui-design-workbench
+Project-URL: Repository, https://github.com/Elgreed/ui-design-workbench
+Project-URL: Changelog, https://github.com/Elgreed/ui-design-workbench/blob/main/CHANGELOG.md
+Keywords: agent-skills,ui,ux,design-review,code-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2; extra == "mcp"
+
+# UI Design Workbench
+
+[Русская версия](README.ru.md) · [Changelog](CHANGELOG.md)
+
+Explore an application's screens and navigation in an interactive HTML preview built from its source code. No application build or launch is needed.
+
+Use it to understand a project, inspect supported UI states, or request a separate UI/UX review. Parsing does not execute application logic or guarantee the same pixels as the running application.
+
+![Review view: demo screen on the left and findings on the right](https://raw.githubusercontent.com/Elgreed/ui-design-workbench/v0.6.10/fixtures/golden/workbench-review/problems-wide.png)
+
+*Review view of the bundled demonstration fixture. Findings belong to the separate review workflow.*
+
+## Install
+
+For source analysis and basic checks, install Python 3.10+ and [pipx](https://pipx.pypa.io/latest/how-to/install-pipx.html), then run:
+
+```sh
+pipx install ui-design-workbench-cli
+uidw --version
+uidw doctor
+```
+
+`doctor` reports dependencies and cache settings. **Full browser checks additionally need Node.js 22+ and Chrome, Edge or Chromium.** Basic `--level quick` checks do not need them. To view the generated HTML, use a browser.
+
+CLI use does not require an agent or MCP. For Codex and other agents, follow [agent setup](references/agent-integrations.md).
+
+## First preview
+
+Open a terminal in your application's root directory. These commands work in PowerShell and a POSIX shell:
+
+```sh
+uidw config setup --detail medium
+uidw workbench --output-dir ../ui-preview --level quick --open
+```
+
+This example selects representative preview data (`medium`). Run `uidw config setup` without the option to choose interactively. The first command stores settings; the second writes `../ui-preview/ui-preview.html` and opens it. Check reports are under `../ui-preview/validation/`.
+
+Look for `проверка pass` in the CLI output. If checks fail, HTML may still exist as a diagnostic preview: read the reports before treating reconstruction as complete. CLI messages are primarily Russian; the HTML interface supports English and Russian. Add `--lang en` to select English in the preview.
+
+For absolute paths, Windows examples, detail levels and recovery steps, see [first run](references/getting-started.md).
+
+## Choose the task
+
+| Task | Command, from the application root |
+| --- | --- |
+| Explore screens without a UI/UX audit | `uidw workbench --output-dir ../ui-preview --level quick --open` |
+| Include browser checks | `uidw workbench --output-dir ../ui-preview --level full --open` |
+| Request a UI/UX review | `uidw review --output-dir ../ui-review --level full` |
+| Check translation limits | `uidw fidelity report` |
+| Inspect available adapters | `uidw fidelity capabilities` |
+| Diagnose installation | `uidw doctor` |
+
+`workbench` and `check` validate reconstruction. `review` requests UI/UX findings. Detail (`low/medium/high`) controls preview content; `--level quick/full` controls validation. No detail level starts a UI/UX audit.
+
+See [using the preview](references/using-preview.md), `uidw --help` and `uidw help advanced` for further commands.
+
+## Source support and accuracy
+
+Each adapter supports a subset of its framework. Evidence below concerns small fixtures, not every platform configuration or application.
+
+| Source | Supported examples | Limits and validation evidence |
+| --- | --- | --- |
+| HTML/CSS | Elements, simple selectors, spacing, linked stylesheets | Dynamic scripts and complex CSS limited; plain HTML fixture compared in a browser |
+| React, Vue, Svelte, React Native | Recognized components, literal properties and supported styles | Arbitrary JavaScript not evaluated; source tests, not framework-wide runtime comparisons |
+| Android Compose | Local components, literal themes/resources, preview arguments | Runtime Kotlin and custom drawing limited; selected YaDonor preview compared with Android capture |
+| Android Views XML | Layouts, resources, navigation | Custom views and dynamic bindings limited; source tests |
+| SwiftUI on iOS/macOS | Local views, literal values, ordered layout modifiers | Dynamic branches and some SF Symbols unresolved; source-only tests, no Apple runtime comparison |
+| Storyboard/XIB | Recognized XML views and attributes | Runtime UIKit/AppKit behavior limited; source tests |
+| WPF / WinUI XAML | Grid placement, literal thickness, colors and states | Complex templates/bindings limited; WPF fixture compared through WPF, WinUI not natively verified |
+| Flutter | Nested widgets, literal constructors, insets and text styles | Arbitrary Dart and runtime state limited; fixture compared with the Flutter test engine |
+
+Missing values and unsupported constructs are reported as gaps. Fonts, system controls and runtime data can change the result. Optional native Android/Apple discovery never launches an emulator or simulator automatically. See [accuracy details](references/fidelity.md) and [native rendering](references/native-rendering.md).
+
+## Files and application source
+
+Preview and review leave application source unchanged. Applying an accepted proposal is a separate action. The default cache lives outside the application repository; an explicit output directory receives HTML and reports. Export browser review state before moving the preview or clearing browser storage.
+
+## Upgrade
+
+For a pipx installation:
+
+```sh
+pipx upgrade ui-design-workbench-cli
+uidw --version
+```
+
+For a managed skill copy, also run `uidw install-skill codex` (or your agent name) and start a new agent session. Linked development skills and separate MCP environments have different steps: see [agent upgrades](references/agent-integrations.md#upgrade-and-development-links).
+
+## Documentation
+
+**User guides:** [First run](references/getting-started.md) · [Using the preview](references/using-preview.md) · [Agent setup](references/agent-integrations.md) · [Troubleshooting](references/troubleshooting.md).
+
+**Technical references (English):** [Fidelity](references/fidelity.md) · [Native rendering](references/native-rendering.md) · [Cache](references/cache-protocol.md) · [Components](references/component-catalog.md) · [IR schema](references/ir-schema.md) · [Review contract](references/review-workflow.md).
+
+Current CLI version: `0.6.10`.

ui_design_workbench_cli-0.6.10/README.md

@@ -0,0 +1,95 @@
+# UI Design Workbench
+
+[Русская версия](README.ru.md) · [Changelog](CHANGELOG.md)
+
+Explore an application's screens and navigation in an interactive HTML preview built from its source code. No application build or launch is needed.
+
+Use it to understand a project, inspect supported UI states, or request a separate UI/UX review. Parsing does not execute application logic or guarantee the same pixels as the running application.
+
+![Review view: demo screen on the left and findings on the right](https://raw.githubusercontent.com/Elgreed/ui-design-workbench/v0.6.10/fixtures/golden/workbench-review/problems-wide.png)
+
+*Review view of the bundled demonstration fixture. Findings belong to the separate review workflow.*
+
+## Install
+
+For source analysis and basic checks, install Python 3.10+ and [pipx](https://pipx.pypa.io/latest/how-to/install-pipx.html), then run:
+
+```sh
+pipx install ui-design-workbench-cli
+uidw --version
+uidw doctor
+```
+
+`doctor` reports dependencies and cache settings. **Full browser checks additionally need Node.js 22+ and Chrome, Edge or Chromium.** Basic `--level quick` checks do not need them. To view the generated HTML, use a browser.
+
+CLI use does not require an agent or MCP. For Codex and other agents, follow [agent setup](references/agent-integrations.md).
+
+## First preview
+
+Open a terminal in your application's root directory. These commands work in PowerShell and a POSIX shell:
+
+```sh
+uidw config setup --detail medium
+uidw workbench --output-dir ../ui-preview --level quick --open
+```
+
+This example selects representative preview data (`medium`). Run `uidw config setup` without the option to choose interactively. The first command stores settings; the second writes `../ui-preview/ui-preview.html` and opens it. Check reports are under `../ui-preview/validation/`.
+
+Look for `проверка pass` in the CLI output. If checks fail, HTML may still exist as a diagnostic preview: read the reports before treating reconstruction as complete. CLI messages are primarily Russian; the HTML interface supports English and Russian. Add `--lang en` to select English in the preview.
+
+For absolute paths, Windows examples, detail levels and recovery steps, see [first run](references/getting-started.md).
+
+## Choose the task
+
+| Task | Command, from the application root |
+| --- | --- |
+| Explore screens without a UI/UX audit | `uidw workbench --output-dir ../ui-preview --level quick --open` |
+| Include browser checks | `uidw workbench --output-dir ../ui-preview --level full --open` |
+| Request a UI/UX review | `uidw review --output-dir ../ui-review --level full` |
+| Check translation limits | `uidw fidelity report` |
+| Inspect available adapters | `uidw fidelity capabilities` |
+| Diagnose installation | `uidw doctor` |
+
+`workbench` and `check` validate reconstruction. `review` requests UI/UX findings. Detail (`low/medium/high`) controls preview content; `--level quick/full` controls validation. No detail level starts a UI/UX audit.
+
+See [using the preview](references/using-preview.md), `uidw --help` and `uidw help advanced` for further commands.
+
+## Source support and accuracy
+
+Each adapter supports a subset of its framework. Evidence below concerns small fixtures, not every platform configuration or application.
+
+| Source | Supported examples | Limits and validation evidence |
+| --- | --- | --- |
+| HTML/CSS | Elements, simple selectors, spacing, linked stylesheets | Dynamic scripts and complex CSS limited; plain HTML fixture compared in a browser |
+| React, Vue, Svelte, React Native | Recognized components, literal properties and supported styles | Arbitrary JavaScript not evaluated; source tests, not framework-wide runtime comparisons |
+| Android Compose | Local components, literal themes/resources, preview arguments | Runtime Kotlin and custom drawing limited; selected YaDonor preview compared with Android capture |
+| Android Views XML | Layouts, resources, navigation | Custom views and dynamic bindings limited; source tests |
+| SwiftUI on iOS/macOS | Local views, literal values, ordered layout modifiers | Dynamic branches and some SF Symbols unresolved; source-only tests, no Apple runtime comparison |
+| Storyboard/XIB | Recognized XML views and attributes | Runtime UIKit/AppKit behavior limited; source tests |
+| WPF / WinUI XAML | Grid placement, literal thickness, colors and states | Complex templates/bindings limited; WPF fixture compared through WPF, WinUI not natively verified |
+| Flutter | Nested widgets, literal constructors, insets and text styles | Arbitrary Dart and runtime state limited; fixture compared with the Flutter test engine |
+
+Missing values and unsupported constructs are reported as gaps. Fonts, system controls and runtime data can change the result. Optional native Android/Apple discovery never launches an emulator or simulator automatically. See [accuracy details](references/fidelity.md) and [native rendering](references/native-rendering.md).
+
+## Files and application source
+
+Preview and review leave application source unchanged. Applying an accepted proposal is a separate action. The default cache lives outside the application repository; an explicit output directory receives HTML and reports. Export browser review state before moving the preview or clearing browser storage.
+
+## Upgrade
+
+For a pipx installation:
+
+```sh
+pipx upgrade ui-design-workbench-cli
+uidw --version
+```
+
+For a managed skill copy, also run `uidw install-skill codex` (or your agent name) and start a new agent session. Linked development skills and separate MCP environments have different steps: see [agent upgrades](references/agent-integrations.md#upgrade-and-development-links).
+
+## Documentation
+
+**User guides:** [First run](references/getting-started.md) · [Using the preview](references/using-preview.md) · [Agent setup](references/agent-integrations.md) · [Troubleshooting](references/troubleshooting.md).
+
+**Technical references (English):** [Fidelity](references/fidelity.md) · [Native rendering](references/native-rendering.md) · [Cache](references/cache-protocol.md) · [Components](references/component-catalog.md) · [IR schema](references/ir-schema.md) · [Review contract](references/review-workflow.md).
+
+Current CLI version: `0.6.10`.

{ui_design_workbench_cli-0.6.7 → ui_design_workbench_cli-0.6.10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ui-design-workbench-cli"
-version = "0.6.7"
+version = "0.6.10"
 description = "Repository UI indexing, graph, preview, and deterministic review CLI"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -43,6 +43,10 @@ py-modules = [
   "fidelity_core",
   "fidelity_adapter_api",
   "fidelity_adapters",
+  "source_syntax",
+  "compose_syntax",
+  "compose_resources",
+  "compose_instances",
   "fidelity_platform_adapters",
   "android_resource_resolver",
   "apple_resource_resolver",
@@ -68,6 +72,10 @@ py-modules = [
   "scripts/coverage_report.py",
   "scripts/fidelity_adapter_api.py",
   "scripts/fidelity_adapters.py",
+  "scripts/source_syntax.py",
+  "scripts/compose_syntax.py",
+  "scripts/compose_resources.py",
+  "scripts/compose_instances.py",
   "scripts/fidelity_core.py",
   "scripts/fidelity_platform_adapters.py",
   "scripts/generate_interaction_matrix.py",

ui_design_workbench_cli-0.6.10/references/agent-integrations.md

@@ -0,0 +1,65 @@
+# Agent setup
+
+[Русский](agent-integrations.ru.md) · [First run](getting-started.md) · [Troubleshooting](troubleshooting.md)
+
+## Choose skill or MCP
+
+A **skill** teaches the agent the workflow; it can use the CLI through shell commands. **MCP** exposes the same core as callable tools. Neither is required for terminal-only use. UIDW does not supply an agent account or model.
+
+## Install the skill
+
+```sh
+pipx install ui-design-workbench-cli
+uidw install-skill codex
+```
+
+If the CLI is already installed, run only the second command. Start a new agent session. For an initial request, provide the application path and ask:
+
+> Use UI Design Workbench to show this project's screens from code, without a UI/UX review. Ask me to choose detail if the project is not configured.
+
+The installer reports the skill location. If it reports an unmanaged existing directory, follow [troubleshooting](troubleshooting.md); do not delete that directory just to rerun installation.
+
+## Optional Codex MCP setup
+
+The following example assumes Codex CLI is available and the application is at `C:/Projects/My App`. Substitute your own absolute path; on macOS/Linux, for example `/home/you/projects/my-app`.
+
+```sh
+pipx inject ui-design-workbench-cli "mcp>=2,<3"
+codex mcp add ui-design-workbench -- uidw-mcp --repo "C:/Projects/My App"
+codex mcp list
+```
+
+If that server name already exists, inspect its configuration before updating it. This is the [official Codex stdio configuration pattern](https://developers.openai.com/codex/mcp/). The equivalent entry in `~/.codex/config.toml` is:
+
+```toml
+[mcp_servers.ui-design-workbench]
+command = "uidw-mcp"
+args = ["--repo", "C:/Projects/My App"]
+```
+
+Use either method, not duplicate entries. If the desktop app cannot resolve `uidw-mcp`, replace `command` with its absolute executable path. A custom `CODEX_HOME` changes the configuration location.
+
+Restart the client or start a fresh session, then ask it to call `ui_project` for the intended repository. Expect a compact project summary or a request to choose detail, followed by a bounded `ui_scope` request when a screen is needed. `codex mcp list` confirms registration, not a successful live tool call. A manually launched stdio server waits for protocol input; it does not print an interactive prompt or open a webpage.
+
+## Upgrade and development links
+
+For a pipx installation and an installer-managed skill copy:
+
+```sh
+pipx upgrade ui-design-workbench-cli
+uidw install-skill codex
+uidw --version
+uidw doctor
+```
+
+For an existing pip installation, update with that same Python interpreter: `python -m pip install --upgrade ui-design-workbench-cli`. Do not mix installers for one environment.
+
+If MCP points to a separate virtual environment, upgrade the package in that environment too, using its Python executable with `-m pip install --upgrade "ui-design-workbench-cli[mcp]"`. Check its version with `-m uidw --version`. Updating a global CLI does not update another environment. Restart clients holding the previous MCP process.
+
+A development symlink/junction points directly to a checkout. Update that checkout and its installed CLI separately; do not overwrite the link with a packaged skill copy. From the checkout, `python scripts/uidw.py --version` checks the source version.
+
+## Other agents
+
+Replace `codex` with `claude`, `cursor`, `gemini`, `copilot`, `opencode`, `agents` or `all`. `all` installs into every supported location. Other MCP clients can launch `uidw-mcp --repo` with an absolute application path as a local stdio command.
+
+Installing a skill and granting source access does not authorize application changes. Preview tasks operate on derived files; source application is a separate action. Model-facing MCP context is visible to the host agent. See the [integration protocol](agent-protocol.md) for discovery paths, bounded context and handoff rules.

ui_design_workbench_cli-0.6.10/references/agent-integrations.ru.md

@@ -0,0 +1,65 @@
+# Подключение агента
+
+[English](agent-integrations.md) · [Первый запуск](getting-started.ru.md) · [Решение проблем](troubleshooting.ru.md)
+
+## Навык или MCP
+
+**Навык** объясняет агенту порядок работы; агент вызывает CLI через терминал. **MCP** предоставляет тот же механизм в виде инструментов. Для работы только в терминале оба необязательны. UIDW не предоставляет аккаунт агента или модель.
+
+## Установка навыка
+
+```sh
+pipx install ui-design-workbench-cli
+uidw install-skill codex
+```
+
+Если CLI уже установлен, выполните только вторую команду. Начните новую сессию агента. В первом запросе укажите путь приложения и попросите:
+
+> Используй UI Design Workbench, чтобы показать экраны этого проекта по коду, без UI/UX-ревью. Если проект ещё не настроен, предложи выбрать детализацию.
+
+Установщик показывает путь навыка. Если он сообщает о существующем неуправляемом каталоге, воспользуйтесь [разделом решения проблем](troubleshooting.ru.md); не удаляйте каталог просто ради повторной установки.
+
+## Необязательно: подключите MCP к Codex
+
+В примере доступен Codex CLI, а приложение находится в `C:/Projects/My App`. Замените путь своим абсолютным путём; на macOS/Linux это может быть `/home/you/projects/my-app`.
+
+```sh
+pipx inject ui-design-workbench-cli "mcp>=2,<3"
+codex mcp add ui-design-workbench -- uidw-mcp --repo "C:/Projects/My App"
+codex mcp list
+```
+
+Если сервер с таким именем уже существует, сначала проверьте его настройки. Команда соответствует [официальной инструкции Codex для stdio](https://developers.openai.com/codex/mcp/). Эквивалентная запись в `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.ui-design-workbench]
+command = "uidw-mcp"
+args = ["--repo", "C:/Projects/My App"]
+```
+
+Выберите один способ, не добавляйте дублирующую запись. Если приложение не находит `uidw-mcp`, укажите в `command` абсолютный путь к исполняемому файлу. При заданном `CODEX_HOME` расположение настроек меняется.
+
+Перезапустите клиент или начните новую сессию, затем попросите вызвать `ui_project` для нужного репозитория. Ожидается краткая сводка либо предложение выбрать детализацию; для конкретного экрана затем используется `ui_scope`. Команда `codex mcp list` подтверждает регистрацию, но не успешный вызов инструмента. Запущенный вручную stdio-сервер ждёт сообщения протокола: приглашения ввода и веб-страницы у него нет.
+
+## Обновление и связь с репозиторием
+
+Для установки через pipx и управляемой копии навыка:
+
+```sh
+pipx upgrade ui-design-workbench-cli
+uidw install-skill codex
+uidw --version
+uidw doctor
+```
+
+Для существующей установки через pip используйте тот же Python: `python -m pip install --upgrade ui-design-workbench-cli`. Не смешивайте установщики в одном окружении.
+
+Если MCP использует отдельное виртуальное окружение, обновите пакет и там: вызовите его Python с `-m pip install --upgrade "ui-design-workbench-cli[mcp]"`. Проверьте версию через `-m uidw --version`. Обновление глобального CLI не обновляет другое окружение. Перезапустите клиенты, в которых ещё работает прежний MCP-процесс.
+
+Символическая ссылка или junction навыка разработчика указывает прямо на репозиторий. Обновляйте этот репозиторий и установленный CLI отдельно; не заменяйте ссылку копией навыка из пакета. Команда `python scripts/uidw.py --version` из репозитория показывает версию исходников.
+
+## Другие агенты
+
+Вместо `codex` поддерживаются `claude`, `cursor`, `gemini`, `copilot`, `opencode`, `agents` и `all`. `all` устанавливает навык во все поддерживаемые каталоги. MCP для другого клиента настраивается как локальная stdio-команда `uidw-mcp --repo` с абсолютным путём проекта.
+
+Установка навыка и доступ к исходникам не означают разрешение менять приложение. Предпросмотр работает с производными файлами; применение предложения к проекту остаётся отдельным действием. Сведения, переданные через MCP, видны использующему его агенту. Технический контракт и таблица путей: [Agent integration protocol](agent-protocol.md), на английском.

ui_design_workbench_cli-0.6.7/references/agent-integrations.md → ui_design_workbench_cli-0.6.10/references/agent-protocol.md

@@ -1,4 +1,6 @@
-# Agent integrations
+# Agent integration protocol
+
+For installation and first use, see [agent setup](agent-integrations.md).
 
 The repository follows the open Agent Skills layout: one `SKILL.md` plus `scripts/`, `references/`, and optional agent-specific metadata. The core workflow communicates through files and shell commands, not a proprietary API.
 
@@ -28,7 +30,7 @@ For contributor checkouts, `./install.ps1 -Agent all` on Windows or `./install.s
 
 ## Capability contract
 
-An agent needs local file read/write access and Python 3.10+. Node.js plus Chromium/Edge is optional but required for headless interaction and geometry diagnostics. The target application, emulator, simulator, bridge server, and internet access are not required.
+An agent needs local file read/write access and Python 3.10+. Node.js 22+ plus Chromium/Edge is optional but required for headless interaction and geometry diagnostics. The target application, emulator, simulator, bridge server, and internet access are not required.
 
 The portable handoff is `ui-agent-job.json`. It contains artifact directory, review scope, selected stable finding IDs, screen IDs, active/baseline versions, annotations, allowed output patterns, and `sourceChangeAllowed: false`. It also points to a bounded `ui-agent-context.json` and a sparse `ui-ir.patch.json`; the agent reads the bounded context and returns patch operations instead of loading or replacing the complete IR. Agents must modify only the declared review artifacts and return validation results.
 
@@ -37,3 +39,25 @@ For ordinary source tasks, `uidw init` can opt a project into lightweight UI gui
 Codex may opt into `render_preview.py --agent codex`, which enables the official local `codex://new` preparation path. Other agents use copied prompts or the JSON job. Provider-specific adapters are optional presentation conveniences and must not change the IR, cache, review semantics, permissions, or approval boundary.
 
 The optional `uidw-mcp` stdio server is a transport facade over the same deterministic CLI core. It exposes compact project discovery, strictly bounded screen/finding context, job preparation, sparse patch application, preview building, and on-demand fidelity explanation. Scoped nodes omit full source expressions by default and expose a stable `scopeHash`; pass it back as `if_none_match` before repeating the same request. MCP is an optional dependency; installing or running the regular CLI must not require it. Configure an agent to launch `uidw-mcp --repo <absolute-project-path>` as a local stdio command; it opens no port and keeps project caches on the local machine. Selected model-facing context is still visible to the host agent and should be treated as derived source data.
+
+## CLI automation contract
+
+Global `--repo` and `--json` options can appear before or after the command.
+With `--json`, argument, repository and handled command errors are written as a
+single JSON document to stdout; stderr is reserved for non-JSON diagnostics.
+Error documents contain `version: 1`, `status: "error"`, an `error` object with
+`code` and `message`, `exitCode`, and an optional `hint` (null when absent).
+Codes are `invalid_arguments`, `invalid_repository`, and `command_failed`.
+Help and version requests remain plain text.
+
+Exit codes: `0` for success (including a prepared job), `2` for invalid arguments
+or repository, `3` for a handled execution error, and `4` for failed checks or
+blocked operations. A diagnostic HTML file can exist even when workbench or
+review exits with `4`; inspect its JSON result and validation reports.
+
+`uidw apply` prepares a JSON implementation job for an external agent. The agent
+must execute that job to change application source. `--direct` removes the
+approved-mockup prerequisite when preparing the job.
+
+Doctor reports Node.js availability separately from `compatible` (version 22+).
+Full checks require a compatible, verifiable Node.js installation and a browser.

{ui_design_workbench_cli-0.6.7 → ui_design_workbench_cli-0.6.10}/references/fidelity.md

@@ -10,6 +10,24 @@ Use `uidw fidelity capabilities` for the installed support matrix, `uidw fidelit
 
 The HTML projection resolves recognized controls through the official-doc-first [platform component catalog](component-catalog.md). Catalog geometry is a render-only fallback: explicit source layout, theme, token, and style evidence always wins, and the source IR is not mutated.
 
+Compose translation follows unique local composable declarations, literal parameter defaults and constructor preview fixtures. Simple imported enum `entries.forEach` loops and literal resource getters can supply repeated content. Expansion is limited to six nested components and 2,000 calls per translated source; ambiguity, recursion and exhausted budgets remain explicit gaps. Runtime Kotlin, arbitrary collection transformations, slot forwarding, custom drawing and arbitrary theme providers are not evaluated.
+
+Literal project theme values and local font assets are resolved from source. The box model marks automatic text measurement as partial and lets the browser wrap and measure the loaded font, rather than treating average character widths as solved geometry. Browser line boxes and shadows can still differ from native rendering. A partial context does not establish native visual parity.
+
+For a user-requested native comparison, use the same authored preview state, locale, font scale and logical viewport. Capture metadata can provide `viewport.safeAreaInsets` in logical pixels for Compose system-bar padding. The following command captures device content after fonts load, excluding workbench chrome. Replace the quoted paths and `SCREEN_ID` with the actual installed skill directory, preview file and screen ID; select a theme ID present in the preview:
+
+```sh
+node "<skill-dir>/scripts/smoke_preview.js" "<preview-dir>/ui-preview.html" --capture-device --capture-screen SCREEN_ID --capture-theme light --screenshot screen.png --geometry-output geometry.json
+```
+
+This helper needs Node.js 22+ and Chromium/Edge, as described in [first run](getting-started.md). It captures the HTML projection, not a native application. Keep the separate native screenshot, device density, source revision and comparison results with the diagnostic artifact; system-bar icons themselves are outside the source projection.
+
+Flutter and SwiftUI use the same balanced source delimiter and literal masking utilities as Compose. Visual parameters are scoped to the current call, excluding child widgets and event handlers. SwiftUI expands unique local View declarations with literal member arguments and represents order-dependent frame/padding/background operations as separate source-backed nodes. Flutter resolves literal constructor defaults, distinguishes TextStyle height factors from widget heights, and propagates SizedBox tight constraints to its child. Expansion is capped at six component levels and 2,000 widget calls. Arbitrary control flow, unavailable SF Symbols and recursive expansion remain gaps.
+
+XAML translates four-value Thickness in left/top/right/bottom order, alpha-first colors, explicit grid tracks/cell spans and literal states. WPF Border and TextBlock defaults are distinct from generic card recipes. Resource bindings, control templates, nonliteral grid tracks and more complex platform layout behavior still require separate handling. Web handles the supported simple selectors in CSS cascade order, including importance and linked stylesheet order; unsupported at-rules are reported rather than applied unconditionally.
+
+The source fixtures in `fixtures/golden/platform-fidelity` exercise these shared failure patterns. A Flutter engine golden, a WPF RenderTargetBitmap and an original Web page can provide independent runtime evidence for their respective fixture. WPF evidence does not verify WinUI, and Flutter test-engine evidence does not verify every device configuration. SwiftUI iOS/macOS fixture assertions are source-only unless matching Apple runtime captures are supplied. Successful source tests or a small native comparison must never promote unrelated screens or platforms to verified visual parity.
+
 Use this contract before creating reviewable IR. The goal is not a visually pleasant approximation; it is a traceable projection of the authored UI.
 
 ## Evidence bundle per screen

ui_design_workbench_cli-0.6.10/references/getting-started.md

@@ -0,0 +1,86 @@
+# First run
+
+[Русский](getting-started.ru.md) · [Preview guide](using-preview.md) · [Troubleshooting](troubleshooting.md)
+
+## 1. Install the CLI
+
+Install Python 3.10+ and pipx using the [official pipx instructions](https://pipx.pypa.io/latest/how-to/install-pipx.html). If pipx is installed but its commands are not found, run `pipx ensurepath` and open a new terminal.
+
+```sh
+pipx install ui-design-workbench-cli
+uidw --version
+uidw doctor
+```
+
+A packaged Agent Skill and MCP are optional; see [agent setup](agent-integrations.md). Internet access is needed to download packages. Source scanning and the generated HTML do not require a running application or network access.
+
+## 2. Select the application and detail
+
+Open a terminal in the application root, then run `uidw config setup`. Or select a level explicitly:
+
+```sh
+uidw config setup --detail medium
+```
+
+| Detail | Intended preview content |
+| --- | --- |
+| `low` | Basic layout and minimal sample data |
+| `medium` | Representative data, interactions and states |
+| `high` | Expanded data, themes and more validation by default |
+
+Detail guides preview preparation; it does not make unsupported runtime expressions executable or repair missing source evidence. Inspect the result for unresolved values. No level starts a UI/UX audit.
+
+The first source command creates a cache automatically. Settings are stored per application; `uidw config show` displays them. You do not need to run `init` before each preview.
+
+## 3. Build and open
+
+From the application root:
+
+```sh
+uidw workbench --output-dir ../ui-preview --level quick --open
+```
+
+Or use explicit paths. Replace the example application path with your own; keep quotes around paths containing spaces.
+
+Windows PowerShell:
+
+```powershell
+uidw --repo "C:/Projects/My App" config setup --detail medium
+uidw --repo "C:/Projects/My App" workbench --output-dir "C:/UI previews/My App" --level quick --open
+```
+
+macOS/Linux:
+
+```sh
+uidw --repo "$HOME/projects/my-app" config setup --detail medium
+uidw --repo "$HOME/projects/my-app" workbench --output-dir "$HOME/ui-previews/my-app" --level quick --open
+```
+
+`--repo` selects source input. `--output-dir` selects generated files and is resolved from the terminal's current directory. If omitted, output goes to the project cache. Use a separate result directory for each application.
+
+## 4. Read the result
+
+| Output | Meaning |
+| --- | --- |
+| `ui-preview.html` | Interactive preview; open this file in a browser |
+| `validation/fidelity-report.json` | Source evidence and missing translation |
+| `validation/ui-coverage.json` | Screen and component coverage |
+| `validation/platform-profile-report.json` | Platform profile checks |
+
+The terminal prints the HTML path and `проверка pass` when checks pass. With failed checks it may still write a diagnostic HTML file. An existing file or an open browser is not a successful validation result. Use `uidw fidelity report` and the reports above to investigate; see [troubleshooting](troubleshooting.md).
+
+The CLI currently prints primarily Russian messages. Add `--lang en` to `workbench` for English HTML controls. `--json` gives machine-readable command output.
+
+## 5. Add full checks when needed
+
+`--level quick` validates the model without headless browser automation. `--level full` adds browser checks and requires Node.js 22+ and Chrome, Edge or Chromium:
+
+```sh
+node --version
+uidw doctor
+uidw workbench --output-dir ../ui-preview --level full --open
+```
+
+The helper uses the built-in [Node.js WebSocket API](https://nodejs.org/download/release/v22.15.0/docs/api/globals.html#websocket). Set `CHROME_PATH` if the browser is outside standard locations. Missing browser tooling makes the full check fail; it does not silently become a quick check.
+
+Next: [explore the preview](using-preview.md) or [connect an agent](agent-integrations.md).

ui_design_workbench_cli-0.6.10/references/getting-started.ru.md

@@ -0,0 +1,86 @@
+# Первый запуск
+
+[English](getting-started.md) · [Предпросмотр](using-preview.ru.md) · [Решение проблем](troubleshooting.ru.md)
+
+## 1. Установите CLI
+
+Установите Python 3.10+ и pipx по [официальной инструкции pipx](https://pipx.pypa.io/latest/how-to/install-pipx.html). Если pipx установлен, но команды не находятся, выполните `pipx ensurepath` и откройте новый терминал.
+
+```sh
+pipx install ui-design-workbench-cli
+uidw --version
+uidw doctor
+```
+
+Навык агента и MCP необязательны: [подключение агента](agent-integrations.ru.md). Интернет нужен для скачивания пакетов. Анализ исходников и готовый HTML не требуют сети или запущенного приложения.
+
+## 2. Выберите приложение и детализацию
+
+Откройте терминал в корне приложения и выполните `uidw config setup`. Или укажите уровень явно:
+
+```sh
+uidw config setup --detail medium
+```
+
+| Уровень | Предполагаемое содержимое предпросмотра |
+| --- | --- |
+| `low` | Базовая разметка и минимум примеров данных |
+| `medium` | Репрезентативные данные, взаимодействия и состояния |
+| `high` | Расширенные данные, темы и больше проверок по умолчанию |
+
+Детализация задаёт подготовку предпросмотра. Она не исполняет неподдерживаемый код и не восстанавливает отсутствующие исходные значения. Проверяйте, какие данные остались неизвестными. Ни один уровень не запускает UI/UX-аудит.
+
+Первая команда анализа автоматически создаёт кеш. Настройки сохраняются для приложения; их показывает `uidw config show`. Вызывать `init` перед каждым предпросмотром не нужно.
+
+## 3. Постройте и откройте макет
+
+Из корня приложения:
+
+```sh
+uidw workbench --output-dir ../ui-preview --level quick --open
+```
+
+Либо укажите абсолютные пути. Замените пример пути приложения своим; сохраняйте кавычки вокруг путей с пробелами.
+
+Windows PowerShell:
+
+```powershell
+uidw --repo "C:/Projects/My App" config setup --detail medium
+uidw --repo "C:/Projects/My App" workbench --output-dir "C:/UI previews/My App" --level quick --open
+```
+
+macOS/Linux:
+
+```sh
+uidw --repo "$HOME/projects/my-app" config setup --detail medium
+uidw --repo "$HOME/projects/my-app" workbench --output-dir "$HOME/ui-previews/my-app" --level quick --open
+```
+
+`--repo` выбирает исходники. `--output-dir` выбирает каталог результатов и отсчитывается от текущего каталога терминала. Без него результат попадает в кеш проекта. Используйте отдельный каталог результата для каждого приложения.
+
+## 4. Проверьте результат
+
+| Файл | Назначение |
+| --- | --- |
+| `ui-preview.html` | Интерактивный предпросмотр; откройте в браузере |
+| `validation/fidelity-report.json` | Происхождение свойств и пробелы переноса |
+| `validation/ui-coverage.json` | Полнота переноса экранов и компонентов |
+| `validation/platform-profile-report.json` | Проверки платформенного профиля |
+
+При успехе терминал показывает путь к HTML и `проверка pass`. При ошибках он тоже может записать диагностический HTML. Наличие файла или открытого браузера не означает успешной проверки. Используйте `uidw fidelity report` и указанные отчёты; подробнее — [решение проблем](troubleshooting.ru.md).
+
+CLI преимущественно выводит сообщения на русском. Добавьте `--lang ru` к `workbench`, чтобы выбрать русский язык HTML. Параметр `--json` предназначен для машинной обработки вывода.
+
+## 5. При необходимости добавьте полные проверки
+
+`--level quick` проверяет модель без автоматизации браузера. `--level full` добавляет браузерные проверки и требует Node.js 22+ и Chrome, Edge или Chromium:
+
+```sh
+node --version
+uidw doctor
+uidw workbench --output-dir ../ui-preview --level full --open
+```
+
+Помощник использует встроенный [WebSocket API Node.js](https://nodejs.org/download/release/v22.15.0/docs/api/globals.html#websocket). Если браузер установлен нестандартно, задайте `CHROME_PATH`. Отсутствие инструментов приводит к ошибке полной проверки, а не к незаметному переходу на quick.
+
+Далее: [работа с предпросмотром](using-preview.ru.md) или [подключение агента](agent-integrations.ru.md).