Public: anyone can read this; the crew can change it.

A .kml file opens as its placemarks: name, description and coordinates in a table #13411

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

A `.kml` file now opens as a table of its placemarks: name, description, longitude and latitude. I ran `tsc`, `gate.ts`, `design-lint` and three test files (`render-kml`, `render-kinds`, `fuzz-renderers`), and all pass. I did not run the full suite or open a `.kml` page in a running app.

shipped production is serving it deploy 7fd75b3

opened this

A .kml file now opens as a table of its placemarks: name, description, longitude and latitude. I ran tsc, gate.ts, design-lint and three test files (render-kml, render-kinds, fuzz-renderers), and all pass. I did not run the full suite or open a .kml page in a running app.

  • Kind: kml is registered in kinds.ts by extension, with a 5 MB size cap, and it is wired into renderers.ts. The media type stays application/octet-stream, like the other map kinds.
  • Parsing: src/web/render/kml.ts reuses the tag scanner from gpx.ts and adds no dependency. The scanner reads only the five built-in entities and numeric references. A DOCTYPE is skipped, so no entity or DTD is expanded, and anything like &lol; stays literal text.
  • Table: The first 500 placemarks are listed, and a note says "first 500 of N" when there are more. Descriptions are escaped text, so a CDATA block holding HTML shows its tags rather than applying them. Each description is clipped to 300 characters.
  • Malformed files: Mismatched tags, a root that isn't kml, text outside the root, or a file with no placemark all keep the source view with a one-line notice.
  • Tests: test/render-kml.test.ts covers a good file, the 500 cap, malformed files, and a hostile entity file. I also added a .kml sample to test/render-kinds.test.ts, because that suite requires one for every known extension.

Left out:

  • Only the first coordinate of a placemark is shown, so a LineString or Polygon appears as its first vertex.
  • No route or map drawing.
  • No terminal (TUI) view for .kml.
  • The first push was refused because no commit said how to try the change. I added an empty commit with a "Try:" line, so the branch has that extra commit.

Try it: commit any .kml file and open its blob page.

Closes #13383

2 earlier comments · 1 event
commented

A .kml file now opens as a table of its placemarks: name, description, longitude and latitude. I ran tsc, gate.ts, design-lint and three test files (render-kml, render-kinds, fuzz-renderers), and all pass. I did not run the full suite or open a .kml page in a running app.

  • Kind: kml is registered in kinds.ts by extension, with a 5 MB size cap, and it is wired into renderers.ts. The media type stays application/octet-stream, like the other map kinds.
  • Parsing: src/web/render/kml.ts reuses the tag scanner from gpx.ts and adds no dependency. The scanner reads only the five built-in entities and numeric references. A DOCTYPE is skipped, so no entity or DTD is expanded, and anything like &lol; stays literal text.
  • Table: The first 500 placemarks are listed, and a note says "first 500 of N" when there are more. Descriptions are escaped text, so a CDATA block holding HTML shows its tags rather than applying them. Each description is clipped to 300 characters.
  • Malformed files: Mismatched tags, a root that isn't kml, text outside the root, or a file with no placemark all keep the source view with a one-line notice.
  • Tests: test/render-kml.test.ts covers a good file, the 500 cap, malformed files, and a hostile entity file. I also added a .kml sample to test/render-kinds.test.ts, because that suite requires one for every known extension.

Left out:

  • Only the first coordinate of a placemark is shown, so a LineString or Polygon appears as its first vertex.
  • No route or map drawing.
  • No terminal (TUI) view for .kml.
  • The first push was refused because no commit said how to try the change. I added an empty commit with a "Try:" line, so the branch has that extra commit.

Try it: commit any .kml file and open its blob page.

commented

A .kml file now opens as a table of its placemarks, on the web page and in the terminal. A person assigned the issue; I'm recording that in a commit line, not a code comment. The earlier push failed the "both doors" gate rule, and the local gate is clean after this push. I have not seen the forge's check verdict on it yet.

What changed

  • Web: src/web/render/kml.ts parses KML and renders the table. kml is a kind in kinds.ts (decided by extension, 5 MB cap) and is registered in renderers.ts.
  • Parsing: It reuses gpx.ts's tag scanner and adds no dependency. A DOCTYPE is skipped and only the five built-in entities and numeric references are decoded, so nothing is expanded. Anything else, like &lol;, stays literal text.
  • Rows: Each row has name, description, longitude and latitude, capped at 500 placemarks with a "first 500 of N" note. Descriptions are escaped text, clipped to 300 characters.
  • Malformed files: Mismatched tags, a root other than kml, or no placemark keep the source view with a one-line notice.
  • Terminal: New src/tui/screens/kml.ts builds the same table for the terminal, wired into workspace.ts the way GeoJSON is. This is what the "both doors" gate wanted. s flips to the source.
  • Tests: test/render-kml.test.ts covers a good file, the 500 cap, malformed files and a hostile entity. test/tui-workspace-formats.test.ts covers the terminal door, and test/render-kinds.test.ts has a .kml sample.

Verification: tsc is clean. The three tests files for this change pass (render-kml, render-kinds, tui-workspace-formats), plus fuzz-renderers from the first push. I did not run the full suite. bun scripts/fast.ts named nearly every test file for this diff, so I ran only the files that cover the change.

Left out

  • Only the first coordinate of a placemark is shown, so a LineString or Polygon appears as its first vertex.
  • No route or map drawing.
  • No docs/features/ page.
  • The terminal table clips descriptions to 80 characters.

Gate lines in commit messages:

  • A "Try:" line, which the pre-push hook required.
  • "No look:", because no page in app.looks shows a .kml.
  • "Direction:", because the "pipeline first" rule asks for a reason when a feature file is added.

How to try it: commit a .kml file to a repository and open its blob page, or open it from the terminal workspace.

Changes requested — before the latest push

The change does what the issue asks and the code is clean (reuses gpx's scanner, no dependency, escaped output, entities never expanded, cap and fallback tested). One change needed: there is no docs/features/kml.md. AGENTS.md requires a feature's how-to there, with one row in docs/features/README.md (test/feature-orphans.test.ts), next to geojson.md and gpx.md; the pull's 'left out' list admits it is missing. Add it: what a .kml shows, the 500 cap, 300-char (web) and 80-char (terminal) description clips, first coordinate only, malformed files keep the source view, how to open it in the terminal. Smaller, do in the same round: (a) the table has no phone treatment I could verify, no .kml appears in the forge's pictures, so confirm the .gj-table scroll region works at 360px; (b) a LineString/Polygon shows only its first vertex with no hint, so say so in the doc.

commented

This round adds the missing how-to for .kml files, docs/features/kml.md, plus its row in docs/features/README.md next to the GeoJSON and GPX entries. It is a docs-only change; no code was touched.

The doc covers what a .kml shows (name, description, longitude, latitude) and how to open it on the web and in the terminal, where s flips to the source. It also covers:

  • Cap: 500 placemarks, with a "Showing the first 500 of N" line for the rest.
  • Clips: descriptions are cut at 300 characters on the web and 80 in the terminal.
  • Coordinates: only the first coordinate of a placemark is shown. A LineString or Polygon shows its first vertex only, and the table gives no hint that more follows. This is stated plainly in the doc, as you asked, rather than changed in the UI.
  • Malformed files: they keep the source view.

On the 360px question, I checked it by reading the CSS, not by viewing a screenshot. The table sits in the .gj-table region (src/web/style/content.ts:587), which has overflow-x: auto; max-width: 100%. Cells wrap long words. So it scrolls sideways inside the column and does not widen the page; the doc says so. I did not run a browser at 360px.

I ran bun x tsc --noEmit, bun scripts/gate.ts --fix and test/feature-orphans.test.ts; all pass.

Approved

The earlier asks are met: docs/features/kml.md exists and is indexed in docs/features/README.md, the terminal screen is wired in with a test, and the first-coordinate-only limit is stated plainly. The table is a focusable, labelled, sideways-scrolling region, so it will not widen a 360px page. It is server-rendered and works with JavaScript off. Nothing new in this round breaks the design principles. Two things I would do next. First, Non-blocking: show a hint in the row, such as a vertex count, when a LineString or Polygon has more than its first coordinate. Second, Non-blocking: add a test that a description over 300 characters is clipped.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs