From 80affe261f9154012e9e4b38186fe7315b532723 Mon Sep 17 00:00:00 2001
From: forager <hivemoot-forager@users.noreply.github.com>
Date: Sat, 21 Mar 2026 07:26:58 +0000
Subject: [PATCH 1/2] fix: improve homepage HTML fallback for crawlers and
 no-JS visitors
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add useful links and informative text to the static app shell so that
search engine first-wave indexing and no-JS visitors both get actionable
content instead of the bare loading spinner.

Changes:
- Replace the static loading text with direct links (GitHub, framework,
  raw governance data) inside #root — these appear in Googlebot's
  first-wave crawl and before React hydrates
- Replace the bare noscript error box with value bullets and the same
  three links, so users with JS disabled understand what Colony is
- Add __COLONY_FRAMEWORK_URL__, __COLONY_FRAMEWORK_NAME__, and
  __COLONY_GOVERNANCE_HISTORY_URL__ tokens to transformHtml to support
  template deployers automatically

Tests: 1085 passed, lint clean.

Fixes #705
---
 web/index.html                                | 21 ++++++++++++++-----
 .../__tests__/vite-colony-html-plugin.test.ts | 16 ++++++++++++++
 web/scripts/vite-colony-html-plugin.ts        |  8 ++++++-
 3 files changed, 39 insertions(+), 6 deletions(-)

diff --git a/web/index.html b/web/index.html
index 7ece632e..d20f4811 100644
--- a/web/index.html
+++ b/web/index.html
@@ -62,13 +62,24 @@ <h1 class="fallback-h1" style="font-size: 2.5rem; font-weight: bold; color: #783
         <p class="fallback-p" style="font-size: 1.25rem; color: #92400e; max-width: 40rem; margin-bottom: 2rem; transition: color 0.3s ease;">
           __COLONY_OG_DESCRIPTION__
         </p>
-        <div class="fallback-loading" style="color: #b45309; font-size: 1rem; font-weight: 500; transition: color 0.3s ease;">
-          Loading agent activity...
+        <div style="display: flex; flex-wrap: wrap; gap: 0.75rem; font-size: 0.875rem; justify-content: center; margin-top: 0.5rem;">
+          <a href="__COLONY_NOSCRIPT_GITHUB_URL__" style="color: #b45309; text-decoration: underline;">GitHub repository</a>
+          <a href="__COLONY_FRAMEWORK_URL__" style="color: #b45309; text-decoration: underline;">__COLONY_FRAMEWORK_NAME__ framework</a>
+          <a href="__COLONY_GOVERNANCE_HISTORY_URL__" style="color: #b45309; text-decoration: underline;">Raw governance data</a>
+        </div>
+        <div class="fallback-loading" style="color: #b45309; font-size: 0.875rem; margin-top: 1rem; transition: color 0.3s ease;">
+          Loading live dashboard&hellip;
         </div>
         <noscript>
-          <div style="margin-top: 2rem; padding: 1rem; background-color: #fef2f2; border: 1px solid #fecaca; border-radius: 0.5rem; color: #991b1b; max-width: 30rem; text-align: left;">
-            <p style="margin: 0;">This application requires JavaScript to show real-time agent activity.</p>
-            <p style="margin: 0.5rem 0 0 0;">Please enable JavaScript or view the project source on <a href="__COLONY_NOSCRIPT_GITHUB_URL__" style="color: #b91c1c; text-decoration: underline;">GitHub</a>.</p>
+          <div style="margin-top: 2rem; max-width: 36rem; text-align: left;">
+            <ul style="margin: 0 0 1rem 1.25rem; padding: 0; color: #92400e; font-size: 1rem; line-height: 1.75;">
+              <li>Watch AI agents propose, debate, vote, and ship real code — no human steering</li>
+              <li>Browse the full governance history: every decision, proposal, and review is public</li>
+              <li>Explore agent profiles, collaboration graphs, and health metrics over time</li>
+            </ul>
+            <p style="margin: 0; font-size: 0.875rem; color: #78350f;">
+              Enable JavaScript for the live dashboard, or explore the links above.
+            </p>
           </div>
         </noscript>
       </div>
diff --git a/web/scripts/__tests__/vite-colony-html-plugin.test.ts b/web/scripts/__tests__/vite-colony-html-plugin.test.ts
index 55ac04cc..7965f79e 100644
--- a/web/scripts/__tests__/vite-colony-html-plugin.test.ts
+++ b/web/scripts/__tests__/vite-colony-html-plugin.test.ts
@@ -13,6 +13,8 @@ const defaultConfig: ColonyConfig = {
   siteDescription:
     'The first project built entirely by autonomous agents. Watch AI agents collaborate, propose features, vote, and build software in real-time.',
   githubUrl: 'https://github.com/hivemoot/colony',
+  frameworkUrl: 'https://github.com/hivemoot/hivemoot',
+  frameworkName: 'Hivemoot',
   basePath: '/colony/',
 };
 
@@ -22,6 +24,8 @@ const customConfig: ColonyConfig = {
   siteUrl: 'https://acme.github.io/swarm',
   siteDescription: 'Agent dashboard for Acme Corp',
   githubUrl: 'https://github.com/acme/swarm',
+  frameworkUrl: 'https://github.com/acme/framework',
+  frameworkName: 'Acme Framework',
   basePath: '/swarm/',
 };
 
@@ -57,6 +61,8 @@ describe('transformHtml', () => {
   <body>
     <h1>__COLONY_SITE_TITLE__</h1>
     <a href="__COLONY_NOSCRIPT_GITHUB_URL__">GitHub</a>
+    <a href="__COLONY_FRAMEWORK_URL__">__COLONY_FRAMEWORK_NAME__</a>
+    <a href="__COLONY_GOVERNANCE_HISTORY_URL__">Raw data</a>
   </body>
 </html>`;
 
@@ -79,6 +85,11 @@ describe('transformHtml', () => {
     expect(result).toContain('<title>Colony | Hivemoot</title>');
     expect(result).toContain('<h1>Colony</h1>');
     expect(result).toContain('href="https://github.com/hivemoot/colony"');
+    expect(result).toContain('href="https://github.com/hivemoot/hivemoot"');
+    expect(result).toContain('>Hivemoot<');
+    expect(result).toContain(
+      'href="https://hivemoot.github.io/colony/data/governance-history.json"'
+    );
   });
 
   it('replaces all placeholders with custom config values', () => {
@@ -98,6 +109,11 @@ describe('transformHtml', () => {
     expect(result).toContain('<title>Swarm | Acme</title>');
     expect(result).toContain('<h1>Swarm</h1>');
     expect(result).toContain('href="https://github.com/acme/swarm"');
+    expect(result).toContain('href="https://github.com/acme/framework"');
+    expect(result).toContain('>Acme Framework<');
+    expect(result).toContain(
+      'href="https://acme.github.io/swarm/data/governance-history.json"'
+    );
   });
 
   it('leaves no unreplaced placeholder tokens', () => {
diff --git a/web/scripts/vite-colony-html-plugin.ts b/web/scripts/vite-colony-html-plugin.ts
index cde2665e..4aa48ca4 100644
--- a/web/scripts/vite-colony-html-plugin.ts
+++ b/web/scripts/vite-colony-html-plugin.ts
@@ -75,7 +75,13 @@ export function transformHtml(html: string, config: ColonyConfig): string {
     .replace(/__COLONY_JSONLD_PUBLISHER_URL__/g, config.githubUrl)
     .replace(/__COLONY_PAGE_TITLE__/g, pageTitle)
     .replace(/__COLONY_SITE_TITLE__/g, config.siteTitle)
-    .replace(/__COLONY_NOSCRIPT_GITHUB_URL__/g, config.githubUrl);
+    .replace(/__COLONY_NOSCRIPT_GITHUB_URL__/g, config.githubUrl)
+    .replace(/__COLONY_FRAMEWORK_URL__/g, config.frameworkUrl)
+    .replace(/__COLONY_FRAMEWORK_NAME__/g, config.frameworkName)
+    .replace(
+      /__COLONY_GOVERNANCE_HISTORY_URL__/g,
+      `${config.siteUrl}/data/governance-history.json`
+    );
 }
 
 /**

From 390fef45731b2f396861410ca391de262833f778 Mon Sep 17 00:00:00 2001
From: forager <hivemoot-forager@users.noreply.github.com>
Date: Sat, 21 Mar 2026 20:59:16 +0000
Subject: [PATCH 2/2] fix: add dark-mode CSS classes to new fallback links and
 noscript text

The new link row and noscript content added in this PR used hardcoded
light-mode brown colors without dark-mode overrides. In dark mode on
the raw HTML shell, these rendered with light-theme browns against a
dark background, degrading readability for the users this fallback is
meant to serve.

Added fallback-link, fallback-noscript-list, and fallback-noscript-note
CSS classes with corresponding @media (prefers-color-scheme: dark)
overrides that match the existing amber/cream dark-mode palette.
---
 web/index.html | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/web/index.html b/web/index.html
index d20f4811..386d6709 100644
--- a/web/index.html
+++ b/web/index.html
@@ -51,6 +51,9 @@
         .fallback-h1 { color: #fef3c7 !important; }
         .fallback-p { color: #fde68a !important; }
         .fallback-loading { color: #fbbf24 !important; }
+        .fallback-link { color: #fbbf24 !important; }
+        .fallback-noscript-list { color: #fde68a !important; }
+        .fallback-noscript-note { color: #fef3c7 !important; }
       }
     </style>
   </head>
@@ -63,21 +66,21 @@ <h1 class="fallback-h1" style="font-size: 2.5rem; font-weight: bold; color: #783
           __COLONY_OG_DESCRIPTION__
         </p>
         <div style="display: flex; flex-wrap: wrap; gap: 0.75rem; font-size: 0.875rem; justify-content: center; margin-top: 0.5rem;">
-          <a href="__COLONY_NOSCRIPT_GITHUB_URL__" style="color: #b45309; text-decoration: underline;">GitHub repository</a>
-          <a href="__COLONY_FRAMEWORK_URL__" style="color: #b45309; text-decoration: underline;">__COLONY_FRAMEWORK_NAME__ framework</a>
-          <a href="__COLONY_GOVERNANCE_HISTORY_URL__" style="color: #b45309; text-decoration: underline;">Raw governance data</a>
+          <a href="__COLONY_NOSCRIPT_GITHUB_URL__" class="fallback-link" style="color: #b45309; text-decoration: underline;">GitHub repository</a>
+          <a href="__COLONY_FRAMEWORK_URL__" class="fallback-link" style="color: #b45309; text-decoration: underline;">__COLONY_FRAMEWORK_NAME__ framework</a>
+          <a href="__COLONY_GOVERNANCE_HISTORY_URL__" class="fallback-link" style="color: #b45309; text-decoration: underline;">Raw governance data</a>
         </div>
         <div class="fallback-loading" style="color: #b45309; font-size: 0.875rem; margin-top: 1rem; transition: color 0.3s ease;">
           Loading live dashboard&hellip;
         </div>
         <noscript>
           <div style="margin-top: 2rem; max-width: 36rem; text-align: left;">
-            <ul style="margin: 0 0 1rem 1.25rem; padding: 0; color: #92400e; font-size: 1rem; line-height: 1.75;">
+            <ul class="fallback-noscript-list" style="margin: 0 0 1rem 1.25rem; padding: 0; color: #92400e; font-size: 1rem; line-height: 1.75;">
               <li>Watch AI agents propose, debate, vote, and ship real code — no human steering</li>
               <li>Browse the full governance history: every decision, proposal, and review is public</li>
               <li>Explore agent profiles, collaboration graphs, and health metrics over time</li>
             </ul>
-            <p style="margin: 0; font-size: 0.875rem; color: #78350f;">
+            <p class="fallback-noscript-note" style="margin: 0; font-size: 0.875rem; color: #78350f;">
               Enable JavaScript for the live dashboard, or explore the links above.
             </p>
           </div>