---
icon: 🎛️
---

# Web Feature Anatomy

What a frontend feature looks like in `packages/web/src/`. The canonical reference is `features/tables/` — when this page and that folder disagree, the folder wins.

## Feature folder

```
features/{feature}/
  api/          # api clients — tables-api.ts, fields-api.ts
  components/   # React components
  hooks/        # react-query hooks — table-hooks.ts
  stores/       # zustand stores, when the feature has client state
  types/
  utils/
  index.ts      # barrel — the feature's public surface
```

Everything crossing the feature boundary goes through `index.ts`. See `features/tables/index.ts`: React components are exported **by name** (`ApTableHeader`, `ImportTableDialog`), while plain function/constant utils are grouped into one object first (`tablesApi`, `tableHooks`) and re-exported as that object.

## API client and hooks

API client: `features/tables/api/tables-api.ts`. Hooks: `features/tables/hooks/table-hooks.ts`.

On any query that fetches a page's **primary** data — the table rows, the list, the thing the page exists to show — render `DataFetchErrorState` (`components/custom/data-fetch-error-state.tsx`) in place of the rows when it fails. `DataTable` takes `isError` / `errorStateEntity` / `onRetry` and swaps it in ahead of the empty state; a surface that is not a `DataTable` (automations, agents, the AI providers and capabilities tabs, the platform MCP page, the embed subdomain steps, the health runs tab) branches on `isError` before its own empty state. `errorStateEntity` is the already-translated lowercase noun that reads inside "Trouble loading {entity}", so it names the thing the user was looking at rather than the endpoint. Leave it off auxiliary queries (feature flags, piece metadata, single-item fetches, filter options, user details) — those should fail silently.

The copy is deliberately unalarming and says the data is safe, because the failure mode being designed against is a user believing their flows are gone. `QueryCache.onError` in `app/query-client.ts` does nothing but `console.error`.

## Route

Routes are registered in `app/routes/project-routes.tsx`, composed from `ProjectRouterWrapper` plus guards:

```tsx
...ProjectRouterWrapper({
    path: routesThatRequireProjectId.myFeature,
    element: (
        <RoutePermissionGuard requiredPermissions={Permission.READ_MY_FEATURE}>
            <PageTitle title="My Feature">
                <SuspenseWrapper>
                    <MyFeaturePage />
                </SuspenseWrapper>
            </PageTitle>
        </RoutePermissionGuard>
    ),
}),
```

The page component itself is `React.lazy()`-imported. `requiredPermissions` takes a single `Permission` or an array. Guards live in `app/guards/` — `permission-guard.tsx`, `flag-route-guard.tsx`, `project-route-wrapper.tsx`.

The platform-admin tree is a different shape and does not use any of that. `app/routes/platform-routes.tsx` is a flat array of hand-written entries, each repeating `PlatformLayout` > `PageTitle` > `SuspenseWrapper` by hand, with no React Router layout route and no `Outlet`. The admin check is not a guard in `app/guards/` either: `useIsPlatformAdmin()` is called inside `PlatformLayout` itself, which renders `<Navigate to="/" />` when it fails. So the guard holds only because every single route remembers to wrap in that layout, and a new admin route that forgets it is reachable by any logged-in user. The nav is a literal in one function, `PlatformSidebar` in `app/components/sidebar/platform/index.tsx`, so a route and its nav entry are edited in two unconnected places.

## Flags, gating, translations

- Feature flags: `flagsHooks.useFlag()`, or `<FlagGuard>` / `flag-route-guard.tsx` for whole routes.
- Paid features: `LockedFeatureGuard` on the frontend, `enabled: platform.plan.<flag>` on the query. The backend counterpart is `platformMustHaveFeatureEnabled()`, which returns 402.
- Translations go in `packages/web/public/locales/en/translation.json` **only** — the other locales are generated. Zod validation messages must be keys in that file, not raw English; reuse the `formErrors` constant from `@activepieces/shared` for common ones.

## Editions

Every customer-facing surface must be checked on all five edition paths — CE, EE self-hosted, Cloud freemium, Cloud self-serve paid, Cloud enterprise. Nothing user-visible hardcodes "Activepieces": name, colours, and logos come from platform appearance. Community always gets the default theme, Cloud always applies platform branding, EE requires `platform.plan.customAppearanceEnabled`. See `ee/helper/appearance-helper.ts`.

A default local dev instance runs `edition=ce` (check `/api/v1/flags`), and most of the platform-admin surface is unreachable there — Global Connections, Pieces, Templates, Billing, Usage, Embedding, SSO, Project Roles, API Keys, Secret Managers, Audit Logs and Event Streaming all render `LockedFeatureGuard` instead of their body, and the AI Center's Capabilities tab is not rendered at all. So a change to any of those cannot be seen locally without first flipping the `platform_plan` flags in the dev Postgres; Embedding needs more than that, since `useEmbedSubdomain` is gated on `edition === CLOUD` and so needs `AP_EDITION=cloud` and a restart. Plan for that before promising a screenshot of a gated page.

To switch a local backend's edition without editing `.env.dev`, prefix the command: `AP_EDITION=cloud npm run dev:backend`. Turbo passes `AP_EDITION` through (`globalPassThroughEnv`) and `bootstrap.ts` loads `.env.dev` without overriding variables already set, so the shell value wins; the startup log says `Activepieces Edition … edition: cloud`. Stop the old backend first, or the new one dies with `EADDRINUSE :3000` while the old edition keeps answering. If the old one runs in another terminal, find it with `lsof -nP -iTCP:3000 -sTCP:LISTEN` and stop its `tsx watch` parent as well as the node child, or the watcher starts it again; the new watcher that already failed retries after any change under `packages/server/api/src` (a `touch` of `bootstrap.ts` is enough).

Running one frontend per edition side by side (a vite port each against its own backend) is the quickest
way to check all of them, but **every port serves the same working tree**, so checking out another branch
changes the code under all three at once. Comparing editions and comparing branches are therefore the same
gesture, and the give-away is a UI that looks a release behind on every port at once rather than on one.
Read the edition off `/api/v1/flags`, not off the port you think you started.

Verify with `npx turbo run lint --filter=web`, or `npm run lint-dev` for the whole repo. Run it from
`packages/web` or through turbo, never `npx eslint --fix <paths>` from the repo root: the root resolves a
different config, reports thousands of errors against files it should not be linting, and `--fix` rewrites
every one it touches. One such run reformatted 84 files that the change had never touched, and the only
way back was to stash the handful of intended edits, `git checkout` the package, and restore them.

## Gotchas

- **`ConfirmationDeleteDialog`'s `mutationFn` must return the request's promise (`mutateAsync`), never call `mutate`.** The dialog runs its own mutation: with `mutate` it resolves at once, closes before the request ends, shows no loading and cannot learn of a failure. It also shows no error toast of its own; a failure reaches only its `onError` prop, so the caller's hook must toast it (AI Center capability Reset was silent on both success and failure this way).
- **To style one word inside a translated sentence, translate the whole sentence and split it around a sentinel; nothing in the app uses `Trans`.** Call `t('Type {text} to confirm', { text: SLOT })`, `split(SLOT)`, and render `before`, the styled word, `after`, so translators can still move the word (see `TypeToConfirm` in `components/custom`). Concatenating two separately translated halves fixes the word order to English.
- **Flags are cached with `staleTime: Infinity`, so a setting that feeds a flag must invalidate `flagsHooks.queryKey` after it changes.** Several flags are computed from platform settings (`THIRD_PARTY_AUTH_PROVIDERS_TO_SHOW_MAP` from the Google switch, `EMAIL_AUTH_ENABLED`, `THEME`), and refetching only the platform leaves the flag stale until reload. `ssoMutations.useUpdatePlatformSso` and the appearance section both do `queryClient.invalidateQueries({ queryKey: flagsHooks.queryKey })`.
- **Gate edition-specific UI on the edition you mean, not on "not the other one".** `flagsHooks.useFlag(ApFlagId.EDITION)` is `undefined` until flags load, so `edition !== ApEdition.CLOUD` is true for a moment on Cloud and self-hosted-only copy flashes there. Write `edition === ApEdition.ENTERPRISE` (or the edition you need) so the loading state falls into the safe branch.
- **Inside a `FormField`, a plain `<Label>` + input is not wired: wrap the input in `FormControl` and use `FormLabel`.** Without `FormControl` the label points at an id the input never gets (screen readers announce nothing, clicking the label does nothing, `getByLabelText` fails), and `FormMessage` errors get no `aria-invalid`/`aria-describedby`. Adding `htmlFor` + `id` by hand fixes the label but still leaves the error unlinked. Test it with `getByLabelText` and by checking `aria-describedby` contains the error's id.
- **A web test that mocks `@tanstack/react-query` breaks at import once the component under test starts reading a `*-hooks.ts` module.** Those modules reference `QueryClient`, the partial mock doesn't export it, and the file fails to load: vitest prints `Test Files 1 failed` while `Tests N passed` still looks green, so read the `Test Files` line. Mock the hooks module the component imports (as `config-detail-save.test.tsx` does for the tier and provider hooks) instead of widening the react-query mock (#16116).
- **The SPA is hardcoded to the host root, so `AP_FRONTEND_URL`'s path prefix does not reach the frontend at all.** `index.html` carries `<base href="/" />`, there is no vite `base`, and `API_BASE_URL` in `lib/api.ts` is `window.location.origin` — origin only, path dropped. An instance served at `example.com/activepieces` therefore loads its bundle, its assets and every `/api/v1/...` call from `example.com/...` at the root, and only works because the operator's proxy exposes those at root too. The server-side subpath support (`domainHelper.getPublicUrlFromRequest`, which prepends the configured base path to advertised URLs) covers what AP *tells* clients, not what the browser *fetches* — the two do not meet. So "we support subpath hosting" is only half true: it holds for what the server advertises and for anything the browser never has to fetch. A second host escapes the constraint only if it serves no SPA at all — which is exactly why MCP consent is redirected back to the frontend base rather than served on the MCP host (see [[mcp-server]]), leaving `AP_MCP_URL` free to carry a prefix.
- **A disabled TanStack query keeps `isPending: true` forever, so a skeleton driven by it never resolves.** `enabled: false` means "has no data and is not fetching", and `isPending` only reports the first half — the spinner spins for the life of the page. Drive loading UI off `isLoading` (`isPending && isFetching`), which is false while disabled. This bites hardest on the plan-gated queries the repo requires an `enabled: platform.plan.<flag>` on: every one of them is permanently pending for a platform without the feature. Also decide what the surface shows in that state — a count rendered from `data ?? 0` reads as a real zero, when the honest answer is that the feature is not on the plan.
- **The `showcase/*.mp4` upsell videos on the CDN are all from 2024 and show the retired Admin Console.** `cdn.activepieces.com/videos/showcase/` holds seven of them (projects, templates, pieces, appearance, api-keys, alerts, flow-issues), last touched March-June 2024, and every frame is the old sidebar, the old tables and the old purple buttons. `FeatureTeaser` renders whatever `videoUrl`/`lockVideoUrl` it is handed, and the Templates locked page still passes `templates.mp4`, so a customer on the paywall watches a product that no longer exists. Do not reach for these when building an upsell surface — either reshoot or leave the video out. Pull a frame with ffmpeg before trusting any CDN asset whose name sounds right.
- **`Button` tightens its own horizontal padding when a direct child is an `<svg>`, and the animated icons defeat it.** Every size variant carries a `has-[>svg]:px-*` pair (`sm` is `px-2.5 has-[>svg]:px-2`, so 10px normally and 8px with an icon) to stop an icon button reading as over-padded. The components in `components/icons/` wrap their `motion.svg` in a `<div>` to own the hover handlers, so `has-[>svg]` never matches and any `AnimatedIconButton` silently keeps the wider padding. Two buttons meant to look alike will differ by 2px a side the moment one uses a bare lucide icon and the other an animated one, so check the computed padding before assuming a diff caused it. To match the animated width deliberately, pass `cn('has-[>svg]:px-2.5', className)` — `Button` runs `cn(buttonVariants({ ..., className }))`, so tailwind-merge drops the variant's own value rather than leaving a specificity fight with `:has()`.
- **A `packages/web` test runs in the `node` environment by default, so importing anything that touches `window` at module load fails at collection.** `vitest.config.ts` sets `environment: 'node'`; ~26 suites opt into a DOM with a `// @vitest-environment jsdom` docblock on line 1. The failure is a bare `ReferenceError: window is not defined` pointing at a *transitive* import (`embed-provider.tsx` reading `window.opener`, reached via `@/features/projects`), not at the test — so read the stack, don't hunt in your own file. Missing the docblock is why `chunk-reducer.test.ts` was red for as long as it was: CI did not run the web suite at all, so nothing surfaced it.
- **Clicking through a Radix/cmdk component in a jsdom test needs the React root mounted on `document.body`, or the click never reaches React.** `createRoot(container)` attaches React's delegated listeners to `container`, but Radix `Popover` portals its content to `document.body` — a sibling of a nested root div — so synthetic events bubble body-ward, away from the listener. Items are queryable in the DOM and everything *looks* wired: the handler simply never runs, the assertion passes vacuously, and nothing tells you. `createRoot(document.body)` puts the portal inside the root container and the same dispatch fires. Three shims are needed first, each surfacing as an unrelated-looking error: `ResizeObserver` (cmdk, at mount), `Element.prototype.scrollIntoView` (cmdk, on open), and `PointerEvent` (absent in jsdom — alias it to `MouseEvent`). **And a throw inside an event handler is not a test failure.** React error boundaries only catch render/lifecycle errors, so an event-handler `TypeError` is re-thrown outside the act() call: `expect(...).toThrow()` sees nothing, the suite reports *passed*, and the only trace is vitest's `Unhandled Errors` block after the summary — which is easy to scroll past and which a `grep` for `passed|failed` hides completely. Grep the run for `Unhandled` too, and read that block as a failure. This is exactly how a crash in the multi-select property stayed invisible to a 101/101-green suite.
- **A panel that hand-rolls its draft state gets none of the form validation the rest of the app assumes.** react-hook-form + `zodResolver` is what surfaces `formErrors.required` and friends; a `useState` draft with a Save button has no schema, so the usual mistake is to *substitute* a fallback for an empty field (`name.trim().length > 0 ? name.trim() : existing.name`) instead of rejecting it. That reads as a silent failure: the request succeeds, the old value returns, and nothing explains why. When a surface cannot use react-hook-form, derive the invalid state, render the message next to the field, and disable the submit — do not paper over the empty value. Bit the AI Center key-detail panel while its sibling connect dialog, on a zod resolver, was correct. The second failure mode is that such a draft never resyncs: seeded once from a prop, it outlives any refetch of the row it mirrors, so a mutation that changes the row without changing its `key` (the AI Center replaces a key's credentials, and the panel is keyed on the config id) leaves the draft describing the old row — phantom "unsaved changes", and a save that reverts what the mutation just wrote. Bump a version segment into the `key` at the site that performs the mutation rather than diffing props inside the panel: TanStack Query hands back a new object identity on every refetch, so a naive identity comparison discards the admin's unsaved edits on a window refocus.
- **Sonner centres its icon against the whole toast, so a two-line toast puts the icon beside the wrong line.** `[data-sonner-toast]` is a centred flex row: fine for one line, visibly wrong the moment a description wraps or carries a disclosure — the icon drifts down next to the body instead of the title. Pass `classNames: { toast: 'items-start!', icon: 'mt-0.5' }` on that toast (the icon is 16px against 13px title text, so it needs the nudge to sit on the title's baseline). The `!` is not optional: sonner ships its own stylesheet, and a plain Tailwind `items-start` loses to it. Per-toast rather than on the `Toaster`, unless every toast in the app is meant to move.
- **To see a fetch-failure placeholder in the dev app, force the branch in code — do not try to break the network.** Patching `XMLHttpRequest.prototype.open` to rewrite the path (the api client is axios, so patching `fetch` alone does nothing) works only sometimes and costs a lot of fiddling: React Query keeps rendering the last good data, so the placeholder needs a query key with no cache; a full reload wipes the patch before the app boots, so navigation has to stay client-side; and some surfaces never error at all even when the rewritten path is confirmed to 404. Temporarily flipping the branch itself — `) : isError ? (` to `) : true || isError ? (` in `DataTable`, plus the same in each hand-written list — makes every page reachable by plain URL with no timing at all. Two cautions: it proves the *rendering* and not that `isError` is ever set, and `true || x` breaks TypeScript's narrowing after the guard, so a forced early return can throw "possibly undefined" errors into the Vite overlay — force it from the caller's prop instead when that happens. Forcing the branch is often not enough on a Community instance: agents, the AI Capabilities section and the embed subdomain steps are behind route guards, edition checks and `LockedFeatureGuard`, so those have to be forced open too (`AgentsFlagGuard`'s redirect, the `edition === ApEdition.COMMUNITY` branch in `routes/platform/setup/ai/index.tsx`, `isCloud` + `locked`) before the page renders at all. Revert with a grep for `true ||` / `false &&` / `locked={false}` before finishing.
- **Run eslint on web files from inside `packages/web`, never from the repo root.** From the root the `@/` alias does not resolve, so every import reports `import/no-unresolved`, and `--fix` silently moves relative imports (`./lib/...`) above the `@/` group. Then the package's own lint fails on `import/order`. Re-run `npx eslint --fix` from `packages/web` to put them back.

- **A table that ORs a secondary query into `isLoading` can never reach its error state.** The runs table passes `isLoading={isLoading || isFetchingFlows}`, where `isFetchingFlows` belongs to the flow list behind the *filter dropdown*. While that second query is fetching or retrying, the skeleton branch wins over `isError`, so a failing runs endpoint shows spinning rows rather than the placeholder — and a failing flows endpoint traps the table there indefinitely. Gate the skeleton on the query that owns the rows, and let a secondary query resolve on its own.

- **Frontend errors go to Sentry through `lib/error-reporting.ts`, and a failed React Query fetch was structurally invisible to it.** `errorReporting.report({ error, source })` is the only entry point — it wraps `@sentry/react`, initialises lazily off the `FRONTEND_SENTRY_DSN` flag, and stamps user/project/platform, page and browser context. Its `FrontendErrorSource` union covers thrown errors (`react-error-boundary`, `route-error`, `window-error`, `unhandled-rejection`, `chunk-preload`), so it never saw a query failure: React Query stores a rejection as state rather than throwing it, unless the query opts into `throwOnError` or Suspense. `QueryCache.onError` in `app/query-client.ts` now reports every failure under the `query` source with the query hash, HTTP status and request url. Two things that path needs and the thrown-error paths do not: skip only what the app has genuinely already handled — a 401 carrying `SESSION_EXPIRED` or `INVALID_BEARER_TOKEN`, which `globalErrorHandler` in `lib/api.ts` turns into a logout and redirect. Everything else reports, including 402 and 403, because both mean the frontend fired a request it should have prevented: 402 is a query missing its `enabled: platform.plan.<flag>` guard, 403 is `PERMISSION_DENIED`/`AUTHORIZATION` slipping past `RoutePermissionGuard`/`checkAccess`. Filtering by bare status is the trap here — "4xx auth-ish" reads as expected and is mostly the opposite, and pass a `dedupeKey`, because the dedupe signature is `name:message:stack` and every axios failure shares a message, so four lists failing together would otherwise report once and hide three endpoints. Nothing reaches Sentry at all without the DSN flag, which self-hosted instances do not set.

- **`api.isApError` throws on any error that has no response.** It reads `(error.response?.data as ApErrorParams).code` — optional-chaining the `response` but then dereferencing `.code` on the `undefined` that comes back, so a network failure, a timeout, or a CORS rejection raises a `TypeError` from inside whatever error handler called it. `queryClient`'s `mutationCache.onError` calls it unguarded on every mutation error, so a mutation that fails offline crashes there rather than showing its toast. When you need the `ApErrorParams` code on a path that can see transport failures, read it defensively (`(error.response?.data as ApErrorParams | undefined)?.code`) instead of reaching for the helper.

- **`refetch()` ignores `enabled`, so a retry handler walks straight through a plan gate.** `enabled: platform.plan.<flag>` stops the automatic fetch and nothing else; a manual `refetch()` fires the request whatever the flag says. A combined retry is where this bites, because the handler usually refetches every query the section draws from: on Connections the overview's Needs-attention retry called `refetchGlobal()` unconditionally, so a platform without Global Connections that hit Retry on an unrelated *project*-connections failure sent a guaranteed 402 to the gated endpoint. Nothing showed, since the error state was already gated on the flag, so the only trace is the failed request and the Sentry report behind it. The fix that generalises is to retry only what actually failed (`...(isError ? [refetch()] : [])`) rather than everything the section reads: the already-gated error flag then keeps the gated refetch unreachable, and a healthy query stops being re-requested because its neighbour broke. Read the repo's `enabled: platform.plan.<flag>` rule as covering both halves, the declaration and every hand-written refetch.
- **`isLoading` is false while a failed query is retrying, so a retry button gated on it looks dead.** React Query sets `isLoading = isPending && isFetching`; once a query has errored its status is `error`, not `pending`, so `refetch()` raises only `isFetching`. Any skeleton or spinner keyed on `isLoading` therefore never fires on a retry — the user clicks and nothing visibly happens until the request resolves. `DataFetchErrorState` handles this itself rather than pushing `isFetching` out to every caller: it awaits whatever `onRetry` returns and drives the `Button`'s own `loading` prop, which is also the only option that works on the surfaces that have no skeleton branch to reuse. A retry wired to `invalidateQueries` needs the promise returned (`return Promise.all([...])`), or the spinner flashes for a single tick.

- **`useWarnBeforeLosingChanges`'s `standDown` ref has to be set *after* the destructive request succeeds, not before it.** `components/custom/leave-without-saving.tsx` guards a dirty panel against navigation and `beforeunload`; `standDown` is how a deliberate exit (deleting the thing being edited) avoids prompting on its own way out. Setting it before `await`ing the delete disarms the guard for the whole request, so a refresh or tab close mid-flight discards the draft silently — and if the delete then fails, the row is still there and the edits are not. A `finally` that restores the ref does not help: the window has already passed. The ordering only works if the mutation and the navigation are separable, so the panel can stand down between them — keep the delete prop to the mutation alone and let the panel call its own `onBack`, rather than handing it one callback that does both.
- **`Button`'s `keyboardShortcut` does not stop firing while the button is loading, and its listener lags a render behind.** Two separate gaps in `components/ui/button.tsx`. The element gets `disabled={disabled || loading}`, but `useKeyboardShortcut` was handed the raw `disabled` prop, so a button mid-request still ran its handler on ⌘/Ctrl+key — latent for years because every caller before the AI Center Save button was a non-loading `variant="outline"` button. Fixing that still leaves a window: the listener is registered in a passive effect, which runs after paint, so between a click and the effect re-running the old closure keeps `disabled=false`. Anything whose handler must not run twice (a mutation) needs its own guard set synchronously inside the handler — a ref, not a `disabled` prop — because no prop can close an effect-timing window. Separately, `Shortcut` renders in `text-gray-11`, which is invisible on a filled button; `Button` now tints it per variant, so pass nothing.
- **Exported types and constants belong at the *end* of the file**, after the components and logic. Reading a file should start with what it does, not its type declarations.
- **The web has two independent "something went wrong" surfaces, and they cover different failures.** `GlobalErrorBoundary` (`app/components/global-error-boundary.tsx`) is a React error boundary: it catches *render* crashes and replaces the page with a reload/go-home fallback. It structurally cannot see a React Query failure — a failed query is stored as state, not thrown during render, unless the query opts into `throwOnError` or Suspense. Nothing global covers that async gap any more: a failed primary query is reported by the surface itself, through `DataFetchErrorState`. The two landed independently (the query surface first, in #12476 for tables; the boundary later, in #13743) and were never calibrated against each other, so for a long stretch a single 404 got a *blocking modal with raw JSON* while an actual app crash got a friendly reload button. Keep that ordering right: a failed fetch on a page that still renders is an in-place placeholder, a dead render tree is the full-page fallback. A modal is only correct when the error payload is something the user must read and copy — flow publish showing the trigger piece's stderr (`flow-hooks.tsx`) is the one case that still earns `ApErrorDialog`.
- **`FriendlyErrorView` is the one renderer for a `FriendlyPieceError` — reach for it before hand-rolling a message line.** `app/builder/data-display/friendly-error-view.tsx` already turns the parsed payload into a status-keyed headline and hint (401 → "Authentication failed" + "Try reconnecting the account…"), an `HTTP {status}` badge, a labelled message block that prefers `apiMessage` over `message`, and its own `Technical Details` disclosure; it is wired to the run-details and test-step panels. For an auth failure the status-keyed *hint* is the part that actually prevents a misdiagnosis — naming whose credentials to fix beats quoting the third party's own sentence, which is what made a rejected Linear key read to a customer as their Activepieces session expiring (Pylon 5833). Three things make it non-trivial to drop into `ApErrorDialog` and all three are local fixes: it renders a second `Technical Details` next to the dialog's own, its disclosure shows `raw ?? payload` so it drops `standardOutput` (the piece's stderr, often the useful half of a failed trigger enable), and `useChangeFlowStatus` has only `flowId` so `pieceDisplayName` falls back to "What the service said". Fix those rather than growing a parallel renderer — a second one means the `message`-is-JSON trap (see *building pieces*) has to be fixed twice.
- **User feedback for a mutation belongs in the hook's `useMutation` options, not in per-call `mutate(vars, { onError })` callbacks.** `MutationCache.onError` in `app/query-client.ts` skips its "Something went wrong" toast only when the *options* carry `onError`, and TanStack drops per-call callbacks once the observer unmounts (dialog closed mid-request) or a newer `mutate` replaces the call. A page that toasts per call looks fine in the happy path and goes silent exactly when the request fails late. Keep per-call callbacks for UI only (close the dialog, move focus).
- **`api.extractServerErrorMessage(err, fallback)` almost never shows `fallback`.** It returns the raw Axios message ("Request failed with status code 500", "Network Error") before falling back, so translated copy is unreachable for HTTP failures. Use `api.serverErrorMessage(err) ?? t('…')`: the server's `params.message` when there is one, your copy otherwise.
- **`eslint --fix` on a `packages/web` test will rewrite a plain DOM assertion into a jest-dom matcher that does not exist here.** The `jest-dom/*` rules are on, but `@testing-library/jest-dom` matchers are not installed, so `--fix` turns `expect(el.hasAttribute('disabled')).toBe(true)` into `expect(el).toBeDisabled()`, and the test then fails at runtime with `Invalid Chai property: toBeDisabled`. Sibling suites handle it with a file-level `/* eslint-disable jest-dom/prefer-in-document, jest-dom/prefer-enabled-disabled */` and assertions on `getAttribute('data-disabled')` (Radix sets it) rather than the `disabled` attribute, which `prefer-to-have-attribute` also rewrites. Run eslint on the test file *before* vitest, not after, so a passing run is the one you commit.
- **Stubbing Radix `Select` in a jsdom test: render each `SelectItem` as a button that calls the real `onValueChange`, and never match a click by button text alone.** The component under test passes `onValueChange` to `Select`, so a stub that captures it in a `vi.hoisted` box and has `SelectItem` call it with its own `value` gives you the real state update without Radix's portal, pointer and `ResizeObserver` machinery. The trap is finding the button afterwards: the dropdown items and the UI they control often carry the same words (a Text/Image type picker next to chips whose badge also reads "Text"), and a `textContent` match takes whichever comes first in the DOM — silently clicking the dropdown item and asserting a no-op. Match on something structural (`button[title="Model Type"]` inside the chip) and give each helper a name that says which one it clicks. Also note `expect(value, 'message')` — valid vitest — is rejected by the repo's `vitest/valid-expect` lint rule, so put the identifying detail in the helper name rather than the assertion message.

- **`DialogDescription` renders a `<p>` (Radix `Primitive.p`), so block content in the description slot is invalid nesting.** `main` already puts a `<p>` inside it, which is one React `validateDOMNesting` warning; adding a `<div>` wrapper takes it to two (measured by rendering the dialog under jsdom and counting `console.error` calls). No visual break — this is a Vite SPA with no SSR, so nothing re-parses the HTML — but it does mean the description slot is the wrong home for a bordered, badged panel. Put that in the dialog body and leave the description a sentence.

- **An error state on the wrong query is worse than missing it.** On an auxiliary query it accuses a page that was working fine; on the primary query, omitting it leaves the user staring at an empty table with no explanation. This surface has been rebuilt twice: a blocking modal with raw JSON (`showErrorDialog`), then a global toast keyed on `meta.errorToastEntity`, and now an in-place placeholder and nothing else. Each move was driven by the same report — a failed fetch reading to customers as deleted data — and the toast went because it either duplicated the placeholder or, on its own, left the empty table unexplained.
- **A `data ?? []` default turns a failed query into an empty state, and nothing else will catch it.** Defaulting the data away means `isError` is the only remaining evidence the fetch failed — the body just renders "nothing here", which is the data-loss illusion this whole surface exists to prevent, and since the global toast was removed there is no second line of defence. Branch on `isError` *before* the empty state, always. `api.isApError(error, ErrorCode.X)` is how you tell an access denial apart from a network blip — note it reads the *response body's* `code`, so it needs the server's `ActivepiecesError` code, not an HTTP status.
- **A ref assigned during render (`const ref = useRef(x); ref.current = x`) is stale inside socket/event callbacks.** The value only advances when React commits a render, so two events handled before that commit both read the same base — a read-modify-write (merging a step into `run.steps`) silently drops the earlier event. Read the zustand store directly instead: `useBuilderStore().getState()` (`app/builder/builder-hooks.ts`) always returns current state. Bit the test-flow widget's progress merge, PR #14453.
- **Builder overlays share one stacking context, so a big `z-` wins over everything — including portalled popovers.** Nothing between an overlay in the canvas panel and `<body>` creates a stacking context (the middle panel is `relative` + `z-auto`; `ResizablePanel` sets only flex/overflow), so a canvas child's `z-index` competes directly with Radix portals. The working ladder: canvas `z-30` (opaque `bg-gray-2` — anything below it is invisible), header and floating corner chrome `z-40`, data selector / canvas controls / popovers `z-50`. That is why the powered-by note at `z-10000` painted over the piece selector.
- **`flowStructureUtil.findPathToStep` is O(n²) on its own, so calling it once per step node makes the canvas O(n³).** It walks `getAllSteps(trigger)` and then calls `getAllSteps(step)` *again* for every step to test containment. One call is fine; a call inside a per-node hook is not, and every step node on the canvas runs its own copy of the run-details hooks (`ApStepNodeStatusInRun` → `useStepOutputInRun` → `useBatchLogs`). Memoising on `[trigger, stepName]` does not save you — the trigger object is new after every flow operation, so the whole grid recomputes on each edit, whether or not the flow has a run or a batch step. Measured on a straight-line flow: 100 steps 31.8ms, 200 steps 173.7ms of blocking main-thread work *per edit*. The fix is ordering, not caching — filter to the few steps you care about **before** the containment test (`getAllSteps(trigger).filter(type === X).filter(isChildOf)` instead of `findPathToStep(...).filter(type === X)`), which took the same measurements to 0.7ms and 2.3ms. Before adding any tree walk to a per-node hook, check what it costs times the node count.
- **The flow "download as image" only captures `.react-flow__viewport`.** `flowScreenshotUtils` (`flow-canvas/utils/flow-screenshot-utils.ts`) clones that one element into an SVG, so anything outside it — the dot-grid background, the powered-by note, canvas controls — is absent unless handled explicitly. Two seams: mark in-viewport chrome you want *omitted* (step chevron, badges) with `data-flow-screenshot-exclude`; anything *outside* the viewport you want *included* has to be redrawn onto the composited 2D canvas in `composeImageWithCanvasBackground` (that's how the background dots and the powered-by mark get there).
- **The piece-selector popover sizes its list to fit the viewport, but the fit needs slack or it clips against the screen edge.** `useAdjustPieceListHeightToAvailableSpace` (`features/pieces/utils/piece-selector-utils.ts`) measures the room above vs. below the trigger, renders the list on whichever side has more, and clamps the height to `[MIN 100, MAX 300]`. That measurement alone still let the popover butt flush against the top/bottom of the builder on short screens (the Radix content + its own padding/offset overran the raw available space). The fix is a `PIECE_SELECTOR_CLIPPING_THRESHOLD` (20px) subtracted from the computed `listHeight` at the call site in `builder/pieces-selector/index.tsx`, leaving a margin so the popover never touches the viewport edge. If it clips again, that constant — not the min/max clamp — is the lever.
- **`Alert`'s `warning` and `destructive` variants ship without a background tint, so a tinted banner has to add one at the call site.** `components/ui/alert.tsx` gives `primary` and `success` a step-3 fill (`bg-accent-3`, `bg-success-3`) but leaves `warning` transparent and `destructive` on `bg-panel`, which reads as a plain panel and sets no border colour either. A banner that needs to look like a banner passes `bg-warning-3` / `bg-danger-3 border-danger-7` itself — that is what the credits usage alert does. Don't "fix" it in the variant without looking: eight-plus existing warning alerts sit inside dialogs on card backgrounds and were designed against the untinted look.
- **`npx turbo run serve --filter=web -- --mode=cloud` cannot do OAuth2 connections.** The provider redirects to `cloud.activepieces.com` after sign-in instead of your local frontend. Use API-key or basic-auth connections, or run a fully local backend.
- **`--mode=cloud` also floods the terminal with `[vite] http proxy error: /ingest/... ETIMEDOUT 127.0.0.1:3000`.** The mode only redirects the API (`API_BASE_URL` → `https://cloud.activepieces.com` in `lib/api.ts`); PostHog still posts to the *relative* `api_host: '/ingest'` (a same-origin reverse proxy so ad blockers don't drop ingestion — `providers/telemetry-provider.tsx`, mirrored in prod by the `fastifyHttpProxy` in `server.ts`). Vite proxies `/ingest` to `127.0.0.1:3000`, which isn't running. Cloud flags also turn telemetry *on* (`TELEMETRY_ENABLED` + `EDITION=cloud`), unlike a local CE backend — so posthog-js keeps polling `/ingest/flags` and flushing `/ingest/e` every few seconds. Harmless, but note the same setup sends real dev clicks to production PostHog whenever `/ingest` does resolve; the clean fix is skipping `posthog.init` under `import.meta.env.DEV`.
- **A motion `layout` animation fired from inside a mutation's `.then()` fast-forwards and reads as a jump — defer the state write two frames.** Motion measures the FLIP offset at the commit that reorders the DOM, then tweens from the first animation frame. When the write happens synchronously after a mutation resolves, that frame arrives tens of ms late (the same commit is refetching a table, tearing down a dialog, re-rendering the page), motion sees a huge time delta and skips most of the tween: a rail row travelling 228px was measured collapsing to 103px in one 6ms frame, then limping through 13 frames. Wrapping the write in `requestAnimationFrame(() => requestAnimationFrame(write))` lets the mutation's re-render settle first, and the same interaction then gives up only 7.6% on the first frame and eases properly. Two traps when checking this: driving the write yourself from a console eval runs on a *quiet* main thread and always looks smooth, so it proves nothing — reproduce through the real UI action; and a route change in the same tick (creating a flow navigates straight to the builder) interrupts the projection outright, which no deferral fixes.
- **`projectCollection` runs on its own private `QueryClient`, fetches once, and never refetches — so any server-derived field on `ProjectWithLimits` is frozen at page load.** `features/projects/stores/project-collection.ts` builds the collection with `queryCollectionOptions({ queryKey: ['projects'], queryClient: collectionQueryClient })`, where `collectionQueryClient` is a `new QueryClient()` local to that module, *not* the app's. So `invalidateQueries(['projects'])` from anywhere else is a no-op, there is no `refetchOnWindowFocus`, and a field like `analytics.lastFlowUpdated` keeps its page-load value until something calls `projectCollectionUtils.refetchProjects()`. Two ways to keep such a field live, and the choice matters: `refetchProjects()` refetches every project (fine for a rare event like a piece-set change — its four existing callers — but wrong on a hot path such as the builder's per-edit autosave), or `projectCollection.utils.writeUpdate({ ...project, ... })` patches the row locally with no request, letting the next natural refetch restore server truth. Note `projectCollection.update()` is a *different* thing: it routes through `onUpdate` and POSTs, and its field allowlist silently drops anything not named there. **A local patch of a server-side *aggregate* also has to reproduce that aggregate's semantics, or it desyncs in two directions.** `analytics.lastFlowUpdated` is a `MAX(flow.updated)` over living flows, so: stamp the value from the mutation response, never `new Date()` (a skewed browser clock reorders against every server-supplied sibling); write only when the incoming value is *newer*, because concurrent mutations on one project resolve out of timestamp order — builder autosaves, and the bulk paths in `use-automations-mutations.ts` that fan out `flowIds.map(id => flowsApi.update(...))` — and an unconditional write lets a late older response move the row backwards; and when the aggregate can *decrease*, a local patch cannot express it at all, so refetch instead (deleting the newest flow lowers the MAX to a value only the server knows — cheap there because deletes are user-initiated, unlike autosave). And if the patch is *deferred* at all — it is here, by two frames, so the reorder animation does not fast-forward — a refetch that lands inside that window must invalidate it, or the pending write reapplies the pre-refetch value over the authoritative one and the newer-than guard happily waves it through; stamp each scheduled write with a generation the refetch bumps.
- **A query collection reports a failed fetch as *ready*, so `useLiveQuery().isError` is never true.** `@tanstack/query-db-collection` calls `markReady()` in its error branch, and `useLiveQuery` sets `isError` only for collection status `error`: a failed load looks exactly like an empty collection (an empty table, or an edit page that treats the row as deleted). Read the failure from the collection's own `QueryClient` instead, as `eventDestinationsCollectionUtils.useAll` does (`useSyncExternalStore` over `getQueryCache().subscribe`, reading `getQueryState(key)?.status === 'error'`). For a retry button use `collection.utils.refetch()`, which resolves on failure; `utils.clearError()` refetches with `throwOnError` and rejects.
- **Never format `packages/web` with bare `prettier` — the web formatting contract lives in the eslint rule, not in `.prettierrc`.** Root `.prettierrc` sets only `singleQuote`, while `packages/web/.eslintrc.json` configures `prettier/prettier` with `trailingComma: "all"`, `printWidth: 80`, `tabWidth: 2`. The repo pins prettier **2.8.4**, whose default `trailingComma` is `es5` — so `npx prettier --write` on a web file silently **strips the trailing commas out of every multi-line function call it touches**, including lines you never edited, turning a 15-line change into a 130-line diff that reviewers have to read past. Format with `npx turbo run lint --filter=web --force -- --fix` instead; that is also what `npm run lint-dev` runs. If you already ran bare prettier, `git checkout` the file and redo the edit rather than trying to hand-restore the commas. **And `lint-dev` repairs rather than reports, so a green run is not a verification on its own.** It runs `--fix`, so running it *after* `git commit` writes the correction into the working tree and leaves the broken content in the commit you push: the terminal says 33 tasks successful while CI fails on the pushed code. Run it before staging, and treat `git status` immediately afterwards as the real check. Clean tree means lint found nothing; a modified file means it just fixed something that is not in your commit.
- **`packages/web`'s lint script only globs `src/**`, so nothing under `packages/web/test/` is ever linted** — not by CI's `lint` job, not by `npm run lint-dev`. Running `npx eslint 'test/**/*.{ts,tsx}'` from `packages/web` today reports 21 errors nobody has seen, so a new web test needs a manual eslint pass or it ships with errors. Most common trap: `testing-library/render-result-naming-convention` fires on any local helper whose name merely *starts with* `render` even when testing-library is not involved — renaming `render` to `renderTabText` does not silence it, only a name that doesn't begin with `render` does. **The trap compounds with the rule that sends tests there.** `packages/web/CLAUDE.md` requires a test under `packages/web/test/`, mirroring its source path, so tests do not ship in the app bundle — but `test/` is exactly what lint does not glob. So the moment you move a test out of `src/`, it leaves the lint pass, and `npx turbo run lint --filter=web` (or `--fix`) then reports **0 errors for a file it never opened**. Seen in one session: two `prettier/prettier` errors were live in a test at `src/...`, the file was moved to `test/...`, the next `lint --fix` went green, and both errors were still there — `npx eslint 'test/**'` from `packages/web` found them. Lint the moved path directly after any such move; a green turbo run is not the check. Note the conventions pull against each other: five test files still sit under `src/` (`src/lib/test/`, `src/app/builder/data-selector/`, `src/features/projects/stores/`), which is why a new test tends to land there by precedent — those five *are* linted, which is the only reason nobody has noticed.
- **A settings page gets its always-visible Save bar by passing `footer` to `CenteredPage`, and passing it switches the whole layout mode.** Without `footer` the page is the original `py-6` block that scrolls with the dashboard container; with it, the page becomes `h-full flex flex-col`, children move into a `ScrollArea`, and the footer pins below — so the Save button stays reachable however long the settings list grows. The wrapper around it has to be a flex child with a definite height (`flex flex-1 flex-col min-h-0` on the `<form>`), because `PlatformLayout` hands the route a `flex-1 overflow-auto` container and an `h-full` that cannot resolve just collapses. Reach for the prop rather than hand-rolling a second page shell; the six pages that omit it render byte-identically.
- **A `DataTable` row that spans all columns must count `table.getVisibleLeafColumns()`, never the authored
  `columns` array.** The two differ: the component prepends a select column and appends an actions column,
  and TanStack can hide others, so the authored length overshoots what the header renders. The loading,
  error and empty rows all render one `TableCell colSpan={...}`, and when that span is too high the table
  gains a column with no header. Because the table is `table-layout: fixed`, that phantom column is handed
  the leftover width, so on the platform Projects table the header covered 720px of a 1725px table and
  stopped two thirds of the way across, then looked fine the moment a row arrived, because real per-column
  cells override the phantom. It hid at laptop widths where the declared sizes were close to the container
  and only looked broken on a wide screen. Fixed in `components/custom/data-table`; the trap is reaching
  for `columns.length` again in a new spanning row.

- **Platform admin screens come in two alignments, and it follows the section rather than the page.**
  A settings screen is a centred `mx-auto max-w-[40rem]` column, a table screen is full width at the
  container's inset, and that split predates the redesign: on `CenteredPage` the title lived inside the
  centred column while `DashboardPageHeader` pages had a full-width one. Hoisting the title into a shared
  shell therefore has to carry the alignment with it, or the title lands at the inset while the content
  centres. `Security` is why the flag cannot live on the page: its API keys and Event streaming sections
  are centred lists while Secret managers and Audit logs are full-width tables, so the header has to
  re-align as you move between sections of one page.

- **`DataTable` carries its own spacing, so a table page wants no page padding.** It brings the toolbar,
  the filter row and the pagination footer with their insets already applied, and it is built to run edge
  to edge inside its container. Wrapping one in `px-6 pt-6` therefore pushes the table in from its own
  controls and opens a dead band between the page header and the toolbar. That padding belongs on the
  surfaces that have no spacing of their own, a card grid or a form, and not on a table. Bit the Projects
  and Users pages during the admin alignment pass, where the table was inset while its own toolbar was not.

- **Those two shells carry the page's layout, not just its header, so removing a header moves the content.**
  `CenteredPage` supplies `mx-auto` centring and a 40rem column; `DashboardPageHeader` supplies nothing, so
  its pages run flush to the container edge. Take the header away to hoist the title somewhere shared and
  the body keeps whichever of those it had: a `CenteredPage` body ends up centred hundreds of pixels right
  of the new header, a table body ends up flush left of it, and the page reads as broken without any one
  file looking wrong. Check the left edge of every converted page against its heading, not just that the
  heading renders.

- **Platform admin has two page shells that disagree, and one settings-row primitive that got cloned five times.** `DashboardPageHeader` (over `components/custom/page-header.tsx`) is `sticky top-0 z-30`, `text-base font-semibold`, full width, and respects `embedState.hidePageHeader`; `CenteredPage` is `max-w-[40rem] mx-auto py-6`, `text-xl font-medium`, and follows itself with a `Separator`. Twelve admin pages take the first, six the second, and four (billing, usage, embed, AI Center) hand-roll their own `h1` instead. Nothing marks which a new page should use, so the choice has been made per-page by whoever copied the nearest neighbour. Same story one level down: `components/custom/item.tsx` (`Item` / `ItemGroup` / `ItemTitle` / `ItemDescription` / `ItemActions`) is the intended label-left, control-right settings row and has nine call sites, eight of them in platform admin, with SSO the clearest reference. But five local re-implementations sit beside it and reuse none of it: `BillingSection` in `billing/index.tsx`, `HealthCard` plus `HealthRowItem` in `infra/health/components/system-health-tab.tsx` (a near-clone of `Item` + `ItemGroup` + `ItemSeparator`), `SectionHeader` under `setup/ai/components/`, an open-coded `Item variant="outline"` in `setup/general/danger-zone-section.tsx`, and `AutoIncludePill` in `piece-set-details-page.tsx`. Reach for `Item` before writing a row, and check whether the clone next to you is one of those five. The real outlier is `appearance-section.tsx`, which is a vertically stacked `FormItem` form rather than a row list, so it is the one file a standardisation pass has to decide about rather than mechanically convert.
- **`packages/web/public/locales/en/translation.json` contains duplicate keys, so no JSON tool may rewrite it — edit it as text.** `agentMoveLosesConnections`, `No projects yet`, `All projects` and `Model` each appear twice today. Any parse-and-dump round-trip (Python's `json`, `jq`, a formatter) silently keeps only the last of each pair and drops the rest, and will additionally unescape every `\uXXXX` sequence in the file — one such round-trip to add a single key produced a 36-line diff with a key deletion buried in it. Add or rename a key with a targeted string replacement and check `git diff --stat` says 1 insertion.
- **Resolving a `translation.json` merge conflict is where that rule is hardest to keep and most worth keeping.** Both sides append to a flat map, so any long-lived web branch conflicts here, and the obvious resolution is to parse both sides and dump the union. That loses the duplicates and escapes exactly as above. It also has a three-way trap of its own: keeping every key that is in *ours* resurrects the keys main **deleted**, because our side never removed them either. Merge as main's bytes plus only the keys our side actually added (`in ours, not in the merge base`), appended as text before the closing brace, then confirm `git diff origin/main` is purely additive. Anything else and a reviewer sees deletions in a file they expected to grow.
- **The "New translation files" sync can delete `en` keys that are still in use.** #16370 pruned 361 keys and took `"Couldn't load {key} models"` with them, though the Tiers page calls it as `t("Couldn't load {key} models")`: keys written in double quotes (the usual form when the key holds an apostrophe) slip past whatever decides a key is unused. After merging such a sync, check that every `t('…')` / `t("…")` literal in your changed files is still a key, and add missing ones back as text. Keys that reach `t()` only through a variable (a kind-to-key map, a zod message in `core/shared`) are pruned the same way, because the extractor only keeps keys it sees in a literal `t('…')` or `translationKey('…')` call (it also scans `core/utils/src/lib/form-errors.ts`): put zod messages in `formErrors` wrapped in `translationKey`, and give a dynamic key a literal `t('…')` call.
- **`AllowOnlyLoggedInUserOnlyGuard` calls its hooks after two early returns, and the linter only lets it.** `react-hooks/rules-of-hooks` does not flag member-expression calls, so `platformHooks.useCurrentPlatform()` / `flagsHooks.useFlags()` sail past it — but add a bare `useSomething()` there and the rule fires, correctly: `isLoggedIn()` can change between renders, so those calls really are conditional. Anything new that needs to run once a session is authenticated belongs in a null-rendering component placed inside the returned `<SocketProvider>` subtree, which mounts only after the guard passes. That is why automatic trial activation is `<AutomaticTrialActivation />` and not a hook.
- **The layering is lint-enforced, not just a convention.** `packages/web/.eslintrc.json` has an `import/no-restricted-paths` zone making the codebase unidirectional: `src/app` may import `src/features`, and both may import `src/lib`/`hooks`/`components`/`types`/`utils` — never the reverse (the one exception is `app/query-client.ts`). So a hook that a public route needs belongs in `src/lib`, but anything rendering a feature's components has to live in that feature; you cannot keep the pair in one `lib` file. It fails as an `import/no-restricted-paths` **error**, not a warning, so it blocks lint.
- **Arbitrary Tailwind values for type, tracking and radius get sent back in review — `packages/web` uses Tailwind v4's stock type and radius scales.** There is no `tailwind.config.js`; the theme lives in the `@theme` block of `src/styles.css`, which overrides neither font sizes nor radii. So `text-[13px]`, `tracking-[-0.025em]` and `rounded-[11px]` are not just style nits — they sit *between* real tokens and drift the page off the scale. Map them: 10–12.5px → `text-xs`, 13–13.5px → `text-sm`, 15–15.5px → `text-base`; negative tracking → `tracking-tight`, uppercase-eyebrow tracking → `tracking-wide`/`wider`; any `rounded-[5–7px]` → `rounded-md`, `rounded-[8–10px]` → `rounded-lg`, `rounded-[11–13px]` → `rounded-xl`. **A colour handed over as a hex is usually a step, and hardcoding it breaks dark mode**: every step but the brand solid is rebound in the `[data-theme='dark']` block, so a light-mode lavender hardcoded as hex sits under dark-mode text unchanged. Match the hex to the nearest step (a pale lavender is `accent-2` or `accent-3`) rather than reaching for `bg-[#...]`; see *design-system/colour*. Layout constraints are the exception and stay arbitrary — `max-w-[628px]` for a reading measure or `lg:w-[344px]` for a sidebar have no token equivalent and are idiomatic. Fractional spacing (`size-5.5`, `size-8.5`, `size-13`) is valid in v4 and beats `size-[22px]`, but **only at half-steps** — v4 generates `.5` and whole numbers, so a finer fraction like `ml-3.9` produces no rule at all and the property computes to `0`, with no build error and no lint error to say so. If a measured value falls between half-steps, either derive it from the geometry and round to the nearest real step, or use the arbitrary value; never invent a decimal and assume it took. Read the computed style back in the browser rather than trusting the class name. Neither eslint nor `tsc` catches any of this, so it only ever surfaces in review — the mapping is written up in the *Tailwind / Styling* section of `packages/web/AGENTS.md` so agents meet it before writing the class. Above 15.5px there is no px mapping, because heading sizes are a per-surface decision: copy the token the neighbouring heading on the same page already uses (a `text-[22px]` page heading becomes the `text-xl` its sibling section headings use) rather than rounding to the closest number.
- **`npx prettier --check` lies about `packages/web` — it flags files nobody has touched, so never treat it as a gate.** Prettier is not in any CI workflow, and the root `.prettierrc` is a single `{"singleQuote": true}` while the resolved binary is prettier **2.8.4**, whose `trailingComma` default is `es5`. The checked-in code is formatted by prettier 3 (via the editor / eslint integration), which defaults to `all` — so every multi-line call with a trailing comma reads as a "code style issue". Running `--check` on a file straight out of `git show HEAD:` reproduces it. If you want to know whether your own edit is formatted, diff `npx prettier <file>` against the file and check the hunks are yours; the pass/fail verdict is meaningless. `npx turbo run lint --filter=web` is the real gate.
- **A date test with hardcoded `Z` fixtures is a false green — CI runs UTC, and both `dayjs().isSame(x, 'day')` and `formatUtils.formatDate` are *local*.** Freezing the clock with `vi.setSystemTime(new Date('…Z'))` and then asserting against a literal `'2025-09-15T00:30:00Z'` only holds where local time is UTC. `grant-utils.test.ts` on [#15079](https://github.com/activepieces/activepieces/pull/15079) was 3/3 green in CI and on `TZ=UTC`, 1 failed on `TZ=America/New_York` (`00:30Z` is the *previous* local day, so "Active today" flips to "Last used Yesterday"), 2 failed on `TZ=Pacific/Honolulu` (the second being `formatDate` rendering `Aug 11` where the test asserted `Aug 12`). Nobody in the Americas can run the suite clean, and nothing in CI will ever tell you. Derive every fixture from the frozen clock instead of writing a literal — `dayjs(NOW).startOf('day').add(30, 'minute')`, `dayjs(NOW).subtract(34, 'day')` — and assert with the same local formatter the code uses (`earlier.format('MMM D')`), so fixture and assertion move together in any zone. Check any new date test with `TZ=America/New_York` and `TZ=Pacific/Honolulu` before pushing; those two straddle UTC on both sides and catch it. The production `isSame(…, 'day')` is *correct* — a user's "today" is their own day — so the bug is always in the test, never in the formatter.
- **`ConfirmationDeleteDialog`'s `entityName` is a required prop that renders nowhere unless you also pass `showToast` — 25 of its 30 call sites compute a label and throw it away.** `components/custom/delete-dialog.tsx` mentions `entityName` three times: the prop type, the destructure, and one `toast.success(t('Removed {entityName}', …))` sitting inside `if (showToast)`. `showToast` is optional and there is no default, so every caller that omits it (or passes `false`) gets no toast and no other use of the value. The dialog body renders `title` and `message` only, so the confirmation never names what is about to be deleted. `project-member-card.tsx` builds `` `${firstName} ${lastName}` `` for nothing; `api-keys/index.tsx` passes `t('API Key')` for nothing. Nothing catches it — the prop is required, so TypeScript is satisfied, and lint has no opinion. Caught on [#15079](https://github.com/activepieces/activepieces/pull/15079), where it also made a newly added `revokedGrants` ICU plural rule unreachable in every locale — a dead translation key that `i18n:extract` will happily keep regenerating. When you want the name on screen, interpolate it into `message` yourself (`t('Revoking {entityName}. …', { entityName: label })`); passing `entityName` alone does nothing. Before adding a translation key for a dialog label, grep for where the prop you are feeding actually renders.
- **An alpha wash over white is far lighter than the colour it names, so a mock's flat grey slab is not what an opacity class renders.** A neutral at 40% over a white card resolves to a shade nobody would call grey. This matters when a design review compares a mock to the app: the MCP Pieces action panel *looked* like low-contrast text on a grey ground in Paper, while the shipped panel was already near-white and its real contrast problem was elsewhere (10px labels, a faint count ≈ 2.3:1). Resolve the alpha before concluding anything about contrast, and prefer an opaque step, which renders the same in the mock and the app. For a *tinted* pill or frame, reach for the `Badge` variants (`destructive` / `warning` / `success` / `info` in `components/ui/badge.tsx`) — each is a step-3 fill, step-11 ink and step-7 border that holds in both themes with no `dark:`.
- **Two everyday building blocks carry a hidden per-instance cost, so a long list gets expensive well before anyone notices — and `VirtualizedList` only helps if the list has a scrollable ancestor.** `TextWithTooltip` registers its own `window` resize listener and does a `scrollWidth`/`clientWidth` layout read per instance (`components/custom/text-with-tooltip.tsx`), and `PieceIcon` wraps every logo in a Radix `Tooltip` (`features/pieces/components/piece-icon.tsx`). A row using one icon and two tooltips therefore costs an image fetch, a tooltip root and two resize listeners; the MCP Pieces list hits ~740 rows behind its "Show N more" button, which is a thousand-plus listeners from one click. Reach for `components/ui/virtualized-list.tsx` (already on `@tanstack/react-virtual`) rather than rolling one: its `virtualizeThreshold` defaults to 100 so a short list keeps its plain inline render, and it measures rows with `measureElement`, so variable heights work. The prerequisite is that `findScrollParent` locates an `overflow: auto|scroll` ancestor or a Radix `data-slot="scroll-area-viewport"` — dashboard pages get one from `app/components/project-layout` — because with no scroll element the virtualizer keeps its seeded viewport and never responds to scrolling. Note also that virtualization does nothing for a *re-render* storm: deriving rows in the render body (filter + sort + fresh objects) and un-memoised rows re-do that work on every keystroke, which is a `useMemo`/`memo` problem, not a windowing one.
- **Virtualizing an existing list silently kills every `:last-child` style on its rows.** `VirtualizedList` wraps each row in its own absolutely-positioned element, so a row that was one of many siblings becomes an only child — `last:border-b-0`, meant to drop the final separator, then matches *every* row and removes all of them. Nothing errors and the list still renders; the borders are just gone. Its non-virtualized branch wraps items in fragments, which create no DOM, so `:last-child` keeps working below the threshold and the two paths disagree — the bug appears only once the list crosses 100 items. Make the separator explicit (pass the row its index or an `isLastRow` flag) before wrapping an existing bordered list, and check the same styles for `:first-child`, `:nth-child` and sibling combinators like `space-y-*`.
- **A `removeQueries` filter written as a whole key silently stops matching the moment that key is reshaped, `gcTime: 0` does not save you, and the flow key is not the only cache the builder reads.** In-builder import bounces `/flows/:id → /flow-import-redirect/:id → /flows/:id` so the builder remounts, and the guard purges the flow's cache on the way through. For 0.84.0–0.90.3 the filter was built from a helper that returned a different shape than the builder page's literal key, so it matched nothing: the import persisted server-side and the canvas kept rendering the pre-import flow (GIT-1863, Pylon 5914). #13178 had fixed it once and #13086 reshaped the page key six days later inside the same 0.84.0 release; #15142 restored the match by accident in 0.90.4. Do not assume the builder's `gcTime: 0` makes the purge redundant: collection is scheduled on a `setTimeout` after the last observer unmounts, so the remount in the same tick reads the stale entry first. A fresh canvas is also not enough: the import rewrites the draft in place, so its version id survives and so do `['sampleData', versionId]` / `['sampleDataInput', versionId]`, and `BuilderStateProvider` copies sample data into its store once through `useRef`, so the background refetch never reaches it and the store keeps the pre-import sample data. Most of the UI hides it, because the server clears `lastTestDate` on every imported step and the test panel and advanced data selector gate on that field; it leaks only where nothing checks `lastTestDate`, such as the friendly data-selector view for a primitive or array output and the formula preview in step inputs. `flowHooks.removeFlowFromCache` is the one owner of the purge: it removes the `['flow', flowId]` prefix and the sample data of every cached version of that flow. Pin it with a test that renders the real `FlowBuilderPage` through the redirect, never one that rebuilds the page key from the helper — that is circular and stays green when the page goes back to a literal key. A stub of `BuilderStateProvider` in such a test must keep its first props, or the refetch re-renders it with fresh data and hides the bug.
- **`placeholderData: keepPreviousData` reuses the last result on *any* query-key change, so on a scoped query it renders one scope's data under another scope's label.** It is reached for to stop a debounced search flashing a skeleton on every settle, which is the transition it earns its keep on — but the key usually carries a scope segment too (a `projectId`), and switching that is treated identically. The MCP Reach tab showed the previous project's pieces under the newly picked project until the replacement landed, and for a project the user cannot see, until the denial swapped in the access alert. Nothing crosses a permission boundary (the rows were fetched and authorised under the previous scope, and the pending request can only return the new scope's data or a denial) so it is misattribution, not disclosure — but on a page whose claim is "this is what a client can reach in *this* project", an admin reads a restricted project as wide open. Scope the placeholder instead of dropping it: the v5 form takes a second argument, so `(previousData, previousQuery) => previousQuery?.queryKey[SCOPE] === scope ? previousData : undefined` keeps the search behaviour and restores the loading state on a scope switch, where it is the correct feedback anyway. Put the scope segment early in the key so the comparison is stable, and cover it with a test — the positional index is exactly what a later key reorder breaks silently. A filter-driven list (a multi-select of projects in the URL, as on the Connections tab) is *not* the same case and wants the plain `keepPreviousData`.
- **`<label for>` never gives an accessible name to a `contenteditable` div — only `aria-label`/`aria-labelledby` does.** HTML restricts `for` to *labelable* elements (`input`, `select`, `textarea`, `button`, `meter`, `output`, `progress`), so `HTMLLabelElement.control()` returns null for a `div[role="textbox"]` and no browser feeds that label into the accname computation. This bites every piece property in the builder: `FormLabel` mints `htmlFor={formItemId}` ([components/ui/form.tsx](packages/web/src/components/ui/form.tsx)) but the mention editor is a ProseMirror contenteditable, so the field is announced as "edit text, blank". The trap in verifying it is that `document.getElementById(label.getAttribute('for'))` resolving proves *id resolution*, not naming — an a11y probe built on `getElementById` reports a fix that screen readers do not see. Check Chrome DevTools → Elements → Accessibility → Computed Properties → Name instead. Attributes reach the editable node through tiptap's `editorProps.attributes`, not through `FormControl`: Radix `Slot` targets `TiptapEditor`'s wrapper div, and prosemirror-view's `computeDocDeco` copies every key of `attributes` onto the contenteditable except `class`/`style`/`contenteditable`/`nodeName`. See [#15217](https://github.com/activepieces/activepieces/pull/15217).
- **`useFormField()` outside a `FormItem` silently yields `id: "undefined-form-item"` instead of throwing.** Its `if (!fieldContext) throw` guard in [components/ui/form.tsx](packages/web/src/components/ui/form.tsx) is dead code — both `FormFieldContext` and `FormItemContext` default to `{} as …`, which is truthy — so a component that reads `formItemId` outside a `FormItem` gets a *shared constant string*, and two of them on one page are duplicate DOM ids with no error anywhere. Any wrapper that reads `formItemId` to label a control has to be rendered inside the same `<FormItem>` as its `<FormLabel>`; check the call sites, the hook will not tell you. This is why the builder's mention editor is *two* components — `TextInputWithMentions` (plain) and `FormFieldMentionInput` (reads `formItemId`) — and not one: `formItemId` is one id per `FormItem`, but several sites render **many** editors under a single one (`DictionaryInput`'s `renderValueInput` fires once per row inside the one `FormItem` for `settings.input` in `step-settings/code-settings`, likewise `OBJECT` properties in `properties-utils`; `customInputNode` once per item in `array-property`; `property-group-tabs` adds `MentionChipsInput`, itself two more). Folding the hook into the shared component would give all of them the same `id`, so `label[for]` would resolve to the *wrong* editor instead of to nothing — worse than the bug. A flag prop does not rescue it either: hooks cannot be conditional, so the shared component would call `useFormField()` for every caller, including `mention-chips-input`, which imports nothing from react-hook-form and survives only because its one caller happens to sit in a form. The *other* direction fails harder and is not guarded: outside a react-hook-form `FormProvider` entirely, `useFormField()` does `const { getFieldState } = useFormContext()` on a `null` return and throws a TypeError, so a wrapper reused outside a form white-screens its subtree rather than degrading. Nothing warns you before it happens, and nothing can: the throw is during render, so no effect-based guard ever runs. In the builder the three property call sites sit inside `AutoFormFielWrapperErrorBoundary`, so they surface the “input value is invalid, please contact support” box instead; `RichTextProperty` renders its own `FormItem` outside that boundary and has no such net.
- **`DialogContent` sets no max-height, so nothing stops a tall dialog growing past the viewport.** It is `grid` + `fixed top-1/2 left-1/2 -translate-1/2` under a fixed overlay, so any overflow hangs off the screen where the page behind cannot scroll it into view — and capping the inner body alone (`max-h-[60vh] overflow-y-auto`) does not help, because the dialog box itself is still unbounded. Put a `ScrollArea` between the header and the footer instead, the way `connect-provider-dialog.tsx` and `tracked-events-dialog.tsx` do: `<ScrollArea viewPortClassName="max-h-[60vh] p-px">`, `DialogContent` left alone. Radix puts the cap and the overflow on its own viewport element, so it does not depend on the parent chain being height-constrained. When checking whether a dialog scrolls, read `clientHeight` vs `scrollHeight` off `[data-slot="scroll-area-viewport"]` rather than trusting a screenshot — browser zoom scales `vh`, so a zoomed-in window makes a correctly-capped dialog look like it overflows.
- **`MultiSelectPieceProperty` resolves the selection by *index* over `[...cachedOptions, ...options]` but renders items and writes values indexed into `options` alone, so the two lists must stay identical or the widget renders a raw index string and the next click throws.** [components/custom/multi-select-piece-property.tsx](packages/web/src/components/custom/multi-select-piece-property.tsx) computes `selectedIndicies` with `findIndex` over the *merged* list, while `items` is `options.map((_, i) => String(i))` and `sendChanges` does `options[Number(index)].value`. An index found in the `cachedOptions` half therefore addresses the wrong option — or none, and then `MultiSelectValue` falls back to `item?.label || value` and paints the literal string `"2"` as a badge, and because the primitive *appends* the newly picked index to the existing controlled value (radix `useControllableState` computes the updater against the `prop` **synchronously in the event handler**), the next selection evaluates `options[2].value` on a shorter array and throws. **No error boundary catches it** — the throw is in an event handler, not in render, so React reports it as an unhandled error, `onChange` is never called, and the click is silently discarded: the control is dead with no visible error at all. **This crash is already live on `main`** for any multi-select with `refreshOnSearch`, where a server-filtered response narrows `options` while `cachedOptions` keeps the full first list — same `"2"` badge, same uncaught `TypeError`. Treating it as cosmetic under-rates it. The lists happen to be identical today only because `cachedOptions` is `firstDropdownState.current`, seeded from the first successful fetch — so **anything that lets a value survive a refresher change breaks the invariant**: a dropdown restore after a connection switch hands the widget the *new* option list next to the *old* cached one. Reset `firstDropdownState.current = undefined` wherever the refreshers change; `onSuccess` re-seeds it from the new response before `setDropdownState`, which realigns the two lists and also stops single-select showing the *old* connection's label for a restored value (`searchable-select.tsx` merges `cachedOptions` first, so the stale label wins the `find`). The trap in testing it is that both renderers are usually mocked to `() => null` in `test/app/builder/piece-properties/`, so a suite can be 101/101 green with the widget never rendered — assert on the props handed to `MultiSelectPieceProperty` (`cachedOptions` length matching `options`), not just on the form value. **The fix is to flip the merge order — `allOptions = [...options, ...cachedOptions]` — and drive selection, `items`, item keys and `sendChanges` off that one list.** `findIndex` then lands in the options half for any value the current list still has, which is the index the rendered row uses, and in the tail for a value only the cached list can label, where `items` still resolves it; duplicates in the tail are simply unreachable. **Do not dedupe the two lists to build that basis.** `cachedOptions.filter(c => !options.some(o => deepEqual(o.value, c.value)))` is O(c·m) `deepEqual` calls *per render*, and the `deep-equal` package costs roughly **70µs per object comparison** — measured on 800 options with `{id, name}` values, that one line took **19 seconds per render** (0.02ms → 21ms even for plain string values). Option lists that big are ordinary, `refreshOnSearch` exists precisely for them, and the component re-renders on every keystroke. The ordering-only version measures *faster* than the code it replaces. General rule: `deepEqual` belongs in an O(n) scan that short-circuits, never inside a nested loop over two option lists. `searchable-select.tsx` needed the same merge order flipped for the label; it resolves by value, so it never had the crash.
- **The f(x) toggle round-trips a property's value through a text box, and only the types named in `parseDynamicValue` survive it.** Toggling f(x) *on* stringifies the current value; toggling *off* runs `formUtils.parseDynamicValue` and falls back to `getDefaultPropertyValue` on `undefined` — so any type the switch does not name has its value silently replaced by the type's default. That is how a Dropdown holding `{{ variables['X'] }}` became `null` and, toggled back, the literal string `"null"` (GIT-1767, hit by a customer on Slack's Channel field, whose own markdown tells people to click (F) and type the id). **Do not generalize the `default:` branch to "keep any string that has a mustache token"**, which is the obvious cleanup and is wrong: `ARRAY` also carries the toggle, and `array-property.tsx` calls `formValues.map(...)`, so a preserved string throws straight into the wrapper's "input value is invalid, please contact support" boundary. Add types one at a time, checking that the manual editor tolerates a string it did not produce — `SearchableSelect` and `MultiSelectPieceProperty` just fail to match and show the placeholder (the value survives, invisibly), `ColorPicker` renders any string, `Switch` shows a non-empty string as ON. Still unhandled and still losing data: `OBJECT` and `JSON`, where a plain `{a: 1}` comes back as `{}` because only the `[`/`{` JSON restore in the dropdown branch reverses `JSON.stringify`. The toggle is offered wherever `allowDynamicValues` is true in `properties-utils.tsx`, which is the list to check against — the text-like types pass `false` there because their manual editor already accepts mentions.
- **`deepEqual` from the `deep-equal` package is LOOSE by default, so matching an option is not the same as matching its type.** Verified on `deep-equal@2.2.2`: `deepEqual('5', 5)`, `deepEqual(0, false)`, `deepEqual('', 0)` and `deepEqual({a:'1'}, {a:1})` are all `true`. Every option-matching call in the web dropdowns relies on this (`searchable-select.tsx`, `multi-select-piece-property.tsx`, `dynamic-dropdown-piece-property.tsx`), which is fine while the result is only used to *find* a row. It stops being fine the moment you write the matched option's value back into the form: `restoreValueIfStillInOptions` restoring `matchingOption.value` instead of the stored value silently rewrites a saved `'12345'` into `12345` when a connection switch re-resolves the dropdown, and the piece — or the backend schema — then sees a number where a string was persisted. Decide deliberately: canonicalize to the option's value (what the option list says is correct) or echo back the value the form already held; if you need the strict comparison, `deep-equal` takes `{ strict: true }`. The same looseness means a stored `0` can match an option whose value is `false`.
- **CI never type checked `packages/web`, so a `tsc` error could sit on `main` while every check stayed green.** The web build script is `vite build`, which transpiles without reading types — `packages/server/{api,worker,sandbox,utils}` build with `tsc -p` and so get the type check for free from the build step, but `packages/server/engine` is bundled by esbuild and has the same hole — it carries pre-existing type errors today, so it cannot just be added to the step. Nothing else in `ci.yml` ran `tsc` against web. The failure mode is that the author's editor is the only thing that sees the error, and it reaches whoever pulls next: [#15524](https://github.com/activepieces/activepieces/pull/15524) landed a `'message' in apError.params` on a union where `INVALID_CREDENTIALS` declares `params: null`, and `main` was red in every contributor's IDE for hours with no CI signal. **Read that class of error as a runtime bug, not a lint nit**: `in` throws a `TypeError` on `null` and `undefined`, so the suppressed complaint was describing a real crash inside a React Query `onError` — the toast never rendered and the user got no feedback at all. The narrowing was honest and the cast was not: `error.response.data as ApErrorParams` promises a `params` object that a proxy 500, a gateway HTML page or a bare `{ message }` body does not carry, so the property is `undefined` at runtime no matter what the cast says. `ci.yml` now runs `npx turbo run typecheck --filter=web` (the `typecheck` task already existed in `turbo.json`) before the core build. When adding a package that builds through a bundler rather than `tsc`, give it the same explicit step.
- **The UI theme default is `light`, not `system` — and the embed pins to light too.** `ThemeProvider` ([components/providers/theme-provider.tsx](packages/web/src/components/providers/theme-provider.tsx)) falls back to `light` when `vite-ui-theme` is unset, and the embed route calls `setPreferenceWithoutPersisting(event.data.data.mode ?? 'light')` so a vendor that passes no `styling.mode` never inherits the *viewer's* OS theme inside the iframe. **The embed must use the non-persisting setter**: the iframe is same-origin with the main app, so the plain `setPreference` writes the vendor's styling choice into the shared `vite-ui-theme` key and the user's own UI silently loses the theme they picked — one visit to a customer's embed and their dark mode is gone. Anything that is a *surface's* display choice rather than the user's preference wants that setter. The flip side is that non-persisted theme state only survives while the provider does, and `app.tsx` remounts its subtree on every language change via `<React.Fragment key={i18n.language}>` — a fresh `ThemeProvider` re-reads `vite-ui-theme` and the override is gone. So `ThemeProvider` sits *outside* that keyed fragment, and any other provider holding state that is not written to storage has to as well. The embed hits this exactly: `VENDOR_INIT` applies `styling.mode` and then `i18n.changeLanguage(locale)` inside the same handler, so a vendor asking for dark plus a non-`en` locale is the case that breaks. `system` is still a real option, but only when a user picks it in Settings > Appearance. The default used to be `system` and nobody noticed, because `system` was silently broken — it read `prefers-color-scheme` once at mount and never re-read it, so in practice everyone landed on light; fixing that (GIT-1478, #15463) flipped every dark-OS user with no stored preference into dark overnight, which is what GIT-1888 reverses. So a "dark mode is the default now" report is not a regression in the toggle, it is this default. The resolved theme is written as `data-theme` on `<html>` in its own effect, independent of branding, so it is set before the flags load.

- **A `.ts` and a `.tsx` of the same name can both sit in the tree, and every importer silently binds to the `.ts`.** `hooks/use-mobile.ts` and `hooks/use-mobile.tsx` were byte-for-byte identical for months: the `.ts` arrived with #11554 and nothing removed the `.tsx` that #11440 had left. Both TypeScript's Node resolution and Vite try `.ts` before `.tsx`, so all five importers of `@/hooks/use-mobile` resolved to the `.ts` and the `.tsx` was unreachable — while still being edited, linted and typechecked like live code. Nothing flags this: the import resolves, tsc is happy, and a `grep` for the symbol shows five healthy importers, which reads as proof the file is *used*. Only a reachability tool sees it. When a file looks dead but its symbol has importers, check for a same-named sibling with the other extension before concluding the tool is wrong.
- **`knip` is the reachability check for `packages/web`; `npm run knip` must exit clean.** Config in `knip.json` at the repo root, every rule at its default `error` severity — nothing is muted, so a non-zero exit means real dead code, not noise. Two settings carry the weight. `src/features/*/index.ts` are **entry points**, because a feature barrel is that feature's public surface (see *Feature folder* above) and is meant to export more than today's callers import; without that, reachability reports the convention itself as dead. `ignoreExportsUsedInFile: true` means anything it does report is referenced *nowhere*, not even in its own file. The two `ignore*` lists cover what knip genuinely cannot see: `tailwindcss`/`tw-animate-css` arrive via `@import` in `styles.css` (knip does not follow CSS), and `dwebp`/`sips`/`cwebp` are system binaries shelled out to by `scripts/generate-usecase-images.mjs`.
- **When knip flags an export whose name clearly has live callers, look for a second symbol of that name before concluding knip is wrong.** This codebase repeatedly grew duplicates — something was moved or re-implemented and the old copy stayed — so a `grep` for the symbol finds the *other* one and reads as proof the finding is bogus. Every instance checked was knip being right: `use-mobile.ts` vs `.tsx` (identical files, resolution silently picks `.ts`), `cursor-position-context.tsx` duplicated under `flow-canvas/` and `state/` (two separate `createContext()` calls), `parseAnswerPairs` shared vs a local copy in `assistant-message.tsx`, and `FlowApprovalRequestState`/`PieceSelectorTabConfig` re-exported locally while every consumer imports them from `@activepieces/shared`. knip also resolves this repo's dynamic imports correctly, including `React.lazy(() => import(x))` (needs `default`) and `import(x).then(m => ({default: m.Named}))` (needs the named export) — do not assume it is guessing. Verify a finding by reading the importing file's actual `import` statement, never by counting `grep` hits on the name.
- **A master/detail settings panel that `return`s one `FormField` early silently deletes that field's value when you go back.** React unwraps a keyless fragment and reconciles by position, so a detail view whose whole return is `<FormField name={`settings.branches.${i}.description`}/>` and a master view whose fragment *starts* with `<FormField name="settings.text"/>` are the same component type at index 0 — React keeps the instance and swaps the `name` prop instead of unmounting. react-hook-form's `useController` then hits `if (previousName && previousName !== name && !isArrayField) control.unregister(previousName)` ([useController.ts:200](https://github.com/react-hook-form/react-hook-form), 7.71.2), and `unregister` does `unset(_formValues, previousName)` — the value the user just typed is **deleted from the form**. `shouldUnregister` is irrelevant; this path ignores it. `isArrayField` is `isNameInFieldArray(_names.array, name)` computed from the **new** name, so detail→detail (`branches.0.description` → `branches.1.description`) is safe and detail→master (`… → settings.text`) is not — which is why the symptom reads as "the *other* route lost its value" rather than "this field is broken". The next keystroke anywhere then persists the pruned settings through `UPDATE_ACTION`, so it survives a reload too. The AI Router settings panel had this; the Router panel does not, because it never early-returns — it renders master and detail as `{isNil(selectedBranchIndex) && …}` / `{!isNil(selectedBranchIndex) && …}` siblings and gives `BranchSettings` an explicit `key` carrying the index. Copy that shape, or key the detail field, whenever a panel swaps between two subtrees that both begin with a form field. To catch it, `Proxy` the object under test with a `deleteProperty` trap that prints `new Error().stack`: a `delete` is invisible to a setter spy, and the stack names the exact library line. The same reuse also explains the *other* symptom, a route description that shows the Input text: `useWatch` keeps the default it computed at mount in a ref (`_defaultValue`) and never refreshes it on a `name` change, so when the swapped-in name has no value yet (a branch whose `description` key the unregister already deleted) `getCurrentOutput()` falls back to the first field's mount-time value, and `useController`'s render-phase `control.register(name, { value })` writes that into `_formValues`. One `key` carrying the branch index on the detail field remounts it and fixes both; `packages/web/test/app/builder/step-settings/ai-router-settings/route-description.test.tsx` reproduces both against the real panel, with the builder store stubbed through `useSyncExternalStore` because the panel is `memo`-wrapped and a non-subscribing stub never re-renders it.
- **`applyOperation` hands the form's live `settings` object to the flow version and to the queued request.** [`flow-state.ts`](packages/web/src/app/builder/state/flow-state.ts) `applyOperation` spreads `{...cleanedNewValues}` shallowly, so `request.settings` — and after `_updateAction`'s `{...request.settings}`, `flowVersion.…settings.branches` — is the *same array of the same objects* react-hook-form is still mutating. `UPDATE_ACTION` is debounced 1 s while every other operation queues immediately, so a request can be serialized with values typed after it was created, and the local flow version mutates without zustand seeing a new reference. It also means logging a queued operation shows you the *final* state, not what was queued — do not debug ordering that way. Separately, `PromiseQueue.halt()` in the `catch` is permanent: one rejected flow update stops every later save for the rest of the session, with only the `UNSAVED_CHANGES_TOAST` to say so.
- **A core step's picker copy (`buildCoreStepMetadata` in `step-utils.tsx`) is pinned in four places, and the test that guards it fails with a misleading message.** The English sentence is the i18n key, so it lives in `step-utils.tsx`, in `public/locales/en/translation.json`, in the matching `docs/flows/*.mdx` frontmatter, and as a key of the fake `JAPANESE_BUNDLE` inside `test/features/pieces/utils/step-utils.test.ts`. Reword the first three and the test fails with `expected ['コード', …] to include '<new sentence>'`, which reads as a locale problem; the fix is the test's own map, not a locale file. Nothing else in the repo carried the old key.
- **A core step's icon is a CDN URL, not a bundled asset, and the SVGs under `packages/web/src/assets/img/piece/` are dead copies.** `buildCoreStepMetadata` in `step-utils.tsx` points Code, Loop, Router and Empty Trigger at `https://cdn.activepieces.com/pieces/new-core/<name>.svg`; the AI Router's is `https://cdn.activepieces.com/pieces/ai_router.png`, a PNG outside `new-core/`, so do not assume every core icon shares one folder or one format. A new core step therefore needs someone with bucket access to upload `pieces/new-core/<name>.svg` before the URL is changed — `curl -o /dev/null -w '%{http_code}'` it first, because a missing asset is a broken image that no test sees. A Vite asset import also satisfies `logoUrl` (the SSO page's Google icon does this) if the cross-team wait is not worth it. Nothing imports the local `img/piece/*.svg`; they are not the fallback.
- **Rewriting a shared component silently drops whatever props it stops destructuring, and optional props make the compiler complicit.** Replacing `LockedFeatureGuard`'s body took the `RequestTrial` sales form off 17 pages at once: every caller still passed `featureKey` and `showContactSales`, the new component just never read them, and because both stayed `?:` in the props type nothing failed to compile and no call site changed in the diff. The prop a rewrite must not lose is the one to make **required** — the moment `featureKey` was, `tsc` listed exactly the call sites that had dropped it, across all three branches of the stack. When a component's props feed a business surface rather than styling, review the destructure, not the prop list.
- **With a resolver, react-hook-form in `onChange` mode re-checks only the field that changed.** It runs the whole schema but stores only that field's error, so a rule that spans fields (a header value that must be re-entered when the URL changes) shows nothing until the other field changes or the form submits. Give the triggering field `rules: { deps: ['other'] }`, or call `trigger('other')`.
- **A list-level zod issue moves between `name` and `name.root`, and the zod resolver keeps only the first issue per path.** `toNestErrors` re-homes an issue at `headers` to `headers.root` once fields like `headers.0.name` are registered (on change and submit), but not on `trigger('headers')`. Put field-array issues on row paths (`['headers', i, 'name']`); after `remove(i)` call `trigger('headers')`, because the field array does not refresh the other rows' errors.
- **`z.url(msg).min(1, required)` never shows `required`.** zod 4 runs the URL format check first and the resolver keeps the first issue. Write `z.string().min(1, required).pipe(z.url(msg))`.
- **The global `MutationCache.onError` toast stays quiet only when `onError` is set in the `useMutation` options.** An `onError` passed to `mutate()` is a per-call callback; the cache still sees a mutation without one and shows "Something went wrong".
- **A TanStack DB query collection on a private `QueryClient` must mount that client, or it never refetches on focus or reconnect.** Only `QueryClientProvider` calls `mount()`, and only for the app's client. Without it a retry that pauses on a hidden tab also never resumes. `event-destinations-collection.ts` mounts and unmounts its client in the live hook's effect; the call is reference-counted.
