@pega/sdk 0.0.14 → 0.0.15

package/templates/react-sdk-reference/.ai-common/skills/embedded-flow/wire-integration.md

@@ -107,9 +107,11 @@ A generic list of surfaces is not good enough. Draw the options from the applica
 
 Ask for both in a single exchange when both are missing. Two round trips for one decision is worse than one.
 
-#### Step 0.4 — The resolved target must survive a full-page reload
+#### Step 0.4 — Authentication must not lose the launch context
 
-Whichever target Step 0.2 or Step 0.3 produced, it has to survive being reloaded. The SDK authenticates by redirecting the whole window to the Pega login form and back, so the application is torn down and re-created between the moment the user triggers the flow and the moment the flow can render. Anything holding the launch context only in memory is gone by then.
+The embedded startup authenticates in a separate popup window and leaves the application page in place, so a launch context held in memory is still there when the flow becomes ready. Nothing needs persisting in that default.
+
+The rest of this step applies only when the host has been configured for main-window redirect login instead. In that mode the SDK redirects the whole window to the Pega login form and back, so the application is torn down and re-created between the moment the user triggers the flow and the moment the flow can render. Anything holding the launch context only in memory is gone by then, so the resolved target has to survive being reloaded.
 
 This is a property of the target, not an edge case, and it must be handled while wiring rather than discovered later:
 
@@ -137,8 +139,8 @@ These two lifetimes are easy to collapse into one, because on a first launch the
 So:
 
 - **Keep the runtime for the lifetime of the page.** When the target is dismissed, hide it and leave the runtime in place. Never discard it to close the flow.
-- **Do not establish it at page start either**, if doing so would authenticate. The first launch is what puts a visitor in front of the login form, and nothing should send them there before they ask. Establish it on the first launch, then keep it.
-- **Drive case creation from the launch itself**, not from the runtime being set up, so that every launch creates a case and the second one behaves like the first.
+- **Do not establish it at page start either**, since establishing it authenticates. The first launch is what opens the Pega login window for a visitor, and nothing should open it before they ask. Starting on the user's own launch action also keeps the browser from treating the login window as an unsolicited popup and blocking it. Establish it on the first launch, then keep it.
+- **Drive case creation from the launch itself**, not from the runtime being set up, so that every launch creates a case and the second one behaves like the first. On the first launch the runtime is not ready when the user acts, so hold that launch until readiness is signalled and then create its case; on later launches create it immediately.
 
 **A single launch cannot detect any of this.** Set-up and first launch coincide, so the flow works, and the defect appears only on a second launch — which is why Step 7 requires the flow to be launched more than once.
 
@@ -148,40 +150,43 @@ So:
 
 Add the following Pega packages to the project's dependency manifest:
 
-| Package                                                          | Purpose                                                         |
-| ---------------------------------------------------------------- | --------------------------------------------------------------- |
-| The Pega SDK adapter package (matching the customer's framework) | Bridge component, runtime context, component registry utilities |
-| The Pega auth package                                            | OAuth authentication and token management                       |
-| The Pega SDK types package                                       | Shared type definitions and interfaces                          |
-| The Pega ConstellationJS core package                            | Runtime engine that provides the PCore global                   |
+| Package                                                          | Purpose                                                                                                 |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| The Pega SDK adapter package (matching the customer's framework) | Bridge component, runtime context, component registry utilities                                         |
+| The Pega auth package                                            | OAuth authentication and token management                                                               |
+| The Pega SDK types package                                       | Shared type definitions and interfaces                                                                  |
+| The Pega ConstellationJS core package                            | Runtime engine that provides the PCore global; its distribution files are served by the host (Step 1.1) |
 
 These are the only external additions. The generated components use the customer's existing UI library — no additional design system packages are needed.
 
 If SDK packages were provided as `.tgz` files (interim distribution), they should already be in the project root with `file:` references in the dependency manifest. Run the project's package install command to link them.
 
-### Step 1.1 — Load the SDK core runtime script
+### Step 1.1 — Serve the SDK core runtime files
+
+The Pega runtime is not loaded by the page. After login succeeds, the SDK's auth package loads the runtime's bootstrap shell from the content server, and the shell then fetches the core bundles and their lazily loaded chunks. The host application only has to make those files reachable. **Do not add a script reference for the core bundle.** Loading it ahead of the application is not how the supported startup works, and the `PCore` global is deliberately absent until authentication has completed.
 
-The Pega ConstellationJS core must be loaded **before** any SDK code executes. It provides the `PCore` global object that all Pega components depend on.
+The files ship inside the ConstellationJS package, under its distribution directory. Serve them at these absolute URLs, in the development server and in the production build alike:
 
-The script ships inside the ConstellationJS package, under its distribution directory. Resolve the exact path from the installed package rather than copying the file anywhere.
+| Served URL                          | Source in the ConstellationJS distribution directory                                       |
+| ----------------------------------- | ------------------------------------------------------------------------------------------ |
+| `/constellation/bootstrap-shell.js` | The bootstrap shell                                                                        |
+| `/constellation/lib_asset.json`     | The library manifest                                                                       |
+| `/constellation/prerequisite/`      | The core bundle files — every file whose name starts with the `constellation-core.` prefix |
+| `/constellation/prerequisite/js/`   | The lazily loaded chunk folder, with its folder structure kept                             |
 
-**Where it goes depends on the shape of the project's entry point.** Identify which of these the customer's framework is, then apply it:
+`serverConfig.sdkContentServerUrl` decides where the SDK requests these from; an empty value means the application's own origin (see Step 2).
 
-| Entry-point shape                                                               | How to load the core script                                                                                                                                                          |
-| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| The project has a hand-editable HTML document that loads the application module | Add a script element ahead of the application's own module script, so it executes first                                                                                              |
-| The framework generates the HTML document and exposes a root layout or shell    | Use the framework's mechanism for injecting a script that runs before application code — most provide an explicit "before interactive" or "head" placement for exactly this          |
-| The framework renders on the server                                             | The script must execute in the browser only. Use the framework's browser-only escape hatch; never let it run during a server render, where there is no `window` to attach `PCore` to |
+Use whatever mechanism the toolchain already has for serving static files at fixed URLs — typically a development-server rule plus a build-time copy step, or a static-asset configuration entry. Resolve the source from the installed package every time the build or development server starts rather than committing a copy: a committed copy silently goes stale when the package is upgraded. Make sure the toolchain's fallback to the entry document does not answer these URLs with the application's HTML when a file is missing — a missing file must fail visibly.
 
-If the development server does not serve files from the dependency directory, either configure it to, or place a copy where the project already serves static assets and reference it from there. Prefer serving from the installed package when the toolchain allows it — a copy silently goes stale when the package is upgraded.
+**Integrity map (optional):** the auth package looks for an import map in the HTML document that carries a hash for the bootstrap shell. Without one it logs a warning that it is falling back to an unverified URL. That warning is expected here and harmless.
 
 **Key requirements:**
 
-- The core script must load and execute **before** the application module runs
-- It must execute only in the browser, not during any server-side rendering phase
-- The reference must resolve from the route the flow launches at — see the document-relative discussion in Step 2, which applies to this script too
+- The URLs are absolute, so they resolve identically from every route — unlike `sdk-config.json`, which is document-relative (Step 2)
+- Nothing in the application's HTML or entry module references the core bundle
+- Every file the shell requests under `/constellation/prerequisite/` is served, including the lazily loaded chunks; serving only the entry bundle fails later, when a component that needs a chunk first mounts
 
-**Verification criterion:** The browser's network panel shows the core script loaded successfully, and the `PCore` global object is available on `window` before application code executes.
+**Verification criterion:** Requesting `<origin>/constellation/bootstrap-shell.js` and `<origin>/constellation/lib_asset.json` in the browser returns a script and JSON respectively, not the application's HTML. After login completes, the network panel shows the core bundle loaded from `/constellation/prerequisite/` and the `PCore` global is defined on `window`.
 
 ### Step 1.2 — Load SDK styles and OAuth callback assets
 
@@ -197,7 +202,7 @@ Import this stylesheet in the application's entry point, **before** the applicat
 
 **OAuth callback assets:**
 
-The SDK's auth package ships browser-facing assets used during the OAuth redirect flow:
+The SDK's auth package ships browser-facing assets used by the login popup and its OAuth callback:
 
 | Asset                   | Source (in auth package)                 | Required served location                                        |
 | ----------------------- | ---------------------------------------- | --------------------------------------------------------------- |
@@ -247,29 +252,44 @@ The file must contain two sections — `serverConfig` and `authConfig`:
 | `serverConfig` | `appMashupCaseType`     | Fully qualified case type class to embed                                                             |
 | `serverConfig` | `excludePortals`        | Array of portal names incompatible with the SDK (prevents auto-selection of admin/developer portals) |
 | `authConfig`   | `authService`           | Authentication service identifier (typically `"pega"`)                                               |
-| `authConfig`   | `mashupClientId`        | OAuth client identifier for embedded/mashup mode                                                     |
+| `authConfig`   | `mashupClientId`        | OAuth client identifier used by the embedded login popup                                             |
 | `authConfig`   | `mashupUserIdentifier`  | Operator identifier for the embedded session                                                         |
 | `authConfig`   | `mashupPassword`        | Operator password (empty for OAuth-only flows)                                                       |
-| `authConfig`   | `portalClientId`        | OAuth client identifier used during main-window redirect authentication                              |
+| `authConfig`   | `portalClientId`        | OAuth client identifier used only by main-window redirect login                                      |
 | `authConfig`   | `portalClientSecret`    | Client secret for portal authentication (empty if public client)                                     |
 | `authConfig`   | `portalGrantType`       | OAuth grant type for portal auth (empty for default authorization code flow)                         |
 
-**⚠️ CRITICAL — Portal credential keys and silent authentication hang:**
+**⚠️ CRITICAL — The client identifier for the active login mode must be non-empty:**
 
-When the bootstrap module authenticates using a main-window redirect (which is the default for embedded mode), the SDK's configuration normalization reads the **portal-prefixed** credential keys (`portalClientId`, `portalClientSecret`, `portalGrantType`), not the mashup-prefixed ones.
+The SDK's configuration normalization picks credential keys by login mode. The embedded startup authenticates in a popup, so it reads the **mashup-prefixed** keys (`mashupClientId` and its siblings). A main-window redirect login reads the **portal-prefixed** keys (`portalClientId`, `portalClientSecret`, `portalGrantType`) instead.
 
-If `portalClientId` is absent or empty, the authentication initializer classifies the session as custom-auth and returns **without ever resolving its readiness promise**. The result is a permanent silent hang:
+If the client identifier for the active mode is absent or empty, treat it as the following failure. The observed case is an empty `portalClientId`: the authentication initializer classifies the session as custom-auth and returns **without ever resolving its readiness promise**. The result is a permanent silent hang:
 
 - No network requests are made
 - No error is thrown or logged
 - The readiness signal never fires
 - The UI remains in its "loading" state indefinitely
 
-**Prevention:** Always populate `portalClientId` — typically with the same value as `mashupClientId`. The `portalClientSecret` and `portalGrantType` fields should be present (even if empty strings) to ensure the normalizer finds them.
+**Prevention:** Always populate both `mashupClientId` and `portalClientId` with the same value, so that neither login mode can hit it. The `portalClientSecret` and `portalGrantType` fields should be present (even if empty strings) to ensure the normalizer finds them.
+
+### Step 3 — Establish the runtime startup
+
+Authentication, registry creation and bootstrap must run exactly once per page load, regardless of how many times the host framework invokes component lifecycle methods.
+
+**Prefer the adapter package's runtime provider.** Check the exports of the SDK adapter package for the customer's framework. When it offers a top-level runtime provider, use it instead of hand-writing startup. It performs, in order: login, registry creation, registration of the host's components, registration of the component creator with the fallback, and bootstrap. It then supplies the readiness state, render context, registry and auth client through the runtime context. The host supplies only:
 
-### Step 3 — Create the bootstrap module
+- The embedded mode
+- A registration callback that registers every component exported by the generated components folder's `component-map` registry file into the registry it is given
+- The fallback component that renders when Pega requests a component with no registry entry
+- Loading, error and logged-out renderings, built from the customer's own primitives
 
-Create a module that handles the Pega SDK lifecycle. **This module's initialization must execute exactly once per page load**, regardless of how many times the host framework invokes component lifecycle methods.
+Rules for placing it:
+
+- **Mount it once, on the first launch, and never unmount it.** Mounting it is what starts login (Step 0.5). Its start guard belongs to the single instance, so a provider that is torn down and re-created authenticates and bootstraps again, which stalls on an already-initialised runtime
+- **Wrap only the Pega target, never the customer's application.** While it is loading, has failed, or has been logged out, it renders that state in place of its children. Wrapped around the whole application, it would replace the customer's UI with a loading, error or logged-out message
+- **Supply the three renderings.** The defaults are bare text. The error rendering receives the error and a retry action; the logged-out rendering receives a log-in-again action, which reloads the page because the runtime stays initialised after logout and cannot re-bootstrap in place
+
+**When the adapter has no runtime provider**, write a startup module that does the same work. **This module's initialization must execute exactly once per page load**, regardless of how many times the host framework invokes component lifecycle methods.
 
 **⚠️ CRITICAL — Initialization must be a module-scoped singleton:**
 
@@ -293,10 +313,10 @@ The module-scoped singleton avoids this entirely because it is immune to compone
 
 **Bootstrap responsibilities:**
 
-1. **Authenticate** — use the SDK auth client to perform login (OAuth redirect or silent renewal)
-2. **Bootstrap in embedded/mashup mode** — initialize the SDK runtime in mashup mode (not full portal), capturing the render context returned by bootstrap
-3. **Create the component registry** — instantiate the SDK's component registry and register all components exported by the generated components folder's `component-map` registry file
-4. **Register the component creator** — tell the SDK runtime to use the registered components for rendering
+1. **Authenticate in a popup** — use the SDK auth client to perform login with main-window redirect turned off. The SDK reports a blocked or closed login popup as an unhandled rejection rather than by rejecting the login call, so intercept those rejections and turn them into an error state with a retry action
+2. **Create the component registry** — only after login, because the SDK core is not available before it. Instantiate the SDK's component registry and register all components exported by the generated components folder's `component-map` registry file
+3. **Register the component creator** — tell the SDK runtime to use the registered components for rendering, with the fallback component
+4. **Bootstrap in embedded/mashup mode** — initialize the SDK runtime in mashup mode (not full portal), capturing the render context returned by bootstrap
 
 This module should expose:
 
@@ -311,7 +331,7 @@ The control was resolved and cleared in Step 0.1. If that gate was skipped, stop
 
 #### Step 4.1 — Attach the launch
 
-**Wait for the bootstrap readiness signal before calling anything.** The call below reads the `PCore` global, which does not exist until the bootstrap module from Step 3 has resolved. A trigger the user can activate before then throws on an undefined global — and because bootstrap usually wins the race on a warm reload, it fails intermittently and looks like a network fault. Gate the control on the readiness signal that Step 3's module exposes: keep it inert until the signal fires, or await the signal inside the handler before proceeding.
+**Wait for the runtime to report ready before calling anything.** The call below reads the `PCore` global, which does not exist until authentication and bootstrap have completed. On the first launch that is after the user has signed in, so hold the launch until readiness is signalled, then make the call; on later launches the runtime is already ready and the call runs immediately. A call made earlier throws on an undefined global, and because only the first launch is ever early, it fails intermittently and looks like a network fault. Gate on the readiness signal that Step 3 exposes (the ready state of the runtime context when the adapter's runtime provider is used): keep the control's call inert until the signal fires, or await the signal inside the handler before proceeding.
 
 On the trigger, call the SDK's mashup API to create a case. It takes three arguments, and an embedded flow needs all three:
 
@@ -335,6 +355,8 @@ Therefore:
 
 **Report dropped pre-fill — do not let it disappear quietly.** When the customer's launch context had values that were clearly meant to seed the case and none of them map to a confirmed property, sending an empty object is correct but silent: the flow works, and the values the user already entered are simply gone. Tell them explicitly — name the properties the case type does accept, name the values that had no home, and state that pre-fill is off until the mapping is confirmed. That mapping is a question for whoever owns the case type; answer it with them, not by inference.
 
+Phrase this for someone who does not know the case type's property names — for example: "Details your users typed before opening the form won't be filled in yet. Ask your Pega app owner which of these fields can be filled in at the start:" — then list the exact property names, since the case type owner needs them.
+
 **⚠️ CRITICAL — omitting `pageName` renders the wrong thing.**
 
 `pyEmbedAssignment` is what narrows the render to the assignment. Without it the runtime returns the **full case view** — stage navigation, a case summary panel, and Details / Case History tabs wrapped around the form. That is a portal experience, not an embedded one, and it is not what the customer asked to embed.
@@ -348,7 +370,7 @@ The failure is easy to miss because it still renders. Two tells:
 
 Then reveal the render target resolved in Step 0.2 — open the dialog, navigate to the route, or show the region — so the flow becomes visible where the customer expects it.
 
-If Step 0.4 established that the target does not survive a reload, this is where its first half goes: persist the launch context **before** the create call, since the authentication redirect can happen inside it. The restoring half belongs wherever the application starts up, so that the context is re-established before the flow is mounted.
+If redirect login is configured and Step 0.4 established that the target does not survive a reload, this is where its first half goes: persist the launch context **before** the create call, since the authentication redirect can happen inside it. The restoring half belongs wherever the application starts up, so that the context is re-established before the flow is mounted.
 
 Per Step 0.5, this create call must run on **every** launch. Anything that makes it fire only the first time — a guard tied to the runtime being set up rather than to the launch — leaves every later launch showing an empty target. If a guard is needed to stop a single launch creating two cases, key it to the launch and release it when the flow is dismissed.
 
@@ -373,12 +395,16 @@ Mount the bridge once and keep it mounted, per Step 0.5. Dismissing the flow hid
 In that target:
 
 1. Render the SDK bridge component, passing:
-   - The render context from bootstrap (contains the root `getPConnect` accessor)
+   - The render context from bootstrap (contains the root `getPConnect` accessor), read from the runtime context
    - The populated component registry
    - A fallback component (renders when a Pega-requested component is not in the registry)
-2. Wrap with the SDK's required context providers (store context for state access, runtime context for environment)
+2. Make sure the SDK's required context providers are in place — store context for state access, and runtime context for environment (the runtime provider from Step 3 already supplies the latter)
 3. The bridge component will recursively resolve and render Pega components from the registry as the case flow progresses
 
+**Keep the Pega area inside the host's look:**
+
+The generated components inherit their font and base text colour rather than setting them, so the element that hosts the Pega container must sit inside the host's base text and theme scope recorded under Global Appearance in the Design Profile. That is usually automatic for a route or a page region. A surface that the host renders outside its application root — commonly a dialog or drawer attached elsewhere in the page — can fall outside that scope. When it does, apply the host's own mechanism for bringing a detached surface into its theme (the way its other dialogs receive it); never re-declare fonts or colours for the Pega container.
+
 **CSS isolation considerations:**
 
 Global CSS resets and normalizers commonly strip intrinsic sizing from inline vector graphics and remove default button styling. If the host application uses such resets, scope corrective rules to the Pega rendering container element rather than modifying the global styles:
@@ -386,23 +412,24 @@ Global CSS resets and normalizers commonly strip intrinsic sizing from inline ve
 - Inline vector graphics within the container should have constrained dimensions (not expand to fill their parent)
 - Interactive elements within the container should retain cursor indicators
 
-**Verification criterion:** After triggering a case launch, the form content (fields, labels, action controls) is visible and interactive within the resolved render target. The bridge is rendering — not just the container element alone.
+**Verification criterion:** After triggering a case launch, the form content (fields, labels, action controls) is visible and interactive within the resolved render target. The bridge is rendering — not just the container element alone. Text inside the Pega container uses the same font family and base text colour as the host's own content around it.
 
 ### Step 6 — Handle flow lifecycle events
 
 Subscribe to SDK lifecycle events to manage what happens when the case flow ends. What "return to the customer's UI" means depends on the render target resolved in Step 0.2: a dialog closes, a route navigates back to where the trigger was, and a region reverts to what it showed before.
 
-| Event                                        | Action                                                                         |
-| -------------------------------------------- | ------------------------------------------------------------------------------ |
-| Cancellation                                 | Dismiss the render target and return the user to where they triggered the flow |
-| Flow completion (assignment processing done) | Dismiss the target, optionally showing a success message or redirecting        |
-| Error                                        | Display an error state or fallback, log for debugging                          |
+| Event                                        | Action                                                                                                                           |
+| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| Cancellation                                 | Dismiss the render target and return the user to where they triggered the flow                                                   |
+| Flow completion (assignment processing done) | Dismiss the target, optionally showing a success message or redirecting                                                          |
+| Error                                        | Display an error state or fallback, log for debugging                                                                            |
+| Logged out                                   | Show the customer's logged-out rendering. Signing in again needs a page reload, because the runtime cannot re-bootstrap in place |
 
 Unsubscribe from these events on component teardown to prevent memory leaks.
 
 ### Step 7 — Verify the integration
 
-Wiring is not finished until the flow has been observed running. Read and execute `{{SKILL_DIR}}/embedded-flow/run-and-verify-integration.md`, which turns the verification criteria stated throughout this skill into executed checks and defines what may be repaired automatically.
+Wiring is not finished until the flow has been observed running. Read and execute `{{SKILL_DIR}}/embedded-flow/run-and-verify-integration{{SKILL_EXT}}`, which turns the verification criteria stated throughout this skill into executed checks and defines what may be repaired automatically.
 
 At minimum it must establish that:
 
@@ -412,6 +439,7 @@ At minimum it must establish that:
 4. A generated field retains its value after the commit event
 5. Completing or cancelling the flow returns the UI to its previous state
 6. No console errors occur during any of the above
+7. The form matches the host's base font and text colour, and its fields neither overlap nor overflow
 
 Do not report the integration as complete on static checks alone.
 
@@ -454,23 +482,26 @@ The Pega SDK repository includes a mashup/embedded sample application that demon
 
 Common integration failures and their resolutions. These are ordered by how they typically manifest during first-time setup.
 
-| Symptom                                                                                                                | Cause                                                                                                                                                                | Resolution                                                                                                                                                                                                       |
-| ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Application hangs indefinitely on startup — no network requests, no errors in console, readiness signal never fires    | The `portalClientId` field is missing or empty in `sdk-config.json`. The auth initializer classifies the session as custom-auth and returns without resolving.       | Add `portalClientId` to the `authConfig` section (typically the same value as `mashupClientId`). Ensure `portalClientSecret` and `portalGrantType` are also present (even as empty strings).                     |
-| Authentication succeeds (network shows token exchange) but the readiness signal never fires; UI stays in loading state | The bootstrap initialization ran more than once and a lifecycle-cleanup cancellation flag aborted the in-flight run after auth completed.                            | Ensure bootstrap is a module-scoped singleton promise (see Step 3). Remove any guard + cancellation flag pattern.                                                                                                |
-| The Pega container is mounted but displays nothing — an empty box after case creation                                  | The host application bootstrapped the SDK but never rendered the bridge component with the returned render context.                                                  | Confirm that after the readiness signal fires, the bridge component is rendered with the render context's `getPConnect` accessor, inside the SDK's store context provider (see Step 5).                          |
-| 404 errors for the ConstellationJS core script                                                                         | The core script is not being served from the referenced path.                                                                                                        | Verify the reference resolves from the route the flow launches at, and that the toolchain serves the dependency directory. If it does not, serve a copy from the static assets directory instead (see Step 1.1). |
-| 404 for `sdk-config.json`                                                                                              | The configuration file is not at the application's served web root, or the route depth at bootstrap time causes the relative fetch to resolve against a nested path. | Move the file to the project's served static directory. If bootstrapping from a nested route, set an explicit document base URL (see Step 2).                                                                    |
-| Inline vector graphics (icons) render at enormous size, filling their parent container                                 | Global CSS resets strip intrinsic sizing from SVG elements.                                                                                                          | Scope size constraints on inline vector graphics to the Pega rendering container (see Step 5 CSS isolation note).                                                                                                |
-| Action buttons, stage indicators, or navigation controls render as unstyled text                                       | The SDK adapter package's stylesheet is not imported. These components use class-based styling that requires the stylesheet to be loaded.                            | Import the stylesheet in the application entry point as described in Step 1.2.                                                                                                                                   |
-| Case creation renders full case chrome (summary bar, stage progress, case history) instead of just the embedded form   | The case was created without `pageName: 'pyEmbedAssignment'`. The server defaults to the full case view.                                                             | Pass all three arguments to the mashup API's case-creation call, including the embedded page name (see Step 4.1).                                                                                                |
-| OAuth redirect opens a blank page or fails silently                                                                    | The OAuth callback assets (`auth.html`, `authDone.js`) are missing from the served web root.                                                                         | Place the auth callback assets as described in Step 1.2.                                                                                                                                                         |
+| Symptom                                                                                                                | Cause                                                                                                                                                                                                                                | Resolution                                                                                                                                                                                                               |
+| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Application hangs indefinitely on startup — no network requests, no errors in console, readiness signal never fires    | The client identifier for the active login mode is missing or empty in `sdk-config.json` (the observed case is an empty `portalClientId`). The auth initializer classifies the session as custom-auth and returns without resolving. | Populate both `mashupClientId` and `portalClientId` in the `authConfig` section with the same value. Ensure `portalClientSecret` and `portalGrantType` are also present (even as empty strings).                         |
+| Authentication succeeds (network shows token exchange) but the readiness signal never fires; UI stays in loading state | The bootstrap initialization ran more than once and a lifecycle-cleanup cancellation flag aborted the in-flight run after auth completed.                                                                                            | Ensure bootstrap is a module-scoped singleton promise (see Step 3). Remove any guard + cancellation flag pattern.                                                                                                        |
+| The Pega container is mounted but displays nothing — an empty box after case creation                                  | The host application bootstrapped the SDK but never rendered the bridge component with the returned render context.                                                                                                                  | Confirm that after the readiness signal fires, the bridge component is rendered with the render context's `getPConnect` accessor, inside the SDK's store context provider (see Step 5).                                  |
+| 404 or HTML returned for `/constellation/` runtime files; runtime global never defined after login                     | The runtime files are not being served at their absolute `/constellation/` URLs, or the toolchain's fallback to the entry document is answering for a missing file.                                                                  | Serve the bootstrap shell, library manifest, core bundles and lazily loaded chunks as described in Step 1.1, resolved from the installed package. Request each URL directly to confirm it returns the file and not HTML. |
+| 404 for `sdk-config.json`                                                                                              | The configuration file is not at the application's served web root, or the route depth at bootstrap time causes the relative fetch to resolve against a nested path.                                                                 | Move the file to the project's served static directory. If bootstrapping from a nested route, set an explicit document base URL (see Step 2).                                                                            |
+| Inline vector graphics (icons) render at enormous size, filling their parent container                                 | Global CSS resets strip intrinsic sizing from SVG elements.                                                                                                                                                                          | Scope size constraints on inline vector graphics to the Pega rendering container (see Step 5 CSS isolation note).                                                                                                        |
+| Action buttons, stage indicators, or navigation controls render as unstyled text                                       | The SDK adapter package's stylesheet is not imported. These components use class-based styling that requires the stylesheet to be loaded.                                                                                            | Import the stylesheet in the application entry point as described in Step 1.2.                                                                                                                                           |
+| Case creation renders full case chrome (summary bar, stage progress, case history) instead of just the embedded form   | The case was created without `pageName: 'pyEmbedAssignment'`. The server defaults to the full case view.                                                                                                                             | Pass all three arguments to the mashup API's case-creation call, including the embedded page name (see Step 4.1).                                                                                                        |
+| The login popup opens blank or fails silently                                                                          | The OAuth callback assets (`auth.html`, `authDone.js`) are missing from the served web root.                                                                                                                                         | Place the auth callback assets as described in Step 1.2.                                                                                                                                                                 |
+| The error state reports that the login popup was blocked or closed                                                     | The browser blocked the popup because login did not start from a user action, popups are disallowed for the site, or the user closed the window.                                                                                     | Start the runtime from the launch action itself (Step 0.5) and have the user allow popups; the retry action re-runs login.                                                                                               |
+| The customer's whole page is replaced by a loading, error or logged-out message                                        | The runtime provider wraps the application instead of only the Pega target.                                                                                                                                                          | Move the provider so it wraps only the Pega target (Step 3).                                                                                                                                                             |
+| The second launch stalls with no request and the loading state never clears                                            | The runtime provider was unmounted with the target and re-created, so it authenticated and bootstrapped again on an initialised runtime.                                                                                             | Mount the provider once and keep it mounted; hide the target instead of discarding it (Steps 0.5 and 3).                                                                                                                 |
 
 ---
 
 ## Notes
 
 - The generated components folder (its location is resolved during analysis and recorded in the Design Profile) has zero dependencies beyond the customer's existing UI library and the Pega SDK packages. No additional design system installation is needed.
-- The bootstrap module should handle token refresh/silent renewal automatically via the SDK auth client.
+- The runtime startup should handle token refresh/silent renewal automatically via the SDK auth client.
 - If the customer's app already has authentication, coordinate with their auth flow — the SDK auth client can share tokens if the same OAuth provider is used.
 - The Pega rendering container can be a modal, a sidebar, an inline section, or a full page. Which one is not a matter of taste — it is resolved in Step 0.2 from what the user asked for or from what their application already does.

package/templates/react-sdk-reference/.ai-common/skills/field-components.md

@@ -118,7 +118,7 @@ This pattern is design-system agnostic. It defines the **behavioral skeleton** e
 
 When implementing the render section with a specific design system:
 
-**1. Check the component-specific skill file** — `{{SKILL_DIR}}/field-skills/<ComponentName>.md` contains a **Design System Mapping** section that describes how to map the component's behavior to a DS primitive. Use it as a starting point.
+**1. Check the component-specific skill file** — `{{SKILL_DIR}}/field-skills/<ComponentName>{{SKILL_EXT}}` contains a **Design System Mapping** section that describes how to map the component's behavior to a DS primitive. Use it as a starting point.
 
 **2. If the chosen design system is not covered** — use the **UI control type** field in the same skill file (e.g., `"Combobox / typeahead autocomplete input"`) to identify the closest DS primitive.
 
@@ -139,6 +139,18 @@ When implementing the render section with a specific design system:
 
 ---
 
+## Visual Preservation
+
+When replacing an existing implementation, the replacement must look the same as the original:
+
+1. **Read the component's companion style file first** (for example a `.css` file in its folder). Note every class's visual intent — spacing, sizing, colours, and layout.
+2. Reproduce that intent through the new design system's inputs or variants, inline styles, or by keeping the style import — whichever gives the closest match.
+3. Never silently drop legacy styling utility classes — map each one to an equivalent style.
+
+In the embedded flow there is no original to preserve: the customer's look, recorded in the Design Profile, decides instead.
+
+---
+
 ## Event Handling
 
 > ⚠️ **CRITICAL — DO NOT DUPLICATE IMPORTS FROM FIELD UTILITIES**

package/templates/react-sdk-reference/.ai-common/skills/infra-components.md

@@ -108,7 +108,7 @@ When an infrastructure component renders another Pega component, resolve it thro
 
 The runtime contract — inputs, callback signatures, derivation logic, and localization — is identical regardless of design system. Only the rendered markup changes.
 
-**1. Check the component-specific skill file** — `{{SKILL_DIR}}/infra-skills/<ComponentName>.md` contains a **Design System Mapping** section. Use it as a starting point.
+**1. Check the component-specific skill file** — `{{SKILL_DIR}}/infra-skills/<ComponentName>{{SKILL_EXT}}` contains a **Design System Mapping** section. Use it as a starting point.
 
 **2. If the chosen design system is not covered** — use the component purpose description to identify the appropriate primitives (button, stepper, breadcrumb, divider, list).
 
@@ -129,6 +129,18 @@ The runtime contract — inputs, callback signatures, derivation logic, and loca
 
 ---
 
+## Visual Preservation
+
+When replacing an existing implementation, the replacement must look the same as the original:
+
+1. **Read the component's companion style file first** (for example a `.css` file in its folder). Note every class's visual intent — spacing, sizing, colours, and layout.
+2. Reproduce that intent through the new design system's inputs or variants, inline styles, or by keeping the style import — whichever gives the closest match.
+3. Never silently drop legacy styling utility classes — map each one to an equivalent style.
+
+In the embedded flow there is no original to preserve: the customer's look, recorded in the Design Profile, decides instead.
+
+---
+
 ## Registration
 
 Register infrastructure overrides in the project's component map under the component's Pega name. Because the SDK's own components are contributed as a spread of built-in entries, **an override must appear after that spread** — an entry listed before it is replaced by the SDK's version and the override silently does nothing.