chore: CI and code-quality improvements

.clang-format

@@ -0,0 +1,34 @@
+# clang-format config for virtualjaguar-libretro.
+#
+# DELIBERATELY MINIMAL.  The upstream codebase has mixed brace style
+# AND mixed indent (tabs in src/tom/*, spaces in libretro.c, Allman
+# braces in src/jerry/jerry.h, K&R elsewhere) per-file.  No single
+# style works.  This config only enforces things that are universally
+# consistent across the tree: don't sort includes, don't reflow long
+# lines, don't touch preprocessor indent.  Brace placement, spacing,
+# and indent style are NOT enforced.
+#
+# The CI check (`clang-format.yml`) runs clang-format-diff on changed
+# lines and posts suggestions to the job summary -- it does NOT fail
+# the build.  Use it as a "consider this" prompt, not a gate.
+
+BasedOnStyle: LLVM
+Language: Cpp
+
+# Don't reflow long lines -- author makes wrapping decisions.
+ColumnLimit: 0
+
+# libretro / UAE include order is hand-tuned; don't reorder.
+SortIncludes: false
+IncludeBlocks: Preserve
+
+# Don't touch preprocessor indent -- breaks ifdef-guarded code.
+IndentPPDirectives: None
+
+# Tolerate both tab and space indent without rewriting.
+UseTab: ForIndentation
+TabWidth: 4
+IndentWidth: 4
+
+# Don't reformat comments (preserves the upstream's ASCII art).
+ReflowComments: false

.clang-tidy

@@ -0,0 +1,47 @@
+# clang-tidy config for virtualjaguar-libretro.
+#
+# Curated check list aimed at catching real bugs in emulator C code
+# without flooding the diff with style-preference noise.  See the
+# CI workflow `clang-tidy` job for how this is invoked (only on
+# PR-changed files).
+#
+# Disabled checks rationale below each `-` entry.
+
+Checks: >
+  bugprone-*,
+  clang-analyzer-*,
+  readability-inconsistent-declaration-parameter-name,
+  readability-misleading-indentation,
+  readability-redundant-control-flow,
+  misc-redundant-expression,
+  -bugprone-easily-swappable-parameters,
+  -bugprone-narrowing-conversions,
+  -bugprone-implicit-widening-of-multiplication-result,
+  -bugprone-reserved-identifier,
+  -bugprone-assignment-in-if-condition,
+  -bugprone-macro-parentheses,
+  -bugprone-signed-char-misuse,
+  -bugprone-suspicious-include,
+  -clang-analyzer-security.insecureAPI.DeprecatedOrUnsafeBufferHandling,
+  -clang-analyzer-valist.Uninitialized
+
+# Don't promote to errors yet -- the workflow itself decides via
+# --warnings-as-errors / continue-on-error.
+WarningsAsErrors: ''
+
+# Apply checks to in-tree headers but skip vendored / generated.
+HeaderFilterRegex: '^(src/(core|tom|jerry|cd)|libretro\.c).*'
+
+# Don't run clang-format inline (we have a separate clang-format job).
+FormatStyle: none
+
+# Disabled-check rationale:
+# - easily-swappable-parameters: emulator hot paths take many same-typed args.
+# - narrowing-conversions / implicit-widening: register byte ops trip these constantly.
+# - reserved-identifier: __LIBRETRO__ and UAE __regs/__pads use reserved names by design.
+# - assignment-in-if-condition: idiomatic in dispatch loops.
+# - macro-parentheses: misfires on GET16/SET32 byte-swap macros.
+# - signed-char-misuse: ROM byte buffers commonly use signed char.
+# - suspicious-include: project includes .c files in a couple of dispatch headers.
+# - DeprecatedOrUnsafeBufferHandling: MSVC-flavored noise about strcpy/sprintf.
+# - valist.Uninitialized: false-positive prone on our log macros.

.ecrc

@@ -0,0 +1,17 @@
+{
+  "Exclude": [
+    "test/roms/.*",
+    "test/baselines/.*",
+    "test/tools/build/.*",
+    "build/.*",
+    "src/m68000/.*",
+    "src/bios/jag.*\\.c$",
+    "src/core/version.h",
+    "libretro-common/.*",
+    "docs/atari-jaguar-1999/.*",
+    ".*\\.(png|jpg|jpeg|gif|bmp|ico|pdf|j64|jag|rom|cof|abs|bin|chd|cue|iso|cdi|so|dll|dylib|a|o|bc|exe|dat|gz|tar|zip|tgz|7z)$"
+  ],
+  "Disable": {
+    "MaxLineLength": true
+  }
+}

.editorconfig

@@ -0,0 +1,56 @@
+# EditorConfig: https://editorconfig.org
+#
+# Project-wide consistency for line endings / charset / final newline.
+# Indentation style is intentionally NOT enforced for C sources here:
+# the upstream Virtual Jaguar tree mixes tabs (src/tom, src/jerry) with
+# 4-space (libretro.c, src/core/cheat.c) and a sweeping reformat is out
+# of scope.  Makefiles (tabs required) and YAML (2-space) are pinned.
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+# Makefiles: recipe lines must be tabs (make will fail loudly if not),
+# but ifeq/else if blocks in this tree mix tab/space indentation for
+# readability; we don't enforce a single style here.
+
+# GitHub Actions / generic YAML.
+[*.{yml,yaml}]
+indent_style = space
+indent_size = 2
+
+# Shell scripts: only enforce no-tabs; the existing tree uses 3-space
+# in some files and 2-space in others, both fine.
+[*.sh]
+indent_style = space
+
+# Markdown: trailing two spaces are a hard line-break — don't strip.
+[*.md]
+trim_trailing_whitespace = false
+
+# Machine-generated UAE 68K core: do not touch.
+[src/m68000/**]
+charset = unset
+end_of_line = unset
+insert_final_newline = unset
+trim_trailing_whitespace = unset
+indent_style = unset
+indent_size = unset
+
+# Embedded BIOS / boot stubs are bin2c-generated hex arrays;
+# every line ends in trailing whitespace by design.
+[src/bios/jag*.c]
+trim_trailing_whitespace = unset
+
+# libretro-common is a vendored subtree.
+[libretro-common/**]
+charset = unset
+end_of_line = unset
+insert_final_newline = unset
+trim_trailing_whitespace = unset
+indent_style = unset
+indent_size = unset

.github/CODEOWNERS

@@ -1 +1 @@
-*       @JoeMatt @twinaphex 
+*       @JoeMatt @twinaphex

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,98 @@
+name: Bug report
+description: A reproducible behavior bug (crash, wrong output, hang, freeze) in a specific game or scenario.
+title: "[bug] "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for filing.  The more reproducible this is, the faster it gets fixed.  For perf regressions, use the `Performance issue` template instead.
+
+  - type: input
+    id: game
+    attributes:
+      label: Game / ROM
+      description: Title, region, dump notes (homebrew vs commercial, .jag vs .j64, CD vs cart).
+      placeholder: "e.g. Atari Karts (1995, USA, .jag)"
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      description: What you did, in order, including which menu screens / inputs.
+      placeholder: |
+        1. Boot ROM
+        2. Press Start at title
+        3. Select Single Race
+        4. Crash on track-select screen
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected vs actual
+      placeholder: |
+        Expected: track-select renders normally.
+        Actual: black screen, audio loops 0.5s buffer, RetroArch logs "GPU stalled".
+    validations:
+      required: true
+
+  - type: dropdown
+    id: bios
+    attributes:
+      label: BIOS mode
+      description: Set in RetroArch core options as `virtualjaguar_bios`.
+      options:
+        - "HLE BIOS (default; no real BIOS file)"
+        - "Real BIOS (jagboot.rom in system/)"
+        - "Not sure"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: blitter
+    attributes:
+      label: Blitter mode
+      description: Set in RetroArch core options as `virtualjaguar_usefastblitter`.
+      options:
+        - "Fast (default)"
+        - "Accurate (Midsummer2)"
+        - "Both (issue is independent of blitter)"
+    validations:
+      required: true
+
+  - type: input
+    id: core_version
+    attributes:
+      label: Core version
+      description: RetroArch -> Information -> Core Information -> "Core Version", or strings on the binary. (e.g. v2.2.0 abc1234)
+    validations:
+      required: true
+
+  - type: input
+    id: frontend
+    attributes:
+      label: Frontend + platform
+      placeholder: "e.g. RetroArch 1.21.0, macOS 14.5 (arm64); or Provenance 3.x iOS"
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs
+      description: Paste relevant lines from the RetroArch log (Settings -> Logging -> Logging Verbosity = Debug, then check `~/Library/Application Support/RetroArch/logs/` on macOS or platform equivalent).  Use `<details><summary>Log</summary>...</details>` for long pastes.
+      render: shell
+
+  - type: checkboxes
+    id: pre
+    attributes:
+      label: Pre-flight
+      options:
+        - label: Verified the issue is in this libretro core (not standalone Virtual Jaguar or another emulator).
+          required: true
+        - label: Searched [existing issues](https://github.com/libretro/virtualjaguar-libretro/issues?q=is%3Aissue) for duplicates.
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: libretro Discord
+    url: https://discord.com/invite/27Xxm2h
+    about: General libretro / RetroArch questions are best in the Discord; this tracker is for Virtual Jaguar core bugs and feature work.
+  - name: Upstream Virtual Jaguar
+    url: http://shamusworld.gotdns.org/git/virtualjaguar
+    about: Issues that are reproducible in standalone Virtual Jaguar (not specific to the libretro core) belong upstream.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,39 @@
+name: Feature request
+description: A new capability you'd like the core to expose.
+title: "[feat] "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Before filing: this is a libretro fork of upstream Virtual Jaguar.  Hardware-emulation requests should usually go upstream; this tracker is for libretro-specific surface (core options, save state shape, RetroAchievements, input remapping, etc.).
+
+  - type: textarea
+    id: what
+    attributes:
+      label: What
+      description: One sentence on what you want.
+    validations:
+      required: true
+
+  - type: textarea
+    id: why
+    attributes:
+      label: Why / use case
+      description: Concrete scenario.  "I want X so I can do Y" beats "X would be nice".
+    validations:
+      required: true
+
+  - type: textarea
+    id: how
+    attributes:
+      label: How (if you have ideas)
+      description: Optional.  Pointers to where you think it'd hook in (`libretro_core_options.h`, a specific subsystem) help if you have them.
+
+  - type: checkboxes
+    id: pre
+    attributes:
+      label: Pre-flight
+      options:
+        - label: This is libretro-fork-specific, not a general Virtual Jaguar emulation feature (those go upstream).
+          required: true

.github/ISSUE_TEMPLATE/performance_issue.yml

@@ -0,0 +1,77 @@
+name: Performance issue
+description: Slowdown, frame drops, or audio stutter in a specific game or scenario.
+title: "[perf] "
+labels: ["performance"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this for perf regressions, frame drops, audio stutter, slow boot.  For functional bugs (crashes, wrong output), use the `Bug report` template instead.
+
+        Run `make benchmark BENCH_ROM=<your rom>` from a fresh clone to get a stable wall-clock number that's easier to triage than "it feels slow".  See [`docs/profiling.md`](https://github.com/libretro/virtualjaguar-libretro/blob/develop/docs/profiling.md).
+
+  - type: input
+    id: game
+    attributes:
+      label: Game / ROM
+      placeholder: "e.g. Wolfenstein 3D (1994, USA, .jag)"
+    validations:
+      required: true
+
+  - type: textarea
+    id: scenario
+    attributes:
+      label: Scenario
+      description: Where in the game.  "Title screen" vs "level 3 with 5 enemies on screen" matter.
+      placeholder: "Level 3 first room: 4 visible enemies + animated wall textures."
+    validations:
+      required: true
+
+  - type: input
+    id: bench
+    attributes:
+      label: Benchmark numbers (if you have them)
+      description: Output of `make benchmark BENCH_ROM=<your rom>` -- frames/sec, ms/frame.  Mention CPU + OS so we can sanity-check.
+      placeholder: "make benchmark BENCH_ROM=Wolf3D.jag -> 42 FPS / 23.8 ms (M2 MBP, macOS 14.5)"
+
+  - type: dropdown
+    id: blitter
+    attributes:
+      label: Blitter mode (matters for perf!)
+      options:
+        - "Fast (default)"
+        - "Accurate (Midsummer2)"
+        - "Both equally slow"
+        - "Tested fast only"
+    validations:
+      required: true
+
+  - type: input
+    id: core_version
+    attributes:
+      label: Core version
+      placeholder: "v2.2.0 abc1234"
+    validations:
+      required: true
+
+  - type: input
+    id: frontend
+    attributes:
+      label: Frontend + hardware
+      placeholder: "RetroArch 1.21.0, macOS 14.5, M2 Pro (arm64)"
+    validations:
+      required: true
+
+  - type: textarea
+    id: regression
+    attributes:
+      label: Did this work better before?
+      description: If yes, name the version it was fast in, or the commit/release that broke it. `git bisect` results welcome.
+
+  - type: checkboxes
+    id: pre
+    attributes:
+      label: Pre-flight
+      options:
+        - label: Verified by running with both `Fast` and `Accurate` blitter modes.
+        - label: Other libretro cores run at full speed on the same hardware (rules out general system slowness).