Implement checked array.h API and align docs with the site.

Replace the prototype header with overflow-safe growth, try_* accessors, and strict-C portability, then document the contracts and add compile-proof tests so doc snippets stay verified.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: code5717

README.md

@@ -19,8 +19,9 @@ Use checked macros by default. Keep unchecked macros only for compatibility or e
 - `array_make(T, size)`: allocate array with initial capacity (`size` can be `0`).
 - `array_free(arr)`: free array memory.
 - `array_reserve(arr, min_capacity)`: ensure capacity, returns `bool` and may update `arr` after `realloc`.
-- `array_try_push(arr, value)`: append one value, returns `bool`.
-- `array_try_at(arr, idx, out_ptr)`: bounds-checked access, returns `bool`.
+- `array_try_push(arr, value)`: append scalar rvalues, returns `bool`.
+- `array_try_push_lvalue(arr, value)`: append struct or other non-scalar elements, returns `bool`.
+- `array_try_at(arr, idx, out_ptr)`: bounds-checked access; writes a pointer into the array, returns `bool`.
 - `array_try_slice_t(T, arr, low, high, out_slice)`: bounds-checked slice creation, returns `bool`.
 - `array_back_ptr(arr)`: pointer to last element or `NULL` when empty.
 - `array_length(arr)`: element count.
@@ -41,8 +42,16 @@ These are kept for compatibility and speed-focused code paths:
 
 ## Portability notes
 
-- Strict C11/C17 path: use `array_for_each_t(T, arr, it)` and typed slice macros.
-- GNU/Clang convenience path: if `typeof` is supported, `array_for_each(arr, it)` is available.
+- Strict C11/C17 path (`-std=c11 -pedantic`): `ARRAY_HAS_TYPEOF` is `0`; use `array_for_each_t(T, arr, it)` and typed slice macros.
+- GNU/Clang convenience path: `ARRAY_HAS_TYPEOF` is `1`; `array_for_each(arr, it)` and `slice_from_array` are available.
+
+## Compile verification
+
+Doc snippets compile under strict C11:
+
+```sh
+tests/compile/run.sh
+```
 
 ## Example (safe usage)
 
@@ -117,4 +126,4 @@ npm run build
 - Workflow file: `.github/workflows/pages.yml`
 - Trigger: push to `main` (or manual `workflow_dispatch`)
 - Output: `site/dist` uploaded as GitHub Pages artifact
-- Expected URL after deploy: `https://airbus5717.github.io/arraylist/`
+- Expected URL after deploy: `https://code5717.github.io/Arraylist/`

array.h

@@ -43,9 +43,17 @@ This reference is organized by operation group and focuses on behavior contracts
 ### `array_try_push(arr, value) -> bool`
 
 - Purpose: append one element at the logical end.
-- Preconditions: `arr` non-`NULL`.
+- Preconditions: `arr` non-`NULL`; `value` must be a scalar type covered by the macro's `_Generic` dispatch (integers and floating-point).
 - Failure behavior: returns `false` if `arr` is null, count overflows, or growth fails.
 - Complexity: amortized `O(1)`, worst-case `O(n)` on resize.
+- Notes: copies the value into the array. Literal and rvalue scalars (for example `10`, loop index) are supported.
+
+### `array_try_push_lvalue(arr, value) -> bool`
+
+- Purpose: append one element when `T` is a struct or other non-scalar type, or when pushing through an lvalue is clearer.
+- Preconditions: `arr` non-`NULL`; `value` must be an lvalue of the array's element type.
+- Failure behavior: same as `array_try_push`.
+- Complexity: same as `array_try_push`.
 
 ### `array_push(arr, value)` (compatibility)
 
@@ -58,13 +66,14 @@ This reference is organized by operation group and focuses on behavior contracts
 
 ### `array_try_at(arr, idx, out_ptr) -> bool`
 
-- Purpose: checked element access by index.
+- Purpose: checked element access by index; writes a pointer to the element inside the array (not a copy).
 - Preconditions:
   - `arr` non-`NULL`
   - `idx < arr->count`
-  - `out_ptr` non-`NULL`
-- Failure behavior: returns `false` when any precondition fails.
+  - `out_ptr` non-`NULL` (address of a `T*` variable)
+- Failure behavior: returns `false` when any precondition fails; does not write `*out_ptr` on failure.
 - Complexity: `O(1)`.
+- Notes: the returned pointer is invalidated if the array is reallocated or freed.
 
 ### `array_at(arr, idx)` (unchecked)
 
@@ -123,10 +132,17 @@ This reference is organized by operation group and focuses on behavior contracts
 ### `array_for_each(arr, it)` (GNU/Clang convenience)
 
 - Purpose: inferred-type iteration where `typeof` is available.
-- Preconditions: `ARRAY_HAS_TYPEOF` enabled and `arr` non-`NULL`.
-- Failure behavior: unavailable in strict mode; otherwise same preconditions as typed iteration.
+- Preconditions: `ARRAY_HAS_TYPEOF` is `1` (GNU/Clang, not strict ISO C) and `arr` non-`NULL`.
+- Failure behavior: macro is unavailable when `ARRAY_HAS_TYPEOF` is `0`; otherwise same preconditions as typed iteration.
 - Complexity: `O(n)`.
 
+### `slice_from_array(arr, low, high)` (GNU/Clang convenience)
+
+- Purpose: unchecked slice creation with inferred element type.
+- Preconditions: `ARRAY_HAS_TYPEOF` is `1`; bounds valid.
+- Failure behavior: unavailable in strict mode; undefined behavior if bounds are invalid.
+- Complexity: `O(1)`.
+
 ## Metadata and nullable helpers
 
 ### `array_length(arr)` / `array_is_empty(arr)`

docs/api-reference.md

@@ -91,11 +91,35 @@ array_for_each(arr, it)
 
 Why this matters: same runtime behavior as typed iteration, but shorter syntax when `typeof` is available.
 
-## 8) Cleanup pattern
+## 8) Struct element push (non-scalar)
+
+```c
+typedef struct { int x; int y; } Point;
+generate_array_type(Point);
+
+Array(Point) points = array_make(Point, 0);
+Point p = { .x = 1, .y = 2 };
+
+if (!array_try_push_lvalue(points, p))
+{
+    array_free(points);
+    return 1;
+}
+```
+
+Why this matters: `array_try_push` dispatches scalar types with `_Generic`; struct elements use the lvalue helper.
+
+## 9) Cleanup pattern
 
 ```c
 array_free(arr);
 arr = NULL;
 ```
 
 Why this matters: freeing ownership plus nulling local pointers helps prevent accidental reuse.
+
+Compile-check all examples:
+
+```sh
+tests/compile/run.sh
+```

docs/examples.md

@@ -78,6 +78,13 @@ Unchecked compatibility APIs:
 - Assume preconditions are already true.
 - Are concise, but undefined behavior is possible if used incorrectly (for example, out-of-bounds access or last-element access on empty arrays).
 
+## Portability
+
+- `array_size_t` is a `size_t` alias used for counts, capacities, and slice lengths.
+- Strict C11/C17 (`-std=c11 -pedantic`): use `array_for_each_t(T, arr, it)` and typed slice macros. `ARRAY_HAS_TYPEOF` is `0`.
+- GNU/Clang convenience (`-std=gnu11` or non-pedantic GCC/Clang): `ARRAY_HAS_TYPEOF` is `1`, enabling `array_for_each` and `slice_from_array`.
+- `array_try_push` accepts scalar rvalues (for example `array_try_push(arr, 10)`) via C11 `_Generic`. For struct or other non-scalar element types, use `array_try_push_lvalue(arr, value)` with an lvalue.
+
 ## Complexity at a glance
 
 | Operation | Complexity | Notes |

docs/overview.md

@@ -61,18 +61,24 @@ What this demonstrates:
 
 ## 3) Compile commands
 
-Strict C11/C17 path:
+Strict C11/C17 path (`ARRAY_HAS_TYPEOF` is `0`; use `array_for_each_t`):
 
 ```sh
 cc -std=c11 -Wall -Wextra -pedantic demo.c -o demo
 ```
 
-GNU11 convenience path (`array_for_each` available when `typeof` is supported):
+GNU11 convenience path (`ARRAY_HAS_TYPEOF` is `1`; `array_for_each` available):
 
 ```sh
 cc -std=gnu11 -Wall -Wextra demo.c -o demo
 ```
 
+Verify the doc snippets in this repository:
+
+```sh
+tests/compile/run.sh
+```
+
 ## 4) Failure-handling pattern (recommended)
 
 For mutating operations, check every `bool`-returning macro:
@@ -97,7 +103,9 @@ Why this pattern works:
   - Confirm you are using checked APIs and handling return values.
 - Iterator macro missing:
   - Use `array_for_each_t` for strict C mode; `array_for_each` requires `ARRAY_HAS_TYPEOF`.
+- Push fails on struct element types:
+  - Use `array_try_push_lvalue(arr, value)` instead of `array_try_push` for struct or other non-scalar `T`.
 - Pointer issues after growth:
-  - Remember reallocation can move the array block; stale element pointers may become invalid.
+  - Remember reallocation can move the array block; pointers from `array_try_at` or slices may become invalid.
 
 Next: [API Reference](./api-reference.md).

docs/quickstart.md

@@ -15,7 +15,7 @@
       content="Header-only dynamic array macros for C with checked APIs, explicit ownership, and strict-C portability."
     />
     <meta property="og:type" content="website" />
-    <meta property="og:url" content="https://airbus5717.github.io/arraylist/" />
+    <meta property="og:url" content="https://code5717.github.io/Arraylist/" />
     <meta name="theme-color" content="#0d1117" />
   </head>
   <body>

site/index.html

@@ -22,6 +22,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.39.1",
+    "@types/mdast": "^4.0.4",
     "@types/node": "^24.10.1",
     "@types/react": "^19.2.7",
     "@types/react-dom": "^19.2.3",
@@ -35,6 +36,7 @@
     "tailwindcss": "^3.4.19",
     "typescript": "~5.9.3",
     "typescript-eslint": "^8.48.0",
+    "unist-util-visit": "^5.1.0",
     "vite": "^7.3.1"
   }
 }

site/package-lock.json

@@ -1,4 +1,4 @@
-import { useRef, useState } from 'react'
+import { useEffect, useRef, useState } from 'react'
 import type { ReactNode } from 'react'
 
 type CodeBlockProps = {
@@ -8,18 +8,34 @@ type CodeBlockProps = {
 export function CodeBlock({ children }: CodeBlockProps) {
   const preRef = useRef<HTMLPreElement>(null)
   const [copied, setCopied] = useState(false)
+  const timeoutRef = useRef<number | null>(null)
   const canCopy = typeof navigator !== 'undefined' && Boolean(navigator.clipboard)
 
+  useEffect(() => {
+    return () => {
+      if (timeoutRef.current !== null) {
+        window.clearTimeout(timeoutRef.current)
+      }
+    }
+  }, [])
+
   async function handleCopy() {
     const text = preRef.current?.textContent ?? ''
 
     if (!text || !navigator.clipboard) {
       return
     }
 
-    await navigator.clipboard.writeText(text)
-    setCopied(true)
-    window.setTimeout(() => setCopied(false), 2000)
+    try {
+      await navigator.clipboard.writeText(text)
+      setCopied(true)
+      if (timeoutRef.current !== null) {
+        window.clearTimeout(timeoutRef.current)
+      }
+      timeoutRef.current = window.setTimeout(() => setCopied(false), 2000)
+    } catch {
+      setCopied(false)
+    }
   }
 
   return (