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.2.2 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.2.3 — the in-progress version, not yet released.

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. Targeting 2.2.3 (package.json is already bumped); finalized into a ✅ Released block when tagged.

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 a phone 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
  • 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 a phone 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 phones (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 phones and shows just the refresh icon, saving room in the tight mobile toolbar. Its keyboard/screen-reader label is preserved.
  • The game view uses the full screen on mobile. The play screen no longer has an outer margin on phones, so the panels run edge-to-edge and reclaim that space. Desktop is unchanged.
  • Settings tabs fit narrow screens. The six-tab row along the top of Settings was too wide for a phone; below a small breakpoint it now collapses into a dropdown of the current tab, and stays a full tab row on wider screens.
  • 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 phones. On a narrow portrait phone, 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 a phone or tablet, 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.
• 🛠️ Developer tooling
  • 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.