Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ It is standalone (not Eurorack), powered from a 5 V power bank through a screw t
- `hardware/` — Hardware designs. `case/` (Blender source in `source/`, STLs by printer bed size, `knobs/`, `legacy_v2/` for the v2.x board, `legacy_lasercut/` for the v1/v2 acrylic drawings, and `remixes/` — community enclosures, one folder each, whose README is its license header), `pcb/` (KiCad 10.0 source, Gerbers per revision, schematic PDF), `bom/` (`bom_v3.9.csv` — **the BOM source of truth**; the guide's table is derived from it. `bom_v3.0.csv` is kept for the previous board).
- `web/` — Next.js site at patternflow.work: landing page (`/`, `/pattern`, `/build`, `/inside` are tabs of one view), the interactive guide (`/guide` is a hub over `/guide/build`, `/guide/play`, `/guide/make` and `/guide/audio`, each with a `/ko` twin; one 3D stage in `components/guide/`, the firmware simulator in `lib/guide/`), Pattern Lab (`/pattern-lab`), community (`/community/**`, SQLite + Drizzle + Better Auth, only on the Pi deployment), browser flasher (no page of its own: the **Flash Patternflow** button on `/pattern` and in the Play guide, installing `public/flash/manifest.json` and the images in `public/flash/bin/`; the bare `/flash` redirects to `/guide/play#flash`), the edition shelf (`/editions`; `/variants` redirects there), the feature catalogue (`/features`, reels per feature), device update handoff (`/update`), journal, roadmap. `lib/pattern/` is the pattern runtime and annotations, `lib/lab/` the Pattern Lab, `lib/community/` the community, `lib/ai/` the prompt Pattern Lab's Copy prompt puts on the clipboard (the site calls no AI service). Architecture doc: `web/ARCHITECTURE.md`. The JS presets in `web/src/lib/presets/` are the source of truth for firmware preset headers.
- `shared/` — `constants.json`, the values the firmware and the site both carry: the panel geometries `PANEL_GEOMETRY` picks from, the knob count, the encoder's 24 detents a turn, the bus maximum and the button timings. Two files are generated from it, `firmware/patternflow/src/core_shared.h` (each key with `PF_SHARED_` in front) and `web/src/lib/shared/constants.ts`, and neither is edited by hand. It exists because the lab counted 20 detents a turn, against the encoder's 24, until 31 July 2026.
- `tools/` — desktop-side helpers: `patternflow-audio-extension` (the browser audio-react extension — also the authoring source the device's `/audio-in` console page is assembled from), `patternflow-audio-android` (phone capture app), `rtpmidi-probe`, `case-models` (builds the /build preview's per-case 3D models, `web/public/cases/<id>/model.glb`, from the case files in the repo; run by hand, not by the site build), and `virtual-panel`. `virtual-panel` is the one that is not a client: a Patternflow with no board, the guide's `DeviceSim` (`web/src/lib/guide/deviceSim.ts`) behind the ports the firmware listens on, with the five contracts in `transports/`. It runs each pattern's JS twin, never a `.pfm` module. The vector suites replay against it, so a change to `DeviceSim` is a change to the panel they test. It is a test fixture, and Wi-Fi and firmware updates are not part of it.
- `tools/` — desktop-side helpers: `patternflow-audio-extension` (the browser audio-react extension — also the authoring source the device's `/audio-in` console page is assembled from), `patternflow-audio-android` (phone capture app), `rtpmidi-probe`, `case-models` (builds the /build preview's per-case 3D models from the case files in the repo, `web/public/cases/<id>/model.glb` and the light `light.glb` beside it that the Build tab's shelf is made of; run by hand, not by the site build), and `virtual-panel`. `virtual-panel` is the one that is not a client: a Patternflow with no board, the guide's `DeviceSim` (`web/src/lib/guide/deviceSim.ts`) behind the ports the firmware listens on, with the five contracts in `transports/`. It runs each pattern's JS twin, never a `.pfm` module. The vector suites replay against it, so a change to `DeviceSim` is a change to the panel they test. It is a test fixture, and Wi-Fi and firmware updates are not part of it.
- `integrations/` — host-software integrations, each with its own README. `integrations/ableton/` is the Max for Live bridge (knobs → Live parameters over OSC). The Home Assistant integration left this repository on 2026-09-03; its author maintains it separately. Integrations are built against the contracts in `docs/` (`rest-api.md`, `osc-spec.md`, `midi-spec.md`), not against the firmware source. `docs/rest-api.md` also has the table for choosing between HTTP, OSC and MQTT, and the rules that make the device's single-connection web server easy to knock over.

## Hard rules (do not violate)
Expand Down
18 changes: 18 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,20 @@ All notable changes to Patternflow will be documented in this file, newest first

### Web

- **The home page's nav is a row of its own on a phone.** Below 901px Guide, Journal, Community, Shop and Instagram were 11px words in the corner over the wordmark, 18px tall to a finger. They are the hero's first row now, 12px words in entries 44px tall, from the column's left edge to its right. Get One is where it was on a 375×667 screen, and pages from 901px up are unchanged.
- **Build, Pattern and Inside start 24px from a phone's edge, not 46px.** The panel's own 22px came on top of the page's 24px, so a 390px phone had a 298px column. It has 342px now, on the hero's and the journal's gutter. On a 375px phone the Inside list's count goes under its heading, where each used to break in two beside the other.
- **The shop is one word in the nav.** It was a box in the nav and a poster with a New tab under the hero's buttons, and it sold next to nothing. The poster is gone from the home page and Shop is drawn as Guide, Journal and Community are. The Inside panel's last row still links it.
- **The phone's section bar marks its open tab with ✕.** A second tap on the open tab goes back to the home page, where the phone's links to Guide, Journal and Community are, and nothing on the bar said so. The bar's words are ink now, not the grey of a caption.
- **The hero's two-line texts share their words on a phone.** Each left a word or two alone on its second line, "them." under 44 characters. They balance their lines below 901px, and the kicker breaks between its two sentences.
- **Small links take a finger on a phone.** Terms & Privacy in the footer was 17px tall and looked like the text around it without a pointer over it. Below 901px it is underlined and 46px tall, and the three links at the foot of the Inside panel are 44px tall, up from 20px.
- **The Build tab's 3D view opens on a shelf of all five cases.** It opened on the official case alone, with arrows to the others. The cases now stand on two boards at one scale, each with its name under it, and its panel lit. Picking one, by the case, by its name or with the keyboard, takes it from the shelf to where the device stands, and All cases brings the shelf back. A case named by the panel's switch, the arrows or a `/build?case=` address is shown by itself as before.
- **Each case has a light model that shows before its full one.** `light.glb` is the device standing assembled, 14 to 55 KB where the full model is 317 to 563 KB and needs the Draco decoder. The light one stands where the device stands until the full one has arrived, which is then drawn in the same place at the same size and turn while the light one fades out over it. The Build tab fetches 154 KB for its 3D view where it fetched 568 KB.
- **The home page no longer fetches the device.** The official case's model and the Draco decoder, 568 KB, loaded with every tab of the home view, the hero's globe included. A full model is now fetched when its case is first shown by itself.
- **The globe turns at one speed on every screen.** A picked place came round by 8% of what was left each frame: 0.46 s to 90% at 60 Hz, 0.23 s on a 120 Hz phone, 0.92 s at 30 Hz. It is 0.46 s at any rate, and so is the camera closing in.
- **Dragging the globe follows the finger, and a flick keeps it turning.** The drag added up each event's `movementX`, which a touch does not always carry, and turned 0.006 radians a pixel whatever the globe's size. It now follows the pointer that began it, one radian for one radius of drag, and lets go with the speed the hand left it, which runs down into the idle drift.
- **The globe's links grow out of their pins.** They draw on over 1.4 s when the map is first seen and when a filter changes them. The dots on them are at least 2.2px across on a phone, where they were 1px.
- **The globe stops drawing when it is off screen.** A phone that had opened Inside and gone back to the home page kept drawing the hidden globe: 14,400 draw calls in 3 s. It is none now.
- **The home view's own moves hold still for reduced motion.** The page rising as it loads, a tab's panel rising, and on a phone the 3D view dropping in and the section bar riding up under it are in place at once. So is a case picked from the shelf.
- **Build map:** the Anbu and Ajman MQTT pins link to engmung/patternflow-exhibition-2026, the exhibition setup and the flowlocal source, now public.
- **Journal text on a phone starts 24px from the screen's edge, not 48px.** The cream gutter and the white panel's padding added up, so 15px text got 17.6 characters a line at 360px. The panel now reaches the screen's edges, and the masthead, the text and both footers start on one 24px line. Pages from 721px up are unchanged.
- **The journal archive's dates and reading times are 13px on a phone, not 10.5px.** They were the smallest text on /journal below 721px, under the 13px the journal's other dates and labels keep. No row's date wraps or meets its post number at 360px, and pages from 721px up are unchanged.
Expand All @@ -27,6 +41,10 @@ All notable changes to Patternflow will be documented in this file, newest first
- **The journal's stylesheet drops 61 lines that matched nothing.** No component or post used `.journal-list-number` or `.journal-figure` with its `-wide` and `-full`, the cover slots never held the `span` two rules styled, and two rules switched off a `::before` nothing switched on. Every journal page renders as before.
- **The site nav links the shop.** Shop sits between Community and Instagram at the top right of the home page, boxed in ink like the hero's outline button, and opens shop.patternflow.work in a new tab. The Inside panel's last row of links carries it too.

### Tools

- **`tools/case-models/light.mjs` makes each case's light model from its full one.** It leaves out what nobody sees while the case is closed, cuts what stays to a triangle budget with meshoptimizer, keeps the LED panel's lit face and the material names, and writes with meshopt compression. `build.sh` runs it after `assemble.mjs`.

## [3.12.0] - 2026-10-27

### Firmware
Expand Down
44 changes: 35 additions & 9 deletions tools/case-models/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,13 +12,17 @@ The 3D models the [/build](https://patternflow.work/build) page's preview shows,

Run `./build.sh` to make all five again (or `./build.sh <case>` for one). The models are committed; nothing here runs when the site builds. Every step is deterministic: the same files in give the same bytes out.

| Model | Size | Loads |
| :--- | ---: | :--- |
| `official/model.glb` | 317 KB | with the page (the guide uses it too) |
| `besoiobiy-printed/model.glb` | 345 KB | when its tab is hovered or picked |
| `simonepda-lasercut/model.glb` | 332 KB | when its tab is hovered or picked |
| `mbchars-horizontal-desktop-printed/model.glb` | 380 KB | when its tab is hovered or picked |
| `jof-patternflood/model.glb` | 563 KB | when its tab is hovered or picked |
Each case has two models. `model.glb` is the full one, every part its own node, which the preview takes apart. `light.glb` is made from it by `light.mjs` (below): the same device standing assembled, small enough that all five load with the tab.

| Case | `model.glb` | `light.glb` |
| :--- | ---: | ---: |
| `official` | 317 KB | 14 KB |
| `besoiobiy-printed` | 345 KB | 30 KB |
| `simonepda-lasercut` | 332 KB | 33 KB |
| `mbchars-horizontal-desktop-printed` | 380 KB | 22 KB |
| `jof-patternflood` | 563 KB | 55 KB |

The five light models load with the Build or Pattern tab, 154 KB between them. A full model loads when its case is first shown by itself, or when a pointer is on it on the way.

The landing page's model before these, `web/public/3dforweb.glb` (a v3.0 device), was 1,155 KB and loaded with the page.

Expand Down Expand Up @@ -123,11 +127,33 @@ Then it checks the result: 410.28 × 176.16 × 42 mm against the README's "appro

Into the model frame it is a half turn about y, 10 mm to the unit, the outline centred and the front face set where the official case's are. The panel lies the long way across here, a quarter turn from the other three, so `ledTurn` turns it a quarter turn clockwise, which puts the top of the pattern at the top as the author mounts the panel (its arrows point up in the rear photo). The board is centred on the encoder holes and bears on the inside of the control section's 3 mm front, as in the official case; the panel's face is flush with the front, on tabs 17.8 mm behind it. Each part is one node: `outer_frame`, `inner_frame`, `rear_display_cover`, `rear_control_cover` and the four `joint_bar_*` in `pla_white`; `control_section`, `usb_retainer`, `stand_left` and `stand_right` in `pla_orange`, the orange of the author's 3MF. Normals as on Besoiobiy's case (`crease_shaded`, imported from `besoiobiy.py`).

## The light models: `light.mjs`

`light.glb` is a case as two nodes: `l`, the lit face of the LED panel with its UVs, and `body`, everything else, one primitive per material. The Build tab opens on a shelf of all five. A picked case's light model then stands where the device stands until its full model has arrived, so the page draws a case before it has fetched 317 KB of it or the Draco decoder.

`node light.mjs` makes all five from their full models (`node light.mjs <case>` for one), and `build.sh` runs it after `assemble.mjs`.

- It leaves out what nobody sees while the case is closed, by node name (`CASES` in the script): the board and the DevKit, mbchars' joint bars, Patternflood's braces and wiring, SimonePDA's loose feet. SimonePDA's case is clear, so its board and DevKit stay, cut down to 260 triangles each.
- It cuts each part that stays to a budget with meshoptimizer: 900 triangles for a part of the shell, 96 for a knob.
- It drops the normals and welds vertices by position. The page works the normals out again from the faces (`toCreasedNormals` in `web/src/components/3d/lightCase.ts`), with an edge wherever two faces meet at more than 36°.
- It keeps the LED panel's lit face as it is, the triangles whose UVs are the LED grid, and gives them the one normal the pattern's shader takes for an LED (`ledPanel` in `patterns/common.ts`).
- It writes the full model's box into the scene's `extras`, so a light model is centred exactly where its full model is, dropped parts or not.
- It writes with `EXT_meshopt_compression`, whose decoder is built into three's loader. Nothing else is fetched before a light model draws.

| Case | Triangles, full | Triangles, light |
| :--- | ---: | ---: |
| `official` | 104,377 | 2,900 |
| `besoiobiy-printed` | 107,154 | 7,946 |
| `simonepda-lasercut` | 103,320 | 3,640 |
| `mbchars-horizontal-desktop-printed` | 125,806 | 5,222 |
| `jof-patternflood` | 110,956 | 10,551 |

## How the preview uses a model

`web/src/components/3d/HeroScene.tsx` with `heroCase.ts` draws whichever model the Build panel's case switch is on.

- **Loading.** Only the official model is preloaded with the page. A remix's model loads when it is picked, or when its tab is hovered (`preloadCaseModel.ts`). The current case stays on screen until the new model has arrived. A model that fails to load is caught, and the official case stays up.
- **Loading.** No full model loads with the page. A case's full model loads when the case is first shown by itself, or when a pointer is on it on the shelf, on its tab or on the arrow that leads to it (`preloadCaseModel.ts`). Until it has arrived the case's light model stands in its place. The full one then takes over in the same place, at the same size and turn, and the light one fades out over it (`CaseShelf.tsx`). A model that fails to load is caught, and the official case stays up.
- **The shelf.** The Build tab's view opens on all five light models standing on two boards, at one scale (`shelfLayout.ts`). A case picked there, by its model or by the name under it, goes from its place on the shelf to where the device stands, and All cases takes it back.
- **Its own copy.** The preview works on a deep clone of drei's cached scene, with its own copy of each material, so it never changes the cached scene, which the guide may be given too. It finds the parts by the node names above; every other top-level node is treated as a piece of the case.
- **Placement.** The model is measured once when it arrives and centred on the preview's orbit target. Every case is drawn at the same scale: the LED panel is the same part in each (and the knobs, except Besoiobiy's own caps), so it is the same size on screen, and what differs is the case round it (up to 4% across the front's diagonal among the three that stand upright; Besoiobiy's case is 8% wider than the official one). mbchars' case lies the long way and is two thirds wider than the official one: on a view too narrow for it, a desktop's tall one, it is drawn smaller, by as little as keeps it within 72% of the view's width, clear of the arrows (`fitAcross` in `buildPose.ts`). On a phone all four fit at the one scale, and on a desktop the other three do. A script does not need to match the official case's origin, only the frame's axes and units.
- **The Build steps** use what `web/src/components/3d/cases/<case>.ts` gives: step 1 shows the case pieces and knobs at 40% of their explode vectors; step 2 shows the board and DevKit, framed on their box; step 3 moves every top-level node by its explode vector times the panel's slider.
Expand All @@ -137,7 +163,7 @@ Into the model frame it is a half turn about y, 10 mm to the unit, the outline c

## Adding a case

A remix with 3D files (or a drawing exact enough to stand up) gets a model the same way: a script in this folder that writes a shell and a `placement.json` in the frame above, a line in `build.sh`, an entry in `web/src/components/3d/cases/`, and the case's card in `web/src/components/sections/build-cases-data.ts`.
A remix with 3D files (or a drawing exact enough to stand up) gets a model the same way: a script in this folder that writes a shell and a `placement.json` in the frame above, a line in `build.sh`, a line in `light.mjs`'s `CASES` saying which of its nodes the light model leaves out, an entry in `web/src/components/3d/cases/`, and the case's card in `web/src/components/sections/build-cases-data.ts`.

## License

Expand Down
5 changes: 4 additions & 1 deletion tools/case-models/build.sh
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
#!/usr/bin/env bash
# Makes every case model again: web/public/cases/<case>/model.glb.
# Makes every case model again: web/public/cases/<case>/model.glb and, from
# it, the light model beside it, light.glb.
#
# tools/case-models/build.sh # all five
# tools/case-models/build.sh official # one
Expand Down Expand Up @@ -45,4 +46,6 @@ for id in "${cases[@]}"; do
exit 1
;;
esac
# The light model is made from the full one, so it follows it.
node light.mjs "$id"
done
Loading
Loading