piximps 0.1.0

package/src/piximps/common/templates/horns.ts

@@ -0,0 +1,152 @@
+import { CellType as C } from '@piximps/domain/types'
+import { Template } from '@piximps/domain/template'
+import { type TemplateRegistry } from './types'
+
+const _ = C.AlwaysEmpty
+const F = C.AlwaysFilled
+
+const wideHorns8 = new Template({
+  grid: [
+    [F, _, _, _],
+    [_, F, _, _],
+  ],
+  anchors: {},
+  compatibleWith: ['wide-horns'],
+  symmetric: true,
+})
+
+const smallHorns8 = new Template({
+  grid: [
+    [_, _, F, _],
+  ],
+  anchors: {},
+  compatibleWith: ['small-horns'],
+  symmetric: true,
+})
+
+const tallHorns8 = new Template({
+  grid: [
+    [_, F, _, _],
+    [_, F, _, _],
+    [_, _, _, _],
+  ],
+  anchors: {},
+  compatibleWith: ['tall-horns'],
+  symmetric: true,
+})
+
+const curvedHorns16 = new Template({
+  grid: [
+    [F, _, _, _],
+    [_, F, _, _],
+    [_, _, F, _],
+  ],
+  anchors: {},
+  compatibleWith: ['wide-horns'],
+  symmetric: true,
+})
+
+const straightHorns16 = new Template({
+  grid: [
+    [_, F, _],
+    [_, F, _],
+    [_, F, _],
+  ],
+  anchors: {},
+  compatibleWith: ['tall-horns'],
+  symmetric: true,
+})
+
+const branchingHorns16 = new Template({
+  grid: [
+    [F, _, _, _, _],
+    [_, F, _, _, _],
+    [_, F, F, _, _],
+    [_, _, _, F, _],
+  ],
+  anchors: {},
+  compatibleWith: ['wide-horns'],
+  symmetric: true,
+})
+
+const stubbyHorns16 = new Template({
+  grid: [
+    [F, _, _],
+    [_, F, _],
+  ],
+  anchors: {},
+  compatibleWith: ['small-horns'],
+  symmetric: true,
+})
+
+const longCurved32 = new Template({
+  grid: [
+    [F, _, _, _, _, _, _, _],
+    [_, F, _, _, _, _, _, _],
+    [_, _, F, _, _, _, _, _],
+    [_, _, _, F, F, _, _, _],
+    [_, _, _, _, _, F, _, _],
+    [_, _, _, _, _, _, F, _],
+  ],
+  anchors: {},
+  compatibleWith: ['wide-horns'],
+  symmetric: true,
+})
+
+const shortStubby32 = new Template({
+  grid: [
+    [_, _, F, _, _],
+    [_, _, _, F, _],
+    [_, _, _, _, F],
+  ],
+  anchors: {},
+  compatibleWith: ['small-horns'],
+  symmetric: true,
+})
+
+const branching32 = new Template({
+  grid: [
+    [F, _, _, _, _, _, _, _],
+    [_, F, _, _, _, _, _, _],
+    [_, _, F, F, _, _, _, _],
+    [_, _, F, _, F, _, _, _],
+    [_, _, _, _, _, F, _, _],
+    [_, _, _, _, _, _, F, _],
+  ],
+  anchors: {},
+  compatibleWith: ['wide-horns'],
+  symmetric: true,
+})
+
+const ramStyle32 = new Template({
+  grid: [
+    [_, F, F, _, _, _],
+    [F, _, _, F, _, _],
+    [F, _, _, _, F, _],
+    [_, F, _, _, F, _],
+    [_, _, F, F, _, _],
+  ],
+  anchors: {},
+  compatibleWith: ['wide-horns'],
+  symmetric: true,
+})
+
+const singleSpike32 = new Template({
+  grid: [
+    [_, F, _],
+    [_, F, _],
+    [_, F, _],
+    [_, F, _],
+    [_, F, _],
+    [_, F, _],
+  ],
+  anchors: {},
+  compatibleWith: ['tall-horns'],
+  symmetric: true,
+})
+
+export const hornTemplates: TemplateRegistry = {
+  8: [wideHorns8, smallHorns8, tallHorns8],
+  16: [curvedHorns16, straightHorns16, branchingHorns16, stubbyHorns16],
+  32: [longCurved32, shortStubby32, branching32, ramStyle32, singleSpike32],
+}

package/src/piximps/common/templates/mouth.ts

@@ -0,0 +1,96 @@
+import { CellType as C } from '@piximps/domain/types'
+import { Template } from '@piximps/domain/template'
+import { type TemplateRegistry } from './types'
+
+const _ = C.AlwaysEmpty
+const F = C.AlwaysFilled
+
+const fangs8 = new Template({
+  grid: [[_, F, _, F]],
+  anchors: {},
+  compatibleWith: ['fangs'],
+  symmetric: true,
+})
+
+const grin8 = new Template({
+  grid: [[_, F, F, F]],
+  anchors: {},
+  compatibleWith: ['grin'],
+  symmetric: true,
+})
+
+const smirk8 = new Template({
+  grid: [[_, _, F, F]],
+  anchors: {},
+  compatibleWith: ['smirk'],
+  symmetric: false,
+})
+
+const fangs16 = new Template({
+  grid: [
+    [_, F, _, F],
+    [F, _, F, _],
+  ],
+  anchors: {},
+  compatibleWith: ['fangs'],
+  symmetric: true,
+})
+
+const grin16 = new Template({
+  grid: [
+    [_, F, F, F],
+    [_, _, F, F],
+  ],
+  anchors: {},
+  compatibleWith: ['grin'],
+  symmetric: true,
+})
+
+const smirk16 = new Template({
+  grid: [
+    [_, _, F, F],
+    [_, F, F, _],
+  ],
+  anchors: {},
+  compatibleWith: ['smirk'],
+  symmetric: false,
+})
+
+const multiFangs32 = new Template({
+  grid: [
+    [_, _, F, _, F, _, F, _],
+    [_, F, _, F, _, F, _, _],
+    [F, _, _, _, _, _, _, _],
+  ],
+  anchors: {},
+  compatibleWith: ['fangs'],
+  symmetric: true,
+})
+
+const wideGrin32 = new Template({
+  grid: [
+    [_, _, F, F, F, F, F, F],
+    [_, _, _, F, F, F, F, F],
+    [_, _, _, _, F, F, F, F],
+  ],
+  anchors: {},
+  compatibleWith: ['grin'],
+  symmetric: true,
+})
+
+const asymSmirk32 = new Template({
+  grid: [
+    [_, _, _, _, F, F, F, F],
+    [_, _, _, F, F, F, _, _],
+    [_, _, F, F, _, _, _, _],
+  ],
+  anchors: {},
+  compatibleWith: ['smirk'],
+  symmetric: false,
+})
+
+export const mouthTemplates: TemplateRegistry = {
+  8: [fangs8, grin8, smirk8],
+  16: [fangs16, grin16, smirk16],
+  32: [multiFangs32, wideGrin32, asymSmirk32],
+}

package/src/piximps/common/templates/types.ts

@@ -0,0 +1,4 @@
+import { type GridSize } from '@piximps/domain/types'
+import { Template } from '@piximps/domain/template'
+
+export type TemplateRegistry = Record<GridSize, Template[]>

package/src/piximps/domain/color-palette.ts

@@ -0,0 +1,22 @@
+import { type RgbaColor } from './types'
+
+export interface ColorPaletteConfig {
+  skin: RgbaColor
+  accent: RgbaColor
+  glow: RgbaColor
+  secondary: RgbaColor
+}
+
+export class ColorPalette {
+  readonly skin: RgbaColor
+  readonly accent: RgbaColor
+  readonly glow: RgbaColor
+  readonly secondary: RgbaColor
+
+  constructor(config: ColorPaletteConfig) {
+    this.skin = config.skin
+    this.accent = config.accent
+    this.glow = config.glow
+    this.secondary = config.secondary
+  }
+}

package/src/piximps/domain/imp-traits.ts

@@ -0,0 +1,35 @@
+export type AccessoryType = 'tail' | 'wings' | 'weapon' | 'hat'
+
+export type AccessoryIndices = Record<AccessoryType, number | null>
+
+export type SymmetryBreakSide = 'left' | 'right'
+
+export interface ImpTraitsConfig {
+  bodyIndex: number
+  hornsIndex: number
+  eyesIndex: number
+  mouthIndex: number
+  accessoryIndices: AccessoryIndices
+  probabilisticBits: boolean[]
+  symmetryBreakSide: SymmetryBreakSide
+}
+
+export class ImpTraits {
+  readonly bodyIndex: number
+  readonly hornsIndex: number
+  readonly eyesIndex: number
+  readonly mouthIndex: number
+  readonly accessoryIndices: AccessoryIndices
+  readonly probabilisticBits: boolean[]
+  readonly symmetryBreakSide: SymmetryBreakSide
+
+  constructor(config: ImpTraitsConfig) {
+    this.bodyIndex = config.bodyIndex
+    this.hornsIndex = config.hornsIndex
+    this.eyesIndex = config.eyesIndex
+    this.mouthIndex = config.mouthIndex
+    this.accessoryIndices = config.accessoryIndices
+    this.probabilisticBits = config.probabilisticBits
+    this.symmetryBreakSide = config.symmetryBreakSide
+  }
+}

package/src/piximps/domain/template.ts

@@ -0,0 +1,35 @@
+import { type TemplateGrid, type AnchorPoint } from './types'
+
+export interface TemplateConfig {
+  grid: TemplateGrid
+  anchors: Record<string, AnchorPoint>
+  compatibleWith: string[]
+  symmetric: boolean
+}
+
+export class Template {
+  readonly grid: TemplateGrid
+  readonly anchors: Record<string, AnchorPoint>
+  readonly compatibleWith: string[]
+  readonly symmetric: boolean
+
+  constructor(config: TemplateConfig) {
+    this.grid = config.grid
+    this.anchors = config.anchors
+    this.compatibleWith = config.compatibleWith
+    this.symmetric = config.symmetric
+  }
+
+  get width(): number {
+    return this.grid[0]?.length ?? 0
+  }
+
+  get height(): number {
+    return this.grid.length
+  }
+
+  get mirroredWidth(): number {
+    if (!this.symmetric) return this.width
+    return this.width * 2 - 1
+  }
+}

package/src/piximps/domain/types.ts

@@ -0,0 +1,34 @@
+export enum CellType {
+  AlwaysEmpty = -1,
+  Probabilistic = 0,
+  AlwaysFilled = 1,
+  InnerBody = 2,
+}
+
+export type GridSize = 8 | 16 | 32
+
+export type OutputFormat = 'buffer' | 'png' | 'svg'
+
+export type RgbaColor = [r: number, g: number, b: number, a: number]
+
+export type AnchorPoint = {
+  row: number
+  columnStart: number
+  columnEnd: number
+}
+
+export type TemplateGrid = CellType[][]
+
+export enum RenderedCellType {
+  Empty = 0,
+  Body = 1,
+  InnerBody = 2,
+  Edge = 3,
+}
+
+export type RenderedGrid = {
+  cells: RenderedCellType[][]
+  colors: (RgbaColor | null)[][]
+  width: number
+  height: number
+}

package/src/piximps/entrypoints/renderers/to-png-binary.ts

@@ -0,0 +1,13 @@
+import { PNG } from 'pngjs'
+import { type RenderedGrid } from '@piximps/domain/types'
+import { toRgbaBuffer } from './to-rgba-buffer'
+
+export function toPngBinary(grid: RenderedGrid, outputSize: number): Uint8Array {
+  const rgbaData = toRgbaBuffer(grid, outputSize)
+
+  const png = new PNG({ width: outputSize, height: outputSize })
+  png.data = Buffer.from(rgbaData)
+
+  const pngBuffer = PNG.sync.write(png)
+  return new Uint8Array(pngBuffer)
+}

package/src/piximps/entrypoints/renderers/to-rgba-buffer.ts

@@ -0,0 +1,26 @@
+import { RenderedCellType, type RenderedGrid } from '@piximps/domain/types'
+
+export function toRgbaBuffer(grid: RenderedGrid, outputSize: number): Uint8Array {
+  const buffer = new Uint8Array(outputSize * outputSize * 4)
+  const scale = outputSize / grid.width
+
+  for (let y = 0; y < outputSize; y++) {
+    for (let x = 0; x < outputSize; x++) {
+      const gridRow = Math.floor(y / scale)
+      const gridCol = Math.floor(x / scale)
+      const pixelOffset = (y * outputSize + x) * 4
+
+      const cell = grid.cells[gridRow]?.[gridCol]
+      const color = grid.colors[gridRow]?.[gridCol]
+
+      if (cell !== undefined && cell !== RenderedCellType.Empty && color) {
+        buffer[pixelOffset] = color[0]
+        buffer[pixelOffset + 1] = color[1]
+        buffer[pixelOffset + 2] = color[2]
+        buffer[pixelOffset + 3] = color[3]
+      }
+    }
+  }
+
+  return buffer
+}

package/src/piximps/entrypoints/renderers/to-svg-string.ts

@@ -0,0 +1,28 @@
+import { RenderedCellType, type RenderedGrid } from '@piximps/domain/types'
+
+export function toSvgString(grid: RenderedGrid, outputSize: number): string {
+  const pixelSize = outputSize / grid.width
+  const rects: string[] = []
+
+  for (let r = 0; r < grid.height; r++) {
+    for (let c = 0; c < grid.width; c++) {
+      const cell = grid.cells[r][c]
+      const color = grid.colors[r][c]
+
+      if (cell === RenderedCellType.Empty || !color) continue
+
+      const x = c * pixelSize
+      const y = r * pixelSize
+
+      rects.push(
+        `<rect x="${x}" y="${y}" width="${pixelSize}" height="${pixelSize}" fill="rgb(${color[0]},${color[1]},${color[2]})" opacity="${color[3] / 255}"/>`,
+      )
+    }
+  }
+
+  return [
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${outputSize}" height="${outputSize}" viewBox="0 0 ${outputSize} ${outputSize}">`,
+    ...rects,
+    '</svg>',
+  ].join('\n')
+}

package/src/piximps/index.ts

@@ -0,0 +1,117 @@
+import { type GridSize, type OutputFormat } from './domain/types'
+import { hashToByteSequence } from './services/hash-to-byte-sequence'
+import { derivePalette } from './services/palette-deriver'
+import { extractTraits } from './services/trait-extractor'
+import { composeLayers } from './services/layer-compositor'
+import { detectEdges } from './services/edge-detector'
+import { toRgbaBuffer } from './entrypoints/renderers/to-rgba-buffer'
+import { toPngBinary } from './entrypoints/renderers/to-png-binary'
+import { toSvgString } from './entrypoints/renderers/to-svg-string'
+import { bodyTemplates } from './common/templates/body'
+import { hornTemplates } from './common/templates/horns'
+import { eyeTemplates } from './common/templates/eyes'
+import { mouthTemplates } from './common/templates/mouth'
+import { accessoryTemplates } from './common/templates/accessories'
+import { type AccessoryType } from './domain/imp-traits'
+
+export interface ImpGeneratorOptions {
+  size: number
+  grid: GridSize
+  format: OutputFormat
+}
+
+export class ImpGenerator {
+  private readonly options: ImpGeneratorOptions
+
+  private static readonly VALID_GRID_SIZES: GridSize[] = [8, 16, 32]
+  private static readonly MAX_OUTPUT_SIZE = 4096
+
+  constructor(options?: Partial<ImpGeneratorOptions>) {
+    const grid = options?.grid ?? 16
+    const size = options?.size ?? 128
+
+    if (!ImpGenerator.VALID_GRID_SIZES.includes(grid)) {
+      throw new RangeError(`Grid size must be one of: ${ImpGenerator.VALID_GRID_SIZES.join(', ')}`)
+    }
+    if (size <= 0 || size > ImpGenerator.MAX_OUTPUT_SIZE) {
+      throw new RangeError(`Output size must be between 1 and ${ImpGenerator.MAX_OUTPUT_SIZE}`)
+    }
+
+    this.options = {
+      size,
+      grid,
+      format: options?.format ?? 'png',
+    }
+  }
+
+  getOptions(): Readonly<ImpGeneratorOptions> {
+    return { ...this.options }
+  }
+
+  size(value: number): ImpGenerator {
+    return new ImpGenerator({ ...this.options, size: value })
+  }
+
+  grid(value: GridSize): ImpGenerator {
+    return new ImpGenerator({ ...this.options, grid: value })
+  }
+
+  format(value: OutputFormat): ImpGenerator {
+    return new ImpGenerator({ ...this.options, format: value })
+  }
+
+  async generate(input?: string): Promise<Uint8Array | string> {
+    const bytes = input !== undefined
+      ? hashToByteSequence(input)
+      : crypto.getRandomValues(new Uint8Array(32))
+
+    const palette = derivePalette(bytes)
+    const traits = extractTraits(bytes, this.options.grid)
+
+    const body = bodyTemplates[this.options.grid][traits.bodyIndex]
+    if (!body) {
+      throw new Error(`No body template at index ${traits.bodyIndex} for grid size ${this.options.grid}`)
+    }
+
+    const horns = hornTemplates[this.options.grid][traits.hornsIndex] ?? null
+    const eyes = eyeTemplates[this.options.grid][traits.eyesIndex] ?? null
+    const mouth = mouthTemplates[this.options.grid][traits.mouthIndex] ?? null
+
+    const accessories: typeof body[] = []
+    const accessoryTypes: AccessoryType[] = ['tail', 'wings', 'weapon', 'hat']
+    for (const accType of accessoryTypes) {
+      const idx = traits.accessoryIndices[accType]
+      if (idx !== null) {
+        const template = accessoryTemplates[accType]?.[this.options.grid]?.[idx]
+        if (template) accessories.push(template)
+      }
+    }
+
+    const composited = composeLayers({
+      gridSize: this.options.grid,
+      body,
+      horns,
+      eyes,
+      mouth,
+      accessories,
+      palette,
+      probabilisticBits: traits.probabilisticBits,
+      symmetryBreakSide: traits.symmetryBreakSide,
+    })
+
+    const edgeDetected = detectEdges(composited)
+
+    switch (this.options.format) {
+      case 'buffer':
+        return toRgbaBuffer(edgeDetected, this.options.size)
+      case 'png':
+        return toPngBinary(edgeDetected, this.options.size)
+      case 'svg':
+        return toSvgString(edgeDetected, this.options.size)
+    }
+  }
+}
+
+export { type GridSize, type OutputFormat } from './domain/types'
+export { type ImpTraits } from './domain/imp-traits'
+export { type ColorPalette } from './domain/color-palette'

package/src/piximps/services/edge-detector.ts

@@ -0,0 +1,60 @@
+import { RenderedCellType, type RenderedGrid, type RgbaColor } from '@piximps/domain/types'
+
+const DARKEN_FACTOR = 0.4
+
+function darkenColor(color: RgbaColor): RgbaColor {
+  const multiplier = 1 - DARKEN_FACTOR
+  return [
+    Math.round(color[0] * multiplier),
+    Math.round(color[1] * multiplier),
+    Math.round(color[2] * multiplier),
+    color[3],
+  ]
+}
+
+function isFilled(cellType: RenderedCellType): boolean {
+  return cellType !== RenderedCellType.Empty
+}
+
+function hasEmptyNeighbor(
+  cells: RenderedCellType[][],
+  row: number,
+  col: number,
+  height: number,
+  width: number,
+): boolean {
+  if (row === 0 || row === height - 1 || col === 0 || col === width - 1) {
+    return true
+  }
+
+  const neighbors = [
+    cells[row - 1][col],
+    cells[row + 1][col],
+    cells[row][col - 1],
+    cells[row][col + 1],
+  ]
+
+  return neighbors.some(n => !isFilled(n))
+}
+
+export function detectEdges(grid: RenderedGrid): RenderedGrid {
+  const { cells, colors, width, height } = grid
+
+  const newCells: RenderedCellType[][] = cells.map(row => [...row])
+  const newColors: (RgbaColor | null)[][] = colors.map(row => [...row])
+
+  for (let r = 0; r < height; r++) {
+    for (let c = 0; c < width; c++) {
+      if (!isFilled(cells[r][c])) continue
+
+      if (hasEmptyNeighbor(cells, r, c, height, width)) {
+        newCells[r][c] = RenderedCellType.Edge
+        if (colors[r][c]) {
+          newColors[r][c] = darkenColor(colors[r][c]!)
+        }
+      }
+    }
+  }
+
+  return { cells: newCells, colors: newColors, width, height }
+}

package/src/piximps/services/hash-to-byte-sequence.ts

@@ -0,0 +1,75 @@
+/**
+ * MurmurHash3 (32-bit) implementation.
+ * Produces a deterministic 32-bit hash from a string.
+ * We run it with multiple seeds to generate enough bytes for trait extraction.
+ */
+function murmurhash3_32(key: string, seed: number): number {
+  let h1 = seed >>> 0
+  const remainder = key.length & 3
+  const bytes = key.length - remainder
+  const c1 = 0xcc9e2d51
+  const c2 = 0x1b873593
+
+  let i = 0
+  while (i < bytes) {
+    let k1 =
+      (key.charCodeAt(i) & 0xff) |
+      ((key.charCodeAt(i + 1) & 0xff) << 8) |
+      ((key.charCodeAt(i + 2) & 0xff) << 16) |
+      ((key.charCodeAt(i + 3) & 0xff) << 24)
+    i += 4
+
+    k1 = Math.imul(k1, c1)
+    k1 = (k1 << 15) | (k1 >>> 17)
+    k1 = Math.imul(k1, c2)
+
+    h1 ^= k1
+    h1 = (h1 << 13) | (h1 >>> 19)
+    h1 = Math.imul(h1, 5) + 0xe6546b64
+  }
+
+  let k1 = 0
+  switch (remainder) {
+    case 3:
+      k1 ^= (key.charCodeAt(i + 2) & 0xff) << 16
+    // falls through
+    case 2:
+      k1 ^= (key.charCodeAt(i + 1) & 0xff) << 8
+    // falls through
+    case 1:
+      k1 ^= key.charCodeAt(i) & 0xff
+      k1 = Math.imul(k1, c1)
+      k1 = (k1 << 15) | (k1 >>> 17)
+      k1 = Math.imul(k1, c2)
+      h1 ^= k1
+  }
+
+  h1 ^= key.length
+  h1 ^= h1 >>> 16
+  h1 = Math.imul(h1, 0x85ebca6b)
+  h1 ^= h1 >>> 13
+  h1 = Math.imul(h1, 0xc2b2ae35)
+  h1 ^= h1 >>> 16
+
+  return h1 >>> 0
+}
+
+/**
+ * Converts a string input to a deterministic byte sequence
+ * by running MurmurHash3 with 8 different seeds, producing 32 bytes.
+ */
+export function hashToByteSequence(input: string): Uint8Array {
+  const seedCount = 8
+  const bytes = new Uint8Array(seedCount * 4)
+
+  for (let seed = 0; seed < seedCount; seed++) {
+    const hash = murmurhash3_32(input, seed)
+    const offset = seed * 4
+    bytes[offset] = hash & 0xff
+    bytes[offset + 1] = (hash >> 8) & 0xff
+    bytes[offset + 2] = (hash >> 16) & 0xff
+    bytes[offset + 3] = (hash >> 24) & 0xff
+  }
+
+  return bytes
+}