@kirigami/php-prepros 1.6.1 → 1.7.1

package/README.md

@@ -34,6 +34,8 @@ Part of the **Kirigami** project ecosystem.
 - [@kirigami/php-prepros](#kirigamiphp-prepros)
   - [Overview](#overview)
   - [Table of contents](#table-of-contents)
+  - [What's new in 1.7.1](#whats-new-in-171)
+  - [What's new in 1.7.0](#whats-new-in-170)
   - [What's new in 1.6.0](#whats-new-in-160)
   - [What's new in 1.4.0](#whats-new-in-140)
   - [What's new in 1.3.0](#whats-new-in-130)
@@ -44,6 +46,7 @@ Part of the **Kirigami** project ecosystem.
   - [Configuration — `kirigami.yaml`](#configuration--kirigamiyaml)
     - [`kirigami` block](#kirigami-block)
     - [`jsonld` block](#jsonld-block)
+    - [`meta` block](#meta-block)
     - [`prepros` block](#prepros-block)
     - [`image` block](#image-block)
     - [`plugins` block](#plugins-block)
@@ -77,6 +80,8 @@ Part of the **Kirigami** project ecosystem.
       - [Automatic mode](#automatic-mode)
       - [Explicit builders](#explicit-builders)
       - [`jsonld` config](#jsonld-config)
+    - [META](#meta)
+      - [`meta` config](#meta-config)
     - [CACHE](#cache)
     - [IMG](#img)
     - [FS](#fs)
@@ -103,6 +108,40 @@ Part of the **Kirigami** project ecosystem.
 
 ---
 
+## What's new in 1.7.1
+
+- **No side effects on import.** `kirigami.yaml` is now loaded on first use
+  (`render()` / `sitemap()` / `runenv()` / `processImages()`), not while the
+  module is being imported. `import '@kirigami/php-prepros'` from a directory
+  with no project no longer throws — which is what made `kiri build --help` /
+  `kiri export --help` / `kiri run --help` crash instead of printing their help.
+
+---
+
+## What's new in 1.7.0
+
+- **`META`** class — a `<head>` SEO / social metadata generator, the companion
+  to [`LD`](#ld). Builds the standard tags — `<title>`, `description`,
+  `keywords`, `robots`, `language`, `generator`, `author`, Open Graph, Twitter
+  Card, `<link rel="canonical">`, favicon / apple-touch-icon / humans — from
+  each page's PHPDOC, the top-level `meta:` block, and the loose `kirigami:` /
+  `jsonld:` keys `LD` already reads. It emits only what it can resolve, and
+  leaves any tag the layout already hand-writes untouched.
+
+  - **Opt-in**: a top-level `meta:` block (empty `meta: {}` is enough) switches
+    on automatic injection into every page's `<head>`. `meta: false` (or
+    `{ auto: false }`) keeps the config but stops the injection.
+  - Per-page PHPDOC: `@meta false` (skip), `@meta_title`, `@meta_description`
+    (falls back to `@description` / `@abstract` / `@excerpt`), `@meta_keywords`,
+    `@meta_image`, `@meta_robots`, `@meta_type`, `@canonical`.
+  - Manual builders — always emitted, still de-duplicated: `META::tag()`,
+    `META::link()`, `META::raw()`, `META::tags()`. Procedural aliases:
+    `meta_tag()`, `meta_link()`, `meta_raw()`, `meta_tags()`.
+
+  Full key reference: [`META` → `meta` config](#meta-config).
+
+---
+
 ## What's new in 1.6.0
 
 - **Managed `<head>` (`prepros.head`).** Every rendered page's `<head>` is now
@@ -371,6 +410,19 @@ otherwise infers from the `kirigami` block and each page's PHPDOC. `jsonld: fals
 no block at all means nothing is injected. Full key reference and per-page
 `@ld_*` tags: [`LD` → `jsonld` config](#jsonld-config).
 
+### `meta` block
+
+Top-level, optional. Its **presence** switches on the [`META`](#meta) generator —
+the standard SEO / social `<meta>` and `<link>` tags are then built for every
+page and injected into its `<head>`. An empty `meta: {}` is enough; everything is
+derived from the `kirigami` block, the `jsonld` block, and each page's PHPDOC
+(`@title`, `@description` / `@abstract`, `@keywords`, `@image`, `@robots`,
+`@og_type`, `@canonical`). Keys refine those inferences. A tag the layout already
+hand-writes is left untouched. `meta: false` (or `meta: { auto: false }`) keeps
+the config values but stops the injection; no block at all means nothing is
+injected (explicit `META::tag()` / `meta_tag()` calls still emit). Full key
+reference and per-page `@meta_*` tags: [`META` → `meta` config](#meta-config).
+
 ### `prepros` block
 
 Options for the PHP → HTML compiler. **Read by `php-prepros`.** Declaring this block (even empty) also makes `kiri` prepend a forced `prepros` task on every build/export/watch.
@@ -1095,6 +1147,96 @@ jsonld:                                   # top-level; the block being present i
 
 ---
 
+### META
+
+A **`<head>` SEO / social metadata generator** — the companion to [`LD`](#ld).
+Where `LD` emits a schema.org `application/ld+json` graph, `META` emits the plain
+tags a browser and a link-preview crawler read: `<title>`, `<meta name="…">`,
+`<meta property="og:…">`, `<meta name="twitter:…">`, and a handful of `<link>`s.
+
+It draws on the same sources, in this order of precedence: the page's PHPDOC, the
+top-level `meta:` block, then the loose `kirigami:` keys and the `jsonld:` block.
+Every tag is emitted **only when it can be resolved** — no value, no tag — and a
+tag the page's layout already writes by hand is detected and skipped, so it drops
+in beside an existing `header.php` without duplicating anything.
+
+**Automatic mode** is opt-in: the top-level `meta:` block (empty `meta: {}` is
+enough) turns on injection into every page's `<head>`, right before `</head>`.
+
+```yaml
+kirigami:
+  project:     Humain Humain
+  baseurl:     https://humainhumain.com
+  tagline:     Ethnographie au service des organisations
+  description: A social-science consultancy using ethnography for organisational change.
+  keywords:    [ethnographie, consultation publique, sciences sociales]
+  author:      Maxime Larrivée-Roy
+
+jsonld:  {}                       # META reads its logo / image / lang / person too
+meta:                             # top-level; the block being present is the switch
+  twitter: "@humainhumain"
+  themeColor: "#0b7285"
+```
+
+Per-page, from the PHPDOC block — each falls back to the generic page tag:
+
+| Tag | Feeds | Default |
+|-----|-------|---------|
+| `@meta false` | skip metadata for this page entirely | — (`@meta_ignore true` also works) |
+| `@meta_title` | `<title>`, `og:title`, `twitter:title` | `@title` |
+| `@meta_description` | `description`, `og:description`, `twitter:description` | `@description` / `@abstract` / `@excerpt` / `@summary`, then the site `description` |
+| `@meta_keywords` | `<meta name="keywords">` | `@keywords`, then `meta.keywords` |
+| `@meta_image` | `og:image`, `twitter:image` | `@image` / `@ogimage`, then `meta.image` |
+| `@meta_robots` | `<meta name="robots">` | `@robots`, then `meta.robots` |
+| `@meta_type` | `og:type` | `@og_type`, then `meta.ogType` |
+| `@canonical` | `<link rel="canonical">` | derived from the file path + `baseurl` |
+
+**Manual builders** — always emitted (with or without a `meta:` block), still
+de-duplicated against the page:
+
+```php
+META::tag(string $name, ?string $content): void   // name= , or property= for an og:* key
+META::link(string $rel, string $href, array $attrs = []): void
+META::raw(string $html): void                       // a verbatim, already-valid tag line
+META::tags(string $html = ''): string               // the whole block, \n-joined
+META::reset(): void
+```
+
+```php
+META::tag('twitter:image', 'https://humainhumain.com/card.png');
+META::tag('og:image:alt', 'The Humain Humain team at work');
+META::link('icon', './favicon.svg', ['type' => 'image/svg+xml']);
+```
+
+Same API from procedural code: `meta_tag()`, `meta_link()`, `meta_raw()`,
+`meta_tags()`.
+
+#### `meta` config
+
+`meta:` is a **top-level** block of `kirigami.yaml` (a sibling of `kirigami:`,
+`jsonld:`, `prepros:`, …). All keys are optional.
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `auto` | `bool` | Inject the tags automatically. Default `true` **once the `meta:` block exists**. `auto: false` (or `meta: false`) keeps the block for its values but stops the injection — `META::tags()` / `meta_tags()` can place them by hand. |
+| `titleFormat` | `string` | `<title>` template for a normal page. Tokens `{title}`, `{project}`, `{tagline}`. Dangling separators from an empty token are trimmed. Default `{title} — {project}`. |
+| `titleFormatHome` | `string` | Title template when the page has no `@title` (home / section landings). Default `{project} — {tagline}`. |
+| `description` | `string` | Default description for pages with no `@description` / `@abstract`. Defaults to the `jsonld` / loose `description`. |
+| `keywords` | `string[]` \| `string` | Default `keywords` content (list or comma string). Defaults to the `jsonld` / loose `keywords`. |
+| `robots` | `string` | Default robots directive. Default `index, follow`. `robots: false` omits the tag. |
+| `language` | `string` | BCP-47 tag → `<meta name="language">` and, dash→underscore, `og:locale`. Defaults to `jsonld.lang` / loose `lang` / `language`, then `en`. |
+| `generator` | `string` \| `false` | `<meta name="generator">`. Default `Kirigami`; `false` omits it. |
+| `author` / `designer` | `string` | Default to the loose `author` / `designer` keys (author also falls back to the `jsonld` person's name). `designer` is not emitted unless set. |
+| `themeColor` | `string` | `<meta name="theme-color">`. Not emitted unless set. |
+| `image` | `string` | Default `og:image` / `twitter:image` — absolute URL or path relative to `baseurl`. Defaults to `jsonld.image` → `jsonld.logo` → loose `image` / `ogimage`. |
+| `ogType` | `string` | Default `og:type`. Default `website`. |
+| `twitterCard` | `string` | `twitter:card` type. Default `summary_large_image`. |
+| `twitter` | `string` \| `map` | Handle for `twitter:site` / `twitter:creator`. A bare string (with/without `@`, or a profile URL) fills both; a map takes `site` / `creator` separately. |
+| `canonical` | `bool` | Emit `<link rel="canonical">`. Default `true`. |
+| `favicon` / `appleTouchIcon` / `humans` | `string` \| `bool` | `<link rel="icon">` / `rel="apple-touch-icon"` / `rel="author"`. A path sets it (page-relative when a bare filename); `true` forces the default file (`favicon.ico` / `apple-touch-icon.png` / `humans.txt`); omitted, the default file is auto-detected on disk at the source root; `false` disables it. |
+
+---
+
 ### CACHE
 
 Persistent SQLite-backed key-value cache. Survives across incremental builds via `.cache.db` at the project root.
@@ -1364,6 +1506,7 @@ surface the signature, parameters, and description.
 | `YAML` | `yaml_parse` · `yaml_parse_file` · `yaml_load_file` |
 | `SCHEMA` | `schema` (factory) · `schema_validate` |
 | `LD` | `ld_add` · `ld_node` · `ld_ref` · `ld_organization` · `ld_person` · `ld_website` · `ld_web_page` · `ld_breadcrumb` · `ld_faq_page` · `ld_script` · `ld_json` |
+| `META` | `meta_tag` · `meta_link` · `meta_raw` · `meta_tags` |
 | `CACHE` | `cache_get` · `cache_set` · `cache_delete` · `cache_purge` |
 | `IMG` | `img_asset` · `img_palette` |
 | `FS` | `fs_dig` · `fs_get_relative_path` · `fs_php_file_info` · `fs_rmdir` · `fs_path_join` |
@@ -1452,6 +1595,11 @@ PREPROS::registerHook(string $hookName, callable $callback): void
 
 Multiple callbacks can be registered for the same hook — they are executed in registration order, each receiving the return value of the previous one.
 
+> Built-in `page_info` + `post_render` callbacks power [`LD`](#ld) and
+> [`META`](#meta): `page_info` captures the page under render, `post_render`
+> injects the JSON-LD `<script>` and the `<meta>`/`<link>` block into its
+> `<head>`. Your own callbacks run after them.
+
 > **`page_info` payload shape.** The hook *fires* with `[$filePath, $pageObject]`,
 > but each callback is expected to return the `$pageObject` alone — so a callback
 > registered after the built-ins receives the bare object, not the pair. Handle

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kirigami/php-prepros",
-  "version": "1.6.1",
+  "version": "1.7.1",
   "description": "PHP preprocessor for the Kirigami static site generator. Compile PHP page templates to clean, deployable HTML — with zero server dependency.",
   "keywords": [
     "kirigami",

package/src/libraries/aliases.inc.php

@@ -425,6 +425,49 @@ function ld_script(bool $pretty = true): string { return LD::script($pretty); }
 function ld_json(bool $pretty = true): string { return LD::json($pretty); }
 
 
+// ===========================================================================
+// META — <head> SEO / social metadata generator
+// ===========================================================================
+
+/**
+ * Adds a `<meta>` tag to the page's `<head>`. The key picks the attribute:
+ * `og:*` → `property=`, everything else → `name=`. An empty value is a no-op.
+ * Always emitted (and de-duplicated against the page), `meta:` block or not.
+ *
+ *   meta_tag('twitter:image', 'https://…/card.png');
+ *
+ * @see META::tag()
+ */
+function meta_tag(string $name, ?string $content): void { META::tag($name, $content); }
+
+/**
+ * Adds a `<link>` tag to the page's `<head>`. `$attrs` are extra attributes
+ * (`type`, `sizes`, `hreflang`, …).
+ *
+ *   meta_link('icon', './favicon.svg', ['type' => 'image/svg+xml']);
+ *
+ * @param  array<string,string|int|bool|null> $attrs
+ * @see    META::link()
+ */
+function meta_link(string $rel, string $href, array $attrs = []): void { META::link($rel, $href, $attrs); }
+
+/**
+ * Adds a verbatim tag line (already valid HTML) to the page's `<head>`.
+ *
+ * @see META::raw()
+ */
+function meta_raw(string $html): void { META::raw($html); }
+
+/**
+ * The full block of generated `<meta>`/`<link>` lines for the current page,
+ * `\n`-joined, or `''`. Calling this places the block by hand.
+ *
+ * @param  string $html Page HTML, used only to skip tags it already carries.
+ * @see    META::tags()
+ */
+function meta_tags(string $html = ''): string { return META::tags($html); }
+
+
 // ===========================================================================
 // CACHE — persistent key/value (SQLite, `.cache.db` at the project root)
 // ===========================================================================

package/src/libraries/meta.class.php

@@ -0,0 +1,506 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * META — `<head>` metadata generator.
+ *
+ * Builds the standard SEO / social `<meta>` and `<link>` tags for a page and
+ * injects them into its `<head>`, from three sources, in this order of
+ * precedence:
+ *
+ *   1. the page's own PHPDOC block (`@title`, `@description`, `@image`, …),
+ *   2. the top-level `meta:` block of `kirigami.yaml` (config + overrides),
+ *   3. the loose keys of the `kirigami:` block and the top-level `jsonld:`
+ *      block (`description`, `keywords`, `author`, `person`, `lang`, `logo`,
+ *      `image`, …) — the same values `LD` already reads.
+ *
+ * It only ever emits what it can resolve: a tag with no value is skipped, and a
+ * tag the page's layout already hand-writes (`<title>`, `<meta name="description">`,
+ * `<link rel="canonical">`, …) is left untouched — so it slots in next to an
+ * existing `header.php` without doubling anything up.
+ *
+ * Automatic injection is **opt-in**: it needs a top-level `meta:` block (an
+ * empty map, `meta: {}`, is enough). `meta: false` (or `meta: { auto: false }`)
+ * keeps the config values but stops the injection; no block at all means
+ * nothing is injected — an explicit `META::tag()` call from a template still
+ * emits.
+ *
+ * Per-page PHPDOC tags, each falling back to the generic page tag:
+ *
+ *   @meta false            skip metadata for this page (or @meta_ignore true)
+ *   @meta_title <text>     <title> / og:title / twitter:title  (default @title)
+ *   @meta_description …    description / og / twitter           (default @description / @abstract / @excerpt)
+ *   @meta_keywords a, b    <meta name="keywords">               (default @keywords)
+ *   @meta_image <path>     og:image / twitter:image             (default @image / @ogimage)
+ *   @meta_robots <rule>    <meta name="robots">                 (default @robots)
+ *   @meta_type <type>      og:type                              (default @og_type)
+ *   @canonical <url>       <link rel="canonical">               (default: derived from the file path + baseurl)
+ *
+ * Manual use from a template or an `includes` file — always emitted, `meta:`
+ * block or not, and still de-duplicated against the page:
+ *
+ *   META::tag('twitter:image', 'https://…/card.png');   // name= or property= picked from the key
+ *   META::link('icon', './favicon.svg', ['type' => 'image/svg+xml']);
+ *   META::raw('<meta name="rating" content="general">');
+ */
+final class META
+{
+    /** Resolved config, once per process. */
+    private static ?object $config = null;
+
+    /** @var array{file:?string,info:object}|null Page context from the `page_info` hook. */
+    private static ?array $page = null;
+
+    /** True once inject()/tags() has run, so the injector does not emit twice. */
+    private static bool $emitted = false;
+
+    /** @var string[] Ready-made tag lines added by hand from a template. */
+    private static array $extra = [];
+
+
+    // -----------------------------------------------------------------------
+    // Configuration
+    // -----------------------------------------------------------------------
+
+    /**
+     * Resolved metadata configuration, merging the `meta:` block with the loose
+     * keys of the `kirigami:` block and the `jsonld:` block.
+     */
+    public static function config(): object
+    {
+        if (self::$config !== null) return self::$config;
+
+        $data = self::data();
+        $raw  = self::metaRaw();
+        $m    = is_object($raw) ? $raw : new stdClass;
+        $ld   = self::jsonld();
+
+        // Opt-in: needs a top-level `meta:` block (an empty map counts).
+        $enabled = is_object($raw) || $raw === true;
+        if ($enabled && isset($m->auto) && !self::truthy($m->auto)) $enabled = false;
+
+        $lang = $m->language ?? $m->lang
+            ?? ($ld->lang ?? null)
+            ?? $data->lang ?? $data->language ?? 'en';
+
+        $person = $ld->person ?? $data->person ?? null;
+        $personName = is_object($person) ? ($person->name ?? null) : (is_string($person) ? $person : null);
+
+        $twitter   = $m->twitter ?? $data->twitter ?? null;
+        $twSite    = $m->twitterSite    ?? (is_object($twitter) ? ($twitter->site ?? null)    : (is_string($twitter) ? $twitter : null));
+        $twCreator = $m->twitterCreator ?? (is_object($twitter) ? ($twitter->creator ?? null) : (is_string($twitter) ? $twitter : null));
+
+        $generator = $m->generator ?? 'Kirigami';
+        if (self::falsy($generator)) $generator = null;
+
+        self::$config = (object) [
+            'enabled'         => $enabled,
+            'project'         => $data->project ?? $m->siteName ?? null,
+            'tagline'         => $m->tagline ?? $data->tagline ?? null,
+            'titleFormat'     => (string) ($m->titleFormat     ?? '{title} — {project}'),
+            'titleFormatHome' => (string) ($m->titleFormatHome ?? '{project} — {tagline}'),
+            'description'     => $m->description ?? $ld->description ?? $data->description ?? null,
+            'keywords'        => self::arr($m->keywords ?? $ld->keywords ?? $data->keywords ?? null),
+            'robots'          => $m->robots ?? 'index, follow',
+            'language'        => $lang,
+            'generator'       => $generator,
+            'author'          => $m->author ?? $data->author ?? $personName ?? null,
+            'designer'        => $m->designer ?? $data->designer ?? null,
+            'themeColor'      => $m->themeColor ?? $m->themecolor ?? $data->themecolor ?? null,
+            'image'           => self::absUrl($m->image ?? $ld->image ?? $ld->logo ?? $data->image ?? $data->ogimage ?? null),
+            'ogType'          => $m->ogType ?? $m->ogtype ?? 'website',
+            'twitterCard'     => $m->twitterCard ?? $m->twittercard ?? 'summary_large_image',
+            'twitterSite'     => self::handle($twSite),
+            'twitterCreator'  => self::handle($twCreator),
+            'canonical'       => !isset($m->canonical) || self::truthy($m->canonical),
+            'favicon'         => $m->favicon ?? null,
+            'appleTouchIcon'  => $m->appleTouchIcon ?? $m->appletouchicon ?? null,
+            'humans'          => $m->humans ?? null,
+        ];
+
+        return self::$config;
+    }
+
+
+    // -----------------------------------------------------------------------
+    // Manual API
+    // -----------------------------------------------------------------------
+
+    /**
+     * Adds a `<meta>` tag. The key picks the attribute: `og:*` → `property=`,
+     * everything else → `name=`. An empty `$content` is a no-op.
+     */
+    public static function tag(string $name, ?string $content): void
+    {
+        $name    = trim($name);
+        $content = $content === null ? '' : trim($content);
+        if ($name === '' || $content === '') return;
+
+        $attr = str_starts_with(strtolower($name), 'og:') ? 'property' : 'name';
+        self::$extra[] = '<meta ' . $attr . '="' . STR::htmlesc($name) . '" content="' . STR::htmlesc($content) . '">';
+    }
+
+    /** Adds a `<link>` tag. `$attrs` are extra attributes (`type`, `sizes`, …). */
+    public static function link(string $rel, string $href, array $attrs = []): void
+    {
+        if (trim($rel) === '' || trim($href) === '') return;
+        $out = '<link rel="' . STR::htmlesc($rel) . '"';
+        foreach ($attrs as $k => $v) {
+            if ($v === null || $v === '' || $v === false) continue;
+            $out .= ' ' . $k . '="' . STR::htmlesc((string) $v) . '"';
+        }
+        $out .= ' href="' . STR::htmlesc($href) . '">';
+        self::$extra[] = $out;
+    }
+
+    /** Adds a verbatim tag line (already valid HTML). */
+    public static function raw(string $html): void
+    {
+        $html = trim($html);
+        if ($html !== '') self::$extra[] = $html;
+    }
+
+    /** Clears the per-render state. */
+    public static function reset(): void
+    {
+        self::$page    = null;
+        self::$emitted = false;
+        self::$extra   = [];
+    }
+
+
+    // -----------------------------------------------------------------------
+    // Output
+    // -----------------------------------------------------------------------
+
+    /**
+     * The full block of tag lines (`\n`-joined), each dropped when `$html`
+     * already carries an equivalent tag. `''` when there is nothing to emit.
+     */
+    public static function tags(string $html = ''): string
+    {
+        self::$emitted = true;
+
+        $c     = self::config();
+        $info  = self::pageInfo();
+
+        /** @var array<int,array{0:string,1:string}> [probe regex, tag html] */
+        $lines = [];
+
+        // The auto block only builds when the `meta:` block opted in; an
+        // explicit META::tag() call still lands through self::$extra below.
+        if ($c->enabled) {
+            $relroot  = self::relroot();
+
+            $title    = self::pageTitle();
+            $desc     = self::pageTag('meta_description', 'metadescription')
+                        ?? ($info->description ?? $info->abstract ?? $info->excerpt ?? $info->summary ?? null);
+            $desc     = is_string($desc) && trim($desc) !== '' ? trim($desc) : ($c->description ?: null);
+            $keywords = self::arr(self::pageTag('meta_keywords', 'metakeywords')) ?: $c->keywords;
+            $image    = self::absUrl(self::pageTag('meta_image', 'metaimage') ?? $info->image ?? $info->ogimage ?? null) ?? $c->image;
+            $robots   = self::pageTag('meta_robots', 'metarobots', 'robots') ?? $c->robots;
+            $ogType   = self::pageTag('meta_type', 'metatype', 'og_type', 'ogtype') ?? $c->ogType;
+            $url      = self::pageTag('canonical') ?? self::pageUrl();
+
+            if ($title) $lines[] = ['#<title[\s>]#i', '<title>' . STR::htmlesc($title) . '</title>'];
+
+            self::name($lines, 'description', $desc);
+            self::name($lines, 'keywords', $keywords ? implode(', ', $keywords) : null);
+            self::name($lines, 'robots', $robots && !self::falsy($robots) ? (string) $robots : null);
+            self::name($lines, 'language', $c->language);
+            self::name($lines, 'generator', $c->generator);
+            self::name($lines, 'author', $c->author);
+            self::name($lines, 'designer', $c->designer);
+            self::name($lines, 'theme-color', $c->themeColor);
+
+            self::name($lines, 'twitter:card', $c->twitterCard);
+            self::name($lines, 'twitter:title', $title);
+            self::name($lines, 'twitter:description', $desc);
+            self::name($lines, 'twitter:image', $image);
+            self::name($lines, 'twitter:site', $c->twitterSite);
+            self::name($lines, 'twitter:creator', $c->twitterCreator);
+
+            self::prop($lines, 'og:site_name', $c->project);
+            self::prop($lines, 'og:locale', $c->language ? str_replace('-', '_', $c->language) : null);
+            self::prop($lines, 'og:type', $ogType);
+            self::prop($lines, 'og:title', $title);
+            self::prop($lines, 'og:description', $desc);
+            self::prop($lines, 'og:url', $url);
+            self::prop($lines, 'og:image', $image);
+
+            if ($c->canonical && $url) {
+                $lines[] = ['#<link\s+[^>]*rel\s*=\s*(["\'])canonical\1#i',
+                            '<link rel="canonical" href="' . STR::htmlesc($url) . '">'];
+            }
+
+            if ($h = self::asset($c->humans, 'humans', 'humans.txt', $relroot)) {
+                $lines[] = ['#<link\s+[^>]*rel\s*=\s*(["\'])author\1#i',
+                            '<link rel="author" type="text/plain" href="' . STR::htmlesc($h) . '">'];
+            }
+            if ($f = self::asset($c->favicon, 'favicon', 'favicon.ico', $relroot)) {
+                $type = str_ends_with($f, '.svg') ? 'image/svg+xml' : (str_ends_with($f, '.png') ? 'image/png' : 'image/x-icon');
+                $lines[] = ['#<link\s+[^>]*rel\s*=\s*(["\'])icon\1#i',
+                            '<link rel="icon" type="' . $type . '" href="' . STR::htmlesc($f) . '">'];
+            }
+            if ($a = self::asset($c->appleTouchIcon, 'appleTouchIcon', 'apple-touch-icon.png', $relroot)) {
+                $lines[] = ['#<link\s+[^>]*rel\s*=\s*(["\'])apple-touch-icon\1#i',
+                            '<link rel="apple-touch-icon" href="' . STR::htmlesc($a) . '">'];
+            }
+        }
+
+        $out  = [];
+        $seen = [];
+        foreach ($lines as [$probe, $tag]) {
+            if (isset($seen[$tag])) continue;
+            if ($html !== '' && preg_match($probe, $html)) continue;
+            $seen[$tag] = true;
+            $out[] = $tag;
+        }
+        foreach (self::$extra as $tag) {
+            if (isset($seen[$tag])) continue;
+            $seen[$tag] = true;
+            $out[] = $tag;
+        }
+
+        return implode("\n", $out);
+    }
+
+
+    // -----------------------------------------------------------------------
+    // Render hooks (wired in prepros.plugins.php)
+    // -----------------------------------------------------------------------
+
+    /** Captures the page under render. Called from the `page_info` hook. */
+    public static function capture(mixed $info): void
+    {
+        self::reset();
+        self::$page = ['file' => PREPROS::$file ?: null, 'info' => is_object($info) ? $info : new stdClass];
+    }
+
+    /**
+     * Injects the tag block right before `</head>` (after any `<meta charset>`
+     * / `<title>` the layout wrote). Called from the `post_render` hook.
+     */
+    public static function inject(string $html): string
+    {
+        try {
+            if (self::$emitted) return $html;
+            if (self::pageOptedOut()) return $html;
+            if (!self::config()->enabled && self::$extra === []) return $html;
+
+            $block = self::tags($html);
+            if ($block === '') return $html;
+
+            $block = '    ' . str_replace("\n", "\n    ", $block) . "\n";
+            return preg_match('#</head>#i', $html)
+                ? preg_replace('#</head>#i', $block . '</head>', $html, 1)
+                : $block . $html;
+        } finally {
+            self::reset();
+        }
+    }
+
+
+    // -----------------------------------------------------------------------
+    // Internals
+    // -----------------------------------------------------------------------
+
+    private static function name(array &$lines, string $name, ?string $content): void
+    {
+        self::meta($lines, 'name', $name, $content);
+    }
+
+    private static function prop(array &$lines, string $prop, ?string $content): void
+    {
+        self::meta($lines, 'property', $prop, $content);
+    }
+
+    /**
+     * Queues a `<meta $attr="$key" content="$content">`, with a probe that
+     * matches the same key under *either* `name=` or `property=` — a layout that
+     * wrote `og:title` as `name=` (or `twitter:image` as `property=`) still
+     * counts as already present.
+     */
+    private static function meta(array &$lines, string $attr, string $key, ?string $content): void
+    {
+        $content = $content === null ? '' : trim($content);
+        if ($content === '') return;
+        $lines[] = [
+            '#<meta\s+[^>]*(?:name|property)\s*=\s*(["\'])' . preg_quote($key, '#') . '\1#i',
+            '<meta ' . $attr . '="' . $key . '" content="' . STR::htmlesc($content) . '">',
+        ];
+    }
+
+    /** The composed page title, per `titleFormat` / `titleFormatHome`. */
+    private static function pageTitle(): ?string
+    {
+        $c    = self::config();
+        $info = self::pageInfo();
+        $page = self::pageTag('meta_title', 'metatitle') ?? $info->title ?? $info->name ?? null;
+
+        $tokens = [
+            '{title}'   => is_string($page) ? trim($page) : '',
+            '{project}' => (string) ($c->project ?? ''),
+            '{tagline}' => (string) ($c->tagline ?? ''),
+        ];
+
+        $fmt = (!$tokens['{title}'] || $tokens['{title}'] === $tokens['{project}'])
+            ? $c->titleFormatHome
+            : $c->titleFormat;
+
+        $out = strtr($fmt, $tokens);
+        // Collapse separators left dangling by an empty token.
+        $out = preg_replace('/\s*[|\x{2013}\x{2014}\-\/·:]\s*(?=$|[|\x{2013}\x{2014}\-\/·:])/u', '', $out);
+        $out = trim(preg_replace('/^\s*[|\x{2013}\x{2014}\-\/·:]\s*|\s*[|\x{2013}\x{2014}\-\/·:]\s*$/u', '', $out));
+
+        return $out !== '' ? $out : ($tokens['{project}'] ?: null);
+    }
+
+    /** The `kirigami:` block. */
+    private static function data(): object
+    {
+        if (isset(PREPROS::$config) && is_object(PREPROS::$config) && isset(PREPROS::$config->data) && is_object(PREPROS::$config->data)) {
+            return PREPROS::$config->data;
+        }
+        return new stdClass;
+    }
+
+    /** The raw top-level `meta:` block: object, `false`, `true`, or `null`. */
+    private static function metaRaw(): mixed
+    {
+        return (isset(PREPROS::$config) && is_object(PREPROS::$config)) ? (PREPROS::$config->meta ?? null) : null;
+    }
+
+    /** The top-level `jsonld:` block as an object (empty when absent / disabled). */
+    private static function jsonld(): object
+    {
+        $raw = (isset(PREPROS::$config) && is_object(PREPROS::$config)) ? (PREPROS::$config->jsonld ?? null) : null;
+        return is_object($raw) ? $raw : new stdClass;
+    }
+
+    private static function pageInfo(): object
+    {
+        return self::$page['info'] ?? new stdClass;
+    }
+
+    /** First non-empty, non-boolean value among the given PHPDOC tag names. */
+    private static function pageTag(string ...$names): ?string
+    {
+        $info = self::pageInfo();
+        foreach ($names as $n) {
+            $v = $info->$n ?? null;
+            if (is_string($v) && trim($v) !== '' && !self::truthy($v) && !self::falsy($v)) return trim($v);
+        }
+        return null;
+    }
+
+    /** `@meta false` / `@meta_ignore true` → skip this page. */
+    private static function pageOptedOut(): bool
+    {
+        $info = self::pageInfo();
+        $v = $info->meta ?? null;
+        if (is_string($v) && self::falsy($v)) return true;
+        return isset($info->meta_ignore) && self::truthy($info->meta_ignore);
+    }
+
+    /** Absolute URL of the page currently under render (mirrors PREPROS::render()). */
+    private static function pageUrl(): ?string
+    {
+        $data = self::data();
+        $file = self::$page['file'] ?? (PREPROS::$file ?: null);
+        if (!$file || empty($data->baseurl)) return null;
+
+        $root = @realpath(PREPROS::$config->root ?? '') ?: (PREPROS::$config->root ?? '');
+        $abs  = @realpath($file) ?: $file;
+        $rel  = str_replace('\\', '/', pathinfo(str_replace($root, '', $abs), PATHINFO_DIRNAME));
+
+        $basepath = rtrim((string) parse_url($data->baseurl, PHP_URL_PATH), '/');
+        $path     = preg_replace('#/+#', '/', $basepath . '/' . trim($rel, '/') . '/');
+        $origin   = preg_replace('#^(https?://[^/]+).*#', '$1', (string) $data->baseurl);
+
+        return $origin . $path;
+    }
+
+    /** Path from the page's directory back to the source root, e.g. `../` or `./`. */
+    private static function relroot(): string
+    {
+        $file = self::$page['file'] ?? (PREPROS::$file ?: '');
+        if ($file === '') return './';
+        $dir  = str_replace('\\', '/', dirname((string) (@realpath($file) ?: $file))) . '/';
+        $root = str_replace('\\', '/', (string) (@realpath(PREPROS::$config->root ?? '') ?: (PREPROS::$config->root ?? ''))) . '/';
+        return FS::getRelativePath($dir, $root);
+    }
+
+    /**
+     * Resolves an asset link: an explicit string is used as-is (page-relative
+     * when it is a bare filename); `true` forces the default file; `null`
+     * auto-detects the default file at the source root (presence reported by
+     * `prepros.js` via `metaFiles`, since these extensions are not mounted);
+     * `false` disables it.
+     */
+    private static function asset(mixed $value, string $key, string $default, string $relroot): ?string
+    {
+        if (self::falsy($value)) return null;
+
+        if (is_string($value) && trim($value) !== '') {
+            $v = trim($value);
+            if (preg_match('#^(https?:)?//#', $v) || str_starts_with($v, '/') || str_starts_with($v, '.')) return $v;
+            return rtrim($relroot, '/') . '/' . ltrim($v, '/');
+        }
+
+        if ($value === true) return rtrim($relroot, '/') . '/' . $default;
+
+        $files = (isset(PREPROS::$config) && is_object(PREPROS::$config)) ? (PREPROS::$config->metaFiles ?? null) : null;
+        $found = is_object($files) ? ($files->$key ?? false) : false;
+        if (!$found) {
+            // Fall back to a direct check, for files that do live in the sandbox.
+            $root = (string) (@realpath(PREPROS::$config->root ?? '') ?: (PREPROS::$config->root ?? ''));
+            $found = $root !== '' && is_file($root . '/' . $default);
+        }
+        return $found ? rtrim($relroot, '/') . '/' . $default : null;
+    }
+
+    /** Turns a relative path into an absolute URL against `baseurl`. */
+    private static function absUrl(?string $url): ?string
+    {
+        if ($url === null || trim($url) === '') return null;
+        $url = trim($url);
+        if (preg_match('#^(https?:)?//#', $url) || str_starts_with($url, 'data:')) return $url;
+
+        $origin = preg_replace('#^(https?://[^/]+).*#', '$1', (string) (self::data()->baseurl ?? ''));
+        return $origin === '' ? $url : $origin . '/' . ltrim($url, '/');
+    }
+
+    /** `@user` / `user` / `https://twitter.com/user` → `@user`. */
+    private static function handle(mixed $v): ?string
+    {
+        if (!is_string($v) || trim($v) === '') return null;
+        $v = trim($v);
+        if (preg_match('#(?:twitter|x)\.com/@?([A-Za-z0-9_]{1,15})#i', $v, $m)) return '@' . $m[1];
+        return '@' . ltrim($v, '@');
+    }
+
+    /** @return array<int,string> */
+    private static function arr(mixed $v): array
+    {
+        if ($v === null || $v === '') return [];
+        if (is_array($v)) return array_values(array_filter(array_map(fn($x) => trim((string) $x), $v), fn($x) => $x !== ''));
+        if (is_object($v)) return self::arr((array) $v);
+        // A scalar string: split a comma-separated list, else keep as one item.
+        $s = trim((string) $v);
+        return str_contains($s, ',') ? self::arr(array_map('trim', explode(',', $s))) : ($s === '' ? [] : [$s]);
+    }
+
+    private static function truthy(mixed $v): bool
+    {
+        if (is_bool($v)) return $v;
+        return in_array(strtolower(trim((string) $v)), ['1', 'true', 'yes', 'on'], true);
+    }
+
+    private static function falsy(mixed $v): bool
+    {
+        if (is_bool($v)) return !$v;
+        return in_array(strtolower(trim((string) $v)), ['0', 'false', 'no', 'off'], true);
+    }
+}

package/src/libraries/prepros.class.php

@@ -142,7 +142,9 @@ final class PREPROS
      *
      * Runs unless `prepros.head` is `false`. A single task opts out with
      * `head: false`. A file already referenced in the page is left alone.
-     * `###TIMESTAMP###` is expanded by replaceTokens() right after.
+     * The `?###TIMESTAMP###` cache-buster is left literal at render time and
+     * only expanded on export (see replaceTokens()), so rebuilding a preview
+     * never rewrites the committed page.
      */
     private static function injectHead(string $contents, string $relroot): string
     {
@@ -208,14 +210,19 @@ final class PREPROS
     /**
      * Expands the build-time text tokens in a generated file. Runs at render
      * time (so `kiri build` / `kiri watch` previews show real values, not the
-     * literal `###YEAR###`), and again — harmlessly — on export.
+     * literal `###YEAR###`).
+     *
+     * `###TIMESTAMP###` is deliberately NOT expanded here: it is only ever a
+     * cache-buster on the managed-`<head>` asset refs, has no preview value,
+     * and expanding it per render would rewrite every committed `src/**` page
+     * with a fresh number on each build. The export copy (bin/tasks/dist.js)
+     * substitutes it — and `###YEAR###` / `###TODAY###` — when writing `dist/`.
      */
     private static function replaceTokens(string $contents): string
     {
         return strtr($contents, [
-            '###YEAR###'      => date('Y'),
-            '###TIMESTAMP###' => (string) time(),
-            '###TODAY###'     => date('Y-m-d'),
+            '###YEAR###'  => date('Y'),
+            '###TODAY###' => date('Y-m-d'),
         ]);
     }
 

package/src/libraries/prepros.plugins.php

@@ -65,14 +65,17 @@ PREPROS::registerHook('page_info', function($info) {
 });
 
 
-// LD — capture the page under render, then inject the automatic
-// schema.org JSON-LD `<script>` into its `<head>` once the HTML is assembled.
-// Registered after the data-loading hook above so `$page` arrives resolved.
+// LD / META — capture the page under render, then inject the automatic
+// schema.org JSON-LD `<script>` and the SEO/social `<meta>`/`<link>` block into
+// its `<head>` once the HTML is assembled. Registered after the data-loading
+// hook above so `$page` arrives resolved.
 PREPROS::registerHook('page_info', function($page) {
 	LD::capture($page);
+	META::capture($page);
 	return $page;
 });
 
 PREPROS::registerHook('post_render', function($html) {
+	$html = META::inject($html);
 	return LD::inject($html);
 });

package/src/prepros.js

@@ -12,16 +12,25 @@ const __modules = new Map;
 const __project = process.cwd();
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const __configpath = path.join(__project, 'kirigami.yaml');
-let   __root = null;
-let   __php  = null;
-
-
-if (!fs.existsSync(__configpath)) throw `Config file not found: ${__configpath}`;
-const config = await walkFile(__configpath);
-if(!config) throw `Invalid config file: ${__configpath}`;
+let   __root   = null;
+let   __php    = null;
+let   __config = null;
+
+
+// Load and cache kirigami.yaml on first use. Deferred (not run at import) so
+// `import '@kirigami/php-prepros'` has no side effects — e.g. `kiri build -h`
+// can pull the module in with no project on disk.
+const loadConfig = async () => {
+    if (__config) return __config;
+    if (!fs.existsSync(__configpath)) throw `Config file not found: ${__configpath}`;
+    __config = await walkFile(__configpath);
+    if (!__config) throw `Invalid config file: ${__configpath}`;
+    return __config;
+}
 
 
 const getPHPInstance = async () => {
+    const config = await loadConfig();
     if(!__php) {
         if(config?.kirigami?.root === undefined) throw `Missing prepros:root property in config file: ${__configpath}`;
         __root = path.join(__project, config.kirigami.root);
@@ -38,6 +47,15 @@ const getPHPInstance = async () => {
         preprosConfig.root = joinWith('/project/', config?.kirigami?.root);
         preprosConfig.data = config.kirigami || {};
         preprosConfig.jsonld = config.jsonld ?? null;
+        preprosConfig.meta = config.meta ?? null;
+        // META auto-detects favicon / apple-touch-icon / humans.txt at the
+        // source root; those extensions aren't mounted into the sandbox, so the
+        // presence check is done here on the real filesystem instead.
+        preprosConfig.metaFiles = {
+            favicon:        fs.existsSync(path.join(__root, 'favicon.ico')),
+            appleTouchIcon: fs.existsSync(path.join(__root, 'apple-touch-icon.png')),
+            humans:         fs.existsSync(path.join(__root, 'humans.txt')),
+        };
         // The build task list — read by PREPROS::injectHead() to auto-wire each
         // page's <head> with a <link>/<script> per sass/esbuild task output.
         preprosConfig.tasks = config.tasks || [];
@@ -91,6 +109,7 @@ const getPHPInstance = async () => {
 
 
 const mountPath = async (localPath, virtualDir, php) => {
+    const config = await loadConfig();
     php = php || await getPHPInstance();
     if(!path.isAbsolute(localPath)) localPath = path.join(__project, localPath);
     virtualDir = virtualDir || path.posix.join('/project', localPath.replace(__project + path.sep, ''));
@@ -242,6 +261,7 @@ const processImages = async (jobs = []) => {
 
 
 const render = async (file = '.', phpIncludes = []) => {
+    const config = await loadConfig();
     const target = path.resolve(config?.kirigami?.root, file);
     const fsvm = path.join('/project', config?.kirigami?.root, file).replace(/\\/g, '/');
     await mountPath(target);
@@ -269,6 +289,7 @@ const render = async (file = '.', phpIncludes = []) => {
 
 
 const sitemap = async () => {
+    const config = await loadConfig();
     await mountPath(config?.kirigami?.root);
     return run(['sitemap']);
 }

package/src/utils.inc.php

@@ -25,6 +25,7 @@ spl_autoload_register(function ($class) {
         'IMG'             => 'img.class.php',
         'LD'              => 'ld.class.php',
         'MD'              => 'md.class.php',
+        'META'            => 'meta.class.php',
         'NORM'            => 'norm.class.php',
         'OBF'             => 'obf.class.php',
 		'PREPROS'         => 'prepros.class.php',