@inglorious/web 6.3.0 → 6.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/web",
-  "version": "6.3.0",
+  "version": "6.4.0",
   "description": "A new web framework that leverages the power of the Inglorious Store combined with the performance and simplicity of lit-html.",
   "author": "Matteo Antony Mistretta <antony.mistretta@gmail.com> (https://ingloriouscoderz.it)",
   "contributors": [
@@ -33,35 +33,59 @@
       "types": "./types/index.d.ts",
       "import": "./src/index.js"
     },
-    "./compass": {
-      "types": "./types/compass.d.ts",
-      "import": "./src/compass/index.js"
-    },
     "./decorators/with-debounce": {
       "types": "./types/decorators/with-debounce.d.ts",
       "import": "./src/decorators/with-debounce/index.js"
     },
+    "./decorators/with-error-boundary": {
+      "types": "./types/decorators/with-error-boundary.d.ts",
+      "import": "./src/decorators/with-error-boundary/index.js"
+    },
+    "./decorators/with-throttle": {
+      "types": "./types/decorators/with-throttle.d.ts",
+      "import": "./src/decorators/with-throttle/index.js"
+    },
     "./directives/*": {
       "types": "./types/directives/*.d.ts",
       "import": "./src/directives/*.js"
     },
-    "./element-size": {
-      "types": "./types/element-size.d.ts",
-      "import": "./src/element-size/index.js"
-    },
     "./form": {
       "types": "./types/form.d.ts",
       "import": "./src/form/index.js"
     },
-    "./geolocation": {
-      "types": "./types/geolocation.d.ts",
-      "import": "./src/geolocation/index.js"
-    },
     "./hydrate": "./src/hydrate.js",
+    "./mobile": {
+      "types": "./types/mobile.d.ts",
+      "import": "./src/mobile/index.js"
+    },
     "./router": {
       "types": "./types/router.d.ts",
       "import": "./src/router/index.js"
     },
+    "./sensors/compass": {
+      "types": "./types/sensors/compass.d.ts",
+      "import": "./src/sensors/compass/index.js"
+    },
+    "./sensors/element-size": {
+      "types": "./types/sensors/element-size.d.ts",
+      "import": "./src/sensors/element-size/index.js"
+    },
+    "./sensors/geolocation": {
+      "types": "./types/sensors/geolocation.d.ts",
+      "import": "./src/sensors/geolocation/index.js"
+    },
+    "./sensors/media-query": {
+      "types": "./types/sensors/media-query.d.ts",
+      "import": "./src/sensors/media-query/index.js"
+    },
+    "./sensors/network-status": {
+      "types": "./types/sensors/network-status.d.ts",
+      "import": "./src/sensors/network-status/index.js"
+    },
+    "./sensors/page-visibility": {
+      "types": "./types/sensors/page-visibility.d.ts",
+      "import": "./src/sensors/page-visibility/index.js"
+    },
     "./static": {
       "types": "./types/static.d.ts",
       "import": "./src/static.js"

package/src/decorators/with-error-boundary/index.js

@@ -0,0 +1,48 @@
+/**
+ * @typedef {import("../../../types/mount").Api} Api
+ */
+
+/**
+ * Wraps a type's `render` in an error boundary. If the base render throws
+ * synchronously, the caught error is handed to `fallback` and its template is
+ * rendered instead — so one failing entity degrades to a fallback UI rather
+ * than taking down the whole app (every child is rendered through the same
+ * `render`, so there is no isolation without this).
+ *
+ * Because the wrap is deterministic, the *same* error produces the *same*
+ * fallback during SSR and during client hydration, so it never introduces a
+ * hydration mismatch.
+ *
+ * NOTE: like React/Svelte boundaries, this only catches errors thrown *during
+ * render*. Errors thrown later — in event handlers, async work (thunks), or in
+ * lit-html directives committed after `render` returns — are not caught here.
+ * Those are the store phase, not the render phase: handle them as entity
+ * `error` state in your handlers (see e.g. the geolocation type).
+ *
+ * @param {(error: Error, entity: object, api: Api) => unknown} [fallback]
+ *   Renders the fallback UI. Receives the caught error, the entity, and the
+ *   render api. Defaults to logging the error and rendering nothing.
+ * @returns {(type: object) => { render: (entity: object, api: Api) => unknown }}
+ *
+ * @example
+ * // Compose after the base type so the boundary wraps its render.
+ * const types = {
+ *   Chart: [ChartBase, withErrorBoundary((err) => html`<p>Chart failed: ${err.message}</p>`)],
+ * }
+ */
+export function withErrorBoundary(fallback = defaultFallback) {
+  return (type) => ({
+    render(entity, api) {
+      try {
+        return type.render?.(entity, api) ?? ""
+      } catch (error) {
+        return fallback(error, entity, api)
+      }
+    },
+  })
+}
+
+function defaultFallback(error) {
+  console.error("[withErrorBoundary] render failed:", error)
+  return ""
+}

package/src/decorators/with-throttle/index.js

@@ -0,0 +1,107 @@
+import { throttle } from "@inglorious/utils/functions/functions.js"
+
+/**
+ * Wraps selected event handlers of a type with throttling, scoped per-entity.
+ *
+ * By default this is leading-edge only: the first call in a burst runs
+ * immediately, and further calls are dropped until `delay` has elapsed — the
+ * last call of a burst may be lost. Pass `{ hasTrailing: true }` to also invoke
+ * the handler once more after `delay`, using the most recent suppressed
+ * call's arguments, so the final state of a burst is never dropped.
+ *
+ * IMPORTANT: because state is managed with `mutative`, the `entity` object
+ * passed into a handler is a draft proxy that gets revoked as soon as the
+ * current update tick finishes. The leading call always runs synchronously
+ * (same tick as the triggering event), so the draft is still live there —
+ * but a trailing call (when `hasTrailing: true`) fires *later*, on its own
+ * timer, after that draft is dead. To keep one code path safe for both
+ * cases, we never close over `entity` itself across the throttle boundary —
+ * only its primitive `id`. Every time the wrapped handler actually runs, we
+ * re-fetch a live entity from the current state via `api.getEntity(entityId)`.
+ * Primitives and `payload` are safe to hold onto as-is; only draft/entity
+ * references are not.
+ *
+ * @param {number|Object} config - Either a single delay (ms) applied to all
+ *   handlers listed in `handlerNames`, or a map of handlerName -> delay (ms).
+ * @param {string[]} [handlerNames] - Handler names to throttle. Required when
+ *   `config` is a single number; ignored when `config` is a map (its keys
+ *   are used instead).
+ * @param {Object} [options]
+ * @param {boolean} [options.hasTrailing=false] - Whether throttled handlers
+ *   should also fire once more after `delay`, using the last suppressed
+ *   call's arguments. Applies to every handler wrapped by this call.
+ *
+ * @example
+ * // leading-edge only (default): rate-limit a frequent event, last call in
+ * // a burst may be dropped
+ * const types = {
+ *   ScrollTracker: [Base, withThrottle(200, ["scroll"])],
+ * }
+ *
+ * @example
+ * // leading + trailing: never lose the final call of a burst
+ * const types = {
+ *   ResizablePanel: [Base, withThrottle({ resize: 100 }, undefined, { hasTrailing: true })],
+ * }
+ */
+export function withThrottle(
+  config,
+  handlerNames,
+  { hasTrailing = false } = {},
+) {
+  const delays =
+    typeof config === "number"
+      ? Object.fromEntries(handlerNames.map((name) => [name, config]))
+      : config
+
+  return (type) => {
+    // one throttled-fn map per entity, so instances don't share windows
+    const throttledByEntity = new Map()
+
+    const behavior = {}
+
+    for (const handlerName of Object.keys(delays)) {
+      const originalHandler = type[handlerName]
+      if (!originalHandler) continue // nothing to wrap if the base type doesn't define it
+
+      behavior[handlerName] = (entity, payload, api) => {
+        const entityId = entity.id // capture the primitive now, while the draft is live
+
+        let perEntity = throttledByEntity.get(entityId)
+        if (!perEntity) {
+          perEntity = {}
+          throttledByEntity.set(entityId, perEntity)
+        }
+
+        if (!perEntity[handlerName]) {
+          perEntity[handlerName] = throttle(
+            (entityId, payload, api) => {
+              const liveEntity = api.getEntity(entityId) // fresh, live reference
+              if (!liveEntity) return // entity was destroyed before this fired
+              originalHandler(liveEntity, payload, api)
+            },
+            delays[handlerName],
+            { hasTrailing },
+          )
+        }
+
+        perEntity[handlerName](entityId, payload, api)
+      }
+    }
+
+    // clean up any pending windows/trailing calls when the entity is destroyed
+    behavior.destroy = (entity, payload, api) => {
+      const entityId = entity.id // same rule applies here: capture before it's gone
+
+      const perEntity = throttledByEntity.get(entityId)
+      if (perEntity) {
+        Object.values(perEntity).forEach((t) => t.cancel())
+        throttledByEntity.delete(entityId)
+      }
+
+      type.destroy?.(entity, payload, api)
+    }
+
+    return behavior
+  }
+}

package/src/directives/unsafe-svg.js

@@ -0,0 +1 @@
+export { unsafeSVG } from "lit-html/directives/unsafe-svg.js"

package/src/mobile/index.js

@@ -0,0 +1,17 @@
+export function isNative() {
+  const capacitor = globalThis.Capacitor ?? globalThis.window?.Capacitor ?? null
+
+  if (!capacitor) {
+    return false
+  }
+
+  if (typeof capacitor.isNativePlatform === "function") {
+    return capacitor.isNativePlatform()
+  }
+
+  if (typeof capacitor.getPlatform === "function") {
+    return ["android", "ios"].includes(capacitor.getPlatform())
+  }
+
+  return capacitor.isNative === true
+}

package/src/mount.js

@@ -5,14 +5,47 @@
 
 import { html, render } from "lit-html"
 
+/**
+ * Root-level error boundary. Unlike the per-entity `withErrorBoundary`
+ * decorator (which isolates a single failing type's render), this catches
+ * errors thrown by the *root* render function itself — before any entity is
+ * reached (e.g. a missing router entity), or by an unguarded child.
+ *
+ * Without it, a throwing root render takes down the whole app: on the initial
+ * pass it aborts the mount, and inside the store subscription it throws out of
+ * the notify loop on every subsequent update, freezing the UI. Catching it
+ * keeps the subscription alive so one bad tick can't kill the app.
+ *
+ * @param {(api: Api) => TemplateResult | null} renderFn
+ * @param {Api} api
+ * @param {(error: unknown, api: Api) => void} onError
+ * @param {((error: unknown, api: Api) => TemplateResult | null) | undefined} fallback
+ * @returns {{ ok: true, template: TemplateResult | null } | { ok: false, fallback: TemplateResult | null }}
+ */
+function renderRoot(renderFn, api, onError, fallback) {
+  try {
+    return { ok: true, template: renderFn(api) }
+  } catch (error) {
+    onError(error, api)
+    return { ok: false, fallback: fallback ? fallback(error, api) : null }
+  }
+}
+
 /**
  * Mounts a lit-html template to the DOM and subscribes to a store for re-rendering.
  * @param {Store} store - The application state store.
  * @param {(api: Api) => TemplateResult | null} renderFn - The root render function.
  * @param {HTMLElement | DocumentFragment} element - The DOM element to mount the template to.
+ * @param {Object} [options] - Root error-boundary options.
+ * @param {(error: unknown, api: Api) => void} [options.onError] - Called when the
+ *   root render throws. Defaults to `console.error`.
+ * @param {(error: unknown, api: Api) => TemplateResult | null} [options.fallback] -
+ *   Optional fallback template rendered in place of the failed root render.
  * @returns {() => void} An unsubscribe function
  */
-export async function mount(store, renderFn, element) {
+export async function mount(store, renderFn, element, options = {}) {
+  const { onError = defaultOnError, fallback } = options
+
   const api = { ...store._api }
   api.render = createRender(api)
 
@@ -21,20 +54,38 @@ export async function mount(store, renderFn, element) {
   // If we need to hydrate, load the heavy lifting only now
   if (shouldHydrate) {
     const { hydrate } = await import("@lit-labs/ssr-client")
-    const template = renderFn(api)
-    hydrate(template, element)
+    const result = renderRoot(renderFn, api, onError, fallback)
+    if (result.ok) {
+      hydrate(result.template, element)
+    } else if (fallback) {
+      // Can't hydrate a render that threw: replace the server markup with the
+      // fallback via a fresh client render instead.
+      render(result.fallback, element)
+    }
   }
 
   const unsubscribe = store.subscribe(() => {
-    const template = renderFn(api)
-    // Standard render is already in the main bundle (it's small)
-    render(template, element)
+    const result = renderRoot(renderFn, api, onError, fallback)
+    if (result.ok) {
+      // Standard render is already in the main bundle (it's small)
+      render(result.template, element)
+    } else if (fallback) {
+      render(result.fallback, element)
+    }
   })
 
   store.notify("init")
   return unsubscribe
 }
 
+/**
+ * Default root-error handler: log without taking the app down.
+ * @param {unknown} error - The error thrown by the root render function.
+ */
+function defaultOnError(error) {
+  console.error("[mount] root render failed:", error)
+}
+
 /**
  * Creates a render function for the mount API.
  * @param {Api} api - The mount API.

package/src/{compass → sensors/compass}/handlers.js

@@ -1,6 +1,6 @@
 /**
- * @typedef {import("../../types/compass.js").CompassEntity} CompassEntity
- * @typedef {import("../../types/compass.js").CompassError} CompassError
+ * @typedef {import("../../../types/sensors/compass.js").CompassEntity} CompassEntity
+ * @typedef {import("../../../types/sensors/compass.js").CompassError} CompassError
  */
 
 const COMPASS_TIMEOUT = 3000

package/src/{element-size → sensors/element-size}/handlers.js

@@ -1,10 +1,10 @@
 /**
- * @typedef {import("../../types/element-size.js").ElementSizeEntity} ElementSizeEntity
- * @typedef {import("../../types/element-size.js").ElementSizeSize} ElementSizeSize
+ * @typedef {import("../../../types/sensors/element-size.js").ElementSizeEntity} ElementSizeEntity
+ * @typedef {import("../../../types/sensors/element-size.js").ElementSizeSize} ElementSizeSize
  */
 
-// Observers aren't serializable, so they're kept here by id, not on the entity.
-const observers = new Map()
+// Listeners aren't serializable, so they're kept here by id, not on the entity.
+const listeners = new Map()
 
 /**
  * Initializes the entity state and starts observing the target element's size.
@@ -35,7 +35,7 @@ export function destroy(entity) {
 export function elementSizeWatch(entity, _, api) {
   entity.isSupported = isSupported()
 
-  if (!entity.isSupported || observers.has(entity.id)) {
+  if (!entity.isSupported || listeners.has(entity.id)) {
     return
   }
 
@@ -54,7 +54,7 @@ export function elementSizeWatch(entity, _, api) {
   })
   observer.observe(element)
 
-  observers.set(id, observer)
+  listeners.set(id, observer)
   entity.isWatching = true
 }
 
@@ -73,11 +73,11 @@ export function elementSizeChange(entity, size) {
  * @param {ElementSizeEntity} entity - The element size entity.
  */
 export function elementSizeUnwatch(entity) {
-  const observer = observers.get(entity.id)
+  const observer = listeners.get(entity.id)
 
   if (observer) {
     observer.disconnect()
-    observers.delete(entity.id)
+    listeners.delete(entity.id)
   }
 
   entity.isWatching = false

package/src/{geolocation → sensors/geolocation}/handlers.js

@@ -1,7 +1,7 @@
 /**
- * @typedef {import("../../types/geolocation.js").GeolocationEntity} GeolocationEntity
- * @typedef {import("../../types/geolocation.js").GeolocationOptions} GeolocationOptions
- * @typedef {import("../../types/geolocation.js").GeolocationPosition} GeolocationPosition
+ * @typedef {import("../../../types/sensors/geolocation.js").GeolocationEntity} GeolocationEntity
+ * @typedef {import("../../../types/sensors/geolocation.js").GeolocationOptions} GeolocationOptions
+ * @typedef {import("../../../types/sensors/geolocation.js").GeolocationPosition} GeolocationPosition
  */
 
 const NO_WATCH_ID = null

package/src/sensors/media-query/handlers.js

@@ -0,0 +1,86 @@
+/**
+ * @typedef {import("../../../types/sensors/media-query.js").MediaQueryEntity} MediaQueryEntity
+ * @typedef {import("../../../types/sensors/media-query.js").MediaQueryMatchEvent} MediaQueryMatchEvent
+ */
+
+const listeners = new Map()
+
+export function create(entity, _, api) {
+  entity.isSupported = isSupported()
+  entity.matches = getMatchState(entity)
+  entity.media = entity.media ?? ""
+  entity.isWatching ??= false
+
+  mediaQueryWatch(entity, _, api)
+}
+
+export function destroy(entity) {
+  mediaQueryUnwatch(entity)
+}
+
+export function mediaQueryChange(entity, event) {
+  entity.matches = event.matches
+}
+
+export function mediaQueryWatch(entity, _, api) {
+  entity.isSupported = isSupported()
+
+  if (!entity.isSupported || entity.isWatching) {
+    return
+  }
+
+  const mql = getMediaQueryList(entity)
+  if (!mql) {
+    return
+  }
+
+  // Snapshot the id while the draft proxy is still live: the callback below
+  // runs after this handler returns, when Mutative has revoked the draft.
+  const id = entity.id
+  const listener = (event) => api.notify(`#${id}:mediaQueryChange`, event)
+
+  listeners.set(id, { mql, listener })
+  entity.isWatching = true
+
+  if (typeof mql.addEventListener === "function") {
+    mql.addEventListener("change", listener)
+  } else if (typeof mql.addListener === "function") {
+    mql.addListener(listener)
+  }
+}
+
+export function mediaQueryUnwatch(entity) {
+  const registration = listeners.get(entity.id)
+
+  if (!registration) {
+    entity.isWatching = false
+    return
+  }
+
+  const { mql, listener } = registration
+
+  if (typeof mql.removeEventListener === "function") {
+    mql.removeEventListener("change", listener)
+  } else if (typeof mql.removeListener === "function") {
+    mql.removeListener(listener)
+  }
+
+  listeners.delete(entity.id)
+  entity.isWatching = false
+}
+
+function getMediaQueryList(entity) {
+  if (typeof globalThis.matchMedia !== "function") {
+    return null
+  }
+
+  return globalThis.matchMedia(entity.media ?? "")
+}
+
+function getMatchState(entity) {
+  return getMediaQueryList(entity)?.matches ?? false
+}
+
+function isSupported() {
+  return typeof globalThis.matchMedia === "function"
+}

package/src/sensors/media-query/index.js

@@ -0,0 +1,3 @@
+import * as handlers from "./handlers.js"
+
+export const MediaQuery = { ...handlers }

package/src/sensors/network-status/handlers.js

@@ -0,0 +1,84 @@
+/**
+ * @typedef {import("../../../types/sensors/network-status.js").NetworkStatusEntity} NetworkStatusEntity
+ */
+
+const ONLINE_EVENT = "online"
+const OFFLINE_EVENT = "offline"
+const listeners = new Map()
+
+export function create(entity, _, api) {
+  entity.isSupported = isSupported()
+  entity.isOnline = getOnlineState()
+  entity.isWatching ??= false
+
+  networkStatusWatch(entity, _, api)
+}
+
+export function destroy(entity) {
+  networkStatusUnwatch(entity)
+}
+
+export function networkStatusChange(entity, value) {
+  entity.isOnline = value
+}
+
+export function networkStatusWatch(entity, _, api) {
+  entity.isSupported = isSupported()
+
+  if (!entity.isSupported || entity.isWatching) {
+    return
+  }
+
+  const win = getWindow()
+  if (!win) {
+    return
+  }
+
+  entity.isOnline = getOnlineState()
+
+  // Snapshot the id while the draft proxy is still live: the callbacks below
+  // run after this handler returns, when Mutative has revoked the draft.
+  const id = entity.id
+  const onlineListener = () => api.notify(`#${id}:networkStatusChange`, true)
+  const offlineListener = () => api.notify(`#${id}:networkStatusChange`, false)
+
+  listeners.set(id, { onlineListener, offlineListener })
+
+  win.addEventListener(ONLINE_EVENT, onlineListener)
+  win.addEventListener(OFFLINE_EVENT, offlineListener)
+  entity.isWatching = true
+}
+
+export function networkStatusUnwatch(entity) {
+  const win = getWindow()
+  const listenerPair = listeners.get(entity.id)
+
+  if (!listenerPair) {
+    entity.isWatching = false
+    return
+  }
+
+  if (win) {
+    win.removeEventListener(ONLINE_EVENT, listenerPair.onlineListener)
+    win.removeEventListener(OFFLINE_EVENT, listenerPair.offlineListener)
+  }
+
+  listeners.delete(entity.id)
+  entity.isWatching = false
+}
+
+function getWindow() {
+  return typeof window !== "undefined" ? window : null
+}
+
+function getOnlineState() {
+  return Boolean(globalThis.navigator?.onLine)
+}
+
+function isSupported() {
+  return (
+    typeof window !== "undefined" &&
+    Boolean(window.addEventListener) &&
+    typeof globalThis.navigator?.onLine === "boolean"
+  )
+}

package/src/sensors/network-status/index.js

@@ -0,0 +1,3 @@
+import * as handlers from "./handlers.js"
+
+export const NetworkStatus = { ...handlers }

package/src/sensors/page-visibility/handlers.js

@@ -0,0 +1,69 @@
+/**
+ * @typedef {import("../../../types/sensors/page-visibility.js").PageVisibilityEntity} PageVisibilityEntity
+ */
+
+const VISIBILITY_EVENT = "visibilitychange"
+const listeners = new Map()
+
+export function create(entity, _, api) {
+  entity.isSupported = isSupported()
+  entity.isVisible = getVisibilityState()
+  entity.isWatching ??= false
+
+  pageVisibilityWatch(entity, _, api)
+}
+
+export function destroy(entity) {
+  pageVisibilityUnwatch(entity)
+}
+
+export function pageVisibilityChange(entity, value) {
+  entity.isVisible = value
+}
+
+export function pageVisibilityWatch(entity, _, api) {
+  entity.isSupported = isSupported()
+
+  if (!entity.isSupported || entity.isWatching) {
+    return
+  }
+
+  const doc = getDocument()
+  if (!doc) {
+    return
+  }
+
+  // Snapshot the id while the draft proxy is still live: the callback below
+  // runs after this handler returns, when Mutative has revoked the draft.
+  const id = entity.id
+  const listener = () => api.notify(`#${id}:pageVisibilityChange`, !doc.hidden)
+
+  listeners.set(id, listener)
+  doc.addEventListener(VISIBILITY_EVENT, listener)
+  entity.isWatching = true
+}
+
+export function pageVisibilityUnwatch(entity) {
+  const doc = getDocument()
+  const listener = listeners.get(entity.id)
+
+  if (listener && doc) {
+    doc.removeEventListener(VISIBILITY_EVENT, listener)
+    listeners.delete(entity.id)
+  }
+
+  entity.isWatching = false
+}
+
+function getDocument() {
+  return typeof document !== "undefined" ? document : null
+}
+
+function getVisibilityState() {
+  const doc = getDocument()
+  return doc?.visibilityState !== "hidden"
+}
+
+function isSupported() {
+  return Boolean(getDocument()?.visibilityState)
+}

package/src/sensors/page-visibility/index.js

@@ -0,0 +1,3 @@
+import * as handlers from "./handlers.js"
+
+export const PageVisibility = { ...handlers }

package/types/decorators/with-debounce.d.ts

@@ -8,6 +8,11 @@ export interface DebounceBehavior {
 }
 
 export declare function withDebounce(
-  config: number | Record<string, number>,
-  handlerNames?: string[],
+  config: number,
+  handlerNames: string[],
+): <T extends Record<string, any>>(type: T) => DebounceBehavior
+
+export declare function withDebounce(
+  config: Record<string, number>,
+  handlerNames?: undefined,
 ): <T extends Record<string, any>>(type: T) => DebounceBehavior

package/types/decorators/with-error-boundary.d.ts

@@ -0,0 +1,11 @@
+import type { TemplateResult } from "lit-html"
+
+import { Api } from "../mount"
+
+export interface ErrorBoundaryBehavior {
+  render: (entity: any, api: Api) => TemplateResult | string
+}
+
+export declare function withErrorBoundary(
+  fallback?: (error: Error, entity: any, api: Api) => TemplateResult | string,
+): <T extends Record<string, any>>(type: T) => ErrorBoundaryBehavior

package/types/decorators/with-throttle.d.ts

@@ -0,0 +1,24 @@
+import { Api } from "../mount"
+
+export interface ThrottleOptions {
+  hasTrailing?: boolean
+}
+
+export interface ThrottleBehavior {
+  destroy?: (entity: any, payload?: any, api?: Api) => void
+  [handlerName: string]:
+    | ((entity: any, payload?: any, api?: Api) => void)
+    | undefined
+}
+
+export declare function withThrottle(
+  config: number,
+  handlerNames: string[],
+  options?: ThrottleOptions,
+): <T extends Record<string, any>>(type: T) => ThrottleBehavior
+
+export declare function withThrottle(
+  config: Record<string, number>,
+  handlerNames?: undefined,
+  options?: ThrottleOptions,
+): <T extends Record<string, any>>(type: T) => ThrottleBehavior

package/types/mobile.d.ts

@@ -0,0 +1 @@
+export declare function isNative(): boolean

package/types/mount.d.ts

@@ -28,11 +28,32 @@ export type Api<
   }
 }
 
+/**
+ * Root error-boundary options for `mount`.
+ */
+export interface MountOptions<
+  TEntity extends BaseEntity = BaseEntity,
+  TState extends EntitiesState<TEntity> = EntitiesState<TEntity>,
+> {
+  /**
+   * Called when the root render function throws. Defaults to `console.error`.
+   */
+  onError?: (error: unknown, api: Api<TEntity, TState>) => void
+  /**
+   * Optional fallback template rendered in place of the failed root render.
+   */
+  fallback?: (
+    error: unknown,
+    api: Api<TEntity, TState>,
+  ) => TemplateResult | null
+}
+
 /**
  * Mounts a lit-html template to the DOM and subscribes to a store for re-rendering.
  * @param store The application state store.
  * @param renderFn The root render function that receives the API and returns a template.
  * @param element The DOM element to mount the template to.
+ * @param options Root error-boundary options (`onError`, `fallback`).
  * @returns An unsubscribe function.
  */
 export function mount<
@@ -42,4 +63,5 @@ export function mount<
   store: Store<TEntity, TState>,
   renderFn: (api: Api<TEntity, TState>) => TemplateResult | null,
   element: HTMLElement | DocumentFragment,
+  options?: MountOptions<TEntity, TState>,
 ): () => void

package/types/{compass.d.ts → sensors/compass.d.ts}

@@ -1,4 +1,4 @@
-import { Api } from "./mount"
+import { Api } from "../mount"
 
 export interface CompassEntity {
   id: string | number

package/types/{element-size.d.ts → sensors/element-size.d.ts}

@@ -1,4 +1,4 @@
-import { Api } from "./mount"
+import { Api } from "../mount"
 
 export interface ElementSizeEntity {
   height: number | null

package/types/{geolocation.d.ts → sensors/geolocation.d.ts}

@@ -1,4 +1,4 @@
-import { Api } from "./mount"
+import { Api } from "../mount"
 
 export interface GeolocationCoordinates {
   accuracy: number

package/types/sensors/media-query.d.ts

@@ -0,0 +1,24 @@
+import { Api } from "../mount"
+
+export interface MediaQueryEntity {
+  id: string | number
+  type?: "MediaQuery"
+  media: string
+  matches: boolean
+  isSupported: boolean
+  isWatching: boolean
+}
+
+export interface MediaQueryMatchEvent {
+  matches: boolean
+}
+
+export interface MediaQueryType {
+  create(entity: MediaQueryEntity, payload: unknown, api: Api): void
+  destroy(entity: MediaQueryEntity): void
+  mediaQueryChange(entity: MediaQueryEntity, event: MediaQueryMatchEvent): void
+  mediaQueryWatch(entity: MediaQueryEntity, payload: unknown, api: Api): void
+  mediaQueryUnwatch(entity: MediaQueryEntity): void
+}
+
+export declare const MediaQuery: MediaQueryType

package/types/sensors/network-status.d.ts

@@ -0,0 +1,23 @@
+import { Api } from "../mount"
+
+export interface NetworkStatusEntity {
+  id: string | number
+  type?: "NetworkStatus"
+  isOnline: boolean
+  isSupported: boolean
+  isWatching: boolean
+}
+
+export interface NetworkStatusType {
+  create(entity: NetworkStatusEntity, payload: unknown, api: Api): void
+  destroy(entity: NetworkStatusEntity, payload: unknown, api: Api): void
+  networkStatusChange(entity: NetworkStatusEntity, value: boolean): void
+  networkStatusWatch(
+    entity: NetworkStatusEntity,
+    payload: unknown,
+    api: Api,
+  ): void
+  networkStatusUnwatch(entity: NetworkStatusEntity): void
+}
+
+export declare const NetworkStatus: NetworkStatusType

package/types/sensors/page-visibility.d.ts

@@ -0,0 +1,23 @@
+import { Api } from "../mount"
+
+export interface PageVisibilityEntity {
+  id: string | number
+  type?: "PageVisibility"
+  isSupported: boolean
+  isVisible: boolean
+  isWatching: boolean
+}
+
+export interface PageVisibilityType {
+  create(entity: PageVisibilityEntity, payload: unknown, api: Api): void
+  destroy(entity: PageVisibilityEntity, payload: unknown, api: Api): void
+  pageVisibilityChange(entity: PageVisibilityEntity, value: boolean): void
+  pageVisibilityWatch(
+    entity: PageVisibilityEntity,
+    payload: unknown,
+    api: Api,
+  ): void
+  pageVisibilityUnwatch(entity: PageVisibilityEntity): void
+}
+
+export declare const PageVisibility: PageVisibilityType