@sprig-and-prose/sprig-ui-csr 0.1.0

package/src/lib/components/Prose.svelte

@@ -0,0 +1,260 @@
+<script>
+  import { describeRenderMode } from '../stores/describeRenderMode.js';
+
+  /** @type {import('../data/universeStore.js').TextBlock | { raw?:string, normalized?:string } | undefined} */
+  export let textBlock;
+
+  /**
+   * Parse text into paragraphs (plain mode)
+   */
+  const toParagraphs = (s) => {
+    if (!s) return [];
+    // Split on blank lines; preserve paragraphs.
+    const parts = s.split(/\n\s*\n/g);
+    return parts.map((p) =>
+      p
+        .split('\n')          // soft breaks
+        .map((x) => x.trim())
+        .filter(Boolean)
+        .join(' ')
+    ).filter(Boolean);
+  };
+
+  /**
+   * Parse text into structured blocks (lists mode)
+   * Returns array of { type: 'paragraph' | 'unordered-list' | 'ordered-list', content: string | string[] }
+   */
+  const parseMarkdownLite = (s) => {
+    if (!s) return [];
+    
+    // Split by blank lines to get blocks
+    const blocks = s.split(/\n\s*\n/g).filter(block => block.trim());
+    const result = [];
+    
+    const unorderedPattern = /^[-—*]\s+/;
+    const orderedPattern = /^\d+\.\s+/;
+    
+    for (const block of blocks) {
+      const lines = block.split('\n').map(line => line.trim()).filter(Boolean);
+      if (lines.length === 0) continue;
+      
+      // Find where list items start (if any)
+      let unorderedStart = -1;
+      let orderedStart = -1;
+      
+      for (let i = 0; i < lines.length; i++) {
+        if (unorderedStart === -1 && unorderedPattern.test(lines[i])) {
+          unorderedStart = i;
+        }
+        if (orderedStart === -1 && orderedPattern.test(lines[i])) {
+          orderedStart = i;
+        }
+      }
+      
+      // Handle unordered list
+      if (unorderedStart >= 0 && (orderedStart === -1 || unorderedStart < orderedStart)) {
+        // Extract leading paragraph text (if any)
+        if (unorderedStart > 0) {
+          const leadingText = lines.slice(0, unorderedStart).join(' ');
+          if (leadingText.trim()) {
+            result.push({ type: 'paragraph', content: leadingText });
+          }
+        }
+        
+        // Extract list items (from first list item to end of block, or until non-list item)
+        const listItems = [];
+        let currentItem = null;
+        for (let i = unorderedStart; i < lines.length; i++) {
+          if (unorderedPattern.test(lines[i])) {
+            // If we have a current item, save it before starting a new one
+            if (currentItem !== null) {
+              listItems.push(currentItem);
+            }
+            const match = lines[i].match(/^[-—*]\s+(.+)$/);
+            currentItem = match[1];
+          } else {
+            // Continuation line - append to current item
+            if (currentItem !== null) {
+              currentItem += ' ' + lines[i];
+            } else {
+              // Stop at first non-list item if we haven't started a list yet
+              break;
+            }
+          }
+        }
+        // Don't forget the last item
+        if (currentItem !== null) {
+          listItems.push(currentItem);
+        }
+        
+        if (listItems.length > 0) {
+          result.push({ type: 'unordered-list', content: listItems });
+        }
+        continue;
+      }
+      
+      // Handle ordered list
+      if (orderedStart >= 0) {
+        // Extract leading paragraph text (if any)
+        if (orderedStart > 0) {
+          const leadingText = lines.slice(0, orderedStart).join(' ');
+          if (leadingText.trim()) {
+            result.push({ type: 'paragraph', content: leadingText });
+          }
+        }
+        
+        // Extract list items
+        const listItems = [];
+        let currentItem = null;
+        for (let i = orderedStart; i < lines.length; i++) {
+          if (orderedPattern.test(lines[i])) {
+            // If we have a current item, save it before starting a new one
+            if (currentItem !== null) {
+              listItems.push(currentItem);
+            }
+            const match = lines[i].match(/^\d+\.\s+(.+)$/);
+            currentItem = match[1];
+          } else {
+            // Continuation line - append to current item
+            if (currentItem !== null) {
+              currentItem += ' ' + lines[i];
+            } else {
+              // Stop at first non-list item if we haven't started a list yet
+              break;
+            }
+          }
+        }
+        // Don't forget the last item
+        if (currentItem !== null) {
+          listItems.push(currentItem);
+        }
+        
+        if (listItems.length > 0) {
+          result.push({ type: 'ordered-list', content: listItems });
+        }
+        continue;
+      }
+      
+      // Otherwise, treat as paragraph (preserve literal text)
+      const paragraphText = lines.join(' ');
+      result.push({ type: 'paragraph', content: paragraphText });
+    }
+    
+    return result;
+  };
+
+  $: text = textBlock?.normalized ?? textBlock?.raw ?? '';
+  $: mode = $describeRenderMode;
+  $: paragraphs = mode === 'plain' ? toParagraphs(text) : null;
+  $: blocks = mode === 'lists' ? parseMarkdownLite(text) : null;
+</script>
+
+{#if mode === 'plain'}
+  {#if paragraphs && paragraphs.length}
+    <div class="prose sp-prose">
+      {#each paragraphs as p}
+        <p>{p}</p>
+      {/each}
+    </div>
+  {:else}
+    <div class="empty">No description yet.</div>
+  {/if}
+{:else if mode === 'lists'}
+  {#if blocks && blocks.length}
+    <div class="prose sp-prose">
+      {#each blocks as block}
+        {#if block.type === 'paragraph'}
+          <p>{block.content}</p>
+        {:else if block.type === 'unordered-list'}
+          <ul>
+            {#each block.content as item}
+              <li>{item}</li>
+            {/each}
+          </ul>
+        {:else if block.type === 'ordered-list'}
+          <ol>
+            {#each block.content as item}
+              <li>{item}</li>
+            {/each}
+          </ol>
+        {/if}
+      {/each}
+    </div>
+  {:else}
+    <div class="empty">No description yet.</div>
+  {/if}
+{/if}
+
+<style>
+  .prose {
+    max-width: 70ch;
+    font-size: var(--sp-font-body);
+    line-height: var(--sp-line-body);
+  }
+
+  p {
+    font-size: var(--sp-font-body);
+    line-height: var(--sp-line-body);
+    margin-bottom: var(--sp-space-4);
+    color: var(--text-color);
+  }
+
+  p:last-child {
+    margin-bottom: 0;
+  }
+
+  ul {
+    list-style: none;
+    padding-left: 0;
+    margin-bottom: var(--sp-space-6);
+  }
+
+  ul li {
+    font-size: var(--sp-font-body);
+    line-height: var(--sp-line-loose);
+    color: var(--text-secondary);
+    margin-bottom: var(--sp-space-3);
+    padding-left: var(--sp-space-6);
+    position: relative;
+  }
+
+  ul li::before {
+    content: '—';
+    position: absolute;
+    left: 0;
+    color: var(--text-tertiary);
+  }
+
+  ul li:last-child {
+    margin-bottom: 0;
+  }
+
+  ol {
+    margin-bottom: var(--sp-space-6);
+    padding-left: var(--sp-space-6);
+  }
+
+  ol li {
+    font-size: var(--sp-font-body);
+    line-height: var(--sp-line-body);
+    margin-bottom: var(--sp-space-3);
+    color: var(--text-color);
+  }
+
+  ol li:last-child {
+    margin-bottom: 0;
+  }
+
+  .empty {
+    color: var(--text-tertiary);
+    font-size: var(--sp-font-small);
+    padding: 10px 0;
+  }
+
+  @media (max-width: 480px) {
+    ul li {
+      padding-left: 20px;
+    }
+  }
+</style>
+

package/src/lib/components/UniverseHeader.svelte

@@ -0,0 +1,20 @@
+<script>
+  import PageHeader from './PageHeader.svelte';
+  import { getDisplayTitle } from '../format/title.js';
+
+  /** @type {{ node: any }} */
+  export let node;
+
+  const firstSentence = (s) => {
+    if (!s) return '';
+    const idx = s.indexOf('.');
+    return idx >= 0 ? s.slice(0, idx + 1) : s;
+  };
+
+  $: subtitle = node.describe?.normalized || node.describe?.raw
+    ? firstSentence(node.describe?.normalized ?? node.describe?.raw)
+    : null;
+</script>
+
+<PageHeader title={getDisplayTitle(node)} {subtitle} />
+

package/src/lib/data/universeStore.js

@@ -0,0 +1,252 @@
+import { writable, derived } from 'svelte/store';
+
+/**
+ * @typedef {{ line:number, col:number, offset:number }} Pos
+ * @typedef {{ file:string, start:Pos, end:Pos }} SourceSpan
+ * @typedef {{ raw:string, normalized?:string, source:SourceSpan }} TextBlock
+ * @typedef {{ repository:string, paths:string[], describe?:TextBlock, source:SourceSpan }} ReferenceBlock
+ * @typedef {{ id:string, kind:'universe'|'anthology'|'series'|'book'|'chapter'|'concept'|'relates', name:string, title?:string, parent?:string, children:string[], container?:string, describe?:TextBlock, endpoints?:string[], from?:Record<string, any>, references?:ReferenceBlock[] }} NodeModel
+ * @typedef {{ name:string, root:string }} UniverseModel
+ * @typedef {{ version:1, universes:Record<string, UniverseModel>, nodes:Record<string, NodeModel>, edges:Record<string, any>, diagnostics:any[], repositories?:Record<string, any>, generatedAt?:string }} UniverseGraph
+ */
+
+export const universeGraph = writable(/** @type {UniverseGraph|null} */ (null));
+
+export const currentUniverseName = writable('Amaranthine');
+
+export const currentUniverse = derived(
+  [universeGraph, currentUniverseName],
+  ([$g, $name]) => $g?.universes?.[$name] ?? null,
+);
+
+export const universeRootNode = derived(
+  [universeGraph, currentUniverse],
+  ([$g, $u]) => ($u && $g ? $g.nodes[$u.root] : null),
+);
+
+export const rootChildren = derived(
+  [universeGraph, universeRootNode],
+  ([$g, $root]) => {
+    if (!$g || !$root) return [];
+    return ($root.children || [])
+      .map((id) => $g.nodes[id])
+      .filter(Boolean)
+      .filter((node) => node.kind !== 'relates'); // Exclude relates nodes from contents
+  },
+);
+
+export const rootAnthologies = derived(
+  [universeGraph, universeRootNode],
+  ([$g, $root]) => {
+    if (!$g || !$root) return [];
+    return ($root.children || [])
+      .map((id) => $g.nodes[id])
+      .filter(Boolean)
+      .filter((node) => node.kind === 'anthology');
+  },
+);
+
+export const rootUngroupedSeries = derived(
+  [universeGraph, universeRootNode],
+  ([$g, $root]) => {
+    if (!$g || !$root) return [];
+    const allSeries = ($root.children || [])
+      .map((id) => $g.nodes[id])
+      .filter(Boolean)
+      .filter((node) => node.kind === 'series');
+    
+    // Filter out series that have an anthology parent
+    return allSeries.filter((series) => {
+      if (!series.parent) return true;
+      const parent = $g.nodes[series.parent];
+      return !parent || parent.kind !== 'anthology';
+    });
+  },
+);
+
+export const currentSeriesId = writable(/** @type {string|null} */ (null));
+
+export const currentSeries = derived(
+  [universeGraph, currentSeriesId],
+  ([$g, $seriesId]) => ($g && $seriesId ? $g.nodes[$seriesId] : null),
+);
+
+export const seriesChildren = derived(
+  [universeGraph, currentSeries],
+  ([$g, $series]) => {
+    if (!$g || !$series) return [];
+    return ($series.children || []).map((id) => $g.nodes[id]).filter(Boolean);
+  },
+);
+
+export const currentAnthologyId = writable(/** @type {string|null} */ (null));
+
+export const currentAnthology = derived(
+  [universeGraph, currentAnthologyId],
+  ([$g, $anthologyId]) => ($g && $anthologyId ? $g.nodes[$anthologyId] : null),
+);
+
+export const anthologySeries = derived(
+  [universeGraph, currentAnthology],
+  ([$g, $anthology]) => {
+    if (!$g || !$anthology) return [];
+    return ($anthology.children || [])
+      .map((id) => $g.nodes[id])
+      .filter(Boolean)
+      .filter((node) => node.kind === 'series');
+  },
+);
+
+/**
+ * Get contextual relationships for a node
+ * @param {UniverseGraph | null} graph
+ * @param {string | null} currentNodeId
+ * @returns {Array<{ relNode: any, otherNode: any, label: string, desc: string | null }>}
+ */
+export function getRelationshipsForNode(graph, currentNodeId) {
+  if (!graph || !currentNodeId) return [];
+
+  const relates = Object.values(graph.nodes).filter(
+    (n) => n.kind === 'relates',
+  );
+  const relationships = [];
+
+  for (const relNode of relates) {
+    if (!relNode.endpoints || !Array.isArray(relNode.endpoints)) continue;
+
+    // Check if current node is actually an endpoint of this relationship
+    if (!relNode.endpoints.includes(currentNodeId)) continue;
+
+    // Find the other endpoint (not the current one)
+    const otherId = relNode.endpoints.find((id) => id !== currentNodeId);
+    if (!otherId) continue;
+
+    const otherNode = graph.nodes[otherId];
+    if (!otherNode) continue; // Skip if other node not found
+
+    // Compute label
+    let label = 'related to';
+    const fromView = relNode.from?.[currentNodeId];
+    if (fromView?.relationships?.values?.length > 0) {
+      label = fromView.relationships.values[0];
+    }
+
+    // Compute description
+    let desc = null;
+    if (fromView?.describe?.normalized) {
+      desc = fromView.describe.normalized;
+    } else if (relNode.describe?.normalized) {
+      desc = relNode.describe.normalized;
+    }
+
+    relationships.push({
+      relNode,
+      otherNode,
+      label,
+      desc,
+    });
+  }
+
+  // Sort: primary by kind (series, book, chapter, concept), secondary by name
+  const kindOrder = { series: 0, book: 1, chapter: 2, concept: 3 };
+  relationships.sort((a, b) => {
+    const aKindOrder =
+      a.otherNode.kind in kindOrder ? kindOrder[a.otherNode.kind] : 999;
+    const bKindOrder =
+      b.otherNode.kind in kindOrder ? kindOrder[b.otherNode.kind] : 999;
+    if (aKindOrder !== bKindOrder) return aKindOrder - bKindOrder;
+    return a.otherNode.name.localeCompare(b.otherNode.name);
+  });
+
+  return relationships;
+}
+
+export const seriesRelationships = derived(
+  [universeGraph, currentSeriesId],
+  ([$g, $seriesId]) => {
+    return getRelationshipsForNode($g, $seriesId);
+  },
+);
+
+/**
+ * Get ancestor chain for a node (parent → grandparent → ...)
+ * Returns array of ancestor nodes in order from immediate parent to root ancestor
+ * @param {UniverseGraph | null} graph
+ * @param {NodeModel | null} node
+ * @returns {NodeModel[]}
+ */
+export function getAncestorChain(graph, node) {
+  if (!graph || !node || !node.parent) return [];
+  
+  const ancestors = [];
+  let currentParentId = node.parent;
+  
+  while (currentParentId) {
+    const parentNode = graph.nodes[currentParentId];
+    if (!parentNode) break;
+    
+    ancestors.push(parentNode);
+    
+    // Stop at series level (series don't have parents in the hierarchy)
+    if (parentNode.kind === 'series') break;
+    
+    currentParentId = parentNode.parent;
+  }
+  
+  return ancestors;
+}
+
+/**
+ * Generate route for a node based on its kind
+ * @param {any} node
+ * @returns {string}
+ */
+export function getNodeRoute(node) {
+  if (!node || !node.id) return '#';
+
+  const parts = node.id.split(':');
+  if (parts.length < 3) return `#${node.id}`;
+
+  const universe = parts[0];
+  const kind = parts[1];
+  const name = parts[2];
+
+  if (kind === 'series') {
+    return `/universes/${universe}/series/${name}`;
+  }
+
+  if (kind === 'anthology') {
+    return `/universes/${universe}/anthology/${name}`;
+  }
+
+  // For other kinds, use generic concept route with URL-encoded node ID
+  return `/universes/${universe}/concept/${encodeURIComponent(node.id)}`;
+}
+
+/**
+ * Fetch UniverseGraph JSON from a static path.
+ * @param {string} url
+ * @param {typeof fetch} [fetchFn] - Optional fetch function
+ */
+export async function loadUniverseGraph(
+  url = '/api/manifest',
+  fetchFn = fetch,
+) {
+  // Add cache-busting headers to ensure we get fresh data
+  const res = await fetchFn(url, {
+    cache: 'no-store',
+    headers: {
+      'Cache-Control': 'no-cache',
+    },
+  });
+  if (!res.ok) throw new Error(`Failed to load ${url}: ${res.status}`);
+  /** @type {UniverseGraph} */
+  const data = await res.json();
+  universeGraph.set(data);
+  const describeRenderMode = res.headers.get('x-describe-render-mode');
+  return {
+    data,
+    describeRenderMode,
+  };
+}
+

package/src/lib/format/title.js

@@ -0,0 +1,97 @@
+/**
+ * @fileoverview Utility for deriving human-friendly display titles from node identifiers
+ */
+
+/**
+ * Derives a human-friendly display title from a node or identifier string.
+ * 
+ * @param {any} nodeOrId - Node object with optional `title`, `name`, `id`, `slug`, or `identifier` fields, or a string identifier
+ * @param {{}} [options] - Optional configuration (currently unused, reserved for future use)
+ * @returns {string} Human-friendly display title, or empty string if no usable identifier found
+ * 
+ * @example
+ * getDisplayTitle({ title: "Custom Title" }) // "Custom Title"
+ * getDisplayTitle({ name: "CountBasedEffect" }) // "Count Based Effect"
+ * getDisplayTitle({ name: "APIResponse" }) // "API Response"
+ * getDisplayTitle({ name: "effect_type" }) // "Effect Type"
+ * getDisplayTitle("PlayerID") // "Player ID"
+ */
+export function getDisplayTitle(nodeOrId, options = {}) {
+  // Handle explicit title override
+  if (nodeOrId && typeof nodeOrId === 'object' && typeof nodeOrId.title === 'string') {
+    const title = nodeOrId.title.trim();
+    if (title.length > 0) {
+      return title;
+    }
+  }
+
+  // Extract identifier string
+  let identifier = null;
+  
+  if (typeof nodeOrId === 'string') {
+    identifier = nodeOrId;
+  } else if (nodeOrId && typeof nodeOrId === 'object') {
+    // Check in order: name, id, slug, identifier
+    identifier = nodeOrId.name || nodeOrId.id || nodeOrId.slug || nodeOrId.identifier || null;
+  }
+
+  if (!identifier || typeof identifier !== 'string' || identifier.trim().length === 0) {
+    return '';
+  }
+
+  // Derive title from identifier
+  return deriveTitleFromIdentifier(identifier);
+}
+
+/**
+ * Derives a human-friendly title from an identifier string.
+ * Handles PascalCase, camelCase, snake_case, kebab-case, and preserves acronyms.
+ * 
+ * @param {string} identifier - The identifier string to convert
+ * @returns {string} Human-friendly title
+ * 
+ * @private
+ */
+function deriveTitleFromIdentifier(identifier) {
+  // Normalize: replace underscores and hyphens with spaces
+  let normalized = identifier
+    .replace(/[_-]/g, ' ')
+    .trim();
+
+  // Split on case boundaries (PascalCase/camelCase)
+  // This regex finds positions where:
+  // - A lowercase letter is followed by an uppercase letter (camelCase boundary)
+  // - An uppercase letter is followed by an uppercase letter followed by a lowercase letter (PascalCase boundary like "APIResponse")
+  // - A digit is followed by a letter or vice versa
+  normalized = normalized.replace(/([a-z])([A-Z])/g, '$1 $2'); // camelCase: "countBased" -> "count Based"
+  normalized = normalized.replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2'); // PascalCase acronyms: "APIResponse" -> "API Response"
+  normalized = normalized.replace(/([0-9])([A-Za-z])/g, '$1 $2'); // Numbers: "Item2" -> "Item 2"
+  normalized = normalized.replace(/([A-Za-z])([0-9])/g, '$1 $2'); // Numbers: "Item2" -> "Item 2"
+
+  // Split into words and process each
+  const words = normalized
+    .split(/\s+/)
+    .filter(word => word.length > 0)
+    .map(word => {
+      // Detect acronyms: 2+ consecutive uppercase letters
+      // Only preserve as acronym if it's a known common acronym
+      // This handles cases like "APIResponse" -> "API Response" but "SIMPLE" -> "Simple"
+      const isAcronymPattern = word.length >= 2 && word === word.toUpperCase() && /^[A-Z]+$/.test(word);
+      
+      // Common acronyms that should be preserved: API, UUID, ID, HTTP, HTTPS, XML, JSON, etc.
+      const commonAcronyms = ['API', 'UUID', 'ID', 'HTTP', 'HTTPS', 'XML', 'JSON', 'URL', 'URI', 'HTML', 'CSS', 'JS', 'TS', 'AB'];
+      if (isAcronymPattern && commonAcronyms.includes(word)) {
+        // It's a known acronym, preserve as-is
+        return word;
+      }
+      
+      // Title-case the word: first letter uppercase, rest lowercase
+      if (word.length === 0) return word;
+      if (word.length === 1) return word.toUpperCase();
+      return word[0].toUpperCase() + word.slice(1).toLowerCase();
+    });
+
+  // Join words with single spaces and collapse multiple spaces
+  return words.join(' ').replace(/\s+/g, ' ').trim();
+}
+

package/src/lib/references/isWildcardPath.js

@@ -0,0 +1,9 @@
+/**
+ * Checks if a path contains a wildcard pattern
+ * @param {string} path - File path to check
+ * @returns {boolean} - True if path contains '*'
+ */
+export function isWildcardPath(path) {
+  return typeof path === 'string' && path.includes('*');
+}
+

package/src/lib/references/linkForPath.js

@@ -0,0 +1,65 @@
+import { get } from 'svelte/store';
+import { universeGraph } from '../data/universeStore.js';
+import { isWildcardPath } from './isWildcardPath.js';
+
+/**
+ * Builds a URL for a file path in a repository
+ * @param {string} repository - Repository key (e.g., "amaranthine")
+ * @param {string} path - File path (e.g., "/backends/api/src/routers/players.js" or "/data/actions/*.yaml")
+ * @returns {string | null} - Full URL to the file/folder, or null if repository is unconfigured
+ */
+export function linkForPath(repository, path) {
+  const graph = get(universeGraph);
+  if (!graph?.repositories) {
+    return null;
+  }
+
+  const repoConfig = graph.repositories[repository];
+  if (!repoConfig) {
+    return null;
+  }
+
+  const { kind, options } = repoConfig;
+  const defaultBranch = options?.defaultBranch || 'main';
+
+  // Handle GitHub repositories
+  if (kind === 'sprig-repository-github') {
+    // Prefer url if available, otherwise build from owner/repo
+    let baseUrl;
+    if (options?.url) {
+      baseUrl = options.url;
+    } else {
+      const owner = options?.owner;
+      const repo = options?.repo;
+      if (!owner || !repo) {
+        return null;
+      }
+      baseUrl = `https://github.com/${owner}/${repo}`;
+    }
+
+    const normalizedBaseUrl = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+
+    // Ensure path begins with /
+    const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+
+    // Handle wildcard paths - link to folder view
+    if (isWildcardPath(path)) {
+      // Derive folder by taking everything up to the last '/'
+      // e.g., "/data/actions/*.yaml" -> "/data/actions"
+      const lastSlashIndex = normalizedPath.lastIndexOf('/');
+      if (lastSlashIndex > 0) {
+        const folderPath = normalizedPath.slice(0, lastSlashIndex);
+        // Build GitHub tree URL: baseUrl/tree/branch/folder
+        return `${normalizedBaseUrl}/tree/${defaultBranch}${folderPath}`;
+      }
+      // Fallback: if no slash, link to repo root
+      return `${normalizedBaseUrl}/tree/${defaultBranch}`;
+    }
+
+    // Build GitHub blob URL: baseUrl/blob/branch/path
+    return `${normalizedBaseUrl}/blob/${defaultBranch}${normalizedPath}`;
+  }
+
+  return null;
+}
+