visual-companion

Visual companion

A small local server that shows HTML screens in the DorkOS frame (DorkOS tokens, both themes, history, pin notes) on the DorkOS canvas. You write a screen; it appears; what the person does there comes back to you.

Use it when the answer is visual: layouts, mockups, motion, side-by-side directions, diagrams. Stay in chat when the answer is words: scope, trade-offs, concepts. For a quick pick between a few labelled choices, a dorkos-ui widget in chat is lighter (its buttons give you a turn directly). Use the companion when the choice needs to be seen.

All commands below are scripts/vc in this skill. Each prints one JSON object.

The loop

1. Show a screen. Write a fragment to a temp file, then:

   scripts/vc show /tmp/layout.html            # add --wake to let a Send reach you
   

   This starts the server if needed (on the port this session had last, else a free one; it never touches another process), writes the screen, and returns url, screen, screen_url and shots (light and dark PNGs you can Read to check your own work). Run it from your project root, or pass --project-dir.
2. Open it on the canvas. The first time, or whenever the canvas lost it: control_ui → browser_navigate with url. Never ask the person to open a URL. In a room, pass target: { roomId } so it lands on the room's canvas. Once it's open, later screens arrive by themselves (WebSocket, falling back to polling through the preview proxy). There's no need to navigate again.
3. Say one line in chat about what's on screen and what you want from it.
4. Read what happened. Feedback arrives in chat. Structured detail is in scripts/vc events (only what's new since your last read).
5. Iterate with a new screen (layout-v2.html). Names are never reused; vc show adds -2, -3 if needed. When the conversation moves on, show a short "Back in chat" screen so a settled choice doesn't linger.

Check it's alive on every turn before relying on it: scripts/vc status (running: false → the next vc show restarts it with the same screens, history and port; re-open the canvas if a screen doesn't appear). It stops itself after 4 hours idle (vc start --idle 30m to change; polls from an open tab don't count).