@missing-elements/h5p-offline-player 0.1.0

package/types/shared/eviction.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Which package a quota squeeze may drop: the coldest by `lastPlayed` that is neither the one
+ * being written nor under a lock anywhere on the origin.
+ *
+ * Both the Service Worker and the Jobs worker install this, because both write the chunk store
+ * and either can be the one that hits the wall — the Jobs worker most often, since the large
+ * writes are its. Before it did, it evicted whichever cache the browser happened to list first.
+ */
+export declare function coldestIdlePackage(exceptPkgId: string, lookups?: {
+    packagesByAge?: () => Promise<Array<{
+        pkgId: string;
+    }>>;
+    busyPackages?: () => Promise<Set<string>>;
+}): Promise<string | null>;
+/** Points the chunk store's eviction at the `packages` table, and cleans the table up after it. */
+export declare function installEvictionPolicy(onEvicted?: (pkgId: string) => void): void;

package/types/shared/forward-index.d.ts

@@ -0,0 +1,85 @@
+/**
+ * A forward index of a zip: the entries readable from its local headers alone, in the order the
+ * bytes arrive, without the central directory that sits at the end of the file.
+ *
+ * A host that ignores `Range` forces the whole archive down before the central directory can be
+ * read, and with it every entry — including the ones that arrived in the first second. Walking
+ * the local headers as they stream in recovers those entries early, so a package laid out
+ * libraries-first (the PHP exporter's order) can boot while its media is still downloading.
+ *
+ * Two things the format does that a forward walk has to survive:
+ *
+ * - **Data descriptors** (general-purpose bit 3). A writer that streams cannot know an entry's
+ *   compressed size before it has written the data, so it writes zeros in the local header and the
+ *   real sizes *after* the data. h5p.com's exporter does this for every entry. There is no length
+ *   to skip by, so the data is scanned for the descriptor signature and a candidate is accepted
+ *   only when the compressed size it carries equals the number of bytes seen since the data began
+ *   — a 64-bit coincidence for a false positive. A writer that omits the optional signature leaves
+ *   the entry unresolvable; the scanner then stops and the central directory decides at the end.
+ * - **zip64**. Sizes of `0xFFFFFFFF` in the header defer to the zip64 extra field, and an entry
+ *   whose header carries that field writes 8-byte sizes in its descriptor.
+ *
+ * Nothing here is trusted further than the central directory would be: names go through the same
+ * normalisation as everything else, and the snapshot is replaced by the real index once the whole
+ * archive is present.
+ */
+export interface ForwardEntry {
+    /** The name as written in the archive. Normalised by the reader, not here. */
+    name: string;
+    directory: boolean;
+    method: number;
+    encrypted: boolean;
+    crc32: number;
+    compressedSize: number;
+    uncompressedSize: number;
+    headerOffset: number;
+    dataStart: number;
+}
+export type ForwardStop = 
+/** The central directory began: every entry has been seen and the index is complete. */
+'central-directory'
+/** Bytes where a local header should be were not one. */
+ | 'bad-signature'
+/** A descriptor entry ran to the end of the input without its descriptor being found. */
+ | 'unresolved-descriptor';
+export interface ForwardIndexSnapshot {
+    /** Entries whose bytes have all arrived, in archive order. Nothing here is still in transit. */
+    entries: ForwardEntry[];
+    /** The offset up to which the archive is accounted for: the end of the last entry in `entries`. */
+    parsedTo: number;
+    /** The central directory was reached, so `entries` is the whole archive. */
+    done: boolean;
+    stopped: ForwardStop | null;
+}
+/**
+ * Feeds on the bytes of an archive in order and collects entries as their local headers pass.
+ * Chunks may be of any size and may split a header, a descriptor or a name anywhere.
+ */
+export declare class LocalHeaderScanner {
+    readonly entries: ForwardEntry[];
+    parsedTo: number;
+    done: boolean;
+    stopped: ForwardStop | null;
+    /** Bytes not yet consumed, carried between pushes. Small: a header prefix or a descriptor tail. */
+    private buffer;
+    /** Absolute offset of `buffer[0]`. */
+    private position;
+    private state;
+    push(chunk: Uint8Array): void;
+    /** The input ended. A descriptor still being looked for can now never be found. */
+    finish(): void;
+    snapshot(): ForwardIndexSnapshot;
+    private consume;
+    private drain;
+    /** Returns false when more bytes are needed or the scan has ended. */
+    private readHeader;
+    /**
+     * Looks for the descriptor that ends `entry`. Returns false when more bytes are needed.
+     *
+     * A candidate is the signature followed by a compressed size equal to the bytes seen since the
+     * data began. Bytes that cannot start a candidate that fits are consumed; the last few are kept,
+     * since a descriptor can straddle two chunks.
+     */
+    private findDescriptor;
+    private record;
+}

package/types/shared/idb.d.ts

@@ -0,0 +1,9 @@
+import type { PackageRecord } from './protocol';
+export declare function getPackage(pkgId: string): Promise<PackageRecord | undefined>;
+export declare function putPackage(record: PackageRecord): Promise<void>;
+export declare function deletePackage(pkgId: string): Promise<void>;
+export declare function allPackages(): Promise<PackageRecord[]>;
+export declare function touchPackage(pkgId: string): Promise<void>;
+export declare function updatePackage(pkgId: string, patch: Partial<PackageRecord>): Promise<PackageRecord | undefined>;
+/** Packages ordered coldest first. Eviction walks this list. */
+export declare function packagesByAge(): Promise<PackageRecord[]>;

package/types/shared/locks.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Web Lock names, one prefix per package: `h5p:<pkgId>:<what>`.
+ *
+ * The Jobs worker holds one per download or extraction for as long as it writes, and the element
+ * holds `playing`, shared, for as long as a package is loaded. Eviction reads
+ * `navigator.locks.query()` and never picks a package with anything held under its prefix. That
+ * is what makes a write in one tab, or a learner mid-video in another, safe from a quota squeeze
+ * caused by a package loading in a third — the `packages` table knows what is cold, but only the
+ * locks know what is in use right now, across every context on the origin.
+ */
+export declare function packageLockName(pkgId: string, what: string): string;
+export declare function packageLockPrefix(pkgId: string): string;
+/** Packages with a lock held under their prefix right now, from every tab and worker on the origin. */
+export declare function busyPackages(): Promise<Set<string>>;

package/types/shared/mime.d.ts

@@ -0,0 +1,7 @@
+export declare function extensionOf(entryName: string): string;
+export declare function contentTypeOf(entryName: string): string;
+/**
+ * True for entries the H5P runtime parses rather than streams. They are never chunked: a
+ * partially available script is worse than a slow one.
+ */
+export declare function isTextEntry(entryName: string): boolean;

package/types/shared/mp4.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Where an MP4 keeps its index, and how much of one we have to inflate to find out.
+ *
+ * A player cannot decode a single frame without `moov`: it holds the sample tables that say where
+ * every frame lives. `-movflags +faststart` moves it to the front of the file; without it — and
+ * it is not the default — it lands after `mdat`, which for a feature-length video means the last
+ * few kilobytes of a few hundred megabytes. Served over `Range` that costs one small request. Out
+ * of a deflated zip entry, where there is no restart point to seek to, it costs the whole file.
+ *
+ * So this decides which of the two a given entry is, off the first few dozen bytes of output.
+ */
+/** Boxes that may legitimately precede the one that decides the question. */
+export type MoovPosition = 
+/** `moov` came first: the player can start on a prefix. */
+'front'
+/** `mdat` came first, so the index is behind it: nothing plays until the whole entry exists. */
+ | 'trailing'
+/** Not enough bytes yet — ask again with more. */
+ | 'incomplete'
+/** Not an MP4, malformed, or the walk ran past its budget. Treated as `front`, the safe guess. */
+ | 'unknown';
+/** Past this much output, stop walking and serve progressively rather than stall the load. */
+export declare const MOOV_SCAN_LIMIT: number;
+export declare function isIndexedMovie(name: string): boolean;
+/**
+ * Walks the top-level box list until `moov` or `mdat` decides it.
+ *
+ * The naive form of this check — "is the second box `mdat`?" — is wrong often enough to matter:
+ * `ftyp`, `free`, `skip`, `wide`, `pdin` and `uuid` all legally sit in front, and a `uuid` holding
+ * an XMP blob runs to tens of kilobytes. The package that prompted all of this is laid out
+ * `ftyp`, `uuid`, `mdat`, so the second box is `uuid` and the shortcut reports the wrong answer
+ * on the one file it most needs to get right.
+ */
+export declare function findMoov(head: Uint8Array, limit?: number): MoovPosition;
+/**
+ * Reads as much of a stream as the walk needs and cancels the rest.
+ *
+ * Cancelling matters: the stream behind this is one ranged request spanning the entire entry, so
+ * leaving it open would pull the whole video to answer a question about its first 64 bytes.
+ */
+export declare function scanMoov(stream: ReadableStream<Uint8Array>, limit?: number): Promise<MoovPosition>;

package/types/shared/pkg-id.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Package identity. The id is derived from what identifies the bytes, not from a counter, so the
+ * same URL (with the same validator) or the same picked file finds its cached chunks again on a
+ * later visit.
+ */
+/**
+ * Id for a remote package. The validator (`ETag`, falling back to `Last-Modified`) is folded in
+ * when the host exposes one, so a republished archive at the same URL gets a new id instead of
+ * colliding with the stale chunks of the old one.
+ */
+export declare function remotePkgId(url: string, validator?: string | null): Promise<string>;
+/**
+ * Id for a picked file. Name, size and mtime are all a browser exposes. The descriptor row dies
+ * with the session because a `File` handle cannot be persisted, but the chunks survive and are
+ * found again when the same file is picked.
+ */
+export declare function filePkgId(file: {
+    name: string;
+    size: number;
+    lastModified: number;
+}): Promise<string>;

package/types/shared/protocol.d.ts

@@ -0,0 +1,232 @@
+/**
+ * The shapes crossing the three contexts: the page (element), the Service Worker and the Jobs
+ * worker. Everything here is structured-cloneable.
+ */
+/** How the bytes of an archive are reached. Persisted, so the worker can rebuild it after a restart. */
+export type SourceDescriptor = {
+    /** Host honours `Range`: read straight from the network, store nothing but extracted entries. */
+    type: 'range-http';
+    url: string;
+    size: number;
+    validator?: string | null;
+} | {
+    /** Host has CORS but ignores `Range`: the archive is downloaded into the chunk store first. */
+    type: 'chunked';
+    url: string;
+    /** `null` until the download finishes for a host that exposes no length. */
+    size: number | null;
+    validator?: string | null;
+} | {
+    /** A `File` from a picker. The handle cannot be persisted; the page re-sends it on request. */
+    type: 'file';
+    name: string;
+    size: number;
+    lastModified: number;
+};
+/** The two descriptors a URL can produce. Both carry a validator; a picked file has none. */
+export type RemoteSourceDescriptor = Exclude<SourceDescriptor, {
+    type: 'file';
+}>;
+/** What a row has been through. Written for whoever is looking at the table; read by nothing. */
+export type PackageStatus = 'registered' | 'indexed';
+/**
+ * Where to look for libraries a package does not carry. `hub` resolves per content type against
+ * the official H5P content-type server; anything else is the URL of a `.h5p` that carries them.
+ */
+export type LibrarySource = 'hub' | {
+    url: string;
+};
+/** The official H5P content-type server. It answers with CORS and honours `Range`. */
+export declare const HUB_CONTENT_TYPE_URL = "https://api.h5p.org/v1/content-types/";
+/** What an archive declared but does not contain. */
+export interface MissingLibraries {
+    /** `mainLibrary` from `h5p.json`, which is what the hub is keyed on. */
+    mainLibrary?: string;
+    /** Folder names as the runtime will ask for them, e.g. `H5P.InteractiveVideo-1.27`. */
+    folders: string[];
+    /** True when the archive carries no libraries at all — the usual content-only export. */
+    all: boolean;
+}
+/** One row of the IndexedDB `packages` table. */
+export interface PackageRecord {
+    pkgId: string;
+    source: SourceDescriptor;
+    /**
+     * A second package whose libraries fill this one's gaps. Stored rather than held in memory so
+     * a restarted worker reattaches it without asking the page again.
+     */
+    libraryPkgId?: string;
+    /**
+     * `libraries` marks an archive registered only to supply library folders to another package.
+     * It is never played, so it is not held to carrying everything its own `h5p.json` declares.
+     */
+    role?: 'content' | 'libraries';
+    /** Absolute URLs of the frame assets, resolved by the element and used to synthesize the frame. */
+    frameAssets: FrameAssets;
+    /** Extra CSP host-sources the host page vouches for. See the `allow-origins` attribute. */
+    allowOrigins?: string[];
+    status: PackageStatus;
+    title?: string;
+    lastPlayed: number;
+    /** The element version that wrote the row. Read by nothing today; a future migration keys on it. */
+    version: string;
+}
+export interface FrameAssets {
+    /** h5p-standalone `main.bundle.js` — the loader that walks dependencies and boots the runtime. */
+    mainJs: string;
+    /** h5p-standalone `frame.bundle.js` — h5p.js, jQuery and the core runtime. */
+    frameJs: string;
+    /** h5p-standalone `styles/h5p.css`. */
+    frameCss: string;
+}
+export type ErrorCode = 'no-cors' | 'no-worker' | 'network' | 'quota' | 'bad-archive' | 'runtime';
+export declare class PlayerError extends Error {
+    code: ErrorCode;
+    /** Set when the failure is a package that declared libraries it does not carry. */
+    missingLibraries?: MissingLibraries;
+    constructor(code: ErrorCode, message: string, options?: {
+        cause?: unknown;
+        missingLibraries?: MissingLibraries;
+    });
+}
+export type ToWorkerMessage = {
+    type: 'ping';
+} | {
+    type: 'register';
+    record: PackageRecord;
+} | {
+    type: 'index';
+    pkgId: string;
+}
+/** Answer to a `need-file` request: the page hands back the `File` the worker lost on restart. */
+ | {
+    type: 'file';
+    pkgId: string;
+    file: File;
+}
+/** Points a package at another one, already registered and indexed, for its libraries. */
+ | {
+    type: 'attach-libraries';
+    pkgId: string;
+    libraryPkgId: string;
+};
+/**
+ * An entry a cold load cannot serve without a background inflate: large and deflated, so there is
+ * no byte in it a `Range` request can reach without the whole stream up to that point.
+ *
+ * These are named in the `indexed` reply so the work can be started before the content asks for
+ * it. That is the only lever there is on a non-faststart mp4, whose index sits at the very end:
+ * the first frame is undecodable until the last byte lands, so the wait cannot be shortened, only
+ * moved somewhere the learner is not watching it.
+ */
+export interface PrefetchEntry {
+    entry: string;
+    /** Uncompressed size — the number that decides whether starting it early is worth the bytes. */
+    size: number;
+}
+export type WorkerReply = {
+    ok: true;
+    type: 'pong';
+    version: string;
+} | {
+    ok: true;
+    type: 'indexed';
+    pkgId: string;
+    entryCount: number;
+    title?: string;
+    prefetch?: PrefetchEntry[];
+    /** Built from the forward index of an archive still downloading, not its central directory. */
+    partial?: boolean;
+    /** For a partial index: whether everything the runtime needs to boot has arrived. */
+    ready?: boolean;
+} | {
+    ok: true;
+    type: 'ack';
+} | {
+    ok: false;
+    code: ErrorCode;
+    message: string;
+    missingLibraries?: MissingLibraries;
+};
+/**
+ * Sent to the frame client, which relays it to its parent element. The Service Worker cannot run
+ * a job itself: browsers kill a worker event after a few minutes and a killed inflate cannot
+ * resume, so every long extraction is handed back to the page.
+ */
+export type FromWorkerMessage = {
+    type: 'need-job';
+    pkgId: string;
+    entry: string;
+} | {
+    type: 'need-file';
+    pkgId: string;
+};
+export type ToJobsMessage = {
+    type: 'download';
+    pkgId: string;
+    source: SourceDescriptor;
+} | {
+    type: 'extract';
+    pkgId: string;
+    entry: string;
+    source: SourceDescriptor;
+    file?: File;
+} | {
+    type: 'abort';
+    pkgId: string;
+};
+export type FromJobsMessage = {
+    type: 'progress';
+    pkgId: string;
+    entry?: string;
+    loaded: number;
+    total: number | null;
+} | {
+    type: 'done';
+    pkgId: string;
+    entry?: string;
+    size: number;
+} | {
+    type: 'failed';
+    pkgId: string;
+    entry?: string;
+    code: ErrorCode;
+    message: string;
+};
+/**
+ * H5P's own iframe-resizing protocol, spoken between the content and whatever embeds it. The
+ * frame sends these to `window.parent`; the element answers them. See `h5p-resizer.js` in
+ * h5p-php-library, which is the reference implementation of this side.
+ */
+export interface H5PResizerMessage {
+    context: 'h5p';
+    action: 'hello' | 'prepareResize' | 'resize' | 'resizePrepared' | 'ready';
+    scrollHeight?: number;
+    clientHeight?: number;
+}
+export type FromFrameMessage = {
+    channel: 'h5p-player';
+    type: 'ready';
+    pkgId: string;
+} | {
+    channel: 'h5p-player';
+    type: 'xapi';
+    pkgId: string;
+    statement: unknown;
+    verb?: string;
+} | {
+    channel: 'h5p-player';
+    type: 'finished';
+    pkgId: string;
+    statement: unknown;
+} | {
+    channel: 'h5p-player';
+    type: 'error';
+    pkgId: string;
+    message: string;
+} | {
+    channel: 'h5p-player';
+    type: 'relay';
+    pkgId: string;
+    payload: FromWorkerMessage;
+};

package/types/shared/range.d.ts

@@ -0,0 +1,16 @@
+/** A byte range with an inclusive end, the form HTTP uses. */
+export interface ByteRange {
+    start: number;
+    end: number;
+}
+export type RangeResult = ByteRange | 'none' | 'unsatisfiable';
+/**
+ * Parses a `Range` header against a known resource size. Only single `bytes` ranges are handled;
+ * a multi-range request is treated as absent, which is a legal response (the server may always
+ * answer `200` with the whole body).
+ *
+ * Returns `'none'` when there is no usable range and `'unsatisfiable'` when the range starts
+ * beyond the end of the resource, which the caller must answer with `416`.
+ */
+export declare function parseRange(header: string | null | undefined, size: number): RangeResult;
+export declare function contentRange(range: ByteRange, size: number): string;

package/types/shared/source.d.ts

@@ -0,0 +1,57 @@
+import { Reader, type CreateReadableOptions } from '@zip.js/zip.js';
+import { type RemoteSourceDescriptor, type SourceDescriptor } from './protocol';
+import type { ByteRange } from './range';
+/**
+ * Source adapters. One interface — a size and a byte-range read — over the three ways an archive
+ * can be reached. The Service Worker and the Jobs worker both build handles from the persisted
+ * descriptor, so neither has to know how the package was opened.
+ */
+export interface SourceHandle {
+    readonly descriptor: SourceDescriptor;
+    /** Total size in bytes. Known for every handle by the time one is built. */
+    readonly size: number;
+    /** Reads an inclusive byte range into memory. Callers keep these bounded. */
+    read(range: ByteRange): Promise<Uint8Array>;
+    /** Streams an inclusive byte range. Used to serve large stored entries without buffering. */
+    stream(range: ByteRange): Promise<ReadableStream<Uint8Array>>;
+}
+/**
+ * Decides how an archive can be reached.
+ *
+ * A single `GET` with `Range: bytes=0-0` answers both questions that matter: a host without CORS
+ * rejects it at the network layer, and a host that ignores `Range` answers `200` with the whole
+ * body (which is why the body is cancelled as soon as the headers arrive — a `HEAD` would prove
+ * neither, and is often blocked outright).
+ */
+export declare function probeSource(url: string, signal?: AbortSignal): Promise<RemoteSourceDescriptor>;
+/**
+ * Builds a handle from a persisted descriptor. A `file` descriptor needs the `File` itself, which
+ * only the page holds — the caller fetches it from the page before calling this.
+ */
+export declare function openSource(pkgId: string, descriptor: SourceDescriptor, file?: Blob, options?: {
+    /**
+     * Open a chunked archive that is still downloading. Only the forward index can address such
+     * a handle — its size is what has arrived so far — so this is for the reader built from that,
+     * never for zip.js, which needs the end of the file.
+     */
+    partial?: boolean;
+}): Promise<SourceHandle>;
+/**
+ * Presents a `SourceHandle` as a zip.js reader. zip.js only ever asks for the central directory
+ * and local headers through this, so reads stay small even for a multi-gigabyte archive.
+ */
+export declare class SourceReader extends Reader<SourceHandle> {
+    private readonly handle;
+    size: number;
+    constructor(handle: SourceHandle);
+    readUint8Array(index: number, length: number): Promise<Uint8Array>;
+    /**
+     * Streams a span in one read instead of paging through it.
+     *
+     * zip.js only calls `readUint8Array` when a reader does not provide this, and it then walks the
+     * entry in 64 kB steps. Over a `File` each step is a free `slice()`; over HTTP each one is a
+     * request, so inflating a 218 MB video meant about 3,500 round trips to the origin — slow
+     * enough to look like a hang, and enough to get throttled. One ranged request covers it.
+     */
+    createReadable(options?: CreateReadableOptions): ReadableStream<Uint8Array>;
+}

package/types/shared/stream-utils.d.ts

@@ -0,0 +1,7 @@
+import type { ByteRange } from './range';
+/**
+ * Restricts a byte stream to an inclusive range without buffering it. Used to answer a `Range`
+ * request from an entry the cache holds in one piece: the body is sliced as it flows rather than
+ * read into memory and cut.
+ */
+export declare function sliceStream(source: ReadableStream<Uint8Array>, range: ByteRange): ReadableStream<Uint8Array>;

package/types/sw/frame-document.d.ts

@@ -0,0 +1,19 @@
+import type { FrameAssets } from '../shared/protocol';
+export declare function sanitizeOrigins(values: readonly string[] | undefined): string[];
+export interface FrameDocumentOptions {
+    pkgId: string;
+    /** Absolute URL of the package root on the virtual file server, without a trailing slash. */
+    virtualRoot: string;
+    assets: FrameAssets;
+    nonce: string;
+    title?: string;
+    /**
+     * Extra origins the host vouches for, for content that reaches somewhere this package cannot
+     * know about — a tenant's own Panopto or Echo360 host, an in-house CDN.
+     */
+    allowOrigins?: string[];
+}
+export declare function buildContentSecurityPolicy(options: FrameDocumentOptions): string;
+export declare function buildFrameDocument(options: FrameDocumentOptions): string;
+/** A fresh nonce per response: reusing one across responses would defeat the point of having it. */
+export declare function createNonce(): string;

package/types/sw/mount.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The Service Worker half of the player: a virtual file server over a zip that is never
+ * extracted to disk, plus the frame document it synthesizes for the runtime to live in.
+ *
+ * It is deliberately stateless. Browsers terminate a worker between events, so every handler
+ * rebuilds what it needs from the `packages` table and the chunk store, and anything that cannot
+ * finish inside one event — downloading an archive, inflating a large entry — is handed to the
+ * page-side Jobs worker instead.
+ */
+export interface MountOptions {
+    /**
+     * Override the route base. Only useful when a host mounts the handlers into a worker whose
+     * scope is not where the routes should live.
+     */
+    scope?: string;
+}
+export declare function mountH5P(worker: ServiceWorkerGlobalScope, options?: MountOptions): void;