docs: add full JSDoc to createDemoLayout

[Copilot]

createDemoLayout — called by every demo scene — had only a bare one-liner JSDoc with no @param or @returns documentation, leaving its signature opaque for contributors.

Changes

• src/demoLayout.ts — expanded the JSDoc block to document both parameters and the DemoLayout return value:

/**
 * Build the shared DOM structure used by demo scenes.
 *
 * Clears `document.body`, injects a top bar with a back link and title,
 * a canvas container, and a performance panel with a live FPS counter.
 *
 * @param title    Text displayed in the top bar heading.
 * @param controls Optional list of control hint strings rendered below the
 *                 FPS counter in the performance panel.
 * @returns        References to the key DOM nodes created by this function.
 */
export function createDemoLayout(title: string, controls: string[] = []): DemoLayout { … }

• tests/demo-layout.test.ts — added an assertion that @param title, @param controls, and @returns are present in the source, consistent with the existing JSDoc-contract test pattern used across the repo.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[PATCH] createDemoLayout exported function is missing a JSDoc comment</issue_title>
<issue_description>Category: documentation
Severity: patch
File(s): src/demoLayout.ts (l.11)

Description

createDemoLayout is a public, exported function that builds the shared DOM structure used by every demo scene. It has no JSDoc comment: its parameters (title, controls) are undocumented, and the shape of the returned DemoLayout object is not described at the call site. Every demo file calls it, so missing documentation affects onboarding for all demo contributors.

Problematic code example

export function createDemoLayout(title: string, controls: string[] = []): DemoLayout {
  // … 40+ lines of DOM construction …
}

Suggested fix

Add a JSDoc block documenting the parameters and return value.

/**
 * Build the shared DOM structure used by demo scenes.
 *
 * Clears `document.body`, injects a top bar with a back link and title,
 * a canvas container, and a performance panel with a live FPS counter.
 *
 * @param title    Text displayed in the top bar heading.
 * @param controls Optional list of control hint strings rendered below the
 *                 FPS counter in the performance panel.
 * @returns        References to the key DOM nodes created by this function.
 */
export function createDemoLayout(title: string, controls: string[] = []): DemoLayout { /* … */ }

Acceptance criteria

• createDemoLayout has a JSDoc block with @param tags for title and controls
• The @returns tag describes the DemoLayout shape</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [PATCH] createDemoLayout exported function is missing a JSDoc comment #380

---

📱 Kick off Copilot coding agent tasks wherever you are with GitHub Mobile, available on iOS and Android.

[Copilot]

Pull request overview

Improves contributor-facing documentation for the shared demo DOM helper createDemoLayout (used by all demo scenes) and adds a test to enforce presence of key JSDoc tags, consistent with the repo’s “JSDoc-contract via source assertions” approach.

Changes:

• Expanded createDemoLayout JSDoc to document parameters and return value.
• Added a Vitest assertion ensuring @param title, @param controls, and @returns exist in src/demoLayout.ts.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
src/demoLayout.ts	Adds full JSDoc block describing behavior, params, and return value for createDemoLayout.
tests/demo-layout.test.ts	Adds a contract-style test asserting JSDoc tags are present in the layout source.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.