@molecule/app-ide-react 1.13.0 → 1.15.0

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-09-13T10:48:48.475Z
+Generated: 2026-09-15T18:15:48.521Z
 -->
 
 # @molecule/app-ide-react
@@ -479,9 +479,33 @@ interface ChatPanelProps {
    * `null`/`undefined` (the default) to render the nudge text with no button.
    * `requiresSignup`, when set, is the backend's flag that the user must sign up
    * rather than upgrade an existing plan; when unset the host's own auth state decides.
+   *
+   * The rest of the context is the backend's own description of the limit that
+   * fired, forwarded verbatim so the host never has to guess the right button:
+   *
+   * - `limitType` — the RULE the backend enforced (e.g. `usage_balance`,
+   *   `spend_cap`, `ai_cost`, `max_tool_loops`).
+   * - `billingAction` — the REMEDY the backend resolved (e.g. `sign_up`,
+   *   `upgrade`, `add_payment_method`, `add_funds`, `raise_spend_cap`,
+   *   `enable_extra_usage`, `contact_support`, `owner_only`, `none`). Prefer this
+   *   over `limitType` when both are present: one limit can need different
+   *   buttons per account (an empty balance is "Add funds" with a card on file
+   *   and "Add a payment method" without one), and `none` means there is nothing
+   *   the user can do — render no button.
+   * - `upgradeTier` — the plan an upgrade would move to, explicitly `null` when
+   *   there is no higher tier, so a top-tier user is never sent to a plans page
+   *   with nothing to sell them.
+   *
+   * Both vocabularies belong to the host's API, so they are plain strings here —
+   * the shared IDE never interprets them. Every field is optional and may be
+   * absent (a backend that sends none of them keeps the old behavior), so the
+   * host must have a fallback.
    */
   buildUpgradeCta?: (context: {
     requiresSignup?: boolean
+    limitType?: string
+    billingAction?: string
+    upgradeTier?: string | null
   }) => ChatEventCardAction | ChatEventCardAction[] | null | undefined
   /**
    * Optional app-specific section appended to the `/help` output — e.g. a plan /
@@ -544,6 +568,45 @@ interface ChatPanelProps {
    * modal — which POSTs to the project's own backend — is unaffected.
    */
   feedbackUrl?: string
+  /**
+   * Lists the project's tests for the `/test` browser. Omit it (the default)
+   * and `/test` has nothing to show — the shared IDE owns no test-discovery
+   * route of its own.
+   *
+   * molecule.dev implements it over `GET /projects/:id/tests`. It is called
+   * on every `/test` invocation and once more when a run finishes, so a spec
+   * the agent just wrote shows up the next time the browser is opened.
+   */
+  listTests?: () => Promise<TestList>
+  /**
+   * Runs the selected tests, streaming {@link TestRunEvent}s back as they
+   * happen. Required alongside {@link ChatPanelProps.listTests} for the
+   * browser's run controls to work.
+   *
+   * The returned handle's `cancel()` must stop the run (molecule.dev aborts the
+   * SSE request, and the server kills the process tree on disconnect). The host
+   * is responsible for running the e2e specs through the preview bond chain —
+   * in a sandbox that means `npx playwright test` with
+   * `@molecule/app-e2e-preview` as the browser, so the spec drives the live
+   * preview rather than a browser binary that is not installed there.
+   *
+   * The run is owned by `ChatPanel`, not by the card, so it keeps streaming
+   * while the browser is closed and is still there when it is re-opened.
+   */
+  runTests?: (selection: TestSelection, onEvent: (event: TestRunEvent) => void) => TestRunHandle
+  /**
+   * Whether this viewer may RUN tests. `false` still lets them open `/test`
+   * and read what the project tests (the platform serves the listing to
+   * viewers) but disables every run control and shows why. Defaults to
+   * `canEdit !== false`.
+   */
+  canRunTests?: boolean
+  /**
+   * Whether the environment the tests run in is up — a running sandbox.
+   * `false` makes `/test` say to start the project instead of listing an empty
+   * browser or letting a Run click fail. Defaults to `true`.
+   */
+  testsAvailable?: boolean
   className?: string
 }
 ```
@@ -1407,6 +1470,183 @@ interface TabBarProps {
 }
 ```
 
+#### `TestFailure`
+
+One failing test and the output that explains it.
+
+```typescript
+interface TestFailure {
+  item: TestItem
+  output?: string | undefined
+}
+```
+
+#### `TestGroup`
+
+One rendered group of rows: a kind within a project directory.
+
+```typescript
+interface TestGroup {
+  kind: TestKind
+  workspace: TestWorkspace
+  /** The directory's name for the heading; `null` for the workspace root. */
+  label: string | null
+  items: TestItem[]
+}
+```
+
+#### `TestItem`
+
+One test file the host discovered in the project.
+
+```typescript
+interface TestItem {
+  /** Stable id, unique across workspaces — used as the row key and to select by. */
+  id: string
+  /** Path relative to its workspace, e.g. `e2e/home.spec.ts`. */
+  file: string
+  kind: TestKind
+  workspace: TestWorkspace
+  /**
+   * The group's project name, ready to render: the same path as `workspace`,
+   * or `null` for the workspace root, which has no name of its own. Hosts that
+   * omit it get the path itself (and the translated "Project" for the root).
+   */
+  workspaceLabel?: string | null
+  /** Human label for the row; the bar falls back to the file path without one. */
+  title?: string
+}
+```
+
+#### `TestList`
+
+What {@link ChatPanelProps.listTests} resolves with.
+
+```typescript
+interface TestList {
+  tests: TestItem[]
+  /**
+   * Per project directory (keyed like {@link TestItem.workspace}), the runners
+   * the host found. Only directories that hold a listed test appear.
+   */
+  runners: Record<string, TestRunners>
+}
+```
+
+#### `TestResultEntry`
+
+What one test file ended as in the last run.
+
+```typescript
+interface TestResultEntry {
+  status: TestStatus
+  durationMs?: number
+  passed: number
+  failed: number
+  skipped: number
+  /** The runner's output, kept for a FAILURE so the row can keep showing it. */
+  output?: string
+}
+```
+
+#### `TestRunHandle`
+
+Handle to a run in flight, so the bar can stop it.
+
+```typescript
+interface TestRunHandle {
+  /** Stop the run — the host aborts its stream, which cancels the work. */
+  cancel(): void
+}
+```
+
+#### `TestRunners`
+
+Which runner drives each kind in one workspace (`null` = none installed).
+
+```typescript
+interface TestRunners {
+  e2e: string | null
+  unit: string | null
+}
+```
+
+#### `TestsCardProps`
+
+Props for {@link TestsCard}.
+
+```typescript
+interface TestsCardProps {
+  /** Every discovered test (unfiltered). */
+  tests: TestItem[]
+  /** How the listing went. */
+  status: TestsStatus
+  /** The run this card is showing — owned by the panel, so it survives a close. */
+  run: TestsRunState
+  /** Seeds the search box from `/test <query>`. */
+  initialQuery: string
+  /** Whether this viewer may run tests at all (a viewer may not). */
+  canRun: boolean
+  /** Runs a selection. */
+  onRun: (selection: TestSelection) => void
+  /** Stops the run in flight. */
+  onCancel: () => void
+  /**
+   * Hands the failing tests to the agent as ONE chat message — a real turn it
+   * answers, exactly like the editor’s “Fix with AI”.
+   */
+  onFix: (failures: TestFailure[]) => void
+  /**
+   * Why fixing is unavailable (a viewer, a turn already streaming), already
+   * translated by the host — `null` when it is available. The card states the
+   * reason on the disabled button rather than letting a click do nothing.
+   */
+  fixDisabledReason: string | null
+  /** Light theme (drives the same row border + field inset the sibling cards use). */
+  isLight: boolean
+  /** Chrome-less inside the command overlay; full card chrome in the timeline. */
+  embedded?: boolean
+}
+```
+
+#### `TestSelection`
+
+What the bar asks the host to run.
+
+```typescript
+interface TestSelection {
+  /** Specific {@link TestItem.id}s. Takes precedence over `kind`. */
+  ids?: string[]
+  /** Everything of this kind when no `ids` are given. */
+  kind?: TestKind | 'all'
+}
+```
+
+#### `TestsRunState`
+
+Everything the card knows about the run it is showing.
+
+```typescript
+interface TestsRunState {
+  runId: string | null
+  running: boolean
+  /** The ids this run covers, in run order. */
+  queued: string[]
+  /** The id whose output is streaming right now, when the host says which. */
+  currentId: string | null
+  /** The live output lines, newest last, capped at {@link MAX_OUTPUT_LINES}. */
+  output: string[]
+  /** Per-id outcome from this run (and from earlier runs, until re-run). */
+  results: Record<string, TestResultEntry>
+  /** How the run ended, once it has. */
+  outcome: TestRunOutcome | null
+  /** A run-level failure message (timeout, transport error) shown in the card. */
+  error: string | null
+  startedAt: number | null
+  durationMs: number | null
+}
+```
+
 #### `ToolCallCardProps`
 
 Properties for tool call card.
@@ -1649,6 +1889,86 @@ A role granted by a share link.
 type ShareRole = (typeof SHARE_ROLES)[number]
 ```
 
+#### `TestKind`
+
+What a test file is: an end-to-end spec driven against the LIVE PREVIEW (the
+`@molecule/app-e2e-preview` bond every scaffolded app carries), or a plain
+unit test run by the project's own runner.
+
+```typescript
+type TestKind = 'e2e' | 'unit'
+```
+
+#### `TestRunEvent`
+
+One event from a run in progress. The host streams these to the bar (over SSE
+in molecule.dev) in the order the run produces them: one `start`, then
+interleaved `output`/`result`, then exactly one `done`.
+
+```typescript
+type TestRunEvent =
+  | { type: 'start'; runId: string; ids: string[]; startedAt?: string }
+  | { type: 'output'; id?: string; stream?: 'stdout' | 'stderr'; chunk: string }
+  | {
+      type: 'result'
+      id: string
+      status: TestStatus
+      durationMs?: number
+      passed?: number
+      failed?: number
+      skipped?: number
+      /** The runner's output for a FAILURE, which the bar keeps visible. */
+      output?: string
+    }
+  | {
+      type: 'done'
+      runId?: string
+      outcome: TestRunOutcome
+      passed?: number
+      failed?: number
+      skipped?: number
+      durationMs?: number
+      error?: string
+    }
+```
+
+#### `TestRunOutcome`
+
+How a whole run ended.
+
+```typescript
+type TestRunOutcome = 'completed' | 'cancelled' | 'timeout' | 'error'
+```
+
+#### `TestsStatus`
+
+Discovery status for the tests list — mirrors {@link ScriptsCard}'s.
+
+```typescript
+type TestsStatus = 'loading' | 'ready' | 'error' | 'unavailable'
+```
+
+#### `TestStatus`
+
+How one test file ended.
+
+```typescript
+type TestStatus = 'passed' | 'failed' | 'skipped'
+```
+
+#### `TestWorkspace`
+
+Which project directory a test file belongs to: the directory that OWNS the
+file (the nearest ancestor holding the runner's config or a `package.json`),
+as a path relative to the workspace root — `app`, `api`, `my-app/app`,
+`packages/web` — or `.` for the workspace root itself. Nothing guarantees
+`app/` or `api/` at the root: the executor names its project directory, so
+the value is a path, not an enum.
+
+```typescript
+type TestWorkspace = 'app' | 'api' | '.' | (string & {})
+```
+
 #### `TimestampsCommand`
 
 Parsed `/timestamps` invocation: toggle, explicit on/off, or an unrecognized argument.
@@ -1766,6 +2086,23 @@ function activityTypeLabel(type: ActivityType): string
 
 **Returns:** The translated channel label.
 
+#### `applyTestRunEvent(state, event)`
+
+Fold one streamed event into the run state.
+
+Deliberately total: an event for an id the card no longer lists is recorded
+anyway (a re-list may be in flight), and an unknown event type leaves the
+state untouched rather than throwing inside a stream handler.
+
+```typescript
+function applyTestRunEvent(state: TestsRunState, event: TestRunEvent): TestsRunState
+```
+
+- `state` — The current state.
+- `event` — The event just received.
+
+**Returns:** The next state (a new object whenever anything changed).
+
 #### `autoCommitReducer(state, action)`
 
 Pure reducer for the auto-commit countdown. Deterministic and side-effect
@@ -1824,6 +2161,23 @@ function buildShareUrl(result: ShareLinkResult, origin: string): string
 
 **Returns:** The absolute, copyable share URL.
 
+#### `buildTestFixMessage(failures)`
+
+Compose the ONE user message the card's “Fix with Synthase” action sends.
+
+It is a real turn the executor answers, so it reads like something a person
+would type: which test failed, where it lives, what the runner said, and to
+re-run it. This is a PROMPT, not UI copy — it is not translated, exactly like
+the auto-fix loop’s own `Fix these issues:` message.
+
+```typescript
+function buildTestFixMessage(failures: readonly TestFailure[]): string
+```
+
+- `failures` — The failing tests, in the order the card lists them.
+
+**Returns:** The message, or `` when there is nothing to fix.
+
 #### `ChatPanel(props)`
 
 AI chat panel with conversation history dropdown and Claude Code-style tool display.
@@ -1885,6 +2239,10 @@ function ChatPanel({
   version,
   extraCommands,
   feedbackUrl,
+  listTests,
+  runTests,
+  canRunTests,
+  testsAvailable,
   className,
 }: ChatPanelProps): JSX.Element
 ```
@@ -1963,6 +2321,18 @@ function CommandPalette({ commands, onDismiss }: CommandPaletteProps): JSX.Eleme
 
 **Returns:** The command palette element.
 
+#### `countByKind(tests)`
+
+How many tests there are of each kind.
+
+```typescript
+function countByKind(tests: readonly TestItem[]): Record<TestKind, number>
+```
+
+- `tests` — Every discovered test.
+
+**Returns:** The per-kind counts.
+
 #### `DeviceFrameSelector(props)`
 
 A dropdown that selects the preview device frame and hosts the Rotate +
@@ -2021,6 +2391,37 @@ function EditorPanel({
 
 **Returns:** The rendered editor panel element.
 
+#### `failedTests(tests, results)`
+
+Every listed test whose last verdict was a failure, with its output — what
+the card's fix actions send.
+
+```typescript
+function failedTests(
+  tests: readonly TestItem[],
+  results: Record<string, TestResultEntry>,
+): TestFailure[]
+```
+
+- `tests` — The currently listed (and filtered) tests.
+- `results` — The per-id outcomes.
+
+**Returns:** The failures, in list order.
+
+#### `failRun(state, message)`
+
+The state after a run that never produced a `done` event — the host's stream
+died, or its request failed before the server could answer.
+
+```typescript
+function failRun(state: TestsRunState, message: string): TestsRunState
+```
+
+- `state` — The current state.
+- `message` — What to show in the card.
+
+**Returns:** The next state, no longer running.
+
 #### `FileExplorer(props)`
 
 Tree-view file explorer component with multi-select, keyboard navigation, and drag-and-drop.
@@ -2064,6 +2465,21 @@ function filterActivitiesByType(activities: Activity[], type: ActivityType | nul
 
 **Returns:** The filtered list (a new array unless `type` is null).
 
+#### `filterTests(tests, query)`
+
+Filters tests by a free-text query, matching (case-insensitively) against the
+file path, the row title, and the project directory. A blank query returns
+every test in input order — the same contract as `filterScripts`.
+
+```typescript
+function filterTests(tests: readonly TestItem[], query: string): TestItem[]
+```
+
+- `tests` — The tests to filter.
+- `query` — The search query.
+
+**Returns:** The matching tests, in input order.
+
 #### `formatAutoCommitBadge(state)`
 
 Formats the countdown's remaining seconds for the compact badge (e.g. `"12s"`).
@@ -2169,6 +2585,20 @@ function groupCommandsByCategory(
 
 **Returns:** One {@link CommandGroup} per non-empty category, in category order.
 
+#### `groupTests(tests)`
+
+Group tests for display: by kind (end-to-end first), then by project
+directory (whatever directories are present — `app`, `my-app/app`,
+`packages/web`, the root last), with the files sorted inside each group.
+
+```typescript
+function groupTests(tests: readonly TestItem[]): TestGroup[]
+```
+
+- `tests` — Every discovered test.
+
+**Returns:** The groups, in display order. Empty groups are never produced.
+
 #### `hasRenderableAvatar(avatar)`
 
 Whether a stored avatar value is renderable (vs. needing the icon fallback).
@@ -2298,6 +2728,20 @@ function isReportFormValid(form: ReportFormState): boolean
 
 **Returns:** `true` when the form can be submitted.
 
+#### `isRowRunning(state, id)`
+
+Whether a row should render as "running": the run is live and either the host
+named this row as current, or it is in the queue and has no verdict yet.
+
+```typescript
+function isRowRunning(state: TestsRunState, id: string): boolean
+```
+
+- `state` — The run state.
+- `id` — The row's test id.
+
+**Returns:** True when the row is part of the live run and still undecided.
+
 #### `isShareRole(value)`
 
 Type guard for a valid {@link ShareRole} (case-insensitive callers should
@@ -2429,6 +2873,24 @@ function parseShareCommand(input: string): ShareCommand | null
 
 **Returns:** The parsed {@link ShareCommand}, or `null`.
 
+#### `parseTestCommand(input)`
+
+Parses a `/test [query | all]` command (`/tests` is the registered alias).
+
+`all` is the one argument that ACTS: it runs everything immediately. Every
+other argument only filters the list, exactly the way `/scripts <query>` seeds
+the scripts browser — running ONE test by name is what the per-row Run button
+is for, and giving the argument a second meaning would make `/test <thing>`
+sometimes list and sometimes execute.
+
+```typescript
+function parseTestCommand(input: string): { query: string; runAll: boolean } | null
+```
+
+- `input` — The raw chat input.
+
+**Returns:** `{ query, runAll }` when it is a `/test` command, else `null`.
+
 #### `parseTimestampsCommand(input)`
 
 Parses `/timestamps [on | off]`. `show`/`hide` are accepted as synonyms.
@@ -2767,6 +3229,23 @@ function SidebarTabs({ activeTab, onTabChange, children, className }: SidebarTab
 
 **Returns:** The sidebar tabs element.
 
+#### `summarizeResults(tests, results)`
+
+The tallies of the last run, over the tests that are still listed. Counted
+per FILE (one row, one verdict) so the collapsed summary matches the rows.
+
+```typescript
+function summarizeResults(
+  tests: readonly TestItem[],
+  results: Record<string, TestResultEntry>,
+): { passed: number; failed: number; skipped: number; reported: number }
+```
+
+- `tests` — The currently listed tests.
+- `results` — The per-id outcomes.
+
+**Returns:** Passed/failed/skipped file counts.
+
 #### `TabBar(props)`
 
 Horizontally scrollable tab bar for open editor files.
@@ -2787,6 +3266,42 @@ function TabBar({
 
 **Returns:** The rendered tab bar element, or null if no tabs are open.
 
+#### `testRowLabel(item)`
+
+The label for a row: the host's title when it gave one, else the file path.
+
+```typescript
+function testRowLabel(item: TestItem): string
+```
+
+- `item` — The test.
+
+**Returns:** The label to render.
+
+#### `TestsCard(props)`
+
+The tests browser shown by `/test`.
+
+```typescript
+function TestsCard({
+  tests,
+  status,
+  run,
+  initialQuery,
+  canRun,
+  onRun,
+  onCancel,
+  onFix,
+  fixDisabledReason,
+  isLight,
+  embedded,
+}: TestsCardProps): JSX.Element
+```
+
+- `props` — See {@link TestsCardProps}.
+
+**Returns:** The rendered tests card.
+
 #### `useChatTimestampsVisible()`
 
 Whether chat timestamps are turned on for every item on this device. Re-renders
@@ -3043,6 +3558,14 @@ An empty report form (the modal's initial state).
 const EMPTY_REPORT_FORM: ReportFormState
 ```
 
+#### `EMPTY_RUN_STATE`
+
+A run that has not started.
+
+```typescript
+const EMPTY_RUN_STATE: TestsRunState
+```
+
 #### `IS_MAC`
 
 Detect macOS / iOS for Cmd vs Ctrl.
@@ -3059,6 +3582,30 @@ Maximum avatar source length we will render inline (~256 KB data-URI).
 const MAX_AVATAR_SRC_LENGTH: 262144
 ```
 
+#### `MAX_FIX_MESSAGE_OUTPUT_CHARS`
+
+Total output kept across a batched fix message, so one click cannot send a novel.
+
+```typescript
+const MAX_FIX_MESSAGE_OUTPUT_CHARS: 12000
+```
+
+#### `MAX_FIX_OUTPUT_CHARS`
+
+Output kept per failure when several are batched into one fix message.
+
+```typescript
+const MAX_FIX_OUTPUT_CHARS: 2000
+```
+
+#### `MAX_OUTPUT_LINES`
+
+Live output lines retained — enough to read, bounded so a chatty run cannot grow forever.
+
+```typescript
+const MAX_OUTPUT_LINES: 400
+```
+
 #### `MAX_PANEL_PERCENT`
 
 Largest a panel may grow to, as a percentage of the container.
@@ -3232,6 +3779,36 @@ Peer dependencies:
 - A custom card is a critical event only when its factory sets
   `critical: true` (a failure, a blocked action, a limit that stopped work) —
   the package never infers it from tone or copy.
+- `ChatPanel` owns no pricing or auth routes, so every limit/upgrade button
+  comes from the host's `buildUpgradeCta(context)`. The context forwards the
+  backend's whole description of the refusal: `requiresSignup`, `limitType`
+  (the rule that fired), `billingAction` (the remedy it resolved — e.g.
+  `add_funds`, `add_payment_method`, `raise_spend_cap`, `upgrade`, `none`) and
+  `upgradeTier` (`null` = no higher plan). Branch on `billingAction` first;
+  every field is optional, so keep a fallback. A live limit banner and a
+  recorded card that declares the same `coversLimitType` state one fact, so
+  the card steps aside while the banner is up — which only reads as one
+  consistent message if the banner's button is resolved from the same
+  `billingAction` the card used.
+- **`/test` lists and runs the project's tests** (`TestsCard`, opened by the
+  `/test` command — `/tests` is a registered alias — in the same closeable
+  overlay as `/scripts` and `/skills`, and renderable in the timeline as the
+  `tests` system card). It owns no routes: pass `listTests` and `runTests`
+  and the command works; omit either and it has nothing to run.
+  `runTests(selection, onEvent)` returns a handle whose `cancel()` must
+  really stop the run, and it must deliver exactly one `done` event however
+  the run ends — including when the request never opened — or the card spins
+  forever. `canRunTests` (a viewer: false) and `testsAvailable` (the
+  environment is up) each disable the run controls and state their own
+  reason in the card. The RUN is owned by `ChatPanel`, not the card, so it
+  keeps streaming while the overlay is closed. `/test all` runs everything;
+  any other argument only filters the list.
+- **End-to-end specs are meant to run against the LIVE PREVIEW.** The host
+  should drive them through `@molecule/app-e2e-preview` (what every
+  `mlcl create` app already bonds in `e2e/bonds.ts`), not a browser binary —
+  in a sandbox there is none. That bond drives the page the person is
+  actually looking at, so **a preview must be open** somewhere or the driver
+  waits and fails; the card says so next to the end-to-end group.
 - Text routes through `t('ide.*')` — `@molecule/app-locales-ide` supplies
   translations.