@aelionsdk/core 0.1.0-beta.1 → 1.1.0-rc.1

package/README.md

@@ -1,7 +1,29 @@
-# @aelionsdk/core
+# `@aelionsdk/core`
 
-Core time, diagnostics and resource primitives for AelionSDK
+Shared time, diagnostics, JSON and resource-lifecycle primitives for
+AelionSDK.
 
-Install with `npm install @aelionsdk/core@next`.
+## Install
 
-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.
+```bash
+npm install @aelionsdk/core@next
+```
+
+`next` currently resolves to `1.1.0-rc.1`. Most applications receive these
+types through `@aelionsdk/sdk`; direct use is intended for extensions and
+custom engine hosts.
+
+## Public surface
+
+- integer-microsecond time and rational frame/sample conversion;
+- `AelionError` and structured diagnostics;
+- JSON value types;
+- disposable and resource-tracking utilities.
+
+Keep time values in integer microseconds at public boundaries, and preserve
+diagnostic codes when wrapping errors so applications can recover
+deterministically.
+
+See the [time model](https://foyonaczy.github.io/AelionSDK/concepts/time-model/)
+and [API reference](https://foyonaczy.github.io/AelionSDK/api/aelionsdk/core/overview/).
+Licensed under MIT.

package/dist/diagnostic-localization.d.ts

@@ -0,0 +1,29 @@
+import type { Diagnostic } from './diagnostic.js';
+/** BCP-47 locale tag, e.g. `en` or `zh-CN`. */
+export type DiagnosticLocale = string;
+/**
+ * Localized message templates keyed by diagnostic `code` then locale. Templates
+ * interpolate `{key}` placeholders from the diagnostic's `details` object; a
+ * placeholder with no matching detail renders as an empty string.
+ */
+export type DiagnosticCatalog = Readonly<Record<string, Readonly<Record<DiagnosticLocale, string>>>>;
+/**
+ * Return a copy of `diagnostic` whose `message` is the localized template for
+ * `locale`, or the original `diagnostic` unchanged when the catalog has no
+ * template for its `code`. The stable `code`, structured fields and
+ * `recoverable` flag are never altered, so callers can keep branching on the
+ * code while rendering a localized message.
+ */
+export declare function localizeDiagnostic<T extends Diagnostic>(diagnostic: T, catalog: DiagnosticCatalog, locale: DiagnosticLocale): T;
+/**
+ * Localize every diagnostic in a result array. Unknown codes pass through with
+ * their original English message.
+ */
+export declare function localizeDiagnostics<T extends Diagnostic>(diagnostics: readonly T[], catalog: DiagnosticCatalog, locale: DiagnosticLocale): readonly T[];
+/**
+ * English message templates for the most common documented diagnostic codes.
+ * Applications extend this with additional locales; unknown codes fall back to
+ * the original English `message`.
+ */
+export declare const defaultDiagnosticCatalog: DiagnosticCatalog;
+//# sourceMappingURL=diagnostic-localization.d.ts.map

package/dist/diagnostic-localization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostic-localization.d.ts","sourceRoot":"","sources":["../src/diagnostic-localization.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,+CAA+C;AAC/C,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAEtC;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CACtC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC,CAAC,CAC3D,CAAC;AACF;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,UAAU,EACrD,UAAU,EAAE,CAAC,EACb,OAAO,EAAE,iBAAiB,EAC1B,MAAM,EAAE,gBAAgB,GACvB,CAAC,CAYH;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,UAAU,EACtD,WAAW,EAAE,SAAS,CAAC,EAAE,EACzB,OAAO,EAAE,iBAAiB,EAC1B,MAAM,EAAE,gBAAgB,GACvB,SAAS,CAAC,EAAE,CAEd;AAED;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,iBAgBtC,CAAC"}

package/dist/diagnostic-localization.js

@@ -0,0 +1,50 @@
+/**
+ * Return a copy of `diagnostic` whose `message` is the localized template for
+ * `locale`, or the original `diagnostic` unchanged when the catalog has no
+ * template for its `code`. The stable `code`, structured fields and
+ * `recoverable` flag are never altered, so callers can keep branching on the
+ * code while rendering a localized message.
+ */
+export function localizeDiagnostic(diagnostic, catalog, locale) {
+    const template = catalog[diagnostic.code]?.[locale];
+    if (template === undefined)
+        return diagnostic;
+    const details = diagnostic.details;
+    const message = template.replace(/\{([a-zA-Z0-9_]+)\}/gu, (_, key) => {
+        const value = details?.[key];
+        // Interpolate primitives only; objects would render as '[object Object]'.
+        return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean'
+            ? String(value)
+            : '';
+    });
+    return { ...diagnostic, message };
+}
+/**
+ * Localize every diagnostic in a result array. Unknown codes pass through with
+ * their original English message.
+ */
+export function localizeDiagnostics(diagnostics, catalog, locale) {
+    return diagnostics.map(diagnostic => localizeDiagnostic(diagnostic, catalog, locale));
+}
+/**
+ * English message templates for the most common documented diagnostic codes.
+ * Applications extend this with additional locales; unknown codes fall back to
+ * the original English `message`.
+ */
+export const defaultDiagnosticCatalog = {
+    PROJECT_ENTITY_KEY_MISMATCH: {
+        en: '{collection} key {key} does not match entity id {id}',
+    },
+    PROJECT_REFERENCE_MISSING: { en: 'Reference {id} does not exist in {collection}' },
+    PROJECT_DUPLICATE_REFERENCE: { en: 'Duplicate reference {value}' },
+    PROJECT_HOST_MISMATCH: { en: '{entity} {id} belongs to another {host}' },
+    PROJECT_MATERIAL_ORPHAN: { en: 'Material instance {id} has no owner' },
+    PROJECT_IMAGE_SEQUENCE_FRAME_MISSING: {
+        en: 'Image sequence {id} references missing frame Asset {frameAssetId}',
+    },
+    PROJECT_IMAGE_SEQUENCE_FRAME_KIND_INVALID: {
+        en: 'Frame Asset {frameAssetId} of image sequence {id} must be an image Asset',
+    },
+    MEDIA_INPUT_INVALID: { en: 'Input media is unsupported or corrupt: {cause}' },
+    OPERATION_ABORTED: { en: '{operation} was aborted' },
+};

package/dist/index.d.ts

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

package/dist/index.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,uBAAuB,CAAC;AACtC,cAAc,WAAW,CAAC"}

package/dist/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aelionsdk/core",
-  "version": "0.1.0-beta.1",
+  "version": "1.1.0-rc.1",
   "description": "Core time, diagnostics and resource primitives for AelionSDK",
   "license": "MIT",
   "repository": {
@@ -27,7 +27,7 @@
     "!dist/.tsbuildinfo"
   ],
   "engines": {
-    "node": ">=20.19"
+    "node": ">=24 <25"
   },
   "publishConfig": {
     "access": "public",