@open-slide/core 1.5.0 → 1.7.0

package/skills/create-theme/SKILL.md

@@ -105,24 +105,31 @@ const Title = ({ children }: { children: React.ReactNode }) => (
 
 ### Footer
 
+Pull the page number from `useSlidePageNumber()` — never hardcode `pageNum` / `total` props.
+
 ```tsx
-const Footer = ({ pageNum, total }: { pageNum: number; total: number }) => (
-  <div
-    style={{
-      position: 'absolute',
-      left: 120,
-      right: 120,
-      bottom: 60,
-      display: 'flex',
-      justifyContent: 'space-between',
-      fontSize: 24,
-      color: '#94a3b8',
-    }}
-  >
-    <span>EDITORIAL NOIR · 2026</span>
-    <span>{pageNum} / {total}</span>
-  </div>
-);
+import { useSlidePageNumber } from '@open-slide/core';
+
+const Footer = () => {
+  const { current, total } = useSlidePageNumber();
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        left: 120,
+        right: 120,
+        bottom: 60,
+        display: 'flex',
+        justifyContent: 'space-between',
+        fontSize: 24,
+        color: '#94a3b8',
+      }}
+    >
+      <span>EDITORIAL NOIR · 2026</span>
+      <span>{current} / {total}</span>
+    </div>
+  );
+};
 ```
 
 ### Eyebrow / accents (optional)
@@ -161,7 +168,7 @@ const Cover: Page = () => (
     <p style={{ fontSize: 36, color: '#94a3b8', maxWidth: 1200, marginTop: 32 }}>
       A short subtitle that explains what this slide is about.
     </p>
-    <Footer pageNum={1} total={5} />
+    <Footer />
   </div>
 );
 ```
@@ -173,7 +180,7 @@ The demo is a normal slide module — same shape as `slides/<id>/index.tsx`, jus
 
 Contract:
 
-- `import type { Page } from '@open-slide/core';`
+- `import { type Page, useSlidePageNumber } from '@open-slide/core';`
 - Inline the **same** `Title`, `Footer`, `Eyebrow` components defined in the theme markdown — verbatim, no abstractions, no imports from elsewhere. The demo and the markdown must stay in lockstep so what the user sees in the panel matches what `create-slide` will paste into a real slide.
 - Export 2–3 `Page` components and a default array. Aim for: a Cover (Eyebrow + Title + subtitle), one Content page exercising body type + accent, and a Closer or "End" card. The "Example usage" block at the bottom of the markdown is a good starting point — extend it.
 - If the theme has runtime-tweakable tokens worth surfacing in the Design panel later, also `export const design: DesignSystem = {...}`.
@@ -182,14 +189,15 @@ Contract:
 Skeleton:
 
 ```tsx
-import type { Page } from '@open-slide/core';
+import { type Page, useSlidePageNumber } from '@open-slide/core';
 
 const Title = ({ children }: { children: React.ReactNode }) => (
   // …same JSX as in themes/<id>.md
 );
-const Footer = ({ pageNum, total }: { pageNum: number; total: number }) => (
+const Footer = () => {
+  const { current, total } = useSlidePageNumber();
   // …
-);
+};
 const Eyebrow = ({ children }: { children: React.ReactNode }) => (
   // …
 );

package/skills/slide-authoring/SKILL.md

@@ -291,6 +291,191 @@ The user uploads the real file via the Assets panel, then clicks the placeholder
 
 Size the placeholder to the slot it occupies. Pass `width`/`height` when the layout has a fixed image box; omit them when the placeholder fills a flex/grid cell. The `hint` should describe the *content* the user needs ("Q3 revenue chart") not the *role* ("hero image").
 
+## Page numbers
+
+If a footer shows the current page (`03 / 12`, `Page 3`, etc.), read it from `useSlidePageNumber()` — **never hardcode** `n` / `TOTAL`. Inserting, reordering, or deleting a page would otherwise force you to retouch every footer.
+
+```tsx
+import { useSlidePageNumber } from '@open-slide/core';
+
+const Footer = () => {
+  const { current, total } = useSlidePageNumber();
+  return (
+    <span>{String(current).padStart(2, '0')} / {String(total).padStart(2, '0')}</span>
+  );
+};
+```
+
+`current` is 1-indexed (matches what readers see) and `total` is the slide's page count. The hook works in every render context (main viewer, thumbnails, overview grid, present mode, presenter window, HTML/PDF export) — the same `<Footer />` JSX is correct everywhere. Call the hook inside a component that's used **per page**; don't try to call it at module top level.
+
+## Page transitions
+
+The framework can run an enter/exit animation between every slide change. There's **no default** — pages snap unless you declare a `SlideTransition`. Snap-swap is a perfectly tasteful default; only opt in when motion adds something.
+
+`prefers-reduced-motion: reduce` is honored automatically. You don't write a fallback.
+
+### Contract
+
+Module-level for the whole deck; per-page to override. The **incoming page wins**: navigating A → B uses `pages[B].transition ?? module.transition`. Its `exit` plays on A, its `enter` plays on B. Going back B → A uses A's transition.
+
+```tsx
+import type { Page, SlideTransition } from '@open-slide/core';
+
+const Cover: Page = () => <section>…</section>;
+const Body:  Page = () => <section>…</section>;
+
+// Module-level default — every page inherits unless it overrides.
+export const transition: SlideTransition = { /* … */ };
+
+// Per-page override.
+Cover.transition = { /* … */ };
+
+export default [Cover, Body];
+```
+
+```ts
+type TransitionPhase = {
+  keyframes: Keyframe[] | PropertyIndexedKeyframes;  // WAAPI keyframes
+  duration?: number;  // ms (falls back to top-level duration)
+  easing?: string;    // CSS easing
+  delay?: number;     // ms — use to overlap exit + enter
+};
+type SlideTransition = {
+  duration: number;          // top-level fallback
+  easing?: string;           // top-level fallback
+  enter?: TransitionPhase;   // runs on incoming page
+  exit?:  TransitionPhase;   // runs on outgoing page
+};
+```
+
+The framework also exposes `--osd-dir` (`1` forward, `-1` backward) and `data-osd-dir` on the wrapper, so a single keyframe can mirror direction without a JS callback.
+
+### Design principles (hold the line)
+
+The single loudest signal of "made in PowerPoint" is six different transitions in one deck. Restraint is the rhythm.
+
+- **Pick one DNA, hold it across the deck.** Same duration band, same easing pair, same out-then-in stagger. Variation lives only in *which property* gets the small nudge — Y, X, opacity, scale, blur.
+- **Duration: 140–280 ms.** Exit 140–180 ms, enter 200–280 ms, enter delayed ~80 ms so they overlap but don't fight. Past 350 ms is video-editor territory; reserve for genuine state changes.
+- **Magnitude ceiling: 12 px or 3% scale.** A 6 px Y-rise reads as "next thought." A 1920 px translateX reads as "different document." Premium tools move barely enough to register.
+- **Opacity is always part of it.** Pure-transform transitions look stiff; pure-opacity transitions are the safest possible default.
+- **Easing: ease-in for exit, ease-out for enter.** `cubic-bezier(0.4, 0, 1, 1)` going out, `cubic-bezier(0, 0, 0.2, 1)` coming in. Never `linear` (feels like a slideshow). Reserve symmetric `ease-in-out` for state-anchored morphs only.
+
+### Tasteful family — six members, one DNA
+
+Use this set as a starting point. Pick one as the deck's house transition; optionally reserve a second for hero/cover slides and a third for genuine section breaks. The CSS-`calc` + `--osd-dir` trick lets a single definition mirror itself on backward navigation when needed.
+
+```tsx
+const EASE_OUT = 'cubic-bezier(0, 0, 0.2, 1)';
+const EASE_IN  = 'cubic-bezier(0.4, 0, 1, 1)';
+
+// RISE — house quiet. 6 px Y. Use as module default.
+export const transition: SlideTransition = {
+  duration: 200,
+  exit:  { duration: 140, easing: EASE_IN,
+           keyframes: [
+             { opacity: 1, transform: 'translateY(0)' },
+             { opacity: 0, transform: 'translateY(-4px)' },
+           ] },
+  enter: { duration: 200, delay: 80, easing: EASE_OUT,
+           keyframes: [
+             { opacity: 0, transform: 'translateY(6px)' },
+             { opacity: 1, transform: 'translateY(0)' },
+           ] },
+};
+
+// DISSOLVE — pure opacity. The quietest possible.
+const dissolve: SlideTransition = {
+  duration: 240,
+  exit:  { duration: 200, easing: EASE_IN,
+           keyframes: [{ opacity: 1 }, { opacity: 0 }] },
+  enter: { duration: 240, delay: 40, easing: EASE_OUT,
+           keyframes: [{ opacity: 0 }, { opacity: 1 }] },
+};
+
+// SETTLE — cover-grade. Rise + a hair of blur on enter only.
+Cover.transition = {
+  duration: 280,
+  exit:  { duration: 160, easing: EASE_IN,
+           keyframes: [
+             { opacity: 1, transform: 'translateY(0)' },
+             { opacity: 0, transform: 'translateY(-6px)' },
+           ] },
+  enter: { duration: 280, delay: 100, easing: EASE_OUT,
+           keyframes: [
+             { opacity: 0, transform: 'translateY(12px)', filter: 'blur(4px)' },
+             { opacity: 1, transform: 'translateY(0)',    filter: 'blur(0)'   },
+           ] },
+};
+
+// BLOOM — scale 0.97 → 1, no translate. Materializes in place.
+const bloom: SlideTransition = {
+  duration: 240,
+  exit:  { duration: 160, easing: EASE_IN,
+           keyframes: [
+             { opacity: 1, transform: 'scale(1)' },
+             { opacity: 0, transform: 'scale(1.01)' },
+           ] },
+  enter: { duration: 240, delay: 80, easing: EASE_OUT,
+           keyframes: [
+             { opacity: 0, transform: 'scale(0.97)' },
+             { opacity: 1, transform: 'scale(1)' },
+           ] },
+};
+
+// FALL — mirrored Rise. Incoming page comes down from above.
+const fall: SlideTransition = {
+  duration: 200,
+  exit:  { duration: 140, easing: EASE_IN,
+           keyframes: [
+             { opacity: 1, transform: 'translateY(0)' },
+             { opacity: 0, transform: 'translateY(4px)' },
+           ] },
+  enter: { duration: 200, delay: 80, easing: EASE_OUT,
+           keyframes: [
+             { opacity: 0, transform: 'translateY(-6px)' },
+             { opacity: 1, transform: 'translateY(0)' },
+           ] },
+};
+
+// BREATH — section break. Exit fully, hold 120 ms, then enter.
+// Reserve for genuine chapter dividers; use at most 1–2× per deck.
+const breath: SlideTransition = {
+  duration: 460,
+  exit:  { duration: 180, easing: EASE_IN,
+           keyframes: [{ opacity: 1 }, { opacity: 0 }] },
+  enter: { duration: 240, delay: 300, easing: EASE_OUT,
+           keyframes: [
+             { opacity: 0, transform: 'translateY(8px)' },
+             { opacity: 1, transform: 'translateY(0)' },
+           ] },
+};
+```
+
+All six share the same DNA — they only differ in which property carries the small nudge. The reader perceives variety; the eye still reads one consistent hand.
+
+### Direction-aware keyframes (use sparingly)
+
+Most tasteful tools don't mirror on backward navigation. When you genuinely need to — e.g. a horizontal slide that should reverse — use `--osd-dir` inside `calc()`:
+
+```tsx
+{ transform: 'translateX(calc(var(--osd-dir, 1) * 8px))' },
+{ transform: 'translateX(0)' },
+```
+
+If you find yourself reaching for this on every transition, you're probably over-designing. Forward = backward is the more refined default.
+
+### Transition anti-patterns
+
+- ❌ Six different transitions across six pages — the single loudest "made in PowerPoint" tell.
+- ❌ `translateX(100%)` slide-from-side — iOS modal / PowerPoint Push; not a slide change.
+- ❌ Aggressive scale-pop (e.g. `0.85 → 1`) + blur — lightbox / photo-viewer vocabulary; implies zooming *into* something.
+- ❌ `clip-path: inset(…)` reveals — After Effects vocabulary; theatrical.
+- ❌ Parallel blur on both layers at once — visual mush; the eye can't fixate.
+- ❌ Duration > 350 ms for a standard slide change — drags.
+- ❌ Translate > 12 px or scale > 3% — reads as rupture, not continuity.
+- ❌ `linear` easing — feels like a slideshow, not a product.
+- ❌ Declaring a transition on every deck. **If you don't have a clear reason, omit it.** Snap-swap is fine.
+
 ## Repeated elements: component, not `map`
 
 When a page has visually repeated items — cards, logo rows, gallery tiles, list rows, step indicators — **define a small component and instantiate it once per item**. Do **not** render the group with `array.map` over a data array.
@@ -356,6 +541,7 @@ This applies whenever the *visual element* repeats, not whenever the *data* does
 - [ ] Visually repeated elements (cards, tiles, logo rows) are rendered as explicit `<Component />` instances, not via `array.map` over a data list.
 - [ ] All imported assets exist on disk — slide-local under `slides/<id>/assets/`, or global under `assets/` (imported via `@assets/...`).
 - [ ] Every `<ImagePlaceholder>` corresponds to a real image the user must supply — not decorative filler. If it could be replaced by typography or layout, it should be.
+- [ ] If a `SlideTransition` is declared, every page sits in one family — same duration band (140–280 ms), same easing pair, same out-then-in stagger, magnitude under 12 px / 3%. No six-different-vocabularies decks. When in doubt, omit transitions entirely.
 - [ ] Nothing outside `slides/<id>/` was edited.
 
 ## Anti-patterns

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

@@ -414,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

package/src/app/components/inspector/asset-picker-dialog.tsx

@@ -0,0 +1,196 @@
+import { ArrowDownToLine, Loader2, Upload } from 'lucide-react';
+import type React from 'react';
+import { useCallback, useId, useRef, useState } from 'react';
+import { toast } from 'sonner';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog';
+import { Tabs, TabsList, TabsTrigger } from '@/components/ui/tabs';
+import { type AssetEntry, uploadWithAutoRename, useAssets } from '@/lib/assets';
+import { format, useLocale } from '@/lib/use-locale';
+import { cn } from '@/lib/utils';
+
+export type PickerScope = 'slide' | 'global';
+const GLOBAL_PICKER_SLIDE_ID = '@global';
+
+export function AssetPickerDialog({
+  slideId,
+  onClose,
+  onPick,
+}: {
+  slideId: string;
+  onClose: () => void;
+  onPick: (asset: AssetEntry, scope: PickerScope) => void;
+}) {
+  const [scope, setScope] = useState<PickerScope>('slide');
+  const effectiveSlideId = scope === 'global' ? GLOBAL_PICKER_SLIDE_ID : slideId;
+  const { assets, loading, refresh } = useAssets(effectiveSlideId);
+  const images = assets.filter((a) => a.mime.startsWith('image/'));
+  const t = useLocale();
+  const path = scope === 'global' ? 'assets/' : `slides/${slideId}/assets/`;
+  const [descPrefix, descSuffix] = t.inspector.replaceImageDescription.split('{path}');
+  const [uploading, setUploading] = useState(false);
+  const [dragActive, setDragActive] = useState(false);
+  const dragDepth = useRef(0);
+  const inputId = useId();
+
+  const handleFile = useCallback(
+    async (file: File) => {
+      if (!file.type.startsWith('image/')) return;
+      setUploading(true);
+      try {
+        const { ok, status, entry } = await uploadWithAutoRename(effectiveSlideId, file);
+        if (!ok || !entry) {
+          toast.error(format(t.asset.toastUploadFailed, { status }));
+          return;
+        }
+        await refresh().catch(() => {});
+        onPick(entry, scope);
+      } finally {
+        setUploading(false);
+      }
+    },
+    [effectiveSlideId, scope, refresh, onPick, t],
+  );
+
+  return (
+    <Dialog open onOpenChange={(o) => !o && onClose()}>
+      <DialogContent className="sm:max-w-xl">
+        <DialogHeader>
+          <DialogTitle>{t.inspector.replaceImageDialogTitle}</DialogTitle>
+          <DialogDescription>
+            {descPrefix}
+            <span className="font-mono">{path}</span>
+            {descSuffix}
+          </DialogDescription>
+        </DialogHeader>
+        <Tabs value={scope} onValueChange={(next) => setScope(next as PickerScope)}>
+          <TabsList>
+            <TabsTrigger value="slide">{t.asset.scopeSlide}</TabsTrigger>
+            <TabsTrigger value="global">{t.asset.scopeGlobal}</TabsTrigger>
+          </TabsList>
+        </Tabs>
+        <label
+          htmlFor={inputId}
+          className={cn(
+            'absolute right-12 top-3.5 inline-flex h-7 cursor-pointer items-center gap-1.5 rounded-[5px] border border-border bg-card px-2 text-[12px] font-medium transition-colors',
+            'hover:bg-muted/60 hover:border-foreground/20 active:translate-y-px',
+            uploading && 'pointer-events-none opacity-60',
+          )}
+        >
+          {uploading ? (
+            <Loader2 className="size-3.5 animate-spin" />
+          ) : (
+            <Upload className="size-3.5" />
+          )}
+          <span>{t.asset.upload}</span>
+        </label>
+        <input
+          id={inputId}
+          type="file"
+          accept="image/*"
+          className="sr-only"
+          disabled={uploading}
+          onChange={(e) => {
+            const file = e.target.files?.[0];
+            e.target.value = '';
+            if (file) handleFile(file).catch(() => {});
+          }}
+        />
+        <section
+          aria-label={t.inspector.replaceImageDialogTitle}
+          className="relative max-h-[60vh] overflow-y-auto"
+          onDragEnter={(e) => {
+            if (uploading || !hasFiles(e)) return;
+            e.preventDefault();
+            dragDepth.current += 1;
+            setDragActive(true);
+          }}
+          onDragOver={(e) => {
+            if (uploading || !hasFiles(e)) return;
+            e.preventDefault();
+            e.dataTransfer.dropEffect = 'copy';
+          }}
+          onDragLeave={() => {
+            dragDepth.current = Math.max(0, dragDepth.current - 1);
+            if (dragDepth.current === 0) setDragActive(false);
+          }}
+          onDrop={(e) => {
+            if (uploading || !hasFiles(e)) return;
+            e.preventDefault();
+            dragDepth.current = 0;
+            setDragActive(false);
+            const file = e.dataTransfer.files?.[0];
+            if (file) handleFile(file).catch(() => {});
+          }}
+        >
+          {loading ? (
+            <p className="px-1 py-6 text-center text-xs text-muted-foreground">
+              {t.inspector.pickerLoading}
+            </p>
+          ) : images.length === 0 ? (
+            <p className="px-1 py-6 text-center text-xs text-muted-foreground">
+              {t.inspector.pickerEmpty}
+            </p>
+          ) : (
+            <div className="grid grid-cols-[repeat(auto-fill,minmax(120px,1fr))] gap-3">
+              {images.map((asset) => (
+                <button
+                  key={asset.name}
+                  type="button"
+                  onClick={() => onPick(asset, scope)}
+                  className={cn(
+                    'group flex flex-col overflow-hidden rounded-lg border bg-card text-left shadow-sm transition-all',
+                    'hover:-translate-y-0.5 hover:shadow-md focus-visible:ring-2 focus-visible:ring-ring/50 focus-visible:outline-none',
+                  )}
+                >
+                  <div className="flex aspect-square w-full items-center justify-center overflow-hidden bg-[repeating-conic-gradient(theme(colors.muted)_0_25%,transparent_0_50%)] bg-[length:12px_12px]">
+                    <img
+                      src={asset.url}
+                      alt=""
+                      className="size-full object-contain"
+                      draggable={false}
+                    />
+                  </div>
+                  <div className="border-t px-2 py-1.5">
+                    <div className="truncate text-[11px] font-medium" title={asset.name}>
+                      {asset.name}
+                    </div>
+                  </div>
+                </button>
+              ))}
+            </div>
+          )}
+          {dragActive && (
+            <div
+              className="pointer-events-none absolute inset-0 z-10 animate-in fade-in-0 duration-200"
+              aria-hidden
+            >
+              <div className="absolute inset-0 bg-brand/5" />
+              <div className="absolute inset-1 rounded-[8px] border border-dashed border-brand/40" />
+              <div className="absolute inset-x-0 bottom-4 flex justify-center">
+                <div className="flex items-center gap-2 rounded-[6px] border border-border bg-card px-3 py-1.5 text-[12px] font-medium shadow-floating">
+                  <ArrowDownToLine className="size-3.5 text-brand" />
+                  <span>{t.asset.dropToUpload}</span>
+                </div>
+              </div>
+            </div>
+          )}
+        </section>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+function hasFiles(e: React.DragEvent): boolean {
+  const types = e.dataTransfer?.types;
+  if (!types) return false;
+  for (let i = 0; i < types.length; i++) {
+    if (types[i] === 'Files') return true;
+  }
+  return false;
+}