Skip to content

Latest commit

 

History

History
108 lines (84 loc) · 4.65 KB

development.md

File metadata and controls

108 lines (84 loc) · 4.65 KB

Development

Repository layout, the demo playground and repository commands.

Demo playground

The interactive one- and two-dimensional demo playground lives in playground/ and shares this repository's dependencies. It runs and builds as a standalone static site without other checkouts. Optional lab panes require ?lab=1 and come from browser-surface-lab, placed beside this checkout:

onirigiri/
browser-surface-lab/

The playground resolves @riteofstring/onirigiri to src/, so pnpm dev:1d and pnpm dev:2d show library changes without a package build. pnpm test includes the playground's Vitest project, and pnpm build:playground builds both apps into their respective dist/ directories with relative asset URLs. Deploy either output directory to any static host, including a subdirectory. The optional lab fixture is not bundled. See the playground README for preview, lab-hosting and deployment instructions.

The functional browser projects under tests/browser/ and the CPU checks that open the 2D playground use its development servers and fixture pages. The native cadence project in the same canonical playwright.config.ts builds and previews its fixture with production React. pnpm test:browser includes both functional projects and production native cadence; node scripts/test-native-content.mjs cadence selects only the latter. The fixture keeps StrictMode enabled in source for development lifecycle coverage.

Retained-capture preview

tests/browser/retained-capture.html is the library-owned retained-picture harness used by the Chrome capture contract. To open it in Chrome with HTML-in-Canvas enabled:

node scripts/preview-retained-capture.mjs

The launcher opens port 5197. Other tabs can open the same URL and use the same engine, provided their browser has the required feature enabled.

Performance harness

bench/ contains the production performance fixture used by pnpm test:performance; pnpm build:performance builds it.

Package boundary

Onirigiri has no backend, Electron, chat, settings, speech, account, or application-shell dependency. React and React DOM are peer dependencies.

Commands

pnpm install --frozen-lockfile --ignore-scripts
code-polishy check --all
code-polishy test --changed
pnpm test
pnpm test:browser
pnpm typecheck
pnpm build
code-polishy supply-chain
pnpm consumer:check

The browser smoke suite runs in headless Chrome and starts the sibling playground's 1D and 2D development servers and the production native fixture preview only for the duration of the check. It covers native scrolling, mouse and keyboard workflows, overview interaction, reduced motion, an effective 200% CSS viewport, and the compact layout.

All automated browser tests, including the performance suite, run in headless Google Chrome. Its required matrix includes 3840×2160 navigation with 50 panes and a 3840×2160 overview stress workload with 500 panes, with a 60Hz display-cadence floor and 120Hz CPU-work budget.

See docs/quality-and-supply-chain-tooling.md for the locked quality, architecture, test, dependency, vulnerability, license, and release-age gates.

Continuous integration

.github/workflows/ci.yml typechecks, runs the unit tests and builds the package on Linux and Windows for every push to main and every pull request. Hosted runners have no hardware WebGPU, so browser suites and pnpm consumer:check run on real GPUs before release.

Releasing

Set the new version in package.json, commit, and push an annotated vMAJOR.MINOR.PATCH tag that matches it, including any prerelease suffix such as -beta.1. .github/workflows/release.yml runs in the npm GitHub environment, verifies the tag, typechecks, runs the unit tests, builds, and publishes @riteofstring/onirigiri through npm trusted publishing, which adds provenance while the repository is public. Browser suites need a real GPU and run before tagging, not in that workflow. Prereleases publish under the beta npm dist-tag; stable versions use latest. Publishing a beta does not replace the stable default installation. Install a beta with npm install @riteofstring/onirigiri@beta, or use its exact version to pin it.

npm trusted publishing can only be configured for a package that already exists. Publish the first version by hand (pnpm build, then npm publish --access public), then add the riteofstring/onirigiri repository, release.yml workflow and npm environment as the package's trusted publisher on npmjs.com.