@ue-too/board 0.9.5 → 0.11.0

package/utils/coordinate-conversions/viewport-world.d.ts

@@ -0,0 +1,101 @@
+import { Point } from "@ue-too/math";
+/**
+ * Converts a point from viewport space to world space.
+ *
+ * @param pointInViewport - The point in viewport coordinates to convert
+ * @param cameraPositionInWorldSpace - The camera's center position in world coordinates
+ * @param cameraZoomLevel - The camera's zoom level (1.0 = normal, >1 = zoomed in, <1 = zoomed out)
+ * @param cameraRotation - The camera's rotation angle in radians
+ * @param worldHasFlippedYAxis - Whether world space uses inverted y-axis (default: false)
+ * @returns The point in world coordinates
+ *
+ * @remarks
+ * This function applies the inverse of the camera transformation to convert from
+ * viewport coordinates to world coordinates. It's essential for translating user
+ * interactions (clicks, drags) into world-space positions.
+ *
+ * The transformation applies these operations in reverse order:
+ * 1. Unzoom: Divide by zoom level (world units per viewport pixel)
+ * 2. Unrotate: Rotate by positive camera rotation (reverse the camera's rotation)
+ * 3. Flip Y (if needed): Negate y if world uses mathematical coordinates
+ * 4. Translate: Add camera position to get absolute world position
+ *
+ * Mathematical formula:
+ * ```
+ * worldPoint = rotate(pointInViewport / zoom, cameraRotation) + cameraPosition
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Click at viewport center with zoomed and rotated camera
+ * const viewportPoint = { x: 0, y: 0 };  // Center of viewport
+ * const cameraPos = { x: 1000, y: 500 };
+ * const zoom = 2.0;  // Zoomed in 2x
+ * const rotation = Math.PI / 4;  // 45 degrees
+ *
+ * const worldPoint = convertFromViewport2World(
+ *   viewportPoint,
+ *   cameraPos,
+ *   zoom,
+ *   rotation,
+ *   false
+ * );
+ * // Result: { x: 1000, y: 500 } (camera position, since viewport center maps to camera position)
+ * ```
+ *
+ * @category Coordinate Conversion
+ * @see {@link convertFromWorld2Viewport} for inverse conversion
+ */
+export declare function convertFromViewport2World(pointInViewport: Point, cameraPositionInWorldSpace: Point, cameraZoomLevel: number, cameraRotation: number, worldHasFlippedYAxis?: boolean): Point;
+/**
+ * Converts a point from world space to viewport space.
+ *
+ * @param pointInWorld - The point in world coordinates to convert
+ * @param cameraPositionInWorldSpace - The camera's center position in world coordinates
+ * @param cameraZoomLevel - The camera's zoom level (1.0 = normal, >1 = zoomed in, <1 = zoomed out)
+ * @param cameraRotation - The camera's rotation angle in radians
+ * @param worldHasFlippedYAxis - Whether world space uses inverted y-axis (default: false)
+ * @returns The point in viewport coordinates
+ *
+ * @remarks
+ * This function applies the camera transformation to convert from world coordinates
+ * to viewport coordinates. This is used for rendering world objects onto the viewport.
+ *
+ * The transformation applies these operations in order:
+ * 1. Translate: Subtract camera position (make position relative to camera)
+ * 2. Flip Y (if needed): Negate y if world uses mathematical coordinates
+ * 3. Zoom: Multiply by zoom level (viewport pixels per world unit)
+ * 4. Rotate: Rotate by negative camera rotation (to align with viewport)
+ *
+ * Mathematical formula:
+ * ```
+ * viewportPoint = rotate((pointInWorld - cameraPosition) * zoom, -cameraRotation)
+ * ```
+ *
+ * The negative rotation ensures that when the camera rotates clockwise, the world
+ * appears to rotate counter-clockwise (from the viewer's perspective), which is
+ * the expected behavior.
+ *
+ * @example
+ * ```typescript
+ * // World object at (1100, 550) with camera at (1000, 500)
+ * const worldPoint = { x: 1100, y: 550 };
+ * const cameraPos = { x: 1000, y: 500 };
+ * const zoom = 2.0;  // Zoomed in 2x
+ * const rotation = 0;  // No rotation
+ *
+ * const viewportPoint = convertFromWorld2Viewport(
+ *   worldPoint,
+ *   cameraPos,
+ *   zoom,
+ *   rotation,
+ *   false
+ * );
+ * // Result: { x: 200, y: 100 }
+ * // ((1100 - 1000) * 2 = 200, (550 - 500) * 2 = 100)
+ * ```
+ *
+ * @category Coordinate Conversion
+ * @see {@link convertFromViewport2World} for inverse conversion
+ */
+export declare function convertFromWorld2Viewport(pointInWorld: Point, cameraPositionInWorldSpace: Point, cameraZoomLevel: number, cameraRotation: number, worldHasFlippedYAxis?: boolean): Point;

package/utils/coordinate-conversions/window-canvas.d.ts

@@ -0,0 +1,90 @@
+import { Point } from "@ue-too/math";
+import { Canvas } from "../../input-interpretation/input-state-machine/kmt-input-context";
+/**
+ * Converts a point from browser window coordinates to canvas coordinates.
+ *
+ * @param pointInWindow - The point in window coordinates (relative to browser viewport)
+ * @param canvas - The canvas object containing position information
+ * @returns The point in canvas coordinates (relative to canvas element)
+ *
+ * @remarks
+ * Window coordinates are relative to the browser's viewport (top-left = 0,0).
+ * Canvas coordinates are relative to the canvas element's top-left corner.
+ *
+ * This conversion is essential for processing mouse and touch events, which
+ * provide coordinates relative to the window, not the canvas element.
+ *
+ * The conversion simply subtracts the canvas position from the window position:
+ * ```
+ * canvasPoint = windowPoint - canvasPosition
+ * ```
+ *
+ * Note: This function expects the canvas object to have a `position` property
+ * containing the canvas element's position in window coordinates (typically
+ * from getBoundingClientRect()).
+ *
+ * @example
+ * ```typescript
+ * // Mouse click at window position (500, 300)
+ * const clickPos = { x: 500, y: 300 };
+ *
+ * // Canvas positioned at (100, 50) in window
+ * const canvas = {
+ *   position: { x: 100, y: 50 },
+ *   width: 800,
+ *   height: 600
+ * };
+ *
+ * const canvasPos = convertFromWindow2Canvas(clickPos, canvas);
+ * // Result: { x: 400, y: 250 }
+ * // (500 - 100 = 400, 300 - 50 = 250)
+ * ```
+ *
+ * @category Coordinate Conversion
+ * @see {@link convertFromCanvas2Window} for inverse conversion
+ */
+export declare function convertFromWindow2Canvas(pointInWindow: Point, canvas: Canvas): Point;
+/**
+ * Converts a point from canvas coordinates to browser window coordinates.
+ *
+ * @param pointInCanvas - The point in canvas coordinates (relative to canvas element)
+ * @param canvas - The canvas object containing position information
+ * @returns The point in window coordinates (relative to browser viewport)
+ *
+ * @remarks
+ * This is the inverse of {@link convertFromWindow2Canvas}. It translates canvas-relative
+ * coordinates to window-relative coordinates.
+ *
+ * The conversion adds the canvas position to the canvas-relative point:
+ * ```
+ * windowPoint = canvasPoint + canvasPosition
+ * ```
+ *
+ * This is useful for positioning DOM elements (like tooltips or menus) at specific
+ * canvas coordinates, as DOM elements use window coordinates.
+ *
+ * @example
+ * ```typescript
+ * // Point on canvas at (400, 250)
+ * const canvasPos = { x: 400, y: 250 };
+ *
+ * // Canvas positioned at (100, 50) in window
+ * const canvas = {
+ *   position: { x: 100, y: 50 },
+ *   width: 800,
+ *   height: 600
+ * };
+ *
+ * const windowPos = convertFromCanvas2Window(canvasPos, canvas);
+ * // Result: { x: 500, y: 300 }
+ * // (400 + 100 = 500, 250 + 50 = 300)
+ *
+ * // Use for positioning a tooltip
+ * tooltip.style.left = `${windowPos.x}px`;
+ * tooltip.style.top = `${windowPos.y}px`;
+ * ```
+ *
+ * @category Coordinate Conversion
+ * @see {@link convertFromWindow2Canvas} for inverse conversion
+ */
+export declare function convertFromCanvas2Window(pointInCanvas: Point, canvas: Canvas): Point;

package/utils/coorindate-conversion.d.ts

@@ -1,5 +1,96 @@
 import { Point } from "@ue-too/math";
+import { Canvas } from "../input-interpretation/input-state-machine/kmt-input-context";
+/**
+ * Converts an isometric 3D point to a flat 2D world point.
+ *
+ * @param point - The 3D point in isometric space (with optional z coordinate)
+ * @returns The 2D point in flat world coordinates
+ *
+ * @remarks
+ * This function performs an isometric projection transformation, converting 3D
+ * coordinates to 2D using standard isometric angles (30 degrees).
+ *
+ * The transformation uses:
+ * - cos(30°) ≈ 0.866 for x-axis projection
+ * - cos(60°) = 0.5 for y-axis projection
+ * - Z-coordinate is added directly to the y-axis (height)
+ *
+ * Mathematical formulas:
+ * ```
+ * x_2d = (x_3d * cos30) - (y_3d * cos30)
+ * y_2d = (x_3d * cos60) + (y_3d * cos60) + z_3d
+ * ```
+ *
+ * This creates the classic isometric diamond grid appearance where:
+ * - Moving along +X goes down-right
+ * - Moving along +Y goes down-left
+ * - Moving along +Z goes straight up
+ *
+ * @example
+ * ```typescript
+ * // Convert a 3D cube corner to 2D isometric projection
+ * const point3D = { x: 10, y: 10, z: 5 };
+ * const point2D = pointConversion(point3D);
+ * // Result: { x: 0, y: 15 }
+ * // x: (10 * 0.866) - (10 * 0.866) = 0
+ * // y: (10 * 0.5) + (10 * 0.5) + 5 = 15
+ *
+ * // 2D point without z-coordinate
+ * const flatPoint = { x: 20, y: 0 };
+ * const projected = pointConversion(flatPoint);
+ * // Result: { x: 17.32, y: 10 }
+ * ```
+ *
+ * @category Coordinate Conversion
+ */
 export declare function pointConversion(point: Point): {
     x: number;
     y: number;
 };
+/**
+ * Converts a point from window coordinates to viewport coordinates in one step.
+ *
+ * @param point - The point in window coordinates (browser viewport)
+ * @param canvas - The canvas object with position and dimensions
+ * @param viewportOriginInCanvasSpace - Viewport origin in canvas space (default: canvas center)
+ * @param viewportHasFlippedYAxis - Whether viewport uses mathematical y-axis (default: false)
+ * @returns The point in viewport coordinates
+ *
+ * @remarks
+ * This is a convenience function that combines two conversions:
+ * 1. Window to Canvas: {@link convertFromWindow2Canvas}
+ * 2. Canvas to Viewport: {@link convertFromCanvas2ViewPort}
+ *
+ * It's particularly useful for processing input events (mouse clicks, touches)
+ * that need to be converted directly to viewport space for interaction handling.
+ *
+ * The default viewport origin is the canvas center, which is common for
+ * mathematical/engineering applications where (0,0) should be in the middle.
+ *
+ * @example
+ * ```typescript
+ * // Mouse click event
+ * const clickPos = { x: event.clientX, y: event.clientY };
+ *
+ * const canvas = {
+ *   position: { x: 100, y: 50 },
+ *   width: 800,
+ *   height: 600
+ * };
+ *
+ * // Convert to centered viewport with y-up
+ * const viewportPos = convertFromWindow2ViewPortWithCanvasOperator(
+ *   clickPos,
+ *   canvas,
+ *   { x: 400, y: 300 },  // center of canvas
+ *   true  // mathematical coordinates
+ * );
+ *
+ * // viewportPos is now relative to viewport center with y-up
+ * ```
+ *
+ * @category Coordinate Conversion
+ * @see {@link convertFromWindow2Canvas} for window to canvas conversion
+ * @see {@link convertFromCanvas2ViewPort} for canvas to viewport conversion
+ */
+export declare function convertFromWindow2ViewPortWithCanvasOperator(point: Point, canvas: Canvas, viewportOriginInCanvasSpace?: Point, viewportHasFlippedYAxis?: boolean): Point;

package/utils/drawing.d.ts

@@ -1,20 +1,168 @@
 import { Point } from "@ue-too/math";
+/**
+ * Draws an arrow from start to end point with an arrowhead.
+ *
+ * @param context - The canvas 2D rendering context
+ * @param cameraZoomLevel - Current camera zoom level for scale-independent sizing
+ * @param startPoint - Arrow tail position in world coordinates
+ * @param endPoint - Arrow head position in world coordinates
+ * @param width - Line width in world units (default: 1)
+ * @param arrowRatio - Ratio of arrowhead size to total length (default: 0.3, unused in implementation)
+ *
+ * @remarks
+ * The arrow consists of a line segment and a triangular arrowhead. The arrowhead
+ * size is adaptive:
+ * - Maximum 10 pixels in viewport space
+ * - Minimum half the arrow length
+ *
+ * This ensures arrows look good at all zoom levels and lengths.
+ *
+ * The arrowhead is constructed perpendicular to the arrow direction, creating
+ * a filled triangle at the end point.
+ *
+ * @example
+ * ```typescript
+ * const ctx = canvas.getContext('2d');
+ * const zoom = 1.5;
+ *
+ * // Draw a simple arrow
+ * ctx.fillStyle = 'blue';
+ * ctx.strokeStyle = 'blue';
+ * drawArrow(ctx, zoom, { x: 0, y: 0 }, { x: 100, y: 50 });
+ *
+ * // Draw a thicker arrow
+ * ctx.fillStyle = 'red';
+ * ctx.strokeStyle = 'red';
+ * drawArrow(ctx, zoom, { x: 0, y: 0 }, { x: 100, y: -50 }, 3);
+ * ```
+ *
+ * @category Drawing Utilities
+ */
 export declare function drawArrow(context: CanvasRenderingContext2D, cameraZoomLevel: number, startPoint: Point, endPoint: Point, width?: number, arrowRatio?: number): void;
+/**
+ * Length of major tick marks in pixels (viewport space).
+ * @category Drawing Utilities
+ */
 export declare const MAJOR_TICK_LENGTH = 30;
+/**
+ * Length of minor tick marks in pixels (viewport space).
+ * @category Drawing Utilities
+ */
 export declare const MINOR_TICK_LENGTH: number;
+/**
+ * Length of half-step tick marks in pixels (viewport space).
+ * @category Drawing Utilities
+ */
 export declare const HALF_TICK_LENGTH: number;
+/**
+ * Offset for major tick labels in pixels (viewport space).
+ * @category Drawing Utilities
+ */
 export declare const TEXT_MAJOR_TICK_OFFSET = 10;
+/**
+ * Offset for half-step tick labels in pixels (viewport space).
+ * @category Drawing Utilities
+ */
 export declare const TEXT_HALF_TICK_OFFSET = 2.5;
+/**
+ * Font size for major tick labels in pixels (viewport space).
+ * @category Drawing Utilities
+ */
 export declare const TEXT_MAJOR_TICK_FONT_SIZE = 20;
+/**
+ * Font size for half-step tick labels in pixels (viewport space).
+ * @category Drawing Utilities
+ */
 export declare const TEXT_HALF_TICK_FONT_SIZE = 10;
 /**
- * @description Draws a ruler on the canvas.
- * argument points are in world space
+ * Draws calibrated rulers along the edges of the viewport.
+ *
+ * @param context - The canvas 2D rendering context
+ * @param topLeftCorner - Top-left corner of viewport in world coordinates
+ * @param topRightCorner - Top-right corner of viewport in world coordinates
+ * @param bottomLeftCorner - Bottom-left corner of viewport in world coordinates
+ * @param alignCoordinateSystem - Whether coordinates align with canvas (y-down) or are mathematical (y-up)
+ * @param cameraZoomLevel - Current camera zoom level
+ *
+ * @remarks
+ * This function draws rulers with three levels of tick marks:
+ * - Major ticks: At powers of 10 (1, 10, 100, etc.) with large labels
+ * - Half ticks: At half-steps (5, 50, 500, etc.) with small labels
+ * - Minor ticks: At 1/10 steps with no labels
+ *
+ * The ruler automatically adapts to the zoom level by calculating appropriate
+ * tick spacing using {@link calculateOrderOfMagnitude} and {@link calculateTickValues}.
+ *
+ * Rulers are drawn along:
+ * - Top edge (horizontal ruler, red)
+ * - Left edge (vertical ruler, green)
+ *
+ * Tick positions are calibrated to align with round numbers in world space,
+ * making it easy to read coordinates at any zoom level.
+ *
+ * @example
+ * ```typescript
+ * const ctx = canvas.getContext('2d');
+ * const zoom = 2.0;
+ *
+ * // Viewport corners in world space
+ * const topLeft = { x: -100, y: 100 };
+ * const topRight = { x: 100, y: 100 };
+ * const bottomLeft = { x: -100, y: -100 };
  *
- * @category Utils
+ * drawRuler(ctx, topLeft, topRight, bottomLeft, false, zoom);
+ * // Draws rulers with ticks at -100, -50, 0, 50, 100
+ * ```
  *
+ * @category Drawing Utilities
+ * @see {@link calculateTickValues} for tick calculation logic
+ * @see {@link calculateOrderOfMagnitude} for order of magnitude calculation
  */
 export declare function drawRuler(context: CanvasRenderingContext2D, topLeftCorner: Point, topRightCorner: Point, bottomLeftCorner: Point, alignCoordinateSystem: boolean, cameraZoomLevel: number): void;
+/**
+ * Calculates tick mark positions and spacing for a ruler.
+ *
+ * @param minValue - Minimum value on the ruler axis
+ * @param maxValue - Maximum value on the ruler axis
+ * @param orderOfMagnitude - Optional pre-calculated order of magnitude (for consistency across axes)
+ * @returns Object containing tick positions and spacing for major, half, and minor ticks
+ *
+ * @remarks
+ * This function determines where to place tick marks on a ruler to show round
+ * numbers at appropriate intervals. It calculates three levels of ticks:
+ *
+ * 1. Major ticks: At powers of 10 (step = 10^n)
+ * 2. Half ticks: At half the major step (step = 5×10^(n-1))
+ * 3. Minor ticks: At 1/10 the major step (step = 10^(n-1))
+ *
+ * The calibration multiplier handles cases where the order of magnitude is very
+ * small (< 1), ensuring tick positions are calculated correctly for zoomed-in views.
+ *
+ * For consistency between x and y axes, you can provide a pre-calculated
+ * orderOfMagnitude. Otherwise, it's calculated from the range width.
+ *
+ * @example
+ * ```typescript
+ * // Ruler showing -100 to 100
+ * const ticks = calculateTickValues(-100, 100);
+ * // Result:
+ * // majorTickStep: 100
+ * // minMajorTickValue: -100, maxMajorTickValue: 100
+ * // halfTickStep: 50
+ * // minorTickStep: 10
+ * // calibrationMultiplier: 1
+ *
+ * // Zoomed in view: 0.001 to 0.01
+ * const zoomedTicks = calculateTickValues(0.001, 0.01);
+ * // Result:
+ * // majorTickStep: 10 (calibrated)
+ * // calibrationMultiplier: 0.001 (multiply tick values by this)
+ * ```
+ *
+ * @category Drawing Utilities
+ * @see {@link calculateOrderOfMagnitude} for order calculation
+ * @see {@link drawRuler} for usage in ruler drawing
+ */
 export declare function calculateTickValues(minValue: number, maxValue: number, orderOfMagnitude?: number): {
     minMajorTickValue: number;
     maxMajorTickValue: number;

package/utils/index.d.ts

@@ -1,3 +1,24 @@
+/**
+ * Utility functions module exports.
+ *
+ * @remarks
+ * This module provides helper functions and utilities used throughout the board package.
+ * Includes coordinate conversion, drawing helpers, observable patterns, and more.
+ *
+ * ## Key Utilities
+ *
+ * - **Coordinate Conversion**: Functions for converting between coordinate systems
+ * - **Drawing Utilities**: {@link reverseYAxis} and other canvas drawing helpers
+ * - **Observable Pattern**: Simple observer implementation for state updates
+ * - **Handler Pipeline**: {@link createHandlerChain} for composing transformation functions
+ * - **Canvas Utilities**: Dimension and position helpers for canvas elements
+ * - **Zoom Level Adjustment**: Helpers for calculating and adjusting zoom levels
+ *
+ * @see {@link createHandlerChain} for creating composable function pipelines
+ * @see {@link reverseYAxis} for Y-axis coordinate system reversal
+ *
+ * @module
+ */
 export * from "./coorindate-conversion";
 export * from "./ruler";
 export * from "./observable";

package/utils/observable.d.ts

@@ -1,18 +1,197 @@
+/**
+ * Type definition for an observer callback function.
+ *
+ * @typeParam T - Tuple type of arguments passed to the observer
+ *
+ * @remarks
+ * Observers are callbacks that get notified when an Observable emits data.
+ * The generic type T is a tuple representing the arguments passed to the callback.
+ *
+ * @example
+ * ```typescript
+ * // Observer that receives a single string
+ * const stringObserver: Observer<[string]> = (message) => {
+ *   console.log(message);
+ * };
+ *
+ * // Observer that receives multiple arguments
+ * const multiObserver: Observer<[number, string, boolean]> = (num, str, flag) => {
+ *   console.log(num, str, flag);
+ * };
+ * ```
+ *
+ * @category Observable Pattern
+ */
 export type Observer<T extends any[]> = (...data: T) => void;
+/**
+ * Options for subscribing to an Observable.
+ *
+ * @property signal - Optional AbortSignal for automatic unsubscription
+ *
+ * @remarks
+ * Subscription options allow for automatic cleanup of subscriptions using
+ * the AbortController API. When the signal is aborted, the subscription
+ * is automatically removed.
+ *
+ * @example
+ * ```typescript
+ * const controller = new AbortController();
+ *
+ * observable.subscribe(
+ *   (data) => console.log(data),
+ *   { signal: controller.signal }
+ * );
+ *
+ * // Later, abort to unsubscribe
+ * controller.abort();
+ * ```
+ *
+ * @category Observable Pattern
+ */
 export interface SubscriptionOptions {
     signal?: AbortSignal;
 }
+/**
+ * Interface for the Observable pattern implementation.
+ *
+ * @typeParam T - Tuple type of data emitted to observers
+ *
+ * @remarks
+ * Observables allow multiple observers to subscribe and receive notifications
+ * when data is emitted. This is the pub-sub pattern for event handling.
+ *
+ * Implementations can be synchronous or asynchronous:
+ * - {@link SynchronousObservable}: Notifies observers immediately
+ * - {@link AsyncObservable}: Notifies observers via microtasks
+ *
+ * @category Observable Pattern
+ */
 export interface Observable<T extends any[]> {
     subscribe(observer: Observer<T>, options?: SubscriptionOptions): () => void;
     notify(...data: T): void;
 }
+/**
+ * Asynchronous Observable implementation that notifies observers via microtasks.
+ *
+ * @typeParam T - Tuple type of data emitted to observers
+ *
+ * @remarks
+ * This Observable uses `queueMicrotask` to defer observer notifications,
+ * ensuring they execute after the current execution context completes but
+ * before the next task. This prevents recursive notification issues and
+ * allows the notifier to complete before observers run.
+ *
+ * Use AsyncObservable when:
+ * - You want to prevent recursion issues in notifications
+ * - Observer execution should not block the notifier
+ * - You need guaranteed async behavior
+ *
+ * @example
+ * ```typescript
+ * const observable = new AsyncObservable<[string]>();
+ *
+ * observable.subscribe((message) => {
+ *   console.log('Observer received:', message);
+ * });
+ *
+ * console.log('Before notify');
+ * observable.notify('Hello');
+ * console.log('After notify');
+ *
+ * // Output:
+ * // Before notify
+ * // After notify
+ * // Observer received: Hello
+ * ```
+ *
+ * @category Observable Pattern
+ * @see {@link SynchronousObservable} for synchronous notifications
+ */
 export declare class AsyncObservable<T extends any[]> implements Observable<T> {
     private observers;
+    /**
+     * Subscribes an observer to receive notifications.
+     *
+     * @param observer - The callback function to be notified
+     * @param options - Optional subscription options including AbortSignal
+     * @returns Unsubscribe function to remove this observer
+     *
+     * @remarks
+     * If an AbortSignal is provided and is already aborted, the observer
+     * is not added and the returned unsubscribe function is a no-op.
+     */
     subscribe(observer: Observer<T>, options?: SubscriptionOptions): () => void;
+    /**
+     * Notifies all observers with the provided data asynchronously.
+     *
+     * @param data - The data to pass to all observers
+     *
+     * @remarks
+     * Each observer is called via `queueMicrotask`, ensuring async execution.
+     * This method returns immediately; observers run later in the event loop.
+     */
     notify(...data: T): void;
 }
+/**
+ * Synchronous Observable implementation that notifies observers immediately.
+ *
+ * @typeParam T - Tuple type of data emitted to observers
+ *
+ * @remarks
+ * This Observable calls all observers synchronously and immediately when
+ * `notify()` is called. The notify method doesn't return until all observers
+ * have executed.
+ *
+ * Use SynchronousObservable when:
+ * - You need immediate, guaranteed execution of observers
+ * - Observer execution order matters and must be predictable
+ * - You're in a performance-critical path (no async overhead)
+ *
+ * Caution: Can lead to recursion issues if observers trigger notifications.
+ *
+ * @example
+ * ```typescript
+ * const observable = new SynchronousObservable<[string]>();
+ *
+ * observable.subscribe((message) => {
+ *   console.log('Observer received:', message);
+ * });
+ *
+ * console.log('Before notify');
+ * observable.notify('Hello');
+ * console.log('After notify');
+ *
+ * // Output:
+ * // Before notify
+ * // Observer received: Hello
+ * // After notify
+ * ```
+ *
+ * @category Observable Pattern
+ * @see {@link AsyncObservable} for asynchronous notifications
+ */
 export declare class SynchronousObservable<T extends any[]> implements Observable<T> {
     private observers;
+    /**
+     * Subscribes an observer to receive notifications.
+     *
+     * @param observer - The callback function to be notified
+     * @param options - Optional subscription options including AbortSignal
+     * @returns Unsubscribe function to remove this observer
+     *
+     * @remarks
+     * If an AbortSignal is provided and is already aborted, the observer
+     * is not added and the returned unsubscribe function is a no-op.
+     */
     subscribe(observer: Observer<T>, options?: SubscriptionOptions): () => void;
+    /**
+     * Notifies all observers with the provided data synchronously.
+     *
+     * @param data - The data to pass to all observers
+     *
+     * @remarks
+     * Each observer is called immediately in order. This method blocks until
+     * all observers have completed execution.
+     */
     notify(...data: T): void;
 }