hookcode-preview-highlight

name	hookcode-preview-highlight
description	End-to-end workflow for HookCode preview DOM highlighting check/start/stop previews, install dependencies, send highlight commands, and verify preview bridge readiness via PAT-authenticated APIs. Use when debugging cross-origin preview iframes, validating bridge integration, or scripting highlight requests against task-group previews.
tags	["preview","debugging","highlight"]

Hookcode Preview Highlight

Overview

This skill ships JS request scripts (with .env loading) and protocol notes for the complete preview highlight flow: check preview status, start previews, install dependencies if needed, send highlight commands, and stop previews after debugging. It also explains the bridge handshake required for cross-origin iframes so you can confirm whether highlight commands are actually reaching the preview DOM. Selector rules now include CSS selectors plus text/attribute matchers (for example text:Save, attr:data-testid=cta, data:testid=cta, aria:label=Search, role:button, or loose data-testid=cta). If a highlight command includes targetUrl, the preview UI will auto-navigate to that URL (and push it to the iframe history) unless the user locks auto-navigation in the toolbar. Target URL matching now supports route patterns like :id, *, **, hash/query wildcards, and || alternatives to avoid unnecessary navigation.

Capabilities

• Query preview status to discover instance names and availability before highlighting.
• Start preview instances or install dependencies when the dev server is missing.
• Send highlight commands with selector/mode/color/padding/scroll options via the backend API.
• Send optional bubble tooltip payloads alongside highlights (text + placement + theme).
• Provide CLI flags that map one-to-one with highlight + bubble payload fields.

• Support selector matcher rules like text:, attr:, data:, aria:, role:, and testid: when CSS selectors are not enough.

• Auto-navigate previews when targetUrl is supplied, with a lock toggle and route-matching rules to keep the current URL stable.

• Verify bridge readiness by checking subscribers and bridge error responses.
• Stop previews after debugging to free ports and resources.

Quick Start

1. Copy .env.example → .env inside this skill folder and fill in HOOKCODE_API_BASE_URL, HOOKCODE_PAT, and HOOKCODE_TASK_GROUP_ID (optional: HOOKCODE_PREVIEW_INSTANCE).
2. Fetch preview status to confirm instance names:

node .codex/skills/hookcode-preview-highlight/scripts/preview_status.mjs \
  --task-group <taskGroupId>

3. Send a highlight command (highlight parameters must be passed via CLI flags):

node .codex/skills/hookcode-preview-highlight/scripts/preview_highlight.mjs \
  --task-group <taskGroupId> \
  --instance app \
  --selector ".page-kicker"

4. Send a highlight + bubble command:

node .codex/skills/hookcode-preview-highlight/scripts/preview_highlight.mjs \
  --task-group <taskGroupId> \
  --instance app \
  --selector ".page-kicker" \
  --target-url "/add" \
  --bubble-text "Update this headline" \
  --bubble-placement right \
  --bubble-theme dark

Environment Variables

Set these in .env (or override via CLI flags). Highlight-specific options are CLI-only.

Variable	Purpose	Used by
HOOKCODE_API_BASE_URL	Base URL of the HookCode backend (for example http://127.0.0.1:4000).	All scripts
HOOKCODE_PAT	PAT token for API authentication.	All scripts
HOOKCODE_TASK_GROUP_ID	Default task group id to target.	All scripts
HOOKCODE_PREVIEW_INSTANCE	Default preview instance name (for example app).	preview_highlight.mjs

Operations (HTTP)

1) Get preview status

Endpoint: GET /api/task-groups/:id/preview/status

Purpose: Confirm the preview is configured, see instance names, and check running/starting status before highlighting.

Script: scripts/preview_status.mjs

node .codex/skills/hookcode-preview-highlight/scripts/preview_status.mjs \
  --task-group <taskGroupId>

2) Start preview

Endpoint: POST /api/task-groups/:id/preview/start

Purpose: Start all configured preview instances so the highlight API can reach a running dev server.

Script: scripts/preview_start.mjs

node .codex/skills/hookcode-preview-highlight/scripts/preview_start.mjs \
  --task-group <taskGroupId>

3) Install preview dependencies

Endpoint: POST /api/task-groups/:id/preview/dependencies/install

Purpose: Run dependency installation without starting the dev server. Use this when highlight requests fail because the dev server never started.

Script: scripts/preview_dependencies_install.mjs

node .codex/skills/hookcode-preview-highlight/scripts/preview_dependencies_install.mjs \
  --task-group <taskGroupId>

4) Send highlight command

Endpoint: POST /api/task-groups/:id/preview/:instance/highlight

Purpose: Forward a DOM highlight command to the preview iframe bridge.

Script: scripts/preview_highlight.mjs

Parameters:

• selector (required): CSS selector to highlight (max length 200); supports matcher rules like text:, attr:, data:, aria:, role:, testid:, or loose data-testid=....

• targetUrl (optional): preview URL or path to navigate to before highlighting; matching supports :param, *, **, query/hash wildcards (e.g. /users/:id?tab=*), and || alternatives (first entry is used for navigation).

TargetUrl matching rules:

• :param matches a single path segment (e.g. /users/:id).
• * matches any characters within a segment; ** matches across segments (e.g. /projects/**/settings).
• Query rules only require params you declare; use ?tab for any value or ?tab=* for wildcard values.
• Hash rules accept wildcards like #section-*.
• || separates alternatives; the first entry is used for navigation if auto-navigation is needed.

• padding (optional): number of pixels around the element (0-64, default 4).
• color (optional): CSS color string for outline/glow (max length 40).
• mode (optional): outline or mask (default outline).
• scrollIntoView (optional): true/false (default false).
• bubble (optional): object for tooltip rendering near the highlight.
  • text (required when bubble provided): text content to display (1-280 chars).
  • placement (optional): top | right | bottom | left | auto (default auto); auto prefers bottom/top and flips when space is insufficient to avoid clipping.
  • align (optional): start | center | end (default center).
  • offset (optional): number of pixels between highlight and bubble (0-64, default 10).
  • maxWidth (optional): max width in px (120-640, default 320).
  • theme (optional): dark | light (default dark).
  • background (optional): bubble background CSS color override.
  • textColor (optional): bubble text color override.
  • borderColor (optional): bubble border color override.
  • radius (optional): bubble corner radius in px (0-24, default 12).
  • arrow (optional): true/false to show the pointer (default true).
• requestId (optional): client-defined id for tracking.

Response:

• success, requestId, subscribers, and optional targetUrl echo for navigation-aware clients.

node .codex/skills/hookcode-preview-highlight/scripts/preview_highlight.mjs \
  --task-group <taskGroupId> \
  --instance app \
  --selector ".page-kicker" \
  --mode outline \
  --color "#ff4d4f" \
  --padding 4 \
  --scroll true \
  --bubble-text "Edit this title" \
  --bubble-placement top \
  --bubble-align center \
  --bubble-offset 12 \
  --bubble-theme dark

5) Stop preview

Endpoint: POST /api/task-groups/:id/preview/stop

Purpose: Stop preview instances after debugging to free ports and resources.

Script: scripts/preview_stop.mjs

node .codex/skills/hookcode-preview-highlight/scripts/preview_stop.mjs \
  --task-group <taskGroupId>

Bridge requirements (must be installed in the preview app)

• Copy shared/preview-bridge.js into the preview project and import it in the app entry file.
• The bridge answers a hookcode:preview:ping handshake from HookCode. Only after the handshake does the frontend forward highlight commands.
• A highlight API response with subscribers: 0 usually means the preview UI is not connected or the bridge did not answer the ping.

Troubleshooting

• preview_not_running (409): Start the preview first or check the instance name.
• selector_required / selector_not_found (response from bridge): verify the selector exists in the preview DOM.
• The bridge now retries selector resolution with querySelectorAll, simple id/class/tag fallbacks, and open shadow-root scans; when in doubt, send a stable CSS selector that maps to a visible element.

• If a targetUrl is supplied but the preview does not navigate, check whether the auto-navigation lock button is enabled in the preview toolbar.

• bubble_text_required: a bubble payload was supplied without valid text.
• fetch failed: the backend is unreachable; check HOOKCODE_API_BASE_URL and local network access.
• subscribers: 0: the preview UI is not listening or the bridge script is missing.

References

• references/highlight-protocol.md for full protocol details and bridge message formats.