@w6w/ui 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to `@w6w/ui` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Releases are
+tagged `vX.Y.Z` and published to npm by `.github/workflows/release.yml`; changes not yet released
+accumulate under `[Unreleased]`. Entries below `[0.1.0]` predate the first npm release — see the
+repo's git history for exact dates and commits.
+
+## [Unreleased]
+
+## [0.1.0]
+
+First npm release (`npm install @w6w/ui`).
+
+- `@w6w/expr` is now a regular npm dependency (`^0.1.0`) instead of the
+  `github:w6w-io/w6w-core#path:packages/expr` git spec, and is external to the build: the dist
+  chunks `import`/`require` it rather than bundling it.
+- Fixed the published manifest: the packed tarball's `main`/`module`/`types` and `exports` point at
+  `./dist/*` (packed with `pnpm pack`, which applies `publishConfig`), and the tarball ships only
+  `dist/`, the stylesheet exports, `LICENSE`, `README.md` and `CHANGELOG.md` — no tests, stories,
+  test loader or `.d.ts` for tests. `scripts/assert-packed-manifest.mjs` and
+  `test/pack-smoke/run.sh` (a clean-consumer `tsc` + `vite build`) gate it.
+- Inside this repo `@w6w/expr` resolves to the sibling core checkout's source through the
+  `w6w-source` export condition (tsconfig `customConditions`, Vite/Storybook `resolve.conditions`,
+  `node --conditions`, the `test/` rigs' esbuild), so no expr `dist/` has to be built first.
+
+### Earlier unreleased changes, shipped in 0.1.0
+
+- The expression editor's rail toggle for a source's child fields (a step's output fields, a
+  document's keys) now reads "N fields ›" instead of a bare 20px chevron, which went unnoticed
+  beside the source chip. On a step with fields, the `▸` arrow moved out of the chip into its own
+  caret that expands the fields; it used to insert the whole output instead.
+- The expression editor's **Workflow state** rail now offers an upstream app step's output
+  fields without a test run: the action's declared `output` (dot keys become nested paths such as
+  `steps.<id>.output.start.utc`), else its `sample`, else the step's last test output. A step with
+  none of these shows "Run a test of this step to see its fields".
+- Rewrote the user guide in `docs/` for docs.w6w.io (section `ui`): an overview, theming, the
+  design system, and a components reference with one page per group. Corrected `README.md`: MIT
+  license, provider-based usage, all 42 components, current stylesheet sizes and bundler notes.
+  Moved the token-gate rules for contributors into `CONTRIBUTING.md`.
+- Added a branded `.storybook/manager.ts` theme.
+- Added `*.stories.tsx` coverage for every exported component, and a `pnpm coverage:stories` check
+  that keeps it that way.
+- Rewrote `README.md` for an outside reader: install/consume without npm, a full component list,
+  palette ancestry, and credits.
+- Added `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, issue templates, and a PR template.
+- Completed `package.json` metadata (`homepage`, `author`, `keywords`, `description`).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 w6w-io
+
+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,3 +1,261 @@
-# Temporary Holding Version
+<p align="center">
+  <a href="https://w6w.io">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset=".github/assets/w6w-lockup-ondark.svg">
+      <source media="(prefers-color-scheme: light)" srcset=".github/assets/w6w-lockup.svg">
+      <img src=".github/assets/w6w-lockup.svg" alt="W6W" width="320">
+    </picture>
+  </a>
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @w6w/ui
+
+React components for [W6W](https://w6w.io) — central API management: one front door, composition,
+visibility and plug & play for every API a product runs on. These are the components W6W's own
+studio is built from, packaged for any app that talks to a W6W server: the connect-an-app modal,
+the app picker, the step builder, the visual workflow canvas, execution history, health and status
+indicators, and the smaller pieces around them.
+
+## Documentation
+
+The user guide lives in [`docs/`](docs/) and is published at
+[docs.w6w.io](https://docs.w6w.io) under **UI**:
+
+- [Overview](docs/overview.md): install, stylesheet, provider, first component, bundler notes.
+- [Theming](docs/theming.md): light/dark mode and every color token.
+- [Design system](docs/design-system.md): the spacing, type and font tokens.
+- [Components](docs/components/index.md): every component, by group, with props and examples.
+
+This README covers the repository itself: what's in it and how it's built.
+
+## Install / consume
+
+```sh
+npm install @w6w/ui react react-dom
+```
+
+`@w6w/expr` is a regular npm dependency and installs with it. `react` and `react-dom` (18 or later)
+are peer dependencies. The npm tarball ships compiled `dist/` (ESM + CJS + `.d.ts`), plus the
+stylesheets; the CommonJS build needs Node 20.19+ / 22.12+ to `require()` the ESM-only `@w6w/expr`.
+
+Two source routes remain, for working against an unreleased commit or a sibling checkout:
+
+- **Git dependency**: `"@w6w/ui": "github:w6w-io/w6w-ui#<commit-sha>"` — the repo is public.
+- **Sibling checkout with `link:`**: `"@w6w/ui": "link:../w6w-ui"` — the pattern this monorepo
+  uses (`studio` links `ui` this way).
+
+In this repo `main`/`module`/`types` and `exports` point at raw `.tsx` source under `./src`
+(`publishConfig` switches them to `dist/` in the packed npm tarball, which `pnpm pack` applies), so
+on those two routes your bundler compiles the package like your own code. Inside this repo
+`@w6w/expr` resolves to the sibling `packages/core` checkout through the `w6w-source` export
+condition (set in `tsconfig.json`, `vite.config.ts`, `.storybook/vite.config.ts`, the `test` script
+and the `test/` rigs). Vite needs nothing extra; a few setups do — see the
+[bundler notes](docs/overview.md#bundler-notes):
+
+- **Vite with a `link:` checkout**: studio sets `optimizeDeps.exclude: ["@w6w/ui"]` so edits are
+  picked up live.
+- **SSR builds**: the package must be bundled, not externalized — the frontend site's Astro build
+  sets `ssr.noExternal` for `@w6w/ui` and `prism-react-renderer` (a React-rendering dependency of a
+  source package needs its own entry). Next.js needs the equivalent, `transpilePackages`.
+- **A linked checkout**: dedupe React (`resolve.dedupe: ["react", "react-dom"]`), or two copies
+  break hooks.
+
+## Usage
+
+Five components call your W6W server themselves — `AppPicker`, `AddConnectionModal`,
+`ActionTestForm`, `StepBuilderModal` and `WorkflowFlowEditor`. They read one API client from
+`W6WUIProvider`. Every other component is props in, callbacks out.
+
+```tsx
+import { AddConnectionModal, W6WUIProvider, createW6WApi } from "@w6w/ui";
+import "@w6w/ui/styles.css";
+
+const api = createW6WApi({ baseUrl: "https://<your-host>", token: () => getToken() });
+
+<W6WUIProvider api={api} theme="light">
+  {open && (
+    <AddConnectionModal
+      onClose={() => setOpen(false)}
+      onCreated={({ connectionId }) => {
+        setOpen(false);
+        refetch(connectionId);
+      }}
+    />
+  )}
+</W6WUIProvider>
+```
+
+`createW6WApi` implements every required `W6WApi` member plus `listApps` and `listTestRuns`. It does
+not implement the optional paged-catalog or app-trigger members, and its `invokeAction` does not
+forward `overrides` yet. `@w6w/react`'s `createW6WUiAdapter` is the other way to build the client.
+See [Providers and the API client](docs/components/providers.md).
+
+`Copyable` is the one props-only component with a side effect: it writes to `navigator.clipboard`.
+
+```tsx
+import { CodeBlock, Copyable } from "@w6w/ui";
+
+<Copyable value={apiKey} readOnly>
+  <input readOnly value={apiKey} />
+</Copyable>
+
+<CodeBlock code={curlSnippet} language="bash" />
+```
+
+### Entrypoints
+
+Three, so you only resolve what you use. This matters more than bundle size: the root index
+imports `@w6w/expr` and CodeMirror, and a bundler resolves before it tree-shakes, so a consumer
+without those in its tree fails to *build*, not merely to slim down.
+
+| Import | Contains | Stylesheet |
+|--------|----------|------------|
+| `@w6w/ui` | everything except the flow editor | `@w6w/ui/styles.css` (~121 KB) |
+| `@w6w/ui/flow` | `WorkflowFlowEditor` and its helpers — pulls in `@xyflow/react` | `@w6w/ui/styles.css` |
+| `@w6w/ui/code` | `CodeBlock` + `Copyable` — needs only React and `prism-react-renderer` | `@w6w/ui/code.css` (~19 KB) |
+
+`code.css` is a strict subset of `styles.css`, so importing both is harmless — the rules are
+byte-identical. Reach for `@w6w/ui/code` when you want the highlighter in something that is not a
+full W6W console; the marketing site (`packages/frontend`) renders its homepage snippets that way,
+at build time, shipping no React at all.
+
+`WorkflowFlowEditor` imports React Flow's stylesheet (`@xyflow/react/dist/style.css`) itself.
+
+```tsx
+import { CodeBlock } from "@w6w/ui/code";
+import "@w6w/ui/code.css";
+```
+
+## Theming
+
+`styles.css` defines every color as a `--w6w-*` custom property, in a light and a dark variant:
+surfaces and text (`--w6w-bg`, `--w6w-panel`, `--w6w-panel-2`, `--w6w-border`, `--w6w-text`,
+`--w6w-muted`), roles (`--w6w-accent`, `--w6w-danger`, `--w6w-success`), health
+(`--w6w-health-*`), code (`--w6w-code-*`), plus `--w6w-radius` and `--w6w-icon-swatch`. Defaults are
+declared with zero specificity (`:where(...)`), so a plain `:root` rule overrides them.
+
+```css
+:root {
+  --w6w-accent: #6b46c1;
+}
+```
+
+The mode resolves in this order: a component's own `theme` prop, then `<W6WUIProvider theme>`,
+then a `data-theme` attribute on `<html>` (or any ancestor, for the CSS), then the OS
+`prefers-color-scheme`. An embedder whose app has its own theme should pass it to the provider, or
+the components may render in a different mode than the page around them. Full tables and the
+troubleshooting list: [`docs/theming.md`](docs/theming.md).
+
+The same namespace carries the spacing and type scale (`--w6w-sp-*`, `--w6w-fs-*`, `--w6w-fw-*`,
+`--w6w-lh-*`, `--w6w-font-*`): [`docs/design-system.md`](docs/design-system.md). The `lint:tokens`
+gate that keeps new code on that scale is described in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+### Where the styles come from
+
+The stylesheet is authored in **Sass**: `src/styles.scss` is the entry point and `src/styles/*.scss`
+holds one partial per component family. `src/styles.css` is compiled from those (`pnpm build:css`)
+and committed, so `import "@w6w/ui/styles.css"` above needs no Sass toolchain on your side — that
+stays the supported way in.
+
+If you *do* build with Sass, you can import the source instead and get the partials as
+`@use`-able modules:
+
+```scss
+@use "@w6w/ui/styles.scss";   // the whole stylesheet
+@use "@w6w/ui/styles/health"; // or one family — see src/styles/ for the list
+```
+
+Editing `src/styles.css` by hand has no effect — it is regenerated, and `pnpm check:css` fails when
+it has drifted from the Sass sources. Two things stay fixed on purpose: `--w6w-*` remain **CSS**
+custom properties (Sass variables would compile away before you could override them at runtime), and
+`.w6w-*` class names are part of the public surface, which is why this ships as one global
+stylesheet rather than CSS Modules.
+
+### Palette ancestry
+
+`@w6w/ui` compiles its own `--w6w-*` tokens from `src/styles.scss` above — branding is not a build
+dependency, so nothing here fetches or imports from another repo at build time. The values
+themselves descend from [`w6w-io/w6w-branding`](https://github.com/w6w-io/w6w-branding), the source
+palette (`tokens/tokens.json`, `BRAND.md`); a branding update is ported into `src/styles/` by hand,
+not pulled in automatically.
+
+## Components
+
+42 exported components (the count `pnpm coverage:stories` checks), grouped as in the docs:
+
+- **Providers**: `W6WUIProvider`, `ExpressionOptionsProvider` (plus `createW6WApi`, `useW6WApi`,
+  `useExpressionOptions`, `startOAuthPopup`, `useEnterSubmit`).
+- **Buttons and icons**: `IconButton`, `Icon`, `EditButton`, `DeleteButton`.
+- **Data display**: `AppIcon`, `ListItem`, `Copyable`, `CopyableText`.
+- **Forms**: `AppPicker`, `ActionTestForm`, `ParamsForm`, `PropertyEntryForm`, `AuthFieldsForm`,
+  `ExpressionInput`, `NodeConfigForm`, `RetryPolicyFields`.
+- **Editors**: `CodeBlock`, `CodeEditor`, `JsonEditor`, `YamlEditor`.
+- **Workflow canvas**: `WorkflowFlowEditor` (from `@w6w/ui/flow`).
+- **Modals**: `Modal`, `ConfirmModal`, `AddConnectionModal`, `StepBuilderModal`.
+- **Status and health**: `HealthStatusPill`, `StepStatusPill`, `UptimeStrip`, `HistoryTimeline`,
+  `RepoSyncIndicator`.
+- **Executions**: `ExecutionList`, `ExecutionFilters`, `ExecutionStats`, `ExecutionDetail`,
+  `ExecutionLogPanel`, `ApiCallsPanel`.
+- **Server resources**: `ServerResourcesCard`, `ServerResourcesCardSmall`, `ServerResourcesRail`,
+  `ServerResourcesBadge`.
+
+Everything is exported from `@w6w/ui` except `WorkflowFlowEditor`, which is only in `@w6w/ui/flow`
+(alongside a re-export of `ExpressionOptionsProvider`). `@w6w/ui/code` re-exports `CodeBlock` and
+`Copyable`.
+
+## Storybook
+
+```sh
+pnpm storybook         # dev server on :6006
+pnpm build-storybook   # static build in storybook-static/ (gitignored)
+pnpm coverage:stories  # fail if an exported component has no story
+```
+
+Stories live **beside their component** (`src/CodeBlock.stories.tsx`), never in a separate
+`stories/` tree, so one cannot drift from the other; `.storybook/main.ts` globs
+`../src/**/*.stories.tsx` and nothing else. There are deliberately no scaffolded Button/Header/Page
+examples — every entry in the sidebar is a real component of this library.
+
+The sidebar is grouped by category: each story's `title` is `<Category>/<Component>`
+(`"Forms/ParamsForm"`), and the category is one of the list in `.storybook/preview.tsx`'s
+`storySort.order` — Buttons, Forms, Editors, Modals, Data Display, Status & Health, Executions,
+Server Resources, Providers. A new category is added to that list too, so the sidebar order stays
+deliberate.
+
+Every component exported from the root entrypoint and from both subpaths (`@w6w/ui/flow`,
+`@w6w/ui/code`) has a co-located story. `pnpm coverage:stories` enforces this: it reads every
+component out of `package.json`'s `exports` map and fails, listing each one by name, if any has no
+matching `*.stories.tsx` — so a newly exported component that ships without a story fails the check,
+not just an existing one that loses its story.
+
+The toolbar's **Theme** switch sets `data-theme` on the canvas, which is the same signal the
+components and `styles.scss` read, so a story is exercising the real theming contract. The preview
+imports `src/styles.scss` (the authored source) rather than the compiled CSS, so editing a partial
+under `src/styles/` hot-reloads.
+
+Stories are excluded from the published tarball (`files`) and from the `.d.ts` emit.
+
+## Develop / contribute
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the dev setup, the full command list, and the rule that a
+new exported component ships with its story.
+
+## Credits
+
+Maintained by **W6W** — `w6w, Inc, a Delaware corporation`.
+[w6w.io](https://w6w.io) · [docs.w6w.io](https://docs.w6w.io)
+
+The `Icon` set (`src/components/icons.tsx`) is copied from the studio's inline SVGs, most of them
+in the [Feather](https://feathericons.com) idiom (MIT, © Cole Bemis); each entry names its source.
+
+Built with [`@xyflow/react`](https://reactflow.dev), CodeMirror (via
+[`@uiw/react-codemirror`](https://uiw-react-codemirror.vercel.app)), and
+[`prism-react-renderer`](https://github.com/FormidableLabs/prism-react-renderer).
+
+## License
+
+**MIT** — see [LICENSE](LICENSE). (Relicensed from FSL-1.1-ALv2 on 2026-09-23; the studio stays
+FSL.)
+
+`@w6w/expr`, which this package depends on, is MIT too, as is `@w6w/types`, the shared model these
+components' wire types mirror (`@w6w/ui` keeps its own local copy rather than depending on it).

package/dist/ActionTestForm.d.ts

@@ -0,0 +1,76 @@
+import { ActionDef, SavedTest, ThemeMode } from './types.ts';
+export interface ActionTestFormProps {
+    /** App the action belongs to. */
+    appId: string;
+    /** The app's actions — the caller already has them from the app detail. */
+    actions: ActionDef[];
+    /** Fixed connection to run against; its credential is resolved server-side. */
+    connectionId?: string;
+    /**
+     * Pre-selected action (controlled). When provided the built-in action
+     * `<select>` is hidden — the caller is already driving the selection.
+     */
+    action?: ActionDef | null;
+    /** Theme hint, accepted for parity with other ui-lib components. */
+    theme?: ThemeMode;
+    /**
+     * Studio-integration seam: when provided (and its reference changes) the
+     * current action's params are seeded from a shallow copy of this object, so a
+     * host page can "open" a saved test pre-filled. The stored object is never
+     * mutated; a subsequent user edit is free to diverge. Optional — existing
+     * consumers keep compiling.
+     */
+    seedValues?: Record<string, unknown> | null;
+    /**
+     * Studio-integration seam: fired after a successful saved-test create/delete
+     * so the host page can invalidate its own `["saved-tests", connId]` query.
+     * The modal rail still refreshes its own list independently. Optional.
+     */
+    onSavedTestsChanged?: () => void;
+    /**
+     * Studio-integration seam (URL-driven host): the id of the saved test being
+     * edited, from a studio deep link (`…/test/:testId`). When it changes to a
+     * non-null id it is adopted as the current `editingTestId` — so the bottom Save
+     * PATCHes that row and the Delete button shows; when null the tester is a
+     * fresh/unsaved test. Optional — existing consumers keep compiling.
+     */
+    seedTestId?: string | null;
+    /**
+     * Studio-integration seam: fired whenever the current `values` diverge from
+     * (or return to) the seeded baseline. This is the unsaved-changes signal the
+     * studio host gates modal-close on (its ConfirmModal prompt). Optional.
+     */
+    onDirtyChange?: (dirty: boolean) => void;
+    /**
+     * Studio-integration seam: fired after a successful save (POST create or PATCH
+     * update) with the resulting `SavedTest`, so the host can sync the URL
+     * (`…/test/:id`) and clear its own dirty state. Optional.
+     */
+    onTestSaved?: (test: SavedTest) => void;
+    /**
+     * Studio-integration seam: fired after a successful delete of the saved test
+     * currently being edited, with the deleted id, so the host can navigate away
+     * from a now-dead `…/test/:id` URL. Optional — existing consumers keep compiling.
+     */
+    onDeleted?: (testId: string) => void;
+    /**
+     * Host-embedded mode. When `true` the caller already renders this widget inside
+     * its own modal (studio's `ConnectionTesterModal`), so the widget suppresses its
+     * OWN `<Modal>` + pop-out (⤢) toggle and instead fills the host container as a
+     * full-height flex column: the params + saved-tests region scrolls and the
+     * action bar is pinned to the bottom. Default `false` — non-embedded (inline /
+     * own pop-out) usages are unchanged.
+     */
+    embedded?: boolean;
+}
+/**
+ * Schema-driven form to test/run a single action against a connection. Renders
+ * the action's declared params through {@link ParamsForm} (the same primitive
+ * the step builder uses) instead of a raw JSON textarea, invokes the action via
+ * `useW6WApi().invokeAction`, and shows the returned value or error.
+ *
+ * The selected action is either controlled by the caller (`action` prop) or
+ * chosen from a built-in `<select>` over `actions`. Param values reset whenever
+ * the selected action changes.
+ */
+export declare function ActionTestForm({ appId, actions, connectionId, action, seedValues, onSavedTestsChanged, seedTestId, onDirtyChange, onTestSaved, onDeleted, embedded, }: ActionTestFormProps): import("react").JSX.Element;

package/dist/AddConnectionModal.d.ts

@@ -0,0 +1,24 @@
+import { ThemeMode } from './types.ts';
+export interface AddConnectionModalProps {
+    onClose: () => void;
+    /** Fired after a successful create (both API-key and OAuth paths). */
+    onCreated: (result: {
+        connectionId: string;
+    }) => void;
+    /** Optional theme hint passed through to `AppIcon` (light/dark variant). */
+    theme?: ThemeMode;
+    /**
+     * Pre-select an app and skip the picker — used when the modal is opened for a
+     * specific app (e.g. from the step builder). Omit to let the user pick.
+     */
+    initialAppId?: string;
+}
+/**
+ * Add-connection modal. Same shape as the step builder's "add a step" modal —
+ * the shared {@link AppPicker} (searchable icon grid) for step one, then the
+ * chosen app's connection fields for step two — minus the tabs. Pick an app →
+ * pick an auth method → fill the fields (or run OAuth) → submit. The
+ * `AuthDef.fields` array drives the form, so no app-specific knowledge is baked
+ * in. Data + IO come from `useW6WApi()`.
+ */
+export declare function AddConnectionModal(props: AddConnectionModalProps): import("react").JSX.Element;

package/dist/AppPicker.d.ts

@@ -0,0 +1,83 @@
+import { ReactNode } from 'react';
+import { AppSummary, ThemeMode } from './types.ts';
+export interface AppPickerProps {
+    /** Fired when the user picks an app card. */
+    onSelectApp: (app: AppSummary) => void;
+    theme?: ThemeMode;
+    /** Optional pre-filter over the app list (e.g. only connectable apps). Applied CLIENT-side, on top of whatever page/list was fetched — never widens a fetch, only narrows what's shown. */
+    filter?: (app: AppSummary) => boolean;
+    /** Search-box placeholder. Defaults to "Search apps…". */
+    searchPlaceholder?: string;
+    /** Message shown when the (filtered) app list is empty. */
+    emptyMessage?: string;
+    /** Render the search input. Defaults to `true`; the connected-apps list opts out. */
+    search?: boolean;
+    /** Rendered beneath `emptyMessage` in the empty state (e.g. a "Browse all apps" button). */
+    emptyAction?: ReactNode;
+    /**
+     * Supply the catalog instead of letting the picker fetch it. For a caller
+     * that already holds the list — and, more to the point, that decides
+     * membership from fields this package's {@link AppSummary} does not carry
+     * (`supportsOAuth`, `owner`): passing the decided list keeps ONE list and one
+     * loading/error state, where `filter` would mean a second `listApps()` whose
+     * result can disagree with the caller's. `null` is "still loading" and
+     * renders the same placeholder the internal fetch does. Supplying a list
+     * (including `null`) always suppresses BOTH the legacy eager fetch and the
+     * bounded paged fetch below.
+     */
+    apps?: AppSummary[] | null;
+    /**
+     * Render an opt-in category-filter chip row, derived from the VISIBLE
+     * catalog's own `categories` values (never the full RFC vocabulary — see
+     * `app-categories.ts`). Defaults to `false`. Only {@link AddConnectionModal}
+     * turns this on today — both `StepBuilderModal` picker call sites already
+     * narrow their catalog through `filter`, so a second filter layer there
+     * would be redundant.
+     */
+    categoryFilter?: boolean;
+    /**
+     * Server-side `category` param for the bounded paged fetch (e.g. `"ai"` for
+     * the AI tab) — sent to `W6WApi.listAppsPage`, never applied client-side.
+     * Ignored when `apps` is supplied or the host has no `listAppsPage`.
+     */
+    category?: string;
+    /** Bounded page size for the paged fetch. Defaults to {@link DEFAULT_PAGE_LIMIT} (60). */
+    pageLimit?: number;
+    /**
+     * Optional page loader that takes precedence over `W6WApi.listAppsPage` and
+     * turns on the paged mode by itself (ignored when `apps` is supplied). It
+     * is called with exactly `{ q, cursor, limit, signal }` — never `category`
+     * or `compact` — and reuses the picker's debounce, stale-response guard,
+     * abort, Load more and Retry. Held in a ref: its identity may change every
+     * render without causing a request.
+     */
+    loadPage?: (options: {
+        q?: string;
+        cursor?: string;
+        limit: number;
+        signal: AbortSignal;
+    }) => Promise<{
+        apps: AppSummary[];
+        nextCursor?: string;
+    }>;
+}
+/**
+ * Searchable grid of app cards (icon + name + id + version) — the shared app picker used
+ * by both the step builder and the add-connection modal.
+ *
+ * **Three loading modes**, chosen automatically and mutually exclusive:
+ *
+ * 1. `apps` supplied (including `null`) — the caller owns loading; this
+ *    component only renders.
+ * 2. `apps` omitted and the host implements `W6WApi.listAppsPage` — bounded
+ *    server-paged loading: one page per search/category, explicit
+ *    "Load more", debounced search, cancellation on query change/unmount
+ *    (T2.1.1 A2). This is the path every current call site in this package
+ *    reaches once its host wires the optional method.
+ * 3. `apps` omitted and the host has ONLY the legacy `W6WApi.listApps` —
+ *    unchanged eager full-catalog fetch, preserved byte-for-byte for
+ *    backward compatibility with an older/imported provider (C6). A host
+ *    with neither `listAppsPage` nor `listApps` settles into this same
+ *    mode's existing empty state — no request, no throw.
+ */
+export declare function AppPicker({ onSelectApp, theme, filter, searchPlaceholder, emptyMessage, search, emptyAction, apps: providedApps, categoryFilter, category, pageLimit, loadPage, }: AppPickerProps): import("react").JSX.Element;