StarPunk/docs/projectplan/v1.X.X-indieweb-options.md

StarPunk v1.X.X IndieWeb-Focused Release Options

Created: 2025-11-28 Status: Options for architect review

Based on analysis of current implementation gaps and IndieWeb specifications, here are three genuinely different paths forward for full IndieWeb protocol support.

---

Option A: v1.2.0 "Conversation" - Webmention & Reply Context

Focus: Enable two-way conversations between IndieWeb sites

What's Missing Now:

• Zero Webmention support (no sending, no receiving)
• No reply context display (when replying to others)
• No backlinks/responses display
• No notification system for mentions

What You'll Get:

• Webmention Sending (W3C Webmention spec)
  • Automatic endpoint discovery via HTTP headers/HTML links
  • Send notifications when mentioning/replying to other sites
  • Queue system for reliable delivery with retries
• Webmention Receiving (W3C Webmention spec)
  • Advertise endpoint in HTML and HTTP headers
  • Verify source mentions target
  • Store and display incoming mentions (likes, replies, reposts)
• Reply Context (IndieWeb reply-context spec)
  • Fetch and display content you're replying to
  • Parse microformats2 from source
  • Cache reply contexts locally
• Response Display (facepile pattern)
  • Show likes/reposts as compact avatars
  • Display full replies with author info
  • Separate responses by type

IndieWeb Specs:

• W3C Webmention: https://www.w3.org/TR/webmention/
• Reply-context: https://indieweb.org/reply-context
• Response display: https://indieweb.org/responses
• Facepile: https://indieweb.org/facepile

Completion Criteria:

• Pass webmention.rocks test suite (21 tests)
• Successfully send/receive with 3+ IndieWeb sites
• Display reply contexts with proper h-cite markup
• Show incoming responses grouped by type

User Value: Transform StarPunk from broadcast-only to conversational. Users can reply to other IndieWeb posts and see who's engaging with their content. Creates a decentralized comment system.

Scope: 8-10 weeks

---

Option B: v1.3.0 "Studio" - Complete Micropub Media & Post Types

Focus: Full Micropub spec compliance with rich media and diverse post types

What's Missing Now:

• No media endpoint (can't upload images/audio/video)
• No update/delete via Micropub (create-only)
• No syndication targets
• Only supports notes (no articles, photos, bookmarks, etc.)
• No query support beyond basic config

What You'll Get:

• Micropub Media Endpoint (W3C Micropub spec section 3.7)
  • Accept multipart uploads for images/audio/video
  • Generate URLs for uploaded media
  • Return media URL to client for embedding
  • Basic image resizing/optimization
• Micropub Updates/Deletes (W3C Micropub spec sections 3.3-3.4)
  • Replace/add/delete specific properties
  • Full post deletion support
  • JSON syntax for complex updates
• Post Type Discovery (IndieWeb post-type-discovery)
  • Articles (with titles)
  • Photos (image-centric posts)
  • Bookmarks (link saving)
  • Likes (marking favorites)
  • Reposts (sharing others' content)
  • Audio/Video posts
• Syndication Targets (Micropub syndicate-to)
  • Configure external targets (Mastodon, Twitter bridges)
  • POSSE implementation
  • Return syndication URLs

IndieWeb Specs:

• W3C Micropub (complete): https://www.w3.org/TR/micropub/
• Post Type Discovery: https://indieweb.org/post-type-discovery
• POSSE: https://indieweb.org/POSSE

Completion Criteria:

• Pass micropub.rocks full test suite (not just create)
• Support all major post types with proper templates
• Successfully syndicate to 2+ external services
• Handle media uploads from mobile apps

User Value: Use any Micropub client (Indigenous, Quill, etc.) with full features. Post photos from your phone, save bookmarks, like posts, all through standard clients. Syndicate to social media automatically.

Scope: 10-12 weeks

---

Option C: v1.4.0 "Identity" - Complete Microformats2 & IndieAuth Provider

Focus: Become a full IndieWeb identity provider and improve content markup

What's Missing Now:

• Minimal h-entry markup (missing author, location, syndication)
• No h-card on pages (no author identity)
• No h-feed markup enhancements
• No rel=me verification
• Using external IndieAuth (not self-hosted)
• No authorization endpoint
• No token endpoint

What You'll Get:

• Complete h-entry Microformats2 (microformats2 spec)
  • Author h-card embedded in each post
  • Location (p-location with h-geo/h-adr)
  • Syndication links (u-syndication)
  • In-reply-to markup (u-in-reply-to)
  • Categories/tags (p-category)
• Author h-card (microformats2 h-card)
  • Full profile page with h-card
  • Representative h-card on homepage
  • Contact info, bio, social links
  • rel=me links for verification
• Enhanced h-feed (microformats2 h-feed)
  • Feed name and author
  • Pagination with rel=prev/next
  • Feed photo/summary
• IndieAuth Provider (IndieAuth spec)
  • Authorization endpoint (login to other sites with your domain)
  • Token endpoint (issue access tokens)
  • Client registration support
  • Scope management
  • Token revocation interface

IndieWeb Specs:

• Microformats2: http://microformats.org/wiki/microformats2
• h-card: http://microformats.org/wiki/h-card
• h-entry: http://microformats.org/wiki/h-entry
• IndieAuth: https://indieauth.spec.indieweb.org/
• rel=me: https://indieweb.org/rel-me

Completion Criteria:

• Pass IndieWebify.me full validation
• Successfully authenticate to 5+ IndieWeb services
• Parse correctly in all major microformats2 parsers
• Provide IndieAuth to other sites (eat your own dogfood)

User Value: Your site becomes your identity across the web. Log into any IndieWeb service with your domain. Rich markup makes your content parse perfectly everywhere. No dependency on external auth services.

Scope: 6-8 weeks

---

Recommendation Rationale

Each option represents a fundamentally different IndieWeb capability:

• Option A (Conversation): Makes StarPunk social and interactive
• Option B (Studio): Makes StarPunk a complete publishing platform
• Option C (Identity): Makes StarPunk an identity provider

All three are essential for "full IndieWeb support" but focus on different protocols:

• A focuses on Webmention (W3C Recommendation)
• B focuses on Micropub completion (W3C Recommendation)
• C focuses on Microformats2 & IndieAuth (IndieWeb specs)

Current Implementation Gaps Summary

Based on code analysis:

Micropub (starpunk/micropub.py)

✅ Create notes (basic) ✅ Query config ✅ Query source ❌ Media endpoint ❌ Updates (replace/add/delete) ❌ Deletes ❌ Syndication targets ❌ Query for syndicate-to

Microformats (templates)

✅ Basic h-entry (content, published date, URL) ✅ Basic h-feed wrapper ❌ Author h-card ❌ Complete h-entry properties ❌ rel=me links ❌ h-feed metadata

Webmention

❌ No implementation at all

IndieAuth

✅ Client (using indielogin.com) ❌ No provider capability

Post Types

✅ Notes ❌ Articles, photos, bookmarks, likes, reposts, etc.

---

Decision Factors

Consider these when choosing:

1. User Demand: What are users asking for most?
2. Ecosystem Value: Which adds most value to IndieWeb network?
3. Technical Dependencies: Option C (Identity) might benefit A & B
4. Market Differentiation: Which makes StarPunk unique?

All three options are genuinely different approaches to "full IndieWeb support" - the choice depends on priorities.