npm package: @funeste38/morphing
Description: morph - 4-byte universal value type for Funesterie (QFLUSH, A11, Spyder, OC8, RGBA, Freeland cubes and reference spaces).
Author: funeste38
Latest version: 0.1.5

# @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

```bash
npm install @funeste38/morphing
```

## Binary layout

Each morph is exactly 4 bytes:

```text
[ 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:

```text
[ 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

```ts
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

```bash
npm install
npm run build
npm test
```

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md).

## License

MIT