@prolibu-suite/cobalt-core 0.9.6 → 0.10.1

package/dist/types/components/co-date-time-picker/co-date-time-picker.d.ts

@@ -2,8 +2,10 @@ import { EventEmitter } from '../../stencil-public-runtime';
 import type { Placement } from '../../utils/positioning';
 /**
  * Date + TIME picker: one field, one popover. Composes `co-popover` (floating
- * panel, outside-click) + `co-calendar` (day grid) + a scrollable list of times
- * beside it — the Google Calendar layout.
+ * panel, outside-click) + `co-calendar` (day grid) + a side panel with
+ * shortcuts (`presetIds`: morning/noon/afternoon/endOfDay/now) and a segmented
+ * `co-time-field` (hh:mm, PageUp/PageDown stepping by `stepMinutes`) for the
+ * exact hour, plus a "Listo" button.
  *
  * VALUE CONTRACT — the committed `value` is a UTC ISO instant
  * ("2026-07-25T21:30:00.000Z"), never a wall-clock string. The wall clock the
@@ -16,16 +18,26 @@ import type { Placement } from '../../utils/positioning';
  * would shift the day west of UTC).
  *
  * INTERACTION (Google):
- *   - Click the field → opens. Picking a DAY commits and keeps the panel open
- *     (you almost always want to set the hour next); picking a TIME commits and
- *     closes. So there is no draft/apply step and no confirm button.
+ *   - Click the field → opens. Picking a DAY commits (with the current DRAFT
+ *     hour, not the previously committed one) and keeps the panel open — you
+ *     almost always want to set the hour next.
+ *   - The exact time is a DRAFT (`draftMinutes`) while `co-time-field` is
+ *     edited (`coInput`) — editing alone never commits. It only commits (and
+ *     closes) on: clicking a shortcut, Enter/`coCommit` from the time field,
+ *     or the "Listo" button.
+ *   - Outside click — and, on mobile, swiping the bottom sheet down — commits
+ *     the draft if it changed, then closes: the same "apply on blur" model a
+ *     text field uses.
+ *   - Escape is the opposite: an explicit DISCARD. It closes WITHOUT applying
+ *     the draft and returns focus to the trigger field.
  *   - ArrowDown on the field → moves focus into the calendar grid.
- *   - The time list is a listbox: Arrow/Home/End/PageUp/PageDown move the active
- *     option, Enter/Space selects it.
- *   - Escape → closes and returns focus to the field. Outside click → closes.
+ *   - Mobile (viewport ≤ `mobileBreakpoint`) renders the same panel as a
+ *     bottom sheet (`co-drawer position="bottom"`) instead of the desktop
+ *     popover; the draft/commit/discard model is identical.
  *
- * Escape is owned here (co-popover `closeOnEscape=false`) so focus can return to
- * the field; outside-click stays with co-popover.
+ * Escape is owned here (co-popover `closeOnEscape=false`) so focus can return
+ * to the field; outside-click/sheet-dismiss stay with co-popover/co-drawer and
+ * are handled by `closeApplyingDraft` (see its doc for the Escape asymmetry).
  *
  * @part field - The bordered trigger row
  * @part label - The field label
@@ -39,8 +51,10 @@ export declare class CoDateTimePicker {
     value: string | null;
     /** IANA zone the wall clock is rendered in. Defaults to the browser zone. */
     timeZone?: string;
-    /** Minutes between consecutive options in the time list. */
+    /** Paso de PageUp/PageDown del campo de hora (antes: paso de la lista). */
     stepMinutes: number;
+    /** Atajos del panel, en orden. Ids del catálogo: morning|noon|afternoon|endOfDay|now. */
+    presetIds: string[] | string;
     /** 12-hour clock (Google style). `false` renders a 24h clock. */
     hour12: boolean;
     /** Earliest selectable day. Date-only "YYYY-MM-DD" or an instant. */
@@ -77,8 +91,8 @@ export declare class CoDateTimePicker {
     mobileBreakpoint: number;
     /** True when the viewport is at/under `mobileBreakpoint`. */
     isMobile: boolean;
-    /** Minutes-of-day highlighted by the keyboard in the time list. */
-    activeMinutes: number;
+    /** Minutes-of-day drafted in the exact-time field (co-time-field), not yet committed. */
+    draftMinutes: number;
     /** Committed instant (UTC ISO) or null. */
     coChange: EventEmitter<string | null>;
     coClear: EventEmitter<void>;
@@ -89,15 +103,13 @@ export declare class CoDateTimePicker {
     private popoverEl?;
     private calendarEl?;
     private triggerBtn?;
-    private listEl?;
     private pendingFocusGrid;
     private pendingFocusTrigger;
-    /** 'center' when the list is (re)opened, 'nearest' while arrowing through it. */
-    private pendingScroll;
     private mql?;
     private mqlHandler;
     connectedCallback(): void;
     disconnectedCallback(): void;
+    componentWillLoad(): void;
     onOpenChange(next: boolean): void;
     private get zone();
     private get isInvalid();
@@ -112,17 +124,27 @@ export declare class CoDateTimePicker {
     private onClearClick;
     private onCalendarSelect;
     private pickTime;
-    private onListKeyDown;
+    private static readonly PRESET_CATALOG;
+    private get presets();
+    private onTimeFieldInput;
+    private onTimeFieldCommit;
     private onPopoverOpen;
+    /**
+     * Closes applying whatever is drafted (R7) — outside click / drawer
+     * swipe-down behave like a field's blur: what you typed sticks. This is
+     * the ONLY path that commits the draft on close; Escape is the opposite —
+     * an explicit discard — and it does NOT go through here: `onRootKeyDown`
+     * flips `this.open` to `false` via `setOpen()` FIRST, so by the time the
+     * real co-popover/co-drawer finish closing and bubble their own `coClose`
+     * back to `onPopoverClose`/this drawer's `onCoClose`, the guard below
+     * already reads `false` and no-ops — the draft is discarded, not applied.
+     */
+    private closeApplyingDraft;
     private onPopoverClose;
     private onRootKeyDown;
     private focusGridSoon;
-    private scrollActiveIntoView;
     componentDidRender(): void;
     private get step();
-    /** Grid of minutes-of-day, plus the committed hour when it falls off-grid
-     *  (an imported 16:37 meeting must stay visible and selectable). */
-    private get options();
     private renderTrigger;
     private renderPanel;
     private renderHelper;

package/dist/types/components/co-drawer/co-drawer.d.ts

@@ -71,9 +71,10 @@ export declare class CoDrawer {
     private stopPropagation;
     private handleTransitionEnd;
     private asideEl?;
-    /** Modeless only: keep the aside promoted to the top layer for its whole
-     *  lifetime (mirrors co-overlay's syncPopover; eviction on disconnect is
-     *  automatic). */
+    /** Ref del aside — SIEMPRE adjunto (handleTransitionEnd lo necesita como
+     *  target). Modeless only: además mantiene el aside promovido al top layer
+     *  para toda su vida (mirrors co-overlay's syncPopover; eviction on
+     *  disconnect is automatic). */
     private promoteModeless;
     componentDidLoad(): void;
     render(): any;

package/dist/types/components/co-file-field/co-file-field.d.ts

@@ -107,6 +107,11 @@ export declare class CoFileField {
     private lastFilesStr;
     private lastParsed;
     private lightboxEl?;
+    /** Seeding `@State` here and not on the class field: the @stencil/vitest
+     *  transform doesn't apply field defaults before the first render, so a
+     *  `failedPreviews.has(...)` in render() would blow up on a bare Set
+     *  (precedente co-data-table / co-audio-player). */
+    componentWillLoad(): void;
     connectedCallback(): void;
     disconnectedCallback(): void;
     private get parsedFiles();
@@ -126,6 +131,15 @@ export declare class CoFileField {
     private handleInputChange;
     private keyFor;
     private handleCopy;
+    /**
+     * The previews grid and the lightbox gallery MUST agree on what they show,
+     * or the index the viewer opens on points at the wrong file. One factory,
+     * two call sites.
+     *
+     * A video stays in the grid even when its poster fails to load (the card
+     * falls back to the type tile) — dropping it would leave no way to play it.
+     */
+    private previewItems;
     /**
      * Opens the clicked image in a co-lightbox with the SAME gallery the
      * previews grid shows. The lightbox is created imperatively on

package/dist/types/components/co-file-field/co-file-field.utils.d.ts

@@ -8,11 +8,28 @@ export declare function formatBytes(bytes: number | undefined): string;
  * digits/punctuation, and file names start with digits all the time.
  */
 export declare function truncateLeft(name: string, max?: number): string;
+/**
+ * Lower-cased extension of an item — from its name, falling back to its url.
+ * The fallback is not decoration: hosts derive `name` from whatever the record
+ * gives them (form-vue: `fileName || name || originalName || id`), so a File
+ * populated without `fileName` arrives named after its id, extensionless, with
+ * the only ".mov" in sight sitting in the url.
+ */
+export declare function fileExtension(item: FileItem): string;
+/**
+ * A stored video we can hand to a player. `url` is required on purpose: the
+ * thumbnail is a poster frame, not the media — an item with only a poster has
+ * nothing to play.
+ */
+export declare function isVideo(item: FileItem): boolean;
 /** An item renders in the previews grid when it's a stored image we can show. */
 export declare function isImage(item: FileItem): boolean;
+/** Items that earn a card in the previews grid: images and videos alike. */
+export declare function isPreviewable(item: FileItem): boolean;
 /**
  * Best lightbox source: the original `url` only when it is itself an image —
  * a PDF that entered the grid via its server-generated thumbnail must open
- * the thumbnail (an `<img>` can't render the PDF).
+ * the thumbnail (an `<img>` can't render the PDF). A video always resolves to
+ * the media itself; its poster travels separately as the player's `poster`.
  */
 export declare function previewSrc(item: FileItem): string | undefined;

package/dist/types/components/co-icon-button/co-icon-button.d.ts

@@ -37,6 +37,15 @@ export declare class CoIconButton {
     label: string;
     /** Phosphor icon name (e.g. "plus", "gear"). Renders co-icon inside the button. */
     icon?: string;
+    /**
+     * Second icon of the swap (play/pause, hamburger/x). With it set, `toggled`
+     * picks which one shows. ⚠️ The swap's crossfade drops the icon name as the
+     * accessible name source — with `toggleIcon` set, the consumer MUST pass
+     * `label` explicitly (the icon alone no longer describes the state).
+     */
+    toggleIcon?: string;
+    /** Swap state: false → `icon`, true → `toggleIcon`. */
+    toggled: boolean;
     /** Icon weight */
     iconWeight: 'regular' | 'thin' | 'light' | 'bold' | 'fill' | 'duotone';
     render(): any;

package/dist/types/components/co-input/co-input.d.ts

@@ -89,10 +89,17 @@ export declare class CoInput {
     /** Emitted when the integrated action button is clicked */
     coAction: EventEmitter<void>;
     hasFocus: boolean;
+    /** Sacudida en curso — se limpia en el animationend del keyframe para poder re-disparar. */
+    shaking: boolean;
+    onStatusChange(newVal: string, oldVal: string): void;
     el: HTMLElement;
     private inputEl?;
     /** Programmatically focus the inner input (post-hydration safe). */
-    setFocus(): Promise<void>;
+    /** Enfoca el input nativo. `options` se reenvía a `focus()` — p. ej.
+     *  `{ preventScroll: true }` para un buscador que vive en un panel
+     *  top-layer (co-popover): el scroll nativo hacia el foco trepa por los
+     *  ancestros del light DOM y arrastra al host (drawer) sin necesidad. */
+    setFocus(options?: FocusOptions): Promise<void>;
     componentDidLoad(): void;
     private handleInput;
     private handleChange;
@@ -101,6 +108,7 @@ export declare class CoInput {
     private handleKeyDown;
     private handleClear;
     private handleAction;
+    private handleShakeEnd;
     private get hasAction();
     private get hasValue();
     private get statusFieldIcon();

package/dist/types/components/co-lightbox/co-lightbox.d.ts

@@ -1,18 +1,26 @@
 import { EventEmitter } from '../../stencil-public-runtime';
 export interface LightboxImage {
-    /** Full-size image URL. */
+    /** Full-size image URL — or, on a video slide, the media itself. */
     src: string;
     /** Optional smaller preview (unused while rendering, kept for hosts). */
     thumbnail?: string;
     /** Caption / aria text (usually the file name). */
     alt?: string;
+    /** What the slide renders. Omitted means 'image' (every pre-video host). */
+    kind?: 'image' | 'video';
+    /** Poster frame for a video slide (usually the server-side thumbnail). */
+    poster?: string;
 }
 /**
- * Fullscreen image viewer — dark scrim, zoom (wheel / buttons / double-click,
+ * Fullscreen media viewer — dark scrim, zoom (wheel / buttons / double-click,
  * anchored at the cursor), drag-to-pan while zoomed, and prev/next carousel
- * when more than one image is provided. Keyboard: Escape closes, arrows
+ * when more than one item is provided. Keyboard: Escape closes, arrows
  * navigate, +/- zoom, 0 resets.
  *
+ * An item with `kind: 'video'` mounts a `co-video` instead of an `<img>`:
+ * zoom/pan make no sense over a seek bar, so they are disabled (and their
+ * toolbar cluster hidden) for as long as that slide is active.
+ *
  * Controlled like co-modal: the host owns `open` and reacts to `coClose`.
  *
  * CAVEAT: the root is `position: fixed`, so an ancestor with `transform`,
@@ -24,6 +32,7 @@ export interface LightboxImage {
  * @part overlay - Fullscreen scrim container
  * @part toolbar - Top bar (caption + zoom controls + actions)
  * @part image - The active image element
+ * @part video - The co-video player on a video slide
  * @part prev - Previous-image arrow button
  * @part next - Next-image arrow button
  * @part counter - The "i / n" indicator
@@ -50,6 +59,13 @@ export declare class CoLightbox {
     dragging: boolean;
     private stageEl?;
     private imgEl?;
+    private playerEl?;
+    /** Set when the viewer opens, consumed by the first player that mounts:
+     *  opening ON a video plays it, arrowing INTO one does not.
+     *  Declared WITHOUT an initializer on purpose: componentWillLoad seeds it,
+     *  and a class-field default would clobber that seed under the
+     *  @stencil/vitest transform (which applies field defaults late). */
+    private pendingAutoplay?;
     private closeBtnEl?;
     private lastImagesStr;
     private lastParsed;
@@ -58,6 +74,9 @@ export declare class CoLightbox {
     private previouslyFocused?;
     /** Focus the close button on the render that follows opening. */
     private pendingFocus;
+    private get activeItem();
+    /** Zoom, pan and the toolbar's zoom cluster are all gated on this. */
+    private get isVideoSlide();
     private get parsedImages();
     componentWillLoad(): void;
     connectedCallback(): void;
@@ -76,13 +95,50 @@ export declare class CoLightbox {
     private attachKeyListener;
     private detachKeyListener;
     private handleKey;
-    /** Minimal focus trap: Tab cycles through the viewer's own buttons. */
+    /**
+     * Minimal focus trap: Tab cycles through the viewer's own buttons — plus the
+     * player's, on a video slide. A shadow root is opaque to `querySelectorAll`,
+     * so co-video's controls have to be pulled in explicitly; without this the
+     * trap would cycle around the player and its play/seek would be unreachable
+     * by keyboard. (Safe because the viewer pins the controls visible: an
+     * auto-hidden control bar is `opacity: 0` and would take focus invisibly.)
+     */
+    private focusables;
+    /** Deepest focused element, walking down through nested shadow roots. */
+    private deepActive;
+    /** True while the player owns this Escape: it is fullscreen (co-video enters
+     *  through the webkit-prefixed API where that is all Safari has, so both
+     *  spellings are checked), or its speed menu is open on top of it. */
+    private escapeBelongsToPlayer;
+    private isFocusInPlayer;
     private trapTab;
     private clampIndex;
     private resetView;
     private requestClose;
     private goTo;
     private preloadNeighbors;
+    private mountPlayer;
+    /**
+     * Autoplay rides the click that opened the viewer instead of co-video's own
+     * `autoplay` prop, which only fires when muted — and a silent video reads as
+     * a broken one. If the browser refuses the unmuted start (Safari), the
+     * rejection is swallowed and the player simply waits on its play button.
+     *
+     * Called from BOTH sides of a race: the player mounts on the first render,
+     * which hosts do while still closed (co-file-field fades the viewer in on
+     * the next frame), so `open` usually arrives second — but a host that
+     * renders the viewer already open flips the order.
+     */
+    private tryAutoplay;
+    /**
+     * Ajusta la caja del slide al frame real. Sin esto el player es un rectángulo
+     * FIJO (ancho tope × alto tope) y el `object-fit: contain` deja franjas negras
+     * a los costados: en un vertical — el caso típico, una grabación de pantalla —
+     * la losa negra tapa media pantalla y se traga los clicks que el usuario dirige
+     * al scrim para cerrar.
+     */
+    private handlePlayerReady;
+    private pauseVideo;
     /** Pan is clamped so the scaled image can't be dragged fully off-stage. */
     private clampPan;
     /**

package/dist/types/components/co-menu-item/co-menu-item.d.ts

@@ -1,4 +1,5 @@
 import { EventEmitter } from '../../stencil-public-runtime';
+import type { Placement } from '../../utils/positioning';
 /**
  * Row inside a `co-menu`. Two modes:
  *
@@ -44,6 +45,11 @@ export declare class CoMenuItem {
     el: HTMLElement;
     hasSubmenu: boolean;
     submenuOpen: boolean;
+    /** Lado hacia el que este ítem PIDE abrir su submenú. Se recalcula en cada
+     *  apertura (no en render) heredando la dirección del ancestro: para cuando
+     *  el usuario puede hoverear una fila de este panel, el submenú del ancestro
+     *  ya se posicionó y publicó su lado. Ver utils/submenu.ts. */
+    submenuPlacementValue: Placement;
     private closeTimer?;
     private rowEl?;
     /** Programmatic focus — used by `co-menu`'s keyboard navigation. Named
@@ -58,6 +64,16 @@ export declare class CoMenuItem {
     private handleMouseEnter;
     private handleMouseLeave;
     private openSubmenu;
+    /** El popover ya se posicionó: publicamos el lado RESUELTO (post-flip) en el
+     *  host para que los co-menu-item anidados —hijos de light DOM— lo hereden.
+     *  Va como atributo y no como evento que burbujee a propósito: `coPlacement`
+     *  es `bubbles: false`, así que el de un submenú de adentro no se confunde
+     *  con el nuestro. */
+    private handlePlacement;
+    /** Cierra el submenú YA (sin delay de gracia). Público: lo invoca el hermano
+     *  que se está abriendo, mismo patrón cross-elemento que `focusItem`. */
+    closeSubmenu(): Promise<void>;
+    private closeSiblingSubmenus;
     private scheduleClose;
     private cancelClose;
     render(): any;

package/dist/types/components/co-modal/co-modal.d.ts

@@ -1,7 +1,14 @@
 import { EventEmitter } from '../../stencil-public-runtime';
 /**
  * @slot        - Modal body content
+ * @slot header-leading - Control before the heading (e.g. a back arrow on a
+ *                        second screen of the same modal)
+ * @slot header-actions - Controls at the right end of the header (e.g. a settings
+ *                        icon-button), before the close button
  * @slot footer - Footer with action buttons
+ * @part modal | header | header-text | heading | description | body | footer -
+ *       layout/typography hooks for a consumer that must match a specific spec
+ *       (paddings, heading weight); colors stay on semantic tokens
  */
 export declare class CoModal {
     /** Whether the modal is visible */
@@ -35,6 +42,9 @@ export declare class CoModal {
     size: 'sm' | 'md' | 'lg' | 'full';
     /** Hide body section and all border dividers (compact confirm dialogs) */
     noDividers: boolean;
+    /** Hairline between header and body. `false` lets the body run straight
+     *  under the heading (Figma modals whose first row is a segmented control). */
+    headerDivider: boolean;
     /** Emitted when the modal requests to close */
     coClose: EventEmitter<void>;
     /** Close animation finished. */

package/dist/types/components/co-number-field/co-number-field.d.ts

@@ -30,9 +30,24 @@ export declare class CoNumberField {
      * Display format. With 'rate' | 'percent' the `value` stays a DECIMAL
      * (e.g. 0.15) but the field shows/edits the PERCENT (15) with a "%" suffix.
      * value/min/max/step are always in the underlying (decimal) unit.
+     * With 'amount' the field is a live money mask: thousands separators while
+     * typing (1234.5 shows 1,234.5), typing restricted to digits and dot, and
+     * paste normalized whatever the source locale ("1.234,56" and "1,234.56"
+     * both commit 1234.56). The emitted value is always the raw number.
      * Reflected so it survives lazy hydration when set via the Vue wrapper.
      */
-    format?: 'rate' | 'percent';
+    format?: 'rate' | 'percent' | 'amount';
+    /**
+     * Oculta los botones ± (campo numérico "plano": precio, tasa). Las flechas
+     * ↑↓ siguen escalonando. Reflejado para que el CSS del host lo lea.
+     */
+    hideControls: boolean;
+    /**
+     * Sufijo de texto a la derecha del número (moneda, unidad). Reemplaza al "%"
+     * automático de `format`; cadena vacía = sin sufijo (útil cuando el slot
+     * `suffix` ya lleva el control que indica la unidad).
+     */
+    suffix?: string;
     focused: boolean;
     el: HTMLElement;
     coChange: EventEmitter<number | null>;
@@ -49,6 +64,12 @@ export declare class CoNumberField {
     private clamp;
     /** Whether the value↔display conversion (×100) is active. */
     private get scaled();
+    /** Whether the live money mask (thousands separators, paste parsing) is on. */
+    private get isAmount();
+    /** El signo entra sólo cuando el rango lo admite (sin `min`, o `min` < 0). */
+    private get allowNegative();
+    /** Texto canónico del input para el valor actual (formateado en amount). */
+    private get displayValue();
     /** Stored decimal → shown number (0.15 → 15). toFixed avoids FP artifacts. */
     private toDisplay;
     /** Typed number → stored decimal (15 → 0.15). */
@@ -57,8 +78,28 @@ export declare class CoNumberField {
     private handleDecrement;
     private handleIncrement;
     private handleInput;
+    /**
+     * Modo amount: en cada input se rearma el display desde los dígitos (miles
+     * con coma, coma tipeada descartada, sólo un punto) y el caret se restituye
+     * contando caracteres significativos — reescribir `value` lo mandaría al
+     * final. El punto colgante ("1,234.") sobrevive porque se reformatea el
+     * TEXTO, no el número parseado.
+     */
+    private handleAmountInput;
+    /**
+     * Pegar en modo amount: el texto llega con el formato de DONDE se copió
+     * (es-CO `1.234,56`, en-US `1,234.56`, la app `$ 34,640.00`), así que se
+     * interpreta con la heurística de separadores ANTES de empalmarlo con lo que
+     * ya había en el campo. Sin el preventDefault, el navegador escribiría el
+     * texto crudo y `parseFloat` cortaría en la primera coma (commit silencioso
+     * de 1 al pegar "1,234.56").
+     */
+    private handlePaste;
     private handleClear;
     private handleBlur;
+    private syncInputText;
+    /** Texto del afijo: `suffix` explícito manda; si no, el "%" de los formatos escalados. */
+    private get affixText();
     private handleFocus;
     private handleKeyDown;
     render(): any;

package/dist/types/components/co-option-list/co-option-list.d.ts

@@ -54,6 +54,9 @@ export declare class CoOptionList {
     /** Término externo para highlight (input en el host, p.ej. ⌘K). */
     highlightTerm: string;
     avatarShape: 'circle' | 'square';
+    /** `end` pinta el suffix como columna a la derecha de la fila (precio/meta),
+     *  sin el guion; `inline` = junto al label (default). */
+    suffixAlign: 'inline' | 'end';
     /** Auto-resalta la primera fila navegable al montar y en cada cambio de
      *  items (paridad command-palette: tipear + Enter = primer resultado).
      *  Salta filas disabled vía nextActiveIndex. */
@@ -117,6 +120,19 @@ export declare class CoOptionList {
     connectedCallback(): void;
     disconnectedCallback(): void;
     onItemsChange(): void;
+    /**
+     * Selected-first VIVO (decisión de producto 2026-09-14, campo Colaboradores):
+     * la partición sigue a `value` — marcar un ítem lo sube al bloque de
+     * seleccionados al instante y desmarcarlo lo devuelve a su lugar del orden del
+     * server. Reemplaza el snapshot congelado al abrir (evitaba saltos, pero se
+     * leía como "no pasó nada" al elegir). El reacomodo se anima con el mismo FLIP
+     * del reorder: tops capturados ANTES de re-particionar, runFlip corre en
+     * componentDidRender. El highlight de teclado se queda sobre el MISMO ítem
+     * (Enter sobre una fila la mueve; el índice viejo apuntaría a otra fila).
+     * Tras un drop del reorder el host manda el value en el orden del preview:
+     * mismo orden → deltas 0 → no-op visual.
+     */
+    onValueChange(): void;
     /** Re-toma el snapshot selected-first. El host la llama al abrir su panel. */
     snapshotOrder(): Promise<void>;
     /**

package/dist/types/components/co-option-list/optionListLogic.d.ts

@@ -47,14 +47,31 @@ export declare function parseValue(raw: string): string[];
  * snapshotDisplay los que la página actual no contiene) + resto en orden de
  * server; buscando → solo resultados reales, seleccionados primero.
  *
- * Invariante: todo id en `snapshotIds` DEBE tener una entrada correspondiente
- * en `snapshotDisplay` (armado por el caller desde selectedItems ∪ items al
- * tomar el snapshot). Un id sin display-item asociado se cae silenciosamente
- * de la lista en modo idle (el `byId.get(d._id) ?? d` sintetiza desde el
- * display-item mismo, pero no hay nada que sintetizar si el id nunca entró a
- * snapshotDisplay en primer lugar).
+ * El bloque idle se recorre por `snapshotIds` (Set ordenado por selección, igual
+ * que `snapshotDisplay`) resolviendo cada id contra la página primero y contra el
+ * display después. Así un seleccionado AUSENTE de `snapshotDisplay` pero presente
+ * en `items` sigue en la lista: `rest` filtra todo id del snapshot, así que sin
+ * esa resolución desaparecía de la lista entera, no sólo del bloque de arriba.
+ * Un id que no está en ninguna de las dos fuentes no tiene nada que pintar y se
+ * ignora (no hay label que mostrar).
  */
 export declare function orderItems(items: OptionListItem[], snapshotIds: Set<string>, snapshotDisplay: OptionListItem[], searching: boolean): OptionListItem[];
+/**
+ * ¿Hay que re-tomar el snapshot selected-first por el cambio del término?
+ *
+ * Sólo en el flanco "había búsqueda → ya no": volver a la lista completa es un
+ * contexto de listado nuevo, y ahí el bloque de arriba tiene que incluir lo que
+ * se seleccionó DURANTE la sesión del panel. Sin esto, un panel abierto sin nada
+ * seleccionado se quedaba con el snapshot VACÍO para siempre (`orderItems`
+ * cortocircuita en `size === 0`): lo elegido mientras se buscaba desaparecía de
+ * la lista al limpiar el término, porque el servidor devuelve la página 1 y esos
+ * registros casi nunca están ahí. Se leía como "se deselecciona solo".
+ *
+ * El re-snapshot por SELECCIÓN no pasa por acá: vive en el componente
+ * (`@Watch('value')`, selected-first vivo desde 2026-09-14 — marcar sube la fila
+ * al instante). Esta función solo decide el flanco del TÉRMINO.
+ */
+export declare function shouldResnapshotOnTerm(prevTerm: string, nextTerm: string): boolean;
 /** Aplana a filas de render insertando un header cuando `group` cambia
  *  (groupItems de co-command-search). `index` cuenta solo items. */
 export declare function buildRows(items: OptionListItem[]): OptionListRow[];

package/dist/types/components/co-overlay/co-overlay.d.ts

@@ -34,8 +34,10 @@ export declare class CoOverlay {
     private releaseLock;
     /**
      * Promote the scrim to the browser top layer so it covers the whole viewport
-     * regardless of ancestor `filter`/`mask`/`transform` (which would otherwise
-     * make `position: fixed` resolve against that ancestor, confining the scrim).
+     * regardless of ancestor containing blocks — `contain: layout` on the
+     * app-shell `.main` / `.co-drawer` / `.co-modal__frame` (which replaced the
+     * old ancestor `filter`/`mask`), or any `transform` — that would otherwise
+     * make `position: fixed` resolve against that ancestor, confining the scrim.
      * The Popover API promotes WITHOUT moving the DOM node, so slots and Stencil
      * reconciliation are untouched. No-ops gracefully where unsupported.
      */

package/dist/types/components/co-popover/co-popover.d.ts

@@ -25,7 +25,21 @@ export declare class CoPopover {
     flip: boolean;
     coOpen: EventEmitter<void>;
     coClose: EventEmitter<void>;
+    /** El placement REAL con el que quedó el panel, ya pasado por el flip — que
+     *  puede no ser el de la prop `placement`. Lo consume `co-menu-item` para que
+     *  una cadena de submenús herede la dirección (ver utils/submenu.ts): sin
+     *  esto, un submenú anidado vuelve a abrir hacia la derecha y se dibuja
+     *  encima del menú padre del que salió.
+     *
+     *  Se emite SOLO cuando el lado cambia (mismo guard que la clase del panel),
+     *  así el path de scroll/resize no dispara un evento por tick. */
+    coPlacement: EventEmitter<{
+        placement: Placement;
+    }>;
     el: HTMLElement;
+    /** Fase de salida: mantiene el panel montado mientras corre la transición de cierre. */
+    closing: boolean;
+    private closeFallbackTimer?;
     private triggerEl?;
     private panelEl?;
     private rafId?;
@@ -36,6 +50,8 @@ export declare class CoPopover {
     componentDidLoad(): void;
     disconnectedCallback(): void;
     onOpenChange(isOpen: boolean): void;
+    private finishClose;
+    private handlePanelTransitionEnd;
     private bindDocListeners;
     private unbindDocListeners;
     toggle(): Promise<void>;