@archetypeai/ds-cli 0.3.7

package/files/rules/state.md

@@ -0,0 +1,405 @@
+---
+paths:
+  - '**/*.svelte'
+  - '**/*.svelte.js'
+  - '**/*.svelte.ts'
+---
+
+# Svelte 5 State Management
+
+Svelte 5 uses runes - special `$` prefixed primitives that control reactivity.
+
+## $state - Reactive State
+
+Declare reactive state that triggers UI updates when changed:
+
+```svelte
+<script>
+  let count = $state(0);
+  let user = $state({ name: 'Alice', age: 30 });
+</script>
+
+<button onclick={() => count++}>
+  Clicked {count} times
+</button>
+```
+
+### Deep Reactivity
+
+Objects and arrays become deeply reactive proxies:
+
+```svelte
+<script>
+  let todos = $state([{ done: false, text: 'Learn Svelte 5' }]);
+
+  // This triggers updates - the array is a proxy
+  todos.push({ done: false, text: 'Build app' });
+
+  // This also triggers updates
+  todos[0].done = true;
+</script>
+```
+
+### $state.raw - Non-Proxied State
+
+For large objects you don't plan to mutate, use `$state.raw` for better performance:
+
+```svelte
+<script>
+  // Must reassign entirely, can't mutate
+  let data = $state.raw({ items: largeArray });
+
+  // This won't trigger updates
+  data.items.push(newItem);
+
+  // This will - full reassignment
+  data = { items: [...data.items, newItem] };
+</script>
+```
+
+### $state.snapshot - Get Plain Object
+
+Get a non-reactive copy of a state proxy (useful for APIs that don't expect proxies):
+
+```svelte
+<script>
+  let state = $state({ count: 0 });
+
+  function save() {
+    // Pass plain object to external API
+    const snapshot = $state.snapshot(state);
+    localStorage.setItem('state', JSON.stringify(snapshot));
+  }
+</script>
+```
+
+### Class Fields
+
+Use $state in class fields:
+
+```svelte
+<script>
+  class Counter {
+    count = $state(0);
+
+    increment() {
+      this.count++;
+    }
+  }
+
+  let counter = new Counter();
+</script>
+```
+
+## $derived - Computed Values
+
+Declare values that automatically update when dependencies change:
+
+```svelte
+<script>
+  let count = $state(0);
+  let doubled = $derived(count * 2);
+  let quadrupled = $derived(doubled * 2);
+</script>
+
+<p>{count} × 2 = {doubled}</p><p>{count} × 4 = {quadrupled}</p>
+```
+
+### $derived.by - Complex Derivations
+
+For multi-line logic, use `$derived.by`:
+
+```svelte
+<script>
+  let items = $state([1, 2, 3, 4, 5]);
+
+  let stats = $derived.by(() => {
+    const sum = items.reduce((a, b) => a + b, 0);
+    const avg = sum / items.length;
+    const max = Math.max(...items);
+    return { sum, avg, max };
+  });
+</script>
+
+<p>Sum: {stats.sum}, Avg: {stats.avg}, Max: {stats.max}</p>
+```
+
+### Overriding Derived Values (Optimistic UI)
+
+Derived values can be temporarily overridden:
+
+```svelte
+<script>
+  let { post } = $props();
+  let likes = $derived(post.likes);
+
+  async function like() {
+    likes++; // Optimistic update
+    try {
+      await api.likePost(post.id);
+    } catch {
+      likes--; // Rollback on failure
+    }
+  }
+</script>
+```
+
+## $effect - Side Effects
+
+Run code when reactive dependencies change:
+
+```svelte
+<script>
+  let count = $state(0);
+
+  $effect(() => {
+    console.log('Count changed to', count);
+    document.title = `Count: ${count}`;
+  });
+</script>
+```
+
+### Teardown / Cleanup
+
+Return a function to clean up before re-running or on destroy:
+
+```svelte
+<script>
+  let interval = $state(1000);
+
+  $effect(() => {
+    const id = setInterval(() => {
+      console.log('tick');
+    }, interval);
+
+    // Cleanup: runs before re-run and on component destroy
+    return () => clearInterval(id);
+  });
+</script>
+```
+
+### $effect.pre - Run Before DOM Updates
+
+Rarely needed - runs before DOM updates:
+
+```svelte
+<script>
+  let messages = $state([]);
+  let container;
+
+  $effect.pre(() => {
+    // Check scroll position before DOM updates
+    messages.length; // Track this dependency
+
+    if (container && shouldAutoScroll(container)) {
+      // Will scroll after DOM updates
+      tick().then(() => container.scrollTo(0, container.scrollHeight));
+    }
+  });
+</script>
+```
+
+### When NOT to Use $effect
+
+**Don't sync state - use $derived instead:**
+
+```svelte
+<script>
+  let count = $state(0);
+
+  // BAD - don't do this
+  let doubled = $state(0);
+  $effect(() => {
+    doubled = count * 2;
+  });
+
+  // GOOD - use $derived
+  let doubled = $derived(count * 2);
+</script>
+```
+
+**Don't create infinite loops:**
+
+```svelte
+<script>
+  let count = $state(0);
+
+  // BAD - infinite loop! reads and writes count
+  $effect(() => {
+    count = count + 1;
+  });
+</script>
+```
+
+**Use callbacks for linked values instead of effects:**
+
+```svelte
+<script>
+  let spent = $state(0);
+  let left = $derived(100 - spent);
+
+  // Update spent via callback, not effect
+  function updateLeft(newLeft) {
+    spent = 100 - newLeft;
+  }
+</script>
+
+<input type="range" bind:value={spent} max={100} />
+<input type="range" value={left} oninput={(e) => updateLeft(+e.target.value)} max={100} />
+```
+
+## $bindable - Two-Way Binding
+
+Enable parent components to bind to a prop:
+
+```svelte
+<!-- FancyInput.svelte -->
+<script>
+  let { value = $bindable(''), ...props } = $props();
+</script>
+
+<input bind:value {value} {...props} />
+```
+
+```svelte
+<!-- Parent.svelte -->
+<script>
+  import FancyInput from './FancyInput.svelte';
+  let name = $state('');
+</script>
+
+<FancyInput bind:value={name} /><p>Hello, {name}!</p>
+```
+
+See [components.md](./components.md) for more on `$props()` and `$bindable()`.
+
+## $inspect - Debugging (Dev Only)
+
+Log when values change (removed in production builds):
+
+```svelte
+<script>
+  let count = $state(0);
+  let user = $state({ name: 'Alice' });
+
+  // Logs whenever count or user changes
+  $inspect(count, user);
+</script>
+```
+
+### Custom Inspection
+
+```svelte
+<script>
+  let count = $state(0);
+
+  $inspect(count).with((type, value) => {
+    if (type === 'update') {
+      debugger; // Break on changes
+    }
+  });
+</script>
+```
+
+### Trace Effect Dependencies
+
+```svelte
+<script>
+  $effect(() => {
+    $inspect.trace(); // Must be first statement
+    doSomethingComplex();
+  });
+</script>
+```
+
+## Common Gotchas
+
+### Destructuring Breaks Reactivity
+
+```svelte
+<script>
+  let user = $state({ name: 'Alice', age: 30 });
+
+  // BAD - name and age are not reactive
+  let { name, age } = user;
+
+  // GOOD - access via object
+  // In template: {user.name}, {user.age}
+</script>
+```
+
+### Async Code Doesn't Track Dependencies
+
+```svelte
+<script>
+  let color = $state('red');
+  let size = $state(100);
+
+  $effect(() => {
+    // color is tracked (read synchronously)
+    console.log(color);
+
+    setTimeout(() => {
+      // size is NOT tracked (read async)
+      console.log(size);
+    }, 100);
+  });
+</script>
+```
+
+### Exporting Reassigned State
+
+Can't directly export state that gets reassigned:
+
+```javascript
+// state.svelte.js
+
+// BAD - won't work across modules
+export let count = $state(0);
+export function increment() {
+  count++;
+}
+
+// GOOD - wrap in object
+export const counter = $state({ count: 0 });
+export function increment() {
+  counter.count++;
+}
+
+// GOOD - use getters
+let count = $state(0);
+export function getCount() {
+  return count;
+}
+export function increment() {
+  count++;
+}
+```
+
+### Effects Only Run in Browser
+
+`$effect` doesn't run during SSR:
+
+```svelte
+<script>
+  $effect(() => {
+    // Safe to use browser APIs here
+    window.addEventListener('resize', handleResize);
+    return () => window.removeEventListener('resize', handleResize);
+  });
+</script>
+```
+
+## Quick Reference
+
+| Rune                | Purpose           | Example                                  |
+| ------------------- | ----------------- | ---------------------------------------- |
+| `$state(value)`     | Reactive state    | `let count = $state(0)`                  |
+| `$state.raw(value)` | Non-proxied state | `let data = $state.raw(bigObject)`       |
+| `$derived(expr)`    | Computed value    | `let doubled = $derived(count * 2)`      |
+| `$derived.by(fn)`   | Complex computed  | `$derived.by(() => { ... })`             |
+| `$effect(fn)`       | Side effect       | `$effect(() => { ... })`                 |
+| `$effect.pre(fn)`   | Pre-DOM effect    | `$effect.pre(() => { ... })`             |
+| `$props()`          | Component props   | `let { foo } = $props()`                 |
+| `$bindable()`       | Two-way prop      | `let { value = $bindable() } = $props()` |
+| `$inspect(...)`     | Debug logging     | `$inspect(count)`                        |

package/files/rules/styling.md

@@ -0,0 +1,245 @@
+---
+paths:
+  - '**/*.css'
+  - '**/*.svelte'
+---
+
+# Styling Rules
+
+## Semantic Token Reference
+
+### Background & Foreground Colors
+
+| Token                     | Usage                        |
+| ------------------------- | ---------------------------- |
+| `bg-background`           | Page/app background          |
+| `text-foreground`         | Primary text color           |
+| `bg-card`                 | Card backgrounds             |
+| `text-card-foreground`    | Text on cards                |
+| `bg-popover`              | Popover/dropdown backgrounds |
+| `text-popover-foreground` | Text in popovers             |
+| `bg-muted`                | Muted/subtle backgrounds     |
+| `text-muted-foreground`   | Secondary/muted text         |
+
+### Interactive Colors
+
+| Token                       | Usage                         |
+| --------------------------- | ----------------------------- |
+| `bg-primary`                | Primary buttons, links        |
+| `text-primary-foreground`   | Text on primary backgrounds   |
+| `bg-secondary`              | Secondary buttons             |
+| `text-secondary-foreground` | Text on secondary backgrounds |
+| `bg-accent`                 | Hover states, highlights      |
+| `text-accent-foreground`    | Text on accent backgrounds    |
+| `bg-destructive`            | Delete/error actions          |
+
+### Border & Input Colors
+
+| Token           | Usage                |
+| --------------- | -------------------- |
+| `border-border` | Default border color |
+| `border-input`  | Input field borders  |
+| `ring-ring`     | Focus ring color     |
+
+### Chart Colors
+
+| Token       | Usage                            |
+| ----------- | -------------------------------- |
+| `--chart-1` | First series color (purple)      |
+| `--chart-2` | Second series color (red-orange) |
+| `--chart-3` | Third series color (green)       |
+| `--chart-4` | Fourth series color (yellow)     |
+| `--chart-5` | Fifth series color (coral)       |
+
+### ATAI Brand Colors
+
+| Token                | Usage                 |
+| -------------------- | --------------------- |
+| `bg-atai-neutral`    | Brand blue accent     |
+| `text-atai-good`     | Success/healthy state |
+| `text-atai-warning`  | Warning state         |
+| `text-atai-critical` | Critical/error state  |
+
+### Sidebar Colors
+
+| Token                     | Usage                |
+| ------------------------- | -------------------- |
+| `bg-sidebar`              | Sidebar background   |
+| `text-sidebar-foreground` | Sidebar text         |
+| `bg-sidebar-accent`       | Sidebar hover/active |
+| `border-sidebar-border`   | Sidebar borders      |
+
+## When to Use Semantic vs Standard Tailwind
+
+### Use Semantic Tokens For:
+
+```svelte
+<!-- Themed colors that should change with light/dark mode -->
+<div class="bg-background text-foreground">
+<div class="bg-card border-border">
+<button class="bg-primary text-primary-foreground">
+<span class="text-muted-foreground">
+```
+
+### Use Standard Tailwind For:
+
+```svelte
+<!-- Spacing and sizing -->
+<div class="p-4 gap-2 w-full h-screen">
+
+<!-- Layout utilities -->
+<div class="flex items-center justify-between">
+<div class="grid grid-cols-2 gap-4">
+<div class="absolute top-0 left-0">
+
+<!-- One-off custom colors -->
+<div class="bg-linear-to-r from-purple-500 to-pink-500">
+<div class="text-amber-500">  <!-- specific non-themed color -->
+
+<!-- Responsive breakpoints -->
+<div class="sm:flex md:grid lg:hidden">
+
+<!-- Animations and transitions -->
+<div class="transition-all duration-200 ease-in-out">
+```
+
+## Dark Mode
+
+Dark mode activates via `.dark` class on the root element:
+
+```html
+<html class="dark">
+  ...
+</html>
+```
+
+Semantic tokens automatically switch values in dark mode. No manual dark: prefixes needed for themed colors:
+
+```svelte
+<!-- This works in both light and dark mode automatically -->
+<div class="bg-background text-foreground border-border">
+```
+
+For custom dark mode overrides, use the `dark:` prefix:
+
+```svelte
+<div class="bg-white dark:bg-slate-900">  <!-- custom dark override -->
+```
+
+## cn() Utility
+
+Import and use for all class composition:
+
+```javascript
+import { cn } from '$lib/utils.js';
+```
+
+```svelte
+<div class={cn(
+  'base-classes here',
+  conditional && 'conditional-classes',
+  className
+)}>
+```
+
+The utility:
+
+- Uses `clsx` for conditional class joining
+- Uses `tailwind-merge` to resolve conflicts (last wins)
+
+Example conflict resolution:
+
+```javascript
+cn('p-4', 'p-2'); // → 'p-2' (later wins)
+cn('bg-red-500', 'bg-background'); // → 'bg-background' (later wins)
+```
+
+## CSS Import Order
+
+In your global CSS file:
+
+```css
+@import '@archetypeai/ds-lib-fonts-internal';
+@import '@archetypeai/ds-lib-tokens/theme.css';
+@import 'tailwindcss';
+@import 'tw-animate-css'; /* optional, for animations */
+```
+
+Order matters - tokens must come before Tailwind.
+
+## Tailwind v4 Specifics
+
+### @theme Directive
+
+Custom theme values are defined with `@theme`:
+
+```css
+@theme {
+  --font-sans: 'PP Neue Montreal', system-ui, sans-serif;
+  --radius-md: var(--radius);
+  --spacing-md: 0.75rem;
+  --color-primary: var(--primary);
+}
+```
+
+### CSS Variables in Classes
+
+You can use CSS variables directly:
+
+```svelte
+<div style:--legend-color={seriesColor}>
+  <span class="bg-(--legend-color)"> </span>
+</div>
+```
+
+### No @apply in Components
+
+Prefer Tailwind classes directly in markup. Use @apply only in base layer CSS:
+
+```css
+/* In theme.css - OK */
+@layer base {
+  body {
+    @apply bg-background text-foreground;
+  }
+}
+```
+
+```svelte
+<!-- In components - use classes directly -->
+<div class="bg-background text-foreground">
+```
+
+## Common Patterns
+
+### Focus States
+
+```svelte
+<button class="focus-visible:ring-ring focus-visible:ring-2 focus-visible:ring-offset-2 outline-none">
+```
+
+### Disabled States
+
+```svelte
+<button class="disabled:pointer-events-none disabled:opacity-50">
+```
+
+### Data State Animations
+
+```svelte
+<div class="data-[state=open]:animate-in data-[state=closed]:animate-out">
+```
+
+### Responsive Design
+
+```svelte
+<div class="w-full max-w-[calc(100%-2rem)] sm:max-w-lg">
+<div class="flex flex-col sm:flex-row">
+```
+
+### Icon Sizing
+
+```svelte
+<!-- Default icon sizing utility -->
+<button class="[&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4">
+```