@sequencestudio/web-core 0.0.0-stage → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Axonista Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,184 @@
-# Temporary Holding Version
+# @sequencestudio/web-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The framework-independent core for sites that render Sequence layouts. React and Svelte
+renderers build on it; it has no UI framework of its own.
+
+It holds:
+
+- **The player's core**, in the separate `@sequencestudio/web-core/player` entry point:
+  control-slot placement, scrub bar annotations, test ids, telemetry types, the viewer's track and
+  volume preferences, and the video utilities (live edge and recovery, stalls, seeking,
+  Shaka error normalizing, text tracks, delivery type, playback authorization). It uses
+  Shaka's types only; `shaka-player` is an optional peer dependency. The main entry point
+  never imports it, apart from the player's test id defaults, which are the `player`
+  group of `DEFAULT_TEST_IDS`. `PLAYER_TOKENS` lists the player's tokens.
+
+- **The adapter.** `mapLayout`, `mapLayoutComponent` and `appendLayoutComponentItems` turn Client Delivery
+  responses, as parsed by `@sequencestudio/sdk`, into components and cards. Cards carry
+  a `target` describing where they lead; each site builds its own URLs from it.
+  Inline rich-text components keep their `content` payload and use the `rich-text`
+  renderer; they have no cards, pagination page or deferred source.
+  Each component retains its original typed response as `raw` for renderer overrides.
+  Unknown component-delivery variants are skipped without losing supported components.
+  `LayoutModel.facets` carries the layout's filter terms and counts when it was requested
+  with facets, passed through `mapLayout` untouched; it is absent when they were not
+  requested or could not be computed. `mapLayout(response, query)` keeps the query the
+  layout was requested with as `LayoutModel.query` (`componentItemsQuery`): its locale, filters,
+  aspects and total count, and `itemsPerComponent` as `limit`, which every page of its components
+  repeats. `mapCards(items, imagePurpose, aspect)` maps the card lists
+  of other responses, such as search results, a container's children, related content or
+  recommendations (`StandaloneCardItem`), into the same cards, and leaves out items it does
+  not recognize.
+- **Placed renderers.** `componentModel(options)` builds the component a renderer's
+  `SequenceShelf` or `SequenceGrid` draws from a site's own items
+  (`PlacedComponentOptions`): `kind` (`shelf` or `grid`), `id`, the raw `items`, `card`
+  (`stacked`, `inline` for grids, or a site card's name), `size`, `variant`,
+  `imagePurpose`, `columns`, `showTitles`, `title`, `subtitle`, `from`, `currentId` and
+  `progress`. It maps the items at the chosen image purpose only (default the size's
+  poster, `poster-16-9` for inline cards), leaves out unknown items and repeats, applies
+  `progress` (a share, or `{ completionRatio, resumeFromSeconds }` whose resume point goes
+  on an asset card's link target) and the `now-playing` badge, and returns a `LayoutComponentModel` with `placement: 'page'`
+  and `from`. Inline grids get `presentation.cardLayout: 'inline'` and one column at every
+  breakpoint unless `columns` sets more. `numberedTitle(card)` gives an inline card's
+  title, `3. The Rivalry` when it has an episode number.
+- **The presentation model.** `resolvePresentation` applies Sequence's defaults and the
+  card size table (`WEB_CARD_SIZES`): aspect ratio, cards per page or grid columns per
+  breakpoint, image purpose and title visibility. `BREAKPOINTS` are `sm` 640, `md` 768,
+  `lg` 1024, `xl` 1280 and `2xl` 1536; each size shows one more card at `2xl` than at
+  `xl`, the adaptive size aside, and `GAME_CARD_COLUMNS` shows 4. `ColumnsPerBreakpoint`'s
+  `2xl` key is optional: without it the `xl` count carries on (`columns2xl`).
+  `columnVariables(columns)` gives the `--sq-cols-*` custom properties a renderer sets.
+  Card variants retain the Sport Event treatment and fall back to standard for
+  unsupported values. Schedule-event cards preserve requested profile/taxonomy context.
+- **Custom renderers.** A component names a site-specific renderer in
+  `presentation.custom.renderer`; the rest of `presentation.custom` is passed through.
+  `resolveLayoutComponentRenderer` picks a component's renderer, and `resolveCardComponent` a shelf's or
+  grid's site card, from the site's choice and then `presentation.custom.card`.
+  `SiteCardProps` is what a site card receives (`card`, its `component`, `position`,
+  `loading`, `sizes`), and `SiteCardConfig` pairs a card renderer with its `columns`.
+  `SiteComponentPlacement` and `placeSiteComponents` place a site's own components among the shown components.
+- **Shelf layout.** `shelfMetrics`, `shelfOffset` and `pageAfterDrag` for card widths,
+  spacing and paging. Renderers own the DOM, events and motion.
+- **Design tokens.** `COLOR_ROLES` and generators for CSS custom properties, Tailwind v4
+  and Tailwind 3, plus `DESIGN_TOKENS` for type per text role (body, component title, card title,
+  button: family, size, line height, weight), shape (card radius and border) and spacing
+  (`component-side`, the space at a component's sides, and `card-gap`, between cards); body text has a
+  font family there, and `BODY_TYPE_TOKENS` names its size, line height and weight, which
+  have no defaults so text keeps the page's own. `CARD_HOVER_GROWTH_MAX` is the most a card
+  grows on hover per column in its component, which `card-hover-growth` scales from 0 to 1; and
+  `COMPONENT_TOKENS` for single parts such as `card-background` and `live-background`,
+  each with its default, a role or a value. `designTokensToCss` writes the tokens a site
+  sets. Every custom property starts with `--sq-` (`cssVar('surface-primary')`), so none
+  collides with a site's own. `STABLE_CLASS_NAMES` lists the class names both renderers put on
+  the main parts, for site CSS where no token fits. The core ships no brand colors. `themesFromConfig`
+  reads a site's themes from app config `settings.themes` over the site's own defaults and
+  accepts only plain color values. The API does not deliver `settings.themes` yet, so until
+  it does, sites get their defaults.
+- **Links and clicks.** `CardHrefContext` is the second argument a site's `cardHref`
+  receives: the `component` a card is in and, for a placed renderer, `from`, the container it
+  lists (`CardSourceContainer`); `cardHrefContext(component)` builds it. `CardClickEvent` carries
+  `component`, `card`, `position`, `source` (`shelf`, `grid`, `adaptive-shelf`,
+  `adaptive-header` or `card`) and `placement` (`layout` or `page`, from
+  `component.placement`). `componentCardClick`, `cardGridClick` and `cardClick` build them.
+- **Card targets.** A Continue Watching container card carries `target.play`, the asset
+  and video assignment the API picked to resume or start. A schedule event card targets
+  the occurrence (`type: 'schedule-event'`), which plays through the schedule event
+  playback endpoint; `assetId` names the asset behind it.
+- **Access.** Cards for gated assets, Continue Watching target assets, and schedule events carry the Client Delivery access
+  policy. `accessState(card.access, viewer)` gives `open`, `sign-in` or `locked` from the
+  viewer's sign-in and entitlements. It is fail-closed: an unsupported policy version or
+  a malformed policy is locked. Playback authorization stays with the server.
+- **Component context.** `componentItemsContext(component, { gameCardFields, componentContext })` gives the context
+  selectors a component requests with its items: the game card selectors (`gameCardContext`) for
+  a `sport-event` component when the site sets `gameCardFields`, then the site's `componentContext`
+  selectors, without repeats. `needsComponentItems` says whether a component is fetched in the browser:
+  deferred components, and components that request context, even when their items came embedded. The
+  renderers hand the selectors to the site's `loadComponentItems` as `ComponentItemsRequest.context`.
+- **Component loading.** The core never calls Sequence and holds no keys. A `ComponentItemsRequest`
+  carries the `layout` (id, slug and component query), the `component`, the `cursor`, the `context`
+  and a `signal`. `componentItemsPath(request)` gives the Client Delivery path for it, by layout
+  id, `componentItemsSdkRequest(request)` the request as the SDK's `getLayoutComponentItems` takes it,
+  and `componentItemsRequestQuery(request)` only its query, so a next page repeats its first
+  page's query. `createComponentItemsLoader({ basePath, headers, fetch })` is a `loadComponentItems`
+  for the site's settings: in the browser it fetches each page from the site's own
+  component-items route (default `/api/sequence`), and gives a viewer component an empty page without
+  a request.
+- **Component-items route.** `@sequencestudio/web-core/server` exports
+  `createComponentItemsRoute({ client, maxLimit, cacheControl, onError })`, the site's server
+  route for those pages: a function from a standard `Request` to a `Response`, mounted at
+  `.../layouts/[layoutRef]/components/[componentId]/items`. It forwards only component parameters within
+  `COMPONENT_ITEMS_ROUTE_LIMITS`, never the visitor's headers, passes Sequence's 4xx through
+  and answers 502 otherwise. It reads with the SDK's `getLayoutComponentItems(...).withResponse()` and
+  caches as Sequence says: a `public` page with Sequence's `Cache-Control`, or the site's
+  `cacheControl`, and anything else as `private, no-store`, so a preview or viewer client is
+  safe. The entry throws if a browser build imports
+  it. The layouts guide in `@sequencestudio/web-react` or `@sequencestudio/web-svelte` (`docs/react/react-2-layouts.md`, `docs/svelte/svelte-2-layouts.md`) mounts it.
+- **Placed loading.** `containerItems(ref, query)` and `catalogSearch(q, query)` build a placed
+  renderer's `source`. `createPlacedItemsLoader({ basePath, headers, fetch })` is a
+  `loadPlacedItems` for the site's settings: in the browser it fetches each page from the site's
+  own container and catalog routes (default `/api/sequence`), and gives a search under 3
+  characters an empty page without a request. `createPlacedItems({ source, getLoader, initial })` is
+  the framework-free state behind a placed renderer given a source: its first page, retry, next
+  pages and a failed next page that ends paging. It reads `getLoader()` for each request, so a
+  loader the site sets after mount is used. `@sequencestudio/web-core/server` exports
+  `createContainerItemsRoute` and `createCatalogSearchRoute`, mounted at `.../containers/[containerRef]`
+  and `.../catalog`, with the component-items route's options and rules: they forward only their own
+  parameters within `PLACED_ITEMS_ROUTE_LIMITS`, read with the SDK's `getContainer` and
+  `listCatalog` through `.withResponse()`, cache as Sequence says (a route's `cacheControl` gets
+  the page and Sequence's own header), and pass Sequence's 4xx through with its error `code`. The placed components guide in either renderer package
+  (`docs/react/react-3-placed-components.md`, `docs/svelte/svelte-3-placed-components.md`) mounts them.
+- **Viewer components.** `isViewerComponent` picks Continue Watching, which a site reads with the viewer's own token. `refreshViewerComponents()` loads every viewer
+  component on show again, for a site to call after recording progress; renderers listen with
+  `onRefreshViewerComponents`. `discoveryView(states, layoutState)` decides what a discovery area
+  draws: the empty, unavailable or failed-layout notice, and whether its components show, from
+  its components' load states and the site's `LayoutState` (`loading`, `failed`, `retry`).
+  `loadWithRetry` retries a failed load
+  once, unless it was rejected: `componentLoadError(status)` gives a `ComponentLoadRejectedError` for a
+  4xx other than 408 and 429, and `isRejectedComponentLoad` also reads an SDK error's
+  `statusCode`.
+- **Component headings.** `component.title` is the presentation title, else the curated source
+  title, trimmed. Untitled components keep no title; their optional subtitle or heading
+  link can still render. `component.presentation.showHeading` defaults
+  to true. When false, React and Svelte omit the title, subtitle, heading link and
+  their wrapper, including during loading and unavailable states. The model keeps
+  the copy for accessible region names; custom renderers must honor the flag too.
+  Card titles use the separate `component.presentation.showTitles` setting.
+- **Continue Watching containers.** A series or collection card with a play target reads
+  as the episode it resumes: the target asset's title, a subtitle of its season and
+  episode and the container's title (`S1:E02 · The Dawn`), and the target asset's image
+  before the container's. `seasonEpisodeLabel(season, episode)` formats the first part.
+- **Event durations.** A schedule-event card shows its asset's duration beside its
+  UPCOMING or LIVE badge, except for a movie.
+- **Products.** `ProductModel` and `productFromCard` give a product overlay a product to
+  show (title, image, price, stock, shop link) instead of asset metadata. Prices use each
+  currency's minor-unit exponent. Price formatting reuses up to 32 locale/currency
+  formatters, evicting the least recently used pair. Only a schedule event's explicit
+  status sets a live badge.
+- **Badges.** `BadgeKind` is `live`, `upcoming`, `duration`, `collection`, `label` or
+  `now-playing`; `DEFAULT_BADGE_PRESETS` places `now-playing` top left in the `strong`
+  style.
+- **Test ids.** `DEFAULT_TEST_IDS` holds the `data-testid` every renderer emits by default.
+  `resolveTestIds(siteTestIds)` merges a site's own over them key by key within each
+  group, where `null` removes an id, a group or, as `testIds: null`, every id.
+  `componentTestId`, `cardTestId` and `badgeTestId` resolve the ids that are functions.
+
+Images: pass `card.image` to the SDK's `selectImageUrl` or `imageSrcSet`, with
+`imageSizesFor(component.presentation.columns)` as the `sizes` attribute, which includes the
+`2xl` step. `card.image` is the component's image purpose only (as sent, even one this version
+does not know), or without one the size's default, `poster-2-3` for 2:3 sizes and
+`poster-16-9` for the rest; a card without it has no `card.image`. Continue Watching cards
+try `poster-16-9`, `backdrop-16-9`, then `thumbnail`. `mapLayout` leaves out an adaptive
+component with no purpose. `mapCard(item, purpose, { exactImage: true })` maps the same way.
+
+Components filled on the server: `fillComponents(layout, { load, fill, gameCardFields,
+componentContext })` reads the first page of each component that needs items, through a loader with
+`loadComponentItems`'s signature and the request the browser would make (`load: (request) =>
+sequence.getLayoutComponentItems(componentItemsSdkRequest(request))`), and sets it with
+`fillComponent`. A component whose read fails is passed on unfilled and listed in `failures`; viewer
+components are never filled, and `fillComponent` returns one unchanged. `fillComponent(component, page)` sets a component's first page
+of items and marks it `filled`, so it renders in the first HTML and `needsComponentItems` is
+false for it; SequenceLayout still refreshes it (after `refreshDelayMs`,
+`refreshAfterSeconds` plus up to 15%) and pages it. A component's remembered first page is keyed
+by its layout, component query, component, context and, for a viewer component, the viewer.
+
+The SDK is a peer dependency used for types; sites also use it to fetch data.

package/dist/access.d.ts

@@ -0,0 +1,29 @@
+import type { ClientDeliveryAssetAccessPolicy } from '@sequencestudio/sdk';
+/** What a card shows for access: playable, sign in first, or locked. */
+export type AccessState = 'open' | 'sign-in' | 'locked';
+export interface ViewerAccess {
+    signedIn: boolean;
+    /**
+     * A stable id for the signed-in viewer, such as the session's user id. With it, viewer
+     * components such as Continue Watching are remembered between visits for this viewer only;
+     * without it, they are not remembered.
+     */
+    id?: string;
+    /** The viewer's entitlement keys, from /me/entitlements. Undefined when they could not be resolved. */
+    entitlements?: readonly string[];
+}
+/** Whether this core can read a policy: the supported version, well formed. */
+export declare function isReadablePolicy(policy: ClientDeliveryAssetAccessPolicy): boolean;
+/**
+ * Whether a policy is in a language version this core does not know. The renderers count such a
+ * policy as needing sign-in, the mildest gate
+ * to advertise, and locks it.
+ */
+export declare function isUnknownPolicyVersion(policy: ClientDeliveryAssetAccessPolicy | null | undefined): boolean;
+/**
+ * The access state to show on a card, from its policy and the viewer. Fail-closed, as the
+ * Client Delivery contract requires: a malformed policy is locked, and so is an unsupported
+ * version, except that a signed-out viewer is asked to sign in first. The
+ * state is for display; playback authorization stays with the server.
+ */
+export declare function accessState(policy: ClientDeliveryAssetAccessPolicy | undefined, viewer: ViewerAccess): AccessState;

package/dist/access.js

@@ -0,0 +1,46 @@
+/** The policy language version this core understands. */
+const SUPPORTED_POLICY_VERSION = 1;
+function isPolicy(policy) {
+    return (typeof policy === 'object' &&
+        policy !== null &&
+        typeof policy.authenticationRequired === 'boolean' &&
+        Array.isArray(policy.requiredEntitlements) &&
+        policy.requiredEntitlements.every((key) => typeof key === 'string') &&
+        (policy.match === 'any' || policy.match === 'all'));
+}
+/** Whether this core can read a policy: the supported version, well formed. */
+export function isReadablePolicy(policy) {
+    return policy?.version === SUPPORTED_POLICY_VERSION && isPolicy(policy);
+}
+/**
+ * Whether a policy is in a language version this core does not know. The renderers count such a
+ * policy as needing sign-in, the mildest gate
+ * to advertise, and locks it.
+ */
+export function isUnknownPolicyVersion(policy) {
+    return typeof policy === 'object' && policy !== null && policy.version !== SUPPORTED_POLICY_VERSION;
+}
+/**
+ * The access state to show on a card, from its policy and the viewer. Fail-closed, as the
+ * Client Delivery contract requires: a malformed policy is locked, and so is an unsupported
+ * version, except that a signed-out viewer is asked to sign in first. The
+ * state is for display; playback authorization stays with the server.
+ */
+export function accessState(policy, viewer) {
+    if (policy === undefined)
+        return 'open';
+    if (isUnknownPolicyVersion(policy))
+        return viewer.signedIn ? 'locked' : 'sign-in';
+    if (!isReadablePolicy(policy))
+        return 'locked';
+    const required = policy.requiredEntitlements;
+    if (!viewer.signedIn && (policy.authenticationRequired || required.length > 0))
+        return 'sign-in';
+    if (required.length === 0)
+        return 'open';
+    if (viewer.entitlements === undefined)
+        return policy.failurePosture === 'open' ? 'open' : 'locked';
+    const held = new Set(viewer.entitlements);
+    const granted = policy.match === 'all' ? required.every((key) => held.has(key)) : required.some((key) => held.has(key));
+    return granted ? 'open' : 'locked';
+}

package/dist/badges.d.ts

@@ -0,0 +1,78 @@
+import { type ViewerAccess } from './access.js';
+import type { AccessBadgeKind, AccessBadgeModel, BadgeKind, BadgeModel, CardModel } from './cards.js';
+export type BadgeCorner = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+/** A badge's copy: fixed text, or a function of what it counts, such as a collection's videos. */
+export type BadgeLabel = string | ((count: number) => string);
+/** How a site shows one kind of badge: its copy, corner and style. */
+export interface BadgePreset {
+    /**
+     * Copy in place of the core's, such as 'Upcoming' for 'UPCOMING'. A function words a
+     * counting badge, such as `(n) => n + " clips"` for a collection's video count.
+     */
+    label?: BadgeLabel;
+    corner?: BadgeCorner;
+    /** Emitted as `data-style`. The renderers style `neutral`, `strong` and `live`; a site styles its own. */
+    style?: string;
+    /** Adds the pulsing live indicator. */
+    pulse?: boolean;
+    /** Leaves this kind off cards. */
+    hidden?: boolean;
+}
+/** A site's badge vocabulary, by kind. Kinds it leaves out keep the defaults. */
+export type BadgePresets = Partial<Record<BadgeKind, BadgePreset>>;
+type ResolvedPreset = Required<Omit<BadgePreset, 'label'>> & {
+    label?: BadgeLabel;
+};
+export declare const DEFAULT_BADGE_PRESETS: Record<BadgeKind, ResolvedPreset>;
+export interface ShownBadge {
+    badge: BadgeModel | AccessBadgeModel;
+    label: string;
+    style: string;
+    pulse: boolean;
+}
+export interface BadgeGroup {
+    corner: BadgeCorner;
+    badges: ShownBadge[];
+}
+/**
+ * How a site words its access badges. `sign-in` is for a signed-out viewer on a card that
+ * needs only sign-in; `entitlement` for a card that needs an entitlement the viewer does
+ * not hold. `entitlements` words one entitlement key in place of `entitlement`, and shows
+ * it even while `entitlement` stays hidden.
+ */
+export interface AccessBadges {
+    'sign-in'?: AccessBadgePreset;
+    entitlement?: AccessBadgePreset;
+    entitlements?: Record<string, AccessBadgePreset>;
+}
+/** An access badge's preset. Its copy is fixed text, as it counts nothing. */
+export type AccessBadgePreset = Omit<BadgePreset, 'label'> & {
+    label?: string;
+};
+type ResolvedAccessPreset = Required<AccessBadgePreset>;
+/** Sign-in shows by default; the entitlement badge is off until a site words it. */
+export declare const DEFAULT_ACCESS_BADGES: Record<AccessBadgeKind, ResolvedAccessPreset>;
+export interface ShownAccessBadge extends ShownBadge {
+    badge: AccessBadgeModel;
+    corner: BadgeCorner;
+}
+/**
+ * The access badge a card shows this viewer, if any. With no policy, none. A policy this
+ * core cannot read as version 1 counts as needing sign-in, the mildest gate to advertise,
+ * so a signed-out viewer sees the sign-in badge. A policy naming any entitlement never
+ * shows the sign-in badge, since signing in alone would not clear it; it shows the
+ * entitlement badge when the viewer lacks access. Otherwise a signed-out viewer sees the
+ * sign-in badge exactly when `authenticationRequired` is true, even if the rest of the
+ * policy is malformed. Without the viewer's state there is none: the badge is a hint, and
+ * playback authorization stays with the server. An entitlement badge names one the viewer
+ * is missing, never one they hold, as an `all` policy can leave them holding some.
+ */
+export declare function accessBadge(card: CardModel, viewer: ViewerAccess | undefined, settings?: AccessBadges): ShownAccessBadge | undefined;
+/**
+ * A card's badges, grouped by corner in a fixed order, after the site's presets. Within a
+ * corner, in this order: the event badge (LIVE or UPCOMING) first, then the card's
+ * other badges, then the access badge from accessBadge. Bottom corners stay empty while
+ * the card shows a progress bar, which runs along the bottom.
+ */
+export declare function badgeGroups(card: CardModel, presets?: BadgePresets, access?: ShownAccessBadge): BadgeGroup[];
+export {};

package/dist/badges.js

@@ -0,0 +1,89 @@
+import { accessState, isReadablePolicy, isUnknownPolicyVersion } from './access.js';
+export const DEFAULT_BADGE_PRESETS = {
+    new: { corner: 'top-left', style: 'strong', pulse: false, hidden: false },
+    'new-season': { corner: 'top-left', style: 'strong', pulse: false, hidden: false },
+    'new-episode': { corner: 'top-left', style: 'strong', pulse: false, hidden: false },
+    'new-video': { corner: 'top-left', style: 'strong', pulse: false, hidden: false },
+    live: { corner: 'top-left', style: 'live', pulse: true, hidden: false },
+    upcoming: { corner: 'top-left', style: 'strong', pulse: false, hidden: false },
+    duration: { corner: 'bottom-right', style: 'neutral', pulse: false, hidden: false },
+    collection: { corner: 'bottom-right', style: 'neutral', pulse: false, hidden: false },
+    episodes: { corner: 'bottom-right', style: 'neutral', pulse: false, hidden: false },
+    label: { corner: 'top-left', style: 'neutral', pulse: false, hidden: false },
+    'now-playing': { corner: 'top-left', style: 'strong', pulse: false, hidden: false },
+};
+const CORNERS = ['top-left', 'top-right', 'bottom-left', 'bottom-right'];
+/** Sign-in shows by default; the entitlement badge is off until a site words it. */
+export const DEFAULT_ACCESS_BADGES = {
+    'sign-in': { label: 'Sign in to watch', corner: 'top-left', style: 'neutral', pulse: false, hidden: false },
+    entitlement: { label: 'Locked', corner: 'top-left', style: 'neutral', pulse: false, hidden: true },
+};
+/**
+ * The access badge a card shows this viewer, if any. With no policy, none. A policy this
+ * core cannot read as version 1 counts as needing sign-in, the mildest gate to advertise,
+ * so a signed-out viewer sees the sign-in badge. A policy naming any entitlement never
+ * shows the sign-in badge, since signing in alone would not clear it; it shows the
+ * entitlement badge when the viewer lacks access. Otherwise a signed-out viewer sees the
+ * sign-in badge exactly when `authenticationRequired` is true, even if the rest of the
+ * policy is malformed. Without the viewer's state there is none: the badge is a hint, and
+ * playback authorization stays with the server. An entitlement badge names one the viewer
+ * is missing, never one they hold, as an `all` policy can leave them holding some.
+ */
+export function accessBadge(card, viewer, settings = {}) {
+    const policy = card.access;
+    if (!viewer || !policy)
+        return undefined;
+    const signIn = () => viewer.signedIn
+        ? undefined
+        : shownAccess({ kind: 'sign-in', label: '' }, { ...DEFAULT_ACCESS_BADGES['sign-in'], ...settings['sign-in'] });
+    if (typeof policy !== 'object' || isUnknownPolicyVersion(policy))
+        return signIn();
+    if (!namesEntitlements(policy))
+        return policy.authenticationRequired === true ? signIn() : undefined;
+    if (!isReadablePolicy(policy) || accessState(policy, viewer) === 'open')
+        return undefined;
+    const held = new Set(viewer.entitlements);
+    const missing = policy.requiredEntitlements.filter((key) => !held.has(key));
+    const entitlement = missing.find((key) => settings.entitlements?.[key]);
+    const preset = { ...DEFAULT_ACCESS_BADGES.entitlement, ...settings.entitlement };
+    const named = entitlement ? { ...preset, hidden: false, ...settings.entitlements[entitlement] } : preset;
+    return shownAccess({ kind: 'entitlement', label: '', ...(entitlement ? { entitlement } : {}) }, named);
+}
+/** Whether a policy names any entitlement, read as loosely as the wire may send it. */
+function namesEntitlements(policy) {
+    const required = policy.requiredEntitlements;
+    return (Array.isArray(required) || typeof required === 'string') && required.length > 0;
+}
+function shownAccess(badge, preset) {
+    if (preset.hidden)
+        return undefined;
+    return { badge: { ...badge, label: preset.label }, label: preset.label, style: preset.style, pulse: preset.pulse, corner: preset.corner };
+}
+/**
+ * A card's badges, grouped by corner in a fixed order, after the site's presets. Within a
+ * corner, in this order: the event badge (LIVE or UPCOMING) first, then the card's
+ * other badges, then the access badge from accessBadge. Bottom corners stay empty while
+ * the card shows a progress bar, which runs along the bottom.
+ */
+export function badgeGroups(card, presets = {}, access) {
+    const groups = new Map();
+    const show = (corner, badge) => {
+        if (card.progress !== undefined && corner.startsWith('bottom'))
+            return;
+        groups.set(corner, [...(groups.get(corner) ?? []), badge]);
+    };
+    for (const badge of card.badges) {
+        const preset = { ...DEFAULT_BADGE_PRESETS[badge.kind], ...presets[badge.kind] };
+        if (preset.hidden)
+            continue;
+        show(preset.corner, { badge, label: badgeLabel(badge, preset.label), style: preset.style, pulse: preset.pulse });
+    }
+    if (access)
+        show(access.corner, { badge: access.badge, label: access.label, style: access.style, pulse: access.pulse });
+    return CORNERS.filter((corner) => groups.has(corner)).map((corner) => ({ corner, badges: groups.get(corner) }));
+}
+function badgeLabel(badge, label) {
+    if (typeof label === 'function')
+        return badge.count === undefined ? badge.label : label(badge.count);
+    return label ?? badge.label;
+}

package/dist/card-model.d.ts

@@ -0,0 +1,70 @@
+import type { RecencyKind } from './recency.js';
+export type CardKind = 'asset' | 'container' | 'product' | 'profile' | 'external-link' | 'custom' | 'schedule-event' | 'category' | 'unknown';
+/**
+ * What a Continue Watching container card plays: the asset the API picked for the
+ * viewer's journey through the container, with the video assignment to play it with.
+ */
+export interface PlayTarget {
+    assetId: string;
+    slug?: string;
+    videoAssignmentId: string;
+    seasonNumber?: number;
+    episodeNumber?: number;
+    /** Why the API picked this asset: not-started, resume or advance. */
+    reason: string;
+    /** Where to resume, when the viewer has progress on this asset. */
+    resumeFromSeconds?: number;
+}
+/** Where a card leads. Sites turn this into their own URL; the core never builds one. */
+export type CardTarget = {
+    type: 'category';
+    id: string;
+    slug: string;
+    taxonomySlug: string;
+} | {
+    type: 'asset' | 'product' | 'profile';
+    id: string;
+    slug?: string;
+    subtype?: string;
+    /** For assets placed with a specific video, the assignment to play. */
+    videoAssignmentId?: string;
+    /** On Continue Watching asset cards: where to resume, as the API selected it. */
+    resumeFromSeconds?: number;
+} | {
+    type: 'container';
+    id: string;
+    slug?: string;
+    subtype?: string;
+    /** On Continue Watching cards: the asset to play, rather than the container's page. */
+    play?: PlayTarget;
+} | {
+    /** A schedule occurrence. Play it through the schedule event playback endpoint, not the asset's. */
+    type: 'schedule-event';
+    id: string;
+    /** The asset behind the event, for display and detail pages. */
+    assetId: string;
+    /** The asset's subtype, such as `stream`. */
+    assetSubtype?: string;
+} | {
+    type: 'external';
+    url: string;
+};
+/**
+ * `now-playing` marks the item a placed renderer's `currentId` names, such as a player page's
+ * video. `collection` counts a collection's videos and `episodes` a season's.
+ */
+export type BadgeKind = RecencyKind | 'live' | 'upcoming' | 'duration' | 'collection' | 'episodes' | 'label' | 'now-playing';
+export interface BadgeModel {
+    kind: BadgeKind;
+    label: string;
+    /** What a counting badge counts, such as a collection's videos or a season's episodes. A site's label function words it. */
+    count?: number;
+}
+/** A badge from the viewer's access to a card: sign in to watch, or an entitlement they lack. */
+export type AccessBadgeKind = 'sign-in' | 'entitlement';
+export interface AccessBadgeModel {
+    kind: AccessBadgeKind;
+    label: string;
+    /** For an entitlement badge, the key whose wording it took, when the site named one. */
+    entitlement?: string;
+}

package/dist/card-model.js

@@ -0,0 +1 @@
+export {};