Add breadcrumbs function, docs and tests

docs/04-development/04-context-api.md

@@ -22,6 +22,7 @@ These use PHP 8.4 `private(set)` — readable but not writable from outside the
 | Property | Type | Description |
 |---|---|---|
 | `navigation` | array | `buildNavigation($this)` — lazy-computed on access |
+| `breadcrumbs` | array | `buildBreadcrumbs($this)` — lazy-computed on access, returns breadcrumb trail for nested pages |
 | `homeLabel` | string | From root `metadata.ini` `slug` field, default `"Home"`. Note: reads `slug`, not `title` — typically set to a short label like "Home" or "Hjem" |
 
 ### Plugin Data Store

docs/04-development/09-breadcrumbs.md

@@ -0,0 +1,79 @@
+# Breadcrumbs
+
+**`buildBreadcrumbs(Context $ctx): array`**
+
+Returns a breadcrumb trail for nested content directories.
+
+| Condition | Return |
+|---|---|
+| Empty `requestPath` (frontpage) | `[]` |
+| Level 1 path (e.g., `/nyheter/`) | `[]` |
+| Level 2 path (e.g., `/nyheter/riksrevisjonen/`) | `[]` |
+| Level 3+ (e.g., `/nyheter/riksrevisjonen/artikkel/`) | Array of breadcrumb items |
+
+### Breadcrumb Item Structure
+
+```php
+[
+    'title' => string,     // Display title
+    'url' => string,       // URL with trailing slash
+    'isCurrent' => false   // Always false (current page excluded)
+]
+```
+
+### Title Resolution
+
+1. `title` field from `metadata.ini`
+2. First `<h1>` in content files (`.md`, `.html`, `.php`)
+3. `ucfirst(folder_name)` as fallback
+
+### URL Construction
+
+Uses `slug` from metadata if available, otherwise the folder name. URLs are:
+- Encoded with `rawurlencode()` for safety
+- Always include trailing slash
+- Prefixed with language prefix (from `$ctx->get('langPrefix', '')`)
+
+### Security
+
+- Path segments containing `..` are skipped (path traversal protection)
+- Only existing directories are included
+- URLs are encoded to prevent injection
+
+## Usage in Templates
+
+```php
+<?php if (!empty($breadcrumbs)): ?>
+<nav aria-label="Breadcrumb">
+    <ol>
+        <?php foreach ($breadcrumbs as $crumb): ?>
+        <li>
+            <a href="<?= htmlspecialchars($crumb['url']) ?>">
+                <?= htmlspecialchars($crumb['title']) ?>
+            </a>
+        </li>
+        <?php endforeach; ?>
+        <li aria-current="page"><?= htmlspecialchars($pageTitle ?? '') ?></li>
+    </ol>
+</nav>
+<?php endif; ?>
+```
+
+## Tests
+
+Located in `devel/tests/helpers/`:
+
+- `build_breadcrumbs_empty_path.phpt` — frontpage returns empty array
+- `build_breadcrumbs_level1.phpt` — single level returns empty array
+- `build_breadcrumbs_level2.phpt` — two levels returns empty array
+- `build_breadcrumbs_level3.phpt` — three+ levels returns breadcrumb array
+- `build_breadcrumbs_security_traversal.phpt` — path traversal attempts are skipped
+- `build_breadcrumbs_skips_missing_dirs.phpt` — missing directories are handled gracefully
+- `build_breadcrumbs_slug_override.phpt` — metadata slug overrides folder name
+- `build_breadcrumbs_extract_title_from_content.phpt` — title extracted from content files
+
+Run tests:
+
+```bash
+cd devel && ./tests/run.sh helpers
+```