lecodes-web-host 2.0.0

package/README.md

@@ -0,0 +1,39 @@
+# lecodes-web-host
+
+A compiled LeCodes bundle in the browser, in the container it is given — the runtime as
+WebAssembly (`runtime/web`) with its host tables in TypeScript. A library: the page around the
+container is the embedder's (`lecodes-web-player` is the one this repo ships).
+
+```ts
+import { mount } from "lecodes-web-host"
+
+const host = await mount(root, code, { onError })
+host.destroy()
+```
+
+```ts
+import { createHost, parseBundleHeader } from "lecodes-web-host"
+
+const host = await createHost(root, { header: parseBundleHeader(code) })
+host.registerPlugin("map", half)          // a plugin's web half, before the bundle that names it
+host.run(code, { onError })                // repeatably
+host.setSafeArea({ top: 59, right: 0, bottom: 34, left: 0 })
+```
+
+The host fills `root` and follows its size. It knows nothing around it — no device, no frame, no
+zoom, no url, no message.
+
+| file | |
+|---|---|
+| `host.ts` | puts the parts together: the module, the tables, the frame |
+| `header.ts` | the bundle's header, and the runtime profile it means |
+| `page.ts` | the container, its size in device px, the canvases |
+| `engines/` | the 3D and the 2D surface (HostGL, HostScene2d) |
+| `tables/` | fetch, storage, device, app, socket, service, input, media — a file per table |
+| `plugins.ts` | the doors of the plugins' web halves |
+| `safeArea.ts` | the browser's insets, or the embedder's |
+| `errors.ts` | what a bundle threw, mapped to its source |
+| `system.ts`, `materials.ts` | the engine's built-in blobs, the archives a bundle asks for |
+
+The UI is `lecodes-web-canvas`: the TreeUI painted on a canvas over the scenes, a native view and
+a video under the picture, the field being edited over it.

package/dist/api.d.ts

@@ -0,0 +1,190 @@
+/** The runtime profile a bundle runs on: Filament + 2D + UI, creator-2d + UI, the UI alone. */
+export type HostProfile = "full" | "2d" | "ui";
+/** A face the app declared in its header, loaded before the first layout. */
+export type BootFont = {
+    family: string;
+    weight: number;
+    italic: boolean;
+    url: string;
+};
+/** The header the compiler writes at the top of a bundle. */
+export type BundleHeader = {
+    /** The SDK the bundle was compiled with; null = compiled before 2.0. Its major must be the host's. */
+    sdk: string | null;
+    name: string | null;
+    preloads: Set<string>;
+    /** `on` = the 3D engine up front, `defer` = the bundle creates it, `off` = the bundle names no 3D call. */
+    gl: "on" | "defer" | "off";
+    is2d: boolean;
+    /** The ids of the app's plugins. */
+    plugins: Set<string>;
+    bootFonts: BootFont[];
+};
+export type SafeAreaEdge = "top" | "right" | "bottom" | "left";
+/** Insets in logical px; `bars` = the edges that are exact-height system bars. */
+export type SafeArea = {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+    bars?: readonly SafeAreaEdge[];
+};
+/** A frame of a stack, in the app's source. */
+export type MappedFrame = {
+    fn: string | null;
+    source: string;
+    line: number;
+    column: number;
+};
+/** What a bundle threw. `native` = the engine's (no place in the app's source); `nativeFrames` =
+ *  the engine's functions, the innermost first, in a second report of the same error. */
+export type PreviewError = {
+    message: string;
+    frames: MappedFrame[];
+    stack?: string;
+    native?: boolean;
+    detail?: string;
+    nativeFrames?: string[];
+};
+export type HostOptions = {
+    /** The header of the bundle the host is for (`parseBundleHeader`): its engines decide the profile,
+     *  its materials the archives, its fonts the boot faces. */
+    header?: BundleHeader;
+    /** The runtime profile, in place of the header's (a host with no bundle yet: an editor). */
+    profile?: HostProfile;
+    /** false = an engine-only host: no UI renderer, no fonts. Default true. */
+    ui?: boolean;
+    /** The project, as the key its storage is kept under. Default: the header's name. */
+    project?: string;
+    /** Insets the embedder took of the container; absent = the page's own (`env(safe-area-inset-*)`). */
+    safeArea?: SafeArea;
+    /** device.language. Default: the browser's. */
+    language?: () => string;
+    /** The url the app was opened with (app.launchUrl). */
+    launchUrl?: string;
+    /** app.setOrientation sink; absent = a best-effort screen.orientation.lock on the page. */
+    onOrientation?: (mode: "landscape" | "portrait" | "auto") => void;
+    /** Listen for keyboard keys (Input.key). Default true. */
+    keyboard?: boolean;
+    /** Windows to listen on for keys besides the host's own. */
+    keyboardTargets?: Window[];
+};
+export type RunOptions = {
+    /** Called when this bundle throws, with the error mapped back to its source. */
+    onError?: (error: PreviewError) => void;
+    /** The bundle's header, in place of the one read from its first lines. */
+    header?: Pick<BundleHeader, "sdk" | "plugins">;
+};
+export type Run = {
+    /** Stop attributing errors to this run. */
+    dispose(): void;
+};
+export type WebViewChannel = {
+    emit(event: string, data?: any): void;
+};
+export type WebViewInstance = {
+    el: HTMLElement;
+    call?(method: string, args: any[]): any | Promise<any>;
+    destroy?(): void;
+};
+export type WebViewFactory = (params: any, channel: WebViewChannel, doc: Document) => WebViewInstance;
+export type ServiceChannel = {
+    emit(event: string, data?: any): void;
+};
+export type ServiceInstance = {
+    call?(method: string, args: any[]): any | Promise<any>;
+    close?(): void;
+};
+export type ServiceFactory = (params: any, channel: ServiceChannel) => ServiceInstance;
+export type HalfHost = {
+    /** `version` = the contract version the half was generated from. */
+    registerView(name: string, factory: WebViewFactory, version?: number): void;
+    registerService(name: string, factory: ServiceFactory, version?: number): void;
+    /** Store bytes in the host's buffer table: the handle a File crosses as. */
+    putBuffer(bytes: ArrayBuffer): number;
+    getBuffer(systemId: number): ArrayBuffer | Uint8Array | null | undefined;
+};
+/** What a plugin's web half exports. */
+export type PluginHalf = (host: HalfHost) => void;
+export type Rect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/** An element of the render tree: where it is, and the style it is painted in (resolved). */
+export type RenderNode = {
+    id: number;
+    type: string;
+    name?: string;
+    rect: Rect;
+    style: Record<string, any>;
+    text?: string;
+    lines?: string[];
+    value?: string;
+    state?: {
+        pressed?: boolean;
+        focused?: boolean;
+        classes?: string[];
+    };
+    clip?: boolean;
+    scroll?: {
+        offset: number;
+        content: number;
+        axis: "x" | "y";
+    };
+    children: RenderNode[];
+};
+/** What is shown, bottom to top: the screen, the screen that left (in a transition), the widgets. */
+export type Layer = {
+    tree: RenderNode;
+    leaving?: boolean;
+    widget?: boolean;
+    backdrop?: {
+        color: number;
+    };
+};
+export type HostUI = {
+    /** The layers the host paints now. */
+    frame(): Layer[];
+    /** The elements named `name`. */
+    findAll(name: string): RenderNode[];
+    /** The render tree as JSON / as text (what `lecodes render` writes). */
+    serialize(): unknown;
+    toText(): string;
+    /** A node's resolved padding: left, top, right, bottom. */
+    paddingOf(node: number): [number, number, number, number];
+    /** A pointer, in the app's logical px (what the host does with the page's own events). */
+    pointerDown(pointer: number, x: number, y: number): void;
+    pointerMove(pointer: number, x: number, y: number): void;
+    pointerUp(pointer: number, x: number, y: number): void;
+};
+export type Host = {
+    readonly profile: HostProfile;
+    /** The runtime module (an embedder that reads the engine directly: an editor). */
+    readonly M: Record<string, any>;
+    /** The runtime's world: the bundle's globals (`_creator`, `_creatorTree`, `_creatorApp`, …). */
+    readonly world: Record<string, unknown>;
+    /** The UI as the host paints it; null on an engine-only host. */
+    readonly ui: HostUI | null;
+    /** Evaluate a bundle. Throws when the bundle is of another SDK major than this host. */
+    run(code: string, options?: RunOptions): Run;
+    /** A plugin's web half, by the id an app lists it under; a bundle gets the ones its header names. */
+    registerPlugin(id: string, half: PluginHalf): void;
+    hasPlugin(id: string): boolean;
+    /** Where a stack of the running bundle leads in its source. */
+    locate(error: unknown): MappedFrame[];
+    /** The insets the app is told now. */
+    safeArea(): SafeArea;
+    /** The embedder's insets (it drew over the container), or null for the page's own. */
+    setSafeArea(area: SafeArea | null): void;
+    /** A warm link ("url") or a synthetic lifecycle event ("pause", "resume"). */
+    emitAppEvent(event: string, data?: string): void;
+    destroy(): void;
+};
+/** Bring a host up in `root`; it fills the element and follows its size. */
+export type CreateHost = (root: HTMLElement, options?: HostOptions) => Promise<Host>;
+/** A host for this bundle, and the bundle run on it. */
+export type Mount = (root: HTMLElement, code: string, options?: Omit<HostOptions, "header" | "profile"> & RunOptions) => Promise<Host>;
+export type ParseBundleHeader = (code: string) => BundleHeader;
+export type ProfileOf = (header: BundleHeader) => HostProfile;