Visual Edits & Tooling

Overview

ProctorAI includes built-in instrumentation for Orchids, a visual editing and development environment. This integration allows developers and designers to interact with the frontend prototype visually while maintaining a direct link to the underlying React source code.

The tooling consists of a custom build-time loader that tags components and a configuration layer that enables secure communication with the Orchids cloud environment.

Visual Edit Configuration

To enable visual editing capabilities, the project is configured via next.config.ts. This configuration ensures that the local development server can securely interface with Orchids tooling.

Allowed Origins

The development server is configured to accept requests from the Orchids cloud domain. This is essential for the visual editor to inject updates or retrieve component metadata.

// next.config.ts
const nextConfig: NextConfig = {
  allowedDevOrigins: ["*.orchids.cloud"],
  // ... other config
};

Component Tagging Loader

The core of the visual editing experience is the component-tagger-loader. This is a custom Webpack/Turbopack loader that processes JSX and TSX files during the build process.

How it Works

The loader automatically instrumentates your React components by injecting metadata tags into the rendered DOM nodes. These tags allow the Orchids editor to:

Identify Components: Instantly map a rendered UI element back to its specific file and line number.
Enable Visual Edits: Facilitate live styling and layout changes that sync back to the source code.

Integration in Turbopack

In this prototype, the loader is hooked into the turbopack rules within next.config.ts:

import path from "node:path";

const LOADER = path.resolve(__dirname, 'src/visual-edits/component-tagger-loader.js');

const nextConfig: NextConfig = {
  turbopack: {
    rules: {
      "*.{jsx,tsx}": {
        loaders: [LOADER]
      }
    }
  }
};

Error Reporting & Instrumentation

The ErrorReporter component serves as a global instrumentation layer. While it handles standard React error boundaries, it is also designed to provide feedback to the visual editing tools when the application enters an unstable state during live editing.

Usage

The ErrorReporter is automatically included in the application layout to capture:

Global runtime errors.
Digest IDs for server-side errors.
Recovery triggers via the reset callback.

import ErrorReporter from "@/components/ErrorReporter";

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  return (
    <html>
      <body>
        <ErrorReporter error={error} reset={reset} />
      </body>
    </html>
  );
}

Development Workflow

When the project is running in a supported environment (like orchids.cloud), the following features become active:

Inspect-to-Code: Click any element in the UI (e.g., a student card in the Dashboard or a button in the Exam flow) to open the corresponding source file in the editor.
Live Style Overrides: Use the Orchids visual interface to modify Tailwind CSS v4 classes or CSS variables in globals.css, with changes reflecting instantly in the browser.
Real-time Analytics Simulation: The visual tooling can interact with the simulated data in src/lib/mockData.ts to test how different risk scores or violation trends appear in the UI without manual state manipulation.