@moku-labs/game 0.0.1 → 0.0.2

package/dist/types-DD-QrG_z.d.mts

@@ -0,0 +1,588 @@
+import { k as Api, lt as Require, t as Api$1 } from "./types-JNc_UQBo.mjs";
+import { D as AnyComponent, N as Entity, t as Api$3, u as Api$2 } from "./types-BxkNNYul.mjs";
+import { o as Events, t as Api$4 } from "./types-DWILGrPn.mjs";
+import { F as Events$1, H as InputApi, I as I18nApi, L as Message, c as UiNode, i as Finding, n as ElementChange, o as JsxState, r as ElementMotion, v as StylesState } from "./types-yg_ywtT-.mjs";
+import { Log } from "@moku-labs/common/browser";
+import { PluginCtx } from "@moku-labs/core";
+import { Node, Yoga } from "yoga-layout/load";
+
+//#region src/plugins/text/types.d.ts
+declare namespace types_d_exports$1 {
+  export { AdvanceTable, BundleLoaded, BundleUnloaded, Config$1 as Config, Deps$1 as Deps, DrawnLabel, IconRun, KernelSlice$1 as KernelSlice, LayoutOptions, Line, LocaleChanged, Point, Run, SeenText, Size, State$1 as State, TextAlign, TextApi, TextBind, TextCtx, TextLayout, TextRun, TextShadow, TextStyle, TextStyleInput, TextStyles, TextValue, TextWrap, Warn };
+}
+/**
+ * A point in reference units: where a label sits, and which point of the block sits there.
+ *
+ * @example
+ * ```ts
+ * const anchor: Point = { x: 0.5, y: 0.5 };
+ * ```
+ */
+type Point = {
+  x: number;
+  y: number;
+};
+/**
+ * The size of a measured block, in reference pixels.
+ *
+ * @example
+ * ```ts
+ * const size: Size = { width: 57.6, height: 38.4 };
+ * ```
+ */
+type Size = {
+  width: number;
+  height: number;
+};
+/**
+ * Which numeric component field a label shows. The component is named, not imported: a HUD is
+ * written before the game's components are in scope.
+ *
+ * @example
+ * ```ts
+ * const bind: TextBind = { component: "Counter", field: "value" };
+ * ```
+ */
+type TextBind = {
+  component: string;
+  field: string;
+};
+/**
+ * What the `Text` component holds. `resolved` is engine-owned: a game writes `content`, `style`,
+ * `bind` and `anchor`, and reads `resolved`.
+ *
+ * @example
+ * ```ts
+ * const value: TextValue = {
+ *   content: "+5", style: "body", bind: undefined, anchor: { x: 0.5, y: 0.5 }, resolved: "+5"
+ * };
+ * ```
+ */
+type TextValue = {
+  content: string | Message;
+  style: string;
+  bind: TextBind | undefined;
+  anchor: Point;
+  resolved: string;
+};
+/**
+ * Where the lines of a block sit inside the widest of them.
+ *
+ * @example
+ * ```ts
+ * const align: TextAlign = "center";
+ * ```
+ */
+type TextAlign = "left" | "center" | "right";
+/**
+ * The wrap width of a style in reference pixels, or `"none"` for one line per `\n` segment.
+ *
+ * @example
+ * ```ts
+ * const wrap: TextWrap = 480;
+ * ```
+ */
+type TextWrap = number | "none";
+/**
+ * The drop shadow of a style as the plugin stores it: a copy of every glyph run in `color`, at
+ * `alpha`, moved by `dx` and `dy` reference pixels.
+ *
+ * @example
+ * ```ts
+ * const shadow: TextShadow = { color: 0x5b3a1e, dx: 0, dy: 4, alpha: 1 };
+ * ```
+ */
+type TextShadow = {
+  color: number;
+  dx: number;
+  dy: number;
+  alpha: number;
+};
+/**
+ * One style as a game writes it: the font and the size are required, the rest has defaults.
+ *
+ * @example
+ * ```ts
+ * // A popup title: cream display glyphs over a brown shadow 4 px down.
+ * const title: TextStyleInput = {
+ *   font: "ui.font-display", size: 56, fill: 0xfff3d6, shadow: { color: 0x5b3a1e, dx: 0, dy: 4 }
+ * };
+ *
+ * defineTextStyles({ "popup.title": title }).map["popup.title"]?.shadow;
+ * // { color: 0x5b3a1e, dx: 0, dy: 4, alpha: 1 }
+ * ```
+ */
+type TextStyleInput = {
+  font: string;
+  bold?: string;
+  italic?: string;
+  size: number;
+  fill: number; /** The outline colour. Drawn only when `strokeWidth` is above 0. */
+  stroke?: number;
+  /**
+   * The outline width in reference px: 8 copies of each glyph run on a circle this wide (12 from 6
+   * on), tinted `stroke`. 0 draws none. It never changes what `measure` answers.
+   */
+  strokeWidth?: number;
+  letterSpacing?: number;
+  align?: TextAlign;
+  wrap?: TextWrap;
+  digits?: boolean;
+  /**
+   * A drop shadow under every glyph run, in reference px at the style size. `alpha` is 1 when
+   * left out. It never changes what `measure` answers.
+   */
+  shadow?: {
+    color: number;
+    dx: number;
+    dy: number;
+    alpha?: number;
+  };
+};
+/**
+ * One style as the plugin stores it: every field filled, `bold` and `italic` only when the game
+ * shipped those MSDF fonts, `shadow` only when the style has one.
+ *
+ * @example
+ * ```ts
+ * const style: TextStyle = {
+ *   font: "ui.font-body", bold: undefined, italic: undefined, size: 32, fill: 0xffffff,
+ *   stroke: 0x000000, strokeWidth: 0, letterSpacing: 0, align: "left", wrap: "none",
+ *   digits: false, shadow: undefined
+ * };
+ * ```
+ */
+type TextStyle = {
+  font: string;
+  bold: string | undefined;
+  italic: string | undefined;
+  size: number;
+  fill: number;
+  stroke: number;
+  strokeWidth: number;
+  letterSpacing: number;
+  align: TextAlign;
+  wrap: TextWrap;
+  digits: boolean;
+  shadow: TextShadow | undefined;
+};
+/**
+ * What `defineTextStyles` returns and a feature registers under its `textStyles` key. Structural
+ * on purpose: `flow` carries the map, `text` reads it.
+ *
+ * @example
+ * ```ts
+ * const styles: TextStyles = { kind: "textStyles", map: { "hud.title": bodyStyle } };
+ * ```
+ */
+type TextStyles = {
+  readonly kind: "textStyles";
+  readonly map: Record<string, TextStyle>;
+};
+/**
+ * The advances of one font at the size the `.fnt` was exported with. Widths scale by
+ * `style.size / size`; kerning pairs are ignored.
+ *
+ * @example
+ * ```ts
+ * const table: AdvanceTable = { size: 32, lineHeight: 40, advances: new Map([["1", 18]]) };
+ * ```
+ */
+type AdvanceTable = {
+  size: number;
+  lineHeight: number;
+  advances: Map<string, number>;
+};
+/**
+ * One run of glyphs: the text and the flags every glyph in it shares.
+ *
+ * @example
+ * ```ts
+ * const run: TextRun = { kind: "text", text: "+5", bold: true, italic: false, color: 0xffe082 };
+ * ```
+ */
+type TextRun = {
+  kind: "text";
+  text: string;
+  bold: boolean;
+  italic: boolean;
+  color: number | undefined;
+};
+/**
+ * One inline icon: an asset key drawn square at the line height.
+ *
+ * @example
+ * ```ts
+ * const run: IconRun = { kind: "icon", key: "hud.coin" };
+ * ```
+ */
+type IconRun = {
+  kind: "icon";
+  key: string;
+};
+/**
+ * A piece of a line: glyphs or one inline icon.
+ *
+ * @example
+ * ```ts
+ * const runs: Run[] = [{ kind: "icon", key: "hud.coin" }];
+ * ```
+ */
+type Run = TextRun | IconRun;
+/**
+ * One laid-out line and how wide it is.
+ *
+ * @example
+ * ```ts
+ * const line: Line = { runs: [{ kind: "icon", key: "hud.coin" }], width: 38.4 };
+ * ```
+ */
+type Line = {
+  runs: Run[];
+  width: number;
+};
+/**
+ * A laid-out block: its lines and the size `measure` answers with.
+ *
+ * @example
+ * ```ts
+ * const layout: TextLayout = { lines: [], width: 0, height: 0 };
+ * ```
+ */
+type TextLayout = {
+  lines: Line[];
+  width: number;
+  height: number;
+};
+/**
+ * What one label container was last filled from: the style object and the laid-out block. An
+ * update with the same style object, the same anchor and the same lines and runs writes the new
+ * text and positions into the objects already there.
+ */
+type DrawnLabel = {
+  style: TextStyle;
+  layout: TextLayout;
+};
+/**
+ * A dev warning that is written once per key. Pure modules take it as an argument, so nothing
+ * below the plugin context reaches the log itself.
+ *
+ * @example
+ * ```ts
+ * const warn: Warn = (key, message) => seen.has(key) || log.warn(message);
+ * ```
+ */
+type Warn = (key: string, message: string, data?: Record<string, unknown>) => void;
+/**
+ * What the pure layout needs next to the runs, the style and the tables.
+ *
+ * @example
+ * ```ts
+ * const options: LayoutOptions = { missingGlyph: "□", warn: () => undefined };
+ * ```
+ */
+type LayoutOptions = {
+  missingGlyph: string;
+  warn: Warn;
+};
+/**
+ * What was resolved for one entity last, so the frame step knows whether anything moved.
+ *
+ * @example
+ * ```ts
+ * const seen: SeenText = { content: "+5", style: "body", bind: undefined, locale: "ru" };
+ * ```
+ */
+type SeenText = {
+  content: unknown;
+  style: string;
+  bind: string | undefined;
+  locale: string;
+};
+/**
+ * text plugin config.
+ *
+ * @example
+ * ```ts
+ * createApp({ pluginConfigs: { text: { fonts: { body: "ui.body", digits: "ui.digits" } } } });
+ * ```
+ */
+type Config$1 = {
+  /** The two fonts every game ships in its boot bundle. They back the built-in styles. */fonts: {
+    body: string;
+    digits: string;
+  }; /** Drawn and measured for a character the font does not have. */
+  missingGlyph: string;
+};
+/**
+ * text plugin state.
+ */
+type State$1 = {
+  /** Built-in styles first, then the styles of every feature in feature order. */styles: Map<string, TextStyle>; /** Style name to the feature that brought it, for the duplicate error. */
+  styleOwner: Map<string, string>; /** The config fonts plus every `font`, `bold` and `italic` of every style. */
+  fontKeys: Set<string>; /** The parsed advance table per font key, filled when `assets` has the font. */
+  tables: Map<string, AdvanceTable>; /** The font keys handed to `renderer.sync.fonts.install`. */
+  installed: Set<string>; /** What was resolved for an entity last. */
+  seen: Map<Entity, SeenText>; /** `bind.component` to its world type; `undefined` after the one warning. */
+  bindTypes: Map<string, AnyComponent | undefined>; /** The measured size of every live label, for `ui`. */
+  measured: Map<Entity, Size>; /** Layout per `style + resolved`, oldest dropped first. */
+  cache: Map<string, TextLayout>; /** What every live label container was last filled from, by container. */
+  drawn: WeakMap<object, DrawnLabel>; /** Entities to re-resolve in the next layout phase. */
+  dirty: Set<Entity>; /** Warning keys already written, so a style, a tag, a glyph or a font warns once. */
+  warned: Set<string>; /** The system, the two world hooks and the display adapter. */
+  removers: Array<() => void>;
+};
+/**
+ * text plugin API, `app.text`. Two questions: how big a piece of text is, and which styles the
+ * game registered. Everything else happens in the frame.
+ *
+ * @example
+ * ```ts
+ * app.text.measure("120", "digits"); // { width: 57.6, height: 38.4 }
+ * app.text.styles(); // ["body", "digits"]
+ * ```
+ */
+type TextApi = {
+  /**
+   * The size of a piece of text in reference pixels, from the advance table of the style's font.
+   * A `Message` is formatted in the current locale first. Never touches a canvas, so the answer
+   * is the same in a browser and in plain Bun. Cached per style and resolved string.
+   *
+   * @param content - A plain string, or what `tr` returned.
+   * @param style - A registered style name. An unknown one warns once and measures as `body`.
+   * @returns The width and height of the block.
+   * @example
+   * ```ts
+   * // `ui.layout` asks once per invalidation, from the Yoga measure function of a text element.
+   * const text = ctx.require(textPlugin);
+   *
+   * text.measure("120", "digits"); // { width: 57.6, height: 38.4 } on the 0.6 em fallback
+   * ```
+   */
+  measure(content: string | Message, style: string): Size;
+  /**
+   * The registered style names: the two built-ins first, then the styles of every feature in
+   * feature order.
+   *
+   * @returns A frozen list of style names.
+   * @example
+   * ```ts
+   * // A dev overlay lists what a game may write in a `style` prop.
+   * app.text.styles(); // ["body", "digits", "hud.digits"]
+   * ```
+   */
+  styles(): readonly string[];
+};
+/**
+ * Resolved dependency APIs.
+ */
+type Deps$1 = {
+  time: Api;
+  flow: Api$1;
+  world: Api$2;
+  renderer: Api$3;
+  assets: Api$4;
+  i18n: I18nApi;
+};
+/**
+ * What the kernel context offers before the deps are attached.
+ *
+ * `text` owns no event, so `emit` is the kernel's and never called here.
+ */
+type KernelSlice$1 = PluginCtx<Config$1, State$1> & {
+  readonly global: object;
+  readonly log: Log.LogApi;
+  readonly require: Require;
+};
+/**
+ * Domain context shared by the files of the plugin: the kernel slice plus the resolved deps.
+ */
+type TextCtx = KernelSlice$1 & {
+  readonly deps: Deps$1;
+};
+/**
+ * Payload of the `assets:bundle-loaded` hook: a bundle landed, so a font may be readable now.
+ */
+type BundleLoaded = Events["assets:bundle-loaded"];
+/**
+ * Payload of the `assets:bundle-unloaded` hook: `keys` names the assets that left.
+ */
+type BundleUnloaded = Events["assets:bundle-unloaded"];
+/**
+ * Payload of the `i18n:locale-changed` hook: every message has to be resolved again.
+ */
+type LocaleChanged = Events$1["i18n:locale-changed"];
+//#endregion
+//#region src/plugins/ui/layout/types.d.ts
+/**
+ * layout module state. `nodes` is attach minus detach: Yoga 3.2.1 has no instance counter.
+ */
+type LayoutState = {
+  yoga: Yoga | undefined;
+  byEntity: Map<Entity, Node>;
+  nodes: number;
+  measured: number;
+  solves: number;
+  scrolling: Entity | undefined;
+  scrollStart: {
+    pointerY: number;
+    offset: number;
+  };
+  order: number;
+  cleanups: Array<() => void>;
+};
+declare namespace types_d_exports {
+  export { Config, Deps, ElementChange, ElementMotion, Finding, FocusRing, KernelSlice, State, UiApi, UiCtx, UiNode };
+}
+/**
+ * The look of the keyboard focus ring: a dashed ring with a solid halo under it, drawn around the
+ * focused control. Colours are `0xRRGGBB`, lengths reference units.
+ *
+ * @example
+ * ```ts
+ * // A dashed ink ring with a cream halo, 9 u outside the control.
+ * const ring: FocusRing = {
+ *   stroke: 0x3a2212, strokeWidth: 4, dash: 10, offset: 9, halo: 0xfff3d6, haloWidth: 12
+ * };
+ * ```
+ */
+type FocusRing = {
+  /** The colour of the dashed ring. */stroke: number; /** The stroke width of the dashed ring. */
+  strokeWidth: number; /** The dash length of the ring, with gaps of half a dash; 0 draws it solid. */
+  dash: number; /** How far outside the control's rect the ring runs, on every side. */
+  offset: number; /** The colour of the solid halo drawn under the ring. */
+  halo: number; /** The stroke width of the halo, centred on the same path as the ring. */
+  haloWidth: number;
+};
+/**
+ * ui plugin config.
+ *
+ * @example
+ * ```ts
+ * createApp({ pluginConfigs: { ui: { tapTargetPt: 48, breakpoints: { tall: 2, wide: 1.5 } } } });
+ * // A game with a white focus ring on a dark board.
+ * createApp({
+ *   pluginConfigs: {
+ *     ui: {
+ *       focusRing: {
+ *         stroke: 0xffffff, strokeWidth: 4, dash: 10, offset: 9, halo: 0x000000, haloWidth: 12
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
+ */
+type Config = {
+  /** Smallest tap target `lint()` accepts, in CSS px (points). */tapTargetPt: number; /** `when` flags: `tall` when height / width is at least `tall`, `wide` the other way round. */
+  breakpoints: {
+    tall: number;
+    wide: number;
+  };
+  /**
+   * The ring drawn around the control the keyboard focused. Shallow merge: a game that sets
+   * `focusRing` gives all six fields.
+   */
+  focusRing: FocusRing;
+};
+/**
+ * ui plugin state: one branch per module.
+ */
+type State = {
+  jsx: JsxState;
+  styles: StylesState;
+  layout: LayoutState;
+};
+/**
+ * Resolved dependency APIs. `anim` is not here: its edge is validation only, and its work
+ * reaches `ui` through the tween driver behind every `ViewHandle`.
+ */
+type Deps = {
+  time: Api;
+  flow: Api$1;
+  world: Api$2;
+  renderer: Api$3;
+  input: InputApi;
+  i18n: I18nApi;
+  text: TextApi;
+};
+/**
+ * What the kernel context offers before the deps are attached.
+ *
+ * `ui` owns no event, so `emit` is the kernel's and never called here.
+ */
+type KernelSlice = PluginCtx<Config, State> & {
+  readonly global: object;
+  readonly log: Log.LogApi;
+  readonly require: Require;
+};
+/**
+ * Domain context shared by the three modules: the kernel slice plus the resolved deps.
+ */
+type UiCtx = KernelSlice & {
+  readonly deps: Deps;
+};
+/**
+ * ui plugin API, `app.ui`. The screen is one more projection, so the three members read it the
+ * way a test reads the board: a snapshot, a key lookup and a list of findings.
+ *
+ * @example
+ * ```ts
+ * // A headless scenario taps the claim button of the reward popup.
+ * app.ui.tree().type; // "row", the root element of the HUD
+ * app.input.tap(app.ui.find("claim") ?? 0);
+ * app.ui.lint(); // []
+ * ```
+ */
+type UiApi = {
+  /**
+   * The live screen as plain data: every root in layer order, every element in child order, with
+   * its rect in root coordinates, its resolved style and its seven state flags. A rect is natural:
+   * under a `fit: "contain"` element it is the rect before that scale, and the fitted element
+   * adds `fitScale`. Works headless.
+   *
+   * @returns The root node; several roots come back under one `screen` node.
+   * @example
+   * ```ts
+   * // A snapshot test reads the HUD without a browser.
+   * app.ui.tree().children.map(child => child.key); // ["coins", "settings", "order"]
+   * // On an iPhone SE the board slot is drawn at 0.8 of its 970 u.
+   * app.ui.tree().children[3]?.fitScale; // 0.8
+   * ```
+   */
+  tree(): UiNode;
+  /**
+   * The entity of a keyed element, so a test can tap it and `anim` can aim at it. Popup roots
+   * come first, then the projection roots in layer order.
+   *
+   * @param key - The `key` prop of the element.
+   * @returns The entity, or `undefined` for an unknown or exiting element.
+   * @example
+   * ```ts
+   * // A headless scenario answers the gate through the button of the popup.
+   * app.input.tap(app.ui.find("claim") ?? 0); // true
+   * app.ui.find("nothing"); // undefined
+   * ```
+   */
+  find(key: string): Entity | undefined;
+  /**
+   * Reads the live screen against the five rules: a tap target under `tapTargetPt` at the size
+   * it is drawn (a `fit: "contain"` on it or above it shrinks it), a text that does not fit its
+   * box in some registered locale, an absolute element with no `reason`, a clipping element
+   * (`scroll`, `overflow: "hidden"`) whose style names a nine-slice it never draws, and a root
+   * element whose style sets a `zIndex` it ignores. Never throws; empty when nothing is mounted.
+   *
+   * @returns One finding per rule and element.
+   * @example
+   * ```ts
+   * // A game test keeps the board honest on an iPhone SE: a 140 u cell in the 0.8 slot.
+   * app.ui.lint(); // [{ rule: "tap-target", key: "cell", detail: "39 x 39 pt" }]
+   * // A list styled with a nine-slice: the clip keeps it from drawing.
+   * app.ui.lint(); // [{ rule: "nine-slice-clipped", key: "orders", detail: "scroll" }]
+   * // A screen root that asks to be drawn over the others: the layer decides that.
+   * app.ui.lint(); // [{ rule: "z-index-on-root", key: "board", detail: "zIndex 2" }]
+   * ```
+   */
+  lint(): readonly Finding[];
+};
+//#endregion
+export { Config$1 as a, TextApi as c, TextValue as d, types_d_exports$1 as f, types_d_exports as i, TextStyleInput as l, State as n, Point as o, UiApi as r, State$1 as s, Config as t, TextStyles as u };