chore: CI and code-quality improvements

.clang-format

@@ -0,0 +1,56 @@
+# clang-format config for virtualjaguar-libretro.
+#
+# This config is deliberately TOLERANT.  The codebase has mixed indent
+# style by file (src/tom/*.c, src/jerry/*.c use tabs; libretro.c,
+# src/core/cheat.c use 4-space) inherited from upstream Virtual Jaguar.
+# Mass reformat is out of scope -- so this config preserves both styles
+# and only enforces things that ARE consistent (brace placement,
+# spacing, no trailing whitespace).
+#
+# The CI check (`clang-format-check.yml`) runs clang-format-diff on
+# CHANGED LINES ONLY so existing files aren't penalised.
+
+BasedOnStyle: LLVM
+Language: Cpp
+
+# Indent: tolerate both tab and space; don't fight existing files.
+UseTab: ForIndentation
+TabWidth: 4
+IndentWidth: 4
+ContinuationIndentWidth: 4
+
+# Braces / control flow: K&R / LLVM-ish, attach.
+BreakBeforeBraces: Attach
+AllowShortFunctionsOnASingleLine: None
+AllowShortIfStatementsOnASingleLine: false
+AllowShortLoopsOnASingleLine: false
+AllowShortBlocksOnASingleLine: Empty
+AllowShortCaseLabelsOnASingleLine: false
+
+# Spacing: standard C.
+SpaceAfterCStyleCast: false
+SpaceBeforeParens: ControlStatements
+SpacesInParentheses: false
+SpacesInSquareBrackets: false
+SpaceBeforeAssignmentOperators: true
+SpacesInCStyleCastParentheses: false
+
+# Line length: 0 = advisory only (clang-format won't reflow).  We
+# leave wrapping decisions to the author.
+ColumnLimit: 0
+
+# Empty lines.
+KeepEmptyLinesAtTheStartOfBlocks: false
+MaxEmptyLinesToKeep: 1
+
+# Headers: libretro / UAE include order is hand-tuned, don't sort.
+SortIncludes: false
+IncludeBlocks: Preserve
+
+# Pointer alignment: codebase mixes `T* p` and `T *p`; pick the
+# more common one (T *p, K&R-style) but don't aggressively rewrite.
+PointerAlignment: Right
+
+# Don't rewrite preprocessor indentation -- breaks ifdef-guarded
+# blocks of code in subtle ways.
+IndentPPDirectives: None

.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