@open-slide/core 1.7.0 → 1.9.0

package/src/app/lib/export-pptx.ts

@@ -0,0 +1,284 @@
+import { createElement } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { designToCssVars } from './design';
+import { SlidePageProvider } from './page-context';
+import { isFrameAnimationSettled, waitForDataWaitfor, waitForFonts } from './print-ready';
+import type { SlideModule } from './sdk';
+
+const SLIDE_W = 1920;
+const SLIDE_H = 1080;
+// 16:9 widescreen in English Metric Units (914400 EMU per inch → 13.333in × 7.5in).
+const EMU_W = 12192000;
+const EMU_H = 6858000;
+const CAPTURE_PIXEL_RATIO = 2;
+
+const ANIMATION_TIMEOUT_MS = 15_000;
+const POLL_INTERVAL_MS = 100;
+
+const CAPTURE_CLASS = 'os-pptx-capture';
+const CAPTURE_STYLE_ID = 'os-pptx-capture-style';
+// Properties intro animations drive from a hidden start state to a visible end
+// state. We read them back once settled and pin them inline so the capture clone
+// can't re-run the keyframes from their invisible 0% frame (see freezeForCapture).
+const FROZEN_PROPS = ['opacity', 'transform', 'filter', 'clip-path'] as const;
+
+export type PptxExportProgress = {
+  phase: 'processing' | 'generating' | 'done';
+  /** Number of pages captured so far (0..total). */
+  current: number;
+  total: number;
+  /** 0–95 while capturing, 98 while assembling, 100 when done. */
+  percent: number;
+};
+
+export async function exportSlideAsImagePptx(
+  slide: SlideModule,
+  slideId: string,
+  onProgress?: (progress: PptxExportProgress) => void,
+): Promise<void> {
+  const pages = slide.default ?? [];
+  if (pages.length === 0) return;
+
+  const total = pages.length;
+  onProgress?.({ phase: 'processing', current: 0, total, percent: 0 });
+
+  const container = document.createElement('div');
+  container.className = CAPTURE_CLASS;
+  container.setAttribute('aria-hidden', 'true');
+  Object.assign(container.style, {
+    position: 'fixed',
+    left: '-99999px',
+    top: '0',
+    pointerEvents: 'none',
+  });
+  document.body.appendChild(container);
+
+  // html-to-image clones each frame and copies its computed style — including the
+  // intro animation — into the clone, which then re-runs the keyframes from their
+  // hidden 0% frame in the rasterised SVG. Fast-forward every animation to its end
+  // frame in the live DOM (a large negative delay lands past a 1ms duration, so
+  // even pseudo-elements paint their final state on the first frame).
+  const captureStyle = document.createElement('style');
+  captureStyle.id = CAPTURE_STYLE_ID;
+  captureStyle.textContent = `.${CAPTURE_CLASS} *, .${CAPTURE_CLASS} *::before, .${CAPTURE_CLASS} *::after {
+    animation-delay: -1s !important;
+    animation-duration: 1ms !important;
+    animation-iteration-count: 1 !important;
+    animation-fill-mode: forwards !important;
+    transition: none !important;
+  }`;
+  document.head.appendChild(captureStyle);
+
+  const designVars = slide.design ? designToCssVars(slide.design) : null;
+
+  const reactRoots: Root[] = [];
+  const frames: HTMLElement[] = [];
+  for (let i = 0; i < pages.length; i++) {
+    const Page = pages[i];
+    if (!Page) continue;
+    const host = document.createElement('div');
+    host.setAttribute('data-osd-canvas', '');
+    host.style.width = `${SLIDE_W}px`;
+    host.style.height = `${SLIDE_H}px`;
+    host.style.overflow = 'hidden';
+    host.style.background = '#fff';
+    if (designVars) {
+      for (const [k, v] of Object.entries(designVars)) host.style.setProperty(k, v);
+    }
+    container.appendChild(host);
+    frames.push(host);
+    const r = createRoot(host);
+    r.render(
+      createElement(SlidePageProvider, { index: i, total: pages.length }, createElement(Page)),
+    );
+    reactRoots.push(r);
+  }
+  // Yield once so React commits all pages and intro animations actually start.
+  await nextPaint();
+
+  try {
+    await waitForFonts();
+
+    const deadline = performance.now() + ANIMATION_TIMEOUT_MS;
+    while (performance.now() < deadline) {
+      const settled = frames.every((frame) => isFrameAnimationSettled(frame));
+      if (settled) break;
+      await sleep(POLL_INTERVAL_MS);
+    }
+    await waitForDataWaitfor(container);
+
+    const { toBlob } = await import('html-to-image');
+    const images: Uint8Array[] = [];
+    for (let i = 0; i < frames.length; i++) {
+      freezeForCapture(frames[i]);
+      const blob = await toBlob(frames[i], {
+        width: SLIDE_W,
+        height: SLIDE_H,
+        pixelRatio: CAPTURE_PIXEL_RATIO,
+        backgroundColor: '#ffffff',
+        cacheBust: true,
+      });
+      if (!blob) throw new Error(`failed to capture page ${i + 1}`);
+      images.push(new Uint8Array(await blob.arrayBuffer()));
+      onProgress?.({
+        phase: 'processing',
+        current: i + 1,
+        total,
+        percent: Math.min(95, ((i + 1) / total) * 95),
+      });
+    }
+
+    onProgress?.({ phase: 'generating', current: total, total, percent: 98 });
+    const pptx = await buildImagePptx(images);
+    downloadBlob(
+      new Blob([pptx as BlobPart], {
+        type: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+      }),
+      `${slideId}.pptx`,
+    );
+  } finally {
+    onProgress?.({ phase: 'done', current: total, total, percent: 100 });
+    for (const r of reactRoots) r.unmount();
+    container.remove();
+    captureStyle.remove();
+  }
+}
+
+// Pin each element's settled visual state inline and remove its animation so the
+// clone html-to-image rasterises renders the final frame instead of replaying the
+// (initially invisible) keyframes. Pseudo-elements are handled by CAPTURE_STYLE_ID.
+function freezeForCapture(root: HTMLElement): void {
+  for (const el of root.querySelectorAll<HTMLElement>('*')) {
+    const cs = getComputedStyle(el);
+    for (const prop of FROZEN_PROPS) {
+      el.style.setProperty(prop, cs.getPropertyValue(prop), 'important');
+    }
+    el.style.setProperty('animation', 'none', 'important');
+    el.style.setProperty('transition', 'none', 'important');
+  }
+}
+
+const XML_DECL = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n';
+const REL_NS = 'http://schemas.openxmlformats.org/package/2006/relationships';
+const OD_REL = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships';
+
+async function buildImagePptx(images: Uint8Array[]): Promise<Uint8Array> {
+  const { zipSync, strToU8 } = await import('fflate');
+  const n = images.length;
+  const files: Record<string, Uint8Array> = {};
+
+  files['[Content_Types].xml'] = strToU8(contentTypesXml(n));
+  files['_rels/.rels'] = strToU8(rootRelsXml());
+  files['ppt/presentation.xml'] = strToU8(presentationXml(n));
+  files['ppt/_rels/presentation.xml.rels'] = strToU8(presentationRelsXml(n));
+  files['ppt/presProps.xml'] = strToU8(presPropsXml());
+  files['ppt/theme/theme1.xml'] = strToU8(themeXml());
+  files['ppt/slideMasters/slideMaster1.xml'] = strToU8(slideMasterXml());
+  files['ppt/slideMasters/_rels/slideMaster1.xml.rels'] = strToU8(slideMasterRelsXml());
+  files['ppt/slideLayouts/slideLayout1.xml'] = strToU8(slideLayoutXml());
+  files['ppt/slideLayouts/_rels/slideLayout1.xml.rels'] = strToU8(slideLayoutRelsXml());
+
+  for (let i = 0; i < n; i++) {
+    const idx = i + 1;
+    files[`ppt/slides/slide${idx}.xml`] = strToU8(slideXml());
+    files[`ppt/slides/_rels/slide${idx}.xml.rels`] = strToU8(slideRelsXml(idx));
+    files[`ppt/media/image${idx}.png`] = images[i];
+  }
+
+  return zipSync(files);
+}
+
+function contentTypesXml(n: number): string {
+  const slideOverrides = Array.from(
+    { length: n },
+    (_, i) =>
+      `<Override PartName="/ppt/slides/slide${i + 1}.xml" ContentType="application/vnd.openxmlformats-officedocument.presentationml.slide+xml"/>`,
+  ).join('');
+  return `${XML_DECL}<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types"><Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/><Default Extension="xml" ContentType="application/xml"/><Default Extension="png" ContentType="image/png"/><Override PartName="/ppt/presentation.xml" ContentType="application/vnd.openxmlformats-officedocument.presentationml.presentation.main+xml"/><Override PartName="/ppt/presProps.xml" ContentType="application/vnd.openxmlformats-officedocument.presentationml.presProps+xml"/><Override PartName="/ppt/slideMasters/slideMaster1.xml" ContentType="application/vnd.openxmlformats-officedocument.presentationml.slideMaster+xml"/><Override PartName="/ppt/slideLayouts/slideLayout1.xml" ContentType="application/vnd.openxmlformats-officedocument.presentationml.slideLayout+xml"/><Override PartName="/ppt/theme/theme1.xml" ContentType="application/vnd.openxmlformats-officedocument.theme+xml"/>${slideOverrides}</Types>`;
+}
+
+function rootRelsXml(): string {
+  return `${XML_DECL}<Relationships xmlns="${REL_NS}"><Relationship Id="rId1" Type="${OD_REL}/officeDocument" Target="ppt/presentation.xml"/></Relationships>`;
+}
+
+function presentationXml(n: number): string {
+  const sldIds = Array.from(
+    { length: n },
+    (_, i) => `<p:sldId id="${256 + i}" r:id="rId${i + 3}"/>`,
+  ).join('');
+  return `${XML_DECL}<p:presentation xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" xmlns:r="${OD_REL}" xmlns:p="http://schemas.openxmlformats.org/presentationml/2006/main"><p:sldMasterIdLst><p:sldMasterId id="2147483648" r:id="rId1"/></p:sldMasterIdLst><p:sldIdLst>${sldIds}</p:sldIdLst><p:sldSz cx="${EMU_W}" cy="${EMU_H}"/><p:notesSz cx="6858000" cy="9144000"/></p:presentation>`;
+}
+
+function presentationRelsXml(n: number): string {
+  const rels = [
+    `<Relationship Id="rId1" Type="${OD_REL}/slideMaster" Target="slideMasters/slideMaster1.xml"/>`,
+    `<Relationship Id="rId2" Type="${OD_REL}/presProps" Target="presProps.xml"/>`,
+  ];
+  for (let i = 0; i < n; i++) {
+    rels.push(
+      `<Relationship Id="rId${i + 3}" Type="${OD_REL}/slide" Target="slides/slide${i + 1}.xml"/>`,
+    );
+  }
+  return `${XML_DECL}<Relationships xmlns="${REL_NS}">${rels.join('')}</Relationships>`;
+}
+
+function presPropsXml(): string {
+  return `${XML_DECL}<p:presentationPr xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" xmlns:r="${OD_REL}" xmlns:p="http://schemas.openxmlformats.org/presentationml/2006/main"/>`;
+}
+
+function slideMasterXml(): string {
+  return `${XML_DECL}<p:sldMaster xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" xmlns:r="${OD_REL}" xmlns:p="http://schemas.openxmlformats.org/presentationml/2006/main"><p:cSld><p:spTree><p:nvGrpSpPr><p:cNvPr id="1" name=""/><p:cNvGrpSpPr/><p:nvPr/></p:nvGrpSpPr><p:grpSpPr><a:xfrm><a:off x="0" y="0"/><a:ext cx="0" cy="0"/><a:chOff x="0" y="0"/><a:chExt cx="0" cy="0"/></a:xfrm></p:grpSpPr></p:spTree></p:cSld><p:clrMap bg1="lt1" tx1="dk1" bg2="lt2" tx2="dk2" accent1="accent1" accent2="accent2" accent3="accent3" accent4="accent4" accent5="accent5" accent6="accent6" hlink="hlink" folHlink="folHlink"/><p:sldLayoutIdLst><p:sldLayoutId id="2147483649" r:id="rId1"/></p:sldLayoutIdLst></p:sldMaster>`;
+}
+
+function slideMasterRelsXml(): string {
+  return `${XML_DECL}<Relationships xmlns="${REL_NS}"><Relationship Id="rId1" Type="${OD_REL}/slideLayout" Target="../slideLayouts/slideLayout1.xml"/><Relationship Id="rId2" Type="${OD_REL}/theme" Target="../theme/theme1.xml"/></Relationships>`;
+}
+
+function slideLayoutXml(): string {
+  return `${XML_DECL}<p:sldLayout xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" xmlns:r="${OD_REL}" xmlns:p="http://schemas.openxmlformats.org/presentationml/2006/main" type="blank" preserve="1"><p:cSld name="Blank"><p:spTree><p:nvGrpSpPr><p:cNvPr id="1" name=""/><p:cNvGrpSpPr/><p:nvPr/></p:nvGrpSpPr><p:grpSpPr><a:xfrm><a:off x="0" y="0"/><a:ext cx="0" cy="0"/><a:chOff x="0" y="0"/><a:chExt cx="0" cy="0"/></a:xfrm></p:grpSpPr></p:spTree></p:cSld><p:clrMapOvr><a:masterClrMapping/></p:clrMapOvr></p:sldLayout>`;
+}
+
+function slideLayoutRelsXml(): string {
+  return `${XML_DECL}<Relationships xmlns="${REL_NS}"><Relationship Id="rId1" Type="${OD_REL}/slideMaster" Target="../slideMasters/slideMaster1.xml"/></Relationships>`;
+}
+
+function slideXml(): string {
+  return `${XML_DECL}<p:sld xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" xmlns:r="${OD_REL}" xmlns:p="http://schemas.openxmlformats.org/presentationml/2006/main"><p:cSld><p:spTree><p:nvGrpSpPr><p:cNvPr id="1" name=""/><p:cNvGrpSpPr/><p:nvPr/></p:nvGrpSpPr><p:grpSpPr><a:xfrm><a:off x="0" y="0"/><a:ext cx="0" cy="0"/><a:chOff x="0" y="0"/><a:chExt cx="0" cy="0"/></a:xfrm></p:grpSpPr><p:pic><p:nvPicPr><p:cNvPr id="2" name="Slide"/><p:cNvPicPr><a:picLocks noChangeAspect="1"/></p:cNvPicPr><p:nvPr/></p:nvPicPr><p:blipFill><a:blip r:embed="rId2"/><a:stretch><a:fillRect/></a:stretch></p:blipFill><p:spPr><a:xfrm><a:off x="0" y="0"/><a:ext cx="${EMU_W}" cy="${EMU_H}"/></a:xfrm><a:prstGeom prst="rect"><a:avLst/></a:prstGeom></p:spPr></p:pic></p:spTree></p:cSld><p:clrMapOvr><a:masterClrMapping/></p:clrMapOvr></p:sld>`;
+}
+
+function slideRelsXml(idx: number): string {
+  return `${XML_DECL}<Relationships xmlns="${REL_NS}"><Relationship Id="rId1" Type="${OD_REL}/slideLayout" Target="../slideLayouts/slideLayout1.xml"/><Relationship Id="rId2" Type="${OD_REL}/image" Target="../media/image${idx}.png"/></Relationships>`;
+}
+
+function themeXml(): string {
+  return `${XML_DECL}<a:theme xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" name="Office Theme"><a:themeElements><a:clrScheme name="Office"><a:dk1><a:sysClr val="windowText" lastClr="000000"/></a:dk1><a:lt1><a:sysClr val="window" lastClr="FFFFFF"/></a:lt1><a:dk2><a:srgbClr val="44546A"/></a:dk2><a:lt2><a:srgbClr val="E7E6E6"/></a:lt2><a:accent1><a:srgbClr val="4472C4"/></a:accent1><a:accent2><a:srgbClr val="ED7D31"/></a:accent2><a:accent3><a:srgbClr val="A5A5A5"/></a:accent3><a:accent4><a:srgbClr val="FFC000"/></a:accent4><a:accent5><a:srgbClr val="5B9BD5"/></a:accent5><a:accent6><a:srgbClr val="70AD47"/></a:accent6><a:hlink><a:srgbClr val="0563C1"/></a:hlink><a:folHlink><a:srgbClr val="954F72"/></a:folHlink></a:clrScheme><a:fontScheme name="Office"><a:majorFont><a:latin typeface="Calibri Light"/><a:ea typeface=""/><a:cs typeface=""/></a:majorFont><a:minorFont><a:latin typeface="Calibri"/><a:ea typeface=""/><a:cs typeface=""/></a:minorFont></a:fontScheme><a:fmtScheme name="Office"><a:fillStyleLst><a:solidFill><a:schemeClr val="phClr"/></a:solidFill><a:gradFill rotWithShape="1"><a:gsLst><a:gs pos="0"><a:schemeClr val="phClr"><a:lumMod val="110000"/><a:satMod val="105000"/><a:tint val="67000"/></a:schemeClr></a:gs><a:gs pos="50000"><a:schemeClr val="phClr"><a:lumMod val="105000"/><a:satMod val="103000"/><a:tint val="73000"/></a:schemeClr></a:gs><a:gs pos="100000"><a:schemeClr val="phClr"><a:lumMod val="105000"/><a:satMod val="109000"/><a:tint val="81000"/></a:schemeClr></a:gs></a:gsLst><a:lin ang="5400000" scaled="0"/></a:gradFill></a:fillStyleLst><a:lnStyleLst><a:ln w="6350" cap="flat" cmpd="sng" algn="ctr"><a:solidFill><a:schemeClr val="phClr"/></a:solidFill><a:prstDash val="solid"/><a:miter lim="800000"/></a:ln><a:ln w="12700" cap="flat" cmpd="sng" algn="ctr"><a:solidFill><a:schemeClr val="phClr"/></a:solidFill><a:prstDash val="solid"/><a:miter lim="800000"/></a:ln><a:ln w="19050" cap="flat" cmpd="sng" algn="ctr"><a:solidFill><a:schemeClr val="phClr"/></a:solidFill><a:prstDash val="solid"/><a:miter lim="800000"/></a:ln></a:lnStyleLst><a:effectStyleLst><a:effectStyle><a:effectLst/></a:effectStyle><a:effectStyle><a:effectLst/></a:effectStyle><a:effectStyle><a:effectLst/></a:effectStyle></a:effectStyleLst><a:bgFillStyleLst><a:solidFill><a:schemeClr val="phClr"/></a:solidFill><a:solidFill><a:schemeClr val="phClr"><a:tint val="95000"/><a:satMod val="170000"/></a:schemeClr></a:solidFill><a:gradFill rotWithShape="1"><a:gsLst><a:gs pos="0"><a:schemeClr val="phClr"><a:tint val="93000"/><a:satMod val="150000"/><a:shade val="98000"/><a:lumMod val="102000"/></a:schemeClr></a:gs><a:gs pos="50000"><a:schemeClr val="phClr"><a:tint val="98000"/><a:satMod val="130000"/><a:shade val="90000"/><a:lumMod val="103000"/></a:schemeClr></a:gs><a:gs pos="100000"><a:schemeClr val="phClr"><a:shade val="63000"/><a:satMod val="120000"/></a:schemeClr></a:gs></a:gsLst><a:lin ang="5400000" scaled="0"/></a:gradFill></a:bgFillStyleLst></a:fmtScheme></a:themeElements></a:theme>`;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function nextPaint(): Promise<void> {
+  return new Promise((resolve) => {
+    let settled = false;
+    const settle = () => {
+      if (settled) return;
+      settled = true;
+      resolve();
+    };
+    requestAnimationFrame(settle);
+    setTimeout(settle, 50);
+  });
+}
+
+function downloadBlob(blob: Blob, filename: string): void {
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = filename;
+  a.rel = 'noopener';
+  document.body.appendChild(a);
+  a.click();
+  a.remove();
+  setTimeout(() => URL.revokeObjectURL(url), 0);
+}

package/src/app/lib/folders.ts

@@ -88,12 +88,22 @@ async function putAssign(slideId: string, folderId: string | null): Promise<void
   if (!res.ok) throw new Error(`PUT /__folders/assign ${res.status}`);
 }
 
+async function putReorder(ids: string[]): Promise<void> {
+  const res = await fetch('/__folders/reorder', {
+    method: 'PUT',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ ids }),
+  });
+  if (!res.ok) throw new Error(`PUT /__folders/reorder ${res.status}`);
+}
+
 export type UseFoldersResult = {
   manifest: FoldersManifest;
   loading: boolean;
   create: (name: string, icon: FolderIcon) => Promise<Folder>;
   update: (id: string, patch: { name?: string; icon?: FolderIcon }) => Promise<void>;
   remove: (id: string) => Promise<void>;
+  reorder: (ids: string[]) => Promise<void>;
   assign: (slideId: string, folderId: string | null) => Promise<void>;
   renameSlide: (slideId: string, name: string) => Promise<void>;
   duplicateSlide: (slideId: string, newId?: string) => Promise<string>;
@@ -163,6 +173,23 @@ export function useFolders(): UseFoldersResult {
     [refresh],
   );
 
+  const reorder = useCallback(
+    async (ids: string[]) => {
+      const prev = manifest;
+      const byId = new Map(prev.folders.map((f) => [f.id, f]));
+      const next = ids.map((id) => byId.get(id)).filter((f): f is Folder => Boolean(f));
+      if (next.length !== prev.folders.length) return;
+      setManifest({ ...prev, folders: next });
+      try {
+        await putReorder(ids);
+      } catch (err) {
+        setManifest(prev);
+        throw err;
+      }
+    },
+    [manifest],
+  );
+
   const assign = useCallback(
     async (slideId: string, folderId: string | null) => {
       await putAssign(slideId, folderId);
@@ -202,6 +229,7 @@ export function useFolders(): UseFoldersResult {
     create,
     update,
     remove,
+    reorder,
     assign,
     renameSlide,
     duplicateSlide,

package/src/app/lib/inspector/fiber.test.ts

@@ -0,0 +1,154 @@
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import { findSlideSource } from './fiber.ts';
+
+class FakeHTMLElement {
+  dataset: Record<string, string> = {};
+  private closestSelf: FakeHTMLElement | null = null;
+  setClosestSelfForSlideLoc() {
+    this.closestSelf = this;
+  }
+  closest(selector: string): FakeHTMLElement | null {
+    if (selector === '[data-slide-loc]') return this.closestSelf;
+    return null;
+  }
+}
+
+type DebugSource = { fileName?: string; lineNumber?: number; columnNumber?: number };
+type FakeFiber = {
+  return: FakeFiber | null;
+  stateNode?: unknown;
+  _debugSource?: DebugSource;
+};
+
+function makeEl(opts: { slideLoc?: string; fiber?: FakeFiber } = {}): FakeHTMLElement {
+  const el = new FakeHTMLElement();
+  if (opts.slideLoc) {
+    el.dataset.slideLoc = opts.slideLoc;
+    el.setClosestSelfForSlideLoc();
+  }
+  if (opts.fiber) {
+    (el as unknown as Record<string, FakeFiber>).__reactFiber$test = opts.fiber;
+  }
+  return el;
+}
+
+function makeFiber(opts: {
+  fileName?: string;
+  line?: number;
+  column?: number;
+  host?: boolean;
+  parent?: FakeFiber | null;
+}): FakeFiber {
+  const source: DebugSource | undefined =
+    opts.fileName !== undefined
+      ? { fileName: opts.fileName, lineNumber: opts.line, columnNumber: opts.column }
+      : undefined;
+  return {
+    return: opts.parent ?? null,
+    stateNode: opts.host ? new FakeHTMLElement() : undefined,
+    _debugSource: source,
+  };
+}
+
+beforeAll(() => {
+  vi.stubGlobal('HTMLElement', FakeHTMLElement);
+});
+
+afterAll(() => {
+  vi.unstubAllGlobals();
+});
+
+describe('findSlideSource primary path', () => {
+  it('reads line:column from data-slide-loc', () => {
+    const el = makeEl({ slideLoc: '42:7' });
+    const hit = findSlideSource(el as unknown as HTMLElement, 'cover');
+    expect(hit).not.toBeNull();
+    expect(hit?.line).toBe(42);
+    expect(hit?.column).toBe(7);
+    expect(hit?.anchor).toBe(el as unknown as HTMLElement);
+  });
+});
+
+describe('findSlideSource fallback', () => {
+  it('matches a POSIX fileName', () => {
+    const fiber = makeFiber({
+      fileName: '/repo/slides/cover/index.tsx',
+      line: 10,
+      column: 4,
+      host: true,
+    });
+    const el = makeEl({ fiber });
+    const hit = findSlideSource(el as unknown as HTMLElement, 'cover');
+    expect(hit).not.toBeNull();
+    expect(hit?.line).toBe(10);
+    expect(hit?.column).toBe(4);
+  });
+
+  it('matches a Windows-backslash fileName', () => {
+    const fiber = makeFiber({
+      fileName: 'C:\\repo\\slides\\cover\\index.tsx',
+      line: 11,
+      column: 2,
+      host: true,
+    });
+    const el = makeEl({ fiber });
+    const hit = findSlideSource(el as unknown as HTMLElement, 'cover');
+    expect(hit).not.toBeNull();
+    expect(hit?.line).toBe(11);
+    expect(hit?.column).toBe(2);
+  });
+
+  it('matches a fileName carrying an HMR ?t= query', () => {
+    const fiber = makeFiber({
+      fileName: '/repo/slides/cover/index.tsx?t=1700000000000',
+      line: 12,
+      column: 0,
+      host: true,
+    });
+    const el = makeEl({ fiber });
+    const hit = findSlideSource(el as unknown as HTMLElement, 'cover');
+    expect(hit).not.toBeNull();
+    expect(hit?.line).toBe(12);
+  });
+
+  it('matches a Windows fileName with an HMR query', () => {
+    const fiber = makeFiber({
+      fileName: 'C:\\repo\\slides\\cover\\index.tsx?t=1700000000000',
+      line: 13,
+      column: 1,
+      host: true,
+    });
+    const el = makeEl({ fiber });
+    const hit = findSlideSource(el as unknown as HTMLElement, 'cover');
+    expect(hit).not.toBeNull();
+    expect(hit?.line).toBe(13);
+    expect(hit?.column).toBe(1);
+  });
+
+  it('returns null when the fiber fileName points at a different slideId', () => {
+    const fiber = makeFiber({
+      fileName: '/repo/slides/other/index.tsx',
+      line: 10,
+      column: 4,
+      host: true,
+    });
+    const el = makeEl({ fiber });
+    const hit = findSlideSource(el as unknown as HTMLElement, 'cover');
+    expect(hit).toBeNull();
+  });
+
+  it('walks up the fiber chain until it finds a matching source', () => {
+    const parent = makeFiber({
+      fileName: '/repo/slides/cover/index.tsx',
+      line: 99,
+      column: 3,
+      host: true,
+    });
+    const leaf = makeFiber({ parent, host: true });
+    const el = makeEl({ fiber: leaf });
+    const hit = findSlideSource(el as unknown as HTMLElement, 'cover');
+    expect(hit).not.toBeNull();
+    expect(hit?.line).toBe(99);
+    expect(hit?.column).toBe(3);
+  });
+});

package/src/app/lib/inspector/fiber.ts

@@ -28,6 +28,12 @@ function getSource(fiber: FiberLike) {
   return fiber._debugSource ?? fiber.memoizedProps?.__source;
 }
 
+// `_debugSource.fileName` may carry Vite's HMR query (`?t=…`) and, on
+// Windows, backslash separators. Both break the naive `endsWith` match.
+function normalizeDebugFileName(fileName: string): string {
+  return fileName.split(/[?#]/)[0].replace(/\\/g, '/');
+}
+
 export function findSlideSource(
   el: HTMLElement,
   slideId: string,
@@ -58,7 +64,12 @@ export function findSlideSource(
   while (fiber) {
     const src = getSource(fiber);
     const isHost = fiber.stateNode instanceof HTMLElement;
-    if (src?.fileName?.endsWith(needle) && src.lineNumber && (!opts?.hostOnly || isHost)) {
+    if (
+      src?.fileName &&
+      normalizeDebugFileName(src.fileName).endsWith(needle) &&
+      src.lineNumber &&
+      (!opts?.hostOnly || isHost)
+    ) {
       return {
         line: src.lineNumber,
         column: src.columnNumber ?? 0,

package/src/app/lib/locale-store.ts

@@ -0,0 +1,67 @@
+import config from 'virtual:open-slide/config';
+import { useSyncExternalStore } from 'react';
+import { en } from '../../locale/en';
+import { ja } from '../../locale/ja';
+import type { Locale } from '../../locale/types';
+import { zhCN } from '../../locale/zh-cn';
+import { zhTW } from '../../locale/zh-tw';
+
+export type LocaleId = Locale['id'];
+
+const LOCALES: Record<LocaleId, Locale> = {
+  en,
+  'zh-TW': zhTW,
+  'zh-CN': zhCN,
+  ja,
+};
+
+export const LOCALE_OPTIONS: ReadonlyArray<{ id: LocaleId; label: string }> = [
+  { id: 'en', label: 'English' },
+  { id: 'zh-TW', label: '繁體中文' },
+  { id: 'zh-CN', label: '简体中文' },
+  { id: 'ja', label: '日本語' },
+];
+
+const STORAGE_KEY = 'open-slide:locale';
+const configLocale = config.locale as Locale | undefined;
+
+function isLocaleId(value: string | null): value is LocaleId {
+  return value === 'en' || value === 'zh-TW' || value === 'zh-CN' || value === 'ja';
+}
+
+function readStored(): Locale {
+  try {
+    const stored = localStorage.getItem(STORAGE_KEY);
+    if (isLocaleId(stored)) return LOCALES[stored];
+  } catch {}
+  return configLocale ?? en;
+}
+
+// A module-level store (rather than React context) so every React root the
+// runtime mounts — the app shell plus the standalone roots used for HTML/PDF
+// export — shares one locale without needing a provider above each of them.
+let current: Locale = readStored();
+const listeners = new Set<() => void>();
+
+function subscribe(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+function getSnapshot(): Locale {
+  return current;
+}
+
+export function setLocale(id: LocaleId): void {
+  current = LOCALES[id];
+  try {
+    localStorage.setItem(STORAGE_KEY, id);
+  } catch {}
+  for (const listener of listeners) listener();
+}
+
+export function useLocaleValue(): Locale {
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}

package/src/app/lib/use-click-page-navigation.ts

@@ -0,0 +1,52 @@
+import { type RefObject, useEffect } from 'react';
+
+// Clicks that land on (or inside) these never navigate — interactive slide
+// content keeps its click, and present chrome is excluded via data-osd-chrome.
+// Authors can opt any element out with a data-osd-interactive attribute.
+const NAV_PASSTHROUGH =
+  'a, button, input, textarea, select, label, summary, iframe, video, audio, embed, object, [role="button"], [role="link"], [contenteditable="true"], [data-osd-interactive], [data-osd-chrome]';
+
+type UseClickPageNavigationOptions<T extends HTMLElement> = {
+  ref: RefObject<T>;
+  enabled?: boolean;
+  /** Fraction of the width on each side that navigates; the center is inert. */
+  edgeRatio?: number;
+  canPrev: boolean;
+  canNext: boolean;
+  onPrev: () => void;
+  onNext: () => void;
+};
+
+export function useClickPageNavigation<T extends HTMLElement>({
+  ref,
+  enabled = true,
+  edgeRatio = 0.3,
+  canPrev,
+  canNext,
+  onPrev,
+  onNext,
+}: UseClickPageNavigationOptions<T>) {
+  useEffect(() => {
+    const el = ref.current;
+    if (!el || !enabled) return;
+
+    const onClick = (event: MouseEvent) => {
+      if (event.button !== 0 || event.defaultPrevented) return;
+      const target = event.target;
+      if (target instanceof HTMLElement && target.closest(NAV_PASSTHROUGH)) return;
+      if (window.getSelection()?.toString()) return;
+
+      const rect = el.getBoundingClientRect();
+      if (rect.width === 0) return;
+      const x = (event.clientX - rect.left) / rect.width;
+      if (x < edgeRatio) {
+        if (canPrev) onPrev();
+      } else if (x > 1 - edgeRatio) {
+        if (canNext) onNext();
+      }
+    };
+
+    el.addEventListener('click', onClick);
+    return () => el.removeEventListener('click', onClick);
+  }, [ref, enabled, edgeRatio, canPrev, canNext, onPrev, onNext]);
+}

package/src/app/lib/use-is-mobile.ts

@@ -0,0 +1,21 @@
+import { useEffect, useState } from 'react';
+
+// Matches Tailwind's `md` breakpoint — below it the slide viewer hides desktop
+// navigation chrome and relies on tap-to-navigate instead.
+const QUERY = '(max-width: 767.98px)';
+
+export function useIsMobile(): boolean {
+  const [mobile, setMobile] = useState(() => {
+    if (typeof window === 'undefined') return false;
+    return window.matchMedia(QUERY).matches;
+  });
+
+  useEffect(() => {
+    const mql = window.matchMedia(QUERY);
+    const onChange = (e: MediaQueryListEvent) => setMobile(e.matches);
+    mql.addEventListener('change', onChange);
+    return () => mql.removeEventListener('change', onChange);
+  }, []);
+
+  return mobile;
+}