API Playground View

Relevant source files

The following files were used as context for generating this wiki page:

• dashboard/views/playground/index.ts
• README_EN.md
• dashboard/views/shell/index.ts
• scripts/capture/readme-screenshots.ts
• dashboard/AGENTS.md

The API Playground View provides a real-time testing environment for the Freebuff Proxy. It enables you to perform streaming and non-streaming chat completion requests through the /v1/chat/completions endpoint. This view serves as a functional demonstration and debugging tool to ensure that account pools, sessions, and upstream connections function correctly.

Sources: README_EN.md:43-47, dashboard/views/playground/index.ts

Architecture and Integration

The Playground is a dedicated module within the frontend dashboard. The application shell manages its lifecycle using a hash-based routing system. When a user selects the Playground, the shell invokes renderPlayground to mount the interface into the main view container.

Component Structure

• Navigation Management: The renderNav function in the shell includes a link to the playground route. Sources: dashboard/views/shell/index.ts:246-248
• View Lifecycle: The shell uses a viewCache to retain the DOM state of the Playground. This prevents the loss of input values and prevents redundant API calls when switching between different dashboard tabs. Sources: dashboard/views/shell/index.ts:77-83
• Mocking and Testing: Automated scripts utilize headless Chromium to interact with the Playground, simulating model selection and message dispatching to generate documentation screenshots. Sources: scripts/capture/readme-screenshots.ts:133-145

Data Flow for Request Execution

The following sequence diagram illustrates how the Playground executes a chat completion request:

Key Functions and Features

The Playground View focuses on providing an OpenAI-compatible interface for Freebuff models.

Interface Capabilities

Feature	Description
Model Selection	Allows users to pick from models returned by GET /v1/models.
Streaming Output	Displays round-trip responses in real-time using Server-Sent Events (SSE).
Input Area	Provides a textarea for entering user messages (e.g., "Hello, introduce yourself").
Status Feedback	Shows session admission and quota scheduling results.

Sources: README_EN.md:46-55, scripts/capture/readme-screenshots.ts:134-142

Automated Interaction Logic

For testing purposes, the readme-screenshots.ts script performs specific actions to validate the Playground:

1. It locates the textarea and select elements.
2. It sets the value property using the window.HTMLTextAreaElement.prototype setter to bypass standard event restrictions.
3. It dispatches input and change events to trigger the underlying state updates.
4. It identifies the "Send" button by its text content and triggers a click event.

Sources: scripts/capture/readme-screenshots.ts:135-150

Implementation Constraints

The Playground adheres to the dashboard's "No Build Chain" rule. It is written in TypeScript but delivered to the browser as plain JavaScript after stripping types via stripTypeScriptTypes.

• Module Referencing: All imports in the Playground must use full relative paths including the .ts extension. Sources: dashboard/AGENTS.md:5-9
• Standard DOM: The view avoids frameworks like React or Vue, instead constructing the UI using direct DOM manipulation via lib/dom.ts. Sources: dashboard/AGENTS.md:10-12
• Caching Behavior: The shell ensures that if the Playground has already been rendered, it is simply unhidden rather than reconstructed, preserving the current state of the test conversation. Sources: dashboard/views/shell/index.ts:98-105

Conclusion

The API Playground View is the primary diagnostic interface for users to verify their Freebuff Proxy configuration. By providing a direct path to the chat completion endpoint, it confirms that the multi-account pool and session management systems are operating as expected before integrating with external downstream agents.