@neuroplastio/xterm-addon-hotty 0.1.0

package/dist/types/addon.d.ts

@@ -0,0 +1,170 @@
+import type { ITerminalAddon, Terminal } from "@xterm/xterm";
+import { type Policy } from "./network.ts";
+export interface HottyOptions {
+    /** Most surfaces at once (reported under `limits`). Default 64. */
+    maxSurfaces?: number;
+    /** Bytes of resources (reported under `limits`). Default 64 MB. */
+    resourceQuota?: number;
+    /** Called once per applied command batch, with timings, for measurements. */
+    onFrame?: (f: FrameStats) => void;
+    /** Called for commands that could not be decoded. */
+    onInvalid?: (reason: string) => void;
+    /**
+     * What surfaces may fetch from the network: the host's half of the network
+     * policy (SPEC §7.2), directive to sources, e.g.
+     * `{ "img-src": ["https://example.com"] }`. A document gets what it asks
+     * for (`<meta name="hotty-network">`) and this allows. Default: nothing.
+     * The embedding page's own CSP must allow these sources too.
+     */
+    network?: Policy;
+    /**
+     * Touch on the whole terminal (SPEC §9): a drag scrolls, over the cells
+     * and the surfaces alike, and a tap on the cells is a click for the
+     * program. This replaces xterm.js's own touch handling, which in 6.1 sends
+     * wheel reports with no position (NaN) and turns taps into nothing.
+     * Default true.
+     */
+    touch?: boolean;
+    /**
+     * What a wheel or a touch drag scrolls, over the cells and the surfaces
+     * alike (SPEC §9). `"terminal"` (the default): the terminal's scrollback,
+     * or on the alternate screen the program's wheel input. `"page"`: the page
+     * the terminal is in, for a page that shows a program's output whole, with
+     * the terminal as tall as what it shows. Neither the addon nor xterm.js
+     * takes a wheel or a touch then: the browser scrolls the page, natively,
+     * and the program hears no wheel. `touch` does nothing in this mode.
+     */
+    scroll?: "terminal" | "page";
+    /**
+     * Keys the browser keeps: they never reach the program, from the terminal
+     * or from a surface holding the keyboard, and the browser acts on them.
+     * A terminal cannot know which keys a program binds, so these are the
+     * browser's own. Default: `browserKeys`, which covers reload, zoom, full
+     * screen, the developer tools, and on a Mac everything with Cmd.
+     */
+    browserKeys?: (e: KeyboardEvent) => boolean;
+}
+/** The browser's own keys (the default for `browserKeys`): reload (F5, Ctrl
+ * or Cmd with R), zoom (Ctrl or Cmd with +, - or 0), full screen (F11), the
+ * developer tools (F12, Ctrl+Shift with I, J or C), and on a Mac everything
+ * with Cmd. */
+export declare function browserKeys(e: KeyboardEvent): boolean;
+export interface FrameStats {
+    commands: number;
+    /** Milliseconds spent applying them. */
+    applyMs: number;
+}
+export interface Inspected {
+    tag: string;
+    attrs: Record<string, string>;
+    text: string;
+    children: [string, string | null, string][];
+}
+/** `drag` stands for `dragstart`, `drag` and `dragend` (SPEC §4, §9.1). */
+export declare const EVENTS: string[];
+export declare class HottyAddon implements ITerminalAddon {
+    private term;
+    private readonly opts;
+    private readonly store;
+    private readonly surfaces;
+    private readonly placements;
+    private readonly assembler;
+    private readonly disposables;
+    private layer;
+    /** Commands held while synchronized output is on (PROTOCOL §5). */
+    private held;
+    private heldTimer;
+    private css;
+    private readonly policy;
+    private metrics;
+    private resizeTimer;
+    /** A surface's key is being forwarded to the terminal (`key`), and the
+     * terminal's own focus is held off meanwhile. A program in the page may
+     * answer the key inside its dispatch, since xterm.js parses what follows
+     * user input at once: a surface that gives the keyboard back then has
+     * its focus carried out once the key is through. */
+    private forwarding;
+    private focusAfter;
+    /** The wheel gesture under way: the surface its last wheel was over ("" for
+     * the cells), where it goes, and when that wheel came. */
+    private gesture;
+    constructor(options?: HottyOptions);
+    activate(term: Terminal): void;
+    dispose(): void;
+    /**
+     * An element of a surface as the program wrote it (tag, attributes, text,
+     * child elements): the shape the shared conformance vectors check
+     * (conformance/README.md). `null` if there is no such surface or element.
+     */
+    inspect(surface: string, id: string): Inspected | null;
+    private onOsc;
+    private run;
+    private submit;
+    private release;
+    private apply;
+    private handle;
+    private reply;
+    private send;
+    private dispatch;
+    private capabilities;
+    private surfaceName;
+    private existing;
+    private place;
+    /** As the native host: index `rows` times, then carriage return. */
+    private moveCursorBelow;
+    /** Puts every placed surface where its cells are now. */
+    private reposition;
+    private position;
+    private unplace;
+    private remove;
+    private reset;
+    private onBufferChange;
+    private host;
+    private cellTouch;
+    private pageScrollBound;
+    /** Whether the page scrolls, not the terminal (the `scroll` option). */
+    private get pageScrolls();
+    /**
+     * Wheels and touches on the cells left to the browser, which scrolls the
+     * page (`scroll: "page"`): they stop at the terminal's element, before
+     * xterm.js, which would take them for its scrollback, or turn a drag into
+     * arrow keys, and cancel the browser's scroll. Nothing here cancels it.
+     */
+    private bindPageScroll;
+    /** Scrolls what scrolls the terminal's page: its nearest ancestor that
+     * scrolls, or the document. */
+    private scrollPage;
+    private cellWheelBound;
+    /** A wheel over the cells begins or goes on with a gesture of the
+     * terminal's: a document that scrolls under the pointer as the terminal
+     * scrolls takes none of it (`wheelGesture`). */
+    private bindCellWheel;
+    /** Touch on the cells (the `touch` option), once the terminal is open. */
+    private bindTouch;
+    /** A wheel, at a point in the page, replayed on the terminal's screen,
+     * where xterm.js handles it as its own: scrollback, or mouse reports and
+     * arrow keys on the alternate screen. */
+    private forwardWheel;
+    /**
+     * A press with Alt held on a surface, a move of its gesture, or its
+     * release (SPEC §9.2), replayed on the cells beneath, where xterm.js
+     * handles them as its own mouse: a report to the program, with Alt, or
+     * its selection (rectangular, with Alt). The press goes to the screen,
+     * where xterm.js listens for presses; the moves and the release to its
+     * document, where it listens while a button is held. The keyboard goes
+     * back to the terminal first, as on a click on the cells (§10.1): a
+     * surface that had it sends `blur`.
+     */
+    private pressCells;
+    private ensureLayer;
+    private browserKey;
+    /** A box in the page as the buffer cells it covers (1-based, as xterm.js
+     * gives an OSC 8 link's range). */
+    private cellRange;
+    /** Cell size in CSS pixels (private in xterm.js), with a measured fallback. */
+    private cell;
+    private hostCss;
+    private scheme;
+    /** On every render: did the cell size, font or theme change? */
+    private checkMetrics;
+}

package/dist/types/delta.d.ts

@@ -0,0 +1,19 @@
+import type { Resolver } from "./resolver.ts";
+export declare class DeltaError extends Error {
+    readonly code: string;
+    constructor(code: string, detail: string);
+}
+export declare const OPS: string[];
+export declare class Deltas {
+    private readonly doc;
+    private readonly resolver;
+    constructor(doc: Document, resolver: Resolver);
+    /** Parses a fragment inert, cleaned and resolved. */
+    parse(html: string): Node[];
+    apply(op: string, target: string | undefined, key: string | undefined, payload: string): void;
+    /** Makes `old` (live) look like `neu` (parsed), keeping `old` where possible. Returns the node now in place. */
+    morphNode(old: Node, neu: Node): Node;
+    private syncAttributes;
+    /** Morphs the children of `parent` (live) into `kids` (parsed). */
+    morphChildren(parent: Node, kids: Node[]): void;
+}

package/dist/types/hostcss.d.ts

@@ -0,0 +1,48 @@
+import type { ITheme } from "@xterm/xterm";
+export interface Metrics {
+    /** Cell size in CSS pixels. */
+    cellW: number;
+    cellH: number;
+    fontFamily: string;
+    fontSize: number;
+}
+export declare function palette(theme: ITheme | undefined): {
+    fg: string;
+    bg: string;
+    ansi: string[];
+    dark: boolean;
+};
+/** The host stylesheet, the same for every surface. What scrolls is each
+ * document's own (`scrollCss`). */
+export declare function hostCss(theme: ITheme | undefined, m: Metrics): string;
+/** The host's own attribute on the root while the rows a document needs are
+ * measured. Under the addon's vendor prefix: `data-hotty-*` is the spec's
+ * (§15). */
+export declare const MEASURE = "data-xterm-hotty-measure";
+/** The host's own attribute on an element of a document that scrolls along
+ * one axis, whose `overflow` along the other is `auto` or `scroll`: that
+ * axis is clipped as `overflow: hidden` clips it (SPEC §5.3). */
+export declare const CLIP = "data-xterm-hotty-clip";
+/** Set on the root while the addon reads which elements need `CLIP`: the
+ * values the document gives them, without the host's. */
+export declare const UNCLIPPED = "data-xterm-hotty-unclipped";
+/**
+ * What scrolls in a document (SPEC §5.1, §5.3): the axes it asked for, a
+ * bitmask (1 vertically, 2 horizontally). `pageScrolls`: the page scrolls,
+ * not the terminal (the addon's `scroll` option), and the browser pans it
+ * from a surface.
+ *
+ * - **None:** a surface is a fixed rectangle of cells, and nothing in it
+ *   scrolls: what does not fit is clipped. The browser pans nothing on a
+ *   touch (a drag is the terminal's, SPEC §9; the surface forwards it),
+ *   unless the page scrolls, which the browser pans as from the cells.
+ *   Nothing shows a scrollbar, even with `overflow: auto`.
+ * - **Along the axes asked for,** the document scrolls as a page does, with
+ *   the browser's scrollbars, inside the frame: they take pixels, never
+ *   cells. The browser pans those axes on a touch.
+ * - **Along an axis not asked for,** the root and every element `CLIP`
+ *   marks are `overflow: hidden` there, important in the host's layer, so
+ *   that the document's CSS cannot undo it: no scrollbar, and nothing the
+ *   user does moves it.
+ */
+export declare function scrollCss(axes: number, pageScrolls: boolean): string;

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export { HottyAddon, EVENTS, browserKeys, type HottyOptions, type FrameStats, type Inspected } from "./addon.ts";
+export { encode, decodeAll, Control, OSC } from "./wire.ts";
+export { HOST, VERSION } from "./version.ts";

package/dist/types/network.d.ts

@@ -0,0 +1,18 @@
+export type Directive = "img-src" | "media-src" | "font-src" | "style-src";
+export declare const DIRECTIVES: readonly Directive[];
+/** Directive → sources: origins (`https://example.com`) or `https:`. */
+export type Policy = Partial<Record<Directive, string[]>>;
+/** A source in canonical form, or null if it is not one HOTTY allows. */
+export declare function source(s: string): string | null;
+/** A policy with only valid directives and sources. */
+export declare function clean(p: Policy | undefined): Policy;
+/** A document's request, from its `<meta name="hotty-network">` content (CSP syntax). */
+export declare function parse(content: string): Policy;
+/** What both halves allow: sources of the document that the host's cover. */
+export declare function intersect(host: Policy, doc: Policy): Policy;
+/** Whether a policy allows fetching an absolute URL for a directive. */
+export declare function allows(p: Policy, d: Directive, url: string): boolean;
+/** A directive's sources as CSP source expressions. */
+export declare function cspSources(p: Policy, d: Directive): string;
+/** The directive that covers an attribute of an element, if it fetches at all. */
+export declare function directiveFor(tag: string, attr: string, rel?: string): Directive | null;

package/dist/types/resolver.d.ts

@@ -0,0 +1,41 @@
+import { INVALID, type Store, type UrlContext } from "./resources.ts";
+export declare class Resolver {
+    /** The program's value of each attribute the resolver rewrote. */
+    private orig;
+    /** The program's text of each `<style>` whose CSS names a resource. */
+    private css;
+    /** Elements that name resources, and which. */
+    private refs;
+    /** Attributes the host set and the program did not write (a detached
+     * surface's `disabled`, SPEC §5.5): live, never reported. */
+    private own;
+    private readonly store;
+    /** The document's base URL and effective network policy (set per a=doc). */
+    ctx: UrlContext | undefined;
+    constructor(store: Store);
+    /** Cleans and resolves an inert subtree, in place. */
+    adopt(root: Node): void;
+    private allowed;
+    private cleanAttributes;
+    /** An attribute as the program wrote it. */
+    get(el: Element, name: string): string | null;
+    /** Every attribute as the program wrote it, in order. */
+    attributes(el: Element): [string, string][];
+    /** Sets an attribute of the host's own, which the program does not see. */
+    setOwn(el: Element, name: string, value: string): void;
+    /** Removes an attribute, if it is the host's own. */
+    removeOwn(el: Element, name: string): void;
+    /** Sets an attribute to the program's value, resolving URLs and CSS. */
+    set(el: Element, name: string, value: string): void;
+    remove(el: Element, name: string): void;
+    /** A `<style>`'s CSS as the program wrote it. */
+    cssOf(el: Element): string;
+    setCss(el: Element, text: string): void;
+    /** Re-resolves everything that names one of `names` (a resource changed);
+     * whether anything did. */
+    refresh(names: Set<string>): boolean;
+    private srcset;
+    private remember;
+    private track;
+}
+export { INVALID };

package/dist/types/resources.d.ts

@@ -0,0 +1,32 @@
+import { type Directive, type Policy } from "./network.ts";
+export declare const INVALID = "about:invalid";
+/** The base URL no document declared (SPEC §7.3): nothing under it loads. */
+export declare const NO_BASE = "https://hotty.invalid/";
+/** What a document's references resolve against (SPEC §7.2, §7.3). */
+export interface UrlContext {
+    /** The document's base URL. */
+    base: string;
+    /** The effective network policy: the host's half and the document's. */
+    policy: Policy;
+}
+export declare function isUrlAttr(name: string): boolean;
+export declare class Store {
+    private entries;
+    private used;
+    readonly quota: number;
+    /** Called with the names whose URL changed, so surfaces can re-resolve. */
+    onChange: (names: Set<string>) => void;
+    constructor(quota?: number);
+    put(name: string, mime: string, bytes: Uint8Array): void;
+    remove(name: string): boolean;
+    /** The `blob:` URL for a resource, or `null` if there is none (yet). */
+    url(name: string): string | null;
+    /** CSS text with every reference resolved; `names` collects the resources.
+     * Without a context (a stylesheet resource, shared by surfaces with
+     * different policies) nothing from the network is allowed. */
+    rewriteCss(css: string, names: Set<string>, ctx?: UrlContext): string;
+    /** Resolves one attribute value; `names` collects the resources it names.
+     * `d` is the directive that covers the attribute, if it fetches. */
+    resolveUrl(value: string, names: Set<string>, ctx?: UrlContext, d?: Directive | null): string;
+    private changed;
+}