Add renderStreet endpoint: managed-street JSON → labeled beauty-shot image

[kfarr]

Summary

Public HTTP endpoint (renderStreet Cloud Function + /render-street hosting rewrite) that turns a managed-street JSON blob into a labeled, angled pseudo-orthographic "beauty shot" PNG, aimed at LLM/skill/MCP callers as a zero-friction on-ramp: every response carries an #managed-street-json: editor deep link. Full API contract and deploy notes in docs/street-render-endpoint.md.

Commit 1 adds the endpoint: render.html + a lean editor-free webpack bundle (street-render.js) with a street-render-harness scene component (payload input, model-load quiescence readiness, bbox corner-fit camera framing, capture API), and the puppeteer-core + @sparticuz/chromium Cloud Function.

Commit 2 is a visual pass tuned side-by-side against NACTO street illustrations:

• default azimuth 45° → 20°; screen-space refit after the analytic corner-fit so the street is centered and fills the frame at any aspect (was off-center with excess sky at 1:1)
• default street length 27m when the payload omits it (fit camera ⇒ shorter street = tighter frame)
• street-label restyle (shared with the editor): white cells + segment-colored accent band on the street-surface edge, bold width over lighter name, flat unlit material with shadows off; bar tucked flush against the street face instead of floating 4m out
• street-environment (shared): shadow camera box was a lopsided ~70×50m around the origin leaving everything beyond it unshadowed; now symmetric 90×90m at the same 2048 map (no added GPU memory, ~4.4cm texels). Harness aligns streets length: middle so a 60m street fits the origin-centered box (default-alignment follow-up: managed-street: default length alignment should be middle #1863)

App-wide impact

street-label and street-environment are shared components: the editor gets the restyled cross-section bar and the larger shadow coverage. Both are visual-only; geometry, alignment handling, units, and save/load paths untouched. Shadow box is strictly larger than before on all four sides at unchanged resolution.

Test plan

• npm test (774 passing, incl. managed-street JSON round-trip contract)
• npm run lint
• Headless renders verified via playwright against render.html at 1:1 and 16:10, azimuths 15/20/25/45, lengths 27/40/50/60: framing centered, label flush + legible, full shadow coverage to the far end of a 60m street
• Editor smoke test: eyeball the restyled label bar on a normal scene
• Staging deploy (hosting before function; RENDER_PAGE_URL/EDITOR_BASE_URL overrides in .env.dev-3dstreet) + curl smoke test

🤖 Generated with Claude Code

[kfarr]

Added in 8e2e94f: stable image URLs. Every successful render is cached at renders/v1/<hash>.<ext> in the default bucket (hash = truncated sha256 of canonicalized street + options, input stored as a .json sidecar) and the response now returns a durable proxy URL (imageUrl in format=json, X-3DStreet-Image-Url on byte responses): /render/img/v1/<hash>.png, served by a new lightweight serveRenderImage function behind a hosting rewrite with immutable cache headers. Cache writes are best-effort; a storage failure degrades to imageUrl: null, not a failed render.

Not covered by local testing (no storage emulator in this repo's emulator config), so the staging smoke test should verify: curl -s 'https://.../render-street?format=json' -d @street.json | jq .imageUrl, then fetch that URL and confirm image bytes + Cache-Control: immutable. Share page and cache eviction/re-render-on-miss are tracked in #1864.

[kfarr]

Manual QA checklist

• Basic render: POST the docs' curl example → PNG looks right (lanes, label bar, vehicles, shadows, title + branding)
• Latency: time 1 cold render and 2-3 warm renders of unique streets; note the numbers here (cold vs warm is the open question)
• Cache: repeat an identical request → near-instant response; open X-3DStreet-Image-Url in a browser → same image at the stable URL
• JSON mode: ?format=json returns image, imageUrl, openInEditorUrl, meta; openInEditorUrl loads the street in the editor and matches the image (include one street with no length field: known gap, image renders 27m but editor opens 60m)
• Headers: normal street → X-3DStreet-Editor-Url present; huge street (max segments, long names/colors) → response still succeeds, header omitted
• GET mode: ?data=<base64url> renders; adding &width=1600&type=jpg overrides options inside the payload (jpg at 1600px)
• Options spot check: environment=sunset, units=imperial, labels=false, boundaries=false each do what they say
• Errors: empty segments → 400 with a clear message; unknown model id in modelsArray → still renders, meta.timedOut: true
• Editor regression: open a normal scene in the editor → label bar and shadows look right (street-label and street-environment were touched by this PR)
• Load sanity: fire ~4 concurrent renders → no 500s or instance OOM (429s on overflow are expected)

[kfarr]

Decision: render natively in Blender; the browser-free path is managed-street JSON → GLB → Blender → PNG

TL;DR: keeping a browser in the render path costs 23–59s/render, so we're
switching to a native renderer (Blender + Cycles, CPU). The new "bare-metal"
Cloud Function takes managed-street JSON, assembles the geometry in headless
THREE (no DOM, no A-Frame), and exports a GLB. Blender loads that GLB and
renders the beauty shot. The endpoint returns both the image and the GLB
({ imageUrl, glbUrl }). The current browser-based endpoint stays working as-is
until the native path is proven. Full next-steps prompt at the bottom.

We are deliberately keeping this managed-street-only for now. A more
generalized "serialized JSON scene manifest (IR)" is explicitly NOT part of this
work — later we can either morph this function or add a second one for that.
Don't build the IR; use GLB as the interchange.

Why the browser is out

The current renderStreet (public/functions/render-street.js) drives headless
Chrome -> A-Frame -> SwiftShader (software WebGL, no GPU) to turn managed-street
JSON into a PNG. Instrumented warm+new renders on dev:

scene	segments	wall time
residential (light)	7	~23s
complete street w/ bus + median	7	~48s
avenue w/ buildings	9	~59s

The killer is rasterization on SwiftShader: the harness does ~3 settle passes at
2–8s each plus a final capture, ~30–50s of the total. Warm instances only remove
cold start; a browser GPU is ~$650–800/mo always-on; screenshot services shoot
half-loaded scenes. None fix the per-render floor.

Why native, and why Blender

The dependency isn't "a browser," it's A-Frame + WebGL. THREE.js runs
headless in Node, and Blender imports glTF natively. So we split the two jobs the
browser conflated — assembling the street (cheap) and rasterizing it (the
expensive part) — and hand geometry to Blender as a standard GLB instead of
re-rasterizing in software WebGL.

• Blender + Cycles (CPU) is the only first-class CPU path (Godot has no CPU
  renderer; Eevee is GPU-only). Path-traced, ~3–15s, cheap, nicer beauty shot,
  and it loads GLB out of the box.
• Godot is the pick only if we later accept a GPU. Settle empirically with a
  bake-off on a golden GLB before committing.

The architecture (managed-street only; no IR)

managed-street JSON
  -> [DOM-free Node assembler: pure THREE, no A-Frame]   ==> GLB (geometry + placed models [+ camera + sun])
  -> [Blender Cycles: load GLB, add sky/ground rig, render]   ==> PNG
  -> [Pillow: composite 2D cross-section label + "made with 3DStreet" branding]
returns { imageUrl, glbUrl }

What lives where:

• GLB (the interchange): every segment surface (the below-box slabs) with
  its material/color, plus every generated model placed at its final transform.
  Optionally also the framed camera and the sun (glTF supports both). GLB is the
  ONLY structured output — no custom manifest.
• Blender adds what isn't geometry: the environment sky/lighting preset,
  the ground plane, and the camera+sun if we don't bake them into the GLB.
• Pillow overlays the 2D label bar + branding after render (same as the
  current capture() — do NOT bake text into 3D).

---

Next-steps prompt (paste into a fresh session)

Build the browser-free street renderer for 3DStreet. Repo: /Users/kieranfarr/dev/
3dstreet, branch claude/street-json-visual-endpoint-59qeln (PR #1860). Read the
"Decision" comment above this prompt for the rationale; read
docs/street-render-endpoint.md for the current endpoint contract.

GOAL: a DOM-free Node function that takes managed-street JSON and returns a GLB,
then a Blender step that renders that GLB to a PNG. Managed-street ONLY. Do NOT
build a generalized JSON scene-manifest / IR — GLB is the interchange.

WORKING AGREEMENT (read first):

• Start writing code within your first few actions. Hard cap ~6 file reads before
  you create the first new file. Don't survey the whole component family — the
  facts you need are below. Build, run, iterate; don't narrate exploration.

THE PIPELINE:
managed-street JSON -> [pure-THREE assembler, no A-Frame/DOM] -> GLB
-> [Blender Cycles] -> PNG (+ return the GLB)

TASK 1 — the assembler (this is the actual raw function; do this first):
Write a Node module street-to-glb that takes managed-street JSON and returns a
GLB Buffer, using THREE directly (no A-Frame, no jsdom). It must:

1. For each segment, build the surface slab: a THREE.BoxGeometry matching the
   below-box geometry (width = segment width, depth = street length,
   height ~0.2, top face at y=0), textured/colored per segment surface+color.
   Position segments across X exactly like src/aframe-components/street-align.js
   (center => start at -totalWidth/2, then walk cumulative widths; y = elevation
   height). Length alignment: center on origin (matches the render harness's
   length: middle).
2. Place generated models. Port the placement arithmetic from
   src/aframe-components/street-generated-clones.js (fixed/random/single/fit),
   -stencil, -striping, -pedestrians, -rail. Load each referenced catalog model
   GLB with THREE GLTFLoader in Node and put it at the computed transform.
   • Model URLs/dims are in src/catalog.json (STREET.catalog); building tiling
     widths are the hardcoded buildingWidths table in
     street-generated-clones.js generateFit() (fallback ||10).
   • random/fit modes use a SEEDED mulberry32 RNG (src/lib/rng.js). Replicate it
     byte-for-byte so JSON->GLB is deterministic (needed for the endpoint's
     content-hash cache). Pin an explicit seed on random/fit entries in tests.
3. Export the assembled THREE.Scene to GLB with GLTFExporter (Node needs a few
   globals shimmed). Optionally include the framed camera and a sun light so the
   GLB is self-renderable; otherwise pass those to Blender separately.
   Reference/oracle for correct GLB output (do NOT reuse its DOM path — it's the
   browser exporter): src/editor/lib/exportUtils.js, src/batch-models.js.
   SCOPE: the managed-street family only — managed-street, street-segment,
   street-align, street-generated-{clones,stencil,striping,pedestrians,rail},
   street-label, street-environment. OUT: legacy street/streetmix-loader,
   intersection, geo, arbitrary user entities.

TASK 2 — Blender render:
A Blender (Cycles, CPU) script that imports the GLB, adds the environment rig
(day/night/sunset: sky + sun + ambient — port the presets from
src/aframe-components/street-environment.js setEnvOption()), a ground plane, and
frames the camera via the corner-fit math in
src/render/street-render-harness.js frameCamera() (analytic corner-fit + the
screen-space refit loop — both are pure THREE, port them). Render to PNG.
Then composite the 2D cross-section label bar + "made with 3DStreet" branding
with Pillow (label cell widths/text/accent come from the travelled-way segments,
same as street-label.js) — do NOT bake labels into the GLB.

VALIDATE with two golden streets end to end (JSON -> GLB -> PNG):

1. suburban-arterial — payload in .claude/skills/street-cross-section/SKILL.md
   (sidewalks + pedestrians + 3 random drive lanes); add explicit seeds.
2. avenue-with-boundaries — drive lanes + sidewalks + boundary variant
   'brownstone' side left AND right (exercises buildingWidths/fit tiling).
   DONE = both GLBs open in Blender and render to a labeled beauty shot comparable
   to the current browser output, and the assembler is deterministic for a fixed
   seed. Do a Cycles-CPU bake-off on one golden GLB to confirm the ~3–15s target
   before wiring it into the Cloud Function.

WIRE-UP (after the pipeline works):
New/updated Cloud Function behind the same POST contract as renderStreet,
returning { imageUrl, glbUrl } (cache both at content-hash paths, mirroring the
existing /render/img/v1/ cache in public/functions/render-street.js). Keep
the old browser endpoint working until this is proven; don't rip it out.

KEY FILES:

• Endpoint (current, keep working): public/functions/render-street.js
• Camera framing math to port: src/render/street-render-harness.js frameCamera()
• Assembler logic to port: the managed-street family listed in TASK 1
• GLB exporter oracle (browser, reference only): src/editor/lib/exportUtils.js,
  src/batch-models.js
• Catalog (model URLs + dims): src/catalog.json
• Environment presets: src/aframe-components/street-environment.js
• Docs/contract: docs/street-render-endpoint.md,
  .claude/skills/street-cross-section/SKILL.md, public/openapi/render-street.yaml

NOTES:

• Deferred, separate from this work: the generalized scene-manifest/IR function;
  prod deploy; the ChatGPT custom GPT; privacy-policy URL.