Give the published page a card

A link to the site showed a URL and a blank square. It now carries a title, a
description, a canonical URL, an icon and a full set of OpenGraph and Twitter
tags, so a page nobody has opened yet arrives as something you can look at.

Two of those tags have to be ABSOLUTE and it is not a style question: a
scraper fetching the page has no base to resolve `/cover.png` against and
drops it silently. `build-site.ts` now copies the images into the output as
well, because an `og:image` pointing at this host has to have the file ON this
host — a card that 404s shows nothing, and nothing about the page itself looks
wrong while it happens.

The cover is a real 1200x630 render rather than a crop of a square one, which
took a change to the renderer worth having anyway. `newFrame` and
`frameCamera` both took a width and a height already; only `renderOne` was
insisting they be equal. And with a non-square frame the old camera fit showed
its flaw: it fitted the bounding SPHERE, which is one number and wrong for
anything not roughly round. The kit scene is wide and flat, so its sphere is
far taller than the scene is, and fitting that into the vertical field left the
models in a band across the middle with empty air above and below — most of a
1.91:1 card. It now fits the BOX, iteratively, because perspective is not
linear in distance: place the camera, project the eight corners, move by how
far the worst one lands past the edge. Two passes is inside a pixel.

That change improves every render, not just the card: on the contact sheet
every model is visibly larger in its cell and nothing crops.

`check-docs` now watches `viewer.html` too. Its description quotes the model
count and the triangle total, which is the same sentence that went stale three
times in the READMEs before that check existed — and a stale number in a card
is worse than one in a README, because nobody reading the card can see the kit
to know it is wrong. The description says "37" rather than "thirty-seven" for
exactly that reason: a word is not a number the check can find.

Also repointing the npm README's two images from `raw.githubusercontent.com`
to the live site. They were pointing into a private repository and would have
404'd on npmjs.com; now they do not depend on the repository being readable at
all.
This commit is contained in:
CRTkafa 2026-08-27 14:34:59 +07:00
parent 151aeb89b2
commit dfee59381e
9 changed files with 128 additions and 9 deletions

BIN
media/cover.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 76 KiB

BIN
media/icon.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 9.7 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 137 KiB

After

Width:  |  Height:  |  Size: 146 KiB

Before After
Before After

Binary file not shown.

Before

Width:  |  Height:  |  Size: 465 KiB

After

Width:  |  Height:  |  Size: 493 KiB

Before After
Before After

View file

@ -4,9 +4,9 @@ A lowpoly medieval model library for [Vibe3D](https://github.com/vibe-stack/vibe
and Three.js. Install a prop and you own its source: readable TypeScript in your and Three.js. Install a prop and you own its source: readable TypeScript in your
own tree, not an opaque package boundary. own tree, not an opaque package boundary.
![The whole kit in one scene](https://raw.githubusercontent.com/CRTkafa/medieval-kit/main/media/kit.png) ![The whole kit in one scene](https://medieval.crt.fyi/kit.png)
![Every model](https://raw.githubusercontent.com/CRTkafa/medieval-kit/main/media/models.png) ![Every model](https://medieval.crt.fyi/models.png)
```sh ```sh
bunx vibe3d add @medieval-kit/wooden-barrel bunx vibe3d add @medieval-kit/wooden-barrel

View file

@ -41,6 +41,19 @@ await writeFile(`${dist}/_headers`, `/viewer-*
Cache-Control: public, max-age=0, must-revalidate Cache-Control: public, max-age=0, must-revalidate
`, 'utf8') `, 'utf8')
/**
* The images the page's own meta tags point at.
*
* `og:image` is an absolute URL to this host, so the file has to BE on this
* host: a card that 404s is a card that shows nothing, and nothing about the
* page itself would look wrong. `kit.png` and `models.png` come too, because
* the published README links to them and a reader of that page should not
* depend on a private repository being readable.
*/
for (const image of ['cover.png', 'icon.png', 'kit.png', 'models.png']) {
await copyFile(`media/${image}`, `${dist}/${image}`)
}
// Listed rather than named. The bundles are hashed, so writing `viewer.js` // Listed rather than named. The bundles are hashed, so writing `viewer.js`
// here would be a lie the moment the bytes change — which is the same mistake // here would be a lie the moment the bytes change — which is the same mistake
// this script's own first version made, in this very line. // this script's own first version made, in this very line.

View file

@ -64,7 +64,21 @@ const WORDS = [
'seventeen', 'eighteen', 'nineteen', 'twenty', 'seventeen', 'eighteen', 'nineteen', 'twenty',
] ]
for (const file of ['README.md', 'REFERENCE.md', 'my-registry/README.md']) { /**
* `viewer.html` is in this list because it is the published page.
*
* Its meta description is what a search result and a shared link show, and it
* quotes the model count and the triangle total — which is the same sentence
* that went stale three times in the READMEs before this check existed. A
* number in a card is worse than a number in a README: nobody reading the card
* can see the kit to know it is wrong.
*
* It carries no table, so the every-model-listed rule does not apply to it,
* any more than it does to the root README.
*/
const CARRIES_A_TABLE = new Set(['REFERENCE.md', 'my-registry/README.md'])
for (const file of ['README.md', 'REFERENCE.md', 'my-registry/README.md', 'viewer.html']) {
const text = readFileSync(file, 'utf8') const text = readFileSync(file, 'utf8')
console.log(file) console.log(file)
@ -74,7 +88,7 @@ for (const file of ['README.md', 'REFERENCE.md', 'my-registry/README.md']) {
// Every model has to appear by id, or the document is describing a smaller // Every model has to appear by id, or the document is describing a smaller
// kit than the one it ships with. The registry README and the reference each // kit than the one it ships with. The registry README and the reference each
// carry a generated table; the root README does not, so it is exempt. // carry a generated table; the root README does not, so it is exempt.
if (file !== 'README.md') { if (CARRIES_A_TABLE.has(file)) {
const missing = ids.filter((id) => !text.includes(`\`${id}\``)) const missing = ids.filter((id) => !text.includes(`\`${id}\``))
expect(`${file}: every model listed`, missing.length === 0, missing.join(', ')) expect(`${file}: every model listed`, missing.length === 0, missing.join(', '))
} }

View file

@ -340,13 +340,51 @@ function frameCamera(root: Object3D, width: number, height: number): { camera: P
const box = new Box3().setFromObject(root) const box = new Box3().setFromObject(root)
const sphere = box.getBoundingSphere(new Sphere()) const sphere = box.getBoundingSphere(new Sphere())
const camera = new PerspectiveCamera(32, width / height, 0.01, 100) const camera = new PerspectiveCamera(32, width / height, 0.01, 100)
const distance = (sphere.radius / Math.sin((camera.fov * Math.PI) / 360)) * 1.12
// Three-quarter view: the one angle that shows two faces at once. Looking // Three-quarter view: the one angle that shows two faces at once. Looking
// straight on hides depth completely. // straight on hides depth completely.
const direction = new Vector3(0.78, 0.5, 1).normalize() const direction = new Vector3(0.78, 0.5, 1).normalize()
/**
* Fit the BOX to the frame, not the sphere to the frame's short side.
*
* A sphere fit is one number and it is wrong for anything that is not
* roughly round. The whole-kit scene is wide and flat: its bounding sphere
* is set by the horizontal extent and is far taller than the scene is, so
* fitting that sphere into the vertical field left the models occupying a
* band across the middle with empty air above and below. On a 1.91:1 social
* card it was most of the picture.
*
* The box fit is iterative because perspective is not linear in distance:
* put the camera somewhere, project the eight corners, see how far past the
* frame edge the worst one lands, and move by that ratio. Two passes is
* inside a pixel at these sizes, and it settles on whichever axis is
* actually tight rather than assuming it is the vertical one.
*/
let distance = (sphere.radius / Math.sin((camera.fov * Math.PI) / 360)) * 1.12
const corner = new Vector3()
for (let pass = 0; pass < 3; pass += 1) {
camera.position.copy(sphere.center).addScaledVector(direction, distance)
camera.lookAt(sphere.center)
camera.updateMatrixWorld(true)
camera.updateProjectionMatrix()
let worst = 0
for (let i = 0; i < 8; i += 1) {
corner.set(
i & 1 ? box.max.x : box.min.x,
i & 2 ? box.max.y : box.min.y,
i & 4 ? box.max.z : box.min.z,
).project(camera)
worst = Math.max(worst, Math.abs(corner.x), Math.abs(corner.y))
}
if (worst <= 0) break
// 0.9 of the frame, so nothing sits on the edge and a shadow has room.
distance *= worst / 0.9
}
camera.position.copy(sphere.center).addScaledVector(direction, distance) camera.position.copy(sphere.center).addScaledVector(direction, distance)
camera.lookAt(sphere.center) camera.lookAt(sphere.center)
camera.updateMatrixWorld(true) camera.updateMatrixWorld(true)
camera.updateProjectionMatrix()
return { camera, floor: box.min.y } return { camera, floor: box.min.y }
} }
@ -356,6 +394,15 @@ function renderOne(
patch?: Record<string, number>, patch?: Record<string, number>,
/** Pre-rotation of the model around the Y axis (radians). For turntables. */ /** Pre-rotation of the model around the Y axis (radians). For turntables. */
spin = 0, spin = 0,
/**
* Frame height, when it is not the width.
*
* Everything here is square because a contact sheet is a grid, but a social
* card is 1.91:1 and cropping a square down to it either loses the model or
* leaves it small. `newFrame` and `frameCamera` both took a width and a
* height already; only this function was insisting they be the same.
*/
tall = size,
): Frame { ): Frame {
const entry = CATALOG[id] const entry = CATALOG[id]
if (!entry) throw new Error(`not in catalog: ${id}`) if (!entry) throw new Error(`not in catalog: ${id}`)
@ -368,8 +415,8 @@ function renderOne(
// stay in a fixed direction, so turntable frames compare one to one. // stay in a fixed direction, so turntable frames compare one to one.
built.root.rotation.y = spin built.root.rotation.y = spin
const triangles = collect(built.root) const triangles = collect(built.root)
const frame = newFrame(size, size) const frame = newFrame(size, tall)
const { camera, floor } = frameCamera(built.root, size, size) const { camera, floor } = frameCamera(built.root, size, tall)
contactShadow(frame, camera, triangles, floor) contactShadow(frame, camera, triangles, floor)
raster(frame, camera, triangles) raster(frame, camera, triangles)
built.dispose() built.dispose()
@ -387,6 +434,7 @@ const flag = (name: string): string | undefined => {
const outDir = flag('out') ?? 'renders' const outDir = flag('out') ?? 'renders'
const one = flag('one') const one = flag('one')
const size = Number(flag('size') ?? (one ? 720 : 300)) const size = Number(flag('size') ?? (one ? 720 : 300))
const tall = Number(flag('height') ?? size)
const only = flag('ids')?.split(',') const only = flag('ids')?.split(',')
@ -453,7 +501,7 @@ const ids = one ? [one]
const frames = new Map<string, Frame>() const frames = new Map<string, Frame>()
for (const id of ids) { for (const id of ids) {
const frame = renderOne(id, size) const frame = renderOne(id, size, undefined, 0, tall)
frames.set(id, frame) frames.set(id, frame)
await writeFile(`${outDir}/${id}.png`, encodePng(frame)) await writeFile(`${outDir}/${id}.png`, encodePng(frame))
console.log(` ${id}`) console.log(` ${id}`)

View file

@ -3,7 +3,51 @@
<head> <head>
<meta charset="UTF-8" /> <meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>@medieval-kit · procedural model viewer</title> <title>@medieval-kit · procedural lowpoly medieval models</title>
<meta
name="description"
content="37 lowpoly medieval models generated from TypeScript you install and own — barrels, tools, a forge, a windmill. 30,390 triangles for the whole kit."
/>
<link rel="canonical" href="https://medieval.crt.fyi/" />
<link rel="icon" type="image/png" href="/icon.png" />
<meta name="theme-color" content="#0b0e12" />
<!--
The card. Every one of these is here because something reads it and shows
the page to somebody who has not opened it yet, and the default without
them is the URL and a blank square.
The image is ABSOLUTE, which is not a style choice: a scraper fetching
this page has no base to resolve "/cover.png" against and will drop it.
Same for the URL. And `og:image` is a real 1200x630 render of the whole
kit rather than a crop of a square one — the renderer will produce any
aspect now, and a card is 1.91:1, so a square image loses either the
windmill off the top or the props off the bottom.
-->
<meta property="og:type" content="website" />
<meta property="og:site_name" content="medieval-kit" />
<meta property="og:url" content="https://medieval.crt.fyi/" />
<meta property="og:title" content="@medieval-kit · procedural lowpoly medieval models" />
<meta
property="og:description"
content="37 lowpoly medieval models generated from TypeScript you install and own — barrels, tools, a forge, a windmill. 30,390 triangles for the whole kit."
/>
<meta property="og:image" content="https://medieval.crt.fyi/cover.png" />
<meta property="og:image:type" content="image/png" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta
property="og:image:alt"
content="37 lowpoly medieval models arranged in one scene: a windmill and an oak-framed market stall behind, a forge, a grindstone and a cart wheel in the middle, barrels, crates and hand tools at the front."
/>
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:title" content="@medieval-kit · procedural lowpoly medieval models" />
<meta
name="twitter:description"
content="37 lowpoly medieval models generated from TypeScript you install and own. Open the viewer and turn any of them over."
/>
<meta name="twitter:image" content="https://medieval.crt.fyi/cover.png" />
<link rel="preconnect" href="https://fonts.googleapis.com" /> <link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin /> <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link <link