add ttyd exec util function (#111)

Author: HUAHUAI23

app/projects/[id]/exec-test/client.tsx

@@ -0,0 +1,12 @@
+'use client'
+
+import { TtydExecTest } from '@/components/terminal/ttyd-exec-test'
+
+interface TtydExecTestClientProps {
+  ttydUrl: string
+  accessToken: string
+}
+
+export function TtydExecTestClient({ ttydUrl, accessToken }: TtydExecTestClientProps) {
+  return <TtydExecTest ttydUrl={ttydUrl} accessToken={accessToken} />
+}

app/projects/[id]/exec-test/page.tsx

@@ -0,0 +1,85 @@
+/**
+ * Terminal Exec Test Page
+ *
+ * Test page for verifying the ttyd-exec utility works in the browser.
+ * Accessible at: /projects/[id]/exec-test
+ */
+
+import { notFound,redirect } from 'next/navigation'
+
+import { auth } from '@/lib/auth'
+import { prisma } from '@/lib/db'
+
+import { TtydExecTestClient } from './client'
+
+export default async function ExecTestPage({
+  params,
+}: {
+  params: Promise<{ id: string }>
+}) {
+  const session = await auth()
+
+  if (!session) {
+    redirect('/login')
+  }
+
+  const { id } = await params
+
+  // Get project with sandbox
+  const project = await prisma.project.findFirst({
+    where: {
+      id: id,
+      userId: session.user.id,
+    },
+    include: {
+      sandboxes: true,
+      environments: true,
+    },
+  })
+
+  if (!project) {
+    notFound()
+  }
+
+  const sandbox = project.sandboxes[0]
+
+  // Get TTYD access token from environments
+  const ttydAccessToken = project.environments.find(
+    (env) => env.key === 'TTYD_ACCESS_TOKEN'
+  )?.value
+
+  if (!sandbox?.ttydUrl || !ttydAccessToken) {
+    return (
+      <div className="p-8">
+        <div className="max-w-2xl mx-auto bg-gray-900 text-white rounded-lg p-6">
+          <h2 className="text-lg font-semibold mb-4 text-red-400">Configuration Missing</h2>
+          <div className="space-y-2 text-sm text-gray-300">
+            <p>
+              <strong>ttydUrl:</strong> {sandbox?.ttydUrl || 'Not available'}
+            </p>
+            <p>
+              <strong>accessToken:</strong> {ttydAccessToken ? 'Configured' : 'Not configured'}
+            </p>
+            <p>
+              <strong>Sandbox Status:</strong> {sandbox?.status || 'No sandbox'}
+            </p>
+          </div>
+          <p className="mt-4 text-yellow-400 text-sm">
+            Make sure the sandbox is RUNNING and TTYD_ACCESS_TOKEN is set in environments.
+          </p>
+        </div>
+      </div>
+    )
+  }
+
+  // Parse the ttydUrl to get base URL (without query params)
+  const ttydBaseUrl = new URL(sandbox.ttydUrl)
+  ttydBaseUrl.search = '' // Remove query params
+  const baseUrl = ttydBaseUrl.toString().replace(/\/$/, '')
+
+  return (
+    <div className="p-8 overflow-auto h-full">
+      <TtydExecTestClient ttydUrl={baseUrl} accessToken={ttydAccessToken} />
+    </div>
+  )
+}

components/layout/project-content-wrapper.module.css

@@ -0,0 +1,38 @@
+/**
+ * ProjectContentWrapper Styles
+ *
+ * Controls visibility of terminal and content panels
+ * Uses data attributes for semantic clarity
+ */
+
+.wrapper {
+  width: 100%;
+  height: 100%;
+  position: relative;
+}
+
+.panel {
+  width: 100%;
+  height: 100%;
+}
+
+/* Hide panels when not visible */
+.panel[data-visible='false'] {
+  display: none;
+  content-visibility: hidden; /* Modern CSS optimization */
+}
+
+/* Terminal panel - block layout */
+.terminalPanel[data-visible='true'] {
+  display: block;
+  content-visibility: auto;
+}
+
+/* Content panel - flex layout */
+.contentPanel[data-visible='true'] {
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  min-height: 0;
+  content-visibility: auto;
+}

components/layout/project-content-wrapper.tsx

@@ -1,40 +1,78 @@
+/**
+ * ProjectContentWrapper Component
+ *
+ * Manages visibility of terminal and content panels based on current route.
+ * Uses CSS-based visibility toggling to preserve component state during navigation.
+ *
+ * Architecture:
+ * - Terminal panel: Persisted in layout, never unmounts (preserves WebSocket state)
+ * - Content panel: Regular page content (overview, settings, etc.)
+ * - Visibility controlled via data attributes + CSS instead of conditional rendering
+ *
+ * Why this approach:
+ * - Leverages Next.js 16 Layout Persistence feature
+ * - Avoids component unmount/remount overhead
+ * - Maintains WebSocket connections and terminal state
+ * - Better performance than Parallel Routes (no redundant RSC fetches)
+ */
+
 'use client';
 
 import { usePathname } from 'next/navigation';
 
 import { TerminalContainer, type TerminalContainerProps } from '@/components/terminal/terminal-container';
 
+import styles from './project-content-wrapper.module.css';
+
+// ============================================================================
+// Types
+// ============================================================================
+
 interface ProjectContentWrapperProps extends TerminalContainerProps {
   children: React.ReactNode;
 }
 
+// ============================================================================
+// Component
+// ============================================================================
+
 export function ProjectContentWrapper({
   children,
   project,
   sandbox,
 }: ProjectContentWrapperProps) {
   const pathname = usePathname();
-  // Check if the current path ends with /terminal
-  const isTerminalPage = pathname?.endsWith('/terminal');
+
+  // Determine which panel to display based on current route
+  const isTerminalPage = pathname?.endsWith('/terminal') ?? false;
 
   return (
-    <>
-      <div 
-        className="w-full h-full"
-        style={{ display: isTerminalPage ? 'block' : 'none' }}
+    <div className={styles.wrapper}>
+      {/* Terminal Panel - Persisted across navigation */}
+      <div
+        data-visible={isTerminalPage}
+        className={`${styles.panel} ${styles.terminalPanel}`}
+        aria-hidden={!isTerminalPage}
+        aria-live={isTerminalPage ? 'polite' : undefined}
+        role="region"
+        aria-label="Terminal Console"
       >
-        <TerminalContainer 
-          project={project} 
-          sandbox={sandbox} 
+        <TerminalContainer
+          project={project}
+          sandbox={sandbox}
           isVisible={isTerminalPage}
         />
       </div>
-      <div 
-        className="w-full h-full flex flex-col overflow-hidden min-h-0"
-        style={{ display: !isTerminalPage ? 'flex' : 'none' }}
+
+      {/* Content Panel - Regular pages (overview, settings, env, etc.) */}
+      <div
+        data-visible={!isTerminalPage}
+        className={`${styles.panel} ${styles.contentPanel}`}
+        aria-hidden={isTerminalPage}
+        role="main"
       >
         {children}
       </div>
-    </>
+    </div>
   );
 }

components/terminal/terminal-container.tsx

@@ -36,6 +36,12 @@ type Sandbox = Prisma.SandboxGetPayload<object>;
 export interface TerminalContainerProps {
   project: Project;
   sandbox: Sandbox | undefined;
+  /**
+   * Controls whether the terminal is visible
+   * - Used to optimize performance by avoiding unnecessary fit() calls when hidden
+   * - Passed down to child components to coordinate visibility state
+   * - Default: true
+   */
   isVisible?: boolean;
 }
 
@@ -136,6 +142,12 @@ export function TerminalContainer({ project, sandbox, isVisible = true }: Termin
             }}
           >
             {/* Each tab maintains its own terminal instance */}
+            {/*
+              isVisible combines two conditions:
+              1. isVisible: Terminal page is visible (not hidden by routing)
+              2. tab.id === activeTabId: This specific tab is active
+              Only when both are true will the terminal fit() to correct dimensions
+            */}
             <TerminalDisplay
               key={tab.id}
               sandboxId={sandbox?.id ?? ''}

components/terminal/terminal-display.tsx

@@ -39,6 +39,13 @@ export interface TerminalDisplayProps {
   fileBrowserUrl?: string | null;
   fileBrowserUsername?: string;
   fileBrowserPassword?: string;
+  /**
+   * Indicates whether this terminal instance is currently visible to the user
+   * - Controls when to trigger terminal resize/fit operations
+   * - Prevents incorrect dimension calculations when container is hidden (display: none)
+   * - Passed down from TerminalContainer which combines route visibility and active tab state
+   * - Default: true
+   */
   isVisible?: boolean;
 }
 
@@ -110,6 +117,11 @@ export function TerminalDisplay({
 
         {/* Terminal Instance */}
         <div className="flex-1 w-full p-2">
+          {/*
+            Pass visibility state to XtermTerminal
+            - XtermTerminal will use this to decide when to call fit()
+            - Avoids fitting terminal when container dimensions are 0 (display: none)
+          */}
           <XtermTerminal
             key={`xterm-${tabId}`}
             wsUrl={ttydUrl}

components/terminal/terminal-toolbar.tsx

@@ -87,7 +87,7 @@ export function TerminalToolbar({
   ];
 
   // Only show endpoints that have a valid domain URL
-  const networkEndpoints = allEndpoints.filter(endpoint => endpoint.domain);
+  const networkEndpoints = allEndpoints.filter((endpoint) => endpoint.domain);
 
   const copyToClipboard = async (text: string, field: string) => {
     try {
@@ -223,9 +223,7 @@ export function TerminalToolbar({
                       <div className="flex-1 min-w-0">
                         <div className="text-[10px] text-gray-500 mb-0.5">Password</div>
                         <code className="text-xs text-blue-400 break-all">
-                          {showPassword
-                            ? fileBrowserCredentials.password
-                            : '••••••••••••••••'}
+                          {showPassword ? fileBrowserCredentials.password : '••••••••••••••••'}
                         </code>
                       </div>
                       <button