Metadata-Version: 2.4
Name: colloquium
Version: 0.1.0
Summary: Agent-native slide creation tool for research talks
Project-URL: Homepage, https://github.com/interconnects-ai/colloquium
Project-URL: Repository, https://github.com/interconnects-ai/colloquium
Author: Nathan Lambert
License-Expression: MIT
License-File: LICENSE
Keywords: academic,markdown,presentations,research,slides
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.10
Requires-Dist: markdown-it-py>=3.0
Requires-Dist: mdit-py-plugins>=0.4
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

# Colloquium — Agent Instructions

## What This Is
Colloquium is an agent-native slide creation tool for research talks. Markdown-based, git-friendly, AI-drivable.

## Commands
- Use `uv` for all Python operations
- `uv pip install -e .` to install in dev mode
- `uv run colloquium build examples/hello.md` to build slides
- `uv run colloquium serve examples/hello.md` for dev server
- `uv run pytest` to run tests

## Architecture Patterns

### CSS
- Slides use `display:none` by default, `display:flex` on `.active`
- CSS specificity: `.slide--type.active` not `.slide--type` (avoids display override bugs)
- CSS custom properties (`--colloquium-*`) for all theme colors/fonts
- Humans can override with custom CSS or per-slide `style` directives

### Navigation (presentation.js)
- Keyboard: arrows, Home/End, Space, PgUp/PgDn, F (fullscreen), Esc
- Click zones: left 1/3 back, right 2/3 forward
- Touch swipe support
- Hash-based URL routing (#1, #2, ...)
- Slide counter + progress bar

### Slide Directives
Per-slide configuration via HTML comments:
- `<!-- layout: two-column -->` — slide layout
- `<!-- class: highlight -->` — CSS classes
- `<!-- style: background: #1a1a2e -->` — inline styles
- `<!-- notes: Speaker notes here -->` — speaker notes (hidden in presentation)

### Output
- All output is a single self-contained HTML file (CSS/JS inlined)
- KaTeX (CDN) for LaTeX math
- highlight.js (CDN) for code syntax highlighting

### PDF Export
- Primary: `@media print` CSS makes all slides visible with page breaks, hides nav
- Users can `Cmd+P` in any browser for a clean PDF
- CLI convenience: `colloquium export` tries system Chrome `--headless --print-to-pdf`
- Optional ghostscript compression if `gs` is on PATH

### Dependencies
- Only 3 runtime deps: markdown-it-py, mdit-py-plugins, pyyaml
- Everything else is stdlib or browser-side CDN

### Citation Convention (Forward-Compatible)
- Use `[@key]` pandoc-style citations in slides (bibtex support planned)
- For now, use plain text citations and manual References slides

## File Layout
```
src/colloquium/
├── __init__.py       # Version, top-level imports
├── cli.py            # argparse CLI entry points
├── parse.py          # Markdown → Slide data structures
├── build.py          # Slides → HTML generation
├── serve.py          # Dev server with live reload
├── export.py         # PDF export (system Chrome + print CSS)
├── deck.py           # Deck class (agent-facing API)
├── slide.py          # Slide dataclass
└── themes/default/
    ├── theme.css     # Default theme
    └── presentation.js  # Navigation engine
```
