@ifc-lite/viewer 1.19.0 → 1.19.1

package/src/components/mcp/README.md

@@ -0,0 +1,171 @@
+# `/mcp` landing — three alternatives
+
+This folder holds three production-quality landing-page candidates for the
+`@ifc-lite/mcp` marketing surface, plus the data and shells they share. Each
+variant is a single self-contained `.tsx` that reads the same catalog +
+recipes + install configs from `./data.ts` so the **content** is identical
+across all three; only the **design language** changes.
+
+```text
+data.ts                 — shared content (catalog, clients, recipes, snippets)
+types.ts                — typed shapes for the shared content
+use-mcp-page.ts         — useFonts / useCopy / useDocumentMeta helpers
+McpLandingA.tsx         — Variant A · "Atelier"        (editorial dev-tool)
+McpLandingB.tsx         — Variant B · "Stage"          (cinematic dark)
+McpLandingC.tsx         — Variant C · "Drafting Room"  (BIM craft)
+McpLandingChooser.tsx   — flips between A/B/C via ?variant=
+```
+
+The catalog is read from
+`apps/viewer/src/generated/mcp-catalog.json`, currently hand-seeded with the
+real shape of the v0.1 surface. A future build step
+(`node packages/mcp/dist/cli.js --dump-tools`) will overwrite that file at
+release time without changing the page code.
+
+---
+
+## Compare them
+
+```text
+/mcp              → Variant A (default)
+/mcp?variant=a    → Variant A
+/mcp?variant=b    → Variant B
+/mcp?variant=c    → Variant C
+```
+
+A small floating chip in the bottom-right also lets you switch without
+touching the URL. The chip is explicitly temporary and gets removed once a
+winner is picked.
+
+---
+
+## Variant A — "Atelier"
+
+> *Editorial dev-tool. Lineage: Stripe / Linear / JetBrains docs.*
+
+| Aspect | Choice |
+|---|---|
+| Background | Warm paper `#fafaf6` (intentionally light-only) |
+| Display | **Newsreader** — variable serif, optical sizes 6–72 |
+| Body & code | **JetBrains Mono** for everything technical, Newsreader at small sizes for prose |
+| Accent | Forest green `#1f4d35` for live elements, amber `#b8742a` for editorial markers |
+| Layout | Narrow content column (`max-w-[68rem]`), 12-col internal grid, sticky-left tool nav |
+| Distinctive moves | Numbered `§01–§03` sections · dropped capitals on the lede · margin "Marginal" notes (Issue · Filed under · Surface · Transports) · hairline filigree dividers · API-reference-style tool rows with `(required, fields)` parameter signatures |
+
+**Strongest when:** the audience is engineers who scan tools/list pages
+forensically and want signal density. The page reads like a printed
+specimen — restrained, opinionated, deeply technical.
+
+**Trade-offs:** the page is cool, not warm. Doesn't market the "agent
+driving a building" feeling — the tool catalog is the centrepiece, not the
+demo. Light-only feels deliberate but loses the developer dark-mode crowd.
+
+---
+
+## Variant B — "Stage"
+
+> *Cinematic dark, demo-driven. Lineage: Linear marketing / Vercel AI / Apple keynote slides.*
+
+| Aspect | Choice |
+|---|---|
+| Background | Deep ink `#0a0a0c` with a fractal-noise grain at 8% mix-overlay |
+| Display | **Instrument Serif** with italic flex for the headlines |
+| Body | **Bricolage Grotesque** (variable, weights 300–700) |
+| Code | **JetBrains Mono** |
+| Accent | Hi-vis chartreuse `#d6ff3f` (construction safety hint) + magenta `#ff5cdc` for interactions |
+| Layout | Full-bleed sections, generous whitespace, oversized cards, horizontal recipe carousel |
+| Distinctive moves | Hero contains a **live SVG IFC wireframe** that progressively colorises through 7 transcript steps (`viewer_color_by_storey` → `viewer_isolate(IfcWall)` → `viewer_colorize(...)`) so the visitor sees the agent driving the model · install grid as oversized cards with hover-glow · recipes as a horizontally scrollable transcript carousel with family-coloured headers · big italic numerals as section markers |
+
+**Strongest when:** the goal is to make people *feel* the product before
+they read about it. This is the "land on Twitter and screenshot" version —
+the wireframe-in-motion is the kind of thing other dev-tool sites don't have.
+
+**Trade-offs:** highest implementation surface (animation state, carousel,
+gradients). The hero animation has to land flawlessly or it looks cheap.
+Dark-only by design, which slightly clashes with the rest of the SPA's
+light/dark toggle.
+
+---
+
+## Variant C — "Drafting Room"
+
+> *BIM craft. Lineage: architectural section drawings, title blocks, Le Corbusier sketches.*
+
+| Aspect | Choice |
+|---|---|
+| Background | Drafting-paper cream `#f4f1e8` over a hairline 8mm + 80mm grid |
+| Display | **EB Garamond** (with italics for the "now drives an LLM" moments) |
+| Body | **EB Garamond** (prose) + **JetBrains Mono** (every datum) |
+| Annotations | **Caveat** — a hand-drafted face used for callouts, leader text, and pencil notes |
+| Accent | Drafting-pencil red `#a8332d` for annotations, drafting blue `#4a6fa5` for live links |
+| Layout | Title-block header (Sheet / Scale / Date / Drawn / Status / Version) · dimension-line section dividers with end-ticks and labelled spans |
+| Distinctive moves | Hero figure is an **isometric IFC entity stack** (project → site → building → storey → wall) with leader-line callouts identifying live tool effects (`IfcWall #262 · painted via MCP`) · install rows formatted like a door-schedule (`I-01`, `I-02`, …) with Mark / Host / Spec / Type / Sht. columns · tool catalog renders as a **building schedule** with mark numbers (`01.07`), R/W/X scope chips, and a sticky storey-style legend · recipes as detail callouts with bubble + leader + "Sht. R-04" reference · north arrow + scale bar at the foot of the hero · sheet-footer pretends the page is a single drawing printed at 1:1 |
+
+**Strongest when:** the audience is architects, structural engineers,
+contractors. Nobody else in dev-tool marketing has shipped a landing that
+respects the AEC craft tradition — the page itself reads as a drawing,
+which is a pun the target audience will get and the LLM crowd will at
+least notice. Strong word-of-mouth potential inside buildingSMART /
+ifc-rs / IfcOpenShell circles.
+
+**Trade-offs:** highest "design point of view" but smallest
+"approachable for any LLM dev" surface. Someone unfamiliar with IFC may
+read the page as a quirky theme rather than a marketing site. Light-only,
+so dark-mode users see a flash on entry.
+
+---
+
+## How to pick
+
+The three differ on **three axes**, not just colour:
+
+| | Variant A | Variant B | Variant C |
+|---|---|---|---|
+| Centrepiece | Tool catalogue | Hero animation | Domain craft |
+| Type discipline | Editorial | Cinematic | Technical drawing |
+| Audience peak | Senior dev / docs reader | Founder / "show me the future" | AEC native / BIM circles |
+| Risk if wrong | Feels too dry | Feels overproduced | Reads as gimmick |
+| Permanence | High — easy to age well | Medium — animations age fastest | High — drafting visuals are timeless |
+
+If the goal is **maximum reach across LLM developers**, B reads loudest.
+If the goal is **lasting authority** with both engineers and AEC pros,
+A is the safest. If the goal is **distinctive positioning** — the only
+MCP landing that visibly came out of an architecture toolkit — C is the
+strongest single-shot.
+
+---
+
+## Implementation notes
+
+* All three variants share the same JSON snippet generator
+  (`makeConfigSnippet`) so the install dialogs stay in lockstep — change
+  it in one place when the bin gets renamed.
+* All three call `useFonts(...)` which injects Google Fonts `<link>`
+  stylesheets while mounted, and refcounts them so flipping between
+  variants doesn't double-load. Fonts are intentionally NOT added to
+  `index.html` so the main viewer keeps its existing first-paint budget.
+* `useDocumentMeta(title, themeColor)` keeps the browser tab and theme
+  colour aligned to whichever variant is mounted.
+* The chooser writes `?variant=…` to the URL via `pushState`, so back
+  button works and direct deep-links to a variant are possible.
+* Tool rows are deep-linkable: `/mcp#viewer_get_selection`. All three
+  variants honour this anchor.
+* Recipes use `data.ts:RECIPES` and emit `data-uses` chips that
+  link directly into the catalog anchors — single source of truth.
+
+## Known follow-ups (not blocking the choice)
+
+1. **Generated catalog**: replace `apps/viewer/src/generated/mcp-catalog.json`
+   with output from `node packages/mcp/dist/cli.js --dump-tools` (CLI flag
+   to be added). The current file is hand-seeded with the real v0.1
+   surface so the page renders as production would.
+2. **Playground link**: all three CTA the `/mcp/playground` route, which
+   is now wired (see `McpPlayground.tsx`, the dispatcher, the inline
+   Three.js viewer, and the BYOK Anthropic chat). The whole read+write
+   tool surface — including BCF authoring, IDS validation, exports, and
+   mutations — runs against an in-browser parsed IFC. No backend.
+3. **Fonts**: Google Fonts is fine for design comparison; production may
+   want to self-host (woff2) for COOP/COEP compliance and stable
+   first-paint.
+4. **Remove the chooser chip** and replace this folder's exports with a
+   single `McpLanding` once the winner is picked.