diff --git a/docs/CODE_MAP.md b/docs/CODE_MAP.md index 5dfa2fd4..33fcd680 100644 --- a/docs/CODE_MAP.md +++ b/docs/CODE_MAP.md @@ -32,8 +32,9 @@ Browser | Feature | Where | | --- | --- | -| Landing page, interactive treemap example, shared navigation | `site/src/App.tsx`, `site/src/Landing.tsx`, `site/src/site.css` | -| User guides, search, table of contents | `site/src/App.tsx`, `site/src/docs/` | +| Landing page, product screenshots, shared navigation | `site/src/Landing.tsx`, `site/src/SiteChrome.tsx`, `site/src/site.css`, `site/public/screenshots/` | +| Product tour, design decisions, user guides, search, table of contents | `site/src/App.tsx`, `site/src/docs/` | +| Full-size screenshot viewer and zoom controls | `site/src/ScreenshotViewer.tsx` | | Static HTML, page metadata, sitemap, and GitHub Pages base path | `site/src/server.tsx`, `site/scripts/prerender.mjs`, `site/vite.config.ts` | ### CLI and process lifecycle diff --git a/site/DESIGN.md b/site/DESIGN.md index 149a59f4..671116c8 100644 --- a/site/DESIGN.md +++ b/site/DESIGN.md @@ -1,11 +1,12 @@ # Public site -The public site extends Srcly's light application palette and Draftably's demonstration-first structure. -It serves developers who want to inspect a local codebase or generate a report for an agent. +The public site extends Srcly's light application palette. It serves developers who want to inspect a local codebase or create a report for an agent. -The landing page pairs a direct setup command with an interactive, labeled example. -The example explains tile area, metric color, and file selection before the longer product copy. -Guides use grouped navigation, content search, section links, and previous/next links. +## Surface modes + +- Landing: Persuade. Lead with real Srcly views, then give two paths: see the product or use it. +- Guides: Read. Group navigation by the visitor's task, keep the article easy to scan, and link search results to the matching section. +- Screenshot viewer: Experience. Let the captured application view fill the screen. Keep zoom, reset, close, keyboard focus, and native image-link fallback. ## Tokens @@ -16,5 +17,16 @@ Guides use grouped navigation, content search, section links, and previous/next - Page width: 1160px; hero type: 42–68px; body: 15px. - Controls have visible focus outlines. Motion respects reduced-motion settings. -The treemap and terminal output are illustrations. Keep that labeling visible. -Do not imply the public site scans files or that missing measurements equal zero. +## Product proof + +- Use screenshots captured from the running application. Keep captions specific to the view and the action it supports. +- The hero uses the repository treemap. The gallery uses the treemap, code inspector, and data-flow views. +- The site must not imply that it scans files or that missing measurements equal zero. +- Do not invent metrics or terminal output to fill space. + +## Guides + +- Navigation groups: Discover, Use Srcly, and Automate & configure. +- Keep the page title, short summary, and edit link in one compact heading area. +- Search results show matching text and link to a matching section when one exists. +- Screenshot figures can open at full size. Keep the image link usable without JavaScript. diff --git a/site/README.md b/site/README.md index 87097ceb..bd16bcd5 100644 --- a/site/README.md +++ b/site/README.md @@ -13,9 +13,10 @@ pnpm test Open the printed development URL with `/srcly/` appended. The build writes `site/dist/`. Each guide has a complete HTML page, with page metadata and a canonical URL. -The browser adds the interactive example, guide search, and copy buttons. +The browser adds section-linked guide search, copy buttons, and a full-size screenshot viewer. -Edit user guides in `src/docs/pages/`. Keep command examples in sync with `server/app/run.py`. +Edit the product tour, design notes, and user guides in `src/docs/pages/`. +Keep command examples in sync with `server/app/run.py`. Add new pages to the navigation in `src/App.tsx` when required. The build reads page titles and introductions from Markdown for search metadata. @@ -24,12 +25,14 @@ Pull requests build the site and run its browser checks. See [DEPLOY.md](DEPLOY. ## Reference and design -Draftably's public site supplied the structure: an interactive product example, direct setup actions, and searchable task guides. +Draftably's public site supplied the structure: a product preview, direct setup actions, and searchable task guides. Srcly keeps its light surfaces, blue links, Inter type, and IBM Plex Mono commands. -The treemap uses clearly labeled example data. It does not scan visitor files. +Real app screenshots show Srcly inspecting its public source and checked-in fixtures. +Capture provenance is in `public/screenshots/README.md`. The site does not scan visitor files. +The docs have three groups: Discover, Use Srcly, and Automate & configure. ## Verification `pnpm test` runs a browser against the built site under `/srcly/`. -It checks direct guide links, rendered content, navigation, search, the example controls, and narrow screens. +It checks static guide content, local links, images, search anchors, screenshot zoom, copy feedback, and narrow screens. Keep screenshot evidence under the repository's ignored `tmp/` directory. diff --git a/site/public/screenshots/README.md b/site/public/screenshots/README.md new file mode 100644 index 00000000..b8227850 --- /dev/null +++ b/site/public/screenshots/README.md @@ -0,0 +1,12 @@ +# Screenshot assets + +These app screenshots come from a real local Srcly run at source revision `653037aa` (2026-11-06). The scanned source is the public `client/src` tree. The graph examples use the checked-in `engine/examples/symbol-graph` fixture. No private repository data appears in these images. + +Each JPEG is 1440 × 960 pixels at quality 88. Capture URLs, UI steps, raw PNG paths, and factual captions are recorded in `tmp/10x/docs/app/CAPTURES.md`. + +- `treemap.jpg` — client source tree sized by LOC and colored by maximum complexity. +- `hotspots.jpg` — ranked complexity list beside the treemap. +- `quadrant.jpg` — activity 2×2, with the Hot mess quadrant selected. +- `code-inspector.jpg` — `App.tsx` source and metrics, focused on the `openAt` complexity witness. +- `data-flow.jpg` — route trace with its partial outcome and callback handoff in the inspector. +- `symbols.jpg` — `NotePage` references in the symbol graph. diff --git a/site/public/screenshots/code-inspector.jpg b/site/public/screenshots/code-inspector.jpg new file mode 100644 index 00000000..e4505840 Binary files /dev/null and b/site/public/screenshots/code-inspector.jpg differ diff --git a/site/public/screenshots/data-flow.jpg b/site/public/screenshots/data-flow.jpg new file mode 100644 index 00000000..849b93eb Binary files /dev/null and b/site/public/screenshots/data-flow.jpg differ diff --git a/site/public/screenshots/hotspots.jpg b/site/public/screenshots/hotspots.jpg new file mode 100644 index 00000000..70853665 Binary files /dev/null and b/site/public/screenshots/hotspots.jpg differ diff --git a/site/public/screenshots/quadrant.jpg b/site/public/screenshots/quadrant.jpg new file mode 100644 index 00000000..561d1af3 Binary files /dev/null and b/site/public/screenshots/quadrant.jpg differ diff --git a/site/public/screenshots/symbols.jpg b/site/public/screenshots/symbols.jpg new file mode 100644 index 00000000..cd836781 Binary files /dev/null and b/site/public/screenshots/symbols.jpg differ diff --git a/site/public/screenshots/treemap.jpg b/site/public/screenshots/treemap.jpg new file mode 100644 index 00000000..e1877c30 Binary files /dev/null and b/site/public/screenshots/treemap.jpg differ diff --git a/site/scripts/prerender.mjs b/site/scripts/prerender.mjs index 1556bb21..5a9077a6 100644 --- a/site/scripts/prerender.mjs +++ b/site/scripts/prerender.mjs @@ -22,7 +22,8 @@ for (const filename of (await readdir("src/docs/pages")).filter((name) => name.e const description = markdown.split(/\n\s*\n/).find((block) => !block.startsWith("#")) ?.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/[`*_]/g, "").replace(/\s+/g, " ").slice(0, 200); assert(description, `Missing page introduction: ${filename}`); - pages.push({ route: `docs/${filename.slice(0, -3)}/`, title: `${title} · Srcly docs`, description }); + const slug = filename.slice(0, -3); + pages.push({ route: slug === "overview" ? "docs/" : `docs/${slug}/`, title: `${title} · Srcly docs`, description }); } function html(page) { @@ -35,7 +36,9 @@ function html(page) { ``, ``, ``, - ``, + ``, + ``, + ``, ].join("\n "); assert.equal(template.match(/
]*)>([\s\S]*?)<\/code><\/pre>/g, (full: string) => {
const id = `code-${codeIndex++}`;
- return `${full}`;
+ return `${full}`;
});
- return