@open-aippt/core 1.13.2

package/src/app/lib/inspector/use-notes.ts

@@ -0,0 +1,134 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+export type NoteSaveStatus =
+  | { kind: 'idle' }
+  | { kind: 'saving' }
+  | { kind: 'saved' }
+  | { kind: 'error'; message: string };
+
+const DEBOUNCE_MS = 600;
+
+type Target = { slideId: string; index: number };
+
+// HMR is suppressed for our writes, so the cached slide module's `notes`
+// stays stale across navigation. Cache last-saved text per target so
+// switching slides and back doesn't surface the old value.
+const sessionCache = new Map<string, string>();
+const cacheKey = (slideId: string, index: number) => `${slideId}:${index}`;
+
+// Remap the per-target cache after a reorder. `order[i]` is the original
+// page index that lands at new position `i`, matching the contract used by
+// the `/__slides/:id/reorder` endpoint.
+export function remapNotesSessionCacheAfterReorder(slideId: string, order: number[]): void {
+  const prev = new Map<number, string>();
+  for (let i = 0; i < order.length; i++) {
+    const cached = sessionCache.get(cacheKey(slideId, i));
+    if (cached !== undefined) prev.set(i, cached);
+    sessionCache.delete(cacheKey(slideId, i));
+  }
+  for (let newIdx = 0; newIdx < order.length; newIdx++) {
+    const oldIdx = order[newIdx];
+    const text = prev.get(oldIdx);
+    if (text !== undefined) sessionCache.set(cacheKey(slideId, newIdx), text);
+  }
+}
+
+export function useNotes(slideId: string, index: number, initial: string | undefined) {
+  const initialText = sessionCache.get(cacheKey(slideId, index)) ?? initial ?? '';
+  const [value, setValueState] = useState(initialText);
+  const [status, setStatus] = useState<NoteSaveStatus>({ kind: 'idle' });
+
+  const lastSavedRef = useRef(initialText);
+  const dirtyRef = useRef(false);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const inflightRef = useRef<AbortController | null>(null);
+  const targetRef = useRef<Target>({ slideId, index });
+  const valueRef = useRef(value);
+  valueRef.current = value;
+
+  const cancelTimer = useCallback(() => {
+    if (timerRef.current != null) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+  }, []);
+
+  const persist = useCallback(async (target: Target, text: string) => {
+    inflightRef.current?.abort();
+    const ctl = new AbortController();
+    inflightRef.current = ctl;
+    setStatus({ kind: 'saving' });
+    try {
+      const res = await fetch('/__notes', {
+        method: 'PUT',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ slideId: target.slideId, index: target.index, text }),
+        signal: ctl.signal,
+      });
+      const body = (await res.json().catch(() => ({}))) as { error?: string };
+      if (!res.ok) throw new Error(body.error ?? `PUT /__notes → ${res.status}`);
+      sessionCache.set(cacheKey(target.slideId, target.index), text);
+      if (inflightRef.current !== ctl) return;
+      lastSavedRef.current = text;
+      dirtyRef.current = false;
+      setStatus({ kind: 'saved' });
+    } catch (err) {
+      if ((err as { name?: string }).name === 'AbortError') return;
+      setStatus({ kind: 'error', message: String((err as Error).message ?? err) });
+    } finally {
+      if (inflightRef.current === ctl) inflightRef.current = null;
+    }
+  }, []);
+
+  const flush = useCallback(async () => {
+    cancelTimer();
+    if (!dirtyRef.current) return;
+    const target = targetRef.current;
+    await persist(target, valueRef.current);
+  }, [cancelTimer, persist]);
+
+  // When the (slideId, index) target changes, flush pending edits for the
+  // previous target before adopting the new initial text.
+  useEffect(() => {
+    const prev = targetRef.current;
+    const targetChanged = prev.slideId !== slideId || prev.index !== index;
+    if (targetChanged && dirtyRef.current) {
+      cancelTimer();
+      const pending = valueRef.current;
+      if (lastSavedRef.current !== pending) void persist(prev, pending);
+    }
+    targetRef.current = { slideId, index };
+    cancelTimer();
+    setValueState(initialText);
+    lastSavedRef.current = initialText;
+    dirtyRef.current = false;
+    setStatus({ kind: 'idle' });
+  }, [slideId, index, initialText, persist, cancelTimer]);
+
+  useEffect(() => {
+    return () => {
+      cancelTimer();
+      inflightRef.current?.abort();
+    };
+  }, [cancelTimer]);
+
+  const setValue = useCallback(
+    (next: string) => {
+      setValueState(next);
+      dirtyRef.current = next !== lastSavedRef.current;
+      cancelTimer();
+      if (!dirtyRef.current) {
+        setStatus({ kind: 'idle' });
+        return;
+      }
+      const target = targetRef.current;
+      timerRef.current = setTimeout(() => {
+        timerRef.current = null;
+        void persist(target, next);
+      }, DEBOUNCE_MS);
+    },
+    [persist, cancelTimer],
+  );
+
+  return { value, setValue, status, flush };
+}

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

@@ -0,0 +1,67 @@
+import config from 'virtual:open-aippt/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-aippt: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/page-context.tsx

@@ -0,0 +1,38 @@
+import { type Context, createContext, type PropsWithChildren, useContext, useMemo } from 'react';
+
+type SlidePageContextValue = {
+  index: number;
+  total: number;
+};
+
+// Stored on globalThis so dev (src) and published (dist) copies of this module
+// share one context instance — otherwise the provider writes to one context and
+// the hook reads from another, and `useSlidePageNumber` always sees null.
+const GLOBAL_KEY = '__open_aippt_page_context__';
+type GlobalWithCtx = typeof globalThis & {
+  [GLOBAL_KEY]?: Context<SlidePageContextValue | null>;
+};
+const g = globalThis as GlobalWithCtx;
+if (!g[GLOBAL_KEY]) {
+  g[GLOBAL_KEY] = createContext<SlidePageContextValue | null>(null);
+}
+const SlidePageContext = g[GLOBAL_KEY];
+
+export function SlidePageProvider({
+  index,
+  total,
+  children,
+}: PropsWithChildren<{ index: number; total: number }>) {
+  const value = useMemo(() => ({ index, total }), [index, total]);
+  return <SlidePageContext.Provider value={value}>{children}</SlidePageContext.Provider>;
+}
+
+export function useSlidePageNumber(): { current: number; total: number } {
+  const ctx = useContext(SlidePageContext);
+  if (!ctx) {
+    throw new Error(
+      'useSlidePageNumber must be called from a slide page rendered by @open-aippt/core',
+    );
+  }
+  return { current: ctx.index + 1, total: ctx.total };
+}

package/src/app/lib/print-ready.test.ts

@@ -0,0 +1,32 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { waitForFonts } from './print-ready';
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe('waitForFonts', () => {
+  it('awaits document.fonts.ready without force-loading any face', async () => {
+    const load = vi.fn();
+    const faces = [
+      { status: 'loaded', load },
+      { status: 'unloaded', load },
+      { status: 'unloaded', load },
+    ];
+    const fonts = {
+      ready: Promise.resolve(),
+      [Symbol.iterator]: () => faces[Symbol.iterator](),
+    };
+    vi.stubGlobal('document', { fonts });
+
+    await waitForFonts();
+
+    expect(load).not.toHaveBeenCalled();
+  });
+
+  it('resolves when the FontFaceSet API is unavailable', async () => {
+    vi.stubGlobal('document', {});
+
+    await expect(waitForFonts()).resolves.toBeUndefined();
+  });
+});

package/src/app/lib/print-ready.ts

@@ -0,0 +1,51 @@
+const DEFAULT_WAITFOR_TIMEOUT_MS = 10_000;
+
+// `document.fonts.ready` already waits for every in-flight face. Never call
+// `face.load()` on the rest: unloaded faces were never requested by CSS, and
+// `load()` ignores `unicode-range`, so a subsetted CJK family (hundreds of
+// faces) would be force-downloaded in full and hang or crash the tab.
+export async function waitForFonts(): Promise<void> {
+  if (!('fonts' in document)) return;
+  await document.fonts.ready;
+}
+
+export async function waitForDataWaitfor(
+  root: HTMLElement,
+  timeoutMs = DEFAULT_WAITFOR_TIMEOUT_MS,
+): Promise<void> {
+  const targets = Array.from(root.querySelectorAll<HTMLElement>('[data-waitfor]'));
+  if (targets.length === 0) return;
+  const deadline = performance.now() + timeoutMs;
+  await Promise.all(
+    targets.map(async (el) => {
+      const selector = el.getAttribute('data-waitfor');
+      if (!selector) return;
+      while (performance.now() < deadline) {
+        try {
+          if (el.querySelector(selector)) return;
+        } catch {
+          return; // invalid selector — skip rather than hang
+        }
+        await nextFrame();
+      }
+    }),
+  );
+}
+
+export function isFrameAnimationSettled(frame: Element): boolean {
+  if (typeof document.getAnimations !== 'function') return true;
+  for (const anim of document.getAnimations()) {
+    const effect = anim.effect as KeyframeEffect | null;
+    if (!effect) continue;
+    const target = effect.target;
+    if (!target || !frame.contains(target)) continue;
+    const timing = effect.getComputedTiming();
+    if (timing.iterations === Infinity) continue;
+    if (anim.playState !== 'finished') return false;
+  }
+  return true;
+}
+
+function nextFrame(): Promise<void> {
+  return new Promise((resolve) => requestAnimationFrame(() => resolve()));
+}

package/src/app/lib/sdk.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from 'vitest';
+import { CANVAS_HEIGHT, CANVAS_WIDTH } from './sdk.ts';
+
+describe('canvas constants', () => {
+  it('targets a 1920x1080 canvas', () => {
+    expect(CANVAS_WIDTH).toBe(1920);
+    expect(CANVAS_HEIGHT).toBe(1080);
+  });
+
+  it('preserves a 16:9 aspect ratio', () => {
+    expect(CANVAS_WIDTH / CANVAS_HEIGHT).toBeCloseTo(16 / 9);
+  });
+});

package/src/app/lib/sdk.ts

@@ -0,0 +1,37 @@
+import type { ComponentType } from 'react';
+import type { DesignSystem } from './design.ts';
+import type { SlideTransition } from './transition.ts';
+
+export type Page = ComponentType & { transition?: SlideTransition };
+
+export type SlideMeta = {
+  title?: string;
+  theme?: string;
+  /** ISO 8601 timestamp. Set once at scaffold time; used to sort the slide list. */
+  createdAt?: string;
+};
+
+export type SlideModule = {
+  default: Page[];
+  meta?: SlideMeta;
+  design?: DesignSystem;
+  // Index-aligned with `default`.
+  notes?: (string | undefined)[];
+  transition?: SlideTransition;
+};
+
+export type FolderIcon = { type: 'emoji'; value: string } | { type: 'color'; value: string };
+
+export type Folder = {
+  id: string;
+  name: string;
+  icon: FolderIcon;
+};
+
+export type FoldersManifest = {
+  folders: Folder[];
+  assignments: Record<string, string>;
+};
+
+export const CANVAS_WIDTH = 1920;
+export const CANVAS_HEIGHT = 1080;

package/src/app/lib/slides.ts

@@ -0,0 +1,26 @@
+import {
+  slideCreatedAt as createdAt,
+  slideIds as ids,
+  loadSlide as load,
+  slideThemes as themes,
+} from 'virtual:open-aippt/slides';
+import type { SlideModule } from './sdk';
+
+export const slideIds: string[] = ids;
+export const slideThemes: Record<string, string> = themes;
+export const slideCreatedAt: Record<string, number> = createdAt;
+
+export function slidesByTheme(themeId: string): string[] {
+  return slideIds.filter((id) => slideThemes[id] === themeId);
+}
+
+export async function loadSlide(id: string): Promise<SlideModule> {
+  return load(id);
+}
+
+export function slideChangeIncludes(data: unknown, slideId: string): boolean {
+  if (!data || typeof data !== 'object') return false;
+  const payload = data as { slideId?: unknown; slideIds?: unknown };
+  if (payload.slideId === slideId) return true;
+  return Array.isArray(payload.slideIds) && payload.slideIds.includes(slideId);
+}

package/src/app/lib/step-context.tsx

@@ -0,0 +1,261 @@
+import {
+  Children,
+  type Context,
+  cloneElement,
+  createContext,
+  isValidElement,
+  type MutableRefObject,
+  type PropsWithChildren,
+  type ReactElement,
+  useCallback,
+  useContext,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { usePrefersReducedMotion } from './use-prefers-reduced-motion';
+
+export type EntryDirection = 'forward' | 'backward' | 'jump';
+
+export type StepController = {
+  advance: () => boolean;
+  retreat: () => boolean;
+};
+
+export type StepAggregate = {
+  revealed: number;
+  stepCount: number;
+};
+
+type Registration = {
+  id: object;
+  stepCount: number;
+  initialRevealed: number;
+  controller: StepController;
+  setRevealed: (n: number) => void;
+};
+
+type StepHostContextValue = {
+  register: (reg: Registration) => () => void;
+  reportRevealed: (id: object, revealed: number) => void;
+  entryDirection: EntryDirection;
+  controlled: boolean;
+};
+
+const GLOBAL_KEY = '__open_aippt_step_host_context__';
+type GlobalWithCtx = typeof globalThis & {
+  [GLOBAL_KEY]?: Context<StepHostContextValue | null>;
+};
+const g = globalThis as GlobalWithCtx;
+if (!g[GLOBAL_KEY]) {
+  g[GLOBAL_KEY] = createContext<StepHostContextValue | null>(null);
+}
+const StepHostContext = g[GLOBAL_KEY];
+
+type StepHostProps = PropsWithChildren<{
+  isActivePage: boolean;
+  entryDirection: EntryDirection;
+  controllerRef: MutableRefObject<StepController | null>;
+  // When set, the host distributes this count across <Steps> children in
+  // mount order — first fills to its stepCount, next takes the remainder.
+  controlledRevealed?: number;
+  onAggregateChange?: (aggregate: StepAggregate) => void;
+}>;
+
+export function StepHost({
+  isActivePage,
+  entryDirection,
+  controllerRef,
+  controlledRevealed,
+  onAggregateChange,
+  children,
+}: StepHostProps) {
+  type Tracked = Registration & { revealed: number };
+  const registrationsRef = useRef<Tracked[]>([]);
+
+  const onAggregateChangeRef = useRef(onAggregateChange);
+  onAggregateChangeRef.current = onAggregateChange;
+  const controlledRevealedRef = useRef(controlledRevealed);
+  controlledRevealedRef.current = controlledRevealed;
+
+  const composite = useMemo<StepController>(
+    () => ({
+      advance: () => {
+        for (const r of registrationsRef.current) {
+          if (r.controller.advance()) return true;
+        }
+        return false;
+      },
+      retreat: () => {
+        for (let i = registrationsRef.current.length - 1; i >= 0; i--) {
+          if (registrationsRef.current[i].controller.retreat()) return true;
+        }
+        return false;
+      },
+    }),
+    [],
+  );
+
+  // useLayoutEffect cleanup-then-mount ordering keeps the registry slot
+  // continuous across page swaps — the outgoing host clears its composite
+  // before the next active host installs its own, with no gap and no overlap.
+  useLayoutEffect(() => {
+    if (!isActivePage) return;
+    controllerRef.current = composite;
+    return () => {
+      if (controllerRef.current === composite) controllerRef.current = null;
+    };
+  }, [isActivePage, composite, controllerRef]);
+
+  const notifyAggregate = useCallback(() => {
+    const cb = onAggregateChangeRef.current;
+    if (!cb) return;
+    let revealed = 0;
+    let stepCount = 0;
+    for (const r of registrationsRef.current) {
+      revealed += r.revealed;
+      stepCount += r.stepCount;
+    }
+    cb({ revealed, stepCount });
+  }, []);
+
+  const distributeControlled = useCallback(() => {
+    const target = controlledRevealedRef.current;
+    if (target == null) return;
+    let remaining = target;
+    for (const r of registrationsRef.current) {
+      const share = Math.max(0, Math.min(r.stepCount, remaining));
+      remaining -= share;
+      if (r.revealed !== share) {
+        r.revealed = share;
+        r.setRevealed(share);
+      }
+    }
+  }, []);
+
+  useLayoutEffect(() => {
+    if (controlledRevealed == null) return;
+    distributeControlled();
+    notifyAggregate();
+  }, [controlledRevealed, distributeControlled, notifyAggregate]);
+
+  const value = useMemo<StepHostContextValue>(
+    () => ({
+      register: (reg) => {
+        const tracked: Tracked = { ...reg, revealed: reg.initialRevealed };
+        registrationsRef.current.push(tracked);
+        if (controlledRevealedRef.current != null) {
+          distributeControlled();
+        }
+        notifyAggregate();
+        return () => {
+          const i = registrationsRef.current.indexOf(tracked);
+          if (i !== -1) registrationsRef.current.splice(i, 1);
+          notifyAggregate();
+        };
+      },
+      reportRevealed: (id, revealed) => {
+        const r = registrationsRef.current.find((x) => x.id === id);
+        if (!r) return;
+        r.revealed = revealed;
+        notifyAggregate();
+      },
+      entryDirection,
+      controlled: controlledRevealed != null,
+    }),
+    [entryDirection, controlledRevealed, distributeControlled, notifyAggregate],
+  );
+
+  return <StepHostContext.Provider value={value}>{children}</StepHostContext.Provider>;
+}
+
+export type StepsProps = PropsWithChildren;
+
+export function Steps({ children }: StepsProps) {
+  const host = useContext(StepHostContext);
+  const flat = Children.toArray(children);
+  const stepCount = flat.filter((c) => isValidElement(c) && c.type === Step).length;
+
+  // Controlled mode waits for the host to assign a slice in the registration
+  // layout-effect; otherwise the entry direction picks the initial reveal.
+  const initial = host?.controlled ? 0 : host?.entryDirection === 'forward' ? 0 : stepCount;
+  const revealedRef = useRef(initial);
+  const [revealed, setRevealed] = useState(initial);
+
+  const idRef = useRef<object>({});
+
+  const applyRevealed = useCallback((n: number) => {
+    revealedRef.current = n;
+    setRevealed(n);
+  }, []);
+
+  useLayoutEffect(() => {
+    if (!host) return;
+    const id = idRef.current;
+    const ctrl: StepController = {
+      advance: () => {
+        if (revealedRef.current >= stepCount) return false;
+        applyRevealed(revealedRef.current + 1);
+        host.reportRevealed(id, revealedRef.current);
+        return true;
+      },
+      retreat: () => {
+        if (revealedRef.current <= 0) return false;
+        applyRevealed(revealedRef.current - 1);
+        host.reportRevealed(id, revealedRef.current);
+        return true;
+      },
+    };
+    return host.register({
+      id,
+      stepCount,
+      initialRevealed: revealedRef.current,
+      controller: ctrl,
+      setRevealed: applyRevealed,
+    });
+  }, [host, stepCount, applyRevealed]);
+
+  const effectiveRevealed = host ? revealed : stepCount;
+
+  let stepIdx = 0;
+  return (
+    <>
+      {flat.map((child, key) => {
+        if (isValidElement(child) && child.type === Step) {
+          const idx = stepIdx++;
+          return cloneElement(child as ReactElement<{ _revealed?: boolean }>, {
+            key: child.key ?? key,
+            _revealed: idx < effectiveRevealed,
+          });
+        }
+        return child;
+      })}
+    </>
+  );
+}
+
+export type StepProps = PropsWithChildren<{
+  duration?: number;
+}>;
+
+type InternalStepProps = StepProps & { _revealed?: boolean };
+
+export function Step({ children, duration = 180, _revealed }: InternalStepProps) {
+  const reduceMotion = usePrefersReducedMotion();
+  const revealed = _revealed ?? true;
+  const ms = reduceMotion ? 0 : duration;
+
+  return (
+    <div
+      data-osd-step={revealed ? 'revealed' : 'pending'}
+      style={{
+        opacity: revealed ? 1 : 0,
+        visibility: revealed ? 'visible' : 'hidden',
+        transition: `opacity ${ms}ms cubic-bezier(0, 0, 0.2, 1)`,
+      }}
+    >
+      {children}
+    </div>
+  );
+}

package/src/app/lib/themes.ts

@@ -0,0 +1,22 @@
+import { loadThemeDemo as load, themes as raw } from 'virtual:open-aippt/themes';
+import type { DesignSystem } from './design';
+import type { Page } from './sdk';
+
+export type Theme = {
+  id: string;
+  name: string;
+  description: string;
+  body: string;
+  hasDemo: boolean;
+};
+
+export type ThemeDemoModule = {
+  default: Page[];
+  design?: DesignSystem;
+};
+
+export const themes: Theme[] = raw;
+
+export async function loadThemeDemo(id: string): Promise<ThemeDemoModule> {
+  return load(id);
+}