IBR is an end-to-end design tool for AI coding agents. It guides UI builds with Design Director planning, web and iOS archetype routing, Calm Precision principles, and platform-specific best practices. Built-in visual validation scans live pages, runs interaction assertions, matches mockups, and verifies design intent — Chrome and Safari.

Built on a custom CDP engine — no Playwright. Works from terminal, Codex, Claude Code slash commands, or code. Zero config.

Design Workflow

/ibr:build <topic> orchestrates the full design-to-validation flow:

1. Preamble — Platform, scope, design mode, archetype hints, UI template, references, density
2. Optional imagegen concepts — Generates visual concepts only when useful, then requires approval before any concept becomes a visual-target
3. Design Director — Produces design-intent.json, specialist planning passes, target roles, and validation criteria
4. Brainstorm & Plan — Guided exploration with platform-specific design rules and a concrete implementation plan
5. Implement — Build with design guidance: Calm Precision, web/iOS/macOS routers, component patterns, data-viz guidance when needed
6. Validate — Scan, match wireframe/visual targets, test interactions, iterate until passing

Design Director

The design-director skill is the primary planning layer for page, flow, app, dashboard, and reference-heavy UI work. It selects guidance in a deterministic order, resolves Mockup Gallery references into roles (wireframe-target, visual-target, inspiration, data-reference), and writes specialist planning artifacts under .ibr/builds/<topic>/specialists/.

Specialist passes are used for flow, visual system, interaction states, content states, Mockup Gallery targets, data visualization, and validation. IBR does not create separate tiny agents for buttons, fonts, or individual visual atoms; those stay inside component patterns and design tokens.

Imagegen Concepts

IBR can use imagegen as an upstream concept pass for mood, style, hero/product imagery, and hi-fi variants. Generated concepts are saved under .ibr/builds/<topic>/references/imagegen/ when they are project-bound. They remain inspiration until the user explicitly approves one as a visual-target.

Imagegen does not replace wireframes, accessibility semantics, interaction requirements, or validation. IBR still validates the rendered implementation with scan, interaction, match, and native tools.

Web Design Routing

The web-design-router skill classifies web interfaces into archetypes: SaaS dashboard, data/research tool, editor/workbench, AI agent chat, commerce/checkout, content/publication, and internal admin. Each archetype sets defaults for navigation, density, primary content, mobile behavior, and validation focus.

iOS Design System

The ios-design-router skill classifies apps into 6 archetypes, each with pre-set defaults for navigation, color, typography, motion, and more. Domain reference files provide comprehensive option catalogs:

| Domain | Reference | Covers | |--------|-----------|--------| | Navigation | 1_navigation_structure.md | Tab bars, transitions, sheets, page hierarchy | | Content | 2_lists_cards_content.md | Lists, cards, swipe actions, content resilience | | Interactions | 3_buttons_touch_interactions.md | Buttons, haptics, toggles, forms | | Visual | 4_color_surface_typography.md | Color, gradients, dark mode, typography | | Motion & States | 5_motion_states_identity.md | Loading, onboarding, celebrations, profiles | | Task Economy | 6_task_economy.md | Step counting, flow validation |

Two-Tier Architecture

IBR scans return structured data, not just raw element dumps. Two layers run on every scan:

Tier 1 — Deterministic Rule Engine (no LLM)

Runs pure algorithms against the runtime data. Zero tokens. Returns structured verdicts with evidence.

| Rule Preset | What It Checks | Algorithm | |-------------|---------------|-----------| | wcag-contrast | Text contrast ratios, AA and AAA | WCAG 2.1 relative luminance | | touch-targets | Interactive element sizing | 44px mobile (WCAG 2.5.5), 24px desktop (WCAG 2.5.8) | | calm-precision | Gestalt, Signal-to-Noise, Fitts, Hick, Content-Chrome, Cognitive Load | Principle-based checks |

Enable via .ibr/rules.json:

{
  "extends": ["wcag-contrast", "touch-targets", "calm-precision"]
}

Or one-off via CLI:

ibr scan http://localhost:3000 --rules wcag-contrast,touch-targets

Output in scanResult.issues with ruleId, severity, message, element, and fix fields.

ibr ask — focused verdicts (v3 thesis M1)

Where scan returns the whole tree, ask returns one verdict + minimal evidence. ~600 bytes vs ~19KB for the same page.

ibr ask http://localhost:3000 'is the touch-target compliant'
ibr -v mobile ask http://localhost:3000 'do status indicators follow signal-to-noise'
ibr ask http://localhost:3000 'is design-system token compliance okay'

Closed question vocabulary today (3 questions); unknown questions return verdict: UNCERTAIN with the supported list. Returns {verdict, findings[], meta} with bounds and a fix per finding. Designed for LLM agents — the agent reads a verdict, optionally drills into one finding's evidence, instead of parsing the full DOM.

Tier 2 — Sensor Layer (structured summaries)

Pre-computed summaries that let the model focus on judgment instead of re-discovering patterns:

| Sensor | What It Produces | Token Saving | |--------|------------------|--------------| | visualPatterns | Groups elements by style fingerprint per category (button, link, input, heading) | Replaces N element dumps with M pattern groups | | componentCensus | Tag/role counts + orphan cursor:pointer elements with no handler | Replaces grep across pages | | interactionMap | Handler coverage — which interactive-looking elements actually have handlers | Pre-computed from handler detection | | contrast | WCAG pass/fail grouped, only failures listed | Model skips passing elements | | navigation | Link structure with depth and counts | Replaces reading Sidebar.tsx | | semanticState | Wraps existing semantic classifier: page intent, states, available actions | Summary form | | oneLiners | 5-second scannable summary lines | Read first, then drill down |

Access in scanResult.sensors. Get summaries-only (cuts ~60% tokens):

ibr scan http://localhost:3000 --output summary

Hydration Waiting

SPAs (Next.js, React, Vue) often render after networkidle fires. IBR's waitForHydration() runs after network idle:

1. Fast-path marker detection: window.__NEXT_DATA__, React DevTools hook, #__next / #root population
2. AX tree fingerprint polling until stable for 500ms with at least one interactive element
3. Settle time (200ms default) to absorb async effects

This eliminates the common "0 elements" result on modern SPAs.

Live Sessions with Auto-Capture

Sessions now auto-capture pre/post interaction by default:

ibr session start http://localhost:3000
ibr session interact --action click --target "Submit"
# Automatically: pre-scan baseline -> action -> URL change detection -> hydration wait -> post-scan -> surface console errors
ibr session close

Each ActionRecord includes:

• navigated: boolean — did the click cause a URL change?
• urlBefore / urlAfter
• actionErrors: string[] — console errors that appeared during this action

Opt out with --no-auto-capture on session start.

Architecture

IBR runs on a custom CDP browser engine — direct Chrome DevTools Protocol over WebSocket. No Playwright, no Puppeteer, no heavyweight browser automation dependencies.

LLM-native features built into the engine:

| Feature | What it does | |---------|-------------| | queryAXTree-first resolution | Find elements by semantic name+role (not fragile CSS selectors). 4-tier: CDP-native search → Jaro-Winkler fuzzy → vision fallback | | DOM chunking | Filter to interactive/leaf elements, chunk for LLM context windows. 60-70% fewer tokens | | Adaptive modality | Scores AX tree quality. High → use text data. Low → include screenshot. Vision only when needed | | Resolution cache | Caches intent→element mappings. Same query twice = instant. Clears on navigation | | observe() | Preview available actions without executing. Returns serializable descriptors | | extract() | Pull structured data from AX tree using schemas |

What's New in v1.4.0

| Feature | Command / Usage | What it does | |---------|----------------|-------------| | Native macOS layout-fill / gap analysis | scanMacOS returns layoutFill[]; surfaced as layout-fill: WARNINGs in issues[] | Per-container largest empty horizontal AND vertical band as pixels + % of container extent. Catches the centered-narrow-content bug class (e.g. terminal at 440px centered in 1074px → 317px / 29.5% leading band) that passes screenshot + a11y + touch-target checks. Threshold default 0.12; configurable via MacOSScanOptions.layoutFill.threshold | | Swift extractor --analyze-layout | ibr-ax-extract --pid N --analyze-layout | Same algorithm in-Swift; emits LAYOUT_FINDINGS:<json> on stderr. Stdout JSON contract unchanged | | Drop-in Swift templates | assets/native/swift-templates/LayoutProbe.swift + RenderSwiftUI.swift | In-process layout dump + wedge-proof cacheDisplay PNG when AX/screencapture are wedged. Off-screen SwiftUI → PNG renderer. Pure AppKit/SwiftUI, zero deps |

What's New in v0.7.0

| Feature | Command | What it does | |---------|---------|-------------| | Interact (MCP + CLI) | ibr interact / MCP interact | Click, type, fill elements by accessible name. LLM-native interaction | | Observe (MCP + CLI) | ibr observe / MCP observe | Preview all clickable/fillable elements before interacting | | Extract (MCP + CLI) | ibr extract / MCP extract | Read page headings, buttons, inputs, links as structured data | | Interact & Verify (MCP) | MCP interact_and_verify | Act + capture before/after state diff (elements added/removed) | | Interaction assertions | ibr test-interact | Click, type, verify — act→verify→screenshot pipeline | | Mockup matching | ibr match | Compare design mockup PNG against live page (SSIM) | | Design verification | ibr record-change / ibr verify-changes | Capture design intent, verify against reality | | Test generation | ibr generate-test | Auto-generate .ibr-test.json from page observation | | Test runner | ibr test | Run declarative test files | | Python scripting | ibr run-script | Execute Python test scripts with sandboxed resources | | Fix-and-iterate | ibr iterate | Convergence detection for test-fix cycles | | Safari support | --browser safari | Cross-browser via safaridriver + macOS AX API | | Cross-browser diff | ibr compare-browsers | Side-by-side Chrome vs Safari comparison | | AX tree coverage | Built into ibr scan | Reports AX tree capture %, shadow DOM piercing | | Flow testing | ibr test-search/form/login | Built-in flows exposed as CLI commands | | Playwright removed | -- | Zero Playwright dependency, custom CDP engine only |

See docs/QUICK-START.md for full usage guide.

What's New in v1.0.0

| Feature | Command / Usage | What it does | |---------|----------------|-------------| | End-to-end design tool | Positioning update | From "visual testing platform" to design + build + validate | | Design Director | /ibr:build | Primary design-agent layer with design intent, specialist planning passes, target roles, and validation criteria | | Web design router | skill: web-design-router | 7 web archetypes covering dashboards, research tools, workbenches, AI chat, checkout, content, and admin | | Data visualization guidance | skill: data-visualization | Chart-worthiness gate, chart routing, attribution, accessibility, and validation rules | | iOS design system | /ibr:build with platform=iOS | 6-archetype router, 7 domain reference files covering navigation, lists, buttons, color, motion, task economy | | apple-platform skill | Loaded during iOS builds | Architecture, SwiftData, concurrency, CI/CD, TestFlight — integrated from standalone apple-dev | | Deterministic rule engine | ibr scan --rules wcag-contrast,touch-targets | WCAG AA/AAA contrast, touch target sizes. No LLM tokens | | Sensor layer | scanResult.sensors | Visual patterns, component census, interaction map, contrast report, navigation, one-liners | | Summary output mode | ibr scan --output summary | Returns sensors + verdict, cuts ~60% of tokens | | Hydration wait | Built into ibr scan | Fixes "0 elements" on SPAs; polls AX tree stability + detects Next.js/React markers | | Auto-capture sessions | Default on | Pre/post scan with URL-change detection and console error surfacing |

What's New in v0.9.0-alpha

| Feature | Command / Skill | What it does | |---------|----------------|-------------| | Build command | /ibr:build <topic> | Guided UI build — brainstorm, plan, implement, verify in one flow | | Capture command | /ibr:capture <url> | Capture a named baseline snapshot for any URL | | UI guidance | /ibr:ui-guidance | On-demand design guidance using IBR scan data | | UI brainstorm preamble | skill: ui-brainstorm-preamble | Pre-build exploration — explore directions before implementing | | UI guidance library | skill: ui-guidance-library | Reusable UI guidance patterns and decision aids | | Mockup gallery bridge | skill: mockup-gallery-bridge | Bridge mockup gallery reviews to IBR scan verification | | Mobile web UI | skill: mobile-web-ui | Mobile web patterns — responsive design, touch targets, viewport handling | | iOS Design | skill: ios-design | iOS-specific patterns — SwiftUI conventions, safe areas, haptics | | macOS UI | skill: macos-ui | macOS-specific patterns — AppKit/SwiftUI, menu bar, window chrome |

The Problem

User says "make the buttons blue with 16px Inter font." You build it. But did it work?

• Screenshots — you're guessing hex codes from pixels
• Manual inspection — slow, error-prone, not automatable
• IBR scan — returns backgroundColor: "rgb(59, 130, 246)", fontSize: "16px", fontFamily: "Inter". Done.

How It Works

# User describes what they want -> you build it -> validate with IBR
npx ibr scan http://localhost:3000/page --json

IBR returns structured data per element:

• computedStyles — backgroundColor, fontSize, fontFamily, padding, grid, flexbox, etc.
• bounds — exact x, y, width, height
• interactive — hasOnClick, hasHref, hasReactHandler, isDisabled
• a11y — role, ariaLabel, ariaDescribedBy
• page-level — pageIntent, auth state, loading state, console errors

For regression, capture before and compare after:

npx ibr start http://localhost:3000    # baseline before changes
# ... edit your code ...
npx ibr check                          # see what changed

Verdicts: MATCH, EXPECTED_CHANGE, UNEXPECTED_CHANGE, LAYOUT_BROKEN

Quick Start

npm install @tyroneross/interface-built-right

That's it. .ibr/ is auto-added to your .gitignore on install.

Validate UI (primary workflow):

npx ibr scan http://localhost:3000 --json    # get structured data

Regression check:

npx ibr start http://localhost:3000    # capture baseline
# ... make changes ...
npx ibr check                          # compare

Sandbox-friendly browser attach

Use connect mode when the agent can reach a Chrome DevTools endpoint but should not spawn Chrome itself.

npx ibr scan http://localhost:3000 \
  --browser-mode connect \
  --cdp-url http://127.0.0.1:9222

You can also provide a browser WebSocket directly:

npx ibr scan http://localhost:3000 \
  --browser-mode connect \
  --ws-endpoint ws://127.0.0.1:9222/devtools/browser/<id>

Environment variables are supported for sandboxed agents and wrappers:

IBR_BROWSER_MODE=connect
IBR_CDP_URL=http://127.0.0.1:9222
IBR_WS_ENDPOINT=ws://127.0.0.1:9222/devtools/browser/<id>
IBR_CHROME_PATH=/path/to/chrome

--headed is now the preferred flag for a visible browser window. --sandbox remains as a deprecated alias for backwards compatibility.

Setup as Agent Plugins

IBR works standalone and ships plugin metadata for both Claude Code and Codex. Claude Code gets slash commands, hooks, and the design-validator agent; Codex gets compact routing skills plus MCP/session tools for the same scan, navigation, search, and validation contract.

Claude Code

1. Add the marketplace (one-time):

/plugin marketplace add tyroneross/interface-built-right

2. Install the plugin:

/plugin install ibr@interface-built-right

3. Use in conversation:

| Command | What it does | |---------|-------------| | /ibr:build <topic> | Guided UI build: preamble → brainstorm → plan → implement → validate | | /ibr:scan <url> | Full page scan with sensor summaries and optional rule checks | | /ibr:snapshot / /ibr:compare | Before/after regression check | | /ibr:interact | Click, type, fill by accessible name | | /ibr:match | Compare rendered UI against a mockup (SSIM) | | /ibr:native-scan | Scan iOS/watchOS/macOS apps | | /ibr:ui | Open the web dashboard at localhost:4200 |

Example:

"Build a daily focus timer for iOS" -> /ibr:build classifies it as a Utility archetype -> routes to iOS design references -> implements with apple-platform patterns -> scans the result, reports any WCAG / touch target / hydration issues.

The plugin hooks run automatic pre/post scans around UI file edits and surface console errors immediately when interactions trigger them.

Codex

Codex consumes .codex-plugin/plugin.json, compact skills under .codex-plugin/skills/, and .codex-plugin/mcp.json. The Codex-compatible agent approach is skills plus MCP tools; Claude-style files under commands/, hooks/, and agents/ are retained for Claude Code and should not be treated as Codex-loaded routing.

Install this checkout as a local Codex plugin:

npm run build
npm run plugin:install-codex

This syncs a slim Codex bundle to ~/plugins/ibr and registers it in ~/.agents/plugins/marketplace.json. Restart Codex after installing. See Codex Plugin Setup for validation steps and failure modes.

Starter prompts:

$ibr Plan this UI with IBR.
$ibr Scan this UI with IBR.
$ibr Validate this design intent.

Use MCP sessions when the agent needs to navigate the current UI state:

{
  "tool": "flow_search",
  "sessionId": "<session id>",
  "query": "pricing plan",
  "userIntent": "Find the plan a buyer would choose",
  "aiValidation": true
}

What IBR Does For You (Plugin Hooks)

When installed as a Claude Code plugin, IBR provides:

• Design validation reminders — after UI file edits, nudges to run npx ibr scan to verify against user intent
• Scan + screenshot guidance — suggests also running IBR scan for precise property data alongside visual checks
• Session end check — reminds if UI work was done but not validated
• Bash safety — blocks destructive commands (rm -rf /, git push --force, etc.)
• Sensitive path protection — prevents writes to ~/.ssh, ~/.aws, /etc/

Hooks are command-based and live in hooks/hooks.json. They call the repo-local shell scripts under hooks/, which are designed to fail softly when no UI work, no config, or no reachable dev server is present.

What IBR Scan Returns

Element Data (per interactive element)

selector:        Unique CSS path
tagName:         button, a, input, etc.
text:            Visible text content
bounds:          { x, y, width, height } — exact position and size
computedStyles:  backgroundColor, color, fontSize, fontFamily, fontWeight,
                 padding, margin, borderRadius, display, gap, flexDirection,
                 alignItems, justifyContent, gridTemplateColumns, etc.
interactive:     { hasOnClick, hasHref, hasReactHandler, isDisabled, cursor }
a11y:            { role, ariaLabel, ariaDescribedBy, ariaHidden }

Page-Level Data

pageIntent:      auth | form | listing | detail | dashboard | error | landing
state.auth:      { authenticated, username, confidence }
state.loading:   { loading, type: spinner|skeleton|progress }
state.errors:    { hasErrors, errors[], severity }
console:         { errors[], warnings[] }
verdict:         PASS | ISSUES | FAIL

Scan Data vs Screenshots

Each approach catches things the other misses. The best validation uses both.

Where IBR scan wins

| Question | Screenshot | IBR Scan | |----------|-----------|----------| | Is this exactly #3b82f6? | Guess from pixels | backgroundColor: "rgb(59, 130, 246)" | | Is the font 16px Inter? | "Looks about right" | fontSize: "16px", fontFamily: "Inter" | | Is the button wired up? | Can't tell | hasOnClick: true, hasReactHandler: true | | Are ARIA labels present? | Can't see | ariaLabel: "Submit form", role: "button" | | Any console errors? | Can't see | console.errors: [] |

Where screenshots win

| Question | IBR Scan | Screenshot | |----------|---------|-----------| | Does the page look right? | Can't judge | Visual coherence at a glance | | Any rendering glitches? | Computed styles can be correct but render wrong | Sees clipping, overlap, z-index issues | | Canvas/SVG/WebGL content? | Not in the DOM | Sees everything rendered | | Font rendering quality? | Reports font-family, not rendering | Sees anti-aliasing, kerning | | Unexpected visual artifacts? | Only checks what you ask | Catches things you didn't think to check |

Best practice: combine both

npx ibr scan http://localhost:3000 --json    # precise property verification
# + screenshot for visual confirmation when needed

For AI agents, scan data is best for precise verification (exact values, handler detection, a11y). Screenshots are best for holistic visual checks. Together they give more confidence than either alone.

CLI Reference

Core Commands

| Command | Description | |---------|-------------| | npx ibr scan <url> --json | Validate UI — returns structured data | | npx ibr start <url> | Capture baseline for regression | | npx ibr check | Compare current state against baseline | | npx ibr serve | Open web UI at localhost:4200 | | npx ibr list | List all sessions | | npx ibr update | Accept current as new baseline | | npx ibr clean --older-than 7d | Clean old sessions |

Interactive Sessions

For pages that need clicks, typing, or navigation before validating:

# Start a persistent browser session
npx ibr session:start http://localhost:3000 --name "search-test"

# Interact with it
npx ibr session:type <id> "input[name=search]" "quantum computing"
npx ibr session:click <id> "button[type=submit]"
npx ibr session:wait <id> ".search-results"
npx ibr session:screenshot <id>

| Command | Description | |---------|-------------| | session:start <url> | Start browser session | | session:click <id> <selector> | Click an element | | session:type <id> <selector> <text> | Type into an element | | session:press <id> <key> | Press keyboard key | | session:scroll <id> <direction> | Scroll page | | session:screenshot <id> | Capture screenshot | | session:wait <id> <selector> | Wait for element | | session:navigate <id> <url> | Navigate to URL | | session:html <id> | Get page HTML | | session:text <id> <selector> | Extract text content | | session:close <id\|all> | Close session |

Memory (Design Specs)

Store design preferences that IBR enforces during every scan:

# Remember that buttons should be blue
npx ibr memory add "Primary buttons are blue" --category color --property background-color --value "#3b82f6"

# Store font preference
npx ibr memory add "Body font is Inter 16px" --property font-family --value "Inter"

# List stored specs
npx ibr memory list

# IBR checks these during every scan automatically

Authenticated Pages

npx ibr login http://localhost:3000/login   # opens browser, log in manually
npx ibr scan http://localhost:3000/dashboard --json  # validates with your auth
npx ibr logout                                 # clear saved auth

Verdicts

After ibr check, you get one of four results:

| Verdict | Meaning | Action | |---------|---------|--------| | MATCH | Nothing changed | You're done | | EXPECTED_CHANGE | Changes look intentional | Review and continue | | UNEXPECTED_CHANGE | Something changed that shouldn't have | Investigate | | LAYOUT_BROKEN | Major structural issues | Fix before continuing |

Programmatic API

import { compare } from '@tyroneross/interface-built-right';

const result = await compare({
  url: 'http://localhost:3000/dashboard',
  baselinePath: './baselines/dashboard.png',
});

console.log(result.verdict);     // "MATCH" | "EXPECTED_CHANGE" | ...
console.log(result.diffPercent); // 2.5
console.log(result.summary);    // "Header background changed. Layout intact."

import { EngineDriver, CompatPage } from '@tyroneross/interface-built-right/engine';

// Direct CDP engine access
const driver = new EngineDriver();
await driver.launch({ headless: true, viewport: { width: 1920, height: 1080 } });

// Navigate with stability detection
await driver.navigate('http://localhost:3000', { waitFor: 'stable' });

// Discover interactive elements (LLM-optimized)
const elements = await driver.discover({
  filter: 'interactive',
  serialize: true,        // compact format for context windows
  maxTokens: 4000,
});

// Find elements by intent (not CSS selectors)
const button = await driver.find('Submit', { role: 'button' });

// Assess page understanding quality
const understanding = await driver.assessUnderstanding();
if (understanding.needsScreenshot) {
  const screenshot = await driver.screenshot({ fullPage: true });
}

// Extract structured data
const data = await driver.extract({
  title: { role: 'heading', extract: 'text' },
  isLoggedIn: { role: 'button', label: 'logout', extract: 'exists' },
});

await driver.close();

import { InterfaceBuiltRight } from '@tyroneross/interface-built-right';

const ibr = new InterfaceBuiltRight({
  baseUrl: 'http://localhost:3000',
  outputDir: './.ibr',
  threshold: 1.0,
});

const { sessionId } = await ibr.startSession('/dashboard', {
  name: 'dashboard-update',
});

// After changes
const report = await ibr.check(sessionId);
console.log(report.analysis.verdict);

await ibr.close();

Configuration

Optional — create .ibrrc.json in your project root:

{
  "baseUrl": "http://localhost:3000",
  "outputDir": "./.ibr",
  "viewport": "desktop",
  "threshold": 1.0,
  "fullPage": true
}

Available viewports: desktop, laptop, tablet, mobile, iphone-14, iphone-14-pro-max

Mobile and device emulation (1.1.0+)

IBR emulates mobile and tablet devices end-to-end via CDP (no Playwright dependency). Three things happen on driver.launch(), in order, BEFORE the first navigate:

1. Emulation.setUserAgentOverride — so the initial HTML response sees a mobile UA
2. Emulation.setDeviceMetricsOverride — width, height, DPR, mobile: true
3. Emulation.setTouchEmulationEnabled — so navigator.maxTouchPoints > 0 and CSS @media (pointer: coarse) matches

--viewport presets

npx ibr scan https://example.com --viewport mobile --json
# viewport in JSON: { name: "mobile", width: 390, height: 844, deviceScaleFactor: 3, mobile: true }

| Preset | Size | DPR | Mobile | |--------|------|-----|--------| | desktop | 1920 x 1080 | 1 | false | | desktop-lg | 2560 x 1440 | 1 | false | | desktop-sm | 1440 x 900 | 1 | false | | laptop | 1366 x 768 | 1 | false | | tablet | 820 x 1180 (iPad Air baseline) | 2 | true | | tablet-landscape | 1180 x 820 | 2 | true | | mobile | 390 x 844 (iPhone 14 baseline) | 3 | true | | mobile-lg | 430 x 932 | 3 | true |

Pre-1.1.0 --viewport mobile parsed cleanly but rendered desktop (375 x 667 with no mobile flag and no UA override). If you previously worked around this by passing custom widths, you can switch to the preset.

--device <name> — canonical profiles

--device carries a full CDP profile (viewport + DPR + mobile + UA + touch). It wins over --viewport when both are given.

npx ibr scan http://localhost:3000 --device iphone-14 --json
npx ibr session:start http://localhost:3000 --device pixel-7

| Device | Size | DPR | UA | |--------|------|-----|----| | iphone-14 | 390 x 844 | 3 | iOS 17 Safari | | iphone-14-pro-max | 430 x 932 | 3 | iOS 17 Safari | | pixel-7 | 412 x 915 | 2.625 | Android 14 Chrome | | ipad-air | 820 x 1180 | 2 | iPad iOS 17 Safari | | ipad-pro-11 | 834 x 1194 | 2 | iPad iOS 17 Safari | | desktop-1440 | 1440 x 900 | 1 | (default Chrome) |

Unknown --device names fail loudly: Error: Unknown --device "iphone-99". Known devices: iphone-14, .... Add more profiles in src/devices.ts.

Library use

import { EngineDriver, resolveDevice, deviceToViewport } from '@tyroneross/interface-built-right'

const profile = resolveDevice('iphone-14')
const driver = new EngineDriver()
await driver.launch({ headless: true, viewport: deviceToViewport(profile) })
await driver.navigate('https://example.com')

Troubleshooting

| Problem | Fix | |---------|-----| | Command not found: ibr | Use npx ibr --help | | Chrome not found | Install Google Chrome, or pass chromePath option | | Auth state expired | npx ibr login <url> | | Session not found | npx ibr list to see available sessions | | --viewport mobile renders desktop (pre-1.1.0) | Upgrade to >= 1.1.0; mobile presets now set the CDP mobile flag + UA + touch | | Unknown --device "..." | Run npx ibr scan --help to see the canonical device list, or add a profile to src/devices.ts |

Requirements

• Node.js 22+ (uses built-in WebSocket for CDP)
• Google Chrome installed (uses system Chrome, no downloads needed)

License

MIT