promptslide 0.3.16 → 0.3.18

package/src/core/slide-renderer.tsx

@@ -58,6 +58,7 @@ export function SlideRenderer({
     <AnimatePresence initial={false}>
       <motion.div
         key={currentSlide}
+        data-slide-render-index={currentSlide}
         variants={slideVariants}
         initial="enter"
         animate="center"
@@ -75,14 +76,8 @@ export function SlideRenderer({
           totalSteps={totalSteps}
           showAllAnimations={showAllAnimations}
         >
-          <SlideErrorBoundary
-            slideIndex={currentSlide}
-            slideTitle={slides[currentSlide]?.title}
-          >
-            <CurrentSlideComponent
-              slideNumber={currentSlide + 1}
-              totalSlides={slides.length}
-            />
+          <SlideErrorBoundary slideIndex={currentSlide} slideTitle={slides[currentSlide]?.title}>
+            <CurrentSlideComponent slideNumber={currentSlide + 1} totalSlides={slides.length} />
           </SlideErrorBoundary>
         </AnimationProvider>
       </motion.div>

package/src/core/transitions.ts

@@ -42,9 +42,11 @@ export interface SlideTransitionConfig {
 // =============================================================================
 
 const fadeVariants: Variants = {
-  enter: { opacity: 0 },
-  center: { opacity: 1 },
-  exit: { opacity: 0 }
+  // Render the next slide fully beneath the current one, then fade the
+  // outgoing slide away. This keeps the frame opaque throughout the change.
+  enter: { opacity: 1, zIndex: 0 },
+  center: { opacity: 1, zIndex: 0 },
+  exit: { opacity: 0, zIndex: 1 }
 }
 
 const slideLeftVariants: Variants = {

package/src/core/types.ts

@@ -27,6 +27,8 @@ export type SlideComponent = React.ComponentType<SlideProps>
  * eliminating the need for runtime step discovery.
  */
 export interface SlideConfig {
+  /** Stable identifier for links and annotations. Keep unchanged when reordering slides. */
+  id?: string
   /** The slide component to render */
   component: SlideComponent
   /** Number of animation steps (0 = no animations). This is the max step number used in <Animated step={N}> */

package/src/core/use-slide-navigation.ts

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useState } from "react"
+import { useCallback, useEffect, useRef, useState } from "react"
 
 import type { NavigationDirection, SlideConfig } from "./types"
 
@@ -15,6 +15,42 @@ interface NavigationState {
   direction: NavigationDirection
 }
 
+const POSITION_KEY = "promptslide:position"
+
+function slideKey(slides: SlideConfig[], index: number): string {
+  return slides[index]?.id || String(index + 1)
+}
+
+function slideFromHash(slides: SlideConfig[]): number | null {
+  if (typeof window === "undefined" || !window.location.hash) return null
+  let hash: string
+  try {
+    hash = decodeURIComponent(window.location.hash.slice(1))
+  } catch {
+    return null
+  }
+  const byId = slides.findIndex(slide => slide.id === hash)
+  if (byId >= 0) return byId
+  if (/^[1-9]\d*$/.test(hash)) {
+    const index = Number(hash) - 1
+    if (index < slides.length) return index
+  }
+  return null
+}
+
+function savedStep(slides: SlideConfig[], index: number): number {
+  if (typeof window === "undefined") return 0
+  try {
+    const saved = JSON.parse(window.sessionStorage.getItem(POSITION_KEY) || "null")
+    if (saved?.slide === slideKey(slides, index) && Number.isInteger(saved.step)) {
+      return Math.max(0, Math.min(saved.step, slides[index]?.steps ?? 0))
+    }
+  } catch {
+    /* Storage may be unavailable. */
+  }
+  return 0
+}
+
 export interface UseSlideNavigationOptions {
   slides: SlideConfig[]
   initialSlide?: number
@@ -43,8 +79,12 @@ export function useSlideNavigation({
   initialSlide = 0,
   onSlideChange
 }: UseSlideNavigationOptions): UseSlideNavigationReturn {
-  const [currentSlide, setCurrentSlide] = useState(initialSlide)
-  const [animationStep, setAnimationStep] = useState(0)
+  const [currentSlide, setCurrentSlide] = useState(() => slideFromHash(slides) ?? initialSlide)
+  const [animationStep, setAnimationStep] = useState(() =>
+    savedStep(slides, slideFromHash(slides) ?? initialSlide)
+  )
+  const slidesRef = useRef(slides)
+  const activeKeyRef = useRef(slideKey(slides, slideFromHash(slides) ?? initialSlide))
 
   const [navState, setNavState] = useState<NavigationState>({
     status: "idle",
@@ -55,6 +95,56 @@ export function useSlideNavigation({
 
   const totalSteps = slides[currentSlide]?.steps ?? 0
 
+  useEffect(() => {
+    if (typeof window === "undefined" || slides.length === 0) return
+    if (slidesRef.current !== slides) {
+      slidesRef.current = slides
+      const previousKey = activeKeyRef.current
+      const movedIndex = slides.findIndex(slide => slide.id && slide.id === previousKey)
+      if (movedIndex >= 0 && movedIndex !== currentSlide) {
+        setCurrentSlide(movedIndex)
+        return
+      }
+      if (movedIndex < 0 && !/^[1-9]\d*$/.test(previousKey) && currentSlide !== 0) {
+        setAnimationStep(0)
+        setCurrentSlide(0)
+        return
+      }
+    }
+    if (!slides[currentSlide]) {
+      setCurrentSlide(0)
+      setAnimationStep(0)
+      return
+    }
+    const key = slideKey(slides, currentSlide)
+    activeKeyRef.current = key
+    const hash = `#${encodeURIComponent(key)}`
+    if (window.location.hash !== hash) {
+      window.history.replaceState(window.history.state, "", hash)
+    }
+    try {
+      window.sessionStorage.setItem(
+        POSITION_KEY,
+        JSON.stringify({ slide: key, step: animationStep })
+      )
+    } catch {
+      /* Storage may be unavailable. */
+    }
+  }, [slides, currentSlide, animationStep])
+
+  useEffect(() => {
+    const handleHashChange = () => {
+      const index = slideFromHash(slides) ?? 0
+      if (index === currentSlide) return
+      setNavState({ status: "transitioning", direction: index > currentSlide ? 1 : -1 })
+      setAnimationStep(0)
+      setCurrentSlide(index)
+      onSlideChange?.(index)
+    }
+    window.addEventListener("hashchange", handleHashChange)
+    return () => window.removeEventListener("hashchange", handleHashChange)
+  }, [slides, currentSlide, onSlideChange])
+
   const onTransitionComplete = useCallback(() => {
     setNavState(prev => {
       if (prev.status === "transitioning") {

package/src/editor/README.md

@@ -0,0 +1,35 @@
+# Development source editor
+
+Run `promptslide studio` and choose **Edit** in the existing top-right toolbar. The editor is injected by the development Vite plugin. Production builds, registry previews, embeds, and export pages do not load it. No editable-component migration is needed.
+
+## Workflow
+
+- Double-click literal text to edit it in place. Select an existing element, or use Slide elements. Shift-click selects several elements. Double-click a selected group to reach the element under the pointer; click outside the slide to deselect.
+- Edit literal text and title/subtitle/eyebrow properties, appearance, image URLs, or public asset paths in Design. Arrange contains positioning and alignment controls.
+- Drag selection outlines to move. The lower handle resizes; the upper handle rotates. Arrow keys nudge by one design pixel, Shift by ten. Alt disables snapping. All geometry is measured in the 1280 × 720 design canvas.
+- Align selected elements along either axis or distribute three or more with equal gaps. Bring forward / Send back set stacking order.
+- For images, adjust the frame size, objectFit, objectPosition, and inset crop.
+- Select a range in Text and apply bold, italic, or underline. Save existing text changes first. Range formatting creates ordinary styled JSX spans, which can subsequently be selected individually.
+- Structure supports inserting text, shapes, and images into JSX containers and duplicating/deleting direct JSX children. Root components and expressions cannot be deleted. Duplicates preview immediately and support Undo and Discard; save to edit copies independently. Insertions render after Save; range formatting previews immediately.
+- Undo/redo affects the buffered draft. Save batches edits to source; Discard restores the source rendering. Close requires resolving unsaved changes. The browser tab retains its draft across hot reloads. Export draft downloads the pending operations for recovery.
+- Editing uses the original viewer canvas, styling, and animation wrappers. Leave Edit to reveal steps normally; opening Edit preserves the currently visible content.
+
+## Source semantics
+
+Instrumentation adds source coordinates and a SHA-256 file revision only to the transformed development module. The original TSX is unchanged until Save. Intrinsic DOM elements and `motion.*` elements are supported. Source files must resolve inside the project's `src/` directory; symlinks outside it are rejected.
+
+A style change belongs to a JSX definition, so it affects all instances of that definition, including shared layouts. Movement uses the individual CSS `translate` property, preserving normal flex/grid flow and existing Motion transforms; rotation uses `rotate`. Resizing sets explicit frame dimensions. It does not convert the deck into an absolute-positioned document.
+
+For direct local `array.map(item => <p>{item.title}</p>)` expressions over literal object arrays, text edits address the selected array item. Imported arrays, spreads, ambiguous bindings, computed expressions, and mixed children are intentionally read-only. Edit those expressions in code. Simple local component text props are resolved automatically when their rendered text is selected, without requiring the component to forward DOM metadata. Ambiguous or imported prop relationships remain unsupported. Shared appearance controls require opting in when multiple matching instances are present on the current slide.
+
+Every batch checks all file revisions and validates all resulting TSX syntax before writing. Stale edits receive HTTP 409. Export or discard the draft and reselect from the current source; there is no force-overwrite button. Deleting an element discards pending edits on that element and its descendants. Other parent/child structural edits that overlap must be saved separately. This is optimistic concurrency protection, not a filesystem transaction across external processes. A save failure rolls back files still matching this operation's output.
+
+The endpoint uses a per-server random token, checks cross-site fetches, limits payload size and operation counts, and only runs in Vite serve mode. Studio enables editing on its default loopback interface. Passing `--host` (including `--host=...`) disables the editor, source instrumentation, and editor endpoint so shared previews cannot edit source files. The client token is a request guard, not authentication for network clients.
+
+## Verification
+
+- `node --test packages/cli/test/editor.test.mjs`: source edits, escaping, conflicts, batch validation, path restrictions, and array instances.
+- `node packages/cli/test/editor.browser.mjs`: isolated temporary deck; text/history, save/reload, concurrent edits, scaled dragging, and production bundle exclusion. Requires the package's Playwright Chromium installation.
+- `tsc -p packages/cli/tsconfig.json --noEmit`: editor and engine types.
+
+Implementation uses TypeScript's JSX parser and original-range patches. No OpenSlide source code is vendored.

package/src/editor/geometry.ts

@@ -0,0 +1,76 @@
+export interface Rect {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+export function translated(value: string, dx: number, dy: number) {
+  // Computed translate may contain percentages or calc() with spaces. Keep
+  // those units so movement does not remove centering or break after resizing.
+  const axes: string[] = []
+  let depth = 0,
+    start = 0
+  const input = value.trim()
+  for (let i = 0; i <= input.length; i++) {
+    const char = input[i]
+    if (char === "(") depth++
+    if (char === ")") depth--
+    if (i === input.length || (depth === 0 && /\s/.test(char!))) {
+      if (i > start) axes.push(input.slice(start, i))
+      start = i + 1
+    }
+  }
+  if (axes[0] === "none") axes.length = 0
+  const offset = (axis: string, delta: number) => {
+    if (!delta) return axis
+    if (/^-?(?:\d*\.)?\d+px$/.test(axis)) return `${parseFloat(axis) + delta}px`
+    return `calc(${axis} ${delta < 0 ? "-" : "+"} ${Math.abs(delta)}px)`
+  }
+  return [offset(axes[0] || "0px", dx), offset(axes[1] || "0px", dy), ...axes.slice(2)].join(" ")
+}
+export function snap(rect: Rect, others: Rect[], tolerance = 6) {
+  const xs = [0, 640, 1280, ...others.flatMap(r => [r.x, r.x + r.width / 2, r.x + r.width])]
+  const ys = [0, 360, 720, ...others.flatMap(r => [r.y, r.y + r.height / 2, r.y + r.height])]
+  const closest = (values: number[], targets: number[]) => {
+    let delta = tolerance + 1
+    let guide: number | undefined
+    for (const v of values)
+      for (const t of targets)
+        if (Math.abs(t - v) < Math.abs(delta)) {
+          delta = t - v
+          guide = t
+        }
+    return Math.abs(delta) <= tolerance ? { delta, guide } : { delta: 0, guide: undefined }
+  }
+  const x = closest([rect.x, rect.x + rect.width / 2, rect.x + rect.width], xs)
+  const y = closest([rect.y, rect.y + rect.height / 2, rect.y + rect.height], ys)
+  return { x: rect.x + x.delta, y: rect.y + y.delta, guideX: x.guide, guideY: y.guide }
+}
+export function aligned(
+  rects: Rect[],
+  axis: "x" | "y",
+  mode: "start" | "center" | "end" | "distribute"
+) {
+  const size = axis === "x" ? "width" : "height"
+  if (mode === "distribute") {
+    if (rects.length < 3) return rects.map(r => r[axis])
+    const sorted = rects.map((r, i) => ({ ...r, i })).sort((a, b) => a[axis] - b[axis])
+    const first = sorted[0]!,
+      last = sorted[sorted.length - 1]!
+    const gap =
+      (last[axis] + last[size] - first[axis] - sorted.reduce((s, r) => s + r[size], 0)) /
+      (rects.length - 1)
+    const result: number[] = []
+    let pos = first[axis]
+    for (const r of sorted) {
+      result[r.i] = pos
+      pos += r[size] + gap
+    }
+    return result
+  }
+  const min = Math.min(...rects.map(r => r[axis])),
+    max = Math.max(...rects.map(r => r[axis] + r[size]))
+  return rects.map(r =>
+    mode === "start" ? min : mode === "end" ? max - r[size] : (min + max - r[size]) / 2
+  )
+}

package/src/editor/mount.ts

@@ -0,0 +1,24 @@
+import { createElement } from "react"
+import { createRoot } from "react-dom/client"
+
+import { EditorLauncher } from "./studio"
+
+// Keep mounting outside the component module so React Fast Refresh can retain
+// the open editor, its draft, and its history when the sidebar code changes.
+export function mountEditor(
+  _slides: unknown,
+  _theme: unknown,
+  token: string,
+  initiallyOpen = false
+) {
+  if (document.getElementById("promptslide-editor-root")) return
+  const host = document.createElement("div")
+  host.id = "promptslide-editor-root"
+  document.body.appendChild(host)
+  const root = createRoot(host)
+  root.render(createElement(EditorLauncher, { token, initiallyOpen }))
+  return () => {
+    root.unmount()
+    host.remove()
+  }
+}

package/src/editor/plugin.mjs

@@ -0,0 +1,189 @@
+import { randomBytes } from "node:crypto"
+import {
+  readFileSync,
+  realpathSync,
+  writeFileSync,
+  renameSync,
+  statSync,
+  readdirSync
+} from "node:fs"
+import nodePath, { resolve, relative, sep, dirname } from "node:path"
+import { fileURLToPath } from "node:url"
+
+import { describe, editSource, instrument, revision } from "./source.mjs"
+
+export function sourceModulePath(base, id, paths = nodePath) {
+  const path = paths.resolve(id.split("?")[0])
+  const rel = paths.relative(base, path)
+  if (
+    !rel ||
+    rel === ".." ||
+    rel.startsWith(".." + paths.sep) ||
+    paths.isAbsolute(rel) ||
+    !/\.[jt]sx$/.test(path)
+  )
+    return
+  return path
+}
+
+export function editorPlugin({ root }) {
+  root = realpathSync(root)
+  const token = randomBytes(24).toString("hex")
+  const base = resolve(root, "src")
+  const client = resolve(dirname(fileURLToPath(import.meta.url)), "mount.ts")
+  const clientUrl = "/@fs/" + client
+  function sourcePath(path) {
+    if (typeof path !== "string" || !/\.[jt]sx$/.test(path)) throw new Error("Invalid source path")
+    const resolved = realpathSync(resolve(root, path))
+    const realBase = realpathSync(base)
+    if (!resolved.startsWith(realBase + sep)) throw new Error("Source must be inside project src/")
+    return resolved
+  }
+  return {
+    name: "promptslide-editor",
+    apply: "serve",
+    enforce: "pre",
+    transform(code, id) {
+      const path = sourceModulePath(base, id)
+      if (!path) return
+      return { code: instrument(code, relative(root, path)), map: null }
+    },
+    resolveId(id) {
+      if (id === "virtual:promptslide-editor") return "\0" + id
+    },
+    load(id) {
+      if (id !== "\0virtual:promptslide-editor") return
+      return `import { mountEditor } from ${JSON.stringify(clientUrl)};
+import { slides } from ${JSON.stringify(resolve(root, "src/deck-config.ts"))};
+import { theme } from ${JSON.stringify(resolve(root, "src/theme.ts"))};
+const dispose = mountEditor(slides, theme, ${JSON.stringify(token)}, import.meta.hot?.data.open ?? false);
+if (import.meta.hot) {
+  import.meta.hot.accept();
+  import.meta.hot.dispose((data) => {
+    data.open = document.querySelector('.ps-edit-action[aria-pressed="true"]') !== null;
+    dispose?.();
+    window.dispatchEvent(new Event("promptslide:editor-refresh"));
+  });
+}`
+    },
+    transformIndexHtml(html, ctx) {
+      const url = new URL(ctx.originalUrl ?? ctx.path, "http://localhost")
+      if (url.searchParams.get("pdf") === "true" || url.searchParams.get("export") === "true")
+        return
+      if (ctx.path !== "/" && ctx.path !== "/index.html") return
+      return {
+        html,
+        tags: [
+          {
+            tag: "script",
+            attrs: { type: "module", src: "/@id/virtual:promptslide-editor" },
+            injectTo: "body"
+          }
+        ]
+      }
+    },
+    configureServer(server) {
+      server.middlewares.use("/__promptslide_editor", (req, res) => {
+        const send = (status, data) => {
+          res.statusCode = status
+          res.setHeader("Content-Type", "application/json")
+          res.end(JSON.stringify(data))
+        }
+        if (
+          req.method !== "POST" ||
+          req.headers["x-promptslide-editor"] !== token ||
+          req.headers["sec-fetch-site"] === "cross-site"
+        )
+          return send(403, { error: "Editor access denied" })
+        let body = ""
+        req.on("data", chunk => {
+          body += chunk
+          if (body.length > 2_000_000) req.destroy()
+        })
+        req.on("end", () => {
+          try {
+            const data = JSON.parse(body)
+            if (data.action === "sources") {
+              const paths = []
+              function walk(directory) {
+                for (const entry of readdirSync(directory, { withFileTypes: true })) {
+                  if (
+                    entry.name.startsWith(".") ||
+                    entry.name === "node_modules" ||
+                    entry.isSymbolicLink()
+                  )
+                    continue
+                  const path = resolve(directory, entry.name)
+                  if (entry.isDirectory()) walk(path)
+                  else if (entry.isFile() && /\.[jt]sx$/.test(path))
+                    paths.push(relative(root, path))
+                }
+              }
+              walk(base)
+              return send(200, { paths: paths.sort() })
+            }
+            if (data.action === "inspect") {
+              const text = readFileSync(sourcePath(data.path), "utf8")
+              return send(200, { revision: revision(text), nodes: describe(text) })
+            }
+            if (
+              data.action !== "save" ||
+              !Array.isArray(data.files) ||
+              !data.files.length ||
+              data.files.length > 100
+            )
+              throw new Error("Invalid edit batch")
+            const seen = new Set()
+            const prepared = data.files.map(file => {
+              const path = sourcePath(file.path)
+              if (seen.has(path)) throw new Error("Duplicate file")
+              seen.add(path)
+              const before = readFileSync(path, "utf8")
+              if (revision(before) !== file.revision) {
+                const error = new Error(
+                  `Conflict in ${file.path}. Source changed; discard or export your draft before reloading.`
+                )
+                error.status = 409
+                throw error
+              }
+              if (!Array.isArray(file.edits) || file.edits.length > 1000)
+                throw new Error("Invalid edits")
+              return {
+                path,
+                before,
+                after: editSource(before, file.edits),
+                mode: statSync(path).mode
+              }
+            })
+            // No asynchronous gap between revision checks and commits. Roll back our writes if a commit fails.
+            const written = []
+            try {
+              for (const file of prepared) {
+                if (readFileSync(file.path, "utf8") !== file.before)
+                  throw new Error("Source changed during save")
+                const temp = file.path + ".promptslide-" + randomBytes(6).toString("hex")
+                writeFileSync(temp, file.after, { flag: "wx", mode: file.mode })
+                renameSync(temp, file.path)
+                written.push(file)
+              }
+            } catch (error) {
+              for (const file of written.reverse())
+                if (readFileSync(file.path, "utf8") === file.after)
+                  writeFileSync(file.path, file.before)
+              throw error
+            }
+            // Invalidate synchronously so a reload immediately after Save cannot receive
+            // the old transform while the filesystem watcher is still debouncing.
+            for (const file of prepared) {
+              for (const module of server.moduleGraph?.getModulesByFile(file.path) || [])
+                server.moduleGraph.invalidateModule(module)
+            }
+            send(200, { saved: prepared.length })
+          } catch (error) {
+            send(error.status || 400, { error: error.message })
+          }
+        })
+      })
+    }
+  }
+}