181 lines
11 KiB
Markdown
181 lines
11 KiB
Markdown
# AGENTS.md
|
||
|
||
## What this is
|
||
|
||
SvelteKit 5 (runes mode) static site that assembles Steam launch commands from
|
||
composable "program classes" (gamescope, MangoHud, Proton, obs-gamecapture,
|
||
gamemode). User flips toggles in a tabbed UI; the app renders one flat launch
|
||
command string like:
|
||
|
||
```
|
||
gamescope -f -- %command% mangohud waitforexecandrun %command%
|
||
```
|
||
|
||
Rendered by adapter-static (`prerender = true` in `src/routes/+page.ts`).
|
||
|
||
## Core model (`src/lib/`)
|
||
|
||
- `meow.ts` — the engine. `ArgEvaluatable` interface (`enabled()`, `envs()`,
|
||
`binary()`, `prefix()`, `suffix()`, `priority()`, `arguments()`); `ArgEval`
|
||
evaluates components: filter `enabled()`, sort by `priority()` (lowest =
|
||
outermost wrapper), envs as `VAR=VAL` space-joined, each program rendered
|
||
`prefix binary args suffix` (empty parts dropped), args sorted by `prio` and
|
||
rendered `arg val` (bare `arg` when val empty), then `%command%` appended.
|
||
- `programs.ts` — data types + `Program` class implementing `ArgEvaluatable`
|
||
from a `ProgramConfig`. Key fields: `enabled`, `name`, `binary`, `prefix`,
|
||
`suffix`, `priority`, `envs`, `args`, `options` (toggleable sub-flags),
|
||
`envSeparators` (per-var merge separators), option `conflicts` (see below).
|
||
- `presets.ts` — re-export index only; real factories live per-program in
|
||
`src/lib/preset/` (see file map).
|
||
- `preset/helpers.ts` — builders shared by presets: `envToggle(label, env,
|
||
val, category?)`, `group(program, labels)` (pairwise conflict keys).
|
||
(Mutually-exclusive flag choices like `-F` filter use ONE option with an
|
||
`args[].values` dropdown — do NOT reintroduce one-option-per-value.)
|
||
|
||
### Semantics to keep in mind
|
||
|
||
- Env vars with the same name merge into ONE var: values dedupe, joined by the
|
||
var's separator from `envSeparators` (default `,`).
|
||
- `conflicts` keys are `'programname'` (program-level) or
|
||
`'program:Option label'` (option-level). Only enabled vs enabled conflict;
|
||
conflicts are displayed as a non-blocking warning banner.
|
||
- Env merge destructuring: `var` is a reserved word in TS — use
|
||
`[varName, vals]` in destructures.
|
||
- Args are space-separated (`-W 1920`), never `arg=val`.
|
||
|
||
## File map
|
||
|
||
| file | role |
|
||
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `src/lib/meow.ts` | evaluation engine (see above) |
|
||
| `src/lib/programs.ts` | types + `Program` adapter + `findConflicts()` |
|
||
| `src/lib/presets.ts` | re-exports the eight preset factories |
|
||
| `src/lib/preset/helpers.ts` | shared option builders |
|
||
| `src/lib/preset/gamescope.ts` | gamescope args (fullscreen, filter/scale dropdowns, HDR, VR, …) |
|
||
| `src/lib/preset/proton-ge.ts` | GloriousEggroll Proton env toggles |
|
||
| `src/lib/preset/proton-cachyos.ts` | CachyOS Proton env toggles (largest set) |
|
||
| `src/lib/preset/obs.ts` | obs-gamecapture CLI |
|
||
| `src/lib/preset/gamemode.ts` | `gamemoderun` wrapper (priority 5 = outermost) |
|
||
| `src/lib/preset/mangohud.ts` | MANGOHUD env options + `MANGOHUD_CONFIG` separator merge |
|
||
| `src/lib/preset/mesa.ts` | Mesa Vulkan layers env toggles (anti-lag, overlay layer, fps-monitor) |
|
||
| `src/lib/preset/prime.ts` | `prime-run` wrapper for NVIDIA PRIME offload |
|
||
| `src/lib/ProgramForm.svelte` | per-program editor: enabled checkbox, options list, Advanced `<details>` (name/binary/prefix/suffix/priority, env vars, args, env separators) |
|
||
| `src/lib/decode.ts` | `applyCommand(cmd, programs)` — enable options/programs a pasted command references (only ever enables, never disables) |
|
||
| `src/routes/+page.svelte` | tabs + `pre.result` command preview + conflict banner; localStorage persistence; decode textarea |
|
||
| `launch_args_env_vars.md` | reference: gamescope args, Proton env-var tables, OBS, gamemode |
|
||
| `steam-tinker-launcher.md` | reference: STL v14 docs (gamescope CLI catalog §3.1–3.6, mangohud, proton, dxvk, wine) |
|
||
|
||
## Conventions
|
||
|
||
- New programs are preset factory functions in `src/lib/preset/<name>.ts`
|
||
returning a `ProgramConfig`, re-exported from `presets.ts`, imported into
|
||
`+page.svelte`'s `programs` array.
|
||
- Every option carries a `category: string`; ProgramForm groups options under
|
||
category headings (keep categories consistent within a preset).
|
||
- Every option should also carry a `desc: string`; it appears as a hover
|
||
tooltip (1 s delay, CSS-only) next to the option row.
|
||
- Default new presets to `enabled: false` so the default output stays stable.
|
||
- Preset files ≤ ~140 lines; split if they grow (that's why the directory
|
||
exists). Shared builders go in `helpers.ts`.
|
||
- `+page.svelte` uses PURE TAB indentation — never build edit oldText with
|
||
spaces.
|
||
- Mutual exclusivity is expressed via `conflicts` (options) or `group()`
|
||
(helpers), never via extra app state.
|
||
- `user-select: none` on tabs/labels to stop double-click selection; inputs and
|
||
`pre.result` stay selectable.
|
||
|
||
## Adding options & programs (agent playbook)
|
||
|
||
Every task in this repo ends with the verification loop below; a change is not
|
||
done until all three pass.
|
||
|
||
### Add an option to an existing program
|
||
|
||
1. Edit `src/lib/preset/<name>.ts` — the program's factory, inside
|
||
`options: [...]`. Mine the flag/env catalogs from `launch_args_env_vars.md`
|
||
and `steam-tinker-launcher.md`.
|
||
2. Pick the builder (from `./helpers`):
|
||
|
||
- Env toggle (checkbox sets `VAR=1`):
|
||
`envToggle('Label', 'ENV_VAR', '1', 'Category')` — pass a custom value as
|
||
the 3rd arg for non-`1` values.
|
||
- Flag with a value (gets an editable input in the UI while enabled):
|
||
|
||
```ts
|
||
{ label: 'Mouse sensitivity', enabled: false, args: [{ arg: '-s', val: '1.0', prio: 0 }], category: 'Window' }
|
||
```
|
||
|
||
- Flag with a fixed value set (gets a `<select>` dropdown instead of a
|
||
text input): add `values: ['auto', 'drm', 'wayland']` to the arg.
|
||
- Flag whose value must match a regex (input turns red + banner error
|
||
while invalid): add `pattern: NUM` or `pattern: NUM_DEC` (exported from
|
||
`./helpers`) or a custom regex source string.
|
||
|
||
- Bare flag: same shape with `val: ''` (checkbox only, no input).
|
||
- Mutually exclusive flag with a fixed value set (e.g. `-F fsr` vs
|
||
`-F nis`): ONE option with `values` on the arg:
|
||
`{ label: 'Filter', enabled: false, args: [{ arg: '-F', val: 'fsr', prio: 0, values: ['none', 'linear', 'fsr', 'nis'] }], category: 'Filter' }`.
|
||
Do NOT create one option per value.
|
||
|
||
3. `category` is required — reuse an existing one from that preset or add a new
|
||
one (it becomes a tab). Keep categories consistent within a preset.
|
||
4. Mutual exclusivity: `conflicts: ['other-program']` or
|
||
`conflicts: ['same-program:Other option label']`; `group()` generates
|
||
these automatically.
|
||
5. Presets only supply defaults — the form binds arg `val` to an input while
|
||
the option is enabled, so users can override values.
|
||
|
||
### Add a new program
|
||
|
||
1. Create `src/lib/preset/<name>.ts` exporting
|
||
`export function <name>(): ProgramConfig` (model on
|
||
`src/lib/preset/obs.ts` — the smallest real example).
|
||
2. Required config: `name`, `enabled` (default `false` so output stays stable),
|
||
`binary`, `prefix` (wrapper like `'gamemoderun'`), `suffix`
|
||
(`'waitforexecandrun'` for proton, `'--'` for gamescope-style), `priority`,
|
||
`envs: []`, `args: []`, `options: [...]`.
|
||
3. Re-export: add `export { <name> } from './preset/<name>';` to
|
||
`src/lib/presets.ts`.
|
||
4. Import it in `src/routes/+page.svelte` and append to the
|
||
`programs = $state([...])` array.
|
||
5. Keep the file ≤ ~140 lines; use `envToggle()`/`group()` for builders and
|
||
repetitive options.
|
||
|
||
Priority semantics: components sort ascending by `priority()` — the outermost
|
||
wrapper has the LOWEST number (gamemoderun=5, gamescope=10, proton=20,
|
||
mangohud=30).
|
||
|
||
## Verification (mandatory before yielding)
|
||
|
||
```bash
|
||
pnpm exec prettier --write <edited files> # lint runs prettier --check
|
||
pnpm check # svelte-check — authoritative type check
|
||
pnpm lint # prettier --check + eslint
|
||
pnpm build # adapter-static build
|
||
```
|
||
|
||
All four must pass. `pnpm check` is the authority — see the known quirk below.
|
||
|
||
Known traps for agents:
|
||
|
||
- **pi-lens/LSP diagnostics on `.svelte` files are stale all session** — they
|
||
falsely report `enabled` / `category` / `envSeparators` as missing from
|
||
`ProgramConfig` on every edit. They are noise: the fields verifiably exist in
|
||
`programs.ts`. Do NOT chase them; rely on `pnpm check` (returns 0 errors
|
||
every time). The `.ts` files' diagnostics are accurate.
|
||
- `+page.svelte` uses pure tabs — edit `oldText` must use tabs, not spaces. If
|
||
the edit tool reports content-drift, re-read the file verbatim before
|
||
retrying.
|
||
- This file (AGENTS.md) is auto-reformatted by prettier/markdownlint after
|
||
edits — always re-read it before further edits; it also uses real em-dashes
|
||
(`—`).
|
||
- `var` is a reserved word in TS destructuring — use `[varName, vals]`.
|
||
- A stale `vite dev` server can serve corrupted modules (missing exports).
|
||
Fix: kill all `vite` processes and restart — never `pkill -f` with a pattern
|
||
that also appears in your own command line (it kills your shell).
|
||
- Do not add options the docs mark as per-user paths or STL-internal settings
|
||
(Vortex/MO2/winetricks/Conty…); README.md is sv boilerplate, ignore it.
|
||
|
||
Reference docs to mine for new options: `launch_args_env_vars.md` and
|
||
`steam-tinker-launcher.md` (README.md is sv boilerplate, ignore it).
|