# Inside the Machine

An original interactive V8 exhibit: rotate the engine, open both banks, follow any cylinder through four strokes, or watch an 18-second guided inspection.

This is an original pilot inspired by a public example linked in the provided brief. It is not a reconstruction of Dilum Sanjaya’s private prompt, model, code, or assets. This run follows the **directed production brief** only; it is not a comparison experiment.

## Open the delivered app

Node.js 22.13+ is required. The included static build works without installing dependencies or contacting a service:

```sh
cd project
npm run preview
```

Open **http://127.0.0.1:4317**. Keep that terminal running. Stop it with Ctrl+C. To use another port: `PORT=4318 npm run preview` (macOS/Linux). Opening `index.html` directly with `file://` is unsupported because the browser needs module loading through HTTP.

## Edit and rebuild

```sh
cd project
npm ci
npm run dev -- --port 4317
```

The development server prints its actual local URL. Edit the files below, then build:

```sh
npm run build
npm test
npm run preview
```

Stop a server before starting another on the same port. The prebuilt static app is in `project/dist/client/`; server intermediates are omitted from this delivery. The Sites starter uses Vinext, React, and Shadcn/Base UI. Three.js supplies the 3D renderer. No account or API key is needed.

## Use the exhibit

- Drag the engine to orbit. Scroll/pinch or use +/− to zoom. The circular arrow resets the camera.
- **Assembled**, **Section**, and **Exploded** switch the inspection view. Exploded mode separates the housings while preserving the connected mechanism.
- Use the numbered buttons, floating tags, or a visible piston to select a cylinder.
- Pause/play, step ±15°, or scrub 0–720°. The slider also accepts Home, End, and arrow keys. Speed ranges from 0.25× to 2×; 1× is 120 crank degrees per second, a teaching pace rather than engine RPM.
- **Take a guided look** runs the same five-stage, 18-second sequence used for the exported demonstration. You can leave it immediately or use a manual control.
- **About this model** explains the references and simplifications. Reduced-motion preference starts the mechanism paused.

## Editable source

| File | Purpose |
| --- | --- |
| `project/lib/mechanics.mjs` | Shared dimensions, firing schedule, crank/piston solution, valve windows, deterministic tour |
| `project/lib/engine-scene.mjs` | Original procedural geometry, materials, camera, world transforms, geometry export |
| `project/app/page.tsx` | Interaction state, linked cylinder diagram, controls and information panel |
| `project/app/globals.css` | Exhibit design and separate phone composition |
| `project/tests/mechanics.test.mjs` | Numerical linkage, firing and period checks |
| `project/scripts/qa.mjs` | Real Chrome desktop/phone interaction and rendered-coordinate checks |
| `project/scripts/capture.mjs` | Reproducible actual-app screenshot sequence, MP4 and GLB export |

See [REMIX.md](REMIX.md) for a concrete editable change example, [MECHANICS.md](MECHANICS.md) for primary references and derived conventions, and [RUN.md](RUN.md) for measured runtime and verification details.

## Exports

- `exports/inside-the-machine-demo.mp4`: 18 seconds, 30 fps, 1440 × 1000, H.264, silent. Actual application frames, captured on a fixed timeline.
- `exports/desktop-section.png`: actual desktop screenshot.
- `exports/phone-section.png`: actual 390 px phone-layout screenshot; the full page scrolls vertically.
- `exports/desktop-assembled.png`: actual assembled-view screenshot.
- `exports/tour-*.png`: selected actual tour frames for inspection.
- `exports/v8-section-static.glb`: static geometry at crank angle 35°, cylinder 1 selected, section view. It contains no interactive controls, mechanical solver, or animation. Open it in a glTF viewer or Blender; use the web project for motion.

## Recreate screenshots and video

Install project dependencies with `npm ci`; install Google Chrome and FFmpeg if absent. The capture script uses Chrome through Playwright, so it does not require downloading a separate Playwright browser.

In terminal 1:

```sh
cd project
PORT=4318 npm run preview
```

In terminal 2:

```sh
cd project
APP_URL=http://127.0.0.1:4318 QA_OUT=../verification node scripts/qa.mjs
APP_URL=http://127.0.0.1:4318 EXPORTS_DIR=../exports node scripts/capture.mjs
```

The capture script temporarily stores 540 PNG frames in the operating system’s temporary directory, encodes them with FFmpeg, and removes those temporary frames. It captures the app at exact `frame / 30` times; computation speed does not alter the exported motion. Audio is intentionally absent. Preserve this first candidate before regenerating exports for a revision.

## Limits

This is an ideal rigid-link teaching mechanism, with normalized procedural dimensions and schematic cam/follower contact. It does not model pressure, temperature, inertia, torque, wear, balance, lubrication, cooling, or structural behavior. Valve timing is idealized, with no overlap or spark advance; the timing-chain envelope is static. Red is a selection/stroke cue, not measured thermodynamic data. A clean render is not evidence of accurate physics.

Browser QA used Chrome on macOS with 1440 × 1000 desktop and 390 × 844 / 360 × 844 phone viewports. These were real browser layouts, not physical iPhone/Android hardware tests. WebGL 2 is required. Native WebMCP support was unavailable in the QA browser; the feature-detected optional registration is not a verified integration.

The starter dependency audit reports 11 advisories (8 high, 2 moderate, 1 low), mainly involving development/server/image tooling. The supplied static preview serves local files only and does not run React Server Functions, image uploads, or a remote worker. Dependencies were not broadly upgraded for this local pilot. Do not treat this delivery as a production-security approval.
