City-Lifeline-Cockpit/dynamic-component-service-master/openspec/changes/add-dreamy-fluid-panel-component/design.md

Context

The reference page at https://github.com/pbakaus/radiant/blob/main/static/sequin-wave.html is a fullscreen WebGL demo. Its core effect comes from a fragment shader that does the following:

• builds a hex/sequin tiling
• samples a layered wave field
• tilts each virtual reflective disc according to that wave
• computes a tight specular response for flashes and sheen

That logic maps well to a plane material in three.js, but several parts of the demo do not belong in a reusable component:

• fullscreen canvas handling
• page label and page background styling
• pointer and touch event listeners
• extra cursor-driven specular lighting

Within this repository, the effect must be expressed as a canvas-side tresjs/three component. Shader files must live under src/shader/<component-name>/, and the component must be integrated through src/dcsConfig.ts without changing the generic preview pages.

Goals / Non-Goals

Goals:

• Provide a plane component with independently configurable length and width that sits flat on the ground by default.
• Keep the visual core of the reference effect: dense reflective cells, layered wave motion, and strong view-dependent flashes.
• Let developers tune the effect through a concise set of safe parameters.
• Keep all core rendering inside the three.js canvas pipeline.
• Keep the implementation self-contained and component-scoped.

Non-Goals:

• Do not reproduce fullscreen page presentation from the reference.
• Do not implement pointer, touch, click, or hover-driven light interaction.
• Do not turn the panel into a volumetric liquid body or a container-based component.
• Do not add generic preview infrastructure changes.
• Do not introduce per-cell real geometry; the panel should stay shader-based for stability and performance.

Decisions

1. Decision: Use a single PlaneGeometry with independently configurable length and width plus a custom shader material instead of instanced reflective discs.

   • Rationale: The reference effect is already fundamentally fragment-driven. A single plane keeps the component lightweight and appropriate for a ground panel.
   • Alternative considered: Instanced disc geometry for each sequin. This would increase geometry and update cost without meaningfully improving the intended medium-distance usage.

2. Decision: Correct the shader field by panel aspect ratio so reflective cells keep a stable shape when length and width diverge.

   • Rationale: Once the panel can become rectangular, UV-space sampling alone would visibly stretch the sequins and wave field. Passing panel length and width into the shader keeps the effect visually consistent.
   • Alternative considered: Leaving the pattern in normalized UV space. This would make the reflective cells look squashed or elongated on non-square panels.

3. Decision: Preserve the reference demo's hex tiling, layered wave sampling, tilt direction estimation, and specular layering in the fragment shader.

   • Rationale: Those are the parts that define the look and directly answer the user's request.
   • Alternative considered: Replacing the pattern with generic noise or texture scrolling. That would lose the recognizable reflective-cell character.

4. Decision: Remove the cursor-driven light source entirely.

   • Rationale: The user explicitly asked to remove the click/interaction effect, and page-level interaction does not belong in a reusable service component.
   • Alternative considered: Keeping an optional pointer highlight toggle. This would add complexity and contradict the requested first version.

5. Decision: Keep color tuning concise with three color controls: base tone, sheen tone, and highlight tone.

   • Rationale: This provides enough freedom to shift between cold and warm looks without exposing the entire internal lighting composition.
   • Alternative considered: Exposing every intermediate ramp color. That would overcomplicate the control panel.

6. Decision: Make the component ground-ready by rotating the internal plane into the XZ orientation and setting a near-ground default placement in the registry.

   • Rationale: This matches the intended use on floor-like surfaces while preserving a simple external object transform contract.
   • Alternative considered: Leaving the plane vertical and requiring external rotation every time. That would create avoidable setup friction.

Risks / Trade-offs

• Risk: The panel depends on view-dependent specular math, so it will feel more alive from angled cameras than from a perfectly top-down view.

  • Mitigation: Keep ambient sheen and wave modulation strong enough that the panel still reads well when viewed from higher angles.

• Risk: Very high density plus large sequin size can overfill cells and reduce readability.

  • Mitigation: Clamp tileDensity and sequinSize to safe ranges in both the component and registry config.

• Risk: A fully opaque backing plate may look too heavy in some scenes, while a fully transparent panel can lose the patterned floor identity.

  • Mitigation: Blend between dark backing gaps and bright sequins, and expose panel opacity as a top-level control.

Migration Plan

• Create the new change artifacts for the component.
• Add dreamyFluidPanelComponent.vue with a single plane mesh and custom shader material.
• Add component-scoped vertex and fragment shader files under src/shader/dreamyFluidPanelComponent/.
• Register the component in src/dcsConfig.ts with defaults, controls, description, preview path, and default ground-oriented object transform.
• Add a preview asset under public/preview/.
• Run npm run build to validate that the component integrates cleanly without touching preview infrastructure.

Open Questions

• None for the current scope.