Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions docs/CODE_MAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
26 changes: 19 additions & 7 deletions site/DESIGN.md
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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.
13 changes: 8 additions & 5 deletions site/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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.
12 changes: 12 additions & 0 deletions site/public/screenshots/README.md
Original file line number Diff line number Diff line change
@@ -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.
Binary file added site/public/screenshots/code-inspector.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added site/public/screenshots/data-flow.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added site/public/screenshots/hotspots.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added site/public/screenshots/quadrant.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added site/public/screenshots/symbols.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added site/public/screenshots/treemap.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
23 changes: 16 additions & 7 deletions site/scripts/prerender.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand All @@ -35,7 +36,9 @@ function html(page) {
`<meta property="og:title" content="${escape(page.title)}" />`,
`<meta property="og:description" content="${escape(page.description)}" />`,
`<meta property="og:url" content="${canonical}" />`,
`<meta name="twitter:card" content="summary" />`,
`<meta property="og:image" content="${origin}${base}screenshots/treemap.jpg" />`,
`<meta property="og:image:alt" content="Srcly inspecting its own client code in the treemap view" />`,
`<meta name="twitter:card" content="summary_large_image" />`,
].join("\n ");
assert.equal(template.match(/<title>.*?<\/title>/g)?.length, 1);
assert.equal(template.match(/<!-- page-meta -->/g)?.length, 1);
Expand All @@ -49,13 +52,19 @@ function html(page) {
for (const page of pages) {
const directory = `dist/${page.route}`;
await mkdir(directory, { recursive: true });
await writeFile(`${directory}/index.html`, html(page));
const content = html(page);
for (const match of content.matchAll(/<img[^>]+src="(\/srcly\/screenshots\/[^"?#]+)"/g)) {
const asset = await readFile(`dist/${match[1].slice(base.length)}`);
assert(asset.length > 0, `Missing screenshot in ${page.route}: ${match[1]}`);
}
await writeFile(`${directory}/index.html`, content);
}

// Keep the docs entry point readable on static hosts, including without JavaScript.
const start = pages.find((page) => page.route === "docs/get-started/");
assert(start, "The docs need a get-started page");
await writeFile("dist/docs/index.html", html(start));
// Keep the overview alias readable on static hosts, including without JavaScript.
const overview = pages.find((page) => page.route === "docs/");
assert(overview, "The docs need an overview page");
await mkdir("dist/docs/overview", { recursive: true });
await writeFile("dist/docs/overview/index.html", html(overview));
await writeFile("dist/404.html", html({ route: "404/", title: "Page not found · Srcly", description: "Find Srcly documentation and setup guides." }).replace('<meta property="og:type"', '<meta name="robots" content="noindex" /><meta property="og:type"'));
await writeFile("dist/.nojekyll", "");
await writeFile("dist/robots.txt", `User-agent: *\nAllow: /\nSitemap: ${origin}${base}sitemap.xml\n`);
Expand Down
Loading
Loading