lecodes-viewer 0.19.0

package/src/embed.ts

@@ -0,0 +1,515 @@
+import { createHost, type EngineMode, type CreatorMethods } from './host'
+import type { PreviewError } from './sourcemapError'
+import { parseFontsHeader, type BootFont } from './utils/fonts'
+import { createUI } from './ui/createUI'
+import { createCanvasUIRenderer } from './ui/mountCanvasUI'
+import type { SafeAreaSpec } from './ui/safeAreaSpec'
+import { SHELL_SAFE_AREAS, asShell, type SimulatorShell } from './ui/shells'
+
+declare const __LECODES_EMBED_VERSION__: string | undefined
+
+/*
+ * The simulator runner — one iframe-hosted host that drives both the landing's live demos and (via
+ * the same-origin window API) the editor's preview. Built by vite.embed.config.ts into a
+ * self-contained static folder (relative asset paths), iframed by embedders:
+ *
+ *   <iframe src="/embed/?src=/examples/<slug>/app.js&zoom=0.75">
+ *
+ * A PUBLISHED platform app runs the same way with `?app=<uuid>` (docs/publish-plan.md): the runner
+ * reads the project's public policy (`/api/publish/<uuid>`), refuses when the browser/embed channel
+ * is off (or the embedding site isn't allowed), then fetches `/code/<uuid>.js` — same-origin, so the
+ * usual `isSafeSrc` rule holds. `?engine=lite|full` overrides the policy's engine: `lite` is the
+ * viewer-lite host (CSS-flexbox UI + OGL 3D, no wasm — what phones get), `full` is this runner's
+ * Filament/yoga host. See runPublished().
+ *
+ * The runner is drivable two ways, both funnelling through the single `mount()` primitive:
+ *
+ *   1. URL + postMessage (the landing). `?src=` boots a same-origin bundle; the embedder can then
+ *      SWITCH bundles without reloading the iframe via
+ *        iframe.contentWindow.postMessage({ type: 'lecodes-run', src: '/examples/…' }, iframeOrigin)
+ *      and change language / display zoom / device shell with { type: 'lecodes-lang', lang } /
+ *      { type: 'lecodes-zoom', zoom } / { type: 'lecodes-shell', shell }. Only the direct embedder
+ *      (the parent frame) is trusted to post — see the message handler. The runner posts BACK
+ *      { type: 'lecodes-orientation', orientation: 'landscape' | 'portrait' | 'auto' } when the app
+ *      calls app.setOrientation — the embedder owns the phone frame, so it is the one to turn it.
+ *
+ *   2. A direct same-origin window API (the editor):
+ *        iframe.contentWindow.lecodesEmbed.mount({ code, methods, safeArea, ui, zoom, keyboardTargets })
+ *      returns the live host handles (uiRoot etc.) for cross-frame inspection. No RPC.
+ *
+ * Crispness: the app is displayed at a fixed CSS `zoom` (default 0.75, `?zoom=` / mount({zoom}) to
+ * override) so the preview matches a real device while the app keeps its true logical viewport — no
+ * blurry `transform: scale()`. The engines size their backing stores to real device pixels via the
+ * host's resolution factor (devicePixelRatio × zoom); see host.ts / docs/simulator-plan.md.
+ *
+ * A switch is a clean reset: the current host is destroyed (engine state isn't shareable between
+ * bundles) and the new bundle mounts fresh in the same document, so the runtime's JS/wasm/fonts stay
+ * warm and no new iframe is needed.
+ *
+ * Top-level form (no iframe): a page may load `embed.js` (stable entry name of the built runner)
+ * as its own module after setting `window.lecodesEmbedConfig` — same options as the URL params.
+ * The published page uses it for phones (docs/publish-plan.md §D3): the app then IS the document,
+ * so browser viewport/keyboard/fullscreen behave as for any first-class page.
+ *
+ * The #loader spinner (embed.html) covers engine bring-up and every switch. Lazy-start policy
+ * (autorun on scroll, Play for 3D) belongs to the embedder — it simply delays creating the iframe
+ * (or the first run message); the runner runs whatever it's given immediately.
+ */
+const root = document.getElementById('app')!
+const loader = document.getElementById('loader')
+
+// Runner options come from the URL (`?src=…&zoom=…`, the iframe form) — or, when a page loads the
+// runner as its own top-level module (`<script type="module" src="/embed/embed.js">` after setting
+// `window.lecodesEmbedConfig = { app, engine, lang, zoom, shell }`), from that config; it wins over
+// the URL. That's how the published page runs an app fullscreen on a phone with no iframe: the
+// page IS the runner document, and only needs a `#app` (plus an optional `#loader`) in its markup.
+const params = new URLSearchParams(location.search)
+const pageConfig: Record<string, unknown> = (() => {
+  const cfg = (window as any).lecodesEmbedConfig
+  return cfg && typeof cfg === 'object' ? cfg : {}
+})()
+for (const [k, v] of Object.entries(pageConfig)) {
+  if (v !== undefined && v !== null && typeof v !== 'object') params.set(k, String(v))
+}
+
+// The simulator language, surfaced to the runtime through the same `window.getLanguage()` hook host
+// apps use (viewer createUtils reads it live). Seeded from `?lang=`, updated by setLang / messages.
+let currentLang = params.get('lang') || 'en'
+;(window as unknown as { getLanguage: () => string }).getLanguage = () => currentLang
+
+// app.setOrientation in the iframe form: the embedder owns the phone frame, so tell it (any origin —
+// the landing serves the runner from the CDN, and the payload is just the mode). Top-level form
+// (the published phone page): undefined → createUtils tries screen.orientation.lock itself.
+const orientationSink = window.parent !== window
+  ? (mode: string) => window.parent.postMessage({ type: 'lecodes-orientation', orientation: mode }, '*')
+  : undefined
+
+// The host currently mounted through the URL/postMessage driver (declared early so applyZoom can nudge
+// it on a live zoom change). The editor's direct mount() manages its own handle.
+let current: MountResult | null = null
+
+// Fixed display zoom (default 0.75) — parameterized so nothing hard-codes it. Applied on #app so the
+// app lays out at its true logical viewport (clientWidth) but rasterizes at the final on-screen size.
+const parseZoom = (raw: string | null | undefined): number | null => {
+  const z = raw != null ? Number(raw) : NaN
+  return Number.isFinite(z) && z > 0 ? z : null
+}
+let currentZoom = parseZoom(params.get('zoom')) ?? 0.75
+
+// Device shell for the URL/postMessage driver (the landing's shell selector). It maps to the app's
+// safe-area insets, which are baked into the host at mount — so a live shell change re-runs the
+// current bundle (like a language switch). The editor's direct mount() passes its own safeArea and
+// ignores this. `abstract` → undefined → the host keeps its neutral web insets.
+let currentShell: SimulatorShell = asShell(params.get('shell'))
+
+// Page-provided safe-area insets (top-level form only: `lecodesEmbedConfig.safeArea =
+// { top, right, bottom, left }` px, live-updated via `lecodesEmbed.setSafeArea`). A page that runs
+// the app fullscreen knows its real insets — its own banner, env(safe-area-inset-*) — and they win
+// over the shell's emulated ones. null = the shell decides.
+type Insets = { top?: number, right?: number, bottom?: number, left?: number }
+const asInsets = (raw: unknown): SafeAreaSpec | null => {
+  if (!raw || typeof raw !== 'object') return null
+  const n = (v: unknown) => (typeof v === 'number' && Number.isFinite(v) && v >= 0 ? Math.round(v) : 0)
+  const i = raw as Insets
+  const box: [number, number, number, number] = [n(i.top), n(i.right), n(i.bottom), n(i.left)]
+  return { portrait: box, landscape: box }
+}
+let pageSafeArea: SafeAreaSpec | null = asInsets(pageConfig.safeArea)
+const effectiveSafeArea = () => pageSafeArea ?? SHELL_SAFE_AREAS[currentShell]
+
+// Frameless viewer-lite: at zoom 1 the runner's #app IS the (iframe or page) viewport, so the lite
+// host needs no private iframe — vw/vh and fixed widgets resolve the same, and the app gets
+// first-class page semantics (keyboard/visualViewport, fullscreen, no iOS iframe focus-scroll).
+// Under a display zoom the private iframe stays: it's what keeps viewport units at the app's
+// logical size while #app rasterizes scaled.
+const liteFrameless = () => currentZoom === 1
+
+const applyZoom = (zoom: number) => {
+  currentZoom = zoom
+  ;(root.style as any).zoom = String(zoom)
+  // A zoom change leaves #app's layout size fixed (the app keeps its logical viewport), so the host's
+  // ResizeObserver stays silent — but the resolution factor moved, so nudge the engines to re-size.
+  current?.refreshResolution()
+}
+applyZoom(currentZoom)
+
+function setLoading(on: boolean) {
+  loader?.classList.toggle('embed-loader--on', on)
+}
+
+function showError(text: string) {
+  const el = document.createElement('div')
+  el.className = 'embed-error'
+  el.textContent = text
+  root.appendChild(el)
+}
+
+// Same-origin paths only — the runner must not become an open proxy for foreign code.
+const isSafeSrc = (src: unknown): src is string =>
+  typeof src === 'string' && src.startsWith('/') && !src.startsWith('//')
+
+// Header directives, as mountCreator sniffs them (see createViewer.ts).
+function sniffHeader(code: string): { engine: EngineMode; preloads: Set<string>; bootFonts: BootFont[] } {
+  // Wide enough for a `// fonts:` line with several faces (URLs make it the longest header line).
+  const header = code.slice(0, 2000)
+  const preloads = new Set<string>()
+  const preload = header.match(/\/\/ preload: (.+)/)
+  if (preload) {
+    for (const item of preload[1].split(';')) preloads.add(item)
+  }
+  const deferEngine = header.includes('// gl: disable') || header.includes('// gl: defer')
+  const glEnabled = !header.includes('// gl: disable')
+  const is2d = header.includes('// 2d: enable')
+  const engine: EngineMode =
+    is2d && glEnabled ? 'dual'
+    : is2d ? '2d'
+    : deferEngine ? 'defer'
+    : 'gl'
+  return { engine, preloads, bootFonts: parseFontsHeader(header) }
+}
+
+export type MountOptions = {
+  /** Same-origin bundle URL to fetch and run (the landing path). */
+  src?: string
+  /** Compiled bundle text to run directly (the editor path). Takes precedence over `src`. */
+  code?: string
+  /** Initial language (else the current `?lang=` / setLang value). */
+  lang?: string
+  /** Display zoom for #app (default 0.75). */
+  zoom?: number
+  /** Device-emulation safe-area override (the embedder's iOS/Android shells). */
+  safeArea?: SafeAreaSpec
+  /** Method overrides assigned onto the 3D creator (the editor's webcam-AR seam). */
+  methods?: Partial<CreatorMethods>
+  /** UI renderer: DOM (default) or the canvas-UI parity renderer. */
+  ui?: 'dom' | 'canvas'
+  /** Extra windows to also poll physical keys from (the editor passes its parent). */
+  keyboardTargets?: Window[]
+  /** Called when the bundle throws, mapped back to original source. */
+  onError?: (e: PreviewError) => void
+  /** app.setOrientation sink ("landscape" | "portrait" | "auto") — the editor turns its phone box.
+   *  Absent = the runner's default: post 'lecodes-orientation' to the parent frame, or (top-level
+   *  form) a best-effort screen.orientation.lock on the page. */
+  onOrientation?: (mode: string) => void
+}
+
+export type MountResult = {
+  _creator: any
+  _creator2d: any
+  _creatorUI: any
+  _creatorUtils: any
+  /** The app root the renderer paints into — walked by the editor's element inspector. */
+  uiRoot: HTMLElement
+  /** Re-push the resolution factor to the engines after a zoom change (no layout change). */
+  refreshResolution(): void
+  destroy(): void
+}
+
+// The single mounting primitive both entry points call. Applies zoom, brings up the engines/UI for
+// the given bundle, runs it, and returns the live host handles. The caller owns session/loader/UI —
+// mount is pure setup + teardown.
+export const mount = async (opts: MountOptions): Promise<MountResult> => {
+  if (opts.zoom !== undefined) applyZoom(opts.zoom)
+  if (opts.lang) currentLang = opts.lang
+
+  let code = opts.code
+  if (code === undefined) {
+    if (!opts.src) throw new Error('embed.mount: pass `code` or `src`')
+    const resp = await fetch(opts.src)
+    if (!resp.ok) throw new Error(`embed: ${opts.src} → HTTP ${resp.status}`)
+    code = await resp.text()
+  }
+
+  const { engine, preloads, bootFonts } = sniffHeader(code)
+  const host = await createHost(root, {
+    engine,
+    ui: opts.ui === 'canvas' ? createCanvasUIRenderer : createUI,
+    preloads,
+    bootFonts,
+    methods: opts.methods,
+    safeArea: opts.safeArea,
+    keyboardTargets: opts.keyboardTargets,
+    onOrientation: opts.onOrientation ?? orientationSink,
+  })
+
+  try {
+    host.run(code, { onError: opts.onError })
+  } catch {
+    // A synchronous boot throw is already reported through onError; swallow it so the host stays
+    // destroyable (whatever the bundle set up before throwing can still surface async errors).
+  }
+
+  // Clear the boot spinner (embed.html starts it on). The URL/postMessage driver manages loading
+  // separately via runFromSrc, but a direct mount() — the editor path — must clear it here, or the
+  // #loader overlay (z-index 9, opaque) hides the app that just mounted underneath it.
+  setLoading(false)
+
+  return {
+    _creator: host._creator,
+    _creator2d: host._creator2d,
+    _creatorUI: host._creatorUI,
+    _creatorUtils: host._creatorUtils,
+    uiRoot: root,
+    refreshResolution: () => host.refreshResolution(),
+    destroy: () => host.destroy(),
+  }
+}
+
+// ---- URL + postMessage driver (the landing) --------------------------------------------------------
+// Wraps `mount` with the loader spinner, error overlay and switch semantics: a monotonic session
+// guards against a slow fetch/mount losing the race to a newer request, and each switch destroys the
+// previous host and wipes #app (host.destroy() removes its canvases, but screens/overlays the UI
+// renderer appended — and our error overlays — are the runner's to clear).
+
+let currentSrc: string | null = null
+let currentApp: { uuid: string, engine: string | null } | null = null
+let session = 0
+
+/** Re-run whatever is mounted through the URL/postMessage driver (language / shell change). */
+function rerunCurrent() {
+  if (currentApp) runPublished(currentApp.uuid, currentApp.engine)
+  else if (currentSrc) runFromSrc(currentSrc)
+}
+
+async function runFromSrc(src: string) {
+  const mySession = ++session
+  currentSrc = src
+  currentApp = null
+  setLoading(true)
+  current?.destroy()
+  current = null
+  root.replaceChildren()
+  try {
+    const result = await mount({
+      src,
+      safeArea: effectiveSafeArea(),
+      onError: (error) => {
+        const base = error.detail ? `${error.message}: ${error.detail}` : error.message
+        // The follow-up native emit carries the decoded top engine frame (see wasmCrashSymbolizer).
+        showError(error.nativeFrames?.length ? `${base} — in ${error.nativeFrames[0]}` : base)
+      },
+    })
+    if (mySession !== session) { result.destroy(); return }
+    current = result
+  } catch (e) {
+    if (mySession === session) showError(String(e))
+  } finally {
+    if (mySession === session) setLoading(false)
+  }
+}
+
+function setLang(lang: string) {
+  const l = lang || 'en'
+  if (l === currentLang) return
+  currentLang = l
+  // Re-run so screens already built in the old language rebuild.
+  rerunCurrent()
+}
+
+function setShell(shell: string) {
+  const s = asShell(shell)
+  if (s === currentShell) return
+  currentShell = s
+  // The safe area is applied when the host is built, so re-run to re-mount with the new insets.
+  rerunCurrent()
+}
+
+// ---- Published apps (?app=<uuid>) ------------------------------------------------------------------
+// The platform's "open in browser" / iframe-embed channel. Policy first, then bundle: a project whose
+// browser channel is off must not run here even though its bundle URL is guessable — the developer's
+// printed QR points at the app, not at a web version they never looked at.
+
+type PublishPolicy = {
+  uuid?: string
+  published: boolean
+  web: { enabled: boolean, engine: 'lite' | 'full', desktopFrame: boolean }
+  embed: { enabled: boolean, referers: string[] }
+  meta: { gl: string, twoD: boolean, ar: boolean } | null
+  firstPartyOrigins?: string[]
+}
+
+/** Origin of the page embedding this runner (null when top-level or unknown). ancestorOrigins is
+ *  the reliable source (Chrome/Safari); the referrer is the Firefox fallback. */
+const parentOrigin = (): string | null => {
+  if (window.parent === window) return null
+  const anc = (location as any).ancestorOrigins as DOMStringList | undefined
+  if (anc && anc.length > 0) return anc[0]
+  try { return document.referrer ? new URL(document.referrer).origin : null } catch { return null }
+}
+
+/** Does the embedding site match an allowlist entry? Entries are the URLs the developer typed
+ *  ("https://example.com" or ".../some/page"): an origin match, or a referrer prefix match when
+ *  the entry carries a path. Empty allowlist = any site. */
+const embedderAllowed = (referers: string[], origin: string): boolean => {
+  if (referers.length === 0) return true
+  const referrer = document.referrer.toLowerCase()
+  return referers.some((raw) => {
+    const entry = raw.toLowerCase().replace(/\/+$/, '')
+    let entryOrigin: string
+    try { entryOrigin = new URL(entry.includes('://') ? entry : `https://${entry}`).origin } catch { return false }
+    if (entryOrigin !== origin.toLowerCase()) return false
+    const hasPath = entry.replace(/^https?:\/\//, '').includes('/')
+    return !hasPath || referrer.startsWith(entry)
+  })
+}
+
+const isProjectMember = async (uuid: string): Promise<boolean> => {
+  try {
+    const token = localStorage.getItem('accessToken')
+    if (!token) return false
+    const resp = await fetch(`/api/projects/${encodeURIComponent(uuid)}/publish`, { headers: { Authorization: `Bearer ${token}` } })
+    return resp.ok
+  } catch { return false }
+}
+
+// The bundle URL hosts fetch, bucketed like the mobile launcher (30 s) so a republish shows up
+// promptly without defeating the cache on every load.
+const publishedBundleUrl = (uuid: string) => `/code/${encodeURIComponent(uuid)}.js?ts=${Math.trunc(Date.now() / 30000) * 30000}`
+
+async function runPublished(uuid: string, engineParam: string | null) {
+  const mySession = ++session
+  currentSrc = null
+  currentApp = { uuid, engine: engineParam }
+  setLoading(true)
+  current?.destroy()
+  current = null
+  root.replaceChildren()
+
+  // The top-level form may inline the policy (`lecodesEmbedConfig.policy` — the published page
+  // already rendered from it, no-store), saving the round trip; the iframe form fetches it.
+  const inline = pageConfig.policy as PublishPolicy | undefined
+  let policy: PublishPolicy
+  if (inline && typeof inline === 'object' && inline.uuid === uuid) {
+    policy = inline
+  } else {
+    try {
+      const resp = await fetch(`/api/publish/${encodeURIComponent(uuid)}`, { cache: 'no-store' })
+      if (!resp.ok) throw new Error(`HTTP ${resp.status}`)
+      policy = await resp.json()
+    } catch {
+      if (mySession === session) { setLoading(false); showError('This app isn’t available.') }
+      return
+    }
+    if (mySession !== session) return
+  }
+
+  const origin = parentOrigin()
+  // Top-level, or iframed by the platform itself (the published page / editor) → first party.
+  const firstParty = origin === null || origin === location.origin || (policy.firstPartyOrigins ?? []).includes(origin)
+  let refusal: string | null = null
+  if (!policy.published) refusal = 'This app isn’t published right now.'
+  else if (firstParty && !policy.web.enabled) refusal = 'This app can’t be opened in the browser — get the LeCodes app.'
+  else if (!firstParty && !policy.embed.enabled) refusal = 'This app can’t be embedded on other sites.'
+  else if (!firstParty && !embedderAllowed(policy.embed.referers, origin!)) refusal = 'This site isn’t allowed to embed this app.'
+  // Developer preview (`?preview=1`, the Publish dialog's "Preview"): a signed-in project member
+  // may run the app before the browser channel is on. Same-origin with the platform, so its
+  // access token is in our localStorage; the member-only publish endpoint is the proof.
+  if (refusal && policy.published && firstParty && params.get('preview') === '1' && await isProjectMember(uuid)) refusal = null
+  if (mySession !== session) return
+  if (refusal) { setLoading(false); showError(refusal); return }
+
+  // Engine: the URL may force one; the policy's is the default; 2D can only run on the full host.
+  const engine: 'lite' | 'full' =
+    policy.meta?.twoD ? 'full'
+    : engineParam === 'full' || engineParam === 'lite' ? engineParam
+    : policy.web.engine
+
+  const src = publishedBundleUrl(uuid)
+  currentSrc = src
+  try {
+    if (engine === 'lite') {
+      const resp = await fetch(src)
+      if (!resp.ok) throw new Error(`embed: ${src} → HTTP ${resp.status}`)
+      const code = await resp.text()
+      if (mySession !== session) return
+      // Lazy chunk: the viewer-lite host — no wasm at all. Under a display zoom it keeps its own
+      // iframe inside #app (the app's CSS viewport = the phone's); at zoom 1 it mounts frameless
+      // (see liteFrameless). Zoom applies through #app like the full host.
+      // Deep path on purpose: the package index re-exports the 3D engine, and a dynamic import
+      // keeps every export — the host alone lets a `gl: disable` app skip the engine chunk
+      // (host.ts loads it lazily on first 3D use).
+      const { mountCreatorLite } = await import('lecodes-viewer-lite/src/host')
+      const lite = await mountCreatorLite(root, code, undefined, {
+        safeArea: effectiveSafeArea(),
+        onOrientation: orientationSink,
+        frame: !liteFrameless(),
+        onError: (error) => showError(error.detail ? `${error.message}: ${error.detail}` : error.message),
+      })
+      if (mySession !== session) { lite.destroy(); return }
+      current = {
+        _creator: lite._creator, _creator2d: undefined, _creatorUI: lite._creatorUI, _creatorUtils: lite._creatorUtils,
+        uiRoot: (lite.uiRoot ?? root) as HTMLElement,
+        // The lite host sizes its canvas from its root box; a display-zoom change is a layout
+        // change there (the box moves), so nothing extra to push.
+        refreshResolution: () => {},
+        destroy: () => lite.destroy(),
+      }
+    } else {
+      const result = await mount({
+        src,
+        safeArea: effectiveSafeArea(),
+        onError: (error) => {
+          const base = error.detail ? `${error.message}: ${error.detail}` : error.message
+          showError(error.nativeFrames?.length ? `${base} — in ${error.nativeFrames[0]}` : base)
+        },
+      })
+      if (mySession !== session) { result.destroy(); return }
+      current = result
+    }
+  } catch (e) {
+    if (mySession === session) showError(String(e))
+  } finally {
+    if (mySession === session) setLoading(false)
+  }
+}
+
+// The typed window API (both entry points share it). Exposed for the editor's direct same-origin use.
+;(window as any).lecodesEmbed = {
+  version: (typeof __LECODES_EMBED_VERSION__ !== 'undefined' && __LECODES_EMBED_VERSION__) || 'dev',
+  mount,
+  setLang,
+  setZoom: applyZoom,
+  setShell,
+  /** Top-level form: the page's real insets (`{ top, right, bottom, left }` px), applied live to the
+   *  running host (both engines expose `_setSafeAreaSpec`); null hands control back to the shell. */
+  setSafeArea(insets: Insets | null) {
+    pageSafeArea = asInsets(insets)
+    current?._creatorUI?._setSafeAreaSpec?.(effectiveSafeArea() ?? null)
+  },
+  destroy() { current?.destroy(); current = null; currentSrc = null; currentApp = null },
+}
+
+window.addEventListener('message', (e: MessageEvent) => {
+  // Only the direct embedder (the parent frame that hosts this iframe) may drive the runner. This is
+  // origin-agnostic on purpose: the landing serves the runner from the CDN (cross-origin to the page),
+  // so an `origin === location.origin` check would reject its own messages. `isSafeSrc` still confines
+  // `src` to same-origin bundle paths, so a stray poster can't make the runner fetch foreign code.
+  if (e.source !== window.parent) return
+  const data = e.data
+  if (!data) return
+  if (data.type === 'lecodes-run' && isSafeSrc(data.src)) {
+    runFromSrc(data.src)
+  } else if (data.type === 'lecodes-lang' && typeof data.lang === 'string') {
+    setLang(data.lang)
+  } else if (data.type === 'lecodes-zoom') {
+    const z = parseZoom(data.zoom)
+    if (z !== null) applyZoom(z)
+  } else if (data.type === 'lecodes-shell' && typeof data.shell === 'string') {
+    setShell(data.shell)
+  }
+})
+
+const initialSrc = params.get('src')
+const initialApp = params.get('app')
+
+if (initialApp) {
+  // A published platform app: policy-gated, same-origin bundle (see runPublished).
+  runPublished(initialApp, params.get('engine'))
+} else if (initialSrc === null || initialSrc === '') {
+  // No initial bundle: keep the loader up and wait for the first run message / mount() call.
+} else if (!isSafeSrc(initialSrc)) {
+  setLoading(false)
+  showError('embed: expected ?src=/path/to/app.js (same-origin)')
+} else {
+  runFromSrc(initialSrc)
+}