New Development for BAIP Trial Prototype

[jung-thomas]

Add new URL Parameter to force Reader Mode
Add new URL Parameter to set no header or customized header bar with reduced navigation options

This way an application could "host" a tutorial in a side window and force it into this minimize mode.

[jung-thomas]

Design for hosted / embedded tutorial mode

Design approved and committed to docs/superpowers/specs/2026-08-10-baip-embed-hosting-design.md. Summary below for the POC team.

Key finding: most of this already exists

• Reader / focus mode already ships — html[data-reader="on"] drives a CSS cascade that hides the right rail, breadcrumbs, footer, and Joule and dims the shellbar. Today it's only triggered by pressing the f key (no URL param, no button). We reuse this cascade.
• Picture-in-Picture side window already ships (documentPictureInPicture) — a floating always-on-top window with full/controller step modes.
• Framing is already allowed. The approuter sends Content-Security-Policy: frame-ancestors 'self' https://*.sap.com https://*.sap.cn https://*.cloud.sap … and no X-Frame-Options. So an iframe host on a *.sap.com / *.cloud.sap origin works today with zero header changes.
• Tutorial HTML is served identically per-slug regardless of query string (slug-keyed cache), so all embed behavior is client-side and ?embed= will not pollute the content cache. No server change needed for the core feature.

Host-facing contract (URL params)

Param	Values	Effect
embed	none	Hide shellbar, footer, breadcrumbs, right rail, Joule, alerts, cmd-palette, progress bar. Bare content.
embed	minimal	Replace the shellbar with a slim bar (SAP mark + title + step progress + theme toggle). No site nav/search/share/profile.
embed	reader	Force the existing reader mode.
embed	full	Reset — clears embed state + persisted flag (the escape hatch).
pip	1	Auto-launch the Picture-in-Picture window on load (combinable with any embed).
step	N	Open the tutorial at step N on load.
host	1	Shorthand = embed=minimal + pip=1 — the one-liner "hosted side window" preset.
host-origin	URL	The host's exact origin; used as the postMessage target and inbound filter (validated against the allow-list).

Persistence: the mode persists to localStorage (like reader mode). Safety: when embed=none, a small fixed "⤢ Open full site" pill is shown so a user can never get trapped in a chrome-less state; embed=full resets.

Works for both iframe and standalone window — the params are purely client-side.

postMessage bridge (host ↔ tutorial)

Loads only when framed or opened with an embed/pip/host param; inert otherwise. Origin-validated against the *.sap.com / *.cloud.sap family (never *).

• Tutorial → host: sap:tutorial:ready {slug,title,stepCount}, sap:tutorial:step-change {slug,stepIndex}, sap:tutorial:step-completed {slug,stepIndex}, sap:tutorial:completed {slug}.
• Host → tutorial: sap:tutorial:goto {stepIndex}, sap:tutorial:set-embed {mode}, sap:tutorial:set-theme {theme}.

This lets BAIP's side panel drive the tutorial to a step and react when the user completes one.

Scope

In scope: embed presets, pip=1 auto-launch, ?step=N deep-link, ?host=1 shorthand, narrow-frame auto-compact, postMessage bridge, and a DB-driven (admin-editable) host-origin allow-list (heaviest piece — may be phased behind a hardcoded allow-list initially, same interface).

Out of scope: server-rendered embed variant, composable per-chrome flags, signed host handshakes.

Action items for the POC team

• Confirm BAIP's trial origin(s) so they're covered by the CSP frame-ancestors allow-list and the bridge origin allow-list — add them if not already *.sap.com / *.cloud.sap.
• Confirm iframe vs. standalone window as the primary hosting path (both are supported regardless) so we shape the demo harness accordingly.

Next step: implementation plan.

[jung-thomas]

Test URLs — embedded / hosted mode (live on PROD)

The hosted-tutorial URL params from this issue are deployed and verified working on developers.sap.com. Swap hana-cloud-alerts for any tutorial / mission / concept slug.

Scenario	URL
Flagship hosted side-window (embed=minimal + auto-PiP)	https://developers.sap.com/tutorials/hana-cloud-alerts?host=1
Minimal chrome — slim embed bar (SAP mark + title + step progress + theme toggle), no nav/search/share/login	https://developers.sap.com/tutorials/hana-cloud-alerts?embed=minimal
Reader mode forced (equivalent to pressing f)	https://developers.sap.com/tutorials/hana-cloud-alerts?embed=reader
Bare content — no shellbar/footer/rail; shows "⤢ Open full site" escape pill	https://developers.sap.com/tutorials/hana-cloud-alerts?embed=none
Reset / escape hatch — clears the attribute and persisted localStorage['embed']	https://developers.sap.com/tutorials/hana-cloud-alerts?embed=full
Deep-link to a step	https://developers.sap.com/tutorials/hana-cloud-alerts?embed=minimal&step=3
Auto-launch Picture-in-Picture	https://developers.sap.com/tutorials/hana-cloud-alerts?pip=1

Host-facing contract

Param	Values	Effect
embed	none	Hide shellbar, footer, breadcrumbs, right rail, Joule, alerts, command palette, progress bar. Bare content.
embed	minimal	Hide real ui5-shellbar; render slim embed bar instead. No global nav/search/share/profile/login.
embed	reader	Force existing reader/focus mode.
embed	full	Explicit reset — clears the embed attribute and persisted localStorage key (the escape-hatch target).
pip	1	Auto-launch Picture-in-Picture side window. Combinable with any embed value.
step	N (int)	Open/scroll to step N on load.
host	1	Shorthand preset = embed=minimal + pip=1 (the flagship BAIP one-liner).
host-origin	URL	Host origin used as the postMessage target + inbound-origin filter (allow-list validated).

Notes

• Mode persists to localStorage — after one ?embed=minimal visit, plain visits stay minimal until ?embed=full.
• Works identically for iframe embedding and standalone-window hosting (params are purely client-side).
• Bidirectional postMessage bridge emits sap:tutorial:ready / step-change / step-completed / completed; only activates when framed or when an embed/pip/host param is present. Set host-origin=<BAIP origin> for the host to receive events.

Verified working on PROD end-to-end. ⚠️ Not yet on DEV — DEV needs a full deploy + content rebuild to pick up the embed island + CSS.