@open-slide/core 1.4.0 → 1.6.0

package/src/app/components/asset-view.tsx

@@ -33,8 +33,11 @@ import {
 import { Tabs, TabsList, TabsTrigger } from '@/components/ui/tabs';
 import {
   type AssetEntry,
+  type AssetUsage,
   fetchSvgAsFile,
+  listAssetUsages,
   renamedCopy,
+  revertAssetUsage,
   type SvglItem,
   searchSvgl,
   useAssets,
@@ -62,6 +65,7 @@ export function AssetView({ slideId }: Props) {
   const [conflict, setConflict] = useState<ConflictState | null>(null);
   const [preview, setPreview] = useState<AssetEntry | null>(null);
   const [confirmDelete, setConfirmDelete] = useState<AssetEntry | null>(null);
+  const [confirmDeleteUsages, setConfirmDeleteUsages] = useState<AssetUsage[] | null>(null);
   const [renaming, setRenaming] = useState<string | null>(null);
   const [logoSearchOpen, setLogoSearchOpen] = useState(false);
   const dragDepth = useRef(0);
@@ -245,7 +249,13 @@ export function AssetView({ slideId }: Props) {
                   asset={asset}
                   onPreview={() => setPreview(asset)}
                   onRename={() => setRenaming(asset.name)}
-                  onDelete={() => setConfirmDelete(asset)}
+                  onDelete={() => {
+                    setConfirmDelete(asset);
+                    setConfirmDeleteUsages(null);
+                    listAssetUsages(effectiveSlideId, asset.name)
+                      .then((u) => setConfirmDeleteUsages(u))
+                      .catch(() => setConfirmDeleteUsages([]));
+                  }}
                 />
               ),
             )}
@@ -282,13 +292,41 @@ export function AssetView({ slideId }: Props) {
       {confirmDelete && (
         <DeleteDialog
           asset={confirmDelete}
-          onCancel={() => setConfirmDelete(null)}
+          usages={confirmDeleteUsages}
+          onCancel={() => {
+            setConfirmDelete(null);
+            setConfirmDeleteUsages(null);
+          }}
           onConfirm={async () => {
             const target = confirmDelete;
+            const usages = confirmDeleteUsages ?? [];
             setConfirmDelete(null);
+            setConfirmDeleteUsages(null);
+            const assetPath =
+              scope === 'global' ? `@assets/${target.name}` : `./assets/${target.name}`;
+            for (const u of usages) {
+              const rev = await revertAssetUsage(u.slideId, assetPath);
+              if (!rev.ok) {
+                toast.error(format(t.asset.toastRevertFailed, { slideId: u.slideId }));
+                return;
+              }
+            }
             const res = await remove(target.name);
-            if (!res.ok) toast.error(format(t.asset.toastDeleteFailed, { status: res.status }));
-            else toast.success(format(t.asset.toastDeleted, { name: target.name }));
+            if (!res.ok) {
+              toast.error(format(t.asset.toastDeleteFailed, { status: res.status }));
+              return;
+            }
+            const totalUsages = usages.reduce((acc, u) => acc + u.count, 0);
+            if (totalUsages > 0) {
+              toast.success(
+                format(t.asset.toastDeletedWithRevert, {
+                  name: target.name,
+                  count: totalUsages,
+                }),
+              );
+            } else {
+              toast.success(format(t.asset.toastDeleted, { name: target.name }));
+            }
           }}
         />
       )}
@@ -376,7 +414,14 @@ function AssetCard({
           <div className="truncate text-[12.5px] font-medium" title={asset.name}>
             {asset.name}
           </div>
-          <div className="folio truncate">{formatSize(asset.size)}</div>
+          <div className="folio flex items-center gap-1.5">
+            <span className="truncate">{formatSize(asset.size)}</span>
+            {asset.unused ? (
+              <span className="shrink-0 rounded-sm bg-muted px-1 py-px text-[10px] font-medium text-muted-foreground leading-none">
+                {t.asset.usageUnused}
+              </span>
+            ) : null}
+          </div>
         </div>
         <DropdownMenu>
           <DropdownMenuTrigger
@@ -517,14 +562,19 @@ function ConflictDialog({
 
 function DeleteDialog({
   asset,
+  usages,
   onCancel,
   onConfirm,
 }: {
   asset: AssetEntry;
+  usages: AssetUsage[] | null;
   onCancel: () => void;
   onConfirm: () => void;
 }) {
   const t = useLocale();
+  const inUse = (usages?.length ?? 0) > 0;
+  const totalUses = usages?.reduce((acc, u) => acc + u.count, 0) ?? 0;
+  const slideCount = usages?.length ?? 0;
   const [descPrefix, descSuffix] = t.asset.deleteAssetDescription.split('{name}');
   return (
     <Dialog open onOpenChange={(open) => !open && onCancel()}>
@@ -532,17 +582,40 @@ function DeleteDialog({
         <DialogHeader>
           <DialogTitle>{t.asset.deleteAssetTitle}</DialogTitle>
           <DialogDescription>
-            {descPrefix}
-            <span className="font-mono">{asset.name}</span>
-            {descSuffix}
+            {inUse ? (
+              <>
+                {format(t.asset.deleteAssetInUseDescription, {
+                  name: asset.name,
+                  count: totalUses,
+                  slides: slideCount,
+                })}{' '}
+                {t.asset.deleteAssetInUseHint}
+              </>
+            ) : (
+              <>
+                {descPrefix}
+                <span className="font-mono">{asset.name}</span>
+                {descSuffix}
+              </>
+            )}
           </DialogDescription>
         </DialogHeader>
+        {inUse && usages && (
+          <ul className="max-h-40 overflow-y-auto rounded-[5px] border border-hairline bg-muted/40 px-3 py-2 font-mono text-[11.5px] leading-relaxed">
+            {usages.map((u) => (
+              <li key={u.slideId} className="flex items-center justify-between gap-3">
+                <span className="truncate">{u.slideId}</span>
+                <span className="text-muted-foreground">×{u.count}</span>
+              </li>
+            ))}
+          </ul>
+        )}
         <DialogFooter>
           <Button variant="outline" onClick={onCancel}>
             {t.common.cancel}
           </Button>
-          <Button variant="destructive" onClick={onConfirm}>
-            {t.common.delete}
+          <Button variant="destructive" onClick={onConfirm} disabled={usages === null}>
+            {inUse ? t.asset.deleteAndRevert : t.common.delete}
           </Button>
         </DialogFooter>
       </DialogContent>

package/src/app/components/inspector/inspector-panel.tsx

@@ -1116,8 +1116,23 @@ function CommentsSection({
 }) {
   const [draft, setDraft] = useState('');
   const [submitting, setSubmitting] = useState(false);
+  const wrapRef = useRef<HTMLDivElement>(null);
   const t = useLocale();
 
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key !== '/') return;
+      if (!(e.metaKey || e.ctrlKey)) return;
+      if (e.altKey || e.shiftKey) return;
+      const ta = wrapRef.current?.querySelector('textarea');
+      if (!ta) return;
+      e.preventDefault();
+      ta.focus({ preventScroll: true });
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, []);
+
   const submit = async () => {
     const trimmed = draft.trim();
     if (!trimmed) return;
@@ -1133,7 +1148,7 @@ function CommentsSection({
   return (
     <Section title={t.inspector.leaveComment}>
       <div className="flex flex-col gap-2">
-        <div className="comment-cue rounded-[6px]">
+        <div ref={wrapRef} className="comment-cue rounded-[6px]">
           <Textarea
             value={draft}
             onChange={(e) => setDraft(e.target.value)}

package/src/app/components/panel/panel-shell.tsx

@@ -68,10 +68,12 @@ export function PanelShell({
           {header}
         </header>
         {banner}
-        <ScrollArea className="flex flex-1 flex-col">
-          <div className="flex min-h-full flex-col">{children}</div>
+        <ScrollArea className="min-h-0 flex-1">
+          <div className="flex min-h-full flex-col">
+            {children}
+            {footer && <div className="mt-auto border-t border-hairline">{footer}</div>}
+          </div>
         </ScrollArea>
-        {footer && <div className="shrink-0 border-t border-hairline">{footer}</div>}
       </div>
     </aside>
   );

package/src/app/components/player.tsx

@@ -2,6 +2,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { useWheelPageNavigation } from '@/lib/use-wheel-page-navigation';
 import { cn } from '@/lib/utils';
 import type { DesignSystem } from '../lib/design';
+import { SlidePageProvider } from '../lib/page-context';
 import type { Page } from '../lib/sdk';
 import { PresentBlackoutOverlay } from './present/blackout-overlay';
 import { PresentControlBar } from './present/control-bar';
@@ -295,7 +296,11 @@ export function Player({
       )}
     >
       <SlideCanvas flat design={design}>
-        {PageComp ? <PageComp /> : null}
+        {PageComp ? (
+          <SlidePageProvider index={index} total={pages.length}>
+            <PageComp />
+          </SlidePageProvider>
+        ) : null}
       </SlideCanvas>
 
       <button

package/src/app/components/present/laser-pointer.tsx

@@ -24,13 +24,12 @@ export function PresentLaserPointer({ enabled }: { enabled: boolean }) {
   return (
     <div
       aria-hidden
-      className="pointer-events-none fixed z-[60]"
+      className="pointer-events-none fixed top-0 left-0 z-[60]"
       style={{
-        left: pos.x,
-        top: pos.y,
         width: 18,
         height: 18,
-        transform: 'translate(-50%, -50%)',
+        transform: `translate3d(${pos.x - 9}px, ${pos.y - 9}px, 0)`,
+        willChange: 'transform',
         borderRadius: '50%',
         background: 'radial-gradient(circle, oklch(0.66 0.24 28 / 0.95) 30%, transparent 70%)',
         boxShadow: '0 0 18px 4px oklch(0.66 0.24 28 / 0.55)',

package/src/app/components/present/overview-grid.tsx

@@ -2,6 +2,7 @@ import { useEffect, useRef, useState } from 'react';
 import { format, useLocale } from '@/lib/use-locale';
 import { cn } from '@/lib/utils';
 import type { DesignSystem } from '../../lib/design';
+import { SlidePageProvider } from '../../lib/page-context';
 import type { Page } from '../../lib/sdk';
 import { CANVAS_HEIGHT, CANVAS_WIDTH } from '../../lib/sdk';
 import { SlideCanvas } from '../slide-canvas';
@@ -136,7 +137,9 @@ export function PresentOverviewGrid({ pages, design, open, current, onClose, onS
                     freezeMotion
                     design={design}
                   >
-                    <PageComp />
+                    <SlidePageProvider index={i} total={pages.length}>
+                      <PageComp />
+                    </SlidePageProvider>
                   </SlideCanvas>
                   {isCurrent && (
                     <span

package/src/app/components/present/progress-bar.tsx

@@ -7,19 +7,19 @@ type Props = {
 };
 
 export function PresentProgressBar({ index, total, visible }: Props) {
-  const pct = total > 0 ? ((index + 1) / total) * 100 : 0;
+  const pct = total > 0 ? (index + 1) / total : 0;
   return (
     <div
       aria-hidden
       className={cn(
-        'pointer-events-none absolute inset-x-0 top-0 z-30 h-[2px] bg-white/8',
+        'pointer-events-none absolute inset-x-0 top-0 z-30 h-[2px] overflow-hidden bg-white/8',
         'motion-safe:transition-opacity motion-safe:duration-200',
         visible ? 'opacity-100' : 'opacity-0',
       )}
     >
       <div
-        className="h-full bg-[var(--brand,#ef4444)] transition-[width] duration-200 ease-out"
-        style={{ width: `${pct}%` }}
+        className="h-full w-full origin-left bg-[var(--brand,#ef4444)] transition-transform duration-200 ease-out"
+        style={{ transform: `scaleX(${pct})` }}
       />
     </div>
   );

package/src/app/components/themes/theme-detail.tsx

@@ -4,6 +4,7 @@ import { Link } from 'react-router-dom';
 import { Button } from '@/components/ui/button';
 import { format, useLocale } from '@/lib/use-locale';
 import { cn } from '@/lib/utils';
+import { SlidePageProvider } from '../../lib/page-context';
 import type { SlideModule } from '../../lib/sdk';
 import { loadSlide, slidesByTheme } from '../../lib/slides';
 import { loadThemeDemo, type ThemeDemoModule, themes } from '../../lib/themes';
@@ -106,7 +107,9 @@ export function ThemeDetail({ themeId, onBack }: { themeId: string; onBack: () =
                 </div>
               ) : Current ? (
                 <SlideCanvas flat freezeMotion design={demo.design}>
-                  <Current />
+                  <SlidePageProvider index={pageIndex} total={totalPages}>
+                    <Current />
+                  </SlidePageProvider>
                 </SlideCanvas>
               ) : null}
             </div>
@@ -227,7 +230,9 @@ function ThemeSlideCard({ id }: { id: string }) {
         {FirstPage ? (
           <div className="h-full w-full motion-safe:transition-transform motion-safe:duration-300 motion-safe:group-hover:scale-[1.03]">
             <SlideCanvas flat freezeMotion design={slide?.design}>
-              <FirstPage />
+              <SlidePageProvider index={0} total={slide?.default.length ?? 1}>
+                <FirstPage />
+              </SlidePageProvider>
             </SlideCanvas>
           </div>
         ) : (

package/src/app/components/themes/themes-gallery.tsx

@@ -1,5 +1,6 @@
 import { useEffect, useState } from 'react';
 import { format, useLocale } from '@/lib/use-locale';
+import { SlidePageProvider } from '../../lib/page-context';
 import { loadThemeDemo, type Theme, type ThemeDemoModule, themes } from '../../lib/themes';
 import { SlideCanvas } from '../slide-canvas';
 
@@ -78,7 +79,9 @@ function ThemePreview({ theme }: { theme: Theme }) {
   return (
     <div className="h-full w-full motion-safe:transition-transform motion-safe:duration-300 motion-safe:group-hover:scale-[1.03]">
       <SlideCanvas flat freezeMotion design={demo.design}>
-        <FirstPage />
+        <SlidePageProvider index={0} total={demo.default.length}>
+          <FirstPage />
+        </SlidePageProvider>
       </SlideCanvas>
     </div>
   );

package/src/app/components/thumbnail-rail.tsx

@@ -28,6 +28,7 @@ import { ScrollArea } from '@/components/ui/scroll-area';
 import { format, useLocale } from '@/lib/use-locale';
 import { cn } from '@/lib/utils';
 import type { DesignSystem } from '../lib/design';
+import { SlidePageProvider } from '../lib/page-context';
 import type { Page } from '../lib/sdk';
 import { CANVAS_HEIGHT, CANVAS_WIDTH } from '../lib/sdk';
 import { SlideCanvas } from './slide-canvas';
@@ -118,7 +119,9 @@ export function ThumbnailRail({
                     style={{ width, height: HORIZONTAL_THUMB_HEIGHT }}
                   >
                     <SlideCanvas scale={scale} center={false} flat freezeMotion design={design}>
-                      <PageComp />
+                      <SlidePageProvider index={i} total={pages.length}>
+                        <PageComp />
+                      </SlidePageProvider>
                     </SlideCanvas>
                   </div>
                 </button>
@@ -155,6 +158,7 @@ export function ThumbnailRail({
     const inner = (
       <ThumbContents
         index={i}
+        total={pages.length}
         active={active}
         page={PageComp}
         design={design}
@@ -236,6 +240,7 @@ function thumbButtonClass(active: boolean): string {
 
 function ThumbContents({
   index,
+  total,
   active,
   page: PageComp,
   design,
@@ -244,6 +249,7 @@ function ThumbContents({
   height,
 }: {
   index: number;
+  total: number;
   active: boolean;
   page: Page;
   design?: DesignSystem;
@@ -271,7 +277,9 @@ function ThumbContents({
         style={{ width: thumbWidth, height }}
       >
         <SlideCanvas scale={scale} center={false} flat freezeMotion design={design}>
-          <PageComp />
+          <SlidePageProvider index={index} total={total}>
+            <PageComp />
+          </SlidePageProvider>
         </SlideCanvas>
         {active && (
           <span

package/src/app/lib/assets.ts

@@ -6,6 +6,7 @@ export type AssetEntry = {
   mtime: number;
   mime: string;
   url: string;
+  unused: boolean;
 };
 
 export type UploadOptions = { overwrite?: boolean };
@@ -45,6 +46,27 @@ async function deleteAsset(slideId: string, name: string): Promise<Response> {
   return fetch(`/__assets/${slideId}/${encodeURIComponent(name)}`, { method: 'DELETE' });
 }
 
+export type AssetUsage = { slideId: string; count: number };
+
+export async function listAssetUsages(slideId: string, name: string): Promise<AssetUsage[]> {
+  const res = await fetch(`/__assets/${slideId}/${encodeURIComponent(name)}/usages`);
+  if (!res.ok) return [];
+  const data = (await res.json().catch(() => null)) as { usages?: AssetUsage[] } | null;
+  return data?.usages ?? [];
+}
+
+export async function revertAssetUsage(
+  slideId: string,
+  assetPath: string,
+): Promise<{ ok: boolean; status: number }> {
+  const res = await fetch('/__edit/revert-asset', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ slideId, assetPath }),
+  });
+  return { ok: res.ok, status: res.status };
+}
+
 export async function uploadWithAutoRename(
   slideId: string,
   file: File,
@@ -69,6 +91,7 @@ export async function uploadWithAutoRename(
     mtime: body?.mtime ?? Date.now(),
     mime: body?.mime ?? uploaded.type ?? 'application/octet-stream',
     url: body?.url ?? `/__assets/${slideId}/${encodeURIComponent(uploaded.name)}`,
+    unused: body?.unused ?? false,
   };
   return { ok: true, status: res.status, entry };
 }

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

@@ -1,6 +1,7 @@
 import { createElement } from 'react';
 import { createRoot } from 'react-dom/client';
 import { designToCssVars } from './design';
+import { SlidePageProvider } from './page-context';
 import type { SlideModule } from './sdk';
 
 type AssetEntry = { name: string; bytes: Uint8Array };
@@ -82,13 +83,17 @@ async function renderPagesToHtml(pages: NonNullable<SlideModule['default']>): Pr
 
   const result: string[] = [];
   try {
-    for (const Page of pages) {
+    for (let i = 0; i < pages.length; i++) {
+      const Page = pages[i];
+      if (!Page) continue;
       const host = document.createElement('div');
       host.style.width = '1920px';
       host.style.height = '1080px';
       container.appendChild(host);
       const root = createRoot(host);
-      root.render(createElement(Page));
+      root.render(
+        createElement(SlidePageProvider, { index: i, total: pages.length }, createElement(Page)),
+      );
       await nextPaint();
       await nextPaint();
       result.push(host.innerHTML);

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

@@ -1,6 +1,7 @@
 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';
 
@@ -62,6 +63,20 @@ const PRINT_STYLES = `
     transform: scale(0.5);
     transform-origin: top left;
   }
+  /* Chromium serializes box-shadow and CSS gradients as PDF transparency
+     groups / soft masks. macOS Preview re-composites those on every page
+     turn, causing 0.5–2s per-page lag. Strip them in the print container
+     only — gradients on pseudo-elements via CSS (DOM walk can't reach them),
+     inline-style gradients via neutralizeGradientBackgrounds() below. */
+  #${PRINT_ROOT_ID} *,
+  #${PRINT_ROOT_ID} *::before,
+  #${PRINT_ROOT_ID} *::after {
+    box-shadow: none !important;
+  }
+  #${PRINT_ROOT_ID} *::before,
+  #${PRINT_ROOT_ID} *::after {
+    background-image: none !important;
+  }
 }
 `;
 
@@ -109,7 +124,9 @@ export async function exportSlideAsPdf(
 
   const reactRoots: Root[] = [];
   const frames: HTMLElement[] = [];
-  for (const Page of pages) {
+  for (let i = 0; i < pages.length; i++) {
+    const Page = pages[i];
+    if (!Page) continue;
     const host = document.createElement('div');
     host.className = 'os-print-frame';
     host.setAttribute('data-osd-canvas', '');
@@ -126,7 +143,9 @@ export async function exportSlideAsPdf(
     root.appendChild(host);
     frames.push(host);
     const r = createRoot(inner);
-    r.render(createElement(Page));
+    r.render(
+      createElement(SlidePageProvider, { index: i, total: pages.length }, createElement(Page)),
+    );
     reactRoots.push(r);
   }
   // Yield once so React commits all pages and CSS animations actually start
@@ -155,6 +174,7 @@ export async function exportSlideAsPdf(
     }
 
     await waitForDataWaitfor(root);
+    neutralizeGradientBackgrounds(root);
     await sleep(100); // flush layout
 
     onProgress?.({ phase: 'printing', current: total, total, percent: 99 });
@@ -170,6 +190,18 @@ export async function exportSlideAsPdf(
   }
 }
 
+// Strip inline-style gradients from background-image so Chromium does not
+// emit them as PDF soft masks. url(...) backgrounds are preserved.
+function neutralizeGradientBackgrounds(root: HTMLElement): void {
+  const elements = root.querySelectorAll<HTMLElement>('*');
+  for (const el of elements) {
+    const bg = getComputedStyle(el).backgroundImage;
+    if (bg?.includes('gradient(')) {
+      el.style.backgroundImage = 'none';
+    }
+  }
+}
+
 function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }

package/src/app/lib/folders.ts

@@ -33,6 +33,19 @@ async function patchSlideName(slideId: string, name: string): Promise<void> {
   if (!res.ok) throw new Error(`PATCH /__slides/${slideId} ${res.status}`);
 }
 
+async function duplicateSlideReq(slideId: string, newId?: string): Promise<string> {
+  const init: RequestInit = { method: 'POST' };
+  if (newId !== undefined) {
+    init.headers = { 'content-type': 'application/json' };
+    init.body = JSON.stringify({ newId });
+  }
+  const res = await fetch(`/__slides/${slideId}/duplicate`, init);
+  if (!res.ok) throw new Error(`POST /__slides/${slideId}/duplicate ${res.status}`);
+  const body = (await res.json()) as { slideId?: unknown };
+  if (typeof body.slideId !== 'string') throw new Error('duplicate response missing slideId');
+  return body.slideId;
+}
+
 async function deleteSlideReq(slideId: string): Promise<void> {
   const res = await fetch(`/__slides/${slideId}`, { method: 'DELETE' });
   if (!res.ok) throw new Error(`DELETE /__slides/${slideId} ${res.status}`);
@@ -83,6 +96,7 @@ export type UseFoldersResult = {
   remove: (id: 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>;
   deleteSlide: (slideId: string) => Promise<void>;
   refresh: () => Promise<void>;
 };
@@ -165,6 +179,15 @@ export function useFolders(): UseFoldersResult {
     [refresh],
   );
 
+  const duplicateSlide = useCallback(
+    async (slideId: string, newId?: string) => {
+      const duplicatedId = await duplicateSlideReq(slideId, newId);
+      await refresh();
+      return duplicatedId;
+    },
+    [refresh],
+  );
+
   const deleteSlide = useCallback(
     async (slideId: string) => {
       await deleteSlideReq(slideId);
@@ -173,5 +196,16 @@ export function useFolders(): UseFoldersResult {
     [refresh],
   );
 
-  return { manifest, loading, create, update, remove, assign, renameSlide, deleteSlide, refresh };
+  return {
+    manifest,
+    loading,
+    create,
+    update,
+    remove,
+    assign,
+    renameSlide,
+    duplicateSlide,
+    deleteSlide,
+    refresh,
+  };
 }

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_slide_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-slide/core',
+    );
+  }
+  return { current: ctx.index + 1, total: ctx.total };
+}

package/src/app/lib/sdk.ts

@@ -6,6 +6,8 @@ export type Page = ComponentType;
 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 = {

package/src/app/lib/slides.ts

@@ -1,4 +1,5 @@
 import {
+  slideCreatedAt as createdAt,
   slideIds as ids,
   loadSlide as load,
   slideThemes as themes,
@@ -7,6 +8,7 @@ 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);