## 1. Project Overview & Quickstart (chenglou/PLATFORM_BUGS)

# PLATFORM_BUGS

Open-source repository chenglou/PLATFORM_BUGS

### Repository Details
- **Repository:** [chenglou/PLATFORM_BUGS](https://github.com/chenglou/PLATFORM_BUGS)
- **Primary Language:** Code

*Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.*

## 2. Official Technical Reference & Guides (chenglou/chenglou.github.io)

## File: README.md

My [Midjourney AI art gallery](https://chenglou.me), made to show shiny UI/UX details. As seen in the [tweet](https://twitter.com/_chenglou/status/1599071638250606592).

[](https://youtu.be/OwzPOJnj2Vw)

## Features
- **Non-disruptive, interruptible transitions**. Animations don't block your ability to interact with the UI.
- **Optionally reduced motion for accessibility**.
- **[Layout-aware decoupled hit areas](https://youtu.be/MBSdQqZkXyc)**. In the gallery's line mode, the left & right cursor hit areas vertically extend to the window's edges, so that horizontally thin images don't have smaller hit areas than others. Hit areas also don't move with their image during transition, so you don't have to snipe click images. Consequently, rapidly clicking the left or right image doesn't accidentally dismiss the gallery (caused by clicking on a gap between image, or re-clicking on the newly centering image itself while it's still moving).
- **[Window resize transition](https://youtu.be/mfePLQ7OAEY)**. Just enough to convey what moved where.
- **[Anchor during resize](https://youtu.be/F2nawwZxy0g)**. No layout shift! Resize without losing what you're looking at.
- **[Area-based responsive image size](https://youtu.be/WkMRftTD4SA)**. Naive responsive layout uses the width of an item, but an image's visual impact is determined by its area. For the same width, square images visually appear bigger, while long images end up too thin. So we punish the formers by shrinking them, and grow the latters, to end up with more visually equal image sizes. Nice tangential article [here](https://www.dreamerux.com/articles/n2zhrp9ikfx2boypip3r2r9mhfy0um).
- **[Non-throttled cursor updates](https://youtu.be/ANgSxs0Y0Ys)**. The cursor state, when specified on the UI elements themselves (e.g. `cursor: 'zoom-in'`), doesn't update immediately during smooth scrolling. Hover effects also don't trigger til scrolling ends.
- **[Edge rubberbanding on the first & last item](https://youtu.be/K1BZcfgYGuY)**.
- **[Dynamic depth management](https://youtu.be/VKEdfOcjO1s)**. Proper z-index adjustments when images overlap. The center image in line view needs to be in front.
- **[Framerate-decoupled animation](https://www.kirupa.com/animations/fixing_frame_rate_for_consistent_animations.htm)**. Transitions run well and on time even when framerate is uneven, or when frames are completely dropped on lower-end devices.
- **[Spring physics](https://youtu.be/lmV07ZoruGA)** (exaggerated in the link for effect). Subtle playful bounces.
- **[Continous hover effect](https://youtu.be/AKmc_7groFY)**. The cursor attracts images magnetically, as opposed to a typical discrete, one-off upward lift transition trigger.
- **[Seamless repositioning on image dismissal](https://youtu.be/jyuYlebNNCg)**. In line view, navigating to a image and dismissing it transports you to the location of that image even if it's way further down the grid.
- **[Pretty selections](https://user-images.githubusercontent.com/1909539/205440816-ff666880-1acb-4ece-b548-51ad8b3af434.png)**. Select-all doesn't ruin the page's look.
- **[Routing](https://youtu.be/Sjpt65KFftg)**.
- **Occlusion culling**. Only render what's in view (sometime called virtualization). This puts a nice hard upper bound on the amount of DOM manipulations.
- **Keyboard inputs & multiple inputs coordination**. Concurrent keys and cursor events are resolved without pretending they're independent events.
- **Progressive image loading**. Though this could be done better.
- **Smoothness & performance**. Works on 120fps displays, including ProMotion.
- **Battery-friendly**. Fewer DOM nodes & no excessive tangential computations. You'll never get the Safari tab energy consumption warning.
- **Blur & brightness effects**. These help focusing on the middle image in the line view.
- **SEO-friendly**.
- Cool images =)

For developers:
- **Short, dependency-free code with no hidden control flow**.
- **Fun debug mode with manual frame stepping**.
- **Guaranteed minimum render count**. Renders are batched per frame. Also no multi-frames cascading rerenders from wrongly ordered state changes.
- **Minimal DOM nodes**. A clean, wrapper-divs-free inspector experience.

## UI Architecture

It's essentially a simplified game engine loop:

```
Initialization (done once, all upfront):
  State declaration
  Static DOM chunks
  Events registration (leverage event delegation to make this happen)

Render:
  DOM reads (batched, to avoid DOM read/write interleaving's catastrophic perf degradation)
  State changes, in this order:
    Handle inputs
    New layout & cursor
    Animation tick
    Commit state changes
  Occlusion & DOM writes (batched, same reason)
  schedule next render (e.g. if animating)
```
Only events and render's final step can schedule a next render

## Development

TypeScript + modules, bundled by Bun. No runtime dependencies.

- `bun install` — once, in a fresh checkout
- `bun start` — dev server (Bun transpiles `index.ts` on the fly, no build step)
- `bun run check` — `tsgo` typecheck + oxlint
- `bun run build` — bundle into `dist/` (emits `index.html` + a hashed JS file)

`index.ts` is the logic, `data.ts` is the photo list, `index.html` is the shell that loads them.

Deploy is automatic: pushing to `master` runs `.github/workflows/deploy.yml`, which builds, copies the static routes (`demo_drag/`, `demo_life/`, `CNAME`) into `dist/`, and publishes that to GitHub Pages. Pages source must be set to "GitHub Actions" in repo settings.

---

## File: demo_drag/README.md

[Draggable cards demo](https://chenglou.me/demo_drag/), showing shiny UI/UX details using the same architecture as the main image gallery. As seen in the [tweet](https://twitter.com/_chenglou/status/1609862082882863104).

[](https://youtu.be/iycK9nq1jf0)

## Features
- **Non-disruptive, interruptible transitions**. Animations don't block your ability to interact with the UI.
- **Dynamic depth management**. Proper z-index adjustments when cards overlap and when a card's being lifted.
- **[Framerate-decoupled animation](https://www.kirupa.com/animations/fixing_frame_rate_for_consistent_animations.htm)**. Transitions run well and on time even when framerate is uneven, or when frames are completely dropped on lower-end devices.
- **Spring physics**. Just like in the image gallery.
- **Card flick**. Releasing a card preserves the flick's velocity and throws it into place.
- **Smoothness & performance**. Works on 120fps displays, including ProMotion.

## Architecture

Same as [image gallery's chart](https://github.com/chenglou/chenglou.github.io/tree/b168386a23ccdffd2ff21c71d2a9e0871471c836#architecture).