From 22fde5bf9f3b4b543582205515728f27758468f5 Mon Sep 17 00:00:00 2001 From: Thalida Noel Date: Sat, 8 Aug 2026 18:03:40 -0400 Subject: [PATCH 01/19] feat: publish the build version on /api/config --- api/models/responses.py | 1 + api/routers/meta.py | 2 + api/tests/test_models.py | 6 +- api/tests/test_server_config.py | 16 + api/tests/test_server_health.py | 8 +- app/src/api/config.ts | 5 +- app/src/types/manifest.generated.ts | 2056 ++++++++++++++------------- app/tests/api/config.test.ts | 16 + app/tests/api/pathBatcher.test.ts | 8 +- 9 files changed, 1089 insertions(+), 1029 deletions(-) diff --git a/api/models/responses.py b/api/models/responses.py index 0fda90c1..e3998308 100644 --- a/api/models/responses.py +++ b/api/models/responses.py @@ -39,6 +39,7 @@ class HealthResponse(BaseModel): class ConfigResponse(BaseModel): allowLocalRepos: bool maxBatchPaths: int + version: str class CommitDetailResponse(BaseModel): diff --git a/api/routers/meta.py b/api/routers/meta.py index 0c97813e..5308f7bd 100644 --- a/api/routers/meta.py +++ b/api/routers/meta.py @@ -6,6 +6,7 @@ from fastapi import APIRouter +from api import __version__ from api.config import MAX_BATCH_PATHS, local_repos_allowed from api.models.responses import ConfigResponse, HealthResponse @@ -22,4 +23,5 @@ def config() -> ConfigResponse: return ConfigResponse( allowLocalRepos=local_repos_allowed(), maxBatchPaths=MAX_BATCH_PATHS, + version=__version__, ) diff --git a/api/tests/test_models.py b/api/tests/test_models.py index 5999c124..4419a9db 100644 --- a/api/tests/test_models.py +++ b/api/tests/test_models.py @@ -169,8 +169,10 @@ def test_health_and_config(self) -> None: self.assertEqual(HealthResponse(ok=True).model_dump(), {"ok": True}) self.assertEqual( - ConfigResponse(allowLocalRepos=False, maxBatchPaths=64).model_dump(), - {"allowLocalRepos": False, "maxBatchPaths": 64}, + ConfigResponse( + allowLocalRepos=False, maxBatchPaths=64, version="1.2.3" + ).model_dump(), + {"allowLocalRepos": False, "maxBatchPaths": 64, "version": "1.2.3"}, ) def test_sse_event_serialization(self) -> None: diff --git a/api/tests/test_server_config.py b/api/tests/test_server_config.py index 4f80ea4e..5a118d38 100644 --- a/api/tests/test_server_config.py +++ b/api/tests/test_server_config.py @@ -20,18 +20,24 @@ def client(tmp_path: Path) -> TestClient: def test_config_enabled(client: TestClient, monkeypatch) -> None: + from api import __version__ + monkeypatch.setenv("CODECITY_ALLOW_LOCAL_REPOS", "1") assert client.get("/api/config").json() == { "allowLocalRepos": True, "maxBatchPaths": MAX_BATCH_PATHS, + "version": __version__, } def test_config_disabled(client: TestClient, monkeypatch) -> None: + from api import __version__ + monkeypatch.delenv("CODECITY_ALLOW_LOCAL_REPOS", raising=False) assert client.get("/api/config").json() == { "allowLocalRepos": False, "maxBatchPaths": MAX_BATCH_PATHS, + "version": __version__, } @@ -41,3 +47,13 @@ def test_config_publishes_the_cap_the_batch_routes_enforce() -> None: from api.routers import file as file_router assert file_router.MAX_BATCH_PATHS == MAX_BATCH_PATHS + + +def test_config_reports_the_running_package_version(client: TestClient) -> None: + """The footer shows which build is running, so /api/config carries the + package version rather than the client guessing from a bundled constant.""" + from api import __version__ + + body = client.get("/api/config").json() + assert body["version"] == __version__ + assert body["version"] diff --git a/api/tests/test_server_health.py b/api/tests/test_server_health.py index 3534cf6e..1ce828a1 100644 --- a/api/tests/test_server_health.py +++ b/api/tests/test_server_health.py @@ -34,6 +34,8 @@ def test_config_default_disabled( # The conftest sets CODECITY_ALLOW_LOCAL_REPOS=1 session-wide for # tests that exercise local scan paths. Override it here to verify the # default-disabled state that the real endpoint exposes. + from api import __version__ + monkeypatch.delenv("CODECITY_ALLOW_LOCAL_REPOS", raising=False) static = tmp_path / "static" static.mkdir() @@ -41,7 +43,11 @@ def test_config_default_disabled( app = create_app(static_dir=static) r = TestClient(app).get("/api/config") assert r.status_code == 200 - assert r.json() == {"allowLocalRepos": False, "maxBatchPaths": MAX_BATCH_PATHS} + assert r.json() == { + "allowLocalRepos": False, + "maxBatchPaths": MAX_BATCH_PATHS, + "version": __version__, + } def test_root_serves_index(client: TestClient) -> None: diff --git a/app/src/api/config.ts b/app/src/api/config.ts index c17585b1..5b2081e8 100644 --- a/app/src/api/config.ts +++ b/app/src/api/config.ts @@ -9,10 +9,12 @@ import type { components } from '@/types/manifest.generated'; export type ServerConfig = components['schemas']['ConfigResponse']; // Pre-boot defaults. maxBatchPaths guesses low: too high silently truncates a -// batch's tail, too low only costs an extra request. +// batch's tail, too low only costs an extra request. `version` matches the +// backend's own metadata-lookup fallback. export const DEFAULT_SERVER_CONFIG: ServerConfig = { allowLocalRepos: false, maxBatchPaths: 16, + version: '0.0.0+unknown', }; let _cached: Promise | null = null; @@ -38,6 +40,7 @@ export async function fetchServerConfig(): Promise { ...(typeof body.maxBatchPaths === 'number' && body.maxBatchPaths > 0 ? { maxBatchPaths: body.maxBatchPaths } : {}), + ...(typeof body.version === 'string' && body.version ? { version: body.version } : {}), }; } catch (_) { return DEFAULT_SERVER_CONFIG; diff --git a/app/src/types/manifest.generated.ts b/app/src/types/manifest.generated.ts index 81e4d21f..c2d5abf0 100644 --- a/app/src/types/manifest.generated.ts +++ b/app/src/types/manifest.generated.ts @@ -4,1049 +4,1059 @@ */ export interface paths { - "/api/health": { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; - }; - /** Health */ - get: operations["health_api_health_get"]; - put?: never; - post?: never; - delete?: never; - options?: never; - head?: never; - patch?: never; - trace?: never; - }; - "/api/config": { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; - }; - /** Config */ - get: operations["config_api_config_get"]; - put?: never; - post?: never; - delete?: never; - options?: never; - head?: never; - patch?: never; - trace?: never; - }; - "/api/file": { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; - }; - /** Get File */ - get: operations["get_file_api_file_get"]; - put?: never; - post?: never; - delete?: never; - options?: never; - head?: never; - patch?: never; - trace?: never; - }; - "/api/images": { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; - }; - get?: never; - put?: never; - /** - * Get Images - * @description Batch image fetch — {path: {mime, b64}} for many small images in one round - * trip. NOT a plural of GET /api/file: it inlines base64, serves images only, - * and omits anything it can't serve. It exists so the scene's billboard loader - * doesn't exhaust the browser's HTTP/1.1 connection pool on a media-heavy repo. - * - * Each path is trust-checked exactly like GET /api/file. Paths that are out of - * root, missing, non-image, or larger than _MAX_BATCH_IMAGE_BYTES are silently - * omitted; the client falls back to the streaming GET for those. Videos are - * never batched (they stream their poster frame), so this is images only. - */ - post: operations["get_images_api_images_post"]; - delete?: never; - options?: never; - head?: never; - patch?: never; - trace?: never; - }; - "/api/fingerprints": { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; - }; - get?: never; - put?: never; - /** - * Get Fingerprints - * @description Batch byte-pattern fingerprint fetch — {path: {b64}}, one round trip for - * many buildings. Trust-checked like GET /api/file; out-of-root / missing / - * unreadable paths are silently omitted. Raw binary bytes never leave the - * server — only the head is read, and only the fingerprint image returned. - */ - post: operations["get_fingerprints_api_fingerprints_post"]; - delete?: never; - options?: never; - head?: never; - patch?: never; - trace?: never; - }; - "/api/commit": { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; - }; - /** Get Commit */ - get: operations["get_commit_api_commit_get"]; - put?: never; - post?: never; - delete?: never; - options?: never; - head?: never; - patch?: never; - trace?: never; - }; - "/api/branches": { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; - }; - /** Get Branches */ - get: operations["get_branches_api_branches_get"]; - put?: never; - post?: never; - delete?: never; - options?: never; - head?: never; - patch?: never; - trace?: never; - }; - "/api/manifest/signature": { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; - }; - /** Signature */ - get: operations["signature_api_manifest_signature_get"]; - put?: never; - post?: never; - delete?: never; - options?: never; - head?: never; - patch?: never; - trace?: never; - }; - "/api/timeline": { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; - }; - /** Timeline */ - get: operations["timeline_api_timeline_get"]; - put?: never; - post?: never; - delete?: never; - options?: never; - head?: never; - patch?: never; - trace?: never; - }; - "/api/manifest": { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; - }; - /** Manifest */ - get: operations["manifest_api_manifest_get"]; - put?: never; - post?: never; - delete?: never; - options?: never; - head?: never; - patch?: never; - trace?: never; + '/api/health': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** Health */ + get: operations['health_api_health_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/config': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** Config */ + get: operations['config_api_config_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/file': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** Get File */ + get: operations['get_file_api_file_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/images': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put?: never; + /** + * Get Images + * @description Batch image fetch — {path: {mime, b64}} for many small images in one round + * trip. NOT a plural of GET /api/file: it inlines base64, serves images only, + * and omits anything it can't serve. It exists so the scene's billboard loader + * doesn't exhaust the browser's HTTP/1.1 connection pool on a media-heavy repo. + * + * Each path is trust-checked exactly like GET /api/file. Paths that are out of + * root, missing, non-image, or larger than _MAX_BATCH_IMAGE_BYTES are silently + * omitted; the client falls back to the streaming GET for those. Videos are + * never batched (they stream their poster frame), so this is images only. + */ + post: operations['get_images_api_images_post']; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/fingerprints': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put?: never; + /** + * Get Fingerprints + * @description Batch byte-pattern fingerprint fetch — {path: {b64}}, one round trip for + * many buildings. Trust-checked like GET /api/file; out-of-root / missing / + * unreadable paths are silently omitted. Raw binary bytes never leave the + * server — only the head is read, and only the fingerprint image returned. + */ + post: operations['get_fingerprints_api_fingerprints_post']; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/commit': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** Get Commit */ + get: operations['get_commit_api_commit_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/branches': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; }; + /** Get Branches */ + get: operations['get_branches_api_branches_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/manifest/signature': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** Signature */ + get: operations['signature_api_manifest_signature_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/timeline': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** Timeline */ + get: operations['timeline_api_timeline_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/manifest': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** Manifest */ + get: operations['manifest_api_manifest_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; } export type webhooks = Record; export interface components { - schemas: { - /** AuthorStat */ - AuthorStat: { - /** Name */ - name: string; - /** Commits */ - commits: number; - /** - * Hue - * @description Stable 0-359 hue from the name hash; the display colour is built from it client-side - */ - hue: number; - }; - /** BranchListResponse */ - BranchListResponse: { - /** Branches */ - branches: string[]; - /** Default */ - default: string | null; - }; - /** BusynessThresholds */ - BusynessThresholds: { - /** Avg */ - avg: number; - /** Busy */ - busy: number; - }; - /** - * CloneProgressEvent - * @description `clone-progress` — git source is being cloned; carries clone progress. - * - * A normal progress tick has `stage` + `percent`. A heartbeat during the - * silent promisor blob fetch instead carries `mb_on_disk` (and no percent), - * so the UI shows the working tree materializing rather than freezing. - */ - CloneProgressEvent: { - /** Label */ - label?: string; - /** - * Stage - * @enum {string} - */ - stage?: "receiving" | "resolving" | "counting" | "updating"; - /** Percent */ - percent?: number; - /** Mb On Disk */ - mb_on_disk?: number; - }; - /** CommitDateRange */ - CommitDateRange: { - /** - * Oldest - * @description Oldest commit date (YYYY-MM-DD), or null when the repo has no commits - */ - oldest: string | null; - /** - * Newest - * @description Newest commit date (YYYY-MM-DD), or null when the repo has no commits - */ - newest: string | null; - }; - /** CommitDetailResponse */ - CommitDetailResponse: { - /** Sha */ - sha: string; - /** Authors */ - authors: string[]; - /** Date */ - date: string; - /** Subject */ - subject: string; - /** Body */ - body: string; - }; - /** CommitEntry */ - CommitEntry: { - /** - * Date - * @description ISO-8601 UTC, e.g. 2026-07-25T14:03:21Z - */ - date: string; - /** Files */ - files: number; - /** Sha */ - sha: string; - /** Authors */ - authors: string[]; - /** Subject */ - subject: string; - /** Same Day Total */ - same_day_total: number; - }; - /** CommitLeader */ - CommitLeader: { - /** Sha */ - sha: string; - /** Files */ - files: number; - }; - /** - * CompleteManifestEvent - * @description `manifest-complete` — a manifest with real, fully-populated metadata (a - * fresh scan's final pass, or a warm cache hit). - */ - CompleteManifestEvent: { - manifest: components["schemas"]["Manifest"]; - }; - /** ConfigResponse */ - ConfigResponse: { - /** Allowlocalrepos */ - allowLocalRepos: boolean; - /** Maxbatchpaths */ - maxBatchPaths: number; - }; - /** DateRangeMs */ - DateRangeMs: { - /** Mincreated */ - minCreated: number; - /** Maxcreated */ - maxCreated: number; - /** Minmodified */ - minModified: number; - /** Maxmodified */ - maxModified: number; - }; - /** DateRanges */ - DateRanges: { - /** - * Mincreated - * @description Earliest resolved create date (ISO), or null for an empty tree - */ - minCreated: string | null; - /** - * Maxcreated - * @description Latest resolved create date (ISO), or null for an empty tree - */ - maxCreated: string | null; - /** - * Minmodified - * @description Earliest resolved modify date (ISO), or null for an empty tree - */ - minModified: string | null; - /** - * Maxmodified - * @description Latest resolved modify date (ISO), or null for an empty tree - */ - maxModified: string | null; - }; - /** DayLeader */ - DayLeader: { - /** Date */ - date: string; - /** Count */ - count: number; - }; - /** DirLeader */ - DirLeader: { - /** Path */ - path: string; - /** Depth */ - depth: number; - /** Children */ - children: number; - /** Descendants */ - descendants: number; - }; - /** DirNode */ - DirNode: { - /** Name */ - name: string; - /** - * @description discriminator enum property added by openapi-typescript - * @enum {string} - */ - type: "directory"; - /** Path */ - path: string; - /** Fullpath */ - fullPath: string; - /** Children */ - children: (components["schemas"]["FileNode"] | components["schemas"]["DirNode"])[]; - /** Children Count */ - children_count: number; - /** Children File Count */ - children_file_count: number; - /** Children Dir Count */ - children_dir_count: number; - /** Descendants Count */ - descendants_count: number; - /** Descendants File Count */ - descendants_file_count: number; - /** Descendants Dir Count */ - descendants_dir_count: number; - /** Descendants Size */ - descendants_size: number; - /** Descendants Created Min */ - descendants_created_min: string | null; - /** Descendants Modified Max */ - descendants_modified_max: string | null; - /** Descendants Ext Breakdown */ - descendants_ext_breakdown: components["schemas"]["ExtBreakdownEntry"][]; - }; - /** - * ErrorEvent - * @description `error` — a failure after the stream began; carries the message. - */ - ErrorEvent: { - /** Error */ - error: string; - }; - /** ExtBreakdownEntry */ - ExtBreakdownEntry: { - /** Ext */ - ext: string | null; - /** Count */ - count: number; - /** Size */ - size: number; - }; - /** FileLeader */ - FileLeader: { - /** Path */ - path: string; - /** Lines */ - lines: number; - /** Bytes */ - bytes: number; - /** Created */ - created: string; - /** Modified */ - modified: string; - /** Media Width */ - media_width?: number; - /** Media Height */ - media_height?: number; - }; - /** FileNode */ - FileNode: { - /** Name */ - name: string; - /** - * @description discriminator enum property added by openapi-typescript - * @enum {string} - */ - type: "file"; - /** Path */ - path: string; - /** Fullpath */ - fullPath: string; - /** Extension */ - extension: string; - /** Size */ - size: number; - /** Lines */ - lines: number; - /** Binary */ - binary: boolean; - /** - * Dirty - * @description Working-tree differs from HEAD for this tracked file (staged or unstaged). Always False for clean/remote repos. - */ - dirty: boolean; - /** - * Created - * @description ISO create date (UTC, Z-suffixed), resolved server-side: git history date when the file has one, filesystem date otherwise - */ - created: string; - /** - * Modified - * @description ISO modify date (UTC, Z-suffixed), resolved server-side: git history date when the file has one, filesystem date otherwise. When dirty is true, this is always the working-tree filesystem date, regardless of git history - */ - modified: string; - /** - * Mediakind - * @description Media classification by extension (single source for the frontend); null for non-media files - */ - mediaKind?: ("image" | "video") | null; - /** Media Width */ - media_width?: number; - /** Media Height */ - media_height?: number; - /** Binarytype */ - binaryType?: string; - }; - /** - * FingerprintEntry - * @description One binary file's byte-pattern fingerprint in a POST /api/fingerprints - * batch response: a base64-encoded grayscale PNG (image/png implied), keyed - * by request path. Computed server-side from the file's head — raw binary - * bytes never ship to the client. - */ - FingerprintEntry: { - /** B64 */ - b64: string; - }; - /** HTTPValidationError */ - HTTPValidationError: { - /** Detail */ - detail?: components["schemas"]["ValidationError"][]; - }; - /** HealthResponse */ - HealthResponse: { - /** Ok */ - ok: boolean; - }; - /** - * ImageBatchEntry - * @description One image in a POST /api/images batch response: its content-type and - * base64-encoded bytes, keyed by request path in the response map. - */ - ImageBatchEntry: { - /** Mime */ - mime: string; - /** B64 */ - b64: string; - }; - /** Manifest */ - Manifest: { - /** Root */ - root: string; - /** Scanned At */ - scanned_at: string; - /** Content Signature */ - content_signature: string; - /** Structure Signature */ - structure_signature: string; - /** Layout Signature */ - layout_signature: string; - tree: components["schemas"]["DirNode"]; - repo: components["schemas"]["RepoInfo"]; - /** Commits */ - commits: components["schemas"]["CommitEntry"][]; - busyness: components["schemas"]["BusynessThresholds"]; - dateRanges: components["schemas"]["DateRanges"]; - stats: components["schemas"]["RepoStats"]; - /** - * Pending - * @description Stages still to come. 'metadata': per-file lines/binary are placeholders. 'history': dates are filesystem dates and commits is empty. Empty list means every field is final. - */ - pending: ("metadata" | "history")[]; - /** - * Readmepath - * @description Absolute path of the root README, or null if there isn't one - */ - readmePath: string | null; - /** - * Readmemodified - * @description That README's mtime, for cache-busting the fetch - */ - readmeModified: string | null; - }; - /** - * PartialManifestEvent - * @description `manifest-partial` — a manifest with the real tree structure but - * placeholder file metadata, sent so the UI can paint the city before - * per-file metadata is resolved. - */ - PartialManifestEvent: { - manifest: components["schemas"]["Manifest"]; - }; - /** PathBatchRequest */ - PathBatchRequest: { - /** Paths */ - paths: string[]; - /** Shas */ - shas?: { - [key: string]: string; - } | null; - }; - /** RangeStat */ - RangeStat: { - /** Min */ - min: number; - /** Max */ - max: number; - }; - /** RepoInfo */ - RepoInfo: { - /** Branch */ - branch: string | null; - /** Remote Url */ - remote_url: string | null; - /** Head Sha */ - head_sha: string | null; - /** Head Subject */ - head_subject: string | null; - /** Dirty */ - dirty: boolean; - }; - /** RepoStats */ - RepoStats: { - lineCountRange: components["schemas"]["RangeStat"]; - byteSizeRange: components["schemas"]["RangeStat"]; - oldestCreatedFile: components["schemas"]["FileLeader"] | null; - newestCreatedFile: components["schemas"]["FileLeader"] | null; - newestModifiedFile: components["schemas"]["FileLeader"] | null; - oldestModifiedFile: components["schemas"]["FileLeader"] | null; - maxLinesFile: components["schemas"]["FileLeader"] | null; - minLinesFile: components["schemas"]["FileLeader"] | null; - maxBytesFile: components["schemas"]["FileLeader"] | null; - minBytesFile: components["schemas"]["FileLeader"] | null; - maxMediaBytesFile: components["schemas"]["FileLeader"] | null; - minMediaBytesFile: components["schemas"]["FileLeader"] | null; - maxMediaPixelsFile: components["schemas"]["FileLeader"] | null; - minMediaPixelsFile: components["schemas"]["FileLeader"] | null; - maxBinaryBytesFile: components["schemas"]["FileLeader"] | null; - minBinaryBytesFile: components["schemas"]["FileLeader"] | null; - /** Mediacount */ - mediaCount: number; - /** Binarycount */ - binaryCount: number; - /** Totallines */ - totalLines: number; - /** Dirtyfilecount */ - dirtyFileCount: number; - /** Codebytes */ - codeBytes: number; - maxDepthDir: components["schemas"]["DirLeader"] | null; - maxChildrenDir: components["schemas"]["DirLeader"] | null; - minChildrenDir: components["schemas"]["DirLeader"] | null; - maxFilesPerCommit: components["schemas"]["CommitLeader"] | null; - minFilesPerCommit: components["schemas"]["CommitLeader"] | null; - commitDates: components["schemas"]["CommitDateRange"]; - maxCommitsPerDay: components["schemas"]["DayLeader"] | null; - /** Maxcommitstreakdays */ - maxCommitStreakDays: number; - /** Authors */ - authors: components["schemas"]["AuthorStat"][]; - }; - /** - * ScanProgressEvent - * @description `scan-progress` — the working tree is being walked; carries the - * heartbeat files-scanned count. - */ - ScanProgressEvent: { - /** Label */ - label?: string; - /** Files Scanned */ - files_scanned?: number; - }; - /** SignatureResponse */ - SignatureResponse: { - /** Root */ - root: string; - /** Scanned At */ - scanned_at: string; - /** Content Signature */ - content_signature: string; - }; - /** - * TimelineBundle - * @description Wire schema for the scrub bundle; mirrors manifest_types.TimelineBundle. - */ - TimelineBundle: { - /** Commits */ - commits: components["schemas"]["CommitEntry"][]; - unionManifest: components["schemas"]["Manifest"]; - /** Deltas */ - deltas: components["schemas"]["TimelineDelta"][]; - /** Bloblines */ - blobLines: { - [key: string]: number; - }; - /** Blobsizes */ - blobSizes: { - [key: string]: number; - }; - /** Commitlineranges */ - commitLineRanges: components["schemas"]["RangeStat"][]; - /** Commitdateranges */ - commitDateRanges: components["schemas"]["DateRangeMs"][]; - /** Note */ - note: string | null; - }; - /** TimelineChange */ - TimelineChange: { - /** Path */ - path: string; - /** - * Sha - * @description New blob sha, or null when deleted - */ - sha: string | null; - }; - /** - * TimelineCompleteEvent - * @description `timeline-complete` — the full replay bundle (fresh build or warm - * cache hit). - */ - TimelineCompleteEvent: { - bundle: components["schemas"]["TimelineBundle"]; - }; - /** TimelineDelta */ - TimelineDelta: { - /** Sha */ - sha: string; - /** Changes */ - changes: components["schemas"]["TimelineChange"][]; - }; - /** - * TimelineProgressEvent - * @description `timeline-progress` — the history walk, blob-table resolution, or (for a - * blobless remote clone) the up-front blob backfill is in progress. The - * `fetch` stage carries `percent`; `history` carries `commits`; `blobs` - * carries `blobsDone`/`blobsTotal` (the total is known up front from the batch - * blob lookup, so that stage reports two ticks, not a live stream). - */ - TimelineProgressEvent: { - /** - * Stage - * @enum {string} - */ - stage: "fetch" | "history" | "blobs"; - /** Percent */ - percent?: number; - /** Commits */ - commits?: number; - /** Blobsdone */ - blobsDone?: number; - /** Blobstotal */ - blobsTotal?: number; - /** Label */ - label?: string; - }; - /** ValidationError */ - ValidationError: { - /** Location */ - loc: (string | number)[]; - /** Message */ - msg: string; - /** Error Type */ - type: string; - /** Input */ - input?: unknown; - /** Context */ - ctx?: Record; - }; + schemas: { + /** AuthorStat */ + AuthorStat: { + /** Name */ + name: string; + /** Commits */ + commits: number; + /** + * Hue + * @description Stable 0-359 hue from the name hash; the display colour is built from it client-side + */ + hue: number; + }; + /** BranchListResponse */ + BranchListResponse: { + /** Branches */ + branches: string[]; + /** Default */ + default: string | null; + }; + /** BusynessThresholds */ + BusynessThresholds: { + /** Avg */ + avg: number; + /** Busy */ + busy: number; + }; + /** + * CloneProgressEvent + * @description `clone-progress` — git source is being cloned; carries clone progress. + * + * A normal progress tick has `stage` + `percent`. A heartbeat during the + * silent promisor blob fetch instead carries `mb_on_disk` (and no percent), + * so the UI shows the working tree materializing rather than freezing. + */ + CloneProgressEvent: { + /** Label */ + label?: string; + /** + * Stage + * @enum {string} + */ + stage?: 'receiving' | 'resolving' | 'counting' | 'updating'; + /** Percent */ + percent?: number; + /** Mb On Disk */ + mb_on_disk?: number; + }; + /** CommitDateRange */ + CommitDateRange: { + /** + * Oldest + * @description Oldest commit date (YYYY-MM-DD), or null when the repo has no commits + */ + oldest: string | null; + /** + * Newest + * @description Newest commit date (YYYY-MM-DD), or null when the repo has no commits + */ + newest: string | null; + }; + /** CommitDetailResponse */ + CommitDetailResponse: { + /** Sha */ + sha: string; + /** Authors */ + authors: string[]; + /** Date */ + date: string; + /** Subject */ + subject: string; + /** Body */ + body: string; }; - responses: never; - parameters: never; - requestBodies: never; - headers: never; - pathItems: never; + /** CommitEntry */ + CommitEntry: { + /** + * Date + * @description ISO-8601 UTC, e.g. 2026-07-25T14:03:21Z + */ + date: string; + /** Files */ + files: number; + /** Sha */ + sha: string; + /** Authors */ + authors: string[]; + /** Subject */ + subject: string; + /** Same Day Total */ + same_day_total: number; + }; + /** CommitLeader */ + CommitLeader: { + /** Sha */ + sha: string; + /** Files */ + files: number; + }; + /** + * CompleteManifestEvent + * @description `manifest-complete` — a manifest with real, fully-populated metadata (a + * fresh scan's final pass, or a warm cache hit). + */ + CompleteManifestEvent: { + manifest: components['schemas']['Manifest']; + }; + /** ConfigResponse */ + ConfigResponse: { + /** Allowlocalrepos */ + allowLocalRepos: boolean; + /** Maxbatchpaths */ + maxBatchPaths: number; + /** Version */ + version: string; + }; + /** DateRangeMs */ + DateRangeMs: { + /** Mincreated */ + minCreated: number; + /** Maxcreated */ + maxCreated: number; + /** Minmodified */ + minModified: number; + /** Maxmodified */ + maxModified: number; + }; + /** DateRanges */ + DateRanges: { + /** + * Mincreated + * @description Earliest resolved create date (ISO), or null for an empty tree + */ + minCreated: string | null; + /** + * Maxcreated + * @description Latest resolved create date (ISO), or null for an empty tree + */ + maxCreated: string | null; + /** + * Minmodified + * @description Earliest resolved modify date (ISO), or null for an empty tree + */ + minModified: string | null; + /** + * Maxmodified + * @description Latest resolved modify date (ISO), or null for an empty tree + */ + maxModified: string | null; + }; + /** DayLeader */ + DayLeader: { + /** Date */ + date: string; + /** Count */ + count: number; + }; + /** DirLeader */ + DirLeader: { + /** Path */ + path: string; + /** Depth */ + depth: number; + /** Children */ + children: number; + /** Descendants */ + descendants: number; + }; + /** DirNode */ + DirNode: { + /** Name */ + name: string; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + type: 'directory'; + /** Path */ + path: string; + /** Fullpath */ + fullPath: string; + /** Children */ + children: (components['schemas']['FileNode'] | components['schemas']['DirNode'])[]; + /** Children Count */ + children_count: number; + /** Children File Count */ + children_file_count: number; + /** Children Dir Count */ + children_dir_count: number; + /** Descendants Count */ + descendants_count: number; + /** Descendants File Count */ + descendants_file_count: number; + /** Descendants Dir Count */ + descendants_dir_count: number; + /** Descendants Size */ + descendants_size: number; + /** Descendants Created Min */ + descendants_created_min: string | null; + /** Descendants Modified Max */ + descendants_modified_max: string | null; + /** Descendants Ext Breakdown */ + descendants_ext_breakdown: components['schemas']['ExtBreakdownEntry'][]; + }; + /** + * ErrorEvent + * @description `error` — a failure after the stream began; carries the message. + */ + ErrorEvent: { + /** Error */ + error: string; + }; + /** ExtBreakdownEntry */ + ExtBreakdownEntry: { + /** Ext */ + ext: string | null; + /** Count */ + count: number; + /** Size */ + size: number; + }; + /** FileLeader */ + FileLeader: { + /** Path */ + path: string; + /** Lines */ + lines: number; + /** Bytes */ + bytes: number; + /** Created */ + created: string; + /** Modified */ + modified: string; + /** Media Width */ + media_width?: number; + /** Media Height */ + media_height?: number; + }; + /** FileNode */ + FileNode: { + /** Name */ + name: string; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + type: 'file'; + /** Path */ + path: string; + /** Fullpath */ + fullPath: string; + /** Extension */ + extension: string; + /** Size */ + size: number; + /** Lines */ + lines: number; + /** Binary */ + binary: boolean; + /** + * Dirty + * @description Working-tree differs from HEAD for this tracked file (staged or unstaged). Always False for clean/remote repos. + */ + dirty: boolean; + /** + * Created + * @description ISO create date (UTC, Z-suffixed), resolved server-side: git history date when the file has one, filesystem date otherwise + */ + created: string; + /** + * Modified + * @description ISO modify date (UTC, Z-suffixed), resolved server-side: git history date when the file has one, filesystem date otherwise. When dirty is true, this is always the working-tree filesystem date, regardless of git history + */ + modified: string; + /** + * Mediakind + * @description Media classification by extension (single source for the frontend); null for non-media files + */ + mediaKind?: ('image' | 'video') | null; + /** Media Width */ + media_width?: number; + /** Media Height */ + media_height?: number; + /** Binarytype */ + binaryType?: string; + }; + /** + * FingerprintEntry + * @description One binary file's byte-pattern fingerprint in a POST /api/fingerprints + * batch response: a base64-encoded grayscale PNG (image/png implied), keyed + * by request path. Computed server-side from the file's head — raw binary + * bytes never ship to the client. + */ + FingerprintEntry: { + /** B64 */ + b64: string; + }; + /** HTTPValidationError */ + HTTPValidationError: { + /** Detail */ + detail?: components['schemas']['ValidationError'][]; + }; + /** HealthResponse */ + HealthResponse: { + /** Ok */ + ok: boolean; + }; + /** + * ImageBatchEntry + * @description One image in a POST /api/images batch response: its content-type and + * base64-encoded bytes, keyed by request path in the response map. + */ + ImageBatchEntry: { + /** Mime */ + mime: string; + /** B64 */ + b64: string; + }; + /** Manifest */ + Manifest: { + /** Root */ + root: string; + /** Scanned At */ + scanned_at: string; + /** Content Signature */ + content_signature: string; + /** Structure Signature */ + structure_signature: string; + /** Layout Signature */ + layout_signature: string; + tree: components['schemas']['DirNode']; + repo: components['schemas']['RepoInfo']; + /** Commits */ + commits: components['schemas']['CommitEntry'][]; + busyness: components['schemas']['BusynessThresholds']; + dateRanges: components['schemas']['DateRanges']; + stats: components['schemas']['RepoStats']; + /** + * Pending + * @description Stages still to come. 'metadata': per-file lines/binary are placeholders. 'history': dates are filesystem dates and commits is empty. Empty list means every field is final. + */ + pending: ('metadata' | 'history')[]; + /** + * Readmepath + * @description Absolute path of the root README, or null if there isn't one + */ + readmePath: string | null; + /** + * Readmemodified + * @description That README's mtime, for cache-busting the fetch + */ + readmeModified: string | null; + }; + /** + * PartialManifestEvent + * @description `manifest-partial` — a manifest with the real tree structure but + * placeholder file metadata, sent so the UI can paint the city before + * per-file metadata is resolved. + */ + PartialManifestEvent: { + manifest: components['schemas']['Manifest']; + }; + /** PathBatchRequest */ + PathBatchRequest: { + /** Paths */ + paths: string[]; + /** Shas */ + shas?: { + [key: string]: string; + } | null; + }; + /** RangeStat */ + RangeStat: { + /** Min */ + min: number; + /** Max */ + max: number; + }; + /** RepoInfo */ + RepoInfo: { + /** Branch */ + branch: string | null; + /** Remote Url */ + remote_url: string | null; + /** Head Sha */ + head_sha: string | null; + /** Head Subject */ + head_subject: string | null; + /** Dirty */ + dirty: boolean; + }; + /** RepoStats */ + RepoStats: { + lineCountRange: components['schemas']['RangeStat']; + byteSizeRange: components['schemas']['RangeStat']; + oldestCreatedFile: components['schemas']['FileLeader'] | null; + newestCreatedFile: components['schemas']['FileLeader'] | null; + newestModifiedFile: components['schemas']['FileLeader'] | null; + oldestModifiedFile: components['schemas']['FileLeader'] | null; + maxLinesFile: components['schemas']['FileLeader'] | null; + minLinesFile: components['schemas']['FileLeader'] | null; + maxBytesFile: components['schemas']['FileLeader'] | null; + minBytesFile: components['schemas']['FileLeader'] | null; + maxMediaBytesFile: components['schemas']['FileLeader'] | null; + minMediaBytesFile: components['schemas']['FileLeader'] | null; + maxMediaPixelsFile: components['schemas']['FileLeader'] | null; + minMediaPixelsFile: components['schemas']['FileLeader'] | null; + maxBinaryBytesFile: components['schemas']['FileLeader'] | null; + minBinaryBytesFile: components['schemas']['FileLeader'] | null; + /** Mediacount */ + mediaCount: number; + /** Binarycount */ + binaryCount: number; + /** Totallines */ + totalLines: number; + /** Dirtyfilecount */ + dirtyFileCount: number; + /** Codebytes */ + codeBytes: number; + maxDepthDir: components['schemas']['DirLeader'] | null; + maxChildrenDir: components['schemas']['DirLeader'] | null; + minChildrenDir: components['schemas']['DirLeader'] | null; + maxFilesPerCommit: components['schemas']['CommitLeader'] | null; + minFilesPerCommit: components['schemas']['CommitLeader'] | null; + commitDates: components['schemas']['CommitDateRange']; + maxCommitsPerDay: components['schemas']['DayLeader'] | null; + /** Maxcommitstreakdays */ + maxCommitStreakDays: number; + /** Authors */ + authors: components['schemas']['AuthorStat'][]; + }; + /** + * ScanProgressEvent + * @description `scan-progress` — the working tree is being walked; carries the + * heartbeat files-scanned count. + */ + ScanProgressEvent: { + /** Label */ + label?: string; + /** Files Scanned */ + files_scanned?: number; + }; + /** SignatureResponse */ + SignatureResponse: { + /** Root */ + root: string; + /** Scanned At */ + scanned_at: string; + /** Content Signature */ + content_signature: string; + }; + /** + * TimelineBundle + * @description Wire schema for the scrub bundle; mirrors manifest_types.TimelineBundle. + */ + TimelineBundle: { + /** Commits */ + commits: components['schemas']['CommitEntry'][]; + unionManifest: components['schemas']['Manifest']; + /** Deltas */ + deltas: components['schemas']['TimelineDelta'][]; + /** Bloblines */ + blobLines: { + [key: string]: number; + }; + /** Blobsizes */ + blobSizes: { + [key: string]: number; + }; + /** Commitlineranges */ + commitLineRanges: components['schemas']['RangeStat'][]; + /** Commitdateranges */ + commitDateRanges: components['schemas']['DateRangeMs'][]; + /** Note */ + note: string | null; + }; + /** TimelineChange */ + TimelineChange: { + /** Path */ + path: string; + /** + * Sha + * @description New blob sha, or null when deleted + */ + sha: string | null; + }; + /** + * TimelineCompleteEvent + * @description `timeline-complete` — the full replay bundle (fresh build or warm + * cache hit). + */ + TimelineCompleteEvent: { + bundle: components['schemas']['TimelineBundle']; + }; + /** TimelineDelta */ + TimelineDelta: { + /** Sha */ + sha: string; + /** Changes */ + changes: components['schemas']['TimelineChange'][]; + }; + /** + * TimelineProgressEvent + * @description `timeline-progress` — the history walk, blob-table resolution, or (for a + * blobless remote clone) the up-front blob backfill is in progress. The + * `fetch` stage carries `percent`; `history` carries `commits`; `blobs` + * carries `blobsDone`/`blobsTotal` (the total is known up front from the batch + * blob lookup, so that stage reports two ticks, not a live stream). + */ + TimelineProgressEvent: { + /** + * Stage + * @enum {string} + */ + stage: 'fetch' | 'history' | 'blobs'; + /** Percent */ + percent?: number; + /** Commits */ + commits?: number; + /** Blobsdone */ + blobsDone?: number; + /** Blobstotal */ + blobsTotal?: number; + /** Label */ + label?: string; + }; + /** ValidationError */ + ValidationError: { + /** Location */ + loc: (string | number)[]; + /** Message */ + msg: string; + /** Error Type */ + type: string; + /** Input */ + input?: unknown; + /** Context */ + ctx?: Record; + }; + }; + responses: never; + parameters: never; + requestBodies: never; + headers: never; + pathItems: never; } export type $defs = Record; export interface operations { - health_api_health_get: { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; - }; - requestBody?: never; - responses: { - /** @description Successful Response */ - 200: { - headers: { - [name: string]: unknown; - }; - content: { - "application/json": components["schemas"]["HealthResponse"]; - }; - }; - }; + health_api_health_get: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; }; - config_api_config_get: { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; }; - requestBody?: never; - responses: { - /** @description Successful Response */ - 200: { - headers: { - [name: string]: unknown; - }; - content: { - "application/json": components["schemas"]["ConfigResponse"]; - }; - }; + content: { + 'application/json': components['schemas']['HealthResponse']; }; + }; }; - get_file_api_file_get: { - parameters: { - query: { - /** @description Absolute path inside a scanned root */ - path: string; - /** @description Blob sha to read instead of the working tree */ - sha?: string | null; - }; - header?: never; - path?: never; - cookie?: never; - }; - requestBody?: never; - responses: { - /** @description Successful Response */ - 200: { - headers: { - [name: string]: unknown; - }; - content: { - "application/json": unknown; - }; - }; - /** @description Validation Error */ - 422: { - headers: { - [name: string]: unknown; - }; - content: { - "application/json": components["schemas"]["HTTPValidationError"]; - }; - }; - }; + }; + config_api_config_get: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; }; - get_images_api_images_post: { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; }; - requestBody: { - content: { - "application/json": components["schemas"]["PathBatchRequest"]; - }; - }; - responses: { - /** @description Successful Response */ - 200: { - headers: { - [name: string]: unknown; - }; - content: { - "application/json": { - [key: string]: components["schemas"]["ImageBatchEntry"]; - }; - }; - }; - /** @description Validation Error */ - 422: { - headers: { - [name: string]: unknown; - }; - content: { - "application/json": components["schemas"]["HTTPValidationError"]; - }; - }; + content: { + 'application/json': components['schemas']['ConfigResponse']; }; + }; }; - get_fingerprints_api_fingerprints_post: { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; - }; - requestBody: { - content: { - "application/json": components["schemas"]["PathBatchRequest"]; - }; - }; - responses: { - /** @description Successful Response */ - 200: { - headers: { - [name: string]: unknown; - }; - content: { - "application/json": { - [key: string]: components["schemas"]["FingerprintEntry"]; - }; - }; - }; - /** @description Validation Error */ - 422: { - headers: { - [name: string]: unknown; - }; - content: { - "application/json": components["schemas"]["HTTPValidationError"]; - }; - }; - }; + }; + get_file_api_file_get: { + parameters: { + query: { + /** @description Absolute path inside a scanned root */ + path: string; + /** @description Blob sha to read instead of the working tree */ + sha?: string | null; + }; + header?: never; + path?: never; + cookie?: never; }; - get_commit_api_commit_get: { - parameters: { - query: { - sha: string; - }; - header?: never; - path?: never; - cookie?: never; - }; - requestBody?: never; - responses: { - /** @description Successful Response */ - 200: { - headers: { - [name: string]: unknown; - }; - content: { - "application/json": components["schemas"]["CommitDetailResponse"]; - }; - }; - /** @description Validation Error */ - 422: { - headers: { - [name: string]: unknown; - }; - content: { - "application/json": components["schemas"]["HTTPValidationError"]; - }; - }; - }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': unknown; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; }; - get_branches_api_branches_get: { - parameters: { - query: { - src: string; - }; - header?: never; - path?: never; - cookie?: never; - }; - requestBody?: never; - responses: { - /** @description Successful Response */ - 200: { - headers: { - [name: string]: unknown; - }; - content: { - "application/json": components["schemas"]["BranchListResponse"]; - }; - }; - /** @description Validation Error */ - 422: { - headers: { - [name: string]: unknown; - }; - content: { - "application/json": components["schemas"]["HTTPValidationError"]; - }; - }; - }; + }; + get_images_api_images_post: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; }; - signature_api_manifest_signature_get: { - parameters: { - query: { - src: string; - branch?: string | null; - no_cache?: boolean; - exclude?: string[]; - }; - header?: never; - path?: never; - cookie?: never; - }; - requestBody?: never; - responses: { - /** @description Successful Response */ - 200: { - headers: { - [name: string]: unknown; - }; - content: { - "application/json": components["schemas"]["SignatureResponse"]; - }; - }; - /** @description Validation Error */ - 422: { - headers: { - [name: string]: unknown; - }; - content: { - "application/json": components["schemas"]["HTTPValidationError"]; - }; - }; - }; + requestBody: { + content: { + 'application/json': components['schemas']['PathBatchRequest']; + }; }; - timeline_api_timeline_get: { - parameters: { - query: { - src: string; - branch?: string | null; - no_cache?: boolean; - exclude?: string[]; - }; - header?: never; - path?: never; - cookie?: never; - }; - requestBody?: never; - responses: { - /** @description Server-Sent Events stream (`text/event-stream`). Named events and their JSON `data` payloads: `timeline-progress` (TimelineProgressEvent, one or more while the history walk / blob resolution run), `timeline-complete` (TimelineCompleteEvent, the full bundle), `error` (ErrorEvent). A warm cache hit emits only `timeline-complete`, no progress. The client closes the connection on `timeline-complete`/`error`. */ - 200: { - headers: { - [name: string]: unknown; - }; - content: { - "application/json": components["schemas"]["TimelineProgressEvent"] | components["schemas"]["TimelineCompleteEvent"] | components["schemas"]["ErrorEvent"]; - }; - }; - /** @description Validation Error */ - 422: { - headers: { - [name: string]: unknown; - }; - content: { - "application/json": components["schemas"]["HTTPValidationError"]; - }; - }; - }; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': { + [key: string]: components['schemas']['ImageBatchEntry']; + }; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; }; - manifest_api_manifest_get: { - parameters: { - query?: { - src?: string; - branch?: string | null; - no_cache?: boolean; - exclude?: string[]; - ref?: string | null; - }; - header?: never; - path?: never; - cookie?: never; - }; - requestBody?: never; - responses: { - /** @description Server-Sent Events stream (`text/event-stream`). Named events and their JSON `data` payloads: `clone-progress` (CloneProgressEvent), `scan-progress` (ScanProgressEvent), `manifest-partial` (PartialManifestEvent), `manifest-complete` (CompleteManifestEvent), `error` (ErrorEvent). The client closes the connection on `manifest-complete`/`error`. When `ref` is set, the manifest is reconstructed as of that commit instead of the working tree (a remote source still emits `clone-progress` if it isn't cloned yet, but never `scan-progress`/`manifest-partial` for the reconstruction itself — the city is already drawn, so a skeleton would flash placeholders). */ - 200: { - headers: { - [name: string]: unknown; - }; - content: { - "application/json": components["schemas"]["CloneProgressEvent"] | components["schemas"]["ScanProgressEvent"] | components["schemas"]["PartialManifestEvent"] | components["schemas"]["CompleteManifestEvent"] | components["schemas"]["ErrorEvent"]; - }; - }; - /** @description Validation Error */ - 422: { - headers: { - [name: string]: unknown; - }; - content: { - "application/json": components["schemas"]["HTTPValidationError"]; - }; - }; - }; + }; + get_fingerprints_api_fingerprints_post: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody: { + content: { + 'application/json': components['schemas']['PathBatchRequest']; + }; + }; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': { + [key: string]: components['schemas']['FingerprintEntry']; + }; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + get_commit_api_commit_get: { + parameters: { + query: { + sha: string; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['CommitDetailResponse']; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + get_branches_api_branches_get: { + parameters: { + query: { + src: string; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['BranchListResponse']; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + signature_api_manifest_signature_get: { + parameters: { + query: { + src: string; + branch?: string | null; + no_cache?: boolean; + exclude?: string[]; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['SignatureResponse']; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + timeline_api_timeline_get: { + parameters: { + query: { + src: string; + branch?: string | null; + no_cache?: boolean; + exclude?: string[]; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Server-Sent Events stream (`text/event-stream`). Named events and their JSON `data` payloads: `timeline-progress` (TimelineProgressEvent, one or more while the history walk / blob resolution run), `timeline-complete` (TimelineCompleteEvent, the full bundle), `error` (ErrorEvent). A warm cache hit emits only `timeline-complete`, no progress. The client closes the connection on `timeline-complete`/`error`. */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': + | components['schemas']['TimelineProgressEvent'] + | components['schemas']['TimelineCompleteEvent'] + | components['schemas']['ErrorEvent']; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + manifest_api_manifest_get: { + parameters: { + query?: { + src?: string; + branch?: string | null; + no_cache?: boolean; + exclude?: string[]; + ref?: string | null; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Server-Sent Events stream (`text/event-stream`). Named events and their JSON `data` payloads: `clone-progress` (CloneProgressEvent), `scan-progress` (ScanProgressEvent), `manifest-partial` (PartialManifestEvent), `manifest-complete` (CompleteManifestEvent), `error` (ErrorEvent). The client closes the connection on `manifest-complete`/`error`. When `ref` is set, the manifest is reconstructed as of that commit instead of the working tree (a remote source still emits `clone-progress` if it isn't cloned yet, but never `scan-progress`/`manifest-partial` for the reconstruction itself — the city is already drawn, so a skeleton would flash placeholders). */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': + | components['schemas']['CloneProgressEvent'] + | components['schemas']['ScanProgressEvent'] + | components['schemas']['PartialManifestEvent'] + | components['schemas']['CompleteManifestEvent'] + | components['schemas']['ErrorEvent']; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; }; + }; } diff --git a/app/tests/api/config.test.ts b/app/tests/api/config.test.ts index 3f8cba55..9e8e62a6 100644 --- a/app/tests/api/config.test.ts +++ b/app/tests/api/config.test.ts @@ -59,6 +59,22 @@ describe('fetchServerConfig', () => { const cfg = await fetchServerConfig(); expect(cfg.maxBatchPaths).toBe(DEFAULT_SERVER_CONFIG.maxBatchPaths); }); + + it('carries the version through from the server', async () => { + vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce( + new Response(JSON.stringify({ allowLocalRepos: false, version: '1.3.0' }), { status: 200 }) + ); + const cfg = await fetchServerConfig(); + expect(cfg.version).toBe('1.3.0'); + }); + + it('keeps the unknown-version default when the server omits it', async () => { + vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce( + new Response(JSON.stringify({ allowLocalRepos: false }), { status: 200 }) + ); + const cfg = await fetchServerConfig(); + expect(cfg.version).toBe('0.0.0+unknown'); + }); }); describe('getServerConfig', () => { diff --git a/app/tests/api/pathBatcher.test.ts b/app/tests/api/pathBatcher.test.ts index 973adf3b..21f76bba 100644 --- a/app/tests/api/pathBatcher.test.ts +++ b/app/tests/api/pathBatcher.test.ts @@ -6,7 +6,7 @@ import { createPathBatcher } from '@/api/pathBatcher'; import { serverConfigNow } from '@/api/config'; vi.mock('@/api/config', () => ({ - serverConfigNow: vi.fn(() => ({ allowLocalRepos: false, maxBatchPaths: 3 })), + serverConfigNow: vi.fn(() => ({ allowLocalRepos: false, maxBatchPaths: 3, version: '1.0.0' })), })); interface Entry { @@ -67,7 +67,11 @@ describe('createPathBatcher', () => { it('re-reads the cap per flush, so a config that arrives late is honoured', async () => { const bodies = mockFetch(echo); - vi.mocked(serverConfigNow).mockReturnValueOnce({ allowLocalRepos: false, maxBatchPaths: 2 }); + vi.mocked(serverConfigNow).mockReturnValueOnce({ + allowLocalRepos: false, + maxBatchPaths: 2, + version: '1.0.0', + }); const batcher = makeBatcher(); const all = Promise.all(['a', 'b', 'c'].map((p) => batcher.request(p))); await vi.runAllTimersAsync(); From 8c2a0a07f3348006098298869d65844b812d05bd Mon Sep 17 00:00:00 2001 From: Thalida Noel Date: Sat, 8 Aug 2026 18:05:26 -0400 Subject: [PATCH 02/19] fix: don't prettier-format manifest.generated.ts app/.prettierignore excludes this file (auto-generated by openapi-typescript, prettier --write from the repo root skipped that ignore file since it isn't at the repo root). Regenerate to restore raw openapi-typescript output. --- app/src/types/manifest.generated.ts | 2058 +++++++++++++-------------- 1 file changed, 1025 insertions(+), 1033 deletions(-) diff --git a/app/src/types/manifest.generated.ts b/app/src/types/manifest.generated.ts index c2d5abf0..0e36f0ec 100644 --- a/app/src/types/manifest.generated.ts +++ b/app/src/types/manifest.generated.ts @@ -4,1059 +4,1051 @@ */ export interface paths { - '/api/health': { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; - }; - /** Health */ - get: operations['health_api_health_get']; - put?: never; - post?: never; - delete?: never; - options?: never; - head?: never; - patch?: never; - trace?: never; - }; - '/api/config': { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; - }; - /** Config */ - get: operations['config_api_config_get']; - put?: never; - post?: never; - delete?: never; - options?: never; - head?: never; - patch?: never; - trace?: never; - }; - '/api/file': { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; - }; - /** Get File */ - get: operations['get_file_api_file_get']; - put?: never; - post?: never; - delete?: never; - options?: never; - head?: never; - patch?: never; - trace?: never; - }; - '/api/images': { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; - }; - get?: never; - put?: never; - /** - * Get Images - * @description Batch image fetch — {path: {mime, b64}} for many small images in one round - * trip. NOT a plural of GET /api/file: it inlines base64, serves images only, - * and omits anything it can't serve. It exists so the scene's billboard loader - * doesn't exhaust the browser's HTTP/1.1 connection pool on a media-heavy repo. - * - * Each path is trust-checked exactly like GET /api/file. Paths that are out of - * root, missing, non-image, or larger than _MAX_BATCH_IMAGE_BYTES are silently - * omitted; the client falls back to the streaming GET for those. Videos are - * never batched (they stream their poster frame), so this is images only. - */ - post: operations['get_images_api_images_post']; - delete?: never; - options?: never; - head?: never; - patch?: never; - trace?: never; - }; - '/api/fingerprints': { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; - }; - get?: never; - put?: never; - /** - * Get Fingerprints - * @description Batch byte-pattern fingerprint fetch — {path: {b64}}, one round trip for - * many buildings. Trust-checked like GET /api/file; out-of-root / missing / - * unreadable paths are silently omitted. Raw binary bytes never leave the - * server — only the head is read, and only the fingerprint image returned. - */ - post: operations['get_fingerprints_api_fingerprints_post']; - delete?: never; - options?: never; - head?: never; - patch?: never; - trace?: never; - }; - '/api/commit': { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; - }; - /** Get Commit */ - get: operations['get_commit_api_commit_get']; - put?: never; - post?: never; - delete?: never; - options?: never; - head?: never; - patch?: never; - trace?: never; - }; - '/api/branches': { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; - }; - /** Get Branches */ - get: operations['get_branches_api_branches_get']; - put?: never; - post?: never; - delete?: never; - options?: never; - head?: never; - patch?: never; - trace?: never; - }; - '/api/manifest/signature': { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; - }; - /** Signature */ - get: operations['signature_api_manifest_signature_get']; - put?: never; - post?: never; - delete?: never; - options?: never; - head?: never; - patch?: never; - trace?: never; - }; - '/api/timeline': { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; - }; - /** Timeline */ - get: operations['timeline_api_timeline_get']; - put?: never; - post?: never; - delete?: never; - options?: never; - head?: never; - patch?: never; - trace?: never; - }; - '/api/manifest': { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; + "/api/health": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** Health */ + get: operations["health_api_health_get"]; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/api/config": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** Config */ + get: operations["config_api_config_get"]; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/api/file": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** Get File */ + get: operations["get_file_api_file_get"]; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/api/images": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put?: never; + /** + * Get Images + * @description Batch image fetch — {path: {mime, b64}} for many small images in one round + * trip. NOT a plural of GET /api/file: it inlines base64, serves images only, + * and omits anything it can't serve. It exists so the scene's billboard loader + * doesn't exhaust the browser's HTTP/1.1 connection pool on a media-heavy repo. + * + * Each path is trust-checked exactly like GET /api/file. Paths that are out of + * root, missing, non-image, or larger than _MAX_BATCH_IMAGE_BYTES are silently + * omitted; the client falls back to the streaming GET for those. Videos are + * never batched (they stream their poster frame), so this is images only. + */ + post: operations["get_images_api_images_post"]; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/api/fingerprints": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put?: never; + /** + * Get Fingerprints + * @description Batch byte-pattern fingerprint fetch — {path: {b64}}, one round trip for + * many buildings. Trust-checked like GET /api/file; out-of-root / missing / + * unreadable paths are silently omitted. Raw binary bytes never leave the + * server — only the head is read, and only the fingerprint image returned. + */ + post: operations["get_fingerprints_api_fingerprints_post"]; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/api/commit": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** Get Commit */ + get: operations["get_commit_api_commit_get"]; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/api/branches": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** Get Branches */ + get: operations["get_branches_api_branches_get"]; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/api/manifest/signature": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** Signature */ + get: operations["signature_api_manifest_signature_get"]; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/api/timeline": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** Timeline */ + get: operations["timeline_api_timeline_get"]; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/api/manifest": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** Manifest */ + get: operations["manifest_api_manifest_get"]; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; }; - /** Manifest */ - get: operations['manifest_api_manifest_get']; - put?: never; - post?: never; - delete?: never; - options?: never; - head?: never; - patch?: never; - trace?: never; - }; } export type webhooks = Record; export interface components { - schemas: { - /** AuthorStat */ - AuthorStat: { - /** Name */ - name: string; - /** Commits */ - commits: number; - /** - * Hue - * @description Stable 0-359 hue from the name hash; the display colour is built from it client-side - */ - hue: number; - }; - /** BranchListResponse */ - BranchListResponse: { - /** Branches */ - branches: string[]; - /** Default */ - default: string | null; - }; - /** BusynessThresholds */ - BusynessThresholds: { - /** Avg */ - avg: number; - /** Busy */ - busy: number; - }; - /** - * CloneProgressEvent - * @description `clone-progress` — git source is being cloned; carries clone progress. - * - * A normal progress tick has `stage` + `percent`. A heartbeat during the - * silent promisor blob fetch instead carries `mb_on_disk` (and no percent), - * so the UI shows the working tree materializing rather than freezing. - */ - CloneProgressEvent: { - /** Label */ - label?: string; - /** - * Stage - * @enum {string} - */ - stage?: 'receiving' | 'resolving' | 'counting' | 'updating'; - /** Percent */ - percent?: number; - /** Mb On Disk */ - mb_on_disk?: number; - }; - /** CommitDateRange */ - CommitDateRange: { - /** - * Oldest - * @description Oldest commit date (YYYY-MM-DD), or null when the repo has no commits - */ - oldest: string | null; - /** - * Newest - * @description Newest commit date (YYYY-MM-DD), or null when the repo has no commits - */ - newest: string | null; - }; - /** CommitDetailResponse */ - CommitDetailResponse: { - /** Sha */ - sha: string; - /** Authors */ - authors: string[]; - /** Date */ - date: string; - /** Subject */ - subject: string; - /** Body */ - body: string; - }; - /** CommitEntry */ - CommitEntry: { - /** - * Date - * @description ISO-8601 UTC, e.g. 2026-07-25T14:03:21Z - */ - date: string; - /** Files */ - files: number; - /** Sha */ - sha: string; - /** Authors */ - authors: string[]; - /** Subject */ - subject: string; - /** Same Day Total */ - same_day_total: number; - }; - /** CommitLeader */ - CommitLeader: { - /** Sha */ - sha: string; - /** Files */ - files: number; - }; - /** - * CompleteManifestEvent - * @description `manifest-complete` — a manifest with real, fully-populated metadata (a - * fresh scan's final pass, or a warm cache hit). - */ - CompleteManifestEvent: { - manifest: components['schemas']['Manifest']; - }; - /** ConfigResponse */ - ConfigResponse: { - /** Allowlocalrepos */ - allowLocalRepos: boolean; - /** Maxbatchpaths */ - maxBatchPaths: number; - /** Version */ - version: string; - }; - /** DateRangeMs */ - DateRangeMs: { - /** Mincreated */ - minCreated: number; - /** Maxcreated */ - maxCreated: number; - /** Minmodified */ - minModified: number; - /** Maxmodified */ - maxModified: number; - }; - /** DateRanges */ - DateRanges: { - /** - * Mincreated - * @description Earliest resolved create date (ISO), or null for an empty tree - */ - minCreated: string | null; - /** - * Maxcreated - * @description Latest resolved create date (ISO), or null for an empty tree - */ - maxCreated: string | null; - /** - * Minmodified - * @description Earliest resolved modify date (ISO), or null for an empty tree - */ - minModified: string | null; - /** - * Maxmodified - * @description Latest resolved modify date (ISO), or null for an empty tree - */ - maxModified: string | null; - }; - /** DayLeader */ - DayLeader: { - /** Date */ - date: string; - /** Count */ - count: number; - }; - /** DirLeader */ - DirLeader: { - /** Path */ - path: string; - /** Depth */ - depth: number; - /** Children */ - children: number; - /** Descendants */ - descendants: number; - }; - /** DirNode */ - DirNode: { - /** Name */ - name: string; - /** - * @description discriminator enum property added by openapi-typescript - * @enum {string} - */ - type: 'directory'; - /** Path */ - path: string; - /** Fullpath */ - fullPath: string; - /** Children */ - children: (components['schemas']['FileNode'] | components['schemas']['DirNode'])[]; - /** Children Count */ - children_count: number; - /** Children File Count */ - children_file_count: number; - /** Children Dir Count */ - children_dir_count: number; - /** Descendants Count */ - descendants_count: number; - /** Descendants File Count */ - descendants_file_count: number; - /** Descendants Dir Count */ - descendants_dir_count: number; - /** Descendants Size */ - descendants_size: number; - /** Descendants Created Min */ - descendants_created_min: string | null; - /** Descendants Modified Max */ - descendants_modified_max: string | null; - /** Descendants Ext Breakdown */ - descendants_ext_breakdown: components['schemas']['ExtBreakdownEntry'][]; - }; - /** - * ErrorEvent - * @description `error` — a failure after the stream began; carries the message. - */ - ErrorEvent: { - /** Error */ - error: string; - }; - /** ExtBreakdownEntry */ - ExtBreakdownEntry: { - /** Ext */ - ext: string | null; - /** Count */ - count: number; - /** Size */ - size: number; - }; - /** FileLeader */ - FileLeader: { - /** Path */ - path: string; - /** Lines */ - lines: number; - /** Bytes */ - bytes: number; - /** Created */ - created: string; - /** Modified */ - modified: string; - /** Media Width */ - media_width?: number; - /** Media Height */ - media_height?: number; - }; - /** FileNode */ - FileNode: { - /** Name */ - name: string; - /** - * @description discriminator enum property added by openapi-typescript - * @enum {string} - */ - type: 'file'; - /** Path */ - path: string; - /** Fullpath */ - fullPath: string; - /** Extension */ - extension: string; - /** Size */ - size: number; - /** Lines */ - lines: number; - /** Binary */ - binary: boolean; - /** - * Dirty - * @description Working-tree differs from HEAD for this tracked file (staged or unstaged). Always False for clean/remote repos. - */ - dirty: boolean; - /** - * Created - * @description ISO create date (UTC, Z-suffixed), resolved server-side: git history date when the file has one, filesystem date otherwise - */ - created: string; - /** - * Modified - * @description ISO modify date (UTC, Z-suffixed), resolved server-side: git history date when the file has one, filesystem date otherwise. When dirty is true, this is always the working-tree filesystem date, regardless of git history - */ - modified: string; - /** - * Mediakind - * @description Media classification by extension (single source for the frontend); null for non-media files - */ - mediaKind?: ('image' | 'video') | null; - /** Media Width */ - media_width?: number; - /** Media Height */ - media_height?: number; - /** Binarytype */ - binaryType?: string; - }; - /** - * FingerprintEntry - * @description One binary file's byte-pattern fingerprint in a POST /api/fingerprints - * batch response: a base64-encoded grayscale PNG (image/png implied), keyed - * by request path. Computed server-side from the file's head — raw binary - * bytes never ship to the client. - */ - FingerprintEntry: { - /** B64 */ - b64: string; - }; - /** HTTPValidationError */ - HTTPValidationError: { - /** Detail */ - detail?: components['schemas']['ValidationError'][]; - }; - /** HealthResponse */ - HealthResponse: { - /** Ok */ - ok: boolean; - }; - /** - * ImageBatchEntry - * @description One image in a POST /api/images batch response: its content-type and - * base64-encoded bytes, keyed by request path in the response map. - */ - ImageBatchEntry: { - /** Mime */ - mime: string; - /** B64 */ - b64: string; - }; - /** Manifest */ - Manifest: { - /** Root */ - root: string; - /** Scanned At */ - scanned_at: string; - /** Content Signature */ - content_signature: string; - /** Structure Signature */ - structure_signature: string; - /** Layout Signature */ - layout_signature: string; - tree: components['schemas']['DirNode']; - repo: components['schemas']['RepoInfo']; - /** Commits */ - commits: components['schemas']['CommitEntry'][]; - busyness: components['schemas']['BusynessThresholds']; - dateRanges: components['schemas']['DateRanges']; - stats: components['schemas']['RepoStats']; - /** - * Pending - * @description Stages still to come. 'metadata': per-file lines/binary are placeholders. 'history': dates are filesystem dates and commits is empty. Empty list means every field is final. - */ - pending: ('metadata' | 'history')[]; - /** - * Readmepath - * @description Absolute path of the root README, or null if there isn't one - */ - readmePath: string | null; - /** - * Readmemodified - * @description That README's mtime, for cache-busting the fetch - */ - readmeModified: string | null; - }; - /** - * PartialManifestEvent - * @description `manifest-partial` — a manifest with the real tree structure but - * placeholder file metadata, sent so the UI can paint the city before - * per-file metadata is resolved. - */ - PartialManifestEvent: { - manifest: components['schemas']['Manifest']; - }; - /** PathBatchRequest */ - PathBatchRequest: { - /** Paths */ - paths: string[]; - /** Shas */ - shas?: { - [key: string]: string; - } | null; - }; - /** RangeStat */ - RangeStat: { - /** Min */ - min: number; - /** Max */ - max: number; - }; - /** RepoInfo */ - RepoInfo: { - /** Branch */ - branch: string | null; - /** Remote Url */ - remote_url: string | null; - /** Head Sha */ - head_sha: string | null; - /** Head Subject */ - head_subject: string | null; - /** Dirty */ - dirty: boolean; - }; - /** RepoStats */ - RepoStats: { - lineCountRange: components['schemas']['RangeStat']; - byteSizeRange: components['schemas']['RangeStat']; - oldestCreatedFile: components['schemas']['FileLeader'] | null; - newestCreatedFile: components['schemas']['FileLeader'] | null; - newestModifiedFile: components['schemas']['FileLeader'] | null; - oldestModifiedFile: components['schemas']['FileLeader'] | null; - maxLinesFile: components['schemas']['FileLeader'] | null; - minLinesFile: components['schemas']['FileLeader'] | null; - maxBytesFile: components['schemas']['FileLeader'] | null; - minBytesFile: components['schemas']['FileLeader'] | null; - maxMediaBytesFile: components['schemas']['FileLeader'] | null; - minMediaBytesFile: components['schemas']['FileLeader'] | null; - maxMediaPixelsFile: components['schemas']['FileLeader'] | null; - minMediaPixelsFile: components['schemas']['FileLeader'] | null; - maxBinaryBytesFile: components['schemas']['FileLeader'] | null; - minBinaryBytesFile: components['schemas']['FileLeader'] | null; - /** Mediacount */ - mediaCount: number; - /** Binarycount */ - binaryCount: number; - /** Totallines */ - totalLines: number; - /** Dirtyfilecount */ - dirtyFileCount: number; - /** Codebytes */ - codeBytes: number; - maxDepthDir: components['schemas']['DirLeader'] | null; - maxChildrenDir: components['schemas']['DirLeader'] | null; - minChildrenDir: components['schemas']['DirLeader'] | null; - maxFilesPerCommit: components['schemas']['CommitLeader'] | null; - minFilesPerCommit: components['schemas']['CommitLeader'] | null; - commitDates: components['schemas']['CommitDateRange']; - maxCommitsPerDay: components['schemas']['DayLeader'] | null; - /** Maxcommitstreakdays */ - maxCommitStreakDays: number; - /** Authors */ - authors: components['schemas']['AuthorStat'][]; - }; - /** - * ScanProgressEvent - * @description `scan-progress` — the working tree is being walked; carries the - * heartbeat files-scanned count. - */ - ScanProgressEvent: { - /** Label */ - label?: string; - /** Files Scanned */ - files_scanned?: number; - }; - /** SignatureResponse */ - SignatureResponse: { - /** Root */ - root: string; - /** Scanned At */ - scanned_at: string; - /** Content Signature */ - content_signature: string; - }; - /** - * TimelineBundle - * @description Wire schema for the scrub bundle; mirrors manifest_types.TimelineBundle. - */ - TimelineBundle: { - /** Commits */ - commits: components['schemas']['CommitEntry'][]; - unionManifest: components['schemas']['Manifest']; - /** Deltas */ - deltas: components['schemas']['TimelineDelta'][]; - /** Bloblines */ - blobLines: { - [key: string]: number; - }; - /** Blobsizes */ - blobSizes: { - [key: string]: number; - }; - /** Commitlineranges */ - commitLineRanges: components['schemas']['RangeStat'][]; - /** Commitdateranges */ - commitDateRanges: components['schemas']['DateRangeMs'][]; - /** Note */ - note: string | null; - }; - /** TimelineChange */ - TimelineChange: { - /** Path */ - path: string; - /** - * Sha - * @description New blob sha, or null when deleted - */ - sha: string | null; - }; - /** - * TimelineCompleteEvent - * @description `timeline-complete` — the full replay bundle (fresh build or warm - * cache hit). - */ - TimelineCompleteEvent: { - bundle: components['schemas']['TimelineBundle']; - }; - /** TimelineDelta */ - TimelineDelta: { - /** Sha */ - sha: string; - /** Changes */ - changes: components['schemas']['TimelineChange'][]; - }; - /** - * TimelineProgressEvent - * @description `timeline-progress` — the history walk, blob-table resolution, or (for a - * blobless remote clone) the up-front blob backfill is in progress. The - * `fetch` stage carries `percent`; `history` carries `commits`; `blobs` - * carries `blobsDone`/`blobsTotal` (the total is known up front from the batch - * blob lookup, so that stage reports two ticks, not a live stream). - */ - TimelineProgressEvent: { - /** - * Stage - * @enum {string} - */ - stage: 'fetch' | 'history' | 'blobs'; - /** Percent */ - percent?: number; - /** Commits */ - commits?: number; - /** Blobsdone */ - blobsDone?: number; - /** Blobstotal */ - blobsTotal?: number; - /** Label */ - label?: string; - }; - /** ValidationError */ - ValidationError: { - /** Location */ - loc: (string | number)[]; - /** Message */ - msg: string; - /** Error Type */ - type: string; - /** Input */ - input?: unknown; - /** Context */ - ctx?: Record; + schemas: { + /** AuthorStat */ + AuthorStat: { + /** Name */ + name: string; + /** Commits */ + commits: number; + /** + * Hue + * @description Stable 0-359 hue from the name hash; the display colour is built from it client-side + */ + hue: number; + }; + /** BranchListResponse */ + BranchListResponse: { + /** Branches */ + branches: string[]; + /** Default */ + default: string | null; + }; + /** BusynessThresholds */ + BusynessThresholds: { + /** Avg */ + avg: number; + /** Busy */ + busy: number; + }; + /** + * CloneProgressEvent + * @description `clone-progress` — git source is being cloned; carries clone progress. + * + * A normal progress tick has `stage` + `percent`. A heartbeat during the + * silent promisor blob fetch instead carries `mb_on_disk` (and no percent), + * so the UI shows the working tree materializing rather than freezing. + */ + CloneProgressEvent: { + /** Label */ + label?: string; + /** + * Stage + * @enum {string} + */ + stage?: "receiving" | "resolving" | "counting" | "updating"; + /** Percent */ + percent?: number; + /** Mb On Disk */ + mb_on_disk?: number; + }; + /** CommitDateRange */ + CommitDateRange: { + /** + * Oldest + * @description Oldest commit date (YYYY-MM-DD), or null when the repo has no commits + */ + oldest: string | null; + /** + * Newest + * @description Newest commit date (YYYY-MM-DD), or null when the repo has no commits + */ + newest: string | null; + }; + /** CommitDetailResponse */ + CommitDetailResponse: { + /** Sha */ + sha: string; + /** Authors */ + authors: string[]; + /** Date */ + date: string; + /** Subject */ + subject: string; + /** Body */ + body: string; + }; + /** CommitEntry */ + CommitEntry: { + /** + * Date + * @description ISO-8601 UTC, e.g. 2026-07-25T14:03:21Z + */ + date: string; + /** Files */ + files: number; + /** Sha */ + sha: string; + /** Authors */ + authors: string[]; + /** Subject */ + subject: string; + /** Same Day Total */ + same_day_total: number; + }; + /** CommitLeader */ + CommitLeader: { + /** Sha */ + sha: string; + /** Files */ + files: number; + }; + /** + * CompleteManifestEvent + * @description `manifest-complete` — a manifest with real, fully-populated metadata (a + * fresh scan's final pass, or a warm cache hit). + */ + CompleteManifestEvent: { + manifest: components["schemas"]["Manifest"]; + }; + /** ConfigResponse */ + ConfigResponse: { + /** Allowlocalrepos */ + allowLocalRepos: boolean; + /** Maxbatchpaths */ + maxBatchPaths: number; + /** Version */ + version: string; + }; + /** DateRangeMs */ + DateRangeMs: { + /** Mincreated */ + minCreated: number; + /** Maxcreated */ + maxCreated: number; + /** Minmodified */ + minModified: number; + /** Maxmodified */ + maxModified: number; + }; + /** DateRanges */ + DateRanges: { + /** + * Mincreated + * @description Earliest resolved create date (ISO), or null for an empty tree + */ + minCreated: string | null; + /** + * Maxcreated + * @description Latest resolved create date (ISO), or null for an empty tree + */ + maxCreated: string | null; + /** + * Minmodified + * @description Earliest resolved modify date (ISO), or null for an empty tree + */ + minModified: string | null; + /** + * Maxmodified + * @description Latest resolved modify date (ISO), or null for an empty tree + */ + maxModified: string | null; + }; + /** DayLeader */ + DayLeader: { + /** Date */ + date: string; + /** Count */ + count: number; + }; + /** DirLeader */ + DirLeader: { + /** Path */ + path: string; + /** Depth */ + depth: number; + /** Children */ + children: number; + /** Descendants */ + descendants: number; + }; + /** DirNode */ + DirNode: { + /** Name */ + name: string; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + type: "directory"; + /** Path */ + path: string; + /** Fullpath */ + fullPath: string; + /** Children */ + children: (components["schemas"]["FileNode"] | components["schemas"]["DirNode"])[]; + /** Children Count */ + children_count: number; + /** Children File Count */ + children_file_count: number; + /** Children Dir Count */ + children_dir_count: number; + /** Descendants Count */ + descendants_count: number; + /** Descendants File Count */ + descendants_file_count: number; + /** Descendants Dir Count */ + descendants_dir_count: number; + /** Descendants Size */ + descendants_size: number; + /** Descendants Created Min */ + descendants_created_min: string | null; + /** Descendants Modified Max */ + descendants_modified_max: string | null; + /** Descendants Ext Breakdown */ + descendants_ext_breakdown: components["schemas"]["ExtBreakdownEntry"][]; + }; + /** + * ErrorEvent + * @description `error` — a failure after the stream began; carries the message. + */ + ErrorEvent: { + /** Error */ + error: string; + }; + /** ExtBreakdownEntry */ + ExtBreakdownEntry: { + /** Ext */ + ext: string | null; + /** Count */ + count: number; + /** Size */ + size: number; + }; + /** FileLeader */ + FileLeader: { + /** Path */ + path: string; + /** Lines */ + lines: number; + /** Bytes */ + bytes: number; + /** Created */ + created: string; + /** Modified */ + modified: string; + /** Media Width */ + media_width?: number; + /** Media Height */ + media_height?: number; + }; + /** FileNode */ + FileNode: { + /** Name */ + name: string; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + type: "file"; + /** Path */ + path: string; + /** Fullpath */ + fullPath: string; + /** Extension */ + extension: string; + /** Size */ + size: number; + /** Lines */ + lines: number; + /** Binary */ + binary: boolean; + /** + * Dirty + * @description Working-tree differs from HEAD for this tracked file (staged or unstaged). Always False for clean/remote repos. + */ + dirty: boolean; + /** + * Created + * @description ISO create date (UTC, Z-suffixed), resolved server-side: git history date when the file has one, filesystem date otherwise + */ + created: string; + /** + * Modified + * @description ISO modify date (UTC, Z-suffixed), resolved server-side: git history date when the file has one, filesystem date otherwise. When dirty is true, this is always the working-tree filesystem date, regardless of git history + */ + modified: string; + /** + * Mediakind + * @description Media classification by extension (single source for the frontend); null for non-media files + */ + mediaKind?: ("image" | "video") | null; + /** Media Width */ + media_width?: number; + /** Media Height */ + media_height?: number; + /** Binarytype */ + binaryType?: string; + }; + /** + * FingerprintEntry + * @description One binary file's byte-pattern fingerprint in a POST /api/fingerprints + * batch response: a base64-encoded grayscale PNG (image/png implied), keyed + * by request path. Computed server-side from the file's head — raw binary + * bytes never ship to the client. + */ + FingerprintEntry: { + /** B64 */ + b64: string; + }; + /** HTTPValidationError */ + HTTPValidationError: { + /** Detail */ + detail?: components["schemas"]["ValidationError"][]; + }; + /** HealthResponse */ + HealthResponse: { + /** Ok */ + ok: boolean; + }; + /** + * ImageBatchEntry + * @description One image in a POST /api/images batch response: its content-type and + * base64-encoded bytes, keyed by request path in the response map. + */ + ImageBatchEntry: { + /** Mime */ + mime: string; + /** B64 */ + b64: string; + }; + /** Manifest */ + Manifest: { + /** Root */ + root: string; + /** Scanned At */ + scanned_at: string; + /** Content Signature */ + content_signature: string; + /** Structure Signature */ + structure_signature: string; + /** Layout Signature */ + layout_signature: string; + tree: components["schemas"]["DirNode"]; + repo: components["schemas"]["RepoInfo"]; + /** Commits */ + commits: components["schemas"]["CommitEntry"][]; + busyness: components["schemas"]["BusynessThresholds"]; + dateRanges: components["schemas"]["DateRanges"]; + stats: components["schemas"]["RepoStats"]; + /** + * Pending + * @description Stages still to come. 'metadata': per-file lines/binary are placeholders. 'history': dates are filesystem dates and commits is empty. Empty list means every field is final. + */ + pending: ("metadata" | "history")[]; + /** + * Readmepath + * @description Absolute path of the root README, or null if there isn't one + */ + readmePath: string | null; + /** + * Readmemodified + * @description That README's mtime, for cache-busting the fetch + */ + readmeModified: string | null; + }; + /** + * PartialManifestEvent + * @description `manifest-partial` — a manifest with the real tree structure but + * placeholder file metadata, sent so the UI can paint the city before + * per-file metadata is resolved. + */ + PartialManifestEvent: { + manifest: components["schemas"]["Manifest"]; + }; + /** PathBatchRequest */ + PathBatchRequest: { + /** Paths */ + paths: string[]; + /** Shas */ + shas?: { + [key: string]: string; + } | null; + }; + /** RangeStat */ + RangeStat: { + /** Min */ + min: number; + /** Max */ + max: number; + }; + /** RepoInfo */ + RepoInfo: { + /** Branch */ + branch: string | null; + /** Remote Url */ + remote_url: string | null; + /** Head Sha */ + head_sha: string | null; + /** Head Subject */ + head_subject: string | null; + /** Dirty */ + dirty: boolean; + }; + /** RepoStats */ + RepoStats: { + lineCountRange: components["schemas"]["RangeStat"]; + byteSizeRange: components["schemas"]["RangeStat"]; + oldestCreatedFile: components["schemas"]["FileLeader"] | null; + newestCreatedFile: components["schemas"]["FileLeader"] | null; + newestModifiedFile: components["schemas"]["FileLeader"] | null; + oldestModifiedFile: components["schemas"]["FileLeader"] | null; + maxLinesFile: components["schemas"]["FileLeader"] | null; + minLinesFile: components["schemas"]["FileLeader"] | null; + maxBytesFile: components["schemas"]["FileLeader"] | null; + minBytesFile: components["schemas"]["FileLeader"] | null; + maxMediaBytesFile: components["schemas"]["FileLeader"] | null; + minMediaBytesFile: components["schemas"]["FileLeader"] | null; + maxMediaPixelsFile: components["schemas"]["FileLeader"] | null; + minMediaPixelsFile: components["schemas"]["FileLeader"] | null; + maxBinaryBytesFile: components["schemas"]["FileLeader"] | null; + minBinaryBytesFile: components["schemas"]["FileLeader"] | null; + /** Mediacount */ + mediaCount: number; + /** Binarycount */ + binaryCount: number; + /** Totallines */ + totalLines: number; + /** Dirtyfilecount */ + dirtyFileCount: number; + /** Codebytes */ + codeBytes: number; + maxDepthDir: components["schemas"]["DirLeader"] | null; + maxChildrenDir: components["schemas"]["DirLeader"] | null; + minChildrenDir: components["schemas"]["DirLeader"] | null; + maxFilesPerCommit: components["schemas"]["CommitLeader"] | null; + minFilesPerCommit: components["schemas"]["CommitLeader"] | null; + commitDates: components["schemas"]["CommitDateRange"]; + maxCommitsPerDay: components["schemas"]["DayLeader"] | null; + /** Maxcommitstreakdays */ + maxCommitStreakDays: number; + /** Authors */ + authors: components["schemas"]["AuthorStat"][]; + }; + /** + * ScanProgressEvent + * @description `scan-progress` — the working tree is being walked; carries the + * heartbeat files-scanned count. + */ + ScanProgressEvent: { + /** Label */ + label?: string; + /** Files Scanned */ + files_scanned?: number; + }; + /** SignatureResponse */ + SignatureResponse: { + /** Root */ + root: string; + /** Scanned At */ + scanned_at: string; + /** Content Signature */ + content_signature: string; + }; + /** + * TimelineBundle + * @description Wire schema for the scrub bundle; mirrors manifest_types.TimelineBundle. + */ + TimelineBundle: { + /** Commits */ + commits: components["schemas"]["CommitEntry"][]; + unionManifest: components["schemas"]["Manifest"]; + /** Deltas */ + deltas: components["schemas"]["TimelineDelta"][]; + /** Bloblines */ + blobLines: { + [key: string]: number; + }; + /** Blobsizes */ + blobSizes: { + [key: string]: number; + }; + /** Commitlineranges */ + commitLineRanges: components["schemas"]["RangeStat"][]; + /** Commitdateranges */ + commitDateRanges: components["schemas"]["DateRangeMs"][]; + /** Note */ + note: string | null; + }; + /** TimelineChange */ + TimelineChange: { + /** Path */ + path: string; + /** + * Sha + * @description New blob sha, or null when deleted + */ + sha: string | null; + }; + /** + * TimelineCompleteEvent + * @description `timeline-complete` — the full replay bundle (fresh build or warm + * cache hit). + */ + TimelineCompleteEvent: { + bundle: components["schemas"]["TimelineBundle"]; + }; + /** TimelineDelta */ + TimelineDelta: { + /** Sha */ + sha: string; + /** Changes */ + changes: components["schemas"]["TimelineChange"][]; + }; + /** + * TimelineProgressEvent + * @description `timeline-progress` — the history walk, blob-table resolution, or (for a + * blobless remote clone) the up-front blob backfill is in progress. The + * `fetch` stage carries `percent`; `history` carries `commits`; `blobs` + * carries `blobsDone`/`blobsTotal` (the total is known up front from the batch + * blob lookup, so that stage reports two ticks, not a live stream). + */ + TimelineProgressEvent: { + /** + * Stage + * @enum {string} + */ + stage: "fetch" | "history" | "blobs"; + /** Percent */ + percent?: number; + /** Commits */ + commits?: number; + /** Blobsdone */ + blobsDone?: number; + /** Blobstotal */ + blobsTotal?: number; + /** Label */ + label?: string; + }; + /** ValidationError */ + ValidationError: { + /** Location */ + loc: (string | number)[]; + /** Message */ + msg: string; + /** Error Type */ + type: string; + /** Input */ + input?: unknown; + /** Context */ + ctx?: Record; + }; }; - }; - responses: never; - parameters: never; - requestBodies: never; - headers: never; - pathItems: never; + responses: never; + parameters: never; + requestBodies: never; + headers: never; + pathItems: never; } export type $defs = Record; export interface operations { - health_api_health_get: { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; - }; - requestBody?: never; - responses: { - /** @description Successful Response */ - 200: { - headers: { - [name: string]: unknown; + health_api_health_get: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; }; - content: { - 'application/json': components['schemas']['HealthResponse']; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["HealthResponse"]; + }; + }; }; - }; - }; - }; - config_api_config_get: { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; }; - requestBody?: never; - responses: { - /** @description Successful Response */ - 200: { - headers: { - [name: string]: unknown; + config_api_config_get: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; }; - content: { - 'application/json': components['schemas']['ConfigResponse']; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["ConfigResponse"]; + }; + }; }; - }; - }; - }; - get_file_api_file_get: { - parameters: { - query: { - /** @description Absolute path inside a scanned root */ - path: string; - /** @description Blob sha to read instead of the working tree */ - sha?: string | null; - }; - header?: never; - path?: never; - cookie?: never; - }; - requestBody?: never; - responses: { - /** @description Successful Response */ - 200: { - headers: { - [name: string]: unknown; - }; - content: { - 'application/json': unknown; - }; - }; - /** @description Validation Error */ - 422: { - headers: { - [name: string]: unknown; - }; - content: { - 'application/json': components['schemas']['HTTPValidationError']; - }; - }; - }; - }; - get_images_api_images_post: { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; - }; - requestBody: { - content: { - 'application/json': components['schemas']['PathBatchRequest']; - }; - }; - responses: { - /** @description Successful Response */ - 200: { - headers: { - [name: string]: unknown; - }; - content: { - 'application/json': { - [key: string]: components['schemas']['ImageBatchEntry']; - }; - }; - }; - /** @description Validation Error */ - 422: { - headers: { - [name: string]: unknown; - }; - content: { - 'application/json': components['schemas']['HTTPValidationError']; - }; - }; - }; - }; - get_fingerprints_api_fingerprints_post: { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; }; - requestBody: { - content: { - 'application/json': components['schemas']['PathBatchRequest']; - }; - }; - responses: { - /** @description Successful Response */ - 200: { - headers: { - [name: string]: unknown; - }; - content: { - 'application/json': { - [key: string]: components['schemas']['FingerprintEntry']; - }; - }; - }; - /** @description Validation Error */ - 422: { - headers: { - [name: string]: unknown; - }; - content: { - 'application/json': components['schemas']['HTTPValidationError']; - }; - }; - }; - }; - get_commit_api_commit_get: { - parameters: { - query: { - sha: string; - }; - header?: never; - path?: never; - cookie?: never; - }; - requestBody?: never; - responses: { - /** @description Successful Response */ - 200: { - headers: { - [name: string]: unknown; - }; - content: { - 'application/json': components['schemas']['CommitDetailResponse']; - }; - }; - /** @description Validation Error */ - 422: { - headers: { - [name: string]: unknown; - }; - content: { - 'application/json': components['schemas']['HTTPValidationError']; - }; - }; - }; - }; - get_branches_api_branches_get: { - parameters: { - query: { - src: string; - }; - header?: never; - path?: never; - cookie?: never; + get_file_api_file_get: { + parameters: { + query: { + /** @description Absolute path inside a scanned root */ + path: string; + /** @description Blob sha to read instead of the working tree */ + sha?: string | null; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": unknown; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["HTTPValidationError"]; + }; + }; + }; }; - requestBody?: never; - responses: { - /** @description Successful Response */ - 200: { - headers: { - [name: string]: unknown; - }; - content: { - 'application/json': components['schemas']['BranchListResponse']; - }; - }; - /** @description Validation Error */ - 422: { - headers: { - [name: string]: unknown; - }; - content: { - 'application/json': components['schemas']['HTTPValidationError']; - }; - }; + get_images_api_images_post: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody: { + content: { + "application/json": components["schemas"]["PathBatchRequest"]; + }; + }; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + [key: string]: components["schemas"]["ImageBatchEntry"]; + }; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["HTTPValidationError"]; + }; + }; + }; }; - }; - signature_api_manifest_signature_get: { - parameters: { - query: { - src: string; - branch?: string | null; - no_cache?: boolean; - exclude?: string[]; - }; - header?: never; - path?: never; - cookie?: never; + get_fingerprints_api_fingerprints_post: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody: { + content: { + "application/json": components["schemas"]["PathBatchRequest"]; + }; + }; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": { + [key: string]: components["schemas"]["FingerprintEntry"]; + }; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["HTTPValidationError"]; + }; + }; + }; }; - requestBody?: never; - responses: { - /** @description Successful Response */ - 200: { - headers: { - [name: string]: unknown; - }; - content: { - 'application/json': components['schemas']['SignatureResponse']; - }; - }; - /** @description Validation Error */ - 422: { - headers: { - [name: string]: unknown; - }; - content: { - 'application/json': components['schemas']['HTTPValidationError']; - }; - }; + get_commit_api_commit_get: { + parameters: { + query: { + sha: string; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["CommitDetailResponse"]; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["HTTPValidationError"]; + }; + }; + }; }; - }; - timeline_api_timeline_get: { - parameters: { - query: { - src: string; - branch?: string | null; - no_cache?: boolean; - exclude?: string[]; - }; - header?: never; - path?: never; - cookie?: never; + get_branches_api_branches_get: { + parameters: { + query: { + src: string; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["BranchListResponse"]; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["HTTPValidationError"]; + }; + }; + }; }; - requestBody?: never; - responses: { - /** @description Server-Sent Events stream (`text/event-stream`). Named events and their JSON `data` payloads: `timeline-progress` (TimelineProgressEvent, one or more while the history walk / blob resolution run), `timeline-complete` (TimelineCompleteEvent, the full bundle), `error` (ErrorEvent). A warm cache hit emits only `timeline-complete`, no progress. The client closes the connection on `timeline-complete`/`error`. */ - 200: { - headers: { - [name: string]: unknown; - }; - content: { - 'application/json': - | components['schemas']['TimelineProgressEvent'] - | components['schemas']['TimelineCompleteEvent'] - | components['schemas']['ErrorEvent']; - }; - }; - /** @description Validation Error */ - 422: { - headers: { - [name: string]: unknown; - }; - content: { - 'application/json': components['schemas']['HTTPValidationError']; - }; - }; + signature_api_manifest_signature_get: { + parameters: { + query: { + src: string; + branch?: string | null; + no_cache?: boolean; + exclude?: string[]; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["SignatureResponse"]; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["HTTPValidationError"]; + }; + }; + }; }; - }; - manifest_api_manifest_get: { - parameters: { - query?: { - src?: string; - branch?: string | null; - no_cache?: boolean; - exclude?: string[]; - ref?: string | null; - }; - header?: never; - path?: never; - cookie?: never; + timeline_api_timeline_get: { + parameters: { + query: { + src: string; + branch?: string | null; + no_cache?: boolean; + exclude?: string[]; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Server-Sent Events stream (`text/event-stream`). Named events and their JSON `data` payloads: `timeline-progress` (TimelineProgressEvent, one or more while the history walk / blob resolution run), `timeline-complete` (TimelineCompleteEvent, the full bundle), `error` (ErrorEvent). A warm cache hit emits only `timeline-complete`, no progress. The client closes the connection on `timeline-complete`/`error`. */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["TimelineProgressEvent"] | components["schemas"]["TimelineCompleteEvent"] | components["schemas"]["ErrorEvent"]; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["HTTPValidationError"]; + }; + }; + }; }; - requestBody?: never; - responses: { - /** @description Server-Sent Events stream (`text/event-stream`). Named events and their JSON `data` payloads: `clone-progress` (CloneProgressEvent), `scan-progress` (ScanProgressEvent), `manifest-partial` (PartialManifestEvent), `manifest-complete` (CompleteManifestEvent), `error` (ErrorEvent). The client closes the connection on `manifest-complete`/`error`. When `ref` is set, the manifest is reconstructed as of that commit instead of the working tree (a remote source still emits `clone-progress` if it isn't cloned yet, but never `scan-progress`/`manifest-partial` for the reconstruction itself — the city is already drawn, so a skeleton would flash placeholders). */ - 200: { - headers: { - [name: string]: unknown; - }; - content: { - 'application/json': - | components['schemas']['CloneProgressEvent'] - | components['schemas']['ScanProgressEvent'] - | components['schemas']['PartialManifestEvent'] - | components['schemas']['CompleteManifestEvent'] - | components['schemas']['ErrorEvent']; - }; - }; - /** @description Validation Error */ - 422: { - headers: { - [name: string]: unknown; - }; - content: { - 'application/json': components['schemas']['HTTPValidationError']; - }; - }; + manifest_api_manifest_get: { + parameters: { + query?: { + src?: string; + branch?: string | null; + no_cache?: boolean; + exclude?: string[]; + ref?: string | null; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Server-Sent Events stream (`text/event-stream`). Named events and their JSON `data` payloads: `clone-progress` (CloneProgressEvent), `scan-progress` (ScanProgressEvent), `manifest-partial` (PartialManifestEvent), `manifest-complete` (CompleteManifestEvent), `error` (ErrorEvent). The client closes the connection on `manifest-complete`/`error`. When `ref` is set, the manifest is reconstructed as of that commit instead of the working tree (a remote source still emits `clone-progress` if it isn't cloned yet, but never `scan-progress`/`manifest-partial` for the reconstruction itself — the city is already drawn, so a skeleton would flash placeholders). */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["CloneProgressEvent"] | components["schemas"]["ScanProgressEvent"] | components["schemas"]["PartialManifestEvent"] | components["schemas"]["CompleteManifestEvent"] | components["schemas"]["ErrorEvent"]; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["HTTPValidationError"]; + }; + }; + }; }; - }; } From 3d75e12c234c69101d46fd5fa0530add7e7f55be Mon Sep 17 00:00:00 2001 From: Thalida Noel Date: Sat, 8 Aug 2026 18:19:28 -0400 Subject: [PATCH 03/19] feat: merge the reset gem into the project chip as a switcher --- .../ProjectSwitcher/ProjectSwitcher.css | 8 ++ .../ProjectSwitcher/ProjectSwitcher.tsx | 16 ++-- app/src/components/ResetViewButton.tsx | 25 ------- app/src/layout/App/App.tsx | 12 +-- app/src/layout/AppHeader/AppHeader.css | 38 ++-------- app/src/layout/AppHeader/AppHeader.tsx | 54 ++++++-------- app/tests/layout/AppHeader.test.tsx | 74 +++++++++++++++++++ 7 files changed, 123 insertions(+), 104 deletions(-) delete mode 100644 app/src/components/ResetViewButton.tsx create mode 100644 app/tests/layout/AppHeader.test.tsx diff --git a/app/src/components/ProjectSwitcher/ProjectSwitcher.css b/app/src/components/ProjectSwitcher/ProjectSwitcher.css index 81e9c894..e9531e13 100644 --- a/app/src/components/ProjectSwitcher/ProjectSwitcher.css +++ b/app/src/components/ProjectSwitcher/ProjectSwitcher.css @@ -14,6 +14,14 @@ flex: 0 0 auto; } +/* The gem is the chip's leading glyph. Sized to the chip's other icons and + held at its intrinsic width so a long repo name shrinks the label, not it. */ +.btn-chip-gem { + width: var(--cc-font-md); + height: var(--cc-font-md); + flex: 0 0 auto; +} + .app-header-branch-pill { display: inline-flex; align-items: center; diff --git a/app/src/components/ProjectSwitcher/ProjectSwitcher.tsx b/app/src/components/ProjectSwitcher/ProjectSwitcher.tsx index 66f99f7f..e93872b1 100644 --- a/app/src/components/ProjectSwitcher/ProjectSwitcher.tsx +++ b/app/src/components/ProjectSwitcher/ProjectSwitcher.tsx @@ -1,11 +1,13 @@ -// components/ProjectSwitcher.tsx — The project chip: label + optional @branch -// pill + a switch cue. Click opens the project switcher. The trailing glyph is -// ChevronsUpDown (a "switchable value" cue), not a down-caret, since clicking -// opens a full switcher screen rather than a dropdown menu. -// Renders nothing until a project is loaded (no label). +// components/ProjectSwitcher.tsx — The project chip: gem + label + optional +// @branch pill + a switch cue. Click opens the project switcher. The trailing +// glyph is ChevronsUpDown (a "switchable value" cue), not a down-caret, since +// clicking opens a full switcher screen rather than a dropdown menu. +// The gem doubles as the app logo, so the chip renders even before a project +// loads: gem alone, still opening the switcher. import './ProjectSwitcher.css'; import { ChevronsUpDown } from 'lucide-preact'; +import { GemIcon } from '@/components/GemIcon/GemIcon'; export interface ProjectSwitcherProps { rootLabel: string; @@ -14,7 +16,6 @@ export interface ProjectSwitcherProps { } export function ProjectSwitcher({ rootLabel, branch, onSwitchSource }: ProjectSwitcherProps) { - if (!rootLabel) return null; return ( diff --git a/app/src/components/ResetViewButton.tsx b/app/src/components/ResetViewButton.tsx deleted file mode 100644 index 73dddb70..00000000 --- a/app/src/components/ResetViewButton.tsx +++ /dev/null @@ -1,25 +0,0 @@ -// components/ResetViewButton.tsx — The gem button at the header's left edge. -// Doubles as the app logo: clicking it resets the camera view (R). Renders -// nothing when no reset handler is wired (pre-boot). - -import { GemIcon } from '@/components/GemIcon/GemIcon'; -import { KEY_BINDINGS } from '@/constants/keyboard'; - -export interface ResetViewButtonProps { - onResetView?: () => void; -} - -export function ResetViewButton({ onResetView }: ResetViewButtonProps) { - if (!onResetView) return null; - return ( - - ); -} diff --git a/app/src/layout/App/App.tsx b/app/src/layout/App/App.tsx index f561fb19..3645ec2a 100644 --- a/app/src/layout/App/App.tsx +++ b/app/src/layout/App/App.tsx @@ -31,12 +31,7 @@ import { DebugModal } from '@/views/DebugModal/DebugModal'; import { LoadingOverlay } from '@/components/LoadingOverlay/LoadingOverlay'; import { HljsThemeLink } from '@/components/HljsThemeLink/HljsThemeLink'; import { SelectionAnnouncer } from '@/components/SelectionAnnouncer/SelectionAnnouncer'; -import { - resetView, - clearSelection, - runCollisionCheck, - runStemDiagnostic, -} from '@/state/stores/scene'; +import { clearSelection, runCollisionCheck, runStemDiagnostic } from '@/state/stores/scene'; import { openProjectsView, closeProjectsView, LOADING_CANCEL } from '@/state/stores/ui'; import { SOURCE_ERROR, CURRENT_SOURCE } from '@/state/stores/source'; import { MANIFEST } from '@/state/stores/manifest'; @@ -93,10 +88,7 @@ export function App() { - openProjectsView({ dismissible: true })} - onResetView={resetView} - /> + openProjectsView({ dismissible: true })} />
diff --git a/app/src/layout/AppHeader/AppHeader.css b/app/src/layout/AppHeader/AppHeader.css index f6f52a00..2ed1913a 100644 --- a/app/src/layout/AppHeader/AppHeader.css +++ b/app/src/layout/AppHeader/AppHeader.css @@ -1,17 +1,14 @@ /* ── Sitewide header ────────────────────────────────────────────────── Full-width strip across the top of the app shell. Sits in the body's - column flex above #app-body; the sidebars start at its lower edge. */ + column flex above #app-body; the sidebars start at its lower edge. + One left-aligned row: project chip, copy-source, open-on-origin. */ #app-header { flex: 0 0 auto; - /* 3-column grid keeps #app-title visually centered in the viewport - regardless of how much content the left controls (gem, project chip, - repo link) occupy. The minmax(0, 1fr) tracks share the leftover space - equally, so the center column stays at true header-center. */ - display: grid; - grid-template-columns: minmax(0, 1fr) auto minmax(0, 1fr); + display: flex; align-items: center; - column-gap: var(--cc-space-6); + gap: var(--cc-space-2); + min-width: 0; height: 32px; padding: 0 var(--cc-space-4); border-bottom: 1px solid var(--cc-border-subtle); @@ -22,29 +19,8 @@ user-select: none; } -#app-header-left { - display: flex; - align-items: center; - gap: var(--cc-space-2); - min-width: 0; -} - -/* Centered cluster: project switcher, copy-source, open-remote (the gem stays - left, in #app-header-left). */ -#app-title { - display: flex; - align-items: center; - justify-content: center; - gap: var(--cc-space-2); - min-width: 0; - color: var(--cc-text-secondary); -} - -/* Visual style fully in .btn-icon (with --no-drag modifier where needed). */ - -/* Header buttons (switch-source, refresh, repo-link) now use - .btn-icon + .btn-icon--no-drag (refresh/switch) or - .btn-icon + .btn-icon--link + .btn-icon--no-drag (repo-link). +/* Header buttons use .btn-icon + .btn-icon--no-drag, or + .btn-icon + .btn-icon--link + .btn-icon--no-drag for the repo link. Inner svg rendering tweak applies to any svg child of a header btn-icon. */ #app-header .btn-icon svg { display: block; diff --git a/app/src/layout/AppHeader/AppHeader.tsx b/app/src/layout/AppHeader/AppHeader.tsx index 3e1d2cef..faaf2b16 100644 --- a/app/src/layout/AppHeader/AppHeader.tsx +++ b/app/src/layout/AppHeader/AppHeader.tsx @@ -1,7 +1,7 @@ -// layout/AppHeader.tsx — Sitewide top header. Composition shell only: the reset -// gem stays at the left edge; the project switcher + its actions (copy-source, -// open-on-origin) sit centered. What's selected is shown in the right sidebar -// (open whenever there's a selection), not here. +// layout/AppHeader.tsx — Sitewide top header. Composition shell only: a single +// left-aligned row holding the project switcher (gem + name + branch) and its +// actions (copy-source, open-on-origin). What's selected is shown in the right +// sidebar (open whenever there's a selection), not here. import './AppHeader.css'; import { ExternalLink } from 'lucide-preact'; @@ -9,46 +9,38 @@ import { SOURCE_INFO } from '@/state/stores/source'; import { MANIFEST } from '@/state/stores/manifest'; import type { Manifest } from '@/types'; import { openProjectsView } from '@/state/stores/ui'; -import { ResetViewButton } from '@/components/ResetViewButton'; import { ProjectSwitcher } from '@/components/ProjectSwitcher/ProjectSwitcher'; import { CopyButton } from '@/components/CopyButton/CopyButton'; export interface AppHeaderProps { /** Fires when the user clicks the project chip to switch source. */ onSwitchSource?: () => void; - /** Fires when the user clicks the reset-view (gem) button. */ - onResetView?: () => void; } -export function AppHeader({ onSwitchSource, onResetView }: AppHeaderProps = {}) { +export function AppHeader({ onSwitchSource }: AppHeaderProps = {}) { const si = SOURCE_INFO.value; const remoteUrl = (MANIFEST.value as Manifest)?.repo?.remote_url ?? null; return (
-
- -
-
- openProjectsView({ dismissible: true }))} - /> - {si.src && } - {remoteUrl && ( - - - - )} -
+ openProjectsView({ dismissible: true }))} + /> + {si.src && } + {remoteUrl && ( + + + + )}
); } diff --git a/app/tests/layout/AppHeader.test.tsx b/app/tests/layout/AppHeader.test.tsx new file mode 100644 index 00000000..ea06fe75 --- /dev/null +++ b/app/tests/layout/AppHeader.test.tsx @@ -0,0 +1,74 @@ +import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'; +import { render } from 'preact'; +import { AppHeader } from '@/layout/AppHeader/AppHeader'; +import { CURRENT_SOURCE } from '@/state/stores/source'; +import { setManifest } from '@/state/stores/manifest'; +import { EMPTY_MANIFEST } from '@/constants/manifest'; +import type { Manifest } from '@/types'; +import { flush } from '../_helpers/preact'; + +const LOADED: Manifest = { + ...EMPTY_MANIFEST, + tree: { ...EMPTY_MANIFEST.tree, name: 'codecity' }, +}; + +function loadProject() { + setManifest(LOADED); + CURRENT_SOURCE.value = { src: '/repos/codecity', branch: 'main' }; +} + +describe('AppHeader', () => { + let container: HTMLDivElement; + + beforeEach(() => { + container = document.createElement('div'); + document.body.appendChild(container); + }); + + afterEach(() => { + render(null, container); + document.body.removeChild(container); + CURRENT_SOURCE.value = null; + setManifest(EMPTY_MANIFEST); + }); + + it('renders the gem inside the project chip', async () => { + loadProject(); + render(, container); + await flush(); + + const chip = container.querySelector('.btn-chip'); + expect(chip).not.toBeNull(); + expect(chip!.querySelector('.gem-icon')).not.toBeNull(); + expect(chip!.textContent).toContain('codecity'); + }); + + it('opens the switcher when the chip is clicked', async () => { + const onSwitchSource = vi.fn(); + loadProject(); + render(, container); + await flush(); + + container.querySelector('.btn-chip')!.click(); + await flush(); + + expect(onSwitchSource).toHaveBeenCalledTimes(1); + }); + + it('still renders the gem before a project loads', async () => { + render(, container); + await flush(); + + const chip = container.querySelector('.btn-chip'); + expect(chip).not.toBeNull(); + expect(chip!.querySelector('.gem-icon')).not.toBeNull(); + }); + + it('has no reset-view control', async () => { + loadProject(); + render(, container); + await flush(); + + expect(container.querySelector('[aria-label="Reset view"]')).toBeNull(); + }); +}); From dda94680f4d2de2f57ecbd46d31766369ff9a25a Mon Sep 17 00:00:00 2001 From: Thalida Noel Date: Sat, 8 Aug 2026 18:28:09 -0400 Subject: [PATCH 04/19] fix: reword stale .btn-chip comment for the flex-row header --- app/src/styles/buttons.css | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/app/src/styles/buttons.css b/app/src/styles/buttons.css index e5e9e24e..d5e064a4 100644 --- a/app/src/styles/buttons.css +++ b/app/src/styles/buttons.css @@ -118,9 +118,9 @@ .btn-chip { appearance: none; - /* Grow with its content up to the header's left column (1fr), then shrink and - truncate — no hard cap, so it uses the space it's given before ellipsizing - (min-width: 0 lets the flex item shrink below its content width). */ + /* Grows with its content, no hard cap, then shrinks and truncates within + the header's flex row (min-width: 0 lets it shrink below its content + width) rather than pushing neighboring header buttons out of view. */ flex: 0 1 auto; min-width: 0; display: inline-flex; From ec5037a4e5c96c7219f5fc4b1bd53f431831b9f6 Mon Sep 17 00:00:00 2001 From: Thalida Noel Date: Sat, 8 Aug 2026 18:34:25 -0400 Subject: [PATCH 05/19] feat: add a version, repo, and creator credit line to the footer --- app/src/layout/AppFooter/AppFooter.css | 34 ++++++++++++++- app/src/layout/AppFooter/AppFooter.tsx | 14 +++---- app/src/layout/AppFooter/FooterMeta.tsx | 44 ++++++++++++++++++++ app/src/layout/AppFooter/FooterSep.tsx | 6 +++ app/tests/layout/AppFooter.test.tsx | 55 +++++++++++++++++++++++++ 5 files changed, 145 insertions(+), 8 deletions(-) create mode 100644 app/src/layout/AppFooter/FooterMeta.tsx create mode 100644 app/src/layout/AppFooter/FooterSep.tsx diff --git a/app/src/layout/AppFooter/AppFooter.css b/app/src/layout/AppFooter/AppFooter.css index 21d95f8f..a5f5f217 100644 --- a/app/src/layout/AppFooter/AppFooter.css +++ b/app/src/layout/AppFooter/AppFooter.css @@ -7,7 +7,7 @@ #app-footer { flex: 0 0 auto; display: grid; - grid-template-columns: minmax(0, 1fr) auto; + grid-template-columns: minmax(0, 1fr) auto minmax(0, 1fr); align-items: center; gap: var(--cc-space-7); padding: 0 var(--cc-space-6); @@ -43,6 +43,9 @@ .app-footer-section.app-footer-right { justify-content: flex-end; } +.app-footer-section.app-footer-center { + justify-content: center; +} .app-footer-item { flex: 0 1 auto; @@ -137,6 +140,32 @@ } } +/* ── Credit line (center section) ──────────────────────────────────── */ +/* Reads as a code comment: the // and the · separators sit at the faint + * separator color, the words one step up so the two links clear 4.5:1. */ +.app-footer-meta { + display: inline-flex; + align-items: center; + gap: var(--cc-space-3); + min-width: 0; +} +.app-footer-meta-comment { + color: var(--cc-text-faint); +} +.app-footer-meta-version, +.app-footer-meta-credit { + color: var(--cc-text-muted); +} +.app-footer-meta-link { + color: var(--cc-text-muted); + text-decoration: none; +} +.app-footer-meta-link:hover, +.app-footer-meta-link:focus-visible { + color: var(--cc-text-strong); + text-decoration: underline; +} + /* ── Footer responsive narrowing ───────────────────────────────────────────── */ /* At narrow widths the status timestamp / "rebuilding…" text is secondary information — hide it so the dot alone represents the status and the @@ -149,4 +178,7 @@ .app-footer-status-detail { display: none; } + .app-footer-center { + display: none; + } } diff --git a/app/src/layout/AppFooter/AppFooter.tsx b/app/src/layout/AppFooter/AppFooter.tsx index ebc49ec0..27cdc9a8 100644 --- a/app/src/layout/AppFooter/AppFooter.tsx +++ b/app/src/layout/AppFooter/AppFooter.tsx @@ -1,4 +1,4 @@ -// layout/AppFooter.tsx — Sitewide bottom status bar. Two sections: +// layout/AppFooter.tsx — Sitewide bottom status bar. Three sections: // left — combined status indicator: [dot] detail-text // One dot, two channels of state: // color — rebuild state (green=idle, yellow=rebuilding, @@ -9,11 +9,10 @@ // A detail next to the dot shows human-readable status // ("rebuilt 5s ago", "rebuilding…", "error: ", "paused"). // title= on the wrapper is a fallback tooltip for narrow widths. +// center — credit line: build version, repo link, attribution // right — current selection metadata (language · lines · size · created // · modified for files; file/dir counts + size for directories), // then a far-right icon cluster (keyboard shortcuts, debug) -// -// The refresh/reset-view button has moved to the header (far right). import './AppFooter.css'; import { useSignal } from '@preact/signals'; @@ -34,6 +33,8 @@ import { import { openShortcuts, openDebug } from '@/state/stores/ui'; import { isDebugMode } from '@/utils/debugMode'; import { humanLanguageFor } from '@/utils/syntaxLanguages'; +import { FooterSep } from './FooterSep'; +import { FooterMeta } from './FooterMeta'; interface FooterFileSelection { kind: NodeKind.File; @@ -114,10 +115,6 @@ function FooterItem({ text, title }: FooterItemData) { ); } -function FooterSep() { - return ·; -} - interface FooterStatusSectionProps { status: FooterStatus | null; } @@ -309,6 +306,9 @@ export function AppFooter() {
+
+ +
diff --git a/app/src/layout/AppFooter/FooterMeta.tsx b/app/src/layout/AppFooter/FooterMeta.tsx new file mode 100644 index 00000000..2fec2bec --- /dev/null +++ b/app/src/layout/AppFooter/FooterMeta.tsx @@ -0,0 +1,44 @@ +// layout/FooterMeta.tsx — The footer's centered credit line, styled as a code +// comment: build version, repo link, attribution. The version comes from the +// server (the running build's package metadata), so it stays accurate for a +// released image without a bundled constant to keep in sync. + +import { SERVER_CONFIG } from '@/state/stores/serverConfig'; +import { FooterSep } from './FooterSep'; + +const REPO_URL = 'https://github.com/thalida/codecity'; +const CREATOR_URL = 'https://thalida.com'; + +export function FooterMeta() { + return ( + + + v{SERVER_CONFIG.value.version} + + + about + + + + made by 🦄{' '} + + thalida. + + + + ); +} diff --git a/app/src/layout/AppFooter/FooterSep.tsx b/app/src/layout/AppFooter/FooterSep.tsx new file mode 100644 index 00000000..98f4ad0e --- /dev/null +++ b/app/src/layout/AppFooter/FooterSep.tsx @@ -0,0 +1,6 @@ +// layout/FooterSep.tsx — The footer's muted-dot separator, shared by the +// selection metadata and the credit line. + +export function FooterSep() { + return ·; +} diff --git a/app/tests/layout/AppFooter.test.tsx b/app/tests/layout/AppFooter.test.tsx index fa7fd66e..053371da 100644 --- a/app/tests/layout/AppFooter.test.tsx +++ b/app/tests/layout/AppFooter.test.tsx @@ -1,6 +1,7 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest'; import { render } from 'preact'; import { AppFooter } from '@/layout/AppFooter/AppFooter'; +import { SERVER_CONFIG, DEFAULT_SERVER_CONFIG } from '@/state/stores/serverConfig'; import { flush } from '../_helpers/preact'; describe('AppFooter — utility icon cluster', () => { @@ -24,3 +25,57 @@ describe('AppFooter — utility icon cluster', () => { expect(btn).not.toBeNull(); }); }); + +describe('AppFooter — credit line', () => { + let container: HTMLDivElement; + + beforeEach(() => { + container = document.createElement('div'); + document.body.appendChild(container); + SERVER_CONFIG.value = { ...DEFAULT_SERVER_CONFIG, version: '1.3.0' }; + }); + + afterEach(() => { + render(null, container); + document.body.removeChild(container); + SERVER_CONFIG.value = DEFAULT_SERVER_CONFIG; + }); + + it('shows the running build version', async () => { + render(, container); + await flush(); + + expect(container.querySelector('.app-footer-center')!.textContent).toContain('v1.3.0'); + }); + + it('links about to the repo and the credit to thalida.com', async () => { + render(, container); + await flush(); + + const links = Array.from(container.querySelectorAll('.app-footer-center a')); + expect(links.map((a) => a.getAttribute('href'))).toEqual([ + 'https://github.com/thalida/codecity', + 'https://thalida.com', + ]); + for (const a of links) { + expect(a.getAttribute('target')).toBe('_blank'); + expect(a.getAttribute('rel')).toBe('noopener noreferrer'); + } + }); + + it('credits the creator with the unicorn', async () => { + render(, container); + await flush(); + + expect(container.querySelector('.app-footer-center')!.textContent).toContain('🦄 thalida.'); + }); + + it('reads as a comment', async () => { + render(, container); + await flush(); + + expect(container.querySelector('.app-footer-center')!.textContent!.trimStart()).toMatch( + /^\/\// + ); + }); +}); From 133d56498f5b23e1c3f0adde5c1aec12b7eb4a8f Mon Sep 17 00:00:00 2001 From: Thalida Noel Date: Sat, 8 Aug 2026 19:07:56 -0400 Subject: [PATCH 06/19] Fix code review findings on the header/footer simplification Fixes the footer's narrow-viewport grid (right cluster was drifting into a dead third track once the center credit line hid), corrects stale comments left behind by the gem/reset-key merge and an earlier chip max-width fix, scopes .btn-chip-gem's sizing so it actually wins over .gem-icon's specificity-tied 1em default, and consolidates the three hardcoded copies of the repo URL into one REPO_URL constant. Co-Authored-By: Claude Opus 5 (1M context) --- app/src/city/interaction/inputHandlers.ts | 2 +- .../NewProjectForm/NewProjectForm.tsx | 3 ++- .../ProjectSwitcher/ProjectSwitcher.css | 17 ++++++++++------- .../ProjectSwitcher/ProjectSwitcher.tsx | 2 +- app/src/constants/keyboard.ts | 2 +- app/src/constants/ui.ts | 4 ++++ app/src/layout/AppFooter/AppFooter.css | 11 ++++++----- app/src/layout/AppFooter/FooterMeta.tsx | 2 +- app/src/styles/buttons.css | 4 ++-- .../ControlsPane/partials/ExcludesSection.tsx | 3 ++- 10 files changed, 30 insertions(+), 20 deletions(-) diff --git a/app/src/city/interaction/inputHandlers.ts b/app/src/city/interaction/inputHandlers.ts index 674f2326..6010d97d 100644 --- a/app/src/city/interaction/inputHandlers.ts +++ b/app/src/city/interaction/inputHandlers.ts @@ -148,7 +148,7 @@ export function createInputHandlers({ } if (hit.object.userData.type === NodeKind.Gem) { picker.setSelection(null); - // Gem click = reset view, same as the R key and the header gem button. + // Gem click = reset view, same as the R key. onResetView(); return; } diff --git a/app/src/components/NewProjectForm/NewProjectForm.tsx b/app/src/components/NewProjectForm/NewProjectForm.tsx index 53bedbf9..7e3739c4 100644 --- a/app/src/components/NewProjectForm/NewProjectForm.tsx +++ b/app/src/components/NewProjectForm/NewProjectForm.tsx @@ -19,6 +19,7 @@ import { } from '@/utils/sources'; import type { SourcePayload } from '@/state/stores/ui'; import { SCAN_PROGRESS } from '@/state/stores/scanProgress'; +import { REPO_URL } from '@/constants/ui'; export interface NewProjectFormProps { allowLocalRepos: boolean; @@ -29,7 +30,7 @@ export interface NewProjectFormProps { onDirty?: () => void; } -const LOCAL_DOCS_URL = 'https://github.com/thalida/codecity#local-directories'; +const LOCAL_DOCS_URL = `${REPO_URL}#local-directories`; export function NewProjectForm({ allowLocalRepos, diff --git a/app/src/components/ProjectSwitcher/ProjectSwitcher.css b/app/src/components/ProjectSwitcher/ProjectSwitcher.css index e9531e13..ac1701c9 100644 --- a/app/src/components/ProjectSwitcher/ProjectSwitcher.css +++ b/app/src/components/ProjectSwitcher/ProjectSwitcher.css @@ -1,8 +1,9 @@ /* The project switcher button is .btn-chip (defined with the button components - in buttons.css), capped at a max-width there. The label and branch pill - truncate with an ellipsis so a long repo name or branch can't overflow the - chip and overlap the neighbouring repo link. The full name stays reachable - via the switcher itself. */ + in buttons.css), which shrinks within the header's flex row rather than + pushing neighboring buttons out of view. The label and branch pill truncate + with an ellipsis so a long repo name or branch can't overflow the chip and + overlap the neighbouring repo link. The full name stays reachable via the + switcher itself. */ .btn-chip-label { white-space: nowrap; min-width: 0; @@ -14,9 +15,11 @@ flex: 0 0 auto; } -/* The gem is the chip's leading glyph. Sized to the chip's other icons and - held at its intrinsic width so a long repo name shrinks the label, not it. */ -.btn-chip-gem { +/* The gem is the chip's leading glyph. Scoped to .btn-chip (not just + .btn-chip-gem) so it wins over .gem-icon's own 1em sizing at equal + specificity — sized to the chip's other icons and held at its intrinsic + width so a long repo name shrinks the label, not it. */ +.btn-chip .gem-icon { width: var(--cc-font-md); height: var(--cc-font-md); flex: 0 0 auto; diff --git a/app/src/components/ProjectSwitcher/ProjectSwitcher.tsx b/app/src/components/ProjectSwitcher/ProjectSwitcher.tsx index e93872b1..99e418aa 100644 --- a/app/src/components/ProjectSwitcher/ProjectSwitcher.tsx +++ b/app/src/components/ProjectSwitcher/ProjectSwitcher.tsx @@ -27,7 +27,7 @@ export function ProjectSwitcher({ rootLabel, branch, onSwitchSource }: ProjectSw if (onSwitchSource) onSwitchSource(); }} > - + {rootLabel && {rootLabel}} {branch && @{branch}} diff --git a/app/src/constants/keyboard.ts b/app/src/constants/keyboard.ts index 55b246d2..1ebb8e65 100644 --- a/app/src/constants/keyboard.ts +++ b/app/src/constants/keyboard.ts @@ -15,7 +15,7 @@ export interface KeyBinding { export const KEY_BINDINGS: Record = { /** Reset the camera framing to the current mode's default pose. - * Mirrors the header gem button and clicking the gem in the city. + * Mirrors clicking the gem in the city. * Does NOT rebuild the city manifest — reload the page for that. */ RESET_VIEW: { label: 'R', keys: ['r', 'R', 'Home'] }, /** Focus camera on the current selection. */ diff --git a/app/src/constants/ui.ts b/app/src/constants/ui.ts index 8b227f13..c424c1a1 100644 --- a/app/src/constants/ui.ts +++ b/app/src/constants/ui.ts @@ -7,6 +7,10 @@ import { SidebarTab } from '@/types/ui'; * (oldest dropped past this). */ export const MAX_RECENT_SOURCES = 10; +/** The codecity repo itself, base for the footer's "about" link and the + * README-anchor deep links used elsewhere in the UI. */ +export const REPO_URL = 'https://github.com/thalida/codecity'; + /** * Activity-bar tab definitions (left-side icon strip). Each entry pairs a tab * id with its Lucide glyph component (imported from lucide-preact) + the diff --git a/app/src/layout/AppFooter/AppFooter.css b/app/src/layout/AppFooter/AppFooter.css index a5f5f217..c987c07d 100644 --- a/app/src/layout/AppFooter/AppFooter.css +++ b/app/src/layout/AppFooter/AppFooter.css @@ -54,9 +54,9 @@ white-space: nowrap; } -/* Shared muted-dot separator. Used between metadata items in the left - * (selection) section and between the branch + repo link in the center - * section. Pointer-events:none so a stray click between items doesn't +/* Shared muted-dot separator. Used between the selection metadata items in + * the right section and between the version/links/credit in the center + * credit line. Pointer-events:none so a stray click between items doesn't * fall on the dot. */ .app-footer-sep { flex: 0 0 auto; @@ -168,10 +168,11 @@ /* ── Footer responsive narrowing ───────────────────────────────────────────── */ /* At narrow widths the status timestamp / "rebuilding…" text is secondary - information — hide it so the dot alone represents the status and the - left / center sections keep their space. */ + information, so it's hidden and the credit line is dropped entirely, + leaving the status dot and the utility-icon cluster in a two-track grid. */ @media (max-width: 580px) { #app-footer { + grid-template-columns: minmax(0, 1fr) auto; gap: var(--cc-space-3); padding: 0 var(--cc-space-4); } diff --git a/app/src/layout/AppFooter/FooterMeta.tsx b/app/src/layout/AppFooter/FooterMeta.tsx index 2fec2bec..f19ac7de 100644 --- a/app/src/layout/AppFooter/FooterMeta.tsx +++ b/app/src/layout/AppFooter/FooterMeta.tsx @@ -4,9 +4,9 @@ // released image without a bundled constant to keep in sync. import { SERVER_CONFIG } from '@/state/stores/serverConfig'; +import { REPO_URL } from '@/constants/ui'; import { FooterSep } from './FooterSep'; -const REPO_URL = 'https://github.com/thalida/codecity'; const CREATOR_URL = 'https://thalida.com'; export function FooterMeta() { diff --git a/app/src/styles/buttons.css b/app/src/styles/buttons.css index d5e064a4..20adc5ef 100644 --- a/app/src/styles/buttons.css +++ b/app/src/styles/buttons.css @@ -113,8 +113,8 @@ LAYER-2 COMPONENTS — Icon-text chip (.btn-chip) ═══════════════════════════════════════════════════════════════════════════ Used by the header project switcher (icon + label + optional badge). - Different from .btn-icon — has gap, asymmetric padding, max-width, - ellipsis truncation on its label. */ + Different from .btn-icon — has gap, shrinks and truncates its label instead + of a hard-capped width. */ .btn-chip { appearance: none; diff --git a/app/src/views/ControlsPane/partials/ExcludesSection.tsx b/app/src/views/ControlsPane/partials/ExcludesSection.tsx index 756864ee..e66f190c 100644 --- a/app/src/views/ControlsPane/partials/ExcludesSection.tsx +++ b/app/src/views/ControlsPane/partials/ExcludesSection.tsx @@ -9,6 +9,7 @@ import './ExcludesSection.css'; import { EyeOff, RotateCcw } from 'lucide-preact'; import { ACTIVE_EXCLUDES, removeExclude, clearExcludes } from '@/state/stores/excludes'; import { Section } from '@/components/Section/Section'; +import { REPO_URL } from '@/constants/ui'; export function ExcludesSection() { const paths = ACTIVE_EXCLUDES.value; @@ -20,7 +21,7 @@ export function ExcludesSection() { Paths you hide from the city, saved in this browser. This does not change the repo.{' '} From b2aaa5a9309fb8dc2b51c46578ed3731c4d34acb Mon Sep 17 00:00:00 2001 From: Thalida Noel Date: Sat, 8 Aug 2026 19:09:51 -0400 Subject: [PATCH 07/19] Brighten the footer credit links so they read as links At the prose color they were indistinguishable from the text around them. --cc-text-primary puts them two steps above that prose; hover keeps --cc-text-strong plus the underline. Co-Authored-By: Claude Opus 5 (1M context) --- app/src/layout/AppFooter/AppFooter.css | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/app/src/layout/AppFooter/AppFooter.css b/app/src/layout/AppFooter/AppFooter.css index c987c07d..0a6520a5 100644 --- a/app/src/layout/AppFooter/AppFooter.css +++ b/app/src/layout/AppFooter/AppFooter.css @@ -142,7 +142,9 @@ /* ── Credit line (center section) ──────────────────────────────────── */ /* Reads as a code comment: the // and the · separators sit at the faint - * separator color, the words one step up so the two links clear 4.5:1. */ + * separator color, the prose one step up. The links sit two steps up from + * the prose around them, which is what marks them as clickable: at the + * prose color they read as plain text. */ .app-footer-meta { display: inline-flex; align-items: center; @@ -157,7 +159,7 @@ color: var(--cc-text-muted); } .app-footer-meta-link { - color: var(--cc-text-muted); + color: var(--cc-text-primary); text-decoration: none; } .app-footer-meta-link:hover, From 4602f6d355da6205773d1c4ed27251a23d629d5e Mon Sep 17 00:00:00 2001 From: Thalida Noel Date: Sat, 8 Aug 2026 19:14:08 -0400 Subject: [PATCH 08/19] Correct the gem-sizing comment's specificity claim .btn-chip .gem-icon is (0,2,0) against .gem-icon's (0,1,0), so it wins on specificity outright, not on import order at a tie. Co-Authored-By: Claude Opus 5 (1M context) --- app/src/components/ProjectSwitcher/ProjectSwitcher.css | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/app/src/components/ProjectSwitcher/ProjectSwitcher.css b/app/src/components/ProjectSwitcher/ProjectSwitcher.css index ac1701c9..6f4ca933 100644 --- a/app/src/components/ProjectSwitcher/ProjectSwitcher.css +++ b/app/src/components/ProjectSwitcher/ProjectSwitcher.css @@ -15,10 +15,10 @@ flex: 0 0 auto; } -/* The gem is the chip's leading glyph. Scoped to .btn-chip (not just - .btn-chip-gem) so it wins over .gem-icon's own 1em sizing at equal - specificity — sized to the chip's other icons and held at its intrinsic - width so a long repo name shrinks the label, not it. */ +/* The gem is the chip's leading glyph, sized to the chip's other icons and + held at its intrinsic width so a long repo name shrinks the label, not it. + The descendant selector outranks .gem-icon's own 1em sizing on specificity, + so the size holds regardless of CSS import order. */ .btn-chip .gem-icon { width: var(--cc-font-md); height: var(--cc-font-md); From b7ccf935ba6399ca89ea5aa5c4e8a01c9048b590 Mon Sep 17 00:00:00 2001 From: Thalida Noel Date: Sat, 8 Aug 2026 20:25:43 -0400 Subject: [PATCH 09/19] Give the gem its own breathing room in the project chip The chip's flex gap spaces every child equally, so the gem read as a glyph inside the name. Only this gap widens; the name, branch pill, and affordance stay a tight cluster. Co-Authored-By: Claude Opus 5 (1M context) --- app/src/components/ProjectSwitcher/ProjectSwitcher.css | 3 +++ 1 file changed, 3 insertions(+) diff --git a/app/src/components/ProjectSwitcher/ProjectSwitcher.css b/app/src/components/ProjectSwitcher/ProjectSwitcher.css index 6f4ca933..2c1c4e18 100644 --- a/app/src/components/ProjectSwitcher/ProjectSwitcher.css +++ b/app/src/components/ProjectSwitcher/ProjectSwitcher.css @@ -23,6 +23,9 @@ width: var(--cc-font-md); height: var(--cc-font-md); flex: 0 0 auto; + /* Reads as the chip's icon rather than a glyph in the name: only this gap + widens, so the name, branch pill, and affordance stay a tight cluster. */ + margin-right: var(--cc-space-2); } .app-header-branch-pill { From 4e86ecae1d0a577a64df96412fb835c1ad5aa9de Mon Sep 17 00:00:00 2001 From: Thalida Noel Date: Sat, 8 Aug 2026 20:25:43 -0400 Subject: [PATCH 10/19] Rework the landing layout for small screens Below 900px the hero stacks above the cards, and the styles written for the side-by-side composition mislead in that arrangement: - The action column kept a viewport-height cap and align-self: center, so the cards sat a screen below the hero with the recents card stretching to absorb the slack. - Grid's default align-content: stretch inflated the auto rows to fill min-height, opening a screen-tall gap between hero and cards. It now centers only while the content fits: `safe` keeps a full recents list from clipping the hero above the scroll origin. - Hero text sat at the page gutter while card titles sat a further 16px in, so two vertically adjacent blocks disagreed on their left edge. The hero now carries the card's own padding. - The close button floated in a band the brand row also occupied. The top inset now clears it. - The flat 90% veil rendered the city as dead black. The scrim runs down the page instead, thinning toward a horizon at the bottom. The page is fixed to the viewport, so the insets clear safe areas. Recents is capped at MAX_RECENT_SOURCES, which bounds the page length without a scroller nested inside the card. Co-Authored-By: Claude Opus 5 (1M context) --- .../components/RecentsList/RecentsList.css | 8 ++- app/src/views/ProjectsView/ProjectsView.css | 63 ++++++++++++++++--- 2 files changed, 61 insertions(+), 10 deletions(-) diff --git a/app/src/components/RecentsList/RecentsList.css b/app/src/components/RecentsList/RecentsList.css index ec9c66e6..38cb15bd 100644 --- a/app/src/components/RecentsList/RecentsList.css +++ b/app/src/components/RecentsList/RecentsList.css @@ -5,9 +5,11 @@ display: flex; flex-direction: column; gap: var(--cc-space-1); - /* Grow into the card's remaining height (the card is height-capped by - .landing-actions), then scroll the rows rather than the page. min-height: 0 - lets this flex child shrink below its content so the overflow is its own. */ + /* Grow into the card's remaining height and scroll the rows rather than the + page, wherever the card is height-capped (the side-by-side landing layout). + Stacked, the card shrink-wraps and the page scroller takes over instead. + min-height: 0 lets this flex child shrink below its content so the overflow + is its own. */ flex: 1 1 auto; min-height: 0; overflow-y: auto; diff --git a/app/src/views/ProjectsView/ProjectsView.css b/app/src/views/ProjectsView/ProjectsView.css index 649a1a96..418b7ec3 100644 --- a/app/src/views/ProjectsView/ProjectsView.css +++ b/app/src/views/ProjectsView/ProjectsView.css @@ -17,20 +17,32 @@ hero side, letting its text keep AA contrast over the city; the action cards carry their own opaque surface and the center/right stays clear. */ .landing--modal { + /* The scrim holds near-full strength across the whole hero column and only + falls off past it, so building edges never cut through the tagline or the + feature cues. */ background: linear-gradient( 100deg, - color-mix(in oklch, var(--cc-bg-app) 82%, transparent) 0%, - color-mix(in oklch, var(--cc-bg-app) 62%, transparent) 24%, - color-mix(in oklch, var(--cc-bg-app) 24%, transparent) 46%, - transparent 64% + color-mix(in oklch, var(--cc-bg-app) 96%, transparent) 0%, + color-mix(in oklch, var(--cc-bg-app) 92%, transparent) 30%, + color-mix(in oklch, var(--cc-bg-app) 60%, transparent) 52%, + transparent 72% ); } -/* Stacked layout: the hero is full-width at the top with no card column beside - it, so a directional scrim can't cover it, fall back to an even veil. */ +/* Stacked layout: the hero sits above the cards rather than beside them, so the + scrim runs down the page instead of across it. Near-solid through the band the + hero occupies, thinning toward the bottom where the city reads as a deliberate + horizon. The cards carry their own opaque surface, so they stay legible over + the thin end. */ @media (max-width: 900px) { .landing--modal { - background: color-mix(in oklch, var(--cc-bg-app) 70%, transparent); + background: linear-gradient( + 180deg, + color-mix(in oklch, var(--cc-bg-app) 97%, transparent) 0%, + color-mix(in oklch, var(--cc-bg-app) 94%, transparent) 55%, + color-mix(in oklch, var(--cc-bg-app) 62%, transparent) 82%, + color-mix(in oklch, var(--cc-bg-app) 40%, transparent) 100% + ); } } @@ -63,10 +75,47 @@ } @media (max-width: 900px) { + /* The page is fixed to the viewport, so it spans the status bar and home + indicator: every edge inset clears its safe area. */ + .landing-close { + top: calc(var(--cc-space-7) + env(safe-area-inset-top)); + right: calc(var(--cc-space-7) + env(safe-area-inset-right)); + } + .landing-inner { grid-template-columns: 1fr; align-items: start; + /* Centered while the content fits, top-aligned the moment it doesn't. The + plain keyword would clip the overflow at the start edge, putting the hero + above the scroll origin and out of reach once the recents list is full. */ + align-content: safe center; gap: var(--cc-space-8); + /* The top band clears the floating close button (its own inset plus its + height) so the brand never shares a line with it. */ + padding: calc(var(--cc-space-9) * 2 + env(safe-area-inset-top)) + calc(var(--cc-space-7) + env(safe-area-inset-right)) + calc(var(--cc-space-9) + env(safe-area-inset-bottom)) + calc(var(--cc-space-7) + env(safe-area-inset-left)); + } + + /* Indent the hero by the card's own padding so its text shares a left edge + with the card titles stacked beneath it. */ + .landing-hero { + padding-inline: var(--cc-space-7); + } + + /* Stacked, the cards follow the hero down the page instead of sharing its row, + so the viewport-height cap and the centering that serve the side-by-side + column would strand them below a screen of empty space. The page scroller + takes over and each card shrink-wraps its content: the recents list is capped + at MAX_RECENT_SOURCES, so the page stays a bounded length without needing a + scroller nested inside the card. */ + .landing-actions { + align-self: stretch; + max-height: none; + } + .landing-card--recents { + flex: 0 0 auto; } } From 207523b94d583f73aaf2c9cc5703b0160af90163 Mon Sep 17 00:00:00 2001 From: Thalida Noel Date: Sat, 8 Aug 2026 20:32:27 -0400 Subject: [PATCH 11/19] Give every over-the-scene panel the same glass The scrubber and the mode toggle each hand-rolled a frosted fill, and they disagreed: 78% against 82% of the same colour. The timeline's is the reference, so 78% and blur(12px) become tokens, and .surface-glass joins the surface roles as the fill for a panel with the canvas behind it. Now shared by the scrubber, the mode toggle, the Shortcuts, Debug and Loading cards, and the landing cards. The timeline's stale-scrub toast keeps its semantic error fill and takes only the blur radius. Chrome laid out in the app body (header, footer, activity bar, sidebars, editor pane) stays opaque: a blur there has nothing to sample. The modal header drops its separate chrome fill so each card reads as one panel rather than an opaque band over glass. Co-Authored-By: Claude Opus 5 (1M context) --- app/src/components/LoadingOverlay/LoadingOverlay.tsx | 2 +- app/src/components/SceneModeToggle/SceneModeToggle.css | 3 --- app/src/components/SceneModeToggle/SceneModeToggle.tsx | 2 +- app/src/components/TimeTravelBar/TimeTravelBar.css | 5 +---- app/src/components/TimeTravelBar/TimeTravelBar.tsx | 2 +- .../components/TimelineStaleNote/TimelineStaleNote.css | 6 ++++-- app/src/styles/cards.css | 2 +- app/src/styles/surfaces.css | 10 ++++++++++ app/src/styles/tokens.css | 8 ++++++++ app/src/views/DebugModal/DebugModal.tsx | 9 +++++++-- app/src/views/ProjectsView/ProjectsView.tsx | 6 +++--- app/src/views/ShortcutsModal/ShortcutsModal.tsx | 4 ++-- 12 files changed, 39 insertions(+), 20 deletions(-) diff --git a/app/src/components/LoadingOverlay/LoadingOverlay.tsx b/app/src/components/LoadingOverlay/LoadingOverlay.tsx index df6ae82a..62bbc707 100644 --- a/app/src/components/LoadingOverlay/LoadingOverlay.tsx +++ b/app/src/components/LoadingOverlay/LoadingOverlay.tsx @@ -25,7 +25,7 @@ export function LoadingOverlay({ onCancel }: LoadingOverlayProps) { return (
-
+
+
- )} + + + {isDebugMode() && ( -
+ )} +
+
+
); diff --git a/app/src/layout/AppFooter/FooterMeta.tsx b/app/src/layout/AppFooter/FooterMeta.tsx index f19ac7de..2f4999f2 100644 --- a/app/src/layout/AppFooter/FooterMeta.tsx +++ b/app/src/layout/AppFooter/FooterMeta.tsx @@ -1,44 +1,30 @@ -// layout/FooterMeta.tsx — The footer's centered credit line, styled as a code -// comment: build version, repo link, attribution. The version comes from the -// server (the running build's package metadata), so it stays accurate for a -// released image without a bundled constant to keep in sync. +// layout/FooterMeta.tsx — The footer's two meta bits, at opposite ends. +// +// Version sits bottom-left with the build status: both answer "what is running +// right now", and it comes from the server rather than a bundled constant, so a +// released image reports its own tag. Credit sits bottom-right, the quiet +// corner. The outward link to the repo lives in the app header. import { SERVER_CONFIG } from '@/state/stores/serverConfig'; -import { REPO_URL } from '@/constants/ui'; -import { FooterSep } from './FooterSep'; +import { CREATOR_URL } from '@/constants/ui'; -const CREATOR_URL = 'https://thalida.com'; +export function FooterVersion() { + return v{SERVER_CONFIG.value.version}; +} -export function FooterMeta() { +export function FooterCredit() { return ( - - - v{SERVER_CONFIG.value.version} - + + made by 🦄{' '} - about + thalida. - - - made by 🦄{' '} - - thalida. - - ); } diff --git a/app/src/layout/AppHeader/AppHeader.css b/app/src/layout/AppHeader/AppHeader.css index 2ed1913a..0c972411 100644 --- a/app/src/layout/AppHeader/AppHeader.css +++ b/app/src/layout/AppHeader/AppHeader.css @@ -19,6 +19,27 @@ user-select: none; } +/* Meta cluster pinned to the far right, opposite the project controls. */ +#app-header-meta { + display: flex; + align-items: center; + gap: var(--cc-space-4); + margin-left: auto; + flex: 0 0 auto; +} + +/* A text link among icon buttons: matched to the resting icon color so the + cluster reads as one weight, and brightened on hover like they are. */ +.app-header-link { + color: var(--cc-text-muted); + text-decoration: none; +} +.app-header-link:hover, +.app-header-link:focus-visible { + color: var(--cc-text-strong); + text-decoration: underline; +} + /* Header buttons use .btn-icon + .btn-icon--no-drag, or .btn-icon + .btn-icon--link + .btn-icon--no-drag for the repo link. Inner svg rendering tweak applies to any svg child of a header btn-icon. */ diff --git a/app/src/layout/AppHeader/AppHeader.tsx b/app/src/layout/AppHeader/AppHeader.tsx index faaf2b16..aa9f95c8 100644 --- a/app/src/layout/AppHeader/AppHeader.tsx +++ b/app/src/layout/AppHeader/AppHeader.tsx @@ -1,14 +1,17 @@ -// layout/AppHeader.tsx — Sitewide top header. Composition shell only: a single -// left-aligned row holding the project switcher (gem + name + branch) and its -// actions (copy-source, open-on-origin). What's selected is shown in the right -// sidebar (open whenever there's a selection), not here. +// layout/AppHeader.tsx — Sitewide top header. Composition shell only. Left: the +// project switcher (gem + name + branch) and its actions (copy-source, +// open-on-origin), all about the project you have open. Right: the meta any +// user might want, about and the keyboard shortcuts. Developer-only tools and +// run-state live in the footer instead; what's selected is shown in the right +// sidebar (open whenever there's a selection). import './AppHeader.css'; -import { ExternalLink } from 'lucide-preact'; +import { ExternalLink, Keyboard } from 'lucide-preact'; import { SOURCE_INFO } from '@/state/stores/source'; import { MANIFEST } from '@/state/stores/manifest'; import type { Manifest } from '@/types'; -import { openProjectsView } from '@/state/stores/ui'; +import { openProjectsView, openShortcuts } from '@/state/stores/ui'; +import { REPO_URL } from '@/constants/ui'; import { ProjectSwitcher } from '@/components/ProjectSwitcher/ProjectSwitcher'; import { CopyButton } from '@/components/CopyButton/CopyButton'; @@ -41,6 +44,26 @@ export function AppHeader({ onSwitchSource }: AppHeaderProps = {}) { )} +
+ + about + + +
); } diff --git a/app/src/utils/debugMode.ts b/app/src/utils/debugMode.ts index 86e978df..93fe5adf 100644 --- a/app/src/utils/debugMode.ts +++ b/app/src/utils/debugMode.ts @@ -1,4 +1,4 @@ -// utils/debugMode.ts — Gate for developer-only UI (the header bug icon and +// utils/debugMode.ts — Gate for developer-only UI (the footer bug icon and // its DebugModal). On in a dev server, when built with VITE_DEBUG, or with // ?debug in the URL — so a prod deploy can still be flipped on for support. diff --git a/app/src/views/FilePreviewPane/FilePreviewPane.tsx b/app/src/views/FilePreviewPane/FilePreviewPane.tsx index 3b9cee8e..662cc6b7 100644 --- a/app/src/views/FilePreviewPane/FilePreviewPane.tsx +++ b/app/src/views/FilePreviewPane/FilePreviewPane.tsx @@ -28,6 +28,8 @@ export enum PreviewKind { Text = 'text', } import { fileUrl, fetchFileText, fetchFileBytes } from '@/api/file'; +import { PaneStats } from '@/components/PaneStats/PaneStats'; +import { fileStatItems } from '@/components/PaneStats/statItems'; import { scrubbedBlobShaFor } from '@/state/stores/presentPaths'; import { fetchFingerprintB64 } from '@/api/fingerprint'; import { IMAGE_EXTS, VIDEO_EXTS, AUDIO_EXTS, PDF_EXTS, FONT_EXTS } from '@/constants/fileKinds'; @@ -583,6 +585,7 @@ export function FilePreviewPane({ state, onClose, onFocus, onExclude }: FilePrev onExclude={file && typeof onExclude === 'function' ? () => onExclude(file) : undefined} excludeTitle="Exclude this file from the city" bodyClass="editor-body surface-app" + footerSlot={file && !deleted ? : null} > {deleted ? (
diff --git a/app/src/views/StreetPane/StreetPane.tsx b/app/src/views/StreetPane/StreetPane.tsx index e3b9235e..98b65684 100644 --- a/app/src/views/StreetPane/StreetPane.tsx +++ b/app/src/views/StreetPane/StreetPane.tsx @@ -16,6 +16,8 @@ import { TimelineStaleNote } from '@/components/TimelineStaleNote/TimelineStaleN import { KEY_BINDINGS } from '@/constants/keyboard'; import { Route, FileType, CalendarRange } from 'lucide-preact'; import { ExtensionBadge } from '@/components/Badge/Badge'; +import { PaneStats } from '@/components/PaneStats/PaneStats'; +import { directoryStatItems } from '@/components/PaneStats/statItems'; import { PathBreadcrumbs } from '@/components/PathBreadcrumbs/PathBreadcrumbs'; import { nodeUrl } from '@/utils/commit'; import { extHueColor } from '@/city/components/buildings/color'; @@ -108,6 +110,7 @@ export function StreetPane({ state, onClose, onFocus, onExclude }: StreetPanePro } excludeTitle="Exclude this road from the city" bodyClass={`street-body${inTimeline ? ' has-stale-note' : ''}`} + footerSlot={} > {inTimeline && ( diff --git a/app/tests/components/paneStats.test.tsx b/app/tests/components/paneStats.test.tsx new file mode 100644 index 00000000..4745d78a --- /dev/null +++ b/app/tests/components/paneStats.test.tsx @@ -0,0 +1,101 @@ +import { describe, it, expect, beforeEach, afterEach } from 'vitest'; +import { render } from 'preact'; +import { PaneStats } from '@/components/PaneStats/PaneStats'; +import { fileStatItems, directoryStatItems } from '@/components/PaneStats/statItems'; +import { NodeKind, type FileNode, type DirNode } from '@/types'; +import { flush } from '../_helpers/preact'; + +const NOW = Date.UTC(2024, 2, 25); + +const FILE: FileNode = { + name: 'index.ts', + type: NodeKind.File, + path: 'src/index.ts', + fullPath: '/tmp/project/src/index.ts', + extension: '.ts', + size: 1536, + lines: 50, + binary: false, + dirty: false, + created: '2024-01-10T09:00:00Z', + modified: '2024-03-20T10:00:00Z', +}; + +const DIR: DirNode = { + name: 'src', + type: NodeKind.Directory, + path: 'src', + fullPath: '/tmp/project/src', + children: [], + children_count: 3, + children_file_count: 3, + children_dir_count: 1, + descendants_count: 12, + descendants_file_count: 9, + descendants_dir_count: 1, + descendants_size: 4096, + descendants_created_min: '2024-01-01T00:00:00Z', + descendants_modified_max: '2024-02-01T00:00:00Z', + descendants_ext_breakdown: [{ ext: '.ts', count: 9, size: 4096 }], +}; + +describe('statItems', () => { + it('describes a file by language, size, and age', () => { + const texts = fileStatItems(FILE, NOW).map((i) => i.text); + expect(texts).toContain('50 lines'); + expect(texts.some((t) => t.startsWith('modified '))).toBe(true); + expect(texts.some((t) => t.startsWith('created '))).toBe(true); + }); + + it('carries the exact date as the tooltip behind a relative age', () => { + const modified = fileStatItems(FILE, NOW).find((i) => i.text.startsWith('modified '))!; + expect(modified.title).toBeTruthy(); + expect(modified.title).not.toBe(modified.text); + }); + + it('omits stats the node does not carry', () => { + const bare: FileNode = { ...FILE, lines: null, size: null, created: null, modified: null }; + const texts = fileStatItems(bare, NOW).map((i) => i.text); + expect(texts.some((t) => t.includes('lines'))).toBe(false); + expect(texts.some((t) => t.startsWith('modified'))).toBe(false); + }); + + it('shows a directory total alongside its direct count when they differ', () => { + const files = directoryStatItems(DIR).find((i) => i.text.includes('files'))!; + expect(files.text).toBe('3 files (9 total)'); + }); + + it('collapses a directory count to one number when they match', () => { + const dirs = directoryStatItems(DIR).find((i) => i.text.includes('dirs'))!; + expect(dirs.text).toBe('1 dirs'); + }); +}); + +describe('PaneStats', () => { + let container: HTMLDivElement; + + beforeEach(() => { + container = document.createElement('div'); + document.body.appendChild(container); + }); + + afterEach(() => { + render(null, container); + document.body.removeChild(container); + }); + + it('separates items with a dot, one fewer than the items', async () => { + render(, container); + await flush(); + + expect(container.querySelectorAll('.pane-stats-item')).toHaveLength(3); + expect(container.querySelectorAll('.pane-stats-sep')).toHaveLength(2); + }); + + it('renders nothing at all when there are no items', async () => { + render(, container); + await flush(); + + expect(container.querySelector('.pane-stats')).toBeNull(); + }); +}); diff --git a/app/tests/layout/AppFooter.test.tsx b/app/tests/layout/AppFooter.test.tsx index 053371da..56e0f889 100644 --- a/app/tests/layout/AppFooter.test.tsx +++ b/app/tests/layout/AppFooter.test.tsx @@ -4,29 +4,7 @@ import { AppFooter } from '@/layout/AppFooter/AppFooter'; import { SERVER_CONFIG, DEFAULT_SERVER_CONFIG } from '@/state/stores/serverConfig'; import { flush } from '../_helpers/preact'; -describe('AppFooter — utility icon cluster', () => { - let container: HTMLDivElement; - - beforeEach(() => { - container = document.createElement('div'); - document.body.appendChild(container); - }); - - afterEach(() => { - render(null, container); - document.body.removeChild(container); - }); - - it('renders the keyboard-shortcuts button in the far-right cluster', async () => { - render(, container); - await flush(); - - const btn = container.querySelector('.app-footer-icons [aria-label="Keyboard shortcuts"]'); - expect(btn).not.toBeNull(); - }); -}); - -describe('AppFooter — credit line', () => { +describe('AppFooter', () => { let container: HTMLDivElement; beforeEach(() => { @@ -41,41 +19,43 @@ describe('AppFooter — credit line', () => { SERVER_CONFIG.value = DEFAULT_SERVER_CONFIG; }); - it('shows the running build version', async () => { + it('shows the running build version beside the status', async () => { render(, container); await flush(); - expect(container.querySelector('.app-footer-center')!.textContent).toContain('v1.3.0'); + const left = container.querySelector('.app-footer-left')!; + expect(left.textContent).toContain('v1.3.0'); + // Beside the status dot, not merely somewhere in the bar. + expect(left.querySelector('.app-footer-status')).not.toBeNull(); }); - it('links about to the repo and the credit to thalida.com', async () => { + it('credits the creator on the right, linked to thalida.com', async () => { render(, container); await flush(); - const links = Array.from(container.querySelectorAll('.app-footer-center a')); - expect(links.map((a) => a.getAttribute('href'))).toEqual([ - 'https://github.com/thalida/codecity', - 'https://thalida.com', - ]); - for (const a of links) { - expect(a.getAttribute('target')).toBe('_blank'); - expect(a.getAttribute('rel')).toBe('noopener noreferrer'); - } + const right = container.querySelector('.app-footer-right')!; + expect(right.textContent).toContain('🦄 thalida.'); + + const link = right.querySelector('a')!; + expect(link.getAttribute('href')).toBe('https://thalida.com'); + expect(link.getAttribute('target')).toBe('_blank'); + expect(link.getAttribute('rel')).toBe('noopener noreferrer'); }); - it('credits the creator with the unicorn', async () => { + it('no longer reads as a code comment', async () => { render(, container); await flush(); - expect(container.querySelector('.app-footer-center')!.textContent).toContain('🦄 thalida.'); + expect(container.querySelector('#app-footer')!.textContent).not.toContain('//'); }); - it('reads as a comment', async () => { + // About and the shortcuts button moved to the header; per-node stats moved to + // the selection pane. Nothing should have been left behind here. + it('holds neither the about link nor the shortcuts button', async () => { render(, container); await flush(); - expect(container.querySelector('.app-footer-center')!.textContent!.trimStart()).toMatch( - /^\/\// - ); + expect(container.querySelector('[aria-label="Keyboard shortcuts"]')).toBeNull(); + expect(container.querySelector('a[href="https://github.com/thalida/codecity"]')).toBeNull(); }); }); diff --git a/app/tests/layout/AppHeader.test.tsx b/app/tests/layout/AppHeader.test.tsx index ea06fe75..f512195b 100644 --- a/app/tests/layout/AppHeader.test.tsx +++ b/app/tests/layout/AppHeader.test.tsx @@ -64,6 +64,23 @@ describe('AppHeader', () => { expect(chip!.querySelector('.gem-icon')).not.toBeNull(); }); + it('puts about and the shortcuts button in the meta cluster', async () => { + loadProject(); + render(, container); + await flush(); + + const meta = container.querySelector('#app-header-meta')!; + expect(meta).not.toBeNull(); + + const about = meta.querySelector('a')!; + expect(about.textContent).toBe('about'); + expect(about.getAttribute('href')).toBe('https://github.com/thalida/codecity'); + expect(about.getAttribute('target')).toBe('_blank'); + expect(about.getAttribute('rel')).toBe('noopener noreferrer'); + + expect(meta.querySelector('[aria-label="Keyboard shortcuts"]')).not.toBeNull(); + }); + it('has no reset-view control', async () => { loadProject(); render(, container); From b1da5417c1d00798256eaf08a849a09125dcfdd7 Mon Sep 17 00:00:00 2001 From: Thalida Noel Date: Sat, 8 Aug 2026 21:12:30 -0400 Subject: [PATCH 15/19] Rebuild the hover tooltip as three lines that cannot overflow It was one flat line of path + a stat, joined by dots, with no width cap. A deep path made an arbitrarily wide card, and the only clamp was a flip to the other side of the cursor, which cannot help a card too wide to fit on either side: it pushed it off the opposite edge instead. Now: the name in strong text, the containing folder beneath it, and the stats last. The path drops whole middle segments to fit a budget, since truncating the tail would hide the end nearest the file. A max-width and per-line ellipsis back that up, because the budget counts characters and only approximates rendered width, and the placement clamps to the viewport after flipping. Stats come from the same builders the selection pane uses, so hover and pane cannot report different numbers, and hovering recovers some of the preview lost when the stats moved out of the app footer. Files pass dates: false to stay to one line. Commits lead with their subject, which is the most identifying thing about them and was previously unused. fileStatItems learned media dimensions, which the old tooltip special cased and the pane got wrong: a PNG reported 0 lines. Co-Authored-By: Claude Opus 5 (1M context) --- app/src/city/interaction/inputHandlers.ts | 8 +- app/src/city/interaction/tooltip.ts | 54 ++++-- app/src/city/interaction/tooltipText.ts | 128 ++++++++++----- app/src/components/PaneStats/statItems.ts | 26 ++- app/src/styles/cards.css | 30 +++- app/tests/city/interaction/tooltip.test.ts | 63 ++++++- .../city/interaction/tooltipText.test.ts | 154 +++++++++++++----- app/tests/components/paneStats.test.tsx | 28 +++- 8 files changed, 374 insertions(+), 117 deletions(-) diff --git a/app/src/city/interaction/inputHandlers.ts b/app/src/city/interaction/inputHandlers.ts index 6010d97d..be99e2ea 100644 --- a/app/src/city/interaction/inputHandlers.ts +++ b/app/src/city/interaction/inputHandlers.ts @@ -20,7 +20,7 @@ import { MODAL_OPEN } from '@/state/stores/ui'; import { NodeKind } from '@/types'; import { scrubbedStatsFor } from '@/state/stores/presentPaths'; import type { PickTarget } from '@/types'; -import { formatHoverTooltip, isDeletedTarget } from './tooltipText'; +import { hoverTooltipContent, type TooltipContent } from './tooltipText'; import type { createPicker } from './picker'; import type { createCameraRig } from '../render/cameraRig'; import type { CityState } from '../state'; @@ -41,7 +41,7 @@ export function createInputHandlers({ rig: ReturnType; renderer: THREE.WebGLRenderer; cityState: CityState; - showTooltip: (text: string, x: number, y: number, deleted?: boolean) => void; + showTooltip: (content: TooltipContent, x: number, y: number) => void; hideTooltip: () => void; onResize: () => void; /** Reset-view action triggered by R / gem-click. Does NOT rebuild the @@ -112,9 +112,9 @@ export function createInputHandlers({ newHover?.kind === NodeKind.File && newHover.file?.path != null ? (scrubbedStatsFor(newHover.file.path)?.lines ?? null) : null; - const tooltipText = formatHoverTooltip(newHover, rootName, scrubLines); + const tooltipText = hoverTooltipContent(newHover, rootName, scrubLines); if (tooltipText) { - showTooltip(tooltipText, e.clientX, e.clientY, isDeletedTarget(newHover)); + showTooltip(tooltipText, e.clientX, e.clientY); canvas.style.cursor = 'pointer'; } else { hideTooltip(); diff --git a/app/src/city/interaction/tooltip.ts b/app/src/city/interaction/tooltip.ts index 23a05797..811dc8f1 100644 --- a/app/src/city/interaction/tooltip.ts +++ b/app/src/city/interaction/tooltip.ts @@ -1,8 +1,7 @@ -// city/interaction/tooltip.ts — Tiny floating label that follows the cursor -// on hover. Shown when the user is hovering a building/street; hidden -// otherwise. Inspired by Cities: Skylines / SimCity — every interactive -// object has a brief name label so the city feels alive without forcing -// a sidebar open. +// city/interaction/tooltip.ts — Tiny floating card that follows the cursor on +// hover. Shown when the user is hovering a building/street/commit; hidden +// otherwise. Inspired by Cities: Skylines / SimCity — every interactive object +// has a brief label so the city feels alive without forcing a sidebar open. // // The imperative showTooltip/moveTooltip/hideTooltip API is kept for the // still-vanilla scene code (picker, inputHandlers) that calls it directly. @@ -10,6 +9,8 @@ // driven by Three.js pointer events rather than React-tree state — the // imperative API IS the right interface for this component. +import type { TooltipContent } from './tooltipText'; + // Tooltip placement — fixed, not user-tunable. const TOOLTIP_OFFSET_PX = 14; const TOOLTIP_VIEWPORT_MARGIN_PX = 4; @@ -27,25 +28,40 @@ function _ensure(): HTMLElement { return _el; } -// showTooltip(text, x, y, deleted?) — show with the given text, positioned near -// cursor (with auto-clamp to viewport so it doesn't bleed off-screen). When -// `deleted`, lead with a red "deleted" badge so a ruin reads at a glance. -export function showTooltip(text: string, x: number, y: number, deleted = false): void { +function _line(cls: string, text: string): HTMLElement { + const line = document.createElement('div'); + line.className = cls; + line.textContent = text; + return line; +} + +/** + * Show the tooltip near the cursor, clamped so it can't leave the viewport. + * Three stacked lines: identity, location, stats. + */ +export function showTooltip(content: TooltipContent, x: number, y: number): void { const el = _ensure(); - if (deleted) { - el.textContent = ''; + el.textContent = ''; + + const title = _line('tooltip-title', content.title); + if (content.deleted) { const badge = document.createElement('span'); badge.className = 'tooltip-deleted'; badge.textContent = 'deleted'; - el.append(badge, document.createTextNode(` · ${text}`)); - } else { - el.textContent = text; + title.prepend(badge, document.createTextNode(' ')); } + el.append(title); + + if (content.path) el.append(_line('tooltip-path', content.path)); + if (content.stats.length > 0) { + el.append(_line('tooltip-stats', content.stats.join(' · '))); + } + el.style.display = 'block'; moveTooltip(x, y); } -// moveTooltip(x, y) — reposition without changing text. Cheap; safe to call +// moveTooltip(x, y) — reposition without changing content. Cheap; safe to call // on every pointermove. export function moveTooltip(x: number, y: number): void { if (!_el) return; @@ -55,10 +71,18 @@ export function moveTooltip(x: number, y: number): void { const h = _el.offsetHeight; const vw = window.innerWidth; const vh = window.innerHeight; + + // Prefer below-right of the cursor, flipping to the other side when that + // would overflow. The final clamp matters independently: a card wider than + // the space on either side overflows whichever way it is flipped, and + // flipping alone would push it off the opposite edge. let px = x + OFFSET; let py = y + OFFSET; if (px + w + MARGIN > vw) px = x - OFFSET - w; if (py + h + MARGIN > vh) py = y - OFFSET - h; + px = Math.min(Math.max(px, MARGIN), Math.max(MARGIN, vw - w - MARGIN)); + py = Math.min(Math.max(py, MARGIN), Math.max(MARGIN, vh - h - MARGIN)); + _el.style.left = `${px}px`; _el.style.top = `${py}px`; } diff --git a/app/src/city/interaction/tooltipText.ts b/app/src/city/interaction/tooltipText.ts index a00d78b2..dd28ddad 100644 --- a/app/src/city/interaction/tooltipText.ts +++ b/app/src/city/interaction/tooltipText.ts @@ -1,75 +1,123 @@ -// city/interaction/tooltipText.ts — Pure formatting for the hover tooltip -// label. Given a pick target and the project's root directory name, returns -// the one-line string shown next to the cursor (or null when nothing should -// show). Kept side-effect-free so it's unit-testable in isolation; the live -// wiring in inputHandlers.ts reads the root name off the manifest signal and -// hands it in. +// city/interaction/tooltipText.ts — Pure content for the hover tooltip. Given a +// pick target and the project's root directory name, returns the three parts the +// renderer draws (or null when nothing should show). Side-effect-free so it's +// unit-testable in isolation; the live wiring in inputHandlers.ts reads the root +// name off the manifest signal and hands it in. +// +// Stats come from the same builders the selection pane uses, so hovering a +// building and selecting it cannot report different numbers. import { NodeKind } from '@/types'; import type { PickTarget } from '@/types'; import { formatRelativeAge } from '@/utils/dates'; import { ROOT_PATH } from '@/constants/manifest'; +import { fileStatItems, directoryStatItems } from '@/components/PaneStats/statItems'; -// Prepend the root directory name (with a leading slash) to a manifest- -// relative path so the tooltip reads as an absolute-looking path (e.g. -// "/codecity/app/main.ts" rather than "app/main.ts"). The root's own path is -// ROOT_PATH — we render just "/codecity", not "codecity/.". +/** Longest path rendered before the middle segments collapse to an ellipsis. */ +const PATH_BUDGET_CHARS = 44; + +export interface TooltipContent { + /** Identity line: a filename, a folder name, or a commit subject. */ + title: string; + /** Location line, already truncated. Absent where a path means nothing. */ + path?: string; + /** Third line, joined with separators by the renderer. */ + stats: string[]; + /** Ruin at the scrubbed commit: the renderer leads with a red badge. */ + deleted: boolean; +} + +// Prepend the root directory name (with a leading slash) to a manifest-relative +// path so it reads as absolute-looking (e.g. "/codecity/app" rather than "app"). +// The root's own path is ROOT_PATH — render just "/codecity", not "codecity/.". function withRoot(relPath: string, rootName: string | null): string { if (!rootName) return relPath || ''; if (!relPath || relPath === ROOT_PATH) return `/${rootName}`; return `/${rootName}/${relPath}`; } -export function formatHoverTooltip( +/** The path minus its last segment: what the title line already shows. */ +function parentOf(relPath: string): string { + const cut = relPath.lastIndexOf('/'); + return cut === -1 ? '' : relPath.slice(0, cut); +} + +/** + * Drop whole segments from the middle until the path fits the budget, keeping + * the first and last. Truncating the tail instead would hide the segment + * nearest the file, which is the informative end. + */ +export function middleTruncatePath(path: string, budget = PATH_BUDGET_CHARS): string { + if (path.length <= budget) return path; + const lead = path.startsWith('/') ? '/' : ''; + const segments = path.slice(lead.length).split('/'); + if (segments.length <= 2) return path; + + // Walk inward from the middle, dropping one segment at a time. + const kept = segments.slice(); + while (kept.length > 2) { + kept.splice(Math.floor(kept.length / 2), 1); + const candidate = `${lead}${kept[0]}/…/${kept.slice(1).join('/')}`; + if (candidate.length <= budget) return candidate; + } + return `${lead}${kept[0]}/…/${kept[kept.length - 1]}`; +} + +export function hoverTooltipContent( target: PickTarget | null, rootName: string | null, // Timeline: lines at the scrubbed commit, or at deletion for a file already gone. scrubLines?: number | null -): string | null { +): TooltipContent | null { if (!target) return null; + const deleted = isDeletedTarget(target); + if (target.kind === NodeKind.Gem) { - // The gem represents the project root and also acts as the reset - // button — clicking it clears the selection and recenters the - // camera. Show both so the affordance is discoverable. - return `${withRoot('', rootName)} · click to reset view`; + // The gem represents the project root and also acts as the reset button, so + // name the affordance to keep it discoverable. + return { title: rootName ?? 'project', stats: ['click to reset view'], deleted: false }; } + if (target.kind === NodeKind.Commit) { const c = target.commit; - const shortSha = c.sha.slice(0, 7); - const filesLabel = `${c.files} file${c.files === 1 ? '' : 's'}`; - return `commit ${shortSha} · ${formatRelativeAge(c.date)} · ${filesLabel}`; + const authors = c.authors.length > 0 ? c.authors[0] : null; + const stats = [c.sha.slice(0, 7)]; + if (authors) stats.push(authors); + stats.push(formatRelativeAge(c.date)); + stats.push(`${c.files} file${c.files === 1 ? '' : 's'}`); + return { title: c.subject || `commit ${c.sha.slice(0, 7)}`, stats, deleted: false }; } + if (target.kind === NodeKind.File && target.file) { const f = target.file; - const fpath = withRoot(f.path || f.name || 'file', rootName); - // Media files (images/video) are binary, so their line count is a - // meaningless 0 — surface pixel dimensions instead. The backend only - // stamps media_width/height on recognized media, so their presence is a - // reliable "this is dimensioned media" signal. - if (f.media_width != null && f.media_height != null) { - return `${fpath} · ${f.media_width}×${f.media_height}`; - } - const lines = scrubLines ?? f.lines; - return fpath + (lines != null ? ` · ${lines} lines` : ''); + const rel = f.path || f.name || 'file'; + const parent = parentOf(rel); + // scrubLines wins where the replay has a value for this commit. + const node = scrubLines != null ? { ...f, lines: scrubLines } : f; + return { + title: f.name || rel, + path: middleTruncatePath(withRoot(parent, rootName)), + stats: fileStatItems(node, { dates: false }).map((i) => i.text), + deleted, + }; } + if (target.kind === NodeKind.Directory && target.dir) { const d = target.dir; - const dpath = withRoot(d.path || d.name || '', rootName); - // Show immediate-child counts (not descendants) — the tooltip is a - // quick "what's directly inside here", not a subtree summary. - const fileCount = d.children_file_count != null ? d.children_file_count : 0; - const dirCount = d.children_dir_count != null ? d.children_dir_count : 0; - const counts = `${fileCount} file${fileCount === 1 ? '' : 's'}, ${dirCount} dir${ - dirCount === 1 ? '' : 's' - }`; - return `${dpath || 'directory'} · ${counts}`; + const rel = d.path || d.name || ''; + const isRoot = !rel || rel === ROOT_PATH; + return { + title: isRoot ? (rootName ?? 'root') : d.name || rel, + path: isRoot ? undefined : middleTruncatePath(withRoot(parentOf(rel), rootName)), + stats: directoryStatItems(d).map((i) => i.text), + deleted, + }; } + return null; } // Whether a hovered file/dir is a ghost-ruin (deleted at the scrubbed commit). -// The tooltip renderer leads with a red "deleted" badge for these, so the marker -// lives with the render, not in this identity-text formatter. export function isDeletedTarget(target: PickTarget | null): boolean { if (target?.kind === NodeKind.File || target?.kind === NodeKind.Directory) { return Boolean(target.isRuin); diff --git a/app/src/components/PaneStats/statItems.ts b/app/src/components/PaneStats/statItems.ts index ad2754de..086299a7 100644 --- a/app/src/components/PaneStats/statItems.ts +++ b/app/src/components/PaneStats/statItems.ts @@ -38,7 +38,16 @@ function ageItem(iso: string, label: string, now: number): PaneStatItem { }; } -export function fileStatItems(file: FileNode, now: number = Date.now()): PaneStatItem[] { +export interface FileStatOpts { + /** Include the created/modified ages. The hover tooltip drops them to stay + * to a single line; the pane has the room. Defaults to true. */ + dates?: boolean; + /** Reference point for the relative ages. Defaults to now. */ + now?: number; +} + +export function fileStatItems(file: FileNode, opts: FileStatOpts = {}): PaneStatItem[] { + const { dates = true, now = Date.now() } = opts; const items: PaneStatItem[] = []; // In Timeline the static node carries max-over-history values, so the replayed // ones win where they exist (at deletion for a file already gone). @@ -48,10 +57,19 @@ export function fileStatItems(file: FileNode, now: number = Date.now()): PaneSta const language = humanLanguageFor(file); if (language) items.push({ text: language }); - if (lines != null) items.push({ text: `${lines} lines` }); + // Media is binary, so its line count is a meaningless 0: the pixel dimensions + // are the size that means something. The backend only stamps media_width and + // media_height on recognized media, so their presence is the signal. + if (file.media_width != null && file.media_height != null) { + items.push({ text: `${file.media_width}×${file.media_height}` }); + } else if (lines != null) { + items.push({ text: `${lines} lines` }); + } if (size != null) items.push({ text: formatBytes(size) }); - if (file.modified) items.push(ageItem(file.modified, 'modified', now)); - if (file.created) items.push(ageItem(file.created, 'created', now)); + if (dates) { + if (file.modified) items.push(ageItem(file.modified, 'modified', now)); + if (file.created) items.push(ageItem(file.created, 'created', now)); + } return items; } diff --git a/app/src/styles/cards.css b/app/src/styles/cards.css index 05965e41..9e6c950b 100644 --- a/app/src/styles/cards.css +++ b/app/src/styles/cards.css @@ -35,12 +35,38 @@ background: var(--cc-bg-tooltip); border: 1px solid var(--cc-border-tooltip); border-radius: var(--cc-radius-sm); - padding: var(--cc-space-2) var(--cc-space-4); + padding: var(--cc-space-3) var(--cc-space-4); box-shadow: var(--cc-shadow-md); + /* A hard cap the path truncation cannot overshoot: the truncation budget is + counted in characters, which only approximates rendered width. */ + max-width: 340px; +} + +/* Three stacked lines: what it is, where it lives, what it measures. Each + clips on its own so one long value can't widen the card. */ +.tooltip-title, +.tooltip-path, +.tooltip-stats { + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; +} +.tooltip-title { + color: var(--cc-text-strong); + font-weight: var(--cc-fw-semibold); +} +.tooltip-path { + color: var(--cc-text-muted); + font-family: var(--cc-font-mono); + font-size: var(--cc-font-2xs); +} +.tooltip-stats { + color: var(--cc-text-secondary); + font-size: var(--cc-font-xs); } /* Leading "deleted" badge on a ruin's hover tooltip — red + bold so it reads - at a glance before the path. */ + at a glance before the name. */ .tooltip-deleted { color: var(--cc-error-light); font-weight: var(--cc-fw-semibold); diff --git a/app/tests/city/interaction/tooltip.test.ts b/app/tests/city/interaction/tooltip.test.ts index eae3c444..6983cf90 100644 --- a/app/tests/city/interaction/tooltip.test.ts +++ b/app/tests/city/interaction/tooltip.test.ts @@ -1,5 +1,10 @@ import { describe, it, expect, afterEach } from 'vitest'; import { showTooltip, hideTooltip, moveTooltip } from '@/city/interaction/tooltip'; +import type { TooltipContent } from '@/city/interaction/tooltipText'; + +function content(partial: Partial = {}): TooltipContent { + return { title: 'hello.ts', stats: [], deleted: false, ...partial }; +} describe('tooltip', () => { afterEach(() => { @@ -7,38 +12,80 @@ describe('tooltip', () => { if (el && el.parentNode) el.parentNode.removeChild(el); }); - it('showTooltip creates a #hover-tooltip element with the text', () => { - showTooltip('hello.ts', 100, 200); + it('showTooltip creates a #hover-tooltip element with the title', () => { + showTooltip(content(), 100, 200); const el = document.getElementById('hover-tooltip')!; expect(el).not.toBeNull(); - expect(el.textContent).toBe('hello.ts'); + expect(el.querySelector('.tooltip-title')!.textContent).toBe('hello.ts'); expect(el.style.display).toBe('block'); }); + it('stacks the path and stats as their own lines', () => { + showTooltip(content({ path: '/repo/app', stats: ['typescript', '50 lines'] }), 0, 0); + const el = document.getElementById('hover-tooltip')!; + expect(el.querySelector('.tooltip-path')!.textContent).toBe('/repo/app'); + expect(el.querySelector('.tooltip-stats')!.textContent).toContain('typescript'); + expect(el.querySelector('.tooltip-stats')!.textContent).toContain('50 lines'); + }); + + it('omits the path and stats lines when there is nothing to put in them', () => { + showTooltip(content(), 0, 0); + const el = document.getElementById('hover-tooltip')!; + expect(el.querySelector('.tooltip-path')).toBeNull(); + expect(el.querySelector('.tooltip-stats')).toBeNull(); + }); + + it('leads a ruin with the deleted badge', () => { + showTooltip(content({ deleted: true }), 0, 0); + const el = document.getElementById('hover-tooltip')!; + const badge = el.querySelector('.tooltip-deleted')!; + expect(badge.textContent).toBe('deleted'); + expect(el.querySelector('.tooltip-title')!.contains(badge)).toBe(true); + }); + it('showTooltip positions near the cursor with a default offset', () => { - showTooltip('foo', 50, 60); + showTooltip(content({ title: 'foo' }), 50, 60); const el = document.getElementById('hover-tooltip')!; expect(el.style.left).toBe('64px'); // 50 + 14 expect(el.style.top).toBe('74px'); // 60 + 14 }); + // Regression: flipping to the other side of the cursor was the only clamp, so + // a card too wide to fit on either side was pushed off the opposite edge. + // Reproducing it needs a card wider than half the viewport, with the cursor + // far enough right that the flip fires. + it('never positions the card off the left or top edge', () => { + showTooltip(content(), 5, 5); + const el = document.getElementById('hover-tooltip')!; + const wide = window.innerWidth - 120; + const tall = window.innerHeight - 120; + Object.defineProperty(el, 'offsetWidth', { value: wide, configurable: true }); + Object.defineProperty(el, 'offsetHeight', { value: tall, configurable: true }); + + // Mid-viewport: far enough right that the flip fires, but with less room to + // the left than the card needs, so the flip lands off-screen. + moveTooltip(window.innerWidth / 2, window.innerHeight / 2); + expect(parseFloat(el.style.left)).toBeGreaterThanOrEqual(0); + expect(parseFloat(el.style.top)).toBeGreaterThanOrEqual(0); + }); + it('moveTooltip is safe before showTooltip (no-op)', () => { expect(() => moveTooltip(10, 20)).not.toThrow(); }); it('hideTooltip sets display:none', () => { - showTooltip('x', 0, 0); + showTooltip(content({ title: 'x' }), 0, 0); hideTooltip(); const el = document.getElementById('hover-tooltip')!; expect(el.style.display).toBe('none'); }); it('reuses the same element across multiple shows', () => { - showTooltip('first', 0, 0); + showTooltip(content({ title: 'first' }), 0, 0); const first = document.getElementById('hover-tooltip'); - showTooltip('second', 0, 0); + showTooltip(content({ title: 'second' }), 0, 0); const second = document.getElementById('hover-tooltip')!; expect(first).toBe(second); - expect(second.textContent).toBe('second'); + expect(second.querySelector('.tooltip-title')!.textContent).toBe('second'); }); }); diff --git a/app/tests/city/interaction/tooltipText.test.ts b/app/tests/city/interaction/tooltipText.test.ts index 31dbf923..1a23f8b0 100644 --- a/app/tests/city/interaction/tooltipText.test.ts +++ b/app/tests/city/interaction/tooltipText.test.ts @@ -1,5 +1,9 @@ import { describe, it, expect } from 'vitest'; -import { formatHoverTooltip, isDeletedTarget } from '@/city/interaction/tooltipText'; +import { + hoverTooltipContent, + isDeletedTarget, + middleTruncatePath, +} from '@/city/interaction/tooltipText'; import { NodeKind } from '@/types'; import type { FileNode, DirNode } from '@/types'; import type { PickTarget } from '@/types'; @@ -34,83 +38,151 @@ function dirTarget(partial: Partial): PickTarget { } as PickTarget; } -describe('formatHoverTooltip', () => { +describe('middleTruncatePath', () => { + it('leaves a path that already fits', () => { + expect(middleTruncatePath('/repo/app/src', 44)).toBe('/repo/app/src'); + }); + + it('drops middle segments, keeping the root and the deepest folder', () => { + const out = middleTruncatePath('/repo/app/src/layout/views/deeply/nested/here', 30); + expect(out.startsWith('/repo/')).toBe(true); + expect(out.endsWith('here')).toBe(true); + expect(out).toContain('…'); + expect(out.length).toBeLessThanOrEqual(30); + }); + + it('cannot truncate a two-segment path, so it leaves it whole', () => { + const long = '/averyveryverylongsingledirectorynamethatwontfit/leaf'; + expect(middleTruncatePath(long, 20)).toBe(long); + }); +}); + +describe('hoverTooltipContent', () => { it('returns null for no target', () => { - expect(formatHoverTooltip(null, 'codecity')).toBeNull(); + expect(hoverTooltipContent(null, 'codecity')).toBeNull(); + }); + + it('leads with the filename and puts its folder underneath', () => { + const t = fileTarget({ name: 'main.ts', path: 'app/main.ts', lines: 42 }); + const c = hoverTooltipContent(t, 'codecity')!; + expect(c.title).toBe('main.ts'); + expect(c.path).toBe('/codecity/app'); + expect(c.stats).toContain('42 lines'); }); - it('shows line count for a plain text file', () => { - const t = fileTarget({ path: 'app/main.ts', lines: 42 }); - expect(formatHoverTooltip(t, 'codecity')).toBe('/codecity/app/main.ts · 42 lines'); + it('leaves the dates to the pane, keeping the hover line short', () => { + const t = fileTarget({ + name: 'main.ts', + path: 'app/main.ts', + lines: 42, + modified: '2024-03-20T10:00:00Z', + created: '2024-01-10T09:00:00Z', + }); + const c = hoverTooltipContent(t, 'codecity')!; + expect(c.stats.some((s) => s.startsWith('modified'))).toBe(false); + expect(c.stats.some((s) => s.startsWith('created'))).toBe(false); }); it('prefers the scrubbed line count (Timeline) over the static FileNode.lines', () => { - const t = fileTarget({ path: 'app/main.ts', lines: 42 }); // union max - // scrubLines is the count at the scrubbed commit — the height's source. - expect(formatHoverTooltip(t, 'codecity', 7)).toBe('/codecity/app/main.ts · 7 lines'); + const t = fileTarget({ name: 'main.ts', path: 'app/main.ts', lines: 42 }); // union max + expect(hoverTooltipContent(t, 'codecity', 7)!.stats).toContain('7 lines'); // null (Live / no timeline) falls back to FileNode.lines. - expect(formatHoverTooltip(t, 'codecity', null)).toBe('/codecity/app/main.ts · 42 lines'); + expect(hoverTooltipContent(t, 'codecity', null)!.stats).toContain('42 lines'); }); it('renders a deleted file the count it is given (the at-deletion value)', () => { - // scrubbedStatsFor resolves "what it measured when deleted"; this stays a - // pure formatter and just prints what it is handed. - const t = { ...fileTarget({ path: 'app/gone.py', lines: 0 }), isRuin: true } as PickTarget; - expect(formatHoverTooltip(t, 'codecity', 214)).toBe('/codecity/app/gone.py · 214 lines'); - }); - - it('keeps pixel dimensions on a deleted media file (intrinsic, not replayed)', () => { const t = { - ...fileTarget({ path: 'app/logo.png', media_width: 800, media_height: 600 }), + ...fileTarget({ name: 'gone.py', path: 'app/gone.py', lines: 0 }), isRuin: true, } as PickTarget; - expect(formatHoverTooltip(t, 'codecity', 0)).toBe('/codecity/app/logo.png · 800×600'); + const c = hoverTooltipContent(t, 'codecity', 214)!; + expect(c.stats).toContain('214 lines'); + expect(c.deleted).toBe(true); }); it('shows pixel dimensions instead of line count for an image file', () => { const t = fileTarget({ + name: 'logo.png', path: 'app/logo.png', lines: 0, mediaKind: 'image', media_width: 1920, media_height: 1080, }); - expect(formatHoverTooltip(t, 'codecity')).toBe('/codecity/app/logo.png · 1920×1080'); + const c = hoverTooltipContent(t, 'codecity')!; + expect(c.stats).toContain('1920×1080'); + expect(c.stats.some((s) => s.includes('lines'))).toBe(false); }); it('falls back to line count when a media file has no dimensions', () => { - const t = fileTarget({ path: 'app/clip.mp4', lines: 0, mediaKind: 'video' }); - expect(formatHoverTooltip(t, 'codecity')).toBe('/codecity/app/clip.mp4 · 0 lines'); + const t = fileTarget({ name: 'clip.mp4', path: 'app/clip.mp4', lines: 0, mediaKind: 'video' }); + expect(hoverTooltipContent(t, 'codecity')!.stats).toContain('0 lines'); }); - it('omits the suffix when a file has no line count', () => { - const t = fileTarget({ path: 'app/empty', lines: null as unknown as number }); - expect(formatHoverTooltip(t, 'codecity')).toBe('/codecity/app/empty'); + it('names a directory and counts what is inside it', () => { + const t = dirTarget({ + name: 'app', + path: 'app', + children_file_count: 3, + descendants_file_count: 9, + children_dir_count: 1, + descendants_dir_count: 1, + }); + const c = hoverTooltipContent(t, 'codecity')!; + expect(c.title).toBe('app'); + expect(c.stats.some((s) => s.includes('files'))).toBe(true); }); - it('shows immediate child counts for a directory', () => { - const t = dirTarget({ path: 'app', children_file_count: 3, children_dir_count: 1 }); - expect(formatHoverTooltip(t, 'codecity')).toBe('/codecity/app · 3 files, 1 dir'); + it('titles the repo root with the root name and gives it no parent path', () => { + const t = dirTarget({ name: '.', path: '.', children_file_count: 1, children_dir_count: 0 }); + const c = hoverTooltipContent(t, 'codecity')!; + expect(c.title).toBe('codecity'); + expect(c.path).toBeUndefined(); }); - it('prepends the root name as an absolute-looking path', () => { - const t = fileTarget({ path: 'a.ts', lines: 1 }); - expect(formatHoverTooltip(t, 'myrepo')).toBe('/myrepo/a.ts · 1 lines'); + it('drops the root segment when there is no root name', () => { + const t = fileTarget({ name: 'a.ts', path: 'app/a.ts', lines: 1 }); + expect(hoverTooltipContent(t, null)!.path).toBe('app'); }); - it('drops the root segment when there is no root name', () => { - const t = fileTarget({ path: 'a.ts', lines: 1 }); - expect(formatHoverTooltip(t, null)).toBe('a.ts · 1 lines'); + it('leads a commit with its subject, details beneath', () => { + const t = { + kind: NodeKind.Commit, + commit: { + sha: 'a7f3c9d1234567', + date: '2024-03-20T10:00:00Z', + files: 6, + authors: ['thalida'], + subject: 'Widen the default tree canopy', + same_day_total: 1, + }, + } as PickTarget; + const c = hoverTooltipContent(t, 'codecity')!; + expect(c.title).toBe('Widen the default tree canopy'); + expect(c.stats).toContain('a7f3c9d'); + expect(c.stats).toContain('thalida'); + expect(c.stats).toContain('6 files'); }); - it('leaves the identity text clean for a ghost-ruin (the deleted badge is a render concern)', () => { - const f = { ...fileTarget({ path: 'a.ts', lines: 1 }), isRuin: true } as PickTarget; - expect(formatHoverTooltip(f, 'r')).toBe('/r/a.ts · 1 lines'); - const d = { - ...dirTarget({ path: 'app', children_file_count: 2, children_dir_count: 0 }), - isRuin: true, + it('falls back to the sha when a commit has no subject', () => { + const t = { + kind: NodeKind.Commit, + commit: { + sha: 'a7f3c9d1234567', + date: '2024-03-20T10:00:00Z', + files: 1, + authors: [], + subject: '', + same_day_total: 1, + }, } as PickTarget; - expect(formatHoverTooltip(d, 'r')).toBe('/r/app · 2 files, 0 dirs'); + expect(hoverTooltipContent(t, 'codecity')!.title).toBe('commit a7f3c9d'); + }); + + it('names the reset affordance on the gem', () => { + const c = hoverTooltipContent({ kind: NodeKind.Gem } as PickTarget, 'codecity')!; + expect(c.title).toBe('codecity'); + expect(c.stats).toContain('click to reset view'); }); }); diff --git a/app/tests/components/paneStats.test.tsx b/app/tests/components/paneStats.test.tsx index 4745d78a..b80fee27 100644 --- a/app/tests/components/paneStats.test.tsx +++ b/app/tests/components/paneStats.test.tsx @@ -41,21 +41,43 @@ const DIR: DirNode = { describe('statItems', () => { it('describes a file by language, size, and age', () => { - const texts = fileStatItems(FILE, NOW).map((i) => i.text); + const texts = fileStatItems(FILE, { now: NOW }).map((i) => i.text); expect(texts).toContain('50 lines'); expect(texts.some((t) => t.startsWith('modified '))).toBe(true); expect(texts.some((t) => t.startsWith('created '))).toBe(true); }); it('carries the exact date as the tooltip behind a relative age', () => { - const modified = fileStatItems(FILE, NOW).find((i) => i.text.startsWith('modified '))!; + const modified = fileStatItems(FILE, { now: NOW }).find((i) => i.text.startsWith('modified '))!; expect(modified.title).toBeTruthy(); expect(modified.title).not.toBe(modified.text); }); + it('drops the dates when the caller asks for the short form', () => { + const texts = fileStatItems(FILE, { now: NOW, dates: false }).map((i) => i.text); + expect(texts).toContain('50 lines'); + expect(texts.some((t) => t.startsWith('modified'))).toBe(false); + expect(texts.some((t) => t.startsWith('created'))).toBe(false); + }); + + it('reports pixel dimensions for media instead of a meaningless line count', () => { + const png: FileNode = { + ...FILE, + name: 'logo.png', + extension: '.png', + binary: true, + lines: 0, + media_width: 800, + media_height: 600, + }; + const texts = fileStatItems(png, { now: NOW }).map((i) => i.text); + expect(texts).toContain('800×600'); + expect(texts.some((t) => t.includes('lines'))).toBe(false); + }); + it('omits stats the node does not carry', () => { const bare: FileNode = { ...FILE, lines: null, size: null, created: null, modified: null }; - const texts = fileStatItems(bare, NOW).map((i) => i.text); + const texts = fileStatItems(bare, { now: NOW }).map((i) => i.text); expect(texts.some((t) => t.includes('lines'))).toBe(false); expect(texts.some((t) => t.startsWith('modified'))).toBe(false); }); From 7933181544b28944741473ad91caa6bdaafd28cc Mon Sep 17 00:00:00 2001 From: Thalida Noel Date: Sat, 8 Aug 2026 21:16:34 -0400 Subject: [PATCH 16/19] Frost the tooltip, and say "directory" before counting one The tooltip rode on --cc-bg-tooltip: translucent at 94% with no blur, so the city showed through raw and muddied the smallest text in the app. It floats on the canvas like the panels do, so it takes .surface-glass, and the token it was the only consumer of goes away. A directory stat row now leads with its kind. A folder named `app` and a file named `app` look alike, and the counts that follow only mean something once you know which one you are reading. Co-Authored-By: Claude Opus 5 (1M context) --- app/src/city/interaction/tooltip.ts | 2 +- app/src/components/PaneStats/statItems.ts | 4 +++- app/src/styles/cards.css | 4 ++-- app/src/styles/tokens.css | 1 - app/tests/city/interaction/tooltipText.test.ts | 2 ++ app/tests/components/paneStats.test.tsx | 4 ++++ 6 files changed, 12 insertions(+), 5 deletions(-) diff --git a/app/src/city/interaction/tooltip.ts b/app/src/city/interaction/tooltip.ts index 811dc8f1..f53557cd 100644 --- a/app/src/city/interaction/tooltip.ts +++ b/app/src/city/interaction/tooltip.ts @@ -22,7 +22,7 @@ function _ensure(): HTMLElement { if (_el && _el.isConnected) return _el; _el = document.createElement('div'); _el.id = 'hover-tooltip'; - _el.className = 'card-tooltip'; + _el.className = 'card-tooltip surface-glass'; _el.style.display = 'none'; document.body.appendChild(_el); return _el; diff --git a/app/src/components/PaneStats/statItems.ts b/app/src/components/PaneStats/statItems.ts index 086299a7..a516c261 100644 --- a/app/src/components/PaneStats/statItems.ts +++ b/app/src/components/PaneStats/statItems.ts @@ -74,7 +74,9 @@ export function fileStatItems(file: FileNode, opts: FileStatOpts = {}): PaneStat } export function directoryStatItems(dir: DirNode): PaneStatItem[] { - const items: PaneStatItem[] = []; + // Lead with the kind: a folder named `app` and a file named `app` look alike, + // and the counts that follow only make sense once you know which this is. + const items: PaneStatItem[] = [{ text: 'directory' }]; const files = countItem(dir.children_file_count, dir.descendants_file_count, 'files'); if (files) items.push(files); const dirs = countItem(dir.children_dir_count, dir.descendants_dir_count, 'dirs'); diff --git a/app/src/styles/cards.css b/app/src/styles/cards.css index 9e6c950b..e87f2dd3 100644 --- a/app/src/styles/cards.css +++ b/app/src/styles/cards.css @@ -30,9 +30,9 @@ padding: var(--cc-space-3) var(--cc-space-6); } -/* Floating tooltip surface (the hover tooltip). */ +/* Floating tooltip surface (the hover tooltip). Pair with .surface-glass: it + rides directly on the canvas. */ .card-tooltip { - background: var(--cc-bg-tooltip); border: 1px solid var(--cc-border-tooltip); border-radius: var(--cc-radius-sm); padding: var(--cc-space-3) var(--cc-space-4); diff --git a/app/src/styles/tokens.css b/app/src/styles/tokens.css index bcf19b6b..23cb90ce 100644 --- a/app/src/styles/tokens.css +++ b/app/src/styles/tokens.css @@ -35,7 +35,6 @@ --cc-bg-sidebar: oklch(0.181 0.019 279.4); --cc-bg-modal: var(--cc-bg-sidebar); /* alias — modal uses the same panel surface as sidebars */ --cc-bg-backdrop: color-mix(in oklch, var(--cc-black) 55%, transparent); - --cc-bg-tooltip: color-mix(in oklch, var(--cc-bg-app) 94%, transparent); --cc-bg-base: var(--cc-bg-app); /* ── COLORS — Borders & tracks ────────────────────────────────────────── */ diff --git a/app/tests/city/interaction/tooltipText.test.ts b/app/tests/city/interaction/tooltipText.test.ts index 1a23f8b0..30a556b8 100644 --- a/app/tests/city/interaction/tooltipText.test.ts +++ b/app/tests/city/interaction/tooltipText.test.ts @@ -130,6 +130,8 @@ describe('hoverTooltipContent', () => { }); const c = hoverTooltipContent(t, 'codecity')!; expect(c.title).toBe('app'); + // A folder named `app` and a file named `app` look alike without it. + expect(c.stats[0]).toBe('directory'); expect(c.stats.some((s) => s.includes('files'))).toBe(true); }); diff --git a/app/tests/components/paneStats.test.tsx b/app/tests/components/paneStats.test.tsx index b80fee27..f7345c74 100644 --- a/app/tests/components/paneStats.test.tsx +++ b/app/tests/components/paneStats.test.tsx @@ -82,6 +82,10 @@ describe('statItems', () => { expect(texts.some((t) => t.startsWith('modified'))).toBe(false); }); + it('names the kind before the counts that depend on it', () => { + expect(directoryStatItems(DIR)[0].text).toBe('directory'); + }); + it('shows a directory total alongside its direct count when they differ', () => { const files = directoryStatItems(DIR).find((i) => i.text.includes('files'))!; expect(files.text).toBe('3 files (9 total)'); From 48848292a95998837dca24cd5090f6fce69a14b0 Mon Sep 17 00:00:00 2001 From: Thalida Noel Date: Sat, 8 Aug 2026 21:18:51 -0400 Subject: [PATCH 17/19] Let glass borders take their cast from what is behind them The tooltip's border was oklch(0.32 0.058 274.6): three times the surface's chroma and hue-shifted bluer. Absolute colours were fine when the panels were opaque, but a glass fill picks up whatever is behind it while the border holds one fixed hue, so the edge read cool against a panel that no longer was. --cc-glass-border is alpha, like the fill, so the edge shifts with the surface. The modal and landing cards had the same mismatch through --cc-border-subtle, less visibly because its chroma is lower. Declared per consumer rather than on .surface-glass, so the borderless glass (scrubber, mode toggle) stays borderless and no cascade order decides the colour. --cc-border-tooltip stays for the InfoPane blockquote that still uses it. Co-Authored-By: Claude Opus 5 (1M context) --- app/src/styles/cards.css | 2 +- app/src/styles/modal.css | 8 ++++---- app/src/styles/tokens.css | 3 +++ app/src/views/ProjectsView/ProjectsView.css | 2 +- 4 files changed, 9 insertions(+), 6 deletions(-) diff --git a/app/src/styles/cards.css b/app/src/styles/cards.css index e87f2dd3..178dda31 100644 --- a/app/src/styles/cards.css +++ b/app/src/styles/cards.css @@ -33,7 +33,7 @@ /* Floating tooltip surface (the hover tooltip). Pair with .surface-glass: it rides directly on the canvas. */ .card-tooltip { - border: 1px solid var(--cc-border-tooltip); + border: 1px solid var(--cc-glass-border); border-radius: var(--cc-radius-sm); padding: var(--cc-space-3) var(--cc-space-4); box-shadow: var(--cc-shadow-md); diff --git a/app/src/styles/modal.css b/app/src/styles/modal.css index 60b4b104..6dcfe5c8 100644 --- a/app/src/styles/modal.css +++ b/app/src/styles/modal.css @@ -29,10 +29,10 @@ flex-direction: column; overflow: hidden; font-family: inherit; - /* A faint full border (header-divider color) lifts the modal off the blurred - backdrop, and an even, slightly darker shadow (no downward offset) rings it - equally rather than casting downward. */ - border: 1px solid var(--cc-border-subtle); + /* A faint alpha border lifts the modal off the blurred backdrop and shifts + with whatever shows through it, and an even shadow (no downward offset) + rings it equally rather than casting downward. */ + border: 1px solid var(--cc-glass-border); box-shadow: 0 0 40px oklch(0 0 0 / 0.7); } diff --git a/app/src/styles/tokens.css b/app/src/styles/tokens.css index 23cb90ce..61613f53 100644 --- a/app/src/styles/tokens.css +++ b/app/src/styles/tokens.css @@ -111,6 +111,9 @@ own fill (the timeline's error toast) still blurs by this radius. */ --cc-glass-fill: color-mix(in oklch, var(--cc-bg-modal) 82%, transparent); --cc-glass-blur: 12px; + /* Alpha, not an absolute colour: an opaque border would hold one fixed hue + while the fill takes its cast from whatever is behind the panel. */ + --cc-glass-border: var(--cc-overlay-border); /* ── COLORS — Pure neutrals ───────────────────────────────────────────── */ --cc-black: oklch(0 0 0); diff --git a/app/src/views/ProjectsView/ProjectsView.css b/app/src/views/ProjectsView/ProjectsView.css index acee6295..047dfc3a 100644 --- a/app/src/views/ProjectsView/ProjectsView.css +++ b/app/src/views/ProjectsView/ProjectsView.css @@ -188,7 +188,7 @@ flex-direction: column; gap: var(--cc-space-4); padding: var(--cc-space-7); - border: 1px solid var(--cc-border-subtle); + border: 1px solid var(--cc-glass-border); border-radius: var(--cc-radius-lg); } From 415bd54e0a0bbe5ba3de824d0a976ff3257890ec Mon Sep 17 00:00:00 2001 From: Thalida Noel Date: Sat, 8 Aug 2026 21:22:09 -0400 Subject: [PATCH 18/19] Tint every border and track with the chosen surface themes.css swaps --cc-bg-app/-chrome/-sidebar across four presets but overrode no border token, so picking warm or green gave you a warm panel ringed by a cool blue border, and every divider, input outline and slider track in the app stayed at hue ~276 regardless. Borders and tracks now derive from --cc-bg-sidebar with relative color syntax: lightness as an offset, chroma as a multiplier, hue straight through. Both constants are measured off the default surface, so the cool theme is unchanged to the eye while the others carry their own cast. A preset only has to swap the surface; no border restates anything. The multiplier matters: today's borders are more saturated than the surface they sit on, so passing chroma through unchanged would have washed out the default theme. Behind @supports, since relative color syntax has no per-declaration fallback. A custom property holding a value the engine cannot parse fails at substitution rather than at parse time, which would drop every border to currentColor instead of to the absolute value above it. This supersedes the alpha glass border: it was neutral, and neutral was the one thing that would not follow the surface. The existing hierarchy, a brighter edge on the tooltip than on the panels, now tints along with everything else. Co-Authored-By: Claude Opus 5 (1M context) --- app/src/styles/cards.css | 2 +- app/src/styles/modal.css | 8 +++--- app/src/styles/tokens.css | 31 ++++++++++++++++++--- app/src/views/ProjectsView/ProjectsView.css | 2 +- 4 files changed, 33 insertions(+), 10 deletions(-) diff --git a/app/src/styles/cards.css b/app/src/styles/cards.css index 178dda31..e87f2dd3 100644 --- a/app/src/styles/cards.css +++ b/app/src/styles/cards.css @@ -33,7 +33,7 @@ /* Floating tooltip surface (the hover tooltip). Pair with .surface-glass: it rides directly on the canvas. */ .card-tooltip { - border: 1px solid var(--cc-glass-border); + border: 1px solid var(--cc-border-tooltip); border-radius: var(--cc-radius-sm); padding: var(--cc-space-3) var(--cc-space-4); box-shadow: var(--cc-shadow-md); diff --git a/app/src/styles/modal.css b/app/src/styles/modal.css index 6dcfe5c8..415f8270 100644 --- a/app/src/styles/modal.css +++ b/app/src/styles/modal.css @@ -29,10 +29,10 @@ flex-direction: column; overflow: hidden; font-family: inherit; - /* A faint alpha border lifts the modal off the blurred backdrop and shifts - with whatever shows through it, and an even shadow (no downward offset) - rings it equally rather than casting downward. */ - border: 1px solid var(--cc-glass-border); + /* A faint border lifts the modal off the blurred backdrop, and an even + shadow (no downward offset) rings it equally rather than casting + downward. */ + border: 1px solid var(--cc-border-subtle); box-shadow: 0 0 40px oklch(0 0 0 / 0.7); } diff --git a/app/src/styles/tokens.css b/app/src/styles/tokens.css index 61613f53..7e779cd7 100644 --- a/app/src/styles/tokens.css +++ b/app/src/styles/tokens.css @@ -37,7 +37,11 @@ --cc-bg-backdrop: color-mix(in oklch, var(--cc-black) 55%, transparent); --cc-bg-base: var(--cc-bg-app); - /* ── COLORS — Borders & tracks ────────────────────────────────────────── */ + /* ── COLORS — Borders & tracks ────────────────────────────────────────── + Absolute fallbacks, matching the default (cool) surface exactly. The + @supports block below rewrites them as offsets from the surface itself so + they follow whichever preset is picked; these values are what engines + without relative color syntax keep. */ --cc-border-subtle: oklch(0.249 0.03 278.4); --cc-border-input: oklch(0.281 0.03 276.1); --cc-border-tooltip: oklch(0.32 0.058 274.6); @@ -111,9 +115,6 @@ own fill (the timeline's error toast) still blurs by this radius. */ --cc-glass-fill: color-mix(in oklch, var(--cc-bg-modal) 82%, transparent); --cc-glass-blur: 12px; - /* Alpha, not an absolute colour: an opaque border would hold one fixed hue - while the fill takes its cast from whatever is behind the panel. */ - --cc-glass-border: var(--cc-overlay-border); /* ── COLORS — Pure neutrals ───────────────────────────────────────────── */ --cc-black: oklch(0 0 0); @@ -205,3 +206,25 @@ --cc-shadow-text: 0 1px 2px oklch(0 0 0 / 0.5); /* canvas overlay text */ --cc-glow-accent: 0 0 6px color-mix(in oklch, var(--cc-accent) 35%, transparent); /* range-pair fill */ } + +/* Borders and tracks, derived from the surface so a preset tints every edge with + it. themes.css swaps only --cc-bg-*, and these resolve against whichever value + wins, so no preset has to restate a border. + + Lightness is an offset and chroma a multiplier, both measured off the default + surface, so the cool theme renders identically to the absolute values above + while a warmer or more neutral surface carries its own hue and saturation + through. Hue passes straight through. + + @supports because relative color syntax has no per-declaration fallback: a + custom property holding an unparseable value fails at substitution, which + would leave every border at currentColor rather than at the value above. */ +@supports (color: oklch(from white l c h)) { + :root { + --cc-border-subtle: oklch(from var(--cc-bg-sidebar) calc(l + 0.068) calc(c * 1.58) h); + --cc-border-input: oklch(from var(--cc-bg-sidebar) calc(l + 0.1) calc(c * 1.58) h); + --cc-border-tooltip: oklch(from var(--cc-bg-sidebar) calc(l + 0.139) calc(c * 3.05) h); + --cc-track: oklch(from var(--cc-bg-sidebar) calc(l + 0.049) calc(c * 1.21) h); + --cc-track-hover: oklch(from var(--cc-bg-sidebar) calc(l + 0.174) calc(c * 2.21) h); + } +} diff --git a/app/src/views/ProjectsView/ProjectsView.css b/app/src/views/ProjectsView/ProjectsView.css index 047dfc3a..acee6295 100644 --- a/app/src/views/ProjectsView/ProjectsView.css +++ b/app/src/views/ProjectsView/ProjectsView.css @@ -188,7 +188,7 @@ flex-direction: column; gap: var(--cc-space-4); padding: var(--cc-space-7); - border: 1px solid var(--cc-glass-border); + border: 1px solid var(--cc-border-subtle); border-radius: var(--cc-radius-lg); } From da8f2c00595a03de72759e7ba6a5cb7a76c1facc Mon Sep 17 00:00:00 2001 From: Thalida Noel Date: Sat, 8 Aug 2026 21:24:29 -0400 Subject: [PATCH 19/19] Settle the glass fill at 90% Co-Authored-By: Claude Opus 5 (1M context) --- app/src/styles/tokens.css | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/src/styles/tokens.css b/app/src/styles/tokens.css index 7e779cd7..c7ffc40f 100644 --- a/app/src/styles/tokens.css +++ b/app/src/styles/tokens.css @@ -113,7 +113,7 @@ scrubber, the mode toggle, the modals and the landing cards frost the scene identically. Applied via .surface-glass; a surface that needs its own fill (the timeline's error toast) still blurs by this radius. */ - --cc-glass-fill: color-mix(in oklch, var(--cc-bg-modal) 82%, transparent); + --cc-glass-fill: color-mix(in oklch, var(--cc-bg-modal) 90%, transparent); --cc-glass-blur: 12px; /* ── COLORS — Pure neutrals ───────────────────────────────────────────── */