@pega/custom-dx-components 26.1.11 → 26.1.12-alpha-0.1

package/README.md

@@ -37,9 +37,13 @@ Ensure you have access to the following in your system:
 
 - Git version 2.30 or later
 
-- System node version >= 24.4.1
+- System node version >= 24.22.1
 
-- System npm version 11.4.2
+- System npm version 11.19.1
+
+## AI-assisted component development
+
+Projects created with DX Component Builder include AI skills and project rules that work in **GitHub Copilot, Claude Code, Cursor, Codex CLI and Gemini CLI**: 32 skills covering every component type, the CLI workflow, and an exhaustive PCore/PConnect API catalog, installed once at `init` with no extra package or setup. It is optional: answer "No" to the "Enable AI-assisted component development?" prompt during `init`, or run `init --noAi`, to create a project without any of it, and switch it off or on later with `npm run disableAi` / `npm run enableAi`. See the generated project's `README.md` for details.
 
 ## Latest Documentation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pega/custom-dx-components",
-  "version": "26.1.11",
+  "version": "26.1.12-alpha-0.1",
   "description": "Utility for building custom UI components",
   "bin": {
     "custom-dx-components": "./bin/index.js"
@@ -20,87 +20,70 @@
   "author": "Custom component dev",
   "sideEffects": false,
   "type": "module",
+  "engines": {
+    "node": ">=24.20.0"
+  },
   "scripts": {
-    "lint:es": "eslint --color --cache --cache-location node_modules/.cache/eslint/ \"src/**\"",
+    "lint:es": "eslint --no-config-lookup -c eslint.config.mjs --color --cache --cache-location node_modules/.cache/eslint/ \"src/**\"",
     "lint:format": "prettier -c \"src/**\"",
     "lint:spelling": "cspell **/*",
-    "fix:es": "eslint --fix .",
+    "fix:es": "eslint --no-config-lookup -c eslint.config.mjs --fix .",
     "fix:format": "prettier -w \"src/**\"",
     "test:unit:local": "node --input-type=module  --experimental-vm-modules node_modules/jest/bin/jest.js --runInBand --coverage=false /tests/unit",
     "test:functional:local": "jest --runInBand /tests/functional --detectOpenHandles --coverage"
   },
   "dependencies": {
-    "@babel/core": "^7.28.0",
-    "@babel/plugin-transform-class-properties": "^7.27.1",
-    "@babel/preset-react": "^7.27.1",
-    "@pega/auth": "^0.2.37",
-    "@pega/constellation-dx-components-build-utils": "^2.0.11",
-    "@pega/inquirer-fuzzy-path": "^3.0.0",
+    "@pega/auth": "^1.0.0",
+    "@pega/constellation-dx-components-build-utils": "^2.0.17",
+    "@pega/inquirer-fuzzy-path": "^4.0.0",
     "ajv": "^8.17.1",
-    "ajv-keywords": "^5.1.0",
     "archiver": "^7.0.1",
     "arg": "^5.0.2",
-    "babel-loader": "^10.0.0",
-    "chalk": "^5.4.1",
-    "check-git": "^2.0.2",
-    "compression-webpack-plugin": "^11.1.0",
-    "css-loader": "7.1.2",
-    "css-minimizer-webpack-plugin": "^7.0.2",
-    "eslint": "^9.36.0",
-    "execa": "^9.6.0",
+    "chalk": "^6.0.1",
+    "compression-webpack-plugin": "^12.0.0",
+    "css-loader": "7.1.5",
+    "css-minimizer-webpack-plugin": "^8.0.0",
+    "eslint": "^10.11.0",
+    "execa": "^10.0.1",
     "file-loader": "6.2.0",
-    "fs-extra": "^11.3.0",
-    "gitignore": "^0.7.0",
-    "inquirer": "^9.3.7",
+    "inquirer": "^9.3.8",
     "jwt-decode": "^4.0.0",
-    "listr2": "^8.3.3",
-    "mini-css-extract-plugin": "2.9.2",
+    "listr2": "^11.1.0",
+    "mini-css-extract-plugin": "2.10.2",
     "mustache": "^4.2.0",
-    "ncp": "^2.0.0",
-    "node-fetch": "^3.3.2",
-    "node-stream-zip": "^1.15.0",
-    "ora": "^8.2.0",
+    "node-stream-zip": "^1.16.0",
+    "ora": "^9.4.1",
     "pascalcase": "^2.0.0",
     "postcss": "^8.5.6",
-    "postcss-loader": "8.1.1",
-    "postcss-preset-env": "10.2.4",
-    "prop-types": "^15.8.1",
-    "react": "^18.2.0",
+    "postcss-loader": "8.2.1",
+    "postcss-preset-env": "11.5.4",
     "react-dev-utils": "^12.0.1",
-    "resolve": "1.22.10",
     "resolve-url-loader": "^5.0.0",
-    "sass-loader": "^16.0.5",
-    "terser-webpack-plugin": "5.3.14",
-    "ts-loader": "^9.5.2",
-    "typescript": "~5.8.3",
+    "sass-loader": "^17.0.1",
+    "terser-webpack-plugin": "5.6.1",
+    "ts-loader": "^9.6.2",
+    "typescript": "~5.9.3",
     "unarchive": "^1.1.3",
-    "undici": "^7.21.0",
+    "undici": "^7.30.0",
     "url-loader": "4.1.1",
-    "webpack": "5.101.0",
-    "webpack-cli": "^6.0.1"
+    "webpack": "5.111.1"
+  },
+  "overrides": {
+    "glob": "^13.0.0",
+    "serialize-javascript": "^7.0.5",
+    "webpack": "$webpack"
   },
   "devDependencies": {
-    "@babel/preset-env": "^7.28.0",
-    "@pega/configs": "^0.17.0",
-    "@pega/prettier-config": "^0.17.0",
-    "@types/jest": "^29.5.14",
-    "@typescript-eslint/eslint-plugin": "^6.15.0",
-    "@typescript-eslint/parser": "^8.34.1",
-    "babel-jest": "^29.7.0",
-    "cspell": "^8.19.4",
-    "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-jest": "^27.6.2",
-    "eslint-plugin-jsx-a11y": "^6.8.0",
-    "eslint-plugin-prettier": "^5.5.4",
-    "eslint-plugin-react": "^7.33.2",
-    "eslint-plugin-react-hooks": "^4.6.0",
-    "eslint-plugin-sonarjs": "^0.23.0",
-    "eslint-plugin-storybook": "^0.6.15",
-    "jest": "^29.7.0",
-    "jest-environment-jsdom": "^29.7.0",
-    "jest-junit": "^16.0.0",
-    "prettier": "3.6.2",
-    "ts-jest": "^29.4.0",
-    "typescript-eslint": "^8.44.1"
+    "@babel/preset-env": "^7.29.7",
+    "@eslint/js": "^10.0.1",
+    "@types/jest": "^30.0.0",
+    "babel-jest": "^30.5.2",
+    "cspell": "^10.3.5",
+    "globals": "^17.12.0",
+    "jest": "^30.5.2",
+    "jest-environment-jsdom": "^30.5.2",
+    "jest-junit": "^17.0.0",
+    "prettier": "^3.9.9",
+    "typescript-eslint": "^8.71.0"
   }
 }

package/src/ai/README.md

@@ -0,0 +1,44 @@
+# AI assets (maintainer notes)
+
+Everything the CLI ships for AI coding tools lives here. Nothing in this folder is copied to customers except `project/`, `catalog/` and `readme-section.md`; this file stays in the CLI repo.
+
+| Path                | What it is                                                                                              | Installed to                                        |
+| ------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| `project/`          | Mirrors the project root: `AGENTS.md`, `.gemini/`, and the component skills in `.claude/skills/` | The project root                                    |
+| `catalog/`          | The PCore/PConnect skills, `references/` and `best-practices/`                                          | `.claude/skills/` (and `.agents/skills`, a link)    |
+| `readme-section.md` | The README section describing the AI setup, between `ai-agents` marker comments                         | Inserted before `## Latest Documentation`           |
+| `index.js`          | `enableAgentFiles`, `removeAgentFiles`, `hasAgentFiles`, used by `init`, `enableAi` and `disableAi`. It also adds and removes a marked block in the project's `.prettierignore` | |
+
+The install and remove file lists are derived from these folders, so adding a skill means adding a folder and nothing else. Skill folders must be one level deep and uniquely named (Claude Code only scans one level); `tests/unit/ai-assets.test.js` enforces this, along with valid frontmatter, working links and manifest paths.
+
+## Adding or changing a component skill
+
+Edit `project/.claude/skills/<name>/`. If it is a new component subtype, also add it to `project/.claude/skills/generate-component-set/component-manifest.json` (with its `cliSubtype` and skill path) and to the routing list in `project/AGENTS.md`. Run `npm run test:unit:local`.
+
+## Where rules live
+
+Keep `SKILL.md` files free of inline code: they hold instructions, routing and pointers, and a unit test fails if one carries more than a few fenced lines. Code skeletons, handler shapes and snippets belong in `references/`, `cookbooks/` or `assets/`, and config properties are listed as tables. Write each rule once, in a skill reference under `project/.claude/skills/create-dx-component/references/`, because every AI tool reads skills. `project/AGENTS.md` loads on every request, so it carries only repo-wide rules and compact routing; keep it under about 9 KB. There are no tool-specific instruction files, Copilot prompt files or custom agents: batch generation and design analysis are skills (`generate-component-set`, `identify-components`) so they work in every tool.
+
+Generation speed depends mostly on how much an agent must read before writing code. Each type has one `*-essentials.md` reference (field, widget, template, presentation) with the must-follow rules for every component file and a closing table of when to open a deeper reference. Agents read the essentials file instead of the deep references. When you add or change a must-follow rule in a deep reference, update the matching essentials file too, and keep each one under about 9 KB. The type skills (`field`, `widget`, `template`, `presentation`) hold only routing, the contract items, the scaffold command and a pointer to their essentials file.
+
+## Re-syncing the catalog from corejs
+
+`catalog/` is a snapshot of `packages/corejs/skills` in the constellation-frontend repo. It is not generated, so re-syncing is manual, and **a plain copy over `catalog/` loses fixes**:
+
+- The snapshot was type-checked against `@pega/pcore-pconnect-typedefs`. Roughly 30 documented signatures and payloads were corrected (for example `loadView`, `openEmbeddedDataModal`, `refreshCaseView`, `acceptSuggestion`, tag, participant and follower payloads, conversation IDs). Those corrections do not exist in corejs unless they were ported back.
+- Monorepo-only references were removed, and each `pconnect-*` skill carries `metadata.verified-against`.
+
+To re-sync:
+
+1. Diff corejs against `catalog/` (`diff -r`) and read the diff before copying anything. Take new or changed content; keep the local corrections or port them upstream first.
+2. Keep customer-facing text free of monorepo paths and internal terms.
+3. Keep custom frontmatter keys under `metadata:`. The shared Agent Skills format that Claude Code, Copilot and Cursor read does not allow bare custom keys.
+4. Type-check every fenced TypeScript block in the changed docs against the installed typedefs, and compare each documented method signature (required and optional parameters) with the typedefs. Fix mismatches in the docs.
+5. Update `metadata.verified-against` only for skills you re-verified.
+6. Run `npm run test:unit:local`, `npx prettier -c "src/**"` and `npx cspell "**/*"`. Allow-list new domain words in `cspell.json`.
+
+Existing customer projects are not updated when the catalog changes: `enableAi` restores missing files but never overwrites existing ones.
+
+## Supporting another AI tool
+
+Check where the tool reads skills and project instructions before adding anything. Today: Claude Code, Copilot and Cursor read `.claude/skills`; Codex and Gemini read `.agents/skills` (a link to it); Gemini needs `.gemini/settings.json` to load `AGENTS.md`. If the tool reads one of those, nothing needs to be added. Never add a second copy of the skills.

package/src/ai/catalog/README.md

@@ -0,0 +1,133 @@
+---
+title: PCore / PConnect API Reference Skills
+description: 'Index of the six PCore/PConnect skills, their shared method-by-method reference catalog, and cross-cutting testing/security/performance/error-handling/accessibility/GenAI-integration/troubleshooting guidance, for building Pega Constellation custom components.'
+---
+
+# PCore / PConnect API Reference Skills
+
+This directory contains **six focused skills**, one per workflow area, plus a **shared reference catalog** (`references/`) that all six draw from. Splitting by workflow keeps each skill's `SKILL.md` narrowly scoped and loadable on its own, while the shared catalog avoids duplicating method-signature facts across skills.
+
+Every API documented here was verified against the latest 26.x release.
+
+Each skill is self-contained — it does not assume access to Pega's internal source code, only the public runtime APIs available to any component at runtime. Only the documented public API surface is covered; methods marked internal, private, or unstable in Pega's own API documentation are intentionally excluded — treat anything not listed here as unsupported and subject to change without notice.
+
+## The Six Skills
+
+| Skill                                                                                    | Covers                                                                                                        |
+| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| [pconnect-assignment-lifecycle/SKILL.md](./pconnect-assignment-lifecycle/SKILL.md)       | Opening, validating, submitting, and deleting assignments/cases; attachments; destructive-action confirmation |
+| [pconnect-forms-and-fields/SKILL.md](./pconnect-forms-and-fields/SKILL.md)               | Form/field validation, cascading dependent fields, autosave tracking, persisting custom widget UI state       |
+| [pconnect-data-subscriptions/SKILL.md](./pconnect-data-subscriptions/SKILL.md)           | Data page subscriptions, application-wide pub/sub, real-time server-pushed case updates                       |
+| [pconnect-case-collaboration/SKILL.md](./pconnect-case-collaboration/SKILL.md)           | Participants, followers, related cases, tags                                                                  |
+| [pconnect-lists-and-views/SKILL.md](./pconnect-lists-and-views/SKILL.md)                 | Repeating row edits, saved list view personalization, non-assignment container item lifecycle                 |
+| [pconnect-navigation-locale-genai/SKILL.md](./pconnect-navigation-locale-genai/SKILL.md) | Deep links/semantic URLs, locale switching, GenAI Assistant conversations                                     |
+
+Each skill's `SKILL.md` covers its own file-listing table and cookbook index. Start with the skill whose topic matches your task; consult [Architecture at a Glance](./references/architecture-overview.md) first if you're new to PCore/PConnect.
+
+## Shared Reference Catalog
+
+[`references/`](./references/) contains method-by-method reference files shared by all six skills above — each file documents a group of methods with a **signature**, a **purpose**, and a minimal **example**.
+
+### PCore APIs
+
+| File                                                                                                   | Covers                                                                                                                                     |
+| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| [references/pcore-bootstrap-registry-routing.md](./references/pcore-bootstrap-registry-routing.md)     | Bootstrap lifecycle, component/module registration, routing, view resources                                                                |
+| [references/pcore-store-context-state.md](./references/pcore-store-context-state.md)                   | Redux-backed store access, context tree, state machines, object diffing                                                                    |
+| [references/pcore-environment-locale-namespace.md](./references/pcore-environment-locale-namespace.md) | Environment info, locale switching, namespace utilities, auth, network status                                                              |
+| [references/pcore-rest-data-messaging.md](./references/pcore-rest-data-messaging.md)                   | REST client, data pages/views, cascade, messaging, pub/sub, events, refresh, expressions                                                   |
+| [references/pcore-case-collaboration-genai.md](./references/pcore-case-collaboration-genai.md)         | Containers, attachments, feed, tags, stakeholders, user, related cases, GenAI, analytics, personalization                                  |
+| [references/pcore-misc-utilities.md](./references/pcore-misc-utilities.md)                             | Constants, behavior overrides, error handling, forms, autosave, debug, mashup bridge, field/annotation utilities, asset loader, navigation |
+
+### PConnect APIs
+
+| File                                                                                                       | Covers                                                                         |
+| ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| [references/pconnect-state-config.md](./references/pconnect-state-config.md)                               | State & configuration management, data access & property manipulation          |
+| [references/pconnect-reference-context-component.md](./references/pconnect-reference-context-component.md) | Page/view reference, context & container management, component information     |
+| [references/pconnect-case-validation-utilities.md](./references/pconnect-case-validation-utilities.md)     | Case & data info accessors, validation/condition checks, sub-API access points |
+| [references/pconnect-misc-suggestions-creation.md](./references/pconnect-misc-suggestions-creation.md)     | Utilities & services, suggestions handling, component creation                 |
+
+### Sub-API Deep Dives
+
+| File                                                                                                                 | Class                                         | Obtained via                                                                   |
+| -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------ |
+| [references/pconnect-actions-api.md](./references/pconnect-actions-api.md)                                           | `ActionsApi`                                  | `pConn.getActionsApi()`                                                        |
+| [references/pconnect-validation-api.md](./references/pconnect-validation-api.md)                                     | `ValidationApi`                               | `pConn.getValidationApi()`                                                     |
+| [references/pconnect-container-manager.md](./references/pconnect-container-manager.md)                               | `ContainerManager`                            | `pConn.getContainerManager()`                                                  |
+| [references/pconnect-case-info-data-info-localization.md](./references/pconnect-case-info-data-info-localization.md) | `CaseInfo`, `DataInfo`, `LocalizationService` | `pConn.getCaseInfo()`, `pConn.getDataInfo()`, `pConn.getLocalizationService()` |
+| [references/pconnect-list-actions.md](./references/pconnect-list-actions.md)                                         | `ListActions`                                 | `pConn.getListActions()`                                                       |
+
+### PCore Sub-API Method Details
+
+The files above cover each `PCore.get*()` accessor's own signature. The files below catalog the methods on the _objects those accessors return_ (for example, what you can call on the `EnvironmentInfo` object returned by `PCore.getEnvironmentInfo()`).
+
+| File                                                                                               | Covers                                                                                                                                         |
+| -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| [references/pcore-environment-info-details.md](./references/pcore-environment-info-details.md)     | `EnvironmentInfo`, `LocaleUtils`, `AuthUtils`                                                                                                  |
+| [references/pcore-rest-data-details.md](./references/pcore-rest-data-details.md)                   | `RestClient`, `DataApi`, `DataApiUtils`, `DataPageUtils`, `DataTypeUtils`, `CascadeManager`, `MashupApi`                                       |
+| [references/pcore-messaging-details.md](./references/pcore-messaging-details.md)                   | `SemanticUrlUtils`, `MessageManager`, `PubSubUtils`, `Events`, `MessagingServiceManager`                                                       |
+| [references/pcore-case-collaboration-details.md](./references/pcore-case-collaboration-details.md) | `ContainerUtils`, `AttachmentUtils`, `FeedUtils`, `TagUtils`, `StakeholderUtils`, `UserApi`, `CaseFollowerApi`, `CaseUtils`, `RelatedCasesApi` |
+| [references/pcore-analytics-genai-details.md](./references/pcore-analytics-genai-details.md)       | `AnalyticsUtils`, `GenAIAssistantUtils`                                                                                                        |
+| [references/pcore-bootstrap-init-details.md](./references/pcore-bootstrap-init-details.md)         | `ComponentsRegistry`, `Initialiser`, `BootstrapUtils` (mostly portal-shell/SDK-bridge internals)                                               |
+| [references/pcore-store-context-details.md](./references/pcore-store-context-details.md)           | `StateUtils`, `ContextTreeManager`                                                                                                             |
+| [references/pcore-misc-details.md](./references/pcore-misc-details.md)                             | `ErrorHandler`, `FormUtils`, `AutosaveUtils`, `MashupBridge`, `ConfirmDialogService`, `FieldDefaultUtils`, `AssetLoader`, `NavigationUtils`    |
+
+## Cross-Cutting Best Practices
+
+[`best-practices/`](./best-practices/) holds guidance that applies across all six skills rather than to one topic: how to test a component that calls these APIs, security considerations when rendering/uploading/linking with them, performance patterns (debouncing, caching, cancellation), a deliberate error-handling/resiliency strategy, accessibility for async/API-driven state, GenAI Assistant integration patterns, and a symptom-indexed troubleshooting guide for the handful of mistakes that recur across every topic area.
+
+| File                                                                                                               | Use when                                                                                                             |
+| ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| [best-practices/testing-pconnect-components.md](./best-practices/testing-pconnect-components.md)                   | Writing or reviewing a Jest/React Testing Library test for a component that calls `PCore.*` or `pConn.*`             |
+| [best-practices/security-considerations.md](./best-practices/security-considerations.md)                           | Rendering feed/comment/GenAI content, building deep links, handling uploads, authenticating, or logging errors       |
+| [best-practices/performance-and-efficiency.md](./best-practices/performance-and-efficiency.md)                     | Debouncing input, caching/invalidating data pages, canceling stale requests, or avoiding redundant subscriptions     |
+| [best-practices/error-handling-and-resiliency.md](./best-practices/error-handling-and-resiliency.md)               | Deciding how a failed call should behave (recover/retry/degrade/block), or containing a failure so it doesn't spread |
+| [best-practices/accessibility-for-async-components.md](./best-practices/accessibility-for-async-components.md)     | Announcing loading/success/error states, managing focus after navigation, or localizing status text                  |
+| [best-practices/genai-assistant-integration-patterns.md](./best-practices/genai-assistant-integration-patterns.md) | Starting/continuing a GenAI Assistant or Agent conversation, streaming responses, or handling `rewriteText` results  |
+| [best-practices/troubleshooting-common-pitfalls.md](./best-practices/troubleshooting-common-pitfalls.md)           | A method is called correctly per its signature but the behavior is still wrong — search by symptom, not method name  |
+
+## Finding a Specific Method Fast
+
+Don't guess which file covers a method by category alone — search for it directly, using the method's exact name:
+
+- Every top-level `PCore.*` / `pConn.*` method is a markdown heading in the form `` `methodName(params)` ``.
+- Every method on a _sub-API_ (an object returned by another method — for example, what `PCore.getEnvironmentInfo()` returns) is a row in a `| Method | Signature | Purpose |` table, with the method name as the first cell, still wrapped in backticks.
+- Both forms are plain text and consistently backtick-wrapped, so a literal (non-regex) full-text search for the bare method name — for example `getDebouncedSubject` or `isFormValid` — across `references/*.md` will find it regardless of which file or which form (heading vs. table row) it's in. Do not restrict a search to `^## ` headings only, or sub-API table methods will be missed.
+- If you only know the class name (e.g. `FormUtils`, `EnvironmentInfo`), search for `` (via `PCore.get...` `` or check the "PCore Sub-API Method Details" / "Sub-API Deep Dives" tables above, which map every class to its file.
+- If the question is about **order, sequencing, cleanup, or combining more than one method** to complete a task (rather than a single method's signature), check the relevant skill's `cookbooks/README.md` first — see the table above for which skill covers which topic — before assembling your own sequence from individual reference files.
+
+## Conventions Used Across These Skills
+
+- Examples use `pConn` for a `PConnect` instance and `getPConnect` for the prop function that returns one — the standard naming convention in Constellation component code.
+- Examples are minimal and illustrative, written directly from each method's documented signature and behavior — they demonstrate the calling pattern, not a specific production implementation.
+- A method's return type notes whether it resolves a `Promise` — always handle the rejection case for any API that returns one.
+- Only publicly documented, supported methods are included. If you find a method on `PCore` or `pConn` at runtime that isn't listed here, treat it as unsupported and avoid depending on it.
+
+## Coverage Roadmap
+
+### Documented across these skills
+
+- PCore top-level APIs (`PCore.*`) and PConnect / component-context APIs (`pConn.*`).
+- Sub-API deep dives: `ActionsApi`, `ValidationApi`, `ContainerManager`, `CaseInfo`, `DataInfo`, `LocalizationService`, `ListActions`.
+- Every sub-API class reachable from a documented `PCore.get*()` accessor now has its own methods cataloged (see the "PCore Sub-API Method Details" table above): `EnvironmentInfo`, `LocaleUtils`, `AuthUtils`, `NamespaceUtils`, `NetworkStatusManager`, `RestClient`, `DataApi`, `DataApiUtils`, `DataPageUtils`, `DataTypeUtils`, `CascadeManager`, `MashupApi`, `SemanticUrlUtils`, `MessageManager`, `PubSubUtils`, `Events`, `MessagingServiceManager`, `ExpressionEngine`, `ContainerUtils`, `AttachmentUtils`, `FeedUtils`, `TagUtils`, `StakeholderUtils`, `UserApi`, `CaseFollowerApi`, `CaseUtils`, `RelatedCasesApi`, `AnalyticsUtils`, `GenAIAssistantUtils`, `GenAIUtils`, `PersonalizationUtils`, `AsynchronousUtils`, `ComponentsRegistry`, `ViewResources`, `Initialiser`, `BootstrapUtils`, `StateUtils`, `ContextTreeManager`, `ErrorHandler`, `FormUtils`, `AutosaveUtils`, `MashupBridge`, `ConfirmDialogService`, `FieldUtils`, `FieldDefaultUtils`, `AnnotationUtils`, `AssetLoader`, `NavigationUtils`.
+- Some large classes (`EnvironmentInfo`, `ContainerUtils`, `CaseUtils`, `DataApi`, `AssetLoader`, `DataApiUtils`, `DataPageUtils`) are documented as a **curated subset** — methods that are purely internal framework plumbing (low-level query builders, container bookkeeping used only by the framework itself, and so on) are intentionally omitted to keep the signal-to-noise ratio high for component authors.
+- Composed, multi-method recipes for common real-world tasks (see each skill's `cookbooks/README.md`) — these chain together methods already cataloged elsewhere and call out ordering/cleanup pitfalls.
+- Cross-cutting testing, security, performance, error-handling, accessibility, GenAI-integration, and troubleshooting guidance (see [`best-practices/`](./best-practices/)) that applies across all six skills rather than to one topic.
+
+### Permanently out of scope
+
+The following classes are only reachable through a `PCore.get*()` accessor that is itself unsupported/private, so there is no supported way to obtain them — they are intentionally not documented anywhere in these skills: `RuntimeParamsAPI`, `RemoteCase`, `MetadataUtils`, `Debugger`, `DeferLoadManager`, `RefreshManager`, `AccessPrivilege`, `ObjectTransformer`, `RoutingUtils`, `CoexistenceManager`.
+
+## Related Documentation
+
+- [Using PCore and PConnect public APIs](https://docs.pega.com/bundle/pcore-pconnect/page/pcore-pconnect-public-apis/api/using-pcore-pconnect-public-apis.html) — official entry point for the public API spec.
+- [Accessing APIs from the PCore object](https://docs.pega.com/bundle/pcore-pconnect/page/pcore-pconnect-public-apis/api/accessing-apis-pcore-object.html)
+- [Accessing APIs from the PConnect object](https://docs.pega.com/bundle/pcore-pconnect/page/pcore-pconnect-public-apis/api/accessing-apis-pconnect-object.html)
+- [Working with Containers](https://docs.pega.com/bundle/pcore-pconnect/page/pcore-pconnect-public-apis/api/working-containers.html)
+- [Working with Messaging Service](https://docs.pega.com/bundle/pcore-pconnect/page/pcore-pconnect-public-apis/api/working-messaging-service.html)
+- [Initializing the Constellation environment](https://docs.pega.com/bundle/pcore-pconnect/page/pcore-pconnect-public-apis/api/initializing-constellation-environment.html)
+- [Caching and invalidating data pages](https://docs.pega.com/bundle/pcore-pconnect/page/pcore-pconnect-public-apis/api/caching-invalidating-constellation-data-pages.html)
+- [Invoking a savable data page](https://docs.pega.com/bundle/pcore-pconnect/page/pcore-pconnect-public-apis/api/invoking-savable-data-page.html)
+- [Using type definitions for PCore and PConnect APIs](https://docs.pega.com/bundle/pcore-pconnect/page/pcore-pconnect-public-apis/api/using-type-definitions-pcore-pconnect-apis.html)
+- [Pega Academy: PCore and PConnect APIs in Constellation DX components](https://academy.pega.com/topic/pcore-and-pconnect-apis-constellation-dx-components/v1)

package/src/ai/catalog/best-practices/README.md

@@ -0,0 +1,24 @@
+---
+title: Cross-Cutting Best Practices — Index
+description: Testing, security, performance, error-handling, accessibility, GenAI-integration, and troubleshooting guidance that applies across all the PCore/PConnect skills, indexed by topic and symptom for AI/RAG retrieval.
+---
+
+# Cross-Cutting Best Practices
+
+> Shared by all the skills in the [skills index](../README.md).
+
+The skills and their `references/`/`cookbooks/` folders document individual methods and multi-method recipes. This folder is different: it covers practices that apply **regardless of which topic you're working in** — how to test a component that calls these APIs, how to use them without introducing a security or accessibility issue, how to integrate GenAI Assistant conversations specifically, and how to recognize/fix the same handful of mistakes that show up across every topic area.
+
+## Guides
+
+| Guide                                                                                     | Use when                                                                                                             |
+| ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| [Testing components that use PCore/PConnect](./testing-pconnect-components.md)            | Writing or reviewing a Jest/React Testing Library test for a component that calls `PCore.*` or `pConn.*`             |
+| [Security considerations](./security-considerations.md)                                   | Rendering feed/comment/GenAI content, building deep links, handling uploads, authenticating, or logging errors       |
+| [Performance & efficiency](./performance-and-efficiency.md)                               | Debouncing input, caching/invalidating data pages, canceling stale requests, or avoiding redundant subscriptions     |
+| [Error handling & resiliency](./error-handling-and-resiliency.md)                         | Deciding how a failed call should behave (recover/retry/degrade/block), or containing a failure so it doesn't spread |
+| [Accessibility for async, API-driven components](./accessibility-for-async-components.md) | Announcing loading/success/error states, managing focus after navigation, or localizing status text                  |
+| [GenAI Assistant integration patterns](./genai-assistant-integration-patterns.md)         | Starting/continuing a GenAI Assistant or Agent conversation, streaming responses, or handling `rewriteText` results  |
+| [Troubleshooting common pitfalls](./troubleshooting-common-pitfalls.md)                   | Something calls the documented method correctly but the behavior is still wrong — search by symptom, not method name |
+
+Nothing in this folder introduces a new API — every recommendation composes methods already cataloged in [`../references/`](../references/) or sequenced in a skill's `cookbooks/`. Use the reference/cookbook links inside each guide for exact signatures and call order.

package/src/ai/catalog/best-practices/accessibility-for-async-components.md

@@ -0,0 +1,53 @@
+---
+title: Accessibility for Async, API-Driven Components
+description: How to announce loading/success/error states, manage focus after navigation, and localize status text for components driven by PCore/PConnect calls, aligned with WCAG 2.2 AA.
+---
+
+# Accessibility for Async, API-Driven Components
+
+> Part of [Cross-Cutting Best Practices](./README.md).
+
+Every state transition covered elsewhere in these guides — a pending `Promise`, a resolved success/empty/error result, a navigation to a new view — is also a moment a screen reader or keyboard-only user can silently miss if it isn't announced or focused correctly. This guide covers where WCAG 2.2 AA requirements intersect with PCore/PConnect usage specifically; it isn't a general accessibility reference.
+
+## Announce Async State Changes With a Live Region, Not Just a Visual Change
+
+The four states covered in [Testing: the four states of an API-driven component](./testing-pconnect-components.md#test-the-four-states-of-an-api-driven-component) (loading, success, empty, error) are all status messages under WCAG 4.1.3 Status Messages. A spinner that only changes visually, or an error message that only appears in the DOM without the right role, is invisible to a screen reader user unless focus already happens to be there:
+
+```tsx
+return (
+  <>
+    {isLoading && <span role='status'>Loading case details…</span>}
+    {error && <span role='alert'>{userFacingErrorMessage}</span>}
+  </>
+);
+```
+
+Use `role="status"` (equivalent to `aria-live="polite"`) for routine completions and `role="alert"` (equivalent to `aria-live="assertive"`) only for genuinely urgent failures — reserve `alert` the same way the [Error Handling & Resiliency](./error-handling-and-resiliency.md#choose-a-deliberate-strategy-recover-retry-degrade-or-block) guide reserves the "block" strategy, for failures that actually need immediate attention. The live region container should already exist in the DOM before the async call resolves; don't inject the container and its message at the same time — a live region added to the DOM at the same moment as its content is often not announced.
+
+## Localize Status Text, Don't Just Make It Announceable
+
+A correctly-roled status message that's hardcoded in one language is still an accessibility (and localization) gap for users on a different locale. Pull status/error copy through `pConn.getLocalizationService().getLocalizedText(...)`/`getLocalizedMessage(...)` (see [pconnect-case-info-data-info-localization.md](../references/pconnect-case-info-data-info-localization.md)) the same way any other user-facing string in these components must be — never hardcode display text. This applies doubly to async status text, since it's easy to hardcode a "quick" loading/error string and forget it needs the same localization treatment as the rest of the view.
+
+## Move Focus After a Navigation-Driven View Change
+
+When a component navigates to a new view or case — via `SemanticUrlUtils.getResolvedSemanticURL`/a container item open, or after `PCore.switchLocale` re-renders localized content — the resulting DOM change is a route change under WCAG 2.4.3 Focus Order: focus must be set to an appropriate element (typically the new view's heading, or a confirmation message for an in-place save) after the update, rather than being left on a now-stale or removed trigger element:
+
+```typescript
+const headingRef = useRef<HTMLHeadingElement>(null);
+
+useEffect(() => {
+  if (viewHasLoaded) headingRef.current?.focus();
+}, [viewHasLoaded]);
+```
+
+## Don't Let a Loading Overlay Trap or Skip Keyboard Focus
+
+A full-panel loading overlay shown while a `Promise` is pending should either disable focus on the content underneath it (so Tab doesn't silently move focus to now-hidden controls) or, if it's a true modal overlay, provide a documented keyboard exit (for example, Escape) as required by WCAG 2.1.2 No Keyboard Trap for any intentional focus trap. An overlay that visually covers content but leaves the covered controls still tab-reachable is a common, easy-to-miss defect specific to async loading states.
+
+## Checklist
+
+- Every loading/success/empty/error transition has a corresponding `role="status"`/`role="alert"` live region, not just a visual change.
+- Live region containers exist in the DOM before the async result that populates them arrives.
+- Status and error text is localized through `LocalizationService`, not hardcoded.
+- Focus moves to the new view's heading (or a confirmation message) after a navigation or in-place content swap, rather than staying on a stale trigger.
+- A loading overlay either disables the controls it covers or provides a documented keyboard exit if it's an intentional modal trap.

package/src/ai/catalog/best-practices/error-handling-and-resiliency.md

@@ -0,0 +1,116 @@
+---
+title: Error Handling & Resiliency
+description: How to choose a deliberate recover/retry/degrade/block strategy for PCore/PConnect failures, avoid silent failures, and contain them so one broken call doesn't take down a whole view.
+---
+
+# Error Handling & Resiliency
+
+> Part of [Cross-Cutting Best Practices](./README.md).
+
+Nearly every method in these skills that crosses the network returns a `Promise` that can reject. This guide covers how to handle that rejection deliberately, rather than leaving it to whatever the default behavior happens to be.
+
+## Choose a Deliberate Strategy: Recover, Retry, Degrade, or Block
+
+Every call that can fail should have an intentional answer to "what happens when this rejects" — picked at the time you write the call, not left to be discovered later. Four broad strategies, roughly in order of how disruptive they are to the user:
+
+| Strategy    | When to use it                                                                                        | Example                                                                                            |
+| ----------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| **Recover** | The failure has an obvious, safe fallback value.                                                      | An optional lookup data page fails — render the field without the enrichment instead of blocking.  |
+| **Retry**   | The failure is likely transient (network blip) and the operation is safe to repeat.                   | A read-only data page fetch fails once — retry it, not a non-idempotent submit (see below).        |
+| **Degrade** | Part of the view can still be useful without the failed piece.                                        | A GenAI Assistant suggestion fails to load — show the rest of the form, omit the suggestion panel. |
+| **Block**   | The failure means continuing would be incorrect or unsafe (e.g. an assignment submit or case delete). | `ActionsApi.finishAssignment` fails — stop, surface the error, do not proceed as if it succeeded.  |
+
+Pick the strategy deliberately for each call; don't let every failure default to the same generic error message regardless of how disruptive the underlying failure actually is.
+
+## Never Fail Silently
+
+An empty `catch` block, or a rejected promise nobody attaches a handler to, hides the failure from both the user and anyone debugging it later. Every failure path needs an observable outcome: a visible error state in the UI, a call to `ErrorHandler`, or at minimum a re-thrown/logged error — never a silent no-op.
+
+```typescript
+// Avoid: the user has no idea the save failed, and nothing is logged.
+saveChanges().catch(() => {});
+
+// Prefer: the failure is visible, and the strategy (recover/retry/degrade/block) is explicit.
+try {
+  await saveChanges();
+} catch (error) {
+  setErrorState('Your changes could not be saved. Please try again.');
+}
+```
+
+## Idempotency Before Retrying a Submit
+
+Retrying is only safe when repeating the call can't cause a duplicate effect. A read (`getPageDataAsync`, `getData`) is generally safe to retry. A write that isn't idempotent — `ActionsApi.finishAssignment`, `deleteWork`, `AttachmentUtils.uploadAttachment` — is not automatically safe to retry blindly: if the first attempt actually succeeded server-side and only the client-side confirmation was lost (e.g. a network drop after the request was sent), a naive retry can duplicate the submit or the upload. See [graceful-submit-failure](../pconnect-assignment-lifecycle/cookbooks/graceful-submit-failure.md) for the documented pattern — confirm the actual outcome (e.g. re-check case/assignment state) before assuming a retry is safe, rather than resubmitting on every failure by default.
+
+## Distinguish Cancellation From Failure
+
+A request canceled on purpose (because a newer one superseded it, or the component unmounted) is not an error and shouldn't be shown as one. Check `RestClient.isRequestCanceled(error)` (see [pcore-rest-data-details.md](../references/pcore-rest-data-details.md)) before running your failure-handling path:
+
+```typescript
+invokeRestApi(routeKey, payload).catch((error) => {
+  if (PCore.getRestClient().isRequestCanceled(error)) return; // intentional — not a failure
+  showErrorState(error);
+});
+```
+
+## Degrade Gracefully When Offline
+
+`NetworkUtils.isOnline()`/`onStatusChange(callback)` (see [pcore-environment-locale-namespace.md](../references/pcore-environment-locale-namespace.md)) let a component know about connectivity changes rather than discovering them only via a failed request. When offline, prefer disabling/queuing calls that require the network (submits, uploads) with a clear "you're offline" state, over letting each one fail individually and showing a wall of unrelated error messages for what is really one underlying cause.
+
+## Contain Failures With Boundaries
+
+A single custom component throwing during render shouldn't be able to blank out an entire page around it. Wrap custom widget rendering in a React error boundary so a failure in one component degrades to an error state for that component's region, not the whole view — this is standard React practice and applies directly here since a rejected `Promise` mishandled inside a component (e.g. an unhandled rejection that triggers a render-time throw) is a common way for one bad API call to take down an unrelated part of the page.
+
+## Give Users an Actionable Message, Not a Stack Trace
+
+`ErrorHandler.setGenericFailedMessage(message)`/`getGenericFailedMessage()` (see [pcore-misc-details.md](../references/pcore-misc-details.md)) control the fallback message shown when a component fails to render. Set this to something a user can act on ("Something went wrong loading this section. Try refreshing the page.") rather than leaving a default that isn't meaningful to an end user — and prefer a specific, component-level error message over the generic fallback whenever the component knows what actually failed. Never surface the raw rejection value, an internal error code, or a stack trace to the user (see [Security Considerations](./security-considerations.md#dont-leak-sensitive-details-through-error-handling)).
+
+## Distinguish a Validation Rejection From a System Failure
+
+`ValidationApi.validate(value, propertyName?)`/`validateEmail(value, options?)` (see [pconnect-validation-api.md](../references/pconnect-validation-api.md)) return a result object describing _why the input was invalid_ — this is not the same category of failure as a rejected `Promise` from a network call, and the two need different handling. A validation result belongs inline, next to the field, worded around what the user should fix; a system/network failure belongs in a broader error state and is worded around what went wrong with the operation, not the input. Don't route both through the same generic error-message path — collapsing them makes a simple "enter a valid email" correction look as alarming as a failed save, and makes a real system failure easy to dismiss as "just a typo."
+
+## Retry With a Backoff and a Limit, Never Forever
+
+When a retry strategy is appropriate (see the table above), retrying immediately and indefinitely can turn a transient blip into a self-inflicted flood of requests against a server that's already struggling. Space retries out (for example, doubling the delay each attempt) and cap the number of attempts, surfacing the failure state once the cap is reached instead of retrying silently forever:
+
+```typescript
+async function fetchWithRetry(fn: () => Promise<unknown>, attempts = 3, delayMs = 500): Promise<unknown> {
+  try {
+    return await fn();
+  } catch (error) {
+    if (attempts <= 1) throw error;
+    await new Promise((resolve) => setTimeout(resolve, delayMs));
+    return fetchWithRetry(fn, attempts - 1, delayMs * 2);
+  }
+}
+```
+
+## Handle a Case Locked or Changed by Another User as an Expected Outcome
+
+A submit, save, or field update can fail specifically because another user (or another tab/session for the same user) modified or locked the same case/assignment first — this is a distinct, expected failure mode in a collaborative system, not the same as a generic network error. Recognize it from the specific failure the call surfaces and give the user a clear next step ("This case was updated by someone else — refresh to see the latest version before continuing") rather than the generic failed-save message, and don't silently overwrite the other change by blindly retrying the original submit.
+
+## Guard Against a Call That Never Resolves
+
+A `Promise` that neither resolves nor rejects (a hung request, a subscription callback that never fires) leaves a loading state on screen indefinitely with no path to an error state. For a call where the framework doesn't already provide a timeout, wrap it with your own bound so the UI can fall back to a visible error/timeout state instead of spinning forever:
+
+```typescript
+function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+  return Promise.race([promise, new Promise<T>((_, reject) => setTimeout(() => reject(new Error('timed out')), ms))]);
+}
+```
+
+Prefer this only as a defensive fallback around calls with no first-class cancellation, not as a substitute for `RestClient.getCancelTokenSource()` (see [Performance & Efficiency: cancel requests that are no longer needed](./performance-and-efficiency.md#cancel-requests-that-are-no-longer-needed)) where that's available — an explicit cancel also stops the server from doing wasted work, where a client-side timeout alone does not.
+
+## Checklist
+
+- Decide recover/retry/degrade/block for each call at the time you write it, not by default.
+- Never leave a rejected promise unhandled or a `catch` block empty — every failure needs an observable outcome.
+- Only retry idempotent operations automatically; confirm actual outcome before retrying a non-idempotent submit/upload/delete.
+- Check `isRequestCanceled` before treating a canceled request as a failure.
+- Use `NetworkUtils` to detect offline state proactively rather than reacting to a pile of individually failed requests.
+- Wrap custom component rendering in an error boundary so one failure doesn't blank the whole page.
+- Show a clear, actionable, generic message to the user; never a raw error object or stack trace.
+- Route validation results and system failures through different UI treatments — don't make a field-level typo look like a broken save.
+- Space out and cap any automatic retry loop; never retry immediately and indefinitely.
+- Give a case-locked/changed-by-another-user failure its own clear message and next step, instead of the generic failed-save path.
+- Guard a call with no built-in cancellation/timeout so a hung request can't leave a loading state on screen forever.

package/src/ai/catalog/best-practices/genai-assistant-integration-patterns.md

@@ -0,0 +1,49 @@
+---
+title: GenAI Assistant Integration Patterns
+description: Conversation lifecycle, state rehydration, streaming, feedback, and safety-gate patterns for building custom components on top of GenAIAssistantUtils and GenAIUtils.
+---
+
+# GenAI Assistant Integration Patterns
+
+> Part of [Cross-Cutting Best Practices](./README.md).
+
+`GenAIAssistantUtils` and `GenAIUtils` (see [pcore-analytics-genai-details.md](../references/pcore-analytics-genai-details.md) and [pcore-case-collaboration-genai.md](../references/pcore-case-collaboration-genai.md)) let a custom component start and continue a conversation with a GenAI Assistant or Agent, and rewrite text. This guide covers the integration patterns specific to these APIs — for content-safety concerns (prompt injection, sanitizing model output), see [Security Considerations](./security-considerations.md); for the general async-state and mocking patterns, see [Testing](./testing-pconnect-components.md#testing-genai-assistant-conversations) and [Error Handling & Resiliency](./error-handling-and-resiliency.md).
+
+## Gate on `isGenAIEnabled()` Before Rendering Any GenAI Affordance
+
+Not every environment has GenAI enabled. Check `PCore.getEnvironmentInfo().isGenAIEnabled()` before rendering a GenAI-dependent button, panel, or suggestion — and treat "disabled" as an expected, silent state (simply don't render the affordance), not an error condition to surface to the user:
+
+```typescript
+const genAIEnabled = PCore.getEnvironmentInfo().isGenAIEnabled();
+
+if (!genAIEnabled) return null; // no GenAI affordance in this environment — not an error
+```
+
+## Rehydrate Conversation History Instead of Trusting Local State Alone
+
+`createConversation`/`createConversationForAgent` start a conversation that's tracked server-side; `getMessages`/`getMessagesForAgent` and the paginated `getConversations`/`getConversationsForAgent` retrieve what's already there. Local component state built up as the user sends/receives messages in the current session is a convenient cache, but it is not the source of truth — on mount (or when reopening a previously started conversation), call `getMessages(assistantID, conversationID, context)` to rehydrate rather than assuming a fresh component instance starts with no history (see [Troubleshooting: a GenAI Assistant conversation's history is empty after a page reload](./troubleshooting-common-pitfalls.md#a-genai-assistant-conversations-history-is-empty-after-a-page-reload)).
+
+## Render Incrementally When `enableStreaming` Is Used
+
+`sendMessage` supports an `enableStreaming` option for a more responsive, incremental reply rather than waiting for the full response. If a component uses streaming, render the partial response as it arrives (with its own visible "in progress" indicator distinct from a fully-loaded message) rather than buffering the whole thing client-side and only rendering once — buffering defeats the purpose of requesting streaming in the first place and leaves the user staring at nothing for longer than necessary.
+
+## Handle `GenAIUtils.rewriteText`'s Discriminated Result Explicitly
+
+`rewriteText({ originalText, rewriteAction })` resolves an object shaped as either `{ success: true, rewrittenText }` or a failure shape — it does not reject on a model-side failure the way a network error would. Check `result.success` explicitly and handle both branches (see [Testing: testing GenAI Assistant conversations](./testing-pconnect-components.md#testing-genai-assistant-conversations)); a component that only reads `result.rewrittenText` without checking `success` first will render `undefined` on failure instead of a clear fallback message.
+
+## Use the Like/Unlike Feedback Loop, Don't Build a Parallel One
+
+`likeAgentMessage`/`unLikeAgentMessage(agentID, conversationID, messageID, context, feedbackText?)` are the documented mechanism for capturing a user's reaction to an Agent's message, including optional free-text feedback on removal of a like. Route thumbs-up/thumbs-down UI through these calls rather than inventing a separate feedback-collection mechanism — this keeps feedback attached to the same conversation/message record the platform already tracks, rather than living in a disconnected system nobody correlates back to the conversation.
+
+## Treat a Long-Running Conversation Call Like Any Other Async Operation
+
+Nothing about `sendMessage`/`sendMessageForAgent` exempts it from the general patterns elsewhere in this folder: it's a `Promise` that can reject (see [Error Handling & Resiliency](./error-handling-and-resiliency.md)), a user can trigger a new message before a previous one resolves (consider whether to disable the input or track/cancel the stale one, per [Performance & Efficiency: cancel requests that are no longer needed](./performance-and-efficiency.md#cancel-requests-that-are-no-longer-needed)), and its pending/success/error states need the same live-region treatment as any other async UI (see [Accessibility for Async, API-Driven Components](./accessibility-for-async-components.md)).
+
+## Checklist
+
+- Check `PCore.getEnvironmentInfo().isGenAIEnabled()` before rendering any GenAI-dependent UI; treat "disabled" as a silent no-render, not an error.
+- Rehydrate conversation history via `getMessages`/`getConversations` on mount rather than relying only on in-session local state.
+- Render streamed responses incrementally, not buffered until fully complete, when `enableStreaming` is used.
+- Explicitly branch on `rewriteText`'s `success` field rather than assuming the happy-path shape.
+- Route message feedback through `likeAgentMessage`/`unLikeAgentMessage` instead of a separate, disconnected mechanism.
+- Apply the same async-state, cancellation, and accessibility patterns used elsewhere in these guides to conversation calls — they aren't a special case.