Experimental Software ↗
README.md

Experimental Software Landing Page

This repo powers experimental.software. The White Room marketing homepage introduces the lab and its projects. The VS Code-style web workspace is available at /code, and the brand guide lives at /brand.

The site is intentionally a little meta: the file tree in /code is generated from this codebase. The earlier markdown pages remain in content/ and are still accessible through their original routes.

Architecture

App shell

The Next.js App Router entry points live in src/app.

  • src/app/page.tsx renders the Gallery homepage using src/components/marketing/GalleryHome.tsx
  • src/components/marketing/catalog.ts defines the project order, descriptions, imagery, categories, and new-release marker; all links render in the initial HTML
  • src/lib/brand-copy.ts keeps the company introduction, About copy, terminology, and metadata consistent with /brand#language
  • src/app/directions/ keeps the comparison studies, including the first marketing homepage at /directions/original; see homepage direction notes
  • src/app/code/page.tsx preserves the IDE experience and opens this repository README
  • src/app/[slug]/page.tsx renders content routes like /projects, /website, /about, and /contact
  • src/app/layout.tsx defines page metadata, favicons, and social cards
  • src/app/globals.css contains the VS Code-inspired visual system
  • src/app/brand/page.tsx renders the White Room brand guide at /brand; see the brand implementation notes for reusable styling and components

IDE UI

The IDE emulator is built from focused components in src/components/ide.

  • WorkspaceShell.tsx owns the top-level UI composition and client-side workspace session
  • ActivityBar.tsx switches between Explorer, Search, and Source Control panels
  • FileExplorer.tsx renders the generated project tree
  • TabBar.tsx handles tabs, preview tabs, pinning, closing, context menus, and drag reorder
  • EditorPane.tsx wraps the editor toolbar, markdown preview, and CodeMirror editor
  • SearchPanel.tsx, QuickOpen.tsx, and CommandPalette.tsx emulate common VS Code workflows
  • SourceControlPanel.tsx shows session markdown edits and generated git history

Workspace model

Workspace state lives in src/features/workspace.

  • types.ts defines the virtual file and folder model
  • workspace.ts contains the reducer for opening files, pinning tabs, editing content, and tab behavior
  • tree.ts builds the explorer tree from flat file data
  • contentRoutes.ts maps content markdown files to public routes

This layer is deliberately separate from the UI so tab and file behavior can be tested without rendering React components.

Editor

Code editing lives in src/features/editor.

The editor is powered by CodeMirror 6 and includes language loading, VS Code-like syntax colors, indentation guides, folding, scroll restoration, cursor position reporting, and per-file undo history.

Markdown preview rendering lives in src/features/preview and uses a unified remark/rehype pipeline with GitHub-flavored markdown and sanitization.

Content

Website copy lives in content/.

The mirrored text and code files are editable during a browser session, including the markdown files that power the public website content. Image files are preview-only because the app does not include image editing tools.

Edits are stored only in React state. Refreshing the page resets the session.

Generated repo mirror

The browser cannot read the repository filesystem at runtime, so the app generates a TypeScript mirror before development, tests, and builds.

  • scripts/generate-repo-mirror.ts reads tracked project files and git history
  • scripts/repoMirrorFilter.ts filters out unsafe or noisy files
  • generated/repoMirror.ts contains the file data shown in the Explorer
  • generated/gitHistory.ts contains git history for the Source Control panel

The generator keeps the site honest to the source while still avoiding secrets, dependency folders, build output, and other local noise. Generated brand downloads are excluded to keep binary archives out of the editor bundle; their source script is included.

Brand asset exports

Run pnpm prepare:brand-fonts then pnpm build:brand-assets to regenerate the downloadable kit in public/brand/downloads/. It includes outlined SVG/PNG lockups, avatars, sharing artwork, a repository-cover template, and design tokens. The source script uses fontkit and sharp at authoring time. Font binaries are never included in the kit. See docs/brand-fonts.md for font delivery and license notes.

Getting Started

Install dependencies:

pnpm install

Run the development server:

pnpm dev

Run tests:

pnpm test

Run lint:

pnpm lint

Configure PostHog analytics and session replay:

NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN=<ph_project_token>
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com

Add the same variables to the production hosting environment. Session replay must also be enabled for the PostHog project.

Build for production:

pnpm build

The dev, test, and build scripts all run pnpm generate:repo first so the in-browser file tree stays in sync with the codebase.