Changelog

📝 Changelog

All notable changes to Formamorph. This fork's first line is 2.0.0 — a full TypeScript rebuild of the upstream JavaScript app (FieryLionite's Formamorph, ~v1.2) — with feature parity as the baseline plus new features on top.

✅ 2.0.0 – 2.6.0 are released (collapsed below). New work lands under 🚧 In Progress — an unnumbered section, so changes accumulate without pinning a version. When a batch earns a release its section is marked Released and collapsed, and a fresh In Progress opens. package.json reads 2.6.0 — the latest released version.

Each release groups changes as Major / Minor, then Added / Removed / Fixed, and within those by audience: 👤 user-facing · 🛠️ developer tooling · ⚙️ backend / invisible.

---

🚧 In Progress

Unreleased — new work accumulates here until it earns a version bump. The next batch will pin its own version; package.json reads 2.6.0 (just released below).

Minor Changes

✨ Added

• 👤 User-facing

  • A broken AI connection no longer strands you on the main menu. The "can't reach your endpoint" warning used to fire when you tried to enter a world, and it refused to close — so a server that wasn't running yet meant you couldn't get in at all. It now appears once the world has loaded, and you can dismiss it: read the world, look around, open Settings and fix the endpoint from inside the game. Nothing is lost by continuing — only the turn itself needs the AI, and the warning still disappears on its own the moment your server answers. The first-run "set up your AI" prompt is unchanged.

• 👤 User-facing

  • Swap between text endpoints with presets. Settings → AI Endpoints → Text now has a preset picker, matching the one the Image tab already has. Save several endpoint configs — a cloud model, a local server, a friend's API — and switch between them from a dropdown instead of retyping the URL, token, model, context window, and output cap each time. An immutable Default entry always sits at the top: it's the shared built-in endpoint, read-only, and can't be deleted or renamed — pick it to go back to "just use ours". On the web the picker replaces the old Use Custom Endpoint checkbox (selecting a preset other than Default is using your own endpoint); on the desktop app it appears only when Use My Own Endpoint is checked, since a bundled local model has no endpoint to swap. Your existing endpoint carries over into a preset automatically.

• 👤 User-facing

  • Direct the story with [square brackets]. Bracketed text in your action now speaks to the AI as the author, not your character — I climb on behind her. [She agrees, and they ride off.] steers what happens, its pace, or its tone, without your character saying a word of it. The direction never appears in the story's prose, and the turn's memory records only what actually happened. The action box's placeholder hints at it, and a ? beside the box opens a How to Play popup (it glows until first opened, like the World Editor's) with four short tabs: writing actions, choices (including Ctrl+click — press-and-hold on mobile — to stack a choice onto your action instead of replacing it), directing with brackets, and how the story's memory and Notes work — with the Choices and Memory Summaries settings right there in their tabs.
  • A Messages view for the narration prompt. Settings → Prompts → Narration's growing row of message editors (Recap Message, Recall Message) is now one Messages view: the conditional lines that ride the story exchange, stacked with their own reset buttons, each appearing only while its feature is on. It also gains the new Direction Message — the line sent alongside a [bracketed] action, now editable per preset like the rest (older preset files simply keep the default).

• 👤 User-facing

  • Semantic Lore (experimental). A companion toggle to Semantic Memory, off by default. Dictionary entries can now also activate when your action's meaning matches them, even with none of their keywords in the text — "I climb the ruined tower on the headland" wakes an Old Beacon entry whose keywords are only "beacon, lighthouse". Keyword activation is completely unchanged; meaning-matches only ever add entries (at most three per turn, above a tuned similarity bar). The AI-context legend marks them with ≈ and shows the similarity, since there's no keyword hit to highlight. Uses the same on-device model as Semantic Memory. For authors: a clear, concrete entry description now doubles as its activation net — sprawling synonym keyword lists become optional rather than necessary.

• 👤 User-facing

  • Scene Recall (experimental). The third semantic toggle, under Semantic Memory, off by default. When your action clearly returns to an old moment — pulling out the keepsake a dead friend carved you — the game brings that turn's full original narration back for the AI, word for word, framed explicitly as a remembered scene ("this already happened; everything since still stands"). Never presented as recent history, at most two scenes per turn, and never near-duplicates of each other or of recent turns — the guard against the repetition freeze that got the old keyword version of this feature removed. Measured on both test models: a planted scene detail no summary carried (a carved gull whistle) surfaced in 0–1 of 3 runs without recall and 3 of 3 with it, with zero cases of the dead friend being written back alive.

• 👤 User-facing

  • Memory Cap (experimental). An always-on companion to Semantic Memory, off by default. Normally every surviving memory rides along each turn, growing with the story; with a cap set, only the N most relevant to your current action ride — even when more would fit — keeping long-story prompts small and sharp. The story's opening and the newest memories always stay, and without relevance data the cap simply does nothing (it never trims blindly by age). Measured on both test models with a 28-memory story capped to 12: recall of a planted old fact held or improved (25%→33% cloud, 83%→92% local) while carrying 57% fewer memories.
  • The Scene Recall prompt is editable. Settings → Prompts → Narration gains a Recall Message view beside the Recap Message (shown while Scene Recall is on): the line that frames a recalled scene as the past is now yours to edit per preset, with the same reset-to-default. Saved and shared presets carry it like any other prompt text; older preset files simply keep the default.
  • Diary Recall (experimental). The fourth semantic toggle — under Semantic Memory, shown with Character Diaries in Staged mode, off by default. A character's motivation pass used to carry only their five newest diary entries; now it carries their three newest plus up to two relevant older ones — she remembers the last time you put a hand on your knife, even if it was thirty turns ago. Same total entry count, so it costs no extra context, and a near-duplicate guard stops a brooding character's five identical "I still don't trust them" lines from crowding out the one distinct memory. Retrieval is deliberately conservative (short diary lines are the hardest texts to match): it stays quiet unless the match is strong.

• 🛠️ Developer tooling

  • Diary-retrieve probe. diary-retrieve-probe.mjs + semantic-diary-cases.json: threshold sweep on diary-shaped first-person entries, shared-word guard asserted, precision/recall per threshold with the shipped value marked.
  • Rehydrate probe. rehydrate-probe.mjs + semantic-rehydrate-cases.json: the dead-Jim temporal fixture — three arms (no recall / bare-pair splice / framed exchange), alive-write and detail-recall metrics, including a bait case the scene itself sets up.
  • Semantic-lore probe. semantic-lore-probe.mjs + semantic-lore-cases.json: threshold sweep for meaning-based dictionary activation — paraphrase actions (asserted keyword-free) vs unrelated actions, precision/recall per candidate threshold, shipped value marked.
  • Semantic-band probe. semantic-band-probe.mjs + semantic-band-cases.json: A/Bs the two digest-band trim strategies on a 28-digest story with planted old facts — a deterministic trim-survival stage (embeddings in Node, no LLM) and a narration-recall stage on both test targets.
  • Recall-margin probe. recall-margin-probe.mjs + semantic-recall-margin-cases.json: a same-cast one-house fixture where every scene clears the absolute floor — margin-over-median sweep (return-hit and charged-clean rates per margin, deterministic, embeddings only) plus a bare-vs-enriched query arm that settled the recall-query question.
  • Sem A/B scorer + rerank probe. sem-ab-score.mjs (objective scoring of the 50-turn semantic-memory A/B runs: planted-fact recall, 8-gram repetition, request size, digests riding) and t6-rerank-probe.mjs (cross-encoder rerankers vs cosine on the A/B's real failure cases — three browser-size families, raw-logit scoring).
  • Freeze-replay probe. freeze-replay-probe.mjs: replays a real failed session's scene-recall selection from its AI-context dump, old stack vs shipped stack — the validation that closed the charged-scene freeze gate (26/34 turns firing → 6/34, zero consecutive repeats).
  • OOC-channel probe. ooc-probe.mjs: three-arm A/B (no convention / system-prompt line / line + user-slot rider) over bracket-direction cases built from the real T27/28 stall, with compliance/defiance/leak metrics and bracket-free control cases as the false-positive guard.
  • Incremental milestone probe mode. milestone-select-probe.mjs --mode incremental: batch-of-1 replay of the labeled fixture through the write-time selector — end-state scoring, must-forget tracking, and the prompt-arm history that produced the shipped paired-forget protocol.
  • Dialogue probes match the production message shape. dialogue-probe.mjs and dialogue-unbaited-probe.mjs now send the player action bare, without the Player action: wrapper the app dropped — their NPC-spoke rates measure the same request the game sends.

• 👤 User-facing

  • Semantic Memory (experimental). A new toggle under Settings → Gameplay, off by default. When the story's remembered moments no longer fit the context budget, the game normally lets the oldest go first; with Semantic Memory on it instead keeps the ones most relevant to what you're doing right now — an old promise resurfaces when you return to the person you made it to. Relevance is judged by a small AI model running entirely on your device (a one-time ~23 MB download when you enable it); nothing about your story leaves your machine, and if the model isn't ready the game simply falls back to the old behavior. The milestone keep/forget system and your pins are unchanged — this only reorders what gets trimmed under pressure.

• 👤 User-facing

  • Setting descriptions moved behind an info icon. Every setting's explanation used to sit inline as a paragraph of gray text, so a tab full of settings read as a wall. Each row now shows the control with a short one-line summary, and its full description opens from a small ⓘ next to the label — so the tab stays scannable and the detail is one click away. Nothing was hidden that you can't reach in a tap, and the icons line up in a column down each tab.
  • Settings tabs are grouped instead of one long list. Presentation, Generation, Accessibility, and Image Gen now break into labeled sections — Appearance / Scene / Narration, Turn Extras / Reasoning / Memory / Performance / Inspection, Reading / Saves & Worlds, and Connection / Image — so a tab reads as a few named blocks rather than a wall of rows. Nothing was added, removed, or renamed — only regrouped, with Narration Reveal and AI Language moved down beside the other narration settings.
  • The Endpoint and Image Gen tabs are now one — AI Endpoints. The two endpoint tabs merged into a single tab with three sub-tabs: Text (your language-model endpoint), Image (the image-generation provider and its presets), and Tag Prompt (the booru-tag prompt). Every field and preset is exactly where it was, just under one roof — Settings now reads as five tabs instead of six, which also fits a phone better.

• ⚙️ Backend / invisible

  • Scene Recall cooldown. A scene that just rode as a recalled memory sits out the next 2 turns before it can be recalled again, so the same moment no longer rides turn after turn while the story stalls. Re-rolling a turn reproduces its original recall exactly.
  • Memory Cap on by default. With Semantic Memory on, the story's long-term recap now keeps the 12 most relevant memories per turn by default instead of everything that fits (the number stays editable in Settings, 0 = uncapped). A 50-turn A/B showed uncapped recaps growing to ~48 memories with markedly more repeated narration; the cap cut request size ~40% on the local tier with recall of planted facts largely held. Fresh installs only — existing installs keep their stored value.
  • Sticky memory verdicts. The story's keep/let-go memory decisions are now made once, when a moment ages into long-term memory, instead of re-voting the whole list every turn — so memories no longer flip between kept and forgotten as the story grows. A kept memory changes only when a newly kept moment explicitly replaces it (a promise fulfilled supersedes the promise) or when you pin it. Verdicts are saved with your game, and the recurring memory-selection request shrinks to just the new moments.
  • Scene Recall margin threshold. A scene is only recalled when it stands out from the story's own baseline relatedness (beats the median similarity by a margin), not merely when it clears a fixed score — in a one-house same-cast story everything clears a fixed score, which had let one scene fire ten times during unrelated moments. Early game (fewer than 5 candidate scenes) keeps the old fixed-score rule.

🐛 Fixed

• 👤 User-facing

  • Optimizing images no longer freezes the app. The World Editor's Optimize Images button (and the same optimize step on world import, export, and backup restore) now does its image crunching off the main thread, so the interface stays responsive instead of locking up while large images re-encode. The button also shows a spinner and a live Optimizing 3/12… count while it works, so it's clear something is happening.
  • Markdown headings, blockquotes, and code render properly. # and ### headings came out at body-text size (a # heading looked identical to a ##### one), and blockquotes had no indent or quote bar at all, so nesting them showed nothing. Tables, inline code, and code blocks were missing their styling too. All of it now renders as intended — headings step down cleanly from # to ######, and nested blockquotes indent per level.
  • Subscript and superscript now work in Markdown. Write H~2~O and x^2^. They nest, and they leave ordinary prose alone — "about ~5 minutes and ~10 more" stays exactly as typed, since the shorthand never spans a space. ~~Strikethrough~~ is unchanged, and writing <sub>/<sup> HTML directly still works as before.
  • Help popup tabs are centered. The How to Play tabs sat left-aligned, so on a phone — where they wrap onto two rows — the rows lined up raggedly against the left edge. They now center, on both rows and on desktop's single row.
  • Worlds with no locations yet start properly. A world that hadn't had any locations authored — which every newly created world starts as — skipped its entire game setup on launch: the opening story prompt wasn't placed in the action box, and stat starting values, traits, and dictionaries were never applied for that playthrough either. Existing worlds were unaffected, since they all have at least one location.
  • Closing the World Editor cancels an in-progress image optimization. Exiting mid-optimize used to leave the run going invisibly: re-entering made the Optimize Images button feel dead for seconds (the abandoned run still owned the encoder), and when the orphaned run eventually finished it silently wrote its stale snapshot back over the world — undoing any edits made since. The run now stops within one image of exiting, a canceled run never writes anything, and the button shows "Scanning…" from the moment it's clicked so there's no feedback gap before the choice dialog.
  • The Diary prompt is hidden unless Staged thinking is on. Settings → Prompts only showed the Diary tab based on the Character Diaries toggle — but diaries are only used by Staged mode, so the tab could linger after switching thinking modes. It now appears only when both are active, matching the toggle that governs it.

• ⚙️ Backend / invisible

  • Image encoding runs in a Web Worker. The decode → downscale → WebP re-encode pipeline (including the lossless WASM path and the image measuring/scanning step) moved into a dedicated worker with a main-thread fallback, and world-optimize reports per-image progress. Public imageOptim API is unchanged. Verified live: optimizing three ~30 MB images produced zero main-thread long tasks (previously 7–15 stutters of ~100 ms each).
  • Workers now load correctly in dev. The image-encode and save conversion/download workers are created as module workers — in dev, Vite serves their source with bare ESM imports, which a classic worker rejects, so they silently fell back to the main thread (or failed). Production builds were unaffected.
  • One worker now handles every JSON file. Save downloads used a worker of their own that built a base64 data URL; worlds, backups, and saves all share one JSON worker that hands back the file directly, so the extra encode step is gone. Downloaded files are byte-identical.
  • World and backup files are written and read off the main thread. Exporting a world, saving a backup, and importing a world file each ran one long blocking call over the file's whole text — with images embedded as base64, that froze the UI for seconds on a large world. All three now run in a Web Worker.
  • Model previews no longer stall on load. The model viewer decoded a model's data by hand, one character at a time, before three.js ever saw it — a multi-second freeze and a large memory spike for a big VRM. It now hands the browser the decode, and cleans up correctly if the viewer closes mid-load.

---

✅ 2.6.0 — Released 2026-07-23 — the memory release: a milestone system that keeps what actually matters with a Memory tab to pin or forget moments, digests that preserve names, places, and deadlines and travel as a single story recap ending with where things now stand, characters that engage you in dialogue several times more often, editable narration User and Recap Messages — plus a long tail of save, stat, model-viewer, and editor fixes (click to expand)

Minor Changes

✨ Added

• 👤 User-facing
  • Milestone memory: the story now remembers what matters. With Memory Digests on, older turns used to ride along as an ever-growing list of one-line summaries — most of them noise ("you walk the bridge road…") that crowded the story's context and, measurably, dragged characters toward silence. Now a silent AI pass reviews those older summaries each turn and keeps only real milestones — promises made, debts owed, wounds taken, things gained, how characters came to see you — while recent turns always stay. In testing this held dialogue as well as sending the full history at roughly a quarter of the context size, and it means long sessions stop growing their prompt every turn.
  • A Memory tab in the game side panel. See exactly what the story remembers long-term: kept moments in full, let-go moments faded. Pin a faded memory to bring it back for good, or forget a kept one — your pins always override the AI's choice, and they're saved with your game. Memories appear the turn they form — the newest sit under a subtle "Recent" divider (those turns are still in the story's full view regardless; the keep/let-go verdict takes effect once they age out of it).
  • Characters engage in conversation several times more often (thinking off). The character's-own-voice rule now also rides directly beside your action in the narration request — the position the AI weighs most. Measured on the default endpoint across four test batches: roughly 3× more turns where characters genuinely engage you in dialogue, including the first-ever 50-turn session that never lost its dialogue; on a strong local model, a perfect score with no side effects. Applies when Thinking Mode is off (other modes already carry the rule in their prompt); if you've customized the narration User Message, your version is kept.
  • The narration prompt's User Message is now editable. Settings → Prompts → Narration gains the same System / User Message toggle the other prompts have. By default it is exactly the Player Action chip — byte-identical to what the game always sent — but you can now add your own standing text around it. A word of care: this text rides directly next to the AI's reply, the most influential position in the entire prompt, and our testing consistently shows extra wrapping here can mute character dialogue. Your story history always records the plain action regardless, so experiments never rewrite the past.
  • Memory Digests is now on by default for new installs — with milestone memory it is simply the better way to play; existing installs keep whatever they had.
  • Narration now keeps 4 recent turns in full (was 3). Paired long-session sweeps of the verbatim window (2 vs 3 vs 4 vs 5, six 50-turn runs each) put the dialogue-holding peak at 4: fewer full turns starve the AI of dialogue examples to imitate, more just adds weight that drags it toward silence. Applies only if you haven't set the Narration verbatim-turns value yourself.

🐛 Fixed

• 👤 User-facing

  • Characters speak up a little more often. Your action now reaches the AI as plain text instead of behind a Player action: label — matching how past turns already appear — which measurably nudges the narrator toward spoken dialogue on charged scenes, with no change to anything you see or type.
  • Characters confirm less and carry the scene more. Two vague narrator guidelines rewritten to say what they actually mean: "stay consistent with the story so far" (which quietly encouraged repeating the story's question habit back at you) is now a concrete continuity rule — positions, objects, and what's been said carry forward unless the action changes them — and the undefined "your reply is complete once the events have been told" clause is simply gone. Measured together on a real stuck session: character turns that end by re-asking something you already answered dropped ~58%, with slightly more spoken dialogue, on both test models.
  • Characters say what they want instead of asking if they may. One word in the narrator's dialogue guidance — characters "asking for what they want next" — read to the AI as a license to seek permission, feeding the confirm-everything habit on charged scenes. It now reads "voicing what they want next": on the default endpoint that nearly doubled turns where characters genuinely engage you (with charged-scene dialogue holding steady across a whole session instead of fading), and on a strong local model it added ~27% more spoken dialogue with no change to its confirmation habits. Credit where due: found by chasing the theory that the AI wrongly believes it needs the player's explicit permission for things to happen.
  • Characters answer you in their own words. When you speak to a character, the narrator could voice your question aloud and then have the character "answer" with only body language. The narration prompt now closes with an explicit contract: the character's spoken, quoted reply is the scene's answer — measured to roughly double the rate of turns where a character genuinely engages you in dialogue.
  • Reordering keyword/value chips works across multiple rows. When a keyword or placeholder-value list wrapped onto more than one line, dragging a chip on a lower row dropped it in the wrong spot. Chip reordering now tracks correctly regardless of how the chips wrap.
  • Dragging a dictionary entry drops it where you aimed. Dragging an entry down past others in the same zone landed it one slot higher than the drop indicator showed, and picking an entry up and dropping it without moving would banish it to the bottom of the list. Both now land exactly where the preview indicates. Upward drags and moves between zones/dictionaries were already correct.
  • Exported world files always end in .json. Downloading a world whose name was set produced a file with no extension, which the import picker then filtered out. The download now always carries the .json extension.
  • Character cards export reliably, even for small portraits. Exporting a character whose portrait was already small/well-compressed could fail with "Could not encode the portrait as WebP" — the export now always produces the WebP the card format needs.
  • A corrupt saved setting can't stop the app from starting. A single malformed value in browser storage (from a bad write, a half-finished migration, or manual tinkering) could throw while the app read it during startup and leave you on a blank screen. Settings now fall back to their default when a stored value can't be read, and quietly rewrite the good value back.
  • The Edit Text box no longer keeps edits you canceled. Making changes in the narration Edit Text box, cancelling, then reopening the same page could leave your abandoned changes sitting in the box. It now starts fresh from the saved text each time you open it.
  • Clearing a numeric setting no longer saves a zero. Emptying Max Output Tokens or an image width/height/steps/CFG field used to store 0 immediately — which then sent a broken request. Cleared fields now fall back to their minimum instead.
  • Editing a character or dictionary no longer discards your work if the save fails. "Save & Exit" on the unsaved-changes prompt used to close the editor even when the save errored — so the edits were gone despite the error message. It now stays open on failure so you can try again; same fix for the world editor's exit prompt.
  • A failed or empty AI turn no longer quietly breaks the rest of your session. When the AI returned nothing (or the request errored) partway through a turn, that turn's action was left stranded in the story history — which then paired every following turn against the wrong message, silently dropping older turns from what the AI could see. Failed turns now clean up after themselves and hand your previous choices back, so you can simply try again.
  • Switching worlds no longer shows the wrong world's comments. Opening one community world's details and quickly opening another could drop the first world's comments into the second's panel if its response arrived late. Each world's comments now stay with that world.
  • Re-rolling a turn's stat changes keeps the turn's regen. Re-rolling only the stat updates for a turn recomputed your stats from the pre-turn baseline plus the new changes — quietly dropping that turn's regeneration/starvation tick, and leaving stale colored deltas on the stat bars. The re-roll now reproduces the full turn (changes + regen), without advancing the clock a second time, so your stats and the bar match a normal turn.
  • Turning off narration read-aloud mid-turn no longer bleeds into the next. Stopping speech while a sentence was still being generated could play that leftover audio into the following turn and shift the word highlighting. Canceled speech now stays canceled.
  • Stop behaves correctly at every point in a turn. Pressing Stop while the narration was still fading in used to let the turn finish anyway (choices and stat changes landed as if you hadn't stopped); pressing Stop while the game was working out an automatic location move could corrupt the previous turn's saved state and blank its choices. Both now stop cleanly. And exiting to the menu mid-turn now cancels the AI request instead of leaving a model generating a reply into nothing.
  • The in-game character model appears as soon as it's ready. The model panel used to wait a fixed 5 seconds before showing your character, regardless of how fast it loaded. It now appears the moment it's ready — instantly for the default model, and after just the real load time for a custom one — while still avoiding the brief flash of the default model that the wait was there to hide. A deleted custom model also no longer leaves the panel spinning forever.
  • Your in-game body matches the customization screen. Body Weight and Breasts Size were applied at double strength once you were in-game — so the model looked heavier/curvier than the preview you set it to. The in-game model now renders exactly what the customization screen shows.
  • Customization now shows a slider for every body shape your model supports. The body sliders used to be a fixed pair (Body Weight, Breasts) — so any other body morph a model exposed was unreachable. Customization now reads the loaded model and gives you one slider per body morph it actually has, labeled by name. Sliders run from -25% to 125% of the model's authored shape (0% = off, 100% = the shape as sculpted). Existing characters carry over unchanged.

• 👤 User-facing (memory)

  • Long sessions no longer starve the narration. With Memory Digests on, older turns used to ride the story's context as many one-line exchanges — and after enough of them, some models started imitating that brevity, collapsing narration from full paragraphs to a sentence or two that could even drop a character's reply mid-scene. Those digests now travel as a single recap exchange — the story asked "Recap the story so far." and answering in one block — which reads as a recap, not as how narration should look. Measured on a real collapsed turn: ~40 words and the NPC's answer lost 4 runs in 5 before, ~125 words and the answer present 5 for 5 after, with no change on models that never collapsed. The recap question itself is editable: Settings → Prompts → Narration → Recap Message.

• ⚙️ Backend / invisible

  • Prerelease updates past .9 are offered correctly. The update check compared prerelease versions as text, so a build like beta.10 looked older than beta.9 and was never offered. Numeric parts of a prerelease tag now compare numerically.

  • Imported prompt-preset share codes are validated more strictly. A hand-crafted share code could smuggle a non-numeric sampler value (e.g. a text temperature) into the AI request, making every call fail. Sampler settings from a share code are now validated and dropped if malformed, like the other tuning fields already were.

  • Desktop app: tighter update and download hardening. The auto-updater now refuses a payload it can't checksum (instead of trusting the connection alone) and the Windows launcher re-verifies the staged download's checksum before installing it; a disk-full or write error during a model/update download now surfaces a clean error instead of crashing the app; and the app window is pinned to its own origin so rendered content can't navigate it elsewhere. The app:// file-serving path also got a stricter containment check.

  • Loading a save from another installed world migrates that world first. Cold-loading a save whose world was an older format could restore against the un-migrated world data, bypassing the compatibility net. The save now restores against the migrated world, and the world details/duplicate paths cache the migrated copy too.

  • New and duplicated worlds get collision-proof IDs. Their IDs were minted from the current timestamp, so creating or duplicating two worlds within the same millisecond could collide and overwrite. They now use a random UUID like every other generated ID.

  • The choices prompt's "who's in the scene" filter now covers every Entities chip format. Choices are shown only the characters actually present this turn, not everyone at the location — but if you'd edited the Choices prompt to use an XML-format Entities chip, that filter was bypassed and the full roster leaked in. All chip formats (plain, markdown, XML; full and summary) now get the scene-only roster, hoisted to one shared path so the list can't drift again.

  • Image generation and downloads can't hang forever anymore. A ComfyUI run that failed server-side (bad graph, out-of-memory) used to leave the app polling for an image that would never arrive; it now detects the failed run and surfaces the error. A community download that stalled mid-transfer is now cut off after 30s of silence instead of hanging, and a failed desktop update download now shows an error you can retry from rather than sticking on "downloading".

  • Context-window auto-detection can't save the wrong endpoint's value. Editing the custom endpoint while a detection probe was still running could persist the old endpoint's context size against the new one; the probe result is now discarded if you've moved on. The admin user search was likewise hardened against a stale page of results landing after a new search, and its query is now URL-encoded.

  • Trait stat effects apply once, not once per rule. A trait that both raised a stat's floor and shifted its cap could over-adjust the stat's value — the pull-to-floor correction was re-applied for every rule the trait carried instead of once. Now applied a single time per stat.

  • The 3D character viewer no longer leaks when you switch models. Swapping the previewed VRM while its model was still loading left the old model's animation loop running forever against a discarded scene, quietly piling up over a session. In-flight loads are now cancelled on switch.

  • The save database opens one connection instead of one per operation. Every save read/write used to open a fresh IndexedDB connection and never close it, so autosave leaked handles each turn — enough of them would have blocked a future save-format upgrade. The connection is now opened once and reused.

  • The story recap now ends with where things stand. The memory recap read as pure backstory — a chronicle with no now — and on some models that caused real harm: a live mid-scene conversation re-opened as a fresh arrival scene, and a standing roleplay agreement lost out to the recap's older framing, inverting who was playing whom. The recap block now closes with a code-built line stating the present: current location, who is present, and your Player Notes verbatim ("the player's own notes hold true: …"). Replayed against the real failing turns, the scene-reset and identity-inversion failures disappeared from every run; no AI call is added — the line is assembled from state the game already tracks. This also gives Player Notes a much stronger seat: they now ride right beside the story instead of only sitting mid-prompt.

  • Long-term memory now keeps the facts that govern the story, not just its events. The milestone selector judged memories by what happened — promises, debts, things gained — so standing state fell through: in real sessions it forgot the player's own stated goal and an in-effect roleplay agreement, leaving later scenes misread. Two fixes: the selector's keep-criteria and worked example now cover a role or pretense being played and the player's stated errand (probed: the goal digest went from dropped 3/3 to kept on both test models), with the example rewritten in placeholder form — generic <entry> slots instead of a concrete mini-story, so the model learns the reasoning rather than pattern-matching real play against example content; and the story's opening memory is always kept as an anchor — with it gone, models wrote a fresh arrival scene over the live one. A player's drop-pin still overrides the anchor.

  • Memory digests keep the facts, not just the shape of them. The turn-summary prompt compressed specifics into categories — "you state your destination and deadline" with the place and date gone for good, since a digest is all that survives of an old turn. Three rules rewritten: specifics stay specific (names, places, objects, amounts, deadlines go in as themselves, from the player's action or the narration), speech's upshot carries what was actually named, and a fact-dense turn is what the allowed second sentence is for. Probed on both test models: fact retention on the default endpoint rose from 8/21 to 18/21 planted facts (both runs), and the strong local model — already retaining everything — cut its over-long two-paragraph digests by two-thirds as a side effect.

  • Memory digests no longer teach the narrator past tense. With Memory Digests enabled, the one-line turn summaries were written in the past tense, and a history full of them could drag the whole story's narration into past tense (and mute dialogue) on some models. Summaries are now written in the story's own present tense — measured to eliminate the tense drift entirely and to make repeated-phrasing echo drop rather than rise.

  • Narration prompt trimmed. The Player Stats section's preamble line duplicated the stats guideline bullet; a section-by-section ablation on both test models measured it inert, so it's removed to spare prompt tokens.

• 🛠️ Developer tooling

  • Now-line probe. New now-line-probe.mjs: replays a real session turn's narration context with and without a proposed recap closing line, for judging mid-scene anchoring and frame-fact fixes against the exact contexts that failed.
  • Summary probe measures fact retention. summary-cases.json gains three planted-fact cases (a stated goal with name/place/deadline, an introduced personal object, a named price) with per-case require regexes; summary-probe.mjs scores them, honors per-model endpoint overrides, counts the player's action as legitimate name material, and sends reasoning_effort: "none".
  • Quality baseline profile + scorer. New harness Profile Q: a 25-turn scripted Sedge Landing session with planted facts, question turns, action-outcome turns, and an agency trap, paced so memory digests drain like real play; qualityScore.mjs scores the countable side (planted-fact recall, cross-turn 8-gram repetition, sentence shape, format violations).
  • Digest-framing probe. New digest-framing-probe.mjs: replays a real collapsed turn's context in three message shapes (paired one-line digests vs one grouped block vs a "Recap the story so far" exchange) to isolate why narration length collapses once digests dominate the history.
  • Strict dialogue-hold probe. New dialogue-hold-probe.mjs + charged-interview-corpus.mjs: 25 consecutive baited turns (every action directly asks a willing character to speak) scored on a strict bar — a character must speak at least two quoted sentences that engage the ask, player-voiced lines excluded — with per-turn trend reporting, so a steadily decreasing dialogue rate registers as a failure even when the average looks fine.
  • Milestone-memory harness. New milestone-select-probe.mjs (hand-labeled 57-entry fixture across four story genres; must-keep recall and noise-keep metrics; prompt variants including the shipping few-shot selector) and carryforward-check.mjs (re-derives each chain's kept/dropped split and judges every dropped fact against late narration for contradictions), plus a selection-driven arm M in the dialogue-hold probe.
  • Format-arms probe: hybrid arm + edit crossing. format-arms-probe.mjs gains arm H (bare history with the label on the current turn only — byte-faithful to the app's real message assembly) and --edit variants now cross with --arms, so e.g. --arms H,B --edit fuse runs both cells fused in one paired batch.

✅ 2.5.2 — Released 2026-07-21 — entity aliases and smarter plural detection, a new Percentage stat type, an action box that grows into a popover, an editable opening scene, and self-sorting stat descriptors — plus narration fixes that keep characters talking through intimate scenes and stop them re-asking questions you already answered, dictionary triggers that cover everything the AI actually reads, and an end to reasoning errors on models that don't support reasoning (click to expand)

Minor Changes

✨ Added

• 👤 User-facing
  • The action box grows as you type — without shoving the game around. Writing a longer action now expands the input upward into a floating popover instead of pushing the narration and buttons out of place. It grows to a comfortable maximum and then scrolls inside itself, and drops back to a single line when you click away (your text is kept). Enter still sends; Shift+Enter adds a new line for multi-line actions.
  • You can edit the opening scene before it begins. The old Start Game button (which fired a hidden, uneditable opening prompt) is gone. When you enter a world the action box is now pre-filled with the editable opening cue — reword it, add a detail, or write your own — and pressing Send begins the story with exactly that text. Re-generating the opening turn drops it back into the box so you can change your starting action and try again.
  • Stat descriptors stay in order automatically. In the Stats editor, a stat's descriptors now keep themselves sorted by threshold (low to high) — the order the AI reads them in — so you no longer have to add them in the right sequence or delete-and-re-add to fix the order. Editing a threshold snaps the row into place when you click away. Existing worlds are read in the correct order too, even if their descriptors were saved out of order.
  • New "Percentage" stat type. Stats can now be a Percentage — a value pinned to 0–100% and shown to you and the AI as N% (e.g. 40%) instead of 40 / 100. It keeps everything a number stat has (descriptors, regen, dynamic code, body-slider bindings, don't-increase/don't-decrease locks); only the min/max range is fixed and the cap can never be moved. Switching an existing stat to Percentage snaps its value into range.
  • Help & changelog pop-outs read better. The in-app help, world Readme, and changelog pop-outs are taller (so long topics need less scrolling) while short ones still size to their content, and bullet lists now hang their wrapped text under the text instead of back under the bullet.
  • Smarter plural detection for entity names. The story parser now recognizes irregular plurals, so an entity named "Wolf" is detected when the narration says "Wolves" (likewise City→Cities, Child→Children, Person→People) — previously only a simple trailing "s" was caught. Applies to entity names and aliases alike.
  • Entity aliases. Entities now have an Aliases field — other names a character or thing goes by (e.g. "Synthia" also called "Matron" or "Em"). Aliases are detected in the story text just like the real name, so an entity is still recognized when the narration uses a nickname, and they're shared with the AI as "also known as" so it can use those nicknames naturally. Aliases travel with a world and with exported character cards.

🐛 Fixed

• 👤 User-facing

  • Quick Start now honors the author's default traits. The world modal's quick-start button (renamed from Skip Customize to Quick Start) skips the setup steps but no longer drops the world's Enabled by Default traits — it now starts you with exactly the defaults the author intended, instead of no traits at all.
  • Characters keep talking during intimate and physical scenes. On charged scenes — closeness, touch, intimacy — characters could fall silent for the rest of the session, the story collapsing into wordless description. The narrator's dialogue guidance now frames speech as part of physical action (words woven into movement) instead of a separate activity, and turn endings favor a spoken line. Measured on the default endpoint: roughly 3× more turns with dialogue and the silence spiral pushed much deeper into a session, with no stray chatter added to scenes where no one is present.
  • Characters stop re-asking questions you already answered. On charged scenes, characters could stall the story by re-posing the same question ("are you sure?", "tell me true") turn after turn even once you'd committed. The story planner and narrator now treat an answered moment as settled — characters act on what you said and the scene moves forward — while still asking genuine questions when you haven't answered yet. Validated against a real stuck session: turn-ending re-asks dropped ~64%, with dialogue volume and legitimate hesitation intact.
  • Fewer turns cut off mid-sentence. The automatic paragraph guidance overestimated how many paragraphs fit the response budget, so intense scenes could hit the token cap and lose their final sentences — often exactly at the payoff moment. The per-paragraph estimate is now calibrated from real play sessions, so the AI is asked for a length it can actually finish.
  • Player Notes now trigger dictionary entries. Keywords written into your Player Notes now activate matching dictionary/lorebook entries, just like the current scene and your action already did — previously notes were sent to the AI but never scanned for triggers.
  • Dictionary entries now trigger on everything the AI is actually told. The rule is now simply: if the AI can read it, it can fire a trigger. Previously only the current location and the characters present were scanned, so a keyword in a nearby or sub-location description — text the AI was being given every turn — silently did nothing. Those blocks now trigger too, and they trigger on exactly the wording the AI receives: where a block is sent as a summary, the summary is what's matched. Two quiet oddities are gone with it — entries could fire on the story's internal save-file structure, and could fire on full descriptions in cases where the AI was only sent the short version. Always-present text (the world description, your stats and traits, and formatting guidance) is still deliberately not scanned, since it repeats every turn and would fire constantly. Authors: a keyword that appears in a neighboring area's summary will now activate — which is the intended control, but worth a pass over entries with very common trigger words.
  • No more reasoning errors on non-reasoning models. When a model doesn't support reasoning (e.g. many local models in LM Studio), Formamorph now stops sending it reasoning settings — which previously made those backends error on every turn — and the Native Reasoning control is replaced with a short "this model doesn't support reasoning" note. Reasoning-capable models are unaffected.

• 🛠️ Developer tooling

  • AI Context viewer highlights only real dictionary matches. The Dictionary view in the AI-context pop-out used to run a plain case-insensitive keyword sweep over the whole prompt — highlighting text that never actually triggered anything and ignoring each entry's match settings. It now marks only the genuine activation hits for the turn, honoring regex / whole-word / case-sensitive / secondary-key rules, and only inside the text that was actually scanned (scene, history, and — for recursive entries — other entries' lore). Every highlight is a clickable chip whose popover explains why it fired (which keyword, where, which rule, secondary status), the entry legend dims entries that didn't activate this turn, and the match data is captured per turn so past turns stay accurate.
  • Stat editor tidy-up + shared collapsible. The Stats editor's lower half (Prevent AI Changes, Stat Descriptors, Dynamic Value Calculation) now matches the labeled-block rhythm of the other editor tabs instead of heavy section headings, and the code section uses a new reusable CollapsibleSection component.
  • Section-style regression probe. regression-style-probe.mjs A/B-tests the Default (Markdown) vs XML prompt preset on the committed regression corpus (planner continuation + digest), assembling each style faithfully — chip bodies through the real context builders, headings through the real restyle — so section style is the only variable. Runs under vite-node.
  • Fact-adherence style probe. factstyle-probe.mjs A/B-tests Markdown vs XML on a fact-dense, comprehension-trap scenario (fixed counts, positions, a name the player hasn't heard) across planner + narration surfaces at matched seeds, dumping every paired output for human judging. Also vite-node.
  • Dynamic baseline mode. The baseline harness can now play a full session live instead of a fixed script: a dynamic profile gives a turn count and a goal policy, and a chooser model (on the cloud default endpoint, so it never competes with the game model for VRAM) reads each turn's narration and choices and writes the player's next action through the real app pipeline. Falls back to the first offered choice if the chooser balks. Also handles worlds with embedded images (the "Optimize imported images?" dialog) on import.
  • Message-format arms + over-fire probes. format-arms-probe.mjs is a standalone loop harness that replays a recorded 30-turn session with self-managed history, so the shape of the conversation itself becomes testable: three message formats (the app's Player action: turns, bare first-person turns, and a single-message story rebuild), plus named prompt ablations and candidate edits, scored per turn for dialogue, freeze register, repetition, and the point a session goes quiet. It measured the narration dialogue fix in this release. overfire-probe.mjs is its false-positive guard — empty scenes and a mute animal companion, where any quoted dialogue at all means the rule is over-firing.
  • Narration re-ask probe. narration-reask-probe.mjs replays a real AI-context export's plan-mode narration requests and scores the re-ask loop (vetting questions ending a turn the player already answered), with dialogue-volume and legitimate-vetting guards; --arm B substitutes the current prompt edits into the recorded messages. The planner probe library also gained a PROMPTS_SRC override so an A/B baseline can run against a snapshot of GamePrompts.ts.

---

✅ 2.5.1 — Released 2026-07-19 — a new built-in XML prompt preset (section wrapping + nested-tag chip bodies), InvokeAI as a supported image generator, plus fixes for world export dropping entity folders/placeholders and missing-group items vanishing from the editor (click to expand)

Minor Changes

✨ Added

• 👤 User-facing

  • New built-in "XML" prompt preset. Alongside Default (Markdown) and Simple, you can now switch the whole prompt set to an XML style — a format some models follow more reliably. It wraps each context section in tags (<game_world>…</game_world>) and renders each chip's contents as nested XML (stats, traits, location, and cast become <stat>, <trait>, <entity> elements with child tags). The chips' new XML format option is also selectable individually on any preset. Like the others the built-in is read-only; duplicate it to a preset of your own to edit.
  • InvokeAI is now a supported image generator. Alongside Automatic1111/Forge and ComfyUI, you can point Formamorph at a local InvokeAI server to generate entity, location, and world images. Pick an installed SDXL, SD1.5, or Z-Image model from a list that loads straight from the server — no filenames to type. Z-Image needs a Qwen3 text encoder and a FLUX-type VAE too; Formamorph finds installed ones for you, with an override in Settings if you'd rather choose. The How to Set Up button shows the one line to add to your invokeai.yaml so the app is allowed to reach it.

• 🛠️ Developer tooling

  • The dev router can set Image Gen settings directly. window.__fmDev.setImage({ provider, model, … }) patches the active image-endpoint preset in one call, so preview verification can reach a provider/model state without driving the Settings dropdowns by hand. DEV-only, tree-shaken from production.

🐛 Fixed

• 👤 User-facing
  • Entities and traits filed under a missing group no longer vanish from the World Editor. If a world's group list was lost but its entities or traits still remembered which group they belonged to, those items simply didn't show up in the editor — only the ungrouped ones loaded. They now appear at the top level instead of disappearing.
  • Exporting a world no longer drops your entity folders or placeholders. The Download World file left out entity groups and placeholders, so importing that file elsewhere lost your folder organization and any author-defined variables/wildcards. Exports now carry the complete world (saving to your library was already fine — only the downloaded .json was affected).

---

✅ 2.5.0 — Released 2026-07-18 — a local Models library with its own tab — add, preview in 3D, inspect license, reorder, delete — plus first-run model onboarding sized to your GPU, body sliders that bind from every model grouped by name, two more local models and a new top-tier pick, dead-endpoint and unloaded-LM-Studio detection, World Editor tab help, and a batch of placeholder, text-box, and Community Creations fixes (click to expand)

Minor Changes

✨ Added

• 👤 User-facing

  • Two more local models added, one for mid-range cards and one for the top end. Gemma-4 12B Uncensored joins the ≤8GB tier as its strongest option yet — it edged out what was there on our tests, and fits comfortably on an 8GB card. Gemma-4 26B StyleTune V2 joins the No-Limit tier as the second-strongest model overall, just behind MeroMero. Both are additions, not replacements — everything already in the list stays.
  • A new top-tier local model: G4 MeroMero 31B. For machines that can run a large model, it's the strongest option Formamorph now offers — it scored highest of every model we tested, and it's the one that best knows when to leave your stats alone: it doesn't nudge your health or nerve for glancing around a room or retying a bootlace, the way most models do. It joins the No-Limit tier of the download list. Nothing changes for existing setups — it's simply there to pick if your graphics card has the room (about 19 GB).
  • On mobile, switching library sections is now a bottom tab bar. Worlds, Entities, Dictionaries, and Models sit across the bottom of the screen — one tap each, always visible, with the current section highlighted — instead of crowding the top row (which the fourth section had made too tight in portrait). The desktop layout is unchanged.
  • Your VRM models now have a library of their own. A new Models tab sits alongside Worlds, Entities, and Dictionaries, showing every avatar you've added as a card with its own portrait — read from the model's own thumbnail where it has one, and drawn for it where it doesn't. Models are named after the title the artist gave them rather than whatever the file was called, they can be reordered by dragging like every other card, and importing a file you already have asks first instead of quietly keeping a second copy of something tens of megabytes large. Files that aren't really avatars (a plain .glb) are marked as such, since they carry no license information and aren't guaranteed to pose or morph. Deleting is free except for your last model — you always keep something to be — and if a save is currently wearing the model you're removing, Formamorph names the saves before you commit rather than letting you find out later.
  • The model you start with is now yours to manage. The bundled avatar appears in your Models library as Default Model, like anything else you'd add — preview it, export it, reorder it, or delete it once you've added another. It's placed there once, so a delete sticks rather than reappearing next launch, and Formamorph keeps at least one model at all times so there's always someone to be. Existing characters carry over untouched.
  • Click a model to look it over, test it, and see who made it. Opening a card gives you the avatar in 3D — turn it, look closer — beside everything its file says about itself: the artist, the license, and whether they've allowed redistribution, commercial use, or asked to be credited. Where a model simply doesn't say, it reads Unknown rather than guessing on the artist's behalf. Underneath, the same body and color sliders you'd use in-game appear for whichever ones the model actually supports — so a creator can confirm an exported avatar responds the way they intended. Export Model saves it back out exactly as it came in, so the artist's own details travel with the file rather than being stripped by the round trip.
  • New installs now point you at the model you need, instead of failing on the first turn. The desktop app runs its AI on your own machine, but a fresh install has no model downloaded yet — so the first thing you tried to play simply didn't work, with nothing to explain why or where to go. Formamorph now offers you a model up front, sized to the graphics card it detects, with one click to download it (the full list is a click away if you'd rather choose). You can dismiss that and look around; if you then start a world before it's ready, it asks again — and the download keeps running while you browse, starting your world by itself the moment it's ready.
  • The Readme can now use placeholders. A world's Readme is shown on entry, once a playthrough's placeholders have been rolled — so it can now insert them like the other world text fields, and its Preview shows the rolled values in the formatted Readme the player will actually read. The World Description deliberately doesn't offer them: it's read in the library before anything is rolled, so a placeholder there would never resolve.
  • A dead endpoint now says so — and notices when you fix it. If you point Formamorph at your own server and it isn't answering, starting a world used to fail with no explanation. It now tells you it can't reach the endpoint and takes you to the setting to fix it. Better still, it keeps checking while it waits: start your server and the prompt clears itself and carries on into your world, with no need to reload the page. There's a Try again button if you'd rather not wait for the next check. Nothing changes if your endpoint is working, and this prompt never appears while your own endpoint is set up and reachable.
  • LM Studio with nothing loaded is now caught before you play, not after. If you point Formamorph at LM Studio while no model is loaded and the model name is still the stock one, every turn fails with "No models loaded" — but the server answers, so nothing looked wrong until you tried to play. Formamorph now spots that exact combination up front and says so. Everything else is left alone on purpose: a model that's listed but idle loads on demand, and once anything is loaded LM Studio answers to any name — so neither is treated as a problem.
  • World Editor tabs can now explain themselves. A ? beside the search box opens a short write-up of what the tab does and why it's built that way — including the parts you couldn't otherwise discover, like exactly which text the Dictionary searches for your keywords. Until you've read a tab's page its ? is tinted, then it settles down for good. Every tab is covered now — Stats, Entities, Locations, Traits, Dictionary and Placeholders. There's a fuller World Editor guide on the wiki.

• 🛠️ Developer tooling

  • The dev router reaches the library's character and dictionary editors. #dev?modal=entityEditor and #dev?modal=dictionaryEditor open each on a blank draft, so both are reachable on a fresh profile without stored data. They were the only editing surfaces the router couldn't land on.

➖ Removed

• 👤 User-facing
  • Three of the smallest downloadable models are gone, because they couldn't actually play. Qwen3-4B RPG Roleplay v2, Gemmasutra Small 4B and Gemmasutra Mini 2B are no longer offered in the model list. Every model Formamorph offers has to do more than write — it also has to quietly answer "did you just walk somewhere?" after each turn, and these three got that wrong a third of the time or worse, sending you to the stables while you stood still reading a notice. The Qwen3 one was worse still: now and then it returned nothing at all, which stopped a story dead on its first turn. The ≤4GB tab now offers Impish LLAMA 4B alone while we look for small models that hold up; if you've already downloaded any of the three, they still work — Formamorph simply won't recommend them to anyone new.

🐛 Fixed

• 👤 User-facing

  • The "nothing here yet" message in Community Creations is now centered. When a section had no listings (or a search matched none), the "Be the first to publish one!" line sat off to the left instead of centered across the grid.
  • Selected multi-select chips are never invisible. A chosen value whose option hadn't loaded yet (for lists filled on demand, like the body-slider picker) counted toward the selection but drew a blank, unremovable chip. Such a chip now shows its own value as its label and can be removed like any other.
  • Binding a stat to a body slider now sees every model, not just the default. When you tie a stat to a body shape in the World Editor, the slider list used to offer only the bundled default model's shapes — so a shape that exists on another model you'd added was simply missing. It now gathers sliders from every model in your library (plus the world's own custom model), grouped under each model's name so you can tell where each comes from. A shape shared by several models appears under each; picking it drives that shape on whichever model is worn. The list loads the first time you open the picker.
  • Community Creations dialogs now name the right kind of thing. Deleting one of your published listings always read "Delete Published World", and the download button always said "Download World" — whatever you were actually looking at. Both now match the item: World, Entity, or Dictionary. The middle browser tab also read "Characters"; it now reads "Entities", matching the library tab.
  • Entity thumbnails in Community Creations no longer crop faces off. Entity art is almost always a portrait, but the cards centered the image — so a tall portrait showed its middle and cut the head off. Entity cards — and the larger preview when you open one — now anchor the thumbnail to the top. World and dictionary art is unchanged.
  • Starting a game no longer wrongly blocks you when your AI server is actually ready. If Formamorph checked your endpoint before you'd loaded a model in it (say, at startup), it remembered that "not ready" answer and would throw up the setup prompt the moment you pressed Start — even after you'd since loaded a model, so "Try again" fixed it instantly. It now re-checks the moment you start a game rather than trusting the old answer, so a working setup launches straight into play. The prompt only appears if a fresh check still can't reach your AI.
  • The model Formamorph suggests for your card is now the best one, not the biggest. The download list used to recommend whichever model was largest for your graphics card — which isn't the same as best, and in the top tier it meant suggesting a huge 70B model that most cards can't even run, ahead of the model that actually scored highest in our testing. Each tier now leads with its top performer and lists the rest in ranked order, so the first thing you're offered is the one we'd actually pick.
  • Large models no longer refuse to load on a graphics card that has room for them. Loading a big model at a large context size could fail with "context size is too large for the available VRAM" — on a card that could fit it. Formamorph loaded the model first and asked for the context second, so it filled the card with the model and left the context nowhere to go. It now reserves room for the context up front and fits the model around it. The strangest part, and the reason this hid for so long: the more graphics memory you had free, the more likely it was to fail — a busy card accidentally left just enough room to work. If you'd been lowering your context size to get a model to load, you can try putting it back.
  • A turn that comes back empty now tells you, instead of doing nothing. Once in a while a model returns no story text at all — nothing to read, nothing to choose from. Formamorph treated that exactly like you pressing Stop: it quietly gave up and sat there, so the only thing you saw was a submit that seemingly did nothing, with no hint whether the game was thinking, broken, or ignoring you. An empty turn now says so and suggests trying again or switching models. Pressing Stop yourself is unchanged — that's still silent, because you already know you did it.
  • World editor text boxes can be dragged taller or shorter again. Grab the bottom-right corner of any long text field — description, readme, entity and location descriptions, dictionary entries — and drag. They still start at the size they always have, so nothing moves until you decide to change it, and the size you pick sticks while you switch between Edit and Preview. The prompt editors in Settings are deliberately unchanged; they're built to fill their panel.
  • Trait descriptions read as words, not raw code. A trait whose player-facing description used a Variable or Wildcard showed the underlying placeholder token in the traits panel instead of the value. It now resolves like every other piece of player-facing text — matching how the location panel already behaved.
  • Traits can now lower a stat's minimum, within limits. A trait that lowered a stat's Min silently did nothing — Min could only ever be raised. Now one trait can lower a floor that another trait raised, back down toward the value you gave the stat, though never below it. A trait that only lowers a Min still does nothing on its own; this only matters when two traits touch the same stat. Max was already free to move both ways and is unchanged.
  • Deleting a character cleans up after itself. Characters are attached to locations by the location keeping a list of who's there — and deleting a character left its entry behind in every location it belonged to. Nothing broke, since the game skips names it can't find, but the leftovers stayed in your world file and built up over time. They're now removed along with the character. Worlds saved before this keep their existing leftovers; they remain harmless.
  • Image tags no longer leak into the story. Image Tags — the booru tags used only for picture generation — were being sent to the narrator along with the description, on both characters and locations, so the AI read 1girl, blue_hair, smiling as if it were part of who someone is. They were always meant to stay out of the story, and now do. Your location and the characters in it are described to the AI on every turn, so this was quietly spending context and muddying every scene.
  • Locations no longer describe themselves twice. A location written before descriptions were split into player-facing and AI-facing versions could send the AI two different description lines at once — the current one, then the older text underneath it — leaving smaller models to guess which to believe. The AI now gets one description, and the older text is only used when there's no newer one to send.
  • The Readme popup is easier to read. The Readme, the help pages and the "What's new" popup all show their text on the same inset panel now, so the writing sits in its own framed area instead of floating on the dialog background — and it's still selectable if you want to copy a line out. The Readme is a little wider than it was to match; "What's new" is unchanged.
  • Text boxes can no longer be dragged sideways out of their column. The plain text fields that were resizable (trait, stat, group and dictionary notes) could be dragged in any direction, which pulled them wider than the space they sit in and skewed the layout around them. They now stretch vertically only, matching every other field.
  • The Reincarnated Drone world's description no longer shows raw placeholder codes. Its description tried to roll a random past life and threat, but a description is read in the library before a playthrough exists — so there was nothing to roll yet and the codes showed through as gibberish. It now describes the same idea in plain words, and your existing copy updates itself on next launch — unless you've edited that world yourself, in which case your version is left alone as always.
  • Desktop updates on Windows can no longer get permanently stuck. If an update was interrupted partway through — the app killed, the machine shut down, antivirus stepping in — every update after it would silently fail and quietly reopen the old version, with no error and no way back. The updater used to test whether the old app had let go of its files by briefly renaming its folder aside and back; an interruption in that split second left the spare folder behind, and its mere presence made every future attempt fail. That step is gone entirely — the update now simply retries the real swap until the old app releases its files, which can't leave anything behind. If you're already stuck, this fix reaches you only by downloading the full app again (the updater can't replace the piece that was broken), or by deleting the leftover app.locktest folder next to Formamorph.exe.
  • A missing launcher now explains itself instead of crashing. If Formamorph.exe had been removed or quarantined by antivirus, choosing Update & Restart closed the app with a raw JavaScript error dialog and no explanation. It now tells you the launcher is missing, names the likely cause, and leaves the app open so you don't lose your place.
  • Placeholders in a world's Readme now read as words, not raw code. A Readme using Variables or Wildcards showed the underlying token text instead of the value, so the first thing you read on entering a world was gibberish. Readme text now resolves its placeholders like every other piece of authored writing. Wildcards in a Readme are also frozen into your save now, so the Readme names the same value the story goes on to use, rather than picking a fresh one each time the popup opened.
  • Deleting a bundled world now sticks. City Rampage, Valentines Survival, and Reincarnated Drone came straight back the next time you returned to the main menu — Formamorph couldn't tell a world you'd deleted apart from one you'd never been given, so it helpfully re-created it. It now remembers that you deleted it and leaves it alone, including when that world's bundled copy is later updated. Changed your mind? Settings → Accessibility → Restore default worlds brings back everything you've deleted, at its latest version. Worlds you made or imported yourself were never affected.
  • Auto response length no longer cuts turns short. With Response Length set to Auto, Formamorph sizes each narration to your Max Output Tokens — but it had badly overestimated how much a paragraph costs, so it was telling the AI to stop after about a third of the room you'd actually given it. It now estimates paragraph length from real narration, so Auto turns fill the budget you set instead of ending early. Nothing changes if you pick a fixed paragraph length yourself; this only affects Auto.

• ⚙️ Backend / invisible

  • The world store no longer opens its database at import. It opened IndexedDB in its constructor, which every operation already does lazily anyway — harmless in the app, but it surfaced as an unhandled error (and a red CI run) in test files that import the store without a database. Opening is now fully lazy.

---

✅ 2.4.2 — Released 2026-07-16 — a one-fix release: each world shows its own Readme again, instead of every world showing the last one you edited (click to expand)

Minor Changes

🐛 Fixed

• 👤 User-facing
  • Each world shows its own Readme again. Once you'd written or edited a Readme, that same text kept appearing when you entered every other world, and a world's own Readme never showed at all. Loading a world now clears the previous world's details instead of carrying them over. This also means editing a world can no longer save someone else's Readme into it — if a world picked up the wrong Readme this way, open it in the editor and correct the text, then save.

---

✅ 2.4.1 — Released 2026-07-16 — a fix-only follow-up to 2.4.0: sub-locations you can walk back out of and a narrator that knows what place you're inside, dropdowns that stay on screen, and desktop publishing that can update and delete again (click to expand)

Minor Changes

🐛 Fixed

• 👤 User-facing
  • The AI now knows what place your location is inside, and you can walk back out of it. The Reachable scope on the Location and Entities prompt chips now sends the location that contains your current one — listed first — alongside its neighbors, so the narrator knows what building the room is in and who's out there. Previously nothing you could put in a prompt could mention it at all. It's also somewhere you can now travel to: moving into a sub-location with no sub-locations of its own and no neighbors used to strand you there permanently, because the game worked out where you could go from a place without ever considering the one containing it. No prompt edits needed — if you use the Reachable chip, this arrives on its own.
  • Long dropdown lists no longer run off the top of the screen. In a world with a lot of locations, the Change Location list was tall enough that it opened upward and had its top cut off by the edge of the screen, putting the first locations out of reach. Dropdowns now size themselves to the space actually available and scroll inside it. Affects every dropdown in the app, not just Change Location — most noticeable on shorter screens.
  • Updating and deleting your published worlds works again in the desktop app. Publishing an update over an existing world, or deleting one you'd already posted, failed in the desktop app with a "Failed to fetch" error — while both worked fine in the browser. The desktop app rewrites the community server's permissions so a native app can talk to it, and that rewrite was accidentally dropping the permission to update or delete. Publishing a brand-new world and downloading were never affected, and nothing about your worlds or the server needed changing.

Minor Changes

➕ Added

• 👤 User-facing
  • Browse and download community characters and dictionaries. Community Creations gains Characters and Dictionaries tabs, with the same search, filters, sorting, and paging worlds already had — each tab scoped to its own kind. Downloading one adds it straight to your library, and the button tells you what you're getting: nothing yet, a re-download of the copy you hold, or an update when the author has published a newer version. Each listing keeps a single local copy that a re-download refreshes in place — so if you've edited yours, it asks before replacing it. An oversized portrait offers the same Optimize / Downscale / Keep choice worlds do.
  • Publish a character or dictionary. When you're signed in, the character and dictionary editors gain a Publish button, working the same way worlds already do: publish as new, or pick one of your existing listings to update. A character with no portrait and a dictionary (which has no art at all) both get stand-in cover art on the listing, so every card looks right in the grid. Only listings of the same type are offered as update targets — a world can't be replaced by a character.
• ⚙️ Backend
  • Characters and dictionaries can remember where they came from. Their local library records now carry the same community link worlds already had — which listing a copy was downloaded from, the version held, when it was downloaded, and whether you've since edited it. The link survives an editor save, and editing a downloaded copy marks it as yours so a later re-download can't quietly overwrite your changes. It's device-local: it never travels in an exported character card or dictionary file, though a backup does carry it, the same way backups already carry this for worlds.

🐛 Fixed

• 👤 User-facing
  • Publishing works when you've published a lot. The publish dialog only ever listed your first 10 published worlds, so an 11th could never be picked to update — it simply wasn't there, with nothing to say so. It now lists every world you've published, and the list scrolls instead of growing the dialog off the top and bottom of the screen (which could put the Publish button out of reach).

---

✅ 2.4.0 — Released 2026-07-16 — a safety net for your library: full Backup & Restore to one portable file, per-turn Autosave, and persistent-storage marking — plus multi-file imports, a browsable Save menu, jump-to-page, data-backed reasoning-model recommendations, and built-in worlds that refresh themselves (click to expand)

Minor Changes

➕ Added

• 👤 User-facing
  • Import many files at once. The Import buttons for worlds, characters, dictionaries, and saves now let you select multiple files in one go. Bad files are skipped and you get a summary ("Imported 5 worlds (1 skipped)"). When a world or character import includes oversized images, a single Optimize / Downscale / Keep prompt covers the whole batch. Lorebooks embedded in imported character cards are added to your dictionary library automatically.
  • Jump to a page. In any paged list (the in-game transcript, the AI-context view, Community Creations), click the … or the current page number to open a small “go to page” box — type a page and press Enter. Out-of-range numbers snap to the nearest valid page. On mobile, tap the current page number.
  • Autosave. Your game now saves itself after every turn, starting once the opening scene finishes. Each world keeps a single Autosave slot (overwritten each turn, tagged Auto in Load) that's separate from your manual saves — it never overwrites them, and you can't accidentally clobber it from the Save dialog. It also re-saves after a Regenerate, but not after an Undo. On by default; turn it off in Settings → Accessibility. A downloaded autosave re-imports as an ordinary manual save.
  • The Save menu now lists your existing saves. Saving a game shows the same browsable save list as Load — your worlds' save folders, with download, delete, and drag-to-reorder. Click a save to drop its name into the box, so overwriting an existing save is one click (then Save confirms the overwrite as before). Typing a fresh name still makes a new save. The box also prefills with the name of the save you're currently in (the one you last loaded or saved this session), so re-saving over your slot is quick.
  • Back up and restore your library in one file. A new Backup & Restore option in the main menu exports your worlds, saves, characters, and dictionaries to a single portable .json, and restores them on any device or after an update. You pick exactly which worlds, saves, characters, and dictionaries to include — each is its own checkbox under a per-type group toggle. Restore works the same way; items that already exist are tagged so you can choose, per type, whether the backup overwrites them. Restoring worlds or characters can also optimize or downscale their images on the way in. Especially useful in the itch app, where an update can otherwise hide your local data — back up first.
  • Optimize a character's portrait when you import it. Importing a character with an oversized image now offers the same Optimize / Downscale choice worlds already had, so a huge portrait doesn't bloat your library.
  • The desktop model catalog now includes reasoning roleplay models, backed by data. The Recommended list (desktop) was refreshed with current community roleplay finetunes, and each now shows its release date and download count so you can weigh the recommendation yourself (counts refresh from Hugging Face and fall back to a snapshot when you're offline). The reasoning-capable ones are flagged with a Reasoning badge (a compact 4B and the Qwen3.6 mixture-of-experts finetune); reasoning is controlled per-prompt from Settings, so these pair with the thinking-budget control out of the box.
  • Built-in worlds refresh themselves. When a built-in world's content changes in a new build, your copy updates to it automatically on launch — as long as you haven't edited that world (edited copies are always left alone). Any worlds updated this way are named in a notification so you know what changed. It compares the actual content, so an update lands exactly once and a world can be improved without waiting for an app version bump.
  • Old saves pick up newly added stats. If a world gains a new stat after you started playing it, loading an existing save now shows that stat (at its starting value) instead of leaving it out. Your existing stats and progress are untouched.
  • Built-in worlds no longer warn about custom code. The "this world contains custom code, trust the source" warning is meant for worlds from elsewhere — it no longer shows for the unmodified built-in example worlds, since they're ours. If you edit a built-in world, the warning returns.
• 🛠️ Developer tooling
  • A repeatable prompt-quality gate. The baseline harness gained a scripted gate (GATE-PROBE.md) with a neutral prompt preset and a second reference world, so prompt changes can be measured the same way every time instead of judged by eye.
  • Model leaderboard. Probe runs now record to a tracked leaderboard (testing/baseline/leaderboard.md), making it easy to see how the reference models compare across prompts — with the research writeup kept alongside it.
  • Screenshot capture in the harness. The baseline runner can grab screens (harness/screen.mjs) and its profile example covers the current model tiers, so a run's output can be eyeballed after the fact.

🐛 Fixed

• 👤 User-facing
  • Long lists scroll again on mobile. On a phone, the Traits and Dictionary lists in the World Editor and the save list in Load/Save wouldn't scroll once they grew past a screenful — the overflow was simply cut off and unreachable. All three now scroll normally.
  • Your library is now marked as persistent storage. The app asks the browser to keep its saved data (worlds, saves, characters, dictionaries) exempt from automatic cleanup, so it's far less likely to be evicted under storage pressure — a common cause of "everything disappeared" reports on the web and itch builds. Pairs with the new Backup & Restore for a belt-and-suspenders safeguard.
  • No more endpoint errors when you're not using reasoning. The app used to probe your endpoint's reasoning support (and tag requests with a reasoning setting) on every connect — which made plain servers like LM Studio log a burst of 'messages' field is required errors and could wedge a just-loaded model. That reasoning machinery now runs only when you've actually turned reasoning on (a Thinking mode, a native effort level, or a per-prompt reasoning level). With reasoning off, requests look exactly like before — no probe, no reasoning fields.
  • Popups no longer flash their empty state while closing. Many dialogs briefly reverted to a blank/initial state for a frame or two during their fade-out — form dialogs (Save game, Backup & Restore, login/profile, preset sharing) and confirmation prompts alike (e.g. a delete confirm losing the item's name as it closed). Form dialogs now reset when opening rather than closing, and confirmations keep the content they were showing until they finish fading out.
  • Saving a backup is reliable everywhere. An earlier approach used the system "save as" dialog, which errored when overwriting an existing file and, in the itch app, could pop the save dialog twice. Backups now download directly — one step, and it works the same in every browser and in the itch app.
  • Downloading community worlds quickly no longer loses one. Two worlds downloaded within the same instant could be assigned the same internal id, so the second silently overwrote the first in your library. Each download now gets a unique id.
  • Clicking a character opens the right one. When two characters shared a name prefix (e.g. "Guard" and "Guard Captain"), clicking one could open the other's details. It now matches the exact character.
  • Dragging a chip and dropping it outside a text box no longer misplaces one later. Cancelling a chip drag (dropping it on empty space or pressing Escape) could leave a stray reference that made your next unrelated drag move a chip you didn't touch. Cancelled drags now clear cleanly.
  • Stat descriptors accept a 0% threshold. In the World Editor, adding a stat descriptor with a threshold of 0 did nothing; it now saves like any other value.
  • Starving no longer wipes out that turn's other stat changes. On a turn where you were starving, the health penalty overwrote Health with a value read before the turn's other changes landed — so any Health the AI awarded, and any Health recovery you'd earned, silently vanished. The penalty is now subtracted from your current Health, so it stacks with the rest of the turn instead of replacing it.
  • Loading a save can't hang on a worker failure. If a background helper (save conversion/download) failed to start, the "Processing save file…" notice could spin forever; such failures now surface as an error and release the dialog.
  • The oldest saves restore their traits and body changes. Very old saves (the deep-nested pre-2.0 format) loaded with their character traits stripped of description (so the AI saw only bare names) and their body stats no longer driving the 3D model. Loading one now brings those up to the current format, the same as newer saves already did.
  • A clearer message when the web app can't reach your AI server. On the web/itch build, a connection failure used to show only a generic "Failed to process AI request." It now offers a Fix connection guide covering the three causes — server not running, wrong Endpoint URL, or CORS turned off on the server — with the exact toggle for LM Studio and Ollama. The same guide is reachable any time from Settings → Endpoint → "Trouble connecting?". (The desktop app already handles this automatically, so it's web-only.)
• ⚙️ Backend
  • Built-in worlds seed with their full content. The first-run seeding path dropped a world's lorebook (dictionaries) and placeholders; they're now carried over intact.
  • Built-in worlds stop re-saving themselves on every launch. The refresh check compared a world's shipped version against a field that actually records the app version that last touched it — so a world could look permanently "newer", rewriting itself (and showing an "Updated" notice) every single launch, while a genuine content-only fix could never reach you at all. It now compares a hash of the shipped content, which settles after one update and can't loop.
  • A background helper that fails to start no longer wedges the rest of the session. If a worker's script failed to load, the broken instance was kept and reused, so every later save load hung on a spinner instead of reporting the error. The failed worker is now discarded and the next attempt starts fresh.

---

✅ 2.3.0 — Released 2026-07-14 — Formamorph goes mobile: the game view, World Editor, character customization, Settings, and Community Creations all adapt to mobile and portrait — one-panel push layouts, bottom sheets, collapsing toolbars, and viewport-correct popups — plus a version-aware "What's new" popup and a configurable Staged-thinking cast (click to expand)

Minor Changes

➕ Added

• 👤 User-facing
  • The "What's new" popup highlights your version. The changelog popout is wider and laid out as a cleaner outline — each version flush-left with its Added/Fixed groups and items stepped in beneath it. Your installed version is tinted blue and tagged (Current), and the newest available version is tinted green and tagged (New!), so you can tell at a glance what you have versus what's new.
  • The "What's new" popup surfaces the versions that matter to you. Instead of a flat "newest three," it now picks what to show based on the version you're on: the full current X.Y series, the couple of versions just before yours, and — when you're several releases behind — the newest few as well. A ... line marks any stretch that's been skipped, and an available update is always shown. You see more of what's relevant around your version without scrolling the whole history.
  • The library's top bar collapses to one menu sooner. The Community Creations / New / Import buttons now fold into a single hamburger on narrower windows (below 1000px), not just in portrait. When they collapse, the separate right-side Load Game / Settings menu folds into that same hamburger too — so there's one menu instead of two, and the grid/detailed view toggle sits flush to the right.
  • Skip Customize is clearer when entering a world. The button gained a skip-forward icon, and in portrait it collapses to just the icon so it fits alongside Enter World without crowding.
  • Choose how many characters the director stages (Staged thinking). Staged mode used to hard-cap the cast at three, so editing the Director prompt to allow more had no effect. Settings → System Prompts now has a Limit Active Characters control (under Thinking, shown for Staged): turn it off for as many characters as the scene calls for, or set your own number (default 5). A new Active Character Guidance chip in the Director prompt keeps its wording in sync with your choice.
  • Toggle the character's animation while customizing. A new Animate character checkbox (above Initial Body Features) freezes the model in place when unchecked — handy for lining up body and color changes on a still pose — and resumes the idle motion when checked. The scene stays live either way, so you can still orbit and see your edits.
  • Character customization works in portrait now. On mobile or a narrow window, the customization controls no longer get squeezed into a sliver that cuts off their labels. They move into a bottom sheet that slides up over the character — tap Customize to open it, adjust anything, then close it to see the full model. The sheet opens at a shorter height that keeps the character in view, with an expand button in its header to grow it when you want more controls at once; it scrolls its full contents at either size. Desktop is unchanged.

🐛 Fixed

• 👤 User-facing
  • Manual stat edits survive a re-generate. Nudging a stat with the in-game slider, then playing on and re-generating a later turn, no longer reverts that stat to its pre-edit value. The edit now becomes the turn's baseline, matching how edited narration and notes already carry forward.
  • Chip pop-outs stay open while you adjust options. Picking a mode on a placeholder or prompt chip (e.g. a Wildcard's World/Unique, or a Location chip's scope/content/format) no longer closes the pop-out, so you can change several settings in a row. Click elsewhere or press Escape to close it as before.
  • The placeholder Edit/Preview toggle only shows when a world has placeholders. It used to appear on every placeholder-capable field even when no placeholders were defined; now it shows up only once you've added at least one.
  • Popups fit the visible screen on mobile. Dialogs (Settings, world details, entity/dictionary editors, load game, and more) were sized to the full device height including the browser's address-bar area, so on mobile a centered popup's title and close button could sit above the visible screen. Every popup now sizes to the actually-visible area, so its header and controls stay on-screen.
  • Turn pager is tidier on mobile. The Previous / Next buttons show just their arrows on mobile (the labels return on wider screens), the numbered strip collapses to only the three pages closest to your current one (no ellipsis), and in the story the pager left-aligns on mobile instead of centering — so the row reads cleanly next to Re-generate.
  • Re-generate is icon-only on mobile. The Re-generate button under the story drops its text label on mobile and shows just the refresh icon, saving room in the tight mobile toolbar. Its keyboard/screen-reader label is preserved.
  • The in-game header is tidier on mobile. The floating buttons over the story crowded the top of the screen, so on mobile the menu (⋯) now sits on the Character/Game/Status tab row, with Edit World and AI Context folded inside it. The background-music toggle and the Hide-UI button are dropped on mobile (not needed), and the three tabs shrink to make room. Desktop keeps all the header buttons as before.
  • The World Editor works on mobile. It used to warn "not optimized for mobile, use a desktop" and hand you the cramped desktop split. It now adapts: on mobile each tab shows one panel at a time — the list of stats/entities/locations/traits/dictionary entries/placeholders, and tapping one slides in its editor with a back button — while desktop keeps the resizable two-column view. The tab strip scrolls sideways, the toolbar wraps, and the mobile warning is gone.
  • The placeholder editor works on mobile. Its two-column list-and-editor layout was unusably cramped on mobile; it now shows one panel at a time — the list, and tapping a placeholder slides in its editor with a back button. Desktop keeps the side-by-side view.
  • The character model fills its panel on mobile. In the Model tab, the 3D character was boxed to a fixed aspect and left dead space; it now uses the panel's full height and width. Landscape/desktop keep the aspect-boxed viewer above the panel.
  • The game view uses the full screen on mobile. The play screen no longer has an outer margin on mobile, so the panels run edge-to-edge and reclaim that space. Desktop is unchanged.
  • The main-menu footer is less crowded on mobile. On mobile the footer keeps your profile/login button and the copyright, and tucks the version/what's-new control, the Patreon and GitHub links, and the "Based on…" credit into a single ⋯ menu. Desktop shows them all inline as before.
  • Community Creations filters tuck away on mobile. On mobile, the sort, author/tag filters, hidden list, and "updates first" toggle now collapse behind a Filters button (with a count of what's active) so the search bar and results have room; tap to expand them in a panel. Refresh now sits beside the search box everywhere. Desktop keeps all the controls inline. Their label-and-control rows used a fixed two-column layout that stayed side-by-side on mobile (unlike Presentation and Generation, which already stacked), squeezing the controls. Those rows now drop to a single stacked column below a small breakpoint, matching the other tabs.
  • Settings tab widgets fit narrow screens. The six-tab row along the top of Settings, plus the Thinking and Native Reasoning mode pickers, were too wide for mobile; below a small breakpoint each now collapses into a dropdown of the current choice, and stays a full tab row on wider screens.
  • Character customization's Back button becomes Abort on the first step. When avatar customization is the first (or only) step of entering a world, its Back button was disabled — a dead end. It now shows Abort and cancels the enter-world flow, matching the other steps.
  • The enter-world steps dim the menu behind them again. The trait / location / character / dictionary selection popups render as plain cards without a dialog backdrop, so the main menu showed through undimmed. A black overlay now sits behind them like every other popup.
  • Location Change is skipped in single-location worlds. With Location Change on, a world that has only one location no longer fires the (pointless) move request each turn — there's nowhere to go — so you don't have to toggle the setting off per world.
  • Community world thumbnails zoom again. Clicking a world's image in the Community Creations details view opens the pan/zoom viewer as before; it had stopped loading because the zoom used the raw server image URL (which the server blocks from cross-origin <img> loads), while the card thumbnail already loaded through the local image cache. The zoom now uses that same cached copy.
  • The world details popup no longer scrolls sideways on small screens. On a narrow portrait viewport, the panel that opens when you pick a world could be cut off on the right with a stray horizontal scroll; its content now stays within the screen.
  • The character model renders cleanly in its viewer. In character customization the 3D model could draw outside the rounded edges of the viewer card, and it could stay cut off at the wrong size after rotating the device or resizing between landscape and portrait. It's now clipped to the panel and re-fits itself whenever the panel changes size, in both the desktop and portrait layouts.
  • The app no longer shows a blank screen over plain HTTP. Opening Formamorph from a non-secure origin — for example loading the dev build on your phone at http://<your-pc-ip> over the local network, or self-hosting without HTTPS — used to render a white screen, because the browser withholds its built-in ID generator outside a secure context. It now falls back to a compatible generator, so it loads and runs the same everywhere.
  • Scrolling the main-menu card grids on touch no longer drags cards around. On mobile, swiping to scroll the worlds, entities, or dictionaries could accidentally pick up and reorder a card. Reordering on touch now needs a short press-and-hold first, so a plain swipe scrolls as expected. Mouse drag is unchanged.
  • The World Editor's + button always adds an item. Adding a stat, entity, location, or stat update used to do nothing unless you'd first typed a name in the search box. It now creates a new item with a default name (e.g. "New Stat") and selects it for editing — matching how traits, dictionaries, and placeholders already worked. Typing a name first still uses that name.
  • The World Editor runs edge-to-edge on mobile. The mobile layout had an outer margin and extra card padding that ate into the little screen space there is; those are gone, so the list and editor use the full width. Desktop is unchanged.
  • Popup buttons don't crowd together when they stack on mobile. When a dialog's action buttons wrap from a row into a vertical stack on a narrow screen, they had no space between them and nearly touched. They now keep standard spacing whether stacked or side-by-side.
• 🛠️ Developer tooling
  • Reusable ListDetail master-detail layout. New components/ui/list-detail.tsx renders a list + detail side-by-side on desktop and a single-panel push (detail slides in over the list with a back header, parallaxed, reduced-motion aware) on mobile — branching on useIsMobile. The caller owns selection and passes showDetail + onBack. PlaceholderEditor is the first adopter (drops its hand-rolled two-column split), so the entity/dictionary modals and the World Editor placeholders tab all get the mobile push for free. Unit-tested (desktop-both-panels vs mobile-back-bar). The list's dnd is unaffected — at rest the list panel's transform is none, so no containing-block interference. Adopted by PlaceholderEditor, DictionaryEditorModal (dictionary tree ⇄ book/entry editor), and the WorldEditor (its per-tab list + detail extracted to shared listContent/detailContent fragments, branched on useIsMobile: desktop resizable split vs mobile push; the < 1024px "not optimized for mobile" warning was removed).
  • Configurable staged cast cap + guidance chip. matchCastToEntities's hardcoded 3 is now runStagedPlanning's activeCharacterCap (Infinity = unbounded), fed from two new settings — limitActiveCharacters (bool) + activeCharacterLimit (int, default 5). A new <ACTIVE CHARACTER GUIDANCE> prompt variable (registered in promptVariables, offered on the Director prompt, resolved via activeCharacterGuidance() in buildContextValues/preview) replaces the Director prompt's cast-size sentence so the prompt tracks the setting. Settings UI row is gated to Staged. Unit tests cover the guidance text and the pinned Director chip list. Default staged cast size shifts 3 → 5.
  • Modal/overlay heights use dvh, not vh. Every arbitrary [Nvh] height on a dialog, card modal, bottom drawer, or scroll region (plus the two full-screen dialogs' h-screen) was converted to the dynamic-viewport unit dvh, so centered overlays no longer overflow the mobile visible viewport and clip their own chrome. Page-root h-screen scaffolds were intentionally left as-is. Verified no [Nvh] heights remain.
  • Changelog popout formatting. UpdateService.foldRelease now emits each version as its own ### <tag> heading (no more version·category merge); ChangelogBody tags the current / newest-uninstalled version headings (cl-current / cl-update) so .changelog-body CSS can tint them (info / success via color-mix, kept muted) and append the (Current) / (New!) labels; indentation is CSS too. Both changelog popouts widened to max-w-3xl. Tests updated.
  • Version-aware changelog selection. buildRecentChangelog now takes the running version and picks releases by rule instead of slicing the newest three: always the newest release (rule 0), the full current minor including newer patches (rule 1), the newest RECENT_CHANGELOG_COUNT when behind by more than one release (rule 2), and the two releases just below the running version (rule 3). Renders ... gap markers wherever hidden releases sit between shown ones (or below the last). currentVersion threaded through parseReleases; unit-tested across the up-to-date, behind-by-one-into-new-minor, and behind-by-many cases.
  • Character customization responsive layout + bottom drawer. CharacterCustomization extracts the viewer and the controls into shared fragments and branches on useIsMobile: desktop keeps the two-card split; portrait renders the viewer full-height with the controls in a vaul bottom drawer (new dep) toggled by a floating Customize button. New components/ui/drawer.tsx follows the shadcn recipe but keeps the overlay separate from DrawerContent. The drawer is modal with a faint overlay so its gestures don't contend with the model's OrbitControls (this was the first-interact lag); it toggles between two fixed, fully-scrollable heights (DRAWER_HEIGHTS, short/tall) via a header expand button rather than vaul snapPoints — a partial snap can't scroll its inner content, so snap points were dropped. The viewer Card gained overflow-hidden to clip the WebGL canvas, and VRMViewer now re-fits via a ResizeObserver on its mount (not just window.resize, which measured stale dimensions mid-layout-swap) so orientation/landscape↔portrait changes no longer leave the model cut off. Single mount of the controls (no duplicate DOM ids). Reachable for verification via the dev-router (#dev?modal=avatar, added to DEV_MODALS). No export-shape or behavior change.
  • VRMViewer cancels its render loop and animation timers on unmount. The requestAnimationFrame loop and the self-scheduling playNextAnimation setTimeout chain were never cancelled in the effect cleanup (only THREE resources were disposed), so every remount (model swap, layout change) leaked another loop + timer driving a disposed scene. Cleanup now tracks and cancels both. Also: the Animate-character toggle feeds dt=0 to freeze in place, and playNextAnimation skips the clip swap while paused so the pose no longer jumps between keyframes.
  • Touch-friendly DnD sensors on the library grids. MainMenu swapped the shared worldSensors from a single PointerSensor (distance: 8, which fired on any touch swipe) to a MouseSensor (distance: 8) + TouchSensor (delay: 200, tolerance: 5) pair — a touch swipe scrolls, a press-and-hold reorders; mouse behavior is unchanged. Fixes worlds/entities/dictionaries in one place. Paired with this, SortableWorldCard's whole-card draggables changed touch-none → touch-pan-y so a vertical swipe pans the grid's ScrollArea natively (with touch-none the browser couldn't start a scroll on a card, so the grid was unscrollable on touch); the delay sensor still takes over both axes once a drag activates. Small grip-handle draggables keep touch-none (their card bodies already scroll).
  • randomUUID() helper with a non-secure-context fallback. crypto.randomUUID is only defined in secure contexts (HTTPS/localhost), so any startup path that mints an id — e.g. migrateWorld on load — threw a blank screen when the app was served over plain-HTTP LAN (phone testing the dev server) or self-hosted without TLS. New lib/uuid.ts uses the native API when present and otherwise builds an RFC-4122 v4 from crypto.getRandomValues (which isn't secure-context-gated); all 34 crypto.randomUUID() call sites now route through it. Unit-tested (native path, fallback path, uniqueness). Still v4 UUIDs — no export-shape or version impact.

---

✅ 2.2.2 — Released — author-defined **Placeholders**: reusable Variables / random Wildcards dropped into world text as chips, with a live Edit/Preview toggle, portability when you share characters and dictionaries, and one shared editor everywhere — plus downloaded worlds now keep their own thumbnail and work fully offline (click to expand)

Minor Changes

➕ Added

• 👤 User-facing
  • Placeholders — reusable values and randomness in your worlds. A new Placeholders tab in the World Editor lets you define named values and drop them into your world's text. Add one value and it's a Variable — reuse it everywhere and change it in one place. Add two or more and it's a Wildcard — each playthrough picks a random one, so worlds feel varied without you writing every case. Insert them as chips into any entity, location, world, or dictionary description (both the player-facing and AI-facing text), and each Wildcard chip chooses World (the same value everywhere this playthrough) or Unique (its own value at that spot). The player and the AI always see the same rolled value, frozen for the save.
  • Preview placeholders while editing. Any field that accepts placeholder chips now has an Edit / Preview toggle (like the prompt fields). Preview swaps each chip for a value — a Variable shows its value, a Wildcard shows a random one of its values (World chips share a value, Unique chips roll separately) — highlighted in the chip's own color. Re-rolls each time you open Preview, so you can see the range.
  • Edit a shared item's placeholders in the library. The library character and dictionary editors get a Character/Dictionary ↔ Placeholders tab switch at the top; the Placeholders tab is the same list-and-editor as the World Editor's, so you can add, edit, and reorder the placeholders a standalone item carries. Its chips now display and resolve correctly in the library editor too.
  • Shared entities and dictionaries keep their placeholders. When you export a character card or a dictionary that uses placeholders, the placeholder definitions it needs travel with it. Importing it into another world adds them to that world (reusing an exact same-name/values match if one already exists, so you don't get duplicates), and its chips keep working. Held in the library, an imported item carries its placeholders until it lands in a world.
• 🛠️ Developer tooling
  • Placeholders — scoped store, shared split UI. The placeholder editor now follows the same pattern as the dictionary editor: a scoped PlaceholderStore context (contexts/PlaceholderStoreContext.tsx, with a placeholderStore(value, setValue) adapter). GameDataContext binds it to the world's placeholders; the library editors bind an isolated adapter over the item's own placeholders field. The split UI is now genuinely the same components everywhere — PlaceholderList (left) + PlaceholderManager (right), reading/writing through the store — instead of the library reimplementing the layout. PlaceholderEditor is the context-bound combined wrapper the modals use; the World Editor's Placeholders tab renders the same pieces (dropped from the generic tab machinery, like the Dictionary tab already was). No behavior change; verified in the World Editor.
  • Placeholders — export/import portability (slice 6). Entity + Dictionary gain an optional placeholders? (one representation for the export file and the in-app library item). Export (buildEntityCardData/buildDictionaryFile) bundles just the used defs via collectUsedPlaceholders; import parses them onto the object; adding a card/book to a world runs absorbPlaceholders (perfect name+values match → reuse id, else fresh-id add) + remapPlaceholderIds to rewrite the item's tokens, then clears the carried section. All pure + unit-tested; entity round-trip test added. Additive export-shape change to the entity card + dictionary .json.
  • Placeholders — field rollout (slice 5). PlaceholderField (the placeholder chip editor) replaced the plain textareas on the accepting fields: entity player/AI descriptions + summary (EntityFields), location player/AI descriptions + summary (LocationManager), world System Prompt (WorldDetailsManager), and dictionary entry value (DictionaryManager). Shared editors (EntityFields, DictionaryManager) take placeholders as a prop so the world-editor callers pass the world's list while the isolated library editors pass none. Extracted KeywordChips reused for values. Completes the feature (author → insert chip → resolve at runtime), verified end-to-end.
  • Placeholders — resolution wiring (slice 4). Placeholder chips now resolve to their frozen values at runtime. Rolls are eagerly primed when a save activates (primeRolls scans the world's authored text once, rolls every Wildcard placement, keeps a loaded save's existing rolls), so resolution is a pure lookup everywhere — no render-time side effects. SaveObject.placeholderRolls persists them (GameplayContext). usePlaceholderResolver + GameViewer's resolvePH apply resolution at the AI-context boundaries (buildContextValues, scene entities, dictionary) and at player-display (entity modal, location panel). The same roll feeds both, so the player and the AI always see the same value. Reverses the earlier "lazy" plan for the render-safety win.
  • Placeholders — chip editor (slice 3). The Lexical chip editor was generalized behind a ChipVocabulary abstraction (lib/chipVocabulary.ts) so one editor serves both token families: the static prompt variables (<…>) and dynamic per-world placeholders ({{ph…}}). PromptField/VariableNode now read their vocabulary from context (prompt path unchanged — verified), and a new PlaceholderField wraps the same editor with the placeholder vocabulary: the toolbar inserts the world's placeholders (fresh placement id per insert), and a Wildcard chip's pop-out offers World | Unique once it has 2+ values. Vocabulary logic unit-tested; not wired into world fields yet (slice 5).
  • Placeholders — foundation (slices 1–2). New authored-world concept: a named value dropped into world text, its behavior inferred from value count (1 = a fixed Variable, 2+ = a random Wildcard). Slice 1: Placeholder type + World.placeholders, save-side SaveObject.placeholderRolls, and the pure resolvePlaceholders core (lib/placeholders.ts) with the token codec, World-shared/Unique-per-spot rolls, lazy roll+freeze, and missing/empty → "" (unit-tested). Slice 2: a per-world Placeholders editor tab (list dnd/duplicate/delete + PlaceholderManager name/values panel), reusing the extracted shared KeywordChips input. Additive world + save export-shape change (nothing consumes it at runtime yet — the chip editor + resolution wiring are later slices).

🐛 Fixed

• 👤 User-facing
  • Downloaded worlds now show their thumbnail in the library — and work fully offline. A world downloaded from Community Creations was storing a link to the server's thumbnail image, which the browser refuses to display on the library card (the server marks those images as same-origin only) and which wouldn't work offline anyway. Downloads now save the world's own cover image directly into the local copy, so the card shows it and the world is fully self-contained. Worlds you already downloaded are healed automatically — no need to re-download.
• 🛠️ Developer tooling
  • World download stores the embedded thumbnail, not the catalog URL. useDownloadCoordinator.fetchWorldContent now prefers migrated.worldOverview.thumbnail (base64, already in the downloaded content) over the ${API_URL}/thumbnails/... URL — the server's Cross-Origin-Resource-Policy: same-origin (Helmet default) blocks the raw URL from <img> embedding cross-origin, and a URL can't render offline. getWorldMetadata also falls back to the embedded thumbnail when a stored one is an http(s) URL, healing pre-fix downloads at read time (it already loads data for tags, so no extra cost). Unit-tested. Separately, the FormamorphServer thumbnails route now sets Cross-Origin-Resource-Policy: cross-origin (overriding Helmet's same-origin default) so those public images are embeddable cross-origin — not needed by the app anymore, but correct for any other embedder (needs a server deploy).

---

✅ 2.2.1 — Released — turns run their follow-up requests (choices, stats, summaries, diaries) concurrently for faster, steadier pacing, and the bundled desktop engine gains parallel requests, Flash Attention on by default, big-model / multi-GPU offload, and a VRAM-share readout (click to expand)

Minor Changes

➕ Added

• 👤 User-facing

  • Turns finish faster with concurrent requests. After the story text, the app asks the model for your choices, stat changes, and any location change — previously one after another, now all at once by default. On endpoints that handle parallel requests (e.g. LM Studio's Parallel setting) this cuts the wait between the narration and your choices by roughly a third, and makes turn times steadier. When memory summaries (and, in Staged mode, character diaries and new-character notes) are on, those run in the same batch too, so they finish with the turn instead of trickling in afterward. In Staged mode the per-character motivation passes also run at the same time instead of one by one, which noticeably speeds up busy scenes. A new Concurrent Requests toggle under Settings → Generation lets you turn it off if a memory-tight local model slows down under the extra load; endpoints that don't run requests in parallel are unaffected either way.
  • The GPU memory widget now shows Formamorph's own share (Desktop). The VRAM bars in Settings → Endpoint get a highlighted segment marking how much the bundled model is using, with a "Formamorph: … GB" readout. It uses the exact per-process figure when your GPU reports one, and otherwise falls back to the engine's own estimate (shown with a ~) — so it works even on the many Windows GeForce cards that don't expose per-process VRAM.
  • Big models and multi-GPU rigs are now supported (Desktop). The GPU offload control used to cap at 64 layers, so a large downloaded model (or a multi-GPU setup with room to spare) couldn't be fully offloaded. It now has Auto (fits as many layers as your VRAM allows — the new default, never runs out of memory), Max (offloads the whole model, splitting across all your GPUs), and Custom (a fixed layer count) under Settings → Endpoint (Advanced). The Context Size slider now also tops out at whatever the loaded model was trained for, instead of a fixed limit.
  • Flash Attention is now on by default (Desktop). The bundled local engine's Flash Attention — which lowers the model's memory use and is often faster — now defaults on instead of off. It's widely supported on modern GPUs, and turning it on by default leaves more headroom for the parallel requests above. If an older GPU won't run it, you can still turn it off under Settings → Endpoint (Advanced).
  • The bundled desktop engine now handles parallel requests. The built-in local model (Desktop app) used to answer one request at a time and reject the rest, which meant the concurrent-requests speedup above didn't apply to it. It now runs up to a configurable number of requests at once. A new Parallel Requests slider under Settings → Endpoint (Advanced) sets how many — the default is 2, and it shows the per-slot context each setting leaves you. Higher is faster but splits the context window between slots and uses more VRAM, so raise it only if your GPU has room.

• 🛠️ Developer tooling

  • Local engine request pooling (electron/llmEngine.cjs). The single-sequence + busy/429 design was replaced with a pool of N node-llama-cpp context sequences (createContext({ sequences: N })) plus an acquire/release wait-queue: concurrent requests each take a free sequence and decode in parallel (llama.cpp batching), and overflow requests queue instead of erroring. Sequences are clearHistory()-reset between uses; a client disconnect aborts the in-flight generation (via an AbortController on the response close) so a canceled request frees its slot. Slot count threads through engineOptions (llm-set-options) and a new localParallelRequests setting; changing it reloads the model.

---

✅ 2.2.0 — Released — the desktop app self-updates, paging back shows a whole past turn (stats, scene, and choices travel back with the story text), entity groups, stacked choices, and a batch of drag-and-drop, scrollbar, stat-bar, and theming polish (click to expand)

Major Changes

➕ Added

• 👤 User-facing
  • The desktop app can update itself — The version number in the menu footer now checks for new releases (on launch, every few hours, and whenever you click it) and shows a " — Update Available!" tag when there's a newer version. Click it for a dialog with the new version's release notes and a Download button; the download runs in the background with a progress bar under the version number, then turns into an Update & Restart button. A release channel picker in that dialog lets you choose Stable (default) or Pre-release builds. On Windows and Linux the update installs itself; on macOS the Download button opens the new .dmg for you to install. (The welcome-animation replay moved off the version number onto the copyright text to make room.)
• 🛠️ Developer tooling
  • Auto-update architecture (desktop). Detection is renderer-side and uniform across platforms: UpdateService reads the GitHub Releases API through the existing net-fetch bridge, filters by the updateChannel setting (GitHub's prerelease flag), semver-compares against APP_VERSION, and caches the last result for an offline fallback. State is a pure reducer (src/lib/updates/updateState.ts) driven by useUpdateChecker; the footer UI (UpdateVersionControl + UpdateDialog) is mounted only under isDesktop() so the web build never checks. Download/apply are per-platform in the main process (electron/updater.cjs): Linux uses electron-updater AppImage self-update (added electron-updater dep; publish: github in electron-builder.yml; the Linux CI step now --publish always so latest-linux.yml reaches the release, which the publish job finalizes); macOS is a notifier (shell.openExternal the .dmg); Windows uses a new Discord-style launcher. Pure logic is unit-tested (semver, reducer, channel filtering, cache fallback); a render test covers the footer tag + dialog.
  • Windows launcher + /app swap. A tiny Go stub (launcher/) is the stable root exe (the only binary SmartScreen judges); the real Electron app lives in <root>/app and is swapped in place on update, with userdata/+models/ beside the root untouched (FORMAMORPH_ROOT now takes precedence in portableProfile.cjs/main.cjs). electron/winUpdate.cjs downloads the /app payload zip, verifies its sha512, and records pending.json; the launcher waits for the app to exit, extracts + swaps (app → app.backup, app.new → app), relaunches with --just-updated, and rolls back if the new build crashes before writing a launch-ok marker. The Windows target changed from portable to dir; CI builds the Go stub and assembles the full-root zip + the app-<ver>-win.zip payload + its .sha512.
  • No world/save export-shape change. The only new persisted state is the FORMAMORPH_updateChannel setting; save/world .json shapes are untouched.

Minor Changes

➕ Added

• 👤 User-facing
  • Multi-select dropdowns now match the theme like the regular dropdowns. The closed multi-select control used a transparent/off-theme surface and its selected-item chips used hardcoded colors that washed out in light mode. The control now uses the same background, border, and focus ring as a normal dropdown, and the chips and their remove buttons follow the theme.
  • Stat-change bars animate consistently everywhere, and respect "reduce motion." The green/red change band and the accent fill now use one shared animation whether the change came from the AI or from paging back through turns, so the two no longer disagree. Turning on your OS "reduce motion" setting makes the bars snap to their final state instead of sliding.
  • Ctrl+click (or long-press) a choice to add it to your action instead of replacing it. Clicking a suggested choice still replaces whatever's in the input box, but Ctrl/Cmd+click — or a touch long-press — appends the choice as a new sentence, so you can stack a couple of choices into one compound action (e.g. "Draw your sword. Attack the goblin."). Every choice whose text is currently staged in the box stays highlighted, and when you page back to a past turn, every choice you stacked that turn is highlighted (not just one).
  • Entities can be organized into groups (folders). The Entities tab now works like the Traits tab: add a group (a named folder), then drag entities into it, and nest groups inside groups to any depth. Groups are purely for keeping the editor tidy — they are never sent to the AI and change nothing about gameplay or how entities read in a scene. Imported character cards land ungrouped. (Adds entityGroups + an entity groupId/order to world exports.)
  • Paging back to an earlier turn now shows that whole turn, not just its text. Flipping to a past turn used to change only the story text while the stats, location, scene, and character stayed on the latest turn. Now the entire view travels back with you: that turn's stats, traits, location (background and ambient sound included), who was in the scene, its choices, and the character's appearance all reflect how things were on that turn. A "Viewing turn N of M" banner marks that you're browsing history, and the controls that only make sense on the current turn (editing stats, changing location, picking a choice) are disabled while you look back — narration and Player Notes stay editable on any turn. Return to the latest turn and everything is live again. On a past turn, the choice you took is highlighted — inferred by matching your next action against that turn's options, so it still lights up even if you reworded the choice before sending it (nothing about your pick is stored). The stat changes for that turn show too — the green/red +/− text and the growing bar segment — and they animate in as you scroll to the turn rather than snapping into place.
• 🛠️ Developer tooling
  • Dragged list/card items no longer resize while dragging. When rows differed in height (e.g. a save folder with a two-line name), the item being dragged snapped to the size of the row it was over. Cause: every sortable rendered its drag offset with CSS.Transform.toString, which bakes in dnd-kit's slot-fit scale. Switched all of them (CSS.Translate.toString, translation only) so a dragged row/card/chip keeps its own size — across SortableTree, LoadGameDialog, LocalModelModal, DictionaryTree, DictionarySelectionModal, WorldEditor, SortableWorldCard, Chip/EditableChip.
  • Dragging an item to the bottom of a World Editor list no longer jitters/runs away. Inside the editor's Radix <ScrollArea>, dragging a location/entity/trait to the bottom made the list judder and the view scroll into empty space. Two causes: at the bottom edge pointerWithin returned no target, so the drop gap flipped on/off every frame (jitter); and the in-flow dragged row extended the scroll height, so auto-scroll chased it downward forever (runaway). Fixed in SortableTree with a closestCenter fallback for collisions (never empty) and a Y-only bounding modifier (restrictYToScrollAncestor) that clamps the drag's vertical position to the viewport but leaves X free — so auto-scroll stays bounded while horizontal depth-nesting still works. Audited every other DndContext: none need it (they're vertical-only/grids bounded by restrictToFirstScrollableAncestor, or have auto-scroll off).
  • Scrollbars: converting native overflow-* containers to Radix <ScrollArea> to drop the OS arrow buttons. On Windows, Chromium renders up/down stepper arrows on native scrollbars that CSS cannot remove (::-webkit-scrollbar-button { display: none } and scrollbar-width are both ignored for the buttons). The only button-less scrollbar is Radix <ScrollArea>, which hides the native bar and draws its own thumb. Converted so far: the Community Creations results list, the changelog body (ChangelogUi), the local-model recommended list + settings panel (LocalModelModal/LocalModelPanel), all six SettingsModal tab/section scrollers (presentation, generation, endpoint, image, prompt-options, accessibility), and the Character Customization card. Also converted (harder cases): the drag-and-drop lists in LoadGameDialog and the installed-models list (LocalModelModal) — the sortable rows now live in the ScrollArea viewport, which restrictToFirstScrollableAncestor still finds; EntityModal (its short-content vertical centering degrades to top-aligned inside the overlay); and both ThemePreviewDialog columns. Still deferred: <textarea>s / editable-div editors (MarkdownField, PromptField, the prompt boxes — need auto-grow + wrapper, an app-wide UX call), the responsive dual-column WorldDetails (splitColumnClasses scrolls one column on mobile, two on desktop — needs a per-breakpoint restructure), horizontal-scroll code blocks (the shared <ScrollArea> is vertical-only by design), the 3D-model viewer tab (canvas owns the wheel), and the popover-hosted lists (command/multi-select/SuggestionList — scroll-lock interactions). No behavior change beyond the scrollbar visual. E2E coverage for these (which jsdom can't provide) is a tracked follow-up.
  • Stat bar animation unified onto one tested geometry (statBar.ts). The live and history paths had diverged — different delta sources (held/drain vs viewStatChanges) and different fill mechanisms (plain width transition vs keyed stat-fill-slide) — which is why the bars kept breaking with each change. Both now feed the same pure statBarFrame(prevValue, curValue, min, max) → { curPct, prevPct, bandLeftPct, bandWidthPct, hasBand, gain } plus bandOrigin(gain, draining), and the accent always slides prev→cur via stat-fill-slide (drain leaves the accent put and collapses the band toward the current value). StatBar now takes (value, delta, draining, animKey) instead of (delta, drainDelta, animKey). Reduced-motion snaps to final (no slide/grow, no drain band) via usePrefersReducedMotion. Geometry is unit-tested (statBar.test.ts: gain/loss/no-change/clamping/sub-pixel/origins). No save- or world-shape change.
  • Entity groups (editor-only folders; the simplest version). Replaced the earlier entity-nesting model with distinct EntityGroup folders, mirroring TraitGroup/traitTree exactly. EntityGroup { id, name, parentId, order } (nestable folders); Entity swaps its old parentId for a single groupId + order. A new entityGroupTree.ts (a 1:1 port of traitTree.ts minus the AI-context builder — groups never feed the AI) backs a rewritten EntityTree on the shared SortableTree; the World Editor's Entities tab gains an Add-Group/Add-Entity popover. GameDataContext gains entityGroups + addEntityGroup/updateEntityGroup/removeEntityGroup (deleting a group reparents its children). Selecting a group opens a name-only EntityGroupManager (mirrors the trait GroupManager). buildEntityContext reverted to the flat pre-grouping output (groupId/order destructured out) — the entity context is byte-for-byte what it was before grouping. Card imports reset groupId to null. Deleted the old parentIdTree.ts and the nesting tests; added entityGroupTree.test.ts. World-export-shape change (entityGroups added, Entity.parentId→groupId+order); no save-shape change. Since 2.2.0 is unreleased, no migration is shipped — old entity-nesting silently drops.
  • Per-page "viewed" state in GameplayContext (isViewingPast + view* selectors). Instead of mutating live state on page change (which would re-introduce the edit-clobbering bug), the context derives read-only viewStats/viewTraits/viewCharacterData/viewVisibleEntities/viewGameTime/viewLocationId/viewChoices/viewStatChanges from the paged snapshot — each aliases the live value on the latest page, so normal play is provably unchanged and only past pages read the snapshot. Panels consume them via destructure-aliases (minimal churn) and gate their mechanical controls on isViewingPast. The body-morph effect now derives from viewStats (avatar re-morphs to the paged turn); background reads the resolved viewed location; a new ambient effect keyed on viewLocationId follows the viewed location and fixes a pre-existing gap where loadGameState set the location without its ambient sound. No save-shape change. Verified in the preview via the whiteRoom 3-turn fixture: cue/narration/choices/edit-disabling all track the paged turn; the latest page stays live.
  • Inferred choice highlight on past turns (matchChoiceToAction, choices.ts). A past page marks which choice the player took by fuzzy-matching the next turn's action against that turn's viewChoices — word-set Sørensen–Dice similarity with a 0.5 confidence threshold (returns -1 for a custom action), tolerant of reworded/reordered choices, glue words dropped, markdown/punctuation stripped. Derived, never stored. Exposed as viewSelectedChoice; the choice render uses it for isSelected on past pages (the live page keeps its choice === playerInput selection). Pure + unit-tested (choices.test.ts), and preview-confirmed on the fixture (the highlighted choice matched the actual action taken).
  • Animated stat deltas on past pages. Reviewing a past turn feeds that turn's derived change (viewStatChanges, computed vs the previous page's stats) into the same StatBar grow band and delta text as a live turn, so the green/red bar + +/− text render for the reviewed turn. The delta is computed by a pure pageStatDeltas(stats, prevStats) (statChanges.ts): each stat's value minus its previous-turn value, or — on the opening turn, which has no predecessor — its starting value (else min), so turn 1 shows its deltas too instead of nothing. New stat-delta-text-in CSS class (fade/slide-in and hold, unlike the live 10s fade-out); StatBar gained an animKey (the page number) so the band re-animates on each scroll-back even when a stat's value/delta coincide between turns; the delta text span re-keys on currentPage for the same reason. While reviewing history the base fill also slides via a keyed stat-fill-slide CSS-var animation (--fill-from/--fill-to = the turn's previous → current value) instead of a plain width transition — so it always starts from the correct origin and stays in step with the grow band, rather than sliding from whatever page you scrolled from (which left a gap on backward navigation). Live keeps the plain transition (you always arrive from the previous turn there). The DEV whiteRoom fixture now carries two stats with per-turn changes so the stats view + deltas are actually exercised (preview-verified: +2 green and −10 red on turn 2, both with animate-in text and matching grow bands; the latest page stays on live deltas). — Starting Formamorph briefly popped up a black terminal window before the app appeared; it no longer does, and the launcher now shows the Formamorph icon instead of a generic one
  • Updates no longer leave a full-size backup copy behind (Windows) — After a successful update the previous version was kept on disk, roughly doubling the install size; it's now removed once the new version is confirmed healthy
  • Re-generate and Rollback no longer undo your edits to the previous turn — Editing a turn's narration or your Player Notes and then re-generating (or rolling back to that turn) reverted it to the original, unedited text. Both now keep your edits — they restore the turn's game state without throwing away what you changed.
  • Stat change bars show the real change and match between the current turn and history — The current turn's green/red delta came from the amount the AI asked to change a stat, while a past turn showed what actually changed; when a change was capped (stat already at max/min) or otherwise limited these disagreed — a maxed stat could still flash a "+N" bar. The live bar/text now use the actual applied movement (appliedStatDeltas, computed from the clamped result), so they line up with the history view everywhere. Unit-tested incl. the capped-stat case.
  • Editing a turn's narration now refreshes what the AI remembers of it — A turn's memory summary and character diary entries are built from its narration; after you edited that narration they were left describing the old text. Editing now clears them so they quietly rebuild from what you wrote.
  • Page footers' Previous/Next buttons no longer jump around as you flip, and the current page is clearly highlighted. As you paged, the strip of page numbers changed how many were shown (more in the middle, fewer near the ends), shifting the Previous and Next buttons left and right. Every pager — the story turns, the AI-context viewer, and the Community Creations browser — now reserves its widest layout at all times, so the buttons stay put. The low page numbers hug the left, the high ones anchor to the right, and a single "…" sits centered between them. The page you're on now shows as a filled button so it's obvious at a glance.
  • You can recover after a local model fails to load (desktop) — If the built-in engine reported a context size too large for VRAM, the panel got stuck: lowering Context Size (or GPU Layers) did nothing because the Save & Reload button only worked while a model was already loaded. Now, after a failed load, the button re-enables so you can lower the setting and retry, and a hint points you at what to change. (The GPU Layers slider under Advanced already lets you partially offload a model that doesn't fully fit VRAM.)
• 🛠️ Developer tooling
  • Local-engine reload isn't gated on status === 'ready' anymore. LocalModelPanel's Save & Reload was disabled unless the engine was ready, so a status: 'error' load (e.g. node-llama-cpp's memory-safety check rejecting a too-large context) trapped the user — the lowered Context Size never reached engineOptions in main.cjs. The enable check is now "settings differ on a ready model, or the last load errored"; the error branch also relabels the button "Retry with these settings" and shows an out-of-VRAM hint. Renderer-only; the underlying node-llama-cpp VRAM estimate is unchanged (its rejection was legitimate).
  • Rollback/Re-generate restore mechanical state only; narration + notes come from the live history. Each gameStates[i] snapshot froze a full copy of fullMessageHistory + playerNotes at turn-end, and loadGameState re-injected those stale copies on restore — clobbering any edit the player made afterward. loadGameState gained a keepLiveHistory option; handleRollback/handleRegenerate now restore the snapshot's mechanical fields but rewind narration by slicing the live flat history (sliceHistoryToPage, turnHistory.ts) and leave notes live. Restore logic only — no save-file shape change. Unit-tested (turnHistory.test.ts), incl. a regression that a kept turn's edit survives the slice.
  • Narration edits invalidate the turn's derived memory (clearTurnDerived). EditTextModal onSave drops the edited turn's summary + diaries (turnDigest.ts, keyed by turnId) so the digest/diary drainers re-select and rebuild the turn. Scoped to narration edits only — Notes edits and the choices/stat partial-regens don't feed the digest or diaries, so they don't force a rebuild. Unit-tested (turnDigest.test.ts).
  • A past page with no saved snapshot no longer claims to show history. If a save's per-turn snapshots were short of its page count (e.g. a converted deep-nested legacy save), paging back flagged history mode — banner, disabled controls — while the stats/location/notes silently fell back to the current turn. A page now counts as history only when it actually has a snapshot; otherwise the panels stay live (matching the pre-page-view behavior) instead of contradicting themselves. Verified: removing a page's snapshot flips it out of history mode with the view state equal to live.
  • Code-derived stats now animate their change live, like every other stat. A stat computed by code (e.g. a level derived from XP) updated its value but showed no green/red delta band on the turn it changed — while paging back to that turn did show it. The live feedback now folds in the code-recompute delta, so live and history agree. (Only affects worlds using stat code.)
  • Editing an unparseable past turn's notes no longer wipes its narration. If a turn's stored JSON couldn't be parsed, saving a notes edit on that turn wrote a blank stub — destroying its narration, choices, and turn id. The notes write now bails when the turn doesn't parse (leaving it untouched), matching the digest/diary paths. Verified: a corrupt turn's content is left intact on a notes edit, while a normal turn still takes the note with narration/choices preserved.
  • A fresh world (or an aborted opening turn) no longer falsely shows "viewing history". With an empty message history the page counter landed on 0 while the total was floored to 1, so currentPage < totalPages flagged history mode — showing a "Viewing turn 0 of 1" banner, disabling choices/location/edit, and dropping Player Notes edits (the write targeted message index −1) before the game even started. The current-page follow now floors at 1. Verified: empty history → page 1, not viewing past, no banner.
  • Stat bars no longer animate away twice when you submit an action. On submit the green/red band drained once, then instantly re-grew and drained again. Cause: currentPage was synced to the latest turn by a post-render effect, so appending your action grew the page count a frame before currentPage caught up — flipping "viewing history" true for one render and remounting the stat band. currentPage is now derived (GameplayContext): it follows the latest turn automatically unless you've paged back, so it can't lag and the flip is gone at the source — fixing every panel, not just the bars. Verified by counting band mounts across a real turn: grow → drain (one), previously grow → grow → drain. Side effect (intended): paging back during generation is now sticky — a new turn no longer yanks you to the latest until you navigate or take an action.
  • Loading a save shows the real stats, not the world's starting values. After loading a mid-game save, the live stats panel could briefly (or persistently) show the world's default values instead of the saved ones, because a reactive effect re-seeded stats from the world whenever its definition loaded — racing with the save restore. Seeding now happens once, only when starting a fresh game (the load path is separate), so a loaded save's stats are never overwritten. Verified: loading a save shows its saved stat values, with each stat's game-start baseline intact.
  • Code-driven stats no longer wipe a turn's regen. After a turn, applying stat code re-set the whole stats array from a snapshot taken before the code ran — so if regen (or a re-generate) landed in between, it was overwritten. The code result now updates only the stats the code actually moved, layered onto the latest values, so regen and concurrent changes survive.
  • Turn/page internals cleanup. The paged turn's assistant message was JSON-parsed twice per render (once for choices, once for notes) — now parsed once. The page↔message index math (page·2−1 for the turn's narration, page·2 for the next action) is centralized in tested pageAssistantIndex/pageNextActionIndex helpers instead of being re-encoded across the view selectors, rollback, and re-generate. No behavior change.
  • Stat bars don't double-grow / lose regen from a redundant recompute. Separately, after a turn processStatCode always handed back a fresh array even when no stat had code, so applyStatChanges re-set the stats a second time — from a pre-regen baseline — replaying the grow and wiping that turn's regen. processStatCode now returns the original array when nothing changed, so the redundant update is skipped. Unit-tested (same reference on no-op, new reference on a real code change).
  • The opening turn's stat changes read from the world's starting values, not zero. Page 1 always showed green "+full value" bars because it had no earlier turn to compare against and fell back to 0. Each stat's game-start value is now recorded (starting, populated at game init from the world default), so the first turn's green/red deltas reflect what actually changed from the world's starting stats. Additive save-shape (starting on saved stats); old saves without it fall back to the previous behavior on their opening turn. Preview-verified: turn 1 shows +2/+5 from the starting values instead of +5/+30 from zero.
  • Rollback/Re-generate now carry the target turn's own notes, not the latest turn's. With per-turn notes, handleRollback/handleRegenerate restore with keepLiveHistory (which skips the snapshot's notes), so the live scratchpad still held the pre-rollback latest turn's notes — a re-generate then froze those onto the fresh turn. Both handlers now seed playerNotes from the target turn's message notes (parseTurnContent(...).notes ?? '') after the restore. Preview-verified: rolling back to a turn seeds the scratchpad with that turn's notes.
  • Per-turn Player Notes (AITurnResult.notes, additive save-shape). Notes moved from the single global playerNotes scratchpad to a per-turn field frozen onto each turn's assistant-message JSON when the turn commits (omitted when empty). GameplayContext gained viewNotes (current page → live scratchpad; past page → that turn's message notes, falling back to the snapshot's global playerNotes for old saves) and a page-aware setViewNotes (edits on the current page write the live scratchpad; on a past page they patch that turn's message only). The Notes tab consumes both; notes stay editable on any page. The live scratchpad is still what the AI receives each turn, so send behavior is unchanged. No migration needed — the snapshot-playerNotes fallback covers pre-existing saves. Preview-verified on the whiteRoom fixture: a note typed on the current page doesn't bleed to past pages, a note typed on a past page persists to that turn only (confirmed on the message JSON) and not its neighbors, and the live page keeps its own note.
  • Paging back mid-generation no longer drags the streaming narration onto the history page. While a turn was still generating, flipping to an earlier turn kept printing the new narration onto the page you were viewing. Generation now continues in the background while you browse history — the past page shows that turn's finished text — and the live narration reappears when you return to the current turn. Fix was render-only (MiddlePanel): the live reveal (narration + reasoning) is now gated on being on the current page (!isViewingPast), not just on a page-local "last message" flag.
  • Player Notes are now per-turn — each turn keeps its own notes as you page back. Notes used to be one shared box for the whole game; paging to an earlier turn still showed (and edited) that single global note. Now every turn carries the notes it had, so flipping back shows that turn's notes and you can edit them there without touching any other turn. On the current turn the box works exactly as before (a running scratchpad the AI sees), and Re-generate carries your notes onto the fresh turn. Old saves still load — a turn with no saved per-turn note falls back to the save's previous global note.
  • Save files no longer store the chat history N times over (storage cleanup + migration). Each per-turn snapshot (currentState + every stateHistory entry) embedded its own copy of the whole flat message history — O(N²) growth on disk. The envelope now carries one canonical top-level messageHistory; snapshots are stripped of their fullMessageHistory copies (stripSnapshotHistory, version.ts), and saveGame writes the new shape. Loading reconstitutes the live current state from the canonical history, so narration/rollback are unchanged. Save-file shape change with a presence-based migration in the shared migrateSave path (import + load): any old save — legacy numeric version: 2 or a string-version save written before this change — has its history hoisted and copies stripped on load, idempotently; old saves still load. The import boundary now runs migrateSave for every envelope (not just numeric-legacy). Unit-tested (saveCompat.test.ts: hoist + strip on legacy and string-version saves, idempotency, canonical-history correctness); preview-verified the whiteRoom fixture (an old-shape save) still loads all 8 turns through the migration with the live history intact.
  • Shared, non-reflowing page footer (Pager). Three pagers — game turns, the AI-context debug viewer, and the community browser — each carried their own copy of the same item loop (first, last, ±1 window, ellipsis gaps), so the centered strip's width, and thus Previous/Next, shifted while flipping. Extracted one Pager component (components/ui/pagination.tsx) over a pure paginationSlots(currentPage, totalPages) (pagination.ts) that returns a constant number of cells (min(totalPages, 7)), padding short/near-edge layouts with invisible spacers; every cell is normalized to the same width (links w-10, spacers h-10 w-10, ellipsis overridden to w-10). Constant count × equal width ⇒ invariant strip ⇒ the buttons never reflow. All three call sites now render <Pager page pageCount onPageChange /> — the three duplicate loops (~60 lines) are gone. For near-edge layouts the spacers are distributed, not tail-padded: low pages left, high pages right-anchored. Pager coalesces each contiguous spacer+ellipsis run into one flex cell (width = the cells it replaces, incl. inter-cell gaps, so the strip width is unchanged) with the ellipsis centered — so a lone ellipsis sits dead-center of the gap even when the groups are lopsided (1 2 3 4 … 8), not jammed against a cluster. The active page uses the filled default button variant (was the near-invisible outline). Pure logic unit-tested (pagination.test.ts); the DEV whiteRoom fixture extended to 8 turns to exercise it — preview-measured: ellipsis 0px off gap-center, Previous/Next pixel-identical across pages, active page bg-primary.

---

✅ 2.1.0 — Released — reasoning-model support (Native mode, endpoint-aware effort, per-prompt reasoning, desktop thought budget, live reasoning block), shareable prompt presets, a first-run welcome animation, and a halved Vulkan-only desktop build (click to expand)

Minor Changes

➕ Added

• 👤 User-facing

  • Share prompt presets — Settings → Prompts now has an Export button and an Import Preset… entry in the preset dropdown. Export gives you a copy-paste share code (for Discord/chat) or a .json file; the whole preset travels — all prompt text, its section style, and its per-prompt tuning (samplers, reasoning, verbatim turns). You can export any preset, including the built-in Default/Simple as starting points. Import lets you pick a file or paste a code, previews the name and any "made for a different version" note, and lets you choose prompt text only vs text + tuning; if the name already exists you can overwrite it or keep both. Presets made in another version import as-is — anything the app doesn't recognize is skipped.

  • A first-run welcome animation — The first time you ever launch Formamorph, a "Welcome To…" title types in and a field of liquid "goo" pops up, gathers together, and merges into the Formamorph title before handing off to the menu. It plays once (never again automatically) and respects your reduced-motion setting (shows a still title instead). Click the tiny version number in the footer to replay it any time (snappier the second time around).

  • Native Reasoning control for reasoning models — The Thinking mode formerly called Off is now Native — it adds nothing to the prompt, so a reasoning model thinks as it normally would and everything else answers immediately. When Native is selected, a Native Reasoning control appears with Default (send no hint — the endpoint decides), None (stop a reasoning model from thinking so it answers directly), and effort levels. The levels shown are detected from your endpoint — the app quietly asks it which it accepts on connect, so you only see options that actually work (e.g. some endpoints offer Min, others Max). While it's still probing (or your endpoint is offline) it shows the universally-safe set. All of it is ignored by models without native reasoning.

    Reasoning is no longer an all-or-nothing switch: it's per-prompt. The Narration and Choices prompts each get their own Native Reasoning control in their Options tab (Settings → Prompts → pick prompt → Options) — narration follows the endpoint-wide level (Global) by default, choices is None. Every other prompt (stat updates, location, summaries, images, the planning stages) never reasons, so a reasoning model won't waste time thinking on bookkeeping. And the Inline / Planning / Staged thinking modes now turn a reasoning model's own thinking off entirely, so it doesn't fight Formamorph's planning step.

  • Reasoning Budget on the built-in desktop engine — When you run Formamorph's own bundled model (desktop app, no custom endpoint), the reasoning control in Narration/Choices Options becomes a Reasoning Budget slider — the share of Max Output Tokens the model may spend thinking before it writes (0% = no reasoning). It's an exact, graceful cap: the model wraps up its thought and gets on with the scene, so you trade a little planning for a lot less waiting. Narration defaults to 40%, Choices to 0%. (This precise budget isn't available over most external endpoints — those keep the coarse effort control instead.)

  • See a reasoning model's thinking — When a reasoning model (or the Inline thinking mode) thinks before it writes, that scratchpad now shows as a collapsible "Thinking…" note above the turn's narration — it streams live while the model thinks, then folds up to "Thought for Ns" once the story begins. Click to re-open it any time; it's saved with the turn, so it's there on old turns and in scrollback too. A new Show Reasoning toggle (Settings → Generation, on by default) hides it if you'd rather not see it — the reasoning is still captured, so turning it back on reveals it on past turns.

• 🛠️ Developer tooling

  • Inline thinking reliably opens the <think> block now (placement fix). The Inline-mode reasoning directive was buried at the end of the narration system prompt, where small models mostly ignored it — so the new "See a reasoning model's thinking" block often stayed empty in Inline mode. Rewrote INLINE_THINKING_DIRECTIVE to a tight 3–4-bullet continuity structure and moved it onto the final player-action turn (adjacent to where the model writes, same trick the Planning plan uses). A new A/B probe (testing/baseline/harness/inline-probe.mjs, 9 gold scenarios × 2 runs on the reference tiers) isolated the cause: the reworded directive still in the system prompt emitted <think> on only Silver-Siren 2/18 · MeroMero 5/18, but the same text on the user turn hit 18/18 on both, every one followed by clean narration with no bullet-leak into the prose. Recency — not wording — was the lever. Prompt/plumbing only; no version/save/export impact.
  • Desktop build roughly halved — Vulkan-only GPU backend (CUDA dropped). electron-builder now excludes node-llama-cpp's CUDA backends (@node-llama-cpp/*cuda*, ~537MB), the unused Windows arm64 backend, and the from-source gitRelease.bundle. Reason (investigated, not assumed): the CUDA prebuilts need CUDA redistributables that don't ship with node-llama-cpp and aren't on normal systems, and even with the exact-matching redist the prebuilt initializes 0 devices on a reference RTX 4090 + CUDA-13.3 driver — a liability that only balloons the download while showing a "CUDA not compatible, falling back" warning every launch. Vulkan runs on every GPU including NVIDIA (it's what the reference machine used all along), so it's the shipped GPU backend with CPU fallback. A clean Windows --dir build measured 548MB, down from 1134MB (−52%), and boots. A dedicated CUDA build (bundling the redistributables) can come later. Config only — no code/version/save impact.
  • Desktop package ~350MB lighter (renderer deps no longer double-shipped). Every renderer library (react, three, kokoro, onnxruntime, Radix, fonts…) was listed in dependencies, so electron-builder auto-packed its raw node_modules copy into the app — dead weight, since Vite already bakes them into dist/. All renderer-only packages moved to devDependencies; dependencies now holds just node-llama-cpp (the one package the Electron main process loads at runtime — verified by grepping every require/import in electron/*.cjs). Verified on a real --dir build: app.asar is 52MB (≈ dist + app code), its 92 packages are node-llama-cpp + transitive deps only, zero renderer packages remain, and the built exe boots. Faster launch for the portable exe (that much less to extract + virus-scan every start) and a smaller download.
  • reasoningEffort setting + Native rename. ThinkingMode's off value is relabeled Native in the UI (the stored value stays 'off', so no settings migration); added ReasoningEffort = 'none' | 'auto' | 'low' | 'medium' | 'high' (SettingsContext, FORMAMORPH_reasoningEffort, default auto; none will send reasoning_effort: "none" to suppress native thinking). The Settings → Generation → Thinking block gains a Native Reasoning tabs widget rendered only under Native (thinkingMode === 'off'), mirroring the Thinking widget's stacked-help layout. All of the reasoning-effort logic is pure + unit-tested in src/lib/reasoningEffort.ts:
    • Endpoint capability detection. detectSupportedReasoningEfforts(url, token, model) probes each candidate (none/minimal/low/medium/high/xhigh/max) with a 1-token request and keeps the 200s (400 = rejected; any network/auth error → null = inconclusive, keep fallback). SettingsContext runs it debounced on connect and remembers each endpoint|model's result in a bounded map (FORMAMORPH_reasoningSupport, cap 30, oldest evicted), so flipping between endpoints or swapping the model on one reads from cache instead of re-probing; it exposes supportedReasoningEfforts for the active pair. reasoningTabs(supported) builds the tabs — always Default (omit) first, then the supported levels in canonical order — falling back to the universal none/low/medium/high when the set is unknown. Verified live: cloud accepts all seven; Ollama accepts none/low/medium/high/max (no minimal); an offline endpoint falls back to the safe set.
    • Request wiring. reasoningEffortBody(mode, effort, supported) is spread into makeAIRequest's body: under Native it sends reasoning_effort verbatim and omits it for auto (send nothing → endpoint default; the literal auto isn't a valid value anywhere — every backend 400s on it); under the guided modes (Inline/Planning/Staged) it forces none so a native model's own thinking doesn't fight the guided step. In every case a value the detected set doesn't include is omitted, so none can't 400 a non-reasoning endpoint and a stale selection can't 400 a turn after switching endpoints.
    • Per-prompt override. resolvePromptReasoning(kind, prefs, globalEffort) picks each request's effort under Native mode: REASONING_CONTROL_KINDS (narration, choices) read their stored choice (now preset-scoped via activeReasoning, defaults narration=global, choices=none), every other prompt is forced to none; global folds in the Generation-level reasoningEffort (which no longer applies to requests on its own). The control renders in the prompt's Options tab (PromptReasoningField) only under Native mode for the two controlled kinds, disabled under the built-in Default preset. makeAIRequest feeds the resolved value through reasoningEffortBody.
    • Reasoning block (capture + persist + UI, additive save-shape). The narration stream now captures reasoning from both sources — a native model's separate reasoning/reasoning_content delta field and inline <think> blocks in content (extractReasoning/extractReasoningLive, unit-tested) — with think-duration timing (first token → first narration token). It's persisted into the per-turn assistant-message JSON as reasoning: { text, ms } (AITurnResult) — an additive save-shape change (absent when the model didn't reason / on pre-2.1.0 saves; presence-based, old saves load fine). Live streaming rides an external store (reasoningStreamStore, mirroring gameplayTextStore so per-token updates don't re-render gameplay). ReasoningBlock renders it above the narration (MiddlePanel): expanded + "Thinking…" while active, auto-collapsing to "Thought for Ns" when narration begins, full markdown in a de-emphasized container. Gated by the showReasoning setting (default on; captured regardless, so toggling on reveals past turns). Verified: model emits <think>/reasoning (node-confirmed), helpers parse it (unit tests), the app correctly captures nothing when the model emits nothing, and the block renders/collapses/styles correctly (preview, injected data).
    • Reasoning Budget (local engine — thought-token cap). The reasoning control is engine-split in the Options tab: external endpoints show the effort level; the bundled desktop engine (localModelActive) shows a Reasoning Budget slider (0–100% of max output). reasoningBudgetBody(mode, kind, budgets, maxTokens) → { thinking_budget_tokens: round(pct% × maxTokens) }, spread into makeAIRequest's body only when localModelActive; guided modes and uncontrolled prompts resolve to 0. electron/llmEngine.cjs maps body.thinking_budget_tokens → session.prompt({ budgets: { thoughtTokens } }) (node-llama-cpp; verified exact — capping to 200/100/40/0 landed on the cap, narration stayed coherent, latency scaled). This also fixes a gap: the local engine ignores reasoning_effort, so guided-mode/None suppression is now enforced there via thinking_budget_tokens: 0. Per-prompt %, preset-scoped (reasoningBudget on PromptPreset, defaults narration 40% / choices 0%), travels with preset export/import. Preset-share shape change (additive): the shared preset .json/code gains an optional reasoningBudget map (older imports drop it; FORMAT_VERSION unchanged). Pure logic unit-tested; UI (engine swap + defaults) verified in preview by forcing the local branch. Desktop end-to-end confirmed by driving the real llmEngine.cjs server standalone: thinking_budget_tokens of omit/200/40/0 capped the <think> block to 1785/873/161/0 chars, narration stayed coherent at every budget (incl. 0).
  • Intro sequence (src/components/IntroSequence.tsx) — a self-contained Canvas 2D + SVG-metaball-filter animation. Two layers (themed background + a blob layer behind a feGaussianBlur+feColorMatrix goo threshold), with the real letterforms drawn onto the filtered layer so they read crisply while keeping liquid edges; the word's alpha ramps through the threshold across the whole hold so it appears to set out of the goo rather than fade in. Colors are pulled live from the app's CSS theme tokens (--primary/--card/--background), so it adapts to the active skin. The puffy title face is a ~2KB Baloo 2 subset embedded as base64 (src/lib/introFont.ts), loaded via FontFace before canvas sampling. First-run gating is a localStorage flag in App.tsx (cinematic first, snappy on replay); the overlay mounts over MainMenu and fades its backdrop out on hand-off to reveal the menu underneath. Reachable for verification via the dev-router (#dev?modal=intro).

• 🛠️ Developer tooling

  • Cross-version chip compat locked (import safety). Confirmed + regression-tested that the prompt tokenizer already treats any chip it doesn't recognize as literal text — so a preset imported from a different app version can't blank, drop text, or crash the editor/preview/runtime; a chip added in a later version just shows as its raw <…> token until that version is installed. parsePromptTemplate's registry-only TOKEN_RE is the single chokepoint (editor, preview, renderPromptTemplate all route through it); new tests in promptTemplate.test.ts cover a foreign base and a foreign variant across parse/serialize/render. No behavior change.
  • Prompt-preset export/import UI. PresetShareDialogs.tsx (ExportPresetDialog + ImportPresetDialog) wired into Settings → Prompts: an Export button (materializes the selected preset — built-ins included — via exportActivePreset(APP_VERSION)) and an Import Preset… Select sentinel. Import parses a file or pasted code (parseSharedAny), previews name + non-blocking warnings, offers texts-only vs +tuning and overwrite-vs-keep-both on a name clash, then importPreset(imported, opts) adds (addFullPreset) or overwrites (replacePreset) and selects it. Export/import round-trip verified live (code decodes to the full stamped preset with tuning; import created a distinct copy, showed the version warning, handled the collision). Not an export-shape change to worlds/saves — a new shareable format (like character cards).
  • Prompt-preset share codec (src/lib/promptPresetShare.ts). Serializes a preset — 15 texts + section style + preset-scoped tuning (samplers/reasoning/verbatim) — to a pretty .json file and a copy-paste share code (UTF-8-safe base64 behind an FMPRESET1: prefix). Stamps kind + formatVersion (1) + the source appVersion. Parsing sanitizes: keeps only recognized text keys and well-typed tuning, silently drops the rest (with a warning), and a source-version/newer-format mismatch warns but still imports as-is (the agreed "import as-is + warn" contract). Groundwork for the import UI; not wired to any surface yet. Unit-tested (round-trip, unicode, junk rejection, unknown-key drop, version/format warnings). Part of the shareable-preset feature (see docs-internal/prompt-preset-sharing.md).
  • Per-prompt tuning is now preset-scoped (settings-store change). Samplers, per-prompt reasoning, and verbatim-turns moved from three global stores (FORMAMORPH_promptSamplers / _promptReasoning / the six _*VerbatimTurns keys) onto each PromptPreset (samplers/reasoning/verbatim fields in src/lib/promptPresets.ts) — groundwork for shareable "prompt packs". Built-in presets carry no tuning (resolve to shipped defaults; their tuning setters no-op like their text). SettingsContext derives the three via activeSamplers/activeReasoning/activeVerbatim(presetStore) and routes setters through updateSamplers/updateReasoning/updateVerbatim (no-op under a built-in) — the public context field/setter names are unchanged, so GameViewer/SettingsModal consumers are untouched. A one-time migratePromptTuning() folds the old global tuning onto every user preset (via foldTuningIntoUserPresets, never overwriting an existing per-preset value, only carrying non-default verbatim), then retires the old keys behind a _promptTuningMigrated marker. Behavior change: switching presets now swaps tuning too (previously text-only); a user on a built-in with custom tuning reverts to defaults there (by design). Pure logic unit-tested; migration verified live. Settings-store only — not world/save export shape.

🐛 Fixed

• 👤 User-facing
  • The welcome animation now matches your theme — On a dark theme the first-run intro rendered on a white background with the "Welcome To…" text invisible (white on white). It read the theme's colors a moment too early — before your theme was applied — so it always grabbed the light-theme palette. It now tracks the active theme, so the intro shows on the correct background with readable text in light or dark.
  • The desktop app now works with local AI servers that don't send CORS headers — On the desktop build, pointing at a custom endpoint whose server has CORS turned off (e.g. some LM Studio setups) failed every request with a generic "Failed to process AI request" — the browser layer blocked the call before it left the app, so no error detail ever surfaced. The desktop app now handles this itself, so a custom endpoint works regardless of the server's CORS setting. (The browser build still needs the server's CORS enabled — that's a browser rule the web version can't bypass.)
• 🛠️ Developer tooling
  • Intro sequence samples theme tokens inside the rAF loop, not once at mount. IntroSequence read --background/--card/--primary via getComputedStyle in its mount effect — which fires before the parent ThemeProvider's effect adds the .dark/.light class, so it always caught the classless :root (light) defaults, while the kicker's live text-foreground flipped to the applied theme → white-on-white on a dark theme. readColors() now runs at the top of each frame() (and renderStatic(), whose reduced-motion call is deferred one rAF), so the canvas tracks whatever theme CSS currently resolves — in lockstep with the CSS-driven kicker, and self-healing if the OS theme flips mid-intro. Verified deterministically (rAF is throttled in a hidden preview tab, so live capture is unreliable): reproducing the token math showed the classless read yields --background: hsl(0 0% 100%) (white) vs hsl(220 12% 10%) (dark) with .dark applied.
  • Desktop CORS shim. The renderer's app://local origin made every external fetch (custom LLM endpoint, community server, Hugging Face) browser-CORS-gated; a server with CORS off failed the preflight (no Access-Control-Allow-Origin) and surfaced only as a network-level TypeError: Failed to fetch → the generic toast. electron/main.cjs now rewrites external http(s) responses (including the OPTIONS preflight) via session.defaultSession.webRequest.onHeadersReceived to carry permissive CORS headers — keeping the normal streaming fetch and leaving webSecurity on (not webSecurity: false, which would drop cross-origin protections app-wide given the app loads community-authored worlds). The pure header transform lives in electron/corsShim.cjs (Authorization is listed explicitly because Access-Control-Allow-Headers: * excludes it per spec); Node-verified. The web build is unaffected — browsers enforce CORS, so hosted users still need the server to send the headers.

---

✅ 2.0.3 — Released — per-world save folders, per-prompt sampling & rebuilt Planning mode, portable-build data folder, smoother narration reveal, and a batch of editor/menu UX fixes (click to expand)

Minor Changes

➕ Added

• 👤 User-facing
  • Saves are now organized into per-world folders — Opening Load Game drops you straight into the current world's folder, listing only its saves — the common case is now one step. A Back button (under Import) and a Saves / <world> breadcrumb take you to the root, where every world with saves has a folder (the current world is always first, even when empty), each showing its save count and when it was last played. Saves and folders can be dragged into any order by a handle on the left, and new ones always appear on top. On a save row, Download and a ✕ delete (which now asks before deleting) sit on the right. Loading a save from a different world now actually switches to that world (after a confirmation) instead of loading in place — or, if that world isn't installed, warns you it'll load into your current world and lets you decide. Importing a save file drops it into its own world's folder and takes you there. Saving a name that already exists in the current world lets you overwrite it or keep both. You can also load a save straight from the main menu — its cog is now a hamburger with Load Game and Settings; picking a save loads its world and drops you into the game (a save whose world you don't have installed explains that and offers download/delete).
  • Per-prompt sampling controls — each prompt's editor (Settings → System Prompts) gains an Options tab with Custom Temperature and Custom Repetition Penalty controls: tick either to override that one prompt's sampling on a slider, or leave it off to use the smart default. The behind-the-scenes helper prompts default to tuned values so their bookkeeping and scene-planning stay consistent — Stat Updates, Location Change, and Summary run low/near-deterministic, while the Planning step runs at a moderate temperature with the repetition penalty relaxed (which it needs to keep every character in a scene). Creative prompts (narration, choices, …) follow your endpoint's own settings. Like the custom-endpoint fields, a value you dial in is kept (just unused) when you switch the override back off. The editor's Verbatim turns field moved onto this Options tab too.
  • Steadier scenes in Planning mode — the optional pre-turn Planning step (Settings → Generation → Thinking → Planning) was rebuilt as a lightweight scene-continuity planner. It now carries the previous scene forward — who was present, what they were holding, where they stood — so the narration doesn't quietly drop a character mid-conversation or swap an established object for a new one, and it names the cast up front. A single call that does the job of the heavier Staged mode's first stages, tuned and verified on both a 12B and a 24B local model.
  • Planning mode fills the scene list — the cast the Planning step names now drives the Entities panel (who's present this turn), the same as Staged mode already did. And a character whose name the player hasn't heard yet is kept out of the narrator's hidden plan — the planner refers to them by how you currently know them ("the silver-haired woman") until the name is actually spoken in the story, so the plan can't accidentally spoil a reveal.
  • The Entities tab is now a live scene list — in Planning and Staged modes it shows exactly who is physically present this turn (sourced from the planner's cast, so someone merely mentioned — "my father, King Luke" — no longer wrongly appears), with their portrait. A character you haven't been introduced to yet shows by how you currently know them ("the hooded woman") and their picture, and their real name appears the instant the narration first speaks it. Off/Inline modes keep the previous behavior (the tab is filled from names found in the narration). Opening a not-yet-named character's detail card is held back until the name is revealed, so the list itself can't spoil it.
  • Portable desktop builds now keep everything in their own folder — The Windows portable .exe and the Linux AppImage store all your data — saves, settings, worlds, and your character library — in a userdata/ folder right beside the app, instead of tucked away in your OS profile. Copy that folder (or the whole portable directory to a USB stick) and your entire setup moves with it. The first time you run the new build, existing data is migrated across automatically. The macOS build installs normally and is unchanged. The version in the corner also now shows the build type — portable, installed, or dev — so you can tell at a glance which build you're on (the browser build stays unlabeled).
• 🛠️ Developer tooling
  • Save store re-keyed to a stable id + per-world folders (save-shape change). The IndexedDB saves store (keyed by name) is replaced by saveRecords (keyed by a uuid id), so identical names can coexist across and within worlds; a one-time upgrade migrates existing rows, minting an id and best-effort stamping worldId by matching each save's worldName to an installed world (unmatched saves stay name-only and group by name). New saves carry SaveObject.worldId (from WorldOverview.id's owning World) — an additive save-file shape change (the exported .json gains worldId; the device-local id is stripped on export, re-minted on import). This additive shape change is what 2.0.3 carries — the version bump lands with it. Grouping/ordering logic is pure + unit-tested in lib/saveOrdering.ts (groupSaves/folderRefFor/mergeOrder); ordering is device-local (a separate saveOrder store keyed by __folders__ / folder key), so it never touches exported saves. saveGame/loadGame now key by id; MenuModal rebuilt around folder/root views with dnd-kit reorder (mirrors the DictionarySelectionModal pattern). Cross-world load is a real world switch: onLoad(id, worldId) → GameViewer calls getWorldData(worldId) → loadWorldData → loadGame against the target world's locations (previously the save loaded into the current world's shell); an uninstalled world can't be switched to, so it warns and loads in place (current world's rules) — harmless (the location lookup is guarded; foreign stats/entities degrade to no-ops), so it's left to the player. The load UI is extracted to a shared LoadGameDialog used by both the in-game menu and the main menu; groupSaves takes an optional current (omitted in the main menu → no pinned folder). The main menu's cog became a [Load Game, Settings] hamburger; a cold-load there resolves the save's world (getWorldData → loadWorldData) and hands the save id to App (initialSaveId), which GameViewer restores on mount instead of starting fresh — an orphaned save is blocked there (no world to run it in).
  • Precall planning wired into participation — the Planning step now parses its Scene/Cast/Beats output through the shared classifyCast (extracted from runStagedPlanning so both paths bucket identically) into defined-entity (loose-match) + ad-hoc (strict-match) candidates that the narration confirms, exactly like the staged director. And sanitizePlanForReveal rewrites any cast name absent from past narration to its parenthetical alias — or a neutral fallback when the model gave none — across the whole plan before it's injected, a code backstop for the prompt's name-spoiler rule that larger models honor unevenly. lib/stagedPlanning.ts.
  • Scene list re-sourced from the planner cast (SceneEntity, save-shape change) — GameState.visibleEntities grows from string[] to SceneEntity[] ({ name, alias?, revealed }). A new buildSceneList (lib/stagedPlanning.ts) maps the turn's planner cast to the tab: canonical entity name for the portrait tie, the alias carried through, and revealed computed against the narration (prior turns + this turn so far, so it flips mid-stream); with no planner it falls back to findEntityNames. runStagedPlanning now returns its NPC cast; GameViewer drives the list at stream-start, per-sentence, and finalize (via a ref, since the narration stream runs at component scope). Old saves load fine — a bare string[] normalizes to { name, revealed: true } on load (normalizeVisibleEntities), non-destructive, no migration of stored files. New saves write the richer shape.
  • Per-prompt sampler resolution (lib/promptSamplers.ts) — resolves each request's temperature and repetition penalty: a pinned or custom value goes to every endpoint; an unpinned prompt sends the global slider value on the built-in engine but omits the field on a custom endpoint, so LM Studio / Ollama apply the model's own configured value (see the verified endpoint-temperature behavior). Every pin was set from measured probe sweeps against a 12B + 24B local model (testing/baseline/harness/*-probe.mjs), not guessed: statUpdates 0.2, locationChange 0.15, summary greedy 0 (small models echo dialogue verbatim above it), and — the odd one out — thinking (Planning) at temp 0.4 with repetition penalty 1, because that prompt inverts the usual rule: its greedy default is to drop cast members the action doesn't engage (so it needs entropy to keep the scene), and a repetition penalty on the list-shaped cast roster suppresses completeness and drives invented characters. Overrides persist as one promptSamplers localStorage record.
  • Portable profile + build-type indicator. Electron redirects userData to <portableRoot>/userdata for relocatable builds (runtime PORTABLE_EXECUTABLE_DIR / APPIMAGE), moving the whole Chromium profile beside the exe; on first run it copies the persistent stores (IndexedDB, Local/Session Storage — caches skipped) out of the old default location once. Pure, electron-free logic lives in electron/portableProfile.cjs (unit-testable). The build type is baked via a Vite __BUILD_TARGET__ define fed by FORMAMORPH_BUILD (set per target in the release workflow: portable for the Windows portable + Linux AppImage, installed for the mac dmg, web for the browser build), surfaced as BUILD_TAG in lib/buildInfo.ts and shown in the footer (empty → dev). The portable artifact is renamed Formamorph-${version}-portable.exe so a future NSIS installer (-setup.exe) can't collide. Release workflow's official actions bumped to current majors (checkout 7, setup-node 6, upload-artifact 7, download-artifact 8).

🐛 Fixed

• 👤 User-facing
  • Load Game menu no longer clips or overflows — Save rows were fixed-height buttons, so a long save name or the "different world" warning spilled out of the row instead of growing it, and a long list of saves ran off the bottom of the dialog with no way to scroll. Rows now expand to fit their contents, the list scrolls when it's taller than the dialog, and the per-save Delete (left) and Download (right) controls sit on opposite ends for less mis-clicking.
  • Long names in dictionary and picker lists now clip with "…" instead of overflowing — A long entry/dictionary name (or entity/theme label) stretched its row past the panel's edge, pushing the duplicate and delete buttons out of reach. Those rows now truncate the name with an ellipsis and keep their controls in view.
  • Opening the World Editor from the menu now animates and no longer reloads the whole menu — It opened as a hard screen swap and, on close, rebuilt the entire main menu (a visible flash plus a redundant re-fetch and profile re-check). It now opens with the same full-screen zoom-from-center animation as Community Creations, and closing it (via its back arrow) just refreshes the world grid, keeping the rest of the menu untouched. The distracting "New world ready" toast on creating a world was also removed.
  • New worlds no longer start with a broken thumbnail — Creating a world seeded a placeholder image from an external host that no longer resolves, so the new world showed a broken image. New worlds now start with no thumbnail (the same clean fallback used everywhere else) until you set one.
  • Every World Editor tab now shows a hint when it's empty — Only Locations did before — Stats, Entities, Traits, and Dictionaries were just blank, leaving you unsure whether to add something or whether it failed to load. They now all show the same "No … yet — use the + button to add one." hint (and a "no matches" note when a search comes up empty).
  • Prompt editor's "Thinking" tab renamed to "Planning" — to match the Thinking-mode option it edits (Off / Inline / Planning / Staged), which was already labeled Planning.
  • Re-generate no longer flashes the old narration — Pressing Re-generate briefly animated the entire previous narration (every paragraph at once) before clearing and streaming the new text. The reveal now only animates while the new narration is actually streaming — during the setup/thinking phase it shows the settled text — so the flash is gone.
  • Smoother narration reveal — a cluster of long-standing glitches in the animated text reveal traced to several compounding causes, now all fixed. The core one: the sentence detector didn't understand markdown, so a sentence ending inside emphasis (*screech.*), a paragraph ending on an em-dash, or a bare **Power: 88%** line never counted as a boundary — whole paragraphs fused into one giant "sentence" that starved the reveal (stutter), then animated across the paragraph break in one burst. Sentence boundaries now recognize closing emphasis markers, and a blank line always ends a sentence (this also fixes streamed text-to-speech chunking at the same spots). On top of that: the reveal now lets each paragraph finish landing before the next begins, no longer has a speed floor faster than slow models can generate (the old cap forced stuttering on any model under ~11 words/s), and uses a tighter per-word fade so a sentence finishes fading within its own span instead of being cut off by the next one. Most importantly, the reveal no longer guesses at a tokens-per-second rate (which a server's initial burst of text could throw off for the whole turn) — it now measures the real time between sentences as they arrive and paces to that, keeping a small buffer so it never runs dry (stutter) or lags far behind (text still revealing long after the choices appear). It also remembers the measured speed between turns, so after the first turn it already knows roughly how fast your model is and starts at the right pace instead of ramping up from a cautious default.
• 🛠️ Developer tooling
  • World Editor is now an in-place modal, not a top-level view. It moved from an App currentView branch into a MainMenu-hosted full-screen <Dialog> (reusing Community Creations' classes) so the menu stays mounted and animates; a new refreshWorlds callback (mirroring refreshDictionaries/refreshEntities) refreshes just the world grid on close instead of remounting the menu. WorldEditor gained a backButton prop that decouples the header back arrow from embedded (GameViewer's embedded popup keeps its X; the menu modal shows the back arrow with no X, Esc/overlay blocked so the guarded back arrow is the sole exit). In the DEV dev-router, worldEditor moved from DEV_VIEWS to DEV_MODALS (reached via #dev?modal=worldEditor), and the drift-guard test was updated to match.
  • List rows clip instead of overflowing (root cause + shared empty-state). Two causes: a flex-grow/flex-1 truncating child needs min-w-0 to shrink, and Radix's ScrollArea wraps its viewport content in an inline display:table div that shrink-wraps to content width — overridden with [&>div]:!block on the shadcn ScrollArea viewport (safe: no horizontal ScrollArea exists anywhere). Dictionary row controls got shrink-0 so the name (not the buttons) absorbs the truncation. The per-tab "nothing here yet" hint is unified into one shared EmptyListHint component reused by every list/tree tab.
• ⚙️ Backend / invisible
  • Imported multi-turn saves from v1.2 no longer corrupt their page history. Converting an old (v1.2) save duplicated the opening page and dropped the current page from the turn history, so on a 3-turn save Re-generate and Rollback landed one turn too early (a page effectively vanished). Old saves stored their history as the prior pages only, with the current turn kept separately; the converter now appends the current turn as the final page (instead of a stale re-alignment that assumed the opposite) and stamps the newer discoveredEntities field onto every converted snapshot. Single-turn saves were unaffected and stay so. Already-imported broken saves aren't auto-repaired — re-import the original v1.2 file to fix them.
  • Phantom "empty scene" cast bullets no longer become participants. isEmptyCastName now also recognizes multi-word declarations like "no other characters present" / "no one else" (not only single-word sentinels such as "none"), so a planner or director that writes the empty scene as a cast bullet doesn't spawn a bogus participant. Affects both Planning and Staged.
  • Cast names with a role/alias parenthetical now classify correctly. Small models habitually gloss a cast line as Bram (ferryman) or Maela (the hooded woman); the cast parser kept the whole "Bram (ferryman" as the name, so it no longer matched the "Bram" entity and misfiled as an invented character (losing the entity tie). parseDirectorCast now splits the name from the parenthetical (shared with the reveal sanitizer via splitNameAlias) and captures the alias on the cast member. Confirmed on a live 12B via a new real-parser probe (harness/planning-parser-probe.test.ts): misclassification dropped from 5/9 cases to 0. Affects Planning and Staged participation.
  • Silent background requests no longer overlap. With Memory Summaries and Character Diaries both on, a turn-summary request could fire while a diary or character-discovery request was already running, doubling up on a single-GPU local endpoint; the three background jobs now strictly take turns.
  • Rollback snapshots no longer change after the fact. Repeating log entries incremented a counter on an entry object shared with already-saved game-state snapshots, retroactively editing them; the increment now produces a fresh entry.
  • Desktop IPC surface hardened — the desktop app's internal fetch bridge now accepts only http/https URLs (it could previously be asked to read file: paths), and an unused bridge that could load a model from an arbitrary absolute path was removed (models load by filename from the models folder only).
  • Duplication pass across the codebase — extracted shared helpers for the five copy-pasted blob-download flows, the three location-list serializers, the image providers' HTTP plumbing, the main menu's three drag-reorder handlers, the editor managers' draft-editing pattern, the settings-form row layouts, and the Location/Trait drag-tree scaffold (~480 duplicated lines removed, no behavior change).

---

✅ 2.0.2 — Released — old-save rollback/import fixes + summary-prompt hardening (click to expand)

Minor Changes

🐛 Fixed

• 👤 User-facing
  • The opening turn of an old (1.2) save can now be rolled back and re-generated — The 2.0.1 import fix handled later turns but left the very first turn dead — rolling back to it did nothing and its Re-generate button was inert. The opening turn now restores and re-rolls. (Its exact pre-turn snapshot was never stored, so a rolled-back opening lands one turn later, and re-generating it rebuilds a fresh start.) This also fixed re-generating the opening on any loaded save, not just 1.2 ones.
  • Importing an old (1.2) save now upgrades it properly — Bringing in a 1.2 save file used to stamp it as current without actually converting it — so its traits reached the AI as bare names (descriptions dropped) and its body-shape stats (belly / weight / bust) stopped driving the character model. Old saves are now migrated the same way whether you import a file or load one already in your library, and the two paths run identical conversion so they can't drift. ⚠️ If you imported a 1.2 save before this fix, re-import the original file to upgrade it — a save that was already brought in stays in its old state.
  • More consistent turn summaries — the memory-digest "summary" prompt (which condenses each turn for long-game memory) was hardened so its retellings come out uniformly short (one or two sentences, single line), lead with what you did, and never quote dialogue verbatim or invent a character name the narration didn't give. Verified on both a small (12B) and large (24B) local model.
• 🛠️ Developer tooling
  • The Sedge Landing baseline harness gained a summary profile (exercises the digest prompt) and per-profile settleMs, so a profile with async drainers can wait longer without slowing the others.

---

✅ 2.0.1 — Released — local LLM engine, AI image generation, dictionaries & character cards, themes, and more (click to expand)

Major Changes

➕ Added

• 👤 User-facing
  • Run a model locally — no endpoint needed (desktop) — the desktop app can now run an LLM entirely on your own machine, so no LM Studio / Ollama / cloud API is required. A bundled engine (node-llama-cpp) loads a GGUF model and serves it on a local OpenAI-compatible endpoint the app targets by default; flip Use My Own Endpoint on to point at a custom/cloud API instead. A model manager (Settings → Endpoint → Manage models…) has two tabs: Recommended — a curated catalog of community roleplay models grouped by the VRAM tier they fit (≤4 GB · ≤8 GB · ≤16 GB · No Limit, auto-selected from your detected GPU), each downloadable straight from Hugging Face with a live progress bar and pause / resume (a paused download survives closing the app); and Installed — every GGUF in your models folder, reorderable, with one-click Load / Unload and a confirm-first Delete. Runtime controls sit in the Endpoint tab behind a Simple / Advanced toggle: Context Size, GPU (a simple on/off, or an exact layer count in Advanced), Flash Attention, and sampling — Temperature, Max Output Tokens, Top-p, Top-K, Min-P, Repetition Penalty — beside a live GPU memory readout and engine status. Models are saved next to the app (portable — not buried in AppData), and it's cross-platform (Windows / macOS / Linux).
  • AI image generation — generate images for entities, locations, and world thumbnails right in the World Editor. A Generate with AI button drafts an SD-style prompt from the subject's description (via your text model), lets you tweak it, and renders through your configured image provider. Providers: a local A1111 / Forge server, and — in the desktop app — an OpenAI-compatible cloud image API (proxied through Electron to sidestep browser CORS). Prompts are LLM-refined into stripped danbooru / booru tags via an editable Tag Prompt (with a <SUBJECT> chip, Settings → Image Gen), plus a positive-prompt prefix for quality/style tags. Characters render at portrait dimensions, locations & thumbnails at landscape. Settings live in named, editable endpoint presets (a "Default" plus your own), switchable in Settings and from the generate popup. For A1111: an ADetailer face/hand-fix toggle and a live progress bar + in-progress preview while it renders.
• 🛠️ Developer tooling
  • Local LLM engine — electron/llmEngine.cjs dynamic-imports node-llama-cpp (ESM) from the CommonJS main process, loads a GGUF, and serves a minimal OpenAI-compatible chat-completions endpoint (streaming + non-streaming) on 127.0.0.1. It reconstructs the model's raw output — re-wrapping reasoning <think> segments via onResponseChunk — so structured aux requests (choices / stats / location) don't come back empty on models that segment their scratchpad. The renderer drives it over an IPC bridge (window.formamorphDesktop.llm): start/stop/load, status pushes, installed-model + partial-download listing, engine options (context / GPU layers / flash attention) with reload-on-change, and a Hugging-Face-only downloader (electron/modelDownload.cjs) using .part temp files, HTTP Range resume, and cancel. The catalog + VRAM tiers live in src/lib/localModels.ts (filenames/sizes verified against the HF API; reasoning models deliberately excluded for now). All of it is gated on isDesktop() and tree-shaken from the web build.
  • Linux & macOS desktop builds — electron-builder now targets AppImage (Linux) and dmg (macOS) beside the Windows portable exe (desktop:build:linux / desktop:build:mac). A release workflow builds all three from one v* tag (a Windows / Linux / macOS matrix) and attaches them to the GitHub Release.
  • Hosted browser build on GitHub Pages — deploys on every push to main, with the community-server features (Discover, login, publish) disabled in that build (VITE_ENABLE_COMMUNITY=false) so nothing unmoderated is surfaced by default. Play it at jakejamesdev.github.io/formamorph.
  • Web build release artifact — tagging a v* release also produces a formamorph-web-<tag>.zip (a full, community-enabled browser build) attached to the GitHub Release, ready to drop onto itch.io or your own host.

🐛 Fixed

• 🛠️ Developer tooling
  • Tagged desktop builds no longer fail on the Linux/macOS runners — electron-builder no longer tries to self-publish (missing GH_TOKEN); the workflow's own publish step handles the upload.

Minor Changes

➕ Added

• 👤 User-facing
  • Import tags from an image's metadata — upload a PNG that embeds its generation prompt (A1111/Forge, ComfyUI, InvokeAI, NovelAI, and other JSON-metadata tools) to an entity or location, and Formamorph offers to use that positive prompt as the Image Tags — no retyping. Declined images and plain photos are untouched.
  • Authored image tags — entities and locations now have an Image Tags field (under the image, above Generate with AI) that persists your booru tags. A shared ✨ toolbar with Undo / Redo writes tags from the description (and now also generates the AI-Facing Summary the same way). The Generate with AI popup edits those same tags two-way — tweak, generate, adjust, regenerate — and no longer auto-overwrites what you authored.
  • Danbooru tag autocomplete — the Image Tags fields, the Generate with AI prompt, and the world Tags editor suggest real Danbooru tags as you type, ranked by how commonly they're used, so you complete a tag with a keystroke instead of guessing spellings. Start typing to filter (an empty field shows nothing); the list loads on demand and works offline. The world Tags editor previously suggested tags scraped from the community browser (with a Refresh button) — it now uses this standardized list, so that button is gone.
  • Editable tag chips — double-click a chip in the world Tags editor or a dictionary entry's Keywords to fix it in place (Enter saves, Esc cancels, clearing it removes the chip) instead of deleting and retyping. Editing a world tag still shows the Danbooru autocomplete; chips keep their position, and drag-to-reorder is unchanged.
  • ComfyUI image provider — generate images through a local ComfyUI server alongside the existing A1111/Forge and cloud options. Ships a working SDXL txt2img workflow that's fully editable per preset: paste your own Save (API Format) graph and mark inject points with tokens (%prompt%, %negative%, %ckpt%, %width%, %height%, %steps%, %cfg%, %seed%, %sampler%). Live progress bar + preview frames stream over ComfyUI's WebSocket, matching the A1111 experience. Launch ComfyUI with --enable-cors-header so the browser can reach it (default port 8188).
  • World README — authors can add a markdown Readme (in the World Editor, below System Prompt Addition, using the same editor as the World Description) that greets the player in a popup when they enter the world. Dismiss it with the X, click-outside, or Esc. A per-world Show Readme toggle lives in the main-menu world popup and is mirrored by a Don't Show This Again checkbox in the popup itself — the two stay in sync (one setting, on by default).
  • Consent-based image optimization — before an oversized image is re-encoded (on import, on generate "Use image", or via the editor's Optimize Images), a prompt offers Optimize (convert to lossless WebP at the same resolution — no visible quality loss) or Downscale (shrink to fit), with a clear Keep original to do nothing. Already-WebP images skip the redundant Optimize option.
  • The world-browser Hidden popover now uses editable tag / author autocomplete boxes, matching the search filters.
  • Dictionaries are books — the World Editor's Dictionary tab now groups lorebook entries into named dictionaries ("books") you add, reorder, collapse, and toggle on/off as a whole, instead of one flat pile. Each book keeps its own Background and Foreground lists, and entries drag between zones or across books; book order sets injection order, and disabling a book mutes all its entries at once. New worlds start with a Default book. A single book exports to its own .json (Download <name> on a selected dictionary) and imports back as a new book (Import Dictionary) — handy for sharing lore between worlds; importing a full world or save file is rejected with a clear message.
  • Dictionary library + lorebook import — the main menu's top-left switcher gains a Dictionaries tab: a library of standalone dictionaries you Import and manage as cards (persisted locally), separate from any world. Import isn't limited to Formamorph files — it also reads and converts open lorebooks: SillyTavern World Info exports and Character Card V2/V3 character_book data (keywords, secondary keywords, content, enabled/constant, case-sensitivity, regex, placement, scan depth). Cards with no image (and worlds without a thumbnail) now show a neutral grey placeholder instead of a broken image. Click a dictionary card to open it in a full editor — the same Background/Foreground tree, entry editor, and drag-to-reorder as the World Editor — rename it, edit entries, Download it, and Save back to the library (with an unsaved-changes prompt). Dictionaries also gain a Description (author note, not sent to the AI), and entries gain Whole words matching (keyword boundaries, so "art" no longer fires on "cart") and richer secondary-keyword logic — require any or all secondaries, and an Exclude mode so an entry fires only when certain words are absent. In the World Editor, Add Dictionary pulls copies of one or more library dictionaries into the current world (multi-select), each as an independent copy.
  • Theme + theme color — Settings → Presentation has a Theme control (Light / Dark / System, as segmented tab buttons; System is the new default and follows your OS) and a Theme Color dropdown below it that recolors the whole app. Eight presets: Graphite (the default — a soft monochrome), Purple, Blue, Rose, Bubble Gum, Forest, Monochrome (crisp greyscale with a true-black dark mode), and High Contrast (an accessibility theme — maximal text contrast, everything outlined, yellow accents in dark). Each is a full hand-tuned palette for both light and dark, so switching restyles every surface — backgrounds, cards, borders, buttons, focus rings — not just a button tint, while keeping text legible. Status colors (error / success / warning) stay constant across all themes. On a fresh install, if your OS requests higher contrast and you're on System mode, it starts on High Contrast automatically — as the initial default only; whatever you pick afterward always sticks.
  • Location background controls — Settings → Presentation adds a Location Background toggle (on by default) that shows or hides the current location's image behind the game; turn it off for a clean, blank themed background. When it's on, a Background Fade slider (0–100%) fades the location image toward the background color for readability — slide it up to calm a busy scene toward the plain background. Pressing the hide-UI (eye) button drops the fade too, so you always see the untouched image underneath.
  • AI Language is now a combobox — the language setting (Settings → Presentation, and the in-game side panel — renamed AI Language) suggests common languages the moment you focus it (no typing needed), while still accepting any free text. A short note explains what it does: it sets the language the AI writes narration and choices in — and you can type your own value, or even a style like "formal English" or "pirate speak", instead of picking from the list.
  • Back button in the enter-world flow — every step of the start-a-world flow (Traits → Location → Characters → Dictionaries → Avatar) now has a Back button, always just to the left of the next/confirm button, that returns to the previous step. On the very first step it's shown but faded/disabled. On the Traits step it also pages back through trait sections before it reaches the flow's start.
  • Bring characters into a world when you start it — a new step in the enter-world flow (after location, before dictionaries) lists your library characters with their portraits; check the ones you want and they're placed into your starting location for that playthrough. Only appears when you have saved characters. The chosen characters are copied in with fresh ids and live entirely in the save — they're never written into the authored world.
  • Choose dictionaries when you start a world — a new step in the enter-world flow (after location, before avatar customization) lists the world's own dictionaries on top and your downloaded library below, each with a drag handle, an enable/disable checkbox, its description, and an enabled/total entry count. Reorder and toggle any of them — world-authored included — to set exactly which lore applies and in what order for this playthrough; enabling a library dictionary pulls in a fresh copy. Your choice is saved with the game, so reloading keeps it. The step is skipped when there's nothing to choose (a single-book world with an empty library).
  • Character cards — share a character as an image — a single character now exports to a shareable WebP whose picture is the character's portrait and whose text (name, descriptions, summary, type, image tags) rides along invisibly inside the image, the way other games do character cards. In the World Editor, Download <name> on a selected entity saves the card; drop that .webp back in via the new main-menu Entities tab and the character returns with its portrait and every field intact (the image itself becomes the portrait — no duplicate stored). The Entities tab is a local library of characters you New, Import, edit in a full editor, reorder, and delete — separate from any world; Add Character in the World Editor pulls copies of one or more of them into the world (multi-select), each an independent copy. A character with no picture still exports, using a generated placeholder. Importing a world, save, dictionary, or a plain non-card image shows a clear message.
  • Import SillyTavern characters — the Entities Import also reads SillyTavern / Character-Card PNGs (the ccv3/chara embedded-card format). It brings across the picture and the name plus description + personality + scenario (folded into the AI-facing description, with {{char}} → the character's name and {{user}} → "the player"); the chat-only fields (greeting, example dialogue, jailbreak prompts) are skipped as they have no place in a world character. If the card carries its own lorebook, you're asked whether to add it to your dictionary library too.
  • Sign in & publish from the desktop app — the desktop build no longer blocks logging into the community server or publishing a world; that guard is gone now that v2 is the standard.
  • Selectable app font — Settings → Presentation gains a Font picker that restyles the whole app's typeface.
  • Live theme preview — a Preview popup (Settings → Presentation) shows every theme color token with a label and color picker, laid out across the real widgets the app uses — checkboxes, tabs, draggable tags, a multiselect, a reorderable list, circle buttons, a sample card — so you can eyeball a palette on actual UI before committing. It's a viewer; nothing is saved.
  • Cards stand out — each theme now gives the card surface its own shade distinct from the page background, so world / entity / dictionary cards read as raised panels instead of blending in. Community & main-menu tags also recolor with the theme (they were stuck blue).
  • Animated stat changes — in-game stat bars now show a change instead of only printing a number: a gain grows a green band and a loss a red band spanning the previous ↔ current value, the ±delta text fades in and out, and the colors drain away at the start of the next turn.
  • "Move Automatically" — the auto-move setting (Settings → Generation) is renamed from Location Moves to Move Automatically, and now resolves the move up front so the narration is written already in the new place rather than describing a move that hasn't happened yet.
  • Narration reveal animation — the streamed-text reveal is a configurable animation (fade / scale / blur / slide, its pace tracking how fast the model generates), tuned in Settings → Presentation with a live demo.
• 🛠️ Developer tooling
  • Env-seeded image defaults — the whole Image Gen setup (provider, endpoint, dimensions, ADetailer, and multiple named presets via VITE_DEFAULT_IMAGE_PRESETS) can be seeded from .env.local.
  • Unified app icon — one source icon (public/icon.png) is now both the browser-tab favicon and the desktop app icon (electron-builder converts it per-platform), replacing the default Vite / Electron icons.
  • VRAM readout built into the desktop app — the Hardware tab's live GPU readout no longer needs a separately-run npm run vram-helper in the packaged desktop build: the Electron main process runs nvidia-smi itself and feeds the renderer over an IPC bridge (window.formamorphDesktop.vramStats). The nvidia-smi logic was factored into a shared electron/vramCollect.cjs used by both the desktop main process and the standalone dev helper. useVramStats prefers IPC when in the desktop build, else polls the helper URL. The Hardware tab is now hidden in the production web build (where no VRAM source exists) and shown only in npm run dev or the desktop app; on desktop it drops the "run the helper" instructions for a built-in note.
  • The main-menu GitHub button and the README / wiki now link to this fork's repo and the live web build.
  • API doc comments + tooling — the high-value TypeScript surface (domain types, contexts, services, and the core lib modules) now carries prose TSDoc comments, so VS Code shows a plain-English summary on hover next to the types. The lint gate validates comment syntax (eslint-plugin-tsdoc), and npm run docs generates a browsable TypeDoc API reference into the gitignored docs-api/.
  • World shape: dictionary → dictionaries — the flat dictionary: DictionaryEntry[] becomes an ordered dictionaries: Dictionary[] (books of entries). An idempotent load-time migration folds any legacy world (including the bundled defaults) into one Default book, positions preserved — no world is re-persisted until the user saves. Injection stays entry-based via a flattenEnabledBookEntries bridge, so a single-book world's prompt output is unchanged. New standalone dictionary file format carries a formamorphKind: 'dictionary' discriminator; world and save exports now also carry an optional formamorphKind: 'world' / 'save' label (additive — old files without it still import). Foreign lorebook parsing (lorebookImport.ts) is grounded in the MIT Character Card V3 spec (credited in THIRD-PARTY-NOTICES.md). The dictionary editing widgets were decoupled from the world store into a scoped DictionaryStore context (useDictionaryStoreState), so the World Editor binds them to the current world's books while the library editor binds them to an isolated single book — the same widgets, two hosts, no shared-state leakage. Dictionary gains an optional description; DictionaryEntry gains optional matchWholeWords, secondaryAll, and secondaryExclude (all additive — absent = prior behavior). The importer now maps ST matchWholeWords, selectiveLogic (AND-ANY/ALL, NOT-ANY/ALL), and lorebook description.
  • Save shape: optional per-playthrough dictionaries — the save envelope (SaveObject) gains an optional dictionaries: Dictionary[] written by the new world-entry dictionary step; older saves lack it and fall back to the world's current books (never clobbered). The per-run set is owned by GameplayContext (runtimeDictionaries + the flattened runtimeDictionary fed to injection); saveGame/loadGame stamp and restore it internally, so GameDataContext holds only the authored books. Pure selection helpers live in lib/dictionarySelection.ts (shouldShowDictionaryStep, buildInitialSelection, finalizeSelection). Additive — old saves import unchanged.
  • New file format: character cards (.webp) — a single entity slices out to a shareable WebP with its text fields embedded in the image, mirroring the dictionary slice. lib/entityCard.ts is a pure RIFF/WebP metadata codec (embedEntityCard/readEntityCard): it promotes a simple VP8/VP8L file to extended VP8X and writes the JSON into an XMP chunk (idempotent — re-embedding replaces, never appends), modeled on the existing PNG-chunk reader in sdMetadata.ts. lib/entityFile.ts adds the formamorphKind: 'entity' discriminator, buildEntityCardData (drops image/model/sound), parseEntityCardData (fresh id, rejects world/save/dictionary payloads), and the exportEntityCard/importEntityCard orchestrators — export omits the portrait from the JSON and import re-sources it from the card's own pixels, so the image is never stored twice. A local library mirrors the dictionary one: EntityStorageService (IndexedDB entitiesDB), a main-menu Entities grid (reusing SortableWorldCard), EntityEditorModal, and AddEntityModal. EntityManager's fields were extracted into a shared EntityFields body (locations picker optional) so the World Editor and the library editor reuse it. New EntityMetadata type. This is a new shareable artifact type; it does not change the world or save .json shape — no version bump.
  • Entry-step character placement (runtime-only) — the new enter-world character step is gated by shouldShowCharacterStep (lib/characterSelection.ts) and picked in CharacterSelectionModal. The chosen library characters thread MainMenu → App → GameViewer as an initialCharacters prop (mirroring initialDictionaries), and the init effect seeds them into GameplayContext.discoveredEntities anchored to the resolved starting location — reusing the existing runtime-character path (allEntities + mergeDiscoveredIntoLocation). So they show as present, persist in the save, and never touch GameData (the authored-world-immutable invariant). Fresh ids on selection; loadGame overrides on load.
  • SillyTavern character PNG import — lib/tavernCard.ts reads a Character-Card PNG (base64 JSON in the ccv3/chara text chunk, V1 flat / V2-V3 data envelope), reusing the now-exported readPngTextChunks from sdMetadata.ts. It maps only name + description/personality/scenario → aiDescription (macro substitution {{char}}/{{user}}), drops the chat-runtime fields, and hands any character_book to the existing convertLorebook. entityFile.importCharacterFile(file) is the unified import entry — WebP card or ST PNG — returning { entity, book }; the main menu offers the book via a confirm dialog. The PNG's pixels become the portrait (re-encoded to WebP).
  • Authored world is immutable during play — the running session no longer writes runtime state back into the authored world (GameDataContext). The stat-change handler updates only playerStats (dropping the old updateStat write-back), and the per-run dictionary set lives in GameplayContext, threaded in from world entry as a GameViewer prop (mirroring initialTraits/initialLocationId). The mid-game Edit World tool edits the authored world directly; it persists only on Save World, and no longer opens pre-marked dirty. The now-unused flattened dictionary derivation was removed from GameDataContext.
• ⚙️ Backend / invisible
  • Design-token color pass — the app's colors were migrated off hardcoded Tailwind palette classes (grays, plus inline reds / greens / ambers / blues for status) and stray hex onto CSS design tokens in index.css, so every surface now flips correctly between light/dark and swaps wholesale with the selected theme color with no per-component overrides. Preset themes ride on this: a data-theme attribute on <html> swaps a full token set, so a theme is authored purely as .light[data-theme="…"] / .dark[data-theme="…"] blocks in index.css — no per-component work. Eight ship (Blue, Purple, Rose, Bubble Gum, Forest, Graphite, Monochrome, High Contrast), each built by one recipe: pick a hue, preserve each token's lightness (so contrast holds), scale saturation by role, and leave the semantic status/chart tokens constant. The bare base and the first-run default are decoupled — blue lives in :root and applies with no attribute, while graphite is what a fresh install starts on. Monochrome and High Contrast communicate depth by an elevation-by-lightness surface ramp (true-black canvas → progressively lighter panels) rather than shadows, which don't read on black; High Contrast targets WCAG AAA (near-maximal text contrast, borders on every element, a yellow accent in dark / monochrome in light) and auto-selects on first run when the OS sets prefers-contrast: more (System mode only, and default-only — it never overrides a chosen theme). To make that outline-heavy theme complete, the button variants now reserve a token-colored border (border border-transparent in the base, border-border on secondary/ghost) — invisible-to-faint in the color themes, maximal in High Contrast, with no layout shift. This whole system replaces the earlier single-color accent picker (its lib/color.ts hex→HSL helper is removed). Added semantic --success / --warning / --info tokens (styled to match the existing --destructive), an --overlay scrim token for image and modal backdrops, and a fill-vs-ink split for destructive red: --destructive is tuned bright for text/icons/indicator bars (readable as its own color on a dark surface) while --destructive-fill stays deep for solid button/badge fills (where white text sits on top) — one token per role so red reads right in both. react-toastify's per-type accent variables now derive from these tokens too. Duplicated widgets were factored into a shared WorldCardShell (main-menu card frame) and Dropzone (dashed upload frame) so a shared color changes in one place. Decorative gradient buttons, scrim contrast text, and runtime/data-driven colors (entity chips, VRM appearance defaults, the categorical highlight palette) are intentionally left literal.

🐛 Fixed

• 👤 User-facing
  • New World / Entity / Dictionary no longer leave a blank behind — Clicking New used to immediately save an empty entry, so backing out of the editor without saving left a stray "New World"/"New Character"/"New Dictionary" in your library. Now New opens the editor on an in-memory draft and nothing is stored until you Save — cancel and it's gone.
  • Gameplay no longer edits your world — Playing a world used to quietly drift its authored stat values (and, briefly, its dictionary order/toggles) into the saved world — so opening Edit World mid-run showed changed values and a "dirty" state you hadn't touched, and saving there baked playthrough state into the world. Now the world changes only when you edit it in the World Editor and Save; per-run state stays with the save file.
  • Re-generate & rollback work on imported v1.2 saves — Old (1.2) saves stored their per-turn history one slot short, so after loading one, rolling back or re-generating landed on the wrong turn. Loading a 1.2 save now realigns that history. (The very first turn of a 1.2 save still can't be rolled back — its snapshot was never stored — but every later turn works.)
  • The world-browser autocomplete dropdowns no longer close when you click their scrollbar, and the Hidden popover's dropdown now scrolls with the mouse wheel.
  • Image Gen polish: the booru tag prompt no longer emits PascalCase / underscored tags the model can't use; the Settings → System Prompts tab is no longer pushed out of place by the Image Gen tab; and generated / imported images are no longer silently optimized without asking first.
  • Toasts follow the theme — pop-up notifications were hardcoded to the dark theme, so they stayed dark-on-light in the new Light / System modes; they now track the resolved light/dark theme, and their success / error / warning accents come from the app's color tokens.
  • Streaming narration reveal fixes — the character-by-character reveal no longer re-animates every paragraph at the end of a response, no longer stalls at the start, and its pacing now tracks the true generation rate (bugs that surfaced with reasoning models and the local engine). A stray "0" could also flash where a stat change of exactly zero was rendered — zero-changes now show nothing at all.

---

✅ 2.0.0 — Released — full TypeScript rebuild + feature parity (click to expand)

Everything below is relative to the point this fork diverged from upstream.

Major Changes

➕ Added

• 👤 User-facing
  • Standalone Windows app — run Formamorph as a desktop .exe (Electron) with no browser needed. It bundles its own engine, so WebGPU TTS, 3D rendering, and saved-world storage all work the same as in-browser.
  • Custom 3D avatars — bring your own .vrm, or set a per-world custom player model.
  • In-app media player — a fully themed audio widget for TTS narration, with auto-generated TTS when the model is loaded and a one-click unload of the TTS model to free VRAM.
  • Redesigned world browser ("Discover") — card-grid layout, tag & author chip search/filtering, and world-preview image zoom.
  • AI output controls — automatic paragraph limits and length-based truncation, an optional "thinking / planning" step before the reply, and a smoothed character-by-character reveal of streamed text.
  • Re-generate & rollback — page back through the turn history to re-generate the latest AI response, or roll back to an earlier turn (discarding the turns after it). The per-turn AI-context viewer flags the regenerated and rolled-back turns.
  • Markdown narration — the AI can format story text with bold/italic, bullet & numbered lists, tables (e.g. inventory), headings, blockquotes, and code; it renders live as the text streams in.
  • Token-based Context Window, auto-detected from your endpoint (LM Studio, OpenRouter, …) with a Detect button and manual override — conversation history now fills the model's real context instead of a fixed character cap, and an over-limit warning flags a value set above the detected maximum.
  • Portrait / mobile layout — a single-panel responsive mode alongside the three-panel desktop view.
  • Lore Dictionary — a keyword-triggered world-info editor; matching keywords inject lore into the AI prompt.
  • Full per-turn AI context viewer — see exactly what's sent to the AI on each turn, plus the raw response before sanitation — useful both for debugging and for authoring/tuning worlds. Each request is its own collapsible section with the prompt and raw output nested inside, and Collapse/Expand all folds every level at once.
  • Stat-driven body sliders — in the world editor, bind any stat to one or more of the model's body morph sliders; the stat's value (min→max) drives the morph live in-game. Legacy weight/breasts/stomach stats are auto-bound on import, so existing worlds keep working.
  • Prompt variables are now chips — the AI prompt editors (Settings → System Prompts) no longer use raw <…> placeholder text. A toolbar inserts each variable as a color-coded chip you can drag to reposition, remove with ×, or use more than once. Clicking a chip opens its options: the Location chip switches between Full / Summary / List (the list of all location names, usable in any prompt — no separate chip needed), and Entities switches between Full / Summary. During a game, an Edit / Preview toggle shows each chip swapped for its live value — color-matched to its chip — so you can see the real assembled prompt.
  • Entities are their own prompt section — the characters and things at a location are no longer dumped inside the location block (which made the AI treat the whole cast as all-present). They're now a separate Entities chip — a roster of who or what could appear — so the model is less likely to crowd every NPC into the scene.
• 🛠️ Developer tooling
  • Automated test suite built from scratch (Vitest + Testing Library) covering the new libraries, services, and components, plus a coverage script (npm run coverage).
  • GitHub Actions CI — typecheck, lint, and tests run on every push and pull request.
  • Optional VRAM monitor — a local helper (npm run vram-helper) and in-app readout that warns before loading TTS would exhaust GPU memory.
  • Desktop packaging — a thin Electron shell (electron/) plus electron-builder config; npm run desktop:build produces a portable Windows exe from the same web build.
  • Project scaffolding: .env.example, .nvmrc, and a rewritten README.
  • This wiki, published automatically from docs/ by a GitHub Action.
• ⚙️ Backend / invisible
  • Full JavaScript → TypeScript conversion of the entire codebase (10 phases), finishing on strict mode with shared domain types under src/types.
  • World & save versioning — an APP_VERSION derived from package.json, idempotent import migration (migrateWorld) that upgrades legacy worlds at every import boundary, presence-based save-envelope detection, and version stamps on saves, exports, and the bundled worlds. (See the World Format versioning notes.)
  • Heavy save conversion and serialization moved to web workers so the UI never freezes on large files.
  • Reusable utilities extracted: world import/catalog, output length, AI-response parsing, tag/dictionary/highlight helpers, and a thumbnail cache.

➖ Removed

• 👤 User-facing
  • The fullscreen menu popup, replaced by the redesigned world browser.
  • The previous bundled example worlds (slime, sugarscape, veilwood), swapped for the current set.
• 🛠️ Developer tooling
  • In-repo planning notes and server stubs under src/docs/ (publish-feature plan, server README, tags-implementation notes, server-worlds stub).
• ⚙️ Backend / invisible
  • All legacy .jsx / .js sources, superseded by .tsx / .ts equivalents (views, contexts, workers, prompts, db & utils, UI primitives).
  • jsconfig.json (replaced by tsconfig.json) and a stray Idle.fbx animation file.

🐛 Fixed

• 👤 User-facing
  • Custom VRM models exported from v1.2 were silently stripped on import — now migrated and preserved.
  • Body-morph sliders now resize clothing meshes instead of clipping through them.
  • VRM outline color rendering issue.
  • AI response parsing errors that could break choices and stat updates.
  • The Settings panel no longer jumps vertically when its contents change.
  • Unsaved world edits are detected on exit, with a confirmation prompt to prevent data loss.
• ⚙️ Backend / invisible
  • Server-Sent Events streaming now handles chunk boundaries correctly — no dropped or garbled tokens mid-stream.
  • Removed side effects from the setPlayerStats state updater.
  • The recent-stat-change highlight timer is cleared properly, and streaming guards against a missing response.body.

Minor Changes

➕ Added

• 👤 User-facing
  • Markdown formatting — toggle (Settings → Presentation, default on) — when on, the narration prompt asks the AI to format with bold/italics, lists, and tables (e.g. inventory) using a floor-based rule (one bold + at least one italic per turn) that small models follow reliably; off keeps plain prose. (Reset Prompts to pick it up if you've customized the system prompt.)
  • Hide stat numbers from the narrator (Settings → Generation, default on) — the narration, planning, and choices requests receive stat descriptors (e.g. "severely injured") instead of raw values, so the model writes to how a stat feels rather than fixating on the number. Stat-updates still get the numbers; falls back to the number when a stat has no descriptor.
  • Slash commands — in the action box (input starting with /) that bypass the AI; the first, /markdown test, types a rich sample through the real narration renderer to preview markdown formatting.
  • Use Custom Endpoint — toggle in Settings → Endpoint — off uses the built-in default endpoint (fields read-only); on lets you enter and edit your own. Custom values are preserved when toggling off and back on.
  • Hide-UI toggle — an eye button in the bottom-left of the game view hides all panels to reveal the background image; it fades out over the background until hovered.
  • Drag-to-reorder for worlds in the main menu.
  • Additional avatar color options.
  • Unified, consistently styled scroll areas, checkboxes, radios, and chips across the app.
  • Tag truncation and a centered download control in the world browser.
  • LLM request status surfaced next to the status bar.
  • Update-aware world browser — downloaded worlds show their status (Downloaded / Update available / out of date) with one-click re-download to pull the latest version.
  • World provenance on cards — local world cards show how each world arrived (Created / Downloaded / Imported) with timestamps.
  • Main-menu layout toggle — switch the world grid between Grid and Detailed layouts.
  • Markdown in world descriptions — world descriptions render markdown, matching the in-game narration.
  • In-game entity viewer — the avatar panel gained Player / Entities tabs; the Entities view shows the first detected entity's image, clicking an entity in the list swaps to it, and clicking the image opens a full zoom view (works even for worlds without a player model). The tab fills from the characters that actually took part in the turn (once the narration finishes, so there's no mid-stream flicker); a Staged-mode character the planner invented shows as a plain, non-clickable entry.
  • Entity popup — viewing an entity now supports the same pan/zoom image view as world thumbnails, sizes the image to most of the popup with its description below, and shows a muted "No description provided." when there's no text.
  • AI-context "current context only" filter — the per-turn context viewer can hide re-generated, rolled-back, and aborted turns so you see only what the AI currently sees (on by default).
  • System Prompts editor — Settings → System Prompts has a tab per prompt type (Narration, Thinking, Choices, Stat Updates, Location Change, Summary, plus the Staged director/character/storyboard), and Reset affects only the selected prompt. Each helper request (Choices, Stat Updates, Location Change, Summary) has a System | User toggle, so you can edit the user message it sends — the framing and the "just output X, no story" cue — not just the system prompt, with Player Action and Narration chips to drop the turn's values into your template. A checkbox group in Settings → Generation turns the optional prompts (Choices, Stat Updates, Location Change) on or off — replacing the old "type DISABLED into the prompt" trick — and a disabled prompt hides its editor tab (worlds that used the DISABLED trick migrate to off automatically). A Verbatim turns field in the editor footer sets how many recent turns each prompt sends in full before older ones collapse into the summary recap.
  • Organized Settings — gameplay settings are grouped into Presentation (language, music, output length, auto-scroll, markdown, narration audio) and Generation (hide stat numbers, thinking, memory summaries, silent requests), so related settings sit together.
  • Staged (director-led) thinking — a new Thinking mode beside Off / Planning / Inline that plans a turn in stages for higher-quality, more consistent scenes: a director stages the scene (a brief description of where you are and what's visible) and casts who's present with each one's placement — where they stand and what they're physically doing right now, always leading with your own position as "Player Character". The director casts only living, acting beings (people, creatures, threats — places and objects stay in the scene description), and gives any character it invents a concrete, reusable name so they stay the same character turn to turn. Each chosen character (up to three) plans its own motivation in a separate pass, speaking in the first person ("I want… / I intend to…"); and a storyboarder combines those into the plan (reacting to what you did, never scripting your next move). When no other characters are present, the motivation and storyboard passes are skipped — the plan is just the scene and your placement — so a solo moment stays fast and doesn't invent filler. The director's scene and cast placements are handed to the narrator alongside the storyboard beats, so the story is grounded in concrete staging and physical interactions stay consistent. The trade-off is several extra requests per turn, so it's best with a fast endpoint. Each stage is visible in the AI-context viewer and never leaks into the story.
  • Full-length, progressive TTS narration — narration is split into sentence chunks so audio is no longer cut off at ~26 s (Kokoro's per-call token cap). Playback is progressive: speech starts after the first sentence and plays gaplessly (Web Audio) as the rest generate, with a determinate progress bar (sentence X of N); the seek bar is driven by the same engine, so the clip is scrubbable/replayable with no hand-off.
  • Stream Narration Audio (in the Text-to-Speech popup, default off) — when on, text-to-speech begins synthesizing each sentence the moment it finishes streaming from the model, instead of waiting for the whole story; much lower audio latency. Off by default since TTS then runs alongside the model and can compete for the GPU on a single-machine setup.
  • Narration speed — a persisted Speed slider (0.5×–2.0×) in the Text-to-Speech popup controls how fast the voice reads. Applies to newly generated audio, so change it and hit the regenerate (↻) button to re-speak the current text at the new pace.
  • Karaoke sentence highlighting — while narration audio plays, the sentence currently being spoken is highlighted in place with a soft accent tint, and the highlight follows the playhead when you scrub the seek bar — so you always know where you are in the text. Works across bold/italic/linked words within a sentence and while narration is still streaming in. On by default (toggle "Highlight while speaking" in the Text-to-Speech popup); silently does nothing on browsers without highlight support.
  • Frozen audio bar — once TTS audio exists, the play/scrub seek bar is pinned to the top of the story panel (instead of scrolling away with the text) and carries the audio-specific buttons (play, regenerate) on its row; the export and edit buttons stay in the top-right corner.
  • Export the story — a download button beside the narration's edit pencil saves the whole playthrough's narration to a file, one turn per block, with a choice of plain text (.txt) or Markdown (.md).
  • Audio settings live with the audio — the TTS controls (voice, speed, Stream Narration Audio, Highlight while speaking) all sit together in the Text-to-Speech popup rather than the main Settings menu, since they only matter once a TTS model is loaded — which only happens from that popup, in-game.
  • Non-streaming narration generates before the rest of the turn — with a TTS model loaded and Stream Narration Audio off, the narration's audio is now generated right after the story text and the turn's remaining requests (choices, stat updates, location change) wait for it to finish, rather than racing alongside it — avoiding GPU contention when the model and TTS share one machine.
  • Memory Summaries (Settings → Generation, default off) — long stories stay coherent without bloating each request. Older turns are summarized into short fact lines as they age out of recent history and fed back to the model: recent turns stay word-for-word, older turns collapse into a compact "story so far" recap, and any past turn your action references is pulled back to full detail. Recall works two ways: by keyword, and by participant — when your action mentions a character, an older turn that character actually took part in is resurfaced even if its summary shares no words with what you typed (so returning to "talk to Mira" after many turns finds the right scene). The memory meter breaks out how much of the window the recap and rehydrated turns use. Runs an extra request per turn, so it can compete for the GPU on a single-machine setup.
  • Link entities to locations from either side — in the World Editor a location's entities are now chosen from a searchable multiselect dropdown (replacing the long checkbox list), and each entity gained a matching Locations dropdown. The two stay in sync, so the relationship can be edited from whichever side you're on.
  • Steadier World Editor tabs — the add/search row now sits below the editor tabs instead of above them, so the tab strip no longer shifts when you switch to or from the Overview tab.
  • Audience-labeled description fields — an entity's and location's descriptions are now split by audience: Player-Facing Description (shown in-game) and AI-Facing Description (full text sent to the model), plus a new AI-Facing Summary — a short version for use where the full description is too long, which a ✨ button generates from the AI-Facing Description using your connected LLM (with undo). Existing v1.2 worlds are upgraded automatically (their old inGameDescription / detailedDescription fields are renamed on import).
  • Planning step uses AI-Facing Summaries — the optional pre-reply planning request now feeds the model each location's and entity's short AI-Facing Summary (falling back to the full description where none is authored), keeping the planning pass lightweight. Narration still gets the full descriptions. The plan also lists each present character with their placement — where they are and what they're physically doing right now — giving the narration concrete staging to work from.
  • Smarter next-action choices — the choices request sees the player's most recent action (not just the resulting narration), so suggestions track what you were actually trying to do, and it uses the short AI-Facing Summaries instead of full descriptions. It's scene-aware: it only sees the characters actually present (named in the recent narration, within a short rolling window), not the whole location roster, so it won't suggest actions for people who haven't appeared yet or already left. And the story no longer duplicates the menu — the narrator prompt is a positive contract that writes only prose while the separate Choices step presents the options, so smaller models stop tacking a "What do you do next?" list onto the end of the narration.
  • AI-context "Hydrations" view — the AI Context viewer (the per-turn debug popup) gained a Dictionary / Hydrations toggle. "Hydrations" shows the exact words and characters used to decide what older context gets recalled for that turn, as color-coded, clickable chips that highlight their matches — and only within the game-text request, so the choices/stats requests stay clean.
  • Duplicate button in the World Editor — every list item (stats, entities, locations, traits, groups, dictionary entries) gains a duplicate button beside delete that makes a deep copy placed right below the original. Duplicating a trait keeps it in the same group; duplicating a group copies the whole nested subtree (subgroups and traits) with fresh ids in the exact same nesting. The copy's name gets a " (Copy)" suffix.
  • Markdown toolbar for the world description — the Edit tab gained a formatting toolbar (bold, italic, headings, lists, link, quote, inline code) plus undo/redo (buttons and Ctrl+Z / Ctrl+Y); the Preview still renders through the same engine as in-game narration.
  • Trait groups (folders) — the World Editor's Traits tab is now a foldering tree: the + opens a popout to Add Group or Add Trait, and traits/groups drag to reorder and nest — drag a row right to tuck it under the group above, left to pull it back out, with the row indenting live as you drag. New worlds start with World and Player groups. Traits and groups gain Player-Facing and AI-Facing descriptions, and traits gain an Enabled by Default flag. In play, the trait-selection popup is now tabbed by group (an implicit General tab holds ungrouped traits, nested groups add a tab row); default traits start checked, and the buttons are Next (walk the groups), Skip (start with the current selection), and Abort (cancel loading the world). A group's AI description is sent to the model as a header above its selected traits.
• ⚙️ Backend / invisible
  • Shared hooks and helpers: a createWorkerClient worker factory, a single IndexedDB open/promisify helper (idb), usePersistentState, useIsMobile, and a cached-thumbnail hook.
  • The Community Creations browser was split out of MainMenu into its own CommunityCreationsBrowser view, with shared world-card/detail presentation helpers (WorldDetails).
  • Trait group data model — the world format gains a traitGroups array ({ id, name, playerDescription?, aiDescription?, parentId, order }); traits move from a single description to playerDescription/aiDescription and gain groupId, isDefault, and order. The tree, reordering, and AI trait-context builder live in pure, unit-tested helpers (lib/traitTree.ts); legacy v1.2 worlds rename their trait description → playerDescription on import.
  • Character diaries — each character present in a turn quietly records a short first-person diary entry about it, from their own point of view, generated as turns age out (opt-in via Settings → Generation → Character Diaries; prompt editable under System Prompts → Diary; covers ad-hoc walk-ons too). With "Show Silent Requests" on, each entry is inspectable per turn in the AI-context viewer. In staged planning, a character's own recent diary is now fed back into its motivation pass as private memory, so it acts with continuity and only knows what it recorded — the start of real information asymmetry between characters. Entries are stored per-turn (AITurnResult.diaries), an additive save-shape change that rolls back with the turn; old saves read as absent.

➖ Removed

• ⚙️ Backend / invisible
  • Dead code and noisy logging, including a leftover bufferToSentence helper and an auth-token console log.

🐛 Fixed

• 👤 User-facing
  • Mislabeled UI text and icons corrected.
  • The memory meter is now an accurate token gauge of the model's context window — prompt + (actually-sent) history + reserved output as a % of the window — fixing the old bar that mixed characters and tokens and counted the full untrimmed log.
• ⚙️ Backend / invisible
  • Entity IDs now use crypto.randomUUID() instead of timestamp-based IDs, avoiding collisions.
  • Cleaner AI prompts — blank or unset author fields (an empty entity type, a missing description, etc.) are no longer padded into the location/entity/trait data sent to the model, and the editor-only starting-location flag is dropped from it. Empty fields previously leaked as blank lines or the literal text undefined, which could confuse smaller models.
  • Stat code runs in a real sandbox — world-authored stat formulas (which ride inside downloaded worlds) now execute in an isolated QuickJS WebAssembly VM instead of new Function, so they can no longer reach the page (fetch, localStorage, the DOM) — closing an untrusted-code hole. A runtime interrupt enforces the 1-second timeout, so a while(true) loop is actually killed instead of hanging the tab (the old after-the-fact check never fired), with memory and stack caps on top. Only whitelisted stat data crosses into the VM; the numeric result is read back and clamped exactly as before. The engine is lazily loaded on first use, so it doesn't affect page load.
  • Lint cleanups across the converted codebase.