@aelionsdk/core 0.1.0-beta.1

package/LICENSE

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

package/README.md

@@ -0,0 +1,7 @@
+# @aelionsdk/core
+
+Core time, diagnostics and resource primitives for AelionSDK
+
+Install with `npm install @aelionsdk/core@next`.
+
+Version 0.1.0-beta.1 is a prerelease and its API may change before the first stable release. This package is part of [AelionSDK](https://github.com/FoyonaCZY/AelionSDK); see the repository README for supported browsers, examples and deployment requirements.

package/dist/diagnostic.d.ts

@@ -0,0 +1,33 @@
+import type { JsonValue } from './json.js';
+export type DiagnosticSeverity = 'info' | 'warning' | 'error' | 'fatal';
+export interface TimeRange {
+    readonly startUs: number;
+    readonly durationUs: number;
+}
+export interface Diagnostic {
+    readonly code: string;
+    readonly severity: DiagnosticSeverity;
+    readonly message: string;
+    readonly path?: readonly (string | number)[];
+    readonly entityId?: string;
+    readonly rangeUs?: TimeRange;
+    readonly recoverable: boolean;
+    readonly details?: Readonly<Record<string, JsonValue>>;
+    readonly cause?: unknown;
+}
+export type Result<T> = {
+    readonly ok: true;
+    readonly value: T;
+    readonly diagnostics: readonly Diagnostic[];
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly Diagnostic[];
+};
+export declare function ok<T>(value: T, diagnostics?: readonly Diagnostic[]): Result<T>;
+export declare function err<T = never>(...diagnostics: readonly Diagnostic[]): Result<T>;
+export declare class AelionError extends Error {
+    readonly diagnostics: readonly Diagnostic[];
+    constructor(diagnostics: readonly Diagnostic[]);
+}
+export declare function throwIfAborted(signal: AbortSignal | undefined, operation: string): void;
+//# sourceMappingURL=diagnostic.d.ts.map

package/dist/diagnostic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostic.d.ts","sourceRoot":"","sources":["../src/diagnostic.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;AAExE,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAC7C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;IACvD,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,MAAM,MAAM,CAAC,CAAC,IAChB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,SAAS,UAAU,EAAE,CAAA;CAAE,GACrF;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,SAAS,UAAU,EAAE,CAAA;CAAE,CAAC;AAExE,wBAAgB,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,WAAW,GAAE,SAAS,UAAU,EAAO,GAAG,MAAM,CAAC,CAAC,CAAC,CAElF;AAED,wBAAgB,GAAG,CAAC,CAAC,GAAG,KAAK,EAAE,GAAG,WAAW,EAAE,SAAS,UAAU,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,CAK/E;AAED,qBAAa,WAAY,SAAQ,KAAK;IACpC,SAAgB,WAAW,EAAE,SAAS,UAAU,EAAE,CAAC;gBAEhC,WAAW,EAAE,SAAS,UAAU,EAAE;CAMtD;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAYvF"}

package/dist/diagnostic.js

@@ -0,0 +1,32 @@
+export function ok(value, diagnostics = []) {
+    return { ok: true, value, diagnostics };
+}
+export function err(...diagnostics) {
+    if (diagnostics.length === 0) {
+        throw new TypeError('err() requires at least one diagnostic');
+    }
+    return { ok: false, diagnostics };
+}
+export class AelionError extends Error {
+    diagnostics;
+    constructor(diagnostics) {
+        const first = diagnostics[0];
+        super(first?.message ?? 'Aelion operation failed', { cause: first?.cause });
+        this.name = 'AelionError';
+        this.diagnostics = diagnostics;
+    }
+}
+export function throwIfAborted(signal, operation) {
+    if (!signal?.aborted)
+        return;
+    const reason = signal.reason;
+    throw new AelionError([
+        {
+            code: 'OPERATION_ABORTED',
+            severity: 'error',
+            message: `${operation} was aborted`,
+            recoverable: true,
+            cause: reason,
+        },
+    ]);
+}

package/dist/disposable.d.ts

@@ -0,0 +1,12 @@
+export interface Disposable {
+    readonly disposed: boolean;
+    dispose(): void | Promise<void>;
+}
+export declare class DisposableStack implements Disposable {
+    #private;
+    get disposed(): boolean;
+    use<T extends Disposable>(value: T): T;
+    defer(callback: () => void | Promise<void>): void;
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=disposable.d.ts.map

package/dist/disposable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"disposable.d.ts","sourceRoot":"","sources":["../src/disposable.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,OAAO,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjC;AAED,qBAAa,eAAgB,YAAW,UAAU;;IAKhD,IAAW,QAAQ,IAAI,OAAO,CAE7B;IAEM,GAAG,CAAC,CAAC,SAAS,UAAU,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC;IAQtC,KAAK,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAOjD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAsBhC"}

package/dist/disposable.js

@@ -0,0 +1,41 @@
+export class DisposableStack {
+    #entries = [];
+    #disposed = false;
+    #disposeTask;
+    get disposed() {
+        return this.#disposed;
+    }
+    use(value) {
+        if (this.#disposed) {
+            throw new ReferenceError('Cannot add a resource to a disposed stack');
+        }
+        this.#entries.push(() => value.dispose());
+        return value;
+    }
+    defer(callback) {
+        if (this.#disposed) {
+            throw new ReferenceError('Cannot add a callback to a disposed stack');
+        }
+        this.#entries.push(callback);
+    }
+    dispose() {
+        this.#disposeTask ??= this.#dispose();
+        return this.#disposeTask;
+    }
+    async #dispose() {
+        this.#disposed = true;
+        const errors = [];
+        for (const entry of this.#entries.reverse()) {
+            try {
+                await entry();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        this.#entries.length = 0;
+        if (errors.length > 0) {
+            throw new AggregateError(errors, 'One or more resources failed to dispose');
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './diagnostic.js';
+export * from './disposable.js';
+export * from './json.js';
+export * from './resource-tracker.js';
+export * from './time.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,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,uBAAuB,CAAC;AACtC,cAAc,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from './diagnostic.js';
+export * from './disposable.js';
+export * from './json.js';
+export * from './resource-tracker.js';
+export * from './time.js';

package/dist/json.d.ts

@@ -0,0 +1,6 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type JsonObject = Record<string, JsonValue>;
+//# sourceMappingURL=json.d.ts.map

package/dist/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../src/json.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAE7D,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,SAAS,EAAE,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEnF,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC"}

package/dist/json.js

@@ -0,0 +1 @@
+export {};

package/dist/resource-tracker.d.ts

@@ -0,0 +1,11 @@
+export interface ResourceSnapshot {
+    readonly counts: Readonly<Record<string, number>>;
+    readonly total: number;
+}
+export declare class ResourceTracker {
+    #private;
+    acquire(kind: string): () => void;
+    snapshot(): ResourceSnapshot;
+    assertReleased(): void;
+}
+//# sourceMappingURL=resource-tracker.d.ts.map

package/dist/resource-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-tracker.d.ts","sourceRoot":"","sources":["../src/resource-tracker.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,qBAAa,eAAe;;IAGnB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,IAAI;IAajC,QAAQ,IAAI,gBAAgB;IAU5B,cAAc,IAAI,IAAI;CAM9B"}

package/dist/resource-tracker.js

@@ -0,0 +1,32 @@
+export class ResourceTracker {
+    #counts = new Map();
+    acquire(kind) {
+        if (kind.length === 0)
+            throw new TypeError('Resource kind must not be empty');
+        this.#counts.set(kind, (this.#counts.get(kind) ?? 0) + 1);
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            const current = this.#counts.get(kind) ?? 0;
+            if (current <= 1)
+                this.#counts.delete(kind);
+            else
+                this.#counts.set(kind, current - 1);
+        };
+    }
+    snapshot() {
+        const counts = Object.fromEntries([...this.#counts.entries()].sort(([a], [b]) => a.localeCompare(b)));
+        return {
+            counts,
+            total: Object.values(counts).reduce((total, count) => total + count, 0),
+        };
+    }
+    assertReleased() {
+        const snapshot = this.snapshot();
+        if (snapshot.total !== 0) {
+            throw new Error(`Aelion resource leak detected: ${JSON.stringify(snapshot.counts)}`);
+        }
+    }
+}

package/dist/time.d.ts

@@ -0,0 +1,19 @@
+export interface Rational {
+    readonly numerator: number;
+    readonly denominator: number;
+}
+export type RoundingMode = 'floor' | 'ceil' | 'nearest';
+export declare class TimeError extends RangeError {
+    readonly code: 'TIME_NOT_SAFE_INTEGER' | 'RATIONAL_INVALID' | 'INDEX_NOT_SAFE_INTEGER' | 'TIME_RESULT_OUT_OF_RANGE';
+    constructor(code: TimeError['code'], message: string);
+}
+export declare function assertTimeUs(value: number, name?: string): number;
+export declare function assertRational(value: Rational, name?: string): Rational;
+export declare function normalizeRational(value: Rational): Rational;
+export declare function frameStartUs(frameIndex: number, frameRate: Rational): number;
+export declare function frameDurationUs(frameIndex: number, frameRate: Rational): number;
+export declare function frameIndexAtTime(timeUs: number, frameRate: Rational, mode?: RoundingMode): number;
+export declare function sampleIndexAtTime(timeUs: number, sampleRate: number, mode?: RoundingMode): number;
+export declare function sampleBoundaryUs(sampleIndex: number, sampleRate: number): number;
+export declare function sampleCountForRange(startUs: number, durationUs: number, sampleRate: number): number;
+//# sourceMappingURL=time.d.ts.map

package/dist/time.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time.d.ts","sourceRoot":"","sources":["../src/time.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;AAExD,qBAAa,SAAU,SAAQ,UAAU;IACvC,SAAgB,IAAI,EAChB,uBAAuB,GACvB,kBAAkB,GAClB,wBAAwB,GACxB,0BAA0B,CAAC;gBAEZ,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM;CAK5D;AAQD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,SAAW,GAAG,MAAM,CAGnE;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,SAAa,GAAG,QAAQ,CAS3E;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,QAAQ,GAAG,QAAQ,CAO3D;AA4CD,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,GAAG,MAAM,CAK5E;AAED,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,GAAG,MAAM,CAK/E;AAED,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,QAAQ,EACnB,IAAI,GAAE,YAAsB,GAC3B,MAAM,CA2BR;AAED,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,YAAsB,GAC3B,MAAM,CAQR;AAED,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAUhF;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,MAAM,CASR"}

package/dist/time.js

@@ -0,0 +1,138 @@
+const MICROSECONDS_PER_SECOND = 1000000n;
+const MAX_SAFE_INTEGER_BIGINT = BigInt(Number.MAX_SAFE_INTEGER);
+const MIN_SAFE_INTEGER_BIGINT = BigInt(Number.MIN_SAFE_INTEGER);
+export class TimeError extends RangeError {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'TimeError';
+        this.code = code;
+    }
+}
+function assertSafeInteger(value, name, code) {
+    if (!Number.isSafeInteger(value)) {
+        throw new TimeError(code, `${name} must be a safe integer; received ${String(value)}`);
+    }
+}
+export function assertTimeUs(value, name = 'timeUs') {
+    assertSafeInteger(value, name, 'TIME_NOT_SAFE_INTEGER');
+    return value;
+}
+export function assertRational(value, name = 'rational') {
+    assertSafeInteger(value.numerator, `${name}.numerator`, 'RATIONAL_INVALID');
+    assertSafeInteger(value.denominator, `${name}.denominator`, 'RATIONAL_INVALID');
+    if (value.numerator <= 0 || value.denominator <= 0) {
+        throw new TimeError('RATIONAL_INVALID', `${name} numerator and denominator must be positive`);
+    }
+    return value;
+}
+export function normalizeRational(value) {
+    assertRational(value);
+    const divisor = greatestCommonDivisor(BigInt(value.numerator), BigInt(value.denominator));
+    return {
+        numerator: Number(BigInt(value.numerator) / divisor),
+        denominator: Number(BigInt(value.denominator) / divisor),
+    };
+}
+function greatestCommonDivisor(left, right) {
+    let a = left < 0n ? -left : left;
+    let b = right < 0n ? -right : right;
+    while (b !== 0n) {
+        const remainder = a % b;
+        a = b;
+        b = remainder;
+    }
+    return a;
+}
+function divide(numerator, denominator, mode) {
+    if (denominator <= 0n) {
+        throw new TimeError('RATIONAL_INVALID', 'division denominator must be positive');
+    }
+    const quotient = numerator / denominator;
+    const remainder = numerator % denominator;
+    if (remainder === 0n)
+        return quotient;
+    if (mode === 'floor')
+        return numerator >= 0n ? quotient : quotient - 1n;
+    if (mode === 'ceil')
+        return numerator >= 0n ? quotient + 1n : quotient;
+    const absoluteRemainder = remainder < 0n ? -remainder : remainder;
+    const direction = numerator < 0n ? -1n : 1n;
+    return absoluteRemainder * 2n >= denominator ? quotient + direction : quotient;
+}
+function toSafeNumber(value, context) {
+    if (value > MAX_SAFE_INTEGER_BIGINT || value < MIN_SAFE_INTEGER_BIGINT) {
+        throw new TimeError('TIME_RESULT_OUT_OF_RANGE', `${context} exceeds safe integer range`);
+    }
+    return Number(value);
+}
+function assertIndex(value, name) {
+    assertSafeInteger(value, name, 'INDEX_NOT_SAFE_INTEGER');
+    if (value < 0) {
+        throw new TimeError('INDEX_NOT_SAFE_INTEGER', `${name} must be non-negative`);
+    }
+}
+export function frameStartUs(frameIndex, frameRate) {
+    assertIndex(frameIndex, 'frameIndex');
+    assertRational(frameRate, 'frameRate');
+    const numerator = BigInt(frameIndex) * MICROSECONDS_PER_SECOND * BigInt(frameRate.denominator);
+    return toSafeNumber(divide(numerator, BigInt(frameRate.numerator), 'floor'), 'frameStartUs');
+}
+export function frameDurationUs(frameIndex, frameRate) {
+    assertIndex(frameIndex, 'frameIndex');
+    const current = frameStartUs(frameIndex, frameRate);
+    const next = frameStartUs(frameIndex + 1, frameRate);
+    return next - current;
+}
+export function frameIndexAtTime(timeUs, frameRate, mode = 'floor') {
+    assertTimeUs(timeUs);
+    assertRational(frameRate, 'frameRate');
+    const denominator = MICROSECONDS_PER_SECOND * BigInt(frameRate.denominator);
+    const rateNumerator = BigInt(frameRate.numerator);
+    // frameStartUs() intentionally floors rational frame boundaries to integer
+    // microseconds. Its inverse must therefore reason about the quantized
+    // boundary, not merely divide timeUs by the rational frame duration.
+    //
+    // max n where floor(n * denominator / rateNumerator) <= timeUs
+    //   = ceil((timeUs + 1) * rateNumerator / denominator) - 1
+    const containing = divide((BigInt(timeUs) + 1n) * rateNumerator, denominator, 'ceil') - 1n;
+    if (mode === 'floor') {
+        return toSafeNumber(containing, 'frameIndexAtTime');
+    }
+    const atOrAfter = divide(BigInt(timeUs) * rateNumerator, denominator, 'ceil');
+    if (mode === 'ceil') {
+        return toSafeNumber(atOrAfter, 'frameIndexAtTime');
+    }
+    const containingStart = divide(containing * denominator, rateNumerator, 'floor');
+    const atOrAfterStart = divide(atOrAfter * denominator, rateNumerator, 'floor');
+    const distanceBefore = BigInt(timeUs) - containingStart;
+    const distanceAfter = atOrAfterStart - BigInt(timeUs);
+    return toSafeNumber(distanceAfter <= distanceBefore ? atOrAfter : containing, 'frameIndexAtTime');
+}
+export function sampleIndexAtTime(timeUs, sampleRate, mode = 'floor') {
+    assertTimeUs(timeUs);
+    assertSafeInteger(sampleRate, 'sampleRate', 'RATIONAL_INVALID');
+    if (sampleRate <= 0) {
+        throw new TimeError('RATIONAL_INVALID', 'sampleRate must be positive');
+    }
+    const numerator = BigInt(timeUs) * BigInt(sampleRate);
+    return toSafeNumber(divide(numerator, MICROSECONDS_PER_SECOND, mode), 'sampleIndexAtTime');
+}
+export function sampleBoundaryUs(sampleIndex, sampleRate) {
+    assertIndex(sampleIndex, 'sampleIndex');
+    assertSafeInteger(sampleRate, 'sampleRate', 'RATIONAL_INVALID');
+    if (sampleRate <= 0) {
+        throw new TimeError('RATIONAL_INVALID', 'sampleRate must be positive');
+    }
+    return toSafeNumber(divide(BigInt(sampleIndex) * MICROSECONDS_PER_SECOND, BigInt(sampleRate), 'floor'), 'sampleBoundaryUs');
+}
+export function sampleCountForRange(startUs, durationUs, sampleRate) {
+    assertTimeUs(startUs, 'startUs');
+    assertTimeUs(durationUs, 'durationUs');
+    if (durationUs < 0) {
+        throw new TimeError('TIME_NOT_SAFE_INTEGER', 'durationUs must be non-negative');
+    }
+    const endUs = startUs + durationUs;
+    assertTimeUs(endUs, 'endUs');
+    return sampleIndexAtTime(endUs, sampleRate) - sampleIndexAtTime(startUs, sampleRate);
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@aelionsdk/core",
+  "version": "0.1.0-beta.1",
+  "description": "Core time, diagnostics and resource primitives for AelionSDK",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FoyonaCZY/AelionSDK.git",
+    "directory": "packages/core"
+  },
+  "keywords": [
+    "aelion",
+    "video",
+    "editing",
+    "browser"
+  ],
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo"
+  ],
+  "engines": {
+    "node": ">=20.19"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc -b --pretty false"
+  }
+}