Zensical

.claude/agents/cf-api-reviewer.md

@@ -0,0 +1,68 @@
+---
+name: cf-api-reviewer
+description: Reviews Cute Framework public API headers for convention compliance. Use after creating or significantly modifying any file in include/.
+color: cyan
+---
+
+You are a specialized code reviewer for Cute Framework's public C/C++ API conventions.
+
+**Generated files** — `*_shd.h` files are produced by `build/cute-shaderc` and must not be reviewed or edited. All other `include/cute_*.h` files, including `cute_shader_bytecode.h`, are hand-written and subject to these rules.
+
+When asked to review a header file, check ALL of the following and report only actual violations (not passing items):
+
+**1. Copyright header** — First comment block must match exactly:
+```
+/*
+	Cute Framework
+	Copyright (C) 2024 Randy Gaul https://randygaul.github.io/
+
+	This software is dual-licensed with zlib or Unlicense, check LICENSE.txt for more info
+*/
+```
+
+**2. Include guard** — Must be `CF_<NAME>_H` where `<NAME>` = filename with `cute_` stripped, uppercased.
+- `cute_physics.h` → `CF_PHYSICS_H`
+- `cute.h` → `CF_H`
+
+**3. extern "C" wrapping** — All C declarations must be inside:
+```c
+#ifdef __cplusplus
+extern "C" {
+#endif // __cplusplus
+...
+#ifdef __cplusplus
+}
+#endif // __cplusplus
+```
+
+**4. Function naming** — Every public C function must start with `cf_`.
+
+**5. Type naming** — Every public struct, enum, and typedef must start with `CF_`.
+
+**6. Lifecycle verbs** — Creation uses `cf_make_<name>`, destruction uses `cf_destroy_<name>`. Flag other patterns.
+
+**7. Deprecation pattern** — Deprecated symbols must have `@deprecated` in their doc comment. The deprecated name must be a `CF_INLINE` forwarder to the new name (or vice versa).
+
+**8. Documentation** — All public declarations must have `/** ... */` block comments (never `///`). Each interior line starts with ` * `. Required tags and order:
+1. `@function` / `@struct` / `@enum` — declaration kind, value is the symbol name
+2. `@category` — functional grouping (e.g. `graphics`, `audio`, `sprite`, `allocator`)
+3. `@brief` — one-line description
+4. `@param` — one per parameter, name padded so descriptions align; omit if none
+5. `@return` — omit for `void`
+6. `@remarks` — optional extended notes; continuation lines align with first word; embedded code uses fenced ` ```c ``` ` blocks
+7. `@example` — optional; title follows `>`, code lines are indented (no backtick fences)
+8. `@related` — space-separated symbol list on one line (highly recommended)
+
+Additional inline annotation rules:
+- Struct members: `/* @member Description. */` before each field; typedef followed by `// @end`
+- Enum values in X-macro blocks: `/* @entry Description. */` before each `CF_ENUM(...)` line, with `/* @end */` as the final entry
+
+**9. C++ wrappers** — A `namespace Cute` section should exist for non-trivial APIs.
+
+**10. Include style** — CF headers use quotes (`"cute_defines.h"`), system/SDL use angle brackets (`<SDL3/SDL.h>`).
+
+**11. cute.h** — If the header is new, check that it's been added to `include/cute.h` in a manner consistent with that file's existing grouping/ordering (do not assume strict global alphabetical order).
+
+**12. CMakeLists.txt** — If a new source file `cute_<name>.cpp` was created, check that it's been added to the `CF_SRCS` source list in the repository root `CMakeLists.txt`.
+
+Report each violation with `filename:line` where possible. Be concise — list only violations.

.claude/hooks/block-generated-files.py

@@ -0,0 +1,23 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: blocks edits to generated shader headers (*_shd.h).
+
+Only files ending in _shd.h are generated by build/cute-shaderc.
+cute_shader_bytecode.h is hand-written and NOT blocked.
+"""
+import sys
+import json
+import os
+
+data = json.load(sys.stdin)
+tool_input = data.get("tool_input", {})
+file_path = tool_input.get("file_path", "")
+
+if file_path:
+    name = os.path.basename(file_path)
+    if name.endswith("_shd.h"):
+        print(
+            f"Blocked: '{name}' is a generated file. "
+            "Regenerate with build/cute-shaderc instead of editing manually.",
+            file=sys.stderr,
+        )
+        sys.exit(2)

.claude/hooks/check-include-guard.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+"""PostToolUse hook: warns when an include/ header is missing its expected CF_*_H guard."""
+import sys
+import json
+import os
+
+data = json.load(sys.stdin)
+tool_input = data.get("tool_input", {})
+file_path = tool_input.get("file_path", "")
+
+norm = os.path.normpath(file_path)
+parts = norm.split(os.sep)
+if "include" in parts and file_path.endswith(".h"):
+    name = os.path.basename(file_path)  # e.g. "cute_graphics.h"
+    base = name[:-2]  # strip ".h"
+
+    if base.startswith("cute_"):
+        rest = base[5:]  # "cute_graphics" -> "graphics"
+    elif base == "cute":
+        rest = ""
+    else:
+        rest = base
+
+    expected = f"CF_{rest.upper()}_H" if rest else "CF_H"
+
+    try:
+        with open(file_path) as f:
+            content = f.read()
+        if expected not in content:
+            print(
+                f"WARNING: {name} is missing expected include guard '{expected}'.",
+                file=sys.stderr,
+            )
+    except OSError:
+        pass

.claude/settings.json

@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 .claude/hooks/block-generated-files.py"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 .claude/hooks/check-include-guard.py"
+          }
+        ]
+      }
+    ]
+  }
+}

.claude/skills/header-api-review/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: header-api-review
+description: Cute Framework public header conventions and review checklist. Reference before creating or modifying any file in include/.
+user-invocable: false
+---
+
+# CF Header Conventions
+
+## File Naming
+- Public headers: `cute_<name>.h` in `include/`
+- Source files: `cute_<name>.cpp` in `src/`
+
+## Generated vs Hand-Written Headers
+- **Generated** (do NOT edit manually): `*_shd.h` shader bytecode files produced by `build/cute-shaderc`
+- **Hand-written** (edit normally): all other `include/cute_*.h` files, including `cute_shader_bytecode.h` which defines shared shader structures and is NOT generated
+
+## Include Guards
+Format: `CF_<NAME>_H` where `<NAME>` is the filename with `cute_` prefix stripped, uppercased.
+- `cute_graphics.h` → `CF_GRAPHICS_H`
+- `cute_sprite.h` → `CF_SPRITE_H`
+- `cute.h` → `CF_H`
+
+## Copyright Header
+Every file must begin with exactly:
+```
+/*
+	Cute Framework
+	Copyright (C) 2024 Randy Gaul https://randygaul.github.io/
+
+	This software is dual-licensed with zlib or Unlicense, check LICENSE.txt for more info
+*/
+```
+
+## Header Structure
+```c
+#ifndef CF_NAME_H
+#define CF_NAME_H
+
+#include "cute_defines.h"
+// ... other includes with quotes for CF headers, angle brackets for system/SDL ...
+
+//--------------------------------------------------------------------------------------------------
+// C API
+
+#ifdef __cplusplus
+extern "C" {
+#endif // __cplusplus
+
+// ... C declarations ...
+
+#ifdef __cplusplus
+}
+#endif // __cplusplus
+
+//--------------------------------------------------------------------------------------------------
+// C++ API
+
+#ifdef __cplusplus
+namespace Cute {
+// ... C++ wrappers ...
+} // namespace Cute
+#endif // __cplusplus
+
+#endif // CF_NAME_H
+```
+
+## Naming Conventions
+- Public C functions: `cf_` prefix, snake_case → `cf_make_sprite`, `cf_draw_line`
+- Public C structs/enums/typedefs: `CF_` prefix → `CF_Sprite`, `CF_PIXEL_FORMAT_R8`
+- X-macro enum patterns: `CF_<NAME>_DEFS` macro + `CF_<NAME>` enum typedef
+- Static internal functions: `s_` prefix — never in public headers
+- C++ namespace: `namespace Cute`, functions snake_case without `cf_` prefix
+
+## Lifecycle Functions
+Prefer `cf_make_<name>(...)` for creation and `cf_destroy_<name>(...)` for destruction.
+Avoid other lifecycle verbs unless strongly motivated.
+
+## Deprecation Pattern
+Old name stays as the real implementation; new name is a `CF_INLINE` forwarder (or vice versa).
+The deprecated symbol's doc comment must include `@deprecated Use cf_new_name instead.`
+```c
+/**
+ * @function cf_old_function
+ * @category example
+ * @brief    Does the thing.
+ * @deprecated Use cf_new_function instead.
+ * @related  cf_new_function
+ */
+CF_INLINE void cf_old_function(int x) { cf_new_function(x); }
+```
+
+## Documentation Format
+
+All public declarations use `/** ... */` block comments with ` * ` on every interior line.
+**Never use `///` style comments for documentation.**
+
+### Tag ordering (follow this sequence)
+1. `@function` / `@struct` / `@enum` — declaration kind; value is the symbol name
+2. `@category` — groups symbol in docs (e.g. `graphics`, `audio`, `input`, `allocator`, `sprite`)
+3. `@brief` — one-line summary
+4. `@param` — one entry per parameter (omit if none)
+5. `@return` — return value description (omit for `void`)
+6. `@remarks` — extended notes, caveats, usage details (optional)
+7. `@example` — code example with `>` title (optional)
+8. `@related` — space-separated list of related symbols (highly recommended)
+
+### Function / typedef / macro
+```c
+/**
+ * @function cf_noise2
+ * @category noise
+ * @brief    Generates a random value given a 2D coordinate.
+ * @param    noise  The noise settings.
+ * @param    x      Noise at this x-component.
+ * @param    y      Noise at this y-component.
+ * @return   Returns a random value at the specified point.
+ * @remarks  You're probably looking for image generation functions such as `cf_noise_pixels` or
+ *           `cf_noise_fbm_pixels`. This function is fairly low-level.
+ * @related  CF_Noise cf_make_noise cf_destroy_noise cf_noise2 cf_noise3 cf_noise4
+ */
+CF_API float CF_CALL cf_noise2(CF_Noise noise, float x, float y);
+```
+
+### Struct — with `// @end` marker and `/* @member */` inline comments
+```c
+/**
+ * @struct   CF_Result
+ * @category utility
+ * @brief    Information about the result of a function, containing any potential error details.
+ * @remarks  Check if a result is an error or not with `cf_is_error`.
+ * @related  CF_Result cf_is_error cf_result_make cf_result_error cf_result_success
+ */
+typedef struct CF_Result
+{
+	/* @member Either 0 for success, or -1 for failure. */
+	int code;
+
+	/* @member String containing details about any error encountered. */
+	const char* details;
+} CF_Result;
+// @end
+```
+
+### Enum — X-macro pattern with `/* @entry */` and `/* @end */`
+```c
+/**
+ * @enum     CF_PlayDirection
+ * @category sprite
+ * @brief    The direction a sprite plays frames.
+ * @related  CF_PlayDirection cf_play_direction_to_string CF_Animation
+ */
+#define CF_PLAY_DIRECTION_DEFS \
+	/* @entry Flips through the frames of an animation forwards. */ \
+	CF_ENUM(PLAY_DIRECTION_FORWARDS, 0) \
+	/* @entry Flips through the frames of an animation backwards. */ \
+	CF_ENUM(PLAY_DIRECTION_BACKWARDS, 1) \
+	/* @end */
+
+typedef enum CF_PlayDirection
+{
+	#define CF_ENUM(K, V) CF_##K = V,
+	CF_PLAY_DIRECTION_DEFS
+	#undef CF_ENUM
+} CF_PlayDirection;
+```
+
+### @example — indented code, title after `>`
+```c
+ * @example > Creating a dynamic array and freeing it afterwards.
+ *           dyna int* a = NULL;
+ *           apush(a, 5);
+ *           afree(a);
+```
+Code lines are indented to align under the title text (no triple-backtick fences in `@example`).
+
+### @remarks — embedded code uses fenced blocks
+When `@remarks` contains a multi-line code snippet, use fenced ` ```c ` blocks:
+```c
+ * @remarks  The members are stored tightly as an array. To access them:
+ *
+ *           ```c
+ *           for (int i = 0; i < info.num_uniforms; ++i) {
+ *               printf("%s\n", info.uniforms[i].block_name);
+ *           }
+ *           ```
+```
+
+### Formatting rules
+- **@param alignment**: pad the parameter name so all descriptions align in a column
+- **@remarks continuation**: indent continuation lines to align with the first word of the description
+- **@related**: single space-separated line; include both the type (`CF_Foo`) and related functions
+- **Inline code**: backticks around all symbol names in prose: `` `cf_make_noise` ``, `` `CF_Noise` ``
+- **Links**: standard Markdown `[text](url)` for external docs
+- **"Default X" / "Out parameter"**: suffix in `@param` descriptions where applicable
+
+## Includes
+- CF headers: quotes → `#include "cute_defines.h"`
+- System/SDL headers: angle brackets → `#include <SDL3/SDL.h>`
+- `cute_defines.h` is almost always needed (provides `CF_INLINE`, `CF_API`, `CF_GLOBAL`, etc.)
+
+## New Header Checklist
+- [ ] Copyright header (exact format)
+- [ ] Include guard `CF_<NAME>_H`
+- [ ] `#include "cute_defines.h"` at minimum
+- [ ] `extern "C" { ... }` wrapping for C section
+- [ ] All public C functions: `cf_` prefix
+- [ ] All public types: `CF_` prefix
+- [ ] `/** ... */` Doxygen comments on all public declarations with `@function`/`@struct`/`@enum`, `@category`, `@brief`, and `@related` tags
+- [ ] `namespace Cute` C++ wrappers section
+- [ ] Added to `include/cute.h` umbrella include (follow that file's existing include ordering conventions)
+- [ ] Source file `cute_<name>.cpp` added to top-level `CMakeLists.txt` (in the `CF_SRCS` list)

.github/actions/setup-cmake/action.yml

@@ -0,0 +1,11 @@
+name: Setup CMake
+description: Install CMake 4.2.x and Ninja (latest) via lukka/get-cmake
+
+runs:
+  using: composite
+  steps:
+    - name: Setup CMake 4.2.x
+      uses: lukka/get-cmake@latest
+      with:
+        cmakeVersion: 4.2.3
+        ninjaVersion: latest