opendevbrowser 0.0.31 → 0.0.33

package/skills/opendevbrowser-motion-design/artifacts/platform-framework-guide.md

@@ -0,0 +1,166 @@
+# Platform And Framework Guide
+
+Motion frameworks are implementation primitives. They do not authorize new dependencies. Prefer existing project libraries and platform APIs. Any new runtime dependency requires approval, maintenance review, and a `libraryPolicy` entry in the motion contract.
+
+## Web Platform
+
+### CSS Transitions
+- Approved use: simple state changes on opacity, transform, color, and filter when supported by the design system.
+- Avoid: sequencing, complex interruption, or layout-property animation.
+- Primitive mapping: duration, easing, transition-property.
+- Reduced motion: shorten or remove transition under `prefers-reduced-motion`.
+- Performance hazards: animating width, height, top, left, or box-shadow in hot paths.
+- Library policy: no dependency.
+
+### CSS Keyframe Animations
+- Approved use: repeated decorative effects, skeletons, icon states, and controlled loops.
+- Avoid: user-blocking sequences and infinite attention traps.
+- Primitive mapping: `@keyframes`, animation duration, direction, fill mode.
+- Reduced motion: pause, remove, or replace with static state.
+- Performance hazards: infinite animations on many nodes.
+- Library policy: no dependency.
+
+### Web Animations API
+- Approved use: cancellable timeline control, dynamic keyframes, and interruption.
+- Avoid: trivial CSS-only transitions.
+- Primitive mapping: `Element.animate()`, `Animation`, `KeyframeEffect`, playback controls, `document.getAnimations()`.
+- Reduced motion: cancel or retarget to final states.
+- Performance hazards: unmanaged animation handles and missing cleanup.
+- Library policy: no dependency.
+
+### View Transition API
+- Approved use: route, view, or shared element continuity in supported browsers.
+- Avoid: pages with unstable identity or unsupported fallback needs that have not been designed.
+- Primitive mapping: `document.startViewTransition`, view-transition names, route hooks.
+- Reduced motion: focus-first instant navigation or fade-through.
+- Performance hazards: stale snapshots, large raster layers, and wrong shared names.
+- Library policy: no dependency.
+
+### CSS Scroll-driven Animations
+- Approved use: scroll progress and view progress where progressive enhancement is acceptable.
+- Avoid: core task flows that require all browsers to animate.
+- Primitive mapping: scroll timelines, view timelines, CSS animation progress.
+- Reduced motion: static content, no pinning, no parallax.
+- Performance hazards: unreadable content during scroll, browser support gaps.
+- Library policy: no dependency.
+
+## JavaScript And React Libraries
+
+### Motion For React
+- Approved use: React UI transitions, layout transitions, gesture, and scroll hooks when already in the project or explicitly approved.
+- Avoid: adding it only for one opacity fade.
+- Primitive mapping: `motion/react`, motion components, layout, variants, AnimatePresence.
+- Reduced motion: use reduced-motion hooks and contract fallback.
+- Performance hazards: layout measurement on large lists and unbounded re-renders.
+- Library policy: new dependency requires approval.
+
+### GSAP 3.x
+- Approved use: complex timelines, SVG, scroll scenes, and production-grade choreography when approved.
+- Avoid: basic UI state transitions and unowned scroll stages.
+- Primitive mapping: timelines, tweens, ScrollTrigger when allowed.
+- Reduced motion: disable timelines or jump to final state.
+- Performance hazards: competing scroll observers and cleanup leaks.
+- Library policy: new dependency requires approval.
+
+### Anime.js 4.x
+- Approved use: lightweight timeline and SVG effects when approved.
+- Avoid: framework state transitions that platform or existing libraries cover.
+- Primitive mapping: timelines, keyframes, targets.
+- Reduced motion: pause or complete instantly.
+- Performance hazards: broad selectors and unmanaged loops.
+- Library policy: new dependency requires approval.
+
+### react-spring
+- Approved use: spring-driven UI states and direct manipulation when already installed or approved.
+- Avoid: deterministic route choreography that needs exact timing.
+- Primitive mapping: spring config, damping, stiffness, mass.
+- Reduced motion: critically damped or instant states.
+- Performance hazards: too many active springs and inaccessible bounce.
+- Library policy: new dependency requires approval.
+
+### Lottie
+- Approved use: exported illustration, onboarding, empty states, and success moments.
+- Avoid: critical controls or data-only content.
+- Primitive mapping: JSON animation, renderer, poster fallback.
+- Reduced motion: static poster frame or no loop.
+- Performance hazards: large JSON, endless loops, renderer overhead.
+- Lifecycle: stop and destroy when removed.
+- Library policy: new dependency requires approval.
+
+### Rive Web Runtime
+- Approved use: state-machine illustration and interactive animated diagrams.
+- Avoid: essential controls without static equivalent.
+- Primitive mapping: Rive state machines, inputs, canvas/WebGL renderer.
+- Reduced motion: static artboard or disabled autoplay.
+- Performance hazards: runtime object leaks, heavy canvases.
+- Lifecycle: clean up runtime objects.
+- Library policy: new dependency requires approval.
+
+### Three.js And react-three-fiber
+- Approved use: real spatial product or scene requirements.
+- Avoid: decorative background only.
+- Primitive mapping: scene, camera, mesh, material, render loop, controls.
+- Reduced motion: static render or 2D equivalent.
+- Performance hazards: GPU cost, battery drain, inaccessible canvas.
+- Lifecycle: dispose geometries, materials, textures, and renderers.
+- Library policy: new dependency requires approval.
+
+### Spline And WebGL Advisory
+- Approved use: visual reference or exported asset only when runtime support and dependency policy are explicit.
+- Avoid: assuming a Spline reference can ship directly.
+- Primitive mapping: static export, embedded scene, or translated Three.js model.
+- Reduced motion: poster frame.
+- Performance hazards: black-box runtime size and device load.
+- Library policy: advisory unless approved.
+
+## Native And Mobile Platforms
+
+### SwiftUI
+- Approved use: state-driven transitions, matched geometry, gestures, and springs.
+- Avoid: hiding navigation or focus order changes behind animation.
+- Primitive mapping: `withAnimation`, `transition`, `matchedGeometryEffect`, gestures.
+- Reduced motion: inspect accessibility reduce-motion setting and reduce travel.
+- Performance hazards: animating large view trees and repeated layout invalidation.
+
+### UIKit And Core Animation
+- Approved use: explicit view, layer, and transition animations.
+- Avoid: running animations outside lifecycle ownership.
+- Primitive mapping: UIView animation, Core Animation, interruptible animators.
+- Reduced motion: instant state or crossfade where essential.
+- Performance hazards: offscreen rendering and layer churn.
+
+### Jetpack Compose
+- Approved use: declarative state animation, visibility, content size, and transitions.
+- Avoid: motion that changes semantic order.
+- Primitive mapping: animate APIs, updateTransition, AnimatedVisibility.
+- Reduced motion: use platform animator duration scale and static fallbacks.
+- Performance hazards: recomposition churn and list animation without keys.
+
+### Android MotionLayout
+- Approved use: complex constraint transitions and coordinated layout states.
+- Avoid: simple microinteractions.
+- Primitive mapping: constraint sets, transitions, progress.
+- Reduced motion: jump to end state or simplified transition.
+- Performance hazards: constraint complexity and gesture conflict.
+
+### React Native Reanimated 4.x
+- Approved use: gesture-coupled native-thread animation with approved architecture.
+- Avoid: projects not on required New Architecture/Fabric posture.
+- Primitive mapping: shared values, worklets, gestures, animations.
+- Reduced motion: static state, shorter duration, or disabled gesture flourish.
+- Performance hazards: JS/native boundary assumptions and missing cleanup.
+- Library policy: new dependency and architecture requirements need approval.
+
+### Flutter Animation APIs
+- Approved use: implicit and explicit animation, page transitions, gestures.
+- Avoid: animation controller sprawl without lifecycle ownership.
+- Primitive mapping: AnimationController, Tween, AnimatedBuilder, Hero.
+- Reduced motion: respect platform accessibility and provide non-motion path.
+- Performance hazards: expensive rebuilds and missing controller disposal.
+
+### Haptics
+- Approved use: threshold, snap, selection, and confirmation feedback on native surfaces.
+- Avoid: web-only assumptions, loops, errors, or high-frequency feedback.
+- Primitive mapping: platform haptics, optional vibration where appropriate.
+- Reduced motion: haptics cannot be the only feedback.
+- Performance hazards: annoyance, accessibility conflict, battery impact.

package/skills/opendevbrowser-motion-design/assets/templates/motion-audit-report.v1.md

@@ -0,0 +1,70 @@
+# Motion Audit Report
+
+## Scope
+
+- Surface:
+- Task:
+- Browser/session:
+
+## Contract Source
+
+- Motion contract:
+- Design-agent contract:
+- Related skills:
+
+## Selected Patterns
+
+| Pattern | User value | Driver | Evidence |
+|---|---|---|---|
+|  |  |  |  |
+
+## Device Matrix
+
+| Posture | Result | Evidence | Issues |
+|---|---|---|---|
+| Phone portrait |  |  |  |
+| Tablet |  |  |  |
+| Desktop |  |  |  |
+| Short viewport |  |  |  |
+| Reduced motion |  |  |  |
+
+## Reduced-motion Result
+
+- `prefers-reduced-motion` path:
+- Meaning preserved:
+- Task completion preserved:
+
+## Keyboard Result
+
+- Focus order:
+- Focus visibility:
+- Escape paths:
+
+## Performance Result
+
+- Frame stability:
+- Input latency:
+- Layout shift:
+- Overflow:
+- Cleanup:
+
+## Temporal Evidence
+
+- `screencast-start` artifact:
+- `screencast-stop` artifact:
+- `snapshot`:
+- `screenshot`:
+- `debug-trace-snapshot`:
+- Console/network stability:
+
+## Issues
+
+| ID | Severity | Evidence | Fix |
+|---|---|---|---|
+|  |  |  |  |
+
+## Release Decision
+
+- Decision: block or pass
+- Reason:
+- Remaining risk:

package/skills/opendevbrowser-motion-design/assets/templates/motion-contract.v1.json

@@ -0,0 +1,79 @@
+{
+  "schemaVersion": "1.0.0",
+  "intent": {
+    "surface": "<page-or-component>",
+    "userValue": "<what-motion-clarifies>",
+    "nonGoals": []
+  },
+  "motionLanguage": {
+    "personality": "<precise-motion-language>",
+    "timingTokens": {
+      "instantMs": 0,
+      "microMs": 120,
+      "standardMs": 220,
+      "expressiveMs": 420
+    },
+    "easingTokens": {
+      "standard": "cubic-bezier(0.2, 0, 0, 1)",
+      "emphasized": "cubic-bezier(0.2, 0, 0, 1)",
+      "exit": "cubic-bezier(0.4, 0, 1, 1)"
+    },
+    "springTokens": {
+      "settle": {
+        "stiffness": 260,
+        "damping": 28,
+        "mass": 1
+      }
+    }
+  },
+  "selectedPatterns": [
+    {
+      "pattern": "no-motion stability",
+      "userValue": "protect task speed",
+      "driver": "state",
+      "owner": "<component-or-route>"
+    }
+  ],
+  "devicePosture": {
+    "mobilePortrait": "short travel, no pinning",
+    "mobileLandscape": "short viewport safe",
+    "tablet": "moderate travel",
+    "desktop": "local transitions",
+    "largeMonitor": "anchor to local region",
+    "foldable": "progressive enhancement only"
+  },
+  "accessibility": {
+    "prefersReducedMotion": "meaning-preserving static or opacity-only path",
+    "keyboardOrder": "unchanged",
+    "focusPolicy": "visible and stable",
+    "motionOnlyFeedback": false
+  },
+  "performance": {
+    "frameBudget": "transform and opacity first",
+    "layoutAnimationAllowed": false,
+    "scrollListenerPolicy": "bounded and passive",
+    "cleanupRequired": true
+  },
+  "libraryPolicy": {
+    "approvedExistingLibraries": [],
+    "newRuntimeDependencies": [],
+    "approvalReference": null
+  },
+  "verificationPlan": {
+    "viewports": [
+      "phone-portrait",
+      "tablet",
+      "desktop",
+      "short-viewport",
+      "reduced-motion"
+    ],
+    "opendevbrowserEvidence": [
+      "snapshot",
+      "screenshot",
+      "debug-trace-snapshot",
+      "screencast-start",
+      "screencast-stop"
+    ],
+    "releaseGate": "assets/templates/motion-release-gate.v1.json"
+  }
+}

package/skills/opendevbrowser-motion-design/assets/templates/motion-release-gate.v1.json

@@ -0,0 +1,18 @@
+{
+  "schemaVersion": "1.0.0",
+  "decision": "block",
+  "checks": [
+    { "id": "contract", "status": "pending", "blocking": true, "evidence": "" },
+    { "id": "pattern-justification", "status": "pending", "blocking": true, "evidence": "" },
+    { "id": "reduced-motion", "status": "pending", "blocking": true, "evidence": "" },
+    { "id": "keyboard", "status": "pending", "blocking": true, "evidence": "" },
+    { "id": "viewports", "status": "pending", "blocking": true, "evidence": "" },
+    { "id": "temporal-proof", "status": "pending", "blocking": true, "evidence": "" },
+    { "id": "debug-trace", "status": "pending", "blocking": true, "evidence": "" },
+    { "id": "console-network", "status": "pending", "blocking": true, "evidence": "" },
+    { "id": "performance", "status": "pending", "blocking": true, "evidence": "" },
+    { "id": "overflow", "status": "pending", "blocking": true, "evidence": "" },
+    { "id": "focus", "status": "pending", "blocking": true, "evidence": "" },
+    { "id": "library-policy", "status": "pending", "blocking": true, "evidence": "" }
+  ]
+}

package/skills/opendevbrowser-motion-design/assets/templates/motion-viewport-matrix.v1.json

@@ -0,0 +1,76 @@
+{
+  "schemaVersion": "1.0.0",
+  "rows": [
+    {
+      "id": "phone-portrait",
+      "viewport": { "width": 390, "height": 844 },
+      "pointer": "coarse",
+      "requirements": ["short travel", "no default parallax", "no pinned scroll by default"]
+    },
+    {
+      "id": "phone-landscape",
+      "viewport": { "width": 844, "height": 390 },
+      "pointer": "coarse",
+      "requirements": ["short viewport safe", "primary actions visible"]
+    },
+    {
+      "id": "tablet-portrait",
+      "viewport": { "width": 820, "height": 1180 },
+      "pointer": "coarse",
+      "requirements": ["touch thresholds", "moderate travel"]
+    },
+    {
+      "id": "tablet-landscape",
+      "viewport": { "width": 1180, "height": 820 },
+      "pointer": "coarse",
+      "requirements": ["touch and keyboard parity"]
+    },
+    {
+      "id": "desktop",
+      "viewport": { "width": 1440, "height": 900 },
+      "pointer": "fine",
+      "requirements": ["local transitions", "keyboard parity"]
+    },
+    {
+      "id": "large-monitor",
+      "viewport": { "width": 1920, "height": 1080 },
+      "pointer": "fine",
+      "requirements": ["avoid excessive travel", "anchor to local regions"]
+    },
+    {
+      "id": "short-viewport",
+      "viewport": { "width": 1280, "height": 560 },
+      "pointer": "fine",
+      "requirements": ["no pinning", "no required tall-stage animation"]
+    },
+    {
+      "id": "reduced-motion",
+      "viewport": { "width": 1440, "height": 900 },
+      "media": { "prefersReducedMotion": "reduce" },
+      "requirements": ["meaning preserved", "task completion preserved"]
+    },
+    {
+      "id": "coarse-pointer",
+      "pointer": "coarse",
+      "requirements": ["no hover-only affordance", "large touch targets"]
+    },
+    {
+      "id": "fine-pointer",
+      "pointer": "fine",
+      "requirements": ["hover has focus equivalent"]
+    },
+    {
+      "id": "keyboard-only",
+      "input": "keyboard",
+      "requirements": ["focus visible", "focus order stable", "escape paths work"]
+    },
+    {
+      "id": "reduced-power",
+      "requirements": ["fewer simultaneous animations", "static skeletons preferred"]
+    },
+    {
+      "id": "foldable-adaptive",
+      "requirements": ["device-posture progressive enhancement only", "default responsive path works first"]
+    }
+  ]
+}

package/skills/opendevbrowser-motion-design/scripts/motion-workflow.sh

@@ -0,0 +1,163 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+skill_root="$(cd "$script_dir/.." && pwd)"
+skills_root="$(cd "$skill_root/.." && pwd)"
+best_practices_root="$skills_root/opendevbrowser-best-practices"
+design_agent_root="$skills_root/opendevbrowser-design-agent"
+# shellcheck source=../../opendevbrowser-best-practices/scripts/resolve-odb-cli.sh
+source "$best_practices_root/scripts/resolve-odb-cli.sh"
+
+render_cli_prefix() {
+  local rendered=()
+  local part
+  for part in "${ODB_CLI[@]}"; do
+    rendered+=("$(printf '%q' "$part")")
+  done
+  printf '%s' "${rendered[*]}"
+}
+
+CLI_PREFIX="$(render_cli_prefix)"
+
+quote_path() {
+  printf '%q' "$1"
+}
+
+print_cat() {
+  printf 'cat %s\n' "$(quote_path "$1")"
+}
+
+print_validator() {
+  printf '%s\n' "$(quote_path "$skill_root/scripts/validate-skill-assets.sh")"
+}
+
+print_help() {
+  cat <<EOF
+OpenDevBrowser motion-design workflow router
+
+Usage:
+  $(quote_path "$script_dir/motion-workflow.sh") <workflow>
+
+Workflows:
+  contract-first
+  pattern-select
+  viewport-matrix
+  reduced-motion-check
+  temporal-proof
+  scroll-stage-audit
+  gesture-motion
+  performance-audit
+  release-gate
+  list
+EOF
+}
+
+workflow="${1:-list}"
+
+case "$workflow" in
+  list)
+    print_help
+    ;;
+  contract-first)
+    print_cat "$skill_root/assets/templates/motion-contract.v1.json"
+    print_cat "$skill_root/artifacts/motion-terminology.md"
+    print_cat "$skill_root/artifacts/platform-framework-guide.md"
+    print_cat "$design_agent_root/assets/templates/design-contract.v1.json"
+    cat <<'EOF'
+# Fill the motion contract before implementation and connect it to design-agent motionSystem.
+EOF
+    ;;
+  pattern-select)
+    print_cat "$skill_root/artifacts/motion-pattern-catalog.md"
+    print_cat "$skill_root/artifacts/motion-anti-patterns.md"
+    print_cat "$skill_root/assets/templates/motion-contract.v1.json"
+    cat <<'EOF'
+# Select only patterns with user value, fallback, device posture, and evidence.
+EOF
+    ;;
+  viewport-matrix)
+    print_cat "$skill_root/assets/templates/motion-viewport-matrix.v1.json"
+    print_cat "$skill_root/artifacts/device-breakpoint-posture.md"
+    cat <<EOF
+$CLI_PREFIX launch --no-extension --start-url <url> --output-format json
+$CLI_PREFIX screenshot --session-id <session-id>
+$CLI_PREFIX snapshot --session-id <session-id>
+# Repeat for phone, tablet, desktop, short viewport, reduced motion, coarse pointer, and keyboard-only posture.
+EOF
+    ;;
+  reduced-motion-check)
+    print_cat "$skill_root/artifacts/accessibility-reduced-motion.md"
+    print_cat "$skill_root/assets/templates/motion-audit-report.v1.md"
+    cat <<EOF
+$CLI_PREFIX launch --no-extension --start-url <url> --output-format json
+$CLI_PREFIX snapshot --session-id <session-id>
+$CLI_PREFIX screenshot --session-id <session-id>
+$CLI_PREFIX debug-trace-snapshot --session-id <session-id>
+# Emulate or configure prefers-reduced-motion, then prove meaning and task completion are preserved.
+EOF
+    ;;
+  temporal-proof)
+    print_cat "$skill_root/artifacts/open-dev-browser-motion-evidence.md"
+    cat <<EOF
+$CLI_PREFIX launch --no-extension --start-url <url> --output-format json
+$CLI_PREFIX snapshot --session-id <session-id>
+$CLI_PREFIX screenshot --session-id <session-id>
+$CLI_PREFIX debug-trace-snapshot --session-id <session-id>
+$CLI_PREFIX screencast-start --session-id <session-id> --output-dir <artifact-dir>
+# Perform the motion interaction: click, pointer-drag, scroll, keyboard, or route transition.
+$CLI_PREFIX screencast-stop --session-id <session-id> --screencast-id <screencast-id>
+$CLI_PREFIX snapshot --session-id <session-id>
+$CLI_PREFIX screenshot --session-id <session-id>
+$CLI_PREFIX debug-trace-snapshot --session-id <session-id>
+EOF
+    ;;
+  scroll-stage-audit)
+    print_cat "$skill_root/artifacts/motion-pattern-catalog.md"
+    print_cat "$design_agent_root/artifacts/scroll-reveal-surface-planning.md"
+    print_cat "$skill_root/artifacts/device-breakpoint-posture.md"
+    cat <<EOF
+$CLI_PREFIX launch --no-extension --start-url <url> --output-format json
+$CLI_PREFIX screencast-start --session-id <session-id> --output-dir <artifact-dir>
+$CLI_PREFIX scroll --session-id <session-id> --dy 900
+$CLI_PREFIX screencast-stop --session-id <session-id> --screencast-id <screencast-id>
+$CLI_PREFIX debug-trace-snapshot --session-id <session-id>
+EOF
+    ;;
+  gesture-motion)
+    print_cat "$skill_root/artifacts/motion-pattern-catalog.md"
+    print_cat "$skill_root/artifacts/device-breakpoint-posture.md"
+    cat <<EOF
+$CLI_PREFIX launch --no-extension --start-url <url> --output-format json
+$CLI_PREFIX pointer-move --session-id <session-id> --x <x> --y <y>
+$CLI_PREFIX pointer-down --session-id <session-id>
+$CLI_PREFIX pointer-drag --session-id <session-id> --to-x <x2> --to-y <y2>
+$CLI_PREFIX pointer-up --session-id <session-id>
+$CLI_PREFIX snapshot --session-id <session-id>
+EOF
+    ;;
+  performance-audit)
+    print_cat "$skill_root/artifacts/performance-frame-budget.md"
+    print_cat "$skill_root/assets/templates/motion-audit-report.v1.md"
+    cat <<EOF
+$CLI_PREFIX launch --no-extension --start-url <url> --output-format json
+$CLI_PREFIX debug-trace-snapshot --session-id <session-id>
+$CLI_PREFIX screenshot --session-id <session-id>
+# Pair browser proof with framework profiler or performance trace for complex motion.
+EOF
+    ;;
+  release-gate)
+    print_validator
+    print_cat "$skill_root/artifacts/motion-release-gate.md"
+    print_cat "$skill_root/assets/templates/motion-release-gate.v1.json"
+    print_cat "$skill_root/assets/templates/motion-audit-report.v1.md"
+    cat <<'EOF'
+# Mark every blocking check pass/fail with evidence. Missing temporal proof blocks release.
+EOF
+    ;;
+  *)
+    echo "Unknown workflow: $workflow" >&2
+    print_help
+    exit 2
+    ;;
+esac