HellionChat/docs/LEARNING-JOURNEY.md

# Development History and Learning Process

## Background

I am self-taught. Hellion Chat is my first FFXIV plugin and my first larger C# project. My professional background is
web development (Next.js, React, TypeScript, Prisma, MySQL) — browser world with a JavaScript toolchain. I knew C# only
superficially before this project, ImGui not at all, and Dalamud only as an end user through other plugins.

When I get stuck somewhere, I use AI tools like Claude Code as a pair assistant. What that looks like exactly and which
classification I use is documented transparently in [`AI_DISCLOSURE.md`](AI_DISCLOSURE.md).

---

## Why a chat plugin at all?

Hellion Chat is not meant to replace Chat 2. Chat 2 delivers a complete chat experience with full history, filters,
search and replay. For most users that is exactly the right thing.

### Two million messages in two years

My desire for a tighter default was honestly personal at first. After two years with Chat 2 my database had grown to
over two million messages, the majority of them /say, /shout and /yell from complete strangers in Limsa. That is exactly
what makes Chat 2's full history useful, and most users are happy to keep it. My own preference wanted a smaller
default. So I built this fork.

### Greeter in several clubs

There was a second use case: I am active as a greeter in several FFXIV clubs. The vanilla chat interface is not enough
for greeter work. Parallel /tell conversations write into a single tab at the same time, and I constantly lose track of
who wrote what. Auto-Tell-Tabs (one of the early Hellion Chat features) came directly from this workflow: one tab per
conversation partner, automatically spawned, with a manual greeted status. The privacy hygiene benefit was a nice bonus,
not the trigger.

### Hellion Online Media

The privacy defaults also reflect a position from my main work. Hellion Online Media is my sole proprietorship, and data
protection toward clients is not a marketing slogan there but operationally relevant. This fork is the plugin form of
the same stance.

---

## Why not contribute to the original?

Three reasons, in descending order of importance.

### Defaults are not negotiable, including mine

Privacy-first as a default is a minority position. Chat 2 rightly serves the broad majority with full history as the
default. Changing those defaults upstream would have been wrong. I would have flipped the standard for a large user base
that wanted it as it was. A clean separation through a dedicated plugin slot was the more respectful path.

### The web interface had to go

It is a central Chat 2 feature for remote access from a second device. A PR removing it has no chance in a
well-maintained upstream project, and that is correct. But exactly that web interface conflicts with the privacy-first
premise of this fork: a chat plugin that starts a local HTTP server is too large an attack surface for my threat model.
So out it went.

### Velocity

A solo-maintainer project with a small tester pool can iterate faster than an established plugin with a large user base.
That is not a criticism of upstream but a different optimization. I do not need roadmap alignment, reviewer
availability, or to spread audit consequences like the web interface removal across multiple releases.

EUPL-1.2 explicitly allows all of this with clear attribution. The code is open under the same license as Chat 2. Infi,
Anna, or anyone else can look in, take ideas, ask questions, or simply ignore the fork. All three are fine with me.

---

## How I release this fast

Anyone looking at the repo sees a lot of releases and a high commit count in a short time. Both tend to read as red
flags from the outside: AI slop, salami tactics, code spam. In Hellion Chat both are deliberate decisions, and I would
rather explain them once than justify them later.

### Groundwork, long before the fork existed

Before I typed the first line into `HellionChat/`, I spent weeks as a reader. Using Chat 2 in-game and playing around
with it. Going through issues in the upstream tracker, especially the closed ones, because that is where you see how
Infi and Anna narrow down bugs. Reading commits, including older ones, to understand _why_ an architecture decision was
made, not just _that_ it was made. If I know today where things live in the codebase, it is not because I navigate
codebases particularly fast but because I read the code beforehand.

That sounds obvious. It is not. The usual order for solo forks is fork first, understand later. I did it the other way
around.

One thing I noticed reading the codebase closely: some patterns felt familiar in ways I had not expected, structural
choices and comment styles that show up across a lot of modern plugin and tooling code regardless of how it was written.
Nothing worth reading into. Coding workflows have changed a lot in the last few years across the board, and the traces
of that show up everywhere. It did make me less self-conscious about my own workflow.

### Infi and Anna's codebase

Hellion Chat builds on a foundation that is already flat. Chat 2 is cleanly structured, naming conventions are
consistent, and the separation between layers (storage, UI, game hooks, IPC) is clearly drawn. That is not a given in
open-source plugin land, and it is the main reason Hellion-specific features often slot in "almost natively". I do not
have to untangle spaghetti before I can put something of my own next to it.

Side note: even during the first codebase walkthrough with Claude, the comment came up several times that the
architecture is unusually tidy and has several extension points prepared. That carries weight because it comes from
outside, but the actual credit goes to Infi and Anna, not Claude.

### Atomic work, small commits

One commit, one logical change. If I fix a bug, rename a variable and add a comment at the same time, that is three
commits, not one. Sounds like micro-management, it is not. If a bug surfaces in six months and I need `git bisect`, I
find the broken change in two minutes instead of two hours. With a 4000-line mega-commit I get to guess which of the
hundred changes is the broken one.

I kept this style deliberately also because Infi works the same way upstream. Sometimes a six-line commit, sometimes
just a typo fix. That is not a weakness, it is a decision for readable Git history. Keeping the style in the fork is a
respect move: anyone comparing both repos should have the same reading rhythm.

Personal bonus: small commits force me to think through and name each step individually. If I cannot explain what a
commit does in two sentences, the change is probably not clear enough yet. At beginner level that is a built-in sanity
check I would not have with a big-bang commit.

### AI as an accelerator, honestly

Yes, AI helps with velocity, and not a little. Without CodeRabbit I would not have found critical bugs like
`Equals/GetHashCode` anti-patterns, hook subscription leaks and TOCTOU races. I am simply too inexperienced for that
class of findings, and I write that exactly as it is.

What I do not do: blindly take code because a tool marked it as a fix. On several CodeRabbit findings, the original
commits from Infi or Anna even included a Stack Overflow link explaining why a particular spot looks the way it does. I
read those before touching anything. Understand first, then change, then commit. That is the difference between "AI
gives me code, I push" and "AI shows me where it breaks, I decide".

Classification and concrete examples of AI usage are in [`AI_DISCLOSURE.md`](AI_DISCLOSURE.md). This section was only
about the velocity aspect: research plus a clean codebase plus atomic commits plus AI-assisted review sparring are the
four factors together. No single one explains the pace on its own.

---

## From the web stack to C# / Dalamud

### Type system? Less of a shock than expected

C# after TypeScript was more comfortable than expected. Properties instead of getters/setters are clean, nullable
reference types feel like `strict: true` in TypeScript. What was unfamiliar was having to think explicitly about value
types versus reference types (`struct` vs. `class` with real behavioural consequences), and generics with constraints
are syntactically different enough that I stumble on them while reading. `async`/`await` is semantically similar, but
threading models are more explicit in C#: `Task.Run`, `ConfigureAwait`, synchronization contexts. That cost me several
bugs before I understood when the main thread (in plugin land: the framework tick) is actually critical.

### Build toolchain: similar, but different

`dotnet` CLI, csproj XML, NuGet are functionally not far from npm and tsconfig. But the XML format of csproj is a
different language than JSON configs. The lock file (`packages.lock.json`) had to be actively enabled
(`RestorePackagesWithLockFile=true`); that is not the default. In the web stack, lock-file-first is standard, in the
.NET stack apparently not. That was a real surprise.

### ImGui is a different world

Immediate-mode rendering has nothing in common with React component trees. There is no virtual DOM, no reconciliation,
no "component state". Every frame the code redraws the UI from scratch, and state lives either in local variables I
manage myself or in ImGui's own ID stack logic.

What is two lines of `useState` in React is a member field plus manual ID stamps on widgets in ImGui, otherwise two
selectables in the same loop collide because they fall back to the same ID. The ID stack collision in `SearchSelector`
(fixed in v1.0.0) was exactly that symptom: all selectables fell back to the same ambiguous ID until I mixed the row
index into the PushID. Classic "why is the wrong entry getting clicked" bug that you only find once you understand how
ImGui handles IDs internally.

### Dalamud specifics

Plugin lifecycle, IPC subscriber pattern, hook system for game functions, game object threading. Much of that was only
understandable through reading the upstream codebase and through [dalamud.dev](https://dalamud.dev). Search results for
"Dalamud" often turn up outdated API examples from old versions. dalamud.dev is the reliable source. If someone is just
starting out: go there, not to Stack Overflow.

### The day DalamudPackager cost me a day

Dalamud SDK 15 ships its own default packager that writes icons and image URLs into the manifest. I had carried over a
`DalamudPackager.targets` file from the upstream repo with a `HandleImages` override, and it was overriding the SDK
default. Result: the manifest had no `IconUrl` anymore, and the plugin appeared in the plugin list without an icon.

The symptom was easy to spot, the cause cost a day. I had treated the override file as mandatory when it was not.
Removed in v0.5.2, SDK default running since then. Lesson: start with defaults, add overrides only when the default
demonstrably does not fit.

---

## What I learned from the fork

### Refactoring in an unfamiliar codebase

The standalone cut in v1.0.0 migrated the entire `ChatTwo.*` identity to `HellionChat.*`. That sounds like find and
replace. It was not.

In concrete terms: code namespace across all 80 source files plus 100 using directives plus two FQN aliases plus the
resource designer strings. Six IPC channels renamed (breaking change for third-party plugins, no known integrations).
Repo folder structure (`ChatTwo/` -> `HellionChat/`) including csproj, sln, all GitHub workflows and dependabot.yml.
Public-facing branding in README, repo.json and yaml reformulated to standalone framing.

It was not a solo find-and-replace because Unicode string paths in workflow YAMLs need different quoting than C#
strings. Because resource designer files have generated content that not every toolchain tracks. And because the
`ChatTwo.*` IPC channel names are strings in `GetIpcSubscriber` calls: no symbol, no compile error if you miss one. That
is when you find out what stays quiet.

### Security is no longer abstract

Before this project, supply chain security was academic for me. Three concrete lessons changed that.

**SQLite native binary.** I had to pin to 3.50.3 (`SQLitePCLRaw.lib.e_sqlite3` override) because `Microsoft.Data.Sqlite`
was pulling in a transitively referenced library at a version containing CVE-2025-6965 (memory corruption via aggregate
term overflow) and CVE-2025-7709. The managed wrapper was new; the native library was not. Lesson: transitive
dependencies do not audit themselves, you have to look.

**Lock file drift.** `packages.lock.json` honoured via `RestorePackagesWithLockFile=true` in the csproj prevents
transitive versions from silently drifting between my machine and CI. I only understood why this is not the default
after a build output mismatch between local and GitHub Actions.

**WrapText and the CodeQL alert that cost three releases.** CodeQL flagged a critical alert in `ImGuiUtil.WrapText` for
unvalidated local pointer arithmetic. v0.5.2 validated an edge case. Alert came back. v0.5.3 checked buffer length via
`GetByteCount` before the pointer math. Alert came back. v0.5.4 rebuilt the whole algorithm on `Span` and int offsets
with a 16 KiB cap on the ArrayPool rent. Only then did it go quiet.

Lesson: when a static analyser complains three times in a row, the analyser is not oversensitive. The data flow logic
is.

### CodeRabbit as an external code reviewer

The v1.0.0 sweep surfaced 3 critical and 21 major findings. Three classes were particularly instructive:

- **`Equals` methods comparing `GetHashCode()`.** Classic hash collision anti-pattern. Sounds like "if hashes are equal
  the objects are equal", which is exactly backwards. Hashes can collide; the objects are not equal.
- **`Dispose` methods that only unsubscribe part of their subscriptions.** Leak on every plugin reload. In normal use
  you do not notice it immediately; in a long-running test you do.
- **TOCTOU races.** Between a bounds check and a read another thread can swap out the array underneath you
  (`GlobalParametersCache`, `AutoTranslate`).

I had at best read the theory on all of these before, never diagnosed them in my own code. CodeRabbit was the moment
where "academic knowledge" became "okay, that is my code, that is my bug".

### External testers are worth their weight

Carla's feedback on pop-out discoverability triggered the header button in v0.6.1. That pop-outs were only reachable via
right-click was something I as maintainer had stopped seeing; I knew the path by heart. Carl's request for theme
variants with brightness gradations shifted my thinking from "one theme = one colour" to "theme families with mood
variants". Jingliu asked for TempTell persistence, which puts the tab system architecturally into question.

Solo I would not have seen any of those three things. Full stop.

### release.yml and the YAML rabbit hole

The `release.yml` workflow simply did not fire on the first v0.6.0 tag push. I dug through permissions, secret scopes
and tag trigger configuration for hours before I understood what was actually happening: the PowerShell heredoc footer
in the "Generate release body" step contained a `---` Markdown horizontal rule at column 1, and that terminated the YAML
block scalar of `run: |`. GitHub could not parse the workflow file, so the push-tag trigger never registered.

Fix: extracted the footer into an external `.github/release-footer.md`, workflow reads it via `Get-Content`. Lesson: if
a workflow does not trigger, verify first that GitHub can even parse the file. That was one of the bugs where I laughed
briefly after the fix and then asked myself how many other YAML files I had that might have the same trap in them.

---

## What I am still learning

### Performance profiling in a game context

The FPS drop bug from upstream Chat 2 ([#145](https://github.com/Infiziert90/ChatTwo/issues/145)) has not been
reproduced or verified in Hellion Chat. v1.0.0 applied several fixes on the suspected paths (DbViewer O(N²) -> O(N),
AutoTranslate lock serialisation, EmoteCache HttpClient reuse), but systematic measurement under load is missing. I
still need to learn how to properly measure what is actually consuming the frame budget in a plugin context.

### Native interop and pointer math

Even after the WrapText Span refactor in v0.5.4, pointer math makes me uneasy. ImGui forces you into `unsafe` code in
several places, and the safety margin from the "unbounded ArrayPool allocation" class of bugs is narrower than I would
like. I want to get better at that before touching deeper ImGui custom drawing.

### Test discipline for plugin code

The repo currently has no test project. That is a deliberate decision, not a forgotten one. Testing plugin code with
FFXIV hooks and Dalamud lifecycle cleanly is non-trivial, and I had not found an approach that made sense without a
large mocking scaffold. Privacy filter and configuration migration would be good test candidates because they are
isolated. On the list, but not a quick win.

### Linux quirks under Wine

XDG compliance, libnotify integration, WireGuard network detection, all on the [roadmap](ROADMAP.md), and all
technically still unclear. Wine and sandboxed plugin code do not share all system APIs, and I do not know where the
pitfalls are until I have found them.

---

## Use of AI tools

I use Claude Code as an assistant, not as a replacement for my own work.

**What I use AI for:**

- Debugging problems where I am stuck after extended research of my own
- Pattern recognition across large codebases (e.g. the ChatTwo -> HellionChat sweep across 80 files)
- Understanding questions on C# and Dalamud concepts I am not yet familiar with
- Code review sparring before I run CodeRabbit on something

**What I do myself:**

- Architecture and design decisions
- Privacy-first defaults and the threat model behind them
- Tester communication and roadmap prioritisation
- Reviewing, verifying, pushing

Classification and concrete examples are in [`AI_DISCLOSURE.md`](AI_DISCLOSURE.md). It matters to me that users and
potential contributors understand how the code came together, especially for a plugin that handles user data.

Yes, AI. Yes, alone. Both mentioned more than strictly necessary. Welcome to the open-source plugin climate.

---

## Why this transparency

Anyone reading the source code should know:

- I am not a professional C# or plugin developer and am still learning
- AI assistance is a tool, not a ghostwriter
- The privacy position, the design decisions and the roadmap are mine
- I try to keep my code as clean and secure as my current skills allow

Hellion Chat is also a learning project, and that should be visible in the repository.

---

## Links

- [`AI_DISCLOSURE.md`](AI_DISCLOSURE.md) -- AI pair disclosure with classification schema
- [`CONTRIBUTORS.md`](CONTRIBUTORS.md) -- who has made this plugin better alongside me
- [`../NOTICE.md`](../NOTICE.md) -- attribution to Infi and Anna for the Chat 2 foundation
- [`ROADMAP.md`](ROADMAP.md) -- planned cycles and topics