Hyperclay-Compatible Self-Updating Page

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

Click the fork button in Val.town to create your own copy of this project.

In your Val.town settings, add these environment variables:

• ADMIN_EMAIL - Your email address (required for authentication)
• APP_NAMESPACE - Optional namespace for storage (defaults to "default")

The val is already configured as an HTTP trigger. Just save and it's live at your Val.town URL.

Visit your Val.town URL (e.g., https://yourusername-yourval.web.val.run) - you should see the Hyperclay starter template in read-only mode.

1. Go to /auth/edit (e.g., https://yourusername-yourval.web.val.run/auth/edit)
2. Enter your admin email address
3. Check your email for the magic link
4. Click the magic link to authenticate

After authentication, return to your main URL. You should now see:

• Edit controls and buttons
• Contenteditable areas become editable
• Auto-save functionality (Ctrl+S)
• Access to version history at /versions

Your public URL is now ready to share! Others will see the read-only version while you can edit by authenticating.

• 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 (GET shows form, POST sends magic link)
• GET /auth/verify?token=... - Magic link verification endpoint

• 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 (automatically set for authenticated users)
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

• Custom email authentication system using magic links
• Sessions stored in Val.town blob storage with 30-day expiration
• Hyperclay-compatible cookies (currentResource=app, isAdminOfCurrentResource=true) set automatically for authenticated users
• Sessions auto-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

• Magic link email authentication gates session creation
• Sessions stored securely in blob storage with expiration
• Save endpoint validates active sessions 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 session expiration in the auth system (currently 30 days)
• 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. Magic link not received: Check spam folder, verify email service is working
3. Magic link expired: Links expire after 15 minutes, request a new one
4. Changes not saving: Verify you're authenticated (check browser cookies for session)
5. Version history empty: Versions are only created after first save
6. Edit mode not working: Ensure Hyperclay.js is loading (check browser console)

1. Check browser cookies for session and 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
5. Verify ADMIN_EMAIL environment variable is set correctly

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