@maxenve/ren-three 0.0.0-stage → 0.1.0

package/src/surface.js

@@ -0,0 +1,204 @@
+// The portable primitives in a three.js scene: a Surface is a ren-canv
+// Document (layout, portable style, text, editing, selection, the native
+// text entry and the accessibility mirror) drawn with a 2D canvas into a
+// three.js texture.
+//
+// - The overlay: primitives placed in the scene itself lie over the canvas,
+//   pixel for pixel, drawn after the scene (a quad in front of an
+//   orthographic camera). The whole canvas is its page.
+// - A panel: primitives placed in a three.js object become a plane in that
+//   object, as large as their content (`pixel` world units per pixel),
+//   facing +z; the texture has `scale` pixels per pixel.
+//
+// Input reaches a surface in its own pixels: the overlay's are the
+// canvas's; a panel's come from the raycast hit's texture coordinate.
+
+import { Document, attach } from 'ren-canv';
+import { Replay2D } from 'ren-canv/backend';
+
+/** The kinds of ren-canv's items that take the focus: an Edit, an Action. */
+const EDIT = 4;
+const ACTION = 5;
+
+/** @typedef {import('./index.js').Renderer} Renderer */
+
+export class Surface extends Document {
+  /**
+   * @param {Renderer} owner @param {boolean} panel
+   */
+  constructor(owner, panel) {
+    const options = owner.options;
+    super(/** @type {any} */ (owner.fonts()), {
+      width: panel ? 1 : owner.width,
+      height: panel ? 1 : owner.height,
+      scale: owner.scale,
+      theme: options.theme,
+      background: 0,
+      aria: options.aria,
+      fit: panel,
+      layout: options.layout,
+    });
+    const kit = owner.kit;
+    this.owner = owner;
+    this.panel = panel;
+    this.replay = new Replay2D(
+      owner.family,
+      owner.picture,
+      () => {
+        this.damage = true;
+        this.full = true;
+        this.present();
+      },
+      owner.monoFamily,
+      // A source that fails: its Images hear `error`; one that left the cache is loaded again.
+      source => this.failed(source),
+      source => this.forgot(source),
+      owner.typefaces,
+    );
+    /** The 2D canvas it draws on, where there is a document. @type {any} */
+    this.image = null;
+    /** @type {any} */
+    this.ctx = null;
+    const doc = owner.canvas?.ownerDocument ?? null;
+    if (doc !== null) {
+      const image = doc.createElement('canvas');
+      const ctx = typeof image.getContext === 'function' ? image.getContext('2d') : null;
+      if (ctx != null) {
+        this.image = image;
+        this.ctx = ctx;
+      }
+    }
+    this.texture = new kit.CanvasTexture(this.image ?? undefined);
+    if (kit.SRGBColorSpace !== undefined) this.texture.colorSpace = kit.SRGBColorSpace;
+    const material = new kit.MeshBasicMaterial({ map: this.texture, transparent: true, toneMapped: false, depthWrite: !panel, side: panel ? kit.DoubleSide : kit.FrontSide });
+    // The overlay fills the orthographic view (-1..1); a panel is a unit
+    // plane scaled to its size.
+    this.mesh = new kit.Mesh(new kit.PlaneGeometry(panel ? 1 : 2, panel ? 1 : 2), material);
+    this.mesh.userData.surface = this;
+    this.mesh.visible = false;
+    this.grow();
+    /** Stops the entry and mirror beside the three.js canvas. @type {(() => void) | null} */
+    this.stop = null;
+    if (owner.canvas != null && doc !== null) this.stop = attach(this, owner.canvas, { input: false, shift: !panel });
+  }
+
+  get kind() {
+    return 'three';
+  }
+
+  get drawing() {
+    return this.ctx !== null;
+  }
+
+  /** Sizes the canvas and the texture to the page, and a panel's plane. */
+  grow() {
+    const image = this.image;
+    if (image !== null) {
+      const w = Math.max(1, Math.round(this.width * this.scale));
+      const h = Math.max(1, Math.round(this.height * this.scale));
+      if (image.width !== w || image.height !== h) {
+        image.width = w;
+        image.height = h;
+        // A texture keeps its size on the GPU: a new size needs a new upload.
+        this.texture.dispose();
+      }
+    }
+    if (this.panel) {
+      const pixel = this.owner.pixel;
+      this.mesh.scale.set(this.width * pixel, this.height * pixel, 1);
+    }
+    this.full = true;
+  }
+
+  sized() {
+    this.grow();
+  }
+
+  /** @param {import('ren-canv/backend').Frame} frame @param {import('ren-canv/backend').Damage | null} damage */
+  draw(frame, damage) {
+    this.replay.run(this.ctx, frame, this.scale, 0, damage, this.shiftX, this.shiftY);
+    this.texture.needsUpdate = true;
+    this.owner.dirty = true;
+    this.owner.request();
+  }
+
+  present() {
+    const painted = super.present();
+    // Shown while it holds anything.
+    const shown = this.root.first !== null || this.overlay.first !== null;
+    if (this.mesh.visible !== shown) {
+      this.mesh.visible = shown;
+      this.owner.dirty = true;
+      this.owner.request();
+    }
+    return painted;
+  }
+
+  /**
+   * Keyboard focus to `item` in this surface (null blurs), as ren-canv's
+   * Document moves it, taking the focus from every other surface of the
+   * renderer first: one surface has the focus and hears the keys, also when
+   * code focuses an item (`focus()`, `focusFirst()`, ren-core's `$focus`)
+   * rather than a press. An item that cannot take the focus (not an Edit
+   * or an Action, or disabled) takes it from no other surface. A blur
+   * handler there that moves the focus (in its own surface or this one)
+   * wins, and `item` hears nothing, as in Chrome.
+   * @param {import('ren-canv').Item | null} item @param {boolean} [ring]
+   */
+  focus(item, ring = false) {
+    if (item !== null && (item.kind === EDIT || item.kind === ACTION) && !item.disabled && !this.closed) {
+      const owner = this.owner;
+      const before = this.current;
+      for (const surface of owner.surfaces) if (surface !== this) surface.focus(null);
+      // A blur handler moved the focus: its move wins.
+      if (this.current !== before) return;
+      for (const surface of owner.surfaces) if (surface !== this && surface.current !== null) return;
+      owner.active = this;
+    }
+    super.focus(item, ring);
+  }
+
+  /**
+   * Whether the item under a point, or an ancestor, hears a drag or a drop:
+   * where the overlay takes files dragged over it though nothing is painted
+   * there (a bare View with `onDrop`), as the DOM's element under them.
+   * @param {number} x @param {number} y
+   */
+  drops(x, y) {
+    return this.dropTarget(x, y) !== null;
+  }
+
+  /**
+   * Where a box of the page shows on screen: the overlay's is the canvas's;
+   * a panel's corners are projected through the camera.
+   * @param {any} canvas @param {number} x @param {number} y @param {number} right @param {number} bottom
+   * @returns {[number, number, number, number]}
+   */
+  screen(canvas, x, y, right, bottom) {
+    if (!this.panel) return super.screen(canvas, x, y, right, bottom);
+    const owner = this.owner;
+    let left = Infinity;
+    let top = Infinity;
+    let r = -Infinity;
+    let b = -Infinity;
+    for (const [px, py] of [[x, y], [right, y], [x, bottom], [right, bottom]]) {
+      const [sx, sy] = owner.project(this, px, py);
+      left = Math.min(left, sx);
+      top = Math.min(top, sy);
+      r = Math.max(r, sx);
+      b = Math.max(b, sy);
+    }
+    return [(canvas.offsetLeft ?? 0) + left, (canvas.offsetTop ?? 0) + top, r - left, b - top];
+  }
+
+  close() {
+    if (this.closed) return;
+    if (this.stop !== null) this.stop();
+    this.stop = null;
+    super.close();
+    this.mesh.parent?.remove(this.mesh);
+    this.mesh.geometry.dispose();
+    this.mesh.material.dispose();
+    this.texture.dispose();
+  }
+}

package/types/index.d.ts

@@ -0,0 +1,473 @@
+import { Item } from 'ren-canv';
+export { loadLayout, loadShaper, remoteLayout } from 'ren-canv';
+import { Surface } from './surface.js';
+export type Host = import('ren-core/host').Host;
+export type Kit = Record<string, any>;
+export type Drawer = {
+    render: (scene: any, camera: any) => void;
+    setSize: (width: number, height: number, style?: boolean) => void;
+    setPixelRatio?: ((ratio: number) => void) | undefined;
+    dispose?: (() => void) | undefined;
+    /**
+     * Loses the WebGL context now (a three.js WebGLRenderer has it).
+     */
+    forceContextLoss?: (() => void) | undefined;
+    /**
+     * its canvas
+     */
+    domElement?: any | undefined;
+};
+export type Options = {
+    /**
+     * The canvas width in CSS pixels; by default the host element's, followed as it resizes (300 without one).
+     */
+    width?: number | undefined;
+    /**
+     * The canvas height in CSS pixels; as width (150 without one).
+     */
+    height?: number | undefined;
+    /**
+     * The device pixel ratio (the window's by default).
+     */
+    scale?: number | undefined;
+    /**
+     * What draws: a WebGLRenderer made on the canvas by default (antialiased), or one given, or a function making it from the canvas.
+     */
+    renderer?: (Drawer | ((canvas: any) => Drawer)) | undefined;
+    /**
+     * The camera: a three.js camera, or `{ fov, near, far, position }` for a PerspectiveCamera (50°, 0.1, 1000, at [0, 0, 5] by default). A `<perspectiveCamera main>` in the view replaces it.
+     */
+    camera?: any | undefined;
+    /**
+     * The scene's background color.
+     */
+    background?: (number | string) | undefined;
+    /**
+     * `frame` (default) renders on animation frames; false renders only when `frame()` is called (tests, a host that drives its own loop).
+     */
+    schedule?: ('frame' | false) | undefined;
+    /**
+     * The bytes of the typeface the primitives are measured and drawn with (needed once a primitive renders).
+     */
+    font?: (ArrayBuffer | Uint8Array) | undefined;
+    /**
+     * The bytes of a monospace typeface: text whose `fontFamily` names monospace is measured and drawn in it (in `font` without it).
+     */
+    mono?: (ArrayBuffer | Uint8Array) | undefined;
+    /**
+     * Typefaces by family name: text whose `fontFamily` names one (the first of its list given here, before a generic family) is measured and drawn in it.
+     */
+    families?: Record<string, ArrayBuffer | Uint8Array> | undefined;
+    /**
+     * Typefaces for the characters a typeface lacks: each such character is measured and drawn in the first of them that has it.
+     */
+    fallback?: (ArrayBuffer | Uint8Array)[] | undefined;
+    /**
+     * The world units of one pixel of a panel (0.01).
+     */
+    pixel?: number | undefined;
+    /**
+     * Theme overrides for the primitives.
+     */
+    theme?: import('ren-core/host').Tokens | undefined;
+    /**
+     * The accessibility mirror of the primitives, as ren-canv's.
+     */
+    aria?: (boolean | 'demand') | undefined;
+    /**
+     * Where the primitives are laid out: this thread by default, or the layout worker `remoteLayout(port)` reaches (ren-canv's).
+     */
+    layout?: import('ren-canv').LayoutPort | undefined;
+    /**
+     * Loads an Image source into something a 2D canvas draws (an HTMLImageElement by default).
+     */
+    image?: import('ren-canv/backend').Picture | undefined;
+};
+/**
+ * The props `element` reads at creation: the Host's `construct` (compiled
+ * templates pass them too), and what a worker serving a ren-three view
+ * passes as `serve`'s `construct`. `of` (`<existing>`) cannot cross
+ * to a worker: an object made elsewhere belongs to the direct runtime.
+ */
+export declare const CONSTRUCT: Set<string>;
+/**
+ * The viewport a primitive's components read (the Host's `viewportOf`):
+ * its panel's size when it is placed in a panel whose primitive sets its
+ * width and height, else the root's (the canvas's). A panel sized by its
+ * content reports the root's: its size follows what it shows, so a view
+ * reading its own size could swing between two layouts. The color scheme
+ * and motion are the root's either way. A component in a panel runs before
+ * its nodes are placed: the source reports the root's until its primitive
+ * is placed, then binds to the panel.
+ */
+declare class Region {
+    owner: Renderer;
+    item: Item;
+    /** @type {Set<(width: number, height: number, flags: number) => void>} */
+    viewers: Set<(width: number, height: number, flags: number) => void>;
+    /** The root's viewport, as it last reported. */
+    root: number[];
+    /** The primitive placed in the panel it is bound to, whose size is the panel's when it sets one. @type {Item | null} */
+    top: Item | null;
+    /** @type {(() => void) | null} */
+    unroot: (() => void) | null;
+    /** @type {(() => void) | null} */
+    unpanel: (() => void) | null;
+    /** @param {Renderer} owner @param {Item} item */
+    constructor(owner: Renderer, item: Item);
+    /** @param {(width: number, height: number, flags: number) => void} report @returns {() => void} */
+    viewport(report: (width: number, height: number, flags: number) => void): () => void;
+    /**
+     * Finds where its primitive is placed: a panel (followed), the overlay
+     * (the root's). False while it is not placed yet.
+     */
+    bind(): boolean;
+    /** What it reports now: the panel's size when its primitive sets one, else the root's. @returns {number[]} */
+    now(): number[];
+    /** Tells every reader. */
+    tell(): void;
+}
+/**
+ * The three.js renderer: the Host `mount` renders into, and the scene,
+ * camera and frame loop it draws.
+ */
+export declare class Renderer {
+    kit: Kit;
+    construct: Set<string>;
+    options: Options;
+    /** The scene, and the container views render into. */
+    scene: any;
+    camera: any;
+    /** @type {Drawer | null} */
+    drawer: Drawer | null;
+    /** The canvas, once open. @type {any} */
+    canvas: any;
+    /** The host element that open marked (`data-ren-root`), unmarked on close. @type {any} */
+    host: any;
+    width: number;
+    height: number;
+    /** Rendered frames. */
+    frames: number;
+    /** True when the scene changed since the last frame. */
+    dirty: boolean;
+    /** Per-frame callbacks (`$animate`): false when one threw and nothing handled it. @type {Set<(frame: Tick) => boolean>} */
+    animations: Set<(frame: Tick) => boolean>;
+    /** The callbacks that had a frame: a callback's first frame has delta 0, whatever time passed before it. @type {WeakSet<(frame: Tick) => boolean>} */
+    animated: WeakSet<(frame: Tick) => boolean>;
+    /** The pending animation frame, or null. @type {any} */
+    pending: any;
+    time: number;
+    opened: boolean;
+    closed: boolean;
+    /** Objects with handlers, for the raycast. */
+    listening: number;
+    /** Objects with a `cursor`: while any, the pointer is raycast for them too. */
+    cursors: number;
+    /** `<gl>`'s settings by property name, applied to the drawer. @type {any} */
+    gl: any;
+    /** Object3D's own fields, which a rebuild from new params leaves alone. @type {Set<string> | null} */
+    base: Set<string> | null;
+    /** The objects under the pointer, nearest first (pointerover/out). @type {any[]} */
+    hovered: any[];
+    /** Removed nodes whose resources go at the next frame unless they come back. @type {any[]} */
+    removed: any[];
+    /** @type {(() => void) | null} */
+    detach: (() => void) | null;
+    /** @type {any} */
+    observer: any;
+    raycaster: any;
+    pointer: any;
+    /** The overlay of the primitives placed in the scene, once there is one. @type {Surface | null} */
+    overlay: Surface | null;
+    /** Its scene and camera, drawn over the scene. @type {any} */
+    overlayScene: any;
+    /** @type {any} */
+    overlayCamera: any;
+    /** Every surface, the overlay first. @type {Set<Surface>} */
+    surfaces: Set<Surface>;
+    /** The root's root-wide listeners (ren-core's `$keys`, `$scrolls` on the scene), heard on every surface; `off` by surface, which goes with it. @type {Set<{ name: string, fn: (event: any) => void, off: Map<Surface, () => void> }>} */
+    rooted: Set<{
+        name: string;
+        fn: (event: any) => void;
+        off: Map<Surface, () => void>;
+    }>;
+    /** The surfaces by their page's root item. @type {WeakMap<Item, Surface>} */
+    pages: WeakMap<Item, Surface>;
+    /** The measure of the primitives' text. @type {import('ren-canv').Fonts | null} */
+    measure: import('ren-canv').Fonts | null;
+    /** The font family the 2D canvas draws them in, and its monospace one (when `mono` is given). */
+    family: string;
+    monoFamily: string | null;
+    /** The font family each typeface slot of the measure draws in (the named typefaces, then the fallbacks; none for slot 0). @type {(string | null)[]} */
+    typefaces: (string | null)[];
+    /** The faces it added to the document's fonts, deleted on close. @type {any[]} */
+    faces: any[];
+    pixel: number;
+    scale: number;
+    /** @type {import('ren-canv/backend').Picture | null} */
+    picture: import('ren-canv/backend').Picture | null;
+    /** The surface keys, copy and select all go to; the one a press grabbed (a drag); the panel under the pointer. @type {Surface | null} */
+    active: Surface | null;
+    /** @type {Surface | null} */
+    grab: Surface | null;
+    /** @type {Surface | null} */
+    over: Surface | null;
+    /** True when the last press went to a surface (its click does not reach the scene). */
+    took: boolean;
+    /** The surface under a drag over the canvas (null: none). @type {Surface | null} */
+    dragged: Surface | null;
+    /** Who follows the viewport (ren-core's `$viewport`), and the window's preference queries while one does. @type {Set<(width: number, height: number, flags: number) => void>} */
+    viewers: Set<(width: number, height: number, flags: number) => void>;
+    /** @type {any[] | null} */
+    queries: any[] | null;
+    tell: () => void;
+    /** Each primitive's viewport source (`viewportOf`), made on first use. @type {WeakMap<Item, Region>} */
+    regions: WeakMap<Item, Region>;
+    /** The sources followed whose primitive is not placed yet: bound as it is. @type {Set<Region>} */
+    unbound: Set<Region>;
+    /** The drawer is this renderer's (made here, or by the `renderer` function for its canvas): closing loses its WebGL context. */
+    owned: boolean | undefined;
+    /** @param {Kit} kit @param {Options} [options] */
+    constructor(kit: Kit, options?: Options);
+    /** The measure of the primitives' text, read from the `font` (and `mono`) option on first use. @returns {import('ren-canv').Fonts} */
+    fonts(): import('ren-canv').Fonts;
+    /** The overlay, made on first use. */
+    makeOverlay(): Surface;
+    /** A new surface: one of this renderer's, hearing the root-wide listeners. @param {Surface} surface */
+    adopt(surface: Surface): void;
+    /** The surface an item belongs to (the overlay for one not placed yet). @param {Item} item */
+    page(item: Item): Surface;
+    get kind(): string;
+    /** @param {string} tag @param {any} props */
+    element(tag: string, props: any): any;
+    /** A text node: an item, drawn inside a primitive and nothing among three.js objects. @param {string} value */
+    text(value: string): Item;
+    /** @param {any} node @param {string} value */
+    content(node: any, value: string): void;
+    /** @param {any} node @param {string} name @param {any} value @param {any} [previous] */
+    set(node: any, name: string, value: any, previous?: any): void;
+    /** Writes a property on a three.js object: a dashed name reaches into it. @param {any} node @param {string} name @param {any} value */
+    apply(node: any, name: string, value: any): void;
+    /**
+     * Rebuilds an object in place from new constructor `params`: the node keeps
+     * its identity (the view, its parent and its handlers hold it). A fresh
+     * object is made and copied in: a scene object takes only what its class
+     * sets beyond Object3D's own fields (not its transform or children);
+     * anything else (a geometry, a material, a curve) takes its whole state,
+     * a geometry's old GPU buffers freed first. The properties the view set
+     * apply again after.
+     * @param {any} node @param {any} params
+     */
+    rebuild(node: any, params: any): void;
+    /** @param {any} node @param {string} name @param {(event: any) => void} handler */
+    listen(node: any, name: string, handler: (event: any) => void): () => void;
+    /** @param {any} parent @param {any} child @param {any} before */
+    insert(parent: any, child: any, before: any): void;
+    /**
+     * Places a primitive linked among three.js objects: in the overlay, in
+     * order among the overlay's other primitives, for the scene; in a panel
+     * of its own for any other object.
+     * @param {any} parent @param {Item} child @param {boolean} moving
+     */
+    place(parent: any, child: Item, moving: boolean): void;
+    /** @param {any} parent @param {any} child */
+    remove(parent: any, child: any): void;
+    /** @param {any} parent @param {any} child @param {boolean} moving */
+    unlink(parent: any, child: any, moving: boolean): void;
+    marker(): Item;
+    /** @param {any} node */
+    parent(node: any): any;
+    /** @param {any} node */
+    next(node: any): any;
+    /** @param {any} value */
+    owns(value: any): boolean;
+    layer(): any;
+    /**
+     * The viewport (ren-core's `$viewport`, `$media`): the canvas's size in
+     * CSS pixels, and the color scheme and motion preferences of the window
+     * it is in (none without one); now, then on each resize or change.
+     * @param {(width: number, height: number, flags: number) => void} report
+     * @returns {() => void}
+     */
+    viewport(report: (width: number, height: number, flags: number) => void): () => void;
+    /**
+     * The viewport of the region `node` is in (ren-core's `$viewport` and
+     * `$media` in a component built there): a primitive's is its panel's
+     * once it is placed in one with a width and height of its own (see
+     * Region), else the root's; null (the root's) for a three.js object.
+     * @param {any} node
+     * @returns {Region | null}
+     */
+    viewportOf(node: any): Region | null;
+    /** Binds the followed sources whose primitive is placed now. */
+    bind(): void;
+    /** The viewport's flags: 1 a dark color scheme, 2 reduced motion (the window's media queries). */
+    flags(): number;
+    /** Follows the window's color scheme and motion preferences, or stops. @param {boolean} on */
+    prefer(on: boolean): void;
+    /** Reports the viewport to its followers. */
+    viewed(): void;
+    present(): void;
+    /**
+     * Prepares an application root: a canvas in its host element (none
+     * without a document), the drawer, pointer events and sizing.
+     * @param {any} element @param {string} id
+     */
+    open(element: any, id: string): any;
+    close(): void;
+    /** Keeps the camera's aspect ratio to the canvas. */
+    aspect(): void;
+    /** Sizes the canvas and the camera. @param {number} width @param {number} height */
+    resize(width: number, height: number): void;
+    /** Follows the host element's size where the options leave it open. @param {any} element */
+    fit(element: any): void;
+    /** Asks for a frame: on the next animation frame, unless one is pending or frames are driven by hand. */
+    request(): void;
+    cancel(): void;
+    /** @param {number} time */
+    tick(time: number): void;
+    /**
+     * One frame: runs the `$animate` callbacks, then renders if anything changed
+     * (an animation always counts as a change).
+     * @param {number} [time] milliseconds
+     */
+    frame(time?: number): boolean;
+    /**
+     * The objects at a canvas point, nearest first: three.js intersections
+     * (`object`, `point`, `distance`, …).
+     * @param {number} x @param {number} y CSS pixels from the canvas's top left
+     * @returns {any[]}
+     */
+    pick(x: number, y: number): any[];
+    /**
+     * Dispatches a pointer event at a canvas point: to the nearest object
+     * with a handler for `type` and then its ancestors, until one stops it.
+     * `pointermove` also sends pointerover and pointerout as the objects
+     * under the pointer change. Returns true when a handler ran.
+     * @param {string} type a ren-core event name (`click`, `pointerdown`, …)
+     * @param {number} x @param {number} y
+     * @param {any} [native] the browser event
+     * @param {Record<string, any>} [more] fields the event also carries (a drop's `files`)
+     */
+    dispatch(type: string, x: number, y: number, native?: any, more?: Record<string, any>): boolean;
+    /** The nearest hit and its ancestors that are part of the view. @param {any[]} hits */
+    chain(hits: any[]): any[];
+    /** @param {any} object @param {string} type @param {any} hit @param {number} x @param {number} y @param {any} native */
+    call(object: any, type: string, hit: any, x: number, y: number, native: any): boolean;
+    /**
+     * The surface and its pixel under a canvas point: the overlay where it
+     * has something there, else the nearest panel the ray hits (from its
+     * texture coordinate). Null when neither. For a `drag` of files, the
+     * overlay also where an item under the point hears drags or drops.
+     * @param {number} x @param {number} y @param {boolean} [drag]
+     * @returns {[Surface, number, number] | null}
+     */
+    surfaceAt(x: number, y: number, drag?: boolean): [Surface, number, number] | null;
+    /**
+     * A canvas point on a panel's plane, in the panel's pixels, whether the
+     * panel is under it or not (a drag that leaves it). Null when the ray
+     * misses the plane.
+     * @param {Surface} surface @param {number} x @param {number} y
+     * @returns {[number, number] | null}
+     */
+    onPanel(surface: Surface, x: number, y: number): [number, number] | null;
+    /**
+     * Where a panel's pixel shows on the canvas, in CSS pixels.
+     * @param {Surface} surface @param {number} px @param {number} py
+     * @returns {[number, number]}
+     */
+    project(surface: Surface, px: number, py: number): [number, number];
+    /**
+     * One input event at a canvas point: to the primitives first (the overlay,
+     * then a panel under the pointer; a drag stays with the surface it
+     * started on), then, when they take nothing, raycast into the scene.
+     * Returns true when anything handled it.
+     * @param {string} type `pointerdown`, `pointermove`, `pointerup`, `pointercancel`, `pointerleave`, `click`, `dblclick`, `contextmenu` or `wheel`
+     * @param {number} x @param {number} y @param {any} [native]
+     */
+    input(type: string, x: number, y: number, native?: any): boolean;
+    /**
+     * A drag over the canvas at a point, carrying `files` files of these MIME
+     * `types` (all a drag tells before its drop): to the surface under it, as
+     * a press (the overlay by point, a panel by the raycast's texture
+     * coordinate), whose items hear it as ren-canv's `dragOver` sends it.
+     * Moving to another surface leaves the first, then enters the second.
+     * Over no surface, the scene's objects under it hear `dragover` through
+     * the raycast. Returns whether a surface or an object took it (the
+     * browser's default is prevented only then).
+     * @param {number} x @param {number} y @param {number} [files] @param {readonly string[]} [types] @param {any} [native]
+     */
+    dragOver(x: number, y: number, files?: number, types?: readonly string[], native?: any): boolean;
+    /** The drag left the canvas (or was cancelled): the surface under it leaves. */
+    dragLeave(): void;
+    /**
+     * Files dropped at a point: on the surface under it (its items hear
+     * `drop` with the files and the point in its pixels), else on the scene's
+     * objects through the raycast (`onDrop` with `files`). A drop ends the
+     * drag without a leave where it lands. Returns whether a surface or an
+     * object took it.
+     * @param {number} x @param {number} y @param {readonly any[]} files @param {any} [native]
+     */
+    dropFiles(x: number, y: number, files: readonly any[], native?: any): boolean;
+    /** Shows a three.js object's cursor on the canvas (null: the page's own). @param {any} object */
+    shown(object: any): void;
+    /**
+     * Takes a new theme for the primitives at once: the overlay and every
+     * panel resolve, lay out and repaint; the scene and all state stay.
+     * @param {import('ren-core/host').Tokens} tokens
+     */
+    setTheme(tokens: import('ren-core/host').Tokens): void;
+    /**
+     * Shows the cursor of the primitives under the pointer on the canvas (their
+     * style's `cursor`); leaves the page's own cursor over the scene.
+     * @param {Surface | null} surface
+     */
+    show(surface: Surface | null): void;
+    /**
+     * Routes a canvas element's pointer, wheel, key and copy events: to the
+     * primitives and the scene (`input`), keys and copy to the surface last
+     * pressed (keys with none to the overlay or the first panel, for the
+     * root's `$keys`; a chord reaches the handlers, as on ren-canv's attach).
+     * Returns the function that stops.
+     * @param {any} canvas
+     */
+    attach(canvas: any): () => void;
+}
+/**
+ * What a `$animate` callback receives each frame. In a worker there is no
+ * renderer, scene or camera: they are null there, and the callback changes
+ * signals instead.
+ */
+export declare class Tick {
+    renderer: Renderer | null;
+    scene: any;
+    camera: any;
+    time: number;
+    delta: number;
+    /** @param {Renderer | null} renderer @param {number} time seconds @param {number} delta seconds since the last frame */
+    constructor(renderer: Renderer | null, time: number, delta: number);
+}
+/**
+ * A three.js renderer for `mount` or an application root's `renderer`.
+ * @param {Kit} kit the three.js namespace
+ * @param {Options} [options]
+ */
+export declare function $three(kit: Kit, options?: Options): Renderer;
+/**
+ * Renders `view()` into a renderer's scene; returns the dispose function.
+ * @param {() => any} view
+ * @param {Renderer} target
+ * @param {import('ren-core/host').Options} [options]
+ * @returns {() => void}
+ */
+export declare function render(view: () => any, target: Renderer, options?: import('ren-core/host').Options): () => void;
+/**
+ * Runs `fn` before every frame while the calling component lives (its
+ * owner's cleanup stops it). Rendered by ren-three, it runs in the
+ * renderer's frame loop, which draws every animation frame while any runs.
+ * Anywhere else (a worker serving the view), it runs on that thread's own
+ * frames (`requestAnimationFrame` where the thread has it, 16 ms timers
+ * otherwise), with a Tick whose renderer, scene and camera are null.
+ * @param {(frame: Tick) => void} fn
+ */
+export declare function $animate(fn: (frame: Tick) => void): void;