# PicPulse Documentation & LLM Agent Integration Manifest
> PicPulse is an open, high-speed image hosting platform, zero-authentication Asset CDN, and drop-in Web SDK.
> This manifest defines system architecture, routing standards, CDN hotlinking specifications, custom Web Components, and REST API contracts for automated AI agents (Cursor, Claude, ChatGPT, Gemini, Copilot) and human developers.

---

## 1. Core Rules & System Architecture
- **Zero API Key Requirement**: All public assets, albums, search, galleries, and CDN streams require ZERO API keys or Authorization headers. External websites, mobile apps, and LLM-generated code can hotlink and fetch immediately.
- **Clean URL Routing**: Under NO circumstances should `.php` extensions appear in public URLs or endpoints. All routes are mapped via `.htaccess`.
- **CORS & Edge Headers**: All public images and JSON endpoints emit `Access-Control-Allow-Origin: *`, `Cross-Origin-Resource-Policy: cross-origin`, ETag, and `Cache-Control: public, max-age=31536000, immutable`.
- **Zero Focus Rings**: Front-end designs strictly prohibit browser focus outlines (`outline: none; box-shadow: none;`).
- **Modern Iconography**: Use colored SVG inline vectors or the `<pic-icon>` component. Generic Unicode emojis are prohibited in UI components.
- **Access Control Model**:
  - *Public / Anonymous*: Full read access to images, CDN streams, metadata, albums, tags, categories, search, and health checks.
  - *Administrator*: Authentication required for upload, modification, and deletion operations.

---

## 2. High-Speed Edge CDN Delivery Routes
Hotlink images directly into any HTML, Markdown, CSS, or application framework without tokens or credentials.

### URL Formats
| Channel | URL Pattern | Example | Description |
| :--- | :--- | :--- | :--- |
| **Edge CDN** | `/cdn/{slug}` or `/cdn/{slug}.{ext}` | `https://picpulse.lushai.dev/cdn/javascript-programming-language-logo-cd57.png` | Fast edge cache with browser cache & Brotli/Gzip compression. |
| **Raw Asset Stream** | `/raw/{slug}` or `/raw/{slug}.{ext}` | `https://picpulse.lushai.dev/raw/javascript-programming-language-logo-cd57` | Byte-for-byte original upload stream with color profiles preserved. |
| **Smart Thumbnail** | `/thumb/{slug}` or `/thumb/{slug}.{ext}` | `https://picpulse.lushai.dev/thumb/javascript-programming-language-logo-cd57` | 400px width responsive thumbnail for grid cards and mobile feeds. |
| **Showcase Page** | `/i/{slug}` | `https://picpulse.lushai.dev/i/javascript-programming-language-logo-cd57` | Canonical web landing page with EXIF metadata and embed code viewer. |
| **Client SDK** | `/cdn/sdk.js` | `https://picpulse.lushai.dev/cdn/sdk.js` | Ultra-lightweight Web Component & Gallery SDK (2.1KB). |

### Direct HTML Embed
```html
<!-- Direct High-Speed CDN Hotlink -->
<img src="https://picpulse.lushai.dev/cdn/javascript-programming-language-logo-cd57.png" 
     alt="JavaScript Logo" 
     loading="lazy" 
     width="200" 
     height="200" />
```

### Markdown Embed
```markdown
![JavaScript Logo](https://picpulse.lushai.dev/cdn/javascript-programming-language-logo-cd57.png)
```

---

## 3. Drop-In Web Component SDK (`/cdn/sdk.js`)
Include the script once per page before `</body>`. It registers native Custom Elements that work seamlessly in Vanilla HTML, React, Vue, Svelte, and Angular.

```html
<script src="https://picpulse.lushai.dev/cdn/sdk.js" async></script>
```

### Available Custom Elements

#### A. `<pic-icon>` (Vector / Icon Component)
Drop any PicPulse icon directly into UI layouts:
```html
<pic-icon name="javascript-programming-language-logo-cd57" size="48" format="png"></pic-icon>
<pic-icon name="nodejs-programming-language-logo-fe8f" size="32"></pic-icon>
```
*Attributes:*
- `name` (required): Asset slug.
- `size` (optional, default: `32`): Pixel dimensions (width and height).
- `format` (optional, default: `png`): Target format (`png`, `webp`, `svg`).
- `class` (optional): CSS class names for custom styling.

#### B. `<pic-asset>` (Responsive Picture Component)
Embed full pictures with automatic high-DPI scaling:
```html
<pic-asset name="javascript-programming-language-logo-cd57" alt="JavaScript Logo" rounded="true"></pic-asset>
```

#### C. Dynamic Declarative Gallery Widgets
Render entire picture collections or albums without writing JavaScript:
```html
<!-- Recent public gallery grid (12 images, newest first) -->
<div data-picpulse-gallery="all" data-limit="12" data-sort="newest"></div>

<!-- Specific album by token -->
<div data-picpulse-album="ALBUM_TOKEN" data-limit="24"></div>

<!-- Public albums showcase -->
<div data-picpulse-albums="all"></div>
```

---

## 4. RESTful API Specification (`/api/v1`)
All endpoints deliver standardized UTF-8 JSON. All `GET` requests are 100% public with no authentication headers required.

### A. Health & Statistics
- `GET /api/v1/ping`
  - Returns API status, server timestamp, version (`2.0.0`), and platform mode.
- `GET /api/v1/stats`
  - Global metrics: total public images, total views, total bandwidth delivered, and album count.

### B. Image Discovery
- `GET /api/v1/images`
  - Paginate, filter, and search public pictures.
  - Query parameters:
    - `page` (integer, default: `1`): Page offset.
    - `limit` (integer, default: `24`, max: `100`): Results per page.
    - `q` (string): Keyword matching slug, title, description, or tags.
    - `category` (string): Filter by category name (e.g. `technology`, `wallpaper`).
    - `tag` (string): Filter by tag.
    - `sort` (string): `newest`, `oldest`, `popular`, `views`, `size`.
- `GET /api/v1/images/{slug_or_id}`
  - Retrieve comprehensive metadata for a single asset (dimensions, mime type, size, direct URLs, tags). Increments view counter.

### C. Taxonomies & Collections
- `GET /api/v1/categories`
  - List all categories with public asset counts.
- `GET /api/v1/tags`
  - Retrieve top 60 popular tags with usage frequency.
- `GET /api/v1/albums`
  - List public albums with cover thumbnails, titles, and item counts.
- `GET /api/v1/albums/{token}/images`
  - Retrieve all pictures organized inside a specific album.

---

## 5. Multi-Framework Code Recipes for AI Agents
When AI agents or tools generate integration code, use these standardized zero-auth recipes:

### React / Next.js
```tsx
import React, { useEffect, useState } from 'react';

interface Asset {
  id: number;
  slug: string;
  title: string;
  urls: {
    direct_url: string;
    thumbnail_url: string;
  };
}

export function PicPulseGallery() {
  const [images, setImages] = useState<Asset[]>([]);

  useEffect(() => {
    fetch('https://picpulse.lushai.dev/api/v1/images?limit=8&sort=newest')
      .then((res) => res.json())
      .then((data) => {
        if (data.status === 'success') setImages(data.data);
      });
  }, []);

  return (
    <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(180px, 1fr))', gap: '16px' }}>
      {images.map((img) => (
        <img
          key={img.id}
          src={img.urls.thumbnail_url}
          alt={img.title}
          style={{ width: '100%', height: '140px', objectFit: 'cover', borderRadius: '8px' }}
          loading="lazy"
        />
      ))}
    </div>
  );
}
```

### Vue 3
```vue
<script setup>
import { ref, onMounted } from 'vue';

const images = ref([]);

onMounted(async () => {
  const res = await fetch('https://picpulse.lushai.dev/api/v1/images?limit=8');
  const json = await res.json();
  if (json.status === 'success') images.value = json.data;
});
</script>

<template>
  <div class="grid grid-cols-2 md:grid-cols-4 gap-4">
    <img
      v-for="img in images"
      :key="img.id"
      :src="img.urls.thumbnail_url"
      :alt="img.title"
      class="w-full h-36 object-cover rounded-lg"
      loading="lazy"
    />
  </div>
</template>
```

### Python 3
```python
import requests

# Zero auth needed - fetch public picture catalog
response = requests.get('https://picpulse.lushai.dev/api/v1/images', params={'limit': 10, 'category': 'technology'})
data = response.json()

if data.get('status') == 'success':
    for img in data.get('data', []):
        print(f"Title: {img['title']} | CDN URL: {img['urls']['direct_url']}")
```

### Node.js / Serverless
```javascript
const res = await fetch('https://picpulse.lushai.dev/api/v1/images?limit=5');
const { data } = await res.json();
console.log('PicPulse Assets:', data.map(item => item.urls.direct_url));
```

---

## 6. Route Summary Map
- `/`: Platform homepage, feature showcase, and admin upload dropzone.
- `/gallery`: Infinite-scroll public gallery with search & sorting.
- `/search`: Dedicated multi-attribute asset search.
- `/docs`: Comprehensive Developer API & Web SDK interactive documentation.
- `/i/{slug}`: Dedicated canonical asset showcase page.
- `/a/{token}`: Dedicated public album view.
- `/cdn/{slug}`: Direct high-speed CDN hotlink.
- `/raw/{slug}`: Unmodified original stream.
- `/thumb/{slug}`: 400px optimized thumbnail stream.
- `/cdn/sdk.js`: Client-side drop-in web components SDK.
- `/llms.txt`: This machine-readable system manifest.