# Fastlane ticketshop — embedding

> Put a working ticket shop on a website. Three modes, one options list, one
> theme contract. This file is the whole integration surface in the order you
> need it; the human version of the same thing is the page at this origin's
> root.

Everything below is served from the origin you fetched this file from. In
production that is `https://embed-shop.fastlane.events`, written `<embed-host>`
in the snippets so they stay correct if you are reading this from staging or a
local rig.

## Pick a mode

| mode | what it is | use it when |
| --- | --- | --- |
| Popup Widget | one `<script>` tag; a pill in a corner opens a panel above your page | you want to add a shop without touching your layout |
| Inline Embed | `<fl-shop>`, an element you place yourself; as tall as its content | the shop belongs in the page, in your own column |
| hosted page | `https://shop.fastlane.events/{shop}/{event}` | you want a link, not code |

They sell the same tickets through the same checkout. The only difference is
where the shop appears.

## Popup Widget

```html
<script src="https://<embed-host>/widget.js"
        data-shop="<shop-slug>"
        data-event="<event-slug>"></script>
```

Classic script, not a module. Under 1 kB. Everything visible is drawn inside an
iframe, so nothing of your CSS reaches it and nothing of it reaches your CSS.

## Inline Embed

```html
<script type="module" src="https://<embed-host>/inline.js"></script>

<fl-shop shop="<shop-slug>" event="<event-slug>"></fl-shop>
```

A module, because it code-splits: the registry arrives up front and the shop
itself arrives when an element connects. Renders into a shadow root, so your
page's CSS cannot reach inside it and its CSS cannot leak out.

## Options

The same list on both embeds. On the `<script>` tag every name takes a `data-`
prefix, which HTML forces — a `<script>` may only carry custom attributes as
`data-*`. On the element they are bare.

| option | element | script tag | meaning |
| --- | --- | --- | --- |
| shop | `shop` | `data-shop` | required. The shop's slug |
| event | `event` | `data-event` | optional. Omitted, the shop's first event. A slug that matches nothing stops and says so in the console — we never quietly sell a different event under a stale link |
| theme | `theme` | `data-theme` | see below. Default: the organiser's own |
| language | `language` | `data-language` | optional. Defaults to the host document's `lang`, then the shop's own default |
| demo | `demo` | `data-demo` | presence turns on a fixture catalog. Never on a real embed |
| position | — | `data-position` | `bottom-left` (default) or `bottom-right`. Popup Widget only: an element has no corner to sit in, it sits where you put it |

## theme

`theme` takes one of four keywords or a theme object.

| value | meaning |
| --- | --- |
| absent | the organiser's own configuration. The default on all three modes |
| `light` | force the light palette |
| `dark` | force the dark palette, if the organiser authored one |
| `auto` | follow the visitor's OS setting. Available everywhere, the default nowhere — a visitor's laptop says nothing about your page |
| an object | your own palettes, below |

The object is an `EventThemeConfiguration`: `{ light: {…}, dark?: {…} }`, plus an
optional `mode` that pins which one is used.

```html
<fl-shop
  shop="<shop-slug>"
  theme='{"light":{"foreground":"#FFFFFF","primary":"#EE4287","primaryForeground":"#1A0A12"}}'
></fl-shop>
```

Three rules that cost people time:

1. **`light` is required.** An override without a usable `light` palette is
   refused whole — the shop keeps its own theme and explains in the console. It
   does not half-apply.
2. **It is observed.** Setting the attribute on a mounted element re-renders it;
   there is no reload and no remount.
   ```js
   document.querySelector("fl-shop").setAttribute("theme", JSON.stringify(myTheme));
   ```
3. **The background belongs to the theme.** A theme carrying a background colour
   or a ground image paints it, and the embed is then as opaque as the theme
   says. A theme with neither paints nothing, and your page shows through the
   gaps between its cards. Transparency is a property of the theme, not of the
   mode.

If it does not parse, the shop's own theme is used and the reason is logged. You
will never get a half-applied theme that looks like a design decision.

## What this will not do

- **It will not adopt your CSS, and yours cannot reach it.** The Popup Widget is
  an iframe; the Inline Embed is a shadow root. Style it through `theme`.
- **It will not guess a colour for your background.** We cannot read your page
  from inside an embed — the browser forbids it across origins. Over a busy
  hero, the readable version is the one your theme provides.
- **It will not quietly sell a different event.** A slug that matches nothing is
  an error, not a fallback.
- **It will not follow the visitor's OS theme unless you ask.** `auto` exists
  and is never the default.

## Checking your work

- The shop renders but is unstyled → the module could not fetch its stylesheet.
  Check the console for the URL it asked for.
- The panel opens on a blank box → the payment provider refuses to be framed;
  checkout breaks out to the top window by design.
- The theme did not apply → look for the console line. It names what was wrong.

## Machine-readable

This file is `<embed-host>/llms.txt` and is generated from the same source as
the page at `<embed-host>/`. If the two ever disagree, the page is right and
this is a bug — `bun run check:llms` in `fastlane-events/ticketshop-v2` is meant
to make that impossible.