paseo-prompt-kit 0.5.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hungcuong9125
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,249 @@
+# PromptKit
+
+PromptKit is a Paseo plugin (id `prompt-kit`) that rewrites the prompt in your Composer. It adds one `PromptKit` pill to the Composer's track bar and a `/rewrite <prompt>` slash command; the default action is `General`. Running it rewrites the current Composer text in place, in your own voice (first person, speaking to the agent), keeps your language and every protected literal (URLs, absolute paths, shell commands, code blocks, model names, tool names), restores focus, and never sends the prompt. You review the result and send it yourself.
+
+Rewriting has three paths, chosen in Settings. The default runs the selected model through the provider's own CLI, headlessly, in a temporary directory — no Paseo agent, no tab, no archive. Your primary conversation never receives a rewrite turn and never changes provider or session. The third path posts straight to an API you configure (OpenAI, Anthropic, Google Gemini, Cloudflare Workers AI, or anything speaking one of those protocols) when a CLI cold start is too slow or no CLI exists.
+
+See [CHANGELOG.md](CHANGELOG.md) for release notes.
+
+## Three ways to run it
+
+- **The pill** — write your prompt, press `PromptKit`. The text is rewritten in place; a leading `/rewrite ` left in the text is ignored. Available once the agent exists, so on a new seat it appears after the first message.
+- **`/rewrite <prompt>`** — type the command with the prompt after it and press Enter. Paseo empties the Composer and hands the text to PromptKit, which puts the `/rewrite …` line straight back, dims it with a light sweep while it works, and then replaces it with the rewrite. A failed rewrite leaves your line in place. Available immediately, including on a new seat before its first message. Because no agent exists yet on a draft, `/rewrite` cannot use `Current agent model`; choose `Dedicated model` or `Direct API` with a selected endpoint and model in Settings, or use the pill once the agent exists.
+- **The PromptKit sheet** (mobile) — write in the Composer as usual and press the pill. A sheet slides up already holding your text and rewrites it at once. Press **Rewrite** again until it reads right, then **Send**: the message goes to the agent, the Composer is cleared, the sheet closes. **✕** closes the sheet and leaves the Composer untouched.
+
+No path sends the message on its own. You review the result and send it yourself.
+
+## Requirements
+
+- Paseo Desktop or Web, version `>=0.9.0` (`paseo-plugin.json`). The plugin is built and tested against the 0.9.0 SDK.
+- For the CLI transports: a provider/model reachable by the daemon, and that provider's CLI on the daemon's `PATH`.
+- For the API transport: an endpoint URL, a model id, and a key — see [API keys](#api-keys).
+
+## Install from a local directory
+
+```bash
+cd /path/to/paseo-prompt-kit
+npm install
+npm run typecheck
+paseo plugin install /path/to/paseo-prompt-kit
+paseo plugin ls
+```
+
+`paseo plugin install` trusts the plugin: server code runs unsandboxed on the daemon host and client code runs inside Paseo. Reload after a code change:
+
+```bash
+paseo plugin reload prompt-kit
+paseo plugin logs prompt-kit
+```
+
+## Install from Git
+
+After the repository is published, install the managed Git checkout:
+
+```bash
+paseo plugin install hungcuong9125/paseo-prompt-kit --ref main
+paseo plugin ls
+```
+
+`--ref` chooses the initial branch, tag, or commit once; later `paseo plugin update prompt-kit` follows the remote's default HEAD. Pin a release instead of tracking `main` by giving `--ref` a tag:
+
+```bash
+paseo plugin install hungcuong9125/paseo-prompt-kit --ref v0.5.2
+```
+
+`paseo plugin ls` reports the installed commit.
+
+## Settings
+
+Open it from Paseo Settings → Plugins → the `…` menu on `prompt-kit` → **Settings**. The bar at the top says whether a rewrite would run and over which path, names the reason when it would not, and holds **Save** / **Discard** once something has changed. Nothing is written until Save.
+
+![PromptKit settings with the default path: Provider CLI, current agent model, output in the prompt's language](docs/images/settings-provider-cli.png)
+
+The screen reads top to bottom in setup order:
+
+1. **Actions** — one switch per action, bundled or custom; up to 6 can be on. One enabled action makes the pill rewrite at once; two or more make it a menu (on mobile, one button per action in the sheet); none hides the pill. A lone action shows no switch. Saving updates every pill at once.
+   **Custom actions** — your own actions, written as action-pack JSON in a text box on the same screen: **Add** opens a sample (Blank template, Copy of General, Execution brief, Plan first, Review request, Make concise, or a copy of one of yours), you change the id, title and instructions, **Apply** checks the JSON, and **Save** stores it. They run through the same rewrite as the bundled ones.
+2. **Rewrite engine** — Transport, Model source (Provider CLI only) and Output language. Every other section appears only when these need it.
+3. **Dedicated model** (CLI + Dedicated) or **API endpoint** (Direct API).
+4. **Advanced** (collapsed) — timeout and the two per-provider overrides.
+
+### Transport
+
+- `Provider CLI` (default) — the provider's own CLI runs the rewrite headlessly. The model comes from **Model source**.
+- `Direct API` — PromptKit posts to an endpoint you configure. No CLI is started, and there is no Model source: the model is chosen in the **API endpoint** section.
+
+### Model source (Provider CLI only)
+
+- `Current agent model` — the model the Composer's model control is showing for the agent whose pill you pressed. PromptKit reads the same value Paseo does (the provider session's runtime model first, then the configured model), so what you see is what runs.
+- `Dedicated model` — a provider, model and thinking option you pick from the daemon's provider catalog, whatever the agent itself runs.
+
+### Output language
+
+`Same as the prompt` (default) keeps the language you wrote in. `English`, `Tiếng Việt`, or any language you add translates the prose while paths, commands, code and names stay exactly as written. A language is one JSON file under `shared/languages/`; see `docs/guides/output-languages.md`.
+
+### The three paths
+
+| Transport | Model source | What runs |
+|---|---|---|
+| `Provider CLI` | `Current agent model` | The agent's own provider CLI with the model the Composer shows |
+| `Provider CLI` | `Dedicated model` | The dedicated provider's CLI with the model you picked |
+| `Direct API` | — | An HTTP request to the endpoint and model chosen under **API endpoint** |
+
+On `Direct API`, an agent whose provider is mapped under **Advanced → Endpoint per provider** sends its own model to that endpoint instead — this is how you point a provider such as `opencode` at your own OpenAI-compatible endpoint. Every other agent uses the endpoint and model from the **API endpoint** section; with no endpoint selected, only mapped providers can rewrite.
+
+### API endpoint
+
+Choose an endpoint — presets and your saved custom endpoints are listed A–Z (Anthropic, Cloudflare Workers AI, Google Gemini, Local server, OpenAI, OpenRouter), with **Custom endpoint…** last — fill in the base URL, pick a **Key source** (see [API keys](#api-keys)), and press **Test**. A successful test fills the **Model** list from the endpoint; the rewrite refuses a model outside that list. When a list has more than 8 models, a **Filter models** row above Model narrows the dropdown by name or id; the saved model always stays in it. Save is blocked while the endpoint cannot work (for example an empty base URL), with the reason in the status bar.
+
+![PromptKit settings on Direct API with the Google Gemini endpoint: key source, connection test, model filter and model](docs/images/settings-direct-api.png)
+
+### Advanced
+
+- `Timeout (ms)`: how long a rewrite may run, default `90000`, allowed range `1000`–`600000`. The daemon caps one plugin call at 30 s, so the screen notes when a budget above that cannot be reached.
+- `CLI per provider` (Provider CLI): lists only the providers you have overridden, plus an Add row. A profile named after its CLI (`pi-peer`, `codex-lead`) resolves on its own and needs no entry; an unresolved provider is refused, never guessed.
+- `Endpoint per provider` (Direct API): lists only mapped providers, plus an Add row. Pressing the pill in an agent of a mapped provider sends that agent's own model to the endpoint over HTTP. A mapped provider ignores the Model chosen under API endpoint.
+
+Settings are host-scoped and persist across plugin reload.
+
+## API keys
+
+An API key is **never** stored in PromptKit's settings document. That document is read by the client — including the Paseo Web UI — so a key placed there would leave your machine. Instead each endpoint picks one **Key source** in the API endpoint section, and the daemon reads the value at request time from that source only. There is no fallback: a key missing from the chosen source fails closed with `missing_api_key`, the message names the variable and the place it looked, and the Composer text is untouched.
+
+| Key source | Rows shown | Where the value is read |
+|---|---|---|
+| `Environment variable` (default) | Key variable | The daemon's environment variable with that name. The plugin server inherits the daemon's environment, so this suits a daemon started from a shell. |
+| `secrets.json` | Key variable, Secrets directory, API key (optional); Cloudflare also Account ID | The entry with that name under `apiKeys` in `<Secrets directory>/secrets.json`. |
+| `No key` | — | Nothing. For a local server (vLLM, llama.cpp, LM Studio). |
+
+**Secrets directory** is shared by every endpoint that uses `secrets.json`. It must be an absolute path or start with `~/`. Empty means `<PASEO_HOME>/plugin-settings/prompt-kit`; `PASEO_HOME` defaults to `~/.paseo`, so on macOS the default file is `~/.paseo/plugin-settings/prompt-kit/secrets.json`.
+
+After a successful **Test**, the Connection row says which source the key came from.
+
+### Why the file exists at all
+
+Paseo Desktop reads your login shell's environment **once, when it starts**, and the daemon keeps that copy. A key exported in `~/.zshrc` after Paseo started does not reach it until you quit and reopen Paseo; a daemon started some other way (a service, a remote host) may never see it. `secrets.json` is read at request time, so it works however and whenever the daemon was started.
+
+### `secrets.json` format
+
+One file holds every key: one entry per key under `apiKeys`, named whatever you like. Each endpoint whose Key source is `secrets.json` points at one entry through its **Key variable**, so several endpoints — or two accounts of one vendor, e.g. `GEMINI_WORK` and `GEMINI_PERSONAL` — share the file. Values must be strings; any other value is ignored.
+
+```json
+{
+  "version": 1,
+  "apiKeys": {
+    "OPENAI_API_KEY": "sk-...",
+    "ANTHROPIC_API_KEY": "sk-ant-...",
+    "GEMINI_API_KEY": "AIza..."
+  }
+}
+```
+
+Start from the template in this repository and keep it owner-only:
+
+```bash
+mkdir -p ~/.paseo/plugin-settings/prompt-kit
+chmod 700 ~/.paseo/plugin-settings/prompt-kit
+cp docs/templates/secrets.template.json ~/.paseo/plugin-settings/prompt-kit/secrets.json
+chmod 600 ~/.paseo/plugin-settings/prompt-kit/secrets.json
+```
+
+Then replace each `replace_me`, delete the entries you do not use, and set the matching endpoints' Key source to `secrets.json`.
+
+### Storing a key from Settings (convenience, least preferred)
+
+> [!WARNING]
+> Typing a key into the **API key** field sends the secret from the Paseo app to the daemon once, over the same connection Paseo uses. When you use Paseo Web or a client on another machine, the key crosses that link. Anyone who can open your Paseo settings can also overwrite or remove stored keys. Use this only on a machine and connection you trust.
+
+Prefer, in this order:
+
+1. **An environment variable** of the daemon (Key source `Environment variable`) — nothing leaves the daemon's machine and no file holds the key.
+2. **Editing `secrets.json` yourself** on the daemon's machine, as above — the key never passes through the Paseo app.
+3. **The API key field** — only when neither of the above is practical.
+
+With Key source `secrets.json`, the API endpoint section shows an **API key** field (masked) and a **Store key** row. **Save** writes the value under the endpoint's Key variable in `secrets.json`: other entries and fields are kept, the directory is created `0700` and the file written `0600` through a temporary file and a rename, and a malformed file is refused rather than overwritten. The field is cleared after saving. The key is write-only: the screen only says whether a value is stored, and **Remove stored key** deletes that one entry. The value never enters the settings document, a log, or an RPC answer. Two clients saving at the same moment can overwrite each other's change.
+
+### What PromptKit guarantees about keys
+
+- The value is never written to the settings document, never returned by any RPC, and never written to a log or an error message. A failure names the **variable** (`The environment variable "GEMINI_API_KEY" is not set`), not the value.
+- The key is read at request time and used for that one request only. It is not cached to disk.
+- PromptKit writes `secrets.json` only when you press **Save** or **Remove** in the API key rows, and only the one entry named by the endpoint's Key variable. It never reads a value back to the app.
+- An endpoint whose Key source is `No key` sends no credential. That is valid for a local server (vLLM, llama.cpp, LM Studio), which is why it is allowed rather than treated as an error.
+
+### Endpoint configuration
+
+Endpoints are defined in the settings document under `apiEndpoints`, because that is the only configuration store a Paseo plugin can read. A provider profile in `~/.paseo/config.json` is **not** visible to PromptKit: the daemon does not pass provider environment variables to plugins.
+
+Each endpoint is one of four protocols. Adding a vendor that speaks one of them is a settings edit, not a code change:
+
+| Protocol | Request | Works with |
+|---|---|---|
+| `openai` | `POST <baseUrl>/chat/completions`, `Authorization: Bearer` | OpenAI, OpenRouter, LiteLLM, vLLM, llama.cpp, LM Studio, Together, Fireworks, Groq, most gateways |
+| `anthropic` | `POST <baseUrl>/v1/messages`, `x-api-key` | Anthropic, z.ai, Alibaba/Qwen, Anthropic-compatible gateways |
+| `gemini` | `POST <baseUrl>/v1beta/models/<model>:generateContent`, `x-goog-api-key` | Google AI Studio, Vertex |
+| `cloudflare` | `POST <baseUrl>/accounts/<account id>/ai/run/<model>`, `Authorization: Bearer` | Cloudflare Workers AI (`@cf/...` models) |
+
+**Cloudflare Workers AI.** Base URL `https://api.cloudflare.com/client/v4`. The endpoint has an extra **Account ID** row, above Key variable, holding the **name** of the variable with your account id — prefilled `CLAUDFLARE_ACCOUNT_ID`, change it if yours differs. The account id is read from the same **Key source** as the token, so with `secrets.json` both live in the file and work however Paseo was started. The key variable defaults to `CLOUDFLARE_AUTH_TOKEN`, an API token with Workers AI permission. Models are the full `@cf/...` ids, for example `@cf/meta/llama-3.1-8b-instruct-fp8`; **Test** lists the account's text-generation models. PromptKit sends `max_tokens: 2048` because the service default of 256 tokens would cut a rewrite short.
+
+Example — a Google Gemini endpoint with `gemini-2.5-flash-lite`, from the settings document:
+
+```json
+{
+  "transport": "api",
+  "apiEndpointId": "gemini",
+  "apiModel": "gemini-2.5-flash-lite",
+  "apiEndpoints": [
+    {
+      "id": "gemini",
+      "label": "Google Gemini",
+      "protocol": "gemini",
+      "baseUrl": "https://generativelanguage.googleapis.com",
+      "keySource": "env",
+      "apiKeyEnv": "GEMINI_API_KEY",
+      "models": ["gemini-2.5-flash-lite"]
+    }
+  ]
+}
+```
+
+Example — point one provider at an endpoint, so it never pays a CLI cold start:
+
+```json
+{
+  "transport": "api",
+  "apiEndpointByProvider": { "opencode": "openrouter" }
+}
+```
+
+An endpoint that lists `models` restricts the choice to that list, and a model outside it fails closed with `invalid_model` before any request. Leave `models` empty to accept any model id — correct for a local server whose list PromptKit cannot know.
+
+### API failure codes
+
+| Code | Meaning |
+|---|---|
+| `missing_api_key` | The endpoint's Key source has no value for its key variable, `secrets.json` is missing or malformed, or the secrets directory is not absolute |
+| `api_endpoint_unknown` | The selected or mapped endpoint id is not defined in `apiEndpoints` |
+| `api_http_error` | The endpoint answered a non-2xx status, or was unreachable |
+| `api_bad_response` | The answer was not JSON, or carried no text |
+| `timeout` | The request exceeded `Timeout (ms)` |
+
+Every one of these leaves the Composer text untouched.
+
+## Limitations
+
+- In-place rewriting works on Desktop and Web only: the mobile app renders the Composer as a native text input with no DOM, and Paseo 0.9.0 exposes no plugin API for Composer text. On mobile the `PromptKit` pill opens the **PromptKit sheet** instead (see above); it reads and clears the Composer through the app's React tree rather than the DOM, which a Paseo update can break in the same way. Nothing is copied or sent on its own. `/rewrite` is not available on mobile. On Web, a refusal names what was found (no Composer, none visible, or more than one visible).
+- Requires Paseo `>=0.9.0`. Because text access depends on the Composer DOM (or, on mobile, the React tree), a Paseo UI change can break it even when the public plugin SDK is compatible.
+- No auto-send. PromptKit only replaces the Composer text; you send the message.
+- PromptKit refuses to replace text you edited while a rewrite was running, and refuses when more than one Composer (or none) is visible.
+- One bundled action: `General` turns the draft into a clear instruction the agent can act on — the concrete action, each constraint made checkable, the working steps for that kind of task (find the cause first, follow the codebase's existing way, keep the change scoped), and when it is done. It never invents files, numbers, requirements or decisions the draft does not contain, and it writes as you, speaking to the agent — never about "the user". Add your own under Settings → Custom actions, or bundle one as a JSON file — see `docs/EXTENDING.md`.
+- The API transport does not stream: it makes one request and waits for the whole answer. A slow endpoint can exceed the daemon's 30-second plugin-call cap, in which case the host reports a timeout before PromptKit's own `Timeout (ms)` can fire.
+- No OAuth or token refresh: an endpoint uses a static key. A provider that needs an interactive login is better served by the CLI transport.
+
+## Project layout
+
+The host compiler accepts only `client/`, `server/` and `shared/` at the root, so the modules live inside them. `docs/CORE.md` names each module's one responsibility; `docs/guides/` walks through the two data-only extensions (a new action pack, a new output language); `docs/EXTENDING.md` covers those plus API protocols, CLI families and settings sections, with templates under `docs/templates/`.
+
+## License
+
+MIT — see `LICENSE`. PromptKit contains no copied upstream code. The Composer text access pattern follows [paseo-emoji](https://github.com/YoseptF/paseo-emoji) (MIT); the plugin runs on [Paseo](https://github.com/getpaseo/paseo) (Apache-2.0) through its public plugin SDK.
+</content>

package/client/actions/enabled.ts

@@ -0,0 +1,30 @@
+import type { ActionSummary } from "../../shared/rpc.js";
+import type { PromptKitSettings } from "../../shared/settings.js";
+
+/** The most actions the pill menu and the mobile sheet show at once. */
+export const MAX_ENABLED_ACTIONS = 6;
+
+/**
+ * The locked UX: `E` is the set of loaded actions the user has enabled.
+ *
+ * A single enabled action is a direct action button, two or more are a menu, and
+ * none hides the pill. Ordering follows the registry so the pill does not depend
+ * on settings-object key order.
+ */
+export function enabledActions(
+  actions: readonly ActionSummary[],
+  settings: PromptKitSettings,
+): readonly ActionSummary[] {
+  return actions.filter((action) => settings.actionEnabled[action.id] ?? action.enabledByDefault);
+}
+
+/** Why the enabled set cannot be saved, or null. */
+export function describeEnabledLimit(
+  actions: readonly ActionSummary[],
+  settings: PromptKitSettings,
+): string | null {
+  const count = enabledActions(actions, settings).length;
+  return count > MAX_ENABLED_ACTIONS
+    ? `${count} actions are enabled; turn some off to keep at most ${MAX_ENABLED_ACTIONS}.`
+    : null;
+}

package/client/commands/rewrite-command.ts

@@ -0,0 +1,54 @@
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+import type { ActionPack } from "../../shared/action-registry/schema.js";
+import type { ActionSummary } from "../../shared/rpc.js";
+import { enabledActions } from "../actions/enabled.js";
+import { createWebComposerAdapter } from "../composer-bridge/web.js";
+import { createRewriteRunner } from "../pills/rewrite-runner.js";
+import { createSettingsReader, type SettingsRead } from "../settings/read-settings.js";
+
+export const REWRITE_COMMAND = "rewrite";
+
+export interface RewriteCommandDependencies {
+  listActions: (customActions: readonly ActionPack[]) => Promise<readonly ActionSummary[]>;
+  readSettings: () => Promise<SettingsRead>;
+}
+
+/**
+ * `/rewrite <prompt>` (Desktop/Web). Workspace scope so a draft seat (no agent
+ * yet) has it; hence agentId is null and "current agent model" refuses. Native
+ * mobile has no Composer DOM: the pill opens a sheet there instead.
+ */
+export function registerRewriteCommand(
+  client: PluginClientContext,
+  dependencies: RewriteCommandDependencies,
+): () => void {
+  return client.addSlashCommand({
+    name: REWRITE_COMMAND,
+    description: "Rewrite the prompt with PromptKit and put the result back in the Composer",
+    argumentHint: "<prompt>",
+    context: "workspace",
+    async onSubmit(context) {
+      const adapter = createWebComposerAdapter();
+      if (!adapter.isSupported()) {
+        throw new Error("On mobile, press the PromptKit pill instead.");
+      }
+      const settings = await dependencies.readSettings();
+      if (settings.status !== "ready") throw new Error(settings.error);
+      const actions = await dependencies.listActions(settings.values.customActions);
+      // Default flow = first enabled action.
+      const action = enabledActions(actions, settings.values)[0];
+      if (action === undefined) {
+        throw new Error("No PromptKit action is enabled. Enable one in PromptKit settings.");
+      }
+      const runner = createRewriteRunner({
+        adapter,
+        rpc: context.rpc,
+        readSettings: createSettingsReader(context.rpc),
+        agentId: null,
+        workspaceId: context.workspace.id,
+        isActive: () => true,
+      });
+      await runner.runText(action.id, context.args);
+    },
+  });
+}

package/client/composer-bridge/adapter.ts

@@ -0,0 +1,15 @@
+/**
+ * Platform-neutral Composer surface. The rest of the plugin never sees a DOM
+ * selector; only `client/composer-bridge/web.ts` implements this.
+ */
+export interface ComposerAdapter {
+  /** False where no DOM exists (native mobile). */
+  isSupported(): boolean;
+  readText(): string | null;
+  replaceText(next: string): boolean;
+  focus(): void;
+  /** Why `readText` returned null, for the user-facing message. */
+  describeFailure(): string;
+  /** Visual "rewriting" state on the Composer; returns the function that ends it. */
+  beginRewriteEffect(): () => void;
+}

package/client/composer-bridge/dom.ts

@@ -0,0 +1,101 @@
+// Paseo has no public plugin API for Composer text, so Desktop/Web attach to the
+// DOM. Selectors come from the app source, never from positional structure.
+// `[data-testid="message-input-root"]` - packages/app/src/composer/input/input.tsx:1787
+// `textarea[data-composer-input]`    - dataSet={COMPOSER_INPUT_DATASET} at input.tsx:670
+//                                      from input.tsx:87, and consumed by
+//                                      packages/app/src/styles/install-web-scrollbar-styles.web.ts:22
+export const COMPOSER_ROOT_SELECTOR = '[data-testid="message-input-root"]';
+export const COMPOSER_INPUT_SELECTOR = "textarea[data-composer-input]";
+
+/**
+ * An inactive pane stays mounted inside `RetainedPanel` and is hidden at an
+ * **ancestor** with `display: none`
+ * (packages/app/src/components/retained-panel.tsx:66-67). That removes the whole
+ * subtree from rendering, but the descendant's own computed `display` is still
+ * `flex`, so reading the element alone reports every retained Composer as
+ * visible. `display` is not inherited, so the ancestor chain must be walked.
+ *
+ * `visibility` is checked along the same chain: the host hides retained panes
+ * with `display`, and a stricter walk can only refuse more, never rewrite a
+ * Composer it cannot prove the user sees.
+ */
+export function isElementVisible(element: Element): boolean {
+  if (!element.isConnected) return false;
+  const view = element.ownerDocument.defaultView;
+  if (!view) return true;
+  for (let node: Element | null = element; node !== null; node = node.parentElement) {
+    const style = view.getComputedStyle(node);
+    if (style.display === "none") return false;
+    if (style.visibility === "hidden" || style.visibility === "collapse") return false;
+  }
+  return true;
+}
+
+/**
+ * Resolves the one Composer the user can see. Exactly one visible root carrying
+ * exactly one visible field must be provable; any other topology returns null so
+ * the caller refuses instead of rewriting a Composer it cannot identify.
+ */
+export interface ComposerTopology {
+  roots: number;
+  visibleRoots: number;
+  fields: number;
+  visibleFields: number;
+}
+
+/** Counts the Composer roots and fields, for diagnostics. */
+export function inspectComposers(root: ParentNode = document): ComposerTopology {
+  const roots = Array.from(root.querySelectorAll(COMPOSER_ROOT_SELECTOR));
+  const visibleRoots = roots.filter(isElementVisible);
+  const fields = visibleRoots.flatMap((entry) =>
+    Array.from(entry.querySelectorAll<HTMLTextAreaElement>(COMPOSER_INPUT_SELECTOR)),
+  );
+  return {
+    roots: roots.length,
+    visibleRoots: visibleRoots.length,
+    fields: fields.length,
+    visibleFields: fields.filter(isElementVisible).length,
+  };
+}
+
+export function describeComposerTopology(topology: ComposerTopology): string {
+  if (topology.roots === 0) return "PromptKit found no Composer on this screen.";
+  if (topology.visibleRoots === 0) {
+    return `PromptKit found ${topology.roots} Composer(s) but none is visible.`;
+  }
+  if (topology.visibleRoots > 1) {
+    return `PromptKit found ${topology.visibleRoots} visible Composers and cannot tell which one to rewrite.`;
+  }
+  if (topology.visibleFields === 0) return "PromptKit found the Composer but not its text field.";
+  return `PromptKit found ${topology.visibleFields} text fields in the Composer.`;
+}
+
+export function locateComposerField(root: ParentNode = document): HTMLTextAreaElement | null {
+  const roots = Array.from(root.querySelectorAll(COMPOSER_ROOT_SELECTOR)).filter(isElementVisible);
+  if (roots.length !== 1) return null;
+  const onlyRoot = roots[0];
+  if (!onlyRoot) return null;
+  const fields = Array.from(
+    onlyRoot.querySelectorAll<HTMLTextAreaElement>(COMPOSER_INPUT_SELECTOR),
+  ).filter(isElementVisible);
+  if (fields.length !== 1) return null;
+  return fields[0] ?? null;
+}
+
+/**
+ * React tracks the value it last saw, so a plain assignment is invisible to
+ * `onChange`. The native setter updates the DOM without tripping React's own
+ * value tracking, and the bubbling `input` event is what React listens to.
+ */
+export function setNativeValue(field: HTMLTextAreaElement, value: string): void {
+  let prototype: object | null = Object.getPrototypeOf(field) as object | null;
+  while (prototype) {
+    const setter = Object.getOwnPropertyDescriptor(prototype, "value")?.set;
+    if (setter) {
+      setter.call(field, value);
+      return;
+    }
+    prototype = Object.getPrototypeOf(prototype) as object | null;
+  }
+  field.value = value;
+}

package/client/composer-bridge/effect.ts

@@ -0,0 +1,64 @@
+import { COMPOSER_ROOT_SELECTOR } from "./dom.js";
+
+const STYLE_ID = "prompt-kit-effect";
+const DIM_OPACITY = "0.45";
+const FADE_MS = 220;
+
+function ensureStyles(doc: Document): void {
+  if (doc.getElementById(STYLE_ID)) return;
+  const style = doc.createElement("style");
+  style.id = STYLE_ID;
+  style.textContent = `
+@keyframes prompt-kit-sweep { from { transform: translateX(-140%) skewX(-20deg); } to { transform: translateX(340%) skewX(-20deg); } }
+.prompt-kit-overlay { position: absolute; inset: 0; pointer-events: none; overflow: hidden; border-radius: inherit; }
+.prompt-kit-beam { position: absolute; top: -10%; bottom: -10%; left: 0; width: 40%;
+  background: linear-gradient(90deg, transparent, var(--prompt-kit-beam, rgba(255,255,255,0.18)), transparent);
+  animation: prompt-kit-sweep 1.1s linear infinite; }
+@media (prefers-reduced-motion: reduce) { .prompt-kit-beam { animation: none; display: none; } }
+`;
+  doc.head.appendChild(style);
+}
+
+/** Beam color from the background behind the field: light on dark surfaces, dark on light ones. */
+function beamColor(element: HTMLElement | null): string {
+  const view = element?.ownerDocument.defaultView;
+  for (let node = element; node && view; node = node.parentElement) {
+    const match = /rgba?\((\d+),\s*(\d+),\s*(\d+)(?:,\s*([\d.]+))?\)/.exec(view.getComputedStyle(node).backgroundColor);
+    if (!match || (match[4] !== undefined && Number(match[4]) === 0)) continue;
+    const luminance = (0.2126 * Number(match[1]) + 0.7152 * Number(match[2]) + 0.0722 * Number(match[3])) / 255;
+    return luminance > 0.5 ? "rgba(0,0,0,0.12)" : "rgba(255,255,255,0.18)";
+  }
+  return "rgba(128,128,128,0.18)";
+}
+
+/** Dims the field and sweeps a slanted light across its Composer until `stop` is called. */
+export function startRewriteEffect(field: HTMLTextAreaElement): () => void {
+  const doc = field.ownerDocument;
+  ensureStyles(doc);
+  const root = field.closest<HTMLElement>(COMPOSER_ROOT_SELECTOR) ?? field.parentElement;
+  const previousTransition = field.style.transition;
+  const previousOpacity = field.style.opacity;
+  field.style.transition = `opacity ${FADE_MS}ms ease`;
+  field.style.opacity = DIM_OPACITY;
+
+  const overlay = doc.createElement("div");
+  overlay.className = "prompt-kit-overlay";
+  overlay.setAttribute("data-prompt-kit-effect", "");
+  overlay.style.setProperty("--prompt-kit-beam", beamColor(root));
+  const beam = doc.createElement("div");
+  beam.className = "prompt-kit-beam";
+  overlay.appendChild(beam);
+  root?.appendChild(overlay);
+
+  let stopped = false;
+  return () => {
+    if (stopped) return;
+    stopped = true;
+    overlay.remove();
+    field.style.opacity = previousOpacity || "1";
+    setTimeout(() => {
+      field.style.transition = previousTransition;
+      if (previousOpacity === "") field.style.removeProperty("opacity");
+    }, FADE_MS + 40);
+  };
+}

package/client/composer-bridge/fiber.ts

@@ -0,0 +1,97 @@
+/**
+ * The host's `MessageInputRef`: its `replaceText` also updates the Composer's
+ * own state (live-text presence, draft), which the inner text field's handle
+ * does not. `getInputSnapshot` is the marker that tells the two apart.
+ */
+export interface ComposerTextHandle {
+  getText(): string;
+  replaceText(text: string): void;
+  focus(): void;
+  getInputSnapshot(): unknown;
+}
+
+interface FiberLike {
+  return: FiberLike | null;
+  child: FiberLike | null;
+  sibling: FiberLike | null;
+  memoizedProps: Record<string, unknown> | null;
+  ref?: unknown;
+}
+
+const MAX_VISITED = 50_000;
+
+/** Fabric public instances carry their fiber; anything else yields null. */
+export function fiberOf(instance: unknown): FiberLike | null {
+  if (instance === null || typeof instance !== "object") return null;
+  const fiber = (instance as { __internalInstanceHandle?: unknown }).__internalInstanceHandle;
+  return fiber !== null && typeof fiber === "object" && "return" in fiber ? (fiber as FiberLike) : null;
+}
+
+function isMessageInputHandle(current: unknown): current is ComposerTextHandle {
+  if (current === null || typeof current !== "object") return false;
+  const handle = current as Partial<ComposerTextHandle>;
+  return (
+    typeof handle.getText === "function" &&
+    typeof handle.replaceText === "function" &&
+    typeof handle.focus === "function" &&
+    typeof handle.getInputSnapshot === "function"
+  );
+}
+
+function handleOf(fiber: FiberLike): ComposerTextHandle | null {
+  for (const ref of [fiber.ref, fiber.memoizedProps?.ref]) {
+    const current = (ref as { current?: unknown } | null | undefined)?.current;
+    if (isMessageInputHandle(current)) return current;
+  }
+  return null;
+}
+
+function belongsToAgent(fiber: FiberLike, agentId: string): boolean {
+  for (let node: FiberLike | null = fiber; node !== null; node = node.return) {
+    if (node.memoizedProps?.agentId === agentId) return true;
+  }
+  return false;
+}
+
+export type ComposerLookup =
+  | { ok: true; handle: ComposerTextHandle }
+  | { ok: false; reason: "no_fiber" | "not_found" | "ambiguous" };
+
+/**
+ * Finds the Composer of `agentId` from any fiber in the same React tree: up to
+ * the root, then down for the element whose ref is a `MessageInputRef`, under
+ * an ancestor whose props name the agent.
+ */
+export function findComposerHandle(start: FiberLike | null, agentId: string): ComposerLookup {
+  if (start === null) return { ok: false, reason: "no_fiber" };
+  let root: FiberLike = start;
+  while (root.return !== null) root = root.return;
+
+  const handles: ComposerTextHandle[] = [];
+  const stack: FiberLike[] = [root];
+  let visited = 0;
+  while (stack.length > 0 && visited < MAX_VISITED) {
+    const fiber = stack.pop()!;
+    visited += 1;
+    const handle = handleOf(fiber);
+    if (handle !== null && !handles.includes(handle) && belongsToAgent(fiber, agentId)) {
+      handles.push(handle);
+    }
+    if (fiber.sibling) stack.push(fiber.sibling);
+    if (fiber.child) stack.push(fiber.child);
+  }
+  if (handles.length === 1) return { ok: true, handle: handles[0]! };
+  if (handles.length > 1) return { ok: false, reason: "ambiguous" };
+  return { ok: false, reason: "not_found" };
+}
+
+export function describeLookupFailure(reason: Exclude<ComposerLookup, { ok: true }>["reason"]): string {
+  switch (reason) {
+    case "no_fiber":
+      return "PromptKit could not reach the app's component tree on this host.";
+    case "not_found":
+      return "PromptKit could not find this agent's Composer.";
+    case "ambiguous":
+      return "PromptKit found more than one Composer for this agent.";
+  }
+}