⚡ FastStrap Preview Studio

Interactive real-time component studio, live playground, and documentation preview engine for FastStrap + FastHTML.

Built primarily as a local learning tool: run the Studio on your own machine, explore real FastStrap examples, and use the code sandbox locally. The Studio shell, Bootstrap/FastStrap assets, and FastHTML's base browser runtimes are served from the local installation. Optional rich renderers (KaTeX, Mermaid, Chart.js, Plotly, and GSAP) still load from CDNs when their components are previewed, so those specific examples need internet access.

🌟 Key Features

• ⚡ Local-First & Offline Core: The Studio and its standard component examples run locally without shared cloud compute. Optional rich renderers may need internet access.
• 📦 Explicit Import Guidance: Every component in the Studio displays an exact, 1-click copyable import statement (from faststrap import ... or from faststrap.presets import ...) alongside runnable code snippets.
• 🎨 Interactive Canvas & Auto-Height: Smooth viewport switcher (Mobile 375px, Tablet 768px, Laptop 1024px, Desktop 100%), background modes (Dark grid, Light grid, Checkerboard, Transparent), and adaptive canvas auto-height.
• 🔧 Type-Safe Interactive Controls: Real-time debounced parameter knobs for variants, sizes, shapes, numbers, and boolean toggles.
• 📋 Dynamic Props Reference: Built-in parameter tables with argument types, defaults, and descriptions for 86 components, including FastStrap v0.10.0's mobile, collection, and responsive table components.
• 🔗 MkDocs Documentation Embeds: Dedicated /embed/{component} endpoint for clean iframe embedding in documentation sites.
• 🧪 Interactive HTMX Sandbox: Real-time interactive demos for ActiveSearch, LoadingButton, EmailValidation, and DataTable with simulated network latency.
• 🧪 Trusted Local Code Playground: Run complete FastHTML examples on your own machine. Keep the Studio loopback-only; hosted documentation mode can disable the sandbox routes entirely.

🚀 Running Locally (Single Command)

Install From Source

# 1. Clone repo
git clone https://github.com/Faststrap-org/FastStrap-Studio.git
cd FastStrap-Studio

# 2. Create and activate a virtual environment, then install the Studio
python -m venv .venv
# Windows PowerShell: .venv\Scripts\Activate.ps1
# macOS/Linux: source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

# 3. Start preview server
python main.py

Open http://127.0.0.1:8080 in your browser. A PyPI installation command will be added after the Studio package has actually been published.

Environment variables supported:

• PORT: Server port (default: 8080)
• HOST: Bind host (default: 127.0.0.1, local machine only)
• RELOAD: Enable hot-reloading (e.g. RELOAD=true)
• STUDIO_ENABLE_ARBITRARY_EXEC: Defaults to true for the local trusted-user workflow. This allows examples to use normal Python imports and application code. It is not a security sandbox; do not expose this mode to untrusted users. Setting it to false applies AST restrictions, but is not process or container isolation.
• STUDIO_ENABLE_SANDBOX: Defaults to true; set to false to omit /sandbox/* routes entirely when hosting only the curated component preview endpoints for documentation.

The Studio's local arbitrary-code sandbox is intentional: it runs code on the user's own machine so complete FastHTML examples work without shared cloud execution. Base frontend scripts are vendored in faststrap_studio/static/vendor/; their upstream versions and licenses are listed in faststrap_studio/static/vendor/README.md. For a hosted docs integration, disable the sandbox and expose only curated /embed/* and /preview/* routes. The STUDIO_ENABLE_ARBITRARY_EXEC=false mode applies AST restrictions but is not a substitute for process/container isolation and should not be presented as a secure public multi-user execution service. Keep the default bind address on loopback; setting HOST=0.0.0.0 exposes the local server to the network.

💡 Using Components in Your FastHTML App

Every component page in Studio provides a copyable import chip:

# 1. Import from FastStrap
from faststrap import Button, Card, Modal, Input, Navbar

# Or from presets for specialized widgets
from faststrap.presets import LoadingButton, KPICard, MetricCard

# 2. Render in FastHTML
@app.get("/")
def home():
    return Card(
        Button("Get Started", variant="primary", pill=True),
        title="Welcome to FastStrap",
    )

📖 Embedding Previews in MkDocs Documentation

To embed an interactive component preview in any markdown documentation page:

<iframe
  src="http://localhost:8080/embed/Button?variant=primary&size=lg&pill=true&text=Click+Me"
  width="100%"
  height="200"
  frameborder="0"
  data-faststrap-preview
></iframe>

When deployed to production, replace localhost:8080 with your hosted studio base URL (STUDIO_BASE_URL env variable).

Add the bridge script to your documentation site (extra_javascript in mkdocs.yml) for automatic iframe height adjustments and theme synchronization:

<script src="/studio-static/js/embed.js"></script>

🧪 Running Tests

# Run full automated test suite (85 tests)
pytest tests/ -q

# Run code linter
ruff check faststrap_studio tests

📂 Architecture Overview

faststrap_studio/
├── __init__.py                 # Lazy package exports (app, cli)
├── main.py                     # Entry point, static files mounting & CORS
├── config.py                   # Environment & base settings
├── catalogue/                  # Modular component specifications & controls (86 components)
│   ├── __init__.py             # Unified CATALOGUE registry & metadata index
│   ├── actions.py              # Buttons, FABs, Toolbars, Segmented Controls
│   ├── display.py              # Cards, Tables, DataCards, Metrics, Tags, Stepper
│   ├── forms.py                # Inputs, Selects, Switches, DatePickers, Sliders, OTP
│   ├── feedback.py             # Alerts, Toasts, Modals, Loaders, Placeholders
│   ├── layout.py               # Containers, Grids, Separators, Page Headers
│   ├── navigation.py           # Navbars, Tabs, Breadcrumbs, Pagination, Dropdowns
│   └── patterns.py             # Pricing Tiers, Feature Highlights, Marketing
├── routes/
│   ├── meta.py                 # Gallery (/), Studio (/studio/{name}), API (/api/catalogue)
│   ├── preview.py              # Isolated iframe canvas with type-safe param parser (/preview/{name})
│   ├── embed.py                # Clean widget endpoint for documentation embeds (/embed/{name})
│   ├── demo.py                 # Interactive HTMX sandbox pages (/demo/*)
│   ├── mock.py                 # Realistic mock backend endpoints with latency simulation
│   ├── theme.py                # Cookie-persisted dark/light theme switcher
│   ├── sandbox.py              # Safe code editor & multi-device preview (/sandbox)
│   ├── export.py               # FastHTML app generator & download (/export/{name})
│   └── assets.py               # Optimized head asset injector
├── static/
│   ├── css/studio.css          # Studio stylesheet & design tokens
│   ├── js/studio.js           # Debounced sync, clipboard, resizer & lazy loader
│   └── js/embed.js            # Bridge script for MkDocs documentation sites
└── tests/
    └── test_catalogue_render.py# Automated pytest suite for all specs & endpoints