@seatlayer/js 0.35.0 → 0.36.0

package/dist/index.d.ts

@@ -1,6 +1,190 @@
 import { PickerSeat, RendererViewMode, SeatHoverDetails, PickerTransport, ChartDoc, AvailabilityRule, ChartTheme, ExpandedSeat } from '@seatlayer/core';
 export { ExpandedSeat, SeatHoverDetails } from '@seatlayer/core';
 
+/**
+ * Buyer access context — the browser half of the Sales Channels contract
+ * (`docs/sales-channels-integration-guide-2026-08-01.md` §6, §9, §10).
+ *
+ * A promoter's own backend mints a short-lived, opaque buyer-access session
+ * (`bse_…`) that grants exactly one event's private channel scope. That bearer
+ * reaches the browser, and only the browser — this module is where it lives,
+ * and the rules it enforces are the ones the guide states outright:
+ *
+ *   - the token is held in memory on a private field. It is never written to
+ *     localStorage/sessionStorage/cookies, never appended to a URL, and never
+ *     placed in a log, an Error message, telemetry, or JSON. `toJSON()` and
+ *     `toString()` are overridden so an accidental `JSON.stringify(context)` or
+ *     template interpolation cannot leak it;
+ *   - refresh goes through the host's `buyerAccessTokenProvider`, which is
+ *     called with a `reason` so the host can distinguish a first acquisition
+ *     from an expiry from a 401;
+ *   - **a configured context never falls back to anonymous Public sale.** When
+ *     no bearer can be obtained the operation fails with a typed access error
+ *     instead of going out unauthenticated. Sending the request without the
+ *     bearer would silently widen the buyer's scope to Public — the exact
+ *     failure the feature exists to prevent (guide §7).
+ *
+ * Deliberately free of any `@seatlayer/core` import: it deals in tokens, HTTP
+ * status codes and callbacks only, so it vendors into the app's widget copy
+ * with no engine coupling.
+ */
+/** Why the SDK is asking the host for a token. Passed to the provider. */
+type BuyerAccessRefreshReason = 
+/** First acquisition, before the chart is fetched. */
+'initial'
+/** Proactive: the held token is inside the renewal skew. */
+ | 'expiring'
+/** Reactive: the held token's own expiry has passed. */
+ | 'expired'
+/** Reactive: the server answered 401 `buyer_access_expired`. */
+ | 'unauthorized'
+/** A realtime reconnect needs a live bearer to mint a subscribe ticket. */
+ | 'reconnect'
+/** The host called `refreshAccess()`. */
+ | 'manual';
+/** What a `buyerAccessTokenProvider` resolves to — the response body of the
+ *  host's own mint endpoint, unchanged. */
+interface BuyerAccessToken {
+    /** The opaque `bse_…` buyer-access session bearer. */
+    token: string;
+    /** Epoch ms. Optional — absent means "trust the server", and the SDK then
+     *  refreshes only reactively on a 401. */
+    expiresAt?: number;
+}
+type BuyerAccessTokenProvider = (context: {
+    reason: BuyerAccessRefreshReason;
+}) => BuyerAccessToken | Promise<BuyerAccessToken>;
+/**
+ * Why private inventory is not available. Never collapsed into a generic
+ * network failure (guide §10) and never carrying channel identity — the buyer
+ * is told the state, not which allocation they missed.
+ */
+type BuyerAccessUnavailableReason = 
+/** The session was revoked (HTTP 401 after refresh, or WS close 4401). */
+'revoked'
+/** The channel is paused — a legitimate, temporary organizer state. */
+ | 'paused'
+/** 401 `buyer_access_invalid`: do not retry this bearer. */
+ | 'invalid'
+/** 403 `buyer_access_origin_mismatch`. */
+ | 'origin_mismatch'
+/** 403 `buyer_access_event_mismatch`. */
+ | 'event_mismatch'
+/** 403 `buyer_access_mode_mismatch` (test bearer on a live event or v.v.). */
+ | 'mode_mismatch'
+/** 403 `channel_access_denied`. */
+ | 'channel_denied'
+/** 422 `invalid_channel_scope` — an integration configuration error. */
+ | 'invalid_scope'
+/** The host's token provider threw or returned nothing usable. */
+ | 'provider_failed'
+/** A one-shot `buyerAccessToken` lapsed and no provider was configured. */
+ | 'no_token';
+/** The access session expired. Carries whether the refresh recovered it. */
+interface BuyerAccessExpiredEvent {
+    reason: BuyerAccessRefreshReason;
+    /** The server's machine code when the expiry was observed over HTTP. */
+    code?: string;
+    /** True when the provider handed back a fresh token and work continues. */
+    refreshed: boolean;
+}
+/** Private inventory is unavailable, and refreshing will not fix it. */
+interface BuyerAccessUnavailableEvent {
+    reason: BuyerAccessUnavailableReason;
+    /** The server's machine code, when there was one. */
+    code?: string;
+    /** The HTTP status, when the state came from an HTTP response. */
+    status?: number;
+    /** True only for states a later retry could clear (`paused`). */
+    retryable: boolean;
+}
+/** One or more selected-but-unheld units stopped being selectable. */
+interface SelectedObjectUnavailableEvent {
+    /** Inventory labels (never channel identity). */
+    labels: string[];
+    reason: 
+    /** An allocation change moved it out of this buyer's scope (guide §9). */
+    'ineligible'
+    /** Someone else held or booked it. */
+     | 'taken'
+    /** 409 `allocation_exhausted` — this private allocation has none left. */
+     | 'exhausted';
+    code?: string;
+}
+interface BuyerAccessContextOptions {
+    provider?: BuyerAccessTokenProvider;
+    /** One-shot escape hatch for hosts that already own the token lifecycle. */
+    token?: string | BuyerAccessToken;
+    /** Renew this long before the stated expiry. Default 30s. */
+    skewMs?: number;
+    onExpired?: (event: BuyerAccessExpiredEvent) => void;
+    onUnavailable?: (event: BuyerAccessUnavailableEvent) => void;
+}
+/**
+ * Thrown instead of letting a scoped request go out unauthenticated. Carries no
+ * bearer and no channel identity, so it is safe to log or hand to an error
+ * reporter verbatim.
+ */
+declare class BuyerAccessUnavailableError extends Error {
+    readonly reason: BuyerAccessUnavailableReason;
+    readonly code?: string;
+    readonly status?: number;
+    constructor(event: BuyerAccessUnavailableEvent);
+}
+declare class BuyerAccessContext {
+    #private;
+    constructor(options: BuyerAccessContextOptions);
+    /**
+     * True when this picker is access-scoped at all. A false here is the
+     * tokenless public picker, which must behave exactly as it always has.
+     *
+     * Answered from what the HOST asked for, never from live token state. It used
+     * to be `!!#provider || !!#token`, which quietly inverted this file's central
+     * rule for a one-shot `buyerAccessToken` host: `#fail()` clears `#token`, so
+     * the first refusal turned a configured context into an "unconfigured" one,
+     * `authorization()` then returned null instead of throwing, and the very next
+     * call went out with no bearer — the anonymous Public sale fallback this
+     * module exists to prevent. A provider host never saw it, because `#provider`
+     * held `configured` true. Found against a live worker in the M9 pass.
+     */
+    get configured(): boolean;
+    /** Set once a state arrives that refreshing cannot clear. */
+    get unavailable(): BuyerAccessUnavailableEvent | null;
+    /** True while a usable bearer is held (ignores skew). */
+    get hasToken(): boolean;
+    /** Epoch ms the current token expires, or 0 when the host didn't say. */
+    get expiresAt(): number;
+    /**
+     * The `Authorization` header value for a scoped operation.
+     *
+     * Returns null only when this context is not configured at all (the ordinary
+     * anonymous public picker). A configured context either returns a bearer or
+     * throws `BuyerAccessUnavailableError` — it never returns null, because a
+     * null here would send the request as anonymous Public sale.
+     */
+    authorization(reason?: BuyerAccessRefreshReason): Promise<string | null>;
+    /**
+     * Handle a 401/403 from a scoped call. Returns true when the caller should
+     * retry the same request once with the refreshed bearer.
+     */
+    handleFailure(status: number, code: string | undefined): Promise<boolean>;
+    /** Host-driven re-acquisition (after the buyer signs in again, say). */
+    refresh(reason?: BuyerAccessRefreshReason): Promise<boolean>;
+    /** Drop the bearer. Called on destroy so nothing outlives the widget. */
+    clear(): void;
+    /** Redaction: the bearer must not survive a stringify or an interpolation. */
+    toJSON(): {
+        configured: boolean;
+        hasToken: boolean;
+    };
+    toString(): string;
+}
+/** Build a context from widget options, or null for the tokenless public path. */
+declare function createBuyerAccessContext(options: {
+    buyerAccessTokenProvider?: BuyerAccessTokenProvider;
+    buyerAccessToken?: string | BuyerAccessToken;
+}, hooks?: Pick<BuyerAccessContextOptions, 'onExpired' | 'onUnavailable'>): BuyerAccessContext | null;
+
 /**
  * Minimal client for the public embed surface of workers/api (the `/pub/*`
  * routes). Deliberately self-contained — it does NOT reuse src/lib/api.ts,
@@ -55,6 +239,19 @@ interface BestAvailableResult {
     items?: HoldResult['items'];
     zoneId?: string;
 }
+interface PubApiOptions {
+    /**
+     * Buyer access session. When present, EVERY scoped operation on this client
+     * carries `Authorization: Bearer bse_…` — chart, objects, hold, replace-hold,
+     * best-available, resume, release, extend, resnapshot and the realtime
+     * subscribe ticket. The binding is immutable for the client's lifetime: there
+     * is no method that turns it off, so no operation can silently downgrade to
+     * anonymous Public sale (guide §6, §7).
+     */
+    access?: BuyerAccessContext;
+    /** A 409 named specific inventory the buyer can no longer have. */
+    onObjectUnavailable?: (event: SelectedObjectUnavailableEvent) => void;
+}
 
 /**
  * SeatingChart — the embeddable buyer picker.
@@ -92,8 +289,32 @@ interface SeatingChartOptions {
     event: string;
     /** API origin. Defaults to https://api.seatlayer.io. */
     apiBase?: string;
-    /** Reserved for future authenticated rendering — accepted + stored, not yet sent. */
+    /** Reserved for future authenticated rendering — accepted + stored, not yet sent.
+     *  NOT the channel-access credential: a buyer access session is a different
+     *  thing with different authority, and uses the two options below. */
     publicKey?: string;
+    /**
+     * Buyer access session provider — the recommended way to render private
+     * channel inventory (Sales Channels guide §6).
+     *
+     * Called with a `reason` whenever the SDK needs a bearer: first acquisition,
+     * a near/actual expiry, a 401 `buyer_access_expired`, a realtime reconnect,
+     * or `refreshAccess()`. It should POST to YOUR backend, which mints the
+     * session with your secret key and returns `{ token, expiresAt }`.
+     *
+     * The token lives in memory for the widget's lifetime and nowhere else: never
+     * in storage, never in a URL, never in a log or an error message. Refresh
+     * returns the same or a narrower scope — the SDK never widens to Public sale
+     * on its own, and a failed refresh stops the scoped operation rather than
+     * retrying it anonymously.
+     */
+    buyerAccessTokenProvider?: BuyerAccessTokenProvider;
+    /**
+     * One-shot escape hatch for hosts that already own the session lifecycle.
+     * Cannot be renewed — when it lapses the widget reports `onAccessExpired`
+     * and then `onAccessUnavailable`. Prefer `buyerAccessTokenProvider`.
+     */
+    buyerAccessToken?: string | BuyerAccessToken;
     /** Max seats selectable at once (default 10). */
     maxSelection?: number;
     /**
@@ -138,6 +359,25 @@ interface SeatingChartOptions {
     onHoldRestored?: (result: HoldResult) => void;
     onHoldExpired?: () => void;
     onGAClick?: (area: GAAreaAvailability) => void;
+    /**
+     * The buyer access session lapsed. `refreshed` says whether the provider
+     * already recovered it — false means private inventory is now unavailable and
+     * `onAccessUnavailable` follows. Distinct from `onError` on purpose: this is
+     * never a network failure (guide §10).
+     */
+    onAccessExpired?: (event: BuyerAccessExpiredEvent) => void;
+    /**
+     * Private inventory is unavailable and refreshing will not fix it — revoked,
+     * paused, wrong origin/event/mode, or the provider failed. Carries a reason,
+     * never a channel name, id, colour or count.
+     */
+    onAccessUnavailable?: (event: BuyerAccessUnavailableEvent) => void;
+    /**
+     * Selected-but-unheld units stopped being selectable — someone else took
+     * them, or an allocation change moved them out of this buyer's scope. The
+     * widget has already dropped them from the selection.
+     */
+    onSelectedObjectUnavailable?: (event: SelectedObjectUnavailableEvent) => void;
     onError?: (err: unknown) => void;
     /**
      * Multi-floor charts only: fires when the buyer taps a deck in the stacked
@@ -164,6 +404,10 @@ declare class SeatingChart {
     private tipEl;
     private tipPos;
     private onTipMove;
+    /** Null for the ordinary public chart — the tokenless path is untouched. */
+    private readonly access;
+    private readonly api;
+    private realtime;
     constructor(options: SeatingChartOptions);
     /** Fetch the chart, mount the renderer, seed statuses and go live. Idempotent. */
     render(): Promise<this>;
@@ -286,9 +530,180 @@ declare class SeatingChart {
     /** Release selected labels from the current hold while keeping the remainder. */
     releaseLabels(labels: string[]): Promise<boolean>;
     /** Tear everything down: close the socket, stop timers, drop the canvas. */
+    /**
+     * Realtime for an access-scoped chart.
+     *
+     * A tokenless chart never gets here: `access` is null, `PubApi.socketUrl()`
+     * returns the URL it always has, and PickerController keeps its own socket
+     * and its own legacy frames. Nothing about the public path changes.
+     */
+    private startRealtime;
+    /**
+     * Re-acquire the buyer access session — call after your app has re-authorized
+     * the buyer (a revoked session cannot be recovered any other way). Resolves
+     * true when a fresh bearer is held; the realtime feed restarts with it.
+     */
+    refreshAccess(): Promise<boolean>;
     destroy(): void;
 }
 
+/**
+ * BuyerRealtimeClient — the client half of `docs/realtime-protocol-2026-08-01.md`.
+ *
+ * Why this exists as a separate socket rather than inside PickerController:
+ * a private scope authenticates with a one-use **subscribe ticket** carried in
+ * `Sec-WebSocket-Protocol`, and a browser can only set that at construction —
+ * `new WebSocket(url, protocols)`. The controller's socket is built from a URL
+ * alone (`PickerTransport.socketUrl`), and a bearer must never travel in a URL
+ * because URLs are routinely logged. So an access-scoped picker asks the
+ * transport for an empty `socketUrl()` (the controller then skips its own
+ * connection entirely) and this client owns the wire instead.
+ *
+ * A tokenless public picker never reaches this file. It keeps the controller's
+ * original socket, offers no subprotocol, and therefore receives byte-for-byte
+ * the frames it received before this module existed (protocol doc §1).
+ *
+ * What it implements:
+ *  - protocol negotiation: offer `seatlayer.v1`, believe the 101 echo, and fall
+ *    back to legacy frame handling when the server (or a proxy) does not echo;
+ *  - the ticket exchange, one mint per connection attempt, ticket in the
+ *    subprotocol list and never in the URL;
+ *  - compact `{default, exceptions}` snapshot reconstruction;
+ *  - `sv.<n>` resume, handling BOTH outcomes (a `resumed` delta or a full
+ *    snapshot) on every reconnect;
+ *  - close code 4401 as a typed access-revoked state, never a reconnect loop;
+ *  - liveness by ping/pong only. Silence is normal and carries no information
+ *    (protocol doc §5) — a quiet socket is never treated as a dead one.
+ */
+
+/** The projected status of one unit, as the server words it on the wire. */
+type WireStatus = string;
+/** A scope's projection: one default plus the units that differ from it. */
+interface Projection {
+    default: WireStatus;
+    exceptions: Record<string, WireStatus>;
+}
+interface StatusChange {
+    label: string;
+    status: WireStatus;
+}
+/** Where reconstructed inventory goes. Implemented over PickerController. */
+interface RealtimeSink {
+    /** Apply a batch of label→status changes. Implementations must paint this as
+     *  ONE pass, not one pass per label (motion system §4 rule 2). */
+    applyStatuses(changes: StatusChange[]): void;
+    /** Re-pull authoritative state over the scoped HTTP route. Used when a frame
+     *  cannot be diffed against what we hold (first snapshot, or the scope's
+     *  default itself changed, which redefines every unit we were never told
+     *  about). */
+    resync(): void | Promise<void>;
+    /** Section availability changed (channel-agnostic; identical for every scope). */
+    onSections?(hidden: string[], closed: string[]): void;
+    /** Scope-projected presence counters. */
+    onPresence?(counts: {
+        shoppingSessions: number;
+        activeHolds: number;
+    }): void;
+}
+interface SubscribeTicket {
+    ticket?: string;
+    /** Exactly what to hand `new WebSocket(url, protocols)`, per protocol doc §3. */
+    protocols?: string[];
+}
+interface BuyerRealtimeOptions {
+    /** The subscribe URL. Must never carry a credential — asserted below. */
+    url: string;
+    sink: RealtimeSink;
+    /** Mint a one-use ticket for THIS connection attempt. Returns null for the
+     *  anonymous public case (no ticket needed). Throwing stops the client. */
+    mintTicket?: () => Promise<SubscribeTicket | null>;
+    /** Typed access states. 4401 arrives here as `revoked`. */
+    onAccessUnavailable?: (event: BuyerAccessUnavailableEvent) => void;
+    /** Test seam. Defaults to the global WebSocket. */
+    socketFactory?: (url: string, protocols: string[]) => WebSocket;
+    /** Test seam for the keepalive/backoff timers. */
+    now?: () => number;
+}
+declare class BuyerRealtimeClient {
+    private readonly opts;
+    private ws;
+    private stopped;
+    private attempt;
+    private reconnectTimer;
+    private pingTimer;
+    private pongTimer;
+    private resumeTimer;
+    /** Our model of this scope's projection. Null until the first snapshot. */
+    private projection;
+    /** Last `snapshotVersion` seen on any frame that carried one — the resume point. */
+    private version;
+    /** True once the 101 echoed `seatlayer.v1`. */
+    private v1;
+    /** Set when we offered v1 and the handshake came back without it — a proxy
+     *  most likely stripped the header, so the next attempt selects the v1 frame
+     *  format with the `?pv=1` marker instead (protocol doc §1). The marker
+     *  selects a format and can never carry a credential or widen a scope. */
+    private useQueryMarker;
+    private hidden;
+    private closedSections;
+    constructor(options: BuyerRealtimeOptions);
+    /** Negotiated protocol, for tests and diagnostics. */
+    get protocol(): 'v1' | 'legacy' | null;
+    get snapshotVersion(): number | null;
+    start(): void;
+    /** Stop for good (destroy, or a revocation). Safe to call twice. */
+    stop(): void;
+    /** Restart after the host re-authorized a revoked buyer (`refreshAccess()`). */
+    restart(): void;
+    private connect;
+    private handleFrame;
+    /** The server answered our resume; cancel the fallback resync. */
+    private answered;
+    private reportIfAccessError;
+    /**
+     * Liveness is ping/pong, and only ping/pong. A socket that receives nothing
+     * for minutes is the normal, correct state for a narrowly-scoped buyer on a
+     * busy event (protocol doc §5), so quiet time never triggers a reconnect.
+     */
+    private startKeepalive;
+    private scheduleReconnect;
+    private clearPongTimer;
+    private clearTimers;
+}
+/**
+ * The slice of PickerController this module drives. Structural on purpose — it
+ * keeps this file free of an `@seatlayer/core` import, and every member here is
+ * public controller API, so nothing in the engine mirror has to change.
+ */
+interface PickerControllerLike {
+    idForLabel(label: string): string | undefined;
+    tableSelection(seatIdOrLabel: string): {
+        physicalSeatIds: string[];
+    } | null;
+    setStatus(ids: string[], status: 'free' | 'held' | 'booked' | 'not_for_sale'): void;
+    getStatus(id: string): string | undefined;
+    flashSeat(id: string, color?: string): void;
+    currentHold(): {
+        labels: string[];
+    } | null;
+    getSelection(): Array<{
+        id: string;
+        label: string;
+    }>;
+    deselect(ids: string[]): void;
+    refresh(): Promise<void>;
+}
+interface ControllerSinkOptions {
+    /** Pulse seats other buyers take, as the controller's own socket does. */
+    flashOnLiveChange?: boolean;
+    /** Selected-but-unheld units that stopped being selectable. */
+    onSelectedObjectUnavailable?: (labels: string[], reason: 'ineligible' | 'taken') => void;
+    /** Section availability changed and the chart itself needs rebuilding. */
+    onSections?: (hidden: string[], closed: string[]) => void;
+    onStatusChange?: () => void;
+}
+declare function createControllerSink(controller: PickerControllerLike, options?: ControllerSinkOptions): RealtimeSink;
+
 /**
  * A secure, framework-neutral host for the SeatLayer chart Designer.
  *
@@ -653,8 +1068,37 @@ interface SeatPickerOptions {
      * SeatLayer dashboard's own transport) or a fully local mock (demos).
      */
     transport?: PickerTransport;
-    /** Reserved for future authenticated rendering. */
+    /** Reserved for future authenticated rendering. NOT the channel-access
+     *  credential — a buyer access session is a different thing with different
+     *  authority, and uses the two options below. */
     publicKey?: string;
+    /**
+     * Buyer access session provider — the recommended way to show private channel
+     * inventory (Sales Channels guide §6).
+     *
+     * Called with a `reason` whenever the widget needs a bearer: first
+     * acquisition, a near/actual expiry, a 401 `buyer_access_expired`, a realtime
+     * reconnect, or `refreshAccess()`. It should POST to YOUR backend, which
+     * mints the session with your secret key and returns `{ token, expiresAt }`.
+     *
+     * The token lives in memory for the widget's lifetime and nowhere else: never
+     * in storage, never in a URL, never in a log or an error message. Refresh
+     * returns the same or a narrower scope; the widget never widens to Public
+     * sale on its own, and a failed refresh stops the scoped operation rather
+     * than retrying it anonymously. Any held seats stay held — a hold is
+     * relinquished by its own opaque capability, not by channel access, so
+     * losing access never strands inventory (guide §9).
+     *
+     * Ignored when a custom `transport` is supplied: that host owns its own
+     * credentials.
+     */
+    buyerAccessTokenProvider?: BuyerAccessTokenProvider;
+    /**
+     * One-shot escape hatch for hosts that already own the session lifecycle.
+     * Cannot be renewed — when it lapses the widget reports `onAccessExpired`
+     * and then `onAccessUnavailable`. Prefer `buyerAccessTokenProvider`.
+     */
+    buyerAccessToken?: string | BuyerAccessToken;
     /** Max seats selectable at once (default 10). */
     maxSelection?: number;
     /** BCP 47 language for the widget UI. Built-in: en, es, de, fr. */
@@ -767,11 +1211,37 @@ interface SeatPickerOptions {
     onHoldRestored?: (hold: HoldResult, seats: PickerSeat[], handoff: CheckoutHandoff) => void;
     /** Modal only: the buyer closed the picker (ESC / scrim / ✕). */
     onClose?: () => void;
+    /**
+     * The buyer access session lapsed. `refreshed` says whether the provider
+     * already recovered it — false means private inventory is now unavailable and
+     * `onAccessUnavailable` follows. Never collapsed into `onError`: an expiry is
+     * a recoverable, buyer-explainable state, not a network failure (guide §10).
+     */
+    onAccessExpired?: (event: BuyerAccessExpiredEvent) => void;
+    /**
+     * Private inventory is unavailable and refreshing will not fix it — revoked,
+     * paused, wrong origin/event/mode, or the provider failed. Carries a reason,
+     * never a channel name, id, colour or count. The widget shows its own
+     * explanatory panel; return nothing to keep it, or handle the state yourself.
+     */
+    onAccessUnavailable?: (event: BuyerAccessUnavailableEvent) => void;
+    /**
+     * Selected-but-unheld units stopped being selectable — someone else took
+     * them, or an allocation change moved them out of this buyer's scope. The
+     * widget has already dropped them from the tray.
+     */
+    onSelectedObjectUnavailable?: (event: SelectedObjectUnavailableEvent) => void;
     onError?: (err: unknown) => void;
 }
 declare class SeatPicker {
     private readonly opts;
     private readonly api;
+    /** Our own public client, or null when the host injected a transport. */
+    private readonly pubApi;
+    /** Null for the ordinary public picker — the tokenless path is untouched. */
+    private readonly access;
+    private realtime;
+    private accessEl;
     private readonly apiBase;
     private readonly controller;
     private readonly maxTickets;
@@ -1277,6 +1747,32 @@ declare class SeatPicker {
         zoneId?: string;
     }): Promise<HoldResult | null>;
     release(): Promise<void>;
+    /**
+     * Realtime for an access-scoped picker.
+     *
+     * A tokenless picker never gets here: `access` is null, `PubApi.socketUrl()`
+     * returns the URL it always has, and PickerController keeps its own socket
+     * and its own legacy frames. Nothing about the public path changes.
+     */
+    private startRealtime;
+    /**
+     * Re-acquire the buyer access session — call after your app has re-authorized
+     * the buyer. A revoked session cannot recover any other way. Resolves true
+     * when a fresh bearer is held; the map and the realtime feed resume with it.
+     */
+    refreshAccess(): Promise<boolean>;
+    /**
+     * The buyer-facing access state. Plain language, no internal vocabulary, and
+     * never a channel name, id or count — the buyer is told what happened and
+     * what to do, not which allocation they missed (guide §7, §10).
+     *
+     * Held seats are deliberately left alone: a hold is relinquished by its own
+     * opaque capability, not by channel access, so losing access never strands
+     * inventory and never silently drops a buyer's cart (guide §9).
+     */
+    private showAccessPanel;
+    private dismissAccessPanel;
+    private accessCopy;
     destroy(): void;
 }
 
@@ -1319,6 +1815,214 @@ interface AttachPickerFrameOptions {
  */
 declare function attachPickerFrame(iframe: HTMLIFrameElement, opts?: AttachPickerFrameOptions): () => void;
 
+/**
+ * Sales-channel planning — the pure, DOM-free half of Channels mode.
+ *
+ * Everything here is deterministic and testable without a canvas: the marker
+ * palette, the mixed-source selection summary, the LOCAL staged preview of an
+ * assignment, and the bucket rows the Review sheet renders.
+ *
+ * The local preview deliberately produces the SAME `AssignmentBuckets` shape the
+ * server returns from `POST /channels/assignments`. There is no dry-run endpoint,
+ * so the review sheet is drawn from this local computation and then REDRAWN from
+ * the authoritative server response after Apply. One renderer, two sources —
+ * which is why the shapes must match exactly.
+ *
+ * Spec: sales-channels-product-ux-spec §8.4–8.5.
+ */
+/** Public sale is a built-in pseudo-channel; the server uses '' as its id. */
+declare const PUBLIC_CHANNEL_ID = "";
+declare const PUBLIC_CHANNEL_NAME = "Public sale";
+type ChannelState = 'active' | 'paused' | 'archived';
+/** Physical inventory status, as the manage surface speaks it. */
+type ChannelSeatStatus = 'free' | 'held' | 'booked' | 'blocked';
+interface ChannelCounts {
+    allocated: number;
+    free: number;
+    held: number;
+    booked: number;
+    blocked: number;
+    units: number;
+}
+/** Buyer-access intents the server stores per channel. */
+type ChannelAccessIntent = 'none' | 'internal' | 'server' | 'hosted_link';
+/**
+ * Buyer-access summary on a channel row. Shipped by the access hardening branch
+ * (merged to app main). Still optional in this type: a worker that predates the
+ * merge simply omits it and the rail reads "—" rather than inventing a state.
+ */
+interface ChannelAccessSummary {
+    intent?: ChannelAccessIntent | string;
+    hasActiveGrants?: boolean;
+    lastMintAt?: number | null;
+    /** Free-text detail (partner host, who paused it) when the server offers one. */
+    detail?: string | null;
+}
+interface ChannelRecord {
+    id: string;
+    name: string;
+    color: string | null;
+    marker: string | null;
+    externalRef: string | null;
+    state: ChannelState;
+    archiveDestination: string | null;
+    createdAt: number;
+    updatedAt: number;
+    archivedAt: number | null;
+    counts: ChannelCounts;
+    access?: ChannelAccessSummary | null;
+}
+interface PublicSaleChannel {
+    id: typeof PUBLIC_CHANNEL_ID;
+    name: string;
+    state: 'active';
+    counts: ChannelCounts;
+    access?: ChannelAccessSummary | null;
+}
+interface ChannelListResult {
+    assignmentVersion: number;
+    publicSale: PublicSaleChannel;
+    channels: ChannelRecord[];
+}
+interface AssignmentBucketCount {
+    count: number;
+}
+interface AssignmentSkippedBucket extends AssignmentBucketCount {
+    labels: string[];
+    truncated: boolean;
+}
+interface AssignmentBuckets {
+    changedFromPublic: AssignmentBucketCount;
+    movedFromOtherChannel: AssignmentBucketCount & {
+        channels: Array<{
+            channelId: string;
+            name: string | null;
+            count: number;
+        }>;
+    };
+    alreadyInTarget: AssignmentBucketCount;
+    skippedHeld: AssignmentSkippedBucket;
+    skippedBooked: AssignmentSkippedBucket;
+    /** Requested labels that are not inventory in this event. */
+    notFound: AssignmentSkippedBucket;
+}
+interface AssignmentResult {
+    ok: true;
+    targetChannelId: string;
+    assignmentVersion: number;
+    requested: number;
+    applied: number;
+    buckets: AssignmentBuckets;
+}
+interface ArchiveBlockedDetails {
+    activeHolds?: number;
+    heldUnits?: number;
+    latestHoldExpiresAt?: number | null;
+    retryAfterMs?: number;
+}
+/**
+ * Suggest a marker for a new channel: the first letter of its name when that
+ * letter is still free, otherwise the next unused letter. Deterministic so the
+ * Create dialog's preview matches what actually gets stored.
+ */
+declare function suggestMarker(name: string, taken: Iterable<string>): {
+    letter: string;
+    color: string;
+};
+/** The letter + color a channel actually renders with (server value wins). */
+declare function markerOf(channel: {
+    id: string;
+    name: string;
+    marker?: string | null;
+    color?: string | null;
+}, index?: number): {
+    letter: string;
+    color: string;
+};
+/** One line of the rail's mixed-source selection summary (§8.4). */
+interface SelectionSourceRow {
+    channelId: string;
+    name: string;
+    count: number;
+}
+/**
+ * Group the current selection by the channel each unit is allocated to today.
+ * Public sale is listed first; the rest follow in list order so the rail's
+ * ordering never jitters as the selection changes.
+ */
+declare function selectionSources(labels: string[], allocation: Map<string, string>, list: ChannelListResult | null): SelectionSourceRow[];
+/**
+ * The LOCAL staged preview of "move these labels to this channel".
+ *
+ * Mirrors the DO's rules exactly (eventChannels.applyAssignment):
+ *   - a unit already in the target is `alreadyInTarget`, whatever its status;
+ *   - otherwise held and booked units are skipped and never rewritten;
+ *   - otherwise a public unit is `changedFromPublic`, a private one is
+ *     `movedFromOtherChannel` (itemised per source);
+ *   - a label that is not inventory in this event is `notFound`.
+ *
+ * Every requested label lands in exactly one bucket — the property the Review
+ * sheet's "every selected seat is in exactly one line" promise depends on.
+ */
+declare function planAssignment(input: {
+    labels: string[];
+    targetChannelId: string;
+    allocation: Map<string, string>;
+    statusOf: (label: string) => ChannelSeatStatus | undefined;
+    nameOf: (channelId: string) => string | null;
+}): AssignmentBuckets;
+/** Units this plan will actually mutate — what the Apply button counts. */
+declare function mutationCount(buckets: AssignmentBuckets): number;
+/** True when moving inventory out of another PRIVATE channel — §8.5 requires an
+ *  explicit confirmation line for exactly this case. */
+declare function needsMoveConfirmation(buckets: AssignmentBuckets): boolean;
+interface BucketRow {
+    kind: 'add' | 'move' | 'same' | 'skip';
+    icon: string;
+    count: number;
+    text: string;
+    why?: string;
+    /** Sampled seat labels for a skipped bucket, when the server sent any. */
+    peek?: string;
+}
+/**
+ * Render-ready rows for the Review sheet. The comp shows five lines; the server
+ * carries a sixth bucket (`notFound`) which is emitted only when it is non-zero,
+ * so a normal review still reads exactly like the approved design.
+ *
+ * Empty buckets are dropped — a zero line is noise, not honesty.
+ */
+declare function bucketRows(buckets: AssignmentBuckets, targetName: string): BucketRow[];
+/**
+ * "try again in ~N minutes" for the archive-blocked-by-holds 409 (§8.8).
+ * Rounds up so the organizer never comes back one tick early.
+ */
+declare function retryAfterCopy(details: ArchiveBlockedDetails | null | undefined): string;
+/** The access line under a channel row. Falls back to "—" before the hardening
+ *  branch lands the `access` field, never to a guess. */
+declare function accessLine(access: ChannelAccessSummary | null | undefined): string;
+/** Plain-language label for the access-intent control. */
+declare function accessIntentLabel(intent: ChannelAccessIntent): string;
+/**
+ * The chart-update refusal `channel_assignment_would_drop` (409) deliberately
+ * mirrors the Apply skipped buckets, so ONE review component renders both.
+ * This adapts it into the same `BucketRow[]` the Review sheet already draws.
+ */
+interface AssignmentDropDetails {
+    droppedUnits?: number;
+    channels?: Array<{
+        channelId: string;
+        name: string | null;
+        count: number;
+        labels?: string[];
+        truncated?: boolean;
+    }>;
+    acknowledgeWith?: string;
+}
+declare function dropReviewRows(details: AssignmentDropDetails | null | undefined): BucketRow[];
+/** Plain-language state badge text (§9: no internal vocabulary on user surfaces). */
+declare function stateBadge(state: ChannelState | 'builtin'): string;
+
 /**
  * Organizer manage-surface client for workers/api (the `/v1/events/:key/*`
  * inventory routes + the public realtime channel). Companion to api.ts (the
@@ -1340,6 +2044,59 @@ declare function attachPickerFrame(iframe: HTMLIFrameElement, opts?: AttachPicke
  * route is still session-only server-side).
  */
 
+/** One page of the organizer-only label → channel projection. */
+interface ChannelAllocationPage {
+    assignmentVersion: number;
+    allocations: Array<{
+        label: string;
+        channelId: string;
+    }>;
+    nextAfterLabel: string | null;
+}
+interface ChannelAuditEntry {
+    id: number;
+    at: number;
+    actor: string | null;
+    action: string;
+    channelId: string | null;
+    assignmentVersion: number;
+    before: unknown;
+    after: unknown;
+    reason: string | null;
+}
+interface ChannelAuditPage {
+    entries: ChannelAuditEntry[];
+    nextBefore: number | null;
+}
+/**
+ * Buyer projection for a preview audience — the same scoped server view the
+ * buyer SDK receives. When an audience cannot be previewed (a paused or
+ * archived channel), the server answers `{available:false, unavailable:[…]}`
+ * and the UI shows the real paused/unavailable landing state instead of
+ * rendering those seats as eligible.
+ *
+ * Fields stay optional: a worker that predates the hardening merge 404s here,
+ * and Channels mode says the preview needs a newer server rather than faking a
+ * projection client-side.
+ */
+interface ChannelPreviewProjection {
+    available?: boolean;
+    unavailable?: Array<{
+        channelId: string;
+        state: 'paused' | 'archived' | string;
+    }>;
+    channelIds?: string[];
+    includePublic?: boolean;
+    /** Labels this audience may buy. Everything else renders as ONE neutral
+     *  unavailable state so preview never leaks which channel holds a seat. */
+    eligible?: string[];
+    counts?: {
+        eligible?: number;
+        free?: number;
+        held?: number;
+        booked?: number;
+    };
+}
 declare class ManageApiError extends Error {
     status: number;
     code?: string;
@@ -1348,10 +2105,17 @@ declare class ManageApiError extends Error {
         label: string;
         reason?: string;
     }[];
+    /**
+     * Structured refusal detail. The channel routes use it for the two 409s a UI
+     * must render rather than merely report: `channel_archive_blocked_by_holds`
+     * carries {activeHolds, heldUnits, latestHoldExpiresAt, retryAfterMs}, and
+     * `channel_assignment_conflict` carries the current assignmentVersion.
+     */
+    details?: Record<string, unknown>;
     constructor(status: number, message: string, code?: string, conflicts?: {
         label: string;
         reason?: string;
-    }[]);
+    }[], details?: Record<string, unknown>);
 }
 interface ReportByStatus {
     free: number;
@@ -1536,6 +2300,76 @@ declare class ManageApi {
         hidden: string[];
         rules: Record<string, AvailabilityRule>;
     }>;
+    /** Allocation list with exact per-channel counts. `includeArchived` adds the
+     *  read-only archived rows behind the rail's "Show archived" control. */
+    channels(key: string, opts?: {
+        includeArchived?: boolean;
+    }): Promise<ChannelListResult>;
+    /** One page of the label → channel map that paints the allocation overlay.
+     *  Paged by label; follow `nextAfterLabel` until it is null. */
+    channelAllocation(key: string, opts?: {
+        afterLabel?: string;
+        limit?: number;
+    }): Promise<ChannelAllocationPage>;
+    channelAudit(key: string, opts?: {
+        limit?: number;
+        before?: number;
+    }): Promise<ChannelAuditPage>;
+    createChannel(key: string, input: {
+        name: string;
+        color?: string | null;
+        marker?: string | null;
+        externalRef?: string | null;
+    }): Promise<{
+        ok: true;
+        channel: ChannelRecord;
+    }>;
+    renameChannel(key: string, channelId: string, name: string): Promise<{
+        ok: true;
+        channel: ChannelRecord;
+    }>;
+    setChannelPaused(key: string, channelId: string, paused: boolean): Promise<{
+        ok: true;
+        channel: ChannelRecord;
+    }>;
+    /** Archive with a mandatory destination for the remaining allocation.
+     *  Throws ManageApiError 409 `channel_archive_blocked_by_holds` while any hold
+     *  is live; `err.details` carries the exact counts + retry window. */
+    archiveChannel(key: string, channelId: string, destination: string | null): Promise<{
+        ok: true;
+        channel: ChannelRecord;
+        assignmentVersion: number;
+        moved: number;
+    }>;
+    /**
+     * Versioned Apply. A stale `assignmentVersion` mutates NOTHING and throws
+     * ManageApiError 409 `channel_assignment_conflict` — the caller keeps its
+     * selection and offers "Refresh and review". There is no dry-run: the review
+     * sheet previews locally, this call returns the authoritative buckets.
+     */
+    applyChannelAssignment(key: string, input: {
+        targetChannelId: string | null;
+        labels: string[];
+        assignmentVersion: number;
+    }): Promise<AssignmentResult>;
+    /**
+     * Read-only buyer projection for an audience (§8.6) — the SAME scoped server
+     * view the buyer SDK receives, never a local approximation.
+     *
+     * Ships on the access-hardening branch. Older workers 404/405 here; callers
+     * MUST feature-detect and quietly say the preview needs a newer server rather
+     * than faking a projection client-side.
+     */
+    channelPreview(key: string, channelIds: string[], opts?: {
+        includePublic?: boolean;
+    }): Promise<ChannelPreviewProjection>;
+    /** Declare how buyers are meant to reach this channel. Drives the rail's
+     *  access line and turns "No buyer access configured" from information into a
+     *  warning when the organizer says the channel is for buyer self-service. */
+    setChannelAccessIntent(key: string, channelId: string, accessIntent: ChannelAccessIntent): Promise<{
+        ok: true;
+        channel: ChannelRecord;
+    }>;
     report(key: string): Promise<ReportResult>;
     controlRoom(key: string, windowMinutes?: number): Promise<ControlRoomSnapshot>;
     log(key: string, opts?: {
@@ -1569,7 +2403,14 @@ declare class ManageApi {
  * {@link ManageApi}. Box office + Sections + full Reports UI are M2/M3.
  */
 
-type SeatManagerMode = 'view' | 'inspect' | 'block' | 'sections';
+type SeatManagerMode = 'view' | 'inspect' | 'block' | 'sections' | 'channels';
+/**
+ * Capabilities the cockpit's token was minted with. Channels mode is gated on
+ * these and fails CLOSED: no `event:channels:view` ⇒ no Channels pill at all;
+ * view without `event:channels:manage` ⇒ read-only inspection with every
+ * mutation control absent, not merely disabled.
+ */
+type SeatManagerCapability = 'event:view' | 'event:block' | 'event:cancel' | 'event:reports' | 'event:channels:view' | 'event:channels:manage';
 /** DO seat status — 'blocked' has no engine analogue (→ 'not_for_sale'). */
 type DoStatus = 'free' | 'held' | 'booked' | 'blocked';
 /** Live KPI snapshot pushed to `onTallies` on every state change. */
@@ -1625,6 +2466,14 @@ interface SeatManagerOptions {
     tokenExpiresAt?: number;
     /** Initial mode. Default 'view'. */
     mode?: SeatManagerMode;
+    /**
+     * The capability set this token was minted with. Supply it whenever you mint
+     * an `mse_…` grant — it is the only way the widget can know a delegated token
+     * carries `event:channels:manage`, and without it Channels mode stays
+     * read-only (fail-closed). A tenant secret (`sk_…`) is org authority and is
+     * never narrowed server-side, so it is treated as fully capable.
+     */
+    capabilities?: SeatManagerCapability[] | string[];
     /** ISO-4217 fallback currency for revenue (chart/event currency wins). */
     currency?: string;
     /** Chart theme override for the chrome (rails/bar). Chart colors come from the doc. */
@@ -1719,6 +2568,8 @@ declare class SeatManager {
     private blockedSection;
     private blockedResultLimit;
     private unblockAllConfirmTimer;
+    private channels;
+    private channelCaps;
     private readonly onFullscreenChange;
     private readonly onKeyDown;
     private readonly onRailClick;
@@ -1726,6 +2577,21 @@ declare class SeatManager {
     /** Build the DOM, load the chart, subscribe to realtime, mount the board. */
     render(): Promise<this>;
     setMode(mode: SeatManagerMode): void;
+    /**
+     * Decide what this token may do with sales channels.
+     *
+     * Declared capabilities win — a host that mints an `mse_…` grant knows exactly
+     * what it asked for. Otherwise a tenant secret (`sk_…`) is org authority the
+     * worker never narrows, so it is fully capable; and a delegated token with no
+     * declaration is probed for read access and then treated as READ-ONLY, because
+     * "we could not tell" must never render mutation controls.
+     */
+    private resolveChannelCapabilities;
+    /** The adapter between the cockpit's internals and Channels mode. */
+    private buildChannelsHost;
+    /** Approximate on-screen seat size, for the channel overlay's marks. Derived
+     *  from the live camera so the overlay tracks zoom without a renderer hook. */
+    private seatPixelSize;
     /** Toggle the normalized sales-velocity outline overlay without changing seat colors. */
     setHeatOverlay(enabled: boolean): void;
     /** Toggle opt-in camera following for new buyer hold/book events. */
@@ -1769,6 +2635,16 @@ declare class SeatManager {
     zoomToFit(): void;
     destroy(): void;
     private buildRenderer;
+    /** Block and Channels are both bulk-selection tools: marquee, ⌘A, category,
+     *  section. The two differ only in WHICH statuses they may act on. */
+    private isBulkSelectMode;
+    /**
+     * Block never touches held or booked inventory, so it cannot select it.
+     * Channels must be able to select it — the Review sheet's honesty depends on
+     * counting the held and sold units inside a marquee and saying they will not
+     * move, rather than silently omitting them from the selection.
+     */
+    private selectableStatuses;
     private updateRendererInteraction;
     private handleSeatSelect;
     private repaintAll;
@@ -1870,4 +2746,294 @@ declare class SeatManager {
     private fail;
 }
 
-export { ApiError, type AttachPickerFrameOptions, type BestAvailableResult, type CheckoutHandoff, type CheckoutLineItem, type ControlRoomActivityEntry, type ControlRoomSectionMetric, type ControlRoomSnapshot, EmbeddedDesigner, type EmbeddedDesignerEventType, type EmbeddedDesignerMessage, type EmbeddedDesignerOptions, type GAAreaAvailability, type HoldConflict, type HoldLineItem, type HoldResult, type LogEntry, type LogPage, ManageApi, ManageApiError, type ReportByStatus, type ReportCategoryMeta, type ReportCategoryRow, type ReportResult, type ResumedHoldResult, SeatManager, type SeatManagerActionResult, type SeatManagerActivity, type SeatManagerMode, type SeatManagerOptions, type SeatManagerTallies, SeatPicker, type SeatPickerOptions, type SeatPickerTheme, SeatingChart, type SeatingChartOptions, type SelectedSeat, attachPickerFrame };
+/**
+ * Channels mode — the sales-channel management surface inside the SeatManager
+ * cockpit. It ships in the SDK, so every embedding platform (and our own Control
+ * Room) gets the same organizer experience.
+ *
+ * Design contract: `SeatmapUX/05 Event Manager.dc.html` (all 8 desktop states +
+ * the mobile artboard). Behaviour: sales-channels-product-ux-spec §8 (states),
+ * §9 (language), §13 (a11y + compact detents). Motion: motion-system §2 tokens,
+ * mirrored here as `--slm-mo-*` so an embed is self-contained, and §3 cockpit
+ * choreography.
+ *
+ * Boundaries this module keeps:
+ *
+ *   - **Capability gating is fail-closed.** Without `event:channels:view` the
+ *     cockpit never renders the pill (SeatManager's job). Without
+ *     `event:channels:manage` every mutation control is ABSENT — not disabled —
+ *     so a read-only operator is never shown authority they do not have.
+ *   - **Nothing here mutates physical inventory.** Assignment moves an
+ *     allocation; held and booked units are never rewritten.
+ *   - **Staging is local, truth is the server.** There is no dry-run endpoint,
+ *     so the Review sheet previews the buckets client-side and then re-renders
+ *     the AUTHORITATIVE bucket counts from the Apply response. A stale
+ *     `assignmentVersion` mutates nothing: the selection survives and the only
+ *     action offered is Refresh and review.
+ *   - **Forward-compatible reads.** The `access` field and the buyer-preview
+ *     projection land on the access-hardening branch. Both are feature-detected;
+ *     absent, the access line reads "—" and the Preview segment says it needs a
+ *     newer server. Neither ever blocks allocation work.
+ */
+
+/** The seat facts the overlay needs. Chart space, not screen space. */
+interface ChannelsSeatView {
+    id: string;
+    label: string;
+    x: number;
+    y: number;
+}
+/** The `ManageApi` subset Channels mode uses — structural so tests can pass a
+ *  hand-rolled double without constructing a real client. */
+interface ChannelsClient {
+    channels(key: string, opts?: {
+        includeArchived?: boolean;
+    }): Promise<ChannelListResult>;
+    channelAllocation(key: string, opts?: {
+        afterLabel?: string;
+        limit?: number;
+    }): Promise<ChannelAllocationPage>;
+    createChannel(key: string, input: {
+        name: string;
+        color?: string | null;
+        marker?: string | null;
+        externalRef?: string | null;
+    }): Promise<{
+        ok: true;
+        channel: ChannelRecord;
+    }>;
+    renameChannel(key: string, channelId: string, name: string): Promise<{
+        ok: true;
+        channel: ChannelRecord;
+    }>;
+    setChannelPaused(key: string, channelId: string, paused: boolean): Promise<{
+        ok: true;
+        channel: ChannelRecord;
+    }>;
+    archiveChannel(key: string, channelId: string, destination: string | null): Promise<{
+        ok: true;
+        channel: ChannelRecord;
+        assignmentVersion: number;
+        moved: number;
+    }>;
+    applyChannelAssignment(key: string, input: {
+        targetChannelId: string | null;
+        labels: string[];
+        assignmentVersion: number;
+    }): Promise<AssignmentResult>;
+    channelPreview(key: string, channelIds: string[], opts?: {
+        includePublic?: boolean;
+    }): Promise<ChannelPreviewProjection>;
+    setChannelAccessIntent(key: string, channelId: string, accessIntent: ChannelAccessIntent): Promise<{
+        ok: true;
+        channel: ChannelRecord;
+    }>;
+}
+interface ChannelsCapabilities {
+    view: boolean;
+    manage: boolean;
+}
+/** Everything Channels mode needs from the cockpit around it. */
+interface ChannelsModeHost {
+    eventKey: string;
+    api: ChannelsClient;
+    /** The rail scroll container the mode paints into. */
+    rail: HTMLElement;
+    /** An absolutely-positioned layer over the map (overlay canvas, flags, bars). */
+    mapLayer: HTMLElement;
+    /** The widget root — dialogs mount here so they inherit the widget's tokens. */
+    root: HTMLElement;
+    seats(): ChannelsSeatView[];
+    statusOf(label: string): ChannelSeatStatus | undefined;
+    selectionLabels(): string[];
+    selectByLabels(labels: string[]): void;
+    clearSelection(): void;
+    selectSection(sectionId: string): void;
+    sections(): Array<{
+        id: string;
+        label: string;
+    }>;
+    categories(): Array<{
+        key: string;
+        label: string;
+        color?: string;
+    }>;
+    labelsInCategory(key: string): string[];
+    sectionOfLabel(label: string): {
+        id: string;
+        label: string;
+    } | null;
+    /** Chart-space → container pixels. Null when there is no live renderer. */
+    worldToScreen(point: {
+        x: number;
+        y: number;
+    }): {
+        x: number;
+        y: number;
+    } | null;
+    /** Approximate on-screen seat size in CSS pixels, for the overlay marks. */
+    seatPixelSize(): number;
+    isCompact(): boolean;
+    /** Make the canvas non-interactive behind a full-detent sheet (§13). */
+    setMapInert(inert: boolean): void;
+    toast(message: string, kind: 'ok' | 'err'): void;
+    onError(err: unknown): void;
+    /** Fired whenever the staged mutation count changes, for host telemetry. */
+    onStagedChange?(staged: number): void;
+}
+/**
+ * Render bucket rows to markup. Deliberately generic over `BucketRow`, because
+ * three different refusals share this exact presentation: the local staged
+ * preview, the authoritative Apply response, and the chart-update
+ * `channel_assignment_would_drop` review (via `dropReviewRows`). One component,
+ * one visual language for "here is every affected unit, in exactly one line".
+ */
+declare function bucketRowsHtml(rows: BucketRow[]): string;
+declare class ChannelsMode {
+    private readonly host;
+    private caps;
+    private active;
+    private list;
+    private allocation;
+    private assignmentVersion;
+    private loadError;
+    private loading;
+    private view;
+    private showArchived;
+    private detailChannelId;
+    private targetChannelId;
+    private conflict;
+    private dialog;
+    private detent;
+    private seatListLimit;
+    private previewAudience;
+    private previewIncludePublic;
+    private previewProjection;
+    private previewSupported;
+    private pollTimer;
+    private layer;
+    private canvas;
+    /** undefined = not resolved yet, null = this environment has no 2d canvas. */
+    private ctx;
+    private bannerEl;
+    private stagedEl;
+    private liveEl;
+    private scrimEl;
+    private lastFocus;
+    private stagedDoneTimer;
+    private lastSelectionCount;
+    private lastCounts;
+    constructor(host: ChannelsModeHost, capabilities: ChannelsCapabilities);
+    /** Called when the cockpit switches into Channels mode. */
+    enter(): void;
+    /** Called when the cockpit leaves Channels mode. Everything this mode painted
+     *  over the map goes with it — no other tool ever inherits a channel overlay. */
+    leave(): void;
+    destroy(): void;
+    /** Capabilities can change when a token rotates. Re-render, fail-closed. */
+    setCapabilities(capabilities: ChannelsCapabilities): void;
+    isActive(): boolean;
+    /**
+     * Whether the map should accept bulk selection right now. Preview is a
+     * read-only simulation of somebody else's view, and a view-only token has no
+     * assignment to stage — in both cases the canvas must not offer selection at
+     * all rather than collect a selection nothing can act on.
+     */
+    canSelect(): boolean;
+    /**
+     * Organizer realtime integration point. M5 ships a per-scope socket for
+     * buyers; the organizer channel-count stream is a later milestone. When it
+     * arrives, call this from the cockpit's WS handler instead of waiting for the
+     * poll — everything downstream already reacts to a fresh list.
+     */
+    applyRealtimeHint(): void;
+    /** The cockpit's selection changed (marquee / click / section / category). */
+    handleSelectionChange(): void;
+    /** Camera moved or the container resized — the overlay is screen-space. */
+    handleViewChange(): void;
+    handleLayoutChange(): void;
+    private refresh;
+    /** Walk every allocation page. Bounded by the event's seat count, and the
+     *  server caps each page, so an arena is a handful of round trips. */
+    private loadAllocation;
+    private channelById;
+    private nameOf;
+    private markerFor;
+    /** Channels an organizer may assign INTO: public sale plus every live channel. */
+    private assignableChannels;
+    private currentPlan;
+    private ensureLayer;
+    private announce;
+    /**
+     * Repaint the allocation (or preview) overlay in ONE canvas pass.
+     *
+     * Channel identity on the map is a fill in the administrative color PLUS the
+     * letter flags below — never color alone. Physical status keeps its own cue:
+     * only FREE units take a channel fill, so sold/held/blocked seats still read
+     * exactly as they do in every other tool.
+     */
+    private paintOverlay;
+    /** Letter flags at each channel's centroid — the non-color identity cue. */
+    private paintFlags;
+    private setStaged;
+    private paintStagedBar;
+    private setBanner;
+    private setView;
+    /** Set by the cockpit so a view switch can re-arm canvas selection. */
+    onInteractionChange?: () => void;
+    private loadPreview;
+    paintRail(): void;
+    private viewSegmentHtml;
+    private countsHtml;
+    private channelRowHtml;
+    private listRailHtml;
+    private selectionRailHtml;
+    private detailRailHtml;
+    private previewRailHtml;
+    private paintSelection;
+    private wireRail;
+    private railAction;
+    private pickSection;
+    private pickCategory;
+    /** A tiny modal chooser reusing the dialog primitive (focus trap + Escape). */
+    private promptChoice;
+    private openDialog;
+    private renderDialog;
+    /**
+     * Mount a modal: `aria-modal` dialog, programmatic name, focus moved inside,
+     * Tab trapped, Escape closes WITHOUT mutating, focus restored on close (§13).
+     */
+    private renderScrim;
+    private closeDialog;
+    private renderCreateDialog;
+    private createChannel;
+    private showDialogError;
+    private renderReviewDialog;
+    /**
+     * Apply. On success the review sheet re-renders with the AUTHORITATIVE server
+     * buckets and the staged bar morphs to a ✓ for 1.2s. On a stale version the
+     * server mutated nothing: keep the selection, shake the bar once, and offer
+     * exactly one action — Refresh and review.
+     */
+    private apply;
+    private showApplied;
+    private shakeStaged;
+    private renderRenameDialog;
+    private setAccessIntent;
+    private togglePause;
+    private renderArchiveDialog;
+    private archive;
+    /**
+     * The synchronized inventory list (§13): the keyboard and screen-reader
+     * equivalent of canvas click / marquee / brush, grouped by section with
+     * per-section select actions.
+     */
+    private renderSeatListDialog;
+    private applySheetClasses;
+    private cycleDetent;
+    /** Back/Close from the full detent returns to the previous one and keeps the
+     *  selection — losing a hard-won selection to a Back press is unforgivable. */
+    handleBack(): boolean;
+}
+
+export { ApiError, type ArchiveBlockedDetails, type AssignmentBuckets, type AssignmentDropDetails, type AssignmentResult, type AttachPickerFrameOptions, type BestAvailableResult, type BucketRow, BuyerAccessContext, type BuyerAccessExpiredEvent, type BuyerAccessRefreshReason, type BuyerAccessToken, type BuyerAccessTokenProvider, BuyerAccessUnavailableError, type BuyerAccessUnavailableEvent, type BuyerAccessUnavailableReason, BuyerRealtimeClient, type BuyerRealtimeOptions, type ChannelAccessIntent, type ChannelAccessSummary, type ChannelAllocationPage, type ChannelAuditEntry, type ChannelAuditPage, type ChannelCounts, type ChannelListResult, type ChannelPreviewProjection, type ChannelRecord, type ChannelSeatStatus, type ChannelState, type ChannelsCapabilities, type ChannelsClient, ChannelsMode, type ChannelsModeHost, type ChannelsSeatView, type CheckoutHandoff, type CheckoutLineItem, type ControlRoomActivityEntry, type ControlRoomSectionMetric, type ControlRoomSnapshot, EmbeddedDesigner, type EmbeddedDesignerEventType, type EmbeddedDesignerMessage, type EmbeddedDesignerOptions, type GAAreaAvailability, type HoldConflict, type HoldLineItem, type HoldResult, type LogEntry, type LogPage, ManageApi, ManageApiError, PUBLIC_CHANNEL_ID, PUBLIC_CHANNEL_NAME, type Projection, type PubApiOptions, type RealtimeSink, type ReportByStatus, type ReportCategoryMeta, type ReportCategoryRow, type ReportResult, type ResumedHoldResult, SeatManager, type SeatManagerActionResult, type SeatManagerActivity, type SeatManagerCapability, type SeatManagerMode, type SeatManagerOptions, type SeatManagerTallies, SeatPicker, type SeatPickerOptions, type SeatPickerTheme, SeatingChart, type SeatingChartOptions, type SelectedObjectUnavailableEvent, type SelectedSeat, type SelectionSourceRow, type StatusChange, type SubscribeTicket, accessIntentLabel, accessLine, attachPickerFrame, bucketRows, bucketRowsHtml, createBuyerAccessContext, createControllerSink, dropReviewRows, markerOf, mutationCount, needsMoveConfirmation, planAssignment, retryAfterCopy, selectionSources, stateBadge, suggestMarker };