@react-x11/components 0.1.0 → 0.2.1

package/dist/desktop-calendar/index.js

@@ -0,0 +1,213 @@
+// Read the calendars the user's desktop already has, and hand them to a
+// `<Calendar dayContent>`.
+//
+// The point of this module is that an app gets the user's real events —
+// Google, Microsoft, CalDAV, local — without asking for a single credential
+// and without an OAuth flow, because the desktop already did all of that. See
+// `./eds.js` for how, and `../calendar/` for what to draw them on.
+//
+// Nothing here opens a D-Bus connection. `useSessionBus()` (or `sessionBus()`
+// for the imperative path) hands over react-x11's shared one, so an app is one
+// name on the bus however many features it turns on.
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useSessionBus } from 'react-x11';
+import { DesktopCalendar } from './eds.js';
+export { DesktopCalendar, parseKeyFile } from './eds.js';
+export { IcalUnavailableError } from './ical.js';
+const pad = (n) => String(n).padStart(2, '0');
+/**
+ * The local calendar day a `Date` falls on, as `'YYYY-MM-DD'`.
+ *
+ * Deliberately a local three-liner rather than an import from `../calendar/`:
+ * no component in this package imports another, because a lateral import
+ * makes the two one unit in a bundler's eyes and an app that wanted only the
+ * events would start paying for the grid. The **format** is the contract they
+ * share, not the function — these keys index straight into a `<Calendar>`'s
+ * `dayContent`.
+ */
+function dayKeyOf(date) {
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+/**
+ * Occurrences grouped by the local day they appear on — which is what a
+ * calendar grid actually renders.
+ *
+ * An all-day event spans `[start, end)` across possibly several days, and a
+ * timed one can cross midnight, so an event lands under **every** day it
+ * touches rather than only under its start.
+ */
+export function byDay(events) {
+    const days = new Map();
+    for (const event of events) {
+        // `end` is exclusive, so a one-day all-day event ending at the next
+        // midnight must not also mark the next day.
+        const lastMs = Math.max(event.start.getTime(), event.end.getTime() - 1);
+        const last = new Date(lastMs);
+        const cursor = new Date(event.start.getFullYear(), event.start.getMonth(), event.start.getDate());
+        while (cursor <= last) {
+            const key = dayKeyOf(cursor);
+            const list = days.get(key);
+            if (list)
+                list.push(event);
+            else
+                days.set(key, [event]);
+            cursor.setDate(cursor.getDate() + 1);
+        }
+    }
+    return days;
+}
+const NO_EVENTS = [];
+const NO_CALENDARS = [];
+const NO_ERRORS = [];
+/** The calendars a caller asked for by uid, or every enabled one. `onlyKey`
+ *  is the comma-joined list, because an array prop is a new identity every
+ *  render and these two effects are keyed on it. */
+function pickCalendars(all, onlyKey) {
+    if (!onlyKey)
+        return all.filter((c) => c.enabled);
+    const wanted = new Set(onlyKey.split(','));
+    return all.filter((c) => wanted.has(c.uid));
+}
+/**
+ * The user's desktop calendar events, as rendering state.
+ *
+ * ```tsx
+ * const { byDay } = useDesktopCalendarEvents({ from, to });
+ *
+ * <Calendar
+ *   dayContent={(day, state) =>
+ *     byDay.get(day)?.slice(0, 3).map((ev) => (
+ *       <box key={ev.uid} style={{ width: 4, height: 4, borderRadius: 2,
+ *                                  backgroundColor: state.selected
+ *                                    ? state.color
+ *                                    : (ev.calendar.color ?? '$accent') }} />
+ *     ))
+ *   }
+ * />
+ * ```
+ *
+ * **`from` and `to` are read by their timestamps, not their identity**, so
+ * `new Date(...)` inline in the render is fine and will not re-query on every
+ * paint. That is the mistake this hook would otherwise invite, and it costs a
+ * D-Bus round trip per frame.
+ *
+ * `status` is `'unavailable'` when there is no session bus or `ical.js` is not
+ * installed — both are ordinary on a machine that simply does not have them,
+ * so neither throws, and `error` says which it was. Treat it as "no calendar
+ * integration here", not as a failure to report.
+ */
+export function useDesktopCalendarEvents(options) {
+    const { from, to, calendars: only, watch = false, enabled = true } = options;
+    const { bus } = useSessionBus();
+    const [events, setEvents] = useState(NO_EVENTS);
+    const [found, setFound] = useState(NO_CALENDARS);
+    const [errors, setErrors] = useState(NO_ERRORS);
+    const [status, setStatus] = useState('idle');
+    const [error, setError] = useState(null);
+    const [nonce, setNonce] = useState(0);
+    const refresh = useCallback(() => setNonce((n) => n + 1), []);
+    // Timestamps, not the Date objects: a caller writing `from={new Date(y, m, 1)}`
+    // in the render body hands us a new identity every paint, and an effect keyed
+    // on that would re-query the bus on every frame.
+    const fromMs = from.getTime();
+    const toMs = to.getTime();
+    const onlyKey = only ? only.join(',') : '';
+    useEffect(() => {
+        if (!enabled) {
+            setStatus('idle');
+            return undefined;
+        }
+        if (!bus) {
+            // `useSessionBus` is still connecting, or there is no bus at all. Its
+            // own `status` distinguishes them; from here both mean "nothing yet".
+            setStatus('unavailable');
+            setEvents(NO_EVENTS);
+            return undefined;
+        }
+        let live = true;
+        const desktop = new DesktopCalendar(bus);
+        const run = async () => {
+            setStatus('loading');
+            setError(null);
+            try {
+                const all = await desktop.listCalendars();
+                if (!live)
+                    return;
+                setFound(all);
+                const result = await desktop.eventsBetween(new Date(fromMs), new Date(toMs), { calendars: pickCalendars(all, onlyKey) });
+                if (!live)
+                    return;
+                setEvents(result.events);
+                setErrors(result.errors);
+                setStatus('ready');
+            }
+            catch (err) {
+                if (!live)
+                    return;
+                // No bus, no ical.js, no EDS on this desktop — all ordinary.
+                setError(err instanceof Error ? err : new Error(String(err)));
+                setEvents(NO_EVENTS);
+                setStatus('unavailable');
+            }
+        };
+        void run();
+        return () => {
+            live = false;
+            void desktop.dispose();
+        };
+        // `refresh` is stable; `nonce` is what a manual refresh moves.
+    }, [bus, enabled, fromMs, toMs, onlyKey, nonce, refresh]);
+    // The subscription is a **separate** effect, and deliberately not keyed on
+    // `nonce`: a change has to re-run the query, and only the query. Watching
+    // from inside the effect the change re-runs means every notification tears
+    // the views down and starts new ones — which is a loop as soon as anything
+    // is delivered while a view is starting, and was one for as long as
+    // `Start()` reported the range's existing contents as a change.
+    //
+    // The cost is one extra `listCalendars()` per range, not per refresh.
+    useEffect(() => {
+        if (!enabled || !watch || !bus)
+            return undefined;
+        let live = true;
+        let stopWatching = null;
+        const desktop = new DesktopCalendar(bus);
+        void (async () => {
+            try {
+                const all = await desktop.listCalendars();
+                if (!live)
+                    return;
+                stopWatching = await desktop.watch(new Date(fromMs), new Date(toMs), () => {
+                    // Re-query rather than patch: a recurrence master edited months
+                    // away changes what this range looks like.
+                    if (live)
+                        refresh();
+                }, { calendars: pickCalendars(all, onlyKey) });
+                if (!live)
+                    await stopWatching();
+            }
+            catch {
+                // No bus, no EDS, nothing to watch. The query effect above is what
+                // reports that to the caller; a second copy of it would only race.
+            }
+        })();
+        return () => {
+            live = false;
+            void (async () => {
+                if (stopWatching)
+                    await stopWatching();
+                await desktop.dispose();
+            })();
+        };
+    }, [bus, enabled, watch, fromMs, toMs, onlyKey, refresh]);
+    const grouped = useMemo(() => byDay(events), [events]);
+    return {
+        events,
+        byDay: grouped,
+        calendars: found,
+        errors,
+        status,
+        error,
+        refresh,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/desktop-calendar/index.js.map

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

package/dist/embed/client.d.ts

@@ -0,0 +1,121 @@
+import type { ExitInfo, ProcessHost, SpawnedProcess } from './host.js';
+/**
+ * Where the child is in its life.
+ *
+ * `'unavailable'` is not an error state to report as a failure: a machine
+ * with no terminal emulator installed, or no mpv, is an ordinary machine.
+ * Both components render their `fallback` on it, the way
+ * `useDesktopCalendarEvents` reports "no bus, no ical.js" rather than
+ * throwing.
+ */
+export type EmbedStatus = 'idle' | 'starting' | 'running' | 'exited' | 'unavailable';
+/**
+ * No backend for this component is installed.
+ *
+ * Thrown by a `PlanFactory`, caught by the hook, and turned into
+ * `status: 'unavailable'`. `tried` is what was looked for, so the message an
+ * app shows can name the install line rather than saying "not found".
+ */
+export declare class BackendUnavailableError extends Error {
+    readonly tried: readonly string[];
+    constructor(what: string, tried: readonly string[]);
+}
+/** What to run, and what to do with it once it is running. */
+export interface LaunchPlan {
+    /** Absolute path or a name on `PATH`. */
+    command: string;
+    args: readonly string[];
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    /** Which backend this plan chose, for `onBackend` and the handle. */
+    backend?: string;
+    /**
+     * Attach a control channel now that the process exists. Its return value is
+     * called at teardown, before the process is signalled.
+     */
+    attach?(process: SpawnedProcess): void | (() => void) | Promise<void | (() => void)>;
+    /** Always run at teardown — temporary directories, sockets. */
+    dispose?(): void | Promise<void>;
+}
+export interface PlanContext {
+    /** The `<foreign>` container the program must draw into. */
+    windowId: number;
+    host: ProcessHost;
+}
+/** Builds the command line, once the window to draw into exists. */
+export type PlanFactory = (context: PlanContext) => Promise<LaunchPlan>;
+export interface UseEmbeddedClientOptions {
+    /**
+     * **Must be referentially stable for as long as the child should keep
+     * running.** A new identity is the restart signal — that is how "the
+     * command changed" reaches a program that cannot be reconfigured in place —
+     * so a factory rebuilt every render restarts the child every render.
+     *
+     * Both components build theirs with `useMemo` over a *string* key rather
+     * than over the props themselves, because `command={['bash']}` is a new
+     * array on every paint and an effect keyed on that never settles. Same
+     * reason `useDesktopCalendarEvents` keys on `from.getTime()`.
+     */
+    plan: PlanFactory;
+    /** Defaults to `nodeProcessHost()`. */
+    host?: ProcessHost;
+    /** False holds off entirely — a pane that is not visible yet. */
+    enabled?: boolean;
+    /** Sent on unmount and on restart. Default `SIGTERM`. */
+    stopSignal?: string;
+    onStart?: (info: {
+        process: SpawnedProcess;
+        backend?: string;
+    }) => void;
+    onExit?: (info: ExitInfo) => void;
+    /** Spawn failures and missing backends alike. */
+    onError?: (err: Error) => void;
+}
+export interface EmbeddedClient {
+    status: EmbedStatus;
+    /** The last failure, including a `BackendUnavailableError`. */
+    error: Error | null;
+    pid: number | null;
+    /** The container window, once `<foreign>` has one. */
+    windowId: number | null;
+    /** Which backend the plan picked. */
+    backend: string | null;
+    /** Wire straight to `<foreign onReady>`. */
+    handleReady: (info: {
+        windowId: number;
+    }) => void;
+    /** Stop the child and start it again with a freshly built plan. */
+    restart: () => void;
+    /** Signal the child. `false` if there is not one. */
+    signal: (signal?: string) => boolean;
+}
+/**
+ * Run a program inside a `<foreign>`.
+ *
+ * ```jsx
+ * const client = useEmbeddedClient({ plan });
+ * return <foreign onReady={client.handleReady} style={{ flexGrow: 1 }} />;
+ * ```
+ *
+ * The `<foreign>` is rendered by the caller rather than here, because the
+ * element's props — style, focus, the `onEmbedded`/`onClientGone` handlers a
+ * component may want to compose with — belong to the component, not to the
+ * lifecycle.
+ */
+export declare function useEmbeddedClient(options: UseEmbeddedClientOptions): EmbeddedClient;
+/**
+ * The first of `candidates` that is installed, or a `BackendUnavailableError`
+ * naming all of them.
+ *
+ * Auto-detection rather than a hard dependency is the whole reason both
+ * components take a `backend` prop that defaults to `'auto'`: this package
+ * cannot depend on a binary, and most machines have exactly one of the ones
+ * it can drive.
+ */
+export declare function resolveBackend<T extends {
+    binaries: readonly string[];
+}>(host: ProcessHost, what: string, candidates: readonly T[]): Promise<{
+    backend: T;
+    path: string;
+}>;
+//# sourceMappingURL=client.d.ts.map

package/dist/embed/client.d.ts.map

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

package/dist/embed/client.js

@@ -0,0 +1,203 @@
+// The lifecycle both XEmbed wrappers have, with none of the vocabulary
+// either of them has.
+//
+// `<Terminal>` and `<MediaPlayer>` are the same component twice: render a
+// `<foreign>` with no `windowId` so it *adopts* whatever turns up inside it,
+// take the container id `onReady` hands over, spawn a program that draws into
+// that id, and hand the program back when the tree changes. Only the argv and
+// the control channel differ, and those are what the two `backends.ts` files
+// are for.
+//
+// Everything here is ordinary React state. The X part is one prop —
+// `onReady` — because core's `<foreign>` already owns the protocol
+// (react-x11#269, ntk#246): the reparent, the save set, `_XEMBED_INFO`, the
+// synthetic ConfigureNotify, and handing the client back on unmount without
+// ever destroying it.
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { nodeProcessHost } from './host.js';
+/**
+ * No backend for this component is installed.
+ *
+ * Thrown by a `PlanFactory`, caught by the hook, and turned into
+ * `status: 'unavailable'`. `tried` is what was looked for, so the message an
+ * app shows can name the install line rather than saying "not found".
+ */
+export class BackendUnavailableError extends Error {
+    tried;
+    constructor(what, tried) {
+        super(`@react-x11/components: no ${what} backend is installed — looked for ` +
+            `${tried.join(', ')}. Install one, or pass \`fallback\` to render ` +
+            'something else.');
+        this.name = 'BackendUnavailableError';
+        this.tried = tried;
+    }
+}
+/**
+ * Run a program inside a `<foreign>`.
+ *
+ * ```jsx
+ * const client = useEmbeddedClient({ plan });
+ * return <foreign onReady={client.handleReady} style={{ flexGrow: 1 }} />;
+ * ```
+ *
+ * The `<foreign>` is rendered by the caller rather than here, because the
+ * element's props — style, focus, the `onEmbedded`/`onClientGone` handlers a
+ * component may want to compose with — belong to the component, not to the
+ * lifecycle.
+ */
+export function useEmbeddedClient(options) {
+    const { plan, enabled = true, stopSignal = 'SIGTERM' } = options;
+    const host = useMemo(() => options.host ?? nodeProcessHost(), [options.host]);
+    const [windowId, setWindowId] = useState(null);
+    const [status, setStatus] = useState('idle');
+    const [error, setError] = useState(null);
+    const [pid, setPid] = useState(null);
+    const [backend, setBackend] = useState(null);
+    const [generation, setGeneration] = useState(0);
+    // The live child, for `signal()`. A ref rather than state because a caller
+    // reaching for it through a handle is not rendering, and re-rendering the
+    // tree because a pid arrived would be work for nothing.
+    const processRef = useRef(null);
+    // Handlers are read at the moment they fire, so a component that passes a
+    // fresh arrow function every render does not restart its child.
+    const handlers = useRef(options);
+    handlers.current = options;
+    const handleReady = useCallback((info) => {
+        setWindowId(info.windowId);
+    }, []);
+    const restart = useCallback(() => setGeneration((n) => n + 1), []);
+    const signal = useCallback((sig = 'SIGTERM') => {
+        const child = processRef.current;
+        return child ? child.kill(sig) : false;
+    }, []);
+    useEffect(() => {
+        if (!enabled || windowId === null) {
+            setStatus('idle');
+            return undefined;
+        }
+        let live = true;
+        let child = null;
+        let detach;
+        let planned = null;
+        const fail = (err, next) => {
+            const wrapped = err instanceof Error ? err : new Error(String(err));
+            if (!live)
+                return;
+            setError(wrapped);
+            setStatus(next);
+            handlers.current.onError?.(wrapped);
+        };
+        void (async () => {
+            setStatus('starting');
+            setError(null);
+            try {
+                planned = await plan({ windowId, host });
+            }
+            catch (err) {
+                // "no xterm on this machine" is not the same kind of news as "spawn
+                // failed", and only one of the two is worth a fallback.
+                fail(err, err instanceof BackendUnavailableError ? 'unavailable' : 'exited');
+                return;
+            }
+            if (!live) {
+                await planned.dispose?.();
+                return;
+            }
+            try {
+                child = await host.spawn(planned.command, planned.args, {
+                    cwd: planned.cwd,
+                    env: planned.env,
+                });
+            }
+            catch (err) {
+                await planned.dispose?.();
+                fail(err, 'exited');
+                return;
+            }
+            // Unmounted while `spawn` was in flight: nothing rendered it, so
+            // nothing should outlive it.
+            if (!live) {
+                child.kill(stopSignal);
+                await planned.dispose?.();
+                return;
+            }
+            processRef.current = child;
+            setPid(child.pid);
+            setBackend(planned.backend ?? null);
+            setStatus('running');
+            child.onExit((info) => {
+                if (!live)
+                    return;
+                processRef.current = null;
+                setStatus('exited');
+                setPid(null);
+                handlers.current.onExit?.(info);
+            });
+            child.onError((err) => fail(err, 'exited'));
+            handlers.current.onStart?.({ process: child, backend: planned.backend });
+            try {
+                const opened = await planned.attach?.(child);
+                // Opening a control channel can take seconds — the socket does not
+                // exist until the player creates it — so the teardown below may
+                // already have run with nothing to tear down. Closing it here is the
+                // only chance there will be.
+                if (live)
+                    detach = opened;
+                else
+                    opened?.();
+            }
+            catch (err) {
+                // A control channel that would not open is a degraded player, not a
+                // dead one: the video is already on screen.
+                fail(err, 'running');
+            }
+        })();
+        return () => {
+            live = false;
+            processRef.current = null;
+            // Order matters: drop the control channel first, so a socket close
+            // triggered by the signal is not reported as the player failing.
+            try {
+                detach?.();
+            }
+            catch {
+                // a channel that is already gone
+            }
+            child?.kill(stopSignal);
+            void planned?.dispose?.();
+        };
+        // `plan` is the restart signal — see the note on the option.
+    }, [enabled, windowId, plan, host, stopSignal, generation]);
+    return {
+        status,
+        error,
+        pid,
+        windowId,
+        backend,
+        handleReady,
+        restart,
+        signal,
+    };
+}
+/**
+ * The first of `candidates` that is installed, or a `BackendUnavailableError`
+ * naming all of them.
+ *
+ * Auto-detection rather than a hard dependency is the whole reason both
+ * components take a `backend` prop that defaults to `'auto'`: this package
+ * cannot depend on a binary, and most machines have exactly one of the ones
+ * it can drive.
+ */
+export async function resolveBackend(host, what, candidates) {
+    const tried = [];
+    for (const backend of candidates) {
+        for (const binary of backend.binaries) {
+            tried.push(binary);
+            const path = await host.which(binary);
+            if (path)
+                return { backend, path };
+        }
+    }
+    throw new BackendUnavailableError(what, tried);
+}
+//# sourceMappingURL=client.js.map

package/dist/embed/client.js.map

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

package/dist/embed/host.d.ts

@@ -0,0 +1,96 @@
+/** How a spawned child ended. */
+export interface ExitInfo {
+    /** Exit status, or `null` when a signal ended it. */
+    code: number | null;
+    /** The signal that ended it, or `null`. */
+    signal: string | null;
+}
+/**
+ * A running child, reduced to what an embedded client needs: its pid, a way
+ * to signal it, and the two things that can happen to it.
+ *
+ * Deliberately not node's `ChildProcess`. Listener registration is a method
+ * per event rather than an `EventEmitter`, so a fake is a dozen lines and
+ * cannot accidentally rely on emitter behaviour (`once`, `removeAllListeners`,
+ * the `error`-with-no-listener throw) that the real one has and a fake would
+ * have to reimplement.
+ */
+export interface SpawnedProcess {
+    readonly pid: number | null;
+    /** POSIX signal name. Returns whether it was delivered. */
+    kill(signal?: string): boolean;
+    onExit(listener: (info: ExitInfo) => void): void;
+    onError(listener: (err: Error) => void): void;
+}
+export interface SpawnOptions {
+    cwd?: string;
+    /**
+     * Added to the ambient environment rather than replacing it: a terminal
+     * with no `PATH` and no `HOME` is not a terminal. An explicit `undefined`
+     * removes a variable.
+     */
+    env?: Record<string, string | undefined>;
+}
+/**
+ * A line-oriented control channel to a player process — mpv's JSON IPC, VLC's
+ * rc interface. Text in, text out, and no framing: the protocols disagree
+ * about what a message is, so splitting is the caller's.
+ */
+export interface IpcSocket {
+    write(data: string): void;
+    onData(listener: (chunk: string) => void): void;
+    onClose(listener: () => void): void;
+    close(): void;
+}
+/** A private directory to put a control socket in, and how to remove it. */
+export interface ScratchSocket {
+    path: string;
+    dispose(): Promise<void>;
+}
+/**
+ * Everything the embedded-client components do outside their own process.
+ *
+ * Every method is async, including the ones whose node counterparts are not:
+ * the node modules behind them are loaded lazily (see the file comment), so
+ * the first call is a dynamic `import()` however synchronous `spawn` itself
+ * is. Nothing here runs during render, so the cost is invisible.
+ */
+export interface ProcessHost {
+    /**
+     * The absolute path `command` resolves to on `PATH`, or `null` when it is
+     * not installed. A command containing a slash is tested as-is.
+     */
+    which(command: string): Promise<string | null>;
+    spawn(command: string, args: readonly string[], options?: SpawnOptions): Promise<SpawnedProcess>;
+    /** A path in a fresh private directory, for a child to create a socket at. */
+    socketPath(prefix: string): Promise<ScratchSocket>;
+    /** Connect to a unix socket a child created. Rejects if it is not there. */
+    connect(path: string): Promise<IpcSocket>;
+    /** The ambient environment, for defaults and for `PATH`. */
+    environment(): Record<string, string | undefined>;
+}
+/** Thrown when a control socket does not appear. */
+export declare class IpcConnectError extends Error {
+    constructor(path: string, cause?: unknown);
+}
+/**
+ * The real one: node's `child_process`, `fs`, `net` and `os`.
+ *
+ * Cached, because it holds nothing per-caller and the module loads it does are
+ * worth doing once. An app that wants a *different* host (a container, a
+ * remote shell) passes it as the `processes` prop instead of replacing this.
+ */
+export declare function nodeProcessHost(): ProcessHost;
+/**
+ * Retry `connect` until the child has created its socket.
+ *
+ * Every player here is given a socket path and creates it *itself*, some
+ * milliseconds after it starts — so the first connect always loses the race,
+ * and "the socket is not there yet" and "the player failed to start" look
+ * identical for that window. Polling with a deadline is what separates them.
+ */
+export declare function connectWhenReady(host: ProcessHost, path: string, options?: {
+    timeoutMs?: number;
+    intervalMs?: number;
+}): Promise<IpcSocket>;
+//# sourceMappingURL=host.d.ts.map

package/dist/embed/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/embed/host.ts"],"names":[],"mappings":"AAwBA,iCAAiC;AACjC,MAAM,WAAW,QAAQ;IACvB,qDAAqD;IACrD,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,2CAA2C;IAC3C,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,2DAA2D;IAC3D,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,MAAM,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,GAAG,IAAI,CAAC;IACjD,OAAO,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAC;CAC/C;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CAC1C;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;IAChD,OAAO,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IACpC,KAAK,IAAI,IAAI,CAAC;CACf;AAED,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC/C,KAAK,CACH,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,cAAc,CAAC,CAAC;IAC3B,8EAA8E;IAC9E,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACnD,4EAA4E;IAC5E,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAC1C,4DAA4D;IAC5D,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CACnD;AAsGD,oDAAoD;AACpD,qBAAa,eAAgB,SAAQ,KAAK;IACxC,YAAY,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,EAGxC;CACF;AA+ED;;;;;;GAMG;AACH,wBAAgB,eAAe,IAAI,WAAW,CA0G7C;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,WAAW,EACjB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GACxD,OAAO,CAAC,SAAS,CAAC,CAcpB"}