Playground Examples

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:

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:

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.