@openbrf/display 0.0.0-stage → 0.1.1

package/LICENSE-EXCEPTION.md

@@ -0,0 +1,28 @@
+# Open BRF Module Exception
+
+Version 1.0
+
+## The exception
+
+As an additional permission under section 7 of the GNU Affero General Public License, version 3 ("AGPL-3.0"), the copyright holders of Open BRF give you permission to combine Open BRF with modules.
+
+A "module" is a plugin, theme, or other extension package that interacts with the Open BRF core exclusively through the documented public extension interfaces: the plugin API, the theme/token contract, the public HTTP API, and the extension points declared in the module manifest format (together, the "Module API").
+
+If you create and convey a module:
+
+1. The module is **not** considered a work based on Open BRF for the purposes of AGPL-3.0, regardless of the linking or loading mechanism.
+2. You may license the module under terms of your own choosing, including proprietary terms; nothing requires you to convey the module's source code.
+3. Running a combined work consisting of an unmodified Open BRF core and one or more modules, including offering it to users over a network, does not extend the obligations of AGPL-3.0 (including section 13) to the modules.
+
+This exception does **not** apply to:
+
+- Modifications of the Open BRF core itself, which remain governed by AGPL-3.0 in full. A "module" that patches, replaces, or bundles modified core code is a modification of the core, not a module.
+- The obligations of AGPL-3.0 regarding the core: anyone conveying or network-hosting a modified core must still offer its Corresponding Source.
+
+As provided by section 7 of AGPL-3.0, you may remove this additional permission from your copy, but you may not add further restrictions.
+
+## Why this exists
+
+The legal status of in-process plugins to (A)GPL software is a decades-old gray zone. Rather than relying on it, Open BRF states the rule explicitly, in both directions: the core is and remains copyleft, and the module ecosystem - community and commercial alike - is legally safe to build in. Vendure pioneered this model for GPL; Open BRF applies it to AGPL.
+
+This exception is granted by Apteo AB as copyright holder of Open BRF. Contributions are accepted under a [CLA](CLA.md) precisely so that this grant remains valid for the whole codebase.

package/README.md

@@ -1,3 +1,127 @@
-# Temporary Holding Version
+# @openbrf/display
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+What every screen showing a housing cooperative's content is built from, in
+[Open BRF](https://github.com/openbrf/openbrf): the screen content contract,
+the rotation builder, the renderer and the fetch loop. The core's display mode
+(a browser opened on a display link) and the digital signage module's player
+both use all four, so a screen shows the association's news, events, the
+notice of the next general meeting and free/busy availability the same way
+whichever of them it runs.
+
+It uses no framework and no DOM library, and has one dependency,
+[`@openbrf/tokens`](https://www.npmjs.com/package/@openbrf/tokens), for the
+default theme's colours.
+
+## Installing
+
+```sh
+npm install @openbrf/display
+```
+
+## The four parts
+
+1. **The screen content contract.** The `ScreenContent` document, version 1,
+   as types (`ScreenContent`, `Slide`, the body kinds), its limits
+   (`SCREEN_CONTENT_LIMITS`, `SLIDE_ID_PATTERN`), and `parseScreenContent`,
+   which reads a document by the player's rules: unknown fields are ignored,
+   a slide of an unknown or malformed kind is skipped, and an unknown
+   `version` is refused with a `ScreenContentError`.
+2. **The rotation builder.** `buildRotation` turns the news items,
+   occurrences, meeting notices, bookable resources and busy intervals a
+   caller has read, and the moment of the fetch, into the `news`, `events`,
+   `meeting` and `availability` slides. It reads nothing on its own.
+   `availabilityWindow` gives the window an availability slide covers: from
+   the minute of the fetch to the end of the next day in the association's
+   time zone.
+3. **The renderer.** `mountRenderer` shows a document on an element: the
+   rotation with each slide's `seconds` and `until`, the schedule, the clock
+   band, the orientation, the theme and every body kind, in Swedish or
+   English. Nothing a slide holds is cut off: a slide the screen cannot hold
+   whole is shown a page at a time, each page for the slide's `seconds`. A
+   list, such as eight events, goes as many items to a page as fit whole; a
+   page still too tall is set smaller, and a text too tall even then, such as
+   a news item of fifty paragraphs, continues on the next page, broken between
+   two words, or a word longer than a page between two of its characters. It
+   fetches nothing; a picture comes from a function you hand it. It adds its stylesheet (`DISPLAY_STYLESHEET`, every class prefixed
+   `obrf-display`) to the document once, as a `<style>` element. A page whose
+   content security policy has no `'unsafe-inline'` in `style-src` serves the
+   stylesheet as a file instead: it links the file as
+   `<link rel="stylesheet" data-obrf-display href="...">` and passes
+   `stylesheet: false` to `mountRenderer`. The renderer then adds no `<style>`
+   element and sets no `style` attribute, only properties through the style
+   object, which such a policy allows. A page that has a `link` or `style` with
+   `data-obrf-display` in its head gets no second copy either way.
+4. **The fetch loop.** `startFetchLoop` asks for screen content with a device
+   token and acts on each answer: 200 and 304 show content, a 401 with
+   `realm="device"` and `device-token-invalid` forgets it and stops, 404
+   pauses, 429 waits, and anything else shows the last content for at most
+   24 hours. Where the content is cached is yours to choose.
+
+## Usage
+
+```ts
+import { mountRenderer, startFetchLoop } from "@openbrf/display";
+
+const renderer = mountRenderer(document.getElementById("screen")!, {
+  // Fetch the picture with the token in a header, never in its URL.
+  picture: async (ref) => {
+    const response = await fetch(
+      new URL(`pictures/${encodeURIComponent(ref.mediaFileId)}`, contentUrl),
+      { headers: { Authorization: `Bearer ${token}` }, credentials: "omit" },
+    );
+    return response.ok ? URL.createObjectURL(await response.blob()) : null;
+  },
+  releasePicture: (url) => URL.revokeObjectURL(url),
+});
+renderer.message("loading", "sv");
+
+startFetchLoop({
+  url: contentUrl,
+  token: () => localStorage.getItem("token"),
+  cache: {
+    read: () => JSON.parse(localStorage.getItem("content") ?? "null"),
+    write: (entry) => localStorage.setItem("content", JSON.stringify(entry)),
+    clear: () => localStorage.removeItem("content"),
+  },
+  onContent: (content, status) => renderer.show(content, status),
+  onRevoked: () => {
+    localStorage.removeItem("token");
+    renderer.message("link-invalid", "sv");
+  },
+  onPaused: () => renderer.message("paused", "sv"),
+  onDisconnected: () => renderer.message("not-connected", "sv"),
+});
+```
+
+Give the element a size, such as the whole viewport: the canvas fills it and
+is turned by the document's orientation.
+
+## Browsers
+
+The renderer and its stylesheet run in Chromium 85, the browser of Samsung's
+2021 Tizen displays, without a shim: the package calls nothing newer and writes
+no CSS newer. A test fails when one of the newer calls or CSS features it
+lists, such as `replaceChildren`, `Array.prototype.at` or `inset`, is added;
+anything it does not list is for review to catch. A word longer than a page
+is broken between characters with `Intl.Segmenter` where the browser has it
+(Chromium 87), and between code points where it does not.
+
+## Versions
+
+The package carries version 1 of the screen content contract. A field or a
+body kind may be added within version 1, and an older renderer ignores what it
+does not know. A change an older renderer would misread raises the contract's
+version, which is served beside version 1, and the package then carries both.
+
+## Documentation
+
+- [The screen content contract](https://github.com/openbrf/openbrf/blob/main/docs/screen-content-contract.md)
+- [ADR 0050: the display mode, and one renderer for every screen](https://github.com/openbrf/openbrf/blob/main/docs/adr/0050-the-display-mode-and-one-renderer-for-every-screen.md)
+- [ADR 0034: digital signage on the public plugin API](https://github.com/openbrf/openbrf/blob/main/docs/adr/0034-digital-signage-on-the-public-plugin-api.md)
+
+## Licence
+
+AGPL-3.0-only, with the
+[Open BRF Module Exception](https://github.com/openbrf/openbrf/blob/main/LICENSE-EXCEPTION.md).
+A player or shell built on this package is a module under that exception and
+may be licensed on any terms. Both texts are in the package.

package/dist/contract.d.ts

@@ -0,0 +1,244 @@
+/**
+ * The screen content contract, version 1: the document a screen fetches and
+ * shows, as ADR 0034 defined it and ADR 0050 made the core's.
+ *
+ * The text of record is docs/screen-content-contract.md. These types and
+ * limits are that text in code, and a change to either is a change to the
+ * contract under its version rules: a field or a body kind may be added within
+ * version 1, because an older player ignores what it does not know, and a
+ * change an older player would misread raises the version.
+ *
+ * "Characters" in a limit are Unicode code points. A server that measures in
+ * UTF-16 code units, as JavaScript's `length` does, never exceeds a limit
+ * measured in code points, so the builder in this package measures in code
+ * units and the parser in code points.
+ */
+/** The version of the document this package reads and builds. */
+export declare const SCREEN_CONTENT_VERSION = 1;
+/** An instant: RFC 3339 in UTC, whole seconds, with "Z": "2026-12-01T09:00:00Z". */
+export type Instant = string;
+/** A time of day, "HH:MM" from "00:00" to "24:00", in the document's `timeZone`. */
+export type LocalTime = string;
+/** The languages a screen speaks. */
+export type ScreenLocale = "sv" | "en";
+/** An ISO weekday: 1 is Monday and 7 is Sunday. */
+export type IsoWeekday = 1 | 2 | 3 | 4 | 5 | 6 | 7;
+/** How the screen lays out its canvas. */
+export interface ScreenLayout {
+    /** Degrees clockwise the player turns its canvas. */
+    orientation: 0 | 90 | 180 | 270;
+    /** A band above the slides with the date and the time, or none. */
+    header: "none" | "clock";
+    theme: "light" | "dark";
+}
+/** One window in which the screen shows the rotation. */
+export interface ScreenScheduleWindow {
+    days: IsoWeekday[];
+    /** Inclusive. */
+    from: LocalTime;
+    /** Exclusive, and after `from`. A window over midnight is two windows. */
+    to: LocalTime;
+}
+/**
+ * When the screen shows the rotation. Outside every window it shows black;
+ * with no window at all it shows the rotation always.
+ */
+export interface ScreenSchedule {
+    /** At most 14. */
+    on: ScreenScheduleWindow[];
+}
+/** One kind of thing in a screen's rotation (GLOSSARY.md, "source"). */
+export type SlideSource = "news" | "events" | "meeting" | "availability" | "picture" | "addon";
+/** A picture the screen may show, fetched by its `mediaFileId`. */
+export interface PictureRef {
+    mediaFileId: string;
+    /** The image type the core identified from the bytes. */
+    contentType: string;
+    byteSize: number;
+    /** Opaque, and changes when the file does: the picture's ETag. */
+    version: string;
+    /** At most 300 characters. */
+    alt: string;
+}
+/** A published news item. */
+export interface NewsBody {
+    kind: "news";
+    /** At most 200 characters. */
+    title: string;
+    /** At most 2 000 characters together. */
+    paragraphs: string[];
+    picture: PictureRef | null;
+    publishedAt: Instant;
+}
+/** One occurrence of a published event, as an events slide lists it. */
+export interface EventsOccurrence {
+    /** At most 200 characters. */
+    title: string;
+    /** At most 500 characters. */
+    description: string | null;
+    /** At most 200 characters. */
+    location: string | null;
+    startsAt: Instant;
+    endsAt: Instant;
+    calledOff: boolean;
+    placesLeft: number | null;
+}
+/** The coming occurrences of published events. */
+export interface EventsBody {
+    kind: "events";
+    /** 1 to 8, soonest first. */
+    occurrences: EventsOccurrence[];
+}
+/** One matter on a general meeting's agenda. */
+export interface AgendaItem {
+    position: number;
+    /** At most 200 characters. */
+    title: string;
+}
+/** The notice of a general meeting the board has called. */
+export interface MeetingBody {
+    kind: "meeting";
+    meetingKind: "ordinary" | "extraordinary";
+    startsAt: Instant;
+    /** At most 200 characters. */
+    place: string;
+    /** At most 500 characters. */
+    digitalParticipation: string | null;
+    /** At most 40. */
+    agenda: AgendaItem[];
+}
+/** A period a bookable resource is taken. Never by whom. */
+export interface BusyInterval {
+    start: Instant;
+    end: Instant;
+}
+/** One bookable resource on an availability slide. */
+export interface AvailabilityResource {
+    /** At most 80 characters. */
+    name: string;
+    mode: "timeSlots" | "wholeDay" | "dateRange";
+    slotMinutes: number | null;
+    /** Minutes after midnight in the document's `timeZone`. */
+    opensAtMinute: number | null;
+    closesAtMinute: number | null;
+    /** Merged, sorted, and inside [from, to). */
+    busy: BusyInterval[];
+}
+/** When the house's bookable resources are free and busy. */
+export interface AvailabilityBody {
+    kind: "availability";
+    /** The fetch, to the minute; never earlier. */
+    from: Instant;
+    /** At most 7 days after `from`. */
+    to: Instant;
+    /** 1 to 12. */
+    resources: AvailabilityResource[];
+}
+/** A picture the board chose for the screen. */
+export interface PictureBody {
+    kind: "picture";
+    picture: PictureRef;
+    /** At most 200 characters. */
+    caption: string | null;
+}
+/** An addon's text slide. */
+export interface AddonTextBody {
+    kind: "text";
+    heading: string;
+    /** At most 2 000 characters together. */
+    body: string[];
+}
+/** An addon's table slide. */
+export interface AddonTableBody {
+    kind: "table";
+    heading: string;
+    /** At most 4. */
+    columns: string[];
+    /** At most 60, each as long as `columns`. */
+    rows: string[][];
+}
+/** One door on an addon's doors slide. */
+export interface AddonDoor {
+    floor: number | null;
+    apartment: string;
+    names: string[];
+}
+/** An addon's doors slide: the names on the doors of one entrance. */
+export interface AddonDoorsBody {
+    kind: "doors";
+    heading: string;
+    /** At most 120. */
+    doors: AddonDoor[];
+}
+/** One slide of an addon's output at the `source` extension point. */
+export type AddonBody = AddonTextBody | AddonTableBody | AddonDoorsBody;
+/** What a slide shows. Its `kind` matches the slide's `source`. */
+export type SlideBody = NewsBody | EventsBody | MeetingBody | AvailabilityBody | PictureBody | AddonBody;
+/** One slide of the rotation. */
+export interface Slide {
+    /** 1 to 64 of A-Z a-z 0-9 . _ : -, the same on every fetch while the slide shows the same thing. */
+    id: string;
+    /** Integer, 5 to 120: how long it stays. */
+    seconds: number;
+    /** The player skips the slide from this instant, without waiting for a fetch. */
+    until: Instant | null;
+    source: SlideSource;
+    /** The addon's plugin id when `source` is "addon", otherwise null. */
+    addon: string | null;
+    body: SlideBody;
+}
+/** The screen content document, version 1. */
+export interface ScreenContent {
+    version: 1;
+    /** The device token's subject: the screen's id. */
+    screenId: string;
+    generatedAt: Instant;
+    /** Integer, 30 to 60. */
+    refreshSeconds: number;
+    locale: ScreenLocale;
+    /** IANA zone of the association's calendar day: "Europe/Stockholm". */
+    timeZone: string;
+    /** The only channel a paired screen's shell takes player releases from. */
+    releaseChannel: "stable" | "beta";
+    layout: ScreenLayout;
+    schedule: ScreenSchedule;
+    /** In order, at most 100; the player loops through them. */
+    rotation: Slide[];
+}
+/** The contract's limits, by what they bound. */
+export declare const SCREEN_CONTENT_LIMITS: {
+    /** The document's size, in bytes of its UTF-8 JSON. */
+    readonly documentBytes: number;
+    readonly rotation: 100;
+    readonly slideSecondsMin: 5;
+    readonly slideSecondsMax: 120;
+    readonly refreshSecondsMin: 30;
+    readonly refreshSecondsMax: 60;
+    readonly scheduleWindows: 14;
+    readonly title: 200;
+    /** All of a news item's paragraphs together. */
+    readonly paragraphs: 2000;
+    readonly description: 500;
+    readonly location: 200;
+    readonly place: 200;
+    readonly digitalParticipation: 500;
+    readonly agendaItems: 40;
+    readonly agendaTitle: 200;
+    readonly occurrencesMin: 1;
+    readonly occurrencesMax: 8;
+    readonly resourcesMin: 1;
+    readonly resourcesMax: 12;
+    readonly resourceName: 80;
+    /** How far an availability slide's `to` may be after its `from`, in days. */
+    readonly availabilityDays: 7;
+    readonly alt: 300;
+    readonly caption: 200;
+    /** All of an addon text slide's paragraphs together. */
+    readonly addonTextBody: 2000;
+    readonly tableColumns: 4;
+    readonly tableRows: 60;
+    readonly doors: 120;
+};
+/** What a slide's `id` is made of. */
+export declare const SLIDE_ID_PATTERN: RegExp;
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"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"}

package/dist/contract.js

@@ -0,0 +1,54 @@
+/**
+ * The screen content contract, version 1: the document a screen fetches and
+ * shows, as ADR 0034 defined it and ADR 0050 made the core's.
+ *
+ * The text of record is docs/screen-content-contract.md. These types and
+ * limits are that text in code, and a change to either is a change to the
+ * contract under its version rules: a field or a body kind may be added within
+ * version 1, because an older player ignores what it does not know, and a
+ * change an older player would misread raises the version.
+ *
+ * "Characters" in a limit are Unicode code points. A server that measures in
+ * UTF-16 code units, as JavaScript's `length` does, never exceeds a limit
+ * measured in code points, so the builder in this package measures in code
+ * units and the parser in code points.
+ */
+/** The version of the document this package reads and builds. */
+export const SCREEN_CONTENT_VERSION = 1;
+/** The contract's limits, by what they bound. */
+export const SCREEN_CONTENT_LIMITS = {
+    /** The document's size, in bytes of its UTF-8 JSON. */
+    documentBytes: 1024 * 1024,
+    rotation: 100,
+    slideSecondsMin: 5,
+    slideSecondsMax: 120,
+    refreshSecondsMin: 30,
+    refreshSecondsMax: 60,
+    scheduleWindows: 14,
+    title: 200,
+    /** All of a news item's paragraphs together. */
+    paragraphs: 2000,
+    description: 500,
+    location: 200,
+    place: 200,
+    digitalParticipation: 500,
+    agendaItems: 40,
+    agendaTitle: 200,
+    occurrencesMin: 1,
+    occurrencesMax: 8,
+    resourcesMin: 1,
+    resourcesMax: 12,
+    resourceName: 80,
+    /** How far an availability slide's `to` may be after its `from`, in days. */
+    availabilityDays: 7,
+    alt: 300,
+    caption: 200,
+    /** All of an addon text slide's paragraphs together. */
+    addonTextBody: 2000,
+    tableColumns: 4,
+    tableRows: 60,
+    doors: 120,
+};
+/** What a slide's `id` is made of. */
+export const SLIDE_ID_PATTERN = /^[A-Za-z0-9._:-]{1,64}$/;
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,iEAAiE;AACjE,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC;AAiOxC,iDAAiD;AACjD,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,uDAAuD;IACvD,aAAa,EAAE,IAAI,GAAG,IAAI;IAC1B,QAAQ,EAAE,GAAG;IACb,eAAe,EAAE,CAAC;IAClB,eAAe,EAAE,GAAG;IACpB,iBAAiB,EAAE,EAAE;IACrB,iBAAiB,EAAE,EAAE;IACrB,eAAe,EAAE,EAAE;IACnB,KAAK,EAAE,GAAG;IACV,gDAAgD;IAChD,UAAU,EAAE,IAAI;IAChB,WAAW,EAAE,GAAG;IAChB,QAAQ,EAAE,GAAG;IACb,KAAK,EAAE,GAAG;IACV,oBAAoB,EAAE,GAAG;IACzB,WAAW,EAAE,EAAE;IACf,WAAW,EAAE,GAAG;IAChB,cAAc,EAAE,CAAC;IACjB,cAAc,EAAE,CAAC;IACjB,YAAY,EAAE,CAAC;IACf,YAAY,EAAE,EAAE;IAChB,YAAY,EAAE,EAAE;IAChB,6EAA6E;IAC7E,gBAAgB,EAAE,CAAC;IACnB,GAAG,EAAE,GAAG;IACR,OAAO,EAAE,GAAG;IACZ,wDAAwD;IACxD,aAAa,EAAE,IAAI;IACnB,YAAY,EAAE,CAAC;IACf,SAAS,EAAE,EAAE;IACb,KAAK,EAAE,GAAG;CACF,CAAC;AAEX,sCAAsC;AACtC,MAAM,CAAC,MAAM,gBAAgB,GAAG,yBAAyB,CAAC"}

package/dist/fetch-loop.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The fetch loop: the request for screen content, and what is done with each
+ * answer, as the table under "Pairing" in ADR 0034 says it.
+ *
+ * | Answer                                                        | What the loop does                                                         |
+ * | ------------------------------------------------------------- | -------------------------------------------------------------------------- |
+ * | 200                                                           | Replaces the cache whole and shows the document.                           |
+ * | 304                                                           | Shows the cached document, now confirmed.                                  |
+ * | 401, `realm="device"` and `device-token-invalid`              | Clears the cache, stops, and says so: the caller forgets the token.        |
+ * | 404                                                           | Clears the cache and says the screen is paused; asks again every minute.   |
+ * | 429                                                           | Keeps what is shown and asks again after `Retry-After`, within a minute.   |
+ * | Anything else, a body that is not a document, a network error | Shows the cache for 24 hours since it was fetched, then says disconnected. |
+ *
+ * Where the content is cached, and what a revocation wipes besides it, is the
+ * caller's, because a shell holds more than the display page does.
+ */
+import type { ScreenContent } from "./contract.ts";
+/** What the loop keeps between fetches. */
+export interface CachedScreenContent {
+    content: ScreenContent;
+    /** The strong ETag the document came with, or null. */
+    etag: string | null;
+    /** ISO 8601 instant of the last 200 or 304. */
+    fetchedAt: string;
+}
+/** Where the content is kept, such as `localStorage`. The caller's to choose. */
+export interface ScreenContentCache {
+    read(): CachedScreenContent | null;
+    write(entry: CachedScreenContent): void;
+    clear(): void;
+}
+/** How fresh the content handed to `onContent` is. */
+export interface FetchedStatus {
+    fetchedAt: Date;
+    /** True when the instance could not be reached and this is the last good content. */
+    stale: boolean;
+}
+export interface FetchLoopOptions {
+    /** The absolute content URL, query included. The token is never put in it. */
+    url: string;
+    /** The device token, read before each request; null when there is none. */
+    token: () => string | null;
+    cache: ScreenContentCache;
+    /** Content to show: fresh, or the last good content while the instance cannot be reached. */
+    onContent(content: ScreenContent, status: FetchedStatus): void;
+    /**
+     * The instance refused the token (401 with `realm="device"` and
+     * `device-token-invalid`), or there is no token. The loop has cleared the
+     * cache and stopped; the caller forgets whatever else it holds, the token
+     * first.
+     */
+    onRevoked(): void;
+    /**
+     * 404: the route is switched off. The loop has cleared the cache, and asks
+     * again every 60 seconds. Without it, a 404 is told as `onDisconnected(null)`.
+     */
+    onPaused?(): void;
+    /**
+     * Nothing to show: no content was ever fetched, or the last was fetched 24
+     * hours ago or more. The loop asks again every 60 seconds.
+     */
+    onDisconnected(lastFetchedAt: Date | null): void;
+    fetch?: typeof fetch;
+    now?: () => Date;
+    setTimeout?: (callback: () => void, ms: number) => unknown;
+    clearTimeout?: (handle: unknown) => void;
+}
+/** A running fetch loop. */
+export interface FetchLoop {
+    /** Stops the loop; a request in flight is aborted and its answer ignored. */
+    stop(): void;
+    /** Fetches now, unless a request is already in flight. */
+    refreshNow(): void;
+}
+/** How long the last good content may be shown, from when it was fetched. */
+export declare const STALE_CONTENT_LIMIT_MS: number;
+/**
+ * Starts fetching screen content: at once, then `refreshSeconds` after each
+ * 200 or 304, held to 30 to 60, and 60 seconds after anything else.
+ *
+ * Each request is `GET url` with the token in `Authorization: Bearer`, the
+ * cached ETag in `If-None-Match`, no cookie (`credentials: "omit"`) and no
+ * HTTP cache (`cache: "no-store"`). Only one is ever in flight. A cache entry
+ * younger than 24 hours is shown at once, as stale, before the first answer.
+ */
+export declare function startFetchLoop(options: FetchLoopOptions): FetchLoop;
+//# sourceMappingURL=fetch-loop.d.ts.map

package/dist/fetch-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-loop.d.ts","sourceRoot":"","sources":["../src/fetch-loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAInD,2CAA2C;AAC3C,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,aAAa,CAAC;IACvB,uDAAuD;IACvD,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,iFAAiF;AACjF,MAAM,WAAW,kBAAkB;IACjC,IAAI,IAAI,mBAAmB,GAAG,IAAI,CAAC;IACnC,KAAK,CAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACxC,KAAK,IAAI,IAAI,CAAC;CACf;AAED,sDAAsD;AACtD,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,IAAI,CAAC;IAChB,qFAAqF;IACrF,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,8EAA8E;IAC9E,GAAG,EAAE,MAAM,CAAC;IACZ,2EAA2E;IAC3E,KAAK,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE,kBAAkB,CAAC;IAC1B,6FAA6F;IAC7F,SAAS,CAAC,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,aAAa,GAAG,IAAI,CAAC;IAC/D;;;;;OAKG;IACH,SAAS,IAAI,IAAI,CAAC;IAClB;;;OAGG;IACH,QAAQ,CAAC,IAAI,IAAI,CAAC;IAClB;;;OAGG;IACH,cAAc,CAAC,aAAa,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IACjD,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IAC3D,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;CAC1C;AAED,4BAA4B;AAC5B,MAAM,WAAW,SAAS;IACxB,6EAA6E;IAC7E,IAAI,IAAI,IAAI,CAAC;IACb,0DAA0D;IAC1D,UAAU,IAAI,IAAI,CAAC;CACpB;AAGD,6EAA6E;AAC7E,eAAO,MAAM,sBAAsB,QAAwB,CAAC;AAO5D;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,CAiQnE"}