@editframe/create 0.43.0 → 0.45.0

package/dist/skills/editframe-composition/references/server-rendering.md

@@ -0,0 +1,753 @@
+---
+title: Server-Side Rendering
+description: Use SSR-safe imports and integrate Editframe with Next.js, Remix, and other server-rendered frameworks without hydration errors.
+type: reference
+nav:
+  parent: "Advanced"
+  priority: 30
+api:
+  entry_points:
+    - name: "@editframe/elements/server"
+      description: SSR-safe types and utilities (no DOM, no Web Components)
+      exports:
+        - getRenderInfo
+        - RenderInfo (type)
+        - EFTimegroup (type)
+        - EFMedia (type)
+        - RenderToVideoOptions (type)
+        - RenderProgress (type)
+        - ContentReadyMode (type)
+    - name: "@editframe/react/server"
+      description: SSR-safe React components and types
+      exports:
+        - Audio
+        - Captions
+        - CaptionsActiveWord
+        - CaptionsAfterActiveWord
+        - CaptionsBeforeActiveWord
+        - CaptionsSegment
+        - Text
+        - TextSegment
+        - Image
+        - Surface
+        - Timegroup
+        - Video
+        - Waveform
+        - PanZoom
+        - RenderToVideoOptions (type)
+        - RenderProgress (type)
+  functions:
+    - name: getRenderInfo
+      signature: "getRenderInfo(html: string): Promise<RenderInfo>"
+      description: Extract render metadata from HTML composition (Node.js safe)
+      returns: RenderInfo
+react:
+  generate: true
+  componentName: "Server-Side Rendering"
+  importPath: "@editframe/react"
+  nav:
+    parent: "Advanced / Server Integration"
+    priority: 85
+---
+
+# Server-Side Rendering
+
+<!-- html-only -->
+Editframe packages provide SSR-safe entry points for server-side rendering with Next.js, Remix, and other React frameworks. Import from `@editframe/elements/server` or `@editframe/react/server` to access types and components without triggering browser-specific code.
+<!-- /html-only -->
+<!-- react-only -->
+Editframe provides an SSR-safe entry point for server-side rendering with Next.js, Remix, and other React frameworks.
+<!-- /react-only -->
+
+## Problem: Browser APIs in SSR
+
+<!-- html-only -->
+The main package entries (`@editframe/elements` and `@editframe/react`) import browser-specific code at the module level:
+- Web Components (`customElements.define()`)
+- DOM APIs (`HTMLElement`, `document`, `window`)
+- Canvas, WebGL, WebCodecs APIs
+<!-- /html-only -->
+<!-- react-only -->
+The main entry point (`@editframe/react`) imports browser-specific code at the module level:
+- Web Components (`customElements.define()`)
+- DOM APIs (`document`, `window`)
+- Browser-only hooks
+- Canvas, WebGL, WebCodecs APIs
+<!-- /react-only -->
+
+This code **will crash** if imported during server-side rendering because Node.js doesn't provide these APIs.
+
+## Solution: SSR-Safe Entry Points
+
+<!-- html-only -->
+Use the `/server` subpath exports that only include types and SSR-safe utilities.
+
+## @editframe/elements/server
+
+Import **types only** and the `getRenderInfo` utility:
+
+```typescript
+import type {
+  EFTimegroup,
+  EFMedia,
+  RenderToVideoOptions,
+  RenderProgress,
+} from "@editframe/elements/server";
+
+import { getRenderInfo } from "@editframe/elements/server";
+```
+
+### What's Included
+
+- **Types:** TypeScript type definitions for all elements (zero runtime code)
+- **getRenderInfo:** Function to extract render metadata from HTML (Node.js safe)
+
+### What's NOT Included
+
+- Web Component class definitions
+- DOM manipulation utilities
+- Browser-specific rendering code
+- Canvas or WebGL APIs
+
+### getRenderInfo Example
+
+```typescript
+// server.ts (Node.js safe)
+import { getRenderInfo } from "@editframe/elements/server";
+
+const html = `
+  <ef-timegroup mode="sequence" duration="30s">
+    <ef-video src="intro.mp4"></ef-video>
+    <ef-video src="outro.mp4"></ef-video>
+  </ef-timegroup>
+`;
+
+const info = await getRenderInfo(html);
+console.log(info.durationMs); // 30000
+console.log(info.width); // 1920
+console.log(info.height); // 1080
+```
+
+## @editframe/react/server
+
+Import **React components** that render to HTML without triggering browser APIs:
+
+```typescript
+import {
+  Timegroup,
+  Video,
+  Audio,
+  Image,
+  Text,
+  Captions,
+  Surface,
+  Waveform,
+  PanZoom,
+} from "@editframe/react/server";
+```
+
+### What's Included
+
+- All composition React components (render to `<ef-*>` tags)
+- Caption styling sub-components
+- All types from `@editframe/elements/server`
+
+### What's NOT Included
+
+- GUI components (Preview, Workbench, Controls, Timeline, etc.)
+- Hooks that depend on browser APIs (`useTimingInfo`, `usePlayback`, etc.)
+- Browser rendering utilities
+<!-- /html-only -->
+<!-- react-only -->
+Import from `@editframe/react/server` to access composition components without triggering browser code:
+
+```tsx
+import {
+  Timegroup,
+  Video,
+  Audio,
+  Image,
+  Text,
+  Captions,
+  Surface,
+  Waveform,
+  PanZoom,
+} from "@editframe/react/server";
+```
+
+## What's Included
+
+**Composition Components:**
+- `Timegroup` - Timeline container
+- `Video`, `Audio`, `Image` - Media elements
+- `Text`, `TextSegment` - Text rendering
+- `Captions` + sub-components - Caption styling
+- `Surface` - Element mirroring
+- `Waveform` - Audio visualization
+- `PanZoom` - Pan/zoom container
+
+**Types:**
+- All render option types (`RenderToVideoOptions`, `RenderProgress`, etc.)
+- All component prop types
+
+## What's NOT Included
+
+**GUI Components:**
+- `Preview`, `Workbench`, `Timeline`, `Controls`
+- `Scrubber`, `Filmstrip`, `TimelineRuler`
+- `Canvas`, `TransformHandles`, `Hierarchy`
+- Any editor/preview UI components
+
+**Hooks:**
+- `useTimingInfo`, `usePlayback`, `useCompositionTime`
+- `usePanZoomTransform`, `useMediaInfo`
+- All browser-dependent hooks
+
+**Browser Utilities:**
+- `renderToVideo`, `createRenderClone`
+- Browser-specific helpers
+<!-- /react-only -->
+
+## Next.js Integration
+
+### App Router (React Server Components)
+
+<!-- html-only -->
+```typescript
+// app/video/[id]/page.tsx (Server Component)
+import { Timegroup, Video, Audio } from "@editframe/react/server";
+
+export default function VideoPage({ params }: { params: { id: string } }) {
+  return (
+    <Timegroup mode="sequence" className="w-[1920px] h-[1080px]">
+      <Video src={`/api/videos/${params.id}/intro.mp4`} className="size-full" />
+      <Audio src={`/api/videos/${params.id}/music.mp3`} volume={0.3} />
+    </Timegroup>
+  );
+}
+```
+<!-- /html-only -->
+<!-- react-only -->
+Import from `/server` in Server Components:
+
+```tsx
+// app/video/[id]/page.tsx (Server Component)
+import { Timegroup, Video, Audio } from "@editframe/react/server";
+
+interface Props {
+  params: { id: string };
+}
+
+export default function VideoPage({ params }: Props) {
+  return (
+    <Timegroup mode="sequence" className="w-[1920px] h-[1080px] bg-black">
+      <Video src={`/api/videos/${params.id}/intro.mp4`} className="size-full" />
+      <Audio src={`/api/videos/${params.id}/music.mp3`} volume={0.3} />
+    </Timegroup>
+  );
+}
+```
+<!-- /react-only -->
+
+### Pages Router (SSR)
+
+Use dynamic imports with `ssr: false` for browser-only code:
+
+<!-- html-only -->
+```typescript
+// pages/editor.tsx
+import dynamic from "next/dynamic";
+
+// Safe: imports from /server
+import { Timegroup, Video } from "@editframe/react/server";
+
+// Unsafe: imports from main entry, requires client-side only
+const Preview = dynamic(
+  () => import("@editframe/react").then((mod) => mod.Preview),
+  { ssr: false }
+);
+
+const Workbench = dynamic(
+  () => import("@editframe/react").then((mod) => mod.Workbench),
+  { ssr: false }
+);
+
+export default function EditorPage() {
+  return (
+    <div>
+      {/* This renders on server */}
+      <Timegroup mode="sequence" className="w-[1920px] h-[1080px]">
+        <Video src="/videos/intro.mp4" className="size-full" />
+      </Timegroup>
+
+      {/* This only renders on client */}
+      <Workbench rendering={false} />
+    </div>
+  );
+}
+```
+<!-- /html-only -->
+<!-- react-only -->
+```tsx
+// pages/video/[id].tsx
+import type { GetServerSideProps } from "next";
+import { Timegroup, Video } from "@editframe/react/server";
+
+interface Props {
+  videoUrl: string;
+}
+
+export const getServerSideProps: GetServerSideProps<Props> = async ({ params }) => {
+  const videoUrl = await fetchVideoUrl(params?.id);
+  return { props: { videoUrl } };
+};
+
+export default function VideoPage({ videoUrl }: Props) {
+  return (
+    <Timegroup mode="fixed" duration="10s" className="w-[1920px] h-[1080px]">
+      <Video src={videoUrl} className="size-full" />
+    </Timegroup>
+  );
+}
+```
+
+### Client-Only Components
+
+For editor UI components, use dynamic imports with `ssr: false`:
+
+```tsx
+// pages/editor.tsx
+import dynamic from "next/dynamic";
+import { Timegroup, Video } from "@editframe/react/server";
+
+// Safe: SSR-safe components
+const composition = (
+  <Timegroup mode="sequence" className="w-[1920px] h-[1080px]">
+    <Video src="/video.mp4" className="size-full" />
+  </Timegroup>
+);
+
+// Safe: Client-only dynamic import
+const Workbench = dynamic(
+  () => import("@editframe/react").then((mod) => mod.Workbench),
+  { ssr: false }
+);
+
+const Preview = dynamic(
+  () => import("@editframe/react").then((mod) => mod.Preview),
+  { ssr: false }
+);
+
+export default function EditorPage() {
+  return (
+    <div>
+      {composition}
+      <Workbench rendering={false} />
+    </div>
+  );
+}
+```
+<!-- /react-only -->
+
+## Remix Integration
+
+Use the `/server` entry for loaders and actions:
+
+```typescript
+// routes/video.$id.tsx
+import type { LoaderFunctionArgs } from "@remix-run/node";
+import { json } from "@remix-run/node";
+import { useLoaderData } from "@remix-run/react";
+import { Timegroup, Video, Audio } from "@editframe/react/server";
+
+export async function loader({ params }: LoaderFunctionArgs) {
+  const videoData = await fetchVideoData(params.id);
+  return json({ videoData });
+}
+
+export default function VideoRoute() {
+  const { videoData } = useLoaderData<typeof loader>();
+
+  return (
+    <Timegroup mode="sequence" className="w-[1920px] h-[1080px]">
+      <Video src={videoData.introUrl} className="size-full" />
+      <Audio src={videoData.musicUrl} volume={0.3} />
+    </Timegroup>
+  );
+}
+```
+
+For client-only components, use `ClientOnly`:
+
+```typescript
+import { ClientOnly } from "remix-utils/client-only";
+<!-- html-only -->
+
+export default function EditorRoute() {
+  return (
+    <ClientOnly>
+      {() => {
+        // Import happens only on client
+        const { Workbench } = require("@editframe/react");
+        return <Workbench rendering={false} />;
+      }}
+    </ClientOnly>
+  );
+}
+```
+<!-- /html-only -->
+<!-- react-only -->
+import { Timegroup, Video } from "@editframe/react/server";
+
+export default function EditorRoute() {
+  return (
+    <>
+      <Timegroup mode="sequence" className="w-[1920px] h-[1080px]">
+        <Video src="/video.mp4" className="size-full" />
+      </Timegroup>
+
+      <ClientOnly>
+        {() => {
+          const { Workbench } = require("@editframe/react");
+          return <Workbench rendering={false} />;
+        }}
+      </ClientOnly>
+    </>
+  );
+}
+```
+<!-- /react-only -->
+
+## Pre-rendering Static HTML
+
+Generate static HTML for compositions:
+
+```typescript
+// build.ts (Node.js)
+import { renderToString } from "react-dom/server";
+import { Timegroup, Video, Text } from "@editframe/react/server";
+import { writeFileSync } from "fs";
+
+const composition = (
+  <Timegroup mode="fixed" duration="10s" className="w-[1920px] h-[1080px]">
+    <Video src="/assets/background.mp4" className="size-full" />
+    <Text className="absolute inset-0 flex items-center justify-center text-6xl">
+      Hello World
+    </Text>
+  </Timegroup>
+);
+
+const html = renderToString(composition);
+writeFileSync("./dist/composition.html", html);
+```
+
+This HTML can then be hydrated on the client with the full browser-side code.
+
+<!-- react-only -->
+```tsx
+// client.tsx
+import { hydrateRoot } from "react-dom/client";
+import { Timegroup, Video, Text } from "@editframe/react"; // Full browser version
+
+hydrateRoot(
+  document.getElementById("root")!,
+  <Timegroup mode="fixed" duration="10s" className="w-[1920px] h-[1080px] bg-black">
+    <Video src="/assets/background.mp4" className="size-full object-cover" />
+    <Text className="absolute inset-0 flex items-center justify-center text-6xl text-white">
+      Hello World
+    </Text>
+  </Timegroup>
+);
+```
+<!-- /react-only -->
+
+## Type Imports
+
+When you only need types (not runtime code), use type-only imports for maximum safety:
+
+```typescript
+// Safe in any environment (no runtime code)
+import type { EFTimegroup, RenderToVideoOptions } from "@editframe/elements/server";
+<!-- react-only -->
+import type { TimegroupProps } from "@editframe/react/server";
+<!-- /react-only -->
+
+function createRenderConfig(): RenderToVideoOptions {
+  return {
+    fps: 30,
+    codec: "h264",
+    scale: 1,
+  };
+}
+```
+
+<!-- react-only -->
+## Type-Only Imports
+
+```typescript
+// Safe in any environment (no runtime code)
+import type { TimegroupProps, VideoProps, RenderToVideoOptions } from "@editframe/react/server";
+
+function createVideoConfig(): VideoProps {
+  return {
+    src: "/video.mp4",
+    className: "size-full",
+  };
+}
+
+function createRenderOptions(): RenderToVideoOptions {
+  return {
+    fps: 30,
+    codec: "h264",
+    scale: 1,
+  };
+}
+```
+
+## Environment-Based Imports
+
+Dynamically import based on environment:
+
+```tsx
+// VideoEditor.tsx
+import type { FC } from "react";
+
+let Timegroup: any;
+let Video: any;
+let Workbench: any;
+
+if (typeof window === "undefined") {
+  // Server: import from /server
+  const server = await import("@editframe/react/server");
+  Timegroup = server.Timegroup;
+  Video = server.Video;
+} else {
+  // Browser: import from main entry
+  const browser = await import("@editframe/react");
+  Timegroup = browser.Timegroup;
+  Video = browser.Video;
+  Workbench = browser.Workbench;
+}
+
+export const VideoEditor: FC = () => {
+  return (
+    <>
+      <Timegroup mode="sequence" className="w-[1920px] h-[1080px]">
+        <Video src="/video.mp4" className="size-full" />
+      </Timegroup>
+      {typeof window !== "undefined" && <Workbench rendering={false} />}
+    </>
+  );
+};
+```
+
+## Typical Setup
+
+### Development (main.tsx)
+
+```tsx
+// src/main.tsx (browser only)
+import ReactDOM from "react-dom/client";
+import { Configuration, TimelineRoot } from "@editframe/react";
+import { Video } from "./Video";
+import "@editframe/elements/styles.css";
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <Configuration mediaEngine="local">
+    <TimelineRoot id="root" component={Video} />
+  </Configuration>
+);
+```
+
+### Video Composition (Video.tsx)
+
+```tsx
+// src/Video.tsx (SSR-safe)
+import { Timegroup, Video, Audio, Text } from "@editframe/react/server";
+
+export const Video = () => {
+  return (
+    <Timegroup mode="sequence" className="w-[1920px] h-[1080px] bg-black">
+      <Timegroup mode="fixed" duration="5s" className="absolute inset-0">
+        <Video src="/assets/intro.mp4" className="size-full object-cover" />
+      </Timegroup>
+      <Timegroup mode="fixed" duration="10s" className="absolute inset-0">
+        <Video src="/assets/main.mp4" className="size-full object-cover" />
+        <Audio src="/assets/music.mp3" volume={0.3} />
+        <Text className="absolute bottom-0 left-0 p-8 text-4xl text-white">
+          Hello World
+        </Text>
+      </Timegroup>
+    </Timegroup>
+  );
+};
+```
+
+This pattern works in:
+- Browser (with `@editframe/react`)
+- SSR (with `@editframe/react/server`)
+- Static generation (with `@editframe/react/server`)
+<!-- /react-only -->
+
+## Common Patterns
+
+### Hydration After SSR
+
+**Server:**
+```typescript
+// server.tsx
+import { renderToString } from "react-dom/server";
+import { Timegroup, Video } from "@editframe/react/server";
+
+const html = renderToString(
+  <Timegroup mode="sequence" className="w-[1920px] h-[1080px]">
+    <Video src="/video.mp4" className="size-full" />
+  </Timegroup>
+);
+
+// Send html to client
+```
+
+**Client:**
+```typescript
+// client.tsx
+import { hydrateRoot } from "react-dom/client";
+import { Timegroup, Video } from "@editframe/react"; // Full browser version
+
+hydrateRoot(
+  document.getElementById("root"),
+  <Timegroup mode="sequence" className="w-[1920px] h-[1080px]">
+    <Video src="/video.mp4" className="size-full" />
+  </Timegroup>
+);
+```
+
+### Conditional Imports
+
+```typescript
+// utils.ts
+export async function loadEditorComponents() {
+  if (typeof window === "undefined") {
+    throw new Error("Editor components require browser environment");
+  }
+
+  const { Workbench, Preview, Timeline } = await import("@editframe/react");
+  return { Workbench, Preview, Timeline };
+}
+```
+
+## Troubleshooting
+
+### Error: `customElements is not defined`
+
+**Problem:** Importing from main entry point during SSR.
+
+**Solution:** Use `/server` entry point:
+```typescript
+// ❌ Wrong
+import { Timegroup } from "@editframe/react";
+
+// ✅ Correct
+import { Timegroup } from "@editframe/react/server";
+```
+
+### Error: `HTMLElement is not defined`
+
+**Problem:** Web Component class definition loaded during SSR.
+
+**Solution:** Use dynamic import with `ssr: false` or conditional import.
+
+### Error: `document is not defined`
+
+**Problem:** Browser-specific code running on server.
+
+**Solution:** Check imports and ensure all browser code is client-only.
+
+<!-- react-only -->
+### Error: `Cannot find module '@editframe/react/server'`
+
+**Problem:** Outdated package version.
+
+**Solution:**
+```bash
+npm install @editframe/react@latest
+```
+
+Ensure version is 0.37.0 or higher.
+
+### Error: `window is not defined`
+
+**Problem:** Browser code running on server.
+
+**Solution:** Use dynamic import with `ssr: false` or check environment:
+```tsx
+if (typeof window !== "undefined") {
+  // Browser-only code
+}
+```
+
+### Component renders but doesn't work
+
+**Problem:** Hydration mismatch between server and client.
+
+**Solution:** Ensure identical imports on both sides or use client-only rendering:
+```tsx
+import dynamic from "next/dynamic";
+
+const ClientComponent = dynamic(() => import("./Component"), {
+  ssr: false,
+});
+```
+
+## What About GUI Components?
+
+GUI components like `Workbench`, `Preview`, and `Timeline` are **never** SSR-safe because they:
+- Depend on browser APIs (`ResizeObserver`, `IntersectionObserver`, etc.)
+- Use Web Components internally
+- Require canvas and WebGL contexts
+- Need interactive event handling
+
+Always use dynamic imports for GUI components:
+
+```tsx
+const Workbench = dynamic(
+  () => import("@editframe/react").then((m) => m.Workbench),
+  { ssr: false }
+);
+```
+<!-- /react-only -->
+
+## Package Structure
+
+Both packages expose <!-- html-only -->three<!-- /html-only --> entry points:
+
+### @editframe/elements
+```json
+{
+  "exports": {
+    ".": "./dist/index.js",          // Browser: Full package (Web Components, DOM APIs)
+    "./server": "./dist/server.js",  // SSR: Types + getRenderInfo only
+    "./node": "./dist/node.js"       // Node: Same as /server (backward compat)
+  }
+}
+```
+
+### @editframe/react
+```json
+{
+  "exports": {
+    ".": "./dist/index.js",          // Browser: Full package (all components + hooks)
+    "./server": "./dist/server.js",  // SSR: Composition components only
+    "./r3f": "./dist/r3f/index.js"   // Browser: React Three Fiber integration
+  }
+}
+```
+
+## Related
+
+- [entry-points.md](references/entry-points.md) - Complete guide to package entry points
+- [r3f.md](references/r3f.md) - React Three Fiber integration
+- [getting-started.md](references/getting-started.md) - Installation and setup
+<!-- react-only -->
+- [configuration.md](references/configuration.md) - Configuration component
+<!-- /react-only -->