chati-dev 4.2.2 → 4.3.0

package/framework/scaffold/motion-premium-3d/scaffold.yaml

@@ -0,0 +1,133 @@
+# Scaffold Premium 3D — motion-premium-3d v1.0.0
+#
+# Extends motion-premium with React Three Fiber + Three.js templates for
+# premium scroll-driven 3D experiences (camera rigs tied to ScrollTrigger
+# scrub, scene crossfades, mesh animation, particle systems, WebGL
+# fallback). Ship as a SEPARATE preset (ADR-3D-01) — 2D projects pay zero
+# bundle cost; 3D projects apply motion-premium first, then this layer.
+#
+# Contract: files[] target paths are disjoint from motion-premium (checked
+# at CI via scaffold-applier test in P9). The two presets compose without
+# conflict on the scaffold-applier's already-exists skip guard.
+
+id: motion-premium-3d
+version: 1.0.0
+description: "R3F + Three.js scroll-driven 3D layer for premium sites. Extends motion-premium. Separate bundle — apply only when 3D is in scope."
+
+framework:
+  chati_dev: ">=4.3.0"
+
+stack:
+  build_tools: ["nextjs"]
+  tailwind: ">=4.0.0"
+  typescript: ">=5.0.0"
+  node: ">=22.0.0"
+  react: ">=18.0.0"
+  # Peer deps pinned by MINOR (ADR-3D-06). Bumping policy: every two minor
+  # bumps from Three.js, update the tested matrix + re-validate templates.
+  three: "^0.160.0"
+  "@react-three/fiber": "^8.15.0"
+  "@react-three/drei": "^9.92.0"
+  # gsap + ScrollTrigger imported directly by ScrollScene.tsx and
+  # InvalidateOnScroll.tsx. motion-premium-3d composes on top of motion-premium
+  # but also declares the dep so a standalone apply (no motion-premium first)
+  # still has an accurate peer-dep surface.
+  gsap: "^3.12.5"
+
+# Inherits motion-premium's brand placeholders — at apply time the loader
+# resolves identically (brand.ts > brandbook.md > interactive). SceneFallback
+# uses PRIMARY_HEX for the fallback background, hence the dependency here.
+placeholders:
+  PRIMARY_HEX:
+    source: brand.colors.primary
+    default: "#7C3AED"
+    type: hex
+  BG_DEEP_HEX:
+    source: brand.colors.bgDeep
+    default: "#0A0A0F"
+    type: hex
+
+brand_sources:
+  - path: lib/brand.ts
+    type: typescript
+    description: "Preferred: brand tokens shared with motion-premium"
+  - path: artifacts/4-UX/brandbook.md
+    type: markdown
+    description: "UX-authored brandbook"
+  - type: interactive
+    prompt: true
+    description: "Fallback: ask user for each placeholder"
+
+# Files ship in phases P2-P5 of the workstream (see
+# .planning/motion-premium-3d-v1.md). P1 landed the skeleton; P2 adds
+# the WebGL detection + fallback trio; P3-P5 add the 3D canvas,
+# scroll-scene, and demo templates.
+files:
+  - source: lib/webgl/detect.ts.template
+    target: lib/webgl/detect.ts
+    phase: webgl
+    override: none
+    notes: "Pure client-side detector. WebGL2 > WebGL1 > reduced-motion opt-out. Scaffold-owned — the cleanup + reduced-motion coordination (ADR-3D-08) is invariant."
+  - source: components/webgl/WebGLContext.tsx.template
+    target: components/webgl/WebGLContext.tsx
+    phase: webgl
+    override: none
+    notes: "React context owning the one-shot detect result. useWebGLReady() hook exposed for consumer short-circuiting. Do not modify — all 3D templates rely on this shape."
+  - source: components/webgl/SceneFallback.tsx.template
+    target: components/webgl/SceneFallback.tsx
+    phase: webgl
+    override: partial
+    notes: "Rendered when WebGL is unavailable. Gradient uses brand placeholders. Extend with children (headline/CTA) — do not remove the role/aria-label contract."
+  - source: components/3d/CanvasProvider.tsx.template
+    target: components/3d/CanvasProvider.tsx
+    phase: canvas
+    override: none
+    notes: "Sole <Canvas> mount. frameloop=demand + WebGL gate + retina-aware DPR. Scaffold-owned — the single-RAF invariant depends on not patching this."
+  - source: components/3d/InvalidateOnScroll.tsx.template
+    target: components/3d/InvalidateOnScroll.tsx
+    phase: canvas
+    override: none
+    notes: "Bridges gsap.ticker -> R3F invalidate(). Must mount inside <Canvas>. Scaffold-owned — removing this re-fragments the RAF budget across Lenis/GSAP/R3F."
+  - source: components/3d/ScrollScene.tsx.template
+    target: components/3d/ScrollScene.tsx
+    phase: scroll-scene
+    override: none
+    notes: "Pinned section with ScrollTrigger-driven progress ref. Scaffold-owned — progress is read by CameraRig/ScrollCrossfade/MeshCrossfade inside <Canvas>."
+  - source: components/3d/CameraRig.tsx.template
+    target: components/3d/CameraRig.tsx
+    phase: scroll-scene
+    override: partial
+    notes: "Keyframe-driven camera interpolation. User supplies keyframes[] via props. Per-segment easing supported. Internal lerp uses reusable Vector3 scratch (zero per-frame alloc)."
+  - source: components/3d/ScrollCrossfade.tsx.template
+    target: components/3d/ScrollCrossfade.tsx
+    phase: scroll-scene
+    override: partial
+    notes: "Multi-group scene crossfade. stops[] + optional at[] for uneven spacing. Best-effort material.opacity cascade with visibility short-circuit for GPU skip."
+  - source: components/3d/MeshCrossfade.tsx.template
+    target: components/3d/MeshCrossfade.tsx
+    phase: scroll-scene
+    override: partial
+    notes: "Single-slot mesh variant swapping with hysteresis (default 2 percent). Use when inactive variants should NOT be instantiated."
+  - source: app/(3d)/scroll-demo/page.tsx.template
+    target: app/(3d)/scroll-demo/page.tsx
+    phase: demo
+    override: partial
+    notes: "Route-group entry. Server Component — metadata + Client wrapper. URL stays at /scroll-demo; drop app/(3d)/ folder to remove. User replaces content for production."
+  - source: app/(3d)/scroll-demo/ScrollDemoClient.tsx.template
+    target: app/(3d)/scroll-demo/ScrollDemoClient.tsx
+    phase: demo
+    override: partial
+    notes: "Client wrapper: WebGLProvider, ScrollScene, ScrollSceneContext. Dynamic-imports ScrollDemoCanvas with ssr:false. User customises overlay HTML + section length."
+  - source: app/(3d)/scroll-demo/ScrollDemoCanvas.tsx.template
+    target: app/(3d)/scroll-demo/ScrollDemoCanvas.tsx
+    phase: demo
+    override: partial
+    notes: "Canvas subtree: CanvasProvider + InvalidateOnScroll + CameraRig + MeshCrossfade + Preload. The 600KB 3D bundle is isolated behind this file's dynamic boundary."
+
+principles:
+  - "Single RAF via frameloop=demand (ADR-3D-03) — Lenis drives GSAP drives invalidate()"
+  - "Canvas mounts client-only via next/dynamic({ ssr: false }) (ADR-3D-04)"
+  - "WebGL detection + SceneFallback graceful degrade (ADR-3D-05)"
+  - "Reduced-motion non-negotiable — prefers-reduced-motion=reduce renders fallback, never the canvas (ADR-3D-08)"
+  - "Disjoint file targets from motion-premium — scaffold-applier enforces the invariant"
+  - "R3F (not vanilla Three.js) for composability with React 19 (ADR-3D-02)"

package/framework/schemas/session.schema.json

@@ -3,8 +3,59 @@
   "title": "chati.dev Session",
   "description": "Schema for .chati/session.yaml - runtime state tracking",
   "type": "object",
-  "required": ["project", "current_agent", "language", "execution_mode"],
+  "required": ["schema_version", "version", "project", "current_agent", "language", "execution_mode"],
   "properties": {
+    "schema_version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+$",
+      "description": "Session schema version (current: 1.2). migrateSession() handles v0 → v1.2 additively."
+    },
+    "version": {
+      "type": "string",
+      "description": "Legacy framework-version marker on the session object (distinct from schema_version). Kept for backwards compatibility."
+    },
+    "mode": {
+      "enum": ["discover", "plan", "build", "validate", "deploy", "completed"],
+      "default": "discover",
+      "description": "Flat pipeline macro-phase (mirrors project.state). Read by prism-engine and mode-governance hooks."
+    },
+    "project_type": {
+      "enum": ["greenfield", "brownfield"],
+      "default": "greenfield",
+      "description": "Flat copy of project.type — kept for hook convenience."
+    },
+    "started_at": {
+      "type": ["string", "null"],
+      "format": "date-time",
+      "description": "ISO timestamp of session creation. Consulted by reasoning-escalator for the deliberate-tier plan freshness check."
+    },
+    "pipeline_position": {
+      "type": "integer",
+      "minimum": 0,
+      "default": 0,
+      "description": "0-indexed position in the AGENT_PIPELINE array. Advanced by recordAgentCompletion."
+    },
+    "completed_agents": {
+      "type": "array",
+      "items": { "type": "string" },
+      "default": [],
+      "description": "History of completed agent names in order. Used by advance-trigger to gate re-entry and by the /chati next routing logic."
+    },
+    "agent_results": {
+      "type": "object",
+      "default": {},
+      "description": "Per-agent score history keyed by agent name. Populated by recordAgentCompletion.",
+      "patternProperties": {
+        "^[a-z][a-z0-9-]*$": {
+          "type": "object",
+          "properties": {
+            "score": { "type": "number", "minimum": 0, "maximum": 100 },
+            "verdict": { "enum": ["APPROVED", "REVIEW", "NEEDS_WORK", "PASS", "FAIL", null] },
+            "completed_at": { "type": ["string", "null"], "format": "date-time" }
+          }
+        }
+      }
+    },
     "project": {
       "type": "object",
       "required": ["name", "type", "state"],
@@ -19,32 +70,12 @@
       "default": "interactive",
       "description": "interactive = agent-driven guided mode; autonomous = Ralph Wiggum mode (Dev agent)"
     },
-    "execution_profile": {
-      "type": "string",
-      "enum": ["explore", "guided", "autonomous"],
-      "default": "guided",
-      "description": "Current execution profile governing confirmation requirements"
-    },
     "providers_enabled": {
       "type": "array",
       "items": { "type": "string" },
       "default": ["claude"],
       "description": "List of enabled CLI providers"
     },
-    "profile_transitions": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "properties": {
-          "from": { "type": "string" },
-          "to": { "type": "string" },
-          "reason": { "type": "string" },
-          "timestamp": { "type": "string", "format": "date-time" }
-        }
-      },
-      "default": [],
-      "description": "History of execution profile changes"
-    },
     "current_agent": {
       "type": "string",
       "description": "Currently active agent name"
@@ -300,6 +331,63 @@
         }
       }
     },
+    "scaffold_candidates": {
+      "type": "array",
+      "default": [],
+      "description": "Scaffold presets eligible for this project (Fase 10 auto-gate). Written by discovery agents (e.g. greenfield-wu) when stack answer matches a preset's trigger conditions.",
+      "items": { "type": "string" }
+    },
+    "scaffold_signals": {
+      "type": "object",
+      "default": {},
+      "description": "Per-preset confidence signals collected during planning (Fase 10 auto-gate). Keys are preset ids (e.g. 'motion_premium', using underscore to avoid YAML dash quoting).",
+      "patternProperties": {
+        "^[a-z][a-z0-9_]*$": {
+          "type": "object",
+          "properties": {
+            "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "0.0 - 1.0. Gate fires at >= 0.7." },
+            "evidence": { "type": "array", "items": { "type": "string" }, "description": "Short strings naming the matches (e.g. 'GSAP ScrollTrigger', 'Lenis smooth-scroll')." },
+            "source_agent": { "type": "string", "description": "Agent that wrote this signal (e.g. 'ux-brand-architect')." },
+            "updated_at": { "type": "string", "format": "date-time" }
+          }
+        }
+      }
+    },
+    "scaffold_applied": {
+      "type": "array",
+      "default": [],
+      "description": "Presets that have been applied via the auto-gate decision dispatcher (Fase 10). Prevents double-apply if advance is re-run.",
+      "items": { "type": "string" }
+    },
+    "active_model": {
+      "type": ["string", "null"],
+      "default": null,
+      "description": "Normalized Claude model key (Article XII v2 / context-window-detection v1). Output of parseClaudeModelId — e.g. 'opus', 'opus[1m]', 'sonnet', 'haiku'. Written at /chati boot; drives context-limit resolution in hooks. Null = unknown (detection chain falls through to provider default)."
+    },
+    "active_provider": {
+      "type": ["string", "null"],
+      "enum": ["claude", "gemini", "codex", null],
+      "default": null,
+      "description": "Active CLI provider. Redundant with providers_enabled[0] but flat for hook convenience."
+    },
+    "context_tokens_used": {
+      "type": "integer",
+      "minimum": 0,
+      "default": 0,
+      "description": "Cumulative rolling estimate of tokens consumed in this session, character-based (1 token ≈ 4 chars). Updated by prism-engine on every UserPromptSubmit. Replaces turn-count as the primary metric for bracket determination."
+    },
+    "context_window_tokens": {
+      "type": ["integer", "null"],
+      "minimum": 1,
+      "default": null,
+      "description": "Cached window size resolved from active_model + active_provider. Lets hooks compute remaining% without re-loading model-limits.json."
+    },
+    "context_last_bracket": {
+      "type": ["string", "null"],
+      "enum": ["FRESH", "MODERATE", "DEPLETED", "CRITICAL", null],
+      "default": null,
+      "description": "Last computed bracket. Surfaced in /chati status and telemetry."
+    },
     "decision_trail": {
       "type": "array",
       "default": [],