ace-design 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d37d8d0a64624263443caca262cd611655266e79a92297907e2f7b97b60a29b8
+  data.tar.gz: df52ac9d0105eadcc42dffaefdc7ccf426c5573f36ef53803ad326b93432b0a3
+SHA512:
+  metadata.gz: 3ec7f5799a786b3b7cd41ea9b4bf867c44b164407247654df55344cc5e0a2f05677e8f09b3dc7f721c0a9a071878ab23e48f80e3a731a7ec677ddd9a8e3be746
+  data.tar.gz: 52b28ea636aed64853402a4d2d6c4c6d3a09be7ad5e5c6cc71fef63b3cb8844cbec65c4911b9e9d603fdffbd3524993e0f71f22b739d09c440d8bfed22b13cdf

data/.ace-defaults/design/config.yml

@@ -0,0 +1,9 @@
+design:
+  node: node
+  runtime_dir: .ace-local/design/runtime
+  run_root: .ace-local/design
+  timeout: 45
+  model: role:assign-engineer
+  agent_timeout: 600
+  language: en
+  input: []

data/.ace-defaults/design/contexts/app/component.md

@@ -0,0 +1,3 @@
+# Application component
+
+Design one reusable element with a minimal host. Show representative states relevant to the brief, such as selected, focused, disabled, loading, empty or invalid; do not invent irrelevant states. Define local interactions and keyboard/focus behavior. Keep content data-driven and demonstrate constrained container widths. Do not build a full application shell.

data/.ace-defaults/design/contexts/app/view.md

@@ -0,0 +1,3 @@
+# Application view
+
+Design one representative working screen with a clear primary task, navigation context and a local interaction. Account for scanning, selection and contextual detail. Explore alternative compositions without building every route or feature.

data/.ace-defaults/design/contexts/app.md

@@ -0,0 +1,3 @@
+# Application assumptions
+
+Organize information around the user's task. Keep status, actionable next steps and recovery clear. Balance density against scanning effort; experienced users may need compact interfaces. Use progressive disclosure for secondary information without hiding routine actions.

data/.ace-defaults/design/contexts/project.md

@@ -0,0 +1,7 @@
+# Shared design assumptions
+
+Start from the audience, task, existing brand and constraints. Prefer concrete hierarchy and useful content over decorative novelty. Treat these as adaptable starting points, never universal aesthetic bans.
+
+Preserve user intent and existing design language. Make primary actions identifiable; provide visible focus, meaningful labels, readable contrast and responsive reflow. Prefer familiar interaction patterns unless a departure helps the task. Respect reduced-motion needs.
+
+During exploration use one language, common mock data, minimal runnable artifacts and a small scope. Production integration, complete states and engineering verification follow explicit direction selection.

data/.ace-defaults/design/contexts/site/component.md

@@ -0,0 +1,3 @@
+# Website component
+
+Design one reusable element in a minimal preview host, not a whole page. Make hierarchy and action understandable in context. Show applicable interaction states and responsive container behavior. Avoid embedding page-specific navigation, unrelated sections or business logic.

data/.ace-defaults/design/contexts/site/view.md

@@ -0,0 +1,3 @@
+# Website view
+
+Design the first viewport and one supporting section. Connect the heading, primary action and supporting evidence. Show the intended reading order and behavior at a narrow viewport. Keep exploration focused on one page-level story.

data/.ace-defaults/design/contexts/site.md

@@ -0,0 +1,3 @@
+# Website assumptions
+
+Make the offer, audience and next action understandable quickly. Establish a deliberate reading rhythm. Use concrete evidence and meaningful links. Adapt imagery, density and typography to the subject and brand rather than applying a generic landing-page formula.

data/.ace-defaults/design/presets/ace-vs-taste.yml

@@ -0,0 +1,37 @@
+{
+  "description": "Three fast ACE directions and one original Taste v2 direction.",
+  "verification": "candidate",
+  "surfaces": [
+    "site"
+  ],
+  "kinds": [
+    "view"
+  ],
+  "intents": [
+    "explore",
+    "reimagine"
+  ],
+  "concurrency": 4,
+  "timeout": 1800,
+  "variants": [
+    {
+      "id": "a",
+      "preset": "fast",
+      "focus": "Direct action and clear hierarchy"
+    },
+    {
+      "id": "b",
+      "preset": "fast",
+      "focus": "Editorial storytelling and photographic context"
+    },
+    {
+      "id": "c",
+      "preset": "fast",
+      "focus": "Evidence and trustworthy comparison"
+    },
+    {
+      "id": "d",
+      "preset": "taste-v2"
+    }
+  ]
+}

data/.ace-defaults/design/presets/fast.yml

@@ -0,0 +1,18 @@
+concurrency: 3
+description: Fast runnable ACE mockups with shared data and lightweight checks
+verification: tested
+artifact_types: [html]
+process: ace
+directions:
+  -
+    component: Immediate affordance, visible actions and efficient interaction
+    site: Direct action, clear offer and confident hierarchy
+    app: Fast queue workflow with efficient scanning and actions
+  -
+    component: Clear content hierarchy, contextual detail and explicit state feedback
+    site: Editorial storytelling with a strong reading rhythm
+    app: Contextual detail with a split workspace and supporting history
+  -
+    component: Calm presentation, progressive disclosure and flexible container behavior
+    site: Evidence and proof, concrete outcomes and trustworthy comparison
+    app: Calm overview with progressive disclosure and clear priorities

data/.ace-defaults/design/presets/impeccable.yml

@@ -0,0 +1,48 @@
+{
+  "description": "Design engineering across product UI and sites: hierarchy, typography, responsive behavior and visual quality.",
+  "verification": "candidate",
+  "evidence": [
+    "Pinned upstream instructions inspected; complete ACE integration smoke not yet verified."
+  ],
+  "process": "external",
+  "surfaces": [
+    "site",
+    "app"
+  ],
+  "kinds": [
+    "view",
+    "component"
+  ],
+  "intents": [
+    "explore",
+    "recreate",
+    "reimagine"
+  ],
+  "artifact_types": [
+    "html",
+    "image",
+    "url"
+  ],
+  "timeout": 1800,
+  "requirements": [
+    {
+      "name": "Shell",
+      "executable": "sh"
+    },
+    {
+      "name": "Impeccable launcher and rendered browser checks",
+      "notes": "Original launcher may download its binary; provider policy applies."
+    }
+  ],
+  "limitations": [
+    "Original workflow is not shortened to ACE fast mode. Required checks may need tools unavailable to a provider."
+  ],
+  "skills": [
+    {
+      "source": "https://github.com/pbakaus/impeccable.git",
+      "revision": "6af45ac9a5eb8792f033d3242f52e99812fd91fa",
+      "entry": ".agents/skills/impeccable/SKILL.md",
+      "role": "lead"
+    }
+  ]
+}

data/.ace-defaults/design/presets/superdesign.yml

@@ -0,0 +1,48 @@
+{
+  "description": "Visual exploration, reproduction and iteration on the Superdesign canvas via its CLI.",
+  "verification": "candidate",
+  "evidence": [
+    "Pinned upstream instructions inspected; complete ACE integration smoke not yet verified."
+  ],
+  "process": "external",
+  "surfaces": [
+    "site",
+    "app"
+  ],
+  "kinds": [
+    "view",
+    "component"
+  ],
+  "intents": [
+    "explore",
+    "recreate",
+    "reimagine"
+  ],
+  "artifact_types": [
+    "html",
+    "image",
+    "url"
+  ],
+  "timeout": 1800,
+  "requirements": [
+    {
+      "name": "Node.js",
+      "executable": "node"
+    },
+    {
+      "name": "Superdesign authentication and service access",
+      "notes": "Original CLI uses its service and may invoke additional models; caller model selects the coding worker only."
+    }
+  ],
+  "limitations": [
+    "Original workflow is not shortened to ACE fast mode. Required checks may need tools unavailable to a provider."
+  ],
+  "skills": [
+    {
+      "source": "https://github.com/superdesigndev/superdesign-skill.git",
+      "revision": "f9f05cd988c247dce6c072eaf9ac6b162f2ffc4b",
+      "entry": "skills/superdesign/SKILL.md",
+      "role": "lead"
+    }
+  ]
+}

data/.ace-defaults/design/presets/taste-v2.yml

@@ -0,0 +1,46 @@
+{
+  "description": "Distinctive marketing pages with subject inventory, art direction, visual assets and critique.",
+  "verification": "candidate",
+  "evidence": [
+    "Pinned upstream instructions inspected; complete ACE integration smoke not yet verified."
+  ],
+  "process": "external",
+  "surfaces": [
+    "site"
+  ],
+  "kinds": [
+    "view"
+  ],
+  "intents": [
+    "explore",
+    "reimagine"
+  ],
+  "artifact_types": [
+    "html",
+    "image",
+    "url"
+  ],
+  "timeout": 1800,
+  "requirements": [
+    {
+      "name": "Node.js",
+      "executable": "node"
+    },
+    {
+      "name": "Browser inspection and image tools",
+      "notes": "Skill requires rendered checks and visual assets; worker must report unavailable tools."
+    }
+  ],
+  "limitations": [
+    "Original workflow is not shortened to ACE fast mode. Required checks may need tools unavailable to a provider.",
+    "Upstream excludes application UI. Use a separately named explicit adaptation for apps."
+  ],
+  "skills": [
+    {
+      "source": "https://github.com/Leonxlnx/taste-skill.git",
+      "revision": "f624f37a8c650b9cc550253104925efe4c8de246",
+      "entry": "skills/taste-skill/SKILL.md",
+      "role": "lead"
+    }
+  ]
+}

data/.ace-defaults/design/presets/ui-ux-pro-max.yml

@@ -0,0 +1,48 @@
+{
+  "description": "Searchable UI/UX knowledge for accessibility, interaction, styles, typography and stack-specific implementation.",
+  "verification": "candidate",
+  "evidence": [
+    "Pinned upstream instructions and search scripts exercised in the 2026-10-16 mixed smoke. Browser checks blocked by provider policy; complete integration remains unverified."
+  ],
+  "process": "external",
+  "surfaces": [
+    "site",
+    "app"
+  ],
+  "kinds": [
+    "view",
+    "component"
+  ],
+  "intents": [
+    "explore",
+    "recreate",
+    "reimagine"
+  ],
+  "artifact_types": [
+    "html",
+    "image",
+    "url"
+  ],
+  "timeout": 1800,
+  "requirements": [
+    {
+      "name": "Python 3",
+      "executable": "python3"
+    },
+    {
+      "name": "Rendered browser verification",
+      "notes": "Original delivery checklist requires keyboard, responsive, motion and reflow checks; provider must support browser execution."
+    }
+  ],
+  "limitations": [
+    "Original workflow is not shortened to ACE fast mode. Required checks may need tools unavailable to a provider."
+  ],
+  "skills": [
+    {
+      "source": "https://github.com/nextlevelbuilder/ui-ux-pro-max-skill.git",
+      "revision": "56ea9cf174ed86786187daa9de0e6247cb0747e4",
+      "entry": ".claude/skills/ui-ux-pro-max/SKILL.md",
+      "role": "lead"
+    }
+  ]
+}

data/.ace-defaults/nav/protocols/guide-sources/ace-design.yml

@@ -0,0 +1,8 @@
+name: ace-design
+type: gem
+description: Design guide resources
+priority: 10
+config:
+  relative_path: handbook/guides
+  pattern: "*.g.md"
+  enabled: true

data/.ace-defaults/nav/protocols/skill-sources/ace-design.yml

@@ -0,0 +1,8 @@
+name: ace-design
+type: gem
+description: Design skill resources
+priority: 10
+config:
+  relative_path: handbook/skills
+  pattern: "*/SKILL.md"
+  enabled: true

data/.ace-defaults/nav/protocols/tmpl-sources/ace-design.yml

@@ -0,0 +1,8 @@
+name: ace-design
+type: gem
+description: Design tmpl resources
+priority: 10
+config:
+  relative_path: handbook/templates
+  pattern: "*.template.md"
+  enabled: true

data/.ace-defaults/nav/protocols/wfi-sources/ace-design.yml

@@ -0,0 +1,8 @@
+name: ace-design
+type: gem
+description: Design wfi resources
+priority: 10
+config:
+  relative_path: handbook/workflow-instructions
+  pattern: "*.wf.md"
+  enabled: true

data/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.2.0] - 2026-10-16
+
+### Added
+- Repeatable `--prompt-append`, inherited session briefs and explicit base replacement, with frozen composition and effective dry-run output.
+- Intent commands `explore`, `recreate` and `reimagine`, immutable image/URL/session sources, and a unified pinned preset catalog with original external processes and typed artifacts.
+- Preset inspection, JSON output, model-free planning, and model-assisted unpublished profile proposals.
+- Inherited project contexts with defaults.md, user.md and effective design.md, transactional AI-assisted adjust/refresh, inspectable reports, freshness checks and site/app adjust skills.
+- View/component task scopes, packaged context defaults and immutable design assumptions in generation sessions.
+- Preset-driven coding-agent generation with shared context/fixtures, per-variant prompts and model assignments, dry-run, status, resume, revision history and explicit selection.
+- Site/app exploration, implementation and audit skills with a shared fast feedback process.
+- Local session validation and loopback preview, pinned Playwright/axe inspection and runtime doctor.
+- Curated contextual cards, six benchmark briefs and an inspiration-to-reviewed-change workflow.
+
+### Changed
+- Replace `generate`, `--context` and `--design-context` with intent commands, `--input` and `--profile`; group project rules under `profile show/adjust/refresh`.
+- Drive site/app exploration through the CLI runner; declare variable-count session variants and bind selection to both artifact and fixture hashes.
+- Compare scaled desktop, tablet and mobile previews with collapsible direction notes.
+- Create mockup sessions under `.ace-local/design/<base36-token>/` using ace-b36ts millisecond tokens.
+- Give default inspection output directories a unique suffix to avoid same-timestamp collisions.
+
+### Fixed
+- Require Node 22.12+ for the pinned inspection dependency and regenerate skills from canonical sources.
+- Isolate embedded variants from gallery DOM access while retaining shared fixtures, and return not-found for directory requests.
+- Preserve child exit status with surviving descendants, clean up interrupted captures, and reject fractional execution limits.
+- Retry readonly profile reads safely when the first publisher creates the transaction lock.
+- Validate missing shared inputs before session allocation and provide complete skill metadata and domain-specific benchmark fixtures.
+- Reject runner sessions missing their task kind or frozen design digest with an actionable error and omit empty user-decision sections.
+- Reuse fresh design ancestors during targeted adjustment and retain the exact published candidate for manual-edit recovery.
+- Preserve the original worker failure or interrupt when diagnostic writes fail, and join every worker before releasing the session lock.
+- Avoid re-raising a caller-handled exception after a successful run; retain recoverable state when final persistence fails.
+- Preserve incomplete browser evidence when browser cleanup fails.
+- Report missing, dangling and cyclic session symlinks as actionable session errors.
+- Use `.template.md` filenames so all packaged design templates resolve through `tmpl://`.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Michal Czyz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,119 @@
+# ace-design
+
+Fast interactive design directions for websites and web applications, followed by production engineering and evidence-based review.
+
+## Skills
+
+| Skill | Outcome |
+| --- | --- |
+| `/as-design-site` | Three lightweight website directions using one shared fixture |
+| `/as-design-app` | Three lightweight web application directions using one shared fixture |
+| `/as-design-site-adjust` / `/as-design-app-adjust` | Personalize and refresh inherited project design assumptions |
+| `/as-design-site-implement` | Production site implementation from an explicit selection |
+| `/as-design-app-implement` | Production app implementation from an explicit selection |
+| `/as-design-site-audit` | Site audit with explicit browser/source coverage |
+| `/as-design-app-audit` | App audit with explicit browser/source coverage |
+| `/as-design-look-for-inspiration` | A researched, tested change prepared for review |
+
+Mockup sessions live at `.ace-local/design/<base36-token>/`, using `ace-b36ts encode --format ms`. The session directory contains all variants, shared fixtures, gallery, feedback and selection. Gallery refresh reflects saved progress, not worker liveness; after a crash use `status` and explicitly `resume`. Embedded variants run without same-origin access to the gallery; the preview server exposes public mockup assets with CORS so shared-fixture requests still work. This is parent-page isolation, not a network security sandbox.
+
+Explore → compare A/B/C → targeted feedback → select → engineer → verify. Exploration uses one language, mock data and minimal HTML/CSS/JS. Each direction runs in its own coding agent through ace-llm, with concurrency controlled by the design preset. Full review, real integrations, translations and production tests start after selection. Native platforms are intentionally separate future work.
+
+## Install and discover
+
+The source package is not yet published. In this monorepo use `bundle install` and `bin/ace-design`. After publication, consumers can install `ace-design`, plus `ace-handbook` and `ace-bundle` for skills, and `ace-search` for knowledge retrieval. Runtime CLI depends only on its declared Ruby dependencies and Node for preview/browser work.
+
+Register installed skills explicitly in the consuming project at `.ace/nav/protocols/skill-sources/ace-design.yml`:
+
+```yaml
+name: ace-design
+type: gem
+priority: 10
+config:
+  relative_path: handbook/skills
+  pattern: "*/SKILL.md"
+  enabled: true
+```
+
+Then run `ace-handbook sync --provider agents`. Canonical sources ship in `handbook/skills`; generated skills belong in `.agents/skills`. The package also ships protocol registrations for `wfi://design/*`, `guide://design/process` and `tmpl://design/*`. In this checkout use `bundle exec ace-handbook sync --provider agents` (no handbook binstub is committed).
+
+## Project assumptions
+
+Use `ace-design profile adjust --surface app --prompt "Keep routine actions visible"` to create inherited project contexts in `.ace-config/design/`. Each context has defaults.md, user.md and effective design.md. `profile refresh` brings in installed library changes without rewriting user decisions. `ace-design profile show --surface app --kind component` reads the effective assumptions. See [contexts and adjustment](docs/contexts.md) for named scopes, conflicts, dry-run and recovery.
+
+## Generate and iterate
+
+```sh
+bin/ace-design explore --surface app --prompt "Customer support workspace" \
+  --preset fast --input docs/product.md \
+  --variant-prompt 'a=Fast, keyboard-friendly queue' \
+  --variant-prompt 'b=Prominent customer history' \
+  --variant-prompt 'c=Calm overview'
+bin/ace-design status .ace-local/design/SESSION
+bin/ace-design preview .ace-local/design/SESSION
+bin/ace-design revise .ace-local/design/SESSION --variant b --prompt "Reduce density"
+bin/ace-design select .ace-local/design/SESSION --variant b --decision "Keep split layout"
+```
+
+`--kind view|component` selects a representative screen or a component in a minimal interactive host. `--profile app/component/data-table` selects a named project context; generation freezes its effective assumptions for every worker and later revision.
+
+Commands return concise text by default; `--json` returns structured output. `--dry-run` resolves inputs without models or a session. `resume SESSION` retries unfinished workers. Exit 0 means success or a valid dry-run, 1 means invalid inputs/configuration, and 2 means incomplete execution. Ctrl-C preserves completed results and records interruption.
+
+Default `fast` has three slots and concurrency three. Model selection defaults to `role:assign-engineer`, respecting the existing ace-llm configuration and execution policies. It requires a configured coding CLI and credentials. Use design `model`, `--model`, or per-slot selectors to customize it. This is an agent-capable CLI workflow; API-only text models are not supported as primary workers.
+
+Preparation creates one shared dataset and differentiated briefs; `--fixtures FILE` preserves supplied JSON bytes instead. Explicit `--input` references are rendered once through ace-bundle with commands and model compression disabled. There is no implicit full-project bundle. `--language` chooses one language (default `en`). Only successful, validated worker artifacts are published; failed revisions keep the previous mockup. Browser inspection remains an explicit later step.
+
+See [runner configuration and lifecycle](docs/runner.md) for custom variants, model assignments, extra prompts, evidence and recovery.
+
+## Local commands
+
+```sh
+bin/ace-design --help
+bin/ace-design validate
+bin/ace-design validate .ace-local/design/8xff3p3z
+bin/ace-design preview .ace-local/design/8xff3p3z --port 0
+bin/ace-design doctor
+bin/ace-design inspect http://127.0.0.1:3000 --surface app --out .ace-local/design/check-1
+```
+
+Use unprefixed commands for an installed consumer outside this monorepo. Preview binds only `127.0.0.1`, prints a free port by default, serves session assets and stops on Ctrl-C. It needs Node 22+, but no npm packages or Playwright. Browser inspection needs the separate pinned runtime below. The explore/recreate/reimagine/revise commands launch coding agents through ace-llm. Skills guide the brief, variant-specific prompts, feedback and engineering handoff; the runner owns repeatable execution and artifacts.
+
+Inspection returns 0 for clean automatic checks, 1 for findings and 2 for incomplete execution. Invalid inspect input also returns an error; no existing evidence is overwritten. Other commands return 0 on success and nonzero on error. `doctor` is read-only and reports missing setup. A clean report does not establish full accessibility, task completion, visual quality, performance or source correctness.
+
+## Browser setup
+
+From this checkout:
+
+```sh
+mkdir -p .ace-local/design/runtime
+cp ace-design/browser/package.json ace-design/browser/package-lock.json .ace-local/design/runtime/
+npm ci --ignore-scripts --prefix .ace-local/design/runtime
+npx --prefix .ace-local/design/runtime playwright install chromium
+bin/ace-design doctor
+```
+
+For an installed gem, `ace-design doctor` reports `manifest_dir` and `runtime_dir`; copy package.json and package-lock.json from the reported manifest directory to the runtime directory, run npm ci there, and install Chromium there with the local Playwright command. Node 22.12+ is required for inspection. Linux hosts may additionally require Playwright system dependencies. Dependencies are pinned; mismatched versions fail explicitly.
+
+Configuration follows the standard ACE cascade in `.ace/design/config.yml`:
+
+```yaml
+design:
+  node: node
+  runtime_dir: .ace-local/design/runtime
+  run_root: .ace-local/design
+  timeout: 45
+```
+
+Timeout is 1–300 seconds per viewport; the parent bounds the complete run. Runtime/run paths are relative to the invoking working directory. Inspect uses 390, 768 and 1440 pixel viewports, screenshots, axe WCAG-tagged checks, document overflow, image loading and JavaScript/page-load errors. It saves JSON and Markdown with coverage limitations. Image checks observe a bounded loading window: an image still loading is a finding, not proof of a permanently broken asset. A timed-out browser operation may leave partial screenshots; only artifacts listed in the final report are evidence. It has no authenticated-session injection: use an accessible local/test URL or report inaccessible states and verify them separately with an authorized browser session.
+
+## More
+
+- [Session and feedback contract](docs/usage.md)
+- [Inspiration sources and weekly prompt](docs/inspiration.md)
+- [Verification and benchmark protocol](docs/testing.md)
+- [Shared workflows](handbook/workflow-instructions/design/)
+- [Curated cards](handbook/catalog/)
+
+## Intent and presets
+
+Use `explore` for new directions, `recreate --from SOURCE` for faithful reproduction, and `reimagine --from SOURCE` for a different appearance with the same functions. Sources can be images, URLs or session variants. `preset list` and `preset show NAME` expose original external skills and comparison presets, requirements and verification evidence. See [runner](docs/runner.md). `--dry-run` is model-free and creates no session; `--json` gives machine-readable results.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test" << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task spec: :test
+task default: :test

data/browser/dependencies.mjs

@@ -0,0 +1,20 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {createRequire} from 'node:module';
+const expected = JSON.parse(fs.readFileSync(new URL('./package.json', import.meta.url),'utf8')).dependencies;
+export function dependencies(directory) {
+  const [major, minor] = process.versions.node.split('.').map(Number);
+  if (major < 22 || (major === 22 && minor < 12)) throw new Error('Node 22.12+ is required for browser inspection');
+  const base = path.resolve(directory);
+  for (const [name,version] of Object.entries(expected)) {
+    const file = path.join(base,'node_modules',name,'package.json');
+    if (!fs.existsSync(file)) throw new Error(`Missing ${name}@${version}; copy packaged browser/package*.json to runtime_dir and run npm ci there`);
+    const installed = JSON.parse(fs.readFileSync(file,'utf8')).version;
+    if (installed !== version) throw new Error(`Expected ${name}@${version}, found ${installed}; run npm ci with the packaged lockfile`);
+  }
+  const require = createRequire(path.join(base,'package.json'));
+  const {chromium} = require('playwright');
+  if (!fs.existsSync(chromium.executablePath())) throw new Error('Chromium missing; run npx playwright install chromium in runtime_dir');
+  const axe = require('@axe-core/playwright');
+  return {chromium, AxeBuilder: axe.default || axe, versions: expected};
+}

data/browser/doctor.mjs

@@ -0,0 +1,7 @@
+import {dependencies} from './dependencies.mjs';
+try {
+ const {chromium,versions} = dependencies(process.argv[2]);
+ const browser = await chromium.launch({headless:true});
+ await browser.close();
+ console.log(JSON.stringify({ready:true,node:process.version,versions,browser:chromium.executablePath()}));
+} catch(e) {console.log(JSON.stringify({ready:false,node:process.version,error:e.message}));process.exitCode=1;}

data/browser/inspect.mjs

@@ -0,0 +1,61 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {dependencies} from './dependencies.mjs';
+const [url,surface,out,runtime,seconds='45'] = process.argv.slice(2);
+const timeout = Number(seconds)*1000;
+const report = {schema_version:1,url,surface,status:'incomplete',viewports:[],findings:[],errors:[],coverage:{automated:['axe WCAG 2.2 A/AA','document overflow','broken images','page load and JavaScript errors'],manual_required:['visual hierarchy','text clipping and overlays','keyboard task completion','required states and languages','brand and content fit'],source:'not inspected'}};
+let browser;
+const add = (rule,width,details) => report.findings.push({rule,width,...details});
+try {
+ if(!['site','app'].includes(surface)) throw new Error('surface must be site or app');
+ const target=new URL(url);
+ if(!['http:','https:'].includes(target.protocol)||target.username||target.password) throw new Error('HTTP(S) URL without credentials required');
+ const {chromium,AxeBuilder,versions}=dependencies(runtime);
+ report.versions=versions;
+ browser=await chromium.launch({headless:true});
+ for (const [width,height] of [[390,844],[768,1024],[1440,900]]) {
+  const context=await browser.newContext({viewport:{width,height},reducedMotion:'reduce'});
+  const page=await context.newPage();
+  page.setDefaultTimeout(timeout);
+  page.setDefaultNavigationTimeout(timeout);
+  page.on('pageerror',e=>add('javascript-error',width,{message:e.message}));
+  let timer;
+  try {
+   const audit = async()=>{
+    const response=await page.goto(url,{waitUntil:'load'});
+    if(!response || response.status()>=400) throw new Error(`HTTP load failed: ${response?.status() ?? 'no response'}`);
+    await page.evaluate(()=>document.fonts.ready);
+    // Trigger lazy content once, with a bounded number of screens, then return to the top.
+    const screens=await page.evaluate(()=>Math.min(12,Math.ceil(document.body.scrollHeight/innerHeight)));
+    for(let i=1;i<screens;i++){await page.evaluate(y=>scrollTo(0,y),i*height);await page.waitForTimeout(80);}
+    await page.evaluate(()=>scrollTo(0,0));
+    const metrics=await page.evaluate(()=>({
+      overflow:document.documentElement.scrollWidth>innerWidth+1,
+      broken:[...document.images].filter(i=>i.complete && !i.naturalWidth).map(i=>i.getAttribute('src')),
+      pending:[...document.images].filter(i=>!i.complete).map(i=>i.getAttribute('src')),
+      title:document.title
+    }));
+    if(metrics.overflow)add('horizontal-overflow',width,{message:'Document exceeds viewport width'});
+    for(const src of metrics.broken)add('broken-image',width,{src});
+    for(const src of metrics.pending)add('image-not-loaded',width,{src});
+    const screenshot=`viewport-${width}.png`;
+    await page.screenshot({path:path.join(out,screenshot),fullPage:true,animations:'disabled',timeout});
+    const accessibility=await new AxeBuilder({page}).withTags(['wcag2a','wcag2aa','wcag21a','wcag21aa','wcag22aa']).analyze();
+    for(const violation of accessibility.violations)add('accessibility',width,{id:violation.id,impact:violation.impact,message:violation.help,help_url:violation.helpUrl,nodes:violation.nodes.map(n=>({target:n.target,summary:n.failureSummary}))});
+    report.viewports.push({width,height,screenshot,title:metrics.title,axe_incomplete:accessibility.incomplete.map(v=>({id:v.id,help:v.help})),status:'inspected'});
+   };
+   await Promise.race([audit(),new Promise((_,reject)=>{timer=setTimeout(()=>reject(new Error('Viewport inspection timed out')),timeout);})]);
+  } catch(e) {report.errors.push({width,message:e.message});}
+  finally {clearTimeout(timer);await context.close();}
+ }
+ report.status=report.errors.length || report.viewports.length!==3 ? 'incomplete' : report.findings.length ? 'findings' : 'pass';
+} catch(e){report.errors.push({message:e.message});}
+finally {
+ try {if(browser)await browser.close();}
+ catch(e){report.errors.push({message:`Browser cleanup failed: ${e.message}`});report.status='incomplete';}
+ fs.writeFileSync(path.join(out,'report.json'),JSON.stringify(report,null,2)+'\n');
+ const lines=[`# Design inspection: ${report.status}`,`\nSurface: ${surface}`,`\nURL: ${url}`,`\nViewports inspected: ${report.viewports.length}/3`,`\nFindings: ${report.findings.length}`,`\n## Findings`,...report.findings.map(f=>`- ${f.width}px ${f.rule}: ${f.message || f.src || f.id}`),`\n## Errors`,...report.errors.map(e=>`- ${e.width || 'runner'}: ${e.message}`),`\n## Coverage`,`\nAutomated: ${report.coverage.automated.join('; ')}.`,`\nStill requires review: ${report.coverage.manual_required.join('; ')}.`,`\nSource: not inspected. A pass only covers the automatic checks.`,...report.viewports.map(v=>`\n![${v.width}px](${v.screenshot})\nAxe checks requiring review: ${v.axe_incomplete.length}.`)];
+ fs.writeFileSync(path.join(out,'report.md'),lines.join('\n')+'\n');
+ console.log(JSON.stringify({status:report.status,report:path.join(out,'report.json')}));
+ process.exitCode=report.status==='pass'?0:report.status==='findings'?1:2;
+}