@neuroplastio/xterm-addon-hotty 0.1.0-next.1

package/dist/types/surface.d.ts

@@ -0,0 +1,486 @@
+import { Deltas } from "./delta.ts";
+import { Resolver } from "./resolver.ts";
+import { type Policy } from "./network.ts";
+import { type Store } from "./resources.ts";
+/** A surface's CSP: nothing from the network but what the host grants. The
+ * `<base>` is the addon's own (a document's is read, then dropped), so any
+ * http(s) base is allowed. */
+export declare function csp(host: Policy): string;
+/** What a surface needs from the addon. */
+/** A window of a surface, in cells from its top-left corner (SPEC §5.2). */
+export interface Window {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface SurfaceHost {
+    layer: HTMLElement;
+    store: Store;
+    /** Sends a HOTTY message (an event) to the program. */
+    event(surface: string, kind: string, target: string, detail?: unknown): void;
+    /** A key the surface does not use (a keydown or its keyup), for the
+     *  terminal to send to the program as if typed there (SPEC §10.2). */
+    key(e: KeyboardEvent): void;
+    /** What the terminal would send the program for a key, sent nowhere
+     *  (SPEC §10.4: a text field names the key from it); null when the
+     *  terminal cannot tell. */
+    encodeKey(e: KeyboardEvent): string | null;
+    /** Sends the program what `encodeKey` gave, as typed. */
+    sendKey(data: string): void;
+    /** A key the browser keeps (the `browserKeys` option): the surface
+     *  leaves it to the browser rather than hand it to the terminal. */
+    browserKey(e: KeyboardEvent): boolean;
+    /** Gives the keyboard back to the terminal. */
+    focusTerminal(): void;
+    /** The host's half of the network policy (SPEC §7.2). */
+    policy: Policy;
+    /** The page scrolls, not the terminal (the `scroll` option): wheels and
+     *  touch drags over the surface are left to the browser. */
+    pageScrolls: boolean;
+    /** The wheel gesture a wheel over a document that scrolls belongs to:
+     *  where it began decides where the rest of it goes (`decide`, called for
+     *  a gesture's first wheel), as a browser latches scrolling to what it
+     *  began on. A gesture begun over the cells stays the terminal's. */
+    wheelGesture(surface: string, decide: () => Route): Route;
+    /** Scrolls the page by dx, dy pixels, where the page scrolls: for a
+     *  gesture the browser would give an element of the document instead. */
+    scrollPage(dx: number, dy: number): void;
+    /** A hyperlink (SPEC §9: a link with target="_blank") was hovered, left
+     *  or clicked: the terminal's, as an OSC 8 hyperlink is. `box` is the
+     *  link's box in the page. */
+    hyperlink(kind: "activate" | "hover" | "leave", e: MouseEvent, url: string, box: DOMRect): void;
+    /** A wheel event over the surface, or a touch drag made one: the
+     *  terminal's (SPEC §9), at a point in the page. */
+    wheel(e: WheelEvent, pageX: number, pageY: number): void;
+    /** A press with Alt held, a move of the gesture it began, or its release
+     *  (SPEC §9.2): the program's, as on the cells beneath, at a point in the
+     *  page. */
+    cells(kind: "down" | "move" | "up", e: MouseEvent, pageX: number, pageY: number): void;
+}
+/** The theme's colour scheme, as the host stylesheet declares it. */
+export type Scheme = "dark" | "light";
+/** Where a gesture or a key that scrolls goes in a document that scrolls
+ * (SPEC §5.3): the document (an element of it that can still move that
+ * way), the terminal, or nowhere (`overscroll-behavior` stopped it). */
+export type Route = "doc" | "terminal" | "stop";
+/** An element's cells, as the user sees it (SPEC §9: `area`). */
+export interface Area {
+    c: number;
+    r: number;
+    w: number;
+    h: number;
+}
+export declare class Surface {
+    readonly name: string;
+    readonly box: HTMLDivElement;
+    readonly frame: HTMLIFrameElement;
+    readonly doc: Document;
+    readonly resolver: Resolver;
+    readonly deltas: Deltas;
+    cols: number;
+    rows: number;
+    /** The part of the surface on screen, in cells (SPEC §5.2). */
+    win: Window;
+    autoRows: boolean;
+    private readonly host;
+    private readonly hostStyle;
+    /** Set while the program moves focus, so no `focus` event echoes back. */
+    private programFocus;
+    /** The document's base URL (SPEC §7.3). */
+    private base;
+    private keyboard;
+    /** Detached (SPEC §5.5): nothing in the surface reaches the program. */
+    private detachedState;
+    /** A press is on something that takes no focus (SPEC §10.1): the focus
+     * the browser gives the frame for it is not the surface's. */
+    private pressNothing;
+    /** The element a press focuses, until the browser is done with it. */
+    private pressed;
+    /** A press of another button than the primary one, until the browser is
+     * done with it: it neither takes nor gives back the keyboard. */
+    private auxPress;
+    private settling;
+    /** A drag under way (SPEC §9.1). */
+    private drag;
+    /** A drag just ended at a release: it reported its own click, so the
+     * browser's, which follows in the same task, is not reported. */
+    private dragReleased;
+    /** The placement asked for presses (`p=1`, SPEC §5.2). */
+    presses: boolean;
+    /** A mouse's or a pen's pointerdown came first: the mousedown that
+     * follows is the same press, not a tap's. */
+    private pointerPress;
+    /** The pointer of a press with Alt held (SPEC §9.2), until its release:
+     * the gesture is the program's. */
+    private altPointer;
+    /** Such a gesture just ended at a release: the browser's click that
+     * follows in the same task is not the surface's. */
+    private altReleased;
+    /** One cell, in CSS pixels: a drag's detail counts cells (SPEC §9.1). */
+    private cellW;
+    private cellH;
+    private css;
+    /** Keys whose keydown went to the program, so their keyup follows. */
+    private forwarded;
+    /** A run of row moves in a field (SPEC §10.2): the caret it left, and the
+     * place along the row it keeps. Anything else that moves the caret ends
+     * it. */
+    private goal;
+    /** The field shown as `text` while focused (`NO_CARET`). */
+    private masked;
+    /** Tab is moving focus: the field it reaches selects its text. */
+    private tabbing;
+    /** The rows the program heard last, while the placement asked for `fit`
+     * (`f=1`, SPEC §5.2); null when it did not. */
+    private fitRows;
+    /** The height may have changed since the last check. */
+    private fitDirty;
+    /** The frame a check waits for. */
+    private fitFrame;
+    private fitObserver;
+    /** The axes the document asked to scroll along (`scroll`, SPEC §5.1): 1
+     * vertically, 2 horizontally, 3 both; 0, nothing scrolls. */
+    private axes;
+    /** Where the touch drag under way goes, once it has a direction. */
+    private touchRoute;
+    /** The box the wheel gesture under way scrolls, if it went to the
+     * document: the gesture moves no other (`scrollWheel`). */
+    private wheelBox;
+    /** Some element may carry `CLIP`. */
+    private clipping;
+    constructor(name: string, host: SurfaceHost, hostCss: string, scheme: Scheme);
+    setHostCss(css: string, scheme: Scheme): void;
+    private restyle;
+    /** Replaces the whole document (`a=doc`): its head's styles and its body.
+     * `detached` (`d=1`) detaches the surface first; without it, the surface
+     * is the program's again (SPEC §5.1, §5.5). `axes` (`scroll`) are the
+     * axes it scrolls along, 0 for none (§5.3). */
+    setDocument(html: string, detached?: boolean, axes?: number): void;
+    /** A delta (SPEC §6). On a detached surface, the controls it adds are
+     * disabled too, and so is one whose `disabled` it removes. */
+    delta(op: string, target: string | undefined, key: string | undefined, payload: string): void;
+    get detached(): boolean;
+    /** `a=detach`: nothing in the surface reaches the program any more. A
+     * surface that has the keyboard gives it back silently, with no `change`
+     * and no `blur`, and its form controls act disabled. */
+    detach(): void;
+    /** Disables the form controls of a detached surface, as if each had the
+     * `disabled` attribute, or enables those it disabled, and marks its
+     * hyperlinks for the host's stylesheet. The attributes are the host's
+     * own: the document reports the program's (SPEC §16). */
+    private sync;
+    private copyAttributes;
+    /** Rows the content needs at `cols` columns (`r=auto`). */
+    contentRows(cols: number, cellW: number, cellH: number): number;
+    /**
+     * Rows the document needs at `cols` columns: `r=auto`'s, and `fit`'s
+     * (SPEC §5.2). The frame is laid out at the width a placement gives it
+     * and a height of 1px, so the viewport adds nothing, then restored in the
+     * same task: nothing is drawn in between.
+     */
+    private neededRows;
+    /**
+     * In a document that scrolls along one axis only, the elements whose
+     * `overflow` along the other is `auto` or `scroll` are marked (`CLIP`), so
+     * that the host stylesheet clips that axis as `overflow: hidden` does
+     * (SPEC §5.3): no scrollbar, and nothing the user does scrolls it. CSS
+     * cannot select by a computed value, so the addon reads it, with its own
+     * rule off (`UNCLIPPED`), each time the document or its style may have
+     * changed: a document, a delta, the host stylesheet. Style only, no
+     * layout, and only for a document with `scroll` of 1 or 2.
+     */
+    private clip;
+    /**
+     * `f=1` on the placement: from `rows`, the placement's own, the program
+     * hears `fit` whenever the rows the document needs differ from those it
+     * heard last. `null`: the placement did not ask (or is gone).
+     *
+     * What can change the height asks for a check in the next frame drawn:
+     * a document, a delta, a resource (`refresh`), the host stylesheet (cell
+     * size, font), an image, stylesheet or font loading, and, for whatever
+     * else does (the user opening a `<details>`, say), the root's and the
+     * body's boxes changing size. One check per frame, so one `fit` at most.
+     */
+    setFit(rows: number | null): void;
+    /** The document's height may have changed: a check in the next frame
+     * drawn. A surface out of view draws none; it checks once shown. */
+    private refit;
+    private checkFit;
+    /** A resource changed (`a=res`, `a=del`): what names it resolves again. */
+    refresh(names: Set<string>): void;
+    /** The surface is `cols`×`rows` cells, and the box shows `win` of it:
+     *  the document keeps the whole size, offset by the window's corner. */
+    setSize(cols: number, rows: number, cellW: number, cellH: number, win?: Window): void;
+    /** The placement's z (SPEC §5.2): CSS z-index on the box, so overlapping
+     *  boxes stack by it, and by their order in the layer at the same z. */
+    setZ(z: number): void;
+    /** Shows the surface with its top-left corner at (x, y) in the screen's pixels. */
+    show(x: number, y: number): void;
+    /** Out of view (its line left the screen): a drag under way ends
+     * (SPEC §9.1). */
+    hide(): void;
+    /** No placement (hidden, or not placed yet): the document stays, and the
+     *  browser skips its style, layout and paint until it is placed again. */
+    park(): void;
+    destroy(): void;
+    hasKeyboard(): boolean;
+    /** `a=focus`: the surface takes the keyboard, at `target` if given. */
+    focus(target?: string): void;
+    /** `a=blur`, or the keyboard leaving: the edited control commits first. */
+    blur(): void;
+    /** The browser's focus goes from the frame to the terminal. The frame lets
+     * go of it first: Firefox can leave the frame focused otherwise. */
+    private giveBack;
+    private commit;
+    private focusedControl;
+    /** Whether the browser's focus is in this surface's frame. */
+    private frameFocused;
+    /**
+     * A press (SPEC §10.1). On an element that takes focus, the focus that
+     * follows gives the surface the keyboard (`onFocusIn`). On anything else,
+     * or anywhere in a detached surface, it takes nothing: a surface that had
+     * the keyboard gives it back (its control commits, then `blur`), and the
+     * focus the browser gives the frame anyway goes back to the terminal.
+     */
+    private onPress;
+    /**
+     * Once the browser is done with a press (its default action focuses the
+     * frame): an element that takes focus has it, even where the browser does
+     * not focus one on a click (a button on a Mac, say); and focus the
+     * surface does not hold goes back to the terminal. The frame keeps it
+     * until then, so text selection starts as usual.
+     */
+    private settle;
+    /** An element got focus: the surface takes the keyboard if the element is
+     * one that takes focus, and the focus is neither the program's (no echo)
+     * nor a detached surface's. */
+    private onFocusIn;
+    private tabbable;
+    private controlKind;
+    /** Whether the focused element uses the key; if not, the program gets it. */
+    private consumes;
+    private onKey;
+    /**
+     * A key the focused element's keymap gives the program (SPEC §10.2, *Keys
+     * for the program*), outside a text field: it reaches the program before
+     * the element uses it (a select's arrows) and before the document
+     * scrolls with it. The keymap is each `data-keys` from the root down to
+     * the element, with no default, and only its `program` bindings count.
+     * The key is named as in a text field (`fieldKey`).
+     */
+    private programKey;
+    /**
+     * A key the focused element's keymap binds to a scroll action (SPEC
+     * §10.2, *Scrolling keys*), outside a text field, and that the element
+     * does not use. Along an axis the document scrolls, it scrolls the
+     * nearest box from the element outward that can still move that way, as
+     * a gesture goes (§5.3), and never the terminal: where nothing can move,
+     * the key is used and does nothing. Along an axis the document does not
+     * scroll, it goes on as if its keymap did not bind it. The key is named
+     * as in a text field (`fieldKey`).
+     */
+    private scrollActionKey;
+    /** Scrolls `to` as a key does (`KeyScroll`), by Chromium's amounts. */
+    private scrollBox;
+    /** A key the program has, as xterm.js encoded it (`data`; null when it
+     * cannot say, and the key goes through it). Its release follows. */
+    private toProgram;
+    /** An input's type, as the browser has it; the program's for a field
+     * that is `text` while focused (`NO_CARET`). */
+    private inputType;
+    /**
+     * A key in a text field. It is named as the program would read it: from
+     * what xterm.js would send the program for it, in the encoding the
+     * program enabled, read as SPEC §10.4 says. The field's keymap (the
+     * default, then each `data-keys` from the root to the field) says what
+     * the field does with each key; what it does not use is the program's,
+     * sent as xterm.js encoded it.
+     */
+    private fieldKey;
+    /** A field's keymap (SPEC §10.2): the default, then the `data-keys` of
+     * each element from the root down to the field. */
+    private keymapOf;
+    /** Does an action in a field, or types text in it. */
+    private edit;
+    /** An input's or a textarea's value: the action's plan, applied with
+     * the editing commands, so that the browser sends `input` (and `change`
+     * when focus leaves) as for typing. */
+    private editValue;
+    /** Replaces code units `from` to `to` of a field's value with `text`, the
+     * caret after it, as typing does. */
+    private replace;
+    /**
+     * A textarea's rows as it lays them out (SPEC §10.2: a line that wraps is
+     * several rows): a hidden copy of its text, wrapped as it wraps, with
+     * every character in an element of its own, measured where each
+     * position is. The place along a row is a position's x.
+     */
+    private textareaRows;
+    /**
+     * An editing host (`contenteditable`): the actions with the selection's
+     * own moves, a character at a time where they need to see the text, so
+     * that words and lines are SPEC §10.2's, then the editing commands.
+     */
+    private editHost;
+    /** A field that hides its caret (`NO_CARET`) is `text` while focused:
+     * from the press that focuses it, so that the caret lands where the
+     * press does, or from the focus. */
+    private maskField;
+    private unmaskField;
+    /**
+     * A key a browser scrolls with, in a document that scrolls (SPEC §5.3):
+     * it scrolls the innermost box, from the focused element outward (from
+     * the root when none is), that can still move that way. Where none can,
+     * the key goes on to the program, as every key the surface does not use
+     * does (§10.2), unless `overscroll-behavior` stops it. The addon scrolls
+     * the box itself: the browser's own action could be the focused
+     * element's instead (a radio button's arrows, a number field's).
+     */
+    private scrollKey;
+    private forward;
+    /** The release of a key the program had: the program hears it too, if it
+     *  asked the terminal for releases (SPEC §10.3). */
+    private onKeyUp;
+    /**
+     * A press of a mouse's or a pen's primary button on an element with
+     * `drag` in its `data-on` (the nearest, from the pressed one outward, and
+     * only if it has an id) starts a drag. The surface then holds the pointer
+     * until the release: captured by its root element, which no delta
+     * replaces, so every move comes here wherever it is (over the cells,
+     * another surface, or outside the page), and nothing else hears it.
+     */
+    private onDragDown;
+    /** A move during a drag: an event each time its target changes, and
+     * while it has none, each time its cell does. */
+    private onDragMove;
+    /** The release ends the drag, wherever it is. Where it began, it is the
+     * click it would have been without the drag; anywhere else, no click. */
+    private onDragUp;
+    /** The browser took the pointer away before the release. */
+    private lostPointer;
+    /**
+     * Ends a drag under way without a release (SPEC §9.1: its placement went
+     * away, a new document came, or the pointer was lost): `dragend` with no
+     * target, at the last cell the program heard of.
+     */
+    cancelDrag(): void;
+    /** Ends a drag under way, silently (a detached or deleted surface). */
+    private dropDrag;
+    /** The surface's cell under the pointer, from its top left (the frame's
+     * origin), counting on past its edges. */
+    private cellOf;
+    /** The element under the pointer, if it is in the window (SPEC §5.2). */
+    private elementAt;
+    /** A drag's target: the nearest element with an id and `drag` in its
+     * `data-on`, from `el` outward; "" where there is none. */
+    private dragTarget;
+    /**
+     * A press of a mouse's or a pen's primary button with Alt held is the
+     * program's: the addon replays it on the cells beneath, and the surface
+     * hears nothing of it (no press, drag, click, focus or selection; its
+     * mousedown is cancelled). It holds the pointer until the release, as a
+     * drag does, so every move and the release go to the cells, wherever the
+     * pointer is. Whether it is the program's is decided here, at the press:
+     * Alt let go later changes nothing.
+     */
+    private onAltDown;
+    private onAltMove;
+    private onAltUp;
+    /** Ends such a gesture without a release: the frame goes away. */
+    private dropAlt;
+    /** A point of the frame's document in the page. */
+    private toPage;
+    /** `press` (SPEC §9), if the placement asked for it: `t` is the nearest
+     * element with an id. A press on a hyperlink is the terminal's. */
+    private reportPress;
+    /**
+     * The cells an element's border box covers as the user sees it, scrolled
+     * included (SPEC §9: `area`), counted from the surface's top left cell:
+     * whole, where it is clipped or scrolled away. An edge within half a
+     * device pixel of a cell's is on it: layout rounds positions to fractions
+     * of a pixel, and the user sees no less than a device pixel.
+     */
+    private areaOf;
+    private listen;
+    /**
+     * Nothing in a surface scrolls, and a wheel over it is the terminal's
+     * (SPEC §5.3, §9). Wheel events never leave an iframe, so without this
+     * the terminal's scrollback (or, on the alternate screen, the program's
+     * wheel input) would stall under the pointer. Ctrl and the wheel stay the
+     * browser's: its zoom. Where the page scrolls (the `scroll` option), the
+     * wheel is the browser's too: nothing in the frame scrolls, so it scrolls
+     * the page, as over the cells; but over an element it would scroll
+     * instead, the surface scrolls the page itself.
+     */
+    private onWheel;
+    /** Whether a wheel or a touch at target would scroll an element of the
+     * document, overflowing with `overflow: auto` or `scroll`: the browser
+     * gives the gesture to it before the page, and nothing in a surface
+     * scrolls (SPEC §5.3), so the gesture would go nowhere. */
+    private inScroller;
+    /**
+     * A wheel over a document that scrolls (SPEC §5.3). A gesture's first
+     * wheel decides where all of it goes, as a browser latches scrolling to
+     * what it began on: while an element under the pointer can still move
+     * that way, the browser scrolls it; where none can, the gesture goes on
+     * to the terminal, as over the cells beneath (§9), unless
+     * `overscroll-behavior` stops it. A gesture the document took goes no
+     * further when it reaches the end there, as in a browser. Where the page
+     * scrolls (the `scroll` option), the page is the terminal, and the
+     * browser chains to it from the document natively. A wheel the browser
+     * does not let the page cancel is the browser's already.
+     */
+    private scrollWheel;
+    /** Where a gesture that scrolls by dx, dy pixels at `target` goes, by its
+     * main axis (SPEC §5.3). */
+    private gestureRoute;
+    private gestureTarget;
+    /** Whether a box that scrolls can still move along `axis`, `d`'s way. */
+    private canMove;
+    /**
+     * What a scroll along `axis`, `d`'s way, from `from` (an element, or the
+     * root for none) moves in a document that scrolls (SPEC §5.3): the
+     * innermost box, from `from` outward, that the user scrolls along it
+     * (`overflow` `auto` or `scroll`; the root's, unless `hidden` or `clip`),
+     * that overflows there, and that can still move that way. At a box that
+     * cannot, the scroll stops if its `overscroll-behavior` is `contain` or
+     * `none`, and goes on outward otherwise. Past the root, and along an axis
+     * the document did not ask for, it is the terminal's.
+     */
+    private scroller;
+    /** Whatever the browser scrolled along an axis the document did not ask
+     * for (a focused element into view, say) goes back to zero. A text
+     * field's own text follows its caret (SPEC §5.3). */
+    private onScroll;
+    /** An event for the program (SPEC §9); a detached surface sends none (§5.5). */
+    private emit;
+    private linkIn;
+    /** A link's `url` (SPEC §9): its href resolved against the document's
+     * base, or "" under hotty.invalid or when it is no URL. */
+    private urlOf;
+    /** The link's box in the page (the iframe may be offset for a window). */
+    private pageBox;
+    /** A hyperlink (SPEC §9): a link with target="_blank" and a `url`. One
+     * without a url is the program's, as any other link. */
+    private isHyperlink;
+    private readonly hyper;
+    /** A link's click (SPEC §9). A hyperlink is the terminal's, as an OSC 8
+     * one is, and not reported; any other link is the program's: an event,
+     * with or without an id. The host opens nothing itself. */
+    private onLink;
+    /** Other buttons on a link do nothing: no navigation, no new tab. */
+    private onAuxClick;
+    private hovered;
+    /** The pointer onto a hyperlink: the terminal hears it, as it does over
+     * an OSC 8 one. */
+    private onOver;
+    private onOut;
+    private onLeave;
+    private onClick;
+    /** The click of the nearest element on `path` that reports one (SPEC §9). */
+    private reportClick;
+    private onSubmit;
+    private onChange;
+    private onInput;
+}

package/dist/types/touch.d.ts

@@ -0,0 +1,37 @@
+export interface TouchHost {
+    /** Scroll by dx, dy pixels, at a point in the page (a wheel event for the
+     *  terminal). */
+    scroll(dx: number, dy: number, pageX: number, pageY: number): void;
+    /** A tap at a point in the page, for a Touch that owns taps too. */
+    tap?(pageX: number, pageY: number): void;
+    /** The listened-to document's point in the page (an iframe's offset). */
+    toPage(x: number, y: number): [number, number];
+    /** Whether a drag that has just begun, scrolling by dx, dy pixels so far,
+     *  is this Touch's. One it declines is the browser's to its end. Absent:
+     *  every drag is. */
+    claim?(dx: number, dy: number, e: TouchEvent): boolean;
+}
+export declare class Touch {
+    private readonly win;
+    private readonly host;
+    private readonly exclusive;
+    private readonly engage?;
+    private touch;
+    private fling;
+    private readonly off;
+    /**
+     * `exclusive`: every touch here is this Touch's (the cells: xterm.js's own
+     * touch handling, which listens on the document, never sees it). Otherwise
+     * (a surface) a touch is left alone until it moves. `engage`, if given,
+     * says on a touch's start whether it is this Touch's at all: one it
+     * declines is the browser's, from start to end.
+     */
+    constructor(target: EventTarget, win: Window, host: TouchHost, exclusive?: boolean, engage?: ((e: TouchEvent) => boolean) | undefined);
+    dispose(): void;
+    private keep;
+    private start;
+    private move;
+    private end;
+    private startFling;
+    private stopFling;
+}

package/dist/types/version.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The addon's version, as its capabilities report it (SPEC §4): package.json's
+ * without its prerelease part (0.1.0 for 0.1.0-next.1), since SPEC §4's
+ * version is dot-separated numbers only. A unit test keeps the two equal so.
+ * A program tells hosts apart by name
+ * and version: under HOST every version takes `a=delta`. Before the scope, as
+ * `xterm-addon-hotty`, 0.1.0 named no version and took `a=patch`, and 0.2.0
+ * took `a=delta`.
+ */
+export declare const VERSION = "0.1.0";
+/** The host's name in its capabilities (SPEC §4): the package's. */
+export declare const HOST = "@neuroplastio/xterm-addon-hotty";

package/dist/types/wire.d.ts

@@ -0,0 +1,59 @@
+export declare const OSC = 7279;
+/** Largest base64 chunk a host sends (VTE ignores longer strings). */
+export declare const CHUNK = 4096;
+/** Largest reassembled command, in base64 bytes. */
+export declare const MAX_COMMAND: number;
+/** `key=value` pairs separated by `:`, in order. */
+export declare class Control {
+    readonly pairs: [string, string][];
+    constructor(pairs?: [string, string][]);
+    static parse(text: string): Control;
+    get(key: string): string | undefined;
+    set(key: string, value: string): this;
+    delete(key: string): this;
+    /** A continuation chunk carries nothing but `m` and `q`. */
+    onlyChunkKeys(): boolean;
+    encode(): string;
+}
+/**
+ * A control value is printable ASCII (SPEC §3.2): each character it may not
+ * hold (`:`, `;`, `=`, a control character, anything outside ASCII) becomes
+ * one `_`, one per code point.
+ */
+export declare function clean(value: string): string;
+export interface Command {
+    control: Control;
+    payload: Uint8Array;
+}
+export type Decoded = {
+    kind: "command";
+    command: Command;
+} | {
+    kind: "invalid";
+    reason: string;
+} | {
+    kind: "partial";
+};
+/**
+ * Reassembles chunked commands. Decoding is synchronous unless the payload is
+ * zlib (`o=z`), which the browser only inflates asynchronously; the caller
+ * then gets a Promise, and xterm's parser waits for it.
+ */
+export declare class Assembler {
+    private partial;
+    /** Feeds the data of one OSC 7279 sequence. */
+    feed(data: string): Decoded[] | Promise<Decoded[]>;
+}
+export declare function fromBase64(b64: string): Uint8Array;
+export declare function toBase64(bytes: Uint8Array): string;
+/** zlib (RFC 1950), which `DecompressionStream` calls "deflate". */
+export declare function inflate(bytes: Uint8Array): Promise<Uint8Array>;
+export declare function text(bytes: Uint8Array): string;
+/**
+ * Encodes one message for the program: base64, chunked at `CHUNK`, each chunk
+ * a complete OSC terminated by ST. Replies are small, so they are never
+ * compressed (`o=z` is optional in both directions).
+ */
+export declare function encode(control: Control, payload?: Uint8Array | string): string;
+/** Decodes messages the host sent (for tests and for programs written in JS). */
+export declare function decodeAll(stream: string): Promise<Command[]>;

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@neuroplastio/xterm-addon-hotty",
+  "version": "0.1.0-next.1",
+  "description": "HOTTY (HTML Over The TTY) for xterm.js: surfaces rendered by the browser, each in a sandboxed iframe",
+  "type": "module",
+  "license": "Apache-2.0",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/hotty-xterm.js"
+    }
+  },
+  "types": "./dist/types/index.d.ts",
+  "files": [
+    "dist/hotty-xterm.js",
+    "dist/hotty-xterm.js.map",
+    "dist/types"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "node build.mjs",
+    "types": "tsc -p tsconfig.types.json",
+    "typecheck": "tsc --noEmit -p .",
+    "test:unit": "node --test tests/unit/*.test.ts",
+    "test:e2e": "playwright test",
+    "check": "npm run typecheck && npm run build && npm run types && npm run test:unit && npm run test:e2e",
+    "prepare": "npm run build && npm run types"
+  },
+  "peerDependencies": {
+    "@xterm/xterm": "^6.0.0 || ^6.1.0-0"
+  },
+  "devDependencies": {
+    "@playwright/test": "1.63.0",
+    "@types/node": "^26.6.3",
+    "@xterm/addon-fit": "0.12.0-beta.301",
+    "@xterm/xterm": "6.1.0-beta.304",
+    "esbuild": "0.28.2",
+    "typescript": "7.0.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/neuroplastio/xterm-addon-hotty.git"
+  },
+  "homepage": "https://github.com/neuroplastio/xterm-addon-hotty#readme",
+  "bugs": "https://github.com/neuroplastio/xterm-addon-hotty/issues",
+  "keywords": [
+    "xterm.js",
+    "xterm",
+    "addon",
+    "hotty",
+    "terminal",
+    "html"
+  ]
+}