@corbet-labs/ccht 0.2.0 → 0.2.3

package/LICENSE.md

@@ -2,15 +2,20 @@
 
 Copyright 2026 Julian Y. Richard Corbet.
 
-The current ccht library is licensed under **LGPL-3.0-only**. The complete
+The current ccht library is licensed under **LGPL-3.0-only WITH
+LGPL-3.0-linking-exception**. The complete
 [LGPL version 3](LICENSES/LGPL-3.0-only.txt) incorporates
-[GPL version 3](LICENSES/GPL-3.0-only.txt).
+[GPL version 3](LICENSES/GPL-3.0-only.txt); the
+[linking exception](<LICENSES/LGPL-3.0-only WITH LGPL-3.0-linking-exception.txt>) waives the
+Minimal Corresponding Source, Minimal Application Code and
+installation-information duties (LGPLv3 §§4d/4e) for combined works that
+link statically or dynamically.
 
 Applications may use the library under different licenses subject to the LGPL's
-conditions. Distribution must preserve the library's notices and rights to modify
-and replace or relink it, including reverse engineering to debug such changes.
-The application license must not restrict those library rights. See section 4
-of the LGPL for the complete conditions for combined works.
+conditions. Distribution must preserve the library's notices and the openness
+of library modifications, including reverse engineering to debug such changes.
+The application license must not restrict those library rights. No relinking
+route or object files are required for combined works under the exception.
 
 Dependencies and external agent executables retain their own licenses and service
 terms. The library's license does not grant rights to an external runtime or

package/LICENSES/LGPL-3.0-linking-exception.txt

@@ -0,0 +1,16 @@
+As a special exception to the GNU Lesser General Public License version 3
+("LGPL3"), the copyright holders of this Library give you permission to
+convey to a third party a Combined Work that links statically or dynamically
+to this Library without providing any Minimal Corresponding Source or
+Minimal Application Code as set out in 4d or providing the installation
+information set out in section 4e, provided that you comply with the other
+provisions of LGPL3 and provided that you meet, for the Application the
+terms and conditions of the license(s) which apply to the Application.
+
+Except as stated in this special exception, the provisions of LGPL3 will
+continue to comply in full to this Library. If you modify this Library, you
+may apply this exception to your version of this Library, but you are not
+obliged to do so. If you do not wish to do so, delete this exception
+statement from your version. This exception does not (and cannot) modify any
+license terms which apply to the Application, with which you must still
+comply.

package/LICENSES/LGPL-3.0-only WITH LGPL-3.0-linking-exception.txt

@@ -0,0 +1,16 @@
+As a special exception to the GNU Lesser General Public License version 3
+("LGPL3"), the copyright holders of this Library give you permission to
+convey to a third party a Combined Work that links statically or dynamically
+to this Library without providing any Minimal Corresponding Source or
+Minimal Application Code as set out in 4d or providing the installation
+information set out in section 4e, provided that you comply with the other
+provisions of LGPL3 and provided that you meet, for the Application the
+terms and conditions of the license(s) which apply to the Application.
+
+Except as stated in this special exception, the provisions of LGPL3 will
+continue to comply in full to this Library. If you modify this Library, you
+may apply this exception to your version of this Library, but you are not
+obliged to do so. If you do not wish to do so, delete this exception
+statement from your version. This exception does not (and cannot) modify any
+license terms which apply to the Application, with which you must still
+comply.

package/LICENSES/dependencies/bytes-1.12.1/LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) 2018 Carl Lerche
+
+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

@@ -1,234 +1,216 @@
-# ccht
+# @corbet-labs/ccht
 
-Reusable conversations for Rust applications, terminals and web frontends.
-**ccht** keeps the conversation model in Rust and compiles
-that same model to Wasm. Native hosts connect to installed agents using the
-[official ACP Rust SDK](https://github.com/agentclientprotocol/rust-sdk).
+Reusable conversations for your applications, powered by the shared Rust/Wasm model.
 
-```text
-Web UI ── @corbet-labs/ccht (Wasm) ── application transport/storage
-                                              │
-TUI / native UI ── ccht::Conversation ── ccht::native ── upstream ACP agent
-```
-
-The library owns structured conversation events, ordered replay, native sessions,
-streaming, cancellation and permission requests. Your application owns its UI,
-instructions, context, tools, user authorization, storage and HTTP/WebSocket/SSE
-transport. No Corbet-specific prompts or database are required.
-
-Agent reasoning, tools, authentication and protocol translation remain upstream.
-ccht does not implement an agent loop, read provider credentials, install agents,
-call paid model HTTP APIs or select an API-key fallback.
-
-## Rust
-
-```toml
-[dependencies]
-ccht = "0.2"
-tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
-```
-
-`native` is the default feature. For the portable model alone:
-
-```toml
-ccht = { version = "0.2", default-features = false }
-```
-
-```rust
-use ccht::{Conversation, Event, WireEvent, acp};
-
-let mut conversation = Conversation::new("workspace/creator");
-conversation.apply(WireEvent::new(
-    "workspace/creator", "turn-1", 1,
-    Event::Update {
-        update: acp::SessionUpdate::AgentMessageChunk(
-            acp::ContentChunk::new("Hello".into()),
-        ),
-    },
-)).unwrap();
-assert_eq!(conversation.turns()[0].text, "Hello");
-```
-
-[examples/native.rs](source/examples/native.rs) shows streaming from an explicitly
-supplied installed ACP executable. It requires native agent authentication already
-configured by the operator. Use `codex-acp`, `claude-agent-acp`, or `opencode acp`
-as separate, reviewed runtime installations. Generic ACP executables also work.
-No agent/runtime is bundled in the crate or browser package.
-
-`NativeClient::connect` initializes the protocol. Create a session with its working
-directory, explicit model (if desired) and application MCP servers. Take the event
-receiver before prompting and consume it concurrently with the prompt future.
-A session accepts one active prompt; another returns `Busy`. Different sessions
-have separate streams and permission identities. History load/resume and model
-selection require the agent's advertised capabilities; unsupported requests fail.
-
-`session.handle().configuration()` exposes the agent's ordered model, reasoning,
-mode and boolean controls. Call `set_model(id)` or `set_config_option(id, value)`
-to change them. The full response replaces the advertised configuration, including
-dependent options; configuration notifications update both the native handle and
-the portable conversation snapshot. Unknown values fail without a fallback.
-`SessionOptions::configuration` applies explicit settings when creating or restoring
-a session. Retain the agent session ID and its working directory in your product
-storage to resume completed conversations across process restarts. Never replay an
-uncertain delivery automatically.
-
-Permissions default to denial. Applications that opt into asking must render the
-request, check their authority and respond with one of the advertised choices.
-A permission callback is not a sandbox: agent-owned tools may have separate runtime
-policy. Configure filesystem/network confinement in the host for your use case.
-ccht advertises no client filesystem or terminal capabilities.
-
-Cancellation asks the upstream agent to stop. If it does not stop within the
-configured shutdown timeout, ccht closes the SDK connection, affecting **all**
-sessions on that connection. Dropping an active prompt also closes its connection.
-Use one connection per independent workload when cancellation must be isolated.
-Bounded event channels fail explicitly on an unresponsive consumer.
-
-`AgentCommand::with_working_directory` sets the actual agent startup directory
-using installed Linux/macOS `env` launchers. Windows currently reports this helper
-as unsupported because the SDK launch configuration lacks a startup-directory
-field. Session cwd alone does not constrain files read during agent startup.
-Linux is covered by process-level tests; macOS support is source-reviewed.
-
-ACP enables `serde_json`'s `preserve_order` feature through Cargo feature
-unification. Applications that hash or sign JSON must explicitly canonicalize
-object keys; depending on a `Value` map's incidental iteration order is unsafe.
-
-## Browser
-
-```sh
-npm install @corbet-labs/ccht
-```
+The root entry (`createConversation`) owns the conversation state machine. The
+`./auth` entry adds typed auth/challenge models mirroring `ccht::auth`, the
+`./dock` entry adds framework-free dock state, and
+`./components/AccountConnection.svelte` adds the first shared Svelte 5 account
+connector alongside the generic `./components/Dock.svelte` edge rail. All
+entries are product-neutral: no product names, prompts, or
+pricing appear in this package.
 
 ```js
 import { createConversation } from '@corbet-labs/ccht';
-// Vite example: emit the Wasm as a separately replaceable asset.
-import wasmUrl from '@corbet-labs/ccht/ccht_bg.wasm?url';
-
-const conversation = await createConversation('workspace/creator', { wasm: wasmUrl });
-// After your authenticated application transport delivers a ccht WireEvent:
-const snapshot = conversation.applyEvent(event);
-render(snapshot.turns);
-// When the view is destroyed:
-conversation.free();
+import { isAuthenticated, validateChallenge } from '@corbet-labs/ccht/auth';
+import { createDockManager, validateDockId } from '@corbet-labs/ccht/dock';
+import AccountConnection from '@corbet-labs/ccht/components/AccountConnection.svelte';
+import Dock from '@corbet-labs/ccht/components/Dock.svelte';
 ```
 
-Version 0.2.0 requires an explicit `wasm` URL or bytes on first initialization.
-A browser cannot launch native processes: its
-application server or desktop host runs `ccht::native`. The package makes no
-network connection apart from loading its Wasm module. The host decides which
-backend is available and how users authenticate to the application.
+The Svelte component ships as source and needs `svelte` `^5` (a peer
+dependency). It has no other dependencies and imports no CSS framework.
 
-## JSR
+## What is shared vs what the app owns
 
-The JSR package exposes the same Rust/Wasm model:
+Shared (this package):
 
-```ts
-import { createConversation } from 'jsr:@corbet-labs/ccht@0.2.0';
+- Conversation state and ordered event replay (Wasm `ConversationModel`).
+- Auth/challenge types and validators (`AuthState`, `Challenge`,
+  `CredentialsProvider`).
+- Presentational account connector markup with stable styling hooks.
 
-const conversation = await createConversation('workspace/creator', {
-  wasm: new URL('https://jsr.io/@corbet-labs/ccht/0.2.0/wasm/ccht_bg.wasm'),
-});
-```
+Owned by the embedding application:
 
-In Deno, allow access with `--allow-net=jsr.io` for this Wasm download.
-Applications can also supply their own Wasm bytes or URL. JSR's corresponding
-source archive uses `dependencies.tar.xz` to fit its package size limit; the
-source files and runtime bytes are the same as the npm distribution.
+- Transport: delivering `WireEvent`s (HTTP/WebSocket/SSE), serving the Wasm
+  bytes, and polling login operations until they complete.
+- Effects: spawning agents, starting or cancelling logins, signing out. These
+  never run in browser library code; the component drives them through
+  app-supplied async callbacks and the app backend does the work.
+- Storage: where credentials persist (OS keychain natively, origin-scoped
+  browser storage on the web). The library defines the interface only.
+- Product copy: account labels, help text, links, and error wording beyond the
+  component's generic strings.
 
-## Python
+Rule: browser code in this package never spawns agents, performs network I/O,
+or holds ambient authority. Service keys are explicit strings passed by the
+app, and secrets are opaque bytes that are never logged.
 
-Install from [PyPI](https://pypi.org/project/ccht/0.2.0/):
+## Auth entry (`@corbet-labs/ccht/auth`)
 
-```sh
-python -m pip install ccht==0.2.0
-```
+Plain types and functions, no DOM access.
 
-```python
-from ccht import Conversation
+`AuthState` mirrors the Rust `snake_case` JSON byte-for-byte:
 
-conversation = Conversation('workspace/creator')
-# Deliver an authorized WireEvent from your application transport.
-conversation.apply_event(event)
-snapshot = conversation.snapshot()
-```
+| Rust | JSON | TypeScript |
+| --- | --- | --- |
+| `Unknown` | `"unknown"` | `'unknown'` |
+| `Unauthenticated` | `"unauthenticated"` | `'unauthenticated'` |
+| `Authenticated { account }` | `{"authenticated": {"account": "…"}}` | `{ authenticated: { account?: string \| null } }` |
 
-The Python package wraps the published Rust conversation model through PyO3.
-It exposes event reduction and snapshots; native agent execution uses a Rust
-host with `ccht::native`. See [py/README.md](py/README.md) for the Python API,
-binary wheel requirements and source rebuild/replacement instructions.
-
-## Event and persistence contract
-
-`WireEvent` version 1 contains `conversation_id`, `request_id`, a per-request
-`sequence` starting at 1, and `event`. Retain the original structured ACP updates:
-text, non-text content, tool calls, thought chunks, plans, permissions and errors
-are distinct. The model returns a serializable snapshot for your renderer.
-
-Assign identities and sequences on a trusted application host. Never let a browser
-select another user's conversation without server-side authorization. Sequence
-numbers are **not** SSE cursors or database row IDs. The app stores its own event
-log and replays each request in order. Already-applied sequences are ignored;
-gaps, a different conversation, malformed events and new events after completion
-fail without mutating state. Delivery identity must not be reused for another turn.
-
-A model holds at most 256 turns, 8 MiB per turn and 1 MiB per event. Applications
-should page long histories into separate models and limit streamed inputs before
-parsing them. Durable transcript storage and reconnection are application concerns;
-a serialized snapshot is a render result, not a native-agent session checkpoint.
-
-Namer is the first integration: Creator/Critic have independent conversation
-scopes, durable application events, authenticated SSE and cancellation. Its queue
-uses a fresh native session per turn with bounded role history supplied by Namer.
-CareerVector's TUI reuses the native session API while keeping CV tools, prompts
-and revision checks in its own code. Explicit local inference can emit the same
-`WireEvent` contract through an application-owned backend.
-
-## Building the Wasm package
-
-Use Rust with `wasm32-unknown-unknown` installed. The checked-in generator uses the
-same exact `wasm-bindgen` version as the Rust crate; no global Wasm CLI is required.
-
-```sh
-cargo build --locked --release --no-default-features --features web --target wasm32-unknown-unknown
-cargo run --locked --release -p ccht-wasm-bundle -- target/wasm32-unknown-unknown/release/ccht.wasm web/wasm
-```
+Helpers: `isAuthenticated(state)` mirrors `AuthState::authenticated`,
+`authAccount(state)` returns the display-only label (or null), and
+`parseAuthState(value)` / `isAuthState(value)` validate decoded JSON. The
+label is provenance for the UI, never an authentication proof.
+
+`Challenge` is `{ verification_url, user_code }`. The backend issues it, pins
+any provider-specific endpoint, and polls for completion; the browser only
+renders a validated challenge. `validateChallenge(value)` accepts an `https:`
+URL with a host (no embedded credentials) and a non-empty code of up to 64
+ASCII alphanumeric or `-` characters. It never throws, so callers can gate
+rendering on it. The component validates internally and renders waiting text
+for a missing or malformed challenge instead of an unvalidated link.
 
-Published npm browser archives include the corresponding Rust source and generator
-under `source/`, original notices, and the full locked dependency sources in
-`source/dependencies.tar.gz`. Cargo's vendor checksums are preserved inside that
-archive. To rebuild from the distributed package, extract it inside `source/`:
+`CredentialsProvider` mirrors the Rust trait with JS method names:
 
-```sh
-cd source
-tar -xzf dependencies.tar.gz
-cargo build --locked --offline --release --no-default-features --features web --target wasm32-unknown-unknown
-cargo run --locked --offline --release -p ccht-wasm-bundle -- target/wasm32-unknown-unknown/release/ccht.wasm ../wasm
+```ts
+interface CredentialsProvider {
+  readCredentials(service: string): Promise<Credential | null>;
+  writeCredentials(service: string, credential: Credential): Promise<void>;
+  deleteCredentials(service: string): Promise<void>;
+}
 ```
 
-The supplied `.cargo/config.toml` uses only those vendored sources. The installed
-Rust toolchain must include the Wasm target and linker. CI rebuilds this kit with
-an empty Cargo cache and tests the replacement module through the same npm API.
-Keep that exported interface compatible when replacing the library.
-
-CI verifies the portable Rust model, actual Wasm compilation and packaged Node
-consumer, native protocol/process fixtures, dependency notices and an independent
-Rust crate consumer. Native fixtures do not call a model or access an account.
-Live runtime support must additionally be checked against the installed agent,
-its advertised capabilities, login state and execution policy.
-
-## License
-
-ccht is **LGPL-3.0-only**. See [LICENSE.md](LICENSE.md) and
-[THIRD-PARTY.md](THIRD-PARTY.md). Applications may use different licenses while
-preserving the LGPL library rights. Distributing a combined Rust binary requires
-a compliant relinking route; making source available somewhere is not by itself
-sufficient. Keep the browser's Wasm replaceable and provide its corresponding
-source and notices. Review the complete license for your distribution method.
-
-ACP and an account's subscription do not guarantee a billing mode. The operator
-must configure the native agent/account and disable unwanted paid usage. Known
-ambient API-key variables are cleared at launch and explicit API-key overrides
-are rejected, but ccht cannot attest saved agent credentials or account billing
-settings. Native runtimes and hosted services retain their own terms; a library
-license does not authorize pooling subscriptions or product-specific login flows.
+`Credential` is `{ account: string; secret: Uint8Array }`. Encode at the app
+boundary (`TextEncoder`/base64) when the store needs text. Service keys are
+app-defined (for example `assistant-login:<provider>`); deleting a missing
+entry succeeds, and a rejected promise signals store failure. There is no
+environment-variable override on the web: the store alone decides, matching
+the documented `ApiKeyState` behavior on Wasm.
+
+## Component (`AccountConnection.svelte`)
+
+Svelte 5 runes. Props:
+
+| Prop | Type | Meaning |
+| --- | --- | --- |
+| `account` | `{ id: string; label: string; kind: 'chatgpt' \| 'opencode_go' \| string }` | Product-neutral identity. Known kinds select the ceremony; unknown kinds fall back to a generic sign-in button. |
+| `state` | `AuthState` | Observed login state (defaults to `'unknown'`). |
+| `busy` | `boolean` | An app-owned operation is in flight; actions disable, cancel shows. |
+| `challenge` | `Challenge \| null` (optional) | Device-code challenge supplied by the app after `onStart` starts polling. |
+| `onStart` | `() => void \| Promise<void>` | Begin the login ceremony (for example start a device flow). |
+| `onCancel` | `() => void \| Promise<void>` | Abort the in-flight operation; also backs Disconnect when `onDisconnect` is omitted. |
+| `onKeySubmit` | `(key: string) => void \| Promise<void>` | Persist a trimmed account key (minimum 8 characters). |
+| `onDisconnect` | optional | Sign out when authenticated. Falls back to `onCancel`, which can branch on app state. |
+
+Rendering:
+
+- Unauthenticated `chatgpt`: sign-in button, then waiting text while `busy`,
+  then the device-code view (code, copy button, sign-in link) once a valid
+  `challenge` arrives. The copy button opens the link during the click (so
+  popup blockers do not trigger) and falls back to a manual-copy message when
+  the clipboard API is unavailable.
+- Unauthenticated `opencode_go`: password key form that clears on submit.
+- Authenticated: connection status with the account label (when known) and a
+  Disconnect button.
+- `unknown` state: neutral checking text with no ceremony buttons.
+
+Callbacks are fire-and-forget from the component's view: the app must handle
+its own failures and surface them through its own operation state, which it
+renders outside the component. Callback rejections are therefore ignored here
+by design.
+
+Accessibility: semantic `section`/`form`/`label`/`button` elements, an
+`aria-label` naming the account connection, `role="status"` for status lines,
+an `aria-live="polite"` region announcing challenge arrival, and
+`role="alert"` for the clipboard fallback. The key input is labelled,
+password-masked, and non-persistent.
+
+## Dock entry (`@corbet-labs/ccht/dock`) and component (`Dock.svelte`)
+
+Framework-free dock state plus a generic Svelte 5 edge rail. `DockKind`
+(`'chat' | 'config' | 'custom'`) classifies a dock and `Placement`
+(`'left' | 'right' | 'bottom' | 'inline'`) places it. The state module is
+plain TypeScript with no DOM access.
+
+`validateDockId(id)` returns an error message or null (never throws). Rules:
+a non-empty string of at most 64 ASCII `[a-z0-9-_]` characters.
+
+`createDockManager()` returns an independent manager:
+
+| Method | Meaning |
+| --- | --- |
+| `register(id, kind, placement)` | Register a closed dock. Throws the validation message for a malformed id, `DuplicateDock: <id>` for a repeat. |
+| `open(id)` / `close(id)` | Mark a dock open or closed. Unknown ids throw `UnknownDock: <id>`. |
+| `openWithFocus(id, token)` | Open a dock and stage an opaque focus token (non-empty string) for the app to consume. |
+| `toggle(id)` | Flip a dock's open state and return the new state. |
+| `isOpen(id)` | Whether a dock is open. |
+| `placement(id)` / `setPlacement(id, placement)` | Read or move a dock's placement. Invalid placements throw `invalid dock placement`. |
+| `openDocks()` | Ids of open docks, in registration order. |
+| `takeFocusToken()` | Take the staged focus token once, clearing it; null when none is staged. |
+| `closeAll()` | Mark every dock closed. |
+| `serialize()` | Persist `[{id, kind, placement, open}]` as JSON, in registration order. The focus token is never persisted. |
+| `restore(json)` | Replace all state from `serialize` output. Every entry is validated first, so a malformed snapshot (thrown as `invalid dock snapshot: …`) leaves current state untouched, and any staged focus token is cleared. |
+
+`Dock.svelte` renders one named dock as an edge rail for the `left` and
+`right` placements. Svelte 5 runes. Props:
+
+| Prop | Type | Meaning |
+| --- | --- | --- |
+| `side` | `'left' \| 'right'` | Which window edge the rail pins to. |
+| `title` | `string` | Panel heading and dialog label. |
+| `open` | `boolean` | App-owned visibility state. |
+| `onClose` | `() => void` | Close intent (tab is hidden while open; Esc key also closes). |
+| `onOpen` | `() => void` | Open intent from the edge tab button. |
+| `tabLabel` | `string` | Short tab caption. |
+| `tabSummary` | `string` (optional, defaults to `''`) | Detail shown in the tab button and panel head. |
+| `closeLabel` | optional `string` | Close button label (defaults to `Close {title}`). |
+| `panelId` | `string` | Panel element id, referenced by the tab's `aria-controls`. |
+| `children` | `Snippet` | Panel body content. |
+
+Rendering:
+
+- Closed: a fixed edge tab button (`aria-expanded="false"`,
+  `aria-controls={panelId}`, labelled `Open {title}: {tabSummary}` or
+  `Open {title}`). The panel stays mounted but hidden and inert.
+- Open: a `role="dialog"` panel with a head (`h2` title, summary paragraph,
+  Close button) and a body rendering `children`.
+- Opening moves focus to the first visible, enabled control in the panel
+  (or the panel itself); closing returns focus to the tab or the previously
+  focused element. Esc closes.
+- The `bottom` and `inline` placements are state-only: they persist and
+  restore through the manager but have no rail chrome here. Custom hosts
+  (for example a ratatui overlay or an inline sheet) render them.
+
+Stable classes: `ccht-dock-tab`, `ccht-dock-tab-text`, `ccht-dock-panel`,
+`ccht-dock-head`, `ccht-dock-title`, `ccht-dock-close`, `ccht-dock-body`.
+The tab and panel carry `data-side` (`left` / `right`) and the panel carries
+`data-open` (`true` / `false`).
+
+CSS variables (with fallbacks when unset): `--ccht-fg`, `--ccht-muted`,
+`--ccht-accent`, `--ccht-border`, `--ccht-panel-bg`, `--ccht-tab-bg`,
+`--ccht-tab-bg-hover`, `--ccht-fg-bright`.
+
+Rule: the app owns dock effects. The manager never persists, the component
+never fetches, spawns, or stores; visibility, persistence, and focus targets
+beyond the panel run through app callbacks and app-held state.
+
+## Styling hooks
+
+Unstyled-but-hooked markup: layout comes from the app, colors resolve through
+CSS custom properties with plain fallbacks. Stable classes:
+
+`ccht-account`, `ccht-status`, `ccht-hint`, `ccht-error`, `ccht-challenge`,
+`ccht-code`, `ccht-button`, `ccht-cancel`, `ccht-disconnect`, `ccht-link`,
+`ccht-keyform`, `ccht-label`, `ccht-input`.
+
+CSS variables (with fallbacks when unset): `--ccht-fg`, `--ccht-muted`,
+`--ccht-error`, `--ccht-accent`, `--ccht-code-bg`. Example:
+
+```css
+:root {
+  --ccht-muted: #a5b5cb;
+  --ccht-error: #fda4af;
+  --ccht-accent: #7bb8ff;
+}
+```

package/THIRD-PARTY.md

@@ -21,8 +21,25 @@ comply with their runtime and service conditions when packaging them yourself.
 Do not infer permission to offer a customer-facing subscription login or pooled
 account service from the wrapper's permissive license.
 
+Permissive references informing the native login drivers (no vendored code;
+hand-rolled protocol shapes with attribution in the module docs):
+
+- Codex app-server protocol (`account/login/start` device-code challenge,
+  `account/login/completed`, `account/read`) from openai/codex under
+  Apache-2.0 informs `src/native/drivers/codex.rs` (`CodexDeviceDriver`).
+  The driver spawns the caller's Codex `app-server`, relays the
+  host-allowlisted challenge, and projects presence only.
+- OpenCode `serve` control plane (`GET /global/health`,
+  `PUT /auth/opencode-go`, `GET /provider`) under MIT informs
+  `src/native/drivers/opencode.rs` (`OpenCodeKeyDriver`). The driver uses
+  loopback `opencode serve` with an ephemeral port, an env-only server
+  password, and hand-rolled HTTP with no new dependencies.
+
+Preserve their original grants and notices when reusing these shapes.
+
 Upstream sources: [ACP SDK](https://github.com/agentclientprotocol/rust-sdk),
 [Codex ACP](https://github.com/agentclientprotocol/codex-acp),
+[openai/codex](https://github.com/openai/codex),
 [Claude ACP](https://github.com/agentclientprotocol/claude-agent-acp),
 [OpenCode](https://github.com/anomalyco/opencode),
 [wasm-bindgen](https://github.com/wasm-bindgen/wasm-bindgen).

package/index.d.ts

@@ -51,7 +51,12 @@ export interface Conversation {
   snapshot(): ConversationSnapshot;
   free(): void;
 }
-/** Transport/authentication and persistence belong to the embedding application. */
+/** Transport/authentication and persistence belong to the embedding application.
+ *
+ * Only the first call's `wasm` option initializes the shared module; later
+ * calls reuse it. `applyEvent` returns the fresh snapshot and throws on
+ * invalid, out-of-scope, gapped, terminal, or freed input. `free` is idempotent.
+ */
 export function createConversation(conversationId: string, options?: {
   wasm?: URL | string | Request | Response | BufferSource | WebAssembly.Module;
 }): Promise<Conversation>;

package/index.js

@@ -3,7 +3,14 @@ import initialize, { ConversationModel } from './wasm/ccht.js';
 
 let initialization;
 
-/** Initialize the shared Rust/Wasm model. Supply an explicit Wasm URL when bundling. */
+/** Initialize the shared Rust/Wasm model. Supply an explicit Wasm URL when bundling.
+ *
+ * Only the first call's `wasm` option initializes the shared module; later
+ * calls reuse it. The returned `applyEvent` applies one ordered event and
+ * returns the fresh snapshot (the underlying Rust boolean for "changed" is
+ * not exposed); it throws on invalid JSON, scope, gap, terminal, or freed
+ * state. `snapshot` returns the parsed render state and `free` is idempotent.
+ */
 export async function createConversation(conversationId, options = {}) {
   if (!initialization) {
     initialization = initialize(options.wasm === undefined ? undefined : { module_or_path: options.wasm })

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@corbet-labs/ccht",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "description": "Reusable conversations for your applications, powered by the shared Rust/Wasm model",
-  "license": "LGPL-3.0-only",
+  "license": "LGPL-3.0-only WITH LGPL-3.0-linking-exception",
   "type": "module",
   "main": "./index.js",
   "types": "./index.d.ts",
@@ -11,11 +11,22 @@
       "types": "./index.d.ts",
       "import": "./index.js"
     },
+    "./auth": {
+      "types": "./src/auth.ts",
+      "import": "./src/auth.ts"
+    },
+    "./dock": {
+      "types": "./src/dock.ts",
+      "import": "./src/dock.ts"
+    },
+    "./components/AccountConnection.svelte": "./src/components/AccountConnection.svelte",
+    "./components/Dock.svelte": "./src/components/Dock.svelte",
     "./ccht_bg.wasm": "./wasm/ccht_bg.wasm"
   },
   "files": [
     "index.js",
     "index.d.ts",
+    "src/",
     "wasm/",
     "source/",
     "LICENSE",
@@ -31,6 +42,9 @@
   "publishConfig": {
     "access": "public"
   },
+  "peerDependencies": {
+    "svelte": "^5"
+  },
   "sideEffects": false,
-  "gitHead": "387d2d172a285508efae68b24822a73b152b1633"
+  "gitHead": "baa0b02cd88ad171d8c9a507a1d08c19d51bcc55"
 }

package/source/.ci/wasm-bundle/Cargo.toml

@@ -4,7 +4,7 @@ version = "0.0.0"
 edition = "2024"
 rust-version = "1.88"
 publish = false
-license = "LGPL-3.0-only"
+license = "LGPL-3.0-only WITH LGPL-3.0-linking-exception"
 
 [dependencies]
 wasm-bindgen-cli-support = "=0.2.128"