@ticketlayer/elements 0.4.0 → 1.0.0

package/dist/types/components.d.ts

@@ -11,7 +11,7 @@ import { TlCartData } from "./components/tl-cart/tl-cart";
 import { TlEventCardEvent } from "./components/tl-event-card/tl-event-card";
 import { TlAuthChanged } from "./components/tl-login/tl-login";
 import { TlOccurrence, TlOccurrenceSelectorTheme } from "./components/tl-occurrence-selector/tl-occurrence-selector";
-import { TlOrderData } from "./utils/order-summary";
+import { TlOrderData } from "@ticketlayer/elements-core";
 import { TlPromoApplied } from "./components/tl-promo-code/tl-promo-code";
 import { TlTicketData } from "./components/tl-ticket/tl-ticket";
 import { AddToCartItem } from "./components/tl-ticket-selector/tl-ticket-selector";
@@ -21,7 +21,7 @@ export { TlCartData } from "./components/tl-cart/tl-cart";
 export { TlEventCardEvent } from "./components/tl-event-card/tl-event-card";
 export { TlAuthChanged } from "./components/tl-login/tl-login";
 export { TlOccurrence, TlOccurrenceSelectorTheme } from "./components/tl-occurrence-selector/tl-occurrence-selector";
-export { TlOrderData } from "./utils/order-summary";
+export { TlOrderData } from "@ticketlayer/elements-core";
 export { TlPromoApplied } from "./components/tl-promo-code/tl-promo-code";
 export { TlTicketData } from "./components/tl-ticket/tl-ticket";
 export { AddToCartItem } from "./components/tl-ticket-selector/tl-ticket-selector";
@@ -109,6 +109,11 @@ export namespace Components {
      * @component tl-buy-tickets-wrapper
      * Wraps any content and opens the Ticketlayer modal when clicked.
      * Uses the SDK's modal manager which handles the iframe overlay.
+     * The web harness for `buyTicketsWrapperCore`. What a press does, what it
+     * announces and what happens when no client has been published are all in
+     * `@ticketlayer/elements-core` (AGENTS.md, TKT-11); what is left here is the
+     * Stencil surface, the accessibility attributes and the one genuinely web
+     * question the core refuses to answer - which key counts as a press.
      * @example <tl-buy-tickets-wrapper event-id="evt_001">
      *   <button>Buy Tickets</button>
      * </tl-buy-tickets-wrapper>
@@ -131,6 +136,14 @@ export namespace Components {
          */
         "occurrenceId"?: string;
     }
+    /**
+     * The web harness for `cartCore`.
+     * It renders and it forwards. The cart, the money rows, the subscription that
+     * keeps them current and every string are in `@ticketlayer/elements-core`
+     * (AGENTS.md, TKT-11); what is left here is the Stencil surface a host writes
+     * HTML against and the one genuinely web thing, finding the client the page
+     * published on `window.Ticketlayer`.
+     */
     interface TlCart {
         /**
           * Checkout button label
@@ -153,6 +166,13 @@ export namespace Components {
          */
         "showRemoveButtons": boolean;
     }
+    /**
+     * The web harness for `cartBadgeCore`.
+     * The count, the "99+" rule, the cart subscription and the remembered value
+     * are all in `@ticketlayer/elements-core`. What is here is the Stencil surface,
+     * the icon, and the two web things the core is handed: the client the page
+     * published and `localStorage`.
+     */
     interface TlCartBadge {
         /**
           * Badge only mode - only shows the count bubble, no icon or button
@@ -182,6 +202,9 @@ export namespace Components {
      * button, Escape, or `ui:modal-close-requested`. The panel embeds `<tl-cart>`,
      * so the actual cart rendering / remove / checkout is shared with the inline
      * cart; the drawer only adds the off-canvas chrome.
+     * The web harness for `cartDrawerCore`: the open/closed rule and the two
+     * intents are the core's (TKT-11). What stays here is the chrome and the one
+     * thing only a browser has, the Escape key.
      * @prop side - which edge the panel slides from (default 'right')
      * @event tlOpen  - the drawer opened
      * @event tlClose - the drawer closed
@@ -207,6 +230,9 @@ export namespace Components {
      * @component tl-checkout-wrapper
      * Wraps any content and opens the Ticketlayer checkout modal when clicked.
      * Uses the SDK's modal manager which handles the iframe overlay.
+     * The web harness for `checkoutWrapperCore`: it renders, it forwards, and it
+     * decides only which key press counts as activation. Everything else is in
+     * `@ticketlayer/elements-core` (AGENTS.md, TKT-11).
      * @example <tl-checkout-wrapper>
      *   <button>Proceed to Checkout</button>
      * </tl-checkout-wrapper>
@@ -218,6 +244,12 @@ export namespace Components {
          */
         "disabled": boolean;
     }
+    /**
+     * The web harness for `eventCardCore`.
+     * It renders and it forwards: which event is shown, how it is read, the status
+     * badge and the date are all in `@ticketlayer/elements-core` (AGENTS.md,
+     * TKT-11).
+     */
     interface TlEventCard {
         /**
           * Event data to display (tl-event-list passes this)
@@ -228,6 +260,13 @@ export namespace Components {
          */
         "eventId"?: string;
     }
+    /**
+     * tl-event-list - what the channel is selling, as a grid of tl-event-card.
+     * The web harness for `eventListCore`: it renders and it forwards. What to ask
+     * for, what came back and every string are in `@ticketlayer/elements-core`
+     * (AGENTS.md, TKT-11).
+     * Usage: <tl-event-list limit="12" columns="3"></tl-event-list>
+     */
     interface TlEventList {
         /**
           * Category filter
@@ -252,6 +291,12 @@ export namespace Components {
      * password is ever handled here.
      * States: enter email -> check your inbox (resend, enter code) -> signed in
      * (email + sign out).
+     * The web harness for `loginCore`: it renders and it forwards. The phases, the
+     * exchange, the auth subscriptions and every string are in
+     * `@ticketlayer/elements-core` (AGENTS.md, TKT-11). What is left here is the
+     * Stencil surface and the two genuinely web things: the client the page
+     * published on `window.Ticketlayer`, and `window.location.search`, which is
+     * where this runtime keeps the `?code=` the core asks for.
      * Usage: <tl-login></tl-login>
      * @event tlAuthChanged  - signed in or out ({ customer, authenticated })
      * @event tlMagicLinkSent - a link was requested for an email
@@ -274,6 +319,9 @@ export namespace Components {
      * the SDK): event, date, ticket count, total and status per row. Clicking a
      * row expands it to show the order's tickets (tl-order-tickets). Shows
      * tl-login inline when nobody is signed in.
+     * The web harness for `myOrdersCore`: it renders and it forwards. Who is
+     * signed in, the two auth subscriptions that keep that current, the listing
+     * and every string are in `@ticketlayer/elements-core` (AGENTS.md, TKT-11).
      * Usage: <tl-my-orders></tl-my-orders>
      * @event tlOrderSelect - a row was expanded ({ orderId })
      * @event tlError       - the orders could not be loaded
@@ -319,6 +367,12 @@ export namespace Components {
      *     page uses; `?redirect_status=` from a Stripe return is honoured too
      *  3. the SDK's `checkout:completed` event, for a page that mounts this before
      *     the customer pays
+     * The web harness for `orderConfirmationCore`: it renders and it forwards. All
+     * three of those routes, the money rows, the event lookup and every string are
+     * in `@ticketlayer/elements-core` (AGENTS.md, TKT-11). What is left here is the
+     * Stencil surface and the two genuinely web things: the client the page
+     * published on `window.Ticketlayer`, and `window.location.search`, which is
+     * where this runtime keeps the parameters the core asks for.
      * Usage: <tl-order-confirmation order-id="ord_xxx"></tl-order-confirmation>
      * @event tlOrderLoaded - the order was loaded
      * @event tlError       - the order could not be loaded
@@ -348,18 +402,14 @@ export namespace Components {
      * cards with PDF download. Fetches the order through the SDK (order-access
      * gated by the session), so it works on a confirmation page or in an account.
      * Usage: <tl-order-tickets order-id="ord_xxx"></tl-order-tickets>
-     * On an empty result it waits rather than concluding there is nothing.
-     * Tickets are issued asynchronously: the payment confirms, the order is
-     * marked paid, and entitlement issuance follows a moment later. A confirmation
-     * page therefore renders BEFORE the passes exist - reliably, not occasionally.
-     * The component used to answer that with "No tickets for this order yet",
-     * which is true and reads as "something went wrong" to someone who has just
-     * been charged. Refreshing showed them, so the only thing missing was the
-     * waiting.
-     * So: an empty order is treated as issuance in flight and polled, with the
-     * gaps widening, for about a minute. Then it stops and says the tickets are
-     * coming by email, because at that point something probably is wrong and a
-     * page that polls forever is worse than one that admits it.
+     * On an empty result it waits rather than concluding there is nothing: tickets
+     * are issued a moment after the order is paid, so a confirmation page renders
+     * before the passes exist. The waiting, the widening schedule behind it and
+     * the point at which it gives up are all in `orderTicketsCore`
+     * (`@ticketlayer/elements-core`, AGENTS.md, TKT-11), along with every string.
+     * This harness renders and forwards, and the one thing it owns is pairing
+     * `mount()` with its teardown - which is what stops the polling when the
+     * element goes off screen.
      */
     interface TlOrderTickets {
         /**
@@ -379,6 +429,8 @@ export namespace Components {
      * cart and publishes cart:updated, so tl-cart and badges re-render on their own.
      * The API has no un-redeem, so the applied state offers only "use a different
      * code", which clears the input for another redemption.
+     * The web harness for `promoCodeCore`: the redemption, the two error messages
+     * and every string are the core's (AGENTS.md, TKT-11).
      * Usage: <tl-promo-code></tl-promo-code>
      * @event tlPromoApplied - a code was redeemed ({ code, benefit, alreadyHeld, cart })
      * @event tlError        - the code was rejected
@@ -583,14 +635,19 @@ declare global {
         new (): HTMLTlBuyTicketsButtonElement;
     };
     interface HTMLTlBuyTicketsWrapperElementEventMap {
-        "tl-complete": OrderResult;
-        "tl-error": { message: string };
-        "tl-close": void;
+        "tlComplete": OrderResult;
+        "tlError": { message: string };
+        "tlClose": void;
     }
     /**
      * @component tl-buy-tickets-wrapper
      * Wraps any content and opens the Ticketlayer modal when clicked.
      * Uses the SDK's modal manager which handles the iframe overlay.
+     * The web harness for `buyTicketsWrapperCore`. What a press does, what it
+     * announces and what happens when no client has been published are all in
+     * `@ticketlayer/elements-core` (AGENTS.md, TKT-11); what is left here is the
+     * Stencil surface, the accessibility attributes and the one genuinely web
+     * question the core refuses to answer - which key counts as a press.
      * @example <tl-buy-tickets-wrapper event-id="evt_001">
      *   <button>Buy Tickets</button>
      * </tl-buy-tickets-wrapper>
@@ -618,6 +675,14 @@ declare global {
         "tlCartUpdated": { cart: TlCartData };
         "tlError": { message: string };
     }
+    /**
+     * The web harness for `cartCore`.
+     * It renders and it forwards. The cart, the money rows, the subscription that
+     * keeps them current and every string are in `@ticketlayer/elements-core`
+     * (AGENTS.md, TKT-11); what is left here is the Stencil surface a host writes
+     * HTML against and the one genuinely web thing, finding the client the page
+     * published on `window.Ticketlayer`.
+     */
     interface HTMLTlCartElement extends Components.TlCart, HTMLStencilElement {
         addEventListener<K extends keyof HTMLTlCartElementEventMap>(type: K, listener: (this: HTMLTlCartElement, ev: TlCartCustomEvent<HTMLTlCartElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
         addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
@@ -635,6 +700,13 @@ declare global {
     interface HTMLTlCartBadgeElementEventMap {
         "tlClick": { itemCount: number };
     }
+    /**
+     * The web harness for `cartBadgeCore`.
+     * The count, the "99+" rule, the cart subscription and the remembered value
+     * are all in `@ticketlayer/elements-core`. What is here is the Stencil surface,
+     * the icon, and the two web things the core is handed: the client the page
+     * published and `localStorage`.
+     */
     interface HTMLTlCartBadgeElement extends Components.TlCartBadge, HTMLStencilElement {
         addEventListener<K extends keyof HTMLTlCartBadgeElementEventMap>(type: K, listener: (this: HTMLTlCartBadgeElement, ev: TlCartBadgeCustomEvent<HTMLTlCartBadgeElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
         addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
@@ -661,6 +733,9 @@ declare global {
      * button, Escape, or `ui:modal-close-requested`. The panel embeds `<tl-cart>`,
      * so the actual cart rendering / remove / checkout is shared with the inline
      * cart; the drawer only adds the off-canvas chrome.
+     * The web harness for `cartDrawerCore`: the open/closed rule and the two
+     * intents are the core's (TKT-11). What stays here is the chrome and the one
+     * thing only a browser has, the Escape key.
      * @prop side - which edge the panel slides from (default 'right')
      * @event tlOpen  - the drawer opened
      * @event tlClose - the drawer closed
@@ -680,14 +755,17 @@ declare global {
         new (): HTMLTlCartDrawerElement;
     };
     interface HTMLTlCheckoutWrapperElementEventMap {
-        "tl-complete": OrderResult;
-        "tl-error": { message: string };
-        "tl-close": void;
+        "tlComplete": OrderResult;
+        "tlError": { message: string };
+        "tlClose": void;
     }
     /**
      * @component tl-checkout-wrapper
      * Wraps any content and opens the Ticketlayer checkout modal when clicked.
      * Uses the SDK's modal manager which handles the iframe overlay.
+     * The web harness for `checkoutWrapperCore`: it renders, it forwards, and it
+     * decides only which key press counts as activation. Everything else is in
+     * `@ticketlayer/elements-core` (AGENTS.md, TKT-11).
      * @example <tl-checkout-wrapper>
      *   <button>Proceed to Checkout</button>
      * </tl-checkout-wrapper>
@@ -710,6 +788,12 @@ declare global {
         "tlClick": { eventId: string };
         "tlError": { message: string };
     }
+    /**
+     * The web harness for `eventCardCore`.
+     * It renders and it forwards: which event is shown, how it is read, the status
+     * badge and the date are all in `@ticketlayer/elements-core` (AGENTS.md,
+     * TKT-11).
+     */
     interface HTMLTlEventCardElement extends Components.TlEventCard, HTMLStencilElement {
         addEventListener<K extends keyof HTMLTlEventCardElementEventMap>(type: K, listener: (this: HTMLTlEventCardElement, ev: TlEventCardCustomEvent<HTMLTlEventCardElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
         addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
@@ -727,6 +811,13 @@ declare global {
     interface HTMLTlEventListElementEventMap {
         "tlEventClick": { eventId: string };
     }
+    /**
+     * tl-event-list - what the channel is selling, as a grid of tl-event-card.
+     * The web harness for `eventListCore`: it renders and it forwards. What to ask
+     * for, what came back and every string are in `@ticketlayer/elements-core`
+     * (AGENTS.md, TKT-11).
+     * Usage: <tl-event-list limit="12" columns="3"></tl-event-list>
+     */
     interface HTMLTlEventListElement extends Components.TlEventList, HTMLStencilElement {
         addEventListener<K extends keyof HTMLTlEventListElementEventMap>(type: K, listener: (this: HTMLTlEventListElement, ev: TlEventListCustomEvent<HTMLTlEventListElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
         addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
@@ -754,6 +845,12 @@ declare global {
      * password is ever handled here.
      * States: enter email -> check your inbox (resend, enter code) -> signed in
      * (email + sign out).
+     * The web harness for `loginCore`: it renders and it forwards. The phases, the
+     * exchange, the auth subscriptions and every string are in
+     * `@ticketlayer/elements-core` (AGENTS.md, TKT-11). What is left here is the
+     * Stencil surface and the two genuinely web things: the client the page
+     * published on `window.Ticketlayer`, and `window.location.search`, which is
+     * where this runtime keeps the `?code=` the core asks for.
      * Usage: <tl-login></tl-login>
      * @event tlAuthChanged  - signed in or out ({ customer, authenticated })
      * @event tlMagicLinkSent - a link was requested for an email
@@ -782,6 +879,9 @@ declare global {
      * the SDK): event, date, ticket count, total and status per row. Clicking a
      * row expands it to show the order's tickets (tl-order-tickets). Shows
      * tl-login inline when nobody is signed in.
+     * The web harness for `myOrdersCore`: it renders and it forwards. Who is
+     * signed in, the two auth subscriptions that keep that current, the listing
+     * and every string are in `@ticketlayer/elements-core` (AGENTS.md, TKT-11).
      * Usage: <tl-my-orders></tl-my-orders>
      * @event tlOrderSelect - a row was expanded ({ orderId })
      * @event tlError       - the orders could not be loaded
@@ -831,6 +931,12 @@ declare global {
      *     page uses; `?redirect_status=` from a Stripe return is honoured too
      *  3. the SDK's `checkout:completed` event, for a page that mounts this before
      *     the customer pays
+     * The web harness for `orderConfirmationCore`: it renders and it forwards. All
+     * three of those routes, the money rows, the event lookup and every string are
+     * in `@ticketlayer/elements-core` (AGENTS.md, TKT-11). What is left here is the
+     * Stencil surface and the two genuinely web things: the client the page
+     * published on `window.Ticketlayer`, and `window.location.search`, which is
+     * where this runtime keeps the parameters the core asks for.
      * Usage: <tl-order-confirmation order-id="ord_xxx"></tl-order-confirmation>
      * @event tlOrderLoaded - the order was loaded
      * @event tlError       - the order could not be loaded
@@ -854,18 +960,14 @@ declare global {
      * cards with PDF download. Fetches the order through the SDK (order-access
      * gated by the session), so it works on a confirmation page or in an account.
      * Usage: <tl-order-tickets order-id="ord_xxx"></tl-order-tickets>
-     * On an empty result it waits rather than concluding there is nothing.
-     * Tickets are issued asynchronously: the payment confirms, the order is
-     * marked paid, and entitlement issuance follows a moment later. A confirmation
-     * page therefore renders BEFORE the passes exist - reliably, not occasionally.
-     * The component used to answer that with "No tickets for this order yet",
-     * which is true and reads as "something went wrong" to someone who has just
-     * been charged. Refreshing showed them, so the only thing missing was the
-     * waiting.
-     * So: an empty order is treated as issuance in flight and polled, with the
-     * gaps widening, for about a minute. Then it stops and says the tickets are
-     * coming by email, because at that point something probably is wrong and a
-     * page that polls forever is worse than one that admits it.
+     * On an empty result it waits rather than concluding there is nothing: tickets
+     * are issued a moment after the order is paid, so a confirmation page renders
+     * before the passes exist. The waiting, the widening schedule behind it and
+     * the point at which it gives up are all in `orderTicketsCore`
+     * (`@ticketlayer/elements-core`, AGENTS.md, TKT-11), along with every string.
+     * This harness renders and forwards, and the one thing it owns is pairing
+     * `mount()` with its teardown - which is what stops the polling when the
+     * element goes off screen.
      */
     interface HTMLTlOrderTicketsElement extends Components.TlOrderTickets, HTMLStencilElement {
     }
@@ -884,6 +986,8 @@ declare global {
      * cart and publishes cart:updated, so tl-cart and badges re-render on their own.
      * The API has no un-redeem, so the applied state offers only "use a different
      * code", which clears the input for another redemption.
+     * The web harness for `promoCodeCore`: the redemption, the two error messages
+     * and every string are the core's (AGENTS.md, TKT-11).
      * Usage: <tl-promo-code></tl-promo-code>
      * @event tlPromoApplied - a code was redeemed ({ code, benefit, alreadyHeld, cart })
      * @event tlError        - the code was rejected
@@ -1076,6 +1180,11 @@ declare namespace LocalJSX {
      * @component tl-buy-tickets-wrapper
      * Wraps any content and opens the Ticketlayer modal when clicked.
      * Uses the SDK's modal manager which handles the iframe overlay.
+     * The web harness for `buyTicketsWrapperCore`. What a press does, what it
+     * announces and what happens when no client has been published are all in
+     * `@ticketlayer/elements-core` (AGENTS.md, TKT-11); what is left here is the
+     * Stencil surface, the accessibility attributes and the one genuinely web
+     * question the core refuses to answer - which key counts as a press.
      * @example <tl-buy-tickets-wrapper event-id="evt_001">
      *   <button>Buy Tickets</button>
      * </tl-buy-tickets-wrapper>
@@ -1100,16 +1209,24 @@ declare namespace LocalJSX {
         /**
           * Emitted when the modal closes
          */
-        "onTl-close"?: (event: TlBuyTicketsWrapperCustomEvent<void>) => void;
+        "onTlClose"?: (event: TlBuyTicketsWrapperCustomEvent<void>) => void;
         /**
           * Emitted when purchase completes successfully
          */
-        "onTl-complete"?: (event: TlBuyTicketsWrapperCustomEvent<OrderResult>) => void;
+        "onTlComplete"?: (event: TlBuyTicketsWrapperCustomEvent<OrderResult>) => void;
         /**
           * Emitted when an error occurs
          */
-        "onTl-error"?: (event: TlBuyTicketsWrapperCustomEvent<{ message: string }>) => void;
+        "onTlError"?: (event: TlBuyTicketsWrapperCustomEvent<{ message: string }>) => void;
     }
+    /**
+     * The web harness for `cartCore`.
+     * It renders and it forwards. The cart, the money rows, the subscription that
+     * keeps them current and every string are in `@ticketlayer/elements-core`
+     * (AGENTS.md, TKT-11); what is left here is the Stencil surface a host writes
+     * HTML against and the one genuinely web thing, finding the client the page
+     * published on `window.Ticketlayer`.
+     */
     interface TlCart {
         /**
           * Checkout button label
@@ -1148,6 +1265,13 @@ declare namespace LocalJSX {
          */
         "showRemoveButtons"?: boolean;
     }
+    /**
+     * The web harness for `cartBadgeCore`.
+     * The count, the "99+" rule, the cart subscription and the remembered value
+     * are all in `@ticketlayer/elements-core`. What is here is the Stencil surface,
+     * the icon, and the two web things the core is handed: the client the page
+     * published and `localStorage`.
+     */
     interface TlCartBadge {
         /**
           * Badge only mode - only shows the count bubble, no icon or button
@@ -1181,6 +1305,9 @@ declare namespace LocalJSX {
      * button, Escape, or `ui:modal-close-requested`. The panel embeds `<tl-cart>`,
      * so the actual cart rendering / remove / checkout is shared with the inline
      * cart; the drawer only adds the off-canvas chrome.
+     * The web harness for `cartDrawerCore`: the open/closed rule and the two
+     * intents are the core's (TKT-11). What stays here is the chrome and the one
+     * thing only a browser has, the Escape key.
      * @prop side - which edge the panel slides from (default 'right')
      * @event tlOpen  - the drawer opened
      * @event tlClose - the drawer closed
@@ -1208,6 +1335,9 @@ declare namespace LocalJSX {
      * @component tl-checkout-wrapper
      * Wraps any content and opens the Ticketlayer checkout modal when clicked.
      * Uses the SDK's modal manager which handles the iframe overlay.
+     * The web harness for `checkoutWrapperCore`: it renders, it forwards, and it
+     * decides only which key press counts as activation. Everything else is in
+     * `@ticketlayer/elements-core` (AGENTS.md, TKT-11).
      * @example <tl-checkout-wrapper>
      *   <button>Proceed to Checkout</button>
      * </tl-checkout-wrapper>
@@ -1221,16 +1351,22 @@ declare namespace LocalJSX {
         /**
           * Emitted when the modal closes
          */
-        "onTl-close"?: (event: TlCheckoutWrapperCustomEvent<void>) => void;
+        "onTlClose"?: (event: TlCheckoutWrapperCustomEvent<void>) => void;
         /**
           * Emitted when checkout completes successfully
          */
-        "onTl-complete"?: (event: TlCheckoutWrapperCustomEvent<OrderResult>) => void;
+        "onTlComplete"?: (event: TlCheckoutWrapperCustomEvent<OrderResult>) => void;
         /**
           * Emitted when an error occurs
          */
-        "onTl-error"?: (event: TlCheckoutWrapperCustomEvent<{ message: string }>) => void;
+        "onTlError"?: (event: TlCheckoutWrapperCustomEvent<{ message: string }>) => void;
     }
+    /**
+     * The web harness for `eventCardCore`.
+     * It renders and it forwards: which event is shown, how it is read, the status
+     * badge and the date are all in `@ticketlayer/elements-core` (AGENTS.md,
+     * TKT-11).
+     */
     interface TlEventCard {
         /**
           * Event data to display (tl-event-list passes this)
@@ -1249,6 +1385,13 @@ declare namespace LocalJSX {
          */
         "onTlError"?: (event: TlEventCardCustomEvent<{ message: string }>) => void;
     }
+    /**
+     * tl-event-list - what the channel is selling, as a grid of tl-event-card.
+     * The web harness for `eventListCore`: it renders and it forwards. What to ask
+     * for, what came back and every string are in `@ticketlayer/elements-core`
+     * (AGENTS.md, TKT-11).
+     * Usage: <tl-event-list limit="12" columns="3"></tl-event-list>
+     */
     interface TlEventList {
         /**
           * Category filter
@@ -1277,6 +1420,12 @@ declare namespace LocalJSX {
      * password is ever handled here.
      * States: enter email -> check your inbox (resend, enter code) -> signed in
      * (email + sign out).
+     * The web harness for `loginCore`: it renders and it forwards. The phases, the
+     * exchange, the auth subscriptions and every string are in
+     * `@ticketlayer/elements-core` (AGENTS.md, TKT-11). What is left here is the
+     * Stencil surface and the two genuinely web things: the client the page
+     * published on `window.Ticketlayer`, and `window.location.search`, which is
+     * where this runtime keeps the `?code=` the core asks for.
      * Usage: <tl-login></tl-login>
      * @event tlAuthChanged  - signed in or out ({ customer, authenticated })
      * @event tlMagicLinkSent - a link was requested for an email
@@ -1302,6 +1451,9 @@ declare namespace LocalJSX {
      * the SDK): event, date, ticket count, total and status per row. Clicking a
      * row expands it to show the order's tickets (tl-order-tickets). Shows
      * tl-login inline when nobody is signed in.
+     * The web harness for `myOrdersCore`: it renders and it forwards. Who is
+     * signed in, the two auth subscriptions that keep that current, the listing
+     * and every string are in `@ticketlayer/elements-core` (AGENTS.md, TKT-11).
      * Usage: <tl-my-orders></tl-my-orders>
      * @event tlOrderSelect - a row was expanded ({ orderId })
      * @event tlError       - the orders could not be loaded
@@ -1353,6 +1505,12 @@ declare namespace LocalJSX {
      *     page uses; `?redirect_status=` from a Stripe return is honoured too
      *  3. the SDK's `checkout:completed` event, for a page that mounts this before
      *     the customer pays
+     * The web harness for `orderConfirmationCore`: it renders and it forwards. All
+     * three of those routes, the money rows, the event lookup and every string are
+     * in `@ticketlayer/elements-core` (AGENTS.md, TKT-11). What is left here is the
+     * Stencil surface and the two genuinely web things: the client the page
+     * published on `window.Ticketlayer`, and `window.location.search`, which is
+     * where this runtime keeps the parameters the core asks for.
      * Usage: <tl-order-confirmation order-id="ord_xxx"></tl-order-confirmation>
      * @event tlOrderLoaded - the order was loaded
      * @event tlError       - the order could not be loaded
@@ -1384,18 +1542,14 @@ declare namespace LocalJSX {
      * cards with PDF download. Fetches the order through the SDK (order-access
      * gated by the session), so it works on a confirmation page or in an account.
      * Usage: <tl-order-tickets order-id="ord_xxx"></tl-order-tickets>
-     * On an empty result it waits rather than concluding there is nothing.
-     * Tickets are issued asynchronously: the payment confirms, the order is
-     * marked paid, and entitlement issuance follows a moment later. A confirmation
-     * page therefore renders BEFORE the passes exist - reliably, not occasionally.
-     * The component used to answer that with "No tickets for this order yet",
-     * which is true and reads as "something went wrong" to someone who has just
-     * been charged. Refreshing showed them, so the only thing missing was the
-     * waiting.
-     * So: an empty order is treated as issuance in flight and polled, with the
-     * gaps widening, for about a minute. Then it stops and says the tickets are
-     * coming by email, because at that point something probably is wrong and a
-     * page that polls forever is worse than one that admits it.
+     * On an empty result it waits rather than concluding there is nothing: tickets
+     * are issued a moment after the order is paid, so a confirmation page renders
+     * before the passes exist. The waiting, the widening schedule behind it and
+     * the point at which it gives up are all in `orderTicketsCore`
+     * (`@ticketlayer/elements-core`, AGENTS.md, TKT-11), along with every string.
+     * This harness renders and forwards, and the one thing it owns is pairing
+     * `mount()` with its teardown - which is what stops the polling when the
+     * element goes off screen.
      */
     interface TlOrderTickets {
         /**
@@ -1415,6 +1569,8 @@ declare namespace LocalJSX {
      * cart and publishes cart:updated, so tl-cart and badges re-render on their own.
      * The API has no un-redeem, so the applied state offers only "use a different
      * code", which clears the input for another redemption.
+     * The web harness for `promoCodeCore`: the redemption, the two error messages
+     * and every string are the core's (AGENTS.md, TKT-11).
      * Usage: <tl-promo-code></tl-promo-code>
      * @event tlPromoApplied - a code was redeemed ({ code, benefit, alreadyHeld, cart })
      * @event tlError        - the code was rejected
@@ -1680,6 +1836,11 @@ declare module "@stencil/core" {
              * @component tl-buy-tickets-wrapper
              * Wraps any content and opens the Ticketlayer modal when clicked.
              * Uses the SDK's modal manager which handles the iframe overlay.
+             * The web harness for `buyTicketsWrapperCore`. What a press does, what it
+             * announces and what happens when no client has been published are all in
+             * `@ticketlayer/elements-core` (AGENTS.md, TKT-11); what is left here is the
+             * Stencil surface, the accessibility attributes and the one genuinely web
+             * question the core refuses to answer - which key counts as a press.
              * @example <tl-buy-tickets-wrapper event-id="evt_001">
              *   <button>Buy Tickets</button>
              * </tl-buy-tickets-wrapper>
@@ -1688,7 +1849,22 @@ declare module "@stencil/core" {
              * </tl-buy-tickets-wrapper>
              */
             "tl-buy-tickets-wrapper": LocalJSX.IntrinsicElements["tl-buy-tickets-wrapper"] & JSXBase.HTMLAttributes<HTMLTlBuyTicketsWrapperElement>;
+            /**
+             * The web harness for `cartCore`.
+             * It renders and it forwards. The cart, the money rows, the subscription that
+             * keeps them current and every string are in `@ticketlayer/elements-core`
+             * (AGENTS.md, TKT-11); what is left here is the Stencil surface a host writes
+             * HTML against and the one genuinely web thing, finding the client the page
+             * published on `window.Ticketlayer`.
+             */
             "tl-cart": LocalJSX.IntrinsicElements["tl-cart"] & JSXBase.HTMLAttributes<HTMLTlCartElement>;
+            /**
+             * The web harness for `cartBadgeCore`.
+             * The count, the "99+" rule, the cart subscription and the remembered value
+             * are all in `@ticketlayer/elements-core`. What is here is the Stencil surface,
+             * the icon, and the two web things the core is handed: the client the page
+             * published and `localStorage`.
+             */
             "tl-cart-badge": LocalJSX.IntrinsicElements["tl-cart-badge"] & JSXBase.HTMLAttributes<HTMLTlCartBadgeElement>;
             /**
              * @component tl-cart-drawer
@@ -1698,6 +1874,9 @@ declare module "@stencil/core" {
              * button, Escape, or `ui:modal-close-requested`. The panel embeds `<tl-cart>`,
              * so the actual cart rendering / remove / checkout is shared with the inline
              * cart; the drawer only adds the off-canvas chrome.
+             * The web harness for `cartDrawerCore`: the open/closed rule and the two
+             * intents are the core's (TKT-11). What stays here is the chrome and the one
+             * thing only a browser has, the Escape key.
              * @prop side - which edge the panel slides from (default 'right')
              * @event tlOpen  - the drawer opened
              * @event tlClose - the drawer closed
@@ -1707,12 +1886,28 @@ declare module "@stencil/core" {
              * @component tl-checkout-wrapper
              * Wraps any content and opens the Ticketlayer checkout modal when clicked.
              * Uses the SDK's modal manager which handles the iframe overlay.
+             * The web harness for `checkoutWrapperCore`: it renders, it forwards, and it
+             * decides only which key press counts as activation. Everything else is in
+             * `@ticketlayer/elements-core` (AGENTS.md, TKT-11).
              * @example <tl-checkout-wrapper>
              *   <button>Proceed to Checkout</button>
              * </tl-checkout-wrapper>
              */
             "tl-checkout-wrapper": LocalJSX.IntrinsicElements["tl-checkout-wrapper"] & JSXBase.HTMLAttributes<HTMLTlCheckoutWrapperElement>;
+            /**
+             * The web harness for `eventCardCore`.
+             * It renders and it forwards: which event is shown, how it is read, the status
+             * badge and the date are all in `@ticketlayer/elements-core` (AGENTS.md,
+             * TKT-11).
+             */
             "tl-event-card": LocalJSX.IntrinsicElements["tl-event-card"] & JSXBase.HTMLAttributes<HTMLTlEventCardElement>;
+            /**
+             * tl-event-list - what the channel is selling, as a grid of tl-event-card.
+             * The web harness for `eventListCore`: it renders and it forwards. What to ask
+             * for, what came back and every string are in `@ticketlayer/elements-core`
+             * (AGENTS.md, TKT-11).
+             * Usage: <tl-event-list limit="12" columns="3"></tl-event-list>
+             */
             "tl-event-list": LocalJSX.IntrinsicElements["tl-event-list"] & JSXBase.HTMLAttributes<HTMLTlEventListElement>;
             /**
              * tl-login - magic-link sign-in. The customer enters an email, we ask the SDK
@@ -1722,6 +1917,12 @@ declare module "@stencil/core" {
              * password is ever handled here.
              * States: enter email -> check your inbox (resend, enter code) -> signed in
              * (email + sign out).
+             * The web harness for `loginCore`: it renders and it forwards. The phases, the
+             * exchange, the auth subscriptions and every string are in
+             * `@ticketlayer/elements-core` (AGENTS.md, TKT-11). What is left here is the
+             * Stencil surface and the two genuinely web things: the client the page
+             * published on `window.Ticketlayer`, and `window.location.search`, which is
+             * where this runtime keeps the `?code=` the core asks for.
              * Usage: <tl-login></tl-login>
              * @event tlAuthChanged  - signed in or out ({ customer, authenticated })
              * @event tlMagicLinkSent - a link was requested for an email
@@ -1733,6 +1934,9 @@ declare module "@stencil/core" {
              * the SDK): event, date, ticket count, total and status per row. Clicking a
              * row expands it to show the order's tickets (tl-order-tickets). Shows
              * tl-login inline when nobody is signed in.
+             * The web harness for `myOrdersCore`: it renders and it forwards. Who is
+             * signed in, the two auth subscriptions that keep that current, the listing
+             * and every string are in `@ticketlayer/elements-core` (AGENTS.md, TKT-11).
              * Usage: <tl-my-orders></tl-my-orders>
              * @event tlOrderSelect - a row was expanded ({ orderId })
              * @event tlError       - the orders could not be loaded
@@ -1749,6 +1953,12 @@ declare module "@stencil/core" {
              *     page uses; `?redirect_status=` from a Stripe return is honoured too
              *  3. the SDK's `checkout:completed` event, for a page that mounts this before
              *     the customer pays
+             * The web harness for `orderConfirmationCore`: it renders and it forwards. All
+             * three of those routes, the money rows, the event lookup and every string are
+             * in `@ticketlayer/elements-core` (AGENTS.md, TKT-11). What is left here is the
+             * Stencil surface and the two genuinely web things: the client the page
+             * published on `window.Ticketlayer`, and `window.location.search`, which is
+             * where this runtime keeps the parameters the core asks for.
              * Usage: <tl-order-confirmation order-id="ord_xxx"></tl-order-confirmation>
              * @event tlOrderLoaded - the order was loaded
              * @event tlError       - the order could not be loaded
@@ -1759,18 +1969,14 @@ declare module "@stencil/core" {
              * cards with PDF download. Fetches the order through the SDK (order-access
              * gated by the session), so it works on a confirmation page or in an account.
              * Usage: <tl-order-tickets order-id="ord_xxx"></tl-order-tickets>
-             * On an empty result it waits rather than concluding there is nothing.
-             * Tickets are issued asynchronously: the payment confirms, the order is
-             * marked paid, and entitlement issuance follows a moment later. A confirmation
-             * page therefore renders BEFORE the passes exist - reliably, not occasionally.
-             * The component used to answer that with "No tickets for this order yet",
-             * which is true and reads as "something went wrong" to someone who has just
-             * been charged. Refreshing showed them, so the only thing missing was the
-             * waiting.
-             * So: an empty order is treated as issuance in flight and polled, with the
-             * gaps widening, for about a minute. Then it stops and says the tickets are
-             * coming by email, because at that point something probably is wrong and a
-             * page that polls forever is worse than one that admits it.
+             * On an empty result it waits rather than concluding there is nothing: tickets
+             * are issued a moment after the order is paid, so a confirmation page renders
+             * before the passes exist. The waiting, the widening schedule behind it and
+             * the point at which it gives up are all in `orderTicketsCore`
+             * (`@ticketlayer/elements-core`, AGENTS.md, TKT-11), along with every string.
+             * This harness renders and forwards, and the one thing it owns is pairing
+             * `mount()` with its teardown - which is what stops the polling when the
+             * element goes off screen.
              */
             "tl-order-tickets": LocalJSX.IntrinsicElements["tl-order-tickets"] & JSXBase.HTMLAttributes<HTMLTlOrderTicketsElement>;
             /**
@@ -1780,6 +1986,8 @@ declare module "@stencil/core" {
              * cart and publishes cart:updated, so tl-cart and badges re-render on their own.
              * The API has no un-redeem, so the applied state offers only "use a different
              * code", which clears the input for another redemption.
+             * The web harness for `promoCodeCore`: the redemption, the two error messages
+             * and every string are the core's (AGENTS.md, TKT-11).
              * Usage: <tl-promo-code></tl-promo-code>
              * @event tlPromoApplied - a code was redeemed ({ code, benefit, alreadyHeld, cart })
              * @event tlError        - the code was rejected