City-Lifeline-Cockpit/dynamic-component-service-master/openspec/changes/add-vertigo-halo-component/design.md

Context

The reference page vertigo.html is a fullscreen WebGL effect that renders a tunnel illusion entirely in the fragment shader. Its recognizable look comes from:

• converting centered UVs into polar coordinates
• building ring bands that scroll by depth
• slicing those rings with angular segment lines
• modulating ring brightness with multiple wave layers
• adding sparse flash spikes and neon edge highlights
• mixing a dark purple / crimson base with amber and red accents

For this repository, the right translation is a component-scoped shader on a single square PlaneGeometry. The component should preserve the motion language and palette feel of the reference while removing DOM shell concerns, fullscreen sizing, and pointer-drag rotation behavior.

Goals / Non-Goals

Goals:

• Add a new independent component instead of editing existing panel components.
• Render the effect on a square plane that sits flat on the ground by default.
• Preserve the reference page's polar tunnel illusion, segmented rings, wave pulses, and flashing highlights.
• Keep the effect autonomous with no click, hover, touch, or drag behavior.
• Expose a concise set of safe controls through src/dcsConfig.ts.

Non-Goals:

• Do not reproduce the fullscreen canvas shell, page label, or document styling from the reference page.
• Do not modify src/views/previewEntry.vue or src/views/templateComponet.vue.
• Do not replace dreamyFluidPanelComponent or any existing panel component.
• Do not introduce extra mesh layers or geometry-heavy ring instancing.
• Do not port unused or page-specific interaction parameters from the reference file.

Decisions

1. Decision: Implement the effect as one square PlaneGeometry with a custom shader material.

   • Rationale: The source effect is fundamentally fragment-driven, and a single plane keeps the port lightweight and aligned with repository conventions.
   • Alternative considered: Building the tunnel from repeated ring meshes or instanced geometry. This was rejected because it adds complexity and does not improve the intended floor-surface use case.

2. Decision: Use square dimensions controlled by a single size prop.

   • Rationale: The user explicitly requested a square plane, so a single size control is clearer than separate length and width values.
   • Alternative considered: Keeping independent width and length controls. This was rejected because it weakens the requested square-plane contract.

3. Decision: Preserve the reference structure by reusing polar mapping, depth scrolling, ring segmentation, layered pulse waves, flash spikes, vignette, haze, and grain in adapted form.

   • Rationale: Those elements are what make the reference visually identifiable as vertigo.html.
   • Alternative considered: Replacing the shader with generic radial noise and bloom. This would lose the reference identity.

4. Decision: Remove pointer drag and keep the rotation drift autonomous.

   • Rationale: A reusable service component should animate on its own and ignore preview pointer events unless interactivity is explicitly required.
   • Alternative considered: Preserving a user-driven rotation offset. This was rejected because it depends on page-level event wiring and contradicts the requested migration style.

5. Decision: Expose a compact control set centered on motion, density, glow, and palette.

   • Rationale: size, tunnelSpeed, rotationSpeed, ringFrequency, segmentCount, pulseIntensity, flashIntensity, edgeGlow, opacity, and four palette colors are enough to reshape the effect without overloading the config panel.
   • Alternative considered: Exposing every internal threshold and timing constant from the source shader. This was rejected because it would create a noisy, harder-to-use control surface.

Risks / Trade-offs

• Risk: Because the source is a fullscreen shader, mapping it onto a finite square plane can make the edges feel more abrupt.

  • Mitigation: Add a soft square edge mask and keep haze / vignette active so the pattern sits naturally inside the plane.

• Risk: High ring density combined with high flash intensity can produce over-bright or noisy visuals.

  • Mitigation: Clamp all exposed numeric props to conservative ranges in both the component and the registry config.

• Risk: The tunnel illusion can look flatter from a perfectly top-down view than from an angled camera.

  • Mitigation: Preserve strong pulse contrast, edge highlights, and atmospheric darkening so the plane still reads clearly from typical scene cameras.

Migration Plan

• Create the OpenSpec change artifacts for the new component.
• Add src/components/vertigoHaloComponent.vue with safe prop clamping, uniform syncing, and time updates.
• Add src/shader/vertigoHaloComponent/panel.vert and panel.frag.
• Register the component in src/dcsConfig.ts with defaults, config controls, and default object transform.
• Add a preview asset under public/preview/.
• Run npm run build and update tasks.md with completion status.

Open Questions

• None for the current scope.