@pega/sdk 0.0.5 → 0.0.6

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

@@ -0,0 +1,476 @@
+# Skill: Wire Pega Integration
+
+Guide the wiring of generated Pega components into a customer's existing application so that a Pega case flow renders seamlessly within their UI.
+
+---
+
+## Purpose
+
+After the `pega-components/` folder has been generated (via the component generation prompt), this skill describes the steps to integrate the Pega SDK into the customer's application — connecting authentication, bootstrapping the runtime, launching case flows on user action, and rendering the flow within the application's layout.
+
+**Step 0 is the exception.** It is a gate, not an integration step, and it runs _before_ generation — see its own heading for why.
+
+---
+
+## Prerequisites
+
+- The `pega-components/` folder exists with generated components and a registry file named `component-map` (the extension follows the customer's framework) — required from **Step 1 onward**. Step 0 runs before generation and needs only the customer's codebase and the Design Profile
+- The customer has a Pega Infinity environment with:
+  - An OAuth 2.0 client configured for the application
+  - A case type to embed (e.g., a service request, onboarding flow)
+  - The SDK configuration values (server URL, app alias, client ID)
+
+---
+
+## Never handle credentials
+
+Operator credentials are typed by a human, into a visible login form, and never touched by this skill. Do not request them, capture them, echo them, write them to any file, or include them in diagnostic output — at any step, and under any failure condition.
+
+This is stated here because it is broken during **debugging**, not during wiring. When a step fails and the temptation is to print the values being sent so the cause is visible, that is the moment the rule applies. Log the shape of what was sent, never the contents. Client secrets and access tokens are covered by the same rule; the configuration file holds only what is safe to serve to a browser.
+
+---
+
+## Integration Steps
+
+### Step 0 — Confirm the launch point and render target
+
+⛔ **Run this immediately after codebase analysis and before component generation** — not at wiring time, where it sits in this document's numbering.
+
+It sits after analysis because resolving the render target may require asking the user, and the options must be drawn from surfaces the application already has — which is what the Design Profile records. It sits before generation because it is the only step that can cancel the integration, and generation writes a folder of components. Analysis is safe to run first regardless: it adds a single profile file and changes nothing the customer owns.
+
+Two things must be settled before a single file changes: **what launches the flow**, and **where the flow renders**. Neither may be assumed, and neither may be deferred until the step that needs it.
+
+#### Step 0.1 — Resolve the launch point
+
+The user names the trigger in their own words — "on click of the apply loan button", "when someone submits the contact form", "from the Get started link". Resolve that description to a real control in their code before touching anything.
+
+Locate the named control by its visible label, then read the surrounding code and determine whether it already has behaviour attached. Look for:
+
+- an event handler bound to the named event
+- navigation of any kind — a link, a route change, a redirect
+- form submission or a server action
+- a state change that opens the customer's own dialog, drawer, or step
+- side effects such as analytics or logging on that same event
+
+**A control that "only navigates" still counts as existing behaviour.** The most common collision is exactly this: an _Apply_ or _Get started_ control that already routes to the customer's own application form. Embedding a Pega case there replaces the customer's whole flow, which is precisely the decision they must make consciously.
+
+**If the user named no launch point at all** — a request like "embed this case in my application" states the goal and nothing else — go to Step 0.3 and ask. This is not a detail to be filled in later.
+
+**If the control cannot be found**, report what you searched for and ask the user to identify it. Do not invent a new control, and do not substitute a similar-looking one.
+
+**If the control exists and already has behaviour**, stop and ask the user, naming the file, the control, and what it currently does:
+
+> The _[label]_ control in _[file]_ currently _[does X]_. Embedding the Pega case flow on this trigger replaces that behaviour. Do you want to override it?
+
+| Answer          | Action                                                                                                                                                                                                                                         |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Override        | Continue to Step 0.2. Record in the final summary exactly what was replaced so the user can restore it from version control                                                                                                                    |
+| Do not override | **Stop the entire wiring process.** Do not embed the flow, do not wire a different control, and do not leave partial edits behind. Report what was left untouched and tell the user the flow can be re-run once they nominate a trigger to use |
+
+**If the control exists and has no behaviour**, continue to Step 0.2.
+
+Never infer consent. An unanswered question is not an override.
+
+#### Step 0.2 — Resolve the render target
+
+The render target is the surface the case flow appears on — a dialog, a route, or a region of an existing page. It determines what Step 5 mounts into and how Step 6 tears down, so it is settled here rather than improvised there.
+
+Work through these in order and stop at the first that produces an answer.
+
+**1. The user stated it.** Read the request thoroughly before concluding they did not. "On click of apply loan _inside a modal_", "... _in a new page_", "... in the panel on the right" all state a target. When it is stated, use it — do not substitute a different surface because it looks easier to wire.
+
+**2. The control's existing behaviour states it.** When Step 0.1 found behaviour and the user approved the override, that behaviour is the answer. The customer has already decided how this journey presents itself, and the embedded flow inherits it:
+
+| What the control does today          | Where the Pega flow renders                                               |
+| ------------------------------------ | ------------------------------------------------------------------------- |
+| Opens a dialog, drawer or sheet      | The same kind of surface, built from the same primitive                   |
+| Navigates to a route or page         | **That same route.** The Pega flow replaces what the destination rendered |
+| Reveals a region of the current page | That same region                                                          |
+
+Taking over the route rather than adding a sibling one is deliberate: existing links and bookmarks keep working, and no unreachable page is left behind.
+
+**3. Otherwise, ask.** Reached when the control has no existing behaviour to inherit, or when no launch point was named at all. Go to Step 0.3.
+
+#### Step 0.3 — Ask, in the customer's own vocabulary
+
+A generic list of surfaces is not good enough. Draw the options from the application itself — the Design Profile records its overlay primitives, its routing approach, and its existing entry-point flows — and name real surfaces from their codebase so the choice is concrete:
+
+> Your application opens the _New request_ form in a dialog, and gives the loan journey its own full page. Where should the Pega case flow appear?
+>
+> - In a dialog, the way _New request_ does
+> - As a full page at its own route, the way the loan journey does
+> - Inline within a page you already have — tell me which one
+>
+> And what should open it? Name the control, and I will check whether it already does something first.
+
+**If the Design Profile has not been produced yet**, do not fall back to a generic list. Inspect the application directly for the same three things — how it routes, which overlay primitive it uses, and how its existing entry points open — and build the options from what you find.
+
+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
+
+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.
+
+This is a property of the target, not an edge case, and it must be handled while wiring rather than discovered later:
+
+| Resolved target                         | What is lost, and what must be restored                                                                                                                                                                                |
+| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A dialog, drawer, sheet, or any overlay | Its open state is a value in memory that the reload discards. Persist the intent to launch before the redirect, and re-open the overlay on return before mounting                                                      |
+| A route that is not at the site root    | The return lands on the address registered with the identity provider, which resolves to the site root — not to where the user was. Persist the launch location before the redirect, and navigate back to it on return |
+| A route at the site root                | Nothing. The return already lands there                                                                                                                                                                                |
+
+Use the application's own mechanisms for both halves — whatever it already uses to keep state across a reload, and whatever it already uses to navigate. Persist only what is needed to re-establish the launch context; never persist anything the user typed and never persist anything returned by authentication.
+
+**This only bites the first time a user authenticates.** Once a session exists the redirect does not happen, the application is never torn down, and the flow appears correctly — so an unhandled target looks intermittent rather than broken, and reliably survives testing. Treat it as always present.
+
+#### Step 0.5 — The runtime outlives the target; the launch does not
+
+Bootstrap initialises runtime globals that belong to the **page**, not to the target surface. They can be initialised once and only once. Creating a case is the opposite — it happens once per launch, every time the user asks for the flow.
+
+These two lifetimes are easy to collapse into one, because on a first launch they look identical: reveal the target, bootstrap, create a case, render. The mistake is binding the runtime's lifetime to the target's visibility, so that hiding the target discards the runtime:
+
+| Concern           | Lifetime                            | What goes wrong if bound to the target                                                                                                    |
+| ----------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| Runtime bootstrap | Once, for as long as the page lives | The second launch re-initialises an already-initialised runtime. It stalls before issuing any request, and the loading state never clears |
+| Case creation     | Once per launch                     | A launch that only fires when the flow is first set up never fires again, so a later launch reveals an empty target                       |
+
+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.
+
+**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.
+
+⛔ **This is a gate.** Do not continue to Step 1 without a resolved launch point and a resolved render target. Do not pick one because the user did not answer — an unanswered question is not a choice. Carry all of it forward: Step 4 attaches the launch to the resolved control, Step 5 mounts into the resolved target, and both honour the reload and lifetime obligations above.
+
+### Step 1 — Install SDK dependencies
+
+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                   |
+
+These are the only external additions. The generated `pega-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
+
+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 script ships inside the ConstellationJS package, under its distribution directory. Resolve the exact path from the installed package rather than copying the file anywhere.
+
+**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:
+
+| 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 |
+
+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.
+
+**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
+
+**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.
+
+### Step 1.2 — Load SDK styles and OAuth callback assets
+
+**SDK adapter stylesheet:**
+
+The SDK adapter package exports a stylesheet that provides styling for the infrastructure components the SDK itself renders (navigation bars, deferred loaders, vertical tabs, and dashboard filters). Without this stylesheet, these components render with class names but no matching CSS rules — resulting in unstyled or invisible controls.
+
+The three overridable chrome components — action buttons, stage indicators, and multi-step navigation — are exempt **when they have been generated and registered as overrides**, because they then carry the customer's own styling. Import the stylesheet regardless: the SDK still renders the non-overridable components, and it costs nothing when an override is in place.
+
+Import this stylesheet in the application's entry point, **before** the application's own global styles. Resolve the exact import specifier from the adapter package's `exports` map in its `package.json` (the CSS export path).
+
+**Verification criterion:** After importing, the browser's network panel shows the stylesheet loaded. Infrastructure components rendered by the SDK display visible, styled controls (navigation is positioned, deferred loaders show progress).
+
+**OAuth callback assets:**
+
+The SDK's auth package ships browser-facing assets used during the OAuth redirect flow:
+
+| Asset                   | Source (in auth package)                 | Required served location                                        |
+| ----------------------- | ---------------------------------------- | --------------------------------------------------------------- |
+| OAuth callback document | `lib/oauth-client/authDone.html`         | Served as `auth.html` at the application's web root             |
+| Callback script         | `lib/oauth-client/authDone.js`           | Served as `authDone.js` at the application's web root           |
+| Lock icon               | `lib/oauth-client/lock-closed-solid.svg` | Served as `lock-closed-solid.svg` at the application's web root |
+
+These files must be placed in the served-static directory identified in Step 2. The callback document must be renamed to `auth.html`; the other files keep their original names.
+
+**Verification criterion:** Navigating to `<origin>/auth.html` in the browser displays the OAuth callback page (a brief "Authorization complete" message).
+
+### Step 2 — Add SDK configuration
+
+The SDK configuration file (`sdk-config.json`) provides connection and authentication details for the Pega server. The SDK's auth client fetches this file at runtime via a **document-relative** URL (`./sdk-config.json`).
+
+**⚠️ CRITICAL — Document-relative fetch implications:**
+
+Because the fetch uses a relative URL, resolution depends on the route depth at which bootstrap runs:
+
+| Route when bootstrap executes | Resolved URL             | Result |
+| ----------------------------- | ------------------------ | ------ |
+| `/`                           | `/sdk-config.json`       | ✅     |
+| `/apply`                      | `/sdk-config.json`       | ✅     |
+| `/apply/` (trailing slash)    | `/apply/sdk-config.json` | ❌ 404 |
+| `/loans/apply`                | `/loans/sdk-config.json` | ❌ 404 |
+
+If the case flow can launch from a nested route or a route with a trailing slash, set an explicit document base URL (e.g., `<base href="/">` or the framework's equivalent base-path configuration) so that the relative fetch always resolves against the application root.
+
+**Placement — discovery procedure:**
+
+1. Identify the directory the project serves at its web root — locate it by finding where other served static assets (images, icons, manifests) reside
+2. Place `sdk-config.json` in that directory
+3. **Move, never copy.** If a `sdk-config.json` already exists at the project root (created by the scaffolding tool), move it to the served location and delete the original. A leftover duplicate at the project root silently diverges over time and can re-introduce authentication failures when someone edits the wrong copy.
+
+**Verification criterion:** Navigating to `<origin>/sdk-config.json` in the browser returns the JSON contents. Also verify this from the same route path where the case flow will bootstrap.
+
+**Required fields:**
+
+The file must contain two sections — `serverConfig` and `authConfig`:
+
+| Section        | Field                   | Purpose                                                                                              |
+| -------------- | ----------------------- | ---------------------------------------------------------------------------------------------------- |
+| `serverConfig` | `infinityRestServerUrl` | Pega Infinity REST API base URL                                                                      |
+| `serverConfig` | `appAlias`              | Application alias configured in Pega                                                                 |
+| `serverConfig` | `sdkContentServerUrl`   | Base URL for static SDK content (empty string = same origin)                                         |
+| `serverConfig` | `appPortal`             | Portal name to load (empty string = auto-detect)                                                     |
+| `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`   | `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`   | `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:**
+
+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.
+
+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:
+
+- 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.
+
+### Step 3 — Create the bootstrap module
+
+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.
+
+**⚠️ CRITICAL — Initialization must be a module-scoped singleton:**
+
+Store the bootstrap promise at module scope (outside any component, class instance, or framework lifecycle hook). If the host framework re-invokes initialization logic during development (e.g., dev-mode double invocation of mount/init callbacks for detecting side-effects), the singleton ensures:
+
+- The first invocation performs authentication and bootstrap
+- Subsequent invocations receive the already-resolved (or in-flight) promise
+- No duplicate authentication attempts or race conditions occur
+
+**Anti-pattern — guard flag + lifecycle cleanup cancellation:**
+
+Do NOT combine a "has already started" boolean guard with a cancellation flag set during lifecycle cleanup. Under dev-mode double invocation:
+
+1. First invocation starts authentication, sets the guard
+2. Cleanup runs, sets the cancellation flag
+3. Second invocation sees the guard and does nothing
+4. The first invocation completes authentication, checks the cancellation flag, and aborts
+5. Result: authentication succeeds but the readiness signal is never emitted — the UI hangs indefinitely showing a loading state
+
+The module-scoped singleton avoids this entirely because it is immune to component lifecycle.
+
+**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 `pega-components/component-map` registry file
+4. **Register the component creator** — tell the SDK runtime to use the registered components for rendering
+
+This module should expose:
+
+- A readiness signal (so the host app knows when Pega is ready)
+- The render context (needed to mount the bridge component)
+- The populated component registry
+- A reference to the auth client (for logout)
+
+### Step 4 — Wire the case launch trigger
+
+The control was resolved and cleared in Step 0.1. If that gate was skipped, stop and run it now — this is the step that overwrites the customer's behaviour, and consent must already be on record before it does.
+
+#### 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.
+
+On the trigger, call the SDK's mashup API to create a case. It takes three arguments, and an embedded flow needs all three:
+
+| Argument | Value                                                                             |
+| -------- | --------------------------------------------------------------------------------- |
+| 1        | The configured case type class                                                    |
+| 2        | The app context constant — `PCore.getConstants().APP.APP`                         |
+| 3        | An options object containing `pageName: 'pyEmbedAssignment'` and `startingFields` |
+
+**⚠️ CRITICAL — `startingFields` keys must be property names on the case type.**
+
+`startingFields` seeds values into the case being created. Its keys are not labels, not display names, and above all **not names from the customer's own domain model**. They must be properties the case type actually accepts at creation — the ones resolved from the server before wiring began. Having just analysed the customer's application is exactly what makes this easy to get wrong: their vocabulary is fresh, plausible, and has no relationship to what the case type declares.
+
+Pega validates the whole payload as a unit. **If a single key does not resolve, the entire create call is rejected** — no case is created, no per-field detail comes back, and the response gives no indication which key was at fault. One wrong name is indistinguishable from a broken integration, which is why this is worth getting right rather than debugging.
+
+Therefore:
+
+- Use only the property names resolved from the server for this case type. If none were resolved, pass an empty object.
+- Never guess, never map by resemblance, and never carry a name across from the customer's domain because it looks equivalent. A case-type property whose name or type happens to look like a plausible destination is the most dangerous match of all — seeding it puts the customer's data in the wrong place and the call succeeds, so nothing surfaces the error.
+- Always pass the key, empty when there is nothing to seed.
+
+**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.
+
+**⚠️ 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.
+
+The failure is easy to miss because it still renders. Two tells:
+
+- chrome the customer never asked for appears above and around the fields
+- components that only exist in the case view (case summary, operator details, attachments) show up as fallback markers, which reads like a registry gap but is not one
+
+**Do not invent options.** Only pass keys the mashup API documents. A flag whose name sounds like it suppresses case chrome does not narrow the render — `pageName` is the only thing that does.
+
+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.
+
+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.
+
+**Verification criterion:** the target surface shows the assignment's fields and its action buttons, and nothing else — no stage indicator, no case-history tab, no case summary panel.
+
+### Step 5 — Mount the bridge component
+
+**Important:** Bootstrap alone renders nothing. The SDK initializes state and returns a render context, but no UI appears until the host application explicitly mounts the bridge component with that context.
+
+Mount into the render target resolved in Step 0.2. What that means in practice differs by surface:
+
+| Resolved target | What to mount into                                                                                                                                                            |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A dialog        | The customer's own dialog primitive, built the way their other dialogs are. The bridge mounts in its content area, and dismissal is wired to the cancellation event in Step 6 |
+| A route or page | The component the route already rendered, replaced by the bridge. Keep the route's existing layout, navigation and page shell — only its content changes                      |
+| A page region   | The named region, in place. The surrounding page keeps rendering                                                                                                              |
+
+Do not introduce a surface the customer does not already use — if their application has no drawer, the flow does not arrive in one.
+
+Mount the bridge once and keep it mounted, per Step 0.5. Dismissing the flow hides the target; it does not tear the bridge down. Whatever the customer's own surfaces use to hide content without discarding it is what applies here.
+
+In that target:
+
+1. Render the SDK bridge component, passing:
+   - The render context from bootstrap (contains the root `getPConnect` accessor)
+   - 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)
+3. The bridge component will recursively resolve and render Pega components from the registry as the case flow progresses
+
+**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:
+
+- 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.
+
+### 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                          |
+
+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.
+
+At minimum it must establish that:
+
+1. The project builds, type-checks and lints cleanly
+2. The Pega runtime initializes and its readiness signal fires
+3. Triggering the case launch renders the form with the generated components, and no fallback component stands in for a missing registry entry
+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
+
+Do not report the integration as complete on static checks alone.
+
+---
+
+## Architecture Summary
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Customer's Application                     │
+│                                                             │
+│  ┌──────────────────────────────────────────────────────┐   │
+│  │  Customer's UI (nav, pages, routing, layout)          │   │
+│  │                                                       │   │
+│  │  [Trigger] ──→ SDK mashup API: create case            │   │
+│  │                                                       │   │
+│  │  ┌─────────────────────────────────────────────────┐  │   │
+│  │  │  Pega Rendering Container                        │  │   │
+│  │  │                                                  │  │   │
+│  │  │  SDK Bridge Component                            │  │   │
+│  │  │    ↓ resolves from registry                      │  │   │
+│  │  │  pega-components/ (generated, customer-styled)   │  │   │
+│  │  │    ↓ wired to                                    │  │   │
+│  │  │  PConnect (Pega runtime state + actions)         │  │   │
+│  │  └─────────────────────────────────────────────────┘  │   │
+│  └──────────────────────────────────────────────────────┘   │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Reference Implementation
+
+The Pega SDK repository includes a mashup/embedded sample application that demonstrates this exact integration pattern. When implementing for a customer, adapt the pattern to match their framework's idioms (lifecycle management, dependency injection, component rendering, event subscription).
+
+---
+
+## Troubleshooting
+
+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.                                                                                                                                                         |
+
+---
+
+## Notes
+
+- The generated `pega-components/` folder 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.
+- 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.