@ticketlayer/elements-core 0.1.0

package/dist/cjs/money.js

@@ -0,0 +1,117 @@
+"use strict";
+/**
+ * The money rows a cart-shaped view renders: subtotal, the booking fee, a
+ * discount and the total.
+ *
+ * Pure: no Stencil, no DOM, no SDK. A core derives these figures and a harness
+ * renders what it returns, so the rule for what is shown can be unit tested on
+ * its own (the platform plan's headless-core split, AGENTS.md). It lived in
+ * `packages/elements/src/utils/cart-totals.ts` until the core split (TKT-68)
+ * and is re-exported from there, so every existing import still resolves.
+ *
+ * The client (`@ticketlayer/live`) already derives these figures from the
+ * sales-surface response and publishes `subtotal`, `fees`, `discount`,
+ * `total`, `hasFees` and `feeLabel` on the cart it hands us. Cores never
+ * import the client, so the same rule is stated here for the case where a
+ * host binds an older connector, or a bare sales cart: read what is there,
+ * and never invent money that is not.
+ *
+ * Money is integer minor units (2500 = 25.00) everywhere on this platform.
+ * Nothing here divides or multiplies money; the only division is the one
+ * `formatPrice` does to render it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FEE_LABEL_FALLBACK = void 0;
+exports.minorUnits = minorUnits;
+exports.expressesFee = expressesFee;
+exports.cartTotals = cartTotals;
+exports.selectionTotals = selectionTotals;
+/** Shown when the response names no fee of its own. */
+exports.FEE_LABEL_FALLBACK = 'Booking fee';
+/**
+ * Minor units, or null when the value is not minor units. Integers and
+ * all-digit strings only: a decimal is not minor units, and treating it as
+ * money here would put floating point into a total.
+ */
+function minorUnits(value) {
+    if (typeof value === 'number')
+        return Number.isInteger(value) ? value : null;
+    if (typeof value === 'string' && /^-?\d+$/.test(value))
+        return Number(value);
+    return null;
+}
+/**
+ * THE RULE: a fee of zero is not the same as no fee.
+ *
+ * Render the fee row when the response EXPRESSES a fee - an amount above
+ * zero, or a fee the surface has NAMED (a `type: 'fee'` line or a fee label)
+ * even where it computes to zero. A response with no fee figure at all, or a
+ * bare zero nothing names, expresses no fee: a channel with no fee profile
+ * renders no row, and we never show a "Booking fee 0.00" the surface did not
+ * put there.
+ */
+function expressesFee(fees, named) {
+    if (fees === null)
+        return named;
+    return fees > 0 || named;
+}
+const lineType = (line) => line.type || 'ticket';
+function cartTotals(cart) {
+    const c = cart || {};
+    const lines = Array.isArray(c.items) ? c.items : [];
+    const feeLines = lines.filter((l) => lineType(l) === 'fee');
+    const discountLines = lines.filter((l) => lineType(l) === 'discount');
+    const subtotal = minorUnits(c.itemsSubtotal) ??
+        minorUnits(c.subtotal) ??
+        lines
+            .filter((l) => !['fee', 'tax', 'discount'].includes(lineType(l)))
+            .reduce((sum, l) => sum + (minorUnits(l.subtotal) ?? 0), 0);
+    const feeFromLines = feeLines.length
+        ? feeLines.reduce((sum, l) => sum + (minorUnits(l.subtotal) ?? 0), 0)
+        : null;
+    const fees = minorUnits(c.totalFees) ?? minorUnits(c.fees) ?? feeFromLines;
+    const discountFromLines = discountLines.length
+        ? discountLines.reduce((sum, l) => sum + Math.abs(minorUnits(l.subtotal) ?? 0), 0)
+        : null;
+    const discount = minorUnits(c.totalDiscounts) ?? minorUnits(c.discount) ?? discountFromLines;
+    const tax = minorUnits(c.totalTax) ?? 0;
+    const named = (typeof c.feeLabel === 'string' && !!c.feeLabel) ||
+        feeLines.some((l) => typeof l.name === 'string' && !!l.name);
+    const label = (typeof c.feeLabel === 'string' && c.feeLabel) ||
+        feeLines.map((l) => l.name).find((n) => typeof n === 'string' && !!n) ||
+        exports.FEE_LABEL_FALLBACK;
+    return {
+        currency: c.currency || 'GBP',
+        subtotal,
+        fees: fees ?? 0,
+        discount: discount ?? 0,
+        // The server's total is what the buyer is charged, so it wins over any sum
+        // we could do here. We only add up when the response carries no total.
+        total: minorUnits(c.total) ?? subtotal + (fees ?? 0) + tax - (discount ?? 0),
+        // The client already applied the rule; honour its answer when it sent one.
+        showFee: typeof c.hasFees === 'boolean' ? c.hasFees : expressesFee(fees, named),
+        feeLabel: label,
+    };
+}
+/**
+ * The totals for a selection that is not yet a cart (tl-ticket-selector).
+ *
+ * The buyer-facing surface quotes no fee before the cart exists - there is no
+ * quote or preview operation, and the channel's fee profile is not exposed to
+ * a publishable key - so `quote` is null on every call today and no fee row is
+ * rendered. It is a parameter rather than an assumption so that the row lights
+ * up from data the moment the surface quotes one, and so the rule stays
+ * testable now.
+ */
+function selectionTotals(lines, quote = null) {
+    const subtotal = (lines || []).reduce((sum, l) => sum + (minorUnits(l.price) ?? 0) * (Math.max(0, Math.trunc(l.quantity || 0)) || 0), 0);
+    const fees = quote ? minorUnits(quote.amount) : null;
+    const named = !!quote?.label;
+    return {
+        subtotal,
+        fees: fees ?? 0,
+        total: subtotal + (fees ?? 0),
+        showFee: quote ? expressesFee(fees, named) : false,
+        feeLabel: quote?.label || exports.FEE_LABEL_FALLBACK,
+    };
+}

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/esm/client.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The client a core is handed.
+ *
+ * Cores receive a client and never construct one (TKT-11), and they never
+ * import `@ticketlayer/live`: this is the structural shape of the connector a
+ * host publishes, narrowed to what the cores in this package actually call.
+ * `@ticketlayer/elements`' `TicketlayerSDK` satisfies it, so a Stencil harness
+ * passes `getSDK()` straight through; a React Native harness will pass the
+ * connector `@ticketlayer/live/native` gives it.
+ *
+ * Everything the managers return is `unknown`. A core narrows what it reads and
+ * tolerates what it does not, because the same core runs against whatever
+ * client version the host installed.
+ */
+export interface ElementEventsManager {
+    getTicketTypes(eventId: string, occurrenceId: string): Promise<unknown[]>;
+}
+export interface ElementCartManager {
+    addItem(ticketTypeId: string, quantity: number, occurrenceId: string): Promise<unknown>;
+}
+export interface ElementClient {
+    getEventsManager(): ElementEventsManager;
+    /** Absent on an older connector, so every call site checks. */
+    getCartManager?(): ElementCartManager | null | undefined;
+}

package/dist/esm/client.js

@@ -0,0 +1,15 @@
+/**
+ * The client a core is handed.
+ *
+ * Cores receive a client and never construct one (TKT-11), and they never
+ * import `@ticketlayer/live`: this is the structural shape of the connector a
+ * host publishes, narrowed to what the cores in this package actually call.
+ * `@ticketlayer/elements`' `TicketlayerSDK` satisfies it, so a Stencil harness
+ * passes `getSDK()` straight through; a React Native harness will pass the
+ * connector `@ticketlayer/live/native` gives it.
+ *
+ * Everything the managers return is `unknown`. A core narrows what it reads and
+ * tolerates what it does not, because the same core runs against whatever
+ * client version the host installed.
+ */
+export {};

package/dist/esm/cores/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The registry: every core this package defines.
+ *
+ * `packages/elements/scripts/build-catalogue.mjs` reads it to emit
+ * `elements.catalogue.json`, and fails when a core claims the `web` runtime and
+ * no Stencil component answers to its tag. Splitting an element means adding it
+ * here and deleting its entry from the hand-kept
+ * `packages/elements/src/catalogue.manifest.json`; the emitter refuses a tag
+ * that is in both, so the two cannot drift while the split is half done.
+ */
+import type { AnyElementCore } from '../manifest.js';
+export { ticketSelectorCore } from './ticket-selector.js';
+export type { AddToCartItem, TicketSelectorDerived, TicketSelectorProps, TicketSelectorRow, TicketSelectorState, TicketSelectorStatus, TicketSelectorStrings, TlTicketType, } from './ticket-selector.js';
+/** Every core, by tag. */
+export declare const ELEMENT_CORES: Record<string, AnyElementCore>;

package/dist/esm/cores/index.js

@@ -0,0 +1,6 @@
+import { ticketSelectorCore } from './ticket-selector.js';
+export { ticketSelectorCore } from './ticket-selector.js';
+/** Every core, by tag. */
+export const ELEMENT_CORES = {
+    [ticketSelectorCore.tag]: ticketSelectorCore,
+};

package/dist/esm/cores/ticket-selector.d.ts

@@ -0,0 +1,104 @@
+import { type TlFeeQuote, type TlSelectionTotals } from '../money.js';
+export interface TlTicketType {
+    id: string;
+    occurrenceId: string;
+    name: string;
+    description?: string;
+    price: number;
+    currency: string;
+    availableQuantity: number;
+    maxPerOrder: number;
+    minPerOrder: number;
+    availabilityStatus: 'available' | 'limited' | 'sold_out';
+    sortOrder: number;
+}
+export interface AddToCartItem {
+    ticketTypeId: string;
+    quantity: number;
+}
+export interface TicketSelectorProps {
+    eventId: string;
+    occurrenceId: string;
+    showButton: boolean;
+    buttonLabel: string;
+}
+export interface TicketSelectorState {
+    ticketTypes: TlTicketType[];
+    quantities: Record<string, number>;
+    loading: boolean;
+    error: string | null;
+    adding: boolean;
+    addSuccess: boolean;
+    /**
+     * The fee the surface has quoted for this selection.
+     *
+     * There is no quote today: the buyer-facing surface exposes no fee until a
+     * cart is checked out (no quote or preview operation, and the channel's fee
+     * profile is not readable with a publishable key), so this stays null and no
+     * fee row is rendered rather than a made-up one. It is state rather than an
+     * assumption so the row lights up from data the moment the surface quotes
+     * one, and so the rule stays testable now.
+     */
+    feeQuote: TlFeeQuote | null;
+}
+export interface TicketSelectorRow {
+    id: string;
+    name: string;
+    description: string | null;
+    priceLabel: string;
+    quantity: number;
+    soldOut: boolean;
+    limited: boolean;
+    canDecrease: boolean;
+    canIncrease: boolean;
+}
+export interface TicketSelectorDerived {
+    rows: TicketSelectorRow[];
+    totals: TlSelectionTotals;
+    totalItems: number;
+    currency: string | undefined;
+    subtotalLabel: string;
+    feeLabel: string;
+    totalLabel: string;
+    /** Whether the tickets / fee / total block is rendered at all. */
+    showTotals: boolean;
+    actionLabel: string;
+    actionDisabled: boolean;
+}
+export type TicketSelectorStatus = 'loading' | 'error' | 'ready';
+declare const STRINGS: {
+    selectTickets: string;
+    adding: string;
+    added: string;
+    limited: string;
+    soldOut: string;
+    ticketsRow: string;
+    totalRow: string;
+    decrease: string;
+    increase: string;
+    loadFailed: string;
+    addFailed: string;
+    noClient: string;
+};
+export type TicketSelectorStrings = typeof STRINGS;
+export declare const ticketSelectorCore: import("../define.js").ElementCore<TicketSelectorProps, TicketSelectorState, TicketSelectorDerived, {
+    load(): Promise<void>;
+    changeQuantity(ticketTypeId: string, delta: number): void;
+    addToCart(): Promise<void>;
+    setFeeQuote(quote: TlFeeQuote | null): void;
+    connectFailed(message: string): void;
+}, TicketSelectorStatus, {
+    selectTickets: string;
+    adding: string;
+    added: string;
+    limited: string;
+    soldOut: string;
+    ticketsRow: string;
+    totalRow: string;
+    decrease: string;
+    increase: string;
+    loadFailed: string;
+    addFailed: string;
+    noClient: string;
+}>;
+export {};

package/dist/esm/cores/ticket-selector.js

@@ -0,0 +1,213 @@
+/**
+ * `tl-ticket-selector`: the reference core.
+ *
+ * This is the whole of what the element does. The Stencil harness in
+ * `packages/elements/src/components/tl-ticket-selector/` renders `view` and
+ * forwards the three `tl*` events; it decides nothing, holds no copy and does
+ * no arithmetic. A React Native harness will render the same view.
+ *
+ * Behaviour is the behaviour the Stencil component had before the split, to
+ * the letter: the same quantity clamping, the same reset after a successful
+ * add, the same three second success message, the same button text, and the
+ * same rule that no fee row is shown until the surface quotes a fee. The one
+ * thing that did not come across is the `console.log` tracing, which a library
+ * should not do for its host.
+ */
+import { defineElement } from '../define.js';
+import { selectionTotals } from '../money.js';
+const STRINGS = {
+    selectTickets: 'Select Tickets',
+    adding: 'Adding...',
+    added: 'Added to cart!',
+    limited: 'Limited',
+    soldOut: 'Sold Out',
+    ticketsRow: 'Tickets',
+    totalRow: 'Total',
+    decrease: 'Decrease quantity',
+    increase: 'Increase quantity',
+    loadFailed: 'Failed to load tickets',
+    addFailed: 'Failed to add to cart',
+    noClient: 'SDK not initialized.',
+};
+/** How long the "Added to cart!" message stays up. */
+const SUCCESS_MS = 3000;
+const totalsOf = (ctx) => selectionTotals(ctx.state.ticketTypes.map((tt) => ({ price: tt.price, quantity: ctx.state.quantities[tt.id] || 0 })), ctx.state.feeQuote);
+const totalItemsOf = (state) => Object.values(state.quantities).reduce((sum, qty) => sum + qty, 0);
+export const ticketSelectorCore = defineElement({
+    tag: 'tl-ticket-selector',
+    docs: 'Pick quantities of the ticket types on sale for one occurrence, and add them to the cart.',
+    category: 'purchase',
+    runtimes: ['web', 'native'],
+    tokens: [
+        'background',
+        'border',
+        'border-hover',
+        'error',
+        'error-bg',
+        'font-family',
+        'foreground',
+        'muted',
+        'muted-foreground',
+        'primary',
+        'primary-foreground',
+        'radius-md',
+        'radius-sm',
+        'spacing-1',
+        'spacing-2',
+        'spacing-3',
+        'spacing-4',
+        'success',
+        'warning',
+        'warning-bg',
+    ],
+    sdkMethods: ['cart.addItem', 'events.getTicketTypes'],
+    props: {
+        eventId: { type: 'string', attr: 'event-id', required: true, docs: 'Event ID' },
+        occurrenceId: { type: 'string', attr: 'occurrence-id', required: true, docs: 'Occurrence ID' },
+        showButton: { type: 'boolean', attr: 'show-button', default: true, docs: 'Show add to cart button' },
+        buttonLabel: { type: 'string', attr: 'button-label', default: 'Add to Cart', docs: 'Button label' },
+    },
+    events: {
+        tlAddToCart: {
+            detail: '{ items: AddToCartItem[]; }',
+            docs: 'Emitted when items are added to cart',
+        },
+        tlQuantityChange: {
+            detail: '{ ticketTypeId: string; quantity: number; total: number; }',
+            docs: 'Emitted when quantity changes',
+        },
+        tlError: {
+            detail: '{ message: string; }',
+            docs: 'Emitted on error',
+        },
+    },
+    strings: STRINGS,
+    statuses: ['loading', 'error', 'ready'],
+    state: () => ({
+        ticketTypes: [],
+        quantities: {},
+        loading: true,
+        error: null,
+        adding: false,
+        addSuccess: false,
+        feeQuote: null,
+    }),
+    status: ({ state }) => (state.loading ? 'loading' : state.error ? 'error' : 'ready'),
+    derive: (ctx) => {
+        const { state, strings, props, formatMoney } = ctx;
+        const totals = totalsOf(ctx);
+        const totalItems = totalItemsOf(state);
+        const currency = state.ticketTypes[0]?.currency;
+        const rows = state.ticketTypes.map((tt) => {
+            const quantity = state.quantities[tt.id] || 0;
+            const soldOut = tt.availabilityStatus === 'sold_out';
+            return {
+                id: tt.id,
+                name: tt.name,
+                description: tt.description ?? null,
+                priceLabel: formatMoney(tt.price, tt.currency),
+                quantity,
+                soldOut,
+                limited: tt.availabilityStatus === 'limited',
+                canDecrease: !soldOut && quantity > 0,
+                canIncrease: !soldOut && quantity < tt.maxPerOrder,
+            };
+        });
+        return {
+            rows,
+            totals,
+            totalItems,
+            currency,
+            subtotalLabel: formatMoney(totals.subtotal, currency),
+            feeLabel: formatMoney(totals.fees, currency),
+            totalLabel: formatMoney(totals.total, currency),
+            showTotals: totals.showFee && totalItems > 0,
+            actionLabel: state.adding
+                ? strings.adding
+                : totalItems === 0
+                    ? strings.selectTickets
+                    : `${props.buttonLabel} - ${formatMoney(totals.total)}`,
+            actionDisabled: totalItems === 0 || state.adding,
+        };
+    },
+    actions: (ctx) => ({
+        /** Read the ticket types for the current event and occurrence. */
+        async load() {
+            try {
+                ctx.setState({ loading: true, error: null });
+                const types = (await ctx.client().getEventsManager().getTicketTypes(ctx.props.eventId, ctx.props.occurrenceId));
+                const quantities = {};
+                for (const type of types)
+                    quantities[type.id] = 0;
+                ctx.setState({ ticketTypes: types, quantities });
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : ctx.strings.loadFailed;
+                ctx.setState({ error: message });
+                ctx.emit('tlError', { message });
+            }
+            finally {
+                ctx.setState({ loading: false });
+            }
+        },
+        /** Nudge one row's quantity, clamped to 0 and the type's maxPerOrder. */
+        changeQuantity(ticketTypeId, delta) {
+            const ticketType = ctx.state.ticketTypes.find((t) => t.id === ticketTypeId);
+            if (!ticketType)
+                return;
+            const current = ctx.state.quantities[ticketTypeId] || 0;
+            const quantity = Math.max(0, Math.min(ticketType.maxPerOrder, current + delta));
+            ctx.setState((state) => ({ quantities: { ...state.quantities, [ticketTypeId]: quantity } }));
+            // After setState, so the total is the one the buyer can now see.
+            ctx.emit('tlQuantityChange', { ticketTypeId, quantity, total: totalsOf(ctx).total });
+        },
+        /**
+         * Add every selected line to the cart, then clear the selection.
+         *
+         * With no client, or a client too old to carry a cart manager, the
+         * selection is still cleared and `tlAddToCart` still fires: a host that
+         * listens for the event and does its own cart keeps working.
+         */
+        async addToCart() {
+            const items = Object.entries(ctx.state.quantities)
+                .filter(([, quantity]) => quantity > 0)
+                .map(([ticketTypeId, quantity]) => ({ ticketTypeId, quantity }));
+            if (items.length === 0)
+                return;
+            ctx.setState({ adding: true, addSuccess: false });
+            try {
+                const cart = ctx.optionalClient()?.getCartManager?.();
+                if (cart) {
+                    for (const item of items) {
+                        await cart.addItem(item.ticketTypeId, item.quantity, ctx.props.occurrenceId);
+                    }
+                }
+                const quantities = {};
+                for (const type of ctx.state.ticketTypes)
+                    quantities[type.id] = 0;
+                ctx.setState({ quantities, addSuccess: true });
+                ctx.after(SUCCESS_MS, () => ctx.setState({ addSuccess: false }));
+                ctx.emit('tlAddToCart', { items });
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : ctx.strings.addFailed;
+                ctx.setState({ error: message });
+                ctx.emit('tlError', { message });
+            }
+            finally {
+                ctx.setState({ adding: false });
+            }
+        },
+        /** What the surface quoted for this selection, when it ever quotes one. */
+        setFeeQuote(quote) {
+            ctx.setState({ feeQuote: quote });
+        },
+        /**
+         * The host never produced a client. Shown, not emitted: the element has
+         * nothing to say to a page that has not started Live yet.
+         */
+        connectFailed(message) {
+            ctx.setState({ error: message || ctx.strings.noClient, loading: false });
+        },
+    }),
+});

package/dist/esm/define.d.ts

@@ -0,0 +1,156 @@
+/**
+ * `defineElement`: the shape every Ticketlayer element is built in.
+ *
+ * The platform plan's section 2.7 and AGENTS.md: behaviour lives in a headless
+ * core, views live in thin per-runtime harnesses. This module is the contract
+ * between the two. A core declares what it is (tag, category, runtimes, props,
+ * events, strings, tokens, the SDK methods it calls) and how it behaves (its
+ * state, the status it reports, the values it derives and the actions it
+ * offers). A harness creates an instance, renders `view`, and forwards the
+ * events. A harness never decides anything.
+ *
+ * Nothing here touches a DOM, a React tree or a network: no element, no node,
+ * no fetch, and no import of `@ticketlayer/live`. A core is handed a client, it
+ * never constructs one (TKT-11).
+ *
+ * The declarative half is also the manifest: `manifestOf` in `./manifest.js`
+ * projects it to the JSON the catalogue is emitted from, so the facts a
+ * consumer reads are the same object the code runs on rather than a second
+ * copy kept by hand.
+ */
+import type { TokenName } from '@ticketlayer/theme';
+import type { ElementClient } from './client.js';
+/** Where a core's harnesses run. */
+export type Runtime = 'web' | 'native';
+/** How the catalogue groups an element. */
+export type ElementCategory = 'discovery' | 'purchase' | 'cart' | 'checkout' | 'account' | 'tickets';
+/** The prop types a harness can carry across every runtime. */
+export type PropType = 'string' | 'number' | 'boolean' | 'object' | 'array';
+/**
+ * One prop, as the core declares it. `attr` is the web attribute the Stencil
+ * harness exposes, or null for a prop a host can only set as a property; the
+ * catalogue emitter fails when a harness disagrees with what is declared here.
+ */
+export interface PropSpec<V> {
+    type: PropType;
+    attr: string | null;
+    default?: V;
+    required?: boolean;
+    docs: string;
+}
+export type PropSpecs<P> = {
+    [K in keyof P]-?: PropSpec<P[K]>;
+};
+/**
+ * One `tl*` event. `detail` is the payload type written out, because the
+ * catalogue is JSON and a type is not: it must read exactly as the harness
+ * declares it, which the emitter checks against the Stencil build.
+ */
+export interface EventSpec {
+    detail: string;
+    docs: string;
+}
+/** The copy a core renders, so a harness holds no strings of its own. */
+export type StringMap = Record<string, string>;
+/** What a core offers a harness to call. Actions may be async. */
+export type ActionMap = Record<string, (...args: never[]) => unknown>;
+/** What `status`, `derive` and a rendered view are computed from. */
+export interface ViewContext<P extends object, S extends object, Str extends StringMap> {
+    props: Readonly<P>;
+    state: Readonly<S>;
+    strings: Readonly<Str>;
+    /** Minor units to the locale's currency string, for example 1333 to "13.33". */
+    formatMoney(amountInMinorUnits: number, currency?: string): string;
+}
+/** What an action is handed. */
+export interface ActionContext<P extends object, S extends object, Str extends StringMap> extends ViewContext<P, S, Str> {
+    /** A patch merged into the state, which notifies the harness. */
+    setState(patch: Partial<S> | ((state: Readonly<S>) => Partial<S>)): void;
+    /** Emit a declared event. An undeclared name throws. */
+    emit(event: string, detail: unknown): void;
+    /** The client, or a throw when the host has not supplied one. */
+    client(): ElementClient;
+    /** The client, or null when the host has not supplied one. Never throws. */
+    optionalClient(): ElementClient | null;
+    /** A timer the instance clears on destroy. */
+    after(ms: number, run: () => void): void;
+}
+/** A core, as `defineElement` returns it. */
+export interface ElementCore<P extends object, S extends object, D extends object, A extends ActionMap, Status extends string, Str extends StringMap> {
+    readonly tag: string;
+    readonly docs: string;
+    readonly category: ElementCategory;
+    readonly runtimes: readonly Runtime[];
+    /**
+     * The `@ticketlayer/theme` tokens the element's harnesses render with, by
+     * canonical name and nothing else. Not `--tl-primary`, not an alias, and
+     * never a value: a token's default is written once, in
+     * `packages/theme/tokens.json`. `TokenName` is generated from that file, so
+     * a token renamed there stops this line compiling, and
+     * `packages/elements/scripts/check-core-tokens.mjs` fails a web harness whose
+     * stylesheet reaches for a token the core did not declare.
+     */
+    readonly tokens: readonly TokenName[];
+    /** The client methods the core calls, as `manager.method`. */
+    readonly sdkMethods: readonly string[];
+    readonly props: PropSpecs<P>;
+    readonly events: Readonly<Record<string, EventSpec>>;
+    readonly strings: Readonly<Str>;
+    /** Every value `status` can return; a harness renders one branch per entry. */
+    readonly statuses: readonly Status[];
+    readonly state: (props: Readonly<P>) => S;
+    readonly status: (ctx: ViewContext<P, S, Str>) => Status;
+    readonly derive: (ctx: ViewContext<P, S, Str>) => D;
+    readonly actions: (ctx: ActionContext<P, S, Str>) => A;
+}
+export type ElementDefinition<P extends object, S extends object, D extends object, A extends ActionMap, Status extends string, Str extends StringMap> = ElementCore<P, S, D, A, Status, Str>;
+/** Everything a harness renders from, recomputed on every change. */
+export interface ElementView<P extends object, S extends object, D extends object, Status extends string, Str extends StringMap> {
+    status: Status;
+    props: Readonly<P>;
+    state: Readonly<S>;
+    strings: Readonly<Str>;
+    derived: D;
+}
+export interface CreateElementOptions<P extends object, Str extends StringMap> {
+    props?: Partial<P>;
+    /**
+     * The client, or a resolver for it. A resolver lets a harness hand over the
+     * one the host published without the core knowing how it was found; a
+     * resolver that throws is treated as no client by `optionalClient`.
+     */
+    client?: ElementClient | null | (() => ElementClient | null);
+    /** Where a declared event goes. A harness maps it onto its own emitter. */
+    emit?: (event: string, detail: unknown) => void;
+    /** Copy overrides, per instance. */
+    strings?: Partial<Str>;
+    /** The locale money is formatted in. */
+    locale?: string;
+    /** The currency used when a value carries none. */
+    currency?: string;
+}
+export interface ElementInstance<P extends object, S extends object, D extends object, A extends ActionMap, Status extends string, Str extends StringMap> {
+    readonly core: ElementCore<P, S, D, A, Status, Str>;
+    readonly props: Readonly<P>;
+    readonly state: Readonly<S>;
+    readonly view: ElementView<P, S, D, Status, Str>;
+    readonly actions: A;
+    setProps(next: Partial<P>): void;
+    setClient(client: ElementClient | null | (() => ElementClient | null)): void;
+    subscribe(listener: (view: ElementView<P, S, D, Status, Str>) => void): () => void;
+    destroy(): void;
+}
+/**
+ * Declare a core. The checks here are the ones a type cannot make: a tag that
+ * is not a `tl-` custom element name, a category or runtime outside the set the
+ * catalogue knows, a duplicated token, a status list that does not include what
+ * `status` can return. They run at import time, so a malformed core fails the
+ * build rather than a browser.
+ */
+export declare function defineElement<P extends object, S extends object, D extends object, A extends ActionMap, Status extends string, Str extends StringMap>(core: ElementCore<P, S, D, A, Status, Str>): ElementCore<P, S, D, A, Status, Str>;
+/**
+ * Instantiate a core. The instance owns the state and the timers; the harness
+ * owns the pixels. `subscribe` fires after every change with the whole view, so
+ * a harness only has to assign it to whatever makes its runtime re-render.
+ */
+export declare function createElement<P extends object, S extends object, D extends object, A extends ActionMap, Status extends string, Str extends StringMap>(core: ElementCore<P, S, D, A, Status, Str>, options?: CreateElementOptions<P, Str>): ElementInstance<P, S, D, A, Status, Str>;