# Strategy Bar -- Drop-in Component

Visual entry/stop/target bar for VWAP-band playbooks. Matches the design at
`/vwap-bands/strategy-bar/` (which is the demo page using this module).

## Files in this directory

| File | Role |
|------|------|
| `index.html` | Demo page (dogfoods the module on mock data). |
| `strategy-bar.js` | The component. Exposes `window.StrategyBar`. ~200 lines, no deps. |
| `strategy-bar.css` | Scoped styles (all rules under `.sb-scope`). |
| `playbooks.json` | Playbook data fixture. Currently hand-maintained; will be auto-generated nightly from `main.trade_playbooks`. |
| `README.md` | This file. |

## Quick integration (Accountability HUD)

Add this once in the HUD's HTML head:

```html
<link rel="stylesheet" href="/db_reports/james-monthly-reports/vwap-bands/strategy-bar/strategy-bar.css">
<script src="/db_reports/james-monthly-reports/vwap-bands/strategy-bar/strategy-bar.js"></script>
```

Then for each open position, render a bar:

```html
<div id="bar-ibit"></div>
<script>
  // One call. Looks up playbook in playbooks.json, computes currentSd, renders.
  StrategyBar.renderFromSlug(
    document.getElementById("bar-ibit"),
    "vwap-pull-in",               // playbook slug from main.trade_playbooks.playbook_slug
    {
      price: 43.23,                // live last price
      vwap: 42.88,                 // current VWAP
      sdBandWidth: 0.28,           // 1-SD band distance (vwap_upper_1 - vwap)
      fillPrice: 42.83,            // entry fill; omit for watchlist/pre-entry
      daysInSetup: 3               // optional
    }
  );
</script>
```

That's the whole integration. No build step, no framework dependency.

## Compact mode (for tight rows in the open-positions table)

Add `sb-compact` to the container class to hide the name/meta column and let
the bar stretch to fill. Useful for inline in a table row:

```html
<td><div class="sb-scope sb-compact" id="bar-123"></div></td>
```

## Data contract

Fields consumed from `playbooks.json` per playbook:

| Field | Type | Notes |
|-------|------|-------|
| `slug` | string | Unique. Matches DB `playbook_slug`. |
| `name` | string | Display name. |
| `direction` | `"long"` \| `"short"` | Flips green (target) vs red (stop). |
| `entry_band_sd` | number | Entry reference in signed SD units. |
| `entry_band_sd_max` | number | Upper bound of entry zone (null = single band). |
| `stop_band_sd` | number \| null | null = structural stop (no red zone rendered). |
| `target_band_sd` | number | Target level. |
| `min_extension_sd` | number \| null | A-grade threshold; lights A+ badge when `|currentSd| >= this`. |
| `subtitle` | string | Short description under the name. |

Live fields the host supplies per render:

| Field | Source in Accountability |
|-------|--------------------------|
| `price` | Broker last price (already displayed as "Last Px"). |
| `vwap` | Current session VWAP. |
| `sdBandWidth` | `vwap_upper_1 - vwap` -- the 1-SD band unit. Already in `alerts_tradingview.indicator_alerts` per-entry; for live-quote context, compute from latest bar. |
| `fillPrice` | `avg_entry_price` from `main.open_positions`. Omit for watchlist. |
| `daysInSetup` | Derived from symbol's historical alert streak. Optional. |

## Mapping to `main.open_positions`

Suggested join to pick the right playbook per position:

```sql
SELECT op.*, tp.slug AS playbook_slug, tp.name AS playbook_name,
       tp.entry_band_sd, tp.stop_band_sd, tp.target_band_sd, tp.min_extension_sd
  FROM main.open_positions op
  LEFT JOIN main.trade_playbooks tp
    ON tp.strategy_name = op.strategy              -- or join on playbook_slug once wired
   AND tp.direction     = LOWER(op.position_side); -- 'long' / 'short'
```

## What's NOT wired yet

1. **Playbook auto-detection.** Currently the host has to pass the slug. A grader that matches a live trade to a playbook (by direction + entry band + SD position) is the next layer.
2. **Live streaming.** `renderFromSlug` reads once per call. For real-time updates call it on every quote tick, or wire a `StrategyBar.update(container, { currentSd })` patch method (TBD).
3. **API endpoint.** `playbooks.json` is static. Wire `/api/playbooks` to query `main.trade_playbooks WHERE is_active = TRUE` when the web-app stabilizes.

## Versioning

`StrategyBar.version` returns the module version. Bump on breaking changes.

Current: `1.0.0` (2026-04-22).
