@aethervtt/shard-ui 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Dias
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# @aethervtt/shard-ui
+
+Part of [Shard](https://github.com/aethervtt/shard), a WebGPU-first 2D/3D game engine in TypeScript. See the repository for documentation.

package/dist/components.d.ts

@@ -0,0 +1,144 @@
+import { type AssetRef, type Entity, type Infer } from '@aethervtt/shard-core';
+export declare const UI_DISPLAYS: readonly ['flex', 'none'];
+export declare const UI_POSITIONS: readonly ['relative', 'absolute'];
+export declare const UI_DIRECTIONS: readonly ['row', 'column', 'row-reverse', 'column-reverse'];
+export declare const UI_JUSTIFY: readonly ['start', 'center', 'end', 'space-between', 'space-around', 'space-evenly'];
+export declare const UI_ALIGN: readonly ['stretch', 'start', 'center', 'end'];
+export declare const UI_ALIGN_SELF: readonly ['auto', 'stretch', 'start', 'center', 'end'];
+export declare const UI_OVERFLOW: readonly ['visible', 'clip', 'scroll'];
+export declare const UI_TEXT_ALIGN: readonly ['start', 'center', 'end'];
+export declare const UI_FIT: readonly ['fill', 'contain', 'cover'];
+export declare const UI_SCALES: readonly ['none', 'fit-height', 'fit-width'];
+export declare const UI_STATES: readonly ['none', 'hovered', 'pressed', 'disabled'];
+export declare const UI_ANCHOR_STATES: readonly ['none', 'on-screen', 'clamped', 'hidden'];
+/** Computed by layout: the node's rect and what clips it. Managed by the UI plugin. */
+export declare const UiLayout: import("@aethervtt/shard-core").ComponentDef<{
+    readonly x: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly y: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly width: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly height: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly clip: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec4, "f32">;
+    readonly content: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec2, "f32">;
+    readonly scale: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly angle: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly visible: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    readonly anchor: import("@aethervtt/shard-core").FieldType<"clamped" | "hidden" | "none" | "on-screen", "u8">;
+    readonly distance: import("@aethervtt/shard-core").FieldType<number, "f32">;
+}>;
+export declare const UiNode: import("@aethervtt/shard-core").ComponentDef<{
+    readonly display: import("@aethervtt/shard-core").FieldType<"flex" | "none", "u8">;
+    readonly position: import("@aethervtt/shard-core").FieldType<"absolute" | "relative", "u8">;
+    readonly direction: import("@aethervtt/shard-core").FieldType<"column" | "column-reverse" | "row" | "row-reverse", "u8">;
+    readonly wrap: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    readonly justify: import("@aethervtt/shard-core").FieldType<"center" | "end" | "space-around" | "space-between" | "space-evenly" | "start", "u8">;
+    readonly alignItems: import("@aethervtt/shard-core").FieldType<"center" | "end" | "start" | "stretch", "u8">;
+    readonly alignSelf: import("@aethervtt/shard-core").FieldType<"auto" | "center" | "end" | "start" | "stretch", "u8">;
+    readonly width: import("@aethervtt/shard-core").FieldType<import("./length.js").UiLength, "f32">;
+    readonly height: import("@aethervtt/shard-core").FieldType<import("./length.js").UiLength, "f32">;
+    readonly minWidth: import("@aethervtt/shard-core").FieldType<import("./length.js").UiLength, "f32">;
+    readonly maxWidth: import("@aethervtt/shard-core").FieldType<import("./length.js").UiLength, "f32">;
+    readonly minHeight: import("@aethervtt/shard-core").FieldType<import("./length.js").UiLength, "f32">;
+    readonly maxHeight: import("@aethervtt/shard-core").FieldType<import("./length.js").UiLength, "f32">;
+    readonly left: import("@aethervtt/shard-core").FieldType<import("./length.js").UiLength, "f32">;
+    readonly top: import("@aethervtt/shard-core").FieldType<import("./length.js").UiLength, "f32">;
+    readonly right: import("@aethervtt/shard-core").FieldType<import("./length.js").UiLength, "f32">;
+    readonly bottom: import("@aethervtt/shard-core").FieldType<import("./length.js").UiLength, "f32">;
+    readonly padding: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec4, "f32">;
+    readonly margin: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec4, "f32">;
+    readonly gap: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec2, "f32">;
+    readonly grow: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly shrink: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly basis: import("@aethervtt/shard-core").FieldType<import("./length.js").UiLength, "f32">;
+    readonly order: import("@aethervtt/shard-core").FieldType<number, "i16">;
+    readonly zIndex: import("@aethervtt/shard-core").FieldType<number, "i16">;
+    readonly overflow: import("@aethervtt/shard-core").FieldType<"clip" | "scroll" | "visible", "u8">;
+    readonly scroll: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec2, "f32">;
+    readonly style: import("@aethervtt/shard-core").FieldType<string, "object">;
+}>;
+export declare const UiRoot: import("@aethervtt/shard-core").ComponentDef<{
+    readonly scale: import("@aethervtt/shard-core").FieldType<"fit-height" | "fit-width" | "none", "u8">;
+    readonly referenceSize: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec2, "f32">;
+    readonly camera: import("@aethervtt/shard-core").FieldType<number | null, "f64">;
+    readonly theme: import("@aethervtt/shard-core").FieldType<AssetRef<"UiTheme"> | null, "object">;
+    readonly order: import("@aethervtt/shard-core").FieldType<number, "i16">;
+}>;
+export declare const UiStyle: import("@aethervtt/shard-core").ComponentDef<{
+    readonly background: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Color, "f32">;
+    readonly borderColor: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Color, "f32">;
+    readonly borderWidth: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly radius: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec4, "f32">;
+    readonly opacity: import("@aethervtt/shard-core").FieldType<number, "f32">;
+}>;
+export declare const UiText: import("@aethervtt/shard-core").ComponentDef<{
+    readonly text: import("@aethervtt/shard-core").FieldType<string, "object">;
+    readonly key: import("@aethervtt/shard-core").FieldType<string, "object">;
+    readonly params: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").JsonValue, "object">;
+    readonly size: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly color: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Color, "f32">;
+    readonly font: import("@aethervtt/shard-core").FieldType<AssetRef<"Font"> | null, "object">;
+    readonly align: import("@aethervtt/shard-core").FieldType<"center" | "end" | "start", "u8">;
+    readonly wrap: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    readonly lineHeight: import("@aethervtt/shard-core").FieldType<number, "f32">;
+}>;
+export declare const UiImage: import("@aethervtt/shard-core").ComponentDef<{
+    readonly texture: import("@aethervtt/shard-core").FieldType<AssetRef<"Texture"> | null, "object">;
+    readonly atlas: import("@aethervtt/shard-core").FieldType<AssetRef<"TextureAtlas"> | null, "object">;
+    readonly region: import("@aethervtt/shard-core").FieldType<string, "object">;
+    readonly slice: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec4, "f32">;
+    readonly tint: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Color, "f32">;
+    readonly fit: import("@aethervtt/shard-core").FieldType<"contain" | "cover" | "fill", "u8">;
+}>;
+export declare const UiInteraction: import("@aethervtt/shard-core").ComponentDef<{
+    readonly state: import("@aethervtt/shard-core").FieldType<"disabled" | "hovered" | "none" | "pressed", "u8">;
+    readonly focused: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+}>;
+export declare const UiButton: import("@aethervtt/shard-core").ComponentDef<{
+    readonly disabled: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+}>;
+export declare const UiToggle: import("@aethervtt/shard-core").ComponentDef<{
+    readonly on: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    readonly disabled: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+}>;
+export declare const UiSlider: import("@aethervtt/shard-core").ComponentDef<{
+    readonly value: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly min: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly max: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly step: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly fill: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Color, "f32">;
+    readonly disabled: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+}>;
+export declare const UiTextInput: import("@aethervtt/shard-core").ComponentDef<{
+    readonly value: import("@aethervtt/shard-core").FieldType<string, "object">;
+    readonly placeholder: import("@aethervtt/shard-core").FieldType<string, "object">;
+    readonly maxLength: import("@aethervtt/shard-core").FieldType<number, "u16">;
+    readonly disabled: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+}>;
+export declare const UiAnchor: import("@aethervtt/shard-core").ComponentDef<{
+    readonly target: import("@aethervtt/shard-core").FieldType<number | null, "f64">;
+    readonly offset: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec3, "f32">;
+    readonly screenOffset: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec2, "f32">;
+    readonly pivot: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec2, "f32">;
+    readonly clamp: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    readonly margin: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly hideBehind: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    readonly scaleDistance: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly minScale: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly maxScale: import("@aethervtt/shard-core").FieldType<number, "f32">;
+}>;
+export declare const UiAnchorArrow: import("@aethervtt/shard-core").TagDef;
+export interface UiEntityEvent {
+    entity: Entity;
+}
+export declare const UiClick: import("@aethervtt/shard-core").EventDef<UiEntityEvent>;
+export declare const UiChanged: import("@aethervtt/shard-core").EventDef<UiEntityEvent>;
+export declare const UiHover: import("@aethervtt/shard-core").EventDef<UiEntityEvent & {
+    hovered: boolean;
+}>;
+export interface UiDefaultsValue {
+    /** Font for text without one (and no theme font). */
+    font: AssetRef<'Font'> | null;
+}
+export declare const UiDefaults: import("@aethervtt/shard-core").ResourceDef<UiDefaultsValue>;
+export type UiNodeValue = Infer<typeof UiNode>;
+export type UiStyleValue = Infer<typeof UiStyle>;
+export type UiTextValue = Infer<typeof UiText>;

package/dist/components.js

@@ -0,0 +1,355 @@
+import {
+  defineComponent,
+  defineEvent,
+  defineResource,
+  defineTag,
+  t
+} from "@aethervtt/shard-core";
+import { uiLength } from "./length.js";
+const UI_DISPLAYS = ["flex", "none"];
+const UI_POSITIONS = ["relative", "absolute"];
+const UI_DIRECTIONS = ["row", "column", "row-reverse", "column-reverse"];
+const UI_JUSTIFY = [
+  "start",
+  "center",
+  "end",
+  "space-between",
+  "space-around",
+  "space-evenly"
+];
+const UI_ALIGN = ["stretch", "start", "center", "end"];
+const UI_ALIGN_SELF = ["auto", "stretch", "start", "center", "end"];
+const UI_OVERFLOW = ["visible", "clip", "scroll"];
+const UI_TEXT_ALIGN = ["start", "center", "end"];
+const UI_FIT = ["fill", "contain", "cover"];
+const UI_SCALES = ["none", "fit-height", "fit-width"];
+const UI_STATES = ["none", "hovered", "pressed", "disabled"];
+const UI_ANCHOR_STATES = ["none", "on-screen", "clamped", "hidden"];
+const UiLayout = defineComponent(
+  "ui/UiLayout",
+  {
+    x: t.f32({ readonly: true, description: "Left edge, in the root's pixels." }),
+    y: t.f32({ readonly: true, description: "Top edge, in the root's pixels." }),
+    width: t.f32({ readonly: true, description: "Border-box width." }),
+    height: t.f32({ readonly: true, description: "Border-box height." }),
+    clip: t.vec4({
+      readonly: true,
+      description: "The visible region (x, y, width, height) after ancestors that clip or scroll; zero size when nothing shows."
+    }),
+    content: t.vec2({
+      readonly: true,
+      description: "Size of what the children cover: the scrollable extent of a scroll node."
+    }),
+    scale: t.f32({
+      default: 1,
+      readonly: true,
+      description: "Draw scale from a scaling anchor (1: none)."
+    }),
+    angle: t.f32({
+      readonly: true,
+      unit: "rad",
+      description: "UiAnchorArrow: rotation toward an off-screen target."
+    }),
+    visible: t.bool({
+      readonly: true,
+      description: "Drawn and hit: false for display none, hidden anchors, and nodes outside a root."
+    }),
+    anchor: t.enum(UI_ANCHOR_STATES, {
+      readonly: true,
+      description: "UiAnchor nodes: on-screen, clamped to an edge, or hidden (behind the camera)."
+    }),
+    distance: t.f32({
+      readonly: true,
+      unit: "m",
+      description: "UiAnchor nodes: the target's distance from the camera."
+    })
+  },
+  {
+    description: "A UI node's computed rect (in pixels of its root's reference size), clip, and anchor state. Written by layout; read it to check where things are.",
+    serialize: false
+  }
+);
+const UiNode = defineComponent(
+  "ui/UiNode",
+  {
+    display: t.enum(UI_DISPLAYS, { description: "none: not laid out, drawn, or hit." }),
+    position: t.enum(UI_POSITIONS, {
+      description: "relative: in the parent's flow (left/top/right/bottom nudge it). absolute: out of flow, placed by left/top/right/bottom in the parent's padding box."
+    }),
+    direction: t.enum(UI_DIRECTIONS, { description: "Main axis children flow along." }),
+    wrap: t.bool({ description: "Wrap children onto new lines when they don't fit." }),
+    justify: t.enum(UI_JUSTIFY, { description: "Distribution of children along the main axis." }),
+    alignItems: t.enum(UI_ALIGN, { description: "Placement of children on the cross axis." }),
+    alignSelf: t.enum(UI_ALIGN_SELF, { description: "Overrides the parent's alignItems." }),
+    width: uiLength({ description: 'Border-box width: pixels, "50%" of the parent, or "auto".' }),
+    height: uiLength({ description: "Border-box height." }),
+    minWidth: uiLength({ description: 'Lower bound on width ("auto": none).' }),
+    maxWidth: uiLength({ description: 'Upper bound on width ("auto": none).' }),
+    minHeight: uiLength({ description: "Lower bound on height." }),
+    maxHeight: uiLength({ description: "Upper bound on height." }),
+    left: uiLength({ description: "Offset from the left (absolute: of the parent)." }),
+    top: uiLength({ description: "Offset from the top." }),
+    right: uiLength({ description: "Offset from the right." }),
+    bottom: uiLength({ description: "Offset from the bottom." }),
+    padding: t.vec4({ min: 0, unit: "px", description: "Inside space: top, right, bottom, left." }),
+    margin: t.vec4({ unit: "px", description: "Outside space: top, right, bottom, left." }),
+    gap: t.vec2({
+      min: 0,
+      unit: "px",
+      description: "Space between children: horizontal, vertical."
+    }),
+    grow: t.f32({ min: 0, description: "Share of free main-axis space this node takes." }),
+    shrink: t.f32({ default: 1, min: 0, description: "Share of overflow this node gives back." }),
+    basis: uiLength({ description: 'Main size before growing and shrinking ("auto": its size).' }),
+    order: t.i16({ description: "Sorts siblings (stable): lower first." }),
+    zIndex: t.i16({
+      description: "Draw and hit order among siblings: higher draws over, and gets clicks first."
+    }),
+    overflow: t.enum(UI_OVERFLOW, {
+      description: "visible: children may spill out. clip: they're cut at the padding box. scroll: cut, and the wheel scrolls it."
+    }),
+    scroll: t.vec2({ min: 0, unit: "px", description: "Scroll offset (overflow scroll)." }),
+    style: t.string({
+      description: `A style in the root's theme ("panel", "button"); fields set here win.`
+    })
+  },
+  {
+    description: "A UI box laid out by flexbox under a UiRoot: sizes, flex, spacing, positioning, clipping. Children are ChildOf entities, in order.",
+    requires: [UiLayout]
+  }
+);
+const UiRoot = defineComponent(
+  "ui/UiRoot",
+  {
+    scale: t.enum(UI_SCALES, {
+      description: "none: one UI pixel per screen pixel. fit-height / fit-width: scale so referenceSize fills the screen that way."
+    }),
+    referenceSize: t.vec2({
+      default: [1920, 1080],
+      min: 1,
+      unit: "px",
+      description: "The size the UI is authored at (and its size headless)."
+    }),
+    camera: t.entity({
+      description: "The camera whose view it draws over and anchors from (null: the first)."
+    }),
+    theme: t.handle("UiTheme", { description: "Styles its nodes name (*.theme.json)." }),
+    order: t.i16({ description: "Draw order among roots: higher draws over." })
+  },
+  {
+    description: "The top of a UI tree: fills the screen and lays out its UiNode children.",
+    requires: [UiNode]
+  }
+);
+const UiStyle = defineComponent(
+  "ui/UiStyle",
+  {
+    background: t.color({ default: [0, 0, 0, 0], description: "Fill color (linear)." }),
+    borderColor: t.color({ default: [0, 0, 0, 0], description: "Border color (linear)." }),
+    borderWidth: t.f32({ min: 0, unit: "px", description: "Border thickness, inside the box." }),
+    radius: t.vec4({
+      min: 0,
+      unit: "px",
+      description: "Corner radii: top left, top right, bottom right, bottom left."
+    }),
+    opacity: t.f32({
+      default: 1,
+      min: 0,
+      max: 1,
+      description: "Multiplies the node and its children."
+    })
+  },
+  {
+    description: "How a node looks: background, border, rounded corners, opacity. Fields at their default take the theme style.",
+    requires: [UiNode]
+  }
+);
+const UiText = defineComponent(
+  "ui/UiText",
+  {
+    text: t.string({ description: 'The text. "\\n" breaks a line.' }),
+    key: t.string({
+      description: "Localization key in the locales/*.strings.json tables: the node shows the current locale's string, and follows locale switches. text shows until it resolves."
+    }),
+    params: t.json({
+      default: {},
+      description: `Values for the key's {name} placeholders: { "amount": 42 }. Numbers format for the locale; "n" (or "count") picks the plural form.`
+    }),
+    size: t.f32({ default: 16, min: 0, unit: "px", description: "Height of one em." }),
+    color: t.color({ default: [1, 1, 1, 1], description: "Text color (linear)." }),
+    font: t.handle("Font", { description: "Font (null: the theme's, then UiDefaults.font)." }),
+    align: t.enum(UI_TEXT_ALIGN, { description: "Line alignment in the node." }),
+    wrap: t.bool({ default: true, description: "Wrap at the node width." }),
+    lineHeight: t.f32({
+      default: 1.2,
+      min: 0.1,
+      description: "Distance between baselines, as a multiple of the size."
+    })
+  },
+  {
+    description: "A node's text (MSDF): its size sets the node's size unless width/height do.",
+    requires: [UiNode]
+  }
+);
+const UiImage = defineComponent(
+  "ui/UiImage",
+  {
+    texture: t.handle("Texture", {
+      description: "The image (ignored when atlas and region are set)."
+    }),
+    atlas: t.handle("TextureAtlas", { description: "An atlas to draw a region of." }),
+    region: t.string({ description: "Atlas region name." }),
+    slice: t.vec4({
+      min: 0,
+      unit: "px",
+      description: "Nine-slice borders (top, right, bottom, left) in image pixels: corners keep their size, edges and middle stretch. Zero: no slicing."
+    }),
+    tint: t.color({ default: [1, 1, 1, 1], description: "Multiplied in (linear)." }),
+    fit: t.enum(UI_FIT, {
+      description: "fill: stretch to the box. contain: fit inside, keeping aspect. cover: fill, cropping."
+    })
+  },
+  {
+    description: "An image in a node: a texture or atlas region, nine-sliced or fitted. Its pixel size is the node's size unless width/height set it.",
+    requires: [UiNode]
+  }
+);
+const UiInteraction = defineComponent(
+  "ui/UiInteraction",
+  {
+    state: t.enum(UI_STATES, { readonly: true, description: "Pointer state." }),
+    focused: t.bool({ readonly: true, description: "Has keyboard and gamepad focus." })
+  },
+  {
+    description: "Hover, press, and focus of an interactive node. Written by the UI plugin.",
+    serialize: false
+  }
+);
+const UiButton = defineComponent(
+  "ui/UiButton",
+  { disabled: t.bool({ description: "Ignores the pointer and focus; state is disabled." }) },
+  {
+    description: "Clickable: sends ui/UiClick on a click, Enter, Space, or the gamepad south button.",
+    requires: [UiNode, UiInteraction]
+  }
+);
+const UiToggle = defineComponent(
+  "ui/UiToggle",
+  {
+    on: t.bool({ description: "Checked." }),
+    disabled: t.bool({ description: "Ignores input." })
+  },
+  {
+    description: "A checkbox or switch: a click flips on and sends ui/UiChanged (and ui/UiClick).",
+    requires: [UiNode, UiInteraction]
+  }
+);
+const UiSlider = defineComponent(
+  "ui/UiSlider",
+  {
+    value: t.f32({ description: "Current value, min to max." }),
+    min: t.f32({ description: "Value at the left edge." }),
+    max: t.f32({ default: 1, description: "Value at the right edge." }),
+    step: t.f32({ min: 0, description: "Snap to multiples of this from min (0: continuous)." }),
+    fill: t.color({
+      default: [0.25, 0.55, 1, 1],
+      description: "Color of the filled part (min to value), drawn inside the node's padding."
+    }),
+    disabled: t.bool({ description: "Ignores input." })
+  },
+  {
+    description: "Dragging sets value from the pointer; left and right step it while focused. Sends ui/UiChanged.",
+    requires: [UiNode, UiInteraction]
+  }
+);
+const UiTextInput = defineComponent(
+  "ui/UiTextInput",
+  {
+    value: t.string({ description: "The text typed." }),
+    placeholder: t.string({ description: "Shown dimmed while value is empty." }),
+    maxLength: t.u16({ description: "Most characters (0: no limit)." }),
+    disabled: t.bool({ description: "Ignores input." })
+  },
+  {
+    description: "A text field: clicking focuses it, typing edits value (sends ui/UiChanged), Enter or Escape blurs. Shows through the node's UiText.",
+    requires: [UiNode, UiInteraction]
+  }
+);
+const UiAnchor = defineComponent(
+  "ui/UiAnchor",
+  {
+    target: t.entity({ description: "The world entity to follow." }),
+    offset: t.vec3({ unit: "m", description: "World offset from the target's position." }),
+    screenOffset: t.vec2({ unit: "px", description: "Offset on screen after projecting, y down." }),
+    pivot: t.vec2({
+      default: [0.5, 0.5],
+      description: "Point of the node on the target: [0, 0] top left, [0.5, 1] bottom center."
+    }),
+    clamp: t.bool({ description: "Keep it on screen when the target is off it (or behind)." }),
+    margin: t.f32({
+      default: 16,
+      min: 0,
+      unit: "px",
+      description: "Distance kept from the edge when clamped."
+    }),
+    hideBehind: t.bool({ description: "Hide while the target is behind the camera." }),
+    scaleDistance: t.f32({
+      min: 0,
+      unit: "m",
+      description: "Scale by distance: 1 at this distance, larger nearer (0: never scale)."
+    }),
+    minScale: t.f32({ default: 0.5, min: 0, description: "Smallest distance scale." }),
+    maxScale: t.f32({ default: 1.5, min: 0, description: "Largest distance scale." })
+  },
+  {
+    description: "Places a node over a world entity's screen position (planet markers): positioned absolute, clamped to the edges, hidden behind the camera, scaled by distance. A UiAnchorArrow child points at an off-screen target.",
+    requires: [UiNode]
+  }
+);
+const UiAnchorArrow = defineTag("ui/UiAnchorArrow", {
+  description: "A child of a UiAnchor node shown only while the anchor is clamped: placed just outside the node's edge toward the target and rotated to point at it (draw it pointing right)."
+});
+const UiClick = defineEvent("ui/UiClick", {
+  description: "A button (or toggle) was clicked, activated from focus, or clicked by ui.click."
+});
+const UiChanged = defineEvent("ui/UiChanged", {
+  description: "A toggle, slider, or text input's value changed from input."
+});
+const UiHover = defineEvent("ui/UiHover", {
+  description: "The pointer entered (hovered true) or left an interactive node."
+});
+const UiDefaults = defineResource("ui/UiDefaults", {
+  description: "Fallbacks: the font UI text uses when neither it nor its theme names one.",
+  init: () => ({ font: null })
+});
+export {
+  UI_ALIGN,
+  UI_ALIGN_SELF,
+  UI_ANCHOR_STATES,
+  UI_DIRECTIONS,
+  UI_DISPLAYS,
+  UI_FIT,
+  UI_JUSTIFY,
+  UI_OVERFLOW,
+  UI_POSITIONS,
+  UI_SCALES,
+  UI_STATES,
+  UI_TEXT_ALIGN,
+  UiAnchor,
+  UiAnchorArrow,
+  UiButton,
+  UiChanged,
+  UiClick,
+  UiDefaults,
+  UiHover,
+  UiImage,
+  UiInteraction,
+  UiLayout,
+  UiNode,
+  UiRoot,
+  UiSlider,
+  UiStyle,
+  UiText,
+  UiTextInput,
+  UiToggle
+};

package/dist/flex.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The flexbox subset UI lays out with, over a flat node array (no ECS, no allocation per layout
+ * once the arrays are big enough). Sizes are border-box pixels; borders draw inside the box and
+ * take no space. Follows CSS Flexbox §9 for the fields UiNode has: basis, grow and shrink with
+ * min/max freezing, wrap with stretched lines, justify, align-items/align-self, absolute children
+ * (static position from justify and align), relative offsets, percentages of the parent's inner
+ * size, and order. Differences from a browser: an item's automatic minimum size is its min-content
+ * size only for text and image leaves (containers may shrink to their padding), and there's no
+ * align-content (lines stretch, as CSS's default does).
+ */
+/** Length slots per node, two floats each (value, unit). */
+export declare const L: {
+    readonly width: 0;
+    readonly height: 1;
+    readonly minWidth: 2;
+    readonly maxWidth: 3;
+    readonly minHeight: 4;
+    readonly maxHeight: 5;
+    readonly left: 6;
+    readonly top: 7;
+    readonly right: 8;
+    readonly bottom: 9;
+    readonly basis: 10;
+};
+export declare const LENGTHS = 11;
+export declare const Dir: {
+    readonly Row: 0;
+    readonly Column: 1;
+    readonly RowReverse: 2;
+    readonly ColumnReverse: 3;
+};
+export declare const Justify: {
+    readonly Start: 0;
+    readonly Center: 1;
+    readonly End: 2;
+    readonly SpaceBetween: 3;
+    readonly SpaceAround: 4;
+    readonly SpaceEvenly: 5;
+};
+/** alignItems values; alignSelf is these plus 1 (0 = auto). */
+export declare const Align: {
+    readonly Stretch: 0;
+    readonly Start: 1;
+    readonly Center: 2;
+    readonly End: 3;
+};
+/** Content size of a leaf (text, image): writes width and height (content box) into `out`. */
+export type Measure = (node: number, maxWidth: number, out: Float32Array) => void;
+/**
+ * Nodes and their layout inputs and outputs, as typed arrays indexed by node. Node 0 is laid out
+ * at the size given to `layout`; each node's children are a linked list (firstChild, nextSibling)
+ * in flow order.
+ */
+export declare class FlexTree {
+    count: number;
+    firstChild: Int32Array<ArrayBuffer>;
+    nextSibling: Int32Array<ArrayBuffer>;
+    /** 1: display none (skipped with its subtree). */
+    hidden: Uint8Array<ArrayBuffer>;
+    absolute: Uint8Array<ArrayBuffer>;
+    direction: Uint8Array<ArrayBuffer>;
+    wrap: Uint8Array<ArrayBuffer>;
+    justify: Uint8Array<ArrayBuffer>;
+    alignItems: Uint8Array<ArrayBuffer>;
+    alignSelf: Uint8Array<ArrayBuffer>;
+    /** Per node, LENGTHS × (value, unit). */
+    lengths: Float32Array<ArrayBuffer>;
+    /** top, right, bottom, left. */
+    padding: Float32Array<ArrayBuffer>;
+    margin: Float32Array<ArrayBuffer>;
+    /** horizontal, vertical. */
+    gap: Float32Array<ArrayBuffer>;
+    flexGrow: Float32Array<ArrayBuffer>;
+    flexShrink: Float32Array<ArrayBuffer>;
+    /** 1: a leaf measured by the Measure callback (text, image). */
+    measured: Uint8Array<ArrayBuffer>;
+    /** 1: positioned by `anchorX/Y` (root coordinates) minus pivot × size, ignoring its parent. */
+    anchored: Uint8Array<ArrayBuffer>;
+    anchorX: Float32Array<ArrayBuffer>;
+    anchorY: Float32Array<ArrayBuffer>;
+    pivotX: Float32Array<ArrayBuffer>;
+    pivotY: Float32Array<ArrayBuffer>;
+    /** Output: position relative to the parent's border box, and border-box size. */
+    x: Float32Array<ArrayBuffer>;
+    y: Float32Array<ArrayBuffer>;
+    w: Float32Array<ArrayBuffer>;
+    h: Float32Array<ArrayBuffer>;
+    /** Measure-only results, and the inputs they were measured for. */
+    mw: Float32Array<ArrayBuffer>;
+    mh: Float32Array<ArrayBuffer>;
+    cache: Float32Array<ArrayBuffer>;
+    cacheValid: Uint8Array<ArrayBuffer>;
+    /** Layout calls this pass (measure and perform), for describe. */
+    calls: number;
+    reserve(n: number): void;
+    /** Clears to `n` nodes with default inputs (row, stretch, auto sizes, shrink 1). */
+    reset(n: number): void;
+    /** Sets a length slot: unit 0 px, 1 percent, 2 auto. */
+    setLength(node: number, slot: number, value: number, unit: number): void;
+    /** Appends `child` to `parent`'s children (after its last). */
+    append(parent: number, child: number, last: Int32Array): void;
+}
+/**
+ * Lays out the tree from node 0 at a given size: every node's x, y (relative to its parent),
+ * w, h. `measure` sizes text and image leaves.
+ */
+export declare function layoutTree(t: FlexTree, width: number, height: number, measure: Measure): void;