@wow-two-beta/ui-vue 0.0.2

package/dist/foundation/datetime/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../src/foundation/datetime/Internals.ts","../../../src/foundation/datetime/Arithmetic.ts","../../../src/foundation/datetime/Boundaries.ts","../../../src/foundation/datetime/IsoDate.ts","../../../src/foundation/datetime/Comparison.ts","../../../src/foundation/datetime/Difference.ts","../../../src/foundation/datetime/Interval.ts"],"sourcesContent":["// Private helpers shared across the datetime slice — deliberately absent from `index.ts` so the public\n// surface stays exactly the documented operation set.\n//\n// Two invariants live here:\n//  1. `cloneDate` is the ONLY producer of a result `Date`. Every public op clones first, then mutates the\n//     clone — \"never mutate the input\" is then structural, not a review convention. A new op that reaches\n//     for `new Date(...)` directly is the thing to catch in review.\n//  2. `daysInMonth` uses the day-0 trick (day `0` of month N+1 = last day of month N) driven through\n//     `setFullYear`, NOT the `new Date(year, month, day)` constructor — that constructor maps years 0-99\n//     to 1900+year, which would silently mis-length February for a year-0-99 date. The probe starts at\n//     local noon so a DST midnight-transition zone can't shift the probe onto an adjacent day.\n\n/** Milliseconds in one second. */\nexport const MS_PER_SECOND = 1000;\n\n/** Milliseconds in one minute. */\nexport const MS_PER_MINUTE = 60_000;\n\n/** Milliseconds in one hour. */\nexport const MS_PER_HOUR = 3_600_000;\n\n/** Milliseconds in one 24-hour period (nominal — a DST day is 23 or 25 hours). */\nexport const MS_PER_DAY = 86_400_000;\n\n/** Copies a `Date` by timestamp. An invalid input yields an equally-invalid copy (`NaN` time). */\nexport function cloneDate(date: Date): Date {\n  return new Date(date.getTime());\n}\n\n/** Returns the length in days of `monthIndex` (0-11) in `year`, leap years included. */\nexport function daysInMonth(year: number, monthIndex: number): number {\n  const probe = new Date(2000, 0, 1, 12);\n  probe.setFullYear(year, monthIndex + 1, 0);\n  return probe.getDate();\n}\n","// Date arithmetic — every op returns a NEW `Date`, the input is never mutated.\n//\n// Two families with deliberately different semantics; picking the wrong one is the usual source of\n// off-by-one-hour bugs:\n//\n//  - CALENDAR ops (`addDays`/`addWeeks`/`addMonths`/`addYears`) go through `setDate`/`setMonth`, which\n//    operate on local wall-clock fields. Adding 1 day across a DST boundary therefore keeps the wall-clock\n//    time (09:00 → 09:00) even though only 23 or 25 hours elapsed. This is what a calendar UI wants.\n//  - ELAPSED ops (`addHours`/`addMinutes`/`addSeconds`) add absolute milliseconds. Across a DST boundary\n//    the wall-clock time shifts by the offset delta, because the request was \"N hours later\", not\n//    \"the same time N days on\". This is what a timer/deadline wants.\n//\n// `addMonths` CLAMPS to the target month's last day: Jan 31 + 1 month = Feb 28 (Feb 29 in a leap year),\n// never Mar 3. The naive `setMonth(getMonth() + 1)` overflows instead, which is the classic bug — the\n// day-of-month is parked at 1 before the month shift and re-applied clamped afterwards to prevent it.\n// `addYears` routes through `addMonths`, so Feb 29 + 1 year = Feb 28 by the same rule.\n\nimport { cloneDate, daysInMonth, MS_PER_HOUR, MS_PER_MINUTE, MS_PER_SECOND } from './Internals';\n\n/** Adds `amount` calendar days (may be negative); preserves wall-clock time across a DST boundary. */\nexport function addDays(date: Date, amount: number): Date {\n  const result = cloneDate(date);\n  result.setDate(result.getDate() + amount);\n  return result;\n}\n\n/** Subtracts `amount` calendar days; preserves wall-clock time across a DST boundary. */\nexport function subDays(date: Date, amount: number): Date {\n  return addDays(date, -amount);\n}\n\n/** Adds `amount` weeks (7 calendar days each); preserves wall-clock time across a DST boundary. */\nexport function addWeeks(date: Date, amount: number): Date {\n  return addDays(date, amount * 7);\n}\n\n/** Subtracts `amount` weeks (7 calendar days each). */\nexport function subWeeks(date: Date, amount: number): Date {\n  return addDays(date, -amount * 7);\n}\n\n/**\n * Adds `amount` calendar months, clamping the day-of-month to the target month's length —\n * Jan 31 + 1 = Feb 28 (Feb 29 in a leap year), Mar 31 - 1 = Feb 28. Time-of-day is preserved.\n */\nexport function addMonths(date: Date, amount: number): Date {\n  const result = cloneDate(date);\n  const day = result.getDate();\n  // Park on the 1st so the month shift can never overflow into the following month, then re-apply\n  // the original day clamped to what the target month actually has.\n  result.setDate(1);\n  result.setMonth(result.getMonth() + amount);\n  result.setDate(Math.min(day, daysInMonth(result.getFullYear(), result.getMonth())));\n  return result;\n}\n\n/** Subtracts `amount` calendar months, clamping the day-of-month to the target month's length. */\nexport function subMonths(date: Date, amount: number): Date {\n  return addMonths(date, -amount);\n}\n\n/** Adds `amount` calendar years, clamping Feb 29 to Feb 28 when the target year isn't a leap year. */\nexport function addYears(date: Date, amount: number): Date {\n  return addMonths(date, amount * 12);\n}\n\n/** Subtracts `amount` calendar years, clamping Feb 29 to Feb 28 when the target year isn't a leap year. */\nexport function subYears(date: Date, amount: number): Date {\n  return addMonths(date, -amount * 12);\n}\n\n/** Adds `amount` hours of elapsed time; wall-clock time shifts across a DST boundary. */\nexport function addHours(date: Date, amount: number): Date {\n  const result = cloneDate(date);\n  result.setTime(result.getTime() + amount * MS_PER_HOUR);\n  return result;\n}\n\n/** Subtracts `amount` hours of elapsed time; wall-clock time shifts across a DST boundary. */\nexport function subHours(date: Date, amount: number): Date {\n  return addHours(date, -amount);\n}\n\n/** Adds `amount` minutes of elapsed time. */\nexport function addMinutes(date: Date, amount: number): Date {\n  const result = cloneDate(date);\n  result.setTime(result.getTime() + amount * MS_PER_MINUTE);\n  return result;\n}\n\n/** Subtracts `amount` minutes of elapsed time. */\nexport function subMinutes(date: Date, amount: number): Date {\n  return addMinutes(date, -amount);\n}\n\n/** Adds `amount` seconds of elapsed time. */\nexport function addSeconds(date: Date, amount: number): Date {\n  const result = cloneDate(date);\n  result.setTime(result.getTime() + amount * MS_PER_SECOND);\n  return result;\n}\n\n/** Subtracts `amount` seconds of elapsed time. */\nexport function subSeconds(date: Date, amount: number): Date {\n  return addSeconds(date, -amount);\n}\n","// Period boundaries — snapping a `Date` to the first/last instant of its day, week, month, or year.\n// Every op returns a NEW `Date`; the input is never mutated.\n//\n// All boundaries are LOCAL wall-clock, matching how a user reads a calendar: \"today\" ends at local\n// 23:59:59.999, not at UTC midnight. End-of-period is the last representable millisecond (…:59.999)\n// rather than the next period's start, so a closed `[start, end]` range covers the period exactly and\n// `isWithinInterval` needs no half-open special case.\n//\n// `startOfWeek` takes `weekStartsOn` because the first day of the week is locale-dependent and NOT\n// derivable from the `Date` itself. The default is 1 (Monday) = ISO-8601, which is also what the\n// majority of locales use; a US/CA/JP calendar passes 0 (Sunday). There is no \"detect it from the\n// locale\" path here on purpose — `Intl` exposes no stable week-start API across engines, so guessing\n// would be worse than an explicit argument. Locale-aware DISPLAY stays in `foundation/i18n`.\n//\n// DST note: in the handful of zones whose DST transition happens AT midnight (e.g. America/Santiago),\n// local 00:00 does not exist on transition day and `setHours(0, …)` yields 01:00. That is the correct\n// \"first instant of the day\" in that zone — the guarantee is first-instant, not literally 00:00.\n\nimport { addDays, subDays } from './Arithmetic';\nimport { cloneDate } from './Internals';\n\n/** Day index a week starts on: `0` Sunday … `6` Saturday. */\nexport type WeekStartsOn = 0 | 1 | 2 | 3 | 4 | 5 | 6;\n\n/** Returns the first instant of `date`'s local day (00:00:00.000). */\nexport function startOfDay(date: Date): Date {\n  const result = cloneDate(date);\n  result.setHours(0, 0, 0, 0);\n  return result;\n}\n\n/** Returns the last instant of `date`'s local day (23:59:59.999). */\nexport function endOfDay(date: Date): Date {\n  const result = cloneDate(date);\n  result.setHours(23, 59, 59, 999);\n  return result;\n}\n\n/**\n * Returns the first instant of `date`'s week. `weekStartsOn` defaults to `1` (Monday, ISO-8601);\n * pass `0` for a Sunday-first (US) calendar.\n */\nexport function startOfWeek(date: Date, weekStartsOn: WeekStartsOn = 1): Date {\n  const offset = (date.getDay() - weekStartsOn + 7) % 7;\n  return startOfDay(subDays(date, offset));\n}\n\n/**\n * Returns the last instant of `date`'s week (day 7 at 23:59:59.999). `weekStartsOn` defaults to `1`\n * (Monday, ISO-8601); pass `0` for a Sunday-first (US) calendar.\n */\nexport function endOfWeek(date: Date, weekStartsOn: WeekStartsOn = 1): Date {\n  return endOfDay(addDays(startOfWeek(date, weekStartsOn), 6));\n}\n\n/** Returns the first instant of the 1st of `date`'s month. */\nexport function startOfMonth(date: Date): Date {\n  const result = cloneDate(date);\n  result.setDate(1);\n  result.setHours(0, 0, 0, 0);\n  return result;\n}\n\n/** Returns the last instant of the last day of `date`'s month (28th-31st at 23:59:59.999). */\nexport function endOfMonth(date: Date): Date {\n  const result = cloneDate(date);\n  // Day `0` of the NEXT month is the last day of this one — avoids a `daysInMonth` lookup and the\n  // day-overflow that `setMonth(getMonth() + 1)` alone would cause on a 31st.\n  result.setMonth(result.getMonth() + 1, 0);\n  result.setHours(23, 59, 59, 999);\n  return result;\n}\n\n/** Returns the first instant of Jan 1 of `date`'s year. */\nexport function startOfYear(date: Date): Date {\n  const result = cloneDate(date);\n  result.setMonth(0, 1);\n  result.setHours(0, 0, 0, 0);\n  return result;\n}\n\n/** Returns the last instant of Dec 31 of `date`'s year. */\nexport function endOfYear(date: Date): Date {\n  const result = cloneDate(date);\n  result.setMonth(11, 31);\n  result.setHours(23, 59, 59, 999);\n  return result;\n}\n","// ISO-8601 parsing + serialization, and the validity guard the rest of the slice leans on.\n//\n// Two spec traps this file exists to neutralize:\n//\n//  1. `new Date('2026-03-15')` — a DATE-ONLY ISO string is parsed as UTC midnight per spec, while a\n//     date-TIME string without an offset is parsed as local. So the same-looking input lands on a\n//     different calendar day depending on which shape it had and which side of UTC the user sits on.\n//     `parseIsoDate` reads a date-only string field-by-field into LOCAL midnight, which is what a\n//     `<input type=\"date\">` value means to the person who typed it.\n//  2. `date.toISOString().slice(0, 10)` — serializes in UTC, so 2026-03-15 23:30 in New York comes back\n//     as `2026-03-16`, and 2026-03-15 00:30 in Tokyo as `2026-03-14`. The day silently shifts, usually\n//     only for users in a subset of timezones, which is why it survives review. `toIsoDateString` reads\n//     the LOCAL fields instead and never touches UTC.\n//\n// Parsing is strict + anchored: only the two accepted shapes parse, everything else returns `null`. No\n// `Invalid Date` is ever returned, so a `Date` that leaves this module is always safe to store in state.\n// The accepted shapes mirror `foundation/http/temporalReviver` (`T` separator, no space) so a value that\n// the API client would upgrade to a `Temporal.*` is exactly a value this module parses.\n\nconst DATE_ONLY = /^(\\d{4})-(\\d{2})-(\\d{2})$/;\nconst DATE_TIME = /^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2})?(\\.\\d{1,9})?(Z|[+-]\\d{2}:?\\d{2})?$/;\n\n/**\n * Narrows `value` to a usable `Date` — a `Date` instance whose time is not `NaN`. Use it before any\n * op in this slice when the input came from outside (props, storage, a hand-built `new Date(input)`).\n */\nexport function isValidDate(value: unknown): value is Date {\n  return value instanceof Date && !Number.isNaN(value.getTime());\n}\n\n/**\n * Parses an ISO-8601 `YYYY-MM-DD` or `YYYY-MM-DDTHH:mm[:ss[.sss]][Z|±HH:mm]` string, returning `null`\n * for any other input — including a well-shaped but impossible date such as `2026-02-30`. Never returns\n * an `Invalid Date`.\n *\n * A date-only string resolves to LOCAL midnight (not UTC midnight, which is what `new Date(string)`\n * would give). A date-time string keeps standard semantics: with an offset it is that absolute instant,\n * without one it is local wall-clock.\n */\nexport function parseIsoDate(value: string): Date | null {\n  if (typeof value !== 'string') return null;\n\n  const text = value.trim();\n  if (text === '') return null;\n\n  const dateOnly = DATE_ONLY.exec(text);\n  if (dateOnly !== null) {\n    const year = Number(dateOnly[1]);\n    const month = Number(dateOnly[2]);\n    const day = Number(dateOnly[3]);\n\n    const result = new Date(2000, 0, 1, 12);\n    // `setFullYear` rather than the `new Date(y, m, d)` constructor: that constructor maps years 0-99\n    // to 1900+year. The probe starts at local noon so a midnight-DST zone can't shift the day.\n    result.setFullYear(year, month - 1, day);\n    result.setHours(0, 0, 0, 0);\n\n    // Round-trip check — the setters normalize out-of-range fields (Feb 30 → Mar 2) instead of failing,\n    // so comparing back is the only way to reject an impossible date.\n    if (result.getFullYear() !== year || result.getMonth() !== month - 1 || result.getDate() !== day) {\n      return null;\n    }\n    return result;\n  }\n\n  if (!DATE_TIME.test(text)) return null;\n\n  const parsed = new Date(text);\n  return isValidDate(parsed) ? parsed : null;\n}\n\n/**\n * Serializes `date` to `YYYY-MM-DD` using its LOCAL calendar fields — the day never shifts by timezone\n * the way `toISOString().slice(0, 10)` does. Round-trips exactly with {@link parseIsoDate}.\n *\n * Throws a `RangeError` on an invalid `Date`, or on a year outside `0000`-`9999` (which ISO-8601 can\n * only express with the extended `±YYYYYY` form this function does not emit). Guard with\n * {@link isValidDate} when the input is untrusted.\n */\nexport function toIsoDateString(date: Date): string {\n  if (!isValidDate(date)) {\n    throw new RangeError('toIsoDateString: expected a valid Date, got an invalid one');\n  }\n\n  const year = date.getFullYear();\n  if (year < 0 || year > 9999) {\n    throw new RangeError(`toIsoDateString: year ${year} is outside the representable range 0000-9999`);\n  }\n\n  const month = String(date.getMonth() + 1).padStart(2, '0');\n  const day = String(date.getDate()).padStart(2, '0');\n  return `${String(year).padStart(4, '0')}-${month}-${day}`;\n}\n","// Date comparison + selection. Predicates return `boolean`; selectors (`minDate`/`maxDate`/`clampDate`)\n// return a NEW `Date` and never mutate an input.\n//\n// NOW IS ALWAYS INJECTABLE. `isToday`/`isPast`/`isFuture` take `now` as their last parameter, defaulting\n// to `new Date()` in the SIGNATURE — never buried in the body. A test passes a fixed `now` and the result\n// is deterministic; a caller that omits it gets the obvious behavior. Any future now-dependent predicate\n// added here must follow the same shape, otherwise the test for it can only be flaky or clock-mocked.\n//\n// Two slice-wide rules encoded here:\n//  - An invalid `Date` makes every predicate `false` (a `NaN` timestamp compares false against\n//    everything, including itself). No predicate throws — callers filter with `isValidDate`.\n//  - A REVERSED range (`start` after `end`) is EMPTY, not auto-normalized: `isBetween` returns `false`.\n//    Silently swapping the bounds would hide a caller bug behind a plausible answer, and the same rule\n//    holds in `Interval.ts` so the whole slice reads one way.\n\nimport { startOfWeek, type WeekStartsOn } from './Boundaries';\nimport { cloneDate } from './Internals';\nimport { isValidDate } from './IsoDate';\n\n/** Tunes whether a range test counts its bounds. */\nexport interface BetweenOptions {\n  /** Count `start`/`end` themselves as inside the range. Defaults to `true`. */\n  readonly inclusive?: boolean;\n}\n\n/** True when both dates fall on the same local calendar day. */\nexport function isSameDay(a: Date, b: Date): boolean {\n  return (\n    a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth() && a.getDate() === b.getDate()\n  );\n}\n\n/**\n * True when both dates fall in the same week. `weekStartsOn` defaults to `1` (Monday, ISO-8601) and\n * must match the value used elsewhere in the same calendar — Dec 31 and Jan 1 can share a week.\n */\nexport function isSameWeek(a: Date, b: Date, weekStartsOn: WeekStartsOn = 1): boolean {\n  return startOfWeek(a, weekStartsOn).getTime() === startOfWeek(b, weekStartsOn).getTime();\n}\n\n/** True when both dates fall in the same month of the same year. */\nexport function isSameMonth(a: Date, b: Date): boolean {\n  return a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth();\n}\n\n/** True when both dates fall in the same calendar year. */\nexport function isSameYear(a: Date, b: Date): boolean {\n  return a.getFullYear() === b.getFullYear();\n}\n\n/** True when `date` is strictly earlier than `other` (millisecond precision). */\nexport function isBefore(date: Date, other: Date): boolean {\n  return date.getTime() < other.getTime();\n}\n\n/** True when `date` is strictly later than `other` (millisecond precision). */\nexport function isAfter(date: Date, other: Date): boolean {\n  return date.getTime() > other.getTime();\n}\n\n/**\n * True when `date` falls in `[start, end]` — bounds included by default, excluded with\n * `{ inclusive: false }`. Returns `false` for a reversed range (`start` after `end`) and for any\n * invalid input; the bounds are never swapped for you.\n */\nexport function isBetween(date: Date, start: Date, end: Date, options?: BetweenOptions): boolean {\n  const value = date.getTime();\n  const from = start.getTime();\n  const to = end.getTime();\n  if (Number.isNaN(value) || Number.isNaN(from) || Number.isNaN(to)) return false;\n  if (from > to) return false;\n  return options?.inclusive === false ? value > from && value < to : value >= from && value <= to;\n}\n\n/** True when `date` falls on the same local day as `now` (defaults to the current clock; inject for tests). */\nexport function isToday(date: Date, now: Date = new Date()): boolean {\n  return isSameDay(date, now);\n}\n\n/** True when `date` is strictly before `now` (defaults to the current clock; inject for tests). */\nexport function isPast(date: Date, now: Date = new Date()): boolean {\n  return isBefore(date, now);\n}\n\n/** True when `date` is strictly after `now` (defaults to the current clock; inject for tests). */\nexport function isFuture(date: Date, now: Date = new Date()): boolean {\n  return isAfter(date, now);\n}\n\n// Shared scan for `minDate`/`maxDate`. Invalid dates are skipped so one bad entry can't win by way of a\n// `NaN` comparison; if every input is invalid the (invalid) first one is returned so the arity contract\n// — \"at least one date in, exactly one date out\" — never degrades into `null`.\nfunction select(first: Date, rest: readonly Date[], keep: (candidate: number, best: number) => boolean): Date {\n  const candidates = [first, ...rest].filter(isValidDate);\n  let best = candidates.at(0) ?? first;\n  for (const candidate of candidates) {\n    if (keep(candidate.getTime(), best.getTime())) best = candidate;\n  }\n  return cloneDate(best);\n}\n\n/** Returns a copy of the earliest of the given dates. Invalid dates are ignored unless all of them are. */\nexport function minDate(first: Date, ...rest: readonly Date[]): Date {\n  return select(first, rest, (candidate, best) => candidate < best);\n}\n\n/** Returns a copy of the latest of the given dates. Invalid dates are ignored unless all of them are. */\nexport function maxDate(first: Date, ...rest: readonly Date[]): Date {\n  return select(first, rest, (candidate, best) => candidate > best);\n}\n\n/**\n * Returns a copy of `date` pulled inside `[min, max]`. Either bound may be omitted or `null` to leave\n * that side open. Bounds are applied low-then-high, so a caller-inverted pair (`min` after `max`)\n * resolves to `max`.\n */\nexport function clampDate(date: Date, min?: Date | null, max?: Date | null): Date {\n  let result = date;\n  if (min != null && isBefore(result, min)) result = min;\n  if (max != null && isAfter(result, max)) result = max;\n  return cloneDate(result);\n}\n","// Signed distance between two dates, in whole units.\n//\n// ARGUMENT ORDER is `(from, to)` and the result is POSITIVE when `to` is later — the same order the\n// existing `daysBetween`/`minutesBetween` helpers in `presentation/forms/DateExtensions` already use.\n// Note this is the REVERSE of `date-fns`, whose `differenceInDays(dateLeft, dateRight)` computes\n// left − right; the parameter names are the reminder.\n//\n// TRUNCATION, never rounding: a partial trailing unit does not count, and truncation is toward zero, so\n// `differenceInX(a, b) === -differenceInX(b, a)` holds for every unit. 25 hours apart = 1 day; 23 hours\n// apart = 0 days. The one exception is internal: the day/week calculation rounds the raw millisecond\n// quotient because a DST day is 23 or 25 hours long and would otherwise truncate to a day short — both\n// endpoints are snapped to local start-of-day first, so what is being rounded is a whole-day quantity\n// that only DST perturbed. That makes day differences CALENDAR-day differences: Mar 15 23:00 → Mar 16\n// 01:00 is 1 day apart, not 0, which is what a calendar UI means by \"1 day\".\n//\n// Month/year differences are calendar-based and agree with `addMonths` clamping: Jan 31 → Feb 28 is a\n// full 1 month, because `addMonths(Jan 31, 1)` lands exactly on Feb 28.\n\nimport { addMonths } from './Arithmetic';\nimport { startOfDay } from './Boundaries';\nimport { MS_PER_DAY, MS_PER_HOUR, MS_PER_MINUTE, MS_PER_SECOND } from './Internals';\n\n/** Signed whole SECONDS from `from` to `to`, truncated toward zero. Positive when `to` is later. */\nexport function differenceInSeconds(from: Date, to: Date): number {\n  return Math.trunc((to.getTime() - from.getTime()) / MS_PER_SECOND);\n}\n\n/** Signed whole MINUTES from `from` to `to`, truncated toward zero. Positive when `to` is later. */\nexport function differenceInMinutes(from: Date, to: Date): number {\n  return Math.trunc((to.getTime() - from.getTime()) / MS_PER_MINUTE);\n}\n\n/** Signed whole HOURS of elapsed time from `from` to `to`, truncated toward zero. Positive when `to` is later. */\nexport function differenceInHours(from: Date, to: Date): number {\n  return Math.trunc((to.getTime() - from.getTime()) / MS_PER_HOUR);\n}\n\n/**\n * Signed CALENDAR days from `from` to `to`. Both endpoints are snapped to local start-of-day first, so\n * the result counts date boundaries crossed rather than 24-hour blocks, and a DST transition never\n * produces an off-by-one. Positive when `to` is later.\n */\nexport function differenceInDays(from: Date, to: Date): number {\n  return Math.round((startOfDay(to).getTime() - startOfDay(from).getTime()) / MS_PER_DAY);\n}\n\n/**\n * Signed whole WEEKS from `from` to `to`, derived from {@link differenceInDays} and truncated toward\n * zero — 13 calendar days apart is 1 week. Positive when `to` is later.\n */\nexport function differenceInWeeks(from: Date, to: Date): number {\n  return Math.trunc(differenceInDays(from, to) / 7);\n}\n\n/**\n * Signed whole calendar MONTHS from `from` to `to`, truncated toward zero — a partial trailing month is\n * dropped, so Jan 15 → Feb 14 is 0. Agrees with `addMonths` clamping (Jan 31 → Feb 28 is 1). Positive\n * when `to` is later.\n */\nexport function differenceInMonths(from: Date, to: Date): number {\n  const target = to.getTime();\n  let months = (to.getFullYear() - from.getFullYear()) * 12 + (to.getMonth() - from.getMonth());\n  if (Number.isNaN(months) || Number.isNaN(target)) return NaN;\n\n  // The field arithmetic above overshoots whenever the day-of-month (or time-of-day) hasn't been\n  // reached yet; step back one month in that case so the count is whole units only.\n  if (months > 0 && addMonths(from, months).getTime() > target) months -= 1;\n  else if (months < 0 && addMonths(from, months).getTime() < target) months += 1;\n  return months;\n}\n\n/**\n * Signed whole calendar YEARS from `from` to `to`, derived from {@link differenceInMonths} and truncated\n * toward zero — the usual \"age in years\" calculation. Positive when `to` is later.\n */\nexport function differenceInYears(from: Date, to: Date): number {\n  return Math.trunc(differenceInMonths(from, to) / 12);\n}\n","// Date ranges — the primitives a calendar grid, a range picker, and a scheduling view are built from.\n//\n// A REVERSED range is EMPTY across this whole slice (same rule as `isBetween`): `eachDayOfInterval`\n// returns `[]`, `isWithinInterval` and `overlaps` return `false`. The bounds are never swapped for you —\n// a reversed range is a caller bug, and normalizing it would return a plausible answer that hides it.\n// Invalid dates behave the same way, so neither function can spin: the loop guard compares against `NaN`\n// and exits immediately.\n//\n// The two membership tests use DIFFERENT bound semantics on purpose, because they answer different\n// questions:\n//  - `isWithinInterval` is a POINT-in-range test → bounds INCLUSIVE. \"Is this day inside the selected\n//    range\" must count the first and last day of the selection.\n//  - `overlaps` is an INTERVAL-vs-INTERVAL test → bounds HALF-OPEN `[start, end)` by default. Two\n//    back-to-back meetings (09:00-10:00 and 10:00-11:00) do not conflict, which is the answer every\n//    scheduler wants. Pass `{ inclusive: true }` for closed-range semantics, where a shared endpoint\n//    does count as an overlap.\n\nimport { addDays } from './Arithmetic';\nimport { startOfDay } from './Boundaries';\nimport { isBetween } from './Comparison';\n\n/** A date range with inclusive bounds. A reversed range (`start` after `end`) is treated as empty. */\nexport interface DateInterval {\n  /** Lower bound of the range. */\n  readonly start: Date;\n\n  /** Upper bound of the range. */\n  readonly end: Date;\n}\n\n/** Tunes whether an overlap test counts a shared endpoint. */\nexport interface OverlapOptions {\n  /**\n   * Treat both ranges as closed `[start, end]`, so ranges that merely touch at an endpoint count as\n   * overlapping. Defaults to `false` (half-open `[start, end)` — touching ranges do not overlap).\n   */\n  readonly inclusive?: boolean;\n}\n\n/**\n * Returns one `Date` per calendar day from `start` to `end`, both ends INCLUSIVE, each snapped to local\n * start-of-day. Returns `[]` when the range is reversed or either bound is invalid.\n *\n * Day stepping is calendar-based (not `+24h`), so a DST transition inside the range neither duplicates\n * nor skips a day.\n */\nexport function eachDayOfInterval(start: Date, end: Date): Date[] {\n  const last = startOfDay(end).getTime();\n  const days: Date[] = [];\n  let cursor = startOfDay(start);\n\n  while (cursor.getTime() <= last) {\n    days.push(cursor);\n    cursor = addDays(cursor, 1);\n  }\n  return days;\n}\n\n/**\n * True when `date` falls inside `interval`, bounds INCLUSIVE. Returns `false` for a reversed interval or\n * any invalid date. Compares at millisecond precision — pass day boundaries\n * (`startOfDay`/`endOfDay`) when a whole-day test is meant.\n */\nexport function isWithinInterval(date: Date, interval: DateInterval): boolean {\n  return isBetween(date, interval.start, interval.end);\n}\n\n/**\n * True when ranges `a` and `b` share any time. Half-open by default, so ranges that only touch at an\n * endpoint do NOT overlap; pass `{ inclusive: true }` to count a shared endpoint as an overlap.\n * Returns `false` when either range is reversed or holds an invalid date.\n *\n * A zero-length range (`start` equal to `end`) never overlaps anything under the default half-open\n * semantics; it does under `{ inclusive: true }`.\n */\nexport function overlaps(a: DateInterval, b: DateInterval, options?: OverlapOptions): boolean {\n  const aStart = a.start.getTime();\n  const aEnd = a.end.getTime();\n  const bStart = b.start.getTime();\n  const bEnd = b.end.getTime();\n\n  if (Number.isNaN(aStart) || Number.isNaN(aEnd) || Number.isNaN(bStart) || Number.isNaN(bEnd)) return false;\n  if (aStart > aEnd || bStart > bEnd) return false;\n\n  if (options?.inclusive === true) return aStart <= bEnd && bStart <= aEnd;\n\n  // A zero-length range spans no time at all, so under half-open semantics it intersects nothing — the\n  // bare `aStart < bEnd && bStart < aEnd` test would otherwise report an overlap for a degenerate range\n  // that happens to sit strictly INSIDE the other, but not for one sitting on its boundary. Callers\n  // asking \"is this instant inside that range\" want `isWithinInterval`, which is inclusive by design.\n  if (aStart === aEnd || bStart === bEnd) return false;\n\n  return aStart < bEnd && bStart < aEnd;\n}\n"],"names":[],"mappings":"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"}

package/dist/foundation/device/Breakpoints.d.ts

@@ -0,0 +1,54 @@
+/** A breakpoint scale — each key (`sm`, `md`, …) mapped to its minimum viewport width in CSS pixels. */
+export type BreakpointScale = Readonly<Record<string, number>>;
+/**
+ * Tailwind v4's default breakpoint scale, in CSS pixels. Opt-in: pass it to `useBreakpoint` explicitly. An app
+ * that customised its `@theme` breakpoints must pass its own map instead, or JS and CSS will disagree.
+ */
+export declare const TAILWIND_BREAKPOINTS: {
+    /** ≥ 640px. */
+    readonly sm: 640;
+    /** ≥ 768px. */
+    readonly md: 768;
+    /** ≥ 1024px. */
+    readonly lg: 1024;
+    /** ≥ 1280px. */
+    readonly xl: 1280;
+    /** ≥ 1536px. */
+    readonly '2xl': 1536;
+};
+/**
+ * How many breakpoints a scale may contain. `useBreakpoint` fans out to exactly this many `useMediaQuery` calls;
+ * eight covers every mainstream scale with room to spare (Tailwind ships 5, Bootstrap 6). See `UseBreakpoint.ts`
+ * for why the count has to be a compile-time constant at all.
+ */
+export declare const MAX_BREAKPOINTS = 8;
+/** One breakpoint compiled to the media query that detects it. */
+export interface BreakpointQuery<TKey extends string = string> {
+    /** The scale key this query stands for. */
+    readonly key: TKey;
+    /** The minimum viewport width, in CSS pixels. */
+    readonly minWidth: number;
+    /** The `(min-width: …px)` string to hand to `matchMedia`. */
+    readonly query: string;
+}
+/**
+ * Compiles a scale into widest-first `(min-width: …)` queries.
+ *
+ * Entries whose width is not a finite number `>= 0` are dropped: a malformed scale must not emit
+ * `(min-width: NaNpx)`, which `matchMedia` accepts and then never matches, quietly skewing the resolved
+ * breakpoint instead of failing.
+ *
+ * @param scale The caller's breakpoint map.
+ * @returns The scale's valid entries as queries, widest first.
+ */
+export declare function toBreakpointQueries<TScale extends BreakpointScale>(scale: TScale): readonly BreakpointQuery<Extract<keyof TScale, string>>[];
+/**
+ * Picks the active breakpoint from a widest-first query list and the match results for it.
+ *
+ * @param queries Compiled queries, widest first, as returned by {@link toBreakpointQueries}.
+ * @param matches Match results positionally aligned with `queries`. A shorter array reads as "did not match" for
+ * the missing tail, which is how a scale larger than {@link MAX_BREAKPOINTS} loses its narrowest entries.
+ * @returns The key of the widest matching breakpoint, or `null` when the viewport is narrower than every entry —
+ * the implicit mobile-first base band, which by definition has no key of its own.
+ */
+export declare function resolveBreakpoint<TKey extends string>(queries: readonly BreakpointQuery<TKey>[], matches: readonly boolean[]): TKey | null;

package/dist/foundation/device/DisplayMode.d.ts

@@ -0,0 +1,13 @@
+/** How the document is being presented — the values of the CSS `display-mode` media feature. */
+export declare const DisplayMode: {
+    /** Installed and running in its own window with no browser chrome. The usual "is this a PWA" answer. */
+    readonly Standalone: "standalone";
+    /** Filling the screen with no OS chrome either — kiosk displays, the Fullscreen API. */
+    readonly Fullscreen: "fullscreen";
+    /** Own window with a minimal navigation strip (back / reload). Installed, but not chrome-free. */
+    readonly MinimalUi: "minimal-ui";
+    /** An ordinary browser tab. Also the SSR answer. */
+    readonly Browser: "browser";
+};
+/** One of the {@link DisplayMode} values. */
+export type DisplayMode = (typeof DisplayMode)[keyof typeof DisplayMode];

package/dist/foundation/device/Platform.d.ts

@@ -0,0 +1,27 @@
+/** The coarse OS families this slice distinguishes. */
+export declare const Platform: {
+    /** macOS, iOS, or iPadOS. */
+    readonly Apple: "apple";
+    /** Any Windows desktop. */
+    readonly Windows: "windows";
+    /** Android phones and tablets. */
+    readonly Android: "android";
+    /** Desktop Linux, X11, and ChromeOS — all Ctrl-keyed, all Linux-idiomatic in their affordances. */
+    readonly Linux: "linux";
+    /** Nothing recognisable — SSR, a stripped user agent, or a platform outside the four above. */
+    readonly Unknown: "unknown";
+};
+/** One of the {@link Platform} families. */
+export type Platform = (typeof Platform)[keyof typeof Platform];
+/**
+ * Identifies the OS family. Read this file's header before using it: the answer is for cosmetic, platform-idiomatic
+ * decisions only, never for feature gating.
+ *
+ * Never throws. Returns `'unknown'` under SSR, for an unrecognised platform, and for an empty hint.
+ *
+ * @param hint Forces the string that is matched, instead of reading the environment — makes tests deterministic and
+ * lets a server render for a client whose platform it already knows. Accepts a full user agent, a
+ * `userAgentData.platform` value, or a bare token such as `'Windows'`.
+ * @returns The detected {@link Platform}.
+ */
+export declare function getPlatform(hint?: string): Platform;

package/dist/foundation/device/PointerType.d.ts

@@ -0,0 +1,11 @@
+/** How precise the primary pointing device is, per the CSS `pointer` media feature. */
+export declare const PointerType: {
+    /** Low-precision primary pointer — a finger on a touchscreen, a TV remote. Size hit targets generously. */
+    readonly Coarse: "coarse";
+    /** High-precision primary pointer — a mouse, trackpad, or stylus. Hover affordances are meaningful here. */
+    readonly Fine: "fine";
+    /** No pointing device at all — keyboard- or voice-driven. Also the SSR answer, where nothing is knowable yet. */
+    readonly None: "none";
+};
+/** One of the {@link PointerType} values. */
+export type PointerType = (typeof PointerType)[keyof typeof PointerType];

package/dist/foundation/device/UseBreakpoint.d.ts

@@ -0,0 +1,20 @@
+import { ComputedRef, MaybeRefOrGetter } from 'vue';
+import { BreakpointScale } from './Breakpoints';
+/**
+ * Resolves the active breakpoint from a caller-supplied scale: the key of the widest breakpoint the viewport
+ * currently satisfies.
+ *
+ * No scale is built in — this library is Tailwind-v4 token-driven and the app owns its `@theme` breakpoints. Pass
+ * `TAILWIND_BREAKPOINTS` to opt into Tailwind's defaults, or your own map to match your tokens.
+ *
+ * The scale may be a ref or getter; changing it re-points the existing subscriptions.
+ *
+ * Reads `null` under SSR, where no media query matches. Layout that must be right before JS runs belongs in CSS;
+ * this composable is for behaviour a media query alone cannot express — which list virtualiser to mount, how many
+ * items to prefetch.
+ *
+ * @param scale Breakpoint key to minimum viewport width in CSS pixels. Entries beyond `MAX_BREAKPOINTS`, counted
+ * widest-first, are ignored; invalid widths are dropped.
+ * @returns The active breakpoint key, or `null` when the viewport is narrower than every entry in the scale.
+ */
+export declare function useBreakpoint<TScale extends BreakpointScale>(scale: MaybeRefOrGetter<TScale>): ComputedRef<Extract<keyof TScale, string> | null>;

package/dist/foundation/device/UseDisplayMode.d.ts

@@ -0,0 +1,23 @@
+import { ComputedRef } from 'vue';
+import { DisplayMode } from './DisplayMode';
+/**
+ * Reports how the document is being presented — its {@link DisplayMode}.
+ *
+ * Falls back to `'browser'` when no mode query matches, which is also what SSR and any browser without
+ * `display-mode` support produce. `'browser'` therefore means "an ordinary tab, as far as can be told", not a
+ * proof that the app is uninstalled.
+ *
+ * @returns The active {@link DisplayMode}.
+ */
+export declare function useDisplayMode(): ComputedRef<DisplayMode>;
+/**
+ * Whether the app is running as an installed app rather than in a browser tab — any display mode other than
+ * `'browser'`.
+ *
+ * Reads `false` under SSR and on iOS < 16.4 (see this file's header). Use it to ADD an installed-only affordance
+ * — suppressing an "Install app" prompt, showing a custom title bar — never to withhold functionality, because a
+ * `false` here can mean "installed, but undetectable".
+ *
+ * @returns `true` when the app is presented outside an ordinary browser tab.
+ */
+export declare function useIsInstalled(): ComputedRef<boolean>;

package/dist/foundation/device/UseOnlineStatus.d.ts

@@ -0,0 +1,12 @@
+import { ShallowRef } from 'vue';
+/**
+ * Tracks whether the browser believes it has a network link — seeded optimistically, synced from
+ * `navigator.onLine` on mount, then kept current by the window `online` / `offline` events.
+ *
+ * Reads `true` under SSR and whenever the status cannot be read: an offline banner rendered by a server that has
+ * never met the client is worse than a missing one, and the value corrects on mount either way. Read this file's
+ * header before acting on it — `false` is reliable, `true` only means a link exists.
+ *
+ * @returns `true` while the browser reports a network link.
+ */
+export declare function useOnlineStatus(): Readonly<ShallowRef<boolean>>;

package/dist/foundation/device/UsePointer.d.ts

@@ -0,0 +1,25 @@
+import { ComputedRef } from 'vue';
+import { PointerType } from './PointerType';
+/**
+ * Reports the precision of the primary pointing device — `'fine'` (mouse, trackpad, stylus), `'coarse'` (finger),
+ * or `'none'`.
+ *
+ * Reactive: a tablet gaining a mouse flips `'coarse'` → `'fine'` without a reload.
+ *
+ * Under SSR this reads `'none'` (there are no media features to read) and corrects on hydration. Treat `'none'`
+ * as "no pointer known", not as a fact — never hide an essential affordance behind it.
+ *
+ * @returns The active {@link PointerType}.
+ */
+export declare function usePointerType(): ComputedRef<PointerType>;
+/**
+ * Whether the primary pointing device can hover — the `(hover: hover)` media feature.
+ *
+ * Gate hover-only affordances on this: a tooltip that opens on mouseover, a table row's hover-revealed actions. On
+ * a touchscreen a hover-only control is simply unreachable and needs a tap target or an always-visible equivalent.
+ *
+ * Reads `false` under SSR, so hover-revealed content must never be the only path to an action.
+ *
+ * @returns `true` when the primary pointer can hover.
+ */
+export declare function useHoverCapability(): ComputedRef<boolean>;

package/dist/foundation/device/index.d.ts

@@ -0,0 +1,8 @@
+export { PointerType } from './PointerType';
+export { usePointerType, useHoverCapability } from './UsePointer';
+export { useOnlineStatus } from './UseOnlineStatus';
+export { DisplayMode } from './DisplayMode';
+export { useDisplayMode, useIsInstalled } from './UseDisplayMode';
+export { Platform, getPlatform } from './Platform';
+export { type BreakpointScale, type BreakpointQuery, TAILWIND_BREAKPOINTS, MAX_BREAKPOINTS, toBreakpointQueries, resolveBreakpoint, } from './Breakpoints';
+export { useBreakpoint } from './UseBreakpoint';

package/dist/foundation/device/index.js

@@ -0,0 +1,187 @@
+import { computed, shallowRef, onMounted, toValue } from "vue";
+import { u as useMediaQuery } from "../../chunks/useMediaQuery-DwVcSgGk.js";
+import { u as useEventListener } from "../../chunks/useEventListener-gohT6zGs.js";
+import { i as isApplePlatform } from "../../chunks/Chord-D9Z-j3O0.js";
+const PointerType = {
+  /** Low-precision primary pointer — a finger on a touchscreen, a TV remote. Size hit targets generously. */
+  Coarse: "coarse",
+  /** High-precision primary pointer — a mouse, trackpad, or stylus. Hover affordances are meaningful here. */
+  Fine: "fine",
+  /** No pointing device at all — keyboard- or voice-driven. Also the SSR answer, where nothing is knowable yet. */
+  None: "none"
+};
+const FINE_POINTER_QUERY = "(pointer: fine)";
+const COARSE_POINTER_QUERY = "(pointer: coarse)";
+const HOVER_QUERY = "(hover: hover)";
+function usePointerType() {
+  const fine = useMediaQuery(FINE_POINTER_QUERY);
+  const coarse = useMediaQuery(COARSE_POINTER_QUERY);
+  return computed(() => {
+    if (fine.value) return PointerType.Fine;
+    if (coarse.value) return PointerType.Coarse;
+    return PointerType.None;
+  });
+}
+function useHoverCapability() {
+  const hover = useMediaQuery(HOVER_QUERY);
+  return computed(() => hover.value);
+}
+const globalTarget = () => typeof window === "undefined" ? null : window;
+function readOnlineStatus() {
+  try {
+    if (typeof navigator === "undefined") return true;
+    return navigator.onLine !== false;
+  } catch {
+    return true;
+  }
+}
+function useOnlineStatus() {
+  const online = shallowRef(true);
+  onMounted(() => {
+    online.value = readOnlineStatus();
+  });
+  useEventListener(
+    "online",
+    () => {
+      online.value = true;
+    },
+    globalTarget
+  );
+  useEventListener(
+    "offline",
+    () => {
+      online.value = false;
+    },
+    globalTarget
+  );
+  return online;
+}
+const DisplayMode = {
+  /** Installed and running in its own window with no browser chrome. The usual "is this a PWA" answer. */
+  Standalone: "standalone",
+  /** Filling the screen with no OS chrome either — kiosk displays, the Fullscreen API. */
+  Fullscreen: "fullscreen",
+  /** Own window with a minimal navigation strip (back / reload). Installed, but not chrome-free. */
+  MinimalUi: "minimal-ui",
+  /** An ordinary browser tab. Also the SSR answer. */
+  Browser: "browser"
+};
+const FULLSCREEN_QUERY = "(display-mode: fullscreen)";
+const STANDALONE_QUERY = "(display-mode: standalone)";
+const MINIMAL_UI_QUERY = "(display-mode: minimal-ui)";
+function useDisplayMode() {
+  const fullscreen = useMediaQuery(FULLSCREEN_QUERY);
+  const standalone = useMediaQuery(STANDALONE_QUERY);
+  const minimalUi = useMediaQuery(MINIMAL_UI_QUERY);
+  return computed(() => {
+    if (fullscreen.value) return DisplayMode.Fullscreen;
+    if (standalone.value) return DisplayMode.Standalone;
+    if (minimalUi.value) return DisplayMode.MinimalUi;
+    return DisplayMode.Browser;
+  });
+}
+function useIsInstalled() {
+  const mode = useDisplayMode();
+  return computed(() => mode.value !== DisplayMode.Browser);
+}
+const Platform = {
+  /** macOS, iOS, or iPadOS. */
+  Apple: "apple",
+  /** Any Windows desktop. */
+  Windows: "windows",
+  /** Android phones and tablets. */
+  Android: "android",
+  /** Desktop Linux, X11, and ChromeOS — all Ctrl-keyed, all Linux-idiomatic in their affordances. */
+  Linux: "linux",
+  /** Nothing recognisable — SSR, a stripped user agent, or a platform outside the four above. */
+  Unknown: "unknown"
+};
+function readPlatformSource() {
+  try {
+    if (typeof navigator === "undefined") return "";
+    const nav = navigator;
+    return nav.userAgentData?.platform || nav.platform || nav.userAgent || "";
+  } catch {
+    return "";
+  }
+}
+function getPlatform(hint) {
+  const source = hint ?? readPlatformSource();
+  if (isApplePlatform(source)) return Platform.Apple;
+  if (/android/i.test(source)) return Platform.Android;
+  if (/windows|win32|win64|wow64/i.test(source)) return Platform.Windows;
+  if (/linux|x11|cros|chrome ?os/i.test(source)) return Platform.Linux;
+  return Platform.Unknown;
+}
+const TAILWIND_BREAKPOINTS = {
+  /** ≥ 640px. */
+  sm: 640,
+  /** ≥ 768px. */
+  md: 768,
+  /** ≥ 1024px. */
+  lg: 1024,
+  /** ≥ 1280px. */
+  xl: 1280,
+  /** ≥ 1536px. */
+  "2xl": 1536
+};
+const MAX_BREAKPOINTS = 8;
+function toBreakpointQueries(scale) {
+  return Object.entries(scale).filter(([, minWidth]) => Number.isFinite(minWidth) && minWidth >= 0).sort(([, left], [, right]) => right - left).map(([key, minWidth]) => ({
+    // `Object.entries` widens the key to `string`; by construction it is a key of `scale`.
+    key,
+    minWidth,
+    query: `(min-width: ${minWidth}px)`
+  }));
+}
+function resolveBreakpoint(queries, matches) {
+  for (const [index, entry] of queries.entries()) {
+    if (matches[index] === true) return entry.key;
+  }
+  return null;
+}
+const NEVER_MATCHES = "not all";
+function queryAt(queries, index) {
+  return queries.at(index)?.query ?? NEVER_MATCHES;
+}
+function useBreakpoint(scale) {
+  const queries = computed(() => toBreakpointQueries(toValue(scale)));
+  const match0 = useMediaQuery(() => queryAt(queries.value, 0));
+  const match1 = useMediaQuery(() => queryAt(queries.value, 1));
+  const match2 = useMediaQuery(() => queryAt(queries.value, 2));
+  const match3 = useMediaQuery(() => queryAt(queries.value, 3));
+  const match4 = useMediaQuery(() => queryAt(queries.value, 4));
+  const match5 = useMediaQuery(() => queryAt(queries.value, 5));
+  const match6 = useMediaQuery(() => queryAt(queries.value, 6));
+  const match7 = useMediaQuery(() => queryAt(queries.value, 7));
+  return computed(() => {
+    const matches = [
+      match0.value,
+      match1.value,
+      match2.value,
+      match3.value,
+      match4.value,
+      match5.value,
+      match6.value,
+      match7.value
+    ];
+    return resolveBreakpoint(queries.value, matches);
+  });
+}
+export {
+  DisplayMode,
+  MAX_BREAKPOINTS,
+  Platform,
+  PointerType,
+  TAILWIND_BREAKPOINTS,
+  getPlatform,
+  resolveBreakpoint,
+  toBreakpointQueries,
+  useBreakpoint,
+  useDisplayMode,
+  useHoverCapability,
+  useIsInstalled,
+  useOnlineStatus,
+  usePointerType
+};
+//# sourceMappingURL=index.js.map

package/dist/foundation/device/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../src/foundation/device/PointerType.ts","../../../src/foundation/device/UsePointer.ts","../../../src/foundation/device/UseOnlineStatus.ts","../../../src/foundation/device/DisplayMode.ts","../../../src/foundation/device/UseDisplayMode.ts","../../../src/foundation/device/Platform.ts","../../../src/foundation/device/Breakpoints.ts","../../../src/foundation/device/UseBreakpoint.ts"],"sourcesContent":["// The pointer vocabulary, kept in its own file rather than inlined into the composable so a consumer can switch\n// on `PointerType.Coarse` without pulling Vue into a pure module — the same value/composable split `foundation/shortcuts`\n// uses for `Modifier` vs `UseHotkeys`.\n\n/** How precise the primary pointing device is, per the CSS `pointer` media feature. */\nexport const PointerType = {\n  /** Low-precision primary pointer — a finger on a touchscreen, a TV remote. Size hit targets generously. */\n  Coarse: 'coarse',\n  /** High-precision primary pointer — a mouse, trackpad, or stylus. Hover affordances are meaningful here. */\n  Fine: 'fine',\n  /** No pointing device at all — keyboard- or voice-driven. Also the SSR answer, where nothing is knowable yet. */\n  None: 'none',\n} as const;\n\n/** One of the {@link PointerType} values. */\nexport type PointerType = (typeof PointerType)[keyof typeof PointerType];\n","// Pointer precision and hover capability, read from the CSS `pointer` / `hover` media features through the shared\n// `useMediaQuery`.\n//\n// WHY NOT A USER-AGENT SNIFF: \"is this a touch device\" is not a device question, it is an INPUT question, and the\n// two diverge constantly. A Windows laptop with a touchscreen has both a fine mouse and a coarse finger; an iPad\n// with a Magic Keyboard reports a FINE pointer; a phone in desktop-site mode still has only a finger. A UA string\n// describes none of that, is trivially spoofed, and is frozen or deprecated on every Chromium browser. The media\n// features track the pointer the user is ACTUALLY holding and re-evaluate when it changes.\n//\n// WHY NOT `'ontouchstart' in window` AS THE PRIMARY SIGNAL: it proves the touch EVENT API is implemented, not that\n// a touchscreen is attached — every desktop Chromium build ships the API, so the check reads true on a mouse-only\n// machine and the UI grows finger-sized hit targets nobody needs. It is also a one-shot boolean with no change\n// event, so it can never react to a tablet being docked to a keyboard mid-session. `(pointer: coarse)` answers the\n// question that was actually being asked, and answers it reactively.\n\nimport { computed, type ComputedRef } from 'vue';\n\nimport { useMediaQuery } from '../hooks';\n\nimport { PointerType } from './PointerType';\n\n// `pointer` / `hover` describe the PRIMARY pointing device. The `any-pointer` / `any-hover` variants report every\n// attached device instead, which is the wrong question for layout: a touchscreen laptop matches `any-pointer:\n// coarse` while the user drives it entirely by mouse, and sizing every target for the finger they are not using\n// wastes the screen. Primary is what layout should follow.\nconst FINE_POINTER_QUERY = '(pointer: fine)';\nconst COARSE_POINTER_QUERY = '(pointer: coarse)';\nconst HOVER_QUERY = '(hover: hover)';\n\n/**\n * Reports the precision of the primary pointing device — `'fine'` (mouse, trackpad, stylus), `'coarse'` (finger),\n * or `'none'`.\n *\n * Reactive: a tablet gaining a mouse flips `'coarse'` → `'fine'` without a reload.\n *\n * Under SSR this reads `'none'` (there are no media features to read) and corrects on hydration. Treat `'none'`\n * as \"no pointer known\", not as a fact — never hide an essential affordance behind it.\n *\n * @returns The active {@link PointerType}.\n */\nexport function usePointerType(): ComputedRef<PointerType> {\n  const fine = useMediaQuery(FINE_POINTER_QUERY);\n  const coarse = useMediaQuery(COARSE_POINTER_QUERY);\n\n  // `pointer` names one primary device, so at most one of these matches in practice. `fine` is tested first so\n  // that a browser reporting both resolves to the more capable pointer rather than to a coincidence of ordering.\n  return computed(() => {\n    if (fine.value) return PointerType.Fine;\n    if (coarse.value) return PointerType.Coarse;\n    return PointerType.None;\n  });\n}\n\n/**\n * Whether the primary pointing device can hover — the `(hover: hover)` media feature.\n *\n * Gate hover-only affordances on this: a tooltip that opens on mouseover, a table row's hover-revealed actions. On\n * a touchscreen a hover-only control is simply unreachable and needs a tap target or an always-visible equivalent.\n *\n * Reads `false` under SSR, so hover-revealed content must never be the only path to an action.\n *\n * @returns `true` when the primary pointer can hover.\n */\nexport function useHoverCapability(): ComputedRef<boolean> {\n  const hover = useMediaQuery(HOVER_QUERY);\n  return computed(() => hover.value);\n}\n","// Network reachability — or as much of it as the browser is willing to admit to.\n//\n// WHAT `navigator.onLine` ACTUALLY MEANS: it is `false` only when the browser is certain there is NO network link\n// — airplane mode, Wi-Fi off, cable unplugged. It is `true` the moment a link exists and says NOTHING beyond that.\n// A captive portal nobody has logged into, hotel Wi-Fi that has not been paid for, a dropped VPN, a DNS failure,\n// or an API that is simply down all report `true`. So `false` is trustworthy and `true` is a hint.\n//\n// USE ACCORDINGLY: explain a failure that already happened (\"you appear to be offline\"), defer a retry, pause a\n// poll. Never treat `true` as a precondition — \"we are online, so this request will succeed\" is exactly the\n// inference this value cannot support. Proving the server that matters is reachable takes a request to it, which\n// is `foundation/http`'s job and not this slice's.\n//\n// The `online` / `offline` events bind through `foundation/hooks`' `useEventListener` rather than a hand-rolled\n// `addEventListener`, so handler identity, attach options, and teardown follow the same rules as every other\n// listener in the library. The target is a GETTER, not a module constant: resolving `window` at module scope\n// would evaluate during a server render, and the lazy getter is the same shape `useEventListener` uses for its\n// own default.\n\nimport { onMounted, shallowRef, type ShallowRef } from 'vue';\n\nimport { useEventListener } from '../hooks';\n\n/** Resolved lazily so importing this module in an SSR pass never touches `window`. */\nconst globalTarget = (): Window | null => (typeof window === 'undefined' ? null : window);\n\n/**\n * Reads `navigator.onLine`, defaulting to online when there is no `navigator` (SSR), when the property is missing\n * (a partial polyfill), or when the read throws. Optimistic by design — see the note on the composable.\n */\nfunction readOnlineStatus(): boolean {\n  try {\n    if (typeof navigator === 'undefined') return true;\n    return navigator.onLine !== false;\n  } catch {\n    return true;\n  }\n}\n\n/**\n * Tracks whether the browser believes it has a network link — seeded optimistically, synced from\n * `navigator.onLine` on mount, then kept current by the window `online` / `offline` events.\n *\n * Reads `true` under SSR and whenever the status cannot be read: an offline banner rendered by a server that has\n * never met the client is worse than a missing one, and the value corrects on mount either way. Read this file's\n * header before acting on it — `false` is reliable, `true` only means a link exists.\n *\n * @returns `true` while the browser reports a network link.\n */\nexport function useOnlineStatus(): Readonly<ShallowRef<boolean>> {\n  // Seeded `true` rather than read at setup: `readOnlineStatus` answers `true` under SSR anyway, and seeding a\n  // constant keeps `navigator` out of the setup pass entirely.\n  const online = shallowRef(true);\n\n  // Re-read once on mount. Two gaps the events alone can never close: the seed was unconditional, and the link\n  // can flip between setup and the listeners attaching.\n  onMounted(() => {\n    online.value = readOnlineStatus();\n  });\n\n  useEventListener(\n    'online',\n    () => {\n      online.value = true;\n    },\n    globalTarget,\n  );\n  useEventListener(\n    'offline',\n    () => {\n      online.value = false;\n    },\n    globalTarget,\n  );\n\n  return online;\n}\n","// The display-mode vocabulary. Split from its composable for the same reason as `PointerType` — a consumer\n// comparing against `DisplayMode.Standalone` should not have to import Vue to do it.\n\n/** How the document is being presented — the values of the CSS `display-mode` media feature. */\nexport const DisplayMode = {\n  /** Installed and running in its own window with no browser chrome. The usual \"is this a PWA\" answer. */\n  Standalone: 'standalone',\n  /** Filling the screen with no OS chrome either — kiosk displays, the Fullscreen API. */\n  Fullscreen: 'fullscreen',\n  /** Own window with a minimal navigation strip (back / reload). Installed, but not chrome-free. */\n  MinimalUi: 'minimal-ui',\n  /** An ordinary browser tab. Also the SSR answer. */\n  Browser: 'browser',\n} as const;\n\n/** One of the {@link DisplayMode} values. */\nexport type DisplayMode = (typeof DisplayMode)[keyof typeof DisplayMode];\n","// Display mode — how the document is presented, and by extension whether the app was installed.\n//\n// Read entirely through `display-mode` media queries on the shared `useMediaQuery`, which makes the answer\n// reactive: a window entering or leaving fullscreen updates live, where the one-shot check at startup that most\n// codebases write would be stale for the rest of the session.\n//\n// QUERY ORDER IS LOAD-BEARING, and is not alphabetical. Browsers do not reliably report exactly one match — a\n// standalone window driven into fullscreen can satisfy both `(display-mode: fullscreen)` and\n// `(display-mode: standalone)` — so the most specific presentation is tested first and wins.\n//\n// KNOWN GAP — iOS Safari only supports `display-mode` from 16.4. On older iOS an installed home-screen app reports\n// `'browser'` here. Its legacy signal is the non-standard `navigator.standalone`, deliberately NOT read: this\n// slice keeps a single detection mechanism, and adding a second, non-reactive sniffer for one stale OS version\n// buys a narrow tail at the cost of two code paths that can disagree. A consumer that needs that tail can read\n// `navigator.standalone` itself and OR it in.\n\nimport { computed, type ComputedRef } from 'vue';\n\nimport { useMediaQuery } from '../hooks';\n\nimport { DisplayMode } from './DisplayMode';\n\nconst FULLSCREEN_QUERY = '(display-mode: fullscreen)';\nconst STANDALONE_QUERY = '(display-mode: standalone)';\nconst MINIMAL_UI_QUERY = '(display-mode: minimal-ui)';\n\n/**\n * Reports how the document is being presented — its {@link DisplayMode}.\n *\n * Falls back to `'browser'` when no mode query matches, which is also what SSR and any browser without\n * `display-mode` support produce. `'browser'` therefore means \"an ordinary tab, as far as can be told\", not a\n * proof that the app is uninstalled.\n *\n * @returns The active {@link DisplayMode}.\n */\nexport function useDisplayMode(): ComputedRef<DisplayMode> {\n  const fullscreen = useMediaQuery(FULLSCREEN_QUERY);\n  const standalone = useMediaQuery(STANDALONE_QUERY);\n  const minimalUi = useMediaQuery(MINIMAL_UI_QUERY);\n\n  return computed(() => {\n    if (fullscreen.value) return DisplayMode.Fullscreen;\n    if (standalone.value) return DisplayMode.Standalone;\n    if (minimalUi.value) return DisplayMode.MinimalUi;\n    return DisplayMode.Browser;\n  });\n}\n\n/**\n * Whether the app is running as an installed app rather than in a browser tab — any display mode other than\n * `'browser'`.\n *\n * Reads `false` under SSR and on iOS < 16.4 (see this file's header). Use it to ADD an installed-only affordance\n * — suppressing an \"Install app\" prompt, showing a custom title bar — never to withhold functionality, because a\n * `false` here can mean \"installed, but undetectable\".\n *\n * @returns `true` when the app is presented outside an ordinary browser tab.\n */\nexport function useIsInstalled(): ComputedRef<boolean> {\n  const mode = useDisplayMode();\n  return computed(() => mode.value !== DisplayMode.Browser);\n}\n","// Platform identification — the LAST-RESORT signal in this slice, and the only one here that asks what the\n// environment IS rather than what it can DO.\n//\n// USE IT ONLY FOR COSMETICS: rendering `⌘K` vs `Ctrl+K` in a shortcut hint, naming a modifier in help text,\n// labelling a button \"Show in Finder\" vs \"Show in Explorer\". NEVER gate a feature on it. A user agent is freely\n// spoofed, `navigator.platform` is deprecated, Chromium freezes its UA, and every question worth gating on\n// (pointer precision, hover, display mode, viewport) has a real capability query in this slice that answers it\n// truthfully. Platform sniffing gates on a guess; a media feature gates on the fact.\n//\n// The Apple branch delegates to `foundation/shortcuts`' `isApplePlatform` rather than re-sniffing: that predicate\n// already backs `mod` → ⌘ resolution, and two sniffers that drift apart would render a ⌘ hint on a Ctrl machine.\n// This file adds the other three families around it and reuses its exact source-precedence rules.\n//\n// Ordering is load-bearing. Android is tested before Linux because Android's UA names the Linux kernel; the\n// Windows pattern is anchored on real tokens (`Windows` / `Win32` / `Win64` / `WOW64`) rather than a bare `win`,\n// which would misread `Darwin` — a substring collision that silently turns a Mac into a PC.\n\nimport { isApplePlatform } from '../shortcuts';\n\n/** The coarse OS families this slice distinguishes. */\nexport const Platform = {\n  /** macOS, iOS, or iPadOS. */\n  Apple: 'apple',\n  /** Any Windows desktop. */\n  Windows: 'windows',\n  /** Android phones and tablets. */\n  Android: 'android',\n  /** Desktop Linux, X11, and ChromeOS — all Ctrl-keyed, all Linux-idiomatic in their affordances. */\n  Linux: 'linux',\n  /** Nothing recognisable — SSR, a stripped user agent, or a platform outside the four above. */\n  Unknown: 'unknown',\n} as const;\n\n/** One of the {@link Platform} families. */\nexport type Platform = (typeof Platform)[keyof typeof Platform];\n\n/**\n * Reads the best available platform string, preferring the modern `userAgentData.platform` over the deprecated\n * `navigator.platform` and falling back to the full user agent. Mirrors `isApplePlatform`'s precedence exactly so\n * both predicates always judge the same text. Returns `''` under SSR or if any read throws.\n */\nfunction readPlatformSource(): string {\n  try {\n    if (typeof navigator === 'undefined') return '';\n    const nav = navigator as Navigator & { userAgentData?: { platform?: string } };\n    return nav.userAgentData?.platform || nav.platform || nav.userAgent || '';\n  } catch {\n    // A throwing `navigator` getter (polyfill, hardened environment) reads as \"no information\", never as a crash.\n    return '';\n  }\n}\n\n/**\n * Identifies the OS family. Read this file's header before using it: the answer is for cosmetic, platform-idiomatic\n * decisions only, never for feature gating.\n *\n * Never throws. Returns `'unknown'` under SSR, for an unrecognised platform, and for an empty hint.\n *\n * @param hint Forces the string that is matched, instead of reading the environment — makes tests deterministic and\n * lets a server render for a client whose platform it already knows. Accepts a full user agent, a\n * `userAgentData.platform` value, or a bare token such as `'Windows'`.\n * @returns The detected {@link Platform}.\n */\nexport function getPlatform(hint?: string): Platform {\n  const source = hint ?? readPlatformSource();\n\n  if (isApplePlatform(source)) return Platform.Apple;\n  if (/android/i.test(source)) return Platform.Android;\n  if (/windows|win32|win64|wow64/i.test(source)) return Platform.Windows;\n  if (/linux|x11|cros|chrome ?os/i.test(source)) return Platform.Linux;\n  return Platform.Unknown;\n}\n","// The breakpoint model — pure, DOM-free, and deliberately WITHOUT a built-in scale.\n//\n// WHY NO DEFAULT SCALE: this library is Tailwind-v4 token-driven, so the app owns its breakpoints in its `@theme`\n// block. A scale hardcoded here would be a second source of truth that silently disagrees with the CSS the same\n// app ships — a layout that switches at 768px in JS and 720px in CSS is a bug no test in this repo could see.\n// `TAILWIND_BREAKPOINTS` is offered as a constant the caller may opt into, never as a fallback a composable reaches for.\n//\n// Queries are plain `(min-width: …)` sorted WIDEST FIRST, so \"the first query that matches\" is the active\n// breakpoint. Mutually-exclusive bands (`min` and `max` together) are the alternative and were rejected: bands\n// need a sentinel max for the widest entry and a sub-pixel gap between neighbours (`max-width: 767.98px`), and\n// both are places for an off-by-one to hide. Independent min-width queries have neither, and match how the\n// mobile-first CSS beside them already cascades.\n\n/** A breakpoint scale — each key (`sm`, `md`, …) mapped to its minimum viewport width in CSS pixels. */\nexport type BreakpointScale = Readonly<Record<string, number>>;\n\n/**\n * Tailwind v4's default breakpoint scale, in CSS pixels. Opt-in: pass it to `useBreakpoint` explicitly. An app\n * that customised its `@theme` breakpoints must pass its own map instead, or JS and CSS will disagree.\n */\nexport const TAILWIND_BREAKPOINTS = {\n  /** ≥ 640px. */\n  sm: 640,\n  /** ≥ 768px. */\n  md: 768,\n  /** ≥ 1024px. */\n  lg: 1024,\n  /** ≥ 1280px. */\n  xl: 1280,\n  /** ≥ 1536px. */\n  '2xl': 1536,\n} as const;\n\n/**\n * How many breakpoints a scale may contain. `useBreakpoint` fans out to exactly this many `useMediaQuery` calls;\n * eight covers every mainstream scale with room to spare (Tailwind ships 5, Bootstrap 6). See `UseBreakpoint.ts`\n * for why the count has to be a compile-time constant at all.\n */\nexport const MAX_BREAKPOINTS = 8;\n\n/** One breakpoint compiled to the media query that detects it. */\nexport interface BreakpointQuery<TKey extends string = string> {\n  /** The scale key this query stands for. */\n  readonly key: TKey;\n  /** The minimum viewport width, in CSS pixels. */\n  readonly minWidth: number;\n  /** The `(min-width: …px)` string to hand to `matchMedia`. */\n  readonly query: string;\n}\n\n/**\n * Compiles a scale into widest-first `(min-width: …)` queries.\n *\n * Entries whose width is not a finite number `>= 0` are dropped: a malformed scale must not emit\n * `(min-width: NaNpx)`, which `matchMedia` accepts and then never matches, quietly skewing the resolved\n * breakpoint instead of failing.\n *\n * @param scale The caller's breakpoint map.\n * @returns The scale's valid entries as queries, widest first.\n */\nexport function toBreakpointQueries<TScale extends BreakpointScale>(\n  scale: TScale,\n): readonly BreakpointQuery<Extract<keyof TScale, string>>[] {\n  return Object.entries(scale)\n    .filter(([, minWidth]) => Number.isFinite(minWidth) && minWidth >= 0)\n    .sort(([, left], [, right]) => right - left)\n    .map(([key, minWidth]) => ({\n      // `Object.entries` widens the key to `string`; by construction it is a key of `scale`.\n      key: key as Extract<keyof TScale, string>,\n      minWidth,\n      query: `(min-width: ${minWidth}px)`,\n    }));\n}\n\n/**\n * Picks the active breakpoint from a widest-first query list and the match results for it.\n *\n * @param queries Compiled queries, widest first, as returned by {@link toBreakpointQueries}.\n * @param matches Match results positionally aligned with `queries`. A shorter array reads as \"did not match\" for\n * the missing tail, which is how a scale larger than {@link MAX_BREAKPOINTS} loses its narrowest entries.\n * @returns The key of the widest matching breakpoint, or `null` when the viewport is narrower than every entry —\n * the implicit mobile-first base band, which by definition has no key of its own.\n */\nexport function resolveBreakpoint<TKey extends string>(\n  queries: readonly BreakpointQuery<TKey>[],\n  matches: readonly boolean[],\n): TKey | null {\n  for (const [index, entry] of queries.entries()) {\n    if (matches[index] === true) return entry.key;\n  }\n  return null;\n}\n","// The active breakpoint, resolved from a caller-supplied scale.\n//\n// WHY THE FIXED-SLOT FAN-OUT BELOW — the one non-obvious thing in this slice:\n//\n// Every media query in this library must go through `foundation/hooks`' `useMediaQuery`, so there is exactly one\n// `matchMedia` implementation, one subscription model, and one SSR semantic. But the scale belongs to the caller,\n// so the NUMBER of queries is not known at compile time.\n//\n// Vue has no rules-of-hooks call-order constraint, so the React original's reason for a fixed arity is gone — but\n// the fixed arity stays, for a Vue-specific reason that is just as real: a composable's cleanup is registered on\n// the surrounding effect scope, so subscriptions created in a loop are only released when the WHOLE scope dies. A\n// scale that shrank mid-session would leak a live `MediaQueryList` per dropped entry. A FIXED number of\n// `useMediaQuery` calls — `MAX_BREAKPOINTS` of them, always — has no such leak, and the slots a smaller scale\n// leaves over are parked on `'not all'`, a valid media query that can never match.\n//\n// What Vue does buy is that each slot takes a GETTER rather than a fixed string, so a changed scale re-points the\n// existing subscriptions instead of needing a remount. The React version could not do that at all.\n//\n// The slot count below MUST equal `MAX_BREAKPOINTS`. Queries arrive widest-first, so a scale with more entries\n// than slots loses its NARROWEST ones — the widest, which decide the answer on large viewports, always get slots.\n\nimport { computed, toValue, type ComputedRef, type MaybeRefOrGetter } from 'vue';\n\nimport { useMediaQuery } from '../hooks';\n\nimport {\n  resolveBreakpoint,\n  toBreakpointQueries,\n  type BreakpointQuery,\n  type BreakpointScale,\n} from './Breakpoints';\n\n/** A valid media query that never matches — parks the slots a scale smaller than `MAX_BREAKPOINTS` leaves unused. */\nconst NEVER_MATCHES = 'not all';\n\n/** Reads slot `index`'s query string, falling back to the never-matching parking query. */\nfunction queryAt(queries: readonly BreakpointQuery[], index: number): string {\n  return queries.at(index)?.query ?? NEVER_MATCHES;\n}\n\n/**\n * Resolves the active breakpoint from a caller-supplied scale: the key of the widest breakpoint the viewport\n * currently satisfies.\n *\n * No scale is built in — this library is Tailwind-v4 token-driven and the app owns its `@theme` breakpoints. Pass\n * `TAILWIND_BREAKPOINTS` to opt into Tailwind's defaults, or your own map to match your tokens.\n *\n * The scale may be a ref or getter; changing it re-points the existing subscriptions.\n *\n * Reads `null` under SSR, where no media query matches. Layout that must be right before JS runs belongs in CSS;\n * this composable is for behaviour a media query alone cannot express — which list virtualiser to mount, how many\n * items to prefetch.\n *\n * @param scale Breakpoint key to minimum viewport width in CSS pixels. Entries beyond `MAX_BREAKPOINTS`, counted\n * widest-first, are ignored; invalid widths are dropped.\n * @returns The active breakpoint key, or `null` when the viewport is narrower than every entry in the scale.\n */\nexport function useBreakpoint<TScale extends BreakpointScale>(\n  scale: MaybeRefOrGetter<TScale>,\n): ComputedRef<Extract<keyof TScale, string> | null> {\n  const queries = computed(() => toBreakpointQueries(toValue(scale)));\n\n  // Fixed-arity fan-out — see this file's header. Do NOT collapse into a loop or a `.map`: the constant call\n  // count is what keeps a caller-supplied scale from leaking subscriptions as it shrinks.\n  const match0 = useMediaQuery(() => queryAt(queries.value, 0));\n  const match1 = useMediaQuery(() => queryAt(queries.value, 1));\n  const match2 = useMediaQuery(() => queryAt(queries.value, 2));\n  const match3 = useMediaQuery(() => queryAt(queries.value, 3));\n  const match4 = useMediaQuery(() => queryAt(queries.value, 4));\n  const match5 = useMediaQuery(() => queryAt(queries.value, 5));\n  const match6 = useMediaQuery(() => queryAt(queries.value, 6));\n  const match7 = useMediaQuery(() => queryAt(queries.value, 7));\n\n  return computed(() => {\n    // Exactly `MAX_BREAKPOINTS` entries — the invariant the header states. Positionally aligned with `queries`.\n    const matches: readonly boolean[] = [\n      match0.value,\n      match1.value,\n      match2.value,\n      match3.value,\n      match4.value,\n      match5.value,\n      match6.value,\n      match7.value,\n    ];\n\n    return resolveBreakpoint(queries.value, matches) as Extract<keyof TScale, string> | null;\n  });\n}\n"],"names":[],"mappings":"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"}

package/dist/foundation/errors/ErrorChain.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Provides the default cap on how many links a `cause` walk yields. Bounds both a pathological chain
+ * and the size of anything built from one (a log payload, a rendered detail list); 8 covers every real
+ * wrap depth seen in practice with room to spare.
+ */
+export declare const DefaultMaxCauseDepth = 8;
+/**
+ * Reads the underlying failure a value wraps — the standard ES2022 `cause`, as thrown
+ * (`new Error(msg, { cause })`). Returns the raw value, not an `Error`: a `cause` can be anything,
+ * and normalizing it here would hide what was actually attached. `undefined` when there is none.
+ *
+ * Never throws — a `cause` getter that throws reads as absent.
+ */
+export declare function getErrorCause(error: unknown): unknown;
+/**
+ * Walks the `cause` chain from an error down to its root, normalizing each link with `toError`, and
+ * returns the links head-first. Always non-empty — the head normalizes even from `undefined`.
+ *
+ * Terminates on every input. Links are tracked by identity, so a self-referencing (`error.cause ===
+ * error`) or mutually-referencing chain stops at the repeat instead of hanging, and `maxDepth` caps
+ * the rest. Truncation is silent: the tail simply has no further links.
+ */
+export declare function flattenErrorChain(error: unknown, maxDepth?: number): Error[];

package/dist/foundation/errors/ErrorLike.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Defines the structural shape every helper in this slice accepts — anything carrying a string
+ * `message`. Deliberately structural rather than `Error`: a value crossing a realm boundary
+ * (iframe, worker, `structuredClone`), rehydrated from JSON, or built by a library that never
+ * subclassed `Error` all fail `instanceof` while still being perfectly usable errors.
+ */
+export interface ErrorLike {
+    /** The human-readable failure description — the one member that makes a value error-like. */
+    readonly message: string;
+    /** The error kind — `'TypeError'`, `'AbortError'`, a custom tag. Absent on hand-rolled shapes. */
+    readonly name?: string;
+    /** The captured stack trace, when the source recorded one. */
+    readonly stack?: string;
+    /** The machine-readable code — Node's `'ETIMEDOUT'`, a legacy `DOMException` number, an app code. */
+    readonly code?: string | number;
+    /** The underlying failure this one wraps (the standard ES2022 `cause`). Untyped — anything can be thrown. */
+    readonly cause?: unknown;
+}
+/**
+ * Checks whether a value can carry properties at all — `typeof null` is `'object'`, and a function
+ * is a legal throw target. Internal; not barrelled.
+ */
+export declare function isObjectLike(value: unknown): value is object;
+/**
+ * Reads a property without trusting the source. A getter can throw and a `Proxy` `get` trap can
+ * throw, so an unguarded read would turn error handling into a second failure. Internal; not barrelled.
+ */
+export declare function readMember(source: object, key: string): unknown;
+/**
+ * Checks `instanceof Error` without trusting the value — `instanceof` invokes `getPrototypeOf`,
+ * which a `Proxy` trap can throw from. Internal; not barrelled.
+ */
+export declare function isError(value: unknown): value is Error;
+/** Checks whether a value is structurally an {@link ErrorLike} — an object (or function) whose `message` reads as a string. */
+export declare function isErrorLike(value: unknown): value is ErrorLike;

package/dist/foundation/errors/ErrorMessage.d.ts

@@ -0,0 +1,13 @@
+/** Provides the message shown when a caught value carries nothing a person could read. Also the floor when a caller's own fallback is blank. */
+export declare const DefaultErrorMessage = "Something went wrong";
+/**
+ * Extracts the message a UI can show for a caught value — the string itself, or its `message` member.
+ *
+ * Narrower than `toError` on purpose. `toError` is total and must produce *some* `Error`, so it
+ * stringifies whatever it gets; this returns UI copy, so a value with no message (a bare number, `{}`,
+ * a JSON blob, `null`) yields `fallback` rather than rendering machine noise into a toast. Guaranteed
+ * never to return `''` or `'[object Object]'` — a blank `fallback` degrades to {@link DefaultErrorMessage}.
+ *
+ * Never throws: a `message` getter that throws reads as absent.
+ */
+export declare function getErrorMessage(value: unknown, fallback?: string): string;