Proposals

Author: davegaeddert

proposals/README.md

@@ -2,28 +2,28 @@
 
 Lightweight implementation ideas for Plain packages.
 
+These are considered living documents. Some implementation details have been thought through, but they haven't been tried yet so here they sit! They are here because we haven't had the need or time yet to fully implement and release them.
+
+These are primarily written with the help of Claude Code.
+
 ## Format
 
-One file per package: `plain-auth.md`, `plain-models.md`, etc.
+One file per proposal: `<package>-<feature-name>.md`
 
 ```markdown
-# plain-<package>
-
-## Feature Name
+# plain-<package>: Feature Name
 
 - Implementation point
 - Another point
 - Why it matters (optional)
 
----
-
-## Another Feature
+## Optional Section
 
-- Another approach
+- Details if needed
 ```
 
 ## Usage
 
-- Add ideas when you have them
-- Delete sections when implemented or abandoned
+- Add new proposals as separate files
+- Delete files when implemented or abandoned
 - Git history keeps old ideas

proposals/plain-assets-webp.md

@@ -0,0 +1,131 @@
+# plain-assets: Automatic WebP Conversion
+
+**Status:** Core feature, optional based on `cwebp` availability
+
+## Overview
+
+Automatically convert PNG/JPEG images to WebP during `plain build` to reduce file sizes by ~25-35%.
+
+**Enabled when:** User has `cwebp` binary installed (from libwebp package)
+
+**Disabled when:** `cwebp` not found (silent skip, no errors)
+
+## Installation (Optional)
+
+```bash
+# macOS
+brew install webp
+
+# Ubuntu/Debian
+sudo apt install webp
+
+# Alpine (Docker)
+apk add libwebp-tools
+```
+
+## Key Design Decisions
+
+- **Optional core feature**: Built into plain-assets, no separate package
+    - If `cwebp` available → WebP variants generated
+    - If not → Original behavior (no WebP)
+    - Zero Python dependencies
+
+- **Dual format strategy**: Generate both original and WebP versions
+    - `hero.jpg` → `hero.abc123.jpg` + `hero.abc123.webp`
+    - Both fingerprinted and added to manifest
+    - No template changes required (backward compatible)
+
+- **Header-based serving**: Use `Accept: image/webp` header
+    - Browser requests `hero.jpg` with `Accept: image/webp`
+    - Server transparently serves `hero.webp` if available
+    - Cleaner than `<picture>` elements
+    - Works with existing `{% asset %}` tags
+
+- **Browser support**: 96%+ in 2025
+    - Supported: Chrome 32+, Firefox 65+, Safari 14+, Edge 18+
+    - Fallback via dual format for old browsers
+
+## Configuration (Optional)
+
+Probably don't need settings - sensible defaults work for everyone. But if needed:
+
+```python
+# settings.py
+ASSETS_WEBP_QUALITY = 85  # Default: 85 (0-100)
+ASSETS_WEBP_ONLY_IF_SMALLER = True  # Default: True (skip if WebP is larger)
+```
+
+## Build Integration
+
+```python
+# In plain/plain/assets/compile.py
+
+def has_webp_support():
+    """Check if cwebp binary is available."""
+    return shutil.which("cwebp") is not None
+
+def compile_assets():
+    webp_enabled = has_webp_support()
+
+    for asset in assets:
+        # Copy original
+        copy_file(asset)
+        fingerprint_file(asset)
+
+        # Generate WebP if enabled and applicable
+        if webp_enabled and is_image(asset):
+            webp_path = convert_to_webp(asset, quality=85)
+            if webp_path:
+                fingerprint_file(webp_path)
+```
+
+## Serving Logic
+
+```python
+# In plain/plain/assets/views.py
+
+def get(self, request, path):
+    # Try to serve WebP variant if browser supports it
+    if path.endswith(('.jpg', '.jpeg', '.png')):
+        if 'image/webp' in request.headers.get('Accept', ''):
+            webp_path = get_webp_variant(path)
+            if webp_path and webp_path in manifest:
+                path = webp_path
+
+    return serve_file(path)
+```
+
+## User Experience
+
+**Developer installs cwebp:**
+
+```bash
+brew install webp
+plain build
+# → Images automatically get WebP variants
+# → Browsers automatically get smaller files
+```
+
+**Developer doesn't install cwebp:**
+
+```bash
+plain build
+# → Works exactly as before
+# → No WebP variants generated
+# → No errors or warnings
+```
+
+**Optional: Check if WebP is working**
+
+```bash
+plain build --verbose
+# → "WebP: Converted 12 images (saved 2.3MB)"
+# OR
+# → "WebP: cwebp not found (install with 'brew install webp')"
+```
+
+## Questions to Resolve
+
+1. **Verbosity**: Should we show a one-time hint if `cwebp` not found?
+2. **AVIF support**: Also support AVIF via `avifenc` (same pattern)?
+3. **Manifest format**: How to represent variants in fingerprint manifest?

proposals/plain-dev-companion.md

@@ -0,0 +1,13 @@
+# plain-dev: WebSocket Development Companion
+
+- WebSocket server integrated into `plain dev` poncho processes
+- Browser script injected via middleware or template tag when `DEBUG=True`
+- Use [idiomorph](https://github.com/bigskysoftware/idiomorph) for DOM morphing instead of full page refreshes
+- Based on ideas from [repaint](https://github.com/dropseed/repaint) project
+
+## Live Reloading
+
+- Template changes → morph DOM with idiomorph (preserves form state, scroll position)
+- Python changes → full refresh after server restart
+- CSS changes → hot reload stylesheets without page refresh
+- Hook into existing `plain.internal.reloader` file watching

proposals/plain-elements-dev-toolbar.md

@@ -0,0 +1,6 @@
+# plain-elements: Development Toolbar Integration
+
+- Visual element inspection during development (inspired by Phoenix LiveView)
+- Highlight elements on page with tooltip showing name and template path
+- Click element to open template file in editor
+- Toolbar button to toggle inspection mode

proposals/plain-email-filebased-viewing.md

@@ -0,0 +1,58 @@
+# plain-email: Filebased Backend HTML/Text Viewing
+
+- Enhance filebased backend to save `.txt` and `.html` files alongside `.log` files
+- Makes email content easily viewable without parsing raw RFC 822 format
+- Double-click `.html` to preview email in browser during development
+- Cat `.txt` or open in editor for quick reading of plain text content
+- Keep `.log` file for debugging (full headers, MIME structure, attachments)
+
+## Current State
+
+- Filebased backend saves emails as `.log` files with raw RFC 822/MIME format
+- Includes full headers, multipart boundaries, base64 encoding, etc.
+- Not human-readable or easily viewable in browser
+- Inherited from Django with unclear use case
+- Console backend is more useful for dev (immediate stdout output)
+
+## Proposed Enhancement
+
+Save three files per email with shared timestamp prefix:
+
+```
+EMAIL_FILE_PATH/
+  20250127-143045-123456.log   # Raw RFC 822 format (existing)
+  20250127-143045-123456.txt   # Plain text body only
+  20250127-143045-123456.html  # HTML body only (if present)
+```
+
+- Parse email message to extract text and HTML parts
+- Save each part to separate file for easy access
+- Handle multipart emails correctly (extract from appropriate MIME part)
+- Skip `.html` if email has no HTML part (text-only emails)
+- Backward compatible: still saves `.log` file
+
+## Why It Matters
+
+- **Development workflow**: See how emails actually render in browser
+- **Template debugging**: Verify HTML output without SMTP setup
+- **Quick testing**: No need to parse MIME format manually
+- **No complexity**: Still file-based, no database or server required
+- **Email client preview**: See exactly what recipients will see
+
+## Implementation
+
+Modify `plain-email/plain/email/backends/filebased.py`:
+
+- Extract text body: `message.body` attribute
+- Extract HTML body: Look for `text/html` alternative in `EmailMultiAlternatives`
+- Use same timestamp prefix for all three files
+- Write files atomically to avoid partial writes
+- Handle encoding correctly (UTF-8 for text/html files)
+
+## Future Enhancements
+
+- Toolbar integration: Browse emails with metadata (subject, from, to, date)
+- Use `.eml` extension instead of `.log` (standard email file format)
+- Add `.json` metadata file for programmatic access
+- Setting to skip `.log` file if not needed (save space)
+- Index file (`emails.html`) linking to all captured emails

proposals/plain-email-modern-email-apis.md

@@ -0,0 +1,23 @@
+# plain-email: Modern Python Email APIs
+
+- Replace legacy `email.mime.*` classes with modern `email.message.EmailMessage` (Python 3.6+)
+- Use `email.policy.EmailPolicy` for consistent encoding, line length, and header handling
+- Modernize attachment handling with `EmailMessage.add_attachment()` instead of manual MIME construction
+- Remove manual `Charset` manipulation - let policy handle it automatically
+- Replace `email.header.Header` usage with policy-based approach
+- Maintain all existing security features (header injection prevention)
+- Keep public API unchanged - all changes are internal implementation
+
+## Benefits
+
+- Cleaner, more Pythonic code
+- Better Unicode handling out of the box
+- Simpler attachment API
+- Future-proof (actively maintained API)
+- Potentially 100-200 fewer lines of code
+
+## Risks
+
+- Policy may handle edge cases differently than current implementation
+- Must thoroughly test all email features (attachments, alternatives, templates, Unicode)
+- Must ensure header injection prevention is preserved

proposals/plain-file-based-secrets.md

@@ -0,0 +1,60 @@
+# plain: File-Based Secrets Loading
+
+- Extend settings loading to support Docker/Kubernetes file-based secrets pattern
+- Check for `PLAIN_<VAR>_FILE` environment variable pointing to file path
+- Automatically check `/run/secrets/<lowercase_var>` as fallback (Docker convention)
+- Maintain backward compatibility - env vars take precedence over files
+- Strip whitespace/newlines from file contents
+- Use existing type parsing (`_parse_env_value`) for file contents
+- No new dependencies required (Python stdlib only)
+
+## Loading Priority
+
+1. `PLAIN_<VAR>` environment variable (highest - existing behavior)
+2. `PLAIN_<VAR>_FILE` environment variable → read file at path
+3. `/run/secrets/<lowercase_var>` file if exists (Docker/K8s default)
+4. Default value from settings (lowest - existing behavior)
+
+## Benefits
+
+- Docker/Kubernetes native - works with container orchestration secrets
+- PaaS compatible - Railway, Render, Fly.io continue using env vars
+- Secure - files can have restrictive permissions (0400)
+- Industry standard - follows MySQL/Postgres official image patterns
+- Foundation for future secrets manager integration (optional)
+
+## Implementation
+
+Modify `plain/plain/runtime/user_settings.py`:
+
+- Add `_read_secret_file(file_path, setting_name)` helper method
+- Extend `_load_env_settings()` to check file sources after env vars
+- Handle errors gracefully (missing files, permissions, etc.)
+- Add tests for file loading and priority order
+- Update `plain/plain/runtime/README.md` with examples
+
+## Docker Compose Example
+
+```yaml
+services:
+  app:
+    secrets:
+      - secret_key
+    environment:
+      # Optional: explicit file path
+      PLAIN_DATABASE_PASSWORD_FILE: /run/secrets/db_password
+
+secrets:
+  secret_key:
+    file: ./secrets/secret_key.txt
+  db_password:
+    file: ./secrets/db_password.txt
+```
+
+## Edge Cases
+
+- Missing file → skip silently, try next source
+- No read permission → log warning, continue
+- Empty file → valid (empty string)
+- Symlinks → follow them (Docker secrets are symlinks)
+- Type parsing errors → fail with clear message

proposals/plain-flags-toolbar-panel.md

@@ -0,0 +1,8 @@
+# plain-flags: Toolbar Panel
+
+- Add dev toolbar panel showing flags evaluated on current request
+- Display flag name, key, value, and result reason (cached/disabled/targeting_match)
+- Session-based temporary overrides (toggles/inputs based on value type)
+- Badge on toolbar button showing flag count and override indicator
+- No context switching to admin for rapid flag iteration
+- Link to admin interface for permanent changes

proposals/plain-models.md renamed to proposals/plain-models-custom-base-queryset.md

@@ -1,25 +1,25 @@
-# plain-models
+# plain-models: Custom Base QuerySet
 
-## Custom Base QuerySet
-
-- Add `default_queryset()` classmethod to QuerySet that subclasses can override?
+- Add `default_queryset()` classmethod to QuerySet that subclasses can override
 - Replaces functionality lost in Manager/QuerySet merge (commit `bbaee93839`)
 - Common use cases: soft deletes, multi-tenancy, published content, archived records
 - More flexible than filters-only (can use `.select_related()`, `.only()`, etc.)
 - Must preserve `base_queryset` for framework operations (migrations, cascades)
 - Need some way to bypass defaults when needed (naming/approach TBD)
 - Usage example:
-  ```python
-  class SoftDeleteQuerySet(QuerySet["Article"]):
-      @classmethod
-      def default_queryset(cls, model):
-          return super().default_queryset(model).filter(deleted_at__isnull=True)
 
-      def with_deleted(self):
-          # How to get unfiltered queryset? TBD
-          pass
+    ```python
+    class SoftDeleteQuerySet(QuerySet["Article"]):
+        @classmethod
+        def default_queryset(cls, model):
+            return super().default_queryset(model).filter(deleted_at__isnull=True)
+
+        def with_deleted(self):
+            # How to get unfiltered queryset? TBD
+            pass
+
+    class Article(Model):
+        query = SoftDeleteQuerySet()
+    ```
 
-  class Article(Model):
-      query = SoftDeleteQuerySet()
-  ```
 - Implementation details TBD (how to integrate with `from_model()`, avoid duplication, bypass mechanism, etc.)