@warpgogol/werkstatt-shared 0.8.3 → 0.8.6

package/README.md

@@ -0,0 +1,135 @@
+# @warpgogol/werkstatt-shared
+
+[Українська](README.uk.md) | English
+
+Stack-agnostic shared infrastructure extracted from `werkstatt-site` (RFC-0868). Owns checks, integration, ontology, passport, share, and surface domains consumed by both the Werkstatt engine and the site plugin.
+
+---
+
+## What this package does
+
+This is a **shared infrastructure library** used by the [Werkstatt](https://www.npmjs.com/package/@warpgogol/werkstatt) engine and the `werkstatt-site` plugin. It provides:
+
+- **Checks** — content validators, SEO validators, surface expand/bake logic
+- **Integration** — CRM, funnel, hub, sharding, QStash adapters
+- **Ontology** — catalogs, enums, Sternsystem owner types
+- **Passport** — DHT signing, identity signing, schema validation
+- **Share** — slug generation, semantic extraction, URL canonicalization, route filtering, middleware, access protection
+- **Surface** — surface expand/bake helpers and labels
+
+You don't use this package on its own — it is consumed by the engine and site plugin as a dependency.
+
+---
+
+## Installation
+
+```sh
+pnpm add @warpgogol/werkstatt-shared
+```
+
+This package is installed automatically when you install `@warpgogol/werkstatt` or `@warpgogol/werkstatt-site`.
+
+---
+
+## How it fits into the Werkstatt ecosystem
+
+| Package | Role |
+| --- | --- |
+| `@warpgogol/forge` | Governance layer — skills, RFC/ADR workflows, CLI, project scaffolding |
+| `@warpgogol/werkstatt` | Runtime engine — missions, releases, deployment, certification, Bordbuch |
+| `@warpgogol/werkstatt-shared` | **This package** — shared infrastructure (checks, integration, ontology, passport, share) |
+| `@warpgogol/werkstatt-site` | Astro site plugin — consumes this package for checks, integration, ontology, passport, share |
+
+The engine and site plugin both import from this package. It MUST NOT import from `werkstatt-site` — enforced by `werkstatt.shared.validate`.
+
+---
+
+## Canonical utilities
+
+### Slug generation (RFC-0915, DNA-88)
+
+| Export | Purpose |
+| --- | --- |
+| `slugUrl(text, lang?)` | Locale-aware URL slug (German umlauts, Ukrainian transliteration, default) |
+| `slugId(text)` | Semantic block ID slug |
+| `HeadingSlugger` | Stateful heading anchor deduplication |
+
+```ts
+import { slugUrl } from "@warpgogol/werkstatt-shared/share/slug";
+
+const url = slugUrl("Über uns", "de"); // "ueber-uns"
+```
+
+### Semantic extraction (RFC-0901)
+
+| Export | Purpose |
+| --- | --- |
+| `splitSentences(text, locale?)` | Locale-aware sentence boundary detection (`de`, `uk`, `en`) |
+
+### Canonical entity URL (RFC-0910)
+
+| Export | Purpose |
+| --- | --- |
+| `canonicalRootUrl(baseUrl)` | Unprefixed root URL for JSON-LD entity identity |
+
+### Placeholder route filtering (RFC-0917)
+
+| Export | Purpose |
+| --- | --- |
+| `hasPlaceholderRoutes(routes)` | Detect Astro dynamic route templates (`[slug]`, `[version]`) |
+
+---
+
+## Architecture
+
+| Directory | Purpose |
+| --- | --- |
+| `src/index.ts` | Main barrel export |
+| `src/checks/` | Content validators, SEO validators, surface expand/bake |
+| `src/integration/` | CRM, funnel, hub, sharding, QStash adapters |
+| `src/ontology/` | Catalogs, enums, Sternsystem owner types |
+| `src/passport/` | DHT signing, identity signing, schema validation |
+| `src/share/` | Slug, semantic, URL canonicalization, routes, middleware, access protection |
+| `src/surface/` | Surface expand/bake helpers and labels |
+| `src/content/` | SystemManifest types and content schema |
+
+---
+
+## Boundary rules
+
+- This package MUST NOT import from `@warpgogol/werkstatt-site` — enforced by `werkstatt.shared.validate`.
+- This package MAY import from `@warpgogol/werkstatt` (engine) and external packages.
+- Axiom dependencies (`@syrokomskyi/axiom-*`) are `optionalDependencies` — consumers without axiom installed must use type-only imports or guard runtime access.
+
+---
+
+## Publishing to npm
+
+This package is published to the npm registry as `@warpgogol/werkstatt-shared`. Publishing is automated via GitHub Actions CI.
+
+### How it works
+
+1. The source lives in the [warpgogol/werkstatt](https://github.com/syrokomskyi/werkstatt) monorepo under `packages/werkstatt-shared/`.
+2. [`@warpgogol/repo-extract`](https://github.com/syrokomskyi/repo-extract) extracts the package into the standalone [syrokomskyi/werkstatt-shared](https://github.com/syrokomskyi/werkstatt-shared) repository, flattening it to repo root and stripping workspace dependencies.
+3. The generated GitHub Actions CI workflow runs on every push to `main`: lint → typecheck → build → test → `npm publish --provenance --access public`.
+4. The `NPM_TOKEN` secret must be set in the [repository settings](https://github.com/syrokomskyi/werkstatt-shared/settings/secrets/actions).
+
+### Triggering a new release
+
+From the werkstatt monorepo root:
+
+```sh
+# 1. Bump the version in packages/werkstatt-shared/package.json
+# 2. Run the extraction (extracts + commits + pushes to github.com:syrokomskyi/werkstatt-shared.git)
+pnpm exec repo-extract --config packages/werkstatt-shared/extract.config.yaml --verbose
+
+# 3. CI picks up the push and publishes to npm automatically
+```
+
+After CI completes, verify the new version on [npmjs.com/package/@warpgogol/werkstatt-shared](https://www.npmjs.com/package/@warpgogol/werkstatt-shared).
+
+---
+
+## License
+
+Apache-2.0

package/README.uk.md

@@ -0,0 +1,135 @@
+# @warpgogol/werkstatt-shared
+
+Українська | [English](README.md)
+
+Спільна інфраструктура, незалежна від стеку, витягнута з `werkstatt-site` (RFC-0868). Володіє доменами checks, integration, ontology, passport, share та surface, які споживають рушій Werkstatt та site-плагін.
+
+---
+
+## Що робить цей пакет
+
+Це **бібліотека спільної інфраструктури**, яку використовують рушій [Werkstatt](https://www.npmjs.com/package/@warpgogol/werkstatt) та плагін `werkstatt-site`. Вона надає:
+
+- **Checks** — валідатори контенту, SEO-валідатори, логіка surface expand/bake
+- **Integration** — адаптери CRM, funnel, hub, sharding, QStash
+- **Ontology** — каталоги, enum-и, типи Sternsystem owner
+- **Passport** — DHT-підписування, підписування ідентичності, валідація схем
+- **Share** — генерація slug-ів, семантична екстракція, канонізація URL, фільтрація маршрутів, middleware, захист доступу
+- **Surface** — хелпери surface expand/bake та мітки
+
+Цей пакет не використовується самостійно — його споживають рушій та site-плагін як залежність.
+
+---
+
+## Встановлення
+
+```sh
+pnpm add @warpgogol/werkstatt-shared
+```
+
+Цей пакет встановлюється автоматично при встановленні `@warpgogol/werkstatt` або `@warpgogol/werkstatt-site`.
+
+---
+
+## Як це вписується в екосистему Werkstatt
+
+| Пакет | Роль |
+| --- | --- |
+| `@warpgogol/forge` | Шар управління — навички, RFC/ADR робочі процеси, CLI, скаффолд проєктів |
+| `@warpgogol/werkstatt` | Рушій runtime — місії, релізи, розгортання, сертифікація, Bordbuch |
+| `@warpgogol/werkstatt-shared` | **Цей пакет** — спільна інфраструктура (checks, integration, ontology, passport, share) |
+| `@warpgogol/werkstatt-site` | Astro site-плагін — споживає цей пакет для checks, integration, ontology, passport, share |
+
+Рушій та site-плагін імпортують з цього пакунка. Він НЕ ПОВИНЕН імпортувати з `werkstatt-site` — це контролюється `werkstatt.shared.validate`.
+
+---
+
+## Канонічні утиліти
+
+### Генерація slug (RFC-0915, DNA-88)
+
+| Експорт | Призначення |
+| --- | --- |
+| `slugUrl(text, lang?)` | Локалізований URL-slug (німецькі умлаути, українська транслітерація, за замовчуванням) |
+| `slugId(text)` | Семантичний slug ID блоку |
+| `HeadingSlugger` | Станковий дедуплікатор якорів заголовків |
+
+```ts
+import { slugUrl } from "@warpgogol/werkstatt-shared/share/slug";
+
+const url = slugUrl("Über uns", "de"); // "ueber-uns"
+```
+
+### Семантична екстракція (RFC-0901)
+
+| Експорт | Призначення |
+| --- | --- |
+| `splitSentences(text, locale?)` | Локалізоване виявлення меж речень (`de`, `uk`, `en`) |
+
+### Канонічний URL сутності (RFC-0910)
+
+| Експорт | Призначення |
+| --- | --- |
+| `canonicalRootUrl(baseUrl)` | Непрефіксований кореневий URL для JSON-LD ідентичності сутності |
+
+### Фільтрація плейсхолдер-маршрутів (RFC-0917)
+
+| Експорт | Призначення |
+| --- | --- |
+| `hasPlaceholderRoutes(routes)` | Виявлення Astro динамічних шаблонів маршрутів (`[slug]`, `[version]`) |
+
+---
+
+## Архітектура
+
+| Директорія | Призначення |
+| --- | --- |
+| `src/index.ts` | Головний barrel-експорт |
+| `src/checks/` | Валідатори контенту, SEO-валідатори, surface expand/bake |
+| `src/integration/` | Адаптери CRM, funnel, hub, sharding, QStash |
+| `src/ontology/` | Каталоги, enum-и, типи Sternsystem owner |
+| `src/passport/` | DHT-підписування, підписування ідентичності, валідація схем |
+| `src/share/` | Slug, семантика, канонізація URL, маршрути, middleware, захист доступу |
+| `src/surface/` | Хелпери surface expand/bake та мітки |
+| `src/content/` | Типи SystemManifest та схема контенту |
+
+---
+
+## Межі
+
+- Цей пакет НЕ ПОВИНЕН імпортувати з `@warpgogol/werkstatt-site` — контролюється `werkstatt.shared.validate`.
+- Цей пакет МОЖЕ імпортувати з `@warpgogol/werkstatt` (рушій) та зовнішніх пакунків.
+- Axiom-залежності (`@syrokomskyi/axiom-*`) — `optionalDependencies`. Споживачі без axiom повинні використовувати type-only імпорти або охороняти runtime-доступ.
+
+---
+
+## Публікація в npm
+
+Цей пакет публікується в реєстр npm як `@warpgogol/werkstatt-shared`. Публікація автоматизована через GitHub Actions CI.
+
+### Як це працює
+
+1. Вихідний код знаходиться в монорепозиторії [warpgogol/werkstatt](https://github.com/syrokomskyi/werkstatt) у `packages/werkstatt-shared/`.
+2. [`@warpgogol/repo-extract`](https://github.com/syrokomskyi/repo-extract) витягує пакет у автономний репозиторій [syrokomskyi/werkstatt-shared](https://github.com/syrokomskyi/werkstatt-shared), вирівнюючи його до кореня репозиторію та видаляючи залежності робочого простору.
+3. Згенерований GitHub Actions CI-воркфлоу запускається при кожному пуші в `main`: lint → typecheck → build → test → `npm publish --provenance --access public`.
+4. Секрет `NPM_TOKEN` має бути встановлений у [налаштуваннях репозиторію](https://github.com/syrokomskyi/werkstatt-shared/settings/secrets/actions).
+
+### Запуск нового релізу
+
+З кореня монорепозиторію werkstatt:
+
+```sh
+# 1. Підняти версію в packages/werkstatt-shared/package.json
+# 2. Запустити екстракцію (витягує + комітить + пушить в github.com:syrokomskyi/werkstatt-shared.git)
+pnpm exec repo-extract --config packages/werkstatt-shared/extract.config.yaml --verbose
+
+# 3. CI підхоплює пуш і публікує в npm автоматично
+```
+
+Після завершення CI перевірте нову версію на [npmjs.com/package/@warpgogol/werkstatt-shared](https://www.npmjs.com/package/@warpgogol/werkstatt-shared).
+
+---
+
+## Ліцензія
+
+Apache-2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warpgogol/werkstatt-shared",
-  "version": "0.8.3",
+  "version": "0.8.6",
   "private": false,
   "type": "module",
   "engines": {
@@ -210,6 +210,10 @@
       "types": "./src/share/image-provider.ts",
       "default": "./src/share/image-provider.ts"
     },
+    "./share/import-scan": {
+      "types": "./src/share/import-scan.ts",
+      "default": "./src/share/import-scan.ts"
+    },
     "./share/knowledge": {
       "types": "./src/share/knowledge/index.ts",
       "default": "./src/share/knowledge/index.ts"
@@ -1371,6 +1375,7 @@
     "hls.js": "^1.6.16",
     "lenis": "^1.3.25",
     "plyr": "^3.8.4",
+    "qrcode": "^1.5.4",
     "gray-matter": "^4.0.3",
     "yaml": "^2.9.0",
     "zod": "^4.4.3"
@@ -1387,6 +1392,7 @@
     "eslint": "^10.8.0",
     "fast-check": "^4.9.0",
     "gsap": "^3.15.0",
+    "@types/qrcode": "^1.5.5",
     "typescript": "^6.0.3",
     "typescript-eslint": "8.65.0",
     "vitest": "^4.1.10"

package/src/share/entitlement.ts

@@ -13,6 +13,7 @@ agnostic contract consumed by the build-time resolver, the feature gates, and ru
   <item>RFC-0169: initial implementation.</item>
   <item>RFC-0706: add nachweis feature for Nachweisregister commercial module.</item>
   <item>RFC-0741: add multi-currency feature for multi-currency build pipeline.</item>
+  <item>RFC-0932: add external-link-qr feature for QR code modal entitlement module.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -37,6 +38,8 @@ export const ENTITLED_FEATURES = [
   "nachweis",
   // RFC-0741: multi-currency entitled feature
   "multi-currency",
+  // RFC-0932: external-link QR code modal module
+  "external-link-qr",
 ] as const;
 
 export type EntitledFeature = (typeof ENTITLED_FEATURES)[number];
@@ -62,6 +65,8 @@ export const STRIPE_FEATURE_LOOKUP_MAP: Record<string, EntitledFeature> = {
   feature_nachweis: "nachweis",
   // RFC-0741
   feature_multi_currency: "multi-currency",
+  // RFC-0932
+  feature_external_link_qr: "external-link-qr",
 };
 
 /**

package/src/share/import-scan.ts

@@ -0,0 +1,71 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Shared utility for scanning TypeScript source files for import specifiers
+matching a pattern. Used by werkstatt.autonomy.validate, werkstatt.shared.validate,
+and forge.autonomy.validate to avoid code duplication (Fowler: Duplicated Code).</purpose>
+<keywords>scan, import, utility, shared, validate, autonomy</keywords>
+<non-goals>
+  <item>Does not define what is forbidden or exempt — callers provide the pattern and filter.</item>
+  <item>Does not scan test files — .test.ts and .spec.ts are always excluded.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0868: extract shared directory-scanning utility from autonomy-validate and shared-validate.</item>
+  <item>RFC-0940: move to @warpgogol/werkstatt-shared so forge can import without depending on @warpgogol/werkstatt.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+
+export interface ImportViolation {
+  file: string;
+  specifier: string;
+}
+
+const EXCLUDE_DIRS = new Set(["node_modules", "tests", "tests-handoff", "dist", "templates"]);
+const EXCLUDE_SUFFIXES = [".test.ts", ".spec.ts"];
+
+const IMPORT_PATTERN =
+  /(?:^|\n)\s*(?:import\s+(?:type\s+)?[^;]+?\s+from\s+|require\s*\(\s*)["'`]([^"'`]+)["'`]/g;
+
+function shouldExcludeFile(fileName: string): boolean {
+  return EXCLUDE_SUFFIXES.some((suffix) => fileName.endsWith(suffix));
+}
+
+export async function scanDirectoryForImports(
+  dir: string,
+  workspaceRoot: string,
+  specifierFilter: (specifier: string) => boolean,
+): Promise<{ violations: ImportViolation[]; scannedFiles: number }> {
+  let scannedFiles = 0;
+  const violations: ImportViolation[] = [];
+  const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      if (EXCLUDE_DIRS.has(entry.name)) continue;
+      const subResult = await scanDirectoryForImports(fullPath, workspaceRoot, specifierFilter);
+      scannedFiles += subResult.scannedFiles;
+      violations.push(...subResult.violations);
+    } else if (entry.name.endsWith(".ts") && !shouldExcludeFile(entry.name)) {
+      scannedFiles++;
+      const content = await readFile(fullPath, "utf8").catch(() => "");
+      let match: RegExpExecArray | null;
+      const pattern = new RegExp(IMPORT_PATTERN.source, "g");
+      while ((match = pattern.exec(content)) !== null) {
+        const specifier = match[1]!;
+        if (specifierFilter(specifier)) {
+          violations.push({
+            file: relative(workspaceRoot, fullPath),
+            specifier,
+          });
+        }
+      }
+    }
+  }
+
+  return { violations, scannedFiles };
+}

package/src/share/scripts/external-link-qr.ts

@@ -0,0 +1,196 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0932: Client-side QR code modal for external links. Attaches click/keyboard
+handlers to [data-qr-trigger] elements, lazy-loads the qrcode library on first activation,
+and manages the modal lifecycle (open, close, focus trap, body scroll lock).</purpose>
+<non-goals>
+  <item>Do not generate QR codes for internal links or non-HTTP links.</item>
+  <item>Do not manage entitlement state — the orchestrator only calls initExternalLinkQr() when entitled.</item>
+  <item>Do not create the modal DOM — the modal element is rendered by layout-component.astro.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0932: initial implementation — QR modal lifecycle, dynamic qrcode import, focus trap, body scroll lock.</item>
+</CHANGE_SUMMARY>
+*/
+
+export interface ExternalLinkQrOptions {
+  /** CSS selector for the modal container element. Default: "[data-external-link-qr-modal]" */
+  modalSelector?: string;
+  /** QR code error correction level. Default: "M" */
+  errorCorrectionLevel?: "L" | "M" | "Q" | "H";
+}
+
+const DEFAULT_MODAL_SELECTOR = "[data-external-link-qr-modal]";
+const DEFAULT_ERROR_CORRECTION = "M" as const;
+
+let initialized = false;
+
+export function initExternalLinkQr(options?: ExternalLinkQrOptions): void {
+  if (initialized) return;
+  initialized = true;
+
+  const modalSelector = options?.modalSelector ?? DEFAULT_MODAL_SELECTOR;
+  const errorCorrectionLevel = options?.errorCorrectionLevel ?? DEFAULT_ERROR_CORRECTION;
+
+  const modalEl = document.querySelector<HTMLElement>(modalSelector);
+  if (!modalEl) return;
+  const modal: HTMLElement = modalEl;
+
+  const overlay = modal.querySelector<HTMLElement>("[data-qr-overlay]");
+  const canvas = modal.querySelector<HTMLCanvasElement>("[data-qr-canvas]");
+  const closeBtnEl = modal.querySelector<HTMLButtonElement>("[data-qr-close]");
+  const openLinkBtn = modal.querySelector<HTMLAnchorElement>("[data-qr-open-link]");
+  const titleEl = modal.querySelector<HTMLElement>("[data-qr-title]");
+  const errorEl = modal.querySelector<HTMLElement>("[data-qr-error]");
+
+  if (!overlay || !closeBtnEl) return;
+  const closeBtn: HTMLButtonElement = closeBtnEl;
+
+  let lastFocused: HTMLElement | null = null;
+
+  function openModal(href: string, trigger: HTMLElement): void {
+    lastFocused = trigger;
+
+    if (titleEl) {
+      try {
+        const url = new URL(href);
+        titleEl.textContent = url.hostname.replace(/^www\./, "");
+      } catch {
+        titleEl.textContent = href;
+      }
+    }
+
+    if (openLinkBtn) {
+      openLinkBtn.setAttribute("href", href);
+    }
+
+    if (errorEl) {
+      errorEl.hidden = true;
+    }
+
+    modal.hidden = false;
+    document.body.style.overflow = "hidden";
+
+    if (canvas) {
+      generateQr(href).catch(() => {
+        if (errorEl) {
+          errorEl.hidden = false;
+        }
+      });
+    }
+
+    closeBtn.focus();
+  }
+
+  async function generateQr(href: string): Promise<void> {
+    if (!canvas) return;
+    const { toCanvas } = await import("qrcode");
+    await toCanvas(canvas, href, {
+      width: 256,
+      margin: 2,
+      errorCorrectionLevel,
+    });
+  }
+
+  function closeModal(): void {
+    modal.hidden = true;
+    document.body.style.overflow = "";
+
+    if (canvas) {
+      const ctx = canvas.getContext("2d");
+      if (ctx) {
+        ctx.clearRect(0, 0, canvas.width, canvas.height);
+      }
+    }
+
+    if (lastFocused) {
+      lastFocused.focus();
+      lastFocused = null;
+    }
+  }
+
+  function isModalOpen(): boolean {
+    return !modal.hidden;
+  }
+
+  function handleTriggerClick(e: Event): void {
+    const trigger = e.currentTarget as HTMLElement;
+    const anchor = trigger.closest("a");
+    if (!anchor) return;
+
+    const href = anchor.getAttribute("href");
+    if (!href) return;
+
+    e.preventDefault();
+    e.stopPropagation();
+    openModal(href, trigger);
+  }
+
+  function handleTriggerKeydown(e: KeyboardEvent): void {
+    if (e.key !== "Enter" && e.key !== " ") return;
+    e.preventDefault();
+    e.stopPropagation();
+    const trigger = e.currentTarget as HTMLElement;
+    const anchor = trigger.closest("a");
+    if (!anchor) return;
+    const href = anchor.getAttribute("href");
+    if (!href) return;
+    openModal(href, trigger);
+  }
+
+  function handleKeydown(e: KeyboardEvent): void {
+    if (!isModalOpen()) return;
+
+    if (e.key === "Escape") {
+      e.preventDefault();
+      closeModal();
+      return;
+    }
+
+    if (e.key === "Tab") {
+      const focusable = Array.from(
+        modal.querySelectorAll<HTMLElement>('button, [href], [tabindex]:not([tabindex="-1"])'),
+      ).filter((el) => !el.hasAttribute("disabled") && el.offsetParent !== null);
+
+      if (focusable.length === 0) return;
+
+      const first = focusable[0];
+      const last = focusable[focusable.length - 1];
+
+      if (e.shiftKey) {
+        if (document.activeElement === first) {
+          e.preventDefault();
+          last.focus();
+        }
+      } else {
+        if (document.activeElement === last) {
+          e.preventDefault();
+          first.focus();
+        }
+      }
+    }
+  }
+
+  function attachTriggers(): void {
+    const triggers = document.querySelectorAll<HTMLElement>("[data-qr-trigger]");
+    for (const trigger of triggers) {
+      trigger.addEventListener("click", handleTriggerClick);
+      trigger.addEventListener("keydown", handleTriggerKeydown);
+    }
+  }
+
+  overlay.addEventListener("click", closeModal);
+  closeBtn.addEventListener("click", closeModal);
+  document.addEventListener("keydown", handleKeydown);
+
+  if (canvas) {
+    canvas.style.cursor = "pointer";
+    canvas.addEventListener("click", () => {
+      const link = openLinkBtn?.getAttribute("href");
+      if (link) window.open(link, "_blank", "noopener,noreferrer");
+    });
+  }
+
+  attachTriggers();
+}

package/src/share/scripts/external-links.ts

@@ -1,20 +1,29 @@
 /*
 <MODULE_CONTRACT>
-<purpose>Applies security attributes to external anchor elements on the page.</purpose>
+<purpose>Applies security attributes to external anchor elements on the page. When the
+external-link-qr entitlement is active, also injects a QR trigger span into each external link.</purpose>
 <non-goals>
   <item>Do not handle internal navigation or routing.</item>
   <item>Do not modify non-HTTP links (mailto:, tel:, etc.).</item>
+  <item>Do not generate QR codes — that is the responsibility of external-link-qr.ts.</item>
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0011 Phase 2: Extracted from layout.astro inline script into src/scripts canonical pattern.</item>
   <item>Migrated to @warpgogol/werkstatt-shared/share/scripts for platform-wide reuse.</item>
+  <item>RFC-0932: accept ExternalLinkBehaviorOptions, inject QR trigger span when entitled.</item>
 </CHANGE_SUMMARY>
 */
 
+export interface ExternalLinkBehaviorOptions {
+  /** Whether the external-link-qr entitlement is resolved. Default false (fail-closed). */
+  externalLinkQrEntitled?: boolean;
+}
+
 // @ai-invariant: This function must only modify external HTTP/HTTPS links. Never touch mailto:, tel:, or internal links.
-export function applyExternalLinkBehavior(): void {
+export function applyExternalLinkBehavior(options?: ExternalLinkBehaviorOptions): void {
   const anchors = document.querySelectorAll("a[href]");
+  const qrEntitled = options?.externalLinkQrEntitled === true;
 
   for (const anchor of anchors) {
     const href = anchor.getAttribute("href");
@@ -41,5 +50,18 @@ export function applyExternalLinkBehavior(): void {
     anchor.setAttribute("data-external-link", "1");
     anchor.setAttribute("target", "_blank");
     anchor.setAttribute("rel", "noopener noreferrer");
+
+    if (qrEntitled && anchor.getAttribute("data-external-link-qr") !== "off") {
+      if (!anchor.querySelector("[data-qr-trigger]")) {
+        const trigger = document.createElement("span");
+        trigger.className = "external-link-qr-trigger";
+        trigger.setAttribute("role", "button");
+        trigger.setAttribute("tabindex", "0");
+        trigger.setAttribute("aria-label", "QR-Code anzeigen");
+        trigger.setAttribute("data-qr-trigger", "");
+        trigger.textContent = "\u2197";
+        anchor.appendChild(trigger);
+      }
+    }
   }
 }

package/src/share/scripts/index.ts

@@ -17,6 +17,7 @@
 // scheduler.ts is loaded dynamically by orchestrator.ts and lordicon.ts
 export * from "./lordicon.ts";
 export * from "./external-links.ts";
+export * from "./external-link-qr.ts";
 export * from "./lenis.ts";
 export * from "./orchestrator.ts";
 // gsap-counter.ts (RFC-0040) is loaded dynamically by orchestrator.ts

package/src/share/scripts/orchestrator.ts

@@ -34,6 +34,8 @@ export interface OrchestrationOptions {
   videoPlayers?: boolean;
   /** RFC-0205: opt in to Lenis smooth scroll. Default false — avoids loading the 17 KB bundle when not needed. */
   smoothScroll?: boolean;
+  /** RFC-0932: entitlement state for external-link-qr module. Passed from layout. */
+  externalLinkQrEntitled?: boolean;
 }
 
 const has = (selector: string) => document.querySelector(selector) instanceof Element;
@@ -49,11 +51,15 @@ export async function runStandardLayoutOrchestration(
   // 1. External links security (mandatory)
   if (has("a[href]")) {
     if (document.readyState === "loading") {
-      document.addEventListener("DOMContentLoaded", () => applyExternalLinkBehavior(), {
-        once: true,
-      });
+      document.addEventListener(
+        "DOMContentLoaded",
+        () => applyExternalLinkBehavior({ externalLinkQrEntitled: options.externalLinkQrEntitled }),
+        {
+          once: true,
+        },
+      );
     } else {
-      applyExternalLinkBehavior();
+      applyExternalLinkBehavior({ externalLinkQrEntitled: options.externalLinkQrEntitled });
     }
   }
 
@@ -139,4 +145,11 @@ export async function runStandardLayoutOrchestration(
       await initVideoPlayers({ prefersReducedMotion });
     });
   }
+
+  // 11. RFC-0932: external-link QR code modal (opt-in via externalLinkQrEntitled: true).
+  // The modal element is rendered by layout-component.astro only on entitled sites.
+  if (options.externalLinkQrEntitled && has("[data-external-link-qr-modal]")) {
+    const { initExternalLinkQr } = await import("./external-link-qr.ts");
+    initExternalLinkQr();
+  }
 }

package/tsconfig.json

@@ -13,7 +13,7 @@
     "allowImportingTsExtensions": true,
     "declaration": true,
     "rewriteRelativeImportExtensions": true,
-    "types": ["node"],
+    "types": ["node", "qrcode"],
     "rootDir": ".",
     "outDir": "dist"
   },