promptslide 0.3.15 → 0.3.17

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/index.mjs

@@ -40,6 +40,7 @@ function printHelp() {
   console.log()
   console.log(`  ${bold("Tools:")}`)
   console.log(`    to-image ${dim("<slide>")} Export a slide as a PNG image`)
+  console.log(`    to-pdf          Export the full deck as a PDF`)
   console.log()
   console.log(`  ${bold("Options:")}`)
   console.log(`    --help, -h      Show this help message`)
@@ -136,6 +137,11 @@ switch (command) {
     await toImage(args)
     break
   }
+  case "to-pdf": {
+    const { toPdf } = await import("./commands/to-pdf.mjs")
+    await toPdf(args)
+    break
+  }
   case "--help":
   case "-h":
   case undefined:

package/src/utils/deck-config.mjs

@@ -33,9 +33,9 @@ export function deriveImportPath(target, filePath) {
  * Uses string manipulation to preserve existing content.
  *
  * @param {string} cwd - Project root directory
- * @param {{ componentName: string, importPath: string, steps: number }} opts
+ * @param {{ componentName: string, importPath: string, steps: number, id?: string }} opts
  */
-export function addSlideToDeckConfig(cwd, { componentName, importPath, steps }) {
+export function addSlideToDeckConfig(cwd, { componentName, importPath, steps, id }) {
   const configPath = join(cwd, DECK_CONFIG_PATH)
   if (!existsSync(configPath)) {
     console.warn(`  Warning: ${DECK_CONFIG_PATH} not found. Skipping deck-config update.`)
@@ -51,7 +51,13 @@ export function addSlideToDeckConfig(cwd, { componentName, importPath, steps })
 
   // Build import and slide entry strings
   const importLine = `import { ${componentName} } from "${importPath}"`
-  const slideEntry = `  { component: ${componentName}, steps: ${steps} },`
+  const slideId =
+    id ||
+    importPath
+      .split("/")
+      .pop()
+      .replace(/^slide-/, "")
+  const slideEntry = `  { id: ${JSON.stringify(slideId)}, component: ${componentName}, steps: ${steps} },`
 
   // Find insertion point for import:
   // Look for the last import from "@/slides/" or "@/layouts/"
@@ -70,11 +76,12 @@ export function addSlideToDeckConfig(cwd, { componentName, importPath, steps })
   }
 
   // Insert import after last slide import, or after last import, or at top
-  const importInsertIdx = lastSlideImportIdx >= 0
-    ? lastSlideImportIdx + 1
-    : lastAnyImportIdx >= 0
-      ? lastAnyImportIdx + 1
-      : 0
+  const importInsertIdx =
+    lastSlideImportIdx >= 0
+      ? lastSlideImportIdx + 1
+      : lastAnyImportIdx >= 0
+        ? lastAnyImportIdx + 1
+        : 0
 
   importLines.splice(importInsertIdx, 0, importLine)
   content = importLines.join("\n")
@@ -169,7 +176,7 @@ export function removeSlideFromDeckConfig(cwd, componentName) {
  * Replace the entire deck-config.ts with a new slide manifest (for deck type).
  *
  * @param {string} cwd - Project root directory
- * @param {{ componentName: string, importPath: string, steps: number, section?: string }[]} slides
+ * @param {{ componentName: string, importPath: string, steps: number, id?: string, section?: string }[]} slides
  * @param {{ transition?: string, directionalTransition?: boolean }} opts
  */
 export function replaceDeckConfig(cwd, slides, opts = {}) {
@@ -182,7 +189,17 @@ export function replaceDeckConfig(cwd, slides, opts = {}) {
 
   const slideEntries = slides
     .map(s => {
-      const parts = [`component: ${s.componentName}`, `steps: ${s.steps}`]
+      const id =
+        s.id ||
+        s.importPath
+          .split("/")
+          .pop()
+          .replace(/^slide-/, "")
+      const parts = [
+        `id: ${JSON.stringify(id)}`,
+        `component: ${s.componentName}`,
+        `steps: ${s.steps}`
+      ]
       if (s.section) parts.push(`section: "${s.section}"`)
       return `  { ${parts.join(", ")} },`
     })
@@ -213,7 +230,7 @@ export function replaceDeckConfig(cwd, slides, opts = {}) {
 /**
  * Parse deck-config.ts and extract the deckConfig structure for publishing.
  * Returns { transition?, directionalTransition?, slides } where slides is
- * an array of { slug, steps, section? }.
+ * an array of { slug, id?, steps, section? }.
  *
  * @param {string} cwd - Project root directory
  * @returns {{ transition?: string, directionalTransition?: boolean, slides: { slug: string, steps: number, section?: string }[] } | null}
@@ -280,6 +297,8 @@ export function parseDeckConfig(cwd) {
       if (!slug) continue // layout or unknown import — skip
       const stepsMatch = body.match(/steps:\s*(\d+)/)
       const entry = { slug, steps: stepsMatch ? parseInt(stepsMatch[1], 10) : 0 }
+      const idMatch = body.match(/\bid:\s*["']([^"']+)["']/)
+      if (idMatch) entry.id = idMatch[1]
       // Preserve original component name so pull can reconstruct the correct export
       if (slugToComponent[slug]) entry.componentName = slugToComponent[slug]
       const sectionMatch = body.match(/section:\s*["']([^"']+)["']/)

package/src/utils/deck-sync.mjs

@@ -0,0 +1,78 @@
+/**
+ * Return the slide slugs backed by files in a resolved registry dependency set.
+ * Only registry-provided files count; scaffold files already present in a target
+ * directory must not make stale deck metadata look valid.
+ *
+ * @param {object[]} items
+ * @returns {Set<string>}
+ */
+export function collectRegistrySlideSlugs(items) {
+  const slugs = new Set()
+
+  for (const item of items ?? []) {
+    for (const file of item.files ?? []) {
+      const target = String(file.target ?? "")
+        .replaceAll("\\", "/")
+        .replace(/^\.\//, "")
+      const path = String(file.path ?? "")
+        .replaceAll("\\", "/")
+        .replace(/^\.\//, "")
+      const fullPath = `${target.replace(/\/?$/, "/")}${path}`.replace(/\/+/g, "/")
+      const match = fullPath.match(/^src\/slides\/(.+)\.tsx?$/)
+      if (match) slugs.add(match[1])
+    }
+  }
+
+  return slugs
+}
+
+/**
+ * Split deck metadata into entries backed by registry files and stale entries.
+ * Array order is preserved so generated deck configs match the published order.
+ *
+ * @param {object[]} slides
+ * @param {Set<string>} availableSlugs
+ * @returns {{ available: object[], missing: object[] }}
+ */
+export function partitionDeckSlides(slides, availableSlugs) {
+  const available = []
+  const missing = []
+
+  for (const slide of slides ?? []) {
+    if (availableSlugs.has(slide.slug)) available.push(slide)
+    else missing.push(slide)
+  }
+
+  return { available, missing }
+}
+
+/**
+ * Select slide files for deck publishing. By default, only files referenced by
+ * deck-config.ts are included. The opt-in flag retains the legacy publish-all
+ * behavior for users who intentionally publish scratch or library slides.
+ *
+ * @param {string[]} slideEntries
+ * @param {{ slug: string }[]} configuredSlides
+ * @param {boolean} includeUnreferenced
+ * @returns {{ selected: string[], unreferenced: string[], missing: string[] }}
+ */
+export function selectSlidesForPublish(
+  slideEntries,
+  configuredSlides,
+  includeUnreferenced = false
+) {
+  const filesBySlug = new Map(slideEntries.map(file => [file.replace(/\.tsx?$/, ""), file]))
+  const configuredSlugs = new Set(configuredSlides.map(slide => slide.slug))
+  const unreferenced = slideEntries.filter(
+    file => !configuredSlugs.has(file.replace(/\.tsx?$/, ""))
+  )
+  const missing = configuredSlides.map(slide => slide.slug).filter(slug => !filesBySlug.has(slug))
+  const selected = includeUnreferenced
+    ? [...slideEntries]
+    : configuredSlides.flatMap(slide => {
+        const file = filesBySlug.get(slide.slug)
+        return file ? [file] : []
+      })
+
+  return { selected, unreferenced, missing }
+}

package/src/utils/export.mjs

@@ -4,8 +4,9 @@ import { fileURLToPath } from "node:url"
 
 import { createServer } from "vite"
 
-import { ensureTsConfig } from "./tsconfig.mjs"
 import { createViteConfig } from "../vite/config.mjs"
+import { projectIdentity, readStudioServer } from "./studio-discovery.mjs"
+import { ensureTsConfig } from "./tsconfig.mjs"
 
 /**
  * Check if Playwright is available.
@@ -40,12 +41,88 @@ async function ensureChromium(chromium) {
   }
 }
 
+/** Find a Studio process serving this project; other projects must not be reused. */
+async function findStudioServer(cwd, preferredPort) {
+  const candidates = preferredPort
+    ? [`http://127.0.0.1:${preferredPort}`, `http://localhost:${preferredPort}`]
+    : [
+        readStudioServer(cwd),
+        ...Array.from({ length: 11 }, (_, i) => `http://127.0.0.1:${5173 + i}`)
+      ]
+  const results = await Promise.all(
+    candidates.filter(Boolean).map(async baseUrl => {
+      try {
+        const response = await fetch(`${baseUrl}/__promptslide_info`, {
+          signal: AbortSignal.timeout(350)
+        })
+        if (!response.ok) return null
+        const info = await response.json()
+        return info.projectId === projectIdentity(cwd) ? baseUrl : null
+      } catch {
+        return null
+      }
+    })
+  )
+  return results.find(Boolean) || null
+}
+
+async function getCaptureServer(cwd, preferredPort) {
+  const studio = await findStudioServer(cwd, preferredPort)
+  if (studio) return { baseUrl: studio, close: async () => {} }
+
+  ensureTsConfig(cwd)
+  const config = createViteConfig({ cwd, mode: "development" })
+  const server = await createServer({
+    ...config,
+    server: { port: 0, strictPort: true },
+    logLevel: "silent"
+  })
+  await server.listen()
+  const address = server.httpServer.address()
+  const port = typeof address === "object" ? address.port : 0
+  return { baseUrl: `http://127.0.0.1:${port}`, close: () => server.close() }
+}
+
+async function waitForExport(page, errors) {
+  try {
+    const handle = await page.waitForFunction(
+      () => {
+        const overlay = document.querySelector("vite-error-overlay")
+        if (overlay) {
+          const root = overlay.shadowRoot
+          return {
+            error:
+              root?.querySelector(".message-body")?.textContent ||
+              root?.textContent ||
+              "Vite compilation failed"
+          }
+        }
+        if (document.querySelector("[data-export-ready='true']")) return { ready: true }
+        return false
+      },
+      null,
+      { timeout: 15000 }
+    )
+    const result = await handle.jsonValue()
+    if (result.error) throw new Error(`Slide compile error: ${result.error.trim()}`)
+  } catch (err) {
+    if (errors.length) throw new Error(`${err.message}\nBrowser errors:\n  ${errors.join("\n  ")}`)
+    throw err
+  }
+}
+
 /**
  * Capture a screenshot of a specific slide.
  * @param {{ cwd: string, slidePath: string, width?: number, height?: number }} opts
  * @returns {Promise<Buffer | null>} PNG buffer, or null if Playwright is not installed
  */
-export async function captureSlideScreenshot({ cwd, slidePath, width = 1280, height = 720 }) {
+export async function captureSlideScreenshot({
+  cwd,
+  slidePath,
+  width = 1280,
+  height = 720,
+  studioPort
+}) {
   let chromium
   try {
     const pw = await import("playwright")
@@ -56,19 +133,8 @@ export async function captureSlideScreenshot({ cwd, slidePath, width = 1280, hei
 
   await ensureChromium(chromium)
 
-  ensureTsConfig(cwd)
-
-  const config = createViteConfig({ cwd, mode: "development" })
-  const server = await createServer({
-    ...config,
-    server: { port: 0, strictPort: false },
-    logLevel: "silent"
-  })
-  await server.listen()
-
-  const address = server.httpServer.address()
-  const port = typeof address === "object" ? address.port : 0
-  const url = `http://localhost:${port}/?export=true&slidePath=${encodeURIComponent(slidePath)}`
+  const server = await getCaptureServer(cwd, studioPort)
+  const url = `${server.baseUrl}/?export=true&slidePath=${encodeURIComponent(slidePath)}`
 
   let browser
   try {
@@ -78,14 +144,10 @@ export async function captureSlideScreenshot({ cwd, slidePath, width = 1280, hei
     const errors = []
     page.on("pageerror", err => errors.push(err.message))
 
-    await page.goto(url, { waitUntil: "domcontentloaded", timeout: 15000 })
-    await page.waitForSelector("[data-export-ready='true']", { timeout: 15000 }).catch(err => {
-      if (errors.length) {
-        throw new Error(`${err.message}\n  Browser errors:\n    ${errors.join("\n    ")}`)
-      }
-      throw err
-    })
-    await page.waitForTimeout(200)
+    const response = await page.goto(url, { waitUntil: "domcontentloaded", timeout: 15000 })
+    if (!response?.ok())
+      throw new Error(`Slide export failed: ${response?.status()} ${await response?.text()}`)
+    await waitForExport(page, errors)
 
     const element = await page.$("[data-export-ready='true']")
     const screenshot = await element.screenshot({ type: "png" })
@@ -105,7 +167,7 @@ export async function captureSlideScreenshot({ cwd, slidePath, width = 1280, hei
  * @returns {Promise<{ capture: (slidePath: string) => Promise<string | null>, close: () => Promise<void> } | null>}
  *   null if Playwright is not available
  */
-export async function createCaptureSession({ cwd, width = 1280, height = 720 }) {
+export async function createCaptureSession({ cwd, width = 1280, height = 720, studioPort }) {
   let chromium
   try {
     const pw = await import("playwright")
@@ -115,36 +177,21 @@ export async function createCaptureSession({ cwd, width = 1280, height = 720 })
   }
 
   await ensureChromium(chromium)
-  ensureTsConfig(cwd)
-
-  const config = createViteConfig({ cwd, mode: "development" })
-  const server = await createServer({
-    ...config,
-    server: { port: 0, strictPort: false },
-    logLevel: "silent"
-  })
-  await server.listen()
-
-  const address = server.httpServer.address()
-  const port = typeof address === "object" ? address.port : 0
-
+  const server = await getCaptureServer(cwd, studioPort)
   const browser = await chromium.launch({ headless: true })
+  const page = await browser.newPage({ viewport: { width, height } })
+  let pending = Promise.resolve()
 
-  async function capture(slidePath) {
-    const url = `http://localhost:${port}/?export=true&slidePath=${encodeURIComponent(slidePath)}`
-    const page = await browser.newPage({ viewport: { width, height } })
+  async function captureOne(slidePath) {
+    const url = `${server.baseUrl}/?export=true&slidePath=${encodeURIComponent(slidePath)}`
+    const errors = []
+    const onPageError = err => errors.push(err.message)
+    page.on("pageerror", onPageError)
     try {
-      const errors = []
-      page.on("pageerror", err => errors.push(err.message))
-
-      await page.goto(url, { waitUntil: "domcontentloaded", timeout: 15000 })
-      await page.waitForSelector("[data-export-ready='true']", { timeout: 15000 }).catch(err => {
-        if (errors.length) {
-          throw new Error(`${err.message}\n  Browser errors:\n    ${errors.join("\n    ")}`)
-        }
-        throw err
-      })
-      await page.waitForTimeout(200)
+      const response = await page.goto(url, { waitUntil: "domcontentloaded", timeout: 15000 })
+      if (!response?.ok())
+        throw new Error(`Slide export failed: ${response?.status()} ${await response?.text()}`)
+      await waitForExport(page, errors)
 
       const element = await page.$("[data-export-ready='true']")
       const screenshot = await element.screenshot({ type: "png" })
@@ -153,11 +200,22 @@ export async function createCaptureSession({ cwd, width = 1280, height = 720 })
       console.error(`  Screenshot error: ${err.message}`)
       return null
     } finally {
-      await page.close().catch(() => {})
+      page.off("pageerror", onPageError)
     }
   }
 
+  function capture(slidePath) {
+    const result = pending.then(() => captureOne(slidePath))
+    pending = result.then(
+      () => {},
+      () => {}
+    )
+    return result
+  }
+
   async function close() {
+    await pending
+    await page.close().catch(() => {})
     await browser.close().catch(() => {})
     await server.close()
   }
@@ -181,3 +239,44 @@ export async function captureSlideAsDataUri({ cwd, slidePath }) {
     return null
   }
 }
+
+/** Render the whole deck at its design size through an existing Studio server. */
+export async function captureDeckPdfFromServer(baseUrl) {
+  const { chromium } = await import("playwright")
+  await ensureChromium(chromium)
+  const browser = await chromium.launch({ headless: true })
+  try {
+    const page = await browser.newPage({ viewport: { width: 1280, height: 720 } })
+    const errors = []
+    page.on("pageerror", error => errors.push(error.message))
+    const response = await page.goto(`${baseUrl}/?pdf=true`, {
+      waitUntil: "domcontentloaded",
+      timeout: 15000
+    })
+    if (!response?.ok()) throw new Error(`Deck PDF export failed: ${response?.status()}`)
+    try {
+      await page.waitForSelector("[data-pdf-ready='true']", { timeout: 15000 })
+    } catch (error) {
+      if (errors.length)
+        throw new Error(`${error.message}\nBrowser errors:\n  ${errors.join("\n  ")}`)
+      throw error
+    }
+    return await page.pdf({
+      width: "1280px",
+      height: "720px",
+      printBackground: true,
+      preferCSSPageSize: true
+    })
+  } finally {
+    await browser.close()
+  }
+}
+
+export async function captureDeckPdf({ cwd, studioPort }) {
+  const server = await getCaptureServer(cwd, studioPort)
+  try {
+    return await captureDeckPdfFromServer(server.baseUrl)
+  } finally {
+    await server.close()
+  }
+}

package/src/utils/registry.mjs

@@ -150,6 +150,29 @@ export function removeLockfileItem(cwd, slug) {
   writeLockfile(cwd, lock)
 }
 
+/**
+ * Remove lockfile entries whose tracked files have all disappeared locally.
+ * Entries with no files (such as the deck manifest) are retained.
+ *
+ * @param {string} cwd
+ * @param {{ items?: Record<string, { files?: Record<string, string> }> }} lock
+ * @returns {string[]} Removed item slugs
+ */
+export function pruneMissingLockfileItems(cwd, lock) {
+  const removed = []
+  lock.items ||= {}
+
+  for (const [slug, item] of Object.entries(lock.items)) {
+    const paths = Object.keys(item.files ?? {})
+    if (paths.length > 0 && paths.every(path => !existsSync(join(cwd, path)))) {
+      delete lock.items[slug]
+      removed.push(slug)
+    }
+  }
+
+  return removed
+}
+
 /**
  * Build common auth headers for registry API requests.
  * @param {{ token: string, organizationId?: string }} auth

package/src/utils/studio-discovery.mjs

@@ -0,0 +1,37 @@
+import { createHash } from "node:crypto"
+import { readFileSync, writeFileSync, unlinkSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join, resolve } from "node:path"
+
+export function projectIdentity(cwd) {
+  return createHash("sha256").update(resolve(cwd)).digest("hex").slice(0, 16)
+}
+
+function discoveryPath(cwd) {
+  return join(tmpdir(), `promptslide-studio-${projectIdentity(cwd)}.json`)
+}
+
+export function registerStudioServer(cwd, baseUrl) {
+  const path = discoveryPath(cwd)
+  writeFileSync(
+    path,
+    JSON.stringify({ root: resolve(cwd), baseUrl: baseUrl.replace(/\/$/, ""), pid: process.pid })
+  )
+  process.on("exit", () => {
+    try {
+      const current = JSON.parse(readFileSync(path, "utf8"))
+      if (current.pid === process.pid) unlinkSync(path)
+    } catch {
+      /* Another process may have removed the file. */
+    }
+  })
+}
+
+export function readStudioServer(cwd) {
+  try {
+    const info = JSON.parse(readFileSync(discoveryPath(cwd), "utf8"))
+    return info.root === resolve(cwd) ? info.baseUrl : null
+  } catch {
+    return null
+  }
+}