From 2af0a855821c8af755495a9f8f2023b4dfd9d2c9 Mon Sep 17 00:00:00 2001
From: Tim Bradgate <timbradgate@hotmail.co.uk>
Date: Thu, 14 May 2026 17:22:07 +0100
Subject: [PATCH] Migrate Phase 2 read-only pages to Vue 3 (Home, About, Help)

- stores/help.ts: Pinia port of Vuex help module with manifest loading, document
  cache, and Fuse.js full-text search
- components/MarkdownRenderer.vue: async marked v18 API via watch+ref; :deep() CSS
  selectors; import.meta.env.BASE_URL for portable help links across base paths
- views/HomeView.vue: reads systemStore.currentShow/settings + userStore.currentUser;
  currentShowSession stubbed null until Phase 6
- views/AboutView.vue: static content port
- views/HelpView.vue: BVN port with sticky sidebar, debounced search, dynamic navbar
  height offset
- views/help/HelpDocView.vue: cache-first doc loading, watch route.params.slug
- router: wire /about and /help routes; fix /help child redirect to absolute path;
  fix catch-all to render NotFoundView in-place (no URL redirect) matching Vue 2
  behaviour

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 client-v3/src/components/MarkdownRenderer.vue | 219 ++++++++++++++++++
 client-v3/src/router/index.ts                 |  10 +-
 client-v3/src/stores/help.ts                  | 109 +++++++++
 client-v3/src/views/AboutView.vue             |  17 ++
 client-v3/src/views/HelpView.vue              |  88 +++++++
 client-v3/src/views/HomeView.vue              |  49 ++--
 client-v3/src/views/help/HelpDocView.vue      |  47 ++++
 7 files changed, 516 insertions(+), 23 deletions(-)
 create mode 100644 client-v3/src/components/MarkdownRenderer.vue
 create mode 100644 client-v3/src/stores/help.ts
 create mode 100644 client-v3/src/views/AboutView.vue
 create mode 100644 client-v3/src/views/HelpView.vue
 create mode 100644 client-v3/src/views/help/HelpDocView.vue

diff --git a/client-v3/src/components/MarkdownRenderer.vue b/client-v3/src/components/MarkdownRenderer.vue
new file mode 100644
index 00000000..6be9a16d
--- /dev/null
+++ b/client-v3/src/components/MarkdownRenderer.vue
@@ -0,0 +1,219 @@
+<template>
+  <!-- eslint-disable vue/no-v-html -->
+  <div class="markdown-content" v-html="renderedHtml" />
+  <!-- eslint-enable vue/no-v-html -->
+</template>
+
+<script setup lang="ts">
+import { ref, watch } from 'vue';
+import { marked } from 'marked';
+import DOMPurify from 'dompurify';
+import log from 'loglevel';
+
+const props = defineProps<{ content: string }>();
+
+const renderedHtml = ref('');
+
+watch(
+  () => props.content,
+  async (content) => {
+    if (!content) {
+      renderedHtml.value = '';
+      return;
+    }
+    try {
+      const raw = await marked.parse(content);
+      let html = transformImagePaths(raw);
+      html = transformMarkdownLinks(html);
+      renderedHtml.value = DOMPurify.sanitize(html, {
+        ALLOWED_TAGS: [
+          'h1',
+          'h2',
+          'h3',
+          'h4',
+          'h5',
+          'h6',
+          'p',
+          'a',
+          'ul',
+          'ol',
+          'li',
+          'img',
+          'code',
+          'pre',
+          'strong',
+          'em',
+          'blockquote',
+          'table',
+          'thead',
+          'tbody',
+          'tr',
+          'th',
+          'td',
+          'br',
+          'hr',
+        ],
+        ALLOWED_ATTR: ['href', 'src', 'alt', 'title', 'class'],
+      });
+    } catch (error) {
+      log.error('Error rendering markdown:', error);
+      renderedHtml.value = '<p class="text-danger">Error rendering documentation</p>';
+    }
+  },
+  { immediate: true }
+);
+
+function transformImagePaths(html: string): string {
+  return html
+    .replace(/src="\.\.\/\.\.\/images\//g, 'src="/docs/images/')
+    .replace(/src="\.\.\/images\//g, 'src="/docs/images/');
+}
+
+function transformMarkdownLinks(html: string): string {
+  const base = import.meta.env.BASE_URL;
+  return html
+    .replace(
+      /href="(\.\.\/)*(pages\/[^"]+)\.md"/g,
+      (_match: string, _dots: string, path: string) => {
+        const slug = path.replace(/^pages\//, '').replace(/_/g, '-');
+        return `href="${base}help/${slug}"`;
+      }
+    )
+    .replace(/href="\.\/([^"]+)\.md"/g, (_match: string, path: string) => {
+      const slug = path.replace(/_/g, '-');
+      return `href="${base}help/${slug}"`;
+    });
+}
+</script>
+
+<style scoped>
+.markdown-content {
+  text-align: left;
+  color: #ebebeb;
+  line-height: 1.6;
+}
+
+.markdown-content :deep(h1),
+.markdown-content :deep(h2),
+.markdown-content :deep(h3),
+.markdown-content :deep(h4),
+.markdown-content :deep(h5),
+.markdown-content :deep(h6) {
+  color: #00bc8c;
+  margin-top: 1.5rem;
+  margin-bottom: 1rem;
+  font-weight: 500;
+}
+
+.markdown-content :deep(h1) {
+  font-size: 2.5rem;
+  border-bottom: 1px solid #375a7f;
+  padding-bottom: 0.5rem;
+}
+
+.markdown-content :deep(h2) {
+  font-size: 2rem;
+  border-bottom: 1px solid #375a7f;
+  padding-bottom: 0.3rem;
+}
+
+.markdown-content :deep(h3) {
+  font-size: 1.75rem;
+}
+
+.markdown-content :deep(h4) {
+  font-size: 1.5rem;
+}
+
+.markdown-content :deep(img) {
+  max-width: 100%;
+  height: auto;
+  border-radius: 0.25rem;
+  margin: 1rem 0;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.3);
+}
+
+.markdown-content :deep(a) {
+  color: #00bc8c;
+  text-decoration: none;
+}
+
+.markdown-content :deep(a:hover) {
+  color: #00efb2;
+  text-decoration: underline;
+}
+
+.markdown-content :deep(code) {
+  background-color: #375a7f;
+  color: #ebebeb;
+  padding: 0.2rem 0.4rem;
+  border-radius: 0.25rem;
+  font-family: 'Monaco', 'Menlo', 'Courier New', monospace;
+  font-size: 0.875rem;
+}
+
+.markdown-content :deep(pre) {
+  background-color: #375a7f;
+  color: #ebebeb;
+  padding: 1rem;
+  border-radius: 0.25rem;
+  overflow-x: auto;
+  margin: 1rem 0;
+}
+
+.markdown-content :deep(pre code) {
+  background-color: transparent;
+  padding: 0;
+  font-size: 0.875rem;
+}
+
+.markdown-content :deep(blockquote) {
+  border-left: 4px solid #00bc8c;
+  padding-left: 1rem;
+  margin: 1rem 0;
+  color: #b8b8b8;
+  font-style: italic;
+}
+
+.markdown-content :deep(ul),
+.markdown-content :deep(ol) {
+  margin: 0.5rem 0;
+  padding-left: 2rem;
+}
+
+.markdown-content :deep(li) {
+  margin: 0.25rem 0;
+}
+
+.markdown-content :deep(table) {
+  width: 100%;
+  margin: 1rem 0;
+  border-collapse: collapse;
+}
+
+.markdown-content :deep(th),
+.markdown-content :deep(td) {
+  padding: 0.75rem;
+  border: 1px solid #375a7f;
+}
+
+.markdown-content :deep(th) {
+  background-color: #375a7f;
+  color: #00bc8c;
+  font-weight: 600;
+}
+
+.markdown-content :deep(tr:nth-child(even)) {
+  background-color: rgba(55, 90, 127, 0.3);
+}
+
+.markdown-content :deep(hr) {
+  border: none;
+  border-top: 1px solid #375a7f;
+  margin: 2rem 0;
+}
+
+.markdown-content :deep(p) {
+  margin: 0.75rem 0;
+}
+</style>
diff --git a/client-v3/src/router/index.ts b/client-v3/src/router/index.ts
index e4b2ede1..ca5ec386 100644
--- a/client-v3/src/router/index.ts
+++ b/client-v3/src/router/index.ts
@@ -22,7 +22,7 @@ const router = createRouter({
     {
       path: '/about',
       name: 'about',
-      component: PlaceholderView,
+      component: () => import('@/views/AboutView.vue'),
       meta: { requiresAuth: false },
     },
     {
@@ -124,14 +124,14 @@ const router = createRouter({
     },
     {
       path: '/help',
-      component: PlaceholderView,
+      component: () => import('@/views/HelpView.vue'),
       meta: { requiresAuth: false },
       children: [
-        { path: '', redirect: 'getting-started' },
+        { path: '', redirect: '/help/getting-started' },
         {
           name: 'help-doc',
           path: ':slug(.*)',
-          component: PlaceholderView,
+          component: () => import('@/views/help/HelpDocView.vue'),
           meta: { requiresAuth: false },
         },
       ],
@@ -144,7 +144,7 @@ const router = createRouter({
     },
     {
       path: '/:pathMatch(.*)*',
-      redirect: '/404',
+      component: NotFoundView,
     },
   ],
 });
diff --git a/client-v3/src/stores/help.ts b/client-v3/src/stores/help.ts
new file mode 100644
index 00000000..c76ba219
--- /dev/null
+++ b/client-v3/src/stores/help.ts
@@ -0,0 +1,109 @@
+import log from 'loglevel';
+import Fuse from 'fuse.js';
+import { defineStore } from 'pinia';
+
+interface HelpManifestEntry {
+  title: string;
+  slug: string;
+  path: string;
+  category: string;
+}
+
+interface HelpState {
+  manifest: HelpManifestEntry[];
+  documents: Record<string, string>;
+  currentDocument: string | null;
+  loading: boolean;
+  error: string | null;
+  searchIndex: Fuse<HelpManifestEntry> | null;
+  searchResults: HelpManifestEntry[];
+}
+
+export const useHelpStore = defineStore('help', {
+  state: (): HelpState => ({
+    manifest: [],
+    documents: {},
+    currentDocument: null,
+    loading: false,
+    error: null,
+    searchIndex: null,
+    searchResults: [],
+  }),
+
+  getters: {
+    documentationManifest: (state) => state.manifest,
+    currentDocumentContent: (state) =>
+      state.currentDocument ? state.documents[state.currentDocument] : null,
+    isLoading: (state) => state.loading,
+    searchResults: (state) => state.searchResults,
+  },
+
+  actions: {
+    async loadManifest() {
+      try {
+        const response = await fetch('/docs/manifest.json');
+        if (!response.ok) throw new Error(`HTTP ${response.status}`);
+
+        const manifest: HelpManifestEntry[] = await response.json();
+        this.manifest = manifest;
+        this.searchIndex = new Fuse(manifest, {
+          keys: ['title', 'path'],
+          threshold: 0.3,
+          includeScore: true,
+        });
+        log.info(`Loaded documentation manifest with ${manifest.length} documents`);
+      } catch (error) {
+        log.error('Failed to load documentation manifest:', error);
+        this.error = 'Failed to load documentation manifest';
+      }
+    },
+
+    async loadDocument(slug: string) {
+      if (this.documents[slug]) {
+        this.currentDocument = slug;
+        this.error = null;
+        return;
+      }
+
+      this.loading = true;
+      const doc = this.manifest.find((d) => d.slug === slug);
+
+      if (!doc) {
+        this.error = 'Document not found';
+        this.loading = false;
+        return;
+      }
+
+      try {
+        const response = await fetch(`/docs/${doc.path}`);
+        if (!response.ok) throw new Error(`HTTP ${response.status}`);
+
+        const content = await response.text();
+        this.documents[slug] = content;
+        this.currentDocument = slug;
+        this.error = null;
+      } catch (error) {
+        log.error('Failed to load documentation:', error);
+        this.error = 'Failed to load documentation';
+      } finally {
+        this.loading = false;
+      }
+    },
+
+    searchDocuments(query: string) {
+      if (!this.searchIndex) {
+        log.warn('Search index not initialized');
+        return;
+      }
+      if (!query || query.trim() === '') {
+        this.searchResults = [];
+        return;
+      }
+      this.searchResults = this.searchIndex.search(query).map((r) => r.item);
+    },
+
+    clearSearch() {
+      this.searchResults = [];
+    },
+  },
+});
diff --git a/client-v3/src/views/AboutView.vue b/client-v3/src/views/AboutView.vue
new file mode 100644
index 00000000..6d38acfc
--- /dev/null
+++ b/client-v3/src/views/AboutView.vue
@@ -0,0 +1,17 @@
+<template>
+  <div class="about">
+    <h1>About DigiScript</h1>
+    <p>A digital script resource for queueing shows, produced by the Dream Team</p>
+    <p>The dream team is</p>
+    <ul style="list-style: none">
+      <li>Tim Bradgate</li>
+      <li>Jack Pollock</li>
+      <li>Matthew Stratford</li>
+      <li>Matthew Gaynor</li>
+    </ul>
+  </div>
+</template>
+
+<script setup lang="ts">
+// Static content — no store dependencies
+</script>
diff --git a/client-v3/src/views/HelpView.vue b/client-v3/src/views/HelpView.vue
new file mode 100644
index 00000000..84c895a1
--- /dev/null
+++ b/client-v3/src/views/HelpView.vue
@@ -0,0 +1,88 @@
+<template>
+  <div class="help">
+    <h1>DigiScript Documentation</h1>
+    <BContainer class="mx-0 help-container" fluid>
+      <BRow>
+        <BCol cols="2">
+          <div class="sticky-nav" :style="{ top: navbarHeight + 'px' }">
+            <BFormInput
+              v-model="searchQuery"
+              placeholder="Search docs..."
+              class="mb-3"
+              @input="handleSearch"
+            />
+            <BButtonGroup vertical class="w-100">
+              <BButton
+                v-for="doc in displayedDocs"
+                :key="doc.slug"
+                :to="{ name: 'help-doc', params: { slug: doc.slug } }"
+                variant="outline-info"
+                active-class="active"
+              >
+                {{ doc.title }}
+              </BButton>
+            </BButtonGroup>
+          </div>
+        </BCol>
+        <BCol cols="10">
+          <RouterView />
+        </BCol>
+      </BRow>
+    </BContainer>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, computed, onMounted, onBeforeUnmount } from 'vue';
+import { storeToRefs } from 'pinia';
+import { debounce } from 'lodash';
+import { useHelpStore } from '@/stores/help';
+
+const helpStore = useHelpStore();
+const { documentationManifest, searchResults } = storeToRefs(helpStore);
+
+const navbarHeight = ref(0);
+const searchQuery = ref('');
+
+const displayedDocs = computed(() => {
+  if (searchQuery.value && searchResults.value.length > 0) {
+    return searchResults.value;
+  }
+  return documentationManifest.value;
+});
+
+onMounted(async () => {
+  await helpStore.loadManifest();
+  calculateNavbarHeight();
+  window.addEventListener('resize', calculateNavbarHeight);
+});
+
+onBeforeUnmount(() => {
+  window.removeEventListener('resize', calculateNavbarHeight);
+});
+
+function calculateNavbarHeight(): void {
+  const navbar = document.querySelector('.navbar');
+  navbarHeight.value = navbar ? (navbar as HTMLElement).offsetHeight : 56;
+}
+
+const handleSearch = debounce(function () {
+  if (!searchQuery.value || searchQuery.value.trim() === '') {
+    helpStore.clearSearch();
+  } else {
+    helpStore.searchDocuments(searchQuery.value);
+  }
+}, 300);
+</script>
+
+<style scoped>
+.help-container {
+  position: relative;
+}
+
+.sticky-nav {
+  position: sticky;
+  padding: 10px 0;
+  background: var(--body-background);
+}
+</style>
diff --git a/client-v3/src/views/HomeView.vue b/client-v3/src/views/HomeView.vue
index 6f4002a6..9710f7df 100644
--- a/client-v3/src/views/HomeView.vue
+++ b/client-v3/src/views/HomeView.vue
@@ -1,24 +1,37 @@
 <template>
-  <div class="container mt-5">
-    <div class="row justify-content-center">
-      <div class="col-md-8 text-center">
-        <h1 class="display-4 mb-4">DigiScript</h1>
-        <div class="alert alert-info" role="alert">
-          <h4 class="alert-heading">Vue 3 Migration in Progress</h4>
-          <p class="mb-0">
-            This is the new Vue 3 frontend served at <code>/ui-new/</code>. The Vue 2 app remains
-            available at <code>/</code> during migration.
-          </p>
-        </div>
-      </div>
-    </div>
+  <div class="home">
+    <template v-if="settings && (settings as Record<string, unknown>).current_show == null">
+      <h1>DigiScript</h1>
+      <b>No show has been loaded. Please create a new one, or load an existing one.</b>
+    </template>
+    <template v-else>
+      <h1>{{ currentShow?.name }}</h1>
+      <b v-if="currentShowSession == null">
+        <template v-if="isAdminUser">
+          No live session has currently been started. Please start a live session to continue.
+        </template>
+        <template v-else>
+          No live session has currently been started. Please wait for a live session to start.
+        </template>
+      </b>
+      <b v-else> Live session has been started. Join <RouterLink to="/live">here</RouterLink>. </b>
+    </template>
   </div>
 </template>
 
-<script lang="ts">
-import { defineComponent } from 'vue';
+<script setup lang="ts">
+import { computed } from 'vue';
+import { storeToRefs } from 'pinia';
+import { useSystemStore } from '@/stores/system';
+import { useUserStore } from '@/stores/user';
 
-export default defineComponent({
-  name: 'HomeView',
-});
+const systemStore = useSystemStore();
+const userStore = useUserStore();
+
+const { currentShow, settings } = storeToRefs(systemStore);
+
+// Stub until Phase 6 wires in the show store
+const currentShowSession = computed(() => null);
+
+const isAdminUser = computed(() => userStore.currentUser?.is_admin ?? false);
 </script>
diff --git a/client-v3/src/views/help/HelpDocView.vue b/client-v3/src/views/help/HelpDocView.vue
new file mode 100644
index 00000000..6bf9d584
--- /dev/null
+++ b/client-v3/src/views/help/HelpDocView.vue
@@ -0,0 +1,47 @@
+<template>
+  <div class="help-doc">
+    <BSpinner v-if="isLoading" variant="info" style="width: 3rem; height: 3rem" />
+    <BAlert v-else-if="error" variant="danger" :model-value="true">
+      <strong>Error:</strong> {{ error }}
+      <br />
+      <BButton variant="outline-danger" size="sm" class="mt-2" @click="retry"> Retry </BButton>
+    </BAlert>
+    <MarkdownRenderer v-else-if="currentDocumentContent" :content="currentDocumentContent" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { watch } from 'vue';
+import { useRoute } from 'vue-router';
+import { storeToRefs } from 'pinia';
+import { useHelpStore } from '@/stores/help';
+import MarkdownRenderer from '@/components/MarkdownRenderer.vue';
+
+const route = useRoute();
+const helpStore = useHelpStore();
+
+const { currentDocumentContent, isLoading, error } = storeToRefs(helpStore);
+
+watch(
+  () => route.params.slug as string,
+  async (slug) => {
+    if (slug) {
+      if (!helpStore.documentationManifest.length) {
+        await helpStore.loadManifest();
+      }
+      await helpStore.loadDocument(slug);
+    }
+  },
+  { immediate: true }
+);
+
+async function retry() {
+  const slug = route.params.slug as string;
+  if (slug) {
+    if (!helpStore.documentationManifest.length) {
+      await helpStore.loadManifest();
+    }
+    await helpStore.loadDocument(slug);
+  }
+}
+</script>