diff --git a/AGENTS.md b/AGENTS.md index 5a1a9b1..43bf9aa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,40 +1,26 @@ -# AGENTS.md — Component-Only Architecture Rules & System Directives +# AGENTS.md — Architecture Rules & Engineering Conventions -## 1. Single Source of Truth Components +## 1. Single Source of Truth UI Components -- All UI design styles are designed once as reusable components in `components/ui/` and `components/layout/`. -- Pages must never implement isolated, inline styles or custom ad-hoc styling blocks. -- Spacing, colors, fonts, borders, buttons, cards, modals, and tables are defined centrally. Any design token alteration automatically cascades across all pages. +- All reusable UI primitives and layout shells are maintained in `components/ui/` and `components/layout/`. +- Pages assemble shared components (`PageShell`, `AdminPageHeader`, `SettingsPanel`, `Panel`, `StatStrip`, `Table`, `Button`, `Input`, `Modal`) rather than introducing isolated ad-hoc styling. +- Typography, spacing, colors, and borders use centralized CSS variables in `app/globals.css`. -## 2. Decoupled Runtime Split +## 2. Decoupled Runtime Architecture -- **Port 3000**: Next.js App Router (Frontend UI, `/vcon/*` admin console, streaming CSV export `/api/export`). -- **Port 4000**: Express.js + Socket.IO process (WebSocket handshake, JWT verification, real-time ingestion). -- **Socket.IO Rule**: Socket.IO must never reside inside Next.js serverless route handlers. +- **Port 3000 (`web`)**: Next.js 15 App Router serving the public overview, `/vcon/*` administration console, authenticated HTTP ingestion (`POST /api/events`), and streaming CSV/JSON exports (`GET /api/export`). +- **Port 4000 (`ingestion`)**: Dedicated Express.js + Socket.IO service (`server/index.js`) handling WebSocket handshakes, client JWT authentication, rate limiting, idempotency deduplication, and batch CSV persistence. +- **Socket.IO Boundary**: Socket.IO connections are handled exclusively by the Port 4000 service and never inside Next.js serverless route handlers. -## 3. Data Storage Rules +## 3. Data Storage & Persistence Rules -- **Collected Realtime Data**: Strictly stored in rotated CSV files at `/storage/data/{clientId}/{YYYY-MM-DD}.csv`. -- **Zero Database Inserts**: Per-row DB inserts are prohibited for collected data streams. -- **File Rotation**: Rotates daily or upon reaching 100MB (`-part2.csv`). -- **Redis / In-Memory Buffer**: Aggregates batches (500 events or 2000ms timer) before flushing to disk. -- **PostgreSQL / Prisma**: Exclusively dedicated to metadata, SDK registrations, and admin settings. +- **Partitioned CSV Event Storage**: Collected events are buffered in memory and flushed in batches to `/storage/data/{clientId}/{YYYY-MM-DD}.csv`. +- **Zero Per-Row Database Inserts**: Event telemetry streams are never inserted per-row into PostgreSQL. +- **File Rotation & Pruning**: CSV files rotate daily or when reaching the configured size threshold (`fileRotationMb`, default `100MB`, creating `-part2.csv`), and expired partitions are pruned according to `autoPruneDays`. +- **PostgreSQL Metadata Store (`pg`)**: PostgreSQL is used strictly for administrator accounts (`admin_users`), login attempt tracking (`admin_login_attempts`), registered SDK client credentials (`client_sdks`), and platform configuration (`admin_settings`). ## 4. Design & Typography Tokens - **Font Stack**: `"Segoe UI", "Segoe UI Web", system-ui, -apple-system, "Helvetica Neue", sans-serif`. -- **Border Radius**: `--radius: 0rem` strictly across all shadcn and custom UI components. -- **Shadows**: None. Clean, soft, compact flat design with subtle 1px borders. - -## 5. Private Development Notes - -- The root `notes/` directory is local-only and must remain ignored by Git. -- `notes/` is exclusively for private development-time notes, plans, reports, and update/fix phase logs. Never put public-facing or publishable documentation, Markdown, or public information in this directory. -- Before starting any repository update, fix, or addition, record its report and plan in `notes/` first. Keep the relevant steps and phase status/logs updated there as work progresses. - -## 6. Phase Implementation & Fast Single-Pass Verification Rules - -- **Strict Scope Lock**: Every phase must only touch the files and targets locked in its phase specification. Never modify unrelated features or UI outside the active phase scope. -- **No Long Verification Loops**: Once a phase's code changes are applied, perform a single verification pass (`compile_applet` + `lint_applet`), update the `notes/` phase logs immediately, close the phase, and prepare for the next phase. -- **Zero Redundant Testing Loops**: Never run repetitive or unnecessary multi-round verification/test loops within the same phase. Implement the scoped patch cleanly, verify once, and close the phase directly. - +- **Border Radius**: `--radius: 0rem` across all UI components. +- **Shadows**: None (`--shadow: none`). Crisp 1px borders with dark and light theme support. diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..2042414 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,33 @@ +# Changelog + +All notable changes to **DataStack** are documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +--- + +## [1.0.0] — 2026-11-17 + +### Added +- **Decoupled Dual-Runtime Architecture**: + - Next.js 15 App Router (**Port 3000**) serving the public overview, `/vcon/*` administration console, authenticated REST ingestion (`POST /api/events`), and streaming dataset exports (`GET /api/export`). + - Dedicated Express + Socket.IO server (**Port 4000**) handling persistent WebSocket handshakes, `sync_data` single-event intake, and `batch_sync` batch ingestion. +- **PostgreSQL Control-Plane Persistence (`pg.Pool`)**: + - Automatic schema provisioning and persistence for `admin_users`, `admin_login_attempts`, `client_sdks`, and `admin_settings`. + - Live `SELECT 1` database health checks integrated into `/api/metrics` and `/vcon/dashboard`. +- **Partitioned CSV Storage & Retention Engine**: + - In-memory batch buffering (`DataBufferEngine` and Port 4000 queue) flushing to `/storage/data/{clientId}/{YYYY-MM-DD}.csv` on threshold (`batchFlushThreshold`) or timer (`batchFlushIntervalMs`). + - Automatic size-based file rotation (`{YYYY-MM-DD}-part2.csv`) at configurable `fileRotationMb` thresholds. + - Automatic retention pruning (`CSVStorageManager.pruneExpiredPartitions(autoPruneDays)`) for expired daily CSV partitions. +- **Client SDK Registry & Security Governance**: + - Per-client HMAC-SHA256 JWT token issuance, one-click key rotation, live revocation (`CLIENT_REVOKED`), and permanent client deletion (`DELETE /api/clients/[id]`). + - Per-client sliding-window rate limiting, payload byte-size guards (`maxPayloadSizeKb`), and 5-minute TTL idempotency deduplication with automatic memory cleanup. + - Automatic bulk client token re-signing (`SDKManager.resignAllClientTokensAsync()`) when the platform `jwtSecret` is updated in `/vcon/settings`. +- **Administrator Authentication & Session Hardening**: + - First-run setup flow (`/vcon/setup`) guarded by `DATASTACK_ADMIN_SETUP_KEY`. + - Node.js `crypto.scrypt` password hashing, timing-safe credential verification, and 5-attempt / 15-minute brute-force login lockout. + - WebCrypto HMAC-SHA256 session cookies (`8h` standard / `30d` Remember me) with preserved session TTL on profile updates (`PUT /api/auth/profile`). +- **Official Python SDK (`datastack-sdk` v1.0.0)**: + - Pip-installable `DataStackClient` with JWT handshake authentication, automatic reconnection, and `threading.Event` acknowledgment synchronization for `sync()` and `batch_sync()`. +- **Docker Compose & Coolify Production Stack**: + - Multi-stage Dockerfiles (`Dockerfile.web`, `Dockerfile.server`, `Dockerfile.proxy`), Nginx WebSocket/HTTP reverse proxy, and shared `datastack-data` and `pgdata` volumes. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..d095ded --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,43 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and maintainers of **DataStack** and the **[Vib Tools](https://vib.tools/)** open-source community pledge to make participation in our project and community a harassment-free, constructive, and welcoming experience for everyone, regardless of background, experience level, gender identity, disability, ethnicity, religion, or nationality. + +## Our Standards + +Examples of behavior that contributes to a positive, productive environment include: + +- Demonstrating empathy, respect, and constructive communication toward other contributors and users. +- Giving and gracefully accepting technical feedback focused on code quality, maintainability, and clarity. +- Focusing on practical solutions that benefit users and the broader open-source community. +- Respecting repository architecture boundaries, documentation standards, and security policies. + +Examples of unacceptable behavior include: + +- Harassment, personal attacks, trolling, insulting, or derogatory comments. +- Publishing others' private information (such as physical or electronic addresses) without explicit permission. +- Submitting malicious code, spam, or intentionally disruptive pull requests/issues. +- Other conduct which could reasonably be considered inappropriate in a professional technical community. + +## Enforcement Responsibilities + +Project maintainers at **Vib Tools** are responsible for clarifying and enforcing standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies within all project spaces (GitHub repositories, issues, pull requests, discussions, and official communication channels) and also applies when an individual is officially representing the project or community in public spaces. + +## Enforcement & Contact + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the **Vib Tools** team at: + +- **Support & Moderation Email**: [support@vibtools.io](mailto:support@vibtools.io) +- **General Inquiries**: [hello@vibtools.io](mailto:hello@vibtools.io) +- **Website**: [https://vib.tools/](https://vib.tools/) + +All complaints will be reviewed and investigated promptly and fairly. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..447959d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,68 @@ +# Contributing to DataStack + +Thank you for your interest in contributing to **DataStack**, an open-source, self-hosted real-time telemetry and event logging platform developed by **[Vib Tools](https://vib.tools/)**. + +We welcome bug reports, documentation improvements, and focused code contributions that align with the project's architecture and engineering standards. + +--- + +## 1. Core Architectural Rules + +Before submitting a pull request, please review [`AGENTS.md`](./AGENTS.md) and ensure your changes respect these core boundaries: + +1. **Single-Source-of-Truth UI Components (`components/ui/` & `components/layout/`)** + - All `/vcon/*` and public views assemble shared primitives (`PageShell`, `AdminPageHeader`, `SettingsPanel`, `Panel`, `StatStrip`, `Table`, `Button`, `Input`, `Modal`). + - Do not introduce isolated inline styles or non-zero border-radius/shadow overrides (`--radius: 0rem`, `--shadow: none`). +2. **Decoupled Dual-Runtime Architecture** + - **Port 3000 (`web`)**: Next.js 15 App Router serving the UI, `/vcon/*` administration console, `POST /api/events`, and `GET /api/export`. + - **Port 4000 (`ingestion`)**: Express + Socket.IO server (`server/index.js`) handling WebSocket handshakes, rate limits, idempotency, and batch CSV flushing. + - Never embed Socket.IO server handlers inside Next.js serverless routes. +3. **Storage & Database Separation** + - Collected telemetry and event payloads are written exclusively in batches to partitioned CSV files under `/storage/data/{clientId}/{YYYY-MM-DD}.csv`. + - PostgreSQL (`pg`) is used strictly for administrator accounts (`admin_users`), login lockout tracking (`admin_login_attempts`), registered SDK clients (`client_sdks`), and platform settings (`admin_settings`). + +--- + +## 2. Local Development Workflow + +1. **Fork & Clone the Repository** + ```bash + git clone https://github.com/vibtoolshq/datastack.git + cd datastack + npm install + ``` +2. **Create a Feature or Fix Branch** + ```bash + git checkout -b fix/short-description + ``` +3. **Run the Development Services** + ```bash + # Terminal 1: Next.js Web UI & Admin Console (Port 3000) + npm run dev + + # Terminal 2: Socket.IO Ingestion Service (Port 4000) + npm run server + ``` +4. **Verify Build & Lint Checks** + ```bash + npm run lint + npm run build + ``` + +--- + +## 3. Pull Request Checklist + +- [ ] Changes are focused on a single bug fix, improvement, or documented feature. +- [ ] `npm run lint` and `npm run build` pass with zero errors. +- [ ] Documentation (`README.md` or relevant `manifest.md`) is updated if behavior or configuration changed. +- [ ] No runtime CSV files (`storage/data/*`) or private environment secrets (`.env`) are committed. + +--- + +## 4. Contact & Support + +- **General Inquiries**: [hello@vibtools.io](mailto:hello@vibtools.io) +- **Technical & Product Support**: [support@vibtools.io](mailto:support@vibtools.io) +- **GitHub Organization**: [https://github.com/vibtoolshq](https://github.com/vibtoolshq) +- **Website**: [https://vib.tools/](https://vib.tools/) diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..6d0977d --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Vib Tools (https://vib.tools/) + +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. diff --git a/README.md b/README.md index 2789727..1caa829 100644 --- a/README.md +++ b/README.md @@ -1,65 +1,338 @@ -# DataStack — Self-Hosted Universal Realtime Data Collection Platform +# DataStack — Open-Source Self-Hosted Real-Time Telemetry & Event Logging Platform -DataStack is a high-throughput, self-hosted data collection platform designed for high-frequency event ingestion over WebSockets with buffered batch persistence to CSV. +> **Practical software for real workflows.** Stream structured events over WebSockets and REST, buffer batches in memory, and persist clean, portable CSV datasets with full operational control. -## Architecture +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE) +[![Next.js 15](https://img.shields.io/badge/Next.js-15-black)](https://nextjs.org/) +[![Socket.IO 4.8](https://img.shields.io/badge/Socket.IO-4.8-010101)](https://socket.io/) +[![PostgreSQL 16](https://img.shields.io/badge/PostgreSQL-16-336791)](https://www.postgresql.org/) +[![Python SDK](https://img.shields.io/badge/Python_SDK-3.8%2B-3776AB)](./sdk-python) +[![Built by Vib Tools](https://img.shields.io/badge/Maintained%20by-Vib%20Tools-0f172a)](https://vib.tools/) -| Process | Port | Role | -| :---------------------- | :--- | :----------------------------------------------------------------------- | -| **Next.js App Router** | 3000 | Frontend UI, `/vcon/*` admin console, streaming CSV export `/api/export` | -| **Express + Socket.IO** | 4000 | WebSocket handshake, JWT client auth, event intake | -| **CSV Writer Worker** | — | In-memory buffer flush to CSV (`500 rows / 2s`) | +**DataStack** is a free, open-source, self-hosted real-time data collection and telemetry logging platform developed by **[Vib Tools](https://vib.tools/)**. It is designed for developers, technical teams, operators, and researchers who need a fast, inspectable, and maintainable system to collect structured JSON events over **Socket.IO WebSockets** and **HTTP REST APIs**, buffer them in memory, and persist them into daily and size-rotated **CSV partitions** without the complexity of heavyweight log clusters or per-row database bottlenecks. -## Data Persistence +--- -- **CSV Storage Path**: `/storage/data/{clientId}/{YYYY-MM-DD}.csv` -- **Schema**: `clientId, eventId, timestamp(ISO), payload(JSON)` -- **Rotation Rule**: Per-day OR 100MB threshold (whichever triggers first). -- **PostgreSQL**: Reserved for SDK client registration and admin settings. Runtime persistence is not wired yet; collected data is never inserted into PostgreSQL. +## Table of Contents -## Python SDK +1. [Why DataStack?](#why-datastack) +2. [Complete A–Z Feature Overview](#complete-az-feature-overview) +3. [System Architecture](#system-architecture) +4. [Admin Console (`/vcon/*`) Guide](#admin-console-vcon-guide) +5. [Quick Start (Local Development)](#quick-start-local-development) +6. [Environment Variables](#environment-variables) +7. [Python SDK (`datastack-sdk`)](#python-sdk-datastack-sdk) +8. [HTTP REST & WebSocket API Reference](#http-rest--websocket-api-reference) +9. [Docker Compose & Coolify Deployment](#docker-compose--coolify-deployment) +10. [Repository Structure](#repository-structure) +11. [Contributing & Security](#contributing--security) +12. [Author & Contact Information (Vib Tools)](#author--contact-information-vib-tools) +13. [License](#license) -Install the client: +--- + +## Why DataStack? + +Many teams need to collect high-frequency telemetry, service heartbeats, IoT sensor readings, or structured operational events, but face two extremes: +- Inserting thousands of events per second row-by-row into a relational database creates lock contention and storage bloat. +- Deploying distributed log clusters introduces high infrastructure costs and operational overhead. + +**DataStack solves this with a focused, transparent architecture:** +- **Zero Per-Row Database Inserts**: Incoming events are validated in memory, queued in a batch buffer, and appended in batches to partitioned CSV files (`/storage/data/{clientId}/{YYYY-MM-DD}.csv`). +- **PostgreSQL for Control-Plane Metadata Only**: PostgreSQL (`pg`) is dedicated strictly to administrator authentication (`admin_users`), brute-force login protection (`admin_login_attempts`), SDK client credentials (`client_sdks`), and platform configuration (`admin_settings`). +- **Portable, Inspectable Datasets**: Collected data lives in standard CSV partitions that can be searched in the browser, exported as streaming CSV or JSON archives, or loaded directly into Python, Pandas, DuckDB, R, or Excel. + +--- + +## Complete A–Z Feature Overview + +### 1. Real-Time Ingestion Engine (Port 4000 & Port 3000) +- **Dedicated Socket.IO Server (`Port 4000`)**: Handles persistent WebSocket connections (`sync_data` for single events and `batch_sync` for batch arrays) completely decoupled from Next.js serverless routes. +- **Authenticated HTTP Ingestion (`POST /api/events`)**: Supports standard HTTP POST ingestion authenticated via either a Client Bearer JWT token (`Authorization: Bearer `) or an active Administrator Session Cookie. +- **Sub-Millisecond In-Memory Batching**: Queues incoming events in memory and flushes to disk automatically when reaching `batchFlushThreshold` (default `500` events) or on a periodic timer (`batchFlushIntervalMs`, default `2000ms`). +- **On-Demand Cross-Process Buffer Flush**: Clicking **Flush Buffer** in `/vcon/storage` (`POST /api/storage`) or triggering an export (`GET /api/export`) flushes both the Next.js buffer and the Port 4000 Socket.IO buffer immediately. + +### 2. Partitioned CSV Storage & Lifecycle Management +- **Client & Date Partitioning**: Stores events under `/storage/data/{clientId}/{YYYY-MM-DD}.csv` with a consistent 4-column schema: `clientId,eventId,timestamp,payload`. +- **Automatic Size-Based File Rotation**: Automatically rotates active daily partitions to `{YYYY-MM-DD}-part2.csv`, `-part3.csv`, etc. when a file reaches `fileRotationMb` (default `100 MB`). +- **Automated Retention Pruning (`autoPruneDays`)**: Automatically removes expired daily CSV partitions older than the configured retention window (default `30` days). +- **Streaming CSV & JSON Exports**: Streams filtered datasets across any client and date range (`Today`, `7d`, `30d`, `All`, or custom dates) in either `.csv` or parsed `.json` format (`GET /api/export`). + +### 3. Client SDK Management & Access Governance +- **Per-Client JWT Credentials**: Issue unique `clientId`, secret key, and signed HMAC-SHA256 JWT tokens from `/vcon/clients`. +- **Configurable Per-Client Rate Limiting**: Enforce per-second sliding-window rate limits customized for each client (`client.rateLimit` capped by global `maxEventsPerSec`). +- **Payload Size Guard**: Rejects oversized event payloads exceeding `maxPayloadSizeKb` (default `100 KB`) before buffering. +- **5-Minute TTL Idempotency Deduplication**: Prevents duplicate event ingestion for identical `clientId:eventId` pairs within a 5-minute sliding window with automatic memory cleanup. +- **Live Key Rotation, Revocation & Deletion**: Rotate client JWT tokens, temporarily revoke/reactivate client access (`403 CLIENT_REVOKED`), or permanently delete client registrations with immediate enforcement across both HTTP and Socket.IO engines. +- **Automatic Token Re-Signing**: Updating the platform `jwtSecret` in `/vcon/settings` automatically re-signs active client tokens in PostgreSQL so client credentials stay synchronized. + +### 4. Security & Administrator Authentication +- **First-Run Installation Setup (`/vcon/setup`)**: Protected by a one-time installation key (`DATASTACK_ADMIN_SETUP_KEY`); permanently locks once the initial administrator account is created in PostgreSQL. +- **Scrypt Password Hashing & Timing-Safe Verification**: Administrator passwords are hashed with Node.js `crypto.scrypt` (`N=16384, r=8, p=1`) and verified using `timingSafeEqual`. +- **Brute-Force Login Lockout**: Tracks failed login attempts in PostgreSQL (`admin_login_attempts`), locking sign-in for 15 minutes after 5 failed attempts within a 15-minute window and returning a `Retry-After` header. +- **WebCrypto HMAC-SHA256 Sessions**: Issues `HttpOnly`, `SameSite=Lax` session cookies (`8 hours` standard or `30 days` with **Remember me**), preserving remaining session lifetime across profile updates. +- **Edge CSRF Protection**: Next.js Middleware (`middleware.ts`) enforces same-origin `Origin` / `Host` / `X-Forwarded-Host` verification on state-changing requests. + +--- + +## System Architecture + +```text ++-----------------------------------------------------------------------+ +| External SDK & HTTP Clients | +| Python SDK (datastack-sdk) | Browser Simulator / REST | ++------------------------------------+----------------------------------+ + | + +---------------+---------------+ + | Nginx Reverse Proxy (Port 80) | + +---------------+---------------+ + | + +-----------------------+-----------------------+ + | (/socket.io/*) | (/* & /api/*) + v v ++------------------------------------+ +------------------------------------+ +| Port 4000: Socket.IO Ingestion | | Port 3000: Next.js 15 App Router | +| - JWT Handshake & Live Revocation | | - /vcon/* Admin Console UI | +| - Rate Limit & Payload Guard | | - POST /api/events REST Ingestion | +| - 5-Min TTL Idempotency Map | | - GET /api/export CSV/JSON Stream | +| - In-Memory Batch Queue | | - Edge Middleware Auth & CSRF | ++-----------------+------------------+ +-----------------+------------------+ + | | + +-------------------+--------------------+ + | + +---------------------------+---------------------------+ + | | + v v ++------------------------------------+ +------------------------------------+ +| Shared CSV Volume (storage/data) | | PostgreSQL 16 Metadata Database | +| /storage/data/{clientId}/ | | - admin_users | +| {YYYY-MM-DD}.csv | | - admin_login_attempts | +| {YYYY-MM-DD}-part2.csv | | - client_sdks | ++------------------------------------+ | - admin_settings | + +------------------------------------+ +``` + +--- + +## Admin Console (`/vcon/*`) Guide + +| Route | View Name | Key Capabilities | +| :--- | :--- | :--- | +| `/vcon/dashboard` | **Dashboard** | View total stored rows, active Socket.IO connections, disk usage, buffered event counts, registered clients, and live recent events. | +| `/vcon/clients` | **Clients** | Register new SDK clients, copy signed JWT tokens, inspect per-client event counters and last-seen timestamps, rotate keys, revoke access, or delete clients. | +| `/vcon/data` | **Data Browser** | Search and filter persisted CSV rows by client and keyword, paginate through records, and inspect formatted JSON payloads. | +| `/vcon/export` | **Export** | Build custom exports filtered by client and date range (`Today`, `7d`, `30d`, `All`), preview row/byte counts, and stream `.csv` or `.json` downloads. | +| `/vcon/storage` | **Storage** | Monitor disk usage, total CSV partition files, active rotation rules (`100MB / Daily`), and trigger an immediate manual buffer flush. | +| `/vcon/settings` | **Settings** | Tune rate limits (`maxEventsPerSec`), payload size limits (`maxPayloadSizeKb`), flush thresholds, file rotation size, retention days (`autoPruneDays`), idempotency, and JWT secret. | +| `/vcon/sdk` | **Python SDK** | Select any registered client from the dropdown to generate a ready-to-run Python snippet pre-populated with that client's signed JWT token. | +| `/vcon/simulator` | **Simulator** | Emit single events or configurable batch test payloads directly from the browser to verify ingestion, rate limits, and CSV flushing. | +| `/vcon/profile` | **Admin Profile** | Update the administrator email address or password with current-password verification. | + +--- + +## Quick Start (Local Development) + +### Prerequisites +- **Node.js** `20+` and `npm` +- **PostgreSQL** `15+` (optional for local development; required for persistent multi-process production state) +- **Python** `3.8+` (optional, for using `datastack-sdk`) + +### 1. Clone & Install Dependencies + +```bash +git clone https://github.com/vibtoolshq/datastack.git +cd datastack +npm install +``` + +### 2. Configure Environment + +```bash +cp .env.example .env +``` + +### 3. Run the Platform + +```bash +# Terminal 1: Start Next.js Web UI & Admin Console (Port 3000) +npm run dev + +# Terminal 2: Start Express + Socket.IO Ingestion Service (Port 4000) +npm run server +``` + +Visit `http://localhost:3000` for the overview page or `http://localhost:3000/vcon/dashboard` for the Admin Console. + +--- + +## Environment Variables + +All environment variables are documented in [`.env.example`](./.env.example): + +| Variable | Default / Example | Description | +| :--- | :--- | :--- | +| `PORT` | `3000` | Next.js web and admin console port | +| `PORT_SOCKET` | `4000` | Express + Socket.IO ingestion server port | +| `DATABASE_URL` | `postgresql://user:pass@localhost:5432/datastack` | PostgreSQL connection string for control-plane tables | +| `DATASTACK_JWT_SECRET` | 32+ char secret | HMAC secret used to sign and verify Client SDK JWT tokens | +| `DATASTACK_ADMIN_SESSION_SECRET` | 32+ char secret | HMAC secret used to sign administrator session cookies | +| `DATASTACK_ADMIN_EMAIL` | `admin@datastack.dev` | Default administrator email pre-filled during initial setup | +| `DATASTACK_ADMIN_SETUP_KEY` | Random secret key | One-time installation key required at `/vcon/setup` | +| `INGESTION_INTERNAL_URL` | `http://127.0.0.1:4000` | Internal URL used by Next.js to query Port 4000 `/health` and `/internal/flush` | + +--- + +## Python SDK (`datastack-sdk`) + +The official Python SDK is located in [`./sdk-python`](./sdk-python) and uses `python-socketio` with `threading.Event` synchronization for reliable acknowledgments over both local and WAN connections. + +### Installation ```bash pip install ./sdk-python ``` -Usage: +### Usage Example ```python from datastack_sdk import DataStackClient -client = DataStackClient(server_url="http://localhost:4000", token="JWT_TOKEN") +client = DataStackClient( + server_url="http://localhost:4000", + token="YOUR_SIGNED_CLIENT_JWT_TOKEN", +) + if client.connect(): - client.sync({"metric": "load", "value": 42}) + # 1. Send a single event and wait for server acknowledgment + ack = client.sync( + data={ + "event_type": "sensor_reading", + "device_id": "env-node-04", + "temperature_c": 24.2, + "humidity_pct": 56.8, + }, + timeout=5.0, + ) + print("Single event ack:", ack) + + # 2. Send a batch of events in a single round-trip + batch_ack = client.batch_sync( + records=[ + {"metric": "cpu_usage", "value": 38.4, "unit": "%"}, + {"metric": "memory_used_mb", "value": 2048, "unit": "MB"}, + ], + timeout=10.0, + ) + print("Batch ack:", batch_ack) + client.disconnect() ``` -## Running the Platform +--- -```bash -# Terminal 1: Web Interface & Admin Console -npm run dev +## HTTP REST & WebSocket API Reference -# Terminal 2: Express Socket.IO Ingestion Engine -npm run server +### WebSocket Events (Port 4000) +Connect with Socket.IO handshake auth: `auth: { token: "" }`. + +- **`sync_data`**: Emit `{ eventId?, timestamp?, data }` -> Callback returns `{ success: true, eventId }` or `{ success: false, error }`. +- **`batch_sync`**: Emit `[{ eventId?, timestamp?, data }, ...]` -> Callback returns `{ success: true, processed, rejected, errors? }`. + +### REST Endpoints (Port 3000) + +| Method & Endpoint | Auth Required | Description | +| :--- | :--- | :--- | +| `POST /api/events` | Client Bearer JWT or Admin Cookie | Ingest a single event or `{ batch: [...] }` over HTTP | +| `GET /api/events` | Admin Session Cookie | List recent buffered and persisted events | +| `GET /api/clients` | Admin Session Cookie | List registered SDK clients and their signed JWT tokens | +| `POST /api/clients` | Admin Session Cookie | Register a new SDK client (`clientId`, `name`, `rateLimit`) | +| `PATCH /api/clients/[id]` | Admin Session Cookie | Rotate client token (`action: "regenerate_token"`) or update status/rate limit | +| `DELETE /api/clients/[id]` | Admin Session Cookie | Permanently delete a client registration | +| `GET /api/data` | Admin Session Cookie | Query paginated CSV records (`clientId`, `search`, `page`, `limit`) | +| `GET /api/export` | Admin Session Cookie | Stream filtered dataset export (`clientId`, `from`, `to`, `format=csv\|json`) | +| `GET /api/storage` | Admin Session Cookie | Get CSV partition file list and disk usage statistics | +| `POST /api/storage` | Admin Session Cookie | Flush both Next.js and Port 4000 buffers to disk immediately | +| `GET / PUT /api/settings` | Admin Session Cookie | Read or update platform runtime settings | +| `GET /api/metrics` | Admin Session Cookie | Consolidated system health, buffer, storage, and Socket.IO metrics | + +--- + +## Docker Compose & Coolify Deployment + +DataStack includes a production-ready Docker Compose stack in [`docker/docker-compose.yml`](./docker/docker-compose.yml): + +- **`proxy`**: Nginx reverse proxy on internal port `80` routing `/socket.io/` to `ingestion:4000` and all other traffic to `web:3000`. +- **`web`**: Standalone Next.js 15 container on port `3000` (runs as non-root user). +- **`ingestion`**: Express + Socket.IO container on port `4000` (runs as non-root user). +- **`postgres`**: PostgreSQL 16 with persistent `pgdata` volume. +- **`redis`**: Redis 7 with persistent `redisdata` volume. +- **`datastack-data` Volume**: Mounted at `/app/storage/data` in both `web` and `ingestion` so CSV partitions are shared seamlessly across containers. + +### Coolify Deployment Steps +1. Create a **Docker Compose** resource in Coolify pointing to your repository. +2. Set **Base Directory** to `/docker` and **Docker Compose Location** to `/docker/docker-compose.yml`. +3. Attach your HTTPS domain to the `proxy` service on port `80`. +4. Deploy the stack, open `https://your-domain.example/vcon/setup`, and enter your administrator email, password (8+ characters), and the generated `SERVICE_REALBASE64_64_ADMININSTALL` key from Coolify's environment variables. + +--- + +## Repository Structure + +```text +datastack/ +├── app/ # Next.js 15 App Router (landing page, /vcon/* console, /api/* routes) +├── components/ +│ ├── layout/ # Shared layout shells (MainLayout, Navbar, Sidebar, PageShell, SettingsPanel) +│ ├── sections/ # Modular page sections (Hero, Features, ClientsTable, ExportWorkspace, etc.) +│ └── ui/ # Single-source-of-truth UI primitives (Button, Input, Table, Modal, StatStrip) +├── core/ # Backend TypeScript modules (auth, Database, sdk, adminSettings, data, Storage, Security) +├── server/ # Dedicated Port 4000 Express + Socket.IO service & CSV batch worker +├── sdk-python/ # Official pip-installable Python client SDK (datastack-sdk) +├── storage/ # Partitioned CSV storage root (/storage/data/{clientId}/{YYYY-MM-DD}.csv) +├── docker/ # Production Dockerfiles, Nginx config, and docker-compose.yml +├── nginx/ # Local Nginx reverse proxy configuration +├── AGENTS.md # Architecture conventions and engineering rules +├── CONTRIBUTING.md # Contributor guidelines and development workflow +├── SECURITY.md # Security architecture and vulnerability reporting policy +├── CODE_OF_CONDUCT.md # Community standards and expectations +├── CHANGELOG.md # Release history and version notes +└── LICENSE # Open-Source MIT License ``` -## Production Containers +--- -## Coolify Deployment +## Contributing & Security -The repository includes a Docker Compose stack for a Coolify Git-based Docker Compose application. Coolify must be installed on a VPS with a domain and HTTPS configured. +- **Contributing**: Contributions, bug reports, and focused pull requests are welcome. Please read [CONTRIBUTING.md](./CONTRIBUTING.md) before submitting changes. +- **Security Policy**: To report a security vulnerability privately, please follow [SECURITY.md](./SECURITY.md) and contact **support@vibtools.io**. +- **Code of Conduct**: Participation in this project is governed by our [Code of Conduct](./CODE_OF_CONDUCT.md). -1. In Coolify, add a Docker Compose application from `https://gitlab.com/ivibtools/datastack.git`, branch `main`. -2. Set Base Directory to `/docker` and Docker Compose Location to `/docker/docker-compose.yml`. Confirm Coolify resolves the Compose file to the repository's `docker/docker-compose.yml`; do not change the Compose file path when changing the Base Directory. -3. Set `DATASTACK_ADMIN_EMAIL` in the application's Environment Variables. Coolify auto-generates the database name/password, JWT/session secrets, and one-time setup key from the `SERVICE_*` variables in Compose. `DATABASE_URL` is assembled internally from the generated database name/password. Do not override generated database identity values after first deployment. -4. In Domains, add the public HTTPS domain to service `proxy` on internal port `80`. Do not expose `web`, `ingestion`, Redis, or PostgreSQL directly. Coolify supplies proxy labels for the selected service. -5. Deploy and check service health and runtime logs in Coolify. +--- -The proxy sends `/` to Next.js and `/socket.io/` to the Socket.IO service over the private Compose network. The Settings page uses the current origin for a deployed WebSocket URL; local development on port 3000 still displays port 4000. +## Author & Contact Information (Vib Tools) -After deployment, open the first-run setup page. Copy the generated `SERVICE_REALBASE64_64_ADMININSTALL` key from Coolify into the setup form, confirm the `DATASTACK_ADMIN_EMAIL` configured for this deployment, and choose a strong password. The server accepts only that configured email, and initial admin setup closes permanently after the first account is stored. +**DataStack** is developed and maintained by **[Vib Tools](https://vib.tools/)** — a software organization building practical desktop applications, self-hosted software, automation tooling, developer utilities, reusable frameworks, and open-source projects for real workflows. -Compose mounts PostgreSQL's `pgdata` named volume, which is intended to survive normal rebuilds/redeploys; never remove the volume or change the generated database name to “reset” the app. Back up `pgdata` before database upgrades or maintenance. Changing the PostgreSQL password also requires updating the existing database role, not just its environment variable. The setup/login code uses PostgreSQL for the bootstrap admin credential only; Prisma-backed client/settings metadata remains P5 work. The `datastack-data` volume persists ingestion CSVs, but the web process does not yet read that volume; cross-process event visibility/shared storage remains P4. This stack has not yet been built or deployed on a Coolify VPS from this environment, so volume persistence still needs target-runtime verification. +| Channel | Details | +| :--- | :--- | +| **Organization / Author** | **Vib Tools** (`vibtools`) | +| **Official Website** | [https://vib.tools/](https://vib.tools/) | +| **GitHub Organization** | [https://github.com/vibtoolshq](https://github.com/vibtoolshq) | +| **GitLab Organization** | [https://gitlab.com/vibtools](https://gitlab.com/vibtools) | +| **General Inquiries** | [hello@vibtools.io](mailto:hello@vibtools.io) | +| **Technical & Product Support** | [support@vibtools.io](mailto:support@vibtools.io) | +| **Phone / WhatsApp** | `+880 1795-470603` (GMT+6 / Asia-Dhaka) | +| **Head Office** | Vib Tools HQ, 5660 Kochakata, Nageswari, Kurigram, Rangpur, Bangladesh | + +### Official Social & Community Profiles +- **X (Twitter)**: [https://x.com/vibtools](https://x.com/vibtools) +- **Facebook**: [https://www.facebook.com/vib.tools](https://www.facebook.com/vib.tools) +- **Instagram**: [https://www.instagram.com/vib.tools/](https://www.instagram.com/vib.tools/) +- **Reddit**: [https://www.reddit.com/user/VibTools/](https://www.reddit.com/user/VibTools/) +- **TikTok**: [https://www.tiktok.com/@vibtools](https://www.tiktok.com/@vibtools) + +--- + +## License + +Copyright © 2026 [Vib Tools](https://vib.tools/). Released under the **[MIT License](./LICENSE)**. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..d044709 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,52 @@ +# Security Policy + +**DataStack** is maintained by **[Vib Tools](https://vib.tools/)** with a focus on security-conscious engineering, clear operational boundaries, and user control. + +--- + +## Supported Versions + +| Version | Supported | +| :--- | :--- | +| `1.0.x` (Current `main`) | :white_check_mark: Supported | +| `< 1.0.0` | :x: Not Supported | + +--- + +## Built-In Security Architecture + +DataStack implements multiple layers of defense across both the Next.js Web/Admin runtime (**Port 3000**) and the Express + Socket.IO Ingestion service (**Port 4000**): + +1. **Administrator Authentication & Brute-Force Protection** + - Administrator passwords are salted and hashed using Node.js `crypto.scrypt` (`N=16384, r=8, p=1, keylen=64`) and verified using `crypto.timingSafeEqual`. + - Failed login attempts are tracked in PostgreSQL (`admin_login_attempts`), locking sign-in for 15 minutes after 5 failed attempts within a 15-minute window. + - Initial setup (`/vcon/setup`) requires a one-time `DATASTACK_ADMIN_SETUP_KEY` and closes permanently once the administrator account is created. +2. **Session & CSRF Protection** + - Administrator sessions use WebCrypto HMAC-SHA256 signed `HttpOnly`, `SameSite=Lax` cookies (`datastack_admin_session`). + - Next.js Edge Middleware (`middleware.ts`) enforces same-origin `Origin`, `Host`, and `X-Forwarded-Host` verification on state-changing requests. +3. **Client SDK Authentication & Live Revocation** + - Every Socket.IO connection and HTTP `POST /api/events` request requires a valid signed Client JWT token (or active Admin Session Cookie). + - Both Port 3000 and Port 4000 verify client status against PostgreSQL (`client_sdks`), immediately rejecting revoked clients (`403 CLIENT_REVOKED`) or superseded rotated tokens (`401 TOKEN_ROTATED`). +4. **Rate Limiting, Payload Guards & Idempotency** + - Per-client sliding-window rate limits (`client.rateLimit` capped by global `maxEventsPerSec`) protect against excessive event volume. + - Event payloads exceeding `maxPayloadSizeKb` (default `100 KB`) are rejected prior to buffering. + - A 5-minute TTL idempotency window deduplicates repeated `clientId:eventId` submissions. + +--- + +## Reporting a Vulnerability + +Please **do not** report sensitive security vulnerabilities in public GitHub issues. + +Instead, report suspected security issues privately to the Vib Tools security and support team: + +- **Security & Support Email**: [support@vibtools.io](mailto:support@vibtools.io) +- **General Contact**: [hello@vibtools.io](mailto:hello@vibtools.io) +- **Website**: [https://vib.tools/](https://vib.tools/) + +### What to Include in Your Report +1. A clear description of the vulnerability and the affected component (`web`, `ingestion`, `sdk-python`, or `docker`). +2. Step-by-step reproduction instructions or a minimal proof-of-concept. +3. The potential impact and any suggested remediation. + +We review all legitimate reports promptly and work with reporters to verify and resolve issues before public disclosure. diff --git a/app/vcon/manifest.md b/app/vcon/manifest.md index 51d21bb..3ba76fb 100644 --- a/app/vcon/manifest.md +++ b/app/vcon/manifest.md @@ -1,16 +1,17 @@ -# VCON Admin Console Manifest +# Admin Console (`/vcon/*`) Manifest ## Purpose -The `/vcon/*` route hosts the full administration control center for DataStack: -- **dashboard**: Realtime metrics, buffer queue, disk usage, quick simulation trigger -- **clients**: SDK registration, JWT handshake token creation, rate limits -- **data**: Live incoming stream inspector with client filters and search -- **export**: CSV dataset exporter and streaming downloads -- **storage**: Disk inspection of `/storage/data/{clientId}/{YYYY-MM-DD}.csv` partitions and flush triggers -- **settings**: Platform limits, rotation sizes, buffer thresholds, and JWT secret management -- **sdk**: Pip-installable Python SDK guide and pre-configured client code generator -- **simulator**: In-browser event emission and batch bursting tester. +The `/vcon/*` routes provide the administration interface for managing DataStack clients, inspecting event streams, configuring runtime parameters, and exporting stored CSV datasets. -## Conventions -- Standard URL handler for all inner pages so page refreshes never redirect to home. -- Zero-radius, zero-shadow compact UI styling using global tokens. +## Routes +- `dashboard/page.tsx`: Live ingestion metrics, active Socket.IO connection count, buffer utilization, and recent events table. +- `clients/page.tsx`: Client SDK registration, JWT credential issuance, key rotation, status revocation, and permanent client deletion. +- `data/page.tsx`: Paginated CSV event browser with client filtering, keyword search, and JSON payload inspection. +- `export/page.tsx`: Dataset export builder with date-range presets (`Today`, `7d`, `30d`, `All`) and streaming CSV/JSON downloads. +- `storage/page.tsx`: On-disk CSV partition inspector (`/storage/data/{clientId}/{YYYY-MM-DD}.csv`) with manual buffer flush controls. +- `settings/page.tsx`: Runtime configuration for rate limits, payload size bounds, buffer thresholds, file rotation size, retention pruning (`autoPruneDays`), and JWT secret. +- `sdk/page.tsx`: Python SDK integration guide that populates ready-to-run code snippets with any registered client's signed JWT token. +- `simulator/page.tsx`: Browser-based event generator for testing single and batch event ingestion pipelines. +- `profile/page.tsx`: Administrator email and password management with current-password verification. +- `login/page.tsx`: Administrator sign-in screen with brute-force lockout protection and optional 30-day session persistence. +- `setup/page.tsx`: First-run administrator initialization screen protected by `DATASTACK_ADMIN_SETUP_KEY`. diff --git a/components/layout/manifest.md b/components/layout/manifest.md index 10dab43..db619e1 100644 --- a/components/layout/manifest.md +++ b/components/layout/manifest.md @@ -1,15 +1,13 @@ -# Layout Components Module Manifest +# Layout Components Manifest ## Purpose -Global layout shell, navigation, top bar, and admin sidebar complying with compact, zero-border-radius, zero-shadow design system. +Global layout shells, navigation headers, and sidebars shared across the public overview and `/vcon/*` administration console. ## Components -- **Navbar.tsx**: Top titlebar with brand, quick links, runtime port indicator (:4000/:3000), and dark/light theme switcher. -- **Sidebar.tsx**: Dedicated `/vcon/` admin console sidebar with mobile drawer support, grouped telemetry & management links. -- **Footer.tsx**: System runtime status line with storage convention display and port allocations. -- **MainLayout.tsx**: Viewport-bounded responsive shell with mobile backdrop and scrolling main container. - -## Dependencies -- `components/ui` -- `next/link` -- `next/navigation` +- `MainLayout.tsx`: Responsive root shell pairing the top navigation bar, sidebar (for `/vcon/*` routes), and scrollable main content region. +- `Navbar.tsx`: Top navigation bar displaying the brand, quick links, dark/light theme toggle, and authenticated administrator controls. +- `Sidebar.tsx`: Collapsible `/vcon/*` administration navigation rail with mobile drawer support. +- `PageShell.tsx`: Standard page container used by all `/vcon/*` views, pairing `AdminPageHeader` with consistent vertical spacing. +- `AdminPageHeader.tsx`: Compact page header rendering the current route title and right-aligned action buttons. +- `SettingsPanel.tsx`: Two-column key/value configuration layout used by `/vcon/settings` and `/vcon/profile`. +- `Footer.tsx`: Compact status footer for public landing pages. diff --git a/components/sections/manifest.md b/components/sections/manifest.md index 1f3a2ca..3e7d09d 100644 --- a/components/sections/manifest.md +++ b/components/sections/manifest.md @@ -1,9 +1,15 @@ -# Sections Manifest +# Page Sections Manifest ## Purpose -Modular section blocks used in landing page and documentation views. +Modular feature sections used across the public landing page and `/vcon/*` administration views. -## Sections -- `Hero.tsx`: Headline, technical metrics, quick start buttons -- `Features.tsx`: Subsystem cards with icons and descriptions -- `Architecture.tsx`: Visual diagram of decoupled port 4000/3000 runtime and data flow. +## Components +- `Hero.tsx`: Public overview hero section with architecture highlights and quick navigation links. +- `Features.tsx`: Core platform capability cards (WebSocket ingestion, partitioned CSV storage, SDK management). +- `SdkSection.tsx`: Interactive Python SDK code preview on the landing page. +- `LandingAbout.tsx`: Deployment and storage architecture summary section. +- `AdminLogin.tsx`: Administrator sign-in form with theme switcher and session persistence toggle. +- `AdminSetup.tsx`: Initial administrator account creation form. +- `ClientsView.tsx`: Client management workspace with search, status filters, and registration modal. +- `ClientsTable.tsx`: Client registry table with credential display, key rotation, access revocation, and deletion modals. +- `ExportWorkspace.tsx`: CSV and JSON dataset export builder with client/date filtering and recent partition downloads. diff --git a/components/ui/manifest.md b/components/ui/manifest.md index 1447304..e506520 100644 --- a/components/ui/manifest.md +++ b/components/ui/manifest.md @@ -1,19 +1,20 @@ -# UI Components Module Manifest +# UI Primitives Manifest ## Purpose -Unified, zero-pill, zero-shadow compact UI design system following the DataStack design guidelines. +Single-source-of-truth UI component library implementing DataStack's compact, zero-border-radius, zero-shadow design system. ## Components -- **Button.tsx**: Standardised buttons with size variants (default 32px, sm 27px, xs 24px, icon 30px), zero border-radius, outline focus. -- **Input.tsx**: Inputs, Textareas, and Selects with consistent border token and Segoe UI typography. -- **Card.tsx**: Structured data container surfaces with zero radius, 1px subtle borders, and header/content/footer partitions. -- **Modal.tsx**: Accessible dialogs with key listener (Escape), backdrop blur, and flexible action footers. -- **Table.tsx**: Compact fixed data tables for real-time streams, client listings, and export jobs. -- **Form.tsx**: Form wrappers, switch toggles, and multi-column row layouts. -- **Text.tsx**: Typography engine providing hierarchy (h1, h2, h3, body, muted, dim, label, code, badge). -- **Icon.tsx**: Lucide-react wrapper for icon rendering. -- **Toast.tsx**: Real-time notification and error/success/warning report system. - -## Dependencies -- `lucide-react` -- `@/lib/utils` (clsx + tailwind-merge) +- `Button.tsx`: Action buttons with variants (`primary`, `secondary`, `ghost`, `danger`, `icon`) and sizes (`default`, `sm`, `xs`, `icon`). +- `Input.tsx`: Standardized `Input`, `Textarea`, and `Select` controls with compact mode and right-element slots. +- `Card.tsx`: Structured 1px-bordered surface containers (`Card`, `CardHeader`, `CardTitle`, `CardContent`, `CardFooter`). +- `Panel.tsx`: Titled section container with optional metadata badge and header action slot. +- `StatStrip.tsx`: Responsive 4-column metric strip used at the top of `/vcon/*` views. +- `Table.tsx`: Compact tabular data primitives (`TableWrap`, `Table`, `TableHeader`, `TableBody`, `TableRow`, `TableHead`, `TableCell`, `TableEmpty`). +- `Modal.tsx`: Accessible modal dialog with Escape key handling and action footer. +- `Form.tsx`: Form layout wrappers and `FormSwitch` boolean toggle control. +- `Pill.tsx`: Compact filter pill button for status and date-range selection. +- `CodeBlock.tsx`: Monospace syntax block for displaying SDK snippets and JSON payloads. +- `CopyButton.tsx`: Clipboard copy button with visual confirmation state. +- `Text.tsx`: Typography helper component for headings, labels, and inline code. +- `Icon.tsx`: Dynamic Lucide icon renderer. +- `Toast.tsx`: Toast notification provider (`useToast`) for operation feedback. diff --git a/core/Database/manifest.md b/core/Database/manifest.md index 4bfb301..001d406 100644 --- a/core/Database/manifest.md +++ b/core/Database/manifest.md @@ -1,12 +1,14 @@ # Database Engine Manifest ## Purpose -Database layer managing PostgreSQL schema via Prisma ORM. +Manages the shared PostgreSQL connection pool (`pg.Pool`), automatic metadata table initialization, and live database health probes (`core/Database/database.ts`). -## Absolute Constraint -PostgreSQL is utilized ONLY for: -1. Client SDK registrations and API keys -2. Admin settings and feature flags -3. System audit logs +## Managed PostgreSQL Tables +PostgreSQL is dedicated strictly to platform metadata and security state: +1. `admin_users`: Administrator account credentials (scrypt password hashes). +2. `admin_login_attempts`: Brute-force login attempt counters and lockout timestamps. +3. `client_sdks`: Registered SDK clients, signed JWT tokens, rate limits, status (`active` / `revoked`), and event counters. +4. `admin_settings`: Global runtime settings (`max_events_per_sec`, `max_payload_size_kb`, `batch_flush_threshold`, `batch_flush_interval_ms`, `file_rotation_mb`, `jwt_secret`, `enable_idempotency`, `auto_prune_days`). -**Collected realtime data is NEVER stored per-row in PostgreSQL.** It is stored exclusively in rotated CSV files at `/storage/data/{clientId}/{YYYY-MM-DD}.csv`. +## Storage Separation Rule +Collected event streams are **never** inserted per-row into PostgreSQL; they are written exclusively in batches to partitioned CSV files under `/storage/data/{clientId}/{YYYY-MM-DD}.csv`. diff --git a/core/Security/manifest.md b/core/Security/manifest.md index e53ad04..878568d 100644 --- a/core/Security/manifest.md +++ b/core/Security/manifest.md @@ -1,12 +1,9 @@ # Security Engine Manifest ## Purpose -Enforces client rate-limiting, event idempotency verification, and payload size bounds. +Enforces per-client sliding-window rate limits, payload size bounds, and event idempotency deduplication (`core/Security/security.ts`). -## Key Logic -- **Idempotency**: Drops duplicate `clientId + eventId` within a 5-minute TTL window. -- **Rate Limit**: Sliding per-second window configurable per client or globally. -- **Payload Guard**: Rejects payloads exceeding 100KB per event with explicit codes. - -## Dependencies -- Native Node.js `Buffer`, `Map` +## Key Responsibilities +- **Idempotency Deduplication**: Rejects duplicate `clientId:eventId` pairs within a 5-minute TTL window. +- **Sliding-Window Rate Limiter**: Enforces the lower of the client's configured `rateLimit` and the global `maxEventsPerSec` limit. +- **Payload Size Guard**: Rejects individual event payloads exceeding `maxPayloadSizeBytes` (default `100 KB`). diff --git a/core/Server/manifest.md b/core/Server/manifest.md deleted file mode 100644 index adda872..0000000 --- a/core/Server/manifest.md +++ /dev/null @@ -1,15 +0,0 @@ -# Server Runtime Manifest - -## Purpose -Express.js and Socket.IO server engine hosting WebSocket connections, JWT authentication handshakes, and event intake on port 4000. - -## Key Logic -- Initializes Express server on Port 4000 (decoupled from Next.js on Port 3000) -- Mounts Socket.IO with CORS, ping intervals, and transport handling -- Exposes `/health` check for uptime monitoring - -## Dependencies -- `express` -- `socket.io` -- `cors` -- `core/connector/socketHandler` diff --git a/core/Storage/manifest.md b/core/Storage/manifest.md index 11427b5..70d563d 100644 --- a/core/Storage/manifest.md +++ b/core/Storage/manifest.md @@ -1,14 +1,10 @@ -# Storage Engine Manifest +# CSV Storage Engine Manifest ## Purpose -File-based CSV storage engine. All collected data is persisted strictly to CSV files (zero per-row database inserts). +Partitioned CSV file storage engine (`core/Storage/csvStorage.ts`) responsible for writing, rotating, inspecting, and pruning collected event datasets on disk. -## Conventions -- **Path**: `/storage/data/{clientId}/{YYYY-MM-DD}.csv` -- **Schema**: `clientId, eventId, timestamp, payload` -- **Rotation**: Rotates per-day or when single file reaches 100MB limit (`-part2.csv`). -- **Batching**: Never writes per-event. Flushes buffered arrays using `json2csv` parser. - -## Dependencies -- `json2csv` -- Node.js `fs`, `path` +## Storage Conventions +- **Path Pattern**: `/storage/data/{clientId}/{YYYY-MM-DD}.csv` +- **Columns**: `clientId,eventId,timestamp,payload` +- **Size & Daily Rotation**: Creates a new daily file per client and rotates to `{YYYY-MM-DD}-part2.csv` when a file reaches `maxFileSizeBytes` (configurable via `fileRotationMb`, default `100MB`). +- **Retention Pruning**: `pruneExpiredPartitions(autoPruneDays)` automatically removes daily CSV partitions older than the configured retention period. diff --git a/core/adminSettings/manifest.md b/core/adminSettings/manifest.md index 4d54a81..0010bac 100644 --- a/core/adminSettings/manifest.md +++ b/core/adminSettings/manifest.md @@ -1,17 +1,15 @@ -# Admin Settings Manifest +# Admin Settings Engine Manifest ## Purpose -Global administrative configuration store and live subsystem parameter tuning. +Manages global runtime configuration (`core/adminSettings/settingsManager.ts`), persisting settings to the PostgreSQL `admin_settings` table and applying live updates across backend engines. ## Managed Parameters -- Ports: Ingestion (:4000) and Web (:3000) -- Rate limiting and maximum payload size bounds -- Buffer flush thresholds (count & timer) -- CSV rotation limits (100MB / per-day) -- JWT signature secret keys - -## Dependencies -- `core/Security/security` -- `core/data/buffer` -- `core/auth/jwt` -- `core/Storage/csvStorage` +- `serverPort` (`4000`) and `webPort` (`3000`) +- `maxEventsPerSec`: Default per-client throughput ceiling (events/sec) +- `maxPayloadSizeKb`: Maximum event payload size in kilobytes +- `batchFlushThreshold`: Number of queued events that triggers an immediate CSV flush +- `batchFlushIntervalMs`: Background timer interval for periodic CSV flushes +- `fileRotationMb`: Maximum CSV partition file size before rotating to `-part2.csv` +- `autoPruneDays`: Retention window in days for automatic CSV partition pruning +- `enableIdempotency`: 5-minute TTL duplicate event filtering toggle +- `jwtSecret`: HMAC secret used to sign and verify Client SDK JWT tokens (updating this automatically re-signs existing client tokens) diff --git a/core/apiEngine/manifest.md b/core/apiEngine/manifest.md index 4de4970..71804a8 100644 --- a/core/apiEngine/manifest.md +++ b/core/apiEngine/manifest.md @@ -1,9 +1,8 @@ # API Engine Manifest ## Purpose -Core administrative API services supplying telemetry, aggregation metrics, and export data feeds to Next.js route handlers. +Aggregates system health, buffer status, client statistics, and CSV storage metrics for the `/vcon/dashboard` administration console (`core/apiEngine/apiService.ts`). ## Responsibilities -- Aggregate telemetry across Buffer, CSV Storage, Sockets, and Security -- Filter and list CSV export datasets -- Provide consolidated administrative health payloads +- Queries the Port 4000 ingestion server (`${INGESTION_INTERNAL_URL}/health`) for live `activeSockets` and remote `bufferSize`. +- Combines remote Socket.IO metrics with local `DataBufferEngine`, `CSVStorageManager`, `SDKManager`, `SecurityEngine`, and `DatabaseEngine` health states. diff --git a/core/auth/manifest.md b/core/auth/manifest.md index 8eaf2dd..a78f62f 100644 --- a/core/auth/manifest.md +++ b/core/auth/manifest.md @@ -1,12 +1,9 @@ -# Core Auth Manifest +# Authentication Engine Manifest ## Purpose -JWT-based authentication engine for Client SDK connections during Socket.IO handshakes. +Provides authentication and session security for both Administrator Console users and Client SDK connections (`core/auth/*`). -## Key Logic -- Signs JWT with `clientId`, `rateLimit`, and timestamp. -- Verifies bearer tokens during Socket.IO connection handshake. -- Disconnects invalid or expired tokens immediately. - -## Dependencies -- `jsonwebtoken` +## Modules +- `jwt.ts`: Signs and verifies Client SDK JWT tokens (`clientId`, `name`, `rateLimit`) using `DATASTACK_JWT_SECRET` or the active `admin_settings.jwt_secret`. +- `adminSession.ts`: WebCrypto HMAC-SHA256 administrator session token signer/verifier (`datastack_admin_session` HTTP-only cookie) compatible with both Next.js Edge Middleware and Node.js route handlers. +- `adminUsers.ts`: PostgreSQL-backed administrator account store (`admin_users`) using `crypto.scrypt` password hashing, timing-safe verification, and brute-force login lockout tracking (`admin_login_attempts`). diff --git a/core/connector/manifest.md b/core/connector/manifest.md deleted file mode 100644 index d01f43d..0000000 --- a/core/connector/manifest.md +++ /dev/null @@ -1,17 +0,0 @@ -# Connector Engine Manifest - -## Purpose -Express + Socket.IO connection intake, WebSocket handshake validation, and real-time event router. - -## Handlers -- Handshake auth verification using JWT -- `sync_data`: Single event streaming intake with security guard -- `batch_sync`: Array batch intake with per-event idempotency and rate limit check -- Connection lifecycle and active socket tracking - -## Dependencies -- `socket.io` -- `core/auth/jwt` -- `core/Security/security` -- `core/data/buffer` -- `core/sdk/sdkManager` diff --git a/core/data/buffer.ts b/core/data/buffer.ts index 20a1a1d..9c499ed 100644 --- a/core/data/buffer.ts +++ b/core/data/buffer.ts @@ -18,6 +18,7 @@ interface BufferGlobalState { type BufferGlobals = typeof globalThis & { __dataStackBufferState?: BufferGlobalState; + __dataStackBufferShutdownRegistered?: boolean; }; const globals = globalThis as BufferGlobals; @@ -66,6 +67,19 @@ export class DataBufferEngine { void this.flush(); }, state.batchFlushIntervalMs); } + + if ( + typeof process !== 'undefined' && + typeof process.on === 'function' && + !globals.__dataStackBufferShutdownRegistered + ) { + globals.__dataStackBufferShutdownRegistered = true; + const flushOnExit = () => { + void this.flush().catch(() => undefined); + }; + process.on('SIGTERM', flushOnExit); + process.on('SIGINT', flushOnExit); + } } /** diff --git a/core/data/manifest.md b/core/data/manifest.md index 0527f2f..0c0b51c 100644 --- a/core/data/manifest.md +++ b/core/data/manifest.md @@ -1,12 +1,9 @@ -# Data Management Manifest +# Data Buffer Engine Manifest ## Purpose -In-memory and Redis buffer engine for high-throughput batching of collected events. +In-memory event batching engine (`core/data/buffer.ts`) that queues incoming events and flushes them in batches to partitioned CSV files on disk. -## Key Logic -- Buffers events in memory to prevent per-event disk I/O. -- Flushes batch to CSV Storage on threshold (500 items) or interval (2000ms). -- Delivers live events to UI subscribers for real-time monitoring. - -## Dependencies -- `core/Storage/csvStorage` +## Key Responsibilities +- Queues validated events in memory to avoid per-event disk I/O overhead. +- Automatically flushes queued batches to `CSVStorageManager.appendBatch()` when the queue reaches `batchFlushThreshold` (`500` events) or when the periodic flush timer (`batchFlushIntervalMs`, default `2000ms`) fires. +- Supports dynamic timer rescheduling via `setFlushInterval(intervalMs)` when updated in `/vcon/settings`. diff --git a/core/manifest.md b/core/manifest.md index 058d150..fc34817 100644 --- a/core/manifest.md +++ b/core/manifest.md @@ -1,15 +1,14 @@ -# Core Backend Engine Manifest +# Core Backend Modules Manifest ## Purpose -Modular backend subsystems for DataStack: -- `auth`: JWT verification and generation -- `connector`: Socket.IO intake and handshake handling -- `data`: In-memory and Redis buffer management -- `Storage`: CSV file partition writing and rotation -- `Security`: Rate limiter, payload validator, idempotency checker -- `sdk`: Client SDK registry and credentials -- `adminSettings`: Configuration state -- `Database`: PostgreSQL / Prisma schema metadata -- `notification`: System alerts and audit events -- `Server`: Express + Socket.IO process (Port 4000) -- `apiEngine`: Aggregated data providers for REST API +Core TypeScript backend engines powering authentication, client SDK management, event buffering, CSV partition storage, and PostgreSQL metadata persistence. + +## Submodules +- `auth/`: Client JWT signing/verification (`jwt.ts`), WebCrypto HMAC-SHA256 admin session tokens (`adminSession.ts`), and PostgreSQL scrypt admin user/lockout management (`adminUsers.ts`). +- `Database/`: Shared PostgreSQL connection pool (`pg.Pool`), automatic schema initialization (`client_sdks`, `admin_settings`), and live `SELECT 1` health checks (`database.ts`). +- `sdk/`: Client SDK registration, token rotation, status revocation, deletion, and event counters backed by PostgreSQL (`sdkManager.ts`). +- `adminSettings/`: Platform runtime configuration store backed by PostgreSQL with live propagation to security, buffer, and storage engines (`settingsManager.ts`). +- `data/`: In-memory event batching queue with configurable flush threshold and interval timer (`buffer.ts`). +- `Storage/`: Partitioned CSV writer (`/storage/data/{clientId}/{YYYY-MM-DD}.csv`), size-based file rotation (`-part2.csv`), and retention pruning (`csvStorage.ts`). +- `Security/`: Per-client sliding-window rate limiter, 5-minute TTL idempotency deduplication, and payload byte-size validation (`security.ts`). +- `apiEngine/`: Consolidated dashboard metrics aggregator combining local storage stats with Port 4000 `/health` telemetry (`apiService.ts`). diff --git a/core/notification/manifest.md b/core/notification/manifest.md deleted file mode 100644 index 42989f7..0000000 --- a/core/notification/manifest.md +++ /dev/null @@ -1,9 +0,0 @@ -# Notification Engine Manifest - -## Purpose -System-level alerts and event notification service for admin awareness. - -## Key Logic -- Records security violations (unauthorized JWT attempts, rate limits) -- Logs storage events (batch flushes, rotation to part files, CSV write failures) -- Real-time notification feed for `/vcon/` admin UI. diff --git a/core/sdk/manifest.md b/core/sdk/manifest.md index 3d50e9f..e64a087 100644 --- a/core/sdk/manifest.md +++ b/core/sdk/manifest.md @@ -1,12 +1,9 @@ -# SDK Management Manifest +# SDK Management Engine Manifest ## Purpose -Manages client SDK credentials, client registration, tokens, and client-level throughput rate limits. +Manages Client SDK registrations, JWT credentials, throughput rate limits, and activity counters (`core/sdk/sdkManager.ts`) backed by PostgreSQL (`client_sdks`). -## Key Logic -- Generates API keys and signed JWT client tokens. -- Tracks client registration status (active/revoked), event counters, and last-active timestamp. -- Allows immediate token revocation or rate limit reconfiguration. - -## Dependencies -- `core/auth/jwt` +## Key Responsibilities +- Registers new clients with unique secret keys and signed JWT tokens. +- Persists client status (`active` / `revoked`), per-client `rateLimit`, `totalEvents`, and `lastActive` timestamps in PostgreSQL `client_sdks`. +- Supports one-click credential rotation (`regenerateTokenAsync`), status toggling (`updateClientAsync`), permanent removal (`deleteClientAsync`), and bulk token re-signing (`resignAllClientTokensAsync`) when the platform JWT secret is updated. diff --git a/docker/Dockerfile.server b/docker/Dockerfile.server index 5fec7c8..3b14594 100644 --- a/docker/Dockerfile.server +++ b/docker/Dockerfile.server @@ -7,10 +7,10 @@ FROM node:22-alpine AS runner WORKDIR /app ENV NODE_ENV=production ENV PORT_SOCKET=4000 -RUN mkdir -p /app/storage/data \ +RUN apk add --no-cache su-exec \ + && mkdir -p /app/storage/data \ && chown -R node:node /app/storage COPY --from=dependencies --chown=node:node /app/node_modules ./node_modules COPY --chown=node:node server ./server -USER node EXPOSE 4000 -CMD ["node", "server/index.js"] +CMD ["sh", "-c", "mkdir -p /app/storage/data && chown -R node:node /app/storage && exec su-exec node:node node server/index.js"] diff --git a/docker/Dockerfile.web b/docker/Dockerfile.web index a3d793e..1d7f8d9 100644 --- a/docker/Dockerfile.web +++ b/docker/Dockerfile.web @@ -1,10 +1,12 @@ FROM node:22-alpine AS dependencies WORKDIR /app +ENV NODE_ENV=development COPY package.json package-lock.json* ./ -RUN if [ -f package-lock.json ]; then npm ci; else npm install --no-audit --no-fund; fi +RUN if [ -f package-lock.json ]; then npm ci --include=dev; else npm install --include=dev --no-audit --no-fund; fi FROM node:22-alpine AS builder WORKDIR /app +ENV NODE_ENV=production ENV NEXT_TELEMETRY_DISABLED=1 COPY --from=dependencies /app/node_modules ./node_modules COPY . . @@ -16,11 +18,11 @@ ENV NODE_ENV=production ENV NEXT_TELEMETRY_DISABLED=1 ENV PORT=3000 ENV HOSTNAME=0.0.0.0 +RUN apk add --no-cache su-exec \ + && mkdir -p /app/storage/data \ + && chown -R node:node /app/storage COPY --from=builder --chown=node:node /app/public ./public COPY --from=builder --chown=node:node /app/.next/standalone ./ COPY --from=builder --chown=node:node /app/.next/static ./.next/static -RUN mkdir -p /app/storage/data \ - && chown -R node:node /app/storage -USER node EXPOSE 3000 -CMD ["node", "server.js"] +CMD ["sh", "-c", "mkdir -p /app/storage/data && chown -R node:node /app/storage && exec su-exec node:node node server.js"] diff --git a/docker/manifest.md b/docker/manifest.md index c3feeeb..b2aa0b9 100644 --- a/docker/manifest.md +++ b/docker/manifest.md @@ -1,23 +1,15 @@ -# Docker Deployment Manifest +# Docker & Coolify Deployment Manifest ## Purpose +Production container definitions and orchestration for DataStack's multi-service architecture (`docker/`): -Production container definitions for the split architecture: +- `web` (`Dockerfile.web`): Standalone Next.js 15 frontend, `/vcon/*` admin console, and REST API on port `3000` (runs as non-root user). +- `ingestion` (`Dockerfile.server`): Express + Socket.IO real-time ingestion server on port `4000` (runs as non-root user). +- `proxy` (`Dockerfile.proxy` + `coolify-nginx.conf`): Nginx reverse proxy on internal port `80`, forwarding `/socket.io/` to `ingestion:4000` and web traffic to `web:3000`. +- `postgres`: PostgreSQL 16 service with persistent `pgdata` volume storing `admin_users`, `admin_login_attempts`, `client_sdks`, and `admin_settings`. +- `redis`: Redis 7 service with persistent `redisdata` volume. -- `web`: standalone Next.js frontend and admin console on port 3000, running as a non-root user. -- `ingestion`: Express + Socket.IO process on port 4000, running as a non-root user. -- `proxy`: Nginx reverse proxy on internal port 80. Coolify routes the public domain to this service; `/socket.io/` is forwarded to ingestion and other paths to web. -- `redis`: private Compose service reserved for the planned shared-buffer integration; current application code does not consume it. -- `postgres`: private Compose service; the first-run admin setup/login helper stores the single bootstrap admin credential in `admin_users` using `pg`. Prisma-backed client/settings/audit metadata is not wired yet. Collected events must remain in CSV files. - -## Coolify Compose Deployment - -- Create a Git-based Docker Compose application from branch `main`. -- Set Base Directory to `/docker` and Compose Location to `/docker/docker-compose.yml`. Confirm the resolved file remains the repository's `docker/docker-compose.yml`. The `/docker` project directory is required because each service uses `build.context: ..` to reach the repository root; using `/` makes that context escape the checkout. -- Set `DATASTACK_ADMIN_EMAIL` in Coolify. Compose uses generated `SERVICE_HEX_32_DATABASENAME`, `SERVICE_PASSWORD_64_POSTGRES`, `SERVICE_REALBASE64_64_JWT`, `SERVICE_REALBASE64_64_ADMINSESSION`, and `SERVICE_REALBASE64_64_ADMININSTALL`; `DATABASE_URL` is assembled from the generated DB name/password. -- On first visit, copy `SERVICE_REALBASE64_64_ADMININSTALL` from Coolify into `/vcon/setup`, confirm the `DATASTACK_ADMIN_EMAIL` configured in Coolify, choose the first admin password, and keep generated secrets in Coolify. The API enforces the configured email and setup closes after the first account is persisted. -- Add the public domain to service `proxy` at internal port `80`. Coolify manages proxy labels in its normal Compose mode; do not enable Raw Compose mode or add direct host port mappings. -- The `web`, `ingestion`, Redis, and PostgreSQL services are private on the Compose network. Only the proxy is exposed to Coolify's domain proxy. -- The `datastack-data` named volume stores ingestion CSVs; `pgdata` stores PostgreSQL files and the bootstrap admin credential. Compose configures these named volumes for persistence; verify restart/redeploy behavior in the target Coolify runtime before relying on it. Do not delete the volumes or regenerate the DB name for an existing deployment. Back up before DB upgrades. DB password rotation requires changing the DB role as well as the Coolify value. -- The web container does not yet share/read `datastack-data`, and Redis is not wired into runtime code. Prisma-backed client/settings metadata remains future work; cross-process reads and general metadata durability are not established by these images. -- Health checks probe the web landing route, ingestion `/health`, proxy route, Redis ping, and PostgreSQL readiness using the generated `POSTGRES_DB` name. These checks do not establish application-level shared-storage readiness. +## Shared Volumes & Networking +- Both `web` and `ingestion` mount the `datastack-data` volume at `/app/storage/data`, ensuring CSV partitions written by either process are immediately visible across the platform. +- Both `web` and `ingestion` connect to `postgres` via `DATABASE_URL` over the private Compose network, synchronizing client registrations, revocation status, and runtime settings automatically. +- `web` communicates with `ingestion` via `INGESTION_INTERNAL_URL="http://ingestion:4000"` for live health metrics and manual buffer flushes. diff --git a/manifest.md b/manifest.md index 4f6f6d5..1985091 100644 --- a/manifest.md +++ b/manifest.md @@ -1,14 +1,21 @@ # DataStack Platform Root Manifest ## Purpose -Root level orchestration and system manifest for the DataStack Universal Realtime Data Collection Platform. +Root directory manifest for **DataStack**, an open-source, self-hosted real-time telemetry and event logging platform developed by **[Vib Tools](https://vib.tools/)**. -## Directory Index -- `app/`: Next.js App Router providing `/` (Landing page) and `/vcon/*` (Admin Console) -- `components/`: Single source of truth UI (`components/ui/`) and layout (`components/layout/`) -- `core/`: Core backend modules (auth, connector, data, storage, sdk, security, settings, server) -- `server/`: Dedicated Express + Socket.IO process on Port 4000 -- `storage/`: Persisted CSV files under `/storage/data/{clientId}/{YYYY-MM-DD}.csv` -- `sdk-python/`: Pip-installable Python SDK (`datastack-sdk`) -- `docker/`: Docker Compose and Dockerfile deployment specs -- `nginx/`: Reverse proxy configuration for WebSocket and Web traffic +## Directory & Governance Index +- `app/`: Next.js 15 App Router serving `/` (public overview), `/vcon/*` (administration console), and `/api/*` (REST endpoints for auth, clients, events, data, storage, settings, and streaming export). +- `components/`: Single-source-of-truth UI primitives (`components/ui/`), layout shells (`components/layout/`), and page sections (`components/sections/`). +- `core/`: Backend TypeScript modules (`auth`, `data`, `Database`, `Storage`, `Security`, `sdk`, `adminSettings`, `apiEngine`). +- `server/`: Dedicated Express + Socket.IO ingestion service on Port 4000 (`index.js`, `socket/handlers.js`, `workers/csvWriter.js`). +- `storage/`: Partitioned CSV data directory (`/storage/data/{clientId}/{YYYY-MM-DD}.csv`). +- `sdk-python/`: Official pip-installable Python client library (`datastack-sdk`). +- `docker/`: Production Dockerfiles (`Dockerfile.web`, `Dockerfile.server`, `Dockerfile.proxy`), Nginx config, and `docker-compose.yml`. +- `nginx/`: Local Nginx reverse proxy configuration (`default.conf`). +- `README.md`: Comprehensive A–Z project documentation, quickstart, architecture, and deployment guide. +- `AGENTS.md`: Architecture rules and engineering conventions. +- `CONTRIBUTING.md`: Open-source contribution guidelines and local development workflow. +- `SECURITY.md`: Built-in security architecture and vulnerability reporting policy (`support@vibtools.io`). +- `CODE_OF_CONDUCT.md`: Community code of conduct. +- `CHANGELOG.md`: Release history and version notes. +- `LICENSE`: Open-source MIT License (`Copyright (c) 2026 Vib Tools`). diff --git a/nginx/manifest.md b/nginx/manifest.md index 2513f4a..ebfae03 100644 --- a/nginx/manifest.md +++ b/nginx/manifest.md @@ -1,4 +1,4 @@ -# Nginx Proxy Manifest +# Nginx Reverse Proxy Manifest (`nginx/`) ## Purpose -Reverse proxy configuration mapping `/socket.io/` WebSocket traffic to the Express ingestion server on Port 4000, and HTTP web traffic to Next.js on Port 3000. +Local and container reverse proxy configuration (`nginx/default.conf`) routing `/socket.io/` WebSocket connections to the Express + Socket.IO ingestion service on Port `4000` and standard HTTP requests to the Next.js server on Port `3000`. diff --git a/package.json b/package.json index c646cb2..640bbc4 100644 --- a/package.json +++ b/package.json @@ -5,7 +5,7 @@ "scripts": { "dev": "next dev -p 3000 -H 0.0.0.0", "server": "node server/index.js", - "build": "next build", + "build": "NODE_ENV=production next build", "start": "next start", "lint": "eslint .", "clean": "next clean" diff --git a/public/assets/aistudio/Forms.size_62bad673.md b/public/assets/aistudio/Forms.size_62bad673.md deleted file mode 100644 index 899f4df..0000000 --- a/public/assets/aistudio/Forms.size_62bad673.md +++ /dev/null @@ -1,174 +0,0 @@ -# Sandbox Form And Input Size Tokens - -## Audit Scope - -Source: canonical [`sandbox/index.html`](../index.html). This review-only inventory records explicit size-related CSS for form layouts, text inputs, selects, textareas, checkboxes, color/range controls, and radio-style review controls. Host and generated mock-tool iframe styles are kept separate. Typography values are included where they size control text; see [`fonts.md`](fonts.md) and [`fonts.size.md`](fonts.size.md) for the complete typography ledgers. - -The current rendered markup includes text, search, URL, email, file, checkbox, color and select controls, textareas, and custom star choices with `role="radio"`. There are no native `input[type=radio]` declarations in the source. Repeated controls in multiple rendered pages are not treated as unique design tokens. No inline size styles were found on rendered host or mock form controls. - -Values below are literal source declarations. Browser-native defaults are not presented as authored dimensions. - -## Host Form Layouts - -| Selector | Exact size declarations | -| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `.prototype-dialog` | `margin:auto; width:min(520px,calc(100vw - 28px)); max-height:min(82dvh,680px); padding:0; overflow:auto; border:1px solid var(--border-strong); border-radius:8px` | -| `.workspace-create-dialog` | `width:min(440px,calc(100vw - 28px))` | -| `.prototype-modal-form` | `display:grid; gap:0` | -| `.prototype-modal-fields` | `display:grid; gap:11px; padding:14px 16px` | -| `.prototype-form-field` | `display:grid; gap:5px; min-width:0` | -| `.prototype-form-grid` | `display:grid; grid-template-columns:minmax(0,1fr) 144px; gap:10px` | -| `.prototype-modal-foot` | `display:flex; gap:7px; padding:11px 16px; border-top:1px solid var(--border)` | -| `.team-name-edit-form` | `display:flex; gap:6px; margin:0 0 6px` | -| `.team-name-form,.team-invite-form` | `display:grid; gap:9px` | -| `.team-field` | `display:grid; gap:5px` | -| `.team-settings-fields` | `display:grid; grid-template-columns:repeat(2,minmax(0,1fr)); gap:10px` | -| `.team-settings-actions` | `display:flex; gap:7px; padding-top:4px` | -| `.team-invite-fields` | `display:grid; grid-template-columns:minmax(0,1fr) 108px auto; gap:6px` | -| `.team-members-toolbar` | `display:flex; gap:8px; margin:0 14px 10px` | -| `.review-reply-form` | `display:grid; gap:6px; margin:9px 0 0 38px` | -| `.review-composer` | `margin:0 0 12px; padding:12px; border:1px solid var(--border); border-radius:7px` | -| `.review-composer-head` | `display:flex; gap:10px; margin-bottom:8px` | -| `.review-rating` | `display:flex; gap:7px; margin:0 0 8px; padding:0; border:0` | -| `.review-rating-options` | `display:flex; gap:2px` | -| `.review-compose-footer` | `display:flex; gap:10px; margin-top:8px` | -| `.profile-edit-form` | `display:grid; gap:12px` | -| `.profile-field` | `display:grid; gap:5px` | -| `.profile-form-actions` | `display:flex; gap:8px; flex-wrap:wrap` | -| `.setting-row` | `display:flex; gap:20px; padding:14px 0; border-bottom:1px solid var(--border)` | -| `.settings-section .setting-row` | `min-height:54px; gap:14px; padding:10px 0` | -| `.settings-switch` | `display:flex; gap:8px; font-size:11.5px` | - -## Host Text Inputs, Selects, And Textareas - -| Selector | Exact size declarations | -| ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `input,select,textarea` | `font-family:inherit` | -| `.search-wrap` | `display:flex; gap:7px; border:1px solid var(--border-strong); border-radius:6px; padding:0 9px; height:30px` | -| `.search-input` | `flex:1; border:none; outline:none; font-size:12.5px` | -| `.side-select` | `width:100%; border:1px solid var(--border-strong); font-size:12.5px; padding:6px 8px; border-radius:5px; outline:none` | -| `.palette-searchbar` | `height:48px; flex:none; display:flex; gap:12px; padding:0 14px; border-bottom:1px solid var(--border-strong)` | -| `.palette-input` | `width:100%; min-width:0; height:100%; border:0; outline:0; font:inherit; font-size:14px` | -| `.search-palette` | `width:min(640px,calc(100vw - 28px)); max-height:min(680px,calc(100dvh - 66px)); display:flex; overflow:hidden; border:1px solid var(--border-palette); border-radius:10px` | -| `.team-name-edit-form input` | `width:min(280px,60vw); min-height:30px; padding:5px 8px; border:1px solid var(--border-strong); border-radius:5px; font:inherit; font-size:11px` | -| `.team-member-search` | `min-width:0; min-height:32px; flex:1; padding:6px 9px; border:1px solid var(--border); border-radius:5px; font:inherit; font-size:11px` | -| `.team-member-filter` | `min-width:112px; min-height:32px; padding:5px 8px; border:1px solid var(--border); border-radius:5px; font:inherit; font-size:10.5px` | -| `.team-field input`, `.team-field select` | `width:100%; min-height:34px; padding:7px 9px; border:1px solid var(--border-strong); border-radius:5px; font:inherit; font-size:11.5px` | -| `.team-field label`, `.prototype-form-field label` | `font-size:10.5px; font-weight:600` | -| `.team-role-select` | `width:100%; max-width:110px; min-height:28px; padding:4px 6px; border:1px solid var(--border); border-radius:4px; font:inherit; font-size:10px` | -| `.prototype-form-field input:not([type="checkbox"]):not([type="color"])`, `.prototype-form-field select`, `.prototype-form-field textarea` | `width:100%; min-height:34px; padding:7px 9px; border:1px solid var(--border-strong); border-radius:5px; font:inherit; font-size:11.5px` | -| `.prototype-form-field textarea` | `min-height:74px; resize:vertical; line-height:1.5` | -| `.collection-picker-search` | `width:100%; min-height:34px; padding:7px 9px; border:1px solid var(--border-strong); border-radius:5px; font:inherit; font-size:11.5px` | -| `.workspace-scratchpad` | `width:100%; min-height:270px; resize:vertical; padding:11px 12px; border:1px solid var(--border-strong); border-radius:6px; font:inherit; font-size:12px; line-height:1.55` | -| `.review-reply-form textarea` | `min-height:58px; padding:7px 8px; border:1px solid var(--border-strong); border-radius:5px; font:inherit; font-size:10.5px; line-height:1.45; resize:vertical` | -| `.review-composer textarea` | `display:block; width:100%; min-height:64px; resize:vertical; padding:8px 9px; border:1px solid var(--border-strong); border-radius:5px; font:inherit; font-size:12px; line-height:1.45` | -| `.profile-field input`, `.profile-field textarea` | `width:100%; border:1px solid var(--border-strong); border-radius:6px; padding:9px 10px; font:inherit; font-size:12.5px; resize:vertical` | -| `.settings-control` | `min-width:140px; max-width:190px` | - -## Host Checkboxes, Color, And Radio Controls - -| Selector | Exact size declarations | -| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -| `.switch-row` | `display:flex; gap:8px; padding:6px 8px; border-radius:5px; font-size:12.5px` | -| `.switch-row input` | `accent-color:var(--accent)`; no authored width/height | -| `.settings-switch input` | `accent-color:var(--accent); width:15px; height:15px` | -| `.collection-tool-option` | `display:flex; gap:8px; min-width:0; min-height:34px; padding:5px 7px; border:1px solid transparent; border-radius:4px` | -| `.collection-tool-option input` | `flex:none; margin:0; accent-color:var(--accent)`; no authored width/height | -| `.collection-add-option` | `display:flex; gap:8px; min-width:0; min-height:40px; padding:6px 8px; border:1px solid var(--border); border-radius:5px` | -| `.collection-add-option input` | `flex:none; margin:0; accent-color:var(--accent)`; no authored width/height | -| `.prototype-color-control` | `width:48px; height:34px; padding:3px; border:1px solid var(--border-strong); border-radius:5px` | -| `.prototype-check-row` | `display:flex; gap:7px; font-size:11px` | -| `.review-rating-options button[role="radio"]` | `width:26px; height:26px; display:grid; padding:0; border:0; border-radius:4px` | -| `.review-rating-options button[role="radio"]:focus-visible` | `outline:1px solid var(--accent)` | - -Review stars are buttons with `role="radio"`, not native radio inputs. Native checkbox/radio dimensions are browser defaults unless the selectors above specify otherwise. - -## Host Responsive Overrides - -All conditions below are `@media (max-width:640px)`; values are literal source declarations. - -| Selector | Exact responsive size declarations | -| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -| `.team-name-edit-form input` | `width:min(220px,48vw)` | -| `.team-invite-fields` | First: `grid-template-columns:minmax(0,1fr) 92px auto`; later: `grid-template-columns:minmax(0,1fr) 84px auto; gap:5px` | -| `.team-member-filter` | `min-width:96px` | -| `.team-role-select` | `padding-inline:3px; font-size:9px` | -| `.workspace-scratchpad` | First: `min-height:220px`; later: `min-height:180px` | -| `.palette-searchbar` | `height:44px; padding-inline:11px; gap:9px` | -| `.settings-section .setting-row` | `min-height:46px; gap:8px; padding:7px 0` | -| `.settings-control` | `min-width:112px; max-width:148px` | -| `.settings-switch` | `gap:6px; font-size:10.5px` | - -## Mock-Tool Form Controls - -Each iframe owns its own form-control styling. Unlisted controls use the preview document's native browser defaults. - -| Preview | Selector | Exact size declarations | -| ------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| JSON Formatter | `.panes` | `flex:1; display:grid; grid-template-columns:1fr 1fr; gap:1px; min-height:0` | -| JSON Formatter | `.pane` | `display:flex; min-height:0` | -| JSON Formatter | `.pane label` | `font-size:11px; padding:8px 14px` | -| JSON Formatter | `textarea` | `flex:1; border:none; padding:14px; font-family:inherit; font-size:13px; resize:none; line-height:1.5` | -| Color Picker | `input[type=color]` | `width:60px; height:40px; border:1px solid var(--frame-border); border-radius:8px; padding:2px` | -| Password Generator | `.row label` | `font-size:13px; flex:1` | -| Password Generator | `input[type=range]` | `flex:2; accent-color:var(--frame-accent)`; no authored width/height | -| Password Generator | `input[type=checkbox]` | No authored dimensions; uses native browser defaults | -| Text Case Converter | `.panes` | `flex:1; display:grid; grid-template-columns:1fr 1fr; min-height:0` | -| Text Case Converter | `.pane` | `display:flex` | -| Text Case Converter | `.pane label` | `font-size:11px; padding:10px 20px; font-weight:600` | -| Text Case Converter | `textarea` | `flex:1; border:none; padding:0 20px 20px; font-size:14px; resize:none; line-height:1.6` | -| SQL Studio | `.editor-wrap` | `height:38%; flex-shrink:0; display:flex; min-height:120px; border-bottom:1px solid var(--frame-border)` | -| SQL Studio | `textarea` | `flex:1; border:none; outline:none; padding:12px 16px; font-family:ui-monospace,"SF Mono",monospace; font-size:13px; resize:none; line-height:1.65` | - -## Auxiliary Form Geometry And Focus States - -| Selector | Exact size declarations | -| ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | -| `.workspace-scratchpad:focus` | `outline:2px solid var(--accent); outline-offset:1px` | -| `.search-palette-backdrop[hidden],.search-palette[hidden]` | `display:none` | -| `.workspace-scratchpad-meta` | `display:flex; gap:8px; margin-top:6px` | -| `.team-name-edit-form input:focus` | `outline:2px solid var(--accent); outline-offset:1px` | -| `.team-member-search:focus` | `outline:2px solid var(--accent); outline-offset:1px` | -| `.team-field input:focus`, `.team-field select:focus` | `outline:2px solid var(--accent); outline-offset:1px` | -| `.prototype-modal-head` | `display:flex; gap:12px; padding:14px 16px; border-bottom:1px solid var(--border)` | -| `.prototype-modal-head p` | `margin-top:3px` | -| `.sr-only` | `position:absolute; width:1px; height:1px; padding:0; margin:-1px; overflow:hidden; clip:rect(0,0,0,0); white-space:nowrap; border:0` | -| `.prototype-form-field input:focus`, `.prototype-form-field select:focus`, `.prototype-form-field textarea:focus` | `outline:2px solid var(--accent); outline-offset:1px` | -| `.collection-picker-search:focus` | `outline:2px solid var(--accent); outline-offset:1px` | -| `.collection-picker-meta` | `display:flex; gap:8px; font-size:9.5px` | -| `.collection-tool-results` | `display:grid; gap:3px; max-height:192px; padding:2px; overflow-y:auto; border:1px solid var(--border); border-radius:5px` | -| `.collection-tool-option-copy` | `min-width:0; flex:1` | -| `.collection-tool-empty` | `padding:15px 10px; font-size:10.5px` | -| `.collection-add-count` | `flex:none; padding:3px 6px; border-radius:4px; font-size:9.5px` | -| `.collection-add-options` | `display:grid; grid-template-columns:repeat(2,minmax(0,1fr)); gap:6px; max-height:220px; padding:1px; overflow-y:auto` | -| `.collection-add-option-copy` | `min-width:0; flex:1` | -| `.collection-add-actions` | `display:flex; gap:10px; padding-top:9px; border-top:1px solid var(--border)` | -| `.collection-add-hint` | `min-width:0; font-size:9.5px; line-height:1.4` | -| `.review-reply-form textarea:focus` | `outline:2px solid var(--accent); outline-offset:1px` | -| `.review-composer-head` | `display:flex; gap:10px; margin-bottom:8px` | -| `.review-rating-options button:hover`, `.review-rating-options button:focus-visible` | `outline:1px solid var(--accent)` | -| `.review-composer textarea:focus` | `outline:2px solid var(--accent); outline-offset:1px` | -| `.profile-field input:focus`, `.profile-field textarea:focus` | `outline:2px solid var(--accent); outline-offset:1px` | -| `.profile-visibility` | `display:flex; gap:12px` | -| `.settings-section .setting-row:focus` | `outline:1px solid var(--accent); outline-offset:2px; border-radius:4px` | -| `.team-name-form,.team-invite-form` | `display:grid; gap:9px` | -| `.team-field input,.team-field select` | `width:100%; min-height:34px; padding:7px 9px; border:1px solid var(--border-strong); border-radius:5px; font:inherit; font-size:11.5px` | -| `.team-field input:focus,.team-field select:focus` | `outline:2px solid var(--accent); outline-offset:1px` | -| `.prototype-form-field input:not([type="checkbox"]):not([type="color"]),.prototype-form-field select,.prototype-form-field textarea` | `width:100%; min-height:34px; padding:7px 9px; border:1px solid var(--border-strong); border-radius:5px; font:inherit; font-size:11.5px` | -| `.prototype-form-field input:focus,.prototype-form-field select:focus,.prototype-form-field textarea:focus` | `outline:2px solid var(--accent); outline-offset:1px` | -| `.profile-field input,.profile-field textarea` | `width:100%; border:1px solid var(--border-strong); border-radius:6px; padding:9px 10px; font:inherit; font-size:12.5px; resize:vertical` | -| `.profile-field input:focus,.profile-field textarea:focus` | `outline:2px solid var(--accent); outline-offset:1px` | -| `.review-rating-options button:hover,.review-rating-options button:focus-visible` | `outline:1px solid var(--accent)` | -| `.collection-add-tools` | `display:grid; gap:10px; margin-top:14px; padding:12px; border:1px solid var(--border); border-radius:7px` | -| `.collection-add-head` | `display:flex; gap:10px` | -| `.collection-add-actions .btn` | `flex:none` | -| `.settings-section .profile-form-actions` at `max-width:640px` | `gap:5px` | -| `.search-palette` at `max-width:640px` | `width:calc(100vw - 16px); max-height:min(72dvh,560px); border-radius:8px` | - -## Inline And Coverage Notes - -- No inline geometry was found on rendered host or mock native form elements. The Password Generator mock preview has inline sizing on the checkbox group row and its four labels: `.row` uses `gap:16px; font-size:13px; flex-wrap:wrap`, and each checkbox label uses `display:flex; gap:6px; align-items:center; flex:none`. -- Page-shell bounds, generic panel/table geometry, and mock iframe app frames are cross-referenced in [`Pages.size.md`](Pages.size.md), [`Sections.size.md`](Sections.size.md), and [`cards.size.md`](cards.size.md); they are not duplicated here unless they directly size a form/control group. -- The rendered host inventory spans text/search/url/email/file inputs, selects, textareas, checkboxes, a color input, and `role="radio"` buttons. Generated preview controls include textareas, a color input, a range input, and checkboxes. -- The CSS extraction includes form wrappers and responsive overrides so dimensions are not reduced to individual input boxes alone. It preserves authored declarations rather than inferring native control sizes. -- Refresh this audit whenever form/control markup or sizing in `sandbox/index.html` changes. This is a source inventory, not a production form-system contract. diff --git a/public/assets/aistudio/MINIFEST_53e19303.md b/public/assets/aistudio/MINIFEST_53e19303.md deleted file mode 100644 index 5551eac..0000000 --- a/public/assets/aistudio/MINIFEST_53e19303.md +++ /dev/null @@ -1,39 +0,0 @@ -# Design Token Directory MINIFEST - -Purpose: preserve review-only token audits extracted from the canonical sandbox prototype. The files document observed source values and are not production token definitions. - -## Files - -- `README.md` - directory purpose, boundaries, and update guidance. -- `MINIFEST.md` - this file inventory and current phase. -- `fonts.md` - exact typography declaration/value inventory for host styles and isolated mock-tool iframe previews, including inline styles. -- `fonts.size.md` - exact numeric font-size values and counts across host CSS, preview CSS, shorthand, and inline markup. -- `buttons.size.md` - exact host/responsive/mock-preview button sizing rules, nested icon sizes, and inline control sizes. -- `cards.size.md` - exact host and iframe card-surface/grid geometry, responsive overrides, and inline-geometry audit. -- `Sections.size.md` - exact section/container sizing, host breakpoints, and iframe-local subsection geometry. -- `Forms.size.md` - exact host form/control sizing, responsive overrides, custom radio controls, iframe controls, and inline group sizing. -- `Pages.size.md` - exact app page-shell bounds, page-width modifiers, primary layout tracks, and responsive overrides. -- `Spacing.size.md` - exact margin, padding, gap, offset, and scroll-spacing values with host/iframe/inline/JS counts. -- `border.styles.size.md` - exact border property/value pairs with host/iframe counts and explicit inline/JS coverage. -- `sidebar.styles.size.md` - exact host rail/sidebar/drawer and SQL Studio iframe styles, dimensions, responsive states, and inline patterns. -- `header.styles.size.md` - exact host/iframe header and chrome rules, responsive variants, and header-scoped inline style patterns. -- `table.styles.size.md` - exact host Teams table and isolated SQL Studio iframe table styles, dimensions, responsive cascade, and markup coverage. -- `popupModel.styles.size.md` - exact popup/modal, palette, dropdown, mobile popover, dialog, picker, toast, responsive, state, and markup coverage. -- `dropdown.styles.size.md` - exact custom workspace dropdown and authored native select control geometry, responsive states, markup, and option-popup boundary. - -## Phase - -- Font-token forensic audit: complete; host CSS, all 13 generated mock-tool preview styles, and inline typography were inventoried from `sandbox/index.html`. No prototype or production styles were changed. -- Font-size-token audit: complete; 23 numeric values and 310 size-bearing occurrences are reconciled across direct CSS, shorthand, and inline declarations by host/iframe scope. -- Button-size-token audit: complete; 53 applicable host rules, 17 mock rules, nested icon/accessory sizes, and inline sizing are documented by scope. -- Card-size-token audit: complete; host card surfaces/layouts and mock iframe card surfaces are recorded by scope, with 206 host and 17 iframe declarations reconciled. -- Section-size-token audit: complete; 137 host and 20 iframe geometry declarations are reconciled, with no inline section geometry. -- Form-size-token audit: complete; 67 form-specific host/iframe rule groups reconcile with zero mismatches; native control defaults and five inline preview group declarations are distinguished. -- Page-size-token audit: complete; page roots, width modifiers, shell constraints, primary grids, and responsive variants reconcile with zero mismatches. -- Spacing-token audit: complete; 222 exact property/value pairs and 642 source declarations reconcile across host CSS, all 13 preview stylesheets, inline markup, and JS offsets. -- Border-style/size audit: complete; 50 exact border property/value pairs and 327 host/iframe CSS declarations reconcile; inline and JS border declarations are absent. -- Sidebar-style/size audit: complete; 96 host rule groups (454 declarations) and 16 SQL Studio rule groups (83 declarations) reconcile; 15 rendered host inline styles are inventoried by pattern. -- Header-style/size audit: complete; 150 host rule groups (530 declarations) and 33 generated-preview rule groups (135 declarations) reconcile; 41 host inline instances across 29 patterns and two preview inline styles are recorded. -- Table-style/size audit: complete; 17 host selector blocks (38 declarations), eight host responsive declarations, and five isolated SQL Studio iframe selector blocks (22 declarations) reconcile. Literal inline and JavaScript table style assignments are absent. -- Popup-modal-style/size audit: complete; 18 workspace dropdown, 24 palette/backdrop, 13 mobile navigation, 19 shared dialog, 13 collection picker, and three toast selector blocks reconcile. -- Dropdown-style/size audit: complete; 25 custom workspace dropdown selector blocks and six native select markup instances across five authored control patterns reconcile; option-popup CSS is absent. No popup-specific inline or JavaScript geometry was found. diff --git a/public/assets/aistudio/Pages.size_0acfe499.md b/public/assets/aistudio/Pages.size_0acfe499.md deleted file mode 100644 index 7f06632..0000000 --- a/public/assets/aistudio/Pages.size_0acfe499.md +++ /dev/null @@ -1,82 +0,0 @@ -# Sandbox Page-Size Tokens - -## Audit Scope - -Source: canonical [`sandbox/index.html`](../index.html). This review-only ledger records page-shell bounds, page-root widths/padding, primary page content grids, and their responsive changes. It does not define production tokens or authorize additional UI migration. - -Rendered roots include the shared `.page` canvas; Workspace, Teams and Team subpages, Tool Detail, Profile/public Profile, and Settings modifiers; and generic-shell views for Discover, Collections, Favorites, Recent, and collection tabs. Unsupported mobile tool details also use the generic `.page` root. Isolated mock-tool documents are iframe applications rather than workbench pages; their local geometry remains in [`Sections.size.md`](Sections.size.md) and [`cards.size.md`](cards.size.md). - -Typography is recorded in [`fonts.md`](fonts.md) and [`fonts.size.md`](fonts.size.md). Section/hero and panel internals are recorded in [`Sections.size.md`](Sections.size.md); card-grid and card-surface geometry is cross-indexed in [`cards.size.md`](cards.size.md); responsive button hit areas remain in [`buttons.size.md`](buttons.size.md). - -## App Viewport And Shared Page Canvas - -| Selector | Exact size declarations | -| --------------------------------- | ---------------------------------------------------------- | -| `.app` | `display:flex; flex-direction:column; height:100vh` | -| `.workbench` | `flex:1; display:flex; min-height:0; overflow:hidden` | -| `.main` | `flex:1; display:flex; flex-direction:column; min-width:0` | -| `.content` | `flex:1; overflow-y:auto; overflow-x:hidden; min-height:0` | -| `.content.runner` | `overflow:hidden; padding:0` | -| `.page` | `padding:26px 30px 40px; max-width:1280px; margin:0 auto` | -| `.app` at `max-width:640px` | `height:100vh; height:100dvh` | -| `.workbench` at `max-width:640px` | `position:relative; flex-direction:column` | -| `.main` at `max-width:640px` | `order:1; flex:1; min-height:0` | -| `.page` at `max-width:640px` | `padding:18px 16px 40px` | - -## Page Width Modifiers - -Modifiers are applied on top of `.page`; the source sets `max-width`, not a fixed width. - -| Page view | Selector | Exact size declaration | -| --------------------------------------------------------- | ----------------- | ---------------------------------- | -| Workspace | `.workspace-page` | `max-width:1160px` | -| Teams | `.teams-page` | `max-width:1040px` | -| Team Invite, Sharing, and Settings | `.team-subpage` | `max-width:760px` | -| Tool Detail | `.detail` | `max-width:1080px` | -| Personal and public Profile | `.profile-page` | `max-width:1080px` | -| Settings | `.settings-page` | `max-width:900px` | -| Discover, Collections, Favorites, Recent, collection tabs | `.page` | `max-width:1280px` (shared canvas) | - -## Primary Page Layout Tracks - -| View/layout | Selector | Exact size declarations | -| ---------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------- | -| Shared page header | `.page-header` | `display:flex; align-items:flex-start; justify-content:space-between; gap:20px; margin-bottom:26px; flex-wrap:wrap` | -| Workspace columns | `.workspace-main-grid` | `display:grid; grid-template-columns:minmax(0,1.15fr) minmax(280px,.85fr); gap:14px; align-items:start` | -| Teams lower content | `.team-bottom-grid` | `display:grid; grid-template-columns:minmax(0,1.15fr) minmax(250px,.85fr); gap:12px; align-items:start` | -| Discover, Favorites, Recent, collection-tool results | `.tool-grid` | `display:grid; grid-template-columns:repeat(auto-fill,minmax(252px,1fr)); gap:12px` | -| Collections index | `.collection-card-grid` | `display:grid; grid-template-columns:repeat(auto-fill,minmax(210px,1fr)); gap:9px` | -| Collection tab tools heading | `.collection-tools-head` | `display:flex; align-items:center; justify-content:space-between; gap:10px; margin:16px 0 9px` | -| Tool Detail hero | `.detail-hero` | `display:flex; gap:20px; margin-bottom:28px; flex-wrap:wrap` | -| Tool Detail glyph | `.detail-glyph` | `width:76px; height:76px; border-radius:18px; flex-shrink:0` | -| Tool Detail content | `.detail-grid` | `display:grid; grid-template-columns:1fr 260px; gap:34px` | -| Tool Detail copy column | `.detail-info` | `flex:1; min-width:260px` | -| Tool Detail title | `.detail-info h1` | `margin-bottom:8px` | -| Tool Detail description | `.detail-info .desc` | `margin-bottom:16px; max-width:600px` | -| Tool Detail actions | `.detail-actions` | `display:flex; gap:8px; flex-wrap:wrap` | -| Profile main columns | `.profile-columns` | `display:grid; grid-template-columns:minmax(0,1.3fr) minmax(240px,.7fr); gap:16px; align-items:start` | - -## Responsive Page Layouts - -| Selector | Media condition | Exact responsive size declarations | -| ---------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -| `.workspace-main-grid` | `max-width:860px` | `grid-template-columns:minmax(0,1fr)` | -| `.detail-grid` | `max-width:860px` | `grid-template-columns:1fr` | -| `.detail-hero` | `max-width:640px` | `display:grid; grid-template-columns:52px minmax(0,1fr); align-items:start; gap:12px; margin-bottom:22px` | -| `.detail-glyph` | `max-width:640px` | `width:52px; height:52px; border-radius:12px` | -| `.detail-info` | `max-width:640px` | `display:contents; min-width:0` | -| `.detail-info h1` | `max-width:640px` | `margin-bottom:6px` | -| `.detail-info .desc` | `max-width:640px` | `margin-bottom:0` | -| `.detail-actions` | `max-width:640px` | `grid-column:1/-1; display:grid; grid-template-columns:minmax(0,1fr) minmax(0,1fr) auto; gap:6px` | -| `.detail-actions .btn` | `max-width:640px` | `height:32px; min-width:0; justify-content:center; padding-inline:8px; white-space:nowrap` (button sizing is also indexed in `buttons.size.md`) | -| `.tool-grid` | `max-width:640px` | `grid-template-columns:1fr` | -| `.team-bottom-grid` | `max-width:640px` | `grid-template-columns:minmax(0,1fr)` | -| `.profile-columns` | `max-width:640px` | `grid-template-columns:1fr; gap:0` | - -## Coverage Notes - -- A fresh raw-source audit matched 42 in-scope selector/media groups and every documented size declaration to the canonical stylesheet with zero discrepancies. -- Page roots, width modifiers, shell constraints, primary content grids, and responsive variants are literal source declarations; computed rendered widths/heights are not substituted for CSS tokens. -- Discover, Collections, Favorites, Recent, and collection-tab views use the generic page root; their card-grid internals are shared and indexed above and in the card ledger. -- The generic page header, Teams header, Profile sections, Workspace sections, and Settings sections have additional spacing values in [`Sections.size.md`](Sections.size.md); this file avoids duplicating those section internals. -- No production source, sandbox HTML, or styling was changed for this audit. Refresh this ledger when page roots or page-level geometry in `sandbox/index.html` change. diff --git a/public/assets/aistudio/README_9c35b8d5.md b/public/assets/aistudio/README_9c35b8d5.md deleted file mode 100644 index f9ced13..0000000 --- a/public/assets/aistudio/README_9c35b8d5.md +++ /dev/null @@ -1,23 +0,0 @@ -# Sandbox Design Tokens - -This directory holds review-only design-token extractions from the canonical `sandbox/index.html` prototype. These documents describe observed prototype values; they are not production token definitions and do not authorize copying prototype styling into the application. - -## Files - -- `fonts.md` - exhaustive typography declaration/value inventory for host styles and generated mock-tool iframe previews, including literal inline typography. -- `fonts.size.md` - standalone exact font-size inventory, including values inside shorthand and inline markup with per-scope occurrence counts. -- `buttons.size.md` - exact button hit-area, padding, responsive, icon, and mock-preview sizing declarations by selector. -- `cards.size.md` - exact card surfaces, card-grid constraints, responsive geometry, modal frames, and isolated mock-preview surfaces. -- `Sections.size.md` - exact page/section bounds, spacing, layout tracks, responsive overrides, and iframe subgroup dimensions. -- `Forms.size.md` - form/control layout and dimensions, responsive states, mock-tool controls, and inline control-group sizing. -- `Pages.size.md` - page-shell bounds, page-specific maximum widths, primary layout tracks, and responsive page geometry. -- `Spacing.size.md` - exact host/iframe spacing property-value tokens with CSS, responsive, inline, and JS-offset counts. -- `border.styles.size.md` - exact host/iframe border properties and values, including widths, styles, colors, radii, responsive rules, and counts. -- `sidebar.styles.size.md` - host activity rail, activity-specific sidebar/drawer styles, responsive states, inline styles, and SQL Studio's isolated iframe sidebar. -- `header.styles.size.md` - exact host and generated-preview header/chrome declarations, responsive rules, and scoped inline styles. -- `table.styles.size.md` - exact host Teams table and isolated SQL Studio iframe table styles, dimensions, responsive cascade, and markup coverage. -- `popupModel.styles.size.md` - exact popup/modal, palette, dropdown, mobile popover, dialog, picker, toast, responsive, state, and markup coverage. -- `dropdown.styles.size.md` - exact custom workspace dropdown and all authored native select control geometry, responsive states, markup, and option-popup boundary. -- `MINIFEST.md` - inventory and scope/status for this directory. - -Update the relevant extraction when the canonical sandbox source changes. Keep host and isolated iframe values distinct, preserve source values exactly, and update this inventory when files or scope change. diff --git a/public/assets/aistudio/Screenshot_1_817e4629.png b/public/assets/aistudio/Screenshot_1_817e4629.png deleted file mode 100644 index ce5d50e..0000000 Binary files a/public/assets/aistudio/Screenshot_1_817e4629.png and /dev/null differ diff --git a/public/assets/aistudio/Screenshot_1_8269fce1.png b/public/assets/aistudio/Screenshot_1_8269fce1.png deleted file mode 100644 index 7df2dfd..0000000 Binary files a/public/assets/aistudio/Screenshot_1_8269fce1.png and /dev/null differ diff --git a/public/assets/aistudio/Screenshot_2_6b1e2710.png b/public/assets/aistudio/Screenshot_2_6b1e2710.png deleted file mode 100644 index 546104c..0000000 Binary files a/public/assets/aistudio/Screenshot_2_6b1e2710.png and /dev/null differ diff --git a/public/assets/aistudio/Screenshot_2_cb6e47fe.png b/public/assets/aistudio/Screenshot_2_cb6e47fe.png deleted file mode 100644 index 1435aa0..0000000 Binary files a/public/assets/aistudio/Screenshot_2_cb6e47fe.png and /dev/null differ diff --git a/public/assets/aistudio/Screenshot_2_f64ff131.png b/public/assets/aistudio/Screenshot_2_f64ff131.png deleted file mode 100644 index 6ae09bd..0000000 Binary files a/public/assets/aistudio/Screenshot_2_f64ff131.png and /dev/null differ diff --git a/public/assets/aistudio/Screenshot_3_1ca7431a.png b/public/assets/aistudio/Screenshot_3_1ca7431a.png deleted file mode 100644 index 2966c7f..0000000 Binary files a/public/assets/aistudio/Screenshot_3_1ca7431a.png and /dev/null differ diff --git a/public/assets/aistudio/Screenshot_3_4f000ebd.png b/public/assets/aistudio/Screenshot_3_4f000ebd.png deleted file mode 100644 index 0ababef..0000000 Binary files a/public/assets/aistudio/Screenshot_3_4f000ebd.png and /dev/null differ diff --git a/public/assets/aistudio/Screenshot_3_fe84ae70.png b/public/assets/aistudio/Screenshot_3_fe84ae70.png deleted file mode 100644 index 908c102..0000000 Binary files a/public/assets/aistudio/Screenshot_3_fe84ae70.png and /dev/null differ diff --git a/public/assets/aistudio/Screenshot_4_456bccaa.png b/public/assets/aistudio/Screenshot_4_456bccaa.png deleted file mode 100644 index a75d2cb..0000000 Binary files a/public/assets/aistudio/Screenshot_4_456bccaa.png and /dev/null differ diff --git a/public/assets/aistudio/Screenshot_4_7b7eb9fe.png b/public/assets/aistudio/Screenshot_4_7b7eb9fe.png deleted file mode 100644 index 52e4b12..0000000 Binary files a/public/assets/aistudio/Screenshot_4_7b7eb9fe.png and /dev/null differ diff --git a/public/assets/aistudio/Screenshot_5_be3f8db7.png b/public/assets/aistudio/Screenshot_5_be3f8db7.png deleted file mode 100644 index 3f203b8..0000000 Binary files a/public/assets/aistudio/Screenshot_5_be3f8db7.png and /dev/null differ diff --git a/public/assets/aistudio/Sections.size_0a249d16.md b/public/assets/aistudio/Sections.size_0a249d16.md deleted file mode 100644 index 2666784..0000000 --- a/public/assets/aistudio/Sections.size_0a249d16.md +++ /dev/null @@ -1,127 +0,0 @@ -# Sandbox Section-Size Tokens - -## Audit Scope - -Source: canonical [`sandbox/index.html`](../index.html). This file records exact sizing for page and section containers; it does not change prototype or production styles. - -Included values cover page bounds, section spacing, layout tracks, display/flex geometry, gaps, padding/margins, border dimensions, and overflow where it affects section layout. Host workbench rules, responsive overrides, and iframe-local subgroups are separate. Typography is covered by [`fonts.md`](fonts.md) and [`fonts.size.md`](fonts.size.md); card surface geometry is also detailed in [`cards.size.md`](cards.size.md). - -The raw source parse found 68 host section/layout rules and 7 iframe subgroup rules. The rendered section wrappers have no inline size geometry. - -## Host Page And Generic Sections - -| Selector | Exact size declarations | -| ----------------------------------------- | --------------------------------------------------------- | -| `.side-block` | `padding:8px 8px 3px` | -| `.side-block+.side-block` | `border-top:1px solid var(--border)` | -| `.page` | `padding:26px 30px 40px; max-width:1280px; margin:0 auto` | -| `.page-header` | `display:flex; gap:20px; margin-bottom:26px` | -| `.page-header h1` | `margin-bottom:5px` | -| `.section` | `margin-bottom:32px` | -| `.section-head` | `display:flex; margin-bottom:14px` | -| `.workspace-page` | `max-width:1160px` | -| `.teams-page` | `max-width:1040px` | -| `.team-subpage` | `max-width:760px` | -| `.teams-header` | `display:flex; gap:18px; margin-bottom:18px` | -| `.teams-header h1` | `display:flex; gap:8px; margin-bottom:5px` | -| `.teams-header-actions` | `display:flex; gap:7px; flex:none` | -| `.profile-page` | `max-width:1080px` | -| `.profile-back` | `margin-bottom:14px` | -| `.profile-side-group` | `padding:6px 0 3px` | -| `.profile-side-group+.profile-side-group` | `border-top:1px solid var(--border)` | -| `.settings-page` | `max-width:900px` | -| `.settings-intro` | `margin-bottom:18px` | -| `.settings-intro h1` | `margin-bottom:4px` | -| `.settings-intro p` | `max-width:620px` | - -## Workspace Sections - -| Selector | Exact size declarations | -| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | -| `.workspace-hero` | `display:flex; gap:20px; padding:22px 24px; margin-bottom:18px; border:1px solid var(--border); border-radius:8px` | -| `.workspace-hero.is-populated` | `padding:14px 18px; margin-bottom:12px` | -| `.workspace-hero-copy` | `min-width:0; max-width:690px` | -| `.workspace-hero h1` | `margin-bottom:7px` | -| `.workspace-hero.is-populated .workspace-eyebrow` | `margin-bottom:4px` | -| `.workspace-hero.is-populated h1` | `margin-bottom:4px` | -| `.workspace-control-strip` | `display:flex; gap:10px; padding:10px 12px; margin-bottom:18px; border:1px solid var(--border); border-radius:7px` | -| `.workspace-main-grid` | `display:grid; grid-template-columns:minmax(0,1.15fr) minmax(280px,.85fr); gap:14px` | -| `.workspace-section` | `min-width:0; margin-bottom:18px` | -| `.workspace-section-head` | `display:flex; gap:10px; margin-bottom:10px` | - -## Team Sections - -| Selector | Exact size declarations | -| ------------------------ | ----------------------------------------------------------------------------------------------------- | -| `.team-settings-fields` | `display:grid; grid-template-columns:repeat(2,minmax(0,1fr)); gap:10px` | -| `.team-settings-actions` | `display:flex; gap:7px; padding-top:4px` | -| `.team-members-panel` | `min-width:0; margin-bottom:14px; border:1px solid var(--border); border-radius:7px; overflow:hidden` | -| `.team-bottom-grid` | `display:grid; grid-template-columns:minmax(0,1.15fr) minmax(250px,.85fr); gap:12px` | - -## Profile Sections - -| Selector | Exact size declarations | -| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `.profile-hero` | `display:grid; grid-template-columns:56px minmax(0,1fr) auto; gap:10px 14px; border:1px solid var(--border); border-radius:8px; padding:14px 16px; margin-bottom:14px` | -| `.profile-stats` | `display:grid; grid-template-columns:repeat(4,minmax(0,1fr)); gap:10px; margin-bottom:18px` | -| `.profile-columns` | `display:grid; grid-template-columns:minmax(0,1.3fr) minmax(240px,.7fr); gap:16px` | -| `.profile-panel` | `border:1px solid var(--border); border-radius:9px; padding:16px; margin-bottom:14px; min-width:0` | -| `.profile-panel-head` | `display:flex; gap:10px; margin-bottom:12px` | -| `.profile-panel-head h2` | `margin:0` | - -## Settings Sections - -| Selector | Exact size declarations | -| -------------------------- | -------------------------------------------------------- | -| `.settings-section` | `border-top:1px solid var(--border); padding:16px 0 5px` | -| `.settings-section-head` | `display:flex; gap:16px; margin-bottom:5px` | -| `.settings-section-head p` | `margin-top:3px` | -| `.settings-note` | `margin:0 0 8px` | - -## Responsive Section Overrides - -Media conditions and source order are retained. Repeated entries for the same selector represent separate source declarations or later overrides. - -| Selector | Media condition | Exact size declarations | -| ------------------------------ | ----------------- | ------------------------------------------------------------------------- | -| `.workspace-main-grid` | `max-width:860px` | `grid-template-columns:minmax(0,1fr)` | -| `.page` | `max-width:640px` | `padding:18px 16px 40px` | -| `.workspace-hero` | `max-width:640px` | `display:block; padding:16px` | -| `.workspace-hero.is-populated` | `max-width:640px` | First: `padding:12px 14px`; later: `padding:10px 12px; margin-bottom:8px` | -| `.workspace-control-strip` | `max-width:640px` | `gap:8px; padding:8px 10px; margin-bottom:10px` | -| `.teams-header` | `max-width:640px` | First: `display:grid; gap:10px`; later: `gap:6px; margin-bottom:12px` | -| `.teams-header-actions` | `max-width:640px` | `width:100%` | -| `.team-bottom-grid` | `max-width:640px` | `grid-template-columns:minmax(0,1fr)` | -| `.profile-hero` | `max-width:640px` | `grid-template-columns:48px minmax(0,1fr); padding:12px; gap:8px 11px` | -| `.profile-stats` | `max-width:640px` | `grid-template-columns:repeat(2,minmax(0,1fr)); gap:8px` | -| `.profile-columns` | `max-width:640px` | `grid-template-columns:1fr; gap:0` | -| `.profile-panel` | `max-width:640px` | `padding:13px` | -| `.workspace-section` | `max-width:640px` | `margin-bottom:14px` | -| `.workspace-section-head` | `max-width:640px` | `margin-bottom:7px` | -| `.team-members-panel` | `max-width:640px` | `margin-bottom:10px` | -| `.settings-intro` | `max-width:640px` | `margin-bottom:12px` | -| `.settings-intro h1` | `max-width:640px` | `margin-bottom:3px` | -| `.settings-section` | `max-width:640px` | `padding:11px 0 3px` | -| `.settings-section-head` | `max-width:640px` | `gap:8px; margin-bottom:3px` | -| `.settings-note` | `max-width:640px` | `margin-bottom:5px` | - -## Isolated Mock-Tool Subsections - -These rules are local to their iframe documents and are not host section tokens. - -| Preview | Selector | Exact size declarations | -| ------------ | ---------------------------- | ---------------------------------------------------------------------------------------------- | -| Color Picker | `.wrap` | `padding:24px; display:grid; grid-template-columns:200px 1fr; gap:24px; flex:1; overflow:auto` | -| Color Picker | `.vals` | `display:flex; gap:12px` | -| Color Picker | `.wrap` at `max-width:520px` | `grid-template-columns:minmax(0,1fr); padding:16px; gap:16px` | -| SQL Studio | `.sb-scroll` | `flex:1; overflow-y:auto; padding:6px 0` | -| SQL Studio | `.sb-section` | `padding:8px 12px 4px` | -| SQL Studio | `.sb-section-title` | `padding:2px 6px 6px; display:flex; gap:6px` | -| SQL Studio | `.sb-section-title .n` | `padding:1px 6px; border-radius:8px` | - -## Inline And Coverage Notes - -- No inline geometric size declarations were found on rendered host section wrappers or mock iframe section wrappers. -- Section headings' font sizes are documented in the font ledgers, not duplicated here. Section surface/card radii and card-only sizing remain indexed in [`cards.size.md`](cards.size.md). -- Exact CSS values are preserved from raw declarations; rendered pixel heights are not inferred from content. -- Refresh this audit whenever section structure or sizing in `sandbox/index.html` changes. This is a source inventory, not a production design-system contract. diff --git a/public/assets/aistudio/Spacing.size_c65fdee7.md b/public/assets/aistudio/Spacing.size_c65fdee7.md deleted file mode 100644 index 3a63fa6..0000000 --- a/public/assets/aistudio/Spacing.size_c65fdee7.md +++ /dev/null @@ -1,236 +0,0 @@ -# Sandbox Spacing-Size Tokens - -## Audit Scope - -Source: canonical [`sandbox/index.html`](../index.html). This review-only ledger inventories authored spacing declarations; it does not define production tokens or authorize additional UI migration. - -Tracked CSS properties are `margin*`, `padding*`, `gap`, `row-gap`, `column-gap`, `top`, `right`, `bottom`, `left`, `inset*`, `scroll-margin*`, and `scroll-padding*`. Values remain literal, including shorthands, `auto`, percentages, `calc()`, and safe-area expressions. Host CSS, all 13 generated mock-tool iframe stylesheets, literal inline attributes, and JavaScript-assigned offsets are counted separately. CSS values retain their source selectors/media context; this token table groups occurrences by exact property/value to avoid repeating multi-property rules. - -The extraction found 498 host CSS declarations, 132 iframe CSS declarations, 10 spacing declarations in 32 literal `style` attributes, and 2 JavaScript-assigned offsets: 642 source declarations and 222 unique property/value pairs. Inline counts are source-literal occurrences, not repeated runtime renders. - -## Exact Token Inventory - -| Property | Exact source value | Host CSS | Iframe CSS | Host inline | Iframe inline | JS assignment | Total | -| ----------------- | ------------------------------------------------- | -------: | ---------: | ----------: | ------------: | ------------: | ----: | -| bottom | `0` | 1 | 0 | 0 | 0 | 0 | 1 | -| bottom | `36px` | 1 | 0 | 0 | 0 | 0 | 1 | -| bottom | `calc(64px + env(safe-area-inset-bottom))` | 1 | 0 | 0 | 0 | 0 | 1 | -| gap | `0` | 3 | 0 | 0 | 0 | 0 | 3 | -| gap | `10px` | 23 | 4 | 0 | 0 | 0 | 27 | -| gap | `10px 14px` | 1 | 0 | 0 | 0 | 0 | 1 | -| gap | `11px` | 4 | 0 | 0 | 0 | 0 | 4 | -| gap | `12px` | 8 | 3 | 0 | 0 | 0 | 11 | -| gap | `14px` | 5 | 0 | 0 | 0 | 0 | 5 | -| gap | `16px` | 3 | 1 | 0 | 1 | 0 | 5 | -| gap | `18px` | 1 | 0 | 0 | 0 | 0 | 1 | -| gap | `1px` | 2 | 1 | 0 | 0 | 0 | 3 | -| gap | `20px` | 4 | 0 | 0 | 0 | 0 | 4 | -| gap | `24px` | 0 | 1 | 0 | 0 | 0 | 1 | -| gap | `2px` | 5 | 0 | 0 | 0 | 0 | 5 | -| gap | `34px` | 1 | 0 | 0 | 0 | 0 | 1 | -| gap | `3px` | 5 | 0 | 0 | 0 | 0 | 5 | -| gap | `4px` | 6 | 0 | 0 | 0 | 0 | 6 | -| gap | `4px 9px` | 1 | 0 | 0 | 0 | 0 | 1 | -| gap | `5px` | 13 | 1 | 0 | 0 | 0 | 14 | -| gap | `5px 12px` | 1 | 0 | 0 | 0 | 0 | 1 | -| gap | `6px` | 19 | 4 | 0 | 4 | 0 | 27 | -| gap | `7px` | 16 | 1 | 0 | 0 | 0 | 17 | -| gap | `8px` | 31 | 5 | 0 | 0 | 0 | 36 | -| gap | `8px 11px` | 1 | 0 | 0 | 0 | 0 | 1 | -| gap | `9px` | 14 | 1 | 0 | 0 | 0 | 15 | -| inset | `0` | 3 | 0 | 0 | 0 | 0 | 3 | -| left | `-7px` | 1 | 0 | 0 | 0 | 0 | 1 | -| left | `0` | 2 | 0 | 0 | 0 | 1 | 3 | -| left | `46px` | 1 | 0 | 0 | 0 | 0 | 1 | -| left | `50%` | 1 | 0 | 0 | 0 | 0 | 1 | -| left | `52px` | 1 | 0 | 0 | 0 | 0 | 1 | -| left | `8px` | 2 | 0 | 0 | 0 | 0 | 2 | -| left | `auto` | 1 | 0 | 0 | 0 | 0 | 1 | -| margin | `-1px` | 1 | 0 | 0 | 0 | 0 | 1 | -| margin | `0` | 4 | 16 | 0 | 0 | 0 | 20 | -| margin | `0 0 12px` | 1 | 0 | 0 | 0 | 0 | 1 | -| margin | `0 0 20px` | 0 | 8 | 0 | 0 | 0 | 8 | -| margin | `0 0 4px` | 0 | 1 | 0 | 0 | 0 | 1 | -| margin | `0 0 6px` | 2 | 0 | 0 | 0 | 0 | 2 | -| margin | `0 0 8px` | 2 | 8 | 0 | 0 | 0 | 10 | -| margin | `0 10px 8px` | 1 | 0 | 0 | 0 | 0 | 1 | -| margin | `0 14px 10px` | 1 | 0 | 0 | 0 | 0 | 1 | -| margin | `0 2px` | 1 | 0 | 0 | 0 | 0 | 1 | -| margin | `0 2px 8px` | 1 | 0 | 0 | 0 | 0 | 1 | -| margin | `0 auto` | 1 | 0 | 0 | 0 | 0 | 1 | -| margin | `0 auto 20px` | 0 | 8 | 0 | 0 | 0 | 8 | -| margin | `12px 0` | 1 | 0 | 0 | 0 | 0 | 1 | -| margin | `16px 0 9px` | 1 | 0 | 0 | 0 | 0 | 1 | -| margin | `22px 0 10px` | 1 | 0 | 0 | 0 | 0 | 1 | -| margin | `5px 2px` | 1 | 0 | 0 | 0 | 0 | 1 | -| margin | `6px 0` | 1 | 0 | 0 | 0 | 0 | 1 | -| margin | `9px 0 0 38px` | 2 | 0 | 0 | 0 | 0 | 2 | -| margin | `auto` | 1 | 0 | 0 | 0 | 0 | 1 | -| margin-bottom | `0` | 2 | 0 | 0 | 0 | 0 | 2 | -| margin-bottom | `10px` | 5 | 0 | 0 | 0 | 0 | 5 | -| margin-bottom | `11px` | 1 | 0 | 0 | 0 | 0 | 1 | -| margin-bottom | `12px` | 7 | 1 | 0 | 0 | 0 | 8 | -| margin-bottom | `14px` | 7 | 0 | 0 | 0 | 0 | 7 | -| margin-bottom | `16px` | 1 | 2 | 0 | 0 | 0 | 3 | -| margin-bottom | `18px` | 6 | 0 | 0 | 0 | 0 | 6 | -| margin-bottom | `20px` | 2 | 1 | 0 | 0 | 0 | 3 | -| margin-bottom | `22px` | 2 | 0 | 0 | 0 | 0 | 2 | -| margin-bottom | `26px` | 1 | 0 | 0 | 0 | 0 | 1 | -| margin-bottom | `28px` | 1 | 0 | 0 | 0 | 0 | 1 | -| margin-bottom | `2px` | 3 | 0 | 0 | 0 | 0 | 3 | -| margin-bottom | `32px` | 1 | 0 | 0 | 0 | 0 | 1 | -| margin-bottom | `3px` | 5 | 0 | 0 | 0 | 0 | 5 | -| margin-bottom | `4px` | 4 | 0 | 0 | 1 | 0 | 5 | -| margin-bottom | `5px` | 5 | 0 | 0 | 0 | 0 | 5 | -| margin-bottom | `6px` | 1 | 0 | 0 | 0 | 0 | 1 | -| margin-bottom | `7px` | 6 | 0 | 0 | 0 | 0 | 6 | -| margin-bottom | `8px` | 4 | 0 | 0 | 0 | 0 | 4 | -| margin-left | `0` | 1 | 0 | 0 | 0 | 0 | 1 | -| margin-left | `36px` | 1 | 0 | 0 | 0 | 0 | 1 | -| margin-left | `3px` | 1 | 0 | 0 | 0 | 0 | 1 | -| margin-left | `43px` | 1 | 0 | 0 | 0 | 0 | 1 | -| margin-left | `6px` | 1 | 0 | 0 | 0 | 0 | 1 | -| margin-left | `auto` | 9 | 2 | 0 | 1 | 0 | 12 | -| margin-right | `3px` | 1 | 0 | 0 | 0 | 0 | 1 | -| margin-right | `4px` | 1 | 0 | 0 | 0 | 0 | 1 | -| margin-top | `0` | 1 | 0 | 0 | 0 | 0 | 1 | -| margin-top | `10px` | 2 | 0 | 0 | 0 | 0 | 2 | -| margin-top | `14px` | 1 | 0 | 0 | 0 | 0 | 1 | -| margin-top | `1px` | 1 | 0 | 0 | 0 | 0 | 1 | -| margin-top | `24px` | 0 | 8 | 0 | 0 | 0 | 8 | -| margin-top | `2px` | 4 | 0 | 0 | 0 | 0 | 4 | -| margin-top | `3px` | 12 | 0 | 0 | 0 | 0 | 12 | -| margin-top | `4px` | 3 | 0 | 0 | 0 | 0 | 3 | -| margin-top | `6px` | 2 | 0 | 1 | 0 | 0 | 3 | -| margin-top | `8px` | 5 | 1 | 0 | 0 | 0 | 6 | -| margin-top | `9px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `0` | 13 | 0 | 0 | 0 | 0 | 13 | -| padding | `0 10px` | 3 | 0 | 0 | 0 | 0 | 3 | -| padding | `0 12px` | 1 | 1 | 0 | 0 | 0 | 2 | -| padding | `0 14px` | 3 | 0 | 0 | 0 | 0 | 3 | -| padding | `0 20px 20px` | 0 | 1 | 0 | 0 | 0 | 1 | -| padding | `0 3px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `0 6px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `0 8px 0 12px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `0 9px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `10px` | 5 | 0 | 0 | 0 | 0 | 5 | -| padding | `10px 0` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `10px 10px 0` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `10px 12px` | 2 | 0 | 0 | 0 | 0 | 2 | -| padding | `10px 14px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `10px 16px` | 0 | 1 | 0 | 0 | 0 | 1 | -| padding | `10px 18px` | 0 | 1 | 0 | 0 | 0 | 1 | -| padding | `10px 20px` | 0 | 1 | 0 | 0 | 0 | 1 | -| padding | `11px 0 3px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `11px 12px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `11px 14px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `11px 16px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `12px` | 6 | 0 | 0 | 0 | 0 | 6 | -| padding | `12px 0` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `12px 14px` | 1 | 2 | 0 | 0 | 0 | 3 | -| padding | `12px 16px` | 0 | 2 | 0 | 0 | 0 | 2 | -| padding | `13px` | 3 | 0 | 0 | 0 | 0 | 3 | -| padding | `13px 15px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `14px` | 3 | 1 | 0 | 0 | 0 | 4 | -| padding | `14px 0` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `14px 10px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `14px 14px 0` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `14px 14px 10px` | 0 | 1 | 0 | 0 | 0 | 1 | -| padding | `14px 16px` | 3 | 0 | 0 | 0 | 0 | 3 | -| padding | `14px 18px` | 1 | 1 | 0 | 0 | 0 | 2 | -| padding | `14px 20px` | 0 | 1 | 0 | 0 | 0 | 1 | -| padding | `15px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `15px 10px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `16px` | 3 | 1 | 0 | 0 | 0 | 4 | -| padding | `16px 0 5px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `16px 20px` | 0 | 2 | 0 | 0 | 0 | 2 | -| padding | `18px 12px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `18px 16px 40px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `1px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `1px 4px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `1px 5px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `1px 6px` | 1 | 2 | 0 | 0 | 0 | 3 | -| padding | `20px` | 0 | 1 | 0 | 0 | 0 | 1 | -| padding | `20px 16px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `22px 24px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `24px` | 0 | 2 | 0 | 0 | 0 | 2 | -| padding | `26px 18px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `26px 30px 40px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `2px` | 1 | 1 | 0 | 0 | 0 | 2 | -| padding | `2px 3px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `2px 4px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `2px 5px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `2px 6px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `2px 6px 6px` | 0 | 1 | 0 | 0 | 0 | 1 | -| padding | `2px 7px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `2px 7px 5px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `30px` | 0 | 8 | 0 | 0 | 0 | 8 | -| padding | `3px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `3px 4px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `3px 5px 6px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `3px 6px` | 2 | 0 | 0 | 0 | 0 | 2 | -| padding | `3px 7px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `4px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `4px 0` | 2 | 0 | 0 | 0 | 0 | 2 | -| padding | `4px 6px` | 4 | 0 | 0 | 0 | 0 | 4 | -| padding | `4px 6px calc(4px + env(safe-area-inset-bottom))` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `4px 9px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `5px 12px` | 0 | 1 | 0 | 0 | 0 | 1 | -| padding | `5px 14px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `5px 7px` | 4 | 0 | 0 | 0 | 0 | 4 | -| padding | `5px 8px` | 4 | 1 | 0 | 1 | 0 | 6 | -| padding | `5px 9px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `6px` | 2 | 0 | 0 | 0 | 0 | 2 | -| padding | `6px 0` | 0 | 1 | 0 | 0 | 0 | 1 | -| padding | `6px 0 3px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `6px 12px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `6px 14px` | 0 | 2 | 0 | 0 | 0 | 2 | -| padding | `6px 7px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `6px 8px` | 5 | 0 | 0 | 0 | 0 | 5 | -| padding | `6px 9px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `7px 0` | 2 | 0 | 0 | 0 | 0 | 2 | -| padding | `7px 14px` | 1 | 2 | 0 | 0 | 0 | 3 | -| padding | `7px 8px` | 2 | 0 | 0 | 0 | 0 | 2 | -| padding | `7px 9px` | 3 | 0 | 0 | 0 | 0 | 3 | -| padding | `8px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `8px 0` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `8px 10px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `8px 12px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `8px 12px 4px` | 0 | 1 | 0 | 0 | 0 | 1 | -| padding | `8px 14px` | 0 | 13 | 0 | 0 | 0 | 13 | -| padding | `8px 14px 5px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `8px 6px 10px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `8px 8px 3px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `8px 9px` | 2 | 0 | 0 | 0 | 0 | 2 | -| padding | `9px` | 2 | 0 | 0 | 0 | 0 | 2 | -| padding | `9px 0` | 2 | 0 | 0 | 0 | 0 | 2 | -| padding | `9px 10px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `9px 14px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding-inline | `10px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding-inline | `11px` | 4 | 0 | 0 | 0 | 0 | 4 | -| padding-inline | `3px` | 2 | 0 | 0 | 0 | 0 | 2 | -| padding-inline | `4px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding-inline | `5px` | 2 | 0 | 0 | 0 | 0 | 2 | -| padding-inline | `6px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding-inline | `7px` | 2 | 0 | 0 | 0 | 0 | 2 | -| padding-inline | `8px` | 2 | 0 | 0 | 0 | 0 | 2 | -| padding-top | `4px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding-top | `6px` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding-top | `9px` | 1 | 0 | 0 | 0 | 0 | 1 | -| right | `0` | 1 | 0 | 0 | 0 | 0 | 1 | -| right | `14px` | 1 | 0 | 0 | 0 | 0 | 1 | -| right | `16px` | 1 | 0 | 0 | 0 | 0 | 1 | -| right | `3px` | 1 | 0 | 0 | 0 | 0 | 1 | -| right | `8px` | 2 | 0 | 0 | 0 | 0 | 2 | -| scroll-margin-top | `18px` | 1 | 0 | 0 | 0 | 0 | 1 | -| top | `0` | 4 | 1 | 0 | 0 | 1 | 6 | -| top | `31px` | 0 | 1 | 0 | 0 | 0 | 1 | -| top | `3px` | 1 | 0 | 0 | 0 | 0 | 1 | -| top | `50%` | 2 | 0 | 0 | 0 | 0 | 2 | -| top | `50px` | 1 | 0 | 0 | 0 | 0 | 1 | -| top | `52px` | 1 | 0 | 0 | 0 | 0 | 1 | -| top | `auto` | 2 | 0 | 0 | 0 | 0 | 2 | -| top | `calc(100% + 21px)` | 1 | 0 | 0 | 0 | 0 | 1 | -| top | `calc(100% + 6px)` | 1 | 0 | 0 | 0 | 0 | 1 | -| top | `calc(100% + 7px)` | 1 | 0 | 0 | 0 | 0 | 1 | -| padding | `40px 10px` | 0 | 0 | 1 | 0 | 0 | 1 | diff --git a/public/assets/aistudio/border.styles.size_371201e0.md b/public/assets/aistudio/border.styles.size_371201e0.md deleted file mode 100644 index 8ea609f..0000000 --- a/public/assets/aistudio/border.styles.size_371201e0.md +++ /dev/null @@ -1,71 +0,0 @@ -# Sandbox Border Styles And Size Tokens - -## Audit Scope - -Source: canonical [`sandbox/index.html`](../index.html). This review-only ledger records authored `border*` CSS declarations and exact values; it does not define production tokens or authorize additional UI migration. - -Included properties are `border`, side borders, `border-color`, `border-radius`, and `border-collapse`, including declarations inside responsive media rules and all 13 generated mock-tool iframe stylesheets. CSS custom-property definitions are not border declarations; references such as `var(--border)` are preserved verbatim. `outline*` and `box-shadow` are separate CSS properties and are excluded. - -The raw extraction found 256 host CSS declarations and 71 iframe CSS declarations, for 327 total declarations and 50 unique property/value pairs. A full-source scan of 32 literal inline `style` attributes found no border declarations. No JavaScript-assigned border properties were found. Preview declarations are counted per generated iframe document, including repeated generic preview styles. - -## Exact Border Property/Value Inventory - -| Property | Exact source value | Host CSS | Iframe CSS | Total | -| ----------------- | ------------------------------------ | -------: | ---------: | ----: | -| `border` | `0` | 20 | 0 | 20 | -| `border` | `1px dashed var(--border-strong)` | 4 | 0 | 4 | -| `border` | `1px solid transparent` | 3 | 0 | 3 | -| `border` | `1px solid var(--accent-border)` | 1 | 0 | 1 | -| `border` | `1px solid var(--border-palette)` | 1 | 0 | 1 | -| `border` | `1px solid var(--border-strong)` | 23 | 0 | 23 | -| `border` | `1px solid var(--border)` | 24 | 0 | 24 | -| `border` | `1px solid var(--frame-border)` | 0 | 15 | 15 | -| `border` | `1px solid var(--success-border)` | 1 | 0 | 1 | -| `border` | `1px solid var(--warning-border)` | 1 | 0 | 1 | -| `border` | `2px solid transparent` | 1 | 0 | 1 | -| `border` | `2px solid var(--bg-main)` | 2 | 0 | 2 | -| `border` | `none` | 10 | 6 | 16 | -| `border-bottom` | `0` | 3 | 0 | 3 | -| `border-bottom` | `1px solid var(--border-strong)` | 1 | 0 | 1 | -| `border-bottom` | `1px solid var(--border)` | 10 | 0 | 10 | -| `border-bottom` | `1px solid var(--frame-border-soft)` | 0 | 1 | 1 | -| `border-bottom` | `1px solid var(--frame-border)` | 0 | 11 | 11 | -| `border-bottom` | `none` | 1 | 0 | 1 | -| `border-collapse` | `collapse` | 1 | 1 | 2 | -| `border-color` | `var(--accent-border)` | 1 | 0 | 1 | -| `border-color` | `var(--accent-hover)` | 1 | 0 | 1 | -| `border-color` | `var(--accent)` | 9 | 0 | 9 | -| `border-color` | `var(--bg-main)` | 1 | 0 | 1 | -| `border-color` | `var(--border-strong)` | 7 | 0 | 7 | -| `border-color` | `var(--danger-border)` | 1 | 0 | 1 | -| `border-color` | `var(--red)` | 1 | 0 | 1 | -| `border-left` | `2px solid var(--accent)` | 1 | 0 | 1 | -| `border-left` | `3px solid var(--accent)` | 1 | 0 | 1 | -| `border-radius` | `0 0 3px 3px` | 1 | 0 | 1 | -| `border-radius` | `0 3px 3px 0` | 1 | 0 | 1 | -| `border-radius` | `10px` | 3 | 3 | 6 | -| `border-radius` | `12px` | 1 | 0 | 1 | -| `border-radius` | `16px` | 0 | 2 | 2 | -| `border-radius` | `18px` | 1 | 0 | 1 | -| `border-radius` | `20px` | 2 | 8 | 10 | -| `border-radius` | `2px` | 1 | 0 | 1 | -| `border-radius` | `3px` | 1 | 1 | 2 | -| `border-radius` | `4px` | 17 | 0 | 17 | -| `border-radius` | `50%` | 9 | 3 | 12 | -| `border-radius` | `5px` | 26 | 2 | 28 | -| `border-radius` | `6px` | 17 | 3 | 20 | -| `border-radius` | `7px` | 17 | 0 | 17 | -| `border-radius` | `8px` | 9 | 13 | 22 | -| `border-radius` | `9px` | 5 | 0 | 5 | -| `border-right` | `0` | 1 | 0 | 1 | -| `border-right` | `1px solid var(--border)` | 3 | 0 | 3 | -| `border-right` | `1px solid var(--frame-border)` | 0 | 2 | 2 | -| `border-right` | `none` | 1 | 0 | 1 | -| `border-top` | `1px solid var(--border)` | 10 | 0 | 10 | - -## Coverage Notes - -- Exact shorthand and side-border declarations are retained rather than expanded into inferred width/style/color values. -- Host and iframe counts are separate. Iframe counts represent generated per-tool documents; repeated generic preview CSS is counted in each generated document. -- Border color custom properties are referenced but not resolved here; their theme values belong to the token/color inventory. -- Refresh this audit when border-related rules or preview documents in `sandbox/index.html` change. No prototype or production styling was changed for this audit. diff --git a/public/assets/aistudio/buttons.size_70a5c466.md b/public/assets/aistudio/buttons.size_70a5c466.md deleted file mode 100644 index cf3dcb3..0000000 --- a/public/assets/aistudio/buttons.size_70a5c466.md +++ /dev/null @@ -1,146 +0,0 @@ -# Sandbox Button-Size Tokens - -## Audit Scope - -Source: canonical [`sandbox/index.html`](../index.html). This is a review-only inventory of source-authored sizing for button controls. It does not change the prototype or production styles. - -The extraction matched button elements rendered by host navigation, sidebars, tabs, views, dialogs, runner controls, and conditional team actions; it also parsed the generated button markup/styles for all 13 mock-tool previews. Responsive CSS rules are included even when their media query is not active in the current browser. Host and iframe scopes remain separate. - -Sizing scope includes button box constraints, padding and gaps, flex sizing, button font sizing, border radius, associated active-state marks, and direct child SVG icon dimensions. Global reset values and button inline sizing are included. Other child content typography is covered by [`fonts.md`](fonts.md) and [`fonts.size.md`](fonts.size.md), not repeated here. - -## Host Button Rules - -Values below are copied from the source declarations; selector order and media conditions distinguish base rules from overrides. `font:inherit` is an inherited sizing instruction, not a fixed dimension. - -| Selector | Exact size-related declarations | -| -------------------------------- | ------------------------------------------------------------------------------------------------------------------- | -| `*` | `box-sizing:border-box; margin:0; padding:0` | -| `.workspace-selector-btn` | `max-width:180px; gap:5px; padding:4px 6px; border-radius:5px; font:inherit` | -| `.workspace-menu-select` | `min-width:0; min-height:28px; flex:1; gap:7px; padding:4px 6px; border-radius:4px; font:inherit; font-size:11.5px` | -| `.workspace-menu-icon` | `width:24px; height:24px; flex:none; border-radius:4px` | -| `.workspace-menu-action` | `width:100%; min-height:32px; gap:8px; padding:5px 8px; border-radius:4px; font:inherit; font-size:11.5px` | -| `.titlebar-theme-toggle` | `width:32px; height:32px; flex:none; border-radius:6px` | -| `.titlebar-search` | `height:32px; gap:8px; border-radius:6px; padding:0 10px; font-size:11.5px` | -| `.titlebar-menu-toggle` | `width:32px; height:32px; border-radius:6px` | -| `.mobile-nav-item` | `width:100%; min-height:34px; gap:8px; padding:6px 8px; border-radius:4px; font:inherit; font-size:12px` | -| `.act-btn` | `width:38px; height:38px; border-radius:9px` | -| `.act-btn.active::before` | `width:3px; height:20px; border-radius:0 3px 3px 0` | -| `.act-btn::after` | `padding:5px 9px; border-radius:5px; font-size:11.5px` | -| `.avatar` | `width:30px; height:30px; border-radius:50%; font-size:11.5px` | -| `.side-item` | `width:100%; min-height:32px; gap:8px; padding:5px 7px; border-radius:5px; font-size:12.5px` | -| `.route-nav-btn` | `gap:6px` | -| `.fav-item` | `width:100%; gap:8px; padding:6px 8px; border-radius:5px; font:inherit` | -| `.tab-close` | `width:18px; height:18px; border-radius:4px` | -| `.workspace-starter` | `min-height:90px; gap:11px; padding:13px; border-radius:7px` | -| `.workspace-stack-button` | `padding:4px 6px; border-radius:4px; font:inherit; font-size:9.5px` | -| `.workspace-sidebar-item` | `width:100%; min-height:30px; gap:7px; padding:5px 7px; border-radius:5px; font:inherit; font-size:11.5px` | -| `.team-member-actions .icon-btn` | `width:27px; height:27px` | -| `.collection-item` | `width:100%; font:inherit` | -| `.collection-card` | `min-height:64px; gap:10px; padding:10px; border-radius:6px; font:inherit` | -| `.collection-tool-main` | `min-width:0; flex:1; gap:9px; padding:0; font:inherit` | -| `.collection-add-actions .btn` | `flex:none` | -| `.tc-play` | `width:26px; height:26px; border-radius:6px; margin-left:auto` | -| `.btn` | `height:32px; gap:7px; padding:0 14px; border-radius:7px; font-size:12.5px` | -| `.btn.sm` | `height:27px; padding:0 10px; font-size:11.5px` | -| `.icon-btn` | `width:30px; height:30px; border-radius:7px` | -| `.back-btn` | `gap:6px; padding:4px 0; font-size:12.5px; margin-bottom:20px` | -| `.rv-name` | `padding:0; font-size:12.5px` | -| `.rv-foot button` | `padding:0; font-size:11.5px` | -| `.review-rating-options button` | `width:26px; height:26px; padding:0; border-radius:4px` | -| `.review-compose-footer .btn` | `height:28px; padding-inline:11px; font-size:11.5px` | -| `.profile-back` | `margin-bottom:14px` | -| `.profile-side-link` | `min-height:30px; font-size:11.5px` | -| `.profile-tool` | `width:100%; gap:10px; padding:9px; border-radius:7px` | - -## Host Responsive Overrides - -All overrides below are under `@media (max-width:640px)` and retain source order. Where a selector repeats `min-height`, the later declaration wins at this breakpoint. - -| Selector | Exact size-related declarations | -| ---------------------------------------------- | ------------------------------------------------------------------------------------------ | -| `.workspace-selector-btn` | `max-width:104px; padding-inline:5px` | -| `.titlebar-search` | `width:34px; height:34px; padding:0; border-radius:8px` | -| `.titlebar-theme-toggle` | `width:34px; height:34px; border-radius:8px` | -| `.act-btn` | `flex:1 1 0; width:auto; min-width:0; height:52px; gap:3px; border-radius:7px` | -| `.act-btn::after` | `padding:0; font-size:9.5px` | -| `.act-btn.active::before` | `width:18px; height:3px; border-radius:0 0 3px 3px` | -| `.avatar` | `flex:0 0 32px; width:30px; height:30px` | -| `.runner-actions .icon-btn` | `width:26px; height:30px; flex:0 0 26px` | -| `.detail-actions .btn` | `height:32px; min-width:0; padding-inline:8px; font-size:11px` | -| `.workspace-starter` | First override: `min-height:68px`; later override: `min-height:60px; padding:9px; gap:7px` | -| `.profile-actions .btn` | `flex:1; min-width:0; height:30px; padding-inline:8px; font-size:11px` | -| `.workspace-control-actions .btn` | `min-height:30px; padding-inline:7px; font-size:10px` | -| `.team-member-actions .icon-btn` | `width:24px; height:24px` | -| `.team-access-share .btn` | `padding-inline:7px; font-size:9.5px` | -| `.settings-section .profile-form-actions .btn` | `flex:1; min-width:0; padding-inline:6px; font-size:9.5px` | - -## Button Content And Icons - -These rules size icons within buttons, separately from the button hit area. `icon()` also writes explicit equal width/height attributes into generated SVG markup. - -| Selector | Exact size declarations | -| ---------------------------- | -------------------------------------------------------------------------- | -| `.workspace-menu-icon svg` | `width:13px; height:13px` | -| `.workspace-menu-action svg` | `width:14px; height:14px` | -| `.titlebar-theme-toggle svg` | `width:15px; height:15px` | -| `.titlebar-search svg` | `width:14px; height:14px` | -| `.titlebar-menu-toggle svg` | `width:16px; height:16px` | -| `.mobile-nav-item svg` | `width:15px; height:15px` | -| `.act-btn svg` | Base: `width:21px; height:21px`; phone override: `width:20px; height:20px` | -| `.profile-side-link svg` | `width:15px; height:15px` | - -Equal SVG width/height attributes present in rendered host button markup use these exact values: `10px`, `11px`, `12px`, `13px`, `14px`, `15px`, `16px`, `17px`, and `20px`. CSS overrides the activity icon attribute to `21px` on desktop and `20px` on phones. - -Button-adjacent text sizing that affects control content is separately declared by `.titlebar-search kbd` (`font-size:9.5px; padding:2px 4px; border-radius:4px`), `.workspace-starter kbd` (`font-size:9px; padding:2px 5px; border-radius:4px`), and `.route-badge` (`font-size:9px; padding:1px 5px; border-radius:4px`). The controls inherit their surrounding font where the rule says `font:inherit`. - -### Nested Button Content Sizing - -These child rules set fixed dimensions or spacing for content inside a button. Child font sizes are already recorded in the font inventories. - -| Selector | Exact size-related declarations | -| ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | -| `.workspace-menu-check` | `width:14px; flex:none` | -| `.act-badge` | `min-width:14px; height:14px; border-radius:7px; padding:0 3px` | -| `.route-arrow`, `.route-card-arrow` | `flex:none` | -| `.route-nav-btn>svg:last-child`, `.route-badge svg`, `.profile-tool>svg:last-child` | `flex:none` | -| `.route-badge` | `gap:3px; padding:1px 5px; border-radius:4px` | -| `.side-item .count` | `padding:1px 6px; border-radius:9px` | -| `.fav-glyph` | `width:26px; height:26px; border-radius:6px` | -| `.workspace-starter-icon` | `width:32px; height:32px; flex:none; border-radius:6px`; phone override: `width:28px; height:28px` | -| `.workspace-starter kbd` | `flex:none; padding:2px 5px; border-radius:4px` | -| `.workspace-sidebar-item svg` | `flex:none` | -| `.workspace-sidebar-item span` | `min-width:0; flex:1` | -| `.workspace-sidebar-item small` | `flex:none` | -| `.collection-card-mark` | `width:32px; height:32px; flex:none; border-radius:5px` | -| `.collection-card-copy`, `.collection-tool-copy`, `.profile-tool-copy` | `min-width:0; flex:1` | -| `.tc-glyph` | `width:40px; height:40px; border-radius:9px` | -| `.profile-tool .fav-glyph` | `width:32px; height:32px` | -| `.workspace-selector-label` | Phone override: `max-width:72px` | - -## Mock-Tool Button Rules - -Each preview document is isolated from host styles. `*` sets `box-sizing:border-box` in all 13 generated preview documents. Only these preview documents author button-specific box sizing; other previews use browser-native button defaults. - -| Preview | Selector | Exact size-related declarations | -| ------------------- | --------------------- | ---------------------------------------------------------------- | -| JSON Formatter | `button` | `padding:6px 14px; border-radius:6px; font-size:13px` | -| Password Generator | `button` | `padding:10px 16px; border-radius:10px; font-size:13px` | -| Password Generator | second `button.ghost` | Inline `width:100%`; its `.ghost` rule changes color only | -| Text Case Converter | `button` | `padding:8px 14px; border-radius:8px; font-size:13px` | -| SQL Studio | `.btn` | `padding:7px 14px; border-radius:6px; font-size:12.5px; gap:5px` | - -The named preview rules apply to every button in that document (`button.ghost` inherits the Password Generator base button sizing). `genericToolDoc()` and the other preview documents define no button-specific dimensions. - -## Literal Inline Button Sizing - -| Scope | Button | Exact inline declaration | -| -------------------------- | ----------------------------------------- | ------------------------ | -| Host | Collections sidebar New collection action | `margin-top:6px` | -| Password Generator preview | Generate new password | `width:100%` | - -## Coverage Notes - -- Extracted the raw CSS declaration text after matching actual button classes from all host views, menus, dialogs, tabs, tool details, runner headers, and conditional team-member actions. This preserves source shorthands such as `padding`, `font`, `flex`, and `border-radius` rather than CSSOM-expanded longhands. -- Included the responsive phone overrides, associated active-state marks, child SVG CSS/attributes, and the two literal inline size declarations. -- Native browser defaults are not assigned invented token values. Seven generated preview documents contain no authored button geometry and therefore rely on their isolated document's browser defaults. -- This file inventories source values only; it does not propose a shared production button system. Refresh it whenever button markup or sizing in `sandbox/index.html` changes. diff --git a/public/assets/aistudio/cards.size_9ff56b47.md b/public/assets/aistudio/cards.size_9ff56b47.md deleted file mode 100644 index 5d2223c..0000000 --- a/public/assets/aistudio/cards.size_9ff56b47.md +++ /dev/null @@ -1,135 +0,0 @@ -# Sandbox Card-Size Tokens - -## Audit Scope - -Source: canonical [`sandbox/index.html`](../index.html). This is a review-only inventory of card and card-like surface geometry; it does not modify prototype or production styling. - -The inventory keeps host workbench CSS separate from generated mock-tool iframe CSS. It covers outer surface dimensions, parent grid tracks/gaps that determine card size, padding and margins, border thickness/radii, and responsive overrides. Text typography is recorded in [`fonts.md`](fonts.md) and [`fonts.size.md`](fonts.size.md), not repeated here. Colors and shadows are not size tokens. - -## Host Page Bounds And Card Grids - -| Selector | Exact size declarations | -| ------------------------- | ----------------------------------------------------------------------------- | -| `.page` | `max-width:1280px; padding:26px 30px 40px` | -| `.workspace-page` | `max-width:1160px` | -| `.teams-page` | `max-width:1040px` | -| `.team-subpage` | `max-width:760px` | -| `.profile-page` | `max-width:1080px` | -| `.settings-page` | `max-width:900px` | -| `.tool-grid` | `grid-template-columns:repeat(auto-fill,minmax(252px,1fr)); gap:12px` | -| `.workspace-main-grid` | `grid-template-columns:minmax(0,1.15fr) minmax(280px,.85fr); gap:14px` | -| `.workspace-starter-grid` | `grid-template-columns:repeat(3,minmax(0,1fr)); gap:10px; margin-bottom:22px` | -| `.workspace-dock-grid` | `grid-template-columns:repeat(auto-fill,minmax(180px,1fr)); gap:8px` | -| `.collection-card-grid` | `grid-template-columns:repeat(auto-fill,minmax(210px,1fr)); gap:9px` | -| `.team-bottom-grid` | `grid-template-columns:minmax(0,1.15fr) minmax(250px,.85fr); gap:12px` | -| `.profile-stats` | `grid-template-columns:repeat(4,minmax(0,1fr)); gap:10px; margin-bottom:18px` | -| `.profile-columns` | `grid-template-columns:minmax(0,1.3fr) minmax(240px,.7fr); gap:16px` | - -## Host Card Surfaces - -Values are literal source declarations. Where one surface has both a border and radius, both are listed to preserve the complete frame geometry. - -| Surface | Exact size declarations | -| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `.workspace-hero` | `gap:20px; padding:22px 24px; margin-bottom:18px; border:1px solid var(--border); border-radius:8px` | -| `.workspace-hero.is-populated` | `padding:14px 18px; margin-bottom:12px` | -| `.workspace-control-strip` | `gap:10px; padding:10px 12px; margin-bottom:18px; border:1px solid var(--border); border-radius:7px` | -| `.workspace-starter` | `min-height:90px; gap:11px; padding:13px; border:1px solid var(--border); border-radius:7px` | -| `.workspace-starter-icon` | `width:32px; height:32px; flex:none; border-radius:6px` | -| `.workspace-dock-card` | `min-width:0; gap:9px; padding:10px; border:1px solid var(--border); border-radius:7px` | -| `.workspace-dock-glyph` | `width:30px; height:30px; border-radius:6px` | -| `.workspace-empty` | `padding:20px 16px; border:1px dashed var(--border-strong); border-radius:7px` | -| `.workspace-sidebar-card` | `padding:10px; margin:0 2px 8px; border:1px solid var(--border); border-radius:6px` | -| `.team-members-panel` | `min-width:0; margin-bottom:14px; border:1px solid var(--border); border-radius:7px; overflow:hidden` | -| `.team-panel-head-inset` | `padding:14px 14px 0` | -| `.team-panel-head` | `gap:10px; margin-bottom:12px` | -| `.team-empty` | `padding:15px; border:1px dashed var(--border-strong); border-radius:6px` | -| `.team-panel` | `min-width:0; padding:14px; border:1px solid var(--border); border-radius:7px` | -| `.tool-card` | `border:1px solid var(--border); border-radius:10px; padding:14px` | -| `.collection-card` | `gap:10px; min-height:64px; padding:10px; border:1px solid var(--border); border-radius:6px` | -| `.collection-card-mark` | `width:32px; height:32px; flex:none; border-radius:5px` | -| `.collection-tool-card` | `gap:8px; padding:10px` | -| `.collection-add-tools` | `gap:10px; margin-top:14px; padding:12px; border:1px solid var(--border); border-radius:7px` | -| `.collection-add-options` | `grid-template-columns:repeat(2,minmax(0,1fr)); gap:6px; max-height:220px; padding:1px; overflow-y:auto` | -| `.collection-add-option` | `min-width:0; min-height:40px; gap:8px; padding:6px 8px; border:1px solid var(--border); border-radius:5px` | -| `.collection-add-count` | `padding:3px 6px; border-radius:4px` | -| `.collection-empty` | `padding:14px; border:1px dashed var(--border-strong); border-radius:6px` | -| `.detail-hero` | `display:flex; gap:20px; margin-bottom:28px` | -| `.review` | `border:1px solid var(--border); border-radius:9px; padding:13px 15px` | -| `.review-replies` | `gap:7px; margin:9px 0 0 38px` | -| `.review-reply` | `padding:8px 9px; border-left:2px solid var(--accent)` | -| `.review-composer` | `margin:0 0 12px; padding:12px; border:1px solid var(--border); border-radius:7px` | -| `.review-empty` | `padding:12px; border:1px dashed var(--border-strong); border-radius:7px` | -| `.profile-side-card` | `gap:8px; padding:8px 6px 10px; border-bottom:1px solid var(--border); margin-bottom:4px` | -| `.profile-hero` | `grid-template-columns:56px minmax(0,1fr) auto; gap:10px 14px; border:1px solid var(--border); border-radius:8px; padding:14px 16px; margin-bottom:14px` | -| `.profile-avatar` | `width:56px; height:56px; flex:0 0 56px; border:2px solid var(--bg-main)` | -| `.profile-stat` | `border:1px solid var(--border); border-radius:8px; padding:13px` | -| `.profile-panel` | `min-width:0; border:1px solid var(--border); border-radius:9px; padding:16px; margin-bottom:14px` | -| `.profile-panel-head` | `gap:10px; margin-bottom:12px` | -| `.profile-tool` | `width:100%; gap:10px; border:1px solid var(--border); border-radius:7px; padding:9px` | -| `.profile-review` | `border:1px solid var(--border); border-radius:7px; padding:12px` | - -## Host Framed Overlays And Notices - -Dialogs and notices are documented separately from content cards because their viewport anchoring differs. - -| Surface | Exact size declarations | -| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `.prototype-dialog` | `position:fixed; inset:0; margin:auto; width:min(520px,calc(100vw - 28px)); max-height:min(82dvh,680px); padding:0; overflow:auto; border:1px solid var(--border-strong); border-radius:8px` | -| `.workspace-create-dialog` | `width:min(440px,calc(100vw - 28px))` | -| `.prototype-modal-head` | `gap:12px; padding:14px 16px; border-bottom:1px solid var(--border)` | -| `.prototype-modal-fields` | `gap:11px; padding:14px 16px` | -| `.prototype-modal-foot` | `gap:7px; padding:11px 16px; border-top:1px solid var(--border)` | -| `.toast` | `max-width:300px; padding:10px 14px; border:1px solid var(--border-strong); border-left:3px solid var(--accent); border-radius:7px` | -| `.offline-banner` | `gap:9px; padding:9px 14px; border:1px solid var(--warning-border); border-radius:8px; margin-bottom:20px` | - -## Host Responsive Overrides - -The 860px and 640px breakpoints are separate source scopes. At 640px, later declarations override earlier declarations where noted. - -| Selector | Media condition | Exact size declarations | -| ------------------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -| `.workspace-main-grid` | `max-width:860px` | `grid-template-columns:minmax(0,1fr)` | -| `.workspace-starter-grid` | `max-width:640px` | First: `grid-template-columns:minmax(0,1fr); gap:7px`; later: `grid-template-columns:repeat(2,minmax(0,1fr)); gap:6px; margin-bottom:14px` | -| `.workspace-hero` | `max-width:640px` | `padding:16px` | -| `.workspace-hero.is-populated` | `max-width:640px` | First: `padding:12px 14px`; later: `padding:10px 12px; margin-bottom:8px` | -| `.workspace-control-strip` | `max-width:640px` | `gap:8px; padding:8px 10px; margin-bottom:10px` | -| `.workspace-starter` | `max-width:640px` | First: `min-height:68px`; later: `min-height:60px; padding:9px; gap:7px` | -| `.workspace-starter-icon` | `max-width:640px` | `width:28px; height:28px` | -| `.workspace-starter-stacks` | `max-width:640px` | `min-height:64px` | -| `.workspace-dock-grid` | `max-width:640px` | `grid-template-columns:minmax(0,1fr)` | -| `.workspace-dock-card` | `max-width:640px` | `padding:8px` | -| `.team-bottom-grid` | `max-width:640px` | `grid-template-columns:minmax(0,1fr)` | -| `.team-members-panel` | `max-width:640px` | `margin-bottom:10px` | -| `.team-panel-head-inset` | `max-width:640px` | `padding:10px 10px 0` | -| `.team-panel-head` | `max-width:640px` | `gap:8px; margin-bottom:8px` | -| `.team-panel` | `max-width:640px` | `padding:12px` | -| `.tool-grid` | `max-width:640px` | `grid-template-columns:1fr` | -| `.collection-add-options` | `max-width:640px` | `grid-template-columns:minmax(0,1fr)` | -| `.detail-hero` | `max-width:640px` | `grid-template-columns:52px minmax(0,1fr); gap:12px; margin-bottom:22px` | -| `.profile-hero` | `max-width:640px` | `grid-template-columns:48px minmax(0,1fr); padding:12px; gap:8px 11px` | -| `.profile-avatar` | `max-width:640px` | `width:48px; height:48px; flex-basis:48px` | -| `.profile-stats` | `max-width:640px` | `grid-template-columns:repeat(2,minmax(0,1fr)); gap:8px` | -| `.profile-stat` | `max-width:640px` | `padding:10px` | -| `.profile-columns` | `max-width:640px` | `grid-template-columns:1fr; gap:0` | -| `.profile-panel` | `max-width:640px` | `padding:13px` | - -## Mock-Tool Framed Surfaces - -Iframe styles are local to each preview and do not inherit host card sizing. - -| Preview scope | Surface | Exact size declarations | -| ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------- | -| Generic mock previews: Base64 Encoder, Image Compressor, Markdown Editor, QR Code Generator, Unit Converter, Hash Generator, SVG Optimizer, Cron Parser | `.card` | `max-width:520px` | -| Password Generator | `.card` | `width:100%; max-width:460px; border:1px solid var(--frame-border); border-radius:16px; padding:24px` | -| Color Picker | `.val` | `border:1px solid var(--frame-border); border-radius:10px; padding:12px 14px; display:flex` | -| Color Picker | `.val` at `max-width:520px` | `gap:10px` | - -The JSON Formatter and Text Case Converter previews do not define a card container. SQL Studio uses an internal sidebar/editor layout rather than a card surface; its dimensions are not recorded as card tokens. - -## Inline And Coverage Notes - -- No non-empty inline geometry declaration was found on rendered host card/panel elements or card surfaces in the 13 generated mock previews. Collection marks have inline background values only; those are not size declarations. -- The card geometry inventory includes CSS-owned dimensions, grid tracks, spacing, border thickness/radius, and responsive rules; it does not infer rendered pixel heights from content or include text-size tokens. -- Nine generated previews use the generic `.card` maximum width; Password Generator and Color Picker have their own local framed surfaces. These iframe values remain isolated from host styles. -- Refresh this source audit whenever card markup or geometry in `sandbox/index.html` changes. This is not a production design-system contract. diff --git a/public/assets/aistudio/dropdown.styles.size_1c83ab46.md b/public/assets/aistudio/dropdown.styles.size_1c83ab46.md deleted file mode 100644 index 01a37a0..0000000 --- a/public/assets/aistudio/dropdown.styles.size_1c83ab46.md +++ /dev/null @@ -1,256 +0,0 @@ -# Sandbox Dropdown Styles And Sizes - -## Audit Scope - -Source: canonical [`sandbox/index.html`](../index.html). This review-only forensic ledger records exact authored dropdown styles and sizes in the sandbox. It does not define production tokens or authorize production dropdown migration. - -Included surfaces: - -- Custom workspace dropdown trigger and menu. -- Workspace menu heading, list, item, select/action rows, check/icon/separator, active, hover, danger, and focus states. -- Native `` Controls - -There are exactly six native select markup instances: - -1. `submittedToolCategory` in the Submit Tool modal. -2. `.side-select[data-change="sort"]` in Discover sorting. -3. `.team-role-select[data-change="team-role"]` in dynamic team rows. -4. `.team-member-filter#teamMemberRoleFilter` in Teams member filtering. -5. `#teamInviteRole` in the Team invite form. -6. `.side-select.settings-control[data-change="settings-theme"]` in Settings. - -### Shared Modal Category Select - -| Selector | Exact declarations | -| ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `.prototype-form-field input:not([type="checkbox"]):not([type="color"]),.prototype-form-field select,.prototype-form-field textarea` | `width:100%; min-height:34px; padding:7px 9px; border:1px solid var(--border-strong); border-radius:5px; background:var(--bg-main); color:var(--text); font:inherit; font-size:11.5px` | -| `.prototype-form-field select:focus` | `outline:2px solid var(--accent); outline-offset:1px` | - -The modal category select has no standalone width or height override beyond this shared rule. - -### Discover Sidebar Select - -| Selector | Exact declarations | -| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `.side-select` | `width:100%; background:var(--bg-main); border:1px solid var(--border-strong); color:var(--text); font-size:12.5px; padding:6px 8px; border-radius:5px; outline:none` | - -The Discover sort select therefore has no explicit `min-height`, `height`, or `max-height`. Its rendered control height follows native select rendering plus 12.5px text and 6px vertical padding. - -Its three option values are authored only as text markup: - -- `Most used` -- `Top rated` -- `Newest` - -### Settings Theme Select - -The settings theme select inherits `.side-select` and adds shared settings dimensions. - -| Selector | Exact declarations | -| ------------------- | ---------------------------------- | -| `.settings-control` | `min-width:140px; max-width:190px` | - -At `@media (min-width:641px) and (max-width:860px)`: - -| Selector | Exact declarations | -| ------------------- | ---------------------------------- | -| `.settings-control` | `min-width:112px; max-width:148px` | - -At `@media (max-width:640px)`: - -| Selector | Exact declarations | -| ------------------- | ---------------------------------- | -| `.settings-control` | `min-width:112px; max-width:148px` | - -The settings select has no separate authored `width`, height, or option geometry. - -### Team Member Role Filter - -| Selector | Exact declarations | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `.team-member-filter` | `min-width:112px; min-height:32px; padding:5px 8px; border:1px solid var(--border); border-radius:5px; background:var(--bg-main); color:var(--text-muted); font:inherit; font-size:10.5px` | - -At `@media (max-width:640px)`: - -| Selector | Exact declarations | -| --------------------- | ------------------ | -| `.team-member-filter` | `min-width:96px` | - -The visible option labels are `All roles`, `Owner`, `Admin`, and `Member`; no CSS targets native `