@nossen/morphing 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 funeste38
+
+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,34 @@
+# @nossen/morphing
+
+Compact 4-byte value shapes and RGBA/cube helpers for low-friction transport.
+
+## Install
+
+```powershell
+npm install @nossen/morphing
+```
+
+## Quick Start
+
+```ts
+import { enigma } from "@nossen/morphing";
+```
+
+## Package Scope
+
+This is the NOSSEN distribution of `@funeste38/morphing`. New projects should use `@nossen/morphing`. Existing projects can migrate by replacing imports from `@funeste38/morphing` with `@nossen/morphing`.
+
+## Quality Gates
+
+| Task | Command |
+| --- | --- |
+| Build | `npm run build` |
+| Test | `npm test` |
+
+## Publishing
+
+This package is published as `@nossen/morphing@1.0.0` and mirrored to the Funesterie JFrog npm registry. Keep runtime files limited through the `files` field before publishing.
+
+## License
+
+See the package license and repository files for terms.

package/dist/morph.d.ts

@@ -0,0 +1,98 @@
+export declare enum MorphKind {
+    Int24 = 0,
+    FloatQ = 1,
+    Flag = 2,
+    Ref = 3
+}
+export type morph = {
+    /** TT = 2 bits type + 6 bits subtype */
+    tt: number;
+    d1: number;
+    d2: number;
+    d3: number;
+};
+export type RgbaTuple = [number, number, number, number];
+export type MorphCubeAxis = string | number;
+export type MorphCube<T = MorphCubeAxis> = {
+    r: T;
+    g: T;
+    b: T;
+    a: T;
+};
+export declare function makeMorph(kind: MorphKind, subtype: number, data24: number): morph;
+export declare function kindOf(m: morph): MorphKind;
+export declare function subtypeOf(m: morph): number;
+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;
+/** Signed Int24 helper */
+export declare function fromSignedInt24(value: number, subtype?: number): morph;
+export declare function toSignedInt24(m: morph): number;
+/** Bool / flag helper */
+export declare function fromFlag(flag: boolean, subtype?: number): morph;
+export declare function toFlag(m: morph): boolean;
+/** RGBA <-> morph mapping (pour OC8, PNG, etc.) */
+export declare function morphToRgba(m: morph): RgbaTuple;
+export declare function rgbaToMorph(rgba: RgbaTuple): morph;
+/** Pack a morph array into a flat RGBA byte buffer */
+export declare function morphsToRgbaBytes(values: morph[]): Uint8Array;
+export declare function rgbaBytesToMorphs(bytes: ArrayLike<number>): morph[];
+/** Encode en Uint32 (petit utilitaire pratique) */
+export declare function morphToUint32(m: morph): number;
+export declare function uint32ToMorph(v: number): morph;
+export declare const enum MorphSpace {
+    Global = 0,
+    QFlush = 1,
+    Spyder = 2,
+    A11 = 3,
+    Nossen = 4,
+    Five = 5,
+    Six = 6,
+    Enigma = 7
+}
+export declare const MorphRefSpaces: any[][];
+export declare function subtypeToSpace(subtype: number): MorphSpace;
+export declare function subtypeToLocalTag(subtype: number): number;
+/** Crée un morph REF dans un espace donné */
+export declare function toRef(value: any, space?: MorphSpace, localTag?: number): morph;
+/** Récupère la valeur référencée par un morph REF */
+export declare function deref(m: morph): any;
+/** Clone bit à bit un morph (utile pour alias) */
+export declare function cloneMorph(m: morph): morph;
+/** Alias : m2 devient une copie du "shape" de m1 */
+export declare function aliasMorph(target: morph, source: morph): morph;
+/** Lightweight visual projection for Freeland Bros / RGBA diagnostics */
+export declare function cubeToRgba(cube: MorphCube): RgbaTuple;
+export declare function rgbaToCube(rgba: RgbaTuple): MorphCube<number>;
+/** Enigma JSON : stocke la STRING JSON dans une ref et retourne un morph REF */
+export declare function fromJson(value: any, space?: MorphSpace): morph;
+/** Essaie de décoder un morph REF en JSON */
+export declare function toJson(m: morph): any;
+/** Enigma : stocke une valeur "secrète" dans l'espace Enigma */
+export declare function enigma(value: any, localTag?: number): morph;
+/** Enigma : récupère une valeur dans l'espace Enigma */
+export declare function unveil(m: morph): any;
+export type PorygonShard = {
+    id: number;
+    morph: morph;
+};
+export type Porygon = {
+    layoutId: number;
+    shards: PorygonShard[];
+};
+export type PorygonLayout = {
+    id: number;
+    description: string;
+};
+/** Crée un Porygon à partir d'un objet JSON (1 shard, layoutId=0) */
+export declare function buildPorygonFromJson(value: any, layoutId?: number): Porygon;
+/** Résout un Porygon (simple : 1 shard JSON Enigma) */
+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 function isMorph(x: any): x is morph;
+export declare function clearSpace(space: MorphSpace): void;
+export declare function clearAllSpaces(): void;

package/dist/morph.js

@@ -0,0 +1,268 @@
+export var MorphKind;
+(function (MorphKind) {
+    MorphKind[MorphKind["Int24"] = 0] = "Int24";
+    MorphKind[MorphKind["FloatQ"] = 1] = "FloatQ";
+    MorphKind[MorphKind["Flag"] = 2] = "Flag";
+    MorphKind[MorphKind["Ref"] = 3] = "Ref";
+})(MorphKind || (MorphKind = {}));
+export function makeMorph(kind, subtype, data24) {
+    if (subtype < 0 || subtype > 63) {
+        throw new RangeError("subtype must be between 0 and 63");
+    }
+    const tt = ((kind & 0b11) << 6) | (subtype & 63);
+    const v = data24 & 0xFFFFFF;
+    return {
+        tt,
+        d1: (v >> 16) & 0xFF,
+        d2: (v >> 8) & 0xFF,
+        d3: v & 0xFF,
+    };
+}
+export function kindOf(m) {
+    return (m.tt >> 6);
+}
+export function subtypeOf(m) {
+    return m.tt & 63;
+}
+export function data24Of(m) {
+    return (m.d1 << 16) | (m.d2 << 8) | m.d3;
+}
+/** Int24 helper */
+export function fromInt24(value, subtype = 0) {
+    return makeMorph(MorphKind.Int24, subtype, value);
+}
+export function toInt24(m) {
+    return data24Of(m);
+}
+/** 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);
+}
+export function toSignedInt24(m) {
+    const raw = data24Of(m) & 0xFFFFFF;
+    return (raw & 0x800000) !== 0 ? raw - 0x1000000 : raw;
+}
+/** Bool / flag helper */
+export function fromFlag(flag, subtype = 0) {
+    const data = flag ? 1 : 0;
+    return makeMorph(MorphKind.Flag, subtype, data);
+}
+export function toFlag(m) {
+    return data24Of(m) !== 0;
+}
+/** RGBA <-> morph mapping (pour OC8, PNG, etc.) */
+export function morphToRgba(m) {
+    return [m.tt & 0xFF, m.d1, m.d2, m.d3];
+}
+export function rgbaToMorph(rgba) {
+    const [r, g, b, a] = rgba;
+    return { tt: r & 0xFF, d1: g & 0xFF, d2: b & 0xFF, d3: a & 0xFF };
+}
+/** Pack a morph array into a flat RGBA byte buffer */
+export function morphsToRgbaBytes(values) {
+    const out = new Uint8Array(values.length * 4);
+    for (let i = 0; i < values.length; i++) {
+        const offset = i * 4;
+        const m = values[i];
+        out[offset] = m.tt & 0xFF;
+        out[offset + 1] = m.d1 & 0xFF;
+        out[offset + 2] = m.d2 & 0xFF;
+        out[offset + 3] = m.d3 & 0xFF;
+    }
+    return out;
+}
+export function rgbaBytesToMorphs(bytes) {
+    if ((bytes.length % 4) !== 0) {
+        throw new RangeError("RGBA byte buffer length must be a multiple of 4");
+    }
+    const out = [];
+    for (let i = 0; i < bytes.length; i += 4) {
+        out.push({
+            tt: Number(bytes[i]) & 0xFF,
+            d1: Number(bytes[i + 1]) & 0xFF,
+            d2: Number(bytes[i + 2]) & 0xFF,
+            d3: Number(bytes[i + 3]) & 0xFF
+        });
+    }
+    return out;
+}
+/** Encode en Uint32 (petit utilitaire pratique) */
+export function morphToUint32(m) {
+    return ((m.tt & 0xFF) << 24) |
+        ((m.d1 & 0xFF) << 16) |
+        ((m.d2 & 0xFF) << 8) |
+        (m.d3 & 0xFF);
+}
+export function uint32ToMorph(v) {
+    return {
+        tt: (v >> 24) & 0xFF,
+        d1: (v >> 16) & 0xFF,
+        d2: (v >> 8) & 0xFF,
+        d3: v & 0xFF,
+    };
+}
+// 8 espaces max (0–7)
+export const MorphRefSpaces = [
+    [], // Global
+    [], // QFlush
+    [], // Spyder
+    [], // A11
+    [], // Nossen
+    [], // 5
+    [], // 6
+    [], // Enigma
+];
+function makeSubtype(space, localTag) {
+    if (localTag < 0 || localTag > 0b000111) {
+        throw new RangeError("localTag must be between 0 and 7");
+    }
+    return ((space & 0b00000111) << 3) | (localTag & 0b00000111);
+}
+export function subtypeToSpace(subtype) {
+    return ((subtype >> 3) & 0b00000111);
+}
+export function subtypeToLocalTag(subtype) {
+    return subtype & 0b00000111;
+}
+// --- Références puissantes ---
+/** Crée un morph REF dans un espace donné */
+export function toRef(value, space = 0 /* MorphSpace.Global */, localTag = 0) {
+    const spaceTable = getSpaceTable(space);
+    const index = spaceTable.push(value) - 1;
+    const subtype = makeSubtype(space, localTag);
+    return makeMorph(MorphKind.Ref, subtype, index);
+}
+/** Récupère la valeur référencée par un morph REF */
+export function deref(m) {
+    if (kindOf(m) !== MorphKind.Ref)
+        return undefined;
+    const space = subtypeToSpace(subtypeOf(m));
+    const index = data24Of(m);
+    const table = getSpaceTable(space);
+    return table[index];
+}
+/** Clone bit à bit un morph (utile pour alias) */
+export function cloneMorph(m) {
+    return { tt: m.tt, d1: m.d1, d2: m.d2, d3: m.d3 };
+}
+/** Alias : m2 devient une copie du "shape" de m1 */
+export function aliasMorph(target, source) {
+    target.tt = source.tt;
+    target.d1 = source.d1;
+    target.d2 = source.d2;
+    target.d3 = source.d3;
+    return target;
+}
+function axisToByte(axis) {
+    if (typeof axis === "number" && Number.isFinite(axis)) {
+        return Math.max(0, Math.min(255, Math.trunc(axis)));
+    }
+    const text = String(axis ?? "");
+    let hash = 2166136261;
+    for (let i = 0; i < text.length; i++) {
+        hash ^= text.charCodeAt(i);
+        hash = Math.imul(hash, 16777619);
+    }
+    return (hash >>> 0) & 0xFF;
+}
+/** Lightweight visual projection for Freeland Bros / RGBA diagnostics */
+export function cubeToRgba(cube) {
+    return [
+        axisToByte(cube.r),
+        axisToByte(cube.g),
+        axisToByte(cube.b),
+        axisToByte(cube.a)
+    ];
+}
+export function rgbaToCube(rgba) {
+    return { r: rgba[0], g: rgba[1], b: rgba[2], a: rgba[3] };
+}
+// --- Compatibilité JSON ---
+/** Enigma JSON : stocke la STRING JSON dans une ref et retourne un morph REF */
+export function fromJson(value, space = 0 /* MorphSpace.Global */) {
+    const json = JSON.stringify(value);
+    return toRef(json, space, /* localTag = */ 1);
+}
+/** Essaie de décoder un morph REF en JSON */
+export function toJson(m) {
+    const v = deref(m);
+    if (typeof v !== "string")
+        return undefined;
+    try {
+        return JSON.parse(v);
+    }
+    catch {
+        return undefined;
+    }
+}
+// --- Mode Enigma ---
+/** Enigma : stocke une valeur "secrète" dans l'espace Enigma */
+export function enigma(value, localTag = 0) {
+    return toRef(value, 7 /* MorphSpace.Enigma */, localTag);
+}
+/** Enigma : récupère une valeur dans l'espace Enigma */
+export function unveil(m) {
+    if (subtypeToSpace(subtypeOf(m)) !== 7 /* MorphSpace.Enigma */)
+        return undefined;
+    return deref(m);
+}
+/** Crée un Porygon à partir d'un objet JSON (1 shard, layoutId=0) */
+export function buildPorygonFromJson(value, layoutId = 0) {
+    const m = fromJson(value, 7 /* MorphSpace.Enigma */);
+    return {
+        layoutId,
+        shards: [{ id: 0, morph: m }],
+    };
+}
+/** Résout un Porygon (simple : 1 shard JSON Enigma) */
+export function resolvePorygon(p) {
+    if (!p.shards.length)
+        return undefined;
+    const shard = p.shards[0];
+    return toJson(shard.morph);
+}
+/** Cube helpers for higher-level Freeland / RGBA tooling */
+export function cubeToRef(cube, space = 0 /* MorphSpace.Global */, localTag = 2) {
+    return toRef(cube, space, localTag);
+}
+export function refToCube(m) {
+    const value = deref(m);
+    if (value &&
+        typeof value === "object" &&
+        "r" in value &&
+        "g" in value &&
+        "b" in value &&
+        "a" in value) {
+        return value;
+    }
+    return undefined;
+}
+// --- Version ---
+export const MORPHING_VERSION = "0.1.5";
+// --- Type guard ---
+export function isMorph(x) {
+    return (x != null &&
+        typeof x === "object" &&
+        typeof x.tt === "number" &&
+        typeof x.d1 === "number" &&
+        typeof x.d2 === "number" &&
+        typeof x.d3 === "number");
+}
+// --- Ref space safety ---
+function getSpaceTable(space) {
+    const idx = space & 0b00000111;
+    return MorphRefSpaces[idx] ?? MorphRefSpaces[0];
+}
+export function clearSpace(space) {
+    const table = getSpaceTable(space);
+    table.length = 0;
+}
+export function clearAllSpaces() {
+    for (let i = 0; i < MorphRefSpaces.length; i++) {
+        MorphRefSpaces[i].length = 0;
+    }
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@nossen/morphing",
+  "version": "1.0.0",
+  "description": "Compact 4-byte value shapes and RGBA/cube helpers for low-friction transport.",
+  "author": "NOSSEN <contact@funesterie.me>",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/morph.js",
+  "types": "dist/morph.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/morph.js",
+      "types": "./dist/morph.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -w",
+    "prepare": "npm run build",
+    "test": "node test/smoke.mjs"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Funesterie/funesterie.git",
+    "directory": "runtime/modules/morphing"
+  },
+  "bugs": {
+    "url": "https://github.com/Funesterie/funesterie/issues"
+  },
+  "homepage": "https://github.com/Funesterie/funesterie/tree/master/runtime/modules/morphing#readme",
+  "keywords": [
+    "morphing",
+    "nossen",
+    "funesterie",
+    "a11",
+    "morph",
+    "qflush",
+    "spyder",
+    "oc8",
+    "rgba",
+    "binary",
+    "encoding"
+  ],
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}