@missing-elements/h5p-offline-player 0.1.0

package/types/sw/package-reader.d.ts

@@ -0,0 +1,242 @@
+import { type FileEntry } from '@zip.js/zip.js';
+import { type MissingLibraries, type PrefetchEntry } from '../shared/protocol';
+import { type SourceHandle } from '../shared/source';
+import type { ByteRange } from '../shared/range';
+import type { ForwardIndexSnapshot } from '../shared/forward-index';
+/**
+ * The package reader: a zip central directory turned into a name → entry index, plus the decision
+ * of how each entry gets served. It does not walk dependencies — h5p-standalone resolves
+ * `preloadedDependencies` itself and asks for the files it needs by name.
+ */
+export type Strategy = 
+/** Small, or text the runtime has to parse whole: inflate once into the cache, then serve. */
+{
+    kind: 'inline';
+}
+/** Large and stored (method 0): the bytes are already flat in the archive, so slice them. */
+ | {
+    kind: 'slice';
+}
+/** Large and deflated (method 8): the Jobs worker inflates into chunks, served progressively. */
+ | {
+    kind: 'chunked';
+};
+/** The parts of `h5p.json` the player needs. Everything in it comes from an untrusted archive. */
+export interface PackageManifest {
+    title?: string;
+    mainLibrary?: string;
+    preloadedDependencies?: LibraryDependency[];
+}
+export interface LibraryDependency {
+    machineName: string;
+    majorVersion: string | number;
+    minorVersion: string | number;
+}
+export interface IndexedEntry {
+    /** Normalised name, the form the virtual server routes on. */
+    name: string;
+    size: number;
+    compressedSize: number;
+    method: number;
+    strategy: Strategy;
+    /** The zip.js entry, for an index read from the central directory. Absent for a forward entry. */
+    zip?: FileEntry;
+    /** Where the compressed bytes begin, when the local header has already been read. */
+    dataStart?: number;
+    encrypted?: boolean;
+}
+/**
+ * An entry together with the archive it lives in. A package may be served from more than one:
+ * content from the one the user opened, libraries from a bundle attached to fill its gaps.
+ */
+export interface LocatedEntry {
+    reader: PackageReader;
+    entry: IndexedEntry;
+}
+export declare class PackageReader {
+    private readonly handle;
+    readonly pkgId: string;
+    readonly entries: Map<string, IndexedEntry>;
+    readonly rejected: string[];
+    manifest: PackageManifest;
+    /**
+     * Built from the forward index of an archive still downloading. Entries arrive as the download
+     * does — `absorb()` takes them in — and every answer is provisional until the archive is whole
+     * and a reader from its central directory replaces this one.
+     */
+    readonly partial: boolean;
+    /** For a partial reader: how far the archive is accounted for, and whether its index is complete. */
+    parsedTo: number;
+    forwardDone: boolean;
+    private forwardStopped;
+    private absorbed;
+    /** Top-level folder of the newest entry: the one folder that may still be receiving files. */
+    private lastTopFolder;
+    /** Archives consulted, in order, for an entry this one does not have. */
+    private readonly fallbacks;
+    /** Library folders reachable from here, built on first use and dropped when `use()` adds more. */
+    private librariesByName;
+    /** Data offsets of stored entries, each read from its local header once. */
+    private readonly dataRanges;
+    private constructor();
+    get title(): string | undefined;
+    static open(pkgId: string, handle: SourceHandle, options?: {
+        requireLibraries?: boolean;
+    }): Promise<PackageReader>;
+    /**
+     * A reader over an archive that is still downloading, from the entries its local headers have
+     * given up so far. Nothing is asserted here: what is missing may simply not have arrived.
+     */
+    static fromForwardIndex(pkgId: string, handle: SourceHandle, snapshot: ForwardIndexSnapshot): Promise<PackageReader>;
+    /**
+     * Takes in the entries a newer snapshot has and this reader does not. Snapshots are cumulative
+     * and in archive order, so only the tail is new; the same first-occurrence rule as the full
+     * index applies, so a later duplicate can never shadow an entry already served.
+     */
+    absorb(snapshot: ForwardIndexSnapshot): Promise<boolean>;
+    /**
+     * For a partial reader: whether the runtime could boot from what has arrived — `h5p.json`, and
+     * for every dependency it declares a folder that is present and finished arriving. A folder has
+     * finished once an entry of a later folder has been seen, since exporters write a folder's files
+     * together; only the newest folder may still be growing. An index the scanner had to give up on
+     * never says ready: what it could not see must wait for the central directory.
+     */
+    bootReady(): boolean;
+    /**
+     * For a partial reader: a miss that can be answered without waiting for more of the archive.
+     * True when the entry's top-level folder has already finished arriving, or when the request
+     * is h5p-standalone's versioned probe on a package that keeps that library unversioned.
+     */
+    provablyAbsent(name: string): boolean;
+    private folderComplete;
+    private hasFolder;
+    /** Adds an archive to consult for entries this one does not carry. */
+    use(reader: PackageReader): void;
+    /**
+     * Looks an entry up in this archive, then in each attached one.
+     *
+     * A miss on a library path is retried against a compatible version of the same library, so
+     * content asking for `H5P.Text-1.0/...` is served from `H5P.Text-1.1/...` when that is what
+     * the attached bundle happens to ship.
+     */
+    get(name: string): LocatedEntry | undefined;
+    /** Exact lookup, this archive first and then each attached one, in order. */
+    private locate;
+    private locateCompatible;
+    /**
+     * Library folders reachable from here, this archive's own taking precedence.
+     *
+     * Memoised, because this runs on the miss path and misses are not rare: h5p-standalone probes
+     * `<Library>-<major>.<minor>/library.json` on purpose to learn whether a package uses versioned
+     * folders, so every load walks through here several times. Rebuilding a map over every entry
+     * name — two thousand of them in a real package — on each of those is work that never changes
+     * its answer. The entry set is fixed after `open`; only `use()` can change the result, and it
+     * drops the cache.
+     */
+    private availableLibraries;
+    /** Every entry name reachable through this reader, including the attached archives. */
+    entryNames(): Set<string>;
+    /** What `h5p.json` declares but nothing reachable from here provides. */
+    missingLibraries(): MissingLibraries | null;
+    /** True when another archive is supplying entries this one does not have. */
+    get hasFallbacks(): boolean;
+    /**
+     * The manifest as the runtime should see it once a library bundle is attached.
+     *
+     * A content-only export does not just drop the library folders, it also strips
+     * `preloadedDependencies` down to the main library — so the runtime would load Interactive
+     * Video and none of the interaction types used inside it, and the first interaction would fail
+     * with "Unable to find constructor". The bundle's own manifest is the list the content type
+     * was published with, so the two are merged: a dependency is kept only if its folder is
+     * actually reachable, and the content's own version wins when both archives have one.
+     */
+    mergedManifest(): PackageManifest;
+    assertLibrariesPresent(): void;
+    /**
+     * Entries that cannot be served cold without a background inflate, in archive order.
+     *
+     * Everything else is reachable on demand: a stored entry is already flat in the archive and
+     * gets sliced, and a small one is cheap to inflate when asked for. Only a large deflated entry
+     * makes the runtime wait on a job, so only these are worth starting early.
+     *
+     * Archive order, not largest first: the point is to have an entry before the learner reaches
+     * it, and the order the packager wrote them in tracks the order the content uses them far
+     * better than size does. The biggest video is not usually the first one on screen.
+     */
+    prefetchable(): PrefetchEntry[];
+    /**
+     * Inflates an entry into a stream. The stream is handed straight to `cache.put()` or to a
+     * `Response`, so the entry never sits in memory as a whole.
+     *
+     * An entry from the central directory goes through zip.js. A forward entry has no zip.js object
+     * behind it and is inflated directly: its compressed span is known from its local header, and
+     * `DecompressionStream` does the rest — the same codec zip.js would have used.
+     */
+    inflate(entry: IndexedEntry): ReadableStream<Uint8Array>;
+    /**
+     * Byte range of an entry's compressed data inside the archive. The central directory records
+     * where the *local* header starts, and the local header's own name and extra fields are what
+     * stand between it and the bytes, so the header has to be read to find them — unless a forward
+     * entry already knows, having come from that very header.
+     *
+     * Read once per entry and kept as a promise: a media element opens with a burst of range
+     * requests, and every one of them used to pay a round trip for the same thirty bytes — over
+     * HTTP, a second request on top of the one for the data — and every seek after that paid it
+     * again. Now the burst shares one read and a seek pays none.
+     */
+    dataRange(entry: IndexedEntry): Promise<ByteRange>;
+    private inflateDirect;
+    private readDataRange;
+    /** Streams a range of an entry's compressed bytes straight out of the source. No storage. */
+    sliceStream(entry: IndexedEntry, range: ByteRange): Promise<ReadableStream<Uint8Array>>;
+}
+/**
+ * Serving strategy for one entry. Size decides first, then compression method: only a large
+ * deflated entry is worth the cost of a background extraction.
+ */
+export declare function chooseStrategy(name: string, entry: {
+    uncompressedSize: number;
+    compressionMethod: number;
+}): Strategy;
+export interface LibraryFolder {
+    machineName: string;
+    major: number;
+    minor: number;
+    folder: string;
+}
+/** Splits `H5P.Text-1.1` into its parts, or returns `null` for a folder that is not a library. */
+export declare function parseLibraryFolder(folder: string): LibraryFolder | null;
+/** Every library folder in a set of entry names, grouped by machine name. */
+export declare function indexLibraryFolders(entryNames: Iterable<string>): Map<string, LibraryFolder[]>;
+/**
+ * Picks the folder that satisfies a dependency, by H5P's own compatibility rule: the same major
+ * version, and a minor at least as high as the one asked for. Libraries are backward compatible
+ * within a major, which is why a platform installs one version per major and content authored
+ * against an older minor keeps working.
+ *
+ * This matters whenever libraries come from somewhere other than the package: a hub bundle ships
+ * the current `H5P.Text-1.1` while content authored earlier asks for `H5P.Text-1.0`, and without
+ * this every such request is a 404.
+ *
+ * The lowest satisfying version wins, as the closest to what the content was written against.
+ */
+export declare function resolveLibraryFolder(available: Map<string, LibraryFolder[]>, dependency: {
+    machineName: string;
+    major: number;
+    minor: number;
+}): string | undefined;
+/**
+ * The dependencies `h5p.json` declares that the archive does not actually carry. Pure, so the
+ * rule can be checked without building a zip.
+ */
+export declare function findMissingLibraries(entryNames: ReadonlySet<string>, manifest: PackageManifest): LibraryDependency[];
+/**
+ * What a package declares but does not carry, or `null` when it carries everything.
+ *
+ * Exports from h5p.com and h5p.org routinely leave the libraries out: the platform they came from
+ * already has them, so bundling them would be waste. Played anywhere else, such an archive is
+ * just a `content/` folder — the runtime asks for `<MainLibrary>/library.json`, gets a 404, and
+ * fails with nothing to go on.
+ */
+export declare function describeMissingLibraries(entryNames: ReadonlySet<string>, manifest: PackageManifest): MissingLibraries | null;
+export declare function explainMissingLibraries(missing: MissingLibraries): string;

package/types/sw/routes.d.ts

@@ -0,0 +1,26 @@
+/**
+ * URL shape of the virtual routes. Our own registration uses the scope `<swDir>h5p/`, so routes
+ * sit directly under it; `mountH5P` puts them at `<hostScope>h5p/`. Both spell the same thing —
+ * `…/h5p/virtual/…` and `…/h5p/frame/…` — so everything downstream works off one base.
+ */
+export interface Routes {
+    /** Absolute URL prefix, always ending in `h5p/`. */
+    base: string;
+    virtual: string;
+    frame: string;
+    ping: string;
+}
+export declare function routesFor(scope: string): Routes;
+export type RouteMatch = {
+    kind: 'ping';
+} | {
+    kind: 'frame';
+    pkgId: string;
+} | {
+    kind: 'entry';
+    pkgId: string;
+    path: string;
+} | {
+    kind: 'none';
+};
+export declare function matchRoute(routes: Routes, url: string): RouteMatch;

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

@@ -0,0 +1,9 @@
+import type { ByteRange } from '../shared/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>;
+/** Counts bytes as they pass, reporting progress without holding on to any of them. */
+export declare function tapProgress(source: ReadableStream<Uint8Array>, onBytes: (total: number) => void): ReadableStream<Uint8Array>;

package/types/sw/sw-entry.d.ts

@@ -0,0 +1 @@
+export {};