@motionstudies/web 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Motion Studies contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,26 @@
+# Motion Studies packages
+
+Shared packages for the Motion Studies transport instrument. The source workspace and compiled distributions expose the same explicit, extensionless module subpaths. The initial release is `0.1.0-alpha.0` under npm’s `next` tag.
+
+- `@motionstudies/core`: transport contracts, indexing, interpolation and visual theme contracts; no browser or Node dependencies.
+- `@motionstudies/three`: `NationalNetworkScene`, `HubPulseScene`, `StationFlowScene`, camera framing and label-mode contracts. React, React Three Fiber and Three.js are peers; rendering internals are not public subpaths.
+- `@motionstudies/web`: picker, theme application, mounting, progressive loaders, observed operations and recording. Import `tokens.css` and `mobile-picker.css` for isolated widgets. `shell.css` is an optional full-page study shell scoped to `.motion-study`; `mountMotionStudy` applies that class. Fonts and edition layouts belong to consumers.
+- `@motionstudies/data`: Node-only GTFS readers, network chunking, merging and station ranking. ZIP reading requires `unzip` on the host. Source selection, provenance overrides and compilation commands belong to each edition.
+
+```tsx
+import { MobilePicker } from '@motionstudies/web/components/MobilePicker'
+import { createDataUrlResolver } from '@motionstudies/web/data-url'
+import { useProgressiveNetworkDay } from '@motionstudies/web/use-progressive-network-day'
+import '@motionstudies/web/tokens.css'
+import '@motionstudies/web/mobile-picker.css'
+
+const resolveData = createDataUrlResolver('/my-edition/data/')
+// Inside a React component:
+// const day = useProgressiveNetworkDay('day.json', enabled, time, resolveData)
+```
+
+Keep the resolver stable across renders. Manifest paths and their chunk paths are relative to the supplied asset root. Changing the resolved manifest URL resets the loader; disabling cancels requests, and re-enabling retries failures. Optional road manifests distinguish a 404 from an error. Observations poll serially; changing their endpoint drops the previous source's state, and disabling/unmounting cancels the request and timer.
+
+Build release candidates with `npm run build:packages`. Distribution manifests and compiled ESM/declarations are written to `.package-dist/`; workspace manifests continue to point at source for fast local iteration. `npm run check:packed` packs and installs those distributions into a separate consumer, builds the lab and validates the public exports. No source aliases or workspace links are used in that consumer.
+
+Source workspace manifests always stay private. `npm run check:release` builds public candidates, tests their packed consumer and records the tested tarball hashes; `npm run release:dry-run` inspects the publication without writing to npm. The manual main-branch `release.yml` workflow publishes those same tarballs with public access and provenance. See [release instructions](https://github.com/emmettl/motionstudies/blob/main/docs/RELEASING.md) for bootstrap-token and trusted-publisher setup. All four shared packages are MIT-licensed; each distribution includes `LICENSE`.

package/components/MobilePicker.d.ts

@@ -0,0 +1,16 @@
+import { type ReactNode } from 'react';
+export interface MobilePickerOption {
+    value: string;
+    label: ReactNode;
+    detail?: ReactNode;
+}
+export interface MobilePickerProps {
+    ariaLabel: string;
+    className?: string;
+    menuPlacement?: 'down' | 'up';
+    onChange: (value: string) => void;
+    options: readonly MobilePickerOption[];
+    triggerLabel?: ReactNode;
+    value: string;
+}
+export declare function MobilePicker({ ariaLabel, className, menuPlacement, onChange, options, triggerLabel, value, }: MobilePickerProps): import("react").JSX.Element;

package/components/MobilePicker.js

@@ -0,0 +1,92 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useId, useRef, useState, } from 'react';
+export function MobilePicker({ ariaLabel, className = '', menuPlacement = 'down', onChange, options, triggerLabel, value, }) {
+    const [open, setOpen] = useState(false);
+    const rootRef = useRef(null);
+    const triggerRef = useRef(null);
+    const optionRefs = useRef([]);
+    const initialFocusIndex = useRef(0);
+    const menuId = useId();
+    const selectedIndex = Math.max(0, options.findIndex((option) => option.value === value));
+    const selectedOption = options[selectedIndex];
+    useEffect(() => {
+        if (!open)
+            return;
+        const handlePointerDown = (event) => {
+            if (!rootRef.current?.contains(event.target))
+                setOpen(false);
+        };
+        const handleFocusIn = (event) => {
+            if (!rootRef.current?.contains(event.target))
+                setOpen(false);
+        };
+        document.addEventListener('pointerdown', handlePointerDown);
+        document.addEventListener('focusin', handleFocusIn);
+        return () => {
+            document.removeEventListener('pointerdown', handlePointerDown);
+            document.removeEventListener('focusin', handleFocusIn);
+        };
+    }, [open]);
+    useEffect(() => {
+        if (open)
+            optionRefs.current[initialFocusIndex.current]?.focus();
+    }, [open]);
+    const openAt = (index) => {
+        initialFocusIndex.current = index;
+        setOpen(true);
+    };
+    const closeAndRestoreFocus = () => {
+        setOpen(false);
+        triggerRef.current?.focus();
+    };
+    const handleTriggerKeyDown = (event) => {
+        if (event.key === 'ArrowDown') {
+            event.preventDefault();
+            openAt(selectedIndex);
+        }
+        else if (event.key === 'ArrowUp') {
+            event.preventDefault();
+            openAt(options.length - 1);
+        }
+        else if (event.key === 'Home') {
+            event.preventDefault();
+            openAt(0);
+        }
+        else if (event.key === 'End') {
+            event.preventDefault();
+            openAt(options.length - 1);
+        }
+    };
+    const handleOptionKeyDown = (event, index) => {
+        let nextIndex;
+        if (event.key === 'ArrowDown')
+            nextIndex = (index + 1) % options.length;
+        else if (event.key === 'ArrowUp') {
+            nextIndex = (index - 1 + options.length) % options.length;
+        }
+        else if (event.key === 'Home')
+            nextIndex = 0;
+        else if (event.key === 'End')
+            nextIndex = options.length - 1;
+        else if (event.key === 'Escape') {
+            event.preventDefault();
+            closeAndRestoreFocus();
+            return;
+        }
+        if (nextIndex !== undefined) {
+            event.preventDefault();
+            optionRefs.current[nextIndex]?.focus();
+        }
+    };
+    return (_jsxs("div", { ref: rootRef, className: `mobile-picker mobile-picker--${menuPlacement}${className ? ` ${className}` : ''}`, children: [_jsxs("button", { ref: triggerRef, className: "mobile-picker__trigger", type: "button", "aria-label": ariaLabel, disabled: options.length === 0, "aria-haspopup": "listbox", "aria-controls": menuId, "aria-expanded": open, onClick: () => {
+                    if (open)
+                        setOpen(false);
+                    else
+                        openAt(selectedIndex);
+                }, onKeyDown: handleTriggerKeyDown, children: [_jsx("span", { children: triggerLabel ?? selectedOption?.label }), _jsx("i", { "aria-hidden": "true" })] }), open && (_jsx("div", { id: menuId, className: "mobile-picker__menu", role: "listbox", "aria-label": ariaLabel, children: options.map((option, index) => (_jsxs("button", { ref: (element) => {
+                        optionRefs.current[index] = element;
+                    }, type: "button", role: "option", "aria-selected": option.value === value, onClick: () => {
+                        onChange(option.value);
+                        closeAndRestoreFocus();
+                    }, onKeyDown: (event) => handleOptionKeyDown(event, index), children: [_jsx("span", { children: option.label }), option.detail && _jsx("small", { children: option.detail })] }, option.value))) }))] }));
+}

package/components/mobile-picker.css

@@ -0,0 +1,147 @@
+/* Import tokens.css once in the consumer. Layout and visibility remain local. */
+.mobile-picker,
+.mobile-picker * {
+  box-sizing: border-box;
+}
+
+:where(.mobile-picker) button {
+  font: inherit;
+  -webkit-tap-highlight-color: transparent;
+  border: 1px solid var(--line);
+  cursor: pointer;
+  transition: border-color 160ms ease, background 160ms ease, transform 160ms ease;
+}
+
+.mobile-picker {
+  position: relative;
+  font-family: 'DM Mono', ui-monospace, monospace;
+}
+
+.mobile-picker__trigger {
+  position: relative;
+  display: flex;
+  min-height: 42px;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  padding: 0 9px;
+  border: 1px solid rgba(193, 204, 255, 0.24);
+  outline: 0;
+  background: rgba(7, 7, 22, 0.82);
+  color: var(--ink);
+  font-size: 0.66rem;
+  letter-spacing: 0.04em;
+  backdrop-filter: blur(14px);
+}
+
+.mobile-picker__trigger i {
+  width: 6px;
+  height: 6px;
+  border-right: 1px solid var(--cyan);
+  border-bottom: 1px solid var(--cyan);
+  transform: translateY(-2px) rotate(45deg);
+  transition: transform 140ms ease;
+}
+
+.mobile-picker__trigger[aria-expanded='true'] {
+  border-color: rgba(141, 250, 255, 0.68);
+  background: rgba(26, 23, 64, 0.94);
+  box-shadow: inset 0 -1px 0 var(--cyan), 0 0 18px rgba(141, 250, 255, 0.11);
+}
+
+.mobile-picker__trigger[aria-expanded='true'] i {
+  transform: translateY(2px) rotate(225deg);
+}
+
+.mobile-picker__menu {
+  position: absolute;
+  top: calc(100% + 5px);
+  right: 0;
+  z-index: 30;
+  display: grid;
+  width: max-content;
+  min-width: 180px;
+  max-width: min(260px, calc(100vw - 24px));
+  padding: 5px;
+  border: 1px solid rgba(141, 250, 255, 0.38);
+  background:
+    linear-gradient(145deg, rgba(20, 18, 50, 0.98), rgba(5, 5, 18, 0.98));
+  box-shadow: 0 15px 42px rgba(0, 0, 0, 0.56), 0 0 28px rgba(69, 89, 156, 0.12);
+  backdrop-filter: blur(22px);
+}
+
+.mobile-picker--up .mobile-picker__menu {
+  top: auto;
+  bottom: calc(100% + 5px);
+}
+
+.mobile-picker__menu::before {
+  position: absolute;
+  inset: 0;
+  border-top: 1px solid rgba(141, 250, 255, 0.22);
+  pointer-events: none;
+  content: '';
+}
+
+.mobile-picker__menu > button {
+  position: relative;
+  display: grid;
+  width: 100%;
+  min-height: 44px;
+  grid-template-columns: 42px minmax(0, 1fr);
+  align-items: center;
+  gap: 9px;
+  padding: 6px 9px;
+  border-color: transparent;
+  background: transparent;
+  color: var(--muted);
+  font-size: 0.67rem;
+  text-align: left;
+}
+
+.mobile-picker__menu > button + button {
+  border-top-color: rgba(193, 204, 255, 0.08);
+}
+
+.mobile-picker__menu > button > span {
+  color: var(--ink);
+  letter-spacing: 0.08em;
+}
+
+.mobile-picker__menu > button > small {
+  overflow: hidden;
+  color: rgba(229, 231, 255, 0.52);
+  font-size: 0.54rem;
+  letter-spacing: 0.02em;
+  line-height: 1.2;
+  text-overflow: ellipsis;
+}
+
+.mobile-picker__menu > button[aria-selected='true'] {
+  border-color: rgba(255, 94, 219, 0.28);
+  background: linear-gradient(90deg, rgba(65, 46, 126, 0.84), rgba(25, 22, 61, 0.58));
+  color: var(--cyan);
+  box-shadow: inset 2px 0 0 var(--pink), 0 0 16px rgba(255, 94, 219, 0.08);
+}
+
+.mobile-picker__menu > button:focus-visible {
+  outline: 1px solid var(--cyan);
+  outline-offset: -2px;
+}
+
+.mobile-picker__trigger:focus-visible {
+  outline: 2px solid var(--cyan);
+  outline-offset: 3px;
+}
+
+.mobile-picker__trigger:disabled {
+  cursor: default;
+  opacity: 0.5;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .mobile-picker button,
+  .mobile-picker__trigger i {
+    transition: none;
+  }
+}

package/data-url.d.ts

@@ -0,0 +1,3 @@
+export type DataUrlResolver = (fileName: string) => string;
+/** The consumer supplies its asset root; packages do not own deployment paths. */
+export declare function createDataUrlResolver(dataRoot: string): DataUrlResolver;

package/data-url.js

@@ -0,0 +1,5 @@
+/** The consumer supplies its asset root; packages do not own deployment paths. */
+export function createDataUrlResolver(dataRoot) {
+    const root = dataRoot.endsWith('/') ? dataRoot : `${dataRoot}/`;
+    return (fileName) => `${root}${fileName}`;
+}

package/mount-motion-study.d.ts

@@ -0,0 +1,3 @@
+import { type ReactNode } from 'react';
+import type { MotionStudyEdition } from '@motionstudies/core/edition';
+export declare function mountMotionStudy(edition: MotionStudyEdition, application: ReactNode): void;

package/mount-motion-study.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { applyVisualTheme } from './visual-theme.js';
+export function mountMotionStudy(edition, application) {
+    const root = document.getElementById('root');
+    if (!root)
+        throw new Error('Motion Studies entry point requires #root');
+    document.documentElement.classList.add('motion-study');
+    document.documentElement.dataset.edition = edition.id;
+    applyVisualTheme(edition.theme);
+    createRoot(root).render(_jsx(StrictMode, { children: application }));
+}

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "@motionstudies/web",
+  "version": "0.1.0-alpha.0",
+  "private": false,
+  "type": "module",
+  "description": "Browser controls and loaders for Motion Studies.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/emmettl/motionstudies.git",
+    "directory": "packages/web"
+  },
+  "homepage": "https://github.com/emmettl/motionstudies#readme",
+  "bugs": {
+    "url": "https://github.com/emmettl/motionstudies/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "next"
+  },
+  "exports": {
+    "./components/MobilePicker": {
+      "types": "./components/MobilePicker.d.ts",
+      "import": "./components/MobilePicker.js",
+      "default": "./components/MobilePicker.js"
+    },
+    "./data-url": {
+      "types": "./data-url.d.ts",
+      "import": "./data-url.js",
+      "default": "./data-url.js"
+    },
+    "./mount-motion-study": {
+      "types": "./mount-motion-study.d.ts",
+      "import": "./mount-motion-study.js",
+      "default": "./mount-motion-study.js"
+    },
+    "./recording": {
+      "types": "./recording.d.ts",
+      "import": "./recording.js",
+      "default": "./recording.js"
+    },
+    "./visual-theme": {
+      "types": "./visual-theme.d.ts",
+      "import": "./visual-theme.js",
+      "default": "./visual-theme.js"
+    },
+    "./use-local-performance": {
+      "types": "./use-local-performance.d.ts",
+      "import": "./use-local-performance.js",
+      "default": "./use-local-performance.js"
+    },
+    "./use-observed-operations": {
+      "types": "./use-observed-operations.d.ts",
+      "import": "./use-observed-operations.js",
+      "default": "./use-observed-operations.js"
+    },
+    "./use-progressive-air-day": {
+      "types": "./use-progressive-air-day.d.ts",
+      "import": "./use-progressive-air-day.js",
+      "default": "./use-progressive-air-day.js"
+    },
+    "./use-progressive-network-day": {
+      "types": "./use-progressive-network-day.d.ts",
+      "import": "./use-progressive-network-day.js",
+      "default": "./use-progressive-network-day.js"
+    },
+    "./use-progressive-road-study": {
+      "types": "./use-progressive-road-study.d.ts",
+      "import": "./use-progressive-road-study.js",
+      "default": "./use-progressive-road-study.js"
+    },
+    "./tokens.css": "./tokens.css",
+    "./shell.css": "./shell.css",
+    "./mobile-picker.css": "./components/mobile-picker.css"
+  },
+  "files": [
+    "**/*.js",
+    "**/*.mjs",
+    "**/*.d.ts",
+    "**/*.d.mts",
+    "**/*.css",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "dependencies": {
+    "@motionstudies/core": "0.1.0-alpha.0"
+  },
+  "peerDependencies": {
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8"
+  }
+}

package/recording.d.ts

@@ -0,0 +1,11 @@
+export interface RecordingOptions {
+    readonly duration: number;
+    readonly fileNamePrefix?: string;
+    readonly onSaving: () => void;
+    readonly onComplete: () => void;
+}
+export interface CanvasRecording {
+    readonly stop: () => void;
+    readonly cancel: () => void;
+}
+export declare function recordCanvas(canvas: HTMLCanvasElement, options: RecordingOptions): CanvasRecording;

package/recording.js

@@ -0,0 +1,62 @@
+function recordingType() {
+    const types = [
+        { mimeType: 'video/mp4;codecs=h264', extension: 'mp4' },
+        { mimeType: 'video/webm;codecs=vp9', extension: 'webm' },
+        { mimeType: 'video/webm;codecs=vp8', extension: 'webm' },
+        { mimeType: 'video/webm', extension: 'webm' },
+    ];
+    return types.find(({ mimeType }) => MediaRecorder.isTypeSupported(mimeType)) ?? {
+        mimeType: '',
+        extension: 'webm',
+    };
+}
+function fileStamp() {
+    return new Date().toISOString().replaceAll(':', '-').replace(/\.\d{3}Z$/, 'Z');
+}
+export function recordCanvas(canvas, options) {
+    const stream = canvas.captureStream(30);
+    const type = recordingType();
+    const recorder = new MediaRecorder(stream, type.mimeType ? { mimeType: type.mimeType, videoBitsPerSecond: 8_000_000 } : undefined);
+    const chunks = [];
+    let stopped = false;
+    let discarded = false;
+    const timer = window.setTimeout(() => stop(), options.duration);
+    recorder.addEventListener('dataavailable', (event) => {
+        if (event.data.size)
+            chunks.push(event.data);
+    });
+    recorder.addEventListener('stop', () => {
+        window.clearTimeout(timer);
+        stream.getTracks().forEach((track) => track.stop());
+        if (discarded) {
+            options.onComplete();
+            return;
+        }
+        const blob = new Blob(chunks, { type: recorder.mimeType || type.mimeType });
+        const url = URL.createObjectURL(blob);
+        const link = document.createElement('a');
+        link.href = url;
+        link.download = `${options.fileNamePrefix ?? 'motion-study'}-${fileStamp()}.${type.extension}`;
+        link.click();
+        window.setTimeout(() => URL.revokeObjectURL(url), 1_000);
+        options.onComplete();
+    });
+    recorder.addEventListener('error', () => {
+        window.clearTimeout(timer);
+        stream.getTracks().forEach((track) => track.stop());
+        options.onComplete();
+    });
+    recorder.start(1_000);
+    function stop() {
+        if (stopped || recorder.state === 'inactive')
+            return;
+        stopped = true;
+        options.onSaving();
+        recorder.stop();
+    }
+    function cancel() {
+        discarded = true;
+        stop();
+    }
+    return { stop, cancel };
+}