Skip to content

Development

Michael Riddle edited this page Aug 24, 2026 · 6 revisions

Development

Prerequisites

Everything in Getting Started — the .NET 10 SDK, Node.js 18+ with npm, and FFmpeg on PATH — plus:

  • (Optional) Docker Desktop — for the Aspire dashboard's local telemetry when running via KHost.AppHost.
  • (Optional) ffprobe — ships with FFmpeg; the transcode tests use it to assert a segment really carries audio.
  • (Optional) Chromecast-Emulator listening on 127.0.0.1:8009 — the Cast tests skip without it.

Running for development

# With the Aspire dashboard (telemetry, resource view)
dotnet run --project src/KHost.AppHost

# The Blazor UI directly
dotnet run --project src/KHost.UserInterface

# Headless (no native window; serve the console to a browser)
dotnet run --project src/KHost.UserInterface -- --headless

Screens are normally launched from the host's Screens dialog, which injects the host's live listening address as --server-uri. To run one by hand:

# --screen-id defaults to the machine name
dotnet run --project src/KHost.Screen2 -- --server-uri http://localhost:5251/ipc/screen --screen-id main

# --log-level debug adds the state the page reports each tick (position, expected
# position, readyState) — how to tell a screen that is behind from one that never started
dotnet run --project src/KHost.Screen2 -- --server-uri http://localhost:5251/ipc/screen --log-level debug

Screen logs land in logs/ beside the screen executable, one file per screen id per day.

Verifying changes in the running app

The repository carries a project skill at .claude/skills/run-khost/SKILL.md — the verified recipe for launching KHost and driving its native window (readiness checks, GUI automation via cliclick, a full playback pass with the log lines that prove each step, shutdown expectations). Agent sessions load it automatically when asked to run the app; it reads as a checklist for humans too.

Its most important rule applies to anyone testing by hand: every graceful exit clears the singer queue and queued performances (the venue's ClearQueueOnClose defaults on and runs on shutdown — window close, Ctrl+C, and SIGTERM alike). Back up src/KHost.UserInterface/bin/Debug/net10.0/cache/ before a test run that will stop the app, and restore it after, or the run eats the local queue.

Hot reload

cd src/KHost.UserInterface
npm run dev           # runs dotnet watch

Building alongside Visual Studio

Redirect the output so the IDE's bin/ isn't locked:

dotnet build KHost.slnx "-p:BaseOutputPath=./obj/_build"

SCSS

SCSS compiles inside dotnet build (AspNetCore.SassCompiler) — there is no separate sass step. The build needs node_modules (npm install in src/KHost.UserInterface/) for copy:vendors.

  • Component styles live beside their component (Foo.razor.scss → scoped Foo.razor.css; the generated .css is gitignored — never edit or commit it).
  • Shared blocks live under wwwroot/scss and are pulled in via app.scss. Only app.scss and themes/* should lack a _ prefix — any other file without one compiles to its own stylesheet.
  • Top-level class names are prefixed kh-, with BEM naming. No inline style attributes, no <style> blocks. Bootstrap Icons only — no Bootstrap CSS/JS; its utility classes resolve to nothing.

Narrow layouts

The console is laid out for roughly 1440px and holds together down to about 700px. Two different widths decide what shrinks, and picking the wrong one is the usual mistake:

  • Panels answer to @container. panel-resize.js writes a pixel width onto the queue column, so a panel can be 180px wide in a 1440px window. Anything inside a panel keys off a named container (kh-queue, kh-singer-info, kh-media-search), never the viewport.
  • The header answers to @media. It spans the window, with no splitter between it and the viewport, so window width is the only width it has.

Set thresholds against a panel's measured width at 1440, not a round number — the queue column is about 283px there, so a 300px threshold would put a full-screen console into narrow mode.

For a control to shrink at all it usually needs min-width: 0 as well as white-space: nowrap: without it a flex item cannot go below its longest word, so it pushes its neighbours off the row instead of truncating.

Scoped CSS across a component boundary

A scoped rule only matches elements the component itself renders. A class handed to another component — <Icon Class="…" />, <InputNumber class="…" />, anything inside a RenderFragment passed as a parameter — lands on markup that carries a different scope id or none at all, and the rule silently matches nothing. Reach it with ::deep from an ancestor the component does render:

.kh-thing__row {
    ::deep .kh-thing__field { width: 120px; }
}

Never lead with ::deep &__x — the & expands to the parent and swallows it, leaving a selector the browser drops.

.kh-card__body pads a direct <form> child and nothing else, so a card body without a form needs its own padding.

Code conventions

  • Interfaces live in KHost.Abstractions, concrete types in their implementation project, registered in that project's ProjectExtensions (AddDomain() / AddDataAccess() / …); UI-only services in Program.cs.
  • Domain services are singletons — guard mutable state with SemaphoreSlim.
  • Services announce changes on IMessageBroker rather than raising events — there is no StateChanged and no IKHostService. A service that has something to report takes IMessageBroker in its own constructor and calls Broker.Announce(new ThingChanged()); components subscribe in OnInitialized, hold the subscriptions in a SubscriptionSet, and dispose it in Dispose. See Messaging.
  • Services that expose configuration use the nested ServiceOptions class pattern with BindConfiguration(ServiceOptions.SectionName) and IOptionsMonitor<> for live reload.
  • Every Task/ValueTask-returning method ends in Async — enforced by reflection in AsyncNamingConventionTests.
  • Component logic lives in a code-behind partial (Foo.razor.cs), never an inline @code block.
  • Member order: fields → events → properties → public → protected → private → nested types.
  • Method names that cross a string boundary ([JSInvokable] called from JS, SignalR hub methods invoked by name) are passed as nameof(...) from C# and taken as a parameter on the JS side, so a rename cannot break silently.

The full conventions, including agent-facing gotchas, live in AGENTS.md in the repository.

Schema changes

Venue.Settings is a JSON column — adding or removing properties on VenueSettings is not a schema change and needs no migration at all. But EF reads keys missing from stored rows as default, ignoring property initializers, so a new setting that must default to true needs a data-only json_set backfill migration.

For a real schema change (any DbSet<T> model), add a migration:

dotnet ef migrations add <Name> --project src/KHost.DataAccess

Additive changes such as an index apply in place and leave both the runtime database and the hand-written AddMediaFts migration alone.

Regenerating the chain from scratch is a separate, deliberate act rather than a step in adding a column. It destroys the local library, users and queue, and it drops the FTS5 setup on the floor:

  1. Delete src/KHost.DataAccess/Migrations/ and the runtime database.
  2. dotnet ef migrations add InitialSchema --project src/KHost.DataAccess
  3. Recreate AddMediaFts by hand — the FTS5 table and its triggers are raw SQL EF will not regenerate, and search throws no such table: media_fts without it. Copy the Up/Down SQL from a prior AddMediaFts.cs.

Contributing

See CONTRIBUTING.md for the contribution workflow, license grant, and DCO sign-off requirements.

Learn more

Starting points for the technologies KHost uses:

Clone this wiki locally