playground-examples

name

playground-examples

description

This skill should be used when adding, editing, or fixing an example in apps/playground — when a task says "add a playground example", "example fails check:examples", "playgroundExamples.test.ts is failing", "regenerate ambient types", "generate-types", "example thumbnail is missing", "run npm run thumbs", "example renders wrong / blank viewer", "example works in tests but breaks in the browser", or when a new example needs to pass its three gates (types, geometry, thumbnail) before merge.

Playground examples

Add or fix an example in apps/playground and clear its three gates: types, geometry, thumbnail. Every example is a self-contained code string that (1) type-checks against the editor's ambient types, (2) evaluates and meshes against the OCCT kernel in the root test suite, and (3) ships a committed .webp thumbnail. Miss any one and CI or the gallery breaks.

For bulk import from an OpenSCAD reference library, use the /scad-to-playground workflow instead — it encodes the same validate→render→repair loop for many examples at once. This skill is the manual, single-example counterpart.

Example anatomy

An example is an Example { id, label, description, code } (apps/playground/src/lib/examples/types.ts). Examples live in category files and are aggregated by a barrel:

File	Category	Notes
apps/playground/src/lib/examples/basics.ts	Basics	Calibration for house comment style
apps/playground/src/lib/examples/mechanical.ts	Mechanical	Largest set
apps/playground/src/lib/examples/sheetMetal.ts	Sheet Metal	imports brepjs-sheetmetal
apps/playground/src/lib/examples/bim.ts	BIM	imports brepjs-bim, uses top-level await
apps/playground/src/lib/examples/families.ts	Families	imports brepjs-families (+ brepjs-bim for the IFC projection)
apps/playground/src/lib/examples/index.ts	barrel	builds CATEGORIES + flat EXAMPLES

To add an example: append an Example to the appropriate category array. To add a new category: create a file exporting an Example[], then register it in CATEGORIES (index.ts).

Code-string rules (hard constraints)

The code field becomes the Monaco editor buffer verbatim AND is executed by both the browser worker and the root test harness. It must obey (types.ts):

• Self-contained. No shared helpers, no imports of other examples, no TS-only constructs the harness's sucrase strip can't handle (transforms: ['typescript'], tests/helpers/playgroundExampleEval.ts).
• Named imports only, from the recognized specifiers. The eval harness rewrites only the import { … } from '<spec>' form for these specifiers: brepjs, brepjs/quick, brepjs/playground, brepjs-sheetmetal, brepjs-bim, brepjs-families (playgroundExampleEval.ts). Namespace (import * as) and default imports are NOT rewritten and will fail at runtime. Prefer 'brepjs/quick'.
• Ends in export default <shape | shape[]>. Return one shape or an array; an array renders each shape. The harness turns export default into return (playgroundExampleEval.ts).
• color() / present() come from 'brepjs/playground', not published API. color(shape, css) tags a color; present(shape, { dxf, ifc, bimTree, overlay2d }) attaches downloadable artifacts. Both are stripped back to the shape before meshing (playgroundExampleEval.ts, 108-113).
• unwrap() finishing ops — never x.ok ? x.value : base. See Gate 2; the silent-fallback ban is enforced by regex.

Comment style

Match basics.ts: one punchy header line, aligned trailing dimension comments, terse one-line section notes. Example from basics.ts:

const drilled = unwrap(cut(box(30, 20, 10), cylinder(5, 15, { at: [15, 10, -2] })));

Keep comments concise — they are read in a small Monaco pane. Avoid multi-line walls of prose.

The three gates

Gate 1 — types (check:examples)

cd apps/playground && npm run check:examples

apps/playground/scripts/checkExamples.ts type-checks every example's code against the generated ambient .d.ts files (src/types/brepjs-ambient.d.ts, -sheetmetal-, -bim-, -families-), wrapped into declare module blocks by the same buildBrepjsModuleDts the Monaco editor uses, with the editor's compiler options (ES2022, moduleResolution Bundler, strict, skipLibCheck). Passing == "no red squiggles in the editor". It also checks the docs landing hero snippet docs-hero:PLAYGROUND_PROGRAM extracted from apps/docs/.vitepress/theme/components/CodeCadHero.vue — if that template literal is renamed or moved, the script exits 1 with a pointed message.

On failure, decide the cause:

Symptom	Cause	Fix
Error on an API the example uses	Example bug	Fix the code string
Method/type exists in src but not the ambient .d.ts	Stale ambient types	Rebuild the package(s), run npm run generate-types, commit the regenerated src/types/*-ambient.d.ts
"Could not find PLAYGROUND_PROGRAM"	Hero literal moved	Restore the literal or update the PLAYGROUND_PROGRAM regex in checkExamples.ts

Regenerating types: generate-ambient-types.ts reads each package's built node_modules/<pkg>/dist/index.d.ts (build the package first), and deliberately excludes the experimental implicit/ modules (EXCLUDED_MODULE_RE = /(^|\/)implicit\//, generator lines 60-64) because they re-export core primitives aliased as sdfCylinder etc. that would otherwise overwrite the real cylinder/box/cone. Satellite packages re-emit their brepjs-sourced names as a top-of-file import type { … } from 'brepjs' that resolves against the sibling declare module 'brepjs' at consumption time — leave that mechanism intact. See kernel-abstraction and companion-packages skills for package build order.

Where it runs in CI: the playground build script is tsc -b && npm run check:examples && vite build (package.json), reached through the site-build job's npm run build:site (path-gated on the site filter in .github/workflows/ci.yml). The playground's prebuild hook (build:deps) builds brepjs-families, brepjs-bim, brepjs-sheetmetal, and brepjs-viewer first.

Gate 2 — geometry (tests/playgroundExamples.test.ts)

npx vitest run --project occt-wasm tests/playgroundExamples.test.ts

Run from the repo root. This lives in tests/, so it is part of the root suite and needs no dist build — root vitest aliases brepjs, brepjs-sheetmetal, brepjs-bim, and brepjs-families to live src (vitest.config.ts). Pre-commit's changed-file run (vitest run --project occt-wasm --changed) picks it up when an example file changes, because vitest --changed follows the import graph into apps/playground/src/lib/examples/.

Four assertion families (tests/playgroundExamples.test.ts):

1. Unique id and label across all examples (lines 20-25).
2. Evals + meshes: each example produces shapeCount > 0 and totalVertices > 0 (lines 27-33).
3. No silent finishing-op fallback: the regex /(\.ok\s*\?[^:]*:|isOk\s*\([^)]*\)\s*\?[^:]*:)/ must not match — patterns like x.ok ? x.value : base or isOk(x) ? unwrap(x) : base are banned (lines 40-48). A swallowed fillet/chamfer failure makes a no-op pass the mesh check while shipping an unfinished part. Use unwrap() so failures throw and get caught. See result-error-handling.
4. Connected-body check for a hard-coded assembly list CONNECTED_BODY_EXAMPLES (universal-joint, geneva-drive, bench-vise, scotch-yoke, three-jaw-chuck, worm-gear-drive, lines 55-62): each exported body must have getSolids().length === 1. A disjoint compound still meshes but detaches on STEP/GLB export. When adding a multi-body mechanism/assembly example, add its id to this list.

If geometry is wrong (see debugging-geometry for the full triage): common example pitfalls are revolve() of a profile whose edge touches the axis (degenerate), features added where they should be cut (inverted boolean), and the silent-fallback pattern above.

Gate 3 — thumbnail (committed .webp)

Each example needs a committed apps/playground/public/example-thumbs/<id>.webp (58 static thumbnails committed today; a further 46 optional .turntable.webp files also live here), consumed by ExampleGallery.tsx. Generating one requires a running dev server:

cd apps/playground
(npm run dev > tmp/pg.log 2>&1 &) ; sleep 6
PORT_URL=$(grep -oE 'http://localhost:[0-9]+' tmp/pg.log | head -1)
npm run thumbs "$PORT_URL" <example-id>

Vite may pick a non-5173 port if one is busy — always sniff the actual URL from the log, don't hardcode. npm run thumbs (shootExamples.ts --thumbs) frames the model (Iso preset, Fit, grid off) and writes a centred square WebP. Commit public/example-thumbs/<id>.webp.

Optional companion: npm run turntables "$PORT_URL" <id> writes an animated <id>.turntable.webp (needs img2webp or ffmpeg on PATH and the DEV-only window.__brepjsOrbit hook). The gallery lazy-loads it on hover and remembers 404s, so a missing turntable is tolerated — many examples ship only the static webp.

Visual-repair loop: npm run shoot "$PORT_URL" tmp/shots <id> writes a full-page PNG; Read it to confirm the shape looks right, edit the code, re-run Gate 2, re-shoot. A shape can pass eval+mesh yet render off-centre, floating, or degenerate — the screenshot is the only thing that catches that.

Symptom → cause → fix

Symptom	Cause	Fix
Gates green, browser shows blank/broken viewer	Stale companion dist (worker lazy-imports brepjs-bim/brepjs-sheetmetal/brepjs-families from their built dist, not src)	build:deps runs on predev/prebuild and auto-heals; restart a long-running dev server after editing brepjs-bim/brepjs-sheetmetal/brepjs-families/brepjs-viewer. See companion-packages.
Namespace/default import fails at runtime but type-checks	Harness only rewrites import { … } from form	Convert to named imports
Example edit not lint/format-checked locally	Playground app code is outside root lint/typecheck/lint-staged	Its own gates are tsc -b + check:examples + vite build, reached through the path-gated site-build CI job
Thumbnail command fails to connect	Wrong port	Sniff the port from the dev-server log
check:examples fails on the hero snippet	Hero literal moved in CodeCadHero.vue	Keep PLAYGROUND_PROGRAM intact or update checkExamples.ts

Note: the production playground-smoke workflow only checks the deployed engine boots; it does NOT verify examples. Gate 2 is the sole guard that each example runs.

Checklist for a new example

1. Add the Example to the right category file (or register a new category in index.ts).
2. cd apps/playground && npm run check:examples — types green.
3. npx vitest run --project occt-wasm tests/playgroundExamples.test.ts — geometry green (add multi-body assemblies to CONNECTED_BODY_EXAMPLES).
4. Start dev server, npm run thumbs "$URL" <id>, commit public/example-thumbs/<id>.webp.
5. Optional: npm run shoot "$URL" tmp/shots <id> + Read the PNG to confirm framing.

Additional resources

The in-code file headers are the authoritative depth and stay current with the code; read them rather than a restatement:

• apps/playground/src/lib/examples/types.ts — authoring rules
• apps/playground/scripts/checkExamples.ts — Gate 1
• tests/playgroundExamples.test.ts + tests/helpers/playgroundExampleEval.ts — Gate 2 + eval harness mechanics
• apps/playground/scripts/shootExamples.ts — Gate 3, audit and turntable modes
• apps/playground/scripts/generate-ambient-types.ts + apps/playground/src/lib/ambientModule.ts — the editor type surface
• .claude/workflows/scad-to-playground.js — bulk-import automation precedent

Sibling skills: debugging-geometry (wrong/empty geometry), result-error-handling (unwrap vs fallback), companion-packages (dist build order, stale-dist trap), quality-gates and ci-triage (gate/CI mechanics).