diff --git a/.agent/skills/astro/SKILL.md b/.agent/skills/astro/SKILL.md new file mode 100644 index 00000000..f8403308 --- /dev/null +++ b/.agent/skills/astro/SKILL.md @@ -0,0 +1,43 @@ +--- +name: astro +description: Comprehensive guide for developing with the Astro web framework, including component architecture, routing, and deployment. +--- + +# Astro Framework Skill + +Use this skill when developing, refactoring, or architecting applications using Astro. + +## Core Concepts + +### 1. Component Architecture +- **Astro Components (`.astro`)**: Zero-client-side JS by default. Components are processed at build time. +- **Island Architecture**: Hydrate interactive UI (Svelte, React, Vue) only when needed using `client:load`, `client:visible`, etc. +- **Content Collections**: Type-safe Markdown/MDX management via `src/content/config.ts`. + +### 2. Routing & Pages +- **File-based Routing**: Any file in `src/pages/` becomes a route. +- **Dynamic Routes**: Use `[id].astro` and export `getStaticPaths()` for SSG, or use SSR mode. +- **Middleware**: Use `src/middleware.ts` for auth, logging, and request/response manipulation. + +## CLI & Workflow +- `npx astro dev`: Start local development server. +- `npx astro build`: Build production site. +- `npx astro check`: Run type-checking and diagnostics. +- `npx astro add `: Add official or community integrations (e.g., `svelte`, `tailwind`). +- `npx astro sync`: Generate TypeScript types for content collections and configurations. + +## Best Practices +- **Prefer SSG**: Build for performance whenever possible. +- **Optimize Assets**: Use `` component for automatic optimization. +- **Styling**: Prefer Tailwind or scoped CSS within `.astro` components. +- **SSR Optimization**: For Cloudflare/Edge deployments, keep dependencies lean to minimize bundle size. + +## Project Structure +``` +src/ +├── components/ # Reusable UI components +├── layouts/ # Base HTML templates +├── pages/ # Route files (required) +├── content/ # Markdown/Data collections +└── middleware.ts # Auth/Request logic +``` diff --git a/.agent/skills/cloudflare/SKILL.md b/.agent/skills/cloudflare/SKILL.md new file mode 100644 index 00000000..d746271a --- /dev/null +++ b/.agent/skills/cloudflare/SKILL.md @@ -0,0 +1,54 @@ +--- +name: cloudflare +description: Best practices for Cloudflare Workers, Durable Objects, and infrastructure (D1, R2, KV). +--- + +# Cloudflare Infrastructure Skill + +Use this skill when developing serverless functions, stateful backends, or managing Cloudflare resources. + +## Durable Objects (Stateful Coordination) + +### 1. Design Patterns +- **Atomic Entities**: Create one Durable Object per logical unit (e.g., chat room, user session, document). +- **SQLite Storage**: Use the built-in SQLite for transactional, strongly consistent storage. +- **Hibernatable WebSockets**: Use for real-time applications to save costs by allowing objects to hibernate while idle. + +### 2. Best Practices +- **Persistence**: Use `storage.put()` or SQL transactions for data you cannot lose. +- **Concurrency**: Use `blockConcurrencyWhile()` sparingly. DOs are single-threaded per instance, which prevents race conditions. +- **Initialization**: Run migrations and setup logic in the constructor or an `init()` method. + +## Workers & Cloudflare Pages + +### 1. API & Performance +- **Lean Bundles**: Keep dependencies minimal for fast cold starts. +- **KV for Config**: Use Cloudflare KV for global configuration or data with high read-concurrency. +- **R2 for Assets**: Store large media and binary data in R2 buckets. + +### 2. Security & Compliance +- **Secrets Management**: Use `wrangler secret put` for API keys and sensitive environment variables. +- **Turnstile**: Integrate Cloudflare Turnstile for bot protection on sensitive routes. + +## Local Development (Wrangler) +- `npx wrangler dev`: Run locally with Miniflare simulation. +- `npx wrangler deploy`: Deploy to Cloudflare. +- `npx wrangler d1 migrations build `: Create database migrations. + +## Code Patterns + +**Durable Object RPC:** +```ts +export class MyObject extends DurableObject { + async getData() { + return await this.ctx.storage.get("data"); + } +} +``` + +**SQL Injection Protection (D1):** +```ts +const { results } = await env.DB.prepare( + "SELECT * FROM users WHERE id = ?" +).bind(userId).all(); +``` diff --git a/.agent/skills/defi-streaming-mechanics/SKILL.md b/.agent/skills/defi-streaming-mechanics/SKILL.md index 16ff6aeb..7081541e 100644 --- a/.agent/skills/defi-streaming-mechanics/SKILL.md +++ b/.agent/skills/defi-streaming-mechanics/SKILL.md @@ -30,7 +30,18 @@ To ensure "Charged Regardless" behavior (Anti-gaming): - *Fix*: Detailed accounting would require a centralized "Tick Server", which reduces decentralization. -## 4. Implementation Checklist +## 4. Virtual Escrow (Cloudflare Durable Objects) +To avoid excessive ledger fees and latency: +- **Off-Chain Accounting**: Use a Cloudflare Durable Object to track per-second debt. +- **Heartbeat**: If the user's connection drops, the DO stops the session immediately, limiting "unpaid" listening to a few seconds. +- **Settlement**: The DO triggers a Soroban contract call only once per session or when a significant balance threshold is reached. + +## 5. State Expiration & Storage +- **Temporary Storage**: Use for transaction nonces and short-lived session IDs to keep contract rent low. +- **TTL Management**: Ensure the contract extends the TTL of active user data to prevent premature expiration during long listening sessions. + +## 6. Implementation Checklist - [ ] **Limit Loop**: Ensure `played_songs.length` does not exceed `MAX_OPS` (safe limit: 50). - [ ] **Gas Estimation**: Ensure Deposit covers not just the Stream Cost but also the `Rent/Gas` for the Settlement Tx. -- [ ] **Dust**: Handle cases where `time_listened` < 1 second (Micro-payments below minimum granularity). +- [ ] **Dust**: Handle cases where `time_listened` < 1 second. +- [ ] **DO Heartbeat**: Implement client-side `ping` to the Durable Object every 5 seconds. diff --git a/.agent/skills/remotion/SKILL.md b/.agent/skills/remotion/SKILL.md index a75f2ce5..09dbe6d3 100644 --- a/.agent/skills/remotion/SKILL.md +++ b/.agent/skills/remotion/SKILL.md @@ -58,7 +58,21 @@ When asking the agent to create animations, use this structured approach: * "Use `z-transform` for depth." * "Rotate X 15deg to give perspective." -## Code Patterns +## Code Patterns & Best Practices + +### Animation Rules +- **Frame-Driven**: Always derive values from `useCurrentFrame()` and `useVideoConfig()`. +- **NO SIDE EFFECTS**: Do not use CSS animations, `setTimeout`, or `requestAnimationFrame`. +- **Interpolation**: Use `interpolate()` with `extrapolateRight: "clamp"` to prevent values from exceeding bounds. +- **Springs**: Use `spring()` for natural motion. Map the 0-1 output to properties using `interpolate()`. + +### Layout & Sequencing +- **Sequences**: Use `` with `from` and `durationInFrames`. +- **Series**: Use `` for consecutive segments. Use `` or negative `offset` for overlaps. +- **Transitions**: Use `` from `@remotion/transitions` for fullscreen scene changes. +- **Asset Loading**: Always use `staticFile('path/to/asset')` for files in the `public/` folder. + +## Essential Code Snippets **Interpolation:** ```tsx @@ -68,23 +82,40 @@ const opacity = interpolate(frame, [0, 30], [0, 1], { }); ``` -**Springs:** +**Advanced Springs:** ```tsx const { fps } = useVideoConfig(); +const frame = useCurrentFrame(); const scale = spring({ frame, fps, - config: { damping: 200 }, + config: { damping: 12, stiffness: 100, mass: 1 }, + durationInFrames: 30, // Stretch/compress the spring }); +const mappedScale = interpolate(scale, [0, 1], [0.8, 1]); +``` + +**Sequencing & Series:** +```tsx + + + + + + + + ``` -**Sequencing:** -Use `` to time events: +**Asset Management:** ```tsx - - - - - - +import { staticFile, Audio, Video, Img } from "remotion"; + +const MyComponent = () => ( + <> +