@zeyos/zx 4.1.0 → 4.2.0

package/CHANGELOG.md

@@ -8,6 +8,67 @@ and friends remain the complete record.
 
 ## Unreleased
 
+## 4.2.0 — 2026-08-26
+
+### Added
+
+- **Calendar scheduling.** `Calendar` adds agenda/day/week/month/year views, local-time collision
+  and spanning layout, range selection, now/loading states, and pointer plus keyboard move/resize.
+  Optimistic updates are the default with an idempotent version-guarded rollback; setting
+  `optimistic: false` leaves updates application-controlled. The optional ZeyOS adapter maps
+  expanded appointment occurrences and Unix seconds while recurrence, DAV, and persistence remain
+  outside core.
+- **Shared record views.** `TableView`, `CardView`, and `KanbanView` use one schema-friendly field,
+  data, sort, selection, loading, and versioned view-state contract. Tables can expose accessible
+  column ordering; cards support safe preview media and grouped responsive layouts; Kanban boards
+  add columns, swim lanes, WIP indicators, and cancelable pointer/keyboard moves in local or
+  application-controlled mode. The optional ZeyOS binding derives fields and projections from an
+  injected client without making validation, permissions, or routing core concerns. Its optional
+  saved-view registry persists named Table/Card/Kanban state by user, workspace, and resource
+  through an injected atomic transport; a compatibility adapter reuses ZeyOS's existing
+  `userfields` endpoints without trusting a client-supplied user identity.
+- **Aurora surfaces.** `Aurora` adds a dependency-free, one- to four-colour ambient-light layer
+  with six geometries, bounded palettes and intensity, CSS-only composition, and deterministic
+  reduced-motion, reduced-transparency, and forced-colour fallbacks. The documentation includes a
+  live application composition and an earlier-studies comparison page.
+
+### Changed
+
+- Liquid-glass recipes now distinguish compact floating overlays from reading-sized panels and
+  apply consistently to menus, pickers, tooltips, column controls, toasts, Launcher, Modal,
+  Dialog, and overlay Sheets. Docked Sheets remain opaque.
+- The documentation search is narrower at desktop widths, and Avatar now appears under Layout.
+- **Application identity now has one deliberate shape language.** `zeyosAppIcon()` and application
+  destinations in Launcher/AppSidebar use quiet circular chromatic lenses with crisp centred white
+  glyphs; `moduleChip()` remains a low-radius tile for entities, nested destinations, and records.
+  Per-icon blur and hover movement were removed, while rim/light/shadow feedback and material-mode
+  differences remain visible without changing geometry.
+
+### Fixed
+
+- AppIcon now preserves native button/link semantics when enhancing an interactive target, forwards
+  ZeyOS badge and selection state, ignores hover on disabled destinations, and uses forced-colour
+  system values for badges.
+- The AppSidebar example no longer replaces AppIcon's internal surface, so collapsed rails retain
+  the same material, focus, selection, and accessibility behavior as expanded navigation.
+
+## 4.1.1 — 2026-08-25
+
+### Changed
+
+- **Material recipes are visibly distinct.** Flat, Glass, and Deep glass now resolve shared
+  semantic tokens consumed by application icons, buttons, raised cards, and transient messages;
+  reduced-transparency and forced-colour environments retain opaque accessible fallbacks.
+- **Theme Studio documents the material system.** Its component showcase now includes the shared
+  AppIcon and raised-surface treatments, and explains which component families consume them.
+- **Application identity is more consistent.** ZeyOS AppIcons use centred white glyphs, a tighter
+  corner radius, CSS-only depth, and explicit hover and focus feedback across module colours.
+
+### Fixed
+
+- AppIcons without badges no longer append a visible `null` text node, preserving exact glyph
+  centring and clean accessible output.
+
 ## 4.1.0 — 2026-08-25
 
 ### Added

package/DESIGN-SYSTEM.md

@@ -34,6 +34,8 @@ and navigation remain application-owned.
 | Dialogs, sheets, dropdowns, context menus, tooltips, messages | Covered | Consolidate duplicate menu behavior before building account/launcher surfaces. |
 | Tabs, panels, toolbar, breadcrumbs, stepper, split view, dock | Covered | Compose layouts; do not let navigation components own routes. |
 | Sorting, selection, dynamic/local filtering, pagination, trees/finder | Covered | `Filter` authors typed nested expressions; `DataFilter` executes simple local predicates. Backend query compilation stays in adapters. |
+| Operational calendars and scheduling | Covered | `Calendar` provides agenda/day/week/month/year views, local collision/spanning layout, selection, and configurable optimistic pointer/keyboard edits. The host owns loading, persistence, permissions, recurrence rules, and DAV. |
+| Record table, card, and Kanban views | Covered by one shared contract | `TableView`, `CardView`, and `KanbanView` share schema fields, records, sort, selection, field controls, loading, and versioned state. Core remains persistence-neutral; the optional ZeyOS registry coordinates named layouts through an injected server transport. The host still owns permissions, server validation, and rollback. |
 | Editable billing/transaction rows | Covered at generic-grid level | `Grid.BillingItems()` composes single-click typed currency/unit editors, flat hierarchy, same-parent row movement, and column visibility over `Table`. Tax, subtotal, posting, rounding, and persistence stay domain code. |
 | Global launcher/search | Covered | `Launcher` combines an application grid, current/pinned state, recent records, and abortable grouped sources. The optional ZeyOS adapter maps the complete 29-app shell catalogue while the host retains permissions, icons, and routing. |
 | Account/profile/preferences menu | Covered at presentation level | `Avatar` and `AccountMenu` provide identity and action UI. The host supplies permitted actions and owns preferences, authentication, and logout. |
@@ -57,6 +59,8 @@ a Zx component or a documented composition are not counted as gaps.
 | ZeyOS behavior | Source evidence | Xenon/Zx coverage |
 | --- | --- | --- |
 | Dynamic search/filter authoring and saved filter controls | [`UI.newSearch`](../zeyos/ext/global.orig/4-ui.orig.js#L3378) and [`UI.newContainerFilters`](../zeyos/ext/global.orig/4-ui.orig.js#L7723) | `Filter` supplies a typed/versioned AST editor; `DataFilter` remains the lightweight local-row helper. A compiler and persistence service are intentionally not core. |
+| Agenda/day/week/month/year scheduling | [`calendar.orig.js`](../zeyos/ext/mod/calendar.orig.js#L61) | `Calendar` covers timed collisions, spanning lanes, windowed range events, activity year view, selection, now state, and pointer/keyboard move/resize. `zeyosCalendar()` maps expanded appointment rows and Unix seconds without importing recurrence, DAV, routing, or permissions into core. |
+| Record table/card collections and reusable view state | [`_newCrdLstTbl`](../zeyos/ext/global.orig/4-ui.orig.js#L4457), [`newCrd`](../zeyos/ext/global.orig/4-ui.orig.js#L4649), and [`newTbl`](../zeyos/ext/global.orig/4-ui.orig.js#L4782) | `TableView`, `CardView`, and the additive `KanbanView` consume the same field descriptors and JSON-safe layout state. `buildZeyosViewConfig()` derives them from the runtime schema; `SavedViewRegistry` adds exact user/workspace/resource scoping and can bridge the existing `userfields` endpoints. Neither imports the client into core. |
 | Editable transaction rows and row movement | [`_newTblAddColEdit`](../zeyos/ext/global.orig/4-ui.orig.js#L5613) and [`newTblItems`](../zeyos/ext/global.orig/4-ui.orig.js#L6070) | `Table`/`Grid.BillingItems()` cover typed editing, currencies/units, hierarchy, single-click entry, same-parent drag/keyboard reorder, and show/hide columns. |
 | Entity selection, priority, status, and permission choices | [`newSelEntity`](../zeyos/ext/global.orig/4-ui.orig.js#L3296), [`newSelPriority`](../zeyos/ext/global.orig/4-ui.orig.js#L3101), and the surrounding Select family | `Select.entity()`, `.priority()`, `.status()`, and `.permission()` cover the interaction contract; the ZeyOS adapter owns schemas and localized catalogues. |
 | Application launcher and module/entity identity | [`newExpLst`](../zeyos/ext/global.orig/4-ui.orig.js#L4355) and entity/module item builders through line 4457 | `Launcher`, `AppIcon`, and the optional ZeyOS adapter cover the full app catalogue, current/pinned state, recent records, grouped abortable search, forks/weblets, and injected routing. |
@@ -70,7 +74,6 @@ a Zx component or a documented composition are not counted as gaps.
 | P0 | **EntityRef** | ZeyOS has a large family of linked/static entity presentations with subtitle, owner/group/assignee context, fork, and record actions: [`newLinkEntity*`](../zeyos/ext/global.orig/4-ui.orig.js#L225) and [`newEntityStatic`/`newEntity*`](../zeyos/ext/global.orig/4-ui.orig.js#L8262). A generic `EntityRef` should own icon/title/subtitle/metadata/link/action semantics; ZeyOS routing, permissions, and context menus remain injected. `Card` is too large for dense table/feed rows. |
 | P0 | **FileItem / FileList** | Existing-file, temporary-file, waiting/progress, MIME, size, and download rows recur in [`newFile`, `newFileTemp`, and `newFileWait`](../zeyos/ext/global.orig/4-ui.orig.js#L8158). `FieldUpload` owns selection/upload but not durable file presentation. Core should render file identity/state/actions; transport, authorization, preview, and download URLs stay with the host. |
 | P0 | **ActivityList / ActivityItem** | [`newFeed`](../zeyos/ext/global.orig/4-ui.orig.js#L8704) combines chronological records, comments, attachments, likes, and incremental updates. Core should own an accessible chronological list, grouping, loading/empty state, and action slots. Posting, reactions, channels, permissions, and persistence remain application code. |
-| P1 | **Scheduler** | The current calendar implements agenda/day/week/month/year views, timed and spanning items, keyboard/routing affordances, and dense collision layout in [`calendar.orig.js`](../zeyos/ext/mod/calendar.orig.js#L61). A generic scheduler is a real core gap, but should be a separate workstream with interval-layout and accessibility invariants; recurrence, DAV, permissions, and routes are adapters/application logic. |
 | P1 | **FacetList** | Counted activity/status/tag/entity side filters appear in [`newNavActivityStatus`](../zeyos/ext/global.orig/4-ui.orig.js#L3967), `newNavTag`, and `newNavEntity`. `Filter` is an expression author, not a compact persistent facet navigator. Core should own selection/count/collapse/loading behavior; query mapping stays injected. |
 | P1 | **EditorHost** | ZeyOS uses plain/Markdown/contenteditable/iframe editors through [`newEditor`](../zeyos/ext/global.orig/4-ui.orig.js#L1607) and `newFrameEditor`. Like `Chart`, core should provide labels, toolbar/action slots, value/lifecycle, dirty/read-only/error states, and an injected engine adapter. Sanitization and document/media policy must not be implicit core behavior. |
 | P1 | **ColorPicker** | The reusable swatch picker is [`newCl`](../zeyos/ext/global.orig/4-ui.orig.js#L3753). A dependency-free accessible swatch/custom-color picker belongs in core and would also serve the Theme Studio. |
@@ -94,7 +97,7 @@ a Zx component or a documented composition are not counted as gaps.
 ### Deliberately application-owned
 
 Routing/history, authentication/session/logout, authorization, server transport/caching, saved-view
-storage, audit policy, transaction tax/discount/subtotal/posting formulas, optimistic writes/undo,
+storage, audit policy, transaction tax/discount/subtotal/posting formulas, server reconciliation and undo history,
 calendar recurrence/DAV synchronization, rich-text sanitization, and activity actions are not
 design-system responsibilities. Moving them into Zx would reproduce ZeyOS application logic inside
 the library and make Xenon less reusable.
@@ -127,10 +130,37 @@ currency, line-total, and hierarchy schema while retaining Table's editing contr
 follow-ups, deliberately separate from this generic preset:
 
 - summary/footer rows and grouped subtotals;
-- column reorder and user-persisted column state;
+- persistence connectors for versioned view state (column order and visibility are now component capabilities);
 - product-specific invoice/transaction presets with tax, discount, rounding, and formula golden tests;
 - server persistence, optimistic rejection, and undo owned by the application/controller layer.
 
+## Record-view contract
+
+`RecordView` is the presentation-neutral base for `TableView`, `CardView`, and `KanbanView`.
+Stable field IDs allow a runtime ZeyOS schema to drive every presentation, while per-view properties
+add table widths, card previews, or board grouping without changing how values, sorting, selection,
+and field visibility work. Each view returns a versioned JSON-safe configuration through
+`getViewState()`; record data and rendered Nodes are deliberately excluded.
+
+The optional ZeyOS adapter builds the shared descriptors and server projection, including hidden
+title, media, column, and swim-lane fields. It can page any concrete record view through an injected
+client. Preference storage remains outside Zx, and Kanban moves are cancelable: local mode updates a
+record clone, while external mode waits for the application to supply accepted server state.
+
+## Calendar contract
+
+`Calendar` normalizes arbitrary event records into stable IDs, copied local Dates, optional colour
+and location, and per-event edit policies. Agenda, day, week, month, and year are presentations of
+the same event set. The interval helpers operate on calendar days rather than fixed 24-hour spans,
+so DST does not move a date; timed overlaps get deterministic columns and all-day/multi-day items
+get non-overlapping clipped lanes.
+
+Move and resize proposals are cancelable and keyboard-equivalent. Optimistic mode is the default
+and provides a version-guarded `revert()` that cannot overwrite a newer local edit. Controlled mode
+emits the same proposal without local mutation. The optional ZeyOS adapter maps expanded
+appointment occurrences and Unix seconds while the application retains transport, recurrence/DAV,
+permissions, routing, validation, and conflict handling.
+
 ## Chart-engine candidates
 
 Chart.js was selected for the first adapter. It is pinned at 4.5.1 as a development dependency for

package/README.md

@@ -98,7 +98,6 @@ ZeyOS binding — see `src/zeyos/modules.js`.
 | `CheckButton` | Two-state pressed button with optional state-specific labels. |
 | `Toggle` | Native-button switch with a separate submitted value. |
 | `Search` | Search input with debounced input, submit, and clear events. |
-| `Launcher` | Cmd/Ctrl+K application and record launcher with ranked local items and abortable grouped sources. |
 | `Select` | APG combobox with local or async filtering, pinned items, priority/status/permission presets, and an optional ZeyOS entity picker. |
 | `Checklist` | Searchable checkbox group with optional async loading. |
 | `TagPicker` | Multi-select combobox that keeps its selection as removable tags. |
@@ -126,16 +125,18 @@ ZeyOS binding — see `src/zeyos/modules.js`.
 | `MenuButton` | APG menu button built on `Dropdown`. |
 | `ContextMenu` | APG right-click menu for a region or, via `selector`, per row. |
 | `Tooltip`, `tooltip()`, `describe()` | Hover/focus description bubble anchored with `position()`. |
-| `Avatar` | Fixed-size user image with initials fallback and optional presence. |
-| `AccountMenu` | Identity trigger and grouped account actions over `MenuButton`. |
 
 ### Data
 
 | API | Description |
 | --- | --- |
 | `Table` | Sortable/selectable table with typed transaction columns, flat-data hierarchy/treegrid projection, and opt-in cell/row editing. |
+| `TableView` | Record-oriented Table composition with shared fields, portable state, column visibility/order, sorting, and selection. |
+| `CardView` | Responsive record cards with configurable fields, safe preview media, grouping, actions, sorting, and selection. |
+| `KanbanView` | Record board with configurable columns, swim lanes, WIP guidance, and cancelable pointer/keyboard movement. |
 | `Grid`, `Grid.BillingItems()` | Table-compatible preset surface with editable currencies, units, totals, and sub-items. |
 | `Chart`, `ChartJsAdapter` | Accessible engine-neutral chart host and explicitly injected Chart.js adapter. |
+| `Calendar` | Agenda/day/week/month/year scheduling with timed collisions, spanning events, range selection, and configurable optimistic drag/resize editing. |
 | `DataFilter` | Declarative select, text, and custom filters for client-side row sets. |
 | `TreeView` | APG tree with lazy children, filtering, and tri-state checkboxes. |
 | `Finder` | Miller-columns hierarchy browser with an optional preview pane. |
@@ -157,8 +158,13 @@ ZeyOS binding — see `src/zeyos/modules.js`.
 
 | API | Description |
 | --- | --- |
+| `AccountMenu` | Identity trigger and grouped account actions over `MenuButton`. |
+| `AppIcon`, `zeyosAppIcon()`, `moduleChip()` | White-glyph identity surface: a generic tile core, circular ZeyOS application presets, compact module/entity tiles, module colour, badges, selection, and CSS-first material. |
+| `Avatar` | Fixed-size user image with initials fallback and optional presence. |
 | `Groupbox` | Collapsible section backed by native `<details>`. |
 | `Card` | Semantic content/record surface with media, native title link, actions, and footer. |
+| `Aurora` | One- to four-colour ambient canvas light; chrome, raised content, and overlays respond through shared material tokens. |
+| `Launcher` | Cmd/Ctrl+K application and record launcher with ranked local items and abortable grouped sources. |
 | `Panel` | Framed, optionally collapsible section with a footer. |
 | `MasterPanel` | Full-height application panel with fixed header actions and footer. |
 | `Tabbox` | APG tabs in four appearances, with lazy content, closing, badges, and disabled states. |
@@ -180,8 +186,8 @@ ZeyOS binding — see `src/zeyos/modules.js`.
 
 Use `@zeyos/client` for ZeyOS authentication, transport, generated resource operations, and runtime
 schema introspection. Zx adds `zx-zeyos`, a schema-driven layer above that client: inject an existing
-client into `connect`, `zeyosTable`, `zeyosForm`, or `zeyosSelect` to generate typed tables, forms,
-and async entity selectors from real resource metadata.
+client into `connect`, `zeyosTable`, `zeyosView`, `zeyosForm`, or `zeyosSelect` to generate typed
+record views, tables, forms, and async entity selectors from real resource metadata.
 
 ```js
 import { createZeyosClient } from '@zeyos/client';
@@ -198,6 +204,12 @@ const editor = zeyosForm(client, 'transactions', {
 });
 ```
 
+`zeyosView()` can coordinate named Table, Card, and Kanban configurations through
+`SavedViewRegistry`. Saved documents are isolated by exact `userId + workspaceId + resource`, keep
+records and selection out of persistence, and use an injected atomic transport. Existing ZeyOS
+installations can adapt their authenticated `fields`, `fields_save`, and `fields_remove` endpoints
+with `createLegacySavedViewTransport()`; the client-provided user id is never sent as authority.
+
 The injection design means Zx never imports or bundles `@zeyos/client`. The optional binding ships
 separately as `dist/zx-zeyos.esm.js` and is not part of the root `src/index.js` API. See the
 schema-driven `website/layouts/zeyos-invoices.layout.js` for list, filter, sort, edit, and create wiring.

package/dist/types/components/app-icon/app-icon.d.ts

@@ -28,6 +28,10 @@ export type AppIconOptions = {
      * Whether the icon represents the active application.
      */
     selected?: boolean;
+    /**
+     * Identity vessel geometry.
+     */
+    shape?: 'tile' | 'circle';
     /**
      * CSS-first glass treatment.
      */
@@ -46,16 +50,18 @@ export type AppIconOptions = {
  * @property {string|null} [label=null] Accessible image label; null makes the icon decorative.
  * @property {string|number|null} [badge=null] Optional corner badge.
  * @property {boolean} [selected=false] Whether the icon represents the active application.
+ * @property {'tile'|'circle'} [shape='tile'] Identity vessel geometry.
  * @property {false|'subtle'|'strong'} [glass='subtle'] CSS-first glass treatment.
  * @property {string|string[]} [class] Additional class names.
  */
 /**
- * Stable application-identity tile with progressive CSS glass treatment.
+ * Stable application-identity surface with progressive CSS glass treatment.
  * @extends {Component<AppIconOptions>}
  */
 export declare class AppIcon extends Component<AppIconOptions> {
     _createdRoot: boolean;
     _snapshot: import("../../core/dom.js").TargetSnapshot;
+    _interactiveRoot: boolean;
     _state: {
         icon?: string | Node | (() => string | Node) | null;
         color?: string | null;
@@ -64,6 +70,7 @@ export declare class AppIcon extends Component<AppIconOptions> {
         label?: string | null;
         badge?: string | number | null;
         selected?: boolean;
+        shape?: 'tile' | 'circle';
         glass?: false | 'subtle' | 'strong';
         class?: string | string[];
     };

package/dist/types/components/aurora/aurora.d.ts

@@ -0,0 +1,72 @@
+import { Component } from '../../core/component.js';
+export type AuroraOptions = {
+    /**
+     * Geometry of the ambient light field.
+     */
+    preset?: 'source' | 'confluence' | 'horizon' | 'diagonal' | 'edge' | 'curtain';
+    /**
+     * Zero to four concrete CSS colours. An empty list uses semantic
+     * Zx colours; shorter palettes repeat across the four gradient fields.
+     */
+    colors?: string[];
+    /**
+     * Strength of the light field.
+     */
+    intensity?: 'subtle' | 'balanced' | 'vivid';
+};
+/**
+ * @typedef {Object} AuroraOptions
+ * @property {'source'|'confluence'|'horizon'|'diagonal'|'edge'|'curtain'} [preset='source']
+ *   Geometry of the ambient light field.
+ * @property {string[]} [colors=[]] Zero to four concrete CSS colours. An empty list uses semantic
+ *   Zx colours; shorter palettes repeat across the four gradient fields.
+ * @property {'subtle'|'balanced'|'vivid'} [intensity='subtle'] Strength of the light field.
+ */
+/**
+ * Decorative multicolour ambient light for an existing application surface.
+ * Aurora owns no application content or interaction: it enhances the target in place and renders
+ * its pointer-transparent light field behind the target's existing children.
+ * @extends {Component<AuroraOptions>}
+ */
+export declare class Aurora extends Component<AuroraOptions> {
+    _createdRoot: boolean;
+    _original: import("../../core/dom.js").TargetSnapshot;
+    _cleaned: boolean;
+    _initialColors: {
+        property: string;
+        value: string;
+        priority: string;
+    }[];
+    _colors: any[] | string[];
+    static cssName: string;
+    /** @type {Readonly<AuroraOptions>} */
+    static defaults: Readonly<AuroraOptions>;
+    /**
+     * Creates or enhances an Aurora surface.
+     * @param {Element|string|null} [target=null] Existing surface, selector, or null.
+     * @param {AuroraOptions} [options={}] Aurora options.
+     */
+    constructor(target?: Element | string | null, options?: AuroraOptions);
+    /** @returns {HTMLElement} */
+    render(): HTMLElement;
+    /** Sets the light-field geometry without replacing surface content. @param {string} preset @returns {this} */
+    setPreset(preset: string): this;
+    /** Sets zero to four concrete colours without replacing surface content. @param {string[]|null} colors @returns {this} */
+    setColors(colors: string[] | null): this;
+    /** Sets the light-field strength without replacing surface content. @param {string} intensity @returns {this} */
+    setIntensity(intensity: string): this;
+    /** Restores an enhanced target exactly, or removes an owned surface. @returns {void} */
+    destroy(): void;
+}
+/** @param {unknown} value @returns {'source'|'confluence'|'horizon'|'diagonal'|'edge'|'curtain'} */
+export declare function normalizeAuroraPreset(value: unknown): 'source' | 'confluence' | 'horizon' | 'diagonal' | 'edge' | 'curtain';
+/** @param {unknown} value @returns {'subtle'|'balanced'|'vivid'} */
+export declare function normalizeAuroraIntensity(value: unknown): 'subtle' | 'balanced' | 'vivid';
+/** @param {unknown} value @returns {string[]} */
+export declare function normalizeAuroraColors(value: unknown): string[];
+/**
+ * Repeats a one-to-three-colour palette deterministically across four gradient fields.
+ * @param {string[]} colors
+ * @returns {string[]}
+ */
+export declare function expandAuroraColors(colors: string[]): string[];

package/dist/types/components/calendar/calendar-model.d.ts

@@ -0,0 +1,202 @@
+/** @typedef {'agenda'|'day'|'week'|'month'|'year'} CalendarView */
+/** @typedef {string|((record: Record<string, any>) => unknown)} CalendarReader */
+export type CalendarView = 'agenda' | 'day' | 'week' | 'month' | 'year';
+export type CalendarReader = string | ((record: Record<string, any>) => unknown);
+export type CalendarEvent = {
+    /**
+     * Stable event identifier.
+     */
+    id: string | number;
+    /**
+     * Visible event title.
+     */
+    title: string;
+    /**
+     * Local start date and time.
+     */
+    start: Date;
+    /**
+     * Local end date and time; equal to start for an instant event.
+     */
+    end: Date;
+    /**
+     * Whether the event belongs in an all-day lane.
+     */
+    allDay: boolean;
+    /**
+     * Optional application-supplied CSS colour.
+     */
+    color: string | null;
+    /**
+     * Optional location.
+     */
+    location: string;
+    /**
+     * Per-event move policy, or null to inherit.
+     */
+    editable: boolean | null;
+    /**
+     * Per-event resize policy, or null to inherit.
+     */
+    durationEditable: boolean | null;
+    /**
+     * Original application record.
+     */
+    data: Record<string, any>;
+};
+export type CalendarNormalizeOptions = {
+    /**
+     * ID reader.
+     */
+    eventId?: CalendarReader;
+    /**
+     * Title reader.
+     */
+    eventTitle?: CalendarReader;
+    /**
+     * Start reader.
+     */
+    eventStart?: CalendarReader;
+    /**
+     * End reader.
+     */
+    eventEnd?: CalendarReader;
+    /**
+     * All-day reader.
+     */
+    eventAllDay?: CalendarReader;
+    /**
+     * Colour reader.
+     */
+    eventColor?: CalendarReader;
+    /**
+     * Location reader.
+     */
+    eventLocation?: CalendarReader;
+    /**
+     * Move-policy reader.
+     */
+    eventEditable?: CalendarReader;
+    /**
+     * Resize-policy reader.
+     */
+    eventDurationEditable?: CalendarReader;
+    /**
+     * Unit used for numeric dates.
+     */
+    dateUnit?: 'milliseconds' | 'seconds';
+};
+/**
+ * @typedef {Object} CalendarEvent
+ * @property {string|number} id Stable event identifier.
+ * @property {string} title Visible event title.
+ * @property {Date} start Local start date and time.
+ * @property {Date} end Local end date and time; equal to start for an instant event.
+ * @property {boolean} allDay Whether the event belongs in an all-day lane.
+ * @property {string|null} color Optional application-supplied CSS colour.
+ * @property {string} location Optional location.
+ * @property {boolean|null} editable Per-event move policy, or null to inherit.
+ * @property {boolean|null} durationEditable Per-event resize policy, or null to inherit.
+ * @property {Record<string, any>} data Original application record.
+ */
+/**
+ * @typedef {Object} CalendarNormalizeOptions
+ * @property {CalendarReader} [eventId='id'] ID reader.
+ * @property {CalendarReader} [eventTitle='title'] Title reader.
+ * @property {CalendarReader} [eventStart='start'] Start reader.
+ * @property {CalendarReader} [eventEnd='end'] End reader.
+ * @property {CalendarReader} [eventAllDay='allDay'] All-day reader.
+ * @property {CalendarReader} [eventColor='color'] Colour reader.
+ * @property {CalendarReader} [eventLocation='location'] Location reader.
+ * @property {CalendarReader} [eventEditable='editable'] Move-policy reader.
+ * @property {CalendarReader} [eventDurationEditable='durationEditable'] Resize-policy reader.
+ * @property {'milliseconds'|'seconds'} [dateUnit='milliseconds'] Unit used for numeric dates.
+ */
+/** @type {readonly CalendarView[]} */
+export declare const CALENDAR_VIEWS: readonly CalendarView[];
+/**
+ * Returns the complete local-date window rendered by a view. The end is exclusive.
+ * @param {CalendarView} view View name.
+ * @param {Date} anchor Date inside the requested period.
+ * @param {{weekStart?: number, agendaDays?: number}} [options={}] Range options.
+ * @returns {{start: Date, end: Date}}
+ */
+export declare function calendarRange(view: CalendarView, anchor: Date, options?: {
+    weekStart?: number;
+    agendaDays?: number;
+}): {
+    start: Date;
+    end: Date;
+};
+/**
+ * Normalizes caller records atomically into the Calendar event contract.
+ * @param {Record<string, any>[]} records Source records.
+ * @param {CalendarNormalizeOptions} [options={}] Reader and date options.
+ * @returns {CalendarEvent[]}
+ */
+export declare function normalizeCalendarEvents(records: Record<string, any>[], options?: CalendarNormalizeOptions): CalendarEvent[];
+/**
+ * Returns defensive Date copies while retaining the caller's opaque source record.
+ * @param {CalendarEvent} event Event to clone.
+ * @returns {CalendarEvent}
+ */
+export declare function cloneCalendarEvent(event: CalendarEvent): CalendarEvent;
+/**
+ * Lays out timed events for one day into collision columns.
+ * @param {CalendarEvent[]} events Normalized events.
+ * @param {Date} day Local day.
+ * @param {{minMinutes?: number, maxMinutes?: number, minimumMinutes?: number}} [options={}] Grid bounds.
+ * @returns {Array<{event: CalendarEvent, start: Date, end: Date, startMinutes: number, endMinutes: number, column: number, columns: number}>}
+ */
+export declare function layoutTimedCalendarEvents(events: CalendarEvent[], day: Date, options?: {
+    minMinutes?: number;
+    maxMinutes?: number;
+    minimumMinutes?: number;
+}): Array<{
+    event: CalendarEvent;
+    start: Date;
+    end: Date;
+    startMinutes: number;
+    endMinutes: number;
+    column: number;
+    columns: number;
+}>;
+/**
+ * Assigns clipped all-day/multi-day spans to non-overlapping lanes in a period.
+ * @param {CalendarEvent[]} events Normalized events.
+ * @param {Date} rangeStart First visible local day.
+ * @param {number} days Number of visible days.
+ * @returns {Array<{event: CalendarEvent, start: number, end: number, lane: number}>}
+ */
+export declare function layoutCalendarSpans(events: CalendarEvent[], rangeStart: Date, days: number): Array<{
+    event: CalendarEvent;
+    start: number;
+    end: number;
+    lane: number;
+}>;
+/**
+ * Creates an immutable local-time move/resize proposal.
+ * @param {CalendarEvent} event Source event.
+ * @param {{days?: number, minutes?: number, endDays?: number, endMinutes?: number}} delta Local delta.
+ * @returns {CalendarEvent}
+ */
+export declare function shiftCalendarEvent(event: CalendarEvent, delta?: {
+    days?: number;
+    minutes?: number;
+    endDays?: number;
+    endMinutes?: number;
+}): CalendarEvent;
+/** @param {Date} value @returns {Date} */
+export declare function startOfCalendarDay(value: Date): Date;
+/** @param {Date} value @param {number} amount @returns {Date} */
+export declare function addCalendarDays(value: Date, amount: number): Date;
+/** @param {Date} value @param {number} weekStart @returns {Date} */
+export declare function startOfCalendarWeek(value: Date, weekStart?: number): Date;
+/** @param {Date} start @param {Date} end @returns {number} */
+export declare function calendarDayDifference(start: Date, end: Date): number;
+/** @param {Date} value @returns {string} */
+export declare function calendarDayKey(value: Date): string;
+/** @param {CalendarEvent} event @returns {boolean} */
+export declare function calendarEventSpansDays(event: CalendarEvent): boolean;
+/** @param {CalendarEvent} event @param {Date} start @param {Date} end @returns {boolean} */
+export declare function calendarEventIntersects(event: CalendarEvent, start: Date, end: Date): boolean;