opendevbrowser 0.0.16 → 0.0.18

package/skills/opendevbrowser-design-agent/artifacts/frontend-evaluation-rubric.md

@@ -0,0 +1,61 @@
+# Frontend Evaluation Rubric
+
+Use this rubric before sign-off. A design should not pass on aesthetics alone.
+
+## Must-Pass Gates
+
+- The UI matches the current design contract.
+- The screen has a clear information hierarchy.
+- Focus, keyboard access, and readable contrast are present where relevant.
+- Responsive behavior is intentional, not accidental.
+- Copy is real enough to evaluate the actual layout.
+- Browser validation was run on the relevant surface.
+
+## Scored Categories
+
+Score each category from `1` to `5`.
+
+### Clarity
+
+- Is the primary action obvious?
+- Is the page purpose understandable within a few seconds?
+
+### Visual Direction
+
+- Does the design feel intentional instead of generic?
+- Are color, type, and spacing working together as one system?
+
+### Component Discipline
+
+- Are repeated patterns actually consistent?
+- Do components share the same edge radius, spacing rhythm, and interaction language?
+
+### State Coverage
+
+- Are default, hover, focus, empty, loading, success, and error states handled when needed?
+
+### Responsiveness
+
+- Does the layout adapt gracefully at the required viewports?
+- Are touch targets and overflow behavior sane?
+
+### Accessibility
+
+- Are semantics, focus order, and contrast acceptable?
+- Does motion preserve meaning when reduced motion is required?
+
+### Performance And Restraint
+
+- Is motion purposeful instead of noisy?
+- Are heavy effects justified?
+- Does the screen avoid unnecessary complexity?
+
+## Failure Triggers
+
+Fail the design review if any of these are true:
+
+- The design depends on placeholder content to look good.
+- Mobile or keyboard behavior is untested.
+- The page is visually inconsistent across repeated components.
+- The design contract and shipped output disagree materially.
+- Real-browser validation was skipped without an explicit blocker.

package/skills/opendevbrowser-design-agent/artifacts/implementation-anti-patterns.md

@@ -0,0 +1,163 @@
+# Implementation Anti-Patterns
+
+Use this list to stop weak frontend patterns before they spread.
+
+## 1. Boolean Sprawl
+
+Bad:
+
+- one screen tracks `isModalOpen`, `isDrawerOpen`, `isPopoverOpen`, `isConfirmingDelete`, and `selectedId` across many siblings
+
+Prefer:
+
+- one overlay owner with an item-backed state object
+
+## 2. Mixed State Ownership
+
+Bad:
+
+- the same filter state lives in component state, URL params, and a shared store
+
+Prefer:
+
+- one canonical owner with derived views elsewhere
+
+## 3. Placeholder-Led Layout
+
+Bad:
+
+- the UI only looks balanced with fake short copy or idealized data
+
+Prefer:
+
+- real or realistic content, plus explicit overflow and truncation rules
+
+## 4. Pattern Drift
+
+Bad:
+
+- repeated cards, panels, or controls each invent their own spacing, radius, or interaction order
+
+Prefer:
+
+- one pattern family per screen, documented in the contract and checked against the component index
+
+## 5. Motion Without A Driver
+
+Bad:
+
+- many components each own their own scroll math, timing, or parallax rules
+
+Prefer:
+
+- one normalized progress model with reduced-motion fallback
+
+## 6. Heavy Work Per Item
+
+Bad:
+
+- each row or card performs expensive layout, measurement, or data reshaping during render
+
+Prefer:
+
+- precomputed data, memoized derivations only when justified by existing project patterns, and lazy detail work
+
+## 7. Overlay Ownership Split
+
+Bad:
+
+- a toolbar opens a modal while a row also mutates that modal's data source independently
+
+Prefer:
+
+- route or feature ownership plus explicit focus-return behavior
+
+## 8. Contract-Free Canvas Mutation
+
+Bad:
+
+- patching `/canvas` before the design contract and generation plan are coherent
+
+Prefer:
+
+- contract first, plan second, mutation third, preview and feedback after
+
+## 9. Unverified Responsive Claims
+
+Bad:
+
+- declaring mobile support without checking layout, scroll, focus, and overflow at mobile widths
+
+Prefer:
+
+- real-surface validation at the required breakpoints
+
+## 10. Stale Runtime Trust
+
+Bad:
+
+- assuming `npm run extension:build` means a live unpacked extension tab is already running the new code
+
+Prefer:
+
+- reload the unpacked extension, reconnect, and then validate the real surface again
+
+## 11. Unbounded Async Restarts
+
+Bad:
+
+- each keystroke, scope switch, or filter tap starts new async work with no debounce or stale-request handling
+
+Prefer:
+
+- one restart policy with debounce, cancellation, and a clear empty-query behavior
+
+## 12. Spinner Stacking
+
+Bad:
+
+- the same async region shows multiple loaders, layout-shifting placeholders, and no stable empty/error plan
+
+Prefer:
+
+- one loading story per region plus layout-preserving placeholders when the final structure matters
+
+## 13. Raw Token Sprawl
+
+Bad:
+
+- repeated components hardcode colors, spacing, or radius values that drift away from the design system
+
+Prefer:
+
+- one semantic token source with leaf components consuming tokens instead of inventing them
+
+## 14. Live-Service Previews
+
+Bad:
+
+- isolated previews depend on live APIs, auth, or global singletons and only render when the full app happens to be running
+
+Prefer:
+
+- deterministic fixtures, explicit dependency installation, and isolated preview state that mirrors production ownership
+
+## 15. Stringly Routed Actions
+
+Bad:
+
+- buttons, tabs, rows, and shortcuts each assemble route strings or params independently
+
+Prefer:
+
+- one typed route translator with explicit invalid-route fallback and shared deep-link handling
+
+## 16. Unstable List Identity
+
+Bad:
+
+- selection, expansion, or animation state is keyed by array index on a sortable or filterable collection
+
+Prefer:
+
+- stable item identity plus an explicit scan-heavy performance plan for large result sets

package/skills/opendevbrowser-design-agent/artifacts/isolated-preview-validation.md

@@ -0,0 +1,68 @@
+# Isolated Preview Validation
+
+Use this playbook before full-page rollout. The goal is to prove the pattern in a stable fixture before broader integration and then carry the same state matrix onto real browser surfaces.
+
+## When To Use It
+
+- new component families
+- dense shells or editors
+- async-heavy screens
+- motion or scroll-driven interactions
+- any UI that already failed once in live validation
+
+## Preview Discipline
+
+Build a deterministic isolated surface first:
+
+- story, fixture route, local sandbox, or `/canvas` preview target
+- realistic copy and realistic data volume
+- fixed viewport sizes for mobile, tablet, and desktop
+- installed theme, router, and shell dependencies when the real surface requires them
+- explicit reduced-motion and empty/error variants when relevant
+
+Do not continue layering polish on a preview that already crashes or visually collapses.
+
+## Required Fixture States
+
+Cover the relevant set explicitly:
+
+- default
+- hover and focus
+- loading
+- empty
+- success
+- error
+- overflow or long-content
+- reduced-motion
+- mobile compact layout
+
+If the component never renders one of these states in isolation, it is likely to regress when integrated.
+
+## Dependency Rules
+
+- inject mock or deterministic data sources into the preview
+- remove network dependence from the isolated fixture
+- install every required environment, provider, or theme dependency directly in the preview
+- keep async, search, and filter fixtures deterministic, including empty-query and non-happy paths
+- keep one owner for feature flags, search params, or overlay state inside the preview
+- if the UI depends on app-shell context, stub only the minimum shell contract needed for the task
+- do not make required production dependencies optional just to silence preview crashes
+
+## Validation Loop
+
+1. Build the isolated surface.
+2. Fix preview crashes, missing dependency wiring, or state drift before broader integration.
+3. Validate the same states in a real browser session.
+4. Only then move to the integrated page, shell, or `/canvas` workflow.
+
+## OpenDevBrowser Commands
+
+```bash
+npx opendevbrowser launch --no-extension --start-url http://127.0.0.1:3000/preview/component
+npx opendevbrowser snapshot --session-id <session-id>
+npx opendevbrowser screenshot --session-id <session-id>
+npx opendevbrowser debug-trace-snapshot --session-id <session-id>
+npx opendevbrowser canvas --command canvas.preview.render --params '{"canvasSessionId":"<canvas-session-id>","leaseId":"<lease-id>","targetId":"<target-id>","projection":"canvas_html"}'
+```
+
+Use the same fixture states as the contract when comparing preview and integrated behavior.

package/skills/opendevbrowser-design-agent/artifacts/loading-and-feedback-surfaces.md

@@ -0,0 +1,56 @@
+# Loading And Feedback Surfaces
+
+Use this when the screen needs loading, empty, success, error, toast, or banner states that must feel intentional instead of bolted on.
+
+## 1. Preserve Layout While Loading
+
+Prefer layout-preserving placeholders over generic spinners:
+
+- keep the real content structure and swap in placeholder data or skeleton rows
+- use a fixed placeholder count for repeated content, usually `3` to `6`
+- keep placeholder frames stable so the loaded state does not jump
+
+Use a single section-level loader only when the layout cannot be meaningfully previewed during load.
+
+## 2. Give Each Region One Loading Story
+
+- one loading affordance per region
+- one empty-state message per result set
+- one recovery action near the failing region
+
+Do not stack row spinners, section spinners, and page spinners for the same fetch.
+
+## 3. Empty, Error, And Success Are Part Of The Design
+
+- empty states should explain why nothing is shown and offer a next action
+- error states should keep retry or fallback actions close to the failed area
+- success states should confirm progress without hijacking the next task
+
+If the screen cannot explain its empty or error behavior in the contract, it is not ready.
+
+## 4. Use Overlays For Transient Feedback
+
+Use overlays, toasts, or banners for short-lived feedback that should not distort the layout:
+
+- keep a single owner for transient feedback state
+- align overlays to a clear edge and keep the motion short
+- auto-dismiss short confirmations when that will not hide critical information
+- queue or replace overlapping feedback instead of stacking many transient surfaces
+
+Use modal or blocking UI only when the user must stop and decide.
+
+## 5. Review Prompts
+
+1. Does the loading state preserve the final layout?
+2. How many placeholders render, and why that count?
+3. What action can the user take from the empty or error state?
+4. Which feedback belongs in layout, and which belongs in an overlay?
+5. Who owns transient banners or toasts?
+
+## Failure Signals
+
+- placeholder layouts collapse or shift when content arrives
+- the design uses more than one loading indicator for the same async region
+- empty and error states are generic copy without a next action
+- toast or banner feedback reflows the main layout unnecessarily
+- multiple features can stack transient overlays without coordination

package/skills/opendevbrowser-design-agent/artifacts/opendevbrowser-ui-example-map.md

@@ -0,0 +1,44 @@
+# OpenDevBrowser UI Example Map
+
+Use nearby repo examples before inventing new structure. These are not design mandates, but they are the fastest way to align with current patterns and shipped constraints.
+
+## Extension UI
+
+- `extension/popup.html`
+  - compact control surfaces, diagnostics panels, brand treatment, settings rows
+- `extension/src/popup.tsx`
+  - popup state orchestration, health-state rendering, annotation history affordances
+- `extension/canvas.html`
+  - full-screen extension-hosted editor shell
+- `extension/src/canvas-page.ts`
+  - design-tab shell wiring, stage controls, inspector and layers integration
+- `extension/src/canvas/canvas-runtime.ts`
+  - runtime-side canvas state ownership and preview synchronization
+- `extension/src/annotate-content.ts`
+  - in-page overlay state, annotation affordances, selection lifecycle
+
+## Canvas Core
+
+- `src/browser/canvas-manager.ts`
+  - public `/canvas` contract surface and session-summary ownership
+- `src/canvas/export.ts`
+  - canonical preview and export renderer boundary
+- `src/canvas/document-store.ts`
+  - normalized design document truth and mutation flow
+
+## Tests As UI Behavior Proof
+
+- `tests/extension-canvas-editor.test.ts`
+  - token editor, layers, inspector, and design-tab interaction expectations
+- `tests/extension-canvas-runtime.test.ts`
+  - runtime shell and preview bridge expectations
+- `tests/extension-popup-brand.test.ts`
+  - popup brand and icon assertions
+- `tests/extension-background.test.ts`
+  - popup and annotation routing expectations that affect UI trust
+
+## How To Use This Map
+
+1. Find the closest shipped surface.
+2. Reuse its ownership model and shell assumptions unless the new brief requires a deliberate break.
+3. Record any intentional deviation in the design contract and ship audit.

package/skills/opendevbrowser-design-agent/artifacts/performance-audit-playbook.md

@@ -0,0 +1,70 @@
+# Performance Audit Playbook
+
+Use this workflow when the UI feels heavy, re-renders too often, scrolls poorly, or becomes unstable under realistic data volume.
+
+## Intake
+
+Capture the problem before optimizing:
+
+- interaction that feels slow
+- viewport and data size
+- whether the issue is input, scroll, resize, animation, or async refresh
+- suspected heavy subtree or component family
+
+## Baseline First
+
+Measure before changing structure:
+
+- React DevTools Profiler for render churn
+- browser Performance panel when the problem looks layout or paint related
+- `debug-trace-snapshot` for console and network regressions tied to the interaction
+
+Treat components taking longer than roughly one frame budget as candidates for deeper audit.
+
+## Common Fix Patterns
+
+- isolate ticking or rapidly changing state from heavy subtrees
+- avoid top-level branch swapping when a stable base tree can express the same states
+- keep props narrow and stable before reaching for memoization
+- move expensive derivations out of render paths
+- virtualize or progressively reveal long collections
+- delay heavy secondary panels until the user asks for them
+- drive scroll motion from one normalized progress model
+
+## Scan-Heavy Surface Discipline
+
+When the screen is mostly about rows, cards, or staged panes:
+
+- keep stable item identity through sorting, filtering, refresh, and optimistic updates
+- avoid index-based expansion or selection state for reorderable collections
+- pick one scan unit and optimize around that unit before styling the rest of the shell
+- prefer lazy containers or progressive reveal before hand-tuned per-item memoization
+- keep inspectors, previews, and secondary editors lazy when they are not needed for the first scan
+- measure with realistic list density and content length instead of trimmed placeholder data
+
+## Restraint Rules
+
+- do not add memoization by default when the repo pattern does not support it
+- do not optimize around fake placeholder data
+- fix ownership churn before micro-optimizing components
+- validate that the slow interaction is actually improved after each change
+
+## Audit Output
+
+Use `assets/templates/design-audit-report.v1.md` and capture:
+
+- issue
+- evidence
+- suspected owner
+- fix
+- validation result
+
+## Validation Commands
+
+```bash
+npx opendevbrowser launch --no-extension --start-url http://127.0.0.1:3000
+npx opendevbrowser debug-trace-snapshot --session-id <session-id>
+npx opendevbrowser screenshot --session-id <session-id>
+```
+
+Pair browser evidence with React DevTools Profiler or equivalent framework tooling when the regression is render-bound.

package/skills/opendevbrowser-design-agent/artifacts/research-harvest-workflow.md

@@ -0,0 +1,81 @@
+# Research Harvest Workflow
+
+Use this workflow before design direction is locked, when the brief references competitors, or when a redesign needs stronger visual and interaction references than the local repo already provides.
+
+## Goal
+
+Turn live product references into a deterministic pattern board instead of vague inspiration.
+
+## Inputs
+
+- A focused brief or design question
+- `3` to `5` reference products or pages
+- The target surface in this repo
+- Constraints that must not be violated:
+  - existing design system rules
+  - supported libraries and runtime budgets
+  - accessibility and responsive requirements
+
+## Evidence Loop
+
+1. Pick reference pages that match the product shape:
+   - dashboard
+   - marketing landing page
+   - onboarding flow
+   - editor
+   - auth/settings surface
+2. Capture the surface with OpenDevBrowser:
+   - `launch`
+   - `goto`
+   - `snapshot`
+   - `screenshot`
+   - `debug-trace-snapshot` when motion, loading, or layout churn matters
+3. Record each page in `assets/templates/reference-pattern-board.v1.json`.
+4. For each reference, extract:
+   - layout recipe
+   - content hierarchy
+   - component families
+   - motion posture
+   - loading and empty-state strategy
+   - token and theming clues
+   - patterns to borrow
+   - patterns to reject
+5. Synthesize only the patterns that fit the repo's current surface, libraries, and runtime budgets.
+6. Translate the synthesis into the design contract before touching `/canvas` or code.
+
+## What To Borrow From External Patterns
+
+These cues should stay explicit in the pattern board:
+
+- From Dimillian:
+  - start from the closest shipped screen family
+  - decide shell, route, overlay, async, and token ownership before implementation
+  - validate patterns in isolation before full integration
+- From Vercel v0:
+  - specify structure, state, and constraints directly
+  - describe concrete interaction states instead of aesthetic buzzwords
+- From Lovable:
+  - use real content and realistic journeys
+  - iterate one improvement axis at a time
+- From public frontend-designer agents:
+  - inspect current stack and assets first
+  - combine aesthetics, accessibility, and implementation practicality in one review loop
+
+## OpenDevBrowser Command Pattern
+
+```bash
+npx opendevbrowser launch --no-extension --start-url https://example.com
+npx opendevbrowser goto --session-id <session-id> --url <reference-url>
+npx opendevbrowser snapshot --session-id <session-id>
+npx opendevbrowser screenshot --session-id <session-id>
+npx opendevbrowser debug-trace-snapshot --session-id <session-id>
+```
+
+Repeat this for each selected reference. Keep the resulting notes in one pattern board so the design contract has a visible source of truth.
+
+## Exit Criteria
+
+- The pattern board lists at least `3` live references.
+- Borrowed and rejected patterns are both explicit.
+- The chosen design direction is justified by evidence, not taste alone.
+- The resulting design contract names component families, state ownership, and validation targets before implementation starts.

package/skills/opendevbrowser-design-agent/artifacts/scroll-reveal-surface-planning.md

@@ -0,0 +1,64 @@
+# Scroll Reveal Surface Planning
+
+Use this when narrative sequencing, pinned sections, or viewport-driven motion is part of the design instead of decorative afterthought.
+
+## 1. Declare The Driver First
+
+Choose one progress owner before writing animation code:
+
+- page-level normalized progress
+- section-local reveal progress
+- pinned stage index with explicit transitions
+
+Do not mix multiple observers, ad-hoc scroll listeners, and independent card timers for the same narrative.
+
+## 2. Separate Layout From Motion
+
+- layout owns reading order, overflow, and breakpoint behavior
+- motion owns interpolation and reveal timing
+- content owns message sequencing and copy density
+
+If motion changes layout ownership, the design contract is incomplete.
+
+## 3. Reduced Motion Is Not Optional
+
+Define the fallback up front:
+
+- no pinning
+- instant section reveal
+- opacity-only transitions
+- static ordering with no transform-based staging
+
+The reduced-motion path should preserve comprehension, not merely disable animation.
+
+## 4. Keep Stages Explicit
+
+For every scroll-driven surface, document:
+
+- stage count
+- trigger range
+- sticky or pinned regions
+- exit condition
+- fallback behavior on mobile or short viewports
+
+If the stage model cannot be written down, it is too implicit to ship safely.
+
+## 5. Browser Validation
+
+Validate:
+
+- mobile, tablet, and desktop viewport behavior
+- keyboard and reading order while the effect is active
+- console stability during scroll
+- reduced-motion output
+- no competing transforms across sibling sections
+
+Use `snapshot`, `screenshot`, and `debug-trace-snapshot` on the real surface after the isolated preview passes.
+
+## Failure Signals
+
+- each section owns its own scroll math
+- pinned content traps focus or blocks reading order
+- reduced-motion removes structure instead of motion only
+- mobile collapses because the reveal model depends on tall desktop viewports
+- the design cannot explain which value actually drives the reveal

package/skills/opendevbrowser-design-agent/artifacts/state-ownership-matrix.md

@@ -0,0 +1,36 @@
+# State Ownership Matrix
+
+High-quality frontend work depends on deciding who owns state before component APIs or prompts expand. One state should have one clear owner.
+
+| State kind | Primary owner | Typical examples | Avoid |
+| --- | --- | --- | --- |
+| Micro interaction state | Local component state | hover affordance, disclosure open state, input focus styling | lifting purely presentational state into global stores |
+| Draft form state | Closest form controller or route-level model | unsaved edits, validation summary, staged submit payload | mirroring each field into unrelated sibling components |
+| URL-addressable view state | URL or search params | filters, sort order, tabs, pagination, selected record id | hiding shareable or refresh-stable state in local component memory |
+| Navigation and deep-link state | route owner or shell-level router | canonical route params, tab destination, invalid-param fallback, external entry translation | letting buttons and tabs build route strings independently |
+| Remote async state | data layer or query cache | list fetch, optimistic mutations, background refresh | duplicating server state into local component snapshots without invalidation rules |
+| Workspace or session state | app-level store or context | authenticated workspace, current project, cross-route inspector selection | pushing global state into prop chains when many routes need it |
+| Overlay state | single route or feature owner | active modal item, drawer record id, command palette visibility | multiple booleans across siblings controlling one overlay |
+| Canvas governance state | design contract and `/canvas` generation plan | plan acceptance, mutation requirements, validation targets | letting ad-hoc UI state bypass the contract |
+| Scroll or motion progress | dedicated derived controller | section reveal progress, pinned story stage, viewport interpolation | separate observers per card with competing transforms |
+
+## Ownership Rules
+
+- If state must survive refresh, it probably belongs in the URL, repo, or data layer.
+- If state must coordinate more than one branch of the tree, write down the owner explicitly before coding.
+- If state exists only to mirror props, remove it unless the component is intentionally editing a local draft.
+- For overlays, prefer item identity or a single state object over boolean pairs like `isOpen` plus `selectedId`.
+- For async flows, define loading, success, and failure ownership together so the UI does not split them across unrelated hooks.
+
+## Design-Agent Prompt Rules
+
+When using this skill, declare:
+
+- the owner of selection state
+- the owner of navigation and deep-link translation
+- the owner of async state
+- the owner of overlay state
+- whether view state belongs in the URL
+- whether the `/canvas` plan or repo code is the mutation authority
+
+If any of those are unclear, the contract is incomplete.

package/skills/opendevbrowser-design-agent/artifacts/theming-and-token-ownership.md

@@ -0,0 +1,43 @@
+# Theming And Token Ownership
+
+Use this when the design task touches visual direction, design systems, or any reusable UI surface that should remain consistent over time.
+
+## 1. Keep One Semantic Token Source
+
+Choose one owner for shared visual tokens:
+
+- app root or workspace shell for global theme values
+- feature shell only when the product intentionally supports a local variant
+
+The token source should define semantic values such as background, surface, text, accent, spacing, radius, shadow, and motion tiers.
+
+## 2. Keep Components Semantic
+
+- consume semantic tokens instead of raw hex values or one-off spacing constants
+- let typography, spacing, and motion inherit from the same token system when possible
+- reserve raw values for rare one-off illustration or algorithmic art cases, not routine UI structure
+
+This keeps visual changes centralized and makes previews and audits easier to trust.
+
+## 3. Theme Controls Need An Owner
+
+- user theme preferences belong in settings or an app-level controller
+- temporary campaign or feature skins must still map back to semantic tokens
+- previews and isolated fixtures should install the same token source the real UI expects
+
+Do not let a leaf component quietly become the token authority.
+
+## 4. Review Prompts
+
+1. Where is the canonical token source?
+2. Which semantic tokens does this surface rely on?
+3. Are any raw values hiding inside repeated components?
+4. Does the preview or fixture install the same theme owner as the integrated screen?
+5. If the product supports theming controls, who owns them?
+
+## Failure Signals
+
+- repeated components hardcode their own colors or spacing
+- the visual direction depends on raw values scattered across leaves
+- preview fixtures do not install the theme or token owner required by production
+- feature-local overrides drift away from the semantic token vocabulary