@warpgogol/werkstatt-shared 0.8.5 → 0.8.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warpgogol/werkstatt-shared",
-  "version": "0.8.5",
+  "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"
   },