refactor: use remix 3

.agents/skills/remix/references/animate-elements.md

@@ -0,0 +1,195 @@
+# Animating Elements
+
+## What This Covers
+
+How to animate insertion, removal, and layout changes of elements. Read this when the task
+involves:
+
+- Adding entrance, exit, or shared-layout transitions to UI
+- Choosing between spring physics (`spring(...)`) and time-based easing (`tween`)
+- Coordinating CSS transitions with the same easing as JS animations
+- Imperative animation loops via `requestAnimationFrame`
+
+Import animation APIs from `remix/ui/animation`. For the smaller set of animation helpers that
+show up alongside other mixins, see `mixins-styling-events.md`.
+
+## Animation Mixins
+
+### `animateEntrance(config)`
+
+Animates an element when inserted. Config specifies the **starting** style the element animates
+**from**:
+
+```tsx
+<div
+  mix={animateEntrance({
+    opacity: 0,
+    transform: "translateY(8px)",
+    ...spring("smooth"),
+  })}
+/>
+```
+
+### `animateExit(config)`
+
+Animates an element when removed. Config specifies the **ending** style the element animates
+**to**. The element stays in the DOM until the animation completes:
+
+```tsx
+{
+  isVisible && (
+    <div
+      key="panel"
+      mix={[
+        animateEntrance({ opacity: 0, transform: "scale(0.98)", ...spring("smooth") }),
+        animateExit({ opacity: 0, duration: 120, easing: "ease-in" }),
+      ]}
+    />
+  );
+}
+```
+
+### `animateLayout(config?)`
+
+Animates layout changes (position/size) using FLIP-style transforms:
+
+```tsx
+{
+  items.map((item) => (
+    <li key={item.id} mix={animateLayout({ ...spring({ duration: 500, bounce: 0.2 }) })} />
+  ));
+}
+```
+
+Options: `duration` (default 200ms), `easing` (default spring snappy), `size` (default true —
+include scale projection for size changes).
+
+### Combining mixins
+
+```tsx
+<div
+  key="card"
+  mix={[
+    animateEntrance({ opacity: 0, transform: "scale(0.95)", ...spring("snappy") }),
+    animateExit({ opacity: 0, transform: "scale(0.98)", duration: 120, easing: "ease-in" }),
+    animateLayout({ duration: 220, easing: "ease-out" }),
+  ]}
+/>
+```
+
+### Shared-layout swap
+
+```tsx
+<div mix={css({ display: "grid", "& > *": { gridArea: "1 / 1" } })}>
+  {stateA ? (
+    <div key="a" mix={[animateEntrance({ opacity: 0 }), animateExit({ opacity: 0 })]} />
+  ) : (
+    <div key="b" mix={[animateEntrance({ opacity: 0 }), animateExit({ opacity: 0 })]} />
+  )}
+</div>
+```
+
+## Spring API
+
+Physics-based spring animation. Returns a `SpringIterator` with `duration`, `easing`, and
+`toString()` for CSS.
+
+### Presets
+
+| Preset   | Bounce | Duration | Character                   |
+| -------- | ------ | -------- | --------------------------- |
+| `smooth` | -0.3   | 400ms    | Overdamped, no overshoot    |
+| `snappy` | 0      | 200ms    | Critically damped, quick    |
+| `bouncy` | 0.3    | 400ms    | Underdamped, visible bounce |
+
+```tsx
+spring("bouncy");
+spring("snappy");
+spring("smooth");
+spring("bouncy", { duration: 300 }); // override duration
+```
+
+### Custom spring
+
+```tsx
+spring({ duration: 500, bounce: 0.3 });
+spring({ duration: 500, bounce: 0.3, velocity: 2 }); // continue momentum from gesture
+```
+
+### Spread into animation mixins
+
+Spreading a spring gives both `duration` and `easing`:
+
+```tsx
+animateEntrance({ opacity: 0, ...spring("bouncy") });
+```
+
+### CSS transitions
+
+The iterator stringifies to `"550ms linear(...)"`:
+
+```tsx
+css({ transition: `width ${spring("bouncy")}` });
+```
+
+Or use the `spring.transition()` helper for multiple properties:
+
+```tsx
+css({ transition: spring.transition("width", "bouncy") });
+css({ transition: spring.transition(["left", "top"], "snappy") });
+```
+
+### Web Animations API
+
+```tsx
+element.animate(keyframes, { ...spring("bouncy") });
+```
+
+### JS iteration
+
+The iterator yields position values from 0 to 1, one per frame:
+
+```tsx
+for (let t of spring("bouncy")) {
+  let x = from + (to - from) * t;
+  updateSomething(x);
+  await nextFrame();
+}
+```
+
+## Tween API
+
+Generator-based tween for animating values over time with cubic bezier easing. Prefer animation
+mixins or CSS transitions with `spring` for most UI work. Use `tween` for imperative
+`requestAnimationFrame` loops, canvas/WebGL, or non-CSS properties.
+
+```tsx
+import { tween, easings } from "remix/ui/animation";
+
+let animation = tween({
+  from: 0,
+  to: 100,
+  duration: 300,
+  curve: easings.easeOut,
+});
+
+animation.next(); // initialize
+function tick(timestamp: number) {
+  if (handle.signal.aborted) return;
+  let { value, done } = animation.next(timestamp);
+  element.style.transform = `translateX(${value}px)`;
+  if (!done) requestAnimationFrame(tick);
+}
+requestAnimationFrame(tick);
+```
+
+Built-in easings: `easings.linear`, `easings.ease`, `easings.easeIn`, `easings.easeOut`,
+`easings.easeInOut`.
+
+## Practical Guidance
+
+- Always key conditional or switching elements you expect to animate.
+- Use `animateLayout` only on the element whose position or size changes.
+- Prefer one clear transition intent per mixin: entrance starts from a style, exit ends at a style.
+- Default to `...spring()` for duration and easing in most cases.
+- Keep DOM work in `handle.queueTask(...)` or `ref(...)`, not in render.

.agents/skills/remix/references/assets-and-browser-modules.md

@@ -0,0 +1,122 @@
+# Assets and Browser Modules
+
+## What This Covers
+
+How to serve browser scripts and styles from source. Read this when the task involves:
+
+- Configuring `createAssetServer` (`fileMap`, `allow`, `deny`, fingerprinting, compiler options)
+- Choosing between `staticFiles()` for already-built files and `createAssetServer()` for source
+  assets that need import rewriting, preloads, or fingerprinted URLs
+- Generating script URLs or `<link rel="modulepreload">` tags for a client entry
+- Keeping server-only files out of the browser via `deny` rules
+
+For routing the URL namespace itself, see `routing-and-controllers.md`. For client entry
+hydration, see `hydration-frames-navigation.md`.
+
+## When To Reach For It
+
+Use `remix/assets` when the app serves browser JavaScript, TypeScript, or CSS from source files.
+This is the right tool for client entrypoints, browser-only helpers, styles under `app/assets/`,
+and monorepo code that should be compiled and served under a public URL namespace.
+
+Use `staticFiles()` for files that already exist on disk exactly as they should be served. Use
+`createAssetServer()` for source scripts or styles that need rewriting, dependency scanning,
+preloads, sourcemaps, or fingerprinted URLs.
+
+## Default Pattern
+
+```typescript
+import * as path from "node:path";
+
+import { createAssetServer } from "remix/assets";
+import { createRouter } from "remix/fetch-router";
+
+let assetServer = createAssetServer({
+  rootDir: path.resolve(import.meta.dirname, ".."),
+  fileMap: {
+    "/assets/app/*path": "app/*path",
+    "/assets/packages/*path": "../packages/*path",
+  },
+  allow: ["app/assets/**", "../packages/**"],
+  deny: ["app/**/*.server.*"],
+  target: { es: "2020", chrome: "109", safari: "16.4" },
+  sourceMaps: process.env.NODE_ENV === "development" ? "external" : undefined,
+  minify: process.env.NODE_ENV === "production",
+  scripts: {
+    define: {
+      "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV ?? "development"),
+    },
+  },
+});
+
+let router = createRouter();
+
+router.get("/assets/*path", ({ request }) => {
+  return assetServer.fetch(request);
+});
+```
+
+## Rules
+
+- Treat `allow` and `deny` as the security boundary for browser-reachable source files.
+- Add a `deny` list for server-only modules such as `*.server.*`, private config, or other files
+  that should never be exposed.
+- Set `rootDir` explicitly in monorepos so relative paths resolve from the intended project root.
+- `fileMap` keys are public URL patterns and values are root-relative file path patterns. They use
+  `route-pattern` syntax on both sides.
+- Keep the same wildcard params on both sides of a `fileMap` entry so import rewriting can map
+  source files back to public URLs.
+- CSS files are compiled and served alongside scripts. Local CSS `@import` rules are rewritten and
+  fingerprinted with the same asset server routing rules.
+
+## Rendering HTML
+
+Use `getHref()` when you need the public URL for one module, and `getPreloads()` when you want
+`<link rel="modulepreload">` tags or `Link` headers for one or more entrypoints and their
+dependencies.
+
+```typescript
+let entryHref = await assetServer.getHref("app/assets/entry.ts");
+let preloads = await assetServer.getPreloads(["app/assets/entry.ts"]);
+```
+
+Use this when rendering documents or layouts that boot browser behavior with a known client entry.
+
+When resolving hydrated client entries during server rendering, pass the source entry ID from
+`clientEntry(import.meta.url, ...)` to `getHref()` inside `resolveClientEntry`. Keep export-name
+resolution in that render helper, and avoid hard-coding public asset URLs in source-owned component
+modules.
+
+## Development vs Deployment
+
+In development:
+
+- Keep `watch` enabled so source changes are picked up without restarting the server
+- Prefer stable URLs with normal revalidation
+- Enable source maps when debugging browser code
+
+In deployment:
+
+- Set `watch: false`
+- Use `fingerprint: { buildId }` for long-lived immutable caching
+- Make sure `buildId` changes for each deploy
+
+Fingerprinting assumes files on disk are stable and requires `watch: false`.
+
+## Useful Compiler Options
+
+- `minify` for production minification of scripts and styles
+- `sourceMaps` for `'external'` or `'inline'` source maps for scripts and styles
+- `sourceMapSourcePaths` for `'url'` or `'absolute'` source map paths
+- `target` as an object for shared browser targets and script-only ECMAScript output, such as
+  `{ es: '2020', chrome: '109', safari: '16.4' }`
+- `scripts.define` to replace globals such as `process.env.NODE_ENV`
+- `scripts.external` to leave specific script imports untouched
+
+Do not nest shared compiler options under `scripts`. Use top-level `minify`, `sourceMaps`,
+`sourceMapSourcePaths`, and `target` so they apply to styles as well as scripts.
+
+## Lifecycle
+
+If the asset server is long-lived and watching the file system, call `await assetServer.close()`
+when shutting down dev servers or disposing tests.