ui

Imported from Victozee26/acode-opencode (src/ui/AGENTS.md). Install upstream with npx skills add Victozee26/acode-opencode --skill ui. Copyright stays with the author.

src/ui

Purpose

DOM rendering layer. Pure functions that build DOM subtrees — no side effects, no state mutation, no network calls.

Ownership

Owned by the root AGENTS.md. Three subdirectories:

• index.ts — render(state, context, actions) orchestrator dispatching to one render function per AppState; initUiStyles(baseUrl) loads CSS via <link> elements; initUiPage($page) sets up persistent header and content containers and idempotently init orientation listeners + apply visibility; updateHeader(state, actions) updates header in-place on every render; updateIframeScale(scale) live-updates the active iframe's CSS transform; isLandscape() helper, applyHeaderVisibility() (reads getHideHeaderInLandscape() + isLandscape() and toggles body class HEADER_LANDSCAPE_HIDDEN_CLASS), initOrientationListener() / destroyOrientationListener() idempotent lifecycle for matchMedia(LANDSCAPE_MEDIA_QUERY) + resize/orientationchange listeners

• components/ — one file per DOM factory function, re-exported through components/index.ts (barrel)

• styles/ — one CSS file per component/domain, loaded via <link> in initUiStyles()

  Components: 9 files (8 + barrel index.ts)

  • container.ts — createContainer (shared root wrapper used by spinner and errorDisplay)
  • spinner.ts — createSpinner, SpinnerElement type
  • iframe.ts — createIframe, setIframeScale
  • headerBar.ts — createHeaderBar (legacy — unused)
  • customHeader.ts — createCustomHeader (replaces FAB, hamburger menu with Start/Restart/Stop)
  • floatingActionButton.ts — createFloatingActionButton plus the FabAction interface (legacy — unused)
  • errorDisplay.ts — createErrorDisplay

  Styles:

  • base.css — keyframes (fade-in), .opencode-fade-in, .opencode-btn utility class
  • container.css — .opencode-container shared flex wrapper
  • idle.css — .opencode-idle, .opencode-idle-icon, .opencode-idle-text
  • ready.css — .opencode-ready-wrapper
  • headerBar.css — .opencode-header, .opencode-header-left, .opencode-header-wordmark, .opencode-header-hamburger, .opencode-header-menu, .opencode-header-scrim, .opencode-fab-item, .opencode-header-update, .opencode-header-update--installing, .opencode-header-update--error, .opencode-header-update--updated, .opencode-header-update-close, @media (orientation: landscape) { body.opencode-hide-header-in-landscape #opencode-header/.opencode-header { display: none } } gated landscape hide, @keyframes opencode-update-pulse
  • spinner.css — .opencode-spinner-ring (conic arc), .opencode-spinner-label, .opencode-spinner-progress (monospace command output line)
  • errorDisplay.css — .opencode-error-icon, .opencode-error-heading, .opencode-error-log, .opencode-error-retry
  • iframe.css — .opencode-iframe
  • floatingActionButton.css — legacy, not loaded

  Consumers (e.g. main.ts, ui/index.ts) import from ./ui/components (resolves to the barrel), never from an individual component file. Tests live in test/ui/components.test.ts.

Local Contracts

• initUiPage($page) is called once during AcodePlugin.init() to set up persistent DOM: it clears $page.body, sets it to a flex column, then appends two containers — #opencode-header (stored in pageHeader) and #opencode-content (stored in pageContent). These containers persist across all subsequent renders. It idempotently calls initOrientationListener() then synchronously applyHeaderVisibility() before any fade-in, so first paint has correct chrome.
• render(state, context, actions) no longer takes $page. On first call, it creates the custom header inside pageHeader; on subsequent calls it only swaps the content area (pageContent.innerHTML). Same-state transitions short-circuit — only updateHeader() runs, no content swap. actions is RenderActions with start, restart, stop, back, optional updateInfo, optional updateStatus, optional onUpdateClick, optional onCancelUpdate, and optional onReinstall fields. Every entry and same-state path calls applyHeaderVisibility() (via updateHeader and directly) so chrome stays in sync across state changes.
• updateHeader(state, actions) (exported) updates the header in-place: shows/hides the Start Server menu item, and creates/replaces/removes the update banner. It calls buildUpdateBanner(actions) to get the banner config and uses createUpdateBannerElement() to build the DOM. actions is HeaderActions (defined in src/types.ts), a structural subset of RenderActions with updateInfo, updateStatus, onUpdateClick, onCancelUpdate, and onReinstall. main.ts calls updateHeader() directly for header-only visual changes (e.g. update banner status), bypassing the state machine entirely. It always calls applyHeaderVisibility() first (even when pageHeader is null) so body class stays correct.
• Header landscape visibility is global chrome (all AppState values, not just Ready): when getHideHeaderInLandscape() (from ../settings) is true and isLandscape() is true, document.body gets class HEADER_LANDSCAPE_HIDDEN_CLASS (opencode-hide-header-in-landscape); otherwise the class is removed. Gated CSS in headerBar.css @media (orientation: landscape) { body.opencode-hide-header-in-landscape #opencode-header { display: none } body.opencode-hide-header-in-landscape .opencode-header { display: none } } collapses the flex header so #opencode-content flexes to full height. DOM is not removed, display:none is instant with no transition, and static layout stays via className / external CSS (no <style> injection).
• isLandscape(): boolean returns window.matchMedia(LANDSCAPE_MEDIA_QUERY).matches || window.innerWidth > window.innerHeight (matchMedia with size fallback for WebView quirks, try/catch guarded). applyHeaderVisibility(): void reads getHideHeaderInLandscape() + isLandscape() and toggles document.body.classList add/remove HEADER_LANDSCAPE_HIDDEN_CLASS. Both are exported for testing/wiring (main.ts wires setOnHideHeaderChange(() => applyHeaderVisibility()) for live toggle without restart).
• initOrientationListener(): void idempotently registers orientation change listeners: MediaQueryList change via addEventListener('change') with addListener fallback (stored orientationMql + orientationHandler refs), plus window resize and orientationchange. Calls applyHeaderVisibility() synchronously on init. destroyOrientationListener(): void is idempotent cleanup: removes all registered listeners via stored refs, clears orientationMql/orientationHandler/orientationInitialized, and removes HEADER_LANDSCAPE_HIDDEN_CLASS from body. main.ts destroy() calls it; AcodePlugin.init() wiring via setOnHideHeaderChange is single-assignment so re-init does not duplicate.
• The custom header (via createCustomHeader) is created once and persists across state transitions. It includes a wordmark image (asset/opencode-wordmark-dark.png) and a hamburger button on the right. Clicking the hamburger opens a dropdown menu with Start/Restart/Stop/Reinstall OpenCode Server actions, with a scrim backdrop to close on outside tap. The "Start Server" item is hidden when the server is already Ready. An optional update banner (.opencode-header-update) is prepended to the menu, built from actions via buildUpdateBanner(). The createCustomHeader function accepts baseUrl to resolve the wordmark asset path.
• Every state variant has its own render function. Never add inline DOM construction in render().
• All DOM is vanilla document.createElement — no framework, no html-tag-js.
• All static CSS is in external .css files under styles/, loaded once by initUiStyles(baseUrl) via <link> elements (called from AcodePlugin.init()). Dynamic styles (position, opacity toggles, transform, config-dependent values) remain as inline element.style.* assignments.
• Components use className or classList instead of cssText for static layout. Never add static CSS as inline styles.
• createIframe(src, scale?) accepts a string URL and optional numeric scale factor (1 = 100%); renderReady passes BASE_URL from ../config/server and getIframeScale() from ../settings.
• setIframeScale(iframe, scale) applies the same CSS-scaling logic as createIframe to an existing iframe element — updates width, height, transform, and transformOrigin inline styles.
• updateIframeScale(scale) is an impure export from index.ts that calls setIframeScale on a module-level activeIframe reference, stored and cleared by render() / renderReady(). Use this for live scale updates without destroying the iframe (e.g. on settings change). No-op when not in Ready state (activeIframe is null).
• The content container (not $page.body) uses overflow: hidden in Ready state. The iframe is CSS-scaled (layout box 100/scale%, then transform: scale()), which overflows the wrapper box; clipping prevents the parent body from becoming scrollable. The embedded web UI scrolls internally. Do NOT remove this clipping.
• Styles use CSS custom properties (var(--primary-color, fallback)) for Acode theming compatibility.
• Global keyframe/utility styles are in styles/base.css, loaded via <link> by initUiStyles(). Provides .opencode-fade-in (state transition), .opencode-btn (hover/active button effects).
• State transitions fade in: the content container gets .opencode-fade-in after every render, triggered with a forced reflow for reliable animation restart.
• createSpinner() uses requestAnimationFrame (not setInterval) for GPU-friendly rotation. The spinner is a conic-gradient arc ring cut with a CSS mask. Returns a SpinnerElement with a stop() method (cancels animation frame) and a setProgressText(text) method (shows/hides a monospace progress line below the status label for real-time command output).
• setSpinnerProgress(text) (exported from index.ts) streams text to the active spinner's progress label — used by main.ts to display live installation output. No-op when no spinner is rendered.
• createCustomHeader(actions, isReady, baseUrl, onBack?, updateBanner?) builds a flex header bar with an optional back button, wordmark image, and hamburger toggle. The hamburger opens a dropdown of FabAction[], preceded by an optional .opencode-header-update banner. The UpdateBannerConfig carries a label, status ('installing' | 'error' | 'updated' | null), onClick, and optional onCancel callbacks. When status === 'installing' — pulsing amber banner with a × close button (.opencode-header-update-close) that calls onCancel to revert to the pre-update state; the main label is non-clickable. When status === 'updated' — green banner, non-interactive <div> (not a button), shows "Updated to X.X". When status === 'error' — red text, clickable to retry. When status === null — amber text, clickable to start the update. A scrim overlay (dimmed + blurred) appears behind the menu to catch outside taps and close it. The scrim is a child of the header with z-index: -1 so it paints behind the header but above page content. The menu is positioned below the header (top: 100%, right-aligned). The Start Server action is hidden when isReady is true. No document-level event listeners are used; the scrim click handler closes the menu directly. Each FabAction item gets a data-action-id attribute matching its id so updateHeader() can query by action id (e.g. [data-action-id="start"]).
• createHeaderBar() and createFloatingActionButton() are legacy components kept for reference but no longer used. The FAB's functionality (Start/Restart/Stop actions) is now served by the hamburger menu in createCustomHeader(). The custom header is created once inside pageHeader and persists across state transitions; updateHeader() modifies it in-place.
• createErrorDisplay() unconditionally renders a warning icon, the diagnostics <pre> and a retry button. The diagnostics block always exists: it holds context.error.logTail (when present) followed by the node/npm version lines, which start as pending placeholders (see setErrorVersions). All dynamic strings use textContent (safe from injection, no escapeHtml needed).
• The diagnostics <pre> uses class opencode-error-log; its text is built by formatDiagnostics(logTail, versions) from src/error.ts. The Copy button reads pre.textContent at click time so the copied text carries the probed versions once they have filled in.
• setErrorVersions(versions) (impure export from index.ts, alongside setSpinnerProgress) fills the mounted error diagnostics block with the probed node/npm versions. It keeps a module-level activeErrorLog ref (plus activeErrorLogTail), both cleared when the content area is swapped, and no-ops when no error view is mounted — so a probe finishing after recovery cannot touch a stale element. main.ts calls it once getRuntimeVersions() answers.
• The error heading <h3> uses class opencode-error-heading (white-space: pre-wrap from CSS) for legible multi-line summaries. message is a short summary (first line of the error); logTail is the diagnostic detail (remaining lines).
• Event handlers (onRestart, onRetry) are attached via addEventListener, never inline onclick attributes.

Work Guidance

• New UI states: add a case to the switch in render() and a corresponding render function.
• New reusable components: each lives in its own file under components/ and is re-exported from components/index.ts. Keep the file scoped to a single component.
• Keep components pure — no side effects, no state access beyond props.

Verification

npm test runs Vitest with jsdom. Test files: test/ui/components.test.ts and test/ui/headerLandscape.test.ts. components.test.ts covers createErrorDisplay retry button and diagnostics rendering (log tail + pending node/npm version lines), the Copy button writing message + diagnostics (pending and probe-filled versions), setErrorVersions in-place fill and no-op when unmounted, initUiPage container creation, render persistent container behavior (header persists across transitions, content swaps), updateHeader in-place updates (Start Server visibility, same-state short-circuit). headerLandscape.test.ts covers landscape header visibility: headerBar.css @media (orientation: landscape) gated rule, isLandscape() fallback (matchMedia + innerWidth/innerHeight), applyHeaderVisibility() toggling body class by getHideHeaderInLandscape()+landscape, initOrientationListener()/destroyOrientationListener() idempotent lifecycle (matchMedia change via addEventListener/addListener fallback + resize/orientationchange), live toggle via setOnHideHeaderChange → applyHeaderVisibility(), and initUiPage/render/updateHeader integration (header hidden in all AppState when landscape+ON). Stubs window.matchMedia (with trigger), window.innerWidth/innerHeight, and acode.require('settings').

Child DOX Index

None. This directory is a leaf in the DOX hierarchy.