@warpgogol/werkstatt-shared 0.2.0

package/src/share/scripts/orchestrator.ts

@@ -0,0 +1,138 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Provides a standard orchestration logic for layout-global scripts across all Warpgogol projects.</purpose>
+<non-goals>
+  <item>Do not handle project-specific feature logic directly.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Created standard layout orchestrator in @warpgogol/werkstatt-shared/share/scripts to reduce code duplication in apps.</item>
+</CHANGE_SUMMARY>
+*/
+
+// @ai-invariant: This is a high-risk module. Preserve its core logic and minimize external side effects during modification.
+
+import { applyExternalLinkBehavior } from "./external-links.ts";
+import { initLordIconOnDemand } from "./lordicon.ts";
+import { initLenis } from "./lenis.ts";
+
+export interface OrchestrationOptions {
+  headerOffset?: number;
+  /** RFC-0040: opt in to GSAP stat counter animation. Default false. */
+  counters?: boolean;
+  /** RFC-0041: opt in to GSAP inline number animation for prose sections. Default false. */
+  inlineNumbers?: boolean;
+  /** RFC-0106: opt in to GSAP scroll-triggered reveal animations. Default false. */
+  reveal?: boolean;
+  /** RFC-0106: opt in to GSAP parallax for [data-parallax-speed] elements. Default false. */
+  parallax?: boolean;
+  /** RFC-0106: opt in to GSAP stagger for [data-motion-stagger] parents. Default false. */
+  stagger?: boolean;
+  /** RFC-0202: opt in to the living-photos runtime for [data-live-photo] elements. Default false. */
+  livePhotos?: boolean;
+  /** RFC-0210: opt in to the lazy feature-video player (Plyr + hls.js) for [data-video-player]. Default false. */
+  videoPlayers?: boolean;
+  /** RFC-0205: opt in to Lenis smooth scroll. Default false — avoids loading the 17 KB bundle when not needed. */
+  smoothScroll?: boolean;
+}
+
+const has = (selector: string) => document.querySelector(selector) instanceof Element;
+
+/**
+ * Runs the standard set of browser initializations required for all Warpgogol platform sites.
+ */
+export async function runStandardLayoutOrchestration(
+  options: OrchestrationOptions = {},
+): Promise<void> {
+  const prefersReducedMotion = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+
+  // 1. External links security (mandatory)
+  if (has("a[href]")) {
+    if (document.readyState === "loading") {
+      document.addEventListener("DOMContentLoaded", () => applyExternalLinkBehavior(), {
+        once: true,
+      });
+    } else {
+      applyExternalLinkBehavior();
+    }
+  }
+
+  // 2. LordIcon hydration (mandatory on demand)
+  if (has("lord-icon")) {
+    initLordIconOnDemand();
+  }
+
+  // 3. Lenis smooth scroll (opt-in via smoothScroll: true)
+  if (options.smoothScroll) {
+    await initLenis({
+      prefersReducedMotion,
+      headerOffset: options.headerOffset ?? 80,
+    });
+  }
+
+  // 4. GSAP stat counter (RFC-0040 — opt-in via counters: true)
+  // Note: has() check removed; initGsapCounter internally guards against empty sections.
+  if (options.counters) {
+    const { scheduleTask } = await import("./scheduler.ts");
+    scheduleTask(async () => {
+      const { initGsapCounter } = await import("./gsap-counter.ts");
+      await initGsapCounter({ prefersReducedMotion });
+    });
+  }
+
+  // 5. GSAP inline number animation (RFC-0041 — opt-in via inlineNumbers: true)
+  if (options.inlineNumbers && has(".js-inline-number")) {
+    const { scheduleTask } = await import("./scheduler.ts");
+    scheduleTask(async () => {
+      const { initInlineNumberAnimation } = await import("./inline-number-animation.ts");
+      await initInlineNumberAnimation({ prefersReducedMotion });
+    });
+  }
+
+  // 6. RFC-0106: reveal animations (opt-in via reveal: true).
+  if (options.reveal && has("[data-motion-reveal]")) {
+    const { scheduleTask } = await import("./scheduler.ts");
+    scheduleTask(async () => {
+      const { initGsapReveal } = await import("./gsap-reveal.ts");
+      await initGsapReveal({ prefersReducedMotion });
+    });
+  }
+
+  // 7. RFC-0106: parallax animations (opt-in via parallax: true).
+  if (options.parallax && has("[data-parallax-speed]")) {
+    const { scheduleTask } = await import("./scheduler.ts");
+    scheduleTask(async () => {
+      const { initGsapParallax } = await import("./gsap-parallax.ts");
+      await initGsapParallax({ prefersReducedMotion });
+    });
+  }
+
+  // 8. RFC-0106: stagger animations (opt-in via stagger: true).
+  if (options.stagger && has("[data-motion-stagger]")) {
+    const { scheduleTask } = await import("./scheduler.ts");
+    scheduleTask(async () => {
+      const { initGsapStagger } = await import("./gsap-stagger.ts");
+      await initGsapStagger({ prefersReducedMotion });
+    });
+  }
+
+  // 9. RFC-0202: living photos runtime (opt-in via livePhotos: true).
+  // Only the in-viewport/tap triggers carry [data-trigger]; the autoplay path is native.
+  if (options.livePhotos && has("[data-live-photo][data-trigger]")) {
+    const { scheduleTask } = await import("./scheduler.ts");
+    scheduleTask(async () => {
+      const { initLivePhotos } = await import("./live-photos.ts");
+      await initLivePhotos({ prefersReducedMotion });
+    });
+  }
+
+  // 10. RFC-0210: feature-video player (opt-in via videoPlayers: true).
+  // Lazy Plyr + hls.js, gated on [data-video-player]; nothing loads without a feature video.
+  if (options.videoPlayers && has("video[data-video-player]")) {
+    const { scheduleTask } = await import("./scheduler.ts");
+    scheduleTask(async () => {
+      const { initVideoPlayers } = await import("./video-player.ts");
+      await initVideoPlayers({ prefersReducedMotion });
+    });
+  }
+}

package/src/share/scripts/scheduler.ts

@@ -0,0 +1,53 @@
+/***************************************************************
+<MODULE_CONTRACT>
+<purpose>Facilitates task scheduling and processing in a non-blocking manner, optimizing idle time for execution.</purpose>
+<non-goals>
+  <item>Do not handle task prioritization or dependencies between tasks.</item>
+  <item>Do not parse raw content or manage data fetching here.</item>
+  <item>Do not own transport or configuration orchestration for tasks.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Tidied by compass.changesummary.tidy; see git history for prior entries.</item>
+</CHANGE_SUMMARY>
+***************************************************************/
+
+// @ai-invariant: This is a high-risk module. Preserve its core logic and minimize external side effects during modification.
+// --- Scheduler Start ---
+type Task = () => Promise<void> | void;
+
+const taskQueue: Task[] = [];
+let isTaskRunnerScheduled = false;
+function processTasks(deadline?: { timeRemaining: () => number; didTimeout: boolean }) {
+  isTaskRunnerScheduled = false;
+
+  // If no deadline (setTimeout fallback), simulate a budget
+  const timeRemaining = deadline ? () => deadline.timeRemaining() : () => 16;
+
+  while (taskQueue.length > 0 && (timeRemaining() > 1 || (deadline?.didTimeout ?? false))) {
+    const task = taskQueue.shift();
+    if (task) {
+      void task();
+    }
+  }
+
+  if (taskQueue.length > 0) {
+    isTaskRunnerScheduled = true;
+    if ("requestIdleCallback" in window) {
+      window.requestIdleCallback(processTasks, { timeout: 1000 });
+    } else {
+      setTimeout(processTasks, 50);
+    }
+  }
+}
+export function scheduleTask(task: Task) {
+  taskQueue.push(task);
+  if (!isTaskRunnerScheduled) {
+    isTaskRunnerScheduled = true;
+    if ("requestIdleCallback" in window) {
+      window.requestIdleCallback(processTasks, { timeout: 1000 });
+    } else {
+      setTimeout(processTasks, 50);
+    }
+  }
+} // --- Scheduler End ---

package/src/share/scripts/video-player.ts

@@ -0,0 +1,116 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+  [RFC-0210] Feature-video runtime. Lazily upgrades native <video controls> elements marked
+  [data-video-player] into a branded Plyr player, attaching hls.js for adaptive HLS playback on
+  browsers without native HLS. Follows the RFC-0175 click-to-load / in-viewport posture: nothing
+  is imported until a feature video is near the viewport, so pages without a feature video (and
+  the above-the-fold paint) ship zero player bytes. Resolves and records the playback mode
+  (file|stream) + impl (native|hlsjs|progressive) on the element. Degrades to the native controls
+  if Plyr/hls.js fail to load (progressive enhancement).
+</purpose>
+<non-goals>
+  <item>Do not touch ambient/background <video> — those are native (handled by live-photos).</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0210: introduced the lazy feature-video player runtime.</item>
+</CHANGE_SUMMARY>
+*/
+
+import "plyr/dist/plyr.css";
+
+export interface VideoPlayersOptions {
+  prefersReducedMotion?: boolean;
+}
+
+function nativeHlsSupported(video: HTMLVideoElement): boolean {
+  return video.canPlayType("application/vnd.apple.mpegurl") !== "";
+}
+
+async function upgrade(video: HTMLVideoElement): Promise<void> {
+  if (video.dataset.videoPlayerReady === "true") return;
+  video.dataset.videoPlayerReady = "true";
+
+  const hlsUrl = video.dataset.hls;
+  let mode: "file" | "stream" = "file";
+  let impl: "native" | "hlsjs" | "progressive" = "progressive";
+  let hlsInstance: { destroy: () => void } | null = null;
+
+  if (hlsUrl) {
+    if (nativeHlsSupported(video)) {
+      // Safari/iOS: native HLS — make the manifest the preferred source.
+      const source = document.createElement("source");
+      source.src = hlsUrl;
+      source.type = "application/vnd.apple.mpegurl";
+      video.insertBefore(source, video.firstChild);
+      video.load();
+      mode = "stream";
+      impl = "native";
+    } else {
+      try {
+        const { default: Hls } = await import("hls.js/light");
+        if (Hls.isSupported()) {
+          const hls = new Hls({ enableWorker: true });
+          hls.loadSource(hlsUrl);
+          hls.attachMedia(video);
+          hlsInstance = hls;
+          mode = "stream";
+          impl = "hlsjs";
+        }
+      } catch {
+        /* hls.js unavailable — fall through to progressive MP4 sources */
+      }
+    }
+  }
+
+  video.dataset.playbackMode = mode;
+  video.dataset.playbackImpl = impl;
+
+  // Brand the UI with Plyr (the native controls remain the fallback if this fails).
+  try {
+    const { default: Plyr } = await import("plyr");
+    const player = new Plyr(video, {
+      controls: [
+        "play-large",
+        "play",
+        "progress",
+        "current-time",
+        "mute",
+        "volume",
+        "captions",
+        "fullscreen",
+      ],
+    });
+    // Keep hls.js bound across Plyr's internal media swaps.
+    void player;
+    void hlsInstance;
+  } catch {
+    /* Plyr unavailable — native controls already present */
+  }
+}
+
+export async function initVideoPlayers(_options: VideoPlayersOptions = {}): Promise<void> {
+  const videos = Array.from(
+    document.querySelectorAll<HTMLVideoElement>("video[data-video-player]"),
+  );
+  if (videos.length === 0) return;
+
+  if (!("IntersectionObserver" in window)) {
+    for (const v of videos) await upgrade(v);
+    return;
+  }
+
+  const observer = new IntersectionObserver(
+    (entries, obs) => {
+      for (const entry of entries) {
+        if (!entry.isIntersecting) continue;
+        const video = entry.target as HTMLVideoElement;
+        obs.unobserve(video);
+        void upgrade(video);
+      }
+    },
+    { rootMargin: "200px" },
+  );
+  for (const v of videos) observer.observe(v);
+}

package/src/share/semantic/ai.ts

@@ -0,0 +1,140 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+  RFC-0051 ai.txt generation. Pure function buildAiTxt produces the
+  machine-readable AI policy file from a structured AiPolicy config.
+</purpose>
+<non-goals>
+  <item>Do not read content files or validate input — the caller is responsible.</item>
+  <item>Do not manage default policy fallback — caller decides skip vs fallback.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0051: Initial implementation.</item>
+</CHANGE_SUMMARY>
+*/
+
+export interface AiProviderOverride {
+  name: string;
+  policy: "allow" | "disallow" | "limited";
+  training?: "allow" | "disallow";
+  usage?: string[];
+  commercial?: "yes" | "no";
+  attribution?: "required" | "optional" | "none";
+  license?: string;
+  contact?: string;
+  url?: string;
+}
+
+export interface AiPolicy {
+  policy: "allow" | "disallow" | "limited";
+  training?: "allow" | "disallow";
+  usage?: string[];
+  commercial?: "yes" | "no";
+  attribution?: "required" | "optional" | "none";
+  license?: string;
+  contact?: string;
+  url?: string;
+  version?: string;
+  updated?: string;
+  providers?: AiProviderOverride[];
+}
+
+function formatKeyValue(key: string, value: string | undefined): string | null {
+  if (value === undefined || value === null) return null;
+  return `${key}: ${value}`;
+}
+
+function _formatList(key: string, values: string[] | undefined): string | null {
+  if (!values || values.length === 0) return null;
+  return `${key}: ${values.join(", ")}`;
+}
+
+export function buildAiTxt(policy: AiPolicy, siteUrl: string): string {
+  const lines: string[] = [];
+
+  const headerComment = siteUrl
+    ? `# ai.txt for ${siteUrl.replace(/^https?:\/\//, "")}`
+    : "# ai.txt";
+  lines.push(headerComment);
+  lines.push("# AI training and usage policy");
+  if (policy.url) lines.push(`# See: ${policy.url}`);
+  if (policy.contact) lines.push(`# Contact: ${policy.contact}`);
+  lines.push("");
+
+  const version = policy.version ?? "0.1";
+  const updated = policy.updated ?? new Date().toISOString().slice(0, 10);
+  lines.push(`version: ${version}`);
+  lines.push(`updated: ${updated}`);
+  lines.push("");
+
+  lines.push("# Default policy for AI systems");
+  lines.push(`policy: ${policy.policy}`);
+
+  const optionalGlobalFields: Array<[string, string | undefined]> = [
+    ["license", policy.license],
+    ["url", policy.url],
+    ["contact", policy.contact],
+  ];
+
+  const pushLine = (key: string, val: string | undefined | string[]) => {
+    if (Array.isArray(val) && val.length > 0) {
+      lines.push(`${key}: ${val.join(", ")}`);
+    } else if (typeof val === "string" && val.length > 0) {
+      lines.push(`${key}: ${val}`);
+    }
+  };
+
+  pushLine("training", policy.training);
+  pushLine("usage", policy.usage);
+  pushLine("commercial", policy.commercial);
+  pushLine("attribution", policy.attribution);
+
+  for (const [key, val] of optionalGlobalFields) {
+    const line = formatKeyValue(key, val);
+    if (line) lines.push(line);
+  }
+
+  const unknownKeys = new Set(Object.keys(policy));
+  const knownKeys = new Set([
+    "policy",
+    "training",
+    "usage",
+    "commercial",
+    "attribution",
+    "license",
+    "contact",
+    "url",
+    "version",
+    "updated",
+    "providers",
+  ]);
+  for (const key of unknownKeys) {
+    if (!knownKeys.has(key)) {
+      const val = (policy as unknown as Record<string, unknown>)[key];
+      if (typeof val === "string" && val.length > 0) {
+        lines.push(`${key}: ${val}`);
+      }
+    }
+  }
+
+  if (policy.providers && policy.providers.length > 0) {
+    lines.push("");
+    for (const provider of policy.providers) {
+      lines.push(`[${provider.name}]`);
+      lines.push(`policy: ${provider.policy}`);
+      if (provider.training) lines.push(`training: ${provider.training}`);
+      if (provider.usage && provider.usage.length > 0) {
+        lines.push(`usage: ${provider.usage.join(", ")}`);
+      }
+      if (provider.commercial) lines.push(`commercial: ${provider.commercial}`);
+      if (provider.attribution) lines.push(`attribution: ${provider.attribution}`);
+      if (provider.license) lines.push(`license: ${provider.license}`);
+      if (provider.contact) lines.push(`contact: ${provider.contact}`);
+      if (provider.url) lines.push(`url: ${provider.url}`);
+      lines.push("");
+    }
+  }
+
+  return lines.join("\n").trimEnd() + "\n";
+}

package/src/share/semantic/block-extraction.ts

@@ -0,0 +1,52 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0208: block text extraction types and registry. Declarative extractors map block-based page content into semantic text for markdown twins.</purpose>
+<non-goals>
+  <item>Do not contain extractor implementations — those live in block-extractors/.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0208: introduced block extraction layer for comprehensive markdown twins.</item>
+</CHANGE_SUMMARY>
+*/
+
+export interface ExtractionContext {
+  pageId: string;
+  lang: string;
+  siteUrl: string;
+}
+
+export interface ExtractedBlockContent {
+  heading?: string;
+  lead?: string;
+  body?: string;
+  items?: Array<{ title: string; description?: string }>;
+  sourceBlockId?: string;
+}
+
+export interface BlockTextExtractor<T = unknown> {
+  blockType: string;
+  extract(props: T, ctx: ExtractionContext): ExtractedBlockContent;
+}
+
+export class BlockExtractorRegistry {
+  private extractors = new Map<string, BlockTextExtractor>();
+
+  register<T>(extractor: BlockTextExtractor<T>): void {
+    this.extractors.set(extractor.blockType, extractor as BlockTextExtractor<unknown>);
+  }
+
+  get(blockType: string): BlockTextExtractor | undefined {
+    return this.extractors.get(blockType);
+  }
+
+  has(blockType: string): boolean {
+    return this.extractors.has(blockType);
+  }
+
+  listTypes(): string[] {
+    return Array.from(this.extractors.keys());
+  }
+}
+
+export const BLOCK_EXTRACTORS = new BlockExtractorRegistry();