# Claude Reframe

An unofficial Chrome extension (Manifest V3) that rearranges claude.ai. **Use at your own risk: it will likely break when Anthropic updates the Claude interface.** It splits the screen: the conversation stays on the left and the message box moves to a full-height pane on the right, so a long prompt no longer grows the box until the answer you are reading is pushed off the screen. Version 0.2 adds an on-page Split view / Normal view button, a session and weekly usage readout, per-area colors that tell claude.ai chat from claude.ai/code, and a settings page with import and export.

It lives in the toolbox at `tools/public/reframe/` → `/reframe`. That page (`index.html`) is the download and install page with the version history; the extension itself is in `extension/` and is downloaded as a zip from `releases/`, the same way as DustyTab.

| File | What it is |
|---|---|
| `CLAUDE.md` | Rules for anyone changing things here |
| `README.md` | This file: layout, how it works, how to test and release |
| `TASKS.md` | The live checklist and "Next up" |
| `DECISIONS.md` | What is decided and what waits on Austin |
| `info.md` | The public write-up at `/reframe/info` |
| `meta.json` | Toolbox metadata |
| `index.html` | The toolbox page: download, install and update steps, version history |

## Layout

```
extension/
  manifest.json      MV3; "key" pins the extension id; runs on https://claude.ai/* only; Alt+Shift+S
  shared.js          settings, normalizers, site key, version compare (classic script; adds the global Reframe)
  content.js         the page script: finds the message box, marks elements, injects the style, resize handle
  popup.html/js/css  the toolbar popup: status, usage, split on/off, width, pane level, diagnostics, update check, link to settings
  options.html/js/css  the settings page (also the extension's options page): split, colors, dock, usage, export and import
  background.js      forwards the keyboard shortcut to the Claude tab
  icons/             icon.svg (source) and the PNGs Chrome uses
  HOW-TO-INSTALL-AND-UPDATE.txt   shipped inside the zip
releases/            releases.json (version history, newest first) and a zip per version
dev/                 make-icons.mjs, make-release.mjs
tests/unit/          node --test for shared.js
tests/e2e/           loads the real extension against stand-in claude.ai pages
```

## How it works

- **Finding things without class names.** The message box is the lowest visible `textarea`, `[contenteditable]` or `[role=textbox]`. The pane is the largest wrapper around it that holds almost no other text and doesn't contain another text field or a scrolling area (a conversation holds a lot of text; the composer holds a button and a disclaimer). The conversation is the nearest scrolling ancestor of the pane, else the largest scrolling block on the page, else the document itself.
- **Layout.** The pane gets `position: fixed` over the right part of the conversation area, full height, with the width a percentage of that area (default 40%). The conversation gets a `max-width` that leaves room for it. The box and its wrappers lose their `max-height` (wrappers keep their own height) and the box gets a tall minimum height. Ancestors with a transform, filter or containment (which would turn `fixed` into "fixed inside this element") are neutralized while the split is on.
- **Reversible.** Everything is `data-reframe` attributes, a few CSS variables on `<html>`, one `<style id="reframe-style">` and one resize handle. Switching off removes the attributes and hides the handle.
- **Staying attached.** A `MutationObserver` (throttled) checks that the marked elements are still connected and still marked; if React replaced one, the full detection runs again. It also re-runs on address changes (polled, because single-page apps change the address without a page load), on resize, and when settings change.
- **When it guesses wrong.** The popup's Pane level − and + choose a smaller or larger wrapper, stored per area (`claude.ai/chat` and `claude.ai/code`). Copy diagnostics gives the tags, attributes, classes and sizes of what it found, with no page text.
- **The dock.** `#reframe-dock` holds the Split view / Normal view button, a ⚙ that asks the background worker to open the settings page, and the usage meters. With the split on and the placement `pane-bottom` (default) or `pane-top`, it is a strip exactly as wide as the pane, and the pane gets padding for it (`--reframe-dock-h`, measured), so it never covers Claude's own controls. In normal view, or with a corner placement, it is a small card in that corner (`bottom-right` for the pane placements).
- **Pace meters.** `paceInfo()` in `shared.js`: the window length is 5 h (session) or 7 d (week); elapsed = 100 × (now − (resetsAt − window)) / window; the verdict compares used % with elapsed % (under at −3 or less, on pace within ±3, over up to 15, high above). Each meter draws used (bar), elapsed (shade and a line), the verdict, the reset clock time (`formatClock`) and the time left.
- **Long messages.** `updateEditorMax()` measures everything in the pane that isn't the box (the lowest bottom edge of the pane's other elements, plus padding) and sets `--reframe-editor-max` so the box stops growing at the top of the pane and scrolls inside itself; it re-runs when the box resizes and on every `check()`.
- **Popups and pickers (0.3.1).** Three layers keep transient UI from being mistaken for the page. (1) `popupField()`: a text field inside an element with a dialog, menu, listbox, combobox or tooltip role (or `aria-modal`), with a search/combobox role or type, or labelled search, filter or find, is never the message box. (2) `openOverlays()`: while any such overlay is visible, `check()` does not re-layout (for at most 6 seconds, in case a page keeps a dialog around), and overlay text is subtracted from the "is there a conversation" test. (3) Sanity checks: a conversation area under 480 px or a pane under 240 px is not split; after applying, a pane that is too short, off screen, the wrong width, or leaves the conversation under 300 px wide is undone at once, with a 15 second back-off (cleared on address change and settings change) so it can't flicker.
- **Top buttons.** `headerClearance()` finds buttons and links in the top band (top edge within 80 px) that overlap the pane's horizontal range and starts the pane below the lowest of them.
- **Chat vs. Code.** `siteKey`/`areaOf` in `shared.js` treat any path starting `/code` as Code and everything else as chat. Each area has a color: a bar across the top (`#reframe-bar`), the pane's left edge, an optional faint tint (`#reframe-tint`, up to 8%) and an optional `[Code] ` title prefix. Both areas are on `claude.ai`, so one content script match covers them.
- **Usage.** `readUsage()` in `content.js` asks `/api/organizations` for the account's organization, then `/api/organizations/<id>/usage`, with the page's own cookies (same origin, no new permission). `parseUsage` in `shared.js` reads `five_hour` and `seven_day` (`utilization` percent, `resets_at`) and tolerates other shapes. These addresses are undocumented and were not checked against the live site; on any failure the readout says "Usage unavailable" and keeps the last good numbers. Polled every few minutes (setting) and when the tab becomes visible.
- **Settings export and import.** `{ app: "claude-reframe", format: 1, version, exported, settings }`; import also accepts a bare settings object, refuses anything that isn't recognisably ours, and always goes through `normalizeSettings`.
- **Settings** are in `chrome.storage.local` under `reframe.settings`: enabled, width percent, wait for the first message, minimum window width, pane level per area, area colors, top line, tint, title prefix, dock on/off and placement (`dockPlace`; the 0.2.0 `dockCorner` is ignored), usage on/off and interval.
- **Updates.** Like DustyTab: download the new zip from the page, empty the folder, paste, reload. The popup's "Check for updates" asks `app.austinpranger.com/reframe/releases/releases.json` (after the user allows that one site) and says whether a newer version exists; it never downloads or installs anything.

## Install (Austin, Windows 10 and Chrome)

The steps are on `/reframe` and in `extension/HOW-TO-INSTALL-AND-UPDATE.txt`. During development you can load `tools/public/reframe/extension/` from a clone directly and press reload after pulling.

## Tests

- Unit: `node --test tools/public/reframe/tests/unit/*.test.mjs`
- End to end: `node tools/public/reframe/tests/e2e/extension.mjs --shots <dir>`. Launches Chromium with the extension and answers every request to claude.ai with a stand-in page. Three layouts with meaningless class names (message box inside the scrolling conversation; separate blocks; a document-scrolling page with a transformed wrapper) are split, given a very long prompt, resized by dragging, nudged by pane level, shrunk below the minimum width, toggled, switched off (no marks left), and re-attached after the page replaces the composer or renames every class.

## Releasing

See "Before you push" in `CLAUDE.md`.

## Pending and intended next steps

The short version of `TASKS.md` for an agent who has only this file open.

1. **Waiting on Austin:** install the current version on the real claude.ai and Claude Code on the web and report what the popup's status box says, plus "Copy diagnostics" output. It was built and tested only against stand-in pages, because claude.ai cannot be reached from the build environment.
2. **Check the usage readout** against the real thing: its two addresses were never reached from here, so "Usage unavailable" means the address or response shape needs fixing from diagnostics.
3. **Agent, recorder for TokenEcon (planned):** a timestamped log of the two usage readings (`five_hour`, `seven_day`, each with `utilization` and `resets_at`) stored locally and exported as JSON in the shape TokenEcon's Lab imports. Opt-in and off by default. This is the only planned change from another tool; read TokenEcon's `TASKS.md` item P2 first and touch nothing else.
4. **Later ideas:** a cap on how tall the message box may grow, pane on the left or stacked, a custom CSS box per area, more layout tweaks.

It will break when Anthropic changes the Claude interface; that is expected, say so on its page, and keep fixes small and tested against a stand-in layout that reproduces the new shape.
