@safe-vanity-blockie/core 0.3.0

package/src/select.ts

@@ -0,0 +1,77 @@
+import type { Candidate } from './miner.js'
+
+/**
+ * A score as a percentage of the template's maximum, rounded to the one decimal a result is
+ * displayed with. `formatScore` renders exactly this number, and `filterCandidates` compares
+ * exactly this number against the match floor, so the figure on a tile and the figure the filter
+ * judges it by are the same figure: 89.96% displays as "90.0%" and must not then be dropped by a
+ * 90% floor over a difference nothing on screen can show.
+ */
+export function scorePercent(score: number, maxScore: number): number {
+  if (maxScore <= 0) return 0
+  return Number(((score / maxScore) * 100).toFixed(1))
+}
+
+export function filterCandidates(
+  candidates: Candidate[],
+  filters: { twoColor: boolean; minContrast: number; minMatch?: number },
+): Candidate[] {
+  const minMatch = filters.minMatch ?? 0
+  return candidates.filter(
+    (candidate) =>
+      (!filters.twoColor || candidate.twoColor) &&
+      candidate.contrast >= filters.minContrast &&
+      scorePercent(candidate.score, candidate.maxScore) >= minMatch,
+  )
+}
+
+export interface SelectReportedResult {
+  reported: Candidate[]
+  /** How many candidates the filters removed. Zero when the fallback was used. */
+  droppedCount: number
+  /** True when filtering removed everything and the unfiltered list is being shown instead. */
+  usedFallback: boolean
+}
+
+/**
+ * Retention is score-ranked and blind to twoColor/minContrast/minMatch, which are applied here —
+ * so callers must retain far more candidates than they intend to display, or the filters will
+ * have nothing left to choose from.
+ *
+ * `fallbackWhenEmpty` defaults to true, which shows the unfiltered list rather than nothing when
+ * the filters match no candidate at all. That suits a caller that can say so alongside the
+ * results — the CLI prints a notice when `usedFallback` comes back true. A caller that can render
+ * an explicit "nothing matches these filters" state should pass false instead: silently showing
+ * everything makes the filter look ignored rather than unsatisfied. With it off, `droppedCount`
+ * stops being a special case and always reports what the filters actually removed.
+ */
+export function selectReported(
+  candidates: Candidate[],
+  options: {
+    twoColor: boolean
+    minContrast: number
+    /** Percentage floor, 0-100, judged as `scorePercent`. Omitted or 0 filters nothing. */
+    minMatch?: number
+    keep: number
+    fallbackWhenEmpty?: boolean
+  },
+): SelectReportedResult {
+  const filtered = filterCandidates(candidates, {
+    twoColor: options.twoColor,
+    minContrast: options.minContrast,
+    minMatch: options.minMatch,
+  })
+  const usedFallback =
+    (options.fallbackWhenEmpty ?? true) && filtered.length === 0 && candidates.length > 0
+  const usable = usedFallback ? candidates : filtered
+  const droppedCount = usedFallback ? 0 : candidates.length - filtered.length
+  return { reported: usable.slice(0, options.keep), droppedCount, usedFallback }
+}
+
+/**
+ * A score as a percentage of the template's maximum. One decimal, because the interesting
+ * results sit in a narrow band near the top and whole percent would collapse distinct scores.
+ */
+export function formatScore(score: number, maxScore: number): string {
+  return `${scorePercent(score, maxScore).toFixed(1)}%`
+}

package/src/templates.ts

@@ -0,0 +1,163 @@
+import type { FaceRegion, FaceSpec, FixedCell, RegionAlternative } from './types.js'
+
+export const MOUTH_BUDGET = 60
+export const MOUTH_STROKE_WEIGHT = 3
+export const MOUTH_BG_WEIGHT = 1
+
+/** Rows 0-4, index = row * 4 + col. 1 = the eye pixel (mirrored to column 5), 0 = background. */
+export const BASE_TARGET: readonly (0 | 1)[] = [
+  0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+]
+
+/** 8 = the eye, 5 = cells hugging it (isolation, incl. col 3 to keep the two eyes apart), 3 = plain background. */
+export const BASE_WEIGHTS: readonly number[] = [
+  3, 3, 3, 3, 3, 3, 5, 3, 3, 5, 8, 5, 3, 3, 5, 3, 3, 3, 3, 3,
+]
+
+/** Rows 5-7 of the left half: r5c0..r5c3, r6c0..r6c3, r7c0..r7c3. */
+export const MOUTH_INDICES: readonly number[] = [20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31]
+
+export const MOUTHS: readonly RegionAlternative[] = [
+  // r5: c0 c1 c2 c3   r6: c0 c1 c2 c3   r7: c0 c1 c2 c3
+  { name: 'smile', cells: [0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1] }, // corners up, dips centre
+  { name: 'frown', cells: [0, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0] }, // corners down
+  { name: 'neutral', cells: [0, 0, 0, 0, 0, 1, 1, 1, 0, 0, 0, 0] }, // straight line
+  { name: 'open', cells: [0, 0, 1, 1, 0, 0, 1, 0, 0, 0, 1, 1] }, // rounded "o" / surprised
+  { name: 'small', cells: [0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0] }, // little mouth
+]
+
+function baseFixedCells(): FixedCell[] {
+  return BASE_TARGET.map((value, index) => ({ index, value, weight: BASE_WEIGHTS[index] }))
+}
+
+function mouthRegion(alternatives: RegionAlternative[]): FaceRegion {
+  return {
+    name: 'mouth',
+    indices: [...MOUTH_INDICES],
+    budget: MOUTH_BUDGET,
+    strokeWeight: MOUTH_STROKE_WEIGHT,
+    bgWeight: MOUTH_BG_WEIGHT,
+    alternatives,
+  }
+}
+
+/** Builds a face with fixed eyes and the named subset of expressions accepted for the mouth. */
+export function faceWithMouths(name: string, mouthNames: string[]): FaceSpec {
+  const alternatives = mouthNames.map((mouthName) => {
+    const mouth = MOUTHS.find((candidate) => candidate.name === mouthName)
+    if (!mouth) {
+      throw new Error(
+        `unknown mouth "${mouthName}"; available: ${MOUTHS.map((m) => m.name).join(', ')}`,
+      )
+    }
+    return { name: mouth.name, cells: [...mouth.cells] }
+  })
+  return { name, fixed: baseFixedCells(), regions: [mouthRegion(alternatives)] }
+}
+
+// Built on a null prototype so a lookup by an attacker- or URL-controlled name can never resolve
+// an inherited Object.prototype key (e.g. "constructor", "toString", "__proto__") instead of
+// throwing the intended "unknown template" error.
+export const TEMPLATES: Record<string, FaceSpec> = Object.assign(Object.create(null), {
+  faces: faceWithMouths(
+    'faces',
+    MOUTHS.map((mouth) => mouth.name),
+  ),
+  ...Object.fromEntries(
+    MOUTHS.map((mouth) => [mouth.name, faceWithMouths(mouth.name, [mouth.name])]),
+  ),
+})
+
+export function getTemplate(name: string): FaceSpec {
+  if (!Object.hasOwn(TEMPLATES, name)) {
+    throw new Error(`unknown template "${name}"; available: ${Object.keys(TEMPLATES).join(', ')}`)
+  }
+  return TEMPLATES[name]
+}
+
+/** Guards the `entry as Record<string, unknown>` casts below: a null or primitive entry would
+ *  otherwise surface as a raw TypeError from the first property read. */
+function requireObject(value: unknown, label: string): Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new Error(`${label} must be an object, got ${JSON.stringify(value)}`)
+  }
+  return value as Record<string, unknown>
+}
+
+function requirePositiveInteger(value: unknown, label: string): number {
+  if (!Number.isInteger(value) || (value as number) <= 0) {
+    throw new Error(`${label} must be a positive integer, got ${JSON.stringify(value)}`)
+  }
+  return value as number
+}
+
+/** Validates untrusted JSON (a `--target file.json`, or a future web designer export). */
+export function parseFaceSpec(input: unknown): FaceSpec {
+  if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+    throw new Error('FaceSpec must be an object')
+  }
+  const raw = input as Record<string, unknown>
+  const name = typeof raw.name === 'string' && raw.name ? raw.name : 'custom'
+
+  const fixedInput = Array.isArray(raw.fixed) ? raw.fixed : []
+  const fixed: FixedCell[] = fixedInput.map((entry, i) => {
+    const cell = requireObject(entry, `fixed[${i}]`)
+    const index = cell.index
+    if (!Number.isInteger(index) || (index as number) < 0 || (index as number) > 31) {
+      throw new Error(`fixed[${i}].index must be an integer between 0 and 31`)
+    }
+    if (cell.value !== 0 && cell.value !== 1) {
+      throw new Error(`fixed[${i}].value must be 0 or 1`)
+    }
+    return {
+      index: index as number,
+      value: cell.value as 0 | 1,
+      weight: requirePositiveInteger(cell.weight, `fixed[${i}].weight`),
+    }
+  })
+
+  const regionsInput = Array.isArray(raw.regions) ? raw.regions : []
+  const regions: FaceRegion[] = regionsInput.map((entry, r) => {
+    const label = `regions[${r}]`
+    const region = requireObject(entry, label)
+    if (!Array.isArray(region.indices) || region.indices.length === 0) {
+      throw new Error(`${label}.indices must be a non-empty array`)
+    }
+    for (const index of region.indices) {
+      if (!Number.isInteger(index) || index < 0 || index > 31) {
+        throw new Error(`${label}.indices must all be integers between 0 and 31`)
+      }
+    }
+    if (!Array.isArray(region.alternatives) || region.alternatives.length === 0) {
+      throw new Error(`${label}.alternatives must contain at least one alternative`)
+    }
+    const alternatives: RegionAlternative[] = region.alternatives.map((altEntry, a) => {
+      const alternative = requireObject(altEntry, `${label}.alternatives[${a}]`)
+      if (!Array.isArray(alternative.cells)) {
+        throw new Error(`${label}.alternatives[${a}].cells must be an array`)
+      }
+      for (const cell of alternative.cells) {
+        if (cell !== 0 && cell !== 1) {
+          throw new Error(`${label}.alternatives[${a}].cells value must be 0 or 1`)
+        }
+      }
+      return {
+        name: typeof alternative.name === 'string' ? alternative.name : `alt${a}`,
+        cells: alternative.cells as (0 | 1)[],
+      }
+    })
+    return {
+      name: typeof region.name === 'string' ? region.name : `region${r}`,
+      indices: region.indices as number[],
+      budget: requirePositiveInteger(region.budget, `${label}.budget`),
+      strokeWeight: requirePositiveInteger(region.strokeWeight, `${label}.strokeWeight`),
+      bgWeight: requirePositiveInteger(region.bgWeight, `${label}.bgWeight`),
+      alternatives,
+    }
+  })
+
+  if (fixed.length === 0 && regions.length === 0) {
+    throw new Error('FaceSpec must define at least one fixed cell or region')
+  }
+  return { name, fixed, regions }
+}

package/src/types.ts

@@ -0,0 +1,66 @@
+/** Hue 0-360, saturation 0-100, lightness 0-100 — the ranges blo emits. */
+export type Hsl = readonly [number, number, number]
+
+/** blo's palette, in the order blo returns it: background, color, spot. */
+export type Palette = readonly [Hsl, Hsl, Hsl]
+
+export interface BloImage {
+  /** 32 values in {0,1,2} for the left half of the 8x8 grid; column c mirrors to 7-c. */
+  readonly data: Uint8Array
+  readonly colors: Palette
+}
+
+/** A cell whose target value is pinned. `index` is 0..31 in the left half of the grid. */
+export interface FixedCell {
+  index: number
+  value: 0 | 1
+  weight: number
+}
+
+/** One accepted shape for a region, e.g. a single mouth expression. */
+export interface RegionAlternative {
+  name: string
+  /** Aligned 1:1 with the region's `indices`. */
+  cells: (0 | 1)[]
+}
+
+/**
+ * A group of cells scored as `max` over a list of alternatives. Every alternative is normalised
+ * to the same `budget`, so no shape wins just for having more stroke pixels.
+ */
+export interface FaceRegion {
+  name: string
+  indices: number[]
+  budget: number
+  /** Relative weight of a cell that should be foreground. */
+  strokeWeight: number
+  /** Relative weight of a cell that should stay background. */
+  bgWeight: number
+  alternatives: RegionAlternative[]
+}
+
+export interface FaceSpec {
+  name: string
+  fixed: FixedCell[]
+  regions: FaceRegion[]
+}
+
+/** Flattened, integer-only form of a FaceSpec. Built once; read millions of times. */
+export interface CompiledFace {
+  readonly name: string
+  readonly maxScore: number
+  readonly nFixed: number
+  readonly fixedIndex: Uint8Array
+  readonly fixedTarget: Uint8Array
+  readonly fixedWeight: Int32Array
+  readonly nRegions: number
+  readonly regionIndexStart: Int32Array
+  readonly regionLength: Int32Array
+  readonly regionAltCount: Int32Array
+  readonly regionCellStart: Int32Array
+  readonly regionIndex: Uint8Array
+  readonly regionCells: Uint8Array
+  readonly regionWeights: Int32Array
+  readonly regionNames: readonly string[]
+  readonly regionAltNames: readonly (readonly string[])[]
+}