A linting layer, and the bug it found

The project had no static analysis. This pass added one: a curated, defect-focused .clang-tidy (the clang static analyzer plus the high-signal bugprone, performance, and unused-code checks — the noisy style families deliberately left off and documented as such), a cppcheck suppressions file, lint scripts for both shells, and a GitHub Actions lint workflow. The gate runs file-parallel over ~140 Qt translation units and lands clean: 143 TUs, zero findings.

It got there by fixing the real defects the first run surfaced. The most consequential was a percentage that had been wrong for most of its range:

// PokemonBox::expLevelRangePercent() — returns a float
- return curExp / expEnd;        // both var32: integer divide, THEN widen → truncated
+ return expEnd ? (float)curExp / expEnd : 0.0f;   // float divide + divide-by-zero guard

Because both operands were 32-bit integers, the division happened in integer space and the fractional part was discarded before the result widened to the float return type. The progress-through-level percentage was therefore pinned at 0 until the very top of a level, where it would finally tick to 1. A new mid-window assertion in tst_pokemonbox now guards it.

The same run caught an unguarded pointer dereference on one branch of PokemonBox::update() (the type-2 path wasn’t guarded the way the type-1 path was), a signed/unsigned char comparison, an integer-multiply widening, several loop variables that should have been const references, and a missing default in a switch. One finding — a destructor that can reach a pure-virtual call on an unusual lifetime path — was suppressed and flagged for a deliberate refactor rather than patched in place.

A dead store that wasn’t a no-op

One analyzer finding was a behavioural bug, not just a code-smell. When PokemonMove fills an empty slot it calls randomize(), which assigns a random 0–3 PP-Ups; the constructor was then meant to reset that to zero so a brand-new move starts clean. It didn’t:

// constructor parameter `ppUp` shadows the member of the same name
- ppUp = 0;          // assigns the parameter — a no-op; the member keeps its random value
+ this->ppUp = 0;    // assigns the member, as intended

The assignment targeted the shadowing constructor parameter, so the member kept the random count and new moves silently carried 0–3 PP-Ups they shouldn’t have. The fix is scoped to construction only; the deliberate “randomize everything” actions are unaffected.

Tests that assert more than values

The suite had been strong on values — does a fragment hold the right bytes after an edit — and largely silent on the machinery around them. This work added the missing test types:

• Signal/slot coverage (tst_signals, via QSignalSpy): mutating a fragment emits exactly the right change signal, with the right count, and bound-clamped no-ops still honour their always-emit contract. It also verifies the internal connect() wiring fires by spying the downstream signal.
• Model contracts (tst_model_tester): every QAbstractItemModel subclass is wrapped in Qt’s own QAbstractItemModelTester, which validates the framework contract and the change-signal protocol (beginResetModel/endResetModel, dataChanged, layoutChanged bracketing) that hand-written tests tend to miss. All models pass clean.
• A visual-regression floor (tst_visual_regression): every home-reachable screen is grabbed through the offscreen renderer and required to show a non-trivial spread of distinct colours — catching the failure a load-without-warnings test can’t, a screen that loads clean yet renders blank. It is deliberately not a pixel-perfect baseline diff, which the project treats as a trap during active UI polish.
• Acceptance scenarios (tst_acceptance): the two user-level promises stated as Given/When/Then — an edited value survives save → close → reopen, and browsing every screen mutates zero save bytes.

That last one is the project’s standing rule, now stated as an executable acceptance test:

GIVEN a loaded save file
WHEN  every screen is visited in turn
THEN  zero save bytes change   // "Save File Integrity Is Sacred"

The full ctest run stays green across all of it. With the test types now broad — values, signals, model contracts, GUI behaviour, visual rendering, and acceptance — the remaining testing work is depth: pushing line coverage toward 100%, where a first gap-fill pass also documented an honest limit, that some uncovered code is reachable only through QML’s meta-object system because the shared libraries export just their registered classes.

References

• Pokered Save Editor 2 repository · documentation site · v0.14.2-alpha release
• clang-tidy · QAbstractItemModelTester · QSignalSpy

fairyfox.io is the hub for Fairy Fox’s software projects. Until now those projects lived as separate repositories with no shared front door; this site provides one, along with a place to document the conventions they have in common.

What the site provides

• A project index. The projects page is generated from a single registry, so it stays current. It currently covers Pokered Save Editor 2 and Random AI Prompt.
• A documentation library. The docs section collects an ecosystem overview, the shared engineering standards, and an entry point into each project’s own documentation site.
• An updates log. This blog, where changes — including round-ups of activity across the projects — are written up.

How the repositories connect

The site is also a hub in a more literal sense: it holds the canonical shared standards (git workflow, versioning, the notes system, cross-project sync), and each project pulls them in on demand through a plain shallow git operation — no submodules, no live dependency. In the other direction, the hub keeps read-only copies of the projects so their changes can be tracked and documented. Each flow is one-directional git, which keeps the repositories independent and avoids circular updates. The model is documented under cross-project sync.

A useful side effect of the setup: because the custom domain is configured on the user site, each project’s GitHub Pages site is served under the same domain, so the navigation can lead directly into a project’s documentation.

From a smoke test to a real suite

Until now the project had only linting and an import smoke test. It now has layered coverage — Vitest for the Node engine and the React app, Playwright for the browser:

$ npm test
✓ lint (0 errors)
✓ smoke (module graph + all prompts)
✓ vitest  — 88 node + 30 web   (118 passed)

$ npm run test:e2e
✓ playwright — e2e + visual + a11y   (8 passed)

The browser specs include visual-regression snapshots (with the random suggestion masked so the page is stable) and accessibility checks via @axe-core/playwright.

The landmine worth documenting

The most instructive detail: the underlying utility library captures the global random function at import time, so you can’t make its randomness deterministic by overriding Math.random in a test:

// Does NOT work — lodash already captured Math.random on import
Math.random = () => 0.42;
expect(_.sample(list)).toBe(list[0]);   // still random

// What the tests do instead: assert invariants, not exact picks
const out = expandPrompt("{#city}");
expect(out).toMatch(/streetview/);          // structure is stable
expect(out.split(",").length).toBeGreaterThan(2);

Only the language’s own renderer, which uses its own seeded RNG, is driven deterministically. (Getting the browser tests to launch on the dev machine was its own saga, ultimately solved by pointing Playwright at the system Chrome.)

Unbreaking the pipeline

With tests in place, the focus turned to shipping. The stable branch had been held at the pre-revival state, and recent commits were red in CI — not from test failures, but from the install step:

npm error code EUSAGE
npm error `npm ci` can only install with an up to date package-lock.json
npm error Missing: @emnapi/core@1.11.1 from lock file

The lockfile had drifted after the new dependencies came in, and an incremental npm install on the Windows machine omitted the Linux-only optional packages that CI needs. The fix that actually works is a clean, full resolve so every platform’s optional dependencies are recorded:

rm -rf node_modules package-lock.json
npm install        # fresh resolve records @emnapi/*, linux-* bindings, etc.
npm ci             # now passes the sync check

Once green, the stable branch fast-forwarded to the current work for the first time in the revival — which promptly exposed two more first-time deployment breakages in the docs and release workflows, both fixed. A recurring theme of the week held to the end: the failures were almost never the code itself, but the build, packaging, and tooling around it.

References

• Random AI Prompt repository · documentation site
• Vitest · Playwright · @axe-core/playwright
• npm ci (why a clean lockfile matters in CI)

Why a language at all

A “dynamic prompt” assembles a prompt from optional pieces, weighted choices, and references to word lists. Expressing that in JavaScript means every generator is a small program, which is fine for a programmer and opaque to everyone else. The goal was a format where the structure of a prompt is visible at a glance.

What DPL looks like

Here’s a complete generator — the city street scene — verbatim:

---
description: A city streetview
---
Start
===
city, streetview, {city}
- {style/building}
- cityscape
- downtown

{#nature}, {#weather}, reflective street

The pieces are deliberately plain: front matter for metadata, a === heading for a section, a plain line that’s always included, - bullet lines that are optional (50% by default), {list} to pull from a word list, and {#generator} to call another generator. Probabilities and repetition read naturally too:

Start
===
- {art-movement}
- {art-technique}
- 50% repeat 0 to 3 times: {image-effect}
- {#rays}

And explicit either/or branching:

Start
===
portrait
- maybe: full body
- otherwise: head and chest, upperbody
- up-close

Logic stays in JavaScript

A core design decision is that DPL is data, not code — it has no variables or counters. Anything that genuinely needs logic delegates to a referenced JavaScript file, so the .dpl stays declarative:

---
description: A subject — animal, character, flower, instrument, creature, tree, or person
script: entity.js
---

The bridge works in both directions: DPL can call into JS, and JS can call back into DPL sections. About 90% of the catalog ended up as pure DPL; the rest keeps a thin .js sidecar.

A weighted layer tree

Underneath, v3 changes the model. The older generators built an ordered string where position carried meaning. v3 treats every file, section, and line as a layer in a tree — the user’s prompt box is the root, each building block a child — and renders by sorting each layer’s children by weight rather than by where they appear. Auto-weights start at 1000 and increment per line; an explicit [n] overrides:

Start
===
[100] wide shot, dramatic lighting   # low weight → sorts to the front
ancient forest, morning mist         # auto-weighted (1000, 1001, …)

Built in phases

To protect a working app, this shipped in phases: (1) the parser and renderer plus a test harness, with sample generators converted; (2) the entire existing catalog converted to DPL; (3) wiring DPL into the live engine and both loaders, making the new v3 catalog the default; and (4) the wrapper UI — a start/end frame applied around every prompt. The frozen v1 and v2 generations remain fully functional, addressed by a path prefix:

{#cave}        → v3 (the default)
{#v2/cave}     → the frozen v2 version
{#v1/castle}   → the frozen v1 version
{#any}         → pick one generator at random from the v3 catalog

The “full versus partial prompt” distinction that drove a lot of duplication in the old system is on its way out, which was the underlying goal all along.

References

• Random AI Prompt repository · documentation site
• DPL design and language notes: reference/dpl-design.md, reference/dpl-language.md
• Prior art: sd-dynamic-prompts (the wildcard/variant idea in the wider ecosystem)

Folders and path-suffix resolution

The flat pile of files moved into category folders, with resolution by path suffix so a bare name, a partial path, or a full path all work:

data/lists/
  color.txt                      → {color}
  danbooru/d/general-sfw.txt      → {general-sfw}  or  {d/general-sfw}
  artist/dhigh.txt                → {dhigh}        or  {artist/dhigh}

That keeps the ~78 existing {name} references working while allowing deep organisation underneath.

A filename-based SFW model

The trickiest part was content gating, which went through several iterations before settling on a rule keyed entirely off the filename — no special configuration, no runtime filtering. A mixed-topic list is two files plus an implicit combined reference:

data/lists/danbooru/d/
  general-sfw.txt     # the safe half
  general-nsfw.txt    # the gated half
  general-sfw.json    # { "description": "Danbooru general descriptor tags (SFW)." }

The resolver combines them by mode: {general} yields the SFW half when adult content is off and both halves when it’s on, while {general-sfw} is always just the safe half. The design goal was that a safe-only user never has to type anything special to stay safe. A content-safety pass also tightened the lists, keeping ordinary adult content gated rather than deleted, with real place names and artist handles protected from false positives.

Group files instead of hardcoded composites

Composite lists became real .group files — each line references another list (or group), resolved by the same suffix lookup:

# data/lists/artist/digipa.group
# Group: the three digital-painting impact artist lists.
artist/dhigh
artist/dmed
artist/dlow

Folders with two or more lists become implied groups automatically; optional <list>.json sidecars supply tooltips in the editor; and keyword became a reserved wildcard that draws a word from any loaded list.

Letting a dictionary do the sorting

The cleanup ran on a principle worth stating: for proper nouns, a model’s world knowledge is the right classifier (no dictionary knows Achernar is a star), but for parts of speech a real dictionary states the answer rather than guessing it. So the dictionary dump was re-sorted into parts of speech using WordNet as the authority, and a roughly 8,800-entry “keyword” junk drawer of proper nouns was hand-classified into people, places, organisations, mythology, astronomy, religion, history, and more — with coverage checks so nothing was silently dropped. Several parallel review passes over the curated lists then caught and fixed hundreds of misfiled entries (surnames sitting in a first-names list, and the like).

References

• Random AI Prompt repository · documentation site
• Princeton WordNet · wordpos (the Node interface used)

Matching the original’s look

The first pass rebuilt the home page around the visual language the original pre-revival generator had established — a dark charcoal canvas with a mint-green accent — captured as CSS variables so the theme is defined in one place:

:root {
  --bg:           hsl(0 0% 13%);   /* charcoal canvas */
  --text:         hsl(0 0% 96%);
  --accent:       #34e2a0;         /* mint green */
  --font-display: "Space Grotesk", system-ui, sans-serif;
}

The real source files were rebuilt rather than mocked up, and the shared-link feature that seeds the app from a URL (#s=…) was preserved throughout.

Decluttering into a workspace

A round of feedback then pushed it from “redesigned” toward “feels like an app.” The made-up tagline and centred hero went; the display font changed to one that read less like a logo; and image generation, the chaos control, and presets were pulled off the home screen for now. Nothing was deleted outright — everything removed was logged for later in a removed-pending-readd.md note, with presets explicitly slated to return as a richer feature. The layout became a full-height app window with a left building-blocks pane beside the composer, and the prompt input was simplified so its rotating placeholder is the live suggestion.

A small fix with a lesson attached

One exchange is worth recording. An offhand remark that the Share link “doesn’t work and was complicated” was wrongly taken as an instruction to remove it. It was an observation, not an order — so the feature was restored and then actually fixed. The old version flashed a tiny “Link copied!” and failed silently when the clipboard API was blocked; the new one keeps the link visible in a selectable field, so it works regardless:

function ShareLink({ url }) {
  const [copied, setCopied] = useState(false);
  const copy = async () => {
    try { await navigator.clipboard.writeText(url); setCopied(true); }
    catch { /* clipboard blocked — the field below still shows the link */ }
  };
  return (
    <div className="share">
      <input readOnly value={url} onFocus={(e) => e.target.select()} />
      <button onClick={copy}>{copied ? "✓ Copied" : "Copy"}</button>
    </div>
  );
}

The takeaway, noted for next time: a critique or a question is an invitation to explain or ask, not permission to delete.

References

• Random AI Prompt repository · documentation site
• React · Vite
• Space Grotesk · navigator.clipboard.writeText

From CommonJS to ESM

The starting point was a 2022 CommonJS codebase. The target was ES modules on Node 24, the active LTS, with every dependency moved to its current major. The entry points opt in through package.json:

{
  "type": "module",
  "engines": { "node": ">=24" }
}

The bulk of the conversion — around 123 files — was done with two throwaway codemods (module.exports = function → export default function, require("x") → import x from "x.js"), then the trickier ~28 files were finished by hand. A couple of genuine ES-module pitfalls came out of it and are worth keeping.

The sharpest one: imports are evaluated before top-level statements. The old code changed the working directory at the top of common.js, but under ESM that line would now run after the settings module had already been imported and read its config file:

// Old (CommonJS): ran early enough to matter
process.chdir(__dirname);
const settings = require("./settings"); // reads ./user-settings.json

// New (ESM): the chdir moves into its own module, imported first
import "./chdir.js";          // performs process.chdir(...) on load
import settings from "./settings.js";

A second one: the generators are loaded by path inside synchronous string-replace callbacks, so switching them to await import() would have meant rewriting the whole pipeline. createRequire preserves the synchronous behaviour exactly:

import { createRequire } from "node:module";
const require = createRequire(import.meta.url);
const generator = require(generatorPath).default;

Proving the port changed nothing

A modernisation is only worth anything if it’s behaviour-preserving, so that was checked rather than asserted. An import smoke test loads the entire module graph, pulls in all 113 dynamic-prompt generators, and expands a sample prompt:

$ npm run smoke
✓ module graph loaded (152 files, node --check clean)
✓ 113 dynamic prompts loaded
✓ promptSuggestion() ran; {#random} expanded

The tree was then reorganised so that all code lives under src/ and all prompt content under data/, with runtime and user data left at the root. That’s a careful change, because the loaders resolve paths relative to files, not the working directory. To prove nothing was lost, the original pre-revival source was pinned as a read-only snapshot and diffed against the current tree:

All 96 curated data files matched the original line-for-line; of 158 shared code files, the differences were either formatting or understood, deliberate refactors.

Documentation, end to end

Finally, the project was brought up to the same management system as its sibling — living notes, a single-source version number, a documentation site, and CI/release workflows. The documentation went all the way to per-function coverage across the server engine, all 113 generators, the classic frontend, and the React web app, settling on JSDoc with the notes wired in as tutorials — one site of around 244 pages.

References

• Random AI Prompt repository · documentation site
• Node.js release schedule (Node 24 “Krypton” LTS)
• node:module createRequire · MDN: JavaScript modules
• JSDoc

The bug under the redesign

The General-tab work ended on a real, long-standing bug: the type dropdowns displayed the wrong type for every Pokémon — a Charizard reading as Ghost/Fighting instead of Fire/Flying — and “reset to default” appeared to do nothing. A diagnostic test proved the stored data was correct all along; the combos just rendered it wrong.

The cause was an off-by-one. The type list has a “no type” placeholder at row 0, so a type stored at index i lives at model row i + 1 — but the lookup returned i:

// TypesModel::valToIndex — "-----" placeholder sits at row 0
- ret = i;        // selects one row early → Fire shows as Ghost, Flying as Fighting
+ ret = i + 1;    // account for the placeholder

The first regression test for it was tautological — it compared the result against the same source the method reads, so it passed regardless. It was rewritten to assert the literal type IDs (Fire = 20, Flying = 2), which is the difference between a test that guards behaviour and one that just agrees with the code.

A binding instead of a toggle

The DV/EV tab’s “Future Shiny” control highlights a small but useful QML pattern. Shiny status is derived from DVs, so the selection has to mirror live data — dragging the DV sliders should flip it on its own. A checkable toggle can’t do that (a click would break the binding), so each segment’s active state is a plain binding to the data, and clicking performs the action that changes the data:

SegSel {
    active: boxData.isShiny          // a binding, not a checkable state
    onClicked: boxData.makeShiny()   // changes data → re-drives `active`
}

One source of truth, no drift.

Closing the loop on data safety

The day finished with a data-integrity pass: destructive editor actions — re-roll, reset, max out, evolve, and the bulk move operations — now ask for confirmation through a shared dialog, while harmless per-field actions don’t. A status badge was added to the Pokémon preview, and the level field was widened so “100” fits.

References

• Pokered Save Editor 2 repository · documentation site
• Gen 1 shininess is derived from DVs (Bulbapedia) · QML property binding

The disassembly as the authority

The Market’s flat “Normal Items” list was split into meaningful groups, with the documented Pokémon Red disassembly (pret/pokered) as the oracle. Two of its data files settle the questions:

• data/items/prices.asm — the per-item buy price (sell is half). A price of 0 means the item can’t be priced or sold.
• data/items/marts.asm — what’s actually stocked; the buyable set is the union of every reachable shop’s inventory.
• data/items/vending_prices.asm — the Celadon roof vending machine (a separate vendor).

The membership sets were transcribed straight from those files into the model, each index commented with its item name:

// indices transcribed from pret/pokered data/items/marts.asm + vending_prices.asm
static const QSet<int> kBuyableInGame = { /* Poké Ball, Potion, Antidote, …,
                                             TMs 01,02,05,07,09,17,32,33,37 */ };

bool ItemMarketModel::buyableInGame(ItemDBEntry *e) {
    return kBuyableInGame.contains(e->index());
}

Items group into Normal (a shop sells it), Vending Machine (the three roof drinks), and Special (priced but no in-game vendor). Items with no price at all are listed nowhere, because there’s genuinely no way to buy or sell them.

A naming sweep, and the trap inside it

A display-wide sweep corrected “Poke” to the accented “Poké” everywhere user-visible — Poké Mart, Poké Ball, Pokédex — touching only display strings, never identifiers. That tripped a subtle trap: one item name doubles as a lookup key in the map data, so renaming it orphaned a link until the data reference was updated to match:

maps.json:  "item": "Poke Ball"   →   "Poké Ball"   (kept in lockstep with the rename)

A reminder that display text and data keys aren’t always separable. The editor’s target was also documented explicitly as the US English release of Red and Blue.

Detailed item tooltips

Finally, the long-deferred detailed-tooltip feature was built as a working vertical slice: an optional info field per item, plumbed through to a tooltip with a title and wrapped body, with the first eleven items’ descriptions authored and checked against the disassembly. The rest of the items, and wiring the tooltip into the other screens, are the next steps.

References

• Pokered Save Editor 2 repository · documentation site
• pret/pokered data/items/ (prices.asm, marts.asm, vending_prices.asm)

The Market rework

The screen became a clean two-pane layout: a shopping list on the left and a cart that reads like a store receipt on the right, itemised with a running total. Buying and selling were unified into a single cart per currency, summing into one net total, and the mode controls moved out of the footer into segmented header strips.

The standout fix was the money/coins exchange. A coin is worth ₽20 — confirmed in the game’s own data (gameCorner.json "price": 20) — but the conversion was inverted:

A coin is worth ₽20.

  old:  coins = rate × money      → ~20 coins per ₽1   (inverted — wrong direction)
  new:  money = rate × coins      → ₽20 per coin        (correct)

So the data was right and the C++ math was wrong. It was reworked into a clear converter — money on one side, coins on the other, live deltas above each. To check this kind of thing against an authority, the documented Pokémon Red disassembly (pret/pokered) was cloned in as a read-only reference. The rework also surfaced another use-after-free, traced with a debugger to shop entries being read from cross-instance static registries after they’d been freed; the fix sweeps only the current model’s live entries.

An automated screenshot pipeline

A headless tool now boots the real UI and captures PNGs of every screen and several states — and it only ever reads the save in memory, so it can’t touch save data. Getting it to render correctly offscreen took working through several quirks (missing fonts, blank grabs, dropped visual effects), ending on a real but hidden GPU window:

# render through a real GPU window, parked off-screen, so effects actually draw
PSE_SHOT_SIZE=750x480   # capture at the app's real window size

A release pipeline

A GitHub Actions workflow now builds and publishes a GitHub Release, gated so it only fires when the version was actually bumped:

The first release, v0.7.2-alpha, went out with all six artifacts after the usual first-run shakeout (a windeployqt flag unsupported on the llvm-mingw toolchain, an Inno Setup path quirk, and a Linux binary-location difference). Screenshots and docs are also served from GitHub Pages, so they stay current without bloating the repo.

References

• Pokered Save Editor 2 repository · documentation site
• pret/pokered (the save-format / pricing oracle)
• GitHub Actions · Inno Setup · linuxdeploy