diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2fe5cc5..9101288 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -196,11 +196,15 @@ Gaps handled explicitly rather than faked: inlined in the prompt as it is for Codex. - **`--model` wants `provider/model`.** A bare id cannot be resolved to a provider, so it is dropped with a warning rather than silently ignored. -- **Structured output is a prompt convention, not a constrained decode.** The model emits its - JSON inside `` tags within ordinary prose, and opencode's own extractor - frequently fails to lift it back out. The adapter parses the tag itself and strips it from the - streamed transcript on the way past — including when the opening tag arrives split across two - deltas. +- **Structured output is fragile twice over.** On the wire, `format` is a *forced tool call* — + opencode registers an internal StructuredOutput tool and sets `toolChoice: "required"`, which + providers reject outright on thinking/reasoning models (opencode#15226, closed upstream). The + adapter classifies that rejection, retries the turn once without `format`, and remembers the + model. In the text, the JSON arrives inside `` tags within ordinary prose — + a convention the system prompt now carries too, so it survives `format` being dropped — and + opencode's own extractor frequently fails to lift it back out. The adapter parses the tag + itself and strips it from the streamed transcript on the way past — including when the + opening tag arrives split across two deltas. The wire types are declared in `providers/opencode-wire.ts` rather than imported from the SDK: the SDK's generated `Event` union omits `message.part.delta` entirely (237 of 313 events in a @@ -389,6 +393,23 @@ Conscious engineering choices, not oversights: - **Session persistence uses the SDK's own `persistSession`** plus Airship's `~/.airship/history` bundles (which record each `sessionId`), so resume survives a daemon restart — without a custom `SessionStore`. A `SessionStore` adapter (S3/Redis) is the path for multi-host hosted mode. +- **The minimap draws rectangles, not thumbnails.** Every frame is a live same-origin + `iframe` running a full instance of the user's app. There is no paint capture anywhere in + the overlay and no cheap way to add one — `FrameAgent` exposes DOM, not pixels — an + `iframe` cannot be duplicated, and cloning one would boot a ninth app against a cap of + eight. So `canvas/minimap.ts` positions plain `div`s, the way `chrome-layer.ts` draws + every other piece of canvas chrome. +- **Frame reorder publishes `z-index`; it never moves DOM nodes.** Moving an `iframe` in the + document tears down and rebuilds its browsing context, so the obvious implementation of + drag-to-restack would reload the app inside whichever frame you dragged, losing its route + and scroll position. `FrameManager.reorder` splices the array and `applyOrder` writes the + index as `z-index` instead; `frames.test.ts` asserts that no element moves. +- **A `feedback: "none"` draggable must be registered `POINTER_ONLY`.** dnd-kit's + `KeyboardSensor` needs `dragOperation.shape`, which only the Feedback plugin publishes — + so a "none" draggable starts a keyboard drag that no arrow key can move, and swallows the + Tab out of it. Nine of the overlay's draggables have no keyboard route for this reason; + where one is wanted it is a real command beside the drag, not a keyboard drag (see + `FramesPanel.moveBy`, and `num-field.ts`'s `stepBy` beside its scrub). - **Deferred for now:** multi-element select, `startup()` pre-warm (a latency optimization that requires threading a warm handle through each edit), and the Vite/Next plugin wrappers plus hosted mode. diff --git a/README.md b/README.md index 1e1f50c..f75866e 100644 --- a/README.md +++ b/README.md @@ -114,6 +114,30 @@ On the canvas: | ⌘/ctrl-wheel, pinch | zoom at cursor | | space-drag, middle-drag | pan | | ⇧1 / ⇧2 / ⇧0 | fit / zoom to selection / 100% | +| `H` | hand tool (view mode) | +| `F` | add a frame | + +## Edit and View + +The two modes point the editor at different things, and the panels follow. + +**Edit** is about an element: hover to highlight, click to select, and the agent panel and +inspector are open on either side of it. + +**View** is about your frames. The page underneath is fully interactive — click through it, +fill in forms, scroll — so there is no element selection, and the two panels that depend on +one step aside. In their place the left panel lists every frame, and a minimap appears in +the bottom-right corner: + +- Click a frame in the list to go to it without changing your zoom; double-click to zoom + to it. Rename it in place, and use `⋯` for its device size, rotate, duplicate and delete. +- The list is stacking order, front-most at the top. Drag a row anywhere along it — or + press ↑↓ on its handle — to restack frames that overlap on the canvas; up is forward. +- Drag the minimap's indicator and the canvas travels with it; press anywhere else on the + map to jump there. Pan far off your frames and it keeps pointing back at them. + +Your panel arrangement is remembered per mode, so switching back returns the inspector +exactly as you left it. ## Inspector @@ -149,6 +173,12 @@ Undo is Airship's, not the agent's. It keeps the previous version of every file undo works on all three. One catch: `codex` and `opencode` get that previous version from Git, so **undo needs your project to be a Git repo on those two**. Airship warns you at startup. +One more `opencode` quirk: the one-line summary and the follow-up suggestion chips come from a +JSON block the model is asked to append to its reply. A model that ignores the instruction +loses the chips and gets a plainer commit message — never the edit itself. Models with thinking +enabled reject opencode's own structured-output request outright; Airship detects that, retries +the turn without it, and remembers not to ask that model again. + ### Authentication Airship reuses whatever the chosen agent already has, and warns at startup if it finds nothing. @@ -374,6 +404,28 @@ first one that answers: With `--exec` it's the opposite: the port has to be *free*, since Airship is about to start your dev server on it. It won't start one on a port that's already taken. +## Troubleshooting + +**Every `opencode` turn fails with "Thinking mode does not support this tool_choice".** +The provider is rejecting the structured-output request opencode sends — it is implemented as a +forced tool call, which models with thinking/reasoning enabled refuse (opencode issue #15226, +closed upstream). Airship retries the turn without that request and remembers the model, so you +should see one warning row and a working edit. If it persists, pick a model without thinking +enabled, or disable thinking for your provider via `--opencode-config`. + +**"No `opencode` binary found on PATH."** +The `opencode` CLI is a separate install (`brew install sst/tap/opencode`); Airship finds it on +PATH rather than bundling it. + +**"No provider credentials found."** +Airship reuses the chosen agent's own login — see [Authentication](#authentication). For +`opencode` that means a provider key or `opencode auth login`; for `codex`, a `codex login` or +an API key; for `claude`, a `claude` login or `ANTHROPIC_API_KEY`. + +**Undo does nothing, or diffs come back empty, on `codex` or `opencode`.** +Both reconstruct their diff baseline from Git, so the project must be a Git repository. Airship +warns about this at startup. + ## Questions Including the ones with unflattering answers. diff --git a/apps/cli/README.md b/apps/cli/README.md index 8aaf37e..9146a0f 100644 --- a/apps/cli/README.md +++ b/apps/cli/README.md @@ -151,6 +151,12 @@ Undo is Airship's, not the agent's. It keeps the previous version of every file undo works on all three. One catch: `codex` and `opencode` get that previous version from Git, so **undo needs your project to be a Git repo on those two**. Airship warns you at startup. +One more `opencode` quirk: the one-line summary and the follow-up suggestion chips come from a +JSON block the model is asked to append to its reply. A model that ignores the instruction +loses the chips and gets a plainer commit message — never the edit itself. Models with thinking +enabled reject opencode's own structured-output request outright; Airship detects that, retries +the turn without it, and remembers not to ask that model again. + ### Authentication Airship reuses whatever the chosen agent already has, and warns at startup if it finds nothing. @@ -376,6 +382,28 @@ first one that answers: With `--exec` it's the opposite: the port has to be *free*, since Airship is about to start your dev server on it. It won't start one on a port that's already taken. +## Troubleshooting + +**Every `opencode` turn fails with "Thinking mode does not support this tool_choice".** +The provider is rejecting the structured-output request opencode sends — it is implemented as a +forced tool call, which models with thinking/reasoning enabled refuse (opencode issue #15226, +closed upstream). Airship retries the turn without that request and remembers the model, so you +should see one warning row and a working edit. If it persists, pick a model without thinking +enabled, or disable thinking for your provider via `--opencode-config`. + +**"No `opencode` binary found on PATH."** +The `opencode` CLI is a separate install (`brew install sst/tap/opencode`); Airship finds it on +PATH rather than bundling it. + +**"No provider credentials found."** +Airship reuses the chosen agent's own login — see [Authentication](#authentication). For +`opencode` that means a provider key or `opencode auth login`; for `codex`, a `codex login` or +an API key; for `claude`, a `claude` login or `ANTHROPIC_API_KEY`. + +**Undo does nothing, or diffs come back empty, on `codex` or `opencode`.** +Both reconstruct their diff baseline from Git, so the project must be a Git repository. Airship +warns about this at startup. + ## Questions Including the ones with unflattering answers.