Preact

import * as mod from "jsr:@nzip/lofi/preact";

Optional Preact bindings for lofi device capabilities and PWA controls.

These components are package-owned examples that application layouts may compose or replace with UI built on the same public runtime APIs.

DeviceStatus

^function

function DeviceStatus(): VNode

Renders live storage, sync, auth, and PWA capability diagnostics.

Returns: The device diagnostics panel, grouped by owning subsystem.

Example

import { DeviceStatus } from "@nzip/lofi/preact";

export function SettingsPage() {
  return <DeviceStatus />;
}

PwaActions

^function

function PwaActions({ ..., ... }: PwaActionsProps): VNode | null

A composable install/update surface that keeps browser event handling package-owned.

| Parameter | Description |

| --- | --- |

| props | An optional controller override and heading text. |

Returns: The install/update section, or null when no action or status is relevant.

Example

import { PwaActions } from "@nzip/lofi/preact";

<PwaActions title="Install this app" />;

pwaFailureMessage

^function

function pwaFailureMessage(code: PwaFailureCode): string

Returns actionable, non-technical recovery guidance for a PWA failure.

RuntimeRecovery

^function

function RuntimeRecovery({ ..., ... }: RuntimeRecoveryProps): JSX.Element | null

Renders recovery only when another tab is running an incompatible broker version.

| Parameter | Description |

| --- | --- |

| props | The startup failure to inspect and an optional reload override. |

Returns: The recovery prompt, or null when no incompatible-broker failure is present.

Example

import { RuntimeRecovery } from "@nzip/lofi/preact";

<RuntimeRecovery failure={startupFailure} />;

useDeviceCapabilities

^function

function useDeviceCapabilities(): DeviceCapabilitiesHook

Reads browser capabilities and exposes an explicit persistence request.

useLiveQuery

^function

function useLiveQuery<T extends TableRow>(createQuery: () => QueryBuilder<T>, dependencies: readonly unknown[]): LiveQuerySnapshot<T>

Subscribes a Preact component to any typed Jazz query.

Equivalent mounted queries share one Jazz subscription. The snapshot preserves the exact row type produced by the builder, including select and include projections. An empty rows array with status: "ready" is an empty result, not a loading signal.

| Parameter | Description |

| --- | --- |

| createQuery | Builds the typed Jazz query; re-invoked when dependencies change. |

| dependencies | Values that, when changed, release the query and open a replacement. |

Returns: The live snapshot: status, exact typed rows, and error.

Example

import { useLiveQuery } from "@nzip/lofi/preact";
import { app } from "../app.ts";

const records = useLiveQuery(
  () => app.schema.records.where({ workspaceId, archived: false }),
  [workspaceId],
);
// records.status is "loading" | "ready" | "error"; records.rows is typed.

usePwaState

^function

function usePwaState(controller: PwaController): PwaState

Subscribes a Preact component to an isolated or shared PWA controller.

| Parameter | Description |

| --- | --- |

| controller | The controller to observe; defaults to the package-wide PWA controller. |

Returns: The current install/update state, kept live via subscription.

Example

import { usePwaState } from "@nzip/lofi/preact";

const pwa = usePwaState();
const updateReady = pwa.update === "ready";

useTableMutations

^function

function useTableMutations<T extends TableRow, Init>(table: TableProxy<T, Init>): TableMutations<T, Init>

Binds one typed Jazz table to stable insert, update, and remove methods.

Mutation promises resolve after local durability; when managed sync is active, global confirmation continues in the background and updates the shared table-scoped pending, durability, and error state.

| Parameter | Description |

| --- | --- |

| table | The typed schema table to mutate, e.g. app.schema.records. |

Returns: Stable insert, update, and remove methods plus the shared mutation state.

Example

import { useTableMutations } from "@nzip/lofi/preact";
import { app } from "../app.ts";

const records = useTableMutations(app.schema.records);
const created = await records.insert({ title: "Release notes", archived: false });
await records.update(created.id, { archived: true });
await records.remove(created.id);

DeviceCapabilitiesHook

^type

type DeviceCapabilitiesHook = {
  report: DeviceCapabilityReport | null;
  requestPersistence(): Promise<void>;
};

State returned by useDeviceCapabilities.

DeviceCapabilityReport

^type

type DeviceCapabilityReport = {
  secureContext: boolean;
  opfs: boolean;
  sharedWorker: boolean;
  webLocks: boolean;
  messageChannel: boolean;
  durableDriverSupported: boolean;
  webAuthn: boolean;
  prf: "available" | "not-reported" | "unknown" | "unavailable";
  persistentPermission: "granted" | "not-granted" | "unavailable" | "error";
  displayMode: "standalone" | "browser";
};

Browser capabilities that determine whether lofi can provide its runtime guarantees.

LiveQuerySnapshot

^type

type LiveQuerySnapshot<T extends TableRow> = {
  status: "loading" | "ready" | "error";
  rows: T[];
  error: string | null;
};

Honest read state for an arbitrary typed Jazz query.

PwaActionsProps

^interface

interface PwaActionsProps {
  readonly controller?: PwaController;
  readonly title?: string;
}

Optional controller and heading text for PwaActions.

PwaController

^type

type PwaController = {
  getState(): PwaState;
  subscribe(subscriber: (state: PwaState) => void): () => void;
  requestInstall(): Promise<PwaInstallState>;
  checkForUpdate(): Promise<boolean>;
  applyUpdate(): boolean;
  initialize(): void;
};

Stateful controller for browser installation and service-worker updates.

PwaFailureCode

^type

type PwaFailureCode = 
  | "registration"
  | "installation"
  | "install-prompt"
  | "update-check"
  | "precache"
  | "runtime-cache";

Stable categories for recoverable offline/PWA failures.

PwaState

^type

type PwaState = {
  worker: PwaWorkerState;
  install: PwaInstallState;
  update: PwaUpdateState;
  failure?: { code: PwaFailureCode; message: string };
};

Current install, service-worker, and offline-cache state.

PwaUpdateState

^type

type PwaUpdateState = 
  | "idle"
  | "checking"
  | "installing"
  | "ready"
  | "applying"
  | "failed";

Foreground update-check and waiting-worker states exposed to application UI.

RuntimeRecoveryProps

^type

type RuntimeRecoveryProps = {
  failure: RuntimeStartupFailure | null;
  reload?: () => void;
};

Inputs for Lofi's explicit persistent-runtime recovery action.

TableMutations

^type

type TableMutations<T extends TableRow, Init> = TableMutationSnapshot & { insert(values: Init): Promise<T>; update(id: string, patch: Partial<Init>): Promise<void>; remove(id: string): Promise<void> };

Typed mutation methods plus their shared table-scoped observable state.

TableMutationSnapshot

^type

type TableMutationSnapshot = {
  pending: number;
  durability: "none" | "local" | "global" | "failed";
  error: string | null;
};

Observable state shared by every mutation consumer for one table.