docs: update architecture documentation and manifests

Refine technical documentation to reflect current architecture, component structure, and routing conventions for the vcon console.
This commit is contained in:
Team Dark Devil committed 2026-11-17 21:22:55 +06:00
1 parent bb938c33c0
commit 367dd819f8
64 files changed
+910 -2661

No files matched your search

+16 -30
View File
@@ -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.
+33
View File
@@ -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.
+43
View File
@@ -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.
+68
View File
@@ -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/)
+21
View File
@@ -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.
+308 -35
View File
@@ -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 <token>`) 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: "<CLIENT_JWT_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)**.
+52
View File
@@ -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.
+14 -13
View File
@@ -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`.
+9 -11
View File
@@ -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.
+12 -6
View File
@@ -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.
+16 -15
View File
@@ -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.
+9 -7
View File
@@ -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`.
+5 -8
View File
@@ -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`).
-15
View File
@@ -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`
+7 -11
View File
@@ -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.
+11 -13
View File
@@ -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)
+3 -4
View File
@@ -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.
+6 -9
View File
@@ -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`).
-17
View File
@@ -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`
+14
View File
@@ -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);
}
}
/**
+6 -9
View File
@@ -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`.
+12 -13
View File
@@ -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`).
-9
View File
@@ -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.
+6 -9
View File
@@ -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.
+3 -3
View File
@@ -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"]
+7 -5
View File
@@ -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"]
+11 -19
View File
@@ -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.
+17 -10
View File
@@ -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`).
+2 -2
View File
@@ -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`.
+1 -1
View File
@@ -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"
@@ -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.
@@ -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.
@@ -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.
-23
View File
@@ -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.
Binary file not shown.

Before

Width:  |  Height:  |  Size: 78 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 32 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 37 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 31 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 160 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 46 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 31 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 77 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 66 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 46 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 43 KiB

@@ -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.
@@ -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 |
@@ -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.
@@ -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.
@@ -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.
@@ -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 `<select>` controls for Discover sorting, Settings theme, Team member role filter, Team role cells, Team invite role, and modal category.
- Shared settings control bounds that constrain the Settings theme select.
- Responsive bounds and mobile overrides for workspace dropdown and native selects.
- Authored markup and dynamic option markup, with native option-popup geometry explicitly distinguished.
Excluded:
- Command palette, mobile navigation popover, native dialogs, and toast surfaces, already covered by `popupModel.styles.size.md`.
- Collection picker labels/cards, checkbox/radio option panels, and generic custom option lists.
- Browser-native `<option>` popup rendering, since `sandbox/index.html` contains no `<option>` CSS declarations controlling platform menu geometry.
- Sidebar section/category popovers unrelated to an explicit dropdown/select control.
## Surface Summary
| Surface | Exact selector blocks | Markup instances | Responsive override blocks |
| --------------------------------- | --------------------: | ------------------: | -------------------------: |
| Custom workspace dropdown trigger | 7 | 1 trigger | 2 declarations |
| Custom workspace dropdown menu | 18 | 1 generated menu | 2 declarations |
| Native `.side-select` | 1 | 2 selects | 0 in select class itself |
| Settings select constraints | 2 | 1 select | 2 breakpoint rules |
| Team member filter select | 1 | 1 select | 1 |
| Team role select | 2 | dynamic rows | 1 |
| Team field select | 2 | 1 select | 0 |
| Prototype modal select | 1 | 1 select | 0 |
| Shared select controls | 0 new selector blocks | 6 total select tags | 0 |
The custom workspace dropdown has 18 menu/internal selector blocks and 7 trigger/positioning selector blocks. Native select markup is present in 6 places, all mapped to one or more exact control patterns below.
## Custom Workspace Dropdown Trigger
Markup:
```html
<button
class="workspace-selector-btn"
id="workspaceSelectorBtn"
type="button"
data-action="toggle-workspace-menu"
aria-haspopup="menu"
aria-expanded="false"
>
<span class="workspace-selector-label">...</span>
<span class="chevron-icon">...</span>
</button>
```
| Selector | Exact declarations |
| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.titlebar-workspace` | `position:relative; min-width:0; color:var(--text-dim); font-size:11px; font-weight:500; letter-spacing:0` |
| `.workspace-selector-btn` | `max-width:180px; display:flex; align-items:center; gap:5px; padding:4px 6px; border:1px solid transparent; border-radius:5px; background:transparent; color:inherit; font:inherit; text-align:left; cursor:pointer; transition:background .14s ease,border-color .14s ease,color .14s ease` |
| `.workspace-selector-btn:hover,.workspace-selector-btn[aria-expanded="true"]` | `background:var(--bg-hover); border-color:var(--border-strong); color:var(--text)` |
| `.workspace-selector-btn:focus-visible` | `outline:2px solid var(--accent-hover); outline-offset:2px` |
| `.workspace-selector-label` | `overflow:hidden; text-overflow:ellipsis; white-space:nowrap` |
| `.chevron-icon` | `flex:none; transition:transform .14s ease` |
| `.workspace-selector-btn[aria-expanded="true"] .chevron-icon` | `transform:rotate(180deg)` |
At `@media (max-width:640px)`:
| Selector | Exact declarations |
| --------------------------- | ------------------------------------- |
| `.workspace-selector-btn` | `max-width:104px; padding-inline:5px` |
| `.workspace-selector-label` | `max-width:72px` |
The trigger's desktop and mobile maximum widths are applied through a max-width constraint, not a fixed width. Its icon is structurally accepted as a flex-none chevron but has no authored icon width/height in the workspace trigger rules.
## Custom Workspace Dropdown Menu
Markup container:
```html
<div
class="workspace-dropdown-menu"
id="workspaceDropdownMenu"
role="menu"
aria-label="Workspaces"
hidden
>
<!-- dynamic workspace rows and actions -->
</div>
```
Dynamic rows are created by `workspaceDropdownHTML()`. The menu owns its popup geometry and all row geometry directly.
| Selector | Exact declarations |
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `.workspace-dropdown-menu[hidden]` | `display:none` |
| `.workspace-dropdown-menu` | `position:absolute; top:calc(100% + 7px); left:0; z-index:350; width:min(300px,calc(100vw - 24px)); max-height:min(70dvh,460px); overflow:auto; padding:4px; background:var(--bg-elevated); border:1px solid var(--border-strong); border-radius:6px; box-shadow:0 8px 20px var(--shadow-menu); color:var(--text)` |
| `.workspace-menu-heading` | `padding:5px 8px; color:var(--text-dim); font-size:9.5px; font-weight:700; letter-spacing:.06em; text-transform:uppercase` |
| `.workspace-menu-list` | `display:grid; gap:1px` |
| `.workspace-menu-item` | `min-height:30px; display:flex; align-items:center; gap:4px; padding:2px 3px; border-radius:4px` |
| `.workspace-menu-item:hover,.workspace-menu-item.active` | `background:var(--bg-hover)` |
| `.workspace-menu-select` | `min-width:0; min-height:28px; flex:1; display:flex; align-items:center; gap:7px; padding:4px 6px; border:0; border-radius:4px; background:transparent; color:var(--text-muted); font:inherit; font-size:11.5px; text-align:left; cursor:pointer` |
| `.workspace-menu-select:hover,.workspace-menu-item.active .workspace-menu-select` | `color:var(--text)` |
| `.workspace-menu-select span` | `overflow:hidden; text-overflow:ellipsis; white-space:nowrap` |
| `.workspace-menu-check` | `width:14px; flex:none; color:var(--accent-hover); text-align:center` |
| `.workspace-menu-icon` | `width:24px; height:24px; display:grid; place-items:center; flex:none; border:0; border-radius:4px; background:transparent; color:var(--text-dim); cursor:pointer` |
| `.workspace-menu-icon:hover` | `background:var(--bg-active); color:var(--text)` |
| `.workspace-menu-icon svg` | `width:13px; height:13px` |
| `.workspace-menu-separator` | `height:1px; margin:5px 2px; background:var(--border)` |
| `.workspace-menu-action` | `width:100%; min-height:32px; display:flex; align-items:center; gap:8px; padding:5px 8px; border:0; border-radius:4px; background:transparent; color:var(--text-muted); font:inherit; font-size:11.5px; text-align:left; cursor:pointer` |
| `.workspace-menu-action:hover` | `background:var(--bg-hover); color:var(--text)` |
| `.workspace-menu-action svg` | `width:14px; height:14px; flex:none` |
| `.workspace-menu-action.danger` | `color:var(--text-danger)` |
| `.workspace-menu-action.danger:hover` | `background:var(--danger-soft); color:var(--text-danger-hover)` |
At `@media (max-width:640px)`:
| Selector | Exact declarations |
| -------------------------- | ------------------------------------------------------------ |
| `.workspace-dropdown-menu` | `top:calc(100% + 21px); width:min(280px,calc(100vw - 92px))` |
### Workspace Menu State Contract
- `hidden` suppresses the menu through `.workspace-dropdown-menu[hidden]`.
- `top:calc(100% + 7px)` positions the menu relative to the titlebar workspace wrapper.
- Desktop menu width is `300px` bounded by `100vw - 24px`; mobile width is `280px` bounded by `100vw - 92px`.
- Maximum height is `70dvh` bounded by `460px`; overflow is vertical through `overflow:auto`.
- List rows use `30px` minimum height; workspace switch rows use `28px` minimum height.
- Menu action rows use `32px` minimum height.
- Active and hover states use `var(--bg-hover)`; active workspace text uses `var(--text)`.
- Current workspace action icons are `24px`; action SVGs are `13px`/`14px`; check width is `14px`.
## Native `<select>` 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 `<option>` geometry.
### Team Role Cell Select
| Selector | Exact declarations |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.team-role-select` | `width:100%; max-width:110px; min-height:28px; padding:4px 6px; border:1px solid var(--border); border-radius:4px; background:var(--bg-elevated); color:var(--text-muted); font:inherit; font-size:10px` |
| `.team-role-select:disabled` | `opacity:.8; cursor:not-allowed` |
At `@media (max-width:640px)`:
| Selector | Exact declarations |
| ------------------- | ----------------------------------- |
| `.team-role-select` | `padding-inline:3px; font-size:9px` |
Team role cells use `Owner`, `Admin`, and `Member`; `Owner` is disabled for the owner account. Native options receive no authored dimensions or state rules.
### Team Invite Role Select
| Selector | Exact declarations |
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.team-field input,.team-field select` | `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` |
| `.team-field input:focus,.team-field select:focus` | `outline:2px solid var(--accent); outline-offset:1px` |
The Team invite role select offers `Member` and `Admin`. It has no standalone select geometry; it shares `.team-field` control dimensions.
## Exact Responsive Contract
| Scope | Applied dropdown geometry |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Base | Workspace trigger `180px` max width; menu width `300px` minus viewport; native sidebar select full width; team filter `112px` minimum; role select `28px` minimum/`110px` maximum; settings select `140px`-`190px` |
| `641px-860px` | Settings select narrows to `112px`-`148px` |
| `max-width:640px` | Workspace trigger `104px` max width and label `72px` max width; menu offset becomes `21px` and width becomes `280px` minus viewport; team filter minimum becomes `96px`; role select inline padding becomes `3px` and font becomes `9px`; settings select remains `112px`-`148px` |
No select receives a popup-height or option-menu font/border override. Native option popups are platform-controlled and are not represented by CSS variables or literal values in the source.
## Markup, Inline, And Option Boundary
Six native `<select>` elements occur in the canonical source. Their only dynamic option markup is for Discover sort, team roles, team role filter, invite role, and settings theme. Submit Tool category options are literal markup.
No popup/container `style` attribute or JavaScript assignment changes select control geometry. No `option { ... }`, `option:checked`, `option:hover`, `<option style>`, or `select::part(...)` rule exists.
Therefore:
- All authored dropdown control geometry is represented above.
- Native option-menu width, height, item padding, scroll behavior, and platform rendering are outside the source.
- A claim of “100% match” applies to all authored HTML/CSS tokens, not platform-owned native option popup chrome.
## Verification
- The custom workspace dropdown is reconciled to 25 exact selector blocks: 7 trigger/positioning/trigger-state blocks and 18 menu/menu-state blocks.
- Six native select markup instances reconcile to five authored control patterns plus inherited/shared settings dimensions.
- Desktop, `641px-860px`, and `max-width-640px` select constraints are grouped exactly by media scope.
- No `<option>` CSS or native option-popup inline sizing exists.
- No dropdown inline style or JavaScript style assignment changes the control geometry.
- This file is a review-only forensic record; no sandbox or production CSS was changed.
@@ -1,67 +0,0 @@
# Sandbox Font-Size Tokens
## Audit Scope
Source: canonical [`sandbox/index.html`](../index.html). This file inventories every literal numeric font size declared by the sandbox design, without changing the prototype or production styles.
The host workbench and each generated mock-tool iframe are separate CSS scopes. Counts include the host stylesheet, the generated stylesheets for all 13 catalogue tools, the numeric size in a `font` shorthand, and literal inline `font-size` attributes in generated markup. Values are preserved exactly as written; CSSOM-expanded inheritance is not counted as a literal size declaration.
| Source scope | Direct `font-size` CSS | Numeric size in `font` shorthand | Inline `font-size` | Size-bearing occurrences |
| ------------------------- | ---------------------: | -------------------------------: | -----------------: | -----------------------: |
| Host workbench | 227 | 1 | 3 | 231 |
| Mock-tool iframe previews | 76 | 0 | 3 | 79 |
| Total | 303 | 1 | 6 | 310 |
There are 23 distinct numeric size values. Every current numeric size uses `px`; there are no `rem`, `em`, `%`, `pt`, `vw`, or other size units among the audited font-size declarations.
## Exact Size Tokens
| Exact value | Host `font-size` CSS | Iframe `font-size` CSS | Host shorthand | Host inline | Iframe inline | Total occurrences |
| ----------- | -------------------: | ---------------------: | -------------: | ----------: | ------------: | ----------------: |
| `8px` | 1 | 0 | 0 | 0 | 0 | 1 |
| `9px` | 11 | 1 | 0 | 0 | 0 | 12 |
| `9.5px` | 18 | 1 | 0 | 0 | 0 | 19 |
| `10px` | 32 | 2 | 1 | 0 | 0 | 35 |
| `10.5px` | 33 | 3 | 0 | 0 | 0 | 36 |
| `11px` | 26 | 4 | 0 | 1 | 1 | 32 |
| `11.5px` | 27 | 0 | 0 | 0 | 0 | 27 |
| `12px` | 26 | 21 | 0 | 1 | 1 | 49 |
| `12.5px` | 18 | 3 | 0 | 0 | 0 | 21 |
| `13px` | 6 | 10 | 0 | 1 | 1 | 18 |
| `13.5px` | 5 | 0 | 0 | 0 | 0 | 5 |
| `14px` | 3 | 10 | 0 | 0 | 0 | 13 |
| `15px` | 3 | 2 | 0 | 0 | 0 | 5 |
| `16px` | 0 | 2 | 0 | 0 | 0 | 2 |
| `16.5px` | 1 | 0 | 0 | 0 | 0 | 1 |
| `17px` | 3 | 0 | 0 | 0 | 0 | 3 |
| `18px` | 5 | 1 | 0 | 0 | 0 | 6 |
| `19px` | 2 | 0 | 0 | 0 | 0 | 2 |
| `20px` | 1 | 0 | 0 | 0 | 0 | 1 |
| `21px` | 1 | 0 | 0 | 0 | 0 | 1 |
| `22px` | 3 | 16 | 0 | 0 | 0 | 19 |
| `23px` | 1 | 0 | 0 | 0 | 0 | 1 |
| `24px` | 1 | 0 | 0 | 0 | 0 | 1 |
| **Total** | **227** | **76** | **1** | **3** | **3** | **310** |
## Shorthand And Inheritance
The host rule `.workspace-dock-glyph` declares `font:700 10px ui-monospace,monospace`; its `10px` contributes one size occurrence above. Thirty host declarations use `font:inherit`; they inherit the surrounding size and do not introduce a separate numeric font-size token. No mock iframe stylesheet contains a numeric size in a `font` shorthand.
## Inline Size Locations
| Scope | Generated UI location | Exact declaration |
| ----------- | ----------------------------------- | ----------------- |
| Host | Discover empty-results message | `font-size:13px` |
| Host | Tool-detail review count | `font-size:12px` |
| Host | Tool-detail source URL | `font-size:11px` |
| Mock iframe | JSON Formatter version/source label | `font-size:11px` |
| Mock iframe | Color Picker palette caption | `font-size:12px` |
| Mock iframe | Password Generator options row | `font-size:13px` |
## Coverage And Reconciliation
- Direct CSS values were scanned from the raw host `<style>` source and generated `toolFrameDoc()` styles for each of the 13 catalogue tools. Repeated generated rules count once per tool document.
- Literal inline styles were separately scanned in generated host and iframe markup. Their six numeric font-size declarations are already included once each in the totals; they are not folded into CSS declaration counts.
- The direct CSS totals reconcile to 227 host + 76 iframe = 303. Adding one shorthand size and six inline sizes gives 310 size-bearing occurrences.
- `inherit` is a value, not a numeric size. It is not listed as a numeric token; the existing [`fonts.md`](fonts.md) inventories the broader font declarations and inherited shorthand separately.
- Refresh this source audit whenever typography in `sandbox/index.html` changes. This is not a production token definition.
-146
View File
@@ -1,146 +0,0 @@
# Sandbox Typography Tokens
## Audit Scope
Source: canonical [`sandbox/index.html`](../index.html). This is a forensic inventory of typography declarations only; it does not define or modify production design tokens.
The host stylesheet and each generated mock-tool iframe are separate style scopes. The iframe scope is not merged into host tokens. The audit parsed the host `<style>` block and the generated `toolFrameDoc()` styles for all 13 catalogue tools, including nested responsive rules. It also scanned literal `style="..."` attributes in generated markup.
| Source scope | CSS declarations | Inline declarations | Notes |
| ------------------------- | ---------------: | ------------------: | ------------------------------------------------------------------- |
| Host workbench | 416 | 4 | Main application shell, views, responsive overrides |
| Mock-tool iframe previews | 185 | 4 | One generated document per each of 13 catalogue tools |
| Total | 601 | 8 | 609 font-related declarations in the audited rendered/source scopes |
The 601 CSS declarations reduce to 54 host and 31 mock property/value groups. Occurrence counts below count literal CSS declarations across the host stylesheet and generated preview documents; repeated values are retained as counts. Inline declarations are listed separately. CSS shorthand declarations are preserved as shorthand, not expanded into inferred longhand tokens.
## Font Families
Exact values as written in CSS. `inherit` is an inheritance instruction, not a named font family.
| Scope | Exact `font-family` value | CSS occurrences |
| ----------- | ------------------------------------------------------------------ | --------------: |
| Host | `-apple-system,BlinkMacSystemFont,'Segoe UI',system-ui,sans-serif` | 1 |
| Host | `inherit` | 2 |
| Host | `ui-monospace,monospace` | 6 |
| Host | `ui-monospace,'SF Mono',Menlo,monospace` | 1 |
| Mock iframe | `-apple-system,system-ui,sans-serif` | 16 |
| Mock iframe | `inherit` | 5 |
| Mock iframe | `ui-monospace,"SF Mono",Menlo,monospace` | 1 |
| Mock iframe | `ui-monospace,"SF Mono",monospace` | 1 |
| Mock iframe | `ui-monospace,monospace` | 21 |
The host base stack is the system UI stack. Monospace stacks are used for code-like labels and content. Mock-tool stacks are local to their iframe documents and do not inherit the host stack across the iframe boundary.
## Font Sizes
All sizes are CSS pixels. Counts are literal stylesheet declarations, not computed or inherited sizes.
| Exact value | Host CSS | Mock iframe CSS |
| ----------- | -------: | --------------: |
| `8px` | 1 | 0 |
| `9px` | 11 | 1 |
| `9.5px` | 18 | 1 |
| `10px` | 32 | 2 |
| `10.5px` | 33 | 3 |
| `11px` | 26 | 4 |
| `11.5px` | 27 | 0 |
| `12px` | 26 | 21 |
| `12.5px` | 18 | 3 |
| `13px` | 6 | 10 |
| `13.5px` | 5 | 0 |
| `14px` | 3 | 10 |
| `15px` | 3 | 2 |
| `16px` | 0 | 2 |
| `16.5px` | 1 | 0 |
| `17px` | 3 | 0 |
| `18px` | 5 | 1 |
| `19px` | 2 | 0 |
| `20px` | 1 | 0 |
| `21px` | 1 | 0 |
| `22px` | 3 | 16 |
| `23px` | 1 | 0 |
| `24px` | 1 | 0 |
## Font Weights
| Exact value | Host CSS | Mock iframe CSS |
| ----------- | -------: | --------------: |
| `400` | 3 | 0 |
| `500` | 10 | 5 |
| `600` | 36 | 6 |
| `650` | 2 | 0 |
| `700` | 26 | 17 |
| `800` | 1 | 0 |
## Font Shorthand And Rendering
| Scope | Property | Exact value | Occurrences |
| ----- | ------------------------ | --------------------------------- | ----------: |
| Host | `font` | `inherit` | 30 |
| Host | `font` | `700 10px ui-monospace,monospace` | 1 |
| Host | `-webkit-font-smoothing` | `antialiased` | 1 |
The shorthand values above are kept verbatim. The `700 10px ui-monospace,monospace` shorthand declares weight, size, and family together.
## Letter Spacing
| Exact value | Host CSS | Mock iframe CSS |
| ----------- | -------: | --------------: |
| `-.01em` | 1 | 1 |
| `-.02em` | 2 | 0 |
| `.02em` | 2 | 0 |
| `.04em` | 2 | 0 |
| `.05em` | 1 | 2 |
| `.06em` | 5 | 4 |
| `.07em` | 2 | 1 |
| `0` | 2 | 2 |
## Line Heights
Unitless values are preserved as written.
| Exact value | Host CSS | Mock iframe CSS |
| ----------- | -------: | --------------: |
| `1` | 1 | 0 |
| `1.25` | 2 | 0 |
| `1.3` | 1 | 0 |
| `1.4` | 8 | 0 |
| `1.45` | 7 | 0 |
| `1.5` | 10 | 1 |
| `1.55` | 3 | 0 |
| `1.6` | 7 | 17 |
| `1.65` | 0 | 1 |
| `1.7` | 1 | 0 |
## Text Treatment
| Property | Exact value | Host CSS | Mock iframe CSS |
| ----------------- | ----------- | -------: | --------------: |
| `text-transform` | `none` | 0 | 1 |
| `text-transform` | `uppercase` | 10 | 7 |
| `text-decoration` | `underline` | 2 | 0 |
## Literal Inline Typography
These eight declarations are in generated HTML attributes rather than stylesheet rules. Counts are source-attribute declarations; values are already represented in the stylesheet tables where applicable.
| Scope | Generated UI location | Exact declarations |
| ----------- | ----------------------------------- | ---------------------------------------------------------------- |
| Host | Discover empty-results message | `font-size:13px` |
| Host | Tool-detail review count | `font-size:12px; font-weight:400` |
| Host | Tool-detail source URL | `font-size:11px` |
| Mock iframe | JSON Formatter version/source label | `font-size:11px; font-family:-apple-system,system-ui,sans-serif` |
| Mock iframe | Color Picker palette caption | `font-size:12px` |
| Mock iframe | Password Generator options row | `font-size:13px` |
## Mock Preview Ownership
The isolated preview styles are generated by `jsonToolDoc()`, `colorToolDoc()`, `passwordToolDoc()`, `textCaseToolDoc()`, `sqlStudioToolDoc()`, and `genericToolDoc()`. The generic document is used by Base64 Encoder, Image Compressor, Markdown Editor, QR Code Generator, Unit Converter, Hash Generator, SVG Optimizer, and Cron Parser. All preview typography remains iframe-local.
## Coverage Notes
- Included host CSS, media-query overrides, generated iframe styles, font shorthand, inheritance declarations, text treatment, and literal inline typography attributes.
- No font download, `@font-face`, external web-font import, or custom font asset is declared in the audited HTML; rendering relies on the listed platform/system fallback stacks.
- Color, spacing, dimensions, and other non-typographic tokens are outside this file's scope.
- Counts describe the canonical source at audit time. They are not production token names and should be regenerated if `sandbox/index.html` changes.
@@ -1,252 +0,0 @@
# Sandbox Header Styles And Size Tokens
## Audit Scope
Source: canonical [`sandbox/index.html`](../index.html). This review-only ledger records the complete authored styling for header and title surfaces in the host workbench and its 13 generated mock-tool previews. The host scope includes titlebar/tab chrome, page and feature headings, dialog/panel heading rows, Profile and Tool Detail identity blocks, runner chrome, offline notices, and the header controls attached to those surfaces. Host sidebar headings/cards are cross-referenced to [`sidebar.styles.size.md`](sidebar.styles.size.md) and are not double-counted here.
The iframe scope includes semantic headers, tool titles/subtitles, labeled pane headings, SQL Studio's title/toolbar/tabs/editor/results headings, and their responsive overrides. The Password Generator strength meter (`.bar`) is a progress indicator, not a header, and is excluded. The titlebar navigation/search menu bodies are separate overlay surfaces; only titlebar chrome is listed.
The declarations below preserve authored values, selector text, and media context. Typography cross-references are available in [`fonts.md`](fonts.md) and [`fonts.size.md`](fonts.size.md); button and page geometry details are additionally indexed in [`buttons.size.md`](buttons.size.md) and [`Pages.size.md`](Pages.size.md). Host and iframe tokens remain separate and are not production design tokens.
## Host Header And Chrome Rules
The source scan matched 150 in-scope host rule groups containing 530 declarations. The stylesheet has separate mobile media blocks, so repeated selector/media pairs are retained as separate source rules and in source order.
| Selector | Media | Exact declarations |
| --- | --- | --- |
| `.titlebar` | base | `position:relative; height:40px; flex:0 0 40px; display:grid; grid-template-columns:minmax(0,1fr) minmax(140px,auto) minmax(0,1fr); align-items:center; gap:16px; padding:0 14px; background:var(--bg-activity); border-bottom:1px solid var(--border); user-select:none` |
| `.titlebar-brand` | base | `display:flex; align-items:center; gap:9px; min-width:0; font-size:11.5px; font-weight:700; letter-spacing:.04em; color:var(--text)` |
| `.titlebar-mark` | base | `width:20px; height:20px; display:grid; place-items:center; border-radius:5px; background:var(--accent); color:var(--text-on-accent); font-size:11px; font-weight:800` |
| `.titlebar-divider` | base | `width:1px; height:16px; background:var(--border-strong); margin:0 2px` |
| `.titlebar-workspace` | base | `position:relative; min-width:0; color:var(--text-dim); font-size:11px; font-weight:500; letter-spacing:0` |
| `.titlebar-document` | base | `min-width:0; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; text-align:center; color:var(--text-muted); font-size:12px` |
| `.titlebar-tools` | base | `display:flex; align-items:center; justify-content:flex-end; gap:6px; min-width:0` |
| `.titlebar-theme-toggle` | base | `width:32px; height:32px; flex:none; display:grid; place-items:center; border:1px solid transparent; border-radius:6px; background:transparent; color:var(--text-muted); transition:background .16s ease,color .16s ease,border-color .16s ease` |
| `.titlebar-theme-toggle:hover` | base | `background:var(--bg-hover); color:var(--text); border-color:var(--border-strong)` |
| `.titlebar-theme-toggle:focus-visible` | base | `outline:2px solid var(--accent-hover); outline-offset:2px` |
| `.titlebar-theme-toggle svg` | base | `width:15px; height:15px; flex:none` |
| `.titlebar-search` | base | `height:32px; display:flex; align-items:center; gap:8px; border:1px solid var(--border); border-radius:6px; background:var(--bg-main); color:var(--text-muted); padding:0 10px; font-size:11.5px; transition:background .16s ease,color .16s ease,border-color .16s ease,box-shadow .16s ease` |
| `.titlebar-search:hover` | base | `background:var(--bg-hover); color:var(--text); border-color:var(--border-strong)` |
| `.titlebar-search[aria-expanded="true"]` | base | `border-color:var(--accent); color:var(--text); background:var(--bg-hover)` |
| `.titlebar-search svg` | base | `width:14px; height:14px; flex:none` |
| `.titlebar-search kbd` | base | `font:inherit; font-size:9.5px; color:var(--text-dim); border:1px solid var(--border-strong); border-radius:4px; padding:2px 4px; margin-left:3px` |
| `.titlebar-search:focus-visible,.titlebar-menu-toggle:focus-visible` | base | `outline:2px solid var(--accent-hover); outline-offset:2px` |
| `.titlebar-menu-toggle` | base | `display:none; width:32px; height:32px; place-items:center; border:0; border-radius:6px; background:transparent; color:var(--text-muted); transition:background .16s ease,color .16s ease` |
| `.titlebar-menu-toggle:hover,.titlebar-menu-toggle[aria-expanded="true"]` | base | `background:var(--bg-hover); color:var(--text)` |
| `.titlebar-menu-toggle svg` | base | `width:16px; height:16px` |
| `.tabbar` | base | `height:34px; flex:0 0 34px; display:flex; align-items:stretch; background:var(--bg-sidebar); border-bottom:1px solid var(--border); overflow-x:auto; overflow-y:hidden; scrollbar-width:none` |
| `.tabbar::-webkit-scrollbar` | base | `display:none` |
| `.tab` | base | `display:flex; align-items:center; gap:7px; padding:0 8px 0 12px; font-size:12px; color:var(--text-muted); border-right:1px solid var(--border); cursor:pointer; white-space:nowrap; position:relative; max-width:200px; transition:background .12s,color .12s` |
| `.tab:hover` | base | `background:var(--bg-hover); color:var(--text)` |
| `.tab.active` | base | `background:var(--bg-main); color:var(--text)` |
| `.tab.active::before` | base | `content:''; position:absolute; top:0; left:0; right:0; height:2px; background:var(--accent)` |
| `.tab:hover .tab-close,.tab.active .tab-close` | base | `opacity:1` |
| `.page-header` | base | `display:flex; align-items:flex-start; justify-content:space-between; gap:20px; margin-bottom:26px; flex-wrap:wrap` |
| `.page-header h1` | base | `font-size:23px; font-weight:700; letter-spacing:-.02em; margin-bottom:5px` |
| `.subtitle` | base | `font-size:13.5px; color:var(--text-muted); line-height:1.5; max-width:560px` |
| `.header-actions` | base | `display:flex; gap:8px; flex-shrink:0` |
| `.workspace-hero` | base | `display:flex; align-items:flex-start; justify-content:space-between; gap:20px; padding:22px 24px; margin-bottom:18px; border:1px solid var(--border); border-radius:8px; background:var(--bg-elevated)` |
| `.workspace-hero.is-populated` | base | `padding:14px 18px; margin-bottom:12px; background:var(--bg-main)` |
| `.workspace-eyebrow` | base | `margin-bottom:7px; color:var(--accent); font-size:10px; font-weight:700; text-transform:uppercase; letter-spacing:.06em` |
| `.workspace-hero h1` | base | `font-size:22px; font-weight:700; margin-bottom:7px` |
| `.workspace-hero p` | base | `color:var(--text-muted); font-size:12.5px; line-height:1.6` |
| `.workspace-hero.is-populated .workspace-eyebrow` | base | `margin-bottom:4px` |
| `.workspace-hero.is-populated h1` | base | `font-size:18px; margin-bottom:4px` |
| `.workspace-hero.is-populated p` | base | `font-size:11.5px` |
| `.workspace-section-head` | base | `display:flex; align-items:center; justify-content:space-between; gap:10px; margin-bottom:10px` |
| `.workspace-section-head h2` | base | `font-size:14px; font-weight:600` |
| `.workspace-section-head span` | base | `color:var(--text-dim); font-size:10.5px` |
| `.teams-header` | base | `display:flex; align-items:flex-start; justify-content:space-between; gap:18px; margin-bottom:18px` |
| `.teams-header h1` | base | `display:flex; align-items:center; gap:8px; font-size:21px; font-weight:700; margin-bottom:5px` |
| `.teams-header p` | base | `color:var(--text-muted); font-size:12px; line-height:1.55` |
| `.team-header-copy` | base | `min-width:0` |
| `.team-name-inline` | base | `display:inline-flex; align-items:center; gap:5px; margin:0 0 6px; padding:0; border:0; background:transparent; color:var(--text); font:inherit; font-size:12px; font-weight:600; cursor:pointer` |
| `.team-name-inline:hover` | base | `color:var(--accent-hover)` |
| `.teams-header-actions` | base | `display:flex; align-items:center; gap:7px; flex:none` |
| `.team-name-slot` | base | `min-height:28px` |
| `.team-panel-head-inset` | base | `padding:14px 14px 0` |
| `.team-panel-head` | base | `display:flex; align-items:center; justify-content:space-between; gap:10px; margin-bottom:12px` |
| `.team-panel-head h2` | base | `font-size:13px; font-weight:600` |
| `.team-panel-head span` | base | `color:var(--text-dim); font-size:10px` |
| `.section-head` | base | `display:flex; align-items:baseline; justify-content:space-between; margin-bottom:14px` |
| `.section-head h2` | base | `font-size:16.5px; font-weight:600; letter-spacing:-.01em` |
| `.section-head .muted` | base | `font-size:11.5px; color:var(--text-dim)` |
| `.prototype-modal-head` | base | `position:sticky; top:0; z-index:1; display:flex; align-items:flex-start; justify-content:space-between; gap:12px; padding:14px 16px; border-bottom:1px solid var(--border); background:var(--bg-elevated)` |
| `.prototype-modal-head h2` | base | `font-size:15px; font-weight:650` |
| `.prototype-modal-head p` | base | `margin-top:3px; color:var(--text-muted); font-size:10.5px; line-height:1.45` |
| `.collection-tools-head` | base | `display:flex; align-items:center; justify-content:space-between; gap:10px; margin:16px 0 9px` |
| `.collection-tools-head h2` | base | `font-size:13px; font-weight:600` |
| `.collection-tools-head span` | base | `color:var(--text-dim); font-size:10px` |
| `.collection-add-head` | base | `display:flex; align-items:center; justify-content:space-between; gap:10px` |
| `.collection-add-head h2` | base | `font-size:12px; font-weight:600` |
| `.collection-add-head p` | base | `margin-top:3px; color:var(--text-dim); font-size:10px; line-height:1.4` |
| `.detail-hero` | base | `display:flex; gap:20px; margin-bottom:28px; flex-wrap:wrap` |
| `.detail-info` | base | `flex:1; min-width:260px` |
| `.detail-copy` | base | `min-width:0` |
| `.detail-info h1` | base | `font-size:22px; font-weight:700; letter-spacing:-.02em; margin-bottom:8px` |
| `.meta-row` | base | `display:flex; align-items:center; gap:10px; flex-wrap:wrap; margin-bottom:10px; font-size:12px` |
| `.meta-row .cat` | base | `color:var(--text-dim); text-transform:uppercase; letter-spacing:.06em; font-weight:600; font-size:11px` |
| `.meta-row .rt` | base | `display:flex; align-items:center; gap:4px; color:var(--yellow); font-weight:600` |
| `.meta-row .rt span` | base | `color:var(--text-muted); font-weight:400` |
| `.detail-info .desc` | base | `font-size:13.5px; color:var(--text-muted); line-height:1.6; margin-bottom:16px; max-width:600px` |
| `.detail-actions` | base | `display:flex; gap:8px; flex-wrap:wrap` |
| `.review-composer-head` | base | `display:flex; align-items:center; justify-content:space-between; gap:10px; margin-bottom:8px` |
| `.review-composer-head strong` | base | `font-size:12px; font-weight:600` |
| `.review-composer-head span` | base | `color:var(--text-dim); font-size:10px` |
| `.runner-top` | base | `height:46px; flex-shrink:0; display:none; align-items:center; gap:10px; padding:0 12px; background:var(--bg-sidebar); border-bottom:1px solid var(--border)` |
| `.runner-top.show` | base | `display:flex` |
| `.runner-tool` | base | `display:flex; align-items:center; gap:9px; min-width:0` |
| `.runner-title` | base | `font-size:13px; font-weight:600; line-height:1.25` |
| `.runner-url` | base | `font-size:10.5px; color:var(--text-dim); font-family:ui-monospace,monospace` |
| `.runner-actions` | base | `margin-left:auto; display:flex; align-items:center; gap:4px` |
| `.runner-actions .badge` | base | `flex-shrink:0; white-space:nowrap` |
| `.offline-banner` | base | `display:flex; align-items:center; gap:9px; background:var(--warning-soft); border:1px solid var(--warning-border); color:var(--warning-text); font-size:12.5px; padding:9px 14px; border-radius:8px; margin-bottom:20px` |
| `.profile-hero` | base | `display:grid; grid-template-columns:56px minmax(0,1fr) auto; align-items:center; gap:10px 14px; background:var(--bg-elevated); border:1px solid var(--border); border-radius:8px; padding:14px 16px; margin-bottom:14px` |
| `.profile-identity` | base | `min-width:0` |
| `.profile-identity h1` | base | `font-size:20px; font-weight:700; margin-bottom:2px` |
| `.profile-title-row` | base | `display:flex; align-items:center; gap:8px; min-width:0; flex-wrap:wrap` |
| `.profile-title-row h1` | base | `min-width:0; max-width:100%; overflow-wrap:anywhere; white-space:normal; margin-bottom:0` |
| `.profile-title-row .profile-pill` | base | `flex:none; padding:3px 7px; font-size:9.5px` |
| `.profile-panel-head` | base | `display:flex; align-items:center; justify-content:space-between; gap:10px; margin-bottom:12px` |
| `.profile-panel-head h2` | base | `margin:0` |
| `.profile-review-head` | base | `display:flex; align-items:center; gap:8px; margin-bottom:7px` |
| `.profile-review-head strong` | base | `font-size:12px` |
| `.profile-review-head span` | base | `margin-left:auto; color:var(--yellow); font-size:11px` |
| `.settings-intro` | base | `margin-bottom:18px` |
| `.settings-intro h1` | base | `font-size:22px; font-weight:700; margin-bottom:4px` |
| `.settings-intro p` | base | `font-size:12.5px; color:var(--text-muted); line-height:1.5; max-width:620px` |
| `.settings-section-head` | base | `display:flex; justify-content:space-between; align-items:flex-start; gap:16px; margin-bottom:5px` |
| `.settings-section-head h2` | base | `font-size:13px; font-weight:650; color:var(--text)` |
| `.settings-section-head p` | base | `font-size:11px; color:var(--text-dim); line-height:1.45; margin-top:3px` |
| `.titlebar` | `(max-width:640px)` | `height:44px; flex-basis:44px; grid-template-columns:auto minmax(0,1fr) auto; gap:10px; padding-inline:10px` |
| `.titlebar-menu-toggle` | `(max-width:640px)` | `display:grid` |
| `.titlebar-divider,.titlebar-search kbd` | `(max-width:640px)` | `display:none` |
| `.titlebar-workspace` | `(max-width:640px)` | `display:block; min-width:0` |
| `.titlebar-document` | `(max-width:640px)` | `text-align:center; font-size:12px; padding-inline:4px` |
| `.titlebar-search` | `(max-width:640px)` | `width:34px; height:34px; justify-content:center; padding:0; border-radius:8px` |
| `.titlebar-theme-toggle` | `(max-width:640px)` | `width:34px; height:34px; border-radius:8px` |
| `.titlebar-search .titlebar-search-label` | `(max-width:640px)` | `display:none` |
| `.runner-top.show` | `(max-width:640px)` | `height:46px; min-height:46px; display:flex; gap:4px; padding:0 6px` |
| `.runner-tool` | `(max-width:640px)` | `width:auto; flex:1; gap:5px` |
| `.runner-title` | `(max-width:640px)` | `overflow:hidden; white-space:nowrap` |
| `.runner-url` | `(max-width:640px)` | `display:none` |
| `.runner-actions` | `(max-width:640px)` | `flex:none; gap:2px; margin-left:0` |
| `.runner-actions .icon-btn` | `(max-width:640px)` | `width:26px; height:30px; flex:0 0 26px` |
| `.runner-actions .badge` | `(max-width:640px)` | `font-size:9px; padding-inline:5px` |
| `.detail-hero` | `(max-width:640px)` | `display:grid; grid-template-columns:52px minmax(0,1fr); align-items:start; gap:12px; margin-bottom:22px` |
| `.detail-info` | `(max-width:640px)` | `display:contents; min-width:0` |
| `.detail-info h1` | `(max-width:640px)` | `font-size:18px; line-height:1.25; margin-bottom:6px` |
| `.meta-row` | `(max-width:640px)` | `gap:6px; margin-bottom:7px; font-size:11px` |
| `.meta-row .cat` | `(max-width:640px)` | `font-size:10px` |
| `.detail-info .desc` | `(max-width:640px)` | `font-size:12.5px; line-height:1.5; 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; font-size:11px; white-space:nowrap` |
| `.workspace-hero` | `(max-width:640px)` | `display:block; padding:16px` |
| `.workspace-hero h1` | `(max-width:640px)` | `font-size:19px` |
| `.workspace-hero.is-populated` | `(max-width:640px)` | `padding:12px 14px` |
| `.workspace-hero.is-populated h1` | `(max-width:640px)` | `font-size:17px` |
| `.teams-header` | `(max-width:640px)` | `display:grid; gap:10px` |
| `.teams-header` | `(max-width:640px)` | `align-items:flex-start` |
| `.teams-header-actions` | `(max-width:640px)` | `width:100%` |
| `.profile-hero` | `(max-width:640px)` | `grid-template-columns:48px minmax(0,1fr); align-items:start; padding:12px; gap:8px 11px` |
| `.profile-identity` | `(max-width:640px)` | `min-width:0` |
| `.profile-identity h1` | `(max-width:640px)` | `font-size:18px` |
| `.workspace-hero.is-populated` | `(max-width:640px)` | `padding:10px 12px; margin-bottom:8px` |
| `.workspace-section-head` | `(max-width:640px)` | `margin-bottom:7px` |
| `.teams-header` | `(max-width:640px)` | `gap:6px; margin-bottom:12px` |
| `.teams-header h1` | `(max-width:640px)` | `font-size:18px; margin-bottom:3px` |
| `.teams-header p` | `(max-width:640px)` | `font-size:11px; line-height:1.4` |
| `.team-panel-head-inset` | `(max-width:640px)` | `padding:10px 10px 0` |
| `.team-panel-head` | `(max-width:640px)` | `gap:8px; margin-bottom:8px` |
| `.settings-intro` | `(max-width:640px)` | `margin-bottom:12px` |
| `.settings-intro h1` | `(max-width:640px)` | `font-size:19px; margin-bottom:3px` |
| `.settings-intro p` | `(max-width:640px)` | `font-size:11px; line-height:1.4` |
| `.settings-section-head` | `(max-width:640px)` | `gap:8px; margin-bottom:3px` |
| `.settings-section-head h2` | `(max-width:640px)` | `font-size:12px` |
| `.settings-section-head p` | `(max-width:640px)` | `font-size:10px; line-height:1.4` |
## Generated Mock-Tool Preview Headers
Each generated preview is an isolated CSS document. The current source scan matched 33 rule groups containing 135 declarations across 13 tool documents. Repeated generic `h1` rules remain associated with their tool; responsive iframe rules retain their own media condition.
| Preview scope | Selector | Media | Exact declarations |
| --- | --- | --- | --- |
| `iframe:json-formatter` | `header` | base | `padding:14px 18px; border-bottom:1px solid var(--frame-border); display:flex; align-items:center; gap:10px; background:var(--frame-header)` |
| `iframe:json-formatter` | `header h1` | base | `font-size:15px; margin:0; font-family:-apple-system,system-ui,sans-serif; font-weight:600` |
| `iframe:json-formatter` | `.bar` | base | `padding:10px 18px; display:flex; gap:8px; border-bottom:1px solid var(--frame-border); background:var(--frame-header)` |
| `iframe:json-formatter` | `.pane label` | base | `font-size:11px; text-transform:uppercase; letter-spacing:.06em; color:var(--frame-muted); padding:8px 14px; background:var(--frame-header); font-family:-apple-system,system-ui,sans-serif` |
| `iframe:base64` | `h1` | base | `font-size:22px; margin:0 0 8px` |
| `iframe:color-picker` | `header` | base | `padding:16px 20px; border-bottom:1px solid var(--frame-border); background:var(--frame-surface); display:flex; align-items:center; gap:10px` |
| `iframe:color-picker` | `header h1` | base | `font-size:16px; margin:0; font-weight:700` |
| `iframe:color-picker` | `header span` | base | `font-size:12px; color:var(--frame-muted); margin-left:auto` |
| `iframe:color-picker` | `header` | `(max-width:520px)` | `padding:12px 16px` |
| `iframe:color-picker` | `header span` | `(max-width:520px)` | `display:none` |
| `iframe:image-compressor` | `h1` | base | `font-size:22px; margin:0 0 8px` |
| `iframe:markdown` | `h1` | base | `font-size:22px; margin:0 0 8px` |
| `iframe:qr-generator` | `h1` | base | `font-size:22px; margin:0 0 8px` |
| `iframe:password-generator` | `h1` | base | `margin:0 0 4px; font-size:18px` |
| `iframe:unit-converter` | `h1` | base | `font-size:22px; margin:0 0 8px` |
| `iframe:text-case` | `header` | base | `padding:16px 20px; border-bottom:1px solid var(--frame-border); display:flex; align-items:center; gap:10px` |
| `iframe:text-case` | `header h1` | base | `font-size:16px; margin:0; font-weight:700` |
| `iframe:text-case` | `header span` | base | `font-size:12px; color:var(--frame-muted); margin-left:auto` |
| `iframe:text-case` | `.pane label` | base | `font-size:11px; text-transform:uppercase; letter-spacing:.06em; color:var(--frame-muted); padding:10px 20px; font-weight:600` |
| `iframe:hash-generator` | `h1` | base | `font-size:22px; margin:0 0 8px` |
| `iframe:svg-optimizer` | `h1` | base | `font-size:22px; margin:0 0 8px` |
| `iframe:cron-parser` | `h1` | base | `font-size:22px; margin:0 0 8px` |
| `iframe:sql-studio` | `.sb-header` | base | `padding:14px 14px 10px; border-bottom:1px solid var(--frame-border); display:flex; align-items:center; gap:9px` |
| `iframe:sql-studio` | `.sb-title` | base | `font-size:13px; font-weight:700; letter-spacing:-.01em` |
| `iframe:sql-studio` | `.toolbar` | base | `height:42px; flex-shrink:0; background:var(--frame-panel); border-bottom:1px solid var(--frame-border); display:flex; align-items:center; gap:6px; padding:0 12px` |
| `iframe:sql-studio` | `.tab-sm` | base | `padding:5px 12px; border-radius:5px; background:transparent; color:var(--frame-soft); font-size:12px; font-weight:500; display:flex; align-items:center; gap:6px; cursor:pointer; transition:background .12s` |
| `iframe:sql-studio` | `.tab-sm:hover` | base | `background:var(--frame-surface)` |
| `iframe:sql-studio` | `.tab-sm.active` | base | `background:var(--frame-accent-bg); color:var(--frame-accent-text)` |
| `iframe:sql-studio` | `.tab-sm .dot` | base | `width:6px; height:6px; border-radius:50%; background:var(--frame-muted)` |
| `iframe:sql-studio` | `.tab-sm.active .dot` | base | `background:var(--frame-accent-icon)` |
| `iframe:sql-studio` | `.editor-head` | base | `padding:7px 14px; font-size:10.5px; text-transform:uppercase; letter-spacing:.06em; color:var(--frame-muted); font-weight:700; border-bottom:1px solid var(--frame-border); display:flex; align-items:center; gap:8px; background:var(--frame-panel)` |
| `iframe:sql-studio` | `.editor-head .dot` | base | `width:6px; height:6px; border-radius:50%; background:var(--frame-success)` |
| `iframe:sql-studio` | `.res-head` | base | `padding:8px 14px; font-size:10.5px; text-transform:uppercase; letter-spacing:.06em; color:var(--frame-muted); font-weight:700; border-bottom:1px solid var(--frame-border); display:flex; align-items:center; gap:12px; position:sticky; top:0; background:var(--frame-panel); z-index:3` |
## Header-Scoped Inline Styles
The host renderer sample yielded 41 inline style attributes across the patterns below. Counts are rendered occurrences; identical source patterns are listed once. Empty `style` attributes contain no authored declarations. Dynamic tool/identity background expressions are preserved literally and not resolved to runtime colors.
| Host element/pattern | Exact inline style source | Rendered occurrences |
| --- | --- | ---: |
| `div.tabbar` | `display: flex;` | 1 |
| `div.profile-avatar` | `background:var(--avatar-indigo)` | 2 |
| `div.profile-avatar` | `background:var(--avatar-pink)` | 1 |
| `div.profile-avatar` | `background:var(--avatar-green)` | 1 |
| `div.runner-glyph` | `background:var(--tool-json-formatter)` | 1 |
| `button.icon-btn` | `color:var(--yellow)` | 3 |
| `div.detail-glyph` | `background:var(--tool-base64)` | 1 |
| `div.runner-glyph` | `background:var(--tool-base64)` | 1 |
| `button.icon-btn` | empty `style` attribute | 10 |
| `div.detail-glyph` | `background:var(--tool-color-picker)` | 1 |
| `div.runner-glyph` | `background:var(--tool-color-picker)` | 1 |
| `div.detail-glyph` | `background:var(--tool-image-compressor)` | 1 |
| `div.runner-glyph` | `background:var(--tool-image-compressor)` | 1 |
| `div.detail-glyph` | `background:var(--tool-markdown)` | 1 |
| `div.runner-glyph` | `background:var(--tool-markdown)` | 1 |
| `div.detail-glyph` | `background:var(--tool-qr-generator)` | 1 |
| `div.runner-glyph` | `background:var(--tool-qr-generator)` | 1 |
| `div.detail-glyph` | `background:var(--tool-password-generator)` | 1 |
| `div.runner-glyph` | `background:var(--tool-password-generator)` | 1 |
| `div.detail-glyph` | `background:var(--tool-unit-converter)` | 1 |
| `div.runner-glyph` | `background:var(--tool-unit-converter)` | 1 |
| `div.runner-glyph` | `background:var(--tool-text-case)` | 1 |
| `div.detail-glyph` | `background:var(--tool-hash-generator)` | 1 |
| `div.runner-glyph` | `background:var(--tool-hash-generator)` | 1 |
| `div.detail-glyph` | `background:var(--tool-svg-optimizer)` | 1 |
| `div.runner-glyph` | `background:var(--tool-svg-optimizer)` | 1 |
| `div.detail-glyph` | `background:var(--tool-cron-parser)` | 1 |
| `div.runner-glyph` | `background:var(--tool-cron-parser)` | 1 |
| `div.runner-glyph` | `background:var(--tool-sql-studio)` | 1 |
Two inline declarations were found in generated previews: `iframe:json-formatter` header source label (`margin-left:auto;font-size:11px;color:var(--frame-muted);font-family:-apple-system,system-ui,sans-serif`) and `iframe:sql-studio` tab (`padding:5px 8px;color:var(--frame-muted)`). No other header-scoped iframe inline style attributes were found.
## Coverage And Reconciliation
- The canonical host stylesheet and every generated preview stylesheet for the 13 catalogue tools were parsed separately. The in-scope CSS rows above reconcile to 150 host groups/530 declarations and 33 iframe groups/135 declarations.
- The host selector union excludes seven sidebar-only rules (`.side-title`, `.side-title .hint`, `.workspace-sidebar-card` and its descendants, `.profile-side-card`, and `.profile-side-group`); those are in [`sidebar.styles.size.md`](sidebar.styles.size.md). The Password Generator strength-meter `.bar` rules are excluded because they are not a heading or header surface.
- The 41 host inline style instances are represented by 29 source-pattern rows; two inline preview style instances are recorded separately.
- CSS declarations remain literal, including variable references, pseudo/states, and media conditions. Browser-computed values and inherited defaults are not substituted.
- This is a documentation-only source audit. No sandbox HTML or production UI/styles were changed; refresh the ledger when `sandbox/index.html` header surfaces change.
@@ -1,264 +0,0 @@
# Sandbox Popup Modal Styles And Sizes
## Audit Scope
Source: canonical [`sandbox/index.html`](../index.html). This review-only forensic ledger records every authored popup/modal surface and exact style/size token in the source. It does not define production tokens or authorize production popup migration.
Included popup surfaces:
- Workspace titlebar dropdown.
- Search command palette and its backdrop.
- Mobile navigation popup menu.
- Native Submit Tool, New Collection, New Workspace, and Copy Link dialogs.
- Shared prototype-dialog shell and modal form, header, fields, controls, notes, and footer.
- Collection picker controls owned by the New Collection popup.
- Toast popup container and toast states.
- Popup-specific responsive overrides at `@media (max-width:640px)`.
Excluded: general application shell/layout, general `.icon-btn`/`.btn` geometry unless directly listed as a modal-owned nested rule, sidebar drawer geometry already covered by the sidebar audit, and mock-tool iframe UI.
## Popup Surface Summary
| Popup surface | Source markup | Base geometry/style rules | Responsive rules |
| --------------------------------------- | -------------------------------- | ------------------------- | --------------------------------------------- |
| Workspace dropdown | 1 popup | 18 selector blocks | 1 positional width override |
| Search palette and backdrop | 1 backdrop + 1 dialog | 20 selector blocks | 5 selectors / 6 declaration overrides |
| Mobile navigation popover | 1 navigation popup | 11 selector blocks | 0 (`display` is in base mobile media context) |
| Prototype dialog shell/shared internals | 4 native `dialog` instances | 24 selector blocks | 0 |
| Collection picker internals | Inside New Collection dialog | 11 selector blocks | 0 |
| Toast | 1 popup container; dynamic items | 3 selector blocks | 0 |
The workspace dropdown and palette have a single host `@media (max-width:640px)` override block. The mobile menu base display rule is activated inside that same host breakpoint.
Custom-property references are retained verbatim, including `var(--backdrop-search)`, `var(--shadow-modal)`, `var(--bg-elevated)`, and `var(--border-strong)`.
## Workspace Dropdown
Markup is the titlebar workspace selector and associated popover:
```html
<div class="titlebar-workspace">
<button class="workspace-selector-btn" aria-expanded="false">...</button>
<div class="workspace-dropdown-menu" hidden>...</div>
</div>
```
| Selector | Exact declarations |
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `.workspace-dropdown-menu[hidden]` | `display:none` |
| `.workspace-dropdown-menu` | `position:absolute; top:calc(100% + 7px); left:0; z-index:350; width:min(300px,calc(100vw - 24px)); max-height:min(70dvh,460px); overflow:auto; padding:4px; background:var(--bg-elevated); border:1px solid var(--border-strong); border-radius:6px; box-shadow:0 8px 20px var(--shadow-menu); color:var(--text)` |
| `.workspace-menu-heading` | `padding:5px 8px; color:var(--text-dim); font-size:9.5px; font-weight:700; letter-spacing:.06em; text-transform:uppercase` |
| `.workspace-menu-list` | `display:grid; gap:1px` |
| `.workspace-menu-item` | `min-height:30px; display:flex; align-items:center; gap:4px; padding:2px 3px; border-radius:4px` |
| `.workspace-menu-item:hover,.workspace-menu-item.active` | `background:var(--bg-hover)` |
| `.workspace-menu-select` | `min-width:0; min-height:28px; flex:1; display:flex; align-items:center; gap:7px; padding:4px 6px; border:0; border-radius:4px; background:transparent; color:var(--text-muted); font:inherit; font-size:11.5px; text-align:left; cursor:pointer` |
| `.workspace-menu-select:hover,.workspace-menu-item.active .workspace-menu-select` | `color:var(--text)` |
| `.workspace-menu-select span` | `overflow:hidden; text-overflow:ellipsis; white-space:nowrap` |
| `.workspace-menu-check` | `width:14px; flex:none; color:var(--accent-hover); text-align:center` |
| `.workspace-menu-icon` | `width:24px; height:24px; display:grid; place-items:center; flex:none; border:0; border-radius:4px; background:transparent; color:var(--text-dim); cursor:pointer` |
| `.workspace-menu-icon:hover` | `background:var(--bg-active); color:var(--text)` |
| `.workspace-menu-icon svg` | `width:13px; height:13px` |
| `.workspace-menu-separator` | `height:1px; margin:5px 2px; background:var(--border)` |
| `.workspace-menu-action` | `width:100%; min-height:32px; display:flex; align-items:center; gap:8px; padding:5px 8px; border:0; border-radius:4px; background:transparent; color:var(--text-muted); font:inherit; font-size:11.5px; text-align:left; cursor:pointer` |
| `.workspace-menu-action:hover` | `background:var(--bg-hover); color:var(--text)` |
| `.workspace-menu-action svg` | `width:14px; height:14px; flex:none` |
| `.workspace-menu-action.danger` | `color:var(--text-danger)` |
| `.workspace-menu-action.danger:hover` | `background:var(--danger-soft); color:var(--text-danger-hover)` |
At `@media (max-width:640px)`:
| Selector | Exact declaration |
| -------------------------- | ------------------------------------------------------------ |
| `.workspace-dropdown-menu` | `top:calc(100% + 21px); width:min(280px,calc(100vw - 92px))` |
## Search Command Palette
Markup:
```html
<div class="search-palette-backdrop" hidden></div>
<section class="search-palette" role="dialog" aria-modal="true" hidden>
...
</section>
```
| Selector | Exact declarations |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.search-palette-backdrop[hidden],.search-palette[hidden]` | `display:none` |
| `.search-palette-backdrop` | `position:fixed; inset:0; z-index:400; background:var(--backdrop-search); backdrop-filter:blur(1px)` |
| `.search-palette` | `position:fixed; z-index:401; top:50px; right:14px; width:min(640px,calc(100vw - 28px)); max-height:min(680px,calc(100dvh - 66px)); display:flex; flex-direction:column; overflow:hidden; background:var(--surface-palette); border:1px solid var(--border-palette); border-radius:10px; box-shadow:0 22px 64px var(--shadow-modal),0 2px 8px var(--shadow-modal-soft)` |
| `.palette-searchbar` | `height:48px; flex:none; display:flex; align-items:center; gap:12px; padding:0 14px; border-bottom:1px solid var(--border-strong); color:var(--text-muted)` |
| `.palette-searchbar svg` | `flex:none; color:var(--text-muted)` |
| `.palette-input` | `width:100%; min-width:0; height:100%; border:0; outline:0; background:transparent; color:var(--text); font:inherit; font-size:14px` |
| `.palette-input::placeholder` | `color:var(--text-dim)` |
| `.palette-escape` | `flex:none; padding:2px 6px; border:1px solid var(--border-strong); border-radius:4px; color:var(--text-dim); font-size:10px` |
| `.palette-results` | `min-height:0; overflow-y:auto; padding:7px 0; overscroll-behavior:contain` |
| `.palette-heading` | `padding:8px 14px 5px; color:var(--text-dim); font-size:10px; font-weight:700; letter-spacing:.06em; text-transform:uppercase` |
| `.palette-result` | `width:100%; min-height:48px; display:flex; align-items:center; gap:11px; padding:7px 14px; border:0; background:transparent; color:var(--text); text-align:left; font:inherit; cursor:pointer` |
| `.palette-result:hover,.palette-result[aria-selected="true"]` | `background:var(--surface-palette-hover)` |
| `.palette-result[aria-selected="true"]` | `box-shadow:inset 2px 0 var(--accent)` |
| `.palette-glyph` | `width:30px; height:30px; flex:none; display:grid; place-items:center; border-radius:6px; color:var(--text-on-accent); font-family:ui-monospace,monospace; font-size:9px; font-weight:700` |
| `.palette-copy` | `min-width:0; flex:1` |
| `.palette-name` | `display:block; overflow:hidden; color:var(--text); font-size:12.5px; font-weight:600; text-overflow:ellipsis; white-space:nowrap` |
| `.palette-meta` | `display:block; margin-top:3px; overflow:hidden; color:var(--text-dim); font-size:10.5px; text-overflow:ellipsis; white-space:nowrap` |
| `.palette-trailing` | `flex:none; color:var(--text-dim); font-size:10px` |
| `.palette-empty` | `padding:26px 18px; text-align:center; color:var(--text-muted); font-size:12px; line-height:1.6` |
| `.palette-tips` | `padding:11px 14px; border-top:1px solid var(--border); color:var(--text-dim); font-size:10.5px; line-height:1.6` |
| `.palette-footer` | `min-height:34px; display:flex; align-items:center; gap:14px; padding:5px 14px; border-top:1px solid var(--border); color:var(--text-dim); font-size:10px` |
| `.palette-footer kbd` | `font:inherit; padding:1px 4px; border:1px solid var(--border-strong); border-radius:3px; color:var(--text-muted)` |
| `.palette-footer-hint` | `display:flex; align-items:center; gap:4px` |
| `.palette-footer-note` | `margin-left:auto` |
At `@media (max-width:640px)`:
| Selector | Exact declarations |
| ---------------------- | ----------------------------------------------------------------------------------------------- |
| `.search-palette` | `top:52px; right:8px; width:calc(100vw - 16px); max-height:min(72dvh,560px); border-radius:8px` |
| `.palette-searchbar` | `height:44px; padding-inline:11px; gap:9px` |
| `.palette-result` | `min-height:46px; padding-inline:11px` |
| `.palette-footer` | `gap:9px; padding-inline:11px` |
| `.palette-footer-note` | `display:none` |
## Mobile Navigation Popover
Markup:
```html
<button class="titlebar-menu-toggle">...</button>
<div class="mobile-nav-menu" id="mobileNavigationMenu" role="navigation" hidden>
...
</div>
```
The toggle is `display:none` until the 640px breakpoint. The popup itself is `display:none` until `[hidden]` is removed while the mobile breakpoint is active.
| Selector | Exact declarations |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `.titlebar-menu-toggle` | `display:none; width:32px; height:32px; place-items:center; border:0; border-radius:6px; background:transparent; color:var(--text-muted); transition:background .16s ease,color .16s ease` |
| `.titlebar-menu-toggle:hover,.titlebar-menu-toggle[aria-expanded="true"]` | `background:var(--bg-hover); color:var(--text)` |
| `.titlebar-menu-toggle svg` | `width:16px; height:16px` |
| `.mobile-nav-menu[hidden]` | `display:none` |
| `.mobile-nav-menu` | `display:none` |
| `.mobile-nav-menu:not([hidden])` | `position:absolute; top:calc(100% + 6px); left:8px; z-index:300; width:min(320px,calc(100vw - 16px)); max-height:min(72dvh,34rem); overflow:auto; padding:6px; background:var(--bg-sidebar); border:1px solid var(--border-strong); border-radius:6px; box-shadow:0 8px 20px var(--shadow-menu)` |
| `.mobile-nav-group` | `padding:4px 0` |
| `.mobile-nav-group+.mobile-nav-group` | `border-top:1px solid var(--border); margin-top:3px; padding-top:6px` |
| `.mobile-nav-heading` | `padding:2px 7px 5px; color:var(--text-dim); font-size:9px; font-weight:700; letter-spacing:.06em; text-transform:uppercase` |
| `.mobile-nav-item` | `display:flex; align-items:center; gap:8px; width:100%; min-height:34px; padding:6px 8px; border:0; border-radius:4px; background:transparent; color:var(--text-muted); font:inherit; font-size:12px; text-align:left` |
| `.mobile-nav-item:hover,.mobile-nav-item.active` | `background:var(--bg-hover); color:var(--text)` |
| `.mobile-nav-item svg` | `width:15px; height:15px; flex:none` |
| `.mobile-nav-item span:nth-child(2)` | `flex:1` |
At `@media (max-width:640px)`:
| Selector | Exact declarations |
| -------------------------------- | ------------------ |
| `.titlebar-menu-toggle` | `display:grid` |
| `.mobile-nav-menu:not([hidden])` | `display:block` |
## Native Prototype Dialogs
There are four native `dialog` instances. All share the `.prototype-dialog` shell; New Workspace has the only variant override.
| Instance | Class/name | Dialog width override |
| -------------------- | ------------------------------------------ | ---------------------------------- |
| `submitToolModal` | `prototype-dialog` | none; shared `520px` maximum shell |
| `newCollectionModal` | `prototype-dialog` | none; shared `520px` maximum shell |
| `newWorkspaceModal` | `prototype-dialog workspace-create-dialog` | `440px` maximum shell |
| `copyLinkModal` | `prototype-dialog` | none; shared `520px` maximum shell |
Shared exact selectors:
| Selector | Exact 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; background:var(--bg-elevated); color:var(--text); box-shadow:0 22px 64px var(--shadow-modal),0 2px 8px var(--shadow-modal-soft)` |
| `.workspace-create-dialog` | `width:min(440px,calc(100vw - 28px))` |
| `.prototype-dialog::backdrop` | `background:var(--backdrop-search)` |
| `.prototype-modal-form` | `display:grid; gap:0` |
| `.prototype-modal-head` | `position:sticky; top:0; z-index:1; display:flex; align-items:flex-start; justify-content:space-between; gap:12px; padding:14px 16px; border-bottom:1px solid var(--border); background:var(--bg-elevated)` |
| `.prototype-modal-head h2` | `font-size:15px; font-weight:650` |
| `.prototype-modal-head p` | `margin-top:3px; color:var(--text-muted); font-size:10.5px; line-height:1.45` |
| `.prototype-modal-fields` | `display:grid; gap:11px; padding:14px 16px` |
| `.prototype-form-field` | `display:grid; gap:5px; min-width:0` |
| `.prototype-form-field label` | `color:var(--text-muted); font-size:10.5px; font-weight:600` |
| `.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 textarea` | `min-height:74px; resize:vertical; line-height:1.5` |
| `.prototype-form-field input:focus,.prototype-form-field select:focus,.prototype-form-field textarea:focus` | `outline:2px solid var(--accent); outline-offset:1px` |
| `.prototype-form-grid` | `display:grid; grid-template-columns:minmax(0,1fr) 144px; gap:10px` |
| `.prototype-color-control` | `width:48px; height:34px; padding:3px; border:1px solid var(--border-strong); border-radius:5px; background:var(--bg-main); cursor:pointer` |
| `.prototype-check-row` | `display:flex; align-items:center; gap:7px; color:var(--text-muted); font-size:11px` |
| `.prototype-modal-foot` | `display:flex; justify-content:flex-end; gap:7px; padding:11px 16px; border-top:1px solid var(--border)` |
| `.prototype-modal-note` | `color:var(--text-dim); font-size:10px; line-height:1.45` |
| `.prototype-dialog .icon-btn` | `flex:none` |
These modal base rules do not receive additional popup-specific 640px overrides. Native dialog sizing therefore remains viewport-bounded by `calc(100vw - 28px)` and `82dvh` at all widths.
## New Collection Popup Picker
| Selector | Exact declarations |
| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.collection-picker-search` | `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` |
| `.collection-picker-search:focus` | `outline:2px solid var(--accent); outline-offset:1px` |
| `.collection-picker-meta` | `display:flex; align-items:center; justify-content:space-between; gap:8px; color:var(--text-dim); font-size:9.5px` |
| `.collection-picker-meta strong` | `color:var(--text-muted); font-weight:600` |
| `.collection-tool-results` | `display:grid; gap:3px; max-height:192px; padding:2px; overflow-y:auto; border:1px solid var(--border); border-radius:5px; background:var(--bg-main)` |
| `.collection-tool-option` | `display:flex; align-items:center; gap:8px; min-width:0; min-height:34px; padding:5px 7px; border:1px solid transparent; border-radius:4px; color:var(--text-muted); cursor:pointer; transition:background .12s,border-color .12s,color .12s` |
| `.collection-tool-option:hover,.collection-tool-option:focus-within` | `background:var(--bg-hover); color:var(--text)` |
| `.collection-tool-option.selected` | `border-color:var(--accent-border); background:var(--accent-soft); color:var(--text)` |
| `.collection-tool-option input` | `flex:none; margin:0; accent-color:var(--accent)` |
| `.collection-tool-option-copy` | `min-width:0; flex:1` |
| `.collection-tool-option-copy strong,.collection-tool-option-copy span` | `display:block; overflow:hidden; text-overflow:ellipsis; white-space:nowrap` |
| `.collection-tool-option-copy strong` | `font-size:10.5px; font-weight:600` |
| `.collection-tool-option-copy span` | `margin-top:2px; color:var(--text-dim); font-size:9px` |
| `.collection-tool-empty` | `padding:15px 10px; color:var(--text-dim); font-size:10.5px; text-align:center` |
## Toast Popup
Markup:
```html
<div class="toast-wrap" id="toasts"></div>
```
Dynamic toast items use `.toast`; `.toast.show` is the active state.
| Selector | Exact declarations |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.toast-wrap` | `position:fixed; bottom:36px; right:16px; display:flex; flex-direction:column; gap:8px; z-index:500` |
| `.toast` | `background:var(--bg-elevated); border:1px solid var(--border-strong); border-left:3px solid var(--accent); color:var(--text); font-size:12.5px; padding:10px 14px; border-radius:7px; box-shadow:0 8px 28px var(--shadow-toast); opacity:0; transform:translateX(16px); transition:opacity .25s,transform .25s; max-width:300px` |
| `.toast.show` | `opacity:1; transform:translateX(0)` |
## Exact State, Cascade, And Z-Index Contract
- Hidden states use HTML `hidden` plus explicit `[hidden]` display suppression for the workspace dropdown, search palette/backdrop, and mobile navigation menu.
- Workspace dropdown z-index is `350`; search backdrop is `400`; search palette is `401`; mobile menu is `300`; native dialog top-layer behavior is browser-native and has no authored z-index; toast container is `500`.
- Native dialog shell is fixed, inset to the viewport, auto-margined, viewport-relative, vertically scrollable, and capped at `82dvh`/`680px`.
- New Workspace is the only dialog-width variant: `440px` maximum instead of shared `520px` maximum.
- Search palette desktop top/right offsets are `50px`/`14px`; mobile becomes `52px`/`8px` with full viewport-minus-16 width and compacted search/result/footer geometry.
- Workspace dropdown desktop maximum width is `300px` with `24px` viewport subtraction; mobile becomes `280px` with `92px` viewport subtraction and a `21px` trigger offset.
- Mobile menu maximum height is `72dvh` or `34rem`, whichever is smaller.
- Collection picker results cap at `192px`, are internally scrollable, and use 34px options.
- Dialog modal form controls use 34px minimum height; textareas use 74px minimum height and vertical resize.
- Toast width is content-derived with a `300px` maximum and 36px bottom / 16px right placement.
## Markup And Inline Geometry Coverage
Four `dialog` elements use the shared CSS shell:
- `submitToolModal`
- `newCollectionModal`
- `newWorkspaceModal`
- `copyLinkModal`
A full-source popup-target scan found zero literal `style` attributes on popup containers or popup-owned controls. No JavaScript assignment to popup element `style` properties was found. Toast items are created through popup-owned markup/classes and no per-instance inline geometry was assigned.
## Verification
- 18 workspace-dropdown selector blocks reconcile exactly to the popup source selectors.
- 24 command-palette/backdrop selector blocks, including five mobile override selectors, reconcile exactly.
- 13 mobile navigation selector blocks reconcile exactly, with two breakpoint activations.
- 19 shared native-dialog and modal-internal selector blocks reconcile exactly.
- 13 New Collection picker selector blocks reconcile exactly.
- Three toast/container/state selector blocks reconcile exactly.
- Source contains no popup-specific inline geometry and no JavaScript popup `style` assignment.
- Responsive popup declarations are grouped by exact breakpoint and no desktop value is inferred or expanded.
- This file is a review-only forensic record; no sandbox or production CSS was changed.
@@ -1,175 +0,0 @@
# Sandbox Sidebar Styles And Size Tokens
## Audit Scope
Source: canonical [`sandbox/index.html`](../index.html). This review-only ledger records authored styles and sizing declarations for the host activity rail, secondary sidebar/drawer and its rendered activity-specific content, plus SQL Studio's separate iframe sidebar. It includes all 13 host sidebar renderer variants as a selector union; repeated UI states are not counted as duplicate CSS sources.
Included styles cover dimensions, layout, spacing, typography, colors/backgrounds, borders/radii, overflow, positioning, transitions, focus/active/hover states, and responsive overrides. The titlebar navigation dropdown is a separate menu and is not included. Generic reset/control rules are included only where they apply to sidebar descendants. Values using semantic variables remain literal references.
The raw CSS inventory contains 96 host rule groups (454 declarations) and 16 SQL Studio sidebar rule groups (83 declarations). The rendered host sidebar union yielded 15 inline style occurrences across four source patterns; SQL Studio sidebar elements have no inline styles. Inline background values are dynamic expressions sourced from collection colors or tool gradients.
## Host Reset And Generic Descendant Rules
| Selector | Media | Exact declarations |
| -------------------------------------------- | ----- | ------------------------------------------------------------------------------------- |
| `*` | base | `box-sizing:border-box; margin:0; padding:0` |
| `button` | base | `font-family:inherit; cursor:pointer` |
| `input,select,textarea` | base | `font-family:inherit` |
| `::-webkit-scrollbar` | base | `width:10px; height:10px` |
| `::-webkit-scrollbar-track` | base | `background:transparent` |
| `::-webkit-scrollbar-thumb` | base | `background:var(--border-strong); border-radius:5px; border:2px solid var(--bg-main)` |
| `::-webkit-scrollbar-thumb:hover` | base | `background:var(--text-dim)` |
| `body.light-theme ::-webkit-scrollbar-thumb` | base | `background:var(--border-strong); border-color:var(--bg-main)` |
## Host Activity Rail
| Selector | Media | Exact declarations |
| ------------------------------------------------------------------------------------------------ | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.activity` | base | `width:52px; flex-shrink:0; background:var(--bg-activity); border-right:1px solid var(--border); display:flex; flex-direction:column; align-items:center; padding:8px 0; gap:2px; transition:width .15s,opacity .15s` |
| `.act-btn` | base | `width:38px; height:38px; border-radius:9px; border:none; background:transparent; display:flex; align-items:center; justify-content:center; color:var(--text-muted); position:relative; transition:background .15s,color .15s` |
| `.act-btn svg` | base | `width:21px; height:21px` |
| `.act-btn:hover` | base | `background:var(--bg-hover); color:var(--text)` |
| `.act-btn.active` | base | `color:var(--text); background:var(--bg-active)` |
| `.act-btn.active::before` | base | `content:''; position:absolute; left:-7px; top:50%; transform:translateY(-50%); width:3px; height:20px; background:var(--accent); border-radius:0 3px 3px 0` |
| `.act-btn::after` | base | `content:attr(data-tip); position:absolute; left:46px; top:50%; transform:translateY(-50%); background:var(--bg-elevated); color:var(--text); padding:5px 9px; border-radius:5px; font-size:11.5px; font-weight:500; white-space:nowrap; opacity:0; pointer-events:none; border:1px solid var(--border-strong); z-index:200; transition:opacity .12s; box-shadow:0 4px 14px var(--shadow-tooltip)` |
| `.act-btn:hover::after` | base | `opacity:1` |
| `.act-badge` | base | `position:absolute; top:3px; right:3px; background:var(--accent); color:var(--text-on-accent); font-size:9.5px; font-weight:700; line-height:1; min-width:14px; height:14px; border-radius:7px; display:flex; align-items:center; justify-content:center; padding:0 3px` |
| `.act-sep` | base | `width:24px; height:1px; background:var(--border-strong); margin:6px 0` |
| `.act-spacer` | base | `flex:1` |
| `.avatar` | base | `width:30px; height:30px; border-radius:50%; background:var(--avatar-gradient); display:flex; align-items:center; justify-content:center; font-size:11.5px; font-weight:700; color:var(--text-on-accent); cursor:pointer; border:2px solid transparent; transition:border-color .15s` |
| `.avatar:hover` | base | `border-color:var(--accent)` |
| `.avatar.active` | base | `border-color:var(--accent); color:var(--text-on-accent)` |
| `.activity` | `max-width:640px` | `order:2; width:100%; height:calc(64px + env(safe-area-inset-bottom)); flex:0 0 calc(64px + env(safe-area-inset-bottom)); flex-direction:row; justify-content:space-around; gap:2px; padding:4px 6px calc(4px + env(safe-area-inset-bottom)); background:var(--bg-activity); border-right:0; border-top:1px solid var(--border); position:relative; z-index:101` |
| `.act-btn` | `max-width:640px` | `flex:1 1 0; width:auto; min-width:0; height:52px; flex-direction:column; gap:3px; border-radius:7px` |
| `#activity [data-act="favorites"],#activity [data-act="recent"],#activity [data-act="settings"]` | `max-width:640px` | `display:none` |
| `.act-btn svg` | `max-width:640px` | `width:20px; height:20px; flex:none` |
| `.act-btn::after` | `max-width:640px` | `position:static; left:auto; top:auto; transform:none; background:transparent; color:var(--text-muted); border:0; box-shadow:none; padding:0; font-size:9.5px; font-weight:500; opacity:1; transition:none; pointer-events:none` |
| `.act-btn.active::before` | `max-width:640px` | `left:50%; top:0; transform:translateX(-50%); width:18px; height:3px; border-radius:0 0 3px 3px` |
| `.act-sep,.act-spacer` | `max-width:640px` | `display:none` |
| `.avatar` | `max-width:640px` | `flex:0 0 32px; width:30px; height:30px` |
| `*` | `max-width:640px` | `scrollbar-width:none; -ms-overflow-style:none` |
| `*::-webkit-scrollbar` | `max-width:640px` | `display:none; width:0; height:0` |
## Host Secondary Sidebar And Shared Controls
| Selector | Media | Exact declarations |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `.sidebar` | base | `width:232px; flex-shrink:0; background:var(--bg-sidebar); border-right:1px solid var(--border); display:flex; flex-direction:column; overflow-y:auto; overflow-x:hidden; transition:width .15s,opacity .15s` |
| `.sidebar.hidden` | base | `width:0; opacity:0; border:none; pointer-events:none` |
| `.side-block` | base | `padding:8px 8px 3px` |
| `.side-block+.side-block` | base | `border-top:1px solid var(--border)` |
| `.side-title` | base | `font-size:9.5px; font-weight:600; text-transform:uppercase; letter-spacing:.07em; color:var(--text-dim); padding:3px 5px 6px; display:flex; align-items:center; justify-content:space-between` |
| `.side-title .hint` | base | `font-size:10px; font-weight:400; letter-spacing:0; color:var(--text-dim)` |
| `.search-wrap` | base | `display:flex; align-items:center; gap:7px; background:var(--bg-main); border:1px solid var(--border-strong); border-radius:6px; padding:0 9px; height:30px; transition:border-color .15s` |
| `.search-wrap:focus-within` | base | `border-color:var(--accent)` |
| `.search-wrap svg` | base | `color:var(--text-dim); flex-shrink:0` |
| `.search-input` | base | `flex:1; background:transparent; border:none; outline:none; color:var(--text); font-size:12.5px` |
| `.search-input::placeholder` | base | `color:var(--text-dim)` |
| `.side-item` | base | `display:flex; align-items:center; gap:8px; width:100%; min-height:32px; padding:5px 7px; border-radius:5px; border:none; background:transparent; color:var(--text-muted); font-size:12.5px; text-align:left; transition:background .12s,color .12s` |
| `.side-item:hover` | base | `background:var(--bg-hover); color:var(--text)` |
| `.side-item.active` | base | `background:var(--accent-soft); color:var(--accent-hover); font-weight:500` |
| `.route-nav-btn` | base | `display:inline-flex; align-items:center; gap:6px` |
| `.route-nav-btn>svg:last-child,.route-badge svg,.profile-tool>svg:last-child` | base | `flex:none; color:var(--text-dim); transition:transform .12s ease,color .12s ease` |
| `.route-nav-btn:hover>svg:last-child,.route-nav-btn:focus-visible>svg:last-child,.route-nav-btn:hover .route-badge svg,.route-nav-btn:focus-visible .route-badge svg` | base | `transform:translate(1px,-1px); color:var(--accent)` |
| `.route-badge` | base | `display:inline-flex; align-items:center; gap:3px; margin-left:auto; padding:1px 5px; border-radius:4px; background:var(--bg-active); color:var(--text-dim); font-size:9px; font-weight:500; white-space:nowrap` |
| `.side-item .count` | base | `margin-left:auto; font-size:11px; color:var(--text-dim); background:var(--bg-elevated); padding:1px 6px; border-radius:9px` |
| `.side-item.active .count` | base | `background:var(--accent-count-bg); color:var(--accent-hover)` |
| `.side-select` | base | `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` |
| `.switch-row` | base | `display:flex; align-items:center; gap:8px; padding:6px 8px; border-radius:5px; cursor:pointer; font-size:12.5px; color:var(--text-muted)` |
| `.switch-row:hover` | base | `background:var(--bg-hover); color:var(--text)` |
| `.switch-row input` | base | `accent-color:var(--accent); cursor:pointer` |
| `.fav-item` | base | `display:flex; align-items:center; gap:8px; width:100%; padding:6px 8px; border:0; border-radius:5px; background:transparent; color:inherit; font:inherit; text-align:left; cursor:pointer; transition:background .12s` |
| `.fav-item:hover` | base | `background:var(--bg-hover)` |
| `.fav-glyph` | base | `width:26px; height:26px; border-radius:6px; flex-shrink:0; display:flex; align-items:center; justify-content:center; font-family:ui-monospace,monospace; font-size:10px; font-weight:700; color:var(--text-on-accent)` |
| `.fav-name` | base | `font-size:12.5px; color:var(--text); overflow:hidden; text-overflow:ellipsis; white-space:nowrap` |
| `.fav-meta` | base | `font-size:10.5px; color:var(--text-dim)` |
| `.empty-side` | base | `padding:14px 10px; font-size:12px; color:var(--text-dim); line-height:1.6; text-align:center` |
| `.collection-item` | base | `width:100%; border:0; background:transparent; color:var(--text); font:inherit; text-align:left` |
| `.collection-item:focus-visible` | base | `outline:2px solid var(--accent); outline-offset:-2px` |
| `.app.focus .activity,.app.focus .statusbar` | base | `display:none` |
| `.app.focus .sidebar` | base | `display:none` |
| `.sidebar` | `max-width:860px` | `position:absolute; left:52px; top:0; bottom:0; z-index:100; box-shadow:8px 0 24px var(--shadow-sidebar)` |
| `.sidebar` | `max-width:640px` | `left:8px; right:8px; top:auto; bottom:calc(64px + env(safe-area-inset-bottom)); width:auto; height:min(60vh,32rem); max-height:calc(100% - 72px); border:1px solid var(--border-strong); border-radius:8px; box-shadow:0 12px 32px var(--shadow-drawer); z-index:100; transform:translateY(calc(100% + 12px)); visibility:hidden; opacity:0; pointer-events:none; transition:transform .18s ease,opacity .18s ease,visibility .18s` |
| `.sidebar.hidden` | `max-width:640px` | `display:none; width:auto` |
| `.app.mobile-sidebar-open .sidebar` | `max-width:640px` | `transform:translateY(0); visibility:visible; opacity:1; pointer-events:auto` |
## Host Sidebar Drawer Context
These workbench rules establish the sidebar's containing flex area and mobile drawer backdrop.
| Selector | Media | Exact declarations |
| --------------------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.workbench` | base | `flex:1; display:flex; min-height:0; overflow:hidden` |
| `.workbench` | `max-width:640px` | `position:relative; flex-direction:column` |
| `.workbench::before` | `max-width:640px` | `content:''; position:absolute; inset:0; background:var(--backdrop-drawer); opacity:0; pointer-events:none; z-index:90; transition:opacity .18s ease` |
| `.app.mobile-sidebar-open .workbench::before` | `max-width:640px` | `opacity:1; pointer-events:auto` |
## Host Activity-Specific Sidebar Content
| Selector | Media | Exact declarations |
| -------------------------------------------------------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.workspace-sidebar-card` | base | `padding:10px; margin:0 2px 8px; border:1px solid var(--border); border-radius:6px; background:var(--bg-elevated)` |
| `.workspace-sidebar-card strong` | base | `display:block; overflow:hidden; color:var(--text); font-size:11.5px; text-overflow:ellipsis; white-space:nowrap` |
| `.workspace-sidebar-card span` | base | `display:block; margin-top:4px; color:var(--text-muted); font-size:10px` |
| `.workspace-sidebar-list` | base | `display:grid; gap:2px` |
| `.workspace-sidebar-item` | base | `width:100%; display:flex; align-items:center; gap:7px; min-height:30px; padding:5px 7px; border:0; border-radius:5px; background:transparent; color:var(--text-muted); font:inherit; font-size:11.5px; text-align:left; cursor:pointer` |
| `.workspace-sidebar-item:hover,.workspace-sidebar-item.active` | base | `background:var(--bg-hover); color:var(--text)` |
| `.workspace-sidebar-item svg` | base | `flex:none; color:var(--accent)` |
| `.workspace-sidebar-item span` | base | `min-width:0; flex:1; overflow:hidden; text-overflow:ellipsis; white-space:nowrap` |
| `.workspace-sidebar-item small` | base | `flex:none; color:var(--text-dim); font-size:9.5px` |
| `.workspace-sidebar-empty` | base | `padding:6px 7px; color:var(--text-dim); font-size:10.5px` |
| `.workspace-sidebar-more` | base | `width:100%; margin-top:2px; padding:5px 7px; border:0; border-radius:4px; background:transparent; color:var(--accent); font:inherit; font-size:10.5px; text-align:left; cursor:pointer` |
| `.workspace-sidebar-more:hover` | base | `background:var(--bg-hover); color:var(--text)` |
| `.profile-side-card` | base | `display:flex; align-items:center; gap:8px; padding:8px 6px 10px; border-bottom:1px solid var(--border); margin-bottom:4px` |
| `.profile-side-avatar` | base | `width:30px; height:30px; flex:0 0 30px; border-radius:50%; display:grid; place-items:center; background:var(--avatar-gradient); color:var(--text-on-accent); font-size:10px; font-weight:700` |
| `.profile-side-copy` | base | `min-width:0` |
| `.profile-side-copy strong,.profile-side-copy span` | base | `display:block; overflow:hidden; text-overflow:ellipsis; white-space:nowrap` |
| `.profile-side-copy strong` | base | `font-size:11.5px; color:var(--text)` |
| `.profile-side-copy span` | base | `font-size:10px; color:var(--text-dim); margin-top:1px` |
| `.profile-side-group` | base | `padding:6px 0 3px` |
| `.profile-side-group+.profile-side-group` | base | `border-top:1px solid var(--border)` |
| `.profile-side-link` | base | `min-height:30px; font-size:11.5px` |
| `.profile-side-link svg` | base | `width:15px; height:15px; flex:none` |
## SQL Studio Iframe Sidebar
These rules belong only to the mock SQL Studio iframe; its styles do not cross into the host sidebar.
| Selector | Exact declarations |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.sidebar` | `width:212px; flex-shrink:0; background:var(--frame-panel); border-right:1px solid var(--frame-border); display:flex; flex-direction:column; overflow:hidden` |
| `.sb-header` | `padding:14px 14px 10px; border-bottom:1px solid var(--frame-border); display:flex; align-items:center; gap:9px` |
| `.sb-logo` | `width:24px; height:24px; border-radius:6px; background:var(--frame-accent); display:flex; align-items:center; justify-content:center; font-family:ui-monospace,monospace; font-size:9px; font-weight:700; color:var(--frame-on-accent); flex-shrink:0` |
| `.sb-title` | `font-size:13px; font-weight:700; letter-spacing:-.01em` |
| `.sb-scroll` | `flex:1; overflow-y:auto; padding:6px 0; -webkit-overflow-scrolling:touch; overscroll-behavior:contain` |
| `.sb-section` | `padding:8px 12px 4px` |
| `.sb-section-title` | `font-size:10px; text-transform:uppercase; letter-spacing:.07em; color:var(--frame-muted); font-weight:700; padding:2px 6px 6px; display:flex; align-items:center; gap:6px` |
| `.sb-section-title .n` | `background:var(--frame-surface); color:var(--frame-soft); padding:1px 6px; border-radius:8px; font-size:9.5px; letter-spacing:0` |
| `.sb-item` | `display:flex; align-items:center; gap:7px; padding:5px 8px; border-radius:5px; font-size:12.5px; color:var(--frame-secondary); cursor:pointer; transition:background .12s; white-space:nowrap; overflow:hidden` |
| `.sb-item:hover` | `background:var(--frame-surface)` |
| `.sb-item.active` | `background:var(--frame-accent-bg); color:var(--frame-accent-text); font-weight:500` |
| `.sb-item .ico` | `width:14px; height:14px; flex-shrink:0; color:var(--frame-muted); display:flex; align-items:center; justify-content:center; font-size:11px` |
| `.sb-item.active .ico` | `color:var(--frame-accent-icon)` |
| `.sb-item .label` | `flex:1; overflow:hidden; text-overflow:ellipsis` |
| `.sb-item .badge` | `font-size:10px; background:var(--frame-surface); color:var(--frame-soft); padding:1px 6px; border-radius:8px; flex-shrink:0` |
| `.sb-item.active .badge` | `background:var(--frame-accent-bg); color:var(--frame-accent-text)` |
## Inline Sidebar Styles
These are inline style attributes emitted by host sidebar renderers. Background values are dynamic, supplied from collection colors or tool gradient tokens; they are not resolved here.
| Renderer/selector | Exact inline style source |
| ----------------------------------------------------- | --------------------------------------- |
| `collectionsSidebar` / `span.fav-glyph` | `background:` + `esc(collection.color)` |
| `favoritesSidebar`, `recentSidebar` / `div.fav-glyph` | `background:` + `tool.gradient` |
| `favoritesSidebar`, `recentSidebar` / `span` | `min-width:0` |
| `collectionsSidebar` / `button.side-item` | `margin-top:6px` |
The rendered view sample contained 15 inline style instances across these patterns. The SQL Studio sidebar contains no inline styles. Inline HTML source patterns are documented once, not repeated per rendered tool/item.
## Coverage Notes
- Host matching included all eight activity sidebar renderers plus hidden/focus/mobile drawer states; responsive media conditions are shown explicitly.
- Global reset/control inheritance is included where it affects sidebar descendants. Titlebar dropdown/menu rules, page content, and the SQL Studio main toolbar are excluded as separate surfaces.
- Theme values remain semantic references; this source inventory does not define production sidebar components or styles.
- No sandbox HTML or production styles were changed. Refresh this audit when sidebar markup or rules in `sandbox/index.html` change.
@@ -1,133 +0,0 @@
# Sandbox Table Styles And Size Tokens
## Audit Scope
Source: canonical [`sandbox/index.html`](../index.html). This review-only ledger records exact authored table-related CSS and sizes in the sandbox. It does not define production tokens or authorize table migration.
Included surfaces are:
- Host Teams member table wrapper and table geometry.
- Host `thead`, `tbody`, header/body cells, row-last state, fixed column widths, compact breakpoint overrides, and empty-state cell spacing.
- SQL Studio generated iframe table, including direct table, header, body, row hover, sticky header, and first-column rules.
- Literal inline style attributes and JavaScript style assignments that directly affect table elements.
Excluded surfaces are nested controls and indicators inside table cells (member avatar, role select, status, actions, toolbar, panel), because their geometry belongs to control/component audits. Generic page overflow and border/status semantics remain in their respective inventories.
## Source And Count Summary
| Surface | Exact table-related declarations | Responsive declarations | Inline declarations |
| ----------------------- | -------------------------------: | ----------------------: | ------------------: |
| Host Teams table | 38 | 8 | 0 |
| SQL Studio iframe table | 22 | 0 | 0 |
| Total | 60 | 8 | 0 |
The host count includes direct table wrapper/table selectors and all table-specific descendant states. At `max-width: 860px`, 1 table declaration applies; at `max-width: 640px`, 7 table declarations apply. The SQL Studio count includes 22 declarations across `table`, `thead th`, `tbody td`, `tbody tr:hover`, and `tbody td:first-child`; exact values are listed below.
Custom-property references are preserved exactly, including `var(--border)`, `var(--frame-border)`, and `var(--frame-border-soft)`.
## Exact Host Teams Member Table Inventory
| Source scope | Selector | Exact declarations |
| -------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Base | `.team-member-table-wrap` | `width:100%; overflow-x:auto` |
| Base | `.team-member-table` | `width:100%; border-collapse:collapse; table-layout:fixed; text-align:left` |
| Base | `.team-member-table th` | `padding:8px 12px; border-top:1px solid var(--border); border-bottom:1px solid var(--border); background:var(--bg-elevated); color:var(--text-dim); font-size:9px; font-weight:700; text-transform:uppercase` |
| Base | `.team-member-table td` | `height:48px; padding:6px 12px; border-bottom:1px solid var(--border); color:var(--text-muted); font-size:10.5px; vertical-align:middle` |
| Base | `.team-member-table tbody tr:last-child td` | `border-bottom:0` |
| Base | `.team-member-table th:first-child, .team-member-table td:first-child` | `width:48%` |
| Base | `.team-member-table th:nth-child(2), .team-member-table td:nth-child(2)` | `width:20%` |
| Base | `.team-member-table th:nth-child(3), .team-member-table td:nth-child(3)` | `width:20%` |
| Base | `.team-member-table th:last-child, .team-member-table td:last-child` | `width:56px; text-align:center` |
| Base | `.team-filter-empty td` | `padding:18px 12px; color:var(--text-dim); text-align:center` |
| `@media (max-width:860px)` | `.team-member-table` | `min-width:620px` |
| `@media (max-width:640px)` | `.team-member-table` | `min-width:0` |
| `@media (max-width:640px)` | `.team-member-table th, .team-member-table td` | `padding-inline:3px` |
| `@media (max-width:640px)` | `.team-member-table td` | `height:44px` |
| `@media (max-width:640px)` | `.team-member-table th:first-child, .team-member-table td:first-child` | `width:50%` |
| `@media (max-width:640px)` | `.team-member-table th:nth-child(2), .team-member-table td:nth-child(2)` | `width:20%` |
| `@media (max-width:640px)` | `.team-member-table th:nth-child(3), .team-member-table td:nth-child(3)` | `width:18%` |
| `@media (max-width:640px)` | `.team-member-table th:last-child, .team-member-table td:last-child` | `width:12%` |
## Exact SQL Studio Iframe Table Inventory
The SQL Studio rules occur once in the single `sql-studio` generated iframe stylesheet embedded in `sandbox/index.html`. They are isolated from the host table and do not inherit host Teams table geometry.
| Source scope | Selector | Exact declarations |
| ------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Iframe base | `table` | `width:100%; border-collapse:collapse; font-size:12.5px` |
| Iframe base | `thead th` | `text-align:left; padding:8px 14px; font-size:10.5px; text-transform:uppercase; letter-spacing:.05em; color:var(--frame-muted); font-weight:700; border-bottom:1px solid var(--frame-border); background:var(--frame-panel); position:sticky; top:31px; z-index:2` |
| Iframe base | `tbody td` | `padding:8px 14px; border-bottom:1px solid var(--frame-border-soft); color:var(--frame-secondary)` |
| Iframe base | `tbody tr:hover` | `background:var(--frame-panel)` |
| Iframe base | `tbody td:first-child` | `color:var(--frame-accent-text); font-family:ui-monospace,monospace; font-weight:600` |
No media query or inline style changes these iframe table rules in the embedded SQL Studio document.
## Exact Cascade And Responsive Contract
### Base Host Table
- Wrapper: `100%` width with horizontal overflow at the wrapper, and no fixed table minimum.
- Table: `100%` width, collapsed borders, fixed layout, left text alignment.
- Header cells: 8px top/bottom and 12px inline padding; 9px uppercase text; 700 weight; dimensional and visual borders use the host semantic references.
- Body cells: fixed 48px height; 6px top/bottom and 12px inline padding; 10.5px text; middle vertical alignment.
- Final body row removes the bottom border. Empty filtered-state cell gets 18px 12px padding and centered 10.5px-inherited text color.
- Fixed columns sum to 144% at base: 48% + 20% + 20% + 56px. Under fixed table layout and horizontal overflow, the remaining proportional widths share the 88% remaining after the fixed 56px column, subject to browser table sizing.
### Compact Host Table Cascade
- At `max-width:860px`, the table receives `min-width:620px`, activating wrapper overflow for a four-column table.
- At `max-width:640px`, `min-width` becomes `0`, inline cell padding becomes `3px`, body height becomes `44px`, and column widths become 50% + 20% + 18% + 12%.
- The 640px reset is later in source order, so it overrides the 860px `min-width:620px` and the base 48% first column, 20% role column, 20% status column, and 56px action column.
- The action column becomes percentage-based at 640px instead of its base fixed 56px width.
### Iframe Table Cascade
- Table font size is 12.5px, inherited by unstyled descendants.
- Header cells are sticky at `31px` with `z-index:2`, left aligned, 8px 14px padded, 10.5px uppercase text, 700 weight, and `.05em` letter spacing.
- Body cells use 8px 14px padding and semantic soft bottom separators.
- Row hover and first-column emphasis are state/type rules, not separate table geometry declarations.
## Markup Coverage
The Teams table markup is generated in JavaScript and contains:
```html
<div class="team-member-table-wrap">
<table class="team-member-table">
<thead>
<tr>
<th scope="col">Member</th>
<th scope="col">Role</th>
<th scope="col">Status</th>
<th scope="col"><span class="sr-only">Actions</span></th>
</tr>
</thead>
<tbody data-team-members>
...
</tbody>
</table>
</div>
```
The SQL Studio iframe markup contains a generic:
```html
<table>
<thead>
...
</thead>
<tbody>
...
</tbody>
</table>
```
Neither surface has literal inline `style` attributes on `table`, `thead`, `tbody`, `tr`, `th`, or `td`. No JavaScript table-element style assignment was found. The SQL Studio script changes `text.style.color` only for status text and does not affect table geometry.
## Verification
- Raw CSS source declarations reconcile to 30 exact base host Teams table declarations and 8 exact host responsive declarations.
- Raw iframe stylesheet declarations reconcile to 22 exact SQL Studio table declarations.
- Responsive host declarations remain separated by exact media scope rather than flattened.
- Reconciliation found no inline table declaration and no missing or duplicate direct table selector in the canonical source.
- This file is a review-only forensic record; no sandbox or production CSS was changed.
+74 -20
View File
@@ -1,48 +1,102 @@
# DataStack Python SDK
# DataStack Python SDK (`datastack-sdk`)
Official Python client for the **DataStack Universal Realtime Data Collection Platform**.
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../LICENSE)
[![Python 3.8+](https://img.shields.io/badge/Python-3.8%2B-3776AB)](https://www.python.org/)
[![Maintained by Vib Tools](https://img.shields.io/badge/Maintained%20by-Vib%20Tools-0f172a)](https://vib.tools/)
Official Python client library for **DataStack — Self-Hosted Real-Time Telemetry & Event Logging Platform**, developed by **[Vib Tools](https://vib.tools/)**.
`datastack-sdk` enables Python services, IoT sensor nodes, microservice workers, and research pipelines to stream structured JSON telemetry events to a DataStack server over Socket.IO with deterministic `threading.Event` acknowledgments.
---
## Installation
Install directly via pip:
Install directly from the `sdk-python` directory:
```bash
pip install ./sdk-python
```
Or in development:
For editable development mode:
```bash
cd sdk-python && pip install -e .
```
---
## Quick Start
```python
from datastack_sdk import DataStackClient
# 1. Initialize client with JWT from /vcon/clients console
# 1. Initialize the client with a signed JWT token from /vcon/clients or /vcon/sdk
client = DataStackClient(
server_url="http://localhost:4000",
token="YOUR_CLIENT_JWT_TOKEN"
token="YOUR_CLIENT_JWT_TOKEN",
)
# 2. Connect to Ingestion Engine
# 2. Connect to the DataStack Socket.IO server
if client.connect():
# 3. Stream single realtime event
res = client.sync({
"action": "user_checkout",
"order_id": "ORD-9482",
"amount": 249.50,
"currency": "USD"
})
# 3. Stream a single structured event and wait for server acknowledgment
res = client.sync(
data={
"event_type": "service_heartbeat",
"service": "billing-worker",
"latency_ms": 18.4,
"status": "healthy",
},
timeout=5.0,
)
print("Sync result:", res)
# 4. Stream batch of records
batch_res = client.batch_sync([
{"metric": "cpu_load", "value": 42.1},
{"metric": "mem_usage", "value": 78.5},
{"metric": "disk_io", "value": 1120}
])
# 4. Stream a batch of events in a single round-trip
batch_res = client.batch_sync(
records=[
{"metric": "cpu_load", "value": 42.1, "unit": "%"},
{"metric": "mem_usage", "value": 68.5, "unit": "%"},
{"metric": "disk_free_gb", "value": 124.0, "unit": "GB"},
],
timeout=10.0,
)
print("Batch result:", batch_res)
# 5. Disconnect cleanly
client.disconnect()
```
---
## API Reference
### `DataStackClient(server_url="http://localhost:4000", token="", reconnection_attempts=5, reconnection_delay=1)`
Creates a new Socket.IO client instance configured for DataStack handshake authentication.
### `client.connect(wait_timeout=5) -> bool`
Establishes a WebSocket/Socket.IO connection to the DataStack Port 4000 ingestion server using `auth={"token": self.token}`. Returns `True` on success or `False` on connection failure.
### `client.sync(data, event_id=None, timeout=5.0) -> dict`
Emits a single event (`sync_data`) and blocks via `threading.Event.wait(timeout)` until the server responds.
- **Returns**: `{"success": True, "eventId": "evt_..."}` or `{"success": False, "eventId": "evt_...", "error": "..."}`.
### `client.batch_sync(records, timeout=10.0) -> dict`
Emits a list of event dictionaries (`batch_sync`) and blocks via `threading.Event.wait(timeout)` until the server acknowledges the batch.
- **Returns**: `{"success": True, "processed": N, "rejected": M}`.
### `client.disconnect()`
Cleanly closes the active Socket.IO connection.
---
## Author & Support
Developed and maintained by **[Vib Tools](https://vib.tools/)**:
- **Website**: [https://vib.tools/](https://vib.tools/)
- **GitHub**: [https://github.com/vibtoolshq](https://github.com/vibtoolshq)
- **General Email**: [hello@vibtools.io](mailto:hello@vibtools.io)
- **Technical Support**: [support@vibtools.io](mailto:support@vibtools.io)
## License
Released under the [MIT License](../LICENSE).
+5 -8
View File
@@ -1,13 +1,10 @@
# Python SDK Manifest
## Purpose
Pip-installable Python client SDK (`datastack-sdk`) enabling Python applications, scrapers, and telemetry daemons to stream real-time events to DataStack.
Pip-installable Python client SDK (`datastack-sdk`) enabling Python services, IoT telemetry agents, and analytics applications to stream structured real-time events to DataStack.
## Contents
- `setup.py`: Standard setuptools configuration
- `datastack_sdk/client.py`: `DataStackClient` class with automatic reconnection, JWT handshake, and sync/batch_sync methods
- `README.md`: Quickstart guide and API reference.
## Dependencies
- `python-socketio[client]`
- `requests`
- `setup.py`: Package metadata and dependencies (`python-socketio[client]`, `requests`).
- `datastack_sdk/__init__.py`: Exports `DataStackClient`.
- `datastack_sdk/client.py`: `DataStackClient` implementation featuring JWT handshake authentication, automatic reconnection, and thread-safe acknowledgment waiting (`threading.Event`) for `sync()` and `batch_sync()`.
- `README.md`: Installation instructions, quickstart example, and API reference.
+24 -4
View File
@@ -3,18 +3,38 @@ from setuptools import setup, find_packages
setup(
name="datastack-sdk",
version="1.0.0",
description="Python client SDK for DataStack Universal Realtime Data Collection Platform",
long_description=open("README.md").read(),
description="Official Python client SDK for DataStack — Self-Hosted Real-Time Telemetry & Event Logging Platform",
long_description=open("README.md", encoding="utf-8").read(),
long_description_content_type="text/markdown",
author="DataStack Engine Team",
author="Vib Tools",
author_email="hello@vibtools.io",
url="https://github.com/vibtoolshq",
project_urls={
"Homepage": "https://vib.tools/",
"Source": "https://github.com/vibtoolshq",
"Support": "mailto:support@vibtools.io",
},
license="MIT",
packages=find_packages(),
install_requires=[
"python-socketio[client]>=5.11.0",
"requests>=2.31.0",
"websocket-client>=1.7.0"
"websocket-client>=1.7.0",
],
classifiers=[
"Development Status :: 5 - Production/Stable",
"Intended Audience :: Developers",
"Intended Audience :: System Administrators",
"Intended Audience :: Science/Research",
"Topic :: System :: Logging",
"Topic :: System :: Monitoring",
"Topic :: Software Development :: Libraries :: Python Modules",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.8",
"Programming Language :: Python :: 3.9",
"Programming Language :: Python :: 3.10",
"Programming Language :: Python :: 3.11",
"Programming Language :: Python :: 3.12",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
],
+83 -2
View File
@@ -159,9 +159,48 @@ function scheduleFlushTimer(intervalMs) {
scheduleFlushTimer(runtimeConfig.batchFlushIntervalMs);
async function ensureDatabaseSchema() {
if (!dbPool) return;
try {
await dbPool.query(`
CREATE TABLE IF NOT EXISTS client_sdks (
client_id TEXT PRIMARY KEY,
name TEXT NOT NULL,
secret TEXT NOT NULL,
token TEXT NOT NULL,
rate_limit INTEGER NOT NULL DEFAULT 100,
status TEXT NOT NULL DEFAULT 'active',
total_events BIGINT NOT NULL DEFAULT 0,
last_active TIMESTAMPTZ,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
)
`);
await dbPool.query(`
CREATE TABLE IF NOT EXISTS admin_settings (
id TEXT PRIMARY KEY DEFAULT 'default',
server_port INTEGER NOT NULL DEFAULT 4000,
web_port INTEGER NOT NULL DEFAULT 3000,
max_events_per_sec INTEGER NOT NULL DEFAULT 100,
max_payload_size_kb INTEGER NOT NULL DEFAULT 100,
batch_flush_threshold INTEGER NOT NULL DEFAULT 500,
batch_flush_interval_ms INTEGER NOT NULL DEFAULT 2000,
file_rotation_mb INTEGER NOT NULL DEFAULT 100,
jwt_secret TEXT NOT NULL,
enable_idempotency BOOLEAN NOT NULL DEFAULT true,
auto_prune_days INTEGER NOT NULL DEFAULT 30,
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
)
`);
} catch {
// Ignore transient startup DB error; retried on next sync cycle
}
}
async function syncSettingsFromDatabase() {
if (!dbPool) return;
try {
await ensureDatabaseSchema();
const res = await dbPool.query(
`SELECT max_events_per_sec, max_payload_size_kb, batch_flush_threshold,
batch_flush_interval_ms, file_rotation_mb, jwt_secret, enable_idempotency
@@ -196,13 +235,14 @@ async function syncSettingsFromDatabase() {
scheduleFlushTimer(nextIntervalMs);
}
} catch {
// Keep existing runtimeConfig if table is not created yet
// Keep existing runtimeConfig if table is not ready yet
}
}
let settingsSyncTimer = null;
if (dbPool) {
void syncSettingsFromDatabase();
setInterval(() => {
settingsSyncTimer = setInterval(() => {
void syncSettingsFromDatabase();
}, 3000);
}
@@ -252,6 +292,47 @@ setupSocketHandlers(io, bufferQueue, writer, {
},
});
let isShuttingDown = false;
async function gracefulShutdown(signal) {
if (isShuttingDown) return;
isShuttingDown = true;
console.log(`[DataStack Ingestion Engine] Received ${signal}, flushing buffer before exit...`);
if (flushTimer) {
clearInterval(flushTimer);
flushTimer = null;
}
if (settingsSyncTimer) {
clearInterval(settingsSyncTimer);
settingsSyncTimer = null;
}
try {
await flushBuffer();
} catch {
// Best-effort flush on exit
}
try {
io.close();
server.close();
if (dbPool) {
await dbPool.end();
}
} catch {
// Ignore close errors
}
process.exit(0);
}
process.on('SIGTERM', () => {
void gracefulShutdown('SIGTERM');
});
process.on('SIGINT', () => {
void gracefulShutdown('SIGINT');
});
server.listen(PORT, () => {
console.log(
`[DataStack Ingestion Engine] Express + Socket.IO listening on port ${PORT}`,
+5 -13
View File
@@ -1,17 +1,9 @@
# Server Manifest
# Socket.IO Ingestion Server Manifest (`server/`)
## Purpose
Independent Express.js and Socket.IO ingestion service operating on Port 4000.
Standalone Express.js and Socket.IO ingestion service running on Port `4000` (`server/index.js`).
## Architecture
- **Port**: 4000 (Decoupled from Next.js on port 3000)
- **Role**: High-throughput WebSocket handshake, JWT verify, event intake
- **Worker**: `workers/csvWriter.js` for async batch appending to `/storage/data/{clientId}/{YYYY-MM-DD}.csv`
- **Socket Handlers**: `socket/handlers.js` with client room partitioning and rate limiting.
## Dependencies
- `express`
- `socket.io`
- `cors`
- `jsonwebtoken`
- `json2csv`
- `index.js`: Initializes the HTTP/Socket.IO server, synchronizes runtime settings and client status from PostgreSQL (`admin_settings`, `client_sdks`), schedules periodic and threshold-based buffer flushes, and exposes `GET /health` and `POST /internal/flush`.
- `socket/handlers.js`: Authenticates Socket.IO handshakes via JWT, blocks revoked clients or rotated tokens in real time, validates rate limits, payload sizes, and 5-minute TTL idempotency on `sync_data` and `batch_sync`, and updates client event counters in PostgreSQL.
- `workers/csvWriter.js`: Asynchronous batch CSV writer appending queued events to `/storage/data/{clientId}/{YYYY-MM-DD}.csv` with automatic size-based file rotation (`-part2.csv`).
+7 -9
View File
@@ -1,12 +1,10 @@
# Storage Data Manifest
# Storage Directory Manifest (`storage/`)
## Purpose
Root directory for all collected realtime CSV datasets.
Root storage directory for partitioned CSV event datasets written by the Next.js and Port 4000 ingestion engines.
## Directory Structure
`/storage/data/{clientId}/{YYYY-MM-DD}.csv`
## Rotation Rules
- Daily partition by ISO date string (`YYYY-MM-DD.csv`)
- Size rotation partition (`{YYYY-MM-DD}-part{N}.csv`) when any single file reaches 100MB threshold.
- Row schema: `clientId, eventId, timestamp, payload`
## Partition Layout
- **File Path**: `/storage/data/{clientId}/{YYYY-MM-DD}.csv`
- **Overflow Rotation**: `/storage/data/{clientId}/{YYYY-MM-DD}-part{N}.csv` when a partition reaches the configured `fileRotationMb` size limit (default `100MB`).
- **CSV Header**: `clientId,eventId,timestamp,payload`
- **Git Policy**: Runtime data files under `storage/data/` are ignored by Git (`.gitignore`).
-5
View File
@@ -1,5 +0,0 @@
# VCON Helpers Manifest
## Purpose
Helper utilities and React hooks for the `/vcon/` admin console.
Notice: Routes reside in `app/vcon/`. This folder contains helper libraries and custom hooks only.