From ac9f7a9299c1da96e904909a2d51f6cf057b99be Mon Sep 17 00:00:00 2001 From: Developer Date: Sun, 14 Jun 2026 09:07:43 +0000 Subject: [PATCH] fix: prevent terminal container from overflowing page on desktop The desktop terminal page sometimes grew an outer scrollbar because the terminal instance/wrapper/container chain lacked height constraints. Without min/max-height enforcement, xterm.js's internal viewport could expand its parent flex/grid track past the available space. - Add overflow: hidden to .terminal-page. - Add max-height: 100% and overflow: hidden to .terminal-instance. - Add max-height: 100% to .terminal-wrapper. - Add min-height: 0 to .terminal-container. - Constrain .xterm-viewport to max-height/width 100% so it fills but never exceeds its container. Quality gates: npm run typecheck, npm run lint, npm test -- --run (87 passed). Refs: openspec/changes/fix-terminal-container-overflow --- .pi-map.index.md | 2 +- .pi-map.md | 4 +- apps/.pi-map.index.md | 2 +- apps/.pi-map.md | 4 +- apps/web/.pi-map.index.md | 2 +- apps/web/.pi-map.md | 4 +- apps/web/src/.pi-map.index.md | 2 +- apps/web/src/.pi-map.md | 4 +- apps/web/src/styles/.pi-map.index.md | 2 +- apps/web/src/styles/.pi-map.md | 8 ++-- apps/web/src/styles/utilities.css | 7 ++++ .../fix-terminal-container-overflow/change.md | 38 +++++++++++++++++++ .../fix-terminal-container-overflow/tasks.md | 13 +++++++ 13 files changed, 75 insertions(+), 17 deletions(-) create mode 100644 openspec/changes/fix-terminal-container-overflow/change.md create mode 100644 openspec/changes/fix-terminal-container-overflow/tasks.md diff --git a/.pi-map.index.md b/.pi-map.index.md index 874982b..c01c767 100644 --- a/.pi-map.index.md +++ b/.pi-map.index.md @@ -16,7 +16,7 @@ dir: . Trust boundary: index routes, map orients, source decides. ## role -Infrastructure and deployment configuration for a self-hosted project management platform with OAuth2 authentication, providing Docker Compose orchestration, environment templates, and development tooling. +Infrastructure and deployment configuration for a self-hosted project management platform with git repository management and OAuth2 authentication. ## parent - ## children diff --git a/.pi-map.md b/.pi-map.md index 67d5f81..d493958 100644 --- a/.pi-map.md +++ b/.pi-map.md @@ -18,7 +18,7 @@ index: ./.pi-map.index.md Trust boundary: index routes, map orients, source decides. ## role -Infrastructure and deployment configuration for a self-hosted project management platform with OAuth2 authentication, providing Docker Compose orchestration, environment templates, and development tooling. +Infrastructure and deployment configuration for a self-hosted project management platform with git repository management and OAuth2 authentication. ## files - .env.example | Provides a template of environment variables for configuring a Headquarter application with PostgreSQL, Redis, Authentik SSO, and Docker/Traefik deployment - .gitignore | Specifies files and directories for Git to ignore across a multi-language project with Python, Node, and custom tooling | dep: Git @@ -31,7 +31,7 @@ Infrastructure and deployment configuration for a self-hosted project management - progress.md | Tracks completed and remaining tasks for a backend-frontend code refactoring project organized in 7 phases - swap-pane | Empty file with no functionality ## arch -Containerized microservices architecture using Docker Compose with PostgreSQL and Redis data layers, Traefik reverse proxy for TLS/ingress, environment-based configuration management, and Makefile-driven development lifecycle. +Containerized microservices architecture using Docker Compose with PostgreSQL/Redis backend, Traefik reverse proxy for TLS termination, and environment-driven configuration management. ## tags docker, redis, git, application, postgresql, compose, traefik, project ## symbols diff --git a/apps/.pi-map.index.md b/apps/.pi-map.index.md index 6fc23cf..3f1ff04 100644 --- a/apps/.pi-map.index.md +++ b/apps/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps ## role -Container for independent, deployable application modules that compose the overall system. +Contains the deployable application entry points and executable configurations for the project. ## parent index: ./.pi-map.index.md map: ./.pi-map.md diff --git a/apps/.pi-map.md b/apps/.pi-map.md index 1c83227..9765054 100644 --- a/apps/.pi-map.md +++ b/apps/.pi-map.md @@ -4,10 +4,10 @@ dir: apps index: apps/.pi-map.index.md ## role -Container for independent, deployable application modules that compose the overall system. +Contains the deployable application entry points and executable configurations for the project. ## files ## arch -Monorepo-style multi-app structure where each sub-directory is a self-contained application sharing common infrastructure and dependencies. +Modular application structure with separate, self-contained app modules that compose shared libraries into runnable binaries. ## tags - ## symbols diff --git a/apps/web/.pi-map.index.md b/apps/web/.pi-map.index.md index 6e8f7f3..d7be654 100644 --- a/apps/web/.pi-map.index.md +++ b/apps/web/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/web ## role -Frontend web application providing the browser-based user interface for the "headquarter" project, built as a modern React SPA with code editing, terminal, and routing capabilities. +Frontend web application providing a browser-based UI with code editing, terminal, and routing capabilities for the "headquarter" project. ## parent index: apps/.pi-map.index.md map: apps/.pi-map.md diff --git a/apps/web/.pi-map.md b/apps/web/.pi-map.md index 967dcea..e236167 100644 --- a/apps/web/.pi-map.md +++ b/apps/web/.pi-map.md @@ -4,7 +4,7 @@ dir: apps/web index: apps/web/.pi-map.index.md ## role -Frontend web application providing the main user interface for the "headquarter" project as a React-based single-page application. +Frontend web application providing a browser-based UI with code editing, terminal, and routing capabilities for the "headquarter" project. ## files - .env.example | Template file defining example environment variables for frontend API and application URL configuration - .eslintrc.cjs | Configures ESLint for a TypeScript browser project with modern ECMAScript module support | dep: @typescript-eslint/parser, @typescript-eslint/eslint-plugin, eslint @@ -16,7 +16,7 @@ Frontend web application providing the main user interface for the "headquarter" - tsconfig.json | TypeScript configuration file for a React project using Vite with modern ES2020 target and bundler module resolution | dep: typescript, react, vite - vite.config.ts | Configures Vite build tool for a React project with custom dev server port and Vitest test settings. | dep: vite, @vitejs/plugin-react ## arch -Modern React SPA built with Vite, TypeScript, and nginx serving, featuring containerized deployment with multi-stage Docker builds, client-side routing, and optimized static asset delivery. +Modern React SPA built with Vite and TypeScript, containerized via multi-stage Docker with nginx serving, featuring client-side routing, optimized static asset delivery, and development tooling (ESLint, Vitest). ## tags react, eslint, vite, typescript, dom, application, nginx, web ## symbols diff --git a/apps/web/src/.pi-map.index.md b/apps/web/src/.pi-map.index.md index afaf27c..4ebffb3 100644 --- a/apps/web/src/.pi-map.index.md +++ b/apps/web/src/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/web/src ## role -Entry point and core infrastructure for a React web application handling routing, authentication, and type definitions. +Provides the core web application entry point, routing infrastructure, and shared domain type definitions for a React-based frontend. ## parent index: apps/web/.pi-map.index.md map: apps/web/.pi-map.md diff --git a/apps/web/src/.pi-map.md b/apps/web/src/.pi-map.md index 4e95e1e..4e991b8 100644 --- a/apps/web/src/.pi-map.md +++ b/apps/web/src/.pi-map.md @@ -4,13 +4,13 @@ dir: apps/web/src index: apps/web/src/.pi-map.index.md ## role -Entry point and core infrastructure for a React web application handling routing, authentication, and type definitions. +Provides the core web application entry point, routing infrastructure, and shared domain type definitions for a React-based frontend. ## files - main.tsx | Bootstraps a React application with routing, authentication, and session management providers. | dep: react, react-dom/client, react-router-dom, ./router, ./state/auth, ./state/sessions, ./styles/tokens.css, ./styles/global.css, ./styles/utilities.css, ./styles/syntax-highlight.css, ./styles/pages/git-history.css, ./styles/pages/projects.css, ./styles/pages/sessions.css, ./styles/pages/ssh-keys.css, ./styles/pages/workspace-detail.css, ./styles/pages/workspaces.css, react-dom - router.tsx | Defines the React Router configuration for a web application with protected routes, nested layouts, and redirects. | exp: AppRouter | dep: react-router-dom, ./components/app-shell, ./components/protected-route, ./pages/DashboardPage, ./pages/PlaceholderPage, ./pages/ProfilePage, ./pages/ProjectsPage, ./pages/GitRepositoriesPage, ./pages/GitHistoryPage, ./pages/ProjectSettingsPage, ./pages/SettingsPage, ./pages/TerminalPage, ./pages/ToolWorkshopPage, ./pages/SshKeysPage, ./pages/ConfigProfilesPage, ./pages/SessionsPage, ./pages/WorkspacesPage, ./pages/WorkspaceDetailPage - types.ts | Defines TypeScript type definitions for user sessions, projects, repositories, and workspaces in an application. | exp: SessionUser, SessionPayload, Project, WorkspaceSummary, RepositorySummary, ProjectWithRepos ## arch -Modular React SPA with React Router v6 (nested routes, protected routes, layout nesting), provider-based context pattern for auth/session management, and centralized TypeScript type definitions. +Modular React SPA with provider-based dependency injection, declarative routing with nested layouts and route guards, and centralized TypeScript type definitions. ## tags pages, styles, css, router, react, session, dom, project ## symbols diff --git a/apps/web/src/styles/.pi-map.index.md b/apps/web/src/styles/.pi-map.index.md index f5f0f53..ca7caf9 100644 --- a/apps/web/src/styles/.pi-map.index.md +++ b/apps/web/src/styles/.pi-map.index.md @@ -2,7 +2,7 @@ dir: apps/web/src/styles ## role -Provides the complete visual design system and styling infrastructure for the web application, including tokens, utilities, global layouts, and component-specific styles. +Provides the complete visual design system and styling foundation for the web application, including themes, tokens, utilities, and component-specific styles. ## parent index: apps/web/src/.pi-map.index.md map: apps/web/src/.pi-map.md diff --git a/apps/web/src/styles/.pi-map.md b/apps/web/src/styles/.pi-map.md index 9272ec4..ff77a07 100644 --- a/apps/web/src/styles/.pi-map.md +++ b/apps/web/src/styles/.pi-map.md @@ -4,16 +4,16 @@ dir: apps/web/src/styles index: apps/web/src/styles/.pi-map.index.md ## role -Provides the complete visual design system and styling infrastructure for the web application, including tokens, utilities, global layouts, and component-specific styles. +Provides the complete visual design system and styling foundation for the web application, including themes, tokens, utilities, and component-specific styles. ## files - global.css | Defines global CSS styles for a web application shell layout, navigation, cards, forms, dialogs, settings pages, and responsive design patterns. | dep: CSS custom properties (CSS variables: --border, --panel, --brand, --muted, --ink, --bg, --danger, --success, --warning, --font-size-xs, --font-size-sm, --space-2, --space-3, --space-4, --space-5) - syntax-highlight.css | Stylesheet for a syntax highlighting component with toolbar, line numbers, code display, and Prism.js theme integration | dep: Prism.js - tokens.css | Defines a comprehensive CSS design token system with light/dark themes, spacing scales, breakpoints, and fluid typography for a web application. -- utilities.css | Provides a comprehensive responsive CSS utility system with layout primitives, mobile-first adaptations, terminal-specific styling, and component patterns for a web application | dep: CSS custom properties (variables), xterm.js (terminal integration) +- utilities.css | Provides responsive CSS utility classes and component styles for a web application including layout, terminal, session navigation, and mobile-specific adaptations. | dep: CSS custom properties (--space-*, --border, --bg, --muted, --brand, --danger, --danger-light, --success, --text, --text-xs, --text-sm), xterm.js (terminal library) ## arch -CSS custom properties-based design token architecture with theme-aware variables (light/dark), mobile-first responsive utilities, and modular separation of concerns across tokens, utilities, global styles, and component-specific stylesheets. +Token-driven CSS architecture using CSS custom properties for light/dark theming, utility-first responsive patterns, and modular separation of concerns across global base styles, design tokens, syntax highlighting, and adaptive utilities. ## tags -space, global, css, web, application, syntax, defines, layout +space, global, css, web, application, danger, syntax, text ## symbols - ## workflows diff --git a/apps/web/src/styles/utilities.css b/apps/web/src/styles/utilities.css index 41f157c..223cbea 100644 --- a/apps/web/src/styles/utilities.css +++ b/apps/web/src/styles/utilities.css @@ -439,6 +439,7 @@ a.nav-item, min-height: 0; padding: var(--space-4); gap: var(--space-4); + overflow: hidden; } .terminal-page-header { @@ -457,6 +458,7 @@ a.nav-item, grid-template-rows: auto 1fr; flex: 1; min-height: 0; + max-height: 100%; border: 1px solid var(--border); border-radius: 10px; overflow: hidden; @@ -549,6 +551,7 @@ a.nav-item, position: relative; width: 100%; height: 100%; + min-height: 0; padding: 0; overflow: hidden; } @@ -557,6 +560,8 @@ a.nav-item, .terminal-container .xterm-viewport { touch-action: auto; overscroll-behavior: auto; + max-height: 100% !important; + width: 100% !important; } /* xterm.js manages its own positioning and sizing */ @@ -767,7 +772,9 @@ a.nav-item, .terminal-instance { flex: 1; min-height: 0; + max-height: 100%; display: none; + overflow: hidden; } .terminal-instance.active { diff --git a/openspec/changes/fix-terminal-container-overflow/change.md b/openspec/changes/fix-terminal-container-overflow/change.md new file mode 100644 index 0000000..1935e0b --- /dev/null +++ b/openspec/changes/fix-terminal-container-overflow/change.md @@ -0,0 +1,38 @@ +# Fix Terminal Container Overflow on Desktop + +## Summary + +On the desktop Terminal page, the terminal container sometimes grows taller than its allocated flex/grid track and acquires its own scrollbar, which in turn causes the outer page to scroll. This happens because the flex container chain from `.terminal-page` down to `.terminal-container` is missing `min-height: 0`, allowing a child with intrinsic content height to expand its parent. + +## Scope + +- `apps/web/src/styles/utilities.css` + - `.terminal-page` + - `.terminal-page-content` + - `.terminal-instance` + - `.terminal-wrapper` + - `.terminal-container` + - `.xterm-viewport` + +## Root Cause + +`.terminal-page-content` is a flex item that receives its height from the flex parent. In CSS flexbox, a flex item's `min-height` defaults to `auto`, which is based on its content. If the xterm.js viewport/canvas renders taller than the available track, the flex item expands to fit it, pushing the page beyond `100vh` and creating a page-level scrollbar. + +## Fix + +1. Add `min-height: 0` to every flex/grid item in the terminal layout chain so each level respects the constrained height from its parent. +2. Keep `overflow: hidden` on the wrapper/container so xterm.js's internal viewport is the only scroll surface. +3. Ensure `.terminal-container .xterm-viewport` fills the container and does not expand past it. + +## Acceptance Criteria + +- [x] Terminal page never shows an outer vertical scrollbar due to terminal content. +- [x] Terminal wrapper and container stay within their allocated track. +- [x] xterm.js internal viewport still scrolls normally. +- [x] Mobile terminal layout is unaffected. +- [x] Quality gates pass: `npm run typecheck`, `npm run lint`, `npm test -- --run`. + +## Related + +- `openspec/specs/tool-terminal` +- `openspec/changes/fix-tmux-mouse-config` diff --git a/openspec/changes/fix-terminal-container-overflow/tasks.md b/openspec/changes/fix-terminal-container-overflow/tasks.md new file mode 100644 index 0000000..23a5527 --- /dev/null +++ b/openspec/changes/fix-terminal-container-overflow/tasks.md @@ -0,0 +1,13 @@ +# Fix Terminal Container Overflow on Desktop — Tasks + +- [x] Discard debug `terminal.tsx` changes from `debug/mobile-terminal-scroll`. +- [x] Create focused branch `fix/terminal-container-overflow` from `dev`. +- [x] Update `utilities.css` to prevent terminal container from overflowing its flex/grid track: + - [x] `.terminal-page`: add `overflow: hidden`. + - [x] `.terminal-instance`: add `max-height: 100%` and `overflow: hidden`. + - [x] `.terminal-wrapper`: add `max-height: 100%`. + - [x] `.terminal-container`: add `min-height: 0`. + - [x] `.terminal-container .xterm-viewport`: add `max-height: 100% !important` and `width: 100% !important`. +- [x] Run `npm run typecheck` and `npm run lint` in `apps/web`. +- [x] Run `npm test -- --run` in `apps/web` (87 passed). +- [x] Update project maps for changed files.