@qoretechnologies/reqraft 0.10.64 → 0.10.65-pr.137.g62fcecc

package/.claude/CLAUDE.md

@@ -1,317 +0,0 @@
-@~/Projects/instruction-files/CLAUDE.md
-@~/Projects/instruction-files/stacks/frontend/FRONTEND.md
-
-# ReQraft (toolkit-react) — Claude entry point
-
-## Shared Qore rules (READ FIRST)
-
-The two `@`-imports above load the shared rules from the **instruction-files**
-repo: the org-wide baseline (`CLAUDE.md`) and the frontend ruleset
-(`stacks/frontend/FRONTEND.md`) — git safety, commit conventions, CI
-monitoring, `/audit`, the Reqore-first rule, the Storybook + Qlip visual-change
-flow, story descriptions, and more. Those files point on to
-`stacks/frontend/BRAND_DESIGN.md` for brand / UI-design decisions (read it
-before building any visual surface). **Everything below this section is
-specific to ReQraft (toolkit-react).**
-
-**If the imports above did not load** — you don't see the shared rules because
-this repo is cloned somewhere other than `~/Projects/instruction-files` — find
-the shared repo before doing any frontend work:
-
-1. Check for a gitignored **`.instruction-files-path`** file at this repo's
-   root. If it exists, read the path `P` from it, then read `P/CLAUDE.md` and
-   `P/stacks/frontend/FRONTEND.md` (+ `P/stacks/frontend/BRAND_DESIGN.md` for
-   UI work) and follow them.
-2. Otherwise locate the `instruction-files` repo on disk (try
-   `~/Projects/instruction-files`, then your other project roots). If found at
-   `P`, write `P` into `.instruction-files-path` (create it — it's gitignored)
-   so future sessions skip the search, then read the files above.
-3. If it isn't cloned anywhere, **STOP and ask the user to clone it**:
-   `git clone git@github.com:qoretechnologies/instruction-files.git ~/Projects/instruction-files`
-   Do not proceed with frontend work until the shared rules are loaded.
-
-# ReQraft (toolkit-react) — project-specific rules
-
-## Project Overview
-
-ReQraft (`@qoretechnologies/reqraft`) is a **React hooks and components toolkit** for Qore Technologies' products. It sits on top of the [ReQore](https://github.com/qoretechnologies/reqore) component library and provides higher-level primitives: data fetching, WebSocket management, user/storage state, and shared form fields.
-
-**Key Facts:**
-
-- **Package name:** `@qoretechnologies/reqraft`
-- **Framework:** React 18 + TypeScript (strict mode)
-- **Build:** TypeScript compilation to `/dist` via `tsconfig.prod.json`; exports `.js` + `.d.ts`
-- **Styling:** styled-components (inherited from ReQore); no CSS modules
-- **State Management:** zustand (stores) + React Context (`use-context-selector`)
-- **Data Fetching:** `@tanstack/react-query` v4 (via `query()` util + `useFetch` hook)
-- **Testing:** Vitest — a `unit` project (jsdom, tests in `__tests__/`) + a `storybook` project (every story run in a real Chromium browser via Playwright); React Testing Library for component assertions
-- **Documentation:** Storybook (stories co-located in `src/` with `.stories.tsx` suffix)
-- **Storybook port:** `6008` (not 6007 — that's reqore)
-
-## Architecture Essentials
-
-### Provider Stack (`src/providers/`)
-
-The app must be wrapped in `ReqraftProvider` (or initialized via `initializeReqraft()`):
-
-```
-ReqraftContext.Provider (appName)
-  └── QueryClientProvider (react-query)
-        └── ReqraftFetchProvider (fetch context: get/post/put/del methods)
-              └── ReqraftUserProvider (loads currentUser + storage, handles waitForStorage)
-```
-
-- **`initializeReqraft(options)`** — call once at app boot to set `instance`, `instanceToken`, `instanceRbacDisabled`, and `unauthorizedRedirect`; returns `ReqraftProvider`
-- **`waitForStorage`** (default `true`) — delays rendering children until user storage is loaded from the server
-
-### Fetch System (`src/utils/fetch.ts`)
-
-- **`fetchConfig`** — mutable global config: `instance`, `instanceToken`, `instanceRbacDisabled`, `unauthorizedRedirect`
-- **`setupFetch()`** — sets `fetchConfig`; called by `initializeReqraft`
-- **`query<T>(config)`** — core async fetch using react-query under the hood; caches GET responses for 5 minutes (`CACHE_EXPIRATION_TIME`); POST/DELETE bypass cache
-- All requests go to `${instance}api/latest/${url}`
-- 401 responses trigger `fetchConfig.unauthorizedRedirect` (default: `/?next=<current-path>`)
-- Auth: token via `Authorization: Bearer` header, but production uses cookies (`credentials: 'include'`)
-
-### WebSocket System (`src/utils/websocket.ts`)
-
-Two classes work together:
-
-- **`ReqraftWebSocketsManager`** (static) — connection pool keyed by URL; shared `WebSocket` instances for `pooled: true` (default)
-- **`ReqraftWebSocket`** — wraps a pooled or dedicated socket; handles reconnect logic, heartbeat (`ping` every 3s), handler registry
-
-**Pooling:** By default (`pooled` not set to `false`), sockets with the same URL share one underlying `WebSocket`. Use `pooled: false` for dedicated connections. The pool key becomes `${url}::${nanoid()}` for non-pooled.
-
-**Reconnect:** Triggered on close (unless code `4999` = intentional). Immediate first try, then `reconnectInterval` (default 5s) up to `maxReconnectTries` (default 10).
-
-**Heartbeat:** Sends `"ping"` every 3s; ignores `"pong"` in message handlers.
-
-### `useReqraftWebSocket` Hook (`src/hooks/useWebSocket/useWebSocket.ts`)
-
-Key options:
-- `openOnMount` / `closeOnUnmount` — lifecycle management
-- `useState` — accumulate messages in local state
-- `includeSentMessagesInState` — also store sent messages
-- `includeLogMessagesInState` — store connect/disconnect/reconnect log entries
-- `onMessage` — raw message callback (pong filtered automatically)
-
-Returns: `{ messages, status, open, close, send, clear, on, pause, resume, addMessage, removeMessage, socket }`
-
-Status enum: `OPEN | CLOSED | CONNECTING | PAUSED`
-
-### `useFetch` Hook (`src/hooks/useFetch/useFetch.tsx`)
-
-- Wraps `query()` via `FetchContext`; supports GET/POST/PUT/DELETE
-- `loadOnMount` — triggers load immediately on mount
-- `load({ body?, mergeBodies? })` — imperative trigger; `mergeBodies` merges call-time body with hook-defined body
-- Returns: `{ data, loading, load, error, errorData, response }`
-
-### Storage System (`src/hooks/useStorage/useStorage.ts`)
-
-- `useReqraftStorage<T>(path, defaultValue?, includeAppPrefix?)` — returns `[value, setter, remover]`
-- Backed by `ReqraftStorageContext` → `StorageProvider` → persisted to server via user storage API
-- `includeAppPrefix` namespaces the key under the current `appName` from context
-- Storage loads from `currentUserStore` (user's `storage` field from `/users?action=current`)
-
-### Current User Store (`src/stores/currentUser/currentUser.tsx`)
-
-- Zustand store: `{ currentUser, loading, error, load, hasAnyPermission, updateStorage }`
-- `load()` — fetches `/users?action=current` (no cache); rejects on error
-- `hasAnyPermission(permissions[])` — checks against `currentUser.permissions`
-- Loaded automatically by `ReqraftUserProvider` on mount
-
-### Form Fields (`src/components/form/fields/`)
-
-Shared form field components built on ReQore, exported from `src/components/form/index.tsx`:
-
-| Component     | Field Type                        |
-|---------------|-----------------------------------|
-| `Boolean`     | Toggle/checkbox                   |
-| `Color`       | Color picker (`react-color`)      |
-| `Cron`        | Cron expression editor            |
-| `File`        | File upload (`react-dropzone`)    |
-| `LongString`  | Multi-line text                   |
-| `Markdown`    | Markdown editor/preview           |
-| `Number`      | Numeric input                     |
-| `Object`      | YAML/JSON object editor           |
-| `RadioGroup`  | Radio group with optional images  |
-| `String`      | Single-line text                  |
-
-A generic `<Field>` component dispatches to the appropriate field by type.
-
-### Menu Component (`src/components/menu/Menu.tsx`)
-
-- `ReqraftMenu` — navigation menu built on ReQore components
-- Types: `TReqraftMenu` (array), `TReqraftMenuItem`, `IReqraftMenuItem`, `IReqraftMenuProps`
-
-### Log Component (`src/components/log/Log.tsx`)
-
-- Displays streaming log messages; typically fed by `useReqraftWebSocket`
-
-## Development Workflows
-
-### Quick Start
-
-```bash
-yarn install
-yarn storybook          # Dev mode on http://localhost:6008
-yarn test               # Vitest unit tests (jsdom)
-yarn test:watch         # Vitest unit watch mode
-yarn test:stories       # Story / interaction tests in a real browser (+ Qlip capture)
-yarn lint               # ESLint check
-yarn build              # TypeScript compilation (tsconfig.prod.json)
-yarn build:test         # Type-check without emit
-```
-
-### Pre-commit Checks
-
-- `yarn precheck` runs: lint → test → build:test:prod
-- `pre-push` hook enforces: `build:test:prod`, `lint`, `test`
-- CI (`.github/workflows/tests.yml`) runs precheck, build and the full story suite for PRs into `develop` **and** for every push to `develop`. GitHub skips `pull_request` workflows while a PR has merge conflicts, so a conflicting PR gets no test runs until it is rebased or merged up
-- Branch naming: always start with the issue number, e.g. `feature/49_pooled-connections`
-
-### Versioning — every PR to `develop` MUST bump the version
-
-`.github/workflows/beta_release.yml` runs on **every push to `develop`** and publishes to NPM using whatever `version` is in `package.json` at push time. A merge without a bump therefore tries to re-publish an already-published version and **fails** (NPM refuses to re-publish). This applies to **every** PR — features, fixes, chores, and docs-only changes alike. There is no exception.
-
-- Bump the **patch** for an ordinary PR while in beta (pre-1.0) — e.g. `0.10.9` → `0.10.10`. Do NOT bump minor/major for ordinary feature/fix PRs.
-- Bump **exactly once per PR**, not once per commit. If the branch has already bumped, leave it alone —
-  a second bump does not make the merge any more publishable, it just burns a version that never ships.
-  Check before you reach for it: `git diff $(git merge-base origin/develop HEAD) -- package.json`. A PR
-  that walked 0.10.36 → 0.10.46 one commit at a time is what this line exists to prevent (#95), and its
-  prereleases are stamped from `package.json`, so a base that moves every push hands consumers what look
-  like ten different release lines instead of successive previews of one.
-- Bump **exactly once per PR**, not once per commit. If the branch has already bumped, leave it alone —
-  a second bump does not make the merge any more publishable, it just burns a version that never ships.
-  Check before you reach for it: `git diff $(git merge-base origin/develop HEAD) -- package.json`. A PR
-  that walked 0.10.36 → 0.10.46 one commit at a time is what this line exists to prevent (#95), and its
-  prereleases are stamped from `package.json`, so a base that moves every push hands consumers what look
-  like ten different release lines instead of successive previews of one.
-- Bump in `package.json` only (no git tag): `npm version patch --no-git-tag-version`, and include the bump in the PR's commit.
-- If another PR bumps to the same version before yours merges, rebase and bump again — the version at merge time must be strictly greater than the last published one.
-
-### Testing Patterns
-
-- Two Vitest projects (see `vitest.config.ts`): **unit** (jsdom; tests in `__tests__/`, mirroring `src/`) and **storybook** (every `*.stories.tsx` run in a real Chromium browser via Playwright). There is no Jest.
-- Wrap unit tests with `ReqraftProvider` (or at minimum `QueryClientProvider`)
-- Use `mock-socket` for WebSocket testing
-- Run: `yarn test` (unit) · `yarn test:stories [file-substring]` (stories) · `yarn precheck` (lint + unit + `build:test:prod`)
-
-### Storybook Stories & visual testing
-
-- Stories are co-located alongside source: `src/hooks/useFetch/useFetch.stories.tsx`
-- Storybook port: **6008**
-- Story + interaction tests run on **Vitest browser mode** (Playwright/Chromium): `yarn test:stories [file-substring]`. Run `yarn install-playwright` once first.
-- **Story network — mocks must follow the instance, and stories must not share connections.**
-  - Build every mock URL with `storyApiUrl(path)` / `storySocketUrl(path)` from
-    `src/stories/storyNetwork.ts`, never a hard-coded `https://hq.qoretechnologies.com:8092/…`.
-    Both mock layers match on host (storybook-addon-mock keys on `host + pathname`,
-    mock-socket on the URL minus its query), so a hard-coded host silently stops matching
-    when `REACT_APP_QORUS_INSTANCE` is overridden and the request goes to the real network.
-  - Requests components make on their own (FormEngine's `system/qorus-type-info`, the
-    expression catalogue `useExpressions` fetches whenever functions are allowed, the
-    reconnect probe `system/pid`) are mocked for every story via `GLOBAL_STORY_MOCK_DATA`
-    (`parameters.mockAddonConfigs.globalMockData`). Add new ones there, not per story file.
-  - A mock `response` must be an object, array or function — a bare number or string fails
-    the addon's validation and the entry is silently never matched (`TStoryMockResponse`
-    enforces this at compile time). The addon compares query-parameter *keys* only, so
-    `system?action=a&context=x` also answers `system?action=b&context=y`.
-  - `.storybook/preview.tsx` resets the shared LSP connections and the expression render
-    client before every story. Do not add per-file `ReqraftWebSocketsManager.closeAll()`
-    calls for LSP isolation.
-  - CI reaches the live hq instance with a valid token, so a story that leaks a real
-    request can pass in CI and hang locally. When a story passes in CI but times out on
-    your machine, look for an unmocked request before anything else.
-- **Visual regression via Qlip** (not Chromatic): the story run captures snapshots through the `qlip` Vitest plugin. Upload is gated on `QLIP_UPLOAD_TOKEN` (`vitest.config.ts`), so **local runs capture but never upload** — PNGs land in `qlip/screenshots/<ts>/stories/auto/<StoryId>.png` (gitignored); read the PNG to verify a visual change. CI (`.github/workflows/tests.yml`) sets the token and uploads a build for dashboard review. The full visual-change flow + the `qlip` MCP review skill live in the imported `stacks/frontend/FRONTEND.md`.
-
-## Code Patterns & Conventions
-
-### Naming
-
-- Enums: PascalCase (e.g., `ReqraftWebSocketStatus`)
-- Hooks: `useReqraft*` prefix
-- Providers: `Reqraft*Provider`
-- Stores: `*Store` suffix
-
-### Context Access
-
-- Use `useContextSelector` (from `use-context-selector`) for fine-grained re-renders
-- Use plain `useContext` only when consuming the full context is acceptable
-
-### Adding a New Hook
-
-1. Create `src/hooks/useMyHook/useMyHook.ts`
-2. Add a story at `src/hooks/useMyHook/useMyHook.stories.tsx`
-3. Export from `src/index.tsx`
-
-### Adding a New Form Field
-
-1. Create `src/components/form/fields/myfield/MyField.tsx`
-2. Add a story at `src/components/form/fields/myfield/MyField.stories.tsx`
-3. Register in `src/components/form/fields/Field.tsx` dispatch
-4. Export from `src/components/form/index.tsx`
-
-## Key Integration Points
-
-### Fetch Auth Flow
-
-1. `initializeReqraft({ instance, instanceToken })` sets `fetchConfig`
-2. All `query()` calls prepend `${instance}api/latest/` and attach token if present
-3. 401 → redirect via `unauthorizedRedirect` (configurable per app)
-
-### WebSocket Auth
-
-- Token appended as `?token=<instanceToken>` to the WS URL
-- Override per-socket with `tokenOverride` option
-
-### React Query Caching
-
-- `ReqraftQueryClient` is a shared `QueryClient` instance (exported for reuse)
-- GET requests cache for 5 minutes; failed responses are immediately invalidated
-- Pass a custom `queryClient` to `query()` to use a different instance
-
-## Common Pitfalls & Solutions
-
-| Issue | Solution |
-|---|---|
-| Storage not loading | Ensure `ReqraftProvider` wraps the tree and `waitForStorage: true` (default) |
-| WebSocket not reconnecting | Check close code — `4999` suppresses reconnect (intentional close) |
-| Multiple sockets for same URL | Default is pooled; set `pooled: false` only when independent connections are needed |
-| 401 loop | Verify `unauthorizedRedirect` is not pointing back to a protected route |
-| `query()` returning stale data | Pass `cache: false`; POST/DELETE bypass cache automatically |
-| Heartbeat noise in logs | Filter `ev.data === 'pong'` — already done inside `useReqraftWebSocket` |
-| Storage path collisions | Use `includeAppPrefix: true` in `useReqraftStorage` to namespace per app |
-| Story shows FormEngine's loading skeleton / "Connecting to language server…" forever | An unmocked request or a connection inherited from an earlier story — see "Story network" above |
-| "No Preview — Sorry, but you either have no stories…" in a story failure | Not a registration failure: addon-vitest injects Storybook's hidden preview body into every test page, and a failed query's DOM dump prints it. Read the assertion above the dump |
-| A story run stops reporting and never times out (no failure, no output) | The page's main thread is blocked, so the in-page 30s test timer cannot fire — usually a synchronous render loop inside `act()`. Find the story with `--reporter=verbose` (the last ✓ is the one before it), then give Chromium `launchOptions: { args: ['--remote-debugging-port=9333'] }` in `vitest.config.ts` locally, enable `Debugger` over CDP BEFORE the freeze, and `Debugger.pause` once `Runtime.evaluate` stops answering to get the stack. Revert the config afterwards |
-| `yarn test:stories` hangs before any test runs (the port message is incidental) | Seen when the checkout path contains `+` — e.g. an auto-named `.claude/worktrees/fix+name` — while the same tree at a `+`-free path runs normally. Use a path without `+` |
-
-## File Reference
-
-| Path | Purpose |
-|---|---|
-| `src/index.tsx` | Main export barrel |
-| `src/providers/ReqraftProvider.tsx` | Root provider + `initializeReqraft` |
-| `src/providers/FetchProvider.tsx` | Exposes `get/post/put/del` via FetchContext |
-| `src/providers/StorageProvider.tsx` | Loads user storage; wraps children |
-| `src/utils/fetch.ts` | Core fetch + caching via react-query |
-| `src/utils/websocket.ts` | `ReqraftWebSocket` + `ReqraftWebSocketsManager` |
-| `src/utils/datetime.ts` | Datetime helpers (e.g., `getCurrentTimeWithMilliseconds`) |
-| `src/hooks/useFetch/` | `useFetch` hook |
-| `src/hooks/useWebSocket/` | `useReqraftWebSocket` hook |
-| `src/hooks/useStorage/` | `useReqraftStorage` hook |
-| `src/stores/currentUser/` | Zustand store for the authenticated user |
-| `src/contexts/ReqraftContext.tsx` | App-level context (`appName`) |
-| `src/contexts/FetchContext.tsx` | HTTP method context |
-| `src/contexts/StorageContext.tsx` | User storage context |
-| `src/components/form/` | Form field components |
-| `src/components/log/` | Log display component |
-| `src/components/menu/` | Navigation menu component |
-| `src/tracking/` | First-party tracking, consent and A/B testing (`core/` no DOM, `browser/`, `react/`, and `ui/`: the A/B test card and overlay on Reqore); how-to in `design/TRACKING.md` |
-| `src/types/` | Shared TypeScript types |
-| `__tests__/` | Vitest unit tests (jsdom) |
-
-## Other
-
-- This library is a **peer-dependency consumer** of ReQore — do not copy ReQore internals here; import from `@qoretechnologies/reqore` instead
-- `yarn update-reqore` updates ReQore to the latest beta

package/.tasks/EXPORT_EXPRESSION_BUILDER.md

@@ -1,38 +0,0 @@
-# TASK — export the bare `ExpressionBuilder` from the form barrel
-
-**Status:** committed `0eea9e7`, pushed (branch `feature/119_export-expression-builder`), PR open — awaiting CI + review
-
-Issue: [toolkit-react#119](https://github.com/qoretechnologies/toolkit-react/issues/119).
-Design: [`design/IDE_INTEGRATION.md`](../design/IDE_INTEGRATION.md) (the shell-at-root / bare-builder-nested rule;
-revised note added in this task).
-
-## Why
-
-The library's own `TemplateField` renders the `ExpressionField` shell for a root field (FormEngine sets
-`allowTextExpressions`) and the bare `ExpressionBuilder` for nested operands — the June 11 "top-level
-re-wrap" decision in `FIELD_STACK_REPORT.md`. The barrel exported the shell but not the builder, so a host
-mirroring that rule (qorus-ide's `template.tsx`) had to deep-import `dist/components/form/expressions/builder`.
-
-## Surface area
-
-| File | Change |
-|---|---|
-| `src/components/form/index.tsx` | `export { ExpressionBuilder }` + `export type { IExpressionBuilderProps }` next to the shell |
-| `__tests__/formBarrelExports.test.ts` | asserts both come from the barrel — fails if the export is removed |
-| `design/IDE_INTEGRATION.md` | one-line revision under "the shell is the host's component" |
-| `package.json` | `0.10.52` → `0.10.53` (single bump) |
-
-## Phases
-
-- [x] export + type export
-- [x] unit test through `yarn test`
-- [x] `build:test:prod` green
-- [ ] `yarn precheck` (lint + unit + prod tsc)
-- [ ] **STOP — user verifies before commit** (no visual surface: nothing to click; the test is the proof)
-- [ ] `/audit`, commit, push, PR, CI, qlip (expect 0 changed snapshots)
-
-## Not this task
-
-toolkit-react#120 was filed alongside this and closed as invalid: both operand mounts have forwarded
-`expressions_url` since the port (5905e52); the symptom was qorus-ide's raw-catalogue override on its own
-legacy builder, fixed there.

package/.tasks/EXPRESSION_BUILDER_REPORT.md

@@ -1,149 +0,0 @@
-# TASK — Expression Builder verbatim re-port
-
-**Status:** Phases A + B + C DONE & verified (uncommitted), including the
-follow-ups (shell-chrome polish, the `validations` `'expression'` case — both
-ticked in Phase C below; the `'expression'` validator gained jest coverage
-2026-06-11). The ported, IDE-matching builder is live in `ExpressionField` /
-FormEngine. Phase D (server render-expression) + E (IDE consumes reqraft) are
-out of scope.
-Design:
-`design/EXPRESSION_BUILDER_REPORT_STRATEGY.md`. Supersedes the from-scratch
-visual builder in `.tasks/FORM_ENGINE_EXPRESSIONS.md` (plumbing retained).
-
-Method (Filip): copy IDE components **and their tests** verbatim → get them
-1:1 + green → then improve. Compare to qorus-ide Storybook **:6007** between
-phases. **No commits until user verifies.**
-
-## Surface area
-
-| Area | reqraft path | IDE source |
-|---|---|---|
-| Type-compat helpers | `src/helpers/expressions.ts` (NEW) | `qorus-ide/src/helpers/expressions.ts` |
-| `areQorusTypesCompatible` | `src/helpers/…` | `qorus-ide/src/helpers/functions.tsx` |
-| `validateField` export | `src/helpers/validations.ts` | (export the existing `_validateField`) |
-| Select flat/intent | `src/components/form/fields/select/Select.tsx` | `qorus-ide` Field/select |
-| TemplateField expr path | `src/components/form/fields/template/TemplateField.tsx` | `qorus-ide` Field/template |
-| ExpressionBuilder | `src/components/form/expressions/builder/**` (NEW) | `qorus-ide/src/components/ExpressionBuilder/**` |
-| Builder tests | `…/builder/*.stories.tsx` | `qorus-ide/src/stories/Components/ExpressionBuilder.stories.tsx` |
-
-## Phase A — Field-stack parity (leaf) — DONE & verified (2026-06-10)
-
-- [x] `src/helpers/expressions.ts` — verbatim port of getArgumentType,
-      argumentMatchesType (from IDE expressions.ts) + areQorusTypesCompatible
-      (from IDE functions.tsx); imports adapted (getQorusTypes/defaultQorusTypes
-      from reqraft `useQorusTypes`). Typechecks.
-- [x] `validateField` — already exported from validations.ts (no change needed)
-- [x] `SelectFormField` — `flat` + `intent` now forwarded (additive; defaults
-      preserve current look). This is the fix Filip named: "make it flat and
-      small and it looks the same." The chip can now go borderless.
-- [x] **GATE:** jest 267/267, full storybook **188/189** (pre-existing flaky
-      only). No regression from the shared Select change.
-- Note: `TemplateField`'s `allowFunctions`/`isFunction` mechanism moved to
-  Phase B — it's circularly dependent with the ExpressionBuilder (TemplateField
-  renders the builder; the builder renders TemplateField), so they land
-  together. Phase B builds in a NEW dir so the current build stays green.
-
-## Phase B — Verbatim ExpressionBuilder + tests — DONE & verified (2026-06-10)
-
-- [x] 9 IDE files copied verbatim into `src/components/form/expressions/builder/`
-      (index.tsx ~1260 LOC + item/argumentWrapper/argumentLabel/argumentDetail/
-      argumentInfo + the two confirm modals + renderTemplate). JSX/markup/props
-      preserved; only imports/hooks/types/seams changed.
-- [x] Seams: AiAssistanceAction **removed**; `renderTemplate` rewritten to use
-      reqraft `useRenderExpression` (client-side, no Creator-WS);
-      `useRegisterHintView` **stubbed**.
-- [x] `TemplateField` — additive `allowFunctions`/`isFunction`; when set, renders
-      the ported builder. Absent → unchanged (field migration safe).
-- [x] Adaptations: `Select` `defaultItems`→`items`; `Select.onChange` single-arg;
-      catalogue passed as `override` (replaces fetch) **and threaded through the
-      group recursion** so offline/CI is deterministic (badge = mock count, not
-      the live 121). `auto`/`Select`/`TemplateField` import aliases.
-- [x] Ported `ExpressionBuilder.stories.tsx` (the IDE play tests) — offline via
-      `mockExpressions`. **10/10 pass.**
-- [x] **GATE:** renders **1:1 vs :6007** (verified by screenshot — chips, underline
-      fields, operator words, group nesting, type-pickers, collapse/Explain all
-      match). eslint clean, jest 267/267, full suite **198/199** (pre-existing
-      flaky only). Old from-scratch builder left intact; build green.
-- Open follow-ups (Phase C / refinements): wire into `ExpressionField`;
-      `validations` has no `'expression'` type case yet (per-expression validity
-      tag always "valid"); `useRenderExpression` is the client-side approximation.
-
-## Phase C — Re-wrap reqraft features — DONE & verified (2026-06-10)
-
-- [x] `ExpressionField` Visual mode now renders the **ported** builder
-      (`./builder`); Text = `DpqlEditor`; Explain/Preview from the shell.
-      Adapted: `onChange (value, remove?)`, `returnType` cast, and
-      **`localTemplates={{ items: [] }}`** (the builder's `filterTemplatesFunc`
-      does `templates.items.filter(...)` — undefined templates crashed it;
-      caught via the error boundary during verify and fixed).
-- [x] From-scratch `ExpressionBuilder.tsx` + its stories **retired** (deleted);
-      no remaining references.
-- [x] **GATE:** FormEngine field → ExpressionField → ported builder verified
-      (ViaFormEngine + the toggle path). jest 267/267, full suite **193/193**
-      (the flaky `OnValidityChange` even passed). HEAD unchanged.
-- [x] **Shell cleanup (done 2026-06-10):** Visual mode now renders ONLY the
-      ported builder (it has its own Explain). The shell's Explain + Preview +
-      Explanation are scoped to **Text mode** (where the DpqlEditor has none).
-      ExpressionField play tests updated to assert the builder rendered.
-- [x] **Danger-border fix (done 2026-06-10):** three parts —
-      (1) ported the IDE's `validations` **`'expression'` case** (reads the
-      catalogue from `field.expressions`); (2) `FormEngine.isOptionValid` now
-      passes `isFunction` from the field value's `is_expression` (the per-field
-      red intent used the base-type check); (3) `ExpressionField` defaults
-      `returnType` to `'auto'` so a valid expression card renders `muted` not
-      `danger`. Verified: the FormEngine expression field is no longer red.
-      eslint clean, jest 267/267, full suite 192/193 (pre-existing flaky only).
-- [x] **Oversized chips/pickers fix (2026-06-10):** root cause — the IDE's
-      `Select` spreads `{...rest}` into its rendered ReqoreButton/Dropdown/Tag,
-      so the builder's verbatim `size='tiny'` reaches ReQore; reqraft's
-      `SelectFormField` accepted `size` in its interface but **never forwarded
-      it** (same class of bug as `flat`/`intent`). Forwarded `size` to all four
-      render branches (bound as `componentSize` — plain `size` would shadow
-      lodash's `size(items)` badge count). Chips now tiny, type pickers
-      compact, operand rows no longer wrap — density matches the IDE.
-      jest 267/267, full suite 192/193 (pre-existing flaky only).
-- Known seam: reqraft's `SelectFormField` still doesn't rest-spread like the
-      IDE's — `flat`/`intent`/`size` are forwarded explicitly; any other
-      pass-through prop the verbatim IDE markup relies on needs the same
-      treatment if a gap shows up.
-- [x] **Type-picker parity (2026-06-10):** `AutoFormField` now matches the
-      IDE's AutoField — unresolved type shows **`auto`** as the selected picker
-      label (not a "Select a type" placeholder; `auto` is not a pickable item
-      so the badge count stays identical to the IDE's 9/14), and the hint is
-      the IDE's orange minimal `ReqoreTag` **"Please select data type"**
-      (was a grey info tag). The 3 AutoFormField story assertions updated.
-- [x] **AI-assist slot (2026-06-10):** the IDE's purple hover button on each
-      expression card is `AiAssistanceAction` → `AiButton` (sends the selected
-      expression's context to the IDE's AI chat). It was one of the three
-      deliberate port seams — `AiButton` depends on IDE-only infrastructure
-      (AI context, SystemStore, QonsoleStore, Creator-WS) that reqraft doesn't
-      have. Added **`extraActions?: IReqorePanelAction[]`** to the ported
-      builder (threaded through the group recursion, prepended exactly where
-      the IDE renders the AI action) so the IDE injects its AiButton at
-      Phase E. jest 267/267, full suite 192/193 (pre-existing flaky only).
-- [x] **`extraActions` upgraded to a factory (2026-06-10):** a static array
-      could not reproduce the IDE's button — the IDE builds
-      `AiAssistanceAction({ context: selectedExpression })` *inline per card*.
-      The seam now also accepts
-      `(ctx: { selectedExpression?, value? }) => IReqorePanelAction[]`,
-      resolved inside each `Expression` with that card's selected schema —
-      so Phase E restores the AI button 1:1, per-card context included.
-      Proven by the new `WithInjectedExtraActions` story (hover → injected
-      action present; 11/11 ported play tests). Full suite **194/194**
-      (even the flaky `OnValidityChange` passed), jest 267/267.
-- Ops note: the Storybook dev server reliably wedges on HMR after edits to
-      these files (symptom: play tests fail in ~2ms with
-      `ReferenceError: __test is not defined`, preview stuck on spinner).
-      A clean restart fixes it every time — restart before trusting failures.
-
-## Phase D — Server (tracked, not in reqraft)
-
-- [x] `render-expression` over LSP/REST; swap `useRenderExpression` —
-      picked up 2026-06-10 in `.tasks/RENDER_EXPRESSION_LSP.md` (branch
-      `feature/render-expression-lsp`): new LSP `dpql/renderExpression`
-      (server code written, deploy pending) + server-first hook with
-      client-side fallback. Design: `design/RENDER_EXPRESSION_TRANSPORT.md`.
-
-## Phase E — Dedupe (not now)
-
-- [ ] IDE consumes reqraft's builder

package/.tasks/EXPRESSION_FIELD_SEAMS.md

@@ -1,66 +0,0 @@
-# TASK — ExpressionField seams: carry `extraActions` through the shell and into operand rows
-
-**Status:** committed `f5fb2ee`, pushed to `origin/bugfix/116_expression-field-seams` (user-verified in the browser 2026-09-07) — no PR yet; CI here runs on pull requests only
-
-Issue: [toolkit-react#116](https://github.com/qoretechnologies/toolkit-react/issues/116).
-Design: [`design/IDE_INTEGRATION.md`](../design/IDE_INTEGRATION.md) (seam table; revised 2026-09-07 in this task).
-Consumer that surfaced it: qorus-ide [PR #275](https://github.com/qoretechnologies/qorus-ide/pull/275) — the IDE swapped its
-legacy builder for `ExpressionField` and its AI-assist button vanished from every expression card.
-
-## Why
-
-`IDE_INTEGRATION.md` names `extraActions` as the seam the IDE re-attaches its AI button through. The
-seam existed on `ExpressionBuilder`, but (a) hosts mount the `ExpressionField` shell, which neither
-declared nor forwarded it, and (b) the builder's two operand `TemplateField` mounts passed nothing
-host-injected, so an operand that is itself an expression lost it again. The group recursion
-(`&&` / `||`) already forwarded it, which is why the existing builder story stayed green while the
-IDE regressed. Not a gap: `expressionsUrl` — the shell resolves it in its own `useExpressions` and
-hands the merged catalogue down (an earlier draft of #116 claimed otherwise; corrected).
-
-## Surface area
-
-| File | Change |
-|---|---|
-| `src/components/form/expressions/ExpressionField.tsx` | declare `extraActions?: IExpressionBuilderProps['extraActions']`, forward to the builder mount |
-| `src/components/form/fields/template/TemplateField.tsx` | declare + destructure `extraActions` (so it never rides `rest` into a leaf input); forward to both editors expression mode renders |
-| `src/components/form/expressions/builder/index.tsx` | pass `extraActions` into both operand `TemplateField` mounts; rest-argument mount takes the catalogue's declared `ui_type` when the argument is empty (qlip #189 rejection) |
-| `src/components/form/fields/select/SelectCollection.tsx` | `className='reqraft-select-dialog'` on the picker modal — a library-owned hook for hosts' tests |
-| `src/components/form/expressions/ExpressionField.stories.tsx` | `NestedOperandKeepsInjectedActions` — shell hop + operand hop, assertion scoped to the nested card; the injected action is the IDE's `AiButton` presentation verbatim (`ReqoreButton` + the resolved `SynthColorEffect`), click stubbed |
-| `design/IDE_INTEGRATION.md` | AI-assist row revised; dead `BRANCH_REMEDIATION.md` reference removed; "the shell is the host's component" note |
-| `package.json` | `0.10.50` → `0.10.51` (single bump from the current `develop` tip `4860e6e`, after #114 merged and published 0.10.50; CI's PR job accepts exactly one patch over the base, so #115 and #117, both still at 0.10.50, must re-bump before they can merge) |
-
-## Phases
-
-### 1 — seams
-- [x] `ExpressionField`: declare + forward
-- [x] `TemplateField`: declare, destructure, forward to `<ExpressionField>` and `<ExpressionBuilder>`
-- [x] builder: both operand mounts
-- [x] picker modal class
-- [x] `yarn build:test` + `yarn lint` clean
-
-### 2 — coverage
-- [x] story written (description in the mandated shape)
-- [x] `yarn test:stories ExpressionField` green (8/8); qlip PNG of the new story read — the magic-wand action sits in BOTH card headers, the nested operand's included; capture dir deleted
-
-### 3 — docs
-- [x] design doc revised with dated notes
-- [x] `.tasks/INDEX.md` row
-- [x] `VERIFY.local.md` written for the click-through
-
-### 4 — gate
-- [x] **STOP — user verified in the browser** (2026-09-07, on :6009)
-- [x] `/audit` — run by following `instruction-files/skills/audit-frontend/SKILL.md` directly (the skill is not linked into `~/.claude/skills/` on this machine); re-run after the last story edit; clean
-- [x] commit `f5fb2ee` (no attribution trailer), pushed
-- [ ] open the PR (CI + qlip build only run on a pull request), `ci-monitor`, qlip review
-
-### 5 — qlip #189 rejection (Foxhoundn)
-- [x] empty rest argument rendered as untyped `auto` under a "true or false" label; empty `any` never reached the template-selector default → declared-type fallback in the rest-argument mount; both expression story files 30/30; verified in the browser on `NestedOperandKeepsInjectedActions`, `WithComplexValue`, and `DefaultBoolean` → Logical Equals
-- [x] design note in `design/EXPRESSION_BUILDER_REPORT_STRATEGY.md` (Revised 2026-09-08)
-- [ ] rejection table shown to the user → push → CI → qlip re-review
-
-## Out of scope (no designed seam yet — needs a design decision first)
-
-Saved values at operand level (the builder owns operand `menuItems` for its type picker → additive
-seam required; the feature is switched off in every IDE surface today), translations, tour
-registration, the guided server-expression flow, dropdown search copy, the picker's action-name
-badge. Listed in #116.