@mirasen/chessboard 0.1.0 → 1.0.0-rc.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @mirasen/chessboard
 
+## 1.0.0-rc.0
+
+### Major Changes
+
+- 2609920: First 1.0 release candidate with the new extension-driven architecture, built-in chess interaction baseline, promotion flow, and auto-promote support.
+
+### Patch Changes
+
+- 2609920: Added promotion and auto-promotion to queen extensions
+
+## 0.1.1
+
+### Patch Changes
+
+- f6ceb99: Fix relative import issues
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -6,45 +6,48 @@
 
 # @mirasen/chessboard
 
-Framework-agnostic TypeScript chessboard library focused on clean architecture, explicit rendering ownership, and extension-driven features.
+A framework-agnostic TypeScript chessboard platform with real chess interaction built in and an extension-driven architecture.
 
-## Status
+## Why this exists
+
+Most chessboards fall into one of two buckets:
 
-**Early public release (`0.1.x`)**
+- rendering primitives that leave core interaction UX to app code
+- tightly coupled monoliths that are hard to extend cleanly
 
-The core architecture is already usable, but the package is still pre-`1.0.0` and the API may evolve.
+`@mirasen/chessboard` aims for a better balance:
 
-Current focus:
+- meaningful built-in chess interaction out of the box
+- first-party extensions for common board UX
+- explicit rendering and ownership boundaries
+- extension-driven growth without turning the board into glue hell
 
-- stable core runtime
-- extension-driven rendering and interaction
-- public wrapper / package API
-- early integration ergonomics
+This is not just a board renderer. It is a chessboard platform designed for real chess interaction.
 
-Not finalized yet:
+## What you get out of the box
 
-- promotion flow
-- some higher-level public APIs
-- broader test coverage
-- final `1.0.0` API guarantees
+The built-in first-party extension baseline currently includes both foundational runtime-facing extensions and user-facing board features.
 
-## Goals
+- `renderer` — the first-party rendering extension that validates the same extension architecture used for board features
+- `events`
+- `selectedSquare`
+- `activeTarget`
+- `legalMoves`
+- `lastMove`
+- `promotion`
+- `autoPromote`
 
-- framework-agnostic board core
-- explicit runtime / render / interaction boundaries
-- extension-first architecture
-- predictable rendering ownership
-- room for advanced features without core hacks
+That means the board already covers a meaningful baseline chess UX instead of stopping at “draw squares and pieces”.
 
-## Current features
+## Highlights
 
-- board rendering
-- orientation support
-- selection and drag interaction
-- move targeting
-- move animation foundation
-- built-in visual extensions such as selected square, active target, legal moves, and last move
-- board events extension with `setOnUiMove(...)` and `setOnRawUpdate(...)`
+- Real built-in chess interaction
+- Extension-driven architecture
+- First-party baseline extensions
+- Explicit SVG slot ownership
+- Clean separation between runtime, rendering, interaction, and animation
+- Promotion flow built into the board pipeline
+- Optional auto-promotion as a separate behavior extension
 
 ## Installation
 
@@ -52,45 +55,219 @@ Not finalized yet:
 npm install @mirasen/chessboard
 ```
 
-## Example
+## Usage
+
+### Minimal example
 
 ```ts
 import { createBoard } from '@mirasen/chessboard';
 
+const element = document.getElementById('board');
+
+if (!element) {
+	throw new Error('Missing board element');
+}
+
 const board = createBoard({
-	// API still evolving in 0.1.x
+	element
 });
+// Set free movability, default - disabled
+board.setMovability({
+	mode: 'free'
+});
+```
+
+### Explicit built-in interaction extensions
+
+```ts
+import { createBoard } from '@mirasen/chessboard';
+
+const element = document.getElementById('board');
+
+if (!element) {
+	throw new Error('Missing board element');
+}
+
+const board = createBoard({
+	element,
+	extensions: [
+		// Always add renderer first, otherwise nothing will be rendered
+		'renderer',
+		'selectedSquare',
+		'activeTarget',
+		'legalMoves',
+		'lastMove',
+		'events',
+		// Keep autoPromote before promotion, otherwise promotion may defer the move first
+		'autoPromote',
+		'promotion'
+	]
+});
+```
 
-board.extensions.events.setOnUiMove((move) => {
+### setOnUIMove
+
+```ts
+import { createBoard } from '@mirasen/chessboard';
+
+const element = document.getElementById('board');
+
+if (!element) {
+	throw new Error('Missing board element');
+}
+
+const board = createBoard({
+	element,
+	state: {
+		board: 'start',
+		interaction: {
+			movability: {
+				mode: 'free'
+			}
+		}
+	}
+});
+
+board.extensions.events.setOnUIMove((move) => {
 	console.log('UI move:', move);
 });
 ```
 
-## Artwork
+### setMovability - strict with explicit destinations
+
+```ts
+import { createBoard } from '@mirasen/chessboard';
+
+const element = document.getElementById('board');
+
+if (!element) {
+	throw new Error('Missing board element');
+}
+
+const board = createBoard({
+	element
+});
+
+board.setMovability({
+	mode: 'strict',
+	destinations: {
+		e2: [{ to: 'e3' }, { to: 'e4' }],
+		d7: [
+			{ to: 'c8', promotedTo: ['queen', 'rook', 'bishop', 'knight'] },
+			{ to: 'd8', promotedTo: ['queen', 'rook', 'bishop', 'knight'] }
+		],
+		g1: [{ to: 'f3' }, { to: 'h3' }]
+	}
+});
+```
+
+### setMovability - strict with a resolver
+
+```ts
+import { createBoard } from '@mirasen/chessboard';
+
+const element = document.getElementById('board');
+
+if (!element) {
+	throw new Error('Missing board element');
+}
+
+const board = createBoard({
+	element
+});
+
+board.setMovability({
+	mode: 'strict',
+	destinations: (source) => {
+		if (source === 'e2')
+			return [
+				{ to: 'e8', promotedTo: ['bishop', 'queen'] },
+				{ to: 'd8', promotedTo: ['rook', 'knight', 'queen'] }
+			];
+		if (source === 'f7')
+			return [
+				{ to: 'f8', promotedTo: ['bishop', 'rook', 'knight', 'queen'] },
+				{ to: 'g8', promotedTo: ['bishop', 'rook', 'knight', 'queen'] }
+			];
+		if (source === 'd7')
+			return [
+				{ to: 'd1', promotedTo: ['bishop', 'knight'] },
+				{ to: 'e1', promotedTo: ['rook', 'knight', 'queen'] }
+			];
+		if (source === 'c2')
+			return [
+				{ to: 'c1', promotedTo: ['bishop', 'rook', 'knight', 'queen'] },
+				{ to: 'b1', promotedTo: ['bishop', 'rook', 'knight', 'queen'] }
+			];
+		return undefined;
+	}
+});
+```
+
+## Promotion and auto-promotion
 
-### Chessnut piece set
+Promotion is handled inside the board interaction pipeline through a natural deferred move flow.
 
-This project uses the Chessnut chess piece set.
+That means the board does not need the awkward pattern of:
 
-This is the current default piece set used by the library.
+- reject move
+- open external dialog
+- replay the move later
 
-- Author: Alexis Luengas — https://github.com/LexLuengas
-- Source: https://github.com/LexLuengas/chessnut-pieces
-- License: Apache License 2.0 — https://github.com/LexLuengas/chessnut-pieces/blob/master/LICENSE.txt
+Instead:
 
-For details, see:
+- `promotion` provides the built-in promotion chooser UI
+- `autoPromote` provides behavior-only auto-promotion logic
 
-- [./assets/pieces/chessnut/ATTRIBUTION.md](./assets/pieces/chessnut/ATTRIBUTION.md)
-- [./assets/pieces/chessnut/LICENSE.txt](./assets/pieces/chessnut/LICENSE.txt)
+These are separate extensions on purpose:
+
+- `promotion` is UI
+- `autoPromote` is behavior
+
+This separation is a good example of the architecture: common chess UX can be built in without collapsing everything into one hardcoded board layer.
+
+## Architecture
+
+`@mirasen/chessboard` is built around explicit boundaries:
+
+- runtime owns board, interaction, and update semantics
+- renderer owns SVG structure and visual layers
+- animation owns transition planning and temporary visual occupancy
+- extensions render through declared slots instead of ad hoc DOM access
+
+The goal is to make common chess interaction powerful without making the system brittle.
+
+## Not just a primitive, not a monolith
+
+The project is intentionally positioned between two weak extremes:
+
+### Primitive-only board
+
+A board that only renders pieces and leaves everything else to app code often forces consumers to rebuild the same interaction UX repeatedly.
+
+### Hardcoded monolith
+
+A board that handles everything internally without clean boundaries becomes difficult to evolve, customize, or extend.
+
+`@mirasen/chessboard` aims for a middle path:
+
+- strong built-in baseline interaction
+- clean internal architecture
+- extension-driven feature growth
+
+## Status
 
-## Versioning note
+Release candidate for version `1.0.0`, focused on a strong built-in interaction baseline and extension-driven architecture.
 
-`0.1.x` is an early public package release.
+## Roadmap after RC
 
-It exists so the package can be installed, explored, integrated experimentally, and published publicly while the library continues moving toward a more complete `1.0.0`.
+After the first release candidate, the next steps are expected to include:
 
-Breaking changes are still possible before `1.0.0`.
+- remaining test hardening
+- documentation expansion
+- more examples
+- further polish toward final `1.0.0`
 
-## License
+## Project direction
 
-MIT
+This platform is being built as a foundation for richer chess learning and interaction workflows, but the board itself is designed to stand as a serious open-source UI platform in its own right.

package/dist/animation/planner.d.ts

@@ -1,6 +1,11 @@
-import { Square } from '../state/board/types/internal';
-import { BoardStateSnapshot } from '../state/board/types/main';
-import { AnimationPlan, AnimationTrack, CalculateAnimationTracksOptions } from './types';
-export declare function collectSuppressedSquares(tracks: AnimationTrack[]): ReadonlySet<Square>;
-export declare function calculateAnimationTracks(pos1: BoardStateSnapshot, pos2: BoardStateSnapshot, options?: CalculateAnimationTracksOptions): AnimationTrack[];
-export declare function calculateAnimationPlan(pos1: BoardStateSnapshot, pos2: BoardStateSnapshot, sessionId: number, options?: CalculateAnimationTracksOptions): AnimationPlan;
+import type { AnimationPlan, AnimationPlanningInput } from './types.js';
+/**
+ * Plan animation tracks and suppressed squares for a state transition.
+ *
+ * This is the single entry point for animation planning.  It:
+ * 1. Normalizes both snapshots (incorporates deferredUIMoveRequest).
+ * 2. Detects lifted-piece-drag drop completion and builds an internal exclude.
+ * 3. Computes tracks via greedy min-distance matching.
+ * 4. Assembles the full suppressedSquares set (track-derived + excluded drop endpoints).
+ */
+export declare function calculateAnimationPlan(input: AnimationPlanningInput): AnimationPlan;

package/dist/animation/planner.js

@@ -1,9 +1,11 @@
-import { isNonEmptyPieceCode } from '../state/board/check';
-import { fileOf, rankOf } from '../state/board/coords';
-import { SQUARE_COUNT } from '../state/board/types/internal';
-import { isMoveExclude, isSquareExclude } from './types';
+import assert from '@ktarmyshov/assert';
+import { isNonEmptyPieceCode } from '../state/board/check.js';
+import { fileOf, rankOf } from '../state/board/coords.js';
+import { SQUARE_COUNT } from '../state/board/types/internal.js';
+// ---------------------------------------------------------------------------
 // Precomputed squared distance: (dFile² + dRank²) for all square pairs.
-// Max value = 7² + 7² = 98, fits in Uint8. Index: a * 64 + b.
+// Max value = 7² + 7² = 98, fits in Uint8.  Index: a * 64 + b.
+// ---------------------------------------------------------------------------
 const SQUARE_DIST = new Uint8Array(SQUARE_COUNT * SQUARE_COUNT);
 for (let a = 0; a < SQUARE_COUNT; a++) {
     for (let b = 0; b < SQUARE_COUNT; b++) {
@@ -12,7 +14,107 @@ for (let a = 0; a < SQUARE_COUNT; a++) {
         SQUARE_DIST[a * SQUARE_COUNT + b] = df * df + dr * dr;
     }
 }
-export function collectSuppressedSquares(tracks) {
+const EMPTY_EXCLUDE = {
+    move: new Map(),
+    square: new Set()
+};
+/**
+ * Detect whether a lifted-piece-drag was just completed (dropped).
+ *
+ * Condition:
+ * - previous snapshot had an active lifted-piece-drag session
+ * - current snapshot has no drag session
+ * - current snapshot has a lastMove
+ *
+ * Returns the lastMove when the condition holds, otherwise null.
+ */
+function detectLiftedPieceDrop(previous, current) {
+    const prevDrag = previous.interaction.dragSession;
+    if (!prevDrag || prevDrag.type !== 'lifted-piece-drag')
+        return null;
+    if (current.interaction.dragSession !== null)
+        return null;
+    return current.change.lastMove ?? null;
+}
+/**
+ * Build an ExcludeSpec that suppresses the move track and both endpoint
+ * fades for a given lastMove (used when a lifted-piece drop is detected).
+ */
+function buildExcludeForDrop(lastMove) {
+    const moveMap = new Map();
+    moveMap.set(lastMove.from, new Set([lastMove.to]));
+    const squareSet = new Set([lastMove.from, lastMove.to]);
+    return { move: moveMap, square: squareSet };
+}
+/**
+ * Normalize a snapshot by incorporating a pending deferredUIMoveRequest
+ * into the board and lastMove.  Currently limited to pawn moves.
+ *
+ * If there is no deferred request the snapshot is returned as-is.
+ */
+function buildEffectiveAnimationPlanningSnapshot(state) {
+    const request = state.change.deferredUIMoveRequest;
+    if (request === null)
+        return state; // nothing to do
+    const newPieces = new Uint8Array(state.board.pieces);
+    const from = request.sourceSquare;
+    const to = request.destination.to;
+    const pieceCode = state.board.pieces[from];
+    assert(pieceCode === 1 /* PieceCode.WhitePawn */ || pieceCode === 9 /* PieceCode.BlackPawn */, 'Only pawn moves should be deferred UI move requests at this time');
+    newPieces[to] = pieceCode;
+    newPieces[from] = 0 /* PieceCode.Empty */;
+    const newBoard = {
+        ...state.board,
+        pieces: newPieces
+    };
+    const newLastMove = {
+        from,
+        to,
+        piece: pieceCode
+    };
+    const newChange = {
+        deferredUIMoveRequest: null,
+        lastMove: newLastMove
+    };
+    return {
+        ...state,
+        board: newBoard,
+        change: newChange
+    };
+}
+/**
+ * When a promotion was already auto-resolved/auto-promoted (no deferredUIMoveRequest but
+ * lastMove.promotedTo is set), the current board already contains the promoted
+ * piece (e.g. queen) on the target square.  For animation planning we
+ * temporarily replace it with the original piece (pawn) so that the greedy
+ * matching can build a proper move track from→to instead of separate fades.
+ *
+ * After the animation finishes the promoted piece will "snap" into view on
+ * the next render frame.
+ */
+function buildPromotionEffectiveCurrent(state) {
+    const lastMove = state.change.lastMove;
+    if (state.change.deferredUIMoveRequest !== null ||
+        lastMove === null ||
+        lastMove.promotedTo === undefined) {
+        return state; // not an auto-resolved/auto-promoted move — nothing to do
+    }
+    const newPieces = new Uint8Array(state.board.pieces);
+    newPieces[lastMove.to] = lastMove.piece;
+    const newBoard = {
+        ...state.board,
+        pieces: newPieces
+    };
+    return {
+        ...state,
+        board: newBoard
+    };
+}
+/**
+ * Collect suppressed squares purely from the given tracks.
+ * For move tracks both endpoints are included; for fade/static the single square.
+ */
+function collectSuppressedSquaresFromTracks(tracks) {
     const result = new Set();
     for (const track of tracks) {
         if (track.effect === 'move') {
@@ -25,14 +127,20 @@ export function collectSuppressedSquares(tracks) {
     }
     return result;
 }
-export function calculateAnimationTracks(pos1, pos2, options) {
+/**
+ * Low-level track calculation.
+ *
+ * Compares two board snapshots (already derived / effective), applies the
+ * provided exclude spec, and returns the resulting animation tracks.
+ */
+function calculateTracks(prevBoard, currBoard, exclude) {
     const tracks = [];
     let nextId = 0;
     const removed = [];
     const added = [];
     for (let sq = 0; sq < SQUARE_COUNT; sq++) {
-        const c1 = pos1.pieces[sq];
-        const c2 = pos2.pieces[sq];
+        const c1 = prevBoard.pieces[sq];
+        const c2 = currBoard.pieces[sq];
         if (c1 === c2)
             continue;
         if (isNonEmptyPieceCode(c1))
@@ -43,29 +151,29 @@ export function calculateAnimationTracks(pos1, pos2, options) {
     // Step 2: greedy min-distance matching of same-code pairs → move tracks
     const removedMatched = new Uint8Array(removed.length);
     const addedMatched = new Uint8Array(added.length);
-    // toSq → code of the piece that moved there (used for static detection)
-    const movedToSqCode = new Map();
     const candidates = [];
     for (let ri = 0; ri < removed.length; ri++) {
         for (let ai = 0; ai < added.length; ai++) {
             if (removed[ri].pieceCode !== added[ai].pieceCode)
                 continue;
-            candidates.push({ dist: SQUARE_DIST[removed[ri].sq * SQUARE_COUNT + added[ai].sq], ri, ai });
+            candidates.push({
+                dist: SQUARE_DIST[removed[ri].sq * SQUARE_COUNT + added[ai].sq],
+                ri,
+                ai
+            });
         }
     }
     candidates.sort((a, b) => a.dist - b.dist);
-    const excl = options?.exclude;
-    const preparedExcl = prepareExclude(excl);
     for (const { ri, ai } of candidates) {
         if (removedMatched[ri] || addedMatched[ai])
             continue;
         removedMatched[ri] = 1;
         addedMatched[ai] = 1;
-        movedToSqCode.set(added[ai].sq, removed[ri].pieceCode);
-        if (excl &&
-            preparedExcl.move.has(removed[ri].sq) &&
-            preparedExcl.move.get(removed[ri].sq).has(added[ai].sq)) {
-            // Suppress this move track but keep both squares matched so they don't become fades.
+        // Check if this move pair is excluded (e.g. lifted-piece drop)
+        const fromSet = exclude.move.get(removed[ri].sq);
+        if (fromSet && fromSet.has(added[ai].sq)) {
+            // Suppress the move track but keep both entries matched so they
+            // don't turn into fades.
             continue;
         }
         tracks.push({
@@ -80,9 +188,8 @@ export function calculateAnimationTracks(pos1, pos2, options) {
     for (let ai = 0; ai < added.length; ai++) {
         if (addedMatched[ai])
             continue;
-        if (preparedExcl.square.has(added[ai].sq)) {
+        if (exclude.square.has(added[ai].sq))
             continue;
-        }
         tracks.push({
             id: nextId++,
             pieceCode: added[ai].pieceCode,
@@ -90,39 +197,51 @@ export function calculateAnimationTracks(pos1, pos2, options) {
             effect: 'fade-in'
         });
     }
-    // Step 4: unmatched removed → fade-out or static
+    // Step 4: unmatched removed → fade-out
     for (let ri = 0; ri < removed.length; ri++) {
         if (removedMatched[ri])
             continue;
-        if (preparedExcl.square.has(removed[ri].sq)) {
+        if (exclude.square.has(removed[ri].sq))
             continue;
-        }
-        const { pieceCode: code, sq } = removed[ri];
-        /*const movedCode = movedToSqCode.get(sq);
-        const isCapture =
-            movedCode !== undefined && fromPieceCode(code).color !== fromPieceCode(movedCode).color;*/
-        const pieceCode = code;
-        tracks.push({ id: nextId++, pieceCode, sq, effect: 'fade-out' });
+        tracks.push({
+            id: nextId++,
+            pieceCode: removed[ri].pieceCode,
+            sq: removed[ri].sq,
+            effect: 'fade-out'
+        });
     }
     return tracks;
 }
-export function calculateAnimationPlan(pos1, pos2, sessionId, options) {
-    return { sessionId, tracks: calculateAnimationTracks(pos1, pos2, options) };
-}
-function prepareExclude(exclude) {
-    const result = { move: new Map(), square: new Set() };
-    if (!exclude)
-        return result;
-    for (const e of exclude) {
-        if (isMoveExclude(e)) {
-            if (!result.move.has(e.fromSq)) {
-                result.move.set(e.fromSq, new Set());
-            }
-            result.move.get(e.fromSq).add(e.toSq);
-        }
-        else if (isSquareExclude(e)) {
-            result.square.add(e.sq);
-        }
+// ---------------------------------------------------------------------------
+// Public API — single orchestrator
+// ---------------------------------------------------------------------------
+/**
+ * Plan animation tracks and suppressed squares for a state transition.
+ *
+ * This is the single entry point for animation planning.  It:
+ * 1. Normalizes both snapshots (incorporates deferredUIMoveRequest).
+ * 2. Detects lifted-piece-drag drop completion and builds an internal exclude.
+ * 3. Computes tracks via greedy min-distance matching.
+ * 4. Assembles the full suppressedSquares set (track-derived + excluded drop endpoints).
+ */
+export function calculateAnimationPlan(input) {
+    // 1) Normalize snapshots to account for deferredUIMoveRequest
+    const effectivePrevious = buildEffectiveAnimationPlanningSnapshot(input.previous);
+    const effectiveCurrent = buildEffectiveAnimationPlanningSnapshot(input.current);
+    // 2) Detect lifted-piece drop and prepare exclude spec
+    const droppedMove = detectLiftedPieceDrop(effectivePrevious, effectiveCurrent);
+    const exclude = droppedMove !== null ? buildExcludeForDrop(droppedMove) : EMPTY_EXCLUDE;
+    // 3) Normalize current for auto-resolved/auto-promoted move (pawn→queen on target square)
+    const planningCurrent = buildPromotionEffectiveCurrent(effectiveCurrent);
+    // 4) Calculate tracks
+    const tracks = calculateTracks(effectivePrevious.board, planningCurrent.board, exclude);
+    // 5) Build suppressedSquares: track-derived + excluded drop endpoints
+    const suppressed = collectSuppressedSquaresFromTracks(tracks);
+    if (droppedMove !== null) {
+        // The dropped move was intentionally suppressed (no move track emitted),
+        // but the base render must still hide both endpoints.
+        suppressed.add(droppedMove.from);
+        suppressed.add(droppedMove.to);
     }
-    return result;
+    return { tracks, suppressedSquares: suppressed };
 }

package/dist/animation/render/fade.d.ts

@@ -1,7 +1,7 @@
-import type { PieceUrls } from '../../extensions/first-party/main-renderer/types/internal';
-import type { RenderGeometry } from '../../layout/geometry/types';
-import type { AnimationTrackFade } from '../types';
-import type { PreparedFadeNode } from './types';
-export declare function prepareFadeTrack(track: AnimationTrackFade, geometry: RenderGeometry, pieceUrls: PieceUrls, layer: SVGElement): PreparedFadeNode;
+import type { PieceUrls } from '../../extensions/first-party/main-renderer/types/internal.js';
+import type { SceneRenderGeometry } from '../../layout/geometry/types.js';
+import type { AnimationTrackFade } from '../types.js';
+import type { PreparedFadeNode } from './types.js';
+export declare function prepareFadeTrack(track: AnimationTrackFade, geometry: SceneRenderGeometry, pieceUrls: PieceUrls, layer: SVGElement): PreparedFadeNode;
 export declare function renderFadeTrack(node: PreparedFadeNode, progress: number): void;
 export declare function cleanFadeTrack(node: PreparedFadeNode): void;

package/dist/animation/render/fade.js

@@ -1,6 +1,6 @@
-import { createSvgElement, updateElementAttributes } from '../../render/svg/helpers';
+import { createSvgElement, updateElementAttributes } from '../../render/svg/helpers.js';
 export function prepareFadeTrack(track, geometry, pieceUrls, layer) {
-    const r = geometry.squareRect(track.sq);
+    const r = geometry.getSquareRect(track.sq);
     const url = pieceUrls[track.pieceCode];
     const initialOpacity = track.effect === 'fade-in' ? '0' : '1';
     const root = createSvgElement(layer, 'image', {
@@ -9,8 +9,8 @@ export function prepareFadeTrack(track, geometry, pieceUrls, layer) {
         href: url,
         x: r.x.toString(),
         y: r.y.toString(),
-        width: r.size.toString(),
-        height: r.size.toString(),
+        width: r.width.toString(),
+        height: r.height.toString(),
         opacity: initialOpacity
     });
     return { ...track, root };