@m4l/testing 0.0.24 → 1.0.1

package/types/packages/testing/playwright/src/helpers/listDatagrid.d.ts

@@ -0,0 +1,219 @@
+import type { Locator, Page } from '@playwright/test';
+/**
+ * Scope that owns the list datagrid DOM — the full page or one managed host window.
+ */
+export type ListDatagridScope = Page | Locator;
+/**
+ * Return the list datagrid container, anchored on the stable `grid` ARIA role so
+ * the locator survives the production preview bundle, where dev-only test ids are
+ * stripped.
+ */
+export declare function getListDataGrid(scope: ListDatagridScope): Locator;
+/**
+ * Return the rendered data rows of the list datagrid. Anchored on the stable ARIA
+ * roles emitted by react-data-grid in the production bundle: a data row is a
+ * `role="row"` that contains a `role="gridcell"`, which excludes the header row
+ * (whose cells are `columnheader`). Module-agnostic across every GClick list MF.
+ */
+export declare function getListDataRows(scope: ListDatagridScope): Locator;
+/**
+ * Return a data cell of the list datagrid by its exact accessible name. Anchored
+ * on the `gridcell` ARIA role so it survives the production bundle and stays
+ * module-agnostic. Exact matching keeps numeric values from colliding with dates
+ * or longer formatted values that merely contain the same digits.
+ */
+export declare function getListCell(scope: ListDatagridScope, text: string): Locator;
+/**
+ * Return one data row of the list datagrid by index (0-based, render order).
+ */
+export declare function getListRow(scope: ListDatagridScope, index?: number): Locator;
+/**
+ * Open the row-actions menu of one data row by clicking its "menu-actions" button.
+ * The menu then exposes the row actions (Edit, Delete, ...) as `menuitem`s, which
+ * the caller clicks by their module-specific label.
+ */
+export declare function openListRowActionsMenu(scope: ListDatagridScope, index?: number): Promise<void>;
+/**
+ * Double-click one data row to trigger its default row action. The datagrid wires
+ * the default action to `onCellDoubleClick`, so the double-click targets a data
+ * cell (the first one after the menu-actions cell), not the row itself.
+ */
+export declare function doubleClickListRow(scope: ListDatagridScope, index?: number): Promise<void>;
+/**
+ * Select one data row by clicking a data cell (skipping the menu-actions cell), so
+ * the master-detail layout updates its detail panel to that record.
+ */
+export declare function selectListRow(scope: ListDatagridScope, index?: number): Promise<void>;
+/** Position of one datagrid cell, as the table view publishes it through ARIA. */
+export interface ListDatagridCellPosition {
+    /** `aria-rowindex` of the row owning the cell. */
+    rowIndex: number;
+    /** `aria-colindex` of the cell itself. */
+    columnIndex: number;
+}
+/**
+ * Return the position of the cell the table view currently has focused, read from the
+ * `aria-selected` marker react-data-grid puts on it.
+ *
+ * ⚠️ **Assert relative movement, never these absolute numbers.** Both indexes are
+ * 1-based and count every rendered row and column, including the header row and the
+ * filter row — so the first data row is `aria-rowindex` 3 in a grid with both, and 2 in
+ * a grid with only a header. Pinning an absolute value would tie a contract to a
+ * chrome layout that has nothing to do with the behavior under test; comparing a
+ * before/after pair is what proves the arrow keys moved the focus.
+ *
+ * Table view only: the cards and list views render no `gridcell` at all.
+ */
+export declare function getFocusedCellPositionListDataGrid(scope: ListDatagridScope): Promise<ListDatagridCellPosition>;
+/**
+ * Return the header controls of the table view, one per visible column.
+ *
+ * Exposed as a locator so a contract can assert **how many** columns are visible —
+ * including none at all, which is a reachable state: hiding every column from the
+ * settings modal leaves the grid with no headers. The readers below cannot answer that
+ * question, because they wait for a first header to appear and a grid with zero columns
+ * never produces one.
+ */
+export declare function getListColumnHeaderButtons(scope: ListDatagridScope): Locator;
+/**
+ * Actions the column header popover always offers, whatever the module configured.
+ *
+ * Sort, filter and group entries come and go with the module's settings, but freezing
+ * and hiding a column are unconditional — they are the datagrid's own base actions. A
+ * contract that only needs to prove "the column configuration popover is open" should
+ * anchor on these, so it stays true for any list module.
+ *
+ * They are located by accessible name: the component publishes each action's test id as
+ * its `aria-label`, which names the action rather than its translated label.
+ */
+export declare const LIST_HEADER_POPOVER_BASE_ACTIONS: readonly ["toggle-freeze", "hide-column"];
+/**
+ * Return the column header popover.
+ *
+ * Resolved from the page, never from the grid: the popover is rendered in a portal at
+ * the end of the document, so a locator scoped to the grid would never find it.
+ */
+export declare function getListHeaderPopover(scope: ListDatagridScope): Locator;
+/**
+ * Open the column configuration popover by clicking one column's header, and wait until
+ * its base actions are on screen.
+ */
+export declare function openListHeaderPopover(scope: ListDatagridScope, columnKey: string): Promise<void>;
+/** One entry of the column header popover, with the state the user sees. */
+export interface ListHeaderPopoverAction {
+    /** Action identity, from the entry's accessible name (`sort-ascending`, …). */
+    action: string;
+    /** Whether the entry is offered but not currently usable. */
+    disabled: boolean;
+}
+/**
+ * Return every action the open column header popover offers, in render order, each with
+ * whether it is currently usable.
+ *
+ * Offered and enabled are different questions and both matter: the popover always
+ * *offers* the same entries for a column, while their enabled state reflects what is
+ * already applied — after sorting a column ascending, that entry turns off and "remove
+ * sort" turns on. A contract that only counted entries would miss that entirely.
+ */
+export declare function getListHeaderPopoverActions(scope: ListDatagridScope): Promise<ListHeaderPopoverAction[]>;
+/**
+ * Click one action of the open column header popover.
+ */
+export declare function clickListHeaderPopoverAction(scope: ListDatagridScope, action: string): Promise<void>;
+/**
+ * Dismiss the column header popover by clicking outside it, and wait until it is gone.
+ *
+ * Clicking the backdrop rather than pressing Escape, and the reason is a real defect:
+ * **opening the popover never moves focus into it**. Verified in a browser — after the
+ * header click the active element is still outside the popover, so Escape never reaches
+ * it and the popover stays open. Moving focus inside by hand and pressing Escape *does*
+ * close it, which pins the fault on the missing focus transfer, not on the key handler.
+ *
+ * Beyond breaking Escape, that leaves the popover unreachable by keyboard and
+ * unannounced to a screen reader. Clicking outside is what a pointer user does anyway,
+ * so this helper stays useful once the focus behavior is fixed.
+ */
+export declare function closeListHeaderPopover(scope: ListDatagridScope): Promise<void>;
+/**
+ * Return the header cell of one column of the table view, located through its stable
+ * `header-column-button-<key>` control rather than a positional index — so a contract
+ * keeps pointing at the same column when the order changes.
+ */
+export declare function getListColumnHeader(scope: ListDatagridScope, columnKey: string): Locator;
+/**
+ * Return the rendered width of one column of the table view, in pixels.
+ *
+ * Read from the header cell's box rather than from the grid's inline
+ * `grid-template-columns`: the template is positional, so reading it would tie the
+ * assertion to a column order that the user can change.
+ */
+export declare function getListColumnWidth(scope: ListDatagridScope, columnKey: string): Promise<number>;
+/**
+ * Drag one column's resize handle by `deltaPx` and return its new width.
+ *
+ * The handle is the header cell's last child — a 10px strip with `cursor: col-resize`
+ * that react-data-grid renders with a generated class name, so it is reached by
+ * geometry (the right edge of the header) instead of by selector. Resizing is a real
+ * pointer drag on purpose: it is the only way the component runs the same code path a
+ * user triggers, including the change callback that persists the new width.
+ */
+export declare function resizeListColumn(scope: ListDatagridScope, columnKey: string, deltaPx: number): Promise<number>;
+/**
+ * Return the visible column keys of the list datagrid, in render order, read from
+ * the header buttons' stable aria-labels (`header-column-button-<key>`). Use it to
+ * assert the grid structure matches the module's expected column configuration.
+ *
+ * Assumes the grid has at least one visible column — it waits for a header to appear.
+ * To assert the empty case, use `getListColumnHeaderButtons` and count instead.
+ */
+export declare function getListColumnKeys(scope: ListDatagridScope): Promise<string[]>;
+/**
+ * Return each visible column's documented alignment, keyed by column key.
+ *
+ * The Notion Columns table declares an `Align` per column, and nothing asserted it until a
+ * real bug went unnoticed: two columns documented `Center` shipped left-aligned and every
+ * contract stayed green, because `REQ-LIST-DATAGRID-002` only compared column **keys**.
+ *
+ * The datagrid encodes alignment as `rdg-cell-align-left|center|right` on the column
+ * header. Those are **react-data-grid's own semantic class names**, not hashed build
+ * output, so anchoring on them does not break the selector policy the way a MUI generated
+ * class would — they are part of the library's stable DOM contract.
+ *
+ * Scrolls horizontally like `getAllColumnKeysViewTableDataGrid`, so virtualized columns
+ * off-screen are collected too.
+ */
+export declare function getAllColumnAlignmentsViewTableDataGrid(scope: ListDatagridScope): Promise<Record<string, string>>;
+/**
+ * Return **every** column key of the datagrid in the **table** view, in order,
+ * scrolling horizontally to reach the ones column virtualization keeps out of the DOM.
+ *
+ * `getListColumnKeys` only sees the columns that currently fit the window, so it can
+ * never prove a grid renders *all* its documented columns — a module shipping fewer
+ * than documented would still match a subset. Use this one whenever the assertion is
+ * about completeness, no matter how many columns the module has or how wide the window
+ * is. The grid is scrolled back to the start before returning.
+ *
+ * Table view only: column headers do not exist in the cards or list views, where the
+ * fields live inside each record and virtualization runs vertically. Use
+ * `getAllFieldKeysViewCardsOrListDataGrid` for those.
+ */
+export declare function getAllColumnKeysViewTableDataGrid(scope: ListDatagridScope): Promise<string[]>;
+/**
+ * Return the field keys rendered for one record in the **cards** or **list** view, in
+ * order, read from the stable `datagrid-field-<key>` anchors.
+ *
+ * No scrolling is needed: a single card or list row already contains every field of
+ * that record — what virtualization hides are the *other* records, not this one's
+ * fields. That is the opposite problem to
+ * `getAllColumnKeysViewTableDataGrid`, hence a separate helper.
+ *
+ * The anchor is a `data-testid` rather than an accessible name on purpose: each field
+ * already renders its own visible label, so putting the machine key into ARIA would
+ * replace a meaningful label with a machine string.
+ *
+ * Exercised in a browser by `REQ-LIST-DATAGRID-006` on the cards view. Still unproven
+ * against the **list** view, whose records are a different element; modules that boot
+ * into it and are therefore where to prove it: `operative_devices_list` (Master) and
+ * `shared_users_list` (Master).
+ */
+export declare function getAllFieldKeysViewCardsOrListDataGrid(scope: ListDatagridScope, recordIndex?: number): Promise<string[]>;

package/types/packages/testing/playwright/src/helpers/listDetail.d.ts

@@ -0,0 +1,65 @@
+import type { Locator, Page, Request } from '@playwright/test';
+import type { ListDatagridScope } from './listDatagrid';
+/**
+ * Return the master-detail empty state ("no item selected"), shown before any
+ * master record is selected. Anchored on the stable `alert` role + accessible name.
+ */
+export declare function getListDetailEmptyState(scope: ListDatagridScope): Locator;
+/**
+ * Return a detail field of the master-detail panel by its visible text. The detail
+ * renders fields as `listitem`s (not datagrid `gridcell`s), so this is scoped to the
+ * detail panel and does not match values shown in the master grid. The field nests
+ * several `listitem`s; `.last()` is the innermost (the actual field row), which is
+ * the element that hides when its accordion collapses — so the same locator works
+ * both for "detail shows X" and "accordion collapsed → X hidden" assertions.
+ */
+export declare function getListDetailField(scope: ListDatagridScope, text: string): Locator;
+/**
+ * Return a detail accordion by its heading text (its `dictionaryId` label).
+ */
+export declare function getListDetailAccordion(scope: ListDatagridScope, name: string): Locator;
+/**
+ * Toggle a detail accordion open/closed by clicking its heading. Collapsing hides
+ * the accordion content; expanding shows it again.
+ */
+export declare function toggleListDetailAccordion(scope: ListDatagridScope, name: string): Promise<void>;
+/**
+ * Return the OPEN accordion content regions (`role="region"`). An accordion's
+ * region exists only while expanded — collapsing removes it from the accessibility
+ * tree — so the count equals the number of currently-open accordions. Prefer this
+ * over a field's visibility for open/close assertions, because MUI clips collapsed
+ * content (a field can stay "visible" to Playwright while clipped).
+ */
+export declare function getListDetailAccordionRegions(scope: ListDatagridScope): Locator;
+/**
+ * Return the field **labels** the detail panel renders, in order.
+ *
+ * `getListDetailField` answers "is this value on screen"; this answers "which fields does
+ * the panel offer at all". The Notion `props_*` table declares one row per field, so a
+ * field silently dropped from the accordion is a documented expectation going unmet — and
+ * nothing catches it if the contract only probes one value.
+ *
+ * ⚠️ **Scoped to the accordion regions, not the page.** A page-level `listitem` lookup also
+ * matches the host sidebar's module entries and the accordion headings, so the list comes
+ * back polluted with entries that are not fields at all.
+ *
+ * Each field renders as a `listitem` whose first text line is its label.
+ */
+export declare function getListDetailFieldLabels(scope: ListDatagridScope): Promise<string[]>;
+/**
+ * Open the detail Logs tab and trigger its load, resolving with the logs request.
+ *
+ * The detail's Logs tab (ObjectLogs) is in manual mode (`fireOnFirstLoad: false`),
+ * so the logs load only when its DynamicFilter is applied via its "refresh" action.
+ * That refresh is the LAST `refresh` button on the page (it appears when the Logs
+ * tab opens, after the master list's own filter refresh). The request carries the
+ * applied filter (resource type/serial + the date range), so any list E2E can
+ * assert "logs load according to the applied filter".
+ */
+export declare function loadListDetailLogsAndCaptureRequest(options: {
+    page: Page;
+    /** Visible label of the Logs tab (the module's `tab_logs` value). */
+    logsTabName: string;
+    /** URL pattern of the logs endpoint (e.g. `/\/users\/resources\/logs/`). */
+    logsEndpointPattern: RegExp;
+}): Promise<Request>;

package/types/packages/testing/playwright/src/helpers/listFilter.d.ts

@@ -0,0 +1,27 @@
+import type { Request } from '@playwright/test';
+import type { ApplyListFilterOptions, ApplyListFiltersOptions } from '../types';
+/**
+ * Apply one list filter through the real DynamicFilter UI and resolve with the
+ * resulting list request, so any list E2E can assert the endpoint was called with
+ * the filter applied — regardless of the filter type.
+ *
+ * Interaction (all anchored on stable ARIA, the production bundle strips testids):
+ * open the field menu (`button[aria-label="searchbox"]`), pick the field by its
+ * visible `menuitem` label, enter the value (text input for string/number, the
+ * operand autocomplete for boolean — the operator already has a sensible default)
+ * and submit it with `Enter` (staging the filter), then trigger the network call
+ * with the filter-actions `button[aria-label="refresh"]` (the DynamicFilter is in
+ * manual mode: applying only stages the filter; refresh fires the request).
+ */
+export declare function applyListFilterAndCaptureRequest(options: ApplyListFilterOptions): Promise<Request>;
+/**
+ * Apply several filters in sequence and resolve with the final list request,
+ * which carries all of them (filters accumulate as chips). Used by the multiple
+ * filters contract.
+ */
+export declare function applyListFiltersAndCaptureRequest(options: ApplyListFiltersOptions): Promise<Request>;
+/**
+ * Extract the filter field names from a captured list request, reading the nested
+ * `f[i][n]=...` query params (e.g. `['name']`, `['document_id', 'active']`).
+ */
+export declare function getListFilterFieldNames(request: Request): string[];

package/types/packages/testing/playwright/src/helpers/listSort.d.ts

@@ -0,0 +1,19 @@
+import type { Request } from '@playwright/test';
+import type { ApplyListSortOptions } from '../types';
+/**
+ * Sort a list by a column header and resolve with the resulting list request, so
+ * any list E2E can assert the endpoint was called with the sort criterion — for
+ * each sort field of the module.
+ *
+ * Interaction (stable ARIA only): click the column header
+ * (`button[aria-label="header-column-button-<columnKey>"]`) to open its menu, then
+ * the `menuitem[aria-label="sort-descending"]` option. Sorting is automatic, so the
+ * request fires immediately. `sort-descending` is used uniformly because it is
+ * always a change from the default sort, so it stays enabled for every field.
+ */
+export declare function applyListSortAndCaptureRequest(options: ApplyListSortOptions): Promise<Request>;
+/**
+ * Extract the sort field names from a captured list request, reading the nested
+ * `s[i][n]=...` query params (e.g. `['name']`, `['name', 'id']`).
+ */
+export declare function getListSortFieldNames(request: Request): string[];

package/types/packages/testing/playwright/src/helpers/listStatePersistence.d.ts

@@ -0,0 +1,15 @@
+import type { Page, Request } from '@playwright/test';
+/**
+ * Module-state cookie names the list DynamicFilterAndSort persists to. The list
+ * uses `prefixCookie: 'master'`, so applied filters/sorts are saved under these
+ * names. Module-agnostic across every GClick list microfrontend.
+ */
+export declare const LIST_FILTERS_STATE_COOKIE = "master_applied_filters";
+export declare const LIST_SORTS_STATE_COOKIE = "master_applied_sorts";
+/**
+ * Resolve with the PUT request that persists the list's applied filters/sorts to
+ * the host module-state cookie (`PUT /cookies/<windowId>/<cookieName>`). Applying a
+ * filter or sort triggers this write, which the module reads back to restore the
+ * list state on reload.
+ */
+export declare function waitForListStatePersistence(page: Page, cookieName: string): Promise<Request>;

package/types/packages/testing/playwright/src/helpers/openHostAccountMenuModule.d.ts

@@ -0,0 +1,10 @@
+import type { OpenHostAccountMenuModuleOptions } from '../types';
+/**
+ * Open a module from the host account popover the way a user does: click the avatar,
+ * then the popover entry.
+ *
+ * This is the real door for the user-scoped modules — the preferences forms the product
+ * never publishes in the sidebar. The rows come from the account menu endpoint
+ * (`menus?position=1`), so the suite must have installed them before calling this.
+ */
+export declare function openHostAccountMenuModule(options: OpenHostAccountMenuModuleOptions): Promise<void>;

package/types/packages/testing/playwright/src/helpers/openHostAuthenticatedMfPreviewModule.d.ts

@@ -0,0 +1,5 @@
+import type { OpenHostAuthenticatedMfPreviewModuleOptions, OpenHostAuthenticatedMfPreviewOpenTimingSnapshot } from '../types';
+/**
+ * Open an authenticated MF preview entry through the real host sidebar flow.
+ */
+export declare function openHostAuthenticatedMfPreviewModule(options: OpenHostAuthenticatedMfPreviewModuleOptions): Promise<OpenHostAuthenticatedMfPreviewOpenTimingSnapshot>;

package/types/packages/testing/playwright/src/helpers/openHostMobileSidebarModule.d.ts

@@ -0,0 +1,15 @@
+import type { Page } from '@playwright/test';
+/**
+ * Accessible name of the host appbar hamburger toggle that opens the mobile nav
+ * drawer. The dictionary label is unmocked in preview, so it renders as this
+ * `N_D:[...]` placeholder; matched by accessible name (a CSS attribute selector
+ * would break on the `[`/`]` in the label).
+ */
+export declare const HOST_MOBILE_NAV_TOGGLE_NAME = "N_D:[appbar.tooltip_toogle_menu]";
+/**
+ * Open a host-shell module on the MOBILE layout: click the appbar hamburger to
+ * reveal the nav drawer, then click the module's menu item. On mobile the host
+ * replaces the desktop sidebar with this drawer, so the desktop sidebar flow does
+ * not apply.
+ */
+export declare function openHostMobileSidebarModule(page: Page, moduleTitle: string): Promise<void>;

package/types/packages/testing/playwright/src/helpers/openHostSidebarModule.d.ts

@@ -0,0 +1,5 @@
+import type { OpenHostSidebarModuleOptions, OpenHostSidebarModuleTimingSnapshot } from '../types';
+/**
+ * Open a host-shell sidebar entry by title, expanding the sidebar first when needed.
+ */
+export declare function openHostSidebarModule(options: OpenHostSidebarModuleOptions): Promise<OpenHostSidebarModuleTimingSnapshot>;

package/types/packages/testing/playwright/src/helpers/realtimePerformanceBrowser.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Serializable browser argument used by page-side helpers that read realtime debug state.
+ */
+export interface BrowserRealtimePerformancePropertyArg {
+    /** Catalog-owned browser property that stores the realtime debug state. */
+    realtimePerformanceProperty: string;
+}
+/**
+ * Serializable browser argument used when a predicate expects multiple device ids.
+ */
+export interface BrowserRealtimeDeviceIdsArg extends BrowserRealtimePerformancePropertyArg {
+    /** Ordered device ids that should already exist in the realtime debug state. */
+    deviceIds: string[];
+}
+/**
+ * Serializable browser argument used when a predicate targets one device id.
+ */
+export interface BrowserRealtimeDeviceIdArg extends BrowserRealtimePerformancePropertyArg {
+    /** Device id that should already be readable from the realtime debug state. */
+    deviceId: string;
+}
+/**
+ * Stable Node-side property name forwarded into browser-executable callbacks.
+ */
+export declare const realtimePerformanceDebugHandleProperty: "__M4L_REALTIME_PERFORMANCE__";
+/**
+ * Minimal DOMRect-like payload returned by browser element sampling.
+ */
+export type BrowserBoundingClientRectLike = Record<string, unknown>;
+/**
+ * Minimal element shape required inside `page.evaluate(...)`.
+ */
+export type BrowserElementLike = {
+    /** Returns the current layout box when the sampled node exists. */
+    getBoundingClientRect?: () => BrowserBoundingClientRectLike;
+};
+/**
+ * Shared realtime motion-authority state exposed by the M4L debug window object.
+ */
+export type BrowserRealtimePerformanceMotionAuthorityState = {
+    /** Active motion sessions keyed by internal marker or session id. */
+    activeSessions?: Record<string, Record<string, unknown>>;
+    /** Latest marker-context snapshots keyed by device or marker id. */
+    markerContexts?: Record<string, Record<string, unknown>>;
+    /** Recent visual marker applications measured after Leaflet accepted frames. */
+    recentVisualApplyFrames?: Array<Record<string, unknown>>;
+    /** Recent completed motion sessions kept for diagnostics. */
+    recentSessions?: Array<Record<string, unknown>>;
+    /** Aggregate summary payload emitted by the realtime debug module. */
+    summary?: Record<string, unknown> | null;
+};
+/**
+ * Motion metrics branch read from `window.__M4L_REALTIME_PERFORMANCE__`.
+ */
+export type BrowserRealtimePerformanceMotionMetrics = {
+    /** Motion authority diagnostics used by realtime browser probes. */
+    motionAuthority?: BrowserRealtimePerformanceMotionAuthorityState;
+};
+/**
+ * Minimal realtime debug state contract expected by M4L browser probes.
+ */
+export type BrowserRealtimePerformanceState = {
+    /** Motion metrics captured by the current app debug instrumentation. */
+    motionMetrics?: BrowserRealtimePerformanceMotionMetrics;
+};
+/**
+ * Minimal document body shape used for failure diagnostics.
+ */
+export type BrowserDocumentBodyLike = {
+    /** Flattened visible text used when the expected UI is missing. */
+    innerText?: string;
+};
+/**
+ * Minimal browser document contract used during page-side sampling.
+ */
+export type BrowserDocumentLike = {
+    /** Body text snapshot used when selection or rendering fails. */
+    body?: BrowserDocumentBodyLike;
+    /** DOM query API used to find map markers and related status nodes. */
+    querySelector?: (selector: string) => BrowserElementLike | null;
+};
+/**
+ * Minimal computed-style payload used to read CSS transforms.
+ */
+export type BrowserComputedStyleLike = {
+    /** Serialized CSS transform matrix or transform function list. */
+    transform?: string;
+};
+/**
+ * Minimal performance API contract used for time-based browser sampling.
+ */
+export type BrowserPerformanceLike = {
+    /** High-resolution timestamp provider used by polling helpers. */
+    now?: () => number;
+};
+/**
+ * Minimal browser global contract used inside `page.evaluate(...)`.
+ */
+export type BrowserGlobalLike = Record<string, unknown> & {
+    /** DOM entry points required by browser collectors and wait helpers. */
+    document?: BrowserDocumentLike;
+    /** Style reader used to inspect marker transforms on map-based views. */
+    getComputedStyle?: (element: unknown) => BrowserComputedStyleLike | null;
+    /** Timing entry point used by browser sampling loops. */
+    performance?: BrowserPerformanceLike;
+};
+/**
+ * Read the realtime motion-authority state exposed by the current page runtime.
+ *
+ * This helper is browser-executable and can be passed directly to
+ * `page.evaluate(...)`.
+ */
+export declare function readRealtimeMotionAuthorityState(arg: BrowserRealtimePerformancePropertyArg): BrowserRealtimePerformanceMotionAuthorityState | null;
+/**
+ * Check whether all requested device ids exist in the realtime marker-context map.
+ *
+ * This helper is browser-executable and can be passed directly to
+ * `page.waitForFunction(...)`.
+ *
+ * @param deviceIds Ordered device ids that should already exist in the debug state.
+ * @returns `true` once every requested device id has one marker context entry.
+ */
+export declare function hasRealtimeMarkerContexts(arg: BrowserRealtimeDeviceIdsArg): boolean;
+/**
+ * Check whether one realtime device is selected or the debug panel is already visible.
+ *
+ * This helper is browser-executable and can be passed directly to
+ * `page.waitForFunction(...)`.
+ *
+ * @param deviceId Device id expected to become selected in the debug state.
+ * @returns `true` when the device is selected or the current debug report panel is visible.
+ */
+export declare function isRealtimeDeviceSelectedOrDebugPanelVisible(arg: BrowserRealtimeDeviceIdArg): boolean;
+/**
+ * Check whether one realtime device is explicitly selected in the browser debug state.
+ *
+ * Unlike the broader fallback helper above, this predicate does not accept the
+ * device panel alone as sufficient evidence. Use it when one probe depends on
+ * the selected marker follow loop being armed from the actual target device.
+ *
+ * @param deviceId Device id expected to become selected in the debug state.
+ * @returns `true` only when the marker context reports an explicit selected state.
+ */
+export declare function isRealtimeDeviceSelected(arg: BrowserRealtimeDeviceIdArg): boolean;

package/types/packages/testing/playwright/src/helpers/viewModeDataGrid.d.ts

@@ -0,0 +1,67 @@
+import { type Locator } from '@playwright/test';
+import { type ListDatagridScope } from './listDatagrid';
+/**
+ * The three view modes a GClick datagrid can render, mirroring the component
+ * `ViewMode` union (`'table' | 'cards' | 'list'`).
+ */
+export type ViewModeDataGrid = 'table' | 'cards' | 'list';
+/**
+ * Return the view mode the datagrid is currently rendering, read from the active
+ * view's accessible name. Waits for a view to be attached before resolving.
+ */
+export declare function getViewModeDataGrid(scope: ListDatagridScope): Promise<ViewModeDataGrid>;
+/**
+ * Assert the datagrid renders in the expected view mode, failing with the mode it
+ * actually rendered so a wrong-view regression is immediately readable.
+ */
+export declare function expectViewModeDataGrid(scope: ListDatagridScope, expectedMode: ViewModeDataGrid): Promise<void>;
+/**
+ * Open the datagrid's view-mode switcher popover. The trigger only renders when the
+ * module configures at least one alternative view, so a module offering table alone
+ * has no switcher at all.
+ */
+export declare function openViewModeSwitcherDataGrid(scope: ListDatagridScope): Promise<void>;
+/**
+ * Return the view modes the module actually offers, read from the switcher popover.
+ *
+ * Anchored on each option's `data-testid` rather than its label: the labels are
+ * dictionary values that say nothing about which view they switch to, so a
+ * translation change would break the locator while the behavior is intact. The test
+ * id encodes the view identity itself, which is what matters here.
+ *
+ * Reading the offered set instead of assuming it is what lets a contract prove it
+ * covered **every** configured view — a hardcoded list silently stops covering a view
+ * the module adds later.
+ */
+export declare function getAvailableViewModesDataGrid(scope: ListDatagridScope): Promise<ViewModeDataGrid[]>;
+/**
+ * Dismiss the view-mode switcher popover without changing the current view.
+ */
+export declare function closeViewModeSwitcherDataGrid(scope: ListDatagridScope): Promise<void>;
+/**
+ * Switch the datagrid to a view mode through the real switcher, and wait until that
+ * view is the one rendering.
+ */
+export declare function switchViewModeDataGrid(scope: ListDatagridScope, mode: ViewModeDataGrid): Promise<void>;
+/**
+ * Open the datagrid's column-settings modal for the **currently active** view. Each
+ * view owns its own configuration, so which modal opens depends on the active view.
+ */
+export declare function openColumnSettingsDataGrid(scope: ListDatagridScope): Promise<void>;
+/**
+ * Hide every column of the active view from its settings modal, and apply.
+ *
+ * A blunt edit on purpose: a contract proving one view's configuration does not leak
+ * into another needs a change that is impossible to miss, and "no columns left" cannot
+ * be confused with a rendering coincidence.
+ */
+export declare function hideAllColumnsDataGrid(scope: ListDatagridScope): Promise<void>;
+/**
+ * Return the rendered record elements of the **currently active** view, so a contract
+ * can count records without caring which view is on screen.
+ *
+ * Each view renders records as a different element, and only the table view exposes
+ * them through ARIA rows. Cards and list rows are anchored on their `data-testid`
+ * because they carry no role that identifies them as one record.
+ */
+export declare function getRenderedRecordsDataGrid(scope: ListDatagridScope, mode: ViewModeDataGrid): Locator;

package/types/packages/testing/playwright/src/helpers/waitForBrowserCondition.d.ts

@@ -0,0 +1,38 @@
+import type { Page } from '@playwright/test';
+/**
+ * Reusable browser-condition callback signature accepted by Playwright wait helpers.
+ */
+export type BrowserConditionFunction<TArg> = (arg: TArg) => boolean | Promise<boolean>;
+/**
+ * Shared input used by browser-condition polling helpers.
+ */
+export interface BrowserConditionOptions<TArg> {
+    /** Serializable argument forwarded into the browser-side condition function. */
+    arg: TArg;
+    /** Browser-executable predicate passed directly to `page.waitForFunction(...)`. */
+    pageFunction: BrowserConditionFunction<TArg>;
+    /** Timeout in milliseconds for the browser-side polling loop. */
+    timeoutMs: number;
+}
+/**
+ * Shared input used by the throwing browser-condition wait helper.
+ */
+export interface WaitForBrowserConditionOptions<TArg> extends BrowserConditionOptions<TArg> {
+    /** Error message thrown when the browser condition does not resolve in time. */
+    timeoutMessage: string;
+}
+/**
+ * Resolve whether one browser-side condition becomes true within the given timeout.
+ *
+ * @param page Playwright page that owns the current browser runtime.
+ * @param options Serializable browser predicate, argument, and timeout.
+ * @returns `true` when the predicate resolved before the timeout, otherwise `false`.
+ */
+export declare function tryWaitForBrowserCondition<TArg>(page: Page, options: BrowserConditionOptions<TArg>): Promise<boolean>;
+/**
+ * Wait for one browser-side condition and throw one caller-owned error on timeout.
+ *
+ * @param page Playwright page that owns the current browser runtime.
+ * @param options Serializable browser predicate, argument, timeout, and failure message.
+ */
+export declare function waitForBrowserCondition<TArg>(page: Page, options: WaitForBrowserConditionOptions<TArg>): Promise<void>;

package/types/packages/testing/playwright/src/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared Playwright helpers that can be reused across multiple apps belong here.
+ *
+ * Keep app-specific selectors, page objects, and one-off flows local to each
+ * `apps/*-e2e` project, and promote only reusable Playwright contracts into
+ * `@m4l/testing/playwright`.
+ */
+export * from './fixtures';
+export * from './helpers';
+export * from './installers';
+export type * from './types';