origam 2.2.1 → 2.5.0

package/dist/src/interfaces/InlineEdit/inline-edit.interface.d.ts

@@ -0,0 +1,241 @@
+import type { ICommonsComponentProps, ITagProps } from '../../interfaces';
+import type { TInlineEditInputType } from '../../types';
+/**
+ * Signature of a validator passed to `<OrigamInlineEdit>` (and to the
+ * `useInlineEdit` composable). Returns `true` when the draft value is
+ * acceptable, or an error message (`string`) that the component will
+ * surface via `role="alert"`.
+ *
+ * Async validators are supported — return a `Promise` and the component
+ * will keep the editor open (and expose `isPending = true`) until it
+ * resolves.
+ */
+export type TInlineEditValidator = (value: string) => true | string | Promise<true | string>;
+/**
+ * Props for `<OrigamInlineEdit>` — edit-in-place pattern.
+ *
+ * The component is intentionally headless on the display side: by
+ * default it renders a button-styled span with the current value (or
+ * the placeholder when the value is empty); consumers can fully
+ * override the affordance via the scoped `#display` slot. In edit
+ * mode it renders a native `<input>` (or `<textarea>` when `multiline`
+ * is true) — wrapping a heavier component (TextField, …) is not
+ * needed and would defeat the keyboard-driven UX.
+ */
+export interface IInlineEditProps extends ICommonsComponentProps, ITagProps {
+    /**
+     * Current value (v-model target). Accepts both `string` and
+     * `number` for ergonomics — the internal draft is normalised to a
+     * string, then `update:modelValue` re-emits with the same shape as
+     * the original (number stays number, string stays string).
+     */
+    modelValue: string | number;
+    /**
+     * Placeholder shown on the input AND surfaced inside the default
+     * `#display` slot when `modelValue` is empty. Consumers wrap with
+     * `t()` if they need i18n.
+     */
+    placeholder?: string;
+    /**
+     * Validation callback. Returns `true` (or `Promise<true>`) when
+     * the draft is acceptable, or an error message string that will
+     * be surfaced in a `role="alert"` element near the input.
+     *
+     * Sync validators run on every Enter / blur. Async validators
+     * keep the editor open until the returned Promise settles.
+     */
+    validate?: TInlineEditValidator;
+    /**
+     * Auto-focus the input when entering edit mode. Setting this to
+     * false is useful for forms where keyboard focus is managed by a
+     * parent (e.g. a wizard that steps focus through siblings).
+     *
+     * @default true
+     */
+    autoFocus?: boolean;
+    /**
+     * Select all the input's text when it gains focus on edit entry.
+     * Common for "click title to rename" patterns — the user can
+     * immediately type a replacement without selecting first.
+     *
+     * @default true
+     */
+    selectOnFocus?: boolean;
+    /**
+     * Confirm the draft when the input loses focus. When false, the
+     * editor stays open on blur and the user must explicitly Enter
+     * to confirm or Escape to cancel.
+     *
+     * @default true
+     */
+    confirmOnBlur?: boolean;
+    /**
+     * Confirm on `Enter`. Disable when the edit zone is a multiline
+     * textarea and Enter should produce a newline (Cmd/Ctrl+Enter to
+     * confirm is the convention — apps wire this manually).
+     *
+     * @default true
+     */
+    confirmOnEnter?: boolean;
+    /**
+     * Cancel (revert the draft) on `Escape`.
+     *
+     * @default true
+     */
+    cancelOnEscape?: boolean;
+    /**
+     * Disables the component — the display affordance becomes
+     * non-interactive (button `disabled`, span `aria-disabled`), the
+     * `edit()` method short-circuits, and any in-flight edit is
+     * cancelled (draft discarded).
+     *
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Render a `<textarea>` instead of a `<input>` in edit mode.
+     * When true, `confirmOnEnter` should generally be disabled by the
+     * consumer so newlines are not swallowed.
+     *
+     * @default false
+     */
+    multiline?: boolean;
+    /**
+     * Strip surrounding whitespace before emitting `update:modelValue`
+     * AND before running the validator. Disable for fields where
+     * trailing spaces are significant (passwords, …).
+     *
+     * @default true
+     */
+    trim?: boolean;
+    /**
+     * Native HTML input type when not in multiline mode.
+     *
+     * @default 'text'
+     */
+    inputType?: TInlineEditInputType;
+    /**
+     * Surface a loading affordance (CSS class hook) on the root while
+     * an async `validate` Promise is in flight. The component sets
+     * `aria-busy="true"` regardless — this prop only controls the
+     * visual hook.
+     *
+     * @default false
+     */
+    loadingOnConfirm?: boolean;
+    /**
+     * Render built-in action buttons (Edit / Confirm / Cancel) next to
+     * the component.
+     *
+     * When `false` (default), only keyboard shortcuts are available:
+     * Enter to confirm, Escape to cancel, click on the display to edit.
+     *
+     * When `true`, three icon buttons are rendered:
+     * - **Edit** — visible in display mode, enters edit mode on click.
+     * - **Confirm** — visible in edit mode, commits the draft on click.
+     * - **Cancel** — visible in edit mode, discards the draft on click.
+     *
+     * The `disabled` prop also disables all three buttons.
+     *
+     * @default false
+     */
+    showActions?: boolean;
+}
+/**
+ * Emits for `<OrigamInlineEdit>`.
+ */
+export interface IInlineEditEmits {
+    /** Final value after successful validation. Same shape as input. */
+    (e: 'update:modelValue', value: string | number): void;
+    /** Editor entered edit mode (display → input transition). */
+    (e: 'edit'): void;
+    /** Editor exited via cancel — the draft was discarded. */
+    (e: 'cancel'): void;
+    /**
+     * Confirmation attempt — fires AFTER validation passes, BEFORE
+     * `update:modelValue`. Consumers can intercept the value for
+     * server-side persistence; the v-model is updated regardless.
+     */
+    (e: 'confirm', value: string | number): void;
+    /** Validator returned an error message (sync or async). */
+    (e: 'validate-error', message: string): void;
+}
+/**
+ * Bindings exposed by the scoped `#display` slot. Consumers use these
+ * to drive any custom affordance (heading, badge, …) into edit mode.
+ */
+export interface IInlineEditDisplaySlotBindings {
+    /** Current value (already coerced to string). */
+    value: string;
+    /** Switches the component into edit mode. */
+    edit: () => void;
+    /** True when the value is empty / nullish — drives placeholder styling. */
+    isEmpty: boolean;
+    /** Resolved placeholder string (with sane fallback). */
+    placeholder: string;
+    /** Mirrors the `disabled` prop, for visual handling. */
+    disabled: boolean;
+}
+/**
+ * Bindings exposed by the scoped `#edit` slot. Consumers use these to
+ * render a fully custom input layout while keeping the same state
+ * machine.
+ */
+export interface IInlineEditEditSlotBindings {
+    /** Draft value (two-way; mutate to feed the validator). */
+    value: string;
+    /** Update the draft from the slot. */
+    setValue: (next: string) => void;
+    /** Run the validator and, if it passes, commit the draft. */
+    confirm: () => void;
+    /** Discard the draft and return to display mode. */
+    cancel: () => void;
+    /** Current validation error (null when no error). */
+    error: string | null;
+    /** True while an async validator is in flight. */
+    isPending: boolean;
+}
+/**
+ * Bindings exposed by the scoped `#actions` slot — typically used to
+ * render visible confirm / cancel buttons (X / ✓).
+ */
+export interface IInlineEditActionsSlotBindings {
+    /** Run the validator and commit if it passes. */
+    confirm: () => void;
+    /** Discard the draft and return to display mode. */
+    cancel: () => void;
+    /** True while an async validator is in flight. */
+    isPending: boolean;
+}
+/**
+ * Slot signatures for `<OrigamInlineEdit>`.
+ */
+export interface IInlineEditSlots {
+    display?: (bindings: IInlineEditDisplaySlotBindings) => any;
+    edit?: (bindings: IInlineEditEditSlotBindings) => any;
+    actions?: (bindings: IInlineEditActionsSlotBindings) => any;
+}
+/**
+ * Options for the `useInlineEdit` composable.
+ */
+export interface IUseInlineEditOptions {
+    /** Sync or async validator — see `TInlineEditValidator`. */
+    validate?: TInlineEditValidator;
+    /**
+     * Strip surrounding whitespace before running the validator and
+     * emitting the new value.
+     *
+     * @default true
+     */
+    trim?: boolean;
+    /**
+     * Called when the draft is committed. Use this when the composable
+     * is consumed outside the SFC's emit pipeline (e.g. inside a
+     * unit-test harness or a wrapper composable).
+     */
+    onConfirm?: (value: string) => void;
+    /** Called when the draft is discarded. */
+    onCancel?: () => void;
+    /** Called when a validator returns an error message. */
+    onError?: (message: string) => void;
+}

package/dist/src/interfaces/ItemGroup/item-group.interface.d.ts

@@ -1,4 +1,4 @@
-import type { ICommonsComponentProps, IGroupItemProps, IGroupProps, ITagProps } from '../../interfaces';
+import type { ICommonsComponentEmits, ICommonsComponentProps, IGroupItemProps, IGroupProps, ITagProps } from '../../interfaces';
 /**
  * Props for `<OrigamItemGroup>` — the renderless selection container.
  * Mirrors `IBtnToggleProps` minus the visual mixins (this group has
@@ -24,3 +24,6 @@ export interface IItemGroupProps extends ICommonsComponentProps, ITagProps, IGro
 export interface IItemGroupItemProps extends ICommonsComponentProps, ITagProps, IGroupItemProps {
     tag?: string;
 }
+/** Emits fired by `<OrigamItemGroup>` — v-model on the active item set. */
+export interface IItemGroupEmits extends ICommonsComponentEmits {
+}

package/dist/src/interfaces/List/list-group.interface.d.ts

@@ -9,3 +9,8 @@ export interface IListGroupProps extends ITagProps, ICommonsComponentProps, ICol
 }
 export interface IListActivatorProps extends ICommonsComponentProps, ITagProps {
 }
+/** Emits fired by `<OrigamListGroup>` — click on the activator chrome
+ *  (used by parents to toggle the open state). */
+export interface IListGroupEmits {
+    (e: 'click:activator', event: MouseEvent): void;
+}

package/dist/src/interfaces/List/list-item.interface.d.ts

@@ -1,4 +1,4 @@
-import type { IActiveProps, IAdjacentProps, IBgColorProps, IBorderProps, IColorProps, ICommonsComponentProps, IDensityProps, IDimensionProps, IElevationProps, IHoverProps, ILinkProps, IMarginProps, IPaddingProps, IRippleProps, IRoundedProps, ITagProps } from '../../interfaces';
+import type { IActiveProps, IAdjacentEmits, IAdjacentProps, IBgColorProps, IBorderProps, IClickEmits, IColorProps, ICommonsComponentProps, IDensityProps, IDimensionProps, IElevationProps, IHoverProps, ILinkProps, IMarginProps, IPaddingProps, IRippleProps, IRoundedProps, ITagProps } from '../../interfaces';
 import type { TLines } from '../../types';
 export interface IListItemProps extends IBorderProps, ICommonsComponentProps, IDensityProps, IDimensionProps, IElevationProps, IRoundedProps, ITagProps, ILinkProps, IColorProps, IBgColorProps, IRippleProps, IPaddingProps, IMarginProps, IAdjacentProps, IActiveProps, IHoverProps {
     active?: boolean;
@@ -12,3 +12,6 @@ export interface IListItemProps extends IBorderProps, ICommonsComponentProps, ID
     title?: string | number;
     value?: any;
 }
+/** Emits fired by `<OrigamListItem>` — generic click + prepend/append slot clicks. */
+export interface IListItemEmits extends IClickEmits, IAdjacentEmits {
+}

package/dist/src/interfaces/List/list.interface.d.ts

@@ -20,3 +20,19 @@ export interface IItemProps {
     returnObject?: boolean;
     valueComparator?: typeof deepEqual;
 }
+/** Emits fired by `<OrigamList>` — selection / open state propagation and
+ *  user-driven click events on items. */
+export interface IListEmits {
+    (e: 'update:selected', value: Array<unknown>): void;
+    (e: 'update:opened', value: Array<unknown>): void;
+    (e: 'click:open', value: {
+        id: unknown;
+        value: boolean;
+        path: Array<unknown>;
+    }): void;
+    (e: 'click:select', value: {
+        id: unknown;
+        value: boolean;
+        path: Array<unknown>;
+    }): void;
+}

package/dist/src/interfaces/Main/main.interface.d.ts

@@ -1,4 +1,4 @@
-import type { IBorderProps, ICommonsComponentProps, IDimensionProps, IMarginProps, IPaddingProps, IRoundedProps, ITagProps } from '../../interfaces';
-export interface IMainProps extends ITagProps, ICommonsComponentProps, IPaddingProps, IMarginProps, IBorderProps, IRoundedProps, IDimensionProps {
+import type { IBgColorProps, IBorderProps, IColorProps, ICommonsComponentProps, IDimensionProps, IElevationProps, IMarginProps, IPaddingProps, IRoundedProps, ITagProps } from '../../interfaces';
+export interface IMainProps extends ITagProps, ICommonsComponentProps, IPaddingProps, IMarginProps, IBorderProps, IRoundedProps, IDimensionProps, IElevationProps, IBgColorProps, IColorProps {
     scrollable?: boolean;
 }

package/dist/src/interfaces/Mask/mask-options.interface.cjs

@@ -0,0 +1 @@
+"use strict";

package/dist/src/interfaces/Mask/mask-options.interface.d.ts

@@ -0,0 +1,48 @@
+import type { TPatternValidator } from '../../types';
+/**
+ * Configuration object accepted by `useMask` / the
+ * `OrigamTextField.mask` prop in its long form.
+ *
+ * - `pattern`   — token-walker template. `#` = digit,
+ *                 `A` = letter, `*` = any char, anything
+ *                 else is a literal preserved verbatim.
+ * - `validator` — optional secondary check on the UNMASKED
+ *                 value (e.g. Luhn for credit cards).
+ * - `required`  — when `true`, `isValid` is `false` until
+ *                 every consumer token is filled.
+ */
+export interface IMaskOptions {
+    pattern: string;
+    validator?: TPatternValidator | null;
+    required?: boolean;
+}
+/**
+ * Resolved config returned by `resolveMaskConfig` after
+ * normalising a string / preset key / IMaskOptions input.
+ * `pattern` is always a raw template string at this layer.
+ */
+export interface IResolvedMaskConfig {
+    pattern: string;
+    validator: TPatternValidator | null;
+    required: boolean;
+}
+/**
+ * Output shape of `applyMask`. `masked` is the formatted
+ * display string (literals interleaved); `unmasked` is the
+ * raw user-provided characters (consumer slots only).
+ */
+export interface IMaskApplyResult {
+    masked: string;
+    unmasked: string;
+    complete: boolean;
+}
+/**
+ * Token emitted by the pattern parser. `consumer` flags
+ * whether the token consumes one character from the input
+ * (`#`, `A`, `*`) or is a literal kept verbatim.
+ */
+export interface IMaskToken {
+    kind: 'digit' | 'letter' | 'any' | 'literal';
+    char: string;
+    consumer: boolean;
+}

package/dist/src/interfaces/Masonry/masonry.interface.cjs

@@ -0,0 +1 @@
+"use strict";

package/dist/src/interfaces/Masonry/masonry.interface.d.ts

@@ -0,0 +1,80 @@
+import type { IBgColorProps, IBorderProps, IColorProps, ICommonsComponentProps, IDimensionProps, IElevationProps, IMarginProps, IPaddingProps, IRoundedProps, ITagProps } from '../../interfaces';
+import type { TGridGapSize, TMasonryAlign } from '../../types';
+/**
+ * Map of `min-width` (px) → number of columns to apply when the
+ * container is at least that wide. Container-query based (NOT viewport),
+ * so a masonry placed in a 600 px sidebar will pick the breakpoint that
+ * matches 600 px, regardless of viewport width.
+ *
+ * Example:
+ *   { 600: 2, 900: 3, 1200: 4 }
+ *
+ * → < 600 px : `columns` prop value (default 3).
+ * → ≥ 600 px : 2.
+ * → ≥ 900 px : 3.
+ * → ≥ 1200 px: 4.
+ *
+ * Keys must be positive integers (pixel widths). Values must be positive
+ * integers (column counts). Order is irrelevant — the composable sorts
+ * the entries by key ascending and picks the largest key ≤ container
+ * width.
+ */
+export type TMasonryColumnBreakpoints = Record<number, number>;
+/**
+ * Props for `<OrigamMasonry>` — Pinterest-style masonry layout.
+ *
+ * `<OrigamMasonry>` ships a CSS-first implementation gated on
+ * `grid-template-rows: masonry` (detected via `useCssSupport`). When
+ * the browser supports it the layout is pure CSS; when it doesn't, a
+ * `useMasonry` JS fallback runs (`ResizeObserver` + bucket-fill
+ * algorithm). The runtime decision is transparent to the consumer.
+ */
+export interface IMasonryProps extends ICommonsComponentProps, ITagProps, IDimensionProps, IMarginProps, IPaddingProps, IRoundedProps, IElevationProps, IBgColorProps, IColorProps, IBorderProps {
+    /**
+     * Number of columns to use when no breakpoint matches the container
+     * width. Must be a positive integer ≥ 1.
+     *
+     * @default 3
+     */
+    columns?: number;
+    /**
+     * Container-query column breakpoints. See `TMasonryColumnBreakpoints`.
+     * When provided, the masonry observes its own size via
+     * `ResizeObserver` and picks the matching column count automatically.
+     *
+     * Pass `undefined` (or an empty object) to disable container-query
+     * resolution and use the `columns` prop verbatim.
+     */
+    columnBreakpoints?: TMasonryColumnBreakpoints;
+    /**
+     * Gap between items, both vertically and horizontally. Accepts:
+     *
+     * - one of the grid size tokens `'xs' | 'sm' | 'md' | 'lg' | 'xl'`
+     *   (resolved via `tokens/component/grid.json`, same matrix as
+     *   `<OrigamGrid>` for visual consistency).
+     * - any CSS length string (`'24px'`, `'1rem'`).
+     * - a plain `number` interpreted as pixels.
+     *
+     * @default 'md'
+     */
+    gap?: TGridGapSize | string | number;
+    /**
+     * Animate `transform` when an item moves to a different position on
+     * column-count change. CSS-only — the transition is applied to the
+     * item children, so the consumer's content doesn't need to know.
+     *
+     * @default true
+     */
+    animated?: boolean;
+    /**
+     * Vertical alignment of items inside a column. `'top'` is the
+     * standard Pinterest layout; `'center'` centres each column's
+     * cumulative content inside the container height.
+     *
+     * Only the JS fallback honours `'center'` — the CSS-native path
+     * always packs to the top. See `TMasonryAlign`.
+     *
+     * @default 'top'
+     */
+    align?: TMasonryAlign;
+}

package/dist/src/interfaces/Media/index.cjs

@@ -0,0 +1,49 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+var _mediaController = require("./media-controller.interface.cjs");
+Object.keys(_mediaController).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _mediaController[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _mediaController[key];
+    }
+  });
+});
+var _mediaPlayer = require("./media-player.interface.cjs");
+Object.keys(_mediaPlayer).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _mediaPlayer[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _mediaPlayer[key];
+    }
+  });
+});
+var _mediaScrubber = require("./media-scrubber.interface.cjs");
+Object.keys(_mediaScrubber).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _mediaScrubber[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _mediaScrubber[key];
+    }
+  });
+});
+var _mediaVolumeControl = require("./media-volume-control.interface.cjs");
+Object.keys(_mediaVolumeControl).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _mediaVolumeControl[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _mediaVolumeControl[key];
+    }
+  });
+});

package/dist/src/interfaces/Media/index.d.ts

@@ -0,0 +1,4 @@
+export * from './media-controller.interface';
+export * from './media-player.interface';
+export * from './media-scrubber.interface';
+export * from './media-volume-control.interface';

package/dist/src/interfaces/Media/index.js

@@ -0,0 +1,4 @@
+export * from "./media-controller.interface.js";
+export * from "./media-player.interface.js";
+export * from "./media-scrubber.interface.js";
+export * from "./media-volume-control.interface.js";

package/dist/src/interfaces/Media/media-controller.interface.cjs

@@ -0,0 +1 @@
+"use strict";

package/dist/src/interfaces/Media/media-controller.interface.d.ts

@@ -0,0 +1,159 @@
+import type { ICommonsComponentProps, IMediaPlayerMethods, IMediaPlayerState } from '../../interfaces';
+import type { TAudioLoopMode, TQualityOption } from '../../types';
+/**
+ * Props for `<OrigamMediaController>` — the universal media-controls
+ * shell consumed by `<OrigamVideo>` and `<OrigamAudio>`. Both parents
+ * own the `<video>` / `<audio>` element AND the playlist (when one);
+ * the Controller is purely presentational and emits intents the
+ * parent acts on.
+ *
+ * The audio-specific contracts (playlist navigation, tri-state loop,
+ * shuffle) ship as opt-in props so video consumers see zero
+ * regression — pass `:show-loop="false"` etc to keep the legacy
+ * video toolbar unchanged.
+ *
+ * Defaults are inlined inside `withDefaults` (cf. CLAUDE.md
+ * `withDefaults` rule) — this interface only types the public API.
+ */
+export interface IMediaControllerProps extends ICommonsComponentProps {
+    /** Reactive media state from `useMediaPlayer()` (or any
+     *  specialisation: `useVideoPlayer`, `useAudioPlayer`). Required. */
+    state: IMediaPlayerState;
+    /** Imperative methods from `useMediaPlayer()`. Required. */
+    methods: IMediaPlayerMethods;
+    /** YouTube-style overlay mode: the shell sits on top of the media
+     *  surface with a dark gradient and auto-hides on `visible=false`.
+     *  When `false`, the shell renders as a regular always-on toolbar.
+     *
+     *  @default false */
+    inset?: boolean;
+    /** Visibility flag driven by the parent's autohide logic.
+     *
+     *  @default true */
+    visible?: boolean;
+    /** Available playback rates exposed via the config menu.
+     *
+     *  @default [0.5, 0.75, 1, 1.25, 1.5, 2] */
+    playbackRates?: ReadonlyArray<number>;
+    /** Enable the cast / AirPlay button (Remote Playback API).
+     *
+     *  @default false */
+    allowRemotePlayback?: boolean;
+    /** Adds a "Download" row to the config menu.
+     *
+     *  @default false */
+    downloadable?: boolean;
+    /** URL surfaced to the consumer when "Download" is clicked.
+     *
+     *  @default null */
+    downloadUrl?: string | null;
+    /** Suggested filename written to the `<a download="…">` attribute.
+     *
+     *  @default undefined */
+    downloadFilename?: string;
+    /** Optional list of quality variants. When the array exposes ≥ 2
+     *  entries, a "Quality" drill-down appears in the config menu.
+     *
+     *  @default [] */
+    qualityOptions?: ReadonlyArray<TQualityOption>;
+    /** Currently-active quality identifier.
+     *
+     *  @default null */
+    currentQuality?: string | null;
+    /** Show the "previous" transport button. The parent listens to
+     *  the `previous` emit and decides whether to skip back 10s
+     *  (single-track) or jump to the previous playlist track.
+     *
+     *  @default false */
+    showPrevious?: boolean;
+    /** Show the "next" transport button. Parent owns the action.
+     *
+     *  @default false */
+    showNext?: boolean;
+    /** Show the tri-state loop button (none → all → one → none).
+     *
+     *  @default false */
+    showLoop?: boolean;
+    /** Show the shuffle toggle button.
+     *
+     *  @default false */
+    showShuffle?: boolean;
+    /** Current loop mode. Supports `v-model:loopMode`. The Controller
+     *  cycles this on click; the parent observes and applies its
+     *  playlist / `<audio loop>` policy.
+     *
+     *  @default 'none' */
+    loopMode?: TAudioLoopMode;
+    /** Current shuffle state. Supports `v-model:shuffle`. The
+     *  Controller toggles on click; the parent reads and switches its
+     *  next-track resolution accordingly.
+     *
+     *  @default false */
+    shuffle?: boolean;
+}
+/**
+ * Emits surfaced by `<OrigamMediaController>`. The shell calls
+ * `methods.*` directly for the basic ops (toggle play, seek, set
+ * volume, set rate, toggle mute, request cast) — those don't bubble.
+ *
+ * The emits below are the ones the PARENT must handle because the
+ * Controller doesn't own enough context:
+ *   - `quality-change` — parent owns the `<source>` swap logic.
+ *   - `download`       — parent owns the URL fetch / anchor click.
+ *   - `previous` / `next` — parent owns the playlist or skip-time
+ *                            policy.
+ *   - `update:loopMode` / `update:shuffle` — two-way binding for the
+ *                                            transport toggles.
+ */
+export interface IMediaControllerEmits {
+    (e: 'quality-change', quality: string): void;
+    (e: 'download'): void;
+    (e: 'previous'): void;
+    (e: 'next'): void;
+    (e: 'update:loopMode', mode: TAudioLoopMode): void;
+    (e: 'update:shuffle', shuffle: boolean): void;
+}
+/**
+ * Scoped slots exposed by `<OrigamMediaController>`. Consumers
+ * inject media-specific blocks (`<OrigamAudio>` injects header +
+ * waveform + footer; `<OrigamVideo>` injects captions/PiP/fullscreen
+ * through `extraControlsRight`).
+ */
+export interface IMediaControllerSlots {
+    /** Block rendered ABOVE the scrubber row. `<OrigamAudio>` injects
+     *  the cover + metadata strip here; `<OrigamVideo>` typically
+     *  leaves it empty. */
+    header?: () => any;
+    /** Replaces the default `<OrigamMediaScrubber>` scrubber row.
+     *  Receives `{ state, methods }` so the consumer can paint a
+     *  custom scrubber (audio waveform via SliderField variant=audio,
+     *  for example) while still routing seeks through `methods.seek`. */
+    waveform?: (bindings: {
+        state: IMediaPlayerState;
+        methods: IMediaPlayerMethods;
+    }) => any;
+    /** Block rendered BELOW the transport row. `<OrigamAudio>` injects
+     *  the playlist list here. */
+    footer?: () => any;
+    /** Buttons rendered at the start of the transport row, before the
+     *  play button. `<OrigamAudio>` can inject custom shuffle / queue
+     *  buttons here when the default `showShuffle` placement doesn't
+     *  fit. */
+    'prepend-transport'?: () => any;
+    /** Buttons rendered at the end of the transport row, after the
+     *  config menu. Consumers add custom buttons (favourite, queue,
+     *  …) here. */
+    'append-transport'?: () => any;
+    /** Additional buttons rendered on the left side of the toolbar,
+     *  AFTER the time display. Legacy slot — prefer `prepend-transport`. */
+    extraControlsLeft?: () => any;
+    /** Additional buttons rendered on the right side of the toolbar,
+     *  BEFORE the config menu. `<OrigamVideo>` injects its captions /
+     *  PiP / fullscreen buttons here. */
+    extraControlsRight?: () => any;
+    /** Extra rows in the config menu (audio output device, subtitle
+     *  track selector, …). Receives `{ closeMenu }`. */
+    configExtra?: (bindings: {
+        closeMenu: () => void;
+    }) => any;
+}