@funeste38/morphing

morphing defines a compact 4-byte value shape for Funesterie systems.

It is designed as a common low-level format that can travel across RGBA pixels, OC8 payloads, QFLUSH memory, A11 state, Spyder graphs and small reference spaces without losing type information.

Why it exists

• Gives every subsystem the same tiny binary primitive
• Keeps transport simple: 4 bytes can map directly to RGBA
• Supports both inline values and references to richer objects
• Stays small enough to embed inside PNG, buffers, queues or memory snapshots

Install

npm install @funeste38/morphing

Binary layout

Each morph is exactly 4 bytes:

[ TT | D1 | D2 | D3 ]

• TT stores the 2-bit kind and the 6-bit subtype
• D1 D2 D3 store a 24-bit payload

Logical layout:

[ 2 bits kind | 6 bits subtype | 24 bits data ]

Kinds:

• Int24 for signed or unsigned compact integers
• FloatQ for future quantized floating-point values
• Flag for booleans, enums and tiny status values
• Ref for handles into one of the internal reference spaces

Core API

• makeMorph(kind, subtype, data24) creates a raw morph
• fromInt24() / toInt24() works with 24-bit integer payloads
• fromSignedInt24() / toSignedInt24() works with signed 24-bit integer payloads
• fromFlag() / toFlag() works with booleans and small flag states
• morphToRgba() / rgbaToMorph() maps directly to image pixels
• morphsToRgbaBytes() / rgbaBytesToMorphs() packs arrays of morphs for buffers or PNG lanes
• morphToUint32() / uint32ToMorph() packs or unpacks a morph as one integer
• toRef() / deref() stores richer runtime values in a named reference space
• fromJson() / toJson() stores JSON payloads through the reference system
• enigma() / unveil() reserves an Enigma-oriented reference space
• cubeToRgba() / rgbaToCube() projects a cube state into RGBA bytes for Freeland Bros-style diagnostics
• cubeToRef() / refToCube() stores and restores higher-order cube states through the ref system
• buildPorygonFromJson() / resolvePorygon() builds higher-order shard structures
• clearSpace() / clearAllSpaces() resets the runtime reference tables

Reference spaces

Ref morphs can point to one of eight runtime spaces:

| Space | Id | Intended use | | --- | --- | --- | | Global | 0 | neutral shared values | | QFlush | 1 | opcodes, runtime slots, orchestration state | | Spyder | 2 | graph nodes, scanner structures | | A11 | 3 | chat state, UI or local execution handles | | Nossen | 4 | metadata, links, side channels | | Five | 5 | free / custom | | Six | 6 | free / custom | | Enigma | 7 | secrets, puzzles, encoded payloads |

Quick example

import {
  MorphSpace,
  fromInt24,
  morphToRgba,
  buildPorygonFromJson,
  resolvePorygon,
  enigma,
  isMorph
} from "@funeste38/morphing";

const hp = fromInt24(120, 1);
const pixel = morphToRgba(hp);
const secret = enigma({ msg: "Funesterie Morph" });

const porygon = buildPorygonFromJson({ name: "Jeff", hp: 120 }, 7);
const restored = resolvePorygon(porygon);

console.log(pixel, restored, isMorph(hp), MorphSpace.A11);

Good fits

• OC8 or PNG-based data transport
• small runtime state snapshots
• lightweight queues or caches
• embedding handles or opaque references inside larger protocols
• Freeland cube diagnostics or RGBA projections

Current limits

• FloatQ is reserved but not yet fully implemented
• reference spaces are in-memory only today
• signed integer semantics depend on host interpretation

Good next improvements

• add stable binary serializers for arrays of morphs
• add reference-space snapshots for persistence or replication
• define a formal FloatQ encoding contract
• add property-based tests for roundtrips and edge cases

Development

npm install
npm run build
npm test

Contributing

See CONTRIBUTING.md.

License

MIT