@descix/frqtl-web 0.6.1-p3.3 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/CLAUDE.md +11 -13
  2. package/LICENSE.md +63 -79
  3. package/README.md +7 -9
  4. package/dist/artifact/double-slit.html +1 -1
  5. package/dist/dist-manifest.json +37 -42
  6. package/dist/frqtl/compat/providers/wasm-load-browser.js +1 -2
  7. package/dist/frqtl/compat/renderer/providers/godrays-layer.js +12 -301
  8. package/dist/frqtl/compat/renderer/providers/p5-provider.js +0 -6
  9. package/dist/frqtl/compat/renderer/providers/three-provider.js +17 -66
  10. package/dist/frqtl/objects/FrqtlApp.js +1 -17
  11. package/dist/frqtl/objects/RecipeContext.js +41 -38
  12. package/dist/frqtl/objects/objects/QuantumEmitter.js +1 -1
  13. package/dist/frqtl/objects/objects/sustainedSource.js +2 -2
  14. package/dist/frqtl/objects/record/Record.js +9 -4
  15. package/dist/frqtl/objects/setup/setupConeEmitter3D.js +3 -3
  16. package/dist/frqtl/objects/setup/setupSphereEmitter3D.js +6 -8
  17. package/dist/frqtl/parts/FrqtlVision.js +27 -158
  18. package/dist/frqtl/parts/GraphingDetectorWall.js +1 -1
  19. package/dist/frqtl/parts/LiveChart.js +1 -1
  20. package/dist/frqtl/parts/SphereEmitter.js +2 -2
  21. package/dist/frqtl/parts/Tunnel.js +1 -1
  22. package/dist/frqtl/parts/Wall.js +10 -97
  23. package/dist/frqtl/scenes/dse-tunnel-rebuild.js +22 -33
  24. package/dist/frqtl/scenes/mirror-route.js +6 -10
  25. package/dist/frqtl-web.min.js +51 -56
  26. package/dist/notebooks/notebooks.json +1 -1
  27. package/dist/sdk.html +2 -3
  28. package/dist/shim/controls/index.js +2 -2
  29. package/dist/shim/engine/router.js +30 -49
  30. package/dist/shim/field-descriptor/index.js +5 -5
  31. package/dist/shim/host/host-view.js +10 -7
  32. package/dist/shim/host/index.js +1 -2
  33. package/dist/shim/project/index.js +3 -13
  34. package/dist/shim/project/record-format.js +4 -96
  35. package/dist/shim/project/specifiers.js +3 -5
  36. package/dist/shim/registry/exhibits.js +11 -11
  37. package/dist/shim/registry/index.js +0 -6
  38. package/dist/shim/registry/walkthrough.js +90 -38
  39. package/dist/shim/render/capture-envelope.js +0 -21
  40. package/dist/shim/render/sun-look.js +11 -6
  41. package/llms.txt +8 -9
  42. package/package.json +2 -3
  43. package/dist/shim/engine/site-graph.js +0 -184
  44. package/dist/shim/host/device.js +0 -42
  45. package/dist/shim/project/parts-spelling.js +0 -77
  46. package/dist/shim/registry/showcase-link.js +0 -61
  47. package/dist/shim/registry/studio-landing.js +0 -70
@@ -258,9 +258,7 @@ export var WALKTHROUGH = [
258
258
  'tall/thin mirrors sit at the vertices of a regular decagon; each mirror\'s tilt is ' +
259
259
  'solved from its incoming/outgoing chords so the reflected centre-line hits the next ' +
260
260
  'mirror exactly, and by the star\'s symmetry the tenth leg feeds straight back into ' +
261
- 'the first — the polygon closes on itself. The scene OPENS with two mirrors (m4, m6) standing ' +
262
- 'off their vertices, so the ring starts broken and the light spills: drag one home with the ' +
263
- 'Hand and watch the field reshape live. Each mirror is a DIFFERENT colour and, on ' +
261
+ 'the first — the polygon closes on itself. Each mirror is a DIFFERENT colour and, on ' +
264
262
  'collision, TAGS the beam with its own colour (its drawn colour = its identity): so a ' +
265
263
  'particle\'s colour history IS its bounce sequence — red after m1, orange after m2, … ' +
266
264
  'magenta after m10, then red again as it re-enters the loop (a pkg-node colour-transition ' +
@@ -282,26 +280,19 @@ export var WALKTHROUGH = [
282
280
  'plateaus and FPS stays healthy while the circuit runs indefinitely — and the gate ' +
283
281
  'survives Restart (it is captured descriptor DATA, not recipe code).',
284
282
  source: 'scenes/mirror-route.js',
285
- // 3D FIRST = the rung's DEFAULT mode (the first declared entry), and this rung is FIRST
286
- // CONTACT (FIRST_CONTACT_WALKTHROUGH_ID below). It opens face-on to the ring (the
287
- // 'table-top' preset's axes: azimuth 0, elevation 0, roll 0) but closer than that preset's
288
- // 780, at distance 440, so the top and bottom slabs sit near the canvas's top and bottom
289
- // edges. The look is the one a reference STUDIO session exported for this scene: the
290
- // particles hidden (renderBaseCanvas false), so the picture is the light field alone — strong
291
- // 'field' god rays computed from the light particles only (godraySource 'leaf'), so the
292
- // mirrors shadow the beam and cast no rays — plus a soft glow. Every other render option
293
- // that session exported sat at the renderer's own default, so it is not restated here.
283
+ // 3D FIRST = the rung's DEFAULT mode (the first declared entry). It opens on the
284
+ // 'table-top' camera preset (three-camera-contract.js cameraPresets) with god-rays on at
285
+ // the sun's settings (SunLook.SUN_GODRAYS, owned by lib/shim/render/sun-look.js), computed
286
+ // from the light particles only (godraySource 'leaf'), so the mirrors shadow the beam and
287
+ // cast no rays.
294
288
  // The 2D mode stays one click away on the MODE strip.
295
289
  modes: [
296
290
  {
297
291
  id: '3d', label: '3D',
298
292
  renderState: {
299
293
  renderer: 'three',
300
- camera: { orbit: { azimuth: 0, elevation: 0, distance: 440, roll: 0 }, preset: null },
301
- render: renderRowsFromBag({
302
- renderBaseCanvas: false, godrays: 3, godrayDensity: 1.085,
303
- godraySource: 'leaf', godrayMode: 'field', glowIntensity: 0.27
304
- })
294
+ camera: { orbit: null, preset: 'table-top' },
295
+ render: renderRowsFromBag(Object.assign({}, SunLook.SUN_GODRAYS, { godraySource: 'leaf' }))
305
296
  }
306
297
  },
307
298
  { id: '2d', label: '2D' }
@@ -384,26 +375,89 @@ export var WALKTHROUGH = [
384
375
  renderState: {
385
376
  render: [{ key: 'colorScheme', value: 'roygbiv' }]
386
377
  },
387
- // 3D FIRST = the rung's DEFAULT mode (the first declared entry): the experiment
388
- // standing up in space with a camera you can move. The 2D mode stays one click away
389
- // on the MODE strip.
378
+ // 3D FIRST = the rung's DEFAULT mode (the first declared entry), because this
379
+ // rung is FIRST CONTACT: STUDIO opens on it, and the thing a newcomer should
380
+ // meet is the experiment standing up in space with a camera they can move.
381
+ // The 2D mode stays one click away on the MODE strip.
390
382
  modes: [
391
383
  {
392
384
  id: '3d', label: '3D',
393
- // THE DSE'S OPENING FRAMING, a choice about what to show first, fitted to a reference STUDIO
394
- // picture: close in, rolled so the barrier runs from upper left down to lower right
395
- // across the canvas with its two slits near the centre, the detector plate above and
396
- // behind it showing its bands and running off the top edge, and the emitter's
397
- // god-ray fan spreading from the lower left. The orbit revolves about
398
- // `target`, the midpoint of the working length (emitter x=20 to the detector's
399
- // far face) at the beam height H/2, so it moves whenever the detector does.
385
+ // FIRST-CONTACT FRAMING: the camera stands BEHIND the emitter, facing the
386
+ // slit wall slightly rotated, so the interference builds up partially
387
+ // visible and invites the viewer to move the camera.
388
+ //
389
+ // DERIVED FROM THE SCENE, not tuned against a picture. The camera sits at
390
+ // target + d·(cos el·sin az, sin el, cos el·cos az)
391
+ // looking back at `target` (three-provider `_applyOrbit`, world y-DOWN).
392
+ // target (138, 200, 0) — the midpoint of the WORKING LENGTH (emitter
393
+ // x=20 → detector far face x=256) at the beam height
394
+ // (H/2): (20 + 256)/2 = 138. It is DERIVED from the
395
+ // geometry, so it moves whenever the detector does. The
396
+ // default centre is the CANVAS centre x=300, which sits
397
+ // PAST the detector: orbiting about it swings the
398
+ // experiment around a point outside itself and pushes
399
+ // the near objects into the lens. The experiment orbits
400
+ // about the experiment.
401
+ // azimuth -60 → sin az = -0.866 ⇒ camera x = 138 - 0.82·d ≈ -257 at
402
+ // d = 480: BEHIND the emitter, looking down +x through the
403
+ // slit wall (x = 96..160) toward the detector (x = 236).
404
+ // cos az = 0.5 swings it 30° off that axis in z — the
405
+ // "slightly rotated" part: dead-on, the slit wall would
406
+ // eclipse the detector completely; at 30° the detector's
407
+ // own hit map shows PAST the barrier edge, partially, which
408
+ // is exactly the invitation to orbit.
409
+ // elevation -18 → sin el < 0 ⇒ a smaller world y = ABOVE the beam plane
410
+ // (y-down): a gentle look down onto it, so the slit plate
411
+ // and the tunnels read as solids rather than edge-on lines.
412
+ // distance 480 → the full 256-px working length and the 400-px canvas
413
+ // height inside the fixed 50° vertical FOV, with the
414
+ // quanta streaming through the slits still legible. It
415
+ // frames the working length, so it is re-derived with the
416
+ // geometry — and by MEASUREMENT (project the scene's
417
+ // bounding box through the camera basis and read the frame
418
+ // fill: 480 gives max|ndc| 0.851), never by scaling the
419
+ // span, which over-corrects because the working length runs
420
+ // mostly ALONG the view direction and foreshortens.
421
+ // roll +90 → the SLIT-SEPARATION AXIS onto the screen HORIZONTAL.
422
+ // Derived from the scene like the rest, and forced by a
423
+ // constraint 2D imposes on 3D: 2D has only x and y, so with
424
+ // the beam on x the ONLY transverse axis available is y —
425
+ // the slits MUST split along y and the fringes MUST spread
426
+ // along y. 3D reuses that one setup (2D≡3D is this rung's
427
+ // headline), so it inherits a floor-to-ceiling wall with the
428
+ // detector eclipsed behind it. No orbit parameter can fix
429
+ // that: `elevation` moves the eye along ±y, which is the
430
+ // slit-separation axis itself, so "getting above it" slides
431
+ // the eye ALONG the pattern instead of over the wall. ROLL is
432
+ // the missing degree of freedom — it turns the VIEWER about
433
+ // the beam axis, leaving the world untouched, and lands world
434
+ // y (fringe spread) on the screen horizontal and world z (the
435
+ // corridor extrusion) on the vertical: a WIDE, low plate with
436
+ // the two slots SIDE BY SIDE and the fringes reading as bands
437
+ // left-to-right — the textbook DSE picture. The plate's
438
+ // on-screen bounding box goes 182×648 (tall) → 648×182 (wide);
439
+ // the framing is otherwise IDENTICAL, since a roll moves
440
+ // neither the eye nor the radius.
441
+ // THE SIGN is the visually approved one. Measured through
442
+ // `_orbitCameraBasis` at this exact pose (detector plate
443
+ // corners, 600×600): at roll +90 the low-y corner projects to
444
+ // screen-x 20.9 px and the high-y corner to 633.0 px (+y →
445
+ // RIGHT); at roll −90 they land at 579.1 px and −33.0 px
446
+ // (+y → LEFT). Both are equally "wide".
400
447
  // preset: null — deliberately NOT a named preset. `setPreset` is a FULL
401
- // framing reset (it forces `target: null` and `roll: 0`), so the
402
- // preset buttons are the way back and cannot express this pose.
448
+ // framing reset: it forces `target: null` (and now `roll: 0`),
449
+ // which is exactly what makes the preset buttons the reliable
450
+ // way back — and exactly why they cannot express this pose,
451
+ // whose whole point is the scene-derived `target` above.
452
+ // NOT a compensator: the former azimuth:38 papered over a renderer defect
453
+ // (a ferried canvas drawn with a y-up UV assumption in the y-down world,
454
+ // on a single-sided plane), fixed at the root — orientation is derived in
455
+ // world space and both broad faces carry the map, so every orbit is now
456
+ // equally correct. This pose is a CHOICE about what to show first.
403
457
  renderState: {
404
458
  renderer: 'three',
405
459
  camera: {
406
- orbit: { azimuth: -26, elevation: -18, distance: 440, roll: -115,
460
+ orbit: { azimuth: -60, elevation: -18, distance: 546, roll: 90,
407
461
  target: { x: 177.5, y: 200, z: 0 } },
408
462
  preset: null
409
463
  }
@@ -683,17 +737,15 @@ export function effectiveRenderState(rung, modeId) {
683
737
  * than silently landing on a blank canvas.
684
738
  *
685
739
  * ── Layer 2: what it shows ───────────────────────────────────────────────────
686
- * The infinite mirror (the ten-mirror {10/3} star) in its DEFAULT (3D) mode, face-on:
687
- * the light field itself, shadowed and reflected live by the mirrors, with two
688
- * mirrors standing off their star positions so the first thing to try is dragging
689
- * one home with the Hand. PRODUCT INTENT — the first thing FRQTL shows is light
690
- * doing what light does, computed live, with objects that are obviously yours to move.
691
- * The showcase roster's first tile (exhibits.js EXHIBITS[0]) is this rung too; its
692
- * test holds the two equal.
740
+ * The double-slit rebuilt on the Tunnel object, in its DEFAULT (3D) mode: the
741
+ * camera stands behind the emitter looking obliquely at the slit wall, and the
742
+ * interference pattern builds on the detector plate while you watch. This is
743
+ * PRODUCT INTENT — the first thing FRQTL shows is its signature experiment, framed
744
+ * so the pattern is already forming and the camera is obviously yours to move.
693
745
  *
694
746
  * @type {string}
695
747
  */
696
- export var FIRST_CONTACT_WALKTHROUGH_ID = 'cl1d-mirror-route';
748
+ export var FIRST_CONTACT_WALKTHROUGH_ID = 'dse-tunnel-rebuild';
697
749
 
698
750
  /**
699
751
  * walkthroughById(id) — id → rung, or null. The ONE resolver every consumer of a
@@ -175,26 +175,6 @@ function bytesToBase64(bytes) {
175
175
  return btoa(bin);
176
176
  }
177
177
 
178
- /**
179
- * base64ToBytes(b64) — the inverse of `bytesToBase64`: an envelope's `encoded.bytes` back to the bytes a
180
- * consumer saves or plays (a page turning a recording into a file). One encoding, one owner of both directions.
181
- *
182
- * @param {string} b64
183
- * @returns {Uint8Array}
184
- */
185
- function base64ToBytes(b64) {
186
- if (typeof b64 !== 'string') {
187
- _fail('base64ToBytes expects the base64 string of encoded.bytes, got ' + typeof b64);
188
- }
189
- if (typeof atob !== 'function') {
190
- _fail('base64ToBytes needs a global atob (every browser, and node >= 16)');
191
- }
192
- var bin = atob(b64);
193
- var out = new Uint8Array(bin.length);
194
- for (var i = 0; i < bin.length; i++) { out[i] = bin.charCodeAt(i); }
195
- return out;
196
- }
197
-
198
178
  /**
199
179
  * Compose a single-capture envelope.
200
180
  *
@@ -294,7 +274,6 @@ export {
294
274
  ENCODED_KEYS,
295
275
  ENCODERS,
296
276
  bytesToBase64,
297
- base64ToBytes,
298
277
  stillEnvelope,
299
278
  videoEnvelope
300
279
  };
@@ -5,24 +5,29 @@
5
5
  *
6
6
  * The values are the FINAL FX bag EXACTLY as played and captured in an export session
7
7
  * (new_sun.png is the primary oracle; sun.png stays the historical dense reference), verbatim from
8
- * the exported renderState, plus `godrayMode: 'radial'`, the mode chosen for the sun once the modes existed. They are in the write door's shape — a BAG, what
8
+ * the exported renderState. They are in the write door's shape — a BAG, what
9
9
  * `runner.setRenderOptions(bag)` takes — and every key is a capability the three renderer declares.
10
10
  *
11
11
  * SunLook.SUN_RENDER — the sun's whole look (rung r8-sun's render rows).
12
+ * SunLook.SUN_GODRAYS — the god-ray pair, PICKED from SUN_RENDER: what another scene lights up
13
+ * "at the sun's settings" with (the mirror's 3D mode, the 3D DSE's switch).
12
14
  *
13
- * `godrayMode` 'radial' is the sun's own (its rays fan from one light point, the source frames' centroid).
15
+ * `godraySource` is NOT here: what the rays are computed from is each borrower's declared choice.
14
16
  * The camera is NOT here: a pose is a rung row's view, not a look.
15
17
  *
16
- * Readers: `lib/shim/registry/walkthrough.js` (a named import); a scene sketch may import it too
17
- * (`@descix/frqtl-web/shim/render/sun-look.js`). Zero physics: render
18
+ * Readers: `lib/shim/registry/walkthrough.js` (a named import) and a scene sketch (`SunLook`, the
19
+ * bridge's publication of this module until the game layer imports it). Zero physics: render
18
20
  * options are read only by the renderer.
19
21
  */
20
22
 
21
23
 
22
24
  var SUN_RENDER = Object.freeze({
23
25
  shape: 'sphere', colorScheme: 'warmcool',
24
- godrays: 1.08, godrayDensity: 1.085, godrayMode: 'radial',
26
+ godrays: 1.08, godrayDensity: 1.085,
25
27
  glowIntensity: 0.93, heat: 0.35, smoke: 0
26
28
  });
27
29
 
28
- export { SUN_RENDER };
30
+ // The pair other scenes light up "at the sun's settings" with — PICKED from SUN_RENDER, never re-typed.
31
+ var SUN_GODRAYS = Object.freeze({ godrays: SUN_RENDER.godrays, godrayDensity: SUN_RENDER.godrayDensity });
32
+
33
+ export { SUN_RENDER, SUN_GODRAYS };
package/llms.txt CHANGED
@@ -2,23 +2,22 @@
2
2
 
3
3
  > A discrete cellular-automata physics engine (compiled Rust → WASM) for the browser: interference,
4
4
  > blackbody spectra and binding emerge from per-pixel rules (1 px/tick, single occupancy, momentum).
5
- > 0.6.1-p3.3 on npm dist-tag `next`. Node twin: @descix/frqtl-node.
5
+ > 0.6.1 on npm dist-tag `latest`. Node twin: @descix/frqtl-node.
6
6
 
7
7
  - Install: `npm install @descix/frqtl-web`
8
- - Live page (claude.ai artifact-safe): https://cdn.jsdelivr.net/npm/@descix/frqtl-web@0.6.1-p3.3/dist/artifact/double-slit.html
9
- - One-file form (global FRQTL): https://cdn.jsdelivr.net/npm/@descix/frqtl-web@0.6.1-p3.3/dist/frqtl-web.min.js — example https://cdn.jsdelivr.net/npm/@descix/frqtl-web@0.6.1-p3.3/dist/artifact/sun.html
8
+ - Live page (claude.ai artifact-safe): https://cdn.jsdelivr.net/npm/@descix/frqtl-web@0.6.1/dist/artifact/double-slit.html
9
+ - One-file form (global FRQTL): https://cdn.jsdelivr.net/npm/@descix/frqtl-web@0.6.1/dist/frqtl-web.min.js — example https://cdn.jsdelivr.net/npm/@descix/frqtl-web@0.6.1/dist/artifact/sun.html
10
10
  - A scene is an ES module: `export default function buildExperiment(exp)`, first statement
11
11
  `exp.createCanvas(w, h, cfg)` (2D, p5) or `exp.createScene(w, h, d, cfg)` (3D, three); parts from
12
- `@descix/frqtl-web/parts`. Example: https://cdn.jsdelivr.net/npm/@descix/frqtl-web@0.6.1-p3.3/dist/frqtl/scenes/double-slit.js
12
+ `@descix/frqtl-web/parts`. Example: https://cdn.jsdelivr.net/npm/@descix/frqtl-web@0.6.1/dist/frqtl/scenes/double-slit.js
13
13
  - Doors (`@descix/frqtl-web/boot`): `bootScene(mount, buildExperiment, opts)`;
14
14
  `bootProject(mount, { files: { 'sketch.js': text }, entry: 'sketch.js' }, opts)` or `{ url, entry }`; a folder whose
15
15
  `frqtl.json` names its entry boots as `{ files }` or `{ url }` with no `entry`.
16
- - `./project`: `FRQTL_WEB_SPECIFIERS`, `libPathOf`, `importMapFor`, `pageImportMapFor`, `FRQTL_WEB_HOST_SPECIFIERS`, `linkProject`, `sketchProject`, `SKETCH_ENTRY`, `projectIdentity`, `MANIFEST_FILE`, `MANIFEST_KEYS`, `normalizeManifest`, `parseManifest`, `serializeManifest`, `manifestFor` (the owner of `frqtl.json`), `RECORD_FILES`, `RECORD_KEYS`, `CHANGE_KEYS`, `OPS`, `BY`, `CLIP_SECONDS`, `CLIP_NAME`, `clipName`, `jsonText`, `rowFaults`, `recordFolderFaults`, `applyRows` (the owner of a Record folder's shape; `rowFaults(row)` is `[]` for a valid change row; `recordFolderFaults(files)` is `[]` for a complete Record; `applyRows(partsBlock, rows)` returns a new block with the change rows applied in order, so `applyRows(parts.before, changes)` is `parts.after`; the entry stands alone: it registers the published parts itself).
17
- - `./registry`: walk-through rungs and `projectOf(id, { mode })` → `{ manifest, files, renderState }` (boot it with `bootProject(mount, { files }, { renderState })`); a showcase tile's link (`showcaseHref(row)` relative to the serving site, `showcaseUrl(row)` absolute on `SHOWCASE_SITE.origin`; `row` is an element of the same imported `EXHIBITS`, and the link carries the row's effective mode on a multi-mode rung), and how STUDIO resolved the link it opened with (`STUDIO_LANDING_ATTR` on `<html>`, a `STUDIO_LANDING_OUTCOMES` id).
16
+ - `./project`: `FRQTL_WEB_SPECIFIERS`, `libPathOf`, `importMapFor`, `pageImportMapFor`, `FRQTL_WEB_HOST_SPECIFIERS`, `linkProject`, `sketchProject`, `SKETCH_ENTRY`, `projectIdentity`, `MANIFEST_FILE`, `MANIFEST_KEYS`, `normalizeManifest`, `parseManifest`, `serializeManifest`, `manifestFor` (the owner of `frqtl.json`), `RECORD_FILES`, `RECORD_KEYS`, `CHANGE_KEYS`, `OPS`, `BY`, `CLIP_SECONDS`, `CLIP_NAME`, `clipName`, `jsonText`, `recordFolderFaults` (the owner of a Record folder's shape; `recordFolderFaults(files)` is `[]` for a complete Record).
17
+ - `./registry`: walk-through rungs and `projectOf(id, { mode })` → `{ manifest, files, renderState }` (boot it with `bootProject(mount, { files }, { renderState })`).
18
18
  - `./kinds`: `registerKind`, `kindNamed`, `kindOf`, `registeredKinds` (a composed fork registers its renamed class).
19
19
  - `./host-view`: `declareHostView`, `HOST_VIEW_OUTCOMES`, `CONTRACT_VIOLATIONS`, `HOST_SDK_SCRIPT` (an app asks its DeSciX shell for a view, once: `declareHostView({ sdk: window.DeSciX, mode, fallback })`; the outcome is on the html element's dataset).
20
- - `./site-graph`: `SITE_GRAPH_DIR`, `SITE_BUILD_ATTR`, `SITE_BUILD_ID_RE`, `siteBuildStampOf`, `STATIC_APP_PAGE`, `HOST_PROVIDED_ATTR`, `SITE_PLACEMENTS`, `SITE_ENTRY_PAGES`, `isSiteEntry`, `siteGraphFaults` (the static site's shape: graph directory, build-stamp attribute, build id pattern and its reader, IDE entry page, the attribute declaring a file host-provided, the graph directory of each placed package, the entry pages; and the rule that a served graph is the placed releases' bytes; for a reader of a served site, both packages)
21
20
  - `await recipeContext.fork(name, NewKind, { by })`: copies the `parts` entry's part file into the folder as `parts/<NewKind>.js` (class renamed, imports rewritten to package specifiers) and re-runs the scene in place.
22
- - API reference: https://cdn.jsdelivr.net/npm/@descix/frqtl-web@0.6.1-p3.3/dist/sdk.html
23
- - Full agent guide: https://cdn.jsdelivr.net/npm/@descix/frqtl-web@0.6.1-p3.3/CLAUDE.md
21
+ - API reference: https://cdn.jsdelivr.net/npm/@descix/frqtl-web@0.6.1/dist/sdk.html
22
+ - Full agent guide: https://cdn.jsdelivr.net/npm/@descix/frqtl-web@0.6.1/CLAUDE.md
24
23
  - Acceptance is visual; no CLI ships. No account, credits or tokens are needed.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@descix/frqtl-web",
3
- "version": "0.6.1-p3.3",
3
+ "version": "0.6.1",
4
4
  "description": "FRQTL for the browser \u2014 the discrete fractal physics engine (compiled Rust \u2192 WASM), its parts as ES modules, the scene doors (bootScene, bootProject) and frqtl-web.min.js.",
5
5
  "type": "module",
6
6
  "engines": {
@@ -17,7 +17,6 @@
17
17
  "./project": "./dist/shim/project/index.js",
18
18
  "./registry": "./dist/shim/registry/index.js",
19
19
  "./host-view": "./dist/shim/host/index.js",
20
- "./site-graph": "./dist/shim/engine/site-graph.js",
21
20
  "./shim/controls/registry.js": "./dist/shim/controls/registry.js",
22
21
  "./shim/render/sun-look.js": "./dist/shim/render/sun-look.js",
23
22
  "./compat/renderer/display-slot.js": "./dist/frqtl/compat/renderer/display-slot.js",
@@ -45,7 +44,7 @@
45
44
  "./dist-manifest.json": "./dist/dist-manifest.json",
46
45
  "./package.json": "./package.json"
47
46
  },
48
- "exportsNotes": "The exports map is documented in README.md, section Exports.",
47
+ "exportsNotes": "Every target is a file the build places at its lib-identity path (dist/frqtl/..., dist/shim/...), the same module a page imports by URL: one module, one URL. `.` is the parts barrel + the scene doors + the shared package core (lib/frqtl/boot-entry.js). `./boot` is the scene doors alone (doors.js); its node condition refuses, naming @descix/frqtl-node. `./parts` and `./parts/*` are the parts directory (one part = one file). `./project` is the specifier table, the link site, the project identity and the frqtl.json owner (lib/shim/project/index.js). `./registry` is the walk-through rungs, the showcase roster and the scene list. `./dist-manifest.json` is the per-file sha256 record a self-hosting consumer checks its copy against. dist/frqtl-web.min.js is a FILE, not an export: the esbuild IIFE of the same entry, global FRQTL. The expected shape of this map is owned by sdk/_build/exports-contract.mjs.",
49
48
  "files": [
50
49
  "dist",
51
50
  "README.md",
@@ -1,184 +0,0 @@
1
- /* Copyright 2023-2026 by Essam Abadir */
2
-
3
- /**
4
- * site-graph.js — the shape of a static FRQTL site: the names a site's documents carry, the directory its
5
- * build-stamped graph sits in, which published package owns which part of that graph, and the ONE rule that says
6
- * whether a served graph is those packages' bytes. The ONE owner and the ONE import door of each:
7
- * lib/shim/engine/router.js and every other consumer import them from here (the router never re-exports them), and a
8
- * node consumer that reads a SERVED site (a publisher's gate) imports them through the package export
9
- * `@descix/frqtl-web/site-graph` (or `@descix/frqtl-node/site-graph`), never typing them.
10
- *
11
- * SITE_GRAPH_DIR 'pub' — the site directory holding the fixed entries and, under
12
- * SITE_GRAPH_DIR/<build>/, the build-stamped module graph
13
- * SITE_BUILD_ATTR the <html> attribute of the IDE document carrying <build>
14
- * SITE_BUILD_ID_RE a <build>: the 8-hex-digit short sha of the commit the bundle was built from
15
- * siteBuildStampOf the ONE reader of that stamp
16
- * STATIC_APP_PAGE the IDE bundle's entry document, beside the publisher's front page
17
- * HOST_PROVIDED_ATTR the attribute declaring a file host-provided (the publisher vendors it beside the page)
18
- * SITE_PLACEMENTS each published package placed in the graph, and the graph directory it is placed at
19
- * SITE_ENTRY_PAGES, isSiteEntry
20
- * the @descix/frqtl-web dist's HTML ENTRIES (reached by navigation or iframe, never loaded as a
21
- * resource): the site keeps them at fixed URLs under SITE_GRAPH_DIR/, outside the stamped graph
22
- * siteGraphFaults the served graph against the placed releases' dist-manifest.json records (empty = faithful)
23
- * SITE_GRAPH_EXPORTS the published names (the parity gate holds both packages' ./site-graph to this table)
24
- *
25
- * Host-neutral ESM with no imports: it loads unchanged in node and in a page.
26
- */
27
-
28
- /** The names `./site-graph` publishes. */
29
- export const SITE_GRAPH_EXPORTS = Object.freeze([
30
- 'SITE_GRAPH_DIR', 'SITE_BUILD_ATTR', 'SITE_BUILD_ID_RE', 'siteBuildStampOf', 'STATIC_APP_PAGE', 'HOST_PROVIDED_ATTR',
31
- 'SITE_PLACEMENTS', 'SITE_ENTRY_PAGES', 'isSiteEntry', 'siteGraphFaults',
32
- ]);
33
-
34
- /** The static site's graph directory name (the entries sit in it, the graph under its build-stamped child). */
35
- export const SITE_GRAPH_DIR = 'pub';
36
-
37
- /** The <html> attribute carrying the static site's build id — the cross-repo contract. */
38
- export const SITE_BUILD_ATTR = 'data-frqtl-site-build';
39
-
40
- /** A build id: the 8-hex-digit short sha of the commit the bundle was built from. */
41
- export const SITE_BUILD_ID_RE = /^[0-9a-f]{8}$/;
42
-
43
- /**
44
- * The build stamp an HTML document carries on <html SITE_BUILD_ATTR>, or null when absent.
45
- * THROWS on more than one stamp. The ONE reader of the stamp.
46
- * @param {string} html
47
- * @returns {string|null}
48
- */
49
- export function siteBuildStampOf(html) {
50
- const stamps = [...html.matchAll(new RegExp('<html\\b[^>]*\\b' + SITE_BUILD_ATTR + '="([^"]*)"', 'gi'))].map((m) => m[1]);
51
- if (stamps.length > 1) {
52
- throw new Error('[site-graph] the document carries ' + stamps.length + ' ' + SITE_BUILD_ATTR + ' stamps: ' + stamps.join(', '));
53
- }
54
- return stamps.length ? stamps[0] : null;
55
- }
56
-
57
- /**
58
- * The static IDE bundle's entry document, beside its front page. The bundle ships THIS name and no
59
- * index.html: a site's index.html is the publisher's front page (lib/shim/host/host-view.js::HOST_FRONT_PAGE).
60
- */
61
- export const STATIC_APP_PAGE = 'app.html';
62
-
63
- /**
64
- * The attribute that declares a file host-provided, on the element that consumes it, in the bytes the browser
65
- * executes (the static build writes it: apps/ide/vite.config.js). Both the bundle gate (the file must be ABSENT from
66
- * the bundle) and the publisher (the file must be PRESENT beside the page) read the set from this attribute.
67
- */
68
- export const HOST_PROVIDED_ATTR = 'data-frqtl-host-provided';
69
-
70
- /**
71
- * Each published package the site places in its graph, and the graph-relative directory it is placed at ('' = the
72
- * graph root). The router derives every same-origin URL into a package from its row; a publisher checks each
73
- * placement against that package's installed `<package>/dist-manifest.json`.
74
- */
75
- export const SITE_PLACEMENTS = Object.freeze([
76
- Object.freeze({ package: '@descix/frqtl-web', dir: '' }),
77
- Object.freeze({ package: '@descix/egpt-math-sdk', dir: 'egpt-math-sdk' }),
78
- ]);
79
-
80
- /**
81
- * The @descix/frqtl-web dist's HTML entry pages written by its entry writer (dist-root-relative). The experiment pages
82
- * (experiments/{id}/index.html) are entries too; isSiteEntry names both.
83
- */
84
- export const SITE_ENTRY_PAGES = Object.freeze(['sdk.html', 'artifact/sun.html', 'artifact/double-slit.html']);
85
- const EXPERIMENT_ENTRY = /^experiments\/[^/]+\/index\.html$/;
86
-
87
- /**
88
- * Is this graph-relative path an entry page (which the site serves at SITE_GRAPH_DIR/<path>, never in the graph)?
89
- * @param {string} rel
90
- * @returns {boolean}
91
- */
92
- export function isSiteEntry(rel) {
93
- return SITE_ENTRY_PAGES.indexOf(rel) !== -1 || EXPERIMENT_ENTRY.test(rel);
94
- }
95
-
96
- /**
97
- * Is a served site graph the placed releases' bytes? PURE: the caller enumerates and hashes.
98
- *
99
- * @param {{graph: Object<string,string>, entries: Set<string>}} served
100
- * graph graph-relative path → sha256 hex, for EVERY file under SITE_GRAPH_DIR/<build>/
101
- * entries the paths present under SITE_GRAPH_DIR/ outside the stamped directory (SITE_GRAPH_DIR-relative)
102
- * @param {Array<{dir: string, name: string, version: string, files: Object<string,string>,
103
- * manifest: {file: string, sha256: string}}>} releases
104
- * one per SITE_PLACEMENTS row: its `dir`, the release's dist-manifest.json `name`, `version` and `files`, and the
105
- * manifest file itself (its dist-relative name and the sha256 of its bytes — the record no manifest lists).
106
- * @returns {string[]} the faults, in a stable order (empty = the graph IS the releases):
107
- * - two placements at one dir, or a manifest key that falls under another placement's dir;
108
- * - a graph file with no owning placement (longest dir prefix), not listed by its owner, or of another sha256;
109
- * - a placement's manifest absent from the graph, or not the release's bytes;
110
- * - a listed file absent from the graph, unless it is an entry (isSiteEntry) present among `entries`;
111
- * - an entry still inside the graph (each entry has ONE URL).
112
- */
113
- export function siteGraphFaults(served, releases) {
114
- const graph = served && served.graph;
115
- const entries = served && served.entries;
116
- if (!graph || typeof graph !== 'object' || !(entries instanceof Set) || !Array.isArray(releases) || releases.length === 0) {
117
- throw new Error('[site-graph] siteGraphFaults({graph: {path: sha256}, entries: Set}, releases[]) — got ' +
118
- JSON.stringify({ graph: typeof graph, entries: Object.prototype.toString.call(entries), releases: Array.isArray(releases) ? releases.length : typeof releases }) + '.');
119
- }
120
- for (const r of releases) {
121
- if (!r || typeof r.dir !== 'string' || !r.files || typeof r.files !== 'object' || !r.manifest ||
122
- typeof r.manifest.file !== 'string' || typeof r.manifest.sha256 !== 'string') {
123
- throw new Error('[site-graph] siteGraphFaults: each release is {dir, name, version, files, manifest: {file, sha256}} — got ' +
124
- JSON.stringify(r && { dir: r.dir, name: r.name, version: r.version, manifest: r.manifest }) + '.');
125
- }
126
- }
127
- const placed = (r, key) => (r.dir ? r.dir + '/' + key : key);
128
- const label = (r) => r.name + '@' + r.version + (r.dir ? ' (at ' + r.dir + '/)' : ' (at the graph root)');
129
- const ownerOf = (rel) => {
130
- let best = null;
131
- for (const r of releases) {
132
- if ((r.dir === '' || rel.startsWith(r.dir + '/')) && (!best || r.dir.length > best.dir.length)) { best = r; }
133
- }
134
- return best;
135
- };
136
- const faults = [];
137
-
138
- // 1. The placements are disjoint.
139
- const dirs = releases.map((r) => r.dir);
140
- for (const d of dirs) {
141
- if (dirs.indexOf(d) !== dirs.lastIndexOf(d)) { faults.push('two placements at one dir: ' + JSON.stringify(d)); break; }
142
- }
143
- for (const r of releases) {
144
- for (const key of Object.keys(r.files).sort()) {
145
- const o = ownerOf(placed(r, key));
146
- if (o !== r) { faults.push(label(r) + ' lists ' + key + ', which falls under ' + label(o) + ' — the placements overlap'); }
147
- }
148
- }
149
-
150
- // 2. Every graph file is its owner's byte.
151
- for (const rel of Object.keys(graph).sort()) {
152
- const o = ownerOf(rel);
153
- if (!o) { faults.push('graph file ' + rel + ' has no owning placement'); continue; }
154
- const key = o.dir ? rel.slice(o.dir.length + 1) : rel;
155
- if (key === o.manifest.file) {
156
- if (graph[rel] !== o.manifest.sha256) {
157
- faults.push('graph file ' + rel + ' is ' + graph[rel] + ', not ' + label(o) + '\'s integrity record (' + o.manifest.sha256 + ')');
158
- }
159
- continue;
160
- }
161
- if (!Object.prototype.hasOwnProperty.call(o.files, key)) {
162
- faults.push('graph file ' + rel + ' is not listed by ' + label(o));
163
- } else if (o.files[key] !== graph[rel]) {
164
- faults.push('graph file ' + rel + ' is ' + graph[rel] + ', ' + label(o) + ' lists ' + o.files[key]);
165
- }
166
- }
167
-
168
- // 3. Every listed file is served: in the graph, or (an entry) at its fixed URL and NOT in the graph.
169
- for (const r of releases) {
170
- const m = placed(r, r.manifest.file);
171
- if (!Object.prototype.hasOwnProperty.call(graph, m)) { faults.push(label(r) + '\'s ' + r.manifest.file + ' is absent from the graph'); }
172
- for (const key of Object.keys(r.files).sort()) {
173
- const rel = placed(r, key);
174
- const inGraph = Object.prototype.hasOwnProperty.call(graph, rel);
175
- if (isSiteEntry(rel)) {
176
- if (inGraph) { faults.push('entry ' + rel + ' (' + label(r) + ') is still inside the graph — an entry has one URL, at ' + SITE_GRAPH_DIR + '/' + rel); }
177
- if (!entries.has(rel)) { faults.push('entry ' + rel + ' (' + label(r) + ') is absent from ' + SITE_GRAPH_DIR + '/'); }
178
- } else if (!inGraph) {
179
- faults.push(label(r) + ' lists ' + key + ' but it is absent from the graph');
180
- }
181
- }
182
- }
183
- return faults;
184
- }
@@ -1,42 +0,0 @@
1
- /* Copyright 2023-2026 by Essam Abadir */
2
-
3
- /**
4
- * device.js — the ONE rule for "this document is open on a phone".
5
- *
6
- * MOBILE_DEVICE_QUERY the media query: a coarse primary pointer (a finger, not a mouse) on a viewport no wider
7
- * than the widest phone held in landscape (932 CSS px, the iPhone Pro Max). A tablet in
8
- * portrait is narrower than that and counts as a phone; a touch laptop has a fine pointer
9
- * and does not.
10
- * isMobileDevice(win) win.matchMedia(MOBILE_DEVICE_QUERY).matches — evaluated in the window that LAYS OUT the
11
- * page (an app framed by the DeSciX shell measures its own frame). A window without
12
- * matchMedia THROWS: every browser has it, so its absence is a caller passing the wrong object.
13
- *
14
- * Its three consumers ask it once each, at load:
15
- * - the host-view call site (apps/ide/src/host-view-entry.js) asks the shell for NoChrome on a phone, CodeSite
16
- * elsewhere;
17
- * - STUDIO (lib/features/ide/AuthorView.jsx) opens with its side panels collapsed on a phone and puts its Hand tool
18
- * between the camera joysticks (the phone toolbar Move | Hand | Look), and words its mirror "try it" for that
19
- * surface (lib/features/ide/studio-try-it.js);
20
- * - FraqtlIde (lib/features/ide/index.jsx) opens the STUDIO tab card with the controls of that surface
21
- * (presets.js presetExplainerFor).
22
- * The static build compiles it into both: the stable host-view entry is bundled as its own self-contained module
23
- * (apps/ide/vite.config.js frqtl-host-view-entry), the IDE's rollup graph carries its own copy of the same source.
24
- *
25
- * Host-neutral ESM with no imports.
26
- */
27
-
28
- /** A phone: a coarse primary pointer on a viewport no wider than a phone in landscape. */
29
- export const MOBILE_DEVICE_QUERY = '(pointer: coarse) and (max-width: 932px)';
30
-
31
- /**
32
- * @param {{matchMedia: function(string): {matches: boolean}}} win the window the page is laid out in
33
- * @returns {boolean}
34
- * @throws {TypeError} a window without matchMedia
35
- */
36
- export function isMobileDevice(win) {
37
- if (!win || typeof win.matchMedia !== 'function') {
38
- throw new TypeError('[device] isMobileDevice(win) needs the window the page is laid out in (a matchMedia ' +
39
- 'function); got ' + (win === null ? 'null' : typeof win) + '. (FAIL-LOUD.)');
40
- }
41
- return win.matchMedia(MOBILE_DEVICE_QUERY).matches === true;
42
- }
@@ -1,77 +0,0 @@
1
- /* Copyright 2023-2026 by Essam Abadir */
2
-
3
- /**
4
- * parts-spelling.js — THE rule for spelling a written value in a `parts` entry's OWN form. A hand's value and a Record
5
- * row's value are the CAPTURE form (ObjectSchema.captureProps); the entry keeps the form its author wrote. Two
6
- * consumers ask it, so the text and the block agree by construction:
7
- * - the writer (RecipeContext toSketch / setDeclared), reading the entry's form off the sketch TEXT;
8
- * - applyRows (record-format.js), reading it off a parts BLOCK ({ name: [kind name, props] }).
9
- *
10
- * spellRect(props, { kind, entryKeys, baseline }) — a 6-tuple of a field whose descriptor derives reads from it
11
- * (ObjectSchema.derivedReads: Wall `z`, `depth`) is written as the 4-tuple plus each derived key whose value
12
- * changed, when the entry spells any of those keys as plain properties; otherwise the 6-tuple stands. A
13
- * 4-tuple equal to the baseline's is not written (no literalizing an untouched expression). THROWS, naming the
14
- * remedy, when `kind` is not registered in this realm (no imported module defines it).
15
- * spellCenter(props, { entryKeys, centerLength }) — a `center` [x, y, 0] is written as two numbers when the entry
16
- * spells two; otherwise the [x, y, z] stands.
17
- * captureCenter(v) — the inverse: a spelled `center` in its capture form. [x, y] → [x, y, 0] (an omitted z is 0,
18
- * the reading placeDeclaredAt gives it); [x, y, z] stands. THROWS on anything else.
19
- *
20
- * `entryKeys()` → the keys the entry spells; `centerLength()` → the element count its `center` spells, or null.
21
- * Both are asked lazily (only when a value needs them). Each function mutates and returns `props`.
22
- */
23
-
24
- import { ObjectSchema } from '../../frqtl/objects/schema/index.js';
25
-
26
- const _JSON = function (v) { return JSON.stringify(v); };
27
-
28
- function _hasSix(props) {
29
- return Object.keys(props).some(function (f) { return Array.isArray(props[f]) && props[f].length === 6; });
30
- }
31
-
32
- /** @param {object} props @param {{ kind: string, entryKeys: function(): string[], baseline: object }} o */
33
- export function spellRect(props, o) {
34
- if (!_hasSix(props)) { return props; }
35
- if (!ObjectSchema.get(o.kind)) {
36
- throw new Error('[parts-spelling] the kind "' + o.kind + '" is not registered in this realm: a 6-number rect is spelled by ' +
37
- 'its descriptor, and a kind registers when the module that defines it is imported (the published parts register ' +
38
- 'with ./project; a project\'s own part, parts/' + o.kind + '.js, when its module is imported) — import the module ' +
39
- 'that defines it. (FAIL-LOUD.)');
40
- }
41
- const derived = ObjectSchema.derivedReads(o.kind);
42
- if (!derived.length) { return props; }
43
- const spelled = o.entryKeys();
44
- const baseline = o.baseline || {};
45
- const R4 = ObjectSchema.RECT_TUPLE[4], R6 = ObjectSchema.RECT_TUPLE[6];
46
- Object.keys(props).forEach(function (f) {
47
- const v = props[f];
48
- const rows = derived.filter(function (d) { return d.field === f && d.tuple === 6 && spelled.indexOf(d.name) !== -1; });
49
- if (!rows.length || !Array.isArray(v) || v.length !== 6) { return; }
50
- const b = Array.isArray(baseline[f]) && baseline[f].length === 6 ? baseline[f] : null;
51
- const four = R4.map(function (k) { return v[R6.indexOf(k)]; });
52
- if (b && _JSON(four) === _JSON(R4.map(function (k) { return b[R6.indexOf(k)]; }))) { delete props[f]; }
53
- else { props[f] = four; }
54
- rows.forEach(function (d) {
55
- const nv = v[R6.indexOf(d.key)];
56
- if (!b || nv !== b[R6.indexOf(d.key)]) { props[d.name] = nv; }
57
- });
58
- });
59
- return props;
60
- }
61
-
62
- /** @param {number[]} v a spelled center @returns {number[]} its capture form [x, y, z] (a new array) */
63
- export function captureCenter(v) {
64
- if (!Array.isArray(v) || (v.length !== 2 && v.length !== 3) || !v.every(function (n) { return typeof n === 'number'; })) {
65
- throw new TypeError('[parts-spelling] captureCenter: a center is [x, y] or [x, y, z] numbers, got ' + JSON.stringify(v) + '. (FAIL-LOUD.)');
66
- }
67
- return v.length === 2 ? [v[0], v[1], 0] : v.slice();
68
- }
69
-
70
- /** @param {object} props @param {{ entryKeys: function(): string[], centerLength: function(): (number|null) }} o */
71
- export function spellCenter(props, o) {
72
- const v = props.center;
73
- if (!Array.isArray(v) || v.length !== 3 || v[2] !== 0) { return props; }
74
- if (o.entryKeys().indexOf('center') === -1) { return props; }
75
- if (o.centerLength() === 2) { props.center = [v[0], v[1]]; }
76
- return props;
77
- }