Mortezakoohjani 091b33a638 feat(platform): finalize commercial runtime, platform shell and hospitality production frontend

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-07-28 20:39:10 +03:30

3.3 KiB

Raw Blame History

Universal Embed Contract

Documentation contract only. No embed SDK, iframe host, or token issuer implementation.
Architecture: published-resource-architecture.md · ADR-022
Contract version: universal-embed.v1 (additive; open embed-type registry)

1. Purpose

Published Resources may be embedded into external websites or applications. Experience owns embed metadata (presentation, theming hooks, allowed origins refs). Business logic for actions inside the embed remains with owning services. All embed contexts identify the surface by publish_id.

2. Reserved embed types (open)

Embed type key	Meaning
`iframe`	Hosted iframe pointing at public/embed URL
`javascript_sdk`	Script loader + mount API
`widget`	Prebuilt widget shell
`popup`	Popup window
`inline`	Inline DOM mount
`modal`	Modal overlay
`floating_button`	Floating launcher
future.*	Unlimited future types

3. Embed metadata (conceptual)

EmbedDescriptor {
  publish_id
  tenant_id
  embed_types_allowed[]
  responsive_sizing { mode, min_height?, aspect_ratio? }
  theme_inheritance { inherit_host, token_ref? }
  security {
    sandbox_flags[]
    allowed_origins[]
    origin_validation
  }
  permission_delegation { scopes[], permission_prefix? }
  token_passing { mode }           # e.g. postMessage, query, header — owned by Identity patterns
  analytics_propagation { publish_id, embed_session_ref? }
}

4. Contract requirements

Responsive sizing

Descriptors MUST support fluid width and documented height strategies (auto, fixed, aspect).
Host pages MUST NOT be required to hardcode Experience internal layout ids.

Security & sandbox

Iframe embeds SHOULD declare sandbox flags and CSP expectations (edge/frontend responsibility when implemented).
Origin validation is mandatory for SDK/postMessage flows.
Secrets MUST NOT be embedded in public HTML; use short-lived tokens via Identity/platform patterns.

Permission delegation

Embeds may request limited scopes; evaluation remains Identity/Core.
Experience stores which scopes an embed advertises, not the auth decision.

Token passing

Modes are reserved: postMessage, signed_query, authorization_header.
Experience does not become token issuer of record.

Theming inheritance

Optional inherit-host tokens; Experience theme packs remain Experience-owned when applied to the resource itself.

Analytics propagation

All embed events record publish_id (and optional embed_session_ref).
Analytics ownership rules unchanged (ADR-022).

5. Ownership

Concern	Owner
Embed metadata / rendering presentation	Experience
Business action execution inside embed	Owning service of the action
Auth tokens	Identity / Core
Paid unlock inside embed	Payment
Host page integration UI	Frontend / external developers

3.3 KiB Raw Blame History