@nossen/morphing 2.0.1 → 2.0.2

package/dist/morph.d.ts

@@ -26,6 +26,13 @@ export declare function data24Of(m: morph): number;
 /** Int24 helper */
 export declare function fromInt24(value: number, subtype?: number): morph;
 export declare function toInt24(m: morph): number;
+/** Quantized fixed-point float helper.
+ *
+ * FloatQ stores a signed 24-bit integer equal to value * scale. The scale is
+ * caller-selected so transport stays compact and deterministic.
+ */
+export declare function fromFloatQ(value: number, subtype?: number, scale?: number): morph;
+export declare function toFloatQ(m: morph, scale?: number): number;
 /** Signed Int24 helper */
 export declare function fromSignedInt24(value: number, subtype?: number): morph;
 export declare function toSignedInt24(m: morph): number;
@@ -51,7 +58,18 @@ export declare const enum MorphSpace {
     Six = 6,
     Enigma = 7
 }
-export declare const MorphRefSpaces: any[][];
+export type MorphRefSpaceTable = any[] & {
+    readonly space: MorphSpace;
+    readonly name: string;
+    readonly description: string;
+};
+export type MorphRefSpaceDescription = {
+    id: MorphSpace;
+    name: string;
+    description: string;
+    size: number;
+};
+export declare const MorphRefSpaces: MorphRefSpaceTable[];
 export declare function subtypeToSpace(subtype: number): MorphSpace;
 export declare function subtypeToLocalTag(subtype: number): number;
 /** Crée un morph REF dans un espace donné */
@@ -92,7 +110,8 @@ export declare function resolvePorygon(p: Porygon): any;
 /** Cube helpers for higher-level Freeland / RGBA tooling */
 export declare function cubeToRef(cube: MorphCube, space?: MorphSpace, localTag?: number): morph;
 export declare function refToCube(m: morph): MorphCube | undefined;
-export declare const MORPHING_VERSION = "0.1.5";
+export declare const MORPHING_VERSION = "0.1.6";
 export declare function isMorph(x: any): x is morph;
+export declare function describeRefSpaces(): MorphRefSpaceDescription[];
 export declare function clearSpace(space: MorphSpace): void;
 export declare function clearAllSpaces(): void;

package/dist/morph.js

@@ -34,17 +34,35 @@ export function fromInt24(value, subtype = 0) {
 export function toInt24(m) {
     return data24Of(m);
 }
+/** Quantized fixed-point float helper.
+ *
+ * FloatQ stores a signed 24-bit integer equal to value * scale. The scale is
+ * caller-selected so transport stays compact and deterministic.
+ */
+export function fromFloatQ(value, subtype = 0, scale = 1000) {
+    if (!Number.isFinite(value)) {
+        throw new RangeError("FloatQ value must be finite");
+    }
+    if (!Number.isFinite(scale) || scale <= 0) {
+        throw new RangeError("FloatQ scale must be a positive finite number");
+    }
+    return makeMorph(MorphKind.FloatQ, subtype, encodeSigned24(Math.round(value * scale)));
+}
+export function toFloatQ(m, scale = 1000) {
+    if (!Number.isFinite(scale) || scale <= 0) {
+        throw new RangeError("FloatQ scale must be a positive finite number");
+    }
+    return decodeSigned24(data24Of(m)) / scale;
+}
 /** Signed Int24 helper */
 export function fromSignedInt24(value, subtype = 0) {
     if (!Number.isInteger(value) || value < -0x800000 || value > 0x7FFFFF) {
         throw new RangeError("signed Int24 value must be between -8388608 and 8388607");
     }
-    const encoded = value < 0 ? 0x1000000 + value : value;
-    return makeMorph(MorphKind.Int24, subtype, encoded);
+    return makeMorph(MorphKind.Int24, subtype, encodeSigned24(value));
 }
 export function toSignedInt24(m) {
-    const raw = data24Of(m) & 0xFFFFFF;
-    return (raw & 0x800000) !== 0 ? raw - 0x1000000 : raw;
+    return decodeSigned24(data24Of(m));
 }
 /** Bool / flag helper */
 export function fromFlag(flag, subtype = 0) {
@@ -105,16 +123,26 @@ export function uint32ToMorph(v) {
         d3: v & 0xFF,
     };
 }
-// 8 espaces max (0–7)
+function makeRefSpace(space, name, description) {
+    const table = [];
+    Object.defineProperties(table, {
+        space: { value: space, enumerable: false },
+        name: { value: name, enumerable: false },
+        description: { value: description, enumerable: false },
+    });
+    return table;
+}
+// 8 espaces max (0-7). Les tableaux restent indexables comme avant, mais
+// portent maintenant une identite stable pour inspection et documentation.
 export const MorphRefSpaces = [
-    [], // Global
-    [], // QFlush
-    [], // Spyder
-    [], // A11
-    [], // Nossen
-    [], // 5
-    [], // 6
-    [], // Enigma
+    makeRefSpace(0 /* MorphSpace.Global */, "global", "Process-local shared references."),
+    makeRefSpace(1 /* MorphSpace.QFlush */, "qflush", "QFlush orchestration references."),
+    makeRefSpace(2 /* MorphSpace.Spyder */, "spyder", "Spyder packet and memory references."),
+    makeRefSpace(3 /* MorphSpace.A11 */, "a11", "A11 agent/runtime references."),
+    makeRefSpace(4 /* MorphSpace.Nossen */, "nossen", "NOSSEN package-level references."),
+    makeRefSpace(5 /* MorphSpace.Five */, "five", "Reserved reference space 5."),
+    makeRefSpace(6 /* MorphSpace.Six */, "six", "Reserved reference space 6."),
+    makeRefSpace(7 /* MorphSpace.Enigma */, "enigma", "Private Enigma references."),
 ];
 function makeSubtype(space, localTag) {
     if (localTag < 0 || localTag > 0b000111) {
@@ -242,7 +270,7 @@ export function refToCube(m) {
     return undefined;
 }
 // --- Version ---
-export const MORPHING_VERSION = "0.1.5";
+export const MORPHING_VERSION = "0.1.6";
 // --- Type guard ---
 export function isMorph(x) {
     return (x != null &&
@@ -257,6 +285,24 @@ function getSpaceTable(space) {
     const idx = space & 0b00000111;
     return MorphRefSpaces[idx] ?? MorphRefSpaces[0];
 }
+function encodeSigned24(value) {
+    if (!Number.isInteger(value) || value < -0x800000 || value > 0x7FFFFF) {
+        throw new RangeError("signed 24-bit value must be between -8388608 and 8388607");
+    }
+    return value < 0 ? value + 0x1000000 : value;
+}
+function decodeSigned24(value) {
+    const unsigned = value & 0xFFFFFF;
+    return (unsigned & 0x800000) ? unsigned - 0x1000000 : unsigned;
+}
+export function describeRefSpaces() {
+    return MorphRefSpaces.map((table, index) => ({
+        id: index,
+        name: table.name,
+        description: table.description,
+        size: table.length,
+    }));
+}
 export function clearSpace(space) {
     const table = getSpaceTable(space);
     table.length = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nossen/morphing",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "Compact 4-byte value shapes and RGBA/cube helpers for low-friction transport.",
   "author": "NOSSEN <contact@funesterie.me>",
   "license": "MIT",