@warpgogol/werkstatt-shared 0.13.0 → 0.14.0

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

@@ -85,7 +85,7 @@ export function initExternalLinkQr(options?: ExternalLinkQrOptions): void {
 
   async function generateQr(href: string): Promise<void> {
     if (!canvas) return;
-    const { toCanvas } = await import("qrcode");
+    const { toCanvas } = await import("qrcode/lib/browser.js");
     await toCanvas(canvas, href, {
       width: 256,
       margin: 2,
@@ -189,8 +189,16 @@ export function initExternalLinkQr(options?: ExternalLinkQrOptions): void {
     canvas.addEventListener("click", () => {
       const link = openLinkBtn?.getAttribute("href");
       if (link) window.open(link, "_blank", "noopener,noreferrer");
+      closeModal();
+    });
+  }
+
+  if (openLinkBtn) {
+    openLinkBtn.addEventListener("click", () => {
+      closeModal();
     });
   }
 
   attachTriggers();
+  modal.setAttribute("data-external-link-qr-modal-initialized", "true");
 }

package/src/share/scripts/gsap-counter.ts

@@ -165,4 +165,6 @@ export async function initGsapCounter(options: GsapCounterOptions = {}): Promise
       }
     });
   });
+
+  document.documentElement.setAttribute("data-gsap-counter-initialized", "true");
 }

package/src/share/scripts/inline-number-animation.ts

@@ -117,4 +117,6 @@ export async function initInlineNumberAnimation(
       },
     });
   });
+
+  document.documentElement.setAttribute("data-inline-number-initialized", "true");
 }

package/src/share/scripts/live-photos.ts

@@ -247,4 +247,6 @@ export async function initLivePhotos(options: LivePhotosOptions = {}): Promise<v
       }
     });
   }
+
+  document.documentElement.setAttribute("data-live-photos-initialized", "true");
 }

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

@@ -0,0 +1,210 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0950: tests for video-player runtime — conditional Plyr controls, viewport play/pause, HLS+autoplay timing.</purpose>
+<keywords>RFC-0950, video-player, test</keywords>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY><item>RFC-0950: initial video-player tests.</item></CHANGE_SUMMARY>
+*/
+
+import { test, expect, vi, beforeEach, afterEach } from "vitest";
+
+// ── Mocks ───────────────────────────────────────────────────────────────────
+
+vi.mock("plyr", () => ({
+  default: vi.fn(() => ({ destroy: vi.fn() })),
+}));
+
+vi.mock("hls.js/light", () => {
+  const hlsRef = { current: null as any };
+  const fn = vi.fn(function Hls() {
+    return hlsRef.current;
+  });
+  const Hls = Object.assign(fn, {
+    isSupported: vi.fn(() => true),
+    _hlsRef: hlsRef,
+  });
+  return { default: Hls };
+});
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function createMockVideo(attrs: Record<string, string | undefined> = {}): any {
+  const video: any = {
+    dataset: {},
+    canPlayType: vi.fn(() => ""),
+    play: vi.fn(() => Promise.resolve()),
+    pause: vi.fn(),
+    load: vi.fn(),
+    insertBefore: vi.fn(),
+    firstChild: null,
+  };
+  for (const [k, v] of Object.entries(attrs)) {
+    if (v !== undefined) video.dataset[k] = v;
+  }
+  return video;
+}
+
+let observerCallbacks: ((
+  entries: { isIntersecting: boolean; target: any }[],
+  obs: { unobserve: () => void },
+) => void)[] = [];
+let observerOptions: { threshold?: number; rootMargin?: string }[] = [];
+
+class MockIntersectionObserver {
+  callback: (
+    entries: { isIntersecting: boolean; target: any }[],
+    obs: { unobserve: () => void },
+  ) => void;
+  options: { threshold?: number; rootMargin?: string };
+  constructor(
+    cb: (
+      entries: { isIntersecting: boolean; target: any }[],
+      obs: { unobserve: () => void },
+    ) => void,
+    opts: { threshold?: number; rootMargin?: string },
+  ) {
+    this.callback = cb;
+    this.options = opts;
+    observerCallbacks.push(cb);
+    observerOptions.push(opts);
+  }
+  observe = vi.fn();
+  unobserve = vi.fn();
+  disconnect = vi.fn();
+}
+
+// ── Setup / teardown ────────────────────────────────────────────────────────
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  observerCallbacks = [];
+  observerOptions = [];
+  (globalThis as any).IntersectionObserver = MockIntersectionObserver;
+  (globalThis as any).window = globalThis;
+  (globalThis as any).document = {
+    querySelectorAll: vi.fn(() => []),
+    createElement: vi.fn((tag: string) => ({ tagName: tag.toUpperCase() })),
+  };
+});
+
+afterEach(() => {
+  delete (globalThis as any).IntersectionObserver;
+  delete (globalThis as any).window;
+  delete (globalThis as any).document;
+  vi.restoreAllMocks();
+});
+
+async function triggerUpgrade(video: any): Promise<void> {
+  const { initVideoPlayers } = await import("../scripts/video-player.ts");
+  vi.spyOn(globalThis.document as any, "querySelectorAll").mockReturnValue([video]);
+  await initVideoPlayers();
+
+  expect(observerCallbacks.length).toBeGreaterThanOrEqual(1);
+  observerCallbacks[0]!([{ isIntersecting: true, target: video }], { unobserve: vi.fn() });
+  await new Promise((r) => setTimeout(r, 100));
+}
+
+// ── Tests ───────────────────────────────────────────────────────────────────
+
+test("initVideoPlayers: returns early when no [data-video-player] elements", async () => {
+  const querySelectorAll = vi.spyOn(globalThis.document as any, "querySelectorAll");
+  querySelectorAll.mockReturnValue([]);
+  const { initVideoPlayers } = await import("../scripts/video-player.ts");
+  await initVideoPlayers();
+  expect(observerCallbacks.length).toBe(0);
+  querySelectorAll.mockRestore();
+});
+
+test("upgrade: data-controls='false' configures Plyr with only ['mute']", async () => {
+  const video = createMockVideo({ controls: "false" });
+  await triggerUpgrade(video);
+
+  const Plyr = (await import("plyr")).default;
+  expect(Plyr).toHaveBeenCalledWith(video, expect.objectContaining({ controls: ["mute"] }));
+});
+
+test("upgrade: without data-controls uses full Plyr controls list", async () => {
+  const video = createMockVideo({});
+  await triggerUpgrade(video);
+
+  const Plyr = (await import("plyr")).default;
+  expect(Plyr).toHaveBeenCalledWith(
+    video,
+    expect.objectContaining({
+      controls: expect.arrayContaining([
+        "play-large",
+        "play",
+        "progress",
+        "current-time",
+        "mute",
+        "volume",
+        "captions",
+        "fullscreen",
+      ]),
+    }),
+  );
+});
+
+test("upgrade: data-autoplay='true' sets up viewport play/pause observer with threshold 0.5", async () => {
+  const video = createMockVideo({ autoplay: "true" });
+  await triggerUpgrade(video);
+
+  const playPauseOpts = observerOptions.find((o) => o.threshold === 0.5);
+  expect(
+    playPauseOpts,
+    "play/pause observer with threshold 0.5 must be created when data-autoplay is true",
+  ).toBeDefined();
+});
+
+test("upgrade: data-autoplay='true' with HLS waits for MEDIA_ATTACHED before play()", async () => {
+  const video = createMockVideo({ autoplay: "true", hls: "https://example.com/stream.m3u8" });
+
+  const hlsInstance = {
+    loadSource: vi.fn(),
+    attachMedia: vi.fn(),
+    destroy: vi.fn(),
+    on: vi.fn(),
+  };
+  const Hls = (await import("hls.js/light")).default as any;
+  Hls._hlsRef.current = hlsInstance;
+
+  await triggerUpgrade(video);
+
+  expect(Hls).toHaveBeenCalled();
+  expect(hlsInstance.attachMedia).toHaveBeenCalledWith(video);
+
+  const attachedCall = hlsInstance.on.mock.calls.find((c: any[]) => c[0] === "hls.MEDIA_ATTACHED");
+  expect(attachedCall, "Hls must register a MEDIA_ATTACHED listener before play()").toBeDefined();
+  attachedCall![1]();
+
+  await new Promise((r) => setTimeout(r, 20));
+  expect(video.play).toHaveBeenCalled();
+});
+
+test("upgrade: data-autoplay='true' without HLS calls play() directly", async () => {
+  const video = createMockVideo({ autoplay: "true" });
+  await triggerUpgrade(video);
+
+  expect(video.play).toHaveBeenCalled();
+});
+
+test("upgrade: skip already-upgraded videos (data-video-player-ready='true')", async () => {
+  const video = createMockVideo({ videoPlayerReady: "true" });
+  await triggerUpgrade(video);
+
+  const Plyr = (await import("plyr")).default;
+  expect(Plyr).not.toHaveBeenCalled();
+});
+
+test("upgrade: viewport observer pauses video when scrolled out", async () => {
+  const video = createMockVideo({ autoplay: "true" });
+  await triggerUpgrade(video);
+
+  const playPauseIdx = observerOptions.findIndex((o) => o.threshold === 0.5);
+  expect(playPauseIdx).toBeGreaterThan(-1);
+
+  observerCallbacks[playPauseIdx]!([{ isIntersecting: false, target: video }], {
+    unobserve: vi.fn(),
+  });
+  expect(video.pause).toHaveBeenCalled();
+});

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

@@ -15,6 +15,7 @@
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0210: introduced the lazy feature-video player runtime.</item>
+  <item>RFC-0950: added viewport play/pause observer, conditional Plyr controls, and HLS+autoplay timing.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -33,9 +34,11 @@ async function upgrade(video: HTMLVideoElement): Promise<void> {
   video.dataset.videoPlayerReady = "true";
 
   const hlsUrl = video.dataset.hls;
+  const autoplay = video.dataset.autoplay === "true";
+  const controlsDisabled = video.dataset.controls === "false";
   let mode: "file" | "stream" = "file";
   let impl: "native" | "hlsjs" | "progressive" = "progressive";
-  let hlsInstance: { destroy: () => void } | null = null;
+  let hlsInstance: unknown = null;
 
   if (hlsUrl) {
     if (nativeHlsSupported(video)) {
@@ -70,24 +73,81 @@ async function upgrade(video: HTMLVideoElement): Promise<void> {
   // 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",
-      ],
-    });
+    const plyrControls = controlsDisabled
+      ? ["mute"]
+      : [
+          "play-large",
+          "play",
+          "progress",
+          "current-time",
+          "mute",
+          "volume",
+          "captions",
+          "fullscreen",
+        ];
+    const player = new Plyr(video, { controls: plyrControls });
     // Keep hls.js bound across Plyr's internal media swaps.
     void player;
     void hlsInstance;
   } catch {
     /* Plyr unavailable — native controls already present */
   }
+
+  // RFC-0950: viewport play/pause for autoplay-enabled videos.
+  if (autoplay) {
+    await playWhenReady(
+      video,
+      hlsInstance as { on: (event: string, listener: () => void) => void } | null,
+    );
+    setupViewportObserver(video);
+  }
+}
+
+async function playWhenReady(
+  video: HTMLVideoElement,
+  hls: { on: (event: string, listener: () => void) => void } | null,
+): Promise<void> {
+  if (hls) {
+    // Wait for hls.js to attach media before calling play().
+    await new Promise<void>((resolve) => {
+      let resolved = false;
+      const timeout = setTimeout(() => {
+        if (!resolved) {
+          resolved = true;
+          resolve();
+        }
+      }, 200);
+      hls.on("hls.MEDIA_ATTACHED", () => {
+        if (!resolved) {
+          resolved = true;
+          clearTimeout(timeout);
+          resolve();
+        }
+      });
+    });
+  }
+  try {
+    await video.play();
+  } catch {
+    /* Autoplay may be blocked by browser policy — user can interact via controls. */
+  }
+}
+
+function setupViewportObserver(video: HTMLVideoElement): void {
+  if (!("IntersectionObserver" in window)) return;
+  const observer = new IntersectionObserver(
+    (entries) => {
+      for (const entry of entries) {
+        if (entry.isIntersecting) {
+          void video.play().catch(() => {});
+        } else {
+          video.pause();
+        }
+      }
+    },
+    { threshold: 0.5 },
+  );
+  observer.observe(video);
 }
 
 export async function initVideoPlayers(_options: VideoPlayersOptions = {}): Promise<void> {

package/src/share/semantic/extract.ts

@@ -68,8 +68,32 @@ const SENTENCE_ABBREVIATIONS: Record<string, string[]> = {
     "u.",
     "vgl.",
     "bspw.",
+    "zzgl.",
+    "inkl.",
+    "exkl.",
+    "bzw.",
+    "ggf.",
+    "ggfls.",
+    "sog.",
+    "o.Ä.",
+  ],
+  uk: [
+    "т.д.",
+    "т.п.",
+    "п.",
+    "ст.",
+    "див.",
+    "пор.",
+    "напр.",
+    "ім.",
+    "о.",
+    "вкл.",
+    "тис.",
+    "млн.",
+    "млрд.",
+    "грн.",
+    "№",
   ],
-  uk: ["т.д.", "т.п.", "п.", "ст.", "див.", "пор.", "напр.", "ім.", "о."],
   en: ["e.g.", "i.e.", "etc.", "vs.", "Mr.", "Mrs.", "Dr.", "Inc.", "Ltd."],
 };
 

package/src/share/semantic/tests/split-sentences.test.ts

@@ -94,4 +94,61 @@ describe("splitSentences", () => {
     expect(result[0]).toBe("Das Studio kann nicht wesentliche Prozesse (z. B. Werkzeuge) ändern.");
     expect(result[1]).toBe("Der wesentliche Leistungsumfang kann nicht einseitig geändert werden.");
   });
+
+  it("does not split on German business abbreviation zzgl.", () => {
+    const result = splitSentences(
+      "€ 49 / Monat (zzgl. USt.) — entspricht 10 Monaten. Zwei Monate gratis.",
+      "de",
+    );
+    expect(result).toHaveLength(2);
+    expect(result[0]).toBe("€ 49 / Monat (zzgl. USt.) — entspricht 10 Monaten.");
+    expect(result[1]).toBe("Zwei Monate gratis.");
+  });
+
+  it("does not split on German abbreviation inkl.", () => {
+    const result = splitSentences(
+      "Das Paket enthält Hosting (inkl. SSL-Zertifikat). Das ist ein guter Deal.",
+      "de",
+    );
+    expect(result).toHaveLength(2);
+    expect(result[0]).toBe("Das Paket enthält Hosting (inkl. SSL-Zertifikat).");
+    expect(result[1]).toBe("Das ist ein guter Deal.");
+  });
+
+  it("does not split on German abbreviation bzw.", () => {
+    const result = splitSentences(
+      "Rechnungen werden monatlich bzw. jährlich erstellt. Das ist fair.",
+      "de",
+    );
+    expect(result).toHaveLength(2);
+    expect(result[0]).toBe("Rechnungen werden monatlich bzw. jährlich erstellt.");
+    expect(result[1]).toBe("Das ist fair.");
+  });
+
+  it("does not split on German abbreviation ggf.", () => {
+    const result = splitSentences(
+      "Der Kunde kann ggf. weitere Module buchen. Das ist optional.",
+      "de",
+    );
+    expect(result).toHaveLength(2);
+    expect(result[0]).toBe("Der Kunde kann ggf. weitere Module buchen.");
+    expect(result[1]).toBe("Das ist optional.");
+  });
+
+  it("does not split on Ukrainian abbreviation тис.", () => {
+    const result = splitSentences(
+      "Вартість складає 5 тис. гривень на місяць. Це вигідна пропозиція.",
+      "uk",
+    );
+    expect(result).toHaveLength(2);
+    expect(result[0]).toBe("Вартість складає 5 тис. гривень на місяць.");
+    expect(result[1]).toBe("Це вигідна пропозиція.");
+  });
+
+  it("does not split on Ukrainian abbreviation грн.", () => {
+    const result = splitSentences("Ціна: 1000 грн. за місяць. Друге речення.", "uk");
+    expect(result).toHaveLength(2);
+    expect(result[0]).toBe("Ціна: 1000 грн. за місяць.");
+    expect(result[1]).toBe("Друге речення.");
+  });
 });

package/src/share/tests/manifest.test.ts

@@ -8,6 +8,7 @@
 </MODULE_MAP>
 <CHANGE_SUMMARY>
   <item>RFC-0286: initial builder tests.</item>
+  <item>RFC-0954: add search interface tests.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -16,6 +17,7 @@ import {
   AGENT_SURFACE_VERSION,
   buildAgentSurfaceManifest,
   computeAgentManifestContentHash,
+  computeSignedContentHash,
   canonicalJson,
 } from "../agent/manifest.ts";
 
@@ -38,6 +40,7 @@ test("buildAgentSurfaceManifest: safe default — empty knowledge/actions, null
   expect(m.interfaces.openapi).toBe(null);
   expect(m.interfaces.mcp).toBe(null);
   expect(m.interfaces.twins).toBe(null);
+  expect(m.interfaces.search).toBe(null);
   expect(m.proof).toBe(null);
   expect(m.surfaceVersion).toBe(AGENT_SURFACE_VERSION);
 });
@@ -81,6 +84,32 @@ test("buildAgentSurfaceManifest: sorts knowledge refs by domain and actions by i
   expect(m.actions.map((a) => a.id)).toEqual(["appointment.request", "lead.submit"]);
 });
 
+test("buildAgentSurfaceManifest: populates search interface when search input is provided", () => {
+  const m = buildAgentSurfaceManifest({
+    ...baseInput,
+    search: { url: "/api/agent/search", model: "@cf/baai/bge-m3", dimensions: 1024 },
+  });
+  expect(m.interfaces.search).toEqual({
+    url: "/api/agent/search",
+    model: "@cf/baai/bge-m3",
+    dimensions: 1024,
+  });
+});
+
+test("buildAgentSurfaceManifest: search interface is null by default", () => {
+  const m = buildAgentSurfaceManifest(baseInput);
+  expect(m.interfaces.search).toBe(null);
+});
+
+test("buildAgentSurfaceManifest: search interface presence changes contentHash", () => {
+  const without = buildAgentSurfaceManifest(baseInput);
+  const withSearch = buildAgentSurfaceManifest({
+    ...baseInput,
+    search: { url: "/api/agent/search", model: "@cf/baai/bge-m3", dimensions: 1024 },
+  });
+  expect(without.contentHash).not.toBe(withSearch.contentHash);
+});
+
 test("computeAgentManifestContentHash: excludes contentHash and proof fields from the hash input", () => {
   const doc: Record<string, unknown> = { a: 1, b: 2, contentHash: "whatever", proof: { x: 1 } };
   const withoutHashFields = { a: 1, b: 2 };
@@ -98,3 +127,25 @@ test("canonicalJson: sorts object keys deeply, preserves array order", () => {
   expect(canonicalJson({ b: 1, a: { d: 2, c: 3 } })).toBe('{"a":{"c":3,"d":2},"b":1}');
   expect(canonicalJson([3, 1, 2])).toBe("[3,1,2]");
 });
+
+test("computeSignedContentHash: always excludes contentHash and proof", () => {
+  const base = { a: 1, b: 2 };
+  const withHash = { ...base, contentHash: "abc", proof: { type: "test" } };
+  const withDifferentHash = { ...base, contentHash: "xyz", proof: { type: "other" } };
+  expect(computeSignedContentHash(withHash)).toBe(computeSignedContentHash(base));
+  expect(computeSignedContentHash(withDifferentHash)).toBe(computeSignedContentHash(base));
+});
+
+test("computeSignedContentHash: supports additional excludeFields", () => {
+  const base = { a: 1, b: 2 };
+  const withTimestamp = { ...base, generatedAt: "2026-01-01T00:00:00Z" };
+  const withDifferentTimestamp = { ...base, generatedAt: "2026-12-31T23:59:59Z" };
+  expect(computeSignedContentHash(withTimestamp, ["generatedAt"])).toBe(
+    computeSignedContentHash(withDifferentTimestamp, ["generatedAt"]),
+  );
+});
+
+test("computeSignedContentHash: matches computeAgentManifestContentHash for same inputs", () => {
+  const doc = { a: 1, b: 2, contentHash: "x", proof: null };
+  expect(computeSignedContentHash(doc)).toBe(computeAgentManifestContentHash(doc));
+});

package/src/share/tests/openapi.test.ts

@@ -8,6 +8,7 @@
 </MODULE_MAP>
 <CHANGE_SUMMARY>
   <item>RFC-0289: initial OpenAPI formatter tests.</item>
+  <item>RFC-0954: add search path projection tests.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -114,3 +115,32 @@ test("formatAgentOpenApi: mcp interface present → x-gogol-mcp is set", () => {
   const doc = formatAgentOpenApi(manifest, []);
   expect(doc["x-gogol-mcp"]).toEqual({ url: "/api/agent/mcp", protocolVersion: "2025-06-18" });
 });
+
+test("formatAgentOpenApi: search interface present → /api/agent/search GET path with dynamic lang enum", () => {
+  const manifest = buildAgentSurfaceManifest({
+    site: "s",
+    baseUrl: "https://s.example",
+    languages: { default: "de", supported: ["de", "uk"] },
+    search: { url: "/api/agent/search", model: "@cf/baai/bge-m3", dimensions: 1024 },
+  });
+  const doc = formatAgentOpenApi(manifest, []);
+  const op = doc.paths["/api/agent/search"]?.get;
+  expect(op).toBeTruthy();
+  expect(op!.operationId).toBe("search.query");
+  expect(op!.tags).toEqual(["search"]);
+  expect(doc.components.schemas["search-response"]).toBeTruthy();
+  const langParam = op!.parameters!.find((p: { name: string }) => p.name === "lang");
+  expect(langParam).toBeTruthy();
+  expect(langParam!.schema.enum).toEqual(["de", "uk"]);
+});
+
+test("formatAgentOpenApi: search interface absent → no search path", () => {
+  const manifest = buildAgentSurfaceManifest({
+    site: "s",
+    baseUrl: "https://s.example",
+    languages: { default: "de", supported: ["de"] },
+  });
+  const doc = formatAgentOpenApi(manifest, []);
+  expect(doc.paths["/api/agent/search"]).toBe(undefined);
+  expect(doc.components.schemas["search-response"]).toBe(undefined);
+});

package/src/share/types/qrcode-browser.d.ts

@@ -0,0 +1,18 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Type shim for the qrcode browser entry point (qrcode/lib/browser.js).
+The qrcode package only ships types for its main entry, but the browser entry
+exports the same toCanvas function. This shim re-exports all types from qrcode
+so the client-side QR code script gets full type safety.</purpose>
+<non-goals>
+  <item>Do not change runtime resolution; this file only fills the missing package declaration.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Add type declaration for qrcode/lib/browser.js deep import used by external-link-qr.ts.</item>
+</CHANGE_SUMMARY>
+*/
+
+declare module "qrcode/lib/browser.js" {
+  export * from "qrcode";
+}

package/src/share/utility-registry.yaml

@@ -3,8 +3,8 @@ utilities:
     canonicalPath: packages/werkstatt-shared/src/share/slug/
     forbiddenImports:
       - "@sindresorhus/slugify"
-      - "cyrillic-to-translit-js"
-      - "github-slugger"
+      - cyrillic-to-translit-js
+      - github-slugger
     functionNames:
       - slugify
       - toSlug