@nossen/morphing 2.0.0 → 2.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +44 -20
  2. package/dist/morph.d.ts +21 -2
  3. package/dist/morph.js +60 -14
  4. package/package.json +2 -6
package/README.md CHANGED
@@ -2,55 +2,79 @@
2
2
 
3
3
  Compact 4-byte value shapes and RGBA/cube helpers for low-friction transport.
4
4
 
5
- ## Overview
5
+ Use Morphing when values need a tiny, inspectable representation for runtime experiments, visual carriers or payload projections.
6
6
 
7
- - Encodes compact values for transport between runtime modules.
8
- - Provides RGBA and cube helpers for visual/binary workflows.
9
- - Keeps low-level value shape logic independent from higher-level orchestration.
7
+ ## Why It Exists
8
+
9
+ The NOSSEN package train is the small-module layer behind Funesterie, A11, QFlush and local agent coordination. Each package owns one bounded runtime concern so automation remains inspectable instead of turning into an opaque blob.
10
+
11
+ ## Core Capabilities
12
+
13
+ - Models compact byte and RGBA-shaped values.
14
+ - Supports lightweight projection and conversion helpers.
15
+ - Pairs with Freeland Bros for diagnostics.
10
16
 
11
17
  ## Install
12
18
 
13
- ```powershell
19
+ ```bash
14
20
  npm install @nossen/morphing
15
21
  ```
16
22
 
17
- ## Usage
23
+ ## Quick Start
24
+
25
+ ```bash
26
+ npm run build
27
+ npm test
28
+ ```
29
+
30
+ ## Library Usage
18
31
 
19
32
  ```ts
20
- import * as Morphing from "@nossen/morphing";
33
+ import * as morphing from "@nossen/morphing";
21
34
  ```
22
35
 
36
+ ## Runtime Fit
37
+
38
+ - @nossen/morphing is part of the NOSSEN runtime module graph.
39
+ - Pairs with @nossen/freeland-bros.
40
+ - Pairs with @nossen/nezlephant.
41
+
42
+ ## Safety Model
43
+
44
+ - Small payload helper, not encryption.
45
+ - Do not treat visual encoding as secrecy.
46
+
23
47
  ## Package Details
24
48
 
25
49
  | Field | Value |
26
50
  | --- | --- |
27
51
  | Package | `@nossen/morphing` |
28
- | Version | `1.0.0` |
29
- | Type | TypeScript library |
52
+ | Version | `2.0.1` |
53
+ | Type | ESM library |
54
+ | CLI binaries | none |
30
55
  | Registry scope | `@nossen` |
56
+ | Repository | `runtime/modules/morphing` |
31
57
 
32
58
  ## Quality Gates
33
59
 
34
- | Task | Command |
60
+ | Field | Value |
35
61
  | --- | --- |
36
- | build | `npm run build` |
37
- | test | `npm run test` |
62
+ | build | `tsc -p tsconfig.json` |
63
+ | test | `node test/smoke.mjs` |
38
64
 
39
65
  ## Publishing
40
66
 
41
- This package is part of the NOSSEN package train. Before publishing, run the quality gates, inspect `npm pack --dry-run`, then publish the immutable version to npmjs and mirror the same version to the Funesterie JFrog npm registry.
67
+ This package is part of the NOSSEN package train. Before publishing, run the quality gates, inspect `npm pack --dry-run`, then publish the immutable version to npmjs and mirror the same version to the Funesterie package backups.
42
68
 
43
69
  ## Support NOSSEN
44
70
 
45
- NOSSEN packages stay public and usable under their license. If this package helps your workflow, choose any support amount that fits your situation. Contributions support Funesterie infrastructure, releases, and maintenance:
71
+ NOSSEN packages stay public and usable under their license. If this package helps your workflow, support Funesterie infrastructure, releases and maintenance through:
46
72
 
47
- - Email: funeste38@gmail.com
48
- - Wero: `+33 7 83 46 37 61` (choose your amount)
49
- - PayPal: https://paypal.me/funeste38 (choose your amount)
50
- - Stripe/card support: https://buy.stripe.com/7sYfZhfKW2DSffZgWU7Re01
51
- - Contact, invoice, sponsorship or custom support: https://funesterie.me/contact/
73
+ - Wero: `+33 7 83 46 37 61`
74
+ - PayPal: https://paypal.me/funeste38
75
+ - Stripe/card checkout: https://funesterie.me/subscription
76
+ - Custom support or invoice: https://funesterie.me/contact/
52
77
 
53
- Support is voluntary; there is no fixed package price.
54
78
  ## License
55
79
 
56
80
  See the package license and repository license files for terms.
package/dist/morph.d.ts CHANGED
@@ -26,6 +26,13 @@ export declare function data24Of(m: morph): number;
26
26
  /** Int24 helper */
27
27
  export declare function fromInt24(value: number, subtype?: number): morph;
28
28
  export declare function toInt24(m: morph): number;
29
+ /** Quantized fixed-point float helper.
30
+ *
31
+ * FloatQ stores a signed 24-bit integer equal to value * scale. The scale is
32
+ * caller-selected so transport stays compact and deterministic.
33
+ */
34
+ export declare function fromFloatQ(value: number, subtype?: number, scale?: number): morph;
35
+ export declare function toFloatQ(m: morph, scale?: number): number;
29
36
  /** Signed Int24 helper */
30
37
  export declare function fromSignedInt24(value: number, subtype?: number): morph;
31
38
  export declare function toSignedInt24(m: morph): number;
@@ -51,7 +58,18 @@ export declare const enum MorphSpace {
51
58
  Six = 6,
52
59
  Enigma = 7
53
60
  }
54
- export declare const MorphRefSpaces: any[][];
61
+ export type MorphRefSpaceTable = any[] & {
62
+ readonly space: MorphSpace;
63
+ readonly name: string;
64
+ readonly description: string;
65
+ };
66
+ export type MorphRefSpaceDescription = {
67
+ id: MorphSpace;
68
+ name: string;
69
+ description: string;
70
+ size: number;
71
+ };
72
+ export declare const MorphRefSpaces: MorphRefSpaceTable[];
55
73
  export declare function subtypeToSpace(subtype: number): MorphSpace;
56
74
  export declare function subtypeToLocalTag(subtype: number): number;
57
75
  /** Crée un morph REF dans un espace donné */
@@ -92,7 +110,8 @@ export declare function resolvePorygon(p: Porygon): any;
92
110
  /** Cube helpers for higher-level Freeland / RGBA tooling */
93
111
  export declare function cubeToRef(cube: MorphCube, space?: MorphSpace, localTag?: number): morph;
94
112
  export declare function refToCube(m: morph): MorphCube | undefined;
95
- export declare const MORPHING_VERSION = "0.1.5";
113
+ export declare const MORPHING_VERSION = "0.1.6";
96
114
  export declare function isMorph(x: any): x is morph;
115
+ export declare function describeRefSpaces(): MorphRefSpaceDescription[];
97
116
  export declare function clearSpace(space: MorphSpace): void;
98
117
  export declare function clearAllSpaces(): void;
package/dist/morph.js CHANGED
@@ -34,17 +34,35 @@ export function fromInt24(value, subtype = 0) {
34
34
  export function toInt24(m) {
35
35
  return data24Of(m);
36
36
  }
37
+ /** Quantized fixed-point float helper.
38
+ *
39
+ * FloatQ stores a signed 24-bit integer equal to value * scale. The scale is
40
+ * caller-selected so transport stays compact and deterministic.
41
+ */
42
+ export function fromFloatQ(value, subtype = 0, scale = 1000) {
43
+ if (!Number.isFinite(value)) {
44
+ throw new RangeError("FloatQ value must be finite");
45
+ }
46
+ if (!Number.isFinite(scale) || scale <= 0) {
47
+ throw new RangeError("FloatQ scale must be a positive finite number");
48
+ }
49
+ return makeMorph(MorphKind.FloatQ, subtype, encodeSigned24(Math.round(value * scale)));
50
+ }
51
+ export function toFloatQ(m, scale = 1000) {
52
+ if (!Number.isFinite(scale) || scale <= 0) {
53
+ throw new RangeError("FloatQ scale must be a positive finite number");
54
+ }
55
+ return decodeSigned24(data24Of(m)) / scale;
56
+ }
37
57
  /** Signed Int24 helper */
38
58
  export function fromSignedInt24(value, subtype = 0) {
39
59
  if (!Number.isInteger(value) || value < -0x800000 || value > 0x7FFFFF) {
40
60
  throw new RangeError("signed Int24 value must be between -8388608 and 8388607");
41
61
  }
42
- const encoded = value < 0 ? 0x1000000 + value : value;
43
- return makeMorph(MorphKind.Int24, subtype, encoded);
62
+ return makeMorph(MorphKind.Int24, subtype, encodeSigned24(value));
44
63
  }
45
64
  export function toSignedInt24(m) {
46
- const raw = data24Of(m) & 0xFFFFFF;
47
- return (raw & 0x800000) !== 0 ? raw - 0x1000000 : raw;
65
+ return decodeSigned24(data24Of(m));
48
66
  }
49
67
  /** Bool / flag helper */
50
68
  export function fromFlag(flag, subtype = 0) {
@@ -105,16 +123,26 @@ export function uint32ToMorph(v) {
105
123
  d3: v & 0xFF,
106
124
  };
107
125
  }
108
- // 8 espaces max (0–7)
126
+ function makeRefSpace(space, name, description) {
127
+ const table = [];
128
+ Object.defineProperties(table, {
129
+ space: { value: space, enumerable: false },
130
+ name: { value: name, enumerable: false },
131
+ description: { value: description, enumerable: false },
132
+ });
133
+ return table;
134
+ }
135
+ // 8 espaces max (0-7). Les tableaux restent indexables comme avant, mais
136
+ // portent maintenant une identite stable pour inspection et documentation.
109
137
  export const MorphRefSpaces = [
110
- [], // Global
111
- [], // QFlush
112
- [], // Spyder
113
- [], // A11
114
- [], // Nossen
115
- [], // 5
116
- [], // 6
117
- [], // Enigma
138
+ makeRefSpace(0 /* MorphSpace.Global */, "global", "Process-local shared references."),
139
+ makeRefSpace(1 /* MorphSpace.QFlush */, "qflush", "QFlush orchestration references."),
140
+ makeRefSpace(2 /* MorphSpace.Spyder */, "spyder", "Spyder packet and memory references."),
141
+ makeRefSpace(3 /* MorphSpace.A11 */, "a11", "A11 agent/runtime references."),
142
+ makeRefSpace(4 /* MorphSpace.Nossen */, "nossen", "NOSSEN package-level references."),
143
+ makeRefSpace(5 /* MorphSpace.Five */, "five", "Reserved reference space 5."),
144
+ makeRefSpace(6 /* MorphSpace.Six */, "six", "Reserved reference space 6."),
145
+ makeRefSpace(7 /* MorphSpace.Enigma */, "enigma", "Private Enigma references."),
118
146
  ];
119
147
  function makeSubtype(space, localTag) {
120
148
  if (localTag < 0 || localTag > 0b000111) {
@@ -242,7 +270,7 @@ export function refToCube(m) {
242
270
  return undefined;
243
271
  }
244
272
  // --- Version ---
245
- export const MORPHING_VERSION = "0.1.5";
273
+ export const MORPHING_VERSION = "0.1.6";
246
274
  // --- Type guard ---
247
275
  export function isMorph(x) {
248
276
  return (x != null &&
@@ -257,6 +285,24 @@ function getSpaceTable(space) {
257
285
  const idx = space & 0b00000111;
258
286
  return MorphRefSpaces[idx] ?? MorphRefSpaces[0];
259
287
  }
288
+ function encodeSigned24(value) {
289
+ if (!Number.isInteger(value) || value < -0x800000 || value > 0x7FFFFF) {
290
+ throw new RangeError("signed 24-bit value must be between -8388608 and 8388607");
291
+ }
292
+ return value < 0 ? value + 0x1000000 : value;
293
+ }
294
+ function decodeSigned24(value) {
295
+ const unsigned = value & 0xFFFFFF;
296
+ return (unsigned & 0x800000) ? unsigned - 0x1000000 : unsigned;
297
+ }
298
+ export function describeRefSpaces() {
299
+ return MorphRefSpaces.map((table, index) => ({
300
+ id: index,
301
+ name: table.name,
302
+ description: table.description,
303
+ size: table.length,
304
+ }));
305
+ }
260
306
  export function clearSpace(space) {
261
307
  const table = getSpaceTable(space);
262
308
  table.length = 0;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nossen/morphing",
3
- "version": "2.0.0",
3
+ "version": "2.0.2",
4
4
  "description": "Compact 4-byte value shapes and RGBA/cube helpers for low-friction transport.",
5
5
  "author": "NOSSEN <contact@funesterie.me>",
6
6
  "license": "MIT",
@@ -9,14 +9,10 @@
9
9
  "url": "https://paypal.me/funeste38"
10
10
  },
11
11
  "donations": {
12
- "policy": "voluntary",
13
- "amount": "user-choice",
14
- "email": "funeste38@gmail.com",
15
12
  "wero": "+33783463761",
16
13
  "weroDisplay": "+33 7 83 46 37 61",
17
14
  "paypal": "https://paypal.me/funeste38",
18
- "stripe": "https://buy.stripe.com/7sYfZhfKW2DSffZgWU7Re01",
19
- "cardOrInvoice": "https://funesterie.me/contact/",
15
+ "stripe": "https://funesterie.me/subscription",
20
16
  "contact": "https://funesterie.me/contact/"
21
17
  },
22
18
  "type": "module",