A simple, elegant implementation of a self-updating HTML page with email authentication, built for Val.town and fully compatible with Hyperclay.js.

• Email Authentication: Secure admin access via magic links
• Hyperclay Integration: Full compatibility with Hyperclay.js editing features
• Version History: Automatic versioning of all changes with viewing capability
• Simple Architecture: Single file implementation, easy to understand and modify
• Persistent Storage: Uses Val.town blob storage for reliability
• Namespace Support: Environment-configurable for multiple deployments

Set these in your Val.town environment:

• ADMIN_EMAIL: The email address that can authenticate for edit access (required)
• APP_NAMESPACE: Namespace for storage keys, allows multiple deployments (optional, defaults to "default")

• GET / - Serves the HTML document
• GET/POST /auth/view - Switches to view mode (clears admin cookies)

• GET/POST /auth/edit - Email auth flow, sets admin cookies on success

• POST /save/app - Saves HTML content (used by Hyperclay.js)
• GET /versions - View version history of all saved documents

1. Visit your Val.town URL
2. See content in read-only mode
3. No edit controls visible (handled by Hyperclay.js)

1. Visit /auth/edit
2. Enter your email (must match ADMIN_EMAIL)
3. Check email for magic link
4. Click link → authenticated and redirected to main page
5. Edit controls now visible and functional

1. After authentication, visit main URL
2. Hyperclay.js detects admin cookies
3. Content becomes editable with edit-mode-* attributes
4. Changes auto-save via Ctrl+S or periodic saves
5. Visit /versions to see change history

• Uses @pomdtr/email_auth for secure magic link authentication
• Sets Hyperclay-compatible cookies (currentResource=app, isAdminOfCurrentResource=true)
• Cookies expire after 30 days but extend on activity

• Main document stored as {namespace}_app
• Versions stored as {namespace}_app_version_{number}
• Version counter stored as {namespace}_app_version_count
• All storage uses Val.town blob storage for persistence

• Loads Hyperclay.js from CDN (always latest version)
• Follows standard Hyperclay patterns for edit mode detection
• Supports all edit-mode-* attributes (contenteditable, show, onclick, etc.)
• Auto-save posts to /save/app endpoint

• Email authentication gates admin cookie setting
• Save endpoint validates admin cookies before accepting changes
• No secrets exposed in client-side code
• Version history only accessible to authenticated admins

The system starts with a Hyperclay starter template that includes:

• Tailwind CSS integration
• Hyperclay.js starter kit
• Template selection interface
• Dark theme styling
• Responsive design

1. Set your ADMIN_EMAIL environment variable
2. Deploy to Val.town
3. Visit your Val.town URL to see public view
4. Visit /auth/edit to test authentication flow
5. Make edits and verify auto-save functionality
6. Check /versions to see version history

• Modify DEFAULT_HTML to change the starting template
• Adjust cookie expiration in editAuthHandler
• Add additional validation in saveHTML if needed
• Extend version history with metadata (timestamps, etc.)

• Single file implementation
• No database setup required
• Minimal configuration (just email)
• Standard Hyperclay patterns

• Persistent blob storage
• Automatic version history
• Comprehensive error handling
• Graceful degradation

• Email-based authentication
• Cookie-based session management
• No client-side secrets
• Protected admin endpoints

1. Can't authenticate: Check ADMIN_EMAIL environment variable matches exactly
2. Changes not saving: Verify admin cookies are set (check browser dev tools)
3. Version history empty: Versions are only created after first save
4. Edit mode not working: Ensure Hyperclay.js is loading (check browser console)

1. Check browser cookies for isAdminOfCurrentResource=true
2. Verify network requests to /save/app are successful
3. Test authentication flow by visiting /auth/edit
4. Check Val.town logs for server-side errors

This implementation provides a robust, secure, and user-friendly self-updating page system that integrates seamlessly with Hyperclay.js while maintaining simplicity and elegance.