@kirigami/php-prepros 1.0.9 → 1.1.0

package/README.md

@@ -17,42 +17,67 @@ Part of the **Kirigami** project ecosystem. Other packages are coming soon.
 ## Table of contents
 
 - [@kirigami/php-prepros](#kirigamiphp-prepros)
-	- [Table of contents](#table-of-contents)
-	- [How it works](#how-it-works)
-	- [Installation](#installation)
-	- [Configuration — `kirigami.yaml`](#configuration--kirigamiyaml)
-	- [Writing pages](#writing-pages)
-		- [PHPDOC header](#phpdoc-header)
-		- [Auto-loading data files](#auto-loading-data-files)
-	- [JavaScript API](#javascript-api)
-		- [`render(file?)`](#renderfile)
-		- [`sitemap()`](#sitemap)
-	- [PHP classes reference](#php-classes-reference)
-		- [PREPROS](#prepros)
-			- [`PREPROS::render(string $file)`](#preprosrenderstring-file)
-			- [`PREPROS::sitemap()`](#preprossitemap)
-			- [`PREPROS::exportFile(string $file)`](#preprosexportfilestring-file)
-		- [MD](#md)
-			- [Plugin API](#plugin-api)
-		- [HTML](#html)
-		- [YAML](#yaml)
-		- [CACHE](#cache)
-		- [IMG](#img)
-		- [FS](#fs)
-		- [STR](#str)
-		- [OBF](#obf)
-		- [STD](#std)
-	- [Plugin system](#plugin-system)
-		- [PREPROS tags](#prepros-tags)
-		- [PREPROS hooks](#prepros-hooks)
-		- [MD plugins](#md-plugins)
-		- [Built-in plugins](#built-in-plugins)
-			- [`{% callout type ["Title"] content %}`](#-callout-type-title-content-)
-	- [Extending the `<markdown>` tag](#extending-the-markdown-tag)
-	- [License](#license)
+  - [Table of contents](#table-of-contents)
+  - [What's new in 1.1.0](#whats-new-in-110)
+  - [How it works](#how-it-works)
+  - [Installation](#installation)
+  - [Configuration — `kirigami.yaml`](#configuration--kirigamiyaml)
+    - [`kirigami` block](#kirigami-block)
+    - [`prepros` block](#prepros-block)
+  - [Writing pages](#writing-pages)
+    - [PHPDOC header](#phpdoc-header)
+    - [Auto-loading data files](#auto-loading-data-files)
+    - [`@content` and `@indent`](#content-and-indent)
+  - [JavaScript API](#javascript-api)
+    - [`render(file?)`](#renderfile)
+    - [`sitemap()`](#sitemap)
+    - [`runenv(script, paths?, ...args)`](#runenvscript-paths-args)
+  - [PHP classes reference](#php-classes-reference)
+    - [PREPROS](#prepros)
+      - [`PREPROS::render(string $file)`](#preprosrenderstring-file)
+      - [`PREPROS::sitemap()`](#preprossitemap)
+      - [`PREPROS::mount(string|array $patterns)`](#preprosmountstringarray-patterns)
+      - [`PREPROS::exportFile(string $file)`](#preprosexportfilestring-file)
+    - [MD](#md)
+      - [Plugin API](#plugin-api)
+    - [HTML](#html)
+    - [YAML](#yaml)
+    - [CACHE](#cache)
+    - [IMG](#img)
+    - [FS](#fs)
+    - [STR](#str)
+    - [ARR](#arr)
+    - [CURL](#curl)
+    - [SCRAPER](#scraper)
+    - [OBF](#obf)
+    - [STD](#std)
+  - [Plugin system](#plugin-system)
+    - [PREPROS tags](#prepros-tags)
+    - [PREPROS hooks](#prepros-hooks)
+    - [MD plugins](#md-plugins)
+    - [Built-in plugins](#built-in-plugins)
+      - [`{% callout type ["Title"] content %}`](#-callout-type-title-content-)
+      - [`{% youtube id [width height] %}`](#-youtube-id-width-height-)
+      - [`{% codepen id [user height] %}`](#-codepen-id-user-height-)
+      - [`{% checklist ["Title"] items %}`](#-checklist-title-items-)
+  - [Extending the `<markdown>` tag](#extending-the-markdown-tag)
+  - [License](#license)
 
 ---
 
+## What's new in 1.1.0
+
+- **`PREPROS::mount()`** — mount extra files into the WASM filesystem on demand, from a glob pattern, at any point during rendering.
+- **`runenv()`** JavaScript export — run an arbitrary PHP script (not a page template) inside the same sandboxed environment, with full access to every `php-prepros` class.
+- **`SCRAPER`** class — fetch a URL and extract `title` / `description` / `image` / `label` from its Open Graph, `<meta>`, and JSON-LD data, with automatic caching.
+- **`CURL`** class — low-level cURL helper used internally by `SCRAPER`, also usable directly (`urlExists()`, `getInfo()`, `getContents()`), with a shared, persisted cookie jar.
+- **`ARR`** class — recursive associative array/object key lookup.
+- **`YAML::loadFile()`** — like `YAML::parseFile()`, but recursively resolves any string value that points to another existing `.yaml`/`.yml`/`.json` file into its parsed content.
+- New `STR` helpers: `STR::is_url()`, `STR::html_entities_decode()`, `STR::shorthash()`, `STR::slug()`.
+- New built-in MD plugins: `{% youtube %}`, `{% codepen %}`, and `{% checklist %}`, alongside the existing `{% callout %}`.
+- `@content` and `@indent` PHPDOC annotations, letting a page skip its own PHP body in favour of pre-rendered content, and control its indentation when nested inside a layout.
+
+---
 
 ## How it works
 
@@ -68,7 +93,7 @@ _index.php  ──▶  PHP (wasm)  ──▶  processTags()  ──▶  HTML::fo
                     └── PHPDOC annotations resolved (yaml / json / md / url)
 ```
 
-Files are mounted into the WebAssembly virtual filesystem on demand. Only `.php`, `.json`, `.yaml`, `.md` and any extra extensions listed in `prepros.mountext` are mounted, keeping memory usage low.
+Files are mounted into the WebAssembly virtual filesystem on demand. Only `.php`, `.json`, `.yaml`, `.yml`, `.md`, `.db`, `.txt` and any extra extensions listed in `prepros.mountext` are mounted automatically, keeping memory usage low. Anything else can be mounted on demand with [`PREPROS::mount()`](#preprosmountstringarray-patterns).
 
 ---
 
@@ -88,24 +113,65 @@ Every project **must** have a `kirigami.yaml` at its root. The preprocessor read
 
 ```yaml
 kirigami:
-  root: src/                # Required. Source directory containing your _*.php pages.
-  baseurl: https://example.com   # Used by sitemap generation.
-  sitename: My Website         # Arbitrary key/value pairs injected as PHP   variables.
-  author:   Jane Doe
+  # ── Required ──────────────────────────────────────────────────────────
+  root:        src                  # Source directory containing your _*.php pages.
+
+  # ── Used internally ──────────────────────────────────────────────────
+  baseurl:     https://example.com  # Used as the base URL when generating sitemap.xml.
+
+  # ── Arbitrary project data ──────────────────────────────────────────
+  # Everything else under `kirigami:` is free-form. The whole block is
+  # extracted as PHP variables and made available in every page, in
+  # before.php/after.php, and anywhere PREPROS::$config->data is read.
+  project:     My Website
+  author:      Jane Doe
+  person:      John Smith
+  jobtitle:    Founder
+  email:       hello@example.com
+  facebook:    https://www.facebook.com/example
+  area:        Somewhere, Country
+  gtag:        G-XXXXXXXXXX
+  banner:      assets/banner.txt
+  description: A short description of the site, useful for <meta name="description">.
+  knowsabout:
+    - Topic one
+    - Topic two
+  keywords:
+    - keyword one
+    - keyword two
 
 prepros:
-  before: _layout/header.php    # Included before every page body.
-  after:  _layout/footer.php    # Included after every page body.
-  format: true                   # Pretty-print the HTML output (default: false).
-  network: false                 # Allow HTTP fetches in PHPDOC @tag annotations.
-  mountext:                      # Extra file extensions to mount into the wasm fs.
-    - .svg
-    - .txt
-  includes:                      # PHP files auto-included before page rendering.
+  before:  _layout/header.php   # Included before every page body.
+  after:   _layout/footer.php   # Included after every page body.
+  format:  true                 # Pretty-print the HTML output (default: false).
+  network: false                # Allow HTTP fetches in PHPDOC @tag annotations.
+  mountext:                     # Extra file extensions to auto-mount into the wasm fs,
+    - .svg                      # in addition to the defaults (.php .json .yaml .yml .md .db .txt).
+    - .webp
+  includes:                     # PHP files auto-included once, before any page renders.
     - _lib/helpers.php
 ```
 
-The entire `kirigami` block is extracted into PHP variables and made available in every page template. `$sitename`, `$author`, etc. are available without any further setup.
+### `kirigami` block
+
+| Key | Required | Description |
+|-----|----------|--------------|
+| `root` | ✅ | Path (relative to the project root) to the directory containing your `_*.php` source pages. Build fails immediately if missing or if the path doesn't exist. |
+| `baseurl` | for `sitemap()` | Root URL used to build absolute `<loc>` entries when generating `sitemap.xml`. |
+| *anything else* | — | Free-form key/value pairs (strings, numbers, booleans, lists, nested maps — anything valid YAML). Every key is extracted as a PHP variable (`$project`, `$author`, `$gtag`, …) and available in page templates, `before.php`, `after.php`, and PHP files listed under `prepros.includes`. Use this to hold your site name, contact info, social links, analytics IDs, SEO keywords, banners, or any project-specific data you want available everywhere. |
+
+### `prepros` block
+
+| Key | Type | Default | Description |
+|-----|------|---------|--------------|
+| `before` | `string` | — | Path (relative to `kirigami.root`) to a PHP file included **before** every page's body. Typically your `<head>`/layout opening. |
+| `after` | `string` | — | Path (relative to `kirigami.root`) to a PHP file included **after** every page's body. Typically your layout closing. |
+| `format` | `bool` | `false` | Pretty-print the compiled HTML via [`HTML::format()`](#html) before writing it to disk. |
+| `network` | `bool` | `false` | Enables outbound HTTP(S) inside the WASM PHP runtime. Required for PHPDOC `@tag https://…` annotations that fetch remote `.yaml`/`.json`/`.md` data (see [Auto-loading data files](#auto-loading-data-files)). |
+| `mountext` | `string[]` | `[]` | Extra file extensions to mount automatically into the virtual filesystem alongside the built-in `.php`, `.json`, `.yaml`, `.yml`, `.md`, `.db`, `.txt`. Use this for assets your PHP code reads directly (e.g. `.svg`, `.txt`, `.webp`). Files with extensions not in this set are simply skipped during mounting — mount them on demand with [`PREPROS::mount()`](#preprosmountstringarray-patterns) instead. |
+| `includes` | `string[]` | `[]` | PHP files (relative to `kirigami.root`) `include_once`'d once, right after config is loaded — before any page renders. The natural place to `PREPROS::registerTag()`, `PREPROS::registerHook()`, or `MD::registerPlugin()`. |
+
+The entire `kirigami` block is extracted into PHP variables and made available in every page template, `before.php`, and `after.php`. `$project`, `$author`, `$gtag`, etc. are available without any further setup.
 
 ---
 
@@ -148,7 +214,7 @@ Every page starts with a PHP docblock that drives metadata and data loading:
 
 All annotations are injected as PHP variables (`$name`, `$title`, `$abstract`, …). You can define any custom annotation you need.
 
-Anotations are also avaiables as variables in `before` and `after` php included files so you can write proper metas in the HTML header.
+Annotations are also available as variables in `before` and `after` PHP included files, so you can write proper metas in the HTML header.
 
 ### Auto-loading data files
 
@@ -182,12 +248,29 @@ When `network: true` is set in `kirigami.yaml`, annotation values that start wit
  */
 ```
 
+### `@content` and `@indent`
+
+Two special annotation names change how a page's body is assembled:
+
+- **`@content`** — if a `content` variable already resolves to a non-empty value (typically because it's a `.md`/`.yaml`/`.json` annotation that auto-loaded into HTML/data, see above), it is used **as-is** as the page body, and the PHP file itself is **not executed** for its output. This is handy for pages that are pure data/markdown wrapped by a shared layout.
+- **`@indent`** — when set to a number, every line of the rendered body is prefixed with that many spaces before being wrapped by `before.php`/`after.php`. Useful for keeping generated HTML readable when a page is nested inside indented layout markup.
+
+```php
+<?php
+/**
+ * @name    changelog
+ * @title   Changelog
+ * @content _changelog.md
+ * @indent  4
+ */
+```
+
 ---
 
 ## JavaScript API
 
 ```js
-import { render, sitemap } from '@kirigami/php-prepros';
+import { render, sitemap, runenv } from '@kirigami/php-prepros';
 ```
 
 ### `render(file?)`
@@ -204,7 +287,7 @@ const result = await render('.');
 // Compile everything (uses kirigami.root from config)
 const result = await render();
 ```
-> Path use by `render()` are all relative to `kirigami.root` configuration.
+> Paths used by `render()` are all relative to the `kirigami.root` configuration.
 
 
 **Returns** `Promise<PreprosResult>`:
@@ -226,6 +309,27 @@ const result = await sitemap();
 // result.files === ['src/sitemap.xml']
 ```
 
+### `runenv(script, paths?, ...args)`
+
+Run an arbitrary PHP script — not a page template — inside the very same sandboxed WASM environment used for `render()`, with the full `php-prepros` class library autoloaded and `kirigami.yaml`'s `kirigami` block available as `PREPROS::$config->data`. Useful for one-off maintenance scripts, data migrations, or CLI-style tooling that needs `CACHE`, `SCRAPER`, `IMG`, etc. without going through the page-rendering pipeline.
+
+```js
+// Run a standalone PHP script
+const result = await runenv('scripts/purge-cache.php');
+
+// Also mount extra local paths/files into the sandbox before running
+const result = await runenv('scripts/build-og-images.php', ['assets/photos']);
+
+// Extra arguments are appended and available as $argv[2], $argv[3], … in the script
+const result = await runenv('scripts/import.php', [], '--force');
+```
+
+- `script` — path to a PHP file **inside the project**, executed with `require_once`.
+- `paths` — optional array of extra local paths (files or directories) to mount into the sandbox before the script runs.
+- `...args` — extra string arguments appended to the script's `$argv`.
+
+**Returns** `Promise<PreprosResult>`, following the same shape as `render()`. Inside the script, call `PREPROS::exportFile()` for any file you want listed in `result.files`.
+
 ---
 
 ## PHP classes reference
@@ -236,13 +340,14 @@ All classes are autoloaded — no manual `require` needed inside your page files
 
 ### PREPROS
 
-The core engine. Manages the rendering pipeline, tag processing, hooks, and file export.
+The core engine. Manages the rendering pipeline, tag processing, hooks, mounting, and file export.
 
 ```php
 // Available inside page templates and included files.
 PREPROS::$config          // stdClass — full resolved config (prepros section of kirigami.yaml)
 PREPROS::registerTag(string $tag, callable $callback)
 PREPROS::registerHook(string $hook, callable $callback)
+PREPROS::mount(string|array $patterns)
 PREPROS::exportFile(string $absolutePath)
 PREPROS::getExportedFiles(): string[]
 ```
@@ -253,7 +358,7 @@ Internal method called once per source file. Orchestrates the full pipeline:
 
 1. Resolves PHPDOC metadata and auto-loads data files.
 2. Fires the `pre_render` hook with the raw source contents.
-3. Includes `before.php`, the page body, and `after.php` into a single string.
+3. Includes `before.php`, the page body (or `@content`, see [above](#content-and-indent)), and `after.php` into a single string.
 4. Processes all registered custom HTML tags.
 5. Fires the `post_render` hook on the assembled HTML.
 6. Optionally pretty-prints via `HTML::format()` (when `format: true`).
@@ -261,11 +366,25 @@ Internal method called once per source file. Orchestrates the full pipeline:
 
 #### `PREPROS::sitemap()`
 
-Scans the source tree for `_index.php` files and generates a standards-compliant `sitemap.xml` (Sitemaps 0.9).
+Scans the source tree for `_index.php` files and generates a standards-compliant `sitemap.xml` (Sitemaps 0.9), using `kirigami.baseurl` as the root URL.
+
+#### `PREPROS::mount(string|array $patterns)`
+
+Mounts additional local project files into the WASM virtual filesystem, on demand, from one or more glob patterns evaluated against the project root (via `picomatch`). Unlike the automatic mounting done for `kirigami.root` (limited to `.php`, `.json`, `.yaml`, `.yml`, `.md`, `.db`, `.txt`, and `prepros.mountext`), `mount()` copies **any** matching file, regardless of extension.
+
+```php
+// Mount every .webp under assets/, wherever the page needs them
+PREPROS::mount('assets/**/*.webp');
+
+// Multiple patterns at once
+PREPROS::mount(['data/**/*.csv', 'vendor/fonts/*.woff2']);
+```
+
+Returns an array of the virtual paths (under `/project/...`) that were mounted, or `false` on failure.
 
 #### `PREPROS::exportFile(string $file)`
 
-Marks a file as a build output so it gets surfaced in `PreprosResult.files`. Called automatically by `render()`, `sitemap()`, `CACHE::set()`, and `IMG::save()`. Call it manually if your custom code writes additional files.
+Marks a file as a build output so it gets surfaced in `PreprosResult.files`. Called automatically by `render()`, `sitemap()`, `CACHE::set()`, and `CURL`. Call it manually if your custom code writes additional files.
 
 ---
 
@@ -345,6 +464,7 @@ A lightweight, zero-dependency YAML parser. Covers the full subset used in stati
 ```php
 $data = YAML::parse(string $yaml, bool $assoc = false): mixed;
 $data = YAML::parseFile(string $path, bool $assoc = false): mixed;
+$data = YAML::loadFile(string $path, bool $assoc = false): mixed;
 ```
 
 Supported features:
@@ -361,6 +481,21 @@ Supported features:
 
 By default, YAML mappings are returned as `stdClass` objects. Pass `true` as the second argument to get associative arrays instead.
 
+`YAML::loadFile()` behaves like `YAML::parseFile()`, then walks the result recursively: any string value ending in `.yaml`, `.yml`, or `.json` that resolves to an existing file (relative to *its own* file's directory) is replaced by that file's parsed content, and so on, recursively. Values that don't match an existing file are left untouched. Circular references (`A → B → A`) throw a `RuntimeException`.
+
+```yaml
+# team.yaml
+lead: people/jane.yaml     # resolved and inlined automatically
+members:
+  - people/jane.yaml
+  - people/john.yaml
+```
+
+```php
+$team = YAML::loadFile('/project/data/team.yaml');
+// $team->lead is now the fully parsed content of people/jane.yaml, not a string
+```
+
 ---
 
 ### CACHE
@@ -374,7 +509,7 @@ CACHE::delete(string $key): bool
 CACHE::purge(): bool   // removes expired entries
 ```
 
-The `$ttl` is in seconds. `0` means the entry never expires. Typical use case: caching the result of network fetches in custom hooks or plugins.
+The `$ttl` is in seconds. `0` means the entry never expires. Typical use case: caching the result of network fetches in custom hooks or plugins — it is what powers [`SCRAPER`](#scraper) and `CURL`'s cookie persistence internally.
 
 ```php
 $data = CACHE::get('my-remote-data');
@@ -404,7 +539,7 @@ $img->save(string $dest): self
 
 `resize()` operates in *contain* mode by default (scales to fit within the target box while preserving aspect ratio). Pass `$cover = true` to crop and fill the exact target dimensions.
 
-`save()` infers the output format from the file extension (`.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`). The saved file is automatically registered via `PREPROS::exportFile()`.
+`save()` infers the output format from the file extension (`.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`).
 
 ```php
 (new IMG('/project/src/images/hero.jpg'))
@@ -434,19 +569,95 @@ FS::pathJoin(string ...$parts): string   // URL-aware path join with .. resoluti
 
 ### STR
 
-String utilities used internally by the tag-processing pipeline.
+String utilities used internally by the tag-processing pipeline, and available for your own templates and plugins.
 
 ```php
 STR::htmlesc(string $str): string
 STR::replaceTags(string $tag, string $html, callable $callback): string
 STR::parseHtmlAttributes(string $attrString): array
 STR::trimIndent(string $str): string
+STR::is_url(string $str): bool
+STR::html_entities_decode(string $str): string
+STR::shorthash(string $str): string
+STR::slug(string $str): string
 ```
 
 `STR::replaceTags()` is the engine behind `PREPROS::registerTag()`. It finds all occurrences of `<tagname ...>...</tagname>` in an HTML string and replaces each with the return value of `$callback($fullMatch, $attrs, $body)`.
 
 `STR::trimIndent()` strips the common leading whitespace from a multi-line string — handy when pulling content out of indented `<markdown>` blocks.
 
+`STR::is_url()` checks whether a string parses as a URL with a recognized scheme (`http`, `https`, `ftp`, `ftps`, `ssh`, `ssl`, `sftp`, `itunes`).
+
+`STR::html_entities_decode()` trims a string and decodes its HTML entities — handy when normalizing text scraped from a third-party page.
+
+`STR::shorthash()` returns the first 12 characters of a string's SHA-256 hash — used internally as a stable, filename-safe cache key (see `SCRAPER`).
+
+`STR::slug()` transliterates a string to ASCII, lowercases it, and strips anything that isn't `[a-z0-9]` — a compact identifier rather than a hyphenated slug.
+
+---
+
+### ARR
+
+Recursive lookup helper for nested arrays and objects.
+
+```php
+ARR::find_key(mixed $data, string $key): mixed
+```
+
+Walks an array or object (including mixed nested `stdClass`/array structures, as produced by `YAML::parse()` or `json_decode()`) depth-first and returns the value of the **first** matching key found, at any depth, or `null` if none matches.
+
+```php
+$config = YAML::parseFile('team.yaml');
+$email  = ARR::find_key($config, 'email'); // finds `email` however deep it's nested
+```
+
+---
+
+### CURL
+
+Low-level HTTP client built on PHP's cURL extension, used internally by `SCRAPER`. Ships with a realistic browser `User-Agent`/header set and a cookie jar persisted at `.cookie.txt` (auto-registered via `PREPROS::exportFile()`).
+
+```php
+CURL::urlExists(string $url, ?string $mimereg = null): bool
+CURL::getInfo(string $url): array|false     // HEAD request, returns curl_getinfo()
+CURL::getContents(string $file, ?string $dest = null, ?callable $clb = null): string|bool
+```
+
+`CURL::urlExists()` issues a `HEAD` request and returns `true` for any `2xx`/`3xx` response.
+
+`CURL::getContents()` downloads a URL. Without `$dest`, it returns the body as a string; with `$dest`, it streams the download to that file path and returns a boolean. Pass `$clb` to receive download progress as a float between `0` and `1`.
+
+```php
+CURL::getContents('https://example.com/report.pdf', '/project/src/downloads/report.pdf', function (float $progress) {
+    error_log(sprintf('%.0f%%', $progress * 100));
+});
+```
+
+---
+
+### SCRAPER
+
+Fetches a URL and extracts page metadata (`title`, `description`, `image`, `label`) from its JSON-LD (`schema.org`), Open Graph, and standard `<meta>` tags — the kind of data you'd want for a rich link preview. Results are cached indefinitely via `CACHE`, keyed on the URL.
+
+```php
+$metas = SCRAPER::get(string $url): object|false;
+```
+
+```php
+$metas = SCRAPER::get('https://example.com/blog/some-article');
+if ($metas) {
+    echo $metas->title;        // string
+    echo $metas->description;  // string
+    echo $metas->image;        // string (absolute URL, may be empty)
+    echo $metas->label;        // string — site/publisher name, may be empty
+    echo $metas->url;          // string — the URL that was scraped
+}
+```
+
+Returns `false` if the page can't be reached, can't be parsed, or has no discoverable title. Throws an `Exception` on invalid URLs. Uses `CURL::getContents()` under the hood, so it benefits from the same shared cookie jar and browser-like headers.
+
+A free `url_exists(string $url, ?string $mimereg = null): bool` function is also available globally (not namespaced under a class), cached the same way as `SCRAPER::get()`.
+
 ---
 
 ### OBF
@@ -471,7 +682,7 @@ STD::succeed(array|string $props = []): void  // exits 0, writes JSON to stdout
 STD::error(array|string $props = []): void    // exits 1, writes JSON to stderr
 ```
 
-These are internal to the build runner. You generally do not need to call them in page templates.
+These are internal to the build runner (`render()`, `sitemap()`, and `runenv()` all rely on them). You generally do not need to call them in page templates, but they are available if a script run via `runenv()` needs to terminate early with a custom result.
 
 ---
 
@@ -528,7 +739,7 @@ PREPROS::registerHook(string $hookName, callable $callback): void
 
 | Hook | When it fires | `$data` type | Expected return |
 |------|---------------|--------------|-----------------|
-| `page_info` | After PHPDOC parsing, before rendering | `[$filePath, $pageObject]` | `$pageObject` (modified) |
+| `page_info` | After PHPDOC parsing, before rendering (auto-loads `.yaml`/`.json`/`.md` annotations) | `[$filePath, $pageObject]` | `$pageObject` (modified) |
 | `pre_render` | Before PHP execution | Raw file contents as `string` | `string` |
 | `post_render` | After tag processing, before `HTML::format()` | Assembled HTML `string` | `string` |
 
@@ -589,6 +800,36 @@ Line two after a blank line.
 %}
 ```
 
+#### `{% youtube id [width height] %}`
+
+Embeds a responsive YouTube player via `<iframe>`. `width`/`height` default to `560`/`315`.
+
+```
+{% youtube dQw4w9WgXcQ %}
+{% youtube dQw4w9WgXcQ 800 450 %}
+```
+
+#### `{% codepen id [user height] %}`
+
+Embeds a CodePen result via `<iframe>`. `user` defaults to `anonymous`, `height` defaults to `400`.
+
+```
+{% codepen abcXYZ %}
+{% codepen abcXYZ jsmith 500 %}
+```
+
+#### `{% checklist ["Title"] items %}`
+
+Renders a block-syntax list of checkbox items, one per line, with an optional title.
+
+```
+{% checklist "Today"
+Do the dishes
+Walk the dog
+Read a book
+%}
+```
+
 ---
 
 ## Extending the `<markdown>` tag

package/index.js

@@ -1 +1 @@
-export { render, sitemap } from "./src/prepros.js";
+export { render, sitemap, runenv } from "./src/prepros.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kirigami/php-prepros",
-  "version": "1.0.9",
+  "version": "1.1.0",
   "description": "PHP preprocessor for the Kirigami static site generator. Compile PHP page templates to clean, deployable HTML — with zero server dependency.",
   "keywords": [
     "kirigami",
@@ -44,8 +44,9 @@
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "dependencies": {
-    "@kirigami/php-wasm": "8.5.10-2",
-    "@kirigami/struct-walker": "1.0.3"
+    "@kirigami/php-wasm": "8.5.10-3",
+    "@kirigami/struct-walker": "1.0.3",
+    "picomatch": "^4.0.7"
   },
   "repository": {
     "type": "git",

package/src/libraries/arr.class.php

@@ -0,0 +1,29 @@
+<?php
+
+
+class ARR
+{
+    public static function find_key(mixed $data, string $key)
+    {
+        if (is_object($data)) {
+            $data = (array) $data;
+        }
+
+        if (is_array($data)) {
+            foreach ($data as $k => $value) {
+                if ($k === $key) {
+                    return $value;
+                }
+
+                if (is_array($value) || is_object($value)) {
+                    $found = ARR::find_key($value, $key);
+                    if ($found !== null) {
+                        return $found;
+                    }
+                }
+            }
+        }
+
+        return null;
+    }
+}

package/src/libraries/cache.class.php

@@ -13,10 +13,7 @@ class CACHE
         static $db = null;
         if($db !== null) return $db;
 
-        if(!empty($_SERVER['NODE_PROJECT'])) $root = $_SERVER['NODE_PROJECT'] . '/';
-        elseif(!empty(PREPROS::$config->root)) $root = rtrim(PREPROS::$config->root, '/') . '/';
-        else throw new Exception("Can't find project root.");
-        
+
         if(!is_file(($dbfile = self::getPath()))) $create = true;
         if(!$db = new SQLite3($dbfile)) throw new Exception("Can't open .cache.db.");
         
@@ -36,6 +33,10 @@ class CACHE
 
 
     private static function getPath() {
+        // if(!empty($_SERVER['NODE_PROJECT'])) $root = $_SERVER['NODE_PROJECT'] . '/';
+        // elseif(!empty(PREPROS::$config->root)) $root = rtrim(PREPROS::$config->root, '/') . '/';
+        // else throw new Exception("Can't find project root.");
+        // return $root . '.cache.db';
         return '/project/.cache.db';
     }