@kurot/ui 1.1.7

package/README.md

@@ -0,0 +1,258 @@
+# @kurot/ui
+
+UI component framework for [@kurot/core](https://github.com/kurot-engine/kurot/tree/main/packages/core). Migrated from Egret EUI, rewritten in modern TypeScript with clean class inheritance — no namespace hacks, no prototype manipulation.
+
+> **Stable (1.1.7).** Requires `@kurot/core@^1.0.12`. Targets ES2022 + evergreen browsers, same as core.
+
+For the full list of changes in this release, see [CHANGELOG.md](./CHANGELOG.md).
+
+## Installation
+
+```bash
+pnpm add @kurot/ui @kurot/core
+```
+
+`@kurot/ui` declares `@kurot/core` as a peer dependency. Install both packages explicitly so the application controls the resolved core version.
+
+## Quick Start
+
+```ts
+import { Group, Label, Button, Rect, BasicLayout } from '@kurot/ui';
+
+const group = new Group();
+group.layout = new BasicLayout();
+group.width = 400;
+group.height = 300;
+
+const btn = new Button();
+btn.label = 'Click Me';
+btn.width = 120;
+btn.height = 36;
+btn.left = 20;
+btn.top = 20;
+
+// Manual skin: transparent hit area + visual children
+btn.graphics.beginFill(0x000000, 0.01);
+btn.graphics.drawRect(0, 0, 120, 36);
+btn.graphics.endFill();
+
+const bg = new Rect(120, 36, 0x6c5ce7);
+btn.addChild(bg);
+
+const lbl = new Label('Click Me');
+lbl.width = 120;
+lbl.height = 36;
+lbl.textAlign = 'center';
+lbl.verticalAlign = 'middle';
+lbl.textColor = 0xffffff;
+btn.labelDisplay = lbl;
+btn.addChild(lbl);
+
+group.addChild(btn);
+```
+
+## Architecture
+
+Every UI component holds a `UIState` instance that manages the layout lifecycle. `Group` and `Component` delegate all layout calls to it — no mixin, no prototype copying.
+
+```
+Group / Component
+  └── ui: UIState        ← layout state + invalidation logic
+        └── owner: IUIOwner  ← back-reference to the DisplayObject
+```
+
+### Layout cycle
+
+Property changes are batched and applied on the next animation frame:
+
+```
+invalidateProperties / invalidateSize / invalidateDisplayList
+  → Validator queues the component
+  → requestAnimationFrame tick
+  → validateProperties  (shallow → deep,  commitProperties)
+  → validateSize        (deep → shallow,  measure)
+  → validateDisplayList (shallow → deep,  updateDisplayList)
+```
+
+### Skin system
+
+```ts
+import { Skin, State, SetProperty } from '@kurot/ui';
+
+class MyButtonSkin extends Skin {
+	constructor() {
+		super();
+		this.skinParts = ['labelDisplay'];
+		this.states = [
+			new State('up'),
+			new State('down', [new SetProperty('bg', 'fillColor', 0x5a4bd1)]),
+			new State('disabled', [new SetProperty('bg', 'fillColor', 0x636e72)]),
+		];
+		// build visual children...
+	}
+}
+
+btn.skinName = MyButtonSkin;
+```
+
+## Components
+
+### Basic Controls
+
+| Component      | Description                                                                 |
+| -------------- | --------------------------------------------------------------------------- |
+| `Label`        | Text display. Wraps `TextField` in the UI lifecycle.                        |
+| `Button`       | Tappable button with `up`/`down`/`disabled` states and `labelDisplay` part. |
+| `CheckBox`     | Toggle button. Dispatches `Event.CHANGE` on selection change.               |
+| `RadioButton`  | Mutually exclusive toggle. Use `groupName` to link buttons.                 |
+| `ToggleButton` | Base for toggle-style buttons.                                              |
+| `ToggleSwitch` | Binary on/off switch (visual variant of `ToggleButton`).                    |
+| `ProgressBar`  | Value indicator. Inject `thumb` (a `Component`) as the fill part.           |
+| `HSlider`      | Horizontal slider. Inject `thumb` and `track` skin parts.                   |
+| `VSlider`      | Vertical slider. Inject `thumb` and `track` skin parts.                     |
+| `Rect`         | Filled/stroked rectangle. Supports `fillColor`, `strokeColor`, `fillAlpha`. |
+| `Image`        | Bitmap display. Supports URL string or `Texture`, `scale9Grid`, `fillMode`. |
+
+### Text Input
+
+| Component      | Description                                                                |
+| -------------- | -------------------------------------------------------------------------- |
+| `EditableText` | Editable text field with `prompt` (placeholder) and `promptColor` support. |
+| `TextInput`    | Skinnable input component. Skin parts: `textDisplay`, `promptDisplay`.     |
+
+### Containers
+
+| Component   | Description                                                                                  |
+| ----------- | -------------------------------------------------------------------------------------------- |
+| `Group`     | Base container. Holds a `LayoutBase` for child positioning. Implements `IViewport`.          |
+| `Panel`     | Container with title bar. Skin parts: `titleDisplay`, `closeButton`, `moveArea` (draggable). |
+| `ViewStack` | Shows one child at a time. Set `selectedIndex` or `selectedChild` to switch.                 |
+| `Scroller`  | Touch-scrolling wrapper for any `IViewport`. Supports bounce, scroll bars, scroll policies.  |
+| `UILayer`   | Full-screen overlay container.                                                               |
+
+### Data-Driven
+
+| Component      | Description                                                                                 |
+| -------------- | ------------------------------------------------------------------------------------------- |
+| `DataGroup`    | Renders a data collection using item renderers. Supports virtual layout for large datasets. |
+| `List`         | `DataGroup` with tap-to-select. Dispatches `ItemTapEvent.ITEM_TAP`.                         |
+| `TabBar`       | Horizontal tab strip driven by `dataProvider`. Dispatches `ItemTapEvent.ITEM_TAP`.          |
+| `ComboBox`     | Drop-down selector. Tapping toggles a `list` skin part; dispatches `Event.CHANGE` on selection. |
+| `ItemRenderer` | Base class for custom item renderers. Override `dataChanged()` to update visuals.           |
+
+### Scroll Bars
+
+| Component    | Description                                               |
+| ------------ | --------------------------------------------------------- |
+| `HScrollBar` | Horizontal scroll bar. Bind to a viewport via `viewport`. |
+| `VScrollBar` | Vertical scroll bar. Bind to a viewport via `viewport`.   |
+
+## Layouts
+
+| Layout             | Description                                                                                                                    |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| `BasicLayout`      | Positions children using `left`/`right`/`top`/`bottom`/`horizontalCenter`/`verticalCenter` and `percentWidth`/`percentHeight`. |
+| `VerticalLayout`   | Linear vertical arrangement with gap, padding, alignment, percent sizes, and virtual layout support.                           |
+| `HorizontalLayout` | Linear horizontal arrangement with gap, padding, alignment, percent sizes, and virtual layout support.                         |
+| `TileLayout`       | Grid arrangement with configurable orientation, column/row counts, justification, and virtual layout support.                  |
+
+## Data Collections
+
+```ts
+import { ArrayCollection } from '@kurot/ui';
+
+const data = new ArrayCollection(['Apple', 'Banana', 'Cherry']);
+
+data.addItem('Durian');
+data.addItemAt('Elderberry', 1);
+data.removeItemAt(0);
+data.replaceItemAt('Fig', 0);
+data.sortOn('name'); // sort by field
+data.sort((a, b) => (a > b ? 1 : -1)); // custom sort
+data.filterFunction(item => item !== 'Fig');
+data.refresh(); // notify view after manual source changes
+```
+
+## Virtual Layout
+
+For large datasets, enable virtual layout so only visible renderers are created:
+
+```ts
+import { List, ItemRenderer, ArrayCollection, Label } from '@kurot/ui';
+
+class MyRenderer extends ItemRenderer {
+	private _label: Label;
+	constructor() {
+		super();
+		this._label = new Label('');
+		this._label.width = 200;
+		this._label.height = 36;
+		this.addChild(this._label);
+	}
+	protected override dataChanged(): void {
+		this._label.text = String(this.data ?? '');
+	}
+}
+
+const list = new List();
+list.dataProvider = new ArrayCollection(largeArray);
+list.itemRenderer = MyRenderer;
+list.useVirtualLayout = true; // only visible renderers are instantiated
+list.width = 200;
+list.height = 300; // visible window height
+list.scrollEnabled = true;
+```
+
+## Constraint Properties
+
+All UI components support these layout constraint properties:
+
+```ts
+component.left = 20;
+component.right = 20;
+component.top = 10;
+component.bottom = 10;
+component.horizontalCenter = 0;
+component.verticalCenter = 0;
+component.percentWidth = 50;
+component.percentHeight = 100;
+```
+
+## View States
+
+```ts
+import { State, SetProperty, AddItems } from '@kurot/ui';
+
+class MyButtonSkin extends Skin {
+	states = [
+		new State('up'),
+		new State('down', [new SetProperty('bg', 'fillColor', 0x5a4bd1)]),
+		new State('disabled', [
+			new SetProperty('bg', 'fillColor', 0x636e72),
+			new SetProperty('lbl', 'textColor', 0xb2bec3),
+		]),
+	];
+}
+```
+
+## Events
+
+| Event                               | Dispatched by                   | Description                                          |
+| ----------------------------------- | ------------------------------- | ---------------------------------------------------- |
+| `Event.CHANGE`                      | `List`, `TabBar`, `ComboBox`, `CheckBox`, `RadioButton`, `Range` | Selection or value changed (user interaction only for List/TabBar) |
+| `ItemTapEvent.ITEM_TAP`             | `List`, `TabBar`                | Item tapped. Has `item`, `itemIndex`, `itemRenderer` |
+| `CollectionEvent.COLLECTION_CHANGE` | `ArrayCollection`               | Data added, removed, replaced, reset                 |
+| `UIEvent.CLOSING`                   | `Panel`                         | Close button tapped (cancelable)                     |
+| `UIEvent.CREATION_COMPLETE`         | Any `Component`                 | First `createChildren` completed                     |
+
+## Differences from Egret EUI
+
+|                | Egret EUI                   | @kurot/ui                          |
+| -------------- | --------------------------- | ------------------------------------ |
+| Namespace      | `eui.*` global              | ES Module named exports              |
+| Component base | `namespace` + `mixin`       | Standard class inheritance           |
+| Layout state   | Prototype-injected          | `UIState` delegation                 |
+| EXML runtime   | Built-in parser             | Compile-time only (`@kurot/cli`)   |
+| `thisObject`   | Required in event listeners | Not needed — use arrow functions     |
+| Virtual layout | Default on                  | Opt-in via `useVirtualLayout = true` |
+| i18n           | Built-in                    | Not supported                        |

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './kurot/core/index.js';
+export * from './kurot/layouts/index.js';
+export * from './kurot/components/index.js';
+export * from './kurot/events/index.js';
+export * from './kurot/states/index.js';
+export * from './kurot/collections/index.js';
+export * from './kurot/binding/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,0BAA0B,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from './kurot/core/index.js';
+export * from './kurot/layouts/index.js';
+export * from './kurot/components/index.js';
+export * from './kurot/events/index.js';
+export * from './kurot/states/index.js';
+export * from './kurot/collections/index.js';
+export * from './kurot/binding/index.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC;AACxC,cAAc,yBAAyB,CAAC;AACxC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,0BAA0B,CAAC"}

package/dist/kurot/binding/Binding.d.ts

@@ -0,0 +1,38 @@
+import { Watcher } from './Watcher.js';
+/**
+ * Binding — static utility class for data binding.
+ *
+ * - `bindProperty(host, chain, target, prop)` — binds `host.chain` → `target.prop`
+ * - `bindHandler(host, chain, handler, thisObject)` — calls `handler(value)` on change
+ * - `bindProperties(host, templates, chainIndex, target, prop)` — template-string binding
+ */
+export declare class Binding {
+    /**
+     * Binds a property chain on `host` to a target property.
+     *
+     * ```ts
+     * Binding.bindProperty(user, ['name'], label, 'text');
+     * // label.text === user.name; auto-updates when user dispatches PropertyChange
+     * ```
+     */
+    static bindProperty(host: unknown, chain: string[], target: unknown, prop: string): Watcher | undefined;
+    /**
+     * Binds a property chain on `host` to a handler function.
+     *
+     * ```ts
+     * Binding.bindHandler(user, ['name'], (v) => console.log(v), null);
+     * ```
+     */
+    static bindHandler(host: unknown, chain: string[], handler: (value: unknown) => void, thisObject: unknown): Watcher | undefined;
+    /**
+     * Template-string binding used by EXML compiler.
+     *
+     * `templates` is a mixed array of literal strings and `Watcher` instances.
+     * `chainIndex` marks which entries are dynamic (property chains).
+     *
+     * The result is the string concatenation of all template values, written
+     * to `target[prop]`.
+     */
+    static bindProperties(host: unknown, templates: unknown[], chainIndex: number[], target: unknown, prop: string): Watcher | undefined;
+}
+//# sourceMappingURL=Binding.d.ts.map

package/dist/kurot/binding/Binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Binding.d.ts","sourceRoot":"","sources":["../../../src/kurot/binding/Binding.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC;;;;;;GAMG;AACH,qBAAa,OAAO;IACnB;;;;;;;OAOG;WACW,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAY9G;;;;;;OAMG;WACW,WAAW,CACxB,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,MAAM,EAAE,EACf,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,EACjC,UAAU,EAAE,OAAO,GACjB,OAAO,GAAG,SAAS;IAQtB;;;;;;;;OAQG;WACW,cAAc,CAC3B,IAAI,EAAE,OAAO,EACb,SAAS,EAAE,OAAO,EAAE,EACpB,UAAU,EAAE,MAAM,EAAE,EACpB,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,MAAM,GACV,OAAO,GAAG,SAAS;CAgCtB"}

package/dist/kurot/binding/Binding.js

@@ -0,0 +1,88 @@
+import { Watcher } from './Watcher.js';
+/**
+ * Binding — static utility class for data binding.
+ *
+ * - `bindProperty(host, chain, target, prop)` — binds `host.chain` → `target.prop`
+ * - `bindHandler(host, chain, handler, thisObject)` — calls `handler(value)` on change
+ * - `bindProperties(host, templates, chainIndex, target, prop)` — template-string binding
+ */
+export class Binding {
+    /**
+     * Binds a property chain on `host` to a target property.
+     *
+     * ```ts
+     * Binding.bindProperty(user, ['name'], label, 'text');
+     * // label.text === user.name; auto-updates when user dispatches PropertyChange
+     * ```
+     */
+    static bindProperty(host, chain, target, prop) {
+        const watcher = Watcher.watch(host, chain, undefined, undefined);
+        if (watcher) {
+            const assign = (value) => {
+                target[prop] = value;
+            };
+            watcher.setHandler(assign, undefined);
+            assign(watcher.getValue());
+        }
+        return watcher;
+    }
+    /**
+     * Binds a property chain on `host` to a handler function.
+     *
+     * ```ts
+     * Binding.bindHandler(user, ['name'], (v) => console.log(v), null);
+     * ```
+     */
+    static bindHandler(host, chain, handler, thisObject) {
+        const watcher = Watcher.watch(host, chain, handler, thisObject);
+        if (watcher) {
+            handler.call(thisObject, watcher.getValue());
+        }
+        return watcher;
+    }
+    /**
+     * Template-string binding used by EXML compiler.
+     *
+     * `templates` is a mixed array of literal strings and `Watcher` instances.
+     * `chainIndex` marks which entries are dynamic (property chains).
+     *
+     * The result is the string concatenation of all template values, written
+     * to `target[prop]`.
+     */
+    static bindProperties(host, templates, chainIndex, target, prop) {
+        if (templates.length === 1 && chainIndex.length === 1) {
+            return Binding.bindProperty(host, templates[0].split('.'), target, prop);
+        }
+        const assign = () => {
+            target[prop] = _joinValues(templates);
+        };
+        let lastWatcher;
+        for (const index of chainIndex) {
+            const element = templates[index];
+            let watcher;
+            if (typeof element === 'string') {
+                watcher = Watcher.watch(host, element.split('.'), undefined, undefined);
+            }
+            else if (element instanceof Watcher) {
+                watcher = element;
+                watcher.reset(host);
+            }
+            if (watcher) {
+                templates[index] = watcher;
+                watcher.setHandler(assign, undefined);
+                lastWatcher = watcher;
+            }
+        }
+        assign();
+        return lastWatcher;
+    }
+}
+// ── Helpers ─────────────────────────────────────────────────────────
+function _joinValues(templates) {
+    let value = '';
+    for (const item of templates) {
+        value += item instanceof Watcher ? String(item.getValue() ?? '') : String(item);
+    }
+    return value;
+}
+//# sourceMappingURL=Binding.js.map

package/dist/kurot/binding/Binding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Binding.js","sourceRoot":"","sources":["../../../src/kurot/binding/Binding.ts"],"names":[],"mappings":"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"}

package/dist/kurot/binding/Watcher.d.ts

@@ -0,0 +1,57 @@
+import type { IEventDispatcher } from '@kurot/core';
+/**
+ * An object that can both dispatch {@link PropertyEvent.PROPERTY_CHANGE} and be
+ * read by arbitrary property name (i.e. it is a record of named bindable values).
+ *
+ * This is the minimal contract a binding host must satisfy. In practice every
+ * host is an {@link EventDispatcher} subclass (Skin, Component, Group, …) whose
+ * own properties are mutated and then announced via
+ * {@link PropertyEvent.dispatchPropertyEvent}. The index signature models that
+ * dynamic access without forcing every host through `as unknown as Record<…>`.
+ */
+export type Bindable = IEventDispatcher & Record<string, unknown>;
+/**
+ * Watcher monitors a property (or property chain) on a host object.
+ * When the property changes (via {@link PropertyEvent}), the registered
+ * handler is invoked with the new value.
+ *
+ * Create instances via the static {@link Watcher.watch} method — do not use the
+ * constructor directly.
+ */
+export declare class Watcher {
+    private _host?;
+    private readonly _property;
+    private _handler?;
+    private _thisObject;
+    private readonly _next?;
+    private _isExecuting;
+    constructor(property: string, handler: ((value: unknown) => void) | undefined, thisObject: unknown, next: Watcher | undefined);
+    /**
+     * Creates and starts a Watcher for a property chain.
+     *
+     * ```ts
+     * // watches host.a.b.c
+     * Watcher.watch(host, ['a', 'b', 'c'], (value) => { ... }, this);
+     * ```
+     *
+     * @param host   Root object hosting the chain.  Must dispatch
+     *               `PropertyEvent.PROPERTY_CHANGE` when its bindable
+     *               properties change (i.e. implement `IEventDispatcher`).
+     * @param chain  Property names forming the chain, e.g. `['a','b','c']`.
+     * @param handler Called with the new leaf value whenever the chain changes.
+     * @param thisObject  `this` context for the handler.
+     * @returns The head Watcher, or `undefined` if `chain` is empty.
+     */
+    static watch(host: IEventDispatcher | undefined, chain: string[], handler: ((value: unknown) => void) | undefined, thisObject: unknown): Watcher | undefined;
+    getValue(): unknown;
+    setHandler(handler: (value: unknown) => void, thisObject: unknown): void;
+    /**
+     * Re-points this watcher at a new host.
+     * Pass `undefined` to detach from the current host.
+     */
+    reset(newHost: IEventDispatcher | undefined): void;
+    unwatch(): void;
+    private _getHostPropertyValue;
+    private _onPropertyChange;
+}
+//# sourceMappingURL=Watcher.d.ts.map

package/dist/kurot/binding/Watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Watcher.d.ts","sourceRoot":"","sources":["../../../src/kurot/binding/Watcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG3D;;;;;;;;;GASG;AACH,MAAM,MAAM,QAAQ,GAAG,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAElE;;;;;;;GAOG;AACH,qBAAa,OAAO;IAGnB,OAAO,CAAC,KAAK,CAAC,CAAW;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,CAA2B;IAC5C,OAAO,CAAC,WAAW,CAAU;IAC7B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAU;IACjC,OAAO,CAAC,YAAY,CAAS;gBAK5B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,SAAS,EAC/C,UAAU,EAAE,OAAO,EACnB,IAAI,EAAE,OAAO,GAAG,SAAS;IAU1B;;;;;;;;;;;;;;;OAeG;WACW,KAAK,CAClB,IAAI,EAAE,gBAAgB,GAAG,SAAS,EAClC,KAAK,EAAE,MAAM,EAAE,EACf,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,SAAS,EAC/C,UAAU,EAAE,OAAO,GACjB,OAAO,GAAG,SAAS;IAUf,QAAQ,IAAI,OAAO;IAKnB,UAAU,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,EAAE,UAAU,EAAE,OAAO,GAAG,IAAI;IAM/E;;;OAGG;IACI,KAAK,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,GAAG,IAAI;IAsBlD,OAAO,IAAI,IAAI;IAQtB,OAAO,CAAC,qBAAqB;IAI7B,OAAO,CAAC,iBAAiB,CAmBvB;CACF"}

package/dist/kurot/binding/Watcher.js

@@ -0,0 +1,119 @@
+import { PropertyEvent } from '../events/PropertyEvent.js';
+/**
+ * Watcher monitors a property (or property chain) on a host object.
+ * When the property changes (via {@link PropertyEvent}), the registered
+ * handler is invoked with the new value.
+ *
+ * Create instances via the static {@link Watcher.watch} method — do not use the
+ * constructor directly.
+ */
+export class Watcher {
+    // ── Instance fields ───────────────────────────────────────────────────
+    _host;
+    _property;
+    _handler;
+    _thisObject;
+    _next;
+    _isExecuting = false;
+    // ── Constructor ───────────────────────────────────────────────────────
+    constructor(property, handler, thisObject, next) {
+        this._property = property;
+        this._handler = handler;
+        this._thisObject = thisObject;
+        this._next = next;
+    }
+    // ── Public methods ────────────────────────────────────────────────────
+    /**
+     * Creates and starts a Watcher for a property chain.
+     *
+     * ```ts
+     * // watches host.a.b.c
+     * Watcher.watch(host, ['a', 'b', 'c'], (value) => { ... }, this);
+     * ```
+     *
+     * @param host   Root object hosting the chain.  Must dispatch
+     *               `PropertyEvent.PROPERTY_CHANGE` when its bindable
+     *               properties change (i.e. implement `IEventDispatcher`).
+     * @param chain  Property names forming the chain, e.g. `['a','b','c']`.
+     * @param handler Called with the new leaf value whenever the chain changes.
+     * @param thisObject  `this` context for the handler.
+     * @returns The head Watcher, or `undefined` if `chain` is empty.
+     */
+    static watch(host, chain, handler, thisObject) {
+        if (chain.length === 0)
+            return undefined;
+        const property = chain[0];
+        const remaining = chain.slice(1);
+        const next = remaining.length > 0 ? Watcher.watch(undefined, remaining, handler, thisObject) : undefined;
+        const watcher = new Watcher(property, handler, thisObject, next);
+        watcher.reset(host);
+        return watcher;
+    }
+    getValue() {
+        if (this._next)
+            return this._next.getValue();
+        return this._getHostPropertyValue();
+    }
+    setHandler(handler, thisObject) {
+        this._handler = handler;
+        this._thisObject = thisObject;
+        if (this._next)
+            this._next.setHandler(handler, thisObject);
+    }
+    /**
+     * Re-points this watcher at a new host.
+     * Pass `undefined` to detach from the current host.
+     */
+    reset(newHost) {
+        if (this._host) {
+            this._host.removeEventListener(PropertyEvent.PROPERTY_CHANGE, this._onPropertyChange);
+        }
+        // The cast is unavoidable: `IEventDispatcher` (core) is not generic over
+        // a property map, so TS cannot know the host also exposes bindable own
+        // properties by name. `Bindable` only adds an index signature on top of
+        // `IEventDispatcher` — it models what every real host (Skin, Component,
+        // Group) already does at runtime. This is the single place the engine
+        // bridges the event-dispatcher contract and dynamic property access.
+        this._host = newHost;
+        if (this._host) {
+            this._host.addEventListener(PropertyEvent.PROPERTY_CHANGE, this._onPropertyChange);
+        }
+        if (this._next) {
+            this._next.reset(this._getHostPropertyValue());
+        }
+    }
+    unwatch() {
+        this.reset(undefined);
+        this._handler = undefined;
+        if (this._next)
+            this._next._handler = undefined;
+    }
+    // ── Private methods ───────────────────────────────────────────────────
+    _getHostPropertyValue() {
+        return this._host ? this._host[this._property] : undefined;
+    }
+    _onPropertyChange = (e) => {
+        // `e` arrives as `Event` because the listener is registered through the
+        // `IEventDispatcher` interface, whose signature is not generic over an
+        // EventMap (core 1.0 limitation). The dispatcher always uses
+        // `PropertyEvent.dispatchPropertyEvent`, which constructs a
+        // `PropertyEvent`, so the runtime type is guaranteed.
+        if (!(e instanceof PropertyEvent))
+            return;
+        if (e.property !== this._property || this._isExecuting)
+            return;
+        try {
+            this._isExecuting = true;
+            if (this._next) {
+                this._next.reset(this._getHostPropertyValue());
+            }
+            if (this._handler) {
+                this._handler.call(this._thisObject, this.getValue());
+            }
+        }
+        finally {
+            this._isExecuting = false;
+        }
+    };
+}
+//# sourceMappingURL=Watcher.js.map

package/dist/kurot/binding/Watcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Watcher.js","sourceRoot":"","sources":["../../../src/kurot/binding/Watcher.ts"],"names":[],"mappings":"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"}

package/dist/kurot/binding/index.d.ts

@@ -0,0 +1,3 @@
+export { Binding } from './Binding.js';
+export { Watcher } from './Watcher.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/kurot/binding/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/kurot/binding/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}

package/dist/kurot/binding/index.js

@@ -0,0 +1,3 @@
+export { Binding } from './Binding.js';
+export { Watcher } from './Watcher.js';
+//# sourceMappingURL=index.js.map

package/dist/kurot/binding/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/kurot/binding/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}