slotlock 0.7.0 → 0.9.0

package/booking-rules.d.ts

@@ -1,3 +1,4 @@
+import { type SlotlockRankedException } from './hours.js';
 import type { Interval, WeeklyAvailabilityRule } from './types.js';
 /**
  * A resource's booking rules: what a booking made through Slotlock (hold, reservation, agent event)
@@ -24,10 +25,46 @@ export interface SlotlockBookingRules {
      */
     bufferBeforeMinutes?: number;
     /**
-     * Minutes kept free after each booking made under the rule, as its trailing buffer: 0-1,440.
-     * Bookings made before the rule, or imported, keep what they have.
+     * Minutes kept free after each booking made under the rule, as its trailing buffer: 0-10,080 (a
+     * week, for a vehicle's service after a long hire). Bookings made before the rule, or imported,
+     * keep what they have.
      */
     turnaroundMinutes?: number;
+    /** A booking lasts at least this many minutes: 1-525,600 (a year). */
+    minDurationMinutes?: number;
+    /** A booking lasts at most this many minutes: 1-525,600. */
+    maxDurationMinutes?: number;
+    /** A booking lasts exactly one of these many minutes: 1-20 lengths, each 1-525,600. */
+    allowedDurations?: number[];
+    /** The length a search offers when it is asked for none: 1-525,600, and allowed by the others. */
+    defaultDurationMinutes?: number;
+    /**
+     * A booking from one local day to another (a hire) starts inside one of these windows of the day,
+     * in the resource's time zone: 1-4 windows. A booking within one day is not held to them.
+     */
+    pickupTimes?: SlotlockDayWindow[];
+    /** Such a booking ends inside one of these windows of the day, alike. */
+    returnTimes?: SlotlockDayWindow[];
+    /**
+     * How the bookable hours hold a booking from one local day to another (a hire): `whole`, every
+     * minute of it inside them; `ends`, only its start and end, the resource being out between. A
+     * booking within one day lies inside them either way. By default `ends` where `pickupTimes` or
+     * `returnTimes` are given, else `whole`. Writes are held to it under `enforceHours`; searches
+     * (slots and ranges) follow it always.
+     */
+    hoursApply?: SlotlockHoursApply;
+    /**
+     * A booking is cancelled at least this many minutes before it starts (RFC 0004 B5): 0-525,600.
+     * Later, cancelling it is refused (`cancel_cutoff`) unless an admin overrides with a reason.
+     */
+    cancelCutoffMinutes?: number;
+    /** A booking is moved at least this many minutes before it starts, alike (`reschedule_cutoff`). */
+    rescheduleCutoffMinutes?: number;
+    /**
+     * What a cancellation costs, recorded on it for the integrator to charge: Slotlock never moves
+     * money. With `withinMinutes`, only a cancellation that late before the start.
+     */
+    cancellationFee?: SlotlockCancellationFee;
     /** A booking lies inside the resource's bookable hours. */
     enforceHours?: boolean;
     /**
@@ -43,8 +80,20 @@ export interface SlotlockBookingRules {
      */
     requireCertain?: boolean;
 }
+/** A cancellation's fee: an amount in the currency's minor unit (cents), ISO 4217 currency. */
+export interface SlotlockCancellationFee {
+    amountMinor: number;
+    currency: string;
+    /** Only a cancellation this many minutes or fewer before the start: 0-525,600. */
+    withinMinutes?: number;
+}
+/** A window of a day: minutes after local midnight, and how long (it may run past midnight). */
+export interface SlotlockDayWindow {
+    startMinutes: number;
+    durationMinutes: number;
+}
 /** Which rule a write broke, as its refusal names it. */
-export type SlotlockBookingRule = 'min_notice' | 'max_advance' | 'slot_step' | 'outside_hours' | 'uncertain';
+export type SlotlockBookingRule = 'min_notice' | 'max_advance' | 'slot_step' | 'outside_hours' | 'uncertain' | 'min_duration' | 'max_duration' | 'duration_not_allowed' | 'pickup_time' | 'return_time' | 'cancel_cutoff' | 'reschedule_cutoff';
 /** Each numeric rule's least and greatest value. */
 export declare const SLOTLOCK_BOOKING_RULE_LIMITS: Readonly<{
     readonly minNoticeMinutes: readonly [0, 525600];
@@ -54,7 +103,29 @@ export declare const SLOTLOCK_BOOKING_RULE_LIMITS: Readonly<{
     readonly bufferBeforeMinutes: readonly [0, number];
     readonly turnaroundMinutes: readonly [0, number];
     readonly checkInMinutes: readonly [1, number];
+    readonly minDurationMinutes: readonly [1, 525600];
+    readonly maxDurationMinutes: readonly [1, 525600];
+    readonly defaultDurationMinutes: readonly [1, 525600];
+    readonly cancelCutoffMinutes: readonly [0, 525600];
+    readonly rescheduleCutoffMinutes: readonly [0, 525600];
 }>;
+/** Lengths `allowedDurations` may list. */
+export declare const SLOTLOCK_MAX_ALLOWED_DURATIONS = 20;
+/** Windows `pickupTimes` and `returnTimes` may each hold. */
+export declare const SLOTLOCK_MAX_DAY_WINDOWS = 4;
+/** How the hours hold a hire (`hoursApply`). */
+export type SlotlockHoursApply = 'whole' | 'ends';
+/** The `hoursApply` a resource's rules mean: as given, else `ends` with pick-up or return times. */
+export declare function hoursApplyOf(rules: SlotlockBookingRules | undefined): SlotlockHoursApply;
+/**
+ * The cutoff rule a cancellation or move of a booking starting at `start`, made at `now`, breaks,
+ * or null (RFC 0004 B5).
+ */
+export declare function cutoffRuleBroken(rules: SlotlockBookingRules | undefined, kind: 'cancel' | 'reschedule', start: Date, now: Date): 'cancel_cutoff' | 'reschedule_cutoff' | null;
+/** The fee a cancellation of a booking starting at `start`, made at `now`, records, or null. */
+export declare function cancellationFeeDue(rules: SlotlockBookingRules | undefined, start: Date, now: Date): SlotlockCancellationFee | null;
+/** The duration rule a booking of `minutes` breaks, or null. */
+export declare function durationRuleBroken(rules: SlotlockBookingRules | undefined, minutes: number): 'min_duration' | 'max_duration' | 'duration_not_allowed' | null;
 /** Booking rules from untrusted input, or a TypeError naming the field that is wrong. */
 export declare function parseBookingRules(value: unknown): SlotlockBookingRules;
 /**
@@ -83,13 +154,27 @@ export declare function bookingBufferBeforeMs(rules: SlotlockBookingRules | unde
  */
 export declare function nextStepStart(from: Date, stepMinutes: number, timezone: string, offsetMinutes?: number): Date;
 /**
- * The rule a booking of `interval` made at `now` breaks, or null. `hours` (the resource's own, or
- * the default) are read only when enforced.
+ * Whether a booking runs from one local day into another (a hire): its last moment falls on a later
+ * local day than its start. One that ends at midnight stays on its day.
+ */
+export declare function isMultiDay(interval: Interval, timezone: string): boolean;
+/**
+ * Whether `instant` lies in one of the windows of its local day: `[start, start + length)`, or with
+ * `closed` (a return) up to and including the window's end.
+ */
+export declare function withinDayWindows(instant: Date, windows: readonly SlotlockDayWindow[], timezone: string, closed?: boolean): boolean;
+/**
+ * The rule a booking of `interval` made at `now` breaks, or null. `hours` (the resource's own, else
+ * inherited, else the default) and `exceptions` are read only when enforced. A hire (a booking from
+ * one local day to another) under `pickupTimes` or `returnTimes` starts and ends in them, and under
+ * `enforceHours` lies inside the hours as `hoursApply` says: wholly, or only at its start and end
+ * (the resource being out between).
  */
 export declare function bookingRuleBroken(params: {
     rules: SlotlockBookingRules | undefined;
     timezone: string;
     hours: readonly WeeklyAvailabilityRule[];
+    exceptions?: readonly SlotlockRankedException[];
     interval: Interval;
     now: Date;
 }): SlotlockBookingRule | null;
@@ -114,6 +199,8 @@ export declare function bookingSearch(params: {
     window: Interval;
     now: Date;
     bufferAfterMs?: number;
+    /** The length searched for: a length the duration rules refuse finds nothing. */
+    durationMs?: number;
 }): SlotlockBookingSearch | null;
 /** The time a search must read as free or busy: its window widened by a slot's buffers. */
 export declare function bookingSearchReach(search: SlotlockBookingSearch): Interval;

package/booking-rules.js

@@ -1,4 +1,4 @@
-import { expandRules } from './rules.js';
+import { coveredByOpenWindows, openWindows } from './hours.js';
 import { zonedOffsetMinutes } from './timezone.js';
 const MINUTE_MS = 60_000;
 const DAY_MINUTES = 24 * 60;
@@ -9,10 +9,131 @@ export const SLOTLOCK_BOOKING_RULE_LIMITS = Object.freeze({
     slotStepMinutes: [1, DAY_MINUTES],
     stepOffsetMinutes: [0, DAY_MINUTES - 1],
     bufferBeforeMinutes: [0, DAY_MINUTES],
-    turnaroundMinutes: [0, DAY_MINUTES],
+    turnaroundMinutes: [0, 7 * DAY_MINUTES],
     checkInMinutes: [1, DAY_MINUTES],
+    minDurationMinutes: [1, 525_600],
+    maxDurationMinutes: [1, 525_600],
+    defaultDurationMinutes: [1, 525_600],
+    cancelCutoffMinutes: [0, 525_600],
+    rescheduleCutoffMinutes: [0, 525_600],
 });
 const LIMITS = SLOTLOCK_BOOKING_RULE_LIMITS;
+/** Lengths `allowedDurations` may list. */
+export const SLOTLOCK_MAX_ALLOWED_DURATIONS = 20;
+/** Windows `pickupTimes` and `returnTimes` may each hold. */
+export const SLOTLOCK_MAX_DAY_WINDOWS = 4;
+const LIST_RULES = new Set(['allowedDurations', 'pickupTimes', 'returnTimes', 'cancellationFee']);
+/** The `hoursApply` a resource's rules mean: as given, else `ends` with pick-up or return times. */
+export function hoursApplyOf(rules) {
+    if (rules?.hoursApply !== undefined)
+        return rules.hoursApply;
+    return rules?.pickupTimes !== undefined || rules?.returnTimes !== undefined ? 'ends' : 'whole';
+}
+function parseHoursApply(value) {
+    if (value !== 'whole' && value !== 'ends')
+        throw new TypeError("Slotlock booking rule hoursApply must be 'whole' or 'ends'");
+    return value;
+}
+/** `cancellationFee` from untrusted input, or a TypeError. */
+function parseCancellationFee(value) {
+    const fee = value;
+    if (typeof fee !== 'object' ||
+        fee === null ||
+        Array.isArray(fee) ||
+        Object.keys(fee).some((key) => !['amountMinor', 'currency', 'withinMinutes'].includes(key)) ||
+        !Number.isSafeInteger(fee.amountMinor) ||
+        fee.amountMinor < 0 ||
+        fee.amountMinor > 1_000_000_000_000 ||
+        typeof fee.currency !== 'string' ||
+        !/^[A-Z]{3}$/.test(fee.currency) ||
+        (fee.withinMinutes !== undefined &&
+            (!Number.isSafeInteger(fee.withinMinutes) || fee.withinMinutes < 0 || fee.withinMinutes > 525_600))) {
+        throw new TypeError('Slotlock booking rule cancellationFee needs amountMinor (a whole 0-1,000,000,000,000), currency (ISO 4217, like EUR) and optionally withinMinutes (0-525600)');
+    }
+    return {
+        amountMinor: fee.amountMinor,
+        currency: fee.currency,
+        ...(fee.withinMinutes !== undefined ? { withinMinutes: fee.withinMinutes } : {}),
+    };
+}
+/**
+ * The cutoff rule a cancellation or move of a booking starting at `start`, made at `now`, breaks,
+ * or null (RFC 0004 B5).
+ */
+export function cutoffRuleBroken(rules, kind, start, now) {
+    const minutes = kind === 'cancel' ? rules?.cancelCutoffMinutes : rules?.rescheduleCutoffMinutes;
+    if (minutes === undefined)
+        return null;
+    return now.getTime() > start.getTime() - minutes * MINUTE_MS ? (kind === 'cancel' ? 'cancel_cutoff' : 'reschedule_cutoff') : null;
+}
+/** The fee a cancellation of a booking starting at `start`, made at `now`, records, or null. */
+export function cancellationFeeDue(rules, start, now) {
+    const fee = rules?.cancellationFee;
+    if (!fee)
+        return null;
+    if (fee.withinMinutes !== undefined && now.getTime() < start.getTime() - fee.withinMinutes * MINUTE_MS)
+        return null;
+    return fee;
+}
+/** `allowedDurations` from untrusted input, or a TypeError. */
+function parseAllowedDurations(value) {
+    if (!Array.isArray(value) ||
+        value.length < 1 ||
+        value.length > SLOTLOCK_MAX_ALLOWED_DURATIONS ||
+        !value.every((length) => Number.isSafeInteger(length) && length >= 1 && length <= 525_600) ||
+        new Set(value).size !== value.length) {
+        throw new TypeError(`Slotlock booking rule allowedDurations must be 1-${SLOTLOCK_MAX_ALLOWED_DURATIONS} different whole minutes, each 1-525600`);
+    }
+    return [...value].sort((a, b) => a - b);
+}
+/** `pickupTimes` or `returnTimes` from untrusted input, or a TypeError. */
+function parseDayWindows(key, value) {
+    const valid = Array.isArray(value) &&
+        value.length >= 1 &&
+        value.length <= SLOTLOCK_MAX_DAY_WINDOWS &&
+        value.every((window) => typeof window === 'object' &&
+            window !== null &&
+            !Array.isArray(window) &&
+            Object.keys(window).every((name) => name === 'startMinutes' || name === 'durationMinutes') &&
+            Number.isSafeInteger(window.startMinutes) &&
+            window.startMinutes >= 0 &&
+            window.startMinutes < DAY_MINUTES &&
+            Number.isSafeInteger(window.durationMinutes) &&
+            window.durationMinutes >= 1 &&
+            window.durationMinutes <= DAY_MINUTES);
+    if (!valid) {
+        throw new TypeError(`Slotlock booking rule ${key} must be 1-${SLOTLOCK_MAX_DAY_WINDOWS} windows of startMinutes (0-1439) and durationMinutes (1-1440)`);
+    }
+    return value.map((window) => ({
+        startMinutes: window.startMinutes,
+        durationMinutes: window.durationMinutes,
+    }));
+}
+/** Refuse durations that leave no length a booking may have (a TypeError naming them). */
+function checkDurations(rules) {
+    const min = rules.minDurationMinutes ?? 1;
+    const max = rules.maxDurationMinutes ?? 525_600;
+    if (min > max)
+        throw new TypeError('Slotlock booking rule minDurationMinutes must not exceed maxDurationMinutes');
+    if (rules.allowedDurations && !rules.allowedDurations.some((length) => length >= min && length <= max)) {
+        throw new TypeError('Slotlock booking rule allowedDurations has no length within the minimum and maximum');
+    }
+    if (rules.defaultDurationMinutes !== undefined && durationRuleBroken(rules, rules.defaultDurationMinutes) !== null) {
+        throw new TypeError('Slotlock booking rule defaultDurationMinutes must be a length the other rules allow');
+    }
+}
+/** The duration rule a booking of `minutes` breaks, or null. */
+export function durationRuleBroken(rules, minutes) {
+    if (!rules)
+        return null;
+    if (rules.minDurationMinutes !== undefined && minutes < rules.minDurationMinutes)
+        return 'min_duration';
+    if (rules.maxDurationMinutes !== undefined && minutes > rules.maxDurationMinutes)
+        return 'max_duration';
+    if (rules.allowedDurations !== undefined && !rules.allowedDurations.includes(minutes))
+        return 'duration_not_allowed';
+    return null;
+}
 /** Booking rules from untrusted input, or a TypeError naming the field that is wrong. */
 export function parseBookingRules(value) {
     if (typeof value !== 'object' || value === null || Array.isArray(value)) {
@@ -21,10 +142,20 @@ export function parseBookingRules(value) {
     const input = value;
     const rules = {};
     for (const key of Object.keys(input)) {
-        if (!(key in LIMITS) && key !== 'enforceHours' && key !== 'requireCertain') {
+        if (!(key in LIMITS) && key !== 'enforceHours' && key !== 'requireCertain' && key !== 'hoursApply' && !LIST_RULES.has(key)) {
             throw new TypeError(`Slotlock booking rules have no ${key}`);
         }
     }
+    if (input.hoursApply !== undefined)
+        rules.hoursApply = parseHoursApply(input.hoursApply);
+    if (input.allowedDurations !== undefined)
+        rules.allowedDurations = parseAllowedDurations(input.allowedDurations);
+    if (input.cancellationFee !== undefined)
+        rules.cancellationFee = parseCancellationFee(input.cancellationFee);
+    if (input.pickupTimes !== undefined)
+        rules.pickupTimes = parseDayWindows('pickupTimes', input.pickupTimes);
+    if (input.returnTimes !== undefined)
+        rules.returnTimes = parseDayWindows('returnTimes', input.returnTimes);
     for (const [key, [min, max]] of Object.entries(LIMITS)) {
         const field = input[key];
         if (field === undefined)
@@ -51,6 +182,7 @@ export function parseBookingRules(value) {
         rules.stepOffsetMinutes >= rules.slotStepMinutes) {
         throw new TypeError('Slotlock booking rule stepOffsetMinutes must be less than slotStepMinutes');
     }
+    checkDurations(rules);
     return rules;
 }
 /**
@@ -73,6 +205,27 @@ export function parseEffectiveBookingRules(value) {
                 dropped.push(key);
             continue;
         }
+        if (key === 'hoursApply') {
+            if (field === 'whole' || field === 'ends')
+                rules.hoursApply = field;
+            else
+                dropped.push(key);
+            continue;
+        }
+        if (LIST_RULES.has(key)) {
+            try {
+                if (key === 'allowedDurations')
+                    rules.allowedDurations = parseAllowedDurations(field);
+                else if (key === 'cancellationFee')
+                    rules.cancellationFee = parseCancellationFee(field);
+                else
+                    rules[key] = parseDayWindows(key, field);
+            }
+            catch {
+                dropped.push(key);
+            }
+            continue;
+        }
         const limits = LIMITS[key];
         if (limits === undefined ||
             typeof field !== 'number' ||
@@ -84,6 +237,13 @@ export function parseEffectiveBookingRules(value) {
         }
         rules[key] = field;
     }
+    // Levels are validated alone: a combination that leaves no length refuses every booking.
+    try {
+        checkDurations(rules);
+    }
+    catch {
+        dropped.push('durations');
+    }
     return { rules, dropped };
 }
 /**
@@ -138,9 +298,35 @@ export function nextStepStart(from, stepMinutes, timezone, offsetMinutes = 0) {
     }
     return candidate;
 }
+/** The local day an instant falls on in `timezone`, as days since 1970-01-01. */
+function localDay(instant, timezone) {
+    const local = instant.getTime() + zonedOffsetMinutes(instant, timezone) * MINUTE_MS;
+    return Math.floor(local / (DAY_MINUTES * MINUTE_MS));
+}
+/**
+ * Whether a booking runs from one local day into another (a hire): its last moment falls on a later
+ * local day than its start. One that ends at midnight stays on its day.
+ */
+export function isMultiDay(interval, timezone) {
+    return localDay(new Date(interval.end.getTime() - 1), timezone) > localDay(interval.start, timezone);
+}
+/**
+ * Whether `instant` lies in one of the windows of its local day: `[start, start + length)`, or with
+ * `closed` (a return) up to and including the window's end.
+ */
+export function withinDayWindows(instant, windows, timezone, closed = false) {
+    const minutes = localMinutes(instant, timezone);
+    return windows.some((window) => {
+        const into = (((minutes - window.startMinutes) % DAY_MINUTES) + DAY_MINUTES) % DAY_MINUTES;
+        return closed ? into <= window.durationMinutes : into < window.durationMinutes;
+    });
+}
 /**
- * The rule a booking of `interval` made at `now` breaks, or null. `hours` (the resource's own, or
- * the default) are read only when enforced.
+ * The rule a booking of `interval` made at `now` breaks, or null. `hours` (the resource's own, else
+ * inherited, else the default) and `exceptions` are read only when enforced. A hire (a booking from
+ * one local day to another) under `pickupTimes` or `returnTimes` starts and ends in them, and under
+ * `enforceHours` lies inside the hours as `hoursApply` says: wholly, or only at its start and end
+ * (the resource being out between).
  */
 export function bookingRuleBroken(params) {
     const { rules, interval, now } = params;
@@ -158,18 +344,37 @@ export function bookingRuleBroken(params) {
         !onStep(interval.start, rules.slotStepMinutes, params.timezone, stepOffset(rules))) {
         return 'slot_step';
     }
+    const duration = durationRuleBroken(rules, (interval.end.getTime() - start) / MINUTE_MS);
+    if (duration)
+        return duration;
+    const multiDay = isMultiDay(interval, params.timezone);
+    if (multiDay && rules.pickupTimes && !withinDayWindows(interval.start, rules.pickupTimes, params.timezone)) {
+        return 'pickup_time';
+    }
+    if (multiDay && rules.returnTimes && !withinDayWindows(interval.end, rules.returnTimes, params.timezone, true)) {
+        return 'return_time';
+    }
+    // A hire the hours hold only at its ends.
+    const hire = multiDay && hoursApplyOf(rules) === 'ends';
     if (rules.enforceHours === true) {
-        const open = expandRules([...params.hours], interval, params.timezone);
-        let covered = interval.start.getTime();
-        for (const window of open.sort((a, b) => a.start.getTime() - b.start.getTime())) {
-            if (window.start.getTime() > covered)
-                break;
-            covered = Math.max(covered, window.end.getTime());
-            if (covered >= interval.end.getTime())
-                break;
+        const open = (window) => openWindows({
+            hours: params.hours,
+            ...(params.exceptions !== undefined ? { exceptions: params.exceptions } : {}),
+            timezone: params.timezone,
+            window,
+        });
+        if (hire) {
+            // Open at the start, and open up to the end: the hours a hire is collected and returned in.
+            const minute = MINUTE_MS;
+            const atStart = { start: interval.start, end: new Date(start + minute) };
+            const atEnd = { start: new Date(interval.end.getTime() - minute), end: interval.end };
+            if (!coveredByOpenWindows(open(atStart), atStart) || !coveredByOpenWindows(open(atEnd), atEnd)) {
+                return 'outside_hours';
+            }
         }
-        if (covered < interval.end.getTime())
+        else if (!coveredByOpenWindows(open(interval), interval)) {
             return 'outside_hours';
+        }
     }
     return null;
 }
@@ -179,6 +384,9 @@ export function bookingRuleBroken(params) {
  */
 export function bookingSearch(params) {
     const { rules, window, now } = params;
+    if (params.durationMs !== undefined && durationRuleBroken(rules, params.durationMs / MINUTE_MS) !== null) {
+        return null;
+    }
     let start = window.start.getTime();
     const end = window.end.getTime();
     if (rules?.minNoticeMinutes !== undefined) {
@@ -188,7 +396,27 @@ export function bookingSearch(params) {
     const bufferBeforeMs = bookingBufferBeforeMs(rules);
     const step = rules?.slotStepMinutes;
     const offset = stepOffset(rules);
-    const toStep = step === undefined ? undefined : (from) => nextStepStart(from, step, params.timezone, offset);
+    const stepped = step === undefined ? undefined : (from) => nextStepStart(from, step, params.timezone, offset);
+    // A slot that runs from one local day into another starts and ends in the pick-up and return
+    // times: candidates move on a minute (or a step) at a time, for at most two days.
+    const durationMs = params.durationMs;
+    const hireRules = rules && (rules.pickupTimes !== undefined || rules.returnTimes !== undefined) ? rules : undefined;
+    const toStep = hireRules === undefined || durationMs === undefined
+        ? stepped
+        : (from) => {
+            let candidate = stepped ? stepped(from) : new Date(Math.ceil(from.getTime() / MINUTE_MS) * MINUTE_MS);
+            for (let tries = 0; tries <= 2 * DAY_MINUTES; tries++) {
+                const slot = { start: candidate, end: new Date(candidate.getTime() + durationMs) };
+                if (!isMultiDay(slot, params.timezone) ||
+                    ((!hireRules.pickupTimes || withinDayWindows(slot.start, hireRules.pickupTimes, params.timezone)) &&
+                        (!hireRules.returnTimes || withinDayWindows(slot.end, hireRules.returnTimes, params.timezone, true)))) {
+                    return candidate;
+                }
+                const next = new Date(Math.floor(candidate.getTime() / MINUTE_MS) * MINUTE_MS + MINUTE_MS);
+                candidate = stepped ? stepped(next) : next;
+            }
+            return new Date(end + 1);
+        };
     const searched = { start: new Date(start), end: new Date(end) };
     if (rules?.maxAdvanceDays !== undefined) {
         const latestStart = now.getTime() + rules.maxAdvanceDays * DAY_MINUTES * MINUTE_MS;

package/dashboard-assistant-ui.d.ts

@@ -0,0 +1,21 @@
+/** How a step reads while it runs, once it has, and when it could not. */
+export type SlotlockAssistantStepState = 'run' | 'ok' | 'bad';
+/** A tool step in plain words: "Checking availability…", "Checked availability", "Couldn't check availability". */
+export declare function slotlockAssistantStepLabel(name: string, title: string, state: SlotlockAssistantStepState, write?: boolean): string;
+/** The verb a proposed change's card is approved with, and whether it removes something. */
+export declare function slotlockAssistantActionVerb(operation: string): {
+    verb: string;
+    busy: string;
+    done: string;
+    danger: boolean;
+};
+/** The chat's styles: one centred column, the composer docked under it, quiet steps and cards. */
+export declare const SLOTLOCK_ASSISTANT_CSS = "\n.assistant-page { display: grid; }\n.assistant { position: relative; display: flex; flex-direction: column; width: min(100%, 720px); margin: 0 auto; min-height: calc(100dvh - 180px); }\n.assistant .thread { flex: 1; }\n.assistant[data-empty] { justify-content: center; padding-bottom: 12vh; }\n.assistant[data-empty] .thread { display: none; }\n.assistant[data-empty] .dock { order: 1; position: static; padding: 0; background: none; }\n.assistant[data-empty] .assistant-start { order: 2; padding-top: var(--space-3); }\n.assistant:not([data-empty]) .assistant-start { display: none; }\n.chips { display: flex; flex-wrap: wrap; justify-content: center; gap: var(--space-2); }\n.chips form { margin: 0; }\n.chip { display: inline-flex; align-items: center; gap: 6px; height: 32px; padding: 0 var(--space-3); border-radius: var(--radius-full); border: 1px solid var(--line); background: var(--surface); color: var(--ink-2); font: inherit; font-size: var(--text-md); cursor: pointer; transition: background var(--fast) var(--ease), border-color var(--fast) var(--ease); }\n.chip:hover { background: var(--hover); border-color: var(--line-strong); color: var(--ink); }\n.thread { list-style: none; margin: 0; padding: var(--space-2) 0 var(--space-6); display: grid; gap: var(--space-6); align-content: start; }\n.turn { margin: 0; min-width: 0; }\n.turn.mine { justify-self: end; max-width: 80%; }\n.bubble { padding: 10px 14px; border-radius: 18px; background: var(--sunken); color: var(--ink); font-size: var(--text-lg); line-height: 1.5; white-space: pre-wrap; overflow-wrap: anywhere; }\n.turn.bot { justify-self: stretch; }\n.prose { max-width: 68ch; color: var(--ink); font-size: var(--text-lg); line-height: 1.6; overflow-wrap: anywhere; }\n.prose > :first-child { margin-top: 0; }\n.prose > :last-child { margin-bottom: 0; }\n.prose p { margin: 0 0 var(--space-3); color: inherit; }\n.prose strong { font-weight: 600; }\n.prose h4 { margin: var(--space-4) 0 var(--space-2); font-size: var(--text-lg); font-weight: 600; }\n.prose ul, .prose ol { margin: 0 0 var(--space-3); padding-left: 20px; }\n.prose li { margin: 4px 0; }\n.prose li > ul, .prose li > ol { margin: 4px 0 0; }\n.prose a { color: var(--accent); text-underline-offset: 2px; }\n.prose code { font: 400 12.5px/1.4 var(--mono); background: var(--sunken); border-radius: 4px; padding: 1px 5px; }\n.prose pre { margin: 0 0 var(--space-3); padding: var(--space-3); background: var(--sunken); border: 1px solid var(--line); border-radius: var(--radius); overflow-x: auto; }\n.prose pre code { background: none; padding: 0; font-size: 12.5px; }\n.prose blockquote { margin: 0 0 var(--space-3); padding-left: var(--space-3); border-left: 2px solid var(--line-strong); color: var(--ink-2); }\n.prose hr { border: 0; border-top: 1px solid var(--line); margin: var(--space-4) 0; }\n.md-table { overflow-x: auto; margin: 0 0 var(--space-3); }\n.md-table table { border-collapse: collapse; font-size: var(--text-md); min-width: 50%; }\n.md-table table { width: auto; }\n.md-table th { font: 600 var(--text-md)/1.4 var(--font); text-transform: none; letter-spacing: 0; background: none; text-align: left; color: var(--ink-2); padding: 6px 16px 6px 0; border-bottom: 1px solid var(--line); white-space: nowrap; }\n.md-table td { padding: 6px 16px 6px 0; border-bottom: 1px solid var(--line-soft); vertical-align: top; }\n.md-table tr:last-child td { border-bottom: 0; }\n.change details.more { margin: 0; }\n.change details.more > summary { cursor: pointer; color: var(--ink-3); font-size: var(--text-sm); list-style: none; }\n.change details.more > summary::-webkit-details-marker { display: none; }\n.change details.more > summary:hover { color: var(--ink-2); }\n.change details.more[open] > summary { margin-bottom: var(--space-2); }\n.turn.steps { justify-self: start; }\ndetails.steps > summary { list-style: none; display: inline-flex; align-items: center; gap: 6px; cursor: pointer; color: var(--ink-3); font-size: var(--text-md); padding: 2px 0; }\ndetails.steps > summary::-webkit-details-marker { display: none; }\ndetails.steps > summary::after { content: \"\"; width: 6px; height: 6px; border-right: 1.5px solid currentColor; border-bottom: 1.5px solid currentColor; transform: rotate(-45deg); transition: transform var(--fast) var(--ease); margin-left: 2px; }\ndetails.steps[open] > summary::after { transform: rotate(45deg); }\ndetails.steps > summary:hover { color: var(--ink-2); }\ndetails.steps.has-bad > summary::before { content: \"\"; width: 6px; height: 6px; border-radius: 50%; background: var(--bad); }\n.step-list { list-style: none; margin: var(--space-2) 0 0; padding: 0 0 0 var(--space-3); border-left: 1px solid var(--line); display: grid; gap: 6px; }\n.step { display: flex; align-items: baseline; gap: var(--space-2); font-size: var(--text-md); color: var(--ink-2); }\n.step::before { content: \"\"; flex: none; width: 7px; height: 7px; border-radius: 50%; background: var(--good); transform: translateY(-1px); }\n.step.bad::before { background: var(--bad); }\n.step.run::before { background: var(--ink-3); }\n.step .why { color: var(--ink-3); font-size: var(--text-sm); }\n.live-steps { display: grid; gap: 6px; }\n.live-steps .step.run, .thinking { background: linear-gradient(90deg, var(--ink-3) 0%, var(--ink) 50%, var(--ink-3) 100%); background-size: 200% 100%; -webkit-background-clip: text; background-clip: text; color: transparent; animation: assistant-shimmer 1.6s linear infinite; }\n.thinking { font-size: var(--text-md); justify-self: start; }\n@keyframes assistant-shimmer { from { background-position: 100% 0; } to { background-position: -100% 0; } }\n.prose.streaming > :last-child::after { content: \"\"; display: inline-block; width: 8px; height: 8px; margin-left: 4px; border-radius: 50%; background: var(--ink-3); vertical-align: baseline; animation: assistant-pulse 1s ease-in-out infinite; }\n@keyframes assistant-pulse { 50% { opacity: 0.25; } }\n.turn.note { color: var(--ink-3); font-size: var(--text-md); }\n.turn.error { display: flex; align-items: center; justify-content: space-between; gap: var(--space-3); padding: 10px 12px; border: 1px solid var(--bad-line); background: var(--bad-wash); border-radius: var(--radius); font-size: var(--text-md); color: var(--ink); }\n.turn.error::before { content: \"\"; flex: none; width: 8px; height: 8px; border-radius: 50%; background: var(--bad); }\n.turn.error > span { flex: 1; }\n.turn.error form, .turn.note form { margin: 0; }\n.text-button { appearance: none; border: 0; background: none; padding: 0; font: inherit; font-size: var(--text-md); color: var(--accent); cursor: pointer; }\n.text-button:hover { text-decoration: underline; text-underline-offset: 2px; }\n.turn.action { justify-self: start; width: min(100%, 560px); }\n.change { padding: var(--space-4) var(--space-5); background: var(--surface); border: 1px solid var(--line-strong); border-radius: var(--radius-lg); display: grid; gap: var(--space-3); }\n.change-title { margin: 0; font-size: var(--text-lg); font-weight: 600; color: var(--ink); overflow-wrap: anywhere; }\n.change .facts { display: grid; grid-template-columns: max-content minmax(0, 1fr); gap: 6px var(--space-4); margin: 0; font-size: var(--text-md); }\n.change .facts dt { color: var(--ink-3); font-size: var(--text-sm); padding-top: 1px; }\n.change .facts dd { margin: 0; color: var(--ink); overflow-wrap: anywhere; }\n.change .facts dd pre { margin: 0; white-space: pre-wrap; font: 400 12px/1.5 var(--mono); }\n.change .facts .was { color: var(--ink-3); text-decoration: line-through; }\n.change-buttons { display: flex; gap: var(--space-2); flex-wrap: wrap; }\n.change-buttons form { margin: 0; }\n.change-buttons button { height: 32px; }\nbutton.danger { background: var(--bad); color: var(--bad-ink); border-color: var(--bad); }\nbutton.danger:hover { filter: brightness(1.08); }\nbutton.ghost { background: transparent; border-color: transparent; color: var(--ink-2); }\nbutton.ghost:hover { background: var(--hover); color: var(--ink); }\n.receipt { margin: 0; display: flex; align-items: baseline; gap: var(--space-2); font-size: var(--text-md); color: var(--ink-2); }\n.receipt::before { content: \"\"; flex: none; width: 7px; height: 7px; border-radius: 50%; background: var(--ink-3); transform: translateY(-1px); }\n.receipt.ok { color: var(--ink); }\n.receipt.ok::before { background: var(--good); }\n.receipt.bad::before { background: var(--bad); }\n.receipt .why { color: var(--ink-3); }\n.dock { position: sticky; bottom: 0; padding: var(--space-6) 0 var(--space-6); background: linear-gradient(to bottom, transparent, var(--canvas) 24px); z-index: 2; }\n.composer { display: grid; margin: 0; background: var(--surface); border: 1px solid var(--line); border-radius: 16px; transition: border-color var(--fast) var(--ease), box-shadow var(--fast) var(--ease); }\n.composer:focus-within { border-color: var(--line-strong); box-shadow: 0 0 0 3px var(--ring); }\n.composer textarea { display: block; width: 100%; min-height: 26px; max-height: 200px; resize: none; border: 0; outline: 0; background: transparent; padding: 14px 16px 0; color: var(--ink); font: inherit; font-size: var(--text-lg); line-height: 1.5; box-shadow: none; }\n.composer textarea:focus { box-shadow: none; border: 0; }\n.composer-bar { display: flex; align-items: center; justify-content: flex-end; gap: var(--space-2); padding: var(--space-2); }\n.composer-bar .count { margin-right: auto; padding-left: var(--space-2); font-size: var(--text-sm); color: var(--ink-3); }\n.composer-bar .count.over { color: var(--warn); }\n.send { display: inline-grid; place-items: center; width: 32px; height: 32px; padding: 0; border-radius: 50%; border: 0; background: var(--button); color: var(--button-ink); cursor: pointer; transition: opacity var(--fast) var(--ease), background var(--fast) var(--ease); }\n.send:hover { background: var(--button-hover); }\n.send:disabled { opacity: 0.4; cursor: default; }\n.send svg { width: 16px; height: 16px; }\n.send .stop { display: none; }\n.assistant.streaming .send .arrow { display: none; }\n.assistant.streaming .send .stop { display: block; }\n.jump { position: absolute; left: 50%; transform: translate(-50%, 0); top: -8px; width: 32px; height: 32px; padding: 0; border-radius: 50%; border: 1px solid var(--line); background: var(--surface); color: var(--ink-2); display: grid; place-items: center; cursor: pointer; box-shadow: var(--pop-shadow); }\n.jump[hidden] { display: none; }\n.new-chat svg, .chats-link svg { width: 14px; height: 14px; }\n.assistant-page[data-empty] .new-chat { display: none; }\n.assistant-actions { display: flex; gap: var(--space-2); }\n.chats-link { display: none; }\n/* Chats: the member's conversations beside the one shown, most recent first, grouped by day. */\n.assistant-shell { display: grid; grid-template-columns: 252px minmax(0, 1fr); gap: var(--space-6); align-items: start; }\n/* It scrolls with the page: a column that scrolled on its own would clip a row's menu. */\n.chats { display: flex; flex-direction: column; gap: var(--space-2); min-width: 0; }\n.chats-head { display: flex; align-items: center; justify-content: space-between; min-height: 36px; }\n.chats-head h2 { margin: 0; font-size: var(--text-md); font-weight: 600; color: var(--ink-2); }\n.icon-button { display: grid; place-items: center; width: 30px; height: 30px; border-radius: var(--radius-sm); color: var(--ink-2); transition: background var(--fast) var(--ease), color var(--fast) var(--ease); }\n.icon-button:hover { background: var(--hover); color: var(--ink); text-decoration: none; }\n.icon-button svg { width: 15px; height: 15px; }\n.chats-filter { height: 32px; font-size: var(--text-md); }\n.chats-filter[hidden] { display: none; }\n/* Sentence case, not the dashboard's uppercase h3. */\n.chat-group { margin: var(--space-3) 0 2px; padding: 0 var(--space-2); font-family: inherit; font-size: var(--text-xs); font-weight: 500; line-height: 1.5; text-transform: none; letter-spacing: 0; color: var(--ink-3); }\n.chat-group[hidden] { display: none; }\n.chat-list { min-width: 0; }\n/* minmax(0, 1fr): a long title is cut with an ellipsis, never widening the column. */\n.chat-rows { list-style: none; margin: 0; padding: 0; display: grid; grid-template-columns: minmax(0, 1fr); gap: 1px; }\n.chat-row { position: relative; display: flex; align-items: center; border-radius: var(--radius); transition: background var(--fast) var(--ease); }\n.chat-row[hidden] { display: none; }\n.chat-row:hover, .chat-row:focus-within, .chat-row.current { background: var(--hover); }\n.chat-link { flex: 1; min-width: 0; display: flex; align-items: baseline; gap: var(--space-2); padding: 7px 4px 7px var(--space-2); color: var(--ink-2); font-size: var(--text-md); }\n.chat-link:hover { color: var(--ink); text-decoration: none; }\n.chat-row.current .chat-link { color: var(--ink); font-weight: 500; }\n.chat-title { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }\n.chat-when { flex: none; font-size: var(--text-xs); color: var(--ink-3); font-variant-numeric: tabular-nums; }\n.chat-menu { position: relative; flex: none; }\n.chat-menu summary { list-style: none; display: grid; place-items: center; width: 28px; height: 28px; margin-right: 2px; border-radius: var(--radius-sm); color: var(--ink-3); cursor: pointer; opacity: 0; transition: opacity var(--fast) var(--ease), background var(--fast) var(--ease); }\n.chat-menu summary::-webkit-details-marker { display: none; }\n.chat-row:hover .chat-menu summary, .chat-row:focus-within .chat-menu summary, .chat-row.current .chat-menu summary, .chat-menu[open] summary { opacity: 1; }\n.chat-menu summary:hover, .chat-menu[open] summary { background: var(--line-soft); color: var(--ink); }\n.chat-menu summary svg { width: 14px; height: 14px; }\n.chat-menu .pop { z-index: 20; width: 260px; display: grid; gap: var(--space-2); }\n.chat-menu .pop form { display: grid; gap: var(--space-2); margin: 0; }\n.chat-menu .pop form + form { padding-top: var(--space-2); border-top: 1px solid var(--line-soft); }\n.chat-menu .pop button.danger { background: none; border-color: transparent; box-shadow: none; color: var(--bad); }\n.chat-menu .pop button.danger:hover { background: var(--bad-wash); }\n.chat-rename input { width: 100%; min-width: 0; height: 34px; }\n.chats-empty { padding: var(--space-2); font-size: var(--text-md); }\n.chats-page .chats { max-width: 560px; }\n.chats-page .chats-head { display: none; }\n.chats-page .chat-menu summary { opacity: 1; }\n@media (max-width: 1100px) {\n  .assistant-shell { grid-template-columns: minmax(0, 1fr); }\n  .assistant-shell > .chats { display: none; }\n  .chats-link { display: inline-flex; }\n}\n@media (hover: none) {\n  .chat-menu summary { opacity: 1; }\n}\n@media (prefers-reduced-motion: reduce) {\n  .live-steps .step.run, .thinking { animation: none; color: var(--ink-3); background: none; }\n  .prose.streaming > :last-child::after { animation: none; }\n}\n@media (max-width: 760px) {\n  .assistant { min-height: calc(100dvh - 140px); }\n  .assistant[data-empty] { justify-content: flex-end; padding-bottom: 0; }\n  .assistant[data-empty] .assistant-start { order: 1; padding: 0 0 var(--space-3); }\n  .assistant[data-empty] .dock { order: 2; position: sticky; padding-bottom: max(12px, env(safe-area-inset-bottom)); }\n  .chips { flex-wrap: nowrap; justify-content: flex-start; overflow-x: auto; max-width: 100%; padding-bottom: 2px; scrollbar-width: none; }\n  .chips::-webkit-scrollbar { display: none; }\n  .chip { flex: none; }\n  .turn.mine { max-width: 88%; }\n  .md-table table { display: table; }\n  .md-table thead { display: table-header-group; }\n  .md-table tbody { display: table-row-group; }\n  .md-table tr { display: table-row; padding: 0; border: 0; }\n  .md-table th, .md-table td { display: table-cell; padding: 6px 12px 6px 0; }\n  .md-table td { border-bottom: 1px solid var(--line-soft); }\n  .composer textarea { font-size: 16px; }\n  .dock { padding-bottom: max(12px, env(safe-area-inset-bottom)); }\n  .change { padding: var(--space-4); }\n  .change .facts { grid-template-columns: minmax(0, 1fr); gap: 2px; }\n  .change .facts dd { margin-bottom: var(--space-2); }\n  .change-buttons form { flex: 1; }\n  .change-buttons button { width: 100%; height: 40px; }\n}\n";
+/**
+ * The browser side of the chat, appended to app.js: Enter sends, the box grows, a write chip fills
+ * the box instead of sending, and a reply streams in from `<root>/assistant/stream` (newline-
+ * delimited JSON: text deltas, steps, then the turn as the server renders it). Without it the
+ * page still works: every form posts and the page reloads at the latest message.
+ * `markdownSource` is renderSlotlockMarkdown's source, so a reply renders as it will once stored.
+ */
+export declare function slotlockAssistantScript(markdownSource: string): string;