Add shared and TDA component gallery

content/meta/code-architecture.md

@@ -7,7 +7,7 @@ order: 1
 status: revised
 created: 2026-08-08
 revised: 2026-08-08
-revision: 2
+revision: 3
 tags:
   - meta
 ---
@@ -135,6 +135,14 @@ properties the kit names but does not ship), and the domain components in `src/c
 stylesheet also has to point Tailwind at the package, because source detection does not look inside
 `node_modules`, and the built-output test is what checks it did.
 
+`site/src/pages/gallery/` is the visual acceptance surface for that boundary. It imports every case
+from `@galaxy-foundry/site-kit/specimens` and renders the shared components through this instance's
+theme; package-declared `isolated` and `document` surfaces receive generated standalone routes.
+Local specimen groups place the filtration hero, persistence divider, point-cloud fingerprint,
+topology breadcrumb, and every declared reference kind beside the shared cases without moving
+their domain vocabulary into the package. Built-output tests require complete shared and local
+coverage, every standalone route, the gallery's design-index link, and the intended search policy.
+
 The site is a pure reader. It validates and renders source; it does not mutate content, author
 notes, or cast artifacts. The only client-side code is progressive enhancement — the homepage
 filtration control — and there is no UI framework.
@@ -179,6 +187,7 @@ aspirational or the checkout is broken.
 | companion measurement | `site/src/lib/companions.ts` |
 | presentation registries | `site/src/lib/tags.ts`, `design-records.ts`, `detail-routes.ts` |
 | shell composition and identity | `site/src/layouts/Base.astro`, `site/src/lib/site-identity.ts` |
+| shared and local visual acceptance | `site/src/pages/gallery/`, `site/src/lib/gallery.ts` |
 | domain furniture | `site/src/components/`, `site/src/lib/motifs.ts` |
 | routes | `site/src/pages/` |
 | corpus and contract tests | `site/tests/` |

site/package.json

@@ -26,7 +26,7 @@
     "@galaxy-foundry/kind-schema": "^0.5.1",
     "@galaxy-foundry/license-policy": "^0.4.1",
     "@galaxy-foundry/reference-contract": "^0.4.0",
-    "@galaxy-foundry/site-kit": "^0.9.1",
+    "@galaxy-foundry/site-kit": "^0.9.2",
     "@galaxy-foundry/tag-registry": "^0.1.1",
     "@galaxy-foundry/wiki-links": "^0.4.0",
     "@tailwindcss/vite": "4.3.3",

site/src/components/GallerySpecimen.astro

@@ -0,0 +1,126 @@
+---
+import { specimenPath, type Specimen, type SpecimenGroup } from '@galaxy-foundry/site-kit/specimens';
+
+interface Props {
+  group: SpecimenGroup;
+  specimen: Specimen;
+  origin: 'shared' | 'tda';
+}
+
+const { group, specimen, origin } = Astro.props;
+const anchor = specimenPath(group, specimen).replace('/', '--');
+---
+
+<article
+  id={anchor}
+  class="gallery-specimen"
+  data-gallery-component={group.component}
+  data-gallery-origin={origin}
+>
+  <header class="gallery-specimen-copy">
+    <span>{origin === 'shared' ? 'Shared case' : 'TDA case'}</span>
+    <h3><a href={`#${anchor}`}>{specimen.name}</a></h3>
+    <p>{specimen.why}</p>
+    <code>{specimenPath(group, specimen)}</code>
+  </header>
+  <div class="gallery-specimen-stage bg-grid">
+    <slot />
+  </div>
+</article>
+
+<style>
+  .gallery-specimen {
+    display: grid;
+    grid-template-columns: minmax(12rem, 0.34fr) minmax(0, 1fr);
+    gap: clamp(1.25rem, 4vw, 3.5rem);
+    padding: clamp(1.5rem, 4vw, 3rem) 0;
+    border-top: 1px solid var(--color-border-subtle);
+    scroll-margin-top: 6rem;
+  }
+
+  .gallery-specimen-copy {
+    align-self: start;
+    position: sticky;
+    top: 5.5rem;
+  }
+
+  .gallery-specimen-copy > span {
+    color: var(--color-brand);
+    font-family: var(--font-mono);
+    font-size: 0.66rem;
+    font-weight: 600;
+    letter-spacing: 0.12em;
+    text-transform: uppercase;
+  }
+
+  .gallery-specimen-copy h3 {
+    margin: 0.45rem 0 0.7rem;
+    font-family: var(--font-serif);
+    font-size: clamp(1.35rem, 2.5vw, 1.9rem);
+    font-variation-settings: 'opsz' 28;
+    font-weight: 580;
+    letter-spacing: -0.035em;
+    line-height: 1.08;
+  }
+
+  .gallery-specimen-copy h3 a {
+    color: var(--color-text-primary);
+    text-decoration: none;
+  }
+
+  .gallery-specimen-copy h3 a:hover {
+    color: var(--color-link);
+  }
+
+  .gallery-specimen-copy p {
+    margin: 0;
+    color: var(--color-text-secondary);
+    font-size: 0.9rem;
+    line-height: 1.6;
+    text-wrap: pretty;
+  }
+
+  .gallery-specimen-copy code {
+    display: inline-block;
+    margin-top: 1rem;
+    color: var(--color-text-muted);
+    font-family: var(--font-mono);
+    font-size: 0.67rem;
+  }
+
+  .gallery-specimen-stage {
+    min-width: 0;
+    overflow: hidden;
+    border: 1px solid var(--color-border-subtle);
+    border-radius: 0.8rem 0.8rem 2rem 0.8rem;
+    background-color: var(--color-surface-raised);
+    box-shadow: 0 1.2rem 3.5rem color-mix(in srgb, var(--color-chrome) 8%, transparent);
+    padding: clamp(1rem, 2.5vw, 1.75rem);
+  }
+
+  [data-gallery-component='SiteFooter'] .gallery-specimen-stage,
+  [data-gallery-component='SiteHeader'] .gallery-specimen-stage,
+  [data-gallery-component='SiteShell'] .gallery-specimen-stage,
+  [data-gallery-component='FiltrationHero'] .gallery-specimen-stage {
+    padding: 0;
+  }
+
+  [data-gallery-component='PersistenceDivider'] .gallery-specimen-stage,
+  [data-gallery-component='PointCloudFingerprint'] .gallery-specimen-stage,
+  [data-gallery-component='TopologyBreadcrumb'] .gallery-specimen-stage {
+    display: grid;
+    min-height: 9rem;
+    align-items: center;
+  }
+
+  @media (max-width: 760px) {
+    .gallery-specimen {
+      grid-template-columns: 1fr;
+      gap: 1rem;
+    }
+
+    .gallery-specimen-copy {
+      position: static;
+    }
+  }
+</style>

site/src/layouts/Base.astro

@@ -1,13 +1,5 @@
 ---
-import '@fontsource-variable/ibm-plex-sans/wght.css';
-import '@fontsource-variable/ibm-plex-sans/wght-italic.css';
-import '@fontsource-variable/source-serif-4/opsz.css';
-import '@fontsource-variable/source-serif-4/opsz-italic.css';
-import '@fontsource/ibm-plex-mono/latin-400.css';
-import '@fontsource/ibm-plex-mono/latin-500.css';
-import '@fontsource/ibm-plex-mono/latin-600.css';
-import '@fontsource/ibm-plex-mono/latin-700.css';
-import '../styles/global.css';
+import '../styles/site-theme';
 import SiteShell from '@galaxy-foundry/site-kit/SiteShell.astro';
 
 import { base } from '../lib/site-base';

site/src/lib/gallery-renderers.ts

@@ -0,0 +1,37 @@
+import ContentNote from '@galaxy-foundry/site-kit/ContentNote.astro';
+import LicenseBadge from '@galaxy-foundry/site-kit/LicenseBadge.astro';
+import LicenseFileBody from '@galaxy-foundry/site-kit/LicenseFileBody.astro';
+import ReferenceContract from '@galaxy-foundry/site-kit/ReferenceContract.astro';
+import SiteFooter from '@galaxy-foundry/site-kit/SiteFooter.astro';
+import SiteHeader from '@galaxy-foundry/site-kit/SiteHeader.astro';
+import SiteShell from '@galaxy-foundry/site-kit/SiteShell.astro';
+import TagChips from '@galaxy-foundry/site-kit/TagChips.astro';
+import type { AstroComponentFactory } from 'astro/runtime/server/index.js';
+
+import FiltrationHero from '../components/FiltrationHero.astro';
+import PersistenceDivider from '../components/PersistenceDivider.astro';
+import PointCloudFingerprint from '../components/PointCloudFingerprint.astro';
+import TopologyBreadcrumb from '../components/TopologyBreadcrumb.astro';
+import { ALL_SPECIMENS } from './gallery';
+
+export const GALLERY_RENDERERS: Record<string, AstroComponentFactory> = {
+  ContentNote,
+  LicenseBadge,
+  LicenseFileBody,
+  ReferenceContract,
+  SiteFooter,
+  SiteHeader,
+  SiteShell,
+  TagChips,
+  FiltrationHero,
+  PersistenceDivider,
+  PointCloudFingerprint,
+  TopologyBreadcrumb,
+};
+
+const unrenderable = ALL_SPECIMENS.filter((group) => !GALLERY_RENDERERS[group.component]);
+if (unrenderable.length > 0) {
+  throw new Error(
+    `gallery has no renderer for: ${unrenderable.map((group) => group.component).join(', ')}`,
+  );
+}

site/src/lib/gallery.ts

@@ -0,0 +1,147 @@
+import { contractKeys } from '@galaxy-foundry/reference-contract';
+import type { ReferenceContractProps } from '@galaxy-foundry/site-kit';
+import {
+  SPECIMENS,
+  type Specimen,
+  type SpecimenGroup,
+} from '@galaxy-foundry/site-kit/specimens';
+
+import { contentReader } from './content-reader';
+import { referenceContract as loadReferenceContract } from './reference-contract';
+import { base } from './site-base';
+
+const referenceContract = loadReferenceContract();
+
+const kindSpecimen = (kind: string): Specimen<ReferenceContractProps> => {
+  const term = referenceContract.kinds[kind];
+  return {
+    id: kind,
+    name: term?.label ?? kind,
+    why:
+      term?.description ??
+      `The ${kind} reference kind under this Foundry's palette and fallback accent.`,
+    props: {
+      contract: referenceContract,
+      references: [
+        {
+          kind,
+          ref: `[[gallery-${kind}]]`,
+          used_at: 'runtime',
+          load: 'upfront',
+          mode: 'verbatim',
+          evidence: 'corpus-observed',
+        },
+      ],
+    },
+  };
+};
+
+export const TDA_KIND_SPECIMENS: SpecimenGroup<ReferenceContractProps> = {
+  id: 'tda-reference-kinds',
+  component: 'ReferenceContract',
+  importPath: '@galaxy-foundry/site-kit/ReferenceContract.astro',
+  summary:
+    'Every reference kind this Foundry declares, derived from its contract so a new kind cannot arrive unseen.',
+  surface: 'inline',
+  specimens: contractKeys(referenceContract, 'kinds').map(kindSpecimen),
+};
+
+export const FILTRATION_HERO_SPECIMENS: SpecimenGroup<{ noteCount: number }> = {
+  id: 'tda-filtration-hero',
+  component: 'FiltrationHero',
+  importPath: '../components/FiltrationHero.astro',
+  summary:
+    'The interactive frontispiece: a point cloud becomes a complex and leaves one persistent loop.',
+  surface: 'isolated',
+  specimens: [
+    {
+      id: 'stable-loop',
+      name: 'Structure across scale',
+      why:
+        'The range control makes filtration tangible while the copy connects multiscale structure to the Foundry workflow.',
+      props: { noteCount: contentReader.noteTargets().length },
+    },
+  ],
+};
+
+export const PERSISTENCE_DIVIDER_SPECIMENS: SpecimenGroup<{ seed: string }> = {
+  id: 'tda-persistence-divider',
+  component: 'PersistenceDivider',
+  importPath: '../components/PersistenceDivider.astro',
+  summary:
+    'A deterministic barcode used as punctuation between conceptual sections.',
+  surface: 'inline',
+  specimens: [
+    {
+      id: 'section-punctuation',
+      name: 'Persistent section break',
+      why:
+        'One interval receives the persistent accent, turning a divider into domain-specific hierarchy without adding prose.',
+      props: { seed: 'gallery:persistence-divider' },
+    },
+  ],
+};
+
+export const POINT_CLOUD_SPECIMENS: SpecimenGroup<{ seed: string }> = {
+  id: 'tda-point-cloud-fingerprint',
+  component: 'PointCloudFingerprint',
+  importPath: '../components/PointCloudFingerprint.astro',
+  summary:
+    'Seeded geometric marginalia that gives each surface a stable visual fingerprint.',
+  surface: 'inline',
+  specimens: [
+    {
+      id: 'stable-fingerprint',
+      name: 'Seeded point cloud',
+      why:
+        'The same semantic seed always yields the same points, neighborhood edges, and highlighted loop.',
+      props: { seed: 'gallery:point-cloud-fingerprint' },
+    },
+  ],
+};
+
+export const TOPOLOGY_BREADCRUMB_SPECIMENS: SpecimenGroup<{
+  href: string;
+  label: string;
+  current: string;
+  seed: string;
+}> = {
+  id: 'tda-topology-breadcrumb',
+  component: 'TopologyBreadcrumb',
+  importPath: '../components/TopologyBreadcrumb.astro',
+  summary:
+    'Back navigation drawn as connected nodes, paired with a deterministic point-cloud signature.',
+  surface: 'inline',
+  specimens: [
+    {
+      id: 'method-detail',
+      name: 'Connected reading path',
+      why:
+        'The ordinary collection-to-note relationship is expressed as a tiny graph without weakening breadcrumb semantics.',
+      props: {
+        href: `${base}/methods/`,
+        label: 'Methods',
+        current: 'Persistent homology',
+        seed: 'gallery:topology-breadcrumb',
+      },
+    },
+  ],
+};
+
+export const TDA_SPECIMENS: readonly SpecimenGroup[] = [
+  TDA_KIND_SPECIMENS,
+  FILTRATION_HERO_SPECIMENS,
+  PERSISTENCE_DIVIDER_SPECIMENS,
+  POINT_CLOUD_SPECIMENS,
+  TOPOLOGY_BREADCRUMB_SPECIMENS,
+];
+
+export const ALL_SPECIMENS: readonly SpecimenGroup[] = [...SPECIMENS, ...TDA_SPECIMENS];
+
+const groupIds = ALL_SPECIMENS.map((group) => group.id);
+if (new Set(groupIds).size !== groupIds.length) {
+  throw new Error('gallery specimen group ids must be unique across shared and TDA groups');
+}
+
+export const specimenOrigin = (group: SpecimenGroup): 'shared' | 'tda' =>
+  TDA_SPECIMENS.some((candidate) => candidate.id === group.id) ? 'tda' : 'shared';