# Companion movement prototype `dashboard/static/dashboard/companion.js` is a browser-only, framework-independent movement core. A host creates `new BrowserCompanion({ surfaces, name, reducedMotion, config, debug, debugSpeed })`; `surfaces()` returns `{ element, edge: 'top' | 'bottom', card?, explicit? }` entries. The host owns DOM discovery, preferences, and lifecycle. The core owns geometry validation, the directed route graph, movement and the coloured-square renderer. A host may supply a renderer implementing `render(position, state, name)` and `destroy()`. `bodySize` is the collision-body height in CSS pixels, independent of future sprite padding. Distance settings ending in `S` are multiples of that size. Speed settings ending in `SPerSec` use those units per second. Durations are milliseconds. `configure()` clamps invalid numeric overrides and ignores unknown keys. The defaults are initial visual tuning values, not animal measurements. An ordinary nested ledge needs a visible computed top border of at least 1 CSS pixel. Climb edges need visible left or right borders. Outer widget top and bottom edges are explicit known surfaces. Interactive controls are excluded unless a host deliberately opts one in. Geometry reads are performed on host refresh events, not each animation frame. The Project Manager adapter refreshes after grid changes, scrolling, resizing and widget mount or removal. Directed routes include short jumps, steps, walks, side climbs and bounded drops. A short attach hop can bridge the normal grid gap to a visible climb edge if its rise stays within `maxJumpRiseS`; this allows a safe drop to a lower card to be followed by a climb back. Downward climbing is not enabled. If a destination cannot be reached through a complete safe route, the companion idles or patrols its current ledge. Page scroll keeps its position attached to the source element. A disappearing destination cancels the move and recovers only to a nearby valid ledge; otherwise the box is hidden until a safe anchor appears. Background tabs pause motion, and reduced motion stops autonomous movement. The activity scheduler has calm, active and resting modes. Normal calm idle lasts 12–20 seconds, sleep 20–45 seconds, and purring/batting 2.2–3.8 seconds. Active bursts plan 2–5 safe transitions before returning to calm; short movement pauses do not choose unrelated passive states. Emote and sleep cooldowns prevent rapid cycling. Rest becomes more likely after repeated bursts. These bounds and activity weights are host-overridable through `config`. For local debugging only, `?companionFast` scales dwell and cooldown time by 10 without changing movement safety or turning on the visual debug overlay. Append `?companionDebug` to the dashboard URL to show ledges, climb edges, graph transitions, rejected element marks, active route and movement limits. The overlay is disabled by default and never receives pointer events. The debug label also shows the current state reason, recent timestamped transitions, mode, remaining burst steps, next dwell timer, active motion phase, and the number of safe jump/drop edges available from the current platform. `landing` lasts 260 ms and is entered only after an airborne jump, drop, or climb hop. Walking, pull-ups, reflow, and completed routes settle to `idle` instead. The dependency-free browser checks live in `dashboard/tests/companion_movement.html`. Serve the repository root with a local static server and open that page; every line should report `PASS`. The Django dashboard suite remains runnable with `.venv/bin/python manage.py test dashboard`.