Spike: Investigate how members add the webring widget

[AJaccP]

🧠 Context

A webring only works if each member can put a small widget on their own personal site that links onward through the ring — typically previous / random / next, plus a link back to our directory. The widget has to figure out "which member am I?" and compute its neighbors.

Here's how the ring is set up on our side:

• Members are one JSON file each in src/content/webring/, with an inRing boolean (some may be listed in the directory but opt out of the ring).
• ring.json (served at /ring.json — currently a hand-written placeholder, later generated at build) lists the in-ring members as { name, url } in ring order. This is the data a widget would read to compute prev/random/next.
• The site is fully static — no backend, hosted on GitHub Pages.
• Members' personal sites live on their own domains, so the widget runs cross-origin relative to us. It would identify the current site (e.g. by matching location.hostname against ring.json) and fail quietly if the site isn't in the ring.

What's not decided — and what this spike is for — is the actual delivery mechanism: how a member adds that widget to their site given this static, cross-origin, no-backend setup.

🎯 Goal

Decide how the embed should work, and write up a clear recommendation. This is investigation only — you are not shipping the widget here (that's a follow-up build ticket). The single question to answer, with reasoning for our specific setup:

How do members add the webring widget to their site — a script embed? an iframe? both? a copy-paste HTML snippet? a web component? something else?

🛠️ Investigation Plan

Prefer a solution that works with the current setup as-is — ring.json, the inRing / webring schema, and static hosting. If the best approach genuinely requires changing how something is set up now (e.g. the shape or generation of ring.json, or a webring schema field), that's acceptable — but call out the change and the reason for it in the recommendation, so the follow-up build ticket and the owners of the ring data/schema can account for it.

1. Pin down our constraints. Static hosting (no server to render or proxy anything), members on arbitrary third-party domains (cross-origin), ring data at /ring.json, self-identification by hostname, quiet failure when not in the ring. Note the cross-origin angle: a member's page reading our /ring.json is a cross-origin request, so CORS matters.

2. Look at other implementations See how existing webrings implement their embeds — student/CS rings and general ones (waterloo network, waterloo cs, uoft etc.), plus any blog posts / write-ups on building a webring widget. For each, note what it uses (script vs iframe vs static HTML), how it computes prev/random/next, and how a member includes it on their website. You can reference their GitHub repositories for ideas, but not to fully copy.

3. Evaluate the candidate approaches for our case, with tradeoffs. At least:

   • Script embed (<script src=…> + a target element): flexible and styleable, and can read the host page's hostname to self-identify — but it runs our third-party JS on members' sites (trust / CSP concerns) and needs CORS on /ring.json.
   • Iframe embed: isolated and safe (no third-party JS on the host), but the iframe loads our origin, so it can't see the member's hostname (they'd have to pass it in as a param), and styling/sizing/theming is constrained.
   • Both / hybrid: e.g. script as the primary path, iframe as a fallback for hosts that block scripts.
   • Plain copy-paste HTML (hand-written prev/next links): simplest to paste, but the member would maintain their own neighbor links — which breaks as the ring changes. Note why this likely doesn't fit a dynamic ring.
   • Web component / anything else you find in other implementations.

   Weigh each on: contributor ease (non-experts must be able to add it), customization (e.g. recoloring to fit their site), accessibility, whether their widget auto-updates when the ring changes, and failure behavior.

4. Confirm the load-bearing assumptions. Confirm the things the recommendation depends on actually hold — e.g. can a third-party page fetch our static /ring.json cross-origin, does GitHub Pages send permissive CORS headers, can a script read its own origin (from its src) and the host page's hostname? A throwaway local proof-of-concept (two localhost ports to simulate cross-origin) is fine to validate feasibility.

✅ Outcome / Acceptance Criteria

• A clear written recommendation answering how members should add the widget — script / iframe / both / other — and why, grounded in our static, cross-origin, no-backend setup.
• The recommendation weighs the key tradeoffs: third-party JS / CSP, cross-origin & CORS, self-identification by hostname, customization, contributor ease, and quiet failure.
• It references how a few existing webrings do it, with takeaways.
• It includes a rough implementation sketch + next steps the follow-up build ticket can be written from — the chosen approach and the shape of the copy-paste snippet members would use.
• Findings are written up where we can read them (e.g. a PR or comment under the issue).
• If the spike commits any code or a doc, pnpm format:check, pnpm check, and pnpm build still pass.