arkaos 5.4.0 → 5.6.0

package/departments/dev/skills/framer-motion/references/api.md

@@ -0,0 +1,312 @@
+# Framer Motion — API Reference
+
+> `motion` v11+ — `import { motion, AnimatePresence, ... } from "motion/react"`
+
+## motion component — Props
+
+### Animation
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `initial` | `Target \| VariantLabel \| false` | Initial state. `false` = no animation on mount (starts directly from `animate`) |
+| `animate` | `Target \| VariantLabel` | Target state. Change = animates automatically |
+| `exit` | `Target \| VariantLabel` | Exit animation (requires parent `AnimatePresence`) |
+| `transition` | `Transition` | Transition config (duration, ease, type, delay...) |
+| `variants` | `Variants` | Map of labels to targets. Propagate to motion children |
+
+### Gesture props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `whileHover` | `Target \| VariantLabel` | Animates during hover |
+| `whileTap` | `Target \| VariantLabel` | Animates during press/tap |
+| `whileFocus` | `Target \| VariantLabel` | Animates during focus |
+| `whileDrag` | `Target \| VariantLabel` | Animates during drag |
+| `whileInView` | `Target \| VariantLabel` | Animates when visible in the viewport |
+
+### Drag
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `drag` | `boolean \| "x" \| "y"` | Enables drag. `true` = both axes |
+| `dragConstraints` | `{ top, left, right, bottom } \| RefObject` | Drag limits. Ref = a parent element |
+| `dragElastic` | `number \| { top, left, right, bottom }` | Elasticity outside constraints (0-1, default 0.35) |
+| `dragMomentum` | `boolean` | Inertia after release (default true) |
+| `dragSnapToOrigin` | `boolean` | Returns to initial position after release |
+| `dragTransition` | `InertiaTransition` | Inertia transition config |
+| `dragPropagation` | `boolean` | Propagates drag to draggable parents |
+| `onDrag` | `(event, info: PanInfo) => void` | Callback during drag |
+| `onDragStart` | `(event, info: PanInfo) => void` | Callback at drag start |
+| `onDragEnd` | `(event, info: PanInfo) => void` | Callback at drag end |
+| `onDirectionLock` | `(axis: "x" \| "y") => void` | Callback when direction is locked |
+
+### Layout
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `layout` | `boolean \| "position" \| "size" \| "preserve-aspect"` | Automatically animates layout changes |
+| `layoutId` | `string` | Shared layout — animates between components sharing the same layoutId |
+| `layoutDependency` | `any` | Forces a layout recalculation when this value changes |
+| `layoutScroll` | `boolean` | Compensates scroll offset in layout calculations |
+| `onLayoutAnimationStart` | `() => void` | Callback at layout animation start |
+| `onLayoutAnimationComplete` | `() => void` | Callback at layout animation end |
+
+### Lifecycle callbacks
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `onAnimationStart` | `(definition) => void` | When an animation starts |
+| `onAnimationComplete` | `(definition) => void` | When an animation ends |
+| `onUpdate` | `(latest: ResolvedValues) => void` | On each frame during animation |
+| `onViewportEnter` | `(entry) => void` | When the element enters the viewport |
+| `onViewportLeave` | `(entry) => void` | When the element leaves the viewport |
+
+### Style (MotionValue-compatible)
+
+The `style` prop accepts `MotionValue` in addition to normal values:
+
+```tsx
+const x = useMotionValue(0);
+<motion.div style={{ x, opacity: 0.5 }} />
+```
+
+**Independent transforms** supported in `style`: `x`, `y`, `z`, `rotateX`, `rotateY`, `rotateZ`, `scale`, `scaleX`, `scaleY`, `skewX`, `skewY`.
+
+## AnimatePresence — Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `mode` | `"sync" \| "wait" \| "popLayout"` | Enter/exit behavior. Default `"sync"` |
+| `initial` | `boolean` | `false` = disables initial animations of children on first render |
+| `onExitComplete` | `() => void` | Callback when all exit animations are finished |
+| `custom` | `any` | Value passed to dynamic `exit` variants |
+| `presenceAffectsLayout` | `boolean` | Does the exiting element still affect layout (default true) |
+
+### Mode details
+
+- **`sync`** (default) — enter and exit simultaneously
+- **`wait`** — waits for exit to finish before starting enter (page transitions)
+- **`popLayout`** — removes the element from flow immediately via `position: absolute`, starts enter during exit
+
+## Transition — Configuration
+
+```tsx
+// Spring (default for physical values)
+transition={{ type: "spring", stiffness: 300, damping: 30, mass: 1 }}
+
+// Tween (default for opacity, color)
+transition={{ type: "tween", duration: 0.3, ease: "easeInOut" }}
+
+// Inertia (for drag momentum)
+transition={{ type: "inertia", velocity: 200, power: 0.8 }}
+
+// Per-value
+transition={{
+  x: { type: "spring", stiffness: 300 },
+  opacity: { duration: 0.2 },
+}}
+
+// Orchestration in variants
+transition={{
+  staggerChildren: 0.08,
+  delayChildren: 0.2,
+  staggerDirection: -1,       // reverse
+  when: "beforeChildren",     // or "afterChildren"
+}}
+```
+
+### Ease presets
+
+`"linear"`, `"easeIn"`, `"easeOut"`, `"easeInOut"`, `"circIn"`, `"circOut"`, `"circInOut"`, `"backIn"`, `"backOut"`, `"backInOut"`, `"anticipate"`
+
+Cubic bezier: `ease: [0.25, 0.1, 0.25, 1.0]`
+
+## Hooks
+
+### useMotionValue
+
+```tsx
+const x = useMotionValue(0);
+// Set without re-render
+x.set(100);
+// Read current value
+x.get(); // 100
+// Bind to style
+<motion.div style={{ x }} />
+```
+
+Creates a reactive value that updates the DOM without React re-render. Foundation of all other hooks.
+
+### useTransform
+
+```tsx
+// Map a value to another
+const opacity = useTransform(x, [-200, 0, 200], [0, 1, 0]);
+
+// Transform with a function
+const rounded = useTransform(x, (latest) => Math.round(latest));
+
+// Combine multiple values
+const combined = useTransform([x, y], ([latestX, latestY]) => latestX + latestY);
+```
+
+Derives a `MotionValue` from one or more others. Recalculated on each source change.
+
+### useSpring
+
+```tsx
+const springX = useSpring(motionValue, {
+  stiffness: 300,   // default 100
+  damping: 30,      // default 10
+  mass: 1,          // default 1
+  restSpeed: 0.01,
+  restDelta: 0.01,
+});
+
+// With initial value (number)
+const spring = useSpring(0);
+spring.set(100); // animates to 100 with spring physics
+```
+
+Creates a spring that follows a `MotionValue` or a number. Ideal for smooth scroll indicators, cursor followers.
+
+### useScroll
+
+```tsx
+// Page scroll
+const { scrollX, scrollY, scrollXProgress, scrollYProgress } = useScroll();
+
+// Target element scroll
+const ref = useRef(null);
+const { scrollYProgress } = useScroll({
+  target: ref,
+  offset: ["start end", "end start"],
+  // offset format: [targetEdge containerEdge]
+  // "start end" = when the top of target reaches the bottom of the container
+});
+
+// Specific container scroll
+const { scrollYProgress } = useScroll({ container: scrollRef });
+```
+
+Returns 4 `MotionValue`: absolute position (scrollX/Y) and normalized 0-1 progress (scrollXProgress/YProgress).
+
+**Offset keywords**: `"start"`, `"center"`, `"end"`, or a number/percentage (`0.5`, `"100px"`).
+
+### useAnimate
+
+```tsx
+const [scope, animate] = useAnimate();
+
+// Imperative animation
+await animate(scope.current, { x: 100, opacity: 1 }, { duration: 0.5 });
+
+// Selectors within the scope
+await animate("li", { opacity: 1 }, { delay: stagger(0.1) });
+
+// Sequence
+await animate([
+  [scope.current, { x: 100 }],
+  ["li", { opacity: 1 }, { delay: stagger(0.1) }],
+]);
+
+<div ref={scope}>
+  <li>...</li>
+</div>
+```
+
+Imperative API for complex animations, sequences, and dynamic orchestrations. Alternative to variants when logic is too dynamic.
+
+### useInView
+
+```tsx
+const ref = useRef(null);
+const isInView = useInView(ref, {
+  once: true,          // triggers only once
+  amount: 0.5,         // 50% visible (default "some")
+  margin: "-100px",    // rootMargin (like IntersectionObserver)
+});
+
+// Usage with animate
+<motion.div
+  ref={ref}
+  initial={{ opacity: 0, y: 50 }}
+  animate={isInView ? { opacity: 1, y: 0 } : {}}
+/>
+```
+
+Wrapper around `IntersectionObserver`. Returns a reactive boolean.
+
+### useReducedMotion
+
+```tsx
+const prefersReduced = useReducedMotion();
+
+<motion.div
+  animate={prefersReduced ? { opacity: 1 } : { opacity: 1, y: 0, scale: 1 }}
+  transition={prefersReduced ? { duration: 0 } : { type: "spring" }}
+/>
+```
+
+Respects `prefers-reduced-motion`. **Always use it** for non-essential animations. Returns `true` if the user has enabled the system preference.
+
+### useMotionValueEvent
+
+```tsx
+const x = useMotionValue(0);
+
+useMotionValueEvent(x, "change", (latest) => {
+  console.log("x changed to", latest);
+});
+
+useMotionValueEvent(x, "animationStart", () => { /* ... */ });
+useMotionValueEvent(x, "animationComplete", () => { /* ... */ });
+useMotionValueEvent(x, "animationCancel", () => { /* ... */ });
+```
+
+Subscribes to a MotionValue without re-render. Auto-cleanup on unmount. Prefer over `onChange` (deprecated).
+
+## Utilities
+
+### stagger
+
+```tsx
+import { stagger } from "motion/react";
+
+animate("li", { opacity: 1 }, { delay: stagger(0.1) });
+animate("li", { opacity: 1 }, { delay: stagger(0.1, { startDelay: 0.2 }) });
+animate("li", { opacity: 1 }, { delay: stagger(0.1, { from: "center" }) });
+// from: number | "first" | "center" | "last"
+```
+
+### animate (standalone)
+
+```tsx
+import { animate } from "motion/react";
+
+// Animate a value
+animate(0, 100, {
+  duration: 1,
+  onUpdate: (latest) => el.style.opacity = latest,
+});
+
+// Animate an element directly (outside React)
+animate(element, { opacity: 1 }, { duration: 0.5 });
+```
+
+### scroll (standalone)
+
+```tsx
+import { scroll } from "motion";
+
+// Callback based on scroll progress
+scroll((progress) => {
+  el.style.opacity = progress;
+});
+
+// Bind to an element's scroll
+scroll(
+  (progress) => { /* ... */ },
+  { target: element, offset: ["start end", "end start"] }
+);
+```

package/departments/dev/skills/framer-motion/references/genjutsu.LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adrien Thevon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/departments/dev/skills/threejs/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: dev/threejs
+description: >
+  Real-time 3D in the browser with three.js and React Three Fiber: modern
+  setup (import maps, WebGL vs WebGPU renderer choice, TSL), the
+  scene-camera-renderer wiring, geometries, materials and lights, loaders,
+  disposal discipline against GPU memory leaks, performance budgets — and
+  the R3F layer (hooks, drei, postprocessing) for React projects.
+  TRIGGER: "three.js", "threejs", "react three fiber", "r3f", "webgl",
+  "webgpu", "shader", "GLSL", "cena 3D", "3D interativo no browser",
+  "drei", "/dev threejs".
+  SKIP: a pre-rendered 3D world scrubbed by scroll (no real-time engine)
+  -> dev/scroll-world; generative 2D canvas -> dev/canvas-generative;
+  generating a 3D asset (GLB mesh) from an image -> the higgsfield-generate
+  skill; React motion without 3D -> dev/framer-motion.
+allowed-tools: [Read, Write, Edit, Bash, Grep, Glob]
+metadata:
+  origin: community
+  source: https://github.com/AThevon/genjutsu
+  license: MIT
+---
+
+<!-- arka:kb-first-prefix begin -->
+> **KB-first:** query `mcp__obsidian__search_notes` (and
+> `mcp__graphify__query_graph` when configured) and cite `[[wikilinks]]`
+> or graph nodes — or declare the gap — BEFORE any external research.
+> Full doctrine: `arka/SKILL.md` (KB-First Research).
+<!-- arka:kb-first-prefix end -->
+
+# Three.js — `/dev threejs`
+
+> **Agent:** Diana (Frontend Dev) | **Framework:** three.js (MIT) + React Three Fiber
+> Core authored from the three.js project's own LLM guidance
+> (`docs/llms.txt`, MIT); the R3F layer derives from genjutsu (MIT) — see
+> `references/`.
+
+## Setup — the modern shape
+
+Import maps, never legacy CDN script tags. Pin one version for `three`
+and `three/addons/` together — mixing versions across the two specifiers
+is the classic silent breaker:
+
+```html
+<script type="importmap">
+{ "imports": {
+    "three": "https://cdn.jsdelivr.net/npm/three@<version>/build/three.module.js",
+    "three/webgpu": "https://cdn.jsdelivr.net/npm/three@<version>/build/three.webgpu.js",
+    "three/tsl": "https://cdn.jsdelivr.net/npm/three@<version>/build/three.tsl.js",
+    "three/addons/": "https://cdn.jsdelivr.net/npm/three@<version>/examples/jsm/" } }
+</script>
+```
+
+`WebGPURenderer` is not exported from `three` — it lives in the
+`three/webgpu` entry, and it is async: `await renderer.init()` before the
+first frame. The TSL node functions live in `three/tsl`, not in
+`three/webgpu`. Omit either entry and the import fails at runtime.
+
+In a bundled project, `npm i three` and import the same specifiers. Check
+the installed version before writing code — the API moves, and the
+project's lockfile outranks your memory of it.
+
+**Renderer choice.** `WebGLRenderer` is the default and safe everywhere.
+`WebGPURenderer` (with TSL node materials) is the forward path but needs
+feature detection and a WebGL fallback; choose it only when the project
+targets browsers you control or ships the fallback. Never mix GLSL
+`ShaderMaterial` into a WebGPU pipeline — that renderer wants TSL
+`NodeMaterial` classes.
+
+## The irreducible core
+
+Scene, camera, renderer, loop — everything else hangs off these:
+
+```js
+const scene = new THREE.Scene();
+const camera = new THREE.PerspectiveCamera(75, w / h, 0.1, 100);
+const renderer = new THREE.WebGLRenderer({ antialias: true });
+renderer.setSize(w, h);
+renderer.setPixelRatio(Math.min(devicePixelRatio, 2)); // cap DPR: 3x buys nothing visible and burns fill rate
+renderer.setAnimationLoop(tick);                        // not a hand-rolled rAF: in XR it swaps to the session's loop; outside XR it is rAF with correct teardown via setAnimationLoop(null)
+```
+
+On resize: update `camera.aspect`, call `camera.updateProjectionMatrix()`,
+then `renderer.setSize`. Forgetting the middle step is why "resize
+stretches everything".
+
+**Animate with elapsed time, not the frame count.** A per-frame delta
+keeps speed identical at 30 and 144 fps; per-frame increments do not.
+Use `THREE.Timer` (`timer.update(); timer.getDelta()`) — `THREE.Clock`
+is deprecated since r183 and warns at runtime.
+
+## Disposal — GPU memory does not garbage-collect
+
+Removing a mesh from the scene frees nothing on the GPU. Every geometry,
+material, texture and render target you create, you `dispose()` when its
+life ends — and a material's textures are disposed separately from the
+material. For a whole subtree, collect first, dispose once: `traverse`
+visits Groups and Lights that have no material, and shared resources must
+not be disposed per-mesh:
+
+```js
+function disposeSubtree(root) {
+  const geometries = new Set(), materials = new Set(), textures = new Set();
+  root.traverse((obj) => {
+    if (!obj.isMesh && !obj.isPoints && !obj.isLine && !obj.isSprite) return;
+    // Sprites share one engine-owned quad geometry app-wide: never dispose it
+    if (obj.geometry && !obj.isSprite) geometries.add(obj.geometry);
+    const mats = Array.isArray(obj.material) ? obj.material : [obj.material];
+    for (const m of mats) {
+      if (!m) continue;
+      materials.add(m);
+      for (const v of Object.values(m)) if (v?.isTexture) textures.add(v);
+      // ShaderMaterial textures live in uniforms, not on the material —
+      // and a uniform's value can be an ARRAY of textures (atlas shape)
+      if (m.uniforms) for (const u of Object.values(m.uniforms)) {
+        const vals = Array.isArray(u?.value) ? u.value : [u?.value];
+        for (const v of vals) if (v?.isTexture) textures.add(v);
+      }
+    }
+  });
+  textures.forEach((t) => t.dispose());
+  materials.forEach((m) => m.dispose());
+  geometries.forEach((g) => g.dispose());
+}
+```
+
+This covers the shapes meshes ordinarily carry — geometries, material
+maps, scalar and array texture uniforms. When a resource is shared
+with meshes OUTSIDE the subtree — a texture atlas, a cached material —
+exclude it: ownership is yours to model, and dispose belongs to the owner.
+
+A single-page app that mounts and unmounts scenes without this leaks
+until the tab dies. This is the number-one three.js production bug.
+
+## Performance budget
+
+- **Draw calls first.** Hundreds of meshes sharing one geometry+material
+  belong in an `InstancedMesh`; thousands of distinct static meshes merge
+  via `BufferGeometryUtils.mergeGeometries`.
+- Reuse geometries and materials across meshes; clone only when a
+  property must diverge.
+- Textures: compressed formats (KTX2/Basis) for anything big, and never
+  larger than the screen area they cover; mipmaps come from the loader or
+  `generateMipmaps`, with no power-of-two constraint in WebGL 2.
+- Lights are per-fragment cost: prefer one directional + ambient or an
+  environment map over a constellation of point lights. Bake what does
+  not move.
+- Shadows are a render pass per caster: tight `shadow.camera` frustum,
+  modest map sizes, `castShadow` only where it is visible.
+
+## Loading models
+
+`GLTFLoader` (with `DRACOLoader` or `KTX2Loader` when the asset uses
+them) from `three/addons/`. Load asynchronously, add a loading state,
+and dispose the loader's intermediates. glTF is the format; converting
+from anything else happens in the asset pipeline, not at runtime.
+
+## React Three Fiber
+
+For React projects, R3F replaces the imperative wiring: the component
+tree IS the scene graph, `useFrame` is the loop, drei supplies the
+controls/loaders/staging you would otherwise hand-write. The full layer —
+hooks discipline, drei picks, postprocessing, and the Do-Nots (from
+setState in useFrame to forgotten dispose) — lives
+in [references/r3f.md](references/r3f.md), with canvas/scene wiring in
+[references/scene-setup.md](references/scene-setup.md) and GLSL/TSL
+patterns in [references/shaders.md](references/shaders.md).
+
+## Output
+
+A working scene module (or R3F component tree) with the render loop,
+resize handling and disposal wired, a stated performance budget (draw
+calls, texture memory, DPR cap), and the renderer choice justified in one
+line. Anything WebGPU/TSL states its fallback.

package/departments/dev/skills/threejs/references/genjutsu.LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adrien Thevon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.