ambient-aurora：实践指南

团队讨论ambient-aurora时，我会先把用途说清楚：以gemini 3.8 flash和gemini 3.1 pro配合Emilkowalski的Skills开发的苹果风网页端屏幕保护程式。这类网页与浏览器自动化工具真正难在登录状态、页面变化和失败恢复往往不稳定，仓库说明只能作为第一层证据。落地前可以选择一个权限清楚的网页流程做端到端短测，用会话保持、元素定位、错误恢复和工件留存判断它是否真的省事。我的判断是，它更适合需要可观测网页自动化流程的开发者；若眼下没有这类需求，先保留观察即可。

Ambient Aurora

繁体中文：一款汲取 Apple Fluid Interface 哲学与 Emil Kowalski 设计工程动效原则 的单档网页环境时钟与萤幕保护程式。结合原生 GLSL 片段着色器、次像素级抗色阶抖动（Dithering）、非对称长按退出机制与极致节能架构，实现零外部依赖、纯粹且低负载的沉浸美学。

English: An Apple-inspired ambient web screensaver and digital timepiece engineered with Emil Kowalski's interaction & motion principles. Powered by raw WebGL GLSL fragment shaders, sub-pixel dithering, asymmetric hold-to-confirm exit mechanics, and zero external dependencies.

体验线上展示 (Live Demo)

视觉模式 / Visual Modes

核心亮点 / Key Highlights

1. 图形渲染与光学防御 (Graphics & Optical Safeguards)

• 硬体级抗色阶杂讯 (Anti-Banding Dithering)：在 GLSL Fragment Shader 输出层注入高频微噪点，彻底消除 OLED 与大尺寸高动态萤幕上的色阶断层（Color Banding）。
• 零跳帧时间轴 (Anti-Jitter Phase Engine)：废弃易引发时间轴重置跳动的 CSS Keyframes，全面采用 requestAnimationFrame 搭配每帧时间差（$Delta t$）正规化速度，完美适配 ProMotion 120Hz 高刷萤幕。
• 无缝交叉淡化 (Blur-Masked Crossfade)：动效模式切换时套用 1500ms cubic-bezier(0.77, 0, 0.175, 1) 双向混合，并辅以动态高斯模糊掩饰重叠过渡。

2. 精准动态与互动哲学 (Emil Kowalski's Motion Principles)

• 非对称时序退出 (Asymmetric Hold-to-Confirm)：
  • 蓄力阶段 (Press)：长按空白键（桌面端）或长按萤幕（触控端）触发严格 2s linear 线性进度与画面推近动态。
  • 中断复原 (Release)：任意时刻松开，立即以 200ms cubic-bezier(0.23, 1, 0.32, 1) 敏捷回弹，杜绝「砖墙式」生硬中断。
• 物理级按压回馈 (Tactile Scale Feedback)：所有控制项与主题色盘在 :active 下触发 scale(0.97)，并透过微正向字距提升小字辨识度。
• 环境感知状态机 (Idle State Engine)：无操作 3 秒后平滑沉浸退场（UI 完全淡出、时钟降至 35% 亮度），唤醒时以 200ms 瞬间响应，并在闲置时自动解除焦点挟持。

3. 行动端原生标准 (Mobile-Native Engineering)

• 觸控設備防禦：
  • 全局配置 100dvh 與 overscroll-behavior: none，消除滾動穿透與橡皮筋回彈。
  • Hover 样式全面收拢于 @media (hover: hover) and (pointer: fine)，阻断行动端点击残留高光（Sticky Hover）。
  • 设定面板在小萤幕自动转换为紧凑型 Bottom Sheet，保证 min-height: 44px 触控热区同时不遮挡中央时钟。
• 无抖动排版 (Jitter Prevention)：时钟宣告 font-variant-numeric: tabular-nums，日期栏位以 calc() 等比连动字级，防止秒数跳动造成版面横向震颤。

4. 系统层节能调度 (System-Level Energy Efficiency)

• 萤幕防休眠 (Screen Wake Lock API)：待机时自动请求常亮，并在视窗可见性改变时无缝重新获取。
• 后台零消耗 (Page Visibility API)：分页切换至背景或最小化时，完全冻结 rAF 渲染回圈与时钟定时器，杜绝无谓电量消耗。

互动指南 / Controls

技术栈 / Tech Stack

• Graphics Core：Raw WebGL 1.0 (Custom GLSL Shaders, FBM, Domain Warping)
• Styling Architecture：Modern CSS3 (backdrop-filter, CSS Variables, 100dvh, Safe Area Insets)
• Runtime Logic：Vanilla JavaScript (ES6+), Zero Dependencies (零外部依赖、单档架构)
• Typography：System Font Stack (-apple-system, SF Pro Display, tabular-nums)

快速开始 / Getting Started

本專案為完全自包含的單檔架構，無需安裝 Node.js，亦無需任何打包工具。

本地运行 (Local Run)

1. Clone 储存库：

   git clone [https://github.com/Cool-Chi/ambient-aurora.git](https://github.com/Cool-Chi/ambient-aurora.git)
   cd ambient-aurora