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

The guide lists every kind of file the viewer opens, generated from the same table the viewer reads #13891

Merged opened this

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

Merged

scout/forge:scout/13869-the-guide-lists-every-kind-of-file-the-v → main 5 commits fork 6 threads · 6 unresolved

  • Merged. scout/13869-the-guide-lists-every-kind-of-file-the-v was merged into main as 42e1c5f.

Review

Sign in to review this change.
6 files changed +211 −1
docs/features/README.md +1
@@ -272,6 +272,7 @@ Read with the guide page [Your apps](../guide-your-apps.md).
272272
273273 ### Files in the browser
274274
275 - [Every kind of file the viewer opens, and how large](file-kinds.md)
275276 - [An .obj or .ply file opens in the 3D viewer](mesh-files.md)
276277 - [An .stl file as a 3D model](file-stl.md)
277278 - [A .dxf file as a picture](file-dxf.md)
docs/features/file-kinds.md added +62
@@ -0,0 +1,62 @@
1 # Which files open
2
3 The forge draws a file on its page when its kind is below and it is within the size shown; over that, the page shows the source or offers Download.
4
5 <!-- file-kinds:begin (generated by scripts/kinds-guide.ts from src/web/render/kinds.ts; edit the code, then run `bun scripts/kinds-guide.ts`) -->
6
7 - **Image**, drawn up to 50 MB: `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.avif`, `.bmp`, `.ico`
8 - **SVG**, drawn up to 5 MB: `.svg`
9 - **PDF**, drawn up to 100 MB: `.pdf`
10 - **HTML page**, drawn up to 2 MB: `.html`, `.htm`
11 - **Audio**, drawn up to 500 MB: `.mp3`, `.ogg`, `.oga`, `.wav`, `.flac`, `.m4a`, `.aac`
12 - **Video**, drawn up to 4 GB: `.mp4`, `.m4v`, `.webm`, `.mov`
13 - **Table (CSV, TSV, JSON lines)**, drawn up to 10 MB: `.csv`, `.tsv`, `.jsonl`, `.ndjson`
14 - **SQLite database**, drawn up to 5 MB: `.db`, `.sqlite`, `.sqlite3`
15 - **3D model**, drawn up to 100 MB: `.stl`, `.3mf`, `.ply`, `.glb`, `.gltf`, `.obj`
16 - **Archive**, drawn up to 50 MB: `.zip`, `.tar`, `.tgz`, `.tar.gz`
17 - **Spreadsheet**, drawn up to 10 MB: `.xlsx`
18 - **Word document**, drawn up to 10 MB: `.docx`
19 - **Slides**, drawn up to 10 MB: `.pptx`
20 - **Layered image**, drawn up to 20 MB: `.ora`
21 - **Font**, drawn up to 20 MB: `.ttf`, `.otf`, `.woff`, `.woff2`
22 - **Photoshop**, drawn up to 4 GB: `.psd`
23 - **Config**, drawn up to 1 MB: `.json`, `.jsonc`, `.yaml`, `.yml`, `.toml`, `.ini`, `.conf`
24 - **Markdown**, drawn up to 1 MB: `.md`, `.markdown`, `.mdx`
25 - **Notebook**, drawn up to 1 MB: `.ipynb`
26 - **Patch**, drawn up to 1 MB: `.patch`, `.diff`
27 - **Log**, drawn up to 1 MB: `.log`, `.ansi`
28 - **Subtitles**, drawn up to 5 MB: `.srt`, `.vtt`
29 - **GPS track**, drawn up to 20 MB: `.gpx`
30 - **HTTP archive**, drawn up to 5 MB: `.har`
31 - **GeoJSON**, drawn up to 5 MB: `.geojson`
32 - **KML**, drawn up to 5 MB: `.kml`
33 - **Calendar**, drawn up to 5 MB: `.ics`
34 - **OpenTimelineIO**, drawn up to 1 MB: `.otio`
35 - **Edit list**, drawn up to 1 MB: `.edl`
36 - **Final Cut XML**, drawn up to 1 MB: `.fcpxml`
37 - **Contacts**, drawn up to 1 MB: `.vcf`, `.vcard`
38 - **Email**, drawn up to 5 MB: `.eml`
39 - **G-code**, drawn up to 50 MB: `.gcode`, `.gco`
40 - **DXF drawing**, drawn up to 5 MB: `.dxf`, a file that opens on 0 then SECTION
41 - **Mermaid diagram**, drawn up to 1 MB: `.mmd`, `.mermaid`
42 - **draw.io diagram**, drawn up to 1 MB: `.drawio`
outdated

Nested backticks break the code span and the sentence is prose. Principle 8: write it as plain text (a file that opens on 0 then SECTION), not as an extension in code.

43 - **Excalidraw**, drawn up to 1 MB: `.excalidraw`
44 - **STEP model**, drawn up to 5 MB: `.step`, `.stp`
45 - **SARIF report**, drawn up to 5 MB: `.sarif`
46 - **Coverage (lcov)**, drawn up to 5 MB: `.lcov`, `lcov.info`
47 - **JUnit report**, drawn up to 5 MB: `*.junit.xml`, `TEST-*.xml`, `.xml with a <testsuite> root`
48 - **OPML**, drawn up to 5 MB: `.opml`, `.xml with an <opml> root`
outdated

.lcov appears twice. Dedupe in kindMatches / BY_NAME.

49 - **RSS or Atom feed**, drawn up to 5 MB: `.rss`, `.atom`, `.xml with an <rss>, <feed> or <rdf:RDF> root`
50 - **Env example**, drawn up to 1 MB: `.env.example`, `.env.sample`, `.env.template`
51 - **OpenAPI**, drawn up to 1 MB: `openapi.json`, `openapi.yaml`, `openapi.yml`, `*.openapi.*`
52 - **package.json**, drawn up to 1 MB: `package.json`
53 - **Makefile**, drawn up to 1 MB: `Makefile`, `GNUmakefile`, `*.mk`
54 - **Dockerfile**, drawn up to 1 MB: `Dockerfile`, `Containerfile`, `*.Dockerfile`
55 - **GitHub workflow**, drawn up to 1 MB: `.github/workflows/*.yml`, `.github/workflows/*.yaml`
56 - **Compose file**, drawn up to 1 MB: `compose.yaml`, `compose.yml`, `docker-compose.yaml`, `docker-compose.yml`
57 - **SQL**, drawn up to 1 MB: `.sql`
58 - **GraphQL**, drawn up to 1 MB: `.graphql`, `.gql`
59 - **Other text**, drawn up to 1 MB: any other text
60 - **Other binary**, none: download only: any other bytes
61
outdated

'any other text' and 'any other bytes' are prose shown as code; render plain.

62 <!-- file-kinds:end -->
docs/guide-your-apps.md +5 −1
@@ -12,7 +12,7 @@ Every app has an address on the forge. To use your own, open the app's Settings,
1212
1313 ## Environment and secrets
1414
15 Variables are set in the app's Settings, App pane: a name, a value, and where it applies (production or previews). A name ending `_KEY`, `_SECRET` or `_TOKEN` is hidden after you save it. A `.env.example` file in the repository opens as a table of what the app needs ([file-env](features/file-env.md)). Never commit a real secret.
15 Variables are set in the app's Settings, App pane: a name, a value, and where it applies (production or previews). A name ending `_KEY`, `_SECRET` or `_TOKEN` is hidden after you save it. A `.env.example` file in the repository opens as a table of what the app needs. Never commit a real secret.
1616
1717 Your own account's keys, tokens and passkeys are at `/settings/secrets`, `/settings/tokens` and `/settings/passkeys`.
1818
@@ -35,6 +35,10 @@ The forge wakes a sleeping app at that time and calls the path. Printing a daily
3535
3636 An app's own data lives under `FORGE_APP_DATA`. See [an app's encrypted backup](features/app-backup.md).
3737
38 ## Which files open
39
40 Every kind of file the viewer draws, and its size limit: [which files open](features/file-kinds.md).
41
3842 Reference: [apps](APPS.md). Next: [Hosting forges](guide-hosting.md).
3943
4044 Every feature note, by topic: [the reference notes](features/README.md).
scripts/kinds-guide.ts added +54
@@ -0,0 +1,54 @@
1 /**
2 * Rewrite the file-kind table in docs/features/file-kinds.md from `kinds.ts`:
3 * `bun scripts/kinds-guide.ts`.
4 */
5 import { ALL_KINDS, RENDER_CAP, kindContent, kindMatches, type FileKind } from "../src/web/render/kinds.ts";
6
7 export const BEGIN = "<!-- file-kinds:begin (generated by scripts/kinds-guide.ts from src/web/render/kinds.ts; edit the code, then run `bun scripts/kinds-guide.ts`) -->";
8 export const END = "<!-- file-kinds:end -->";
9
10 /** The name a person says for each kind. A new kind without one fails the type check. */
11 export const NAMES: Readonly<Record<FileKind, string>> = {
12 image: "Image", svg: "SVG", pdf: "PDF", html: "HTML page", audio: "Audio", video: "Video", csv: "Table (CSV, TSV, JSON lines)",
13 sqlite: "SQLite database", model3d: "3D model", archive: "Archive", sheet: "Spreadsheet", document: "Word document",
14 slides: "Slides", layers: "Layered image", font: "Font", psd: "Photoshop", config: "Config", markdown: "Markdown",
15 notebook: "Notebook", patch: "Patch", log: "Log", subtitles: "Subtitles", gpx: "GPS track", har: "HTTP archive",
16 geojson: "GeoJSON", kml: "KML", calendar: "Calendar", otio: "OpenTimelineIO", edl: "Edit list", fcpxml: "Final Cut XML",
17 contacts: "Contacts", mail: "Email", gcode: "G-code", dxf: "DXF drawing", mermaid: "Mermaid diagram", drawio: "draw.io diagram",
18 excalidraw: "Excalidraw", step: "STEP model", sarif: "SARIF report", lcov: "Coverage (lcov)", junit: "JUnit report",
19 opml: "OPML", feed: "RSS or Atom feed", env: "Env example", openapi: "OpenAPI", package: "package.json", makefile: "Makefile",
20 dockerfile: "Dockerfile", workflow: "GitHub workflow", compose: "Compose file", sql: "SQL", graphql: "GraphQL",
21 text: "Other text", binary: "Other binary",
22 };
23
24 /** 1_000_000 as `1 MB`; 4_000_000_000 as `4 GB`; no cap as `none: download only`. */
25 export function capText(bytes: number): string {

Comment says nothing is - but the code returns 'none: download only'. Make them agree.

26 if (bytes <= 0) return "none: download only";
27 return bytes >= 1_000_000_000 ? `${bytes / 1_000_000_000} GB` : `${bytes / 1_000_000} MB`;
28 }
29
30 /** One line to a kind, so a narrow screen wraps the names instead of squeezing a column. */
31 export function renderKinds(): string {
32 return ALL_KINDS.map((k) => {
33 const names = [...kindMatches(k).map((m) => `\`${m}\``), ...(kindContent(k) === undefined ? [] : [kindContent(k)])];
34 const cap = RENDER_CAP[k] > 0 ? `, drawn up to ${capText(RENDER_CAP[k])}` : `, ${capText(RENDER_CAP[k])}`;
35 return `- **${NAMES[k]}**${cap}: ${names.join(", ")}`;
36 }).join("\n");
37 }
38
39 export function kindsIn(doc: string): string {
40 const a = doc.indexOf(BEGIN), b = doc.indexOf(END);
41 if (a < 0 || b < a) throw new Error("docs/features/file-kinds.md has no file-kinds markers");
42 return doc.slice(a + BEGIN.length, b).trim();
43 }
44
45 export function withKinds(doc: string, table: string): string {
46 const a = doc.indexOf(BEGIN), b = doc.indexOf(END);
47 if (a < 0 || b < a) throw new Error("docs/features/file-kinds.md has no file-kinds markers");
48 return `${doc.slice(0, a + BEGIN.length)}\n\n${table}\n\n${doc.slice(b)}`;
49 }
50
51 if (import.meta.main) {
52 const path = new URL("../docs/features/file-kinds.md", import.meta.url);
53 await Bun.write(path, withKinds(await Bun.file(path).text(), renderKinds()));
54 }
src/web/render/kinds.ts +47
@@ -529,3 +529,50 @@ const SNIFFED: readonly (readonly [string, Magic])[] = [
529529 export function sniffType(head: Uint8Array): string {
530530 return SNIFFED.find(([, is]) => is(head))?.[0] ?? "binary data";
531531 }
532
533 /** Every kind, in the order the guide lists them: media first, then data, then text formats. */
534 export const ALL_KINDS: readonly FileKind[] = Object.keys(RENDER_CAP) as FileKind[];
535
536 /** Kinds that no extension names: a file name, a root element or the bytes decide. */
537 const BY_NAME: Readonly<Partial<Record<FileKind, readonly string[]>>> = {
538 junit: ["*.junit.xml", "TEST-*.xml", ".xml with a <testsuite> root"],
539 opml: [".xml with an <opml> root"],
540 feed: [".xml with an <rss>, <feed> or <rdf:RDF> root"],
541 env: [".env.example", ".env.sample", ".env.template"],
542 openapi: ["openapi.json", "openapi.yaml", "openapi.yml", "*.openapi.*"],
543 package: ["package.json"],
544 makefile: ["Makefile", "GNUmakefile", "*.mk"],
545 dockerfile: ["Dockerfile", "Containerfile", "*.Dockerfile"],
546 workflow: [".github/workflows/*.yml", ".github/workflows/*.yaml"],
547 compose: ["compose.yaml", "compose.yml", "docker-compose.yaml", "docker-compose.yml"],
548 lcov: ["lcov.info"],
outdated

lcov: '.lcov' is already produced from TEXTUAL; drop it here, which removes the duplicate in the guide.

549 archive: [".tar.gz"],
550 };
551
552 /** Kinds named in words, not by a name: shown as plain text, never as code. */
553 const BY_CONTENT: Readonly<Partial<Record<FileKind, string>>> = {
554 dxf: "a file that opens on 0 then SECTION",
555 text: "any other text",
556 binary: "any other bytes",
557 };
558
559 /**
560 * Extensions the sniffing tables above do not list: `.xlsx` is checked by its zip entries, not
561 * named.
562 */
563 const SNIFFED_EXTENSIONS: Readonly<Partial<Record<FileKind, readonly string[]>>> = {
564 sheet: ["xlsx"],
outdated

Redundant if xlsx is already in OFFICE/TEXTUAL; and line 563 is convoluted (adds tar.gz inside a loop). Remove or simplify, and cover with a test.

565 archive: ["zip", "tar", "tgz"],
566 };
567
568 /** What names a kind, for the guide: extensions and file names, each once, to show as code. */
569 export function kindMatches(kind: FileKind): string[] {
570 const exts = new Set<string>(SNIFFED_EXTENSIONS[kind] ?? []);
571 for (const [ext, m] of Object.entries(MEDIA)) if (m.kind === kind) exts.add(ext);
572 for (const [ext, k] of Object.entries(TEXTUAL)) if (k === kind) exts.add(ext);
573 for (const [ext, k] of Object.entries(OFFICE)) if (k === kind) exts.add(ext);
574 return [...[...exts].map((e) => `.${e}`), ...(BY_NAME[kind] ?? [])];
575 }
576
577 /** What a kind is named by in words, when no name does: shown as plain text. */
578 export const kindContent = (kind: FileKind): string | undefined => BY_CONTENT[kind];
test/kinds-guide.test.ts added +42
@@ -0,0 +1,42 @@
1 import { expect, test } from "bun:test";
2 import { readFileSync } from "node:fs";
3 import { renderKinds, kindsIn, withKinds } from "../scripts/kinds-guide.ts";
4 import { ALL_KINDS, fileKind, kindMatches, RENDER_CAP } from "../src/web/render/kinds.ts";
5 import { RENDERERS } from "../src/web/render/renderers.ts";
6
7 const DOC = readFileSync(new URL("../docs/features/file-kinds.md", import.meta.url), "utf8");
8
9 test("the guide holds the file-kind table the code renders", () => {
10 expect(kindsIn(DOC), "docs/features/file-kinds.md is stale: run bun scripts/kinds-guide.ts").toBe(renderKinds());
11 });
12
13 test("a stale table is caught and withKinds repairs it", () => {
14 const stale = withKinds(DOC, renderKinds().replace("SQLite database", "Nope"));
15 expect(kindsIn(stale)).not.toBe(renderKinds());
16 expect(withKinds(stale, renderKinds())).toBe(DOC);
17 expect(() => withKinds("nothing", "t")).toThrow("markers");
18 });
19
20 test("every kind has a renderer, except text and binary, which keep the source view", () => {
21 const without = ALL_KINDS.filter((k) => RENDERERS[k] === undefined && k !== "text" && k !== "binary");
22 expect(without, `kind(s) with no renderer registered in renderers.ts: ${without.join(", ")}`).toEqual([]);
23 });
24
25 test("every kind is listed with a cap, and a named extension resolves to its kind", () => {
26 expect(ALL_KINDS.length).toBe(Object.keys(RENDER_CAP).length);
27 expect(kindMatches("sqlite")).toContain(".sqlite");
28 expect(renderKinds()).toContain("- **SQLite database**, drawn up to 5 MB: `.db`, `.sqlite`, `.sqlite3`");
29 expect(fileKind("a.tsv", new Uint8Array([97]))).toBe("csv");
30 });
31
32 test("a name is shown once, prose is plain text, and sheets and archives are named", () => {
33 for (const k of ALL_KINDS) {
34 const names = kindMatches(k);
35 expect({ k, dup: names.length !== new Set(names).size }).toEqual({ k, dup: false });
36 }
37 expect(kindMatches("lcov")).toEqual([".lcov", "lcov.info"]);
38 expect(kindMatches("sheet")).toEqual([".xlsx"]);
39 expect(kindMatches("archive").sort()).toEqual([".tar", ".tar.gz", ".tgz", ".zip"]);
40 expect(renderKinds()).toContain("- **DXF drawing**, drawn up to 5 MB: `.dxf`, a file that opens on 0 then SECTION");
41 expect(renderKinds()).toContain("- **Other binary**, none: download only: any other bytes");
42 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs